跬步 On Coding

Lexideck 背单词小应用：AI 时代的 Vibe Coding 实践

Tue, 30 Jun 2026 19:16:00 +0800

我平时习惯通过 RSS 订阅 Hacker News，后来随着 Twitter 上线了默认翻译功能，我对直接阅读第一手英文资讯的需求越发强烈。然而现实很骨感：词汇量实在太低。因为现在机器翻译过于方便，我一般都是直接依赖浏览器翻译来看文章；有时候也会强迫自己不用全篇翻译，而是借助划词翻译来硬啃。

硬啃倒是能啃下来，但问题在于：读完了，生词该不认识还是不认识，英语水平并没有实质性的提升。

我觉得关键的痛点在于，我没有把这些在真实阅读场景中遇到的生词记录下来，也没有去反复背诵。所以我一直有个执念：做一个记录生词的工具。在划词翻译发现生词时，顺手把它记录下来，然后可以在手机上同步，随时随地利用碎片时间背单词。一旦这个“阅读发现 -> 记录 -> 间隔重复背诵”的数据飞轮转起来，我相信我的英语水平肯定会逐步提升。

不过，因为我自己一直是个偏后端的程序员，没怎么写过前端和 UI，这个计划就一直停留在脑海里，没有真正落地。

直到这半年，我深度体验了 Vibe Coding 的开发模式后，我突然顿悟了：在现在的 AI 时代，我其实根本就不需要会写前端和 UI。我只需要把需求描述清楚，让 Coding Agent 一点点帮我把代码“糊”出来就好了。

所以，我决定重启这个计划，目标是实现这样一个闭环模式：

浏览器插件：用于阅读时的划词翻译，并一键添加生词。
服务端：接收生词并存储，同时可以通过 LLM 生成更多的词汇释义、例句和记忆法。
手机客户端：同步服务端数据，利用间隔重复算法背诵生词。

1. 划词与词典：站在巨人的肩膀上

在一番调研后，我发现了一个专门做查词的浏览器插件 Yomitan。它非常强大，支持导入自定义字典，并且可以通过 AnkiConnect 协议，把查到的生词直接写入到 Anki 中。

Anki 确实是背单词的终极方案，但它毕竟是个有些古老的软件了，而且要在各个设备间丝滑同步并不算简单。不过 Yomitan 的 AnkiConnect 协议给了我灵感：我完全可以自己写一个兼容 AnkiConnect 协议的服务端，来替代 Anki 接收 Yomitan 的单词。

在寻找 Yomitan 的英汉字典时，我遇到了一点波折。网上我只找到了《牛津高阶英汉双解词典第10版(OALD 10) Yomitan 适配版》。但在实际使用中我发现，高阶字典其实不适合用来背单词——它的释义太细，例句太多，看一眼卡片密密麻麻，认知负担极重。

幸好，在那个分享帖子里，作者给出了将 mdx 字典转换为 Yomitan 格式的思路。于是我找来了《牛津低阶》、《牛津中阶》和《牛津袖珍》的双解词典，让 Coding Agent 参照别人的转换脚本，生成了这些字典的 Yomitan 版本。经过对比，我发现《牛津中阶英汉双解词典》的内容粒度最适合我现在的词汇量和背诵节奏。

(注：由于词典版权原因，这里我就不直接放分享地址了，如果有技术交流需要的同学可以给我发邮件。)

2. 服务端：轻车熟路的 Serverless 架构

搞定了输入端，接下来就是服务端了。

为了零成本且高可用，技术栈我毫不犹豫地选择了可以免费搭建的 Cloudflare Workers，数据库使用 Cloudflare D1。

说干就干。我直接套用了我之前总结定义的 Go 开发流 Prompt（参考这里），稍微调整后丢给 LLM。很快，一个运行在 Cloudflare Workers 上、完全兼容 AnkiConnect 核心接口的后端 API 服务就跑起来了。

3. 客户端：让 AI 帮我做设计与前端

数据存下来了，接下来是怎么背。

我最初在 Apple Store 上找了一些背单词 App，发现它们对导入自定义生词（尤其是带有上下文例句的生词）的支持都不太好。那我是不是要自己开发一个 iOS App？考虑到我没有苹果开发者账号，也没有备案域名，这条路显然太重了。

最终我决定：直接用 PWA (Progressive Web App) 的形式提供这个背单词的应用。

既然要提供类似 Anki 的硬核背单词体验，那就必须用上最先进的算法。我直接接入了 FSRS v5 算法来处理重复练习和刻意练习的调度。很快，一个 Demo 级别的 PWA 就写好了。

但是，Demo 实在太丑了。这时候 Vibe Coding 的威力显现了：

我在 Twitter 上看到了一个很棒的项目 awesome-design-md。我直接让 AI 结合这个库，帮我推荐一个适合背单词 App 的 DESIGN.md。

第一版，AI 推荐了 Spotify 的卡片式风格。改完一看，纯黑的主题在白天背单词看着很难受。
于是我让 AI 继续帮我换一个浅色的设计，它又推荐了 Lovable 风格。
这一版出来后，非常清爽现代。我又指挥 AI 一点点调试了 PC 端和 iPhone 端的响应式体验。

最终，就有了现在这一版体验相当不错的 Lexideck (GitHub: zhu327/lexideck)。

4. 扩展视野：终端里的碎片时间

应用跑通后，发生了一件很有意思的事。

我在逛 Twitter 的时候，看到有人推荐了 fishword 这个项目。它的理念很绝：在使用 Pi 等 Coding Agent 写代码时，Agent 经常需要好几分钟去输出 Token。这个等待的过程极其无聊，大多数人（包括我）会切出去看网页，等切回来时往往 Agent 已经执行完很久，或者中途中断了。而 fishword 在这个等待的间隙，通过 TUI 浮窗让你背单词！

这是一个极其神奇且切中痛点的想法。不过 fishword 内置的是标准词库，我既然有了 Lexideck，完全可以自己写一个 Pi extension 对接我自己的生词本。

再一次“说干就干”，很快 pi-extension-lexideck 就出炉了。

至此，我的背单词“数据飞轮”彻底闭环了：

输入：看英文文章时，用 Yomitan 浏览器插件划词翻译，一键记录生词。
移动端复习：通勤或摸鱼时，打开 iPhone 上的 PWA 背单词。
PC端复习：在用 Pi 辅助写代码等待输出时，终端里弹出生词顺手复习。

5. 解决问题与妥协

当然，开发过程中也有没解决的问题。后来我在 Apple Store 发现了一个叫“面包 Anki”的 App，支持导入 Anki 的 .apkg 数据包。为了能用上它的原生体验，我在 Lexideck 服务端增加了生词导出为 .apkg 文件的功能。

不过很遗憾，导出的文件在“面包 Anki”里无法正常导入。排查了一阵还没找到确切原因，考虑到现有的 PWA 和 TUI 已经能满足我 90% 的需求，这个 bug 我就暂时搁置了。在个人项目中，懂得适时妥协也是推进项目的一种策略。

总结：Vibe Coding 时代的程序员

回顾开发 Lexideck 的这短短几天，我最大的感慨是：我依然不懂 TypeScript，依然不会手写精美的 CSS，但我能通过 Vibe Coding 的流程，把一个全栈应用又快又好地“糊”出来。

在这个低成本 Coding 的时代，只要你有清晰的想法，能拆解梳理出自己的需求（业务逻辑、架构设计、数据流向），结合 DESIGN.md 这样的规范约束，就尽管放手去 Coding 吧。

另外分享一个经验：在这次开发中，我大量使用了国产模型做过程 Coding，速度快且便宜。但在完成某个模块后，我通常会把代码丢给 GPT-5.5 重新 Review 一下。事实证明，GPT-5.5 总是能精准地挑出一些边界条件处理不当、或者架构耦合度高的毛病。通过不同模型之间的交叉 Review 来保证代码质量，是当下极其高效的工作流。

工具已经就绪，接下来，就看我自己能不能坚持把生词背下去了，哈哈。

Loop Engineering 实践: Pi Coding Agent

Wed, 17 Jun 2026 09:16:00 +0800

我在之前写过一些关于AI Agent在开发流程中应用的经验，比如《打造适合自己的 AI Harness 工程：从开发流、E2E 测试到自动排障》。随着对AI Agent的深入实践，我发现人肉打Prompt的日子快要到头了，未来我们更多是设计一个系统，让系统来自动化地与Agent交互。最近我一直在研究 Loop Engineering，并尝试将它落地到我的日常工作中，特别是用 Pi Coding Agent 来实现自动化巡检和代码修复。

1. Loop Engineering 是什么，由哪些环境组成

以前，我们程序员和AI编码Agent的交互模式是这样的：我写一个Prompt，提供上下文，Agent返回结果，我再根据结果写下一个Prompt。Agent就像一个工具，始终在我手里。但现在这种模式正在被 Loop Engineering 所取代。

Loop Engineering 的核心思想是构建一个小型系统，让这个系统自己去发现工作、把工作交给Agent、检查Agent的产出、记录发生的一切，并自主决定下一步行动。我们只需要设计好这个系统一次，之后系统就会自动地与Agent交互。Addy Osmani 将其分解为六个部分：

Automation (自动化): 触发器，在特定时间、事件或条件发生时启动循环。
State file (状态文件): 记录循环的进度和历史，让Agent在每次运行时都能从上次中断的地方继续。
Verifier (验证器): 自动化检查Agent产出的质量，判断工作是否完成或需要返工。
Skill (技能): 封装项目特定的知识、规则和最佳实践，避免Agent重复学习上下文。
Connector (连接器): 让Agent能与外部工具（如Git、Jira、Slack、监控系统）交互，使其能在真实环境中执行操作。
Sub-agent (子Agent): 将复杂任务分解给多个Agent并行处理，通常会有一个“生成者”和一个“检查者”Agent，避免“自说自话”。

Anthropic 的工程师们在 2024 年实现了每天合并的代码量翻了八倍（虽然他们自己也承认这可能有些夸大）。但无论数字如何，核心机制是明确的：杠杆点已经从“编写Prompt”转移到了“设计驱动Prompt的循环”。

当然，不是所有任务都适合 Loop Engineering。在投入资源构建之前，我们需要进行一个“4条件测试”：

任务可重复：循环的设置成本需要通过多次运行来摊销。一次性任务手动Prompt会更快更便宜。
验证自动化：循环需要有无需人工干预就能判断工作是否失败的机制（例如测试套件、类型检查、Linter、构建）。
Token 预算充足：循环会重新读取上下文，尝试和探索，这会消耗大量Token。
Agent 拥有资深工程师的工具：日志、可复现的环境、运行和调试代码的能力。

如果这四个条件有一个不满足，那么构建循环的成本很可能高于其带来的收益。

2. goal/loop 命令意味着什么，分别有什么职能

在 Loop Engineering 中，loop 和 goal 是两个非常核心的命令，它们赋予了Agent持续运行和自我验证的能力。

/loop：定义了循环的** cadence (节奏)**，比如每隔 30 分钟运行一次，或者每天固定时间运行。它专注于“何时”运行任务，无论之前的任务是否完成，都会按时触发。
/goal：则定义了一个任务的最终结束条件。它会持续运行，直到你设定的某个条件真正满足为止。这意味着一个单独的小模型会检查完成情况，确保“制造者”Agent不会自己给自己批改作业。

我通常会将它们结合起来使用，比如：

/loop 30m /goal All tests in test/auth pass and lint is clean. Scan src/auth for new failures, propose fixes in claude/auth-fixes, open draft PR when goal condition holds.

这个命令的含义是：每隔 30 分钟，Agent 就会检查 src/auth 目录，扫描新的故障，并尝试在 claude/auth-fixes 分支中提出修复方案，直到 test/auth 中的所有测试都通过且 Lint 干净为止，然后才会打开一个 PR。这实现了任务的自动化执行和验证的 maker-checker 分离。

3. 我的 Loop Engineering 的思路

在了解了 Loop Engineering 的基本概念和工作原理后，我开始思考如何将它与我现有的 AI Harness 工程结合起来。在《打造适合自己的 AI Harness 工程：从开发流、E2E 测试到自动排障》这篇文章中，我曾提到在建设 srecli 的过程中，CLI 已经具备了查询指标（metrics）和日志（logs）的能力。现在，我又加入了 Sentry API 的事件查询功能，这三者的结合，补齐了 Loop Engineering 中“Trigger（触发器）”的部分。通过生成巡检报告，我们可以触发一个自动化的循环来识别并改进代码。

我的 Loop Engineering 思路大致分为以下几个步骤：

1. `app-inspection` 创建了一个巡检用的 skill

这个 app-inspection skill 是整个循环的起点，它负责对应用程序进行全面的健康检查。

执行 make lint/make test/make e2e: 这是最基础的静态代码检查和自动化测试，确保代码质量和功能正确性。
查询 24 小时内 metrics 5xx 请求路径，应用 ERROR 日志: 通过 srecli 接入的监控系统，我会让 Agent 检查过去 24 小时内服务的 5xx 错误率和具体的出错路径，以及应用程序的 ERROR 级别日志，从中识别潜在的运行时问题。
查询 24 小时 Sentry events: Sentry 作为错误监控工具，能够捕获应用程序的异常和错误。Agent 会查询 Sentry 中的新事件，及时发现未被其他监控捕获的问题。
出巡检报告: 综合以上所有信息，Agent 会生成一份结构化的巡检报告，这份报告是后续判断是否需要代码修复的关键依据。

这个 app-inspection skill 扮演了“Trigger”的角色，它自动化地检查了代码和服务的健康状况，作为自动化的发起条件触发为代码改进提供决策前提条件。

2. 记忆 `LOOP.md` 记录每次执行结果

为了让 Agent 拥有“记忆”，我引入了一个仓库根目录下的 LOOP.md 文件作为状态文件 (State File)。Agent 每次执行循环前，都会读取 LOOP.md 的内容，特别是其中的 In progress / Escalated to humans / Lessons learned 这三段。

In progress (进行中)：记录上次循环中识别但尚未完成修复的问题。
Escalated to humans (已升级至人工处理)：记录 Agent 尝试修复但无法自动解决，需要人工干预的问题。
Lessons learned (经验教训)：沉淀每次修复的经验，避免 Agent 重复犯错。

正如 Addy Osmani 所说，“Agent 会遗忘，但仓库不会”。LOOP.md 确保了 Agent 在每次运行时都能恢复到之前的状态，而不是从零开始，这极大地提升了循环的效率和可靠性。

# Loop state · ci-triage

## Last run
2026-06-09 03:30 UTC · 7 failures classified, 3 fixes drafted, 4 escalated

## In progress
- claude/fix-auth-token-refresh — tests passing locally, awaiting CI
- claude/fix-flaky-payment-webhook — retry pattern applied, monitoring

## Completed today
- claude/bump-axios-1.7.4 → merged (CI green, deps loop verified)
- claude/lint-fix-pass-june-9 → merged

## Escalated to humans
- src/billing/refund.ts — tests failing in 3 ways, root cause unclear
- ci/staging-runner — infra timeouts, not a code issue

## Lessons learned (write here, not in chat)
- 2026-06-08: PowerShell hits TLS 1.2 issue on this Windows runner. Use bash.
- 2026-06-07: tests/e2e/checkout requires Stripe webhook secret in env. Skip if missing.

## Stop conditions met since last review
- /goal “all tests pass + lint clean” achieved on commit 3a7b8c1 at 02:14 UTC

3. 判断跟进巡检报告，以及记忆内容，判断哪些问题需要代码修复

这是整个循环的“决策中心”。Agent 会综合分析 app-inspection 生成的巡检报告和 LOOP.md 中的历史记录：

优先接续 In progress 中未完成项：确保上次循环中开始修复的问题能够继续推进。
复核 Escalated to humans 是否已可处理：检查之前需要人工介入的问题，看是否已具备自动处理的条件。
避免重复已完成项：通过 LOOP.md 中的记录，避免重复处理已经解决的问题。

如果巡检报告没有告警或异常，并且 LOOP.md 中也没有任何待处理或待复核的开放项，那么 Agent 会判断本期无需处理，直接在 LOOP.md 顶部写入“本期无需处理的代码问题”并结束本次循环，不进行后续的代码修复流程。这就像一个“早退闸门”，避免不必要的Token消耗和资源占用。

4. 切分支，走 `go.md` 的 writing plan 后续流程完成代码修复

如果 Agent 判断存在需要修复的代码问题，那么它会基于 master 分支切出一个新的修复分支，然后进入我之前文章中提到的 go 启动 Prompt 流程。

## Required Go Gates

Maintain these gates visibly and include their final statuses in the final report:

- `GO-1: Brainstorming design approved` — status: `completed`, `blocked: <reason>`, or `skipped: <valid reason>`
- `GO-2: Design document saved` — status: `completed`, `blocked: <reason>`, or `skipped: <valid reason>`
- `GO-3: Implementation plan saved` — status: `completed`, `blocked: <reason>`, or `skipped: <valid reason>`
- `GO-4: Subagent execution completed` — status: `completed` or `blocked: <reason>`; may not be skipped
- `GO-5: Validation completed` — status: `completed`, `blocked: <reason>`, or `skipped: <valid reason>` only when no applicable validation commands are available
- `GO-6: Whole-change review completed and required fixes handled` — status: `completed` or `blocked: <reason>`; may not be skipped
- `GO-7: Simplifier completed` — status: `completed` or `blocked: <reason>`; may not be skipped
- `GO-8: Final report delivered` — status: `completed`, `blocked: <reason>`, or `skipped: <valid reason>`

在 Loop Engineering 的场景下，我会明确要求 Agent 跳过 GO-1: Brainstorming design approved 阶段。因为问题已经通过巡检报告和 LOOP.md 明确识别并锁定了，Agent 无需再进行额外的用户确认。它会直接将“巡检报告 + LOOP.md 判定出的待修复问题”作为锁定需求，从 GO-2（Design document saved）阶段开始，自动完成后续的 writing-plans、执行、验证、review 和 simplify 等所有流程，不再向用户提问。这极大地减少了人工介入，实现了开发流程的高度自动化。

5. 提交 PR

当 go.md 的所有流程（从 GO-2 到 GO-7）都顺利完成后，Agent 会自动提交 Git Commit，并使用 kgit mr master 发起合并请求 (Pull Request)。最后，它会在 LOOP.md 中写入本次运行的摘要，并根据本轮结果更新 In progress / Completed today / Escalated to humans / Lessons learned / Stop conditions 各段。

4. Pi Coding Agent 的实战

为了实现上述 Loop Engineering 的思路，我选择了 earendil-works/pi 这个 Agent 框架。

1. 配置 Pi Coding Agent

