@eevee-ta/cli 0.1.0-beta.1

package/README.md

@@ -0,0 +1,492 @@
+# @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+。
+
+## 安装
+
+本地开发或全局启用：
+
+```bash
+cd eevee-cli
+npm install
+npm run build
+npm link           # 同时提供 eevee 和 eevee-cli 命令
+```
+
+已发布后从 npm 安装：
+
+```bash
+npm install -g @eevee/cli@latest
+```
+
+从本地仓库目录全局安装：
+
+```bash
+npm install -g .
+```
+
+## 配置服务器地址和 token
+
+```bash
+eevee config set --url http://127.0.0.1:10001/mcp
+eevee config set --token <your-user-token>
+eevee ping
+```
+
+也可以一次写入：
+
+```bash
+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`：
+
+```bash
+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 迁移版 |
+
+联网命令均支持临时覆盖：
+
+```bash
+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：
+
+```bash
+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`：
+
+```json
+{
+  "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`。
+
+```bash
+# 使用独立下载目标配置；同步仍然强制执行
+eevee lint --refresh-config intl.download.json
+```
+
+提交前推荐使用：
+
+```bash
+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`。完整结构如下：
+
+```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` 只负责告诉检查器去哪里读快照：
+
+```json
+{ "outPaths": [{ "path": "locales" }] }
+```
+
+`.eevee/download.json` 使用 `eevee intl download` 的目标数组格式：
+
+```json
+[
+  {
+    "outPath": ".eevee/locales",
+    "format": "json",
+    "languages": { "zh-CN": "zh-CN" },
+    "projects": [{ "projectId": 1, "tags": [123] }]
+  }
+]
+```
+
+把 `projectId` 和 tag ID 换成后端词条项目实际值。提交检测推荐在 Git `pre-commit` 中执行：
+
+```bash
+npx @eevee/cli lint --staged --language java
+```
+
+## Business command layer
+
+Business commands 是主要接口，命名规范固定为 `<group> <action>`。它把底层 `call_api_operation` 封装成语义稳定、参数有类型的命令，不需要手工查找 `operation_id`：
+
+```bash
+# 看全部领域和命令
+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` 查看：
+
+```bash
+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：
+
+```bash
+eevee tools list
+eevee tools list --raw
+eevee tools list --json
+```
+
+每个工具的实时 schema 和固定工作流说明都可以离线式查看：
+
+```bash
+eevee tools docs [tool-name]
+```
+
+### 1. list_api_operations：发现 API
+
+用途：从运行时 Swagger/OpenAPI 目录搜索 operation_id、HTTP 方法、路径、参数位置和摘要。
+
+常用筛选：
+
+```bash
+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。
+
+```bash
+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。服务端会继续执行原有角色权限、登录态校验和审计逻辑。
+
+读示例：
+
+```bash
+eevee tools call call_api_operation \
+  '{"operation_id":"ProjectsController_list","parameters":{}}'
+```
+
+带路径参数：
+
+```bash
+eevee tools call call_api_operation \
+  '{"operation_id":"ProjectsController_detail","parameters":{"id":1}}'
+```
+
+带 query/body 的通用形态：
+
+```bash
+eevee tools call call_api_operation \
+  '{"operation_id":"<write-operation-id>","parameters":{"id":1},"body":{"name":"example"}}'
+```
+
+大 payload 用文件。文件内容是 MCP `arguments` 的完整对象，必须包含 `operation_id`：
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+eevee prompts list
+eevee prompts get code-review --args '{"language":"TypeScript"}'
+```
+
+任意标准 method/notification（包括 server 当前新增而 CLI 尚未包一层快捷方式的能力）:
+
+```bash
+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 全局目录：
+
+```bash
+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：
+
+```bash
+eevee skills install codex,claude
+eevee skills install codex
+eevee skills install universal
+```
+
+复制到某个项目的 Claude/Codex 目录：
+
+```bash
+cd /path/to/repo
+eevee skills install codex,claude --project .
+```
+
+复制到任意自定义 skills 根目录：
+
+```bash
+mkdir -p .agents/skills
+eevee skills install universal --dir .agents/skills
+```
+
+强制刷新、预演和卸载：
+
+```bash
+eevee skills update
+eevee skills install --dry-run
+eevee skills uninstall --yes
+eevee skills uninstall codex --global --yes
+eevee skills uninstall claude --project . --yes
+```
+
+管理查询：
+
+```bash
+eevee skills list
+eevee skills paths
+eevee skills info
+```
+
+Claude/Codex 重启后加载名为 `eevee-mcp` 的 skill。Skill 内容指导 Agent 先 discover contract，再 call tool，并避免未授权的破坏性变更。
+
+## 诊断与故障排查
+
+```bash
+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`。
+
+## 开发
+
+```bash
+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 复制。

package/assets/skills/eevee-mcp/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: eevee-mcp
+description: Operate eevee through the @eevee/cli business commands—projects, versions, terms, translations, tags, permissions, logs—and retain access to raw MCP tools/resources/prompts.
+---
+
+# eevee business-aware MCP skill
+
+Use this skill when a user asks Codex/Claude or another terminal Agent to inspect or change data on an eevee i18n server. Prefer **business-meaningful CLI commands** over hand-written JSON-RPC.
+
+## Golden rules
+
+1. Read before write. Resolve IDs with list/detail commands.
+2. Never guess project/version/term/tag/user IDs.
+3. Destructive delete/clear operations require explicit `--yes`; ask the user first if they did not request deletion.
+4. Report actual response data verbatim. If `isError=true`, stop and show the error instead of inventing fields.
+5. Keep the user's personal token private; never print it or put it in code/docs/tests.
+
+## First-run setup
+
+```bash
+eevee ping
+
+# Set once per machine/home directory
+eevee config set --url https://eevee.example.com/mcp
+eevee config set --token <user-token>
+
+# Inspect without revealing the token
+eevee doctor
+eevee config show
+```
+
+Temporary overrides have highest precedence and work on any connected command:
+
+```bash
+eevee project list --url http://127.0.0.1:10001/mcp --token "$EEVEE_TOKEN" --json
+```
+
+## Start from business intent
+
+List every packaged business command by domain:
+
+```bash
+eevee business        # complete matrix of every business command
+```
+
+Get exact flags/types for one operation:
+
+```bash
+eevee project create --help
+```
+
+Common examples:
+
+```bash
+eevee project list
+eevee project create --name Demo --locales zh-CN,en-US --description '示例项目'
+eevee project detail 12
+eevee version list 12
+eevee version create --id 12 --name 'Release 1' --status 2
+eevee term create --id 12 --version-id 34 --name login.button \
+  --translations '{"zh-CN":"登录","en-US":"Sign in"}'
+eevee translation set-content --id 12 --term-id 56 --locale zh-CN --content 登录
+eevee translation assign-translators --id 12 --locales zh-CN,en-US --translator-ids 2,3
+eevee permission list 12
+eevee log list --id 12 --page 1 --page-size 20
+```
+
+Add `--json` for machine-readable `{ok,data}` output, or `--raw` to inspect the complete MCP result.
+
+## Fallback: raw server tools
+
+The current eevee MCP server exposes three REST-backed tools. Use these only for an operation not yet represented by the business catalog, or while diagnosing it:
+
+- `list_api_operations`: search runtime Swagger operations by method/tag/text and obtain `operation_id`.
+
+  ```bash
+  eevee tools call list_api_operations '{"method":"GET","search":"terms","limit":50}'
+  ```
+
+- `get_api_operation`: read path/query/body contracts and required types before calling.
+
+  ```bash
+  eevee tools call get_api_operation '{"operation_id":"<operation_id>"}'
+  ```
+
+- `call_api_operation`: execute the selected API as the token owner.
+
+  ```bash
+  eevee tools call call_api_operation '{"operation_id":"<read-id>"}'
+  eevee tools call call_api_operation '{"operation_id":"<write-id>","parameters":{"id":1},"body":{"name":"demo"}}'
+  ```
+
+Always inspect current capability with `eevee tools list`; future servers may expose more tools.
+
+## Other standard MCP surfaces
+
+```bash
+eevee resources list
+eevee resources templates
+eevee resources read <uri>
+eevee prompts list
+eevee prompts get <prompt-name> --args '{"key":"value"}'
+eevee request <method> '<params-json>'
+eevee notify <method> --params '<params-json>'
+```
+
+Use `eevee request` for standard methods without a dedicated subcommand and `eevee notify` for JSON-RPC notifications. Use `@file.json` where JSON payload arguments are accepted to keep large payloads out of shell history.
+
+## Installation into agents
+
+Default installation copies this skill into Codex + Claude global directories:
+
+```bash
+eevee skills install
+```
+
+Other supported targets:
+
+```bash
+eevee skills install codex
+eevee skills install claude
+eevee skills install universal                 # ~/.agents/skills
+eevee skills install codex,claude --project .  # repository-local copies
+eevee skills install universal --dir .agents/skills
+eevee skills update
+eevee skills paths
+```