title: 团队协作规范 · README form: index updated: 2026-05-07 tags:

• 团队协作规范
• 入口 aliases:
• 协作规范
• 团队文档规范

团队协作规范

这是什么：OPC 聚合体（多个 One Person Company 松散协作）的文档协作基础设施规范。

核心理念：

• 每个 OPC 老板自己管私人内容；团队项目分 per-project 协作
• Obsidian 是团队标配的 AI 外挂记忆（不是编辑器偏好），所有 OPC 必装
• coding agent 必装团队 skills：Obsidian 格式理解 + team-collab 协议；Claude 走 plugin，Codex 走 Codex marketplace + ~/.codex/skills
• 懒人入口：npm install -g @embodot/collab@latest 后用 team-collab install-skills --agent all --force / register / init / sync / doctor 完成 agent skill 安装更新、已有仓库登记、新项目接入、同步、审计和飞书自动化安装
• 代码仓库可在 GitHub 或 GitLab；内部团队项目推荐优先创建在 GitLab embodot 组织，文档仓库统一在 GitLab
• opt-in：每人自己选加入哪些项目，权限 = collaborator
• 所有文档遵循 form/topic 双维度分类学，必需底座为 9 个内容入口 + archive/（见 07）
• AI handoff 自动同步 state 四件套：Claude Code 用 /handoff，Codex 用 $handoff；TODO 通过 @owner + 立即 push 实现分布式锁
• .claude/ 个人级不入代码仓库；新人入门走 team-collab init

目录

| # | 文档 | 目标读者 | 核心内容 | |---|------|---------|---------| | 00 | 架构总览 | 所有人 | OPC 聚合体 + 技术栈约定（Obsidian 必需）+ 三层架构 + 双平台 | | 01 | 新人入门 | 新加入的 OPC 同伴 | 装 Obsidian + agent + skills；按本地现状使用 register 或 init --join | | 03 | 日常工作流 | 所有协作者 | 开工 / 工作 / 结束 / 冲突处理 | | 04 | 安全与硬约束 | 所有协作者 | 禁止清单、wikilink 规则、gitleaks、OPC 信息边界 | | 05 | AI 工作协议模板 | 项目发起者 / AI | CLAUDE.md / AGENTS.md、slash command、bootstrap 脚本、各种模板 | | 06 | 运维手册 | 项目发起者 | GitLab Group、新项目 bootstrap、OPC onboard、故障处理 | | 07 | 文档组织规范 | 所有协作者 + AI | form/topic 双维度、必需底座、命名约定、frontmatter 规范、TODO 认领、好/坏实践 | | 08 | 飞书同步自动化 | 项目维护者 / 运维 | 飞书群 webhook 摘要、PR/MR 事件通知、selected docs 到飞书知识库 | | 09 | 飞书接入 Checklist | 项目维护者 / 运维 | 新项目接入飞书群通知和知识库同步的执行清单 | | 10 | 新项目初始化 Runbook | 项目 owner / agent | 从空 code/docs repo 到审计通过的新项目端到端初始化流程 |

最短阅读路径

你是新加入的 OPC 同伴：

1. 00 架构总览 — 10 分钟理解"为什么这么做"
2. 01 新人入门 — 20-30 分钟装工具 + 跑 team-collab init --join --dry-run 或 team-collab register
3. 03 日常工作流 — 5 分钟记住流程
4. 04 安全与硬约束 — 5 分钟知道雷区

总计约 40-50 分钟。

你是项目发起者 / 维护者：全部读，重点 05、06、08、09 和 10。

你是 AI agent：项目入口以代码仓库 AGENTS.md 为主，CLAUDE.md 只做兼容导入；协议由 team-collab:team-collab-protocol 瘦入口和按需 references 承载，05 是模板源头。

当前状态

