@jangts/agent-core 0.3.5 → 0.5.0

package/development/docs/api/kits.md

@@ -2,13 +2,15 @@
 
 [共同类型](types.md) · [返回首页](README.md)。每个 Kit 从自己的子路径导入具名函数／构造器，静态声明与每次运行上下文分离。
 
-## Intents、Interaction、Tools
+## Domain Tools、Scope、Interaction、Tools
+
+IntentRegistry 注册继承 ModelTool 的 IntentTool，保留 scopePolicy、targetPolicy 和任务约束。asIntent.delegates 可覆盖推导结果；delegates 是可选允许集合，不是顺序。不存在独立 Intent 实体或 Intent ID；Scope 的 goalIds 引用真实 Tool ID。可选注册辅助从 `@jangts/agent-core/kits/domains` 导入。
 
 | 能力 | 首选接口／关键合同 |
 | --- | --- |
 | IntentRegistry | 定义主键 id，使用 scopePolicy/targetPolicy，实现共同 Registry 合同 |
-| ScopeRegistry | id、intentIds、toolIds、queryScopeIds、knowledgeTopicIds；aliases保留，查询方法使用scopeId |
-| defineAgentCatalog | 由实际登记投影关系；当前任务为`{ intentId, scopeId? }`，不能同时用scope指策略和引用 |
+| ScopeRegistry | id、goalIds、toolIds、queryScopeIds、knowledgeTopicIds；aliases保留，查询方法使用scopeId |
+| defineAgentCatalog | 由实际登记投影关系；当前任务为`{ goalId, scopeId? }`，不能同时用scope指策略和引用 |
 | defineInteractionProtocol | 一份commands声明编译协议，commandField由App拥有，不强制其wire字段叫type或kind |
 | defineCommandCatalog | commands闭集可用Record书写；公开definitions为数组，toRecord()为明确映射 |
 | bindInteraction | 对齐协议与具名handler；dispatch(input, context)，不执行未登记命令 |
@@ -20,7 +22,7 @@
 
 InteractionProtocol、CommandCatalog 是公开构造器；Interaction 与 Interaction.Commands 分别提供它们的命名空间入口。
 
-Tools Kit保留全局检查→选中检查→授权→resume/execute→完成→finalize的真实次序。生命周期和contribution是本Kit局部协议。接收者字段叫receiver，不与OutputField.owner混用；请求内journal沿用Core分配的invocationId。
+Tools Kit 保留全局检查→授权→resume/execute→完成→finalize 的真实次序。每个工具只声明一个 lifecycle 块：inspect、finalize 等钩子对全部工具运行，id/protocol/call 与 authorize/resume/complete 只由被选中的工具运行。接收者字段叫receiver，不与OutputField.owner混用；请求内journal沿用Core分配的invocationId。
 
 ## Evidence 与 Retrieval
 
@@ -72,6 +74,22 @@ TextSkill 定义使用 id、entry、toolIds 和 kind=text-workflow。目录项
 
 TextSkillLoader 接受 load({ entries }, { read })。注册 ID、路径、工具引用和重复项检查先于对应文件读取，read 与自定义解析器均须同步。读取端口、注册项和错误工厂可以由类实现，原型 getter 与原方法接收者保留。工具回执的 App 自有字段由 App 显式投影。
 
