# 项目协同约定(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 场景,WHEN/THEN)→ tasks(DAG)→ testcases(case 绑定 task)。 2. 实现完成后跑门禁:`PROJECT_ROOT=. bash openspec/scripts/check_spec_coverage.sh` —— **gap 必须为 0** 才算完成;不要为过门禁编造场景。 3. 归档:变更验收后移入 `openspec/changes/archive/-chg_*`。 ## 构建与测试 - 动手前先探查现有约定(根 `package.json` scripts、tests 目录组织、启动方式), 沿用现有脚本;没有现成约定时默认:单元/集成测试用 `node --test`(零新依赖), 测试文件放 `tests/unit/<模块>/`。 - 集成测试起服务用 **30050–30099** 端口段(避开开发常驻端口),跑完即停。 - 依赖已装齐(node_modules 存在)就不要重跑 `npm ci`;必须重装时加 `--cache /tmp/npm-cache`(默认缓存目录不可写)。 ## 提交 - 格式 `(): <摘要>`,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 | ### 19 算子 → schema v2 字段映射表(chg_0013 · 闭环 learnings 候选 c) 每个算子的成功输出均含顶层 `ok:true / schema_version:"v2" / computed_at`;业务载荷挂在算子键下(`tee.* / psi.* / paillier.* / audit.* ...`)。**PHI 约定**:除 did/tee/audit/psi 4 类算子外,其余算子载荷内不含业务明文,仅含派生统计量。 | 算子 | 算法(核心) | 关键 input | 业务载荷(顶层 key)| 复用 chg | 业务场景 | 敏度 | |---|---|---|---|---|---|---| | `hello-mpc` | shamir-3pc-mock | `numbers:[int]` | `mpc.{protocol,party_count,numeric_sum}` | chg_0002/0008 | MVP 演示 | L0 | | `pir` | FNV-1a 32-bit 假名索引 | `keyword:string` | `query.{hash,length}` + `hits[]` + `hit_count` + `db_size` | chg_0002/0008 | 单点假名检索 | L1 | | `vertical-lr` | mini-batch 梯度下降 | `features:number[][]` + `labels:number[]` | `weights/bias/loss_history[]/iterations/learning_rate/rows` | chg_0002/0008 | 纵向 LR(mock)| L1 | | `scql` | secret-share 聚合 v2 | `columns/rows` | `scql.{sum,column_count,mean,per_column_sum[],share_count,part_sums[],protocol}` | chg_0002/0008 | 多方 SQL 聚合 | L2 | | `horizontal-fedavg` | fedavg-gaussian-dp-v2 | `clients:[{label,w}]` + `[epsilon,aggregation,dim]` | `fedavg.{aggregated,client_count,round_count,aggregation,dimension,algorithm,noise_scale,noise_applied}` | chg_0002/0008 | 横向联邦(DP) | L2 | | `secure-mlp` | Laplace-DP 推理 | `features:number[][]` + `[epsilon,weights,bias]` | `mlp.{predictions[],noise_scale,rows,weights_used,bias_used,epsilon,mechanism,deterministic}` | chg_0005/0008 | 神经网络推理(DP) | L2 | | `tee-inference` | TEE-mock enclave | `prompt:string` + `model:string` + `[attestation_key,verify_key]` | `tee.{attestation,response,model,prompt_length,enclave,hash_full}` + `tee.verify_code/quote`(HMAC) | chg_0005/0008 | enclave 内推理 | L2 | | `prompt-defense` | 关键词+pattern+z-score | `prompt:string` + `[signature,threshold]` | `defense.{detected,threat_level,matched_keywords[],score,pattern_hits,z_score,z_anomaly,signature_provided,signature_valid,reasons[],prompt_length,keywords_total}` | chg_0005/0008 | prompt 注入防护 | L1 | | `compliance-audit` | HMAC-SHA256 链 append/verify | append: `action/actor/user/payload`;verify: `entries[]` | append: `audit.{trail_id,action,actor,user,timestamp,compliance_score,status,prev_hash,payload_hash,chain_index,mode}`;verify: `audit.{chainValid,entries_verified,first_bad_index,mode}` | chg_0005/0008 | 不可篡改日志链 | L0 | | `paillier-he` | paillier-he-additive-v2 | `values:int[]` + `[seed]` | `paillier.{values[],ciphertexts[],sum_encrypted,sum_decrypted,plaintext_sum,homomorphic_invariant_ok,pubkey{n,g,n_squared}` | chg_0009 | 同态密文求和 | L0 | | `threshold-sig` | 2-of-3 Shamir 门限签名 | `message:string` + `shares:[{x,y}]` | `threshold_sig.{message,shares_used,share_x[],share_y[],reconstructed_secret_hex,reconstructed_signature,original_signature,signature_match,with_one_share_fails,threshold,total_shares,field_prime_hex}` | chg_0009 | 门限签名重构 | L0 | | `mpc-beaver` | beaver-mpc-triple-v2 | `x/y/a/b/c` | `mpc.{x,y,triple{a,b,c,triple_consistent},revealed_public{d,e},z,xy_ground_truth,invariant_ok,tolerance,algorithm}` | chg_0009 | Beaver 三元组验证 | L0 | | `psi` | cuckoo-psi-v2 | `set_a/set_b[]` + `hash_key` | `psi.{set_a_size,set_b_size,intersection[],size,leaked_non_intersection,algorithm}` | chg_0009 | 两方求交 | L3(PHI) | | `did-identity` | did-hmac-v2 | `method/identifier` + `[secret]` | `did.{did,method,identifier,doc,proof{type,verification_method,signature},verify_with_correct_secret,verify_with_wrong_secret,algorithm}` | chg_0009 | 身份 DID + HMAC 验签 | L1 | | `tds-connector` | tds-hmac-jwt-v2 | `contract_hash_a/b` + `[subject,scope,ttl]` | `tds.{contract_hash_match,sha256_a,sha256_b,access_token,token_type,ttl_seconds,subject,scope,algorithm}` | chg_0009 | 可信数据空间合约 | L1 | | `data-masking` | field-aware-masking-v2 | `field_type:string` + `value:string` + `[seed]` | `masking.{field_type,original_length,masked,masked_length,reversible_hash,algorithm}` | chg_0009 | 字段感知脱敏 | L2 | | `data-watermark` | zero-width-watermark-v2 | action=embed/extract + `text/payload` | `watermark.{action,text,zero_width_chars_found,extracted_payload,algorithm}` | chg_0009 | 零宽字符水印 | L1 | | `abac-policy` | abac-jsonlogic-v2 | `subject/object/action/env` + `policy` | `abac.{decision,reasons[],allow_matched_keys[],deny_matched_keys[],env_violations[],algorithm}` | chg_0009 | ABAC 策略判定 | L1 | | `model-watermark` | lsb-model-watermark-v2 | action=embed/extract + `weights/payload` | `watermark.{action,byte_count,extracted_payload,weights_length,algorithm}` | chg_0009 | 模型权重水印 | L1 | **字段约定**: - `ok:true` + `schema_version:"v2"` + `computed_at` = 顶层成功三元组(19 个算子一致) - 业务载荷 key 与算子同名(`psi.*`、`paillier.*`、`audit.*`),便于 caller 按算子路由 - `schema_version` 缺失 → 算子未升级到 v2(仅 chg_0008 之前的 9 算子起步版可能),按需 触发 `recompute_classification` / 走 schema v1 兼容路径 - 敏度 L0=公开 / L1=内部 / L2=机密 / L3=PHI(含患者 ID 等),与可信数据空间分级对齐 **业务场景对位**(learnings §明日接力.2 闭环): - 金融联合风控 chg_0010 → psi/paillier-he/threshold-sig/did-identity/mpc-beaver/compliance-audit/abac-policy(7) - 车云合规 chg_0011 → tds-connector/data-masking/horizontal-fedavg/data-watermark/abac-policy/compliance-audit/did-identity/psi/paillier-he(9) - 医疗隐私查询 chg_0013 → did-identity/tee-inference/psi/paillier-he/abac-policy/compliance-audit(6,含 MPQ独有 tee-inference) ### 已落 chg 索引(13 归档 + 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 | | chg_0013 medical_privacy_query | 医疗联合诊断 3 医院(HIPAA 等价 PHI 不出域)+ 6 算子复用 + 19 算子 schema v2 映射表 | 8e54bcd | 45 | archive/2026-10-02-chg_0013_medical_privacy_query | ### 关键文档 - `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 顶层规范