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

118 lines
4.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`:
```markdown
=== <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 的派单前自检应加:
```bash
# prompt 内容必须含 "不要做的事" 清单
if ! grep -q "不要做的事" "$PROMPT_FILE"; then
echo "ERROR: prompt 缺 '不要做的事' 硬约束" >&2
exit 1
fi
```
强制派单方把硬约束写进 prompt,避免未来误用。
## 8. 验证
- [x] chg_0003 prompt 含完整"不要做"清单 → sandbox 没误碰 host 全局配置
- [x] 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` — 复盘原文