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]>
118 lines
4.2 KiB
Markdown
118 lines
4.2 KiB
Markdown
# 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` — 复盘原文 |