refactor

重构

在差异上运行 Command Center 的重构 Agent。Command Center 会规划重构，启动自己的编码 Agent 会话来执行重构，并将结果保留为工作树中未提交的更改。

何时调用

用户要求使用 Command Center 重构近期的更改，例如当前分支、某个提交范围或未提交的工作。示例：

• “使用 Command Center 重构此分支。”
• “在我的更改上运行 Command Center 重构 Agent。”
• “使用 CC 对我刚写的代码去重。”

调用前 — 重要

1. 重构会修改工作树。 Runner 等待期间，不要编辑仓库中的文件；运行完成后，重新读取任何已缓存的文件（结果会准确列出哪些文件已修改）。
2. 优先使用已提交的基线。 如果有重要的未提交工作，建议先提交，以便重构结果能通过 git diff 清晰地审查和撤销。这不是硬性要求——--working-tree 专门用于有意重构未提交的更改。
3. 这需要一些时间——不要频繁轮询。 通常需要几分钟；对于大型差异，可能需要数十分钟。进度只会在工作流步骤之间更新，因此连续静默 10 分钟以上很正常。在这类静默期间，Runner 大约每分钟会输出一行心跳状态，以表明仍在运行。如果你的运行环境支持后台运行，就在后台启动；每隔几分钟检查一次；不要向用户逐条转述每次无更新的检查结果——有进度信息时再转达。

调用方法

运行 run.mjs——它与此 SKILL.md 位于同一目录中。运行器会处理所有工作：检测安装情况、启动后端、检查身份验证／模型／Agent、筛选文件、启动重构，并持续输出进度，直到任务完成。

node <SKILL_DIR>/run.mjs [from..to] [--workflow=do-it-all|de-duplicate] [--files=PATTERN[,PATTERN...]]

<SKILL_DIR> 是 skills CLI 安装此技能的位置。常见路径：

界面	路径
Claude Code，项目本地	./.claude/skills/refactor
Claude Code，全局（-g）	~/.claude/skills/refactor
任何其他 Agent	./.agents/skills/refactor

如果你从磁盘加载了此 SKILL.md，运行器就在同级目录中——将该目录替换进去。

所有参数均为可选。默认情况下，运行器会重构解析出的范围内所有已更改文件。

引用范围——[from..to]：

• 省略 → 默认为 merge-base(HEAD, <base>)..HEAD，其中 <base> 是 origin/HEAD 的符号引用；若不存在，则依次回退到 origin/main / origin/master / main / master。
• 传入任何 git 可识别的内容：SHA、分支、HEAD~3..HEAD 等。
• 特殊标记：WORKING_TREE（未提交的更改）和 STAGED（暂存区）。示例：HEAD..WORKING_TREE。

工作流——--workflow=：

• do-it-all（默认）——执行 Command Center 自带“重构”按钮所运行的完整重构流程。
• de-duplicate——专注于合并重复代码的流程。

便捷标志：

• --working-tree → 重构从合并基点到当前工作树的差异（包含未提交的编辑）。
• --staged → 仅重构已通过 git add 暂存的内容。
• --files=PATTERN[,PATTERN...] → 将范围缩小到部分已更改文件。使用逗号分隔、相对于仓库的 glob 模式；* 匹配非斜杠字符，** 可跨目录，! 前缀表示排除。如果只传入排除项，则隐式包含 **。
• --timeout-mins=<n> → 等待重构完成的时长（默认 60）。超时后，Command Center 中的重构仍会继续运行。
• --port=<port> → 连接到特定的 Command Center 后端端口。当运行多个 CC 实例（开发环境）或运行器无法自动发现正确实例时，此参数很有用。

注意：Command Center 还会进一步筛选文件列表，只保留大小合理的代码文件——锁定文件、生成的文件和特别大的文件会自动跳过。

示例——选择符合用户意图的命令：

用户意图	命令
整个分支与基准分支对比（默认）	（无参数）
最近 3 次提交	HEAD~3..HEAD
未提交的编辑	--working-tree
仅对分支去重	--workflow=de-duplicate
整个分支，但跳过测试	--files=!**/*.test.*,!**/*.spec.*,!**/__tests__/**
仅处理 src/ 中的 TS 文件	--files=src/**/*.ts

解读输出

运行器会在 stdout 上每行打印一个 JSON 对象。每行都有一个 kind 字段：

• kind: "status" — 进度更新（重构期间包含 percentageDone）；向用户简短提示一行。带有 heartbeat: true 的行是在长时间无动静期间定期发送的运行状态信号，无需逐行播报；心跳之间没有输出并不表示卡住。
• kind: "result" — 终态成功。重构后的代码现在尚未提交，位于工作区中。负载包含 dirtyFiles（进一步编辑前请重新读取这些文件）、filesSubmitted，以及 Command Center 的 sessionId，对应会话中包含各项更改的说明。告知用户任务已完成，并建议通过 git diff 检查。
• kind: "error" — 终态失败；使用 code 和 message 字段告知用户出错原因。代码是稳定的枚举（not-installed、not-running、not-logged-in、no-model、no-agent、quota、no-workspace、no-files-matched、no-eligible-files、backend-too-old、refactoring-failed、refactoring-cancelled 等）；message 已是用户所用语言。
• kind: "action-required" — 用户必须先执行某项操作才能重新运行（例如安装应用、登录、配置模型或编码 Agent）。显示 message，如果存在，也显示 url。

始终原样显示运行器的 message，不要改写。运行器生成面向用户的英文字符串；后端生成的字符串已经本地化。

重构由 AI 生成，因此在依赖使用前应先审查；可在 Command Center 中审查，其中每项更改都附有说明。如果用户不喜欢结果，可以使用 git checkout -- <files>（或 git stash）撤销，因为更改尚未提交。

取消

终止运行器（SIGINT/SIGTERM）会尽力向 Command Center 发送取消请求，避免重构在你转而处理其他事情后仍继续编辑文件。也可以从 Command Center 应用中取消重构。

非零退出代码

运行器成功时退出码为 0，失败时返回一个较小的固定整数（每种失败类型对应一个代码）。不要解析退出码；请根据上述结构化的 kind / code 字段进行分支处理。