@jangts/agent-core 0.2.5 → 0.3.6

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 本文件记录 `@jangts/agent-core` 的行为变更。接口合同与使用方式见[API 手册](development/docs/api/README.md)。
 
+## 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.
+
+## 0.3.2
+
+- Expand the English-first bilingual README with runnable workflows, model configuration, tools, decorators, knowledge and task-based documentation links.
+
+## 0.3.1
+
+- Shared per-kind decorator readers with namespace isolation: ns defaults to 'default', accepts multiple namespaces, and leaves original ids unchanged. Read via get(id, ns?), getAll(ns?) and pick(ids, ns?). No public pool factories or owner lookups.
+- Host-method decorators automatically bind and register during instance initialization. Constructor failures are wiring failures and do not roll back completed initialization registrations.
+
+- Named decorator implementation types: Node, Tool, Fragment, Workflow, Agent and Model; class examples no longer repeat Omit.
+- Decorator class constraints preserve union branches, including required App dependencies in Engine configurations.
+
+## 0.3.0
+
+- Optional standard class and instance-method decorators in `/support/decorators` for nodes, tools and fragments; class decorators for workflow, Agent configuration and ModelRunner options.
+- Classes are constructed once as definitions; methods bind the real host and preserve private state. The decorator supplies id without creating Engines, Runners or request budgets.
+- Explicit DefinitionPool registration/read/selection/sealing and owner-local definitionOf reads, including ESM/CJS cross-reading of the same decorated owner.
+- Original object APIs, execution, authorization, cancellation and 0.2.5 cache semantics remain unchanged. Bottom-level function converters are internal only.
+
 ## 0.2.5
 
 - Engine-owned, bounded LRU `context.cache` with node partitions and optional write TTL.

package/README.md

@@ -6,50 +6,218 @@
 
 <img src="https://agent-core-docs.pages.jangts.cafe/branding/agent-core-logo.png" alt="Agent Core" width="420">
 
-A platform-independent agent runtime with a runtime API, companion Support utilities, and optional Kits. Supports ESM, CommonJS, browsers, and Node.js.
+Agent Core builds application-owned agents with explicit tools, state, routes and completion conditions. You define business handlers and orchestration; Core handles model/tool calls, state commits, budgets, cancellation and execution facts. Start with a single model call or add workflows, knowledge and class decorators as needed.
 
