sync-cli-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sync CLI Skill

同步CLI Skill

Synchronize the

skills/base44-cli/

skill with the latest CLI source code from the Base44 CLI repository using git-based change detection.

使用基于git的变更检测，将

skills/base44-cli/

skill与Base44 CLI仓库的最新CLI源代码同步。

Usage

使用说明

When activated, this skill will ask for:

CLI source folder path (required) - The local path to the Base44 CLI source code (must be a git repository)

启用后，本skill将要求提供以下信息：

CLI源码文件夹路径（必填）- Base44 CLI源码的本地路径（必须是git仓库）

How It Works

工作原理

This skill uses git to efficiently detect changes:

Reads the locally stored version from
```
CLI_VERSION
```
(e.g.,
```
v0.0.17
```
)
Compares against the CLI source repository to find changed command files
Only processes commands that have actually changed

本skill使用git高效检测变更：

从
```
CLI_VERSION
```
读取本地存储的版本（例如
```
v0.0.17
```
）
与CLI源码仓库进行对比，找出发生变更的命令文件
仅处理实际发生变更的命令

Steps

操作步骤

Step 1: Gather Input

步骤1：收集输入信息

Ask the user for the CLI source folder path using the AskQuestion tool if available, otherwise ask conversationally:

Required:

CLI source folder path (e.g.,

~/projects/base44-cli

/Users/me/base44-cli

)

If the user provided this in the initial prompt, use that value.

如果可用则使用AskQuestion工具向用户询问CLI源码文件夹路径，否则通过对话方式询问：

必填项：

CLI源码文件夹路径（例如

~/projects/base44-cli

或

/Users/me/base44-cli

）

如果用户在初始提示中已经提供了该路径，则直接使用该值。

Step 2: Validate Source Folder and Discover Structure

步骤2：验证源文件夹并识别目录结构

Check that the provided path exists and is a git repository (
```
.git/
```
directory exists)
Check for
```
package.json
```
with CLI-related content
Discover the commands directory - look for directories containing command files:
- Common patterns:
```
src/cli/commands/
```
  ,
```
src/commands/
```
  ,
```
commands/
```
  ,
```
lib/commands/
```
- Look for files with
```
.command(
```
  or
```
program.command
```
  patterns
Identify the CLI source root - the parent directory containing both commands and shared code

Store these discovered paths for use in subsequent steps:

```
<commands-path>
```
: Path to commands directory (e.g.,
```
src/cli/commands
```
)
```
<cli-root>
```
: Path to CLI source root (e.g.,
```
src/cli
```
)

If validation fails or structure is unclear, ask the user to clarify.

检查提供的路径是否存在，且为git仓库（存在
```
.git/
```
目录）
检查是否存在包含CLI相关内容的
```
package.json
```
文件
查找命令目录 - 查找包含命令文件的目录：
- 常见路径模式：
```
src/cli/commands/
```
  、
```
src/commands/
```
  、
```
commands/
```
  、
```
lib/commands/
```
- 查找包含
```
.command(
```
  或
```
program.command
```
  模式的文件
识别CLI源码根目录 - 同时包含命令代码和共享代码的父目录

将识别到的路径存储起来供后续步骤使用：

```
<commands-path>
```
：命令目录的路径（例如
```
src/cli/commands
```
）
```
<cli-root>
```
：CLI源码根目录的路径（例如
```
src/cli
```
）

如果验证失败或者目录结构不清晰，请要求用户澄清。

Step 3: Read Local Version and Detect Changes

步骤3：读取本地版本并检测变更

Read the stored version from
```
CLI_VERSION
```
in the skills repository root (e.g.,
```
v0.0.17
```
)

Get changed command files using git in the CLI source folder:

bash

# From the CLI source folder, list command files changed since the stored version
git diff --name-only <stored-version> HEAD -- <commands-path>

If the stored version tag doesn't exist, fall back to:

bash

# List all command files if tag is missing
git ls-files <commands-path>

