docs: reframe glue coding as pinhaoma

This commit is contained in:
tukuaiai
2026-05-01 22:32:58 +08:00
parent 6f963cc4fb
commit a510b32622
4 changed files with 200 additions and 327 deletions
+9 -9
View File
@@ -165,7 +165,7 @@ TODO:仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署
**建议阅读顺序(从抽象到落地)**
1. 🔑 元方法论:用“生成器/优化器”的递归闭环让系统自我进化
2. 🧬 胶水编程:复用成熟轮子,把注意力放在“连接方式”
2. 🧬 拼好码:复用成熟能力,用胶水代码连接、编排、适配业务流程
3. 🔮 哲学方法论工具箱:把抽象方法论落到可验证、可迭代的工程动作
<details>
@@ -191,19 +191,19 @@ TODO:仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署
</details>
<details>
<summary><strong>🧬 胶水编程 (Glue Coding)</strong></summary>
<summary><strong>🧬 拼好码(胶水原则)</strong></summary>
> 一句话:能抄不写,能连不造,能复用不原创
> 一句话:成熟能力解决通用问题,胶水代码连接业务流程,自研只服务真正不可替代的差异
胶水编程是 Vibe Coding 的终极进化形态,目标是把注意力从“造轮子”迁移到“连接方式”,从而缓解三大致命缺陷:
拼好码是 Vibe Coding 的工程交付形态:优先复用官方能力、平台能力、成熟库、稳定工具、开源仓库和事实标准,只写必要的连接、编排、适配、隔离与业务代码。
| 问题 | 解法 |
|:---|:---|
| 🎭 AI 幻觉 | ✅ 只使用已验证的成熟代码,零幻觉 |
| 🧩 复杂性爆炸 | ✅ 每个模块都是久经考验的轮子 |
| 🎓 门槛过高 | ✅ 你只需要描述"连接方式" |
| 🎭 AI 顺手造轮子 | ✅ 先找成熟方案,偏离必须说明 |
| 🧩 复杂性爆炸 | ✅ 通用复杂度交给成熟生态 |
| 🎓 交付不稳定 | ✅ 胶水代码只负责连接、编排、适配和业务规则 |
👉 [深入了解胶水编程](./assets/documents/principles/fundamentals/胶水编程.md)
👉 [深入了解拼好码](./assets/documents/principles/fundamentals/胶水编程.md)
</details>
@@ -329,7 +329,7 @@ TODO:仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署
### 项目内部文档
* [**胶水编程 (Glue Coding)**](./assets/documents/principles/fundamentals/): 软件工程的圣杯与银弹,Vibe Coding 的终极进化形态
* [**拼好码(胶水原则)**](./assets/documents/principles/fundamentals/胶水编程.md): 复用成熟能力,用胶水代码连接、编排、适配业务流程
* [**Chat Vault**](./assets/repos/chat-vault/): AI 聊天记录保存工具,支持 Codex/Kiro/Gemini/Claude CLI。
* [**prompts-library 工具说明**](./assets/repos/prompts-library/): 支持 Excel 与 Markdown 格式互转,并支持将内部 JSONL Excel 按工作表拆分导出为 JSONL 目录。
* [**编程提示词集合**](https://docs.google.com/spreadsheets/d/1Ifk_dLF25ULSxcfGem1hXzJsi7_RBUNAki8SBCuvkJA/edit?gid=1254297203#gid=1254297203): 适用于 Vibe Coding 流程的专用提示词(云端表格)。
+1 -1
View File
@@ -32,7 +32,7 @@ assets/documents/
3. **范式** → [软件开发范式演进](./principles/fundamentals/软件开发范式演进.md)
4. **底层** → [底层程序逻辑设计与工程优化项](./principles/fundamentals/底层程序逻辑设计与工程优化项.md)
5. **思维** → [philosophy](./principles/philosophy/README.md)
6. **理念** → [胶水编程](./principles/fundamentals/胶水编程.md)
6. **理念** → [拼好码(胶水原则)](./principles/fundamentals/胶水编程.md)
7. **入门** → [Vibe Coding 哲学原理](./guides/getting-started/Vibe%20Coding%20哲学原理.md)
8. **环境** → [开发环境搭建](./guides/getting-started/开发环境搭建.md)
9. **默认 CLI** → [Codex CLI 配置](./guides/getting-started/Codex-CLI配置.md)
@@ -4,8 +4,8 @@
## 📖 核心方法论
### 胶水编程 (Glue Coding)
- [胶水编程](./胶水编程.md) - 软件工程的圣杯与银弹
### 拼好码(胶水原则)
- [拼好码](./胶水编程.md) - 复用成熟能力,用胶水代码连接、编排、适配业务流程
- [语言层要素](./语言层要素.md) - 看懂 100% 代码的 8 个层级
### 理论基础
@@ -1,361 +1,234 @@
# 🧬 胶水编程 (Glue Coding)
# 拼好码(胶水原则)
> **软件工程的圣杯与银弹——终于出现了。**
> 成熟能力解决通用问题,胶水代码连接业务流程,自研只服务真正不可替代的差异。
---
## 一句话定义
## 🚀 颠覆性宣言
**拼好码**是一种以“胶水原则”为核心的工程方法:优先复用成熟方案,只写必要的连接、编排、适配、隔离与业务代码,用最低成本交付稳定、可替换、可回滚的业务系统。
**胶水编程不是一种技术,而是一场革命。**
它不是“少写代码”的偷懒方法,而是把工程资源集中到业务价值上:通用复杂度交给成熟生态,业务差异由薄胶水表达。
它可能完美解决了 Vibe Coding 的三大致命缺陷:
## 核心链路
| 传统 Vibe Coding 的痛点 | 胶水编程的解法 |
|:---|:---|
| 🎭 **AI 幻觉** - 生成不存在的 API、错误的逻辑 | ✅ **零幻觉** - 只使用已验证的成熟代码 |
| 🧩 **复杂性爆炸** - 项目越大越失控 | ✅ **复杂性归零** - 每个模块都是久经考验的轮子 |
| 🎓 **门槛过高** - 需要深厚编程功底才能驾驭 AI | ✅ **门槛消失** - 你只需要描述"连接方式" |
---
## 💡 核心理念
```
传统编程:人写代码
Vibe CodingAI 写代码,人审代码
胶水编程:AI 连接代码,人审连接
```text
UserInput(拼好码)
-> 成熟能力
-> 可复用方案
-> 适配边界
-> 胶水代码
-> 能力编排
-> 业务逻辑
-> 可运行业务流程
-> 可替换业务系统
-> 低成本高稳定工程交付
```
### 范式转移
## 胶水原则
**从「生成」到「连接」的根本性转变:**
“胶水原则”是最高级别的“不重复造轮子”:能复用成熟方案就不自研底层能力,只写用于连接、编排、适配、隔离和表达业务逻辑的胶水代码。
- ❌ 不再让 AI 从零生成代码(幻觉的根源)
- ❌ 不再重复造轮子(复杂性的根源)
- ❌ 不再要求你理解每一行代码(门槛的根源)
默认答案不是“我来实现”,而是:
- ✅ 只复用成熟的、经过生产验证的开源项目
- ✅ AI 的唯一职责:理解你的意图,将模块连接起来
- ✅ 你的唯一职责:描述清楚「输入是什么,输出要什么」
> 有没有官方能力、平台能力、事实标准、主流框架、成熟库、稳定工具、GitHub 开源仓库或内部公共能力可以直接复用?
---
当成熟方案能以可接受的成本、风险和复杂度可靠满足需求时,它就是默认答案;自研不是默认选项,而是需要证明合理性的例外选项。
## 🏗️ 架构哲学
## 决策顺序
```
┌─────────────────────────────────────────────────────────┐
│ 你的业务需求 │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ AI 胶水层 (Glue Layer) │
│ │
│ "我理解你要做什么,让我把这些积木连起来" │
│ │
└─────────────────────────────────────────────────────────┘
┌────────────────┼────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 成熟模块 A │ │ 成熟模块 B │ │ 成熟模块 C │
│ (10万+ ⭐) │ │ (生产验证) │ │ (官方 SDK) │
└─────────────┘ └─────────────┘ └─────────────┘
```
1. 优先寻找官方能力、平台能力、事实标准方案或已有内部公共能力。
2. 优先采用成熟开源库、稳定框架、长期维护工具、主流生态方案或托管服务。
3. 优先通过配置、插件、扩展点、适配层或编排层满足需求。
4. 仅在业务差异、集成边界、编排流程、适配层或领域规则需要时编写自研代码。
5. 只有当成熟方案无法满足关键约束,或其成本、风险、复杂度不可接受时,才允许自研核心能力。
**实体 (Entity)**:成熟的开源项目、官方 SDK、久经考验的库
**连接 (Link)**:AI 生成的胶水代码,负责数据流转和接口适配
**功能 (Function)**:你描述的业务目标
## 成熟方案判断标准
---
判断一个方案是否成熟,不能只看是否流行,还要看:
## 🎯 为什么这是银弹?
- 是否由官方、主流社区、头部厂商或长期稳定组织维护。
- 是否有清晰文档、版本记录、测试覆盖、安全更新和活跃维护。
- 是否被真实生产环境广泛使用。
- 是否与当前技术栈、团队能力、部署环境和合规要求兼容。
- 是否具备可观测、可测试、可回滚、可替换和边界隔离能力。
### 1. 幻觉问题 → 彻底消失
成熟方案不等于盲目依赖。没有边界、不可替换、不可回滚的复用,会从效率优势变成锁定风险。
AI 不再需要"发明"任何东西。它只需要:
- 阅读模块 A 的文档
- 阅读模块 B 的文档
- 写出 A → B 的数据转换
## 胶水代码应该做什么
**这是 AI 最擅长的事情,也是最不容易出错的事情。**
自研代码的合理边界:
### 2. 复杂性问题 → 转嫁给社区
- 连接不同系统。
- 封装业务流程。
- 适配输入输出。
- 组合已有能力。
- 隔离第三方依赖。
- 表达项目特有业务规则。
- 实现成熟方案确实无法覆盖的差异化核心能力。
每个模块背后都有:
- 数千个 Issue 的讨论
- 数百个贡献者的智慧
- 数年的生产环境打磨
优秀的胶水代码应该短、薄、清晰、可测试、可删除。它越像业务编排层,而不是底层框架,越符合拼好码。
**你不是在管理复杂性,你是在站在巨人的肩膀上。**
## 胶水代码不应该做什么
### 3. 门槛问题 → 降到最低
明确禁止:
你不需要懂:
- 底层实现原理
- 最佳实践细节
- 边界情况处理
- 重复实现已有成熟框架。
- 重复实现通用基础设施。
- 无理由重写稳定库。
- 为了控制感、安全感或技术偏好制造私有轮子。
- 在未调研成熟方案前直接进入自研实现。
- 让第三方 SDK、外部 API 或平台私有模型污染核心业务模型。
你只需要会说人话:
> "我要把 Telegram 的消息,经过 GPT 处理,存到 PostgreSQL"
拼好码反对的是工程中的控制幻觉:开发者常把“自己写”误认为更可控、更安全、更优雅,但真实世界里,自研通常意味着更高缺陷率、更高维护成本、更弱生态支持和更差长期稳定性。
**AI 会帮你找到最合适的轮子,然后把它们粘起来。**
## 偏离协议
---
拼好码不是绝对禁止自研,而是要求自研必须有充分理由。
## 📋 实践流程
如需偏离胶水原则,必须说明:
```
1. 明确目标
└─→ "我要实现 XXX 功能"
- 偏离原因。
- 已评估的成熟方案。
- 为什么成熟方案不能满足关键约束。
- 自研范围和边界。
- 维护成本。
- 安全风险。
- 供应商锁定或私有实现锁定风险。
- 测试策略。
- 替换、删除或回滚路径。
2. 寻找轮子
└─→ "有没有成熟的库/项目已经做过类似的事?"
└─→ 让 AI 帮你搜索、评估、推荐
未完成偏离说明前,不得默认进入自研核心能力实现路径。
3. 理解接口
└─→ 把官方文档喂给 AI
└─→ AI 总结:输入是什么,输出是什么
## 胶水原则之禅
4. 描述连接
└─→ "A 的输出要变成 B 的输入"
└─→ AI 生成胶水代码
- 成熟方案优于自研实现。
- 官方能力优于私有轮子。
- 事实标准优于个人偏好。
- 复用优于重写。
- 编排优于重造。
- 适配优于侵入。
- 连接优于耦合。
- 资源整合优于单打独斗。
- 薄胶水优于厚平台。
- 业务逻辑优于基础设施。
- 平台能力优于底层代码。
- 稳定生态优于新奇技术。
- 长期维护优于短期快感。
- 可替换优于强绑定。
- 可回滚优于不可逆。
- 可验证优于想当然。
- 少写代码优于多造代码。
- 必要自研优于盲目复用。
- 明确边界优于隐式依赖。
- 充分理由优于控制幻觉。
- 偏离必须说明。
- 自研必须克制。
- 能复用时,不要重造。
- 能编排时,不要发明。
- 能适配时,不要入侵。
- 如果成熟方案能可靠满足需求,它就应该是默认答案。
5. 验证运行
└─→ 跑通 → 完成
└─→ 报错 → 把错误扔给 AI,继续粘
```
## 常见场景
---
### 登录认证
## 🔥 经典案例
错误路径:自己设计密码加密、Token 签发、OAuth 流程、验证码和权限基础设施。
### 案例:Polymarket 数据分析 Bot
拼好码路径:优先评估云厂商认证服务、Auth0、Firebase Auth、Keycloak、企业统一身份系统或框架内置认证模块。
**需求**:实时获取 Polymarket 数据,分析后推送到 Telegram
胶水代码只负责:
**传统做法**:从零写爬虫、写分析逻辑、写 Bot → 3000 行代码,2 周时间
- 把认证结果接入业务用户体系。
- 把外部用户 ID 映射到内部用户模型。
- 处理业务角色和权限。
- 封装登录后的业务流程。
**胶水做法**
```
轮子 1: polymarket-py (官方 SDK)
轮子 2: pandas (数据分析)
轮子 3: python-telegram-bot (消息推送)
### AI 客服
胶水代码: 50 行
开发时间: 2 小时
```
错误路径:从零训练模型、写向量数据库、写知识库检索、写对话管理、写监控系统。
---
拼好码路径:优先使用成熟大模型 API、向量数据库、RAG 框架、客服平台和日志监控工具。
## 📚 延伸阅读
胶水代码只负责:
- [语言层要素](./语言层要素.md) - 看懂 100% 代码必须掌握的 12 层要素
- 业务知识整理。
- 问题分类。
- 工作流编排。
- 人工转接规则。
- 企业系统接口适配。
- 回答质量评估。
### 订单流程
错误路径:自己写完整调度系统、消息队列、重试机制、状态机、通知系统。
拼好码路径:优先使用成熟消息队列、任务调度平台、工作流引擎、云函数、监控告警服务。
胶水代码只负责:
- 订单创建后触发库存检查。
- 支付成功后触发发货。
- 发货后触发通知。
- 异常时进入人工处理。
- 在不同系统之间做数据适配。
## 与相近概念的区别
### 拼好码 vs 低代码
低代码强调用平台快速搭建应用;拼好码强调工程决策中优先复用成熟能力。低代码可以是拼好码的一种工具,但拼好码不等于低代码。
### 拼好码 vs 微服务
微服务是一种系统拆分架构;拼好码是一种复用优先的工程哲学。微服务如果盲目自研基础设施,反而违背拼好码。
### 拼好码 vs 自研平台化
平台化追求沉淀公共能力;拼好码警惕“厚平台”。只有公共能力确实稳定、复用频繁、边界清晰时,平台化才有价值。
## AI 时代的拼好码
AI 特别适合生成:
- 接口适配代码。
- 数据转换代码。
- 工作流编排代码。
- 测试用例。
- SDK 调用示例。
- 配置模板。
- 迁移脚本。
但 AI 也容易顺手造轮子,所以更好的模式是让 AI 在胶水原则约束下工作:
1. 先查成熟方案。
2. 再评估成熟度、许可证、维护状态和替代方案。
3. 再生成适配层和编排层。
4. 再补业务逻辑和测试。
5. 最后输出偏离说明与回滚路径。
## 内化
学会拼好码后,工程习惯应该从:
> “我来实现这个功能。”
变成:
> “这个功能已有成熟能力吗?我该如何接入、编排、隔离和验证?”
从:
> “我能不能写出来?”
变成:
> “我该不该自己写?”
最终,拼好码要内化成一句工程本能:
> 成熟能力解决通用问题,胶水代码连接业务流程,自研只服务于真正不可替代的差异。
## 延伸阅读
- [语言层要素](./语言层要素.md) - 看懂代码需要掌握的语言层级
- [胶水开发提示词(在线提示词库入口)](../../../prompt/README.md)
- [项目实战:polymarket-dev](../../case-studies/polymarket-dev/)
---
## 🎖️ 总结
> **能抄不写,能连不造,能复用不原创。**
胶水编程是 Vibe Coding 的终极进化形态。
它不是偷懒,而是**工程智慧的最高体现**——
用最少的原创代码,撬动最大的生产力。
**这就是软件工程等待了 50 年的银弹。**
---
*"The best code is no code at all. The second best is glue code."*
# 胶水编程(glue coding)方法论
## **1. 胶水编程的定义**
**胶水编程(glue coding)**是一种新型的软件构建方式,其核心理念是:
> **几乎完全复用成熟开源组件,通过最小量的“胶水代码”将它们组合成完整系统**
它强调的是“连接”而不是“创造”,在 AI 时代尤其高效
## **2. 产生背景**
传统软件工程往往需要开发者:
* 设计架构
* 自己编写逻辑
* 手动处理各种细节
* 重复造轮子
这导致开发成本高、周期长、成功率低
而当下的生态已经发生根本变化:
* GitHub 上成熟的开源库成千上万
* 框架覆盖各种场景(Web、AI、分布式、模型推理…)
* GPT / Grok 能帮助搜索、分析、组合这些项目
在这种环境中,再从零写代码已经不是最高效的方式
于是,“胶水编程”成为一种新范式
## **3. 胶水编程的核心原则**
### **3.1 凡是能不写的就不写,凡是能少写的就少写**
任何已有成熟实现的功能,都不应该重新造轮子
### **3.2 凡是能 CV 就 CV**
直接复制使用经过社区检验的代码,属于正常工程流程,而非偷懒
### **3.3 站在巨人的肩膀上,而不是试图成为巨人**
利用现成框架,而不是试图自己再写一个“更好的轮子”
### **3.4 不修改原仓库代码**
所有开源库应尽量保持不可变,作为黑盒使用
### **3.5 自定义代码越少越好**
你写的代码只承担:
* 组合
* 调用
* 封装
* 适配
也就是所谓的**胶水层**
## **4. 胶水编程的标准流程**
### **4.1 明确需求**
把系统要实现的功能拆成一个个需求点
### **4.2 使用 GPT/Grok 拆解需求**
让 AI 将需求细化为可复用模块、能力点和对应的子任务
### **4.3 搜索现成的开源实现**
利用 GPT 的联网能力(如 Grok):
* 根据每个子需求搜索对应的 GitHub 仓库
* 检查是否存在可复用组件
* 对比质量、实现方式、许可证等
#### 🔍 使用 GitHub Topics 精准找轮子
**方法**:让 AI 帮你找到需求对应的 GitHub Topic,然后浏览该主题下的热门仓库
**示例提示词**
```
我需要实现 [你的需求],请帮我:
1. 分析这个需求可能涉及哪些技术领域
2. 推荐对应的 GitHub Topics 关键词
3. 给出 GitHub Topics 链接(格式:https://github.com/topics/xxx
```
**常用 Topics 示例**
| 需求 | 推荐 Topic |
|:---|:---|
| Telegram Bot | [telegram-bot](https://github.com/topics/telegram-bot) |
| 数据分析 | [data-analysis](https://github.com/topics/data-analysis) |
| AI Agent | [ai-agent](https://github.com/topics/ai-agent) |
| CLI 工具 | [cli](https://github.com/topics/cli) |
| Web 爬虫 | [web-scraping](https://github.com/topics/web-scraping) |
**进阶技巧**
- [GitHub Topics 首页](https://github.com/topics) - 浏览所有主题
- [GitHub Trending](https://github.com/trending) - 发现热门新项目
- 组合多个 Topic 筛选:`https://github.com/topics/python?q=telegram`
### **4.4 下载并整理仓库**
将选定的仓库拉取到本地,分类整理
### **4.5 按架构体系进行组织**
把这些仓库放置到项目结构中,例如:
```
/services
/libs
/third_party
/glue
```
并强调:**开源仓库作为第三方依赖,绝对不可修改。**
### **4.6 编写胶水层代码**
胶水代码的作用包括:
* 封装接口
* 统一输入输出
* 连接不同组件
* 实现最小业务逻辑
最终系统通过多个成熟模块组合而成
## **5. 胶水编程的价值**
### **5.1 极高的成功率**
因为使用的是社区验证过的成熟代码
### **5.2 开发速度极快**
大量功能可以直接复用
### **5.3 降低成本**
时间成本、维护成本、学习成本都大幅减少
### **5.4 系统更稳定**
依赖成熟框架而非个人实现
### **5.5 易于扩展**
通过替换组件就能轻松升级能力
### **5.6 与 AI 强配**
GPT 能辅助搜索、拆解、整合,是胶水工程的天然增强器
## **6. 胶水编程 vs 传统开发**
| 项目 | 传统开发 | 胶水编程 |
| ------ | ----- | ------ |
| 功能实现方式 | 自己写 | 复用开源 |
| 工作量 | 大 | 小得多 |
| 成功率 | 不确定 | 高 |
| 速度 | 慢 | 极快 |
| 错误率 | 容易踩坑 | 使用成熟方案 |
| 重点 | “造轮子” | “组合轮子” |
## **7. 胶水编程的典型应用场景**
* 快速原型开发
* 小团队构建大系统
* AI 应用/模型推理平台
* 数据处理流水线
* 内部工具开发
* 系统集成(System Integration
## **8. 未来:胶水工程将成为新的主流编程方式**
随着 AI 能力不断增强,未来的开发者不再需要自己写大量代码,而是:
* 找轮子
* 组合轮子
* 智能连接组件
* 以极低成本构建复杂系统
胶水编程将会成为新的软件生产力标准