OpenSpec × Karpathy LLM Wiki 融合研究报告

研究时间：2026-04-15 调研对象：[open-wiki-spec](https://github.com/sh940701/open-wiki-spec) · [OpenSpecPowers](https://github.com/seanf-ai/OpenSpecPowers) · [conflux](https://github.com/tumf/conflux) · [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)

一、核心发现

已经存在一个成熟的开源项目直接解决了 OpenSpec 与 Karpathy LLM Wiki 的融合问题：

[sh940701/open-wiki-spec](https://github.com/sh940701/open-wiki-spec) (ows CLI) ⭐

将 Karpathy LLM Wiki 的持久知识层 × OpenSpec 的变更管理融为一体

这是目前最完整的融合方案，也是我们最值得参考的蓝本。

二、OpenSpec 生态全览

项目	定位	核心技术
Fission-AI/OpenSpec	原始规范驱动开发框架	Spec → Change → Verification 生命周期
sh940701/open-wiki-spec	OpenSpec + LLM Wiki 融合	typed markdown vault + 6种笔记类型 + 确定检索引擎
seanf-ai/OpenSpecPowers	OpenSpec 的增强工具层	轻量级 power commands，20+ AI 助手兼容
tumf/conflux	OpenSpec 的并行化扩展	并发 worktree 自动化执行 OpenSpec 变更

三、open-wiki-spec 核心设计（融合关键）

3.1 两个框架各自的强项

Karpathy LLM Wiki 提供	OpenSpec 提供
持久、不断积累的知识层	"当前状态"与"变更提议"的严格分离
wiki 是主要工作界面	变更是有独立证据、验证、生命周期跟踪的单元
LLM 维护 wiki，人类审查	Agent 工作流有明确阶段（propose → apply → verify → archive）
`index.md`、`log.md` 导航	Verification + Validation 机制保证一致性

3.2 融合的核心理念


"The LLM is not a search engine — it's a programmer.
 Give it a wiki, not a filesystem."



核心洞察：

Karpathy LLM Wiki 的问题是"有结构但无约束"——wiki 积累多了，质量参差不齐，容易变成垃圾堆
OpenSpec 的问题是"有流程但无记忆"——每个 session 从零开始，历史决策和设计 rationale 丢失在 chat history 里
两者互补：Wiki 给 OpenSpec 提供持久记忆，OpenSpec 给 Wiki 提供结构化流程


3.3 六种笔记类型（typed markdown vault）

open-wiki-spec 定义了 6 种互有关联的笔记类型，构成知识图谱：

笔记类型 作用 对应 OpenSpec
Feature 当前行为的规范说明 替代 OpenSpec 的 spec.md
Change 提议或进行中的工作单元 对应 OpenSpec 的 changes/
System 技术边界/组件上下文 新的维度
Decision 设计决策及其依据 新的维度（OpenSpec 分散在 design.md）
Source 证据：PRD、Issue、会议记录、代码阅读笔记 新的维度
Query 调查笔记和捕获的分析结果 新的维度（可写回 wiki 的好答案）

3.4 确定检索子代理架构（关键创新！）

这是 open-wiki-spec 相对于 Karpathy 原版模式最大的技术升级——在创建任何新工作之前，运行强制预检检索扫描，不是 LLM 猜，是机械化的评分：

笔记类型	作用	对应 OpenSpec
Feature	当前行为的规范说明	替代 OpenSpec 的 spec.md
Change	提议或进行中的工作单元	对应 OpenSpec 的 changes/
System	技术边界/组件上下文	新的维度
Decision	设计决策及其依据	新的维度（OpenSpec 分散在 design.md）
Source	证据：PRD、Issue、会议记录、代码阅读笔记	新的维度
Query	调查笔记和捕获的分析结果	新的维度（可写回 wiki 的好答案）


用户请求
   │
   ▼
┌──────────────────────────────────────────┐
│  Main Agent（Claude Code 等）             │
│                                          │
│  1. 解析用户请求                         │
│  2. 调用检索子代理 ───────────────┐       │
│  4. 读取分类 + 候选列表        │       │
│  5. 做出最终工作决策            │       │
└──────────────────────────────────────┘       │
                          ▼                    │
                    Retrieval Subagent         │
                    （ows CLI）                │
                          │                    │
         ┌────────────────┼────────────────┐  │
         │  a. 构建 vault 索引            │  │
         │  b. 标准化查询                  │  │
         │  c. 词汇检索（BM25）            │  │
         │  d. 图扩展（1跳邻居）           │  │
         │  e. 加权评分排序               │  │
         │  f. 规则分类                   │  │
         │  g. 返回结构化结果             │  │
         └────────────────────────────────┘  │



评分信号（规则驱动，非 LLM 自由判断）：

信号 权重
精确标题匹配 +40
别名匹配 +35
语义相似度 +30
活跃 Change 重叠 +25
同 System +20
同 Feature 链接 +20
部分标题匹配 +20
全文匹配 +15 / +8
共享 Source +10
共享 Decision +10
反向链接邻近度 +10

分类结果（规则阈值）：

分类 含义 Agent 动作
existing_change 同目的的活跃 Change 已存在 继续它
existing_feature 匹配的 Feature 存在 创建新 Change 附加到它
new_feature 未找到相似项 创建新 Feature + Change
needs_confirmation 结果模糊 询问用户选择

3.5 Change 生命周期

信号	权重
精确标题匹配	+40
别名匹配	+35
语义相似度	+30
活跃 Change 重叠	+25
同 System	+20
同 Feature 链接	+20
部分标题匹配	+20
全文匹配	+15 / +8
共享 Source	+10
共享 Decision	+10
反向链接邻近度	+10

分类	含义	Agent 动作
existing_change	同目的的活跃 Change 已存在	继续它
existing_feature	匹配的 Feature 存在	创建新 Change 附加到它
new_feature	未找到相似项	创建新 Feature + Change
needs_confirmation	结果模糊	询问用户选择


proposed → planned → in_progress → applied → (archived)




proposed：初始描述，检索扫描完成
planned：Why、Delta Summary、Tasks、Validation 部分填写完毕
in_progress：正在实现，tasks 被勾选
applied：规范笔记更新，反映变更
archived：归档到 99-archive/


3.6 Vault 目录结构


wiki/
  00-meta/         # Vault 元数据（schema、log、conventions）
  01-sources/      # 外部引用和文档
  02-systems/      # 系统/组件架构
  03-features/     # 功能规范（含需求）
  04-changes/      # 活跃变更（proposed → applied）
  05-decisions/    # 设计决策及依据
  06-queries/      # 调查笔记
  99-archive/      # 已完成变更



3.7 CLI 命令

命令 说明
ows init 初始化 vault
ows propose 提议新变更（带预检检索）
ows continue 继续已有变更
ows apply 将变更应用到规范笔记
ows verify 验证 vault 一致性（4个维度）
ows query 搜索 vault 图
ows status 显示变更状态和下一步
ows archive 归档已完成的变更
ows retrieve 独立检索扫描（只读）
ows migrate 从 OpenSpec 格式迁移



四、融合对我们现有工作的价值

4.1 当前 Vad-agents/OpenSpec 的局限

我们的 SPEC-DRIVEN-AI 方案（四阶段：意图定义 → 技术规划 → 任务分解 → 自动化执行）有明确的流程，但缺失：

缺失维度 现状 LLM Wiki 能补充
持久记忆 每个 session 从文件系统重新读取 wiki 中积累设计决策、历史上下文
跨 session 积累 换 session 什么都没了 Feature/Decision 页面长期维护
来源追溯 分散在 chat history Source 笔记：PRD/Issue/会议记录
变更前的预检 靠 LLM 猜是否已有类似变更 规则检索 + 评分分类
wiki 自然生长 规范是静态文档 每次变更/查询都让 wiki 更丰富

4.2 可以在 Vad-agents 中借鉴的设计

方案 A：吸收检索子代理到 vad-skill

命令	说明
ows init	初始化 vault
ows propose	提议新变更（带预检检索）
ows continue	继续已有变更
ows apply	将变更应用到规范笔记
ows verify	验证 vault 一致性（4个维度）
ows query	搜索 vault 图
ows status	显示变更状态和下一步
ows archive	归档已完成的变更
ows retrieve	独立检索扫描（只读）
ows migrate	从 OpenSpec 格式迁移

缺失维度	现状	LLM Wiki 能补充
持久记忆	每个 session 从文件系统重新读取	wiki 中积累设计决策、历史上下文
跨 session 积累	换 session 什么都没了	Feature/Decision 页面长期维护
来源追溯	分散在 chat history	Source 笔记：PRD/Issue/会议记录
变更前的预检	靠 LLM 猜是否已有类似变更	规则检索 + 评分分类
wiki 自然生长	规范是静态文档	每次变更/查询都让 wiki 更丰富

在 vad-skill:plan 之前增加 preflight retrieval 步骤

扫描现有的 docs/specs/ 或 docs/design/ 目录


规则驱动评分，避免 LLM 重复发现已有方案



方案 B：增加笔记类型到现有流程

引入 Decision 笔记（当前分散在 design.md）
引入 Source 笔记（PRD/需求来源）
引入 Query 笔记（调研结果可写回 wiki）


方案 C：参考 vault 结构组织知识

将 docs/requirements/ → wiki/03-features/

将 docs/design/ → wiki/05-decisions/

新增 wiki/01-sources/、wiki/06-queries/





五、在我们项目中落地建议

5.1 短期（1-2周）：借鉴思路，不引入新工具

在现有 vad-agents 框架内优化：

1. 在 vad-skill:plan 前增加"预检"步骤：调用 vad 命令扫描已有 specs，发现相似需求时提醒用户，避免重复开工


2. 规范文档增加 Source/Decision 分离：
   - 所有 spec.md 顶部的"来源"section（链接到原始 PRD/Issue）
   - 所有 design.md 中的"决策"单独成节，方便后续溯源

3. 增加 vad-skill:query 命令：让 AI 在 wiki（docs/）中搜索，而非每次从代码重新构建上下文



5.2 中期（1个月）：构建轻量版 LLM Wiki 层

参考 open-wiki-spec 的 6 种笔记类型，但不做完整迁移：

1. 新建 docs/wiki/ 目录：

- docs/wiki/sources/ — 原始需求文章、竞品分析、用户反馈

- docs/wiki/decisions/ — 架构决策记录

- docs/wiki/features/ — 现有功能规范

- docs/wiki/changes/ — 变更记录（参考 OpenSpec 的 changes/）

- docs/wiki/queries/ — 调研结果（可沉淀的问答）

- docs/wiki/log.md — append-only 时间线

2. 修改 vad-skill:plan：当用户提新需求时，先搜索 docs/wiki/ 中的相似内容，再制定计划

3. 修改 vad-skill:check：verify 阶段检查 wiki 一致性（变更后更新对应 Feature/Decision 页面）



5.3 长期（2-3个月）：引入 open-wiki-spec

如果项目规模足够大，考虑直接采用 ows CLI


或基于 open-wiki-spec 架构开发自己的 vad-wiki 工具
与 Claude Code/Cursor 等 IDE 深度集成





六、参考价值排序

优先级 项目 理由
⭐⭐⭐ open-wiki-spec 完整融合方案，6种类型笔记、检索子代理、vault 结构都有
⭐⭐ OpenSpecPowers 轻量增强，保持 OpenSpec 流程同时增加 power commands
⭐⭐ tumf/conflux 并行化思路，适用于多模块同时变更场景
⭐ Fission-AI/OpenSpec 原始框架，我们的 SPEC-DRIVEN-AI-FINAL.md 已深度研究



附：open-wiki-spec 完整生命周期示例

优先级	项目	理由
⭐⭐⭐	open-wiki-spec	完整融合方案，6种类型笔记、检索子代理、vault 结构都有
⭐⭐	OpenSpecPowers	轻量增强，保持 OpenSpec 流程同时增加 power commands
⭐⭐	tumf/conflux	并行化思路，适用于多模块同时变更场景
⭐	Fission-AI/OpenSpec	原始框架，我们的 SPEC-DRIVEN-AI-FINAL.md 已深度研究

`bash


1. 初始化
ows init

2. 提议变更（预检检索自动运行）
ows propose "Add user authentication" --keywords "auth,login"

3. 填充 Change 的 Why、Delta Summary、Tasks、Validation
   然后推进生命周期：
ows continue           # proposed → planned
ows continue          # planned → in_progress

4.完成任务，然后应用到规范 Feature
ows apply 

5.填充 Feature 笔记中的 ADDED/MODIFIED 标记
   验证一切一致
ows verify

6.归档完成的变更
ows archive



附：迁移路径（从现有 OpenSpec）

open-wiki-spec 提供了从 OpenSpec 格式迁移的完整工具：

OpenSpec → open-wiki-spec
specs//spec.md → wiki/03-features/.md
changes// (4文件) → wiki/04-changes/.md (单文件)
changes/archive/-/ → wiki/99-archive/-.md
config.yaml context → wiki/01-sources/project-context.md
design.md → wiki/05-decisions/`

OpenSpec	→	open-wiki-spec
specs//spec.md	→	wiki/03-features/.md
changes// `(4文件)`	→	wiki/04-changes/.md `(单文件)`
changes/archive/-/	→	wiki/99-archive/-.md
config.yaml `context`	→	wiki/01-sources/project-context.md
design.md	→	wiki/05-decisions/`