audit-clerk-skill

Clerk CLI 技能审计

对照实际的 Clerk CLI 源码，检查此仓库中的 skills/clerk-cli/，并针对技能文档与源码不一致之处提出精确的修改建议。CLI 是事实依据；技能文档是维护者文档，必须与 CLI 保持同步。

此任务需要完整的命令清单，不能只快速搜索一遍。先建立源码模型，再将其与技能文档中的现有说法进行比较。

输入

• CLI 事实来源：一个 clerk/cli 检出版本，其中包含 packages/cli-core/src/commands/**，以及 packages/cli-core/src/cli.ts、cli-program.ts、mode.ts 和 packages/cli-core/src/lib/ 中引用的任何文件。
• 目标技能：skills/clerk-cli/SKILL.md 和 skills/clerk-cli/references/*.md。

源码检出版本解析

按以下顺序解析 CLI 源码检出版本：

1. 如果提供了 --source <path>，则使用该路径。该路径必须包含 packages/cli-core/src/commands/。
2. 如果当前仓库本身包含 packages/cli-core/src/commands/，则使用当前仓库根目录。
3. 如果设置了 CLERK_CLI_REPO，则使用该路径。如果变量值包含敏感路径片段，不要打印该值。
4. 在 Conductor 中，查找唯一一个匹配 ../cli/*/packages/cli-core/src/commands/ 的同级工作区。如果匹配到多个，请询问要使用哪一个。
5. 如果没有可用的检出版本，并且任务允许访问网络，则将公开的 CLI 仓库克隆到 .context/clerk-cli-source：

mkdir -p .context
cd .context
git clone --depth 1 https://github.com/clerk/cli.git clerk-cli-source

如果以上方法均不可用，请停止并向用户索要 CLI 源码路径。不要仅依据已安装的 clerk 二进制文件进行审计，因为该二进制文件可能已过时，也不会暴露所有源码级分支。

工作流程

1. 整理 CLI 命令清单

遍历 packages/cli-core/src/commands/ 并建立结构化清单。对于每个顶层命令和子命令，记录：

• 完整命令路径，例如 clerk config patch 或 clerk api ls。
• 用途，取自源码中的命令描述或帮助字符串。
• 标志，包括短格式、类型、默认值和破坏性行为。
• 命令覆盖默认值时使用的退出代码。
• 由 isAgentMode()、CLERK_MODE、TTY 检测或相关辅助函数控制的 Agent 模式分支。
• 命令是否会修改远程状态，以及是否需要 --dry-run、--yes 或生产环境目标指引。

将 packages/cli-core/src/commands/<name>/README.md 仅作为辅助背景信息来阅读。利用这些文件标记模拟或存根命令，并交叉核对 references/recipes.md 中有关 API 端点的说法。不要建议将命令 README 复制到此仓库；这些文件包含内部实现细节，会使技能文档变得冗长。

同时记录跨命令行为：

• Runner 优先级逻辑，包括锁文件到包管理器 Runner 的映射。
• 身份验证、密钥解析、--app 和 --instance 目标选择。
• doctor 检查项和 --json 输出格式。
• Agent 模式下提示、JSON 默认值、打开浏览器、OAuth 回调、部署移交和沙盒警告的行为。
• 如果技能文档提及 clerk init --prompt 或类似的移交行为，也要记录。

优先阅读源码，而不是运行二进制文件。如果运行时行为不明确，请将 packages/cli-core/src/**/*.test.ts 或 packages/cli-core/src/test/ 下的测试作为辅助依据。

2. 提取技能文档中的说法

阅读 skills/clerk-cli/SKILL.md 和 skills/clerk-cli/references/ 下的每个文件。提取所有具体说法：

• 核心命令表中的命令和调用指引。
• 在正文、表格和示例中提及的标志。
• Agent 模式行为条目。
• 退出代码、错误格式和 JSON 输出的说法。
• SKILL.md 与 references/*.md 之间的交叉引用。

3. 对比源代码与技能文档

按以下四类生成结构化差异：

1. 技能文档缺失：源代码中存在，但技能文档中完全没有提及的命令、子命令、标志或行为。
2. 技能文档过时：技能文档中的说法已与源代码不符，包括重命名的标志、默认值变更、已移除的命令、退出码变化或重新设计的 Agent 模式分支。
3. 技能文档说明不足：技能文档提及了命令，但对其实际复杂性或容易踩坑之处说明不充分。
4. 说明过于详细：技能文档中编码的细节，通过 clerk <cmd> --help、生成的示例或引用的文件能更好地说明。

对于第 1 至第 3 类，请同时注明源文件及行号，以及技能文档中的目标位置。

4. 确定放置位置

根据维护价值安排变更：

• 核心工作流、思维模型和安全性保留在 SKILL.md 中。
• 各命令的标志详情、操作示例和边缘情况放在 references/recipes.md 或新的参考文件中。
• Agent 模式分支放在 references/agent-mode.md 中；SKILL.md 只保留简要概述。
• 身份验证、密钥解析和目标选择放在 references/auth.md 中。

优先使用 clerk <command> --help，避免重复生成的帮助内容。具有破坏性语义、隐藏交互或 Agent 模式差异的标志值得在技能文档中说明。通常应从文档正文中移除不言自明的标志说明，交由 --help 介绍。

如果精简技能文档能降低偏差风险，应将其视为有效提议。目标是让技能文档准确且经久耐用，而不是让它变得更长。

5. 提出编辑建议

提交便于审核的提议。每项变更都应包含：

• 路径，例如 skills/clerk-cli/SKILL.md 或 skills/clerk-cli/references/agent-mode.md。
• 严重级别：drift、gap 或 polish。
• 原因及源代码引用，例如 packages/cli-core/src/commands/<cmd>/<file>.ts:<line>。
• 在此代码库中的目标位置。
• 可行时提供统一差异；否则提供简洁的修改前和修改后内容。

按目标文件对提议分组。不要仅因相邻章节而重写准确内容。

6. 应用或交回审核

默认行为：提交提议后等待审核。

如果通过 --apply 调用，则直接应用 drift 和 gap 级别的编辑，然后列出供审核的 polish 建议。应用编辑后，运行此代码库中可用的格式化或验证命令。如果没有格式化工具，则通过轻量级检查验证 Markdown 和 JSON 结构。

约束

• 绝不臆造标志。如果某个标志只出现在测试中，却不在命令解析器中，应标记为需要人工审核。
• 保留现有 clerk-cli 技能简洁、使用第三人称的文风。
• 提议和编辑中不要使用 em dash。
• skills/clerk-cli/SKILL.md 应保持在约 500 行。详细内容应移至 references/，而不是塞满主技能文档。
• 不要将已安装的 clerk 二进制视为权威来源。仅在源代码和测试仍有歧义时，才用 --help 确认生成的呈现内容。
• 不要提交或输出密钥。如果审查涉及环境变量指导，应遵守代码库关于 1Password 和禁止明文密钥的规则。

输出格式

按以下格式返回提议：

# clerk-cli skill audit - <YYYY-MM-DD>

## Summary
<counts per bucket, plus the largest drift>

## skills/clerk-cli/SKILL.md
### <section name>
- [drift|gap|polish] <one-line description>
  - source: packages/cli-core/src/commands/<...>:<line>
  - target: skills/clerk-cli/SKILL.md:<line>
  - change: <diff or concise before/after>

## skills/clerk-cli/references/<file>.md
...

## New files
...

## Open questions
...

确保结果便于浏览，以便维护者逐项批准、拒绝或应用。