sync-cli-skill

同步 CLI 技能

使用基于 git 的变更检测，将 skills/base44-cli/ 技能与 Base44 CLI 仓库中的最新 CLI 源代码同步。

用法

激活此技能后，它会询问：

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

工作原理

此技能使用 git 高效检测变更：

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

步骤

第 1 步：收集输入

如果有 AskQuestion 工具，请使用该工具询问用户 CLI 源代码文件夹路径；否则，通过对话询问：

必填：

• CLI 源代码文件夹路径（例如，~/projects/base44-cli 或 /Users/me/base44-cli）

如果用户已在初始提示中提供此路径，请使用该值。

第 2 步：验证源文件夹并发现结构

1. 检查提供的路径是否存在，以及是否为 git 仓库（存在 .git/ 目录）
2. 检查是否有包含 CLI 相关内容的 package.json
3. 发现命令目录——查找包含命令文件的目录：
   • 常见模式：src/cli/commands/、src/commands/、commands/、lib/commands/
   • 查找包含 .command( 或 program.command 模式的文件
4. 确定 CLI 源代码根目录——包含命令和共享代码的父目录

保存这些已发现的路径，以便在后续步骤中使用：

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

如果验证失败或结构不明确，请让用户说明情况。

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

1. 从技能仓库根目录中的 CLI_VERSION 读取存储的版本（例如，v0.0.17）

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

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

   如果不存在已存储的版本标签，则回退到：

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

3. 获取基础设施变更（CLI 源代码根目录中除命令以外的文件）：

   # 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>"
   

4. 向用户展示检查结果，然后再继续：

   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
   

5. 如果未检测到变更（命令和基础设施均无变更）：报告“自版本 X 起无变更”并退出

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

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

需要检查的内容

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

影响类型	检查内容	文档操作
API/客户端变更	基础 URL、端点、标头、请求/响应处理	可能影响多个命令的行为
配置/默认值	默认值、环境变量、配置文件路径	更新 SKILL.md 配置部分
身份验证	令牌处理、登录流程、会话管理	更新身份验证相关引用
全局选项	CLI 级标记，如 --verbose、--json、--help	更新 SKILL.md 全局选项
输出格式	结果的显示方式、日志行为	在受影响命令的引用中注明
类型/接口	共享类型定义	通常属于内部内容，但可能表明 API 有变更
错误处理	退出代码、错误消息、验证	更新故障排除部分
依赖项	package.json 变更	检查是否有影响行为的更新

注意：实际文件结构因 CLI 而异。请通过检查 git diff 输出来发现结构，不要预设特定路径。

如何处理基础设施变更

1. 阅读每个已变更的基础设施文件，了解变更内容
2. 识别跨领域影响：
   • 新增全局选项 → 更新 SKILL.md 中的“全局选项”部分
   • 默认值变更 → 在受影响的命令参考文档中注明
   • 身份验证流程变更 → 更新身份验证相关参考文档
   • 新增环境变量 → 在 SKILL.md 中记录
   • API 端点变更 → 可能影响多个命令
3. 如果变更影响以下内容，则标记为需要更新 SKILL.md：
   • 用户配置 CLI 的方式
   • 前置条件或设置步骤
   • 用户可能看到的错误消息
   • 输出格式

基础设施变更示例

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

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

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

步骤 5a：将命令路由到正确的技能

命令按关注领域分配到不同技能。在阅读或更新参考文档之前，先确定哪个技能负责该命令。

已知命令路由：

命令	目标技能	原因
logs	skills/base44-troubleshooter/	故障排查 / 调试相关
其他所有命令	skills/base44-cli/	项目管理相关

对于新命令或未知命令，根据命令用途判断其归属：

关注领域	目标技能	示例
可观测性、调试、诊断、监控	skills/base44-troubleshooter/	logs、monitor、status、health
项目设置、资源管理、部署、身份验证	skills/base44-cli/	create、deploy、entities push、login

如果新命令的用途不明确，请阅读其源代码并思考：**“开发者会用它来构建 / 管理应用，还是调查 / 调试问题？”**据此确定路由。如果确实无法判断，请询问用户。

使用目标技能的 references/ 文件夹读取和编写参考文件，并相应更新该技能的 SKILL.md 命令表。

步骤 5b：阅读现有技能参考文档

从目标技能的 references/ 文件夹中阅读对应的参考文件：

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)

映射规则：<commands-path>/{parent}/{name}.ts → references/{parent}-{name}.md

如果新命令没有对应的参考文件，请记录下来，以便在适当的技能中创建。

步骤 5c：将源代码与文档进行比较

将 CLI 源代码与现有技能文档进行比较：

从源代码中提取

解析命令文件并提取：

