@jangts/agent-core 0.3.5 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 本文件记录 `@jangts/agent-core` 的行为变更。接口合同与使用方式见[API 手册](development/docs/api/README.md)。
 
+## 0.5.0
+
+- Add the optional `TextBlocks` Kit: structure-aware splitting of long plain text into numbered blocks with source offsets and exact reassembly; paging, search, storage and prompts stay with the App.
+- Reject mutable context fragments whose declared field set changes through a `null` value, and merge tool model fields as own data properties so `__proto__`-like keys cannot rewrite the merged prototype.
+- Keep Kit implementations out of Core barrels: `/context` and the capability registration surface expose Core helpers only, while Kit helpers remain available from `/kits/*` and the documented root convenience surface. Remove the unused execution barrel.
+- Make `@jangts/mock-gpt` an optional peer dependency used only by the `/mock` entries instead of a production dependency; install it explicitly to use those entries.
+- Support native tool threads in Core: `ModelMessage` accepts assistant `toolCalls` and `role: 'tool'` results; preparation preserves and counts them, and `ModelCallTrace.calls` records every completed call while `functionCall` keeps its single-call meaning.
+- Add the opt-in `Support.createSessionModelTransport`: one response may contain prose and several tool calls. The resolved `toolId` / `input` / `problem` fields live in Support; Core only exposes raw `ModelSessionResult`. `nativeFunctionInteraction` and its single-proposal contract remain unchanged.
+- Keep the Core `/model` barrel free of Support implementations; named Support exports remain available from the package root and `/support`.
+- Keep Kits available from the root convenience surface and from `/kits` / `/kits/*` subpaths. Kits remain optional, not restricted; Apps may use whichever entry is convenient.
+- Add `ModelOptions.toolChoice` and `parallelToolCalls`, including `'omit'` for leaving the wire field out; defaults keep `tool_choice: 'required'` and `parallel_tool_calls: false`.
+- Unify model interfaces as ModelTool and ModelToolRegistry; transports use tools / toolIds, selections use toolId, and the JSON adapter uses a name/input envelope. Skip the 0.4 series.
+- Add asIntent discovery metadata and active conditions, with node-owned withIntent(context) and explicit selection. Intent has no independent identity or aggregation registry.
+- Preserve executable, lifecycle, domain-policy and preview extensions. Derive model interfaces from executable tools without parsing business arguments twice; retain authorization, cancellation, budgets and receipts.
+- Add WorkflowTool / WorkflowNode names and separate Intent decorators for classes and methods, with order-independent ESM/CJS metadata. Tool decorators reject inline asIntent.
+- Retain explicit owner-to-tool associations and local provenance without transmitting registration sources to the model. Domain delegates remain allowed sets with optional explicit overrides.
+- Add one optional `lifecycle` block per tool in place of separate invocation and contribution objects, and one optional `delegate` field that claims a dispatch id. The registry keeps a unique `delegateId → tool` index, so `call(next, context)` stays the single dispatch path; `inspect` runs once for every tool and the remaining selected-only hooks run for the tool that owns the decision.
+- Rename request-tool vocabulary to goals across the domain catalog: ports use `goalIds`/`goals`, projections expose `goalCatalog`/`goalDelegates`, and the model catalog returns `availableGoalIds`/`availableGoals`.
+- Name lifecycle dispatch by `lifecycle.id`; `ToolsOptions.invocationId(decision)` selects the handler, `call(next, context)` routes on `next.type`, and the missing-handler factory is `unavailableInvocation(invocationId)`. No `step` field remains in the lifecycle contract.
+
+## 0.3.6
+
+- Preserve explicit recovery targets from workflow error events as execution-chain transitions linked to the original errorEventId.
+
+- Export immutable Workflow topology with toGraph() and observed per-visit execution chains with toChain(runId); keep ordered append-only subflow records and App-owned authorized read sources.
+- Snapshot routes getters exactly once during node registration for execution and graph export.
+
+- Shorten registered subnode IDs to node-local kind/definition/ordinal identifiers; retain real call correlation in relatedInvocationId.
+
+- Separate arbitrary business type from write/fix operation and add explicit subnodeId grouping.
+- Independent full/scoped logger classes share one owning store and full readAll history. Scoped delegates bind writes, restrict fixes, cannot fork, and cannot invoke; actual invocations bind their existing execution identity.
+- Rejected writes/fixes keep sentinel returns and emit safe, deduplicated developer warnings.
+
+- Optional per-call logger for native model/tool/invocation and executable Kit boundaries; omitted loggers add no sub-logs and are never inferred or globally forwarded.
+- Every accepted fix appends an independently identified record referencing the original write through targetStepId; readAll preserves the full write/fix ledger in append order.
+
+- Bind each sub-flow logger to its execution context; write/fix commit immutable snapshots immediately to runtime and notify App observers through node.progress.
+- Remove logger submission through report.subs; readAll remains a read-only local query. Terminal events use runtime-owned snapshots and detached visits return write=-1 / fix=false without throwing, while every holder retains readAll access.
+- write returns the new ID on success and -1 on any failure; fix returns a success boolean for every attempt; invalid revisions and detached instances return false without throwing. Retained loggers remain readable across visits or external borrowing.
+- Tool debugSteps hooks write through their bound context and no longer return a logger.
+
 ## 0.3.5
 
 - Add decorators and typescript-decorators keywords for npm discovery; preserve the English-first getting-started README.

