seeyon-skill-tools

Seeyon AI skills 通用 CLI。把散落在各 skill 里的辅助脚本收敛为一个零依赖、预编译的 npm 包，一次安装、跨客户端跨平台、每条命令几百毫秒跑通。

为什么

• 快：code-stats 从 npx tsx（每次现场转译 ~1.3s）改为纯 node bin（~0.1s），约 10x 提速
• 可靠的上报：skill-report 自动检测客户端/模型（env → 进程祖先链 → 客户端日志），无需 AI 猜
• 一次安装：全局 bin 覆盖机器上所有客户端（claude / codex / opencode / cursor / gemini …）和所有 skill

安装

① 全局 npm（在线首选）

npm i -g seeyon-skill-tools

② 离线 tarball（内网/断网）

npm pack seeyon-skill-tools     # 或在包目录 npm pack 生成 .tgz
npm i -g ./seeyon-skill-tools-<version>.tgz

③ 仓库内直跑（零安装兜底）

skills 仓库已在本机时，无需安装，直接：

node <skills-root>/.scripts/cli/bin/code-stats.mjs ...
node <skills-root>/.scripts/cli/bin/skill-report.mjs usage <skill>

首次配置

seeyon-skills setup

交互收集上报地址 / 企业邮箱 / 上报 token / GitLab 地址、token 和目标分支，先写入 ~/.seeyon-ai/config.json（权限 600，不入 git），再发一条 spec 测试上报验证连通性。验证失败会保留配置，方便修复网络或 token 后运行 seeyon-skills doctor 重测。

非交互：

seeyon-skills setup --yes \
  --report-url https://<host> --email [email protected] --token <report-token> \
  --gitlab-server https://gitlab.seeyon.com --gitlab-token <glpat> \
  --gitlab-target-branches standard-V10.x-develop,master \
  --gitlab-default-target standard-V10.x-develop

其他：seeyon-skills doctor（用现有配置复测）、seeyon-skills path（打印配置路径）。

命令

| 命令 | 用途 | 示例 | |------|------|------| | code-stats | Git 变更代码统计 | code-stats --repo . --mode all --format json | | gitlab-mr | 创建 GitLab MR | gitlab-mr --title "..." --description-file code-commit.md --skip-if-exists --output compact | | skill-report usage <skill> | skill 使用遥测 | skill-report usage spec | | skill-report spec --file <spec.md> | spec 上报 | skill-report spec --file changes/active/x/spec.md --story-no V5-123 | | seeyon-skills setup\|doctor\|path | 配置管理 | seeyon-skills setup |

配置文件

~/.seeyon-ai/config.json（可用 SEEYON_AI_CONFIG 覆盖路径）：

{
  "reportBaseUrl": "https://<host>",   // 上报地址
  "email": "[email protected]",          // 上报身份邮箱
  "token": "<report-token>",          // 上报 API token（Bearer）
  "gitlab": {
    "server": "https://gitlab.seeyon.com",
    "token": "<glpat>",
    "targetBranches": ["standard-V10.x-develop", "master"],
    "defaultTargetBranch": "standard-V10.x-develop"
  },
  "insecureTLS": false                // 服务端证书链不全时临时置 true
}

环境变量可覆盖：AI_REVIEW_SPEC_REPORT_BASE_URL、AI_REVIEW_REPORT_TOKEN、AI_REVIEW_REPORT_EMAIL、GITLAB_SERVER、GITLAB_TOKEN、AI_REVIEW_INSECURE_TLS。

旧版 ~/.claude/.code-commit.json 不再作为默认配置文件。gitlab-mr 和 merging-branches 首次运行时会把其中缺失的 GitLab 配置合并到 ~/.seeyon-ai/config.json，但不会自动删除旧文件。

从旧版 Toolkit 更新后，执行一次 node setup.js --cli，把最新的 seeyon-skill-tools 重新安装到全局命令目录。

预置默认值（团队统一项）

内部上报地址、共享 token 等团队统一项可放入预置文件，setup 时作为输入默认值（回车即采用），只需填个人邮箱。查找顺序：

1. seeyon-skills setup --preset <file>
2. 环境变量 SEEYON_AI_PRESET
3. ~/.seeyon-ai/preset.json（node setup.js 会自动从仓库 preset.json 部署到此处）

// preset.json（只作为 setup 输入默认值，非最终配置）
{ "reportBaseUrl": "https://ai-hub.seeyoncloud.com", "token": "<shared-token>" }

预置文件只存在于内部仓库和用户本机，不随公共 npm 包发布（包内不含任何内网地址/token）。

上报是 best-effort

skill-report 任何失败都静默退 0，绝不阻塞技能流程；未安装/未配置时跳过。可用 AI_REVIEW_SKILL_USAGE_DISABLED=1 关闭。

故障排查

| 现象 | 处理 | |------|------| | TLS 证书校验失败 | 服务端证书链不完整。正解：让服务端补全中间证书；或本机设 NODE_EXTRA_CA_CERTS=<CA文件>（安全）。临时：seeyon-skills setup --insecure，或 preset 里设 "insecureTLS": true（团队统一跳过校验）| | 上报 HTTP 401/403 | token 无效，重跑 seeyon-skills setup | | code-stats 找不到 | 未安装全局 bin，用仓库内 node .../bin/code-stats.mjs 兜底 | | 客户端显示 unknown | 当前客户端未暴露 env 且无法从进程链/日志识别；不影响上报本身 |

开发

零依赖、零构建：bin/*.mjs 为可执行入口，lib/*.mjs 为共享模块。Node ≥18。