AI File Editor 使用说明

基于大模型回答的智能文件编辑工具 —— 专为内网环境设计，通过"复制提示词 → 网页 LLM → 粘贴回复"的方式，让大模型安全地编辑本地文件。

• 工作原理
• 环境要求
• 快速上手（3 步）
• 命令详解
  • prompt edit — 单文件提示词
  • prompt batch — 多文件提示词
  • prompt raw — 从零创建文件提示词
  • apply — 解析回复并执行编辑
• 完整工作流示例
• XML 编辑协议（LLM 回复格式）
• 安全机制
• 内网环境适配特性
• 常见问题 FAQ
• 在线 API 模式（可选）

┌──────────────┐   ①生成提示词    ┌──────────────┐
│  本地脚本     │ ──────────────→ │  提示词文本   │
│ ai_file_     │                 │ (含文件内容)  │
│ editor.py    │                 └──────┬───────┘
└──────────────┘                        │ ②复制粘贴
                                        ▼
┌──────────────┐   ④解析并执行    ┌──────────────┐
│  本地文件     │ ←────────────── │  网页 LLM     │
│  (自动备份)   │                 │ (人工复制回复)│
└──────────────┘                 └──────┬───────┘
                                        │ ③保存为 response.txt
                                        ▼
                                  本地回复文件

核心思想：大模型不直接碰你的文件，而是输出结构化的 <file_edit> 编辑指令，本地脚本解析后才执行，且默认先预览、确认后才写入。

假设要让网页大模型给 main.py 添加错误处理：

Step 1 — 生成提示词

python ai_file_editor.py prompt edit main.py -i "添加错误处理"

屏幕上会输出完整提示词（含文件内容 + 编辑协议说明），全选复制。 Windows 可直接送入剪贴板：

python ai_file_editor.py prompt edit main.py -i "添加错误处理" | clip

Step 2 — 网页 LLM 生成回复

把提示词粘贴到任意网页大模型（DeepSeek / 豆包 / 文心一言等），等它输出 <file_edit> 格式的回复，全选复制回复内容，用记事本保存为 response.txt（与脚本放在同一目录）。

Step 3 — 预览并执行

# 先预览（默认模式，不改文件）
python ai_file_editor.py apply response.txt

# 确认无误后执行，并备份原文件
python ai_file_editor.py apply response.txt --apply --backup

为单个已有文件生成编辑提示词。

python ai_file_editor.py prompt edit <文件路径> -i "<指令>" [-o 输出文件]

示例：

python ai_file_editor.py prompt edit src/main.py -i "给所有函数添加类型注解"
python ai_file_editor.py prompt edit src/main.py -i "重构" -o prompt.txt

把目录下多个文件合并成一条提示词，一次发给网页 LLM。

python ai_file_editor.py prompt batch <目录> -i "<指令>" [--pattern 模式] [-o 输出文件]

示例：

python ai_file_editor.py prompt batch ./src -i "给所有函数加类型注解" --pattern "*.py"

⚠️ 注意：文件越多提示词越长。超过约 10 万字符时脚本会警告——网页 LLM 输入框可能装不下，建议按子目录分批处理。

不附带已有文件，让 LLM 从零创建新文件。

python ai_file_editor.py prompt raw -i "创建一个 FastAPI 入口文件 app.py，包含健康检查接口"

从回复文件中解析 <file_edit> 指令，默认只预览不写入。

python ai_file_editor.py apply <回复文件> [--base-dir 目录] [--apply] [--backup]

输出示例：

💬 大模型说明:
我帮你添加了类型注解。

📋 解析到 1 条编辑指令:
   EDIT main.py

[预览] EDIT main.py
  ┌─ DIFF ────────────────────
  │ - def add(a, b):
  │ + def add(a: int, b: int) -> int:
  └────────────────────────────

📌 以上为预览，加 --apply 确认执行

📌 重要：请在生成提示词时的同一目录下执行 apply。提示词中的文件路径是相对路径，apply 默认也以当前目录为基准解析。如果不在同一目录，用 --base-dir 指定。

场景：内网项目 ./src 下有 3 个 Python 文件，要给所有函数加类型注解。

