KoiWeave v2.0 --- 从"AI 自觉"到"AI 受控"
一、背景：AI 写代码很快，但 AI 不知道你之前为什么那么写
这是当前 AI-assisted 开发的核心矛盾------代码生成效率上去了，但知识复用率没跟上。
我们面临三个具体问题：
| 问题 | 表现 | 后果 |
|---|---|---|
| 知识碎片化 | 架构决策散落在 Slack/PR/Comment 里，AI 看不到 | 重复决策、重复踩坑 |
| 知识不流动 | service-auth 的 ADR 不会自动同步到 service-order | 各服务各自为政 |
| 知识会腐烂 | 三个月前的设计文档没人更新 | 逐渐变成错误文档 |
KoiWeave 的回答是：让 AI 在写代码前必须读完相关的历史知识，在写完后必须把新知识吐回来。
二、架构总览：三环进化 + 双 Skill 体系
2.1 整体布局
KoiWeave（本仓库）
│
┌───────────┴───────────┐
│ │
koi-llm-wiki/ skills/
（知识中枢仓库） （AI Skill 定义）
│ │
│ ┌───────┴───────┐
│ │ │
│ koi-weave-wiki koi-weave-dev
│ （中枢运维） （开发辅助）
│ │ │
└───────────────┴───────────────┘
│
┌─────────────┼─────────────┐
│ │ │
service-auth service-order service-payment2.2 三环进化机制
知识在三个时间尺度上自动进化：
微循环（每次归档 ~ 秒级）
push → 写 staging → 写 auto-ingest → 中枢消化 → 创建确认标记
日循环（每天 ~ 分钟级）
健康检查 → 术语一致性 → 链接完整性 → 时效标记(30d) → 矛盾检测
周循环（每周 ~ 小时级）
回流模式分析 → 知识缺口检测 → 公共抽象提取 → 周报生成三、v1.x 的教训：文本宪法管不住 AI
3.1 旧方案长什么样
v1.x 的核心思路是：在 AGENTS.md 里写规则，告诉 AI 该怎么做。
AGENTS.md 中定义了"四步锁"：
Step 0: 读取 STATUS.md → 判断同步状态 → 落后则 pull
Step 1: 读取 MANIFEST.md → 加载知识到上下文
Step 2: 四问验证 → 通过前禁止编码
Step 3: 归档回流 → 分析 diff → 写回中枢3.2 问题在哪
AGENTS.md 是文本，AI 可以自由决定是否遵守。实践中我们发现：
- AI 会"忘记"执行某些步骤------问就说做了，实际上没做
- 同一操作不同 AI 工具行为不同------OpenCode、Claude Code、Cursor 各自解读
- 回流没有事务保证------"上传成功删除，失败重试"这个需求无法实现
- 去重靠 AI 自觉------"检查 SYNC_LOG 最近 5 条"这种指令，AI 不一定执行
- 不可复现------人无法复现 AI 的操作流程
核心矛盾：约束写在文本里，执行靠 AI 自觉------这本身就是矛盾的。
四、v2.0 升级：从"AI 自觉"到"AI 受控"
4.1 核心变化
v1.x: AGENTS.md 文本声明 → AI 自觉遵守
↓
v2.0: SKILL.md + scripts/ 可执行脚本 → AI 按步骤执行 bash 命令 → 输出 JSONAI 不再直接操作文件，而是通过 skill script 执行：
用户："知识回流"
→ AI 读取 SKILL.md 找到 push 命令
→ AI 分析 diff，生成标准 YAML
→ AI 调用 bash scripts/push.sh <change-name>
→ push.sh 执行三阶段事务，输出 JSON
→ AI 读取 JSON，向用户汇报4.2 双 Skill 体系
v2.0 将原本的一个 skill 拆分为两个独立 skill，职责分界清晰：
koi-weave-wiki（知识中枢运维）
├── SKILL.md 入口
├── scripts/
│ ├── digest.sh 扫描 signals/ 素材
│ └── health.sh 健康检查
├── references/ 参考文档
└── assets/templates/ 初始化模板
koi-weave-dev（微服务开发辅助）
├── SKILL.md 入口
├── scripts/
│ ├── status.sh 同步检查 + 事务审计
│ ├── pull.sh git pull --ff-only
│ └── push.sh 三阶段事务回流
├── references/ 四问验证 + 事务说明
├── assets/templates/ 服务宪法模板4.3 标准 Skill 目录结构
每个 skill 遵循统一结构：
skills/<name>/
├── SKILL.md 核心（必选）：技能定义 + 操作指南
├── README.md 人类阅读的使用说明
├── scripts/ 辅助 shell 脚本（AI 调用执行）
├── references/ 参考文档（规则说明、原理图）
└── assets/ 静态资源（模板、图片）五、三阶段事务：解决"上传成功删除，失败重试"
这是 v2.0 最核心的技术设计。
5.1 问题场景
开发者完成功能开发后执行回流：
- 如果中途网络断了怎么办？
- git push 失败了，staging 文件还在吗？
- 下一次重推会不会重复写入？
5.2 三阶段协议
hash 去重
┌──────────┐ ┌──────────────┐ 成功 ┌──────────┐
│ AI生成 │───→│ Phase 1 │───────────→│ PENDING │
│ YAML │ │ PREPARE │ └─────┬─────┘
└──────────┘ │ 写 staging │ │
└──────────────┘ 失败重试 │
│ 成功
▼
┌──────────────┐
│ Phase 2 │
│ COMMIT │
│ 写 auto-ingest│
│ git push │
└──────┬───────┘
│
┌───────┴───────┐
│ │
git push 失败 写入成功
│ │
▼ ▼
重试保留staging ┌──────────┐
│ COMMITTED │
└─────┬─────┘
│
中枢 digest
│
▼
.done 创建
│
status 检测
│
▼
┌──────────┐
│ ACKED │
│ 删 staging│
└──────────┘5.3 关键设计点
幂等性：每个回流内容计算 SHA256 指纹。相同内容 always 相同 hash。三阶段各环节都做去重检查。
文件见证：
Phase 1: .wiki-context/staging/<change>.pending.yaml
Phase 2: koi-llm-wiki/signals/auto-ingest/<service>/<change>.yaml
Phase 3: .../.ack/<change>.done（中枢 digest 完成后创建）边界情况：
| 场景 | 行为 |
|---|---|
| git push 网络超时 | staging 保留，重试幂等 |
| 同内容重推 | hash 相同，跳过写入 |
| 内容修改后重推 | hash 变化，覆盖旧内容 |
| 离线开发 | 允许，staging 保留，上线后推送 |
六、标准化回流格式
v1.x 的回流内容是 AI 自由撰写的 Markdown 文本。v2.0 定义为标准 YAML Schema：
yaml
schema_version: "1.0"
service: auth
change_name: add-phone-login
entities:
- name: PhoneLogin
summary: "手机号登录凭证"
fields:
- { name: phone, type: string }
modules_updated:
- name: auth-module
changes: "新增 phoneLogin() 方法"
architecture_decisions:
- title: "手机登录安全策略"
summary: "验证码5分钟有效，错误5次锁定30分钟"
glossary_terms:
- { cn: "短信验证码", en: "SMS Code", definition: "一次性验证码" }AI 只负责"分析 diff → 填字段"，CLI 负责"校验 → hash → 存储 → git push"。职责分界清晰。
七、跨平台兼容
所有脚本兼容 Linux、macOS、Windows（Git Bash）：
| 命令 | Linux | macOS | Windows | 方案 |
|---|---|---|---|---|
| SHA256 | sha256sum | shasum -a 256 | 同上之一 | 自动检测函数 |
| 时间戳 | date -Iseconds | 不支持 | 不支持 | date -u +"%Y-%m-%dT%H:%M:%S%z" |
| sed -i | ✅ | 需备份后缀 | ⚠️ | 脚本中避免使用 |
bash
# 跨平台 SHA256 检测
_sha256() {
if command -v sha256sum >/dev/null 2>&1; then
echo -n "$1" | sha256sum | cut -d' ' -f1
elif command -v shasum >/dev/null 2>&1; then
echo -n "$1" | shasum -a 256 | cut -d' ' -f1
elif command -v openssl >/dev/null 2>&1; then
echo -n "$1" | openssl dgst -sha256 | cut -d' ' -f2
fi
}零安装依赖------bash + git + sha256sum/shasum/openssl 均为操作系统自带。
八、AI 工具集成
三种主流 AI 编程工具均可使用：
| 工具 | 加载方式 | Skill 目录 |
|---|---|---|
| OpenCode | 自动发现 .opencode/skills/ |
.opencode/skills/koi-weave-*/ |
| Claude Code | CLAUDE.md 引用 | skills/koi-weave-*/ |
SKILL.md 是 AI 的操作指南，AGENTS.md 是行为宪法，scripts/ 是可执行工具------三层约束确保 AI 行为一致。
九、从 v1.x 到 v2.0 的迁移
| 维度 | v1.x | v2.0 |
|---|---|---|
| 约束方式 | AGENTS.md 文本声明 | SKILL.md + 可执行 bash 脚本 |
| 回流事务 | 无保证 | 三阶段 PREPARE → COMMIT → ACK |
| 去重机制 | AI 人工检查 | SHA256 内容指纹自动去重 |
| 脚本语言 | Node.js（需安装） | bash（系统自带） |
| Skill 数量 | 1 个合并 skill | 2 个独立 skill（wiki + dev） |
| 技能结构 | 单个 SKILL.md | SKILL.md + scripts/ + references/ + assets/ |
| AGENTS.md 强度 | 建议性 | 宪法级（含禁止操作条款） |
| 跨平台 | 仅 Linux | Linux + macOS + Windows Git Bash |
十、完整开发流程演示
===== 第 1 步：知识中枢初始化 =====
koi-weave-wiki init ./koi-llm-wiki
→ 创建骨架：AGENTS.md + wiki/ + signals/ + outputs/
===== 第 2 步：接入微服务 =====
koi-weave-dev init auth
→ 创建 AGENTS.md + .wiki-context/ + staging/ + 中枢回流目录
===== 第 3 步：日常开发循环 =====
# 检查同步
koi-weave-dev status # 🟢 最新
# 加载知识
koi-weave-dev load-task "给用户增加手机号登录"
→ 自动匹配加载：User, PhoneLogin, auth-module, ADR-001, ADR-007
→ 输出四问清单
# 编码前验证（AI 逐条附证据）
✅ 问题一：涉及 User, PhoneLogin, auth-module
✅ 问题二：wiki 定义 login(phone) → 代码 loginByPhone() 匹配
✅ 问题三：ADR-001 要求 JWT → 本变更输出 JWT
✅ 问题四：glossary "SMS Code" → 变量名 smsCode
# AI 编码...
# 回流
cat <<'YAML' | koi-weave-dev push add-phone-login
schema_version: "1.0"
service: auth
change_name: add-phone-login
entities:
- name: PhoneLogin
summary: "手机号登录凭证"
YAML
# 查看回流状态
koi-weave-dev status
→ 自动检测 .done → 清理 staging
→ 🟢 最新，回流已确认十一、总结
KoiWeave v2.0 的核心思想很简单：把 AI 该遵守的规则从文本变成可执行工具。
AI 做它最擅长的（分析 diff、提取知识、生成 YAML），脚本做最需要确定性的（文件操作、hash 计算、git push）。
这就是 v2.0 的全部秘密------不是约束变多了，而是约束从软的变成了硬的。
参考
- 项目地址：KoiWeave
- 架构设计文档：
doc/KoiWeave 架构设计.md - 协议：MIT