我的 pi 配置仓库 (https://github.com/zhu327/pi) 结构如下:

.pi/agent/
├── AGENTS.md              # Karpathy 风格的 agent 行为准则
├── extensions/            # 自定义扩展
│   ├── goal.ts            # 长时间目标跟踪与自动续跑（/goal 命令）
│   ├── grep-find.ts       # 确保 grep、find 工具始终激活
│   ├── model-patches.ts   # 模型级 patch（qwen3.7-max xhigh reasoning）
│   ├── question.ts        # 结构化多问题 UI（chips、多选、预览）
│   ├── todo.ts            # 4 状态任务管理 + overlay widget（/todos 命令）
│   └── web-fetch.ts       # URL 抓取转 markdown，含 SSRF 防护
├── prompts/
│   └── handoff.md         # 会话交接 prompt（替代上下文压缩）
└── skills/
    └── skill-creator/     # Skill 创建、评估、迭代优化工具链

通过 pi install 命令，我安装了两个关键的插件：

@gotgenes/pi-subagents: 实现了 Claude Code 风格的子代理，支持并行执行任务、隔离会话。这对于实现“制造者”和“检查者”分离的子 Agent 模式至关重要。
@koltmcbride/pi-loop: 提供了定时/循环 Prompt 调度功能，可以按时间间隔或 Cron 表达式反复执行任务，是整个 Loop Engineering 的核心调度器。

在设计选择上，我遵循了几个原则：

交接优于上下文压缩：使用 prompts/handoff.md 生成结构化交接文档，让新的 Agent 会话能够无缝接续工作，而不是在单个超长会话中压缩上下文，有效避免了上下文丢失和Token浪费。
Karpathy 行为准则：AGENTS.md 约束 Agent 的行为，要求“先想再写、最简实现、手术式改动、目标驱动执行”，减少过度工程和不必要的修改。

2. 用 goal meta 出一个 `goal` 的 Prompt

goal 最重要的职能是控制持续运行任务的最终结束验证条件以及一系列约束。为此，我利用了 https://github.com/joeseesun/qiaomu-goal-meta-skill 这个技能，它能够很好地实现 goal 的各种约束定义。

以下是我为 kfinops CI 分诊循环设计的一个 /goal Prompt，它详细定义了 Agent 的目标、验证、约束、边界、迭代策略以及完成/暂停条件：

/goal 运行一次 kfinops CI 分诊循环：用 app-inspection skill 跑完整巡检拿到报告；读取仓库根目录 LOOP.md 全文（重点 In progress / Escalated to humans / Lessons learned 三段），结合巡检报告判定本期要处理的真实代码问题——优先接续 In progress 中未完成项、复核 Escalated 是否已可处理、避免重复已完成项。早退闸门：若巡检报告无告警/异常，且 LOOP.md 三段（In progress / Escalated to humans / Lessons learned）中也没有任何可处理或待复核的开放项，则判定本期无需处理，立即在 LOOP.md 顶部 Last run 写明「本期无需处理的代码问题（巡检无异常 + LOOP.md 无开放项）」并直接结束 goal，不切分支、不进入 go.md 流程。否则基于 master 用 `kgit new master <task_name>` 切出修复分支；走 `.pi/prompts/go.md` 的 writing-plans 及后续全流程并自动跑完；提交 git commit 后用 `kgit mr master` 发起合并请求；最后在 LOOP.md 写入新的 Last run 条目，并将 In progress / Completed today / Escalated to humans / Lessons learned / Stop conditions 各段按本轮结果更新（保留历史已完成与已积累的 lessons，只追加不覆盖）。
验证：app-inspection 报告已生成；已读取 LOOP.md 旧状态；修复分支已存在（`git branch` 可见）；go.md 的 GO-2/GO-3/GO-4/GO-5/GO-6/GO-7 各 gate 状态已记录；`git log` 显示本次 commit；`kgit mr master` 返回 MR 编号或 URL；LOOP.md 顶部 Last run 已替换为本次时间戳与摘要，且 Completed today 或 Escalated to humans 已追加本轮分支/MR/结果。
约束：使用 go.md 流程，但跳过 brainstorming 阶段的 `question` 用户确认——把「巡检报告 + LOOP.md 判定出的待修复问题」作为锁定需求直接进入 writing-plans，之后的执行、验证、review、simplify 全部自动完成，不再向用户询问；不直接 push 或提交到 master；不修改 .pi/ 目录、巡检脚本、CI 配置、生产配置和任何密钥；不改动与本问题无关的模块；LOOP.md 只追加/更新本轮相关行，不删除历史记录与已沉淀的 lessons；判定无问题时只更新 LOOP.md 的 Last run 一行即退出，不做其他写入。
边界：只允许写入当前修复分支内的业务代码文件 + LOOP.md（仓库根目录）；禁止触碰 master 分支、其他进行中分支、.pi/、infra/生产 manifest、以及修复目标之外的破坏性操作。
迭代策略：一次只修一个被选中的真实问题；go.md 子代理执行后按验证命令（make lint-full / go test / make e2e 中与改动相关的最小集合）重跑检查；同一问题在 lint/test 上连续 2 次仍不绿必须换证据来源或降级为 escalated；单次循环最多 3 轮聚焦修复，超出则暂停并报告，并把降级项写入 LOOP.md 的 Escalated to humans。
完成条件：本次选中的修复有「分支 + commit + MR + 检查通过或明确失败原因 + LOOP.md 已更新」五项证据齐全；或在巡检 + 读 LOOP.md 后判定本期无真实可处理问题，已仅在 LOOP.md 的 Last run 写明「本期无需处理的代码问题（巡检无异常 + LOOP.md 无开放项）」后立即结束，不切分支、不进入 go.md 流程。
暂停条件：Sentry token 失效或 srecli 不可用导致巡检拿不到数据；修复需要破坏性变更、DB 迁移、付费服务、凭证或产品决策；同一问题连续 2 次无法变绿；MR 发起失败或需要人工审批；所有权或责任归属不清。

3. 配置到 Pi Coding Agent 的 Loop 流程中

在实际的 Pi Coding Agent 运行中，我们不能直接使用 /loop 0 8 * * * /goal <prompt> 这种方式来同时激活 loop 和 goal。因为 pi 的 loop 插件和 goal 扩展是分开工作的，loop 负责定时触发一个 Prompt，而 goal 负责持续推进一个长期目标。

所以，我借助 goal 扩展的 get_goal/create_goal/update_goal 工具来管理 goal 的状态。

/loop 0 8 * * * 这是每天 08:00 自动触发的 kfinops CI 分诊循环（cron: 0 8 * * *）。全程自动完成，不要向用户提问。\n\n第一步——goal 状态检查：调用 get_goal 工具。若存在 status 非 complete 的 goal 且其 objective 仍是本 CI 分诊任务（通常是昨天未跑完的遗留），直接继续推进它，跳到第三步；若遗留 goal 与当前任务无关或明显卡死，先把情况记入 LOOP.md 的 Escalated to humans，然后用 update_goal 标记 complete 以便新建。\n\n第二步——创建 goal（仅当无 active goal 时）：调用 create_goal 工具，objective 使用下方 === GOAL OBJECTIVE === 与 === END === 之间的整段原文（不要改写、不要省略）。\n\n=== GOAL OBJECTIVE ===\n运行一次 kfinops CI 分诊循环：用 app-inspection skill 跑完整巡检拿到报告；读取仓库根目录 LOOP.md 全文（重点 In progress / Escalated to humans / Lessons learned 三段），结合巡检报告判定本期要处理的真实代码问题——优先接续 In progress 中未完成项、复核 Escalated 是否已可处理、避免重复已完成项。早退闸门：若巡检报告无告警/异常，且 LOOP.md 三段中也没有任何可处理或待复核的开放项，则判定本期无需处理，立即在 LOOP.md 顶部 Last run 写明「本期无需处理的代码问题（巡检无异常 + LOOP.md 无开放项）」并直接结束 goal，不切分支、不进入 go.md 流程。否则基于 master 用 `kgit new master <task_name>` 切出修复分支；走 `.pi/prompts/go.md` 的 writing-plans 及后续全流程并自动跑完；提交 git commit 后用 `kgit mr master` 发起合并请求；最后在 LOOP.md 写入新的 Last run 条目，并将 In progress / Completed today / Escalated to humans / Lessons learned / Stop conditions 各段按本轮结果更新（保留历史已完成与已积累的 lessons，只追加不覆盖）。\n验证：app-inspection 报告已生成；已读取 LOOP.md 旧状态；修复分支已存在（`git branch` 可见）；go.md 的 GO-2/GO-3/GO-4/GO-5/GO-6/GO-7 各 gate 状态已记录；`git log` 显示本次 commit；`kgit mr master` 返回 MR 编号或 URL；LOOP.md 顶部 Last run 已替换为本次时间戳与摘要，且 Completed today 或 Escalated to humans 已追加本轮分支/MR/结果。\n约束：使用 go.md 流程，但跳过 brainstorming 阶段的 `question` 用户确认——把「巡检报告 + LOOP.md 判定出的待修复问题」作为锁定需求直接进入 writing-plans，之后的执行、验证、review、simplify 全部自动完成，不再向用户询问；不直接 push 或提交到 master；不修改 .pi/ 目录、巡检脚本、CI 配置、生产配置和任何密钥；不改动与本问题无关的模块；LOOP.md 只追加/更新本轮相关行，不删除历史记录与已沉淀的 lessons；判定无问题时只更新 LOOP.md 的 Last run 一行即退出，不做其他写入。\n边界：只允许写入当前修复分支内的业务代码文件 + LOOP.md（仓库根目录）；禁止触碰 master 分支、其他进行中分支、.pi/、infra/生产 manifest、以及修复目标之外的破坏性操作。\n迭代策略：一次只修一个被选中的真实问题；go.md 子代理执行后按验证命令（make lint-full / go test / make e2e 中与改动相关的最小集合）重跑检查；同一问题在 lint/test 上连续 2 次仍不绿必须换证据来源或降级为 escalated；单次循环最多 3 轮聚焦修复，超出则暂停并报告，并把降级项写入 LOOP.md 的 Escalated to humans。\n完成条件：本次选中的修复有「分支 + commit + MR + 检查通过或明确失败原因 + LOOP.md 已更新」五项证据齐全；或在巡检 + 读 LOOP.md 后判定本期无真实可处理问题，已仅在 LOOP.md 的 Last run 写明「本期无需处理的代码问题（巡检无异常 + LOOP.md 无开放项）」后立即结束，不切分支、不进入 go.md 流程。\n暂停条件：Sentry token 失效或 srecli 不可用导致巡检拿不到数据；修复需要破坏性变更、DB 迁移、付费服务、凭证或产品决策；同一问题连续 2 次无法变绿；MR 发起失败或需要人工审批；所有权或责任归属不清。\n=== END ===\n\n第三步——执行：goal 创建（或接续）后，立即按 objective 中的 验证/约束/边界/迭代策略 推进；走 .pi/prompts/go.md 流程但跳过 brainstorming 的 question 确认。\n\n第四步——收尾：达到 objective 的完成条件后，调用 update_goal 工具标记 complete。

这个 JSON 配置定义了一个每天早上 8 点触发的循环。每次循环启动时，它会首先检查是否存在未完成的 goal，如果存在，则继续推进；否则，它会创建一个新的 goal，其 objective 就是上面那段长 Prompt。然后，Agent 会按照 objective 中定义的验证、约束、边界和迭代策略来执行，并最终在 goal 完成时将其标记为 complete。

通过这种方式，我成功地让我的 Pi Coding Agent 实现了：每天自动进行应用巡检，根据巡检报告和历史记录判断是否需要代码修复，如果需要则全自动地切分支、走完整个代码编写、测试、审查流程，并最终提交 PR。

总结

在过去的两年里，与编码 Agent 协作的重心一直放在 Prompt 上，我们追求更好的 Prompt、更精确的上下文、更优秀的单次输出。但现在，这个阶段正在结束。Agent 已经足够强大，下一个杠杆点已经提升了一个层次：它转变为设计一个系统，由这个系统来决定 Agent 何时工作、做什么、通过什么门槛、以及哪些状态需要在不同运行之间持久化。

但坦率地说，并非所有开发者都应该立即冲向 Loop Engineering。只有当任务重复、验证自动化、预算能够承受消耗、并且 Agent 拥有资深工程师的工具时，Loop Engineering 才能发挥其价值。如果错过其中任何一个条件，那么构建循环的成本可能远高于其回报。

如果这些条件都符合，那么就从小处着手：一个自动化、一个技能、一个状态文件、一个验证门。先让手动运行变得可靠，然后将其封装成技能，再用循环来调度。顺序至关重要。跳过这些步骤，你最终可能会为一套无人理解的系统买单。

杠杆点已经移动，我们的工作职责也随之改变。构建循环，但要始终保持工程师的思维。

用LLM Wiki构建SRE知识库

Wed, 27 May 2026 09:16:00 +0800

前段时间，部门leader交给我一个任务：公司SRE平台的工单系统已经累积了7019个人工工单，这些工单里沉淀了大量运维过程中的实际问题和解决经验，leader希望我能用这些数据建立一个SRE领域的专属知识库。

接到任务后，我初步盘算了一下，制定了一个看似顺理成章的计划：

把这7000多个工单全部格式化为Markdown文件，提取工单标题、内容、处理会话以及审批详情。
选型知识库的检索方案，在传统的 RAG（检索增强生成）和最近比较火的 LLM Wiki 之间做个抉择。

但随着项目的推进，我发现事情并没有那么简单。在这个过程中，我对“如何用大模型解决实际工程问题”又有了一些新的体悟，在这里复盘总结一下。

1. 现实的骨感：信息密度极低的“脏数据”

在写脚本把7019个工单全部格式化抓下来之后，我满怀期待地开始分析数据，结果被现实浇了一盆冷水。

我发现大部分的工单内容极其水：基本都是“我想开通XX权限”、“XX环境怎么连不上了”，然后处理结果直接就是“已处理”、“已结束”。中间的沟通会话也往往是简单的确认信息（比如“是这个IP吗？”“是的”）。

这意味着工单本身的信息密度是非常低的。如果采用 RAG 方案，核心逻辑是文本切块（Chunking）和向量检索。面对这种毫无上下文、纯碎片的工单信息，切块后丢进向量数据库，检索出来的绝对是一堆毫无逻辑关联的废话，基本没有可行性。

考虑到 RAG 方案在召回、重排上需要花费极大的精力去调优，而我的工程直觉告诉我：尽量不要搞得那么复杂，怎么简单怎么来，快速跑通才是王道。

所以我决定放弃 RAG，走 LLM Wiki 的方案。

2. 初试 LLM Wiki 与人工“蒸馏”

LLM Wiki 本质上是一种方法论（通过大模型全局阅读并生成结构化的索引和概念页面，查询时先查索引再读原文），具体怎么实现各有各的说法。为了快速验证，我找了 NousResearch 官方的 Hermes Agent SKILL，稍微修改适配了 Cursor 就跑了起来。

第一次 Ingest（数据摄入）跑完后，大模型基于工单生成了 25 个 Entities（实体）和 Concepts（概念）页面。查询的时候确实能起到一些作用，但问题依然回到了数据源本身——工单信息太碎了，Agent 检索回答的依然是碎片信息的拼凑，效果并不理想。

思考了一下，我决定回到问题的本质：大模型再强，也无法从没有逻辑的对话中凭空创造严谨的知识。

于是我做了一个苦力活（也是最关键的一步）：把工单中有用的事实信息分类整理，蒸馏出真正的核心内容。我按照上一步生成的 25 个概念分类，重新梳理了一份 1400 行的 SRE 领域知识文档。在用 Agent 辅助蒸馏的过程中，我反复强调了一个 Prompt 核心：绝对不要添油加醋，必须是工单中确认的客观事实。

这份 1400 行的文档，把原本碎片的工单价值分门别类地聚拢了起来。说实话，单单是这份纯文本发出来，就已经非常有价值了，甚至不需要 Agent 来检索。

3. 扩大战果：整合全域资产

有了这份高质量的“蒸馏”数据后，我开始思考更高维度的解法。

其实部门内部原本是有一些 SRE 相关的系统性文档的，只是非常零散，散落在各个地方，且互相之间有很多复杂的文档引用。既然要做知识库，不如一次性做透。

我利用 WPS 的云文档 MCP 工具（mcp_kso-yundoc），写脚本爬取了所有这些现存的 SRE 领域知识库文档，规范化地保存到 raw/articles 目录下。

加上之前蒸馏出来的 25 份核心工单事实，我的知识库语料扩充到了 646 份高质量文档。

4. 建立真正的 SRE Wiki Index

语料准备就绪后，我基于这些高质量文档，重新跑了一遍 LLM Wiki 的 Ingest 流程。

这一次，奇迹出现了。系统完美地生成了 22 个 Entities 页面、56 个 Concepts 页面，以及 1 个 Comparisons 页面。一整个 SRE 领域的全景索引（Index）被清晰地建立了起来。

看看最终生成的 index.md，非常有成就感：

# Wiki Index

> 金山办公 SRE 平台工单知识库内容目录。
> 每个 wiki 页面按类型归类，附一行摘要。查询前先读此文件定位相关页面。
> Last updated: 2026-05-26 | Total pages: 86

## Entities

| Page | Summary |
|------|---------|
| [[kae-application-engine]] | KAE 金山应用引擎 — 一站式应用生命周期管理平台（创建/发布/性能分析/日志/配置/OpenAPI/WPS365 API对接/开放平台应用管理） |
| [[kcicd-ci-cd-platform]] | KCICD CI/CD 流水线平台 — 镜像构建/自动部署/多分支编排/Webhook/Git Submodule/国际化镜像加速/构建缓存 |
| [[klb-load-balancer]] | KLB 金山负载均衡 — 上游配置/路由插件/健康检测/证书自动化/七层路由/监控指标/灰度放量 |
| [[khub-image-registry]] | KHUB 镜像仓库平台 — 镜像存储/清理/海外分发/hub-mirror/清理策略/权限管理 |
| [[milvus-vector-database]] | Milvus 向量数据库 — 存储计算分离架构/索引选型/性能基准/部署运维/监控/可用性矩阵 |
| [[business-gateway]] | 业务网关平台 — istio+Envoy 网关/路由/限流/WASM/Lua/鉴权/监控/多实例 |
| [[istio-service-mesh]] | istio 服务网格 — istiod 配置/Sidecar iptables/Proxyless gRPC/东西流量/性能优化 |
| [[domain-management]] | 域名管理 — 购买/备案/解析/国际化域名/域名适配库/Region-Srv/企业自定义域名 |
| [[ssl-certificate]] | SSL 证书管理 — DV/OV/EV 证书/购买/部署/KLB 自动化/巡检 |
| [[inner-ingress-gateway]] | 内网网关 — 集群内服务就近访问/inter-ingress-gateway/跨机房切量 |
| [[region-srv]] | Region-Srv 域名下发服务 — entry 域名配置/v2/v3 接口/全球多区域 |
| [[cdn-service]] | CDN 内容分发网络 — CDN 域名规范/国际化 CDN/wpscdn 域名体系/多厂商覆盖/回源配置 |
| [[iam-identity-management]] | IAM 身份与访问管理系统 — 组织/企业/用户/部门模型，KSO Token 认证体系，云厂 AK/SK 全生命周期管理，权限命名规范，订阅通知，安全系数机制，OAuth2 SSO/KIAM |
| [[kac-access-control]] | KAC 访问控制平台 — 堡垒机/权限审批/操作审计/云厂账号及AK全生命周期管理/KAC配置中心 |
| [[srecli-cli-tool]] | srecli SRE 命令行工具 — AI 驱动的排障搭子，统一对接 KAE/KLB/KDB/KITSM/KCG 能力 |
| [[bastion-host]] | 堡垒机 KSOP — 基于 JumpServer 的商业版堡垒机，域名已迁移至 ksop.kso.net |
| [[kafka-message-queue]] | Kafka 消息队列 — 消息中心/Topic管理/磁盘扩容/消费堆积/跨集群通信 |
| [[kdb-database-platform]] | KDB 金山数据库平台 — 监控架构/备份降本与事故复盘/Binlog 中心规划/MySQL HA/多引擎管理 |
| [[ks3-object-storage]] | KS3 金山对象存储 — Bucket管理/CORS/生命周期/AK-SK/回收站 |
| [[kslm-license-management]] | KSLM 许可证管理 — 软件许可证购买/分配/监控/回收 |
| [[ceph-storage]] | Ceph 存储集群 — YXY Ceph 分布式存储管理 |
| [[sre-team]] | SRE 团队 — 组织架构/职责分工/工单流程/KITSM权限 |

## Concepts

| Page | Summary |
|------|---------|
| [[cloud-native-application-standards]] | 云原生应用规范 — 优雅启停/微服务治理/可观测性/Docker 镜像规范/KLB 使用规范/共享集群/K8S 调度原理/HPA/调度优化/安全规范 |
| [[cloud-vm-image-standardization]] | 云主机基础镜像标准化 — Linux/Windows 系统配置/安全加固/磁盘自动挂载/内核参数优化 |
| [[container-graceful-shutdown]] | K8S 应用优雅启停 — SIGTERM 处理/preStop Hook/Pod 生命周期/1号进程问题/优雅下线流程/滚动升级策略 |
| [[container-image-management]] | 容器镜像管理 — Docker 镜像规范/KHUB/Harbor/hub-mirror/清理策略/海外分发 |
| [[cloud-platform-release-standards]] | 云平台发版流程和标准 — 产研测三方流程/发版节奏/准入准出标准/线上监控指标 |
| [[cloud-service-change-process]] | 云服务变更流程规范 — 核心/企业核心/非核心云服务变更评审要求/warroom 应急处置 |
| [[kso-token-authentication]] | KSO Token 认证与透传 — JWKManager/Claims 提取/透传/刷新/持久化/业务网关集成/鉴权网关规则变量 |
| [[klb-upstream-configuration]] | KLB 上游配置 — 上游组/负载均衡算法/健康检测/流量比例/超时重试 |
| [[sre-client-certificate-login]] | 使用客户端证书登录 SRE — p12 证书加密/HOST 配置/多平台导入方式 |
| [[kdesign-theme]] | Kdesign Theme 主题使用 — 多主题模式/动态皮肤切换/theme-mode |
| [[kdesign-icons-library]] | Kdesign Icons 图标库 — React/Vue/Vue3 SVG 图标/多色填充/Figma IconGen 插件 |
| [[service-governance]] | 微服务治理 — 服务发现/gRPC LB/k8sresolver/东西流量/全链路灰度/蓝绿发版/RPC规范/熔断降级/开发环境治理/流量泳道 |
| [[capacity-management]] | 容量管理 — K8S 集群调度/连接数治理/HTTP 连接池配置/异常连接案例/TIME_WAIT 治理 |
| [[database-capacity-management]] | 数据库容量管理 — MySQL/Redis/TiDB 等容量规划/扩容缩容/数据归档与成本优化 |
| [[mysql-operation-practices]] | MySQL 运维实践 — 开发规范/GTID HA/主从延迟/CHAR-VARCHAR/2020-2023 故障模式/BlockHole 运维 |
| [[redis-operation-practices]] | Redis/Tendis 运维实践 — 使用规范/性能排查/主从复制/宿主机初始化/2020-2023 故障模式 |
| [[tidb-operation-practices]] | TiDB 开发与运维规范 — 开发规范/TiUP 部署/慢查诊断/OOM 预案/系统表与常用命令 |
| [[clickhouse-operation-practices]] | ClickHouse 运维实践 — 表引擎选择/字段设计/SQL 规范/分布式集群方案/高可用架构 |
| [[mongodb-operation-practices]] | MongoDB 运维实践 — 设计规范/索引/API/连接规范/2021-2023 故障模式 |
| [[elasticsearch-operation-practices]] | Elasticsearch 运维实践 — 概念/集群模式/KDB 平台操作/Mapping/自研插件/Go SDK/常见问题 |
| [[network-security-practices]] | 网络安全实践 — DNS/域名安全/SSL证书/本地HTTPS/IP白名单/来源IP与白名单区别/CSRF防护 |
| [[network-infrastructure]] | 网络基础设施 — VPC安全分级/DCI专线/子网带宽/MTU/网卡队列/NCE纳管/内部网站 |
| [[idc-operations-practices]] | IDC 机房运维实践 — 上架流程/现场操作/设备报废/存储介质/OpenStack扩容/NUMA/BIOS |
| [[idc-and-hardware-management]] | IDC 与硬件管理 — 服务器上架/设备报废/存储介质销毁/机房操作规范/NUMA |
| [[observability-platform]] | 可观测性平台 — Prometheus/VM/Grafana/日志平台/Jaeger/50X告警/采样率治理 |
| [[observability-and-monitoring]] | 可观测性与监控 — Metrics/Logging/Tracing 三大支柱/Prometheus/VM/日志平台/Jaeger |
| [[ingress-gateway-comparison]] | 入口网关对比 — Kong vs istio Gateway vs KLB/分层架构/选型建议 |
| [[cascading-failure-patterns]] | 级联故障模式 — KLB/业务网关/连接追踪表溢出/多域名互相影响/客户端重试风暴 |
| [[fault-recovery-and-postmortem]] | 故障复盘方法论 — 故障分级/应急响应/复盘模板/根因分析与改进跟踪 |
| [[tcp-connection-problems]] | TCP 连接问题 — 半连接队列满/TIME_WAIT堆积/连接追踪表满/连接数暴涨/OOM |
| [[config-driven-incidents]] | 配置变更驱动的故障 — 权益变更/DNS配置/健康检查配置/灰度回退 |
| [[client-retry-storm]] | 客户端重试风暴 — 权益变更触发传输重试/推送通道断开触发重连/重试放大机制 |
| [[internationalization-deployment]] | 国际化部署 — 海外机房/网络隔离/监控数据源/域名规范/全链路灰度/账号数据迁移及服务升级 |
| [[i18n-and-multilanguage]] | 国际化与多语言研发 — i18n 工具链/资源文件管理/前后端多语言规范与差异化配置 |
| [[local-development-environment]] | SRE 内网本地开发环境 — 珠海园区 k8s_local_dev 集群，支持本地断点调试和服务网格流量泳道 |
| [[wps-web-plugin-system]] | WPS Web 插件 2.0 体系 — 第二代 JSAPI + Web 插件框架，CEF 改造/FakeHTTPS/WPSvConsole/插件平台 |
| [[wps-365-api-system]] | WPS 365 API 体系 — 云体系统一 API，涵盖 IAM/Drive/会议/日历/邮箱/稻壳等核心领域 |
| [[topic-change-process]] | Topic 变更流程 — 发布方/订阅方标准化 Topic 迁移流程，双写渐进式切换 |
| [[ref-ai-gateway]] | AI 网关运行备忘 — 大模型统一接入/EP管理/灰度放量/模型配额 |
| [[ref-bastion-host]] | 堡垒机运行备忘 — KSOP域名迁移/连接排障/安全组配置/权限管理 |
| [[ref-cdn-configuration]] | CDN 配置运行备忘 — 多厂商覆盖/回源配置/CORS/缓存刷新/排障指南 |
| [[ref-data-migration]] | 数据迁移运行备忘 — DTS工具矩阵/跨区域同步/checksum校验/不支持的场景 |
| [[ref-database-capacity-management]] | 数据库容量管理运行备忘 — 监控指标/扩容阈值/连接池配置/慢查询 |
| [[ref-international-deployment]] | 国际化部署运行备忘 — 海外集群/网络隔离/监控数据源/上线流程 |
| [[ref-ip-whitelist-management]] | IP 白名单管理运行备忘 — 三层架构/KAE出口IP/安全组/桶策略/申请流程 |
| [[ref-k8s]] | K8S 集群管理运行备忘 — 资源配额/调度/命名空间/ETCD/PVC |
| [[ref-kac]] | KAC 配置中心运行备忘 — 下线迁移/域名兼容性/K8S Secret注入 |
| [[ref-kae]] | KAE 应用引擎运行备忘 — 工作负载/健康检查/准入策略/NodePort限制 |
| [[ref-kae-container-troubleshooting]] | KAE 容器排障运行备忘 — ExitCode对照/Pod故障模式/优雅启停 |
| [[ref-kafka-operations]] | Kafka 运维运行备忘 — ConsumerLag/磁盘扩容/Topic管理/客户端兼容性 |
| [[ref-klb-operations]] | KLB 运行备忘 — 路由插件/监控指标/证书管理/上游配置/日志分析/ACL/流量染色 |
| [[ref-kdb]] | KDB 数据库平台运行备忘 — 多引擎支持/安全策略/DDL工单/ClickHouse排障 |
| [[ref-ks3]] | KS3 对象存储运行备忘 — CORS配置/生命周期/回收站/Cloudplex自助 |
| [[ref-kslm]] | KSLM 监控告警运行备忘 — Prometheus保留期/告警平台迁移/knight |
| [[ref-network-security]] | 网络安全运行备忘 — WAF拓扑/DDoS防护/网络隔离/漏洞管理 |
| [[ref-permission-management]] | 权限管理运行备忘 — RBAC模型/策略配置/权限失效/审批缓存 |
| [[ref-sre-team]] | SRE 团队运行备忘 — KITSM 权限/工单审批链/项目加入流程/值班惯例 |

## Comparisons

| Page | Summary |
|------|---------|
| [[ingress-gateway-comparison]] | 入口网关对比：Kong vs istio Gateway vs KLB — 功能/场景/运维/选型建议 |

## Queries
<!-- 值得保留的查询结果 -->

5. 交付与总结

最后，我基于 LLM Wiki 的机制，单独抽取了一个 wiki-query 的只读查询 SKILL，交付给了负责 Agent 的团队。

现在，一个专用的 SRE 领域知识库查询 Agent 正式上线了。当用户提问时，Agent 的工作流非常清晰：

先看 Index 目录，定位到可能相关的几个概念/实体页面。
直接读取这几个文档的原始内容（因为长文本大模型的上下文窗口现在足够大）。
综合多份原文进行总结回答，并在回答中附带上精准的文档引用链接。

为什么最终没有用 RAG？

在这次实践中，我深刻体会到，当一个业务领域的概念繁杂、专业名词多且上下文强依赖时，RAG 的召回率往往是个灾难。你要花大量的时间去搞定 Chunking 策略、微调 Embedding 模型、优化多路召回和重排机制，ROI 非常低。

而 LLM Wiki 的思路，其实就是利用了当前大模型超长上下文的能力——大力出奇迹。通过前期建立良好的索引目录，查询时直接把整篇甚至多篇高度相关的文档塞给大模型，让它自己去阅读理解。这种做法不仅实现起来简单直接，而且几乎杜绝了碎片化导致的幻觉，给出的答案质量极高。

软件开发的过程实际就是解决问题的过程。架构的设计、技术的选型，不能盲目追逐所谓的主流（比如言必称 RAG），最终还是要服务于数据本身的特质和实际的业务需求。在妥协与变通中找到那条最简单、最能快速跑通的路径，往往就是最优解。

打造适合自己的 AI Harness 工程：从开发流、E2E 测试到自动排障

Sat, 09 May 2026 10:16:00 +0800

最近有点忙，主要围绕着打造适合自己的 harness 工程来进行。在之前的《AI工程落地实践》的文章中，我已经基于 superpowers 构建了适合我们团队的 AI 开发工作流：

brainstorming ──→ writing-plans ──→ executing-plans ──┬──→ test-driven-development
                                                      └──→ code-review-expert ──→ learn

但是在这个流程的中间，我发现了一个问题：我需要多次跟 Agent 对话来确认进度，而 Cursor 是以请求次数计费的。这就导致每次开发需求我不仅需要频繁切入确认，还浪费了不少 Cursor 的高级模型请求次数。为了解决这个问题，我在现有的开发流程上增加了一个新的 go 启动 SKILL。

1. 开发流程的全自动化与架构规约

通过引入新的启动机制，现在的流程流畅了很多：

https://github.com/zhu327/go-clean-arch/blob/main/.cursor/skills/go/SKILL.md

除了第一步 brainstorming 阶段还需要人工确认（其实也是通过 AskQuestion Tool 来引导提问），剩下的一旦启动，1次请求就可以走完整个开发流程，最多可以一口气消耗掉 2 千万 Token。

除了开发流程本身的提效，这期间我感触最深的一点是：要写清楚架构约束，制定好项目的规约。这就是 harness 工程极其重要的一部分。比如我在维护的 Go 项目中，基于 DDD + Clean Architecture 的约束，我对每一层的代码都做了详细的规范化：

https://github.com/zhu327/go-clean-arch/tree/main/.cursor/rules

基本上按这个流程并加上严格的 rule 约束开发以后，我就不怎么再自己去一行行 review 代码了。Opus 4.6 确实强，配上详尽的上下文，真有点“言出法随”的意思。

2. 让 AI 接管 E2E 测试

代码虽然是 AI 写的，但在合并代码前，我还是得手工黑盒测试相关逻辑是否满足需求。既然 AI 都能写代码了，那能不能让 AI 来帮我们做 E2E 的 API 测试呢？

要做 E2E 测试，首先要解决的是环境问题。以前手工测试的时候，我往往只能把代码发布到测试环境上做，因为应用本身依赖的外部 HTTP/gRPC 服务非常多，又有自己的数据库，在本地测试造数据非常麻烦。为了打造一个适合 AI Agent 的 E2E 测试环境，我做了以下基建：

外部依赖 Mock：我找到了 mockd，它可以直接 mock 真实的 HTTP/gRPC 服务。我们的 app 只需要把依赖服务的地址配置到 mockd 上，所有的请求真实发生，只是打到了 mockd 上。
数据库依赖：通过 testcontainers-go，用 Docker 在每次测试前启动真实的数据库，测试后自动销毁。
API 验证：引入了 gavv/httpexpect 来方便地请求 API 并验证返回数据。

环境有了，数据构造对 AI 来说根本不是事儿。为了把 E2E 测试也加入到标准流程中，我专门写了一个 e2e-testing 的 skill，并把它加入到 writing-plans 的过程中，强制要求 Agent 在有接口变更时，先设计 E2E 测试用例并构造数据。所有的 E2E 测试直接在代码仓库中维护。

把 E2E 加入到开发流程中后，我基本上彻底从代码细节中解放出来了。现在我主要看的就是 E2E 的测试用例是否符合业务预期，预期对上了，就快速开发、快速上线。

3. SRE 与自动排障 Agent 的探索

除了开发流程的 AI 化，我还关注到了一个非常有意思的开源项目：OpenSRE。它旨在构建开源 AI 运维智能体，依托大模型与各种监控基建工具，通过自动关联告警、日志与指标进行深度推理，实现生产故障从定位到修复的端到端自动化。

在研究了相关流程以后，我萌生了自己做一个自动 AI 排障 Agent 的想法。正好我们部门也在推进 srecli，这个命令行工具整合了 SRE 平台的容器、网关、CMDB、DB平台、日志、告警和知识库。有了底座，结合我之前在《复盘：ClawOps AI Agent》中得出的经验——不要轻易从头造一个厚重的 Agent，我决定还是走轻量级的路线，构建一套 SKILL 组合。

首先用 AGENTS.md 给 Agent 立一个人设：

You are Tracer, a Senior SRE Assistant for incident investigation and root cause analysis.
你的任务是帮助开发者排查生产故障。你可以调用底层的 `srecli` 工具来获取监控、日志、Kubernetes和发布状态等信息。

核心工作原则：
1. **证据驱动****：当你需要确切证据（错误堆栈、具体指标值、发版时间）时，必须调用 `srecli`，不要猜测。
2. **结构化输出****：永远不要向用户倾泻原始日志或大量 JSON，请对信息进行提炼。
3. **区分事实与推测****：明确指出哪些是已验证的证据（Validated Claims），哪些是合理的推测（Non-validated Claims）。
4. **无指责文化（Blameless）****：关注系统和流程的缺陷（如“缺乏配置校验”），而不是人的失误（如“小明配错了”）。
5. **增量排查****：每次调用工具后，说明你的发现，并说明你的下一步排查计划，让开发者随时掌握排查进度。

接下来就是一套基于事件流的 SKILL 组合：alert-triage -> root-cause-analysis -> blameless-postmortem。我把多方看文章和研究 OpenSRE 蒸馏出来的逻辑写成了模板（节选部分核心逻辑）：

Skill: Alert Triage (告警初诊)

要求 Agent 提取受影响范围，收集四大黄金信号（Latency, Traffic, Errors, Saturation），追溯最近1小时的变更记录，并对日志进行摘要聚类。绝对禁止直接输出原始日志。

# Skill: Alert Triage & Context Gathering
**Description**: 
当用户丢出一个告警（如高错误率、CPU飙升）或描述一个线上故障时触发。你的任务是作为 SRE 值班工程师的“副驾”，迅速通过 `srecli` 完成第一轮现场信息收集与整合，避免工程师在多个监控平台间来回切换。

## Core Workflow (执行动作要求):
1. **解析意图与范围****：提取受影响的 Service, Namespace/Environment, Time window。
2. **收集四大黄金信号 (Golden Signals)****：调用 `srecli` 收集该服务及核心依赖的以下指标：
   - **Latency (延迟)**: 获取 P50, P95, P99 响应时间。
   - **Traffic (流量)**: 获取请求速率 (RPS) 或当前活跃连接数。
   - **Errors (错误)**: 计算整体错误率 (5xx 比例) 及 Error Budget Burn Rate (判断是 Fast burn 还是 Slow burn)。
   - **Saturation (饱和度)**: 获取 CPU 利用率 (是否发生 Throttling)、内存使用率 (是否接近 OOM)、连接池使用率。
3. **变更追溯 (Change Context)****：调用 `srecli` 获取最近 1 小时内该服务的基础设施变更、代码发布记录（Deployments/Rollouts）。
4. **日志摘要 (Log Digestion)**：调用 `srecli` 获取最近 15 分钟的 ERROR/FATAL 日志。**[绝对禁止]**** 直接输出原始日志，必须对日志进行聚类（如：某 NullPointerException 出现 50 次）。

## Constraints (排障护栏):
- 必须验证指标的当前状态，不要只看告警触发那一刻。
- 不要只看当前服务，检查其**下游依赖调用失败率**。
- **输出必须结构化**，让值班人员一眼看清现场。

## Output Template (必须严格遵循以下格式输出):
### 🚨 告警初诊报告: [Service Name]
- **告警时间与影响服务**: [时间] / [受影响服务]
- **Error Budget 状态**: [判断属于 Fast burn / Slow burn / 正常，及当前错误率]

#### 📊 黄金信号快照 (Golden Signals)
- 🟢/🔴 **Latency****: [当前 P99 延迟，对比基线]
- 🟢/🔴 **Traffic****: [当前 QPS/连接数趋势]
- 🟢/🔴 **Errors****: [当前 5xx 错误率]
- 🟢/🔴 **Saturation****: [CPU节流 / 内存使用 / 磁盘 / 连接数状态]

#### 🔄 上下文与变更记录
- **最近发布**: [时间 / 版本号 / 变更人，如无则写"1小时内无变更"]
- **关键日志聚类**:
  1. `[报错类型摘要]` - 出现 N 次
- **下游依赖**: [依赖服务是否健康]

#### 🧠 初步判断与建议步骤
- **初步判断**: [例如：现象高度吻合 21:31 的灰度发布窗口，且新版本 Pod 错误率显著高于旧版本]
- **下一步建议****: [列出具体建议，如“是否允许我调用 `srecli` 查看慢查询？”或“是否暂停灰度扩大？”等待用户指令]

Skill: Root Cause Analysis (根因分析)

遵循“提出假设 -> 寻找判别性证据 -> 排除假设 -> 锁定根因”的逻辑链。输出必须包含“已证实的推论”和“尚未证实的假设”，并且给出紧急止血的建议动作。

# Skill: Root Cause Analysis (Hypothesis-Driven)
**Description**:
当需要定位问题根本原因时触发。你必须表现得像一名资深 SRE。排查不是盲目执行命令，而是遵循“提出假设 -> 寻找判别性证据 -> 排除假设 -> 锁定根因”的逻辑链。

## Reasoning Sequence (排查逻辑链):
1. **观察事实 (Observe)****: 列出目前已知的确凿事实。
2. **生成假设 (Hypothesize)****: 形成 2-4 个合理的根因假设。
3. **判别性验证 (Discriminate)****:
   - 优先选择能**同时证实一个假设并排除其他假设**的 `srecli` 动作。
   - **特殊处理规则**:
     - *CPU/连接数告警*: 必须区分是“空闲连接堆积”、“慢查询/昂贵查询”还是“真实流量突增”。
     - *存储打满*: 必须明确检查是否为 Audit logs (如 Postgres/Aurora) 等后台机制导致。
4. **排除与锁定 (Eliminate & Select)****: 排除与证据矛盾的假设。如果多个假设存活，选择最符合奥卡姆剃刀原则的，并注明。

## Anti-Bias Rules (防偏见规则):
- 不要预设故障类型，让数据说话。
- 如果现有假设与调取到的指标/日志矛盾，立即抛弃并生成新假设。
- **绝不伪造数据**：如果缺少遥测数据，必须在“缺失证据”中明确声明。

## Output Template (必须严格遵循以下格式输出):
### 🔍 深度根因分析 (RCA) 结论

**ROOT_CAUSE (根本原因)****:
[1-2句话陈述。如果无法证实，请写 "最有可能的根因是...，但缺失以下证据：...。绝不能只写'无法确定'。]

**ROOT_CAUSE_CATEGORY****:
[必须从以下选择其一：configuration_error | code_defect | data_quality | resource_exhaustion | dependency_failure | infrastructure | unknown]

**CAUSAL_CHAIN (故障传导链)****:
- [Step 1: 触发点/初始故障，如: 错误配置被合入]
- [Step 2: 故障蔓延，如: 连接池未正确释放]
- [Step 3: 最终症状，如: 数据库拒绝连接导致API 502]

**EVIDENCE_DIGEST (证据摘要)****:
✅ **VALIDATED_CLAIMS (已证实的推论)****:
- [事实 1] [Evidence: srecli 调用的具体指标/日志路径]
- [事实 2] [Evidence: ...]

⚠️ **NON_VALIDATED_CLAIMS (尚未证实的假设)****:
- [假设 1] [需什么数据验证，如: "需验证 DB 慢查询日志，但当前无 srecli 权限"]

**ALTERNATIVE_HYPOTHESES_CONSIDERED (被排除的假设)****:
- [被排除的假设及排除原因，如: "曾怀疑突发流量，但排查发现 QPS 同比无明显上升"]

**REMEDIATION_STEPS (修复建议)****:
1. [最紧急的止血动作，附带确切的 `srecli` 命令代码块（如回滚/扩容），提示用户确认执行]
2. [下一步修复建议]

Skill: Blameless Postmortem (无指责复盘)

故障恢复后，要求 Agent 出具复盘报告。运用 5 Whys 分析法深挖系统性缺陷，并按照 SMART 原则和控制层级（系统防护 -> 自动化检测 -> 流程规范）提出预防措施。

# Skill: Blameless Postmortem Generation
**Description**:
当故障恢复，用户要求出具故障通报或复盘报告时触发。你不仅要总结事件，还要将失败转化为组织学习的机会。

## Core Principles (核心原则):
1. **无指责文化 (Blameless Culture)****: 人难免犯错，系统应该具备韧性。绝对不要写“某开发人员配置错误”，必须重构为“部署流水线缺乏配置合法性校验”。
2. **量化影响 (Quantify Impact)****: 必须量化受影响用户数、SLA 违规时间、潜在业务损失。
3. **5 Whys 分析****: 深度追问，不能停留在“代码有Bug”表面，要深挖到流程、架构设计的系统性原因。
4. **SMART 与控制层级 (Hierarchy of Controls)****: 预防措施按“消除风险 -> 增加系统护栏 -> 完善流程(SOP) -> 培训”的优先级提出。

## Output Template (必须严格遵循以下 Markdown 结构):
### 📄 故障复盘报告 (Blameless Postmortem)

#### 1. 摘要与量化影响 (Summary & Impact)
- **事件描述**: [1-2句话总结]
- **故障级别**: [Sev1/Sev2/Sev3]
- **量化影响**: [受影响用户占比 / 具体 Downtime 时长 / 对外 SLA 影响]

#### 2. 时间线重建 (Timeline Reconstruction)
| Time (UTC/Local) | Event | Source | Action Taken |
|---|---|---|---|
| [HH:MM] | 故障潜伏/变更触发 | [如 CI/CD] | [发布 V2.0] |
| [HH:MM] | 告警触发/发现异常 | [如 Grafana] | [错误率飙升至 8.7%] |
| [HH:MM] | 锁定根因 | [人工/Agent] | [确认是新代码逻辑导致的连接泄漏] |
| [HH:MM] | 止血与恢复 | [CI/CD] | [执行回滚，指标恢复正常] |
> **核心指标**: 发现延迟 (Detection lag): [X] 分钟 | 修复时间 (MTTR): [Y] 分钟

#### 3. 根因分析 (Root Cause Analysis - 5 Whys)
- **Problem**: [初始现象，如支付网关宕机]
  - **Why?** [直接原因，如：DB连接池耗尽]
  - **Why?** [深入一步，如：重试逻辑没有正确释放超时连接]
  - **Why?** [再深入，如：新版本的压测在测试环境未暴露出此问题]
  - **Why?** [系统/流程原因，如：测试环境缺乏生产级别的真实长连接模拟]
- **系统性根因**: [总结最后的系统性缺陷]

#### 4. 纠正与预防措施 (Corrective Actions)
*(按控制层级从强到弱排列，符合 SMART 原则)*
- **[系统防护/Engineering]** [如：给连接池增加绝对超时强制回收机制] (Owner: ___ | Due: _____)
- **[自动化检测/Detection]** [如：增加连接池利用率 > 80% 的告警] (Owner: ___ | Due: _____)
- **[流程规范/Administrative]** [如：补充压测 SOP，增加长连接阻断测试] (Owner: ___ | Due: _____)

#### 5. 经验教训 (Lessons Learned)
- 🟢 **What went well****: [做得好的地方，如：回滚机制生效迅速，10分钟内止血]
- 🔴 **What could be improved****: [需要改进的短板，如：监控仅发现了报错，没有提前发现连接池缓慢泄露的趋势]

从 AI 开发流到 E2E AI 测试，再到 AI 排障，我算是为团队跑通了一套全流程的 AI 研发基建。

4. 探索多智能体并发工作流

除了公司的 Cursor，部门老板最近还为我们提供了火山云的 OpenCode (Coding Plan)。为了尝试新的可能性，我没有直接把 superpowers 搬过去。在读到《软件基本功没死，它在 AI 时代变得更值钱了》这篇文章后，我开始在 OpenCode 上实践基于 mattpocock/skills 改造的开发流程：

想法
  ↓
/grill-me [客户需求文档]       -- 与 AI 建立共同的设计概念
  ↓
/to-prd                        -- 将对话转化为目的地文档
  ↓
/to-issues                     -- 切分为垂直曳光弹 Issue（看板）
  ↓
ralph-once.sh / ralph-loop.sh  -- AFK 智能体逐 Issue 实现（TDD）
  ↓
人工 QA + 代码审查              -- 把品味和判断注回代码
  ↓
回到看板                        -- QA 产生新 Issue，循环继续

这个流程相比 superpowers 有个巨大的优势：to-issues 环节会把庞大的需求切分成一个个小的 Issue，并分析它们之间的依赖关系。下一步就可以启动多个 subagent 并发去开发多个 Issue。对于大需求而言，这种开发流不仅更快，而且更可靠，毕竟每个 subagent 只用专注于一个小任务，上下文污染的概率大大降低。

正如那篇文章里提到的感悟，在 AI 时代，我们人类要做的是接口和抽象的设计，内部的实现完全交给 AI，把实现细节当作黑盒。在使用 OpenCode 的过程中，我确实感觉到国产模型在推理能力上相较于 Opus 4.6 还有一定差距（Token 生成速度也稍慢一些），但通过这种极其严密的流程约束和任务拆解，依然能稳定输出不错的结果。

5. 业务实战：多云生命周期的 IaC 与抽象

说完了这些工具和流程上折腾的事情，再来说说我最近在做的具体业务。

目前我们在做一个 CMDB 系统，要实现对云资源的全生命周期管理。这里最大的挑战是要同时对接 4 朵公有云：AWS、阿里云、华为云、金山云。我之前在腾讯蓝鲸的同事做多云管理，搞了一年多还没能把几朵云完全对齐，可见水有多深。而且，我本心并不希望自己只是作为运维的“乙方”去纯做一套死板的平台功能，我希望运维同学能深度参与进来。我来做引擎，运维同学在引擎的基础上扩展能力。

基于这个思路，刚开始就把方案定格在了 IaC（基础设施即代码）上。在 Terraform 和 Pulumi 之间，由于国内云对 Pulumi 支持欠佳（特别是金山云根本不支持），最终选择了 Terraform。

为此，我开发了一个轻量级的执行引擎：tfengine。在产品逻辑上，我要求运维同学自己维护相关资源的 HCL 模板，然后在平台上以表单的形式面向普通用户提供申请。资源创建过程中，平台会完整透传 terraform plan/apply 的日志信息。这样做的好处是，一旦资源申请出问题，运维同学通过日志直接就能排查，而不是遇到报错就来找我们开发定位。

除了资源创建，全生命周期管理中还有很多 Day 2 的操作（比如开关机、升降配等），这些没法用 Terraform 搞定，只能通过各云厂商的 SDK 重新封装。这就引出了两座大山：

平台内部现有的 cloudservice 模块做得太早，抽象极差，甚至账号管理都乱七八糟，简而言之就是一坨屎山。
不同云厂商的模型差异巨大，比如华为云有一个独创的“企业项目 ID”概念，而金山云的 SDK 又经常缺斤少两。

幸运的是，现在我有 AI Agent 这个得力助手。我把这些繁杂的脏活全交给了 Agent：让它去扒不同云厂商的 SDK 源码，读又臭又长的 API 文档，最后帮我糊出了一个非常轻量的封装微服务，我管它叫 cloudkit。

cloudkit 采用了纯插件式架构，新增一个功能就是新增一个插件，插件内部封装好 4 朵云对应的 API 流程。遇到屎山代码？让 Agent 去理清逻辑并隔离出清晰的接口。

最后，在 CMDB 平台上统一调用 tfengine 和 cloudkit，走同一套账号体系进行纳管。这套方案非常灵活，开发极快。目前我们已经顺利实现了云主机和对象存储的全生命周期管理。

回过头看，无论是流程的演进，还是屎山代码的重构，AI 都在以一种不可逆的方式改变着我们的工作模式。从最初的“测试转开发”，到如今的“写规范让 Agent 开发”，我们解决问题的方式一直在变，但作为程序员，那种对系统掌控感和抽象设计的追求，始终如一。

复盘：ClawOps AI Agent

Sat, 07 Mar 2026 12:00:00 +0800

前言

过去的两周，我经历了一次充满激情的开发，也经历了一次彻底的失败。

起因是我准备在内部做一个公共的“运维AI机器人”。我满怀热情地规划了多租户架构、复杂的并发控制、MCP（Model Context Protocol）对接以及各种内部系统的打通。然而，经过两周的爆肝，项目上线没多久就被平台团队勒令下线，而从业务价值来看，老板其实也并不需要这样一个东西。

俗话说，失败是成功之母。虽然项目黄了，但这两周踩过的坑、写过的废代码，都是技术架构演进路上的宝贵经验。我在这里复盘一下整个过程，聊聊我的技术实现、妥协，以及如果让我重新设计，我会怎么做。

1. 雄心勃勃的初始架构

项目初期的定位非常庞大：一个服务于全公司的公共运维Agent平台。为了支撑这个目标，我设计了一套相当复杂的服务端架构。

项目本身基于 PicoClaw。

在这个阶段，我的思维主要停留在“如何用技术解决所有场景的问题”。

多租户与隔离：每个用户拥有独立的Workspace，利用文件系统工具和Shell工具的黑名单机制进行隔离。
高并发的AgentLoop池：为了支持多用户，我设计了一个AgentLoop Worker池。当Inbound Bus收到消息时，自动分配Worker处理；处理完毕后通过Outbound消息池并发调用Channel的发送接口，随后Worker自动回收。
Web Channel的设计：为了让用户能在网页上使用，我做了一个Web Channel。前端通过POST接口发送消息到Inbound Bus，服务端通过SSE（Server-Sent Events）向前端持续推送AI的回复。同时，Tool调用的过程也会产生摘要，通过Hook机制经SSE推送给前端，连会话的Title都是AI自动生成并推送的。
状态与存储：Web会话和消息数据全部落盘MySQL。因为是公共服务，Inbound进入前和Outbound发出后，都需要对接内部认证组件拦截并识别用户，将用户信息注入Message Metadata，最终融合到LLM的System Prompt中。
内部IM（WPS协作）集成：通过WebSocket连接获取内部IM机器人的消息，提取出内部用户信息注入Inbound，再通过平台的发消息API回传给用户。由于共享Metadata，WPS端和Web端可以共用同一个AgentLoop实例和Workspace记忆。

初期架构流转图大概是这样的：

除此之外，我还实现了一个多用户的Cron任务管理服务。系统会遍历每个用户的Workspace，拉起Cron实例。AgentLoop中会记录用户的 last channel，以此决定定时任务的执行结果该推送到Web还是WPS（由于Web没有主动推送能力，还需要做特殊处理屏蔽Web Channel记录）。

2. 核心能力建设与“妥协”

在Agent本体骨架搭好后，下一步就是Skill（技能）的建设。这里我遇到了几个典型的架构决策问题。

WPS 365 MCP的对接与Proxy模式

我们内部使用了WPS 365，它提供了MCP。但是它的MCP使用OAuth2协议，AccessToken只有2小时有效期。如何让AI顺畅调用？我最初的想法是写个Wrapper程序直连数据库刷新Token，但这太不优雅了。最终的妥协方案是：在Web服务上暴露一个WPS MCP Proxy。

调用这个Proxy时携带User ID，Proxy负责去数据库换Token、组装认证请求头，最后转发给WPS。这样一来，AI只需要用普通的 mcptools 配合用户ID就能完成调用。

CMDB对接：CLI vs MCP

在对接内部CMDB平台时，我有了一个洞察：其实MCP并没有那么神圣，面向Agent开发的CLI工具才是未来。因为Agent的Shell Tool结合Skill可以搞定一切CLI的调用，而且极为灵活。

于是我把内部服务直接包成了一个CLI工具给Agent调用，并写了Skill说明文档。但Leader认为，这种能力应该包装成标准的MCP提供给其他生态。

这是一个典型的业务视角与开发视角的冲突。没问题，我把它改成了MCP暴露，但紧接着认证又成了痛点——现阶段做AI工具调用，搞复杂的统一认证太累了，其实最简单的固定Token透传才是效能最高的。

3. 失败的根因与挣扎

项目开发完了，写好了帮助文档，准备大干一场。然后，就迎来了平台团队的审核。

下线。

复盘这个结果，核心死穴在于：Sandbox（沙盒）隔离方案太简陋。

我原本以为，在程序层面做一个Shell命令的黑名单（比如禁用 rm、ssh）就万事大吉了。但我忽略了平台本身网络环境的复杂性。内部平台机器之间的网络是没有严格隔离的。Agent最核心的能力是能够自主编写Skill扩展能力、执行脚本。这意味着无论我怎么在应用层做黑名单，只要Agent能执行Python/Shell，它就能在内网里横冲直撞。要想解决，必须依赖底层平台做深度的容器网络隔离，而这在短时间内根本推不动。

服务端走不通，我不甘心，于是决定转向客户端（桌面版）。

我用Golang的 Wails 框架，花了极短的时间糊了一个和网页端一样的桌面客户端。

Wails甚至能直接Hook之前写的Gin路由。
因为不支持SSE，我把推送机制改造成了Wails自带的Event Bus。
MySQL太重？直接切成SQLite本地存储。
WPS协作只能单实例WebSocket连接？我在服务端保留了一个非常轻量的“消息转发网关”，根据User ID把消息路由到对应打开的客户端上。

技术上走通了，但这次碰到了最终的BOSS——业务价值伪需求。从老板的角度来看，团队并不需要一个新的、复杂的公共Agent平台。能力强的同事早就自己部署了类似的开源项目（比如OpenClaw），而能力稍弱的同事用Cursor就能解决80%的代码和运维问题。

4. 复盘：如果重来，我会怎么设计？

在之前的文章中我提到过，解决问题有不同的思维层次。

我这次的失败，在于我用第一层（用技术解决看到的所有问题）的精力，去挑战了第四层（从组织与平台底座出发看演进）的难题，最终因为基础设施不匹配和伪需求而夭折。

如果让我重新规划这个项目，我绝对不会立项做一个“多租户的企业级公共Agent”。我会将其彻底定位为一个极致轻量化的“个人AI助手（Personal AI Agent）”。

以下是我的重构思路：

1. 抛弃统一认证，拥抱本地配置（Identity）

既然是个人助手，就不要去对接什么内部复杂的SSO认证了。用户的身份定义完全下放。

用户只需要在本地修改自己的 USER.md 文件，明确自己的职责、系统偏好等。对于CMDB这种系统，直接在本地配置里写入私人Token，LLM在调用CLI或MCP时自动拼装读取即可。

2. WPS 365 MCP 授权的本地化改造

不需要服务端的Proxy和数据库。我会开发一个专用的CLI工具。

用户在本地执行CLI生成认证链接，浏览器授权后将Callback的AccessToken及其Refresh Token直接存入本地配置目录（如 ~/.wps/config.json）。之后的Token刷新完全由本地CLI自动完成，Agent直接调用本地工具即可。

3. 极简的Channel消息路由

保留服务端的“消息路由网关”，但不做任何用户认证。

WPS机器人在收到消息后，直接告诉用户他当前的 Chat ID。用户只需在自己本地助手的配置里填入这个 Chat ID。本地助手连上服务端网关的WebSocket，网关只负责无脑地按 Chat ID 转发消息。安全、轻量、解耦。

新的架构图将变得异常清晰且易于维护：

5. 结语

软件开发的过程，本质上是对业务需求进行抽象、提炼并构建逻辑的过程。

这次历时两周的“失败”，虽然没有产出能在公司内部大放异彩的平台产品，但它逼着我理清了Agent在ToB复杂网络下的安全死结，也帮我认清了“大而全的平台”与“小而美的个人工具”之间的边界。

做技术不能一味地追求架构的宏大（什么都想上多租户、Worker池、分布式），最终还是要服务于真实的痛点。现在的个人版架构，虽然看起来像是一个妥协的产物，但它没有了沉重的安全包袱，没有了复杂的数据库依赖，反而能把Agent的核心能力（工具调用、记忆、任务流）发挥到极致。

有时，砍掉一半的需求，反而能得到一个更健壮的架构。这就是我这两周交出的学费。

AI工程落地实践

Wed, 11 Feb 2026 14:00:00 +0800

前几天在整理项目代码的时候，看着 commit log 里那些由 AI 生成的代码，突然有点感慨。以前写代码是体力和脑力的双重劳动，现在好像变成了单纯的脑力博弈——跟 AI 的博弈。

这篇想絮絮叨叨聊一下从传统的开发模式转变为 Vibe Coding 的过程中，我踩过的坑以及现在摸索出来的一套还算顺手的 SOP。

1. 回顾：前AI时代的手工作坊

在那时候，我接一个大需求，流程基本是雷打不动的：

拆解：把大需求掰碎了，变成一个个小任务。
设计：看老代码，定方案。哪里要改，哪里要加，脑子里或者纸上得有个谱。
搬砖：按计划写代码，写单测。
验证：跑通端对端流程。
Code Review：提 PR，等同事挑刺，改代码，合并。

这个过程里，最重要的一步其实往往被忽视，就是复盘。这波开发里学到了什么新模式？引入了什么新坑？怎么避免下次再犯？这种“复利”思维才是工程师成长的关键。

2. Vibe Coding 时代的冲击与适应

进入 AI 时代（或者说 Cursor 时代）后，我一开始也是懵的，试错了很多次，现在的 SOP 变成了这样：

聊需求：先不急着写代码。拉着 ChatGPT 或者 Gemini 开聊。讨论业界怎么做，现在的项目痛点在哪。这一步是为了定方向，最后产出一份靠谱的需求文档。
定计划（feat.md大法）：
- 我会在 Cursor 里建个 feat.md，把需求文档丢进去。
- 在 Cursor 里 @feat.md，让 AI 出 Plan。
- 重点：如果 Plan 太大，我会让它拆。如果 Plan 漏了东西，只要不致命，我先不打断，记在小本本上，等它写完代码再补。
- 有时候 Plan 实在离谱，改动量太大，我会回头改 feat.md，限制它的发挥范围，只做第一阶段。
生成：Plan 只要逻辑通顺，我就让 Cursor 开工。
人工 Review：这一步绝对不能省。我对 AI 的信任度还没到无脑 Merge 的地步，尤其是 E2E 测试覆盖率不够高的时候。我得盯着它生成的代码，脑子里过一遍逻辑。
收尾：测试，合并。

这个流程看着挺顺，但有个大问题：我怎么把“复利”这一环加回来？

之前我看 Spec Driven Development（文档驱动开发），也就是 Speckit 或者 OpenSpec 那一套，试了一下就放弃了。感觉太重了，光是喂给 AI 的上下文就把窗口撑爆了，而且那种从头到尾写文档的感觉，很反直觉，完全没有了快速验证的快感。

直到读到那篇《认知重建：Speckit 用了三个月，我放弃了》，里面提到了复利工程的概念，简直说到我心坎里去了：

Plan ──────→ Work ──────→ Review ──────→ Compound
详细规划     执行工作     质量检查       知识沉淀
   ↑                                       │
   └───────────────────────────────────────┘
            知识复合：下次规划更精准

这不就是我以前手工作坊时代的升级版吗？

3. 在 Cursor 中落地复利工程

理论有了，怎么在 Cursor 里实现？上个月 Cursor 2.4 更新了 SubAgents、Skills 和 Commands，我感觉机会来了。

我先是扒了 everything-claude-code 这个项目，想复刻一套工具链：

Subagent: planner, code-reviewer, doc-updater
Skill: security-review, tdd-workflow
Commands: learn（这个最关键，用于知识沉淀）

理想很丰满，流程应该是 planner -> tdd-guide -> code-reviewer -> learn。

现实很骨感。Cursor 的 SubAgent 经常“自作主张”。你给它编排好了流程，它跑着跑着就切回自己的默认 Plan 模式，或者无视我的 SubAgent 逻辑。那一阵子搞得我很抓狂，感觉在跟一个不听话的实习生较劲。

不过，learn 这个命令我是真留下来了。每次做完需求，把改动总结成知识点存下来，下次 AI 再写代码时，就能读到这些“家规”，确实有用。

4. 最终的折衷方案

不死心的我又去研究了 superpowers 和 code-review-expert 这两个项目，重新调整了策略。

既然 Cursor 对 SubAgent 的调度有自己的想法，那我就顺着它，把流程简化，侧重于前置规划和后置学习。

现在的工具组合变成了：

Skill: brainstorming, writing-plans, executing-plans, test-driven-development, subagent-driven-development, code-review-expert, using-superpowers
Commands: learn (雷打不动)

流程图大概是这样：

brainstorming ──→ writing-plans ──→ executing-plans ──┬──→ test-driven-development
                                                      └──→ code-review-expert ──→ learn

为了适配 Cursor，我把 Claude Code 定义的工具名都改了一遍，还在 Prompt 里强制要求它必须明确调用哪个 Skill。

虽然现在 Cursor 还是偶尔会丢失上下文，或者写着写着断片了，需要我手动把断掉的节点接起来，但整体上，这套流程已经能复刻我以前的工作流了。

总结：

不管 AI 工具有多强，它终究是个工具。不要被工具牵着鼻子走，也不要为了用 AI 而用 AI。

我觉得核心还是要把人的经验沉淀下来。以前我们沉淀在脑子里、Wiki 里，现在我们通过 learn 命令沉淀在本地文档里。

AI 可以帮我们把 Plan -> Work 这一段做得飞快，但 Review -> Compound 这一段，目前还得靠我们自己把关。只有把这个闭环跑通了，才算真正把 AI 用成了自己的副驾驶，而不是请了个随时会跑路的外包。

我的2025

Sun, 04 Jan 2026 10:00:00 +0800

今天是2026年的第一个周日，窗外是珠海特有的温润海风。这一年，我从深圳到珠海，从一家迷茫的小公司到了老牌的金山办公。如果说2024年是本命年的阵痛，那么2025年对我来说，更像是在这激荡的技术浪潮中，努力寻找平衡与自洽的一年。

依然按照惯例，絮絮叨叨地复盘下我的2025吧。

行云创新：及时止损的教训

2025年的开头，我还在行云创新做云原生产品。当时做的是基于 K8s 的在线云 IDE，技术方案其实挺有意思：用 K8s 调度启动在线编辑器，用 code-server 和 selkies 暴露桌面 IDE，甚至还研究了 Docker Windows 容器。为了解决文件同步，我设计了 Sidecar 模式的文件服务，负责上传变更、初始化 git 目录这些活儿。

技术上虽然有成就感，但职场环境却让我第一次深刻体会到“庙小妖风大”。

先是内部莫名其妙的同事纠纷，随后是让人窒息的“服从性测试”。有一次我下班刚到家，就被领导一个电话叫回去值守，其实压根不是我的问题。最崩坏的是关于技术方向的讨论，领导要求我周末加班，把已经验证通过的方案改回到之前被废弃的死路上。我坚持了专业意见，并坦言周末搞不定，结果就是失去了所谓的“信任”。

在小公司，当领导不信任你，却又指望你干活时，事情会变得极其扭曲。他们开始通过能力欠缺的测试同学来传达意见。说实话，和理解能力、沟通能力都不在一个频次的人合作，真的非常痛苦。加上 2B 产品那种“为了投标乱堆定制功能”的短视，我意识到这里看不到未来。

教训很简单：不要对小公司抱有幻觉，更不要在让自己难受的环境里硬磨。 庆幸的是，年底和前同事聊天，发现我走后那里果然陷入了无意义的压榨。及时抽身，是我今年做的最正确的决定之一。

找工作：不匹配就是不匹配

2月过完年，我重新回到了 Boss 直聘的战场。明显的感受是，互联网的盛况确实不再了，坑位少了很多。

期间也面了一些不错的地方。比如一家做家具电商的新加坡公司，离家近，JD 也匹配。结果面试时考缓存一致性，我竟然脑子短路卡壳了，哈哈。还有影石360，面到了三轮，最后败在一道我没刷过的动态规划算法题上。

其实面多了就想通了：面试不过，本质上就是不匹配。 不擅长手写算法是我一直以来的短板，而很多岗位需要的也不是我这种偏工程和架构的背景。最后，我投了广州的唯品会和珠海的金山办公。唯品会方向没对上，而金山办公这边，经过5轮面试定级P7，我重新回到了 SRE 的老本行。

金山办公：双城生活与新的大腿

6月入职金山，刚进去就遇到了一出“大厂政治剧”。我的直接领导是一位从腾讯过来的高P总监，本以为抱到了“鹅厂老乡”的大腿，结果他入职半个月、试用期快过的时候突然离职了。原因是外来的高P动了老员工的利益，被“兄弟文化”排挤。

那一刻我真的很迷茫，简历这两年已经有点花了，要是这儿也待不住怎么办？好在新的 leader 就位后，我渐渐稳住了阵脚。我抛开了之前的屎山代码，开始在组内推广我推崇的“整洁架构”。

现在的状态是，我手下带了2个人，还跨地域带了武汉的2个同事。我把更多精力放在了架构约束上：制定项目规范、拆解需求、帮同事解决技术卡点，努力不让项目走向不可控的混乱。

最明显的变化是生活节奏。金山是真的不加班，早9晚6，非常养人。但我开启了“双城模式”：周一早起驱车去珠海，周五晚回深圳。对家人有愧疚，但下班后大把的独处时间，也让我看了不少以前没空看的电影，算是一种孤独的补偿吧。

Vibe Coding：AI 时代的生存法则

今年我最大的技术冲击来自于 AI。半年多前公司配了 Cursor，我正式开启了 Vibe Coding 模式。现在的流程是：我负责思考方案，写好文档，然后跟 AI 讨论可行性。

我的工具链目前是这样的：

Google AI Studio (Gemini 3 Pro)：负责宏观架构，它上下文大，适合讨论长篇的实施计划。
Cursor (Claude Sonnet 4.5)：负责写代码，又快又好。
GPT-5.1 Codex High：负责 Review，它能抓到很多我忽略的边界细节。

读代码也有了神器，deepwiki.com 理解大框架，gitingest.com 配合 Gemini 3 Pro 读仓库源码。在 Vibe Coding 时代，我发现程序员的“品味”变得空前重要。AI 会发散，如果没有严格的架构约束和清晰的规范，AI 产出的代码大概率也是一堆难以维护的屎山。

开源与折腾

有了闲暇时间，开源项目也搞得风生水起。

Pingsix：写了20多个插件，被 GPT-5.1 捉了十几个虫，解锁了Ingress Controller。
Bookmark：趁着 Pocket 关闭，我把老书签整理了，顺便用 AI 做了自动化总结。
NAS：家里的 RK3399 还在服役，换了 SSD，折腾了联通 IPv6。现在结合夸克网盘和 TG 机器人，追剧已经成了全自动的享受。

甚至我还精简了银行卡，把一堆乱七八糟的卡消了。现在主刷农行精粹白和工行香格里拉白。理财归微众，工资归招行，生活变得简单了不少。

结尾

2025年，我在珠海的夕阳里思考过职业危机，也在双城的高速上想念过家人。虽然简历看上去不再那么“大厂精英”，但我对编程的热爱反而因为 AI 的介入变得更纯粹了——我不再纠结于繁琐的语法，而是更专注于解决问题本身。

未来依然不确定，但就像我折腾 OpenWrt 拨号一样，掉线了就重新拨号，断路了就换个方案。只要逻辑还在，系统总能 Run 起来。

再见，2025。你好，2026。

AI Agent 工程化实践：从 Prompt 到 Context 的思维转变

Sun, 30 Nov 2025 10:00:00 +0800

最近在新公司这边，大部分精力都耗在了 AI Agent 的落地应用上。大家都在谈 Agent，网上的 Demo 也是满天飞，但当你真正把这玩意儿往生产环境搬的时候，会发现完全是两码事。

简单的说，AI Agent 的核心逻辑其实并不复杂，本质上就是一个基于 ReAct（Reasoning and Acting）范式的工程结构，程序在一个死循环里不断地调用 LLM 的 API，让它根据当前的观测去决策下一步是思考还是行动。

起初我也觉得这就跟写个脚本差不多，但在实际调试过程中，我发现让 Agent “跑通”不难，但要让它“跑好”、“省钱”且“不犯蠢”，这里面全是工程细节。我也复盘了一下这段时间的踩坑经历，总结了一些在工程实践中的“巧思”。

遇到的瓶颈

在项目初期，我碰到的最大痛点就是 Token 的消耗 和 上下文窗口（Context Window）的限制。

Agent 运行起来后，为了保证它能记住之前的操作，我们往往会把历史对话一股脑地塞进 Prompt 里。但随着交互轮数的增加，上下文会迅速膨胀。这不仅烧钱（Token 费很贵），更要命的是，当无关信息太多时，LLM 的注意力会被稀释，导致它开始“幻觉”或者逻辑混乱，也就是我们常说的“变笨了”。

为了解决这个问题，我开始从工程角度去干预 Agent 的记忆机制，我发现单纯的 Prompt Engineering 已经不够用了，我们需要进阶到 Context Engineering（上下文工程）。

几个工程化的巧思

针对上下文过载和执行效率低的问题，我在工程实践中尝试了以下几个优化策略，效果还不错：

1. 动态整理与压缩上下文

这招主要是应对“记不住”的问题。当对话轮数逼近模型的 Context 上限时，如果直接截断最早的记录，Agent 可能会丢失关键的任务背景。

我的做法是，在检测到 Token 数快到阈值时，触发一个后台任务，让 LLM 自己对之前的多轮对话做一个动态整理（Summary）。

输入：过去 N 轮的详细对话。
输出：提取出“用户的核心诉求”、“已完成的关键步骤”和“当前获得的中间结果”。

用这段高密度的摘要替换掉那 N 轮冗长的对话。这样既大幅减少了 Token 量，又确保了历史关键信息得以保存，让 Agent 始终记得“我是谁，我在哪，我要干什么”。

2. Checkpoint 回溯与有效信息保留

Agent 在尝试调用工具时，并不总是成功的。有时候它参数传错了，有时候 API 报错了。在标准的 ReAct 循环里，这些报错信息（Error Logs）会被完整地记录在上下文里。

这就导致一个问题：如果 Agent 试错了好几次才成功，那上下文里会充斥着大量的垃圾报错信息。这些信息对于后续的决策不仅无用，反而可能误导模型。

这里我引入了一个类似游戏存档的 Checkpoint（检查点） 机制。

在执行关键动作前，系统会自动保存当前的上下文快照。
当检测到 Agent 陷入死循环或产生大量无效交互时，系统会强制回滚到上一个 Checkpoint。
关键点：回溯不是简单的“读档重来”，我们会通过规则提取出刚才试错过程中产生的“有效信息”（比如“某个参数验证失败”的结论），将其注入到回溯后的上下文中。

这样既清洗了上下文中的噪音，又保留了试错的价值，避免 Agent 在同一个坑里跌倒两次。

3. Sub Agent 解决上下文隔离

在某些场景下，Agent 需要执行非常复杂的子任务，比如写一段 Python 代码并执行，或者进行复杂的数据清洗。

如果把这些子任务的所有中间步骤都塞进主线程的上下文（Main Context），瞬间就会把 Token 撑爆。我的解决思路是引入 Sub Agent（子智能体）：

把复杂任务分发给一个独立的 Sub Agent。
Sub Agent 拥有独立的上下文空间，它可以在里面进行多轮的思考、调试、修正。
当 Sub Agent 任务完成后，只提取“最终结果”返回给主 Agent。

通过这种方式，我们实现了上下文的物理隔离，主 Agent 的视野始终保持清爽，只关注宏观流程，而细节则由 Sub Agent 屏蔽。

4. 面向“人”设计工具，而非面向 API

这一点是我觉得思维层次提升最大的地方。

最初给 Agent 设计工具时，我习惯直接把后端的原子 API 扔给它，比如 login(), get_token(), get_user_info()。结果就是 Agent 完成一个简单的查用户信息，需要来回跑三趟。

后来我意识到，Agent 使用工具的逻辑应该更像“人”使用 app。工具的设计粒度应该更粗。我们将多个原子 API 组合封装成一个面向业务场景的高阶工具。这样一次调用就能搞定，减少了 Agent 的交互流程，容错率也大大提升。

总结：从 Prompt 到 Context

回顾这些优化点，我们可以发现，提升 Agent 能力的关键，不仅仅在于你 Prompt 写得有多花哨，更在于你如何管理它所能看到的“世界”。

让我们来总结下这里的思维层次：

第一层（Prompt Engineering）：专注于怎么把 Prompt 词写好，试图用一段话把所有要求都告诉 AI。
第二层（RAG / Memory）：开始给 AI 外挂数据库，解决知识库的问题。
第三层（Context Engineering）：把上下文看作一种稀缺的计算资源，通过动态压缩、Checkpoint 回溯、Sub Agent 隔离等工程手段，动态地管理 AI 的注意力。
第四层（Architecture Design）：从单点优化走向系统设计，构建一套具备自我纠错、状态管理、分层协作的智能体运行时环境。

以前做传统开发，我们优化的是 CPU 和内存；现在做 AI 开发，我们优化的其实是 Context Window 和 Token 效率。

在这个技术日新月异的时代，作为程序员，我们不仅要会写代码，更要学会如何设计系统来弥补模型的短板。这些关于 Context 的巧思，其实就是把复杂的非结构化问题，通过工程手段变得有序化的过程。

希望这些瞎絮叨的经验能对正在折腾 Agent 的你有那么一点点启发。2025 年了，保持学习，保持思考，依然是应对变化的唯一解法。

系统性思维的陷阱：从“完美方案”到“有效落地”

Fri, 21 Nov 2025 10:00:52 +0800

我做程序员已经 10 多年了。

回想刚入行那会儿，我的思维模式很简单：产品经理提什么，我就做什么。那时候追求的是“短平快”，像个执行指令的机器，代码写得快就是牛。

后来加入了腾讯，随着职级的提升，负责的系统越来越复杂，我开始意识到：写代码只是冰山一角，做方案才是真正的考验。

所谓的“系统性思维”，一度让我受益匪浅，但最近我发现，如果一旦陷入对“完美”的执念，系统性思维反而会成为阻碍项目落地的最大陷阱。今天想和大家聊聊，如何在架构设计、风险控制和实际落地之间找到那个微妙的平衡点。

方案的本质：平衡客观条件的艺术

什么是做方案？以前我觉得是画一张最漂亮的架构图，用最牛的组件。现在我理解，做方案其实是把各种“客观条件”作为输入，寻找最优解的过程。

这些客观条件包括：

硬件资源：手头有多少服务器？
依赖组件：公司基建支持什么？（比如你想用 ClickHouse，但公司运维没经验，出了问题没人兜底，那这就不是一个好选项，不如看看现有组件能不能替代。）
人力成本：团队几个人？水平如何？
时间窗口：业务等得起多久？

我见过很多“完美”的方案，逻辑自洽，架构优雅，但落地需要半年。而另一个方案虽然略显粗糙，但只需要 1 个月，且预留了后续演进的空间。在商业世界里，后者往往才是胜者。

架构不是设计出来的，是演进出来的。 我们需要做的是调整各种客观条件的优先级，在风险可控的前提下，通过多方评审（集思广益，消除盲区），找到那个平衡点。

实战案例：只解决 80% 的问题

分享一个我在腾讯做权限中心时的真实案例。

当时我们面临一个痛点：有一个中心化的管理员，每天大量时间都在处理审批单，他一直在吐槽，希望把这些审批自动路由到对应的业务负责人，别全堆在他头上。

我第一反应是：做不到。

从技术角度看，审批范围是一个复杂的表达式。要根据用户申请的数据去匹配这个表达式，没法直接做数据库索引。如果要实现，就得全表扫描进行遍历匹配，性能扛不住。而且，很多申请范围很模糊，根本匹配不到具体负责人，最后还是得兜底回落到管理员那里。

于是这个需求被我挡回去了。后来问题太严重，捅到了上面。在复盘会上，我的 Leader 问了一句话，让我瞬间顿悟：

“能不能在只解决 80% 问题的前提下，来做这个方案？”

我突然意识到，我陷入了“完美主义”的陷阱。我一直在纠结那 20% 匹配不到的情况，却忽略了如果能自动化处理掉 80% 的单子，管理员的工作量就能大大减轻。

于是我重新设计了方案：

引入前置索引：提取表达式中的关键特征做索引。
允许降级：能走索引匹配的先走索引，匹配不到的（那复杂的 20%），直接回退给中心管理员。

事实证明，方案落地后，管理员的压力骤减。这就告诉我：有时候真的没有完美的方案，只有平衡现状的方案。

开源代码的“神话”与重构

在阅读优秀开源项目代码时，我常有这种时刻：“哇塞，这代码写得太神了，连这种极端场景都想到了，作者是开了天眼吗？”

随着我自己经验的增长，我发现所谓的“神人”并没有那么玄乎。

他能考虑到那个场景，很可能只是因为他踩过那个坑。

版本 1.0 可能是个草台班子。
版本 2.0 修复了几个致命 Bug（踩坑）。
版本 3.0 因为补丁打多了，代码太烂，被迫重构，把之前的坑变成了新的设计约束。

我在腾讯的 6 年里，权限中心整体重构过 3 次，API 网关也重构过 3 次。每一次重构，都是因为旧的方案无法适应新的客观条件。

踩坑并不是坏事，失败也是财富。 那些让你绞尽脑汁都想不到的 Edge Case，往往是别人血淋淋的经验积累。我们在做方案时，不要怕现在的方案未来会被推翻，只要预留了演进空间，现在的“不完美”就是未来能力的基石。

警惕“过度系统化”的僵局

我现在所在的公司，领导层是运维出身。运维思维和研发思维有一个本质的区别：运维天然厌恶风险（Risk Averse），而研发需要管理风险。

这就导致了一个尴尬的局面：我提出了方案 A 来解决问题 A，但在评审会上，领导会挑战：“你这个方案没有解决问题 B 怎么办？有没有风险？”

于是，技术评审会变成了“挑刺大会”。

为了应对领导的挑刺，我们被迫把方案搞得越来越复杂，试图覆盖所有角落。
方案一复杂，落地难度就指数级上升。
最终结果是：动作变形，无法落地，不了了之。

组内甚至有同事因为方案迟迟推不动，最后无奈活水走人。

这种过度系统化的思考方式，实际上是一种停滞。领导当然需要系统性思考，但如果一直纠结于“一步到位”的完美方案，就会导致方案根本不具备可行性。

我的应对策略：最小化闭环

面对这种环境，如果硬刚，很容易陷入内耗。我的应对方法是：MVP（Minimum Viable Product）策略 + 工具提效。

把方案切得足够小：不要试图画一张大饼，而是聚焦当前最核心的痛点。
快速跑通 PoC（概念验证）：与其在会议室争论风险，不如直接把代码跑起来，让领导看到可视化的成果。
利用 AI 提效：为了不让自己太累，我现在大量使用 AI 编程工具。它可以帮我快速生成原型代码，大大缩短从“想法”到“演示”的时间。

虽然这样做确实会累一点（因为要先斩后奏，自己承担一部分验证成本），但在“不做不错”和“艰难推进”之间，我选择后者。

写在最后

系统性思维是好东西，它让我们思考得更全面。但我们不能让系统性思维成为阻碍系统发展的借口。

做方案，本质上是在不确定性中寻找确定性。

既要有思维高度，也要有“先解决当下问题”的务实态度。不要害怕方案不完美，只要控制好风险，让系统转起来，剩下的，交给时间去演进。

pingsix-ingress-controller启动

Mon, 20 Oct 2025 10:00:52 +0800

https://github.com/zhu327/pingsix

PingSIX 自从上次重构之后, 我一直在考虑如何扩展这个项目的功能与使用场景, 有2个方向可以考虑:

支持proxy-wasm插件
实现pingsix-ingress-controller

在调研了proxy-wasm的相关功能后, 结论是由于pingora面向的场景是CDN的反向代理, 所以没有考虑过方便的修改请求体与响应体, 这就造成很难基于pingora来实现proxy-wasm的ABI, 如果我要自己定义一个wasm的接口协议, 没法复用社区现有的proxy-wasm插件, 那就没必要了, 不如直接写Rust的插件. 相关参考内容:

在放弃了proxy-wasm的支持后, 我开始调研如何实现pingsix-ingress-controller, 由于pingsix的的资源定义是参考apisix来实现的, 所以就直接参考apisix-ingress-controller来实现我们自己的pingsix-ingress-controller.

1. apisix-ingress-controller架构

1. K8s Resources Watch Layer (资源监听层)

各种Controller通过Kubernetes的Watch机制监听对应的资源变化
支持的资源类型包括：
- Gateway API: HTTPRoute, Gateway, GRPCRoute, TCPRoute, UDPRoute, TLSRoute
- Kubernetes原生: Ingress, IngressClass
- APISIX CRD: ApisixRoute, ApisixGlobalRule, ApisixTls, ApisixConsumer, ApisixUpstream
- 自定义: Consumer, GatewayProxy

2. Provider Layer (提供者层)

Provider接收Controller的Update/Delete请求
TranslateContext收集所有依赖资源（Services, Secrets, EndpointSlices等）
为Translator提供完整的上下文信息

3. Translator Layer (翻译层)

将K8s资源翻译成ADC资源描述
每种资源类型都有对应的Translator方法
输出TranslateResult，包含：
- Services (路由规则)
- SSL/TLS (证书)
- Consumers (消费者)
- GlobalRules (全局规则)
- PluginMetadata (插件元数据)

4. ADC Client Layer (ADC客户端层)

ConfigManager: 管理多个GatewayProxy的配置
Store/MemDB: 内存数据库，存储ADC资源状态
StoreDelta: 对比新旧配置，计算差异
将变更任务传递给Executor执行

5. ADC Executor Interface (执行器接口)

ADC Executor提供统一的Execute接口，支持三种实现：

HTTPADCExecutor: 通过HTTP调用ADC Server（推荐方式）
DefaultADCExecutor: 通过命令行调用adc命令

6. ADC HTTP Server (ADC HTTP服务器)

ADC HTTP Server的核心流程：

接收/sync端点的PUT请求
解析ADCServerRequest（包含opts和config）
根据label-selector从APISIX拉取现有资源
将ADC资源描述转换为APISIX资源格式
对比已拉取的资源，计算差异（Diff）
调用APISIX Admin API执行创建/更新/删除操作
返回SyncResult（包含成功/失败状态）

7. APISIX Data Plane (APISIX数据平面)

最终在APISIX中创建/更新/删除的资源：

Routes (路由)
Services (服务)
Upstreams (上游)
SSL/TLS (证书)
Consumers (消费者)
Global Rules (全局规则)
Plugin Metadata (插件元数据)

8. 核心特性

多GatewayProxy支持: 通过ConfigManager管理多个APISIX实例的配置
Label Selector: 支持通过标签选择器过滤资源
增量同步: 通过MemDB对比差异，只同步变更的资源
错误处理: 完善的错误收集和状态更新机制
灵活的执行方式: 支持HTTP、命令行多种执行模式
资源隔离: 通过label实现不同资源的隔离和管理

2. apisix-ingress-controller的经验

虽然以前也写过一些operator的代码, 但是在学习apisix-ingress-controller代码的过程中, 我还是学到了一些新的东西, 在controller watch一类资源的时候, 我们可以watch所有关联的资源类型, 一旦这些关联的资源类型有变更, 就可以进入统一的变更流程, 这样就减少了我们写controller的逻辑复杂度, 所有的关联资源的变更都会触发主资源的更新.

// SetupWithManager sets up the controller with the Manager.
func (r *IngressReconciler) SetupWithManager(mgr ctrl.Manager) error {
	r.genericEvent = make(chan event.GenericEvent, 100)

	return ctrl.NewControllerManagedBy(mgr).
		For(&networkingv1.Ingress{},
			builder.WithPredicates(
				MatchesIngressClassPredicate(r.Client, r.Log),
			),
		).
		WithEventFilter(
			predicate.Or(
				predicate.GenerationChangedPredicate{},
				predicate.AnnotationChangedPredicate{},
				predicate.NewPredicateFuncs(TypePredicate[*corev1.Secret]()),
			),
		).
		Watches(
			&networkingv1.IngressClass{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressForIngressClass),
			builder.WithPredicates(
				predicate.NewPredicateFuncs(r.matchesIngressController),
			),
		).
		Watches(
			&discoveryv1.EndpointSlice{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesByService),
		).
		Watches(
			&corev1.Secret{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesBySecret),
		).
		Watches(&v1alpha1.BackendTrafficPolicy{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressForBackendTrafficPolicy),
			builder.WithPredicates(
				BackendTrafficPolicyPredicateFunc(r.genericEvent),
			),
		).
		Watches(&v1alpha1.HTTPRoutePolicy{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesByHTTPRoutePolicy),
			builder.WithPredicates(httpRoutePolicyPredicateFuncs(r.genericEvent)),
		).
		Watches(&v1alpha1.GatewayProxy{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesForGatewayProxy),
		).
		WatchesRawSource(
			source.Channel(
				r.genericEvent,
				handler.EnqueueRequestsFromMapFunc(r.listIngressForGenericEvent),
			),
		).
		Complete(r)
}

IngressReconciler Watch 事件详解

根据代码分析，IngressReconciler 在 SetupWithManager 方法中配置了多个 watch 事件。让我为您详细解释每个事件的作用和逻辑：

1. 主资源 Watch - Ingress (第70-81行)

For(&networkingv1.Ingress{}, builder.WithPredicates(
    MatchesIngressClassPredicate(r.Client, r.Log),
))

作用：监听 Ingress 资源本身的变化

Predicates（过滤条件）：

MatchesIngressClassPredicate: 只处理由当前控制器管理的 IngressClass 的 Ingress
GenerationChangedPredicate: 资源的 Generation 发生变化（spec 修改）
AnnotationChangedPredicate: 注解发生变化
TypePredicate[*corev1.Secret](): 用于 Secret 类型判断

逻辑：这是主要的监听对象，当 Ingress 的规格或注解变化时触发 Reconcile

2. IngressClass Watch (第82-88行)

Watches(
    &networkingv1.IngressClass{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressForIngressClass),
    builder.WithPredicates(
        predicate.NewPredicateFuncs(r.matchesIngressController),
    ),
)

作用：监听 IngressClass 资源的变化

触发条件：

matchesIngressController: 只监听由当前控制器管理的 IngressClass（通过 spec.controller 字段匹配）

逻辑 (listIngressForIngressClass)：

检查 IngressClass 是否是默认类（通过注解 ingressclass.kubernetes.io/is-default-class）
如果是默认类：列出所有未指定 IngressClassName 或指定为该类的 Ingress
如果不是默认类：通过索引查找使用该 IngressClass 的所有 Ingress
返回需要 reconcile 的 Ingress 列表

使用场景：当 IngressClass 的配置变化时，需要重新处理所有使用该类的 Ingress

3. EndpointSlice Watch (第89-92行)

Watches(
    &discoveryv1.EndpointSlice{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesByService),
)

作用：监听后端服务的 Endpoint 变化

逻辑 (listIngressesByService)：

从 EndpointSlice 的 label 中提取 Service 名称（discovery.k8s.io/service-name）
通过索引 ServiceIndexRef 查找引用该 Service 的所有 Ingress
过滤出由当前控制器管理的 Ingress
返回需要 reconcile 的 Ingress 列表

使用场景：当后端 Pod 的 IP 地址变化（扩缩容、重启等）时，需要更新 APISIX 的 upstream 配置

4. Secret Watch (第93-96行)

Watches(
    &corev1.Secret{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesBySecret),
)

作用：监听 TLS 证书 Secret 的变化

逻辑 (listIngressesBySecret)：

通过索引 SecretIndexRef 查找直接引用该 Secret 的 Ingress（TLS 配置）
查找引用该 Secret 的 GatewayProxy（用于 provider 认证）
如果 GatewayProxy 引用了该 Secret，找到使用该 GatewayProxy 的 IngressClass
再找到使用这些 IngressClass 的所有 Ingress
去重后返回所有需要 reconcile 的 Ingress

使用场景：

TLS 证书更新或轮换
GatewayProxy 的 AdminKey Secret 变化

5. BackendTrafficPolicy Watch (第97-102行)

Watches(&v1alpha1.BackendTrafficPolicy{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressForBackendTrafficPolicy),
    builder.WithPredicates(
        BackendTrafficPolicyPredicateFunc(r.genericEvent),
    ),
)

作用：监听后端流量策略的变化

Predicates 逻辑：

Create: 返回 true，新建时触发
Delete: 返回 true，删除时触发
Update: 检测 targetRefs 的变化
- 找出被移除的 targetRefs
- 将包含被移除 targetRefs 的旧对象发送到 genericEvent channel
- 这样可以清理不再被引用的资源

逻辑 (listIngressForBackendTrafficPolicy)：

遍历 Policy 的所有 targetRefs（引用的 Service）
通过索引查找使用这些 Service 的 Ingress
去重后返回需要 reconcile 的 Ingress 列表

使用场景：配置后端流量策略（如负载均衡算法、健康检查等）

6. HTTPRoutePolicy Watch (第103-106行)

Watches(&v1alpha1.HTTPRoutePolicy{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesByHTTPRoutePolicy),
    builder.WithPredicates(httpRoutePolicyPredicateFuncs(r.genericEvent)),
)

作用：监听 HTTP 路由策略的变化

Predicates 逻辑：

Create/Delete: 返回 true
Update: 检测 targetRefs 的变化
- 找出被移除的 targetRefs
- 将包含被移除 targetRefs 的旧对象发送到 genericEvent channel

逻辑 (listIngressesByHTTPRoutePolicy)：

遍历 Policy 的所有 targetRefs
过滤出 Kind 为 Ingress 的引用
获取这些 Ingress 对象
返回需要 reconcile 的 Ingress 列表

使用场景：配置 HTTP 路由级别的策略（如重写、重定向、超时等）

7. GatewayProxy Watch (第107-109行)

Watches(&v1alpha1.GatewayProxy{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesForGatewayProxy),
)

作用：监听 GatewayProxy 配置的变化

逻辑 (listIngressesForGatewayProxy -> listIngressClassRequestsForGatewayProxy)：

通过索引 IngressClassParametersRef 查找引用该 GatewayProxy 的 IngressClass
对每个 IngressClass，调用 listIngressForIngressClass 获取相关 Ingress
去重后返回所有需要 reconcile 的 Ingress

使用场景：

GatewayProxy 的 APISIX 地址变化
发布服务配置变化
Provider 配置变化

8. Generic Event Channel (第110-116行)

WatchesRawSource(
    source.Channel(
        r.genericEvent,
        handler.EnqueueRequestsFromMapFunc(r.listIngressForGenericEvent),
    ),
)

作用：处理通过 channel 发送的自定义事件

逻辑 (listIngressForGenericEvent)：

根据对象类型路由到相应的处理函数：
- BackendTrafficPolicy -> listIngressForBackendTrafficPolicy
- HTTPRoutePolicy -> listIngressesByHTTPRoutePolicy

使用场景：

处理 Policy 的 targetRefs 被移除时的清理工作
确保当资源不再被引用时，能正确更新相关配置

整体工作流程

1. 事件触发 → 2. Predicate 过滤 → 3. MapFunc 映射 → 4. Reconcile 队列 → 5. Reconcile 执行

Reconcile 主要步骤：

获取 Ingress 对象：如果不存在则执行删除逻辑
查找 IngressClass：确定配置来源
处理 IngressClass Parameters：加载 GatewayProxy 配置
处理 TLS：加载证书 Secret
处理 Backends：加载 Service 和 EndpointSlice
处理 HTTPRoutePolicy：应用路由策略
处理 BackendTrafficPolicy：应用后端流量策略
更新 APISIX 配置：通过 Provider 同步到 APISIX
更新状态：更新 Ingress 和相关资源的状态

关键设计特点

索引优化：使用 Field Indexer 快速查找资源关系
级联更新：依赖资源变化时自动触发主资源更新
去重机制：避免重复处理同一个 Ingress
事件通道：使用 genericEvent channel 处理复杂的清理场景
条件过滤：通过 Predicate 减少不必要的 Reconcile

indexer性能优化

可以看到在上面的watch逻辑中有很多的list操作, 比如listIngressForBackendTrafficPolicy, 这个时候就需要事先在k8s client的indexer中建立索引来优化查询速度, 避免list全扫数据:

func setupIngressIndexer(mgr ctrl.Manager) error {
	// create IngressClass index
	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		IngressClassRef,
		IngressClassRefIndexFunc,
	); err != nil {
		return err
	}

	// create Service index for quick lookup of Ingresses using specific services
	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		ServiceIndexRef,
		IngressServiceIndexFunc,
	); err != nil {
		return err
	}

	// create secret index for TLS
	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		SecretIndexRef,
		IngressSecretIndexFunc,
	); err != nil {
		return err
	}

	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		TLSHostIndexRef,
		IngressTLSHostIndexFunc,
	); err != nil {
		return err
	}

	return nil
}

