139 lines
20 KiB
Markdown
139 lines
20 KiB
Markdown
# 纵向功能
|
||
|
||
状态：全部切片已完成，等待最终统一人工审核
|
||
需求版本：0.3.0（已确认、已冻结）
|
||
实施方案版本：0.4.0（已确认）
|
||
项目骨架：已确认（2026-08-12）
|
||
|
||
允许的状态：“待开始”“进行中”“待用户查看”“已完成”“已阻塞”。用户已于 2026-08-14 授权 F-004 及后续切片由 Agent 验证通过后直接标记“已完成”并提交，最后统一人工审核。“已完成”仍不等于最终功能验收已经通过。
|
||
|
||
## 当前版本功能切片
|
||
|
||
### 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 流式回复
|
||
|
||
- 状态：已完成（用户于 2026-08-13 审核通过）
|
||
- 用户可见结果：普通会话可启动 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——项目管理与项目聊天
|
||
|
||
- 状态：已完成（用户于 2026-08-14 审核通过）
|
||
- 用户可见结果：创建、选择、重命名和删除项目，在项目中维护多个独立会话。
|
||
- 主要验收：AC-026 至 AC-033。
|
||
- 自动化验证结果：2026-08-13 通过全仓类型检查、16 项测试、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查。
|
||
- 人工操作结果：2026-08-13 使用本机应用内浏览器完成；验证了真实目录创建项目、首条消息才创建项目会话、项目历史恢复并继续聊天、重命名、删除确认信息，以及删除后本地工作目录仍然存在。
|
||
|
||
### F-004——用户交互卡片
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：Agent 请求单选、多选、确认或意见输入，回答后继续同一 Run。
|
||
- 主要验收：AC-034 至 AC-038。
|
||
- 实现结果：DeepSeek 工具调用被转换为独立 `interaction.*` 领域事件；交互请求按 Run 持久化，回答后使用原 `runId` 和 `toolCallId` 继续模型请求，不创建新 Run 或用户消息。支持单选、多选、确认和自由文本，包含选项数量、选择上下限、未知选项、重复回答及 8 KiB 文本校验。
|
||
- 页面结果：消息时间线按交互类型显示四类 VanJS 卡片；等待回答时禁用普通输入；回答后保留只读问题和答案；等待中的任务可从卡片停止并显示取消状态。
|
||
- 自动化验证结果：2026-08-14 通过全仓类型检查、21 项测试和 75 个断言、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查；Fake Model 验证暂停和恢复前后 Run 标识不变、事件序列连续。
|
||
- 人工操作结果：2026-08-14 使用隔离数据目录和本机应用内浏览器验证四类卡片、提交条件、只读答案、取消状态及刷新恢复；页面控制台无错误。
|
||
|
||
### F-005——停止、失败与重试
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：停止当前生成并从失败状态重试。
|
||
- 主要验收：AC-005、AC-010、AC-011。
|
||
- 实现结果：Agent Core 持有每个活动 Run 的取消控制器，停止操作真正中断 ModelPort；停止前已生成内容持久化，Run 和事件日志进入 `cancelled` 终态。失败或取消后创建带 `retryOfRunId` 的新 Run，复用原触发消息且不重复写入用户消息。Repository 与串行启动锁共同执行全局单活动 Run 检查，第二个任务返回 `RUN_ALREADY_ACTIVE`。
|
||
- 失败处理：DeepSeek 请求增加与环境配置一致的模型超时并映射 `MODEL_TIMEOUT`；Bun 服务空闲超时与模型超时对齐；流式连接提前中断时前端结束加载并主动取消仍在运行的后台任务。
|
||
- 页面结果：生成时发送按钮切换为“停止生成”；失败和取消显示明确状态及“重试”按钮；API 启动失败时保留输入草稿。
|
||
- 自动化验证结果：2026-08-14 通过全仓类型检查、24 项测试和 84 个断言、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查。
|
||
- 人工操作结果：2026-08-14 使用隔离慢速 Fake Model 验证停止按钮、部分回复保留、取消终态和重试成功；并通过两个连续 HTTP 请求确认活动任务期间第二个请求稳定返回 `409 RUN_ALREADY_ACTIVE`；页面控制台无错误。
|
||
|
||
### F-006——附件、文件列表、读取与搜索
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：附加工作区文件并让 Agent 安全读取和搜索。
|
||
- 主要验收：AC-007 至 AC-009、AC-021、AC-022、AC-028、AC-030。
|
||
- 实现结果：消息新增必填附件元数据，支持一次选择最多 10 个工作区文件和仅附件消息；普通草稿、项目草稿与已有会话均由服务端解析可信工作区，浏览器和模型不能传入根目录。文件层支持目录浏览、文件名与 UTF-8 内容搜索、2 MiB 内文本读取、二进制识别，并拒绝绝对路径、`..`、空字节和符号链接逃逸。
|
||
- Agent 工具：新增 `list_directory`、`search_files` 和 `read_text_file`；普通文件工具使用独立 `tool.started`、`tool.completed`、`tool.failed` 事件，结果交回同一次模型请求链继续生成，与用户交互事件保持区分。
|
||
- 页面结果：VanJS 输入区提供工作区文件选择器、目录导航、搜索、最多 10 项选择、待发送附件和历史附件状态；只有附件时发送按钮可用。附件在发送后消失或不可访问时，历史会话仍可打开并明确显示“不可用”；项目目录离线时附件入口禁用且不会回退到默认工作区。
|
||
- 自动化验证结果：2026-08-14 通过全仓类型检查、29 项测试和 99 个断言、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查；覆盖读取/搜索、二进制拒绝、绝对路径、父目录跳转、符号链接逃逸、仅附件消息和文件工具续跑。
|
||
- 人工操作结果：2026-08-14 使用隔离工作区、隔离数据目录和未配置模型密钥的本机应用内浏览器完成；验证选择 `README.md`、仅附件发送、会话标题与附件历史恢复；删除测试文件后刷新，历史附件显示“不可用”，隔离页面控制台无错误。
|
||
|
||
### F-007——文件创建与安全修改
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：Agent 在正确工作区内创建和安全修改文本文件。
|
||
- 主要验收：AC-008、AC-009、AC-023、AC-028。
|
||
- 实现结果：新增 `create_text_file` 和 `apply_text_patch` 两个模型工具。新建文件使用排他写入，目标已存在时不会覆盖；修改必须携带最近一次 `read_text_file` 返回的 SHA-256 内容哈希，并使用 1 至 50 项精确文本替换。待替换文本不存在、默认模式下出现多次、文件已被外部改动或修改没有产生变化时均明确失败。
|
||
- 写入安全：新文件先解析真实父目录并再次检查工作区边界，阻止通过目录符号链接写到外部；已有文件修改在同目录写临时文件、保留原权限并原子替换，替换前再次核对内容哈希。继续限制 UTF-8 文本和 2 MiB 上限，不增加删除、移动、批量覆盖或 Shell 能力。
|
||
- 页面结果：创建和修改与其他文件工具共用已有工具状态卡片，分别显示“创建文件”和“修改文件”；成功与失败仍使用 `tool.completed` 和 `tool.failed`，不会混入主要回复消息或用户交互卡片。
|
||
- 自动化验证结果：2026-08-14 通过全仓类型检查、31 项测试和 109 个断言、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查；覆盖排他创建、哈希修改、过期哈希、缺失替换、歧义替换、路径穿越及目录符号链接逃逸。
|
||
|
||
### F-008——会话管理与个人设置
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：重命名和删除会话，查看并修改非敏感设置。
|
||
- 主要验收：AC-003、AC-018。
|
||
- 会话管理：普通会话和项目会话在选中后提供重命名与删除入口；重命名立即更新会话文件、侧栏和当前标题。删除前展示会话名称，并明确说明删除消息、附件元数据和运行记录但不修改工作区文件；有活动任务时拒绝删除，成功后普通或项目会话列表同步移除。
|
||
- 个人设置：侧栏底部进入设置页，可查看和修改普通对话默认工作区及文件工具详情偏好；新工作区经服务端 `realpath` 和读写目录校验后保存到独立 `settings.json`，后续普通对话即时使用新目录。页面只显示 DeepSeek 模型名、是否已配置和应用版本，不返回或渲染模型密钥。
|
||
- 自动化验证结果：2026-08-14 通过全仓类型检查、35 项测试和 121 个断言、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查；覆盖会话重命名/删除接口、设置持久化、工作区规范化以及响应中不存在密钥字段。
|
||
- 人工操作结果：2026-08-14 使用隔离数据目录和本机应用内浏览器完成；验证创建失败终态会话后重命名、刷新恢复名称、删除确认与列表清空；将默认工作区修改为 `/tmp` 并关闭工具详情后刷新，页面恢复规范化路径 `/private/tmp` 和关闭状态；隔离页面控制台无错误。
|
||
|
||
### F-009——Claude Desktop 视觉与交互收口
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：全部已支持状态在目标视口下贴近确认后的参考界面。
|
||
- 主要验收：AC-001、AC-002、AC-012、AC-013、AC-020、AC-024。
|
||
- 消息排版：新增不依赖大型 UI 库的安全 Markdown 组件，支持段落、无序/有序列表、引用、链接、行内代码、粗体、表格和带语言标识的代码块；代码块提供复制按钮和复制结果反馈。解析过程直接创建 DOM 节点，不把消息内容作为 HTML 注入。
|
||
- 滚动行为：打开长会话和用户停留在底部时自动滚动到最新内容；用户主动向上滚动超过 80 px 后，新消息和状态更新不再抢回底部。页面根节点继续锁定视口高度，侧栏和消息内容区分别独立滚动，顶部区域、侧栏底部和输入区不跟随消息滚动。
|
||
- 视觉收口：沿用已确认的 Claude Desktop 深色三栏结构，补齐 Markdown 表格、引用、代码块、会话操作、设置页与文件选择器样式；没有增加未实现的 Claude 小组件或无效入口。新增组件继续使用功能共置样式，TypeScript 文件均不超过 400 行。
|
||
- 自动化验证结果：2026-08-14 通过全仓类型检查、36 项测试和 123 个断言、生产构建、代码检查、格式检查、文件规模检查与架构依赖检查；智能滚动阈值有独立测试。
|
||
- 人工操作结果：2026-08-14 使用隔离数据目录和本机应用内浏览器验证列表、引用、表格、TypeScript 代码块及复制反馈；长消息新增后滚动位置到达底部（`1812/1812`），主动上滚到 `212` 后再新增消息仍保持 `212`；页面根节点和 `body` 均无滚动，侧栏与内容区为独立 `overflow-y: auto`，隔离页面控制台无错误。应用内浏览器固定为 1280×720，1440×900 的结构约束由同一桌面断点和既有参考截图覆盖。
|
||
|
||
### F-010——恢复、边界与发布前加固
|
||
|
||
- 状态：已完成（Agent 于 2026-08-14 验证通过，等待最终统一人工审核）
|
||
- 用户可见结果：刷新、重启、目录离线和数据损坏等边界均有明确恢复行为。
|
||
- 主要验收：AC-006、AC-017 至 AC-019、AC-023、AC-029、AC-030、AC-036、AC-037。
|
||
- 运行恢复：服务启动时检查遗留活动任务；执行中的 Run 转为带 `RUN_INTERRUPTED` 的可重试失败终态并补写持久化事件，等待用户回答且交互请求仍完整的 Run 保持等待状态。SSE 注册表会从本地事件日志恢复并按序去重，因此重连后可以重放已有事件。
|
||
- 数据容错：会话、项目、运行和交互列表会隔离单个损坏的 JSON 记录；Run 事件日志允许忽略因意外断电产生的不完整末行，但中间损坏仍明确报错，避免悄悄跳过有效日志。设置加载失败不会阻断会话和项目历史进入页面。
|
||
- 发布边界：所有 API 请求体限制为 5 MiB，超限返回稳定的 `REQUEST_TOO_LARGE`；新增敏感信息扫描，检查源代码和文档中的常见密钥、私钥及前端模型密钥引用。应用继续不包含身份认证端点，认证由部署时的反向代理负责。
|
||
- 自动化验证结果：2026-08-14 通过全仓格式、代码、类型、文件规模、架构依赖和敏感信息检查，39 项测试和 134 个断言全部通过，Web 与 Web Server 生产构建成功。新增覆盖服务中断恢复、等待交互保留、事件重放去重、损坏记录隔离、不完整 NDJSON 末行及 5 MiB 请求边界。
|
||
- 人工操作结果：2026-08-14 使用 F-009 的隔离数据目录重启实际生产构建；首次页面恢复“Markdown 验收”最近会话，选择后完整恢复列表、引用、表格、代码块、长消息和失败重试状态，证明发布构建可从真实本地文件重新构建页面状态。
|
||
|
||
## 最终统一人工审核
|
||
|
||
F-001 至 F-010 均已完成开发和 Agent 验证，当前进入功能验收阶段。建议按切片编号依次审核；只有用户明确回复“功能验收通过”后，阶段门才会标记为已确认。
|
||
|
||
## 后续版本想法
|
||
|
||
当前无。新增想法只记录在这里，不扩大 0.3.0 冻结范围。
|