@jennie-shawn/starwork 0.1.0-alpha.21 → 0.1.0-alpha.22

package/skills/starworkMultiagent-spec.md

@@ -2,180 +2,226 @@
 
 ## 状态
 
-- 版本：v0.8 accepted implementation note
+- 版本：v0.9 implementation note
 - 所属模块：StarWork Skills
 - Skill 名称：`starworkMultiagent`
 - 相关命令：`starwork multiagent`
 - 相关 Core 能力：Agent Lanes
-- 实现状态：已按 Codex 标准线程工具边界收敛
-- 目标：帮助 Agent 把用户关于常用智能体、会话职责、多 Agent 分工、跨 lane 消息和共享输出的自然语言请求，转换成安全的 StarWork 协作流程
+- 实现状态：友好引导体验改版中
+- 目标：把用户关于多 AI 协作的自然语言请求，转成“先解释、再检查、再设计、先预览、确认后执行”的安全协作流程
 
 ## 一句话定义
 
-`starworkMultiagent` 是 StarWork 多 Agent 协作设计与 Codex App 线程控制 skill。
+`starworkMultiagent` 是 StarWork 的多 AI 协作顾问。
 
-它不是 `starwork multiagent` 命令本身。Skill 在 Codex App 正常路径中直接调用标准线程工具；CLI 只记录 StarWork 项目事实源。
+它面向用户时讲“AI 岗位、当前 AI 会话、可以整理或修改的范围、交接消息”；面向项目事实源时仍维护 Agent Lanes；面向 Codex App 时仍直接调用标准线程工具。
+
+## v0.9 用户体验原则
+
+### 用户看到 AI 岗位
+
+默认用户语言：
+
+| 内部词 | 用户可见说法 |
+|---|---|
+| lane | AI 岗位 / 职责位 |
+| session / thread | AI 会话 / 当前会话 |
+| write_scope | 可以整理或修改的范围 |
+| binding | 把这个会话登记到某个岗位 |
+| shared output | 共享给其他 AI 的成果 |
+| handoff | 交接消息 |
+| CLI | StarWork 命令工具 |
+| host / adapter | 你正在使用的 AI 工具 |
+| dry-run | 先预览，不真正写入 |
+
+内部词只在用户追问机制、开发验收、调试记录或协议消息正文中出现。
+
+### 第一屏先解释流程
+
+用户说“创建 AI 团队 / 开启 MultiAgent / 创建多个 Agent”时，先输出：
 
 ```text
-用户说“让开发 lane 开始修复 issue”
-  ↓
-starworkMultiagent 读取 StarWork binding
-  ↓
-Skill 组装 STARWORK:MULTIAGENT_MESSAGE
-  ↓
-send_message_to_thread 投递到目标 Codex thread
-  ↓
-multiagent request record 记录真实投递状态
+可以。我会先帮你把这个项目拆成几个清楚的 AI 岗位。
+
+每个岗位会有三件事：
+1. 它负责什么；
+2. 它可以整理或修改哪些内容；
+3. 它完成后要怎么交接。
+
+我会按这个顺序来：
+1. 先检查当前项目是否准备好；
+2. 再给你设计岗位方案；
+3. 先预览要写入的协作记录；
+4. 等你确认后再正式创建。
+
+检查和预览阶段不会改你的项目文件。
 ```
 
-## 事实源
+第一屏不得出现 `lane`、`write_scope`、`binding`、`thread`、`CLI`、`doctor` 或具体 multiagent 子命令。
+
+### 只问自然问题
 
-Agent Lanes 协议事实源是：
+创建团队时，先问：
 
 ```text
-product/core/agent-lanes-spec.md
-product/planning/features/multiagent/specs/v0.8-skill-cli-minimal-boundary.md
+这个项目主要想完成什么？
+你希望哪些事情交给不同 AI 分开做？
+有没有哪些文件或内容不希望 AI 主动修改？
 ```
 
-本 SPEC 只规定 skill 如何判断、追问、调用标准线程工具和记录 CLI 状态，避免重复维护协议。
+不要向用户索要 lane id、write scope 或 session id。Skill 根据回答生成内部字段。
 
-## 设计边界
+### 先预览，再写入
 
-`starworkMultiagent` 应该做：
+创建或调整岗位前，用表格预览：
 
