feat(dispatch-helpers): A-2 prep-sandbox-space.sh + dispatch-preflight.sh; B-2 brainstorming↔openspec 映射; E-2 prompt 模板

A-2 prep-sandbox-space.sh:
- 修 A-1 mount 断链:拷贝 workspace 当前状态到 /tmp/xstudio-sandbox/<hash>/space/
- +force 选项覆盖已有空间
- 推断 workspaceRoot 走 last_workspace 文件兜底

A-2 dispatch-preflight.sh:
- 4 项自检:docker / 容器 up / space 可写 / .claude/skills 拷到位
- + bonus: workspaceRoot ai-config
- 自动调 prep-sandbox-space / prep-sandbox-skills / auto-setup-xstudio-ai
- 实测:ccc workspace 全部 ✅

B-2 brainstorming-openspec-mapping.md:
- design.md → chg 工件字段映射表
- naming 约定 (capability / chg_id / S 编号 / C 编号)
- chg 创建 10 步 checklist
- 与 superskills using-superpowers 冲突解决

E-2 prompt-template.md:
- 6 段 prompt 结构 (Header / Cache / Don't / 工件 / 步骤 / 汇报)
- 完整 chg_0005 实例
- 模板生成脚本占位(待下次写)

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
xstudio agentandClaude Opus 4.8 committed 2026-09-28 13:57:57 +08:00
1 parent 77337aeef4
commit 9eeb9a8030
4 files changed
+556

No files matched your search

@@ -0,0 +1,188 @@
# Brainstorming ↔ Openspec 映射指南(B-2)
> 编制:2026-09-28 · 配合 learnings §B-2
> 状态:host-side 文档;给"同时激活 brainstorming + openspec"的场景用
---
## 1. 背景
两个 skill 看起来重叠:
- **brainstorming**(superskills):设计阶段产出 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
- **ai-collab-framework**(openspec):每个 chg 产出 proposal/spec/tasks/testcases/map.yaml 五件套
实际分工:
| skill | 阶段 | 产出 |
|---|---|---|
| brainstorming | **变更前**(跨多个 chg 的整体设计) | `design.md`(一份) |
| ai-collab-framework | **每个 chg**(具体行为的 openspec 工件) | 五件套(一份/每个 chg) |
## 2. 调用顺序(必须)
```
Phase 1: brainstorming 跑 → design.md 写好 → 用户 review
↓ 批准
Phase 2: design.md 拆解成 N 个 chg,每个写 openspec 五件套
↓
Phase 3: 每个 chg 走 xstudio-sandbox-dispatch 派单
```
**关键**:brainstorming 的 design doc 不替代 chg 工件;design doc 是"前置设计 spec",chg 工件是"具体执行的 contract"。
## 3. design.md → chg 工件的映射表
| design.md 段落 | chg 工件字段 | 说明 |
|---|---|---|
| `# Spec: <capability>` 标题行 | spec.md `# Spec:` 标题 + map.yaml `# spec: <capability>@<chg_id>` | capability 名必须一致,chg_id 必须对应目录 basename |
| `## Requirement` EARS 句式 | spec.md `## Requirement` 段 | 复制保留 + 改写为 capability 级 EARS |
| `## ADDED Scenarios` (`### S<n>`) | spec.md `## ADDED Scenarios` | capability 级全局 S 编号,跨 chg 连续 |
| `## MODIFIED Scenarios` | spec.md `## MODIFIED Scenarios` | **整块从 openspec/specs/<cap>/spec.md 拷贝**再改(modality,modifies 是完整替换) |
| `## REMOVED Scenarios` | spec.md `## REMOVED Scenarios` | 含 `**Reason**` + `**Migration**` 两行 |
| `## Why` + `## Who` + `## Scope` + `## Non-Goals` + `## Acceptance` | proposal.md 同名段 | 改写为 chg 级(带 change_id frontmatter) |
| `## Impact` | proposal.md `## Impact` | 影响 capability 名(应一致) |
| 隐含的"任务列表"(脑图) | tasks.md `# Tasks (DAG)` | 把脑图转 YAML 节点(id / type / depends_on / output / verification) |
| `## UX / Interaction` | spec.md 同名段 | UI 类变更才需要,非 UI 不写 |
| 隐含的"每个 scenario 对应一个 case" | testcases.md `### C<n>_<slug>` | one-to-many 也行(map.yaml 显式声明) |
## 4. 命名约定(避免冲突)
### 4.1 capability 级 S 编号
- capability 在 `openspec/specs/<cap>/spec.md` 主 spec 已有 → 新 chg 接续最大号
- capability 是新的 → 从 S1 起
- **新 chg 用 delta 段**(`## ADDED/MODIFIED/REMOVED Scenarios`),非 delta 写法(`## Concrete Scenarios`)会有迁移提示
### 4.2 chg_id
格式:`chg_NNNN_<capability-scope>_<change-slug>`
- NNNN:四位数字,按 archive 一起扫(不重用)
- capability-scope:与 capability 名一致
- change-slug:动词/名词短语(kebab-case)
例:`chg_0003_dispatch_helpers`、`chg_0004_experiment_platform_frontend`
### 4.3 capability 名
- 单一 capability:`<scope>`(如 `experiment_platform`)
- 跨 capability 复合 chg:拆成多个 chg,不要硬塞进一个
## 5. testcases 命名约定
格式:`C<数字>_<slug>`(`C1_list_default`)
- 每个 scenario 至少 1 条 case(map.yaml 显式声明)
- one-to-many OK:`S4 → [C4_no_token_600, C7_perm_smoke_passes]`
- 数字连续,从 1 起
- 跨 chg 不重用(避免追溯混淆)
## 6. 模板速查(chg 工件最小集)
### proposal.md 最小 frontmatter
```yaml
---
change_id: chg_NNNN
status: proposed
owner: pm@team
stakeholders: [pd, tm, qa, dev]
priority: P1
target_release: v0.X
created: YYYY-MM-DD
skip_coverage: false # 纯 refactor 设 true
---
```
### spec.md 最小结构
```markdown
# Spec: <capability 名称>
## Requirement
WHEN <trigger> THE SYSTEM SHALL <response>。
## ADDED Scenarios
### S<n> <场景名>
- **WHEN** <触发动作>
- **AND** <前置条件>
- **THEN** <可观测结果>
## UX / Interaction(UI 类才填)
- 原型位置:...
- 交互决策:...
```
### tasks.md 最小结构
```markdown
# Tasks (DAG)
- id: T1
type: architect | implementer | tester | qa
depends_on: []
output: <path>
verification: <check>
```
### testcases.md 最小结构
```markdown
### C<n>_<slug>
- Scenario: S<n>
- Type: unit | integration | e2e | ux
- Priority: P0 | P1 | P2
- Given: ...
- When: ...
- Then: ...
- Automated: true | false
- Bound Task: T<n> # 必须在 tasks.md 真实存在
```
### testcases.map.yaml 最小结构
```yaml
# spec: <capability>@<chg_NNNN>
scenarios:
- id: S1
cases: [C1_<slug>, C2_<slug>]
gate:
blocking_gap_tolerance: 0
implementation_files:
- src/<module>/
test_files:
- tests/<module>/
```
## 7. 流程清单(chg 创建)
```
□ 1. 读 design.md,按"## ADDED Scenarios"分 chg(每 chg 一个 delta 段)
□ 2. mkdir -p openspec/changes/chg_<NNNN>_<slug>
□ 3. cp templates/{proposal,spec,tasks,testcases,testcases.map.yaml}.md chg_<NNNN>_<slug>/
□ 4. 改 frontmatter:
- change_id: chg_<NNNN>
- skip_coverage: true(纯基础设施/无行为变更)
□ 5. 写 spec.md:# Spec: <capability> + delta 段
□ 6. 写 tasks.md:T1=architect, T2=implementer, T3=tester (T 编号 capability 内唯一)
□ 7. 写 testcases.md:Bound Task 必须真实存在
□ 8. 写 testcases.map.yaml:scenario ↔ case 绑定
□ 9. 写 proposal.md:why/scope/acceptance
□ 10. 跑门禁:PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh
- PASS → 可 dispatch
- FAIL → 修工件
```
## 8. 与 superskills `using-superpowers` 的冲突解决
brainstorming skill 要求"设计 doc 写好后等用户批准才能 writing-plans"。
openspec 的 chg 工件是 ai-collab-framework 自带的 deliverable,不经过 superskills writing-plans。
**冲突解决**(已写在 learnings §B-3):
- 同时激活 brainstorming + openspec → 以 **openspec 工件** 为权威 approval artifact
- brainstorming 的 design doc 作为前置 spec 即可(用户批准 design.md 即视为批准 openspec chg)
- 不需要 writing-plans skill
## 9. 验证 checklist
- [x] design.md 写好 → commit `3f5f32f`
- [x] chg_0003/0004/0005 用本流程走通
- [x] check_spec_coverage.sh gap=0
- [ ] dispatch skill 文档同步更新(待 user 决策)
## 10. 相关文件
- `docs/superpowers/learnings/2026-09-28-dispatch-session.md` §B-2 / §B-3
- `docs/superpowers/specs/2026-09-28-xstudio-dispatch-improvements.md`(design doc 范例)
- `openspec/scripts/check_spec_coverage.sh` — 门禁脚本
- `~/.claude/skills/ai-collab-framework/SKILL.md` §5/§6/§7/§8 — 6 条门禁硬约定
@@ -0,0 +1,160 @@
# Dispatch Prompt 模板(E-2)
> 编制:2026-09-28 · 配合 learnings §E-2
> 状态:host-side 模板(不用模板,直接抄结构)
---
## 1. 模板使用方式
每个 dispatch 的 prompt 由 host **手工拼接**以下 6 段:
1. **Header**(必有) — 角色 + 工作目录 + 约束
2. **Cache 约定**(必 include)— `dispatch-cache-env.sh` 注入
3. **不要做的事**(必有)— `prompt-protocol.md` §2 清单
4. **chg 工件内容**(必有)— proposal / spec / tasks / testcases / map.yaml
5. **实施步骤**(按 tasks.md T 顺序)
6. **汇报约定 + 不要做的事** — `.xstudio-report.md` 格式
## 2. Prompt Header 模板
```markdown
你是 xstudio 沙盒 agent。本任务:<chg_id>_<chg_slug> —— <一句话目标>。
# 角色与约束(硬约定)
- 工作目录:**`$XSTUDIO_SANDBOX_SPACE`**(git 分支 `sandbox`,已由内核播种,主线 HEAD = <main commit hash>)。shell 初始 cwd 是只读 ccWorkDir,**每条命令先 `cd $XSTUDIO_SANDBOX_SPACE` 再执行**。
- 写文件只允许落在 `$XSTUDIO_SANDBOX_SPACE`(已 bind-mount);落工作区或 home 都被拒。
- 容器内路径:`/home/ubuntu/ccWorkDir` = 宿主工作区只读;`/home/ubuntu/space` = 本空间可写。
- 本空间非持久,**每个 task 完成后立即 git commit**。
- 不要执行 `xstudio.build.run` / `xstudio.console.*`(容器已关闭);构建/测试走容器本地 shell。
- workspace 在 `<commit>` commit(main),本空间 re-seed 后应基于此。
```
## 3. Cache 约定(cat dispatch-cache-env.sh)
直接 cat 脚本内容,详见 `scripts/dispatch-cache-env.sh`。
## 4. 不要做的事(防 host 接管硬约束)
```markdown
# 不要做的事(防 host 接管硬约束)
- 不修改 ~/.zshrc / ~/.bashrc / ~/ssw.ini / 全局 git config
- 不动 /usr/local/bin / /opt/
- 不动 macOS 系统设置
- 不写 /Users/xs/Desktop/workspace 之外的工作区
- 不 fallback 到 /tmp 或其他路径(mount 不可用就报错退出)
- 不调 xstudio.build.run / xstudio.console.*
- <chg 专属约束,如"不修改 src/backend/src/auth/" 等>
```
## 5. chg 工件内容(5 个文件逐个粘贴)
详见 `docs/superpowers/dispatch-helpers/brainstorming-openspec-mapping.md` §6。
## 6. 实施步骤(按 tasks.md T1→Tn 顺序)
每 T 含:
- **目标**:一句话
- **输出文件**:明确路径
- **验证命令**:可执行的 shell 片段
- **commit**:`feat(<scope>): T<n> <短描述>`
## 7. 汇报约定(最终必填)
`.xstudio-report.md` 模板:
```markdown
=== <chg_id> <chg_slug> ===
PASS / FAIL
改动文件清单(每文件一句话):
- <path1>: <说明>
- <path2>: <说明>
...
门禁:
- check_spec_coverage.sh: gap=N
- e2e <test>.sh: pass=N/fail=N
- tsc --noEmit: N error
git log sandbox --oneline | head -10:
- <hash> <msg>
...
是否建议合并:是 / 否(说明原因)
```
## 8. 完整 Prompt 实例(chg_0005)
```markdown
你是 xstudio 沙盒 agent。本任务:chg_0005_experiment_platform_extend —— 在 chg_0002 已落地的 3 算子基础上,新增 6 个真算法算子。
# 角色与约束(硬约定)
- 工作目录:**`$XSTUDIO_SANDBOX_SPACE`**(git 分支 `sandbox`,已由内核播种,主线 a94f40e + 1 phase-1 commit)。shell 初始 cwd 是只读 ccWorkDir,**每条命令先 `cd $XSTUDIO_SANDBOX_SPACE` 再执行**。
- 写文件只允许落在 `$XSTUDIO_SANDBOX_SPACE`(已 bind-mount);落工作区或 home 都被拒。
- 容器内路径:`/home/ubuntu/ccWorkDir` = 宿主工作区只读(main 刚合并 phase 1 + chg_0004);`/home/ubuntu/space` = 本空间可写。
- 本空间非持久,**每个 task 完成后立即 git commit**。
- 不要执行 `xstudio.build.run` / `xstudio.console.*`(容器已关闭);构建/测试走容器本地 shell。
# Cache 约定(cat dispatch-cache-env.sh 输出)
export npm_config_cache=/tmp/npm-cache
export PIP_CACHE_DIR=/tmp/pip-cache
export UV_CACHE_DIR=/tmp/uv-cache
# 不要做的事(防 host 接管硬约束)
- 不修改 ~/.zshrc / ~/ssw.ini / 全局 git config
- 不动 /usr/local/bin / /opt/
- 不写 /Users/xs/Desktop/workspace 之外的工作区
- 不 fallback 到 /tmp 或其他路径
- 不调 xstudio.build.run / xstudio.console.*
- 不动 src/backend/src/auth/(契约红线)
- 不动 src/frontend/(chg_0004 已定,本 chg 不涉及前端)
# chg_0005 五件套(写到 openspec/changes/chg_0005_experiment_platform_extend/)
## proposal.md
<... 600 字 ...>
## spec.md
<... 1300 字 ...>
## tasks.md
<... 700 字 ...>
## testcases.md
<... 1500 字 ...>
## testcases.map.yaml
<... 200 字 ...>
# 实施步骤(按 tasks.md T1→T5)
[每个 T 一段,含目标/输出/验证/commit]
# 汇报约定
完成写 $XSTUDIO_SANDBOX_SPACE/.xstudio-report.md,格式:
=== chg_0005 experiment_platform_extend ===
PASS / FAIL
...(详见上文模板)
# 注意事项
- timeoutSec=3000,约 50 分钟
- 真问题(mount 不可用 / npm 失败)回退给我,不要硬扛
```
## 9. 模板生成的工具脚本(可选)
host 可写 `scripts/render-dispatch-prompt.sh <chg_dir>` 自动化:
- 读 `openspec/changes/<chg>/proposal.md` `spec.md` `tasks.md` `testcases.md` `testcases.map.yaml`
- 拼成完整 prompt 写到 `<chg_dir>/.prompt-for-sandbox.md`
- host 可直接 `mcp__xstudio__xstudio_ai_exec(prompt=$(cat .prompt-for-sandbox.md))`
(这次没写,下次有需求再加。)
## 10. 验证
- [x] chg_0003/0004/0005 用本模板走通
- [x] sandbox agent 没误改 host 全局配置
- [ ] 模板工具脚本化(待 E-2 完整落地)
## 11. 相关文件
- `scripts/dispatch-cache-env.sh` — Cache 约定
- `scripts/dispatch-with-wait.sh` — 一键派单 + wait
- `scripts/dispatch-preflight.sh` — 派单前自检
- `docs/superpowers/dispatch-helpers/prompt-protocol.md` — "不要做"清单
- `docs/superpowers/dispatch-helpers/brainstorming-openspec-mapping.md` — chg 工件结构