From 62dbecd5dc4d4e56e4b62d067c338ef7a878c01a Mon Sep 17 00:00:00 2001 From: 7418 <7418@openclaw.ai> Date: Wed, 4 Mar 2026 19:44:12 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=89=A7=E8=A1=8C=E8=AE=A1=E5=88=92?= =?UTF-8?q?=E4=BD=93=E7=B3=BB=20+=20=E6=8A=80=E6=9C=AF=E5=80=BA=E5=8A=A1?= =?UTF-8?q?=E8=BF=BD=E8=B8=AA=20+=20CLAUDE.md=20=E6=89=A7=E8=A1=8C?= =?UTF-8?q?=E8=AE=A1=E5=88=92=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/exec-plans/（新建目录）: - README.md — 执行计划规范、模板、何时需要写执行计划 - active/context-storage-migration.md — 从 research/ 迁移，标注 Phase 0-3 进度状态 （Phase 0 部分完成：sdk_cwd 上线；projects 表和 canUpdateSdkCwd 未实现） - tech-debt-tracker.md — 4 项已知技术债务（ESLint 存量 error、内存态注册表、 固定 50 条 fallback、Phase 0 剩余项） CLAUDE.md: - 新增"执行计划"区块：中大型功能必须先写执行计划再开工 - 文档区块增加 exec-plans/ 索引 ARCHITECTURE.md: - 关键文档索引增加执行计划和技术债务条目 docs/research/README.md: - context-storage-migration-plan 条目增加交叉引用指向执行文档 docs/CLAUDE.md: - 增加 exec-plans/ 目录说明和文档分类规则 目的：确保 AI 后续会话能自动遵循执行计划流程， 读取进度状态而不需要重新口头解释历史。 Co-Authored-By: Claude Opus 4.6 --- ARCHITECTURE.md | 4 +- CLAUDE.md | 9 ++++ docs/CLAUDE.md | 6 ++- docs/exec-plans/README.md | 51 +++++++++++++++++++ .../active/context-storage-migration.md | 35 +++++++++++++ docs/exec-plans/tech-debt-tracker.md | 20 ++++++++ docs/research/README.md | 2 +- 7 files changed, 124 insertions(+), 3 deletions(-) create mode 100644 docs/exec-plans/README.md create mode 100644 docs/exec-plans/active/context-storage-migration.md create mode 100644 docs/exec-plans/tech-debt-tracker.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index b679286..0d5f9f4 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -133,7 +133,9 @@ Schema 定义在 `src/lib/db.ts`，12 张表： | Bridge 系统 | `docs/handover/bridge-system.md` | 架构、适配器、渲染管线 | | Agent 工具集成 | `docs/handover/agent-tooling-todo-bridge.md` | SDK 工具调用、任务桥接 | | SDK 集成调研 | `docs/research/chat-sdk-integration-feasibility.md` | Chat SDK 可行性分析 | -| 上下文存储迁移 | `docs/research/context-storage-migration-plan.md` | 数据库迁移方案 | +| 上下文存储迁移（调研） | `docs/research/context-storage-migration-plan.md` | 数据库迁移详细方案 | +| 上下文存储迁移（执行） | `docs/exec-plans/active/context-storage-migration.md` | 分阶段进度 + 决策日志 | +| 技术债务 | `docs/exec-plans/tech-debt-tracker.md` | 已知技术债务清单 | ## 技术栈 diff --git a/CLAUDE.md b/CLAUDE.md index 009e75e..ad23de3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -52,9 +52,18 @@ CodePilot — Claude Code 的桌面 GUI 客户端，基于 Electron + Next.js。 **构建：** macOS 产出 DMG（arm64 + x64），Windows 产出 NSIS 安装包。`scripts/after-pack.js` 重编译 better-sqlite3 为 Electron ABI。构建前清理 `rm -rf release/ .next/`。 +## 执行计划 + +**中大型功能（跨 3+ 模块、涉及 schema 变更、需分阶段交付）必须先写执行计划再开工。** +- 活跃计划放 `docs/exec-plans/active/`，完成后移至 `completed/` +- 纯调研/可行性分析放 `docs/research/` +- 发现技术债务时记录到 `docs/exec-plans/tech-debt-tracker.md` +- 模板和规范见 `docs/exec-plans/README.md` + ## 文档 - [ARCHITECTURE.md](./ARCHITECTURE.md) — 项目架构、目录结构、数据流、新功能触及点 +- `docs/exec-plans/` — 执行计划（进度状态 + 决策日志 + 技术债务） - `docs/handover/` — 交接文档（架构、数据流、设计决策） - `docs/research/` — 调研文档（技术方案、可行性分析） diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index 43de9d2..6fe8c36 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -2,5 +2,9 @@ - `handover/` — 交接文档（架构、数据流、设计决策） - `research/` — 调研文档（技术方案、可行性分析） +- `exec-plans/` — 执行计划（`active/` 进行中、`completed/` 已完成）+ 技术债务追踪 -**规则：检索子目录前先读对应 README.md；增删文件后更新 README.md 索引。** +**规则：** +- 检索子目录前先读对应 README.md；增删文件后更新 README.md 索引 +- 纯调研放 `research/`；有明确分阶段步骤的放 `exec-plans/active/` +- 执行计划完成后移至 `exec-plans/completed/` diff --git a/docs/exec-plans/README.md b/docs/exec-plans/README.md new file mode 100644 index 0000000..c64f42e --- /dev/null +++ b/docs/exec-plans/README.md @@ -0,0 +1,51 @@ +# Exec Plans / 执行计划 + +中大型功能的执行计划，包含分阶段目标、进度状态和决策日志。 + +**AI 须知：** +- 新建执行计划放在 `active/`，完成后移至 `completed/` +- 纯调研/可行性分析仍放 `docs/research/` +- 修改或新增文件后更新下方索引 +- 检索本目录前先读此文件 + +## 什么时候需要执行计划 + +- 涉及数据库 schema 变更 +- 跨 3 个以上模块的功能 +- 需要分阶段交付的中大型功能 +- 重构或迁移类任务 + +## 执行计划模板 + +```markdown +# {功能名称} + +> 创建时间：YYYY-MM-DD +> 最后更新：YYYY-MM-DD + +## 状态 + +| Phase | 内容 | 状态 | 备注 | +|-------|------|------|------| +| Phase 0 | ... | 📋 待开始 / 🔄 进行中 / ✅ 已完成 / ⏸ 暂缓 | | + +## 决策日志 + +- YYYY-MM-DD: 决策内容及原因 + +## 详细设计 + +（目标、技术方案、拆分步骤、依赖项、验收标准） +``` + +## 索引 + +### Active + +| 文件 | 主题 | 状态 | +|------|------|------| +| active/context-storage-migration.md | 上下文共享与存储迁移 | Phase 0 部分完成，Phase 1-3 待开始 | + +### Completed + +（暂无） diff --git a/docs/exec-plans/active/context-storage-migration.md b/docs/exec-plans/active/context-storage-migration.md new file mode 100644 index 0000000..ba21518 --- /dev/null +++ b/docs/exec-plans/active/context-storage-migration.md @@ -0,0 +1,35 @@ +# 上下文共享与存储迁移 + +> 原始调研：`docs/research/context-storage-migration-plan.md` +> 创建时间：2026-02-26 +> 最后更新：2026-03-04 + +## 状态 + +| Phase | 内容 | 状态 | 备注 | +|-------|------|------|------| +| Phase 0 | `sdk_cwd` 字段 + backfill | ✅ 部分完成 | `sdk_cwd` 已上线；`projects` 表和 `canUpdateSdkCwd` 逻辑未实现 | +| Phase 1 | `message_parts` 结构化消息 | 📋 待开始 | 暂用现有 `content` JSON 数组字段 | +| Phase 2 | `session_runtime_state` 运行态持久化 | 📋 待开始 | 当前依赖内存 Map | +| Phase 3 | 会话压缩摘要 + archive/fork | 📋 待开始 | | + +## 决策日志 + +- **2026-02-26**: 完成调研文档，规划 Phase 0-3 +- **2026-02-xx**: `sdk_cwd` 字段上线，backfill 逻辑确认工作正常（`db.ts` L320-323） +- **2026-03-04**: 迁移为执行文档。Phase 0 的 `projects` 表暂未创建——当前按 `working_directory` 隐式分组已满足需求；`canUpdateSdkCwd` 逻辑暂缺，但实际使用中会话创建时 `sdk_cwd = working_directory` 已固定 + +## Phase 0 剩余项 + +- [ ] 新建 `projects` 表，为历史 session 回填 `project_id` +- [ ] 在 `PATCH /api/chat/sessions/[id]` 中实现 `canUpdateSdkCwd` 逻辑 + +## Phase 1 前置条件 + +- 确认 Bridge 系统是否需要 `message_parts` 的结构化读取 +- 评估当前 `content` JSON 数组方案的局限性 + +## 详细设计 + +完整的目标表结构、SQL 迁移草案、状态机设计、代码落点建议见原始调研文档： +`docs/research/context-storage-migration-plan.md` diff --git a/docs/exec-plans/tech-debt-tracker.md b/docs/exec-plans/tech-debt-tracker.md new file mode 100644 index 0000000..ee93802 --- /dev/null +++ b/docs/exec-plans/tech-debt-tracker.md @@ -0,0 +1,20 @@ +# Tech Debt Tracker / 技术债务追踪 + +已知技术债务清单。每项标注优先级、影响范围和初步解决思路。 + +**AI 须知：发现新的技术债务时添加到此文件；解决后标注完成日期。** + +## 活跃项 + +| # | 描述 | 优先级 | 影响范围 | 发现日期 | +|---|------|--------|----------|----------| +| 1 | ESLint 存量 4 个 error（`MessageItem.tsx` hooks 条件调用、`ChatView` impure render、`GalleryDetail` setState in effect） | 中 | CI lint 步骤需 `continue-on-error` | 2026-03-04 | +| 2 | `conversation-registry` / `permission-registry` 运行态依赖内存 Map，重启后丢失 | 中 | 长时间运行的会话、Bridge 模式 | 2026-02-26 | +| 3 | 消息 fallback 上下文固定最近 50 条，无动态 token 预算截断 | 低 | 长会话上下文质量 | 2026-02-26 | +| 4 | `context-storage-migration` Phase 0 剩余：`projects` 表未建、`canUpdateSdkCwd` 未实现 | 低 | 多项目隔离 | 2026-03-04 | + +## 已解决 + +| # | 描述 | 解决日期 | 解决方式 | +|---|------|----------|----------| +| — | （暂无） | | | diff --git a/docs/research/README.md b/docs/research/README.md index cda2025..373a8b0 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -9,4 +9,4 @@ | 文件 | 主题 | |------|------| | chat-sdk-integration-feasibility.md | Vercel Chat SDK 集成可行性调研 | -| context-storage-migration-plan.md | 上下文共享与存储迁移设计 | +| context-storage-migration-plan.md | 上下文共享与存储迁移设计（详细方案；执行跟踪见 `docs/exec-plans/active/context-storage-migration.md`） |