cli-self-check

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cli-self-check

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

The "new function rationality" self-check skill for te-cli. It solidifies the structured checks repeatedly used in manual code reviews into executable scripts + judgment rules.

何时用

When to Use

合并了新的命令域（
```
src/commands/te-*
```
）或新命令
新增 / 修改了
```
skills/
```
下的 skill
发版前自检、或评估某分支 CLI 功能是否「做完整了」

Merged new command domains (
```
src/commands/te-*
```
) or new commands
Added/modified skills under
```
skills/
```
Pre-release self-check, or evaluating whether the CLI functions of a branch are "fully implemented"

怎么跑

How to Run

bash

undefined

bash

undefined

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

Full scan (recommended for pre-release)

node self-check/scan.mjs

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

Only check changed domains relative to a branch (recommended after merging/PR, focus on current changes)

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

机器可读，便于接 CI

Machine-readable, suitable for CI integration

node self-check/scan.mjs --json


退出码：存在 **P1** 时返回 `1`，否则 `0`，可直接用于 CI 卡口。

> 脚本是纯 Node、零新依赖、只读不改仓库。判读和修复由你（agent）依据下方规则完成——脚本负责「发现」，你负责「确认 + 修」。

node self-check/scan.mjs --json


Exit code: Returns `1` when **P1** issues exist, otherwise `0`, which can be directly used for CI checks.

> The script is pure Node, zero new dependencies, read-only and does not modify the repository. Judgment and repair are done by you (agent) based on the rules below—the script is responsible for "discovering", and you are responsible for "confirming + fixing".

六个检测维度

Six Detection Dimensions

维度	名称	查什么	漏了会怎样
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；版本号 vs CHANGELOG	用户照 README 用，以为新功能不存在
D6	工程健壮性	每个域是否有 verify 脚本；是否接入 `tsc --noEmit`	回归无自动拦截；类型错误只在 build 暴露

Dimension	Name	What to Check	Consequences of Missing
D1	Command Registration	Whether the new domain is registered in `src/index.ts` ; whether the MCP service has registered mapping	The command does not load at all; `buildMcpUrl` throws an error at runtime
D2	Domain ↔ Skill Pairing	Whether each business domain has a corresponding skill; tool commands should not have skills	The agent doesn't know how to use the new command
D3	Skill Document Coverage	Whether commands ↔ `references/*.md` are in one-to-one correspondence	The agent lacks command documents and is forced to guess parameters
D4	Skill Internal Consistency	Whether the CRITICAL rule "+cmd→cmd.md" matches the actual filename; whether links in SKILL.md are invalid	The agent reads empty documents according to the rules and guesses IDs/parameters randomly
D5	Document Synchronization	Whether README (Chinese/English) covers all services; version number vs CHANGELOG	Users follow the README and think the new function doesn't exist
D6	Engineering Robustness	Whether each domain has a verify script; whether it is connected to `tsc --noEmit`	No automatic interception for regression; type errors are only exposed during build

严重度与处理原则

Severity and Handling Principles

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

🔴 P1 (Blocking)：Will cause command loading failure, or agent behavior errors (reading empty documents → random guessing). Must be fixed, CI should block.
🟡 P2 (Obvious deviation for users/agents)：Missing/outdated documents, invalid links. Should be fixed before release.
🟢 P3 (Engineering Robustness)：Gaps in verify/typecheck, inconsistent styles. Fix at an optional time, does not block release.
ℹ️ info：Confirmation items that comply with conventions (e.g., tool commands have no skills), no handling required.

各维度判读 + 修复指引

Judgment + Repair Guidelines for Each Dimension

D1 命令注册

D1 Command Registration

