101 lines
8.6 KiB
Markdown
101 lines
8.6 KiB
Markdown
# 纵向功能
|
||
|
||
状态：开发中
|
||
需求版本：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 冻结范围。
|