Get infrastructure changes (CLI source root excluding commands):

bash

# From the CLI source folder, list infra files changed since the stored version
git diff --name-only <stored-version> HEAD -- <cli-root> | grep -v "<commands-path>"

Present findings to the user before proceeding:

Found X changed command files since vX.X.X:
- <commands-path>/deploy.ts
- <commands-path>/entities/push.ts
- <commands-path>/auth/login.ts

Found Y infrastructure changes (may affect all commands):
- <cli-root>/utils/api-client.ts
- <cli-root>/config/defaults.ts

If no changes detected (neither commands nor infra): Report "No changes since version X" and exit

读取存储的版本：从skill仓库根目录的
```
CLI_VERSION
```
文件中读取（例如
```
v0.0.17
```
）

获取变更的命令文件：在CLI源码文件夹中使用git命令获取：

bash

# 在CLI源码文件夹中，列出存储版本以来发生变更的命令文件
git diff --name-only <stored-version> HEAD -- <commands-path>

如果存储的版本标签不存在，则回退到以下命令：

bash

# 如果标签缺失则列出所有命令文件
git ls-files <commands-path>

获取基础设施变更（CLI源码根目录下除命令之外的内容）：

bash

# 在CLI源码文件夹中，列出存储版本以来发生变更的基础设施文件
git diff --name-only <stored-version> HEAD -- <cli-root> | grep -v "<commands-path>"

在继续操作前向用户展示检测结果：

自vX.X.X版本以来共检测到X个变更的命令文件：
- <commands-path>/deploy.ts
- <commands-path>/entities/push.ts
- <commands-path>/auth/login.ts

检测到Y个基础设施变更（可能影响所有命令）：
- <cli-root>/utils/api-client.ts
- <cli-root>/config/defaults.ts

如果未检测到任何变更（命令和基础设施都没有变更）：提示“自版本X以来无任何变更”并退出流程

Step 4: Check Infrastructure Changes

步骤4：检查基础设施变更

Before processing individual commands, review any infrastructure changes that may affect all commands:

在处理单个命令之前，先检查所有可能影响全部命令的基础设施变更：

What to Look For

需关注的变更类型

Review each changed non-command file and categorize by impact type:

Impact Type	What to look for	Documentation Action
API/Client changes	Base URLs, endpoints, headers, request/response handling	May affect multiple commands' behavior
Config/Defaults	Default values, environment variables, config file paths	Update SKILL.md config section
Authentication	Token handling, login flow, session management	Update auth-related references
Global options	CLI-wide flags like `--verbose` , `--json` , `--help`	Update SKILL.md global options
Output formatting	How results are displayed, logging behavior	Note in affected command references
Types/Interfaces	Shared type definitions	Usually internal, but may indicate API changes
Error handling	Exit codes, error messages, validation	Update troubleshooting section
Dependencies	`package.json` changes	Check for behavior-affecting updates

Note: The actual file structure varies by CLI. Discover the structure by examining the git diff output rather than assuming specific paths.

检查每个变更的非命令文件，按影响类型分类：

影响类型	需关注的变更	文档处理动作
API/客户端变更	基础URL、接口地址、请求头、请求/响应处理逻辑	可能影响多个命令的行为
配置/默认值	默认值、环境变量、配置文件路径	更新SKILL.md配置章节
鉴权逻辑	Token处理、登录流程、会话管理	更新鉴权相关的引用内容
全局选项	CLI全局参数，例如 `--verbose` 、 `--json` 、 `--help`	更新SKILL.md全局选项章节
输出格式	结果展示方式、日志行为	在受影响的命令引用中备注
类型/接口定义	共享类型定义	通常是内部变更，但可能暗示API发生了变化
错误处理	退出码、错误信息、校验逻辑	更新故障排查章节
依赖	`package.json` 变更	检查是否有影响行为的更新

注意：不同CLI的实际文件结构可能不同。请通过git diff输出来识别结构，不要假设固定路径。

