KoiWeave — 编织。把分散的代码仓库、零散的知识、不同时间尺度的工作流织成一张有韧性、不断进化的网当代码仓库越 split知识越需要 unite。KoiWeave 点个赞给个支持一、写在前面先承认一个事实AI 写代码已经很快了但 AI 不知道你之前为什么那么写。这就是当前 AI-assisted 开发的核心矛盾——代码生成效率上去了但知识复用率没跟上。每个微服务仓库各自为政A 服务踩过的坑B 服务照踩不误三个月前的架构决策新来的 AI 会话一无所知。Karpathy 提出过 LLM Wiki 模式raw/ → LLM compile → wiki/。但那是个人知识管理不适合多仓库微服务团队。本文要分享的是一个在生产环境可落地的持续进化知识中枢架构解决三个核心问题知识从哪来—— 自动从代码变更中提取不是人写知识怎么流—— 跨仓库自动同步不手动拷贝知识怎么活—— 定期保鲜、自动检测矛盾不腐烂二、工具栈与环境分类工具版本作用AI 编码助手OpenCodelatestAI 编程会话的入口承载 AGENTS.md 宪法规范驱动开发OpenSpec 1.0propose → apply → archive 变更生命周期管理知识库桥接cubocompany/opengem 0.7OpenCode 连接 Obsidian 的插件桥知识管理Obsidianlatest本地优先的知识库前端用户阅读/搜索的界面版本控制Git GitHub/GitLab—所有仓库的版本管理和协作基础运行时Node.js 20.19.0—OpenSpec CLI 运行环境Shellbash—自动化运维脚本执行环境核心依赖 (npm){dependencies:{opencode-ai/plugin:^1.17.0}}全局安装npminstall-gfission-ai/openspeclatestnpminstall-gcubocompany/opengemlatest三、设计哲学三环进化架构整个体系的核心不是目录结构而是知识在三个时间尺度上的自动进化┌─────────────────────────────────────────────────────────────────────┐ │ 三环持续进化架构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 微循环每次变更 ~ 秒级 日循环每天 ~ 分钟级 │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ OpenSpec archive│ │ 健康检查触发 │ │ │ │ ↓ │ │ ↓ │ │ │ │ AI 分析 diff │ │ 术语一致性扫描 │ │ │ │ ↓ │ │ 链接完整性检查 │ │ │ │ 提取新实体/ADR │ │ 时效性检查 │ │ │ │ ↓ │ │ 矛盾检测 │ │ │ │ 更新 wiki/ │ │ ↓ │ │ │ │ OpenGem → Obsidian│ │ 报告输出 │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ 周循环每周 ~ 小时级 │ │ ┌──────────────────────────────────────┐ │ │ │ 模式识别 → 知识缺口检测 → 债务推断 │ │ │ │ ↓ │ │ │ │ 生成周报 自动创建 OpenSpec proposal │ │ │ └──────────────────────────────────────┘ │ │ │ │ 三个循环独立运转构成知识库的新陈代谢系统 │ │ 不需要人主动维护AI 自动完成采集→提炼→保鲜→报告 │ └─────────────────────────────────────────────────────────────────────┘三环的分工逻辑环触发条件耗时AI 自主性人的角色微循环代码归档秒级100% 自动只需 review 代码日循环cron / hook分钟级100% 自动浏览报告周循环定时小时级分析自动行动建议决策是否采纳四、仓库架构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 微服务加一个服务只需两步在服务仓库中创建AGENTS.md.wiki-context/MANIFEST.md在知识中枢创建signals/auto-ingest/service-xxx/剩余的知识拉取、同步检查、归档回流全部自动。Q4: 谁维护 wiki会不会变成另一个僵尸文档库答案写在三环里微循环保证每次代码变更都有知识回流不回流无法 archive日循环保证每天检查知识是否过时周循环保证发现知识缺口知识不是写出来的是流出来的。只要代码在变知识就在更新。十一、收益与成本收益收益原理不重复决策AI 写代码前读完 ADR你不会再做同样的技术选型讨论不重复踩坑别的服务遇到的坑记录在 wikiAI 帮你自动避开跨服务一致性所有服务读同一个实体定义、同一个接口契约新人上手快AGENTS.md MANIFEST.md 就是一份精准的 on-boarding 地图知识不腐烂日检自动过期、周检自动填补缺口零维护负担不需要人写文档不需要人更新 wiki成本成本评估初始搭建1-2 天目录结构 AGENTS.md 三环脚本服务接入每个服务 10 分钟AGENTS.md MANIFEST.md运维开销三个 shell 脚本跑一次几秒钟学习曲线理解概念半天日常使用零上手十二、总结这个架构不是发明了新工具而是把四个已有的东西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 开发的知识体系欢迎交流。