agent-team

把“多会话 = 多部门”的协作机制落到项目文件夹里。它不是角色扮演,而是岗位制度:每个会话有固定职责、写入边界、收件箱、交接班和审核闸。

先守住的边界

• 先有适合业务场景的项目地基,再搭协作层。默认目标目录 = 当前工作目录;若缺 docs/ 或缺清晰的目标/进度/交接文件,先判断项目类型:互联网产品 / Vibe Coding 才优先建议 vibe-project-foundation;其他业务场景优先使用已有专用业务地基 Skill 或现有文件结构。若没有合适地基,先问清目标业务、交付物、验收标准、过程资源、风险/复核方式,再帮用户创建一个最小业务地基,然后搭协作层。
• 三层必须齐全:管理层 / 执行层 / 审核层。最小盘是 lead,do,review;不要为了“多 Agent”硬拆部门。
• 创建 docs/collaboration/、新增/删除/替换部门、首次创建部门会话、改变跨会话路由或通知模式前,必须先让用户确认;已登记为自动/人工的短唤醒按 部门表.md 执行,不每次重复确认。
• 不直接写业务代码;本 skill 只做团队诊断、协作层搭建、会话登记和协作规则维护。
• 已有 docs/collaboration/ 时不要覆盖;先读现状,再判断是增量加部门、登记会话、更新规则还是重建。
• 启动前硬闸:不得从“帮我搭建团队/部门”直接默认成互联网产品开发。必须先确认项目最终交付物和会话创建模式,再推荐部门。

运行铁律

这些规则必须写进生成物,且后续派活都要遵守:

1. 三类节点闸:每个功能 / 环节只推进一个验收节点。部门完成节点后先回报统筹部;统筹部按三类判断:产品感知/重大边界节点必须请用户确认,流程性/技术性节点可自主推进,可自主推进但影响项目可见性的节点必须用简短节点卡汇报。
2. 收件箱是真相源:任务详情和回报写对应部门 收件箱.md;每个部门会话在上岗/接班时只做一次通知能力登记,后续按登记的“自动/人工”模式执行。通知只表达三类状态:有新任务 / 任务已完成 / 遇到阻断。
3. 完成回报四件套:产出路径、验证结果(含未验证项)、日志收据、错题自检。缺任一项,统筹部不能视为完成闭环。
4. 统筹不吃长上下文:统筹部先读自己的收件箱,只核日志收据存在;只有回报不足、收据错误、部门结论冲突或用户要求时,才读最小必要正文。
5. 审核层独立:审核部门亲自验证,不继承执行部门长上下文,不采信“已通过”转述;结论回统筹部,不自动触发返工或放行。
6. 体验先于测试:可运行功能先给用户体验;进入“需要用户体验 App”的节点时,统筹部默认直接帮用户打开 App,不先问“要不要打开”,然后给一张短体验卡。用户明确确认“体验 OK / 可以进测试”后,测试部才做专业质量关。
7. 设计必须可视化:凡涉及 UI、交互、视觉呈现、页面布局、设计稿、用户体验路径的节点,设计部不能只交文字说明、ASCII 线框、Markdown 表格或抽象结论;必须提供用户可直接判断的可视化预览。优先用 OpenDesign 等专用设计工具生成可编辑 artifact;工具不可用时必须说明原因,并用本地 HTML + PNG 截图、Figma、可打开图片等兜底。
8. 设计确认独立于功能确认:用户确认功能方向 OK 不等于视觉 / 交互通过。用户确认设计视觉或交互方向前,统筹部不得派开发部正式实现;最多只能推进功能可行性或技术评估。
9. 风险/成本按触发介入:安全部只在大阶段、上线/外发前或隐私、权限、密钥、授权、第三方平台、生产配置等风险出现时介入;财务部只在成本节点介入,只预警上报不卡死发布。
10. 放行由用户拍板:审核层三关通过后,统筹部只给放行建议;标记完成、对外发布、付费等由用户确认。
11. 路由口诀:澄清类(不改产物、不裁决、不推进状态)直连对方收件箱;要改 / 要裁决 / 要变状态 / 要放行 / 要增删部门,经统筹部。

统筹部三类节点决策

