KoiWeave-构建企业级LLM-WIKI，打造下一阶段软件AI研发流程KoiWeave 知识中枢体系

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

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

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

核心矛盾

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

三个具体问题

问题	日常表现	KoiWeave 的做法
知识碎片化	架构决策散落在 Slack/PR/Comment 里，AI 看不到	所有知识集中到 `koi-llm-wiki/`，通过 AGENTS.md 强制 AI 启动时加载
知识不流动	service-auth 的 ADR 不会自动同步到 service-order	代码变更归档时自动回流知识到中枢，所有服务拉取同一份知识
知识会腐烂	三个月前的设计文档没人更新，逐渐变成错误文档	日检自动扫描过时条目，周检自动识别知识缺口

与 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/ 仓库根目录（不是微服务仓库）。

典型场景：

场景	触发方式	输出
初始化骨架	`init ./koi-llm-wiki`	AGENTS.md + log.md + wiki/{INDEX,MANIFEST,glossary} + 空目录结构
消化素材	`digest` 或 `digest inbox/meeting-notes`	信号归档 + 实体/概念/ADR 写入 wiki
补充实体	`write entity User`	wiki/entities/User.md
补充概念	`write concept jwt-authentication`	wiki/concepts/jwt-authentication.md
生成 ADR	`write adr 统一登录方案`	wiki/architecture/decisions/ADR-NNN-*.md
加术语	`glossary add 三环 Three-Loops 三层时间尺度的自动化机制`	wiki/glossary/index.md
健康检查	`health`	outputs/reports/health-check-*.md
周报	`weekly`	outputs/reports/weekly-review-*.md
日志归档	`archive now`	logs/YYYY-Www.md

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

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

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

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

典型场景：

场景	触发方式	输出
接入新服务	`init service-notification`	AGENTS.md + .wiki-context/ 全套文件 + 中枢回流目录
首次填充	`fill-manifest`	MANIFEST.md 中填入实体/模块/ADR 路径
检查同步	`status`	🟢最新 / 🔴落后 / 🟡待推送状态报告
按需加载	`load entity User` 或 `load task 改登录`	相关 wiki 页面加载到上下文
提交需求	`submit requirement ./docs/req.md`	signals/requirements/.md
提交设计	`submit design ./docs/design.md`	signals/auto-ingest/service-xxx/.md
归档回流	`push <change-name>`	signals/auto-ingest/service-xxx/.md + SYNC_LOG 追加
查看日志	`sync-log`	最近 PULL/PUSH 记录

核心特性：每个微服务仓库通过 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) → 矛盾检测 → 报告

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

四、核心概念

术语	定义
知识中枢 (Knowledge Hub)	`koi-llm-wiki/` 仓库，存储所有经过提炼的结构化知识
信号 (Signal)	输入到知识中枢的原始素材，包括自动回流和手动投放
投射 (Projection)	服务仓库通过 `.wiki-context/` 将远程知识映射为本地上下文
回流 (Backflow)	OpenSpec archive 时将变更中的知识提取写回中枢
保鲜 (Freshness)	日检自动审核知识准确性，超过 30 天未审核标记为 stale
三环 (Three Loops)	微循环(变更级)、日循环(维护级)、周循环(战略级)
宪法 (Constitution)	AGENTS.md 文件，定义 AI 的强制行为规则
Skill	`skills/<name>/SKILL.md` 文件，向 AI 提供场景化的操作指令集

五、快速上手

如果你是知识中枢维护者

在 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

当前仓库	加载的 Skill	命令前缀
`koi-llm-wiki/`	`koi-weave-wiki`	`/koi-weave-wiki`
`service-xxx/`	`koi-weave-dev`	`/koi-weave-dev`

六、完整指令参考

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

指令	参数	功能
`init <路径>`	目标目录路径	从 templates/ 复制骨架并创建完整空目录结构，追加初始化日志
`digest`	—	扫描所有未处理素材，提取知识写入 wiki
`digest <路径>`	signals/ 子路径	仅处理指定路径的素材
`write entity <名>`	PascalCase	创建/更新实体定义
`write concept <名>`	kebab-case	创建/更新概念说明
`write module <名>`	kebab-case	创建/更新模块设计
`write adr <标题>`	标题文本	生成 ADR 记录
`fix <路径>`	wiki 页面路径	修正页面错误，同步更新索引/术语
`glossary add <中> <英> <定义>`	三项必填	添加新术语
`glossary sync`	—	扫描全库，确保术语使用一致
`health`	—	执行五项完整健康检查
`weekly`	—	检查/生成周报
`archive now`	—	执行 log.md 7 天归档

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

指令	参数	功能
`init <name>`	kebab-case	从模板初始化新服务全套文件
`status`	—	检查知识同步状态
`load <类型> <名称>`	entity/module/concept/adr	按需加载对应知识
`load task <描述>`	自然语言	根据任务描述自动匹配知识集
`submit requirement <路径>`	文件路径	提交需求文档到中枢
`submit design <路径>`	文件路径	提交模块设计到中枢
`push <change>`	change 名	手动触发归档回流
`sync-log`	—	查看 PULL/PUSH 日志
`fill-manifest`	—	引导首次填充 MANIFEST.md

七、典型工作场景

场景 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 记录

各文件职责

文件	位置	谁维护	写入频率	核心作用
AGENTS.md	每个仓库根目录	init 创建，极少改	初始化一次	AI 行为宪法，定义强制流程
STATUS.md	.wiki-context/	不维护（只读）	从不写入	实时检查指引，AI 按步骤执行
SYNC_LOG.md	.wiki-context/	AI 追加	每次 PULL/PUSH	纯追加审计日志
MANIFEST.md	.wiki-context/	init 创建+首次填充	有新增知识时	知识索引 + 任务映射表
log.md	koi-llm-wiki/	AI 追加	每次变更操作	全局变更审计 + 7天归档
SKILL.md	skills//	人工维护	有新场景时	Skill 行为指令（AI 加载）
readme.md	skills//	人工维护	有指令变更时	人类使用说明（指令速查）

文件生成模板

`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 读什么？

新项目第一次跑通：

在目标目录执行 init <路径> 创建知识中枢骨架（含宪法/索引/术语表/空目录结构）
在首个微服务仓库执行 init service-xxx 接入
用 write entity / write module / write adr 填充骨架
填充越完整，后续开发的效率提升越明显

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 有什么区别？

	Confluence	Copilot	KoiWeave
知识来源	人写	公开代码	自动从代码变更提取
知识更新	人手动	不更新	archive 时自动回流
AI 是否必读	不强制	不读	AGENTS.md 强制 Step 1
跨服务同步	手动拷贝	无	自动 PULL/PUSH
保鲜机制	无	无	日检 stale + 周检缺口

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

加一个服务只需两步：

在服务仓库执行 init service-xxx
在中枢确认 signals/auto-ingest/service-xxx/ 已创建

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

Q6: 遇到冲突了怎么办？

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

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

可以	不可以
基于本地缓存的知识开发	获取最新知识（无网络）
编写代码、本地测试	git push/pull
OpenSpec archive（标记待同步）	推送回流到中枢

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

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

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

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