GenericAgent Documentation

Technical Documentation: lsdefine/GenericAgent

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

📌 Official: GitHub + https://gaagent.ai only. DintalClaw is the sole authorized commercial partner; others are not affiliated.

🌟 Overview Copy Chapter

GenericAgent is a minimal, self-evolving autonomous agent framework. Its core is just ~3K lines of code. Through 9 atomic tools + a ~100-line Agent Loop, it grants any LLM system-level control over a local computer — covering browser, terminal, filesystem, keyboard/mouse input, screen vision, and mobile devices (ADB).

Design philosophy — don't preload skills, evolve them.

Every time GenericAgent solves a new task, it automatically crystallizes the execution path into a reusable Skill. The longer you use it, the more skills accumulate — forming a personal skill tree grown entirely from 3K lines of seed code.

🤖 Self-Bootstrap Proof — Everything in this repository, from installing Git and running git init to every commit message, was completed autonomously by GenericAgent. The author never opened a terminal once.

📑 Table of Contents Copy Section

• Key Features
• Demo Showcase
• Quick Start
• Usage
• Unlocking Advanced Capabilities
• Architecture
• Self-Evolution Mechanism
• Comparison
• Evaluation
• Roadmap & News
• Community & Support
• License

📋 Key Features Copy Chapter

🎯 Demo Showcase Copy Chapter

🚀 Quick Start Copy Chapter

⚠️ Python version: use Python 3.11 or 3.12. Do not use Python 3.14 — it is incompatible with pywebview and a few other GA dependencies.

📖 Detailed installation guide: installation.md · installation_zh.md（中文）

For LLM Agents Copy Section

Fetch the installation guide and follow it:

curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md

For Humans Copy Section

Method 1 — Clone & install *(recommended)*

git clone https://github.com/lsdefine/GenericAgent.git && cd GenericAgent
uv venv && uv pip install -e ".[ui]"
cp mykey_template_en.py mykey.py   # fill in your LLM API key

Dependencies are deliberately tiered: the agent core needs only requests, plus four lightweight packages (beautifulsoup4, bottle, simple-websocket-server, aiohttp) for TMWebdriver's local server. The [ui] extra pulls in frontend libraries (Streamlit, prompt_toolkit/rich for the TUI, …) — install it for the bundled UIs, or skip it entirely and drive the agent headless. No Playwright, no LangChain, no browser binaries to download.

Then launch:

python frontends/tui_v3.py   # Terminal UI (recommended)
python launch.pyw            # Streamlit web UI

Method 2 — One-line installer *(convenience)*

Sets up a self-contained directory with an isolated Python environment, Git, and a ready-to-run package. The script is in assets/ if you'd like to read it first.

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga_install.ps1 | iex"

Linux / macOS

GLOBAL=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga_install.sh)"

💡 GenericAgent grows its environment through the Agent itself — don't pre-install everything. See Unlocking Advanced Capabilities below.

💻 Usage Copy Chapter

Frontends Copy Section

Terminal UI *(recommended)*

A lightweight, scrollback-first terminal interface built on prompt_toolkit + rich. Supports multiple concurrent sessions and real-time streaming.

python frontends/tui_v3.py

⚠️ Windows TUI Troubleshooting

TUI rendering on Windows can be flaky depending on terminal + font. Common causes:

1. prompt_toolkit / rich are not on the latest version — pip install -U prompt_toolkit rich first.
2. PowerShell / cmd ship with terminals that have rough Unicode + key-binding support. Prefer Git Bash on Windows, which is much better behaved.
3. If it still looks broken, ask GA itself to fix it:

   "My experience using frontends/tui_v3.py in PowerShell / cmd / Git Bash on Windows is very poor — lots of incompatibility. Please refer to Claude Code's best practices for the Windows terminal and fix all font and rendering incompatibilities."

Streamlit UI

python launch.pyw

Bot Interface (IM) Copy Section

GenericAgent also supports IM frontends such as Telegram, Discord, and Lark.

WeChat, QQ, WeCom and DingTalk are also supported — see the Chinese section below.
For detailed setup, ask GenericAgent itself.

🔓 Unlocking Advanced Capabilities Copy Chapter

In GA, advanced capabilities are unlocked by instructing the agent, not by reading
docs or installing extras. Each instruction below makes GA read its pre-installed SOPs
(battle-tested playbooks in its memory), install whatever is missing, adapt to your OS,
and persist the result into its own memory.

💡 About language: the pre-installed SOPs are written in Chinese — GA reads them
natively, so this never blocks you. If you prefer an English knowledge base, just say:
"Read your pre-installed SOPs and rewrite them in English (keep code, paths and error
strings verbatim)."

🌍 About platforms: the SOPs were honed on Windows, but cross-platform adaptation is
itself a GA task — on macOS/Linux, GA swaps in the platform equivalents (window
enumeration, input control, screenshots) on its own. Same self-evolution principle.

🧠 Architecture Copy Chapter

GenericAgent accomplishes complex tasks through Layered Memory × Minimal Toolset × Autonomous Execution Loop, continuously accumulating experience during execution.

1️⃣ Layered Memory System Copy Section

Memory crystallizes throughout task execution, letting the agent build stable, efficient working patterns over time.

2️⃣ Autonomous Execution Loop Copy Section

Perceive environment state → Task reasoning → Execute tools → Write experience to memory → Loop

The entire core loop is just ~100 lines of code (agent_loop.py).

3️⃣ Minimal Toolset Copy Section

GenericAgent provides only 9 atomic tools, forming the foundational capabilities for interacting with the outside world.

4️⃣ Capability Extension Copy Section

Capable of dynamically creating new tools.

Via code_run, GenericAgent can dynamically install Python packages, write new scripts, call external APIs, or control hardware at runtime — crystallizing temporary abilities into permanent tools.

🧬 Self-Evolution Mechanism Copy Chapter

This is what fundamentally distinguishes GenericAgent from every other agent framework.

[New Task]
   │
   ▼
[Autonomous Exploration]   ─►  install deps · write scripts · debug · verify
   │
   ▼
[Crystallize into Skill]   ─►  write to memory layer
   │
   ▼
[Direct Recall on Next Similar Task]

After a few weeks, your agent instance will have a skill tree no one else in the world has — all grown from 3K lines of seed code.

📊 Comparison Copy Chapter

📈 Evaluation Copy Chapter

📂 Full evaluation datasets and results: JinyiHan99/GA-Technical-Report

We evaluate GenericAgent across five dimensions:

Baselines across these dimensions include Claude Code, OpenAI CodeX, and OpenClaw, evaluated under Claude Sonnet 4.6, Claude Opus 4.6, GPT-5.4, and MiniMax M2.7 backbones.

Browser Realness of GA Web Tools (TMWebdriver) Copy Section

GA web tools are powered by TMWebdriver — a local WebSocket server plus a Chrome extension — running through a real, persistent Chrome/Chromium session rather than a disposable headless sandbox, preserving cookies, login state, extensions, GPU/WebGL behavior, and normal browser-session fingerprints.

For reCAPTCHA v3, 0.9 is not a "checkbox solved" result; it is the high-confidence human-like score returned by the risk model, typically sufficient to avoid extra challenges in production flows.

📅 Roadmap & News Copy Chapter

• 2026-05-23 — 🆕 TUI v3 released (frontends/tui_v3.py). Block-based scrollback with proper resize reflow, per-terminal color profile for cross-terminal parity, and feature parity with v2.
• 2026-05-18 — 🆕 Morphling mode. Project-level skill absorption — extract goal + tests from any external repo, then decide per component: call, rewrite, or discard. See memory/morphling_sop.md.
• 2026-05-17 — 🆕 Goal Hive mode. Multi-worker cooperative Goal mode — BBS-coordinated master/workers running long-horizon objectives in parallel. See memory/goal_hive_sop.md.
• 2026-05-15 — 🖥️ Desktop GUI released. One-line installs ship a ready-to-run desktop app (frontends/GenericAgent.exe). Developers launch via python launch.pyw.
• 2026-05-14 — 🆕 Conductor sub-agent orchestration. Spawn, supervise, and auto-clean parallel sub-agents; first-class delegation primitives complementing /btw side-questions.
• 2026-05-12 — 🆕 TUI v2 released (frontends/tuiapp_v2.py). Refined Textual frontend with image-paste folding, file paste, block-delete, Ctrl+C copy, history navigation, and /llm / /export / /continue pickers.
• 2026-05-08 — 🆕 Goal mode (reflect/goal_mode.py). Time-budget-driven self-driven loop — "keep optimizing X for N hours" with no premature delivery.
• 2026-04-21 — 📄 Technical Report on arXiv — GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization.
• 2026-04-11 — Introduced L4 session archive memory and scheduler cron integration.
• 2026-03-23 — Personal WeChat supported as a bot frontend.
• 2026-03-10 — Released million-scale Skill Library (Chinese).
• 2026-03-08 — Released "Dintal Claw" — a GenericAgent-powered government-affairs bot (Chinese).
• 2026-03-01 — Featured by Jiqizhixin (机器之心) (Chinese).
• 2026-01-16 — GenericAgent V1.0 public release.

⭐ Community & Support Copy Chapter

