需求分析与完善需求文档

把原始需求和参考资料整理为 DeepWrite 后续开发的需求基线。重点回答“要做什么、为什么做、做到什么程度、依据是什么、哪些内容尚未确认”，不提前替代开发阶段设计具体代码方案。

核心边界

• 仅在用户显式调用 $需求分析-生成开发文档 时执行。
• 只分析并完善需求文档，不修改 apps/desktop/、packages/、配置或其他业务文件。
• 不生成逐文件、逐类、逐方法的开发步骤，不把技术实现猜测写成需求事实。
• 必须深读用户提供的需求文档、截图、原型、HTML 和其他本地附件；禁止只登记文件路径。
• 必须检索现有实现，用于说明当前能力、可复用行为和需求差距，但不在本阶段决定最终代码落点。
• 不在对话中逐项追问。把无法确认的问题集中写到文档最后的“用户确认区”，交给用户编辑后再进入开发阶段。

事实等级与冲突规则

为关键结论标注来源和确定性：

• 已明确：原始需求、用户文字或参考文件能够直接证明。
• 分析推断：根据现有系统或多份证据推导，尚未经用户确认。
• 待用户确认：存在歧义、冲突、缺失，或不同选择会显著影响范围与实现。

发现素材冲突时，不得自行合并为确定结论。记录冲突双方、影响范围和推荐取值，并放入“用户确认区”。

只把会实质影响业务范围、交互口径、协议契约、智能体行为、本地存储语义、兼容性、性能成本或交付形态的选择交给用户确认。框架内的常规编码方式、组件复用和文件组织由开发阶段按现有项目规范决定，不要把低层技术细节变成用户负担。

工作流

1. 建立素材清单

读取用户提供的需求描述和全部本地文件，建立来源编号 S01、S02……，记录：

• 文件类型、完整路径、是否成功读取、内容摘要。
• 该素材覆盖的业务模块、页面、智能体能力、协议规则或视觉区域。
• 素材之间的版本、重复、冲突和缺失关系。

相对路径按仓库根目录解析。仓库内文件在产物中写相对路径，仓库外本地文件写绝对路径。关键附件无法读取时，明确列为阻断问题，不得声称已完成深度解析。

2. 深度解析需求语义

从原始需求中提取并补全：

• 业务背景、目标用户、角色和使用场景（短篇创作、资料库管理、智能体协作等）。
• 触发入口、前置条件、主流程、分支流程、失败流程和结束状态。
• 功能范围、本次不做内容、上下游依赖和兼容要求。
• 业务规则、状态流转、权限、数据范围、校验和异常提示。
• window.deepwrite.* 命令、事件、字段、默认值、来源和回显规则；流式 Thinking / message / tool / mutation 语义。
• 页面加载态、空态、禁用态、错误态、版本冲突、重复提交和并发边界。
• 可验证的验收标准，避免“优化一下”“保持一致”等不可验收表述。

为每条可独立验收的需求分配稳定编号 REQ-001、REQ-002……，后续模块说明和验收标准都引用该编号。

3. 深度解析页面与参考文件

截图或原型图片

逐张查看并记录：

• 页面层级、入口、区域划分、信息层次和内容顺序。
• 标题、按钮、标签、占位语、提示语等可见文案，尽量保留原文。
• 三栏布局、资源树、对话面板、右侧编辑器、弹窗、Tab 和导航关系。
• 控件的可见、选中、禁用、展开、折叠、加载、空态和错误态。
• 能从证据确认的尺寸、间距、颜色、对齐、滚动和响应式特征。
• 静态图片无法证明的点击、跳转、协议和动态规则，标为推断或待确认。

HTML 参考

同时读取源码和实际渲染结果：

• 分析 DOM、CSS、脚本、静态资源、字段、事件绑定和页面结构。
• 条件允许时在本地渲染，并按目标桌面视口查看页面；仅阅读源码不足以代替视觉检查。
• 区分需要还原的业务交互与仅用于演示的假数据、占位链接、静态动画。
• 记录可复用的文案、组件状态、布局参数和交互线索，不直接复制与当前 Vue / Electron 技术栈冲突的实现。

多份页面参考

建立“页面/区域—来源—需求编号”映射。同一区域出现差异时，列出差异，并在“用户确认区”要求用户选择优先版本。

4. 检索现有系统

使用 rg 从业务名词、组件名、协议命令、事件、字段、智能体阶段、Catalog 类型和配置标识开始检索：

• 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 / Agent / Tool 入口与 Catalog / 迁移逻辑）。
• 契约与运行时：packages/contracts/、packages/shared/、packages/pi-runtime-adapter/。
• 运行链路：Renderer → Preload → Main → Core/Agent/Tool Utility → 流式事件 / 原子写入 / 审阅 diff。
• 文档：docs/ARCHITECTURE.md、docs/PHASE_STATUS.md、docs/bug解决需求文档/、AGENTS.md 及历史解决结果。

在文档中严格区分“现有行为”“新需求”“两者差距”。不要因为现有代码如此实现，就把它自动视为新需求。

5. 完善需求并建立追溯关系

按业务模块而非技术端拆分需求。每个模块至少包含：

• 目标、边界、角色、前置条件和完整业务流程。
• REQ-xxx 需求编号及详细规则。
• 页面、字段、事件、状态、数据范围和异常行为。
• 原始素材证据、现有实现和需求差距。
• 可执行的验收标准。
• 分析推断、冲突和待确认项。

建立 需求编号 -> 原始来源 -> 页面/协议/事件/数据影响 -> 验收标准 的追溯矩阵，避免后续开发只看到概述而遗漏原始证据。

