@gt-fe/eap-cli

@gt-fe/eap-cli 是 EAP 单 Agent 项目的命令行入口。它负责命令参数、登录交互、终端输出、Playground 和聊天体验；项目发现、依赖安装、Runtime 目录物化、服务创建、打包与验包统一委托给 @gt-fe/eap-sdk。

如果你是第一次开发 Agent，请先阅读 场景一：常规 Agent 开发手册。本文是 CLI 命令和选项的详细参考。

跨模块的开发、配置、交付和排障入口见 dev-tools 文档。

安装

npm install -g @gt-fe/eap-cli
eap --help

使用 npm 私服时，在 ~/.npmrc 中配置：

@gt-fe:registry=https://npm.your-company.com/

项目结构

一个项目只包含一个 Agent：

<project>/
├── agent.manifest.json
├── graph.json
├── eap.config.json
├── eap.lock.yaml
├── tools/<code>/...
├── skills/<code>/...
├── .eap/
│   ├── remote/
│   ├── runtime/agents/<agentCode>/<version>/preinstall/...
│   └── package/

开发者维护根级配置和本地 Tool/Skill；.eap/ 是 SDK/CLI 生成的缓存状态。CLI Runtime 默认读取 .eap/runtime，不直接读取项目源目录。eap.config.json 的 localToolDirectories / localSkillDirectories 可列出项目内外的资源父目录，模板默认分别是 ["./tools"] / ["./skills"]；其中直接子目录根部有 toolset.manifest.json 或 SKILL.md / skill.md 时会随 Runtime 一起物化。

Agent code 和版本来自根级 agent.manifest.json，因此 dev、chat、install 和 publish 都不接受 Agent code/version 选择参数。

创建与更新项目

正式开发主路径是先在开发者平台创建 Agent 源数据并取得 code，再用 eap create 准备本地项目，最后进入项目目录同步平台配置：

eap config platform.portalUrl https://portal.example
eap config platform.foundationServiceUrl https://service.example
eap login
eap create sales-assistant --template single-agent-with-tools
cd sales-assistant
eap init <agent-code> --version 1.0.0
eap install
eap validate

交互式终端里，向导默认值使用命令行已给出的项目名和 --template，不要一路回车就当成默认 ReAct。含 @gt-fe/eap-sdk 的模板会把依赖写成当前 SDK 版本范围（现在是 ^0.2.1）。

仅需本地模板时，可以直接创建：

eap create sales-assistant \
  --template single-agent-with-tools \
  --dir ./sales-assistant

内置模板：

| 模板 | 场景 | |---|---| | simple-flow | 固定步骤顺序执行 | | single-agent-with-tools | 单 Agent + ReAct Tool 调用 | | plan-and-execute | 规划后逐步执行 | | dag-workflow | 并行扇出后合并 | | agent-api-orchestration | 面向前端智能体页面的 Agent API 服务 |

所有模板都使用根级单 Agent 布局。工作流语义由 graph.json 定义，Agent Manifest 不包含 mode。包含 Tool 的模板自带本地、已锁定的 echo-tool。single-agent-with-tools 另默认锁定 http-weather。

常用开发流程

使用 Registry Tool/Skill 的完整流程：

eap login
eap install search-tool --type tool --version 1.2.0
eap install
eap validate --strict
eap dev
eap chat
eap package
eap publish

eap install <code> --type tool|skill --version <version> 下载一个精确版本的 Registry Tool 或 Skill，写入 .eap/remote，并更新根级 Manifest 与 eap.lock.yaml。不带资源参数时，eap install 根据锁文件恢复缺失的 Registry 缓存，同时从当前项目的 tools/<code> 或 skills/<code> 自动发现并刷新已声明本地 Tool/Skill 的版本和相对路径。开发锁不保存资源摘要，package 物化时才从实际入口文件计算。该命令自动从当前工作目录发现 Agent 项目，不需要 --root。

核心命令

| 命令 | 说明 | 主要 SDK API | |---|---|---| | eap init <code> [--version <version>] [--reset] | 同步 Portal Agent 信息并合并 Tool/Skill/Subagent 引用；--reset 经确认后清理 .eap/ 和 eap.lock.yaml 再全量重置资源；资源始终通过安装流程处理 | SDK Manifest/资源安装 API | | eap create [name] | 从内置模板创建本地 Agent 项目 | 模板复制 | | eap install [code] --type tool\|skill [--version <version>] | 带资源参数时安装 Registry 资源；省略版本时使用版本列表第一项；省略资源参数时同步缓存并刷新项目目录中的本地资源锁定记录 | installAgentResource() / installAgentDependencies() | | eap uninstall <code> | 自动识别本地或 Registry 资源，清理目录/缓存、Manifest 引用和锁记录 | uninstallAgentResource() | | eap validate | 校验源文件、Graph、锁文件和资源路径 | validateAgentProject() | | eap dev [port] | 物化 Runtime，启动本地 HTTP 服务和 Playground | prepareAgentRuntime() + createAgent() + startAgentHttpServer() | | eap chat | 物化 Runtime，进程内调用 Runtime 并在交互式终端聊天（需要 TTY） | prepareAgentRuntime() + createAgent() | | eap package | 生成确定性的单 Agent Runtime 部署包或 standalone Runtime 目录 | packageAgentProject() / packageStandaloneAgentProject() | | eap publish | 验包、上传包并回写唯一 Agent Version 的 artifact | readAgentPackage() |