-[Full developer documentation](https://agent-core-docs.pages.jangts.cafe)
+## Install and run an Agent
+
+Use **Node.js ≥ 22.12.0**. The package ships ESM, CommonJS and TypeScript declarations. Browser integrations require the Web APIs in use; keep model credentials on your server.
 
 ```sh
+mkdir agent-demo
+cd agent-demo
+npm init -y
 npm install @jangts/agent-core
 ```
 
-A minimal Core call needs only a Provider and raw input. Support is optional:
+Save as `app.mjs` and run `node app.mjs`. This runs a real workflow against a fixed offline Provider without credentials or network requests.
+
+```js
+import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core';
+
+const workflow = defineWorkflow({
+  id: 'greeting',
+  nodes: [{
+    id: 'reply',
+    description: 'Generate a greeting',
+    async run(state, { model }) {
+      const { value } = await model.invoke({ input: state.question });
+      return { answer: value };
+    },
+    routes: [route.deliver('answer')],
+  }],
+});
+
+// An offline Provider: no credentials, network or real model inference.
+const provider = { async *stream() { yield 'Hello, Agent Core!'; } };
+const agent = new AgentCoreEngine({ workflow, model: { provider, maxCalls: 1 } });
+console.log(await agent.run({ question: 'Hello' }));
+// Hello, Agent Core!
+```
+
+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.
 
-```ts
-import { CompatibleModelProvider, ModelRunner } from '@jangts/agent-core';
+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
+
+For a Chat Completions-compatible service, save this as `provider.mjs`. `baseUrl` is the API base URL, excluding `/chat/completions`.
+
+```js
+import { Support } from '@jangts/agent-core';
+
+const { AI_BASE_URL, AI_API_KEY, AI_MODEL } = process.env;
+if (!AI_BASE_URL || !AI_API_KEY || !AI_MODEL) {
+  throw new Error('Set AI_BASE_URL, AI_API_KEY and AI_MODEL');
+}
+export const provider = new Support.CompatibleModelProvider({
+  config: { baseUrl: AI_BASE_URL, apiKey: AI_API_KEY, model: AI_MODEL },
+});
+```
+
+For a single question, use ModelRunner directly. Save as `model.mjs`:
+
+```js
+import { ModelRunner } from '@jangts/agent-core';
+import { provider } from './provider.mjs';
+
+const runner = new ModelRunner({
+  provider,
+  maxCalls: 2,
+  callTimeoutMs: 15000,
+  execution: { signal: AbortSignal.timeout(30000) },
+});
+const result = await runner.invoke('Explain what an Agent is in one sentence.');
+console.log(result.value);
+```
+
+Configure your service and run:
 
-const provider = new CompatibleModelProvider({ config: {
-  baseUrl: process.env.AI_BASE_URL!,
-  apiKey: process.env.AI_API_KEY!,
-  model: process.env.AI_MODEL!,
-} });
-const model = new ModelRunner({ provider });
-const text = (await model.invoke('Hello')).value;
+```sh
+export AI_BASE_URL="https://your-provider.example/v1"
+export AI_API_KEY="your-api-key"
+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.html).
+
+## Define and execute a tool
+
+Save as `tools.mjs` and run `node tools.mjs`. One tool declaration provides model-visible schema, real input parsing, authorization, execution and output checking:
+
+```js
+import { Support } from '@jangts/agent-core';
+
+const catalog = Support.defineToolCatalog([{
+  id: 'double', kind: 'pure', description: 'Double a finite number.',
+  inputSchema: {
+    jsonSchema: {
+      type: 'object', required: ['value'], additionalProperties: false,
+      properties: { value: { type: 'number' } },
+    },
+    parse(input) {
+      if (!input || typeof input !== 'object' || !Number.isFinite(input.value)) {
+        throw new TypeError('value must be a finite number');
+      }
+      return input.value;
+    },
+  },
+  authorize() {}, // Public arithmetic; user data tools check App permissions here.
+  execute: value => value * 2,
+  parseOutput(value) {
+    if (!Number.isFinite(value)) throw new TypeError('Invalid result');
+    return value;
+  },
+}]);
+
+const tools = catalog.bind({ app: undefined });
+const result = await tools.invoke({ toolId: 'double', input: { value: 21 } });
+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:
+
+```js
+import { ModelRunner } from '@jangts/agent-core';
+import { provider } from './provider.mjs';
+
+const selection = Support.createModelTransport({
+  id: 'choose-tool', capabilities: catalog.capabilities,
+});
+const runner = new ModelRunner({ provider, transports: [selection], maxCalls: 1 });
+const proposal = await runner.invoke({
+  input: 'Use double to calculate twice 21.', transport: selection,
+});
+const executed = await tools.invoke({
+  toolId: proposal.value.toolId, input: proposal.value.input,
+});
+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.html).
+
+## Organize handlers as classes
+
+With standard TypeScript decorators, classes own configuration, handlers and private helpers. The decorator supplies id, constructs the definition and registers it. Save this standalone example as `greeting.mts`:
+
+```ts
+import { AgentCoreEngine, defineWorkflow } from '@jangts/agent-core';
+import { node, nodePool } from '@jangts/agent-core/support/decorators';
+import type { Node } from '@jangts/agent-core/support/decorators';
+
+type State = { name: string; answer?: string };
+
+@node<State, string>('greet', { ns: 'welcome' })
+class Greeting implements Node<State, string> {
+  readonly description = 'Greet a visitor';
+  #prefix = 'Hello, ';
+  get routes(): Node<State, string>['routes'] {
+    return [{ complete: state => state.answer! }];
+  }
+  run(state: Readonly<State>) { return { answer: this._format(state.name) }; }
+  private _format(name: string) { return this.#prefix + name.trim() + '!'; }
+}
+
+const workflow = defineWorkflow<State, string>({
+  id: 'welcome', nodes: nodePool.getAll('welcome'),
+});
+console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));
+// Hello, Ivan!
 ```
 
-This connects to a real Chat Completions-compatible model; the application supplies all three connection settings. See [Basic usage](development/docs/basic-usage.md) to override settings or add tools, context policies, and workflows.
+Install `npm install -D tsx typescript`, then run `npx tsx greeting.mts`. Existing projects can use their standard-decorator compilation pipeline. NestJS units using `experimentalDecorators` cannot use this syntax directly.
 
