Files
dth/CLAUDE.md
T
xstudio agentandClaude Code a20a11bab0 docs(dth): F-2 子模块索引 + 已落 chg 索引(6 后端模块 + 6 前端 + 19 算子 + 10 chg 表格)
- 后端模块表:auth/books/shop/lms/dth.experiment/common
- 前端视图表:Login/Dashboard/OperatorList/Run/Book/Product
- 实验台算子表:9 既有 + 10 chg_0009 新增
- 已落 chg 表:9 归档(含 merge hash + e2e 数 + 归档路径)+ 1 active (chg_0010)
- 关键文档索引(learnings / dispatch-helpers / design.md / SPEC.md)

handoff §2 优先级 3 之 F-2 闭环。

Co-Authored-By: Claude Code <[email protected]>
2026-09-28 21:50:25 +08:00

103 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!-- 由 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-09-28 苏苏拍板)
### 后端模块(6)
| 模块 | 路径 | 能力 | 引入 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/dth/lms/` | students / courses / enrollments(3 子系统 + 17 e2e) | chg_0006 |
| `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 |
### 前端视图(6)
| 视图 | 路径 | 能力 | 引入 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 |
### 实验台算子(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 索引(9 归档 + 1 提案)
| 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** (active) | 3 银行联合反欺诈场景(纯算子组合,无新代码) | — | 12 (待实现) | openspec/changes/chg_0010_federated_risk_control |
### 关键文档
- `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 算子选型设计
- `openspec/SPEC.md`:实验台 + LMS + auth 顶层规范