merge sandbox/dd24a29: chg_0003 dispatch_helpers — A1 prep + A2 setup + A3 wait scripts (3 host tools, 8 cases, gate PASS)

- scripts/prep-sandbox-skills.sh: A1 host-side skill 拷贝 (跳过 symlink/template-boot-jnpf/JNPF_*)
- scripts/setup-xstudio-ai.sh: A2 host-side ai-config writer (python3 merge 不覆盖已有 providers)
- scripts/wait-for-task.sh: A3 host-side completion poller (轮询 /tmp/xstudio-sandbox/*/space/.xstudio-report.md)
- tests/e2e/dispatch_helpers.test.sh: 6 case 自检
- openspec/changes/chg_0003_dispatch_helpers/{5 工件}

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
xstudio agentandClaude Opus 4.8 committed 2026-09-28 11:18:36 +08:00
1 parent 3f5f32fd99
commit a94f40e42e
9 files changed
+917

No files matched your search

@@ -0,0 +1,39 @@
---
change_id: chg_0003
status: proposed
owner: pm@dth
stakeholders: [dev, sre]
priority: P1
target_release: v0.2
created: 2026-09-28
skip_coverage: false
---
# Change: xstudio-sandbox-dispatch 三个 host-side 辅助脚本
## Why
首次 dispatch(taskId ai-1790562657-0EF743)暴露三个真坑:沙盒拿不到 skill 资产(手搓降级骨架)/ ai-config.json 缺省值 401 重试 / 任务完成信号只走 macOS 通知 AI agent 漏接。本 chg 给出 host-side 最小修改路径。
## Who
编排 agent(host 侧)、未来 dispatch 的复用者。
## Scope
- 3 个脚本:`scripts/prep-sandbox-skills.sh`(A1)、`scripts/setup-xstudio-ai.sh`(A2)、`scripts/wait-for-task.sh`(A3)
- 不动 xstudio 内核、不重打 sandbox 镜像、不改 ai-collab-framework 门禁脚本
## Non-Goals
- 不补 ssw-jnpf-lite-react 完整 demo/shop/dashboard 业务模块(那是 chg_0005+)
- 不做 React 前端(chg_0004)
## Impact
- 新 capability `dispatch_helpers`(独立元能力)
## Acceptance
- [ ] `bash scripts/prep-sandbox-skills.sh <wsHash>` 后 `/tmp/xstudio-sandbox/<wsHash>/space/.claude/skills/ai-collab-framework/` 存在
- [ ] `bash scripts/setup-xstudio-ai.sh <workspaceRoot>` 后 `<workspaceRoot>/.xstudio/ai-config.json` 含正确 provider 配置(baseURL / authTokenEnv=ANTHROPIC_AUTH_TOKEN / model=MiniMax-M3 / ccContainer=true)
- [ ] `bash scripts/wait-for-task.sh <taskId>` 在 `.xstudio-report.md` 出现后立即打印内容并 exit 0
- [ ] 三个脚本自带 `set -euo pipefail` + `--help` 输出
- [ ] check_spec_coverage.sh gap=0
## Rollout
合并 main 即生效;host 在下次 dispatch 前手动调三个脚本即可。
@@ -0,0 +1,36 @@
---
change_id: chg_0003
owner: pd@dth
status: draft
requires_human_validation: false
---
# Spec: dispatch_helpers
## Requirement
提供 3 个 host-side bash 脚本,让下次 dispatch 不再需要手动配 ai-config / 手动 cp skill / 手动轮询 task status。
## ADDED Scenarios
### S1 prep_sandbox_skills_copies_skills
- **WHEN** host 跑 `bash scripts/prep-sandbox-skills.sh <wsHash>` 其中 wsHash 是 `/tmp/xstudio-sandbox/<wsHash>/space/` 真实存在的 sandbox
- **THEN** 脚本退出 0,且 `/tmp/xstudio-sandbox/<wsHash>/space/.claude/skills/` 下包含 `ai-collab-framework` + `ssw-jnpf-lite-react` 两个目录
- **AND** 复制过程跳过 symlink + template-boot-jnpf(>50MB)以减少空间占用
### S2 setup_xstudio_ai_writes_provider_config
- **WHEN** host 跑 `bash scripts/setup-xstudio-ai.sh <workspaceRoot>` 其中 `~/.claude/skills/` 或 `~/ssw.ini` 提供 ANTHROPIC_AUTH_TOKEN
- **THEN** `<workspaceRoot>/.xstudio/ai-config.json` 写入含 `claude-process` provider(baseURL / authTokenEnv=ANTHROPIC_AUTH_TOKEN / model=MiniMax-M3 / ccContainer=true)
- **AND** 若 ai-config.json 已有 providers 字段,**不覆盖**已有 provider,只填空缺失字段(幂等)
### S3 wait_for_task_returns_report_when_md_appears
- **WHEN** host 跑 `bash scripts/wait-for-task.sh <taskId>` 默认 timeout = 3000s
- **AND** 在 timeout 内 `/tmp/xstudio-sandbox/<hash>/space/.xstudio-report.md` 出现
- **THEN** 脚本打印报告内容并 exit 0
### S4 wait_for_task_times_out_when_md_missing
- **WHEN** host 跑 `bash scripts/wait-for-task.sh <taskId> 5` (timeout 5s)
- **AND** `.xstudio-report.md` 不存在
- **THEN** 5s 后脚本 exit 1 并打印 `TIMEOUT after 5s; check mcp__xstudio__xstudio_ai_status manually`
## UX / Interaction(UI 类变更填写)
- N/A,纯命令行脚本
@@ -0,0 +1,30 @@
# Tasks (DAG)
- id: T1
type: implementer
depends_on: []
output: scripts/prep-sandbox-skills.sh
verification: bash scripts/prep-sandbox-skills.sh --help 打印 usage;用 ls /tmp/xstudio-sandbox | head -1 拿真实 wsHash,跑脚本,再 ls /tmp/xstudio-sandbox/<hash>/space/.claude/skills/ 含 ai-collab-framework + ssw-jnpf-lite-react
- id: T2
type: implementer
depends_on: []
output: scripts/setup-xstudio-ai.sh
verification: bash scripts/setup-xstudio-ai.sh /Users/xs/Desktop/workspace/dth 退出 0;jq -e '.providers.claude-process.baseURL' /Users/xs/Desktop/workspace/dth/.xstudio/ai-config.json 非空
- id: T3
type: implementer
depends_on: []
output: scripts/wait-for-task.sh
verification: 模拟:在 /tmp/xstudio-sandbox/<hash>/space/.xstudio-report.md touch 假文件,跑 wait 验证返回
- id: T4
type: tester
depends_on: [T1, T2, T3]
output: tests/e2e/dispatch_helpers.test.sh (自检三脚本)
verification: bash tests/e2e/dispatch_helpers.test.sh 全过
- id: T5
type: qa
depends_on: [T4]
output: PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh
verification: stdout 含 PASS 且 gap=0
@@ -0,0 +1,22 @@
# spec: dispatch_helpers@chg_0003
scenarios:
- id: S1
cases: [C1_prep_copies_ai_collab_framework, C2_prep_skips_template_boot_jnpf]
- id: S2
cases: [C3_setup_writes_claude_process_provider, C4_setup_preserves_existing_providers]
- id: S3
cases: [C5_wait_returns_when_report_appears]
- id: S4
cases: [C6_wait_times_out_when_report_missing]
- id: 全部
cases: [C7_test_runner_passes_all, C8_check_spec_coverage_gap_zero]
gate:
blocking_gap_tolerance: 0
implementation_files:
- scripts/prep-sandbox-skills.sh
- scripts/setup-xstudio-ai.sh
- scripts/wait-for-task.sh
- tests/e2e/dispatch_helpers.test.sh
test_files:
- tests/e2e/
@@ -0,0 +1,90 @@
---
change_id: chg_0003
owner: qa@dth
status: draft
spec_ref: spec.md
---
# Testcases
## Cases
### C1_prep_copies_ai_collab_framework
- Scenario: S1
- Type: integration
- Priority: P0
- Given: ~/.claude/skills/ai-collab-framework 存在
- When: bash scripts/prep-sandbox-skills.sh <wsHash>
- Then: /tmp/xstudio-sandbox/<wsHash>/space/.claude/skills/ai-collab-framework/ 存在
- Automated: true
- Bound Task: T1
### C2_prep_skips_template_boot_jnpf
- Scenario: S1
- Type: integration
- Priority: P1
- Given: ~/.claude/skills/ssw-jnpf-lite-react/template-boot-jnpf 存在
- When: bash scripts/prep-sandbox-skills.sh <wsHash>
- Then: sandbox 空间内 .claude/skills/ssw-jnpf-lite-react/template-boot-jnpf 不存在(被显式 exclude)
- Automated: true
- Bound Task: T1
### C3_setup_writes_claude_process_provider
- Scenario: S2
- Type: integration
- Priority: P0
- Given: 任意 workspaceRoot;ANTHROPIC_AUTH_TOKEN 在 env 或 ~/ssw.ini
- When: bash scripts/setup-xstudio-ai.sh <workspaceRoot>
- Then: <workspaceRoot>/.xstudio/ai-config.json 的 .providers.claude-process.baseURL 非空,model 非空,authTokenEnv == "ANTHROPIC_AUTH_TOKEN"
- Automated: true
- Bound Task: T2
### C4_setup_preserves_existing_providers
- Scenario: S2
- Type: integration
- Priority: P1
- Given: workspaceRoot/.xstudio/ai-config.json 已有 anthropic-api provider
- When: bash scripts/setup-xstudio-ai.sh <workspaceRoot>
- Then: anthropic-api 段仍存在;claude-process 段是新加的(merged 不覆盖)
- Automated: true
- Bound Task: T2
### C5_wait_returns_when_report_appears
- Scenario: S3
- Type: integration
- Priority: P0
- Given: 某 wsHash,报告文件不在
- When: bash scripts/wait-for-task.sh fake-task 30,后台另一个进程在 5s 后创建 /tmp/xstudio-sandbox/<hash>/space/.xstudio-report.md
- Then: 脚本在 5s 内打印报告内容并 exit 0
- Automated: true
- Bound Task: T3
### C6_wait_times_out_when_report_missing
- Scenario: S4
- Type: integration
- Priority: P1
- Given: 报告文件永远不会出现
- When: bash scripts/wait-for-task.sh fake-task 3
- Then: 3s 后 exit 1,stderr 含 TIMEOUT
- Automated: true
- Bound Task: T3
### C7_test_runner_passes_all
- Scenario: S1, S2, S3, S4
- Type: e2e
- Priority: P0
- Given: 三个脚本 + 测试就位
- When: bash tests/e2e/dispatch_helpers.test.sh
- Then: exit 0
- Automated: true
- Bound Task: T4
### C8_check_spec_coverage_gap_zero
- Scenario: 全部
- Type: e2e
- Priority: P0
- Given: chg 工件齐备
- When: PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh
- Then: stdout 含 PASS 且 gap=0
- Automated: true
- Bound Task: T5