项目定位与核心价值

frago 是一个跨平台桌面应用项目，通过 Tauri 框架将 Python 后端能力与现代化 Web 前端打包为单一可执行安装包，覆盖 macOS、Linux、Windows 三大主流操作系统。项目采用 pyproject.toml 作为 Python 端的元数据与依赖声明核心，资料来源：pyproject.toml:1-40；前端通过 src-tauri/package.json 管理 Node.js 侧依赖与构建脚本，资料来源：src-tauri/package.json:1-60。

应用发布形态包括 .dmg（macOS Apple Silicon / Intel）、.deb（Ubuntu/Debian）、.rpm（Fedora/RHEL）、.AppImage（通用 Linux）与 .msi（Windows），用户可直接下载对应平台的安装包完成部署，无需额外配置运行时环境，资料来源：README.md:1-120。

系统架构

frago 沿用 Tauri 的"前端 WebView + Rust 后端 + Python 脚本侧"三层架构。前端 UI 位于 src/ 目录，由 Tauri 容器在系统 WebView 中渲染；Rust 端位于 src-tauri/，负责窗口管理、系统调用与桥接 IPC；Python 端则由 src/frago/ 提供业务能力，并通过 pyproject.toml 描述其打包配置。资料来源：src-tauri/package.json:1-40、资料来源：pyproject.toml:1-40。

graph TD
    A[Web 前端 UI] -->|IPC| B[Rust Tauri 后端]
    B -->|子进程调用| C[Python 业务模块 frago]
    C --> D[扩展包 extension_bundle]
    C --> E[社区脚本 community-recipes]
    B --> F[系统 WebView 渲染]

目录结构与扩展机制

项目根目录下的关键模块划分清晰：

• src/frago/：Python 主代码目录，包含核心逻辑与资源。
• src/frago/_resources/extension_bundle/：扩展包目录，用于托管运行时所需的扩展资源；keys/README.md 进一步说明了扩展包中密钥与凭据文件的存放与引用方式，资料来源：src/frago/_resources/extension_bundle/README.md:1-40、资料来源：src/frago/_resources/extension_bundle/keys/README.md:1-40。
• community-recipes/：社区贡献的脚本与工作流示例集合，供用户复用与参考，资料来源：community-recipes/README.md:1-60。
• src-tauri/：Tauri 桌面容器配置与 Rust 后端代码。

扩展包机制允许第三方在不修改主程序的前提下注入新的功能资源；密钥目录独立于主代码存放敏感凭据，避免与普通资源混淆。

版本与发布节奏

项目版本号遵循语义化版本控制，自 v0.45.0 起持续迭代，经历 v0.46.0 → v0.48.1 → v0.49.1 等多个版本，并于 v1.0.0 达到首个主版本里程碑，目前最新发布为 v1.2.0，资料来源：README.md:1-120。在 Linux 通用 .AppImage 渠道下载后需执行 chmod +x 赋予可执行权限；macOS 用户首次打开应用时可能需要额外的安全确认步骤，资料来源：README.md:1-120。

发布周期密集、跨平台同步的节奏表明项目注重稳定性与多端一致性，开发者可在每次发布时同步获取 Linux、Windows 与 macOS 的对应安装包。

模块定位与总体职责

src-tauri/src/ 是 frago 桌面端的 Rust 后端源码根目录，基于 Tauri 框架承载应用的核心业务逻辑。该模块向上为前端（WebView）暴露 IPC 命令，向下通过 installer/ 子模块完成运行时依赖与子进程的部署与启动。

从 v1.0.0 起，frago 以打包好的桌面应用形式分发（.dmg、.deb、.rpm、.AppImage、.msi），因此 src-tauri/src 同时承担了"应用主程序"与"安装/启动 Claude Code 生态"两类职责。资料来源：src-tauri/src/commands.rs:1-40

src-tauri/src 主要由两大部分组成：

命令层（commands.rs）

commands.rs 是前后端交互的桥接层。Tauri 模式下的前端通过 invoke() 调用此处注册的 #[tauri::command] 函数，Rust 端在主线程或异步运行时中执行并回传结果。

该文件通常包含三类命令：

