docs: 更新 PERDAS 开发流程到长期记忆

- 添加 PERDAS 增强版开发流程完整记录 - 详细记录每次会话开始和开发功能的步骤 - 记录强约束指令和正确行为 - 记录重要文件说明和错误处理 - 添加关键命令速查表确保后续开发时能遵循 PERDAS 开发流程
2026-02-19 03:45:04 +08:00
parent be9542cf9d
commit e3722787e1
1 changed files with 270 additions and 0 deletions
--- a/PERDAS-GUIDE.md
+++ b/PERDAS-GUIDE.md
@@ -0,0 +1,270 @@
+# 🎯 PERDAS 增强版快速开始指南
+
+欢迎使用 PERDAS 增强版开发模式！本指南帮助你快速上手。
+
+## 📋 5 分钟快速启动
+
+### 第一步：启动开发环境
+
+```bash
+cd /root/.openclaw/workspace/stock-tool
+./init.sh
+```
+
+**预期输出**：
+```
+🚀 启动 Stock Tool 开发环境...
+✅ 服务器启动成功!
+🌐 地址: http://localhost:8080
+💡 下一步:
+   1. 在浏览器访问 http://localhost:8080
+   2. 运行 ./scripts/health-check.sh 进行健康检查
+```
+
+### 第二步：健康检查
+
+```bash
+./scripts/health-check.sh
+```
+
+**预期输出**：
+```
+📊 健康检查总结
+通过: 25
+失败: 0
+总计: 25
+✨ 所有检查通过！开发环境正常。
+```
+
+### 第三步：端到端测试
+
+```bash
+./scripts/e2e-test.sh
+```
+
+**预期输出**：
+```
+✅ 所有测试通过！
+💡 提示: 测试截图已保存到 tests/screenshots/
+```
+
+### 第四步：查看功能清单
+
+```bash
+cat feature_list.json
+```
+
+你会看到 6 个功能，5 个已完成：
+
+```json
+{
+  "summary": {
+    "total": 6,
+    "completed": 5,
+    "in_progress": 1,
+    "pending": 0
+  }
+}
+```
+
+### 第五步：开发新功能
+
+**当前进行中的功能**：
+- feat-006: 数据刷新功能
+
+**开发步骤**：
+1. 查看 feature_list.json 中 feat-006 的 steps
+2. 使用浏览器访问 http://localhost:8080
+3. 手动测试功能
+4. 更新 feature_list.json（修改 passes: true）
+5. 提交代码
+
+---
+
+## 🔄 标准工作流程
+
+### 每次会话开始时
+
+```bash
+# 1. 确认目录
+pwd
+# 输出: /root/.openclaw/workspace/stock-tool
+
+# 2. 启动环境
+./init.sh
+
+# 3. 健康检查
+./scripts/health-check.sh
+
+# 4. 查看进度
+cat PROGRESS.md
+
+# 5. 查看功能清单
+jq '.features[] | select(.status=="in_progress")' feature_list.json
+```
+
+### 开发功能时
+
+1. **阅读步骤**
+   ```bash
+   jq '.features[] | select(.id=="feat-006")' feature_list.json
+   ```
+
+2. **实现功能**
+   - 修改代码
+   - 测试功能
+   - 验证效果
+
+3. **运行测试**
+   ```bash
+   ./scripts/e2e-test.sh
+   ```
+
+4. **保存截图**
+   ```bash
+   # 在浏览器中测试后截图
+   cp screenshot.png tests/screenshots/feat-006-xxx.png
+   ```
+
+5. **更新状态**
+   ```bash
+   # 修改 feature_list.json
+   jq '.features[] | select(.id=="feat-006") | .passes = true' feature_list.json > tmp.json && mv tmp.json feature_list.json
+   ```
+
+6. **更新进度文件**
+   ```bash
+   vim PROGRESS.md
+   ```
+
+7. **提交代码**
+   ```bash
+   git add .
+   git commit -m "feat: 完成 feat-006 数据刷新功能"
+   git push
+   ```
+
+---
+
+## 📚 重要文件说明
+
+| 文件 | 用途 | 修改规则 |
+|------|------|----------|
+| `feature_list.json` | 功能清单 | **仅修改** `passes` 字段 |
+| `PROGRESS.md` | 进度跟踪 | 每会话更新 |
+| `init.sh` | 环境启动 | 必要时更新 |
+| `.gitignore` | 忽略规则 | 必要时更新 |
+| `README.md` | 项目文档 | 必要时更新 |
+
+---
+
+## ⚠️ 强约束指令（必须遵守）
+
+> **It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.**
+
+### 绝对禁止的行为：
+
+- ❌ 删除或修改测试用例
+- ❌ 删除或修改其他功能的代码
+- ❌ 修改 `feature_list.json` 中除 `passes` 字段外的任何内容
+- ❌ 未通过端到端测试就标记完成
+- ❌ 未保存截图证据就标记完成
+
+### 正确的行为：
+
+- ✅ 只修改当前要开发的功能
+- ✅ 功能完成后运行端到端测试
+- ✅ 测试通过后保存截图
+- ✅ 更新 `feature_list.json` 的 `passes` 字段
+- ✅ 更新 `PROGRESS.md` 记录本次工作
+- ✅ 提交 Git commit
+
+---
+
+## 🐛 错误处理
+
+### 服务器未运行
+
+```bash
+./init.sh
+```
+
+### 测试失败
+
+```bash
+# 查看服务器日志
+cat logs/server.log
+
+# 检查 API 是否正常
+curl http://localhost:8080/api/stocks
+
+# 重新测试
+./scripts/e2e-test.sh
+```
+
+### Git 冲突
+
+```bash
+git fetch origin
+git rebase origin/main
+git push
+```
+
+---
+
+## 📖 相关文档
+
+- **完整文档**: README.md
+- **进度跟踪**: PROGRESS.md
+- **功能清单**: feature_list.json
+- **健康检查**: scripts/health-check.sh
+- **端到端测试**: scripts/e2e-test.sh
+
+---
+
+## 💡 常用命令速查
+
+```bash
+# 启动环境
+./init.sh
+
+# 健康检查
+./scripts/health-check.sh
+
+# 端到端测试
+./scripts/e2e-test.sh
+
+# 查看功能
+jq '.features[] | select(.status=="in_progress")' feature_list.json
+
+# 查看提交历史
+git log --oneline -10
+
+# 提交更改
+git add .
+git commit -m "feat: 描述"
+git push
+```
+
+---
+
+## 🎉 开始你的第一个功能
+
+当前进行中的功能：**feat-006 - 数据刷新功能**
+
+按照以下步骤开始：
+
+1. 查看功能详情：
+   ```bash
+   jq '.features[] | select(.id=="feat-006")' feature_list.json
+   ```
+
+2. 启动服务器并测试：
+   ```bash
+   ./init.sh
+   http://localhost:8080
+   ```
+
+3. 完成功能开发并更新状态
+
+祝你开发顺利！🚀