-- 判断用户是在初始化协作层、登记当前会话、增加 lane、绑定会话、释放会话、查看状态、发送跨 lane 指令，还是登记共享输出。
-- 采访 lane ID、职责、写入范围、真实 Codex thread id、共享输出受众。
-- 在 Codex App 中直接调用 `create_thread`、`send_message_to_thread`、`read_thread`、`list_threads`、`set_thread_title`、`set_thread_pinned`、`set_thread_archived`。
-- Skill 自己组装 `STARWORK:MULTIAGENT_MESSAGE v1`。
-- 用 `multiagent status --target <path> --json` 读取绑定。
-- 用 `multiagent bind` 记录真实 thread 绑定。
-- 用 `multiagent request record` 记录真实投递结果。
-- 用 `multiagent share` 登记共享输出索引。
+| AI 岗位 | 负责什么 | 可以整理或修改的范围 | 交接方式 |
+|---|---|---|---|
+| 调研助手 | 整理资料和用户痛点 | 调研笔记、资料区 | 共享调研摘要 |
+| 写作助手 | 写初稿和改表达 | 草稿、文档区 | 提交草稿给检查助手 |
+| 检查助手 | 检查事实和风险 | 检查记录 | 给出修改建议 |
 
-`starworkMultiagent` 不应该做：
+表格后加：
 
-- 写死前端、后端、测试等默认职责。
-- 自动创建任务系统、锁系统或 JSON manifest。
-- 静默修改 `matters/registry.md`。
-- 替用户决定项目一定需要多少 lane。
-- 把 lane workspace 当成项目正式输出目录。
-- 搬运或复制共享输出文件。
-- 在 Codex App 正常路径中把会话创建、消息投递、读取、命名、置顶或归档交给 CLI 伪装完成。
-- 在标准工具不可见或失败时宣称已自动送达。
+```text
+如果这个方案没问题，我再创建这些协作记录。
+```
 
-## 用户语义与主流程
+所有写入前说明：
 
-| 用户语义 | Skill 判断 | 主流程 |
-|---|---|---|
-| “把当前会话创建为一个常用智能体，负责 X” | 登记当前会话为一个稳定职责位 | 必要时 `init` / `add`，标准工具处理宿主显示动作，再 `bind` |
-| “初始化 multiagent / Agent Lanes” | 创建协议文件和可选空 lane | `multiagent init` |
-| “新增一个负责 X 的 Agent” | 创建稳定职责位，当前不一定绑定 session | `multiagent add` |
-| “把当前 Codex 绑定到 review” | 将当前具体会话绑定到已有 lane | `multiagent bind` |
-| “释放这个职责位” | 解除当前 session 绑定 | `set_thread_archived` 可选，再 `multiagent release` |
-| “看看当前分工” | 只读查看协作状态 | `multiagent status --target <path> --json` |
-| “这个输出给 writing 和 review 看” | 登记共享输出索引 | `multiagent share` |
-| “让开发 lane 开始开发” | 结构化跨会话指令 | `status` 读取绑定，Skill 组装消息，`send_message_to_thread` 投递，`request record` 记录 |
-| “看看开发 lane 做到哪了” | 宿主观察加 StarWork 状态汇总 | `status` 读取绑定，再 `read_thread` / `list_threads` |
-| “创建产品、开发、验收三个智能体” | 创建并绑定可工作的独立会话 | 必要时 `doctor` / `init` / `add`，再 `create_thread` / `set_thread_title` / `set_thread_pinned` / `bind` |
+```text
+下面是预览，还不会真正写入。
+```
+
+写入后说明：
+
+```text
+这次只写入了协作记录，没有改你的业务内容。
+```
+
+如果会修改正式文件，列出文件、目的和确认点。
 
-## Skill-owned Message
+### 不套模板
 
-Skill 直接渲染完整消息，不向 CLI 索要消息模板。
+Skill 可以用内容创作、课程制作、产品开发、资料整理等少量例子帮助用户理解拆分方式，但必须说明：
 
-Instruction Message 必须包含：
+```text
+这些只是参考，我会根据你当前这个项目重新设计，不会直接套模板。
+```
+
+不得把示例做成固定模板选择器。
+
+## v0.8 调用边界
+
+v0.9 只改变用户交互层，不改变 v0.8 工具边界。
+
+Codex App 正常路径继续直接调用：
 
-- `STARWORK:MULTIAGENT_MESSAGE v1` 包装。
-- `message_type: instruction`。
-- `request_id`、`from_lane`、`to_lane`、`created_at`、`recorded_in`。
-- 用户指令正文。
-- write scope、安全边界和当前工作区。
-- 完成后回报要求。
+- `create_thread`
+- `send_message_to_thread`
+- `read_thread`
+- `list_threads`
+- `set_thread_title`
+- `set_thread_pinned`
+- `set_thread_archived`
 
