1. 研发知识为什么总在重复踩坑从 KoiWeave 与 LLM-WIKI 说起研发团队的知识沉淀长期卡在一个尴尬的位置代码仓库越拆越细知识却越来越散。A 服务三个月前踩过的序列化坑B 服务换个同学照样再踩一遍一次架构评审定下的鉴权边界等到新会话的 AI 助手接手时它一无所知只能凭当前代码猜。KoiWeave 想解决的就是这件事——把分散的代码仓库、零散的知识、不同时间尺度的工作流织成一张有韧性、能持续进化的网。它不是一个新编辑器也不是又一个文档站而是一套让知识随代码变更自动流动的工程规则。LLM-WIKI 是这套规则里的知识组织范式原始素材先进raw/或signals/由 LLM 编译成结构化的wiki/再由人审阅。Karpathy 提过这个模式对个人知识管理很有效但个人版放到多仓库微服务团队里会立刻失效——没人愿意手动把十几个仓库的变更抄进 wiki。所以 KoiWeave 在 LLM-WIKI 之上补了三件事知识从代码变更里自动提取、跨仓库自动同步、定期保鲜并检测矛盾。配合 OpenSpec 管变更生命周期、OpenCode 作为 AI 编码入口、Obsidian 作为本地优先的阅读前端整条链路才真正跑得起来。这篇文章适合三类人正在被“文档写完就过期”折磨的研发负责人、想给团队搭 AI 知识中枢的架构师、以及已经在用 OpenCode 或 Obsidian 但觉得知识还是散的开发者。下面我会给出可复制的目录结构、索引配置、增量更新脚本并完整演示一次从文档入库到检索验证的动作。你不需要一次搭全先跑通微循环再补日循环和周循环。先说清楚一个前提知识中枢仓库不存业务代码只存结构化知识。所有 OpenSpec 变更发生在各自的微服务仓库里因为变更需要apply落到代码而中枢只负责“记住为什么”。这个边界一旦模糊中枢就会退化成第二个代码仓库维护成本立刻失控。2. 前置准备TaoToken 接入与 OpenCode、OpenSpec 环境搭建在动手搭目录之前先把模型调用这条链路打通。KoiWeave 的微循环依赖 AI 分析 diff、提取实体、生成 ADR这些动作都要走模型接口。我用 TaoToken 作为统一入口它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的请求格式OpenCode、Cline 这类工具都能直接对接。官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content需要看文档或领 Key 从这里进。第一步拿到 API Key。进入控制台创建密钥路径是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后复制保存后面配置里要用。如果你还没决定用哪个模型可以先去模型对话页试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite确认响应风格符合预期再写进配置。第二步安装运行时和 CLI。OpenSpec 需要 Node.js 20.19.0 以上先确认版本node -v # 期望输出 v20.19.0 或更高 npm install -g fission-ai/openspeclatest npm install -g cubocompany/opengemlatest openspec --versioncubocompany/opengem是 OpenCode 连接 Obsidian 的桥接插件负责把 wiki 内容推送到 Vault。装完后在项目里初始化 OpenSpeccd service-auth openspec init # 生成 openspec/ 目录与 changes/、specs/ 子结构第三步配置 OpenCode 的模型接入。OpenCode 的配置文件通常放在项目根或用户目录我用项目级配置便于团队统一。新建或编辑opencode.json{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { claude-sonnet-4-5: { name: Claude Sonnet 4.5 } } } }, model: taotoken/claude-sonnet-4-5 }注意apiKey用环境变量注入不要把明文写进仓库。在 shell 里设置export TAOTOKEN_API_KEYsk-你的密钥 # 建议写进 ~/.bashrc 或 ~/.zshrc团队则用 .env 并加入 .gitignore如果你用的是 Claude Code 这类工具配置思路一致Base URL 填https://taotoken.net/apiKey 用刚创建的Model ID 填你选定的模型名。三件套缺一不可Base URL、API Key、Model ID。配置完成后跑一次连通性验证curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [{role: user, content: 回复 OK}] }返回里能看到choices数组且内容正常说明链路通了。这一步没过后面所有自动化都会卡在模型调用上所以务必先验证。环境就绪后我们进入目录结构设计。3. 可复制配置知识中枢目录、索引与增量更新脚本这一节是整篇最需要照着做的地方。先建知识中枢仓库我把它命名为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 # 全局索引地图 │ ├── MANIFEST.md # 保鲜清单 │ ├── concepts/ │ ├── entities/ │ ├── modules/ │ ├── architecture/ │ │ ├── decisions/ # ADR │ │ ├── proposals/ │ │ └── diagrams/ │ ├── summaries/ │ └── glossary/ ├── ops/ # 运维层脚本 │ ├── health-check.sh │ ├── sync-obsidian.sh │ └── report-weekly.sh └── outputs/ └── reports/建目录用一条命令即可mkdir -p koi-llm-wiki/{signals/{inbox,auto-ingest/{service-auth,service-order,service-payment},requirements,references},wiki/{concepts,entities,modules,architecture/{decisions,proposals,diagrams},summaries,glossary},ops,outputs/reports} cd koi-llm-wiki git init接着写wiki/INDEX.md它是 AI 检索知识的总入口。索引不要手写全部内容只维护“主题 → 路径 → 关键词”的映射让 AI 按需展开# 知识索引地图 ## 实体 | 实体 | 路径 | 关键词 | |---|---|---| | User | wiki/entities/User.md | 用户、账号、鉴权主体 | | Order | wiki/entities/Order.md | 订单、状态机、幂等 | | Payment | wiki/entities/Payment.md | 支付、回调、对账 | ## 模块 | 模块 | 路径 | 关键词 | |---|---|---| | auth | wiki/modules/auth-module.md | 登录、Token、SSO | | order | wiki/modules/order-module.md | 下单、取消、超时 | ## 架构决策 | ADR | 路径 | 状态 | |---|---|---| | ADR-001 统一鉴权 | wiki/architecture/decisions/ADR-001.md | accepted |然后是wiki/MANIFEST.md它记录每篇知识的保鲜状态日循环脚本靠它判断哪些页面过期# 知识保鲜清单 | 路径 | 最后审核 | 状态 | 负责人 | |---|---|---|---| | wiki/entities/User.md | 2026-07-01 | fresh | backend | | wiki/modules/auth-module.md | 2026-06-20 | stale | auth-team | | wiki/architecture/decisions/ADR-001.md | 2026-06-28 | fresh | arch |关键在增量更新脚本。微循环的核心是OpenSpec 归档时把变更 diff 交给模型分析提取新实体、模块改动、架构决策写回signals/auto-ingest/再触发 wiki 更新。下面这个ops/ingest.sh是可运行的骨架#!/usr/bin/env bash set -euo pipefail SERVICE${1:?用法: ingest.sh service-name change-id} CHANGE_ID${2:?缺少 change-id} WIKI_ROOT${KOI_WIKI_PATH:-$(cd $(dirname $0)/.. pwd)} INGEST_DIR$WIKI_ROOT/signals/auto-ingest/$SERVICE mkdir -p $INGEST_DIR # 1. 取本次 change 的 diff DIFF$(cd $SERVICE git diff HEAD~1 -- openspec/changes/$CHANGE_ID || true) if [ -z $DIFF ]; then echo 未检测到变更跳过; exit 0 fi # 2. 交给模型分析提取结构化知识 PROMPT你是知识提取器。阅读以下 OpenSpec 变更 diff输出 JSON {\entities\:[],\modules\:[],\decisions\:[],\summary\:\\} 只输出 JSON不要解释。diff 如下 $DIFF RESULT$(curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d $(jq -n --arg p $PROMPT {model:claude-sonnet-4-5,messages:[{role:user,content:$p}]})) # 3. 落盘到 auto-ingest等待日循环二次校验 echo $RESULT | jq -r .choices[0].message.content \ $INGEST_DIR/${CHANGE_ID}.json echo [$(date %F %T)] ingest $SERVICE/$CHANGE_ID 完成 $WIKI_ROOT/log.md脚本依赖jq没装先apt install jq或brew install jq。把它挂到 OpenSpec 归档钩子上每次openspec archive后自动执行chmod x ops/ingest.sh # 在 service-auth 的 openspec 配置里追加 post-archive 钩子 # 或手动./ops/ingest.sh service-auth add-phone-login再补一个同步到 Obsidian 的脚本ops/sync-obsidian.sh把wiki/推送到 Vault#!/usr/bin/env bash set -euo pipefail WIKI_ROOT${KOI_WIKI_PATH:-$(cd $(dirname $0)/.. pwd)} VAULT${OBSIDIAN_VAULT:?请设置 OBSIDIAN_VAULT 环境变量} rsync -av --delete $WIKI_ROOT/wiki/ $VAULT/KoiWeave/ echo [$(date %F %T)] sync to obsidian 完成 $WIKI_ROOT/log.mdOBSIDIAN_VAULT指向你的 Vault 根目录比如~/Documents/Obsidian/MyVault。这两个脚本加起来不到 60 行却构成了知识流动的骨架。配置写完后下一步就是验证它真的能跑。4. 验证请求从文档入库到检索的完整动作配置写完不验证等于没写。这一节我完整走一遍从文档入库到检索命中的动作你可以照着复现。假设service-auth刚完成一个add-phone-login变更我们要让知识中枢记住“新增了手机号登录实体”。第一步在服务仓库归档变更cd service-auth openspec archive add-phone-login # 归档后触发 post-archive 钩子自动调用 ops/ingest.sh如果钩子没配手动执行cd ../koi-llm-wiki ./ops/ingest.sh service-auth add-phone-login执行后检查回流素材是否落盘ls signals/auto-ingest/service-auth/ # 期望看到 add-phone-login.json cat signals/auto-ingest/service-auth/add-phone-login.json | jq .正常输出应该是一个 JSON包含entities、modules、decisions、summary四个字段。如果entities里出现PhoneLogin说明模型正确识别了新实体。这一步是微循环的产出但还没进 wiki需要日循环二次校验后写入。第二步手动触发一次日循环的保鲜检查。先写ops/health-check.sh的核心逻辑#!/usr/bin/env bash set -euo pipefail WIKI_ROOT${KOI_WIKI_PATH:-$(cd $(dirname $0)/.. pwd)} cd $WIKI_ROOT echo 术语一致性扫描 # 检查 glossary 中的术语是否在页面里被误写 for term in $(grep -oP ^\| \K[^|] wiki/glossary/index.md | sed s/ *$//); do grep -rl $term wiki/ /dev/null || echo 术语未使用: $term done echo 链接完整性检查 # 检查 [[...]] 链接指向的文件是否存在 grep -rhoP \[\[\K[^\]] wiki/ | while read -r link; do [ -f wiki/$link.md ] || echo 断链: $link done echo 时效性检查 # MANIFEST 中超过 30 天未审核的标记 stale awk -F| NR2 $3 ~ /[0-9]{4}-[0-9]{2}-[0-9]{2}/ { cmddate -d \$3\ %s; cmd | getline t; close(cmd); if (systime()-t 2592000) print stale: $2 } wiki/MANIFEST.md echo [$(date %F %T)] health-check 完成 log.md执行它chmod x ops/health-check.sh ./ops/health-check.sh输出里如果出现断链: entities/PhoneLogin说明回流素材还没被编译进 wiki这正是我们要处理的。第三步让 AI 把auto-ingest里的素材编译成 wiki 页面。在知识中枢目录启动 OpenCodecd koi-llm-wiki opencode在会话里输入指令让 AI 读取AGENTS.md规则后处理素材读取 signals/auto-ingest/service-auth/add-phone-login.json 按 AGENTS.md 规则提取知识 1. 若 PhoneLogin 是新实体在 wiki/entities/ 创建 PhoneLogin.md 2. 更新 wiki/modules/auth-module.md 的登录方式章节 3. 在 wiki/INDEX.md 实体表追加一行 4. 在 wiki/MANIFEST.md 追加保鲜记录 5. 引用 glossary 中的术语补充 [[链接]]AI 执行后检查产物ls wiki/entities/ | grep PhoneLogin grep -n PhoneLogin wiki/INDEX.md第四步检索验证。这是最关键的收尾动作验证知识真的能被“用起来”。在 Obsidian 里打开 Vault先同步./ops/sync-obsidian.sh然后在 Obsidian 搜索框输入PhoneLogin应该能命中entities/PhoneLogin.md和modules/auth-module.md。再回到 OpenCode 会话问一个依赖知识的问题service-auth 现在支持哪些登录方式各自的实体是什么如果 AI 能答出“手机号登录对应 PhoneLogin 实体与原有账号登录并存”说明知识链路闭环了代码变更 → 自动提取 → wiki 编译 → 检索命中 → AI 复用。整个过程不需要人手写文档只需要在归档时触发一次脚本。5. 常见报错排查401、local proxy failed 与 reading choices链路跑起来后报错基本集中在模型调用和路径解析两块。我把踩过的坑按现象、原因、解法列出来你对照排查。401 Unauthorized。最常见通常是 Key 没注入或写错。先确认环境变量echo $TAOTOKEN_API_KEY # 应输出 sk- 开头的字符串为空说明没 export如果为空检查是否写进了正确的 shell 配置文件source ~/.bashrc后重试。如果 Key 存在仍 401检查opencode.json里是否误写成apiKey: sk-xxx明文且带了多余空格。还有一种情况是 Base URL 写成了https://taotoken.net/api/带尾斜杠某些客户端会拼成双斜杠导致鉴权失败统一去掉尾斜杠。local proxy failed。这个报错通常出现在客户端尝试走本地代理但代理未启动时。检查你的环境变量里是否有HTTP_PROXY、HTTPS_PROXY残留env | grep -i proxy # 如果有输出且你并不需要代理unset 掉 unset HTTP_PROXY HTTPS_PROXY ALL_PROXY清掉后重启 OpenCode。如果团队网络确实需要统一出口确保代理配置在系统层而非散落在各工具里避免工具间互相干扰。reading choices of undefined。这个报错说明请求返回体里没有choices字段通常是响应被错误解析或接口返回了错误对象。先看原始返回curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:hi}]} | jq .如果返回里有error字段按错误信息处理如果返回正常但脚本仍报错检查jq表达式是否写成了.choices[0].message.content而实际结构不同。另外 Model ID 拼错也会导致返回异常确认claude-sonnet-4-5与你在模型对话页看到的一致。OAuth 相关报错。如果你用的是 Claude Code 这类带 OAuth 流程的工具报错往往出在回调地址或 token 刷新。检查配置文件里的baseURL是否指向https://taotoken.net/api以及是否误用了需要浏览器登录的旧配置。改用 API Key 方式接入通常能绕开这类问题配置三件套写全Base URL、Key、Model ID。路径解析失败。微服务仓库里 AI 找不到知识中枢时按优先级排查echo $KOI_WIKI_PATH ls ../koi-llm-wiki/AGENTS.md git submodule status .wiki-contextKOI_WIKI_PATH没设就设上相对路径不对就调整目录层级submodule 没初始化就git submodule update --init。三级路径解析只要有一级命中就能工作但建议团队统一用环境变量避免各人目录结构不同导致行为不一致。术语不一致告警。日循环报“术语未使用”或“断链”多半是 AI 写入时没查 glossary。回到AGENTS.md确认规则是否被加载必要时在会话里显式提醒“先读 glossary 再写”。断链则检查[[链接]]的路径是否相对wiki/根写[[entities/User]]而不是[[User]]。6. 持续进化把知识中枢接进日常研发流搭好之后真正决定它能不能活下来的是日常习惯。我的做法是把三环拆成三个触发点微循环挂在 OpenSpec 归档钩子上日循环用 cron 每天凌晨跑一次health-check.sh周循环用report-weekly.sh生成知识缺口报告并自动创建 OpenSpec proposal。cron 配置示例# 每天 02:00 跑保鲜检查 0 2 * * * cd /path/to/koi-llm-wiki ./ops/health-check.sh outputs/reports/cron.log 21 # 每周一 03:00 跑周报 0 3 * * 1 cd /path/to/koi-llm-wiki ./ops/report-weekly.sh outputs/reports/cron.log 21新服务接入只要两步在服务仓库建AGENTS.md和.wiki-context/MANIFEST.md在中枢建signals/auto-ingest/service-xxx/。剩下的拉取、同步检查、归档回流全自动。如果你团队已经在用 Coding Plan 做长期编码和 Agent 任务可以把知识中枢的检索接口接进去让 Agent 在动手前先读 ADR 和实体定义路径在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。需要查接入细节就去文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteKey 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。最后说一个我自己的体会知识中枢的价值不在搭得多完整而在第一次代码变更后它真的自动长出了一条知识。先让微循环跑通哪怕只有一个服务、一个实体也比攒一堆没人维护的文档强。等这条链路稳定了再补日循环和周循环知识就会像代码一样随迭代自然进化。