操作线上参考(Ops wire reference)
操作层为核心 KnowledgeEntry 操作定义传输无关的请求/响应信封。产品可经任意传输承载这些 JSON 载荷 —— 进程内调用、消息队列或 adapter 内的 HTTP 映射 —— 线上保持传输无关。以下字段表溯源到 schemas/ops/ 中的已提交 schema。
基线操作
| Op | 请求 | 响应 | 语义 |
|---|---|---|---|
upsert | UpsertRequest | UpsertResponse | 按稳定 id 创建或更新 KnowledgeEntry(1..n 条;可选幂等键) |
extract→promote | PromoteRequest | PromoteResponse | 把提取的候选提升为持久 KnowledgeEntry(可选合并目标) |
relate | RelateRequest | RelateResponse | 创建或更新 Relation |
check | CheckRequest | CheckResponse | 在一个 Scope 上运行检查器;返回 Finding[](规则经 rule_refs 和/或内嵌 rules[]) |
assemble | AssembleRequest | AssembleResponse | 为 Scope 返回 AssemblePacket(仅结构) |
每个操作都有配对的请求与响应 schema。可选族各自增加配对:l2-computable 下的 project / compute、ke-extraction 下的 extract,以及 33 个操作的 spoke-memory 族。
单一失败方言
每个响应都是成功载荷或 { "error": ErrorEnvelope } 的 oneOf —— 成功与错误分支互斥:
| ErrorEnvelope 字段 | 类型 | 说明 |
|---|---|---|
code | 字符串,必填 | 机器可读错误码(开放词汇) |
message | 字符串,必填 | 人类可读错误消息 |
details | 开放对象,可选 | 结构化错误上下文 |
extensions | ExtensionMap,必填 | 产品 namespace 袋 |
操作库的预期拒绝以 SpokeResult 返回,携带 TypeScript 与 Rust 共享的稳定 SpokeRejectCode 字符串(REVISION_CONFLICT、STORED_REVISION_STALE、CANDIDATE_NOT_PROVISIONAL、CANDIDATE_TERMINAL_STATUS、EMPTY_CANONICAL_NAME、RELATION_SELF_EDGE、RELATION_MISSING_ENDPOINT、CAPABILITY_PORT_MISSING、INTERNAL_ERROR 等)。
Scope 选择器
check 与 assemble 共享 Scope 选择器。scope_id 必填;其余细化全部可选:
| 字段 | 类型 | 说明 |
|---|---|---|
scope_id | 字符串,必填 | 协议中立的不透明选择器。产品经 adapter 或 op extensions 映射 World / Book / 章节 / 手稿 id |
entry_ids | 字符串数组 | 收窄到显式 KnowledgeEntry |
entry_types | 字符串数组 | 按开放 entry_type 词汇过滤 |
timeline_event_ids | 字符串数组 | 收窄到显式 L5 TimelineEvent id |
source_id | 字符串 | 溯源或手稿定位符作用域 |
timeline_scale | TimelineScale | L5 层级过滤(brief、narrative、moment) |
fork_id | ForkId | L5 分支过滤 —— 对 TimelineEvent.fork_id 严格相等(l5-fork) |
viewpoint | 字符串 | 读者上下文(ke-ownership)—— 读者的 holder KnowledgeEntry entry_id;缺省时不指名主体,也不授予私有可见性 |
cognition | CognitionSelection | 认知细化(spoke-cognition)—— 要求已协商的标志,且只提供 current 视图;见认知选择 |
extensions | ExtensionMap | 产品作用域查询元数据;协议匹配器忽略它,adapter 原样往返 |
列表细化(entry_ids、entry_types、timeline_event_ids)按存在性匹配:省略的列表视为缺失并匹配全部;显式给出的列表——包括 []——会收窄结果,因此 [] 不匹配任何条目。
认知选择(spoke-cognition)
Scope.cognition 在 check、assemble 与按作用域读取 KnowledgeEntry / TimelineEvent 的端口调用上携带 CognitionSelection。该载体只提供 current 视图:{ view: "current", filter, selection_policy }。recorded_at 形式属于 Memory 来源视图;在此提供会被整体拒绝,而不是返回空投影。
选择在授权之后、投影或任何检查器副作用之前应用:仅当至少一条携带记录满足完整的单记录过滤合取时才保留该 KnowledgeEntry,不携带任何匹配记录的条目被排除。filter 是数据模型参考 §认知所述的封闭语法 —— 每个提供的谓词都在同一条记录上做 AND,谓词绝不跨记录或跨目标连接。
current 形式必须提供 selection_policy,以 { policy_id, policy_version } 命名产品策略。算法由产品提供;库只校验 selected_record_id 属于被追踪的 input_record_ids。结果保留归因:每个 item 保留自己的 holder、target 与 assessment_context,保留的分歧绝不取平均或被替换。
未知谓词、未实现的维度或不可用的视图会拒绝整个请求 —— 不静默剥离、不返回部分响应、不回退到未过滤输出:
{
"error": {
"code": "invalid_input",
"message": "Unsupported cognition requirement",
"details": { "reason": "unsupported_cognition_requirement", "field": "scope.cognition.filter.q" }
}
}携带 Scope.cognition 的请求要求已协商的 spoke-cognition 标志;协商结果缺少该族时,请求走既有 capability_missing 分支,处理器无副作用。参见协议参考 §认知协商与拒绝。
信封字段表
UpsertRequest / UpsertResponse
UpsertRequest 必填:knowledge_entries。响应:{ knowledge_entries: [...], rejected? } 或 { error }。rejected[] 在成功分支携带逐条 { entry_id, code, message }。
| 字段 | 说明 |
|---|---|
knowledge_entries | 要创建或更新的 KnowledgeEntry |
idempotency_key | 不透明幂等提示(协议 v0.1 无服务端语义) |
extensions | 可选传输元数据 |
PromoteRequest / PromoteResponse
PromoteRequest 必填:candidate。响应:{ knowledge_entry, superseded_id? } 或 { error }。
| 字段 | 说明 |
|---|---|
candidate | 候选 KnowledgeEntry(通常 status 为 provisional) |
target_entry_id | 可选合并目标 KnowledgeEntry id;响应随之携带 superseded_id |
RelateRequest / RelateResponse
RelateRequest 必填:relation。响应:{ relation } 或 { error }。
| 字段 | 说明 |
|---|---|
relation | 要创建或更新的 Relation(经 revision 做 OCC) |
CheckRequest / CheckResponse
CheckRequest 必填:scope。响应:{ findings: [...] } 或 { error }。
| 字段 | 说明 |
|---|---|
scope | 检查器作用域选择器 |
rule_refs | 不透明规则 id 或 URI;未被 rules[] 覆盖时由接收方解析 |
rules | 可选内嵌 Rule 对象,用于可移植交换(按 rule_id 覆盖) |
checker_kinds | 可选检查器种类过滤 |
extensions | 可选传输元数据 |
AssembleRequest / AssembleResponse
AssembleRequest 必填:scope。响应:{ packet } 或 { error }。
| 字段 | 说明 |
|---|---|
scope | 组装作用域选择器 |
max_entries | 可选条目数量提示(协议不强制) |
extensions | 可选传输元数据 |
当 scope.cognition 存在时,packet.cognition 是在已授权来源集上选出的 CognitionProjection { view, items[], extensions }。每个 item 携带自己的 holder、target、assessment_context、presence(assessed 或 no_record)与 assessments[];current 的已评估 item 还携带 selection: { policy, input_record_ids[], selected_record_id }。投影在 max_entries 截断之前计算 —— 限额只收窄精简的包条目,绝不改变请求了哪些已授权认知 —— 请求不带认知选择时该字段缺省。参见数据模型参考 §认知。
可选操作(ke-extraction)
extract 是 ke-extraction 能力标志下的可选操作族,由既有 input-source 角色的主机提供;五个基线操作族保持不变。它从被引用的源材料提议 provisional 候选 KnowledgeEntry。
| Op | 意图 | 请求 | 响应 |
|---|---|---|---|
extract | 从被引用的源材料提议 provisional 候选 KnowledgeEntry | ExtractRequest | ExtractResponse |
ExtractRequest / ExtractResponse
ExtractRequest 必填:run_id、sources。输入仅含引用:请求携带溯源指针与各自的可选 span。
| 字段 | 说明 |
|---|---|
run_id | 非空不透明关联标识;经 run.run_id 原样回显 |
sources | 非空 SourceAnchor[](溯源指针);抽取范围是该列表加上每个锚点的可选 span(span 缺省表示整个被引用制品) |
entry_types | 可选的咨询性提示,说明调用方期望的候选类型;服务方主机可采用或忽略它们 |
extensions | 可选传输元数据 |
ExtractResponse 携带单一分支:成功 { candidates, run } —— 或 失败 { error }。
| 成功字段 | 说明 |
|---|---|
candidates | KnowledgeEntry[] —— 每个返回的候选都携带 status: "provisional";空数组是合法的零结果运行 |
run | ExtractionRunMetadata —— 必填 run_id(请求的精确回显)、可选非空 method、可选不透明 coverage_hint |
extensions | 可选传输元数据 |
| 失败字段 | 说明 |
|---|---|
error | ErrorEnvelope —— 该响应的失败分支 |
extensions | 可选传输元数据 |
provisional 不变量。 库只准入 status 为 provisional 的候选。当任一候选携带其他状态时,整个集合被拒绝并返回错误分支 —— merged / deleted 条目给出 CANDIDATE_TERMINAL_STATUS,其他状态给出 CANDIDATE_NOT_PROVISIONAL;被准入的候选保持抽取器产出的状态,成功响应并原样回显请求的 run_id。
extract 与 extract→promote 的区别。 基线 extract→promote 行覆盖准入:promote 把单个 provisional 候选准入持久存储。可选 extract 操作覆盖产出:它从被引用的源材料提议 provisional 候选。抽取产物经 promote 到达持久存储。
可选族(spoke-memory)
面向按主体记忆的 33 个操作,分属三个能力标志。每个操作都有配对的请求/响应 schema,命名为 memory-<segments>-{request,response}.schema.json —— memory.records.promote 对应 memory-records-promote-request.schema.json / memory-records-promote-response.schema.json。
| 能力 | 操作 |
|---|---|
spoke-memory | 25 个核心操作:memory.describe、memory.spaces.list / .freeze / .unfreeze、memory.subjects.ensure / .get / .fence、memory.grants.list / .grant / .revoke、memory.capture、memory.candidates.list / .get / .dismiss / .review、memory.records.create / .get / .update / .delete / .list / .promote、memory.recall、memory.profile.get / .update、memory.receipts.get |
spoke-memory-reflection | memory.reflections.state、.list、.generate |
spoke-memory-transfer | memory.exports.create、.get,memory.imports.stage、.activate、.discard |
族规则。 读操作返回其载荷;每个变更操作返回 MemoryReceipt(committed / pending / failed),其 result 只携带 ID、revision、计数、结果枚举、摘要与成本事实。失败分支为 { error } —— 共享信封形状,且 details.retry_class 必填(retryable / terminal / uncertain)。除 memory.subjects.ensure 外,每个变更操作都要求 idempotency_key,条件写入要求 expected_revision。逐操作的授权能力、请求字段与错误码见 记忆参考 与族规格。
共享规则
- Check ≠ Assemble ——
check只返回 findings;assemble只返回包。 $ref组合 —— ops schema 以$ref引用数据层类型,每个类型只定义一次。- 纯度 —— 操作库相对主机 I/O 是纯函数:存储访问、LLM 调用、ranking、retrieval 与传输绑定由产品经注入的 adapter ports 提供。库运行协议门禁;adapter 拥有持久化。
相关页面
- 协议参考 —— 三列模型与能力标志。
- 编排操作(orchestrate ops) —— 用真实签名调用每个编排器。
- 数据模型参考 —— 这些信封携带的对象。
- 认知记录 —— 记录形状、
q、封闭过滤语法与投影。 - connect 参考 —— ops 信封作为不透明 invoke 载荷被包装。
- 记忆参考 —— 可选
spoke-memory族的 33 个操作、能力划分与提供方指引。