002-拼好码

复用成熟能力，用胶水代码连接、编排、适配业务流程。
成熟能力解决通用问题，胶水代码连接业务流程，自研只服务真正不可替代的差异。

关系定位

拼好码不是替代胶水编程，而是胶水编程的超集。

胶水编程关注的是“如何用最少胶水代码把成熟模块连接起来”；拼好码在此基础上继续向前、向后扩展：

• 向前：从用户意图出发，先判断需求能否被成熟能力覆盖。
• 中间：选择成熟方案，设计适配边界，用胶水代码完成连接与编排。
• 向后：把业务流程做成可运行、可验证、可替换、可回滚的系统。

所以：

拼好码 = 需求语言化
       + 成熟能力发现
       + 复用方案评估
       + 适配边界设计
       + 胶水编程
       + 能力编排
       + 业务逻辑表达
       + 工程门禁
       + 可替换/可回滚治理

胶水编程是拼好码中的“连接实现层”，不是拼好码的全部。

一句话定义

拼好码是一种以“胶水原则”为核心的工程方法：优先复用成熟方案，只写必要的连接、编排、适配、隔离与业务代码，用最低成本交付稳定、可替换、可回滚的业务系统。

它不是“少写代码”的偷懒方法，而是把工程资源集中到业务价值上：通用复杂度交给成熟生态，业务差异由薄胶水表达。

颠覆性宣言

拼好码不是一种单点技术，而是一套工程判断方法。

它继承胶水编程的“连接优先”，但不止于写胶水代码；它要求开发者从“实现者心态”转向“整合者心态”：

不是看到需求就写代码，而是先识别已有能力、评估成熟度、设计边界，再用最少自研完成业务闭环。

传统 Vibe Coding 的痛点	胶水编程的解法	拼好码的扩展
AI 幻觉：生成不存在的 API、错误逻辑	只连接已验证模块，减少发明空间	先查成熟方案，再用门禁校验依赖、路径、接口与运行结果
复杂性爆炸：项目越大越失控	每个模块复用成熟轮子	通用复杂度交给成熟生态，业务复杂度留在清晰边界内
门槛过高：需要深厚编程功底	用户描述连接方式，AI 生成胶水	用户定义目标和验收，AI 搜索、评估、适配、编排，机器门禁强制验证
自研冲动：控制感压过工程收益	少写底层代码	偏离复用路径必须说明成本、风险、测试和回滚路径

核心理念

传统编程：人写代码
Vibe Coding：AI 写代码，人审代码
胶水编程：AI 连接代码，人审连接
拼好码：AI 搜索/评估/连接/编排能力，人审目标/边界/门禁/取舍

范式转移

从“生成”转向“连接”，再从“连接”升级为“能力编排”：

• 不再默认让 AI 从零生成底层能力。
• 不再重复造轮子。
• 不再把“自己写”当作更可控。
• 优先复用成熟的、经过生产验证的官方能力、平台能力、开源项目和事实标准。
• AI 的职责是理解意图、查找能力、评估方案、生成适配层、编排流程。
• 人的职责是说清目标、设定边界、审查取舍、设计门禁。
• 机器门禁负责把自然语言验收标准变成测试、CI、schema、类型、脚本和检查清单。

架构哲学

┌─────────────────────────────────────────────────────────┐
│                     用户意图 / 业务需求                  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                     拼好码决策层                         │
│  需求语言化 -> 成熟能力搜索 -> 方案评估 -> 边界设计       │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                 AI 胶水层 / 能力编排层                   │
│      适配输入输出，连接系统，编排流程，隔离依赖           │
└─────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
   │  官方能力 A  │  │  成熟库 B    │  │  平台服务 C  │
   │  官方维护    │  │  生产验证    │  │  可观测可替换 │
   └─────────────┘  └─────────────┘  └─────────────┘
          │                │                │
          └────────────────┼────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────┐
│              可运行 / 可测试 / 可回滚的业务系统          │
└─────────────────────────────────────────────────────────┘