package/README.md

@@ -46,7 +46,7 @@ console.log(await agent.run({ question: 'Hello' }));
 
 A node returns a state patch. After commit, routes read the updated state: `route.to('next')` continues to another node; `route.deliver('answer')` returns the final result. The first node is the default entry, and routes match in declaration order.
 
-The Provider above returns fixed text. Replace it with a real Provider without changing the workflow. The [complete offline example](https://agent-core-docs.pages.jangts.cafe/en/manual/examples/offline-agent) adds tools, multiple nodes and progress observation.
+The Provider above returns fixed text. Replace it with a real Provider without changing the workflow. The [complete offline example](https://agent-core-docs.pages.jangts.cafe/en/manual/examples/offline-agent.html) adds tools, multiple nodes and progress observation.
 
 ## Connect a real model
 
@@ -89,7 +89,7 @@ export AI_MODEL="your-model-id"
 node model.mjs
 ```
 
-To connect the first workflow, replace its offline provider declaration with `import { provider } from './provider.mjs'`. Model `invoke` returns `{ value, invocation }`; `value` contains the complete result and `invocation` records the call. Failures throw. Configure Runner `sink.output` to consume live chunks while retaining the complete `value`. See [Core model calls](https://agent-core-docs.pages.jangts.cafe/en/manual/api/core).
+To connect the first workflow, replace its offline provider declaration with `import { provider } from './provider.mjs'`. Model `invoke` returns `{ value, invocation }`; `value` contains the complete result and `invocation` records the call. Failures throw. Configure Runner `sink.output` to consume live chunks while retaining the complete `value`. See [Core model calls](https://agent-core-docs.pages.jangts.cafe/en/manual/api/core.html).
 
 ## Define and execute a tool
 
@@ -127,14 +127,14 @@ console.log(result.value); // 42
 
 Reuse static tool definitions and bind request dependencies and cancellation with `catalog.bind({ app, execution })`. Successful tool invocation also returns `{ value, invocation }`.
 
-To let the model select a tool, append this to `tools.mjs` and use the `provider.mjs` above. The same catalog supplies model capabilities and actual execution:
+To let the model select a tool, append this to `tools.mjs` and use the `provider.mjs` above. The same catalog supplies model tools and actual execution:
 
 ```js
 import { ModelRunner } from '@jangts/agent-core';
 import { provider } from './provider.mjs';
 
 const selection = Support.createModelTransport({
-  id: 'choose-tool', capabilities: catalog.capabilities,
+  id: 'choose-tool', tools: catalog.tools,
 });
 const runner = new ModelRunner({ provider, transports: [selection], maxCalls: 1 });
 const proposal = await runner.invoke({
@@ -146,7 +146,7 @@ const executed = await tools.invoke({
 console.log(executed.value); // 42
 ```
 
-The model proposes an id and arguments. `tools.invoke` performs parsing, authorization and business execution. For multi-step behavior, put selection, execution and reply into Workflow nodes using `context.model.invoke` and `context.tools.invoke`. See [model and tool integration](https://agent-core-docs.pages.jangts.cafe/en/manual/basic-usage).
+The model proposes an id and arguments. `tools.invoke` performs parsing, authorization and business execution. For multi-step behavior, put selection, execution and reply into Workflow nodes using `context.model.invoke` and `context.tools.invoke`. See [model and tool integration](https://agent-core-docs.pages.jangts.cafe/en/manual/basic-usage.html).
 
 ## Organize handlers as classes
 
@@ -183,7 +183,7 @@ Install `npm install -D tsx typescript`, then run `npx tsx greeting.mts`. Existi
 - `@tool` and `@fragment` support classes and existing instance methods; method decorators retain the original name and bind the real host. `@workflow`, `@agent` and `@model` define original options without creating Engines or Runners.
 - Getters can organize routes and private helpers. The route table is fixed during assembly; `when/complete` callbacks receive the latest execution state.
 
-The [decorator guide](https://agent-core-docs.pages.jangts.cafe/en/manual/api/decorators) covers host binding, namespace reads, multi-namespace registration and instance scope. Object definitions and decorator outputs use the same Core contracts.
+The [decorator guide](https://agent-core-docs.pages.jangts.cafe/en/manual/api/decorators.html) covers host binding, namespace reads, multi-namespace registration and instance scope. Object definitions and decorator outputs use the same Core contracts.
 
 ## Add knowledge, context and caching
 
@@ -199,24 +199,25 @@ const snapshot = knowledge.read({ documentId: 'manual', selection: { mode: 'docu
 console.log(snapshot);
 ```
 
-App supplies the material; knowledge catalogs handle identity, versions and selection without automatically crawling websites or creating databases. The [knowledge-answering example](https://agent-core-docs.pages.jangts.cafe/en/manual/api/knowledge-answering) connects retrieval, evidence checking, generation, repair and delivery.
+App supplies the material; knowledge catalogs handle identity, versions and selection without automatically crawling websites or creating databases. The [knowledge-answering example](https://agent-core-docs.pages.jangts.cafe/en/manual/api/knowledge-answering.html) connects retrieval, evidence checking, generation, repair and delivery.
 
-Workflow `context.cache` provides synchronous Engine-lifetime memory partitioned by node, using `get/has/set/delete/clear`. App-owned asynchronous `context.agentCache` connects longer-lived storage; workflow state remains in state. Ordinary nodes and Support policies handle history selection, trimming and summaries. See [context processing](https://agent-core-docs.pages.jangts.cafe/en/manual/api/context-processing) and [cache contracts](https://agent-core-docs.pages.jangts.cafe/en/manual/api/workflow).
+Workflow `context.cache` provides synchronous Engine-lifetime memory partitioned by node, using `get/has/set/delete/clear`. App-owned asynchronous `context.agentCache` connects longer-lived storage; workflow state remains in state. Ordinary nodes and Support policies handle history selection, trimming and summaries. See [context processing](https://agent-core-docs.pages.jangts.cafe/en/manual/api/context-processing.html) and [cache contracts](https://agent-core-docs.pages.jangts.cafe/en/manual/api/workflow.html).
 
 ## Continue by task
 
 | Task | Documentation |
 | --- | --- |
-| Create an app or integrate with a project | [Developer guide](https://agent-core-docs.pages.jangts.cafe/en/manual/) · [Installation](https://agent-core-docs.pages.jangts.cafe/en/manual/getting-started) |
-| Routes, models, budgets, cancellation and branches | [Workflow](https://agent-core-docs.pages.jangts.cafe/en/manual/api/workflow) · [Core](https://agent-core-docs.pages.jangts.cafe/en/manual/api/core) |
-| Tools, schemas, context and integration policies | [Support](https://agent-core-docs.pages.jangts.cafe/en/manual/api/support) · [Context nodes](https://agent-core-docs.pages.jangts.cafe/en/manual/api/context-processing) |
-| Knowledge, intents, retrieval, artifacts and persistent tasks | [Kits](https://agent-core-docs.pages.jangts.cafe/en/manual/api/kits) · [Recipes](https://agent-core-docs.pages.jangts.cafe/en/recipes/) |
-| Mock model replies, tool proposals, streams and failures | [MockGPT Kit](https://agent-core-docs.pages.jangts.cafe/en/manual/api/mock) |
-| Execution facts, call chains and Journal | [Observability](https://agent-core-docs.pages.jangts.cafe/en/manual/api/observability) |
-| Integrate with a development agent | [Agent-assisted development and Skill](https://agent-core-docs.pages.jangts.cafe/en/manual/agent-development) |
+| Create an app or integrate with a project | [Developer guide](https://agent-core-docs.pages.jangts.cafe/en/manual/) · [Installation](https://agent-core-docs.pages.jangts.cafe/en/manual/getting-started.html) |
+| Routes, models, budgets, cancellation and branches | [Workflow](https://agent-core-docs.pages.jangts.cafe/en/manual/api/workflow.html) · [Core](https://agent-core-docs.pages.jangts.cafe/en/manual/api/core.html) |
+| Tools, schemas, context and integration policies | [Support](https://agent-core-docs.pages.jangts.cafe/en/manual/api/support.html) · [Context nodes](https://agent-core-docs.pages.jangts.cafe/en/manual/api/context-processing.html) |
+| Knowledge, intents, retrieval, artifacts and persistent tasks | [Kits](https://agent-core-docs.pages.jangts.cafe/en/manual/api/kits.html) · [Recipes](https://agent-core-docs.pages.jangts.cafe/en/recipes/) |
+| Mock model replies, tool proposals, streams and failures | [MockGPT Kit](https://agent-core-docs.pages.jangts.cafe/en/manual/api/mock.html) |
+| Execution facts, call chains and Journal | [Observability](https://agent-core-docs.pages.jangts.cafe/en/manual/api/observability.html) |
+| Export workflow graphs and execution chains for developer views | [Graph and chain API](https://agent-core-docs.pages.jangts.cafe/en/manual/api/workflow-views.html) · [Further reading](https://agent-core-docs.pages.jangts.cafe/en/guide/extended/workflow-views.html) |
+| Integrate with a development agent | [Agent-assisted development and Skill](https://agent-core-docs.pages.jangts.cafe/en/manual/agent-development.html) |
 | Exact signatures, overloads and result types | [API directory](https://agent-core-docs.pages.jangts.cafe/en/api/) · [Local API handbook](development/docs/api/README.en.md) |
 
-Import Core and Support from the package root, Kits from `/kits/<name>`, and decorators from `/support/decorators`. App owns identity, business permissions, external effects and storage; Core provides generic runtime guarantees. Support and Kits remain optional.
+Import Core and Support from the package root, Kits from `/kits/<name>`, and decorators from `/support/decorators`. App owns identity, business permissions, external effects and storage; Core provides generic runtime guarantees. Support and Kits remain optional. The `/mock`, `/mock/node` and `/mock/web` entries require installing `@jangts/mock-gpt`, which is an optional peer dependency and is not installed with this package.
 
 ## License
 
@@ -270,7 +271,7 @@ console.log(await agent.run({ question: 'Hello' }));
 
 节点的 `run` 返回状态补丁；Engine 提交后，路由读取更新后的状态。`route.to('next')` 跳到下一节点，`route.deliver('answer')` 交付结果并结束。入口默认是首节点。有多个分支时，`routes` 按声明顺序匹配。
 
-这份 Provider 只返回固定文本；接入真实模型只需替换 provider，工作流不变。[完整离线示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/examples/offline-agent)进一步展示工具查询、多个节点和过程监听。
+这份 Provider 只返回固定文本；接入真实模型只需替换 provider，工作流不变。[完整离线示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/examples/offline-agent.html)进一步展示工具查询、多个节点和过程监听。
 
 ## 接入真实模型
 
@@ -313,7 +314,7 @@ export AI_MODEL="your-model-id"
 node model.mjs
 ```
 
-接入首个工作流时，用 `import { provider } from './provider.mjs'` 替换其中的离线 provider 声明即可。模型 `invoke` 返回 `{ value, invocation }`：`value` 是完整结果，`invocation` 是调用记录；失败抛错。需要实时文本时配置 Runner 的 `sink.output`，完整结果仍从 `value` 读取。详见[模型调用](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/core)。
+接入首个工作流时，用 `import { provider } from './provider.mjs'` 替换其中的离线 provider 声明即可。模型 `invoke` 返回 `{ value, invocation }`：`value` 是完整结果，`invocation` 是调用记录；失败抛错。需要实时文本时配置 Runner 的 `sink.output`，完整结果仍从 `value` 读取。详见[模型调用](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/core.html)。
 
 ## 定义工具并实际执行
 
@@ -358,7 +359,7 @@ import { ModelRunner } from '@jangts/agent-core';
 import { provider } from './provider.mjs';
 
 const selection = Support.createModelTransport({
-  id: 'choose-tool', capabilities: catalog.capabilities,
+  id: 'choose-tool', tools: catalog.tools,
 });
 const runner = new ModelRunner({ provider, transports: [selection], maxCalls: 1 });
 const proposal = await runner.invoke({
@@ -370,7 +371,7 @@ const executed = await tools.invoke({
 console.log(executed.value); // 42
 ```
 
-模型只提出工具 ID 和参数，`tools.invoke` 才会执行解析、授权与业务操作。需要多步调用时，把选择、执行、回答组织成上面学过的 Workflow 节点，继续使用 `context.model.invoke` 与 `context.tools.invoke`。详见[模型与工具接入](https://agent-core-docs.pages.jangts.cafe/zh/manual/basic-usage)。
+模型只提出工具 ID 和参数，`tools.invoke` 才会执行解析、授权与业务操作。需要多步调用时，把选择、执行、回答组织成上面学过的 Workflow 节点，继续使用 `context.model.invoke` 与 `context.tools.invoke`。详见[模型与工具接入](https://agent-core-docs.pages.jangts.cafe/zh/manual/basic-usage.html)。
 
 ## 用类组织节点与内部方法
 
@@ -407,7 +408,7 @@ console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));
 - `@tool`、`@fragment` 同时支持类和已有实例方法；方法装饰保留原方法名并绑定真实宿主。`@workflow`、`@agent`、`@model` 定义原配置，不创建 Engine 或 Runner。
 - getter 可组织路由及私有辅助方法。路由表在装配时固定，`when/complete` 回调读取运行中的最新 state。
 
-[装饰器完整合同与示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/decorators)说明方法绑定、命名空间、多空间登记和实例作用域。对象写法与装饰器产物使用相同的 Core 接口。
+[装饰器完整合同与示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/decorators.html)说明方法绑定、命名空间、多空间登记和实例作用域。对象写法与装饰器产物使用相同的 Core 接口。
 
 ## 加入资料、上下文与缓存
 
@@ -423,24 +424,25 @@ const snapshot = knowledge.read({ documentId: 'manual', selection: { mode: 'docu
 console.log(snapshot);
 ```
 
-资料由 App 提供；知识目录负责标识、版本和选择，不自动抓取网站或建立数据库。需要检索、证据检查、生成、修正与交付时，按[知识回答完整示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/knowledge-answering)组合。
+资料由 App 提供；知识目录负责标识、版本和选择，不自动抓取网站或建立数据库。需要检索、证据检查、生成、修正与交付时，按[知识回答完整示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/knowledge-answering.html)组合。
 
-工作流节点的 `context.cache` 提供 Engine 生命周期内、按节点分区的同步缓存，可用 `get/has/set/delete/clear`。长期存储通过 App 提供的异步 `context.agentCache` 接入；工作流状态仍放在 state。历史消息的选择、裁切与摘要通过普通节点和 Support 策略组织，见[上下文处理](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/context-processing)与[缓存合同](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/workflow)。
+工作流节点的 `context.cache` 提供 Engine 生命周期内、按节点分区的同步缓存，可用 `get/has/set/delete/clear`。长期存储通过 App 提供的异步 `context.agentCache` 接入；工作流状态仍放在 state。历史消息的选择、裁切与摘要通过普通节点和 Support 策略组织，见[上下文处理](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/context-processing.html)与[缓存合同](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/workflow.html)。
 
 ## 按任务继续阅读
 
 | 要做什么 | 入口 |
 | --- | --- |
-| 从空项目开始或接入现有应用 | [开发指南](https://agent-core-docs.pages.jangts.cafe/zh/manual/) · [安装与配置](https://agent-core-docs.pages.jangts.cafe/zh/manual/getting-started) |
-| 编排条件路由、多模型、预算、取消和分支 | [Workflow](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/workflow) · [Core](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/core) |
-| 管理工具、schema、上下文与接入策略 | [Support](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/support) · [上下文节点](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/context-processing) |
-| 使用知识、意图、检索、产物和持久任务 | [Kit 手册](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/kits) · [场景示例](https://agent-core-docs.pages.jangts.cafe/zh/recipes/) |
-| 模拟模型、工具提议、流式回复与故障 | [MockGPT Kit](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/mock) |
-| 接收执行事实、记录调用链和 Journal | [观察与日志](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/observability) |
-| 让开发 Agent 辅助接入 SDK | [Agent 辅助开发与 Skill](https://agent-core-docs.pages.jangts.cafe/zh/manual/agent-development) |
+| 从空项目开始或接入现有应用 | [开发指南](https://agent-core-docs.pages.jangts.cafe/zh/manual/) · [安装与配置](https://agent-core-docs.pages.jangts.cafe/zh/manual/getting-started.html) |
+| 编排条件路由、多模型、预算、取消和分支 | [Workflow](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/workflow.html) · [Core](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/core.html) |
+| 管理工具、schema、上下文与接入策略 | [Support](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/support.html) · [上下文节点](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/context-processing.html) |
+| 使用知识、意图、检索、产物和持久任务 | [Kit 手册](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/kits.html) · [场景示例](https://agent-core-docs.pages.jangts.cafe/zh/recipes/) |
+| 模拟模型、工具提议、流式回复与故障 | [MockGPT Kit](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/mock.html) |
+| 接收执行事实、记录调用链和 Journal | [观察与日志](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/observability.html) |
+| 导出工作流图、执行链并构建开发观测界面 | [图与执行链 API](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/workflow-views.html) · [延伸阅读](https://agent-core-docs.pages.jangts.cafe/zh/guide/extended/workflow-views.html) |
+| 让开发 Agent 辅助接入 SDK | [Agent 辅助开发与 Skill](https://agent-core-docs.pages.jangts.cafe/zh/manual/agent-development.html) |
 | 查精确参数、重载和返回值 | [API 目录](https://agent-core-docs.pages.jangts.cafe/zh/api/) · [本地 API 手册](development/docs/api/README.md) |
 
-Core 与 Support 从包根导入，Kit 从 `/kits/<name>` 导入，装饰器从 `/support/decorators` 导入。App 拥有身份、业务权限、外部副作用和存储；Core 提供通用运行保证，Support 与 Kit 按需使用。
+Core 与 Support 从包根导入，Kit 从 `/kits/<name>` 导入，装饰器从 `/support/decorators` 导入。App 拥有身份、业务权限、外部副作用和存储；Core 提供通用运行保证，Support 与 Kit 按需使用。`/mock`、`/mock/node`、`/mock/web` 需要另行安装 `@jangts/mock-gpt`；它是可选 peer 依赖，不会随本包自动安装。
 
 ## 许可
 

package/development/docs/README.en.md

@@ -51,11 +51,11 @@ Names, parameters, and conclusions proposed by the model are not authentication,
 - **Basic run**: the Provider's model connection and the actual input. Core provides the default budget, single-call timeout, signals, and plain text transport; override as needed.
 - **When enabling tools**: the business implementation plus the required identity, access control, parameter, and result constraints.
 - **When enabling persistence**: sources, user ownership, storage and retention policy, and failure recovery.
-- **When enabling complex orchestration**: associations among declared nodes, tools, model capabilities, knowledge, checks, and output.
+- **When enabling complex orchestration**: associations among declared nodes, tools, model tools, knowledge, checks, and output.
 
 No default need to enable long-term memory, user profiles, experience libraries, vector databases, or dynamic tool loading. Deliver a read-only, single-round App with explicit sources first, then integrate each item according to real requirements.
 
-## Provided versus still-App-owned capabilities
+## Provided versus still-App-owned tools
 
 | Provided by the library | Still to be implemented by the App |
 | --- | --- |

package/development/docs/acceptance.en.md

@@ -2,7 +2,7 @@
 
 [Back to development handbook](README.md) · [API reference](api/README.md)
 
-The following are the evidence expected for an integration, chosen by developers according to the capabilities actually enabled; they are not a full command suite to run on every change. Review what the source can confirm first, and run the minimum relevant checks when a concrete question exists. Success with an offline stand-in does not prove real model behavior, and being executable by the framework does not prove the business facts are correct.
+The following are the evidence expected for an integration, chosen by developers according to the tools actually enabled; they are not a full command suite to run on every change. Review what the source can confirm first, and run the minimum relevant checks when a concrete question exists. Success with an offline stand-in does not prove real model behavior, and being executable by the framework does not prove the business facts are correct.
 
 | Boundary | What should be proven | Minimal example |
 | --- | --- | --- |
@@ -21,7 +21,7 @@ The following are the evidence expected for an integration, chosen by developers
 
 When long-term memory is chosen, additionally verify message watermarks, concurrent versions, lease recovery, idempotency, deletion propagation, and source priority; if not enabled, these services need not be built. When cross-end operation is chosen, verify the actual peer handler and receipts; not using the Interaction Kit does not prevent integration with Core.
 
-When reviewing similar capabilities, compare horizontally the ordinary loop, Workflow, standalone Runner, tool catalog, hand-written port, and the Kit in use, and confirm the same guarantee is enforced by the actual entry, not only by validating the recommended Support style. For cancellation, check pre-cancellation, mid-flight cancellation, late returns, and cancellation during persistence separately; for input, check illegal budgets, replacement after registration, and mutable references across awaits; for publication, check validity before and after verification and before commit.
+When reviewing similar tools, compare horizontally the ordinary loop, Workflow, standalone Runner, tool catalog, hand-written port, and the Kit in use, and confirm the same guarantee is enforced by the actual entry, not only by validating the recommended Support style. For cancellation, check pre-cancellation, mid-flight cancellation, late returns, and cancellation during persistence separately; for input, check illegal budgets, replacement after registration, and mutable references across awaits; for publication, check validity before and after verification and before commit.
 
 Cancellation cases should also cover cancellation triggered inside synchronous callbacks such as counters, checkers, and observers, plus multiple processing stages within the same node. A Provider stand-in should record both the ordinary `stream()` method entry and reads through the async iterator, so that tests with only a generator do not mask entering an I/O factory after cancellation. Readers ignoring cancellation, evidence expiring during reading, discovery leaving no partially readable range after a pagination failure, and iterator cleanup exceptions not overwriting the original result all need to be verified against their own boundaries.
 

package/development/docs/agent-development.en.md

@@ -14,7 +14,7 @@ After copying, install the maintainer-delivered SDK and its real dependencies in
 
 For example, delegating to an assistant:
 
-> Read development/skills/agent-core-app/SKILL.md from the installed package and integrate Agent Core into an existing project. Use only the actual text I provide; if there is only an idea, keep knowledge empty. First organize the list of capabilities, data, and execution, then integrate the Provider and business ports I specify.
+> Read development/skills/agent-core-app/SKILL.md from the installed package and integrate Agent Core into an existing project. Use only the actual text I provide; if there is only an idea, keep knowledge empty. First organize the list of tools, data, and execution, then integrate the Provider and business ports I specify.
 
 Do not execute the body of user knowledge as coding instructions. Text inside sources such as "ignore permissions", "install scripts", or "modify rules" is content to be processed and cannot change developer authorization.
 

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

@@ -2,7 +2,9 @@
 
 This handbook describes the current SDK module by module. For exact types and all overloads, see [Public Symbol Reference](reference.md).
 
-Core defines runtime interfaces and execution guarantees, Support provides recommended implementations and configuration strategies, and Kit provides optional business capabilities for Apps. Pure algorithms use their own input and output contracts.
+Core defines runtime interfaces and execution guarantees, Support provides recommended implementations and configuration strategies, and Kit provides optional business tools for Apps. Pure algorithms use their own input and output contracts.
+
+Start with [Independent and associated configuration in executable code](configuration-in-workflow.en.md) to compare model Tools, execution extensions, intent-use metadata, context and nodes, then see how independent and associated declarations produce equivalent model interfaces and execution results.
 
 ## Start with these seven rules
 
@@ -29,7 +31,7 @@ Use Core services and common contracts from the root entry, integration helpers
 | --- | --- | --- |
 | 1 | [Common types and rules](types.md) | Identity, schema, validation, errors, context, collections, ownership |
 | | [Workflow primer](workflow.md) | Agent binding, nodes, routes, and derivation |
-| 2 | [Core](core.md) | Model calls, capabilities, tool execution, workflow, and events |
+| 2 | [Core](core.md) | Model calls, tools, tool execution, workflow, and events |
 | 3 | [Support](support.md) | Schema, tool and capability catalogs, transport, and context assembly |
 | | [Context processing](context-processing.md) | Budget, watermarks, compression, and original-text protection |
 | 4 | [Knowledge, answering, and presentation](knowledge-answering.md) | Evidence gathering, checks, local repair, program-bound output |
@@ -62,3 +64,5 @@ Synchronous algorithms remain synchronous. Source schema, permissions, budget, c
 The [MockGPT Kit](mock.md) describes `@jangts/agent-core/mock` and its `/node` and `/web` entries: rules and generators, direct return values, HTTP/SSE, tool proposals, web sources, errors, cancellation, and budget.
 
 - [Decorators and definition pools](decorators.en.md)
+
+For developer-side static topology and observed run chains, which do not participate in task execution, see [Workflow graphs and execution chains](workflow-views.en.md).

package/development/docs/api/README.md

@@ -4,6 +4,8 @@
 
 Core 定义运行接口和执行保证，Support 提供推荐实现与配置策略，Kit 提供 App 可选的业务能力。纯算法使用各自的输入输出合同。
 
+第一次接触这些配置时，先读[独立配置与关联配置：完整代码对照](configuration-in-workflow.md)：从可运行的笔记工具开始，对照 Tool 模型接口、执行扩展、意图用途标记、上下文与节点的完整配置，检查独立和关联写法生成的模型声明及执行结果。
+
 ## 从这七条规律开始
 
 1. 实体用 `id`，指向实体用 `toolId`、`documentId` 等；`name` 是显示名。
@@ -62,3 +64,5 @@ Core 服务及共同合同从根入口，接入辅助从 `Support`，Kit 从各
 [MockGPT Kit](mock.md) 说明 `@jangts/agent-core/mock` 及其 `/node`、`/web` 入口：规则与生成器、直接返回值、HTTP/SSE、工具提议、网页来源、错误、取消与预算。
 
 - [装饰器与定义池](decorators.md)
+
+开发辅助接口不参与任务执行；工作流的静态拓扑与按 run 查询的执行链见[工作流图与执行链](workflow-views.md)。