How to Handle Infra Changes

处理基础设施变更的方法

Read each changed infra file to understand what changed
Identify cross-cutting impacts:
- New global options → Update SKILL.md "Global Options" section
- Changed defaults → Note in affected command references
- Auth flow changes → Update auth-related references
- New environment variables → Document in SKILL.md
- API endpoint changes → May affect multiple commands
Flag for SKILL.md update if the change affects:
- How users configure the CLI
- Prerequisites or setup steps
- Error messages users might see
- Output format

阅读每个变更的基础设施文件，理解变更内容
识别跨命令的影响：
- 新增全局选项 → 更新SKILL.md的“全局选项”章节
- 默认值变更 → 在受影响的命令引用中备注
- 鉴权流程变更 → 更新鉴权相关的引用内容
- 新增环境变量 → 在SKILL.md中添加文档说明
- API接口变更 → 可能影响多个命令
如果变更影响以下内容，则标记需要更新SKILL.md：
- 用户配置CLI的方式
- 前置条件或设置步骤
- 用户可能看到的错误信息
- 输出格式

Example Infrastructure Change

基础设施变更示例

Changed file: (some config/defaults file)

Before:
  export const DEFAULT_TIMEOUT = 30000;
  
After:
  export const DEFAULT_TIMEOUT = 60000;

Impact: All commands now have 60s timeout instead of 30s
Action: Update SKILL.md "Configuration" or "Troubleshooting" section

变更文件: (某个配置/默认值文件)

变更前:
  export const DEFAULT_TIMEOUT = 30000;
  
变更后:
  export const DEFAULT_TIMEOUT = 60000;

影响: 所有命令的默认超时时间从30秒改为60秒
处理动作: 更新SKILL.md的“配置”或“故障排查”章节

Step 5: Process Each Changed Command

步骤5：处理每个变更的命令

For each changed command file, perform the following steps:

对每个变更的命令文件，执行以下步骤：

Step 5a: Route Command to the Correct Skill

步骤5a：将命令路由到对应的Skill

Commands are split across skills by concern. Before reading or updating a reference, determine which skill owns the command.

Known command routing:

Command	Target Skill	Reason
`logs`	`skills/base44-troubleshooter/`	Troubleshooting / debugging concern
Everything else	`skills/base44-cli/`	Project management concern

For new/unknown commands, reason about ownership based on the command's purpose:

Concern	Target Skill	Examples
Observability, debugging, diagnostics, monitoring	`skills/base44-troubleshooter/`	`logs` , `monitor` , `status` , `health`
Project setup, resource management, deployment, auth	`skills/base44-cli/`	`create` , `deploy` , `entities push` , `login`

If a new command's purpose is ambiguous, read its source code and ask: "Would a developer use this to build/manage the app, or to investigate/debug it?" Route accordingly. When genuinely unclear, ask the user.

Use the target skill's

references/

folder for reading and writing reference files, and update that skill's

SKILL.md

command table accordingly.

命令按功能划分到不同的skill中。在读取或更新引用文档前，先确定该命令所属的skill。

已知的命令路由规则：

命令	目标Skill	原因
`logs`	`skills/base44-troubleshooter/`	属于故障排查/调试功能
其他所有命令	`skills/base44-cli/`	属于项目管理功能

对于新增/未知的命令，根据命令的用途判断归属：

功能分类	目标Skill	示例
可观测性、调试、诊断、监控	`skills/base44-troubleshooter/`	`logs` 、 `monitor` 、 `status` 、 `health`
项目初始化、资源管理、部署、鉴权	`skills/base44-cli/`	`create` 、 `deploy` 、 `entities push` 、 `login`

如果新命令的用途不明确，阅读其源码并思考：“开发者使用这个命令是为了构建/管理应用，还是为了排查/调试问题？” 据此进行路由。如果确实无法判断，询问用户。

使用目标Skill的

references/

文件夹来读写引用文件，并对应更新该Skill的

