docs/concepts/glue-coding.md

<a id="concept-glue-coding"></a>

# 拼好码

> 复用成熟能力，用胶水代码连接、编排、适配业务流程。

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

<a id="concept-glue-coding-关系定位"></a>
### 关系定位

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

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

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

所以：

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

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

<a id="concept-glue-coding-一句话定义"></a>
### 一句话定义

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

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

<a id="concept-glue-coding-颠覆性宣言"></a>
### 颠覆性宣言

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

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

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

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

<a id="concept-glue-coding-核心理念"></a>
### 核心理念

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

<a id="concept-glue-coding-范式转移"></a>
#### 范式转移

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

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

<a id="concept-glue-coding-架构哲学"></a>
### 架构哲学

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

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

<a id="concept-glue-coding-核心链路"></a>
### 核心链路

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

<a id="concept-glue-coding-为什么有效"></a>
### 为什么有效

<a id="concept-glue-coding-1-幻觉问题从发明转向核验"></a>
#### 1. 幻觉问题：从“发明”转向“核验”

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

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

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

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

<a id="concept-glue-coding-2-复杂性问题转交给成熟生态"></a>
#### 2. 复杂性问题：转交给成熟生态

每个成熟模块背后都有：

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

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

<a id="concept-glue-coding-3-门槛问题从底层实现转向业务编排"></a>
#### 3. 门槛问题：从底层实现转向业务编排

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

你真正要做的是：

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

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

<a id="concept-glue-coding-胶水原则"></a>
### 胶水原则

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

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

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

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

<a id="concept-glue-coding-决策顺序"></a>
### 决策顺序

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

<a id="concept-glue-coding-成熟方案判断标准"></a>
### 成熟方案判断标准

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

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

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

<a id="concept-glue-coding-胶水代码应该做什么"></a>
### 胶水代码应该做什么

自研代码的合理边界：

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

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

<a id="concept-glue-coding-胶水代码不应该做什么"></a>
### 胶水代码不应该做什么

明确禁止：

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

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

<a id="concept-glue-coding-实践流程"></a>
### 实践流程

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

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

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

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

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

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

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

<a id="concept-glue-coding-使用-github-topics-找成熟能力"></a>
#### 使用 GitHub Topics 找成熟能力

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

```text
我需要实现 [你的需求]，请帮我：
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 |

<a id="concept-glue-coding-经典案例"></a>
### 经典案例

<a id="concept-glue-coding-polymarket-数据分析-bot"></a>
#### Polymarket 数据分析 Bot

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

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

拼好码做法：

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

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

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

<a id="concept-glue-coding-常见场景"></a>
### 常见场景

<a id="concept-glue-coding-登录认证"></a>
#### 登录认证

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

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

胶水代码只负责：

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

<a id="concept-glue-coding-ai-客服"></a>
#### AI 客服

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

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

胶水代码只负责：

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

<a id="concept-glue-coding-订单流程"></a>
#### 订单流程

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

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

胶水代码只负责：

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

<a id="concept-glue-coding-偏离协议"></a>
### 偏离协议

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

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

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

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

<a id="concept-glue-coding-胶水原则之禅"></a>
### 胶水原则之禅

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

<a id="concept-glue-coding-与相近概念的区别"></a>
### 与相近概念的区别

<a id="concept-glue-coding-拼好码-vs-胶水编程"></a>
#### 拼好码 vs 胶水编程

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

简化理解：

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

<a id="concept-glue-coding-拼好码-vs-低代码"></a>
#### 拼好码 vs 低代码

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

<a id="concept-glue-coding-拼好码-vs-微服务"></a>
#### 拼好码 vs 微服务

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

<a id="concept-glue-coding-拼好码-vs-自研平台化"></a>
#### 拼好码 vs 自研平台化

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

<a id="concept-glue-coding-ai-时代的拼好码"></a>
### AI 时代的拼好码

AI 特别适合生成：

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

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

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

<a id="concept-glue-coding-内化"></a>
### 内化

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

> “我来实现这个功能。”

变成：

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

从：

> “我能不能写出来？”

变成：

> “我该不该自己写？”

从：

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

变成：

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

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

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

<a id="concept-glue-coding-延伸阅读"></a>
### 延伸阅读

- [语言层要素](language-layers.md) - 看懂代码需要掌握的语言层级
- [胶水开发提示词（在线提示词库入口）](../../prompts/README.md)