@eevee-ta/cli 0.1.0-beta.1 → 1.2.0

package/README.md

@@ -1,11 +1,42 @@
-# @eevee/cli
+# @eevee-ta/cli
 
-`@eevee/cli` 是 eevee MCP 服务的业务化命令行客户端和 Agent Skill 管理工具。公开命令采用稳定 `<group> <action>` 规范；也可以继续使用完整 MCP 能力（tools/resources/prompts/request/notify）。CLI 可直接给 Codex、Claude Code 或其他终端 Agent 使用，也适合人工排查 eevee 数据。
+`@eevee-ta/cli` 是 eevee MCP 服务的业务化命令行客户端和 Agent Skill 管理工具。公开命令采用稳定 `<group> <action>` 规范；也可以继续使用完整 MCP 能力（tools/resources/prompts/request/notify）。CLI 可直接给 Codex、Claude Code 或其他终端 Agent 使用，也适合人工排查 eevee 数据。
 
-运行时零依赖，只需要 Node.js 20.4+。
+运行时零依赖，只需要 Node.js 16+。
 
 ## 安装
 
+### 一键安装（推荐）
+
+使用 OSS 一键安装：
+
+```bash
+curl -fsSL http://tga-doc.oss-accelerate-overseas.aliyuncs.com/eevee-dev/install.sh | bash
+# 或
+wget -qO- http://tga-doc.oss-accelerate-overseas.aliyuncs.com/eevee-dev/install.sh | bash
+```
+
+安装器会：
+
+1. 检查 `curl/wget`、`tar`、系统架构和 musl/glibc 环境；
+2. 下载并安装新 CLI 前，先检查并删除旧平台 `tant-intl-agent-cli`，避免 `eevee` 命令冲突；
+3. Node.js 缺失或低于 16 时，从 npmmirror 下载用户级 Node.js 到 `~/.eevee/node`；
+4. 使用用户级 npm 全局目录 `~/.eevee/npm`，从国内 npm 镜像安装 `@eevee-ta/cli@latest`，并将两个目录写入 shell PATH；
+5. 自动探测并复制 Skill 到已安装 Agent 的全局目录。
+
+可用环境变量定制：
+
+| 变量 | 默认值 |
+|---|---|
+| `EEVEE_PACKAGE_NAME` | `@eevee-ta/cli` |
+| `EEVEE_NODE_VERSION` | `22.21.1` |
+| `EEVEE_NODE_MIRROR` | `https://npmmirror.com/mirrors/node` |
+| `EEVEE_NPM_REGISTRY` | `https://registry.npmmirror.com` |
+| `EEVEE_NODE_HOME` | `~/.eevee/node` |
+| `EEVEE_NPM_PREFIX` | `~/.eevee/npm` |
+
+### npm 安装
+
 本地开发或全局启用：
 
 ```bash
@@ -18,15 +49,40 @@ npm link           # 同时提供 eevee 和 eevee-cli 命令
 已发布后从 npm 安装：
 
 ```bash
