# python-offlineAi

**Repository Path**: lbrave/python-offline-ai

## Basic Information

- **Project Name**: python-offlineAi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI File Editor 使用说明

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

---

## 目录

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

---

## 工作原理

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

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

---

## 环境要求

| 项目 | 要求 |
|------|------|
| Python | 3.9+（开发验证环境为 3.13） |
| 第三方依赖 | **离线模式零依赖**；在线模式需 `pip install openai` |
| 操作系统 | Windows（已适配 GBK/CRLF），Linux/macOS 同样可用 |

---

## 快速上手（3 步）

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

**Step 1 — 生成提示词**

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

提示词（含文件内容 + 编辑协议说明）会自动写入当前目录的 `request.txt`。打开该文件全选复制即可。
Windows 可直接送入剪贴板：

```bash
type request.txt | clip
```

**Step 2 — 网页 LLM 生成回复**

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

**Step 3 — 预览并执行**

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

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

---

## 命令详解

### prompt edit — 单文件提示词

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

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

| 参数 | 说明 |
|------|------|
| `file` | 要编辑的文件路径（必填） |
| `-i, --instruction` | 给大模型的编辑指令（必填） |
| `-o, --output` | 提示词保存到文件（默认 `request.txt`） |

示例：

```bash
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
```

---

### prompt batch — 多文件提示词

把多个文件**合并成一条提示词**，一次发给网页 LLM。支持**多目录、多文件混选**——可以跨项目不同文件夹自由组合。

```bash
python ai_file_editor.py prompt batch <路径1> [路径2 ...] -i "<指令>" [--pattern 模式] [--exclude 模式] [-o 输出文件]
```

| 参数 | 说明 |
|------|------|
| `paths` | 一个或多个路径（必填）。每个路径可以是**目录**（按 `--pattern` 递归展开）或**具体文件**（直接收录） |
| `-i, --instruction` | 编辑指令（必填） |
| `--pattern` | 目录展开时的文件匹配模式，默认 `*.py` |
| `--exclude` | 排除模式，可多次指定，如 `--exclude "test_*" --exclude "*_bak.py"` |
| `-o, --output` | 提示词保存到文件（默认 `request.txt`） |

示例：

```bash
# 单个目录（向后兼容）
python ai_file_editor.py prompt batch ./src -i "给所有函数加类型注解"

# 多个目录混选
python ai_file_editor.py prompt batch ./src ./lib ./services -i "统一加日志"

# 目录 + 具体文件混选
python ai_file_editor.py prompt batch ./src config.py main.py -i "重构配置读取"

# 排除测试文件
python ai_file_editor.py prompt batch ./src -i "加类型注解" --exclude "test_*"
```

内置规则：

- **自动排除**：`__pycache__`、`.git`、`venv`、`.venv`、`node_modules`、`*.pyc` 等目录/文件默认不收录
- **自动去重**：同一文件被目录展开和显式指定多次时只收录一次
- **路径容错**：个别路径不存在时警告并跳过，不中断

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

---

### prompt raw — 从零创建文件提示词

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

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

---

### apply — 解析回复并执行编辑

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

```bash
python ai_file_editor.py apply <回复文件> [--apply] [--backup]
```

| 参数 | 说明 |
|------|------|
| `response_file` | 网页 LLM 回复保存的文件（必填） |
| `--apply` | 实际执行编辑（不加则只预览） |
| `--backup` | 编辑前自动备份原文件（生成 `xxx.bak_时间戳`） |

> 注：apply 固定以**当前工作目录**为基准解析文件路径，必须在生成提示词的同一目录下执行。

输出示例：

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

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

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

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

> 📌 **重要**：请在**生成提示词时的同一目录**下执行 `apply`。提示词中的文件路径是相对路径，`apply` 固定以当前目录为基准解析。

---

## 完整工作流示例

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

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

# ② 生成批量提示词（写入 request.txt）并复制到剪贴板
python C:\tools\ai_file_editor.py prompt batch ./src -i "给所有函数加类型注解"
type request.txt | 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
```

---

## XML 编辑协议（LLM 回复格式）

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

**1. 创建/覆盖文件**

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

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

```xml
<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. 删除文件**

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

协议要点：

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

---

## 安全机制

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

| 机制 | 说明 |
|------|------|
| 默认预览 | 不加 `--apply` 只看 diff，不写文件 |
| 自动备份 | `--backup` 在写入前生成 `文件名.bak_时间戳` |
| 空匹配拒绝 | `old_content` 为空时拒绝执行（防止内容被插到文件开头） |
| 多匹配拒绝 | `old_content` 匹配到多处时拒绝执行（防止改错位置），提示补充上下文 |
| 首行缩进保留 | 解析器精确保留内容缩进，Python 代码不会因缩进丢失而语法错误 |
| 行尾自适应 | 网页复制导致 `\n`/`\r\n` 不一致时自动归一化匹配，写回保持原行尾 |
| 编码保持 | GBK 文件编辑后仍是 GBK，不会被强制转成 UTF-8 |

---

## 内网环境适配特性

| 特性 | 说明 |
|------|------|
| 零依赖 | 离线模式只用 Python 标准库，无需 pip install |
| GBK 兼容 | 自动识别 UTF-8 / UTF-8-BOM / GBK 编码（Windows 记事本默认编码也能读） |
| CRLF 兼容 | Windows 文件行尾自动适配 |
| 中文控制台 | Windows GBK 控制台不会因特殊字符崩溃 |
| 剪贴板集成 | 提示词默认写入 `request.txt`，`type request.txt | clip` 复制到剪贴板 |

---

## 常见问题 FAQ

**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 模式（可选）

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

```bash
# 配置环境变量
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
```

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

---

## 附录：命令速查表

| 场景 | 命令 |
|------|------|
| 单文件提示词 | `python ai_file_editor.py prompt edit main.py -i "指令"` |
| 多文件提示词 | `python ai_file_editor.py prompt batch ./src -i "指令"` |
| 跨目录混选 | `python ai_file_editor.py prompt batch ./src ./lib main.py -i "指令"` |
| 排除文件 | 加 `--exclude "test_*"`（可多次指定） |
| 新文件提示词 | `python ai_file_editor.py prompt raw -i "指令"` |
| 复制到剪贴板 | `type request.txt | clip` |
| 保存提示词 | 任意 prompt 命令加 `-o prompt.txt`（默认 request.txt） |
| 预览编辑 | `python ai_file_editor.py apply response.txt` |
| 执行编辑 | `python ai_file_editor.py apply response.txt --apply` |
| 执行+备份 | `python ai_file_editor.py apply response.txt --apply --backup` |