SKILL.md

命令表格。

Step 5b: Read Existing Skill Reference

步骤5b：读取现有的Skill引用文档

Read the corresponding reference file from the target skill's

references/

folder:

skills/base44-cli/                      <- project management commands
├── SKILL.md
└── references/
    ├── auth-login.md      <- for <commands-path>/auth/login.ts
    ├── auth-logout.md
    ├── auth-whoami.md
    ├── create.md          <- for <commands-path>/create.ts
    ├── deploy.md
    ├── entities-create.md <- for <commands-path>/entities/create.ts
    ├── entities-push.md
    ├── functions-create.md
    ├── functions-deploy.md
    ├── rls-examples.md
    └── site-deploy.md

skills/base44-troubleshooter/           <- troubleshooting commands
├── SKILL.md
└── references/
    └── project-logs.md    <- for <commands-path>/logs.ts (or similar)

Mapping rule:

<commands-path>/{parent}/{name}.ts

→

references/{parent}-{name}.md

If no reference file exists for a new command, note it for creation in the appropriate skill.

从目标Skill的

references/

文件夹中读取对应的引用文件：

skills/base44-cli/                      <- 项目管理命令
├── SKILL.md
└── references/
    ├── auth-login.md      <- 对应 <commands-path>/auth/login.ts
    ├── auth-logout.md
    ├── auth-whoami.md
    ├── create.md          <- 对应 <commands-path>/create.ts
    ├── deploy.md
    ├── entities-create.md <- 对应 <commands-path>/entities/create.ts
    ├── entities-push.md
    ├── functions-create.md
    ├── functions-deploy.md
    ├── rls-examples.md
    └── site-deploy.md

skills/base44-troubleshooter/           <- 故障排查命令
├── SKILL.md
└── references/
    └── project-logs.md    <- 对应 <commands-path>/logs.ts（或类似文件）

映射规则：

<commands-path>/{父目录}/{文件名}.ts

→

references/{父目录}-{文件名}.md

如果新命令没有对应的引用文件，标记需要在对应Skill中创建该文件。

Step 5c: Compare Source with Documentation

步骤5c：对比源码与文档

Compare the CLI source code with the existing skill documentation:

将CLI源码与现有Skill文档进行对比：

Extract from Source

从源码中提取信息

Parse the command file to extract:

Command name and aliases
Description/help text
Available options and flags (name, alias, description, default, required, type)
Usage examples (if present)
Subcommands

解析命令文件，提取以下内容：

命令名称和别名
描述/帮助文本
可用选项和参数（名称、别名、描述、默认值、是否必填、类型）
使用示例（如果存在）
子命令

Detect Changes

检测变更

Identify differences:

Command-Level:

New commands (source exists, no reference file)
Changed command descriptions

Option/Argument-Level (CRITICAL): 3. New options added 4. Removed options 5. Changed option descriptions 6. Changed option defaults 7. Changed option types (e.g., string to boolean) 8. Changed required status 9. Changed option aliases (e.g.,

-f

-F

) 10. Option converted to positional argument (e.g.,

create -n my-app

→

create my-app

) 11. Positional argument converted to option (e.g.,

create my-app

→

create -n my-app

)

Detecting Option ↔ Positional Changes:

Look for these patterns in Commander.js:

Named option:

.option('-n, --name <value>', 'description')

.requiredOption(...)

Positional argument:

.argument('<name>', 'description')

or in command definition

.command('create <name>')

When an option disappears but a positional argument with similar semantics appears (or vice versa), flag this as a breaking change that affects how users invoke the command.

识别差异点：

命令级别：

新增命令（源码存在，无对应的引用文件）
命令描述变更

选项/参数级别（关键变更）： 3. 新增选项 4. 删除选项 5. 选项描述变更 6. 选项默认值变更 7. 选项类型变更（例如从字符串改为布尔值） 8. 选项必填状态变更 9. 选项别名变更（例如

-f

改为

-F

