GenericAgent

1. 项目简介

GenericAgent 是一个极简、可自我进化的自主 Agent 框架。核心 6 个文件共计约 3062 行 Python 代码（ga.py 557 行 + llmcore.py 971 行 + agent_loop.py 118 行 + agentmain.py 262 行 + TMWebDriver.py 284 行 + simphtml.py 870 行），通过 9 个原子工具 和 118 行的 Agent Loop，赋予任意大语言模型（LLM）对本地计算机的系统级控制能力，覆盖浏览器、终端、文件系统、键鼠输入、屏幕视觉及移动设备。

其核心设计哲学是：不预设技能，靠进化获得能力——每解决一个新任务，Agent 就将执行路径自动固化为 Skill，供后续直接调用。

核心功能

• 自我进化：每次任务自动沉淀 Skill，能力随使用持续增长
• 极简架构：约 3K 行核心代码，Agent Loop 约百行，零复杂依赖
• 强执行力：注入真实浏览器（保留登录态），9 个原子工具直接接管系统
• 高兼容性：支持 Claude / GPT / Gemini / Kimi / MiniMax / GLM 等主流模型
• 极致省 Token：上下文窗口不到 30K，分层记忆让关键信息始终在场
• 多前端支持：Streamlit Web UI、Qt 桌面、Telegram / 微信 / QQ / 飞书 / 企业微信 / 钉钉 Bot
• 移动端控制：通过 ADB 控制 Android 设备

技术栈总览

类别	技术
语言	Python 3.11 / 3.12
最小依赖	streamlit、pywebview
LLM 通信	原生 HTTP 请求（requests 库），支持 OpenAI / Anthropic 协议
浏览器控制	自研 WebSocket/HTTP 双通道驱动（TMWebDriver），使用 simple_websocket_server、bottle、BeautifulSoup
GUI 前端	Streamlit（默认）、PySide6（Qt）、pywebview
系统控制	win32api（键鼠）、subprocess（终端）、ADB（Android）
OCR	rapidocr-onnxruntime
视觉检测	ultralytics（YOLO）
可观测性	Langfuse（可选插件）

---

2. 目录结构说明

