Work Together

把你的 AI 聊天当成「老板」，把其他 AI 工具当成「员工」：老板（当前聊天）负责拆解任务、划定边界、验收成果；员工（其他工具的真实桌面会话）负责具体干活。Codex、ZCode、Qoder、WorkBuddy 六款客户端，任何一款的聊天都能当老板；哪个员工没额度或不可用，就按顺序自动换下一个。配置里「老板」写作 coordinator，「员工」写作 engine——后文沿用这两个术语。

你只需告诉老板「想做什么」，老板会先看项目，补齐做事清单，再带员工执行。可以直接说：

> 用 work-together，帮我给现有网站增加帮助页并更新使用说明。你当老板，先检查项目，安排能并行的员工干活，再亲自检查成果。先在本地完成，不接 Gitee；不发布、不推送。

像开一家小店一样理解流程

上面的网站任务只是讲解例子，不是已执行的验证记录。能独立完成、文件不重叠的活可以一起做；必须用到前一份成果的活要排在后面。员工不能给自己盖「验收通过」章；检查不合格就按问题单修好，再检查。每个员工只动分给自己的文件，越界会被检测拦下；工位约定不等于操作系统沙箱。

第一次用：你说目标，老板准备清单

用户不必先手写 JSON、学会命令或读完术语。老板先检查本地 Git、Node.js 和可用桌面工具，再根据现有文件整理需求单、分工表与检查办法；缺少会影响结果的业务信息时，用普通话问清。对用户先讲「谁做什么、什么时候算完成」，按需再解释配置字段。

默认先做一次本地小任务：一名员工能完成就不强行多开；可独立拆分时再安排多名员工。老板负责准备配置和运行命令，用户只需完成实际缺少的安装、登录或业务选择。模型选择像「按名单找有空且符合预算的员工」：默认按候选顺序检查当前免费资格，不用用户先理解完整费率表；没有合格候选就说明原因，不自动改用收费模型。

看进度时先用「等开工、正在做、等老板检查、检查通过、已汇总、需要你处理」描述；不确定员工是否还在工作，就说「正在查原会话」，不能再找一个人重复干同一件活。team 中 merged 只表示汇总到本地，不能描述为已发布或 Gitee PR 已合并。老板中断后的接管目前仅适用于旧任务包流程，团队模式恢复见 团队说明。

多员工模式：老板可以把一个大目标自动拆成小任务，给同一名员工排几件活，也可以让同一工具里的多名员工（独立会话）、不同工具的员工一起干活。员工按能力和空闲情况领取任务，只改自己负责的文件，可以通过本地消息箱分享发现、提出求助。老板随时查看每名员工在做什么、排着什么活、卡在哪里；验收后再把各自成果汇总。

新手直接本地用，不需要 Gitee。 没有 Gitee 账号、暂时不想配置线上协作，都可以先让老板在本机带员工干活：拆任务、分配、共享发现、验收和汇总都在本地完成，也不需要 Mattermost 等聊天平台。多员工本地使用看 团队模式说明，其中会说明本地 Git 和桌面工具的准备要求。

Gitee 是可选的线上任务清单和交付窗口。 老板需要把进度放到网上时再添加：每件活自动对应一张 Issue 任务卡，整轮通过验收的成果汇总成一个 PR，交给老板或仓库维护者评审。普通本地运行不会发布到 Gitee；需要时按 Gitee 接入说明 单独开启同步，不会自动合并 PR 或改动目标分支。

不需要先读完全部文档：传统任务包流程可照 端到端样例 执行；额度不足、桌面不可用或任务卡住时，按症状查 FAQ。Windows 五款执行器有传统流程现场验证，多员工本地模式另有 ZCode 验证；macOS 仍为实验性，首次使用先读 macOS 清单。

适合跨模块改动、独立文稿或其他能按文件拆分的项目任务：执行过程在真实桌面可见，前置包验收后才放行依赖，审批或提问集中给出介入卡。单文件小改动、必须同时写同一文件的工作不必强行并行。

技术配置中，多员工流程使用 team 模式：先读团队说明，老板确认目标、scope 和验收条件，桌面规划器返回经校验的任务图，再调度员工执行；独立 verify 后 collect 到本地集成分支。只有用户要求 Gitee 自动化时才使用 gitee sync/watch，仅发布已验收的专用团队分支。旧 workflow 任务包模式仍可使用，同一目录不混跑两种模式。

