@jangts/agent-core 0.2.0 → 0.2.5

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

@@ -0,0 +1,273 @@
+# Complete Offline Example: Service Status Q&A
+
+[Back to example index](../examples.md) · [Model and tool integration](../basic-usage.md) · [How it works](../mechanisms.md)
+
+The code below can be copied into a project with the SDK installed and run without model credentials, a database, network access, or extra example files. The Provider only assembles strings from fixed data, so it serves to explain the execution process and has no real semantic understanding; the tool likewise returns only offline demo data.
+
+## Preparation
+
+First obtain the SDK and its real dependencies through the [installation guide](../getting-started.md). Save the complete JavaScript code as `app.mjs` and run `node app.mjs`. Save TypeScript as `app.ts` and use the compilation flow already present in your project; a standalone Node project can set type to module in package.json and install typescript/@types/node:
+
+```sh
+npx tsc --module nodenext --target es2022 --strict --outDir dist app.ts
+node dist/app.js
+```
+
+The two stages are separate code files; do not paste declarations from multiple stages into the same file.
+
+## Stage One: Configure a Single Node
+
+Start by getting state updates and final delivery working end to end. The Workflow entry defaults to the first node, nodes return partial updates, and `route.deliver` reads the final field.
+
+### TypeScript
+
+```ts
+import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core';
+
+type State = { question: string; answer?: string };
+const workflow = defineWorkflow<State, string>({
+  id: 'service-helpdesk',
+  nodes: [{
+    id: 'answer',
+    description: '回答演示服务状态',
+    run: () => ({ answer: '演示服务在线。' }),
+    routes: [route.deliver('answer')],
+  }],
+});
+const agent = new AgentCoreEngine({ workflow });
+const answer = await agent.run({ question: '演示服务在线吗？' });
+console.log(answer);
+```
+
+### JavaScript
+
+```js
+import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core';
+
+const workflow = defineWorkflow({
+  id: 'service-helpdesk',
+  nodes: [{
+    id: 'answer',
+    description: '回答演示服务状态',
+    run: () => ({ answer: '演示服务在线。' }),
+    routes: [route.deliver('answer')],
+  }],
+});
+const agent = new AgentCoreEngine({ workflow });
+const answer = await agent.run({ question: '演示服务在线吗？' });
+console.log(answer);
+```
+
+The expected output is `演示服务在线。`. No model is needed at this point.
+
+## Stage Two: Add Tools, a Model, and Observation
+
+This stage still uses the same defineWorkflow, AgentCoreEngine, and agent.run. The new lookup node first executes the tool and obtains a validated result, and the answer node then calls the already bound model. Listening only receives metadata and explicitly approved node progress, and no persistent log is configured.
+
+`createServiceAgent` is the assembly function of the App in this example, not a new SDK entry point; the fixed tool definition and Workflow are reused outside the function. Each call establishes an independent tool runtime and Engine, which can be used to give a request its own observation and lifecycle. The authorize of a production tool must be connected to real server-side identity and rules; the empty authorization here applies only to the public offline constants in this example.
+
+### TypeScript
+
+```ts
+import { AgentCoreEngine, Support, defineWorkflow, route } from '@jangts/agent-core';
+import type { ChatProvider, ExecutionOptions } from '@jangts/agent-core/types';
+
+type Status = { status: 'online'; latencyMs: number };
+type State = { question: string; service?: Status; answer?: string };
+
+// 固定定义只写一次；这个离线公开资料工具不需要用户身份。
+const tools = Support.defineToolCatalog([{
+  id: 'get_status',
+  kind: 'read',
+  description: '读取演示服务的当前状态',
+  inputSchema: {
+    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
+    parse(value: unknown) {
+      if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).length !== 0) throw new TypeError('状态查询不接受参数');
+      return {};
+    },
+  },
+  authorize() {
+    // 仅适用于本例的公开离线数据；真实用户数据必须在这里校验授权。
+  },
+  execute: (): Status => ({ status: 'online', latencyMs: 12 }),
+  parseOutput(value: unknown): Status {
+    if (!value || typeof value !== 'object') throw new TypeError('状态结果无效');
+    const status = value as Partial<Status>;
+    if (status.status !== 'online' || typeof status.latencyMs !== 'number'
+      || !Number.isFinite(status.latencyMs) || status.latencyMs < 0) {
+      throw new TypeError('状态结果无效');
+    }
+    return { status: status.status, latencyMs: status.latencyMs };
+  },
+}]);
+
+const provider: ChatProvider = {
+  async *stream(messages, context) {
+    context.signal.throwIfAborted();
+    // 固定模拟协议，仅用于离线教程；不是语义理解或事实校验器。
+    const input = JSON.parse(messages.at(-1)?.content ?? '{}');
+    yield `演示服务${input.service.status === 'online' ? '在线' : '不可用'}，延迟 ${input.service.latencyMs}ms。`;
+  },
+};
+
+const workflow = defineWorkflow<State, string>({
+  id: 'service-helpdesk',
+  nodes: [
+    {
+      id: 'lookup',
+      description: '执行状态查询工具',
+      provides: ['service'],
+      async run(_state, { tools, report }) {
+        report({ payload: { phase: 'lookup', message: '正在查询服务状态' } });
+        const { value } = await tools.invoke({ toolId: 'get_status', input: {} });
+        return { service: value as Status };
+      },
+      routes: [route.to('answer')],
+    },
+    {
+      id: 'answer',
+      description: '根据查询回执组织回答',
+      requires: ['service'],
+      provides: ['answer'],
+      async run(state, { model }) {
+        const { value } = await model.invoke({
+          input: JSON.stringify({ question: state.question, service: state.service }),
+        });
+        return { answer: value };
+      },
+      routes: [route.deliver('answer')],
+    },
+  ],
+});
+
+export function createServiceAgent(execution: ExecutionOptions = {}) {
+  const runtime = tools.bind({ app: {} });
+  return new AgentCoreEngine({
+    workflow,
+    model: { provider, maxCalls: 1 },
+    maxRounds: 1,
+    execution,
+  }).bindToolRuntime(runtime);
+}
+
+const agent = createServiceAgent({
+  observe: {
+    accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
+    event(fact) {
+      if (fact.type === 'node.progress') console.log('[进度]', fact.payload.payload);
+      if (fact.type === 'model.start') console.log('[进度] 正在组织回答');
+    },
+  },
+});
+console.log(await agent.run({ question: '演示服务在线吗？' }));
+```
+
+### JavaScript
+
+```js
+import { AgentCoreEngine, Support, defineWorkflow, route } from '@jangts/agent-core';
+
+const tools = Support.defineToolCatalog([{
+  id: 'get_status',
+  kind: 'read',
+  description: '读取演示服务的当前状态',
+  inputSchema: {
+    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
+    parse(value) {
+      if (!value || typeof value !== 'object' || Array.isArray(value)
+        || Object.keys(value).length !== 0) throw new TypeError('状态查询不接受参数');
+      return {};
+    },
+  },
+  authorize() {
+    // 仅适用于本例的公开离线数据；真实用户数据必须在这里校验授权。
+  },
+  execute: () => ({ status: 'online', latencyMs: 12 }),
+  parseOutput(value) {
+    if (!value || typeof value !== 'object' || value.status !== 'online'
+      || typeof value.latencyMs !== 'number' || !Number.isFinite(value.latencyMs)
+      || value.latencyMs < 0) throw new TypeError('状态结果无效');
+    return { status: value.status, latencyMs: value.latencyMs };
+  },
+}]);
+
+const provider = {
+  async *stream(messages, context) {
+    context.signal.throwIfAborted();
+    const input = JSON.parse(messages.at(-1)?.content ?? '{}');
+    yield `演示服务${input.service.status === 'online' ? '在线' : '不可用'}，延迟 ${input.service.latencyMs}ms。`;
+  },
+};
+
+const workflow = defineWorkflow({
+  id: 'service-helpdesk',
+  nodes: [
+    {
+      id: 'lookup',
+      description: '执行状态查询工具',
+      provides: ['service'],
+      async run(_state, { tools, report }) {
+        report({ payload: { phase: 'lookup', message: '正在查询服务状态' } });
+        const { value } = await tools.invoke({ toolId: 'get_status', input: {} });
+        return { service: value };
+      },
+      routes: [route.to('answer')],
+    },
+    {
+      id: 'answer',
+      description: '根据查询回执组织回答',
+      requires: ['service'],
+      provides: ['answer'],
+      async run(state, { model }) {
+        const { value } = await model.invoke({
+          input: JSON.stringify({ question: state.question, service: state.service }),
+        });
+        return { answer: value };
+      },
+      routes: [route.deliver('answer')],
+    },
+  ],
+});
+
+export function createServiceAgent(execution = {}) {
+  const runtime = tools.bind({ app: {} });
+  return new AgentCoreEngine({
+    workflow,
+    model: { provider, maxCalls: 1 },
+    maxRounds: 1,
+    execution,
+  }).bindToolRuntime(runtime);
+}
+
+const agent = createServiceAgent({
+  observe: {
+    accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
+    event(fact) {
+      if (fact.type === 'node.progress') console.log('[进度]', fact.payload.payload);
+      if (fact.type === 'model.start') console.log('[进度] 正在组织回答');
+    },
+  },
+});
+console.log(await agent.run({ question: '演示服务在线吗？' }));
+```
+
+Lookup and model progress appear first, and the final output is:
+
+```text
+演示服务在线，延迟 12ms。
+```
+
+Tool and model invocations each return `{ value, invocation }`; the final Result of the current Workflow is a string. These two boundaries do not need to share the same shape. Nodes report only a payload, and the Loop handles execution identity, time, and correlation.
+
+The `as Status` in the TypeScript example does not perform runtime validation. Real validation is done by the tool's parseOutput, which then associates the result of a known demo tool with the state type. When integrating with Node/NestJS or another host, you still need to establish identity, authorization, and signal per request, and must not hand a client's permission flag directly to the model or tool as a trusted condition.
+
+## Keep Configuring Without Changing the Entry Point
+
+- Cancel this run: `agent.run({ question }, { signal })`.
+- Add a real model: replace the bound Provider and keep the same node calls and result reads.
+- Add conditional branches: use raw routes or route builders in the ordinary routes array.
+- Handle over-limit input: add an explicit node per the [context node contract](../api/context-processing.md); the final model call remains subject to the Core budget check.
+
+The tool order in this example is configured by the Workflow, not chosen by the model. Model capability selection should register a capability schema, a transport, and a real authorized execution entry separately, and a model claiming it "looked it up" must not be taken as a real tool receipt.

