Files
dth/docs/superpowers/dispatch-helpers/prompt-protocol.md
T
xstudio agentandClaude Opus 4.8 10587153d2 feat(dispatch-helpers): G-1 cache 策略 + G-2 一键派单 + G-3 派单规范
G-1 cache 策略(docs/superpowers/dispatch-helpers/cache-strategy.md):
- 三种依赖容器内路径约定(/tmp/npm-cache, /tmp/pip-cache, /tmp/uv-cache)
- scripts/dispatch-cache-env.sh 注入 prompt 头部
- 给 xstudio 内核的 mount ~/.cache 请求文档

G-2 一键派单(scripts/dispatch-with-wait.sh):
- 包装 wait-for-task.sh,提供 active 派单 + 同步等待接口
- 验证:超时 → EXIT=1,报告就位 → EXIT=0

G-3 派单规范(docs/superpowers/dispatch-helpers/prompt-protocol.md):
- 派单"不要做"硬约束清单(11 条)
- 派单"允许做"白名单
- 汇报约定 + host-side wrapper 模板
- 失效场景 + 内核维护者建议

Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-09-28 13:48:43 +08:00

4.2 KiB
Raw Blame History

Dispatch Prompt 规范(G-3)

编制:2026-09-28 · 配合 learnings §G-3 状态:host-side 派单约束清单;内核"接管"语义不可控,由调用方规避


1. 背景

AI 插件(Claude Code / WorkBuddy / Cursor)的"继续此对话"按钮是否接管 host 会话,取决于插件实现,xstudio / dispatch skill 这边无法控制。

  • Claude Code /resume = 修改会话历史(接管)
  • Claude Code --continue = 保留历史继续(续命)
  • WorkBuddy / Cursor "继续对话"按钮行为不透明,需读插件源码

没有"只读查看"模式:shell / 工具调用本身不能"只读"。本规范通过 host 端派单约束,主动规避 sandbox 任务引发 host 接管的场景。

2. 派单"不要做"清单(写入 prompt 头部)

每个 dispatch prompt 必须含以下约束(host 加):

# 不要做的事(防止 host 接管的硬约束)
- 不修改 ~/.zshrc / ~/.bashrc / ~/.config/、任何 shell rc 文件
- 不修改 ~/ssw.ini / ~/Library/Application Support/ 任何凭据
- 不修改全局 git config(git config --global / git config --system)
- 不修改 /usr/local/bin / /opt/ 等系统级 PATH 路径
- 不动本机 docker 守护进程配置
- 不动 macOS 系统设置(defaults write、login items 等)
- 不调 macOS 网络请求(open URL、SMS 等)
- 不写 ~/.claude/settings.json(xstudio 内核自己的事)
- 不写 /Users/xs/Desktop/workspace 之外的工作区(dth workspace 边界)
- 不 fallback 到 /tmp 或其他路径(mount 不可用就报错退出)
- 不调 xstudio.build.run / xstudio.console.*(容器已关闭)

3. 派单"允许做"清单

# 允许做的事(受 sandbox 空间约束)
- 写 $XSTUDIO_SANDBOX_SPACE 内的文件
- 跑 install + dev + test 命令(容器本地 shell)
- 改 src/、tests/、scripts/、openspec/changes/<chg>/
- 写 $XSTUDIO_SANDBOX_SPACE/.xstudio-report.md(**汇报用**)
- 阶段性 git commit 在 sandbox 分支

4. 汇报约定(G-2 配合)

sandbox agent 必须在退出前写 $XSTUDIO_SANDBOX_SPACE/.xstudio-report.md:

=== <chg_id> <chg_slug> ===
PASS / FAIL

改动文件清单(每文件一句话):
- ...

门禁:
- check_spec_coverage.sh: gap=N
- e2e <test>.sh: pass=N/fail=N
- tsc --noEmit: N error

git log sandbox --oneline | head -10:
- <hash> <msg>
...

是否建议合并:是 / 否

host 通过 dispatch-with-wait.sh(G-2 脚本)阻塞等待 + 自动读这份报告,不需要 "继续此对话"。

5. Host-side 派单 wrapper 模板(chg_0003+ 已落地)

[mcp__xstudio__xstudio_ai_exec] ← host 派单
  ↓ taskId / sessionId
[mcp__xstudio__xstudio_ai_logs] ← host 实时读 logs(如需)
  ↓
[scripts/dispatch-with-wait.sh <taskId> 3000] ← host 阻塞等待 + 读报告
  ↓ EXIT 0 = 报告就位 + cat 完
EXIT 0 = host 拿到结果,无需接管 sandbox 会话

6. 失效场景与兜底

场景 症状 兜底
sandbox 不写 .xstudio-report.md wait-for-task.sh timeout exit 1 host 调 mcp__xstudio__xstudio_ai_status 手动查
sandbox 误写 host 全局配置 (罕见)host 检测 dispatch skill 加 sandbox 写权限白名单(黑名单兜底)
sandbox 内核接管 host session (未观察到) prompt 强约束 + 设置文件加 gitignore 兜底

7. 给内核维护者的建议

dispatch skill 的派单前自检应加:

# prompt 内容必须含 "不要做的事" 清单
if ! grep -q "不要做的事" "$PROMPT_FILE"; then
  echo "ERROR: prompt 缺 '不要做的事' 硬约束" >&2
  exit 1
fi

强制派单方把硬约束写进 prompt,避免未来误用。

8. 验证

  • chg_0003 prompt 含完整"不要做"清单 → sandbox 没误碰 host 全局配置
  • chg_0005 prompt 含完整清单 → sandbox 没动 host
  • 内核派单前自检(待 dispatch skill 升级)

9. 相关文件

  • scripts/dispatch-with-wait.sh — 一键派单 + wait(G-2)
  • scripts/dispatch-cache-env.sh — 注入 cache 约定(G-1)
  • docs/superpowers/dispatch-helpers/cache-strategy.md — cache 策略
  • docs/superpowers/learnings/2026-09-28-dispatch-session.md — 复盘原文