KoiWeave — 构建企业级持续进化的研发知识中枢(LLM-WIKI)

KoiWeave — 编织。把分散的代码仓库、零散的知识、不同时间尺度的工作流，织成一张有韧性、不断进化的网

当代码仓库越 split，知识越需要 unite。

KoiWeave 点个赞！给个支持！

一、写在前面

先承认一个事实：AI 写代码已经很快了，但 AI 不知道你之前为什么那么写。

这就是当前 AI-assisted 开发的核心矛盾——代码生成效率上去了，但知识复用率没跟上。每个微服务仓库各自为政，A 服务踩过的坑，B 服务照踩不误；三个月前的架构决策，新来的 AI 会话一无所知。

Karpathy 提出过 LLM Wiki 模式：raw/ → LLM compile → wiki/。但那是个人知识管理，不适合多仓库微服务团队。

本文要分享的是一个在生产环境可落地的持续进化知识中枢架构，解决三个核心问题：

1. 知识从哪来—— 自动从代码变更中提取，不是人写
2. 知识怎么流—— 跨仓库自动同步，不手动拷贝
3. 知识怎么活—— 定期保鲜、自动检测矛盾，不腐烂

二、工具栈与环境

核心依赖 (npm)

{"dependencies":{"@opencode-ai/plugin":"^1.17.0"}}

全局安装

npminstall-g@fission-ai/openspec@latestnpminstall-g@cubocompany/opengem@latest

三、设计哲学：三环进化架构

整个体系的核心不是目录结构，而是知识在三个时间尺度上的自动进化：

┌─────────────────────────────────────────────────────────────────────┐ │ 三环持续进化架构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 微循环（每次变更 ~ 秒级） 日循环（每天 ~ 分钟级） │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ OpenSpec archive│ │ 健康检查触发 │ │ │ │ ↓ │ │ ↓ │ │ │ │ AI 分析 diff │ │ 术语一致性扫描 │ │ │ │ ↓ │ │ 链接完整性检查 │ │ │ │ 提取新实体/ADR │ │ 时效性检查 │ │ │ │ ↓ │ │ 矛盾检测 │ │ │ │ 更新 wiki/ │ │ ↓ │ │ │ │ OpenGem → Obsidian│ │ 报告输出 │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ 周循环（每周 ~ 小时级） │ │ ┌──────────────────────────────────────┐ │ │ │ 模式识别 → 知识缺口检测 → 债务推断 │ │ │ │ ↓ │ │ │ │ 生成周报 + 自动创建 OpenSpec proposal │ │ │ └──────────────────────────────────────┘ │ │ │ │ 三个循环独立运转，构成知识库的"新陈代谢"系统 │ │ 不需要人主动维护，AI 自动完成采集→提炼→保鲜→报告 │ └─────────────────────────────────────────────────────────────────────┘

三环的分工逻辑

四、仓库架构

4.1 整体布局

┌─────────────────────────────────────────────────────────────────┐ │ 多仓库知识编织架构 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ KoiWeave（知识中枢） │ │ ┌─────────────────────────┐ │ │ │ signals/ │ │ │ │ auto-ingest/ ◀──────────────┐ │ │ │ wiki/ │ │ │ │ │ entities/ │ │ │ │ │ modules/ │ │ │ │ │ concepts/ │ │ │ │ │ architecture/ │ │ │ │ └──────────┬──────────────┘ │ │ │ │ │ │ │ OpenGem (push) │ │ │ │ │ │ │ ▼ │ │ │ Obsidian Vault │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ │ service-auth │ │ service-order│ │service-pay │ │ │ │ │ AGENTS.md │ │ AGENTS.md │ │ AGENTS.md │ │ │ │ │ MANIFEST │ │ MANIFEST │ │ MANIFEST │ │ │ │ │ openspec/ │ │ openspec/ │ │ openspec/ │ │ │ │ └──────┬───────┘ └──────┬───────┘ └──────┬─────┘ │ │ │ └─────────────────┼──────────────────┘ │ │ │ │ 归档时自动回流 │ │ │ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘

4.2 知识中枢仓库 (KoiWeave / koi-llm-wiki/)

这是整个体系的"大脑"。它不存放任何业务代码，只存放结构化的知识。

