# 实施契约 v3(内部工作约定) 本文件是实施期间各模块的唯一接口约定。改动共享契约先改此文件,再改调用者。 ## 1. Store schema v3 `SanshengStore.peek()`: ```js { version: 3, seq: 0, // 服务端单调序号:review/dispatch/artifact/event 共用 projects: { [projectId]: ProjectBinding }, reviews: [Review], dispatches: [DispatchRecord], reworks: [ReworkRecord], artifacts: { [artifactId]: ArtifactSnapshot }, leases: { [projectId]: WriteLease }, events: [Event], } ``` ### ProjectBinding ```js { id: 'prj-xxxxxxxx', schemaVersion: 3, name, workspaceId, hostWorkspaceId, projectTreeId, workDir, roomId, bots: { lead, shangshu, gongbu }, models: { lead?, shangshu?, gongbu? }, maxReworks: 3, autoRework: true, delivery: { include: [], exclude: [] }, // ArtifactSnapshot 交付范围 submissionSeq: 0, // 成果提交代次(每项目) createdAt, updatedAt } ``` 约束(`saveProject` 内校验,抛 `SanshengStoreError`,`code` 见括号): - 同一 `roomId` 只能属于一个项目(`room-taken`)。 - 三角色 Bot 互不相同(`roles-duplicated`)。 - 同一 Bot 只能属于一个项目(`bot-taken`)。 - 已有项目升级时保留未提供的字段。 ### Review v3 ```js { id: 'rev-xxxxxxxx', seq: 17, projectId, goalId, goalRevision, kind: 'stage'|'goal', stageIndex: number|null, stageTitle, reviewSubjectDigest: string, // 验收标准+任务范围(digest.js) artifactSnapshotId: string|null, artifactDigest: string|null, submissionSeq: number, // 生成审查时的项目成果代次 verdict: 'pass'|'reject', reviewerRole: 'shangshu'|'lead'|'user', reviewerBotId, reviewerSessionId, evidence, reason, at, eventKey } ``` ### ArtifactSnapshot 见 `src/artifact.js` 的 `captureArtifactSnapshot`。必须包含:`id/projectId/goalId/scope/stageIndex/workDir/kind(baseCommit/diffDigest/manifest digest)/files[]/digest/fileCount/totalBytes/truncated/policy/createdAt`。 ### DispatchRecord ```js { id: 'dsp-xxxx', requestId, payloadDigest, bootId, projectId, roomId, goalId, goalRevision, action, stageIndex, actorBotId, actorRole, actorName, reason, status: 'prepared'|'in_flight'|'confirmed'|'rejected'|'unknown'|'cancelled', revisionAfter, nativeResult: { ok, text }, note, at, sentAt, finishedAt, reconciledBy, reconciledAt, resolvedBy, resolvedAt } ``` - `beginDispatch`:同 `requestId` + 同 `payloadDigest` 返回 `{record, replay:true}`,不再写;同 id 不同 digest 抛 `SanshengStoreError('payload-conflict')`。 - `markDispatchInFlight(id)`:发送前落盘。 - `finishDispatch(id, patch)`。 - `reconcileDispatches(bootId)`:只把 `prepared`/`in_flight` 标 `unknown`;`confirmed`/`rejected` 不动。 ## 2. digest.js - `stageDigest(goal, stageIndex)` = 阶段验收范围(stageId/title/acceptance/tasks[id,botId,task]),**不含** status/note,避免纯执行状态变化使审查无意义失效。 - `goalDigest(goal)` = objective/acceptance/constraints + 各阶段 stageDigest,**不含** status。 - `artifactDigestOf(snapshot)` = snapshot.digest。 - 兼容别名:`reviewSubjectDigest(kind, goal, stageIndex)`。 ## 3. gate.js `evaluateGoalAction({ action, actor, project, goal, reviews, members, args, reworks, artifact, projectFreshness })` - `actor.kind === 'unknown'` → 拒绝(`unknown-actor`)。 - `actor.kind !== 'bot'` → 用户放行(用户操作不是 Bot 越权;需服务端另验会话来源)。 - Main Bot → 拒绝(`main-bot`)。 - 最新判决算法:先按 `projectId/goalId/kind/stageIndex/reviewerRole` 取 `seq` 最大(无 seq 时按数组末尾);**先取最新再审摘要**,最新是 reject 就拒绝,不能跳过 reject 找旧 pass。 - 通过校验:`review.goalRevision === goal.revision`(并发前置条件)且 `reviewSubjectDigest === 当前摘要` 且 `artifactDigest === 当前 artifact.digest`(项目有 workDir 时)且 `submissionSeq === project.submissionSeq`。 - 阶段 `pass/rework`:用 stage 审查;目标 `complete`:用 goal 审查且 reviewerRole=lead;全部阶段必须 passed。 - `projectFreshness` 为 `'missing'|'broken'|'stale'` 时受治理写操作拒绝(`state-unavailable`)。 ## 4. artifact.js ```js export const DEFAULT_EXCLUDES export function deliveryPolicyOf(project) -> { include, exclude, maxFileBytes, maxFiles } export async function captureArtifactSnapshot({ project, goal, stageIndex=null, scope='stage', policy, now=Date.now() }) -> snapshot export async function verifyArtifactSnapshot({ snapshot, project, policy }) -> { ok, reason?, current } export function summarizeSnapshot(snapshot) -> { digest, kind, fileCount, totalBytes, truncated, baseCommit, diffDigest } ``` - workDir 为空:`kind:'unscoped'`,digest 稳定;`verify` 对 unscoped 返回 ok(向后兼容),但 `sansheng_review` 仍记录。 - workDir 不存在:`kind:'missing'`,digest 稳定;verify 只在两者都 missing 时 ok。 - Git:`baseCommit` (`git rev-parse HEAD`,可空)、`statusDigest`(`git status --porcelain=v1 -z`)、`diffDigest`(`git diff HEAD --binary` 的 sha256);交付范围内未跟踪文件逐个 hash。 - 非 Git:递归 manifest,排除目录/敏感文件,按路径排序,逐文件 sha256(>64MB 记 size+mtime)。 - 排除:`.git,node_modules,.venv,venv,__pycache__,dist,build,coverage,.next,.cache,.turbo,target,out,*.log,*.tmp,.env*,.npmrc,.pypirc,*.pem,*.key,*.p12,id_rsa*,credentials*`。 - 快照在服务端生成;不接受调用方提供的 hash 作为事实。 ## 5. identity.js ```js resolveActor({ dsbot, store, sessionId, isBotSession }) -> { kind: 'user'|'bot'|'unknown', trusted: boolean, sessionId, botId?, botName?, isMain?, project?, role?, reason? } ``` - 无 `sessionId` → user(host 直接调用)。 - `sessionId` 是 Bot 会话(`isBotSession(sessionId)` 或 state 索引命中)但反查不到 Bot → `unknown`(过期/损坏身份)。 - 非 Bot 会话 → user。 - Bot 命中多个项目 → `projectConflict: true`,`project` 取唯一命中;多个时 gate 拒绝(`project-conflict`)。 ## 6. Governance service(sansheng → ds-bot) 见 `docs/verification/00-baseline.md` §3.5。实现于 `src/governance.js`。 ## 7. HTTP 端点(`src/route.js`) | 方法 | 路径 | 作用 | | --- | --- | --- | | GET | `/sansheng/state?workspaceId=&sessionId=` | 状态投影;返回 `{ generatedAt, projects, current, health }` | | GET | `/sansheng/health` | 存储/DS Bot 状态新鲜度 | | POST | `/sansheng/project/resolve` | `{ workspaceId, path, title }` → `{ project }` 或 `{ missing:true }` | | POST | `/sansheng/provision` | `{ workspaceId, path, name, models, maxReworks }` → 创建项目(与工具共用核心) | | POST | `/sansheng/config` | `{ projectId, models, maxReworks, autoRework }` → 仅改本项目 | | POST | `/sansheng/control` | `{ projectId, action: pause|resume|stop }` → 调用 `rt.goalControl`(用户操作) | | POST | `/sansheng/reconcile` | `{ projectId, id, verdict }`(尚书或用户) | 所有写端点校验 `projectId` 与当前项目上下文,失败返回 4xx 与可读原因。 ## 8. 状态投影(api.js) 每个 project 新增字段(不改顶部结构): ```js { phase: 'uninitialized'|'待配置'|'待执行'|'执行中'|'待审查'|'返工中'|'待核实'|'失败'|'暂停'|'已完成', attention: [{ role, reason, next }], currentStage: { index, title, acceptance, digest, taskCounts }, submissionSeq, lastSubmission: {...}|null, reviewsHistory: [...], // 折叠历史区 roles: [ { ..., sessionId, clickable, tone, next } ], } ``` ## 9. 测试 - 基线:`node --test --test-isolation=none sansheng/test/*.test.js` - 新增文件:`artifact.test.js`、`review-v3.test.js`、`isolation.test.js`、`dispatch-v2.test.js`、`api-v3.test.js`、`client.test.js`(扩展)。 - 全部用隔离临时目录,不碰用户状态。