• 实体：成熟的开源项目、官方 SDK、平台能力、托管服务、内部公共能力。
• 连接：AI 生成或辅助生成的胶水代码，负责数据流转、接口适配和流程编排。
• 边界：隔离第三方模型、SDK、API 与核心业务模型。
• 门禁：测试、类型、schema、lint、CI、脚本和审查清单。
• 目标：可运行业务流程和可替换业务系统。

核心链路

UserInput(拼好码)
  -> 成熟能力
  -> 可复用方案
  -> 适配边界
  -> 胶水代码
  -> 能力编排
  -> 业务逻辑
  -> 可运行业务流程
  -> 可替换业务系统
  -> 低成本高稳定工程交付

为什么有效

1. 幻觉问题：从“发明”转向“核验”

AI 最容易出错的地方，是凭空发明不存在的 API、参数、路径和业务规则。

拼好码降低幻觉的方式不是“相信 AI 更聪明”，而是改变任务形态：

• 先找真实存在的成熟能力。
• 再读取官方文档、README、示例和类型定义。
• 再生成适配层。
• 最后用测试、运行结果和 CI 校验。

AI 不再主要负责发明底层能力，而是负责理解、连接、转换和验证。

2. 复杂性问题：转交给成熟生态

每个成熟模块背后都有：

• 大量真实用户场景。
• Issue 和 PR 中沉淀的边界案例。
• 长期维护者的升级与安全修复。
• 生产环境反复验证后的稳定性。

你不是在逃避复杂性，而是在复用生态已经支付过的试错成本、测试成本、维护成本和生产验证成本。

3. 门槛问题：从底层实现转向业务编排

你不需要把认证、支付、调度、日志、存储、解析、渲染、监控全部自己实现一遍。

你真正要做的是：

说清业务目标，选择成熟能力，设计边界，把它们编排成业务流程。

这要求的不是低水平，而是更高水平的工程判断。

胶水原则

“胶水原则”是最高级别的“不重复造轮子”：能复用成熟方案就不自研底层能力，只写用于连接、编排、适配、隔离和表达业务逻辑的胶水代码。

默认答案不是“我来实现”，而是：

有没有官方能力、平台能力、事实标准、主流框架、成熟库、稳定工具、GitHub 开源仓库或内部公共能力可以直接复用？

当成熟方案能以可接受的成本、风险和复杂度可靠满足需求时，它就是默认答案；自研不是默认选项，而是需要证明合理性的例外选项。

决策顺序

1. 优先寻找官方能力、平台能力、事实标准方案或已有内部公共能力。
2. 优先采用成熟开源库、稳定框架、长期维护工具、主流生态方案或托管服务。
3. 优先通过配置、插件、扩展点、适配层或编排层满足需求。
4. 仅在业务差异、集成边界、编排流程、适配层或领域规则需要时编写自研代码。
5. 只有当成熟方案无法满足关键约束，或其成本、风险、复杂度不可接受时，才允许自研核心能力。

成熟方案判断标准

判断一个方案是否成熟，不能只看是否流行，还要看：

• 是否由官方、主流社区、头部厂商或长期稳定组织维护。
• 是否有清晰文档、版本记录、测试覆盖、安全更新和活跃维护。
• 是否被真实生产环境广泛使用。
• 是否与当前技术栈、团队能力、部署环境和合规要求兼容。
• 是否具备可观测、可测试、可回滚、可替换和边界隔离能力。

成熟方案不等于盲目依赖。没有边界、不可替换、不可回滚的复用，会从效率优势变成锁定风险。

胶水代码应该做什么

自研代码的合理边界：

• 连接不同系统。
• 封装业务流程。
• 适配输入输出。
• 组合已有能力。
• 隔离第三方依赖。
• 表达项目特有业务规则。
• 实现成熟方案确实无法覆盖的差异化核心能力。

优秀的胶水代码应该短、薄、清晰、可测试、可删除。它越像业务编排层，而不是底层框架，越符合拼好码。

胶水代码不应该做什么

明确禁止：

