docs: 执行计划体系 + 技术债务追踪 + CLAUDE.md 执行计划规则

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 <noreply@anthropic.com>
2026-03-04 19:44:12 +08:00
1 parent e0c38af4fa
commit 62dbecd5dc
@@ -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/`
@@ -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
+
+（暂无）
@@ -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`
@@ -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 |
+
+## 已解决
+
+| # | 描述 | 解决日期 | 解决方式 |
+|---|------|----------|----------|
+| — | （暂无） | | |
@@ -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`） |