工具审批三档、智能体护栏取代固定 12 步、检查脚本分道并行

MCP / 自定义工具的审批三档(tools/trust.py)
- 平台看不出这两类工具做什么,以前审批关卡一律当它们安全、照跑不误。现在默认每次调用都等审批;
  工具页可以逐个改成「始终允许 · 门控把关」或「始终允许」,审批卡上的「始终允许」等于前者
- 门控把关:每次调用先由门控模型审一遍工具说明、参数和节点任务;判可疑、出错、超时、答不成格式,
  一律交还给人,不会变成放行。判定包进 checkpoint,审批恢复重放时不再问一遍
- agent 节点、工具节点、协作团队三处关卡都接上;团队成员停不下来等人,门控没放行的调用不执行
- 每次运行在发起时快照档位(runs.tool_trust),恢复和接着跑沿用同一份;正式运行不看档位,一律等审批;
  升级前发起的运行照旧不问——它们可能正停在某个审批上,多问一次答复就会对错号
- 接口:GET /api/tools 带 trust / trust_key,PUT /api/tools/trust;设置新增门控模型;新事件 tool.gated
- 界面:工具页三选一、审批卡「始终允许」、设置页门控模型、运行记录解码 tool.gated;
  顺手修了 MCP 工具详情 404、工具审批被驳回却显示成放行

智能体护栏(engine/guards.py),取代固定的「最多 12 步」
- 步数只留兜底:默认 100,设置里可改;以前画布自动写进节点的 12 按「没填」处理
- 同一个工具、同样的参数第二次不再执行,把上次的结果交还给它;连续 3 步拿不到新信息就收尾
- 每个节点的令牌预算(默认 200 万)和金额预算(默认不限),都可以在设置里改成不限
- 上下文用到窗口的 60% 先压缩早期的工具结果,到 85% 就收尾;临近任何一个上限先提醒模型一次
- 下游结构化校验失败时写明是上游哪个 agent 提前收了尾;复核信号带上收尾原因,
  问数据页只在真是步数用满时才给「放宽步数重跑」
- 上限在发起时快照(runs.agent_limits);升级前发起的运行一字不改走旧逻辑

检查脚本
- check-all 默认 4 道并行:量时间最多的两项互不重叠;并行时没过的最后单独重跑一遍,重跑才过的
  单列成「偶发」。16 项全量从约 21 分钟降到约 7 分钟(加上一次重跑约 10 分钟);--lanes 1 回到串行

顺带修的
- 设置接口里的 limits 改为只读:库里存着旧版设置页写进去的一份(max_agent_steps: 25),从不生效,
  却盖住了真实上限,问数据页照着错的数许诺
- test_kb 里嵌入模型那条测试不再真连 api.openai.com(代理慢时一条要等近 4 分钟)
- check-stream 读滚动容器前先等它挂上,并行跑时不再偶发