• 重复实现已有成熟框架。
• 重复实现通用基础设施。
• 无理由重写稳定库。
• 为了控制感、安全感或技术偏好制造私有轮子。
• 在未调研成熟方案前直接进入自研实现。
• 让第三方 SDK、外部 API 或平台私有模型污染核心业务模型。

拼好码反对的是工程中的控制幻觉：开发者常把“自己写”误认为更可控、更安全、更优雅，但真实世界里，自研通常意味着更高缺陷率、更高维护成本、更弱生态支持和更差长期稳定性。

实践流程

1. 明确目标
   -> 我要实现什么业务结果？
   -> 输入是什么？输出是什么？验收标准是什么？

2. 寻找成熟能力
   -> 有没有官方能力、平台能力、内部公共能力？
   -> 有没有事实标准、成熟框架、开源库、托管服务？

3. 评估可复用方案
   -> 维护状态、许可证、安全风险、生产案例、团队熟悉度如何？
   -> 是否可观测、可测试、可替换、可回滚？

4. 设计适配边界
   -> 外部 SDK/API 如何隔离？
   -> 核心业务模型如何保持干净？
   -> 失败、限流、重试、回滚怎么处理？

5. 编写胶水代码
   -> A 的输出如何变成 B 的输入？
   -> 如何封装流程、转换数据、组合能力？

6. 设计工程门禁
   -> 测试、类型、schema、lint、CI、脚本、检查清单如何覆盖验收标准？

7. 形成可替换系统
   -> 如果第三方方案失效，替换路径是什么？
   -> 如果本次选择失败，如何回滚？

使用 GitHub Topics 找成熟能力

让 AI 帮你把需求转换成可搜索的生态关键词：

我需要实现 [你的需求]，请帮我：
1. 分析这个需求涉及哪些成熟能力领域
2. 推荐对应的 GitHub Topics、官方能力、平台能力和主流开源项目
3. 对每个候选方案评估成熟度、维护状态、许可证、替换风险和接入成本
4. 最后给出优先采用方案和偏离说明

示例：

需求	优先搜索方向
Telegram Bot	官方 Bot API、telegram-bot topic、成熟 bot SDK
数据分析	pandas、polars、duckdb、data-analysis topic
AI Agent	官方 SDK、主流 agent 框架、workflow/orchestration 工具
CLI 工具	cli framework、argparse/click/typer、shell completion
Web 爬虫	官方 API 优先，其次 web-scraping、playwright、scrapy

经典案例

Polymarket 数据分析 Bot

需求：实时获取 Polymarket 数据，分析后推送到 Telegram。

传统做法：从零写爬虫、数据清洗、分析逻辑、Bot 推送、错误处理和调度。

拼好码做法：

成熟能力 1：Polymarket 官方/主流 SDK
成熟能力 2：pandas / polars / duckdb 做数据分析
成熟能力 3：python-telegram-bot 做消息推送
成熟能力 4：cron / workflow / queue 做调度

胶水代码：
  -> 拉取市场数据
  -> 转成统一内部数据结构
  -> 调用分析函数
  -> 生成消息
  -> 推送 Telegram
  -> 记录日志与失败重试

关键不是“自己造一个 Polymarket SDK”，而是把成熟能力拼成可运行、可替换、可观测的业务流程。

常见场景

登录认证

错误路径：自己设计密码加密、Token 签发、OAuth 流程、验证码和权限基础设施。

拼好码路径：优先评估云厂商认证服务、Auth0、Firebase Auth、Keycloak、企业统一身份系统或框架内置认证模块。

胶水代码只负责：

• 把认证结果接入业务用户体系。
• 把外部用户 ID 映射到内部用户模型。
• 处理业务角色和权限。
• 封装登录后的业务流程。

AI 客服

错误路径：从零训练模型、写向量数据库、写知识库检索、写对话管理、写监控系统。

拼好码路径：优先使用成熟大模型 API、向量数据库、RAG 框架、客服平台和日志监控工具。

胶水代码只负责：

