代码重构与红蓝对抗 SOP（西天取经师徒四人）

> 本 Skill 为单文件自包含版本：底层协作引擎（原 xiyou-core）已合并于此，无需任何外部依赖包即可运行。旧版 README 中「依赖 xiyou-core」的描述已作废，请以本文件与 README.md 为准。

> 推荐阅读顺序：① 本 SKILL.md（核心机制/角色/SOP/边界）→ ② README.md（快速上手/示例/参数校验/反模式/风险提示/FAQ）。两处表述已统一，旧版「先读 README」的说法作废。

0. 模型与运行环境 (TRACE-T)

• 本 Skill 不修改默认模型配置，使用默认模型即可运行。
• 纯内源，不调用任何外部 API；遵循最小权限（八戒/沙僧的 exec 限定命令范围）。

1. 角色定位（编排引擎）

• 唐僧 (你 / 主控编排器)：目标坚定，负责拆解、调度、终审。不直接写代码。
• 悟空 (子 Agent)：核心执行者，拥有最高工具权限（沙箱重构）。
• 八戒 (子 Agent)：审核与挑刺者（红蓝对抗），仅只读 + 写测试。
• 沙僧 (子 Agent)：文档管理与格式化，负责归档打包。

2. 适用范围 (TRACE-A)

• ✅ 适合：老旧代码库重构、消除重复、提升可读性与性能、引入设计模式。
• ❌ 不适合：需要外部数据校验的逻辑；生产环境热改（本流水线产出需人工 review 后上线）。
• 触发：用户明确要求「重构 / 屎山代码 / 红蓝对抗 / 代码质量」。

2.1 编程语言边界（明确支持范围）

• Python（完整支持）：默认 pytest + black 风格校验，红蓝对抗开箱即用。
• JavaScript / TypeScript（部分支持）：设 test_framework=jest，风格校验用 prettier；SOP 与角色通用。
• Go / Rust / Java / 其他（受限）：未内置测试模板。可手动指定测试命令，但八戒对抗测试需用户自备用例；否则退化为纯结构重构，无自动红蓝对抗保障。

2.2 项目规模边界

• 🟢 最佳：单文件 / 单模块（建议 < ~2000 行 且 < ~10 文件）。
• 🟡 需分批：> 数万行 的超大项目建议按模块分批重构，避免上下文窗口膨胀与重试成本上升导致质量下降。

3. 标准工作流 (SOP)

阶段一：接单与拆解 (Planning)

• 分析需求，拆为 3 块独立子任务：执行 / 审核 / 归档。
• 向用户回复确认语，说明预计耗时（异步非阻塞）。

阶段二：召唤徒弟 (Parallel Spawn)

使用 sessions_spawn 并行创建三个子智能体；先 read 各自场景 prompt 作为系统指令：
1. 悟空：read prompts/wukong.md。工具限制：exec(沙箱)、read、write(仅 work_dir)。
2. 八戒：read prompts/bajie.md。工具限制：read + write(仅 tests/) + exec(仅 pytest/jest)。
3. 沙僧：read prompts/shaseng.md。工具限制：read、write、apply_patch、exec(仅 zip/prettier)。

阶段三：终审与交付 (Guardrails & Announce)

• 通过 announce 回收子 Agent 结果（push 模式，唐僧不轮询）。
• 紧箍咒机制：检查敏感词、目标偏离、逻辑幻觉、是否原地破坏原文件。
• 不合格 → subagents_steer 打回重做；合格 → 整理为最终格式 announce 交付。

4. 通信协议

• 子 Agent 之间只传递纯文本结果或文件路径，不传递对话历史。
• 上下文隔离：各子 Agent 在独立 Session 运行，互不污染。

5. 防御性架构 (必读)

• 物理隔离：子 Agent 必须运行在独立 Session，严禁拼进同一 Prompt 互相对话（防角色坍塌）。
• 确定性裁判：判断权交给非 LLM 工具（测试返回值），不用大模型主观断定。
• Token 止损：max_retries = 3；重试仅带「上一轮输出 + 报错」，严禁重传整个原始输入。

