KoiWeave-构建企业级LLM-WIKI，打造下一阶段软件AI研发流程

KoiWeave 知识中枢体系 — 使用说明与架构设计

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

skill地址：https://gitee.com/knowledge-accumulation_1/koi-weave

一、定位：解决了什么问题

核心矛盾

AI 写代码的速度已经很快，但 AI 不知道你之前为什么那么写。每个微服务仓库各自为政，A 服务踩过的坑 B 服务照踩不误；三个月前的架构决策，新来的 AI 会话一无所知。

三个具体问题

与 AI 工具解耦

KoiWeave 不绑定任何 AI 工具。只要该工具支持：

• 加载 AGENTS.md 作为行为宪法
• 加载 skills/<name>/SKILL.md 作为场景指令
• 执行标准 Git/Markdown 文件操作

就可以使用 KoiWeave。当前已验证的工具：OpenCode、Claude Code，其他同类工具可类推。

二、核心能力：两个 Skill

整个体系的能力通过两个 Skill 承载，分别面向知识中枢维护和微服务开发两个场景：

KoiWeave
├── koi-weave-wiki ← 知识中枢运维 Skill
│ └── 在 koi-llm-wiki 仓库中加载，处理素材消化、健康检查、术语维护等
│
└── koi-weave-dev ← 微服务开发 Skill
└── 在 service-xxx 仓库中加载，处理服务接入、知识同步、归档回流等

2.1 koi-weave-wiki — 知识中枢运维 Skill

职责：维护知识中枢本身——消化素材、补充知识、修复错误、术语管理、健康检查、周报生成。

适用仓库：koi-llm-wiki/ 仓库根目录（不是微服务仓库）。

典型场景：

核心特性：通过结构化指令（不是模糊自然语言）触发，每个指令有明确的参数和产出物。

2.2 koi-weave-dev — 微服务开发 Skill

职责：在微服务仓库中加载知识、执行开发流程、确保代码与知识库一致。

适用仓库：任何 service-xxx/ 微服务仓库（不是知识中枢仓库）。

典型场景：

核心特性：每个微服务仓库通过 init 自动获得完整的「四步锁」AGENTS.md，AI 在该仓库中无权跳过知识加载与四问验证。

两个 Skill 的协作关系

┌──────────────────────┐
│ koi-llm-wiki │
│ (知识中枢仓库) │
└──────────┬───────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
service-auth service-order service-payment
▲ ▲ ▲
│ │ │
└────────────────┼────────────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
koi-weave-wiki skill koi-weave-dev skill
(中枢维护场景) (微服务开发场景)

三、架构概览

仓库拓扑

KoiWeave (本仓库)
┌─────────────────────────────┐
│ koi-llm-wiki/ ← 知识中枢 │
│ skills/ ← 2 个 AI 技能 │
│ INFO.md ← 本文件 │
└──────────┬──────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
service-auth/ service-order/ service-payment/
├── AGENTS.md ├── AGENTS.md ├── AGENTS.md
├── .wiki-context/ ├── .wiki-context/ ├── .wiki-context/
│ ├── STATUS.md │ ├── STATUS.md │ ├── STATUS.md
│ ├── SYNC_LOG.md │ ├── SYNC_LOG.md │ ├── SYNC_LOG.md
│ └── MANIFEST.md │ └── MANIFEST.md │ └── MANIFEST.md
└── openspec/ └── openspec/ └── openspec/

知识中枢目录结构

koi-llm-wiki/
├── AGENTS.md # 中枢宪法（AI 行为规则）
├── log.md # 全局变更审计日志
│
├── signals/ # [输入层] 原始素材
│ ├── inbox/ # 人工拖入（会议纪要、外部文档）
│ ├── auto-ingest/ # 自动回流（各服务 archive 时写入）
│ │ ├── service-auth/
│ │ ├── service-order/
│ │ └── service-payment/
│ ├── requirements/ # 产品需求文档
│ └── references/ # 外部技术参考
│
├── wiki/ # [知识层] AI 维护的结构化知识
│ ├── INDEX.md # 全局索引地图
│ ├── MANIFEST.md # 知识保鲜清单
│ ├── glossary/index.md # 术语表（一致性底线）
│ ├── entities/ # 业务实体定义
│ ├── modules/ # 功能模块设计
│ ├── concepts/ # 抽象概念说明
│ ├── architecture/
│ │ ├── decisions/ # ADR 架构决策记录
│ │ ├── proposals/ # 跨服务提案
│ │ └── diagrams/ # C4 架构图
│ └── summaries/ # 长文档 AI 摘要
│
└── outputs/ # [衍生物] 周报、报告
└── archive/signals/ # 已消化素材归档

