diff --git a/README.md b/README.md index 60c8c31..6ec4c0a 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署 **建议阅读顺序（从抽象到落地）** 1. 🔑 元方法论：用“生成器/优化器”的递归闭环让系统自我进化 -2. 🧬 胶水编程：复用成熟轮子，把注意力放在“连接方式” +2. 🧬 拼好码：复用成熟能力，用胶水代码连接、编排、适配业务流程 3. 🔮 哲学方法论工具箱：把抽象方法论落到可验证、可迭代的工程动作
@@ -191,19 +191,19 @@ TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署
-🧬 胶水编程 (Glue Coding) +🧬 拼好码（胶水原则） -> 一句话：能抄不写，能连不造，能复用不原创。 +> 一句话：成熟能力解决通用问题，胶水代码连接业务流程，自研只服务真正不可替代的差异。 -胶水编程是 Vibe Coding 的终极进化形态，目标是把注意力从“造轮子”迁移到“连接方式”，从而缓解三大致命缺陷： +拼好码是 Vibe Coding 的工程交付形态：优先复用官方能力、平台能力、成熟库、稳定工具、开源仓库和事实标准，只写必要的连接、编排、适配、隔离与业务代码。 | 问题 | 解法 | |:---|:---| -| 🎭 AI 幻觉 | ✅ 只使用已验证的成熟代码，零幻觉 | -| 🧩 复杂性爆炸 | ✅ 每个模块都是久经考验的轮子 | -| 🎓 门槛过高 | ✅ 你只需要描述"连接方式" | +| 🎭 AI 顺手造轮子 | ✅ 先找成熟方案，偏离必须说明 | +| 🧩 复杂性爆炸 | ✅ 通用复杂度交给成熟生态 | +| 🎓 交付不稳定 | ✅ 胶水代码只负责连接、编排、适配和业务规则 | -👉 [深入了解胶水编程](./assets/documents/principles/fundamentals/胶水编程.md) +👉 [深入了解拼好码](./assets/documents/principles/fundamentals/胶水编程.md)
@@ -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 流程的专用提示词（云端表格）。 diff --git a/assets/documents/README.md b/assets/documents/README.md index e76b63f..7271953 100644 --- a/assets/documents/README.md +++ b/assets/documents/README.md @@ -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) diff --git a/assets/documents/principles/fundamentals/README.md b/assets/documents/principles/fundamentals/README.md index cfbc225..8435db7 100644 --- a/assets/documents/principles/fundamentals/README.md +++ b/assets/documents/principles/fundamentals/README.md @@ -4,8 +4,8 @@ ## 📖 核心方法论 -### 胶水编程 (Glue Coding) -- [胶水编程](./胶水编程.md) - 软件工程的圣杯与银弹 +### 拼好码（胶水原则） +- [拼好码](./胶水编程.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程 - [语言层要素](./语言层要素.md) - 看懂 100% 代码的 8 个层级 ### 理论基础 diff --git a/assets/documents/principles/fundamentals/胶水编程.md b/assets/documents/principles/fundamentals/胶水编程.md index 8204943..a1086ae 100644 --- a/assets/documents/principles/fundamentals/胶水编程.md +++ b/assets/documents/principles/fundamentals/胶水编程.md @@ -1,361 +1,234 @@ -# 🧬 胶水编程 (Glue Coding) +# 拼好码（胶水原则） -> **软件工程的圣杯与银弹——终于出现了。** +> 成熟能力解决通用问题，胶水代码连接业务流程，自研只服务真正不可替代的差异。 ---- +## 一句话定义 -## 🚀 颠覆性宣言 +**拼好码**是一种以“胶水原则”为核心的工程方法：优先复用成熟方案，只写必要的连接、编排、适配、隔离与业务代码，用最低成本交付稳定、可替换、可回滚的业务系统。 -**胶水编程不是一种技术，而是一场革命。** +它不是“少写代码”的偷懒方法，而是把工程资源集中到业务价值上：通用复杂度交给成熟生态，业务差异由薄胶水表达。 -它可能完美解决了 Vibe Coding 的三大致命缺陷： +## 核心链路 -| 传统 Vibe Coding 的痛点 | 胶水编程的解法 | -|:---|:---| -| 🎭 **AI 幻觉** - 生成不存在的 API、错误的逻辑 | ✅ **零幻觉** - 只使用已验证的成熟代码 | -| 🧩 **复杂性爆炸** - 项目越大越失控 | ✅ **复杂性归零** - 每个模块都是久经考验的轮子 | -| 🎓 **门槛过高** - 需要深厚编程功底才能驾驭 AI | ✅ **门槛消失** - 你只需要描述"连接方式" | - ---- - -## 💡 核心理念 - -``` -传统编程：人写代码 -Vibe Coding：AI 写代码，人审代码 -胶水编程：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 能力不断增强，未来的开发者不再需要自己写大量代码，而是： - -* 找轮子 -* 组合轮子 -* 智能连接组件 -* 以极低成本构建复杂系统 - -胶水编程将会成为新的软件生产力标准