统筹部的判断原则:

用户负责产品体验、功能取舍、设计判断和重大风险拍板;统筹部负责技术流程、部门调度、常规质量关和无争议推进。自主推进必须保留简短汇报,遇到产品感知或重大边界变化必须停下确认。

A. 必须用户确认

凡是影响产品体验、用户感知、功能取舍、界面设计、交互流程、视觉呈现、MVP 边界、产品路线、上线发布、外发交付、成本明显增加、隐私/安全/云端/密钥/授权风险的节点,统筹部必须停下来让用户确认。

典型情况:

• 功能做完后,需要用户上手体验。
• UI / 交互 / 设计稿完成后,需要给用户看可视化预览。
• 设计部产出只包含文字说明、ASCII 线框、Markdown 表格或抽象结论时,不得视为完成设计节点。
• 用户只确认功能方向 OK、但未确认视觉 / 交互方向时,不得进入正式开发实现。
• 功能要新增、删除、后置、改变范围时,需要用户判断。
• 测试通过后是否正式收口、是否进入下一大阶段,需要用户确认。
• 涉及云端、上传、API Key、联网下载、费用、打包体积明显变化时,需要用户确认。

B. 统筹可以自主推进

凡是用户不适合判断、且不改变产品体验和重大边界的流程性 / 技术性节点,统筹部可以按专业判断推进,不必反复询问。

典型情况:

• 产品边界确认后,派设计部做最小交互草案。
• 设计草案完成后,派开发部做实现评估。
• 设计视觉 / 交互已由用户确认,且技术评估结论清楚、风险可控时,派开发部进入正式实现;UI 未确认前只能推进实现评估 / 技术可行性。
• 用户体验 OK 后,派测试部做质量关。
• 测试无 P0/P1/P2 阻断时,统筹部可以建议通过并进入收口确认。
• 日志、交接、错题集、进度记录、轻量验证、commit 存档等常规动作。

C. 可以自主推进但必须汇报

这类不需要用户拍板,但统筹部要用简短节点卡告诉用户“我已经推进到哪一步”。

节点卡示例:

• “开发评估完成,但 UI 未确认,我只派开发做技术可行性评估。”
• “设计视觉 / 交互已确认且开发评估风险可控,已派开发正式实现。”
• “你体验 OK 后,我已派测试部做质量关。”
• “测试无阻断,我准备收口存档。”
• “安全/财务本节点未触发,所以未介入。”

App 体验节点

进入“需要用户体验 App”的节点时,统筹部默认直接帮用户打开 App,不先问“要不要打开”。如果当前环境能启动 / 打开 App,就直接执行;如果启动失败,说明失败原因、已尝试命令和用户可手动打开的入口。

体验卡标准:

入口:
重点:
建议试法:
判断口径:

体验卡要求:

• 入口:告诉用户从哪里进,如“配音/克隆音 → IndexTTS2 情感配音 → 情感强度”。
• 重点:告诉用户这次主要看什么,只放 1-2 个重点。
• 建议试法:给 2-4 个具体操作,让用户不用自己想怎么测。
• 判断口径:告诉用户只需要回复“体验 OK”或指出哪里不顺。

示例:

入口:配音/克隆音 → IndexTTS2 情感配音 → 情感强度
重点:听三档差异是否明显、自然。
建议试法:
- 试 开心 + 克制 / 标准 / 鲜明。
- 试 活力口播 是否默认带入 开心 + 鲜明。
- 切到 自然 看是否固定标准并提示。
判断口径:你觉得好用就说“体验 OK”,不顺就告诉我具体点。

设计可视化确认节点

凡涉及 UI、交互、视觉呈现、页面布局、设计稿、用户体验路径的节点,设计部必须交付用户可以直接判断的可视化预览,不能只交文字说明、ASCII 线框、Markdown 表格或抽象结论。

设计部交付优先级:

1. 优先使用 OpenDesign 等专用设计工具生成可编辑设计产物或 artifact。
2. 如果当前会话未热加载 OpenDesign MCP、OpenDesign 没有 active project、权限不足、工具连接失败,设计部必须在回报里明确失败原因。
3. 工具不可用时,必须用本地 HTML + PNG 截图、Figma、可打开图片预览等方式兜底,保证用户看到“做出来大概是什么样”。
4. 如果用户不想安装、启动、授权、注册或修复 OpenDesign,或不愿意为当前会话重载 / 新开会话,设计部不得卡住,应按用户偏好直接选择本地 HTML + PNG、Figma 或可打开图片预览。

