@eevee/cli

@eevee/cli 是 eevee MCP 服务的业务化命令行客户端和 Agent Skill 管理工具。公开命令采用稳定 <group> <action> 规范；也可以继续使用完整 MCP 能力（tools/resources/prompts/request/notify）。CLI 可直接给 Codex、Claude Code 或其他终端 Agent 使用，也适合人工排查 eevee 数据。

运行时零依赖，只需要 Node.js 20.4+。

安装

本地开发或全局启用：

cd eevee-cli
npm install
npm run build
npm link           # 同时提供 eevee 和 eevee-cli 命令

已发布后从 npm 安装：

npm install -g @eevee/cli@latest

从本地仓库目录全局安装：

npm install -g .

配置服务器地址和 token

eevee config set --url http://127.0.0.1:10001/mcp
eevee config set --token <your-user-token>
eevee ping

也可以一次写入：

eevee config set \
  --url http://127.0.0.1:10001/mcp \
  --token 00000000-0000-4000-8000-000000000001

默认配置文件是 ~/.eevee-cli/config.json，权限为 0600。可用 EEVEE_CLI_CONFIG=/path/config.json 改变位置。

优先级：

1. 命令行：--url / --token
2. 环境：EEVEE_MCP_URL / EEVEE_TOKEN
3. 持久配置：~/.eevee-cli/config.json
4. URL 默认：http://127.0.0.1:10001/mcp

查看有效配置时 token 默认遮蔽；确认原始值时使用 --reveal：

eevee config show
eevee config show --reveal
eevee config get token --reveal
eevee config unset --token

不要把真实 token 提交到代码仓库。需要更换时可调用服务端 /api/v1/auth/reset-token 后重新执行 config set。

命令总览

| 命令 | 说明 | |---|---| | eevee <group> <action> | 推荐：执行 project、version、term、translation 等约 50 个业务动作 | | eevee business / eevee -h | 查看全部业务命令；-h 会列全协议命令 | | eevee <group> <action> --help | 查看该动作的 path/query/body 参数和类型 | | eevee config show/set/get/unset/path | 管理服务器地址和用户 token | | eevee doctor | 校验配置、MCP 连接、tools/list 和已装 Skill | | eevee ping | 完成完整 MCP initialize 握手并调用 ping | | eevee tools list/docs/call | 列出工具、展示详细用法、调用 MCP tool | | eevee resources ... | list/templates/read/subscribe/unsubscribe | | eevee prompts ... | list/get | | eevee request <method> | 调用任意标准 MCP JSON-RPC method | | eevee notify <method> | 发送 JSON-RPC notification | | eevee skills install/update/... | 安装内置 Agent Skill 到 Claude/Codex/global 目录 | | eevee lint [files...] | 本地国际化检查；eslint-plugin-eevee/no-created 的 CLI 迁移版 |

联网命令均支持临时覆盖：

eevee --url https://staging.example.com/mcp \
      --token <token> \
      --timeout 30000 \
      ping

本地国际化检查

eevee lint 把 eslint-plugin-eevee 的 no-created 规则迁移为本地检查器。Web 适配器直接解析 TypeScript AST，支持 .ts、.tsx、.js、.jsx、.mjs 和 .cjs，不依赖目标项目安装 ESLint：

eevee lint
eevee lint apps/gaia/src
eevee lint --staged
eevee lint --source changed
eevee lint --language web --json

检查配置优先读取 .eevee-lint.json、.eeveerc.json，然后读取 package.json 的 eevee.lint：

{
  "eevee": {
    "lint": {
      "refresh": {
        "config": "intl.download.json"
      },
      "languages": {
        "web": {
          "enabled": true,
          "root": ".",
          "intlConfig": "intl.json",
          "includes": ["apps/**/*.{ts,tsx,js,jsx}"],
          "excludes": ["**/*.test.*", "**/mock/**"],
          "excludeAscii": true,
          "tagMatchMap": {
            "apps/gaia/**/*": ["gaia"],
            "apps/sso/**/*": ["sso"]
          },
          "excludeProperties": ["title", "description"],
          "excludeTrack": true
        },
        "java": {
          "enabled": true,
          "root": ".",
          "intlConfig": ".eevee/intl.json",
          "includes": ["*/src/main/java/**/*.java"],
          "excludes": ["**/src/test/**", "**/generated/**"],
          "tagMatchMap": {
            "*/src/main/java/**/*": ["server"]
          },
          "localeMethods": ["getLocaleMessage", "tryLocaleMessage", "getMessage"],
          "checkHardcoded": true,
          "excludeMethods": ["trace", "debug", "info", "warn", "error"]
        }
      }
    }
  }
}

intlConfig 复用旧插件的 intl.json 结构；CLI 只读取 outPaths 下的 zh-CN*.json 作为平台词条。 excludePropertys 和 execludeTrack 这两个旧拼写继续兼容，推荐新配置使用上面的规范拼写。

eevee lint 在检查前强制同步一次平台词条快照，下载完成后再读取 intlConfig 指向的本地 JSON。 refresh.config 指向 eevee intl download 使用的目标数组配置；不配置时默认读取项目 package.json 的 eevee.intl。