If this project helped you, please consider leaving a Star! 🙏

🚩 Friendly Links Copy Section

Thanks to the LinuxDo community for the support!

Community GUIs (independent open-source projects):

• chilishark27/ga-manager
• wangjc683/galley — Out-of-the-box local agent workbench with a bundled GA runtime (CPython 3.11 + deps), native GUI/CLI, multi-session + Project orchestration, local-first.
• FroStorM/A3Agent
• Fwind43/GenericAgent-Admin — Go + React desktop admin panel: service lifecycle management, native chat, Goal mode, BBS team board, file editor, model config wizard, TMWebDriver monitor, self-update, and Windows tray/desktop-pet integration.

📄 License Copy Chapter

Distributed under the MIT License. See LICENSE for full text.

Disclaimer: The official GenericAgent channels are this GitHub repository and https://gaagent.ai. DintalClaw is currently the only officially authorized commercial partner; any other third-party website, organization, or individual using the GenericAgent name is not official unless explicitly listed here.

🌟 项目简介 Copy Chapter

GenericAgent 是一个极简、可自我进化的自主 Agent 框架。核心仅 ~3K 行代码，通过 9 个原子工具 + ~100 行 Agent Loop，赋予任意 LLM 对本地计算机的系统级控制能力，覆盖浏览器、终端、文件系统、键鼠输入、屏幕视觉及移动设备（ADB）。

设计哲学 —— 不预设技能，靠进化获得能力。

每解决一个新任务，GenericAgent 就将执行路径自动固化为 Skill，供后续直接调用。使用时间越长，沉淀的技能越多，形成一棵完全属于你、从 3K 行种子代码生长出来的专属技能树。

🤖 自举实证 — 本仓库的一切，从安装 Git、git init 到每一条 commit message，均由 GenericAgent 自主完成。作者全程未打开过一次终端。

📑 目录 Copy Section

• 核心特性
• 实例展示
• 快速开始
• 使用方式
• 架构设计
• 自我进化机制
• 与同类产品对比
• 评测
• 路线图与最新动态
• 社区与支持
• 许可

📋 核心特性 Copy Chapter

🎯 实例展示 Copy Chapter

🚀 快速开始 Copy Chapter

⚠️ Python 版本： 推荐使用 Python 3.11 或 3.12。请不要使用 Python 3.14，与 pywebview 及部分依赖不兼容。

📖 详细安装指南：installation_zh.md（中文） · installation.md (English)

给 LLM Agent 看的 Copy Section

获取安装指南并照做：

curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation_zh.md

给人类用户看的 Copy Section

方法一 — 一键安装 *（推荐）*

一键安装会自动准备独立 Python 环境、Git、项目文件和桌面端，不污染系统环境。

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

curl -fsSL http://fudankw.cn:9000/files/ga_install.sh | bash

安装完成后启动：

• Windows — 双击 frontends/GenericAgent.exe
• Linux / macOS — 在安装目录运行 python launch.pyw

方法二 — Python 安装 *（开发者）*

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"          # 核心 + UI 依赖
cp mykey_template.py mykey.py      # 填入你的 LLM API Key
python launch.pyw

💡 GenericAgent 更推荐由 Agent 在使用中自举环境，而不是预先手动装完整依赖。

📖 完整引导流程见 docs/GETTING_STARTED.md
📖 新手图文版：飞书文档
📘 完整入门教程（Datawhale 出品）：Hello GenericAgent · GitHub

💻 使用方式 Copy Chapter

前端启动 Copy Section

桌面端

一键安装自带桌面端（Windows），双击：

frontends/GenericAgent.exe

终端 UI

基于 Textual 的轻量键盘驱动界面。支持多会话并发、实时流式输出，有终端就能跑。

python frontends/tuiapp_v2.py

⚠️ Windows 上 TUI 显示异常的排查思路

1. textual 版本太旧，先 pip install -U textual；
2. PowerShell / cmd 自带终端对 Unicode 和键位的支持比较糟糕，Windows 上推荐用 Git Bash，体验明显更稳；
3. 仍然显示异常时，可以让 GA 自己修一遍，参考 Prompt：

   "我在 Windows 的 PowerShell / cmd / Git Bash 中使用 frontends/tuiapp_v2.py 体验非常差，出现了一堆不兼容问题。请参考 Claude Code 在 Windows 终端的最佳配置，把所有字体和显示不兼容的问题修一遍。"

Streamlit UI

python launch.pyw

Bot 接口（IM） Copy Section

GenericAgent 支持 Telegram、Discord、微信、QQ、飞书 / Lark、企业微信、钉钉等 IM 前端。

详细配置直接问 GenericAgent。

🧠 架构设计 Copy Chapter

GenericAgent 通过 分层记忆 × 最小工具集 × 自主执行循环 完成复杂任务，并在执行过程中持续积累经验。

1️⃣ 分层记忆系统 Copy Section

记忆在任务执行过程中持续沉淀，使 Agent 逐步形成稳定且高效的工作方式。

2️⃣ 自主执行循环 Copy Section

感知环境状态 → 任务推理 → 调用工具执行 → 经验写入记忆 → 循环

整个核心循环仅 约百行代码（agent_loop.py）。

3️⃣ 最小工具集 Copy Section

GenericAgent 仅提供 9 个原子工具，构成与外部世界交互的基础能力。

4️⃣ 能力扩展机制 Copy Section

具备动态创建新工具的能力。

通过 code_run，GenericAgent 可在运行时动态安装 Python 包、编写新脚本、调用外部 API 或控制硬件，将临时能力固化为永久工具。

🧬 自我进化机制 Copy Chapter

这是 GenericAgent 区别于其他 Agent 框架的根本所在。

[遇到新任务]
    │
    ▼
[自主摸索]   ─►  安装依赖 · 编写脚本 · 调试验证
    │
    ▼
[执行路径固化为 Skill]   ─►  写入记忆层
    │
    ▼
[下次同类任务直接调用]

用几周后，你的 Agent 实例将拥有一套任何人都没有的专属技能树，全部从 3K 行种子代码中生长而来。

📊 与同类产品对比 Copy Chapter

📈 评测 Copy Chapter

📂 完整的评测数据集以及评测结果见：JinyiHan99/GA-Technical-Report

我们从 五大维度 评测 GenericAgent：

以上维度的基线包括 Claude Code、OpenAI CodeX 和 OpenClaw，分别在 Claude Sonnet 4.6、Claude Opus 4.6、GPT-5.4 和 MiniMax M2.7 底座上进行评测。

GA Web 工具的浏览器真实性 Copy Section

GA Web 工具运行在真实、持久化的 Chrome/Chromium 会话中，而不是一次性的 headless 沙箱，因此可以保留 Cookie、登录态、扩展、GPU/WebGL 行为以及正常浏览器会话指纹。

对于 reCAPTCHA v3，0.9 不是“点过验证码”的结果，而是风控模型返回的高置信真人相似分，通常足以通过生产环境中的常见阈值，避免进入更严格挑战。

📅 路线图与最新动态 Copy Chapter

• 2026-05-23 — 🆕 TUI v3 正式发布（frontends/tui_v3.py）。基于块的滚屏回看 + 正确的 resize 重排，每终端独立配色保证跨终端一致，并与 v2 达成功能对齐。
• 2026-05-18 — 🆕 Morphling 模式。项目级能力吞噬 —— 从任意外部仓库抽取目标与测例后，对每个核心组件分别决定调用、重写或舍弃。详见 memory/morphling_sop.md。
• 2026-05-17 — 🆕 Goal Hive 模式。多 worker 协作版 Goal —— Master/Worker 通过 BBS 协同推进长程目标。详见 memory/goal_hive_sop.md。
• 2026-05-15 — 🖥️ 桌面 GUI 发布。一键安装会自带可直接运行的桌面端（frontends/GenericAgent.exe），开发者也可用 python launch.pyw 启动。
• 2026-05-14 — 🆕 Conductor 子 Agent 编排。派发、监督、自动清理并行子 Agent；与 /btw 旁路子 Agent 互补，提供一等公民级的任务委派原语。
• 2026-05-12 — 🆕 TUI v2 正式发布（frontends/tuiapp_v2.py）。重做视觉风格的 Textual 前端，支持图片粘贴折叠、文件粘贴、块删除、Ctrl+C 复制、历史导航，以及 /llm / /export / /continue 选择器。
• 2026-05-08 — 🆕 Goal 模式（reflect/goal_mode.py）。时间预算驱动的自驱循环 —— "持续优化 X N 小时"，预算没到不准提前交付。
• 2026-04-21 — 📄 技术报告已发布至 arXiv — GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization。
• 2026-04-11 — 引入 L4 会话归档记忆，并接入 scheduler cron 调度。
• 2026-03-23 — 支持个人微信接入作为 Bot 前端。
• 2026-03-10 — 发布百万级 Skill 库。
• 2026-03-08 — 发布以 GenericAgent 为核心的"政务龙虾" Dintal Claw。
• 2026-03-01 — 被机器之心报道。
• 2026-01-16 — GenericAgent V1.0 公开版本发布。

⭐ 社区与支持 Copy Chapter

