Files
dth/docs/superpowers/dispatch-helpers/cache-strategy.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

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