ai-collab · AI 协作开发框架插件
> 把「文件即通信」的多角色 AI 协作机制做成通用插件：任何软件项目，通过本插件一键初始化约定文件，任何 AI 客户端都能驱动 AI 多角色协作（O 主控 + 专业角色）完成项目。
- 机制来源：真实项目实践「AI 情报官」多角色协作机制 v1.0（源自 One News 多会话协作框架），已验证可支撑一个完整项目的 AI 协作开发。
- 核心洞察：AI 会失忆、会并行互相覆盖、会自作主张、会编造——文件机制解决这一切。AI 的"云端记忆"只带你是谁，文件机制才带项目进行到哪。
- 不绑定任何 AI 客户端：载体是文件，WorkBuddy / CodeBuddy / DeepSeek Harness / Claude 桌面端等均适用。
---
快速开始（3 步）
# 1. 初始化一个新项目（生成约定文件五件套 + docs 骨架）
python3 ai-collab/init.py my-app --desc "团队任务管理小程序" \
--tech "微信小程序 + 云开发" --constraint "UI 复用现有设计令牌" -y
# 2. （可选）git 初始化 + 同步守护
cd my-app && git init
nohup bash ../ai-collab/scripts/git_sync.sh . 60 >/dev/null 2>&1 &
# 3. 打开任意 AI 客户端，粘贴 SESSION_BOOT.md 的接棒提示词 → AI 完成上下文继承 → 开始派发任务> 已有项目想切换协作模式：在项目根目录跑 init.py 生成约定文件（目录非空时先 --dir 指定子目录或手动放置模板）， > 或直接把 templates/ 下的模板复制进项目根目录并替换 {{变量}}。
---
包结构
ai-collab/
├── README.md ← 本文件
├── plugin.json ← 插件元数据
├── SKILL.md ← 技能形态入口（支持自定义技能的工具可引用）
├── init.py ← 一键初始化脚手架
├── docs/
│ ├── MECHANISM.md ← 机制原理（为什么有效）
│ └── CUSTOMIZATION.md ← 定制指南（角色/阶段/验收/同步）
├── templates/ ← 通用模板（{{变量}} 占位）
│ ├── CONTEXT.md.tpl ← 项目速览（第一必读）
│ ├── ROLE_CARDS.md.tpl ← 角色卡（O + 6 专业角色）
│ ├── TASK_BOARD.md.tpl ← 任务看板（📋→🔄→✅/🚫 + 关口检查）
│ ├── RELAY.md.tpl ← 阶段流水线 + 里程碑 + 待拍板项
│ ├── COMMLOG.md.tpl ← 沟通交接记录（倒序）
│ ├── COLLABORATION.md.tpl ← 协作总规
│ ├── NAVIGATION.md.tpl ← 文档导航与交叉引用索引
│ └── SESSION_BOOT.md.tpl ← 新会话接棒提示词（复制即用）
└── scripts/
├── git_sync.sh ← Git 守护（60s 自动 commit+push）
└── notion_sync.py ← Notion 文档同步（可选，幂等）---
机制速览（详见 docs/MECHANISM.md）
| 要素 | 要点 |
|---|---|
| 文件即通信 | 约定文件是唯一事实来源；新会话读文件 100% 继承 |
| 角色体系 | O 主控持有全局，子 Agent 临时扮演 I/A/P/D/Q/K，身份由角色卡权威定义 |
| 约定文件 | CONTEXT / ROLE_CARDS / TASK_BOARD / RELAY / COMMLOG / COLLABORATION / NAVIGATION |
| Git 纪律 | 改前 pull --rebase，改后立即 commit，小步快推 |
| 任务流转 | 📋 待认领 → 🔄 进行中 → ✅ 完成 / 🚫 阻塞；交付交接包；3 分支意图识别 |
| 关口检查 | 阶段级全 ✅ 由 O 检查，通过才放行下一阶段 |
| owner 参与 | 只拍板 + 给凭证；AI 显式请求资源，绝不编造 |
| 会话继承 | 新会话按序读五件套 → 汇报继承摘要 → 等待派发 |
| 同步 | Git 60s 守护 + Notion 60s 幂等同步（可选） |
---
常见问题
Q: 我的 AI 客户端不支持自定义技能，能用吗？ 能。核心用法就是把 SESSION_BOOT.md 的接棒提示词粘贴进新会话——任何能读文件、能 git 的 AI 都能按机制运行。
Q: 云端会话和本地会话能并行吗？ 能。两边都遵守 Git 纪律（改前拉、改后推、认领前看状态），各自改不同文件时无冲突。
Q: 子 Agent 怎么派？ O 用 SESSION_BOOT.md 中的「子 Agent 身份注入」模板开头，子 Agent 启动读角色卡获得身份，交付写回约定文件。
Q: 需要一直开着同步守护吗？ 不必。守护只是让多端实时一致；单人单机时手动 commit+push 即可（机制不依赖守护）。
---
许可
MIT。机制与模板欢迎自由复用与改进；改进建议可回写本包（docs/CUSTOMIZATION.md §6）。
---
作为 DSH 插件安装 / 发布
本包已按官方规范打包为 DSH 插件（cordis bundle 形态）：package.json 声明 dsh.bundle + cordis.patch.yml，并注册 ai_collab_init 工具（AI 可直接调用它初始化协作项目）。
本地安装（有 dsh CLI 时）
dsh plugin --profile web add ./ai-collab # 本地目录
dsh plugin --profile web add dsh-ai-collab # npm 发布后
dsh plugin --profile web add github:you/dsh-ai-collab # GitHub 直装（需授权 prepare 脚本）无 dsh CLI 的桌面版：把本仓库克隆到 ~/.dsh/profiles/web/node_modules/dsh-ai-collab，并在 ~/.dsh/profiles/web/cordis.patch.yml 注册：
- insert:
- id: ai-collab
name: dsh-ai-collab重启 DSH 生效。
发布到市场（让其他人可用）
1. npm 发布（供 dsh plugin add dsh-ai-collab）：pnpm publish（本包为纯 JS，无构建步骤）。 2. GitHub 仓库 + 打 dsh-plugin topic → DSH 插件市场 每 2 小时自动收录，用户可在 Web GUI 设置页一键安装；SKILL.md 会被识别为 skill 形态安装到 ~/.dsh/skills/。 3. 参考：官方发布文档 docs/user/develop/basic/publish.zh.md。