微信扫一扫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 编码规范参见渐进式文件索引