| 条目 | 状态 | |------|------| | 规范本身 | 已迁入 GitLab embodot/team-collab-playbook，本地作为 Obsidian 项目目录维护 | | 分享给团队的方式 | GitLab invite-only；PROJECTS.md 只公开项目名录，不公开具体内容 | | 文档仓库策略 | GitLab embodot/<project>-docs；main 保护，禁止直推，高层共享文档通过 MR | | 代码仓库策略 | GitHub 或 GitLab 均可；内部团队项目推荐 GitLab 组织内创建/镜像；main 必须保护，代码更新走 PR/MR，保护/共享分支禁止强推，自有非保护工作分支可按归属规则强推 | | npm CLI | @embodot/collab，命令入口 team-collab / embodot-collab，提供 install-skills、docs-path、register、init、sync、doctor、初始化、审计和飞书安装；支持独立 docs repo 和已有 Obsidian vault 子目录两种本地布局 | | playbook 自动化 | GitLab CI 自动校验、npm pack、飞书 MR/main 通知、默认分支知识库同步 | | 试点项目 | egocap、persona，docs repo 已迁入 GitLab embodot/*-docs | | 已运行在此规范下的项目 | 2 个：egocap、persona |

规范如何演变

基于实际运行问题迭代。发现：

• 某步骤卡新人 → 改对应文档
• 某约束过严/过松 → 改 04 或 05
• 某故障场景漏了 → 补 06

在父 vault（现在）或未来的 team-collab-playbook repo 开 PR。

版本

• v0.47 (2026-05-12) — 新增团队协作规范 TODO，记录 HTML artifact harness 作为下一阶段可读性/交付物开发方向；Markdown 仍作为 canonical memory，HTML 作为模板化人类阅读界面。
• v0.46 (2026-05-12) — 许可调整为代码/脚本 Apache-2.0，文档/规范文本 CC BY-SA 4.0，并以 EMBODOT（杭州具点科技有限公司）作为署名主体。
• v0.45 (2026-05-12) — 将 playbook / npm CLI 许可切换为 PolyForm Noncommercial 1.0.0，明确禁止未授权商业使用。
• v0.44 (2026-05-11) — 关闭 playbook 仓库自身 GitLab 群通知：MR 通知也改为显式 opt-in，wiki sync 仅同步飞书文档；GitHub 通知策略不变。
• v0.43 (2026-05-11) — 明确 GitHub 可保留 PR/merge 群通知，但 GitLab docs 不向群组发通知；GitLab wiki sync 模板只同步飞书文档，不再调用 feishu-repo-event.sh。
• v0.42 (2026-05-11) — 修正 GitLab MR 群通知默认策略：除明确 opt-in 的 playbook 等项目外，gitlab-mr-trigger 默认注入静默变量，CI 模板也要求 TEAM_COLLAB_MR_NOTIFY_ENABLED=1 才发送 MR 群通知；Feishu wiki sync 不受影响。
• v0.41 (2026-05-10) — 放宽 AI git 强推策略：保护/共享/归属不清分支仍禁止强推，自有非保护工作分支允许 rebase 后强推；同步收紧 team-collab skill 触发条件，避免仅因全局配置存在而误触发。
• v0.40 (2026-05-08) — GitLab docs 自动化改进：personal devlog auto-merge 兼容默认分支 trigger pipeline 缺失 MR head pipeline 的场景；CI 模板改用 python:3.12-slim 避免自托管 runner 运行时 apk add 卡源；补充 shared runner minutes 约束下的自托管 runner / MR 提醒 / wiki sync 策略。
• v0.39 (2026-05-07) — auto-merge token 支持 protected file-type CI variable GITLAB_AUTOMERGE_TOKEN_FILE，避免长 OAuth token 不能 masked 时只能放普通 env var。
• v0.38 (2026-05-07) — 修复 team-collab gitlab-mr-trigger live 创建兼容性：先读取 project id，再创建 trigger/hook，兼容 GitLab trigger 响应不返回 project_id 的情况。
• v0.37 (2026-05-07) — auto-merge 增加显式 allowHandoffTraces 选项：允许 mapped author 的 MR 同时新增 append-only _handoffs/*.md，仍拒绝删除、重命名和改写历史。
• v0.36 (2026-05-07) — 增加 GitLab MR trigger 配置命令与个人开发记录 auto-merge fast path：只改本人 开发记录/<用户名>/... 的 MR 可由 trusted pipeline 自动 squash merge。
• v0.35 (2026-05-06) — 修复 Feishu PR/MR 通知信任边界：GitHub PR 改为 pull_request_target + base SHA trusted checkout；GitLab MR 改为项目 webhook 触发默认分支 pipeline，并从 TRIGGER_PAYLOAD 读取 MR 事件
• v0.34 (2026-05-06) — 新增 PR/MR 描述 Markdown hygiene SOP：禁止用 inline \n 拼接 summary/body，统一通过临时 Markdown 文件或 --body-file 写入，并在创建后检查网页渲染。
• v0.33 (2026-05-06) — 修复 install-adapters --dry-run 在目标目录尚未创建时的路径解析，dry-run 不再要求目标目录已存在。
• v0.32 (2026-05-06) — 新增 install-adapters，可从 GitHub team-collab-skills 安装 Cursor / VS Code / Cline / OpenCode / Continue / Gemini CLI thin adapters；doctor 增加 adapter 检查。
• v0.31 (2026-05-06) — 纠正 Codex marketplace 边界：Codex/Claude runtime artifacts 统一回到 GitHub team-collab-skills；playbook 只保留 SOP、CLI、installer、doctor 与自动化。
• v0.30 (2026-05-06) — 历史过渡版本：曾修复 npm 全局安装后的 Codex marketplace 注册，但仍把 marketplace 放在 playbook，已由 v0.31 纠正。
• v0.29 (2026-05-05) — 历史过渡版本：曾在 playbook 新增 Codex marketplace team-collab-playbook 与 team-collab plugin；该位置后续证明不合理，已迁回 team-collab-skills。
• v0.28 (2026-05-04) — audit 对 vault-subdir 保持文档模板检查，并改查父级 vault git 仓库是否接入飞书 wiki sync CI/scripts，避免尊重原路径时放弃 CI 规范
• v0.27 (2026-05-04) — audit 在 vault-subdir 模式下不再把子目录当独立 docs repo 检查，但仍需由父级 vault git 仓库承接飞书同步
• v0.26 (2026-05-03) — register/doctor/sync 支持已有 Obsidian vault 子目录作为合法 docs 布局，避免 agent 为了套用默认 Projects/<project>-docs 路径而复制或迁移用户已有文档
• v0.25 (2026-05-03) — audit 接受 obsidian-docs、obsidian-docs/、/obsidian-docs 三种代码仓库 ignore 写法，避免旧项目接入时产生误导性 warning
• v0.24 (2026-05-03) — 修复远程机器 Codex skill 安装 fallback clone 问题；register 对“大 Obsidian vault 子目录不是独立 docs repo”的错误提示更明确
• v0.23 (2026-05-03) — 重构 npm CLI 接入体验：新增 register 和结构化 ~/.team-collab/config.json，init --join 改为先 dry-run 识别本地布局，sync/doctor 支持项目登记和清晰错误提示
• v0.22 (2026-05-03) — 精简新人入门：移除 GitLab 权限管理细节和历史问题复盘式说明，只保留成员操作路径与 skills 更新命令
• v0.21 (2026-05-03) — team-collab install-skills 自动更新已安装的 Claude Code 插件；团队成员只需 npm 更新 + 一条 install-skills 命令刷新 agent skills
• v0.20 (2026-05-03) — 将团队协议 skill 内置名统一为 team-collab-protocol；Claude 入口为 team-collab:team-collab-protocol，Codex 入口为 ~/.codex/skills/team-collab-protocol
• v0.19 (2026-05-03) — 明确 GitLab 协作权限：普通成员默认 project-level invite，不默认加入 embodot 顶层 group；补充 Reporter/Developer/Maintainer 使用场景
• v0.18 (2026-05-03) — npm CLI 增加 team-collab install-skills 和 docs-path，支持 Codex 安装本地 skills；重写新人入门为 prompt-first 路径
• v0.17 (2026-05-03) — npm CLI 增加 team-collab init 和 team-collab doctor，把新人加入项目、leader 初始化项目和本地诊断收束成懒人入口
• v0.16 (2026-05-03) — 新增 @embodot/collab npm CLI、playbook GitLab CI 自动校验/npm pack/飞书通知/知识库同步；发版前将脚本入口统一为 team-collab
• v0.15 (2026-05-02) — 放宽代码仓库平台假设：GitHub/GitLab 均可，内部团队项目推荐 GitLab 组织内创建或镜像，代码更新按平台走 PR/MR
• v0.14 (2026-05-02) — 新增新项目初始化 runbook，串联 docs 初始化、code agent 入口、飞书自动化和审计验收
• v0.13 (2026-05-02) — 新增代码仓库 agent 入口初始化脚本，明确 AGENTS.md 由显式 bootstrap 生成初稿、agent 补全、人类审核
• v0.12 (2026-05-02) — 收窄代码仓库 AGENTS.md 口径：保留极薄项目公共入口，个人 vibe coding 规范留在全局薄指针
• v0.11 (2026-05-02) — 同步 team-collab skill 与多 agent 薄指针，明确 session start、audit、Feishu 和 handoff 触发路径
• v0.10 (2026-05-02) — 审计脚本覆盖飞书自动化和 agent 接入状态；飞书缺口默认 warning，适合渐进迁移
• v0.9 (2026-05-02) — 飞书接入 checklist、安装器脚本、知识库 Markdown 渲染器沉淀为可复制项目流程
• v0.8 (2026-05-02) — 飞书自动化扩展：GitHub PR / GitLab MR 事件卡片、selected docs 到飞书知识库同步、egocap 试点 CI 模板
• v0.7 (2026-05-01) — 飞书 webhook 摘要脚本可靠化：JSON 编码、可选签名、返回码校验、长度截断、dry-run、target 配置文件、默认消息卡片富文本；修正必需底座计数和 AGENTS.md/CLAUDE.md 入口口径
• v0.6 (2026-05-01) — 引入 GitHub/GitLab 治理分工、GitLab MR 分级、强制 开发记录/<用户名>/...、迁移审计/初始化脚本、飞书群摘要同步 v1、多工具适配计划
• v0.5 (2026-04-24) — 新增 07-文档组织规范：form/topic 双维度分类学、必需底座扩为 9 个内容入口 + archive/（加 OVERVIEW + TODO）、frontmatter 强制字段、TODO @owner 认领机制（git push 作分布式锁）；同步更新 team-collab-skills/SKILL.md 加文档硬约束和 TODO 认领流程；所有 template 加 form 字段
• v0.4 (2026-04-24) — 引入 team-collab-skills plugin；项目级主文档改为 AGENTS.md；全局薄指针按 agent 分；GitLab Group = embodot
• v0.3 (2026-04-24) — 定调 Obsidian 为团队必需项；合并 01/02 为统一入门
• v0.2 (2026-04-24) — OPC 聚合体 + GitHub/GitLab 双平台；slash command 归用户级
• v0.1 (2026-04-24) — 初版

不在本规范范围内

• 具体项目的架构、业务逻辑 → 看该项目自己的 docs repo
• 代码风格、语言规范、框架选型 → 看项目自己的 AGENTS.md / CLAUDE.md 或 CONTRIBUTING.md
• OPC 之间的商业合作条款 → 各自协商
• 跨 OPC 纠纷解决 → 超出本规范 scope

反馈与问题

• 文档错误、模糊：直接改（有 push 权限）或 @P0
• 某步骤卡住：飞书群反馈
• 协议层面系统性问题：开 issue 或在 PROJECTS.md 发起讨论