📊 索引概览表

索引名称	索引字段	索引函数	主要用途
IngressClassRef	`ingressClassRef`	`IngressClassRefIndexFunc`	根据 IngressClass 查找 Ingress
ServiceIndexRef	`serviceRefs`	`IngressServiceIndexFunc`	根据后端 Service 查找 Ingress
SecretIndexRef	`secretRefs`	`IngressSecretIndexFunc`	根据 TLS Secret 查找 Ingress
TLSHostIndexRef	`tlsHostRefs`	`IngressTLSHostIndexFunc`	根据 TLS 主机名查找 Ingress

Ingress 的 4 个索引形成了一个完整的查询体系：

IngressClassRef：管理层面 - 按控制器分组
ServiceIndexRef：数据平面 - 后端服务关联
SecretIndexRef：安全层面 - TLS 证书管理
TLSHostIndexRef：域名层面 - SSL 配置管理

这些索引确保了当任何依赖资源变化时，控制器都能快速、准确地找到需要更新的 Ingress，实现高效的级联更新和实时配置同步。

3. pingsix-ingress-controller架构决策

从apisix-ingress-controller的架构中, 我们知道apisix抽象了一种ADC(API Declarative CLI)的资源类型用来在ingress与apisix资源之间作为中间的桥梁, 如果直接使用apisix-ingress-controller来对接pingsix的话, 就需要pingsix完整的实现apisix的admin api, 并且还需要在使用时启动etcd.