-npm install -g @eevee/cli@latest
+npm install -g @eevee-ta/cli@latest
 ```
 
+npm 包的 `postinstall` 也会自动执行 Skill 迁移；如果安装时使用 `--ignore-scripts`，可手动执行 `eevee skills update --auto --global --force`。
+
 从本地仓库目录全局安装：
 
 ```bash
 npm install -g .
 ```
 
+## 版本更新
+
+CLI 每次执行命令时会检查 npm dist-tag 中的 `latest`。发现新版本时：
+
+- 交互终端会询问是否立即更新；
+- 非交互终端会输出更新命令，不阻塞当前命令；
+- 更新成功后会立即触发 Skill 迁移，并提示重新执行原命令。
+
+也可主动检查并更新：
+
+```bash
+eevee update
+eevee update --yes
+eevee update --yes --registry https://registry.npmmirror.com
+```
+
+默认 npm 镜像是 `https://registry.npmmirror.com`，可用 `EEVEE_NPM_REGISTRY` 覆盖。跳过启动检查：
+
+```bash
+EEVEE_SKIP_UPDATE_CHECK=1 eevee ping
+eevee ping --no-update-check
+```
+
 ## 配置服务器地址和 token
 
 ```bash
@@ -70,6 +126,8 @@ eevee config unset --token
 | `eevee <group> <action>` | 推荐：执行 project、version、term、translation 等约 50 个业务动作 |
 | `eevee business` / `eevee -h` | 查看全部业务命令；`-h` 会列全协议命令 |
 | `eevee <group> <action> --help` | 查看该动作的 path/query/body 参数和类型 |
+| `eevee i18n scan` | 本地扫描 JS/TS/JSX/Vue 与 Java Spring Boot 项目中的硬编码词条 |
+| `eevee update` | 检查、交互确认并更新到 npm latest，同时迁移 Skill |
 | `eevee config show/set/get/unset/path` | 管理服务器地址和用户 token |
 | `eevee doctor` | 校验配置、MCP 连接、tools/list 和已装 Skill |
 | `eevee ping` | 完成完整 MCP initialize 握手并调用 ping |
@@ -78,8 +136,7 @@ eevee config unset --token
 | `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 skills install/update/...` | 安装/更新内置 Agent Skill 到 Codex、Claude Code、Cursor、OpenCode 或自定义目录 |
 
 联网命令均支持临时覆盖：
 
@@ -90,153 +147,154 @@ eevee --url https://staging.example.com/mcp \
       ping
 ```
 
-## 本地国际化检查
+## 国际化扫描与导出
+
+### 服务端词条导出
 
-`eevee lint` 把 `eslint-plugin-eevee` 的 `no-created` 规则迁移为本地检查器。Web 适配器直接解析
-TypeScript AST，支持 `.ts`、`.tsx`、`.js`、`.jsx`、`.mjs` 和 `.cjs`，不依赖目标项目安装 ESLint：
+按项目 `intl.json` 的 `outPaths / projectIds / tags` 配置从 EEVEE 服务端导出词条：
 
 ```bash
-eevee lint
-eevee lint apps/gaia/src
-eevee lint --staged
-eevee lint --source changed
-eevee lint --language web --json
+eevee i18n export                 # 默认写 path（开发目录）
+eevee i18n export --target build  # 写 buildPath（线上目录）
+eevee i18n export --env online    # --target build 的语义别名
+eevee i18n export --dry-run --json
 ```
 
-检查配置优先读取 `.eevee-lint.json`、`.eeveerc.json`，然后读取 `package.json` 的 `eevee.lint`：
+每次只写入一个目录：`dev/offline` 使用 `path`，`build/online` 使用 `buildPath`。旧配置中以 `/` 开头的输出路径按项目根内路径处理。
+
+导出配置支持：
 
 ```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
+  "format": "json",
+  "groupByTag": true,
+  "clean": true,
+  "localeAliases": {
+    "zh-CN": "zh",
+    "en-US": "en"
+  },
+  "outPaths": [
+    {
+      "path": "/apps/gaia/public/intl/",
+      "buildPath": "/apps/gaia/public/intl/",
+      "projectIds": [
+        {
+          "projectId": 12,
+          "branchIds": [21, 22],
+          "tags": ["gaia"]
         },
-        "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"]
+        {
+          "projectId": 1,
+          "branchIds": [],
+          "tags": ["portal", "talos", null]
         }
-      }
+      ]
     }
-  }
+  ]
 }
 ```
 
-`intlConfig` 复用旧插件的 `intl.json` 结构；CLI 只读取 `outPaths` 下的 `zh-CN*.json` 作为平台词条。
-`excludePropertys` 和 `execludeTrack` 这两个旧拼写继续兼容，推荐新配置使用上面的规范拼写。
+规则：
 
