125 lines
16 KiB
Markdown
125 lines
16 KiB
Markdown
# 路线图与版本自省
|
||
|
||
> 每个版本完成后在此追加"自省"：缺什么、哪里不好、下一版怎么补。
|
||
|
||
## 版本计划
|
||
|
||
| 版本 | 主题 | 内容 |
|
||
|---|---|---|
|
||
| v0.1.0 | 骨架 + 聊天链路 | monorepo、electron-vite 三进程、pi SDK 嵌主进程、IPC 事件转发、聊天 UI（流式文本 + thinking 折叠）、停止/排队基础 |
|
||
| v0.2.0 | 会话管理 | 会话列表/新建/恢复/重命名/删除、分支（New session / Edit from here）、运行状态与用量展示 |
|
||
| v0.3.0 | 模型与设置 | 模型选择、Provider/API key 管理（写入 ~/.pi auth）、系统提示词自定义、连通性测试 |
|
||
| v0.4.0 | 工具与审批 | 工具调用卡片（参数/结果折叠展示）、tool_call 拦截 → Approval Card、defineTool 业务工具骨架（本地可跑的演示工具） |
|
||
| v0.5.0 | 打磨 | 深浅主题、GSAP 动效细节、快捷键、错误态/空态、队列可视化、自动滚动策略 |
|
||
| v0.8.0 | 动态插件系统（M0–M3） | 两层能力模型（内置组件级/外置 iframe）、pi 原生契约聚合 extension、@aso/plugin-sdk、plugin://peer:// 协议、视图切换+聊天保活+徽标、侧栏/面板/胶囊/深链槽位、浏览器面板插件化、插件重载 |
|
||
| v0.9.0 | 插件一等公民 + 可观测 | entry.renderer 宿主内 React 组件（Blob 装载+单实例 React）、.pi/extensions 一等插件源（build 开关门控）、声明式设置体系（13 控件+一级导航入口）、统一日志系统（滚动文件/api.log/IPC 追踪/渲染层错误归档）、渐进式教程 docs/plugins/ + DESIGN.md + plugin-template、性能/样式标准与检验器（激活 10s/装载 8s 护栏、@aso/plugin-sdk/ui 组件库+三态、withTimeout/withRetry、plugin:check）、状态胶囊详情面板（ZCode Git 工具式：头部+分组+行尾彩色数值，B3 浮动态并入顶栏胶囊）、图标统一 lucide 白名单、面板平铺标签条 |
|
||
| 未来 | | 插件管理与 zip 导入（M4）、ed25519 签名在线更新（M5）、外置插件模板与开发工作流（M6）、pi 原生扩展目录管控（M7）、B3/B4/B5 槽位、electron-builder 打包与自动更新、i18n（中/英）、sqlite 持久化与迁移、本地备份恢复、热点词/生成/模板业务插件、手动模式编排 UI、RPC 子进程隔离模式 |
|
||
|
||
---
|
||
|
||
## v0.8.0 — 动态插件系统（M0–M3）
|
||
|
||
**交付**：
|
||
- 仓库根 pnpm workspace（apps/* + packages/*）+ `@aso/plugin-sdk`（类型 + definePlugin + 页面桥 client/hooks；源码形态被 workspace 消费，无构建步骤）
|
||
- 主进程 `PluginHost`：内置（代码注册）+ 外置（`userData/plugins/`，manifest 校验/契约版本检查/main.mjs 动态 import）双目录合并（高 semver 胜、外置遮蔽组件级内置需 replacesNative）；聚合 InlineExtension 扇出真实 pi `ExtensionAPI`；内联 UI（状态胶囊/工具栏按钮）主进程单一事实源 + 事件广播；插件 KV 存储；`plugin://`（路径穿越防护）/`peer://`（tokens.css）特权协议；CSP 加 `frame-src plugin:`；插件启停/重载联动 runtime 重建
|
||
- 渲染层：插件列表/内联 UI hooks；`PluginPageFrame`（iframe + 桥宿主侧：origin+source 双校验、白名单 invoke、主题下发、深链参数、热重载换 src）；`PluginErrorBoundary`；`PluginStatusCapsules`（TitleBar 槽，两视图可见）；App 视图切换（activeView{view,params}、聊天列 display:none 保活、Ctrl+N 全局/Ctrl+K,Ctrl+, 仅聊天、插件禁用自动回落）；SidebarNav 插件入口 + 会话区头代理活动徽标（待审批>出错>流式）；SidePanel 零改动承载插件 tab
|
||
- 浏览器面板 → 内置插件：browserTools 迁 `pi.registerTool`（customTools 摘除）、面板 tab 按启用态门控、状态胶囊示范（"浏览器 N 页"）
|
||
- 验证：typecheck/build 通过（含 SDK 打包、tokens.css 构建期拷贝）；dev 启动截图核验（聊天布局无回归、浏览器面板正常、无报错）
|
||
- 关键事实澄清：pi resource-loader **默认自动加载** `~/.pi/agent/extensions`——M7（原生目录管控）从"建设加载"降为"开关+可见性"
|
||
|
||
**自省**（v0.8.0 → 指导 M4+）：
|
||
1. **外置插件尚未强制签名**——当前 `userData/plugins/` 直接装载（代码里已留 TODO）；M5 验签落地前不对外分发任何外置插件。
|
||
2. **B3/B4/B5 槽位数据已通、渲染未接**——状态胶囊已在 TitleBar 生效；Composer 工具行按钮、聊天流围栏块元组件（data-table 等）、聊天区浮动胶囊排 M4 同批或下版本。
|
||
3. **切换回聊天未自动聚焦输入框**——保活后焦点丢失，需 Composer 暴露 focus 入口（data 属性 + App effect）。
|
||
4. **插件管理 UI 仍占位**——SettingsModal"插件"tab 转正（列表/启停/重载/导入）排 M4。
|
||
5. **TS7（typescript 7 native）增量缓存坑**——改 `declare global` 后 typecheck 可能读到旧程序，删 `out/tsconfig.{node,web}/` 下 tsbuildinfo 即恢复。
|
||
6. **workspace 迁移副作用**——根 workspace 化后 electron postinstall 偶发不跑（"Electron uninstall"），手动 `node node_modules/.pnpm/electron@*/node_modules/electron/install.js` 修复；新克隆/重装后注意。
|
||
|
||
---
|
||
|
||
## v0.2.0 — 会话管理
|
||
|
||
**交付**：
|
||
- 主进程 `AgentService` 升级为 `AgentSessionRuntime` 模式：`newSession` / `switchSession`（自动重挂事件订阅 + 通知渲染层）、factory 按 cwd 复用/重建 services
|
||
- 会话列表 `SessionManager.list`（名称/首消息/条数/修改时间）、重命名（`setSessionName`）、删除（`shell.trashItem` 移入回收站，可恢复）
|
||
- 渲染层：侧栏真实会话列表（选中高亮 + 绿条指示、悬停操作：重命名/删除）、重命名对话框、删除确认、历史消息与工具状态重建（`session_switched` 事件）
|
||
- 启动自动 `continueRecent` 恢复最近会话
|
||
- 验证：typecheck/build 通过；Node 冒烟（list/new/switch 恢复 2 条历史/rename 可见于 list）；应用截图核验（列表选中态、历史气泡渲染正确）
|
||
|
||
**自省**（v0.2.0 → 指导 v0.3+）：
|
||
1. **pi 的落盘约定**——只有出现 assistant 消息会话文件才真正写入（避免空会话残留）。由此：纯手动模式（不调 LLM）产生的会话不会自动出现在列表里，将来 D2 双模式统一时要在手动路径补 assistant 侧记录（`sendCustomMessage` 或直接 appendMessage）。
|
||
2. **重命名仅限当前会话**——`setSessionName` 作用于活跃会话；列表项上的重命名按钮对非活跃会话实际是"切过去再改名"或干脆隐藏，当前实现有误导。v0.3 修正：非活跃项隐藏重命名按钮（或先 open 再 rename）。
|
||
3. **会话列表不实时**——列表在加载和切换后刷新，别的窗口/CLI 新建的会话不会自动出现；缺一个"刷新"入口或文件监听。排 v0.5。
|
||
4. **cwd 固定为 home**——会话按 cwd 分组，工作区切换（店铺 A/店铺 B 各自会话域）还没设计；等 `packages/agent` 业务域明确后一起做。
|
||
5. **键盘链路仍未人工实测**（computer-use 无法激活窗口）；冒烟+截图继续兜底，但 Enter 发送/Shift+Enter 换行/重命名快捷键需要用户实机过一遍。
|
||
|
||
## v0.3.0 — 模型与设置
|
||
|
||
**交付**：
|
||
- 模型目录：`ModelRuntime.getProviders/getModels/listCredentials` → 41 个 provider 全量分组展示（含 deepseek/anthropic/openai/google/zai 等），行内显示 推理/上下文窗口
|
||
- API key 管理：`modelRuntime.login(providerId,'api_key',{prompt})` 持久化写入 `~/.pi/agent/auth.json`（与 pi CLI 完全共享），支持更换/移除（logout）
|
||
- 模型切换：`session.setModel(model,{persist:true})`，选中态高亮 + `state` 事件同步侧栏
|
||
- 系统提示词：应用设置存 `userData/aso-settings.json`，经 `resourceLoaderOptions.systemPrompt` 注入；保存后运行时整体重建（dispose + continueRecent 重挂当前最近会话，历史保留）
|
||
- 设置弹窗：双标签页（模型与密钥 / 系统提示词）、搜索过滤、密钥输入（password 型）、操作通知条；侧栏齿轮入口
|
||
- 验证：typecheck/build；Node 冒烟（login→auth.json 写入→setModel→logout 移除、systemPrompt 生效）；应用截图 + a11y 树核验弹窗完整渲染与交互（齿轮点击成功打开）
|
||
|
||
**自省**（v0.3.0 → 指导 v0.4+）：
|
||
1. **模型列表太长**——41 个 provider 全量平铺，滚动找模型体验一般；虽然已按"已配置凭据优先"排序，但缺少"仅显示已配置"开关和常用置顶。排 v0.5。
|
||
2. **OAuth 流程未接**——`login(providerId,'oauth')` 需要 auth_url/device_code 的 UI 交互（AuthInteraction.notify），当前只支持 API key。GitHub Copilot 等 OAuth-only provider 暂时用不了。排 v0.4 或 v0.5（优先级低于业务工具）。
|
||
3. **密钥无连通性测试**——保存假 key 也能存上，要到真正发消息才 401。应加"测试连接"（发一次极小请求）。排 v0.5。
|
||
4. **系统提示词重建成本**——保存提示词会整体重建 runtime（重新加载扩展/skills），秒级耗时且丢当前流式状态；保存前应检查是否有进行中的回复。当前实现未拦截，记录待修。
|
||
5. **运行时重建后模型选择**——重建走 continueRecent，会话内保存的模型跟随会话；但全局默认模型（settings 持久化）与 UI 状态的同步依赖 `state` 事件，尚未覆盖"重建后 model fallback"提示（modelFallbackMessage 丢弃未展示）。排 v0.5。
|
||
|
||
## v0.4.0 — 工具与审批
|
||
|
||
**交付**：
|
||
- 业务工具骨架（`src/main/tools/demo-tools.ts`）：`hotword_lookup`（演示数据源）、`price_check`（核价演示，敏感操作）；接口形态对齐架构 D2（后端就绪后换实现不动接口）
|
||
- 审批链路：`ApprovalService` + `tool_call` 拦截 extension（`TOOLS_REQUIRING_APPROVAL` 名单：price_check/bash/write/edit）→ IPC `approval_request` → 渲染层 Approval Card（beautifului 风格，GSAP back.out 入场）→ `approval:resolve` 回传；120s 超时自动拒绝；窗口关闭拒绝全部未决
|
||
- 工具经 `customTools` 注入（与内置 read/bash/… 并存注册），promptSnippet/promptGuidelines 进系统提示词
|
||
- 验证：typecheck/build；Node 冒烟（customTools 注册、**手动直调 execute 成功 = D2 双模式共用能力实证**、拦截契约三名单场景：放行/拒绝 block/批准放行）；应用带扩展正常启动
|
||
|
||
**自省**（v0.4.0 → 指导 v0.5+）：
|
||
1. **端到端审批未实拍**——LLM 生成 tool_call → 审批卡弹出 → 拒绝后 agent 收到 block 结果的完整链路仍缺真实凭据验证（本机无 key）。拦截契约已单元级验证，剩余风险在事件时序（extension 在 AgentSession 的 tool hooks 上触发，理论覆盖所有工具）。
|
||
2. **审批名单硬编码**——应做成设置项（每个工具可配置 always/ask/never）；且业务工具多了以后要按"工具元数据声明敏感级别"，而非集中名单。排 v0.5。
|
||
3. **手动模式 UI 缺失**——D2 的另一半（UI 按钮直调工具）后端就绪前只能停留在代码层（smoke 已证 execute 可直调）。等 packages/agent 建立后做"手动模式面板"。
|
||
4. **工具卡片在审批等待期间无"等待审批"状态**——ToolCard 显示 running，但用户看不出是在等他确认；应联动 approval 状态显示"等待审批中"。排 v0.5。
|
||
5. **审批卡无倒计时**——120s 超时静默拒绝，卡片上应显示剩余时间。排 v0.5。
|
||
|
||
## v0.5.0 — 打磨
|
||
|
||
**交付**（消化 v0.1–v0.4 自省清单）：
|
||
- Markdown 渲染增强：标题（#~### 映射 h3~h5）、无序/有序列表、引用块、链接（外链转系统浏览器）、行内 code/加粗；fenced code 不变
|
||
- 审批体验闭环：ToolCard 新增"等待审批"占位态（tool_call 已产生、审批未决时 amber 呼吸点 + 参数预览）；Approval Card 增加 mm:ss 倒计时（≤15s 变红）
|
||
- 会话列表：手动刷新按钮（补齐外部进程/CLI 新建会话不可见的缺口）；重命名按钮仅在当前活跃会话显示（修正 v0.2 的误导交互）
|
||
- 设置：模型列表"仅显示已配置"开关；保存系统提示词前检查流式状态（回复中禁止重建运行时并给出提示）
|
||
- 快捷键：Ctrl+N 新会话、Ctrl+, 打开设置、Esc 关闭弹窗
|
||
- 版本号提升 0.5.0（侧栏状态区展示）
|
||
- 验证：typecheck/build；应用截图核验（刷新按钮/版本号/消息渲染/无异常）
|
||
|
||
**自省**（v0.5.0 → 后续）：
|
||
1. **浅色主题未做**——深色已统一，浅色需要全量 CSS 变量化改造（所有 zinc-* 硬编码），工作量半人日以上，单独排 v0.6。
|
||
2. **OAuth 登录流仍未接**（GitHub Copilot 等 OAuth-only provider 用不了），需要 auth_url/device_code 的 UI 事件处理。
|
||
3. **密钥连通性测试未做**——保存假 key 要到真正发消息才暴露。
|
||
4. **打包发布链路未建**——electron-builder 配置、图标、自动更新（排 v0.6，发布前置条件）。
|
||
5. **真实 LLM 端到端仍未验证**（本机无凭据，所有版本共通的遗留项）；用户配 key 后建议按 roadmap 末尾的验收清单过一遍。
|
||
|
||
## v0.1.0 — 骨架 + 聊天链路
|
||
|
||
**交付**：
|
||
- pnpm monorepo（`apps/desktop` + `docs/`；后端/后台/数据库按约定未创建）
|
||
- Electron 44 + electron-vite 5 + React 19 + Tailwind v4 + GSAP + lucide-react
|
||
- 主进程 ESM（`.mjs`）内嵌 pi SDK 0.85.0（`@earendil-works/*` 全部 external，运行时从 node_modules 加载）；preload 输出 `.cjs`
|
||
- IPC：`agent:send/steer/stop/state` + `agent:event` 事件流（delta 40ms 合批，参考 pi-web 节流经验）
|
||
- UI：侧栏（品牌/模型状态/上下文用量/成本/版本）、聊天区（用户气泡、流式助手文本 + 光标、thinking 折叠、工具卡片含参数/结果）、输入区（自适应高度、Enter 发送/Shift+Enter 换行、流式时排队提示 + 停止按钮）、空状态建议词、错误条 + 自动重试条
|
||
- 会话复用 `~/.pi/agent`（与用户已装的 pi CLI 互通）
|
||
- 验证：typecheck 通过、build 通过、应用启动 UI 截图核验通过、pi SDK 冒烟脚本通过（无凭据时错误干净传播）
|
||
|
||
**自省**（v0.1.0 → 指导 v0.2+）：
|
||
1. **真实 LLM 往返未验证**——本机 `~/.pi/agent/auth.json` 为空对象，无任何 API key；模型解析为 `unknown/unknown`（pi 的 fallback）。需要用户配 key（`pi /login` 或等 v0.3 设置界面）后复测流式/工具/思考链路。
|
||
2. **会话管理完全缺失**——重启后不恢复历史；侧栏列表是占位框。v0.2 用 `SessionManager`（list/open/create/rename/delete + 分支）补齐，pi 会话文件在 `~/.pi/agent/sessions/<encoded-cwd>/` 下按 cwd=home 分组，要注意 cwd 策略（固定 home 还是工作区选择）。
|
||
3. **工具面过宽**——当前默认 `read/bash/edit/write` 全开（冒烟已证实）。按架构 D2/D6，v0.4 收窄为业务工具白名单。
|
||
4. **Markdown 渲染极简**——只有 fenced code/行内 code/加粗；标题、列表、链接、表格都没有，长回复可读性差。排 v0.5。
|
||
5. **无 SSE 之外的流控**——超长回复没有虚拟化，消息多后可能卡；先记录，v0.5 评估虚拟滚动。
|
||
6. **坑位记录**：pi-coding-agent 0.85.0 漏声明 `@earendil-works/pi-server` 依赖（已手动补装）；electron-vite 5 需显式 `external: ['electron', /^@earendil-works\//]`；`"type":"module"` 下 preload 必须 `.cjs`；PowerShell 改写含中文的源文件会毁编码（统一用写入工具）。
|
||
7. **交互验证受限**——computer-use 无法激活该窗口（虚拟显示），键盘链路未实测；已用截图 + Node 冒烟双层验证替代，后续版本需人工过一遍键盘操作。
|