koi-llm-wiki/ ├── AGENTS.md # AI 行为宪法（最重要的文件） ├── log.md # 全局操作日志 │ ├── signals/ # [输入层] 所有知识的原始信号源 │ ├── inbox/ # 收集箱（人工拖入） │ ├── auto-ingest/ # 自动回流素材（各服务归档时写入） │ │ ├── service-auth/ │ │ ├── service-order/ │ │ └── service-payment/ │ ├── requirements/ # 产品需求文档 │ └── references/ # 外部技术文档 │ ├── wiki/ # [知识层] AI 维护的结构化知识 │ ├── INDEX.md # 全局索引地图（AI 自动维护） │ ├── MANIFEST.md # 知识保鲜清单 │ ├── concepts/ # 抽象概念（Event-Loop, CQRS, RBAC） │ ├── entities/ # 业务实体（User, Order, Payment） │ ├── modules/ # 功能模块设计（auth, order, payment） │ ├── architecture/ │ │ ├── decisions/ # ADR（代码归档时自动生成） │ │ ├── proposals/ # 跨服务设计提案（轻量文档） │ │ └── diagrams/ # C4 架构图（Mermaid） │ ├── summaries/ # 长文档 AI 摘要 │ └── glossary/ # 术语表（跨文章一致性保证） │ ├── ops/ # [运维层] 自动化脚本 │ ├── health-check.sh │ ├── sync-obsidian.sh │ └── report-weekly.sh │ └── outputs/ # [衍生物] 周报、图表 └── reports/

4.3 微服务仓库 (service-xxx/)

每个服务仓库只增加两个东西：一个 AGENTS.md 和一个.wiki-context/目录。

service-auth/ ├── AGENTS.md # 指向知识中枢的导航指令 ├── .wiki-context/ # 知识投射层（指针文件，无实体数据） │ ├── MANIFEST.md # 本服务相关的 wiki 路径索引 │ ├── STATUS.md # 同步状态（🟢最新/🔴落后/⚠️冲突） │ └── SYNC_LOG.md # 完整的推送/拉取操作日志 ├── openspec/ # 服务级别的 OpenSpec 变更 │ ├── changes/ │ │ ├── add-phone-login/ │ │ │ ├── proposal.md │ │ │ ├── design.md │ │ │ ├── tasks.md │ │ │ └── specs/ │ │ └── ... │ └── specs/ ├── src/ └── tests/

关键设计决策：知识中枢仓库不包含openspec/。因为 OpenSpec 的生命周期需要 apply（代码变更），而知识中枢只存知识不存代码。所有的变更发生在各自的微服务仓库中。

五、最核心的机制：知识如何流动

5.1 微循环：从代码变更到知识提取

当开发者在 service-auth 中完成一个 OpenSpec change 并执行archive时：

OpenSpec Archive 触发 │ ▼ AI 分析变更 diff │ ┌───────────┼───────────┐ ▼ ▼ ▼ 新增实体 修改模块 架构决策 │ │ │ ▼ ▼ ▼ wiki/entities/ wiki/modules/ ADR 自动生成 User.md auth-module/ │ ▼ 回流信息写入 signals/auto-ingest/service-auth/ │ ▼ OpenGem (push) │ ▼ Obsidian 知识库

这个过程不需要任何人介入——AI 自动 diff 分析、自动提取、自动写入。

5.2 拉取：服务启动时如何获取最新知识

这是整个架构中最实际的工程问题。知识中枢和各服务仓库是独立的 git 仓库，AI 在服务仓库中启动时，通过三级路径解析找到知识中枢：

AI 路径解析优先级： P0: $KOI_WIKI_PATH 环境变量 ← 推荐，团队标准化 P1: git submodule .wiki-context/ ← 开箱即用 P2: ../koi-llm-wiki/ 相对路径 ← 本地开发约定 P3: 自动 clone 到 ~/.koi-wiki/ ← 零配置兜底

AI 启动时的完整流程：

