- 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]>
3.2 KiB
3.2 KiB
项目协同约定(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)
- 每个行为变更对应
openspec/changes/chg_*:proposal(why/scope/acceptance) → spec(### S 场景,WHEN/THEN)→ tasks(DAG)→ testcases(case 绑定 task)。 - 实现完成后跑门禁:
PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh—— gap 必须为 0 才算完成;不要为过门禁编造场景。 - 归档:变更验收后移入
openspec/changes/archive/<YYYYMMDD>-chg_*。
构建与测试
- 动手前先探查现有约定(根
package.jsonscripts、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 里声明。