From 3f5f32fd997182ecccc3f2c3feba259c3286c0f8 Mon Sep 17 00:00:00 2001 From: xstudio agent Date: Mon, 28 Sep 2026 11:00:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(design):=20xstudio-sandbox-dispatch=20fram?= =?UTF-8?q?ework=20improvements=20=E2=80=94=20A1=20skill=20prep=20+=20A2?= =?UTF-8?q?=20ai-config=20auto-detect=20+=20A3=20task=20completion=20signa?= =?UTF-8?q?l=20+=20chg=5F0004=20React=20frontend=20scope?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...026-09-28-xstudio-dispatch-improvements.md | 274 ++++++++++++++++++ 1 file changed, 274 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md diff --git a/docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md b/docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md new file mode 100644 index 0000000..385b3df --- /dev/null +++ b/docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md @@ -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 ls -la /home/ubuntu/.claude/skills/` 看软链状态 + `mount | grep ccWorkDir` 看挂载选项。 + +### 解决方案(3 个,宿主侧) + +**方案 1(推荐):pre-dispatch host-side prep script** +- 在派单前,host 跑 `scripts/prep-sandbox-skills.sh ` +- 把 `~/.claude/skills/` 里的非 symlink skill 全部 `cp -R` 到 `/tmp/xstudio-sandbox//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//`(pre-dispatch 已 cp)" +- 不动文件系统,全靠 prompt 指令 +- 风险:靠 prompt 不稳定,agent 可能绕过 + +**方案 3:写 xstudio 内核 plugin** +- 给 xstudio 加一个 pre-task hook,让内核在容器启动时把 skill 挂到容器内 `~/.claude/skills/` +- 风险:动 xstudio 内核,超出本次范围 + +### 决策 + +选方案 1:写 `scripts/prep-sandbox-skills.sh ` 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 打开后自动跑一次(写入 `/.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" </space/.xstudio-report.md` 一旦出现 = 任务完成 + 报告就位 + +**信号 2:host-side poll loop(在 manifest 内的 socket,不靠 macOS 通知)** + +写 `scripts/wait-for-task.sh [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 `(放后台,不阻塞对话),到时间自动出报告,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 等下次) \ No newline at end of file