universal-file-ops

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

触发场景

正向触发词（满足任一即触发）：

「帮我规范地处理文件…」「检查 Python 脚本规范」「生成测试」
「帮我搭建 Python 环境」「安装 Python 包」「切换 Python 版本」
「这个脚本有什么问题」「帮我 OO 化这个 Python 文件」

否定条件（满足任一项即不触发）：

用户明确说「只用系统 Python，不用技能」
任务仅需单次文件读取，无需规范化/质量保证

核心能力

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

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

渐进式文件索引

| 文件名 | 位置 | 说明 | |--------|------|------| | references/antipatterns.md | 反模式 | 常见错误模式和正确做法 | | references/report_templates.md | 报告模板 | A/B/C 三阶段固定报告格式 | | references/error_codes.md | 错误码手册 | UFO-XXXX 全类错误码说明 | | references/guide.md | 使用指南 | 完整操作教程和示例 | | references/faq.md | 常见问题 | 14 对 Q&A | | references/py_standards.md | Python 编码规范 | 13 节规范说明 | | references/permissions.md | 权限说明 | 安全风险扫描结果 | | references/changelog.md | 更新日志 | 版本更新记录 |

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

工作流程

理解用户需求
规划执行步骤
调用相关工具/脚本
返回结果给用户

📚 渐进式加载：本技能采用渐进式 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化→测试→沙箱→修复→报告                      │
└──────────┴──────────────────────────────────────────────┘

钩子规则：

| 规则 | 说明 | |------|------| | 每个钩子执行前必须 hook_runner.py check <ID> | 前置未完成 → 报错阻止 | | 每个钩子执行后必须 hook_runner.py done <ID> | 记录完成，后置才能继续 | | done 记成功，不记好坏 | review 查到 warning、sandbox 有失败，只要执行了就用 done，结果数据写在 --output 里 | | fail 只用于致命错误 | 脚本找不到、环境未就绪等导致根本无法执行的情况才用 fail。一旦 fail，后续链路全部阻断 | | H-C10 是唯一例外 | 容忍前置 failed，路由定了就能出报告。其他钩子前置必须是 done | | 不允许跳过钩子不做标记 | 每个钩子必须有一个 done 或 fail 状态 |

故障处理两种路径：

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-A01 | python_env.py detect | 检测系统已安装的 Python 版本 | | H-A02 | python_env.py setup | 创建 venv（默认 Python 3.11） | | H-A03 | python_env.py install --packages ... | 安装任务所需依赖包 | | H-A11 | LLM 语义分析 | 分析用户意图 → 输出 {"route":"B"} 或 {"route":"C"} |

H-A11 路由逻辑：

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

PHASE B — 工具箱（文件 CRUD）

| 钩子 | 操作 | 说明 | |------|------|------| | H-B01 | text_crud.py read 或 file_ops.py | 读取源文件 | | H-B02 | LLM 处理/转换 | 在内存中处理数据，不写磁盘 | | H-B03 | text_crud.py create/update 或 file_ops.py copy/move | 原子写入目标文件 | | H-B04 | text_crud.py read 回读 | 验证写入内容与预期一致 |

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

PHASE C — 脚本流水线

| 钩子 | 操作 | 说明 | |------|------|------| | H-C01 | 读取渐进式文件索引中的编码规范 | 前置加载 13 节规范 | | H-C02 | 创建需求一览表 | Markdown 表格，R-001 起编 | | H-C03 | text_crud.py create 写入 .py | 依规范+需求表生成并写入 | | H-C04 | py_tools.py normalize --fix | 自动修复格式问题 | | H-C05 | py_tools.py review | 语法/docstring/行数/命名检查 | | H-C06 | py_tools.py oo-ify | 仅 >600 行正式工具，可选 | | H-C07 | py_tools.py gen-test -o test_<target> | 生成 pytest 框架 | | H-C08 | py_tools.py sandbox-test --file --test-file | 沙箱执行测试 | | H-C09 | 修复循环（见下方嵌套） | 失败时自动修复，最多 3 次 | | H-C10 | 输出结构化报告 | 含需求对比、修复记录、测试详情 |

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

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

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

| 嵌套钩子 | 操作 | 说明 | |---------|------|------| | H-C09.1 | 分析失败原因 | 查看 sandbox 输出，定位断言/导入/语法错误 | | H-C09.2 | text_crud.py update 修复代码 | 修复 bug，记录修了什么 | | H-C09.3 | py_tools.py normalize --fix | 重新规范化修复后的代码 | | H-C09.4 | py_tools.py sandbox-test | 重新沙箱执行 |

循环条件：

全部通过 → 退出循环，进 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 编码规范参见渐进式文件索引