• 状态查询：返回当前安装状态、版本号、运行平台等元信息。
• 安装触发：接收前端"开始安装 Claude Code / frago 资源"的请求，调用 installer/ 下的子模块。
• 进程启动：通过 launcher 启动 Claude Code 进程并把 stdout/stderr 推送给前端事件总线。

由于命令名直接暴露给前端，建议保持稳定的签名；任何破坏性变更需要同步更新前端的 IPC 调用点。资料来源：src-tauri/src/commands.rs:1-80

常量层（constants.rs）

constants.rs 集中管理以下内容：

• 远端下载地址（GitHub release URL、CDN 路径）。
• 平台/架构标识（如 aarch64-apple-darwin、x86_64-unknown-linux-gnu）。
• 安装路径默认值（~/.frago、~/.local/bin 等）。
• IPC 事件名、Tauri State 键名。

集中常量有助于在多平台打包时只在一处切换 URL 与路径，避免散落在各业务模块中造成漂移。资料来源：src-tauri/src/constants.rs:1-60

安装器子模块（installer/）

installer/ 是 src 中体积最大、职责最具体的子目录，承载了 frago 桌面应用区别于普通 Tauri 项目的核心能力。

claude_code.rs — Claude Code 部署

负责检测本地是否已存在 Claude Code，必要时下载、解压并写入 PATH。该模块的输出会被 commands.rs 用于在 UI 上展示"已安装/未安装"徽标。资料来源：src-tauri/src/installer/claude_code.rs:1-120

frago.rs — frago 自部署

与 claude_code.rs 对称，但目标是 frago 自身的 CLI/二进制更新。常见模式是从当前运行的 release 拉取最新构件并替换旧文件，从而支持"应用内升级"。资料来源：src-tauri/src/installer/frago.rs:1-100

downloader.rs — 下载抽象

封装 HTTP 下载、进度回调、校验（SHA256/etag）等通用逻辑，被 claude_code.rs 与 frago.rs 复用，避免重复实现流式写入与重试。资料来源：src-tauri/src/installer/downloader.rs:1-150

launcher.rs — 进程拉起

负责启动 Claude Code 子进程并管理其生命周期。典型职责包括：

• 设置子进程工作目录与环境变量。
• 异步读取 stdout/stderr，通过 Tauri emit 推送给前端。
• 在用户关闭主窗口时优雅终止子进程。

资料来源：src-tauri/src/installer/launcher.rs:1-140

数据流概览

flowchart LR
    UI[前端 WebView] -->|invoke| CMD[commands.rs]
    CMD --> CC[installer/claude_code.rs]
    CMD --> FR[installer/frago.rs]
    CC --> DL[installer/downloader.rs]
    FR --> DL
    CMD --> LH[installer/launcher.rs]
    LH -->|emit 事件| UI
    DL -->|进度回调| CMD

命令层是唯一对外入口；安装器子模块之间通过 downloader 解耦下载细节，由 launcher 统一负责子进程生命周期。资料来源：src-tauri/src/commands.rs:1-40、src-tauri/src/installer/launcher.rs:1-140

社区与版本相关说明

frago 从 v0.45.0 起持续在 macOS（Apple Silicon / Intel）、Linux（.deb、.rpm、.AppImage）、Windows（.msi）上发布，每个 release 页面均提供对应的安装包矩阵，说明 src-tauri/src 中多平台分支逻辑确实在生产环境中被频繁触达。最新稳定版 v1.2.0 与 v1.0.0、v1.1.0 共享同一套安装包布局，意味着该模块的架构在 v1.x 系列中保持稳定。资料来源：frago v1.2.0 release

模块概述与角色

api 模块位于 frago 桌面客户端的前端工程内（src/frago/client/src/api/），负责在基于 Web 技术栈的前端与 Python 后端之间建立统一的调用通道。该模块对外屏蔽底层传输差异，使上层 UI 组件、状态管理与业务逻辑可以通过一致的接口调用后端能力，而无需关心实际通信介质。

从目录组成可以判断，api 模块采用了传输层可插拔的设计：将传输实现与上层 API 调用分离。client.ts 定义抽象契约，websocket.ts 与 pywebview.ts 分别提供两种具体传输实现，index.ts 负责聚合导出，对外暴露统一入口。资料来源：src/frago/client/src/api/index.ts:1-1

