用途
srgn-cli 是一份用于构建安全、语法感知的 srgn 命令行工具的实用指南。它的目标是把用户意图转化为精确的 srgn 命令，并采用安全的默认行为。重点覆盖源码搜索、内容转换、限定范围的迁移以及类似 lint 的检查等 CLI 工作流。
主要能力
该技能围绕一套工作流决策树组织，帮助使用者逐步确定：
- 请求类型：仅搜索（不改变内容）、流式转换（stdin/stdout 管道）、文件转换（对 glob 匹配文件就地更新）。
- 作用域策略：仅正则作用域、仅语言作用域、语言加正则组合作用域、自定义 tree-sitter 查询作用域。
- 动作策略：替换（在 -- 之后给出替换参数）、可组合动作（--upper、--lower、--titlecase、--normalize、--symbols、--german）、独立动作（-d、-s）。
- 安全控制：文件操作优先使用 --dry-run，glob 保持加引号，缺失文件应导致 CI 失败时使用 --fail-no-files。
- 输出模式：人类可读（默认 tty）或机器可读（--stdout-detection force-pipe）。
- 行为验证：确认预期匹配数量、确认没有越界编辑、必要时用更严格作用域重跑。
使用方式
命令构造模板为：
srgn [LANGUAGE_SCOPE_FLAGS...] [GLOBAL_FLAGS...] [ACTION_FLAGS...] [SCOPE_REGEX] -- [REPLACEMENT]
建议增量构建：先定作用域（如 --python 'imports'），再加正则过滤（如 '^old_pkg'），然后加动作（替换 -- 'new_pkg' 或可组合标志 --upper），接着按需加文件模式标志（--glob '**/*.py' --dry-run），最后加 CI 行为（--fail-any 或 --fail-none）。
安全协议要求：默认先采用非破坏性行为；优先给出基于 stdin 或搜索模式的示例，再做就地重写；文件编辑必须先预览，先跑 --dry-run，确认后再去掉 --dry-run 运行同一命令。同时要保护 shell 解析边界：正则加引号、glob 加引号（如 --glob '/*.py'）、替换值放在 -- 之后。注意 --glob 只接受一个模式，不能重复；glob 语法仅支持 *、?、[...]、，不支持 {a,b} 花括号展开。多文件处理可用更宽的 glob 加 --dry-run，或通过 fd 逐文件处理（仅限当前工作目录，无 [path] 参数）：
fd -e <ext> --strip-cwd-prefix -x srgn --glob '{}' --stdin-detection force-unreadable [OPTIONS] [PATTERN]
应使用能解决问题的最窄作用域，优先语言作用域加锚定正则，而非宽泛的纯正则替换。-d 和 -s 视为高风险操作，必须提供明确作用域。
适用场景
资料给出了若干高价值任务配方，例如：
- 仅重命名 Python 模块导入：srgn --python 'imports' '^old_pkg' --glob '**/*.py' --dry-run -- 'new_pkg'
- 仅将 Python 调用点的 print 转为 logging：srgn --python 'function-calls' '^print$' --glob '**/*.py' --dry-run -- 'logging.info'
- 重命名 Rust use 前缀而不触碰字符串/注释：srgn --rust 'uses' '^good_company' --glob '**/*.rs' --dry-run -- 'better_company'
- 仅删除 C# 注释：srgn --csharp 'comments' -d '.*'
- 仅搜索 Rust unsafe 关键字用法：srgn --rust 'unsafe'
- 当 Python 文档字符串出现不良模式时让 CI 失败：srgn --python 'doc-strings' --fail-any 'param.+type'
- 为下游解析器强制机器可读输出：srgn --python 'strings' --stdout-detection force-pipe '(foo|bar)'
- 以确定性顺序预览多文件变更：srgn --typescript 'imports' '^legacy-lib' --glob 'src/**/*.ts' --sorted --dry-run -- 'modern-lib'
此外还提供意图到命令的映射，例如“安全重命名导入”用语言导入作用域加锚定正则加 --glob 与 --dry-run；“仅更新函数调用”用语言调用点作用域加精确名称正则；“仅注释/文档字符串”用预置注释/文档字符串作用域，仅在需要 OR 语义时加 -j；“模式出现则 CI 失败”用限定作用域搜索加 --fail-any；“必需模式缺失则 CI 失败”用限定作用域搜索加 --fail-none；“需要可解析输出”用 --stdout-detection force-pipe；“正则转义麻烦”用 --literal-string 并通过 -- 显式替换。
限制与注意事项
资料还包含失败与调试手册，例如：预期有匹配却无匹配时，检查语言作用域与预置查询名，临时移除正则单独测试作用域，加 --stdout-detection force-pipe 查看精确匹配列；匹配过多时，尽量锚定正则（^...$），从通用语言作用域收窄到特定预置查询；目标文件错误时，确认 --glob 模式与 shell 引号，在 CI 中加 --fail-no-files 捕获空 glob；--glob 重复使用时，因其为单值参数不能重复，可改用更宽 glob 加 --dry-run 或逐文件处理；多语言作用域行为不明确时，默认是交集（从左到右收窄），使用 -j 获得 OR 行为；特殊字符被误当正则时，使用 --literal-string 进行字面匹配。
该技能还提供参考文件加载指南：references/cli-cookbook.md 用于常规命令构造与实用配方；references/language-scopes.md 用于按语言选择预置查询；references/advanced-patterns.md 用于自定义查询、捕获替换、join 语义与 CI 失败模式；references/deepwiki-recursive-notes.md 用于完整的 DeepWiki 派生背景与架构上下文。
执行检查清单要求在返回最终命令前确认：作用域最小且尽可能语法感知；替换参数位于 -- 之后（若使用替换）；glob 已加引号；文件编辑带 --dry-run（除非用户要求直接应用）；使用多个语言作用域时 join 语义明确（-j 与默认交集）；失败标志与用户意图一致（--fail-any、--fail-none、--fail-no-files）；用户需要机器解析时输出模式明确。
关于该工具的具体版本、安装方式、收费与价格、支持平台等信息，资料中暂未提供。