-`eevee lint` 在检查前强制同步一次平台词条快照，下载完成后再读取 `intlConfig` 指向的本地 JSON。
-`refresh.config` 指向 `eevee intl download` 使用的目标数组配置；不配置时默认读取项目
-`package.json` 的 `eevee.intl`。
+- `branchIds` 是 EEVEE 版本 ID 数组，`[]` 表示全部版本。数组内按配置顺序拉取，跨版本重复 key 由后配置版本覆盖；
+- `tags: []` 表示全部词条；
+- `tags: [null]` 表示无标签词条，也可以和普通标签混用；
+- `format` 支持 `json`、`js`、`ts`、`property`、`properties`；`js/ts` 输出 ESM `export default`；
+- `groupByTag: true` 输出 `语言-标签.格式`；`false` 输出 `语言.格式`；
+- `localeAliases` 只影响输出文件名，例如 `zh-CN` 配置为 `zh` 后输出 `zh-web.json`；
+- `clean: true` 时仅清理输出目录中符合当前语言命名规则的旧导出文件，再写入新文件；
+- 项目和标签都按配置顺序处理；不按标签分组合并时，重复 key 由后配置的项目/标签覆盖；
+- token 优先级为 `--token`、`EEVEE_TOKEN`、`intl.json` 的 `token`、本机 CLI 配置；`intl.json` 适合配置基础数据读取 token，个人 token 不建议提交到仓库。
 
-同步失败、平台返回 0 词条、本地词条文件解析失败，都会直接阻断检查；不会退回旧快照，也不会提供
-`--no-refresh` 旁路。词条同步成功但代码引用的 key 未登记时，诊断为 `unregistered`，退出码同样是 `1`。
+`i18n scan` 迁移自 `@tant/eslint-plugin-eevee` 的核心检查能力，但不要求目标项目安装 ESLint 插件，也不需要 Node 项目改造：
 
 ```bash
-# 使用独立下载目标配置；同步仍然强制执行
-eevee lint --refresh-config intl.download.json
+eevee i18n scan
+eevee i18n scan /path/to/project
+eevee i18n scan --json
+eevee i18n scan --include 'src/main/java/**/*.java' --exclude '**/generated/**'
 ```
 
-提交前推荐使用：
+CLI 会默认依次查找：
 
-```bash
-eevee lint --staged
+```text
+intl.json
+.eevee/i18n.json
+eevee.i18n.json
 ```
 
-发现问题退出码为 `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`。完整结构如下：
+旧版 ESLint 插件配置中的 `outPaths`、`includes`、`excludes`、`excludeAscii`、`tagMatchMap`、`excludePropertys`、`execludeTrack` 均继续可用，同时支持更正后的 `excludeProperties` 和 `excludeTrack`：
 
 ```json
 {
-  "refresh": {
-    "config": ".eevee/download.json"
+  "outPaths": [{ "path": "locales/" }],
+  "includes": ["src/**/*.{js,jsx,ts,tsx,vue}"],
+  "excludes": ["**/*.test.*"],
+  "excludeAscii": true,
+  "tagMatchMap": {
+    "src/pages/**": ["page"]
   },
-  "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
-    }
-  }
+  "excludeProperties": ["description"],
+  "excludeTrack": true
 }
 ```
 
-`.eevee/intl.json` 只负责告诉检查器去哪里读快照：
+检查规则：
 
-```json
-{ "outPaths": [{ "path": "locales" }] }
+- 扫描 JavaScript / TypeScript 字符串、模板字符串、JSX / Vue 文案；
+- `formatMessage(...)` 内的词条会按 `zh-CN-<tag>.*` 词条文件检查「未登记」和「标签不匹配」；
+- 词条文件支持 JSON、`export default {}` / `module.exports = {}` 常见形态和 Spring properties；JS 词条只做静态解析，不执行项目代码；
+- 默认跳过纯 ASCII、导入导出字符串、对象属性 key、指定属性和埋点调用；
+- 默认跳过测试、Mock、Fixture 和构建生成文件；
+- 默认跳过模板字符串插值里的已国际化表达式；
+- TSX 中 `INTL.操作` 这类成员表达式不视为 JSX 文案；
+- 支持禁用注释：
+  - `// eevee-i18n-disable-next-line`
+  - `// eevee-i18n-disable`
+  - `// eevee-i18n-disable-file`
+- 默认与旧插件一致跳过普通函数调用的直接字符串参数，需要更严格检查时可加 `--check-call-arguments`。
+
+### Java Spring Boot 兼容
+
+CLI 不依赖 ESLint 解析 Java，因此可以直接在 Maven / Gradle 多模块 Spring Boot 仓库执行：
+
+```bash
+cd /path/to/spring-boot-service
+eevee i18n scan
 ```
 
-`.eevee/download.json` 使用 `eevee intl download` 的目标数组格式：
+默认包含：
 
