KoiWeave 架构设计
KoiWeave --- 持续进化的代码研发知识中枢
本文档完整描述 KoiWeave 的目录结构、知识流动规则、多仓库协作模式以及自动化运维机制。
作者：Elcker
目录
- [1. 核心理念](#1. 核心理念)
- [2. 目录结构总览](#2. 目录结构总览)
- [3. 知识流动三环](#3. 知识流动三环)
- [4. 多仓库协作模式](#4. 多仓库协作模式)
- [4.5 同步日志与状态追踪](#4.5 同步日志与状态追踪)
- [4.6 知识拉取机制：从远程仓库到本地可用](#4.6 知识拉取机制：从远程仓库到本地可用)
- [5. AGENTS.md 的职责](#5. AGENTS.md 的职责)
- [6. OpenSpec 在架构中的位置](#6. OpenSpec 在架构中的位置)
- [7. OpenGem (Obsidian 同步)](#7. OpenGem (Obsidian 同步))
- [8. 关键问题与决策记录](#8. 关键问题与决策记录)
1. 核心理念
1.1 设计目标
- 高质量：AI 在写代码前必定读取已有知识，不重复决策、不重复踩坑
- 高效率：知识自动提取、自动维护，人不做机器能做的事
- 持续进化：知识在三次时间尺度上自动迭代，不腐烂、不过时
1.2 设计原则
| 原则 | 含义 |
|---|---|
| 知识驱动开发 | 开发前必读知识，开发后必回流知识 |
| 代码是主要信号源 | 最可靠的知识来自实际代码变更，而非人工撰写 |
| 知识必须保鲜 | 没有定期审核的知识不如没有 |
| AI 替代人做记录 | 人只做决策，提取/归类/链接/维护全部自动化 |
| 工具即管线 | OpenCode + OpenSpec + OpenGem + Obsidian 不是独立工具，是一条端到端管线 |
2. 目录结构总览
2.1 知识中枢仓库 (koi-llm-wiki/)
koi-llm-wiki/
│
├── AGENTS.md # [核心] AI 行为宪法
│ 定义了整套知识系统的操作规则，
│ OpenCode 每次启动都会读取它
│
├── log.md # 全局操作日志（AI 自动维护）
│
├── .gitignore
│
├── signals/ # [输入层] 所有知识的原始信号源
│ ├── inbox/ # 临时收集箱（可手动拖入文件/链接）
│ ├── auto-ingest/ # 自动采集的原始素材（只读，不改）
│ │ ├── service-auth/ # 来自 service-auth 的归档回流
│ │ ├── service-order/ # 来自 service-order 的归档回流
│ │ └── service-payment/ # 来自 service-payment 的归档回流
│ ├── requirements/ # 产品需求文档、会议纪要
│ └── references/ # 外部技术文档、RFC、论文
│
├── wiki/ # [知识层] AI 维护的结构化知识
│ ├── INDEX.md # 全局索引地图（AI 自动维护）
│ ├── MANIFEST.md # 知识保鲜清单：上次审核时间、下次审核时间
│ ├── concepts/ # 抽象概念
│ │ ├── event-loop.md
│ │ ├── cqrs.md
│ │ └── rbac.md
│ ├── entities/ # 业务实体
│ │ ├── User.md
│ │ ├── Order.md
│ │ └── Payment.md
│ ├── modules/ # 功能模块设计
│ │ ├── auth-module.md
│ │ ├── order-module.md
│ │ └── payment-module.md
│ ├── architecture/
│ │ ├── decisions/ # 架构决策记录（ADR，自动生成）
│ │ │ ├── ADR-001-auth-session.md
│ │ │ └── ADR-002-order-lifecycle.md
│ │ ├── proposals/ # 跨服务设计提案（轻量，非 OpenSpec）
│ │ │ └── unified-sso.md
│ │ └── diagrams/ # C4 架构图（Mermaid）
│ ├── summaries/ # 对 signals/ 中长文档的 AI 摘要
│ └── glossary/ # 术语表（跨文章一致性保证）
│
├── ops/ # [运维层] 自动化脚本
│ ├── health-check.sh # 知识库健康检查脚本
│ ├── sync-obsidian.sh # OpenGem Obsidian 同步脚本
│ └── report-weekly.sh # 周报生成脚本
│
└── outputs/ # [衍生层] 生成物
├── charts/ # Mermaid/PlantUML 图表
└── reports/ # 周报、质量报告2.2 微服务仓库 (service-xxx/)
service-auth/ # 任意微服务仓库
│
├── AGENTS.md # [核心] 指向知识中枢的导航指令
│ 包含了「开发前必读 wiki」的规则
│
├── .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/
└── ...2.3 目录结构设计决策
| 决策 | 理由 |
|---|---|
signals/ 而非 raw/ |
不只是"原始素材"，而是包含自动采集通道的信号源，体现 AI 自主采集能力 |
取消 dev/ |
开发在各自服务仓库完成，wiki 中不需要开发目录 |
wiki 仓库不含 openspec/ |
知识中枢不产生代码，OpenSpec 生命周期在服务仓库中完成 |
新增 ops/ |
自动化运维脚本的独立容器，让日循环/周循环可执行 |
新增 MANIFEST.md |
知识的"保鲜期"记录，解决知识老化无人知的问题 |
新增 glossary/ |
术语一致性：AI 写所有页面时参照同一个术语表，避免同物多名 |
新增 architecture/proposals/ |
跨服务设计提案的存放地，作为知识而非 Change 被消费 |
新增 architecture/decisions/ |
ADR 从服务仓库归档时自动生成，非人工撰写 |
3. 知识流动三环
知识的持续进化通过三个时间尺度的循环实现。
3.1 第一环：微循环（每次代码变更）
触发点：服务仓库中的 OpenSpec 归档
┌──────────────────────┐
│ 这个环节 100% AI 自动 │
│ 人不需要介入 │
└──────────────────────┘
service-xxx/openspec archive
│
▼
AI 分析变更 diff
├── 新增了哪些实体？ → 写入 wiki/entities/
├── 修改了哪些模块逻辑？ → 更新 wiki/modules/
├── 涉及哪些概念？ → 更新/创建 wiki/concepts/
├── 有架构决策？ → 生成 wiki/architecture/decisions/ADR-xxx.md
└── 涉及跨服务影响？ → 更新 wiki/architecture/proposals/ 相关提案
│
▼
回流信息写入 signals/auto-ingest/service-xxx/
│
▼
OpenGem (push) → Obsidian 知识库同步3.2 第二环：日循环（每日健康检查）
触发点：cron / git hook / 手动执行 ops/health-check.sh
ops/health-check.sh
│
├── 术语一致性扫描
│ 检查 glossary/ 中的术语在各 wiki 页面中使用是否一致
│
├── 链接完整性检查
│ 检查 wiki/ 中的 [[链接]] 是否全部有效
│
├── 时效性检查
│ 读取 MANIFEST.md，标记超过 30 天未审核的页面为 stale
│
├── 矛盾检测
│ 同一实体/概念在不同页面中的描述是否冲突
│
└── 报告输出
结果记录到 log.md + outputs/reports/3.3 第三环：周循环（战略进化）
触发点：每周自动运行 / 按需触发
AI 分析
├── 代码仓库模式识别
│ 哪些模块变更最频繁？跨服务调用趋势？
├── 知识缺口检测
│ wiki 中缺少哪些必要的概念/实体/决策记录？
├── 技术债务推断
│ 是否存在重复模式、可提取的公共抽象？
│
▼
AI 生成分析报告 → outputs/reports/weekly-review.md
│
▼
人类阅审
├── 批准技术债务修复 → 在服务仓库中创建 OpenSpec change
├── 批准知识补充 → 直接更新 wiki 或创建 proposal
└── 忽略/推迟3.4 三环工作原理
微循环 日循环 周循环
(每次变更) (每天) (每周)
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 代码归档触发 │ │ cron 定时触发 │ │ 自动分析 │
│ 知识自动提取 │ │ 健康检查 │ │ 模式识别 │
│ wiki 即时更新 │ │ 不一致修复 │ │ 缺口检测 │
│ Obsidian 推送 │ │ 报告输出 │ │ 提案生成 │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
│ 保证已有知识不腐烂 │
│ │
└──────────────────┬──────────────────────┘
│
▼
知识库持续进化
不堆积、不老化、不重复4. 多仓库协作模式
4.1 架构总览
koi-llm-wiki（知识中枢）
┌─────────────────────────┐
│ signals/ │
│ auto-ingest/ ◀────────────── 各服务归档回流
│ wiki/ │
│ entities/ │
│ modules/ │
│ concepts/ │
│ architecture/ │
└──────────┬──────────────┘
│
OpenGem (push)
│
▼
Obsidian Vault
(可读、可搜索、可链接)
│
│
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ service-auth/ │ │ service-order/ │ │ service-payment/ │
│ │ │ │ │ │
│ AGENTS.md │ │ AGENTS.md │ │ AGENTS.md │
│ ↓ │ │ ↓ │ │ ↓ │
│ .wiki-context/ │ │ .wiki-context/ │ │ .wiki-context/ │
│ MANIFEST.md │ │ MANIFEST.md │ │ MANIFEST.md │
│ │ │ │ │ │
│ openspec/ │ │ openspec/ │ │ openspec/ │
│ changes/ │ │ changes/ │ │ changes/ │
│ specs/ │ │ specs/ │ │ specs/ │
└──────────────────┘ └──────────────────┘ └──────────────────┘4.2 .wiki-context/MANIFEST.md 示例
每个微服务仓库中的 MANIFEST.md 不加锁，由 AI 自动维护。
markdown
# .wiki-context: service-auth
## 相关模块
- `wiki/modules/auth-module/` ← 认证模块设计
- `wiki/modules/user-service/` ← 用户服务接口
## 相关实体
- `wiki/entities/User`
- `wiki/entities/Session`
- `wiki/entities/Token`
## 相关概念
- `wiki/concepts/jwt-authentication`
- `wiki/concepts/oauth2-flow`
- `wiki/concepts/rbac`
## 相关 ADR
- `wiki/architecture/decisions/ADR-001-auth-session`
- `wiki/architecture/decisions/ADR-007-token-refresh`
## 依赖的服务
- `service-order` → 用户鉴权
- `service-payment` → 用户身份校验4.3 知识投射流程
AI 在 service-auth 中启动 OpenCode
│
▼
AGENTS.md 被加载
│
├── 读取 .wiki-context/MANIFEST.md
│ │
│ ▼
├── 按 MANIFEST 索引加载相关知识
│ ├── wiki/modules/auth-module/ → 架构设计
│ ├── wiki/entities/User → 实体定义
│ └── wiki/architecture/decisions/ → 历史决策
│
├── 基于完整上下文编写代码
│
└── OpenSpec archive 时自动回流
│
▼
回流信息 → signals/auto-ingest/service-auth/4.4 跨服务架构变更（不使用 OpenSpec 编排）
[场景: 统一 SSO 方案]
1. 写提案（轻量文档，不是 OpenSpec change）
人在 wiki 仓库中创建：
wiki/architecture/proposals/unified-sso.md
├── 背景与动机
├── 方案选型对比
├── 各服务改动点清单
└── 接口契约定义
2. 提案作为知识被消费
service-auth 启动 OpenCode：
AGENTS.md → `读取 wiki/architecture/proposals/`
AI 看到 unified-sso.md
→ 在 service-auth/openspec 创建 change
→ 实现 auth 侧的 SSO 改动
service-order 同上。
3. 知识回流
各服务归档 → 回流 signals/auto-ingest/
日检发现原提案标记的改动已完成
→ 无需额外编排4.5 同步日志与状态追踪
服务仓库持有的知识是知识中枢的本地镜像。必须追踪这个镜像的时效性，否则 AI 可能基于过时的知识做出错误决策。
4.5.1 状态文件：.wiki-context/STATUS.md
每个服务仓库维护一个精简的状态文件，AI 启动时第一眼就能知道知识是否最新。
markdown
# Wiki Context Status --- service-auth
## 当前同步状态
| 字段 | 值 |
|---|---|
| 最后拉取 (Pull) | 2026-06-20 10:30:00 |
| 知识中枢 HEAD | `abc1234` (main) |
| 知识中枢最新 HEAD | `def5678` (main) |
| 同步状态 | 🔴 落后 3 次提交 |
| 未推送的回流 | 0 条 |
| 上次健康检查 | 2026-06-20 09:00:00 ✅ |
## 快速判断
- 🟢 **最新** --- 可以直接开始开发
- 🔴 **落后** --- AI 必须先执行 pull 更新本地镜像，再开始开发
- 🟡 **有未推送回流** --- 上次归档的回流尚未被知识中枢消费
- ⚠️ **冲突** --- push 时发现与知识中枢现有内容冲突，需人工介入STATUS.md 由 AI 在每次 pull / push 操作后自动更新，人不手动维护。
4.5.2 日志文件：.wiki-context/SYNC_LOG.md
完整的操作审计日志，记录每一次知识同步。
markdown
# Sync Log --- service-auth
## Pull（从知识中枢拉取）
| 时间 | 操作 | 拉取版本 | 涉及内容 | 拉取方式 | 结果 |
|---|---|---|---|---|---|
| 2026-07-02 10:30 | pull | `abc1234` | entities/User, modules/auth, ADR-001 | 全文拉取 | ✅ |
| 2026-06-30 09:15 | pull | `a1b2c3d` | concepts/rbac, ADR-001, ADR-007 | 增量拉取 | ✅ |
| 2026-06-28 14:00 | pull | `f0e1d2c` | proposals/unified-sso | 按需拉取 | ✅ |
## Push（向知识中枢回流）
| 时间 | 操作 | 关联 Change | 推送内容 | 结果 |
|---|---|---|---|---|
| 2026-07-02 11:00 | push | add-phone-login | 新实体 PhoneLogin, 更新 ADR-001 | ✅ 已接收 |
| 2026-06-29 16:30 | push | fix-session-expiry | 更新 Session 实体 | ⚠️ 冲突：Session 已在中枢被修改 |
| 2026-06-25 10:00 | push | refactor-auth-middleware | ADR-008 新增 | ✅ 已接收 |拉取方式说明
| 方式 | 适用场景 | AI 操作 |
|---|---|---|
| 全文拉取 | 首次建立上下文，或落后超过 10 次提交 | 读取 MANIFEST.md 中列出的所有 wiki 文件 |
| 增量拉取 | 少量落后（1-5 次提交） | 只读取知识中枢有变更的文件 |
| 按需拉取 | 特定提案/概念需要参考 | 只读取单个文件，不更新本地镜像状态 |
冲突处理
Push 时发现冲突（知识中枢已有内容的更新比本次回流更新），AI 采取以下策略：
冲突类型：实体/模块在同一时间段被两个服务同时修改
处理步骤：
1. AI 读取知识中枢中的最新版本
2. AI 对比本地版本与中枢版本，识别差异点
3. 如果差异可合并 → AI 自动合并后重新 push
4. 如果差异不可合并 → 标记 SYNC_LOG 为冲突
→ 人介入解决
→ 解决后更新 STATUS.md 为 🟢4.5.3 完整同步流程
知识中枢 (koi-llm-wiki)
┌────────────────────────┐
│ wiki/entities/User v3 │
│ wiki/modules/auth v2 │
└───────────┬────────────┘
│
╔════════════════════╪════════════════════╗
║ Pull 流程 │ ║
║ │ ║
║ ┌────────────────▼────────────┐ ║
║ │ ① AI 启动 → 读 STATUS.md │ ║
║ │ → 状态 🔴 落后 │ ║
║ │ ② AI 向知识中枢发起 pull │ ║
║ │ → 读取 v3 的 User.md │ ║
║ │ → 读取 v2 的 auth-module │ ║
║ │ ③ 更新 STATUS.md → 🟢 │ ║
║ │ ④ 追加 SYNC_LOG.md 记录 │ ║
║ └─────────────────────────────┘ ║
║ ║
║ Push 流程 ║
║ ┌─────────────────────────────┐ ║
║ │ ① OpenSpec archive 触发 │ ║
║ │ ② AI 提取知识变更 │ ║
║ │ ③ 写入 signals/auto-ingest/ │ ║
║ │ ④ 追加 SYNC_LOG.md 记录 │ ║
║ │ ⑤ 更新 STATUS.md → 确认 │ ║
║ └─────────────────────────────┘ ║
╚══════════════╦═══════════════════════════╝
│
┌────┴────┐
│ service │
│ -auth │
│ │
│ STATUS │
│ SYNC_LOG│
└─────────┘4.5.4 AI 启动检查清单
AI 在服务仓库中启动开发会话时，必须按以下顺序执行：
□ 1. 读取 .wiki-context/STATUS.md
→ 判断同步状态
→ 如果 🔴 落后：先执行 pull，再继续
→ 如果 ⚠️ 冲突：通知人类处理，暂停
□ 2. 读取 .wiki-context/MANIFEST.md
→ 获取本服务相关的知识路径索引
□ 3. 按索引加载知识到上下文
→ 实体定义、模块设计、ADR、概念
□ 4. 检查 SYNC_LOG.md 最近的 pull 记录
→ 确认当前上下文的时间点
□ 5. 开始开发4.6 知识拉取机制：从远程仓库到本地可用
这是最关键的实践问题。wiki 仓库和各服务仓库是独立的 git 仓库，存储在不同服务器上（或同一台服务器的不同目录）。AI 在服务仓库中启动时，如何拿到 wiki 中的知识？
4.6.1 路径解析优先级链
AGENTS.md 中关于知识源的声明，采用三级路径解析：
服务仓库中 AGENTS.md 声明：
"本服务的架构知识存储在项目级知识中枢"
AI 解析路径时依次尝试：| 优先级 | 方式 | 说明 |
|---|---|---|
| P0 | 环境变量 KOI_WIKI_PATH |
最灵活，CI/CD 和本地开发通用 |
| P1 | 服务仓库中的 git submodule | 自包含，适合团队标准化 |
| P2 | 相对路径 ../koi-llm-wiki/ |
本地开发约定，零配置 |
| P3 | 自动 clone 到 ~/.koi-wiki/ |
兜底，首次使用自动下载 |
4.6.2 三种拉取方式详解
方式 A：环境变量（推荐）
开发者机器 / CI 服务器上设置：
KOI_WIKI_PATH=/data/repos/koi-llm-wiki
AI 的工作流程：
1. 读取环境变量 $KOI_WIKI_PATH
2. 检查路径是否存在
3. 如果不存在 → git clone git@github.com:org/koi-llm-wiki.git $KOI_WIKI_PATH
4. 如果存在 → git -C $KOI_WIKI_PATH pull --ff-only
5. 读取 $KOI_WIKI_PATH/wiki/ 下的知识
6. 更新 STATUS.md (PULL_TIME, WIKI_HEAD)
7. 追加 SYNC_LOG.md优点：
- 环境变量一次设置，所有服务共享同一个 wiki clone
- 避免每个服务都 clone 一份 wiki，节约磁盘
- CI/CD 中只需在 pipeline 层面设置一个变量
缺点：
- 需要初始化步骤（设置环境变量 / 首次 clone）
方式 B：Git Submodule（开箱即用）
每个服务仓库将 wiki 仓库添加为 submodule：
cd service-auth
git submodule add git@github.com:org/koi-llm-wiki.git .wiki-context/koi-llm-wiki
git submodule init
git submodule update
目录结构变为：
service-auth/
├── .wiki-context/
│ ├── MANIFEST.md
│ ├── STATUS.md
│ ├── SYNC_LOG.md
│ └── koi-llm-wiki/ ← git submodule，指向知识中枢
│ ├── wiki/
│ └── signals/
└── openspec/AI 的工作流程：
Service Repo Wiki Submodule
┌──────────────┐ ┌──────────────┐
│ │ │ │
│ git status │────同步──────▶│ 检查 submod │
│ │ │ 是否最新 │
└──────────────┘ └──────┬───────┘
│
┌────────────┴────────────┐
│ │
落后 / 未初始化 已是最新
│ │
▼ ▼
git submodule update --remote 直接读取
--merge .wiki-context/koi-llm-wiki
│
▼
更新 STATUS.md
追加 SYNC_LOG.md优点 ：git 原生支持，git clone --recurse-submodules 一键拉取所有内容
缺点：每个仓库持有一份 wiki 副本，多人开发时 submodule commit 容易漂移
方式 C：自动 Clone（零配置兜底）
AI 在服务仓库中启动，发现没有任何路径指向 wiki：
1. AI 检查 KOI_WIKI_PATH → 未设置
2. AI 检查 ../koi-llm-wiki/ → 不存在
3. AI 检查 .wiki-context/koi-llm-wiki/ → 不存在
4. AI 读取 AGENTS.md 中的 wiki 仓库地址：
"知识中枢仓库: git@github.com:org/koi-llm-wiki.git"
5. AI clone 到 ~/.koi-wiki/koi-llm-wiki/
6. 更新 STATUS.md
7. 追加 SYNC_LOG.md: "首次自动 clone"4.6.3 推荐方案组合
| 场景 | 推荐方式 | 理由 |
|---|---|---|
| 个人本地开发 | 方式 A（环境变量） | 一次 clone，所有服务共享，AI 自动维护 |
| 团队标准化 | 方式 A + B 混合 | 环境变量为主，submodule 作为 fallback |
| CI/CD 流水线 | 方式 A（环境变量） | pipeline yaml 中设置变量，runner 上 clone |
| 新手开箱 | 方式 C（自动 clone） | 零配置，第一次启动自动完成 |
最佳实践（推荐给团队）：
1. 团队约定统一的wiki仓库路径：
/opt/koi-wiki/koi-llm-wiki/ （服务器）
~/koi-wiki/koi-llm-wiki/ （本地开发机）
2. 写入团队的开发环境初始化脚本：
# setup-wiki.sh
if [ ! -d "$KOI_WIKI_PATH" ]; then
git clone git@github.com:org/koi-llm-wiki.git $KOI_WIKI_PATH
fi
echo "KOI_WIKI_PATH=$KOI_WIKI_PATH" >> ~/.bashrc
3. 各服务仓库的 AGENTS.md 中声明：
"知识中枢路径参考环境变量 KOI_WIKI_PATH，默认 ../koi-llm-wiki/"4.6.4 在服务仓库中启动 AI 的完整流程
整合同步检查（4.5）和拉取机制（4.6），AI 在服务仓库中的完整启动流程：
┌─────────────────────────────────────────────────────────────┐
│ 服务仓库中 AI 启动完整流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Step 0: 路径解析 │
│ │ │
│ ├── 检查 $KOI_WIKI_PATH │
│ │ ├── 存在 → 验证路径是否有效 │
│ │ └── 不存在 → 尝试方式 B / C │
│ │ │
│ ▼ │
│ Step 1: 同步状态检查 │
│ │ │
│ ├── 读取 .wiki-context/STATUS.md │
│ ├── 获取本地记录的 WIKI_HEAD │
│ ├── git fetch 知识中枢 → 获取远程最新 HEAD │
│ ├── 比较 WIKI_HEAD vs 远程 HEAD │
│ │ ├── 一致 → 🟢 无需操作 │
│ │ └── 不一致 → 🔴 执行 pull │
│ │ │
│ ▼ │
│ Step 2: 执行 Pull │
│ │ │
│ ├── git pull 或 git submodule update │
│ ├── 更新 STATUS.md (PULL_TIME, WIKI_HEAD) │
│ ├── 追加 SYNC_LOG.md │
│ │ │
│ ▼ │
│ Step 3: 加载知识上下文 │
│ │ │
│ ├── 读取 .wiki-context/MANIFEST.md │
│ ├── 按索引读取 wiki 文件 │
│ │ ├── 实体 → concepts → 模块 → ADR → 提案 │
│ │ │
│ ▼ │
│ Step 4: 开始开发 │
│ │ │
│ └── AI 基于完整上下文编写代码 │
│ │
│ ...（开发完成后） │
│ │
│ Step N: OpenSpec Archive 触发 Push │
│ │ │
│ ├── 提取知识变更 │
│ ├── 写入 signals/auto-ingest/service-xxx/ │
│ ├── 追加 SYNC_LOG.md (push 记录) │
│ └── 更新 STATUS.md │
│ │
└─────────────────────────────────────────────────────────────┘4.6.5 多开发者 / CI 环境下的注意事项
| 场景 | 问题 | 解决方案 |
|---|---|---|
| 开发者 A 更新了 wiki | 开发者 B 仍然看到旧知识 | AI pull 时自动检测远程更新，STATUS.md 自动变 🔴 |
| CI 流水线同时跑多个 job | 各自 clone wiki 耗时 | 在 runner 上缓存 wiki 仓库，路径通过环境变量传入 |
| 两个服务同时 push 回流 | signals/auto-ingest/ 写入冲突 | 按服务名分目录写入，各自隔离 |
| wiki 仓库被 force push | submodule 无法同步 | 推荐方式 B（submodule）时禁用 force push，方式 A 无此问题 |
| 开发者离线工作 | 无法 pull 最新知识 | STATUS.md 标记为 ⚠️ 离线，允许基于本地缓存继续开发，上线前必须重新 pull |
5.1 知识中枢 AGENTS.md (koi-llm-wiki/AGENTS.md)
定义中枢本身的维护规则：
markdown
# AGENTS.md --- koi-llm-wiki 知识中枢
## 目录语义
- signals/: 只读输入区，AI 不可修改原始素材
- wiki/: AI 维护的知识区，按规则增删改
- ops/: 自动化脚本存放地
- outputs/: 生成物输出目录
## 知识维护规则
1. 每次写入知识时，必须引用 glossary/ 中的术语
2. 每篇文章必须包含关联实体/概念的 [[链接]]
3. 新概念出现时，必须检查是否存在于 glossary/
4. 修改知识时，必须同步更新 INDEX.md
5. 从 auto-ingest/ 提取知识后，标记来源路径
## 知识保鲜
- MANIFEST.md 中的 lastReviewed 超过 30 天的页面标记 stale
- stale 页面优先在下次日检中重写或删除5.2 服务仓库 AGENTS.md (service-xxx/AGENTS.md)
衔接知识中枢与开发过程：
markdown
# AGENTS.md --- service-auth
## 知识源
本服务的架构知识存储在项目级知识中枢：
../koi-llm-wiki/ （同级目录或 git submodule 引入）
## 强制流程
### Step 0: 启动时检查同步状态
读取 .wiki-context/STATUS.md：
1. 如果同步状态为 🔴 落后 → 先执行 pull 再继续
2. 如果同步状态为 ⚠️ 冲突 → 通知人类，暂停开发
3. pull 完成后更新 STATUS.md 为 🟢，并写入 SYNC_LOG.md
### Step 1: 加载知识上下文
读取 .wiki-context/MANIFEST.md → 加载所有相关的 wiki 知识
按以下优先级加载：
1. 架构决策（ADR）--- 理解历史原因
2. 实体定义 --- 确保数据模型一致
3. 模块设计 --- 理解当前架构
4. 相关提案（proposals）--- 了解进行中的变更
### Step 2: 变更前验证知识
对照已加载的 wiki 知识与当前代码：
1. 代码是否已偏离 wiki 中的设计？
2. wiki 中的知识是否需要更新？
3. 如果存在差异 → 先更新 wiki，再改代码
### Step 3: 变更后回流
OpenSpec archive 时自动执行：
1. 提取本变更引入的新实体 / 新概念
2. 提取设计决策 → 形成 ADR 素材
3. 写入 signals/auto-ingest/service-auth/
4. 追加 SYNC_LOG.md 记录（push 条目）
5. 更新 STATUS.md 确认回流已发出6. OpenSpec 在架构中的位置
6.1 范围限定
OpenSpec 只存在于微服务仓库中，用于管理功能级别的变更。
koi-llm-wiki 仓库中不需要 openspec/ 目录。6.2 OpenSpec 生命周期与知识回流的对应关系
propose → 设计文档写入 wiki/architecture/proposals/
│
▼
apply → 代码实现（无知识操作）
│
▼
archive ◀──→ 知识回流（关键节点）
│
├── 提取新实体 → wiki/entities/
├── 更新模块设计 → wiki/modules/
├── 生成 ADR → wiki/architecture/decisions/
├── 更新术语 → wiki/glossary/
└── 写入回流记录 → signals/auto-ingest/service-xxx/6.3 为什么 wiki 仓库不需要 OpenSpec
| 原因 | 说明 |
|---|---|
| OpenSpec 的生命周期是 propose → apply → archive | wiki 仓库没有代码可 apply |
| 知识中枢的变更（如新增分类）直接改即可 | 不需要用 OpenSpec 管理知识结构调整 |
| 跨服务设计提案是知识 不是变更 | 放在 architecture/proposals/ 作为文档被消费 |
7. OpenGem (Obsidian 同步)
7.1 同步模式
Push 模式（AI 主动推送）：
wiki/ 发生变更（AI 写入/修改知识）
│
▼
ops/sync-obsidian.sh
│
├── 读取 wiki/INDEX.md 获取全量文章列表
├── 比较 Obsidian vault 中的状态
├── 将新增/修改的 .md 文件推送到 Obsidian vault
├── 删除 Obsidian 中不再存在的条目（需确认）
└── 记录同步结果到 log.md7.2 OpenGem 的作用
OpenGem 是 OpenCode 的 Obsidian 插件桥，核心能力：
- 读取：AI 从 Obsidian vault 中搜索和读取笔记
- 写入：AI 将知识写入 Obsidian vault
- 搜索：AI 在 Obsidian 笔记中执行全文搜索
- 维护：自动维护 Obsidian 中的知识结构和链接
7.3 同步策略
| 场景 | 策略 |
|---|---|
| AI 写入新知识到 wiki/ | 立即 push 到 Obsidian |
| AI 更新已有知识 | push 更新到 Obsidian |
| 手动在 Obsidian 中写笔记 | 可选：定期 pull 到 signals/inbox/ |
| 删除知识 | 标记删除，确认后同步 |
8. 关键问题与决策记录
Q1: 多仓库间代码如何存放？
决策：代码放在各自的微服务仓库中，知识中枢只存知识和规格。
koi-llm-wiki/--- 知识中枢（当前仓库）service-auth/--- 独立微服务仓库service-order/--- 独立微服务仓库
Q2: 跨服务架构变更如何协调？
决策：不使用 OpenSpec 编排，使用 wiki/architecture/proposals/ 作为共享知识。
- 在知识中枢写一篇 proposal 文档
- 各服务 AGENTS.md 强制读取 proposal
- 各自在本地 OpenSpec 实现自己的部分
- 归档时各自回流，知识自动编织
Q3: 开发时 AI 如何获取知识？
决策 ：通过 AGENTS.md + .wiki-context/MANIFEST.md 实现。
AI 在服务仓库启动时，AGENTS.md 强制要求：
- 读取 MANIFEST.md 获取相关知识的路径索引
- 按索引读取 wiki 中的模块设计、实体定义、ADR
- 基于完整上下文编写代码
Q4: 每个服务仓库启动时，AI 如何从远程 wiki 仓库拉取知识？
决策：采用三级路径解析 + 自动拉取。
AI 路径解析优先级：
P0: $KOI_WIKI_PATH 环境变量 (推荐，团队标准化)
P1: git submodule .wiki-context/ (开箱即用)
P2: ../koi-llm-wiki/ 相对路径 (本地开发约定)
P3: 自动 clone 到 ~/.koi-wiki/ (零配置兜底)AI 启动时自动执行：
- 解析 wiki 仓库路径（按优先级链尝试）
- 检查
.wiki-context/STATUS.md记录的本地版本 git fetch远程对比，发现落后则自动 pull- 更新 STATUS.md 和 SYNC_LOG.md
- 按 MANIFEST.md 索引加载知识
详见 [4.6 知识拉取机制](#4.6 知识拉取机制)。
Q5: 知识保鲜如何实现？
决策：通过 MANIFEST.md + 日检脚本。
- 每篇知识条目有 lastReviewed 时间戳
- 超过 30 天未审核的标记为 stale
- 日检时优先处理 stale 条目
- 周检时分析知识缺口