GenericAgent/
├── agentmain.py              # 🚀 主入口：GeneraticAgent 类定义，CLI/任务/反射三种运行模式
├── agent_loop.py             # 🔄 Agent 执行循环核心（约 100 行），驱动 LLM → 工具调用 → 结果反馈
├── ga.py                     # 🛠️ GenericAgentHandler：所有 9 个工具的具体实现
├── llmcore.py                # 🧠 LLM 通信层：Session 管理、协议适配、流式解析、历史压缩
├── TMWebDriver.py            # 🌐 浏览器驱动：WebSocket + HTTP 双通道，管理浏览器 Tab 会话
├── simphtml.py               # 📄 HTML 优化器：简化网页 HTML 以节省 Token，含列表裁剪和智能截断
├── launch.pyw                # 🖥️ GUI 启动器：pywebview 封装 Streamlit + 空闲监控 + Bot 子进程管理
├── hub.pyw                   # 📊 服务管理器：tkinter 多服务启停面板（reflect/frontends 一键管理）
├── mykey_template.py         # 🔑 API Key 配置模板（复制为 mykey.py 使用）
│
├── assets/                   # 📦 静态资源
│   ├── sys_prompt.txt        #   系统提示词（中文）
│   ├── sys_prompt_en.txt     #   系统提示词（英文）
│   ├── tools_schema.json     #   9 个工具的 JSON Schema 定义
│   ├── tools_schema_cn.json  #   工具 Schema 中文版（供国产模型使用）
│   ├── insight_fixed_structure.txt      #   记忆系统固定结构描述
│   ├── global_mem_insight_template.txt  #   L1 记忆索引初始模板
│   ├── code_run_header.py    #   代码执行时自动注入的头文件（路径/异常处理）
│   ├── tool_usable_history.json         #   工具使用示范历史
│   └── tmwd_cdp_bridge/      #   Chrome 浏览器扩展（CDP 桥接）
│       ├── manifest.json
│       ├── background.js
│       ├── content.js
│       ├── popup.html / popup.js
│       └── disable_dialogs.js
│
├── memory/                   # 🧠 记忆与能力模块
│   ├── global_mem.txt        #   L2 全局事实库（运行时生成）
│   ├── global_mem_insight.txt#   L1 记忆索引（运行时生成）
│   ├── memory_management_sop.md  #   L0 记忆管理元规则
│   ├── memory_cleanup_sop.md #   记忆清理 SOP
│   ├── plan_sop.md           #   计划模式 SOP
│   ├── scheduled_task_sop.md #   定时任务 SOP
│   ├── autonomous_operation_sop.md  #   自主操作 SOP
│   ├── tmwebdriver_sop.md    #   浏览器驱动使用 SOP
│   ├── web_setup_sop.md      #   Web 环境搭建 SOP
│   ├── vision_sop.md         #   视觉能力 SOP
│   ├── ljqCtrl_sop.md        #   键鼠控制 SOP
│   ├── procmem_scanner_sop.md#   进程内存扫描 SOP
│   ├── keychain.py           #   密钥安全存储（XOR 加密）
│   ├── adb_ui.py             #   Android UI 自动化（u2 + 原生 fallback）
│   ├── ocr_utils.py          #   OCR 工具（RapidOCR）
│   ├── ljqCtrl.py            #   Windows 键鼠控制（win32api）
│   ├── ui_detect.py          #   UI 元素检测（YOLO + OmniParser）
│   ├── procmem_scanner.py    #   进程内存扫描（YARA 规则）
│   └── vision_api.template.py#   视觉 API 模板
│
├── reflect/                  # 🔁 反射/调度模块
│   ├── autonomous.py         #   自主探索脚本（空闲 30 分钟触发）
│   └── scheduler.py          #   定时任务调度器（cron 风格 + L4 归档）
│
├── frontends/                # 🖼️ 前端界面
│   ├── stapp.py              #   Streamlit 默认 Web UI（主前端）
│   ├── stapp2.py             #   Streamlit 备选 UI
│   ├── qtapp.py              #   PySide6 Qt 桌面应用（悬浮球 + 聊天面板）
│   ├── chatapp_common.py     #   前端通用逻辑（消息清理、命令解析、会话恢复）
│   ├── continue_cmd.py       #   /continue 命令实现（会话列表、恢复、快照）
│   ├── tgapp.py              #   Telegram Bot 前端
│   ├── fsapp.py              #   飞书 Bot 前端
│   ├── qqapp.py              #   QQ Bot 前端
│   ├── dingtalkapp.py        #   钉钉 Bot 前端
│   ├── wecomapp.py           #   企业微信 Bot 前端
│   ├── wechatapp.py          #   个人微信 Bot 前端
│   ├── desktop_pet.pyw       #   桌面宠物 v1
│   ├── desktop_pet_v2.pyw    #   桌面宠物 v2
│   └── skins/                #   桌面宠物皮肤资源
│
├── plugins/                  # 🔌 插件
│   └── langfuse_tracing.py   #   Langfuse 可观测性追踪（monkey-patch 方式无侵入接入）
│
├── tests/                    # 🧪 测试
│   ├── conftest.py           #   测试环境配置
│   ├── test_minimax.py       #   MiniMax 模型适配测试
│   └── test_minimax_integration.py  #   MiniMax 集成测试
│
├── GETTING_STARTED.md        # 📖 新手上手指南
├── CONTRIBUTING.md           # 🤝 贡献指南
├── README.md                 # 📋 项目说明（中英双语）
└── LICENSE                   # 📄 MIT 许可证

---

3. 架构设计

整体架构模式

GenericAgent 采用 “极简分层 + 事件驱动循环” 架构，整个系统可分为 4 层：

┌─────────────────────────────────────────────────┐
│              前端层 (Frontends)                   │
│  Streamlit / Qt / Telegram / 微信 / 飞书 / ...     │
└──────────────────────┬──────────────────────────┘
                       │ put_task() / display_queue
