基于已确认需求文档的功能开发

把用户确认后的需求基线直接转化为可运行代码。开发阶段自行完成代码级方案分析，但不再生成一份中间“开发文档”。

核心边界

• 仅在用户显式调用 $功能开发-基于开发文档 时执行。
• 用户显式调用代表授权按已确认需求开发，不再重复要求用户确认同一方案。
• 开发主输入必须是完善需求文档；同时重新读取其中引用的关键原始需求、截图、原型和 HTML，避免摘要丢失视觉与交互细节。
• 严格按需求范围打通 Renderer、Preload、Main、Core / Agent / Tool、contracts、本地存储和配置的必要链路，不扩大为无关重构。
• 不生成中间开发方案、执行文档或独立迁移脚本文件（除非需求明确要求且用户确认）。
• 涉及真实用户数据目录、密钥或外部系统配置时，只生成操作说明写入最终解决结果文档末尾；禁止直接改写用户机器上的生产数据或密钥。

输入定位

优先读取用户给出的 Markdown 路径。只给文件名或需求主题时，先用 rg --files 在以下位置定位：

docs/bug解决需求文档/需求开发文档/*.md
docs/bug解决需求文档/需求文档/**/*.md
docs/ARCHITECTURE.md
docs/PHASE_STATUS.md
docs/bug解决需求文档/参考文件/**

优先选择名称包含 完善需求文档 且与主题完全匹配的文件。只有存在多个同等匹配文件、无法安全判断时才询问用户。

开发前就绪门槛

完整读取文档后，首先检查末尾“用户确认区”。在通过门槛前不得修改业务代码。

可以直接开发

满足以下条件之一：

• 文档的“可进入开发”已勾选，且所有标为必须确认或阻断的问题已有明确答案。
• 用户在当前对话中明确说明该文档已经确认，并补充了所有阻断答案；把这次明确说明视为最高优先级需求输入。

非阻断细节只有在用户勾选“允许按推荐方案和现有规范合理处理”，或在当前对话中明确授权时，才可按推荐方案推断。

必须停止开发

出现以下任一情况，停止修改并精确告诉用户需要填写的确认编号：

• 文档缺少“用户确认区”或最终确认结论，且当前对话也没有明确确认。
• 影响业务口径、范围、状态流转、协议事件、本地存储语义或核心交互的问题未回答。
• 用户答案彼此矛盾，且不同选择会产生实质性代码差异。
• 关键参考文件无法读取，导致无法满足明确的视觉或交互验收要求。
• 文档仍是“待用户确认”，且当前对话也没有明确授权。

不要把一般技术细节包装成阻断问题。能按项目现有模式安全决定的实现细节，应在获得非阻断推断授权后直接处理。

需求依据优先级

出现冲突时按以下顺序处理：

1. 用户在当前对话中的最新明确指令。
2. 完善需求文档“用户确认区”的答案、纠正和限制。
3. 文档中标为“已明确”的需求、业务规则和验收标准。
4. 原始参考文件对页面视觉、文案和交互的直接证据。
5. 现有系统行为和项目规范，用于未规定部分的兼容处理。
6. 文档中的分析推断或推荐方案，仅在用户已授权时采用。

不能按优先级消解的实质冲突，停止并报告对应需求编号，不得静默选择。

工作流

1. 提取需求执行基线

从完善需求文档提取内部清单，不额外落盘：

• 需求批次、范围、非目标、角色和完整业务流程。
• REQ-xxx 需求编号、业务规则、验收标准和来源编号。
• 页面入口、布局、文案、字段、资源树、对话、编辑器、按钮、交互和各类状态。
• window.deepwrite.* 命令 / 事件、字段、枚举、错误语义和兼容要求。
• 智能体阶段、工具、附件、写回 diff、revision 和本地存储要求。
• 用户确认区中的选择、补充、纠正和限制。
• Catalog、工作目录、模型配置、初始化数据和历史数据影响。

建立内部 REQ-xxx -> 代码落点 -> 验证证据 矩阵，开发和收尾时逐项核销。

2. 回看原始参考文件

根据需求追溯表重新读取会影响实现的素材：

• 截图/原型：逐区核对布局、可见文案、字段、组件状态、弹窗、跳转和空/错/禁用态。
• HTML：读取源码和资源；条件允许时实际渲染，在目标视口检查结构、样式和交互。
• 原始需求：核对被摘要省略的边界、例外、数据口径、协议契约和验收描述。

完善需求文档负责建立语义基线，原始素材仍是还原页面细节的重要证据。禁止只读文档摘要就开始大模块开发。

3. 定位完整现有链路

使用 rg 定位并阅读同领域实现：

• Renderer：apps/desktop/src/renderer/src/components/、composables/、data/、utils/、types/、ui-feedback.ts。
• Preload / Main：apps/desktop/src/preload/、apps/desktop/src/main/。
• Utilities：apps/desktop/src/utilities/（Core Catalog、Agent entry、Tool entry、迁移 / 导入）。
• 契约与运行时：packages/contracts/、packages/shared/、packages/pi-runtime-adapter/。
• 真实链路：Renderer -> Preload Zod -> Main -> Core/Agent/Tool Utility -> 流式事件/原子写入/审阅 diff。
• 文档：docs/ARCHITECTURE.md、docs/PHASE_STATUS.md、同模块历史需求和解决结果，只作辅助证据。

先区分现有能力、可复用点和真实差距，再决定代码落点。优先扩展同领域能力，避免新建与现有实现高度重复的平行链路。

4. 完成代码级分析并直接开发

在内部确定实现顺序，不生成开发文档。一般按依赖关系执行：

1. packages/contracts 契约、字段映射、事件、枚举、常量和兼容策略。
2. Core / Agent / Tool Utility、Main 路由、Preload 白名单与 Zod 校验。
3. Renderer API 编排、流式事件归并、状态管理和错误 / 浮层反馈。
4. 页面、组件、资源树、对话、编辑器、弹窗和静态资源。
5. 工作目录、模型配置、迁移 / 导入或历史数据兼容说明。
6. 类型检查、边界检查、单测、构建、冒烟和回归验证。

按业务模块和 REQ-xxx 分组完成最小完整链路。每组修改后检查字段、方法、事件、状态、错误处理和旧调用兼容性，不留下“前端已做、Utility 待补”或相反的半链路，除非需求明确限制范围。

Renderer 开发要求

• 遵循 Vue 3、TypeScript、Pinia、Naive UI 现有写法，不引入新 UI 框架。
• 只通过 window.deepwrite.* 访问能力；禁止 Renderer 导入 Node、Electron、SQLite 或 Pi Runtime。
• 页面结构、可见文案、内容顺序、字段、按钮和状态以已确认需求及原始参考为准。
• 临时警告、错误、成功提示统一使用浮层反馈；只有必须确认的风险操作才用模态弹窗（见 AGENTS.md）。
• 覆盖加载、空数据、错误、禁用、重复提交、版本冲突、成功刷新 / 返回，以及中文长文本和三栏折叠场景。
• 流式会话必须正确处理 session / run / message 身份、事件先到、重复事件和完成态；写回走待审阅 diff，不得静默覆盖。
• 条件允许时启动本地桌面或 Renderer 预览验证；有视觉参考时对照检查关键区域并记录偏差。

Main / Utility / contracts 开发要求

• 协议与 Zod schema 放入 packages/contracts，并同步 Preload 双向校验。
• Core 是项目文件唯一写入者；新建 / 打开路径必须经 Main 授权的系统目录选择器，不允许 Renderer 提交任意路径。
• 原子写继续使用临时文件 + rename；跨文件更新遵循现有串行提交与失败回滚语义。
• Agent Utility 保持会话并发锁定、流式事件和 Provider / Faux 边界；密钥只在 Main safeStorage 解密后按需注入，不进入 Renderer。
• Tool Utility 有副作用的能力必须经 Policy / Approval。
• 新增配置字段走现有 store / 配置封装，不硬编码密钥。
• 旧 Write Claw 迁移与导入保持显式触发语义，不隐式把旧书籍同步进创作空间。

本地数据、配置与外部说明

涉及用户 userData、工作目录项目结构、迁移步骤或外部配置时，生成完整说明，但只写入最终解决结果文档末尾。

• 写清路径含义、字段、默认值、兼容规则和风险。
• 涉及不可逆数据变更时提供明确步骤和回滚建议。
• 敏感配置只写字段名、用途和配置方式，不写真实密钥。
• 不直接修改用户机器上的生产数据或密钥文件。

验证要求

根据实际改动执行尽可能完整的验证：

• 仓库根优先执行 pnpm typecheck、pnpm lint、pnpm test；涉及构建时 pnpm build。
• 涉及 Renderer 构建产物时补充 pnpm smoke:renderer；涉及 Electron / Utility 健康时尽量 pnpm smoke。
• 大改动可用 pnpm verify（typecheck + lint + test + build）。
• 页面：有截图或 HTML 参考时，核对目标视口下的布局、文案、交互和状态；无法运行时做静态对照并说明限制。
• 联动：验证协议字段、错误语义、流式事件、写回 diff、revision 冲突和历史续接。

验证矩阵至少覆盖：

• 每个 REQ-xxx 都有实现文件和验证证据。
• Renderer / Preload / Main / Utility 命令、事件、字段、枚举和错误语义一致。
• contracts、Utility、Main、Renderer 展示和可选配置口径一致。
• 状态流转、异常、并发和外部 Provider 失败有兜底。
• 新旧入口、旧数据、对话历史和未修改业务流程没有明显回归。

构建失败时先判断是本次改动、仓库既有问题还是环境问题。本次改动导致的错误必须修复；不能完成的验证要保留原始错误摘要并写明影响。

解决结果文档

开发完成后只生成一个结果文档：

docs/bug解决需求文档/需求文档/敏捷需求与bug/{需求批次}-解决结果.md

需求批次优先读取完善需求文档；没有时使用需求文档文件名去掉 -完善需求文档 后缀，并在偏差说明中记录。文件名中的 / \ : * ? " < > | 等非法字符替换为 -。

文档包含：

# {需求批次} — 解决结果

> 来源需求文档：{路径}
> 用户确认状态：已确认
> 开发范围：Renderer / Preload / Main / Core / Agent / Tool / contracts / 本地存储 / 配置

## 开发摘要
## 用户确认项落实情况
## 需求实现追溯矩阵

| 需求编号 | 实现说明 | 修改文件 | 验证证据 | 状态/偏差 |
| --- | --- | --- | --- | --- |

## 修改文件
### Renderer
### Preload / Main / Utilities
### packages 与其他

## 协议、事件与数据结构变更
## 页面还原与交互验证
## 验证结果
## 回归范围
## 偏差、限制与遗留项
## 本地数据、配置或后续处理说明

本章节必须是文档最后一章。有用户数据或外部配置变更时写完整说明并标明“需用户自行执行”；没有则写“无”。

没有涉及的端写“无”。不得额外生成开发文档或执行文档。

反模式

• 未检查用户确认区就直接改代码。
• 把完善需求文档再次改写为开发文档，只输出计划而不开发。
• 只读需求摘要，不回看影响页面还原的截图、原型或 HTML。
• 忽略 REQ-xxx 和验收标准，凭经验实现相似功能。
• 只改 Renderer 展示，不补齐必要的契约、Main 路由、Core 写入或 Agent 事件能力。
• 在 Renderer 中引入 Node / Electron / Pi SDK，破坏进程边界。
• 为匹配参考图而破坏明确业务规则，或为复用旧页面而忽略参考图。
• 私自改写用户生产数据或密钥。
• 把工具或外部 Provider 失败包装成成功，继续发出错误写回动作。
• 用大范围无关重构掩盖需求实现。

最终回复

简明说明：

1. 已按哪份确认后的需求文档完成开发。
2. 完成的 Renderer / Main / Utility / contracts 核心链路及主要文件。
3. REQ-xxx 完成数量、是否存在偏差或遗留项。
4. 运行的类型检查、测试、构建和冒烟验证及结果。
5. 解决结果文档路径。
6. 如有用户数据或外部配置说明，说明已写在结果文档末尾且需用户自行执行。