Skilled：让 AI 编码助手拥有记忆与规范的工作流框架

一位开发者的"健忘症"困扰，催生了一个 AI 工作流革命

2024 年的某个深夜，荷兰独立开发者 Michel Kerkmeester 对着屏幕叹气。他花了整整两天时间，向 AI 编程助手解释一个复杂的电商结账系统的架构：为什么要用事件溯源模式、不同领域模型之间的边界在哪里、支付服务为什么不直接调用库存 API……第三天，当他继续这个项目时，AI 回复了一句令他哭笑不得的话："抱歉，我没有关于这个项目之前对话的记忆。"

这就是当前所有 AI 编程助手的根本缺陷——会话失忆症（Amnesia）。每一次新会话，都是从零开始。上下文窗口关闭，架构决策、权衡取舍、精心推理的过程，全部化为乌有。

Michel 没有选择忍耐或抱怨，他花了数月时间，构建出了一套完整的工作流框架，让 AI 编码助手能够"记住"一切。这个框架，就是 Skilled（全称：Skilled — Agent Orchestration Loops w/ Custom Spec Kit & Memory System）。

它不是又一个 AI 编程工具，它是 AI 编程的"操作系统"

Skilled 的本质，不是替代 OpenCode、Claude Code 或 Copilot，而是叠加在它们之上的一层智能管理层。它让任何兼容 MCP（Model Context Protocol）的 AI 编码助手，获得三种核心能力：

• 持久化记忆：决策、上下文、项目历史在本地 SQLite 数据库中长期存储，跨会话、跨崩溃、跨压缩（Compaction）存活。
• 结构化规范：每个文件变更都必须附有规范的 Spec 文件夹，记录"变更了什么、为什么变更、如何变更"，就像软件开发的"实验日志"。
• 多 Agent 协作路由：12 个专业 Agent 在 20 个按需技能的引导下，协同工作，避免单一 AI 模型能力边界不足的问题。

这三个层次共同构成了一套"上下文管理层"，让 AI 编程助手从"单次会话的临时工具"进化为"项目生命周期内的长期伙伴"。

Spec Kit Framework：每一次变更都有"实验记录"

在传统开发中，我们有 commit message、有 code review、有技术文档。但对于 AI 辅助编程来说，这些机制完全失效了——因为 AI 生成代码的速度极快，而且往往在多轮对话中逐步完善，没有任何单一节点对应最终产出。

Spec Kit Framework 引入了强制性的文档化门槛。其核心是一个三门（3-Gate）系统：

当用户执行类似 /speckit:complete Build a user authentication system 这样的命令时，框架会自动：创建对应 Spec 文件夹 → 运行研究 Agent 收集信息 → 生成实现计划 → 分配给相应 Agent 执行 → 在执行过程中持续更新 Spec 文档。所有这些都保存在本地 SQLite 数据库中，下次打开会话时，AI 会自动加载所有相关记忆。

四级文档深度，满足不同复杂度

级别	规模	必需文件	适用场景
Level 1	< 100 行	spec.md, plan.md, tasks.md, implementation-summary.md	小功能、Bug 修复
Level 2	100-499 行	Level 1 + checklist.md	需要 QA 验证、多文件变更
Level 3	500+ 行	Level 2 + decision-record.md	架构变更、复杂重构
Level 3+	复杂度 80+	Level 3 + 审批流程、合规检查	高复杂度项目协调

Cognitive Memory：本地优先的 RAG 系统

Skilled 的记忆引擎是一个完全本地化运行的 RAG（检索增强生成）系统，不依赖任何云服务。它的工作方式非常优雅：

1. 向量嵌入层：使用 Nomic Embed Text v1.5（768 维）模型将记忆文本转换为向量，默认通过本地 Ollama 服务运行，也可以回退到 HuggingFace Local（纯 Node.js 实现，无需 Python 环境）或 OpenAI/Voyage 云端 API。

2. 混合检索：不是简单的语义相似度匹配，而是将 RAG 语义搜索与**图感知（Graph-Aware）**项目上下文结合。当检索"支付模块"时，系统不仅能找到语义相关的内容，还能理解代码库中各模块之间的依赖关系和调用链路。

