inkreach-agent/docs/roadmap.md

路线图与版本自省

每个版本完成后在此追加"自省"：缺什么、哪里不好、下一版怎么补。

版本计划

版本	主题	内容
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 动效细节、快捷键、错误态/空态、队列可视化、自动滚动策略
未来		electron-builder 打包与自动更新、i18n（中/英）、sqlite 持久化与迁移、本地备份恢复、CDP 插件、热点词/生成/模板业务插件、手动模式编排 UI、RPC 子进程隔离模式

---

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.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 冒烟双层验证替代，后续版本需人工过一遍键盘操作。