这一设计使得 frago 既能在打包为 PyWebview 桌面应用时直接走本地桥接通道，又能在需要远程调试或独立部署时切换到 WebSocket 通道，而调用方代码无需修改。

传输层架构

api 模块的核心是传输抽象。client.ts 中定义了上层调用方依赖的接口契约，包括方法调用、事件订阅、连接生命周期等通用能力；具体传输协议由子类或工厂函数注入。资料来源：src/frago/client/src/api/client.ts:1-1

flowchart LR
    UI[前端 UI/Store] --> Client[client.ts<br/>抽象客户端]
    Client -->|运行时选择| WS[websocket.ts]
    Client -->|运行时选择| PY[pywebview.ts]
    WS -->|TCP/WS| Backend[Python 后端服务]
    PY -->|window.pywebview.api| Backend

模块通过环境或构建配置决定使用哪一条传输路径，从而在开发、调试、打包分发等不同场景中自动适配。

WebSocket 传输实现

websocket.ts 实现基于浏览器原生 WebSocket 协议的传输方式。调用方发起请求时，客户端将方法名与参数封装为消息帧，通过 WebSocket 发送到 Python 后端的 WS 服务端；后端处理完成后返回响应帧，客户端再解析为 Promise 结果。资料来源：src/frago/client/src/api/websocket.ts:1-1

该实现通常具备以下能力：

• 异步请求/响应关联：通过消息 ID 或自增计数器区分并发请求。
• 重连与心跳：在网络波动时维持会话稳定。
• 事件推送：后端可通过同一通道向前端广播通知，前端通过订阅 API 接收。

WebSocket 通道适合需要后端独立运行、跨网络访问或前后端解耦调试的场景。

pywebview 传输实现

pywebview.ts 利用 pywebview 提供的 window.pywebview.api 桥接对象，让前端直接调用 Python 中通过 @webview.api 暴露的同步/异步方法。相比 WebSocket，这种方式不需要额外的网络层，消息直接在进程内传递，开销更低、延迟更小。资料来源：src/frago/client/src/api/pywebview.ts:1-1

由于 pywebview 在打包后的桌面应用中作为首选运行时，pywebview.ts 通常也是默认或推荐传输实现。它将 Python 方法包装为返回 Promise 的 JS 函数，并向上层提供与 client.ts 抽象一致的接口形态，从而保证切换传输层时业务代码无感知。

模块入口与导出

index.ts 作为模块的对外入口，集中导出抽象客户端、传输实现以及工厂函数（例如 createClient()）。上层模块仅需从 @/api 或相对路径导入统一入口，而无需直接依赖具体传输文件，便于后续扩展新的传输方式（例如未来可能加入的 IPC 或 gRPC-Web）。资料来源：src/frago/client/src/api/index.ts:1-1

使用模式与最佳实践

• 保持调用层无感知：业务代码应仅依赖抽象客户端接口，而非直接引用 websocket.ts 或 pywebview.ts。
• 统一错误处理：在抽象层捕获并规范化传输错误（如网络断开、方法未注册、超时），向上抛出统一错误类型。
• 关注连接生命周期：WebSocket 通道需要处理重连；pywebview 通道需关注 Python 端 API 的注册时机，避免在桥接对象未就绪前调用。
• 利用事件通道：对于后端主动推送的状态变化（进度、日志、通知），应使用订阅 API 而非轮询，以降低延迟与开销。

总结

api 模块是 frago 客户端前后端通信的中枢。它通过抽象客户端契约与可插拔传输实现，解耦了上层业务与底层通信细节，使同一套前端代码既能运行在本地 PyWebview 桌面壳内，也能通过 WebSocket 与独立部署的 Python 后端协作。这一架构在保持调用一致性的同时，为开发调试、远程使用与打包分发提供了灵活的适配空间。

模块定位与职责

Capabilities（能力声明）是 Tauri 2.x 安全模型的核心配置文件，位于 src-tauri/capabilities/ 目录中，用于以静态、显式的方式声明前端 WebView 允许调用的后端命令、窗口对象和权限集合。Frago 作为 Tauri 桌面应用，在 src-tauri/capabilities/default.json 中对所有 Tauri 内置 capability（如 core:default、core:event、core:window 等）以及自定义命令能力进行了集中声明，从而避免在 Rust 源码中散落权限开关。资料来源：src-tauri/capabilities/default.json:1-60。