「域未在 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
```
）。脚本只检查后者，且只提取字面量传参；变量传参不报（宁可漏报不误报）。

"Domain not registered in src/index.ts": Add
```
import('./commands/<dir>/index.js')
```
to
```
loadCommands()
```
(business domains) or
```
registerXxxCommand()
```
(tool commands) in
```
src/index.ts
```
.
"MCP service not registered with mapping": Call
```
registerMcpMappings({ '<service>': { componentName, mappingPath } })
```
at the top of the domain
```
index.ts
```
that still uses MCP transport (refer to
```
te-community/index.ts
```
). The Analysis domain only allows Capability Gateway and should not register MCP mapping.
Note the difference between two types of "service": commander group name (e.g.,
```
engage
```
) ≠ MCP routing key (e.g.,
```
engage_config
```
). The script only checks the latter and only extracts literal parameters; variable parameters are not reported (prefer under-reporting over false positives).

D2 域↔skill 配对

D2 Domain ↔ Skill Pairing

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

Convention: Business domains are paired with skills, tool commands (interactive/operation and maintenance) are not. It is correct that
```
sync
```
,
```
model
```
,
```
auth
```
,
```
config
```
,
```
api
```
have no skills.
If a new business domain is added, register the mapping in
```
DOMAIN_TO_SKILL
```
at the top of
```
scan.mjs
```
; register new tool commands in
```
TOOL_DIRS
```
. Missing registration will be reported as P2, reminding you to supplement the mapping or confirm the classification.

D3 skill 文档覆盖

D3 Skill Document Coverage

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

Judgment uses "normalization + inclusion" matching, which can recognize that
```
create-team.md
```
covers
```
+create
```
, so what is reported here is genuine missing documents.
Fix method: Add a
```
.md
```
file in
```
references/
```
of the corresponding skill, and add a link in the command list in SKILL.md.
Skills that adopt the "group/inline document" strategy (
```
ae-dataops
```
,
```
ae-kb
```
) are exempt from per-command checks in
```
GROUPED_DOC_SKILLS
```
—if a new skill also uses this strategy, add it to the list.

D4 skill 内部一致性（最易出 P1）

D4 Skill Internal Consistency (Most Prone to 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
```
指向的文件不存在——补文件或修链接。

Rule Conflict: If the top of SKILL.md states "reference filename equals the command name (+cmd → references/cmd.md)", then every command must have a strictly identically named file. If the document for
```
+list
```
is named
```
list-teams.md
```
, the agent will try to read the non-existent
```
list.md
```
.
- Two Fix Methods (choose one): ① Rename the file to be strictly identical to the command (
```
list.md
```
  ) — recommended, as the rule is most self-consistent; ② Rewrite the top rule to "follow the links in the command list below" and delete the assertion that "filename = command name".
Invalid Links: The
```
references/xxx.md
```
links in SKILL.md point to non-existent files — supplement the files or fix the links.

D5 文档同步

D5 Document Synchronization

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

New domains/new commands should be synchronized to the command tables in
```
README.md
```
and
```
README.zh.md
```
.
The version number must have a corresponding entry in CHANGELOG.md during release.

D6 工程健壮性

D6 Engineering Robustness

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

It is recommended to add a
```
scripts/verify-te-<domain>.mjs
```
for new domains (refer to the existing
```
verify-te-analysis-tools.mjs
```
: traverse command source code and verify registration, flags, description and document contracts), and add a
```
verify:<domain>
```
script in
```
package.json
```
.
It is recommended to add
```
"typecheck": "tsc --noEmit"
```
to move type checking forward from build.

维护脚本

Maintain the Script

scan.mjs

顶部有可调配置，新增模块时按需更新：

```
DOMAIN_TO_SKILL
```
：业务域目录 → skill 名映射
```
COMMAND_SKILL_OVERRIDES
```
：同一命令域内由 overlay skill 负责的命令路径 → skill 名映射
```
TOOL_DIRS
```
：工具命令目录（豁免 skill 检查）
```
GROUPED_DOC_SKILLS
```
：走分组/内联文档策略的 skill（豁免逐命令 reference 检查）

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

There are adjustable configurations at the top of

scan.mjs

, update as needed when adding modules:

```
DOMAIN_TO_SKILL
```
: Mapping from business domain directory → skill name
```
COMMAND_SKILL_OVERRIDES
```
: Mapping from command paths in the same command domain that are handled by overlay skills → skill name
```
TOOL_DIRS
```
: Tool command directories (exempt from skill checks)
```
GROUPED_DOC_SKILLS
```
: Skills that adopt the group/inline document strategy (exempt from per-command reference checks)

Judgment Philosophy: The script only reports clues that "are worth a human look", and confirmation and repair are done by the agent combined with the source code. When adding new detection dimensions, prioritize ensuring zero false positives — a false P1 is more harmful to tool credibility than under-reporting.