KoiWeave v2.0 详细使用步骤手把手教你从零搭建企业级 AI 知识中枢让 AI 在写代码前必须读完历史知识写完后必须把新知识吐回来。目录一、环境准备二、知识中枢初始化三、知识填充消化原始素材四、微服务接入五、日常开发循环六、归档回流三阶段事务七、健康检查与维护八、多服务协作九、常见问题附录 A命令速查表附录 B目录结构参考一、环境准备1.1 前提条件工具说明Git版本控制所有仓库基础bash运行 skill 脚本Linux/macOS/Windows Git Bashsha256sum 或 shasum计算内容指纹系统自带验证环境git--versionbash--versionsha256sum--version2/dev/null||shasum--version2/dev/null||echo需要 sha256sum 或 shasum1.2 克隆项目gitclone https://gitee.com/knowledge-accumulation_1/koi-weavecdKoiWeave1.3 目录概览克隆后得到以下结构KoiWeave/ ├── skills/koi-weave-wiki/ ← 知识中枢运维 Skill ├── skills/koi-weave-dev/ ← 微服务开发 Skill ├── koi-llm-wiki/ ← 知识中枢实例预置空骨架 ├── service-auth/ ← 微服务示例 ├── service-order/ ├── service-payment/ └── doc/ ← 文档零安装不需要 Node.js、npm、pip。bash git 即可运行。二、知识中枢初始化知识中枢koi-llm-wiki/是整个体系的大脑存储所有结构化知识。2.1 方案 A从零创建推荐# 在 AI 工具中加载 koi-weave-wiki skill执行koi-weave-wiki init ./koi-llm-wikiAI 会执行以下操作创建文件 koi-llm-wiki/AGENTS.md ← 知识中枢宪法 koi-llm-wiki/log.md ← 全局操作日志 koi-llm-wiki/wiki/INDEX.md ← 全局索引地图 koi-llm-wiki/wiki/MANIFEST.md ← 知识保鲜清单 koi-llm-wiki/wiki/glossary/index.md ← 术语表 koi-llm-wiki/.gitignore 创建空目录 signals/{inbox,auto-ingest,requirements,references}/ wiki/{entities,modules,concepts,summaries}/ wiki/architecture/{decisions,diagrams,proposals}/ outputs/{charts,reports,archive/signals}/2.2 方案 B使用预置实例项目中已包含预初始化的koi-llm-wiki/可以直接使用cdkoi-llm-wikigitinitgitadd-Agitcommit-minit: 知识中枢骨架# 推送到远程仓库团队协作必需gitremoteaddorigin gitgithub.com:org/koi-llm-wiki.gitgitpush-uorigin main2.3 设置知识中枢路径# 推荐设置环境变量所有服务共享同一个知识中枢exportKOI_WIKI_PATH/path/to/koi-llm-wiki# 写入 shell 配置文件永久生效echoexport KOI_WIKI_PATH/path/to/koi-llm-wiki~/.bashrc如果不设置脚本自动尝试../koi-llm-wiki/。三、知识填充消化原始素材知识中枢初始化后是空的需要填充知识。这是通过消化原始素材完成的。3.1 放入原始素材将以下类型的文档放入signals/目录# 会议纪要、设计文档放入 inboxcpmeeting-notes.md koi-llm-wiki/signals/inbox/cplogin-design.md koi-llm-wiki/signals/inbox/# 需求文档放入 requirementscpprd-v2.md koi-llm-wiki/signals/requirements/# 技术参考放入 referencescprfc-oauth2.md koi-llm-wiki/signals/references/3.2 执行消化# 在 AI 工具中加载 koi-weave-wiki skill 后koi-weave-wiki digestAI 会执行Step 1: 调用 scripts/digest.sh 扫描素材 → 输出待处理文件清单 Step 2: AI 逐一读取素材文件 → 识别实体、概念、决策、术语 Step 3: AI 按以下顺序写入 wiki ① glossary/ → 新术语 ② entities/ → 新实体定义 ③ concepts/ → 新概念说明 ④ modules/ → 模块设计更新 ⑤ architecture/decisions/ → ADR 生成 Step 4: 更新 INDEX.md 和 MANIFEST.md Step 5: 归档素材到 outputs/archive/signals/ Step 6: 追加 log.md3.3 手动补充知识除了自动消化也可以手动让 AI 补充知识# 添加实体koi-weave-wikiwriteentity User koi-weave-wikiwriteentity Order# 添加模块koi-weave-wikiwritemodule auth-module# 添加概念koi-weave-wikiwriteconcept jwt-authentication# 生成 ADR架构决策记录koi-weave-wikiwriteadr认证会话管理方案# 添加术语koi-weave-wiki glossaryadd短信验证码SMS Code通过短信发送的一次性验证码四、微服务接入每个微服务需要接入 KoiWeave 体系获得知识中枢的投射。4.1 接入新服务# 在 service-xxx 目录的父级执行# 在 AI 工具中加载 koi-weave-dev skill 后koi-weave-dev init authAI 会执行以下操作在服务仓库创建 service-auth/AGENTS.md ← 服务宪法四步锁 service-auth/.wiki-context/STATUS.md ← 同步状态 service-auth/.wiki-context/SYNC_LOG.md ← 同步日志 service-auth/.wiki-context/MANIFEST.md ← 知识索引 service-auth/.wiki-context/staging/ ← 回流暂存区 在知识中枢创建 koi-llm-wiki/signals/auto-ingest/auth/.ack/ ← 回流确认目录4.2 检查同步状态cdservice-auth koi-weave-dev status输出示例{syncStatus:upToDate,syncLabel: 最新,wikiPath:/data/koi-llm-wiki,backflowTransactions:[],cleanCount:0}4.3 拉取最新知识koi-weave-dev pull输出示例{status:success,oldHead:abc1234,newHead:def5678,commits:[{hash:def5678,message:fix: User entity phone field}],changedFiles:[wiki/entities/User.md]}五、日常开发循环这是最核心的流程。每次开发一个功能都需要执行加载知识→验证→编码→回流的闭环。5.1 场景给用户增加手机号登录假设我们要在 service-auth 中增加手机号登录功能。Step 1: 检查同步cdservice-auth koi-weave-dev status确保知识是最新版本。如果 落后先执行koi-weave-dev pull。Step 2: 加载相关知识koi-weave-dev load-task给用户增加手机号登录AI 自动匹配知识集匹配结果 P1 实体: User (wiki/entities/User.md) PhoneLogin (wiki/entities/PhoneLogin.md) P2 模块: auth-module (wiki/modules/auth-module.md) P3 概念: sms-code (wiki/concepts/sms-code.md) P0 ADR: ADR-001-auth-session ADR-007-token-refresh输出四问验证清单。Step 3: 五问验证编码前必答AI 逐条回答每条必须有具体证据✅ 问题一涉及哪些实体/模块/概念 证据User已加载 wiki/entities/User.md PhoneLogin已加载 wiki/entities/PhoneLogin.md auth-module已加载 wiki/modules/auth-module.md SMS Code已加载 wiki/concepts/sms-code.md ✅ 问题二wiki 设计与当前代码一致 证据wiki/modules/auth-module.md 的 login(phone, code) 方法签名 与当前代码 AuthService.loginByPhone(phone, code) 参数匹配 ✅ 问题三ADR 约束 证据ADR-001 要求使用 JWT → 本变更产生 JWT token ✅ ADR-007 要求双 Token 机制 → 同时返回 access_token refresh_token ✅ ✅ 问题四术语与 glossary 一致 证据glossary SMS Code 短信验证码 代码变量名 smsCode → 一致 ✅ ✅ 问题五有进行中的提案涉及本服务 证据扫描 wiki/architecture/proposals/ 目录 → 本次无匹配提案跳过五问全部通过前禁止输出任何代码。Step 4: AI 编码AI 基于上述知识编写代码。过程中如果发现 wiki 知识需要更新AI 必须先更新 wiki 再改代码。5.2 场景Bug 修复koi-weave-dev load-task修复登录 session 过期判断AI 自动匹配P2 模块: auth-moduleP0 ADR: ADR-001-auth-sessionP1 实体: Session, User加载知识 → 四问验证 → 修复代码 → 回流。5.3 场景新增 API 接口koi-weave-dev load-task新增用户注销接口AI 自动匹配P2 模块: auth-module了解现有 API 设计P1 实体: Session, Token涉及的数据模型P0 ADR: ADR-001, ADR-007历史决策约束六、归档回流三阶段事务开发完成后需要把本次变更中的知识提取出来回流到知识中枢。6.1 执行回流# AI 分析 diff 后生成标准 YAML通过 stdin 传入catYAML|koi-weave-dev push add-phone-loginschema_version: 1.0 service: auth change_name: add-phone-login entities: - name: PhoneLogin summary: 手机号登录凭证 fields: - name: phone type: string description: 手机号E.164 格式 - name: code type: string description: 短信验证码 modules_updated: - name: auth-module changes: 新增 phoneLogin() 和 verifySmsCode() 两个方法 architecture_decisions: - title: 手机登录安全策略 summary: 验证码有效期5分钟错误5次锁定30分钟 glossary_terms: - cn: 短信验证码 en: SMS Code definition: 通过短信发送的一次性验证码 YAML6.2 三阶段内部流程push.sh内部执行三个阶段Phase 1 — PREPARE ├── 计算内容 SHA256 hash ├── 幂等检查同 hash 跳过 └── 写入 .wiki-context/staging/change.pending.yaml Phase 2 — COMMIT ├── 幂等检查同 hash 已确认 → 清理 staging ├── 复制到 koi-llm-wiki/signals/auto-ingest/auth/change.yaml └── git add git commit git push Phase 3 — ACK异步下次 status 时完成 ├── 中枢 digest 后创建 .ack/change.done ├── status 检测到 .done → 自动清理 staging └── SYNC_LOG 追加 ✅ 已完成6.3 输出结果{status:committed,hash:sha256:a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890,phase:committed,waitingForAck:true}6.4 确认回流完成koi-weave-dev status如果看到cleanCount: 1说明回流已确认staging 已自动清理。6.5 失败处理# git push 失败 → staging 保留# 修复网络/权限后重试即可幂等koi-weave-dev push add-phone-loginCLI 自动检测同 hash 的 staging 已存在 → 跳过 PREPARE → 直接从 COMMIT 开始。七、健康检查与维护知识库需要定期维护否则会腐烂。7.1 执行健康检查在知识中枢仓库中执行koi-weave-wiki healthAI 执行五项检查① 术语一致性 — glossary 中的术语在全库使用是否一致 检查读取 glossary → 在全站搜索术语使用 → 标记不一致 ② 链接完整性 — [[wiki/...]] 链接是否全部有效 检查解析所有 [[链接]] → 验证目标文件存在 ③ 时效性 — 超过 30 天未审核的页面 检查读取 MANIFEST.md → 标记 stale 条目 ④ 矛盾检测 — 同一实体在不同页面描述是否冲突 检查跨页面对比同名词条 ⑤ 报告输出到 outputs/reports/7.2 修正 stale 知识koi-weave-wiki fix wiki/entities/User.mdAI 读取当前内容对比代码和最新需求更新后同步更新 INDEX.md 和 MANIFEST.md。7.3 术语一致性同步koi-weave-wiki glossarysyncAI 扫描全站确保术语使用与 glossary 一致。八、多服务协作8.1 场景跨服务架构变更需要统一三个服务的 SSO 方案。关键在于proposal 模板的标准化格式load proposal精准定向push 时自动更新消费状态。Step 1在知识中枢创建提案koi-weave-wikiwriteproposal统一 SSO 方案AI 使用模板创建提案必须按服务名分节# 统一 SSO 方案 ## 背景与动机 当前三个服务各自维护登录体系... ## 方案选型对比 | 方案 | 优点 | 缺点 | | ------------- | -------- | -------------- | | OAuth2 OIDC | 标准协议 | 实现复杂度较高 | ## 各服务改动点 ← AI 通过这个章节定位 ### service-auth ← 开发者通过 load proposal 定位 - [ ] 集成 OAuth2 登录流程 - [ ] 新增 /api/auth/sso/login 接口 ### service-order ← 格式固定### service-xxx - [ ] 用户鉴权切换到 SSO Token ### service-payment - [ ] 用户身份校验切换到 SSO ## 状态追踪 | 服务 | 状态 | 完成日期 | | --------------- | --------- | -------- | | service-auth | ⏳ 进行中 | — | | service-order | ⏳ 进行中 | — | | service-payment | ⏳ 进行中 | — |proposal 模板skills/koi-weave-wiki/assets/templates/proposal-template.mdStep 2service-auth 开发者领取任务精准定向cdservice-auth koi-weave-dev load proposal unified-ssoAI 执行1. 读取 wiki/architecture/proposals/unified-sso.md 2. 查找 ### service-auth 章节当前服务名 3. 提取该节的 checklist □ 集成 OAuth2 登录流程 □ 新增 /api/auth/sso/login 接口 4. 输出为本服务的开发任务列表得到定向任务后开发者按日常流程开发→ 检查同步: koi-weave-dev status → 加载知识: koi-weave-dev load-task 集成 OAuth2 → 四问验证 编码Step 3完成开发回流并标记消费标志# push 时 YAML 中带 proposal 字段指名关联的提案catYAML|koi-weave-dev push sso-authschema_version: 1.0 service: auth change_name: sso-auth proposal: unified-sso # ← 关联的提案名关键字段 entities: - name: SsoToken summary: SSO 统一认证令牌 YAMLpush 成功后AI 自动执行提案状态更新Step 1: push 成功 → CLI 输出 {status:committed,...} Step 2: AI 检测到 YAML 中有 proposal: unified-sso Step 3: 读取提案文件 读取 $WIKI_PATH/wiki/architecture/proposals/unified-sso.md Step 4: 将本服务的 checklist 项标记为已完成 - [ ] 集成 OAuth2 登录流程 → - [x] 集成 OAuth2 登录流程 - [ ] 新增 /api/auth/sso/login 接口 → - [x] 新增 /api/auth/sso/login 接口 Step 5: 更新状态追踪表 | service-auth | ⏳ 进行中 | — | → | service-auth | ✅ 已完成 | 2026-07-08 | Step 6: git add git commit git push 到知识中枢 Step 7: 告知用户 ✅ 回流成功 ✅ 提案 unified-sso 中 service-auth 的 2 项任务已完成Step 4其他服务同理cdservice-order koi-weave-dev load proposal unified-sso# 领取 order 的任务# 编码...catYAML|koi-weave-dev push sso-order# 回流 自动更新消费标志Step 5所有服务完成后# 知识中枢的人或 AI 周检时确认所有服务已完成 # 提案的状态追踪表 | service-auth | ✅ 已完成 | 2026-07-08 | | service-order | ✅ 已完成 | 2026-07-09 | | service-payment | ✅ 已完成 | 2026-07-10 |关键设计load proposal unified-sso ← 精准拉取提案提取本服务 checklist push 带 proposal 字段 ← 回流时指名关联的提案 AI 自动更新提案状态 ← 消费标志自动更新无需人手动操作8.2 场景接入第 10 个微服务koi-weave-dev init notification两步完成服务仓库创建宪法文件中枢创建回流目录剩余的全自动——知识拉取、同步检查、归档回流、健康检查。九、常见问题Q1: 知识中枢路径找不到# 设置环境变量exportKOI_WIKI_PATH/data/repos/koi-llm-wiki或确保../koi-llm-wiki/存在相对路径兜底。Q2: push 时 git push 失败staging 会保留修复网络/权限后重试即可。幂等检查确保不会重复写入。Q3: 离线能做什么# 可以koi-weave-dev status# 显示 ⚠️ 离线koi-weave-dev load entity User# 读本地缓存# 不可以koi-weave-dev pull# 需要网络# push 可以执行但 staging 保留联网后自动推送Q4: 多个 AI 工具怎么选工具特点OpenCodeSkill 体系最成熟.opencode/自动发现AtomCode当前对话环境通过 bash 工具执行Claude CodeCLAUDE.md 宪法支持三种工具都通过 bash 调用同一个脚本行为完全一致。Q5: 知识中枢的 AGENTS.md 有什么用它是宪法级指令。定义了什么能做、什么不能做、必须按什么流程操作。AI 每次启动时自动加载不得跳过。Q6: 如何保证 AI 真的执行了五问验证宪法中明确写着五问全部通过前禁止输出任何代码且证据必须是具体的文件名、ADR 编号、glossary 术语。没有证据的回答视为未通过。附录 A命令速查表koi-weave-wiki在 koi-llm-wiki 仓库执行命令参数说明init路径从模板初始化知识中枢骨架digest[子路径]扫描 signals/ 素材提取知识write entityPascalCase名添加或更新实体定义write conceptkebab-case名添加或更新概念write modulekebab-case名添加或更新模块write adr标题生成架构决策记录write proposal标题创建跨服务提案fix路径修正 wiki 页面错误health—五项完整健康检查glossary add中 英 定义添加术语glossary sync—统一全站术语引用koi-weave-dev在 service-xxx 仓库执行命令参数说明init服务名接入新服务到 KoiWeavestatus—同步检查 事务审计pull—拉取知识中枢最新知识load类型 名称精确加载实体/模块/概念/ADR/proposalload-task描述任务驱动加载自动匹配pushchange名三阶段事务回流stdin 传入 YAML可选带 proposal 字段附录 B目录结构参考知识中枢koi-llm-wiki/koi-llm-wiki/ ├── AGENTS.md 宪法 ├── log.md 操作日志 ├── signals/ 原始素材输入层 │ ├── inbox/ 人工投放 │ ├── auto-ingest/ 自动回流各服务写入 │ │ ├── auth/ │ │ ├── order/ │ │ └── payment/ │ ├── requirements/ 需求文档 │ └── references/ 外部参考 ├── wiki/ 结构化知识层 │ ├── INDEX.md 全局索引 │ ├── MANIFEST.md 保鲜清单 │ ├── entities/ 业务实体 │ ├── modules/ 功能模块 │ ├── concepts/ 抽象概念 │ ├── architecture/ │ │ ├── decisions/ ADR │ │ ├── proposals/ 提案 │ │ └── diagrams/ 架构图 │ ├── summaries/ AI 摘要 │ └── glossary/ 术语表 └── outputs/ 生成物 ├── reports/ 报告 └── charts/ 图表微服务service-xxx/service-auth/ ├── AGENTS.md 宪法四步锁 代码约束 ├── .wiki-context/ 知识投射层 │ ├── STATUS.md 同步状态 │ ├── SYNC_LOG.md 同步日志 │ ├── MANIFEST.md 知识索引 │ └── staging/ 回流暂存区 ├── src/ 源码 └── tests/ 测试