-Launch Message 使用同一包装，但正文应描述 lane 职责、写入范围、当前工作区、启动后的第一步和回报方式。
+CLI 只记录 StarWork 项目事实源：
 
-## 常见入口：创建 Agent 团队
+- `starwork doctor --target <path> --json`
+- `starwork multiagent init`
+- `starwork multiagent add`
+- `starwork multiagent bind`
+- `starwork multiagent release`
+- `starwork multiagent status --target <path> --json`
+- `starwork multiagent share`
+- `starwork multiagent request record`
 
-“创建 Agent 团队”不是只创建 lane。完整成功标准是：每个目标职责都有 lane、每个 lane 已绑定可工作的独立 session，或者输出中明确说明哪些 lane 未完成以及阻塞原因。
+Codex App 正常路径不得恢复旧的 CLI 自动投递、创建或消息模板路径。
 
-流程：
+## 主要流程
 
-1. `starwork doctor --target <path> --json` 确认工作台健康；如需启用协作层，使用 `multiagent init`。
-2. 对缺失 lane 使用 `multiagent add`，先 dry-run，用户确认后写入。
-3. Skill 为每个 lane 组装 Launch Message。
-4. 用 `create_thread` 创建独立 Codex thread。
-5. 用 `set_thread_title` 设置短标题，格式固定 `<职责名> Agent`。
-6. 用户要求置顶时，用 `set_thread_pinned`。
-7. `create_thread` 返回 thread id 后，用 `multiagent bind` 记录绑定。
-8. 任一标准工具失败时，输出 `manual_handoff_required`，给出完整可复制 Launch Message，并明确尚未自动创建或绑定。
+### 创建 AI 团队
 
-## 常见入口：发送跨 lane 指令
+1. 用户语言第一屏说明 AI 岗位是什么。
+2. 只读检查项目是否准备好，并说明只读取、不写入。
+3. 用自然问题采访项目目标、分工需求和禁止主动修改的内容。
+4. 给岗位表格预览，并等待用户确认。
+5. 用户确认后写入协作记录。
+6. 需要独立 Codex 会话时，用 `create_thread` 创建，用 `set_thread_title` 命名，必要时用 `set_thread_pinned` 置顶，再用 `multiagent bind` 记录真实会话。
+7. 汇报时区分岗位已创建、会话已绑定、消息已送达和目标任务已完成。
 
-流程：
+### 绑定当前会话
 
-1. 用 `multiagent status --target <path> --json` 读取目标 lane binding。
-2. 未绑定时，先协助用户绑定已有会话或创建新会话。
-3. Skill 组装 Instruction Message。
-4. 用 `send_message_to_thread` 投递。
-5. 成功后运行：
+先说：
 
-```bash
-starwork multiagent request record --from <from-lane> --to <to-lane> --message "<text>" --host-delivery delivered_via_codex_thread_tool --delivery-tool send_message_to_thread --target <path> --yes
+```text
+我可以把当前这个 AI 会话登记成一个长期岗位。以后你就可以说“让验收助手继续处理”，而不是每次从头解释。
 ```
 
-6. 如果标准工具失败，输出 `manual_handoff_required` 和完整消息；如果只是补记已经发生的人工动作，使用 `recorded_only`。
+如果拿不到当前会话 ID，先允许用户“稍后绑定”，不要一上来要求 `codex:<thread-id>`。
+
+### 跨岗位交接
 
-## `request record` 状态语义
+先说：
 
-`--host-delivery` 支持：
+```text
+我会把这条任务整理成一段交接消息，发送给对应的 AI 岗位，并记录在项目协作记录里。
+
+这表示消息送达了，不表示对方已经完成任务。需要的话，我可以接着帮你查看它的进展。
+```
 
-- `delivered_via_codex_thread_tool`：Codex App 标准线程工具真实投递成功。
-- `recorded_only`：仅记录事实，不表示自动送达。
-- `manual_handoff_required`：需要用户复制消息到目标会话。
-- `failed`：投递或记录失败。
-- `delivered`：历史兼容值；Codex App 正常路径不要新写入该状态。
+成功投递后用 `multiagent request record` 记录 `delivered_via_codex_thread_tool`。
 
-## Lane Workspace 与正式输出
+### 查看进展
 
-每个 lane 默认拥有一个过程工作区：
+汇报分三块：
 
 ```text
