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。