应用架构概览

pinable-desktop 是 PinableAgents 的图形化桌面客户端，基于 Wails 框架构建。Wails 是一个轻量级的桌面应用框架，它将 Go 作为后端语言，React 作为前端渲染层，通过系统原生的 WebView 组件呈现界面，避免了 Electron 带来的巨大资源开销。

整体架构分为三层：

  • Go 后端层：负责核心业务逻辑，包括模块管理、工作流编排、文件系统操作、Git 命令执行以及与 AI 后端的 API 通信。Go 层通过 Wails 的绑定机制将服务方法暴露给前端。
  • React 前端层：使用 React 18 + TypeScript 构建，配合 Tailwind CSS 实现响应式界面。前端通过 Wails 提供的 window.go 命名空间调用后端方法。
  • IPC 桥接层：Wails 运行时在 Go 和 JavaScript 之间建立双向通信通道，支持方法调用和事件推送两种模式。
┌─────────────────────────────────────────┐
│            React Frontend               │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Modules  │ │ Workflows│ │ Terminal │ │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│       │             │            │       │
│  ─────┴─────────────┴────────────┴───── │
│           Wails IPC Bridge              │
│  ───────────────────────────────────── │
│       │             │            │       │
│  ┌────┴─────┐ ┌────┴─────┐ ┌────┴────┐ │
│  │ModuleSvc │ │FlowSvc   │ │ShellSvc │ │
│  └──────────┘ └──────────┘ └─────────┘ │
│            Go Backend                   │
└─────────────────────────────────────────┘

Modules 页面：模块管理中心

Modules 页面是 pinable-desktop 的首要入口，展示所有已安装和可用的模块。页面顶部是搜索栏和筛选器，支持按名称、分类和状态过滤模块。主体区域以卡片网格形式展示每个模块，每张卡片包含模块图标、名称、版本号、简要描述和状态指示器。

核心功能包括：

  • 一键安装：点击模块卡片上的"安装"按钮，后台自动下载、验证完整性、注册到系统并激活。进度条实时显示下载和安装进度。
  • 模块详情：点击卡片展开详情面板，显示完整的模块描述、依赖关系、变更日志和配置选项。
  • 批量操作：支持多选模块进行批量启用、禁用或卸载操作。
  • 更新提示：当已安装模块有新版本可用时，卡片右上角会显示更新徽章。

Provider 页面：AI 后端配置

Provider 页面用于管理 AI 后端的连接配置。PinableAgents 支持多种 AI 后端，包括 OpenAI Codex、Anthropic Claude 和 Google Gemini。每个后端以独立的配置卡片呈现。

每张 Provider 卡片包含以下配置项：

配置项 说明 示例值
API 密钥 后端的身份验证密钥，以密文形式存储 sk-ant-***
默认模型 该后端使用的默认模型版本 claude-opus-4-6
API 端点 自定义 API 地址，适用于私有部署或代理 https://api.anthropic.com
请求超时 单次 API 请求的超时时间（秒） 120
重试次数 请求失败时的自动重试次数 3

页面底部提供"连接测试"按钮，点击后系统向后端发送一个轻量级请求以验证 API 密钥和网络连通性。测试结果以绿色（成功）或红色（失败）标记显示，失败时附带详细的错误信息。

Workflows 页面：工作流执行仪表盘

Workflows 页面是日常操作的核心界面。左侧是工作流选择面板，列出所有可用的工作流（如 do、omo、bmad 等），每个工作流旁边显示其包含的阶段数量和预估执行时间。

选择工作流后，右侧主区域显示任务输入表单和执行控制台。任务输入支持富文本编辑，可以粘贴需求文档、代码片段和参考链接。点击"执行"后，页面切换为实时执行视图，以时间轴形式展示每个阶段的执行进度：

  • 阶段指示器：每个阶段显示为一个圆形节点，颜色表示状态（灰色等待、蓝色执行中、绿色完成、红色失败）。
  • 实时日志：下方的日志面板实时流式输出当前阶段的智能体思考过程和操作记录。
  • 文件变更预览：右侧面板实时显示智能体修改的文件列表和 diff 预览。
  • 中断控制：随时可以暂停或终止正在执行的工作流。暂停后可以查看中间状态并决定是否继续。

Skills 页面：技能自动检测

Skills 页面展示系统自动检测到的开发环境能力。PinableAgents 在启动时和每次打开项目时，会自动扫描系统环境，识别可用的工具链和技能。

检测的技能分为三类：

  1. 语言运行时：Go、Node.js、Python、Rust、Java 等编程语言的安装状态和版本。
  2. 开发工具：Git、Docker、kubectl、terraform 等工具的可用性。
  3. 框架检测：基于项目文件自动识别使用的框架（React、Vue、Next.js、Gin 等）。

每个检测到的技能显示为一个状态卡片，包含版本号、安装路径和健康状态。智能体在执行任务时会参考这些技能信息来选择合适的工具和命令。

Config 页面：JSON 配置编辑器

Config 页面提供了一个功能完整的 JSON 编辑器，用于编辑 config.json 配置文件。编辑器基于 Monaco Editor（VS Code 的核心编辑器组件）构建，支持语法高亮、自动补全、错误检测和代码折叠。

编辑器的左侧显示完整的 JSON 内容，右侧是一个可视化的表单视图，两者保持双向同步。你可以选择自己习惯的编辑方式。配置项的自动补全基于内置的 JSON Schema，确保你输入的每个字段和值都是合法的。

页面顶部的工具栏提供以下操作：保存配置、重置为默认值、导入配置文件、导出当前配置。保存前会自动执行 Schema 验证，如果配置存在错误，会以红色波浪线标记具体位置并给出修复建议。

Logs 页面：执行历史记录

