srgn-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

srgn CLI

Overview

概述

Use this skill to convert user intent into precise

srgn

commands with safe defaults. Focus on CLI workflows for search, transformation, scoped migrations, and lint-like checks.

使用本技能将用户需求转换为带有安全默认值的精准

srgn

命令。聚焦于搜索、转换、范围化迁移和类lint检查的CLI工作流。

Workflow Decision Tree

工作流决策树

Classify the request.
- Search only: no content changes expected.
- Transform in stream: stdin/stdout pipeline usage.
- Transform files: in-place updates over globs.
Identify scope strategy.
- Regex scope only.
- Language scope only.
- Combined language + regex scope.
- Custom tree-sitter query scope.
Identify action strategy.
- Replacement (positional replacement argument after
```
--
```
  ).
- Composable actions (
```
--upper
```
  ,
```
--lower
```
  ,
```
--titlecase
```
  ,
```
--normalize
```
  ,
```
--symbols
```
  ,
```
--german
```
  ).
- Standalone actions (
```
-d
```
  ,
```
-s
```
  ).
Apply safety controls.
- Prefer
```
--dry-run
```
  for file operations.
- Keep globs quoted.
- Add
```
--fail-no-files
```
  when missing files should fail CI.
Choose output mode.
- Human-readable (default tty).
- Machine-readable (
```
--stdout-detection force-pipe
```
  ).
Validate behavior.
- Confirm expected match count.
- Confirm no out-of-scope edits.
- Re-run with stricter scope if needed.

对请求进行分类。
- 仅搜索：不涉及内容变更。
- 流式转换：使用stdin/stdout管道。
- 文件转换：通过通配符进行原地更新。
确定范围策略。
- 仅正则表达式范围。
- 仅语言范围。
- 语言+正则表达式组合范围。
- 自定义tree-sitter查询范围。
确定操作策略。
- 替换（
```
--
```
  后的位置替换参数）。
- 可组合操作（
```
--upper
```
  ,
```
--lower
```
  ,
```
--titlecase
```
  ,
```
--normalize
```
  ,
```
--symbols
```
  ,
```
--german
```
  ）。
- 独立操作（
```
-d
```
  ,
```
-s
```
  ）。
应用安全控制。
- 文件操作优先使用
```
--dry-run
```
  。
- 通配符保持引号包裹。
- 当文件缺失应导致CI失败时，添加
```
--fail-no-files
```
  。
选择输出模式。
- 人类可读（默认终端模式）。
- 机器可读（
```
--stdout-detection force-pipe
```
  ）。
验证行为。
- 确认预期匹配数量。
- 确认无超出范围的编辑。
- 必要时使用更严格的范围重新运行。

Safety Protocol

安全协议

Default to non-destructive behavior first.
- Prefer stdin-based or search-mode examples before in-place rewrites.
For file edits, require preview path.
- Use
```
--dry-run
```
  first.
- Then run the same command without
```
--dry-run
```
  only after confirmation.
Protect shell parsing boundaries.
- Quote regex.
- Quote globs:
```
--glob '**/*.py'
```
  .
- Use
```
--
```
  before replacement values.
Use the narrowest scope that solves the task.
- Prefer language scope + anchored regex over broad regex-only replacement.
Treat
```
-d
```
and
```
-s
```
as high-risk operations.
- Always provide explicit scope for them.

优先采用非破坏性行为。
- 在原地重写前，优先提供基于stdin或搜索模式的示例。
对于文件编辑，要求预览路径。
- 首先使用
```
--dry-run
```
  。
- 仅在确认后，再运行不带
```
--dry-run
```
  的相同命令。
保护shell解析边界。
- 正则表达式添加引号。
- 通配符添加引号：
```
--glob '**/*.py'
```
  。
- 替换值前使用
```
--
```
  。
使用能解决任务的最窄范围。
- 优先选择语言范围+锚定正则表达式，而非宽泛的仅正则表达式替换。
将
```
-d
```
和
```
-s
```
视为高风险操作。
- 始终为它们提供明确的范围。

Command Construction Template

命令构建模板

Use this template when building commands:

bash