-_系统/协作/lanes/<lane-id>/workspace/
-_system/collaboration/lanes/<lane-id>/workspace/
+1. AI 会话最近状态：<summary>
+2. 岗位工作记录：<worklog summary>
+3. 共享成果：<shared output summary>
 ```
 
-它用于：
+不要把会话最近有回复直接说成任务完成。
 
-- 调研笔记。
-- 未确认草稿。
-- 中间分析。
-- 临时实验结果。
-- 给同一 lane 后续会话看的上下文材料。
+## 降级与安全接入
 
-项目正式输出目录用于：
+目标目录不是 StarWork 工作台时，说：
 
-- 用户认可的最终交付物。
-- 项目正式文档。
-- 发布稿、确认稿、版本记录。
-- 可被整个项目长期引用的稳定成果。
+```text
+我还不能确认这个目录已经适合开启多 AI 分工。
+
+为了避免写错位置，我建议先完成项目接入检查。这个过程会先预览，不会直接改文件。
+```
+
+AI 入口文档处于 `pending_merge` 时，说这是为了避免不同 AI 读到不一致规则，然后转入 `starworkInit` 安全接入。
+
+自动线程工具不可用时，说：
 
-workspace 内容需要其他 lane 读取时，建议生成 `starwork multiagent share ... --path "_系统/协作/lanes/<lane-id>/workspace/<file>"`。
+```text
+当前这个 AI 工具暂时不能自动把消息送到另一个会话。
+
+我会换成更稳妥的方式：生成一段交接消息，让你复制给目标 AI 会话。
+这样项目记录仍然清楚，也不会误以为任务已经自动完成。
+```
 
-## 安全约束
+必须展示完整 `STARWORK:MULTIAGENT_MESSAGE`，并明确“还没有自动送达”。不得说已通知或已发送成功。
 
-- 写入类 CLI 命令默认先 dry-run。
-- 用户明确要求执行或确认后，才使用 `--yes`。
-- 只读 `status` 可以直接运行。
-- 不创建默认 lane 模板。
-- 不静默覆盖已有绑定。
-- 不绕过 StarWork 工作区边界。
-- 不修改 `matters/registry.md`。
-- 不把 lane workspace 当成项目正式事实源。
-- 标准线程工具不可见或失败时，不调用 CLI 子命令伪装自动投递或自动创建。
+## 状态口径
+
+| 状态 | 可以说 | 不可以说 |
+|---|---|---|
+| 岗位已创建 | 已经创建了 AI 岗位 | Agent 已经开始工作 |
+| 会话已绑定 | 这个岗位已经有对应 AI 会话 | 任务已经完成 |
+| 消息已送达 | 交接消息已发送给目标会话 | 目标会话已经完成任务 |
+| 目标任务已完成 | 目标会话已明确回报完成，或 worklog / shared output 有完成证据 | 只因消息已发送就说完成 |
 
 ## 验收标准
 
-- 给定“让开发 lane 开始实现”，skill 用 `multiagent status --target <path> --json` 查绑定，自己组装 `STARWORK:MULTIAGENT_MESSAGE v1`，用 `send_message_to_thread` 投递，再用 `multiagent request record` 写入 `delivered_via_codex_thread_tool`。
-- 给定“创建产品、开发、验收三个智能体”，skill 用 `create_thread` 建会话，用 `set_thread_title` 设置 `<职责名> Agent`，必要时用 `set_thread_pinned`，再用 `multiagent bind` 记录。
-- 给定“看看开发 lane 做到哪了”，skill 用 `multiagent status --target <path> --json` 查绑定，再用 `read_thread` 或 `list_threads` 观察。
-- 给定标准线程工具不可见或失败，skill 输出 `manual_handoff_required` 和完整可复制消息，并说明尚未自动送达。
-- 给定“这个输出给 writing 和 review 看”，skill 生成 `starwork multiagent share ...`，不移动原文件。
+- 第一屏包含 AI 岗位、负责什么、可以整理或修改哪些内容、交接、先预览和确认后。
+- 第一屏不包含内部词：lane、write_scope、binding、thread、CLI、doctor、multiagent init、multiagent add。
+- 创建团队时先问项目目标、分工需求和禁止主动修改内容。
+- 创建或调整岗位前用表格预览，并有“如果这个方案没问题，我再创建这些协作记录。”
+- 写入前说“下面是预览，还不会真正写入”；写入后说“这次只写入了协作记录，没有改你的业务内容。”
+- 自动工具不可用时说明还没有自动送达，并给出完整可复制交接消息。
+- v0.8 禁止项扫描继续通过。