ViGent2/Docs/Doc_Rules.md

# 📋 开发日志更新规则

> **本文件定义了 AI 助手更新开发文档的规范**

---

## ⚡ 核心原则

| 规则 | 说明 |
|------|------|
| **默认更新** | 更新 `DayN.md` 和 `TASK_COMPLETE.md` |
| **按需更新** | 其他文档仅在内容变化涉及时更新 |
| **链路对齐** | 新增/重构文档后，回写入口文档（`README.md` 或对应 `*_README.md`） |
| **智能修改** | 错误→替换，改进→追加（见下方详细规则） |
| **先读后写** | 更新前先查看文件当前内容 |
| **日内合并** | 同一天的多次小修改合并为最终版本 |

---

## 🧾 全局文档更新清单 (Checklist)

> **每次提交重要变更时，请核对以下文件是否需要同步：**

| 优先级 | 文件路径 | 检查重点 |
| :---: | :--- | :--- |
| 🔥 **High** | `Docs/DevLogs/DayN.md` | **(最新日志)** 详细记录变更、修复、代码片段 |
| 🔥 **High** | `Docs/TASK_COMPLETE.md` | **(任务总览)** 更新 Day Current、`[x]` 与更新时间 |
| ⚡ **Med** | `README.md` | **(项目主页)** 功能特性、技术栈、最新截图 |
| ⚡ **Med** | `Docs/DEPLOY_MANUAL.md` | **(部署手册)** 环境变量、依赖包、启动命令变更 |
| ⚡ **Med** | `Docs/PUBLISH_DEPLOY.md` | **(发布专项)** 四平台登录/发布实现、排障、验收流程 |
| ⚡ **Med** | `Docs/BACKEND_DEV.md` | **(后端规范)** 接口契约、模块划分、环境变量 |
| ⚡ **Med** | `Docs/BACKEND_README.md` | **(后端文档)** 接口说明、架构设计 |
| ⚡ **Med** | `Docs/FRONTEND_DEV.md` | **(前端规范)** API封装、日期格式化、新页面规范 |
| ⚡ **Med** | `Docs/FRONTEND_README.md` | **(前端文档)** 功能说明、页面变更 |
| 🧊 **Low** | `Docs/DOC_RULES.md` | **(规则文档)** 文档结构变化或流程变化时同步更新 |
| 🧊 **Low** | `Docs/*_DEPLOY.md` | **(子系统部署)** LatentSync/CosyVoice/字幕等独立部署文档 |

---

## 🔍 修改原内容的判断标准

### 场景 1：错误修正 → **替换/删除**

**条件**：之前的方法/方案**无法工作**或**逻辑错误**

**操作**：
- ✅ 直接替换为正确内容
- ✅ 添加一行修正说明：`> **修正 (HH:MM)**：[错误原因]，已更新`
- ❌ 不保留错误方法（避免误导）

**示例**：
```markdown
## 🔧 XXX功能修复

~~旧方法：增加超时时间（无效）~~
> **修正 (16:20)**：单纯超时无法解决，已更新为Stealth模式

### 解决方案
- 启用Stealth模式...
```

### 场景 2：方案改进 → **保留+追加**

**条件**：之前的方法**可以工作**，后来发现**更好的方法**

**操作**：
- ✅ 保留原方法（标注版本 V1/V2）
- ✅ 追加新方法
- ✅ 说明改进原因

**示例**：
```markdown
## ⚡ 性能优化

### V1: 基础实现 (Day 5)
- 单线程处理 ✅

### V2: 性能优化 (Day 7)
- 多线程并发
- 速度提升 3x ⚡
```

### 场景 3：同一天多次修改 → **合并**

**条件**：同一天内对同一功能的多次小改动

**操作**：
- ✅ 直接更新为最终版本
- ❌ 不记录中间的每次迭代
- ✅ 可注明"多次优化后"


---

## 🔍 更新前检查清单

> **核心原则**：追加前先查找，避免重复和遗漏

### 必须执行的检查步骤

