@gt-fe/eap-cli 0.2.17 → 0.2.19

package/dist/templates/agent-api-orchestration/README.md

@@ -1,326 +1,326 @@
-# Agent API 服务模板
-
-这个模板模拟一个真实的前端智能体页面后端：Node.js 进程内嵌 `@gt-fe/eap-sdk`，启动后直接提供 Agent HTTP API。前端只需要知道 Agent code、服务地址和 SSE 事件协议，就可以完成能力发现、会话管理、历史消息、同步调用和流式对话。
-
-SDK 仍然是执行核心，模板里的 HTTP 层只是宿主适配器。它不重新实现 Graph、Tool 路由或 Runtime 事件；流式接口原样转发 Runtime `SSEEvent`。整图超时：图上未写 `config.timeout` 时为 20 分钟。
-
-## 启动
-
-```bash
-npm install
-npm run dev
-```
-
-开发启动会先把当前项目物化到 `.eap/runtime`，然后启动 HTTP 服务。默认地址是 `http://127.0.0.1:3000`。启动日志会打印 Agent 能力描述地址：
-
-```text
-GET http://127.0.0.1:3000/api/v1/agents/my-agent
-```
-
-生产构建使用 `npm run build`。构建会通过 SDK 生成包含项目配置和锁文件的
-`dist/.eap/runtime`。正式宿主应从 `dist/embedded-agent.js` 调用
-`createEmbeddedAgent({ credentialProvider })`，显式注入短期凭证，再把 Agent 挂到自己的 HTTP
-服务；不要把 `npm start` 的演示入口直接当成生产凭证接入方案。
-
-模板里的 Express HTTP 层是可直接运行的服务骨架。它不实现登录、Bearer 鉴权、租户绑定或业务授权；这些职责由使用方在反向代理或自己的路由层集成。
-模板随附的 `eap.config.json` 将 `runtime.storage.profile` 设为 `dev`，由 Runtime 提供本地文件
-存储来演示会话和消息能力；状态位于 `.eap/`（生产入口位于 `dist/.eap/`）。模板不实现数据库。
-
-## 项目配置
-
-Portal 和 Foundation 地址只配置在 `eap.config.json`：
-
-```json
-{
-  "platform": {
-    "portalUrl": "https://developer-portal.example",
-    "foundationServiceUrl": "https://foundation.example"
-  }
-}
-```
-
-开发和生产运行都从 SDK 整理后的 Runtime Agent 目录读取该文件。生产构建不会再由模板脚本
-单独复制配置，因此模板不再设置 `EAP_PLATFORM_ENDPOINT` 或
-`FOUNDATION_SERVICE_URL`；`.env` 文件只放 Token 回退、模型密钥和 HTTP 服务配置。
-配置文件会随构建产物发布，请只写平台地址和其他非敏感配置。本地模型写在
-`runtime.llm.models.<模型名>`（`baseUrl` + `apiKey`），与另外四个执行模式模板相同。
-`apiKey` 使用 `${OPENAI_API_KEY}` 这类环境变量引用，不要写入明文密钥。不要只配顶层
-`runtime.llm.baseUrl`，否则可能落到 OpenAI 默认地址。
-
-## 前端接口
-
-所有接口都支持跨域（由 `EAP_HTTP_CORS_ORIGIN` 控制），JSON 请求使用 `Content-Type: application/json`。Agent code 来自 `agent.manifest.json` 的 `code` 字段。
-
-| 方法 | 路径 | 用途 |
-| --- | --- | --- |
-| `GET` | `/health` | 存活检查 |
-| `GET` | `/api/v1/agents/:agentCode` | Agent 名称、版本、模型、Tool/Skill、Graph 节点和可用能力 |
-| `POST` | `/api/v1/agents/:agentCode/sessions` | 创建会话，返回完整 Session |
-| `GET` | `/api/v1/agents/:agentCode/sessions` | 分页查询会话 |
-| `GET` | `/api/v1/agents/:agentCode/sessions/:sessionId` | 查询会话详情 |
-| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/archive` | 归档会话 |
-| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/restore` | 尝试恢复会话（当前 Runtime 返回 501） |
-| `GET` | `/api/v1/agents/:agentCode/sessions/:sessionId/messages` | 分页查询历史消息 |
-| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/messages` | 发送一条消息并等待完整回复 |
-| `POST` | `/api/v1/agents/:agentCode/invoke` | 无路径会话的同步调用 |
-| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/stream` | 在会话中流式对话 |
-| `POST` | `/api/v1/agents/:agentCode/stream` | 无路径会话的流式调用 |
-
-`restore` 接口保留在 SDK 能力边界中，但当前 Runtime 不支持恢复，会返回 `501 not_supported`，能力描述里的 `sessions.restore` 也会标为 `false`。
-
-### 能力发现
-
-前端页面加载时先请求能力描述，不必把模型或 Graph 配置硬编码到页面：
-
-```ts
-const capability = await fetch(
-  'http://127.0.0.1:3000/api/v1/agents/my-agent',
-).then((response) => response.json());
-
-console.log(capability.agent.name, capability.capabilities.stream);
-```
-
-### 创建会话并发送消息
-
-```ts
-const session = await fetch(
-  'http://127.0.0.1:3000/api/v1/agents/my-agent/sessions',
-  {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ title: '产品咨询' }),
-  },
-).then((response) => response.json());
-
-const result = await fetch(
-  `http://127.0.0.1:3000/api/v1/agents/my-agent/sessions/${session.id}/messages`,
-  {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ content: '帮我总结本周的产品反馈' }),
-  },
-).then((response) => response.json());
-
-console.log(result.data.output, result.data.tokenUsage);
-```
-
-同步调用返回 Runtime 的完整响应：`{ code, data, traceId }`。`data` 包含 `taskId`、`sessionId`、`output`、`status`、`tokenUsage` 和 `duration`。
-
-### 流式对话
-
-流式端点返回标准 `text/event-stream`。每一帧的 `event` 是 Runtime 事件类型，`data` 是事件负载加上 `correlationId`、`taskId` 和 `timestamp`：
-
-```ts
-const response = await fetch(
-  `http://127.0.0.1:3000/api/v1/agents/my-agent/sessions/${session.id}/stream`,
-  {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ content: '继续给出三个可执行建议' }),
-  },
-);
-
-const reader = response.body!.getReader();
-const decoder = new TextDecoder();
-let buffer = '';
-while (true) {
-  const { done, value } = await reader.read();
-  if (done) break;
-  buffer += decoder.decode(value, { stream: true });
-  const frames = buffer.split('\n\n');
-  buffer = frames.pop() ?? '';
-  for (const frame of frames) {
-    const dataLine = frame.split('\n').find((line) => line.startsWith('data:'));
-    if (dataLine) console.log(JSON.parse(dataLine.slice(5)));
-  }
-}
-```
-
-常见事件包括 `task.started`、`response.chunk`、`response.final`、`tool.called`、`tool.result`、`stats.token_usage` 和 `task.completed`。前端应以 `response.final` 或 `task.completed` 作为本轮结束信号，并处理 `task.error` 与 `error`。
-
-## SDK Token 与用户信息示例
-
-`EAP_SDK_TOKEN` 只用于开发入口的演示回退，构建产物的生产运行不读取它。模板通过
-`AgentCredentialProvider` 把凭证交给 Runtime，不请求凭证 sidecar，也不负责刷新 Token。
-
-生产宿主显式注入 Provider，显式注入优先于 `EAP_SDK_TOKEN`：
-
-```ts
-import { createEmbeddedAgent, createAgentApp } from './dist/embedded-agent.js';
-
-const agent = await createEmbeddedAgent({
-  credentialProvider: hostCredentialProvider,
-});
-```
-
-开发模式未传 `credentialProvider` 时，`createEmbeddedAgent()` 才读取 `EAP_SDK_TOKEN`；生产模式
-缺少显式 Provider 会直接失败。宿主可以把返回的 Agent 传给 `createAgentApp(agent)` 或自己的
-HTTP 路由。
-
-如果宿主已经拿到前端用户 Token，需要查询用户信息时，可以调用独立的 `src/platform-user.ts` 示例（构建后为 `dist/platform-user.js`）：
-
-```ts
-import { resolveTokenUser } from './dist/platform-user.js';
-
-const user = await resolveTokenUser(externalToken);
-console.log({ userId: user.userId, roles: user.roles, permissions: user.permissions });
-```
-
-`resolveTokenUser()` 内部调用 `createPlatformClient()` 和 `client.resolveTokenUser(token)`，只返回 SDK 的 `PlatformIdentity`。宿主仍需自行处理 401、租户绑定、会话归属和业务权限；模板 HTTP 接口不会自动读取 `Authorization` 请求头。
-
-## 资源管理服务模块
-
-模板提供 `src/http/services/resource-service.ts`，并从 `src/index.ts` 导出
-`resourceService`。它是宿主对 SDK `AgentResourceManager` 的流程封装，包含：
-
-- `install()`：安装指定版本，写入 desired 状态。
-- `update()`：调用 manager 的 `refresh()`，检查并更新远程资源元数据或缓存；要切换到新版本，使用 `install()` 传入新的 `ref`。
-- `enable()` / `disable()`：修改资源 desired 状态。
-- `apply()`：按 desired 集物化资源；可以传 `reload: false` 只物化不切换 Runtime。
-- `reload()`：显式重新创建 Runtime。
-- `applyAndReload()`：先以 `reload: false` 应用资源，再根据 `requiresReload` 显式重载 Agent。
-
-模板不实现资源状态存储。使用该模块前，宿主必须实现或接入自己的
-`AgentResourceManager`，并在 `createEmbeddedAgent()` 中注入：
-
-```ts
-import { createEmbeddedAgent, createAgentResourceService } from './dist/embedded-agent.js';
-import type { AgentResourceManager } from '@gt-fe/eap-sdk';
-
-const resourceManager: AgentResourceManager = createHostResourceManager({
-  client,
-  runtimeRoot,
-  store: resourceStore,
-});
-
-const agent = await createEmbeddedAgent({
-  credentialProvider,
-  resourceManager,
-});
-const resourceService = createAgentResourceService(agent);
-```
-
-`createHostResourceManager()`、`resourceStore` 是宿主实现，不是模板或 SDK 导出的函数。模板只
-演示 SDK manager 接口和调用顺序，不负责状态存储实现。未注入 manager 时，调用资源
-方法会返回 `resource_manager_unavailable`（501）。
-
-典型的更新和启用流程：
-
-```ts
-import { resourceService } from './src/index.js';
-
-const ref = { kind: 'tool', code: 'search-tool', version: '1.2.0' } as const;
-
-await resourceService.install({ ref, enabled: false }); // 安装但不启用
-await resourceService.update({ ref });                  // 检查远程资源
-await resourceService.enable(ref);                      // 设置 desired=enabled
-
-const applied = await resourceService.applyAndReload([ref]);
-if (applied.reload?.status === 'failed') {
-  throw new Error(applied.reload.error?.message ?? 'Agent reload failed');
-}
-
-await resourceService.disable(ref);                      // 设置 desired=disabled
-await resourceService.applyAndReload([ref]);
-```
-
-`enable()`/`disable()` 只更新 desired 状态；`applyAndReload()` 完成物化并在必要时调用
-`agent.reload()`，`effectiveState` 才表示资源已经进入当前 Runtime。生产服务应在请求排空或维护
-窗口中执行重载。构建期固定资源版本时，仍应在 Agent 源项目中使用 `eap install` 或
-`installAgentResource()`，再重新生成 standalone Runtime；不要在每个用户请求中修改
-`eap.lock.yaml`。
-
-## RAG 检索模块
-
-`graph.json` 在作答节点之前放了一个 `type: "rag"` 节点，路径是 `__start__ → rag → respond → __end__`。这是节点形态示例：未配置 `retrievalSources` 时检索面为空，rag 节点结束后仍由 `respond` 作答。要做多源检索，按下面补 `retrievalSources`（以及会话勾选 `ragSources`）。
-
-### 节点配置
-
-rag 节点的 config 字段均可省略，各有缺省：
-
-| 字段 | 默认 | 说明 |
-| --- | --- | --- |
-| `model` | `default` | 决策/降噪判分/空结果重写共用的主力模型 |
-| `totalK` | `10` | 融合降噪后最终进上下文的总条数 |
-| `maxIterations` | `5` | 本节点检索轮次上限（同轮并发 tool_call 只计 1）。到上限该节点结束，后续图节点继续 |
-| `quota` | — | 融合主辅配额：源桶 → 占比（合计 1） |
-| `nearDupThreshold` | `0.8` | 近重去重阈值（字符 3-gram Jaccard） |
-| `retrievalSources.sources` | — | 检索面数据源目录（会话勾选 `ragSources` 在此基础上过滤） |
-| `toolSources` | — | 工具名 → 融合源桶映射（缺省全归 `kb` 桶） |
-
-`retrievalSources.sources` 里，工具型外部源的 `type` 是开放集合（kb/dw/api/maxkb/milvus/…），约定工具名为 `${type}_search`；`id` 是会话勾选键，`source` 是工具内资源定位，`ref` 在注册工具名与约定不符时显式指定：
-
-```json
-{
-  "id": "rag",
-  "type": "rag",
-  "config": {
-    "retrievalSources": {
-      "sources": [
-        { "type": "maxkb", "id": "运行分析", "source": "【正式】运营分析报告智能体v1.0" },
-        { "type": "dw", "id": "城市目标销售月报", "source": "sa_region_city_monthly_target_sales" },
-        { "type": "local-file", "id": "共享资料", "source": "./docs" }
-      ]
-    },
-    "quota": { "kb": 0.7, "dw": 0.2, "local": 0.1 },
-    "toolSources": { "dw_search": "dw", "maxkb_search": "kb" }
-  }
-}
-```
-
-模板默认只声明一个 `local-file` 源（`source` 指向 `./docs`，请改成你自己的目录）；工具型源需要先把对应工具注册进 `agent.manifest.json` 的 `toolRefs`。
-
-### 请求级检索范围
-
-每次对话可通过请求体带上 `ragSources`（会话勾选的数据源 id）和 `ragScope`（本地目录范围），覆盖图里的默认检索面：
-
-```ts
-const result = await fetch(
-  `http://127.0.0.1:3000/api/v1/agents/my-agent/sessions/${session.id}/messages`,
-  {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      content: '帮我总结本周的产品反馈',
-      ragSources: ['运行分析', '城市目标销售月报'],
-      ragScope: { dirPaths: ['D:/workpalce/共享资料'] },
-    }),
-  },
-).then((response) => response.json());
-```
-
-- `ragSources`：`undefined` = 目录全部启用（缺省）；`[]` = 全不勾（外部源全拒，声明过 local-file 未勾则本地关闭）。
-- `ragScope`：只作用本地源；`dirPaths` 按目录整棵圈定（含子目录），`fileIds` 与 `dirPaths` 取并集，`fileIds: []` 显式关本地。
-
-## 环境变量
-
-| 变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `EAP_HTTP_HOST` | `127.0.0.1` | HTTP 监听地址 |
-| `EAP_HTTP_PORT` | `3000` | HTTP 监听端口 |
-| `EAP_HTTP_CORS_ORIGIN` | `*` | 允许的前端 Origin |
-| `EAP_HTTP_MAX_BODY_BYTES` | `1048576` | JSON 请求体上限 |
-| `EAP_SDK_TOKEN` | — | 仅开发/演示用 Token 回退；生产必须显式注入 `credentialProvider` |
-
-生产部署仍应由反向代理负责 TLS、鉴权、限流、访问日志脱敏和更严格的 Origin 白名单。模板不替宿主实现租户绑定、审计存储或业务级授权策略。
-
-如果需要把模板路由嵌入已有 Express 应用，请复用 `src/http/routes` 中的路由工厂，在宿主完成鉴权后再挂载；`startAgentHttpServer()` 适合直接启动独立服务。
-
-## 作为模块嵌入
-
-需要自行接入 Fastify、Express 或其他 HTTP 框架时，可以只使用 SDK 入口：
-
-```ts
-import { agent, invoke, stream, startAgentHttpServer } from './src/index.js';
-
-await invoke('你好');
-for await (const event of stream('给我一句摘要')) console.log(event);
-
-// 或把模板适配器挂到一个独立端口，作为最小服务实现。
-const service = await startAgentHttpServer(agent, { port: 3001 });
-```
-
-生产宿主要显式注入凭证时，使用上面的 `createEmbeddedAgent()` 工厂创建 Agent，再把实例传给
-`createAgentApp()` 或 `startAgentHttpServer()`；不要把生产 Token 写入项目文件。
-
-会话和消息函数也从 `src/index.ts` 导出，适合在宿主路由中按自己的鉴权和审计规范重新映射；资源安装、启用和 Runtime 切换使用上面的 `resourceService`，图配置更新仍由宿主直接使用 SDK 管理。
+# Agent API 服务模板
+
+这个模板模拟一个真实的前端智能体页面后端：Node.js 进程内嵌 `@gt-fe/eap-sdk`，启动后直接提供 Agent HTTP API。前端只需要知道 Agent code、服务地址和 SSE 事件协议，就可以完成能力发现、会话管理、历史消息、同步调用和流式对话。
+
+SDK 仍然是执行核心，模板里的 HTTP 层只是宿主适配器。它不重新实现 Graph、Tool 路由或 Runtime 事件；流式接口原样转发 Runtime `SSEEvent`。整图超时：图上未写 `config.timeout` 时为 20 分钟。
+
+## 启动
+
+```bash
+npm install
+npm run dev
+```
+
+开发启动会先把当前项目物化到 `.eap/runtime`，然后启动 HTTP 服务。默认地址是 `http://127.0.0.1:3000`。启动日志会打印 Agent 能力描述地址：
+
+```text
+GET http://127.0.0.1:3000/api/v1/agents/my-agent
+```
+
+生产构建使用 `npm run build`。构建会通过 SDK 生成包含项目配置和锁文件的
+`dist/.eap/runtime`。正式宿主应从 `dist/embedded-agent.js` 调用
+`createEmbeddedAgent({ credentialProvider })`，显式注入短期凭证，再把 Agent 挂到自己的 HTTP
+服务；不要把 `npm start` 的演示入口直接当成生产凭证接入方案。
+
+模板里的 Express HTTP 层是可直接运行的服务骨架。它不实现登录、Bearer 鉴权、租户绑定或业务授权；这些职责由使用方在反向代理或自己的路由层集成。
+模板随附的 `eap.config.json` 将 `runtime.storage.profile` 设为 `dev`，由 Runtime 提供本地文件
+存储来演示会话和消息能力；状态位于 `.eap/`（生产入口位于 `dist/.eap/`）。模板不实现数据库。
+
+## 项目配置
+
+Portal 和 Foundation 地址只配置在 `eap.config.json`：
+
+```json
+{
+  "platform": {
+    "portalUrl": "https://developer-portal.example",
+    "foundationServiceUrl": "https://foundation.example"
+  }
+}
+```
+
+开发和生产运行都从 SDK 整理后的 Runtime Agent 目录读取该文件。生产构建不会再由模板脚本
+单独复制配置，因此模板不再设置 `EAP_PLATFORM_ENDPOINT` 或
+`FOUNDATION_SERVICE_URL`；`.env` 文件只放 Token 回退、模型密钥和 HTTP 服务配置。
+配置文件会随构建产物发布，请只写平台地址和其他非敏感配置。本地模型写在
+`runtime.llm.models.<模型名>`（`baseUrl` + `apiKey`），与另外四个执行模式模板相同。
+`apiKey` 使用 `${OPENAI_API_KEY}` 这类环境变量引用，不要写入明文密钥。不要只配顶层
+`runtime.llm.baseUrl`，否则可能落到 OpenAI 默认地址。
+
+## 前端接口
+
+所有接口都支持跨域（由 `EAP_HTTP_CORS_ORIGIN` 控制），JSON 请求使用 `Content-Type: application/json`。Agent code 来自 `agent.manifest.json` 的 `code` 字段。
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `GET` | `/health` | 存活检查 |
+| `GET` | `/api/v1/agents/:agentCode` | Agent 名称、版本、模型、Tool/Skill、Graph 节点和可用能力 |
+| `POST` | `/api/v1/agents/:agentCode/sessions` | 创建会话，返回完整 Session |
+| `GET` | `/api/v1/agents/:agentCode/sessions` | 分页查询会话 |
+| `GET` | `/api/v1/agents/:agentCode/sessions/:sessionId` | 查询会话详情 |
+| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/archive` | 归档会话 |
+| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/restore` | 尝试恢复会话（当前 Runtime 返回 501） |
+| `GET` | `/api/v1/agents/:agentCode/sessions/:sessionId/messages` | 分页查询历史消息 |
+| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/messages` | 发送一条消息并等待完整回复 |
+| `POST` | `/api/v1/agents/:agentCode/invoke` | 无路径会话的同步调用 |
+| `POST` | `/api/v1/agents/:agentCode/sessions/:sessionId/stream` | 在会话中流式对话 |
+| `POST` | `/api/v1/agents/:agentCode/stream` | 无路径会话的流式调用 |
+
+`restore` 接口保留在 SDK 能力边界中，但当前 Runtime 不支持恢复，会返回 `501 not_supported`，能力描述里的 `sessions.restore` 也会标为 `false`。
+
+### 能力发现
+
+前端页面加载时先请求能力描述，不必把模型或 Graph 配置硬编码到页面：
+
+```ts
+const capability = await fetch(
+  'http://127.0.0.1:3000/api/v1/agents/my-agent',
+).then((response) => response.json());
+
+console.log(capability.agent.name, capability.capabilities.stream);
+```
+
+### 创建会话并发送消息
+
+```ts
+const session = await fetch(
+  'http://127.0.0.1:3000/api/v1/agents/my-agent/sessions',
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title: '产品咨询' }),
+  },
+).then((response) => response.json());
+
+const result = await fetch(
+  `http://127.0.0.1:3000/api/v1/agents/my-agent/sessions/${session.id}/messages`,
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content: '帮我总结本周的产品反馈' }),
+  },
+).then((response) => response.json());
+
+console.log(result.data.output, result.data.tokenUsage);
+```
+
+同步调用返回 Runtime 的完整响应：`{ code, data, traceId }`。`data` 包含 `taskId`、`sessionId`、`output`、`status`、`tokenUsage` 和 `duration`。
+
+### 流式对话
+
+流式端点返回标准 `text/event-stream`。每一帧的 `event` 是 Runtime 事件类型，`data` 是事件负载加上 `correlationId`、`taskId` 和 `timestamp`：
+
+```ts
+const response = await fetch(
+  `http://127.0.0.1:3000/api/v1/agents/my-agent/sessions/${session.id}/stream`,
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content: '继续给出三个可执行建议' }),
+  },
+);
+
+const reader = response.body!.getReader();
+const decoder = new TextDecoder();
+let buffer = '';
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  buffer += decoder.decode(value, { stream: true });
+  const frames = buffer.split('\n\n');
+  buffer = frames.pop() ?? '';
+  for (const frame of frames) {
+    const dataLine = frame.split('\n').find((line) => line.startsWith('data:'));
+    if (dataLine) console.log(JSON.parse(dataLine.slice(5)));
+  }
+}
+```
+
+常见事件包括 `task.started`、`response.chunk`、`response.final`、`tool.called`、`tool.result`、`stats.token_usage` 和 `task.completed`。前端应以 `response.final` 或 `task.completed` 作为本轮结束信号，并处理 `task.error` 与 `error`。
+
+## SDK Token 与用户信息示例
+
+`EAP_SDK_TOKEN` 只用于开发入口的演示回退，构建产物的生产运行不读取它。模板通过
+`AgentCredentialProvider` 把凭证交给 Runtime，不请求凭证 sidecar，也不负责刷新 Token。
+
+生产宿主显式注入 Provider，显式注入优先于 `EAP_SDK_TOKEN`：
+
+```ts
+import { createEmbeddedAgent, createAgentApp } from './dist/embedded-agent.js';
+
+const agent = await createEmbeddedAgent({
+  credentialProvider: hostCredentialProvider,
+});
+```
+
+开发模式未传 `credentialProvider` 时，`createEmbeddedAgent()` 才读取 `EAP_SDK_TOKEN`；生产模式
+缺少显式 Provider 会直接失败。宿主可以把返回的 Agent 传给 `createAgentApp(agent)` 或自己的
+HTTP 路由。
+
+如果宿主已经拿到前端用户 Token，需要查询用户信息时，可以调用独立的 `src/platform-user.ts` 示例（构建后为 `dist/platform-user.js`）：
+
+```ts
+import { resolveTokenUser } from './dist/platform-user.js';
+
+const user = await resolveTokenUser(externalToken);
+console.log({ userId: user.userId, roles: user.roles, permissions: user.permissions });
+```
+
+`resolveTokenUser()` 内部调用 `createPlatformClient()` 和 `client.resolveTokenUser(token)`，只返回 SDK 的 `PlatformIdentity`。宿主仍需自行处理 401、租户绑定、会话归属和业务权限；模板 HTTP 接口不会自动读取 `Authorization` 请求头。
+
+## 资源管理服务模块
+
+模板提供 `src/http/services/resource-service.ts`，并从 `src/index.ts` 导出
+`resourceService`。它是宿主对 SDK `AgentResourceManager` 的流程封装，包含：
+
+- `install()`：安装指定版本，写入 desired 状态。
+- `update()`：调用 manager 的 `refresh()`，检查并更新远程资源元数据或缓存；要切换到新版本，使用 `install()` 传入新的 `ref`。
+- `enable()` / `disable()`：修改资源 desired 状态。
+- `apply()`：按 desired 集物化资源；可以传 `reload: false` 只物化不切换 Runtime。
+- `reload()`：显式重新创建 Runtime。
+- `applyAndReload()`：先以 `reload: false` 应用资源，再根据 `requiresReload` 显式重载 Agent。
+
+模板不实现资源状态存储。使用该模块前，宿主必须实现或接入自己的
+`AgentResourceManager`，并在 `createEmbeddedAgent()` 中注入：
+
+```ts
+import { createEmbeddedAgent, createAgentResourceService } from './dist/embedded-agent.js';
+import type { AgentResourceManager } from '@gt-fe/eap-sdk';
+
+const resourceManager: AgentResourceManager = createHostResourceManager({
+  client,
+  runtimeRoot,
+  store: resourceStore,
+});
+
+const agent = await createEmbeddedAgent({
+  credentialProvider,
+  resourceManager,
+});
+const resourceService = createAgentResourceService(agent);
+```
+
+`createHostResourceManager()`、`resourceStore` 是宿主实现，不是模板或 SDK 导出的函数。模板只
+演示 SDK manager 接口和调用顺序，不负责状态存储实现。未注入 manager 时，调用资源
+方法会返回 `resource_manager_unavailable`（501）。
+
+典型的更新和启用流程：
+
+```ts
+import { resourceService } from './src/index.js';
+
+const ref = { kind: 'tool', code: 'search-tool', version: '1.2.0' } as const;
+
+await resourceService.install({ ref, enabled: false }); // 安装但不启用
+await resourceService.update({ ref });                  // 检查远程资源
+await resourceService.enable(ref);                      // 设置 desired=enabled
+
+const applied = await resourceService.applyAndReload([ref]);
+if (applied.reload?.status === 'failed') {
+  throw new Error(applied.reload.error?.message ?? 'Agent reload failed');
+}
+
+await resourceService.disable(ref);                      // 设置 desired=disabled
+await resourceService.applyAndReload([ref]);
+```
+
+`enable()`/`disable()` 只更新 desired 状态；`applyAndReload()` 完成物化并在必要时调用
+`agent.reload()`，`effectiveState` 才表示资源已经进入当前 Runtime。生产服务应在请求排空或维护
+窗口中执行重载。构建期固定资源版本时，仍应在 Agent 源项目中使用 `eap install` 或
+`installAgentResource()`，再重新生成 standalone Runtime；不要在每个用户请求中修改
+`eap.lock.yaml`。
+
+## RAG 检索模块
+
+`graph.json` 在作答节点之前放了一个 `type: "rag"` 节点，路径是 `__start__ → rag → respond → __end__`。这是节点形态示例：未配置 `retrievalSources` 时检索面为空，rag 节点结束后仍由 `respond` 作答。要做多源检索，按下面补 `retrievalSources`（以及会话勾选 `ragSources`）。
+
+### 节点配置
+
+rag 节点的 config 字段均可省略，各有缺省：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `model` | `default` | 决策/降噪判分/空结果重写共用的主力模型 |
+| `totalK` | `10` | 融合降噪后最终进上下文的总条数 |
+| `maxIterations` | `5` | 本节点检索轮次上限（同轮并发 tool_call 只计 1）。到上限该节点结束，后续图节点继续 |
+| `quota` | — | 融合主辅配额：源桶 → 占比（合计 1） |
+| `nearDupThreshold` | `0.8` | 近重去重阈值（字符 3-gram Jaccard） |
+| `retrievalSources.sources` | — | 检索面数据源目录（会话勾选 `ragSources` 在此基础上过滤） |
+| `toolSources` | — | 工具名 → 融合源桶映射（缺省全归 `kb` 桶） |
+
+`retrievalSources.sources` 里，工具型外部源的 `type` 是开放集合（kb/dw/api/maxkb/milvus/…），约定工具名为 `${type}_search`；`id` 是会话勾选键，`source` 是工具内资源定位，`ref` 在注册工具名与约定不符时显式指定：
+
+```json
+{
+  "id": "rag",
+  "type": "rag",
+  "config": {
+    "retrievalSources": {
+      "sources": [
+        { "type": "maxkb", "id": "运行分析", "source": "【正式】运营分析报告智能体v1.0" },
+        { "type": "dw", "id": "城市目标销售月报", "source": "sa_region_city_monthly_target_sales" },
+        { "type": "local-file", "id": "共享资料", "source": "./docs" }
+      ]
+    },
+    "quota": { "kb": 0.7, "dw": 0.2, "local": 0.1 },
+    "toolSources": { "dw_search": "dw", "maxkb_search": "kb" }
+  }
+}
+```
+
+模板默认只声明一个 `local-file` 源（`source` 指向 `./docs`，请改成你自己的目录）；工具型源需要先把对应工具注册进 `agent.manifest.json` 的 `toolRefs`。
+
+### 请求级检索范围
+
+每次对话可通过请求体带上 `ragSources`（会话勾选的数据源 id）和 `ragScope`（本地目录范围），覆盖图里的默认检索面：
+
+```ts
+const result = await fetch(
+  `http://127.0.0.1:3000/api/v1/agents/my-agent/sessions/${session.id}/messages`,
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      content: '帮我总结本周的产品反馈',
+      ragSources: ['运行分析', '城市目标销售月报'],
+      ragScope: { dirPaths: ['D:/workpalce/共享资料'] },
+    }),
+  },
+).then((response) => response.json());
+```
+
+- `ragSources`：`undefined` = 目录全部启用（缺省）；`[]` = 全不勾（外部源全拒，声明过 local-file 未勾则本地关闭）。
+- `ragScope`：只作用本地源；`dirPaths` 按目录整棵圈定（含子目录），`fileIds` 与 `dirPaths` 取并集，`fileIds: []` 显式关本地。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `EAP_HTTP_HOST` | `127.0.0.1` | HTTP 监听地址 |
+| `EAP_HTTP_PORT` | `3000` | HTTP 监听端口 |
+| `EAP_HTTP_CORS_ORIGIN` | `*` | 允许的前端 Origin |
+| `EAP_HTTP_MAX_BODY_BYTES` | `1048576` | JSON 请求体上限 |
+| `EAP_SDK_TOKEN` | — | 仅开发/演示用 Token 回退；生产必须显式注入 `credentialProvider` |
+
+生产部署仍应由反向代理负责 TLS、鉴权、限流、访问日志脱敏和更严格的 Origin 白名单。模板不替宿主实现租户绑定、审计存储或业务级授权策略。
+
+如果需要把模板路由嵌入已有 Express 应用，请复用 `src/http/routes` 中的路由工厂，在宿主完成鉴权后再挂载；`startAgentHttpServer()` 适合直接启动独立服务。
+
+## 作为模块嵌入
+
+需要自行接入 Fastify、Express 或其他 HTTP 框架时，可以只使用 SDK 入口：
+
+```ts
+import { agent, invoke, stream, startAgentHttpServer } from './src/index.js';
+
+await invoke('你好');
+for await (const event of stream('给我一句摘要')) console.log(event);
+
+// 或把模板适配器挂到一个独立端口，作为最小服务实现。
+const service = await startAgentHttpServer(agent, { port: 3001 });
+```
+
+生产宿主要显式注入凭证时，使用上面的 `createEmbeddedAgent()` 工厂创建 Agent，再把实例传给
+`createAgentApp()` 或 `startAgentHttpServer()`；不要把生产 Token 写入项目文件。
+
+会话和消息函数也从 `src/index.ts` 导出，适合在宿主路由中按自己的鉴权和审计规范重新映射；资源安装、启用和 Runtime 切换使用上面的 `resourceService`，图配置更新仍由宿主直接使用 SDK 管理。