在 Tauri 2.x 中，"capability" 取代了旧版的 allowlist 机制，每一个 capability 文件都对应一组可被特定窗口（通过 windows 字段匹配窗口 label 或 webview label）激活的权限集合，并由 tauri.conf.json 中的 app.security.capabilities 数组统一引用。资料来源：src-tauri/tauri.conf.json:1-120。

文件结构与关键字段

default.json 顶层一般包含三个关键字段：$schema、identifier 和 windows/permissions。其典型结构如下表所示：

资料来源：src-tauri/capabilities/default.json:1-40。

权限条目按作用域可划分为：core:*（Tauri 内置核心 API）、插件命名空间（如 dialog:allow-open、fs:allow-read-text-file）、以及项目自定义命令前缀。Frago 在 default.json 中通常启用 core:default 以获得窗口、事件、应用生命周期等基础能力。资料来源：src-tauri/capabilities/default.json:10-50。

与 Rust 侧命令的联动

Capabilities 文件仅做"声明"，真正的命令实现与权限边界由 Rust 侧命令宏 #[tauri::command] 以及插件注册共同决定。Frago 的命令注册入口位于 src-tauri/src/lib.rs 的 #[cfg_attr(mobile, tauri::mobile_entry_point)] pub fn run() { … }，其中通过 .invoke_handler(tauri::generate_handler![…]) 列出可被前端调用命令的 Rust 函数名。只有当某条 command 在 capability 的 permissions 中以 "allow-*" 形式显式允许时，前端 invoke() 调用才能成功。资料来源：src-tauri/src/lib.rs:1-120。

应用启动时 src-tauri/src/main.rs 负责调用 frago_lib::run()，Rust 进程根据已加载的 capability 列表对 IPC 消息做白名单校验；任何未在 capability 中声明的调用都会被 Tauri 运行时拒绝并抛出 NotAllowed。资料来源：src-tauri/src/main.rs:1-40。

前端调用约定与版本依赖

前端通过 @tauri-apps/api（版本见 package.json 的 dependencies 段）发起 invoke('plugin:name|command', args) 调用，调用前需要确保对应 core:* 或插件能力已在 capability 中放行。Frago 默认采用 core:default 与若干常用插件能力组合，从而在保持最小特权的前提下支持窗口控制、文件系统读写、对话框等常见操作。资料来源：package.json:1-60。

Tauri 与插件版本由 src-tauri/Cargo.toml 的 [dependencies] 段统一约束，tauri = "2"、tauri-plugin-* 的版本必须与 package.json 中 @tauri-apps/* 主版本一致，否则 capability 校验可能因 ABI 不匹配而失败。资料来源：src-tauri/Cargo.toml:1-80。

安全模型小结

flowchart LR
    A[前端 WebView] -->|invoke| B(Tauri IPC)
    B --> C{capability 校验}
    C -->|允许| D[Rust command handler]
    C -->|拒绝| E[抛出 NotAllowed]
    D --> F[业务逻辑/插件]
    style C fill:#fef3c7,stroke:#92400e

Frago 的安全边界落在"窗口 ↔ capability ↔ Rust 命令"三层：只有当窗口 label 命中 capability 的 windows、且所请求命令被 permissions 列入允许列表，并且 Rust 侧确实注册了该命令时，一次 invoke 调用才会被执行。这种"声明-校验-执行"的三段式模型，使 Frago 可以在不修改 Rust 代码的前提下，通过新增或裁剪 capability JSON 来调整前端能力面，方便在打包发布到 macOS / Windows / Linux（.dmg / .msi / .deb / .rpm / .AppImage，见 v1.2.0 Release）时按需收紧或放开权限。资料来源：src-tauri/tauri.conf.json:1-120、src-tauri/capabilities/default.json:1-60。

Pitfall Log / 踩坑日志

项目：tsaijamey/frago

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/tsaijamey/frago | host_targets=claude, openclaw, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/tsaijamey/frago | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/tsaijamey/frago | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/tsaijamey/frago | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/tsaijamey/frago | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/tsaijamey/frago | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/tsaijamey/frago | release_recency=unknown