• 命令名称和别名
• 描述 / 帮助文本
• 可用选项和标志（名称、别名、描述、默认值、是否必需、类型）
• 用法示例（如有）
• 子命令

检测变更

找出差异：

命令级别：

1. 新增命令（存在源文件，但没有参考文件）
2. 命令描述变更

选项 / 参数级别（重要）： 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）

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

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

• 命名选项：.option('-n, --name <value>', 'description') 或 .requiredOption(...)
• 位置参数：.argument('<name>', 'description') 或命令定义中的 .command('create <name>')

当某个选项消失，而语义相近的位置参数出现时（反之亦然），请将其标记为影响命令调用方式的破坏性变更。

记录比较结果

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

步骤 5d：更新参考文件

按以下格式更新或创建 references/{command-name}.md：

# base44 {command}

{Description from source}

## Syntax

```bash
npx base44 {command} [options]

选项

选项	描述	必填
-o, --option <value>	{description}	{yes/no}

示例

{example usage from source}

备注

{Any important behavioral notes}

### 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):
1. Update the **Available Commands** tables if commands were added/removed
2. Update **Quick Start** if workflow changed
3. Update **Common Workflows** sections if relevant

**For `skills/base44-troubleshooter/SKILL.md`** (troubleshooting commands):
1. Update the **Available Commands** table if troubleshooting commands were added/removed
2. 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

### Step 6b: Flag base44-sandbox for review

The `skills/base44-sandbox/` skill (the cloud-sandbox flavor) is **hand-authored** and self-contained — it carries its own concise guidelines and links out to `base44-cli`'s references rather than copying them, so this sync does not edit it automatically. If this sync changed the backend-function authoring conventions in `skills/base44-cli/references/functions-create.md` (directory layout, `function.jsonc` shape, entry-point conventions, naming rules), **flag `skills/base44-sandbox/SKILL.md` for manual review** in the summary so its inline guidance can be updated to match.

### Step 7: Update CLI_VERSION and Skill Frontmatter

After successfully updating all changed commands:

1. Get the current version/commit from the CLI source:
   ```bash
   # Get latest tag, or HEAD commit if no tags
   git describe --tags --always

2. 在 skills 仓库根目录中更新 CLI_VERSION，设置为新版本（例如，v0.0.47）

3. 更新 skills/base44-cli/SKILL.md frontmatter 中的 metadata.sourcePackage。将 name 设置为 base44（正在同步的 npm 包），并将 version 设置为不带 v 前缀的新版本（例如，0.0.47）。示例：

   metadata:
     sourcePackage:
       name: base44
       version: 0.0.47
   

   这样，Base44 CLI 就能检测已安装的技能是否已过期。

第 8 步：提供摘要

完成所有更新后，向用户提供摘要：

## Sync Summary

### Version Updated
- Previous: v0.0.17
- Current: v0.0.20

### Changed Command Files Processed
- <commands-path>/deploy.ts
- <commands-path>/entities/push.ts

### 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)

### 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)

### 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`

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

### New Commands
- (none)

### Removed Commands  
- (none)

### Manual Review Recommended
- [List any changes that need verification]

重要备注

• 基于 Git 的检测：此技能依赖 Git 标签/提交来检测更改。请确保 CLI 源文件夹是有效的 Git 仓库。
• 保留现有内容：除非详细说明、示例或警告已过时，否则不要删除它们
• 保持格式一致：遵循 SKILL.md 和参考文件的现有风格
• 保持渐进式披露：详细文档放在参考文件中，摘要放在 SKILL.md 中
• 标记不确定之处：如果源代码不明确，请标记出来以供人工审核
• 遵循 RLS/FLS 文档要求：entities-create.md 和 rls-examples.md 包含手工编写的安全文档，请谨慎更新

故障排除

问题	解决方案
在 CLI 仓库中找不到标签	使用 git tag -l 列出可用标签，或改为与提交哈希进行比较
未检测到基础设施更改	检查共享代码是否位于非标准目录中；调整 git diff 路径
不确定基础设施更改是否会影响用户	查找命令文件使用的导出项；如果仅供内部使用，请记录但跳过文档更新
找不到命令文件	尝试搜索 .command( 或 program.command 模式
未检测到选项	在 commander.js 文件中查找 .option( 模式
未检测到位置参数	在 .command('cmd <argName>') 模式中查找 .argument( 或 <argName>
未发现选项 → 位置参数的变更	将旧选项列表与新参数列表进行比较；如果某个选项消失且出现了类似的参数，则很可能是转换
缺少描述	检查 description: 属性或 .description( 调用
子命令结构	entities push 等命令可能位于 entities/push.ts 中
未检测到参数变更	比较每个选项属性：名称、别名、描述、默认值、必填状态、类型
未检测到预期中的更改	确认 CLI_VERSION 中存储的版本与有效的 Git 标签/提交匹配