@gt-fe/eap-runtime

v0.0.28

Published

3 days ago

Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化

0High
0Medium
0Low

ikeukenhof

golduck01

ivapor

@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-09-14 | 会话滑动窗口压缩默认开；EAP_RUNTIME_COMPRESSION=0 关闭 | | 2026-09-08 | docs/TODO.md 改为主路径状态（已落地 / 不在本包），不是排期 | | 2026-08-29 | 待办收口：docs/TODO.md。此后压缩已挂主路径（默认关）；窗口展示不在 Runtime；Gateway 须 tools/list | | 2026-08-24 | 0.0.10：官方 Skill / Harness、ForkParams、对话详情、存储两档。依赖 @eap/[email protected]。详见 CHANGELOG.md | | 2026-08-21 | 0.0.9：Gateway /mcp JSON-RPC 补 Accept；tools/call 透传工具版本。详见 CHANGELOG.md | | 2026-08-19 | 0.0.8：Skill 子图 SSE 闭环；ExecuteParams.traceId；tool.called 改为 Tool 节点开始执行。依赖 @eap/[email protected]。详见 CHANGELOG.md | | 2026-08-18 | 0.0.7：DevHttpExecutor、mode=mcp 缺配置失败、HTTP 出站语义与 Gateway 共用 @eap/[email protected] | | 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 §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/ | | Runtime DDL | docs/ddl.md | | SDK 集成手册 | docs/contracts/runtime-sdk-integration-final.md | | 环境变量总表 | docs/governance/governance-env-config.md | | 预装联调契约 | docs/contracts/preload-hosting-runtime-contract.md | | 预装加载与请求流转 | docs/contracts/runtime-preinstall-load-flow.md | | Runtime 主路径状态 | docs/TODO.md | | 技能 FS 待办 | docs/TODO-skill-fs.md | | 本地 Agent 闭环 | 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）

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, taskId, traceId, overrides: { /* … */ } });

细则与字段表见 docs/contracts/runtime-sdk-integration-final.md。

3.2 `createDevRuntime()`（dev-tools / 本地）

eap chat（默认 SDK 嵌入）与本地测试使用的装配工厂：LLM、Tool、Governance、存储、GraphLoader 一次配齐，无需起 Runtime HTTP。

import { createDevRuntime } from '@eap/runtime';

const rt = createDevRuntime();
const result = await rt.agentRuntime.execute({ /* … */ });

诊断字段见返回值 diagnostics（deploymentContext、tool 模式、storage profile 等）。

3.3 与 Hosting / dev-tools 的关系

开发者本机                          生产
─────────                          ────
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。

4. Graph 执行

引擎：LangGraphAdapter（IStateGraphEngine）将平台 Graph DSL 编成 LangGraph StateGraph
节点：llm、tool、subgraph（Skill）、并行/条件边、HITL 等待
Skill 子图：节点可带内嵌 subgraphDsl；或仅 skillId，从 state.skillDefinitions 取 workflow 执行。技能正文用短目录 + read_file，不灌 system
权限：子图执行前 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
Runtime 清单：.kiro/specs/runtime-requirements-for-vendor.md
样例预装根：fixtures/eap-preinstall-sample/

预装相关环境变量（默认多为关闭）

| 变量 | 默认 | 含义 | |------|------|------| | EAP_PREINSTALL_ROOT | — | 预装根；也可用 GraphLoader({ preinstallRoot }) | | EAP_PRELOAD_REQUIRE_READY | 关 | 缺 .ready → runtime.preload.missing | | EAP_PRELOAD_REQUIRE_CHECKSUM | 关 | snapshot 须含 sha256 或 artifacts。开启时摘要不匹配抛 RUNTIME_PRELOAD_PACKAGE_CORRUPT；未开仍 warn、不中断 | | 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）。

改样例后重算摘要：

node ../fixtures/eap-preinstall-sample/scripts/seal-snapshot.mjs

6. 持久化与存储 Profile

assembleRuntimeStorage() 按 profile 与环境变量选择介质。表结构见 docs/ddl.md。