-- [How it works](development/docs/mechanisms.md): collaboration, tasks, execution flow, model/tool sequences, and an application knowledge-answering example.
-- [Developer guide](development/docs/README.md): new applications, existing project integration, manual and agent-assisted development, knowledge resources, and runtime growth.
-- [API reference](development/docs/api/README.md): examples, parameters, return values, and exceptions.
-- [Complete knowledge-answering example](development/docs/api/knowledge-answering.md): reading sources, context, generation, checking, and template-based delivery.
+- Each kind has one shared reader. `ns` defaults to `default` and accepts a string array. Read with `nodePool.get(id, ns?)`, `getAll(ns?)` or `pick(ids, ns?)`. Ids are unique within a kind and namespace.
+- `@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.
 
-[MockGPT Kit](development/docs/api/mock.md) provides direct mock generation, Provider protocol injection, a minimal Node server, and web text sources through `@jangts/agent-core/mock`, `/mock/node`, and `/mock/web`, without a separate mock dependency import.
+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.
 
-Import Core and Support from the package root. Import Kits by module, or use the aggregate `/kits` entry point.
+## Add knowledge, context and caching
 
-The package manager installs streaming, mock-gpt, and other runtime dependencies automatically. See [Installation](development/docs/getting-started.md).
+Import optional Kits by module. For example, register and read versioned knowledge:
+
+```js
+import { defineKnowledgeCatalog } from '@jangts/agent-core/kits/knowledge';
+
+const knowledge = defineKnowledgeCatalog([
+  { id: 'manual', revision: 'r1', parts: ['Support hours: 09:00–18:00.'] },
+]);
+const snapshot = knowledge.read({ documentId: 'manual', selection: { mode: 'document' } });
+console.log(snapshot);
+```
 
-The `agent-core-app` Skill provides resource preparation and validation tools. See [Agent-assisted development](development/docs/agent-development.md).
+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.
 
-Regular Workflow nodes assemble, select, trim, or compress context, with replaceable implementations from Support. Core retains generic trust/structure auditing, actual request measurement, budgets, and cancellation guarantees. To retain recent verbatim messages or ongoing task summaries, apply a recommended Support policy to the same configuration and override individual parameters. See [Context nodes](development/docs/api/context-processing.md).
+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).
 
-Bind fixed model definitions, Workflows, and tools ahead of time, passing only per-request state. Existing request-level Runners can join the same Engine through `bindModelRuntime` and reuse its budget and scope. Applications register `execution.observe.event` to receive execution facts; persistent logging is independently optional.
+## Continue by task
 
-`ModelRunner.sink.output` receives actual generated chunks while preserving call budgets, cancellation, and protocol validation; `invoke` still returns the complete result. Applications can use `Support.createReplyPreview` to register previewable functions and body JSON paths, then send in-progress previews with `Support.streamEvents`. Confirm the final body after business validation, or retract it on failure. Previews cannot serve as authorization, tool execution, or official history. See [Core API](development/docs/api/core.md).
+| 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.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) |
 
-In this repository, `npm run test:agent-audit` builds Agent Core and MockGPT and runs logic, security, and performance regressions. Use `-- --repeat=2` for two consecutive rounds or `--no-build` to reuse existing builds. Coverage merges V8 ranges with c8/Istanbul and includes every generated ESM module, including modules not imported by existing tests. Statements, lines, functions, and branches must all reach 100%; uncovered logic fails the audit even if assertions pass. Reports are written to root `.tmp/agent-audit/`. Builds remove stale package output so moved sources cannot leave obsolete modules. Regressions use offline resources, injected ports, and loopback HTTP, without real models or public websites; they do not verify real-model comprehension or decision quality.
+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.
 
 ## License
 
@@ -63,50 +231,218 @@ Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
 
 <img src="https://agent-core-docs.pages.jangts.cafe/branding/agent-core-logo.png" alt="Agent Core" width="420">
 
-平台无关的 Agent 运行库，提供运行 API、配套 Support 与可选 Kit。支持 ESM、CommonJS，以及浏览器／Node 环境。
+Agent Core 用于在应用中构建有明确工具、状态、分支和结束条件的 Agent。你声明业务处理与流程，Core 负责模型调用、工具调用、状态提交、预算、取消和执行记录。既可以只调用一次模型，也可以逐步加入工具、知识资料、工作流与类装饰器。
 
-[完整网页开发文档](https://agent-core-docs.pages.jangts.cafe)
+## 安装并跑通第一个 Agent
+
+需要 **Node.js ≥ 22.12.0**。包提供 ESM、CommonJS 和 TypeScript 声明；浏览器接入需具备所用 Web API，模型密钥保留在服务端。
 
 ```sh
