ViGent2/Docs/Doc_Rules.md

# 📋 开发日志更新规则

> **本文件定义了 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/FRONTEND_DEV.md` | **(前端规范)** API封装、日期格式化、新页面规范 |
| ⚡ **Med** | `Docs/FRONTEND_README.md` | **(前端文档)** 功能说明、页面变更 |
| 🧊 **Low** | `Docs/implementation_plan.md` | **(实施计划)** 核对计划与实际实现的差异 |
| 🧊 **Low** | `Docs/architecture_plan.md` | **(前端架构)** 拆分计划与阶段目标 |

---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


---

## 🔍 更新前检查清单

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

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

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

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

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

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

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

### 示例场景

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

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

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

---

## ️ 工具使用规范

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

### ✅ 推荐工具：apply_patch

**使用场景**：
- 追加新章节到文件末尾
- 修改/替换现有章节内容
- 更新状态标记（🔄 → ✅）
- 修正错误内容

**优势**：
- ✅ 自动处理字符编码（Windows CRLF）
- ✅ 精确替换，不会误删其他内容
- ✅ 有错误提示，方便调试

**注意事项**：
```markdown
1. **必须精确匹配**：TargetContent 必须与文件完全一致
2. **处理换行符**：文件使用 \r\n，不要漏掉 \r
3. **合理范围**：StartLine/EndLine 应覆盖目标内容
4. **先读后写**：编辑前先 view_file 确认内容
```

### ❌ 禁止使用：命令行工具

**禁止场景**：
- ❌ 使用 `echo >>` 追加内容（编码问题）
- ❌ 使用 PowerShell 直接修改文档（破坏格式）
- ❌ 使用 sed/awk 等命令行工具

**原因**：
- 容易破坏 UTF-8 编码
- Windows CRLF vs Unix LF 混乱
- 难以追踪修改，容易出错

**唯一例外**：简单的全局文本替换（如批量更新日期），且必须使用 `-NoNewline` 参数

### 📝 最佳实践示例

**追加新章节**：
```diff
*** Begin Patch
*** Update File: Docs/DevLogs/DayN.md
@@
 ## 🔗 相关文档
 
 ...
---

## 🆕 新章节
内容...
*** End Patch
```

**修改现有内容**：
```diff
*** Begin Patch
*** Update File: Docs/DevLogs/DayN.md
@@
-**状态**：🔄 待修复
+**状态**：✅ 已修复
*** End Patch
```


---

## 📁 文件结构

```
ViGent2/Docs/
├── task_complete.md              # 任务总览（仅按需更新）
├── Doc_Rules.md                  # 本文件
├── FRONTEND_DEV.md               # 前端开发规范
├── FRONTEND_README.md            # 前端功能文档
├── architecture_plan.md          # 前端拆分计划
├── DEPLOY_MANUAL.md              # 部署手册
├── SUPABASE_DEPLOY.md            # Supabase 部署文档
└── DevLogs/
    ├── Day1.md                   # 开发日志
    └── ...
```

---

## 📅 DayN.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行以内）
- **超长代码**：使用 `// ... 省略 ...` 或仅列出文件名+行号
- **完整代码**：引用文件链接，而非粘贴全文

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

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


---

## 📝 task_complete.md 更新规则（仅按需）

> ⚠️ **仅当用户明确要求更新 `task_complete.md` 时才更新**

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

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

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

1. **文件头部 & 导航**
   - [ ] `更新时间`：必须是当天日期
   - [ ] `整体进度`：简述当前状态
   - [ ] `快速导航`：Day 范围与文档一致

2. **核心任务区**
   - [ ] `已完成任务`：添加新的 [x] 项目
   - [ ] `后续规划`：管理三色板块 (优先/债务/未来)

3. **统计与回顾**
   - [ ] `进度统计`：更新对应模块状态和百分比
   - [ ] `里程碑`：若有重大进展，追加 `## Milestone N`

4. **底部链接**
   - [ ] `时间线`：追加今日概括
   - [ ] `相关文档`：更新 DayLog 链接范围

> **口诀**：头尾时间要对齐，任务规划两手抓，里程碑上别落下。

---

**最后更新**：2026-02-04