Knowledge Hub 是怎样在 AI 的参与下被一点点做出来的 · Jayleonc

在传统的软件工程语境下，像 Knowledge Hub (以下简称 KH) 这样涵盖了 VFS 2.0（物化路径）、实时 ACL 过滤（GORM Scope 注入）、RAPTOR 层级检索（自底向上递归摘要）、复杂 Git 同步以及自动化 PR 流程的系统，其技术密度和工程复杂性之高，本该是一个由两三个资深后端牵头、带上一个前端磨上好几个月才能落地的工程量。

但在过去这段时间里，我独自承担了从产品构思、架构设计、全栈开发到运维落地的所有角色。在没有任何外部产品经理、测试、或者运维支持的情况下，我通过与 AI 的深度结对，独自一人让这套系统从几行原始 Spec 长成了现在的硬核模样。

翻看代码库，AI 的痕迹无处不在。但作为一个专业的后端架构师，我今天想聊的不是 AI 多么能干，而是我如何通过一套名为 Spec-Driven Development (SDD) 的治理体系，指挥 AI 把一个模糊的想法，锻造成一个具备“自演进”能力的工业级产品的。在这个过程中，我们也无意中实践并深化了一个关于 Hermes Agent（赫尔墨斯智能体） 的前沿命题——即如何让系统在设计层面实现受控的“自我进化”。

一、起念与架构主权：对“烟囱式”RAG 的一次清算

KH 的起点，源于我对公司内部知识治理痛点的长期观察，更是我对自己过去两个 AI 实战项目深度复盘后的产物。

在那之前的尝试中，我先后构建了两个针对不同业务场景的智能客服系统。虽然业务上跑通了，但底层的架构却让我如鲠在喉：每一个系统背后都挂着一个独立的、为了上线而“快速堆砌”出来的 RAG 逻辑。 这种“烟囱式”的开发导致了严重的问题：召回效果难以统一调优、权限逻辑在各处重复造轮子、管理维护极其混乱。虽然它们完成了当下的业务使命，但在我心里，那种“不够好”的工程遗憾感始终挥之不去。

我意识到，我需要的是一套通用的、具备工业级韧性的知识治理中枢。它不应该只是一个业务的“挂件”，而应该是整个 AI 生态的“逻辑底座”。

正因为这个项目从头到尾只有我一个人负责，我才更不敢在架构上“偷懒”。我深知，如果为了图快而采用那种“打补丁”式的堆砌逻辑，任何设计上的疏漏最终都会转化成我个人的运维噩梦。为了不让自己将来陷入“每天忙于修补漏洞”的死循环，我必须逼着自己站在通用工业级方案的高度，去推敲每一行核心代码的合理性。这种全链路的原子化压力，反而成了维持架构纯粹性的最强动力。

二、SDD 生态：基于 Skill 插件的“意图编译器”网络

在 AI 辅助开发的早期，我曾犯过一个典型的错误：把 AI 当成高级版的 IDE 补全插件。后来我意识到，AI Agent 在 KH 的研发流中实际上扮演了多个“编译器”的角色。

我的工作核心发生了本质的迁移：从维护易变的代码，转向了维护更稳定的规范 (Spec)。 这正是 Spec-Driven Development (SDD) 的精髓。为了支撑这一体系，我在系统内部（.codex/skills）构建了一套完整的 Skill 生态，每一个 Skill 都是一个专业化的“意图编译器单元”。

2.1 需求预研与意图冻结：从 Idea 到 Spec

在这个阶段，我扮演的是“问题定义者”。

• Idea Skill：这是进化的原点。它负责将我那些模糊、发散的想法澄清为可执行的方案。比如当我想实现“类似 VS Code 的路径感应交互”时，Idea Skill 会帮我判定复杂度，并建议我是否需要引入物化路径。
• Research / Deep-Research Skill：在动笔前，我会指挥 AI 进行硬核预研。比如“如何在 pgvector 中利用 B-Tree 表达式索引优化实时 ACL 过滤”。它输出的不再是空洞的教程，而是针对 KH 现有 internal/database 现状的可行性报告。
• Spec Skill：这是最重要的环节。它将预研结果“编译”成一份结构化的、声明式的 spec.md (意图代码)。这份文档是系统的宪法，只说 What，严禁出现 Step 1/2 这种时间顺序。这种做法确保了维护软件的核心，从维护代码转向了维护规范。