-```json
-[
-  {
-    "outPath": ".eevee/locales",
-    "format": "json",
-    "languages": { "zh-CN": "zh-CN" },
-    "projects": [{ "projectId": 1, "tags": [123] }]
-  }
-]
+```text
+**/src/main/java/**/*.java
+**/src/main/resources/templates/**/*.{html,htm,jsp,jspf,tag,ftl,vm}
 ```
 
-把 `projectId` 和 tag ID 换成后端词条项目实际值。提交检测推荐在 Git `pre-commit` 中执行：
+Java 支持包括：
 
-```bash
-npx @eevee/cli lint --staged --language java
+- 普通字符串和 Java 17 文本块；
+- 跳过 Java 注释；
+- 默认跳过注解中的中文说明，可用 `--check-annotations` 打开；
+- 识别 `MessageSource#getMessage` 使用 message key 的常规写法；
+- 支持 Thymeleaf / JSP / Freemarker / Velocity 模板文本和 UI 属性；
+- 跳过 `#{...}`、`${...}`、`<spring:message>`、`<fmt:message>` 等已国际化表达式；
+- 词条输出目录支持 `messages*_zh*_CN*.properties`。
+
+示例配置：
+
+```json
+{
+  "outPaths": ["src/main/resources/messages/"],
+  "includes": [
+    "**/src/main/java/**/*.java",
+    "**/src/main/resources/templates/**/*.{html,jsp}"
+  ],
+  "excludes": ["**/generated/**"]
+}
 ```
 
+扫描发现问题会输出文件、行列、规则和词条；CI 中可直接使用非 0 退出码阻断流水线，`--no-fail` 可保留展示但不阻断。
+
 ## Business command layer
 
 Business commands 是主要接口，命名规范固定为 `<group> <action>`。它把底层 `call_api_operation` 封装成语义稳定、参数有类型的命令，不需要手工查找 `operation_id`：
@@ -406,33 +464,43 @@ eevee notify notifications/cancelled '{"requestId":"<id>","reason":"user cancell
 
 ## Agent Skill 快速安装
 
-仓库中已经内置 `assets/skills/eevee-mcp/SKILL.md` 和 `reference.md`。
+仓库内置两个 Agent Skill：
 
-默认复制到当前用户的 Codex + Claude 全局目录：
+- `eevee-mcp`：业务数据操作与 MCP 能力。
+- `eevee-integration`：把 EEVEE 词条导出和代码扫描接入 Java Spring Boot 或 UmiJS 项目；包含项目/版本 ID 询问清单、目录纳入/屏蔽策略、提交钩子和误报处理。
+
+默认自动探测已安装的 Codex、Claude Code、Cursor 和 OpenCode，并复制到对应客户端的全局目录：
 
 ```bash
 eevee skills install
+eevee skills install --skill eevee-integration
+eevee skills agents    # 查看探测结果
 ```
 
 实际路径：
 
 - Codex: `$CODEX_HOME/skills/eevee-mcp`，默认 `~/.codex/skills/eevee-mcp`
 - Claude Code: `$CLAUDE_CONFIG_DIR/skills/eevee-mcp`，默认 `~/.claude/skills/eevee-mcp`
+- Cursor: `$CURSOR_HOME/skills/eevee-mcp`，默认 `~/.cursor/skills/eevee-mcp`
+- OpenCode: `$OPENCODE_CONFIG_DIR/skills/eevee-mcp`，默认 `~/.config/opencode/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,claude,cursor,opencode
 eevee skills install codex
+eevee skills install claudecode
 eevee skills install universal
+eevee skills install --all
+eevee skills install --skill eevee-integration codex,claude
 ```
 
 复制到某个项目的 Claude/Codex 目录：
 
 ```bash
 cd /path/to/repo
-eevee skills install codex,claude --project .
+eevee skills install codex,claude,cursor,opencode --project .
 ```
 
 复制到任意自定义 skills 根目录：
@@ -457,10 +525,18 @@ eevee skills uninstall claude --project . --yes
 ```bash
 eevee skills list
 eevee skills paths
+eevee skills agents
 eevee skills info
 ```
 
