World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
import type { SourceKind } from "./sourceKinds";
import { S } from "./i18n";
import { createParser } from "eventsource-parser";
export class ApiError extends Error {
status: number;
/** 服务端给的稳定错误码(没有则是尚未转换的契约守卫,message 已是英文原句) */
code?: string;
constructor(status: number, message: string, code?: string) {
super(message);
this.status = status;
this.code = code;
}
}
/** 服务端拒绝时回的正文 */
type Refusal = { error?: string; code?: string; detail?: string };
/** 一次拒绝给人看的那句话。
*
* 有 code 就查 i18n,没有(或这一条还没进表)就退回服务端的英文原句——
* 服务端永远说英文,因为界面语言在客户端(docs/decisions/0004)。
* **普通请求与对话流共用这一处**:对话流从前只读 `error`,于是明明有译文的
* `no_chat_model` 在中文界面上也是一句英文 */
function refusalMessage(body: Refusal, fallback: string): string {
let message = body.error || fallback;
// code 来自网络,不是字面量——这一处 cast 换来 err 表本身的全量类型检查
const worded = body.code
? (S.err as Record<string, string | undefined>)[body.code]
: undefined;
if (worded) message = worded;
if (body.detail) message = S.errDetail(message, body.detail);
return message;
}
/** 对话流里的 `error` 帧:与请求被拒是同一个信封 `{error, code}`,用同一个函数读。
* 读不成 JSON 的是旧格式的一句英文,原样显示 */
function streamFailure(data: string): string {
try {
const body: unknown = JSON.parse(data);
if (body && typeof body === "object") return refusalMessage(body as Refusal, data);
} catch { /* 旧格式:纯文本 */ }
return data;
}
async function request<T>(path: string, init?: RequestInit): Promise<T> {
const res = await fetch(path, {
credentials: "include",
headers:
init?.body instanceof FormData
? {}
: { "Content-Type": "application/json" },
...init,
});
if (!res.ok) {
// 措辞在这一个收口点定:22 个文件里的 toast.error(e.message) 一处都不用改
let message = res.statusText;
let code: string | undefined;
try {
const body = (await res.json()) as Refusal;
code = body.code;
message = refusalMessage(body, message);
} catch {
// 非 JSON 响应体,保留 statusText
}
throw new ApiError(res.status, message, code);
}
return res.json() as Promise<T>;
}
export interface User {
id: string;
org_id: string;
email: string;
display_name: string;
is_admin: boolean;
created_at: string;
}
/** 个人访问令牌(0014):给 MCP 客户端的长命钥匙,以发它的人的身份行事。
* 有效权限 = 这个人的角色 ∩ scope;`kb_ids` 为空 = 这个人能进的全部库。 */
export interface TokenView {
id: string;
name: string;
/** 给人认的那一小截(`utp_pat_ab12`),够对上配置文件里那一串,又不足以复原 */
token_prefix: string;
scope: "read" | "write";
kb_ids: string[] | null;
expires_at: string | null;
last_used_at: string | null;
/** 撤销打戳不删行 */
revoked_at: string | null;
created_at: string;
}
export interface Workspace {
id: string;
org_id: string;
name: string;
created_at: string;
}
/** 建库时可选的预置本体包(`GET /ontology-packs`)。 */
export type OntologyPack = {
id: string;
name: string;
summary: string;
classes: number;
properties: number;
};
export interface Kb {
id: string;
workspace_id: string;
name: string;
kind: string;
description: string | null;
visibility: "open" | "restricted";
/** 部署的公共默认空间(第一个建的库):永远 open、不可删除 */
is_default: boolean;
/** 抽取遇到本体外的说法时,是否允许系统自动补进本体并改写等它的事实。
关掉不影响"留意":未匹配统计照常累积可见,只是变成你点一下的提案 */
auto_extend_ontology: boolean;
/** 把推出来的事实写进账本(R1)。**缺省关**——推理往图里加东西,
* 而声明可能是错的,不该在用户没表态时就按它改图 */
materialize_inferences: boolean;
/** 抽取结束自动排一轮类型消解(只自动落地子树内精化的那一档) */
auto_type_resolution: boolean;
/** 治理开关(0025,缺省关):agent 按先进先出过等人的重复对,先读台账里人的
* 先例再裁;打开就开始,关掉就停 */
governance: boolean;
/** 这次打开治理的时刻;保险丝只数它之后的撤回 */
governance_since: string | null;
/** 多久重推一次(分钟)。事实持续在变,只靠手点会让派生一直是缺的 */
inference_interval_minutes: number;
/** 上次推完的时间 */
last_inference_at: string | null;
/** 内置本体按哪种语言播种、新描述写哪种语言。**跟语料走,不跟界面走**
(界面语言在客户端,见 docs/decisions/0004) */
ontology_lang: "en" | "zh";
/** 调用者在本库的角色(仅详情接口返回):前端据此门控破坏性入口 */
my_role?: "viewer" | "editor" | "admin" | "owner" | null;
}
/** 账户层"我的知识库"行:库 + 我的角色 + 加入信息 + 概览统计。 */
export interface MyKb {
kb: Kb;
my_role: "viewer" | "editor" | "admin" | "owner" | null;
joined_at: string | null;
added_by_name: string | null;
doc_count: number;
member_count: number;
}
/** 审计事件(纯审计展示)。 */
export interface AuditEvent {
id: string;
action: string;
target_kind: string;
target_id: string | null;
detail: Record<string, unknown>;
/** null = 引擎自动(裁决器、一致性检查、推理);有 id 没名字 = 账号已移除 */
actor_id: string | null;
actor_name: string | null;
created_at: string;
}
export interface KbMember {
user_id: string;
email: string;
display_name: string;
role: "viewer" | "editor" | "admin";
}
export interface Doc {
id: string;
kb_id: string;
source_id: string | null;
filename: string;
mime: string;
size_bytes: number;
status: string;
graph_status: string;
/** 摄入管道的失败原因 */
error: string | null;
/** 图谱抽取管道的失败原因(与 error 分列:两条管道各存各的) */
graph_error: string | null;
chunk_count: number;
/** 文档标签。**今天没有任何界面用它**——故意留着,理由写在
* `migrations/0002_ingest.sql` 的 `tags` 列上 */
tags: string[];
missing_since: string | null;
/** 墓碑(#268):删了但留着,可撤销 */
deleted_at: string | null;
/** 真删过:内容没了,回不来 */
purged_at: string | null;
/** 这份文件的字要靠哪一种模型读、而那种模型没配(0040):ocr / transcribe;文档此时是 failed */
reader_needed: "ocr" | "transcribe" | null;
created_at: string;
/** 文档日期——`#610`:从文件名或正文首行解析出来的「文件上写的日期」,
* 与 `created_at`(上传时刻)必须分开展示。`null` 表示没认出来(`#610` 决定 3) */
doc_time: string | null;
/** `doc_time` 是怎么来的:`"content"` = 文件名或正文,`"none"` = 没认出来。
* 上传时刻不在这里—— `created_at` 才是 */
doc_time_source: "content" | "none";
}
/** 一类抽取丢弃在一篇文档里的聚合:事实抽出来了,却没能落地。 */
export interface ExtractionDrop {
document_id: string;
/** 稳定的原因码,前端按它查文案(attr_domain_mismatch / low_confidence / ...) */
reason: string;
/** 该原因下的具体对象(属性 key、谓词名、"salary@organization") */
detail: string;
count: number;
example: string | null;
}
export interface SourceView {
id: string;
kind: SourceKind;
name: string;
config: {
urls?: string[];
feed_url?: string;
content_mode?: "feed" | "full_new_items";
endpoint?: string;
/** github_issues:owner/name */
repo?: string;
/** github_issues:PR 在 GitHub 模型里也是工单,默认不收 */
include_pull_requests?: boolean;
/** jira_issues:站点地址,如 https://issues.apache.org/jira */
base_url?: string;
/** jira_issues:项目 key,如 KAFKA */
project?: string;
/** false = 这个来源下的文档只检索、不抽取(schema 文档,0035 决定 7);缺省抽取 */
extract?: boolean;
} | null;
icon: string | null;
sync_interval_minutes: number | null;
sync_cron: string | null;
last_sync_at: string | null;
last_sync_status: "never" | "queued" | "running" | "ok" | "failed";
last_sync_error: string | null;
last_sync_added: number;
doc_count: number;
missing_count: number;
/** 全文补全那一块;**不是 RSS 全文来源的就是 null**,不用再拿 kind 与
* content_mode 自己推一遍适不适用(0026 / #417) */
rss_full_content: RssFullContentSummary | null;
}
/** 一个 RSS 来源当前代的全文补全进度。五个计数一起读,所以一起给。 */
export interface RssFullContentSummary {
state: "pending" | "active" | "disabled";
pending: number;
/** queued 与 hydrating 合成一格 */
queued: number;
retrying: number;
complete: number;
/** terminal、deleted、superseded 合成一格 */
terminal: number;
}
export interface SearchResult {
id: string;
document_id: string;
seq: number;
text: string;
filename: string;
}
/** 这个库走到哪一步了(#313)。凭据不出库:模型那项只说配没配 */
export interface Readiness {
has_chat_model: boolean;
documents: number;
processing: number;
failed: number;
entities: number;
}
export interface LlmSettingsView {
chat_base_url?: string | null;
chat_model?: string | null;
/** 推理强度:none | minimal | low | medium | high;空 = 端点默认 */
chat_reasoning_effort?: string | null;
has_chat_key?: boolean;
embed_base_url?: string | null;
embed_model?: string | null;
embed_dim?: number | null;
has_embed_key?: boolean;
/** mineru | ark(0065) */
ocr_provider?: string;
ocr_base_url?: string | null;
ocr_backend?: string | null;
ocr_model?: string | null;
has_ocr_key?: boolean;
transcribe_base_url?: string | null;
transcribe_model?: string | null;
has_transcribe_key?: boolean;
}
export interface Member {
user_id: string;
email: string;
display_name: string;
role: string;
is_admin: boolean;
}
export interface OrgUser {
id: string;
email: string;
display_name: string;
is_admin: boolean;
}
/** 一个身份提供方 subject 绑定到的账号(0056) */
export interface OidcIdentity {
user_id: string;
subject: string;
email: string;
}
/** 问数数据源(凭据不下发,只有 host:port/db 摘要)。 */
export interface DataSourceView {
id: string;
name: string;
engine: string;
summary: string;
created_at: string;
last_test_at: string | null;
last_test_ok: boolean | null;
}
export interface GraphNode {
id: string;
name: string;
// 没判出类型时为 null(0009)
type_key: string | null;
type_label: string | null;
color: string;
shape: "circle" | "square";
degree: number;
disambiguator: string | null;
}
export interface SyncRun {
id: string;
started_at: string;
finished_at: string | null;
status: "running" | "ok" | "failed";
created_docs: number;
updated_docs: number;
error: string | null;
}
/** 分块的抽取产物(文档查看器右栏)。 */
export interface ChunkFact {
chunk_id: string;
fact_id: string;
/** A live open-layer statement with a usable phrase, eligible for a regression case. */
is_open_statement: boolean;
subject_id: string;
subject: string;
/** 本体没认下这条关系时是原文说法;两者都拿不出时为 null */
predicate: string | null;
/** true = 名字来自原文,不是本体认下的关系 */
inferred: boolean;
object_id: string | null;
object: string | null;
valid_from: string | null;
valid_to: string | null;
confidence: number;
}
/** 一条推出来的事实,连同它的证明(实体面板的「推出来的」那一档)。
*
* `premises` 是这一档存在的理由:不给出前提的话,一条派生边跟一条普通的边
* 在界面上看不出区别,而那正是「推理污染知识」的样子。 */
/** 一条条件:这个属性、这样比、跟这个值比 */
export interface RuleCondition {
/** 组号:同组「与」,组间「或」(决定记录 0029)。不带 = 第 0 组 */
group?: number;
predicate_id: string;
/** gt | gte | lt | lte | between | in | not_in | present */
op: string;
/** 数字 / [lo,hi] / 字符串数组;present 不带 */
operand?: unknown;
predicate_label?: string;
/** x = rule subject (default); y = the entity reached by the one declared join */
side?: "x" | "y";
}
export interface RuleInput {
name: string;
description?: string;
subject_type_id: string;
/** typing = class; attribute = value; relation = an edge to the joined Y */
conclusion: "typing" | "attribute" | "relation";
conclude_type_id?: string;
conclude_predicate_id?: string;
join_predicate_id?: string;
conclude_value?: unknown;
conditions: RuleCondition[];
}
/** 一条规则标住的一个实体,连同让它成立的那几条读数 */
export interface RuleMatch {
derived_id: string;
entity_id: string;
entity: string;
concluded: string | null;
valid_from: string | null;
valid_to: string | null;
object_id?: string | null;
object_entity?: string | null;
relation_predicate?: string | null;
/** 「全烃 = 12.3」这种可读形态,按前提顺序 */
premises: string[];
}
export interface BusinessRule extends Omit<RuleInput, "conclusion" | "join_predicate_id"> {
conclusion: "typing" | "attribute" | "computed" | "relation";
/** Raw server tree; unsupported nodes must remain read-only. */
conclude_expr?: unknown;
id: string;
enabled: boolean;
subject_label: string;
conclude_type_label: string | null;
conclude_predicate_label: string | null;
join_predicate_id?: string | null;
join_predicate_label?: string | null;
/** 此刻凭它成立的结论条数 */
derived_count: number;
/** 上次跑的时候有几个实体的读数组合没展开完。**大于零就意味着少推了** */
capped: number;
/** 当前定义是第几版。改判据或结论就加一,改名不算。老的夹具没有它,界面按第 1 版读 */
version?: number;
}
/** 规则定义史的一版:说了什么、从什么时候到什么时候、此刻凭它成立几条 */
export interface RuleVersion {
id: string;
seq: number;
definition: {
subject_type_id: string;
conclusion: BusinessRule["conclusion"];
conclude_type_id: string | null;
conclude_predicate_id: string | null;
conclude_value: unknown;
conclude_expr: unknown;
join_predicate_id: string | null;
conditions: { group: number; seq: number; side: string; predicate_id: string; op: string; operand: unknown }[];
};
recorded_at: string;
superseded_at: string | null;
derived_count: number;
/** 定义里提到的类与谓词现在叫什么;改名或删掉的查不到,界面就显示 id */
labels: Record<string, string>;
}
export interface DerivedFact {
id: string;
subject_id: string;
subject: string;
/** 字面值结论(规则推出的归类与属性)没有实体宾语 */
object_id: string | null;
object: string;
predicate: string;
/** 靠哪条规则推的 */
/** 靠哪条规则推的。后两种是 0017 补上的跨谓词规则 */
rule: "transitive" | "symmetric" | "inverse" | "sub_property" | "business";
/** 业务规则的名字。公理推的为 null——公理没有名字 */
rule_name?: string | null;
/** 凭业务规则定义的哪一版推出的。公理推的为 null */
rule_version?: number | null;
valid_from: string | null;
valid_to: string | null;
confidence: number;
derived_at: string;
/** 直接前提,按推导顺序 */
premises: string[];
}
/** 一条**没有落地**的派生(0017 §3):推出来了,撞上一条断言,拦在图外。
* 没有自己的 id,用那条违规的 id 指它——面板、幽灵边、Review 卡片三处靠它对上 */
export interface BlockedDerivation {
violation_id: string;
subject_id: string;
subject: string;
object_id: string;
object: string;
predicate: string;
rule: string;
via_label: string;
valid_from: string | null;
valid_to: string | null;
against_fact: string;
against_text: string;
premises: string[];
}
/** 证明的一步:一条前提,连同它的证据(0002 R2)。
*
* 那一步自己的前提在 `premises` 里再往下一层。所以证明是一棵树,
* 深度与推理同一条上限。断言那一步 `premises` 是空的——它的叶子是
* `evidence` 里的原句,不必再往下问
*/
export interface ProofStep {
seq: number;
fact_id: string;
subject_id: string;
subject: string;
predicate_id: string | null;
predicate: string | null;
object_id: string | null;
object: string | null;
valid_from: string | null;
valid_to: string | null;
confidence: number;
/** 这条前提后来被撤了;派生随之失效,证明仍要读得出当时靠的是什么 */
retracted: boolean;
evidence: Evidence[];
/** 这一步自己的前提(0030):按 seq 展开的子证明。叶子的 premises 为空 */
premises: ProofStep[];
}
export interface Proof {
derived: DerivedFact;
steps: ProofStep[];
}
/** 审核页的分档。**与服务端的 queue 参数是同一组字面量**——拼错会拿到
* 一个明确的 unknown_queue 错误,而不是悄悄的空列表。 */
export type ReviewQueue =
| "pending"
| "duplicates"
| "conflicts"
| "unconfirmed"
| "lowconf"
| "mappings"
| "violations"
| "defects"
// 对齐器两票不一致的签名与类别词(#725,0044 决定 3)
| "alignment"
// 勘误 agent 被闸门拦下、等人答的动作(0044 决定 7)
| "errata"
| "merges"
// agent 的每一笔(0025):建议、自动裁决与人的回答
| "agent";
/** 重复项按两边类型的关系筛:any 全部;same 两边都有类型且相等;conflict 都有且不等 */
export type ReviewTypeFilter = "any" | "same" | "conflict";
/** 各档的真实条数。左栏的徽标读它,不读列表长度 */
export interface ReviewCounts {
/** 记忆抽出、等人点头的事实(0015) */
pending: number;
duplicates: number;
/** 重复项里两边同类型 / 类型冲突的各多少(#428);没类型的一侧哪档都不算 */
duplicates_same_type: number;
duplicates_type_conflict: number;
conflicts: number;
unconfirmed: number;
lowconf: number;
mappings: number;
violations: number;
defects: number;
/** 对齐器拿不定的签名与类别词(#725) */
alignment: number;
/** 勘误 agent 留给人的动作(0044 决定 7) */
errata: number;
merges: number;
/** agent 写下、等人回答的建议(0025) */
agent: number;
/** agent 的全部记录(Agent 队列翻页用) */
agent_rows: number;
/** 这个库的 govern 任务此刻在跑 */
agent_running: boolean;
/** 还没轮到 agent 看的对 */
agent_queue: number;
}
/** 类型消解的一条建议:一个待精化的实体、送去检索的画像、以及候选类。
*
* `profile` 回给调用方是有意的——检索找不着的时候,第一个要看的就是
* 「我们拿什么去找的」,而不是猜是画像不对还是类的描述不对。 */
export interface TypeSuggestion {
entity_id: string;
name: string;
/** 现在挂着的类,可能没有(0009) */
coarse: string | null;
coarse_description: string | null;
proposed_type: string | null;
specific_type: string | null;
fact_count: number;
profile: string;
candidates: {
id: string;
key: string;
label: string;
description: string;
distance: number;
}[];
}
/** 跑完一轮的结果。**三档分开报**:自动改了的、留给人的、裁决说「都不是」的。
* 最后那一档带着理由——这一步押在「选择都不是是个体面答案」上,
* 不记理由,最大的那一档就是不透明的。 */
export interface ResolutionOutcome {
batch: string | null;
retyped: number;
for_review: {
entity_id: string;
name: string;
coarse: string | null;
from_type_id: string | null;
to_type_id: string;
choice: string;
confidence: number;
reason: string | null;
/** 选中的类不在粗类的子树里——换的是分类轴,不是往下走一格 */
crosses_axis: boolean;
}[];
left_alone: {
name: string;
coarse: string | null;
specific_type: string | null;
reason: string | null;
top_candidate: string | null;
}[];
}
export interface ReviewSide {
id: string;
name: string;
// 没判出类型时为 null(0009)
type_label: string | null;
color: string;
disambiguator: string | null;
degree: number;
top_facts: string[];
}
/** agent 在一对上留下的、还开着的建议(0025);卡片上的裁决就是对它的回答 */
export interface ReviewProposal {
id: string;
action: "merge" | "keep" | "unsure";
confidence: number;
reason: string | null;
}
export interface ReviewItem {
id: string;
score: number;
reason: string | null;
stage: "adjudicating" | "human";
created_at: string;
left: ReviewSide;
right: ReviewSide;
proposal: ReviewProposal | null;
}
/** agent 的一笔(0025):看了哪一对、想怎么办、凭什么、人怎么答的 */
export interface AgentDecision {
id: string;
run_id: string;
target_kind: "review";
target_id: string;
action: "merge" | "keep" | "unsure";
confidence: number;
reason: string | null;
/** 它被给看的先例:同对 / 同名 / 撤回各一条一条,类型对的习惯是一条汇总 */
precedents: AgentPrecedent[];
status: "proposed" | "applied" | "accepted" | "overridden" | "reverted" | "superseded";
merge_id: string | null;
/** defer 留给人的那一个问题;只有 unsure 的行才有 */
question: string | null;
/** 第二层看了什么:一条一次查询 */
trace: { tool: string; args: Record<string, string>; note: string }[];
/** 第二层花的模型调用 */
calls: number;
created_at: string;
decided_at: string | null;
decided_by_name: string | null;
left: string | null;
right: string | null;
}
export type AgentPrecedent =
| {
family: "same_pair" | "same_name" | "revert";
event_id: string;
action: string;
left: string;
right: string;
at: string;
/** 人拍板时写的那一句(0026);0026 之前的决定没有 */
why?: string | null;
}
| { family: "type_pair"; merged: number; kept: number; reverted: number };
/** 数据映射的一条口径:业务概念 → 数据资产定义(见 docs/decisions/0011)。
*
* 字段是列而不是 JSON 里的键——从前它是一条 `mapped_to` 事实,
* 这几样全塞在 `object_value` 里。 */
export interface ConceptMapping {
id: string;
concept_id: string;
concept_name: string;
/** 挂载的数据源。同一概念在不同源上可以有不同定义 */
source: string;
table_name: string | null;
expr: string | null;
sql: string | null;
unit: string | null;
summary: string | null;
/** 派生指标:算出来的,不是表里的列 */
derived: boolean;
status: "proposed" | "confirmed" | "rejected";
}
/** 一条口径改动之前的样子。**整版快照而不是差异**(0006):
* 读的时候要回答的是「当时是什么」,差异得从头重放才答得出来 */
export interface MappingRevision {
id: string;
before: Record<string, unknown>;
/** 改的人;用户是软删除的,所以归因不会因为人离职而丢 */
changed_by_name: string | null;
changed_at: string;
}
/** 一处公理违规(0002 R0)。判据来自本体自己声明的公理,没声明就不报 */
/** derived_contradiction 独有(0017):推出来的那条三元组——它没有落库,
* 只能在这里写出来。其它种类是 `{}` */
export interface ViolationDetail {
axiom?: "functional" | "inverse_functional" | "asymmetry" | "self_loop";
rule?: "transitive" | "symmetric" | "inverse" | "sub_property";
via_label?: string;
subject?: string;
predicate?: string;
object?: string;
valid_from?: string | null;
valid_to?: string | null;
premises?: string[];
}
export type ViolationResolution =
| "fact_retracted"
| "fact_closed"
| "axiom_relaxed"
| "accepted";
export interface AxiomViolation {
id: string;
kind:
| "self_loop"
| "asymmetry"
| "cycle"
| "functional"
| "inverse_functional"
| "signature"
| "derived_contradiction";
/** 判据来自哪条关系。判「公理写错了」时从这里进本体去改 */
predicate: string | null;
left_fact: string;
left_text: string;
/** 自反那一类与 left 相同——一条事实跟自己矛盾 */
right_fact: string;
right_text: string;
/** `path` 的长度:环上的、互斥组里的事实,派生的前提;自环与签名为 0 */
path_len: number;
detected_at: string;
detail: ViolationDetail;
/** 审核线索(0017 §2),一次只给一条:旧断言没写结束日期、有同名实体、
* 抽取置信度低。没有就空 */
hint: "stale" | "duplicate" | "unsure" | null;
/** 环上的每一条事实(按顺序),或互斥组里的每一条(按 id);自环与签名为空。
* 撤事实要指名撤哪条(#202) */
path: { id: string; text: string }[];
}
/** 本体自己的一处自相矛盾。**与 AxiomViolation 不是一回事**:那个说
* 「事实与定义抵触」,这个说「定义自己站不住」,后者更根本 */
/** 对齐队列里的一条(#725):一条短语签名,或一个类别词,都是对齐器两票不一致、等人定的 */
export type AlignmentItem =
| {
kind: "phrase";
id: string;
phrase: string;
subject_class: string | null;
object_class: string | null;
object_is_value: boolean;
statement_count: number;
examples: string[];
/** 两票;候选多到没问模型时两票为空、`reason` 说明(0053) */
votes: {
first?: AlignmentVote | null;
second?: AlignmentVote | null;
reason?: string;
candidates?: number;
} | null;
decided_at: string;
/** 人绑过、还没说单个日期标哪一端的签名(#966):现在绑到的属性与方向。
* 两票不一致的条目两个都是 null */
bound_to: string | null;
direction: "forward" | "reverse" | null;
}
| {
kind: "kind_word";
kind_word: string;
words: string[];
examples: string[];
phrases: string[];
entity_count: number;
votes: { first?: string | null; second?: string | null } | null;
decided_at: string;
}
| {
/** 对齐器提的一条蕴含规则(0044 决定 3 第五片) */
kind: "rule";
id: string;
trigger: "phrase" | "kind_word";
phrase: string;
subject_class: string | null;
object_class: string | null;
object_is_value: boolean;
property: string;
property_label: string;
reading: string | null;
statement_count: number;
examples: string[];
votes: { agent?: { property: string; reading: string | null } | null } | null;
decided_at: string;
};
/** 勘误 agent 被闸门拦下的一笔(0044 决定 7):它想撤、改或加什么,凭哪句原话,为什么留给人 */
export interface ErrataItem {
id: string;
document_id: string;
document: string;
action: "retract" | "revise" | "add";
/** 结构报的理由;空 = 抽样看到的 */
flag: "domain" | "range" | "name_absent" | "no_date" | null;
fact_id: string | null;
/** 动作指向的那条事实:撤的就是看的那条,改的是改成的,加的是加的 */
proposed: { subject: string; property: string; object: string } | null;
reason: string;
quote: string | null;
/** 闸门的理由:`derived 2` / `answered 1` / `contradiction CEO of`(0027 的写法) */
detail: string | null;
created_at: string;
}
export interface AlignmentVote {
property: string;
direction: "forward" | "reverse";
/** 状态属性下,只带一个日期的陈述那个日期标的是什么(#966);事件与恒常没有 */
marks?: AlignmentMarks | null;
}
/** 单个日期在状态上标的是开始、结束,还是都不是(`phrase_bindings.marks`,#966) */
export type AlignmentMarks = "start" | "end" | "none";
export interface OntologyDefect {
id: string;
kind:
| "symmetric_and_asymmetric"
| "transitive_and_functional"
| "subclass_cycle"
| "disjoint_with_ancestor"
| "inherits_disjoint"
// 0017 加的三类:都在谓词上,前两类关于逆,第三类是子属性成环
| "inverse_of_itself"
| "inverse_not_mutual"
| "sub_property_cycle"
// 0017:两条规则加在一起产出互斥的派生,按规则对聚合报一次
| "rules_disagree";
subject_label: string | null;
other_label: string | null;
path_labels: string[];
detected_at: string;
detail: DefectDetail;
}
/** rules_disagree 独有:哪两条规则、撞在哪条公理上、几对、几个例子 */
export interface DefectDetail {
count?: number;
rules?: {
rule_a: string;
via_a: string;
rule_b: string;
via_b: string;
axiom: string;
count: number;
examples: [string, string][];
}[];
}
export interface FactReviewItem {
id: string;
subject_name: string;
predicate_label: string | null;
object_name: string | null;
valid_from: string | null;
valid_to: string | null;
confidence: number;
evidence_count: number;
quote: string | null;
}
/** 一句记忆抽出、等人点头的事实(0015)。`quote` 是那句记忆的全文——
* 确认界面把原句放在三元组上面,人对着原句判断,而不是凭空判断三元组。 */
export interface PendingFactItem {
id: string;
subject_id: string;
subject_name: string;
predicate_id: string | null;
/** 本体里的关系名;为空时显示 `proposed_predicate`(斜体,标明是原话) */
predicate_label: string | null;
proposed_predicate: string | null;
/** 开放陈述(0044):文档自己的关系短语;有它就没有 predicate,那不是缺陷 */
phrase: string | null;
/** 按文档角色词记的限定:值或实体 */
qualifiers: { role: string; value?: unknown; entity_id?: string; entity_name?: string }[] | null;
/** 照抄的时间词,不是算出来的日期 */
time_words: { text: string; char_start: number }[] | null;
object_id: string | null;
object_name: string | null;
object_value: { value?: unknown; unit?: string; summary?: string } | null;
valid_from: string | null;
valid_to: string | null;
confidence: number;
chunk_id: string;
quote: string;
proposed_by: string | null;
proposed_by_name: string | null;
/** 经 MCP 记进来时,那个 agent 的令牌名;网页端对话里为空 */
proposed_token_name: string | null;
created_at: string;
}
/** 时态冲突(自动闭合拿不准的那些):旧事实 vs 新事实。 */
export interface ConflictItem {
id: string;
reason: "no_time" | "simultaneous" | "low_confidence";
created_at: string;
predicate_label: string;
old_fact_id: string;
old_subject: string;
old_object: string | null;
old_valid_from: string | null;
new_fact_id: string;
new_subject: string;
new_object: string | null;
new_valid_from: string | null;
new_confidence: number;
}
/** 决策台账事件(audit_events 的 review 域切片):detail 是决策时的自包含快照。 */
export interface ReviewHistoryEvent {
id: string;
action: string;
target_kind: string;
target_id: string | null;
detail: Record<string, unknown>;
/** null = 系统(AI 裁决器) */
actor_name: string | null;
created_at: string;
}
/** 一档队列里等着的:多少条、最老的一条从什么时候起等(空队列是 null) */
export interface QueueWait {
count: number;
oldest_at: string | null;
}
/** 一个时间窗口里的决定 */
export interface DecidedWindow {
total: number;
/** 其中台账上没有 actor 的——AI 裁决器自己办的 */
automatic: number;
by_action: { action: string; count: number }[];
/** actor_id 为 null 的一行是裁决器;label 是台账里的身份快照 */
by_actor: { actor_id: string | null; label: string | null; count: number }[];
}
/** 一个时间窗口里 agent 写下的行,按现在的状态数 */
export interface AgentWindow {
applied: number;
proposed: number;
accepted: number;
overridden: number;
reverted: number;
}
/** 审核台总览(#377):等着办的、办过的、库的成色。与左栏计数同一套口径 */
export interface ReviewSummary {
/** agent 在这个库里做过什么(0025) */
agent: { running: boolean; queue: number; open: number; last_7d: AgentWindow; last_30d: AgentWindow };
waiting: Record<
| "pending"
| "duplicates"
| "conflicts"
| "unconfirmed"
| "lowconf"
| "violations"
| "defects"
| "alignment"
| "errata",
QueueWait
>;
decided: {
last_7d: DecidedWindow;
last_30d: DecidedWindow;
/** 近 14 天,一天一条,含零 */
daily: { day: string; count: number }[];
};
health: {
facts: number;
low_confidence: number;
unconfirmed: number;
contested: number;
};
}
export interface MergeLog {
id: string;
source_name: string;
target_name: string;
merged_by_name: string | null;
reason: string | null;
created_at: string;
reverted_at: string | null;
}
/** 边上的属性(0037):`{ key: "amount", value: { value: 4e9, unit: "$" } }` */
export interface FactQualifier {
qualifier_type_id: string;
key: string;
label: string;
value: { value?: unknown; unit?: string } | null;
entity_id: string | null;
entity_name: string | null;
}
export interface GraphEdge {
id: string;
source: string;
target: string;
/** 本体没认下这条关系时是原文说法;两者都拿不出时为 null(0052 之前的老数据) */
predicate: string | null;
label: string | null;
/** 这条边是从哪条开放陈述算出来的,那条陈述的原话(0044 决定 1):
* 画布一条陈述只画一条边,有类型化行就画它,原话跟在这里不丢 */
said_as: string | null;
/** true = 这条边的名字来自原文,不是本体认下的关系 */
inferred: boolean;
/** true = 这条边是**推出来的**,不是任何人断言的(R1)。
* 与 `inferred` 不是一回事:那个说「名字来自原文」,这个说「不是谁说的」 */
derived: boolean;
/** 推它出来的那条规则;断言的边为 null。
* 界面靠它认出 `inverse`——那种边与来源边是同一件事的两种说法,
* 画两条只是把冗余画了两遍(见 Graph 的 `layOutParallelEdges`) */
rule: string | null;
/** 推它出来用到的前提事实 id(按证明顺序);断言的边为空。
* 并边要靠它认准来源——只按节点对匹配会把说法挂到错的边上 */
premises: string[];
valid_from: string | null;
valid_to: string | null;
/** **读出来的**区间(0022):没起点的事实从最早的证据起,结束了不知哪天的到说出
* 它的那份文档为止。滑杆按这两个过滤;上面那两个是原文说了什么,只用来显示。
* 前端不自己解释 NULL——规则只在服务端的 world_axis 里有一份 */
holds_from: string | null;
holds_to: string | null;
confidence: number;
/** 有争议(0017 §3):有一条 open 的公理违规或时态冲突指着它。整条边画成警戒色 */
contested: boolean;
/** 幽灵边(0017 §3):没落地的派生。`id` 是那条 `derived_contradiction` 违规的 id;
* `derived` 同时为 true,跟着派生开关走。点它打开主语的面板 */
blocked: boolean;
/** 边上的属性(0037) */
qualifiers: FactQualifier[];
/** 文档的角色词(0044):不是本体属性,另放一处 */
statement_qualifiers: StatementQualifier[];
}
/** 实体的一个名字(0041)。`canonical` 是面板标题上那个;曾用名在世界轴上有结束 */
export interface NameView {
fact_id: string;
name: string;
canonical: boolean;
recorded_at: string;
valid_from: string | null;
valid_from_precision: string | null;
valid_to: string | null;
valid_to_precision: string | null;
document_ids: string[];
evidence_count: number;
}
/** 开放陈述按文档角色词记的限定(0044):值或实体 */
export interface StatementQualifier {
role: string;
value: unknown | null;
entity_id: string | null;
entity_name: string | null;
}
export interface EntityFact {
id: string;
direction: "out" | "in";
/** 同 GraphEdge:本体外的关系回落到原文说法,两者都没有时为 null */
predicate_key: string | null;
predicate_label: string | null;
/** 这条边是从哪条开放陈述算出来的,那条陈述的原话(0044 决定 1):
* 画布一条陈述只画一条边,有类型化行就画它,原话跟在这里不丢 */
said_as: string | null;
/** true = 名字来自原文,不是本体认下的关系 */
inferred: boolean;
/** 关系的时态类别。没有谓词就无从谈起,为 null */
temporal: string | null;
other_id: string | null;
other_name: string | null;
/** 字面值宾语(属性事实/问数映射):{"value":…} 或 {"summary":…} */
object_value: Record<string, unknown> | null;
/** 边上的属性(0037) */
qualifiers: FactQualifier[];
/** 文档的角色词(0044):不是本体属性,另放一处 */
statement_qualifiers: StatementQualifier[];
valid_from: string | null;
valid_to: string | null;
/** 读出来的区间(0022),与 GraphEdge 同义:「此刻成立」按它判 */
holds_from: string | null;
holds_to: string | null;
/** 见证从文档的哪条日期来,照文档的字(0064):「提报日期 2026年9月4日」。没有起止的
事实,`holds_from` 就是见证的日期——它是「截至」,不是起点 */
attested_by?: string | null;
valid_from_precision: string | null;
/** year | month | day,外加 unknown = 原文说它结束了但没说哪天 */
valid_to_precision: string | null;
confidence: number;
evidence_count: number;
/** 证据全部停留在来源文档的旧版(未被现行内容确认;不代表事实失效) */
stale: boolean;
/** 修正行:区间闭合来自引擎对账/人工裁决而非抽取原文 */
corrected: boolean;
/** 有争议(0017 §3):哪一种、Review 里那一项的 id、派生撞断言时推出来的那句话。
* 行不压暗——断言仍然活着 */
contested: {
kind: string;
ref_id: string;
derived?: string | null;
} | null;
/** 证据集合里最新的文档时间(开放事实的"最后确认时间") */
last_evidence_time: string | null;
}
/** 实体的一次认知变更(记录时间轴上的事件,与 EntityFact 的有效时间轴正交)。
*
* 不是每个事件都来自一条事实:retyped / retype_reverted 来自改类账本,
* 没有谓词、没有对方、没有方向。 */
export interface EntityHistoryEvent {
/** 事实事件才有;改类事件为 null */
fact_id: string | null;
/** 记录时刻:写入 = recorded_at,作废 = invalidated_at,改类 = 改类那一刻 */
at: string;
kind:
| "asserted"
| "corrected"
| "rejected"
| "merged"
/** 别人并进了它:事实搬到它名下 */
| "merged_in"
/** 它并进了别人:这个 id 从此不再单独存在 */
| "merged_away"
| "merge_reverted"
| "retyped"
| "retype_reverted";
direction: "out" | "in" | null;
predicate_label: string | null;
other_name: string | null;
object_value: Record<string, unknown> | null;
valid_from: string | null;
valid_to: string | null;
valid_from_precision: string | null;
/** year | month | day,外加 unknown = 原文说它结束了但没说哪天 */
valid_to_precision: string | null;
confidence: number | null;
/** null = 引擎自动(抽取写入 / 时态对账闭合 / 高置信自动改类) */
actor_name: string | null;
action: string | null;
document_id: string | null;
filename: string | null;
quote: string | null;
/** 改类事件的两端。起点为 null = 从「未分类」改过来(0009 之后最常见的一种) */
from_type_label: string | null;
to_type_label: string | null;
}
/** Stored comparisons against the regular phrase-alignment decisions. */
export interface OntologyRegressionCase {
id: string;
kb_id: string;
statement_id: string;
expected_property_id: string;
expected_direction: "forward" | "reverse";
created_by: string | null;
created_at: string;
origin: "adoption" | "person";
last_checked_at: string | null;
last_result: {
passed: boolean;
human_bound: boolean;
actual_property_id: string | null;
actual_direction: "forward" | "reverse" | null;
status: "bound" | "none" | "undecided";
decided_at: string | null;
} | null;
subject_id: string;
subject_label: string;
phrase: string;
object_id: string | null;
object_label: string | null;
object_value: Record<string, unknown> | null;
expected_property_label: string;
expected_property_key: string;
actual_property_label: string | null;
actual_property_key: string | null;
created_by_label: string | null;
}
export interface Evidence {
/** 模型在这一块里实际用的谓词说法。本体外的谓词不落到关系上,界面显示的就是这里 */
proposed_predicate: string | null;
quote: string | null;
chunk_id: string;
document_id: string;
filename: string;
seq: number;
/** 证据出自文档的第几版 */
doc_version: number;
/** 文档已有更新版本(证据停留在旧版;不代表事实失效) */
stale: boolean;
/** 这条证据的文档已被删除;事实还活着是因为另有出处(#268) */
document_deleted: boolean;
/** 这块文字从哪来(0040);证明链那条路不带,缺席即原文 */
origin?: "stated" | "ocr" | "transcribed" | "described";
origin_model?: string | null;
anchor?: Record<string, unknown> | null;
}
export interface ChunkFull {
id: string;
seq: number;
text: string;
/** 这块文字从哪来(0040) */
origin: "stated" | "ocr" | "transcribed" | "described";
origin_model: string | null;
/** ocr: {page, bbox?};transcribed: {start_ms, end_ms, speaker} */
anchor: Record<string, unknown> | null;
}
export interface EntityTypeView {
id: string;
key: string;
label: string;
color: string;
shape: "circle" | "square";
builtin: boolean;
/** 全部父类(subClassOf 可以有多个) */
parents: string[];
/** 与它互斥的类:**声明「不可能同时是」** */
disjoint: string[];
/** 左栏画树时挂在哪一支下。不参与语义,只管展示 */
primary_parent: string | null;
description: string;
usage: number;
}
export interface RelationTypeView {
id: string;
key: string;
label: string;
temporal: string;
functional: boolean;
inverse_functional: boolean;
/** 其余四条 OWL 公理。**推理机的判据全在这里** */
is_transitive: boolean;
is_symmetric: boolean;
is_asymmetric: boolean;
is_irreflexive: boolean;
/** 指向另一个关系的两条:`p⁻¹ = q` 与 `p ⊑ q`。是 id 不是布尔,
* 所以界面上是下拉框 */
inverse_of: string | null;
sub_property_of: string | null;
builtin: boolean;
description: string;
/** relation(宾语是实体)| attribute(宾语是字面值) */
kind: "relation" | "attribute";
/** 可以当主语的类。attribute 至少一个;relation 留空 = 不限 */
domains: string[];
/** 可以当宾语的类。只对 relation 有意义——attribute 的值域是 datatype */
ranges: string[];
/** 这条关系的边能带哪些属性(0037):属性定义的 id */
qualifiers: string[];
datatype: "text" | "number" | "date" | "bool" | null;
unit: string | null;
usage: number;
}
/** 一条能力问题(0061 决定 1):本体该答得上来的问题,代理提本体时照着看 */
export interface CompetencyQuestion {
id: string;
kb_id: string;
question: string;
expected_answer: string | null;
needs: unknown | null;
origin: "person" | "agent";
status: "accepted" | "proposed" | "rejected" | "retired";
created_at: string;
updated_at: string;
last_checked_at: string | null;
last_result: unknown | null;
}
/** 本体的两个数(0061 决定 5) */
export interface QuestionReport {
questions: {
accepted: number;
proposed: number;
checked: number;
answered: number;
/** 答上了且途中从图谱拿到过事实 */
answered_with_graph: number;
/** 答上了且只走了图谱:本体本身答的 */
answered_graph_only: number;
};
proposals: {
open: number;
adopted: number;
adopted_edited: number;
rejected: number;
decided: number;
changed: number;
changed_share: number | null;
};
/** 文档说了、本体还放不下的:没有类的类别词、没绑到属性的短语形状(代理读的就是这两样) */
uncovered: { kind_words: number; phrases: number };
}
/** 一条谓词的一端挂着两个以上开放值(#341)。
*
* 本体自己长出来的库里没人声明过唯一性,于是接任不闭合前任:两条 `leads`
* 都开着,"六月谁在管"两个都答。引擎不自动推断这个公理(它驱动账本改写),
* 所以只能把证据摆出来问人。 */
export interface UniquenessCandidate {
predicate_id: string;
key: string;
label: string;
kind: string;
/** subject = 主语侧(functional);object = 宾语侧(inverse functional) */
side: "subject" | "object";
axiom: "functional" | "inverse_functional";
/** 已经声明过、只是还没对过账(导入的,或声明之前就在的行) */
declared: boolean;
holders: number;
open_facts: number;
/** 对账会闭合几条,几条拿不准要进人审 */
would_close: number;
would_review: number;
examples: {
holder: string;
values: {
fact_id: string;
name: string | null;
valid_from: string | null;
confidence: number;
}[];
}[];
}
/** `description` 与 `reason` 不是一回事:description 逐字进抽取提示词,是模型判断
"什么算这个类"的唯一依据;reason 只是给人看的"为什么该加"。喂错了这个类会成为
下一个倾倒场——实测 technology 就是这么来的。 */
/** 代理提的一条多带的几格(0061):谁提的、服务哪些问题、会绑上哪些形状。
Suggest 的一份没有这些,渲染照旧 */
export interface AgentProposalFields {
proposed_by?: "suggest" | "agent";
/** 服务的能力问题 id */
serves?: string[];
/** 会归到这个类下的类别词 */
kind_words?: string[];
/** 原文里的几句,给人核对定义用 */
examples?: string[];
/** 本体里离这条提案最近的已有元素(按向量):采纳前看它是不是其实已经有了 */
closest?: { key: string; label: string; distance: number }[];
domains?: string[];
ranges?: string[];
parents?: string[];
signatures?: {
phrases?: {
phrase: string;
subject: string | null;
object: string | null;
value: boolean;
/** map_to 的形状:读属性的方向 forward | reverse */
direction?: string;
}[];
kind_words?: string[];
};
}
export interface OntologyProposals {
entity_types: (AgentProposalFields & {
key: string;
label: string;
description?: string;
reason?: string;
})[];
relation_types: (AgentProposalFields & {
key: string;
label: string;
temporal?: string;
functional?: boolean;
description?: string;
reason?: string;
/** 这条关系归并了哪些表层说法。有它才谈得上把等待的事实改写过去 */
forms?: string[];
})[];
/**
* 宾语是字面值的说法("成立日期 = 2015")。
*
* 跟 relation_types 分开是因为它们要的东西不一样:属性有 datatype,
* 而把它当关系建出来,那个值就会变成一个假实体。domain 不在这里——
* 服务端从事实的主语类型里取,猜错会让整条被丢弃
*/
attribute_types?: (AgentProposalFields & {
key: string;
label: string;
datatype?: string;
unit?: string;
description?: string;
reason?: string;
forms?: string[];
})[];
/**
* 本体里**已经有**这个意思,只需把说法挂过去。
*
* 跟 relation_types 的区别是不建东西:同一个意思长出第二个 key,
* 这批事实就永久分在两处,谁也认不出它们本是一回事。
*/
map_to?: (AgentProposalFields & {
key: string;
/** 服务端标的:目标落在关系还是属性上。两条改写路径不一样,
而模型只答得出一个 key,看不出它在哪一档。代理提的还有 class */
kind?: string;
/** 代理提的:目标的标签,人看键看不懂 */
label?: string;
forms?: string[];
reason?: string;
})[];
}
/** 一个类/属性在这次导入里的去向。key_taken = key 被另一个 IRI 占着,报告但不动 */
export interface PlannedItem {
iri: string;
key: string;
label: string;
has_description: boolean;
disposition: "create" | "update" | "key_taken" | "aligned" | "superseded";
functional?: boolean;
conflict_with?: string | null;
}
/** 预览与落库返回同一个计划:点确认之后发生的事就是刚看过的事 */
export interface ImportPlan {
format: string;
triples: number;
classes: PlannedItem[];
relations: PlannedItem[];
attributes: PlannedItem[];
/** 出现过但今天不消费的公理 → 次数。不是已跳过,是暂未投影 */
unprojected: [string, number][];
classes_without_description: number;
functional_relations: number;
}
/** 一次导入记下的账。**键与 `owl_import.rs` 写进 `summary` 的一一对应**;
* 全是可选的——老记录可能缺字段,界面按缺失处理而不是显示 0 */
export interface OntologyImportSummary {
classes_created?: number;
classes_updated?: number;
classes_key_taken?: number;
classes_without_description?: number;
relations_seen?: number;
relations_created?: number;
relations_superseded?: number;
relations_updated?: number;
functional_relations?: number;
/** 逆属性 / 父属性连上了几条——目标 IRI 不在这个库里时会静默跳过 */
inverse_linked?: number;
sub_property_linked?: number;
attributes_seen?: number;
attributes_created?: number;
/** **按原因分组的计数**,不是一个数:`{no_domain: 3, unknown_domain: 1}`。
* 跳过一个属性的理由不止一种,而理由才是人下一步要处理的东西 */
attributes_skipped?: Record<string, number>;
/** 没投影下来的 IRI 与出现次数(服务端最多记 30 条) */
unprojected?: [string, number][];
triples?: number;
}
export interface OntologyImportView {
id: string;
filename: string;
format: string;
byte_size: number;
summary: OntologyImportSummary;
imported_by_name: string | null;
imported_at: string;
}
export interface Source {
n: number;
/** 缺省 = 文档 chunk 引用;charter = 内置手册(跳 /docs/{slug}#{anchor}) */
kind?: "charter";
chunk_id?: string;
document_id?: string;
slug?: string;
anchor?: string;
heading?: string;
filename: string;
excerpt: string;
/** 块里被引到的那几句(图谱事实的引文,#968 的后续):界面在原文里把它们标出来 */
quotes?: string[];
}
/** Agentic 对话的行动轨迹(工具调用一步一条)。 */
export interface ChatStep {
kind:
| "search"
| "document"
| "docs"
| "entity"
| "facts"
| "neighbors"
| "timeline"
| "path"
| "changes"
| "query"
| "tool";
/** 数据:查询、实体名、来源名、工具名。照原样显示 */
label: string;
/** 服务端写的英文。**有 `status` 的步骤不读它**,界面按下面的字段自己说(#942);
* 那之前存下的消息只有它。问数与 remember 的 detail 是数据(目的、记下的那句话) */
detail: string;
status?: "ok" | "failed" | "not_found" | "invalid";
/** 列出了几个;`total` 是一共有几个(列出来的少于有的时候) */
count?: number;
total?: number;
/** 列到上限就停了,后面可能还有,总数不知道 */
more?: boolean;
/** 世界时间:问的是那时成立的事实。RFC 3339 */
valid_at?: string;
/** 记录时间:按那时(`as_of`)或那之前(`before`)记下的。RFC 3339 */
as_of?: string;
before?: string;
/** changes 的窗口,YYYY-MM-DD;没有 until 就是开到现在 */
since?: string;
until?: string;
/** paths_between:最短的那条几跳 */
hops?: number;
/** 参数不对时是哪一个;`missing` 分开没给与给错了 */
param?: string;
missing?: boolean;
/** 问数跑的那条 SQL(#936) */
sql?: string;
/** `remember` 那一步带着它:那句记忆落成的 chunk。对话里的确认卡按它取
* 待确认项(0015);回放时也据此重画 */
chunk_id?: string;
/** 这一步发生时正文已经有多长(UTF-16 码元,与 `string.length` 同一单位)。
* 据此把轨迹穿回正文里,而不是全堆在最前面。
* **这条迁移之前的消息没有它**——缺省时整段轨迹回到顶部,即旧的样子 */
at?: number;
}
/** 会话行(Chat 左栏列表)。 */
export interface ConversationRow {
id: string;
title: string;
created_at: string;
updated_at: string;
message_count: number;
}
/** 会话消息(含落库的行动轨迹与引用,历史回放用)。 */
export interface ConversationMessage {
id: string;
role: "user" | "assistant";
content: string;
steps: ChatStep[];
sources: Source[];
stopped: boolean;
created_at: string;
}
/** 告警中心的一组(0005):**连着的、同类的几次故障**。
*
* 存储那边仍是一次故障一行,折叠在服务端读的时候做——这样翻页数的是组,
* 一段连续故障不会被页边界切断。 */
export type AlertGroup = {
kb_id: string | null;
/** 系统级告警没有库名 */
kb_name: string | null;
/** `source.sync_failed` / `llm.unreachable` —— 措辞在 i18n 里按这个查 */
kind: string;
severity: "info" | "warning" | "error";
/** 这一组几次 */
count: number;
/** 其中我没读过的几次 */
unread: number;
latest_at: string;
/** 跟 latest_at 一起圈出这一组,标已读时原样发回去 */
earliest_at: string;
/** 明细,最多几条,新的在前 */
lines: {
name?: string;
error?: string;
job?: string;
warnings?: {
kind: string;
detail: Record<string, unknown>;
}[];
}[];
};
export const api = {
health: () =>
request<{ status: string; name: string; version: string }>(
"/api/v1/health",
),
me: () => request<User>("/api/v1/auth/me"),
alerts: (o: { q?: string; limit?: number; offset?: number }) => {
const p = new URLSearchParams();
if (o.q?.trim()) p.set("q", o.q.trim());
if (o.limit != null) p.set("limit", String(o.limit));
if (o.offset) p.set("offset", String(o.offset));
return request<{ items: AlertGroup[]; total: number }>(
`/api/v1/alerts?${p}`,
);
},
alertsUnread: () => request<{ unread: number }>("/api/v1/alerts/unread"),
/** 失败任务回队列(#216)。库内一条、全局一条(管理员);范围可按种类与失败时间收窄 */
failedJobs: (kbId: string) =>
request<{ failed: number }>(`/api/v1/kbs/${kbId}/jobs/failed`),
requeueJobs: (
kbId: string | null,
body: { kind?: string; failed_since?: string } = {},
) =>
request<{ requeued: number }>(
kbId ? `/api/v1/kbs/${kbId}/jobs/requeue` : "/api/v1/jobs/requeue",
{ method: "POST", body: JSON.stringify(body) },
),
alertReadGroup: (g: {
kb_id: string | null;
kind: string;
from: string;
to: string;
}) =>
request<{ marked: number }>("/api/v1/alerts/read-group", {
method: "POST",
body: JSON.stringify(g),
}),
alertsReadAll: () =>
request<{ ok: boolean }>("/api/v1/alerts/read-all", { method: "POST" }),
login: (email: string, password: string) =>
request<{ user: User }>("/api/v1/auth/login", {
method: "POST",
body: JSON.stringify({ email, password }),
}),
register: (email: string, password: string, displayName: string) =>
request<{ user: User; workspace: Workspace }>("/api/v1/auth/register", {
method: "POST",
body: JSON.stringify({ email, password, display_name: displayName }),
}),
logout: () =>
request<{ ok: boolean }>("/api/v1/auth/logout", { method: "POST" }),
updateMe: (displayName: string) =>
request<User>("/api/v1/auth/me", {
method: "PATCH",
body: JSON.stringify({ display_name: displayName }),
}),
changePassword: (currentPassword: string, newPassword: string) =>
request<{ ok: boolean }>("/api/v1/auth/password", {
method: "POST",
body: JSON.stringify({
current_password: currentPassword,
new_password: newPassword,
}),
}),
/** 我发过的个人令牌(0014)。撤销过的也在——撤过这件事本身要看得见 */
tokens: () => request<{ tokens: TokenView[] }>("/api/v1/me/tokens"),
/** 发一枚。**明文只在这一次的响应里**,列表永远给不出它 */
issueToken: (body: {
name: string;
scope: "read" | "write";
/** 缺省 = 这个人能进的全部库 */
kb_ids?: string[] | null;
/** 0 = 不过期 */
expires_in_days: number;
}) =>
request<{ token: string; info: TokenView }>("/api/v1/me/tokens", {
method: "POST",
body: JSON.stringify(body),
}),
revokeToken: (tokenId: string) =>
request<{ ok: boolean }>(`/api/v1/me/tokens/${tokenId}`, { method: "DELETE" }),
workspaces: () => request<Workspace[]>("/api/v1/workspaces"),
/** 这个工作区,以及**我在里面是什么角色**。建库要 Admin+(见 api/kbs.rs
* 的 create),而 `GET /workspaces` 那份列表不带角色 */
workspaceRole: (workspaceId: string) =>
request<{ workspace: Workspace; role: string }>(
`/api/v1/workspaces/${workspaceId}`,
),
kbs: (workspaceId: string) =>
request<Kb[]>(`/api/v1/workspaces/${workspaceId}/kbs`),
/** 审计台账。**分页 + 筛选**——台账是合规材料,只看最近 100 条等于查不了历史。
* `action` 是前缀:`entity.` 捞出 entity.retyped / entity.renamed 一族。 */
kbAudit: (
kbId: string,
opts: {
action?: string;
actor?: string;
since?: string;
until?: string;
limit: number;
offset: number;
},
) => {
const p = new URLSearchParams({
limit: String(opts.limit),
offset: String(opts.offset),
});
if (opts.action) p.set("action", opts.action);
if (opts.actor) p.set("actor", opts.actor);
if (opts.since) p.set("since", opts.since);
if (opts.until) p.set("until", opts.until);
return request<{
events: AuditEvent[];
total: number;
/** 这个库实际发生过的动作,筛选下拉按它填 */
actions: string[];
}>(`/api/v1/kbs/${kbId}/audit?${p}`);
},
myKbs: (workspaceId: string) =>
request<{ kbs: MyKb[] }>(`/api/v1/workspaces/${workspaceId}/my-kbs`),
createKb: (
workspaceId: string,
body: {
name: string;
description?: string | null;
visibility?: string;
/** 预置本体包 id,顺序有意义:第一个会认领同名的种子类 */
ontology_packs?: string[];
},
) =>
request<Kb>(`/api/v1/workspaces/${workspaceId}/kbs`, {
method: "POST",
body: JSON.stringify(body),
}),
ontologyPacks: () =>
request<{ packs: OntologyPack[] }>("/api/v1/ontology-packs"),
kbDetail: (kbId: string) => request<Kb>(`/api/v1/kbs/${kbId}`),
updateKb: (kbId: string, body: Record<string, unknown>) =>
request<Kb>(`/api/v1/kbs/${kbId}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
deleteKb: (kbId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}`, { method: "DELETE" }),
kbMembers: (kbId: string) =>
request<{ members: KbMember[] }>(`/api/v1/kbs/${kbId}/members`),
setKbMember: (kbId: string, userId: string, role: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/members/${userId}`, {
method: "PUT",
body: JSON.stringify({ role }),
}),
removeKbMember: (kbId: string, userId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/members/${userId}`, {
method: "DELETE",
}),
adminDeployment: () =>
request<{
open_registration: boolean;
/** 外层兜底,防任务无限堆积;真正的节流是按模型的限额 */
worker_concurrency: number;
default_model_concurrency: number;
/** 新建知识库的本体语言默认值。**不是界面语言**——那个在客户端 */
default_ontology_lang: "en" | "zh";
model_limits: {
base_url: string;
model: string;
max_concurrent: number;
}[];
models_in_use: { base_url: string; model: string; kind: string }[];
}>("/api/v1/admin/deployment"),
saveAdminDeployment: (
openRegistration: boolean,
workerConcurrency?: number,
defaultModelConcurrency?: number,
modelLimit?: {
base_url: string;
model: string;
max_concurrent: number | null;
},
defaultOntologyLang?: "en" | "zh",
) =>
request<{ ok: boolean }>("/api/v1/admin/deployment", {
method: "PUT",
body: JSON.stringify({
open_registration: openRegistration,
...(workerConcurrency !== undefined
? { worker_concurrency: workerConcurrency }
: {}),
...(defaultModelConcurrency !== undefined
? { default_model_concurrency: defaultModelConcurrency }
: {}),
...(modelLimit ? { model_limit: modelLimit } : {}),
...(defaultOntologyLang
? { default_ontology_lang: defaultOntologyLang }
: {}),
}),
}),
adminCreateUser: (body: {
email: string;
display_name: string;
password: string;
role: string;
}) =>
request<{ user: User }>("/api/v1/admin/users", {
method: "POST",
body: JSON.stringify(body),
}),
/** 已停用的账号。**没有它恢复就够不着**——那个人从所有列表里消失,
* 而恢复接口要的正是他的 id */
deactivatedUsers: () => request<OrgUser[]>("/api/v1/users/deactivated"),
/** 恢复一个停用的账号 */
adminReactivateUser: (userId: string) =>
request<{ ok: boolean }>(`/api/v1/admin/users/${userId}`, {
method: "POST",
}),
/** 停用一个账号(软删除)。归因照旧查得到——审计、合并日志、改类账本都靠它 */
adminDeactivateUser: (userId: string) =>
request<{ ok: boolean }>(`/api/v1/admin/users/${userId}`, {
method: "DELETE",
}),
/** 授予或收回系统管理员(#1233) */
adminSetSystemAdmin: (userId: string, isAdmin: boolean) =>
request<{ ok: boolean }>(`/api/v1/admin/users/${userId}`, {
method: "PUT",
body: JSON.stringify({ is_admin: isAdmin }),
}),
adminDataSources: () =>
request<{ data_sources: DataSourceView[] }>("/api/v1/admin/data-sources"),
adminCreateDataSource: (body: { name: string; conn_string: string }) =>
request<{ id: string }>("/api/v1/admin/data-sources", {
method: "POST",
body: JSON.stringify(body),
}),
adminDeleteDataSource: (id: string) =>
request<{ ok: boolean }>(`/api/v1/admin/data-sources/${id}`, {
method: "DELETE",
}),
/** 存之前先试一次:**不落库**。回来的是 ok,连不上时还有一句原因——
* 密码错、库名拼错、端口不通是三件不同的事 */
adminTestConnString: (conn_string: string) =>
request<{ ok: boolean; engine?: string; error?: string }>(
"/api/v1/admin/data-sources/test",
{ method: "POST", body: JSON.stringify({ conn_string }) },
),
adminTestDataSource: (id: string) =>
request<{ ok: boolean }>(`/api/v1/admin/data-sources/${id}/test`, {
method: "POST",
}),
/** 这个源授权给了哪些工作区(0014)。授权与挂载是两层:
* 授权由系统管理员写,挂载由 KB 管理员在授权过的集合里挑 */
dataSourceGrants: (id: string) =>
request<{ workspaces: { id: string; name: string }[] }>(
`/api/v1/admin/data-sources/${id}/grants`,
),
grantDataSource: (id: string, workspaceId: string) =>
request<{ ok: boolean }>(
`/api/v1/admin/data-sources/${id}/grants/${workspaceId}`,
{ method: "PUT" },
),
/** 收回授权。**连同该工作区里已挂上的一起卸掉**,返回卸了几个 */
revokeDataSource: (id: string, workspaceId: string) =>
request<{ ok: boolean; unmounted: number }>(
`/api/v1/admin/data-sources/${id}/grants/${workspaceId}`,
{ method: "DELETE" },
),
/** 一页口径。**Viewer 就能看**——问数的答案直接由口径决定,
* 看得见答案却看不见口径,等于要人信一个不给看的算法 */
mappings: (
kbId: string,
opts: {
status?: "proposed" | "confirmed" | "rejected";
q?: string;
limit?: number;
offset?: number;
} = {},
) => {
const p = new URLSearchParams();
if (opts.status) p.set("status", opts.status);
if (opts.q) p.set("q", opts.q);
if (opts.limit != null) p.set("limit", String(opts.limit));
if (opts.offset != null) p.set("offset", String(opts.offset));
const qs = p.toString();
return request<{
items: ConceptMapping[];
total: number;
counts: { proposed: number; confirmed: number; rejected: number };
// 最近一轮探索的账(#503)。单看列表答不了「漏了多少」——
// 十二条提议对着八十列的宽表与刚好覆盖完一个小库长得一样。
last_run?: {
id: string;
started_at: string;
finished_at: string | null;
sources: string[];
tables_scanned: number;
columns_scanned: number;
schema_truncated: boolean;
cap: number;
returned: number;
accepted: number;
dropped: Record<string, { n: number; example: string }>;
tables_covered: string[];
error: string | null;
};
}>(`/api/v1/kbs/${kbId}/mappings${qs ? `?${qs}` : ""}`);
},
/** 改一条口径。改之前那一版自动进 revisions */
reviseMapping: (
kbId: string,
mappingId: string,
body: {
table_name?: string | null;
expr?: string | null;
sql?: string | null;
unit?: string | null;
summary?: string | null;
derived: boolean;
},
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/mappings/${mappingId}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
mappingRevisions: (kbId: string, mappingId: string) =>
request<{ revisions: MappingRevision[] }>(
`/api/v1/kbs/${kbId}/mappings/${mappingId}/revisions`,
),
kbDataSources: (kbId: string) =>
request<{ data_sources: DataSourceView[] }>(
`/api/v1/kbs/${kbId}/data-sources`,
),
kbDataSourcesAvailable: (kbId: string) =>
request<{ data_sources: DataSourceView[] }>(
`/api/v1/kbs/${kbId}/data-sources/available`,
),
/** 挂载。**`schema_error` 非空时挂载仍然成了**——源是真挂上的,只是它的
* 库表结构没摄进来,问数看不见有哪些表。同一件事会进告警中心 */
mountDataSource: (kbId: string, dsId: string) =>
request<{
ok: boolean;
schema_tables: number;
schema_error?: string | null;
}>(`/api/v1/kbs/${kbId}/data-sources/${dsId}`, {
method: "PUT",
}),
unmountDataSource: (kbId: string, dsId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/data-sources/${dsId}`, {
method: "DELETE",
}),
exploreMappings: (kbId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/data-sources/explore`, {
method: "POST",
}),
syncDataSourceSchema: (kbId: string, dsId: string) =>
request<{ ok: boolean; schema_tables: number }>(
`/api/v1/kbs/${kbId}/data-sources/${dsId}/sync-schema`,
{ method: "POST" },
),
/** 文库一页。**服务端筛选与分页**——从前一次取回整库、前端切片,
* 而客户端筛选只筛得到已经拿下来的那些 */
documents: (
kbId: string,
opts: {
source?: string;
q?: string;
graph?: string;
/** "deleted" = 「已删除」视图:只列墓碑(#268) */
state?: "deleted";
limit: number;
offset: number;
},
) => {
const p = new URLSearchParams({
limit: String(opts.limit),
offset: String(opts.offset),
});
if (opts.source) p.set("source", opts.source);
if (opts.q) p.set("q", opts.q);
if (opts.graph) p.set("graph", opts.graph);
if (opts.state) p.set("state", opts.state);
return request<{
docs: Doc[];
total: number;
/** 下面四个**只按来源作用域算**,不受名字/状态筛选影响——
* 它们是批量按钮的作用范围 */
ready: number;
/** `graph_status = 'done'`:抽取进度条的分子 */
done: number;
extracting: number;
failed: number;
/** 整库的墓碑数(删了、没清的),不随作用域变 */
deleted: number;
}>(`/api/v1/kbs/${kbId}/documents?${p}`);
},
/** 一键重试这个作用域里全部抽取失败的文档 */
retryFailedDocs: (kbId: string, source?: string) =>
request<{ queued: number; found: number }>(
`/api/v1/kbs/${kbId}/documents/retry-failed${source ? `?source=${source}` : ""}`,
{ method: "POST" },
),
/** 整库一次取回:行数按 (文档 × 原因 × 对象) 聚合后很小,避免逐行发请求 */
extractionDrops: (kbId: string) =>
request<{ drops: ExtractionDrop[] }>(
`/api/v1/kbs/${kbId}/extraction-drops`,
),
upload: (kbId: string, files: File[], sourceId?: string) => {
const form = new FormData();
for (const f of files) form.append("files", f, f.name);
const qs = sourceId ? `?source=${sourceId}` : "";
return request<{ created: Doc[]; skipped: unknown[] }>(
`/api/v1/kbs/${kbId}/documents${qs}`,
{ method: "POST", body: form },
);
},
deleteDocument: (id: string) =>
request<{ ok: boolean; deletion_id: string; invalidated_facts: number }>(
`/api/v1/documents/${id}`,
{ method: "DELETE" },
),
/** 撤销删除(#268):文档、分块、随之作废的事实原路复活 */
restoreDocument: (id: string) =>
request<{ ok: boolean }>(`/api/v1/documents/${id}/restore`, { method: "POST" }),
/** 真删(#268 下半):只对已删除的开放,库管理员,不可撤销 */
purgeDocument: (id: string) =>
request<{ ok: boolean; chunks: number; blobs: number }>(
`/api/v1/documents/${id}/purge`,
{ method: "POST" },
),
search: (kbId: string, q: string) =>
request<{ results: SearchResult[] }>(`/api/v1/kbs/${kbId}/search`, {
method: "POST",
body: JSON.stringify({ q }),
}),
settings: (workspaceId: string) =>
request<LlmSettingsView>(`/api/v1/workspaces/${workspaceId}/settings`),
saveSettings: (workspaceId: string, body: Record<string, unknown>) =>
request<{ ok: boolean }>(`/api/v1/workspaces/${workspaceId}/settings`, {
method: "PUT",
body: JSON.stringify(body),
}),
graphOverview: (kbId: string, limit?: number) =>
request<{
nodes: GraphNode[];
edges: GraphEdge[];
/** 库里一共有多少。**与 nodes.length 不是一回事**——画布只画度数最高的
* 那一批,把上限当成规模显示是这个接口从前最误导人的地方 */
total_nodes?: number;
total_edges?: number;
}>(`/api/v1/kbs/${kbId}/graph/overview${limit ? `?limit=${limit}` : ""}`),
/** 邻域视图**没有总数**:它本来就只是一小片,说「共 325 个」没有意义。
* 两个字段声明成可选,好让调用方与总览共用一个类型 */
graphNeighborhood: (kbId: string, entityId: string) =>
request<{
nodes: GraphNode[];
edges: GraphEdge[];
total_nodes?: number;
total_edges?: number;
}>(`/api/v1/kbs/${kbId}/graph/neighborhood?entity=${entityId}&hops=2`),
/** 按名字找实体。**一并回总数**——「宁分勿合」会造出一堆同名,
* 固定十条时想找的那个可能根本不在这十条里 */
searchEntities: (kbId: string, q: string, limit = 10) =>
request<{ entities: GraphNode[]; total: number }>(
`/api/v1/kbs/${kbId}/entities?q=${encodeURIComponent(q)}&limit=${limit}`,
),
entityDetail: (kbId: string, entityId: string) =>
request<{
entity: GraphNode;
facts: EntityFact[];
/** 这个实体的名字(0041):本名、简称、曾用名,各带出处与有效期。
* 名字事实不在 facts 里——它不是一条「关于它的事」 */
names: NameView[];
/** 推出来的那些**单独一个键**,不掺进 facts:混在同一个列表里,
* 用户看不出「文档里写的」和「引擎推的」的区别 */
derived: DerivedFact[];
/** 没落地的派生(0017 §3):连 `derived_facts` 都不在,所以也单独一个键 */
blocked: BlockedDerivation[];
/** 同名的其他实体。**打开面板就给**——合并入口要长在能看见同名的地方,
* 而不是藏在「改一次名」之后 */
same_name: GraphNode[];
}>(`/api/v1/kbs/${kbId}/entities/${entityId}`),
/** 认知变更历史(记录时间轴):服务端分页 */
/** 人工修正实体的类型或名字。同名不拦——返回的 same_name 供界面提示是否合并。 */
updateEntity: (
kbId: string,
entityId: string,
body: { type_id?: string; canonical_name?: string },
) =>
request<{ entity: GraphNode; same_name: GraphNode[] }>(
`/api/v1/kbs/${kbId}/entities/${entityId}`,
{ method: "PATCH", body: JSON.stringify(body) },
),
/** 人工修正一条事实的有效区间(302)。**整体替换**:四个值一起提交,
* 服务端作废旧行、插修正行——不是原地改,所以这次修改会出现在 History 上。 */
updateFactTime: (
kbId: string,
factId: string,
body: {
valid_from: string | null;
valid_from_precision: string | null;
valid_to: string | null;
valid_to_precision: string | null;
note?: string;
},
) =>
request<{
ok: boolean;
unchanged?: boolean;
fact_id?: string;
closed?: number;
conflicts?: number;
}>(`/api/v1/kbs/${kbId}/facts/${factId}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
/** 这个库走到哪一步了(#313):四个页面的空状态共用。只回布尔与计数 */
readiness: (kbId: string) =>
request<Readiness>(`/api/v1/kbs/${kbId}/readiness`),
/* ---- 业务规则(0021 / #277):人写下的判据,引擎按物化的节奏跑 ---- */
rules: (kbId: string) =>
request<{ rules: BusinessRule[] }>(`/api/v1/kbs/${kbId}/rules`),
createRule: (kbId: string, body: RuleInput) =>
request<{ id: string }>(`/api/v1/kbs/${kbId}/rules`, {
method: "POST",
body: JSON.stringify(body),
}),
updateRule: (
kbId: string,
ruleId: string,
body: {
name?: string;
description?: string;
enabled?: boolean;
conditions?: RuleCondition[];
/** 结论整组替换:三格互相定义,只改一格会留下半截状态 */
conclusion?: "typing" | "attribute" | "relation";
conclude_type_id?: string;
conclude_predicate_id?: string;
join_predicate_id?: string;
conclude_value?: unknown;
},
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/rules/${ruleId}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
/** 一条规则此刻标了谁。规则卡片上那个数字点开就是它 */
ruleMatches: (kbId: string, ruleId: string, page = 0, per = 20) =>
request<{ matches: RuleMatch[]; total: number }>(
`/api/v1/kbs/${kbId}/rules/${ruleId}/matches?page=${page}&per=${per}`,
),
/** 一条规则的定义史:改过几次、每一版怎么说 */
ruleVersions: (kbId: string, ruleId: string) =>
request<{ versions: RuleVersion[] }>(`/api/v1/kbs/${kbId}/rules/${ruleId}/versions`),
deleteRule: (kbId: string, ruleId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/rules/${ruleId}`, {
method: "DELETE",
}),
/** 立刻跑一遍。物化默认一小时一轮,而写规则的人想马上看见它推出了什么 */
runRules: (kbId: string) =>
request<{
rules: number;
hits: number;
capped: number;
inserted: number;
invalidated: number;
/** 链跑了几轮:1 就是没有链,2 就是一条规则读了另一条的结论(0030) */
rounds: number;
/** 跑满上限还在产出:链比 MAX_DEPTH 长,后面那几环没接上 */
rounds_capped: boolean;
}>(`/api/v1/kbs/${kbId}/rules/run`, { method: "POST" }),
entityHistory: (kbId: string, entityId: string, page: number, per = 30) =>
request<{ events: EntityHistoryEvent[]; total: number }>(
`/api/v1/kbs/${kbId}/entities/${entityId}/history?page=${page}&per=${per}`,
),
factEvidence: (kbId: string, factId: string) =>
request<{ evidence: Evidence[] }>(
`/api/v1/kbs/${kbId}/facts/${factId}/evidence`,
),
/** 一条派生事实的证明(0002 R2):前提按推导顺序,每条带证据,一路到原句。
* 派生已失效时回 null——不是错误 */
derivedProof: (kbId: string, derivedId: string) =>
request<{ proof: Proof | null }>(
`/api/v1/kbs/${kbId}/derived/${derivedId}/proof`,
),
/** 没落地的派生的证明链(0017 §3):前提在违规的 path 里 */
blockedProof: (kbId: string, violationId: string) =>
request<{ steps: ProofStep[] | null }>(
`/api/v1/kbs/${kbId}/violations/${violationId}/proof`,
),
documentDetail: (id: string) =>
request<{ document: Doc; chunks: ChunkFull[] }>(`/api/v1/documents/${id}`),
extractDocument: (id: string) =>
request<{ job_id: number }>(`/api/v1/documents/${id}/extract`, {
method: "POST",
}),
reprocessDocument: (id: string) =>
request<{ job_id: number }>(`/api/v1/documents/${id}/reprocess`, {
method: "POST",
}),
/** 来源级全量重抽(增量语义:既有决策保留) */
reExtractSource: (kbId: string, sourceId: string) =>
request<{ queued: number }>(
`/api/v1/kbs/${kbId}/sources/${sourceId}/re-extract`,
{
method: "POST",
},
),
/** 图谱重建(清算语义:清空图层后全量重抽;KB admin) */
rebuildGraph: (kbId: string) =>
request<{
entities_removed: number;
facts_removed: number;
queued: number;
}>(`/api/v1/kbs/${kbId}/graph/rebuild`, { method: "POST" }),
ontology: (kbId: string) =>
request<{
entity_types: EntityTypeView[];
relation_types: RelationTypeView[];
}>(`/api/v1/kbs/${kbId}/ontology`),
ontologyRegressions: (kbId: string) =>
request<{ cases: OntologyRegressionCase[] }>(
`/api/v1/kbs/${kbId}/ontology/regressions`,
),
addOntologyRegression: (
kbId: string,
body: {
statement_id: string;
relation_type_id: string;
direction: "forward" | "reverse";
},
) =>
request<{ id: string }>(`/api/v1/kbs/${kbId}/ontology/regressions`, {
method: "POST",
body: JSON.stringify(body),
}),
createEntityType: (kbId: string, body: Record<string, unknown>) =>
request<{ id: string }>(`/api/v1/kbs/${kbId}/ontology/entity-types`, {
method: "POST",
body: JSON.stringify(body),
}),
updateEntityType: (kbId: string, id: string, body: Record<string, unknown>) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/ontology/entity-types/${id}`,
{
method: "PATCH",
body: JSON.stringify(body),
},
),
deleteEntityType: (kbId: string, id: string) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/ontology/entity-types/${id}`,
{
method: "DELETE",
},
),
typeEntities: (kbId: string, typeId: string, page: number, per = 12) =>
request<{
entities: { id: string; name: string; fact_count: number }[];
total: number;
}>(
`/api/v1/kbs/${kbId}/ontology/entity-types/${typeId}/entities?page=${page}&per=${per}`,
),
createRelationType: (kbId: string, body: Record<string, unknown>) =>
request<{ id: string }>(`/api/v1/kbs/${kbId}/ontology/relation-types`, {
method: "POST",
body: JSON.stringify(body),
}),
/** 一端挂着两个以上开放值的谓词(#341):本体没人声明唯一性时接任不闭合前任 */
uniquenessCandidates: (kbId: string) =>
request<{ candidates: UniquenessCandidate[] }>(
`/api/v1/kbs/${kbId}/ontology/uniqueness`,
),
/** 补上声明之后把已经在账上的开放行对一遍。声明本身走 updateRelationType */
reconcileRelationType: (kbId: string, id: string) =>
request<{ corrected: number; conflicts: number }>(
`/api/v1/kbs/${kbId}/ontology/relation-types/${id}/reconcile`,
{ method: "POST" },
),
updateRelationType: (
kbId: string,
id: string,
body: Record<string, unknown>,
) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/ontology/relation-types/${id}`,
{
method: "PATCH",
body: JSON.stringify(body),
},
),
deleteRelationType: (kbId: string, id: string) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/ontology/relation-types/${id}`,
{
method: "DELETE",
},
),
/** 上次算出来、还没人表态的提案(0049)。刷新页面靠它,不必重跑模型 */
storedProposals: (kbId: string) =>
request<OntologyProposals>(`/api/v1/kbs/${kbId}/ontology/proposals`),
/** 一条提案有人拒绝了。改状态不删行——拒绝留痕,下一轮 Suggest 不再刷回待看。
* 只收拒绝:采纳走 adoptProposal,元素和采纳的状态一起提交(0061 决定 3) */
decideProposal: (
kbId: string,
section: string,
key: string,
status: "rejected",
/** 拒绝的理由(0061):下一轮代理读得到 */
reason?: string,
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/ontology/proposals`, {
method: "POST",
body: JSON.stringify({ section, key, status, reason }),
}),
/** 叫本体代理来看一眼(0061 决定 2):排一份任务,结果落在 storedProposals */
proposeOntology: (kbId: string) =>
request<{ queued: boolean }>(`/api/v1/kbs/${kbId}/ontology/propose`, {
method: "POST",
body: "{}",
}),
/** 采纳代理的一条提案(0061 决定 3):元素、回归用例、采纳的状态和后续任务一次提交 */
adoptProposal: (
kbId: string,
section: string,
key: string,
edits?: {
label?: string;
description?: string;
datatype?: string;
domains?: string[];
ranges?: string[];
parents?: string[];
},
) =>
request<{
id: string;
/** 复用时留着没写的形状或类别词,各带人定成了什么:代理读过之后人另定了、和提案不一样的 */
skipped: ({ phrase: string } | { kind_word: string })[];
}>(`/api/v1/kbs/${kbId}/ontology/proposals/adopt`, {
method: "POST",
body: JSON.stringify({ section, key, ...(edits ?? {}) }),
}),
/** 能力问题(0061 决定 1) */
listQuestions: (kbId: string) =>
request<CompetencyQuestion[]>(`/api/v1/kbs/${kbId}/questions`),
createQuestion: (
kbId: string,
body: { question: string; expected_answer?: string },
) =>
request<{ id: string }>(`/api/v1/kbs/${kbId}/questions`, {
method: "POST",
body: JSON.stringify(body),
}),
updateQuestion: (
kbId: string,
qid: string,
body: {
question?: string;
expected_answer?: string;
status?: "accepted" | "rejected" | "retired";
},
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/questions/${qid}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
deleteQuestion: (kbId: string, qid: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/questions/${qid}`, {
method: "DELETE",
}),
/** 让代理给库提问题(0061 决定 1):排任务,结果是 proposed 的问题 */
proposeQuestions: (kbId: string) =>
request<{ queued: boolean }>(`/api/v1/kbs/${kbId}/questions/propose`, {
method: "POST",
body: "{}",
}),
/** 两个数(0061 决定 5) */
questionReport: (kbId: string) =>
request<QuestionReport>(`/api/v1/kbs/${kbId}/questions/report`),
/** 上传本体文件只算出计划,一个字节都不写库 */
previewOntologyImport: (kbId: string, file: File) => {
const form = new FormData();
form.append("file", file, file.name);
return request<{ filename: string; plan: ImportPlan }>(
`/api/v1/kbs/${kbId}/ontology/imports/preview`,
{ method: "POST", body: form },
);
},
/** 执行刚看过的那个计划——服务端重新算一遍,两条路径共用同一段代码 */
applyOntologyImport: (kbId: string, file: File) => {
const form = new FormData();
form.append("file", file, file.name);
return request<{ import_id: string; plan: ImportPlan }>(
`/api/v1/kbs/${kbId}/ontology/imports`,
{ method: "POST", body: form },
);
},
ontologyImports: (kbId: string) =>
request<{ imports: OntologyImportView[] }>(
`/api/v1/kbs/${kbId}/ontology/imports`,
),
sources: (kbId: string) =>
request<{ sources: SourceView[] }>(`/api/v1/kbs/${kbId}/sources`),
createSource: (kbId: string, body: Record<string, unknown>) =>
request<{ source: SourceView; ingest_token?: string | null }>(
`/api/v1/kbs/${kbId}/sources`,
{
method: "POST",
body: JSON.stringify(body),
},
),
sourceToken: (kbId: string, sourceId: string) =>
request<{ ingest_token: string | null }>(
`/api/v1/kbs/${kbId}/sources/${sourceId}/token`,
),
rotateSourceToken: (kbId: string, sourceId: string) =>
request<{ ingest_token: string }>(
`/api/v1/kbs/${kbId}/sources/${sourceId}/rotate-token`,
{ method: "POST" },
),
updateSource: (
kbId: string,
sourceId: string,
body: Record<string, unknown>,
) =>
request<{ source: SourceView }>(`/api/v1/kbs/${kbId}/sources/${sourceId}`, {
method: "PATCH",
body: JSON.stringify(body),
}),
deleteSource: (kbId: string, sourceId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/sources/${sourceId}`, {
method: "DELETE",
}),
cleanupMissing: (kbId: string, sourceId: string) =>
request<{ deleted: number }>(
`/api/v1/kbs/${kbId}/sources/${sourceId}/missing/cleanup`,
{
method: "POST",
},
),
syncSource: (kbId: string, sourceId: string) =>
request<{ queued: boolean }>(
`/api/v1/kbs/${kbId}/sources/${sourceId}/sync`,
{
method: "POST",
},
),
sourceRuns: (kbId: string, sourceId: string) =>
request<{ runs: SyncRun[] }>(
`/api/v1/kbs/${kbId}/sources/${sourceId}/runs`,
),
documentExtractions: (docId: string) =>
request<{ facts: ChunkFact[] }>(`/api/v1/documents/${docId}/extractions`),
/** 审核队列的各档**真实条数**。与列表分开取——列表有一页的上限,数数没有。
* 从前徽标读的是数组长度,而接口固定只回 100 条,于是 164 条写成 100。 */
review: (
kbId: string,
queue: ReviewQueue,
limit: number,
offset: number,
/** 只对 duplicates 有意义:按两边类型的关系筛(#428) */
types: ReviewTypeFilter = "any",
) =>
request<{
counts: ReviewCounts;
queue: ReviewQueue;
/** 只有当前这一档的一页。类型按档不同,调用处按 queue 收窄 */
items: unknown[];
}>(
`/api/v1/kbs/${kbId}/review?queue=${queue}&limit=${limit}&offset=${offset}&types=${types}`,
),
/** 一批重复项同一个动作(#428):每条各自裁、各自记台账,回来逐条说成没成 */
/** `rationale`:人拍板时写的那一句(0026)——什么让你这么定。可不写;写了就跟着
* 决定一起进台账,下一次裁决器和 agent 读到的先例就不只是结果 */
reviewBatch: (kbId: string, ids: string[], action: "merge" | "keep", rationale?: string) =>
request<{
decided: number;
outcomes: { id: string; error: string | null }[];
}>(`/api/v1/kbs/${kbId}/review/batch`, {
method: "POST",
body: JSON.stringify({ ids, action, rationale: rationale || null }),
}),
/** 闭合日期带精度(year | month | day):写多少位就是多少精度,服务端照存 */
closeFact: (kbId: string, factId: string, validTo: string, precision: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/facts/${factId}/close`, {
method: "POST",
body: JSON.stringify({ valid_to: validTo, valid_to_precision: precision }),
}),
resolveConflict: (
kbId: string,
conflictId: string,
body: {
action: "close" | "keep" | "reject_new";
close_at?: string;
close_at_precision?: string;
},
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/conflicts/${conflictId}`, {
method: "POST",
body: JSON.stringify(body),
}),
/** 一句记忆抽出的全部待确认项(0015)。空数组 = 这句话没有等着人的东西了 */
pendingForChunk: (kbId: string, chunkId: string) =>
request<{ items: PendingFactItem[] }>(
`/api/v1/kbs/${kbId}/review/pending?chunk_id=${chunkId}`,
),
decidePending: (kbId: string, pendingId: string, action: "confirm" | "reject") =>
request<{ ok: boolean; fact_id?: string; created?: boolean; conflicts?: number }>(
`/api/v1/kbs/${kbId}/review/pending/${pendingId}`,
{ method: "POST", body: JSON.stringify({ action }) },
),
decideReview: (kbId: string, reviewId: string, action: "merge" | "keep", rationale?: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/review/${reviewId}`, {
method: "POST",
body: JSON.stringify({ action, rationale: rationale || null }),
}),
/** 对一条数据映射口径表态(0011)。改状态不删行——拒绝留痕,下一轮探索不再提议它 */
decideMapping: (
kbId: string,
mappingId: string,
status: "confirmed" | "rejected",
) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/review/mappings/${mappingId}`,
{
method: "POST",
body: JSON.stringify({ status }),
},
),
/** 跑一遍一致性检查。同步返回——纯计算,没有模型调用也没有网络 */
runConsistencyCheck: (kbId: string) =>
request<{
edges: number;
/** **零和零不一样**:没有公理时结论是「没有判据」,不是「未发现矛盾」 */
predicates_with_axioms: number;
found: number;
inserted: number;
cleared: number;
/** 环没搜完的谓词数(#642)。不为零时那些谓词上的环只报了一部分 */
cycles_capped: number;
classes: number;
/** 本体自己的矛盾**单独回**,不加进 found:两个数不是一类东西 */
defects_found: number;
defects_new: number;
}>(`/api/v1/kbs/${kbId}/consistency/check`, { method: "POST" }),
/** 人定一条短语签名:属性与方向,或没有(陈述留在开放图谱)。判定和它的重算任务
* 一次提交,答 202 和 job id(0051);类型化图谱在后台重算,`review` / `graph`
* 事件到了就是算完了,也可以拿 job id 去 `/kbs/{id}/jobs/{job_id}` 问 */
decideAlignmentPhrase: (
kbId: string,
bindingId: string,
property: string | null,
direction: "forward" | "reverse",
/** 只在状态属性下给;null = 不说(只带一个日期的陈述留在开放图谱) */
marks: AlignmentMarks | null,
) =>
request<{ ok: boolean; job_id: number; status: "accepted" }>(
`/api/v1/kbs/${kbId}/review/alignment/phrases/${bindingId}`,
{ method: "POST", body: JSON.stringify({ property, direction, marks }) },
),
/** 人批或驳一条蕴含规则:答 202 和 job id,隐含事实在后台算(0044 决定 3 第五片) */
decideAlignmentRule: (kbId: string, ruleId: string, approve: boolean) =>
request<{ ok: boolean; job_id: number; status: "accepted" }>(
`/api/v1/kbs/${kbId}/review/alignment/rules/${ruleId}`,
{ method: "POST", body: JSON.stringify({ approve }) },
),
/** 人答勘误 agent 留下的一笔(0044 决定 7):批了就执行,否了只记 */
decideErrata: (kbId: string, actionId: string, approve: boolean) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/review/errata/${actionId}`, {
method: "POST",
body: JSON.stringify({ approve }),
}),
/** 人定一个类别词:类,或没有。它名下的实体换类,短语签名跟着重判 */
decideAlignmentKindWord: (kbId: string, kindWord: string, cls: string | null) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/review/alignment/kind-words/${encodeURIComponent(kindWord)}`,
{ method: "POST", body: JSON.stringify({ class: cls }) },
),
/** 对一处本体缺陷表态。**两个出路**——它压根没看数据,没有「数据错了」这条 */
decideDefect: (
kbId: string,
defectId: string,
resolution: "fixed" | "accepted",
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/review/defects/${defectId}`, {
method: "POST",
body: JSON.stringify({ resolution }),
}),
/** 跑一遍推理(R1)。开关关着时后端回 inference_off */
/** 类型消解:**只算不写**。回执里带着送去检索的画像——检索找不着时,
* 第一个要看的就是「我们拿什么去找的」 */
/** 手动合并:把 source 并进 target。**方向要紧**——source 消失,
* 它的事实搬到 target 上;合并可整体回滚(entity_merges 记着快照) */
mergeEntities: (kbId: string, source: string, target: string, rationale?: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/entities/merge`, {
method: "POST",
body: JSON.stringify({ source, target, rationale: rationale || null }),
}),
typeResolutionPreview: (kbId: string) =>
request<{ items: TypeSuggestion[] }>(
`/api/v1/kbs/${kbId}/ontology/type-resolution/preview`,
{ method: "POST" },
),
/** 跑一遍并落库。三档分开回:自动改的、留给人的、说「都不是」的 */
typeResolutionApply: (kbId: string) =>
request<ResolutionOutcome>(`/api/v1/kbs/${kbId}/ontology/type-resolution`, {
method: "POST",
}),
/** 认可一个「粗类 → 细类」的配对,并把带上的实体改过去。
* **认可的是类对,改的是实体**——认可一次,之后同一对不再进人工 */
approveRefinement: (
kbId: string,
body: { from_type_id: string; to_type_id: string; entity_ids: string[] },
) =>
request<{ retyped: number }>(
`/api/v1/kbs/${kbId}/ontology/type-resolution/approve`,
{ method: "POST", body: JSON.stringify(body) },
),
/** 撤销一整批:把那批实体放回原来的类 */
typeResolutionUndo: (kbId: string, batchId: string) =>
request<{ reverted: number }>(
`/api/v1/kbs/${kbId}/ontology/type-resolution/${batchId}`,
{ method: "DELETE" },
),
runInference: (kbId: string) =>
request<{
/** 编译出来的规则条数。为零时是「没有规则」而不是「推不出东西」 */
rules: number;
edges: number;
derived: number;
inserted: number;
/** 前提没了、跟着作废的 */
invalidated: number;
/** 撞上单谓词上限、没推完的谓词个数 */
capped: number;
}>(`/api/v1/kbs/${kbId}/inference/run`, { method: "POST" }),
/** 对一处公理违规表态。三个出路——第三个是这一档独有的:可能是定义错了 */
decideViolation: (
kbId: string,
violationId: string,
resolution: ViolationResolution,
opts: { closeAt?: string; closeAtPrecision?: string; factId?: string } = {},
) =>
request<{ ok: boolean }>(
`/api/v1/kbs/${kbId}/review/violations/${violationId}`,
{
method: "POST",
body: JSON.stringify({
resolution,
close_at: opts.closeAt ?? null,
close_at_precision: opts.closeAtPrecision ?? null,
fact_id: opts.factId ?? null,
}),
},
),
confirmFact: (kbId: string, factId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/facts/${factId}/confirm`, {
method: "POST",
}),
rejectFact: (kbId: string, factId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/facts/${factId}/reject`, {
method: "POST",
}),
revertMerge: (kbId: string, mergeId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/merges/${mergeId}/revert`, {
method: "POST",
}),
reviewSummary: (kbId: string) =>
request<ReviewSummary>(`/api/v1/kbs/${kbId}/review/summary`),
/** 回答 agent 的一笔(0025):merge / keep 答一条建议,revert 撤回一条自动合并,
* merge 也能推翻一条自动分开。走的是人的裁决路径,成为新先例 */
agentAnswer: (
kbId: string,
decisionId: string,
action: "merge" | "keep" | "revert",
rationale?: string,
) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/review/agent/${decisionId}`, {
method: "POST",
body: JSON.stringify({ action, rationale: rationale || null }),
}),
reviewHistory: (kbId: string, page: number, per = 20) =>
request<{ events: ReviewHistoryEvent[]; total: number }>(
`/api/v1/kbs/${kbId}/review/history?page=${page}&per=${per}`,
),
members: (workspaceId: string) =>
request<Member[]>(`/api/v1/workspaces/${workspaceId}/members`),
orgUsers: () => request<OrgUser[]>("/api/v1/users"),
setMemberRole: (workspaceId: string, userId: string, role: string) =>
request<{ ok: boolean }>(
`/api/v1/workspaces/${workspaceId}/members/${userId}`,
{
method: "PUT",
body: JSON.stringify({ role }),
},
),
removeMember: (workspaceId: string, userId: string) =>
request<{ ok: boolean }>(
`/api/v1/workspaces/${workspaceId}/members/${userId}`,
{
method: "DELETE",
},
),
testSettings: (workspaceId: string) =>
request<{
chat: { ok: boolean; reply?: string; error?: string };
embed: { ok: boolean; dim?: number; error?: string };
ocr?: { ok: boolean; version?: string | null; error?: string };
transcribe?: { ok: boolean; error?: string };
}>(`/api/v1/workspaces/${workspaceId}/settings/test`, { method: "POST" }),
/** 读扫描件的服务、转写模型各自一个保存:存它们不碰对话与嵌入那几列。
* `requeued`:因为缺它而等着的文件,这一存重新排进了处理队列几份 */
saveOcrSettings: (
workspaceId: string,
body: { provider: string; base_url: string; api_key: string; backend: string; model: string },
) =>
request<{ ok: boolean; requeued: number }>(
`/api/v1/workspaces/${workspaceId}/settings/ocr`,
{ method: "PUT", body: JSON.stringify(body) },
),
saveTranscribeSettings: (
workspaceId: string,
body: { base_url: string; api_key: string; model: string },
) =>
request<{ ok: boolean; requeued: number }>(
`/api/v1/workspaces/${workspaceId}/settings/transcribe`,
{ method: "PUT", body: JSON.stringify(body) },
),
/** 是否配置了单点登录(0056)。四项环境变量缺一个都是 false——
* 登录页据此决定要不要露出那个按钮 */
oidcStatus: () =>
request<{ enabled: boolean; password_login: boolean }>("/api/v1/auth/oidc/status"),
/** 谁的哪个身份提供方 subject 绑定到了这个部署的哪个账号(只读 + 解绑) */
oidcIdentities: () =>
request<{
issuer: string;
client_id: string;
redirect_uri: string;
identities: OidcIdentity[];
}>("/api/v1/admin/oidc/identities"),
/** 我自己的绑定。绑定本身走 `/api/v1/auth/oidc/start?link=1`,由本人在身份提供方那边完成 */
oidcMe: () =>
request<{ enabled: boolean; linked: boolean; subject?: string | null }>(
"/api/v1/auth/oidc/me",
),
oidcUnlinkMe: () =>
request<{ ok: boolean }>("/api/v1/auth/oidc/me", { method: "DELETE" }),
/** 管理员解绑。没有替人绑定的接口——那是一条冒充别人登录的路 */
oidcUnlink: (userId: string) =>
request<{ ok: boolean }>(`/api/v1/admin/oidc/identities/${userId}`, {
method: "DELETE",
}),
};
/** RAG 对话:SSE 流式。返回中止函数。 */
export const conversationsApi = {
/** **可搜可翻页**:标题会重(同一个问题问两次就重了),而固定一百条之后的
* 会话界面上根本不存在。搜的是标题与消息正文两处——人记得住的往往是
* 问过的那句话,不是标题 */
list: (kbId: string, q = "", limit = 30, offset = 0) => {
const p = new URLSearchParams({
limit: String(limit),
offset: String(offset),
});
if (q.trim()) p.set("q", q.trim());
return request<{ conversations: ConversationRow[]; total: number }>(
`/api/v1/kbs/${kbId}/conversations?${p}`,
);
},
/** 改标题。标题本来是从第一句话自动取的,而一段对话跑偏是常态 */
rename: (kbId: string, id: string, title: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/conversations/${id}`, {
method: "PATCH",
body: JSON.stringify({ title }),
}),
detail: (kbId: string, id: string) =>
request<{ messages: ConversationMessage[] }>(
`/api/v1/kbs/${kbId}/conversations/${id}`,
),
stop: (kbId: string, id: string, generationId: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/chat/${id}/stop`, {
method: "POST",
body: JSON.stringify({ generation_id: generationId }),
}),
remove: (kbId: string, id: string) =>
request<{ ok: boolean }>(`/api/v1/kbs/${kbId}/conversations/${id}`, {
method: "DELETE",
}),
};
export interface ChatHandlers {
/** `messageId`:这一问存下的 id。答到一半失败了,凭它重答(#936);老的服务端不发 */
onConversation: (id: string, messageId?: string, generationId?: string) => void;
onSources: (s: Source[]) => void;
onStep: (s: ChatStep) => void;
onDelta: (text: string) => void;
onDone: (stopped: boolean) => void;
onError: (message: string, error?: ApiError) => void;
/** 接上一个已经在跑的回答:这是它此刻的样子,**覆盖,不是追加** */
onSnapshot?: (s: { generation_id: string; content: string; steps: ChatStep[]; sources: Source[] }) => void;
/** 这个会话没有在跑的生成——最常见的答案,不是错误 */
onIdle?: () => void;
}
/** 接上一个正在生成的回答(刷新页面之后走这里)。
*
* 与 `streamChat` 读的是同一条事件流,只是多了开头那份快照。 */
export function reattachChat(
kbId: string,
conversationId: string,
handlers: ChatHandlers,
): () => void {
return consumeChatStream(
(signal) =>
fetch(`/api/v1/kbs/${kbId}/conversations/${conversationId}/stream`, {
credentials: "include",
signal,
}),
handlers,
true,
);
}
export function streamChat(
kbId: string,
/** `retry_message_id`:重答这场对话最后那个没有回答的问题(#936),不再存一遍 */
body: { conversation_id?: string; message: string; retry_message_id?: string },
handlers: ChatHandlers,
): () => void {
return consumeChatStream(
(signal) =>
fetch(`/api/v1/kbs/${kbId}/chat`, {
method: "POST",
credentials: "include",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal,
}),
handlers,
);
}
/** SSE 的读法只有一份:发起请求的方式不同,收下来之后的处理完全一样。 */
function consumeChatStream(
open: (signal: AbortSignal) => Promise<Response>,
handlers: ChatHandlers,
allowIdle = false,
): () => void {
const controller = new AbortController();
let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
let terminal = false;
const fail = (message: string, error?: ApiError) => {
if (terminal || controller.signal.aborted) return;
terminal = true;
handlers.onError(message, error);
};
(async () => {
try {
const res = await open(controller.signal);
if (controller.signal.aborted) {
await res.body?.cancel();
return;
}
if (!res.ok || !res.body) {
let message = res.statusText;
let code: string | undefined;
try {
const body = (await res.json()) as Refusal;
code = body.code;
message = refusalMessage(body, message);
} catch { /* keep the HTTP status */ }
fail(message, new ApiError(res.status, message, code));
return;
}
reader = res.body.getReader();
const decoder = new TextDecoder();
let trailingCr = false;
const parser = createParser({ onEvent: ({ event, data: value }) => {
if (terminal || controller.signal.aborted) return;
if (event === "done") {
const stopped = JSON.parse(value).stopped === true;
terminal = true;
handlers.onDone(stopped);
}
else if (event === "error") fail(streamFailure(value));
else if (event === "idle") {
if (allowIdle) { terminal = true; handlers.onIdle?.(); }
else fail(S.ask.streamInterrupted);
} else if (event === "conversation") {
const frame = JSON.parse(value);
handlers.onConversation(frame.id, frame.message_id, frame.generation_id);
}
else if (event === "sources") handlers.onSources(JSON.parse(value));
else if (event === "step") handlers.onStep(JSON.parse(value));
else if (event === "delta") handlers.onDelta(JSON.parse(value).text);
else if (event === "snapshot") handlers.onSnapshot?.(JSON.parse(value));
} });
while (!terminal && !controller.signal.aborted) {
const { done, value } = await reader.read();
if (done) {
// v3 holds a final CR until the next character confirms its line ending.
if (trailingCr) parser.feed("\n");
break;
}
if (controller.signal.aborted) break;
const chunk = decoder.decode(value, { stream: true });
if (chunk) trailingCr = chunk.endsWith("\r");
parser.feed(chunk);
}
// EOF never dispatches an incomplete frame and is not an application done.
fail(S.ask.streamInterrupted);
} catch (e) {
fail(e instanceof SyntaxError ? S.ask.streamInterrupted : String(e));
} finally {
if (reader) {
try { await reader.cancel(); } catch { /* terminal/abort already decided */ }
reader.releaseLock();
}
}
})();
return () => {
controller.abort();
void reader?.cancel().catch(() => {});
};
}