┌──────────────────────▼──────────────────────────┐
│            调度层 (GeneraticAgent)                │
│  agentmain.py: 任务队列、LLM 选择、历史管理         │
└──────────────────────┬──────────────────────────┘
                       │ agent_runner_loop()
┌──────────────────────▼──────────────────────────┐
│            执行层 (Agent Loop + Handler)          │
│  agent_loop.py: 循环驱动                          │
│  ga.py: 9 个工具实现 + 记忆管理                    │
└──────────┬───────────────────────┬──────────────┘
           │                       │
┌──────────▼──────────┐ ┌─────────▼──────────────┐
│   LLM 通信层         │ │   环境交互层             │
│  llmcore.py:         │ │  TMWebDriver (浏览器)    │
│  OpenAI / Claude /   │ │  subprocess (终端)       │
│  Native 协议适配      │ │  ljqCtrl (键鼠)         │
│  流式解析 / 历史裁剪   │ │  adb_ui (Android)      │
└─────────────────────┘ │  ocr_utils / ui_detect  │
                        └────────────────────────┘

核心模块职责

模块	文件	职责
调度核心	agentmain.py	GeneraticAgent 类：管理任务队列、LLM 客户端列表、对话历史，支持 CLI / 任务文件 / 反射 三种运行模式
执行循环	agent_loop.py	agent_runner_loop() 生成器：LLM 调用 → 解析工具调用 → 分发执行 → 注入 anchor prompt → 循环，约 100 行
工具处理	ga.py	GenericAgentHandler：实现 do_code_run、do_file_read 等 9 个工具方法 + do_no_tool 兜底 + 记忆管理
LLM 通信	llmcore.py	多协议适配（OpenAI SSE / Claude SSE / Responses API），BaseSession → 各 Session 子类，ToolClient / NativeToolClient 封装工具协议
浏览器驱动	TMWebDriver.py	WebSocket + HTTP 双通道管理浏览器 Tab 会话，支持 JS 注入执行
HTML 优化	simphtml.py	简化网页 DOM 以节省 Token：属性精简、列表裁剪、智能截断、变化监控

模块间调用关系与数据流

用户输入
  │
  ▼
[前端] ──put_task()──▶ [GeneraticAgent.task_queue]
                              │
                        run() 循环消费
                              │
                              ▼
                     组装 system_prompt
                   (sys_prompt.txt + 分层记忆)
                              │
                              ▼
              ┌── agent_runner_loop() ──┐
              │                        │
              │  ① 发送 messages       │
              │     给 LLM 客户端      │
              │         │              │
              │  ② 解析 response       │
              │     提取 tool_calls    │
              │         │              │
              │  ③ handler.dispatch()  │
              │     执行工具方法        │
              │         │              │
              │  ④ 收集结果            │
              │     注入 anchor prompt │
              │     (工作记忆+历史摘要) │
              │         │              │
              │  ⑤ turn_end_callback   │
              │     记录历史、注入提示  │
              │         │              │
              │  ⑥ 若未完成 → 回到 ①  │
              └────────────────────────┘
                              │
                              ▼
                     display_queue.put()
                              │
                              ▼
                         [前端展示]

---

4. 核心流程解析

4.1 应用启动流程

以默认 GUI 模式 python launch.pyw 为例：

1. launch.pyw 启动：

   • 找到空闲端口（18501-18599）
   • 子线程启动 streamlit run frontends/stapp.py
   • 可选启动 Telegram / QQ / 飞书等 Bot 子进程
   • 启动空闲监控线程（30 分钟无操作自动触发任务）
   • 创建 pywebview 窗口加载 Streamlit 页面

2. frontends/stapp.py 初始化：

   • @st.cache_resource 单例创建 GeneraticAgent 实例
   • GeneraticAgent.__init__() 读取 mykey.py 配置，按变量名规则创建 LLM Session 列表
   • 启动 agent.run() 守护线程

3. GeneraticAgent.run() 进入主循环：

   • 阻塞等待 task_queue.get()
   • 收到任务后组装系统提示（sys_prompt.txt + 分层记忆）
   • 创建 GenericAgentHandler 实例
   • 调用 agent_runner_loop() 执行任务