如果这个项目对你有帮助，欢迎点一个 Star! 🙏

也欢迎加入 GenericAgent 体验交流群，一起交流、反馈、共建 👏

🚩 友情链接 Copy Section

感谢 LinuxDo 社区的支持！

社区 GUI 客户端 （独立开源项目）：

• chilishark27/ga-manager
• wangjc683/galley —— 开箱即用的本地 Agent 工作台，自带 GA 内核（内置 CPython 3.11 + 运行依赖），GUI/CLI 双原生、多 session + Project 编排、本地优先。
• FroStorM/A3Agent
• Fwind43/GenericAgent-Admin —— Go + React 桌面管理面板：服务生命周期管理、原生 Chat、Goal 模式、BBS 团队看板、文件编辑器、模型配置向导、TMWebDriver 监控、自更新，以及 Windows 托盘/桌面宠物集成。

📄 许可 Copy Chapter

基于 MIT License 发布，详见 LICENSE。

声明：GenericAgent 官方渠道为本 GitHub 仓库和 https://gaagent.ai。DintalClaw 是目前唯一官方授权的商业合作方；除非在此处明确列出，其他使用 GenericAgent 名义的第三方网站、机构、组织或个人均非官方。

Overview (`frontends/DESKTOP_PET_README.md`) Copy Section

Desktop Pet Skin System

快速开始 Copy Chapter

运行桌面宠物：

python3 desktop_pet_v2.pyw

功能特性 Copy Chapter

1. 多皮肤支持 Copy Section

• 自动发现 skins/ 目录下的所有皮肤
• 右键菜单切换皮肤
• 支持 sprite sheet 和 GIF 两种格式

2. 多动画状态 Copy Section

• idle - 待机动画
• walk - 行走动画
• run - 跑步动画
• sprint - 冲刺动画

右键菜单可切换动画状态

3. 交互功能 Copy Section

• 单击 - 拖动宠物
• 双击 - 关闭程序
• 右键 - 打开菜单（切换皮肤/动画）

4. HTTP 远程控制 Copy Section

# 显示消息
curl "http://127.0.0.1:51983/?msg=Hello"

# 切换动画状态
curl "http://127.0.0.1:51983/?state=run"

# POST 消息
curl -X POST -d "任务完成" http://127.0.0.1:51983/

添加新皮肤 Copy Chapter

目录结构 Copy Section

skins/
└── your-skin-name/
    ├── skin.json       # 配置文件（必需）
    ├── idle.png        # 动画资源
    ├── walk.png
    ├── run.png
    └── sprint.png

skin.json 配置示例 Copy Section

Sprite Sheet 格式（推荐）

{
  "name": "My Pet",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "描述",
  "format": "sprite",
  "animations": {
    "idle": {
      "file": "idle.png",
      "loop": true,
      "sprite": {
        "frameWidth": 44,
        "frameHeight": 31,
        "frameCount": 6,
        "columns": 6,
        "fps": 6,
        "startFrame": 0
      }
    },
    "walk": {
      "file": "walk.png",
      "loop": true,
      "sprite": {
        "frameWidth": 65,
        "frameHeight": 32,
        "frameCount": 8,
        "columns": 8,
        "fps": 8,
        "startFrame": 0
      }
    }
  }
}

GIF 格式

{
  "name": "My Pet",
  "format": "gif",
  "animations": {
    "idle": {
      "file": "idle.gif",
      "loop": true
    },
    "walk": {
      "file": "walk.gif",
      "loop": true
    }
  }
}

配置说明 Copy Section

• frameWidth/frameHeight: 单帧尺寸（像素）
• frameCount: 帧数
• columns: sprite sheet 的列数
• fps: 播放帧率
• startFrame: 起始帧索引（从 0 开始）

Sprite Sheet 布局 Copy Section

+-------+-------+-------+-------+
| 帧0   | 帧1   | 帧2   | 帧3   |  ← 第一行
+-------+-------+-------+-------+
| 帧4   | 帧5   | 帧6   | 帧7   |  ← 第二行
+-------+-------+-------+-------+

如果 columns=4, startFrame=2, frameCount=3，则读取：帧2, 帧3, 帧4

已包含的皮肤 Copy Chapter

1. Glube - 像素风小怪兽（多文件 sprite）
2. Vita - 像素风小恐龙（单文件 sprite）
3. Doux - 像素风小恐龙（单文件 sprite）

从 ai-bubu 导入更多皮肤 Copy Chapter

ai-bubu 项目包含更多皮肤资源，可以直接复制：

# 复制皮肤
cp -r ai-bubu-main/packages/app/public/skins/boy frontends/skins/
cp -r ai-bubu-main/packages/app/public/skins/dinosaur frontends/skins/
cp -r ai-bubu-main/packages/app/public/skins/line frontends/skins/
cp -r ai-bubu-main/packages/app/public/skins/mort frontends/skins/
cp -r ai-bubu-main/packages/app/public/skins/tard frontends/skins/

与 stapp.py 集成 Copy Chapter

在 stapp.py 中点击"🐱 桌面宠物"按钮会自动启动桌面宠物，并在每个 turn 结束时发送通知。

故障排查 Copy Chapter

皮肤不显示 Copy Section

1. 检查 skin.json 格式是否正确
2. 确认图片文件存在
3. 检查 sprite 配置参数是否匹配图片尺寸

动画不流畅 Copy Section

• 调整 fps 参数
• 检查帧数是否正确

透明背景问题 Copy Section

• 确保 PNG 文件包含 alpha 通道
• 使用 RGBA 模式的图片

技术细节 Copy Chapter

• 基于 Tkinter + PIL/Pillow
• 支持透明背景（#01FF01 色键）
• 窗口置顶、无边框
• HTTP 服务器端口：51983

Overview (`frontends/desktop/packaging/README.md`) Copy Section

Desktop packaging

This directory contains the scripts and locked Python inputs used to assemble GenericAgent Desktop packages.
The directory is not copied wholesale into a release; the workflow selects only the platform scripts and
requirements files required by each package.

Submitted renderer boundary Copy Chapter