# ① 进入项目目录（重要！后续 apply 也要在这里执行）
cd C:\myproject

# ② 生成批量提示词并复制到剪贴板
python C:\tools\ai_file_editor.py prompt batch ./src -i "给所有函数加类型注解" | clip

# ③ 打开网页 LLM，Ctrl+V 粘贴，发送

# ④ 把 LLM 完整回复复制，保存为 C:\myproject\response.txt

# ⑤ 先预览改动
python C:\tools\ai_file_editor.py apply response.txt

# ⑥ 确认无误，执行并备份
python C:\tools\ai_file_editor.py apply response.txt --apply --backup

输出：

✅ EDIT src\a.py（编码: utf-8）
  备份: a.py.bak_20260817_233000
✅ EDIT src\b.py（编码: gbk）（行尾归一化匹配）
  备份: b.py.bak_20260817_233000
✅ EDIT src\c.py（编码: utf-8）
  备份: c.py.bak_20260817_233000

提示词已引导 LLM 按以下格式回复，了解协议有助于你检查回复是否正确：

1. 创建/覆盖文件

<file_edit path="utils.py" action="create">
<new_content>
def helper():
    pass
</new_content>
</file_edit>

2. 编辑已有文件（查找替换）

<file_edit path="main.py" action="edit">
<old_content>
def add(a, b):
    return a + b
</old_content>
<new_content>
def add(a: int, b: int) -> int:
    return a + b
</new_content>
</file_edit>

3. 删除文件

<file_edit path="old.py" action="delete">
</file_edit>

协议要点：

• 一条回复可包含多条 <file_edit>，对应多个文件
• old_content 必须与文件内容完全匹配（含缩进换行），且应包含 3~5 行上下文确保唯一
• path 必须与提示词中给出的路径完全一致

工具内置多重防护，宁可拒绝执行，也不冒险改错文件：

Q1: apply 时提示"未找到匹配文本"？

按以下顺序排查：

1. 网页复制时是否丢了行尾空格（某些网页渲染会吞掉）
2. 文件缩进是空格还是 Tab，与 LLM 输出是否一致
3. 生成提示词后文件是否被手动修改过
4. 是否在生成提示词的同一目录下执行的 apply

Q2: 提示"old_content 匹配到 N 处"？

说明这段代码在文件里出现了多次，脚本拒绝执行。让 LLM 重新生成回复，在 old_content 中包含更多上下文（比如函数定义行 + 前后几行），确保唯一匹配。

Q3: 回复文件保存后解析不到编辑指令？

检查 LLM 回复是否完整复制（有些网页复制会漏掉后半部分），以及是否包含 <file_edit 标签。可以用文本编辑器打开 response.txt 搜索 <file_edit 确认。

Q4: LLM 回复被截断了怎么办？

网页 LLM 输出长度有限。把任务拆小：单文件用大改动时，改用"分多次编辑"策略，一次只让 LLM 改一部分。

Q5: 提示词太长贴不进网页？

缩小 prompt batch 的范围（按子目录分批），或减少 --pattern 匹配的文件数。超过 10 万字符时脚本会主动警告。

Q6: 改错了怎么恢复？

如果加了 --backup，同目录下有 文件名.bak_时间戳 备份文件，复制回来即可。强烈建议重要文件始终加 --backup。

Q7: 支持编辑非 Python 文件吗？

支持。任何文本文件都可以（JS/Java/配置/Markdown 等），用 --pattern 指定，如 --pattern "*.java"。

如果环境可以访问大模型 API（如公司内网部署的模型服务），可以跳过手动复制：

# 配置环境变量
set OPENAI_API_KEY=your-key
set OPENAI_BASE_URL=http://your-llm-server/v1
set OPENAI_MODEL=your-model

# 一键编辑（自动调用 API + 解析 + 执行）
python ai_file_editor.py edit main.py -i "添加错误处理" --apply --backup
python ai_file_editor.py batch ./src -i "加类型注解" --apply
python ai_file_editor.py raw -i "创建 FastAPI 入口文件" --apply

在线模式命令与离线模式参数一致，安全机制完全相同（默认预览、备份、防护）。