4.2 LLM 客户端初始化流程

# agentmain.py - GeneraticAgent.__init__()
from llmcore import mykeys  # 触发 PEP 562 __getattr__，加载 mykey.py

for k, cfg in mykeys.items():
    # 变量名决定协议：
    # 'native' + 'claude' → NativeClaudeSession（原生 Claude 工具调用）
    # 'native' + 'oai'    → NativeOAISession（原生 OpenAI 工具调用）
    # 'claude'             → ClaudeSession（文本协议，已 deprecated）
    # 'oai'                → LLMSession（文本协议，已 deprecated）
    # 'mixin'              → MixinSession（多 Session 混合）

关键设计：变量命名即配置，无需额外的配置文件解析逻辑。

4.3 Agent 执行循环（核心）

agent_loop.py 中的 agent_runner_loop() 是整个框架最核心的函数，约 100 行代码：

# agent_loop.py — agent_runner_loop()（关键逻辑摘录，约 100 行）
def agent_runner_loop(client, system_prompt, user_input, handler, tools_schema, max_turns=40):
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_input}
    ]
    turn = 0
    while turn < handler.max_turns:
        turn += 1
        # ① LLM 推理 — 流式返回
        response = yield from client.chat(messages=messages, tools=tools_schema)

        # ② 解析工具调用 — 无工具调用时自动构造 no_tool
        if not response.tool_calls:
            tool_calls = [{'tool_name': 'no_tool', 'args': {}}]
        else:
            tool_calls = [{'tool_name': tc.function.name,
                           'args': json.loads(tc.function.arguments),
                           'id': tc.id} for tc in response.tool_calls]

        # ③ 逐个执行工具，收集结果
        tool_results = []; next_prompts = set(); exit_reason = {}
        for ii, tc in enumerate(tool_calls):
            tool_name, args = tc['tool_name'], tc['args']
            outcome = yield from handler.dispatch(tool_name, args, response, index=ii)
            if outcome.should_exit: break       # 用户交互中断（如 ask_user）
            if not outcome.next_prompt: break    # next_prompt 为 None → 任务完成
            tool_results.append(...)
            next_prompts.add(outcome.next_prompt)

        if not next_prompts or exit_reason: break   # 退出循环

        # ④ 注入 anchor prompt（工作记忆 + 历史摘要）
        next_prompt = handler.turn_end_callback(response, tool_calls, tool_results, turn, ...)
        messages = [{"role": "user", "content": next_prompt, "tool_results": tool_results}]

关键设计点：

• 生成器（Generator）模式：整个循环是一个生成器，通过 yield 实时流式输出内容给前端
• Anchor Prompt 注入：每轮结束后注入工作记忆和历史摘要，防止长对话中信息丢失
• no_tool 兜底：当 LLM 不调用任何工具时，自动触发 do_no_tool 进行二次确认或结束任务
• 历史仅保留在 Session 中：每轮 messages 只包含新的 user 消息，完整历史由 LLMSession.history 维护

4.4 工具执行流程

以 code_run 为例：

用户说 "帮我在桌面创建 hello.txt"
  │
  ▼
LLM 返回 tool_call: code_run(script="...", type="python")
  │
  ▼
handler.dispatch("code_run", args, response)
  │
  ▼
ga.py → do_code_run():
  ├── 提取代码（从 args.script 或回复中的代码块）
  ├── 注入 code_run_header.py（路径修正、异常钩子）
  ├── subprocess 执行 Python 脚本
  ├── 捕获 stdout/stderr，截断过长输出
  └── 返回 StepOutcome(result, next_prompt=anchor_prompt)

4.5 分层记忆系统