package/development/docs/examples.en.md

@@ -0,0 +1,36 @@
+# Integration references and maintenance tools
+
+[Back to development handbook](README.md) · [Manual maintenance](maintenance.md) · [Shared flow](flows/knowledge-maintenance.md)
+
+This kit provides [new project initialization](create-app.md), integration references for existing projects, copy-and-run offline code, and knowledge maintenance tools.
+
+## Integration code references
+
+For the overall flow and call timing see [How the mechanism works](mechanisms.md); the knowledge answering diagram there is an illustration of an App composing local Kit contracts.
+
+| Reference | What it offers an existing project |
+| --- | --- |
+| [Offline complete service answering](examples/offline-agent.md) | The same contract in TS/JS, from single node to tools, models, and process observation; no credentials needed |
+| [Basic model and tool calls](basic-usage.md) | Named calls, static tool catalogs, real authorization and execution, Provider stream boundaries |
+| [Core API](api/core.md) | Executor, model, tool, and cancellation/budget contracts |
+| [Support Context](api/support.md#context) | Assembling existing knowledge and profiles into model input |
+| [Knowledge API](api/knowledge-answering.md#knowledge) | Text parsing, section reading, and snapshots |
+| [Knowledge answering contract](api/knowledge-answering.md) | Connecting reading, generation, checks, and output through local Kit interfaces |
+
+The above are module call references; they do not create project directories, install dependencies, or start applications. Actual side effects are still carried by the existing project's ports.
+
+## Maintenance tools
+
+The following paths are relative to the installed package's `development/`. Scripts require Node 22+ and a resolvable Core build.
+
+| Entry | Input | Output and side effects |
+| --- | --- | --- |
+| `skills/agent-core-app/scripts/validate-knowledge.mjs PROJECT` | Existing project knowledge manifest, sources, and required read references | Check results; does not modify files |
+| `skills/agent-core-app/scripts/prepare-source.mjs PROJECT --source UTF8_FILE --id DOCUMENT_ID` | Existing project, explicitly provided source, and stable document id | Source awaiting review and a proposal; does not overwrite effective knowledge or configuration |
+| `skills/agent-core-app/scripts/plan.mjs PROJECT [--source UTF8_FILE]` | Existing project, optional source path | Agent development plan; see the Skill for specific behavior |
+| `skills/agent-core-app/scripts/create-app.mjs TARGET [--write]` | Empty target directory, name and purpose, optional real source | Read-only plan by default; explicitly creates a TypeScript/Node project and unpublished source candidates |
+| `skills/agent-core-app/scripts/create-app.mjs TARGET --check` | Generation receipt, current managed files, and the selected template | Read-only diff report; does not overwrite user modifications |
+
+Knowledge maintenance tools work from configuration explicitly provided by the project and do not scan or execute project code. For initialization and diff checks see [Create an App](create-app.md). For knowledge format, flow, and publication responsibility see the [Maintenance guide](maintenance.md). Failures exit with a non-zero code and an error report; invalid UTF-8, budget, or section errors cannot be bypassed by relaxing validation.
+
+The tools do not replace document review, resource authorization, database write-back, or publication, and they do not by default take on PDF/OCR, web crawling, or arbitrary material ingestion.

package/development/docs/flows/knowledge-maintenance.en.md

@@ -0,0 +1,38 @@
+# Knowledge Preparation, Maintenance, and Publication Flow
+
+This flow is referenced by the development-time knowledge preparation tools, the manual maintenance process, and the App's runtime knowledge growth implementation. It is not a prompt or state machine that Core executes automatically, and it grants no read or write permission. In an existing project, development-time verification and runtime loading reuse the same knowledge.config.json and compileApplicationKnowledge. When there is only an idea and no source, keep an empty file and an empty document list, and do not generate initial facts.
+
+## Shared Process
+
+| Stage | What must be obtained | Execution responsibility |
+| --- | --- | --- |
+| Obtain sources | Originals or references, source entity, time, usage/access scope | Organized by developers, or received by the App under authorization |
+| Form candidates | Locatable body text/fields; unknowns and conflicts retained | Human or App extractor; model output is only a candidate |
+| Assign identity | Stable document/section IDs, explicit revision and locale | The App's maintenance policy; not the model inventing new program handlers at will |
+| Check structure and references | Documents, sections, task reads, and budgets all usable | The same application compile entry and local validators such as Knowledge/Task |
+| Approve for publication | Human/business verification decided from sources and risk; authorization scope not widened | The App's own publication policy; the library does not build in generic approval |
+| Publish the version | Persistent records and the concurrent version commit succeed, then the new catalog becomes available | Controlled publication during development, or a transactional/CAS implementation at runtime |
+| Use and trace | Requests bind the catalog and source snapshot; corrections can find the old version | App handler and storage; Core maintains execution budget and cancellation |
+
+## Shared Rules
+
+1. Document IDs are unique within the catalog; section IDs are globally unique within a document. A title or file path does not replace identity.
+2. Changing body text or metadata that affects interpretation requires changing the revision. A snapshot does not replace source material, approval records, or a content hash.
+3. Validate references to tasks, readers, sections, outputs, and checks. A knowledge file passing syntax parsing does not mean the whole Agent integration is correct.
+4. Source material, user preferences, experience candidates, published knowledge, and tool receipts are handled separately; a user statement does not automatically become a public fact.
+5. Use the smallest complete read scope; when the budget is insufficient, report an error explicitly or read in batches, and do not silently truncate rules or necessary evidence.
+6. A failed check or publication does not overwrite the old version. Existing requests keep using their own old snapshot, and knowledge is not swapped out behind the scenes between generation and review.
+7. A data update does not automatically add execution permission. Dynamic knowledge references and program capability registration are two different flows.
+
+## Where the Shared Rules Are Enforced
+
+The example knowledge.config.json is an **App-owned configuration template**, not a new protocol in the library. It declares source files, read budgets, and read references that must be valid. compileApplicationKnowledge in development/skills/agent-core-app/scripts/lib/knowledge.mjs is used by both the validation tool and runtime loading; when the App copies or rewrites the template, it keeps the same entry:
+
+```text
+开发者／开发期脚本 → 源稿和配置 → 共享编译校验 → 发布应用资料
+运行期增长适配器 → 经审定的新版本 → 共享编译校验 → 持久提交／切换可用版本
+```
+
+The example implements only reading local source files, version computation, reference checks, and in-memory catalog construction. Runtime candidate extraction, review, persistence transactions, CAS, deletion, and permission filtering remain the App's responsibility; writing a flow in this file does not mean those capabilities are integrated.
+
+When integrating other formats, databases, or retrieval services, keep this flow and the same structure/reference checks, and replace only the input and commit adapters. There is no need to hard-code storage paths or one product's data tables into Core.

package/development/docs/getting-started.en.md

@@ -0,0 +1,71 @@
+# Installation and integration
+
+[Back to development handbook](README.md) · [API handbook](api/README.md)
+
+Install Agent Core as a dependency in your application, then integrate models, tools, and workflows as needed.
+
+When starting from an empty directory, you can first generate a TypeScript/Node project following [Create an App](create-app.md), then complete dependency and model integration along this page.
+
+## Installation
+
+Install from npm:
+
+```sh
+npm install @jangts/agent-core
+```
+
+Dependencies are installed by the package manager according to `package.json`. When using a local package provided by the maintainer, specify the tarball path:
+
+```sh
+npm install /artifacts/jangts-agent-core-0.1.0.tgz
+```
+
+Replace the path and version according to the actual delivery. Offline installation requires the maintainer to provide a complete local dependency source, and the package manager resolves all dependencies.
+
+The package provides ESM, CommonJS, and TypeScript declarations. Use Node.js 22.12.0 or later; the runtime must provide the APIs in use such as `fetch`, `AbortSignal`, and `ReadableStream`. Model credentials are managed by the application's server-side configuration.
+
+## Wire up the first call
+
+First provide a ChatProvider that the App has already configured, then pass the raw question; all other run settings have defaults:
+
+```ts
+import { Support, ModelRunner } from '@jangts/agent-core';
+
+const provider = new Support.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;
+```
+
+The above uses the application's existing environment configuration, and the service must be compatible with Chat Completions; baseUrl does not include /chat/completions. The Provider handles HTTP/SSE itself, so you do not need to implement stream separately. Run the [Offline complete example](examples/offline-agent.md) first without model credentials; it does not call a real model. Plain text calls need no Knowledge, tools, or workflows. Kits are imported from `@jangts/agent-core/kits/<name>` as needed; see the corresponding task documentation for specific compositions.
+
+| Provided by the App | Executed by existing interfaces |
+| --- | --- |
+| The Provider's real connection configuration and user input; signal/budget overrides as needed | ModelRunner checks budget, handles cancellation/timeout, and calls the model |
+| Centralized tool declarations, server-side identity, and business implementation | Core ToolRegistry executes registrations; optional Support reduces repeated wiring, and authorization constraints come from the actual declarations |
+| Continue/end conditions and business error exits | AgentCoreEngine executes according to registered flows |
+| Knowledge reading, visibility scope, sources and versions | Kits such as Knowledge process provided data under local contracts |
+
+Next, follow [Model and tool integration](basic-usage.md) to complete text calls, tool proposals, and real execution in order. ModelRunner.invoke is one complete model call; multi-step execution is explicitly orchestrated by the App with existing Core APIs. For parameters and errors see [Core](api/core.md), [Support](api/support.md), and [Kit](api/kits.md).
+
+## Knowledge and output integration
+
+- [Knowledge documents](knowledge.md): sections, versions, selection, and snapshots; parse/define process only in-memory data and create no storage.
+- [Knowledge answering contract](api/knowledge-answering.md): the local interfaces of Knowledge, Answering, and Presentation, connected by the App through reader, authorization, model, review, and output.
+- [Manual maintenance](maintenance.md) and [Agent-assisted development](agent-development.md): shared rules and scripts for maintaining existing code and knowledge.
+- [Operations](operations.md): Core output, Support observer, App logs, cancellation, and budget.
+
+Prepare knowledge faithfully when raw material exists; when there is only an idea, keep knowledge empty with open items, and do not write speculation or demo text as facts. Knowledge growth is carried by the existing App's authorization, storage, and update flows.
+
+## Lifecycle wiring
+
+Static declarations can be validated during the existing project's assembly stage; user materials, read evidence, consumed budget, and session state should have explicit request/session ownership. Do not store mutable current-request state in objects shared across users.
+
+Before integration, verify small-scope behavior that has no real side effects, then verify real models and business execution as needed. The call code in the documentation is not a standalone application template, and it does not automatically grant publication or operation permissions.
+
+## Debug with a mock model
+
+When there are no model credentials, use the [MockGPT Kit](api/mock.md) to configure fixed replies, input-dependent generators, tool proposals, and failures. Direct calls are imported from `@jangts/agent-core/mock`; when a standalone HTTP model service is needed, use createMockServer from `@jangts/agent-core/mock/node`. Point the model client at its local address, and the application's workflow, tool authorization, and budget contracts stay the same.

package/development/docs/knowledge.en.md

@@ -0,0 +1,89 @@
+# Knowledge documents, sections, and versions
+
+[Back to development handbook](README.md) · [Knowledge API](api/knowledge-answering.md#knowledge) · [Complete answering chain](api/knowledge-answering.md)
+
+## How the library learns your knowledge structure
+
+Core does not scan knowledge directories, infer a knowledge base from file names, or automatically generate sections from Markdown headings. The App explicitly executes the following chain:
+
+```text
+App reads controlled sources
+  → provides id, revision, locale, and body/structure
+  → Knowledge.parseKnowledgeDocument (only when text anchors are used)
+  → Knowledge.defineKnowledgeCatalog
+  → App checks the task's document/section references
+  → catalog.read with the reads allowed for this round
+  → passes the KnowledgeSnapshot as evidence to subsequent handlers
+```
+
+This structure is a local specification after adopting the Knowledge Kit, not a document format every Agent must store. The App can generate `KnowledgeDocument.parts` directly without Markdown parsing.
+
+## Development-time preparation tools and runtime assembly functions
+
+| Entry/asset | Purpose | What it does not do |
+| --- | --- | --- |
+| [Maintenance guide](maintenance.md) | Prepare knowledge in the project; organize faithfully when sources exist, keep empty when none | Knowledge must have real sources; ideas are not facts |
+| `Knowledge.parseKnowledgeDocument({id, revision, text, locale?})` | Parse paired section anchors into a document tree | Does not read files, compute revision, or complete all catalog validation |
+| `Knowledge.defineKnowledgeCatalog(documents, options?)` | Compile/freeze an in-memory document catalog, providing ids, sectionIds, assertSelection, read | Does not create databases, watch files, import uploads, or automatically learn or write back |
+| [Section marker notes](#text-section-anchors) | Local code fragment explaining paired anchors and nesting rules | Not initial knowledge and not loaded automatically |
+| [knowledge.mjs](../skills/agent-core-app/scripts/lib/knowledge.mjs) | App-side template shipped with the Skill for explicitly reading files, computing versions, and compiling catalogs | Not a built-in persistent initializer of the library |
+
+Minimal document JSON structure:
+
+```json
+{
+  "id": "service-guide",
+  "revision": "content-version-1",
+  "locale": "zh-CN",
+  "parts": [
+    "全局引言。",
+    { "id": "delivery", "parts": [
+      "本章节自身正文。",
+      { "id": "delivery.timing", "parts": ["时机说明。"] }
+    ] }
+  ]
+}
+```
+
+`parts` may mix raw text strings and subsections. Structured section IDs must be non-empty strings and **globally unique within the same document**, not merely unique among adjacent siblings. Document IDs are unique within the catalog; catalog compilation rejects duplicate sections and cycles. Do not run only the text parser and skip catalog compilation.
+
+## Text section anchors
+
+Sources use paired markers on their own lines, with no indentation:
+
+```md
+<!-- agent-section:delivery -->
+本章节自身正文。
+<!-- agent-section:delivery.timing -->
+子章节正文。
+<!-- /agent-section:delivery.timing -->
+<!-- /agent-section:delivery -->
+```
+
+The characters accepted in IDs by the text adapter are English letters, digits, `_`, `.`, `:`, and `-`. Markers must keep spaces as in the example and occupy their own line; opening and closing IDs must match and nest correctly. Markdown `#` headings are merely body text. The parser recognizes anchors from raw text and is not a full Markdown interpreter; do not put example anchors on their own lines inside code fences in sources, or they will also be recognized as real sections.
+
+Stable IDs represent content identity. Changing a title does not require changing the ID; when splitting/deleting sections, migrate task mappings and historical reference policies at the same time. Characters such as `.` are only part of the ID; parent-child relationships are determined by the actual nesting in `parts` and cannot be guessed from names.
+
+## Three ways to read
+
+| Request | Returned scope |
+| --- | --- |
+| `{documentId:'service-guide', selection:{mode:'document'}}` | The whole body text and all descendants, in source order |
+| `{documentId:'service-guide', selection:{mode:'self', sectionIds:['delivery']}}` | The selected section's own string body, excluding subsections |
+| `{documentId:'service-guide', selection:{mode:'subtree', sectionIds:['delivery']}}` | The selected section and all its descendants |
+
+Sections explicitly selected are joined by two newlines in the order of the request array; duplicate IDs are rejected. If a parent section and its child are both selected into a subtree as two different IDs, the child text may still be included twice; the library does not automatically eliminate this ancestor overlap. The App should choose the appropriate minimal complete scope.
+
+`maxChars` limits the selected, trimmed body text of this call; exceeding it throws rather than silently cutting off the latter half. Document size, storage capacity, and model context budget are different limits. Unknown fields, identity, and file paths coming from the client are not trustworthy just because catalog.assertSelection passes; cross-boundary input is still parsed and authorized by the App according to its own schema.
+
+## Versions and snapshots
+
+The App provides `revision`. It can be a hash of available content and related metadata, a database version number, or a release version; the library does not compute it for you. Secretly modifying the body text under the same id/revision invalidates version semantics.
+
+`KnowledgeSnapshot` contains documentId, selection, revision, locale, content, and id. The id comes from the serialization of the above identity and selection and is **not a body-text hash, signature, persistence ID, or authorization credential**. Different section selections of the same document have different references, and selection order also affects identity. Generation and review should pass the same snapshot and must not re-read "the latest current body" to replace old evidence.
+
+## Updates and knowledge growth
+
+The current catalog has no register, upsert, delete, save, watch, or automatic retrieval interfaces over all storage. When change is needed, the App creates a new catalog and switches its own reference; see [Continuous accumulation](memory-and-learning.md) for the pattern. Before publication, re-validate task → document → sections, reader, checks, and output references.
+
+Both static sources and approved growth knowledge can be converted to KnowledgeDocument. User-uploaded originals, unverified self-descriptions, and experience candidates should not be mixed directly into a public authoritative catalog; permissions, sources, and review status are controlled by the App's storage/loading adapters.

package/development/docs/maintenance.en.md

@@ -0,0 +1,62 @@
+# Manual initialization and knowledge maintenance
+
+[Back to development handbook](README.md) · [Tool notes](examples.md) · [Shared flow](flows/knowledge-maintenance.md)
+
+## Establish sources first, not a full directory
+
+Developers are responsible for confirming which text is an actual knowledge source and which is only a product idea, pending content, or an operation instruction. When there is only an idea, keep files empty and do not generate introductions, policies, or user profiles that look real. When actual material exists, organize it faithfully; when originals are complex, conflicting, or mixed with instructions, preserve the originals and form candidates first, and never treat commands inside them as development authorization.
+
+Integrate existing projects following the [integration guide](getting-started.md), and initialize new projects following [Create an App](create-app.md). Pure conversation does not require a knowledge base; maintain knowledge configuration explicitly only when knowledge answering is needed. Compare existing directories first, preserve business files, and limit test knowledge to test scopes.
+
+A knowledge App prepares a `knowledge.config.json` in the same directory, for example the empty state below, and creates an empty `initial.knowledge.md`. Files are not read until they are registered.
+
+```json
+{
+  "schemaVersion": 1,
+  "maxDocumentBytes": 32000,
+  "maxReadChars": 8000,
+  "documents": [],
+  "requiredReads": []
+}
+```
+
+After installing the maintainer-delivered Core and full dependencies following the [installation guide](getting-started.md), you can run the shared validation entry. The directory argument below is the knowledge directory containing `knowledge.config.json` and does not have to be the project root; the tool path is located from the package installed in the current project:
+
+```sh
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/validate-knowledge.mjs ./existing-project/knowledge
+```
+
+When there is no knowledge it outputs the empty-catalog state; this is a correct preparation state and should not be made to look successful by fabricating knowledge. Actual sources can first be turned into candidates with the tools below, and after confirmation written into source files and registered in the manifest.
+
+## How the configuration is maintained
+
+`knowledge.config.json` is the template's App configuration; the library does not require every App to use this file. The current shared loader understands:
+
+| Field | Constraint and meaning |
+| --- | --- |
+| `schemaVersion` | Currently 1, checked by the shared compiler |
+| `maxDocumentBytes` | Positive integer, byte limit per source file; not a model token limit |
+| `maxReadChars` | Positive integer, per-read character limit for Knowledge |
+| `documents` | May be empty; entries are `{id,file,locale?}`; currently only lowercase `*.knowledge.md` file names in the same directory are allowed, and model-supplied paths are not accepted |
+| `requiredReads` | `{documentId,selection}` actually depended on by tasks; all references are checked at compile time |
+
+Document IDs must be unique; see [Knowledge documents](knowledge.md) for section rules. Newly added files must be registered explicitly; being on disk does not automatically grant publication or read eligibility. Source and subsequent version traceability are carried by the maintainer's own change records; candidate tools do not replace complete publication records.
+
+## Adding and updating reuse the same validation
+
+```sh
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/prepare-source.mjs ./existing-project/knowledge --source ./revision.md --id initial-doc
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/validate-knowledge.mjs ./existing-project/knowledge
+```
+
+The first command only generates a candidate; the second checks the **currently effective configuration** and does not publish the candidate. The candidate contains the original file, document ID, suggested addition/replacement, source hash, revision, as well as the configuration hash at preparation time and existing document versions. Candidate validation also checks existing required section references; deleting a referenced section fails, and the task and configuration must be explicitly adjusted and the candidate prepared again—errors cannot be skipped automatically.
+
+The configuration hash comes from the raw bytes actually parsed this time, sharing a single configuration read with the candidate's budget and required-read validation, so it is not re-read after validation and marked against a different baseline. Each source file version comes from content read this time; this does not constitute an atomic multi-file filesystem snapshot.
+
+Publication is done by the maintainer: verify sources, body diffs, task references, and permissions → save the candidate to a controlled source file → add the new document to the manifest or update an existing file → use the same check entry → publish one complete version. Before publishing, compare the effective configuration and the revisions of replaced documents against the candidate baseline; if stale, redo the comparison. A single-file write is not a multi-file transaction; production systems should use their own versioned publication, transactions, or atomic switching.
+
+Direct editing follows the same flow. A failed validation keeps the published version; generation and review use the same snapshot; a failed update does not delete the original file. Manual and runtime growth can share `compileApplicationKnowledge`, replacing only the input and commit adapters.
+
+## What maintenance does not happen automatically
+
+The tools have no automatic approval, publication, file watching, indexing, scheduled learning, or database writes. User profiles and business experience are different application data; define their sources, updates, and deletions according to [Continuous accumulation](memory-and-learning.md), then decide whether to convert them into readable Knowledge documents.

package/development/docs/materials.en.md

@@ -0,0 +1,38 @@
+# User materials and data boundaries
+
+[Back to development handbook](README.md) · [Continuous accumulation](memory-and-learning.md)
+
+Receiving material, extracting body text, using it within a round, storing it in a personal profile, and publishing it as shared knowledge are different operations. Core does not automatically convert uploads into long-term memory, nor does it trust instructions in material just because the material contains section anchors.
+
+## Minimal processing chain
+
+```text
+Server confirms identity and material ownership
+  → App checks format/size, saves necessary source information
+  → Controlled parser extracts body text, records extraction failures or gaps
+  → Selects content according to this round's authorization
+  → Support context fragment marks it as user data and sets a budget
+  → Handler uses the material and binds output to actual evidence
+```
+
+Parsing and saving are provided by App adapters. The plain text example does not mean PDF, image OCR, audio transcription, web crawling, or archives are supported. When these formats are needed, register parsing capabilities and acceptable results explicitly; parsing failure must not be treated as empty content and then followed by a complete conclusion.
+
+| Field to be made explicit | Purpose |
+| --- | --- |
+| Material ID, owning user/tenant, access scope | The server establishes permissions and does not trust client-claimed owners |
+| Original reference, type, source time, content hash | Retrieve the original and determine versions; do not treat file names as stable identity |
+| Extraction version, body text, gaps, and parsing status | Distinguish originals from model/parser output |
+| Lifecycle, retention, and deletion method | Whether this round, the session, or persistent storage is decided by the product |
+| Review/publication status | Candidate material cannot automatically become shared authoritative knowledge |
+
+See [Material record](records.md#material-record) for a reference. It is an App-owned record sample with no corresponding Core persistence API.
+
+## Context and tools
+
+Use Support fragments to note the real source, `trust: 'user'`, and the corresponding lifecycle. The trust label is part of the assembly contract, not a sandbox; the App still needs to prevent material body text from being treated as higher-privilege instructions or executable code. Do not dynamically add one executable tool per uploaded file; usually keep a controlled `material.read` whose parameters reference IDs authorized for this round.
+
+When continuing use across rounds, pass only references available to the session and re-confirm permissions and lifecycle. When persistent storage is needed, enter the application's own candidate and publication flow. After deleting an original, also clean up extracted text, summaries, indexes, and references according to the App policy—do not delete only the UI list.
+
+## Delivery limits
+
+Do not output the full material text by default in errors, logs, or receipts. Partial reads, insufficient budget, and incomplete parsing should become explicit check results; retries cannot widen the visible scope. Source references, file download URLs, and cross-end presentation are chosen by the App; the Interaction Kit is optional, and front and back ends are not forced to use InteractionProtocol/CommandCatalog uniformly.