- chg_0001_dth_scaffold (skip_coverage): openspec framework + NestJS+React+PGlite scaffold - chg_0002_sp1_experiment_platform_mvp: 6 scenarios S1-S6 + 21 perm-smoke + 16 e2e + 3 demo operators (hello-mpc/pir/vertical-lr) Sandbox task exit 0. Independent verification: check_spec_coverage.sh gap=0 PASS. Co-Authored-By: Claude Opus 4.8 <[email protected]>
50 lines
3.2 KiB
Markdown
50 lines
3.2 KiB
Markdown
<!-- 由 XStudio 沙盒模版生成;按项目实际自由改写,合并审核时一并 review -->
|
||
|
||
# 项目协同约定(ai-collab-framework · openspec)
|
||
|
||
## 空间与分支
|
||
- 本目录是**沙盒工作空间**,git 分支 `sandbox`;宿主 xstudio 工作区(容器内
|
||
`/home/ubuntu/ccWorkDir`,只读)是 `main` 主线,仅供对照。
|
||
- 所有改动在本目录内完成并 commit;**合并回 main 由宿主编排者向用户提请,
|
||
用户审核通过后才执行**——不要自行尝试。
|
||
- shell 初始 cwd 在只读的 ccWorkDir:**每条命令先 `cd` 到本空间**再执行;
|
||
临时日志/探针脚本一律写 `/tmp`,不要落进本目录。
|
||
|
||
## 写文件与持久性(V1.59 硬约束)
|
||
- **文件写入只允许落在 `/home/ubuntu/space`**(即本目录)。xstudio 的
|
||
`xstudio.file.write/edit/delete` 已按此钳制:传本目录相对路径或
|
||
`/home/ubuntu/space/...` 前缀路径,其他路径一律被拒。
|
||
- 宿主命令执行工具(`xstudio.build.run` / `xstudio.console.*`)对容器**已关闭**;
|
||
构建/测试/运行一律在本目录内用容器本地 shell 完成(npm 缓存加
|
||
`--cache /tmp/npm-cache`,测试端口 30050–30099)。
|
||
- **本空间非持久**:宿主重启清理 /tmp、或容器删除时本目录可能丢失。
|
||
因此:① 每完成一个可交付单元立即 `git commit` 到 `sandbox` 分支;
|
||
② 最终交付清单写进汇报文本(宿主据此合并审核);③ 不要把唯一副本
|
||
只留在本目录——汇报里的文件清单 + git 提交是恢复依据。
|
||
|
||
## 变更驱动流程(openspec)
|
||
1. 每个行为变更对应 `openspec/changes/chg_*`:proposal(why/scope/acceptance)
|
||
→ spec(### S<n> 场景,WHEN/THEN)→ tasks(DAG)→ testcases(case 绑定 task)。
|
||
2. 实现完成后跑门禁:`PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh`
|
||
—— **gap 必须为 0** 才算完成;不要为过门禁编造场景。
|
||
3. 归档:变更验收后移入 `openspec/changes/archive/<YYYYMMDD>-chg_*`。
|
||
|
||
## 构建与测试
|
||
- 动手前先探查现有约定(根 `package.json` scripts、tests 目录组织、启动方式),
|
||
沿用现有脚本;没有现成约定时默认:单元/集成测试用 `node --test`(零新依赖),
|
||
测试文件放 `tests/unit/<模块>/`。
|
||
- 集成测试起服务用 **30050–30099** 端口段(避开开发常驻端口),跑完即停。
|
||
- 依赖已装齐(node_modules 存在)就不要重跑 `npm ci`;必须重装时加
|
||
`--cache /tmp/npm-cache`(默认缓存目录不可写)。
|
||
|
||
## 提交
|
||
- 格式 `<type>(<scope>): <摘要>`,type ∈ feat/fix/test/docs/chore;
|
||
openspec 工件用 scope=变更号+任务号。正例:
|
||
`feat(note): 新增笔记 CRUD 与未登录拦截`、`chg_0001(T1): 设计工件`。
|
||
- **运行时产物不 commit**:build/、dist/、events.jsonl、/tmp 探针、
|
||
node_modules 等;提交前 `git status` 过一眼再 add。
|
||
- 完成前按 `xstudio-sandbox` 技能的自评审清单过一遍边界条件
|
||
(缺参删除/越权隔离/空列表/超长输入/幂等)。
|
||
|
||
## 代码
|
||
- 结构与脚手架约定见现有 `src/`;不引入新依赖前先在变更 proposal 里声明。 |