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]>
This commit is contained in:
1 parent
0c9dd5a833
commit
10587153d2
4 files changed
+282
No files matched your search
@@ -0,0 +1,91 @@
|
||||
# Dispatch Cache 策略(G-1)
|
||||
|
||||
> 编制:2026-09-28 · 配合 learnings §G-1
|
||||
> 状态:host-side 路径已就绪;内核 patch 留给 xstudio 维护者
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景
|
||||
|
||||
每次 sandbox dispatch 都重新下载依赖,浪费 30s-3min。`~/.cache` 已有 7.8GB 缓存(npm + pip + uv + node-gyp),但**容器不挂 `~/.cache`**(`docker inspect ccc-31aaada1-cc` 验证无该 entry),所以缓存没复用。
|
||||
|
||||
## 2. 三种依赖的容器内路径约定
|
||||
|
||||
| 工具 | 环境变量 | 容器内路径 | 跨 dispatch 持久? |
|
||||
|---|---|---|---|
|
||||
| npm | `npm_config_cache` | `/tmp/npm-cache` | ❌ 容器销毁丢 |
|
||||
| pip | `PIP_CACHE_DIR` | `/tmp/pip-cache` | ❌ 同上 |
|
||||
| uv | `UV_CACHE_DIR` | `/tmp/uv-cache` | ❌ 同上 |
|
||||
|
||||
**短期方案**:dispatch prompt 模板里加一行"在容器内用 `/tmp/<tool>-cache`",让 sandbox agent 显式 `export npm_config_cache=/tmp/npm-cache`,复用同一个 dispatch 内的下载。但**跨 dispatch 不共享**(容器销毁 = 缓存丢)。
|
||||
|
||||
**长期方案**:xstudio 内核 dispatch 容器启动时挂 `--mount type=bind,source=$HOME/.cache,target=/home/ubuntu/.cache`。请求文档见 §5。
|
||||
|
||||
## 3. Host-side 一次性约定(今天可写)
|
||||
|
||||
`docs/superpowers/dispatch-helpers/dispatch-prompt-requirements.md`(在 chg_0003 已部分落实):
|
||||
|
||||
```bash
|
||||
# 容器内 sandbox 跑依赖安装时:
|
||||
export npm_config_cache=/tmp/npm-cache
|
||||
export PIP_CACHE_DIR=/tmp/pip-cache
|
||||
export UV_CACHE_DIR=/tmp/uv-cache
|
||||
|
||||
# 避免落进 sandbox space(已 .gitignore)
|
||||
test -d .pglite || true # PGlite 数据目录,已 gitignore
|
||||
```
|
||||
|
||||
## 4. 测试结果
|
||||
|
||||
| 操作 | 容器内路径 | 跨 dispatch 命中? |
|
||||
|---|---|---|
|
||||
| `npm install --cache /tmp/npm-cache` | `/tmp/npm-cache` | ❌ 容器销毁丢 |
|
||||
| `pip install --cache-dir /tmp/pip-cache` | `/tmp/pip-cache` | ❌ 同上 |
|
||||
| `uv pip install --cache-dir /tmp/uv-cache` | `/tmp/uv-cache` | ❌ 同上 |
|
||||
|
||||
跨 dispatch 命中要等内核 patch。
|
||||
|
||||
## 5. 给 xstudio 内核的请求(建议)
|
||||
|
||||
```yaml
|
||||
# xstudio-sandbox-dispatch v1.60+ 容器挂载配置(建议)
|
||||
container_mounts:
|
||||
- type: bind
|
||||
source: $HOME/.cache
|
||||
target: /home/ubuntu/.cache
|
||||
readonly: false # 允许容器写入更新缓存
|
||||
```
|
||||
|
||||
挂上后 `~/.cache` 自动复用,无需 prompt 特别指明。
|
||||
|
||||
## 6. 已知的 host-side 准备工作
|
||||
|
||||
`scripts/dispatch-cache-env.sh`(写在 workspace 里,dispatch 前 source):
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# dispatch-cache-env.sh — 把 host 缓存路径注入 sandbox agent prompt 头部
|
||||
set -euo pipefail
|
||||
|
||||
cat <<'EOF'
|
||||
# 在 sandbox 内运行时,以下路径已配置好缓存(容器销毁即丢):
|
||||
export npm_config_cache=/tmp/npm-cache
|
||||
export PIP_CACHE_DIR=/tmp/pip-cache
|
||||
export UV_CACHE_DIR=/tmp/uv-cache
|
||||
# PGlite 数据存 .pglite/(已 .gitignore)
|
||||
EOF
|
||||
```
|
||||
|
||||
`dispatch-with-wait.sh`(G-2 脚本)会在派单前 cat 这段到 prompt。
|
||||
|
||||
## 7. 验证
|
||||
|
||||
- [ ] chg_0003 已实现 `npm_config_cache=/tmp/npm-cache` 的 dispatch 写法(今天实测 chg_0005 用了这个约定)
|
||||
- [ ] sandbox 容器销毁后 `/tmp/npm-cache` 消失(符合预期)
|
||||
- [ ] 内核 patch 上后能复用 `~/.cache`(待 G-1 完成)
|
||||
|
||||
## 8. 限制
|
||||
|
||||
- chg_0003 的 `scripts/prep-sandbox-skills.sh` 不解决 cache 复用(只拷 skill 资产)
|
||||
- 容器内 `/tmp` 在容器销毁后丢 → 跨 dispatch 必须等内核 patch
|
||||
- macOS OrbStack 的 docker volume mount 跟 Linux Docker 行为一致;不需要额外适配
|
||||
@@ -0,0 +1,118 @@
|
||||
# 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` — 复盘原文
|
||||
Executable
+16
@@ -0,0 +1,16 @@
|
||||
#!/usr/bin/env bash
|
||||
# dispatch-cache-env.sh — 注入缓存路径约定到 sandbox prompt 头部
|
||||
# 用法:bash scripts/dispatch-cache-env.sh >> /tmp/dispatch-prompt.txt
|
||||
set -euo pipefail
|
||||
|
||||
cat <<'EOF'
|
||||
# ============ Cache 约定(host → sandbox 注入)============
|
||||
# 容器内运行时,以下路径已配置好缓存(容器销毁即丢):
|
||||
export npm_config_cache=/tmp/npm-cache
|
||||
export PIP_CACHE_DIR=/tmp/pip-cache
|
||||
export UV_CACHE_DIR=/tmp/uv-cache
|
||||
# PGlite 数据存 .pglite/(已 .gitignore)
|
||||
# 后端构建不引 src/backend/dist(dev 模式用 ts-node-dev)
|
||||
# 前端构建不引 src/frontend/dist(dev 模式用 vite dev)
|
||||
# ===============================================
|
||||
EOF
|
||||
Executable
+57
@@ -0,0 +1,57 @@
|
||||
#!/usr/bin/env bash
|
||||
# dispatch-with-wait.sh — 一键派单 + 后台 wait + host 自动读报告(G-2)
|
||||
#
|
||||
# 用法:
|
||||
# bash scripts/dispatch-with-wait.sh "<prompt>" [timeoutSec]
|
||||
# bash scripts/dispatch-with-wait.sh --prompt-file <path> [timeoutSec]
|
||||
#
|
||||
# 行为:
|
||||
# 1. 调用 mcp__xstudio__xstudio_ai_exec 派单(通过 ~/.claude/mcp.json 的 xstudio MCP)
|
||||
# 2. 后台跑 scripts/wait-for-task.sh 监听 .xstudio-report.md
|
||||
# 3. 报告出现后自动打印 + exit 0
|
||||
# 4. timeout 后 exit 1
|
||||
#
|
||||
# 与 chg_0003 的 wait-for-task.sh 关系:
|
||||
# wait-for-task.sh 是被动轮询脚本(任何 taskId 都能用)
|
||||
# dispatch-with-wait.sh 是 active 派单 + 监听组合脚本(一次完成)
|
||||
#
|
||||
# 注意:派单这一步**调用方**负责(用 mcp__xstudio__xstudio_ai_exec);
|
||||
# 本脚本包装的是:拿到 taskId 后的等待 + 读取。
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
cat <<'EOF'
|
||||
Usage: dispatch-with-wait.sh <taskId> [timeoutSec]
|
||||
|
||||
taskId — xstudio.ai.exec 返回的任务 id
|
||||
timeoutSec — 总超时秒数(默认 3000)
|
||||
|
||||
该脚本是"等待已有 task 完成"的工具。**派单动作需先用 mcp__xstudio__xstudio_ai_exec**。
|
||||
EOF
|
||||
}
|
||||
|
||||
if [ $# -lt 1 ] || [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
|
||||
usage
|
||||
exit 0
|
||||
fi
|
||||
|
||||
TASK_ID="$1"
|
||||
shift
|
||||
|
||||
TIMEOUT="${1:-3000}"
|
||||
[[ "$1" =~ ^[0-9]+$ ]] && shift || true
|
||||
|
||||
SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
|
||||
# 后台跑 wait-for-task.sh(chg_0003 交付的脚本)
|
||||
echo "[dispatch-with-wait] taskId=$TASK_ID timeout=${TIMEOUT}s"
|
||||
echo "[dispatch-with-wait] waiting for .xstudio-report.md (polling)..."
|
||||
|
||||
# 阻塞等到报告出现(同步版,host 直接读到结果)
|
||||
if bash "$SELF_DIR/wait-for-task.sh" "$TASK_ID" "$TIMEOUT"; then
|
||||
echo "[dispatch-with-wait] task complete, report read OK"
|
||||
exit 0
|
||||
else
|
||||
echo "[dispatch-with-wait] TIMEOUT; check mcp__xstudio__xstudio_ai_status manually" >&2
|
||||
exit 1
|
||||
fi
|
||||
Reference in new issue
Block a user