README.md

AI 文档中心

适用范围：本仓库内的 Claude / Codex / Cursor / Trae 等 AI 编程工具

最后更新时间：2026-06-05

1. 推荐读取顺序

第一步：总入口

• AGENTS.md

第二步：按任务类型选择

• 想快速定位代码：LOCATIONS.md
• 想按功能理解入口：FEATURE_MAP.md
• 想建立整体心智模型：PROJECT_OVERVIEW.md
• 想理解进程边界和数据流：ARCHITECTURE.md
• 想理解 DB 字段和 source of truth：DATA_MODEL.md
• 想看执行规则、偏好治理、踩坑防复犯：GUARDRAILS.md
• 想修改代码前确认流程：WORKFLOWS.md
• 想跑测试或做完成验证：TESTING.md
• 想看桌面端产品说明：../product/README.md
  • 说明：docs/product/* 用于产品现状与设计意图说明，不是 AI 规则权威入口
• 想做竞品分析或产品经理调研：../pm/README.md
  • 说明：docs/pm/* 用于竞品研究、评分矩阵和机会清单，不替代产品现状说明文档
• 想做仓库卫生、忽略规则检查、提交前清理：优先看 WORKFLOWS.md，必要时看 TESTING.md
• 想改同步、设备或服务端：优先看 LOCATIONS.md、FEATURE_MAP.md，必要时再看 ARCHITECTURE.md
• 想续接当前桌面端同步主线、更新同步文档或判断当前阶段进度：先看
  • ../plans/2026-03-25-beta-v1-sync-stage-handoff.md
  • ../architecture/sync-expanded-boundary-beta-v1.md
  • ../architecture/sync-expanded-contract-beta-v1.md
  • ../architecture/sync-expanded-checklist-beta-v1.md
  • ../architecture/may-sync-kickoff-checklist.md
• 想回看 4 月 16 日这轮扩域为什么这样设计、任务最初如何拆解：再补看
  • ../plans/2026-04-16-expanded-desktop-sync-beta-v1-design.md
  • ../plans/2026-04-16-expanded-desktop-sync-beta-v1-implementation-plan.md
  • ../architecture/sync-boundary-beta-v1.md
  • ../architecture/sync-contract-v1.md
• 想看“同步基线完成之后接下来做什么”、AI 助手怎么承接当前产品、当前 AI 已经做到哪里，以及下一阶段为什么这样排：先看
  • ../plans/2026-04-17-post-sync-beta-v1-roadmap.md
  • ../plans/2026-04-17-ai-assistant-v1-design.md
  • ../plans/2026-04-18-ai-assistant-v2-expansion-plan.md
  • ../plans/2026-05-01-ai-assistant-post-cq1-hardening-implementation-plan.md
  • ../plans/2026-04-17-desktop-focus-control-deferred-research.md
• 想盘点“AI 对每日总结各板块当前到底覆盖到哪里”、以及接下来怎么补到全量覆盖：先看
  • ../plans/2026-05-07-ai-daily-summary-coverage-audit.md
  • ../plans/2026-05-07-ai-daily-summary-full-coverage-design.md
  • ../plans/2026-05-07-ai-daily-summary-full-coverage-implementation-plan.md
  • 注意：2026-05-07-ai-daily-summary-coverage-audit.md 是带日期的现状快照，不是长期架构权威
• 想继续加固“AI 解析录入”的稳定性、准确性、字段精细度和确认写入防线：先看
  • ../plans/2026-05-23-ai-parse-entry-hardening-design.md
  • ../plans/2026-05-23-ai-parse-entry-hardening-implementation-plan.md
  • 这两份文档聚焦 parseInput -> shared ai schema/date/validation -> CandidateCards/AIAssistant -> aiAssistant commands 的录入闭环，不替代 provider discovery、source restore 或 draft storage 计划
• 想把 AI 从“解析录入工具”升级为“聊天式全能助手 + 智能自动执行”：先看
  • ../plans/2026-05-23-ai-chat-assistant-automation-design.md
  • ../plans/2026-05-23-ai-chat-assistant-automation-implementation-plan.md
  • 这两份文档聚焦 chat orchestrator -> tool/action registry -> risk policy -> command executor，推荐采用单一对话窗口、澄清追问、自然分析层 + 操作层、低风险自动执行 + undo、中高风险确认、破坏性/设置类动作阻断的长期路线
  • 模型参数、工具能力、能力显示、联网搜索、知识库和 MCP 的产品形态按 Cherry Studio 对齐，但 LifeManager 对本地记录外发增加额外隐私确认
  • 如果本轮要做 AI 对话助手 UI 原型或交给设计师重画，仍优先看这两份文档中的 UI 防重构原则、功能原型布局、AIChatBlock 显示规范、温室书房视觉方向 和 设计/生图主提示词
  • UI 第一版是功能原型：useAIChatController 保持 headless，当前 ChatShell / ChatMessageList / InspectorPanel / ComposerBar 和未来 ChatStream 都只是可替换壳层；未来设计师重构只替换 renderer，不改 orchestrator / risk policy / executor
  • 如果目标是让 AI 从头到尾自动开发，必须从 implementation plan 的 End-to-End Auto-Development Control 和 Task 0: Add shared AI chat scenario fixtures 开始，再按 Package Map / Package Gates / Stop Conditions / Final Manual QA Script 执行，不要直接跳到 UI 或 orchestrator
  • 当前已落地第一版对话助手基线：AIChatSession / AIChatMessage / AIChatBlock / AIActionProposal / AIActionExecution 类型、aiChatRepository 与 aiChat commands、runAIChatTurn、useAIChatController、ChatShell / ChatMessageList / InspectorPanel / ComposerBar / ModelCapabilityBar / ActionProposalCards
  • 当前页面入口已补齐上下文注入：DailySummary / TaskManager / Calendar / HealthRecord 会带 activeDate / suggestedInput / contextSummary / sourceState 进入同一个对话助手，不再只依赖空白解析框
  • 当前安全回归已覆盖 aiActionSafety.test.ts：未知工具、破坏性关键词、批量目标、覆写参数、外部搜索参与写动作、MCP 文件系统和本地记录外发都会先走本地 policy 或确认，不信任模型自报低风险
• 想修正 .figma/24_295 周历、.figma/35_183 笔记/日记、.figma/35_508 每日总结导出长图的高拟真还原问题：先看
  • ../plans/2026-05-25-figma-greenhouse-ui-parity-correction-plan.md
  • 这份文档是本轮 UI 事故后的强制执行计划，重点是 Figma 资产 100% 盘点、运行时资产迁移、Calendar/Notes/JournalLibrary full-bleed scenic page、DailySummaryExport 1600px 内容驱动长图、超长背景不重复不空白、以及截图差异闭环
  • 实施前必须同步对照 GUARDRAILS.md 的 Figma 高拟真 / full-bleed 场景 Gate，不得再把 1:1 还原降级为通用 greenhouse shell
• 想快速判断 AI v2 哪些已经落地、哪些还没做完：优先看
  • ../plans/2026-04-18-ai-assistant-v2-expansion-plan.md 中 2.3 V2 当前完成度快照（2026-04-23）
  • 当前真实状态是：V2-1 ~ V2-7 与 V2-CQ1 已完成；当前详细执行参考切到 ../plans/2026-05-01-ai-assistant-post-cq1-hardening-implementation-plan.md
  • 2026-05-01 这份 post-CQ1 hardening 收尾计划也已执行完成；当前主线不再保留未完成的 AI 构建包
  • Notes 仍不在当前 AI 主线写入内，V2-8 Notes 只读回看评估 已暂缓，不是默认下一包
• 想查看工具适配说明：TOOLS/CLAUDE.md、TOOLS/CODEX.md、TOOLS/CURSOR.md、TOOLS/TRAE.md
• 如果准备收尾本轮工作：除了看 TESTING.md，还要记得在最后额外运行一次 npm run dev

第三步：只在需要时读模块文档

• MODULES/notes-and-journals.md
• MODULES/daily-summary.md
• MODULES/task-and-progress.md
• MODULES/theme-and-settings.md
• MODULES/ai-assistant.md

2. 当前同步文档角色

当前实现状态 / 继续开发入口

下面这些文档共同构成当前同步主线的现实入口：

• ../plans/2026-03-25-beta-v1-sync-stage-handoff.md
  • 描述当前代码已经稳定实现到哪里、还有哪些非阻塞尾项
• ../architecture/sync-expanded-boundary-beta-v1.md
• ../architecture/sync-expanded-contract-beta-v1.md
• ../architecture/sync-expanded-checklist-beta-v1.md
  • 描述当前扩域 Beta v1 的边界、合同、收口证据与域级 Ready 结论
• ../architecture/may-sync-kickoff-checklist.md
  • 描述 5 月继续往生产化 / 移动端 / 账号体系推进时，哪些基础已经到位、哪些仍需保持本地

如果问题是“现在已经做到哪一步”或“从这里继续往下做什么”，优先看这 5 份。

同步完成后的下一阶段路线

下面这些文档负责回答“同步已经完成之后，产品下一步要往哪里走”：

• ../plans/2026-04-17-post-sync-beta-v1-roadmap.md
  • 描述原计划残余、手动闭环、AI 助手 v1 和延后方向的优先顺序
• ../plans/2026-04-17-ai-assistant-v1-design.md
  • 描述 AI 助手当前落地基线、当前代码已经怎样接入、以及 v1 阶段的固定边界
• ../plans/2026-04-18-ai-assistant-v2-expansion-plan.md
  • 描述 AI v2 阶段规划与任务拆解，包括 provider 策略、记忆/回看深化、页面内陪跑与后续延后项
  • 同时包含截至 2026-04-23 的 V2 完成度快照，用于避免把现状误判成“仅 v1”或误判 V2-6 / V2-7 仍未完成
• ../plans/2026-05-01-ai-assistant-post-cq1-hardening-implementation-plan.md
  • 描述 V2-CQ1 完成后的收尾计划与完成证据
  • 当前可作为“本轮 AI 主线已全部完成”的最终收口参考
• ../plans/2026-04-17-desktop-focus-control-deferred-research.md
  • 描述桌面端拦截 / 白名单方向为什么不应误判成当前 4 月主线

当前 AI provider / endpoint 入口规则额外固定为：

• 官方 endpoint 可以继续展示 provider preset 里的预设能力，但 AI 页面运行时只依赖最近一次连接测试里已验证通过的能力
• New API、relay、以及其他 custom OpenAI-compatible endpoint 默认按 yellow 看待，不因为 preset 绿灯就放宽运行时判断
• 网关 / 自定义链路优先看“最近测试 / 受限链路”口径，不把未验证项当成稳定保证
• 只有通过验证矩阵的能力，才作为当前这条链路的稳定能力开放
• multiTurn 本轮仍只用于展示 preset / inferred 信息，不作为 AI 页面运行 gate

如果问题是“同步做完以后接下来优先做什么”或“AI 助手应该怎么承接当前基线”，优先看这 4 份。

原始设计 / 历史拆解参考

下面这些文档仍然重要，但职责已经不同：

• ../plans/2026-04-16-expanded-desktop-sync-beta-v1-design.md
• ../plans/2026-04-16-expanded-desktop-sync-beta-v1-implementation-plan.md
  • 保留为 4 月 16 日这轮扩域的设计依据、任务拆解与回归排查参考
• ../architecture/sync-boundary-beta-v1.md
• ../architecture/sync-contract-v1.md
  • 保留为扩域前的较小 Beta v1 历史基线
• ../plans/2026-04-16-dual-track-release-burndown-design.md
• ../plans/2026-04-16-dual-track-release-burndown-plan.md
  • 保留为发布 / 清债残余来源
• ../plans/2026-03-23-daily-plan-2026-03-24-to-2026-04-13.md
  • 保留为历史执行轨迹

不要把“原始设计 / 历史拆解”文档直接当成“当前未完成 TODO 清单”使用。

3. 文档用途

PROJECT_OVERVIEW.md

建立项目整体印象，适合第一次进入仓库时阅读。

ARCHITECTURE.md

解释 Electron 主进程、预加载、渲染进程、IPC、文件系统、lowdb，以及 apps/server 同步服务端的边界关系。

FEATURE_MAP.md

按功能模块列出：

• 页面入口
• 关键组件
• service / main-process / server 文件
• 典型测试文件
• 搜索关键词

这是最常用的定位文档。

DATA_MODEL.md

描述 DBData、重要业务类型、镜像层与文件系统工作区之间的关系。

TESTING.md

说明测试命令、测试目录分布、回归重点和推荐验证方式。

WORKFLOWS.md

定义当前推荐的任务流转方式、计划维护方式、仓库卫生检查方式和完成前验证规则。

GUARDRAILS.md

定义强制 Gate（UI 响应式/固定浅色基底、命名一致、文档更新、踩坑回填）、统一台账和沟通输出规则。

LOCATIONS.md

按“我要改什么”给出最快跳转路径，也覆盖同步客户端、设备诊断、服务端 auth / devices / sync 与当前同步扩域计划入口。

LEGACY.md

解释历史规则文件、历史 specs、工具私有目录的地位。

4. 阅读原则

• 先定位，再深读
• 先读共享文档，再读工具私有文件
• 只在任务需要时加载对应模块文档
• 如果问题涉及当前同步主线，先区分“当前实现基线”和“下一阶段目标范围”
• 更新计划或索引文档时，要同时检查 README.md、LOCATIONS.md、WORKFLOWS.md 与相关计划是否仍然一致
• 如果本轮已经完成代码、测试、lint、build 等步骤，收尾时仍必须最后再跑一次 npm run dev
• 历史 docs/plans/* 文档只在追溯决策、核对残余来源或理解实现演进时再读

5. 关联入口

• 总入口：../../AGENTS.md
• 工具适配：TOOLS/CLAUDE.md、TOOLS/CODEX.md、TOOLS/CURSOR.md、TOOLS/TRAE.md
• 历史说明：LEGACY.md

6. 近期收口重点（2026-05）

为了让 AI 在“界面细节收口 + AI 解析细节增强”这条线上能直接定位到最新实现，本轮文档索引已统一补充以下入口：

• 每日总结三态日期胶囊（今日/昨日/自选）与首屏后无闪屏切换
• .figma/24_295 / 35_183 / 35_508 温室工作台重构：周历、笔记/日记共享 src/styles/greenhouse.css 背景/石墙贴边/浅色双边框；DailySummaryExport 改为 1600px 内容驱动高度长图，且不改应用内 DailySummary 六卡舞台
• .figma/37_210 专注时钟温室执行台：2026-05-27 已按从干净基线重做计划完成普通温室执行台与全屏沉浸窗；2026-05-28 又针对主卡坐标、右窗圆角、右侧面板嵌入、idle 动态进度、全屏图标按钮、模式菜单和设置 Popover 行为完成回归修正，并补充右侧栏折叠/展开能力。右侧专注主卡与全屏沉浸窗共享同一个氛围背景状态，默认预设顺序为 植物温室（focustimerbackground.png）优先、沙漏背景（Defaultpicture.jpg）第二。全屏沉浸窗必须通过 Electron BrowserWindow.setFullScreen 进入系统级全屏，覆盖 Windows 任务栏，并通过 entering/exiting 过渡态连接普通态与全屏态。2026-06-05 新增桌面端专注悬浮窗：专注会话运行态以主进程 electron/focusSessionRuntime.ts 为唯一 source of truth，主页面和 src/focus-floating/FocusFloatingWindowApp.tsx 都通过 preload focus session IPC 订阅同一 snapshot；悬浮窗由 electron/focusFloatingWindow.ts 创建固定 260x128 置顶透明小窗，入口在专注主卡工具栏，关闭只隐藏不停止计时。执行计划见 ../plans/2026-05-27-focus-timer-greenhouse-rebuild-from-clean-plan.md 与 ../superpowers/plans/2026-06-05-focus-floating-window-implementation-plan.md，防复犯记录见 GUARDRAILS.md 的 FocusTimer 条目，视觉 QA 证据见 ../../artifacts/visual-qa/figma-greenhouse/focus-*.png 与 ../../artifacts/visual-qa/figma-greenhouse/diff-notes.md。后续改动仍必须遵守 FocusTimer 防复犯 Gate，不能复用已回退的失败 focusTimerGarden.css 思路。
• WeekView 上方/全天/下方网格竖线对齐补偿与滚动条行为
• TaskManager 日历月份下拉修复、甘特图左列拖拽改宽
• 全局 transient scrollbar（滚动显隐）与黑色 tooltip/passive popover 样式基线
• 用户选项分组重组（基础设置/时间设置/专注设置/数据设置）
• AI 解析链路（electron/ai/parseInput.ts）与 schema/日期解析规则（src/shared/ai/*）
• AI 解析录入闭环新一轮加固计划（2026-05-23-ai-parse-entry-hardening-*）：稳定性、准确性、字段精细度、候选 UI 校验和确认写入失败防线
• AI 对话助手与智能自动执行计划（2026-05-23-ai-chat-assistant-automation-*）：聊天式入口、历史记录问答、建议、动作卡、低风险自动执行和 undo
• AI 对话助手 UI 雏形与设计交接补充：功能原型采用对话流 + 可收起 Inspector，消息流只放摘要卡，完整候选编辑、动作 before/after、依据、工具记录放右侧详情栏；视觉方向为继承 DailySummary 的“温室书房”，但业务逻辑和消息/action 合同保持 headless
• AI 对话助手自动开发总控：2026-05-23-ai-chat-assistant-automation-implementation-plan.md 已补齐 Task 0 共享场景夹具、包级执行顺序、阶段门禁、停止条件、组件 API 合同、最终手工 QA 和完成清单，后续 AI 可以按该计划从类型/夹具一路执行到最终启动验证
• AI 对话助手第一版实现补充：当前已有聊天会话持久化、清消息/清上下文、模型与工具状态、页面来源上下文、动作卡与安全 policy；视觉和完整 Inspector 详情仍按功能原型迭代，不把现有 AntD 卡片壳当长期设计合同