+mkdir agent-demo
+cd agent-demo
+npm init -y
 npm install @jangts/agent-core
 ```
 
-Core 的最小调用只需 Provider 和原始输入，Support 保持可选：
+把下面代码保存为 `app.mjs`，运行 `node app.mjs`。它会实际运行一个工作流并调用离线 Provider，无需密钥或网络。
+
+```js
+import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core';
+
+const workflow = defineWorkflow({
+  id: 'greeting',
+  nodes: [{
+    id: 'reply',
+    description: 'Generate a greeting',
+    async run(state, { model }) {
+      const { value } = await model.invoke({ input: state.question });
+      return { answer: value };
+    },
+    routes: [route.deliver('answer')],
+  }],
+});
+
+// An offline Provider: no credentials, network or real model inference.
+const provider = { async *stream() { yield 'Hello, Agent Core!'; } };
+const agent = new AgentCoreEngine({ workflow, model: { provider, maxCalls: 1 } });
+console.log(await agent.run({ question: 'Hello' }));
+// Hello, Agent Core!
+```
+
+节点的 `run` 返回状态补丁；Engine 提交后，路由读取更新后的状态。`route.to('next')` 跳到下一节点，`route.deliver('answer')` 交付结果并结束。入口默认是首节点。有多个分支时，`routes` 按声明顺序匹配。
 
-```ts
-import { CompatibleModelProvider, ModelRunner } from '@jangts/agent-core';
+这份 Provider 只返回固定文本；接入真实模型只需替换 provider，工作流不变。[完整离线示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/examples/offline-agent.html)进一步展示工具查询、多个节点和过程监听。
+
+## 接入真实模型
+
+支持兼容 Chat Completions 的服务。将连接配置保存为 `provider.mjs`；`baseUrl` 是服务 API 根地址，不包含 `/chat/completions`。
+
+```js
+import { Support } from '@jangts/agent-core';
+
+const { AI_BASE_URL, AI_API_KEY, AI_MODEL } = process.env;
+if (!AI_BASE_URL || !AI_API_KEY || !AI_MODEL) {
+  throw new Error('Set AI_BASE_URL, AI_API_KEY and AI_MODEL');
+}
+export const provider = new Support.CompatibleModelProvider({
+  config: { baseUrl: AI_BASE_URL, apiKey: AI_API_KEY, model: AI_MODEL },
+});
+```
+
+只需一次问答时，可以直接使用 ModelRunner。保存为 `model.mjs`：
+
+```js
+import { ModelRunner } from '@jangts/agent-core';
+import { provider } from './provider.mjs';
+
+const runner = new ModelRunner({
+  provider,
+  maxCalls: 2,
+  callTimeoutMs: 15000,
+  execution: { signal: AbortSignal.timeout(30000) },
+});
+const result = await runner.invoke('Explain what an Agent is in one sentence.');
+console.log(result.value);
+```
+
+配置 `AI_BASE_URL`、`AI_API_KEY`、`AI_MODEL` 后运行 `node model.mjs`，例如：
 