在我的印象中曾经看到过apisix-ingress-controller实现过一个不需要etcd的方案:

Embrace the Lightweight APISIX Ingress Controller Without etcd Dependency

然后我在apisix-ingress-controller 1.8.x 版本的代码下找到了这个这个实现方式, 只是当前的 2.0.x 版本在引入了ADC相关的功能后去掉了etcd-adapter, 那我在考虑实现我的pingsix-ingress-controller时, 为了避免直接改动pingsix的代码, 并且也不希望在ingress启动时依赖etcd, 所以决定重新引入etcd-adapter, 然后为了后续pingsix-ingress-controller能同步apisix-ingress-controller的上游更新, 我决定在现有的ADC Executor的接口的基础上, 实现pingsix的Executor, 这样就可以在避免直接修改apisix的逻辑代码, 使用一种adapter的方式来实现我们自己的pingsix-ingress-controller.

可以看到我们实现的这个Executor, 其实就是重复了一遍ADC http serve的逻辑, 但是最终资源的数据是写入到etcd-adapter中的, 我们实现了一个apisix-ingress-controller最底层的抽象, 通过这种低成本的改造我们后续还可以继续同步apisix-ingress-controller的变更, 并不会造成代码冲突.

总结

在实现pingsix-ingress-controller的过程中, 我完整的阅读了apisix-ingress-controller的代码, 收获了一些写operator的技巧, 然后在分析现有apisix-ingress-controller的代码架构时, 决定通过扩展ADC Executor的实现来实践了面向对象的开闭原则, 对于后续的代码更新合并开了一个好头.

