dsh-sansheng-liubu/docs/verification/01-contracts.md

7.9 KiB
Raw Blame History

实施契约 v3(内部工作约定)

本文件是实施期间各模块的唯一接口约定。改动共享契约先改此文件,再改调用者。

1. Store schema v3

SanshengStore.peek():

{
  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

{
  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

{
  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

{
  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

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

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
POST /sansheng/reconcile { projectId, id, verdict }(尚书或用户)

所有写端点校验 projectId 与当前项目上下文,失败返回 4xx 与可读原因。

8. 状态投影(api.js)

每个 project 新增字段(不改顶部结构):

{
  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(扩展)。
  • 全部用隔离临时目录,不碰用户状态。