-Claude/Codex 重启后加载名为 `eevee-mcp` 的 skill。Skill 内容指导 Agent 先 discover contract，再 call tool，并避免未授权的破坏性变更。
+自动迁移时机：
+
+- `install.sh` 安装成功后；
+- npm 安装/更新包后的 `postinstall`；
+- `eevee update` 更新成功后；
+- 用户主动执行 `eevee skills install/update`。
+
+未检测到任何客户端时，自动迁移会跳过；显式 `--all` 会写入全部兼容目录。对应 Agent 重启后加载名为 `eevee-mcp` 的 skill。Skill 内容指导 Agent 先 discover contract，再 call tool，并避免未授权的破坏性变更。
 
 ## 诊断与故障排查
 

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

@@ -0,0 +1,46 @@
+---
+name: eevee-integration
+description: Integrate @eevee-ta/cli term export and i18n scanning into Java Spring Boot or UmiJS/Umi Max repositories, including intl.json, scripts, Git hooks, project/version IDs, and include/exclude scope. Not for routine eevee data operations; use eevee-mcp for those.
+metadata:
+  short-description: Configure EEVEE CLI for Java or UmiJS repositories
+---
+
+# EEVEE Project Integration
+
+Use this skill when adding or changing EEVEE CLI integration in a application repository. Produce a reproducible configuration, project-specific scripts or npm scripts, documentation, and a commit-time check. Do not merely leave instructions in chat.
+
+## Mandatory intake
+
+Before writing or changing configuration, inspect the repository and ask the user for decisions that cannot be inferred. In particular, ask for all of the following that are not already authoritative in the repository:
+
+1. EEVEE server URL and token policy.
+2. Platform project ID(s). Never guess them.
+3. Version ID list. Clarify whether all versions are wanted (`branchIds: []`) or only selected IDs.
+4. Tag policy: all terms, selected tags, or `[null]` for untagged terms; whether output must be split by tag.
+5. Output directories for development and build artifacts, output format, and language filename aliases.
+6. Source-directory policy: which directories must be scanned, which are generated/test/mock/vendor and must be excluded, and how legacy debt should be handled.
+7. Commit-gate scope: staged files only or full repository.
+
+Use `references/intake.md` for the exact question set and decision rules. If the user supplies only some values, state the reasonable defaults you will use and ask only for decisions that materially change behavior.
+
+## Implementation route
+
+1. Inspect the existing build system, source layout, locale resources, lint scripts, and Git hooks.
+2. Read the mode-specific reference:
+   - Java 11 / Spring Boot / Maven or Gradle: `references/java-springboot.md`
+   - UmiJS / Umi Max / React front end: `references/umijs.md`
+3. Add `intl.json` at the repository root unless an existing configuration is authoritative.
+4. Add a small wrapper script or npm script rather than requiring people to remember long CLI invocations.
+5. Add a commit-time check for staged source files when the user wants commit gating.
+6. Document the configuration, commands, exclusions, suppression comments, and known legacy debt in the repository.
+7. Run dry-run export, real export where authorized, scanning, syntax/build checks, and the commit gate. Record actual commands and results.
+
+## Non-negotiable constraints
+
+- Do not guess project IDs, version IDs, tags, or output paths.
+- Do not commit personal tokens or machine-specific Maven settings. A basic read-only token may be committed only when the user explicitly says it is safe.
+- Prefer narrow, explainable exclusions and inline suppression comments over a long file-by-file baseline.
+- Do not silently overwrite locale resources. Confirm whether the EEVEE project is the source of truth and whether cleanup is enabled.
+- Preserve unrelated user modifications and do not reset a dirty worktree.
+- Keep full scans informational when there is known legacy debt; make the commit gate scan only staged files unless the user explicitly requires a full blocking scan.
+- When a repository uploads terms to EEVEE, include source metadata: `description` (usage location), `params` for placeholders, and `source_info` (`repo`/`branch`/`path`/`line` — all four together or omitted). Refresh existing translations with `translation set-content`; `term update` ignores `--translations`.

package/assets/skills/eevee-integration/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "EEVEE Integration"
+  short_description: "Configure EEVEE CLI for Java or UmiJS repositories"

package/assets/skills/eevee-integration/references/intake.md

