@eevee-ta/cli 0.1.0-beta.1

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

@@ -0,0 +1,105 @@
+# @eevee/cli reference for Agents
+
+## Command model
+
+1. **Business layer (preferred):** stable English `<group> <action>` commands with typed options, Bearer-token auth and response unwrapping handled by the CLI.
+2. **Raw MCP layer (fallback/debugging):** tools/list, resources/*, prompts/*, arbitrary requests and notifications.
+
+Never call HTTP REST endpoints directly unless the user explicitly asks; route through MCP so session negotiation and auditing stay consistent.
+
+## Configuration
+
+| Source | Example |
+|---|---|
+| Persistent file | `eevee config set --url http://127.0.0.1:10001/mcp --token <token>` |
+| Per command | `eevee project list --url <mcp-url> --token <token>` |
+| Environment | `EEVEE_MCP_URL=<url> EEVEE_TOKEN=<token> eevee doctor` |
+
+Precedence is flags → environment → `~/.eevee-cli/config.json` → built-in local URL. The config file is created with mode `0600`.
+
+## Business discovery
+
+```bash
+eevee business            # all packaged operations grouped by domain
+eevee <group> <action> --help
+```
+
+Domains included: project, version, term, translation, tag-group, tag, permission, log, profile, config, and system user. Every delete/clear command is guarded by `--yes`.
+
+### Representative lifecycle
+
+```bash
+# Projects
+eevee project list --json
+eevee project create --name Demo --locales zh-CN,en-US --json
+eevee project update --id 86 --description 'Updated by CLI'
+eevee project delete 86 --yes --json
+
+# Versions and terms
+eevee version list 86
+eevee version create --id 86 --name v1
+eevee term list 86
+eevee term set-tags --id 86 --version-id 9 --term-id 22 --tag-ids 3,4
+
+# Translations
+eevee translation set-content --id 86 --term-id 22 --locale en-US --content Hello
+eevee translation set-status --id 86 --term-id 22 --locale en-US --status 3
+```
+
+Use the returned IDs from live responses rather than examples above.
+
+## Built-in MCP tool fallbacks
+
+| Server tool | Purpose | Invocation |
+|---|---|---|
+| `list_api_operations` | Search Swagger-derived REST operations by method/tag/text; returns pagination and `operation_id`. | `eevee tools call list_api_operations '{"method":"GET","search":"terms","limit":50}'` |
+| `get_api_operation` | Return one operation's contract: path/query/header parameters and JSON body schema. | `eevee tools call get_api_operation '{"operation_id":"<id>"}'` |
+| `call_api_operation` | Execute an operation as the authenticated token owner using `parameters.path/query` plus `body`. | `eevee tools call call_api_operation '{"operation_id":"<id>","parameters":{"id":1},"body":{}}'` |
+
+Check `eevee tools list` first; it is authoritative if the server adds tools later. Read detailed schemas and offline workflow notes with `eevee tools docs [tool-name]`.
+
+## Full MCP surface
+
+```bash
+eevee ping
+eevee tools list [--raw|--json]
+eevee tools docs [tool]
+eevee tools call <tool> '<arguments-json>'      # also supports @payload.json / --args @file.json
+eevee resources list | templates | read <uri>
+eevee resources subscribe <uri>
+eevee prompts list
+eevee prompts get <name> --args '{"key":"value"}'
+eevee request completion/complete '{"ref":{"type":"ref/prompt","name":"review"},"argument":{"name":"code","value":"..."}}'
+eevee notify notifications/cancelled '{"requestId":"<id>","reason":"cancelled"}'
+eevee request logging/setLevel '{"level":"info"}'
+```
+
+Every network command completes MCP initialize + initialized handshake over Streamable HTTP, sends `Authorization: Bearer <user-token>`, and preserves `Mcp-Session-Id` automatically.
+
+## Output conventions
+
+- Human output unwraps REST `{status,data,msg}` envelopes and renders arrays as aligned tables.
+- `--json` prints `{ok:true,data}` or `{ok:false,data}`.
+- `--raw` prints the full MCP CallToolResult including content blocks and structured content.
+- Empty REST data prints `(空)` instead of implying failure.
+
+## Skill installation
+
+Default Codex + Claude global copy:
+
+```bash
+eevee skills install
+```
+
+Target examples:
+
+```bash
+eevee skills install codex                      # $CODEX_HOME/skills/eevee-mcp
+eevee skills install claude                     # $CLAUDE_CONFIG_DIR/skills/eevee-mcp
+eevee skills install universal                  # ~/.agents/skills/eevee-mcp
+eevee skills install codex,claude --project .
+eevee skills install universal --dir .agents/skills
+eevee skills update                             # replace bundled-skill managed copies
+eevee skills uninstall --yes                    # explicit removal
+eevee skills paths                              # inspect destination roots
+```

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

@@ -0,0 +1,181 @@
+---
+name: eevee-migration
+description: Guide i18n term migration from code repositories into eevee — incremental versioning, param extraction, Git source_info, deduplication, and API-first operations.
+---
+
+# eevee i18n 迁移技能
+
+当需要将代码仓库中的 i18n 词条迁移到 eevee 平台时使用此技能。
+核心原则：**所有操作走 API，不直接修改数据库**。
+
+## 操作人规范
+
+- 统一使用超管用户（如 id=1）的 token，不要通过 mock 登录创建多余用户
+- Token 通过 `Authorization: Bearer <token>` 传递
+- 不确定 token 时先用 `GET /api/v1/users` 确认用户身份
+
+## 完整迁移流程
+
+### 第一步：切换代码仓库分支
+
+```bash
+cd /path/to/repo && git checkout release/X.Y
+git branch --show-current  # 确认分支
+```
+
+### 第二步：提取代码中使用的 i18n key
+
+**Java 项目（properties + MessageFormat）**：
+
+1. 扫描所有 `.java` 文件，匹配以下模式：
+   - `getLocaleMessage("key")` / `tryLocaleMessage("key", params)`
+   - `new BizException(ReturnCode.XXX, "key", params...)`
+   - 字符串字面量 `"gaia.xxx.yyy"`（带包名前缀）
+2. 扫描枚举文件（`ReturnCode.java` 等），提取 `localeMsgRef` 值
+3. 读取 `messages_zh_CN.properties` 获取所有已翻译 key
+4. 计算交集：`matched = codeKeys ∩ propsKeys`
+
+**前端项目（JSON/tsx formatMessage）**：
+
+1. 扫描 `intl.tsx`/`intl.ts` 文件，匹配 `formatMessage({ id: 'key' }, { 0: x })`
+2. 从函数签名提取参数名和类型（`x: number` → 数量，`x: ReactNode` → 名称）
+3. 通过英文内容反向搜索匹配未直接引用的 key
+
+### 第三步：对比上一版本获取增量
+
+```
+新增 key = 当前版本 matched - 上一版本 matched
+删除 key = 上一版本 matched - 当前版本 matched
+```
+
+只将**新增 key** 迁移到新版本（增量模式），不重复已有词条。
+
+### 第四步：通过 API 创建版本
+
+```bash
+curl -X POST /api/v1/projects/{projectId}/versions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "release-X.Y"}'
+```
+
+⚠️ 如果同名版本软删后唯一键冲突，需要应用层在软删时改名（`name__del__{id}`）或硬删旧记录。
+
+### 第五步：通过 API 创建词条（含翻译、描述、参数）
+
+```bash
+curl -X POST /api/v1/projects/{projectId}/versions/{versionId}/terms \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "gaia.service.error.xxx",
+    "description": "模块：错误描述",
+    "params": [{"name":"count","value":"1","desc":"数量"}],
+    "translations": {"zh-CN":"中文","en-US":"English","ja-JP":"日本語","ko-KR":"한국어"}
+  }'
+```
+
+**描述生成规则**：
+从 key 路径推断模块前缀 + zh-CN 内容：
+`gaia.service.workflow.error.task_check.xxx` → `"任务校验：xxx"`
+
+**参数提取规则**：
+扫描 zh-CN 翻译中的 `{0}` `{1}` 占位符，结合上下文推断：
+
+| 上下文 | 推断 | 示例 |
+|--------|------|------|
+| `{0}` 后跟 个/条/项 | count | `{"name":"count","value":"1","desc":"数量（个）"}` |
+| `{0}` 成功 + `{1}` 失败 | successCount/failCount | `{"name":"successCount","value":"1","desc":"成功数"}` |
+| `【{0}】` 括号内 + 表 | tableName | `{"name":"tableName","value":"table_name","desc":"表名"}` |
+| `{0}` + 原因/失败 | errorMsg | `{"name":"errorMsg","value":"错误详情","desc":"错误信息"}` |
+| 通知模板 `{0}`~`{4}` | 依次: 空间/时间/名称/原因/链接 | 见下方模板映射 |
+
+通知模板映射：
+`{0}`→spaceName, `{1}`→timestamp, `{2}`→flowName/taskName, `{3}`→failReason, `{4}`→detailUrl
+
+⚠️ **同一词条内参数名不可重复**。如两个占位符推断出同名（如两个 `tableName`），需根据位置区分（如 `spaceName` + `tableName`）。
+
+**source_info（Git 信息）**：
+API 要求 `repo/branch/path/line` 四字段完整或全部留空：
+
+```json
+{
+  "repo": "https://gitlab.example.com/team/repo",
+  "branch": "release/6.1",
+  "path": "gaia-common/src/main/java/.../ReturnCode.java",
+  "line": 0
+}
+```
+
+通过已有词条 PATCH 补充：
+```bash
+curl -X PATCH /api/v1/projects/{projectId}/terms/{termId} \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"source_info": {...}, "params": [...]}'
+```
+
+### 第六步：去重（新版本不含旧版本已有的词条）
+
+对比新旧版本的 term name 集合，删除新版本中与旧版本重复的：
+
+```
+V6.0 增量 = V6.0 全量 keys - V5.0 keys
+```
+
+逐个通过 `DELETE /api/v1/projects/{projectId}/terms/{termId}` 删除。
+
+### 第七步：清理"待分类"中的重复词条
+
+新版本发布后，"待分类"中与正式版本重复的词条应删除，只保留独有词条。
+
+## 质量检查
+
+### 遗漏 key 报告
+
+分类输出：
+
+| 分类 | 说明 |
+|------|------|
+| 代码引用但 properties 缺失 | 枚举或代码中定义了 key 但 properties 里没翻译 |
+| properties 有但代码未引用 | 历史遗留或预留 |
+| 前缀 key（尾带 `.`） | 动态拼接，非缺失 |
+| 误报 | 非 i18n 字符串被正则误匹配 |
+
+### 参数覆盖率
+
+检查翻译中含 `{N}` 但 params 为空的词条，通过 PATCH 补齐。
+
+## 常见坑
+
+### ❌ 不要做的事
+
+1. **不要直接修改数据库**——绕过校验、日志和数据完整性
+2. **不要用 `DELETE /projects/:id/terms` 清空单版本**——这会清空整个项目所有版本的词条
+3. **不要 mock 登录创建多余用户**——统一用超管 token
+4. **不要假设 properties 文件名用横杠**——Java 习惯用下划线（`messages_zh_CN.properties` 不是 `messages_zh-CN.properties`）
+5. **不要用 SQL LIKE 搜索 `__del__`**——`_` 在 LIKE 中是通配符，会误匹配 `delete_failed` 等正常 key
+
+### ⚠️ 注意事项
+
+1. source_info 四字段要么全填要么全空，不能只填部分
+2. 同一词条的 params 数组中 name 不可重复
+3. 版本删除前必须清空其下所有词条
+4. 软删记录的唯一键冲突需在应用层处理（改名后软删）
+5. 批量 API 调用时控制并发（建议 3~5），避免打垮服务
+
+## 多版本增量模式图
+
+```
+V4.5（全量 311）
+  └── V5.0（增量 184 = 5.0新增key）
+        └── V6.0（增量 194 = 6.0新增key）
+              └── V6.1（增量 0 = 无新增，复用 V6.0）
+
+待分类 = 全量导入 - 各正式版本已有的 key
+```
+
+每次切换分支后：
+1. 提取 key → 对比上一版 → 得到增量
+2. 创建新版本 → 创建增量词条
+3. 无增量则不创建新版本，仅更新版本名

package/assets/skills/eevee-project-setup/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: eevee-project-setup
+description: Guide configuring a frontend or Java backend project to use @eevee/cli for term sync (intl download) and lint (missing-key / hardcoded-text detection). Covers web and Java adapters, file layout, and step-by-step initialization.
+---
+
+# eevee 项目接入技能
+
+当需要让一个代码仓库通过 `@eevee/cli` 实现**词条同步**和**国际化检查**时使用此技能。
+核心原则：**所有词条数据通过 API 拉取，配置文件提交到仓库，token 不入 Git**。
+
+## 前置条件
+
+```bash
+eevee config set --url http://127.0.0.1:10001/mcp
+eevee config set --token <your-user-token>
+eevee ping
+```
+
+确认项目 ID 和版本 ID：
+
+```bash
+eevee project list
+eevee intl versions --project <projectId>
+```
+
+## 通用流程
+
+1. 确认项目类型（前端 web / 后端 java）
+2. 创建 `.eevee/` 目录存放同步配置
+3. 创建 `.eevee-lint.json`（Java）或在 `package.json` 配置 `eevee.lint`（web）
+4. 运行 `eevee intl download --dry-run` 验证
+5. 运行 `eevee lint` 验证
+6. 把快照目录加入 `.gitignore`（快照不入 Git）
+
+---
+
+## 前端项目（web adapter）
+
+前端项目有 `package.json`，配置写入 `eevee` 字段或独立 `.eevee-lint.json`。
+
+### package.json
+
+```jsonc
+{
+  "eevee": {
+    "intl": "intl.download.json",
+    "lint": {
+      "refresh": {
+        "config": "intl.download.json"
+      },
+      "languages": {
+        "web": {
+          "enabled": true,
+          "root": ".",
+          "intlConfig": "intl.json",
+          "includes": ["src/**/*.{ts,tsx,js,jsx}"],
+          "excludes": ["**/*.test.*", "**/mock/**", "**/node_modules/**"],
+          "excludeAscii": true,
+          "tagMatchMap": {
+            "src/**/*": ["<project-tag>"]
+          },
+          "excludeProperties": ["title", "description"],
+          "excludeTrack": true
+        }
+      }
+    }
+  }
+}
+```
+
+### intl.download.json
+
+```json
+[
+  {
+    "outPath": ".eevee/locales",
+    "format": "json",
+    "splitByTag": false,
+    "languages": {
+      "zh-CN": "zh-CN-<tag-name>"
+    },
+    "projects": [
+      { "projectId": 1, "tags": [123] }
+    ]
+  }
+]
+```
+
+### intl.json（lint 数据源）
+
+```json
+{
+  "outPaths": [
+    { "path": ".eevee/locales" }
+  ]
+}
+```
+
+### 运行
+
+```bash
+eevee lint --staged
+eevee lint --language web
+```
+
+---
+
+## 后端项目（Java adapter）
+
+Java 项目（如 Spring Boot）通常没有 `package.json`，推荐在仓库根目录放 `.eevee-lint.json`，
+同步配置放 `.eevee/` 目录。
+
+### 目录结构
+
+```
+project-root/
+├── .eevee/
+│   ├── sync.json          ← 运行时 properties 全量生成
+│   ├── download.json      ← lint 用 JSON 快照
+│   ├── intl.json          ← lint 数据源声明
+│   └── README.md
+├── .eevee-lint.json       ← lint 规则
+└── .gitignore             ← 忽略 .eevee/locales/
+```
+
+### .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/**", "**/target/**"],
+      "tagMatchMap": {
+        "*/src/main/java/**/*": ["<tag-name>"]
+      },
+      "localeMethods": ["getLocaleMessage", "tryLocaleMessage", "getMessage"],
+      "checkHardcoded": true,
+      "excludeMethods": ["trace", "debug", "info", "warn", "error"]
+    }
+  }
+}
+```
+
+### .eevee/download.json（lint 快照）
+
+```json
+[
+  {
+    "outPath": "locales",
+    "format": "json",
+    "splitByTag": false,
+    "languages": {
+      "zh-CN": "zh-CN-<tag-name>"
+    },
+    "projects": [
+      { "projectId": 3, "versions": [2, 29, 30, 31] }
+    ]
+  }
+]
+```
+
+### .eevee/intl.json
+
+```json
+{
+  "outPaths": [
+    { "path": "locales" }
+  ]
+}
+```
+
+> `outPaths` 相对于 `.eevee/intl.json` 自身目录解析，所以 `"locales"` 指向 `.eevee/locales/`。
+
+### .eevee/sync.json（运行时 properties 全量生成）
+
+```json
+[
+  {
+    "outPath": "<module>/src/main/resources/static/i18n",
+    "format": "properties",
+    "splitByTag": false,
+    "languages": {
+      "zh-CN": "messages_zh_CN",
+      "en-US": "messages_en_US",
+      "ja-JP": "messages_ja_JP",
+      "ko-KR": "messages_ko_KR"
+    },
+    "projects": [
+      {
+        "projectId": 3,
+        "versions": [2, 29, 30, 31],
+        "tags": []
+      }
+    ],
+    "options": {
+      "properties": { "escape": "none" }
+    }
+  }
+]
+```
+
+关键点：
+
+- `tags: []` 表示不做标签过滤，项目级全量拉取（适用于没有平台标签的后端项目）
+- 语言映射的 value 是文件名前缀（不含 `.properties`），直接生成 `messages_zh_CN.properties`
+- `escape: "none"` 保持 UTF-8 原文，与 Spring Boot `MessageSource` 兼容
+- `outPath` 相对于 `.eevee/` 目录解析，`../` 可以跳出回到仓库根
+
+### .gitignore 追加
+
+```gitignore
+# eevee lint 本地快照；运行时 properties 由 sync.json 显式同步
+/.eevee/locales/
+```
+
+### 运行
+
+```bash
+# 预览运行时同步
+eevee intl download --config .eevee/sync.json --dry-run
+
+# 全量生成 properties
+eevee intl download --config .eevee/sync.json
+
+# lint（自动刷新快照 + 检查）
+eevee lint --staged --language java
+```
+
+---
+
+## 无标签项目的特殊处理
+
+如果 EEVEE 平台项目没有创建任何标签组：
+
+- `tags: []` → 项目级全量拉取
+- 省略 `tags` 且平台无标签 → 自动降级为项目级全量
+- `versions` 省略 → 拉取项目全部版本
+
+后端项目推荐显式配置 `versions`，避免新版本迁移后把未发布的 key 拉进当前分支。
+
+## 版本升级维护
+
+每次创建新 release 版本后：
+
+1. 在 EEVEE 通过 API 迁移增量词条
+2. 拿到新 version ID
+3. 追加到 `.eevee/sync.json` 和 `.eevee/download.json` 的 `versions` 数组
+4. 执行 `eevee intl download --config .eevee/sync.json` 刷新 properties
+
+## 常见问题
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| 未读取到任何 zh-CN*.json | `intl.json` 的 `outPaths` 路径不对 | 确认路径相对于 `intl.json` 所在目录 |
+| 平台返回 0 个词条 | 项目没有标签且未配置 `tags: []` | 显式设置 `"tags": []` |
+| token 过期 401 | `~/.eevee-cli/config.json` 里的 token 失效 | `eevee config set --token <new>` |
+| 全量 sync 后 diff 很大 | key 顺序按平台排序 | 一次性重排，后续 diff 只看新增/删除 |
+| properties 某行换行 | 翻译里含物理换行 | 已在 CLI 修复，确保使用最新版本 |