145 lines
5.7 KiB
JavaScript
145 lines
5.7 KiB
JavaScript
// 部门 ↔ 程序的内部操作契约(方案 §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
|
||
}
|