微服务仓库附加结构

service-auth/
├── AGENTS.md # AI 宪法（四步锁 + 代码约束 + 离线规则）
├── .wiki-context/
│ ├── STATUS.md # 实时检查指引（只读）
│ ├── SYNC_LOG.md # PULL/PUSH 日志（纯追加）
│ └── MANIFEST.md # 本服务知识索引
└── openspec/ # 变更管理
├── changes/
└── specs/

三环进化机制

知识在三个时间尺度上自动进化，不需要人工触发：

微循环（每次归档 ~ 秒级）
OpenSpec archive → AI diff 分析 → 提取实体/ADR → 写回中枢

日循环（每天 ~ 分钟级）
健康检查 → 术语一致 → 链接完整 → 时效标记(30d) → 矛盾检测 → 报告

周循环（每周 ~ 小时级）
回流模式分析 → 知识缺口检测 → 公共抽象提取 → 周报生成

四、核心概念

五、快速上手

如果你是知识中枢维护者

在 koi-llm-wiki/ 仓库中加载 koi-weave-wiki Skill，通过 /koi-weave-wiki 命令激活。

# 首次初始化（新建或重建知识中枢）
你：init ./koi-llm-wiki
AI：从 templates/ 复制 AGENTS.md / log.md / wiki/{INDEX,MANIFEST}.md / glossary/index.md
创建空目录骨架（signals/outputs/wiki 各级子目录）
追加初始化日志记录

# 消化一批素材
你：digest
AI：扫描 inbox/ 和 auto-ingest/ → 提取知识 → 写入 wiki → 归档素材

# 补充一个实体定义
你：write entity User

# 做一次健康检查
你：health

# 生成周报
你：weekly

如果你是微服务开发者

在 service-xxx/ 仓库中加载 koi-weave-dev Skill，通过 /koi-weave-dev 命令激活。

# 接入新服务
你：init service-notification
AI：从模板创建 AGENTS.md / STATUS.md / SYNC_LOG.md / MANIFEST.md → 在中枢创建回流目录

# 首次填充知识索引
你：fill-manifest

# 开始日常开发
你：load task 改登录逻辑
AI：根据任务匹配知识 → 加载 ADR + 实体定义 + 模块设计 → 报告加载结果

# 检查知识是否最新
你：status

# 归档回流
你：push <change-name>
AI：分析 change diff → 去重 → 提取新知识 → 写入中枢 → 追加日志

切换 Skill

六、完整指令参考

koi-weave-wiki（知识中枢运维）

koi-weave-dev（微服务开发辅助）

七、典型工作场景

场景 0：初始化新的知识中枢

背景：新项目第一次搭建，或重新初始化现有知识中枢。

你：init ./koi-llm-wiki
AI：
✅ 复制 templates/AGENTS.md → ./koi-llm-wiki/AGENTS.md
✅ 复制 templates/log.md → ./koi-llm-wiki/log.md
✅ 复制 templates/wiki/INDEX.md → ./koi-llm-wiki/wiki/INDEX.md
✅ 复制 templates/wiki/MANIFEST.md → ./koi-llm-wiki/wiki/MANIFEST.md
✅ 复制 templates/wiki/glossary/index.md → ./koi-llm-wiki/wiki/glossary/index.md
✅ 复制 templates/.gitignore → ./koi-llm-wiki/.gitignore
✅ 创建空目录结构（signals/{inbox,auto-ingest,requirements,references}/
outputs/{charts,reports}/, outputs/archive/signals/,
wiki/{entities,modules,concepts,summaries}/,
wiki/architecture/{decisions,diagrams,proposals}/, logs/）
✅ 追加初始化记录到 log.md

询问：是否需要 git init 和配置远程仓库地址？

完成。建议下一步：
1. git init && git add -A && git commit -m "init: 知识中枢骨架"
2. 使用 koi-weave-dev 的 init 命令接入第一个微服务
3. 用 write entity / write adr / digest 等指令填充知识

场景 1：新服务接入

背景：团队要加一个 service-notification 微服务。