2.2 方案编译与指令转化：从 Plan 到 Task

有了 Spec 之后，AI 开始进入“实现编译”阶段。

• Plan Skill：将 spec.md 结合 Go 语言的约束和架构不变量，“编译”成 plan.md (编译计划)。在这里，我们将复杂的系统变形过程拆解为受控的 Phase（编译阶段）。Phase 在这里是合法的，它代表了系统从旧状态向新状态的“安全编译路径”。
• Task Skill：这是 SDD 落地的最后一公里。它将 plan.md 编译为 tasks.md (指令流)。这里的每一个任务都是原子化的、带验证逻辑的。比如“修改 DocumentService 构造函数签名，引入 ProjectReader”，做完即打勾，这种指令流确保了执行过程的可暂停与可回滚。

2.3 执行、审计与质量的“拦截器”

• Execute Skill：AI 根据 tasks.md 进行高速代码生成的阶段。
• Review-Doc / Review-Exec Skill：这是架构的一道防线。在重构核心逻辑时，我会启用审计技能，让 AI 自主扫描产出的代码是否违反了 Spec 中的硬约束（如：严禁在 Service 层直接拼 SQL）。
• Gen-Test-for-Service Skill：这是我对质量的执着。AI 会根据 Service 定义，自动生成符合 KH 规范的表格驱动测试，确保逻辑闭环。
• Aesthetic-Review Skill：这是我最看重的逻辑审计工具。作为架构师，我眼中的“审美”绝非像素级的视觉，而是代码的结构诚实度。我会启用这个技能，让 AI 对 internal/ 下的 Go 代码进行“层级扫描”：从函数的命名动宾结构，到包定义的内聚性，再到接口设计的克制度（严禁超过 5 个方法的臃肿接口）。它能帮我识别出那些为了图省事而塞进 utils 包的垃圾逻辑，确保系统的每一行代码读起来都有一种工程上的“节奏感”。

这种基于 Skill 的 SDD 模式，让 KH 的研发过程变成了一个全自动的编译管道。当业务变化时，我只需在最顶层的 Spec 环节修改意图，剩下的编译流会自动在各个 Skill 间流转。

三、意图指挥：Vibe Coding 的后端实践

“Vibe Coding”被很多人误解为一种玄学氛围感，但在我的视角里，Vibe 是一种跨职能的指挥权。 我不写 CSS，但我对“什么是好用的工业级工具”有着偏执的直觉。

3.1 作为一个后端，如何精准定义前端？

在重构从 Breadcrumb 到 VfsTree 的过程中，我并没有去查阅 React 的 API，我只是向 AI 下达了关于“Vibe”的指令：

• “我要的是一种像 VS Code 一样冷峻、且具备极致功能性的交互感。面包屑不能只是摆设，它要能‘钻透’当前的层级，看到邻居的风景。”

当我下达这种指令时，我其实是在定义系统的执行标准。我使用了 AI 的 Frontend-Design 技能，通过不断的“意图对齐”，让 AI 在不偏离我审美上限的前提下，完成了诸如“树路径自愈算法”等高性能实现。

3.2 后端思维对前端的“降维打击”

AI 最初给出的树状态管理方案是传统的嵌套对象。我一眼就识破了其中的灾难：在处理 Git 同步过来的上万个节点时，递归更新会触发整棵树的 Diff，UI 绝对会卡死。
于是我利用后端思维进行了强制干预。我告诉 AI：“抛弃你的递归树，我要的是 邻接表 (Adjacency List)。所有节点必须扁平化存储在 Map 里，更新必须是 $O(1)$ 的。前端的 vfsStore.ts 必须像数据库索引一样精准。”

这种“后端逻辑跨界输血”的配合，最终磨出了那套即便在万级节点下也丝滑如初的交互。这种手感，不是靠调 CSS 调出来的，而是靠后端架构师对“数据结构”的坚持 Vibe 出来的。这种跨越职能边界的指挥权，就是我理解的 AI 时代的“全栈掌控力”。

