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 的教训文本宪法管不住 AI3.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 Schemaschema_version:1.0service:authchange_name:add-phone-loginentities:-name:PhoneLoginsummary:手机号登录凭证fields:-{name:phone,type:string}modules_updated:-name:auth-modulechanges:新增 phoneLogin() 方法architecture_decisions:-title:手机登录安全策略summary:验证码5分钟有效错误5次锁定30分钟glossary_terms:-{cn:短信验证码,en:SMS Code,definition:一次性验证码}AI 只负责分析 diff → 填字段CLI 负责校验 → hash → 存储 → git push。职责分界清晰。七、跨平台兼容所有脚本兼容 Linux、macOS、WindowsGit Bash命令LinuxmacOSWindows方案SHA256sha256sumshasum -a 256同上之一自动检测函数时间戳date -Iseconds不支持不支持date -u “%Y-%m-%dT%H:%M:%S%z”sed -i✅需备份后缀⚠️脚本中避免使用# 跨平台 SHA256 检测_sha256(){ifcommand-vsha256sum/dev/null21;thenecho-n$1|sha256sum|cut-d -f1elifcommand-vshasum/dev/null21;thenecho-n$1|shasum-a256|cut-d -f1elifcommand-vopenssl/dev/null21;thenecho-n$1|openssl dgst-sha256|cut-d -f2fi}零安装依赖——bash git sha256sum/shasum/openssl 均为操作系统自带。八、AI 工具集成三种主流 AI 编程工具均可使用工具加载方式Skill 目录OpenCode自动发现.opencode/skills/.opencode/skills/koi-weave-*/Claude CodeCLAUDE.md 引用skills/koi-weave-*/SKILL.md 是 AI 的操作指南AGENTS.md 是行为宪法scripts/ 是可执行工具——三层约束确保 AI 行为一致。九、从 v1.x 到 v2.0 的迁移维度v1.xv2.0约束方式AGENTS.md 文本声明SKILL.md 可执行 bash 脚本回流事务无保证三阶段 PREPARE → COMMIT → ACK去重机制AI 人工检查SHA256 内容指纹自动去重脚本语言Node.js需安装bash系统自带Skill 数量1 个合并 skill2 个独立 skillwiki dev技能结构单个 SKILL.mdSKILL.md scripts/ references/ assets/AGENTS.md 强度建议性宪法级含禁止操作条款跨平台仅 LinuxLinux 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 该遵守的规则从文本变成可执行工具。AGENTS.md 说你该做什么——宪法SKILL.md 说具体怎么做——操作指南scripts/ 说我帮你做——可执行工具AI 做它最擅长的分析 diff、提取知识、生成 YAML脚本做最需要确定性的文件操作、hash 计算、git push。这就是 v2.0 的全部秘密——不是约束变多了而是约束从软的变成了硬的。参考项目地址KoiWeave架构设计文档doc/KoiWeave 架构设计.md协议MIT