你：init service-notification
AI：
✅ 复制 templates/AGENTS.md → service-notification/AGENTS.md（替换 {{SERVICE_NAME}}）
✅ 复制 templates/STATUS.md → service-notification/.wiki-context/STATUS.md
✅ 复制 templates/SYNC_LOG.md → service-notification/.wiki-context/SYNC_LOG.md
✅ 复制 templates/MANIFEST.md → service-notification/.wiki-context/MANIFEST.md
✅ 创建 koi-llm-wiki/signals/auto-ingest/service-notification/
已完成接入。建议执行 fill-manifest 填充知识索引。

生成的 AGENTS.md 包含完整的四步锁、代码生成约束和离线降级规则，开箱即用。

场景 2：日常开发 + 知识同步

背景：你休假回来，要改 service-auth 的用户登录逻辑。

你：status
AI：🔍 知识同步状态
→ git fetch… 🔴 落后 5 次提交
→ 执行 git pull –ff-only… ✅ 完成
→ 追加 SYNC_LOG.md PULL 记录
🟢 现在是最新版本

你：load task 改用户登录逻辑
AI：根据任务匹配加载集：
→ wiki/modules/auth-module.md
→ wiki/entities/User.md
→ wiki/entities/Session.md
→ wiki/entities/Token.md
→ ADR-001-auth-session
→ ADR-007-token-refresh
已完成加载，你可以开始编码了。

你：（给出需求后）
AI：开始编码前，执行四问验证——
□ 涉及实体 ✓ User, Session 已加载
□ wiki 设计 vs 代码 → 一致
□ ADR 约束 → ADR-001 使用 JWT，本次未偏离
□ 术语检查 ✓ 与 glossary 一致
四问全部通过，开始生成代码。

场景 3：信号素材消化

背景：产品经理扔了一份登录页面改版的需求文档到 signals/inbox/。

你：digest
AI：📋 信号素材消化报告
扫描素材：1 份
定位目录：signals/inbox/

提取成果：
├── 新实体：PhoneLogin → wiki/entities/PhoneLogin.md
├── 更新模块：auth-module → wiki/modules/auth-module.md
│ └── 新增手机验证码登录流程
├── 新术语：短信验证码 (SMS Code) → wiki/glossary/
├── 新 ADR：ADR-008-手机登录安全策略
│ └── wiki/architecture/decisions/ADR-008-phone-login
└── 关联更新：
├── wiki/INDEX.md ✅
└── wiki/MANIFEST.md ✅

素材归档：outputs/archive/signals/login-redesign-2026.md
追加 log.md ✅

场景 4：跨服务提案 + 分头实施

背景：需要统一三个服务的 SSO 方案。

# 第一步：在知识中枢写提案
你：write proposal 统一 SSO 方案
AI：创建 wiki/architecture/proposals/unified-sso.md
包含：背景、OAuth2 vs SAML vs 自建对比、各服务改动点、接口契约

# 第二步：各服务开发者各自消费（无需协调会议）
你（在 service-auth 中）：load task 实现 SSO 改造
AI：读取 proposals/unified-sso.md → 了解本服务的改动点
→ 创建 OpenSpec change → 开始编码

# 第三步：各自归档回流
你（archive 时自动）：push unified-sso-auth
AI：分析 diff → 提取新实体/ADR → 写入 auto-ingest/ → 追加 SYNC_LOG.md

不需要中央编排，proposal 就是知识，各服务通过 AGENTS.md 的强制加载自动对齐。

场景 5：健康检查与周报

背景：周五下午，你想看看知识库的健康状况。

你：health
AI：🔍 健康检查报告
✅ 术语一致性 — 通过（glossary 8 项，全库使用一致）
✅ 链接完整性 — 通过（所有 [[wiki/…]] 链接有效）
⚠️ 时效性 — 2 个页面超过 30 天未审核
→ wiki/entities/User.md（上次审核：30天前）
→ wiki/modules/auth-module.md（上次审核：45天前）
✅ 矛盾检测 — 未发现冲突描述
报告已输出到 outputs/reports/health-check-2026-W27.md

你：weekly
AI：📊 本周知识回顾
├── 新增实体：PhoneLogin
├── 新增 ADR：ADR-008-手机登录安全策略
├── 更新模块：auth-module
├── 活跃服务：service-auth（2 次回流）
└── 检测缺口：建议补充「手机验证码」概念文档
报告已输出到 outputs/reports/weekly-review-2026-W27.md

场景 6：离线开发

