From 10587153d295aa9b289eae34f05e162459df5ef2 Mon Sep 17 00:00:00 2001 From: xstudio agent Date: Mon, 28 Sep 2026 13:48:43 +0800 Subject: [PATCH] =?UTF-8?q?feat(dispatch-helpers):=20G-1=20cache=20?= =?UTF-8?q?=E7=AD=96=E7=95=A5=20+=20G-2=20=E4=B8=80=E9=94=AE=E6=B4=BE?= =?UTF-8?q?=E5=8D=95=20+=20G-3=20=E6=B4=BE=E5=8D=95=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../dispatch-helpers/cache-strategy.md | 91 ++++++++++++++ .../dispatch-helpers/prompt-protocol.md | 118 ++++++++++++++++++ scripts/dispatch-cache-env.sh | 16 +++ scripts/dispatch-with-wait.sh | 57 +++++++++ 4 files changed, 282 insertions(+) create mode 100644 docs/superpowers/dispatch-helpers/cache-strategy.md create mode 100644 docs/superpowers/dispatch-helpers/prompt-protocol.md create mode 100755 scripts/dispatch-cache-env.sh create mode 100755 scripts/dispatch-with-wait.sh diff --git a/docs/superpowers/dispatch-helpers/cache-strategy.md b/docs/superpowers/dispatch-helpers/cache-strategy.md new file mode 100644 index 0000000..713def6 --- /dev/null +++ b/docs/superpowers/dispatch-helpers/cache-strategy.md @@ -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/-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 行为一致;不需要额外适配 \ No newline at end of file diff --git a/docs/superpowers/dispatch-helpers/prompt-protocol.md b/docs/superpowers/dispatch-helpers/prompt-protocol.md new file mode 100644 index 0000000..11af7c7 --- /dev/null +++ b/docs/superpowers/dispatch-helpers/prompt-protocol.md @@ -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// +- 写 $XSTUDIO_SANDBOX_SPACE/.xstudio-report.md(**汇报用**) +- 阶段性 git commit 在 sandbox 分支 +``` + +## 4. 汇报约定(G-2 配合) + +sandbox agent **必须**在退出前写 `$XSTUDIO_SANDBOX_SPACE/.xstudio-report.md`: + +```markdown +=== === +PASS / FAIL + +改动文件清单(每文件一句话): +- ... + +门禁: +- check_spec_coverage.sh: gap=N +- e2e .sh: pass=N/fail=N +- tsc --noEmit: N error + +git log sandbox --oneline | head -10: +- +... + +是否建议合并:是 / 否 +``` + +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 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` — 复盘原文 \ No newline at end of file diff --git a/scripts/dispatch-cache-env.sh b/scripts/dispatch-cache-env.sh new file mode 100755 index 0000000..b39c9a7 --- /dev/null +++ b/scripts/dispatch-cache-env.sh @@ -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 \ No newline at end of file diff --git a/scripts/dispatch-with-wait.sh b/scripts/dispatch-with-wait.sh new file mode 100755 index 0000000..f73c74e --- /dev/null +++ b/scripts/dispatch-with-wait.sh @@ -0,0 +1,57 @@ +#!/usr/bin/env bash +# dispatch-with-wait.sh — 一键派单 + 后台 wait + host 自动读报告(G-2) +# +# 用法: +# bash scripts/dispatch-with-wait.sh "" [timeoutSec] +# bash scripts/dispatch-with-wait.sh --prompt-file [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 [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 \ No newline at end of file