• 业务知识整理。
• 问题分类。
• 工作流编排。
• 人工转接规则。
• 企业系统接口适配。
• 回答质量评估。

订单流程

错误路径：自己写完整调度系统、消息队列、重试机制、状态机、通知系统。

拼好码路径：优先使用成熟消息队列、任务调度平台、工作流引擎、云函数、监控告警服务。

胶水代码只负责：

• 订单创建后触发库存检查。
• 支付成功后触发发货。
• 发货后触发通知。
• 异常时进入人工处理。
• 在不同系统之间做数据适配。

偏离协议

拼好码不是绝对禁止自研，而是要求自研必须有充分理由。

如需偏离胶水原则，必须说明：

• 偏离原因。
• 已评估的成熟方案。
• 为什么成熟方案不能满足关键约束。
• 自研范围和边界。
• 维护成本。
• 安全风险。
• 供应商锁定或私有实现锁定风险。
• 测试策略。
• 替换、删除或回滚路径。

未完成偏离说明前，不得默认进入自研核心能力实现路径。

胶水原则

• 成熟方案优于自研实现。
• 官方能力优于私有轮子。
• 事实标准优于个人偏好。
• 复用优于重写。
• 编排优于重造。
• 适配优于侵入。
• 连接优于耦合。
• 资源整合优于单打独斗。
• 薄胶水优于厚平台。
• 业务逻辑优于基础设施。
• 平台能力优于底层代码。
• 稳定生态优于新奇技术。
• 长期维护优于短期快感。
• 可替换优于强绑定。
• 可回滚优于不可逆。
• 可验证优于想当然。
• 少写代码优于多造代码。
• 必要自研优于盲目复用。
• 明确边界优于隐式依赖。
• 充分理由优于控制幻觉。
• 偏离必须说明。
• 自研必须克制。
• 能复用时，不要重造。
• 能编排时，不要发明。
• 能适配时，不要入侵。
• 如果成熟方案能可靠满足需求，它就应该是默认答案。

与相近概念的区别

拼好码 vs 胶水编程

胶水编程强调“用最少胶水代码连接成熟组件”。拼好码包含胶水编程，但还包含成熟能力发现、方案评估、边界隔离、门禁设计、替换路径和偏离协议。

简化理解：

胶水编程：把轮子粘起来
拼好码：先判断该用哪些轮子，再设计边界、粘起来、验证它、让它可替换

拼好码 vs 低代码

低代码强调用平台快速搭建应用；拼好码强调工程决策中优先复用成熟能力。低代码可以是拼好码的一种工具，但拼好码不等于低代码。

拼好码 vs 微服务

微服务是一种系统拆分架构；拼好码是一种复用优先的工程哲学。微服务如果盲目自研基础设施，反而违背拼好码。

拼好码 vs 自研平台化

平台化追求沉淀公共能力；拼好码警惕“厚平台”。只有公共能力确实稳定、复用频繁、边界清晰时，平台化才有价值。

AI 时代的拼好码

AI 特别适合生成：

• 接口适配代码。
• 数据转换代码。
• 工作流编排代码。
• 测试用例。
• SDK 调用示例。
• 配置模板。
• 迁移脚本。
• 偏离说明。

但 AI 也容易顺手造轮子，所以更好的模式是让 AI 在胶水原则约束下工作：

1. 先查成熟方案。
2. 再评估成熟度、许可证、维护状态和替代方案。
3. 再生成适配层和编排层。
4. 再补业务逻辑和测试。
5. 最后输出偏离说明与回滚路径。

内化

学会拼好码后，工程习惯应该从：

“我来实现这个功能。”

变成：

“这个功能已有成熟能力吗？我该如何接入、编排、隔离和验证？”

从：

“我能不能写出来？”

变成：

“我该不该自己写？”

从：

“这个系统要写多少代码？”

变成：

“这个系统能复用多少成熟能力，剩下的胶水边界是否清晰？”

最终，拼好码要内化成一句工程本能：

成熟能力解决通用问题，胶水代码连接业务流程，自研只服务于真正不可替代的差异。