背景：你在飞机上，网络不可达，但需要继续开发。

你：status
AI：⚠️ 网络不可达，切换离线模式
→ 读取本地缓存：上次同步版本 abc1234（3 小时前）
→ 离线降级：已启用，允许基于缓存开发
→ 限制：archive 时会标记为「待同步」

你：load task 改支付回调逻辑
AI：基于本地缓存的 wiki 知识加载…
→ wiki/modules/payment-module.md（缓存版本）
→ wiki/entities/Payment.md（缓存版本）
✅ 离线加载完成，可以开始编码。

（落地后）
AI 自动检测网络恢复：
→ git pull 获取最新知识… ✅
→ 推送标记为待同步的回流信息… ✅
→ 通知用户：离线期间的变更已全部同步

八、文件体系说明

核心文件关系

AGENTS.md（宪法）
/ | \\
▼ ▼ ▼
STATUS.md MANIFEST.md SYNC_LOG.md
(实时检查指引) (知识索引) (同步日志)

AGENTS.md → 定义 AI 必须执行的四步锁
STATUS.md → Step 0 的检查流程指引（只读）
MANIFEST.md → Step 1 的知识加载表 + 任务-知识映射
SYNC_LOG.md → Step 0 PULL 记录 + Step 3 PUSH 记录

各文件职责

文件生成模板

skills/koi-weave-wiki/templates/ — 知识中枢骨架模板

6 个文件，init 命令复制到目标目录生成完整知识中枢：

templates/
├── .gitignore # OS/IDE/outputs 忽略规则
├── AGENTS.md # 知识中枢宪法（含三环操作指令）
├── log.md # 空日志（含表头）
└── wiki/
├── INDEX.md # 索引地图骨架（5 类占位表）
├── MANIFEST.md # 保鲜清单骨架（含统一规则）
└── glossary/
└── index.md # 基础术语表（7 条核心术语）

skills/koi-weave-dev/templates/ — 微服务接入模板

4 个文件，init 命令复制并替换 {{SERVICE_NAME}}：

templates/
├── AGENTS.md # 四步锁 + 四问验证 + 代码约束 + 离线降级（139行）
├── STATUS.md # 实时检查步骤 + 离线降级流程（40行）
├── SYNC_LOG.md # 单表纯追加格式（6行）
└── MANIFEST.md # P0-P4优先级 + 任务映射 + 填充检查表（104行）

九、FAQ

Q1: 知识库是空的，强制 AI 读什么？

新项目第一次跑通：

INFO.md 写明的这一刻，wiki/entities/、wiki/modules/ 等目录确实为空。模板中的 MANIFEST.md 包含首次填充检查表，fill-manifest 指令引导完成这一步。

Q2: AI 真的会遵守四步锁吗？能不能跳过？

AGENTS.md 对 AI 而言是宪法级指令，不是建议。AI 工具每次启动时自动加载 AGENTS.md，AI 以该文件中的规则作为行为基准。文件中明确写了"四问全部通过前，禁止输出任何代码"——这不是装饰性文字。

Q3: 适用于哪些 AI 工具？

KoiWeave 与具体 AI 工具解耦。兼容条件：

• 支持加载 AGENTS.md 作为行为宪法
• 支持加载 skills/<name>/SKILL.md 作为场景指令
• 能执行标准 Git/Markdown 文件操作

当前已验证：OpenCode、Claude Code。同类工具可类推使用。

Q4: 和直接用 Confluence/Copilot 有什么区别？

Q5: 10+ 微服务也能用吗？

加一个服务只需两步：

剩余的全自动：知识拉取、同步检查、归档回流、健康检查。没有额外运维成本。

Q6: 遇到冲突了怎么办？

Git pull 冲突通常发生在多人同时修改知识中枢。AGENTS.md 规定：冲突时立即停止，通知人工介入。建议 team 约定：知识中枢的修改通过 OpenSpec change 流程，避免多人同时编辑同一页。

Q7: 离线能做什么？不能做什么？

恢复网络后 AI 自动执行 recovery：git pull + 推送待同步内容。

koi-llm-wiki/
AGENTS.md ← 宪法已就位
signals/inbox/ ← 等待你的第一个素材
wiki/MANIFEST.md ← 保鲜清单已创建

service-auth/
AGENTS.md ← 四步锁已部署（来自模板）
.wiki-context/ ← 投射层已就位
openspec/changes/ ← 第一个 change 等你去 propose