@gt-fe/eap-runtime 0.0.8

package/README.md

@@ -0,0 +1,323 @@
+# @eap/runtime
+
+Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编译与执行、Task/Session/Message、Checkpoint、Tool 编排、预装定义加载、Token 预算、HITL / Fork。
+
+生产调用入口为 **hosting-service 内嵌**本包；本地开发由 **dev-tools**（`eap chat` / `eap dev`）通过 `createDevRuntime()` 进程内嵌调用，通常不单独启动 Runtime HTTP 服务。
+
+## 更新日志
+
+| 日期 | 摘要 |
+|------|------|
+| 2026-08-19 | 0.0.8：Skill 子图 SSE 闭环；`ExecuteParams.traceId`；`tool.called` 改为 Tool 节点开始执行。依赖 `@eap/contracts@0.0.8`。详见 [CHANGELOG.md](./CHANGELOG.md) |
+| 2026-08-18 | 0.0.7：`DevHttpExecutor`、`mode=mcp` 缺配置失败、HTTP 出站语义与 Gateway 共用 `@eap/contracts@0.0.7` |
+| 2026-07-29 | 补全 `.env.example` 全量环境变量（部署上下文 / Tool / 预装 / 存储装配 / 调试分区）；§5 预装开关表补 `EAP_PRELOAD_DEFINITION_CACHE` |
+| 2026-07-30 | 新增 `AgentRuntime.seedSessionMessages()`（OpenAI Assistants 风格会话种子消息）；专为 SDK `createAgentService({ messages })` 服务，支持 few-shot / 开场白一次性预置；role 白名单 user/assistant，exactly-once 幂等。详见 [`docs/contracts/runtime-sdk-integration-final.md`](../docs/contracts/runtime-sdk-integration-final.md) §4.5 / §5.5 |
+| 2026-07-24 | 修订 README / 样例说明表述，去除口语化 |
+| 2026-07-24 | 增补预装加载与请求流转文档链接 `docs/contracts/runtime-preinstall-load-flow.md` |
+| 2026-07-24 | **全面重写**：补充 SDK、Graph、预装加载、存储 Profile、与 dev-tools 的关系、环境变量速查及文档索引；此前内容主要覆盖 Tool L1 demo 与私服发布 |
+| 2026-07-24 | 对齐预装契约与样例目录 `fixtures/eap-preinstall-sample`、预装行为开关（`EAP_PRELOAD_*`） |
+| （更早） | 初版：快速开始、Tool L1 demo、Hosting 关系、私服发布、简短文档索引 |
+
+| 权威文档 | 路径 |
+|----------|------|
+| 模块规格 | [`.kiro/specs/04-runtime-core/`](../.kiro/specs/04-runtime-core/) |
+| SDK 集成手册 | [`docs/contracts/runtime-sdk-integration-final.md`](../docs/contracts/runtime-sdk-integration-final.md) |
+| 环境变量总表 | [`docs/governance/governance-env-config.md`](../docs/governance/governance-env-config.md) |
+| 预装联调契约 | [`docs/contracts/preload-hosting-runtime-contract.md`](../docs/contracts/preload-hosting-runtime-contract.md) |
+| 预装加载与请求流转 | [`docs/contracts/runtime-preinstall-load-flow.md`](../docs/contracts/runtime-preinstall-load-flow.md) |
+| 本地 Agent 闭环 | [`docs/workflows/local-agent-dev-loop.md`](../docs/workflows/local-agent-dev-loop.md) |
+
+---
+
+## 1. 定位与边界
+
+**负责**
+
+- 按 Graph DSL 执行 Agent（同步 `execute` / 流式 `stream`）
+- 从 **Deployment 预装目录**（或开发态 Registry / 本地 tools）加载 Graph、Tool、Skill 定义
+- Session / Message / Checkpoint / Task 生命周期与持久化装配
+- Tool 路由与执行（mock / 本机 MCP / Tool Gateway）
+- HITL 中断恢复、Checkpoint Fork
+- Token 预算与用量统计；可选 Trace 采集钩子
+
+**不负责**
+
+- 对外 HTTP/API 网关、发布与流量（Hosting / Portal）
+- Agent/Tool/Skill **登记**与审批（Registry / developer-portal）
+- 企业鉴权策略本体（Governance 服务；Runtime 只调客户端）
+- CLI / Playground UI（dev-tools）
+
+---
+
+## 2. 能力一览（按源码模块）
+
+| 模块 | 目录 | 能力 |
+|------|------|------|
+| SDK 门面 | `src/runtime/` | `AgentRuntime`：`execute` / `stream` / `seedSessionMessages` / `resumeHitl` / `streamResumeHitl` / `fork`；`createDevRuntime()` 本地装配 |
+| Graph | `src/graph/` | `LangGraphAdapter`、子图（Skill）、LLM/Tool 节点、HITL、条件边、重试 |
+| 预装 / Registry | `src/registry/` | `GraphLoader`、`FileSystemDeploymentSnapshot`、严格预装、`runtime.preload.*` |
+| Tool | `src/tool/` | `ToolOrchestrator` / `ToolExecutionRouter`、mock/dev-mcp/Gateway、确认拦截 |
+| Checkpoint | `src/checkpoint/` | Memory / File / Redis+PG / PG；Composite |
+| Session / Message | `src/session/` | Session 上下文、多轮消息落盘、HITL 占位消息 |
+| Task | `src/task/` | 任务状态机（含 `waiting_hitl`） |
+| Token | `src/token/` | 预算、Session 日预算、节点用量统计 |
+| Governance 客户端 | `src/governance/` | AllowAll（本地）/ Http；`skill:use` / tool 权限 |
+| LLM Provider | `src/providers/` | Echo / Http(OpenAI 兼容) / Routing |
+| SSE | `src/sse/` | 流式事件封装 |
+| Memory | `src/memory/` | 压缩等（演进中） |
+| Dev HTTP | `src/api/`、`src/server.ts` | 仅 `EAP_DEV_HTTP=1`；生产勿依赖 |
+
+---
+
+## 3. 对外入口
+
+### 3.1 `AgentRuntime`（Hosting / SDK）
+
+```ts
+import { createAgentRuntime } from '@eap/runtime';
+
+// 由 Hosting 或 createDevRuntime 注入依赖后：
+await agentRuntime.execute({ agentCode, input, sessionId, taskId, traceId, /* … */ });
+for await (const ev of agentRuntime.stream({ agentCode, input, sessionId, taskId, traceId })) { /* SSE */ }
+await agentRuntime.seedSessionMessages({ agentCode, messages: [ /* role: user | assistant */ ] });
+await agentRuntime.resumeHitl(taskId, { choice, userId, /* … */ });
+for await (const ev of agentRuntime.streamResumeHitl(taskId, { choice, userId })) { /* HITL 续跑事件 */ }
+await agentRuntime.fork(checkpointId, { /* overrides */ });
+```
+
+细则与字段表见 [`docs/contracts/runtime-sdk-integration-final.md`](../docs/contracts/runtime-sdk-integration-final.md)。
+
+### 3.2 `createDevRuntime()`（dev-tools / 本地）
+
+`eap chat`（默认 SDK 嵌入）与本地测试使用的装配工厂：LLM、Tool、Governance、存储、`GraphLoader` 一次配齐，**无需起 Runtime HTTP**。
+
+```ts
+import { createDevRuntime } from '@eap/runtime';
+
+const rt = createDevRuntime();
+const result = await rt.agentRuntime.execute({ /* … */ });
+```
+
+诊断字段见返回值 `diagnostics`（deploymentContext、tool 模式、storage profile 等）。
+
+### 3.3 与 Hosting / dev-tools 的关系
+
+```text
+开发者本机                          生产
+─────────                          ────
+dev-tools (eap chat / eap dev)
+    │ createDevRuntime()
+    ▼
+@eap/runtime  ◄──────────────  hosting-service 内嵌 runtime/dist
+    │                              │
+    ├─ GraphLoader ← EAP_PREINSTALL_ROOT / 本地 Agent 工程
+    ├─ Tool：mock | mcp | Gateway
+    └─ 存储：profile=dev|integration|…
+```
+
+- **生产**：Hosting HTTP → 内嵌 Runtime；预装根由 Hosting 注入；`EAP_DEPLOYMENT_CONTEXT=server`
+- **本地 Agent 开发**：优先 `eap chat`（SDK）；`eap chat-http` / `eap dev` 才走 HTTP
+- 改本仓 `src/**` 后须 `pnpm run build`，再重启 Hosting 或重新拉起 CLI
+
+本地闭环步骤：[`docs/workflows/local-agent-dev-loop.md`](../docs/workflows/local-agent-dev-loop.md)。
+
+---
+
+## 4. Graph 执行
+
+- **引擎**：`LangGraphAdapter`（`IStateGraphEngine`）将平台 Graph DSL 编成 LangGraph StateGraph
+- **节点**：`llm`、`tool`、`subgraph`（Skill）、并行/条件边、HITL 等待
+- **Skill 子图**：节点可带内嵌 `subgraphDsl`；或仅 `skillId`，从 state.`skillDefinitions` 取 `workflow` 执行；技能 `prompt` 经 `activeSkillPrompt` 注入子图入口 LLM
+- **权限**：子图执行前 `skill:{skillId}:use`（Governance）
+- **流式**：`stream()` 产出 RuntimeEvent，再映射为 SSE（`response.chunk`、`tool.*`、`task.*` 等）
+
+DSL / 契约细节见 `.kiro/specs/04-runtime-core/design.md` §1.4 与 `src/graph/contracts/`。
+
+---
+
+## 5. 预装定义加载（生产权威路径）
+
+生产（`server` + `EAP_PREINSTALL_ROOT`）下，**Agent / Graph / Tool / Skill 可执行定义只读本地预装**，不回退 Registry 拉定义（治理、Tool Gateway、LLM 出站除外）。
+
+| 组件 | 作用 |
+|------|------|
+| `FileSystemDeploymentSnapshot` | 读三层目录：`agents/` · `shared/` · `users/` |
+| `GraphLoader` | `loadGraph` / `loadToolDefinitions` / `loadSkillDefinitions` |
+| 严格预装 | `strictPreinstall`（server + 有预装根时默认 true） |
+
+联调契约与样例目录：
+
+- [`docs/contracts/preload-hosting-runtime-contract.md`](../docs/contracts/preload-hosting-runtime-contract.md)
+- Runtime 清单：[`.kiro/specs/runtime-requirements-for-vendor.md`](../.kiro/specs/runtime-requirements-for-vendor.md)
+- 样例预装根：[`fixtures/eap-preinstall-sample/`](../fixtures/eap-preinstall-sample/)
+
+### 预装相关环境变量（默认多为关闭）
+
+| 变量 | 默认 | 含义 |
+|------|------|------|
+| `EAP_PREINSTALL_ROOT` | — | 预装根；也可用 `GraphLoader({ preinstallRoot })` |
+| `EAP_PRELOAD_REQUIRE_READY` | 关 | 缺 `.ready` → `runtime.preload.missing` |
+| `EAP_PRELOAD_REQUIRE_CHECKSUM` | 关 | snapshot 须含 sha256 或 artifacts |
+| `EAP_PRELOAD_USER_SKILL_OVERRIDE` | 关 | `users` 优先于 `shared` |
+| `EAP_PRELOAD_VALIDATE_SKILL_IO` | 关 | 校验 Skill `inputDef.required`（`state.skillInput`） |
+| `EAP_PRELOAD_DEFINITION_CACHE` | 有预装时开 | 定义缓存；`0`/`false` 关闭，`1`/`true` 强制开 |
+| `EAP_AGENT_VERSION` | — | 默认 Agent 版本目录名 |
+
+错误码：`runtime.preload.*`（`@eap/contracts`）。
+
+改样例后重算摘要：
+
+```bash
+node ../fixtures/eap-preinstall-sample/scripts/seal-snapshot.mjs
+```
+
+---
+
+## 6. 持久化与存储 Profile
+
+由 `assembleRuntimeStorage()` / `EAP_RUNTIME_STORAGE_PROFILE` 统一装配 Checkpoint、Session、Message。
+
+| Profile | Checkpoint | Session | Message | 典型场景 |
+|---------|------------|---------|---------|----------|
+| `test` | Memory | Memory | Memory | 单测 |
+| `dev` | File | File | File | `eap chat` / 本机 |
+| `integration` | Redis + PG | （Hosting Session） | PG | Hosting 内嵌联调 |
+| `production` | Redis + PG | （Hosting Session） | PG | 多副本生产 |
+
+常用目录变量（**仅 `dev` profile**）：
+
+| 变量 | 说明 |
+|------|------|
+| `EAP_CHECKPOINT_DIR` | File Checkpoint |
+| `EAP_SESSION_DIR` | File Session |
+| `EAP_MESSAGE_DIR` | File Message |
+
+完整策略与库表约定：[`docs/governance/governance-env-config.md` §9](../docs/governance/governance-env-config.md#9-runtime-存储装配策略)、[`docs/architecture/session-message-checkpoint-alignment.md`](../docs/architecture/session-message-checkpoint-alignment.md)、[`docs/verification/db-storage-verification.md`](../docs/verification/db-storage-verification.md)。
+
+本地带 File 存储的 fixture 示例：[`fixtures/eap-local-test/`](../fixtures/eap-local-test/)（`chat.sh` / `chat-db.sh`）。
+
+---
+
+## 7. Tool 与 LLM
+
+| 模式 | 何时 | 说明 |
+|------|------|------|
+| `mock` | 本地默认 | 不调真实 Tool |
+| `mcp` / DevMcp | `eap chat --tool-mode mcp` | 本机直连 MCP（`EAP_TOOL_EXECUTION_MODE`，仅 createDevRuntime） |
+| Gateway | 生产 / Hosting | `EAP_TOOL_GATEWAY_TRANSPORT=mcp`（生产）；`http` 仅调试 |
+
+- 编排：`ToolOrchestrator` + `ToolExecutionRouter`（`deploymentContext`: `server` \| `desktop` \| `dev`）
+- L1 Tool 演示（非 Agent Graph 生产调用路径）：[`docs/workflows/tool-demo-l1-guide.md`](../docs/workflows/tool-demo-l1-guide.md)、`examples/demo-tool/`
+- 执行契约：[`docs/contracts/tool-execution.md`](../docs/contracts/tool-execution.md)
+
+LLM：`EchoLLMProvider`（无配置时的默认实现）→ `HttpLLMProvider`（`OPENAI_*`）→ `RoutingLLMProvider`；默认模型可通过 `EAP_DEFAULT_MODEL` 指定。
+
+---
+
+## 8. 快速开始
+
+> 须先构建兄弟包 `@eap/contracts`。本仓推荐 **pnpm**。
+
+```bash
+cd ../eap-contracts && pnpm install && pnpm run build
+cd ../runtime && pnpm install && pnpm run build
+
+# 单测
+pnpm test
+
+# 独立 dev HTTP（非生产调用路径；需 EAP_DEV_HTTP=1）
+EAP_DEV_HTTP=1 pnpm run dev
+```
+
+预装样例单测：
+
+```bash
+pnpm exec vitest run \
+  src/__tests__/preinstall-sample-fixture.test.ts \
+  src/__tests__/preload-strict.test.ts \
+  src/__tests__/preload-checksum-users.test.ts \
+  src/__tests__/preload-skill-definitions.test.ts
+```
+
+---
+
+## 9. 关键环境变量（速查）
+
+生产（写在 **Hosting 进程**）：
+
+```bash
+EAP_DEPLOYMENT_CONTEXT=server
+EAP_PREINSTALL_ROOT=/data/eap/preinstall
+EAP_TOOL_GATEWAY_TRANSPORT=mcp
+EAP_RUNTIME_STORAGE_PROFILE=integration   # 或 production
+FOUNDATION_SERVICE_URL=...
+```
+
+本地（`eap chat` / createDevRuntime，常由 `.env.local` 注入）：
+
+```bash
+EAP_DEPLOYMENT_CONTEXT=dev
+EAP_PREINSTALL_ROOT=/abs/path/to/preinstall   # 或 Agent 工程内预装树
+EAP_RUNTIME_STORAGE_PROFILE=dev
+EAP_TOOL_EXECUTION_MODE=mock                 # 或 mcp
+# OPENAI_BASE_URL / OPENAI_API_KEY / EAP_DEFAULT_MODEL
+```
+
+完整表：[`docs/governance/governance-env-config.md`](../docs/governance/governance-env-config.md)。
+
+---
+
+## 10. Tool L1 demo（可选）
+
+验证 Tool 编排层（非完整 Agent Graph）：
+
+| 模式 | 命令 |
+|------|------|
+| server | `cd examples/demo-tool && npm run demo:server` |
+| desktop | `cd examples/demo-tool && npm run demo:desktop` |
+
+步骤与排错：[`docs/workflows/tool-demo-l1-guide.md`](../docs/workflows/tool-demo-l1-guide.md)。
+
+---
+
+## 11. 发布到公司私有 npm（可选）
+
+私服：`https://maven.gtcloud.cn/repository/npm-local/`（模板 [`.npmrc.example`](./.npmrc.example)）。
+
+> `@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中作为命令直接执行。
+
+```bash
+cp .npmrc.example .npmrc
+npm login --registry https://maven.gtcloud.cn/repository/npm-local/
+
+# 1) 先发 @eap/contracts（version 改为目标版，如 0.0.1）
+cd ../eap-contracts && cp .npmrc.example .npmrc
+pnpm run build && npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
+
+# 2) runtime：package.json 中 @eap/contracts 改为版本号（勿再用 file:）
+cd ../runtime && pnpm run build
+npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
+```
+
+含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。
+
+---
+
+## 12. 文档索引
+
+| 文档 | 用途 |
+|------|------|
+| [runtime-sdk-integration-final.md](../docs/contracts/runtime-sdk-integration-final.md) | SDK API、SSE、接入验收 |
+| [preload-hosting-runtime-contract.md](../docs/contracts/preload-hosting-runtime-contract.md) | Hosting↔Runtime 预装目录契约 |
+| [runtime-preinstall-load-flow.md](../docs/contracts/runtime-preinstall-load-flow.md) | 解压→读盘→首/次请求完整流转 |
+| [governance-env-config.md](../docs/governance/governance-env-config.md) | 全平台环境变量与存储 profile |
+| [local-agent-dev-loop.md](../docs/workflows/local-agent-dev-loop.md) | dev-tools + runtime 本地闭环 |
+| [session-message-checkpoint-alignment.md](../docs/architecture/session-message-checkpoint-alignment.md) | Session/Message/Checkpoint 关系 |
+| [db-storage-verification.md](../docs/verification/db-storage-verification.md) | PG/Redis 存储核验 |
+| [tool-execution.md](../docs/contracts/tool-execution.md) | Tool 执行契约 |
+| [tool-demo-l1-guide.md](../docs/workflows/tool-demo-l1-guide.md) | Tool L1 demo |
+| [platform-four-services-overview.md](../docs/architecture/platform-four-services-overview.md) | 四服务总览（含预装目录语义） |
+| [implementation-status.md](../docs/status/implementation-status.md) | 实现进度 |
+| [module-status-and-backlog.md §7.7](../docs/status/module-status-and-backlog.md) | Runtime backlog |
+| [`fixtures/eap-preinstall-sample/`](../fixtures/eap-preinstall-sample/) | 预装契约样例树 |
+| [`fixtures/eap-local-test/`](../fixtures/eap-local-test/) | 本地 chat + 存储闭环 |

package/dist/api/handlers/index.d.ts

@@ -0,0 +1,3 @@
+export { InvokeOrchestrator, type InvokeOrchestratorDeps, } from './invoke.handler.js';
+export { StreamOrchestrator, type StreamOrchestratorDeps, } from './stream.handler.js';
+export { MessagesOrchestrator, type MessagesOrchestratorDeps, } from './messages.handler.js';

package/dist/api/handlers/index.js

@@ -0,0 +1,4 @@
+// API Handlers barrel export
+export { InvokeOrchestrator, } from './invoke.handler.js';
+export { StreamOrchestrator, } from './stream.handler.js';
+export { MessagesOrchestrator, } from './messages.handler.js';

package/dist/api/handlers/invoke.handler.d.ts

@@ -0,0 +1,77 @@
+/**
+ * InvokeOrchestrator — 同步调用编排器
+ *
+ * 实现 POST /api/v1/agents/:agentCode/invoke 的核心编排逻辑：
+ * 1. 检查 Session 日预算（SessionBudgetChecker）
+ * 2. 解析/创建 Session 上下文（SessionContextService）
+ * 3. 创建 Task（TaskService）
+ * 4. 启动 Task（pending → running）
+ * 5. 构建/执行 Graph（IStateGraphEngine）
+ * 6. 记录 Token 消耗（TokenStatsService + TaskService）
+ * 7. 完成 Task（running → success）
+ * 8. 返回 InvokeResponse
+ *
+ * @see design.md §1.5 /stream 内部执行逻辑
+ * @see requirements.md Requirement 11 AC1-AC2
+ */
+import type { SessionContextService } from '../../session/session-context.service.js';
+import type { MessageService } from '../../session/message.service.js';
+import type { TaskService } from '../../task/task.service.js';
+import type { IStateGraphEngine } from '../../graph/contracts/state-graph.contract.js';
+import type { TokenStatsService } from '../../token/token-stats.service.js';
+import type { TokenBudgetGuard } from '../../token/token-budget-guard.js';
+import type { SessionBudgetChecker } from '../../token/session-budget-checker.js';
+import type { InvokeRequest, InvokeResponse } from '../routes/agent.routes.js';
+import type { GraphLoader } from '../../registry/graph-loader.js';
+import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
+import type { ITraceCollector } from '../../contracts/trace-collector.js';
+/**
+ * InvokeOrchestrator 构造器依赖
+ */
+export interface InvokeOrchestratorDeps {
+    sessionContextService: SessionContextService;
+    taskService: TaskService;
+    graphEngine: IStateGraphEngine;
+    tokenStatsService: TokenStatsService;
+    tokenBudgetGuard: TokenBudgetGuard;
+    sessionBudgetChecker: SessionBudgetChecker;
+    /** 多轮短期记忆写回；未注入时跳过持久化（仅不推荐的测试桩） */
+    messageService?: MessageService;
+    /** 从 Registry 加载 Graph DSL，未提供时使用内置默认图 */
+    graphLoader?: GraphLoader;
+    /** 用于判断 session Checkpoint 是否已有历史，避免双重 append */
+    checkpointSaver?: ICheckpointSaver;
+    traceCollector?: ITraceCollector;
+}
+/**
+ * InvokeOrchestrator — 同步调用全流程编排
+ *
+ * 协调 SessionContextService、TaskService、IStateGraphEngine、TokenStatsService
+ * 等服务完成一次同步 Agent 调用的完整生命周期。
+ */
+export declare class InvokeOrchestrator {
+    private readonly sessionContextService;
+    private readonly taskService;
+    private readonly graphEngine;
+    private readonly tokenStatsService;
+    private readonly tokenBudgetGuard;
+    private readonly sessionBudgetChecker;
+    private readonly messageService?;
+    private readonly graphLoader?;
+    private readonly checkpointSaver?;
+    private readonly traceCollector?;
+    constructor(deps: InvokeOrchestratorDeps);
+    /**
+     * 执行同步调用编排
+     *
+     * @param req - 解析后的调用请求
+     * @param userId - 经认证的用户 ID
+     * @returns 完整的 InvokeResponse（含 taskId, sessionId, output, tokenUsage, duration, status）
+     */
+    execute(req: InvokeRequest, userId: string): Promise<InvokeResponse>;
+    private buildResponse;
+    private buildErrorResponse;
+    private isTimeoutError;
+}
+/** @deprecated 请直接从 `graph/hitl/hitl-handler` 导入；此处保留 re-export 兼容旧测试引用 */
+export { unwrapHitlPaused } from '../../graph/hitl/hitl-handler.js';