3. IPC 架构：记忆引擎以独立的 MCP 服务器进程运行（mk-spec-memory），与 AI 编码助手之间通过 Unix Socket 进行 IPC 通信，多个客户端可以同时连接。

这意味着：即使 Ollama 服务重启，只要数据库文件在，记忆就不会丢失。而且整个系统不依赖任何外部网络——对于企业内网环境，这一点极为关键。

12 个专业 Agent，20 个按需技能

框架内置了 12 个专业 Agent，分别负责不同的职责领域：实现 Agent、审查 Agent、研究 Agent、文档 Agent、Git Agent 等。它们通过 Skill Advisor 路由系统进行协调——根据用户请求中的关键词，动态加载最相关的技能模块。

20 个内置技能包括：

• sk-code：针对不同编程语言和框架的代码实现模式
• system-spec-kit：规范套件管理
• sk-doc：文档生成
• sk-git：Git 操作
• system-deep-loop：深度研究循环
• cli-external-orchestration：CLI 外部编排
• mcp-tooling：MCP 工具集成

这些技能是可扩展的。开发者可以 Fork 框架后，在 .opencode/skills/<your-skill>/ 目录下添加自己的技能包，框架会自动发现并加载。

技术架构：TypeScript + MCP 原生设计

从代码结构来看，Skilled 是一个高度工程化的 TypeScript 项目，而非粗糙的概念验证（PoC）：

• 主语言：TypeScript，IDE 支持完善
• MCP 协议：5 个原生 MCP 服务器，各自在独立进程中运行，通过 Unix Socket 进行进程间通信
• 依赖管理：npm，根目录仅有 3 个轻量依赖（chokidar、cors、express），用于文件监控和内部 HTTP 服务
• 启动自举：每个 MCP 服务器都有独立的 launcher 脚本（.cjs），首次运行时会自动下载并打包所需依赖，用户无需全局安装 TypeScript
• 嵌入模型：推荐 Ollama + Nomic Embed Text v1.5，也可选择 OpenAI Embeddings 或 Voyage AI（需要 API Key）
• 数据库：SQLite，本地文件，无服务依赖

上手门槛：Node.js 环境 + 愿意改变工作习惯

Skilled 不是那种"一键安装即用"的工具。它的部署门槛主要在于理念认同，而非技术复杂性：

最低要求：Node.js 18+、npm、git、POSIX shell，推荐 8GB+ 内存（运行本地 embedding 模型时需要）。

部署复杂度：中等。需要理解 MCP 协议的基本概念，以及框架的"文档优先"理念。

不支持的场景：没有 Web UI，不是一个独立运行的 Web 服务，本质上是一套配置层和协议层，必须与 OpenCode、Claude Code 等 AI 编码 CLI 配合使用。

争议与局限

尽管 Skilled 解决了 AI 编程中的真实痛点，但也存在一些值得关注的局限：

1. 记忆质量依赖 AI 本身：如果 AI 在 Spec 文件夹中写入了错误或过时的信息，记忆引擎会忠实地存储并检索这些信息，导致"垃圾进、垃圾出"的问题。

2. 三门系统的严格性：Gate 3 是硬拦截，理论上保证了文档质量，但也意味着 AI 不能"先写代码再补文档"。对于快速原型探索场景，这种约束反而可能降低效率。

3. TypeScript Only：框架本身是 TypeScript 项目，Python 开发者使用门槛略高。

4. 相对小众：31 stars、3 forks、1 个 open issue，生态还很早期。大量采用前需要关注社区活跃度。

行业意义：从"工具"到"协作伙伴"的范式转变

Skilled 最有价值的地方，不是它的某个具体功能，而是它提出的核心理念：AI 编程助手不应该是一个有健忘症的临时工具，而应该是项目生命周期内持续学习、持续记忆的协作伙伴。

项目信息：GitHub: https://github.com/MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory | 语言: TypeScript | 许可: MIT | Stars: 31

图：Skilled 框架架构总览