┌──────────────────────────────────────────────────────────┐ │ 服务仓库中 AI 启动完整流程 │ ├──────────────────────────────────────────────────────────┤ │ │ │ Step 0: 路径解析 │ │ ├── P0 $KOI_WIKI_PATH → 存在？ │ │ ├── P1 submodule → 初始化？ │ │ ├── P2 相对路径 → 存在？ │ │ └── P3 自动 clone → 执行 clone │ │ │ │ Step 1: 同步状态检查 │ │ ├── 读取 STATUS.md → 获取本地 WIKI_HEAD │ │ ├── git fetch 远程 → 获取最新 HEAD │ │ ├── 一致？ → 🟢 跳过 │ │ └── 不一致？ → 🔴 执行 pull │ │ │ │ Step 2: 加载知识 │ │ ├── 读取 MANIFEST.md → 获取知识索引 │ │ ├── ADR → 理解历史决策 │ │ ├── 实体 → 确保数据模型一致 │ │ ├── 模块 → 理解当前架构 │ │ └── 提案 → 了解进行中的变更 │ │ │ │ Step 3: 开始开发 │ │ └── AI 基于完整上下文编写代码 │ │ │ └──────────────────────────────────────────────────────────┘

5.3 同步日志与状态追踪

每个服务的.wiki-context/中维护两个关键文件：

STATUS.md：精简状态，AI 一眼判断知识是否最新。

# Wiki Context Status — service-auth | 字段 | 值 | |---|---| | 最后拉取 (Pull) | 2026-07-02 10:30:00 | | 知识中枢 HEAD | `abc1234` | | 知识中枢最新 HEAD | `def5678` | | 同步状态 | 🔴 落后 3 次提交 | | 未推送的回流 | 0 条 |

SYNC_LOG.md：完整的操作审计日志。

# Sync Log — service-auth ## Pull（从知识中枢拉取） | 时间 | 操作 | 拉取版本 | 涉及内容 | 结果 | |---|---|---|---|---| | 2026-07-02 10:30 | pull | `abc1234` | entities/User, modules/auth | ✅ | ## Push（向知识中枢回流） | 时间 | 操作 | 关联 Change | 推送内容 | 结果 | |---|---|---|---|---| | 2026-07-02 11:00 | push | add-phone-login | 新实体 PhoneLogin | ✅ 已接收 |

状态文件的意义：AI 在开始工作前通过 STATUS.md 知道自己持有的知识是否是"最新版"，避免基于过期知识做决策。

六、AGENTS.md：整个体系的宪法

AGENTS.md是这个体系中最关键的文件。OpenCode 每次启动时自动加载。它定义了 AI 的行为规则。

知识中枢的 AGENTS.md

# AGENTS.md — koi-llm-wiki 知识中枢 ## 目录语义 - signals/: 只读输入区，不修改原始内容 - wiki/: AI 维护区，按规则增删改 - ops/: 脚本执行区，不修改 ## 知识维护规则 1. 写入知识时必须引用 glossary/ 中的术语 2. 每篇文章必须包含 [[链接]] 指向关联概念 3. 新概念出现时，先检查 glossary 是否存在 4. 修改知识时同步更新 INDEX.md 5. 从 auto-ingest/ 提取知识后标记来源路径

微服务仓库的 AGENTS.md

# AGENTS.md — service-auth ## 知识源 知识中枢路径（按优先级）： P0: $KOI_WIKI_PATH P1: ../koi-llm-wiki/ ## 强制流程 Step 0: 读取 STATUS.md → 如果 🔴 落后，先 pull Step 1: 读取 MANIFEST.md → 加载 ADR → 实体 → 模块 Step 2: 变更前对比 wiki 与代码，有差异先更新 wiki Step 3: OpenSpec archive 时自动回流知识

AGENTS.md 不是建议，是强制指令。AI 不能跳过"读 wiki"这一步。

七、术语表：知识一致性的底线

多服务多仓库最怕的是同一个概念在不同地方叫法不同。术语表解决的就是这个问题。

wiki/glossary/index.md | 术语 | 英文 | 定义 | |---|---|---| | 知识中枢 | Knowledge Hub | 存储所有结构化知识的仓库 | | 信号 | Signal | 输入知识中枢的原始素材 | | 投射 | Projection | 服务仓库通过 .wiki-context/ 投影知识 | | 回流 | Backflow | 归档时将知识提取写回中枢 | | 保鲜 | Freshness | 定期审核知识准确性 | | 三环 | Three Loops | 微循环/日循环/周循环 |

AI 写入任何 wiki 页面时，必须先查术语表。新术语出现，先补充到术语表再使用。这就从根源上杜绝了"一个概念三个名字"的问题。

八、日循环：知识的保鲜机制

知识像生鲜，不及时处理就会腐烂。日循环脚本负责每天自动检查：