设计部完成回报四件套中的“产出路径”必须同时包含:

• 设计说明文档路径。
• 可视化预览路径,如 OpenDesign artifact 链接 / 本地 HTML / PNG 截图 / Figma 链接 / 可打开图片。
• 若使用兜底方案,必须写清 OpenDesign 当前状态和后续恢复条件。

OpenDesign 接入规则:

• 先确认本机 OpenDesign App 是否运行,再确认 daemon 健康状态。
• 不要假设默认端口一定是 7456;应从 OpenDesign 日志或本机监听端口确认实际 daemon URL。
• 确认后将 open-design MCP 注册到 Codex;当前会话可能无法热加载新 MCP,必要时提示用户重载 / 新开会话。
• 若 OpenDesign artifact 写入提示没有 active project,要求用户在 OpenDesign 内创建或点进项目,或直接使用本地 HTML / PNG 兜底交付,不能卡住节点。
• 若发现未安装 / 未运行 OpenDesign、权限不足、连接失败或 MCP 未热加载,设计部必须主动询问用户是否需要帮忙安装 / 启动 / 授权 / 注册 MCP / 重载或新开会话;用户不处理时立即走兜底可视化方案。
• 最小排障顺序:查 App 是否运行 → 查监听端口或日志里的 daemon URL → 查 MCP 是否已注册 / 当前会话是否已热加载 → 查 active project → 查权限 / 连接错误;任一步失败都同时给兜底预览方案。
• OpenDesign 只是增强设计表达和可视化确认能力,不代表自动扩大为完整 UI 重设计、品牌升级或开发实现。

统筹部收到设计回报后:

• 先展示可视化预览,再给用户一张简短节点卡。
• 节点卡建议结构:成果 / 判断点 / 建议 / 风险 / 下一步。
• 不要把长技术说明或设计正文直接丢给用户判断。
• 用户确认设计视觉或交互方向前,不得派开发部进入正式实现;如果用户只反馈功能方向 OK 但 UI 未确认,只能推进功能可行性或技术评估。

自主推进停止条件

统筹自主推进不等于无限连续推进。可以连续推进流程性节点,但遇到以下情况必须停下问用户:

• 结论有明显不确定。
• 部门之间判断冲突。
• 需要牺牲体验、范围、成本、速度中的任一项。
• 要新增依赖、云端、联网、模型、成本。
• 要改变用户之前确认过的产品方向。
• 要进入可运行功能体验、UI 视觉确认、发布/打包/外发、大阶段收口。

诊断流程

如果用户已经说清项目类型、交付物和会话创建模式,直接诊断;不要重复问。信息不足时一次只问一个关键问题。

第一问:

这个项目最终要交付的东西是什么:可运行软件、内容/课程、运营结果、调研方案、自动化流程、线下交付,还是其他?

第二问:

这次会话部门怎么创建:由当前 Codex 这类有会话管理工具的 Agent 自动创建,还是你会先手动创建好各部门会话窗口,我只负责生成部门文件和上岗引导?

第一问没有答清前,不得推荐 product/design/dev/test 软件常见盘。第二问没有答清前,不得声称已经创建部门会话。若项目缺少地基文件,还要先判断是否已有适用的场景地基 Skill;没有时再创建通用最小业务地基,不要把所有项目都导向 vibe-project-foundation。

诊断时固定三层,只判断执行层拆几个、审核层开几关:

触发维度	命中则影响	部门
软件 / 互联网产品 / Vibe Coding / 有可运行产物	启用软件盘	product/design/dev/test
UI/交互/视觉重	强化设计	design
资料收集、用户/市场/竞品/事实核验重	加研究	research
方案、流程、排期、资源配置重	加策划	planning
数据采集/清洗/导入导出/准确性重	加数据	data
批处理、定时、跨平台自动执行	加自动化	auto
文案/图片/视频/报告持续生产	加内容	content
增长、转化、留存、商业化运营	加增长运营	growth
账号、登录、隐私、合规、第三方平台、密钥、生产配置	开风险关	security
预算、成本敏感、付费项	开成本关	finance
复杂功能、需要 bug/异常覆盖	独立质量关	test 或 review
都不强烈	通用最小盘	lead,do,review