**1. 快速浏览全文**（使用 `Read` 或 `Grep`）
```markdown
# 检查是否存在：
- 同主题的旧章节？
- 待更新的状态标记（🔄 待验证）？
- 未完成的TODO项？
```

**2. 判断操作类型**

| 情况 | 操作 |
|------|------|
| **有相关旧内容且错误** | 替换（场景1） |
| **有相关旧内容可改进** | 追加V2（场景2） |
| **有待验证状态** | 更新状态标记 |
| **全新独立内容** | 追加到末尾 |

**3. 必须更新的内容**

- ✅ **状态标记**：`🔄 待验证` → `✅ 已修复` / `❌ 失败`
- ✅ **进度百分比**：更新为最新值
- ✅ **文件修改列表**：补充新修改的文件
- ❌ **禁止**：创建重复的章节标题

### 发布相关变更的三检（新增）

若涉及抖音/微信/B站/小红书发布或扫码登录，额外执行：

1. **路由真值检查**：以 `backend/app/modules/publish/router.py` 为准校验 API 路径，避免文档写成旧路径（例如 `/screenshots/`）。
2. **专项文档对齐**：更新 `Docs/PUBLISH_DEPLOY.md` 中对应平台章节（登录、发布判定、排障）。
3. **入口文档回写**：至少回写一处入口文档（`README.md` 或 `Docs/BACKEND_README.md` / `Docs/DEPLOY_MANUAL.md`）。

### 示例场景

**错误示例**（未检查旧内容）：
```markdown
## 🔧 QR登录修复 (15:00)
**状态**：🔄 待验证

## 🔧 QR登录修复 (16:00)  ❌ 重复！
**状态**：✅ 已修复
```

**正确做法**：
```markdown
## 🔧 QR登录修复 (15:00)
**状态**：✅ 已修复  ← 直接更新原状态
```

---

## ️ 工具使用规范

> **核心原则**：使用正确的工具，避免字符编码问题

### ✅ 推荐工具：Read / Grep / apply_patch

**使用场景**：
- `Read`：更新前先查看文件当前内容
- `apply_patch`：精确替换现有内容、追加新章节
- `Grep`：搜索文件中是否已有相关章节
- `Write`：创建新文件（如 Day{N+1}.md）

**注意事项**：
```markdown
1. **先读后写**：编辑前先用 Read 确认内容
2. **精确匹配**：`apply_patch` 的上下文必须与文件内容一致
3. **避免重复**：编辑前用 Grep 检查是否已存在同主题章节
```

### ❌ 禁止使用：命令行工具修改文档

**禁止场景**：
- ❌ 使用 `echo >>` 追加内容
- ❌ 使用 `sed` / `awk` 修改文档
- ❌ 使用 `cat <<EOF` 写入内容

**原因**：
- 容易破坏 UTF-8 编码和中文字符
- 难以追踪修改，容易出错
- 无法精确匹配替换位置

### 📝 最佳实践示例

**追加新章节**：使用 `apply_patch`，以文件末尾稳定上下文为锚点追加。

**修改现有内容**：使用 `apply_patch` 精确替换。
```markdown
@@
-**状态**：🔄 待修复
+**状态**：✅ 已修复
```


---

## 📁 文件结构

```
ViGent2/Docs/
├── TASK_COMPLETE.md              # 任务总览（仅按需更新）
├── DOC_RULES.md                  # 本文件
├── BACKEND_DEV.md                # 后端开发规范
├── BACKEND_README.md             # 后端功能文档
├── FRONTEND_DEV.md               # 前端开发规范
├── FRONTEND_README.md            # 前端功能文档
├── DEPLOY_MANUAL.md              # 部署手册
├── PUBLISH_DEPLOY.md             # 多平台发布专项文档
├── SUPABASE_DEPLOY.md            # Supabase 部署文档
├── LATENTSYNC_DEPLOY.md          # LatentSync 部署文档
├── COSYVOICE3_DEPLOY.md           # 声音克隆部署文档
├── ALIPAY_DEPLOY.md              # 支付宝付费部署文档
├── SUBTITLE_DEPLOY.md            # 字幕系统部署文档
└── DevLogs/
    ├── Day1.md                   # 开发日志
    └── ...
```