编写可维护的代码 -- 面向AI编程

Thu, 16 Oct 2025 10:00:52 +0800

这是最近在小组内做的一次技术分享的文字稿，总体来说我觉得没有表达出特别硬核的内容，我本身也希望说这次分享不用讲的太硬核，在分享的开头还设计了互动环节，分享的过程中也尝试加入一些问答来互动，奈何现公司的技术氛围确实比较沉闷，似乎同事都比较I，好在最后的问答环节有几个比较好的问题，总体来说还算是一次成功的分享吧，希望自己能输出更多的好内容。

P1: 我们写的代码是写给谁看的?

(🎤 互动环节): “大家有没有过接手一个项目时，看到的第一感觉是：我该从哪下手？结果花了三天才搞明白一个功能的逻辑。有过类似经历的兄弟举个手我看看？”
小说家写小说给读者，建筑师盖房子给业主… 那我们程序员写代码，最终是写给未来的自己，和接手我们代码的同事看的。
代码的可维护性，决定了我们是在“创造价值”还是在“创造负债”。

P2: 举几个代码坏味道的例子?

(🎤 互动环节): “看过《重构》的同学应该都知道代码坏味道。来，大家一起吐槽一下，你在项目里见过最痛苦的代码坏味道是什么？” (引导大家说出几个)
其实按照我朴素的理解，能让我快速理清逻辑的就是好代码，理解起来很费劲的，那肯定就充满坏味道。
正如我在入职后接手的kitam项目，它就充满了这些味道：
- 代码逻辑不内聚：功能实现像天女散花。
- 分层过多且混乱：一个请求要穿越重重关卡。
- 外部依赖离散：数据库、缓存的调用没有统一规范。

