设计记录
以下按开发阶段记录设计取舍,早期方案可能已调整;当前操作方式以使用文档为准。
调研日期:2026-10-08。查看了下列仓库、产品说明、官方组件示例和终端文档;实际检查了 Vibe Kanban 任务卡片及 shadcn Sidebar 官方截图。借鉴信息架构与交互方式,没有复制其他管理平台的业务实现;Agent 品牌图标使用 Lobe Icons 的 MIT 授权静态素材。
| 参考 | 对本项目的启发 | 本次采用 |
|---|---|---|
| Vibe Kanban、产品界面 | 任务有明确状态,计划、运行和复核阶段需要不同信息密度 | 首页活动卡片 + 最近记录列表;筛选、状态标识和详情入口 |
| Opcode | 项目与会话是本地 CLI 的自然组织单位,用量应按项目和 Agent 查看 | 目录分组、首条用户消息作为标题、历史继续、用量导出 |
| Nexus | 统一入口需要兼容多个终端 Agent,桌面端可使用 Tauri | 内置适配器、自定义程序、真实系统 PTY |
| Agent Deck | 多会话场景需要清楚区分当前关注的任务和终端会话 | 项目导航、状态概览、交互终端与会话恢复入口 |
| Mission Control | 任务派发、执行记录和结果检查应独立表达 | 超级 Agent 父子任务,保存计划和检查消息,失败/等待状态不自动算成功 |
| shadcn Sidebar | 分组侧栏、克制的选中态、工具栏和主体职责清晰 | 左侧图标栏 + 项目栏;标准 Button、Tabs、Dialog、Sheet、Select 等组件 |
| xterm.js 与 portable-pty | 终端应承接原生交互,而非用文本框模拟 | 字节流读取、终端输入、尺寸同步、进程退出与输出回放 |
首页先回答“哪些任务需要我操作”,再展示进行中的任务。卡片只展示名称、Agent、状态、项目、消息预览和用量;会话 ID、退出码、模型、路径放入详情侧面板。历史列表按项目折叠,不将大量对话铺成卡片。
任务详情参照常见聊天产品:消息在居中的阅读列排列,用户消息使用浅色背景,Agent 回复直接呈现 Markdown。工具执行记录默认折叠;底部保留后续输入。原始日志是独立标签页。超级 Agent 的子任务也使用相同详情页面。
UI 使用 shadcn/ui 的主题 token、操作系统界面字体(macOS 使用 SF / PingFang,Windows 使用 Segoe UI / Microsoft YaHei)、Lucide 图标。自定义 CSS 限于主题、页面尺寸与 Markdown 排版。交互动画采用 Motion 的短距离过渡并遵循系统减少动画偏好。
- 内置 Agent:按能力适配结构化事件或文本输出,提供聊天详情、退出状态及已上报用量;会话恢复按程序能力开放,详见 支持范围。
- 自定义程序:参数数组 + Prompt,兼容标准输出与既有 JSONL 事件。
- 交互终端:承接原生 CLI 的权限审批和交互,不推测每条终端命令的语义状态。
- 超级 Agent:将用户目标交给配置的模型生成有界计划,依次执行本机 Agent,最后核对输出。不是无限自主循环,也不通过自动关闭全部权限来绕过阻塞。
CLI 接口依据本机安装版本的 --help,以及 Claude Headless 文档、Qwen Headless 文档。历史格式按本机实际 JSONL schema 适配,并由脱敏的合成 fixture 验证。
| 优先级 | 需求 | 前置工作 |
|---|---|---|
| P1 | 原生审批协议适配 | 为不同 CLI 分别建立双向控制通道,避免根据自然语言猜测审批状态 |
| P1 | Git worktree 隔离与 Diff 审查 | 项目 Git 状态、分支生命周期、冲突处理、合并前预览 |
| P1 | 逐请求用量账本 | 为会话去重的每条用量事件建立时间索引,处理缓存与服务商定价 |
| P2 | 定时任务与并发调度 | 持久任务队列、并发上限、目录写入冲突、失败退避 |
| P2 | 完整插件 SDK / MCP 接口 | 能力声明、版本协商、权限范围、事件契约;与 UI 插件运行环境分离 |
| P2 | 数据存储升级与备份 | JSON 元数据迁移到 SQLite,日志保留策略和增量全文索引 |
这些扩展未出现在界面中作为不可用占位按钮。当前版本优先完成本地任务、聊天详情、历史管理、真实终端和有界编排的闭环。
2026-10-08:视觉与首次使用流程改版
Section titled “2026-10-08:视觉与首次使用流程改版”这轮将界面基础色从偏蓝的灰白调整为低饱和中性灰,保持白色内容区、浅灰侧栏、深灰主要操作。状态色仅用于运行、等待和异常等真实状态。配色是本项目的主题 token,并非声称提取了参考产品的精确色值。
| 参考 | 观察 | 本项目落实 |
|---|---|---|
| Linear 2024 UI 改版 | 统一侧栏、页头、面板的对齐和层级;以黑白关系探索表面颜色 | 去掉蓝色全局底色、蓝色选中态和卡片浮起阴影;统一白色主区、浅灰侧栏、系统字体和紧凑标题 |
| Linear 2026 UI 改版 | 降低辅助导航的视觉重量,减少图标背景与不必要的边界;底色向低饱和灰调整 | 删除重复的机器人图标背景和每张卡片的“查看详情”;首页移除大数字概览卡;状态颜色缩到图标 |
| VS Code Activity Bar | 主导航入口对应一组相关视图,并使用清晰名称 | 图标栏区分工作台、自动化、Agent、插件;底部独立设置;次级导航随分区变化 |
| VS Code Walkthroughs | 引导步骤少,每步提供明确操作 | 可跳过并可重新打开的使用指南:检查 Agent、选择项目、启动任务;另设已有对话入口 |
| Notion Sidebar | 按用途分组导航,项目内容通过可折叠区域组织 | 工作台导航与项目列表分区;项目可收起,配置页面不再铺出项目列表 |
| Raycast Settings | 将扩展和配置放在明确的管理区域 | 管理页使用分区表单;按本次用户要求,Agent 和插件独立于设置,设置仅保留偏好与 API |
阅读了以上官方说明,并查看 Linear 官方浅色/深色主题对比图。采用它们的信息组织原则,继续复用已有 shadcn/ui 和 Lucide,不复制品牌样式。
当前任务页:紧凑状态标签、等待操作优先、按需打开筛选、卡片/列表切换;最近历史最多展示五条,其余进入历史页。历史页保留项目分组、搜索、归档和恢复。
新建任务页:默认只显示项目、Agent、任务内容和执行权限。名称、模型、延后启动收进“更多设置”;自定义命令和交互终端收进带说明的运行方式菜单。自动派发先说明用途并检查 LLM 配置。插件开发示例按需展开。
验证覆盖:首次引导与记忆、分区导航、状态筛选、历史归档/恢复、聊天详情、普通任务/自定义命令/交互终端的提交契约,以及 LLM 未配置时禁止自动派发。当前环境未授予桌面 UI 自动化权限,因此未完成原生窗口截图验收。
对话执行记录与多 Agent 支持
Section titled “对话执行记录与多 Agent 支持”| 参考 | 采用的交互 |
|---|---|
| assistant-ui ToolFallback 与 工具文档 | 工具调用使用紧凑可折叠步骤;默认显示动作、目标及状态,展开后显示输入和结果 |
| AI Elements Tool 与 Chain of Thought | 显式区分执行中、已完成和失败;思考摘要与正文分开,原始事件收进二级展开区 |
| OpenCode Agents | 主会话与子 Agent 可分别查看,并能返回父会话 |
| Claude Subagents | 子 Agent 保留自己的会话、名称与记录,不混入父会话正文 |
| Lobe Icons | 使用官方开源图标库区分 Agent,许可保存在 public/agents/LICENSE |
继续复用 shadcn 的 Button、Tabs、Badge、Tooltip 和原生 disclosure,不引入第二套 UI 基础组件。对话先显示可读结果,命令、文件编辑、计划、搜索和委派记录按类型展开;只有用户主动打开“原始事件”时显示 JSON。工具通过调用 ID 配对,支持并行调用结果乱序返回;流式文字在工具步骤边界内合并。
父会话列表默认收起已有父记录的子 Agent,避免历史首页被内部工作线程占满。详情保留子会话卡片、专用标签及返回父会话入口。导入子 Agent 的状态仍显示“历史会话”,不根据文件时间猜测运行状态。Claude 共用父 session ID 的子记录按 agent ID 独立计量。
本次新增程序的命令和流式事件依据官方文档与源码,具体能力、边界及链接见 Agent 支持范围。新增四个 CLI 未在本机安装,测试采用合成协议事件及真实子进程,不声称完成了对这些 CLI 的真实模型调用。
2026-10-09:对话阅读层级与界面偏好
Section titled “2026-10-09:对话阅读层级与界面偏好”这轮参考了 assistant-ui Tool group、Chat panel、Subagent list 和 AI Elements Conversation 的官方页面与组件示例。
- 对话正文作为唯一常驻主视图;移除第二排日志 / 子任务导航与常驻用量。
- 同一轮回复只显示一次 Agent 名称;连续工具和运行记录合并为可展开的执行摘要,摘要保留失败数和正在执行的动作。
- 长用户消息可折叠;上翻后提供“回到最新”,加载旧消息时保留阅读位置。
- 子 Agent、原始日志、Token 与管理操作统一放入右侧详情面板;子会话保留返回父会话入口。
- 底部按状态提供继续输入、启动、停止或重新配置;无法续聊时不再显示禁用的大输入框。
界面设置遵循 shadcn 主题变量,使用现有 next-themes 管理浅色、深色及系统主题变化。主题色使用 Tailwind 调色板,仅覆盖主要操作与焦点变量;默认保持中性底色。另可调整对话字号。偏好保存在本地,终端、通知、状态及单色品牌图标同步适配深色。
本轮用户明确要求由其查看界面,因此停止窗口预览与视觉验收。
2026-10-09:命令折叠、API 导航与主题修正
Section titled “2026-10-09:命令折叠、API 导航与主题修正”- assistant-ui Terminal block 将命令、目录、真实退出状态与输出分层;AI Elements Terminal 提供状态和复制操作。本项目保持外层执行过程展开规则,命令内部默认收起,摘要限于单行,完整内容按需查看;失败状态可见但不自动展开长日志。
- Claude Code API 配置移至 Agent 程序分区的独立页面,程序卡片保留链接入口;从新建任务进入管理页、配置页后可返回草稿。
- 任务 tab 激活后,面包屑和导航分区从当前任务推导,不沿用之前打开的设置页或项目筛选。
- 依照 shadcn Chart 的主题示例,Recharts 坐标文字、网格、悬浮提示、图例和数据系列接入已有主题变量,避免默认白色提示框与深色文字在 dark 模式下冲突。
只进行代码构建和回归测试,窗口外观按用户要求留给用户查看。
项目文件、Monaco 与执行终端
Section titled “项目文件、Monaco 与执行终端”参考 VS Code 界面结构 的 Explorer 与编辑器标签、Cursor Agents Window 的任务与审阅入口、Cline Checkpoints 的 Compare 工作流。采用明确的“文件 / 改动”次级导航:文件树复用现有侧栏,不增加第四个常驻栏;任务、文件、差异共用标签栏。完整工作区改动与任务记录涉及的文件分开标注,不假设所有改动均由 Agent 产生;此次未实现 Cline 的影子仓库或检查点恢复。
代码编辑采用 Monaco React,依照所安装 Monaco 的 ESM exports 配置本地 Worker、差异编辑器与主题。只读 Git 查询不执行 diff 驱动或 fsmonitor hook;读取数量、文件大小与 Git 进程设有上限。文件保存检查内容版本并以同目录临时文件替换,避免覆盖已检测到的并发修改。
执行记录继续参考 assistant-ui Terminal block 和 AI Elements Tool。利用 Acorn 静态解析 Agent 的 JS 包装调用,提取命令、工作目录和独立工具参数;不 eval、不猜测动态参数,包装代码折叠为原始调用。命令输出去掉可识别的运行包装头,原始事件仍保留。
终端采用 xterm.js 与真实 PTY,只替换任务详情的内容区域。延迟加载和错误边界局部化,终端尺寸约束在详情面板内;无输出、加载失败、进程退出均显示对应状态。实际启动原任务 Agent 的原生 TUI,使用其会话恢复参数;未执行付费模型调用,也未按用户明确要求打开窗口做视觉验收。
导航与侧栏整理(2026-10-09)
Section titled “导航与侧栏整理(2026-10-09)”下表的取舍是针对 OiAgent 工作流的设计判断;来源是各产品的官方界面与交互说明。
| 参考 | 适合借鉴 | 在 OiAgent 中的代价 / 取舍 | 本次落实 |
|---|---|---|---|
| VS Code 布局、最近使用顺序 | 工具栏、侧栏、编辑区职责明确;关闭当前编辑器回到最近使用的编辑器 | 完整 IDE 的多侧栏、多面板会增加任务管理的学习成本 | 保留单侧栏,任务与文件共享 MRU;关闭后台标签不切走当前内容;最后一个标签返回此前页面及项目筛选 |
| Cursor Agents Window | 对话、文件编辑、改动审阅在同一工作区完成 | 更多运行环境、Agent 与视图入口容易争抢空间 | 管理页与工作区分层,从 Agent / 插件 / 设置返回工作台时恢复原任务、文件或列表;保留任务 Tab 与文件 Tab |
| JetBrains Tool Windows、Editor Tabs | 工具按场景出现,编辑区保持明确焦点;关闭标签后的目标有独立规则 | 隐藏工具会降低首次使用时的可发现性 | 管理页侧栏只保留相关导航,去掉重复说明与无关新建入口;项目文件区保留带文字的返回入口 |
侧栏默认 256 px,整个应用共用同一宽度,不随页面、项目、文件切换改变。拖动边缘可调至 208–420 px,窗口较窄时为主体保留空间;支持方向键调整、双击复位,宽度存入本机偏好。页面切换只保留轻微淡入,避免纵向位移。最左侧图标统一为 20 px、点击区域 40 px。状态栏只在同步或读取异常时显示右侧文字。
关闭有未保存修改的文件时,先处理保存 / 放弃 / 取消;只有实际关闭后才改变活动 Tab 和访问历史。关闭 Tab 不停止任务或 PTY 进程。
文件编辑事件与上下文菜单
Section titled “文件编辑事件与上下文菜单”- Cline ChatRow 源码:编辑、新增和删除有明确文件入口,内容可以折叠。OiAgent 将文件入口保留在紧凑卡片中,多文件分别显示;调用参数继续收起。
- 文件卡片接入现有 Monaco 文件 / Git 差异标签。这里的“查看改动”是当前工作区相对最近提交的差异,可能包含用户及其他任务的修改,不伪装成单次事件快照。项目外路径禁用打开入口。
- VS Code 上下文菜单规范:仅显示当前对象相关操作,相近操作分组。相比把所有功能塞进一个菜单,这种方式更易扫描,但仍需在卡片和工具栏保留常用入口。
- 使用现有 shadcn/Radix Context Menu(同一套主题、焦点管理和边缘避让)。任务列表提供打开 / 复制,标签提供关闭 / 批量关闭,文件提供打开 / 工作区差异 / 路径复制,消息提供整条或选中文本复制。右键后台标签不改变当前标签;批量关闭复用未保存文件保护。Monaco 和 TUI 不被全局菜单接管。
OiAgent 标志
Section titled “OiAgent 标志”- Cursor 品牌规范:区分界面标志与应用图标,提供不同背景版本。借鉴其简洁的轮廓和分场景资产,不使用其立方体图案。
- Mistral 品牌规范:紧凑符号、独立图标、单色版本和留白规范。OiAgent 采用单色而非其渐变或像素形象。
- VS Code 品牌规范:普通标志与应用图标区分,背景对比不足时使用反白。OiAgent 界面通过 alpha mask 跟随主题文字色,桌面版本使用素色底板。
最终采用开放的圆角 O 环与右上圆点融合为 i 的单色符号。圆点与环呼应 Agent 和工作区,不堆叠机器人、星芒或网络节点。图像由 imagegen 根据专门的几何构图生成,参考品牌图案没有作为 OiAgent 素材使用。界面只使用符号加现有字体的 OiAgent 名称,不引入装饰字体、渐变或动画。PNG 源稿保留在仓库,平台图标由 Tauri CLI 生成。
2026-10-09:MCP 与 Skills 管理
Section titled “2026-10-09:MCP 与 Skills 管理”- VS Code MCP 管理:采用独立管理入口及用户/项目作用范围。优点是配置上下文明确;直接照搬设置 JSON 对首次使用不友好,所以 OiAgent 提供命令、逐行参数、远程地址表单,认证和其他原生字段放在高级配置中。
- Claude Code MCP、Codex MCP、OpenCode MCP、Gemini MCP:使用各 CLI 的原生配置格式,不另外存一份无法生效的通用配置。Codex 使用 TOML;OpenCode 使用
mcp,其余适配程序使用mcpServers。Claude 用户级.claude.json和项目级.mcp.json分开管理。 - Codex Skills、Gemini Skills、Qwen Skills、OpenCode Skills:展示 SKILL.md 名称和用途,支持导入完整目录、新建、编辑和移出加载目录。Codex 主目录采用
.agents/skills,兼容读取旧.codex/skills。 - 保存前检查原文件指纹,检测外部修改;保存使用临时文件和替换,配置原文备份。TOML 保留无关配置及其注释;JSONC 保存为格式化 JSON,原注释保留在备份。配置管理不会执行 MCP 或 Skill 脚本。
- 暂未适配 Goose/Aider/自定义程序的原生配置,界面明确说明,不伪装成已生效。导入拒绝符号链接、特殊文件和过大资源包。
2026-10-09:局域网设备与任务
Section titled “2026-10-09:局域网设备与任务”- 用户选择另一台安装 OiAgent 的电脑作为控制端。VS Code Remote SSH 与 Zed Remote Development 将执行设备作为工作上下文,并持续显示连接状态;优点是本机与远程资源不易混淆。但完整远程 IDE 引入安装服务器、终端和文件系统访问,本轮只接入任务生命周期,不开放任意文件/终端 RPC。
- Tailscale 设备审批 提供显式批准和撤销的设计依据。OiAgent 将“共享本机”“连接其他电脑”“允许访问本机的设备”分组;主页面只保留开关、共享范围、配对入口和设备状态,端口放进高级设置。
- 安全默认:启动时关闭;只绑定选中的 RFC1918 / IPv6 ULA 网卡;TLS 自签名证书通过一次性邀请传递,客户端仅信任这份证书、检查地址、不跟随重定向、不使用系统代理,不忽略证书错误。配对码 5 分钟有效、单次使用,本机审批后才发放高熵令牌。
- 服务端只存令牌哈希;客户端使用系统凭据存储(macOS Keychain、Windows Credential Manager、Linux Secret Service)。配对、速率、请求大小和并发均有限制,浏览器 Origin 请求被拒绝。设备权限随每次请求验证,关闭共享会中止监听并使旧连接失效。
- 远程任务只允许显式共享的项目、内置 Agent 和受限权限选项,拒绝自定义命令、额外参数、环境变量、指定 API 凭据及外部会话恢复。设备只能查看/操作自己创建的任务,不能枚举本机原有历史。共享项目限制任务工作目录,不代表 OS 沙箱;实际工具能力仍由 Agent 的本机配置决定。
- 已接受的任务在断线、关闭共享、撤销设备后继续执行,可由本机停止。控制端保留本次打开期间的离线记录;任务在执行设备持久化。远程文件编辑、原生 TUI 及超级 Agent 调度不在此接口范围内。
- 自动化覆盖配对未审批/重放/错误票据、任务授权范围、撤销、任意 RPC 拒绝、错误 TLS 证书和远程启动参数清理。证书握手使用本机回环测试,没有调用真实 Agent 或收费 API;未进行两台物理电脑的实机联调,也未验证 Windows/Linux 构建。
- macOS 打包加入
NSLocalNetworkUsageDescription,依照 Apple 本地网络隐私说明 和 Tauri 原生配置合并方式。系统网络权限仍由用户在实际连接时决定。
2026-10-09:模板、Prompt 优化与就地新建
Section titled “2026-10-09:模板、Prompt 优化与就地新建”- VS Code Prompt Files:借鉴“可复用提示 + 显式调用 + 参数填写”。优点是重复工作更快;纯文本文件的发现与编辑门槛较高,因此 OiAgent 用输入框旁的模板库,先预览再插入,支持分类、搜索和自定义变量。该页面注明 Agent Host 已转向 Skills;这里借鉴交互,不宣称兼容 VS Code 原生配置。
- Claude 提示词最佳实践:优化围绕目标、范围、约束和预期结果,保留原意,避免自动扩大任务。原文与建议分开,可编辑、确认替换和撤销;无 API 时直接进入配置并保留任务草稿。模型建议仍可能出错,由用户决定是否使用。
- Zed Parallel Agents:借鉴项目内新建线程及独立标签。优点是无需反复选项目,但容易混淆“继续旧任务”和“新任务”;OiAgent 新建只继承项目、设备、Agent,不继承上一任务内容、会话、参数或放宽的权限。
- 模板只保存 Prompt;全局模板可跨设备任务复用。优化请求始终由控制端配置的 LLM 执行,不把 API 凭据传到执行设备。
保留已认可的 24px 导航图标。品牌标志由同一轮廓派生为细线条 SVG(1.65 笔画、1.25 圆点半径),替换粗重的旧位图;桌面图标使用素色圆角底板。SVG 是后续编辑源稿,Tauri CLI 统一生成 PNG、ICO、ICNS 和 favicon,避免应用与界面图标不同步。
2026-10-09:全局返回
Section titled “2026-10-09:全局返回”参考 VS Code 位置导航 与 JetBrains 导航历史,新增按访问顺序返回的全局入口,放在最左侧图标栏顶部,提示显示在右侧。首次打开不显示,没有更早可访问位置时隐藏。页面、项目筛选、任务与文件标签共用访问记录,关闭标签后的最近访问逻辑保持独立;已关闭标签跳过,不重新打开。任务状态更新和输入草稿不新增访问记录,返回动作本身也不入栈。新建任务草稿仅在内存保留,返回后恢复,历史最多保留 100 个位置。
沿用 Motion useAnimate 和 减少动态效果支持:工作区位置改变时,用 180ms 淡入及 4px 位移过渡,连续切换会停止上一次动画;内容更新和输入不会触发。动画作用于稳定容器,不重建任务详情或终端。返回按钮以高度、间距和透明度一起展开/收起,使下方图标平滑让位;收起即移出键盘与辅助技术交互范围。系统启用减少动态效果时直接切换。
2026-10-09:配置持久化与系统文件入口
Section titled “2026-10-09:配置持久化与系统文件入口”- LLM 配置复用项目已依赖的 keyring 系统凭据库,API 地址、模型和密钥作为一个凭据写入,避免保存中断造成不同服务的配置混用。重启后的首次读取放在后台工作线程;返回前端的状态只含地址、模型和是否存在密钥。测试使用独立 MockCredential,不访问开发者的真实凭据库。
- Skill 编辑复用文件工作区和 Monaco,保存仍走原生 Skill 校验、指纹比较及备份流程;使用普通文本文件的未保存保护和外部修改比较。列表恢复 Agent、范围及 Skills 标签,新建只填写名称与用途,正文进入文件标签编辑。
- 系统打开使用 Tauri 官方 Opener,前端只提交项目目录、相对路径及 open/reveal 操作。后端复用文件路径校验,拒绝越界、符号链接和缺失文件;不开放 URL、指定外部程序或任意 Shell 执行接口。关闭插件自动接管网页链接功能,系统打开仅由明确的菜单操作触发。
- 使用指南参考 VS Code 欢迎页实现 的 Start、Recent、Walkthroughs 分区及简短操作入口。OiAgent 保留现有布局,使用“开始”“历史记录”“配置与扩展”“任务状态说明”,按钮直接描述操作,去掉“找回”“探索”等引导式措辞。
2026-10-09:README 信息结构
Section titled “2026-10-09:README 信息结构”本次参考各项目仓库中的 README,借鉴文档组织方式,正文按 OiAgent 的实际功能编写:
- Zed:项目定位简短,安装与开发入口直接可见。
- VS Code:首页保留项目概览,详细开发说明链接到专门文档。
- Cline:顶部品牌与导航集中,按使用场景介绍功能。
- CC Switch:用能力表说明工具差异,将快速开始与完整手册分开。
- AionUi:为多 Agent 工作区提供清楚的功能分组和下载入口。
OiAgent 首页采用品牌标志、功能概览、Agent 兼容表、快速开始和折叠问答。原有操作与实现细节迁入 使用手册。未添加虚构截图、性能数字、发布状态或许可证徽章;安装说明保留当前平台验证范围。
2026-10-09:临时项目、指令文件、关于页与项目网站
Section titled “2026-10-09:临时项目、指令文件、关于页与项目网站”- VS Code 未命名工作区和 IntelliJ Scratch files:借鉴先开始工作、再决定是否保留的操作方式。OiAgent 使用独立工作目录,结束后保留,归档 7 天后启动时清理;保留与删除有明确入口。
- VS Code 关于对话接口和 IntelliJ 帮助入口:关于页聚焦安装版本、复制诊断信息、文档与反馈,不展示框架清单或宣传语。
- 指令文件按原生 CLI 的范围和名称适配,依据 Codex AGENTS.md、Claude Code memory、Qwen memory、Gemini GEMINI.md和 OpenCode rules。选择 Agent 与作用范围后进入文件编辑器,保留备份与冲突检查,不自动同步到运行中的模型。
- 网站参考 Zed的产品与文档分工,以及 Starlight的侧栏、搜索和主题组件。首页使用项目标志、简短用途、任务场景与文档入口,不使用虚构截图或性能宣传。
- 静态部署按照 Astro GitHub Pages配置独立构建、仓库子路径、静态产物和部署工作流。审批文档明确当前只有等待状态识别与原生 TUI 处理,没有统一 GUI 审批卡片。
独立网站第二版
Section titled “独立网站第二版”- Linear:首页先展示工作界面,再分区说明用途。本项目采用可切换的任务、对话和文件示例,明确标注示意内容;不使用虚构用户数、评价或性能数据。
- Zed:产品界面承担主要展示,下载和项目入口保持直接。OiAgent 首页删除原先的功能对照表和大 Logo 展示,保留工作区、Agent 列表和文档入口。
- Cursor Docs:增加文档概览,把首次使用、日常操作与配置分开;详细文档保留左侧分类和右侧章节目录。
- Starlight 组件替换:通过正式扩展点替换首页、页头与页脚。搜索、主题、移动导航、Tabs、Steps、Aside、LinkCard 和代码高亮继续使用组件库;样式通过主题变量和必要的布局调整统一。
网站保留灰白与暗色两套主题,正文采用系统字体。选中状态与 hover 分开处理;示例标签支持键盘切换,动效遵循系统的减少动态效果设置。
Claude Code API 配置与检测
Section titled “Claude Code API 配置与检测”- cc-switch 添加供应商 与 模型获取实现:服务字段和模型映射分区,远端模型列表与手动填写并存。OiAgent 使用独立编辑页,不自动覆盖模型映射。
- Anthropic Models API:按
data、has_more、last_id读取分页,提供超时、数量和响应大小限制;列表加载失败不阻止手动配置。 - Claude Code 模型配置:Fable 映射写入任务环境的
ANTHROPIC_DEFAULT_FABLE_MODEL,与其他三个模型别名一致。连接测试解析已配置别名后发送短 Messages 请求,不硬编码某个“最新”模型。 - CC Switch 模型表单:按模型角色排列显示名称、请求模型 ID 和独立 1M 选项;常用高级配置折叠展示。JSON 支持粘贴、文件导入和编辑,确认应用到草稿后再保存。保留完整的非鉴权设置,包括插件、未知字段及独立的
model;导入的标准鉴权字段分离到已有加密密钥存储。执行时合并到会话私有 settings 文件,原始全局及项目文件保持不变。1M 标记兼容大小写,连接测试不将标记发送给模型服务。
连接测试与模型列表请求不写入任务记录,不返回密钥,也不回显上游错误正文。保存的密钥只在地址和鉴权方式仍匹配时用于请求,HTTP 仅允许本机回环地址,重定向不自动跟随。验证使用本地模拟服务,不调用用户的真实 API。
TODO List
Section titled “TODO List”- Things 默认列表:借鉴未完成计划与完成归档分离,以及列表内按项目整理的方式。本次不增加日历、周期任务或看板。
- Todoist 任务详情:名称留在列表,备注与项目放在展开的编辑区,减少常驻字段。
- Microsoft To Do 添加与编辑:回车快速添加、直接勾选完成、恢复未完成;重要标记用于排序和筛选。
OiAgent 在每条未完成计划旁提供「创建任务」,带入名称、备注与项目目录,仍需用户确认 Agent 和执行权限。已有草稿时明确选择追加或替换,计划完成状态由用户控制。清单独立按需读取,原子写入并检查版本,不纳入任务历史扫描。
计划编辑页与子计划
Section titled “计划编辑页与子计划”参考 Todoist 子任务 的层级列表、折叠和独立详情。OiAgent 将编辑表单移到独立页面,支持根计划与四级嵌套;编辑页可改变父计划,前后端拒绝循环关系、缺失父节点与超深层级。
父计划显示直接子计划完成数;过滤时保留祖先作为上下文。完成父计划可一并完成后代,操作前确认;恢复子计划会恢复祖先,完成所有子计划仍需手动确认父计划。删除仅移除选中的计划,子计划上移一级。每份编辑草稿使用独立的导航标识,返回和关闭标签跳过已保存、已放弃的编辑页。后台只修改其他计划时更新草稿版本;同一计划冲突仍要求明确重新载入。
可恢复的工作流与人工确认
Section titled “可恢复的工作流与人工确认”本次阅读了以下官方产品页面及文档:
- Dify Workflow Studio:步骤类型、控制流与运行观察分层。OiAgent 采用工作流库、独立步骤编辑页和运行详情;文件操作按顺序执行,避免同项目并行修改相互覆盖。
- Dify Human Input:确认与补充说明作为工作流步骤。OiAgent 在运行页提供确认、拒绝和补充输入,不把等待超时当作同意。
- n8n Executions:工作流定义与运行记录分开,运行保留自己的计划快照。OiAgent 删除定义不会删除已有记录,失败步骤重试保留之前成功结果。
- LangGraph Persistence:在执行边界保存状态。OiAgent 在启动子进程前记录尝试和任务 ID,重启后等待用户决定,不自动重放执行结果不明确的步骤。
采用紧凑的步骤列表与右侧配置区,避免在当前桌面布局中再嵌入复杂画布。支持 Agent、人工确认、LLM 检查三类步骤,检查失败可按用户指定上限返工。当前不实现定时器、任意条件分支或多项目并行调度。文档内的 Dify 截图请求返回 403,结构参考来自可访问的产品页面和官方说明;未据此声称复刻了截图布局。
计划生成与结果检查的 Prompt
Section titled “计划生成与结果检查的 Prompt”参考 LangGraph Workflows and Agents 中的任务串联和评估后修订,以及 Claude Prompting Best Practices 中明确目标、约束与输出格式的建议。
计划生成明确当前执行器的能力:顺序执行、共享项目、三种步骤、有限的前序结果摘要。未知项目事实先调查,需用户决定的事项单列人工确认;实际测试由 Agent 执行,LLM 检查只评价报告中的证据。生成结果经过类型、Agent 可用性与权限校验,并清除模型覆盖、API 配置和自动返工设置,再交给用户编辑。检查 Prompt 区分任务要求和不可信输出;证据不足时说明缺少什么,不凭退出码判定成功,也不追加原目标之外的要求。
计划拖动与固定页面标签
Section titled “计划拖动与固定页面标签”参考 Todoist 子任务 的拖动手柄、层级调整,以及筛选或自动排序下限制拖动的做法;结合 VS Code 界面说明 中标签和导航分区的方式。
OiAgent 使用三种可预览落点:同级之前、同级之后和子计划;独立区域用于移回顶层。拖动保留整个子树,前后端均校验循环与深度,落下后才保存。使用 dnd-kit 的 PointerSensor 与 KeyboardSensor,手柄以外仍可正常点击和滚动。返回按钮移至顶部,标签栏固定保留功能页入口,不参与文件和任务的批量关闭。
项目置顶与归档批量操作
Section titled “项目置顶与归档批量操作”参考 Slack 星标对话 将常用项目保留在侧栏顶部,以及 shadcn/ui Data Table 的行选择、选择计数和批量操作。
OiAgent 在项目与会话列表的悬停区提供置顶和颜色按钮,避免常驻文字挤占名称空间。项目不归档;会话归档后可在独立列表多选恢复或删除。切换筛选时清空选择,删除前显示目标和保留范围。
图工作流(2026-10)
Section titled “图工作流(2026-10)”| 参考 | 采用的做法 | 在 OiAgent 中的取舍 |
|---|---|---|
| Dify Workflow Studio | 连接画布、选中节点后配置、分开观察运行结果 | 节点只显示名称、Agent、权限或状态;内容及高级参数放右侧,不堆进卡片。 |
| n8n Flow Logic | 显式分支、汇合及可见执行关系 | 支持“是 / 否”出口与等待全部前置路径的汇合;不用数组顺序暗示依赖。 |
| LangGraph Workflows | 并行、路由、评估后修订 | 只读 CLI 并行,项目写入在单次运行中互斥;返工限制到独立前置 Agent,避免其他路径使用过期结果。 |
| React Flow、Handle | 成熟的连线、拖动、缩放和节点交互 | 使用库内画布及控件,结合现有 shadcn、Agent 图标、主题变量;提供下拉连线入口,不强制精细拖动。 |
以上是设计取舍,并非复刻这些产品的完整能力。图仅支持 DAG,条件使用已配置 LLM 判断证据;不支持任意代码条件、定时触发、跨设备节点或无限循环。原有顺序计划仅在编辑时迁移,正在使用的旧运行保持原执行器。
性能方面,画布模块延迟加载;拖动仅更新草稿,不写磁盘。执行器每次处理状态变化时保存检查点,普通轮询不写盘、不发送状态事件。一个协调线程管理节点状态,CLI 子进程与 LLM 请求并行;用量写入也使用同一把锁,避免覆盖运行记录。未变化的运行版本不触发重绘,拖动坐标在松手后写回表单。前序结果仅收集已连接的祖先摘要。最多 24 个节点、4 个活动节点,画布渲染使用稳定组件类型。
此节替代前面顺序工作流版本的“不提供分支”限制及列表编辑方案。
工作流固定工作区
Section titled “工作流固定工作区”继续参考 React Flow Workflow Editor 的画布编辑组件组合,以及 n8n Workflow components 的节点与连线结构。此前把全局设置、目标和节点参数纵向排列,导致操作位置分散;此次调整为固定顶部操作、填满剩余空间的画布和右侧设置面板。
全局设置与节点设置共用同一面板。生成计划与 LLM API 设置放在任务目标下方,顶部仅保留名称、保存和启动。节点参数分为内容、执行和连接,表单控件统一占满面板宽度。添加节点收进菜单,较少使用的并行数放在运行选项内。画布不随设置分类切换而重建,长 Prompt 在输入框内滚动;窗口较窄时设置面板覆盖画布右侧,可收起后继续编排。未添加新依赖。
顶部标签拖动排序
Section titled “顶部标签拖动排序”参考 VS Code 的标签与编辑器布局 和 IntelliJ IDEA 的编辑器标签,保留原有标签外观,直接拖动标题调整位置。实现复用已有 dnd-kit DndContext,不增加依赖。
任务、文件和当前页面共用一个显示顺序;移动时显示落点,放下后才更新顺序。拖动使用位移阈值避免误触,超出标签栏或按 Escape 取消。排序与访问历史分离,关闭右侧按显示顺序处理,关闭当前标签仍按访问顺序返回。页面标签保持不可关闭。
应用插件:清单、宿主与管理页
Section titled “应用插件:清单、宿主与管理页”参考 VS Code Contribution Points、Extension Host 和 Web Extensions,采用声明式入口、版本化 API、按需加载和独立 Worker。界面通过宿主组件描述,而非直接修改应用 DOM;避免插件样式污染现有任务与编辑器。
管理页参考 VS Code Extensions 和 IntelliJ IDEA Plugins:左侧搜索和列表,右侧详情、页面入口、设置、权限;窄区域在列表与详情之间切换。安装预览、启用、更新和卸载分开处理,不在页面内放开发教程。
OiAgent 当前使用本地目录安装,没有引入市场、签名服务或 Node.js 宿主。工作区只加载清单,页面打开后才加载脚本;隐藏页面终止 Worker、保留表单草稿。UI 按帧合并,树规模、消息数量和持久数据都有上限;没有新增运行时依赖。旧 CLI 协议继续作为 Agent 配置使用。
审批与窗口关闭
Section titled “审批与窗口关闭”- Claude Agent SDK:用户审批与提问:把操作内容与本次批准、拒绝、回答问题放在同一张卡片,不暗中提升后续权限。
- Cline:审批控制:区分命令、文件操作等具体请求,保留完整参数供核对。OiAgent 的「允许本次」不会启用自动批准。
- Tauri:系统托盘与 Slack:通知设置:区分关闭窗口与退出程序,在托盘提供恢复窗口、退出两个固定入口。关闭偏好可记住,但运行任务和未保存文件仍需确认退出。
MCP 与 Skill 编辑
Section titled “MCP 与 Skill 编辑”- VS Code MCP 管理和扩展列表:搜索与类别切换放在列表顶部,单项管理操作集中到右侧菜单,编辑进入单独页面。OiAgent 的用户级、项目级范围保留为共同筛选。
- Agent Skills 格式规范、Anthropic Skill Creator和 OpenAI Skills:AI 帮写保留明确的触发条件、任务边界和按需展开的参考资料;生成后先比较改动,再应用与保存。只生成 SKILL.md,不虚构配套文件。
2026-10-11:配置列表与确认弹窗
Section titled “2026-10-11:配置列表与确认弹窗”参考 VS Code Agent Customizations 的分类、搜索和逐项编辑布局,以及 Zed MCP 管理 的列表与新增入口。MCP/Skills 页将 Agent 和作用范围合并为一个切换入口,当前值始终可见;搜索与新增并排,刷新、导入和路径操作放入菜单。
退出提示沿用 Radix Dialog 的焦点和键盘交互:正文只说明任务与未保存文件的影响,操作集中在底部,默认聚焦取消。弹窗与 AI 帮写面板使用短过渡,并遵循系统的减少动态效果偏好。
2026-10-13:新建任务与工作台
Section titled “2026-10-13:新建任务与工作台”参考 VS Code Chat view 的底部输入区和会话控制项、Claude Code Desktop 的项目与权限选择,以及 assistant-ui Composer 的输入和发送布局。
新建任务将项目、Agent、权限和 Prompt 优化放在输入框附近,使用设置中的发送快捷键启动,与任务对话保持一致,Shift+Enter 换行;高级参数按需打开。当前任务默认按状态分组显示列表,历史记录保持独立。侧栏突出当前导航项,图标栏和侧栏使用不同底色。启动页只根据首次加载的任务状态选择,用户开始操作后不再自动跳转。
2026-10-13:对话、审批与运行中控制
Section titled “2026-10-13:对话、审批与运行中控制”参考用户提供的 ChatGPT 应用布局、Claude Code 交互模式、权限审批和 Copilot CLI 消息引导。保留居中的阅读列与底部输入框;借鉴操作分层,不照搬不同 CLI 的执行行为。
| 区域 | 默认展示 | 按需展开或操作 |
|---|---|---|
| 回复 | Markdown 正文、文件与网页链接 | 长用户消息展开;代码复制 |
| 执行过程 | 展开步骤分组,显示操作、对象和状态 | 命令、工具参数、子 Agent 派发等最底层记录折叠 |
| 审批 | 操作名称、用途、命令或修改前后内容、文件与工作目录 | 其他参数折叠;允许、拒绝、停止;拒绝原因可选 |
| 输入框 | Agent、权限、发送;运行时显示停止 | API 与模型放入对话设置;发送菜单选择排队或立即发送 |
| 消息队列 | 输入框上方显示数量、Agent 与消息预览 | 移除消息;暂停后继续队列 |
| 代码块 | 语言或内容类型、复制、语法高亮 | 内部滚动;不自动打开折叠的执行记录 |
- 默认发送:加入队尾,不打断当前轮。成功结束后继续;失败、等待操作或停止时保留队列。
- 立即发送:先保存消息,再停止当前进程。确认旧进程退出后优先执行新消息,其余消息顺序不变。优先恢复对应 Agent 的会话;不能恢复时传入有界历史上下文。它与 Copilot 的原生 steering 不同。
- 权限:本机 Claude Code、Qwen Code 通过控制协议切换,收到确认才更新显示。失败不改变已显示的权限;已有审批仍需用户答复。其他连接的选择只用于下轮,界面区分「当前执行权限」与「下轮执行权限」。
- 错误:未能停止或重新启动时,消息保留在队列;不自动重试可能产生副作用的操作。不因切换到 Auto 就代用户批准已有请求。
- 终端:由原生 TUI 接管输入,不与 GUI 同时向一个进程发送消息。
性能与内容安全
Section titled “性能与内容安全”语法高亮使用 highlight.js 常用语言包,代码块出现后异步加载,在共享 Worker 中计算,合并流式更新,不对日志自动猜测语言。Worker 空闲 30 秒后释放,过期结果丢弃;超过 50,000 字符时保留纯文本,复制始终使用原文。浅色和深色使用 GitHub 语法主题;高亮输出转义源码中的 HTML。消息调度按任务互斥,不阻塞其他会话的发送。
运行中的任务输出按 100 毫秒合并更新,等待确认、完成等状态立即更新。未变化的任务保留引用与排序,历史消息保留 Markdown 渲染结果。隐藏标签停止接收父页面的重复渲染,同时保留草稿与原有空闲释放机制;窗口隐藏时暂停对话、工作流、产物、文件树、Git 和端口检查,返回后恢复。产物列表按固定周期刷新,不随每次 token 更新重启查询。文件树与 Git 轮询等待上次读取完成,未变化的结果保留引用。
任务详情在任务入口悬停或聚焦时预加载。进展卡片仅在尺寸实际变化时测量,合并同一帧内的尺寸通知;高度与分区位移使用原生动画,遵循系统减少动态效果设置。
2026-10-13:运行反馈
Section titled “2026-10-13:运行反馈”当前轮 Agent 回复末尾显示加载图标,尚未收到回复时也显示;等待审批、完成、失败或停止后移除。历史回复和嵌套工具记录不继承父任务的加载状态,动画遵循系统减少动态效果设置。
工作流节点参照 React Flow 状态指示的分状态展示,补充最新一次执行的 Agent 和两行消息预览。节点详情复用子任务卡片,显示状态、预览、模型和已上报用量;点击进入对话。重试记录按最新在前排列,进度直接使用任务上报内容,不估算完成百分比。
参考 VS Code 的编辑器组与网格布局:拖到边缘分栏、拖入其他组移动标签、关闭空组后合并空间。分隔线采用 shadcn/ui Resizable 使用的 react-resizable-panels,复用键盘调整和尺寸约束。
分组与访问历史独立维护。每个标签只有一个实例,移动时保留编辑器、对话和终端状态;面包屑与任务操作跟随当前焦点。插件仅在可见分栏中运行,隐藏后暂停,避免后台页面持续消耗资源。
窗口与版本检查
Section titled “窗口与版本检查”窗口布局参考 VS Code 的自定义布局,按 Tauri 窗口定制文档实现:macOS 使用 Overlay 标题栏保留系统按钮,Windows / Linux 使用自定义窗口控制。关闭按钮仍经过现有任务与未保存文件确认流程。
版本信息来自 GitHub Latest Release 接口。按 SemVer 比较正式版本;不将请求失败当作最新版本,不读取或发送 Agent 配置。后台与手动检查共享请求,提示集中在关于页面,设置入口仅显示黄点。
标题栏保持 48px 高度,与主内容顶部对齐。macOS 按系统按钮的实际高度居中,调整原生标题栏的点击区域,并在窗口缩放、屏幕缩放比例变化和重新聚焦后恢复对齐;全屏期间交给系统管理。Windows / Linux 的窗口按钮并入页面标题栏右侧,不增加整页顶栏;参照 VS Code 标题栏样式,按钮各占 46px,撑满标题栏高度,图标居中,按下不发生位移。标题与页面操作在窄窗口中允许横向滚动,窗口按钮始终保留独立空间。
输入框模型选择
Section titled “输入框模型选择”模型与 API 配置位于输入框底部,任务模板使用图标入口。模型菜单内集中展示该模型的可选参数,避免工具栏铺满设置项。新建任务与续聊使用同一组件。
模型数据遵循 Codex App Server model/list、Qoder CN 模型选择及 Qoder SDK 模型接口。OpenCode 使用 models 命令。Claude Code 沿用应用已有 API 配置,与原生模型配置的环境变量映射一致。
目录查询不发送任务或模型请求;按程序版本和项目缓存、合并并发请求。只传递白名单模型字段,不将完整配置或账号信息发送到前端。未提供机器可读能力的 CLI 允许手动输入,不补造模型或参数列表。
紧凑菜单、路径导航与内容过渡
Section titled “紧凑菜单、路径导航与内容过渡”- 参考 VS Code 紧凑菜单:Windows / Linux 将应用菜单入口放到图标栏顶部,复用原生菜单的动作、快捷键和可用状态。macOS 窗口控制区保留在导航列顶部,主内容不增加顶栏空白;左侧主导航始终展开,移除收起按钮、菜单项和快捷键,保留宽度调整。
- 参考 VS Code 面包屑及其目录选择截图:路径逐级显示,点击展开同级目录与文件。目录按需读取;后端仅扫描当前层,按目录优先排序、游标分页,每页 80 项,搜索不受当前页限制。
- 共用 Radix 下拉菜单和右键菜单按内容确定宽度,受窗口宽度限制。操作文字单行显示,图标、快捷键和子菜单箭头保持固定占位;纯文本长标签截断并保留完整标题提示。
- 任务进展卡片使用已有 Motion 和 ResizeObserver 对内容高度与分组位置变化做 200ms 过渡,遵循减少动态效果设置。上下文用量与权限、监管位于输入框下方同一行,左右分布并垂直居中,详情卡片向左对齐。
- 运行任务按创建时间排序,历史任务仍按更新时间排序;任务列表、项目内列表和未访问项目的排序共用同一时间规则。正文、用量更新不改变运行任务的位置。
- 任务详情使用完整的侧向进出动画,遮罩与面板同为 200ms;面板退出完成后再释放改动和产物预览。减少动态效果时直接切换。
- 按钮只过渡颜色、边框颜色、阴影和透明度,按下不平移。项目行操作预留固定宽度,悬停只改变透明度;提示延迟 350ms 显示,与触发按钮保留间距,只做淡入淡出,箭头沿用组件原生定位。
子 Agent 入口与列表(2026-11-02)
Section titled “子 Agent 入口与列表(2026-11-02)”以用户提供的 Codex 侧栏截图为主参考:子 Agent 分组使用一排少量图标及状态数量,不为每个子任务再套卡片。沿用已有 Agent 品牌图标,浅色底帮助区分固定身份;运行、等待和异常使用状态标记。标题进入已有详情页面,单个图标直接打开子会话,顶部移除重复入口。
详情采用平铺列表,分工名称与状态在首行,任务、最近输出和模型用量按层级展示。搜索覆盖全部子任务,按状态筛选,每次挂载 40 条。图标和列表按创建顺序固定,不按输出时间或状态变化重排;复用任务进展的尺寸动画及减少动态效果设置,不改变详情面板宽度。
2026-11-10:存储空间的概览与清理流程
Section titled “2026-11-10:存储空间的概览与清理流程”实际查看了 Telegram Desktop 存储管理截图、Telegram 官方存储管理介绍及界面素材 与 Be Connected 的 macOS 存储界面截图(第 2 页)。后者展示的是 Catalina,借鉴概览和管理分层,不作为当前 macOS 外观依据。
- 概览采用容量条、分类大小和明确的清理入口;隐藏没有内容的分类。分类占比复用已有 chart token,列表、按钮、信息弹层使用已有 shadcn/Radix 组件。
- 具体项目放入固定尺寸的管理弹窗,支持搜索、排序、本页选择和分页。首页保留一行自动清理规则;路径、保护原因和统计范围按需查看。
- 删除确认在同一弹窗中完成,保持尺寸和焦点连续。确认前展示删除影响及具体目录;每次最多选择 100 项,默认不选中,受保护项不能被批量勾选。
- 只在进入页面、手动刷新和清理后分析;管理列表每页最多 50 项。按用户要求未启动浏览器,使用组件交互测试、类型检查和构建验证。