srgn [LANGUAGE_SCOPE_FLAGS...] [GLOBAL_FLAGS...] [ACTION_FLAGS...] [SCOPE_REGEX] -- [REPLACEMENT]

Build incrementally:

Scope first.
- Example:
```
--python 'imports'
```
Regex filter second.
- Example:
```
'^old_pkg'
```
Action third.
- Replacement:
```
-- 'new_pkg'
```
- Or composable flag:
```
--upper
```
File mode flags fourth (if needed).
- ```
--glob '**/*.py' --dry-run
```
CI behavior last.
- ```
--fail-any
```
  or
```
--fail-none
```

构建命令时使用以下模板：

bash

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

High-Value Task Recipes

高价值任务示例

Rename module imports in Python only:

bash

srgn --python 'imports' '^old_pkg' --glob '**/*.py' --dry-run -- 'new_pkg'

Convert
```
print
```
calls to logging in Python call-sites only:

bash

srgn --python 'function-calls' '^print$' --glob '**/*.py' --dry-run -- 'logging.info'

Rename Rust
```
use
```
prefixes without touching strings/comments:

bash

srgn --rust 'uses' '^good_company' --glob '**/*.rs' --dry-run -- 'better_company'

Remove C# comments only:

bash

srgn --csharp 'comments' -d '.*'

Search for Rust
```
unsafe
```
language keyword usage only:

bash

srgn --rust 'unsafe'

Fail CI if undesirable pattern appears in Python docstrings:

bash

srgn --python 'doc-strings' --fail-any 'param.+type'

Force machine-readable output for downstream parsers:

bash

srgn --python 'strings' --stdout-detection force-pipe '(foo|bar)'

Preview multi-file changes with deterministic ordering:

bash

srgn --typescript 'imports' '^legacy-lib' --glob 'src/**/*.ts' --sorted --dry-run -- 'modern-lib'

For broader, categorized examples, load

references/cli-cookbook.md

仅在Python中重命名模块导入：

bash

srgn --python 'imports' '^old_pkg' --glob '**/*.py' --dry-run -- 'new_pkg'

仅在Python调用点将
```
print
```
调用转换为日志：

bash

srgn --python 'function-calls' '^print$' --glob '**/*.py' --dry-run -- 'logging.info'

重命名Rust的
```
use
```
前缀，不修改字符串/注释：

bash

srgn --rust 'uses' '^good_company' --glob '**/*.rs' --dry-run -- 'better_company'

仅移除C#注释：

bash

srgn --csharp 'comments' -d '.*'

仅搜索Rust中
```
unsafe
```
关键字的使用：

bash

srgn --rust 'unsafe'

若Python文档字符串中出现不良模式，CI失败：

bash

srgn --python 'doc-strings' --fail-any 'param.+type'

强制生成机器可读输出以供下游解析器使用：

bash

srgn --python 'strings' --stdout-detection force-pipe '(foo|bar)'

以确定性顺序预览多文件变更：

bash

srgn --typescript 'imports' '^legacy-lib' --glob 'src/**/*.ts' --sorted --dry-run -- 'modern-lib'

如需更全面的分类示例，请加载

references/cli-cookbook.md

。

Failure and Debug Playbook

故障排查手册

No matches when matches are expected.
- Verify language scope and prepared query name.
- Remove regex temporarily to test scope alone.
- Add
```
--stdout-detection force-pipe
```
  to inspect exact matched columns.
Too many matches.
- Anchor regex (
```
^...$
```
  ) where possible.
- Narrow from generic language scope to a specific prepared query.
Wrong files targeted.
- Confirm
```
--glob
```
  pattern and shell quoting.
- Add
```
--fail-no-files
```
  in CI to catch empty globs.
Unclear behavior across multiple language scopes.
- Default is intersection (left-to-right narrowing).
- Use
```
-j
```
  for OR behavior.
Special characters misinterpreted as regex.
- Use
```
--literal-string
```
  when literal matching is intended.

预期有匹配但实际无匹配。
- 验证语言范围和预定义查询名称。
- 暂时移除正则表达式以单独测试范围。
- 添加
```
--stdout-detection force-pipe
```
  以检查精确匹配的列。
匹配结果过多。
- 尽可能为正则表达式添加锚点（
```
^...$
```
  ）。