+## TextBlocks
+
+```ts
+interface TextBlock {
+  readonly number: number
+  readonly text: string
+  readonly start: number
+  readonly end: number
+}
+TextBlocks.split(text, { targetChars }): readonly TextBlock[]
+```
+
+`split` 只切分已解码的纯文本：标题与分隔线起新块，空行结束当前块，其余在换行处按 `targetChars` 断开。超过目标长度的单行保留为一个块，由分页读取再切片段，避免同一行被拆成互不相关的两段。各块按顺序拼回与原文逐字一致，保留全部空白与 CRLF；`number` 从 1 开始，`start`／`end` 是原文 UTF-16 偏移。`targetChars` 必须为正整数，空文本返回空数组。
+
+Kit 不读写文件、不分页、不访问模型或存储；分页窗口、索引、摘要与提示词由 App 决定。块边界是结构边界，不与固定字符窗口对齐，需要覆盖范围时使用 `start`／`end`。
+
 ## TextSearch、VectorSearch、RRF、ModelCalls
 
 ```ts

package/development/docs/api/knowledge-answering.en.md

@@ -43,7 +43,7 @@ interface AnswerTaskDefinition<Input, Metadata> {
   readonly id: string;
   readonly description: string;
   readonly inputSchema: SchemaAdapter<Input>;
-  readonly intentIds: readonly string[];
+  readonly goalIds: readonly string[];
   readonly scopeId?: string;
   readonly readerId: string;
   readonly outputId: string;
@@ -145,6 +145,9 @@ OutputResult is `{ outputId, kind, value }`. Group children use program-assigned
 | --- | --- |
 | defineTextTemplate(master, options) | Pure compilation; render(values) substitutes once synchronously; errors.missingField creates an error |
 | defineSemanticSlots(definition) | namespace, keys, maxOccurrences; isValid(text): boolean |
+| defineReplyFormats({ formats, checks }) | Compiles template-bound reply formats; resolve(context) returns an inspected format only on a match and undefined otherwise |
+| replyFormatChecks.bubbles(totalLimit) / textBudget(maxChars) | Shared bubble count, blank-bubble and text-length checks; the app declares the limits |
+| mergeReplyBubbles(bubbles, limit) | Program normalization for replies without a template: drops blank bubbles and merges overflow into the last one |
 | replyBubbleTexts(input) | Keeps the existing plain-text／bubble extraction responsibility and returns readonly string[]; count and length limits are enforced by the registered output contract |
 | publishReplyEvents({ text, delivery }, context) | Returns AsyncIterable<AgentOutputEvent>, preserving backpressure and cancellation as consumers pull; pacing continues to use *Ms |
 | serializeOutputEvents(events) / textOutputEvents(chunks) | Preserves explicit conversion between events and text streams and is not an invoke return mode |

package/development/docs/api/knowledge-answering.md

@@ -43,7 +43,7 @@ interface AnswerTaskDefinition<Input, Metadata> {
   readonly id: string;
   readonly description: string;
   readonly inputSchema: SchemaAdapter<Input>;
-  readonly intentIds: readonly string[];
+  readonly goalIds: readonly string[];
   readonly scopeId?: string;
   readonly readerId: string;
   readonly outputId: string;
@@ -145,6 +145,9 @@ OutputResult为`{ outputId, kind, value }`。group子项使用程序分配的id
 | --- | --- |
 | defineTextTemplate(master, options) | 纯编译；render(values)同步替换一次；errors.missingField创建错误 |
 | defineSemanticSlots(definition) | namespace、keys、maxOccurrences；isValid(text): boolean |
+| defineReplyFormats({ formats, checks }) | 编译模板绑定的回复格式；resolve(context)仅命中时返回带inspect的格式，其余返回undefined |
+| replyFormatChecks.bubbles(totalLimit) / textBudget(maxChars) | 通用气泡数量、空白气泡与正文长度检查，限额由应用声明 |
+| mergeReplyBubbles(bubbles, limit) | 无模板回复的程序归一：丢弃空白气泡并把超出部分并入最后一条 |
 | replyBubbleTexts(input) | 保留现有纯文本／气泡提取职责，返回readonly string[]；数量与长度限制由已登记输出合同执行 |
 | publishReplyEvents({ text, delivery }, context) | 返回AsyncIterable<AgentOutputEvent>，保留消费者拉取时的背压及取消；pacing继续使用*Ms |
 | serializeOutputEvents(events) / textOutputEvents(chunks) | 保留事件与文本流的显式转换，不作为invoke返回模式 |

package/development/docs/api/mock.en.md

@@ -2,6 +2,8 @@
 
 MockGPT simulates model replies with fixed data, functions and lightweight text algorithms, and is suited to debugging protocols, tool selection, streaming output, failure and cancellation. It does not perform real LLM inference. Ordinary rules do not use the network; the web source is an explicit optional network capability.
 
+Install `@jangts/mock-gpt` before using the `/mock`, `/mock/node` or `/mock/web` entries; it is an optional peer dependency and is not installed with this package.
+
 ## Entry points and public exports
 
 | Entry | Runtime exports | Type exports |

package/development/docs/api/mock.md

@@ -2,6 +2,8 @@
 
 MockGPT 用固定数据、函数及轻量文本算法模拟模型回复，适合调试协议、工具选择、流式输出、失败与取消。它不执行真实 LLM 推理。普通规则不联网；网页来源是显式的可选网络能力。
 
+使用 `/mock`、`/mock/node`、`/mock/web` 前需安装 `@jangts/mock-gpt`；它是可选 peer 依赖，不会随本包自动安装。
+
 ## 入口与公开导出
 
 | 入口 | 运行时导出 | 类型导出 |

package/development/docs/api/observability.en.md

@@ -83,13 +83,13 @@ await agent.run(state);
 | execution.observe.event | Loop／Workflow, model.start／end, tool start／end and permitted dynamic reports | Side channel; a synchronous throw, async rejection or hang does not change execution; still effective when persistent logging is closed |
 | execution.diagnostics → CoreLogOutput.write | Optional persistent projection of the same fact | The App decides fields, body, storage and retention; it gains no content authorization from other listeners |
 | ModelRunner.sink.output | model.start／output／parsed of the same outer layer, plus model.end on success, failure or cancellation | Body waits in order, propagates failures and preserves backpressure; the end notification is limited to 250 milliseconds independently, and its failure does not override the result or the original exception |
-| context.report({ usedModel, payload, subs }) | Immediate report during the current node's run | usedModel is optional boolean metadata, payload／subs are read only when content is permitted; Core fills in identity, time and sequence, and reports after the node ends or is cancelled are dropped |
-| node report(update, context) | usedModel／payload／subs on completion／transition | Evaluated only when content is permitted; does not replace immediate reports during the run |
+| context.report({ usedModel, payload }) | Immediate report during the current node's run | usedModel is optional boolean metadata, payload are read only when content is permitted; Core fills in identity, time and sequence, and reports after the node ends or is cancelled are dropped |
+| node report(update, context) | usedModel／payload on completion／transition | Evaluated only when content is permitted; does not replace immediate reports during the run |
 | context.createSubFlowLogger() | Sub-log instance bound to this execution | write records first, fix completes later, readAll obtains a fixed-format snapshot; reuses the existing node.progress outlet |
 
 Listeners can filter by metadata such as event, nodeId and workflowNodeId. workflowNodeId keeps the owning Workflow node, while model／tool boundaries still have their own nodeId and invocationId. Repeated visits to the same node have different spans, and concurrent runs do not correlate through lastCall or a shared "current request". `withObserver` can be called on an existing request scope to add a listener, inherited along sub-scopes; this is immutable wiring and leaves the original scope unaffected. Canonical methods are bound to their original receivers at assembly time. When a reusable Engine has no request scope configured, each run is assigned an independent identity.
 
-Listeners without accepts receive metadata only. Content events, payload and subs are collected only after the corresponding consumer explicitly accepts them; other metadata consumers do not gain the body as a side effect. Each consumer receives an independent copy. The result snapshot is isolated from the actual return value, so preview edits do not rewrite the final value; model results must still satisfy the existing Journal snapshot contract.
+Listeners without accepts receive metadata only. Content events, payload and sub-log content are collected only after the corresponding consumer explicitly accepts them; other metadata consumers do not gain the body as a side effect. Each consumer receives an independent copy. The result snapshot is isolated from the actual return value, so preview edits do not rewrite the final value; model results must still satisfy the existing Journal snapshot contract.
 
 ModelPart does not provide separate reasoning content chunks. State, process notes explicitly provided by the model, tool facts, transient previews and the final answer each keep their own meaning; internal hidden reasoning or the raw protocol must not be treated as a user reply. Selection, compression and assembly can be registered as ordinary nodes separately and use real lifecycle facts; algorithmic reports are delivered as permitted node.progress.
 
@@ -97,7 +97,7 @@ Adding a listener only changes assembly configuration; the original Workflow, ru
 
 ## Sub-log instances and record-first-then-complete
 
-Workflow nodes, simple run(step), ToolRegistry／Support tools and the execution context of executeInvocation all provide `createSubFlowLogger()` and `report()`. Each node visit or call has one instance, and repeated create returns the same instance; no global logger is shared. subs accepts only SubFlowLogger instances belonging to that execution; plain objects, objects imitating readAll, hand-written arrays and readAll() snapshots are rejected; invalid material does not become a main execution fact. The normalized stored field subSteps is still an array, so reading historical data does not require re-creating a logger.
+Workflow nodes, simple run(step), ToolRegistry／Support tools and the execution context of executeInvocation all provide `createSubFlowLogger()` and `report()`. Each node visit or call has one instance, and repeated create returns the same instance; no global logger is shared. The factory is already bound to the execution context; no context argument is required. Identity inherits the App diagnostic scope and identifies the Engine definition, run and node visit without retaining App service objects. The Loop owns the lifecycle: each accepted write/fix immediately commits an immutable snapshot to runtime before publishing node.progress to observers and the log outlet. Nodes never submit a logger or readAll() result. Terminal events use the committed runtime snapshot without reading the logger. Node completion detaches writes and releases the runtime reference; failure and cancellation preserve prior records. A later visit gets a new instance. readAll() remains readable by any holder and emits nothing. Nodes, Apps and external code may retain or lend the instance; Core does not prescribe its use. A later visit receives a new logger and may consult the previous flow through a retained old instance. Apps apply each appended fix to the original write view using operation/targetStepId and order revisions with revision. Stored subSteps remain fixed-format arrays.
 
 ```ts
 async run(state, context) {
@@ -116,23 +116,49 @@ async run(state, context) {
     if (!context.signal.aborted) subs.fix(id, { status: 'error' });
     throw error;
   }
-  context.report({ usedModel: false, subs });
+  context.report({ usedModel: false });
 }
 ```
 
 | Method | Fixed contract |
 | --- | --- |
-| write(input): string | name and kind are required, status defaults to planned; stepId, sequence, createdAtMs and initial revision=1 are allocated automatically. Optional parentStepId, relatedDefinitionId, caseId, nextStepIds, status, time, summary, payload and usedModel. startedAtMs is recorded automatically only when running is reported explicitly, so planned time does not pass for an actual start. |
-| fix(stepId, patch): void | Completes status, model usage, pending times, summary, successors or payload fields for a record in the same instance; a terminal state cannot be reopened, but missing result fields can still be filled while execution is active. Keeps the ID, first order and original times, incrementing revision each time. payload merges missing keys recursively and existing facts cannot be overwritten; a given summary, time or successor cannot be rewritten. |
-| readAll(): readonly RecordedSubStep[] | Returns an immutable snapshot in first-write order; later fix calls do not change an earlier snapshot. With no steps it is [], and the snapshot remains readable after the execution is closed. |
+| write(input): string \| -1 | name and kind are required, status defaults to planned; stepId, sequence, createdAtMs and initial revision=1 are allocated automatically. Optional parentStepId, relatedDefinitionId, caseId, nextStepIds, status, time, summary, payload and usedModel. startedAtMs is recorded automatically only when running is reported explicitly, so planned time does not pass for an actual start. |
+| fix(stepId: string \| -1, patch): boolean | Completes status, model usage, pending times, summary, successors or payload fields for a record in the same instance; a terminal state cannot be reopened, but missing result fields can still be filled while execution is active. Every successful fix appends an independent record with operation=fix, a new stepId, sequence and createdAtMs. targetStepId references the original write and revision increases for that original. Each fix carries the resulting state without changing any earlier row. payload merges missing keys recursively and existing facts cannot be overwritten; a given summary, time or successor cannot be rewritten. |
+| readAll(): readonly RecordedSubStep[] | Returns all write/fix records in append order; repeated fixes create separate rows and never mutate earlier rows or snapshots. With no steps it is [], and the snapshot remains readable after the execution is closed. |
 
-The fixed record fields are origin=reported, stepId, sequence, name, kind, status, createdAtMs and revision, plus the optional fields above. planned／unknown can advance to an actual status, while running cannot go back to planned or skipped; success／error／cancelled／skipped are terminal, the status and established facts cannot be rewritten, but pending result fields can still be filled while the owning node is active. Statuses and legal transitions come from the same reportedStepStatusCatalog. A retry writes another record and does not reopen a terminal state. The parent and successors must belong to the same logger; when the successor ID is not yet available, nextStepIds can be completed in one later fix. Pending payload fields are omitted first and are not represented by null or an empty array as an overwritable placeholder. By default at most 256 records, 65536 JSON characters for the full snapshot and 1024 write/fix calls; payload accepts only bounded-depth JSON data and does not accept functions, service instances, circular references or internal getters.
+Records have origin=reported, operation=write/fix, unique stepId, append sequence, name, kind, status, createdAtMs and revision. Fix records reference the original write with targetStepId; fixing a fix ID is rejected. Historical projected snapshots may omit operation. planned／unknown can advance to an actual status, while running cannot go back to planned or skipped; success／error／cancelled／skipped are terminal, the status and established facts cannot be rewritten, but pending result fields can still be filled while the owning node is active. Statuses and legal transitions come from the same reportedStepStatusCatalog. A retry writes another record and does not reopen a terminal state. The parent and successors must belong to the same logger; when the successor ID is not yet available, nextStepIds can be completed in one later fix. Pending payload fields are omitted first and are not represented by null or an empty array as an overwritable placeholder. By default at most 256 original writes, 1024 total write/fix records and 65536 JSON characters for the complete ledger; payload accepts only bounded-depth JSON data and does not accept functions, service instances, circular references or internal getters.
 
-write and fix emit the initial／completion event through the existing node.progress at that moment, with payload.subStep holding operation, stepId, sequence, revision, createdAtMs, status and optional usedModel metadata. When content is permitted, the event carries the fixed-format subSteps snapshot at that point; node end／failure events also carry the last snapshot. The log appends revisions, and events already emitted are not updated in place. Results returning out of order do not change the initial order, and replay can distinguish "only a plan at the time" from "a result later". When only a plan or start was received without a result, the original status is kept; success, failure or an actual model call cannot be inferred.
+write and fix emit the initial／completion event through the existing node.progress at that moment, with payload.subStep holding operation, current record stepId, targetStepId for fixes, sequence, revision, createdAtMs, status and optional usedModel metadata. When content is permitted, the event carries the fixed-format subSteps snapshot at that point; node end／failure events also carry the last snapshot. The log appends revisions, and events already emitted are not updated in place. Results returning out of order do not change the initial order, and replay can distinguish "only a plan at the time" from "a result later". When only a plan or start was received without a result, the original status is kept; success, failure or an actual model call cannot be inferred.
 
 The main node reports through context.report({ usedModel: true | false }) whether it used the model this time, and the outer usedModel in the log is kept as metadata; sub-steps report their own usedModel through write／fix. Unreported stays unknown and does not default to false; a reported true cannot change back to false. A child's true is not automatically aggregated into the main node's original marker. This is a node report: a field of true does not fabricate model.start／end or call counts, and model internal hidden reasoning is not collected. The end report(update, context) is still evaluated only when content collection is permitted; markers that must be kept in metadata mode should be submitted during the run with context.report.
 
-Content permission continues to be decided per event and per consumer. Without content authorization, payload／summary getters are not read, nor are the private payload／subs getters in reports; only permitted status, revision and boolean metadata are kept. The instance closes when execution ends or is cancelled, and write／fix reject late modifications. Log shutdown, outlet failure or a process crash still follow the original failure isolation and incomplete mechanism; recording intent first does not constitute a transactional audit guarantee.
+Content permission continues to be decided per event and per consumer. Without content authorization, payload／summary getters are not read, nor are the private payload getters in reports; only permitted status, revision and boolean metadata are kept. The instance closes when execution ends or is cancelled, and write returns numeric -1 and fix returns false without throwing, inspecting arguments, recording or emitting. readAll remains readable. fix returns true on success; invalid IDs, invalid input, forbidden revisions and detachment all return false without throwing, changing the record or emitting a revision. write returns the new ID on success and -1 on any failure, including invalid input, limits and detachment, without throwing, recording or emitting. Log shutdown, outlet failure or a process crash still follow the original failure isolation and incomplete mechanism; recording intent first does not constitute a transactional audit guarantee.
+
+## Subnode grouping and restricted delegation
+
+subnodeId groups multiple records within one node visit. It is independent of stepId, which identifies a log record. A group can contain multiple writes and multiple fixes per write; ungrouped logs belong to the parent node. Grouping does not imply dispatch, contiguous phases, scheduling or dependencies.
+
+SubFlowLogger and ScopedSubFlowLogger are independent, non-inheriting classes implementing SubFlowLog. The full class owns storage/lifecycle, accepts subnodeId directly on write, and may fork(subnodeId). A scoped instance holds only the original logger and bound ID: write adds the ID, fix checks original-record ownership and delegates. It cannot override its group, fork or be supplied to native invoke. Both readAll methods return the same complete immutable ledger, including other groups.
+
+Business type is an arbitrary string; operation is the separate write/fix enum. type and the compatible kind classification fill each other's omitted default. Fix uses the explicit SubFlowStepFix whitelist (status, usedModel, times, summary, nextStepIds, payload), not Partial of the write input. Identity, group, business type and label cannot be revised. A rejected fix returns false; rejected writes return -1. Safe console warnings explain fixed reasons, deduplicated per logger, without payloads or arbitrary error text; console failures do not change results.
+
+Registered subnode IDs are local to one node visit: kind:encodedDefinitionId:ordinal, for example tool:product.references:1. Definition IDs are URL-encoded. The owning logger allocates ordinals per kind/definition at call start; failure and cancellation never reuse them, and a new node visit starts from 1. Parent identity stays in its existing fields. relatedInvocationId separately retains the real call identity for correlation with model/tool events; a short ordinal never replaces invocationId. App-owned custom groups need no business enum. Direct write({subnodeId, type, name}) and fork(subnodeId).write({type, name}) are equivalent grouping choices. fork validates its ID and native invoke rejects scoped/forged logger inputs at the boundary.
+
+## Optional native call records
+
+logger is a per-call choice. Omission creates no native sub-log; passing it produces a fixed write followed by a separate fix on success, error or cancellation. Components do not create owning logger storage or implicitly forward full logging authority. Tools expose a scoped delegate bound by Core to the actual invocation. It may be lent to business helpers but cannot fork or be passed to another invoke. Business steps remain App-owned.
+
+| Entry | Explicit logger location |
+| --- | --- |
+| ModelRunner / Workflow model.invoke; ToolRegistry / Support tool invocation | request.logger |
+| executeInvocation / Tools lifecycle | ports.logger(context) |
+| Retrieval.run; Answering task.read/readAsync, checks.check, flow.run; output.compose | context.logger |
+| Knowledge.read; recovery chain tryRecover | Optional second context argument |
+| Support.processContext / context node run | ports.logger / explicitly supplied context.logger |
+| retryMultipleModelCalls | request.logger; records only an actual fallback attempt |
+| Delivery.deliver; Aggregation.collect | execution.logger; optional third execution argument respectively |
+
+Fixed records contain producer/definition identity and execution status, never automatic copies of prompts, results, tool arguments or customer material. A checker returning a rejection or a recovery returning unhandled still completed normally; callers choose whether to record the business result. Existing Core events and receipts remain unchanged. Pure configuration, lookup and formatting functions do not record.
 
 ## File adaptation and relational table mapping
 

package/development/docs/api/observability.md

@@ -83,13 +83,13 @@ await agent.run(state);
 | execution.observe.event | Loop／Workflow、model.start／end、工具开始／结束及获准的动态报告 | 旁路；同步抛错、异步拒绝或悬挂不改变执行；关闭持久日志仍有效 |
 | execution.diagnostics → CoreLogOutput.write | 同一事实的可选持久投影 | App 决定字段、正文、存储和保留期；不获得其他监听器的内容授权 |
 | ModelRunner.sink.output | 同一外层的 model.start／output／parsed，以及成功、失败或取消时 model.end | 正文按序等待、传播失败、保留背压；结束通知独立限时250毫秒，其失败不覆盖结果或原始异常 |
-| context.report({ usedModel, payload, subs }) | 当前节点运行中的即时报告 | usedModel 为可选布尔元数据，payload／subs 仅内容获准才读取；Core 补齐身份、时间和序号，节点结束或取消后的报告丢弃 |
-| 节点 report(update, context) | 完成／跳转时的 usedModel／payload／subs | 内容获准才求值，不替代运行中的即时报告 |
+| context.report({ usedModel, payload }) | 当前节点运行中的即时报告 | usedModel 为可选布尔元数据，payload 仅内容获准才读取；Core 补齐身份、时间和序号，节点结束或取消后的报告丢弃 |
+| 节点 report(update, context) | 完成／跳转时的 usedModel／payload | 内容获准才求值，不替代运行中的即时报告 |
 | context.createSubFlowLogger() | 绑定本次执行的子日志实例 | write 先留记录，fix 随后补全，readAll 取得固定格式快照；复用既有 node.progress 出口 |
 
 监听器可用 event、nodeId、workflowNodeId 等元数据过滤。workflowNodeId 保留所属 Workflow 节点，模型／工具边界自身仍有 nodeId 和 invocationId。重复访问同一节点有不同 span，并发运行不借助 lastCall 或共享“当前请求”关联。可在已有请求作用域上调用 `withObserver` 增加监听，沿子作用域继承；这是不可变的接线，原作用域不受影响。规范方法在装配时绑定原接收者。可复用 Engine 未配置请求作用域时，每次 run 分配独立身份。
 
-无 accepts 的监听器仅接元数据。内容事件、payload 和 subs 只在对应消费者明确接纳后采集；其他元数据消费者不会连带获得正文。消费者拿到独立副本。结果快照与实际返回值隔离，不因预览修改而改写最终值；模型结果仍须符合既有 Journal 快照合同。
+无 accepts 的监听器仅接元数据。内容事件、payload 和子日志正文 只在对应消费者明确接纳后采集；其他元数据消费者不会连带获得正文。消费者拿到独立副本。结果快照与实际返回值隔离，不因预览修改而改写最终值；模型结果仍须符合既有 Journal 快照合同。
 
 ModelPart 不提供独立推理内容分片。状态、模型明确提供的过程说明、工具事实、暂态预览和最终答案各自保持含义，不能把内部隐藏推理或原始协议当用户回复。选择、压缩与装配可分别注册普通节点，使用真实生命周期事实；算法报告按获准的 node.progress 交付。
 
@@ -97,7 +97,7 @@ ModelPart 不提供独立推理内容分片。状态、模型明确提供的过
 
 ## 子日志实例与先记后补
 
-Workflow 节点、简易 run(step)、ToolRegistry／Support 工具及 executeInvocation 的执行 context 均提供 `createSubFlowLogger()` 和 `report()`。每次节点访问或调用各有一个实例，多次 create 返回同一实例；不共用全局 logger。subs 只接受所属执行的 SubFlowLogger 实例，普通对象、仿造 readAll 的对象、手写数组和 readAll() 快照均会拒收；非法材料不成为主执行事实。规范化后的存储字段 subSteps 仍为数组，读取历史数据不需要重新创建 logger。
+Workflow 节点、简易 run(step)、ToolRegistry／Support 工具及 executeInvocation 的执行 context 均提供 `createSubFlowLogger()` 和 `report()`。每次节点访问或调用各有一个实例，多次 create 返回同一实例；不共用全局 logger。创建入口已绑定执行 context，无需再次传参；身份沿 App 装配的诊断作用域继承，自动关联当前 Engine 定义、run 与 node 访问，不保存 App 服务对象。Loop 接管生命周期，write／fix 接受后立即把不可变快照交给 runtime，再通过 node.progress 通知 App 与日志出口。节点不提交 logger 或 readAll() 的结果；终态事件使用 runtime 已接收的快照，不回读 logger。节点结束时解绑写入并释放 runtime 的实例引用，失败与取消保留此前记录；再次访问同一节点创建独立实例。readAll() 向任何持有者提供持续只读查询，不产生事件或提交。实例可由节点、App 或外部代码保留并借用，Core 不限制用途；后续节点访问获得新实例，旧实例可用于读取上次 flow。App 按 operation 与 targetStepId 将追加的 fix 应用到原 write 对应的界面视图，按 revision 判断修订顺序。存储字段 subSteps 为固定格式数组。
 
 ```ts
 async run(state, context) {
@@ -116,23 +116,76 @@ async run(state, context) {
     if (!context.signal.aborted) subs.fix(id, { status: 'error' });
     throw error;
   }
-  context.report({ usedModel: false, subs });
+  context.report({ usedModel: false });
 }
 ```
 
 | 方法 | 固定合同 |
 | --- | --- |
-| write(input): string | name、kind 必填，status 默认 planned；自动分配 stepId、sequence、createdAtMs 和初始 revision=1。可选 parentStepId、relatedDefinitionId、caseId、nextStepIds、状态、时间、摘要、payload 和 usedModel。只有明确报告 running 才自动记 startedAtMs，计划时间不冒充实际开始。 |
-| fix(stepId, patch): void | 给同一实例内的记录补状态、模型使用、待定时间、摘要、后继或 payload 字段；终态不能重开，但执行仍活跃时可补缺失的结果字段。保留 ID、首次顺序和原时间，每次增加 revision。payload 递归补缺失键，已有事实不能覆盖；已给定的摘要、时间和后继不能改写。 |
-| readAll(): readonly RecordedSubStep[] | 按首次 write 顺序返回不可变快照；之后的 fix 不改变先前快照。没有步骤为 []，执行关闭后仍可读快照。 |
+| write(input): string \| -1 | name 必填，type 为自定义业务类型；兼容的 kind 分类与 type 至少提供一项，缺省时互为补足，status 默认 planned；自动分配 stepId、sequence、createdAtMs 和初始 revision=1。可选 parentStepId、relatedDefinitionId、caseId、nextStepIds、状态、时间、摘要、payload 和 usedModel。只有明确报告 running 才自动记 startedAtMs，计划时间不冒充实际开始。 |
+| fix(stepId: string \| -1, patch): boolean | 给同一实例内的记录补状态、模型使用、待定时间、摘要、后继或 payload 字段；终态不能重开，但执行仍活跃时可补缺失的结果字段。每次成功均追加独立记录，operation=fix，分配新 stepId、sequence、createdAtMs；targetStepId 指向原 write 的 ID，revision 按该原记录递增。记录携带本次修订后的完整状态，不修改原 write 或先前 fix。payload 递归补缺失键，已有事实不能覆盖；已给定的摘要、时间和后继不能改写。 |
+| readAll(): readonly RecordedSubStep[] | 按实际追加顺序返回全部 write／fix 记录；多次 fix 对应多条记录，旧行和旧快照保持不变。没有步骤为 []，执行关闭后仍可读快照。 |
 
-记录的固定字段为 origin=reported、stepId、sequence、name、kind、status、createdAtMs、revision，及上述可选字段。planned／unknown 可推进到实际状态，running 不能退回计划或 skipped；success／error／cancelled／skipped 为终态，状态和已确定的事实不能改写，但所属节点仍活跃时可以继续填入等待中的结果字段。状态及合法推进关系来自同一 reportedStepStatusCatalog。重试另 write 一条，不重开终态。父、后继必须属于同一 logger；尚未取得后继 ID 时可在后续 fix 中一次补齐 nextStepIds。待填 payload 字段先省略，不以 null 或空数组冒充可覆盖的占位。默认最多256条、全部快照65536个JSON字符、1024次 write/fix；payload 只收有限深度的 JSON 数据，不接受函数、服务实例、循环引用或内部 getter。
+记录的固定字段为 origin=reported、operation=write／fix、唯一 stepId、追加序号 sequence、name、kind、status、createdAtMs、revision；fix 另有 targetStepId，始终关联原 write，不能以 fix 记录的 ID 再修订。历史投影快照可缺省 operation。planned／unknown 可推进到实际状态，running 不能退回计划或 skipped；success／error／cancelled／skipped 为终态，状态和已确定的事实不能改写，但所属节点仍活跃时可以继续填入等待中的结果字段。状态及合法推进关系来自同一 reportedStepStatusCatalog。重试另 write 一条，不重开终态。父、后继必须属于同一 logger；尚未取得后继 ID 时可在后续 fix 中一次补齐 nextStepIds。待填 payload 字段先省略，不以 null 或空数组冒充可覆盖的占位。默认最多256条原始 write、总计1024条 write／fix 记录、全部序列65536个JSON字符；payload 只收有限深度的 JSON 数据，不接受函数、服务实例、循环引用或内部 getter。
 
-write 和 fix 当时就经既有 node.progress 发射初始／补全事件，payload.subStep 保存 operation、stepId、sequence、revision、createdAtMs、status 和可选 usedModel 元数据。内容获准时，事件附带该时点的固定格式 subSteps 快照；节点结束／失败事件也附带最后快照。日志追加修订，已经输出的事件不原地更新。结果乱序返回不改变初始顺序，回放可区分“当时只有计划”和“后来有了结果”。只收到计划或开始而没有结果时保持原状态；不能推断已经成功、失败或实际调用了模型。
+write 和 fix 当时就经既有 node.progress 发射初始／补全事件，payload.subStep 保存 operation、当前记录 stepId、fix 的 targetStepId、sequence、revision、createdAtMs、status 和可选 usedModel 元数据。内容获准时，事件附带该时点的固定格式 subSteps 快照；节点结束／失败事件也附带最后快照。日志追加修订，已经输出的事件不原地更新。原始 write 不因乱序结果而重新排序；fix 按实际接收顺序追加，回放可区分“当时只有计划”和“后来有了结果”。只收到计划或开始而没有结果时保持原状态；不能推断已经成功、失败或实际调用了模型。
 
 主节点通过 context.report({ usedModel: true | false }) 上报本次自身是否使用模型，日志外层 usedModel 作为元数据保留；子步骤通过 write／fix 上报自身的 usedModel。未上报保持未知，不默认 false；已报告 true 不能改回 false。子节点的 true 不自动汇总进主节点原始标记。此为节点报告，不因字段为 true 而补造 model.start／end 或调用次数，也不采集模型内部隐藏推理。结束 report(update, context) 仍仅在内容采集获准时求值，需在元数据模式保留的标记应在运行中用 context.report 提交。
 
-内容权限继续按事件和消费者分别判断。未获内容授权时不读取 payload／summary getter，也不读取报告中的私有 payload／subs getter；只保留已获准的状态、修订和布尔元数据。执行结束或取消后实例关闭，write／fix 拒绝迟到修改。日志关闭、出口失败或进程崩溃仍遵守原失败隔离及 incomplete 机制，先记意图不构成事务审计保证。
+内容权限继续按事件和消费者分别判断。未获内容授权时不读取 payload／summary getter，也不读取报告中的私有 payload getter；只保留已获准的状态、修订和布尔元数据。执行结束或取消后实例关闭，write 固定返回数字 -1，fix 返回 false，不报错、不校验或读取入参、不入账或发事件；readAll 持续可读。fix 成功返回 true；无效 ID、非法输入、禁止的修订及解绑等失败统一返回 false，不抛错、不改变原记录或产生修订事件。write 成功返回新 ID，非法输入、容量限制、解绑等任何失败统一返回 -1，不抛错、不入账或发事件。日志关闭、出口失败或进程崩溃仍遵守原失败隔离及 incomplete 机制，先记意图不构成事务审计保证。
+
+## 子节点归集与受限委托
+
+`subnodeId` 是同次 node 执行内的逻辑归集身份，不是某条日志的 ID。一个子节点可以拥有多条 write，以及每条 write 的多次 fix；未指定 subnodeId 的记录直接归父 node。它不规定分发、连续分段、执行顺序或依赖关系。App 按实际职责组织自定义子节点，无需为了日志增加调度节点。
+
+- `SubFlowLogger` 是完整类，独占记录存储与生命周期。write 可直接填写任意非空字符串 subnodeId，无业务枚举；也可通过 fork(subnodeId) 创建另一个实例。
+- `ScopedSubFlowLogger` 是独立且不继承完整类的委托类，只持有原 logger 与绑定 ID，不保存记录。write 自动补归属并拒绝覆盖；fix 只能修订该子节点的原记录，越界返回 false。没有 fork，不能作为原生 invoke 的 logger。
+- 两类实现共同读写接口 `SubFlowLog`；它们的 readAll 返回同一份全量不可变记录，包括其他分组。读权限不会扩大受限实例的写权限。
+- fix 使用独立 `SubFlowStepFix`，不是 Partial<write参数>。只接受 status、usedModel、startedAtMs、endedAtMs、summary、nextStepIds、payload，仍受状态推进和已有事实保护。不能改变 subnodeId、type、kind、name、stepId 或其他身份字段。
+- type 是可自定义的业务日志类型，operation 才是 write／fix。fix 继承原记录的业务类型和归属；每次成功都追加独立记录。
+
+```ts
+const logger = context.createSubFlowLogger();
+// 可直接指定分组，fork 不是必需步骤。
+logger.write({ subnodeId: 'prepare', type: 'source.read', name: '读取资料' });
+const logs: SubFlowLog = logger.fork('prepare');
+prepareMaterials(logs); // 子函数只需要公共读写接口。
+await context.tools.invoke({ toolId: 'read', input: {}, logger });
+// Core 传给真实工具的 execution.logger 是 ScopedSubFlowLogger。
+```
+
+注册子节点 ID 只在本次 node 执行内唯一，格式为 kind:encodedDefinitionId:ordinal，例如 tool:product.references:1。定义 ID 使用 URL 编码，计数按能力种类与定义 ID 分开，在调用开始时分配；失败、取消不复用，下一次 node 访问从1开始。父级访问身份已有独立字段，不重复拼入子节点 ID。真实调用身份单独保存在 relatedInvocationId，用于对应模型／工具主事件，不以短序号代替 invocationId。重复／并发调用分别归集，同次调用的多条日志保持相同 subnodeId。自定义子节点由 node 自行命名，两种归集都没有业务枚举约束。
+
+fix 的失败统一返回 false，write 的失败统一返回 -1；调试控制台使用固定原因输出 warn，同一 logger 同类原因去重，不包含入参、正文或任意错误文本。控制台自身异常不改变返回值。fork 对无效 ID 的参数检查与 invoke 对非完整 logger 的边界检查仍保留。
+
+## 原生调用的可选记录
+
+logger 是调用级参数，不是全局开关。未传入时不产生原生子日志，开发者可以自行组织全部记录；显式传入时原生组件统一 write 一条运行记录，并在成功、失败或取消时 fix，形成两条独立记录。不自动创建完整 logger 存储或向所有下游传播完整 logger 权限，不改变它所属的 App、Engine、node 或生命周期。Tool handler 取得 Core 为本次调用绑定的 execution.logger，可把该受限委托交给内部业务函数；不能继续 fork 或传给另一次 invoke。
+
+| 原生入口 | 显式传入位置 | 固定记录 |
+| --- | --- | --- |
+| ModelRunner.invoke／Workflow model.invoke | request.logger | Model call，关联阶段 ID |
+| ToolRegistry.invoke／invokeAsync、Support 工具 | request.logger | Tool call，关联工具 ID |
+| executeInvocation／Tools Kit 生命周期 | ports.logger(context) | Invocation，关联 handler ID |
+| Retrieval.run | context.logger | Retrieval |
+| Answering task.read／readAsync、checks.check、flow.run | context.logger | 证据读取、每个实际 checker、完整答复流程 |
+| Knowledge.read | 可选第二参数的 logger | Read knowledge |
+| Presentation outputs.compose | context.logger | Compose output |
+| Support.processContext、上下文节点 run | ports.logger／显式提供的 context.logger | Process context |
+| Support.retryMultipleModelCalls | request.logger | 只在实际降级重试时记录 Retry model proposal |
+| Policies 恢复链 tryRecover | 可选第二参数的 logger | 每个实际尝试的恢复策略 |
+| Delivery.deliver | execution.logger | Deliver result |
+| Aggregation.collect | 可选第三参数的 logger | Aggregate queries |
+
+固定记录只描述执行边界，不自动复制模型输入输出、工具参数或客户材料。检查正常返回不通过、恢复正常返回未处理，都属于函数成功返回；业务结果由开发者按需补充。已有 Core 主事件继续提供原有调用事实；可选子日志用于节点内部编排展示，不替代主事件、回执或权限检查。纯配置、清单查询和格式化函数不追加日志。
+
+```ts
+const logger = context.createSubFlowLogger();
+await context.model.invoke({ input: '简要说明', logger });
+await context.tools.invoke({ toolId: 'read', input: {}, logger });
+// 此次调用未传 logger，不追加原生子日志。
+await context.tools.invoke({ toolId: 'read', input: {} });
+```
 
 ## 文件适配与关系表映射