审批质询(前端)第一步:质询的类型与接口、时间线解读 approval.inquiry

- types.ts 末尾按前后端约定加 Inquiry、InquiryRequest/Response、查询与快照的类型,字段名一个不改
- api/inquiry.ts:提问(POST,不设超时,服务端自有时长上限)、列出问答、取质询引用过的查询快照(外层包不包一层都交给界面认)
- decode.ts:approval.inquiry 不再落进「未识别的事件」,解读成顶层一行「审批人质询」:标题带问题前 40 字,副标题说回答完成 / 不完整(写明哪个上限)/ 未能回答、查了几次,封存之后问的写明封存后追加;缺字段、类型不对的照实少说,不拿 0 顶查询次数
- check-decode 断言上述说法与缺字段的兜底;check-trace 加「运行停在审批时来了一条质询,相位仍是等待」:等待段不被收掉、执行时长不涨、恢复后照常跑完、每个前缀上 trace 与 decodePhase 一致
This commit is contained in:
ThearchyHelios
2026-10-05 18:46:03 +08:00
parent 14dcbe19bb
commit 23cdc986fc
6 changed files with 341 additions and 4 deletions
+24 -2
View File
@@ -1,7 +1,29 @@
/**
* 审批质询的接口(/api/runs/{run_id}/…)。现在是空的,审批质询的工作包往里加,挂在 api.inquiry 上。
* 审批质询的接口(/api/runs/{run_id}/inquiries…),挂在 api.inquiry 上。
*
* 请求函数(get / post / del……)和 ApiError 从 ./http 导入,不要从 ./client 导入:client.ts 要导入
* 这个文件把它挂到 api 上,反过来导入就成了循环(见 http.ts 开头的说明)。
*/
export const inquiry = {}
import type { InquiryList, InquiryRequest, InquiryResponse } from '../types'
import { get, qs, request, type RequestOptions } from './http'
const run = (id: string) => `/runs/${encodeURIComponent(id)}`
export const inquiry = {
/**
* 就报告提问。核查模型只读查库作答,通常要几十秒,不设超时:服务端自己有时长上限,到点按查到的结果收尾。
* 拒绝时 409 带 code(inquiry_not_open:运行没停在这张审批上、正式运行已封存、运行还在执行;inquiry_busy:这次运行
* 另有一条质询正在回答;inquiry_disabled:设置里关了审批质询),输入不合法 422 带 field,detail 都是一句中文
*/
ask: (runId: string, body: InquiryRequest) =>
request<InquiryResponse>(`${run(runId)}/inquiries`, { method: 'POST', body: JSON.stringify(body) }),
/** 这次运行的问答(封存前后的都算,按时间排)。report、unit 可选,只要某份报告、某一句的 */
list: (runId: string, filter?: { report?: string; unit?: string }, opts?: RequestOptions) =>
get<InquiryList>(`${run(runId)}/inquiries${qs(filter)}`, opts),
/**
* 质询引用过的查询快照(遮罩列已遮掉)。不是这次运行的质询引用过的工件回 404。约定没定死外面包不包一层
* {id, content},原样交回,由界面认(Inquiry.tsx 的 snapshotOf)
*/
snapshot: (runId: string, artifact: string, opts?: RequestOptions) =>
get<unknown>(`${run(runId)}/inquiries/artifacts/${encodeURIComponent(artifact)}`, opts),
}
+29 -1
View File
@@ -3274,9 +3274,37 @@ export const BUNDLE_TEXT = {
fileName: (name: string) => `${name}-可验证报告.html`,
}
/** 审批质询:审批人在批准前就待审的报告提出质询 */
/**
* 审批质询:审批人在批准前就待审的报告提问(选一句、划一段原文,或就整份报告),核查模型只读查库作答。问答写进运行
* 记录、随运行一并封存,不改动报告;封存之后只有探索运行还能问,追加在封存之后
*/
export const INQUIRY_TEXT = {
title: '审批质询',
// ---- 时间线(decode.ts 解读 approval.inquiry):标题带问题的前 40 字,副标题说回答是否完成、查了几次 ----
timeline: (question: string) => (question ? `审批人质询:${question}` : '审批人质询'),
complete: '回答完成',
/** 按已查到的结果收了尾:回答可能缺了没来得及查的部分 */
incomplete: (limit: string) => `回答不完整(${limit})`,
failed: (limit: string | null) => (limit ? `未能回答(${limit})` : '未能回答'),
/** 服务端没说成没成(缺字段)、却有回答正文:只说答了,不说完成 */
answered: '已回答',
queries: (n: number) => (n > 0 ? `查询 ${formatNumber(n)} 次` : '未执行查询'),
postSeal: '封存后追加',
limit: {
max_queries: '已达查询次数上限',
timeout_s: '已达时长上限',
max_cost_usd: '已达单次金额上限',
daily_max_usd: '已达核查每日金额上限',
} as Record<string, string>,
limitOther: '已达上限',
detail: {
question: (q: string) => `问题:${q}`,
quote: (q: string) => `原文:「${q}」`,
answer: (t: string) => `回答:${t}`,
error: (e: string) => `原因:${e}`,
model: (m: string) => `核查模型:${m}`,
},
}
/**
+53 -1
View File
@@ -3,7 +3,7 @@ import type { NodeState, RunPhase } from './trace'
import { formatDuration, formatNumber } from '../lib/format'
import {
ABSENCE_CLAIM_TEXT, CATALOG_DRIFT_TEXT, CATALOG_PATCH_TEXT, COPILOT_CONTEXT_TEXT, JUDGE_TEXT, MERGE_TEXT, RUN_SQL_CHECK_TEXT, SCHEMA_PARTIAL_TEXT, SQL_CHECK_TEXT, TYPE_LABEL,
CATALOG_TABLE_FIELD_LABEL, DUAL_CHECK_TEXT,
CATALOG_TABLE_FIELD_LABEL, DUAL_CHECK_TEXT, INQUIRY_TEXT,
claimTally,
evidenceTally, issuanceLabel, nodeTypeLabel,
} from '../lib/terms'
@@ -704,6 +704,52 @@ const JUDGE_FAILED_TITLE = '结论句裁判未能执行'
/** 审批行末尾:批的时候点了「始终允许」,这个工具之后不再问人 */
const ALWAYS_NOTE = ',并设为「始终允许 · 门控把关」'
/** 「审批人质询」那一行的标题里,问题最多带几个字(按字数,不按 UTF-16 码元) */
const INQUIRY_TITLE = 40
/**
* approval.inquiry → 一行「审批人质询」:标题带问题的前 40 字,副标题说回答是否完成、查了几次(封存之后问的另写一句)。
*
* 只认服务端给的:ok 为真才说「回答完成」,带着触顶原因的说不完整、写明是哪个上限;没说成没成(缺字段)又有回答正文的
* 只说「已回答」。查了几次认 queries,没有再认 inquiry_artifacts,两样都没有就不说次数——不拿 0 去顶。字段类型不对的
* 当没给:问题不是字符串就只写「审批人质询」
*/
function inquiryStep(d: Record<string, any>, seq: number): Step {
const T = INQUIRY_TEXT
const str = (v: unknown) => (typeof v === 'string' ? v.trim() : '')
const question = str(d.question)
const chars = [...question]
const head = chars.length > INQUIRY_TITLE ? `${chars.slice(0, INQUIRY_TITLE).join('')}…` : question
const limit = str(d.limit)
const limitText = limit ? T.limit[limit] ?? T.limitOther : ''
const answer = str(d.answer_text)
const error = str(d.error)
const state = d.ok === true ? (limit ? T.incomplete(limitText) : T.complete)
: d.ok === false || !answer ? T.failed(limitText || null) : T.answered
const runs = Array.isArray(d.queries) ? d.queries.length
: Array.isArray(d.inquiry_artifacts) ? d.inquiry_artifacts.length : null
const fine = !limit && !error && (d.ok === true || (d.ok !== false && !!answer))
const quote = str(d.quote)
const model = str(d.model)
const doc = str(d.answer_doc)
const detail = [
question ? T.detail.question(question) : '',
quote ? T.detail.quote(quote) : '',
answer ? T.detail.answer(answer) : '',
error ? T.detail.error(error) : '',
model ? T.detail.model(model) : '',
].filter(Boolean).join('\n')
return {
id: `iq-${seq}`, seq, kind: 'human', status: 'done', code: 'approval_inquiry',
level: fine ? 'info' : 'warn',
title: T.timeline(head),
sub: [state, runs != null ? T.queries(runs) : '', d.post_seal === true ? T.postSeal : ''].filter(Boolean).join(' · '),
...(detail ? { detail } : {}),
// 回答组装成的文档(数字带出处):展开区可以下钻
...(doc ? { artifact: doc } : {}),
}
}
/**
* 门控模型(工具信任档「始终允许 · 门控把关」)对一次调用的结论。team:协作团队里拦下的,
* 成员停不下来等人,这次调用不执行。没有工具名(老数据、字段缺了)就说「一次工具调用」
@@ -2112,6 +2158,12 @@ export function decodeRun(events: RunEvent[], final?: RunFinal, opts?: DecodeOpt
break
}
case 'approval.inquiry':
// 审批人在批准前就待审的报告提问(审批质询):运行停在审批上时服务端追加这一条,node_id 为空,运行本身没动、
// 报告也不改(相位照旧,见 nextPhase)。封存之后探索运行也能问,带 post_seal。一条事件就是一问一答,挂在顶层
out.push(inquiryStep(d, seq))
break
case 'catalog.drift': {
// 从发布版本发起的正式运行:发布之后数据目录有变化。只提醒、运行照常,所以是一条警告,不是失败
const drift = catalogDrift(d)
+105
View File
@@ -3690,3 +3690,108 @@ export interface ChallengeArtifact {
claims: ChallengeClaim[]
model: string | null
}
// ---------------------------------------------------------------------------
// 审批质询:审批人就待审的报告提问,核查模型只读查库作答。形状照前后端共用的接口约定(F5a / F5b 同一份),字段名一个
// 不改;回答正文、行数、触顶原因都是服务端给的,界面只排版
// ---------------------------------------------------------------------------
/** 回答停在哪个上限上:每次最多查询次数、时长、这一次的金额、核查的每日金额 */
export type InquiryLimit = 'max_queries' | 'timeout_s' | 'max_cost_usd' | 'daily_max_usd'
/** 质询的回答 */
export interface InquiryAnswer {
/** 渲染后的正文(数字已按出处换好) */
text: string
/** compose_doc 组装的文档工件:有它,正文里的数字可以点开看出处;没有(组装失败)只显示 text */
doc_artifact: string | null
ok: boolean
limit: InquiryLimit | (string & {}) | null
/** 没答成时的中文说明 */
error: string | null
}
/** 核查模型为回答执行的一次只读查询。编号是这次质询自己的,快照按质询工件接口取(遮罩列已遮掉) */
export interface InquiryQuery {
alias: string
artifact: string
sql: string
row_count: number | null
truncated: boolean
/** 数据源名 */
source: string | null
}
export interface InquiryUsage {
input_tokens?: number
output_tokens?: number
cost_usd?: number | null
calls?: number
unpriced_calls?: number
}
/** 一次质询:问的是哪份报告的哪一句(或划选的哪段原文)、问了什么、怎么答的、查了什么 */
export interface Inquiry {
/** 运行记录里那条 approval.inquiry 事件的序号;没写进运行记录时为 null */
seq: number | null
/** 什么时候问的(ISO 时间或秒级时间戳) */
at: string | number | null
/** 提问人的署名;没署名时为 null */
actor: string | null
/** 报告撰写节点 id */
report: string
/** 句子单元 id(如 u12);就整份报告提问时为 null */
unit: string | null
/** 划选的原文 */
quote: string | null
question: string
answer: InquiryAnswer
queries: InquiryQuery[]
/** 作答的核查模型 */
model: string | null
usage: InquiryUsage
/** 运行封存之后才问的(只有探索运行可以) */
post_seal: boolean
/** 提问时停在的那张审批;封存之后问的为 null */
approval_id: string | null
}
/** POST /runs/{id}/inquiries 的请求体 */
export interface InquiryRequest {
report: string
unit: string | null
quote?: string | null
question: string
/** 运行停在审批上时必填:指明是哪一张 */
approval_id?: string
}
/** POST /runs/{id}/inquiries 的答复 */
export interface InquiryResponse {
inquiry: Inquiry
/** 是否写进了运行记录 */
recorded: boolean
/** 没写进运行记录时的中文说明,否则为 null */
note: string | null
}
/** GET /runs/{id}/inquiries 的答复 */
export interface InquiryList {
items: Inquiry[]
}
/**
* GET /runs/{id}/inquiries/artifacts/{artifact}:质询引用过的查询快照,遮罩列照证据面板的规则遮掉(值写「已遮罩」)。
* 约定只说了是快照:可能是快照本身,也可能包在 {id, content} 里(同工件接口),界面两种都认
*/
export interface InquirySnapshot {
columns: string[]
rows: unknown[][]
sql: string | null
truncated: boolean
/** 结果一共几行(快照的 row_count / total_rows),不给时按 rows 的长度 */
total: number | null
/** 遮掉的列 */
masked: string[]
source: string | null
}