- 从通用语言范围缩小到特定的预定义查询。
目标文件错误。
- 确认
```
--glob
```
  模式和shell引号。
- 在CI中添加
```
--fail-no-files
```
  以捕获空通配符。
多语言范围下行为不明确。
- 默认是交集（从左到右缩小范围）。
- 使用
```
-j
```
  实现OR逻辑。
特殊字符被误解析为正则表达式。
- 当需要字面匹配时，使用
```
--literal-string
```
  。

Reference Loading Guide

参考资料加载指南

Load reference files based on request type:

```
references/cli-cookbook.md
```
- Load for routine command construction and practical recipes.
```
references/language-scopes.md
```
- Load for prepared query selection by language.
```
references/advanced-patterns.md
```
- Load for custom queries, capture substitutions, join semantics, and CI failure modes.
```
references/deepwiki-recursive-notes.md
```
- Load for complete DeepWiki-derived background and architecture context.

根据请求类型加载参考文件：

```
references/cli-cookbook.md
```
- 用于常规命令构建和实用示例时加载。
```
references/language-scopes.md
```
- 用于按语言选择预定义查询时加载。
```
references/advanced-patterns.md
```
- 用于自定义查询、捕获替换、连接语义和CI失败模式时加载。
```
references/deepwiki-recursive-notes.md
```
- 用于获取完整的DeepWiki衍生背景和架构上下文时加载。

Intent-to-Command Map

需求到命令映射

Use this map to respond quickly:

"Rename imports safely"
- Use language import scope + anchored regex +
```
--glob ... --dry-run
```
  .
"Update function calls only"
- Use language call-site scope (for example
```
--python 'function-calls'
```
  ) + exact name regex.
"Only comments/docstrings"
- Use prepared comment/docstring scopes, add
```
-j
```
  only when OR semantics are required.
"CI should fail if pattern appears"
- Use scoped search +
```
--fail-any
```
  .
"CI should fail if required pattern is missing"
- Use scoped search +
```
--fail-none
```
  .
"I need parseable output"
- Use
```
--stdout-detection force-pipe
```
  .
"Regex escaping is painful"
- Use
```
--literal-string
```
  and explicit replacement via
```
--
```
  .

使用此映射快速响应：

"安全重命名导入"
- 使用语言导入范围+锚定正则表达式+
```
--glob ... --dry-run
```
  。
"仅更新函数调用"
- 使用语言调用点范围（例如
```
--python 'function-calls'
```
  ）+精确名称正则表达式。
"仅处理注释/文档字符串"
- 使用预定义的注释/文档字符串范围，仅当需要OR语义时添加
```
-j
```
  。
"如果出现特定模式，CI应失败"
- 使用范围化搜索+
```
--fail-any
```
  。
"如果缺少必要模式，CI应失败"
- 使用范围化搜索+
```
--fail-none
```
  。
"我需要可解析的输出"
- 使用
```
--stdout-detection force-pipe
```
  。
"正则表达式转义很麻烦"
- 使用
```
--literal-string
```
  并通过
```
--
```
  进行显式替换。

Execution Checklist

执行检查清单

Before returning a final command, verify:

Scope is minimal and syntax-aware where possible.
Replacement argument is after
```
--
```
(if replacement is used).
Globs are quoted.
```
--dry-run
```
is present for file edits unless user requested direct apply.
Join semantics are explicit when multiple language scopes are used (
```
-j
```
vs default intersect).
Failure flags align with user intent (
```
--fail-any
```
,
```
--fail-none
```
,
```
--fail-no-files
```
).
Output mode is explicit if user needs machine parsing.

在返回最终命令前，验证以下内容：

范围尽可能最小，且在可能的情况下具备语法感知能力。
若使用替换，替换参数位于
```
--
```
之后。
通配符已添加引号。
文件编辑命令中包含
```
--dry-run
```
，除非用户要求直接应用。
当使用多语言范围时，显式指定连接语义（
```
-j
```
vs 默认交集）。
失败标记与用户需求一致（
```
--fail-any
```
、
```
--fail-none
```
、
```
--fail-no-files
```
）。
若用户需要机器解析，显式指定输出模式。