update: README重写+agentmain/tgapp改进+SOP优化

2026-02-15 08:49:12 +08:00
parent 33fc5e6457
commit 480b131a0a
5 changed files with 247 additions and 90 deletions
--- a/README.md
+++ b/README.md
@@ -1,105 +1,248 @@
-# PC-Agent-Loop: High-Performance Autonomous PC Controller
+# GenericAgent — 3,300 Lines to Full OS Autonomy

-[English](#english) | [中文说明](#chinese)
+[English](#english) | [中文](#chinese)

 <a name="english"></a>

-PC-Agent-Loop is a minimalist yet powerful autonomous agent framework designed to bridge Large Language Models with direct OS-level execution. Unlike traditional chatbots, it possesses "physical" agency—the ability to perceive its environment, reason about complex goals, and execute multi-step operations across the file system, browsers, and local applications.
+A minimalist autonomous agent framework that gives any LLM physical-level control over your PC — browser, terminal, file system, keyboard, mouse, screen vision, and mobile devices — in ~3,300 lines of Python.

-## 🚀 Evolutionary Intelligence & Extensibility
+No Electron. No Docker. No Mac Mini. No 500K-line codebase. No paid installation service.

-This agent is not limited to a fixed set of features. Its true power lies in its ability to **autonomously discover environment-specific capabilities** and **manufacture its own tools**:
+## What Happens When You Use It

- **Self-Discovery via Long-Term Memory**: 
-  - The agent maintains a "Global Memory" (L2 Facts) to store system paths, credentials, and environmental status.
-  - It can autonomously retrieve context-aware SOPs (Standard Operating Procedures) to handle specialized tasks like Instant Messaging (IM) database recovery or Gmail API operations.
- **Dynamic Tool Manufacturing**:
-  - Through `code_run`, the agent can write and execute arbitrary Python scripts to interface with new hardware or software.
-  - Examples of self-integrated capabilities include:
-    - **Deep Web Interaction**: JS injection via Tampermonkey for UI automation.
-    - **Digital Forensics**: Querying SQLCipher-encrypted databases (e.g., encrypted local storage of IM apps).
-    - **Vision-Driven Logic**: Understanding UI states through local vision APIs (`ask_vision`).
-    - **System Indexing**: Utilizing **Everything CLI (es.exe)** for instant file discovery across the entire OS.
-    - **Android Automation**: ADB-based control for mobile device interaction.
+```
+You: "Read my WeChat messages"
+Agent: installs dependencies → reverse-engineers DB → writes reader script → saves as SOP
+Next time: instant recall, zero setup.

-## 📂 Project Architecture
+You: "Monitor stock prices and alert me"
+Agent: installs mootdx → builds screening workflow → sets up scheduled task → saves as SOP
+Next time: one sentence to run.

- `agent_loop.py`: The core "Sense-Think-Act" engine (under 100 lines) driving the autonomous cycle.
- `ga.py`: The fundamental atomic toolset (File, Web, Code, User interaction).
- `agentapp.py` & `launch.pyw`: A Streamlit-based graphical interface and persistent launcher.
- `sidercall.py`: Robust LLM session management supporting multiple backends and model switching.
+You: "Send this file via Gmail"
+Agent: configures OAuth → writes send script → saves as SOP
+Next time: just works.
+```

-## 🛠️ Usage Examples
+**Dogfooding**: This repository — from installing Git to `git init`, writing this README, to every commit message — was built entirely by GenericAgent without the author opening a terminal once.

-### 1. Autonomous Environment Adaptation
-"Scan my local memory for recent SOPs regarding mail processing, then find and download my latest reimbursement receipts from Gmail."
+Every task the agent solves becomes a permanent skill. After a few weeks, your instance has a unique skill tree — grown entirely from 3,300 lines of seed code.

-### 2. Complex Multi-Step Automation
-"Locate a specific encrypted IM database, decrypt it to find messages about 'Project X', and summarize the findings into a PDF report."
+## The Seed Philosophy

-### 3. Real-Time System Intervention
-"Monitor my cloud dashboard via the browser; if the status turns red, execute a local PowerShell script to restart the service and notify me."
+Most agent frameworks ship as finished products. GenericAgent ships as a **seed**.

-## 🧩 Atomic Toolset (The Primitives)
+The 5 core SOPs define how the agent thinks, remembers, and operates. From there, every new capability is discovered and recorded by the agent itself:

-The agent achieves high-level goals by orchestrating these 7 primitive actions:
-1. `code_run`: The ultimate "Swiss Army Knife" for executing Python/PowerShell.
-2. `web_scan`: Semantic perception of live web pages and tabs.
-3. `web_execute_js`: Direct physical interaction with web DOM elements.
-4. `file_read` & `file_write`: Direct disk access and file management.
-5. `file_patch`: Safe, block-level code modification to evolve its own scripts.
-6. `ask_user`: Bridging the gap for human decision-making or sensitive credentials.
-7. `conclude_and_reflect`: The mechanism for distilling experiences into long-term memory.
+1. You ask it to do something new
+2. It figures out how (install dependencies, write scripts, test)
+3. It saves the procedure as a new SOP in its memory
+4. Next time, it recalls and executes directly
+
+The agent doesn't just execute — it **learns and remembers**.
+
+## Quick Start
+
+```bash
+# 1. Clone
+git clone https://github.com/lsdefine/pc-agent-loop.git
+cd pc-agent-loop
+
+# 2. Install minimal deps
+pip install streamlit pywebview
+
+# 3. Configure API key
+cp mykey_template.py mykey.py
+# Edit mykey.py with your LLM API key
+
+# 4. Launch
+python launch.pyw
+```
+
+Once running, tell the agent: *"Execute web setup SOP to unlock browser tools"* — it handles the rest. See [WELCOME_NEW_USER.md](WELCOME_NEW_USER.md) for the full bootstrap sequence.
+
+## vs. Alternatives
+
+| | GenericAgent | OpenClaw | Claude Code |
+|---|---|---|---|
+| Codebase | ~3,300 lines | ~530,000 lines | Open-source (large) |
+| Deploy | `pip install` + API key | Multi-service orchestration | CLI + subscription |
+| Browser | Injects into real browser (keeps login state) | Sandboxed/headless | Via MCP plugins |
+| OS Control | Keyboard, mouse, vision, ADB | Multi-agent delegation | File + terminal |
+| Self-evolution | Grows SOPs & tools autonomously | Plugin ecosystem | Stateless per session |
+| Core shipped | 10 .py + 5 SOPs | Hundreds of modules | Rich CLI toolkit |
+
+## How It Works
+
+```
+User instruction
+      ↓
+┌─────────────────────┐
+│  agent_loop.py (92L) │  ← Sense-Think-Act cycle
+│  "What do I know?    │
+│   What should I do?" │
+└────────┬────────────┘
+         ↓
+┌─────────────────────┐
+│  7 Atomic Tools      │  ← All capabilities derive from these
+│  code_run            │     Execute any Python/PowerShell
+│  file_read/write     │     Direct disk access
+│  file_patch          │     Surgical code edits
+│  web_scan            │     Read live web pages
+│  web_execute_js      │     Control browser DOM
+│  ask_user            │     Human-in-the-loop
+└────────┬────────────┘
+         ↓
+┌─────────────────────┐
+│  Memory System       │  ← Persistent across sessions
+│  L0: Meta-SOP        │     How to manage memory itself
+│  L2: Global Facts    │     Environment, credentials, paths
+│  L3: Task SOPs       │     Learned procedures (self-growing)
+└─────────────────────┘
+```
+
+The agent starts with 7 primitive tools. Through `code_run`, it can install packages, write scripts, and interface with any hardware or API — effectively manufacturing new tools at runtime.
+
+<details>
+<summary>What Ships in the Box</summary>
+
+**Core engine** (runs the agent):
+- `agent_loop.py` — Sense-Think-Act loop (92 lines)
+- `ga.py` — Tool definitions and execution
+- `sidercall.py` — LLM communication (multi-backend)
+- `agentmain.py` — Session orchestration
+
+**Interface** (talk to the agent):
+- `stapp.py` — Streamlit web UI
+- `tgapp.py` — Telegram bot interface
+- `launch.pyw` — One-click launcher with floating window
+
+**Infrastructure**:
+- `TMWebDriver.py` — Browser injection bridge (not Selenium — injects JS into your real browser via Tampermonkey)
+- `simphtml.py` — HTML→text cleaner for web perception
+
+**5 Core SOPs** (shipped, version-controlled):
+1. `memory_management_sop` — L0 constitution: how the agent manages its own memory
+2. `autonomous_operation_sop` — Self-directed task execution
+3. `scheduled_task_sop` — Cron-like recurring tasks
+4. `web_setup_sop` — Browser environment bootstrap
+5. `ljqCtrl_sop` — Desktop physical control (keyboard, mouse, DPI-aware)
+
+Everything else — Gmail integration, WeChat automation, vision APIs, game downloaders, stock analysis workflows — the agent builds and memorizes on its own through use.
+
+</details>

 ---

 <a name="chinese"></a>

-# PC-Agent-Loop: 高性能 PC 级自主 AI Agent
+# GenericAgent — 3,300 行代码，完整 OS 级自主控制

-pc-agent-loop 是一个极致简约的 PC 级自主 AI Agent 框架。它通过不到 100 行的核心引擎代码，构筑了对浏览器、终端和文件系统的物理级自动化能力。
+一个极简自主 Agent 框架。用约 3,300 行 Python，让任意 LLM 获得对你 PC 的物理级控制能力——浏览器、终端、文件系统、键鼠、屏幕视觉、移动设备。

-## 🚀 进化智能与扩展性
+不需要 Electron，不需要 Docker，不需要 Mac Mini，不需要 53 万行代码，不需要付费安装服务。

-本 Agent 不局限于预设功能。其核心优势在于能够**自主发现环境特定能力**并**制造属于自己的工具**：
+## 用起来是什么样的

- **基于长期记忆的自我发现**: 
-  - Agent 维护“全局记忆”（L2 Facts）以存储系统路径、凭据和环境状态。
-  - 能够自主检索上下文相关的 SOP（标准作业程序），以处理即时通讯软件（IM）数据库恢复、Gmail API 操作等专业任务。
- **动态工具制造**:
-  - 通过 `code_run`，Agent 可以编写并执行 Python/PowerShell 脚本来对接新硬件或软件。
-  - **自集成能力示例**:
-    - **深度 Web 自动化**: 通过 Tampermonkey 进行 JS 注入实现 UI 自动化。
-    - **数字取证**: 查询 SQLCipher 加密的数据库（如加密的本地 IM 数据库）。
-    - **视觉驱动逻辑**: 通过本地视觉 API (`ask_vision`) 理解 UI 状态。
-    - **系统全盘索引**: 利用 **Everything CLI (es.exe)** 实现毫秒级文件检索。
-    - **安卓自动化**: 基于 ADB 控制移动设备交互。
+```
+你："帮我读取微信消息"
+Agent：安装依赖 → 逆向数据库 → 写读取脚本 → 保存为 SOP
+下次：一句话直接调用，零配置。

-## 📂 项目结构
+你："帮我监控股票并提醒"
+Agent：安装 mootdx → 构建选股工作流 → 设置定时任务 → 保存为 SOP
+下次：一句话启动。

- `agent_loop.py`: 核心引擎，负责“感知-思考-行动”的自主循环逻辑。
- `ga.py`: 工具箱，定义了原子工具的具体实现。
- `agentapp.py` & `launch.pyw`: 基于 Streamlit 的交互界面与持久化启动器。
- `sidercall.py`: LLM 通信层，支持多后端切换。
+你："用 Gmail 发这个文件"
+Agent：配置 OAuth → 写发送脚本 → 保存为 SOP
+下次：直接能用。
+```

-## 🛠️ 典型使用场景
+**自举实证**：本仓库从安装 Git、`git init`、编写 README 到每一条 commit message，全程由 GenericAgent 完成——作者没有打开过一次终端。

-1. **环境自适应**: “扫描我的本地记忆寻找邮件处理 SOP，然后从 Gmail 下载最新的报销收据。”
-2. **跨模块协作**: “定位特定的加密 IM 数据库并解密，查找关于‘项目 X’的消息，并汇总成 PDF 报告。”
-3. **系统干预**: “监控云端控制台，若状态异常则执行本地脚本重启服务并邮件通知我。”
+每个解决过的任务都会变成永久技能。用几周后，你的 Agent 实例会拥有一套独特的技能树——全部从 3,300 行种子代码中生长出来。

-## 🧩 7 大核心原子工具
+## 自举哲学

-1. `code_run`: 终极工具，执行 Python/PowerShell 脚本。
-2. `web_scan`: 网页与标签页的语义化感知。
-3. `web_execute_js`: 物理级网页操控（点击、滚动、数据提取）。
-4. `file_read` & `file_write`: 磁盘文件直接访问。
-5. `file_patch`: 安全的源码级局部修改。
-6. `ask_user`: 关键决策或凭据输入时的人机协作。
-7. `conclude_and_reflect`: 将执行经验提炼进长期记忆的机制。
+多数 Agent 框架以成品形态发布。GenericAgent 以**种子**形态发布。

-## ⚠️ 警告
-本 Agent 具备执行本地代码和控制操作系统的**物理权限**。请务必在受信任的环境中运行。
+5 个核心 SOP 定义了 Agent 如何思考、记忆和行动。之后的一切能力，由 Agent 在使用中自主发现并记录：

---
-*Note: This README was autonomously generated and refined by the Agent.*
+1. 你让它做一件新事
+2. 它自己摸索方法（安装依赖、写脚本、测试）
+3. 把流程保存为新 SOP
+4. 下次直接调用
+
+Agent 不只是执行——它**学习并记忆**。
+
+## 快速开始
+
+```bash
+# 1. 克隆
+git clone https://github.com/lsdefine/pc-agent-loop.git
+cd pc-agent-loop
+
+# 2. 安装最小依赖
+pip install streamlit pywebview
+
+# 3. 配置 API Key
+cp mykey_template.py mykey.py
+# 编辑 mykey.py 填入你的 LLM API Key
+
+# 4. 启动
+python launch.pyw
+```
+
+启动后告诉 Agent："执行 web setup SOP 解锁浏览器工具"——剩下的它自己搞定。完整引导流程见 [WELCOME_NEW_USER.md](WELCOME_NEW_USER.md)。
+
+## 对比
+
+| | GenericAgent | OpenClaw | Claude Code |
+|---|---|---|---|
+| 代码量 | ~3,300 行 | ~530,000 行 | 已开源（体量大） |
+| 部署 | `pip install` + API key | 多服务编排 | CLI + 订阅 |
+| 浏览器 | 注入真实浏览器（保留登录态） | 沙箱/无头浏览器 | 通过 MCP 插件 |
+| OS 控制 | 键鼠、视觉、ADB | 多 Agent 委派 | 文件 + 终端 |
+| 自我进化 | 自主生长 SOP 和工具 | 插件生态 | 会话间无状态 |
+| 出厂配置 | 10 个 .py + 5 个 SOP | 数百模块 | 丰富 CLI 工具集 |
+
+## 工作原理
+
+Agent 拥有 7 个原子工具：`code_run`（执行任意代码）、`file_read/write/patch`（文件操作）、`web_scan`（网页感知）、`web_execute_js`（浏览器控制）、`ask_user`（人机协作）。
+
+通过 `code_run`，它可以安装任何包、编写任何脚本、对接任何硬件——相当于在运行时制造新工具。学到的流程保存为 SOP，下次直接调用。
+
+核心循环只有 92 行（`agent_loop.py`）：感知 → 思考 → 行动 → 记忆。
+
+<details>
+<summary>出厂清单</summary>
+
+**核心引擎**：
+- `agent_loop.py` — 感知-思考-行动循环（92 行）
+- `ga.py` — 工具定义与执行
+- `sidercall.py` — LLM 通信（多后端）
+- `agentmain.py` — 会话编排
+
+**交互界面**：
+- `stapp.py` — Streamlit Web UI
+- `tgapp.py` — Telegram 机器人
+- `launch.pyw` — 一键启动 + 悬浮窗
+
+**基础设施**：
+- `TMWebDriver.py` — 浏览器注入桥接（非 Selenium，通过 Tampermonkey 注入真实浏览器）
+- `simphtml.py` — HTML→文本清洗
+
+**5 个核心 SOP**（出厂自带，版本控制）：
+1. `memory_management_sop` — L0 宪法：Agent 如何管理自身记忆
+2. `autonomous_operation_sop` — 自主任务执行
+3. `scheduled_task_sop` — 定时任务
+4. `web_setup_sop` — 浏览器环境引导
+5. `ljqCtrl_sop` — 桌面物理控制（键鼠、DPI 感知）
+
+其余一切——Gmail、微信自动化、视觉 API、游戏下载、股票分析——都是 Agent 在使用中自主构建并记忆的。
+
+</details>
+
+## 许可
+
+MIT
--- a/agentmain.py
+++ b/agentmain.py
@@ -126,7 +126,7 @@ if __name__ == '__main__':
            m = re.match(r'(\d{4}-\d{2}-\d{2})_(\d{4})_', f)
            if m and now >= datetime.strptime(f'{m[1]} {m[2]}', '%Y-%m-%d %H%M'):
                raw = open(f'./tasks/pending/{f}', encoding='utf-8').read()
-                dq = agent.put_task(f'按scheduled_task_sop执行任务文件 ./tasks/pending/{f}（立刻移到running）\n内容：\n{raw}', source='scheduler')
+                dq = agent.put_task(f'按scheduled_task_sop执行任务文件 ../tasks/pending/{f}（立刻移到running）\n内容：\n{raw}', source='scheduler')
                threading.Thread(target=drain, args=(dq, f), daemon=True).start()
                break
        time.sleep(55 + random.random() * 10)
--- a/memory/autonomous_operation_sop.md
+++ b/memory/autonomous_operation_sop.md
@@ -7,15 +7,17 @@

 ## 🎯 核心目标（按价值优先级排序）

-1. **探索性学习**：发现新工具/API/优化模式
-2. **上网冲浪**：学习新知识
-3. **优化工具**：改进代码性能/可维护性
-4. **发现潜在问题**：预判失败场景并设计测试
-5. **审查记忆系统**：修正错误或过时记录，修正未按L0的记忆编排
+1. **能力扩展**：主动发现用户环境中已有但未被利用的工具/库/数据源（扫描pip list、项目目录、配置文件），形成可复用操作知识
+2. **知识学习**：上网冲浪、文档阅读，学习新技术/新领域知识，扩展认知边界
+3. **探索性实验**：对发现的工具/API进行实际测试验证，产出可操作经验（非停留文档层面）
+4. **优化工具**：改进代码性能/可维护性
+5. **发现潜在问题**：预判失败场景并设计测试
+6. **审查记忆系统**：修正错误或过时记录（低频执行）

 ### 选择原则
- **增量价值优先**：必须产生新知识/新能力
- **假设驱动**：明确"要验证什么假设"
+- **增量价值优先**：必须产生新知识/新能力，优先选择能扩展自身操作能力的任务
+- **自主发现**：主动扫描用户环境（pip list、项目目录、配置文件）发现未知工具，而非等用户告知
+- **假设驱动**：明确"要验证什么假设"，实验必须有动手验证环节
 - **禁止低价值验证**：不验证 global_mem 中的静态配置，不做无假设的巡检

 主要目标是让你未来更加强大。探索的核心产出是记忆——每次运行应将有价值的发现（用户偏好、环境事实、新知识）整理为记忆更新提案，纳入报告待用户审批后写入。
@@ -27,16 +29,16 @@
 ### 阶段 1：自主探测（用户离开时）
 - **启动检查**：
  - 读取可能有的 `./autonomous_reports/history.txt` 了解历史记录。
-  - **不连续两次选择相同子任务**（除非间隔很久或环境显著变化）。
+  - **不连续两次选择相同子任务**（除非间隔很久或环境显著变化）。同一网站算同一子任务，不同网站算不同。
 - **执行方式**：基于目标自由进行，无需预先批准，直接执行只读或实验性操作。
 - **约束**：小步快跑，每次只做一个小任务（剩下的下次再做），控制在15个回合以内。严禁修改核心记忆/系统设置；严禁读取敏感数据（但可以检测存在性）。

 ### 阶段 2：生成报告与方案
 - **位置**：目录若不存在请新建
-  - 最新报告：`./autonomous_reports/latest.txt`
-  （若存在，先从首行 [探测时间] 提取时间戳，重命名为 `YYYY-MM-DD_HHMM.txt`）
-  - 历史索引：`./autonomous_reports/history.txt`（prepend单行摘要，报告写完后必须立即更新）
- **格式**：包含 [探测时间]、[子任务]、[探测目标]、[过程]、[发现]、[记忆更新提案(待审)]、[执行方案(待批)]、[可能收益]。
+  - 报告文件：`./autonomous_reports/RXX_简短描述.md`（XX为自增序号，从history.txt末尾推断下一个编号）
+  - 历史索引：`./autonomous_reports/history.txt`（每条任务一行，报告写完后必须append）
+  - 已处理报告归档至 `./autonomous_reports/archived/`
+- **history.txt格式**：请先查看此文件来获取详细格式，`#XX | 日期 | 类型 | 主题 | 结论`（严格单行，禁止换行）
 - **篇幅**：默认简洁，仅关键发现详述

 ### 阶段 3：等待批准
@@ -55,6 +57,7 @@

 ## 📝 探测领域（示例，鼓励发散，不要总盯着技术/agent）
 - 上网冲浪（科技/科学/文化/时事热点，视野要广）
+  - ⚠️ 禁止泛采集标题列表（零价值）。必须：选≤2个话题深入读正文提炼观点，或带明确目标搜索（如接口文档）。导航受限无法读正文时立即换方向。
 - 实用小工具（写脚本解决日常痛点，如批量重命名、格式转换）
 - 信息聚合（天气、新闻摘要、特定话题最新动态）
 - 本地环境健康（磁盘空间、过期大文件、异常进程）
@@ -64,4 +67,5 @@
 - 了解用户（从PC上的文件/目录/浏览器书签等推断用户兴趣和偏好，不读密钥文件）
 - 推荐（基于对用户的了解，推荐游戏/视频/工具/脚本等，附理由）
 - 自身演进（思考框架的不足或新需求，提出改进方案供用户审批）
- SOP/记忆维护（审查脚本可用性、路径有效性，但不要每次都选这个）
+- SOP/记忆维护（审查脚本可用性、路径有效性，但不要每次都选这个）
+- 整理cwd（清理临时文件、归档过期产物、检查磁盘占用）
--- a/memory/scheduled_task_sop.md
+++ b/memory/scheduled_task_sop.md
@@ -9,3 +9,5 @@
 3. 读文件执行
 4. 完成→移到done/，**在文件内追加执行报告**供用户查阅
 5. schedule非once→算下次时间，新建文件到pending/
+
+注意tasks目录在../，即你的code root下
--- a/tgapp.py
+++ b/tgapp.py
@@ -1,4 +1,4 @@
-import os, sys, re, threading, asyncio, queue as Q, socket
+import os, sys, re, threading, asyncio, queue as Q, socket, time
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from agentmain import GeneraticAgent
 from telegram import Update
@@ -90,11 +90,19 @@ if __name__ == '__main__':
        _lock_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM); _lock_sock.bind(('127.0.0.1', 19527))
    except OSError: sys.exit('Another instance is already running.')
    if not ALLOWED: sys.exit('ERROR: tg_allowed_users in mykey.py is empty or missing. Set it to avoid unauthorized access.')
+    _logf = open(os.path.join(os.path.dirname(__file__), 'temp', 'tgapp.log'), 'a', encoding='utf-8', buffering=1)
+    sys.stdout = sys.stderr = _logf
    threading.Thread(target=agent.run, daemon=True).start()
    proxy = vars(mykey).get('proxy', 'http://127.0.0.1:2082')
+    print('proxy:', proxy)
    app = ApplicationBuilder().token(mykey.tg_bot_token).proxy(proxy).get_updates_proxy(proxy).build()
    app.add_handler(CommandHandler("stop", cmd_abort))
    app.add_handler(CommandHandler("llm", cmd_llm))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_msg))
-    print("TG bot running...")
-    app.run_polling()
+    print(f"TG bot starting... {time.strftime('%m-%d %H:%M')}")
+    while True:
+        try:
+            app.run_polling(drop_pending_updates=True)
+        except Exception as e:
+            print(f"[{time.strftime('%m-%d %H:%M')}] polling crashed: {e}", flush=True)
+            time.sleep(10)