Files
AgentLab/frontend/src/typesLedger.ts
T
ThearchyHelios 8d9a712eae 业务本体与标准实体:跨源键值对齐、对账共变算子、健康证据链与实体助手
- 新增标准业务实体(CanonicalEntity)模型、确定性跨源编码翻译、后台候选实体扫描与文档驱动实体智能助手
- 新增指标本体图谱(factor / reconciles_with / upstream_driver)、DAG 防环校验以及 ontology_neighbors / source_health 内置工具
- 新增跨源对账(analysis_reconcile)与滞后共变(analysis_cochange)分析算子,打通 [[h:H1]] 数据源健康证据链、报告导出与本体消融评测
- 数据目录新增「标准业务实体」视图与候选审阅工作台,口径页集成指标本体拓扑面板与端到端浏览器检查
2026-11-12 12:57:53 +08:00

1440 lines
50 KiB
TypeScript
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.
/**
* 口径账本的接口约定(docs/design/next-round/02-口径账本.md;服务端 app/ledger/view.py、issue.py、reconcile.py、certify.py)。
*
* 界面层不放逻辑:每个数的标签、整题判断、能做的动作(能不能出具、能不能自动、不能的原因、要不要先核对参数)都由服务端
* 给,界面照着画。比对在封存之后做(不在封存范围内),GET /api/runs/{id}/ledger 在比对还没出结果时答 state=pending,
* 页面按退避再取(store/ledger.ts),不靠实时流:ledger.matched 在事件总线关闭之后才追加,打开着的页面收不到。
*/
import type { FormSchema } from './typesApp'
/** 绑定的一个参数:值是这次运行查到过的遮罩值时不给值(masked),也不能拿它代填出具 */
export interface LedgerBinding {
field: string
value?: unknown
masked?: boolean
}
/** 差在哪的一条(explain_sql_diff 的条目,SQL 片段已按遮罩换过)。text 是一句中文说明 */
export interface LedgerDiffItem {
aspect?: string
a?: unknown
b?: unknown
text?: string
}
export interface LedgerDiff {
items: LedgerDiffItem[]
/** 兜底说明:两条 SQL 对不上结构,没能归纳成具体差异 */
fallback: boolean
text_diff: string[]
}
/** 一份相关口径(同一个数据源、查了同样的表,但不等价) */
export interface LedgerRelated {
caliber?: string
workflow_id?: string
version?: number
level?: string
level_text?: string
workflow_name?: string | null
node_id?: string
comparable?: boolean
reason?: string
via?: string
binding?: LedgerBinding[]
diff?: LedgerDiff | null
}
/**
* 一个数的标签(四种):
* - caliber:来自口径「X」vN(how:independent 等价已证明 / composed 助手选用)
* - related:相关口径(附差在哪),数本身是这次的推理
* - reasoning:这次的推理,没有相关的已发布口径
* - unknown:没比对(reason 写为什么)
*/
export interface LedgerLabel {
kind: 'caliber' | 'external' | 'derived' | 'assessed' | 'related' | 'reasoning' | 'unknown'
how?: 'independent' | 'composed'
source?: string
as_of?: string
stale?: boolean
rule?: { inputs?: string[]; conditions?: number; then?: number; else?: number }
assessment?: {
score?: number | null
level?: string | null
dimensions?: { name?: string; weight?: number }[]
levels?: { name?: string; min?: number }[]
}
caliber?: string
workflow_id?: string
version?: number
level?: string
level_text?: string
workflow_name?: string | null
binding?: LedgerBinding[]
related?: LedgerRelated[]
reason?: string
/** 出自哪条查询(查询快照工件);指标是 queries */
query?: string
queries?: string[]
node_id?: string
column?: string | null
card?: string
metric?: string
}
/** 一条查询的比对:proven / composed / related / none / skipped */
export interface LedgerQuery {
artifact: string
node_id?: string
source?: string
tables?: string[]
status: 'proven' | 'composed' | 'related' | 'none' | 'skipped' | string
reason?: string
note?: string
candidates: (LedgerRelated & { status?: string; how?: string })[]
/**
* 逐格比过的(服务端 ledger/match._cells,algo 4):被引用的每一列各自的结论和候选。整条(按全部引用列投影)没证明、
* 报告引用了这条查询好几列时才有;每个数的标签已经按它那一格标好,界面照标签画,不拿它重算
*/
cells?: Record<string, { status: string; reason?: string; candidates: (LedgerRelated & { status?: string; how?: string })[] }>
}
/** 整题判断(主报告):所有带标签的数都来自同一口径的同一版、参数一致时 equivalent */
export interface LedgerWhole {
equivalent: boolean
reason?: string
counts?: Partial<Record<LedgerLabel['kind'], number>>
caliber?: string
workflow_id?: string
version?: number
level?: string
level_text?: string
workflow_name?: string | null
how?: 'independent' | 'composed'
binding?: LedgerBinding[]
missing?: string[]
missing_required?: string[]
}
/** 按口径正式出具这一项:能不能(available / reason)、能不能自动(auto / auto_reason)、已经发起过的那一次(issued_run) */
export interface LedgerIssueAction {
kind: 'issue'
workflow_id: string
version: number
caliber: string
workflow_name: string
how?: 'independent' | 'composed' | null
level?: string | null
level_text: string
available: boolean
auto: boolean
reason?: string
auto_reason?: string
issued_run?: string
}
/** 入口字段(比对工件里记的那一份):核对参数的表单照它画 */
export interface LedgerField {
name: string
required: boolean
has_default: boolean
}
/**
* 看差多少(口径对账)这一项。
*
* `available` 是**这一项当前这个人能不能真的发起**(服务端按同一份资产授权判:应用授权给到「使用」、比对等价、
* 绑定没被遮;builder / admin / 关登录放行)。只有 available 为真的那一项才带着口径身份(workflow_id / version)——
* 服务端不把身份给出去的那些只是**说明**,不是操作凭据,界面也就不该拿它去发请求(真发出去入口也会 403)。
* 人读的部分(哪条查询、哪份口径、等级、差在哪、入口字段)照旧原样给。
*/
export interface LedgerReconcileAction {
kind: 'reconcile'
query: string
caliber: string
/** 能不能真的发起对账;false 时下面两样一定没有 */
available: boolean
/** 要对账的那一版口径:只有 available 为真时才有 */
workflow_id?: string
version?: number
node_id?: string
workflow_name?: string | null
level_text: string
/** 参数是推断的、不全的、带遮罩值的:要人先核对(check_reason 是原因) */
needs_check: boolean
check_reason?: string
binding: LedgerBinding[]
/** 两条 SQL 对不上结构:多半要人选对照的指标 */
fallback: boolean
fields?: LedgerField[]
}
export type LedgerAction = LedgerIssueAction | LedgerReconcileAction
/** 按口径出具过的一次正式运行。tier_text 是「完整出具 / 降档出具 / 不予出具」,运行没结束时为空 */
export interface LedgerIssued {
run_id: string
status: string
end_reason?: string | null
workflow_id: string
version: number
tier?: string | null
tier_text?: string | null
auto: boolean
created_at?: string | null
}
/** 对账卡上的一组对照:这次 / 口径 / 差值 / 相对差各是哪个指标 */
export interface LedgerReconcileGroup {
label: string
ours: string
caliber: string
diff: string
rel: string
}
/** 对过的一次账 */
export interface LedgerReconciled {
run_id: string
status: string
query?: string
caliber?: string
workflow_id?: string
version?: number
/** binding:按比对时的参数;checked:人核对过的参数 */
inputs_from?: 'binding' | 'checked' | string
rows?: number[] | null
card?: string
groups?: LedgerReconcileGroup[]
created_at?: string | null
/** 「说明有用 / 看不懂」(服务端 ledger/feedback.feedback_of):看的这个人最后一次给的、各几个人 */
feedback?: LedgerFeedback
}
export type LedgerFeedbackVerdict = 'useful' | 'unclear'
/** 对账结果上的反馈:mine 是看的这个人最后一次给的(没给过为空),useful / unclear 是各几个人(每人只算最后一次) */
export interface LedgerFeedback {
mine?: LedgerFeedbackVerdict | null
useful: number
unclear: number
}
/** POST /api/ledger/answers/{run}/reconcile/{对账运行}/feedback 的答复 */
export interface LedgerFeedbackOut {
run_id: string
feedback: LedgerFeedback
}
/**
* 答案身上的召回标记(GET /runs/{id}/ledger 的 recall,服务端 ledger/recall.answer_marks;细案做法 7「依据有变」「已按 vN
* 核对,不影响」)。几种 state 都可能带:没比对过、不比对的答案照样可能被标依据有变。不放数、表名、取值
*/
export interface LedgerRecallMarks {
/** 口径升版后召回重算、数没变:在这个答案上记的「已按 vN 核对,不影响」 */
checked?: {
workflow_id?: string | null
workflow_name?: string | null
from_version?: number | null
to_version?: number | null
recall_run?: string | null
changed?: boolean
at?: string | null
/** 行序不定、没能核对的那几项(服务端 ledger/recall.settle):不算进「不影响」 */
row_order_metrics?: string[]
}[]
/** 依据有变:kind 是 catalog(目录里影响数字的项被驳回或修改)/ structure(表结构)/ values(新码值)/ catalog_edit */
basis?: { kind?: string | null; items?: number; new_errors?: number; at?: string | null }[]
/** 看的这个人手上、说的是这个答案的 recall 待办(还没处理的) */
tasks?: { id: string; reason?: string; to_version?: number | null }[]
}
export interface LedgerCaliber {
caliber: string
workflow_id: string
version: number
level?: string
graph_hash?: string | null
workflow_name?: string | null
level_text: string
}
/**
* GET /api/runs/{id}/ledger。state:matched 比对过;pending 正在比对(或刚跑完、封存完就比);ineligible 这次运行不比对
* (reason 写为什么);unreadable 比对记录读不出
*/
export interface RunLedger {
run_id: string
state: 'matched' | 'pending' | 'ineligible' | 'unreadable'
reason?: string
/** 「封存后比对,不在封存范围内」 */
note?: string
artifact?: string
algo?: string
trigger?: string
retro?: boolean
matched_at?: string | null
post_seal?: boolean
/** 事后补比的:按现在的口径回看 / 按之后发布的口径回看 */
retro_note?: string
calibers?: LedgerCaliber[]
queries?: LedgerQuery[]
reports?: Record<string, { labels: Record<string, LedgerLabel> }>
primary?: string | null
whole?: LedgerWhole
actions?: LedgerAction[]
issued?: LedgerIssued[]
reconciled?: LedgerReconciled[]
recall?: LedgerRecallMarks
}
/** 证据片段接口(GET /runs/{id}/evidence/segments/{seg})的 ledger 键:这个片段的标签和比对的来历 */
export interface SegmentLedger {
label: LedgerLabel
artifact?: string
algo?: string
trigger?: string
retro?: boolean
matched_at?: string | null
post_seal?: boolean
note?: string
retro_note?: string
}
/** POST /api/ledger/answers/{run}/issue 的答复:created 为假是同一次已经发起过、交回那一次 */
export interface LedgerIssueOut {
run_id: string
created: boolean
issued: LedgerIssued
}
/** POST /api/ledger/answers/{run}/reconcile 的请求体 */
export interface LedgerReconcileIn {
query: string
workflow_id: string
version: number
inputs?: Record<string, unknown>
confirm?: boolean
pairs?: { ours: string; metric: string }[]
}
export interface LedgerReconcileOut {
run_id: string
reconciled: LedgerReconciled
}
/** 认不出列怎么配时 409(ledger_reconcile_needs_pairs)另带的选项 */
export interface LedgerPairOptions {
columns: string[]
metrics: { id: string; name: string; unit?: string }[]
/**
* 预选的对照(服务端 ledger/reconcile._suggested):这一列单独比和口径取数的某一列等价(逐格证明了),口径卡上只读那一格的
* 指标。界面照它预选、人可以改;老服务端不给
*/
suggested?: { ours: string; metric: string }[]
}
// ---------------------------------------------------------------- 认证队列(可沉淀的问题)
export interface CertifyTurn {
run_id: string | null
conversation_id?: string | null
turn_id?: string | null
question: string
}
export interface CertifyFrozen {
workflow_id: string
name: string
status?: string
published_version?: number | null
}
/** 三种来源:确定性重复(SQL 形状相同)、问题聚类、被反复用的答案 */
export interface CertifyItem {
id: string
kind: 'shape' | 'cluster' | 'reused'
question: string
turns: CertifyTurn[]
frozen_into?: CertifyFrozen[]
// shape
source?: string
shape?: string
runs?: number
conversations?: number
params?: { index: number; distinct: number }[]
constants?: number
related?: { caliber?: string; workflow_id?: string; version?: number; level?: string }[]
representative?: { run_id: string; query?: string }
peers?: string[]
// cluster
count?: number
// reused
uses?: { exports: number; app: boolean; extracted: boolean; canvas: boolean }
}
export interface CertifyQueue {
items: CertifyItem[]
considered: { runs: number; matched: number; questions: number }
threshold: { runs: number; conversations: number; exports: number }
embedder?: unknown
}
/** 固化成口径草稿(POST /copilot/from-run,freeze: true)的答复 */
export interface FreezeOut {
workflow_id: string
name: string
nodes: number
edges: number
params: string[]
metrics: string[]
sources: CertifyTurn[]
}
// ---------------------------------------------------------------- 口径目录 / 试跑
export interface CaliberMetric {
id: string
name?: string
unit?: string
decimals?: number
format?: string
/** 公式(formula)、外部常量(external)、单元格条件规则(rule)、评估(assessment) */
kind?: string
grain?: string
time_field?: string
numerator?: string
denominator?: string
dimensions?: string[]
filters?: string[]
contract?: Record<string, unknown>
/** 定义卡:文字定义、范围、排除项、负责人、生效日期、引用 */
definition?: { text?: string; scope?: string; exclusions?: string[]; owner?: string; effective_from?: string; citations?: unknown[] }
params?: { name: string; type: string; default?: unknown; min?: number; max?: number }[]
}
/** GET /api/ledger/calibers:一份已发布口径卡的可调用描述(不返回 SQL、不返回参数值) */
export interface CaliberDescriptor {
workflow_id: string
workflow_name: string
version: number
level: string
graph_hash?: string | null
semantic_hash?: string | null
card: { node_id: string; title: string; caliber?: string | null; caliber_version?: string | null }
metrics: CaliberMetric[]
entry_schema: FormSchema
composable: boolean
compose_reason?: string | null
dependencies: {
sources: string[]
tables: string[]
catalog_versions?: Record<string, unknown> | null
schema_versions?: Record<string, unknown> | null
}
issuance: {
level: string
auto_issue: boolean
requires_independent_proof: boolean
side_effects?: string | null
reasons: string[]
}
}
export interface ValidationCheck {
code: string
status: 'pass' | 'fail' | 'unknown'
detail: string
metric_id?: string
name?: string
}
export interface QualityReport {
status: 'pass' | 'fail' | 'unknown'
checks: ValidationCheck[]
}
export interface CaliberTrialMetric extends CaliberMetric {
quality?: QualityReport
masked?: boolean
value?: unknown
rendered?: string
}
/** POST /api/ledger/calibers/{wf}/{version}/{node}/trial:按固定版本试跑一次 */
export interface CaliberTrialOut {
validation?: QualityReport
run_id: string
status: string
output?: Record<string, unknown> | null
error?: string | null
metrics: CaliberTrialMetric[]
/** 这次试运行各取数节点读到的表;旧服务端没有 */
queries?: DraftTrialQuery[]
}
// ---------------------------------------------------------------- 从业务文档起草口径
/**
* 草稿的细状态(app/ledger/docdraft.STATUSES):起草中 → 待确认问题 / 待接数据路径 / 待签字发布 → 已接上;
* 另有已驳回。界面不再逐个画这些状态,按 CaliberDraftStage 折成四种阶段;细状态留在标签的悬停提示里。
* ready 表示图已经生成、没有未决问题,可以试运行、可以签字发布;questions_open 也有图和数,
* 只是还没清完问题,不阻断试运行。path_pending 是旧路径:图还没生成,取数只能来自一次真实运行。
*/
export type CaliberDraftStatus = 'drafting' | 'questions_open' | 'path_pending' | 'ready' | 'attached' | 'rejected' | 'failed'
/**
* 界面上的阶段(服务端 stage):起草中 / 待审 / 已丢弃 / 失败。ready、questions_open、path_pending、attached
* 都归「待审」;细状态仍照实给,需要说清楚时用 status。
*/
export type CaliberDraftStage = 'drafting' | 'review' | 'discarded' | 'failed'
/** 一条引用:逐字原文、原文所在段落(chunk)、段号、span 是原文里的 [start, end) */
export interface DraftCitation {
chunk: string
document_id?: string
/** 原文所在段落的段号(1 起) */
ordinal?: number
quote: string
span?: [number, number]
}
/** 一条指标的定义(docdraft.DEFINITION_FIELDS) */
export interface DraftDefinition {
text?: string
scope?: string
exclusions?: string[]
owner?: string
effective_from?: string
citations?: DraftCitation[]
}
export interface QuerySemantics {
version: 1
enabled: boolean
aliases: string[]
grain: string
aggregation: string
time: null | { start: string; end: string; timezone: string; basis: 'calendar_day' | 'production_day'; periods: ('day' | 'month')[]; description: string }
entities: { field: string; label: string; entity_key?: string | null; members: { value: string; label: string; aliases: string[] }[] }[]
}
export type OntologyLinkKind = 'factor' | 'reconciles_with' | 'upstream_driver'
export type OntologyFactorRole = 'numerator' | 'denominator' | 'multiplier' | 'addend' | 'subtrahend' | 'component'
export type OntologyStatus = 'proposed' | 'verified' | 'confirmed' | 'rejected'
export interface MetricOntologyTarget {
workflow_id: string
card_id: string
metric_id: string
version?: number
}
export interface MetricOntologyLink {
id?: string
kind: OntologyLinkKind
target: MetricOntologyTarget
status?: OntologyStatus
source?: 'human' | 'rule' | 'docdraft' | 'ai' | string
role?: OntologyFactorRole
entity_key?: string
lag_periods?: number
abs_tol?: number
rel_tol?: number
rationale?: string
citations?: Record<string, unknown>[]
}
export interface CanonicalEntityMember {
value: string
label: string
aliases: string[]
source_codes?: Record<string, string>
}
export interface CanonicalEntityBinding {
id?: string
source_id?: string | null
source_name: string
table_name: string
column_name: string
status: OntologyStatus
source: 'human' | 'rule' | 'ai' | 'profile' | string
note?: string
reason?: string
updated_at?: string
updated_by?: string | null
}
export interface CanonicalEntityCaliberParam {
id?: string
workflow_id: string
card_id?: string
param_name: string
status: OntologyStatus
source: 'human' | 'rule' | 'ai' | 'profile' | string
note?: string
}
export interface CanonicalEntity {
id: string
key: string
label: string
description: string
aliases: string[]
members: CanonicalEntityMember[]
bindings: CanonicalEntityBinding[]
caliber_params?: CanonicalEntityCaliberParam[]
version: number
created_by?: string | null
updated_by?: string | null
created_at?: string | null
updated_at?: string | null
}
export interface WorkflowOntologyMetric {
metric_id: string
name: string
unit: string
contract?: Record<string, unknown> | null
links: MetricOntologyLink[]
lineage: { node_id?: string; source: string; tables: string[] }[]
}
export interface WorkflowOntologyCard {
workflow_id: string
workflow_name: string
version: number
card_id: string
title: string
caliber: string
sources: string[]
tables_by_source: Record<string, string[]>
metrics: WorkflowOntologyMetric[]
}
export interface WorkflowOntologyEdge {
id: string
kind: OntologyLinkKind
status: OntologyStatus
source: string
role?: OntologyFactorRole | null
entity_key?: string | null
lag_periods?: number
abs_tol?: number | null
rel_tol?: number | null
rationale?: string
from: { workflow_id: string; version: number; card_id: string; metric_id: string }
to: { workflow_id: string; version?: number | null; card_id: string; metric_id: string }
}
export interface WorkflowOntology {
workflow_id: string
version: number
cards: WorkflowOntologyCard[]
edges: WorkflowOntologyEdge[]
issues: { level: string; code: string; message: string; node_id?: string | null; field?: string | null }[]
}
export interface OntologyGraph {
cards: WorkflowOntologyCard[]
edges: WorkflowOntologyEdge[]
entities: CanonicalEntity[]
table_bridges?: Record<string, unknown>[]
}
export interface EntityAttachmentOut {
attachment_id: string
title: string
mime: string
char_count: number
chunk_count: number
saved_to_kb: boolean
document_id?: string | null
collection?: string | null
}
export interface EntityPatchChange {
id: string
op: 'upsert_entity' | 'upsert_binding' | 'remove_binding' | 'upsert_member' | 'upsert_caliber_param' | string
entity_key: string
entity_label: string
summary: string
before?: unknown
after?: unknown
reason: string
op_payload: Record<string, unknown>
}
export interface EntityApplyPatchOut {
applied_count: number
created_entities: number
updated_entities: number
bindings_changed: number
caliber_params_changed: number
members_changed: number
entities: CanonicalEntity[]
problems?: string[]
}
export interface EntityAssistantMessage {
role: 'user' | 'assistant'
content: string
}
export interface EntityAssistantRequest {
messages: EntityAssistantMessage[]
source_ids?: string[]
focus_entity_key?: string | null
attachment_ids?: string[]
document_ids?: string[]
pending_ops?: Record<string, unknown>[]
}
export type EntityAssistantEvent =
| { type: 'text'; delta: string }
| {
type: 'query'
source: string
sql: string
columns: string[]
rows: unknown[][]
row_count: number
truncated: boolean
error?: string | null
}
| {
type: 'proposal'
changes: EntityPatchChange[]
expected_versions: Record<string, number>
}
| { type: 'done'; usage?: { input_tokens?: number; output_tokens?: number }; queries?: number }
| { type: 'error'; code?: string; message: string }
export interface EntityDiscoveryJob {
id: string
status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted' | string
source_ids: string[]
document_ids: string[]
attachment_ids: string[]
note: string
phase: string
summary: {
sources_scanned?: number
source_names?: string[]
tables_scanned?: number
columns_scanned?: number
workflows_scanned?: number
documents_scanned?: number
doc_titles?: string[]
chunks_scanned?: number
model_id?: string
step_index?: number
step_total?: number
progress_pct?: number
model_chars?: number
ops_detected?: number
candidate_keys?: string[]
applied_count?: number
created_entities?: number
updated_entities?: number
proposed_bindings?: number
proposed_params?: number
added_members?: number
skipped_count?: number
skipped_reasons?: string[]
touched_entities?: { id: string; key: string; label: string }[]
}
error?: string | null
started_by?: string | null
started_at?: string | null
finished_at?: string | null
created_at?: string | null
updated_at?: string | null
}
export interface EntityDiscoveryActiveOut {
job: EntityDiscoveryJob | null
latest: EntityDiscoveryJob | null
}
export interface SemanticInventory {
version: number
note: string
warnings?: { document_id: string; line: number; quote: string; reason: string }[]
items: { id: string; name: string; kind: 'input' | 'metric'; section: string; formula: string; policy: string;
status: 'definition_only' | 'unavailable'; dependencies: string[]; implementation: string;
fields: Record<string, string>; source: { document_id: string; line: number; span: number[]; quote: string } }[]
rules: { document_id: string; section: string; text: string; line: number; span: number[] }[]
}
/** 草稿里的一条指标:业务定义 + 取数表达式;取数 SQL 在草稿图上(CaliberDraft.sql),这里不返回。 */
export interface DraftMetric {
source_definition_id?: string
semantic?: QuerySemantics
links?: MetricOntologyLink[]
id?: string
name: string
synonyms?: string[]
unit?: string
/** 小数位 */
decimals?: number
/** 指标表达式,形如 cell(nodes.fetch_1, 0, '列');一组取数时节点 id 是 fetch */
expression?: string
contract?: Record<string, unknown>
/** 粒度,如「日」「订单行」 */
grain?: string
/** 业务时间字段的业务叫法 */
time_field?: string
filters?: string[]
numerator?: string
denominator?: string
dimensions?: string[]
definition?: DraftDefinition
open_questions?: string[]
/**
* K04 的业务字段:统计时间口径、退款处理。指标声明了它们,取数 SQL 上的受控绑定才跟着走;
* 界面按 binding.editable_fields 的 value_labels 把机器值翻成给人看的说法,不直接显示这两个键名
*/
time_role?: string
refund_rule?: string
}
/** 草稿图的入口字段:发布后按这些字段收参数 */
export interface DraftEntryField {
name: string
type: string
required: boolean
default?: unknown
description?: string
}
/**
* 试运行的状态:还会缺必填入口字段(needs_input),这时不跑,等人填了再发起;needs_input 没有 run_id。
*/
export type DraftTrialStatus = 'running' | 'succeeded' | 'failed' | 'needs_input' | 'stale'
/** 起草后自动发起的那次只读试运行(draft.payload.trial) */
export interface DraftTrial {
run_id: string
status: DraftTrialStatus
error?: string
version?: number
graph_hash?: string
execution_hash?: string
inputs_hash?: string
}
/** GET /api/ledger/drafts/{id}/trial 的一条:name 和 rendered 一一对应 */
export interface DraftTrialMetric {
quality?: QualityReport
masked?: boolean
id: string
name: string
value?: unknown
rendered?: string
}
/**
* 一次试运行里某个取数节点读到的一张表:列头、前几行、总行数;截断时只带回前若干行,
* 遮罩过的格子在 rows 里已经是「已遮罩」这样的字样,页面照原样显示。
*/
export interface DraftTrialQuery {
node_id: string
/** 这张表是查还是别的工具拿到的(旧服务端可能没有) */
tool?: string
/** 取数用的数据源 */
source?: string
columns: string[]
rows: unknown[][]
total_rows: number
/** 只带回了前若干行 */
truncated?: boolean
source_truncated?: boolean
preview_truncated?: boolean
/** 遮罩过的列名;格子本身已经是遮罩后的字样 */
masked?: string[]
}
/** GET /api/ledger/drafts/{id}/trial:这次自动试运行的状态和每个指标的值;POST 同一个路径按填好的入口字段再发起一次 */
export interface DraftTrialOut {
validation?: DraftTrialValidation
run_id: string
status: DraftTrialStatus
metrics: DraftTrialMetric[]
/** 这次试运行各取数节点读到的表;旧服务端和旧草稿没有 */
queries?: DraftTrialQuery[]
error?: string | null
}
/**
* 试跑响应里的 validation。它不是一份固定的质量报告:服务端按分支给不同的东西——成功时是质量结论
* (status + checks),另并进这次试跑对应的**验证记录**一段(K05 的 record / covers_current / note);
* stale、needs_input、running 这些分支可能只有其中一段,甚至只有 note(老服务端也可能什么都不给)。
*
* 所以按**联合形状**读:status 缺席就是「没有质量结论」,不能当成通过(也不写成未知通过);covers_current
* 可能是 null(调用方没有当前依据),只有 === true 才算覆盖。质量结论自己走 QualityReport 的类型,
* 由页面按 status 认全之后才交给质量报告那块画。
*/
export interface DraftTrialValidation {
/** 这一段自己的格式版本(服务端新加的;认不得就照实当没有) */
schema_version?: number
/** 这一次执行是怎么结束的(succeeded / failed / running / needs_input / stale) */
execution?: string
status?: 'pass' | 'fail' | 'unknown'
checks?: ValidationCheck[]
/** 这次试运行对应的验证记录;没有就是 null(缺证据不能算验证通过) */
record?: DraftValidationRecord | null
/** 这条记录还覆不覆盖当前定义/绑定:只有 === true 才算覆盖,null 是判不了 */
covers_current?: boolean | null
/** 服务端就这一段的一句说明(例如「这次试运行还没有留下可对应的验证记录」) */
note?: string
}
/** 带独立期望试运行的那一份:指标要逐条给全卡指标,来源是三种之一 */
export interface DraftExpectIn {
metrics: Record<string, unknown>
source?: DraftExpectationSource
sample_id?: string
sample_version?: string
note?: string
}
/** 被丢弃的条目和原因(含 SQL 痕迹、引用核对不上) */
export interface DraftDropped {
name: string
reason: string
}
/** 草稿和已发布口径的对齐结果:新的、已有出处的、和现有口径定义不同的 */
export interface DraftAlignment {
new: string[]
duplicate: { name: string; workflow_id?: string; version?: number; node_id?: string }[]
conflict: { name: string; workflow_id?: string; version?: number; reason?: string }[]
}
/** 起草时用了哪份文档的哪些段落 */
export interface DraftDocument {
document_id: string
title: string
chunk_ids: string[]
}
/** GET /api/ledger/drafts 的一条:只有计数和状态,正文用 GET /api/ledger/drafts/{id} 看 */
export interface CaliberDraftSummary {
definition_count?: number
id: string
title: string
status: CaliberDraftStatus
/** 服务端算的界面阶段;旧服务端没有,页面按 status 推 */
stage?: CaliberDraftStage
metric_count: number
question_count: number
workflow_id: string | null
created_at: string | null
error: string | null
}
/** 起草轮次和覆盖情况:多轮续跑时每轮更新,covered 是已经起草出的指标名数,uncovered 是还没覆盖的 */
export interface DraftProgress {
round: number
covered: number
uncovered: number
}
/** 发布前检查的一项:服务端从图和试跑状态算出来,只读,不拦人 */
export interface DraftCheck {
key: string
label: string
ok: boolean
detail?: string
}
/** 草稿图里一组取数:一条 SQL 出哪几个指标(metric_ids 对应 DraftMetric.id) */
export interface DraftGroup {
sql: string
entry_fields?: DraftEntryField[]
metric_ids?: string[]
}
/** 草稿图上能写的口径卡:多张时 PATCH 要指明改哪一张(card_id) */
export interface DraftCardRef {
id: string
title: string
}
/** 按字段改一处(K03):op 只有 set / remove,path 是白名单里的字段路径,位置由 metric_id 定,不用数组下标 */
export interface DraftOperation {
op: 'set' | 'remove'
metric_id: string
path: string
/** 只有 set 才有:写 '' 是「声明成空」、数组整份设置;remove 不接受 value */
value?: unknown
}
// ---------------------------------------------------------------- K04 业务绑定能力(服务端能力描述)
/** 一个能按字段改的业务定义:机器值 + 给人看的说法 */
export interface DraftEditableField {
field: string
label: string
values: string[]
/** 机器值 → 界面上写的说法 */
value_labels: Record<string, string>
help: string
}
/** 一个取数节点上「定义 vs 取数实现」的判定结果(aligned / needs_update / unsupported / not_declared) */
export interface DraftBindingNode {
node_id: string
status: string
reason: string
/** 该做什么:none / sync / author / manual */
fix: string
declared: Record<string, string>
values: Record<string, string>
metrics: string[]
binding_fingerprint?: string
}
/**
* GET /api/ledger/drafts/{id} 的 binding(K04):能按字段改哪些业务定义、允许值、现在的值、定义和取数实现的
* 同步状态、不支持时的原因和该做什么。**不给模板和 SQL**;aligned 只说定义和实现同步,不等于验证通过。
*/
export interface DraftBinding {
editable_fields: DraftEditableField[]
/** 现在的业务值:字段 → 值(各取数节点里最先出现的那一个) */
current: Record<string, string>
status: 'aligned' | 'needs_update' | 'unsupported' | 'unbound' | string
reason: string
fix: string
/** 这次判定涉及哪些指标(metric_id) */
metrics: string[]
checked: boolean
/** 每条指标声明的业务值:metric_id → {字段: 值}(工作台按它算「改这一项影响哪几条指标」) */
metric_values: Record<string, Record<string, string>>
unsupported_reason?: string
binding_fingerprints?: Record<string, string>
nodes?: DraftBindingNode[]
/** 只有变更回执里的那一段有:这一次在同一事务里把取数 SQL 也改过来了 */
synced?: boolean
}
// ---------------------------------------------------------------- K05 / K06 验证与审阅
/**
* 一条验证记录的状态。**没有 pass / verified 这种状态**:matched 只是「这一次和这份期望对得上」,
* observed 是「跑了、取了数,但没有独立期望」,都不能说成验证通过(结论看 DraftValidationSummary.verdict)。
*/
export type DraftValidationStatus = 'matched' | 'mismatched' | 'observed' | 'unverified' | 'failed'
/** 期望来自哪里:人工确认 / 固定夹具 / 独立计算。不能拿当前 SQL 的结果抄一份当标准答案 */
export type DraftExpectationSource = 'human_confirmed' | 'fixture' | 'independent_computation'
/** 验证总情况里的结论(服务端现算):verified 要「有独立期望对得上」且「有覆盖它的认证审阅」 */
export type DraftValidationVerdict = 'none' | 'stale' | 'verified' | 'rejected' | 'mismatched' | 'failed' | 'observed' | 'unverified'
/** 这条记录上最新的一次审阅决定(认证主体、确认范围、所审依据) */
export interface DraftValidationReview {
id: string
draft_id: string
record_id: string
workflow_id?: string | null
decision: 'confirmed' | 'rejected' | string
actor?: string | null
/** 主体是不是认证过的(关登录时自报的署名是 false) */
verified: boolean
/** 确认范围:这份记录覆盖的指标,可以只确认其中一个子集 */
scope: string[]
basis?: Record<string, unknown>
note?: string | null
created_at?: string | null
/** 这条决定还算不算覆盖当前定义/绑定 */
covers_current?: boolean | null
}
/** 这次运行交回的某一个指标的实际值:值、形状、行数、遮罩,以及和期望比出来的结果 */
export interface DraftValidationActual {
value?: unknown
status?: string
rendered?: string
rows?: number | null
masked?: boolean
truncated?: boolean
shape?: string | null
shape_ok?: boolean | null
/** 引擎记过「业务描述和取数条件的关系还没被证明」:待人工确认的缺口,不改这次比较的结论 */
semantic_unverified?: boolean
findings?: string[]
/** 期望给的、对比的那个原值 */
expected?: unknown
/** 对得上 / 对不上 / 判不了(null) */
ok?: boolean | null
}
/** 这一次试跑对着比的独立期望 */
export interface DraftValidationExpected {
source: DraftExpectationSource | string
metrics: Record<string, unknown>
note?: string | null
hash?: string
}
/** GET /api/ledger/drafts/{id}/validations 的一条记录(只追加,不改写旧的) */
export interface DraftValidationRecord {
id: string
draft_id: string
workflow_id?: string | null
version: number
card_id: string
metric_ids: string[]
definition_hash?: string
binding_fingerprints?: Record<string, string>
semantic_hash?: string
execution_hash?: string
method: { version: number; note: string }
sample: { id: string; version: string }
inputs: Record<string, unknown>
inputs_hash?: string
/** 没有独立期望就是 null:只记 observed,不能算验证通过 */
expected: DraftValidationExpected | null
actual: Record<string, DraftValidationActual>
status: DraftValidationStatus
problems: string[]
run_id?: string
trial_id?: string
actor?: string | null
/** trial:试跑留下的;late:到终态时补记的 */
origin?: string
created_at?: string | null
/** 还覆不覆盖**当前**定义/绑定(定义、取数或绑定改过就对不上了) */
covers_current?: boolean | null
review?: DraftValidationReview | null
}
/** 一份草稿的验证总情况;verdict 才是结论 */
export interface DraftValidationSummary {
verdict: DraftValidationVerdict
/** 拿来下结论的那条记录的状态;一条记录都没有时是 none。老服务端可能不给这一段 */
status?: DraftValidationStatus | 'none'
/** 只有 === true 才算覆盖当前定义/绑定;false 是不覆盖,缺字段是判不了 */
covers_current?: boolean | null
record_id?: string | null
review?: DraftValidationReview | null
/** 这次被确认到的指标(确认范围):确认范围要盖住这条记录的全部指标才算整张卡通过 */
confirmed?: string[]
/** 这条记录覆盖、但还没被确认的指标:非空就不算整张卡通过 */
unconfirmed?: string[]
/** 逐状态的条数;读数缺字段时按 0 显示,不猜 */
counts?: { total?: number; covering?: number } & Record<string, number | undefined>
reason: string
/** 记录里哪些指标的语义说明仍待人工确认 */
semantic_gaps?: string[]
method?: { version: number; note: string }
}
/**
* 字段基线 B 覆盖到哪一步(K11 的按字段推进):complete 是整张卡每一格都有基线,partial 是还有没基线的格
* 或整条没基线的指标,unknown 是读不出来。「有没有基线」看 status,**「整张是不是都有」看这里**,两件事不能混。
*/
export interface DraftFieldCoverage {
status: 'complete' | 'partial' | 'unknown' | string
/** 逐条指标覆盖了几格、缺哪些格 */
metrics?: Record<string, { covered: number; expected: number; missing: string[] }>
/** 整条都没有基线的指标 */
uncovered_metric_ids?: string[]
}
/** 字段基线 B 的状态:known 有可还原的接受导入值 / baseline_unknown 没有(不能拿当前内容冒充 B) */
export interface DraftFieldBaseline {
status: 'known' | 'baseline_unknown' | string
reason?: string
artifact_id?: string
version?: number
content_hash?: string
card_id?: string
workflow_id?: string
accepted_revision?: number
accepted_at?: string
metric_ids?: string[]
field_count?: number
/** known 不等于完整:按字段推进出来的基线常常只覆盖卡上的一部分 */
coverage?: DraftFieldCoverage
source_snapshot_artifact_id?: string
}
/** GET /api/ledger/drafts/{id}/validations:记录(新的在前)+ 总情况 + 字段基线状态 */
export interface DraftValidationsOut {
draft_id: string
/** 老服务端可能不给这一段:显示时照实说读不到,不当成「有基线」 */
field_baseline?: DraftFieldBaseline
records: DraftValidationRecord[]
summary: DraftValidationSummary
method?: { version: number; note: string }
}
/** PATCH 草稿(operations 那条路)回来的变更回执:改了什么、影响哪些指标、绑定同步到哪一步、旧验证怎么失效 */
export interface DraftChangeReceipt {
applied: boolean
classification: 'definition' | 'display' | 'none' | string
card: string
metrics: string[]
operations: { op: string; metric_id: string; path: string; changed: boolean }[]
revision: number | null
definition_hash: { before: string; after: string; changed: boolean }
validation: { invalidated: boolean; scope: string; metrics: string[]; reason: string; next: string }
binding: DraftBinding
}
export interface DraftDefinitionDiagnostic {
kind?: 'needs_info' | 'validation_failed' | string
reasons?: string[]
questions?: string[]
}
/** GET /api/ledger/drafts/{id}:payload 摊平在上层(documents / metrics / dropped / open_questions / alignment) */
export interface CaliberDraft extends CaliberDraftSummary {
semantic_inventory?: SemanticInventory
selected_definition_ids?: string[]
implementation_mode?: 'all' | 'selected'
definition_issues?: { definition_id: string; name: string; reason: string }[]
implementation_progress?: { total: number; completed: number; pending: number; blocked: number; active_names: string[] }
definition_diagnostics?: Record<string, DraftDefinitionDiagnostic>
job?: { status: string; attempt: number; error?: string | null; retryable: boolean }
/**
* 这份草稿的权威口径卡(K02)。已接管的草稿(有取数图的)才有:图上一张可写的卡时就是它,多张时是下游契约
* 声明的那一张;认不出来(多张又没有唯一目标)时是 null,改的时候要显式给 target.card_id
*/
card_id?: string | null
/** 图上能写的口径卡,一张一条;页面上要人挑的时候用它 */
cards?: DraftCardRef[]
/** 客户端要带回来的基准版本(Workflow.version):PATCH 时当 expected_revision。老草稿没有图时为 null */
revision?: number | null
/**
* K04 的业务绑定能力描述:能按字段改哪些业务定义、允许值、现在的值、定义和取数实现的同步状态。
* 已接管的草稿才有;工作台照它决定展示哪些业务修改(逐资产启用)
*/
binding?: DraftBinding
/** K05 的字段基线 B 状态:有可还原的接受导入值 / 无法还原(老草稿) */
field_baseline?: DraftFieldBaseline
/** K05 的验证总情况:结论、覆盖判断、最新一条、审阅;整条记录走 /validations */
validation?: DraftValidationSummary
/** 这次 PATCH 走 operations 时的变更回执(改了什么、影响指标、绑定同步到哪一步) */
change?: DraftChangeReceipt
/** 这一次 PATCH 和上次是同一个 request_id(已经写进去了,没有新增版本) */
replayed?: boolean
documents?: DraftDocument[]
metrics?: DraftMetric[]
/** 草稿图的入口字段 */
entry_fields?: DraftEntryField[]
/** 入口字段在各组里声明不一致的地方(必填取并集、类型取更宽),合并时记下的说明 */
entry_notes?: string[]
/** 草稿图里的取数 SQL 模板:入口字段在运行时渲染;页面只读展示,不出现执行值 */
sql?: string | null
dropped?: DraftDropped[]
open_questions?: string[]
/** 还没有起草出来的指标名称:续跑跑到轮数上限或没有新指标后剩下的,可以再起一份 */
uncovered?: string[]
/** 这张草稿图有几个取数节点(fetch_1、fetch_2…):多组指标共用一张口径卡 */
blocks?: number
/** 逐组取数:每条 SQL 出哪几个指标;旧草稿没有,页面回退到拼接的 sql 字段 */
groups?: DraftGroup[]
/** 多轮续跑的进度;旧草稿没有 */
progress?: DraftProgress
/** 模型回复被截断,指标是从完整片段里抢救出来的 */
salvaged?: boolean
alignment?: DraftAlignment
/** 发布前检查;旧草稿没有图时不给 */
checks?: DraftCheck[]
/** 起草后自动发起的那次只读试运行;旧草稿可能没有 */
trial?: DraftTrial | null
/** 草稿图对应的版本号 */
version?: number | null
/** 文档超过一次能发给模型的字数,后面的段落没有参与起草 */
doc_truncated?: boolean
/** 数据目录太大,只展开了文档点到的几张表 */
catalog_truncated?: boolean
/** 旧服务端只给这一个:上面两种截断之一,界面按较窄的那条说 */
truncated?: boolean
model_id?: string | null
collection?: string | null
datasource_id?: string | null
/** 起草时的文档 id 和附加要求 */
origin?: { documents?: string[]; guidance?: string; fixed_filters?: string
continuation_from?: { draft_id: string; workflow_id?: string; revision: number; merge_required: boolean; merged_revision?: number }
}
created_by?: string | null
updated_at?: string | null
workflow_name?: string | null
}
/** POST /api/ledger/drafts/{id}/attach:接上一次真实运行后建出的工作流版本 */
export interface CaliberDraftAttachOut {
workflow_id: string
version: number
/** 并进了定义的指标(口径卡上的 metric) */
metrics: unknown[]
/** 对不上已有指标名的那些,由人决定新建还是忽略 */
warnings: string[]
}
// ---------------------------------------------------------------- K11 增量重导入(B / L / R 三方)
/**
* 一格的三方状态(app/ledger/reimport.FIELD_STATES)。**能不能接受由状态定**:
* update(无冲突更新)/ conflict(人工改过)/ new(新增候选)/ manual(没有可比基线,要人工对齐)能接受;
* missing(这次没提取到)**不能**——漏提取不当删除,L 上的原值原样留着;unchanged 不用接受。
*/
export type DraftImportFieldState = 'update' | 'conflict' | 'new' | 'missing' | 'manual' | 'unchanged'
/** 一条候选指标(工作项)的状态:逐字段三方算出来的 + 人处置之后的 */
export type DraftImportItemStatus = 'pending' | 'update' | 'conflict' | 'new' | 'manual' | 'unchanged'
| 'partial' | 'accepted' | 'rejected' | 'failed'
/** 一格的三方:b 是上次被接受的导入值、l 是现在图上人工维护的值、r 是这次抽出来的候选 */
export interface DraftImportField {
path: string
state: DraftImportFieldState | string
b?: unknown
l?: unknown
r?: unknown
b_present: boolean
l_present: boolean
r_present: boolean
/** 人处置过没有:accepted / rejected / null */
decided?: string | null
/** 这一格现在能不能接受(和状态一一对应,界面按它禁不禁用按钮) */
acceptable: boolean
}
/** 这条候选对上了哪条指标、凭什么(名字像不像不参与,只认稳定身份和来源证据) */
export interface DraftImportAlign {
metric_id?: string
/** metric_id(候选带着稳定身份)/ evidence(按来源证据)/ new(没对上)/ manual(要人指定) */
mode?: string
reason?: string
evidence?: string[]
live_evidence?: string[]
/** 证据比对取自哪个:baseline(B 的引用)还是 live(当前图的引用) */
basis?: string
/** mode 是 manual 时,对上的候选有哪几条 */
candidates?: string[]
manual?: boolean
/** 引用指向的段落没进这次提示:不能当出处,记下来 */
invisible_citations?: unknown[]
}
/** 一条工作项(一条候选指标):逐字段三方 + 人的处置 */
export interface DraftImportItem {
item_id: string
seq: number
/** 对齐到的图上指标;没对齐上时是空串 */
metric_id: string
/** 候选自己的身份(和图上无关) */
candidate_id: string
/** 持久对齐键(稳定身份 + 规范化的来源证据):重新抽之后还按它认同一条工作项 */
align_key?: string
/** 服务端标的「这条抽坏了」(引用一段没有给过模型的原文):它上面一律不能接受 */
failed?: boolean
name: string
status: DraftImportItemStatus | string
align: DraftImportAlign
error: string
accepted: string[]
rejected: string[]
applied_revision?: number | null
fields: DraftImportField[]
}
/** 一次导入里值得单独列出来的格子(冲突 / 要人工对齐 / 漏提取) */
export interface DraftImportConflict {
metric_id: string
item_id: string
seq: number
name: string
path: string
state: string
b?: unknown
l?: unknown
r?: unknown
}
/**
* 一次增量重导入(GET /api/ledger/drafts/{id}/imports、GET /api/ledger/imports/{run_id})。
* **R 只是候选,不改 L**:工作项和冲突是后台抽出来的,真正落到图上的只有「接受选定字段」。
*/
export interface DraftImportRun {
run_id: string
draft_id: string
workflow_id: string
/** queued / running / succeeded / partial / failed / interrupted / cancelled */
status: string
error: string
actor: string
request_id: string
created_at: string
items_total: number
items_decided: number
source_snapshot?: Record<string, unknown>
visible_chunk_ids?: string[]
prompt_version?: number
parse_version?: number
model_id?: string
items: DraftImportItem[]
conflicts: DraftImportConflict[]
}
/** POST /api/ledger/imports/{run_id}/accept:这一次落到哪一版、是不是重放(B 和 L 在同一次提交里推进) */
export interface DraftImportAcceptOut extends DraftImportRun {
applied: boolean
replayed: boolean
revision: number | null
}
// ---------------------------------------------------------------- K12 受限的自然语言修改(只产出提案)
/** 必须先问清的澄清项:含糊业务条件(要人指定取值)或没匹配到已声明的能力 */
export interface NlChangeClarification {
kind: 'ambiguous' | 'no_match' | 'missing' | string
field?: string | null
question: string
options: { value: string; label: string }[]
}
/**
* 一句话产出的受限修改提案:K03 同一形状的 operations + 影响摘要(preview)+ 澄清项。
* **只读**:不落库、不新增版本;ready 为真才谈得上应用。
*/
export interface NlChangeProposal {
card: string
ready: boolean
operations: DraftOperation[]
metrics: string[]
clarifications: NlChangeClarification[]
/** changes.summary 的同一份形状(preview 为 true、persisted 为 false);服务端没给就是 null */
preview?: (DraftChangeReceipt & { preview?: boolean; persisted?: boolean }) | null
/** 模型自报但不作数的键(批准、审阅这类),只是照实记下来 */
ignored_claims?: string[]
notes?: string[]
}
/**
* POST /api/ledger/drafts/{id}/change-proposal(只预览)的回:提案 + 这次没落库(applied / persisted 都是 false)。
* POST …/nl-change 的 confirm=true 交回的是**草稿详情**(见 NlChangeOut),不是这个形状。
*/
export interface NlChangePreviewOut {
draft_id: string
workflow_id: string
revision: number
card: string
proposal: NlChangeProposal
applied?: boolean
persisted?: boolean
}
/** POST …/nl-change 的回:confirm=false 是 NlChangePreviewOut;confirm=true 是草稿详情(带这一次的 change 回执) */
export type NlChangeOut = NlChangePreviewOut | (CaliberDraft & { replayed?: boolean })