四、方案裁决：架构师的“决策剪枝”艺术

AI 擅长“出卷子”，它会针对一个目标给你抛出方案 A、B、C。架构师的护城河，就是要在这些方案中通过博弈，挑出那个最稳健的解。

4.1 攻克 ACLScopeForVFSNode 难题

这是一个极其变态的逻辑：要在数据库层实现“目录穿透”，即只要下级有一个文件可见，父目录就必须可见。

我并没有教 AI 怎么写 SQL，我只是下达了“效果指令”：

“我要在数据库层实现透明的权限穿透。不准用中间表，不准有异步同步。你给我出几个方案，我们要能在多表 JOIN 的复杂环境下也绝对不出别名冲突。”

AI 随后在对话框里卷出了三个方案：

• 方案 A：在 Service 层写递归函数（被我秒杀，性能太差）。
• 方案 B：引入一个专门的权限映射表（被我否决，同步一致性太难搞）。
• 方案 C：利用 EXISTS 子查询在 GORM Scope 层实现实时拦截。

我最终选定了方案 C。但我并没有直接让它写代码，而是继续追问：“在多表 JOIN 时，你怎么保证 db.Statement.Table 不会指错对象？”这种在细节边缘进行的深度博弈，让系统最终产出了那段硬核代码。

五、Hermes 闭环：系统设计的“自我进化”逻辑

在 KH 的演进中，我一直在尝试构建一个叫 “Hermes 闭环” 的体系。它让系统具备了某种“自省能力”。

5.1 持久化上下文与长期记忆

通过 CLAUDE.md、agents.md 和 constitution.md，我为 AI 提供了分层的持久化记忆：

• 企业级记忆：整个公司的安全红线与合规要求。
• 项目级记忆：constitution.md 中定义的“强制应用租户和 ACL 过滤”的编码宪法。
• 个人级记忆：我个人的代码风格偏好。

5.2 架构的“自我审计”

每当一个核心 Phase 结束，我会指挥 AI 启用 Sync-Doc / Review-Doc Skill 执行一次“架构体检”。
我会让 AI 对照 DEV_LOG.md（系统的思考快照）和源码事实。我会问：“基于 VFS 2.0 的新语义，看看目前的 Prune 清理逻辑是否还存在逻辑断层？”

AI 往往能敏锐地发现冗余，并根据 spec.md 自动推导出重构方案。这种 “从日志到 Spec，再从 Spec 到源码” 的研发闭环，就是我理解的 Hermes。它让 KH 变成了一个不仅能跑、还能“感知”自己设计缺陷、并能在我这个“主脑”的监控下自我手术的生命体。

六、程序员的价值转变：从“搬砖工”到“系统导演”

回看 KH 的诞生历程，我深感我的身份已发生了本质的转变。

传统的模式里，我的价值建立在“手握键盘”的实现能力上。但在 AI 原生工作流中，基石变成了 意图定义与规范设计。
我不再去调度线程，我是在调度智能体与系统。我不再是代码机器，我成了系统的导演。

这意味着，我的核心竞争力从“谁写得更好”变成了“谁定义问题更准”。这要求我们必须从“执行者”走向“设计者”，从“技术爱好者”走向“系统思考者”。这种转变比过去更难，因为它考验的是对业务深度的理解和对系统优雅度的直觉。

结语：重新定义架构师的数字主权

Knowledge Hub 的每一行代码，都是我用意志“感应”出来的产物。

我们使用的工具——Claude Code 是全能的“工作流引擎”，Gemini CLI 是灵活的“上下文专家”，而 Codex CLI 则是精准的“安全助手”。配合着那一整套精心设计的 Skill 插件，它们构成了我的“核动力”研发体系。

接下来的 Phase 5，我们将进一步深化这种“意图指挥”模式，让 KH 彻底进化为一个能够自主推导架构缺口、甚至能尝试自我修复设计断层的“自演进系统”。未来程序员将像建筑师和哲学家一样，在设计人与机器共处的未来秩序中，重新夺回创造者的冠冕。

加油吧，AI 原生架构师们。