@gt-fe/eap-sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,370 +1,378 @@
-# @gt-fe/eap-sdk
-
-`@gt-fe/eap-sdk` 是 EAP 单 Agent 项目的开发期 SDK，负责项目发现与校验、用户会话、平台 API、Tool/Skill 依赖安装、Runtime 目录物化、本地 Agent Service 以及确定性打包。
-
-Agent 的实际执行仍由 `@gt-fe/eap-runtime` 负责。SDK 不重新实现 Graph 编译、节点执行、Tool 路由或 Runtime 事件协议。
-
-## 安装
-
-```bash
-npm install @gt-fe/eap-sdk
-```
-
-本包为纯 ESM：
-
-```ts
-import { createAgentService } from '@gt-fe/eap-sdk';
-```
-
-## 项目模型
-
-一个项目只开发一个 Agent，开发者维护的源文件位于项目根目录：
-
-```text
-<project>/
-├── agent.manifest.json
-├── graph.json
-├── eap.config.json
-├── eap.lock.yaml
-├── tools/<code>/...
-├── skills/<code>/...
-└── .eap/
-    ├── remote/                         # Registry 资源缓存
-    ├── runtime/                        # 开发态 EAP_PREINSTALL_ROOT
-    │   └── agents/<agentCode>/<version>/preinstall|users/
-    ├── sessions/                       # 可选的本地会话数据
-    ├── package-staging/                # 打包临时目录
-    └── package/                        # 默认包输出目录
-```
-
-`agent.manifest.json`、`graph.json`、`eap.config.json`、`eap.lock.yaml` 以及本地 `tools/`、`skills/` 是项目输入；`.eap/` 是 SDK 生成的可删除状态。
-
-项目 `eap.config.json.version` 必须严格等于当前安装的 `@gt-fe/eap-sdk` package version；字段级配置和部署交付说明见 [dev-tools 文档入口](../../docs/README.md)。
-
-`findAgentRoot()` 和 `resolveAgentProject()` 只发现源项目，不使用 `EAP_PREINSTALL_ROOT`。选择器只支持 `root` 和 `startDir`，不存在 Agent code、版本或目录歧义选择。
-
-```ts
-import {
-  resolveAgentProject,
-  validateAgentProject,
-  type AgentProjectSelector,
-} from '@gt-fe/eap-sdk';
-
-const selector: AgentProjectSelector = { root: process.cwd() };
-const project = resolveAgentProject(selector);
-const validation = validateAgentProject(project.root);
-
-if (!validation.valid) {
-  console.error(validation.issues);
-}
-```
-
-## 核心能力
-
-| 能力 | 主要 API | 说明 |
-|---|---|---|
-| 项目发现 | `findAgentRoot()`、`resolveAgentProject()` | 查找根级单 Agent 项目 |
-| 项目校验 | `validateAgentProject()`、`validateGraph()` | 校验 Manifest、Graph、`eap.lock.yaml` 和资源路径 |
-| 用户会话 | `getCurrentUserSession()`、`saveCurrentUserSession()` | 管理当前登录用户和平台 Token；本地可用 `EAP_CHAT_USER` / `EAP_DEBUG_USER` |
-| 平台 API | `createPlatformClient()` | 访问 Portal、Foundation 和平台认证 |
-| 依赖安装 | `installAgentResource()`、`installAgentDependencies()` | 下载或恢复 Tool/Skill ZIP 制品，并维护 `eap.lock.yaml` |
-| Runtime 物化 | `prepareAgentRuntime()` | 生成 Runtime 可直接读取的预装目录 |
-| 本地服务 | `createAgentService()` | 物化后创建 Runtime-backed Agent Service |
-| Standalone 服务 | `packageStandaloneAgentProject()`、`createEmbeddedAgentService()` | 将同一套物化 Runtime 输出到 `dist/runtime`，启动时不读取源项目 |
-| 打包与验包 | `packageAgentProject()`、`readAgentPackage()` | 生成并校验单 Agent Runtime 部署包 |
-| Schema | `AgentManifestSchema`、`GraphSchema`、`ToolManifestSchema` 等 | SDK 所有项目文件的 Zod Schema |
-
-所有公共 API 均从包根导出，不需要导入内部路径。
-
-## 平台 API
-
-`createPlatformClient()` 是 Portal 与 Foundation HTTP 调用的统一入口。端点由调用方显式提供，客户端会使用当前用户会话 Token；也可通过 `token` 覆盖，便于服务端或测试宿主注入凭证。
-
-```ts
-import { createPlatformClient } from '@gt-fe/eap-sdk';
-
-const platform = createPlatformClient({
-  portalEndpoint: 'https://portal.example',
-  foundationEndpoint: 'https://foundation.example',
-});
-
-const agents = await platform.portalFetch('/api/v1/agents');
-const deployment = await platform.foundationFetch('/api/v1/deployments', {
-  method: 'POST',
-  body: JSON.stringify({ agentCode: 'report-agent', version: '1.0.0' }),
-});
-```
-
-客户端同时提供 `checkPortalHealth()`、`checkFoundationHealth()`、`uploadPortalFile()`，以及会保存统一用户会话的 `loginWithCas()`、`validateAndSaveToken()`，和吊销 Token 的 `revokeToken()`。Registry Tool/Skill 安装也使用此客户端，不再维护独立 HTTP 实现。
-
-## 当前用户会话
-
-SDK 将当前用户资料和平台凭证统一保存在 `~/.eap/config.json`；可通过 `EAP_CONFIG_DIR` 修改目录。
-
-```ts
-import {
-  clearCurrentUserSession,
-  getCurrentUserSession,
-  getCurrentUserToken,
-  saveCurrentUserSession,
-} from '@gt-fe/eap-sdk';
-
-saveCurrentUserSession({
-  userId: 'U001',
-  username: 'alice',
-  roles: ['developer'],
-  permissions: [],
-  token: '<platform-token>',
-  authMethod: 'token',
-  platformUrl: 'https://foundation.example',
-});
-
-const user = getCurrentUserSession();
-const token = getCurrentUserToken();
-clearCurrentUserSession();
-```
-
-规则如下：
-
-- 同一时刻只有一个当前用户，不随 CLI profile 或 Runtime storage profile 切换。
-- `getCurrentUserSession()` 始终返回用户资料；没有已保存会话时返回 `default-user`。
-- `getCurrentUserToken()` 优先读取 `EAP_TOKEN`，否则读取已保存 Token；默认用户不提供 Token。
-- Runtime 环境准备会把当前 Token 映射为 `EAP_DELEGATION_TOKEN`。
-- 用户资料在进程内缓存；测试或特殊宿主可调用 `clearUserSessionCache()` 清除缓存。
-
-## 版本锁定文件与资源安装
-
-开发态版本锁定文件是 `eap.lock.yaml`（规格称 `eap.lock`）。只供 dev-tools 在安装、校验、Runtime 准备和打包时使用。Runtime 与生产 Hosting 都不读它；发布包目标态是 `dependencies.lock`。
-
-```yaml
-lockfileVersion: 2
-resources:
-  tools:
-    - code: search-tool
-      version: 1.2.0
-      source: registry
-      path: .eap/remote/tools/search-tool/1.2.0
-      digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
-  skills: []
-  subagents: []
-```
-
-每条 Tool/Skill 记录包含：
-
-- `code`：Agent Manifest 中声明的资源编码。
-- `version`：确定的语义化版本。
-- `source`：`registry` 或 `local`。
-- `path`：相对于项目根的可移植目录路径。
-- `digest`：对应 Manifest 文件字节的 SHA-256，用于开发态缓存完整性校验。
-
-Registry 资源存放在 `.eap/remote`；工程内资源在 `tools/<code>` 或 `skills/<code>`。`eap.lock.yaml` 中 `source: local` 的 digest 优先按 `toolset.manifest.json` 计算，没有该文件再回退 `tool.manifest.json`。`source: registry` 也可以是 toolset；SDK 把它及同目录制品作为整体复制，不展开或校验其 `tools[]` 子工具。绝对路径、`..` 穿越、符号链接、缺失目录、缺失 Manifest 和本地/Registry 同名冲突都会被拒绝。
-
-安装单个远程资源：
-
-```ts
-import { installAgentResource } from '@gt-fe/eap-sdk';
-
-await installAgentResource({
-  root: process.cwd(),
-  kind: 'tool',
-  code: 'search-tool',
-  version: '1.2.0',
-  token: process.env.EAP_TOKEN,
-});
-```
-
-按名称和精确版本安装当前项目中的本地资源：
-
-```ts
-import { installLocalAgentResource } from '@gt-fe/eap-sdk';
-
-await installLocalAgentResource({
-  root: process.cwd(),
-  kind: 'tool',
-  code: 'echo-tool',
-  version: '1.0.0',
-});
-```
-
-按名称卸载当前项目中的本地或 Registry 资源：
-
-```ts
-import { uninstallAgentResource } from '@gt-fe/eap-sdk';
-
-await uninstallAgentResource({
-  root: process.cwd(),
-  code: 'echo-tool',
-});
-```
-
-恢复全部锁定资源并刷新本地资源记录：
-
-```ts
-import { installAgentDependencies } from '@gt-fe/eap-sdk';
-
-const result = await installAgentDependencies({ root: process.cwd() });
-console.log(result.restoredRegistryResources, result.refreshedLocalResources);
-```
-
-只有安装 API 会访问平台。服务启动和打包默认离线；远程缓存缺失时应先执行安装，而不是在 Runtime 启动后动态拉取。
-
-Registry Tool/Skill 安装会按 code 和 version 查询 Portal 资源详情，并通过其中的 `source_url` 下载 ZIP 制品。制品会解压到 `.eap/remote/tools/<code>/<version>/` 或 `.eap/remote/skills/<code>/<version>/`；锁文件中的 `digest` 是解压后根 Manifest 文件字节的 SHA-256，用于离线完整性校验。
-
-`agent.manifest.json` 只使用 `toolRefs`、`skillRefs` 和 `subagentRefs` 声明依赖；其中 `subagentRefs` 使用 `{ code, version }`，不会触发 Tool/Skill ZIP 下载。
-
-## Runtime 目录物化
-
-`prepareAgentRuntime()` 根据 Agent Manifest 和 `eap.lock.yaml` 生成一棵完整、干净的 Runtime 目录：
-
-```ts
-import { prepareAgentRuntime } from '@gt-fe/eap-sdk';
-
-const prepared = await prepareAgentRuntime({ root: process.cwd() });
-console.log(prepared.runtimeRoot);
-```
-
-资源映射规则：
-
-| 来源 | Runtime 目标目录 |
-|---|---|
-| Registry Toolset | `agents/<agentCode>/<version>/preinstall/tools/<toolsetCode>/` |
-| Registry Skill | `agents/<agentCode>/<version>/preinstall/skills/<skillCode>/` |
-| 本地 Tool | `agents/<agentCode>/<version>/users/<developerUserId>/tools/<toolCode>/` |
-| 本地 Skill | `agents/<agentCode>/<version>/users/<developerUserId>/skills/<skillCode>/` |
-
-物化器还会：
-
-- 复制根级 Agent Manifest 与 Graph。
-- 校验本地资源的根 Manifest 摘要和 Registry 解压缓存中的根 Manifest 摘要；锁文件不记录 Registry ZIP 摘要。
-- 生成 `dependencies.lock`、`snapshot.json` 和 `.ready`。
-- 把 Registry Toolset/Skill 复制到该 Agent 的 `preinstall/`，把本地 Tool/Skill 复制到 `users/<developerUserId>/`；不再生成 `shared/`。
-- 排除 `.git`、`.eap`、`node_modules`、`.env*`、coverage 和临时文件。
-- 拒绝符号链接和越界路径。
-- 通过临时目录加原子替换，避免 Runtime 看到半成品。
-
-物化器不创建 Runtime、不启动 HTTP 服务、不访问平台，也不负责压缩包。
-
-摘要字段的输入和格式见 [dev-tools SHA-256 摘要约定](../../docs/README.md#sha-256-摘要约定)。
-
-## Agent 服务
-
-`createAgentService()` 是异步工厂，因为必须先完成校验和目录物化，再构造 Runtime：
-
-```ts
-import { createAgentService } from '@gt-fe/eap-sdk';
-
-const service = await createAgentService({
-  root: process.cwd(),
-  messages: [{ role: 'system', content: '你是一个数据分析助手。' }],
-});
-
-const result = await service.invoke('汇总这份报告');
-
-for await (const event of service.stream('列出支撑数据')) {
-  console.log(event.type, event.data);
-}
-```
-
-启动本地 HTTP 服务：
-
-```ts
-await service.start({ host: '127.0.0.1', port: 3000 });
-// 使用结束后
-await service.stop();
-```
-
-默认行为：
-
-- `EAP_PREINSTALL_ROOT` 指向准备好的 `.eap/runtime`，不是项目源目录。
-- Runtime 只从准备好的 `.eap/runtime` 读取 Tool/Skill 定义；本地资源必须先锁定并物化。
-- `eap chat` / `eap dev` 传入 `sessionPersistence: true`，使用 Runtime `dev` profile，会话与消息写入 `.eap/sessions`。
-- Runtime `test` profile 为 Redis+PostgreSQL，不再表示内存。`createAgentService()` 在未开启 `sessionPersistence` 时仍设置 `EAP_RUNTIME_STORAGE_PROFILE=test`，本地嵌入须显式 `sessionPersistence: true` 或 `dev`。
-
-需要注入自定义 Runtime 时，使用 `runtimeFactory(prepared, environment)`。不要传入已经构造完成、并绑定了其他 GraphLoader 根目录的 Runtime。
-
-### Standalone Runtime 服务
-
-使用现有 `eap package` 命令生成独立服务需要的 Runtime 目录：
-
-```bash
-eap package --target standalone --output ./dist/runtime
-```
-
-该模式复用项目校验、资源解析、Runtime 物化和摘要校验，但不生成 TAR.GZ，也不复制项目的
-`package.json`、`eap.config.json` 或 `eap.lock.yaml`。输出目录结构为
-`dist/runtime/agents/<code>/<version>/`。
-
-已由构建工具打包的服务入口可以直接消费该目录：
-
-```ts
-import { createEmbeddedAgentService } from '@gt-fe/eap-sdk';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const service = await createEmbeddedAgentService({
-  runtimeRoot: join(dirname(fileURLToPath(import.meta.url)), 'runtime'),
-});
-await service.start({ host: '0.0.0.0', port: 3000 });
-```
-
-`createEmbeddedAgentService()` 只校验并读取已物化 Runtime，不会重新发现源项目或执行物化。
-默认的 `eap package` 行为不变，仍然生成可交付的 TAR.GZ 部署包。
-
-## 打包与验包
-
-`packageAgentProject()` 会独立生成 package staging Runtime 树，不复用开发态 `.eap/runtime`：
-
-```ts
-import { packageAgentProject, readAgentPackage } from '@gt-fe/eap-sdk';
-
-const artifact = await packageAgentProject({
-  root: process.cwd(),
-});
-
-const verified = readAgentPackage(artifact.archivePath);
-console.log(verified.manifest.agents[0], verified.digest);
-```
-
-默认输出：
-
-```text
-.eap/package/eap-agent-project.tar.gz
-.eap/package/eap-agent-project.tar.gz.sha256
-```
-
-部署包只包含：
-
-- 物化后的 Agent 版本目录内容，直接展开到包根目录（例如 `agent.manifest.json`、`graph.json`、`preinstall/`、`users/`）。
-- 根目录的包文件索引 `eap-package.json`。
-
-部署包不会包含 `eap.lock.yaml`、`.eap/remote`、会话、checkpoint、staging 名称或其他开发缓存。`readAgentPackage()` 会校验 `eap-package.json` 的所有文件大小和摘要，并要求包内恰好有一个 Agent。
-
-## 项目配置映射
-
-`eap.config.json` 由 `EapProjectConfigSchema` 校验。SDK 在 Runtime 构造前完成以下主要映射：
-
-顶层 `version` 是 SDK package version；配置版本不匹配时项目校验、服务创建和打包都会失败。
-
-| 项目配置或输入 | Runtime 环境变量 |
-|---|---|
-| `platform.portalUrl` | `EAP_PLATFORM_ENDPOINT` |
-| `platform.foundationServiceUrl` | `FOUNDATION_SERVICE_URL` |
-| `runtime.deploymentContext` | `EAP_DEPLOYMENT_CONTEXT` |
-| `runtime.governance.enabled` | `GOVERNANCE_DISABLED` |
-| `runtime.storage` | `EAP_RUNTIME_STORAGE_PROFILE`、`EAP_CHECKPOINT_DIR` |
-| `runtime.tools` | `EAP_TOOL_EXECUTION_MODE`、`EAP_TOOL_GATEWAY_TRANSPORT` |
-| 准备好的 Runtime 目录 | `EAP_PREINSTALL_ROOT` |
-| 当前用户 Token | `EAP_DELEGATION_TOKEN` |
-
-显式环境变量优先于大多数项目配置；`EAP_PREINSTALL_ROOT` 始终使用本次物化得到的目录。
-
-## 内置模板
-
-SDK 与 CLI 使用同一套根级单 Agent 项目约定。内置模板包括：
-
-- `simple-flow`：固定顺序工作流。
-- `single-agent-with-tools`：单 Agent + ReAct Tool 调用。
-- `plan-and-execute`：规划、Tool 执行、总结。
-- `dag-workflow`：条件分支与任务聚合。
-
-工作流语义由 `graph.json` 表达，`agent.manifest.json` 只保存身份和依赖。包含 Tool 的模板自带本地、已锁定的 `echo-tool`，校验和打包不依赖 Registry 缓存。
+# @gt-fe/eap-sdk
+
+`@gt-fe/eap-sdk` 是 EAP 单 Agent 项目的开发期 SDK，负责项目发现与校验、用户会话、平台 API、Tool/Skill 依赖安装、Runtime 目录物化、本地 Agent Service 以及确定性打包。
+
+Agent 的实际执行仍由 `@gt-fe/eap-runtime` 负责。SDK 不重新实现 Graph 编译、节点执行、Tool 路由或 Runtime 事件协议。
+
+## 安装
+
+```bash
+npm install @gt-fe/eap-sdk
+```
+
+本包为纯 ESM：
+
+```ts
+import { createAgentService } from '@gt-fe/eap-sdk';
+```
+
+## 项目模型
+
+一个项目只开发一个 Agent，开发者维护的源文件位于项目根目录：
+
+```text
+<project>/
+├── agent.manifest.json
+├── graph.json
+├── eap.config.json
+├── eap.lock.yaml
+├── tools/<code>/...
+├── skills/<code>/...
+└── .eap/
+    ├── remote/                         # Registry 资源缓存
+    ├── runtime/                        # 开发态 EAP_PREINSTALL_ROOT
+    │   └── agents/<agentCode>/<version>/preinstall|users/
+    ├── sessions/                       # 可选的本地会话数据
+    ├── package-staging/                # 打包临时目录
+    └── package/                        # 默认包输出目录
+```
+
+`agent.manifest.json`、`graph.json`、`eap.config.json`、`eap.lock.yaml` 以及本地 `tools/`、`skills/` 是项目输入；`.eap/` 是 SDK 生成的可删除状态。
+
+项目 `eap.config.json.version` 必须严格等于当前安装的 `@gt-fe/eap-sdk` package version；字段级配置和部署交付说明见 [dev-tools 文档入口](../../docs/README.md)。
+
+`findAgentRoot()` 和 `resolveAgentProject()` 只发现源项目，不使用 `EAP_PREINSTALL_ROOT`。选择器只支持 `root` 和 `startDir`，不存在 Agent code、版本或目录歧义选择。
+
+```ts
+import {
+  resolveAgentProject,
+  validateAgentProject,
+  type AgentProjectSelector,
+} from '@gt-fe/eap-sdk';
+
+const selector: AgentProjectSelector = { root: process.cwd() };
+const project = resolveAgentProject(selector);
+const validation = validateAgentProject(project.root);
+
+if (!validation.valid) {
+  console.error(validation.issues);
+}
+```
+
+## 核心能力
+
+| 能力 | 主要 API | 说明 |
+|---|---|---|
+| 项目发现 | `findAgentRoot()`、`resolveAgentProject()` | 查找根级单 Agent 项目 |
+| 项目校验 | `validateAgentProject()`、`validateGraph()` | 校验 Manifest、Graph、`eap.lock.yaml` 和资源路径 |
+| 用户会话 | `getCurrentUserSession()`、`saveCurrentUserSession()` | 管理当前登录用户和平台 Token；本地可用 `EAP_CHAT_USER` / `EAP_DEBUG_USER` |
+| 平台 API | `createPlatformClient()` | 访问 Portal、Foundation 和平台认证 |
+| 依赖安装 | `installAgentResource()`、`installAgentDependencies()` | 下载或恢复 Tool/Skill ZIP 制品，并维护 `eap.lock.yaml` |
+| Runtime 物化 | `prepareAgentRuntime()` | 生成 Runtime 可直接读取的预装目录 |
+| 本地服务 | `createAgentService()` | 物化后创建 Runtime-backed Agent Service |
+| Standalone 服务 | `packageStandaloneAgentProject()`、`createEmbeddedAgentService()` | 将同一套物化 Runtime 输出到 `dist/runtime`，启动时不读取源项目 |
+| 打包与验包 | `packageAgentProject()`、`readAgentPackage()` | 生成并校验单 Agent Runtime 部署包 |
+| Schema | `AgentManifestSchema`、`GraphSchema`、`ToolManifestSchema` 等 | SDK 所有项目文件的 Zod Schema |
+
+所有公共 API 均从包根导出，不需要导入内部路径。
+
+## 平台 API
+
+`createPlatformClient()` 是 Portal 与 Foundation HTTP 调用的统一入口。端点由调用方显式提供，客户端会使用当前用户会话 Token；也可通过 `token` 覆盖，便于服务端或测试宿主注入凭证。
+
+```ts
+import { createPlatformClient } from '@gt-fe/eap-sdk';
+
+const platform = createPlatformClient({
+  portalEndpoint: 'https://portal.example',
+  foundationEndpoint: 'https://foundation.example',
+});
+
+const agents = await platform.portalFetch('/api/v1/agents');
+const deployment = await platform.foundationFetch('/api/v1/deployments', {
+  method: 'POST',
+  body: JSON.stringify({ agentCode: 'report-agent', version: '1.0.0' }),
+});
+```
+
+客户端同时提供 `checkPortalHealth()`、`checkFoundationHealth()`、`uploadPortalFile()`，以及会保存统一用户会话的 `loginWithCas()`、`validateAndSaveToken()`，和吊销 Token 的 `revokeToken()`。Registry Tool/Skill 安装也使用此客户端，不再维护独立 HTTP 实现。
+
+## 当前用户会话
+
+SDK 将当前用户资料和平台凭证统一保存在 `~/.eap/config.json`；可通过 `EAP_CONFIG_DIR` 修改目录。
+
+```ts
+import {
+  clearCurrentUserSession,
+  getCurrentUserSession,
+  getCurrentUserToken,
+  saveCurrentUserSession,
+} from '@gt-fe/eap-sdk';
+
+saveCurrentUserSession({
+  userId: 'U001',
+  username: 'alice',
+  roles: ['developer'],
+  permissions: [],
+  token: '<platform-token>',
+  authMethod: 'token',
+  platformUrl: 'https://foundation.example',
+});
+
+const user = getCurrentUserSession();
+const token = getCurrentUserToken();
+clearCurrentUserSession();
+```
+
+规则如下：
+
+- 同一时刻只有一个当前用户，不随 CLI profile 或 Runtime storage profile 切换。
+- `getCurrentUserSession()` 始终返回用户资料；没有已保存会话时返回 `default-user`。
+- `getCurrentUserToken()` 优先读取 `EAP_TOKEN`，否则读取已保存 Token；默认用户不提供 Token。
+- Runtime 环境准备会把当前 Token 映射为 `EAP_DELEGATION_TOKEN`。
+- 用户资料在进程内缓存；测试或特殊宿主可调用 `clearUserSessionCache()` 清除缓存。
+
+## 版本锁定文件与资源安装
+
+开发态版本锁定文件是 `eap.lock.yaml`（规格称 `eap.lock`）。只供 dev-tools 在安装、校验、Runtime 准备和打包时使用。Runtime 与生产 Hosting 都不读它；发布包目标态是 `dependencies.lock`。
+
+```yaml
+lockfileVersion: 2
+resources:
+  tools:
+    - code: search-tool
+      version: 1.2.0
+      source: registry
+      path: .eap/remote/tools/search-tool/1.2.0
+      digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+  skills: []
+  subagents: []
+```
+
+每条 Tool/Skill 记录包含：
+
+- `code`：Agent Manifest 中声明的资源编码。
+- `version`：确定的语义化版本。
+- `source`：`registry` 或 `local`。
+- `path`：相对于项目根的可移植目录路径。
+- `digest`：对应 Manifest 文件字节的 SHA-256，用于开发态缓存完整性校验。
+
+Registry 资源存放在 `.eap/remote`；工程内资源在 `tools/<code>` 或 `skills/<code>`。`eap.lock.yaml` 中 `source: local` 的 digest 优先按 `toolset.manifest.json` 计算，没有该文件再回退 `tool.manifest.json`。`source: registry` 也可以是 toolset；SDK 把它及同目录制品作为整体复制，不展开或校验其 `tools[]` 子工具。绝对路径、`..` 穿越、符号链接、缺失目录、缺失 Manifest 和本地/Registry 同名冲突都会被拒绝。
+
+安装单个远程资源：
+
+```ts
+import { installAgentResource } from '@gt-fe/eap-sdk';
+
+await installAgentResource({
+  root: process.cwd(),
+  kind: 'tool',
+  code: 'search-tool',
+  version: '1.2.0',
+  token: process.env.EAP_TOKEN,
+});
+```
+
+按名称和精确版本安装当前项目中的本地资源：
+
+```ts
+import { installLocalAgentResource } from '@gt-fe/eap-sdk';
+
+await installLocalAgentResource({
+  root: process.cwd(),
+  kind: 'tool',
+  code: 'echo-tool',
+  version: '1.0.0',
+});
+```
+
+按名称卸载当前项目中的本地或 Registry 资源：
+
+```ts
+import { uninstallAgentResource } from '@gt-fe/eap-sdk';
+
+await uninstallAgentResource({
+  root: process.cwd(),
+  code: 'echo-tool',
+});
+```
+
+恢复全部锁定资源并刷新本地资源记录：
+
+```ts
+import { installAgentDependencies } from '@gt-fe/eap-sdk';
+
+const result = await installAgentDependencies({ root: process.cwd() });
+console.log(result.restoredRegistryResources, result.refreshedLocalResources);
+```
+
+只有安装 API 会访问平台。服务启动和打包默认离线；远程缓存缺失时应先执行安装，而不是在 Runtime 启动后动态拉取。
+
+Registry Tool/Skill 安装会按 code 和 version 查询 Portal 资源详情，并通过其中的 `source_url` 下载 ZIP 制品。制品会解压到 `.eap/remote/tools/<code>/<version>/` 或 `.eap/remote/skills/<code>/<version>/`；锁文件中的 `digest` 是解压后根 Manifest 文件字节的 SHA-256，用于离线完整性校验。
+
+`agent.manifest.json` 只使用 `toolRefs`、`skillRefs` 和 `subagentRefs` 声明依赖；其中 `subagentRefs` 使用 `{ code, version }`，不会触发 Tool/Skill ZIP 下载。
+
+Skill 包的 `skill.manifest.json` 可以通过 `toolsets`（或旧版 `toolRefs` 中的 `{ code, version }` 对象）声明 Toolset 依赖。安装 Skill 时，这些依赖会合并到 Agent 的 `toolRefs` 和 `eap.lock.yaml`：
+
+- Agent 已有同名 Toolset 时，以 Agent 的版本为准，Skill 不会覆盖它。
+- Agent 没有同名 Toolset 时，Registry Skill 会按 Skill 声明的版本安装 Registry Tool；本地 Skill 会复用并锁定当前项目的本地 Tool，缺失时提示先执行 `eap install`。
+- Skill 中仅有字符串工具名或 `{ toolId, name }` 的引用属于 Runtime 的工具筛选信息，不会被误当成可下载的 Toolset。
+
+卸载 Tool 前 SDK 会检查当前 Agent 已声明的 Skill 依赖。仍被 Skill 引用时会拒绝卸载，并列出 Skill 版本；请先更新 Skill 或在平台重新配置依赖，再重新安装 Skill 后卸载 Tool。
+
+## Runtime 目录物化
+
+`prepareAgentRuntime()` 根据 Agent Manifest 和 `eap.lock.yaml` 生成一棵完整、干净的 Runtime 目录：
+
+```ts
+import { prepareAgentRuntime } from '@gt-fe/eap-sdk';
+
+const prepared = await prepareAgentRuntime({ root: process.cwd() });
+console.log(prepared.runtimeRoot);
+```
+
+资源映射规则：
+
+| 来源 | Runtime 目标目录 |
+|---|---|
+| Registry Toolset | `agents/<agentCode>/<version>/preinstall/tools/<toolsetCode>/` |
+| Registry Skill | `agents/<agentCode>/<version>/preinstall/skills/<skillCode>/` |
+| 本地 Tool | `agents/<agentCode>/<version>/users/<developerUserId>/tools/<toolCode>/` |
+| 本地 Skill | `agents/<agentCode>/<version>/users/<developerUserId>/skills/<skillCode>/` |
+
+物化器还会：
+
+- 复制根级 Agent Manifest 与 Graph。
+- 校验本地资源的根 Manifest 摘要和 Registry 解压缓存中的根 Manifest 摘要；锁文件不记录 Registry ZIP 摘要。
+- 生成 `dependencies.lock`、`snapshot.json` 和 `.ready`。
+- 把 Registry Toolset/Skill 复制到该 Agent 的 `preinstall/`，把本地 Tool/Skill 复制到 `users/<developerUserId>/`；不再生成 `shared/`。
+- 排除 `.git`、`.eap`、`node_modules`、`.env*`、coverage 和临时文件。
+- 拒绝符号链接和越界路径。
+- 通过临时目录加原子替换，避免 Runtime 看到半成品。
+
+物化器不创建 Runtime、不启动 HTTP 服务、不访问平台，也不负责压缩包。
+
+摘要字段的输入和格式见 [dev-tools SHA-256 摘要约定](../../docs/README.md#sha-256-摘要约定)。
+
+## Agent 服务
+
+`createAgentService()` 是异步工厂，因为必须先完成校验和目录物化，再构造 Runtime：
+
+```ts
+import { createAgentService } from '@gt-fe/eap-sdk';
+
+const service = await createAgentService({
+  root: process.cwd(),
+  messages: [{ role: 'system', content: '你是一个数据分析助手。' }],
+});
+
+const result = await service.invoke('汇总这份报告');
+
+for await (const event of service.stream('列出支撑数据')) {
+  console.log(event.type, event.data);
+}
+```
+
+启动本地 HTTP 服务：
+
+```ts
+await service.start({ host: '127.0.0.1', port: 3000 });
+// 使用结束后
+await service.stop();
+```
+
+默认行为：
+
+- `EAP_PREINSTALL_ROOT` 指向准备好的 `.eap/runtime`，不是项目源目录。
+- Runtime 只从准备好的 `.eap/runtime` 读取 Tool/Skill 定义；本地资源必须先锁定并物化。
+- `eap chat` / `eap dev` 传入 `sessionPersistence: true`，使用 Runtime `dev` profile，会话与消息写入 `.eap/sessions`。
+- Runtime `test` profile 为 Redis+PostgreSQL，不再表示内存。`createAgentService()` 在未开启 `sessionPersistence` 时仍设置 `EAP_RUNTIME_STORAGE_PROFILE=test`，本地嵌入须显式 `sessionPersistence: true` 或 `dev`。
+
+需要注入自定义 Runtime 时，使用 `runtimeFactory(prepared, environment)`。不要传入已经构造完成、并绑定了其他 GraphLoader 根目录的 Runtime。
+
+### Standalone Runtime 服务
+
+使用现有 `eap package` 命令生成独立服务需要的 Runtime 目录：
+
+```bash
+eap package --target standalone --output ./dist/runtime
+```
+
+该模式复用项目校验、资源解析、Runtime 物化和摘要校验，但不生成 TAR.GZ，也不复制项目的
+`package.json`、`eap.config.json` 或 `eap.lock.yaml`。输出目录结构为
+`dist/runtime/agents/<code>/<version>/`。
+
+已由构建工具打包的服务入口可以直接消费该目录：
+
+```ts
+import { createEmbeddedAgentService } from '@gt-fe/eap-sdk';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const service = await createEmbeddedAgentService({
+  runtimeRoot: join(dirname(fileURLToPath(import.meta.url)), 'runtime'),
+});
+await service.start({ host: '0.0.0.0', port: 3000 });
+```
+
+`createEmbeddedAgentService()` 只校验并读取已物化 Runtime，不会重新发现源项目或执行物化。
+默认的 `eap package` 行为不变，仍然生成可交付的 TAR.GZ 部署包。
+
+## 打包与验包
+
+`packageAgentProject()` 会独立生成 package staging Runtime 树，不复用开发态 `.eap/runtime`：
+
+```ts
+import { packageAgentProject, readAgentPackage } from '@gt-fe/eap-sdk';
+
+const artifact = await packageAgentProject({
+  root: process.cwd(),
+});
+
+const verified = readAgentPackage(artifact.archivePath);
+console.log(verified.manifest.agents[0], verified.digest);
+```
+
+默认输出：
+
+```text
+.eap/package/eap-agent-project.tar.gz
+.eap/package/eap-agent-project.tar.gz.sha256
+```
+
+部署包只包含：
+
+- 物化后的 Agent 版本目录内容，直接展开到包根目录（例如 `agent.manifest.json`、`graph.json`、`preinstall/`、`users/`）。
+- 根目录的包文件索引 `eap-package.json`。
+
+部署包不会包含 `eap.lock.yaml`、`.eap/remote`、会话、checkpoint、staging 名称或其他开发缓存。`readAgentPackage()` 会校验 `eap-package.json` 的所有文件大小和摘要，并要求包内恰好有一个 Agent。
+
+## 项目配置映射
+
+`eap.config.json` 由 `EapProjectConfigSchema` 校验。SDK 在 Runtime 构造前完成以下主要映射：
+
+顶层 `version` 是 SDK package version；配置版本不匹配时项目校验、服务创建和打包都会失败。
+
+| 项目配置或输入 | Runtime 环境变量 |
+|---|---|
+| `platform.portalUrl` | `EAP_PLATFORM_ENDPOINT` |
+| `platform.foundationServiceUrl` | `FOUNDATION_SERVICE_URL` |
+| `runtime.deploymentContext` | `EAP_DEPLOYMENT_CONTEXT` |
+| `runtime.governance.enabled` | `GOVERNANCE_DISABLED` |
+| `runtime.storage` | `EAP_RUNTIME_STORAGE_PROFILE`、`EAP_CHECKPOINT_DIR` |
+| `runtime.tools` | `EAP_TOOL_EXECUTION_MODE`、`EAP_TOOL_GATEWAY_TRANSPORT` |
+| 准备好的 Runtime 目录 | `EAP_PREINSTALL_ROOT` |
+| 当前用户 Token | `EAP_DELEGATION_TOKEN` |
+
+显式环境变量优先于大多数项目配置；`EAP_PREINSTALL_ROOT` 始终使用本次物化得到的目录。
+
+## 内置模板
+
+SDK 与 CLI 使用同一套根级单 Agent 项目约定。内置模板包括：
+
+- `simple-flow`：固定顺序工作流。
+- `single-agent-with-tools`：单 Agent + ReAct Tool 调用。
+- `plan-and-execute`：规划、Tool 执行、总结。
+- `dag-workflow`：条件分支与任务聚合。
+
+工作流语义由 `graph.json` 表达，`agent.manifest.json` 只保存身份和依赖。包含 Tool 的模板自带本地、已锁定的 `echo-tool`，校验和打包不依赖 Registry 缓存。