| 条件 | Checkpoint | Message / LLM 回合 | Token 配额 | |------|------------|-------------------|------------| | EAP_RUNTIME_STORAGE_PROFILE=dev，或未设 profile 且未配置数据库与 Redis | 文件（默认 .eap/checkpoints） | 文件 | 进程内，不落库 | | test / integration / production，或未设 profile 但已配置 DATABASE_URL/DB_* 或 REDIS_* | Redis + PostgreSQL | PostgreSQL | PostgreSQL token_budgets |

后一路径缺少数据库或 Redis 时抛错。显式 dev 时即使已配置数据库仍使用文件。

仅文件路径使用的目录变量：EAP_CHECKPOINT_DIR、EAP_SESSION_DIR、EAP_MESSAGE_DIR（可用 EAP_DATA_DIR 作为根目录）。

环境变量总表：governance-env-config.md §9。

7. Tool 与 LLM

| 模式 | 何时 | 说明 | |------|------|------| | mcp / DevToolExecutor | 本地默认（dev + mcp） | 按清单直连 MCP / HTTP / 本机 code | | 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、examples/demo-tool/
执行契约：docs/contracts/tool-execution.md

LLM：EchoLLMProvider（无配置时的默认实现）→ HttpLLMProvider（OPENAI_*）→ RoutingLLMProvider；默认模型可通过 EAP_DEFAULT_MODEL 指定。

8. 快速开始

须先构建兄弟包 @eap/contracts。本仓推荐 pnpm。

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

预装样例单测：

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 进程）：

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 注入）：

EAP_DEPLOYMENT_CONTEXT=dev
EAP_PREINSTALL_ROOT=/abs/path/to/preinstall   # 或 Agent 工程内预装树
EAP_RUNTIME_STORAGE_PROFILE=dev
EAP_TOOL_EXECUTION_MODE=mcp                  # 仅 createDevRuntime / eap chat；Hosting 的 TOOL_EXECUTION_MODE 不读
# OPENAI_BASE_URL / OPENAI_API_KEY / EAP_DEFAULT_MODEL

完整表：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。

11. 发布 npm 包

升版、CHANGELOG、git commit / git push 不在脚本里，先做完再跑脚本。脚本只做构建、发布、核对 registry 上的版本号。

| 脚本 | 包 | registry | |------|----|----------| | scripts/publish-intranet.sh | @eap/runtime | Nexus https://maven.gtcloud.cn/repository/npm-local/ | | scripts/publish-public.sh | @gt-fe/eap-runtime | npmjs。临时目录改名；dist 里 @eap/contracts 改为 @gt-fe/eap-contracts。不改源码 package.json |

# 登录（一次性）
cp .npmrc.example .npmrc
npm login --registry https://maven.gtcloud.cn/repository/npm-local/
npm login --registry https://registry.npmjs.org/

./scripts/publish-intranet.sh
./scripts/publish-public.sh

不要在源码目录对 npmjs 执行 npm publish（publishConfig 指向 Nexus；公网 dist 必须改写 contracts）。含 _authToken 的 .npmrc 已 gitignore，勿提交凭证。@eap:registry=... 须写入 .npmrc 文件，不可在 shell 中当命令执行。

UAT Hosting 吃公网包：把 @eap/runtime 指到 npm:@gt-fe/eap-runtime@<本版> 后重建镜像。

12. 文档索引

| 文档 | 用途 | |------|------| | runtime-sdk-integration-final.md | SDK API、SSE、接入验收 | | preload-hosting-runtime-contract.md | Hosting↔Runtime 预装目录契约 | | runtime-preinstall-load-flow.md | 解压→读盘→首/次请求完整流转 | | governance-env-config.md | 全平台环境变量与存储 profile | | local-agent-dev-loop.md | dev-tools + runtime 本地闭环 | | session-message-checkpoint-alignment.md | Session/Message/Checkpoint 关系 | | db-storage-verification.md | PG/Redis 存储核验 | | tool-execution.md | Tool 执行契约 | | tool-demo-l1-guide.md | Tool L1 demo | | platform-four-services-overview.md | 四服务总览（含预装目录语义） | | implementation-status.md | 实现进度 | | module-status-and-backlog.md §7.7 | Runtime backlog | | fixtures/eap-preinstall-sample/ | 预装契约样例树 | | fixtures/eap-local-test/ | 本地 chat + 存储闭环 |