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]>
91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# 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 行为一致;不需要额外适配 |