） 10. 选项转换为位置参数（例如

create -n my-app

→

create my-app

） 11. 位置参数转换为选项（例如

create my-app

→

create -n my-app

）

Document the Comparison

检测选项↔位置参数的变更：

Command: deploy (<commands-path>/deploy.ts)

Source options:
  --force (-f): Force deployment [boolean, default: false]
  --env <name>: Target environment [string, required]

Documented options (references/deploy.md):
  --force (-f): Force deploy without confirmation [boolean, default: false]  
  --env <name>: Environment name [string, optional]

Changes detected:
  - --force: description changed
  - --env: required status changed (required vs optional)

Command: create (<commands-path>/create.ts)

Source (current):
  Positional: <name> - The app name [required]
  Options: --template (-t): Template to use [string, optional]

Documented (references/create.md):
  Options:
    -n, --name <name>: The app name [string, required]
    --template (-t): Template to use [string, optional]

Changes detected:
  - BREAKING: --name (-n) option converted to positional argument <name>
    Old syntax: npx base44 create -n my-app
    New syntax: npx base44 create my-app

在Commander.js中查找以下模式：

命名选项：

.option('-n, --name <value>', '描述')

或

.requiredOption(...)

位置参数：

.argument('<name>', '描述')

或在命令定义中

.command('create <name>')

如果某个选项消失了，但出现了语义相似的位置参数（反之亦然），标记为破坏性变更，会影响用户调用命令的方式。

Step 5d: Update Reference File

记录对比结果

Update or create

references/{command-name}.md

with the following format:

markdown

undefined

命令: deploy (<commands-path>/deploy.ts)

源码中的选项:
  --force (-f): 强制部署 [布尔值, 默认: false]
  --env <name>: 目标环境 [字符串, 必填]

文档中的选项 (references/deploy.md):
  --force (-f): 无需确认强制部署 [布尔值, 默认: false]  
  --env <name>: 环境名称 [字符串, 选填]

检测到的变更:
  - --force: 描述变更
  - --env: 必填状态变更（从选填改为必填）

命令: create (<commands-path>/create.ts)

源码（当前）:
  位置参数: <name> - 应用名称 [必填]
  选项: --template (-t): 使用的模板 [字符串, 选填]

文档（references/create.md）:
  选项:
    -n, --name <name>: 应用名称 [字符串, 必填]
    --template (-t): 使用的模板 [字符串, 选填]

检测到的变更:
  - 破坏性变更: --name (-n)选项转换为位置参数 <name>
    旧语法: npx base44 create -n my-app
    新语法: npx base44 create my-app

base44 {command}

步骤5d：更新引用文件

{Description from source}

按以下格式更新或创建

references/{命令名称}.md

：

markdown

undefined

Syntax

base44 {command}

bash

npx base44 {command} [options]

{源码中的描述}

Options

语法

Option	Description	Required
`-o, --option <value>`	{description}	{yes/no}

bash

npx base44 {command} [options]

Examples

选项

bash

{example usage from source}

选项	描述	是否必填
`-o, --option <value>`	{描述}	{是/否}

Notes

示例

{Any important behavioral notes}

undefined

bash

{源码中的使用示例}

Step 6: Update Main Skill Files (if needed)

注意事项

After processing all changed commands, update the SKILL.md of each affected skill:

For
skills/base44-cli/SKILL.md
(project management commands):

Update the Available Commands tables if commands were added/removed
Update Quick Start if workflow changed
Update Common Workflows sections if relevant

For
skills/base44-troubleshooter/SKILL.md
(troubleshooting commands):

Update the Available Commands table if troubleshooting commands were added/removed
Update the Troubleshooting Flow if command behavior changed

General rules:

Keep the existing structure and formatting of each skill
Do NOT change the frontmatter description unless explicitly asked

{任何重要的行为说明}

undefined

Step 7: Update CLI_VERSION and Skill Frontmatter

步骤6：更新主Skill文件（如有需要）