@@ -0,0 +1,87 @@
+# EEVEE Integration Intake
+
+Use these questions before changing `intl.json`, wrapper scripts, or hooks. The goal is to make platform metadata and repository scope explicit rather than inferred.
+
+## Required platform questions
+
+Ask these unless the repository already contains authoritative answers:
+
+```text
+1. EEVEE MCP 地址是什么？token 是基础读取 token 还是个人 token？是否允许写入仓库？
+2. 使用哪个 EEVEE 项目 ID？多个项目需要合并导出吗？
+3. 每个项目使用哪些版本 ID？是全部版本（branchIds: []）还是指定 ID 列表？
+4. 词条按什么规则筛选？
+   - tags: [] 表示全部
+   - tags: [null] 表示无标签
+   - tags: ["web", null] 表示指定标签加无标签
+5. 输出是否按标签拆分？
+   - groupByTag: true -> zh-CN-web.json
+   - groupByTag: false -> zh-CN.json
+6. 输出格式是什么：json、js、ts、property、properties？
+7. 每种语言输出文件名是否需要别名？
+   例：zh-CN -> zh，或 zh-CN -> messages_zh_CN
+8. 开发目录 path 和构建目录 buildPath 分别是什么？每次导出只写其中一个，默认写哪个？
+```
+
+If the user knows the project but not IDs, offer discovery commands rather than guessing:
+
+```bash
+eevee project list --json
+eevee version list <project-id> --json
+eevee tag-group list <project-id> --json
+```
+
+`branchIds` is a required array in current CLI versions. Do not use legacy singular `branch` values.
+
+## Required repository-scope questions
+
+Ask these after inspecting the repository:
+
+```text
+1. 哪些源码目录包含用户可见文案，必须纳入扫描？
+2. 哪些目录是生成代码、测试、Mock、Fixture、文档示例、vendor 或构建产物，应该屏蔽？
+3. 存量未国际化文案是立即全量修复、全量阻断、还是先只阻断本次变更文件？
+4. 是否存在组件内部按词条 key 翻译的列配置或动态字典，需要用注释豁免？
+5. locale 资源目录是否只允许 EEVEE 导出，还是还保存手工文件？
+```
+
+### Include policy
+
+Start narrow and expand only with evidence:
+
+- Java: usually `**/src/main/java/**/*.java`; include template resources only when the project has server-rendered templates.
+- UmiJS: usually source directories such as `src/**/*.{ts,tsx,js,jsx}` or application-specific `apps/<app>/src/**`.
+- Scan real source directories, not an entire repository by default.
+- Always let CLI defaults exclude dependencies, build outputs, generated Umi directories, minified files, tests, mocks, and fixtures unless the user explicitly requires otherwise.
+
+### Exclude and suppression policy
+
+Prefer this order:
+
+1. Correct the code by moving user-visible text to the project's i18n mechanism.
+2. Use an inline comment for a semantic false positive:
+   ```ts
+   title: '操作', // eevee-i18n-disable：组件内部按 key 翻译
+   ```
+3. Use a next-line comment for declarations or dynamic dictionary keys:
+   ```ts
+   // eevee-i18n-disable-next-line：动态拼接词条字典 key
+   const title = REPO_INTL[`${isEdit ? '编辑' : '新建'}表`];
+   ```
+4. Use file-level suppression only when the entire file is a term-key map, internal mapping, Mock, or generated equivalent:
+   ```java
+   // eevee-i18n-disable-file：本文件只维护词条 key
+   ```
+5. Add a directory or glob to `excludes` only for generated/test/mock/vendor content or an explicitly approved legacy-debt boundary.
+6. Do not maintain an unexplained list of hundreds of source files. If full scanning has legacy debt, keep it informational with `--no-fail` and gate only staged files.
+
+## Output and gate decisions
+
+Confirm these before writing files:
+
+- Is EEVEE the source of truth? A real export can remove keys that exist locally but are absent in the selected EEVEE project/version/tag set.
+- Is `clean` enabled? Cleanup deletes old generated language-prefix files; hand-written files in the output directory need another location or a non-language prefix.
+- Should the commit hook scan only staged files? This is normally preferred for repositories with legacy debt.
+- Which existing build checks must accompany the EEVEE check?
+
+Record the user's answers and the resulting defaults in project documentation before implementation.