6. 写入完善需求文档

产物固定写入：

docs/bug解决需求文档/需求开发文档/

默认文件名为 {需求主题}-完善需求文档.md。用户指定该目录内的输出文件时按指定路径写入。

• 初次生成时不得覆盖无关同名文档；名称冲突且无法判断是否为同一需求时添加 -v2。
• 用户明确要求继续完善已有文档时，在原文件上更新，并保留用户已填写的确认答案、补充内容和人工勾选状态。
• 一个需求只生成一个主文档；多模块写在同一文档中。

文档结构

使用以下结构，并根据需求复杂度展开细节：

# {需求主题}完善需求文档

> 文档状态：待用户确认 / 已确认
> 需求批次：{原文批次；没有则写待确认}
> 生成依据：{来源编号列表}
> 适用范围：Renderer / Preload / Main / Core / Agent / Tool / contracts / 本地存储 / 配置

## 1. 需求概述

### 1.1 背景与问题
### 1.2 建设目标
### 1.3 用户、角色与场景
### 1.4 范围与非目标

## 2. 原始素材解析

| 来源编号 | 类型 | 本地路径 | 深度解析结论 | 覆盖范围 | 冲突/缺失 |
| --- | --- | --- | --- | --- | --- |

## 3. 现有系统与需求差距

| 模块 | 现有行为及证据 | 新需求 | 差距 | 确定性 |
| --- | --- | --- | --- | --- |

## 4. 完整业务流程

描述入口、前置条件、主流程、分支、异常、结束状态，以及 Renderer、Main、Core、Agent 和外部 Provider 之间的协作。

## 5. 功能需求

### 5.1 {业务模块}

#### REQ-001 {需求名称}

- 需求描述：
- 适用角色：
- 触发入口与前置条件：
- 主流程：
- 分支与异常：
- 业务规则与校验：
- 输入、输出、字段与事件：
- 状态和数据范围：
- 页面与交互要求：
- 智能体、工具或本地存储要求：
- 兼容和历史数据要求：
- 来源依据：S01、S02
- 确定性：已明确 / 分析推断 / 待用户确认
- 验收标准：

## 6. 页面与交互规格

按页面描述入口、布局区域、可见文案、树/对话/编辑器/按钮、操作反馈、弹窗跳转，以及加载/空/错/禁用状态。临时反馈必须约定为浮层提示。

## 7. 协议、事件、数据与配置需求

描述业务需要的数据含义和契约，不写具体 Vue 组件、Utility 函数、SQL 或代码落点。

## 8. 非功能与兼容要求

描述性能、流式响应、防重复、并发、审计、安全、桌面适配、历史数据和旧入口兼容要求。

## 9. 需求追溯与验收矩阵

| 需求编号 | 来源 | 页面/流程 | 协议/事件/数据影响 | 验收标准 | 确定性 |
| --- | --- | --- | --- | --- | --- |

## 10. 风险、假设与缺失信息

列出已识别风险和分析推断，不在这里替代用户作最终决定。

## 11. 用户确认区（请用户填写）

> 本节必须保持为文档最后一节。请在“用户填写”栏补充答案；完成后勾选确认结论，再调用 `$功能开发-基于开发文档`。
> 确认项使用稳定编号：业务问题 `CONF-BIZ-xxx`、技术选择 `CONF-TECH-xxx`、视觉交互 `CONF-UI-xxx`，并明确标注是否阻断开发。

### 11.1 必须确认的业务问题

| 编号 | 问题 | 影响 | 是否阻断 | 可选项/建议 | 用户填写 |
| --- | --- | --- | --- | --- | --- |

### 11.2 技术选型与实现偏好

| 编号 | 待选择内容 | 为什么需要确认 | 是否阻断 | 可选方案与取舍 | 推荐方案 | 用户填写 |
| --- | --- | --- | --- | --- | --- | --- |

### 11.3 视觉、交互与参考文件缺口

| 编号 | 页面/区域 | 缺失或冲突 | 是否阻断 | 建议 | 用户填写 |
| --- | --- | --- | --- | --- | --- |

### 11.4 用户补充与纠正

- [用户填写]

### 11.5 最终确认结论

- [ ] 我已确认本文档中的需求范围、业务规则、页面交互和验收标准，可进入开发。
- [ ] 我允许开发阶段对不影响业务口径的非阻断细节，按本文档推荐方案和项目现有规范合理处理。
- 确认人：[用户填写]
- 确认日期：[用户填写]
- 其他限制：[用户填写]

即使没有待确认问题，也必须保留用户确认区，写明“未发现阻断问题”，并由用户勾选最终确认。

质量门槛

完成前逐项检查：

• 所有用户提供的本地文件均已读取；无法读取的文件已明确标记。
• 每张截图/原型和每个 HTML 都有内容级解析，不只是路径列表。
• 关键需求都有 REQ-xxx 编号、来源、确定性和验收标准。
• 现有行为、目标需求、分析推断和用户待确认内容已明确区分。
• 页面关键文案、字段、状态、交互和异常场景已覆盖。
• Renderer、Main、Core、Agent、协议事件、本地存储口径已对齐到需求层。
• 文档最后一节是完整的“用户确认区”，其后没有其他章节。
• 未修改业务代码，未生成代码级开发方案。

最终回复

简明告知用户：

• 完善需求文档的完整路径和包含的业务模块。
• 已深度解析的需求文件、截图、HTML 或原型数量。
• 待确认问题数量及是否存在阻断项。
• 请用户直接填写文档末尾“用户确认区”，确认后再调用 $功能开发-基于开发文档。
• 本阶段未修改业务代码。