After successfully updating all changed commands:

Get the current version/commit from the CLI source:

bash

# Get latest tag, or HEAD commit if no tags
git describe --tags --always

Update
```
CLI_VERSION
```
in the skills repository root with the new version (e.g.,
```
v0.0.47
```
)
Update
```
metadata.sourcePackage
```
in
```
skills/base44-cli/SKILL.md
```
frontmatter. Set
```
name
```
to
```
base44
```
(the npm package being synced) and
```
version
```
to the new version without the
```
v
```
prefix (e.g.,
```
0.0.47
```
). Example:
yaml
```
metadata:
  sourcePackage:
    name: base44
    version: 0.0.47
```
This allows the Base44 CLI to detect when installed skills are out of date.

处理完所有变更的命令后，更新每个受影响Skill的SKILL.md：

针对
skills/base44-cli/SKILL.md
（项目管理命令）：

如果有新增/删除的命令，更新可用命令表格
如果工作流程发生变更，更新快速开始章节
如果有相关变更，更新常见工作流章节

针对
skills/base44-troubleshooter/SKILL.md
（故障排查命令）：

如果有新增/删除的故障排查命令，更新可用命令表格
如果命令行为发生变更，更新故障排查流程章节

通用规则：

保留每个Skill现有的结构和格式
除非明确要求，否则不要修改前言部分的描述

Step 8: Present Summary

步骤7：更新CLI_VERSION和Skill前言

After all updates, present a summary to the user:

undefined

成功更新所有变更的命令后：

从CLI源码中获取当前版本/提交哈希：

bash

# 获取最新标签，如果没有标签则获取HEAD提交哈希
git describe --tags --always

用新版本更新Skill仓库根目录的
```
CLI_VERSION
```
文件（例如
```
v0.0.47
```
）
更新
```
skills/base44-cli/SKILL.md
```
前言中的
```
metadata.sourcePackage
```
。将
```
name
```
设置为
```
base44
```
（正在同步的npm包名），
```
version
```
设置为不带
```
v
```
前缀的新版本号（例如
```
0.0.47
```
）。示例：
yaml
```
metadata:
  sourcePackage:
    name: base44
    version: 0.0.47
```
这可以让Base44 CLI检测到已安装的Skill是否过时。

Sync Summary

步骤8：展示同步总结

Version Updated

—

Previous: v0.0.17
Current: v0.0.20

完成所有更新后，向用户展示总结：

undefined

Changed Command Files Processed

同步总结

—

版本更新

<commands-path>/deploy.ts
<commands-path>/entities/push.ts

之前版本: v0.0.17
当前版本: v0.0.20

Infrastructure Changes Reviewed

已处理的变更命令文件

(list infra files from git diff output)
Example: config.ts (timeout increased to 60s)
Example: api-client.ts (no user-facing changes)

<commands-path>/deploy.ts
<commands-path>/entities/push.ts

Files Updated

已检查的基础设施变更

references/deploy.md (updated options)
references/entities-push.md (updated description)
SKILL.md (updated command table, added timeout note)
CLI_VERSION (v0.0.17 → v0.0.20)
skills/base44-cli/SKILL.md frontmatter metadata.sourcePackage.version (0.0.17 → 0.0.20)

(列出git diff输出中的基础设施文件)
示例: config.ts (超时时间增加到60秒)
示例: api-client.ts (无面向用户的变更)

Breaking Changes (highlight prominently)

已更新的文件

create

-n, --name

option converted to positional argument

Old:
```
npx base44 create -n my-app
```
New:
```
npx base44 create my-app
```

references/deploy.md (更新了选项)
references/entities-push.md (更新了描述)
SKILL.md (更新了命令表格，添加了超时说明)
CLI_VERSION (v0.0.17 → v0.0.20)
skills/base44-cli/SKILL.md 前言 metadata.sourcePackage.version (0.0.17 → 0.0.20)

Option Changes

破坏性变更（重点高亮）