在任何一款客户端（Codex / ZCode / Qoder / WorkBuddy）的聊天中都可这样开始（项目目录使用当前工作目录，你就是老板）：

> 使用 work-together 完成【你的目标】。你当老板，先看现有项目，写清要交什么、哪些文件不能动、怎样检查；给员工分好活，能同时做的就同时做，需要前面成果的就排队。员工交货后由你检查，最后告诉我成果在哪里、检查了什么、还有什么问题。先本地完成，不接 Gitee。

该示例只授权项目任务协作，发布、推送等外部操作仍取决于用户的具体任务要求。

选择主持方与执行器

当前聊天负责管理与独立验收；默认 engine=auto。用户已授权在缺额度或不可用时按以下顺序切换，无需为同一策略重复询问。

workbuddy 保留为 workbuddy-global 别名。显式 engine 从该项开始按表向后选择，fallback=false 才锁定单项；预检逐项记录不可用原因。每任务每候选最多尝试一次，耗尽后明确报告。Auto、空费率、未标价及付费模型均不能充当免费候选；不因所有候选失败而启用收费模型。限时免费以本次桌面元数据为准，不承诺永久免费。

执行中的任务只有确认原会话已停止，才可带已有产物、原会话 ID 和失败原因转交下一项。创建、派发或连接结果不明确时记 unknown，查询原会话，禁止自动重派。模型错误、超时和没回应本身不是停止证明。

计划顶层 engine 为默认值，任务可覆写 engine。主持方写入 coordinator（缺省 codex）：Codex 与五款桌面客户端（ZCode、Qoder 双区、WorkBuddy 双区）的聊天都可以担任主持方，在哪个聊天里运行本 skill，谁就是主持方；主持方不能把 Exec 指派给同族执行器（如 ZCode 主持时任务自动落到 Qoder/WorkBuddy）。主持方自己的桌面无需调试端口；启动脚本会自动跳过主持方同族桌面，防止重启杀掉协调会话。简单任务用单包；只有文件归属和依赖允许时才并行。旧 executor=both 表示 ZCode 与 WorkBuddy 国际版组合，不能写为 plan.engine=both。

环境与启动

需要 Node.js >=22.13，以及已安装并登录的候选桌面；team 使用内置 SQLite。桥使用版本相关的本机私有接口，不改桌面数据库或 app.asar，不复制模型密钥。应用可启动、模型可选、任务可执行是不同检查，预检成功不等于整套工作流通过。v1.4.0 已记录 Windows 五执行器现场验证，新版本以实际 doctor/smoke 为准；team 模式的验证范围另见团队说明。

• Windows：scripts/start-desktops.ps1 -Engine auto 按五级列表启动/复用；也可只选任一 engine。脚本自动读取当前目录 plan.json 的 coordinator（或用 -Coordinator 指定），跳过主持方同族桌面（主持聊天就运行在其中，重启会杀掉会话）；显式 -Engine <单项> 视为覆盖。both 兼容旧双客户端，all 等同启动列表 auto。多候选启动会继续检查其余项，最后汇总失败；它只准备桌面，不派发模型请求。路径参数见 运行说明。
• 健康实例直接复用；缺调试端口的所选应用可能退出后重启。当前项目活跃任务及持锁主持方受保护；其他项目或人工会话需先检查，不能为预检中断活跃任务。仅用户明确允许中断后用 -ForceRestart，随后查询原会话恢复。
• macOS：实验性、未真机验证。先读 macOS 清单，Bash 启动器目前仅支持旧 ZCode / WorkBuddy 国际版入口；五级 Windows 启动参数不适用于该脚本。

ZCode 默认权限为 yolo，Qoder 与 WorkBuddy 为 bypassPermissions。用户指定的权限设置应在执行器能力内尊重，完全访问不扩大业务授权。所有任务先检查当前模型报价；指定模型不可用或不满足免费策略时进入下一候选，fallback=false 则明确失败。

执行与验收