-const provider = new CompatibleModelProvider({ config: {
-  baseUrl: process.env.AI_BASE_URL!,
-  apiKey: process.env.AI_API_KEY!,
-  model: process.env.AI_MODEL!,
-} });
-const model = new ModelRunner({ provider });
-const text = (await model.invoke('你好')).value;
+```sh
+export AI_BASE_URL="https://your-provider.example/v1"
+export AI_API_KEY="your-api-key"
+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.html)。
+
+## 定义工具并实际执行
+
+将下面代码保存为 `tools.mjs`，运行 `node tools.mjs`。工具同时声明模型可见 schema、真实输入解析、授权、执行和结果检查：
+
+```js
+import { Support } from '@jangts/agent-core';
+
+const catalog = Support.defineToolCatalog([{
+  id: 'double', kind: 'pure', description: 'Double a finite number.',
+  inputSchema: {
+    jsonSchema: {
+      type: 'object', required: ['value'], additionalProperties: false,
+      properties: { value: { type: 'number' } },
+    },
+    parse(input) {
+      if (!input || typeof input !== 'object' || !Number.isFinite(input.value)) {
+        throw new TypeError('value must be a finite number');
+      }
+      return input.value;
+    },
+  },
+  authorize() {}, // Public arithmetic; user data tools check App permissions here.
+  execute: value => value * 2,
+  parseOutput(value) {
+    if (!Number.isFinite(value)) throw new TypeError('Invalid result');
+    return value;
+  },
+}]);
+
+const tools = catalog.bind({ app: undefined });
+const result = await tools.invoke({ toolId: 'double', input: { value: 21 } });
+console.log(result.value); // 42
+```
+
+工具定义可复用；`catalog.bind({ app, execution })` 在请求中绑定服务端依赖和取消信号。工具执行成功同样返回 `{ value, invocation }`。
+
+让模型选择工具时，将下面代码接在 `tools.mjs` 末尾，并使用上面的 `provider.mjs`。同一份 catalog 同时生成模型可见能力和真实执行入口：
+
+```js
+import { ModelRunner } from '@jangts/agent-core';
+import { provider } from './provider.mjs';
+
+const selection = Support.createModelTransport({
+  id: 'choose-tool', capabilities: catalog.capabilities,
+});
+const runner = new ModelRunner({ provider, transports: [selection], maxCalls: 1 });
+const proposal = await runner.invoke({
+  input: 'Use double to calculate twice 21.', transport: selection,
+});
+const executed = await tools.invoke({
+  toolId: proposal.value.toolId, input: proposal.value.input,
+});
+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.html)。
+
+## 用类组织节点与内部方法
+
+使用 TypeScript 标准装饰器时，节点类提供配置与实现，装饰器补上 id、实例化并登记；无需手写 new 或 bind。下面是一份独立的 `greeting.mts`：
+
+```ts
+import { AgentCoreEngine, defineWorkflow } from '@jangts/agent-core';
+import { node, nodePool } from '@jangts/agent-core/support/decorators';
+import type { Node } from '@jangts/agent-core/support/decorators';
+
+type State = { name: string; answer?: string };
+
+@node<State, string>('greet', { ns: 'welcome' })
+class Greeting implements Node<State, string> {
+  readonly description = 'Greet a visitor';
+  #prefix = 'Hello, ';
+  get routes(): Node<State, string>['routes'] {
+    return [{ complete: state => state.answer! }];
+  }
+  run(state: Readonly<State>) { return { answer: this._format(state.name) }; }
+  private _format(name: string) { return this.#prefix + name.trim() + '!'; }
+}
+
+const workflow = defineWorkflow<State, string>({
+  id: 'welcome', nodes: nodePool.getAll('welcome'),
+});
+console.log(await new AgentCoreEngine({ workflow }).run({ name: 'Ivan' }));
+// Hello, Ivan!
 ```
 
-以上是兼容 Chat Completions 的真实模型接入；三个连接值由应用提供。接下来按[基础调用说明](development/docs/basic-usage.md)覆盖设置或接入工具、上下文策略和工作流。
+独立运行可安装 `npm install -D tsx typescript`，再执行 `npx tsx greeting.mts`。使用项目编译流程时，保持标准装饰器语义；开启 `experimentalDecorators` 的 NestJS 编译单元不能直接使用这套语法。
 
-- [工作机制图解](development/docs/mechanisms.md)：总体协作、任务概念、执行流程、模型与工具时序，以及 App 知识回答示例。
-- [第三方开发指南](development/docs/README.md)：新应用创建、已有项目接入、手工与 Agent 开发、知识资料及运行增长。
-- [API 手册](development/docs/api/README.md)：调用示例、参数、返回值与异常。
-- [知识回答完整调用](development/docs/api/knowledge-answering.md)：资料读取、上下文、生成、检查与母板交付。
+- 每类各一个共享池；`ns` 默认 `default`，可传字符串数组。`nodePool.get(id, ns?)`、`getAll(ns?)`、`pick(ids, ns?)` 读取定义，同类型同命名空间内 id 唯一。
+- `@tool`、`@fragment` 同时支持类和已有实例方法；方法装饰保留原方法名并绑定真实宿主。`@workflow`、`@agent`、`@model` 定义原配置，不创建 Engine 或 Runner。
+- getter 可组织路由及私有辅助方法。路由表在装配时固定，`when/complete` 回调读取运行中的最新 state。
 
-[MockGPT Kit](development/docs/api/mock.md) 提供直接模拟生成、Provider 协议注入、最小 Node Server 和网页文本来源；使用 `@jangts/agent-core/mock`、`/mock/node`、`/mock/web`，无需单独导入模拟器依赖。
+[装饰器完整合同与示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/decorators.html)说明方法绑定、命名空间、多空间登记和实例作用域。对象写法与装饰器产物使用相同的 Core 接口。
 