```
deploy --env
```
: now required (was optional)
```
entities push --dry-run
```
: default changed from true to false

create

-n, --name

选项转换为位置参数

旧语法:
```
npx base44 create -n my-app
```
新语法:
```
npx base44 create my-app
```

New Commands

选项变更

(none)

```
deploy --env
```
: 现在为必填项（之前是选填）
```
entities push --dry-run
```
: 默认值从true改为false

Removed Commands

新增命令

(none)

Manual Review Recommended

已删除命令

[List any changes that need verification]

undefined

Important Notes

建议手动审核

Git-based detection: This skill relies on git tags/commits to detect changes. Ensure the CLI source folder is a valid git repository.
Preserve existing content: Don't remove detailed explanations, examples, or warnings unless they're outdated
Keep formatting consistent: Match the existing style of SKILL.md and reference files
Maintain progressive disclosure: Keep detailed docs in references, summaries in SKILL.md
Flag uncertainties: If source code is unclear, flag it for manual review
Respect RLS/FLS docs: The
```
entities-create.md
```
and
```
rls-examples.md
```
contain hand-written security documentation - update carefully

[列出所有需要验证的变更]

undefined

Troubleshooting

重要注意事项

Issue	Solution
Tag not found in CLI repo	Use `git tag -l` to list available tags, or fall back to comparing with a commit hash
Infra changes not detected	Check if shared code is in non-standard directories; adjust the git diff paths
Unsure if infra change affects users	Look for exports used by command files; if internal-only, note but skip documentation
Can't find command files	Try searching for `.command(` or `program.command` patterns
Options not detected	Look for `.option(` patterns in commander.js files
Positional args not detected	Look for `.argument(` or `<argName>` in `.command('cmd <argName>')` patterns
Option → positional change missed	Compare old options list with new arguments list; if an option disappeared and a similar argument appeared, it's likely a conversion
Missing descriptions	Check for `description:` properties or `.description(` calls
Subcommand structure	Commands like `entities push` may be in `entities/push.ts`
Changed args not detected	Compare each option property: name, alias, description, default, required, type
No changes detected but expected	Verify the stored version in `CLI_VERSION` matches a valid git tag/commit

基于Git的检测: 本Skill依赖git标签/提交来检测变更，请确保CLI源码文件夹是有效的git仓库。
保留现有内容: 不要删除详细的说明、示例或警告，除非它们已经过时
保持格式一致: 匹配SKILL.md和引用文件的现有样式
保持渐进式披露: 详细文档放在references中，摘要放在SKILL.md中
标记不确定点: 如果源码内容不明确，标记为需要手动审核
谨慎处理RLS/FLS文档:
```
entities-create.md
```
和
```
rls-examples.md
```
包含手写的安全文档，更新时请谨慎

—

故障排查

—

问题	解决方案
CLI仓库中找不到标签	使用 `git tag -l` 列出可用标签，或者回退到与提交哈希对比
未检测到基础设施变更	检查共享代码是否在非标准目录中；调整git diff的路径
不确定基础设施变更是否影响用户	查找命令文件使用的导出内容；如果是内部变更，备注即可，无需更新文档
找不到命令文件	尝试搜索 `.command(` 或 `program.command` 模式
未检测到选项	在Commander.js文件中查找 `.option(` 模式
未检测到位置参数	查找 `.argument(` 或 `.command('cmd <argName>')` 中的 `<argName>` 模式
遗漏了选项→位置参数的变更	对比旧的选项列表和新的参数列表；如果某个选项消失了，同时出现了相似的参数，很可能是发生了转换
缺少描述	查找 `description:` 属性或 `.description(` 调用
子命令结构	类似 `entities push` 的命令可能存放在 `entities/push.ts` 中
未检测到参数变更	对比每个选项的属性：名称、别名、描述、默认值、是否必填、类型
预期有变更但未检测到	验证 `CLI_VERSION` 中存储的版本是否对应有效的git标签/提交