同步失败、平台返回 0 词条、本地词条文件解析失败，都会直接阻断检查；不会退回旧快照，也不会提供 --no-refresh 旁路。词条同步成功但代码引用的 key 未登记时，诊断为 unregistered，退出码同样是 1。

# 使用独立下载目标配置；同步仍然强制执行
eevee lint --refresh-config intl.download.json

提交前推荐使用：

eevee lint --staged

发现问题退出码为 1。--json 输出 {ok:true,data} envelope，其中 data.passed=false 表示检查执行成功但存在诊断； 配置或执行失败仍是 {ok:false}。每条诊断包含 code、精确位置、原文、中文说明和 hint：

• missing-intl：文案没有接入国际化；
• tag-mismatch：词条存在，但不属于当前文件配置的标签；
• unregistered：词条不在当前平台数据中。

当前不开启源码自动修复。改写文案需要选择词条 key、补充导入并确认运行时 API，自动改写容易产生语义错误； 因此诊断只输出确定性建议，--fix 作为保留参数。后续只有在能生成稳定 key 且不影响导入/类型/运行时行为时， 才应把对应诊断标记为 fixable=true。

Java 后端项目接入

Java 适配器解析 .java 文件，适合 Spring Boot 后端仓库：

• 校验 LocaleHandler.getLocaleMessage(...)、tryLocaleMessage(...)、MessageSource.getMessage(...) 第一参数里的直写字符串是否登记到配置的 EEVEE tag；
• 检查 Java 字符串字面量中的硬编码中文；
• 默认排除日志方法（trace/debug/info/warn/error 等）、单测断言和注解描述；
• 默认排除 **/src/test/** 和 **/generated/**。

后端仓库无 package.json 时，推荐在仓库根目录放 .eevee-lint.json。完整结构如下：

{
  "refresh": {
    "config": ".eevee/download.json"
  },
  "languages": {
    "web": { "enabled": false },
    "java": {
      "enabled": true,
      "root": ".",
      "intlConfig": ".eevee/intl.json",
      "includes": ["*/src/main/java/**/*.java"],
      "excludes": ["**/src/test/**", "**/generated/**"],
      "tagMatchMap": {
        "*/src/main/java/**/*": ["server"]
      },
      "checkHardcoded": true
    }
  }
}

.eevee/intl.json 只负责告诉检查器去哪里读快照：

{ "outPaths": [{ "path": "locales" }] }

.eevee/download.json 使用 eevee intl download 的目标数组格式：

[
  {
    "outPath": ".eevee/locales",
    "format": "json",
    "languages": { "zh-CN": "zh-CN" },
    "projects": [{ "projectId": 1, "tags": [123] }]
  }
]

把 projectId 和 tag ID 换成后端词条项目实际值。提交检测推荐在 Git pre-commit 中执行：

npx @eevee/cli lint --staged --language java

Business command layer

Business commands 是主要接口，命名规范固定为 <group> <action>。它把底层 call_api_operation 封装成语义稳定、参数有类型的命令，不需要手工查找 operation_id：

# 看全部领域和命令
eevee business

# Standard syntax
eevee project list
eevee project create --name Demo --locales zh-CN,en-US
eevee project detail 12
eevee translation set-content --id 12 --term-id 34 --locale zh-CN --content 你好
eevee project delete 12 --yes

支持的域包括：project/version/term/translation/tag-group/tag/permission/log/profile/config/user。完整矩阵直接在 eevee -h 中列出。每个动作的完整 flag、位置说明、类型和必填状态用 --help 查看：

eevee term create --help
eevee translation assign-translators --help

命令路由只接受 <group> <action>；中文内容只用于说明和描述，不再参与命令解析。

输出约定：

• human 输出会解开 REST {status,data,msg} 包裹，列表渲染成表格；
• --json 输出稳定的 {ok,data}；
• --raw 输出完整 MCP CallToolResult；
• 所有 delete/clear 命令必须显式加 --yes；
• 联网业务命令同样可加 --url、--token 和 --timeout。

内置 MCP 工具详解

用权威列表检查服务器当前暴露的全部 tools：

eevee tools list
eevee tools list --raw
eevee tools list --json

每个工具的实时 schema 和固定工作流说明都可以离线式查看：

eevee tools docs [tool-name]

1. list_api_operations：发现 API

用途：从运行时 Swagger/OpenAPI 目录搜索 operation_id、HTTP 方法、路径、参数位置和摘要。

常用筛选：

eevee tools call list_api_operations '{"method":"GET","search":"terms","limit":20}'
eevee tools call list_api_operations '{"tag":"项目"}'
eevee tools call list_api_operations '{"search":"translation status"}'

适用场景：

• 不知道某个业务动作对应哪个接口；
• 需要 operation_id；
• 需要按项目、版本、词条、翻译、标签、权限、日志等关键词探索接口。

2. get_api_operation：读取契约

用途：获取单个操作的 path/query/header 参数和 application/json body schema。

eevee tools call get_api_operation '{"operation_id":"<operation-id>"}'

调用写操作前必须先读契约，确认：