非软件项目不要硬套产品/设计/开发/测试;先按交付物、验收标准、过程资源、风险和复核方式判断。无法归类时用 lead,do,review,再按风险补 research/planning/content/data/auto/security/finance。

地基选择

协作层依赖“能让部门读懂目标和边界”的项目地基,但地基不等于固定的软件目录。

处理顺序:

1. 先看项目里是否已有可用地基:如 docs/、业务方案、项目说明、交付清单、进度/交接文件、行业专用目录。已有时按现有地基规划部门职责和可写范围,不要强行改成软件结构。
2. 若是互联网产品、软件、Vibe Coding 或明确有 app/ design/ docs/spec.md 这类产物,才优先建议或使用 vibe-project-foundation。
3. 若是课程、内容、运营、咨询、线下交付、调研、内部流程等非软件项目,先找是否有对应专用业务地基 Skill 或现有模板;有就使用它。
4. 若没有专用地基,不要停在“请先装某个软件地基”。先问清目标业务、最终交付物、验收标准、过程资源、风险/复核方式,然后创建最小业务地基。

最小业务地基只包含能支撑协作的通用文件:

• docs/overview.md:项目目标、交付物、服务对象/使用对象、边界。
• docs/progress.md:当前阶段、已完成、进行中、下一步。
• docs/agent-guide.md:本项目协作规则、文件分工、注意事项。
• 必要时按业务创建 deliverables/、materials/、research/、operations/、scratch/ 等目录;不要创建无关的软件目录。

推荐团队时给出:

• 三层各有哪些部门,以及命中依据。
• 每个部门的职责、禁止事项、输入、输出、可写范围、禁止写入范围。
• 跨部门路由:澄清直连还是经统筹。
• 哪些节点必须用户确认。
• 会话创建模式:自动创建会话 或 手动创建会话窗口,以及对应执行步骤。

创建前停下确认:

我建议按以上团队配置创建 docs/collaboration/,会话模式为【自动创建 / 手动创建】。你确认吗?

创建协作层

确认后运行脚本。若没有专用地基且用户确认由本 Skill 补最小业务地基,加 --create-minimal-foundation --allow-without-foundation。默认通用最小盘:

python3 <skill目录>/scripts/scaffold_team.py "<目标项目目录>" \
  --profile "<团队诊断摘要>" \
  --session-mode "manual"

按诊断展开时显式传角色:

python3 <skill目录>/scripts/scaffold_team.py "<目标项目目录>" \
  --profile "软件 + 数据强 + 涉隐私/平台 + 有预算" \
  --roles "lead,product,design,dev,data,test,security,finance" \
  --session-mode "auto"

可选角色:

• 管理层:lead
• 执行层:do/research/planning/product/design/dev/data/auto/content/growth
• 审核层:review/test/security/finance

脚本会创建 docs/collaboration/README.md、部门表.md、会话启动清单.md、错题集.md、任务交接模板.md 和 部门/<部门名>/ 下的 岗位说明.md、上岗引导.md、交接班文档.md、收件箱.md、日志/<ISO周>.md;审核层另有 把关报告/。脚本拒绝覆盖已有协作层,拒绝重复角色,拒绝缺少管理层/执行层/审核层的全新团队;未传 --session-mode auto/manual 时会中止,防止绕过会话模式确认。

会话创建模式

自动创建会话(Codex / 有会话管理工具)

用户确认采用自动模式后:

