8.6 KiB
8.6 KiB
纵向功能
状态：开发中 需求版本：0.3.0（已确认、已冻结） 实施方案版本：0.4.0（已确认） 项目骨架：已确认（2026-08-12）
允许的状态：“待开始”“进行中”“待用户查看”“已完成”“已阻塞”。每个切片自动化验证完成后先进入“待用户查看”并暂停；用户明确确认后才标记“已完成”，再开始下一切片。“已完成”仍不等于最终功能验收已经通过。
当前版本功能切片
F-001——应用外壳、首次状态与普通会话
- 状态：已完成（用户于 2026-08-12 审核通过）
- 用户可见结果：首次进入看到“最近”和“项目”空状态及右侧对话引导；点击“新任务”不会创建空会话，发送首条有效消息后普通会话出现，选择历史会话可还原消息并继续输入。
- 页面与交互：Claude Desktop 风格三栏外壳、空状态、对话引导、新任务草稿、普通历史会话、输入校验、加载与保存失败状态。
- 服务或接口：普通会话列表、会话详情、首条消息原子创建会话、已有会话追加用户消息。
- 数据持久化：Conversation 和 Message 实体 JSON、普通会话可重建索引、首条消息失败不暴露空会话。
- 权限与校验：应用内无身份层；普通会话强制
projectId = null；空文本拒绝；客户端不能指定工作区。 - 异常状态：列表加载失败、会话不存在、输入无效、持久化失败、重复提交期间禁用。
- 自动化测试：Core 首条消息和空消息用例、本地文件 Repository、Web DTO/路由及骨架回归共 10 个测试、24 个断言，全部通过。
- 验证命令与结果：
bun run format:check、bun run lint、bun run typecheck、bun run check:file-size、bun run check:architecture、bun test、bun run build全部通过。 - 人工验证步骤：在空数据目录启动生产服务；确认首次引导与空最近列表；点击“新任务”确认列表不新增；发送“这是第一条本地消息”确认会话和消息出现；刷新确认不自动选择；点击历史会话确认消息恢复。
- 人工操作结果：2026-08-12 使用本机浏览器完成上述步骤，首次与点击新任务后的会话数均为 0，发送后为 1，刷新后仍显示引导，选择历史后消息恢复。
- 视觉参考：已只读采集本机 Claude Desktop 新任务页并保存为
docs/visual-reference/claude-new-task.png；F-001 实现截图保存为docs/visual-reference/f001-conversation.png。历史任务采集超时，留待 F-009 补齐。 - 查看阶段修改：根据用户反馈将集中式
global.css拆为全局令牌/reset、应用外壳样式和 conversations 组件共置样式；后续组件继续遵循相同约定。 - 已知限制：本切片不调用模型；用户消息可持久化，但助手回复从 F-002 开始。
F-002——Agent Core 与 DeepSeek 流式回复
- 状态：待用户查看
- 用户可见结果：普通会话可启动 Agent Run，DeepSeek 回复增量显示，完成后的助手消息写入本地会话并可继续聊天；未配置模型密钥时保留用户消息并显示明确错误。
- Agent Core：新增独立于 HTTP 的
AgentRunService、Run/RunEvent 领域对象、ModelPort与RunRepository；模型增量、完成和失败均转为稳定的领域事件。 - DeepSeek 接入：
model-deepseek在适配器内部映射 OpenAI 兼容协议，Core 只依赖自身 Message/ModelEvent 类型；首个模型固定为 DeepSeek。 - 服务与流式协议：新增
POST /api/runs和GET /api/runs/:runId/events；事件按序包含 Run 开始、消息开始/增量/完成及 Run 完成/失败。前端使用基于fetch的 SSE 读取，兼容不提供原生EventSource的 WebView。 - 数据持久化：每次运行保存
run.json和有序events.ndjson；成功后助手消息写入真实本地 Conversation 文件，失败后保存稳定失败终态和错误代码。 - 轮次关联：每条用户和助手消息都必须保存
runId；Run 使用triggerMessageId指向触发本轮运行的用户消息，并复用流式message.started给出的助手messageId，因此运行、触发消息、流式事件和最终消息可以稳定互查。会话写接口只提供查询，新增消息必须通过 Run 用例，避免产生没有 Run 的孤立消息。“第几回合”由用户消息顺序计算，不持久化易失序号；重试链retryOfRunId仍在 F-005 实现。 - 页面与交互：发送消息后进入运行状态、实时拼接助手草稿、完成后读取持久化消息；模型配置缺失时显示“尚未配置 DeepSeek API 密钥”，输入恢复可用且不丢失已提交的用户消息。
- 异常状态：模型密钥缺失保留具体可行动提示；其他模型异常对外收敛为“模型服务暂时不可用”，不泄露供应商原始错误或密钥。
- 自动化测试：Agent Core 成功/失败和轮次关联、文件 Run Repository、HTTP 与 SSE 消息标识一致性、禁止绕过 Run 直接写消息及原有回归共 13 个测试、43 个断言，全部通过。
- 验证命令与结果：
bun run format:check、bun run lint、bun run typecheck、bun run check:file-size、bun run check:architecture、bun test、bun run build全部通过。 - 人工验证步骤：以空临时数据目录和未配置 DeepSeek 密钥启动生产构建；发送“最终失败链路验收”；检查用户消息、错误提示、输入恢复以及 Run 事件文件和失败摘要。
- 人工操作结果：2026-08-12 使用本机应用内浏览器完成；页面准确显示模型密钥缺失提示，输入恢复，用户消息保留；
events.ndjson依次写入run.started、message.started、run.failed，run.json状态为failed。 - 查看阶段修改：根据用户反馈将应用外壳锁定为浏览器可视区高度；页面根节点不再滚动，侧栏仅“最近”区域内部滚动，ConversationPane 仅消息内容区内部滚动，顶部操作、侧栏底部信息和输入组件保持固定。2026-08-13 在 1280×720 视口验证根页面高度与视口一致且无页面滚动，两个内容区均为独立
overflow-y: auto容器。 - 开发环境修正：
bun run dev的后端固定以仓库根目录运行并读取根.env；前端由 Vite 提供 HMR，开发时统一访问127.0.0.1:5173，/api按同一份HOST/PORT配置代理到 Bun watch 后端。生产start仍由 Bun/Hono 提供构建后的web/dist。 - 视觉参考：失败状态验收截图保存为
docs/visual-reference/f002-model-config-error.jpg。 - 已知限制：真实 DeepSeek 成功调用需要用户在运行环境提供自己的密钥；自动化和本次人工验收未使用或读取真实密钥。停止与重试留在 F-005，服务重启后的事件重放加固留在 F-010。
- 主要验收：AC-004、AC-010、AC-014、AC-016。
F-003——项目管理与项目聊天
- 状态：待开始
- 用户可见结果：创建、选择、重命名和删除项目，在项目中维护多个独立会话。
- 主要验收：AC-026 至 AC-033。
F-004——用户交互卡片
- 状态：待开始
- 用户可见结果：Agent 请求单选、多选、确认或意见输入，回答后继续同一 Run。
- 主要验收：AC-034 至 AC-038。
F-005——停止、失败与重试
- 状态：待开始
- 用户可见结果：停止当前生成并从失败状态重试。
- 主要验收：AC-005、AC-010、AC-011。
F-006——附件、文件列表、读取与搜索
- 状态：待开始
- 用户可见结果：附加工作区文件并让 Agent 安全读取和搜索。
- 主要验收：AC-007 至 AC-009、AC-021、AC-022、AC-028、AC-030。
F-007——文件创建与安全修改
- 状态：待开始
- 用户可见结果：Agent 在正确工作区内创建和安全修改文本文件。
- 主要验收：AC-008、AC-009、AC-023、AC-028。
F-008——会话管理与个人设置
- 状态：待开始
- 用户可见结果：重命名和删除会话，查看并修改非敏感设置。
- 主要验收：AC-003、AC-018。
F-009——Claude Desktop 视觉与交互收口
- 状态：待开始
- 用户可见结果：全部已支持状态在目标视口下贴近确认后的参考界面。
- 主要验收：AC-001、AC-002、AC-012、AC-013、AC-020、AC-024。
F-010——恢复、边界与发布前加固
- 状态：待开始
- 用户可见结果：刷新、重启、目录离线和数据损坏等边界均有明确恢复行为。
- 主要验收：AC-006、AC-017 至 AC-019、AC-023、AC-029、AC-030、AC-036、AC-037。
后续版本想法
当前无。新增想法只记录在这里，不扩大 0.3.0 冻结范围。