• 哪些值属于 parameters.path；
• 哪些值属于 parameters.query；
• body 的必填字段和类型；
• 是否不支持通过 MCP 直接上传 multipart 文件。

3. call_api_operation：执行 API

用途：以当前 token 用户身份回环调用 REST API。服务端会继续执行原有角色权限、登录态校验和审计逻辑。

读示例：

eevee tools call call_api_operation \
  '{"operation_id":"ProjectsController_list","parameters":{}}'

带路径参数：

eevee tools call call_api_operation \
  '{"operation_id":"ProjectsController_detail","parameters":{"id":1}}'

带 query/body 的通用形态：

eevee tools call call_api_operation \
  '{"operation_id":"<write-operation-id>","parameters":{"id":1},"body":{"name":"example"}}'

大 payload 用文件。文件内容是 MCP arguments 的完整对象，必须包含 operation_id：

cat >/tmp/eevee-api-call.json <<'JSON'
{
  "operation_id": "<create-operation-id>",
  "body": {
    "name": "demo",
    "locales": ["zh-CN", "en-US"]
  }
}
JSON

eevee tools call call_api_operation --args @/tmp/eevee-api-call.json

安全约定：

• delete / clear / 批量更新 / 解冻等破坏性动作必须由用户明确要求后执行；
• 先读取详情或列表确认 ID，再修改；
• 结果的 isError=true 时停止并把真实错误反馈给用户；
• 不要伪造返回数据中不存在的字段或 ID。

标准 MCP 能力映射

CLI 每次请求都会按 Streamable HTTP 规范完成 initialize → notifications/initialized → 目标请求，并透传 Bearer token 与 Mcp-Session-Id。

Resources:

eevee resources list
eevee resources templates
eevee resources read eevee://example/resource
eevee resources subscribe eevee://example/resource
eevee resources unsubscribe eevee://example/resource

Prompts:

eevee prompts list
eevee prompts get code-review --args '{"language":"TypeScript"}'

任意标准 method/notification（包括 server 当前新增而 CLI 尚未包一层快捷方式的能力）:

eevee request logging/setLevel '{"level":"info"}'
eevee request completion/complete '{"ref":{"type":"ref/prompt","name":"review"},"argument":{"name":"code","value":"..."}}'
eevee notify notifications/cancelled '{"requestId":"<id>","reason":"user cancelled"}'

roots/list、sampling/createMessage、elicitation/create 属于 server 向 client 发起的回调方向。CLI 是一次性进程，不声明这些客户端 callback capability；因此不会向服务端误报支持。

输出格式：

• 默认 human-readable；tool text result 会原样打印；
• --raw 输出完整 MCP result；
• --json 输出 {ok:true,data:...} envelope。

Agent Skill 快速安装

仓库中已经内置 assets/skills/eevee-mcp/SKILL.md 和 reference.md。

默认复制到当前用户的 Codex + Claude 全局目录：

eevee skills install

实际路径：

• Codex: $CODEX_HOME/skills/eevee-mcp，默认 ~/.codex/skills/eevee-mcp
• Claude Code: $CLAUDE_CONFIG_DIR/skills/eevee-mcp，默认 ~/.claude/skills/eevee-mcp
• Universal/兼容 Agent Skills 实现: $EEVEE_AGENT_HOME/skills/eevee-mcp，默认 ~/.agents/skills/eevee-mcp

显式选择 agent：

eevee skills install codex,claude
eevee skills install codex
eevee skills install universal

复制到某个项目的 Claude/Codex 目录：

cd /path/to/repo
eevee skills install codex,claude --project .

复制到任意自定义 skills 根目录：

mkdir -p .agents/skills
eevee skills install universal --dir .agents/skills

强制刷新、预演和卸载：

eevee skills update
eevee skills install --dry-run
eevee skills uninstall --yes
eevee skills uninstall codex --global --yes
eevee skills uninstall claude --project . --yes

管理查询：

eevee skills list
eevee skills paths
eevee skills info

Claude/Codex 重启后加载名为 eevee-mcp 的 skill。Skill 内容指导 Agent 先 discover contract，再 call tool，并避免未授权的破坏性变更。

诊断与故障排查

eevee doctor

常见问题：

| 现象 | 处理 | |---|---| | 缺少 token | eevee config set --token ... 或设置 EEVEE_TOKEN | | ECONNREFUSED | 用 curl 确认 server 地址和端口，或修正 --url | | HTTP 401 | 用户 token 无效/冻结/已重置，重新设置 token | | method not found | 用 eevee tools list 确认 server capabilities | | 响应超时 | 提高 --timeout，检查网关对长连接/SSE 的限制 |

协议头使用 Authorization: Bearer <token>、Accept: application/json, text/event-stream、Content-Type: application/json 和协商后的 MCP-Protocol-Version。

开发

npm run build       # TypeScript 编译到 dist/src
npm run check       # build + Node.js test runner
npm run cli -- help # 本地调用 CLI
node dist/src/bin/cli.js doctor

单测覆盖 CLI 参数解析、配置持久化/遮蔽/覆盖、JSON 参数解析、MCP initialize/session/Bearer 握手，以及 skill 复制。