P3: 今天分享的主题

今天分享的主题是编写可维护的代码，以及我们可探讨下面向AI编程。
面对代码的坏味道和混乱，我们有什么良药？—— 答案是：一个好的架构。今天我将分享我们kfinops项目中使用的架构：整洁架构 (Clean Architecture)。

P4: 我们的敌人是谁？——是“耦合”这头怪兽！

(🖼️ 视觉元素占位符: 此处放置一张生动的图片，比如一个身上贴满“耦合”标签的小怪兽 🐲)
在深入架构之前，我们先要认清我们真正的敌人：耦合 (Coupling)。
什么是耦合？当你修改代码的一个地方，却意外地导致另一个看似无关的地方也必须修改，甚至直接崩溃时，你就遇到了耦合。
整洁架构的核心目标只有一个：斩断不必要的耦合，为我们的代码建立“防火墙”，控制变更的“爆炸半径”。
接下来，我会通过4个我们都经历过的惨痛问题，来展示整洁架构是如何一步步帮我们驯服这头怪兽的。
(🖼️ 视觉元素占位符: 此处展示完整的整洁架构“洋葱图”，并快速解释四个环：Entities -> Use Cases -> Adapters -> Frameworks)

P5: 问题一：“我只想改个业务规则，为什么还要动数据库和API的代码？”

(🖼️ 视觉元素占位符: 洋葱图高亮最内层的 “Entities” 环)
痛点场景： 你想修改一个实体（比如 User）的业务规则。但在很多项目中，这个实体被定义成了一个“万能Struct”：
```
// user.go
// 它既是业务实体，又是GORM模型，还是HTTP响应体
type User struct {
    ID        uint      `json:"id" gorm:"primaryKey"` // <-- 高亮此行
    Name      string    `json:"name" gorm:"size:255"`
    Points    int       `json:"points"`
    // ...
}
```
- 现在，产品说：为了兼容新App，ID 字段对外要改成 user_id。
- 你只能修改：ID uint \json:“user_id” gorm:“primaryKey”``。
- 问题来了： 你只是在修改一个前端展示字段的名称，却迫使你修改了一个核心业务实体（User）的文件。这就是业务逻辑和展示细节的耦合。
解药：一个纯净的【领域层 Domain Layer】
- 它的唯一职责：建立一个“无菌室”，只存放最核心、最纯粹的业务实体和业务规则。
- kfinops 的实践:
```
// internal/domain/subdomain.go
// 只有业务属性，没有json，gorm等任何技术标签
type SubDomain struct {
    ID         string // 纯粹的业务ID
    FullDomain string
    Status     SubDomainStatus
}
```
- 效果： 业务核心完全稳定。前端/数据库的任何变化，都不会触碰到这个文件。

P6: 问题二：“‘创建子域名’这个功能，代码到底在哪？”

(🖼️ 视觉元素占位符: 洋葱图高亮第二层的 “Use Cases” 环)
(🎤 互动环节): “举个手，谁遇到过想看懂一个功能，结果在IDE里跳了十几个文件的情况？”
痛点场景： 业务流程像天女散花，心智负担极大，你根本找不到一个地方能看清这个功能的“剧本”。这就是业务流程的逻辑离散。

解药：一个清晰的【用例层 Use Case Layer】

它的唯一职责：像一个“导演”，负责编排一个完整的业务故事。一个Use Case就代表系统的一个能力。

kfinops 的实践:

// in internal/usecase/subdomain/service.go
type SubDomainUseCase struct {
    repo repository.SubDomainRepository // 依赖接口
}
func (uc *SubDomainUseCase) CreateSubDomain(...) error {
    // 1. 验证输入 (DTO)                <-- 高亮
    // 2. 创建 Domain 实体             <-- 高亮
    // 3. 调用 Domain 实体业务方法      <-- 高亮
    // 4. 通过【接口】进行持久化          <-- 高亮
    return uc.repo.Save(ctx, domainEntity)
}

效果： 想理解一个功能，只需要看这一个文件。它清晰地讲述了“做什么（What）”，而不关心“怎么做（How）”。

P7: 问题三：“数据库要从MySQL换成MongoDB，完了，项目要重写了！”

(🖼️ 视觉元素占位符: 洋葱图高亮第三层的 “Adapters” 环，并画一个箭头表示依赖反转)
痛点场景： 你的代码里到处都是 gorm.DB.Where(...).Find(...)。你的业务逻辑“知道”你正在使用GORM和MySQL。这就是业务逻辑和数据存储技术的强耦合。
解药：【适配器层 Adapter】 + 【依赖倒置原则】
- 它的唯一职责：将技术细节“适配”成业务层能理解的“插件”。
- 核心魔法——依赖倒置：
  1. Use Case（使用者） 在自己包里定义接口。
  2. Adapter（实现者） 去实现这个接口。
- 效果： 技术实现变成了可插拔的“零件”。更换数据库？只需要写一个新的Repository实现，然后在DI配置里换掉即可，Use Case层的代码一行都不用改！

P8: 问题四：“这代码根本没法写单元测试！”

(🖼️ 视觉元素占位符: 一张图片，左边是混乱的毛线球代表紧耦合，右边是整齐的乐高积木代表可测试)
(🎤 互动环节): “诚实地举手，谁因为代码太难测试而放弃写单元测试的？”
痛点场景： 业务逻辑里 new 了一个数据库连接，导致单元测试必须依赖真实环境。这是【可测试性灾难】。

解药：【接口】 + 【依赖注入 Dependency Injection】

它的唯一职责：将组件之间的依赖关系从“硬编码”变为“外部配置”。

效果：在单元测试中，我们可以轻松地“骗”过 Use Case：

// 我们可以轻易地用一个 "假的" mockRepo 替换掉 "真的" GormRepo
mockRepo := new(MockSubDomainRepository)
// 告诉 mockRepo: "当有人调用Save方法时，假装成功"
mockRepo.On("Save", mock.Anything, mock.Anything).Return(nil) // <-- 高亮

useCase := NewSubDomainUseCase(mockRepo) // 依赖被注入了！ <-- 高亮
err := useCase.CreateSubDomain(...)

assert.NoError(t, err) // 测试通过！全程没有碰过数据库！

这让编写快速、可靠的单元测试成为可能，极大地保证了代码质量。

P9: 可维护性的延伸：构建强大的可观测性

作为SRE团队，我们不仅要写出可维护的代码，更要确保系统在生产环境中是‘可理解’、‘可诊断’的。
可观测性三大支柱：
- 🪵 日志 (Logging) - 定位“哪里”出错了: 接入KAE，结构化日志，包含request_id。
- 📊 指标 (Metrics) - 了解“怎么样”了: Prometheus + Grafana Dashboard。
- 🔗 追踪 (Tracing) - 分析“为什么”慢了: OpenTelemetry 分布式追踪。
小结：整洁的架构让代码在“静态时”易于理解；完善的可观测性体系则让系统在“运行时”易于诊断。

P10: 面向AI编程：架构即契约，约束即指导