ops/health-check.sh │ ├── ① 术语一致性扫描 │ 检查 glossary/ 中的术语在各页面使用是否一致 │ ├── ② 链接完整性检查 │ 检查 [[wiki/entities/User]] 之类的链接是否有效 │ ├── ③ 时效性检查 │ MANIFEST.md 中超过 30 天未审核的标记为 stale │ ├── ④ 矛盾检测（计划中） │ 同一实体在不同页面的描述是否冲突（需语义分析） │ └── ⑤ 报告输出 → log.md + outputs/reports/

检测到 stale 页面后，AI 会自动决定是重写、补充还是标记待删除。

九、多仓库协作：跨服务架构变更怎么办

这是一个常见的场景：需要统一 SSO 方案，涉及 auth、order、payment 三个服务。

方案是不用复杂的编排工具，用共享知识驱动：

1. 写提案（轻量文档） 人（或 AI）在 wiki 仓库创建： wiki/architecture/proposals/unified-sso.md ├── 背景与动机 ├── 方案选型对比（OAuth2 vs SAML vs 自建） ├── 各服务改动点清单 └── 接口契约定义 2. 各服务自主消费 service-auth 启动 OpenCode： AGENTS.md → 读取所有 proposals/ AI 看到 unified-sso.md → 在 service-auth/openspec 创建 change → 实现 auth 侧的 SSO 改动 service-order、service-payment 同理 3. 各自回流 各服务 archive 时各自回流知识 日检发现原提案中标记的改动点已全部完成 → 在 proposal 中追加完成状态

不需要中央编排。proposal 是知识，不是变更。各服务通过 AGENTS.md 的强制读取指令"自动对齐"。

十、回答几个关键质疑

Q1: 这和 Copilot + Confluence 有什么区别？

Copilot 不读你的 wiki。Confluence 不会自动从 git diff 中提取知识。这个体系的核心是闭环——代码变更自动驱动知识更新，知识又反过来指导代码变更。不是文档工具，是知识代谢系统。

Q2: AI 真的能准确提取知识吗？

不需要"完美"提取。提取后写入signals/auto-ingest/，日检时 AI 会二次校验。而且提取的任务是结构化的——识别新实体、提取决策理由、记录修改点——这些 GPT/Claude 级别的模型做得相当好。

Q3: 服务多了怎么办？（10+ 微服务）

加一个服务只需两步：

1. 在服务仓库中创建AGENTS.md+.wiki-context/MANIFEST.md
2. 在知识中枢创建signals/auto-ingest/service-xxx/

剩余的（知识拉取、同步检查、归档回流）全部自动。

Q4: 谁维护 wiki？会不会变成另一个僵尸文档库？

答案写在三环里：

• 微循环保证每次代码变更都有知识回流，不回流无法 archive
• 日循环保证每天检查知识是否过时
• 周循环保证发现知识缺口

知识不是"写"出来的，是"流"出来的。只要代码在变，知识就在更新。

十一、收益与成本

收益

成本

十二、总结

这个架构不是发明了新工具，而是把四个已有的东西（OpenCode、OpenSpec、OpenGem、Obsidian）用一套知识流动规则串了起来。本质上做了一件简单的事：

让 AI 在写代码前必须读完相关的历史知识，在写完后必须把新知识吐回来。

听起来简单，但做到之后的效果是：

• 知识不靠人写，靠代码变更自动产生
• 知识不等人喂，靠日检周检自动保鲜
• 知识不锁在单仓库，靠三环机制跨服务流动

Karpathy 的 LLM Wiki 证明了raw → AI → wiki模式对个人的有效性。这个架构试图回答的是：当你有十几个微服务、几百个开发者、几千次 commit 的时候，这个模式怎么 work。

答案就是三环 + 投射 + 回流。没有魔法，只有工程。

koi-llm-wiki/ AGENTS.md ← 一切从这里开始 signals/inbox/ ← 你的第一个素材 wiki/MANIFEST.md ← 第一条知识的保鲜记录 service-auth/ AGENTS.md ← 指向知识中枢的桥梁 .wiki-context/STATUS.md ← 同步日志准备好了 openspec/changes/ ← 第一个 change 等你去 propose 你没有来晚，知识中枢才刚刚初始化。

全文完。如果你也在搭建 AI-assisted 开发的知识体系，欢迎交流。