From 9f493c12f91fe14623b35579a012b7f7cdf14a3f Mon Sep 17 00:00:00 2001 From: hwd32 Date: Sat, 23 May 2026 21:53:05 +0800 Subject: [PATCH] =?UTF-8?q?feat(context):=20=E6=96=B0=E5=A2=9E=20resume-co?= =?UTF-8?q?ntext=20Skill=20=E5=92=8C=E9=A1=B9=E7=9B=AE=E4=B8=8A=E4=B8=8B?= =?UTF-8?q?=E6=96=87=E6=96=87=E6=A1=A3=E4=BD=93=E7=B3=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 resume-context Skill（接着干）- 换电脑时自动同步上下文 - 新增 docs/PROJECT_CONTEXT.md 项目整体上下文 - 新增 docs/DECISIONS.md 架构决策记录（ADR） - 新增 docs/06_开发日志/ 按日期记录讨论内容 - 新增根目录 ENVIRONMENT.md 开发环境配置 - 更新 ai-collab-setup/SKILL.md 版本升至 v2.2 --- .trae/skills/ai-collab-setup/SKILL.md | 18 ++- .trae/skills/resume-context/SKILL.md | 138 +++++++++++++++++++++ ENVIRONMENT.md | 74 ++++++++++++ docs/06_开发日志/2026-05-23_框架搭建.md | 57 +++++++++ docs/06_开发日志/README.md | 18 +++ docs/DECISIONS.md | 154 ++++++++++++++++++++++++ docs/PROJECT_CONTEXT.md | 112 +++++++++++++++++ 7 files changed, 560 insertions(+), 11 deletions(-) create mode 100644 .trae/skills/resume-context/SKILL.md create mode 100644 ENVIRONMENT.md create mode 100644 docs/06_开发日志/2026-05-23_框架搭建.md create mode 100644 docs/06_开发日志/README.md create mode 100644 docs/DECISIONS.md create mode 100644 docs/PROJECT_CONTEXT.md diff --git a/.trae/skills/ai-collab-setup/SKILL.md b/.trae/skills/ai-collab-setup/SKILL.md index 7e1eea7..45c9838 100644 --- a/.trae/skills/ai-collab-setup/SKILL.md +++ b/.trae/skills/ai-collab-setup/SKILL.md @@ -1055,17 +1055,13 @@ skill 执行后： --- -**Version**: 2.1 +**Version**: 2.2 **Created**: 2026-05-23 **Updated**: 2026-05-23 **Based On**: ErrLens AI Programming Project -**Changes from v2.0**: -- 新增项目级目录 docs/、tools/、data/ -- 权限矩阵新增 docs/ (Dev:RW, QA:R)、tools/ (Dev:RW)、data/ (Dev:RW, QA:R) -- Dev AI 职责新增：维护项目级文档、开发工具、训练数据 -- QA AI 只读路径新增 docs/、data/ -- QA AI 禁止路径新增 tools/ -- 工作流从线性升级为 4 阶段 + retry + escalation -- 新增提示词模板（code-style.md、doc-template.md、bug-report.md） -- JSON 配置新增 description 语义定义 -- 目录结构新增 src/server/、src/config/、src/types/ 子目录 \ No newline at end of file +**Changes from v2.1**: +- 新增 resume-context Skill（接着干）- 解决多电脑切换时的上下文同步 +- 新增 docs/PROJECT_CONTEXT.md 项目整体上下文 +- 新增 docs/DECISIONS.md 架构决策记录（ADR） +- 新增 docs/06_开发日志/ 按日期记录讨论内容 +- 新增根目录 ENVIRONMENT.md 开发环境配置 \ No newline at end of file diff --git a/.trae/skills/resume-context/SKILL.md b/.trae/skills/resume-context/SKILL.md new file mode 100644 index 0000000..8edd924 --- /dev/null +++ b/.trae/skills/resume-context/SKILL.md @@ -0,0 +1,138 @@ +--- +name: "resume-context" +description: "Loads project context and syncs conversation history. Invoke when user switches computers, starts a new session, or says '接着干'、'继续'、'resume'." +--- + +# 接着干 - 上下文同步 Skill + +## 功能 + +当用户更换电脑、开启新会话、或说"接着干"时，自动读取项目上下文文档，恢复之前的开发状态和讨论背景。 + +## 触发条件 + +- 用户说"接着干"、"继续"、"resume"、"continue" +- 用户提到更换电脑/环境 +- 新会话开始，需要恢复上下文 +- 用户说"同步一下思路" + +## 执行步骤 + +### 1. 读取项目上下文 + +按以下顺序读取核心文档： + +``` +1. docs/PROJECT_CONTEXT.md # 项目整体上下文 +2. docs/DECISIONS.md # 关键决策记录 +3. docs/06_开发日志/ # 最新开发日志（按日期倒序） +4. AGENTS.md # AI 角色和权限约定 +``` + +### 2. 读取最新开发日志 + +```powershell +# 获取最新的开发日志文件 +Get-ChildItem "docs/06_开发日志/" -Filter "*.md" | Sort-Object Name -Descending | Select-Object -First 3 +``` + +读取最近 3 篇日志，了解最近的讨论内容。 + +### 3. 同步状态 + +向用户报告当前状态： + +```markdown +## 上下文同步完成 + +### 项目状态 +- **当前阶段**: [从 PROJECT_CONTEXT.md 读取] +- **最新任务**: [从 review/active/ 读取最新任务] +- **最近工作**: [从最新开发日志读取] + +### 待办事项 +- [从 PROJECT_CONTEXT.md 和开发日志中提取] + +### 可以继续的工作 +- [列出可以继续开发的任务] +``` + +### 4. 确认用户意图 + +询问用户： +- 继续上次未完成的工作？ +- 开始新的任务？ +- 查看项目状态？ + +## 文档格式要求 + +### PROJECT_CONTEXT.md + +```markdown +# 项目上下文 + +## 项目愿景 +[一句话描述项目目标] + +## 当前阶段 +[当前处于哪个阶段，已完成什么] + +## 技术栈 +[主要技术选型] + +## 团队架构 +[1 人 + 2AI 协作模式] + +## 关键决策 +[列出重要决策和原因] + +## 待解决问题 +[列出悬而未决的问题] + +## 下一步计划 +[接下来的工作重点] +``` + +### 开发日志格式 + +```markdown +# YYYY-MM-DD_主题 + +## 讨论内容 +[主要讨论了什么] + +## 关键决策 +[做出了什么决定] + +## 完成的工作 +[做了什么改动] + +## 待办事项 +[接下来要做什么] +``` + +## 使用场景 + +**何时调用此 skill：** +- ✅ 更换电脑后开始工作 +- ✅ 开启新会话，需要恢复上下文 +- ✅ 长时间未开发，需要回忆项目状态 +- ✅ 用户说"接着干"、"继续" + +**不适用场景：** +- ❌ 首次启动项目（应使用 ai-collab-setup） +- ❌ 只需要查看代码（直接搜索即可） + +## 注意事项 + +1. **不要修改文档**：此 skill 只读取上下文，不修改任何文件 +2. **关注最新内容**：优先读取最新的开发日志 +3. **识别阻塞点**：注意 PROJECT_CONTEXT.md 中的"待解决问题" +4. **权限意识**：遵循 AGENTS.md 中的权限约定 + +--- + +**Version**: 1.0 +**Created**: 2026-05-23 +**Based On**: ErrLens AI Programming Project +**Purpose**: 解决用户多电脑切换时的上下文同步问题 diff --git a/ENVIRONMENT.md b/ENVIRONMENT.md new file mode 100644 index 0000000..e09f924 --- /dev/null +++ b/ENVIRONMENT.md @@ -0,0 +1,74 @@ +# ErrLens 开发环境配置 + +## 前置依赖 + +| 工具 | 版本要求 | 说明 | +|------|---------|------| +| Node.js | >= 20.x | JavaScript 运行时 | +| pnpm | >= 9.0.0 | 包管理器 | +| Python | >= 3.10 | AI 训练算法 | +| Git | >= 2.40 | 版本控制 | + +## 快速开始 + +```bash +# 1. 克隆项目 +git clone +cd errlens + +# 2. 安装前端依赖 +pnpm install + +# 3. 恢复上下文（换电脑后） +# 在 Trae 中使用 resume-context Skill + +# 4. 启动开发服务器（根据子项目） +cd projects/P01_errlens_app +pnpm dev +``` + +## 子项目环境 + +### P01_errlens_app（小程序） +```bash +cd projects/P01_errlens_app +pnpm install +pnpm dev +``` + +### P02_errlens_training（训练算法） +```bash +cd projects/P02_errlens_training +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate +pip install -r requirements.txt +``` + +### P03_errlens_web（Web 管理后台） +```bash +cd projects/P03_errlens_web +pnpm install +pnpm dev +``` + +## 开发工具 + +- **IDE**: Trae CN +- **AI 协作**: 1 人 + 2AI（Dev AI + QA AI） +- **上下文同步**: 使用 `resume-context` Skill + +## 跨平台开发 + +本项目支持在 Windows、macOS、Linux 上开发。换电脑时： + +1. `git pull` 拉取最新代码 +2. 在 Trae 中使用 `resume-context` Skill 恢复上下文 +3. 继续开发 + +## 环境变量 + +各子项目的环境变量文件： +- `projects/P01_errlens_app/.env` +- `projects/P03_errlens_web/.env` + +参考各子项目的 `ENVIRONMENT.md` 获取详细配置。 diff --git a/docs/06_开发日志/2026-05-23_框架搭建.md b/docs/06_开发日志/2026-05-23_框架搭建.md new file mode 100644 index 0000000..24f018e --- /dev/null +++ b/docs/06_开发日志/2026-05-23_框架搭建.md @@ -0,0 +1,57 @@ +# 2026-05-23_框架搭建 + +## 讨论内容 + +用户是嵌入式 MCU 软件开发者，个人团队开发错题本项目。需求包括： +1. 学生错题本小程序（跨平台，微信优先） +2. Web 管理后台（给老师和机构用） +3. 数据训练算法（错题分析和推荐） +4. 数据飞轮思维（数据采集 → AI 分析 → 个性化推荐） + +用户在家和单位两台电脑间切换开发，需要上下文同步机制。 + +## 关键决策 + +1. **采用"1 人 + 2AI"协作框架** - Dev AI 编码 + QA AI 测试 +2. **R/W/RW/- 四态权限体系** - 比二元权限更灵活 +3. **项目级文档放在根目录 docs/** - 不属于任何子项目 +4. **新增 tools/ 和 data/ 目录** - 开发工具和训练数据独立管理 +5. **工作流增加 retry 和 escalation 机制** - 自动处理 Bug 修复循环 +6. **创建 resume-context Skill** - 解决多电脑切换时的上下文同步 + +## 完成的工作 + +### 框架搭建 +- ✅ 创建完整目录结构 +- ✅ 编写 AGENTS.md（AI 角色和权限约定） +- ✅ 创建 AI 配置文件（coder.json、tester.json、workflow.json） +- ✅ 创建提示词模板（code-style.md、doc-template.md、bug-report.md） + +### Skill 工具 +- ✅ ai-collab-setup - 一键创建协作框架 +- ✅ add-subproject - 动态添加子项目 +- ✅ resume-context - 上下文同步（接着干） + +### 文档体系 +- ✅ docs/PROJECT_CONTEXT.md - 项目整体上下文 +- ✅ docs/DECISIONS.md - 架构决策记录 +- ✅ docs/06_开发日志/ - 开发日志目录 + +### 目录新增 +- ✅ docs/ - 项目级总体文档（5 个子目录） +- ✅ tools/ - 开发工具脚本 +- ✅ data/ - 训练数据 + +## 待办事项 + +1. [ ] 完成产品需求文档（PRD） +2. [ ] 完成系统架构设计 +3. [ ] 启动 P01_errlens_app 小程序开发 +4. [ ] 设计数据采集方案 +5. [ ] 规划 Web 管理后台功能 + +## 备注 + +- 用户是嵌入式开发者，对前端/AI 框架不熟悉，需要 AI 多承担技术选型工作 +- Web 管理后台功能尚未确定，先简化设计，保持可扩展性 +- 用户有一些数据但不够，需要数据飞轮思维 diff --git a/docs/06_开发日志/README.md b/docs/06_开发日志/README.md new file mode 100644 index 0000000..2d11ed2 --- /dev/null +++ b/docs/06_开发日志/README.md @@ -0,0 +1,18 @@ +# 开发日志索引 + +## 使用说明 + +按日期记录开发讨论内容，格式：`YYYY-MM-DD_主题.md` + +## 日志列表 + +| 日期 | 主题 | 文件 | +|------|------|------| +| 2026-05-23 | 框架搭建 | [2026-05-23_框架搭建.md](./2026-05-23_框架搭建.md) | + +## 如何添加新日志 + +1. 在 `docs/06_开发日志/` 下创建新文件 +2. 命名格式：`YYYY-MM-DD_主题.md` +3. 参考 [2026-05-23_框架搭建.md](./2026-05-23_框架搭建.md) 的格式 +4. 更新本索引 diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md new file mode 100644 index 0000000..8f83ca3 --- /dev/null +++ b/docs/DECISIONS.md @@ -0,0 +1,154 @@ +# 架构决策记录 (ADR) + +## 什么是 ADR？ + +ADR（Architecture Decision Record）记录项目中重要的架构决策及其原因。当新成员（或 AI）加入时，可以通过 ADR 快速理解"为什么这么做"。 + +## 决策记录 + +### ADR-001: 采用"1 人 + 2AI"协作框架 + +**日期**: 2026-05-23 +**状态**: 已采纳 +**决策者**: 人类负责人 + +**背景**: +项目需要高效开发，但团队只有 1 人。利用 AI 辅助编程可以大幅提升效率。 + +**决策**: +采用 1 个负责人 + 2 个 AI（Dev AI 编码 + QA AI 测试）的协作模式。 + +**后果**: +- ✅ 开发效率大幅提升 +- ✅ 代码质量有保障（独立测试 AI） +- ⚠️ 需要维护权限体系和协作流程 +- ⚠️ 人类需要审阅 AI 输出 + +--- + +### ADR-002: 采用 R/W/RW/- 四态权限体系 + +**日期**: 2026-05-23 +**状态**: 已采纳 +**决策者**: 人类负责人 + +**背景**: +初始框架使用简单的 allowed/forbidden 二元权限，无法满足"只读"场景。 + +**决策**: +采用四态权限：`-`（无权）、`R`（只读）、`W`（可写）、`RW`（读写）。 + +**后果**: +- ✅ 更细粒度的权限控制 +- ✅ 明确只读路径（如 task.md、feedback/） +- ⚠️ 权限矩阵更复杂，需要维护 + +--- + +### ADR-003: 项目级文档放在根目录 docs/ + +**日期**: 2026-05-23 +**状态**: 已采纳 +**决策者**: 人类负责人 + +**背景**: +项目级文档（产品需求、架构设计等）不属于任何子项目，需要独立存放。 + +**决策**: +在根目录创建 `docs/` 目录，而非 `projects/P00_DOCS/`。 + +**后果**: +- ✅ 语义清晰，业界标准 +- ✅ 路径简短 +- ⚠️ 需要在权限矩阵中单独定义 + +--- + +### ADR-004: 新增 tools/ 和 data/ 目录 + +**日期**: 2026-05-23 +**状态**: 已采纳 +**决策者**: 人类负责人 + +**背景**: +开发工具脚本和训练数据需要独立管理，不应混入项目代码。 + +**决策**: +在根目录创建 `tools/`（开发工具）和 `data/`（训练数据）。 + +**权限**: +- `tools/`: Dev AI 可写，QA AI 禁止 +- `data/`: Dev AI 可写，QA AI 只读 + +**后果**: +- ✅ 职责分离，便于管理 +- ✅ 训练数据独立于代码 +- ⚠️ 需要维护数据版本 + +--- + +### ADR-005: 工作流增加 retry 和 escalation 机制 + +**日期**: 2026-05-23 +**状态**: 已采纳 +**决策者**: 人类负责人 + +**背景**: +线性工作流无法处理测试失败的情况。 + +**决策**: +- 增加 retry 机制：最多 3 轮测试修复循环 +- 增加 escalation 机制：第 3 轮仍有 BLOCKER/HIGH 时升级给人类 + +**后果**: +- ✅ 自动处理常见 Bug 修复 +- ✅ 严重问题及时升级 +- ⚠️ 需要维护修复轮次计数 + +--- + +### ADR-006: 创建 resume-context Skill 解决多电脑同步 + +**日期**: 2026-05-23 +**状态**: 已采纳 +**决策者**: 人类负责人 + +**背景**: +用户在家和单位两台电脑间切换，需要快速恢复开发上下文。 + +**决策**: +- 创建 `resume-context` Skill +- 创建 `docs/PROJECT_CONTEXT.md` 项目上下文 +- 创建 `docs/06_开发日志/` 按日期记录讨论 + +**后果**: +- ✅ 换电脑后快速恢复上下文 +- ✅ 新 AI 对话可以读取背景 +- ⚠️ 需要维护文档更新 + +--- + +## 决策模板 + +```markdown +### ADR-XXX: 决策标题 + +**日期**: YYYY-MM-DD +**状态**: 考虑中 / 已采纳 / 已废弃 +**决策者**: XXX + +**背景**: +[为什么需要做这个决策] + +**决策**: +[具体决定是什么] + +**后果**: +- ✅ 好处 +- ⚠️ 需要注意的点 +``` + +--- + +**最后更新**: 2026-05-23 +**维护者**: 人类负责人 + Dev AI diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md new file mode 100644 index 0000000..64776c9 --- /dev/null +++ b/docs/PROJECT_CONTEXT.md @@ -0,0 +1,112 @@ +# 项目上下文 - ErrLens 错题本 + +## 项目愿景 + +打造跨平台的学生错题本应用，配套 Web 管理后台和数据训练算法，形成"数据采集 → AI 分析 → 个性化推荐"的数据飞轮。 + +## 当前阶段 + +**框架搭建阶段**（2026-05-23 完成） + +已完成： +- ✅ "1 人 + 2AI（Dev AI + QA AI）"协作框架 +- ✅ 完整目录结构和权限体系（R/W/RW/- 四态） +- ✅ AI 配置文件（coder.json、tester.json、workflow.json） +- ✅ 提示词模板（code-style.md、doc-template.md、bug-report.md） +- ✅ Skill 工具（ai-collab-setup、add-subproject、resume-context） +- ✅ 项目级文档目录（docs/、tools/、data/） + +待启动： +- ⏳ P01_errlens_app 小程序开发 +- ⏳ P02_errlens_training 数据训练算法 +- ⏳ P03_errlens_web Web 管理后台 + +## 技术栈 + +| 层级 | 技术选型 | 说明 | +|------|---------|------| +| 小程序 | Taro + React + TypeScript | 跨平台（微信优先，预留支付宝/抖音） | +| Web 管理 | Next.js + React + TypeScript | SSR，便于 SEO 和性能 | +| 后端 | NestJS + TypeScript | 统一语言，便于维护 | +| 数据库 | PostgreSQL | 关系型数据，支持复杂查询 | +| AI 训练 | Python + PyTorch | 错题分析和推荐算法 | +| 包管理 | pnpm | 快速、节省磁盘空间 | +| 协作框架 | 1 人 + 2AI | Dev AI（编码）+ QA AI（测试） | + +## 团队架构 + +``` +人类负责人（唯一决策者） +├── Dev AI（编码 AI）- 编写代码、文档、影响评估 +└── QA AI（测试 AI）- 编写测试、执行测试、质量保障 +``` + +详细权限见 [AGENTS.md](../AGENTS.md) + +## 关键决策 + +| 决策 | 原因 | 日期 | +|------|------|------| +| 采用 R/W/RW/- 四态权限体系 | 比二元权限更灵活，明确只读路径 | 2026-05-23 | +| 项目级文档放在根目录 docs/ | 不属于任何子项目，业界标准做法 | 2026-05-23 | +| 新增 tools/ 和 data/ 目录 | 开发工具和训练数据需要独立管理 | 2026-05-23 | +| 创建 resume-context Skill | 解决多电脑切换时的上下文同步问题 | 2026-05-23 | +| 工作流增加 retry 机制 | 允许最多 3 轮测试修复循环 | 2026-05-23 | +| 工作流增加 escalation 机制 | 第 3 轮仍有严重 Bug 时升级给人类 | 2026-05-23 | + +## 待解决问题 + +1. **Web 管理后台具体功能** - 尚未确定，需要简化设计，保持可扩展性 +2. **数据来源** - 用户有一些数据但不够，需要数据飞轮思维 +3. **跨平台优先级** - 目前主要是微信，但框架上要考虑跨平台 +4. **AI 训练算法细节** - 错题分析和推荐算法的具体实现方案 + +## 下一步计划 + +1. [ ] 完成产品需求文档（PRD） +2. [ ] 完成系统架构设计 +3. [ ] 启动 P01_errlens_app 小程序开发 +4. [ ] 设计数据采集方案 +5. [ ] 规划 Web 管理后台功能 + +## 项目结构 + +``` +errlens/ +├── docs/ # 项目级总体文档 +│ ├── 01_产品需求/ +│ ├── 02_系统架构/ +│ ├── 03_开发规范/ +│ ├── 04_部署运维/ +│ ├── 05_变更日志/ +│ └── 06_开发日志/ +├── tools/ # 开发工具脚本 +├── data/ # 训练数据 +├── projects/ # 子项目 +│ ├── P01_errlens_app/ # 错题本小程序 +│ ├── P02_errlens_training/# 数据训练算法 +│ └── P03_errlens_web/ # Web 管理后台 +├── review/ # 任务交接中心 +├── reports/ # 测试/质量报告 +├── shared/ # 共享资源 +└── .ai/ # AI 协作配置 +``` + +## 开发环境 + +- **操作系统**: Windows / macOS / Linux（跨平台开发） +- **IDE**: Trae CN +- **Node.js**: >= 20.x +- **包管理器**: pnpm >= 9.0.0 +- **Python**: >= 3.10（AI 训练） + +## 同步机制 + +- **代码同步**: Git（远程仓库：GitCode） +- **上下文同步**: `docs/PROJECT_CONTEXT.md` + `docs/06_开发日志/` +- **恢复上下文**: 使用 `resume-context` Skill + +--- + +**最后更新**: 2026-05-23 +**维护者**: 人类负责人 + Dev AI