eap install

eap install search-tool \
  --type tool \
  --version 1.2.0

• --type 仅支持 tool 和 skill。
• 必须指定精确版本。
• 需要当前平台登录 Token。
• 本地资源直接放在当前项目的 tools/<code> 或 skills/<code>；执行不带资源参数的 eap install 时自动刷新本地锁定记录，不需要额外安装参数。
• 单 Agent 物化流程暂不支持安装 Subagent。
• 交互式终端直接执行 eap install 时，可选择安装 Registry 资源或同步资源。
• 非交互环境中不带资源参数的 eap install 始终执行同步，适合 CI。

本地资源按以下约定发现：

tools/<code>/toolset.manifest.json
skills/<code>/SKILL.md

如果同一 code 同时存在本地目录和 Registry 锁定记录，命令会报冲突，不会隐式覆盖。

eap uninstall

eap uninstall echo-tool
eap uninstall search-tool --type tool

命令根据当前项目的 eap.lock.yaml 和本地目录自动识别资源来源，不需要 --root。卸载会清理对应的本地目录或 .eap/remote 缓存、Agent Manifest 引用和锁定记录；--type 仅在同一 code 被识别为多种资源类型时使用。

eap validate

eap validate
eap validate --strict

严格模式把 warning 也视为失败。校验不会修复依赖，也不会生成 Runtime 目录。

eap dev

eap dev                    # 默认监听 0.0.0.0:3000
eap dev 8080               # 指定本地服务端口
eap dev --tool-mode mcp
eap dev --no-ui
eap dev --ui-port 5174

启动顺序：

发现并校验当前项目
→ 根据 eap.lock.yaml 生成 .eap/runtime
→ 设置 EAP_PREINSTALL_ROOT
→ 创建 @gt-fe/eap-runtime
→ 启动 Agent HTTP 服务
→ 启动 Playground（默认）

eap dev 不是源码 watch 命令，也不会执行项目的 npm run dev。当前实现会在启动时重新生成 .eap/runtime；源文件变更后需要重新启动命令。CLI 不读取模板项目的 EAP_RUNTIME_ROOT，Runtime 路径保持在 .eap/runtime。

eap dev 开启本地会话持久化，会话和消息保存在 Runtime 根目录旁的 sessions 目录，默认是 .eap/sessions，不会进入部署包。Playground 启动时会自动恢复当前用户和 Agent 最近一次会话。

eap chat

eap chat
eap chat --tool-mode mcp
eap chat --restore
eap chat --session <session-id>
eap chat --invoke
eap chat --verbose
eap chat --no-color

本仓库里的 CLI 通过 workspace 使用仓库根目录 runtime/（npm 名 @gt-fe/eap-runtime）。全局 npm i -g 的 CLI 仍走私服 Runtime 版本，横幅可能显示 0.0.15。

eap chat 需要交互式终端（TTY），在 CLI 进程内通过 SDK 创建 Agent，不要求预先启动 eap dev。默认使用 Runtime stream；--invoke 切换为整包调用。任务结束后任务头带总耗时：┌─ ✓ Task … · 12.3s (12300ms)，失败同样（✗）。工具行 → 入参 来自 tool.called / tool.progress 的 arguments；← 出参 是工具返回。同一工具名并行多次（如多个 query_dataset_data）按 toolCallId 分行，各自保留入参。MCP 调用成功但业务正文报错（如数据集 999）仍显示 ✓，入参同样输出。--verbose 展开入参/出参 JSON。

聊天用户优先用 eap login 会话。本地没 login、也没起 Foundation 时，用调试身份（EAP_CHAT_USER / default-user + debug-token）。钥匙放工程 .env.local 的 OPENAI_API_KEY，不要写进 eap.config.json。默认创建新会话；使用 --restore 恢复最近一次会话，--session <session-id> 恢复指定会话，REPL 内 /new 或 /clear 新建会话。

REPL 内置命令：