Logs 页面记录了所有工作流执行的完整历史。每条记录包含执行时间、工作流名称、任务描述、执行状态、耗时和变更文件数。支持按时间范围、状态和工作流类型进行筛选。

点击任一记录可以展开完整的执行详情，包括每个阶段的输入输出、智能体的推理过程、文件变更的完整 diff 以及测试执行结果。这些日志对于审计追踪和问题排查非常有价值。

// 日志记录的数据结构
{
  "id": "exec-20260225-143022",
  "workflow": "do",
  "task": "添加用户权限管理模块",
  "status": "completed",
  "started_at": "2026-02-25T14:30:22Z",
  "completed_at": "2026-02-25T14:35:47Z",
  "duration_ms": 325000,
  "phases": [
    { "name": "analyze", "status": "completed", "duration_ms": 45000 },
    { "name": "implement", "status": "completed", "duration_ms": 210000 },
    { "name": "review", "status": "completed", "duration_ms": 70000 }
  ],
  "files_changed": 7,
  "worktree": "pinable/do/20260225-143022"
}

Conversations 页面：会话浏览器

Conversations 页面展示与 AI 后端的所有对话历史。与 Logs 页面不同，Conversations 聚焦于消息级别的交互细节。你可以查看每次交互中发送给智能体的完整提示词、系统消息和智能体的响应内容。

会话浏览器支持全文搜索，方便你快速找到特定的对话内容。每个会话可以导出为 Markdown 格式，便于归档或分享。会话列表按时间倒序排列，最近的对话显示在最上方。

对于调试目的，你可以在 Conversations 中查看完整的 token 使用统计，包括输入 token 数、输出 token 数和总费用估算。这有助于优化提示词长度和控制 API 使用成本。

Terminal 页面：嵌入式终端

Terminal 页面内嵌了一个功能完整的终端模拟器，基于 xterm.js 实现。你无需离开 pinable-desktop 即可执行任意 shell 命令。终端自动继承当前项目的工作目录和环境变量配置。

Terminal 页面的特殊功能包括：

  • 命令补全：针对 PinableAgents CLI 命令提供智能补全建议。
  • 多标签页：支持同时打开多个终端标签页，每个标签页运行独立的 shell 会话。
  • 输出捕获：命令输出可以一键复制或发送到工作流的任务输入中。
  • 快捷执行：从 Logs 或 Workflows 页面可以直接跳转到 Terminal 执行相关命令。

IPC 通信机制

pinable-desktop 的前后端通过 Wails 的 IPC（进程间通信）机制进行交互。Wails 在构建时自动为 Go 后端暴露的方法生成 TypeScript 绑定代码，前端通过这些绑定以类型安全的方式调用后端服务。

// Go 后端定义服务方法
type ModuleService struct {}

func (s *ModuleService) ListModules() ([]Module, error) {
    return registry.GetAll()
}

func (s *ModuleService) InstallModule(name string) error {
    return registry.Install(name)
}

// React 前端调用（自动生成的绑定）
import { ListModules, InstallModule } from '../wailsjs/go/main/ModuleService';

const modules = await ListModules();
await InstallModule('do');

除了方法调用外，Wails 还支持事件驱动通信。Go 后端可以通过 runtime.EventsEmit 向前端推送实时事件，前端通过 runtime.EventsOn 注册监听器。这种机制用于工作流执行进度的实时推送、日志流式输出等场景。

键盘快捷键

pinable-desktop 提供了丰富的键盘快捷键以提高操作效率。

快捷键 macOS Windows 功能
页面切换 Cmd+1~8 Ctrl+1~8 切换到对应的页面标签
全局搜索 Cmd+K Ctrl+K 打开命令面板，快速执行操作
新建任务 Cmd+N Ctrl+N 在 Workflows 页面创建新任务
保存配置 Cmd+S Ctrl+S 在 Config 页面保存当前配置
新建终端 Cmd+T Ctrl+T 在 Terminal 页面打开新标签
切换终端 Cmd+Tab Ctrl+Tab 在终端标签页之间切换

按 Cmd+K（macOS）或 Ctrl+K（Windows）打开命令面板，输入关键词即可快速访问任何功能。命令面板支持模糊匹配。

系统托盘集成

pinable-desktop 支持最小化到系统托盘运行。关闭主窗口后，应用继续在后台运行，托盘图标提供快捷菜单：

  • 显示/隐藏窗口：双击托盘图标切换主窗口可见性。
  • 执行状态：托盘图标根据当前是否有运行中的任务变化颜色（绿色空闲、蓝色执行中、红色有错误）。
  • 快速操作：右键菜单提供"新建任务""打开日志""退出应用"等快捷选项。
  • 通知推送：当后台任务完成或失败时，系统会弹出原生通知提示用户。

自动更新机制

pinable-desktop 内置了自动更新功能。每次启动时以及每隔 24 小时，应用会向更新服务器检查是否有新版本可用。更新检查是非阻塞的，不会影响正常使用。

当检测到新版本时，应用会在界面顶部显示一个更新提示条，包含版本号和主要变更摘要。用户可以选择立即更新或稍后提醒。点击立即更新后，应用会在后台下载更新包，下载完成后提示重启以完成安装。

更新过程采用差量更新策略，只下载变化的文件部分，大幅减少下载量。所有更新包都经过数字签名验证，确保来源的可信性和完整性。

// 更新配置（config.json）
{
  "update": {
    "auto_check": true,
    "check_interval_hours": 24,
    "channel": "stable",
    "allow_prerelease": false
  }
}

更新通道分为 stable（稳定版）和 beta（测试版）。默认使用 stable 通道，如果你希望提前体验新功能，可以切换到 beta 通道，但需要承受潜在的稳定性风险。