Originals/ViGent2

Fork 0

Files

Kevin Wong 74516dbcdb 更新

2026-02-04 11:56:37 +08:00

8.8 KiB

Raw Permalink Blame History

📋 开发日志更新规则

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

示例：

## 🔧 XXX功能修复

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

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

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

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

操作：

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

示例：

## ⚡ 性能优化

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

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

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

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

操作：

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

🔍 更新前检查清单

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

必须执行的检查步骤

1. 快速浏览全文（使用 view_file 或 grep_search）

# 检查是否存在：
- 同主题的旧章节？
- 待更新的状态标记（🔄 待验证）？
- 未完成的TODO项？

2. 判断操作类型

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

3. 必须更新的内容

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

示例场景

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

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

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

正确做法：

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

️ 工具使用规范

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

✅ 推荐工具：apply_patch

使用场景：

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

优势：

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

注意事项：

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

❌ 禁止使用：命令行工具

禁止场景：

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

原因：

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

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

📝 最佳实践示例

追加新章节：

*** Begin Patch
*** Update File: Docs/DevLogs/DayN.md
@@
 ## 🔗 相关文档
 
 ...
---

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

修改现有内容：

*** 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 更新规则（日常更新）

新建判断 (对话开始前)

回顾进度：查看 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 更新规则（仅按需）

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

更新原则

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

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

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

文件头部 & 导航
- 更新时间：必须是当天日期
- 整体进度：简述当前状态
- 快速导航：Day 范围与文档一致
核心任务区
- 已完成任务：添加新的 [x] 项目
- 后续规划：管理三色板块 (优先/债务/未来)
统计与回顾
- 进度统计：更新对应模块状态和百分比
- 里程碑：若有重大进展，追加 ## Milestone N
底部链接
- 时间线：追加今日概括
- 相关文档：更新 DayLog 链接范围

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

最后更新：2026-02-04

8.8 KiB Raw Permalink Blame History Unescape Escape