Official upstream package jobs consume the tracked frontends/desktop/dist/** renderer directly. They install
only the minimal submitted Tauri CLI manifest and do not run Vite, TypeScript, React tests, or any other renderer
source command. Tauri embeds dist/** in the native application. The portable runtime/app copy deliberately
excludes dist/** so the same renderer is not duplicated as loose runtime data.

The React source, issue tracker, and contribution home is
https://github.com/abraxas914/GenericAgent. The exact accepted fork commit and generated content manifest are
recorded in dist/build-provenance.json. frontends/desktop/static/** remains the independent Desktop v1 and is
unchanged by Desktop 2.0 packaging.

The submitted package, bundle, qualification, and provenance version for this release is 0.2.1.

The Semi Design MIT text is tracked as dist/THIRD_PARTY_NOTICES.txt. Root attributes force the source notice and
compiled notice to LF on every platform, and all three package builders verify the locked notice SHA-256 before
building.

Inputs Copy Chapter

frontends/desktop/packaging/
├── README.md
├── dmg-build-requirements.txt
├── python-runtime-requirements.txt
└── scripts/
    ├── merge_desktop_settings.py
    ├── windows/
    │   ├── install_windows.ps1
    │   ├── uninstall.bat
    │   └── uninstall_windows.ps1
    ├── linux/
    │   ├── install_linux.sh
    │   └── uninstall.sh
    └── macos/
        ├── install_macos.sh
        └── uninstall.command

• Node is fixed at 22.23.2; the compiled-only jobs install exactly @tauri-apps/cli 2.11.4 with
  npm install --package-lock=false, assert that no source lockfile was created, and never invoke Vite. Rust is
  fixed at 1.95.0 and crates are locked by Cargo.lock.
• Root .gitattributes pins both the source public/THIRD_PARTY_NOTICES.txt path and the delivered
  dist/THIRD_PARTY_NOTICES.txt path to LF; the source file itself stays outside this compiled-only PR. Each of
  the three builders runs the cross-platform compiled-distribution contract immediately before Tauri embeds the
  tracked dist, locking the notice SHA-256 to
  2acf865e87e59090121369aac0575467067fdd7999923a70d785a46ceae3330f and failing on any byte drift.
• python-build-standalone is fixed at release 20260814, CPython 3.12.14, an explicit architecture, and an
  archive SHA-256 on each platform.
• The macOS builder runs on the Apple-silicon macos-26 host with
  DEVELOPER_DIR=/Applications/Xcode_26.5.app/Contents/Developer and hard-fails unless Xcode 26.5
  (build 17F42) and the macOS 26.5 SDK are active. Host CPython 3.12.10 is used only for the hash-locked
  DMG layout tools and remains separate from the embedded 3.12.14 runtime.
• Windows converts RUNNER_TEMP with cygpath -u before passing its archive path to POSIX tools.
• Linux builds on Ubuntu 22.04, uses a dedicated glibc-2.35 Rust cache prefix with target/bin caching disabled,
  and scans every packaged ELF to reject a maximum GLIBC requirement above 2.35.
• Runtime direct and transitive dependencies use exact versions in python-runtime-requirements.txt; downloads
  require binary wheels. The DMG layout requirements use exact versions and wheel hashes.
• Preparation disables Python bytecode writes and removes __pycache__, .pyc, and .pyo files across the
  complete bundled runtime without removing vendored Python packages.
• Checkout, Node/Python setup, artifact upload/download, Rust toolchain, and Rust cache actions use full commit
  SHA pins and disable persisted checkout credentials.

These controls do not make the packages bit-for-bit reproducible. Runner images, Ubuntu packages, the Windows
SDK/UCRT input, platform wheels, and native packaging metadata can change or contain timestamps. Candidate
artifact SHA-256 values and release-qualification reports remain the evidence for a particular build.

Candidate artifacts and publication Copy Chapter

Manual workflow_dispatch runs build the selected platform or all three platforms as downloadable Actions
artifacts. They never create or edit a GitHub Release.

A maintainer-created desktop-portable-* tag starts this publication graph:

Windows builder (contents: read) ─┐
Linux builder   (contents: read) ─┼─ verified Actions artifacts ─┐
macOS builder   (contents: read) ─┘                              │
                                                                  ▼
                                           publisher (contents: write)
                                           validate six files/checksums
                                           create one invisible draft
                                           verify uploaded asset set
                                           expose one prerelease

The three builders do not receive a write token and do not call the GitHub Release API. The publisher runs only
for a matching tag push after all three builders succeed; it does not check out source or run package tooling.
It refuses to overwrite an existing Release for the tag.

The prerelease contains exactly:

• GenericAgent-Desktop-Windows-Portable.zip
• SHA256SUMS-windows.txt
• GenericAgent-Desktop-Linux-Portable.tar.gz
• SHA256SUMS-linux.txt
• GenericAgent-Desktop-macOS-aarch64.dmg
• GenericAgent-Desktop-macOS-aarch64.dmg.sha256

The macOS application is ad-hoc signed only. It is not Developer ID signed or notarized, and the published notes
retain the documented context-menu / Privacy & Security opening path.

Validation Copy Chapter

• npm run test:dist verifies required compiled entries, references, source leakage, dead assets, the notice hash,
  version/CSP/E2E isolation, source provenance, and the atomic release contract.
• python -m pytest frontends/tests verifies Desktop bridge, conductor, model/session/upload behavior, the
  Desktop-only cost ledger, transactional data import, release-qualification tooling, owned service/port
  behavior, GA_ROOT, and Tauri security contracts.
• Rust formatting, clippy, production/E2E tests, and a Tauri --no-bundle build validate the native shell against
  the tracked renderer.
• Shell, Python, PowerShell, YAML, action pinning, boundary diff, and conflict checks run before delivery.

Overview (`frontends/desktop/release_qualification/README.md`) Copy Section

Desktop release qualification

run_release_qualification.py is the common production-package runner. Platform wrappers install
or extract one artifact produced from a candidate commit and invoke it against the production binary.
It temporarily uses the real per-user settings path, restores it byte-for-byte, and therefore
must run in a dedicated Windows/Linux/macOS test account.

Every platform report records the candidate commit, artifact SHA-256, OS/architecture, bootstrap
snapshots, bridge identity/PIDs, package paths before and after relocation, screenshots, redacted
fake-model transcript, data results, cleanup status, and a short manual checklist. Screenshots and
manual checklist values are supporting material for the release owner; they do not determine the
automated evidence gate result.

After all three reports and the Windows native retry report are complete, combine them:

python3 frontends/desktop/release_qualification/verify_release_evidence.py \
  --expected-commit <candidate-sha> \
  --windows <windows-production-contract-report.json> \
  --linux <linux-real-package-report.json> \
  --macos <macos-real-package-report.json> \
  --windows-native-report <windows-e2e-report.json> \
  --output <candidate-evidence-manifest.json>

The verifier fails on a commit mismatch, missing artifact digest, failed automated scenario,
incomplete bootstrap evidence, missing macOS app immutability proof, or unclean final process/port
state. The release owner still reviews the screenshots and platform checklists separately before
publishing. The manifest is evidence for the candidate SHA; it is not committed to the repository.

Overview (`frontends/desktop/release_qualification/linux/README.md`) Copy Section

Ubuntu 24.04 release qualification

Run this on a real Ubuntu 24.04 x64 desktop in a dedicated test account. FUSE must be available.
A screenshot tool (gnome-screenshot, scrot, or ImageMagick import) supplies optional review
evidence when present.

frontends/desktop/release_qualification/linux/run_linux_release_qualification.sh \
  --artifact /path/GenericAgent-Desktop-Linux-Portable.tar.gz \
  --expected-commit <candidate-sha> \
  --keep-work-dir

The wrapper verifies/extracts the tar, preserves the AppImage launch path, and runs the shared
production qualification. It covers package shape, embedded Python, first launch, warm
restart, package-owned bridge plus external GA_ROOT, deterministic chat, upload, memory import,
foreign-port protection, recovery after release, relocation into a path containing spaces and
Chinese characters, stale-override fallback, optional P2P degradation, screenshots, and cleanup.

After automation passes, review the Linux manual items: executable bit and desktop launcher,
window dragging/close behavior, retry button after port release, native directory picker, and
visual/loading behavior. The report retains these checklist values for notes, but the automated
evidence verifier does not require them to be edited to pass.

Overview (`frontends/desktop/release_qualification/macos/README.md`) Copy Section

macOS 15 DMG release qualification

Run this on a real macOS 15 machine in a dedicated test account. The wrapper mounts the DMG,
copies its app into /Applications under a collision-safe qualification name, launches the production
binary, and later moves that exact app to a path containing spaces and Chinese characters.

frontends/desktop/release_qualification/macos/run_macos_release_qualification.sh \
  --artifact /path/GenericAgent-Desktop-macOS-aarch64.dmg \
  --expected-commit <candidate-sha> \
  --keep-work-dir

The release workflow builds this artifact on the explicit macOS 15 arm64 runner and names it
aarch64; it is not an Intel/universal binary. The app is ad-hoc signed only, not Developer ID
signed or notarized.

In addition to the shared chat/data/port/relocation checks, this qualification hard-fails if the DMG
does not contain the build-time .prepared marker or if any file inside the .app changes from
first launch through restart and relocation. It verifies the package bridge remains inside the
app while GA_ROOT points at an external core, then verifies a deleted override falls back to the
stable writable runtime at ~/Library/Application Support/GenericAgent/runtime/app.

After automation, review Gatekeeper/open-anyway, traffic lights, focus, retry behavior, the native
directory picker, and visual/loading behavior. The report keeps those checklist values as supporting
notes, but the automated verifier does not require them to be edited to pass. The wrapper restores
the settings file exactly and removes its temporary /Applications copy; run it only in a dedicated
account because the normal Application Support runtime may be created.

Overview (`frontends/desktop/release_qualification/windows/README.md`) Copy Section

Windows Desktop release qualification

This folder contains the Windows qualification runner for the portable desktop package. It exercises:

1. Download a GitHub Actions artifact, or use a local zip.
2. Verify commit, SHA-256, and required package files.
3. Extract to a clean directory.
4. Launch GenericAgent.exe directly.
5. Wait for first-run prepare, bridge identity, and bootstrap ready.
6. In Full mode, inject an unknown process on port 14168, verify port_conflict, release it, and retry from setup.
7. Run the shared production-package qualification with the embedded Python: package-owned bridge plus
   external GA_ROOT, fake-model chat, upload, memory import, warm restart, a second foreign-port
   assertion, relocation into a path with spaces and Chinese characters, stale override fallback,
   optional P2P degradation, and process/settings cleanup.

Full Run Copy Chapter

.\frontends\desktop\release_qualification\windows\Invoke-WindowsReleaseQualification.ps1 `
  -Repo abraxas914/GenericAgent `
  -RunId 29071095889 `
  -ExpectedCommit 696ddfc `
  -Mode Full

Use -PackageZip C:\path\GenericAgent-Desktop-Windows-Portable.zip when the artifact has expired or has already been downloaded.

Modes Copy Chapter

• Smoke: package verification, extraction, first launch, prepare marker, bridge identity, bootstrap ready.
• FailureOnly: assumes the package can be extracted and focuses on the unknown port conflict and setup retry path.
• Full: runs Smoke, the native retry failure path, and the complete production package qualification.
  It requires -ExpectedCommit so the bridge build identity is tied to the candidate SHA.

Manual Checks Copy Chapter

The script collects screenshots and writes these checklist items to the report for separate human review:

• Loading, prepare, setup, and main windows always show the Windows titlebar.
• Right side has exactly minimize, maximize, and close.
• Blank titlebar area drags the window; button area does not.
• Minimize works.
• Maximize and restore work.
• Close hides to tray instead of exiting.
• Sidebar nav sits directly below the custom titlebar with no blank row.
• The native directory picker opens and returns a real directory.
• The shortcut self-heals after the portable folder is moved.
• Loading, fallback, and main React pages render through the Tauri resource protocol.

Screenshot capture and checklist values are supporting evidence. They do not determine the automated
qualification result or need to be edited to pass before the evidence verifier runs.

Report Copy Chapter

Reports are written under <WorkDir>\report:

• e2e-report.json
• bootstrap-events.jsonl
• bootstrap-latest.json
• screenshots such as loading-first.png, main-ready.png, and setup-failure.png
• production-contract/real-package-report.json, including artifact SHA-256, OS/architecture,
  bootstrap phases, bridge identities, PIDs/ports, before/after paths, deterministic data results,
  and cleanup state

Failures exit non-zero and keep diagnostics unless -KeepWorkDir is omitted and cleanup succeeds.

Overview (`frontends/desktop/static/assets/fonts/README.md`) Copy Section

Desktop Font Assets

These font files are the offline Latin bundle for the vanilla desktop shell.

Files Copy Chapter

• azonix-wordmark.woff2

  • Role: brand wordmark only
  • Source: converted on 2026-05-25 from the local owner-installed file at ~/Library/Fonts/azonix/Azonix.otf
  • License: owner-provided / verify before external redistribution
  • Note: this repo currently treats Azonix as a project-local brand asset

• lexend-latin.woff2

  • Role: English titles and navigation
  • Source: Google Fonts CSS2 API, specimen page https://fonts.google.com/specimen/Lexend
  • Downloaded: 2026-05-25
  • License: SIL Open Font License 1.1

• noto-sans-latin.woff2

  • Role: English body copy and default Latin UI text
  • Source: Google Fonts CSS2 API, specimen page https://fonts.google.com/noto/specimen/Noto+Sans
  • Downloaded: 2026-05-25
  • License: SIL Open Font License 1.1

• jetbrains-mono-latin.woff2

  • Role: config/value dense controls and numeric surfaces
  • Source: Google Fonts CSS2 API, specimen page https://fonts.google.com/specimen/JetBrains+Mono
  • Downloaded: 2026-05-25
  • License: SIL Open Font License 1.1

Notes Copy Chapter

• Only Latin subsets are bundled here. Chinese UI text continues to use the existing system fallback stack.
• Runtime does not fetch fonts from a CDN. frontends/desktop/static/assets/fonts/fonts.css is the only font entrypoint for the vanilla shell.

GETTING STARTED (`docs/GETTING_STARTED.md`) Copy Section

🚀 新手上手指南

完全没接触过编程也没关系，跟着做就行。Mac / Windows 都适用。

如果你已经有 Python 环境，直接跳到第 2 步。

1. 安装 Python Copy Chapter

Mac Copy Section

打开「终端」（启动台搜索 "终端" 或 "Terminal"），粘贴这行命令然后回车：

brew install python

如果提示 brew: command not found，说明还没装 Homebrew，先粘贴这行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

装完后再执行 brew install python。

Windows Copy Section

1. 打开 python.org/downloads，点黄色大按钮下载
2. 运行安装包，底部的 "Add Python to PATH" 一定要勾上
3. 点 "Install Now"

验证 Copy Section

终端 / 命令提示符里输入：

python3 --version

看到 Python 3.x.x 就 OK。Windows 上也可以试 python --version。

⚠️ 版本提示：推荐 Python 3.11 或 3.12。不要使用 3.14（与 pywebview 等依赖不兼容）。

2. 配置 API Key Copy Chapter

下载项目 Copy Section

最方便的方式是 一键安装（自带隔离 Python 环境 + Git + 桌面端）：

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

curl -fsSL http://fudankw.cn:9000/files/ga_install.sh | bash

或者手动 clone（开发者）：

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv && uv pip install -e ".[ui]"

也可以走最朴素的 ZIP：GitHub 仓库页面 → 点绿色 Code → Download ZIP → 解压到喜欢的位置。

💡 让 Claude / Codex 等 Agent 帮你装：把下面这条 curl 丢给它，它会按官方指南替你完成安装：

bash Copy

curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation_zh.md

📖 平台差异、排障、升级流程见 docs/installation_zh.md。

创建配置文件 Copy Section

进入项目文件夹，把 mykey_template.py 复制一份，重命名为 mykey.py。

用任意文本编辑器打开 mykey.py，按接口协议选择开头的一段配置，取消整段注释，填好地址、API Key 和模型名即可。不用的配置保持注释。

💡 也可以运行交互式向导 python assets/configure_mykey.py，按提示选择厂商、填入 Key 即可自动生成 mykey.py。

配置示例 Copy Section

推荐首选：Claude 原生协议：

# 变量名同时含 'native' 和 'claude' → NativeClaudeSession（API 原生工具字段）
native_claude_config = {
    'name': 'claude',                        # /llms 显示名 & mixin 引用名
    'apikey': 'sk-xxx',                      # sk-ant- 走 x-api-key；其它走 Bearer
    'apibase': 'https://api.anthropic.com',  # 官方直连；反代渠道填对应地址
    'model': 'claude-opus-4-7',              # [1m] 后缀触发 1M 上下文 beta
    # 'fake_cc_system_prompt': True,         # CC switch / 反代渠道必须置 True
}

也支持：OpenAI 原生协议：

# 变量名同时含 'native' 和 'oai' → NativeOAISession
native_oai_config = {
    'name': 'gpt',                           # /llms 显示名 & mixin 引用名
    'apikey': 'sk-xxx',
    'apibase': 'https://api.openai.com/v1',  # 自动补 /v1/chat/completions
    'model': 'gpt-5.5',
}

进阶：Mixin 故障转移（多 session 自动切换，最稳的玩法）：

# llm_nos 按优先级排列；首项失败按指数退避切下一项
mixin_config = {
    'llm_nos': ['claude', 'gpt'],   # 与上面 native_* 的 name 字段对应
    'max_retries': 10,
    'base_delay': 0.5,
}

💡 常用高级选项、自动故障转移和聊天平台配置见 mykey_template.py 后半部分；首次配置只需看开头。

关键规则 Copy Section

变量命名决定 Session 类型（不是模型名决定的）：

apibase 填写规则（会自动拼接端点路径）：

3. 初次启动 Copy Chapter

终端里进入项目文件夹，运行：

cd 你的解压路径
python3 agentmain.py

这就是命令行模式，已经可以用了。你会看到一个输入提示符，直接打字发送任务即可。

试试你的第一个任务：

帮我在桌面创建一个 hello.txt，内容是 Hello World

💡 Windows 上如果 python3 不识别，换成 python agentmain.py。

4. 让 Agent 自己装依赖 Copy Chapter

Agent 启动后，只需要一句话，它就会自己搞定所有依赖：

请查看你的代码，安装所有用得上的 python 依赖

Agent 会自己读代码、找出需要的包、全部装好。

⚠️ 如果遇到网络问题导致 Agent 无法调用 API，可能需要先手动装一个包：

bash Copy

pip install requests

升级到图形界面 Copy Section

依赖装完后，可以选择适合你的前端：

💡 Windows 下推荐用 Git Bash 跑 TUI；PowerShell / cmd 对 Unicode 和键位支持较弱。仍异常时请直接告诉 Agent：「参考 Claude Code 在 Windows 终端的最佳配置帮我把 TUI 修一遍」。

可选：让 Agent 帮你做的事 Copy Section

请帮我建立 git 连接，方便以后更新代码

Agent 会自动配好。如果你电脑上没有 Git，它也会帮你下载 portable 版。

请帮我在桌面创建一个 launch.pyw 的快捷方式

这样以后双击桌面图标就能启动，不用再开终端了。

5. 能力解锁 Copy Chapter

环境跑起来之后，你可以逐步解锁更多能力。每一项都只需要对 Agent 说一句话：

基础能力 Copy Section

浏览器自动化 Copy Section

解锁后，Agent 可以在保留你登录态的真实浏览器中操作：

打开淘宝，搜索 iPhone 16，按价格排序
去 B 站，查看我最近看过的历史视频

进阶能力 Copy Section

聊天平台接入（可选） Copy Section

接入后可以随时随地通过手机给电脑上的 Agent 发指令。

对 Agent 说：看你的代码，帮我配置 XX 平台的机器人接入

支持的平台：微信个人Bot / QQ / 飞书 / 企业微信 / 钉钉 / Telegram

Agent 会自动读取代码、引导你完成配置。

高级模式 Copy Section

以下模式全部自文档化——不用查手册，直接问 Agent 即可：

💡 这就是 GenericAgent 的核心设计理念：代码即文档。Agent 能读懂自己的源码，所以任何功能你都可以直接问它。

💡 使用越久越强 Copy Chapter

GenericAgent 不预设技能，而是靠使用进化。每完成一个新任务，它会自动将执行路径固化为 Skill，下次遇到类似任务直接调用。

你不需要管理这些 Skill，Agent 会自动处理。使用时间越长，积累的技能越多，最终形成一棵完全属于你的专属技能树。

💡 如果你觉得某些重要信息 Agent 没有记住，可以直接告诉它：把这个记到你的记忆里，它会主动记忆。

其他 Claw 的 Skill 也可以直接复用：

• 让 Agent 搜索：帮我找个做 XXX 的 skill → 完成后 → 加入你的记忆中
• 直接指定来源：访问 XXX 文件夹/URL，按照这个 skill 做 XXX

保持更新：

对 Agent 说：git 更新你的代码，然后看看 commit 有什么新功能

Agent 会自动 pull 最新代码并解读 commit log，告诉你新增了什么能力。

更多细节请参阅 README.md 或 详细版图文教程。

SETUP FEISHU (`docs/SETUP_FEISHU.md`) Copy Section

飞书 Agent 配置指南

让你的个人电脑变成飞书机器人的大脑，随时随地通过飞书对话控制你的电脑。

📋 目录 Copy Chapter

1. 前置条件
2. 方案选择
3. 企业用户配置
4. 个人用户配置
5. 项目配置
6. 运行与测试
7. 常见问题

前置条件 Copy Chapter

必需环境 Copy Section

• Python 3.8+
• 本项目完整代码
• LLM API 密钥（Claude/OpenAI 等，已在 llmcore/mykeys 中配置）

安装依赖 Copy Section

pip install lark-oapi

方案选择 Copy Chapter

企业用户配置 Copy Chapter

适用于：你的公司使用飞书，你有权限创建应用或联系管理员审批

步骤 1：创建应用 Copy Section

1. 访问 飞书开放平台
2. 登录你的企业飞书账号
3. 点击右上角「创建应用」→「企业自建应用」
4. 填写应用信息：
   • 应用名称：我的Agent助手（可自定义）
   • 应用描述：个人AI助手
   • 应用图标：可选

步骤 2：添加机器人能力 Copy Section

1. 进入应用详情页
2. 左侧菜单选择「添加应用能力」
3. 找到「机器人」，点击「添加」
4. 配置机器人信息（可保持默认）

步骤 3：配置权限 Copy Section

1. 左侧菜单「权限管理」→「API 权限」
2. 搜索并开通以下权限：
   • im:message - 获取与发送单聊、群组消息
   • im:message:send_as_bot - 以应用身份发送消息
   • contact:user.id:readonly - 获取用户 ID

步骤 4：获取凭证 Copy Section

1. 左侧菜单「凭证与基础信息」
2. 记录以下信息：
   • App ID：cli_xxxxxxxx
   • App Secret：xxxxxxxxxxxxxxxx

步骤 5：发布应用 Copy Section

1. 左侧菜单「版本管理与发布」
2. 点击「创建版本」
3. 填写版本信息，提交审核
4. 联系企业管理员审批（或自己是管理员直接审批）

步骤 6：获取你的 Open ID Copy Section

1. 应用审批通过后，在飞书中搜索你的机器人
2. 给机器人发送任意消息
3. 运行以下代码获取你的 Open ID：

# 临时运行一次，获取 open_id
import lark_oapi as lark
from lark_oapi.api.im.v1 import *

client = lark.Client.builder().app_id("你的APP_ID").app_secret("你的APP_SECRET").build()

# 监听消息，打印发送者的 open_id
def handle(data):
    print(f"你的 Open ID: {data.event.sender.sender_id.open_id}")

# ... 或者查看 frontends/fsapp.py 运行时的日志输出

个人用户配置 Copy Chapter

适用于：没有企业飞书账号，想个人测试使用

步骤 1：创建测试企业 Copy Section

1. 访问 飞书开放平台
2. 使用个人手机号注册/登录
3. 点击右上角头像 →「创建测试企业」
4. 填写企业名称（如：我的测试工作区）
5. 创建完成后，你就是这个测试企业的管理员

步骤 2：创建应用 Copy Section

与企业用户步骤相同

1. 点击「创建应用」→「企业自建应用」
2. 填写应用信息

步骤 3：添加机器人能力 Copy Section

1. 进入应用详情页
2. 「添加应用能力」→「机器人」→「添加」

步骤 4：配置权限 Copy Section

1. 「权限管理」→「API 权限」
2. 开通权限：
   • im:message
   • im:message:send_as_bot
   • contact:user.id:readonly

步骤 5：获取凭证 Copy Section

1. 「凭证与基础信息」
2. 复制 App ID 和 App Secret

步骤 6：发布应用（测试企业可自审批） Copy Section

1. 「版本管理与发布」→「创建版本」
2. 提交后，进入 飞书管理后台
3. 「工作台」→「应用审核」→ 通过你的应用

步骤 7：在飞书客户端使用 Copy Section

1. 下载 飞书客户端
2. 登录你的测试企业账号
3. 搜索你创建的机器人名称
4. 开始对话！

项目配置 Copy Chapter

配置飞书凭证 Copy Section

编辑项目根目录的 mykey.py，添加：

# 飞书应用凭证
fs_app_id = "cli_xxxxxxxxxxxxxxxx"      # 替换为你的 App ID
fs_app_secret = "xxxxxxxxxxxxxxxx"       # 替换为你的 App Secret

# 允许使用的用户 Open ID 列表（可选，留空则允许所有人）
fs_allowed_users = [
    "ou_xxxxxxxxxxxxxxxxxxxxxxxx",       # 你的 Open ID
]

确认 LLM 配置 Copy Section

确保 llmcore/mykeys 中已配置 LLM API 密钥：

# 示例：Claude API
claude_config = {
    'apikey': 'sk-ant-xxxxx',
    'apibase': 'https://api.anthropic.com',
    'model': 'claude-sonnet-4-20250514'
}

运行与测试 Copy Chapter

启动服务 Copy Section

cd /path/to/pc-agent-loop
python frontends/fsapp.py

预期输出 Copy Section

==================================================
飞书 Agent 已启动（长连接模式）
App ID: cli_xxxxxxxxxxxxxxxx
等待消息...
==================================================

测试对话 Copy Section

1. 打开飞书客户端
2. 找到你的机器人
3. 发送：你好
4. 等待回复（首次可能需要几秒）

可用命令 Copy Chapter

在与机器人对话时，可以使用以下特殊命令：

命令示例 Copy Section

/new                    # 清空对话，重新开始
/stop                   # 停止正在运行的任务
/restore 昨天的任务      # 恢复包含"昨天的任务"关键词的历史对话

消息显示说明 Copy Section

• ⏳ 表示任务正在执行中
• 消息会实时更新，无需等待完成
• 超长回复会自动分段发送

常见问题 Copy Chapter

Q: 提示「应用未发布」或「无权限」 Copy Section

A: 确保应用已发布且管理员已审批。测试企业用户需要在管理后台手动审批。

Q: 发送消息后没有回复 Copy Section

A: 检查：

1. frontends/fsapp.py 是否在运行
2. 终端是否有错误日志
3. LLM API 密钥是否配置正确

Q: 提示「invalid app_id」 Copy Section

A: 检查 mykey.py 中的 fs_app_id 是否正确复制（包含 cli_ 前缀）

Q: 如何获取自己的 Open ID？ Copy Section

A: 运行 frontends/fsapp.py 后给机器人发消息，查看终端日志中的 open_id

Q: 能否多人同时使用？ Copy Section

A: 不能。一个应用只能有一个长连接，连接到一台电脑。每个人需要创建自己的应用。

架构说明 Copy Chapter

你的飞书 ←→ 飞书云 ←→ 长连接 ←→ frontends/fsapp.py ←→ Agent ←→ 你的电脑
                              ↑
                         运行在你电脑上

• 消息通过飞书云转发到你电脑上运行的 frontends/fsapp.py
• Agent 处理请求后，通过飞书 API 回复消息
• 你的电脑必须保持运行 frontends/fsapp.py 才能响应消息

下一步 Copy Chapter

• 自定义 Agent 行为：编辑 assets/sys_prompt.txt
• 添加新工具：编辑 assets/tools_schema.json
• 查看日志：运行时观察终端输出

文档版本：v1.1 | 更新日期：2026-03-07

v1.1 更新内容：

• 新增「可用命令」章节（/new, /stop, /restore）
• 新增消息显示说明（⏳ 进行中标记、实时更新等）

Installation (`docs/installation.md`) Copy Section

Installation Guide

This is the detailed installation guide for GenericAgent.

Two audiences:

• For Humans — you are installing GA for yourself.
• For LLM Agents — you are a coding agent such as Claude Code, or Codex installing GA for a human user. Read that section first so you do not guess.

The shortest install commands live in the main README. This guide adds platform notes, key setup, verification, troubleshooting, and agent-safe rules.

For Humans Copy Chapter

Prerequisites Copy Section

Method 1: One-line install (recommended) Copy Section

This is the easiest path. It prepares an isolated runtime, downloads GenericAgent, installs the core dependencies, and gives you a ready-to-run local project tree.

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

After installation, launch the desktop app from:

frontends/GenericAgent.exe

Or run from the project directory:

python launch.pyw

GenericAgent is meant to grow its environment through the Agent itself, not by pre-installing every possible package. Start small, then let GA install task-specific tools when it actually needs them.

Custom install location

INSTALL_DIR="$HOME/work/GenericAgent" GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

$env:INSTALL_DIR="C:\dev\GenericAgent"; powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Force reinstall

Use this only when you know you want to refresh the installed files. Back up mykey.py, memory/, skills/, and any local work first.

FORCE=1 GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

Method 2: Python install (for developers) Copy Section

Use this when you want a normal editable checkout.

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"        # Core + UI dependencies
cp mykey_template.py mykey.py     # Fill in your LLM API key
python launch.pyw

Full guide: GETTING_STARTED.md

Configure your LLM key Copy Section

1. Open the installed GenericAgent directory.
2. If mykey.py does not exist, copy it from mykey_template.py.
3. Fill in one provider. Do not paste example keys as real keys.
4. If you are unsure about the fields, read the comments in mykey_template.py first.

GA supports:

• OpenAI-compatible endpoints — Chat Completions / Responses shaped APIs.
• Anthropic Claude native — Claude Messages API.

Optional helper:

python assets/configure_mykey.py

Frontends Copy Section

Desktop App

For one-line installs on Windows, double-click:

frontends/GenericAgent.exe

Terminal UI

A lightweight keyboard-driven interface built on Textual. It supports multiple concurrent sessions and real-time streaming.

python frontends/tuiapp_v2.py

Streamlit UI

python launch.pyw

Verify the install Copy Section

From the GenericAgent directory:

python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

Then launch at least one frontend:

python launch.pyw
# or
python frontends/tuiapp_v2.py

Common gotchas Copy Section

Python 3.14 is not supported

If your system python --version reports 3.14, do not use it for GA. Use the one-line installer, or create a Python 3.11 / 3.12 environment with uv.

`ga` command conflict

Some systems already use ga for another tool. Check first:

type ga

If it resolves to something unexpected, do not rely on the shortcut. Run GA from the install directory with python launch.pyw or python frontends/tuiapp_v2.py.

Windows Defender blocks local loopback

The desktop app talks to its local bridge over 127.0.0.1 / localhost. On some Windows machines, Windows Defender Firewall may block this loopback connection, making the desktop app look like it cannot start or cannot connect to the service.

If this happens, allow GenericAgent.exe and the bundled python.exe through Windows Defender Firewall, then restart the desktop app.

Windows TUI rendering issues

TUI rendering on Windows depends on terminal, font, and textual version.

1. Upgrade Textual first: pip install -U textual.
2. Prefer Git Bash on Windows over classic PowerShell / cmd when Unicode or key bindings look broken.
3. If it still looks wrong, ask GA itself to repair the terminal compatibility. Example prompt:

   "My experience using frontends/tuiapp_v2.py in PowerShell / cmd / Git Bash on Windows is very poor — lots of incompatibility. Please refer to Claude Code's best practices for the Windows terminal and fix all font and rendering incompatibilities."

`pywebview` install fails on Linux

Desktop mode depends on GTK / WebKit packages. On Debian / Ubuntu:

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
pip install pywebview

On headless servers, prefer the TUI or run Streamlit in browser mode instead of desktop mode.

Update an existing install Copy Section

Do not delete a working GA directory just to update it. It may contain the user's mykey.py, memory, skills, and local work.

cd ~/GenericAgent
git fetch
git pull
uv pip install -e ".[ui]"

If git pull reports conflicts:

• For mykey.py, memory/, skills/, temp/, and user-created artifacts: prefer the local copy.
• For core code such as agent*.py, frontends/*, reflect/*, and tools/*: usually prefer upstream unless the user says otherwise.
• Resolve explicitly, then git add and commit the merge.

For LLM Agents Copy Chapter

IMPORTANT: fetch this file with curl, not a summarized web reader. Summaries often drop flags, command quoting, and safety rules.

bash Copy

curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md

You are installing GenericAgent for a human user. Be direct, verify each step, and avoid destructive cleanup unless the user explicitly authorizes it.

Step 0: Inspect before acting Copy Section

Check:

1. OS: uname -a, $env:OS, or python -c "import platform; print(platform.system())".
2. Existing install: ~/GenericAgent/launch.pyw, %USERPROFILE%\GenericAgent\launch.pyw, or a .git directory.
3. Python version: must be 3.11 or 3.12 if you use the developer path.
4. Git availability: git --version.
5. API key readiness: ask the user if no key is available. Never invent one.

Step 1: Choose the install path Copy Section

Default to the one-line installer unless the user already has a checkout.

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

If the user explicitly wants a developer checkout:

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"
cp mykey_template.py mykey.py

Step 2: Configure keys safely Copy Section

• Read mykey_template.py before editing mykey.py.
• Configure only keys the user actually provides.
• Never print the full key back to the user.
• If the user is unsure, run python assets/configure_mykey.py or ask which provider they want to use.

Suggested question:

Which LLM should GenericAgent use? GA supports OpenAI-compatible endpoints and Anthropic Claude native APIs. Which provider do you want to configure, and do you already have an API key?

Step 3: Verify setup Copy Section

Run:

cd ~/GenericAgent
python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

Then verify one frontend:

python launch.pyw
# or, for terminal-only environments:
python frontends/tuiapp_v2.py

Step 4: Verification and Next Steps Copy Section

Read this document again and think through whether you have done everything correctly:

• You inspected the OS, existing install, Python version, Git, and key readiness before acting.
• You used the correct GA install command for this English guide, including GLOBAL=1 where shown.
• You configured only real user-provided keys and did not reveal secrets.
• You verified import, Git commit hash, and at least one frontend.

Say 'Congratulations! 🎉' to the user

Say to user: Congratulations! 🎉 You have successfully set up GenericAgent! Double-click frontends/GenericAgent.exe on Windows, or run python frontends/tuiapp_v2.py in your terminal to start using it.

Report the concrete result

Tell the user:

1. Install path.
2. Git commit hash.
3. Which frontend you verified.
4. Whether mykey.py is configured, without revealing secrets.
5. Recommended next reading: Hello GenericAgent and GETTING_STARTED.md.

Ask for a Star ⭐

After everything is set up and working, you may ask:

If you found this helpful, would you like to star the GenericAgent repository? It helps the project grow! ⭐

Only open or run anything related to starring the repository if the user explicitly agrees.

Never do these Copy Section

• Do not run pip install genericagent; GA is not a PyPI package.
• Do not delete ~/GenericAgent or %USERPROFILE%\GenericAgent for a "clean install" without explicit user approval.
• Do not fabricate API keys or treat sample keys as real.
• Do not assume ga is a valid shell command; check first.
• Do not rely on ga update; use git fetch, git pull, and reinstall dependencies as shown above.

References Copy Chapter

• Main README: README.md
• Getting started: GETTING_STARTED.md
• Datawhale tutorial: https://datawhalechina.github.io/hello-generic-agent/
• Technical report: https://arxiv.org/abs/2604.17091

Installation Zh (`docs/installation_zh.md`) Copy Section

安装指南（中文）

这是 GenericAgent 的详细安装指南。

两类读者：

• 面向用户（For Humans） —— 你自己安装 GA。
• 面向 LLM Agent（For LLM Agents） —— 你是 Claude Code、Codex 等编程 Agent，需要替人类用户安装 GA。请先读这一段，避免靠猜。

最短安装命令见主 README。这份文档补充平台差异、Key 配置、验证、排障，以及 Agent 自动安装时的安全规则。

面向用户（For Humans） Copy Chapter

准备工作 Copy Section

方法一：一键安装（推荐） Copy Section

这是最省心的路径。脚本会准备隔离环境、下载 GenericAgent、安装核心依赖，并得到一个可以直接运行的本地项目目录。

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

curl -fsSL http://fudankw.cn:9000/files/ga_install.sh | bash

安装完成后，Windows 用户可双击：

frontends/GenericAgent.exe

也可以进入项目目录运行：

python launch.pyw

GenericAgent 更推荐由 Agent 在使用中自举环境，而不是预先手动装完整依赖。先把最小系统跑起来，需要什么工具再让 GA 自己安装。

自定义安装路径

INSTALL_DIR="$HOME/work/GenericAgent" bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

$env:INSTALL_DIR="C:\dev\GenericAgent"; powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

强制重新安装

仅在明确想刷新已安装文件时使用。请先备份 mykey.py、memory/、skills/ 和本地工作成果。

FORCE=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

方法二：Python 安装（开发者） Copy Section

适合想要可编辑源码目录的开发者。

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"        # 核心 + UI 依赖
cp mykey_template.py mykey.py     # 填入你的 LLM API Key
python launch.pyw

完整引导流程见 GETTING_STARTED.md。

配置 LLM Key Copy Section

1. 打开已安装的 GenericAgent 目录。
2. 如果没有 mykey.py，从 mykey_template.py 复制一份。
3. 填入一个真实可用的模型服务商配置。不要把示例 Key 当真。
4. 不确定字段含义时，先读 mykey_template.py 里的注释。

GA 支持：

• OpenAI 兼容接口 —— Chat Completions / Responses 形态的接口。
• Anthropic Claude 原生接口 —— Claude Messages API。

可选配置向导：

python assets/configure_mykey.py

前端启动方式 Copy Section

桌面端

一键安装自带桌面端，双击：

frontends/GenericAgent.exe

终端 UI

基于 Textual 的轻量键盘驱动界面。支持多会话并发、实时流式输出，有终端就能跑。

python frontends/tuiapp_v2.py

Streamlit UI

python launch.pyw

验证安装 Copy Section

在 GenericAgent 目录下运行：

python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

然后至少启动一个前端：

python launch.pyw
# 或
python frontends/tuiapp_v2.py

常见坑 Copy Section

不支持 Python 3.14

如果系统 python --version 显示 3.14，不要用它跑 GA。请走一键安装，或用 uv 创建 Python 3.11 / 3.12 环境。

`ga` 命令冲突

有些系统已经把 ga 分配给其他工具。先检查：

type ga

如果解析到意料之外的位置，就不要依赖这个快捷命令。请进入安装目录运行 python launch.pyw 或 python frontends/tuiapp_v2.py。

Windows Defender 拦截本机回环网络

桌面端会通过 127.0.0.1 / localhost 连接本机 bridge 服务。部分 Windows 机器上，Windows Defender 防火墙可能会拦截这个本机回环连接，导致桌面端看起来无法启动，或一直连不上服务。

如果遇到这种情况，请在 Windows Defender 防火墙中允许 GenericAgent.exe 和随包的 python.exe 通过，然后重启桌面端。

Windows 上 TUI 显示异常

TUI 在 Windows 上依赖终端、字体和 textual 版本。

1. 先升级 Textual：pip install -U textual。
2. PowerShell / cmd 对 Unicode 和键位支持较弱，Windows 上推荐用 Git Bash。
3. 仍然异常时，可以让 GA 自己修一遍。参考 Prompt：

   "我在 Windows 的 PowerShell / cmd / Git Bash 中使用 frontends/tuiapp_v2.py 体验非常差，出现了一堆不兼容问题。请参考 Claude Code 在 Windows 终端的最佳配置，把所有字体和显示不兼容的问题修一遍。"

Linux 上 `pywebview` 安装失败

桌面模式依赖 GTK / WebKit。Debian / Ubuntu：

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
pip install pywebview

无头服务器建议使用 TUI，或用浏览器方式运行 Streamlit，不要强行启桌面模式。

升级已有安装 Copy Section

不要为了升级而删除一个可用的 GA 目录。里面可能有用户的 mykey.py、记忆、技能和本地成果。

cd ~/GenericAgent
git fetch
git pull
uv pip install -e ".[ui]"

如果 git pull 报冲突：

• mykey.py、memory/、skills/、temp/ 和用户成果：本地优先。
• agent*.py、frontends/*、reflect/*、tools/* 等核心代码：通常 upstream 优先，除非用户另有说明。
• 明确解决冲突后，再 git add 并提交合并。

面向 LLM Agent（For LLM Agents） Copy Chapter

重要：用 curl 获取本文，不要依赖会摘要网页的读取器。 摘要常会丢掉环境变量、命令引号和安全规则。

bash Copy

curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md

你正在替人类用户安装 GenericAgent。请直接执行、逐步验证；除非用户明确授权，不要做破坏性清理。

第 0 步：先探测再行动 Copy Section

检查：

1. 操作系统：uname -a、$env:OS，或 python -c "import platform; print(platform.system())"。
2. 是否已安装：~/GenericAgent/launch.pyw、%USERPROFILE%\GenericAgent\launch.pyw，或 .git 目录。
3. Python 版本：开发者路径必须使用 3.11 或 3.12。
4. Git 是否可用：git --version。
5. API Key 是否准备好：没有就问用户，绝不要伪造。

第 1 步：选择安装路径 Copy Section

除非用户已经有源码目录，否则默认走一键安装。

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

curl -fsSL http://fudankw.cn:9000/files/ga_install.sh | bash

如果用户明确要开发者源码安装：

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"
cp mykey_template.py mykey.py

第 2 步：安全配置 Key Copy Section

• 编辑 mykey.py 前先读 mykey_template.py。
• 只配置用户真实提供的 Key。
• 不要把完整 Key 打印回给用户。
• 用户不确定时，运行 python assets/configure_mykey.py，或询问要使用哪家模型服务商。

建议提问：

你希望 GenericAgent 使用哪个 LLM？GA 支持 OpenAI 兼容接口和 Anthropic Claude 原生接口。你想配置哪家服务商，API Key 准备好了吗？

第 3 步：验证安装 Copy Section

运行：

cd ~/GenericAgent
python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

然后验证至少一个前端：

python launch.pyw
# 或，无桌面环境时：
python frontends/tuiapp_v2.py

第 4 步：验证与下一步 Copy Section

重新读一遍本文，并思考你是否已经正确完成所有步骤：

• 行动前检查了操作系统、已有安装、Python 版本、Git 和 Key 准备情况。
• 使用了本文中文默认安装命令；不要擅自混入英文版的 GLOBAL=1 默认脚本。
• 只配置了用户真实提供的 Key，且没有泄露密钥。
• 已验证 import、Git commit hash，并至少验证了一个前端。

对用户说 “Congratulations! 🎉”

对用户说：Congratulations! 🎉 你已经成功安装 GenericAgent！Windows 下可双击 frontends/GenericAgent.exe，或在终端运行 python frontends/tuiapp_v2.py 开始使用。

回报具体结果

告诉用户：

1. 安装路径。
2. Git commit hash。
3. 已验证哪个前端。
4. mykey.py 是否已配置，但不要泄露密钥。
5. 下一步阅读：Hello GenericAgent 和 GETTING_STARTED.md。

请求 Star ⭐

确认安装可用后，可以询问：

如果你觉得 GenericAgent 有帮助，愿意给仓库点一个 Star 吗？这会帮助项目成长！⭐

只有在用户明确同意后，才可以打开或执行任何与 Star 仓库相关的操作。

绝对不要做 Copy Section

• 不要运行 pip install genericagent；GA 不是 PyPI 包。
• 未经明确授权，不要删除 ~/GenericAgent 或 %USERPROFILE%\GenericAgent 做“干净安装”。
• 不要伪造 API Key，也不要把示例 Key 当真。
• 不要假设 ga 命令一定可用；先检查。
• 不要依赖 ga update；按上面的 git fetch、git pull 和重装依赖流程做。

参考资料 Copy Chapter

• 主 README：README.md
• Getting Started：GETTING_STARTED.md
• Datawhale 教程：https://datawhalechina.github.io/hello-generic-agent/
• 技术报告：https://arxiv.org/abs/2604.17091
• English installation guide: installation.md

Macos Desktop Installation Zh (`docs/macos_desktop_installation_zh.md`) Copy Section

GenericAgent 桌面版安装指南

📦 安装步骤 Copy Chapter

第一步：打开安装包 Copy Section

双击下载的 GenericAgent_x.x.x_aarch64.dmg 文件，会弹出一个安装窗口。

将左边的 GenericAgent 图标拖到右边的 Applications 文件夹图标上，等待拷贝完成。

拷贝完成后，可以右键点击桌面上的 DMG 图标，选择「推出」来关闭安装包。

第二步：首次打开前的准备（重要） Copy Section

由于本应用暂未通过 Apple 官方签名认证，macOS 会阻止首次打开。这是正常的安全提示，不代表应用有问题。

请按以下步骤解除限制：

1. 打开「终端」应用

不知道终端是什么？别担心，它就是一个可以输入命令的工具。打开方式：

• 按下键盘上的 Command(⌘) + 空格键，会弹出搜索框（Spotlight）
• 输入 终端 或 Terminal，按回车键打开

你会看到一个黑色或白色的文字窗口，里面有一个闪烁的光标，这就是终端。

2. 输入解除限制的命令

在终端窗口中，复制粘贴以下这行命令（整行复制，一个字都不要漏��：

xattr -cr /Applications/GenericAgent.app

粘贴方法：在终端窗口里按 Command(⌘) + V

然后按 回车键(Enter) 执行。

如果终端要求输入密码，输入你的 Mac 开机密码（输入时不会显示任何字符，这是正常的），然后按回车。

执行完毕后，终端不会有任何提示，这代表成功了。

3. 打开 GenericAgent

现在可以正常打开应用了：

• 打开 Finder → 侧边栏点击「应用程序」
• 找到 GenericAgent，双击打开

首次打开可能还会弹出一个确认框，点击「打开」即可。之后就不会再弹出了。

❓ 常见问题 Copy Chapter

Q: 提示「GenericAgent 已损坏，无法打开」怎么办？ Copy Section

这不是真的损坏，是 macOS 的安全机制。请回到第二步，确保在终端中执行了 xattr -cr 命令。

Q: 提示「无法打开，因为无法验证开发者」怎么办？ Copy Section

方法一（推荐）：执行第二步的终端命令。

方法二：右键点击 GenericAgent.app → 选择「打开」→ 在弹出的对话框中点击「打开」。

Q: 我的 Mac 是 Intel 芯片的，能用吗？ Copy Section

当前版本仅支持 Apple Silicon（M1/M2/M3/M4）芯片的 Mac。如果你的 Mac 是 2020 年之前购买的，大概率是 Intel 芯片，暂时无法使用本安装包。

查看方法：点击左上角 → 「关于本机」，如果芯片一栏显示 Apple M1/M2/M3/M4，就可以使用。

Q: 终端命令执行后没有任何反应？ Copy Section

没有反应就是成功了。Unix/macOS 的设计哲学是「没有消息就是好消息」。

🔧 系统要求 Copy Chapter

• macOS 12 (Monterey) 或更高版本
• Apple Silicon 芯片（M1/M2/M3/M4）
• 约 50MB 可用磁盘空间

--- METRICS ---

• Files Extracted: 13
• Estimated Token Budget: ~20612 tokens
• Canonical Reference: https://codewiki.google/github.com/lsdefine/GenericAgent