L0 — 元规则（memory_management_sop.md）
│    定义记忆写入的核心公理：行动验证原则、禁止易变状态、最小充分指针
│
L1 — 记忆索引（global_mem_insight.txt）
│    ≤30 行极简索引，指向 L2/L3 的入口
│    每次 LLM 调用时注入 system_prompt
│
L2 — 全局事实（global_mem.txt）
│    经行动验证的稳定知识：路径、配置、用户偏好
│
L3 — 任务 Skills / SOPs（memory/*.md, *.py）
│    可复用的工作流程：浏览器操作、定时任务、视觉能力等
│
L4 — 会话归档（L4_raw_sessions/）
     从已完成任务中提炼的归档记录，由 scheduler 自动收集

记忆在运行时通过 get_global_memory() 函数组装并注入到系统提示中：

# ga.py
def get_global_memory():
    # 读取 insight_fixed_structure.txt（L0 规则摘要）
    # 读取 global_mem_insight.txt（L1 索引）
    # 拼接为 system_prompt 的一部分

4.6 浏览器控制流程

Agent 调用 web_scan
  │
  ▼
ga.py → do_web_scan()
  │
  ▼
simphtml.py → get_html(driver)
  ├── TMWebDriver.execute_js() 注入 JS 获取页面 HTML
  ├── BeautifulSoup 解析 → 移除隐藏元素、精简属性
  ├── 列表裁剪（cutlist）：检测重复列表，只保留前 3 项
  └── 智能截断（smart_truncate）：按 budget 递归裁剪

Agent 调用 web_execute_js
  │
  ▼
ga.py → do_web_execute_js()
  │
  ▼
simphtml.py → execute_js_rich(script, driver)
  ├── 启动变化监控（注入 startStrMonitor JS）
  ├── TMWebDriver.execute_js(script) 执行用户脚本
  ├── 收集页面变化（DOM diff + 瞬态文本）
  └── 返回 {status, js_return, diff, transients, newTabs}

---

5. 关键设计与实现

5.1 设计模式

模式	应用位置	说明
生成器管道	agent_loop.py、llmcore.py	整个执行循环和 LLM 通信都使用 Python 生成器实现流式处理，数据一边生成一边消费
策略模式	llmcore.py 的 Session 体系	BaseSession 定义接口，ClaudeSession、LLMSession、NativeClaudeSession、NativeOAISession 分别实现不同协议
命令分发	ga.py 的 dispatch()	通过反射 getattr(self, f"do_{tool_name}") 将工具名映射到处理方法
多 Session 降级（MixinSession）	llmcore.py	多 LLM 会话自动降级：按优先级尝试多个 Session，失败自动切换下一个，指数退避重试，成功后定时回弹到主 Session
Monkey-Patch	plugins/langfuse_tracing.py	零侵入式追踪：不修改核心代码，通过替换函数引用实现 Langfuse 集成
PEP 562 模块级 __getattr__	llmcore.py	延迟加载 mykeys 配置，首次访问时才读取 mykey.py
单例 + 缓存	stapp.py 的 @st.cache_resource	确保 Streamlit 多次 rerun 时 Agent 实例不重复创建

5.2 数据模型

GenericAgent 不使用数据库，所有数据以 文件 形式存储：

数据类型	存储位置	格式
API 密钥配置	mykey.py	Python 变量
工具定义	assets/tools_schema.json	JSON
分层记忆	memory/*.txt / memory/*.md	纯文本 / Markdown
安全密钥	~/ga_keychain.enc	XOR 加密的 JSON
LLM 对话日志	temp/model_responses/	文本文件
定时任务	sche_tasks/*.json	JSON
任务报告	sche_tasks/done/*.md	Markdown

5.3 状态管理

• 对话历史：存储在 LLMSession.history 列表中，格式为 Claude 的 content-block 格式（[{role, content: [{type, text}]}]）
• 工作记忆：GenericAgentHandler.working 字典，包含 key_info（关键信息）和 related_sop（关联 SOP），每轮自动注入到 anchor prompt
• 历史摘要：GenericAgentHandler.history_info 列表，记录每轮的精简摘要（[USER]: ... / [Agent]: ...）

5.4 上下文窗口管理

GenericAgent 的一大特点是极致省 Token，通过以下机制控制上下文大小：

1. compress_history_tags()：压缩旧消息中的 <thinking> / <tool_use> / <tool_result> 标签内容
2. trim_messages_history()：当历史总字符数超过 context_win * 3 时，从头部裁剪旧消息
3. Anchor Prompt：不传递完整历史，而是注入精简的工作记忆 + 历史摘要
4. HTML 裁剪：simphtml.py 的列表裁剪和智能截断，将网页从数万字符压缩到可控范围

5.5 错误处理策略

• LLM 通信：_openai_stream() 支持自动重试（可配置 max_retries），对 429/500/502/503/504 等状态码指数退避重试
• 工具执行：每个 do_xxx 方法独立捕获异常，返回错误信息作为 StepOutcome 让 LLM 自行决策
• 轮次保护：每 7 轮注入 “禁止无效重试” 提示，每 35 轮强制 ask_user
• 代码执行：code_run 支持 timeout 参数，超时自动终止；code_run_header.py 注入自定义 excepthook 引导 Agent 探测而非猜测

5.6 安全机制

• 密钥管理：memory/keychain.py 使用 XOR 加密存储密钥到 ~/ga_keychain.enc，Agent 只能通过 keys.xxx.use() 获取值，不会在对话中泄露
• 用户白名单：所有 Bot 前端（Telegram / QQ / 飞书等）都支持 allowed_users 配置，限制可交互的用户
• 宪法约束：insight_fixed_structure.txt 中的 [CONSTITUTION] 规定了 Agent 的行为边界——修改自身源码需请示、不可读取密钥文件、决策前必须查记忆
• 进程安全：禁止无条件杀 Python 进程（会杀死自身），要求精确 PID

---

6. 环境搭建与运行

前置条件

• Python 3.11 或 3.12（⚠️ 不要使用 3.14，与 pywebview 不兼容）
• 至少一个 LLM API Key（OpenAI / Anthropic / MiniMax / Kimi 等）

安装步骤

# 1. 克隆仓库
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 2. 安装最小依赖
pip install streamlit pywebview

# 3. 配置 API Key
cp mykey_template.py mykey.py
# 编辑 mykey.py，按模板注释填入你的 LLM API Key

启动方式

# 方式 1：GUI 模式（推荐）— pywebview 窗口 + Streamlit
python launch.pyw

# 方式 2：命令行模式 — 直接在终端交互
python agentmain.py

# 方式 3：服务管理器 — 管理 reflect/frontends 子服务
python hub.pyw

# 方式 4：任务文件模式 — 从文件读取任务
python agentmain.py --task mytask --input "你的任务描述"

# 方式 5：反射模式 — 加载监控脚本
python agentmain.py --reflect reflect/autonomous.py

# 方式 6：带 Bot 启动
python launch.pyw --tg --feishu --sched  # Telegram + 飞书 + 定时调度

关键配置说明（mykey.py）

变量名规则	触发的 Session 类型	说明
含 native + claude	NativeClaudeSession	Anthropic 原生工具调用（推荐）
含 native + oai	NativeOAISession	OpenAI 原生工具调用（推荐）
含 claude（不含 native）	ClaudeSession	文本协议（已 deprecated）
含 oai（不含 native）	LLMSession	文本协议（已 deprecated）
含 mixin	MixinSession	多 Session 自动降级：配置多个 LLM 后端，按优先级依次尝试，失败自动切换，成功后定时（默认 5 分钟）回弹主 Session

apibase 填写规则：

• 填 http://host:port → 自动补 /v1/chat/completions
• 填 http://host:port/v1 → 自动补 /chat/completions
• 填完整 URL → 直接使用

---

7. 推荐学习路线

阶段一：入门（1-2 小时）

目标：理解项目整体架构和运行机制

1. 阅读 README.md — 了解项目定位、核心特性、工作机制概述
2. 阅读 GETTING_STARTED.md — 跟着做一遍环境搭建，亲手跑起来
3. 阅读 assets/tools_schema.json — 理解 9 个原子工具的定义和参数
4. 阅读 assets/sys_prompt.txt — 理解 Agent 的 “人格设定” 和行动原则
5. 阅读 agent_loop.py（约 100 行）— 这是整个框架的心脏，理解 LLM → 工具 → 反馈 → 循环 的核心逻辑

阶段二：进阶（3-5 小时）

目标：深入理解核心模块实现

1. ga.py — 重点看 GenericAgentHandler 类的以下方法：
   • do_code_run：理解代码执行的沙箱机制
   • do_no_tool：理解 LLM 不调用工具时的兜底策略
   • _get_anchor_prompt：理解工作记忆注入机制
   • turn_end_callback：理解轮次保护和历史记录
2. llmcore.py — 重点理解：
   • BaseSession 及其子类的继承关系
   • _parse_claude_sse / _parse_openai_sse：流式解析逻辑
   • compress_history_tags / trim_messages_history：上下文压缩
   • ToolClient vs NativeToolClient：两种工具协议的区别
3. agentmain.py — 理解 GeneraticAgent 类的初始化（LLM 选择逻辑）和三种运行模式（CLI / 任务 / 反射）
4. memory/memory_management_sop.md — 理解分层记忆的设计哲学和操作规范

阶段三：实践（按兴趣选择）

1. 添加一个新的工具：
   • 在 assets/tools_schema.json 中定义 Schema
   • 在 ga.py 中添加 do_xxx 方法
   • 测试：启动 Agent，让它使用新工具
2. 接入一个新的 LLM 提供商：
   • 在 mykey_template.py 中添加配置模板
   • 如果需要新协议，在 llmcore.py 中继承 BaseSession
3. 编写一个反射脚本：
   • 参考 reflect/autonomous.py 和 reflect/scheduler.py
   • 创建 reflect/my_monitor.py，实现 check() 函数
   • 通过 python agentmain.py --reflect reflect/my_monitor.py 启动
4. 编写一个新的前端：
   • 参考 frontends/chatapp_common.py 中的通用逻辑
   • 核心接口：agent.put_task(query) 返回 display_queue
   • 从 display_queue 中消费 {next: ...} / {done: ...} 消息

---

8. 常见问题与注意事项

容易踩的坑

• Python 版本：必须用 3.11 或 3.12，3.14 与 pywebview 不兼容
• mykey.py 变量命名：变量名决定了走哪种协议，而非模型名称。例如用 Claude 模型但走 OpenAI 兼容接口时，变量名应包含 oai 而非 claude
• apibase 不要写完整路径：填 https://api.openai.com/v1 即可，系统会自动拼接 /chat/completions
• MiniMax 温度限制：MiniMax 要求温度在 (0, 1] 范围内，llmcore.py 已自动修正，但需注意
• Kimi 温度覆盖：Kimi/Moonshot 的温度会被强制设为 1.0，配置中填写的值会被忽略
• Windows 键鼠控制：ljqCtrl.py 严禁同时导入 pyautogui（会污染 win32api）
• 浏览器工具需要先解锁：web_scan / web_execute_js 需要先执行 Web Setup SOP（安装浏览器扩展），否则无法使用

代码中的特殊约定

• StepOutcome 的 next_prompt：返回 None 表示任务完成退出循环；返回字符串则作为下一轮的 user prompt 注入
• should_exit=True：用于 ask_user 等需要暂停等待用户输入的场景
• _index 参数：多工具调用时的索引，_index > 0 时跳过 anchor prompt 注入以节省 Token
• code_run_header.py：所有通过 code_run 执行的 Python 代码都会自动注入此头文件，它修改了 subprocess.run 以处理编码问题，并添加了自定义异常钩子
• 文件路径约定：Agent 的工作目录是 temp/，记忆文件在 memory/，路径中 ./ 指向 temp/，../ 指向项目根目录

值得注意的技术债务

• 非 Native Session 已标记 Deprecated：LLMSession 和 ClaudeSession（文本协议）未来可能移除，新用户应直接使用 Native 配置
• 部分模块仅支持 Windows：ljqCtrl.py（键鼠控制）和 procmem_scanner.py（内存扫描）依赖 win32api / ctypes.windll，仅在 Windows 上可用
• 测试覆盖有限：tests/ 目录仅包含 MiniMax 相关的单元测试，核心模块缺少系统性测试
• ga.py 体量较大：GenericAgentHandler 在 557 行中承载了所有 9 个工具实现、辅助函数（code_run、file_read、file_patch、web_scan 等）及记忆管理逻辑，是单文件中职责最多的模块