universal-file-ops

> 受众：本技能专为普通大模型/智能体用户设计，非专业开发者。目标是让智能体能规范地使用 Python 创造工具脚本，输出即正确，无需反复调试。

触发场景

正向触发词（满足任一即触发）：
- 「帮我规范地处理文件…」「检查 Python 脚本规范」「生成测试」
- 「帮我搭建 Python 环境」「安装 Python 包」「切换 Python 版本」
- 「这个脚本有什么问题」「帮我 OO 化这个 Python 文件」

否定条件（满足任一项即不触发）：
- 用户明确说「只用系统 Python，不用技能」
- 任务仅需单次文件读取，无需规范化/质量保证

核心能力

> 📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤460行），详细内容拆分到 references/*.md 按需加载。

1. 通用文件操作 (工具箱 B) — 标准化 IO、原子写入、自动备份、错误码输出
2. Python 脚本质量流水线 (脚本流水线 C) — 前置规范加载 → 需求一览表 → 代码生成 → 规范化 → 审查 → OO 化建议 → 测试生成 → 沙箱执行 → 修复循环 → 终版报告
3. Python 环境管理 (环境 A) — 版本安装/切换/包管理/干净重装（scripts/python_env.py，含网络重试）
4. 脚本类型区分 — 自动识别临时脚本 vs 正式工具，临时脚本豁免 600 行 OO 化限制
5. 沙箱测试 — py_tools.py sandbox-test 在隔离临时 venv 中自动编译并执行测试
6. 自引用 I/O — 所有文件写入强制通过 text_crud.py / file_ops.py 或 utils.atomic_write()，禁止原生 open()/write()
7. 流程钩子系统 — scripts/hook_runner.py 强制执行三阶段流水线，每步写状态文件，不可跳过、不可乱序

渐进式文件索引

→ 详见 references/guide.md 完整使用指南
→ 反模式参见 references/antipatterns.md
→ 常见问题参见 references/faq.md

工作流程

1. 理解用户需求
2. 规划执行步骤
3. 调用相关工具/脚本
4. 返回结果给用户
   > 📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。

三阶段架构总览

┌─────────────────────────────────────────────────────────┐
│  PHASE A — 环境准备 (H-A01 ~ H-A03)                      │
│  检测 Python → 创建 venv → 安装依赖                       │
├─────────────────────────────────────────────────────────┤
│  A.1 — 语义路由 (H-A11)                                   │
│  用户意图分析 → 输出 "B" (工具箱) 或 "C" (脚本流水线)       │
├──────────┬──────────────────────────────────────────────┤
│ PHASE B  │  PHASE C                                      │
│ 工具箱    │  脚本流水线                                    │
│ H-B01~04 │  H-C01~C10 含嵌套修复循环 H-C09.1~C09.4       │
│ 读→处理→写│  规范加载→需求→生成→规整→审查→                  │
│ →验证    │  OO化→测试→沙箱→修复→报告                      │
└──────────┴──────────────────────────────────────────────┘

钩子规则：

故障处理两种路径：

H-C01 → H-C02 → H-C03 → H-C04 → H-C05 → H-C06 → H-C07 → H-C08 → H-C09 → H-C10
                                                                                ↑
                                                            H-C10 只认 H-A11，
                                                            不认 C/B 链上任何钩子

┌────────────────────────────────────────────────────────────────────┐
│ 步骤执行了但结果不理想（review 有 warning、sandbox 有失败）          │
│   → 用 done，--output 记录实际情况                                  │
│   → 链路继续，C09 修复循环按需启动                                  │
├────────────────────────────────────────────────────────────────────┤
│ 步骤无法执行 → 先尝试修复，而不是直接放弃                             │
│   → 用 fail 标记                                                    │
│   → 排查原因，修复问题（安装 Python、修正代码、装依赖等）               │
│   → 用 done 覆盖 fail 状态（重试通过，retry_count 自动 +1）            │
│   → 链路恢复正常                                                    │
│   → 再次 fail → 再次修复 → **最多 3 次**                             │
│   → 3 次后依然 fail → `done` 被拒绝，只能跳 H-C10 输出报告            │
├────────────────────────────────────────────────────────────────────┤
│ 怎么判断是"可修复"还是"不可修复"？                                    │
│   H-A01 detect_python 失败 → 装 Python → 重试                      │
│   H-A03 install_deps 失败  → 换镜像源 → 重试                        │
│   H-C03 generate_code 失败 → 修正模板 → 重试                        │
│   H-C08 sandbox_test 失败 → 这不属于 fail，用 done 记录结果即可       │
│   Python 解释器本身损坏 → 不可修复 → 放弃                            │
└────────────────────────────────────────────────────────────────────┘

PHASE A — 环境准备

H-A11 路由逻辑：
- 用户要求读/写/改/复制/移动/重命名文件 → route: "B"
- 用户要求创建/更新/审查/测试 Python 脚本 → route: "C"
- 不确定时问用户

PHASE B — 工具箱（文件 CRUD）

所有写操作使用 utils.atomic_write()（tempfile.mkstemp → os.replace() 原子交换），写入中断不会产生残缺文件。

PHASE C — 脚本流水线

I/O 规范： 流水线中所有文件读写必须使用技能自身脚本或 utils.atomic_write()。任何地方出现 open(file, "w") 都是不合规的。

H-C09 修复循环（嵌套钩子）

sandbox-test 有 failed 或 errors 时进入此循环。每次迭代执行以下子钩子：

循环条件：
- 全部通过 → 退出循环，进 H-C10
- 仍有失败且迭代 < 3 次 → 重复 H-C09.1 → H-C09.4
- 仍有失败且迭代 ≥ 3 次 → 退出循环，进 H-C10（报告含未通过项）

输出报告模板

每次流水线执行完毕，必须输出结构化报告。详细模板见 references/report_templates.md，包含模板 A（环境准备）、模板 B（工具箱）、模板 C（脚本流水线）及字段填写规则。

错误输出规范

所有错误均返回标准化 JSON 格式：

{
  "error_code": "UFO-2001",
  "script": "scripts/py_tools.py",
  "line": 173,
  "message": "这个 Python 文件用了 Tab 缩进，标准写法是用 4 个空格",
  "suggestion": "运行 scripts/py_tools.py normalize 自动修复，或把 Tab 改成 4 个空格"
}

→ 完整错误码手册参见 references/error_codes.md
→ Python 编码规范参见渐进式文件索引