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

177 lines
7.9 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.

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