@jangts/agent-core 0.2.1 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 本文件记录 `@jangts/agent-core` 的行为变更。接口合同与使用方式见[API 手册](development/docs/api/README.md)。
 
+## 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.
+- Optional asynchronous App-owned `context.agentCache`; persistent and volatile spaces are explicit, independent and never silently fall back.
+- Both workflow and `$step` contexts expose the same cache operations; forks have fresh memory and only use an explicitly restored App cache port.
+- Vector filter, grouping and returned-hit metadata use independent snapshots so callback mutations cannot affect later consumers.
+
 ## 0.2.1
 
 ### 变更

package/README.md

@@ -6,50 +6,217 @@
 
 <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) 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).
+
+## 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).
+
+## 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) 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) 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) and [cache contracts](https://agent-core-docs.pages.jangts.cafe/en/manual/api/workflow).
 
-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) |
+| 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) |
+| 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 +230,217 @@ 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)进一步展示工具查询、多个节点和过程监听。
+
+## 接入真实模型
+
+支持兼容 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)。
+
+## 定义工具并实际执行
+
+将下面代码保存为 `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)。
+
+## 用类组织节点与内部方法
+
+使用 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)说明方法绑定、命名空间、多空间登记和实例作用域。对象写法与装饰器产物使用相同的 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)组合。
 
-上下文通过普通 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)与[缓存合同](https://agent-core-docs.pages.jangts.cafe/zh/manual/api/workflow)。
 
-固定模型定义、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) |
+| 编排条件路由、多模型、预算、取消和分支 | [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) |
+| 查精确参数、重载和返回值 | [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,5 @@ 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)

package/development/docs/api/README.md

@@ -60,3 +60,5 @@ Core 服务及共同合同从根入口，接入辅助从 `Support`，Kit 从各
 ## 模拟模型
 
 [MockGPT Kit](mock.md) 说明 `@jangts/agent-core/mock` 及其 `/node`、`/web` 入口：规则与生成器、直接返回值、HTTP/SSE、工具提议、网页来源、错误、取消与预算。
+
+- [装饰器与定义池](decorators.md)

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

@@ -0,0 +1,83 @@
+# Decorators and definition pools
+
+Import decorators and readers from `@jangts/agent-core/support/decorators`. Only standard TypeScript decorators are supported; NestJS compilation units using experimentalDecorators cannot use this syntax directly. Original object, define, constructor and bind paths remain available. No runtime dependency, reflection metadata or automatic DI is added.
+
+Class decorators construct a definition once after static initialization and supply id. Classes own their original fields, handlers, private helpers and getters; do not repeat complete options in decorator metadata. Classes require zero-argument construction. Constructors initialize definitions without business operations. No Engine, Runner, request budget or model call is created.
+
+## Named class contracts
+
+Import Node, Tool, Fragment, Workflow, Agent and Model from the decorator subpath. These contracts omit the decorator-owned id. Object-shaped contracts support implements; Agent preserves the original union and is checked by its decorator rather than requiring a class to implement a union. Getters, private fields and prototype methods retain their original receiver.
+
+```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 = { text: string; answer?: string };
+@node<State, string>('greet', { ns: 'chat' })
+class Greeting implements Node<State, string> {
+  readonly description = 'Greeting';
+  readonly routes = [{ complete: (state: Readonly<State>) => state.answer! }];
+  #prefix = 'Hello, ';
+  run(state: Readonly<State>) { return { answer: this._format(state.text) }; }
+  private _format(text: string) { return this.#prefix + text.trim(); }
+}
+const workflow = defineWorkflow<State, string>({ id: 'greeting', nodes: nodePool.getAll('chat') });
+console.log(await new AgentCoreEngine({ workflow }).run({ text: 'visitor' }));
+```
+
+## Namespaces and reads
+
+Each kind has one shared reader: nodePool, toolPool, fragmentPool, workflowPool, agentPool and modelPool. Consumers do not create pools or register definitions manually. Every decorator accepts optional `{ ns: string | readonly string[] }`, defaulting to `'default'`.
+
+```ts
+nodePool.get('greet', 'chat');
+nodePool.getAll('chat');
+nodePool.pick(['greet', 'answer'], 'chat');
+nodePool.get('greet');    // default namespace
+nodePool.getAll();       // only default, not every namespace
+nodePool.pick(['greet']);
+```
+
+Ids are unique within one kind and namespace. Other namespaces and kinds may reuse an id. Names match exactly, without hierarchy, wildcard or fallback; blank names and empty namespace arrays reject. Repeated namespaces are deduplicated. An array registers the same definition in multiple namespaces without copying or reconstructing it. All destinations are checked before writing; a conflict leaves no partial registration.
+
+get returns undefined on a miss. getAll returns a frozen registration-order snapshot, or an empty array for an unknown namespace. pick takes an id array, preserves caller order and rejects missing or repeated ids; an empty id array returns an empty snapshot. Reads accept original-definition generics, for example `nodePool.get<WorkflowNode<State, string>>('greet', 'chat')`. The generic describes the caller's expected contract, not a runtime type proof.
+
+ns is external registration metadata, excluded from Core options. Returned ids remain unchanged. Combining same-id definitions from different namespaces in one Workflow or ToolRegistry still fails original uniqueness checks. App owns explicit node ordering and routes. Readers expose no constructors, registration, reset, sealing, tags or owner lookups.
+
+## Existing instance methods
+
+```ts
+class GreetingService {
+  constructor(private readonly prefix: string) {}
+  @node<State, string>('reply', {
+    ns: 'chat-service', description: 'Use an existing service',
+    routes: [{ complete: (state: Readonly<State>) => state.answer! }],
+  })
+  answer(state: Readonly<State>) { return { answer: this.prefix + state.text }; }
+}
+const service = new GreetingService('Hello, ');
+const definition = nodePool.get('reply', 'chat-service');
+```
+
+Standard instance initializers automatically bind and register methods. No registerFrom, manual bind, renamed handler or extra class decorator is needed. Initializers run before instance fields and constructor bodies, so they bind without invoking handlers or reading business fields. Read and execute only after successful host construction. Constructor failures do not roll back completed initializer registrations and must be treated as wiring failures. Pools retain host references; use long-lived services, not request-scoped hosts. A second instance with the same kind, namespace and id rejects without replacing the original binding.
+
+Direct metadata callbacks also bind the host. Nested schema/routes retain their original receiver, and arrow functions retain lexical this. Only public instance methods are supported; static/private methods, top-level function decorator syntax and implicit inheritance merging are unsupported. A class-owned id rejects because its decorator supplies id.
+
+## Original consumers
+
+| Decorator | Class contract | Adapted method | Reader | Original consumer |
+| --- | --- | --- | --- | --- |
+| node | Node<State, Result, App> | run | nodePool | defineWorkflow |
+| tool | Tool<Input, Output, App> | execute | toolPool | defineTool / defineToolCatalog |
+| fragment | Fragment<Input> | format | fragmentPool | defineContextFragments |
+| workflow | Workflow<State, Result, App> | None | workflowPool | defineWorkflow |
+| agent | Agent<State, Result, App> | None | agentPool | Engine constructor |
+| model | Model | None | modelPool | ModelRunner constructor |
+
+agent/model ids are registration keys, not Core branch, model or transport identities. Original schema, graph, trust, authorization, result, budget and cancellation boundaries remain in force. Nodes are validated in the final graph. No public metadata-plus-free-function adapter is provided; top-level functions belong directly in original options.
+
+## Getter-defined routes
+
+A routes getter may return `when: state => this._ready(state)` and `complete: state => this._reply(state)`. Workflow assembly reads and snapshots the table, potentially reading the getter multiple times. Keep getters pure and independent of request state. After state patches commit, route callbacks receive the latest state and can call private helpers. The getter is not re-evaluated each run; do not store request state on shared nodes.
+
+ESM/CJS module copies share roots within one JavaScript realm. Processes, workers and separate realms do not share roots. Independently evaluated classes registering the same kind, namespace and id reject rather than merge. Explicitly retain definition modules in the bundle: discarded side-effect-only imports cannot guarantee registration. Shared definitions must not retain request identity, signal or budget. Reading is neither execution nor authorization.