@jangts/agent-core 0.3.6 → 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 依赖，不会随本包自动安装。
+
 ## 入口与公开导出
 
 | 入口 | 运行时导出 | 类型导出 |