docs(design): xstudio-sandbox-dispatch framework improvements — A1 skill prep + A2 ai-config auto-detect + A3 task completion signal + chg_0004 React frontend scope

This commit is contained in:
xstudio agent committed 2026-09-28 11:00:46 +08:00
1 parent 82a96f4b81
commit 3f5f32fd99
1 file changed
+274
@@ -0,0 +1,274 @@
# xstudio-sandbox-dispatch 框架完善设计
> 编制日期:2026-09-28
> 触发:首次端到端派单(taskId `ai-1790562657-0EF743`,exit 0)后复盘,发现 3 个真坑
> 范围:仅限宿主(macOS / xstudio 内核 MCP 客户端)侧的改进;不动 xstudio 内核本身
> 配合:chg_0003 React 前端(独立 chg,按 ai-collab-framework 标准流程)
---
## 0. 摘要
今天首次跑完 xstudio-sandbox-dispatch 闭环,**主线功能(派单 → 沙盒执行 → 门禁 → 合并)跑通了**,但暴露 3 个宿主侧的真坑:A1 沙盒拿不到 skill 资产 → 完整脚手架没进容器;A2 ai-config.json 缺省值导致首次派单 401;A3 任务完成信号只走 macOS 通知,AI agent 容易漏接。
本设计为 A1/A2/A3 三项提供最小修改路径,使下一次 dispatch:
- ✅ 沙盒能拿到 `ssw-jnpf-lite-react` 完整脚手架(不再降级为手搓最小骨架)
- ✅ 首次派单就用对 provider,0 次 403 重试
- ✅ AI agent 在任务完成时自动知道,不靠 macOS 通知
非目标:不动 xstudio 内核、不重写 sandbox 容器镜像、不改 claude-process provider 本身。
---
## A1:skill 资产挂载问题
### 现象(2026-09-28 实战)
- 宿主:`/Users/xs/.claude/skills/ai-collab-framework/` 和 `/Users/xs/.claude/skills/ssw-jnpf-lite-react/` 都在
- 我手工 `cp -R` 到 `/Users/xs/Desktop/workspace/dth/.xstudio/cc/.claude/skills/`
- 沙盒 agent 启动后 `find /` 找不到 `run.sh`(ssw 脚手架入口),`/home/ubuntu/.claude/skills/` `Permission denied`
- 结论:**沙盒拿到的 ccWorkDir 不含 `.xstudio/`**(要么不挂、要么挂但被内核忽略),手工放 .xstudio 没用
- 后果:沙盒降级为手搓最小 NestJS 骨架,少了 ssw-jnpf-lite-react 的 demo/shop/dashboard 业务模块
### 根因(推断,未验证)
候选 1:xstudio 内核 ccWorkDir 挂载在 mount 阶段就排除 `.xstudio/`(防止容器写回污染运行时配置)
候选 2:`.xstudio/cc/.claude/skills/` 是 xstudio 容器 config 分区,**不挂进 ccWorkDir**,只挂进容器内的 `~/.claude/`
候选 3:技能 symlink 指向 host 绝对路径,容器解析时 host 路径不存在
需要 spike 验证:`docker exec <container> ls -la /home/ubuntu/.claude/skills/` 看软链状态 + `mount | grep ccWorkDir` 看挂载选项。
### 解决方案(3 个,宿主侧)
**方案 1(推荐):pre-dispatch host-side prep script**
- 在派单前,host 跑 `scripts/prep-sandbox-skills.sh <wsHash>`
- 把 `~/.claude/skills/` 里的非 symlink skill 全部 `cp -R` 到 `/tmp/xstudio-sandbox/<hash>/space/.claude/skills/`(**写进 sandbox space,不写 workspace**)
- 沙盒空间是 sandbox agent 自己的 cwd,相当于「把 skill 拷到 sandbox agent 家目录」,agent 自然能在 `Skill` 工具调用时找到
- 代价:每个新空间首单要重做;symlink 解引用由 host 负责,避免容器解析失败
- 风险:磁盘占空间(每个 sandbox copy 一份 skills),但 skills 文件 < 5MB,可忽略
**方案 2:prompt 显式约束**
- 每次 dispatch 在 prompt 里写:"skill 在 `/home/ubuntu/space/.claude/skills/<name>/`(pre-dispatch 已 cp)"
- 不动文件系统,全靠 prompt 指令
- 风险:靠 prompt 不稳定,agent 可能绕过
**方案 3:写 xstudio 内核 plugin**
- 给 xstudio 加一个 pre-task hook,让内核在容器启动时把 skill 挂到容器内 `~/.claude/skills/`
- 风险:动 xstudio 内核,超出本次范围
### 决策
选方案 1:写 `scripts/prep-sandbox-skills.sh <wsHash>` host-side 脚本,作为 dispatch 流程的标准前置步骤。
### 实现要点
```bash
# scripts/prep-sandbox-skills.sh
SKILL_SRC="$HOME/.claude/skills"
SPACE_DIR="/tmp/xstudio-sandbox/$1/space"
if [ ! -d "$SPACE_DIR" ]; then
echo "ERROR: space $SPACE_DIR 不存在;先派一个任务让内核播种" >&2
exit 1
fi
mkdir -p "$SPACE_DIR/.claude/skills"
for skill_dir in "$SKILL_SRC"/*/; do
name=$(basename "$skill_dir")
# 跳过 symlink(在容器里会断),只拷实体目录
if [ ! -L "$skill_dir" ]; then
cp -R "$skill_dir" "$SPACE_DIR/.claude/skills/$name"
echo "copied: $name"
fi
done
```
**集成进 dispatch 流程**:
- 在调 `xstudio.ai.exec` 之前,host 先跑 prep script
- prep 写在 sandbox 空间 = sandbox agent 自己能 `ls -la /home/ubuntu/space/.claude/skills/`
- prompt 里**不**再提 skill 路径(让 sandbox agent 用自己的 Skill tool 探索发现),避免 prompt ↔ skill 漂移
### 验证脚本:`scripts/verify-skill-prep.sh`
- 派一个微小探针任务,prompt = "列出 /home/ubuntu/space/.claude/skills/ 下所有目录"
- 确认返回包含 `ai-collab-framework` 和 `ssw-jnpf-lite-react`
- exit 0 = 验证通过
---
## A2:ai-config.json 缺省值导致首次派单 401
### 现象
- 宿主有 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL=https://lm.mayishangshu.cn:88/minimax/anthropic`、`ANTHROPIC_MODEL=MiniMax-M3` 在 env
- 首次派单,claude-process provider 因为 ai-config.json 是 `{}` 用了兜底 `api.minimaxi.com/anthropic` + 空 `MINIMAX_API_KEY`
- 沙盒收到 "Failed to authenticate. API Error: 403 Request not allowed"
- 浪费一轮 dispatch + 等 ~30 秒才手动纠正
### 解决方案
**写 `scripts/setup-xstudio-ai.sh`**:workspace 打开后自动跑一次(写入 `<ws>/.xstudio/ai-config.json`),后续 dispatch 直接命中配置。
```bash
# scripts/setup-xstudio-ai.sh
CONFIG="$1/.xstudio/ai-config.json" # arg = workspaceRoot
# 1. 读 ANTHROPIC_BASE_URL(兜底 lm.mayishangshu.cn:88/minimax/anthropic)
BASE_URL="${ANTHROPIC_BASE_URL:-https://lm.mayishangshu.cn:88/minimax/anthropic}"
# 2. 读 ANTHROPIC_AUTH_TOKEN(从 ~/ssw.ini 兜底)
TOKEN_ENV="${ANTHROPIC_AUTH_TOKEN:-}"
if [ -z "$TOKEN_ENV" ] && [ -f "$HOME/ssw.ini" ]; then
TOKEN_ENV=$(awk -F'key=' '/^\[llm—api\]/{f=1} f && /key=/{print $2; exit}' "$HOME/ssw.ini" | tr -d ' ')
fi
if [ -z "$TOKEN_ENV" ]; then
echo "ERROR: ANTHROPIC_AUTH_TOKEN 未设且 ~/ssw.ini 无 [llm—api].key=" >&2
exit 1
fi
# 3. 读 ANTHROPIC_MODEL(兜底 MiniMax-M3)
MODEL="${ANTHROPIC_MODEL:-MiniMax-M3}"
# 4. 写 ai-config.json(JSON 化 TOKEN_ENV 值转义)
ESCAPED_TOKEN=$(printf '%s' "$TOKEN_ENV" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read())[1:-1])')
mkdir -p "$(dirname "$CONFIG")"
cat > "$CONFIG" <<EOF
{
"providers": {
"claude-process": {
"baseURL": "$BASE_URL",
"authTokenEnv": "ANTHROPIC_AUTH_TOKEN",
"ccContainer": true,
"model": "$MODEL"
}
}
}
EOF
echo "ai-config written: $CONFIG (baseURL=$BASE_URL, model=$MODEL, authTokenEnv=ANTHROPIC_AUTH_TOKEN)"
```
**集成方式**:在 `setup-xstudio-ai.sh` 写入 config 后,claude-process provider 需要**重启才能读 ai-config**?或者 provider 是按需读的(每次 exec 都读 ai-config.json)?
待 spike 验证:写完 config 立刻派单,看是否还要重启。
---
## A3:任务完成信号只在 macOS 通知,AI agent 漏接
### 现象
- 任务 exit 0,macOS 通知发了
- 我没主动 poll `xstudio.ai.status`(之前 `sleep 90` 那次被用户打断,所以不知道已经完成)
- 用户主动告知后才知道
### 解决方案(双管齐下)
**信号 1:sandbox 写完成报告到固定路径**
prompt 里固定一行:"完成后写 `=== 任务报告 ===` markdown 到 `/home/ubuntu/space/.xstudio-report.md`"
host 端每次 dispatch 之后,`/tmp/xstudio-sandbox/<hash>/space/.xstudio-report.md` 一旦出现 = 任务完成 + 报告就位
**信号 2:host-side poll loop(在 manifest 内的 socket,不靠 macOS 通知)**
写 `scripts/wait-for-task.sh <taskId> [timeoutSec]`:
```bash
TASK_ID="$1"
TIMEOUT="${2:-3000}"
START=$(date +%s)
WS_HASH=$(ls /tmp/xstudio-sandbox | head -1) # 简单假设一个 hash
REPORT="/tmp/xstudio-sandbox/$WS_HASH/space/.xstudio-report.md"
while true; do
if [ -f "$REPORT" ]; then
echo "task complete, report: $REPORT"
cat "$REPORT"
exit 0
fi
ELAPSED=$(($(date +%s) - START))
if [ $ELAPSED -gt $TIMEOUT ]; then
echo "TIMEOUT after ${TIMEOUT}s; check mcp__xstudio__xstudio_ai_status manually"
exit 1
fi
sleep 30
done
```
**集成方式**:派单后立即 `scripts/wait-for-task.sh <taskId>`(放后台,不阻塞对话),到时间自动出报告,host agent 在下一轮 tool 调用时能看到结果文件。
实际上更轻量:不写单独 wait script,**只让 sandbox 写报告**。host agent 自己有 `xstudio.ai.status` 可以调,再加一条经验法则:"dispatch 后 30s / 90s / 180s 各 check 一次 status"。但 wait-for-task 让这套循环可以脚本化,方便以后挂 cron / system service。
---
## B:chg_0003 React 前端(独立 chg,按 ai-collab-framework)
能力名:`experiment_platform_web`(独立 capability,避免与 backend 的 experiment_platform 共享 S 编号空间)。
### 范围
- 登录页:SSW envelope 标准登录(`/api/ssw/dth/auth/login`)
- Dashboard:3 卡(实验总数 / 算子数 / 学员数),本 MVP 取 mock 数据
- Operator 列表页:3 算子卡片(hello-mpc / pir / vertical-lr),点卡片进 run
- Run 页面:算子表单(按 schema 字段)+ 启动 + 结果展示(真算子的 output_json 渲染为表格 + 能力雷达图 mock)
### 6 scenarios(capability 级 S 编号从 1 起)
- S1 page_login_form_submit
- S2 page_login_success_redirect_to_dashboard
- S3 page_login_failure_show_401_message
- S4 page_operator_list_shows_three_cards
- S5 page_run_form_submit_starts_run_with_run_id
- S6 page_run_result_shows_output_json_with_real_data
S 编号不与 chg_0002 冲突(chg_0002 是 backend capability,编号 1-6;chg_0003 是 web capability,独立从 S1 起)。
### chg_0003 主要改动文件(约束)
- `src/frontend/src/main.tsx`(路由入口)
- `src/frontend/src/api/{auth,operators,runs}.ts`(3 个 API 客户端)
- `src/frontend/src/views/{Login,Dashboard,OperatorList,Run}.tsx`(4 页)
- `src/frontend/src/components/{OperatorCard,RunResult,Radar}.tsx`(3 组件)
- `src/frontend/vite.config.ts`(proxy `/api` → :30000)
- 修改 `package.json` 加 react-router-dom / axios / recharts
### 部署方式
`./run.sh dev` 已经同时起后端 30000 + 前端 5173;前端访问 `http://127.0.0.1:5173`,Vite proxy 把 `/api/*` 转给 30000。
---
## 实施顺序
```
T1 (本任务): 写 A1 prep-sandbox-skills.sh + A2 setup-xstudio-ai.sh + A3 wait-for-task.sh
T2 (本任务): 写 design.md(本文档)→ spec self-review → 用户 review
T3 (本任务): 写 chg_0003 工件(proposal/spec/tasks/testcases/map)
T4 (本任务): 派 sandbox 任务做 chg_0003 frontend + 验证 chg_0003 PASS + gate
T5 (本任务): 独立复核 + mergePreview + 用户批准 + apply + commit
T6 (后续): 沙盒空间清理
```
T1-T2 在 host 完成,T3-T6 走 sandbox dispatch。
---
## 风险与回滚
| 风险 | 缓解 |
|---|---|
| A1 prep script 拷贝 skills 失败导致 sandbox 拿到空 .claude/skills/ | 在 prep script 末尾 `test -d $SPACE_DIR/.claude/skills/ai-collab-framework` 断言,失败 exit 1 不派单 |
| A2 setup 误覆盖用户已有 ai-config.json | 先读再合并(jq merge),不覆盖已有 provider,只填空 |
| A3 wait-for-task 永久 hang | timeout 默认 3000s,到时 exit 1 让人工接管 |
| chg_0003 frontend vite proxy / CORS 问题 | 后端 `cors: true` 已开;proxy 配置在 vite.config.ts |
| sandbox 沙盒 `.claude/skills/` 写不进 gitignore 的 `space/` 区域 | space 不入 git,但 sandbox 内不算工作区,OK |
---
## 能力边界
- 不动 xstudio 内核(不改 `.xstudio/cc/` 加载流程)
- 不重写 sandbox 容器镜像(不重打 `cc:latest`)
- 不改 ai-collab-framework 门禁脚本(已经稳定)
- 不做 React 组件库沉淀(先 MVP,组件随用随写)
- 不做 E2E 浏览器测试(Playwright 等下次)