企业官网建设流程全解析

KoiWeave v2.0 — 从"AI 自觉"到"AI 受控"

一、背景：AI 写代码很快，但 AI 不知道你之前为什么那么写

这是当前 AI-assisted 开发的核心矛盾——代码生成效率上去了，但知识复用率没跟上。

我们面临三个具体问题：

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

二、架构总览：三环进化 + 双 Skill 体系

2.1 整体布局

KoiWeave（本仓库） │ ┌───────────┴───────────┐ │ │ koi-llm-wiki/ skills/ （知识中枢仓库） （AI Skill 定义） │ │ │ ┌───────┴───────┐ │ │ │ │ koi-weave-wiki koi-weave-dev │ （中枢运维） （开发辅助） │ │ │ └───────────────┴───────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ service-auth service-order service-payment

2.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 可以自由决定是否遵守。实践中我们发现：

1. AI 会"忘记"执行某些步骤——问就说做了，实际上没做
2. 同一操作不同 AI 工具行为不同——OpenCode、Claude Code、Cursor 各自解读
3. 回流没有事务保证——"上传成功删除，失败重试"这个需求无法实现
4. 去重靠 AI 自觉——"检查 SYNC_LOG 最近 5 条"这种指令，AI 不一定执行
5. 不可复现——人无法复现 AI 的操作流程

核心矛盾：约束写在文本里，执行靠 AI 自觉——这本身就是矛盾的。

四、v2.0 升级：从"AI 自觉"到"AI 受控"

4.1 核心变化

v1.x: AGENTS.md 文本声明 → AI 自觉遵守 ↓ v2.0: SKILL.md + scripts/ 可执行脚本 → AI 按步骤执行 bash 命令 → 输出 JSON

AI 不再直接操作文件，而是通过 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 完成后创建）

边界情况：

六、标准化回流格式

v1.x 的回流内容是 AI 自由撰写的 Markdown 文本。v2.0 定义为标准 YAML Schema：

schema_version:"1.0"service: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、Windows（Git Bash）：

# 跨平台 SHA256 检测_sha256(){ifcommand-vsha256sum>/dev/null2>&1;thenecho-n"$1"|sha256sum|cut-d' '-f1elifcommand-vshasum>/dev/null2>&1;thenecho-n"$1"|shasum-a256|cut-d' '-f1elifcommand-vopenssl>/dev/null2>&1;thenecho-n"$1"|openssl dgst-sha256|cut-d' '-f2fi}

零安装依赖——bash + git + sha256sum/shasum/openssl 均为操作系统自带。

八、AI 工具集成

三种主流 AI 编程工具均可使用：

SKILL.md 是 AI 的操作指南，AGENTS.md 是行为宪法，scripts/ 是可执行工具——三层约束确保 AI 行为一致。

九、从 v1.x 到 v2.0 的迁移

十、完整开发流程演示

===== 第 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