| 命令 | 说明 | |---|---| | / | 输入后显示命令建议；↑↓ 移动高亮，Tab 或行末 → 补进输入框，Enter 执行 | | /help | 查看内置命令 | | /session | 查看当前会话 | | /history | 上下键选择当前用户、当前 Agent 的历史会话并继续对话 | | /new | 开始新对话 | | /clear | 清屏并开始新会话 | | /exit | 退出 |

聊天界面由 Ink 渲染。普通文本会直接发送给 Agent；以 / 开头时仍可像普通文本一样继续编辑，命令建议只显示在输入框下方，不会抢走输入焦点。Tab（或光标在行末时按 →）把高亮命令补进输入框，再 Enter 执行。Esc 会收起命令建议或返回历史会话列表；在主输入框连续按两次 Esc 才会退出聊天。

eap package

eap package
eap package --output ./dist/sales-assistant.tar.gz
eap package --target standalone --output ./.eap/runtime

交互式执行时会先选择使用当前 agent.manifest.json 版本，或更新版本号；选择更新后会先写回本地 manifest，再生成部署包或 standalone Runtime。非交互环境默认使用当前版本。

默认输出：

.eap/package/eap-agent-project-<code>-<version>.tar.gz
.eap/package/eap-agent-project-<code>-<version>.tar.gz.sha256

--target standalone 默认生成 .eap/runtime/agents/<code>/<version>/，供构建后的 dist/index.js 通过 createAgent({ runtimeRoot }) 启动；是否提供 HTTP 由 startAgentHttpServer() 决定，不生成 TAR.GZ。

eap-package.json.files[].digest 校验包内单个 Runtime 文件；旁边的 .sha256 校验整个 TAR.GZ。完整摘要约定见 dev-tools 文档。

包根目录直接包含物化后的 Agent 版本内容（例如 agent.manifest.json、graph.json、eap.config.json、eap.lock.yaml、preinstall/）和 eap-package.json。Registry 与本地 Tool/Skill 都位于 preinstall/，包内不会生成开发者分层资源目录。以下内容不会进入生产包：

• .eap/remote
• .eap/sessions
• checkpoint
• 其他开发缓存

eap publish

eap publish
eap publish --package ./dist/sales-assistant.tar.gz

publish 先调用 SDK 验证 TAR.GZ 包内容，上传对象存储后将返回地址回写到包内唯一 Agent Version。默认按当前项目 agent.manifest.json 的 code/version 读取 .eap/package/eap-agent-project-<code>-<version>.tar.gz。

登录与配置

登录

eap login                              # 默认 CAS 浏览器登录
eap login --token <jwt>                # 直接提供 Token（校验后登录）
eap login --cas-port 3210              # 指定本地回调端口
eap logout

当前用户身份、角色、权限和平台 Token 统一保存在：

~/.eap/config.json

可使用 EAP_CONFIG_DIR 修改目录。登录状态只有一份，不随 CLI profile 或 Runtime storage profile 切换；EAP_TOKEN 可以临时覆盖已保存 Token。

全局配置

eap config --list
eap config platform.portalUrl https://portal.example
eap config platform.foundationServiceUrl https://service.example
eap config profile --list
eap config profile dev --use

CLI profile 只用于平台地址等 CLI 配置覆盖，不改变当前登录用户。

项目配置

eap.config.json 保存平台端点和 Runtime 开发配置。SDK 在创建服务时将其映射到 Runtime 环境变量，其中：

• 顶层 version 必须严格等于当前安装的 @gt-fe/eap-sdk package version。
• 顶层 localToolDirectories、localSkillDirectories 可省略或为空数组；目录不存在、没有入口文件或入口内容不规范都不会在物化阶段报错。
• platform.portalUrl 映射为 EAP_PLATFORM_ENDPOINT。
• platform.foundationServiceUrl 映射为 FOUNDATION_SERVICE_URL。
• EAP_PREINSTALL_ROOT 始终指向当前 runtimeRoot，CLI 默认是 <project>/.eap/runtime。
• 当前用户 Token 映射为 EAP_DELEGATION_TOKEN。
• runtime.llm.models.<模型名>（仅 deploymentContext=dev）按模型映射网关。EAP_LLM_CONNECTIONS 只带 apiKeyEnv 引用，不含明文密钥。apiKey 支持 ${ENV_VAR}，密钥放 .env.local。未配钥匙时启动失败，不会掉进 Echo。

其他命令

| 命令 | 说明 | |---|---| | eap list <code> [--type agent|tool|skill] | 查看某个资源 code 的版本历史 | | eap info <code> | 查看 Agent/Tool/Skill 详情 | | eap doctor | 检查 Node、依赖和平台连通性 | | eap upgrade | 检查或升级 @gt-fe/eap-cli |

具体参数以 eap <command> --help 为准。