1. 先读现场、AGENTS.md、现有修改。将目标、输入、禁止修改边界、交付物、逐条验收条件和回退入口写入 SPEC.md。不覆盖用户已有 Spec。
2. 写 PLAN.md 及 plan.json：每包有唯一 id、prompt、files、acceptance、dependsOn；默认 concurrency=2。目录归属覆盖子目录，交叠包串行，依赖包必须等前置包经主持方验收、登记 verified 后启动。共享构建输出、依赖安装、Git index、锁文件分配唯一写入责任。混排不设通用顶层 model，避免跨工具误用。
3. 读 运行说明，使用本 skill 的脚本连接真实桌面会话。先 doctor 检查候选，或 doctor <执行器> 单项检查；桌面登录不代表 API 或 CLI 已登录。派发后必须打开本次真实项目和目标 session，检查侧栏选中正确任务、正文出现本次任务包标记，并记录 <包ID>.visibility.json。仅有 sessionId、后台日志或旧测试会话截图不算桌面执行过程可见。脚本会自动定位，失败用 open <包ID> 修复原会话，禁止重新派发。接口不可用时按上述候选策略切换并记录原因，不伪造会话、不直接写桌面数据库。已派发但状态未知时禁止切换。首次本地调试适配需说明它是版本相关的私有桌面桥。
4. 在能承载后台进程的宿主中运行 workflow.mjs run <plan.json>，工作目录为项目根；Windows 隐藏窗口，stdout/stderr 重定向到 .work-together 或用户指定本地日志路径。headless 环境若会回收子进程，按运行说明交由可承载后台的调用方启动；不要反复绕过进程策略。主聊天仅报告状态变化、交付结果和人工决策。
5. 使用当前主持环境真实提供的计划工具（若有）同步任务；没有则维护 PLAN.md 的勾选项。定期读紧凑 status/watch，主会话在本轮保持跟进，独立工作完成后再收尾。skill 本身不能在主持方回合结束后主动唤醒聊天：只有配置了可用的宿主通知机制才能承诺跨回合自动汇报。
6. 状态包括 queued、running、needs_user、exec_done、verified、failed、unknown、blocked、cancelled。needs_user 时自动定位该会话并给出简短回顾卡：完成了什么、卡在哪里、具体需回答什么、项目绝对路径、会话标题/ID、下一步。普通轮询不抢用户当前选中的会话。通过执行器原生待办维护本包进度，不把主持方的总计划假称为外部工具原生全局计划。后台其他无依赖包可继续。
7. 业务问题或超出 Spec 的新操作仍需用户判断。审批模式下，已有明确授权且与 Spec 完全相符的操作可批准一次。失联/超时先查原会话，unknown 不重派；取消后确认停止再释放文件归属。恢复复用持久会话 ID，同项目只允许一个调度器；恢复前确认原 runner 已退出。主持方工具失联时，可由其他工具 workflow.mjs takeover <执行器> 接管：写入 coordinatorHistory，接管后的派发排除现任主持方同族执行器；由现任主持方同族执行且未验收的包默认拒绝自验，需 verify <包ID> <证据> --self-review 显式登记（记录 reviewer/selfReviewed），或交由其他工具/原主持方复核；run --resume 始终按初始主持方校验。
8. 网页或小程序需要截图时，把页面/路线、登录前提、截图尺寸、输出文件名与回填位置写入任务包，由所选执行器使用其实际可用的浏览器或桌面工具截图。记录来源与截图时间，并检查图片文件真实可打开、内容对应文章、最终文稿引用全部存在。截图失败列为缺口，不用生成图冒充产品界面。
9. Exec 结束仅记 exec_done。你逐项读取真实产物、检查 diff、独立运行适合改动的测试，必要时看截图/控制台/应用后台状态，证据映射到 Spec 条件。失败退回原会话修复。将独立验收记录交给 verify 命令；不能仅凭执行者“通过”结案。所有包 verified 后交付，更新 PLAN.md 并给出简洁总报告。

文件归属是协作约定，非操作系统隔离：真正相互冲突的构建/依赖/可变外部状态必须串行，或经用户接受后使用 worktree。不要承诺“同目录完全互不干扰”。发布、推送、发消息按当前用户授权范围处理。日志、截图、桌面会话、账号配置和密钥默认只留本地。

配套材料（按需读取，不用一次读完）

• 遇到问题：按症状查 references/faq.md——桌面不可见、verify 退出码 2、连接断开/unknown、headless 主持启动失败、模型费率判断等高频问题与反模式。
• 第一次使用：通读 references/walkthrough.md 端到端样例（含一次真实的"模型请求 error → 退回原会话修复"支线）。
• macOS 用户：适配为实验性、未现场验证，先读 references/macos.md 的边界与真机验证清单。
• 写计划：拷贝 examples/plan.example.json 与 examples/SPEC.template.md。
• 命令速查与环境边界：references/operations.md 顶部速查表；包内导览见 README.md。