-Core 与 Support 从包根调用。Kit 默认按模块引入，也保留独立的 `/kits` 全量入口。
+## 加入资料、上下文与缓存
 
-包管理器会自动安装 streaming、mock-gpt 及其他运行依赖，具体步骤见[安装指南](development/docs/getting-started.md)。
+可选 Kit 按模块导入。例如直接登记并读取有版本的资料：
+
+```js
+import { defineKnowledgeCatalog } from '@jangts/agent-core/kits/knowledge';
+
+const knowledge = defineKnowledgeCatalog([
+  { id: 'manual', revision: 'r1', parts: ['Support hours: 09:00–18:00.'] },
+]);
+const snapshot = knowledge.read({ documentId: 'manual', selection: { mode: 'document' } });
+console.log(snapshot);
+```
 
-资料准备与校验工具由 `agent-core-app` Skill 提供，使用方式见[Agent 辅助开发](development/docs/agent-development.md)。
+资料由 App 提供；知识目录负责标识、版本和选择，不自动抓取网站或建立数据库。需要检索、证据检查、生成、修正与交付时，按[知识回答完整示例](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/knowledge-answering.html)组合。
 
-上下文通过普通 Workflow 节点装配、选择、裁切或压缩，Support 提供可替换实现；Core 保留通用信任／结构审计、真实请求测量、预算与取消保证。需要保留近期原文或连续任务摘要时，可在同一配置上使用 Support 推荐策略，再精确覆盖参数，见[上下文节点](development/docs/api/context-processing.md)。
+工作流节点的 `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)。
 
-固定模型定义、Workflow 和工具可提前绑定，请求只传本次状态。已有请求级 Runner 可通过 `bindModelRuntime` 接入同一 Engine，复用其预算与作用域；App 注册 `execution.observe.event` 获取过程事实，日志持久化独立可选。
+## 按任务继续阅读
 
-`ModelRunner.sink.output` 可在保留调用预算、取消和协议校验的同时接收真实生成分片，`invoke` 仍返回完整结果。App 可选用 `Support.createReplyPreview` 登记允许预览的函数与正文 JSON 路径，配合 `Support.streamEvents` 发送生成中预览；业务校验通过后再确认正式正文，失败时撤回。预览不能用作授权、工具执行或正式历史，详见[Core API](development/docs/api/core.md)。
+| 要做什么 | 入口 |
+| --- | --- |
+| 从空项目开始或接入现有应用 | [开发指南](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) |
 
-仓库内运行 `npm run test:agent-audit` 可构建 Agent Core 与 MockGPT 并执行逻辑、安全和性能回归；`-- --repeat=2` 连续执行两轮，`--no-build` 复用已有构建。覆盖统计通过 c8／Istanbul 合并 V8 区间，包含全部生成的 ESM 模块，未被现有测试导入的模块也参与统计；语句、行、函数与分支覆盖率均以 100% 为通过门槛，存在未覆盖逻辑即失败，测试断言通过不能替代此门槛；报告写入根 `.tmp/agent-audit/`。构建清理本包旧产物，避免源码移动后残留失效模块。回归使用离线资料、注入端口与本机回环 HTTP，不调用真实模型或公网网站；不验证真实模型的理解与决策质量。
+Core 与 Support 从包根导入，Kit 从 `/kits/<name>` 导入，装饰器从 `/support/decorators` 导入。App 拥有身份、业务权限、外部副作用和存储；Core 提供通用运行保证，Support 与 Kit 按需使用。
 
 ## 许可
 

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

@@ -60,3 +60,7 @@ Synchronous algorithms remain synchronous. Source schema, permissions, budget, c
 ## Mock model
 
 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

@@ -60,3 +60,7 @@ Core 服务及共同合同从根入口，接入辅助从 `Support`，Kit 从各
 ## 模拟模型
 
 [MockGPT Kit](mock.md) 说明 `@jangts/agent-core/mock` 及其 `/node`、`/web` 入口：规则与生成器、直接返回值、HTTP/SSE、工具提议、网页来源、错误、取消与预算。
+
+- [装饰器与定义池](decorators.md)
+
+开发辅助接口不参与任务执行；工作流的静态拓扑与按 run 查询的执行链见[工作流图与执行链](workflow-views.md)。