- chg_0010 federated_risk_control → archive/2026-10-02-... - chg_0011 vehicle_cloud_compliance → archive/2026-10-02-... - chg_0012 lms_multiscene_v2 → archive/2026-10-02-... - CLAUDE.md F-2 修正:LMS 实际路径 src/backend/src/lms/(旧条目写 dth/lms/ 错) - F-2 加 chg_0012 LMS v2 视图(CourseList/CourseDetail/SceneRenderer + 4 Scene) - 已落 chg 索引:12 归档 + 0 提案(chg_0010/0011/0012 三行带 merge commit + e2e 数) - 关键文档加 frc/vc/lms-v2 三份 scenario.md 引用 Co-Authored-By: Claude Code <[email protected]>
115 lines
8.7 KiB
Markdown
115 lines
8.7 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 里声明。
|
||
|
||
## dth 子模块索引(F-2 · 2026-10-02 苏苏拍板)
|
||
|
||
### 后端模块(7)
|
||
|
||
| 模块 | 路径 | 能力 | 引入 chg |
|
||
|---|---|---|---|
|
||
| `auth` | `src/backend/src/dth/auth/` | JWT 登录 + admin seed | chg_0001 |
|
||
| `books` | `src/backend/src/dth/books/` | 商品 CRUD + List/Create/Update/Remove (TypeORM-free) | chg_0007 |
|
||
| `shop` | `src/backend/src/dth/shop/` | 购物车 + 订单 + checkout | chg_0007 |
|
||
| `lms` | `src/backend/src/lms/` | students / courses / enrollments v1 + lms-v2 多场景 controller/service/module(6 子系统 + LMS v1 17 + v2 45 = 62 e2e) | chg_0006 / chg_0012 |
|
||
| `dth/experiment` | `src/backend/src/dth/experiment/` | 实验台:19 算子 + operators/operator-runs controllers + ExperimentModule | chg_0002/0005/0008/0009 |
|
||
| `common` | `src/backend/src/dth/common/` | 共享 types + utils + interceptor | chg_0001 |
|
||
|
||
### 前端视图(13)
|
||
|
||
| 视图 | 路径 | 能力 | 引入 chg |
|
||
|---|---|---|---|
|
||
| Login | `src/frontend/src/views/Login.tsx` | 用户名密码登录 + token 持久化 | chg_0004 |
|
||
| Dashboard | `src/frontend/src/views/Dashboard.tsx` | 登录后落地页(按角色路由) | chg_0004 |
|
||
| OperatorList | `src/frontend/src/views/OperatorList.tsx` | 实验台 19 算子列表 + run 触发 | chg_0004/0009 |
|
||
| Run | `src/frontend/src/views/Run.tsx` | 单算子 run 详情 + result 显示 | chg_0004 |
|
||
| Book | `src/frontend/src/views/Book.tsx` | 商品 CRUD 视图(Lite-React demo) | chg_0007 |
|
||
| Product | `src/frontend/src/views/Product.tsx` | 商品详情 + 购物车联动 | chg_0007 |
|
||
| CourseList | `src/frontend/src/views/LMS/CourseList.tsx` | LMS 课程列表 + 选课 | chg_0012 |
|
||
| CourseDetail | `src/frontend/src/views/LMS/CourseDetail.tsx` | LMS 课程详情 + scene 列表 + 进度条 | chg_0012 |
|
||
| SceneRenderer | `src/frontend/src/views/LMS/SceneRenderer.tsx` | 4 scene 类型 dispatcher(slide/quiz/sim/pbl) | chg_0012 |
|
||
| SlideScene | `src/frontend/src/views/LMS/SlideScene.tsx` | MiniMD → HTML via dangerouslySetInnerHTML | chg_0012 |
|
||
| QuizScene | `src/frontend/src/views/LMS/QuizScene.tsx` | 选择 + 简答 + 自动判分 + 完成 | chg_0012 |
|
||
| SimScene | `src/frontend/src/views/LMS/SimScene.tsx` | iframe sandbox=allow-same-origin | chg_0012 |
|
||
| PBLScene | `src/frontend/src/views/LMS/PBLScene.tsx` | 「即将推出」占位(与后端 501 文案字面一致) | chg_0012 |
|
||
|
||
### 实验台算子(19 · chg_0002 起累计)
|
||
|
||
| 算子 | 算法 | 引入 chg |
|
||
|---|---|---|
|
||
| `hello-mpc` / `pir` / `vertical-lr` / `scql` / `horizontal-fedavg` / `secure-mlp` / `tee-inference` / `prompt-defense` / `compliance-audit` | 9 既有(含 chg_0008 真算法改写) | chg_0002/0005/0008 |
|
||
| `paillier-he` / `threshold-sig` / `mpc-beaver` / `psi` / `did-identity` / `tds-connector` / `data-masking` / `data-watermark` / `abac-policy` / `model-watermark` | 10 真算法算子(schema v2) | chg_0009 |
|
||
|
||
### 已落 chg 索引(12 归档 + 0 提案)
|
||
|
||
| chg | 能力 | 主线 merge commit | e2e case 数 | 归档路径 |
|
||
|---|---|---|---|---|
|
||
| chg_0001 dth_scaffold | NestJS + React + TypeORM-free 脚手架 + admin seed | c1cf6f5 | — | archive/2026-09-28-chg_0001_dth_scaffold |
|
||
| chg_0002 sp1_experiment_platform_mvp | 实验台 MVP + 9 mock 算子 + e2e | c1cf6f5 | 16 | archive/2026-09-28-chg_0002_sp1_experiment_platform_mvp |
|
||
| chg_0003 dispatch_helpers | A-1 prep-sandbox-space.sh + A-2 setup + A-3 wait 脚本 | a94f40e | 8 | archive/2026-09-28-chg_0003_dispatch_helpers |
|
||
| chg_0004 experiment_platform_frontend | React SPA 4 views + 5 components + Vite proxy | 10acc81 | 14 | archive/2026-09-28-chg_0004_experiment_platform_frontend |
|
||
| chg_0005 experiment_platform_extend | 6 new operators + registration + 8 e2e | f1a15c4 | 27 | archive/2026-09-28-chg_0005_experiment_platform_extend |
|
||
| chg_0006 lms_bootstrap | LMS 3 子系统 + 5 场景 + 6 cases | 5c27b0f | 17 | archive/2026-09-28-chg_0006_lms_bootstrap |
|
||
| chg_0007 lite_demo_restore | 补回 lite-react book/shop demo (TypeORM-free) | df62c96 | 33 | archive/2026-09-28-chg_0007_lite_demo_restore |
|
||
| chg_0008 operator_real_algorithms | 6 算子真算法(crypto-js + secret-share + Box-Muller + HMAC) | 66d21a5 | 15 | archive/2026-09-28-chg_0008_operator_real_algorithms |
|
||
| chg_0009 sp1_more_operators | 10 算子真算法(6 大方向全覆盖,总 19 算子) | ff45f13 | 27 | archive/2026-09-28-chg_0009_sp1_more_operators |
|
||
| chg_0010 federated_risk_control | 3 银行联合反欺诈场景(纯算子组合,无新代码) | b4a1ee3 | 37 | archive/2026-10-02-chg_0010_federated_risk_control |
|
||
| chg_0011 vehicle_cloud_compliance | 50 车 × 6 步出域可追溯(tds-connector / data-masking / watermark / fedavg / abac / audit) | 7bda015 | 24 | archive/2026-10-02-chg_0011_vehicle_cloud_compliance |
|
||
| chg_0012 lms_multiscene_v2 | LMS v2 多场景(slide / quiz / sim / pbl 4 类)+ MiniMD 零依赖 + FRC 6-scene 模板 + LMS v1 重建 | 415a017 | 45 | archive/2026-10-02-chg_0012_lms_multiscene_v2 |
|
||
|
||
### 关键文档
|
||
|
||
- `docs/superpowers/learnings/`:本日复盘 + silent-exit 排查记录
|
||
- `docs/superpowers/dispatch-helpers/`:prompt-template / cache-strategy / brainstorming-openspec-mapping / prompt-protocol
|
||
- `docs/dth/sp1-more/design.md`:chg_0009 算子选型设计
|
||
- `docs/dth/frc/scenario.md`:chg_0010 金融联合风控 6 步流程 + 8 算子映射 + 9 不变性
|
||
- `docs/dth/vc/scenario.md`:chg_0011 车云数据合规 6 步流程 + 6 算子映射 + 出域 PII 清单
|
||
- `docs/dth/lms-v2/scenario.md`:chg_0012 LMS v2 多场景 4 scene payload + FRC 6-scene 模板 + MiniMD 规格 + OpenMAIC 对位
|
||
- `openspec/SPEC.md`:实验台 + LMS + auth 顶层规范 |