7.9 KiB
7.9 KiB
实施契约 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(扩展)。 - 全部用隔离临时目录,不碰用户状态。