SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cli-self-check

cli-self-check

测试与质量

查看项目

更新于 10-15 14:57

技能介绍

cli-self-check 是 te-cli 的「新功能合理性」自检 skill，把一次人工 code review 中反复用到的结构化检查固化成可重复执行的脚本加判读规则。

用途

用于检测新合并到 te-cli 的 CLI 功能是否合理。适用场景包括：合并了新的命令域（src/commands/te-*）或新命令；新增或修改了 skills/ 下的 skill；发版前自检，或评估某分支 CLI 功能是否「做完整了」。

主要能力

从六个维度扫描：

  • D1 命令注册：新域是否在 src/index.ts 注册；MCP service 是否注册了 mapping。漏了会导致命令根本不加载，或 buildMcpUrl 运行时抛错。
  • D2 域与 skill 配对：每个业务域是否有对应 skill；工具命令不应有 skill。漏了会导致 agent 不知道怎么用新命令。
  • D3 skill 文档覆盖：命令与 references/*.md 是否一一对应。漏了会导致 agent 缺命令文档，被迫猜参数。
  • D4 skill 内部一致性：CRITICAL 规则「+cmd→cmd.md」是否与真实文件名相符；SKILL.md 内链接是否失效。漏了会导致 agent 按规则去读文档却读空，瞎猜 ID 或参数。
  • D5 文档同步：README（中/英）是否覆盖所有 service；版本号与 CHANGELOG 是否对应。漏了会导致用户照 README 用，以为新功能不存在。
  • D6 工程健壮性：每个域是否有 verify 脚本；是否接入 tsc --noEmit。漏了会导致回归无自动拦截，类型错误只在 build 暴露。

使用方式

全量扫描（推荐发版前用）：

node self-check/scan.mjs

只看相对某分支的变更域（推荐合并或提 PR 后用，聚焦本次改动）：

node self-check/scan.mjs --since master

机器可读，便于接 CI：

node self-check/scan.mjs --json

退出码：存在 P1 时返回 1，否则 0，可直接用于 CI 卡口。脚本是纯 Node、零新依赖、只读不改仓库。判读和修复由 agent 依据规则完成——脚本负责「发现」，agent 负责「确认加修」。

严重度与处理原则

  • P1（阻断）：会导致命令加载失败，或 agent 行为出错（读空文档导致瞎猜）。必须改，CI 应卡。
  • P2（面向用户或 agent 的明显偏差）：文档缺失或滞后、失效链接。发版前应改。
  • P3（工程健壮性）：verify 或 typecheck 缺口，风格不统一。择期补，不阻断发版。
  • info：符合约定的确认项（如工具命令无 skill），无需处理。

各维度判读与修复指引

D1 命令注册：若「域未在 src/index.ts 注册」，在 src/index.ts 的 loadCommands()（业务域）或 registerXxxCommand()（工具命令）补上 import('./commands/<dir>/index.js')。若「MCP service 未注册 mapping」，在仍使用 MCP transport 的域 index.ts 顶部调 registerMcpMappings({ '<service>': { componentName, mappingPath } })（参考 te-community/index.ts）。Analysis 域只允许 Capability Gateway，不应注册 MCP mapping。注意区分两种 service：commander 分组名（如 engage）不等于 MCP 路由 key（如 engage_config）。脚本只检查后者，且只提取字面量传参；变量传参不报（宁可漏报不误报）。

D2 域与 skill 配对：约定业务域配 skill，工具命令（交互式或运维）不配。sync、model、auth、config、api 无 skill 是正确的。若新增业务域，需在 scan.mjs 顶部 DOMAIN_TO_SKILL 里登记映射；新增工具命令登记到 TOOL_DIRS。漏登记会被报 P2，提醒补映射或确认归类。

D3 skill 文档覆盖：判定用「归一化加包含」匹配，能识别 create-team.md 覆盖 +create，所以这里报的是真缺文档。修法：在对应 skill 的 references/ 补 .md，并在 SKILL.md 命令清单里挂上链接。采用「分组或内联文档」策略的 skill（ae-dataops、ae-kb）在 GROUPED_DOC_SKILLS 中豁免逐命令检查——若新 skill 也走这种策略，加进去。

D4 skill 内部一致性（最易出 P1）：规则矛盾方面，SKILL.md 顶部若写「reference filename equals the command name（+cmd → references/cmd.md）」，则每个命令都必须有严格同名文件。若 +list 的文档叫 list-teams.md，agent 会去读不存在的 list.md。两种修法择一：① 把文件重命名为与命令严格同名（list.md），推荐，规则最自洽；② 改写顶部规则为「以下方命令清单中的链接为准」，删掉「filename = command name」的断言。失效链接方面，SKILL.md 里 references/xxx.md 指向的文件不存在，需补文件或修链接。

D5 文档同步：新域或新命令要同步进 README.md 和 README.zh.md 的命令表。发版时版本号要在 CHANGELOG.md 有对应条目。

D6 工程健壮性：新域建议补一个 scripts/verify-te-<domain>.mjs（参考现有 verify-te-analysis-tools.mjs：遍历命令源码并校验注册、flag、description 和文档契约），并在 package.json 加 verify:<domain> 脚本。建议加 "typecheck": "tsc --noEmit"，把类型检查从 build 前移。

维护脚本

scan.mjs 顶部有可调配置，新增模块时按需更新：DOMAIN_TO_SKILL（业务域目录到 skill 名映射）、COMMAND_SKILL_OVERRIDES（同一命令域内由 overlay skill 负责的命令路径到 skill 名映射）、TOOL_DIRS（工具命令目录，豁免 skill 检查）、GROUPED_DOC_SKILLS（走分组或内联文档策略的 skill，豁免逐命令 reference 检查）。

判读哲学：脚本只报「值得人看一眼」的线索，确认与修复由 agent 结合源码做。新增检测维度时，优先保证零误报——一个假 P1 比漏报更伤工具可信度。

限制

脚本为只读工具，不修改仓库；判读和修复需由 agent 依据规则完成。脚本只提取字面量传参，变量传参不报。关于收费、价格、平台支持等信息，资料暂未提供。