# KoiWeave

**Repository Path**: knowledge-accumulation_1/koi-weave

## Basic Information

- **Project Name**: KoiWeave
- **Description**: 搭建持续进化的微服务知识中枢
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KoiWeave — 搭建持续进化的微服务知识中枢

> 当代码仓库越 split，知识越需要 unite。

---

## 一、写在前面

先承认一个事实：**AI 写代码已经很快了，但 AI 不知道你之前为什么那么写。**

这就是当前 AI-assisted 开发的核心矛盾——代码生成效率上去了，但知识复用率没跟上。每个微服务仓库各自为政，A 服务踩过的坑，B 服务照踩不误；三个月前的架构决策，新来的 AI 会话一无所知。

Karpathy 提出过 LLM Wiki 模式：`raw/ → LLM compile → wiki/`。但那是个人知识管理，不适合多仓库微服务团队。

本文要分享的是一个在生产环境可落地的**持续进化知识中枢架构**，解决三个核心问题：

1. **知识从哪来** —— 自动从代码变更中提取，不是人写
2. **知识怎么流** —— 跨仓库自动同步，不手动拷贝
3. **知识怎么活** —— 定期保鲜、自动检测矛盾，不腐烂

---

## 二、工具栈与环境

| 分类             | 工具                                              | 版本   | 作用                                       |
| ---------------- | ------------------------------------------------- | ------ | ------------------------------------------ |
| **AI 工具**      | 任何兼容的 AI 编程助手（已验证：OpenCode、Claude Code） | latest | 加载 AGENTS.md 和 Skill，承载知识库宪法     |
| **规范驱动开发** | [OpenSpec](https://openspec.dev/)                 | >= 1.0 | propose → apply → archive 变更生命周期管理 |
| **版本控制**     | Git + GitHub/GitLab                               | —      | 所有仓库的版本管理和协作基础               |
| **运行时**       | Node.js >= 20.19.0                                | —      | OpenSpec CLI 运行环境                      |

> KoiWeave 与具体 AI 工具解耦。只要 AI 工具支持加载 AGENTS.md 和 Skill，即可使用本体系。

## 三、设计哲学：三环进化架构

整个体系的核心不是目录结构，而是**知识在三个时间尺度上的自动进化**：

```
┌─────────────────────────────────────────────────────────────────────┐
│                     三环持续进化架构                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  微循环（每次变更 ~ 秒级）        日循环（每天 ~ 分钟级）              │
│  ┌─────────────────┐           ┌─────────────────┐                  │
│  │ OpenSpec archive│           │ 健康检查触发     │                  │
│  │    ↓             │           │    ↓             │                  │
│  │ AI 分析 diff     │           │ 术语一致性扫描   │                  │
│  │    ↓             │           │ 链接完整性检查   │                  │
│  │ 提取新实体/ADR   │           │ 时效性检查       │                  │
│  │    ↓             │           │ 矛盾检测         │                  │
│  │ 更新 wiki/       │           │    ↓             │                  │
│  │ AI 总结 + 写入知识 │          │ 报告输出         │                  │
│  └─────────────────┘           └─────────────────┘                  │
│                                                                     │
│  周循环（每周 ~ 小时级）                                             │
│  ┌──────────────────────────────────────┐                          │
│  │ 模式识别 → 知识缺口检测 → 债务推断    │                          │
│  │    ↓                                 │                          │
│  │ 生成周报 + 自动创建 OpenSpec proposal │                          │
│  └──────────────────────────────────────┘                          │
│                                                                     │
│  三个循环独立运转，构成知识库的"新陈代谢"系统                          │
│  不需要人主动维护，AI 自动完成采集→提炼→保鲜→报告                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 三环的分工逻辑

| 环     | 触发条件    | 耗时   | AI 自主性          | 人的角色         |
| ------ | ----------- | ------ | ------------------ | ---------------- |
| 微循环 | 代码归档    | 秒级   | 100% 自动          | 只需 review 代码 |
| 日循环 | cron / hook | 分钟级 | 100% 自动          | 浏览报告         |
| 周循环 | 定时        | 小时级 | 分析自动，行动建议 | 决策是否采纳     |

---

## 四、架构设计原理

### 4.1 整体布局

```
┌─────────────────────────────────────────────────────────────────┐
│                    多仓库知识编织架构                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                    KoiWeave（知识中枢）                        │
│                    ┌─────────────────────────┐                  │
│                    │  signals/               │                  │
│                    │    auto-ingest/ ◀──────────────┐          │
│                    │  wiki/                  │     │           │
│                    │    entities/            │     │           │
│                    │    modules/             │     │           │
│                    │    concepts/            │     │           │
│                    │    architecture/        │     │           │
│                    └──────────┬──────────────┘     │           │
│                               │                     │           │
│                       知识沉淀到 wiki              │           │
│                                                    │           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │           │
│  │ 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/                #   术语表（跨文章一致性保证）
│
└── 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/
```

这个过程不需要任何人介入——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 一眼判断知识是否最新。

```markdown
# Wiki Context Status — service-auth

| 字段              | 值                  |
| ----------------- | ------------------- |
| 最后拉取 (Pull)   | 2026-07-02 10:30:00 |
| 知识中枢 HEAD     | `abc1234`           |
| 知识中枢最新 HEAD | `def5678`           |
| 同步状态          | 🔴 落后 3 次提交    |
| 未推送的回流      | 0 条                |
```

**SYNC_LOG.md**：完整的操作审计日志。

```markdown
# 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` 是这个体系中最关键的文件。AI 工具每次启动时自动加载。它定义了 AI 的行为规则。

### 知识中枢的 AGENTS.md

```markdown
# AGENTS.md — koi-llm-wiki 知识中枢

## 目录语义

- signals/: 只读输入区，不修改原始内容
- wiki/: AI 维护区，按规则增删改
- ~~ops/: 脚本执行区（已废弃，由技能替代）~~

## 知识维护规则

1. 写入知识时必须引用 glossary/ 中的术语
2. 每篇文章必须包含 [[链接]] 指向关联概念
3. 新概念出现时，先检查 glossary 是否存在
4. 修改知识时同步更新 INDEX.md
5. 从 auto-ingest/ 提取知识后标记来源路径
```

### 微服务仓库的 AGENTS.md

```markdown
# 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 页面时，必须先查术语表。新术语出现，先补充到术语表再使用。这就从根源上杜绝了"一个概念三个名字"的问题。

---

## 八、日循环：知识的保鲜机制

知识像生鲜，不及时处理就会腐烂。日循环脚本负责每天自动检查：

```
AI 日循环（通过 health 指令触发）
        │
        ├── ① 术语一致性扫描
        │    检查 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 启动 AI 工具：
       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+ 微服务）

加一个服务只需两步：

1. 在服务仓库中创建 `AGENTS.md` + `.wiki-context/MANIFEST.md`
2. 在知识中枢创建 `signals/auto-ingest/service-xxx/`

剩余的（知识拉取、同步检查、归档回流）全部自动。

### Q4: 谁维护 wiki？会不会变成另一个僵尸文档库？

答案写在三环里：

- **微循环**保证每次代码变更都有知识回流，不回流无法 archive
- **日循环**保证每天检查知识是否过时
- **周循环**保证发现知识缺口

知识不是"写"出来的，是"流"出来的。只要代码在变，知识就在更新。

---

## 十一、收益与成本

### 收益

| 收益             | 原理                                                    |
| ---------------- | ------------------------------------------------------- |
| **不重复决策**   | AI 写代码前读完 ADR，你不会再做同样的技术选型讨论       |
| **不重复踩坑**   | 别的服务遇到的坑记录在 wiki，AI 帮你自动避开            |
| **跨服务一致性** | 所有服务读同一个实体定义、同一个接口契约                |
| **新人上手快**   | AGENTS.md + MANIFEST.md 就是一份精准的 on-boarding 地图 |
| **知识不腐烂**   | 日检自动过期、周检自动填补缺口                          |
| **零维护负担**   | 不需要人写文档，不需要人更新 wiki                       |

### 成本

| 成本         | 评估                                        |
| ------------ | ------------------------------------------- |
| **初始搭建** | 1-2 天（目录结构 + AGENTS.md + 三环脚本）   |
| **服务接入** | 每个服务 10 分钟（AGENTS.md + MANIFEST.md） |
| **运维开销** | 三个 shell 脚本，跑一次几秒钟               |
| **学习曲线** | 理解概念半天，日常使用零上手                |

---

## 十二、总结

> **让 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

你没有来晚，知识中枢才刚刚初始化。
```

---