dsh-sansheng-liubu/workbench/host/contract.mjs

145 lines
5.7 KiB
JavaScript
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.

// 部门 ↔ 程序的内部操作契约(方案 §6)。
//
// 四个动作是唯一的“业务事实来源”:
// dispatchTask / reportTaskResult / requestTaskInput / syncDecision
// 部门在会话里怎么说话都不影响账本;账本只认这四条结构化调用。
//
// 部门在没有自建 HTTP 通道时,用一段可解析的行内指令表达这四个动作:
// 【三省六部】{"action":"reportTaskResult","taskId":"task_…","attemptId":"att_…",…}
// 指令行必须单独成行,前缀固定、正文是单行 JSON。解析器宁可返回 null 也不猜测:
// 解析失败的行当普通文本,绝不用“看起来像”的句子更新任务状态(方案明令禁止)。
//
// 这里只做“文本 ↔ 结构化调用”的纯转换,不碰网络、不碰 store,便于单测。
export const CONTRACT_ACTION_PREFIX = '【三省六部】'
/** 四个合法动作:多一个少一个都属于“意图不明”,直接拒绝而不是猜。 */
export const CONTRACT_ACTIONS = Object.freeze([
'dispatchTask',
'reportTaskResult',
'requestTaskInput',
'syncDecision',
])
const ACTION_SET = new Set(CONTRACT_ACTIONS)
export class ContractError extends Error {
constructor(code, message, details = undefined) {
super(message)
this.name = 'ContractError'
this.code = code
if (details !== undefined) this.details = details
}
}
/**
* 从一段部门输出里取出全部契约行。
*
* 返回 { calls, invalid }:
* - calls:解析成功的调用,按出现顺序;
* - invalid:看起来像契约行但 JSON 坏了/缺 action 的行(附原文,便于在 UI 上提示重发)。
*
* 一个动作只接受一行一条。同一行里塞数组视为格式错误:批量派发必须逐条写,
* 否则“派发到一半失败”无法解释是哪一条。
*/
export function parseContractLines(text) {
const calls = []
const invalid = []
if (typeof text !== 'string' || text === '') return { calls, invalid }
const lines = text.split(/\r?\n/)
for (const raw of lines) {
const line = raw.trim()
if (!line.startsWith(CONTRACT_ACTION_PREFIX)) continue
const body = line.slice(CONTRACT_ACTION_PREFIX.length).trim()
let parsed
try {
parsed = JSON.parse(body)
} catch (error) {
invalid.push({ line: raw, reason: `JSON 解析失败:${error.message}` })
continue
}
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
invalid.push({ line: raw, reason: '契约正文必须是单个对象' })
continue
}
if (typeof parsed.action !== 'string' || !ACTION_SET.has(parsed.action)) {
invalid.push({ line: raw, reason: `未知动作:${String(parsed.action)}` })
continue
}
calls.push({ action: parsed.action, payload: parsed })
}
return { calls, invalid }
}
/** 给部门用的指令模板:只描述字段,不塞业务判断,避免模板把“已完成”写成结论。 */
const TEMPLATES = Object.freeze({
dispatchTask: {
taskId: 'task_…',
targetRoleId: 'gongbu',
idempotencyKey: '<同一任务同一意图固定不变>',
packet: { objective: '…', acceptance: ['…'], constraints: [], materialRefs: [] },
},
reportTaskResult: {
taskId: 'task_…',
attemptId: 'att_…',
reportVersion: 1,
summary: '做了什么、结果是什么',
checks: [{ name: '检查项', ok: true, detail: '证据' }],
artifactRefs: ['art_…'],
},
requestTaskInput: {
taskId: 'task_…',
attemptId: 'att_…',
reason: '缺什么、为什么必须由用户决定',
},
syncDecision: {
taskId: 'task_…',
decision: 'approve | reject | retry',
note: '可选说明',
},
})
/** 渲染成可直接贴进部门系统提示的一小段说明。 */
export function describeContract() {
const lines = [
`需要走程序的动作,请单独起一行,写作:${CONTRACT_ACTION_PREFIX}{…单行 JSON…}`,
'平台只认下面四个动作,且只认结构化字段——在正文里写“已完成”不会改变任务状态。',
]
for (const action of CONTRACT_ACTIONS) {
lines.push(`· ${action}:${JSON.stringify(TEMPLATES[action])}`)
}
return lines.join('\n')
}
/**
* 单条调用的轻量校验(字段存在性与形状)。业务级校验(归属、状态机、幂等)在 service 层,
* 这里只拦“明显没法处理”的调用,让错误尽早、可读地回到部门。
*/
export function validateContractCall(call) {
const errors = []
if (call === null || typeof call !== 'object') return ['调用必须是对象']
if (!ACTION_SET.has(call.action)) errors.push(`未知动作:${String(call.action)}`)
const payload = call.payload ?? {}
if (typeof payload.taskId !== 'string' || payload.taskId.trim() === '') errors.push('缺少 taskId')
switch (call.action) {
case 'dispatchTask':
if (typeof payload.idempotencyKey !== 'string' || payload.idempotencyKey.trim() === '') {
errors.push('dispatchTask 必须带 idempotencyKey(同一意图固定不变)')
}
break
case 'reportTaskResult':
if (typeof payload.attemptId !== 'string' || payload.attemptId.trim() === '') errors.push('reportTaskResult 必须带 attemptId')
if (typeof payload.summary !== 'string' || payload.summary.trim() === '') errors.push('reportTaskResult 必须带非空 summary')
break
case 'requestTaskInput':
if (typeof payload.reason !== 'string' || payload.reason.trim() === '') errors.push('requestTaskInput 必须带 reason')
break
case 'syncDecision':
if (typeof payload.decision !== 'string' || payload.decision.trim() === '') errors.push('syncDecision 必须带 decision')
break
default:
break
}
return errors
}