---

## 📅 DayN.md 更新规则（日常更新）

### 更新时机

> **边开发边记录，不要等到最后才写。**

- 每完成一个功能/修复后，**立即**追加到 DayN.md
- 避免积攒到对话末尾一次性补写，容易遗漏变更
- `TASK_COMPLETE.md` 同理，重要变更完成后及时同步

### 新建判断 (对话开始前)
1. **回顾进度**：查看 `TASK_COMPLETE.md` 了解当前状态
2. **检查日期**：查看最新 `DayN.md`
   - **今天 (与当前日期相同)** → 🚨 **绝对禁止创建新文件**，必须**追加**到现有 `DayN.md` 末尾！即使是完全不同的功能模块。
   - **之前 (昨天或更早)** → 创建 `Day{N+1}.md`

### 追加格式
```markdown
---

## 🔧 [章节标题]

### 问题描述
简要描述...

### 解决方案
```code
# 代码示例
```

### 结果
- ✅ 修复了 xxx
```

### 快速修复格式
```markdown
## 🐛 [Bug 简述] (HH:MM)

**问题**：一句话描述
**修复**：修改了 `文件名` 中的 xxx
**状态**：✅ 已修复 / 🔄 待验证
```

### ⚠️ 注意
- **DayN.md 文件开头禁止使用 `---`**，避免被解析为 Front Matter。
- 分隔线只用于章节之间，不作为文件第一行。

---

## 📏 内容简洁性规则

### 代码示例长度控制
- **原则**：只展示关键代码片段（10-20行以内）
- **超长代码**：使用 `// ... 省略 ...` 或仅列出文件名+行号
- **完整代码**：引用文件链接，而非粘贴全文

### 调试信息处理
- **临时调试**：验证后删除（如调试日志、测试截图）
- **有价值信息**：保留（如错误日志、性能数据）

### 敏感信息处理
- **禁止落盘**：Cookie 值、Token、密钥、完整手机号、支付凭证。
- **日志引用**：仅记录必要关键词与结论，避免粘贴大段原始日志。
- **路径引用**：优先给相对路径与文件名，不记录无关个人目录信息。

### 状态标记更新
- **🔄 待验证** → 验证后更新为 **✅ 已修复** 或 **❌ 失败**
- 直接修改原状态，无需追加新行


---

## 📝 TASK_COMPLETE.md 更新规则

> 与 DayN.md 同步更新，记录重要变更时更新任务总览。

### 更新原则
- **格式一致性**：直接参考 `TASK_COMPLETE.md` 现有格式追加内容。
- **进度更新**：仅在阶段性里程碑时更新进度百分比。

### 🔍 完整性检查清单 (必做)

每次更新 `TASK_COMPLETE.md` 时，必须**逐一检查**以下板块：

1. **文件头部**
   - [ ] `更新时间`：必须是当天日期
   - [ ] `整体进度`：与当前 Day 状态一致（例如 Day31）

2. **当日 Current 区块**
   - [ ] 新增/更新 `Day N (Current)` 标题
   - [ ] 关键任务以 `[x]` 列出（避免仅写结论）
   - [ ] 前一天 Day 标题取消 `(Current)` 标记

3. **Roadmap 与模块状态**
   - [ ] 如有已完成长期事项，及时从待办迁移到已完成
   - [ ] 模块完成度有变化时同步更新

4. **相关文档链接**
   - [ ] 新增的核心文档（如 `PUBLISH_DEPLOY.md`）要在相关位置可追溯
   - [ ] 若 DayN 记录了“文档回写”，`TASK_COMPLETE.md` 的当日条目也要体现

> **口诀**：头部日期、当日 Current、模块状态、链接可追溯。

---

**最后更新**：2026-03-03