Skip to content

操作线上参考(Ops wire reference) ​

操作层为核心 KnowledgeEntry 操作定义传输无关的请求/响应信封。产品可经任意传输承载这些 JSON 载荷 —— 进程内调用、消息队列或 adapter 内的 HTTP 映射 —— 线上保持传输无关。以下字段表溯源到 schemas/ops/ 中的已提交 schema。

KnowledgeEntry 状态迁移与终态KnowledgeEntry 状态迁移与终态

基线操作 ​

Op请求响应语义
upsertUpsertRequestUpsertResponse按稳定 id 创建或更新 KnowledgeEntry(1..n 条;可选幂等键)
extract→promotePromoteRequestPromoteResponse把提取的候选提升为持久 KnowledgeEntry(可选合并目标)
relateRelateRequestRelateResponse创建或更新 Relation
checkCheckRequestCheckResponse在一个 Scope 上运行检查器;返回 Finding[](规则经 rule_refs 和/或内嵌 rules[])
assembleAssembleRequestAssembleResponse为 Scope 返回 AssemblePacket(仅结构)

每个操作都有配对的请求与响应 schema。可选族各自增加配对:l2-computable 下的 project / compute、ke-extraction 下的 extract,以及 33 个操作的 spoke-memory 族。

单一失败方言 ​

每个响应都是成功载荷或 { "error": ErrorEnvelope } 的 oneOf —— 成功与错误分支互斥:

ErrorEnvelope 字段类型说明
code字符串,必填机器可读错误码(开放词汇)
message字符串,必填人类可读错误消息
details开放对象,可选结构化错误上下文
extensionsExtensionMap,必填产品 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_scaleTimelineScaleL5 层级过滤(brief、narrative、moment)
fork_idForkIdL5 分支过滤 —— 对 TimelineEvent.fork_id 严格相等(l5-fork)
viewpoint字符串读者上下文(ke-ownership)—— 读者的 holder KnowledgeEntry entry_id;缺省时不指名主体,也不授予私有可见性
cognitionCognitionSelection认知细化(spoke-cognition)—— 要求已协商的标志,且只提供 current 视图;见认知选择
extensionsExtensionMap产品作用域查询元数据;协议匹配器忽略它,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,保留的分歧绝不取平均或被替换。

未知谓词、未实现的维度或不可用的视图会拒绝整个请求 —— 不静默剥离、不返回部分响应、不回退到未过滤输出:

json
{
  "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 候选 KnowledgeEntryExtractRequestExtractResponse

ExtractRequest / ExtractResponse ​

ExtractRequest 必填:run_id、sources。输入仅含引用:请求携带溯源指针与各自的可选 span。

字段说明
run_id非空不透明关联标识;经 run.run_id 原样回显
sources非空 SourceAnchor[](溯源指针);抽取范围是该列表加上每个锚点的可选 span(span 缺省表示整个被引用制品)
entry_types可选的咨询性提示,说明调用方期望的候选类型;服务方主机可采用或忽略它们
extensions可选传输元数据

ExtractResponse 携带单一分支:成功 { candidates, run } —— 或 失败 { error }。

成功字段说明
candidatesKnowledgeEntry[] —— 每个返回的候选都携带 status: "provisional";空数组是合法的零结果运行
runExtractionRunMetadata —— 必填 run_id(请求的精确回显)、可选非空 method、可选不透明 coverage_hint
extensions可选传输元数据
失败字段说明
errorErrorEnvelope —— 该响应的失败分支
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-memory25 个核心操作: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-reflectionmemory.reflections.state、.list、.generate
spoke-memory-transfermemory.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 拥有持久化。

相关页面 ​