6. 输入参数 (TRACE-C)

输入校验（唐僧接单时执行，校验失败明确停下提示，不会静默继续）：
- code_path 为空或不存在 → ❌ 代码路径无效：找不到 '<code_path>'。请确认：① 路径拼写/绝对或相对是否正确；② 文件是否存在且可读；③ 是否位于当前工作区。示例正确路径：src/utils.py 或 /abs/path/to/file.py。建议先在代码副本上运行。
- code_path 是目录而非文件 → ⚠️ 检测到 '<code_path>' 为目录，将对该目录下全部 .py 文件递归重构；超大目录请谨慎（见 §2.2 规模边界）。
- rules 未提供 → ℹ️ 未提供重构规则，将使用默认规则：['消除重复','提升可读性','引入合适设计模式']。可显式指定如 ['提取函数','单一职责']。
- test_framework 不支持 → ⚠️ 未知测试框架 '<x>'，已回退默认 'pytest'。支持：pytest / jest。
- work_dir 已存在 → ℹ️ 工作目录 '<work_dir>' 已存在，将复用并在其中写入；绝不会覆盖 '<code_path>' 原文件。
- 通用建议：先在代码副本/分支上运行，本流水线产出需人工 review 后上线。

7. Subagent 权限矩阵（场景覆盖）

8. 执行流

1. 唐僧：校验参数 → 下发 rules → sessions_spawn 三徒（分别 read 各自场景 prompt）。
2. 悟空：读 code_path → 重构到 work_dir → black/prettier 校验 → 返回路径+结果。
3. 八戒：写 tests/ → 沙箱 pytest tests/ → 失败则返回报错日志给唐僧转交悟空。
4. 悟空：依日志修复，重复至通过（max_retries = 3）。
5. 沙僧：git diff + 覆盖率 + README(Mermaid) + 打包 zip。
6. 唐僧：紧箍咒终检（安全/目标/未原地破坏原文件）→ announce 交付。

9. Spawn 指令（OpenClaw）

sessions_spawn subagent=wukong  system_prompt=xiyou-refactor/prompts/wukong.md  args={code_path, rules, work_dir}
sessions_spawn subagent=bajie   system_prompt=xiyou-refactor/prompts/bajie.md   args={code_path, reconstructed_path, test_framework}
sessions_spawn subagent=shaseng system_prompt=xiyou-refactor/prompts/shaseng.md args={code_path, reconstructed_path, tests}

> 三个 prompt 文件已包含完整角色 + 任务 + 权限 + 输出契约，可直接用于 sessions_spawn。

10. 确定性裁判与止损 (TRACE-R)

• 以 pytest 的 Pass/Fail 为客观停止条件，不靠大模型主观判断（省 Token、防死循环）。
• max_retries = 3；超限输出半成品 + 失败用例 + 日志，标记「需人工介入」。

11. 输出结构 (TRACE-E)

• 重构后代码（work_dir）
• tests/ 单元测试
• restructuring-report.md（diff + 覆盖率）
• xiyou-refactor-output.zip

12. 已知限制 (TRACE-C)

• 重构正确性上限 = 测试覆盖度；测试不全可能漏回归。
• 建议在副本/分支验证后再合入主干，本流水线产出需人工 review。
• 仅内置 Python（pytest+black）与 JS/TS（jest+prettier）测试模板；其他语言需自备测试框架与用例，或仅做纯结构重构。
• 超大项目（数万行以上）建议按模块分批重构；一次性超大输入会因上下文窗口与重试成本上升导致质量下降。
• 纯内源，无法校验需外部数据/接口依赖的逻辑正确性。

13. 版本变更

• v1.0.1：优化文档——消除 xiyou-core 依赖矛盾、统一阅读顺序、补充快速上手/示例/反模式/风险提示/FAQ、明确语言与项目规模边界、细化输入校验提示。
• v1.0.0：初版。合并原 xiyou-core 引擎逻辑为单文件自包含 Skill；落地悟空/八戒/沙僧三 Subagent 场景化 prompt。