(🖼️ 视觉元素占位符: 一个对比图)
- 左边 (无架构): 人类 🤯 → prompt → AI 🤖 → 一堆散乱代码 💩
- 右边 (有架构): 人类 😎 → 短prompt → AI 🤖 → 精准、分层的代码 ✅
一个好的架构，就是整个项目的“代码契约 (Code Contract)”，它为AI提供了一个清晰、明确的上下文环境。
有了这份“契约”，约束就变成了对AI最有效的指导：
1. 架构定义了“剧本 (Playbook)”: AI会像一个熟悉项目的老手一样，在正确的地方写代码。
2. 约束提供了“护栏 (Guardrails)”: AI不会在usecase层直接写SQL。
3. “契约”简化了我们的“指令 (Prompt)”: 从“一步步告诉AI怎么做”，变成了“为 CreateUser 用例实现API”这样简单的指令。
结论：架构即提示 (Architecture as the Prompt)。

P11: 总结与行动指南

编写可维护代码的核心是“降低理解成本”和“控制变更影响”。
整洁架构是一份强大的“代码契约”，通过强制规则保证了项目的一致性。
(🚀 行动号召):
- 团队可以马上尝试的实践: 在下一个新功能里，先和同事花10分钟讨论一下它的 Use Case 是什么。
- 推荐大家试用: 克隆我们的 kfinops 项目或go-clean-arch模板，亲手运行一下，感受分层的清晰。
面向AI编程不是一句口号，而是一种新的工作范式。 你的架构越清晰、约束越明确，AI就越能成为你的得力助手。

P12: Q&A

谢谢大家！
项目模板参考: https://github.com/zhu327/go-clean-arch
大家有什么问题吗？或者对我们团队未来的代码规范有什么建议？

Vibe Coding有感: 从PingSIX重构说起

Tue, 02 Sep 2025 14:55:52 +0800

说到“Vibe Coding”，这个词最近在开发者圈子里越来越流行。在过去，我的实践很大程度上还停留在比较初级的阶段：把需求和代码片段在 ChatGPT、Google AI Studio 或是 Grok 之间来回地复制粘贴。来到新公司后，虽然开通了 GitHub Copilot，体验有所提升，但感觉它更多时候还是一个“超级智能补全”工具。直到今年7月份，公司给配上了 Cursor，我的编程体验才真正开启了一场变革，正式进入了 Vibe Coding 的奇妙旅程。

恰好，距离我上次更新个人项目 PingSIX 已经有一段时间了。PingSIX 是一个我基于 Cloudflare 高性能框架 Pingora 开发的 API 网关。两周前，Pingora 发布了 0.6.0 版本，这给了我一个绝佳的契机。我决定利用这个机会，彻底实践一次全程使用 Cursor 的 Vibe Coding，对 PingSIX 进行一次大重构。

这次重构断断续续花了一周时间，最终新增了 6636 行代码，删除了 3578 行。这不仅仅是数字上的变化，整个项目在架构、可维护性、可读性、安全性及性能上，都达到了一个我自己非常满意的状态。

我的 Vibe Coding 工作流

在这次重构之旅中，我逐渐摸索出了一套与 AI 高效协作的工作流。这套流程的核心思想是：你，作为程序员，依然是掌舵者；而 AI，是你最强大的副驾驶。

1. 选择对的“副驾”：模型很重要

工欲善其事，必先利其器。我尝试了 Cursor 内置的多个模型，最终发现 claude-4-sonnet 是我的首选。它表现最稳定，理解复杂上下文的能力很强，生成代码的质量也相当高，而且价格合适。其它模型或多或少会有些小问题，而 Sonnet 则提供了一种“无脑用”的稳定预期。

2. 精准的指令：上下文工程是关键

把 AI 当成一个需要明确指令的初级程序员。在你让 Cursor 写代码前，必须先自己整理好需求。需求描述得越详细、越清晰，AI 生成的代码质量就越高。我会把相关的代码文件、需要调用的函数定义，都通过 @ 符号添加到上下文中，为 AI 提供一个完整的“作战地图”。

3. 从战略到战术：让 AI 先当“架构师”

如果你自己对某个功能也一头雾水，不知道该如何下手，那就先别急着让 AI 写代码。我会先打开 “Ask” 模式，把我的难题抛给它，让 LLM 帮我出谋划策。通过一遍遍的追问和迭代，更新我的需求，最终将 AI 提供的方案整理成一份详尽的文档，甚至细化到某个具体逻辑的实现步骤。有时，我还会让它先为我的设想编写单元测试，然后再让 Agent 遵循这份“蓝图”去实现功能代码。

4. 你永远是代码的最终责任人

要时刻记住，LLM 的回答具有不确定性。它是一个强大的工具，但不能替代你的专业判断。我的原则是：先由我来确定“怎么写”的顶层设计，再让 LLM 来完成“体力活”。当代码生成后，Code Review 是必不可少的一环。仔细审查每一行代码，确保它完全符合你的预期。如果不确定，那就让 LLM 继续为这段代码补充单元测试，用测试用例来验证逻辑的正确性。

5. 让 AI 成为你的“代码评审专家”

除了写代码，AI 在 Code Review 方面也表现出色。有时我们自己很难发现项目中的潜在问题，这时就可以借助 LLM 的视角。我会用下面这个 Prompt 来请求一次全面的“代码体检”：

你是一个Rust编程大师, API网关领域的专家, 请你从代码总体的架构, 可读性, 可维护性, 安全性, 性能方面全面的review我的项目代码, 给出你的分析报告, 并对有哪些代码需要修改给出具体的修改建议。

从局部优化到全局审视：当AI助手遇到架构难题

在使用上述 Prompt 的过程中，我发现了一个 Cursor 的局限性。它的文件索引方式似乎是基于代码片段的向量化，这导致它在进行 Review 时，非常擅长发现局部的、函数级别的问题，但很难从项目整体的架构、分层和依赖关系上给出宏观的分析。

为了解决这个问题，我引入了两个外部工具，形成了一套组合拳：

gitingest.com: 这个小工具能把整个项目的代码，按照文件结构，完整地生成一个 Markdown 文本。
aistudio.google.com: 我使用的是 Gemini 2.5 Pro 模型，它支持百万级别的 Token 上下文，足以一次性“吞下”我的整个项目代码。

我的工作流变成了：使用 gitingest 打包项目 -> 将生成的 Markdown 完整地粘贴到 Google AI Studio -> 使用上面那个专家 Prompt 让 Gemini 进行全局审查。

经过这个流程，我得到了一份详尽的“体检报告”，其深度和广度甚至超出了我的预期。下面是最近一次 Gemini Review 报告的一部分摘录：

好的，作为一名在 Rust 编程和 API 网关领域都有深入研究的专家，我非常荣幸能为您审查 PingSIX 这个项目。

首先，请允许我表达我的赞赏：这是一个非常出色、设计精良的项目。它不仅基于 Cloudflare Pingora 这一高性能框架，还在架构设计、代码实现和功能完整性上达到了很高的水準。许多设计决策，例如配置热加载的实现方式、插件系统的设计以及对安全性的关注，都体现了作者深厚的技术功底和对 API 网关领域的深刻理解。

以下是我的综合分析报告，涵盖了总体架构、可读性、可维护性、安全性、性能以及具体的修改建议。

1. 总体架构 (Overall Architecture)

分析: 项目的整体架构是现代、模块化且高度可扩展的，非常符合云原生 API 网关的设计理念。

坚实的基础: 项目选择基于 Cloudflare 的 Pingora 框架，这是一个明智的决定。Pingora 提供了经过生产环境严酷考验的高性能、多线程的异步 I/O 核心，让项目可以专注于网关业务逻辑的实现，而不是底层网络细节。

配置驱动: … 特别是 Etcd 的集成，通过 arc-swap 和 dashmap 实现的配置热加载机制，是高性能网关的黄金标准…

逻辑分层清晰: 项目代码在 src 目录下按功能清晰地划分了模块（config, proxy, plugin, admin, core 等），职责分明。

共享服务设计: SharedHealthCheckService 的设计是一个关键的性能优化…

评价: 架构设计堪称典范，无论是性能、可扩展性还是可靠性方面都考虑得非常周到，达到了业界领先水平。

2. 代码可读性 (Readability)

分析: * 命名规范: … * 注释质量高: …更重要的是解释了“为什么这么做”（The Why）… * 错误处理: …ProxyError 枚举类型非常完善…

评价: 代码可读性极佳。

3. 可维护性 (Maintainability)

分析: * 高内聚，低耦合: … * 强大的配置校验: …在 src/config/mod.rs 中大量使用了 validator crate… * 泛型编程的极致运用: src/admin/mod.rs 中的 AdminResource Trait 和 ResourceHandler<T> 泛型结构是可维护性的典范…

评价: 项目的可维护性非常出色。

4. 安全性 (Security)

分析: * 容器安全: Dockerfile 遵循了最佳实践，使用了多阶段构建…并且创建了一个低权限的非 root 用户… * API 认证: …在比较密钥时使用了 constant_time_eq 函数，有效防止了时序攻击（Timing Attack）。 * TLS 配置: …代码强制将 TLS 的最低版本设置为 TLS 1.3…

评价: 安全性设计考虑周全，遵循了行业内的安全最佳实践。

5. 性能 (Performance)

分析: * 无锁热加载: 使用 arc-swap 来实现路由表…避免了读写锁带来的性能开销… * 高效的路由匹配: …通过反转主机名来巧妙地利用 matchit 的前缀匹配能力实现对通配符域名…这是一个极其聪明和高效的实现。 * 预编译与缓存: …

评价: 性能设计和优化做到了极致…README.md 中提到的性能指标（100K+ RPS, <10ms P99 延迟）基于此架构是完全可信的。

总结

PingSIX 是一个非常优秀的项目，其代码质量、架构设计和性能考量都达到了专业甚至顶尖的水平。它不仅是一个功能强大的 API 网关，更是一个极佳的 Rust 工程实践范例。 … 希望这份详尽的审查报告对您有所帮助！

拿到这份宏观报告后，我就可以把其中具体的修改建议，一段段地贴回 Cursor，让它帮我完成代码的微调和优化。改完一轮，再打包给 Gemini 重新审查，如此循环，直到臻于完美。

一点感想

LLM Agent 的强大无疑极大地提升了我的开发效率，但它也像一把双刃剑。这种前所未有的效率有时也会让上游的 PM 或 Leader 觉得：“反正你很快就能做出来，那我们就快速地改需求吧。” 结果可能导致我们做了很多功能，但真正沉淀和落地的却不多，这或许是“高效”时代下新的烦恼。

面对层出不穷的新工具和新范式，我的建议是：先用起来再说。用的多了，体会自然就深了。别人的经验可以参考，但更重要的是在实践中找到最适合自己的那套 Vibe。

我不确定 LLM 最终会不会淘汰程序员这个职业，但我能确定的是，会 Vibe Coding 的程序员，一定会淘汰不会 Vibe Coding 的程序员。所以，朋友们，都 Vibe起来吧！

整洁架构落地实践

Mon, 04 Aug 2025 14:55:52 +0800

最近在新公司接手了一个历史悠久的项目，功能不多，代码量却不小。深入其中，才发现有太多太多的槽点，简直让人头大。每当要新增一个功能或者修复一个 Bug，都感觉像是在雷区里跳舞，步步惊心。

总结下来，这个项目主要有这么几个“硬伤”：

代码逻辑不内聚：同一个功能的实现，像天女散花一样分散在好几个不同的文件里，想理清完整的逻辑链条，得在 IDE 里跳来跳去，极其耗费心智。
分层过多且混乱：一个简单的请求，要穿越重重关卡，经过好几个层级的调用才能抵达终点。有时你都分不清某一层到底是干嘛的，感觉纯粹是为了分层而分层。
内部自研框架不好用：项目依赖了一个内部的 kgo 框架，但文档缺失，设计理念也比较陈旧，出了问题排查起来非常困难。
外部依赖离散：对数据库、缓存、外部 API 的调用封装得五花八门，没有统一的规范和入口，整个项目像一个杂乱的“百宝箱”。

恰好，Leader 对这个项目制定了新的方向与目标，之前这些遗留问题实实在在成了我们前进路上的绊脚石。因此，一次彻底的架构升级与重构势在必行。同时，部门内也正在推广项目规范化和最佳实践输出，这简直是天赐良机。

很久以前我就读过《架构整洁之道》这本书，在之前的项目中也或多或少受到一些启发，但从未有机会从一个项目初始就完整地贯彻整洁架构的理念。这次，我决定抓住机会，来一场彻彻底底的整洁架构实践。在这个过程中，我感觉自己对整洁架构的理解，以及对 SOLID 原则的落地方式，都有了前所未有的深入体会。

在实践的过程中，我将心得与经验沉淀下来，开源了一个即开即用的 Go 整洁架构项目模板，希望能给有同样需求的同学一些参考： https://github.com/zhu327/go-clean-arch

项目模板特性

Clean Architecture: 清晰地分离业务逻辑与基础设施。
Dependency Injection: 使用 Google Wire 实现编译时依赖注入，避免反射。
Structured Logging: 开箱即用的结构化日志。
Configuration Management: 基于 Viper 的环境化配置管理。
Docker Support: 包含 Dockerfile 和 docker-compose.yaml，便于部署。

架构设计

这个项目严格遵循整洁架构（Clean Architecture）的原则，确保代码库的可扩展性、可维护性和可测试性。

各层描述

🔵 Domain 层: 包含核心的业务逻辑和实体。它是最独立的层，不依赖于任何其他层。
🟣 Use Case 层: 通过与 Domain 层交互来编排业务工作流。它定义了供 Adapter 层实现的接口。
🟠 Adapter 层: 作为与外部世界（如 UI、数据库、外部 API）沟通的桥梁。它实现了 Use Case 层定义的接口。
🟢 External World: 代表与应用程序交互的外部系统，如 Web 客户端、数据库或第三方服务。

核心原则

依赖方向: 所有依赖都必须指向内部。Domain 层位于中心，任何内层都不能依赖于外层。这是依赖倒置的核心。
接口隔离: 接口由消费者（Use Case 层）定义，由提供者（Adapter 层）实现。这使得业务逻辑与基础设施细节解耦。
分层隔离: 每一层只与它的相邻层交互，保持清晰的职责分离。

项目结构

internal/
├── domain/          # Domain 层 (业务实体和规则)
├── usecase/         # Use Case 层 (业务逻辑, 接口, DTOs)
├── adapter/         # Adapter 层
│   ├── delivery/    # 交付机制 (例如, HTTP, gRPC handlers)
│   ├── repository/  # 仓库实现 (数据库访问)
│   └── gateway/     # 到外部服务的网关
└── di/              # 依赖注入配置 (Wire)

实践中的思考与“顿悟”

理论总是美好的，但实践才是检验真理的唯一标准。在重构过程中，我遇到了不少困惑，也收获了很多“原来如此”的顿悟时刻。

1. 每一层到底应该放什么？

刚开始划分代码时，我经常会纠结一个结构体、一个文件到底该放在哪。经过反复的思考和试错，我总结出了一套相对清晰的指导方针。

internal/domain/
- ✅ 应该包含: 核心业务实体（代表业务对象的 Struct）、值对象、领域服务接口、与领域相关的枚举和常量。
- ❌ 不应包含: HTTP 请求/响应结构体、分页或 API 特定数据等应用级概念、任何基础设施细节（如 JSON 标签）。
internal/usecase/
- ✅ 应该包含: 具体业务用例的实现（如 CreateUser, LoginUser）、依赖项的接口定义（如 UserRepository）、请求和响应的 DTO（数据传输对象）。
internal/adapter/
- ✅ 应该包含: 将请求转换为用例调用的 HTTP/gRPC 处理器、实现 Use Case 层接口的数据库仓库、外部服务的客户端（网关）。

通过这个项目我深刻地体会到，项目的根本目的是解决现实世界的问题。我们需要对现实中的实体进行建模，这就是 domain 层的使命。这个实体必须纯粹，不依赖任何外部技术，只包含自身的业务规则和逻辑。

而 usecase 层，则是针对领域模型的一次具体应用和落地。它需要依赖外部能力，比如查询一次数据库、调用一次 gRPC。这时，我们不应该直接在 usecase 中去 new 一个 DB client。而是应该在 usecase 中定义业务所需的 interface，然后由 adapter 层的 repository 或 gateway 来实现这些接口。

这样一来，repository 就不再只是对 GORM 或 sqlx 的简单封装，它变成了 usecase 接口的具体“提供者”。它需要将从数据库查出的数据模型，转换为 usecase 能理解的 domain 模型。最后，通过依赖注入，实现了完美的依赖倒置。

2. 关于依赖注入：从排斥到接受

在以往的项目中，我基本没用过依赖注入，项目里充斥着各种 init() 函数和全局变量，给测试和维护带来了无尽的痛苦。后来接触到依赖注入，有个老哥自己撸了一套基于反射的 DI 框架，读他的代码真的太难受了，完全不知道依赖到底是怎么注入进来的，魔法感十足，这导致我对依赖注入一度有先入为主的排斥。

但在实践整洁架构的过程中，由于 usecase 必须做依赖倒置，我不得不引入 DI 工具。最终选择了 Google 的 wire。用过之后才发现，它其实并没有什么魔法，只是通过扫描代码，自动生成了那些“手动挡”的初始化代码而已（wire_gen.go）。相对于通过反射实现的“自动挡”，这种代码生成的方式让一切依赖关系都变得明确和可知，可读性好太多了。

3. DTO 的归属之争

这是一个让我纠结了很久的问题。usecase 理想情况下只应该依赖 domain 定义的模型。然而在实际业务中，总会有一些不属于 domain 核心模型的结构，比如 CreateUserRequest、UserListResponse。注意，这并非 delivery 层用于解析 JSON 的结构体，而是 usecase 自身执行业务逻辑所需要的数据结构。

我曾经犹豫过，要不要把这些结构体也塞进 domain 层？

纠结过后，我得出的结论是：不能！一定要保持 domain 层的纯粹性。这些结构体实际上是和某个具体的 usecase 强绑定的，它们应该属于 usecase 层。所以，我在 usecase 层下也创建了 dto 目录，用来存放这些用例专属的请求/响应结构。

这确实会导致 delivery (HTTP) 层和 usecase 层可能都有各自的 DTO，初看可能会有些冗余和困惑。但这样做的好处是职责更清晰，usecase 不会因为 delivery 层的变化（比如修改一个 JSON 字段名）而被迫修改。这是为了层与层之间的解耦，必须付出的代价。

4. 我终于悟了：“在调用者包中定义接口”

我之前读到过 Go 社区的一个广为流传的建议（出自 colobu.com/gotips/018.html）：

在使用者的包中定义接口，而不是提供者的包中定义。

说实话，在没有深入实践整洁架构之前，我对这条原则一直是一知半解。为什么接口要让“用的人”来定义，而不是“做的人”来定义呢？

在这次重构之后，我“悟了”。这不就是对“依赖倒置原则”最精准、最通俗的诠释吗！

在我们的架构里： - usecase 是接口的使用者（消费者）。 - adapter 是接口的实现者（提供者）。

usecase 说：“我需要一个能根据用户 ID 找到用户，并返回 domain.User 的能力，我不管你是从 MySQL、Redis 还是从文件中获取，总之，你得满足我定义的这个 UserRepository 接口。”

// in usecase/iface/repository.go
package iface

import "your_project/internal/domain"

type UserRepository interface {
    FindByID(ctx context.Context, id uint) (*domain.User, error)
}

然后，adapter/repository 层去实现它。

// in adapter/repository/user_gorm.go
package repository

// ...
func (r *userRepository) FindByID(ctx context.Context, id uint) (*domain.User, error) {
    // gorm query logic...
    // convert gorm model to domain.User
}

这样做的好处是巨大的：

完美解耦：usecase 只关心它需要什么，不关心底层如何实现。更换数据库实现对 usecase 毫无影响。
易于测试：在为 usecase 写单元测试时，我们可以轻而易举地 mock 这个 UserRepository 接口，而无需一个真实的数据库连接。
符合最小知识原则：如果让 adapter 来定义接口，它可能会暴露很多 usecase 根本不需要的方法，增加了使用者的心智负担。而由使用者定义，则可以确保接口的精简和必要。

总结

从一个混乱的遗留项目开始，到最终落地一套清晰、可维护的整洁架构，这次重构之旅让我收获颇丰。整洁架构并不仅仅是一套死板的目录结构或分层规则，它更是一种引导我们写出高内聚、低耦合代码的思维方式。

它迫使我们去思考： - 什么是业务的核心？（Domain） - 业务流程是怎样的？（UseCase） - 技术细节如何与业务逻辑解耦？（Adapter & Dependency Inversion）

通过这次实践，我对依赖倒置、接口隔离等 SOLID 原则有了远比书本上更深刻的理解。当你真正理解了“为什么”要这么做，而不是仅仅停留在“是什么”和“怎么做”的层面时，你会发现，写出整洁、健壮的代码，其实是一件充满乐趣的事情。

希望这篇文章能为同样在重构道路上探索的你，提供一些有价值的参考与启发。

