@gt-fe/eap-cli 0.2.19 → 0.2.21

package/README.md

@@ -1,304 +1,304 @@
-# @gt-fe/eap-cli
-
-`@gt-fe/eap-cli` 是 EAP 单 Agent 项目的命令行入口。它负责命令参数、登录交互、终端输出、Playground 和聊天体验；项目发现、依赖安装、Runtime 目录物化、服务创建、打包与验包统一委托给 `@gt-fe/eap-sdk`。
-
-如果你是第一次开发 Agent，请先阅读 [场景一：常规 Agent 开发手册](../../docs/developer-guide.md)。本文是 CLI 命令和选项的详细参考。
-
-跨模块的开发、配置、交付和排障入口见 [dev-tools 文档](../../docs/README.md)。
-
-## 安装
-
-```bash
-npm install -g @gt-fe/eap-cli
-eap --help
-```
-
-使用 npm 私服时，在 `~/.npmrc` 中配置：
-
-```ini
-@gt-fe:registry=https://npm.your-company.com/
-```
-
-## 项目结构
-
-一个项目只包含一个 Agent：
-
-```text
-<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` 准备本地项目，最后进入项目目录同步平台配置：
-
-```bash
-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`）。
-
-仅需本地模板时，可以直接创建：
-
-```bash
-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 的完整流程：
-
-```bash
-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`
-
-```bash
-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。
-
-本地资源按以下约定发现：
-
-```text
-tools/<code>/toolset.manifest.json
-skills/<code>/SKILL.md
-```
-
-如果同一 code 同时存在本地目录和 Registry 锁定记录，命令会报冲突，不会隐式覆盖。
-
-### `eap uninstall`
-
-```bash
-eap uninstall echo-tool
-eap uninstall search-tool --type tool
-```
-
-命令根据当前项目的 `eap.lock.yaml` 和本地目录自动识别资源来源，不需要 `--root`。卸载会清理对应的本地目录或 `.eap/remote` 缓存、Agent Manifest 引用和锁定记录；`--type` 仅在同一 code 被识别为多种资源类型时使用。
-
-### `eap validate`
-
-```bash
-eap validate
-eap validate --strict
-```
-
-严格模式把 warning 也视为失败。校验不会修复依赖，也不会生成 Runtime 目录。
-
-### `eap dev`
-
-```bash
-eap dev                    # 默认监听 0.0.0.0:3000
-eap dev 8080               # 指定本地服务端口
-eap dev --tool-mode mcp
-eap dev --no-ui
-eap dev --ui-port 5174
-```
-
-启动顺序：
-
-```text
-发现并校验当前项目
-→ 根据 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`
-
-```bash
-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`
-
-```bash
-eap package
-eap package --output ./dist/sales-assistant.tar.gz
-eap package --target standalone --output ./.eap/runtime
-```
-
-交互式执行时会先选择使用当前 `agent.manifest.json` 版本，或更新版本号；选择更新后会先写回本地 manifest，再生成部署包或 standalone Runtime。非交互环境默认使用当前版本。
-
-默认输出：
-
-```text
-.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 文档](../../docs/README.md#sha-256-摘要约定)。
-
-包根目录直接包含物化后的 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`
-
-```bash
-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`。
-
-## 登录与配置
-
-### 登录
-
-```bash
-eap login                              # 默认 CAS 浏览器登录
-eap login --token <jwt>                # 直接提供 Token（校验后登录）
-eap login --cas-port 3210              # 指定本地回调端口
-eap logout
-```
-
-当前用户身份、角色、权限和平台 Token 统一保存在：
-
-```text
-~/.eap/config.json
-```
-
-可使用 `EAP_CONFIG_DIR` 修改目录。登录状态只有一份，不随 CLI profile 或 Runtime storage profile 切换；`EAP_TOKEN` 可以临时覆盖已保存 Token。
-
-### 全局配置
-
-```bash
-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` 为准。
+# @gt-fe/eap-cli
+
+`@gt-fe/eap-cli` 是 EAP 单 Agent 项目的命令行入口。它负责命令参数、登录交互、终端输出、Playground 和聊天体验；项目发现、依赖安装、Runtime 目录物化、服务创建、打包与验包统一委托给 `@gt-fe/eap-sdk`。
+
+如果你是第一次开发 Agent，请先阅读 [场景一：常规 Agent 开发手册](../../docs/developer-guide.md)。本文是 CLI 命令和选项的详细参考。
+
+跨模块的开发、配置、交付和排障入口见 [dev-tools 文档](../../docs/README.md)。
+
+## 安装
+
+```bash
+npm install -g @gt-fe/eap-cli
+eap --help
+```
+
+使用 npm 私服时，在 `~/.npmrc` 中配置：
+
+```ini
+@gt-fe:registry=https://npm.your-company.com/
+```
+
+## 项目结构
+
+一个项目只包含一个 Agent：
+
+```text
+<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` 准备本地项目，最后进入项目目录同步平台配置：
+
+```bash
+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`）。
+
+仅需本地模板时，可以直接创建：
+
+```bash
+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 的完整流程：
+
+```bash
+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`
+
+```bash
+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。
+
+本地资源按以下约定发现：
+
+```text
+tools/<code>/toolset.manifest.json
+skills/<code>/SKILL.md
+```
+
+如果同一 code 同时存在本地目录和 Registry 锁定记录，命令会报冲突，不会隐式覆盖。
+
+### `eap uninstall`
+
+```bash
+eap uninstall echo-tool
+eap uninstall search-tool --type tool
+```
+
+命令根据当前项目的 `eap.lock.yaml` 和本地目录自动识别资源来源，不需要 `--root`。卸载会清理对应的本地目录或 `.eap/remote` 缓存、Agent Manifest 引用和锁定记录；`--type` 仅在同一 code 被识别为多种资源类型时使用。
+
+### `eap validate`
+
+```bash
+eap validate
+eap validate --strict
+```
+
+严格模式把 warning 也视为失败。校验不会修复依赖，也不会生成 Runtime 目录。
+
+### `eap dev`
+
+```bash
+eap dev                    # 默认监听 0.0.0.0:3000
+eap dev 8080               # 指定本地服务端口
+eap dev --tool-mode mcp
+eap dev --no-ui
+eap dev --ui-port 5174
+```
+
+启动顺序：
+
+```text
+发现并校验当前项目
+→ 根据 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`
+
+```bash
+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`
+
+```bash
+eap package
+eap package --output ./dist/sales-assistant.tar.gz
+eap package --target standalone --output ./.eap/runtime
+```
+
+交互式执行时会先选择使用当前 `agent.manifest.json` 版本，或更新版本号；选择更新后会先写回本地 manifest，再生成部署包或 standalone Runtime。非交互环境默认使用当前版本。
+
+默认输出：
+
+```text
+.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 文档](../../docs/README.md#sha-256-摘要约定)。
+
+包根目录直接包含物化后的 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`
+
+```bash
+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`。
+
+## 登录与配置
+
+### 登录
+
+```bash
+eap login                              # 默认 CAS 浏览器登录
+eap login --token <jwt>                # 直接提供 Token（校验后登录）
+eap login --cas-port 3210              # 指定本地回调端口
+eap logout
+```
+
+当前用户身份、角色、权限和平台 Token 统一保存在：
+
+```text
+~/.eap/config.json
+```
+
+可使用 `EAP_CONFIG_DIR` 修改目录。登录状态只有一份，不随 CLI profile 或 Runtime storage profile 切换；`EAP_TOKEN` 可以临时覆盖已保存 Token。
+
+### 全局配置
+
+```bash
+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` 为准。