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