1. 先运行脚本创建 docs/collaboration/。
2. 用 tool_search 搜索 create_thread、send_message_to_thread、set_thread_title、set_thread_pinned、list_threads 等会话工具。
3. 工具可用时,为每个部门创建一个会话;标题建议用数字前缀保持顺序,如 01 统筹部、02 产品部、03 开发部。
4. 把每个部门的 上岗引导.md 作为初始化消息发给对应会话,要求该会话先接班,只汇报职责 / 阶段 / 进行中 / 收件箱 / 待确认问题,不要立刻做业务任务。
5. 把返回的会话 ID 写入 docs/collaboration/部门表.md,并把通知模式登记为 自动。若发送工具失败,本部门通知模式改为 人工,并向用户说明没有完成自动建会话。
6. 最后向用户汇报:已创建哪些会话、哪些会话 ID 已登记、哪些需要用户手动处理。

如果工具不可用或调用失败,不得说“已创建会话”;改为手动模式收尾。

手动创建会话窗口(其他 Agent / 无会话管理工具)

用户确认采用手动模式后:

1. 只运行脚本创建 docs/collaboration/ 和各部门文件。
2. 不调用会话工具,不声称创建了会话。
3. 输出手动上岗清单:每个部门对应的 上岗引导.md 路径、建议窗口名、需要用户粘贴给该会话的第一句话。
4. docs/collaboration/部门表.md 的会话 ID 保持 待登记,通知模式保持 待登记 或按用户说明改为 人工。
5. 用户手动创建好窗口后,把各部门 上岗引导.md 发给对应会话;部门会话按引导读取自己的岗位说明、交接班、错题集、收件箱,之后所有交接都写对应部门文件夹的 收件箱.md。

创建后检查:

1. docs/collaboration/ 结构完整,三层至少各一个部门。
2. docs/agent-guide.md 已追加多会话协作说明。
3. docs/collaboration/会话启动清单.md 已写明自动/手动模式和每个部门的上岗入口。
4. 自动模式下,部门表.md 已登记实际会话 ID 和通知模式;手动模式下,已明确提示用户会话尚未创建。
5. docs/progress.md 记录协作层创建、团队配置摘要、下一步。
6. git status --short;若只有本次协作层相关变更,可单独提交:

git add docs/agent-guide.md docs/progress.md docs/collaboration
git commit -m "chore: 搭建多会话协作层"

若仓库已有其他未提交变更,不要混提交,向用户说明。

维护模式

后续可能要新增/合并/删除部门、替换会话、登记会话 ID、调整边界、派活或独立把关。处理原则:

1. 先读 docs/collaboration/部门表.md,确认现有三层和部门。
2. 判断是否破坏“三层至少各一个”或职责边界。
3. 涉及新增/删除/替换部门、跨会话消息、放行、返工、状态升级,先让用户确认。
4. 加部门用 scaffold_team.py <项目> --add-roles "<ids>";脚本只补建缺失部门并追加部门表,仍需人工同步受影响流转规则。
5. 减/合并部门时,先把在办事项和历史交代进日志,再更新部门表和相关岗位说明;不要直接删历史。
6. 通知能力登记只在上岗/接班时做一次:
   • 读 部门表.md 的本部门“通知模式”。若已登记为 自动 或 人工,本会话后续都按该模式执行,不要每次任务完成都重新探测工具。
   • 若通知模式是 待登记,有 tool_search 时搜索 send_message_to_thread 等发送工具;没有 tool_search 或搜不到发送工具,登记为 人工。
   • 自动:后续通知默认直接调用会话发送工具发短唤醒,不再预先做能力检查。
   • 人工:后续通知默认直接给用户可复制的短唤醒,请用户手动提醒目标部门。
   • 若自动模式实际调用失败,本次回退为人工提醒,并请用户通知统筹部更新 部门表.md。
   • 若用户发现 Agent 工具能力变化,让用户告知统筹部会话,由统筹部更新 部门表.md 的通知模式。

Skill 开发与验证

修改本 skill 或 scripts/scaffold_team.py 后:

python3 <skill目录>/scripts/verify_agent_team.py

只有验证通过,才能声称生成物保留了启动前硬闸、会话创建模式分流、三类节点闸、短唤醒、收件箱真相源、日志收据、错题自检、统筹不读部门正文、体验节点默认打开 App、体验卡、体验先于测试、设计可视化确认、OpenDesign 兜底、功能 OK 不等于 UI 通过、统筹自主推进停止条件和确认状态枚举。如果新增规则改变部门行为,同步更新 tests/pressure_scenarios.md 和验证脚本。