9.1 KiB
9.1 KiB
📋 开发日志更新规则
本文件定义了 AI 助手更新开发文档的规范
⚡ 核心原则
| 规则 | 说明 |
|---|---|
| 默认更新 | 更新 DayN.md 和 TASK_COMPLETE.md |
| 按需更新 | 其他文档仅在内容变化涉及时更新 |
| 智能修改 | 错误→替换，改进→追加（见下方详细规则） |
| 先读后写 | 更新前先查看文件当前内容 |
| 日内合并 | 同一天的多次小修改合并为最终版本 |
🧾 全局文档更新清单 (Checklist)
每次提交重要变更时，请核对以下文件是否需要同步：
| 优先级 | 文件路径 | 检查重点 |
|---|---|---|
| 🔥 High | Docs/DevLogs/DayN.md |
(最新日志) 详细记录变更、修复、代码片段 |
| 🔥 High | Docs/TASK_COMPLETE.md |
(任务总览) 更新 [x]、进度条、时间线 |
| ⚡ Med | README.md |
(项目主页) 功能特性、技术栈、最新截图 |
| ⚡ Med | Docs/DEPLOY_MANUAL.md |
(部署手册) 环境变量、依赖包、启动命令变更 |
| ⚡ Med | Docs/BACKEND_DEV.md |
(后端规范) 接口契约、模块划分、环境变量 |
| ⚡ Med | Docs/BACKEND_README.md |
(后端文档) 接口说明、架构设计 |
| ⚡ Med | Docs/FRONTEND_DEV.md |
(前端规范) API封装、日期格式化、新页面规范 |
| ⚡ Med | Docs/FRONTEND_README.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. 必须更新的内容
- ✅ 状态标记：
🔄 待验证→✅ 已修复/❌ 失败 - ✅ 进度百分比：更新为最新值
- ✅ 文件修改列表：补充新修改的文件
- ❌ 禁止：创建重复的章节标题
示例场景
错误示例（未检查旧内容）：
## 🔧 QR登录修复 (15:00)
**状态**：🔄 待验证
## 🔧 QR登录修复 (16:00) ❌ 重复！
**状态**：✅ 已修复
正确做法：
## 🔧 QR登录修复 (15:00)
**状态**：✅ 已修复 ← 直接更新原状态
️ 工具使用规范
核心原则：使用正确的工具，避免字符编码问题
✅ 推荐工具：Edit / Read / Grep
使用场景：
Read：更新前先查看文件当前内容Edit：精确替换现有内容、追加新章节Grep：搜索文件中是否已有相关章节Write：创建新文件（如 Day{N+1}.md）
注意事项：
1. **先读后写**：编辑前先用 Read 确认内容
2. **精确匹配**：Edit 的 old_string 必须与文件内容完全一致
3. **避免重复**：编辑前用 Grep 检查是否已存在同主题章节
❌ 禁止使用：命令行工具修改文档
禁止场景：
- ❌ 使用
echo >>追加内容 - ❌ 使用
sed/awk修改文档 - ❌ 使用
cat <<EOF写入内容
原因：
- 容易破坏 UTF-8 编码和中文字符
- 难以追踪修改，容易出错
- 无法精确匹配替换位置
📝 最佳实践示例
追加新章节：使用 Edit 工具，old_string 匹配文件末尾内容，new_string 包含原内容 + 新章节。
修改现有内容：使用 Edit 工具精确替换。
old_string: "**状态**：🔄 待修复"
new_string: "**状态**：✅ 已修复"
📁 文件结构
ViGent2/Docs/
├── TASK_COMPLETE.md # 任务总览（仅按需更新）
├── DOC_RULES.md # 本文件
├── BACKEND_DEV.md # 后端开发规范
├── BACKEND_README.md # 后端功能文档
├── FRONTEND_DEV.md # 前端开发规范
├── FRONTEND_README.md # 前端功能文档
├── DEPLOY_MANUAL.md # 部署手册
├── SUPABASE_DEPLOY.md # Supabase 部署文档
├── LATENTSYNC_DEPLOY.md # LatentSync 部署文档
├── COSYVOICE3_DEPLOY.md # 声音克隆部署文档
├── SUBTITLE_DEPLOY.md # 字幕系统部署文档
└── DevLogs/
├── Day1.md # 开发日志
└── ...
📅 DayN.md 更新规则（日常更新）
更新时机
边开发边记录，不要等到最后才写。
- 每完成一个功能/修复后，立即追加到 DayN.md
- 避免积攒到对话末尾一次性补写，容易遗漏变更
TASK_COMPLETE.md同理，重要变更完成后及时同步
新建判断 (对话开始前)
- 回顾进度：查看
TASK_COMPLETE.md了解当前状态 - 检查日期：查看最新
DayN.md- 今天 (与当前日期相同) → 🚨 绝对禁止创建新文件，必须追加到现有
DayN.md末尾！即使是完全不同的功能模块。 - 之前 (昨天或更早) → 创建
Day{N+1}.md
- 今天 (与当前日期相同) → 🚨 绝对禁止创建新文件，必须追加到现有
追加格式
---
## 🔧 [章节标题]
### 问题描述
简要描述...
### 解决方案
```code
# 代码示例
结果
- ✅ 修复了 xxx
### 快速修复格式
```markdown
## 🐛 [Bug 简述] (HH:MM)
**问题**：一句话描述
**修复**：修改了 `文件名` 中的 xxx
**状态**：✅ 已修复 / 🔄 待验证
⚠️ 注意
- DayN.md 文件开头禁止使用
---，避免被解析为 Front Matter。 - 分隔线只用于章节之间，不作为文件第一行。
📏 内容简洁性规则
代码示例长度控制
- 原则：只展示关键代码片段（10-20行以内）
- 超长代码：使用
// ... 省略 ...或仅列出文件名+行号 - 完整代码：引用文件链接，而非粘贴全文
调试信息处理
- 临时调试：验证后删除（如调试日志、测试截图）
- 有价值信息：保留（如错误日志、性能数据）
状态标记更新
- 🔄 待验证 → 验证后更新为 ✅ 已修复 或 ❌ 失败
- 直接修改原状态，无需追加新行
📝 TASK_COMPLETE.md 更新规则
与 DayN.md 同步更新，记录重要变更时更新任务总览。
更新原则
- 格式一致性：直接参考
TASK_COMPLETE.md现有格式追加内容。 - 进度更新：仅在阶段性里程碑时更新进度百分比。
🔍 完整性检查清单 (必做)
每次更新 TASK_COMPLETE.md 时，必须逐一检查以下所有板块：
-
文件头部 & 导航
更新时间：必须是当天日期整体进度：简述当前状态快速导航：Day 范围与文档一致
-
核心任务区
已完成任务：添加新的 [x] 项目后续规划：管理三色板块 (优先/债务/未来)
-
统计与回顾
进度统计：更新对应模块状态和百分比里程碑：若有重大进展，追加## Milestone N
-
底部链接
时间线：追加今日概括相关文档：更新 DayLog 链接范围
口诀：头尾时间要对齐，任务规划两手抓，里程碑上别落下。
最后更新：2026-02-08