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)**：[错误原因]，已更新
• ❌ 不保留错误方法（避免误导）

示例：

## 🔧 XXX功能修复

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

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

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

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

操作：

• ✅ 保留原方法（标注版本 V1/V2）
• ✅ 追加新方法
• ✅ 说明改进原因

示例：

## ⚡ 性能优化

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

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

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

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

操作：

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

---

🔍 更新前检查清单

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

必须执行的检查步骤

1. 快速浏览全文（使用 Read 或 Grep）

# 检查是否存在：
- 同主题的旧章节？
- 待更新的状态标记（🔄 待验证）？
- 未完成的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）。

示例场景

错误示例（未检查旧内容）：

## 🔧 QR登录修复 (15:00)
**状态**：🔄 待验证

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

正确做法：

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

---

️ 工具使用规范

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

✅ 推荐工具：Read / Grep / apply_patch

使用场景：

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

注意事项：

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

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

禁止场景：

• ❌ 使用 echo >> 追加内容
• ❌ 使用 sed / awk 修改文档
• ❌ 使用 cat <<EOF 写入内容

原因：

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

📝 最佳实践示例

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

修改现有内容：使用 apply_patch 精确替换。

@@
-**状态**：🔄 待修复
+**状态**：✅ 已修复

---

📁 文件结构

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

追加格式

---

## 🔧 [章节标题]

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

### 解决方案
```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