验证(沙箱):tsc 干净,生产构建通过,pytest 1655 passed(两遍),check-all 16 项检查、3562 项全过;
新增后端测试 53 条,关键逻辑做了 22 处变异验证、全部抓到。
This commit is contained in:
ThearchyHelios
2026-09-28 11:47:45 +08:00
parent e4f2693918
commit 62aac187d8
40 changed files with 2882 additions and 126 deletions
+107
View File
@@ -1125,6 +1125,113 @@ await section('报告核对 report.checked、口径卡的台账(可点击证
check('载荷缺字段也不崩,只说核对了报告', bare?.title === '核对报告' && !bare.artifact, bare?.title)
})
await section('工具门控 tool.gated(工具信任三档)', async () => {
// 契约:data = {tool, verdict: allow|escalate, reason, model, duration_ms, call_id?, agent?},node_id 是所在节点
const E = (seq, type, node_id, data = {}) => ({ seq, type, node_id, ts: 1790000000 + seq, data })
const gated = (steps) => flatten(steps).filter((s) => s.code === 'tool_gated')
const nodeOf = (steps, id) => steps.find((s) => s.nodeId === id && s.kind === 'node')
// 放行:info 级的一行,挂在 agent 节点下,接着是正常的工具调用
const allowRun = mod.decodeRun([
E(1, 'node.started', 'agent', { node_type: 'agent', label: '查档案' }),
E(2, 'tool.gated', 'agent', { tool: 'crm_lookup', verdict: 'allow', reason: '只读查询,参数正常', model: 'tiny-1', duration_ms: 820, call_id: 'c1' }),
E(3, 'tool.start', 'agent', { tool: 'crm_lookup', args: { id: 'C-1' }, call_id: 'c1' }),
E(4, 'tool.end', 'agent', { tool: 'crm_lookup', call_id: 'c1', preview: '{"name":"示例客户"}', duration_ms: 40 }),
])
const allow = gated(allowRun)[0]
check('放行:说「门控放行 <工具>:<理由>」', allow?.title === '门控放行 crm_lookup:只读查询,参数正常', allow?.title)
check('……info 级,不是提醒', allow?.level === 'info', allow?.level)
check('……挂在所在节点下面,排在工具调用前', nodeOf(allowRun, 'agent')?.children?.[0] === allow
&& nodeOf(allowRun, 'agent')?.children?.[1]?.kind === 'tool', nodeOf(allowRun, 'agent')?.children?.map((c) => c.kind).join(','))
check('……行尾写门控用的模型和耗时', allow?.meta === '门控 tiny-1 · 820 ms', allow?.meta)
// 问门控时那次模型调用已经答完了:不能在门控那几秒里还转着「思考并作答」
const thinking = flatten(mod.decodeRun([E(1, 'node.started', 'agent', { node_type: 'agent' }), E(2, 'llm.start', 'agent', { model: 'm' }),
E(3, 'tool.gated', 'agent', { tool: 'crm_lookup', verdict: 'allow', reason: '只读' })])).find((s) => s.kind === 'llm')
check('……门控一来,前面那次模型调用收成完成', thinking?.status === 'done', thinking?.status)
// 拦下(agent 节点):warn 级,接着是 human.requested,交给人批
const escEvents = [
E(1, 'node.started', 'agent', { node_type: 'agent', label: '改档案' }),
E(2, 'tool.gated', 'agent', { tool: 'mcp:demo/search', verdict: 'escalate', reason: '参数里带了删除条件', model: 'tiny-1', duration_ms: 910 }),
E(3, 'human.requested', 'agent', { mode: 'approve', tool: 'mcp:demo/search', args: {}, title: 'Agent 想调用工具 mcp:demo/search', trust_key: 'mcp:demo/search' }),
E(4, 'run.interrupted', 'agent', { payload: { kind: 'tool_approval', node_id: 'agent', tool: 'mcp:demo/search', trust_key: 'mcp:demo/search' } }),
]
const escRun = mod.decodeRun(escEvents)
const esc = gated(escRun)[0]
check('拦下:说「门控拦下 <工具>,交给人工审批:<理由>」', esc?.title === '门控拦下 mcp:demo/search,交给人工审批:参数里带了删除条件', esc?.title)
check('……warn 级', esc?.level === 'warn', esc?.level)
check('……挂在所在节点下面,后面跟着等审批的那一行', nodeOf(escRun, 'agent')?.children?.includes(esc)
&& flatten(escRun).some((s) => s.kind === 'human' && s.status === 'waiting'))
// 协作团队里拦下:成员停不下来,紧接着一条 tool_needs_approval 的 log,调用不执行。
// 两个成员并行,两条门控都拦下之后 log 才到:按工具名各认各的(按先后取最近的一条会配错)
const teamRun = mod.decodeRun([
E(1, 'node.started', 'team', { node_type: 'supervisor', label: '调研团队' }),
E(2, 'tool.start', 'team', { tool: 'crm_lookup', args: {}, agent: '研究员', call_id: 't1' }),
E(3, 'tool.start', 'team', { tool: 'weather', args: {}, agent: '分析员', call_id: 't2' }),
E(4, 'tool.gated', 'team', { tool: 'crm_lookup', verdict: 'escalate', reason: '要批量导出', model: 'tiny-1', duration_ms: 700, agent: '研究员', call_id: 't1' }),
E(5, 'tool.gated', 'team', { tool: 'weather', verdict: 'escalate', reason: '门控模型没答上来:超时', model: 'tiny-1', duration_ms: 20000, agent: '分析员', call_id: 't2' }),
E(6, 'log', 'team', { level: 'warn', code: 'tool_needs_approval', message: '研究员 想调用 crm_lookup,需要人工确认,协作节点里不执行' }),
E(7, 'log', 'team', { level: 'warn', code: 'tool_needs_approval', message: '分析员 想调用 weather,需要人工确认,协作节点里不执行' }),
E(8, 'tool.end', 'team', { tool: 'crm_lookup', agent: '研究员', call_id: 't1', preview: '没有执行:crm_lookup 这次调用需要人工确认', duration_ms: 710 }),
E(9, 'tool.end', 'team', { tool: 'weather', agent: '分析员', call_id: 't2', preview: '没有执行:weather 这次调用需要人工确认', duration_ms: 20010 }),
])
const teamRows = gated(teamRun)
const crm = teamRows.find((s) => s.title.includes('crm_lookup'))
const wx = teamRows.find((s) => s.title.includes('weather'))
check('团队里拦下:改说「门控拦下 <工具>,协作团队里不执行:<理由>」', crm?.title === '门控拦下 crm_lookup,协作团队里不执行:要批量导出', crm?.title)
check('……并行的两条按工具名各认各的:标题和折进来的原话都对得上', wx?.title === '门控拦下 weather,协作团队里不执行:门控模型没答上来:超时'
&& !!crm?.detail?.includes('研究员 想调用 crm_lookup') && !!wx.detail?.includes('分析员 想调用 weather'), `${wx?.title} / ${crm?.detail} / ${wx?.detail}`)
check('……副标题写是哪个成员调的', crm?.sub === '研究员 调用' && wx?.sub === '分析员 调用', `${crm?.sub} / ${wx?.sub}`)
check('……那条 log 折进门控那一行,不另起一行', !flatten(teamRun).some((s) => s.code === 'tool_needs_approval')
&& !!crm?.detail?.includes('协作节点里不执行'), flatten(teamRun).filter((s) => s.kind === 'note').map((s) => s.title).join(' | '))
check('……挂在团队节点下面', !!nodeOf(teamRun, 'team')?.children?.includes(crm))
// 没有门控的团队审批(ask 档)照旧:log 自己成一行
const plain = flatten(mod.decodeRun([E(1, 'node.started', 'team', { node_type: 'supervisor' }),
E(2, 'log', 'team', { level: 'warn', code: 'tool_needs_approval', message: '研究员 想调用 crm_lookup,需要人工确认,协作节点里不执行' })]))
check('……没过门控的 tool_needs_approval 照旧自己成一行', plain.some((s) => s.code === 'tool_needs_approval'))
// 拦下后交给了人(agent 节点),之后同一节点再来的 log 不改写它
const handed = mod.decodeRun([E(1, 'node.started', 'a', { node_type: 'agent' }),
E(2, 'tool.gated', 'a', { tool: 'crm_lookup', verdict: 'escalate', reason: '可疑' }),
E(3, 'human.requested', 'a', { mode: 'approve', tool: 'crm_lookup', title: '要调用 crm_lookup' }),
E(4, 'log', 'a', { level: 'warn', code: 'tool_needs_approval', message: 'x 想调用 crm_lookup' })])
check('……已经交给人工的,不会被后来的 log 改口', gated(handed)[0]?.title === '门控拦下 crm_lookup,交给人工审批:可疑', gated(handed)[0]?.title)
// 审批卡上点了「始终允许」:后端的 human.resolved 带 always(工具审批是平铺的 {tool, approved, note, always})
const resolved = (data) => flatten(mod.decodeRun([...escEvents, E(5, 'run.resumed', null, { response: data, actor: '张工' }),
E(6, 'human.resolved', 'agent', data)]))
.find((s) => s.kind === 'human')
const always = resolved({ tool: 'mcp:demo/search', approved: true, note: '', actor: '张工', always: true })
check('始终允许:审批那一行写「放行了,并设为「始终允许 · 门控把关」」', always?.title === 'Agent 想调用工具 mcp:demo/search → 张工 放行了,并设为「始终允许 · 门控把关」',
always?.title)
const once = resolved({ tool: 'mcp:demo/search', approved: true, note: '', actor: '张工' })
check('……只是通过的不带这句', once?.title === 'Agent 想调用工具 mcp:demo/search → 张工 放行了', once?.title)
const denied = resolved({ tool: 'mcp:demo/search', approved: false, note: '不许导出', actor: '张工' })
check('……工具审批被驳回写「驳回了」(以前只读 response,平铺的 approved 读不到,一律写放行)',
denied?.title === 'Agent 想调用工具 mcp:demo/search → 张工 驳回了' && !!denied.detail?.includes('备注:不许导出'), `${denied?.title} / ${denied?.detail}`)
// 缺字段:不崩,不出 undefined,不当成没翻译的记录
let bare = []
let thrown = null
try {
bare = flatten(mod.decodeRun([
E(1, 'tool.gated', null, {}),
E(2, 'node.started', 'x', { node_type: 'agent' }),
E(3, 'tool.gated', 'x', { verdict: 'allow' }),
E(4, 'tool.gated', 'x', { tool: 'crm_lookup', verdict: 'escalate', reason: null, duration_ms: 'slow' }),
E(5, 'log', 'x', { level: 'warn', code: 'tool_needs_approval' }),
]))
} catch (e) { thrown = e }
const rows = bare.filter((s) => s.code === 'tool_gated')
check('缺字段:不抛异常,每条都成一行', !thrown && rows.length === 3, thrown ? String(thrown.message) : `${rows.length} 行`)
check('……没有工具名说「一次工具调用」,没有理由就不带冒号', rows[0]?.title === '门控拦下一次工具调用,交给人工审批'
&& rows[1]?.title === '门控放行一次工具调用', rows.map((r) => r.title).join(' | '))
check('……理由、耗时不是字符串 / 数字时不拼出 undefined / null', !rows.some((r) => /undefined|null|NaN/.test(`${r.title}${r.meta ?? ''}${r.detail ?? ''}`)),
rows.map((r) => `${r.title} ${r.meta ?? ''}`).join(' | '))
check('……没有消息的 tool_needs_approval 也折进去', rows[2]?.title === '门控拦下 crm_lookup,协作团队里不执行', rows[2]?.title)
check('……不是「一条还没翻译的记录」', !bare.some((s) => s.title === '一条还没翻译的记录'))
})
await section('术语', async () => {
// 没起名的节点退到类型名,类型名跟全站同一张表
const h = mod.decodeRun([{ seq: 1, type: 'node.started', node_id: 'h', ts: 1, data: { node_type: 'human', label: 'h' } }])