打造一个属于自己的AI书签

Mon, 07 Jul 2025 14:55:52 +0800

前言

我一直是个重度的书签使用者，多年来都依赖 Pocket 来收藏和沉淀那些在网上看到的、值得一读的文章。然而，最近 Pocket 宣布其通知服务即将关闭，这对我来说像是一个信号，是时候去寻找一个更稳定、更可控的替代品了。

我的探索之旅就这样开始了：

Raindrop.io：社区里很多人推荐，功能也确实强大。但不知道是不是网络原因，我这边访问起来总是感觉有点慢，而且用惯了 Pocket 的我，对它的界面和交互逻辑始终有些不太习惯。
自建服务：作为程序员，第一反应自然是自己动手。我找到了像 linkding 这样的优秀开源项目。我尝试把它部署在 fly.io 的免费实例上，但 linkding 对资源的要求不低，最低配的 256M 内存实例直接就 OOM (Out of Memory) 了，升级配置又意味着成本。
从零开始写一个？ 这个念头一闪而过。我甚至构思好了技术选型：参照 linkding 的功能，用我最近在学习的 Rust 实现后端，部署在 Cloudflare Workers 上，再配上 Cloudflare D1 的 SQLite 数据库。这套方案 Serverless、成本极低，堪称完美。但转念一想，这工程量可不小，对于业余项目来说，我实在没有那么多时间投入进去。

就在我快要放弃，准备将就着用某个方案时，我想起了一篇以前收藏过的文章。

1. 灵感乍现：LLM x GitHub 书签

那篇文章是 LLM x 书签收藏：摘要 & 全文索引，作者提供了一个极具创意的思路：通过一个浏览器插件 osmos::memo，可以将书签直接保存到指定 GitHub 仓库的 README.md 文件里。

这个方案瞬间击中了我！它足够简单，没有多余的功能，完美符合我的需求。数据就躺在自己的 GitHub 仓库里，再也不用担心服务关停。虽然原文后续介绍了如何利用 LLM 对书签进行摘要和索引，但我觉得还可以更进一步，改造成一个完全自动化、更符合我使用习惯的流程。

说干就干，我立刻创建了一个新的仓库 bookmark，准备开始我的改造计划。

2. 存量数据的漫漫迁移路

要打造新家，首先得把老家的家当搬过去。第一步，就是处理从 Pocket 导出的几百条存量书签。

我写了一个简单的 Python 脚本，将 Pocket 导出的 HTML 文件解析成 Markdown 格式，然后一股脑儿地塞进了 README.md。但这只是万里长征的第一步。我的目标是让每个书签都有 AI 生成的摘要和分类。

我想到了最近很火的 Gemini，它的命令行工具 gemini-cli 看起来很适合用来做批处理。于是，我开始了我的踩坑之旅：

初次尝试（失败）：我用 Playwright 写了个脚本，模拟浏览器去访问我的 230 个书签链接，把每个页面的完整 HTML 都抓取下来。结果，所有内容加起来足足有 165MB。
分割文件 + Gemini CLI（失败）：我把这 165MB 的内容按每个网页一个文件进行分割，然后尝试用 gemini-cli 遍历所有文件，让它为每个 HTML 生成摘要和分类。结果，Gemini 的上下文窗口有限，而且 API 调用非常非常慢，一个下午过去，才处理了不到 80 个。果断放弃。
打包上传 AI Studio（失败）：我想，单个处理不行，那就打包处理。我用 Python 脚本把网页按每 20 个一组进行打包，但每个包的文件大小仍在 5MB ~ 14MB 之间。这个大小对于直接上传到 Google AI Studio 来说还是太大了，此路不通。
精简内容 + 手动处理（成功！）：看来问题出在原始 HTML 内容太庞杂了。我再次修改脚本，在分割文件的同时，引入 html2text 库，将臃肿的 HTML 转换成纯文本。这下效果立竿见影，每 20 个网页打包成的文件只有 400KB ~ 600KB。
AI 手工操作：我将这 13 个（230/20 ≈ 13）处理过的文本文件，手动一个个上传到 Google AI Studio。然后，通过精心设计的 Prompt，让 AI 为文件里的每一个链接都生成摘要，并整理成我想要的 Markdown 格式。
最终分类：我把 AI 生成的所有摘要内容汇总到一个 summary.md 文件里。最后，再把这个汇总文件上传给 AI Studio，给它下达最终指令：“请根据这些内容的摘要，将所有链接按技术领域、生活、思考等类别进行分类整理。”

最终，我得到了完美的分类归档文件：category.md。虽然过程曲折，但看到整齐划一的成果时，一切都值了。

3. 新增书签？交给 GitHub Actions 吧！

处理完存量数据，接下来就要考虑如何自动化地处理每一个新增的书签了。我的思路是，让万能的 GitHub Actions 来扮演这个智能管家的角色。

整个流程如下：

触发：每当我通过 osmos::memo 插件向 README.md 添加新链接并推送到 GitHub 时，就会自动触发 GitHub Actions 的 workflow。
解析：在 workflow 中运行的 Python 脚本 (process_bookmarks.py) 会使用 git diff 命令，精准地找出 README.md 中新增加的那一行书签链接。
抓取内容：为了避免自己写爬虫遇到的各种反爬问题，我选择了一个非常棒的工具——jina reader。通过调用它的 API (https://r.jina.ai/URL)，可以直接获取到目标链接页面的干净、规范的 Markdown 文本。
生成摘要：将获取到的 Markdown 文本发送给 LLM API，让它生成一段简洁的摘要。
智能分类：将链接的原始标题和 AI 生成的摘要再次组合，发送给 LLM API，让它判断这个链接应该属于哪个分类。
写入归档：最后，脚本会按照 [标题](链接) - 摘要 的格式，将这条全新的、处理好的书签信息，追加到 category.md 文件对应的分类下。

就这样，一套完全自动化的 AI 书签整理流程就诞生了。我只需要在浏览器上点一下收藏，剩下的抓取、摘要、分类、归档工作，都由我的 AI 管家在云端默默完成。

4. 拥有你自己的 AI 书签

这套方案我已经开源在 GitHub 上：https://github.com/zhu327/bookmark

目前我使用的 LLM API 是由硅基流动提供的免费模型 deepseek-ai/DeepSeek-R1-0528-Qwen3-8B，效果相当不错。如果你也对这个方案感兴趣，可以非常简单地拥有自己的 AI 书签：

Fork 这个仓库。
在你的仓库 Settings -> Secrets and variables -> Actions 中，添加两个 Repository secrets：
- LLM_API_URL: 兼容 OpenAI API 格式的大模型接口地址，例如 https://api.siliconflow.cn/v1/chat/completions。
- OPENAI_API_KEY: 调用该 API 所需的 Key。

当然，这个方案也并非完美。比如对于有严格反爬策略的网站（点名微信公众号），jina reader 也无能为力，无法直接获取到文章内容。

总结

在后 Pocket 时代，借助 LLM 的强大能力，我的个人书签系统完成了一次有趣的进化。它不再是一个依赖于第三方在线服务的传统书签，而是变成了一个由我自己掌控、活在 GitHub 上的智能知识库。所有数据都以 Markdown 格式清晰地存储，检索也变得前所未有的简单——打开 category.md，按下 CTRL + F 即可。

这个小项目让我再次感受到，将 AI 作为一种工具融入到个人工作流中，能够迸发出巨大的能量。它不仅解决了我的实际问题，也让整个过程充满了探索和创造的乐趣。

我理解的AI Agent与MCP

Wed, 02 Apr 2025 10:55:52 +0800

前言

最近AI圈子里Manus这个项目可以说是相当火了，连带着MCP（Model Context Protocol）这个概念也开始频繁出现在各种技术讨论区。作为一个程序员，自然也对这些新东西充满了好奇，于是花时间捣鼓了一下AI Agent和MCP相关的知识。这篇文章就是我学习和思考后，对这两个概念的一些个人理解和梳理。

1. 从Workflow到AI Agent：大脑的进化

回顾我们以前做自动化任务，比如搞个自动抢票、自动下单之类的，思路基本都是围绕着一个固定的workflow。我们会预先设定好一套流程逻辑：收到指令 -> 判断条件 -> 走对应分支 -> 调用特定工具（API、脚本等）。整个过程就像一个流程图，每个节点和路径都是我们程序员预先设计好的。在这个模式下，我们程序员就是这个workflow的“大脑”，我们把执行计划通过代码逻辑，“硬编码”到系统里。比如预定机票这个场景，我们会写代码一步步调用查询接口、选择航班接口、填写乘机人信息接口、支付接口等等。

2. LLM登场：有了“大脑”，但还缺“手脚”

随着大语言模型（LLM）技术的突飞猛进，特别是像DeepSeek R1这样强大的推理模型出现，它们的推理和规划能力越来越接近人类大脑。这就让我们自然而然地想到：能不能让LLM来充当这个自动化流程的“大脑”，代替我们来制定执行计划呢？

想法很美好，但LLM本质上还是一个文本补全的模型。它能“思考”并告诉你计划是什么，但它自己并不能直接撸起袖子去调用那些具体的工具（API、函数等）来完成任务。为了解决这个问题，OpenAI在其API中引入了tools（或称为 Function Calling）的概念。

这个流程大致是这样的：

我们的应用程序（可以称为Agent）调用LLM API时，在请求的上下文中详细描述可用的工具：每个工具是干嘛的、输入需要什么参数、输出是什么格式。
Agent把用户的自然语言指令（Prompt）发给LLM。
LLM根据用户的需求，结合它所知道的工具信息，判断是否需要以及需要调用哪个（或哪些）工具。
如果需要调用工具，LLM不会直接执行，而是返回一个包含调用指令的响应，里面说明了要调用哪个工具以及需要传递的参数（通常是JSON格式）。
Agent收到这个响应后，解析出调用指令，在Agent自己的环境里执行相应的工具（比如调用一个本地函数或一个外部API）。
Agent拿到工具的执行结果后，把这个结果再次作为上下文信息，传回给LLM。
LLM根据工具的执行结果，决定下一步是继续调用其他工具，还是生成最终的回复给用户。

这个基于tools的交互模式，让LLM有了指挥“手脚”（工具）的能力。但这里也暴露了一个比较明显的弊端：完成一个任务可能需要多次与LLM进行交互（LLM决策 -> Agent执行 -> Agent反馈结果 -> LLM再决策…），并且为了让LLM理解上下文，每次交互都需要传递越来越长的历史信息，这既增加了延迟，也增加了API调用成本和Token消耗。

3. CodeAct：让LLM直接写代码执行

我们知道，当前LLM最强的能力之一就是代码生成。于是，就有人想出了另一种更直接的思路：既然LLM擅长写代码，而我们提供的工具本身很多就是函数或者可以通过代码调用的API，那何不让LLM直接生成一小段可执行的代码（比如Python），然后在我们的Agent里内置一个安全的代码执行沙箱来运行这段代码呢？

在这段生成的代码里，LLM可以直接包含对我们提供的工具（函数）的调用，甚至可以编写一些简单的流程控制逻辑（if/else、循环等）。这样一来，多个步骤和工具调用可能通过一次LLM生成、一次代码执行就完成了，大大减少了与LLM的交互次数。这种方法就被称为CodeAct（代码作为行动）。

4. 到底什么是AI Agent？

聊了这么多，我们再来尝试给AI Agent下一个定义。我认为，AI Agent = LLM（大脑） + Tools（手脚） + Agent Runtime（执行器） + 决策循环。

具体来说，AI Agent通过调用LLM API，并结合一系列可用的工具（Tools），来理解并执行用户的自然语言任务。它通常采用一种决策-执行-观察的循环模式（ReAct）：

决策（Reason）：由LLM根据当前任务目标和上下文信息，决定下一步是调用工具还是直接回复。
执行（Act）：由Agent Runtime根据LLM的决策，执行相应的工具调用或代码片段。
观察（Observe）：Agent Runtime将执行结果反馈给LLM，作为新的上下文信息，供LLM进行下一轮决策。

这个循环一直持续，直到任务完成。

但这里有个关键问题：LLM本身具有一定的不确定性。对于相同的输入（Prompt），它每次返回的结果可能都不完全一样。这就给AI Agent的执行带来了挑战，有时候可能会偏离预期或者卡在某个环节。因此，在开发AI Agent时，接入Tracing（追踪）系统变得非常重要。我们需要能够实时跟踪Agent与LLM的每一次交互、上下文内容、工具调用情况以及执行结果，这样才能在出现问题时快速定位和调试，进而优化我们的Prompt或者Agent逻辑。

5. 多Agent协作：专业的事交给专业的Agent

随着Manus的流行，多Agent编排（Multi-Agent Orchestration）的理念也开始受到关注。核心思路是化整为零，分工协作。

我们不再试图构建一个“万能”的超级Agent，而是将复杂的任务拆解，构建多个功能单一、职责明确的专家Agent。比如，我们可以把web_search和web_fetch这两个工具组合起来，封装成一个专门负责网页抓取的web_scraper_agent。这种单一功能的Agent，它的大脑（LLM）可能不需要最顶级的推理能力，我们可以选用一个性能足够且成本更低的模型（比如一些中小型模型或者特定领域的微调模型）。

当我们有了多个这样的专家Agent后，再引入一个Planner Agent（规划器Agent）。这个Planner Agent通常需要一个推理能力较强的LLM作为大脑，它的职责是：

接收用户的原始任务。
将任务拆解成若干子步骤。
根据每个子步骤的需求，选择并调用合适的专家Agent。
收集专家Agent的执行结果。
根据执行结果，动态调整后续的计划（可能需要重新规划或调用其他Agent）。
循环这个过程，直到最终任务完成，然后将结果汇总返回给用户。

这种多Agent架构带来的好处显而易见：

成本效益：在大量执行具体任务的专家Agent上可以使用更便宜的LLM。
维护性：每个Agent功能单一，更容易开发、测试和维护。
扩展性：可以方便地增加新的专家Agent来扩展整个系统的能力。
可能更优化的上下文管理：Planner Agent可能只需要关注子任务的目标和专家Agent返回的关键结果，而不需要承载所有底层工具调用的详细上下文。

6. Prompt工程：Agent的灵魂

无论是使用ReAct还是CodeAct，无论是单Agent架构还是多Agent编排，有一个环节始终是绕不开的，那就是Prompt Engineering（提示工程）。

我们需要为每一个与LLM交互的环节（无论是Planner Agent制定计划，还是专家Agent执行任务，或是Function Calling/CodeAct的触发）精心设计Prompt。好的Prompt需要能够引导LLM按照我们的预期来思考和输出：

让Planner Agent生成结构化、可分步执行的计划。
让LLM在需要时准确地选择并调用我们提供的工具。
让LLM返回格式规范、易于解析的文本（比如JSON），方便Agent Runtime处理。

可以说，Prompt就是我们给AI Agent注入灵魂的方式。

7. MCP：Agent间沟通的标准语

随着多Agent架构的兴起，Agent之间如何发现彼此、如何调用彼此的能力就成了一个问题。这时，MCP（Model Context Protocol）这个概念应运而生。

你可以把MCP理解为一套为Agent（或者说LLM的工具）设计的标准化接口规范。

在没有MCP之前，我们实现的工具可能五花八门：一段本地Python代码、一个内部HTTP API调用、一个第三方云服务接口等等。每次要给Agent添加新工具，都需要手动编写关于这个工具的描述（功能、参数、格式），然后注入到Agent的上下文中。

有了MCP之后，情况就可能变得更规范：

工具提供方可以将其能力封装成一个遵循MCP协议的MCP Server。
Agent可以通过标准的MCP方法（比如list_tools）来动态发现某个MCP Server提供了哪些工具及其描述。
Agent可以通过标准的MCP RPC Call来执行这些工具。

MCP不仅仅规范了工具的调用，它通常也试图规范Prompt模板、资源管理等Agent开发中常见的元素。如果MCP能够被广泛采用，理论上可以：

降低Agent的开发门槛：开发者可以直接复用社区提供的、遵循MCP标准的工具服务，而不需要自己重复实现和描述工具。
提高Agent的互操作性：不同开发者、不同团队开发的Agent或许能更容易地进行协作。

当然，MCP目前似乎还在发展初期，但它指明了一个让Agent生态更加规范化、标准化的方向。

8. 总结：门槛不高，精通不易

以上就是我这段时间学习下来，对AI Agent和MCP的一些粗浅理解。在阅读了几个开源的Manus实现（或者类似的多Agent框架）之后，我的一个直观感受是：

对于掌握Python的程序员来说，上手开发一个基础的AI Agent，或者编写一个简单的Tool/MCP Server，技术门槛似乎并不算特别高。很多框架（如LangChain、LlamaIndex等）已经帮我们处理了与LLM交互、管理上下文、执行工具等繁琐的底层工作。

然而，真正的挑战在于：如何在一个特定的业务场景下，设计和实现一个稳定、可靠、高效的AI Agent。这需要：

深刻理解业务需求，并将其转化为适合Agent执行的任务流程。
精心的Prompt设计与调优，不断尝试，引导LLM给出期望的输出。
有效的Tracing和Debugging，快速定位Agent执行过程中的问题并进行修复。
合理的架构选择（单Agent vs 多Agent，ReAct vs CodeAct）和成本控制。

就像当年我们从写简单脚本到构建复杂系统一样，AI Agent的世界也是易学难精。工具和框架降低了入门门槛，但要做出真正好用的Agent，还需要大量的实践、思考和打磨。

跬步 On Coding

Lexideck 背单词小应用：AI 时代的 Vibe Coding 实践

1. 划词与词典：站在巨人的肩膀上

2. 服务端：轻车熟路的 Serverless 架构

3. 客户端：让 AI 帮我做设计与前端

4. 扩展视野：终端里的碎片时间

5. 解决问题与妥协

总结：Vibe Coding 时代的程序员

Loop Engineering 实践: Pi Coding Agent

1. Loop Engineering 是什么，由哪些环境组成

2. goal/loop 命令意味着什么，分别有什么职能

3. 我的 Loop Engineering 的思路

1. app-inspection 创建了一个巡检用的 skill

2. 记忆 LOOP.md 记录每次执行结果

3. 判断跟进巡检报告，以及记忆内容，判断哪些问题需要代码修复

4. 切分支，走 go.md 的 writing plan 后续流程完成代码修复

5. 提交 PR

4. Pi Coding Agent 的实战

1. 配置 Pi Coding Agent

2. 用 goal meta 出一个 goal 的 Prompt

3. 配置到 Pi Coding Agent 的 Loop 流程中

总结

用LLM Wiki构建SRE知识库

1. 现实的骨感：信息密度极低的“脏数据”

2. 初试 LLM Wiki 与人工“蒸馏”

3. 扩大战果：整合全域资产

4. 建立真正的 SRE Wiki Index

5. 交付与总结

打造适合自己的 AI Harness 工程：从开发流、E2E 测试到自动排障

1. 开发流程的全自动化与架构规约

2. 让 AI 接管 E2E 测试

3. SRE 与自动排障 Agent 的探索

4. 探索多智能体并发工作流

5. 业务实战：多云生命周期的 IaC 与抽象

复盘：ClawOps AI Agent

前言

1. 雄心勃勃的初始架构

2. 核心能力建设与“妥协”

WPS 365 MCP的对接与Proxy模式

CMDB对接：CLI vs MCP

3. 失败的根因与挣扎

4. 复盘：如果重来，我会怎么设计？

1. 抛弃统一认证，拥抱本地配置（Identity）

2. WPS 365 MCP 授权的本地化改造

3. 极简的Channel消息路由

5. 结语

AI工程落地实践

1. 回顾：前AI时代的手工作坊

2. Vibe Coding 时代的冲击与适应

3. 在 Cursor 中落地复利工程

4. 最终的折衷方案

我的2025

行云创新：及时止损的教训

找工作：不匹配就是不匹配

金山办公：双城生活与新的大腿

Vibe Coding：AI 时代的生存法则

开源与折腾

结尾

AI Agent 工程化实践：从 Prompt 到 Context 的思维转变

遇到的瓶颈

几个工程化的巧思

1. 动态整理与压缩上下文

2. Checkpoint 回溯与有效信息保留

3. Sub Agent 解决上下文隔离

4. 面向“人”设计工具，而非面向 API

总结：从 Prompt 到 Context

系统性思维的陷阱：从“完美方案”到“有效落地”

方案的本质：平衡客观条件的艺术

实战案例：只解决 80% 的问题

开源代码的“神话”与重构

警惕“过度系统化”的僵局

我的应对策略：最小化闭环

写在最后

pingsix-ingress-controller启动

1. apisix-ingress-controller架构

1. K8s Resources Watch Layer (资源监听层)

2. Provider Layer (提供者层)

3. Translator Layer (翻译层)

4. ADC Client Layer (ADC客户端层)

5. ADC Executor Interface (执行器接口)

1. `app-inspection` 创建了一个巡检用的 skill

2. 记忆 `LOOP.md` 记录每次执行结果

4. 切分支，走 `go.md` 的 writing plan 后续流程完成代码修复

2. 用 goal meta 出一个 `goal` 的 Prompt