From edb0f8e27d14cc6689eb862110ea947d9ef575c7 Mon Sep 17 00:00:00 2001 From: tukuaiai Date: Fri, 1 May 2026 22:46:54 +0800 Subject: [PATCH] docs: integrate glue coding into pinhaoma --- README.md | 4 +- assets/documents/AGENTS.md | 2 +- assets/documents/README.md | 2 +- .../principles/fundamentals/README.md | 2 +- .../principles/fundamentals/拼好码.md | 328 +++++++++++++++--- 5 files changed, 288 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 5318291..7a53d53 100644 --- a/README.md +++ b/README.md @@ -191,7 +191,7 @@ TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署
-🧬 拼好码（胶水原则） +🧬 拼好码（胶水编程的超集） > 一句话：成熟能力解决通用问题，胶水代码连接业务流程，自研只服务真正不可替代的差异。 @@ -330,7 +330,7 @@ TODO：仓库内没有发现 Dockerfile、docker-compose.yml、K8s/Helm 部署 ### 项目内部文档 -* [**拼好码（胶水原则）**](./assets/documents/principles/fundamentals/拼好码.md): 复用成熟能力，用胶水代码连接、编排、适配业务流程。 +* [**拼好码（胶水编程的超集）**](./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/AGENTS.md b/assets/documents/AGENTS.md index a89bdee..744b94f 100644 --- a/assets/documents/AGENTS.md +++ b/assets/documents/AGENTS.md @@ -24,7 +24,7 @@ assets/documents/ - `guides/getting-started/Vibe Coding 校验.md`：语言化、门禁、人机分工与 Vibe Coding 工程闭环。 - `guides/getting-started/Codex-CLI配置.md`：默认 AI CLI 路线。 - `guides/getting-started/OpenCode-CLI配置.md`：Codex CLI 不可用时的备选路线。 -- `principles/fundamentals/拼好码.md`：胶水原则与复用优先的工程交付方法。 +- `principles/fundamentals/拼好码.md`：胶水编程的超集，覆盖复用优先、能力编排、边界治理与工程门禁。 ## 操作规范 diff --git a/assets/documents/README.md b/assets/documents/README.md index 884a726..184262b 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 0645f4c..953a2b4 100644 --- a/assets/documents/principles/fundamentals/README.md +++ b/assets/documents/principles/fundamentals/README.md @@ -4,7 +4,7 @@ ## 📖 核心方法论 -### 拼好码（胶水原则） +### 拼好码（胶水编程的超集） - [拼好码](./拼好码.md) - 复用成熟能力，用胶水代码连接、编排、适配业务流程 - [语言层要素](./语言层要素.md) - 看懂 100% 代码的 8 个层级 diff --git a/assets/documents/principles/fundamentals/拼好码.md b/assets/documents/principles/fundamentals/拼好码.md index a1086ae..90d5a8a 100644 --- a/assets/documents/principles/fundamentals/拼好码.md +++ b/assets/documents/principles/fundamentals/拼好码.md @@ -1,13 +1,114 @@ -# 拼好码（胶水原则） +# 拼好码（胶水编程的超集） > 成熟能力解决通用问题，胶水代码连接业务流程，自研只服务真正不可替代的差异。 +## 关系定位 + +**拼好码不是替代胶水编程，而是胶水编程的超集。** + +胶水编程关注的是“如何用最少胶水代码把成熟模块连接起来”；拼好码在此基础上继续向前、向后扩展： + +- 向前：从用户意图出发，先判断需求能否被成熟能力覆盖。 +- 中间：选择成熟方案，设计适配边界，用胶水代码完成连接与编排。 +- 向后：把业务流程做成可运行、可验证、可替换、可回滚的系统。 + +所以： + +```text +拼好码 = 需求语言化 + + 成熟能力发现 + + 复用方案评估 + + 适配边界设计 + + 胶水编程 + + 能力编排 + + 业务逻辑表达 + + 工程门禁 + + 可替换/可回滚治理 +``` + +胶水编程是拼好码中的“连接实现层”，不是拼好码的全部。 + ## 一句话定义 **拼好码**是一种以“胶水原则”为核心的工程方法：优先复用成熟方案，只写必要的连接、编排、适配、隔离与业务代码，用最低成本交付稳定、可替换、可回滚的业务系统。 它不是“少写代码”的偷懒方法，而是把工程资源集中到业务价值上：通用复杂度交给成熟生态，业务差异由薄胶水表达。 +## 颠覆性宣言 + +拼好码不是一种单点技术，而是一套工程判断方法。 + +它继承胶水编程的“连接优先”，但不止于写胶水代码；它要求开发者从“实现者心态”转向“整合者心态”： + +> 不是看到需求就写代码，而是先识别已有能力、评估成熟度、设计边界，再用最少自研完成业务闭环。 + +| 传统 Vibe Coding 的痛点 | 胶水编程的解法 | 拼好码的扩展 | +|:---|:---|:---| +| AI 幻觉：生成不存在的 API、错误逻辑 | 只连接已验证模块，减少发明空间 | 先查成熟方案，再用门禁校验依赖、路径、接口与运行结果 | +| 复杂性爆炸：项目越大越失控 | 每个模块复用成熟轮子 | 通用复杂度交给成熟生态，业务复杂度留在清晰边界内 | +| 门槛过高：需要深厚编程功底 | 用户描述连接方式，AI 生成胶水 | 用户定义目标和验收，AI 搜索、评估、适配、编排，机器门禁强制验证 | +| 自研冲动：控制感压过工程收益 | 少写底层代码 | 偏离复用路径必须说明成本、风险、测试和回滚路径 | + +## 核心理念 + +```text +传统编程：人写代码 +Vibe Coding：AI 写代码，人审代码 +胶水编程：AI 连接代码，人审连接 +拼好码：AI 搜索/评估/连接/编排能力，人审目标/边界/门禁/取舍 +``` + +### 范式转移 + +从“生成”转向“连接”，再从“连接”升级为“能力编排”： + +- 不再默认让 AI 从零生成底层能力。 +- 不再重复造轮子。 +- 不再把“自己写”当作更可控。 +- 优先复用成熟的、经过生产验证的官方能力、平台能力、开源项目和事实标准。 +- AI 的职责是理解意图、查找能力、评估方案、生成适配层、编排流程。 +- 人的职责是说清目标、设定边界、审查取舍、设计门禁。 +- 机器门禁负责把自然语言验收标准变成测试、CI、schema、类型、脚本和检查清单。 + +## 架构哲学 + +```text +┌─────────────────────────────────────────────────────────┐ +│ 用户意图 / 业务需求 │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 拼好码决策层 │ +│ 需求语言化 -> 成熟能力搜索 -> 方案评估 -> 边界设计 │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ AI 胶水层 / 能力编排层 │ +│ 适配输入输出，连接系统，编排流程，隔离依赖 │ +└─────────────────────────────────────────────────────────┘ + │ + ┌────────────────┼────────────────┐ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ 官方能力 A │ │ 成熟库 B │ │ 平台服务 C │ + │ 官方维护 │ │ 生产验证 │ │ 可观测可替换 │ + └─────────────┘ └─────────────┘ └─────────────┘ + │ │ │ + └────────────────┼────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 可运行 / 可测试 / 可回滚的业务系统 │ +└─────────────────────────────────────────────────────────┘ +``` + +- **实体**：成熟的开源项目、官方 SDK、平台能力、托管服务、内部公共能力。 +- **连接**：AI 生成或辅助生成的胶水代码，负责数据流转、接口适配和流程编排。 +- **边界**：隔离第三方模型、SDK、API 与核心业务模型。 +- **门禁**：测试、类型、schema、lint、CI、脚本和审查清单。 +- **目标**：可运行业务流程和可替换业务系统。 + ## 核心链路 ```text @@ -23,6 +124,42 @@ UserInput(拼好码) -> 低成本高稳定工程交付 ``` +## 为什么有效 + +### 1. 幻觉问题：从“发明”转向“核验” + +AI 最容易出错的地方，是凭空发明不存在的 API、参数、路径和业务规则。 + +拼好码降低幻觉的方式不是“相信 AI 更聪明”，而是改变任务形态： + +- 先找真实存在的成熟能力。 +- 再读取官方文档、README、示例和类型定义。 +- 再生成适配层。 +- 最后用测试、运行结果和 CI 校验。 + +AI 不再主要负责发明底层能力，而是负责理解、连接、转换和验证。 + +### 2. 复杂性问题：转交给成熟生态 + +每个成熟模块背后都有： + +- 大量真实用户场景。 +- Issue 和 PR 中沉淀的边界案例。 +- 长期维护者的升级与安全修复。 +- 生产环境反复验证后的稳定性。 + +你不是在逃避复杂性，而是在复用生态已经支付过的试错成本、测试成本、维护成本和生产验证成本。 + +### 3. 门槛问题：从底层实现转向业务编排 + +你不需要把认证、支付、调度、日志、存储、解析、渲染、监控全部自己实现一遍。 + +你真正要做的是： + +> 说清业务目标，选择成熟能力，设计边界，把它们编排成业务流程。 + +这要求的不是低水平，而是更高水平的工程判断。 + ## 胶水原则 “胶水原则”是最高级别的“不重复造轮子”：能复用成熟方案就不自研底层能力，只写用于连接、编排、适配、隔离和表达业务逻辑的胶水代码。 @@ -80,6 +217,131 @@ UserInput(拼好码) 拼好码反对的是工程中的控制幻觉：开发者常把“自己写”误认为更可控、更安全、更优雅，但真实世界里，自研通常意味着更高缺陷率、更高维护成本、更弱生态支持和更差长期稳定性。 +## 实践流程 + +```text +1. 明确目标 + -> 我要实现什么业务结果？ + -> 输入是什么？输出是什么？验收标准是什么？ + +2. 寻找成熟能力 + -> 有没有官方能力、平台能力、内部公共能力？ + -> 有没有事实标准、成熟框架、开源库、托管服务？ + +3. 评估可复用方案 + -> 维护状态、许可证、安全风险、生产案例、团队熟悉度如何？ + -> 是否可观测、可测试、可替换、可回滚？ + +4. 设计适配边界 + -> 外部 SDK/API 如何隔离？ + -> 核心业务模型如何保持干净？ + -> 失败、限流、重试、回滚怎么处理？ + +5. 编写胶水代码 + -> A 的输出如何变成 B 的输入？ + -> 如何封装流程、转换数据、组合能力？ + +6. 设计工程门禁 + -> 测试、类型、schema、lint、CI、脚本、检查清单如何覆盖验收标准？ + +7. 形成可替换系统 + -> 如果第三方方案失效，替换路径是什么？ + -> 如果本次选择失败，如何回滚？ +``` + +### 使用 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 | + +## 经典案例 + +### Polymarket 数据分析 Bot + +需求：实时获取 Polymarket 数据，分析后推送到 Telegram。 + +传统做法：从零写爬虫、数据清洗、分析逻辑、Bot 推送、错误处理和调度。 + +拼好码做法： + +```text +成熟能力 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 框架、客服平台和日志监控工具。 + +胶水代码只负责： + +- 业务知识整理。 +- 问题分类。 +- 工作流编排。 +- 人工转接规则。 +- 企业系统接口适配。 +- 回答质量评估。 + +### 订单流程 + +错误路径：自己写完整调度系统、消息队列、重试机制、状态机、通知系统。 + +拼好码路径：优先使用成熟消息队列、任务调度平台、工作流引擎、云函数、监控告警服务。 + +胶水代码只负责： + +- 订单创建后触发库存检查。 +- 支付成功后触发发货。 +- 发货后触发通知。 +- 异常时进入人工处理。 +- 在不同系统之间做数据适配。 + ## 偏离协议 拼好码不是绝对禁止自研，而是要求自研必须有充分理由。 @@ -127,52 +389,19 @@ UserInput(拼好码) - 能适配时，不要入侵。 - 如果成熟方案能可靠满足需求，它就应该是默认答案。 -## 常见场景 - -### 登录认证 - -错误路径：自己设计密码加密、Token 签发、OAuth 流程、验证码和权限基础设施。 - -拼好码路径：优先评估云厂商认证服务、Auth0、Firebase Auth、Keycloak、企业统一身份系统或框架内置认证模块。 - -胶水代码只负责： - -- 把认证结果接入业务用户体系。 -- 把外部用户 ID 映射到内部用户模型。 -- 处理业务角色和权限。 -- 封装登录后的业务流程。 - -### AI 客服 - -错误路径：从零训练模型、写向量数据库、写知识库检索、写对话管理、写监控系统。 - -拼好码路径：优先使用成熟大模型 API、向量数据库、RAG 框架、客服平台和日志监控工具。 - -胶水代码只负责： - -- 业务知识整理。 -- 问题分类。 -- 工作流编排。 -- 人工转接规则。 -- 企业系统接口适配。 -- 回答质量评估。 - -### 订单流程 - -错误路径：自己写完整调度系统、消息队列、重试机制、状态机、通知系统。 - -拼好码路径：优先使用成熟消息队列、任务调度平台、工作流引擎、云函数、监控告警服务。 - -胶水代码只负责： - -- 订单创建后触发库存检查。 -- 支付成功后触发发货。 -- 发货后触发通知。 -- 异常时进入人工处理。 -- 在不同系统之间做数据适配。 - ## 与相近概念的区别 +### 拼好码 vs 胶水编程 + +胶水编程强调“用最少胶水代码连接成熟组件”。拼好码包含胶水编程，但还包含成熟能力发现、方案评估、边界隔离、门禁设计、替换路径和偏离协议。 + +简化理解： + +```text +胶水编程：把轮子粘起来 +拼好码：先判断该用哪些轮子，再设计边界、粘起来、验证它、让它可替换 +``` + ### 拼好码 vs 低代码 低代码强调用平台快速搭建应用；拼好码强调工程决策中优先复用成熟能力。低代码可以是拼好码的一种工具，但拼好码不等于低代码。 @@ -196,6 +425,7 @@ AI 特别适合生成： - SDK 调用示例。 - 配置模板。 - 迁移脚本。 +- 偏离说明。 但 AI 也容易顺手造轮子，所以更好的模式是让 AI 在胶水原则约束下工作： @@ -223,6 +453,14 @@ AI 特别适合生成： > “我该不该自己写？” +从： + +> “这个系统要写多少代码？” + +变成： + +> “这个系统能复用多少成熟能力，剩下的胶水边界是否清晰？” + 最终，拼好码要内化成一句工程本能： > 成熟能力解决通用问题，胶水代码连接业务流程，自研只服务于真正不可替代的差异。