Show HN：White Collar Agent - 一款具備 TUI 介面的電腦任務 AI 代理

White Collar Agent

---

🚀 概覽

White Collar Agent 是一個極簡但功能強大的電腦使用 AI 代理，能夠執行一系列複雜的電腦端和瀏覽器端任務。
它能夠自主地解析任務、規劃行動並執行行動以達成複雜目標。根據任務性質，它可以切換 CLI 和 GUI 模式。該程式碼也可作為建構您自己智慧代理的基礎。

使用者可以：

• 🧠 使用內建代理自動規劃和執行複雜的任務系列
• 🧩 繼承基礎代理以建構自己專門的代理行為或工作流程
• 💻 與代理透過 TUI 介面互動。

這使其成為組織、研究人員和開發人員探索系統式代理 AI、執行時期程式碼生成和自主執行以自動化其工作流程並達成結果的理想工具。這是一個開源專案，仍在開發中，因此我們歡迎任何建議、貢獻和回饋！您可以自由使用、託管和貨幣化此專案（在發布和貨幣化時請給予鳴謝）。

---

✨ 特點

• 🧠 單一基礎代理架構 — 簡單、可擴展的核心，負責推理、規劃和執行。
• ⚙️ CLI/GUI 模式 — 代理可根據任務的複雜性在 CLI 和 GUI 模式之間切換。GUI 模式仍處於實驗階段 🧪。
• 🧩 繼承與擴展 — 透過繼承基礎類別來建構您自己的代理。
• 🔍 任務文件介面 — 定義結構化任務，供代理進行上下文學習。
• 🧰 動作庫 — 可重複使用的工具（網路搜尋、程式碼執行、I/O 等）。
• 🪶 輕量級與跨平台 — 無縫支援 Linux 和 Windows。

重要提示

GUI 模式注意事項： GUI 模式仍處於實驗階段。這意味著當代理決定切換到 GUI 模式時，您會遇到許多問題。我們仍在努力改進。

🔜 未來規劃

• 記憶體模組 — 即將推出！
• 外部工具整合 — 待定
• MCP 層 — 待定
• 主動行為 — 待定

---

🧰 開始使用

先決條件

• Python 3.9+
• git、conda 和 pip
• 您選擇的 LLM 提供者（例如 OpenAI 或 Gemini）的 API 金鑰

安裝

git clone https://github.com/zfoong/White-Collar-Agent.git
cd White-Collar-Agent
conda env create -f environment.yml

---

⚡ 快速入門

匯出您的 API 金鑰：

export OPENAI_API_KEY=<YOUR_KEY_HERE>

或

export GOOGLE_API_KEY=<YOUR_KEY_HERE>

執行 CLI 工具：

python -m core.main

這將執行內建的 White Collar Agent，您可以與之互動：

1. 與代理對話
2. 要求它執行複雜的任務系列
3. 執行命令 /help 以尋求協助
4. 與 AI 代理協同工作

---

使用容器執行

儲存庫根目錄包含 Docker 配置，其中包含 Python 3.10、關鍵系統套件（包括 Tesseract OCR）以及 environment.yml/requirements.txt 中定義的所有 Python 依賴項，以便代理可以在隔離的環境中一致地執行。

以下是使用容器執行我們的代理的設定說明。

建構映像檔

從儲存庫根目錄：

docker build -t white-collar-agent .

執行容器

映像檔預設配置為使用 python -m core.main 啟動代理。要互動式執行：

docker run --rm -it white-collar-agent

如果您需要提供環境變數，請傳遞一個環境檔案（例如，基於 .env.example）：

docker run --rm -it --env-file .env white-collar-agent

使用 -v 掛載任何應在容器外部持續存在的目錄（例如資料或快取資料夾），並根據您的部署需求調整埠或額外標誌。容器內建了 OCR（tesseract）、螢幕自動化（pyautogui、mss、X11 公用程式和虛擬 framebuffer）以及常見 HTTP 用戶端的系統依賴項，以便代理可以在容器內處理檔案、網路 API 和 GUI 自動化。

啟用 GUI/螢幕自動化

GUI 操作（滑鼠/鍵盤事件、螢幕截圖）需要 X11 伺服器。您可以連接到主機顯示器，或使用 xvfb 執行無頭模式：

• 使用主機顯示器（需要 Linux 和 X11）：

  docker run --rm -it \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v $(pwd)/data:/app/core/data \
    white-collar-agent
  

  為代理應讀取/寫入的任何資料夾新增額外的 -v 掛載。

• 使用虛擬顯示器執行無頭模式：

  docker run --rm -it --env-file .env white-collar-agent bash -lc "Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 && exec python -m core.main"
  

預設情況下，映像檔使用 Python 3.10 並捆綁了 environment.yml/requirements.txt 中的 Python 依賴項，因此 python -m core.main 可以直接使用。

---

🧠 範例：建構自訂代理

您可以透過繼承基礎代理輕鬆建立自己的專門代理：

import asyncio
import os
from core.agent_base import AgentBase

class MyCustomAgent(AgentBase):
    def __init__(
        self,
        *,
        data_dir: str = "core/data",
        chroma_path: str = "./chroma_db",
    ):
        super().__init__(
            data_dir=data_dir,
            chroma_path=chroma_path,
        )
        # 您的實現

    def _generate_role_info_prompt(self) -> str:
        """
        定義此代理的角色、行為和目的。
        """
        return (
            "你是 MyCustomAgent — 一個智慧研究助理。 "
            "你的角色是從多個來源尋找、總結和綜合資訊。 "
            "你回應簡潔，優先考慮事實準確性，並在相關時引用來源。 "
            "如果你找不到某樣東西，你會解釋原因並建議替代方案。"
        )

agent = MyCustomAgent(
    data_dir=os.getenv("DATA_DIR", "core/data"),
    chroma_path=os.getenv("CHROMA_PATH", "./chroma_db"),
)
asyncio.run(agent.run())

在這裡，您重用了所有核心的規劃、推理和執行邏輯 — 只需插入您自己的個性、動作和任務文件。

---

🧩 架構概覽

組件	描述
BaseAgent	核心推理和執行引擎 — 可被繼承或直接使用。
Action / Tool	可重複使用的原子函數（例如，網路搜尋、API 調用、檔案操作）。
Task Document	描述代理必須達成什麼以及如何達成。
Planner / Executor	處理目標分解、腳本生成和執行。
LLM Wrapper	模型互動的統一層（OpenAI、Gemini 等）。

---

🤝 如何貢獻

歡迎貢獻和建議！您可以透過 @zfoong 或 thamyikfoong(at)craftos.net 與我們聯繫。我們目前沒有設定檢查機制，因此無法直接接受貢獻，但我們非常感謝任何建議和回饋。

🧾 授權

此專案根據 MIT 授權 授權。您可以自由使用、託管和貨幣化此專案（在發布和貨幣化時必須給予此專案鳴謝）。

---

⭐ 鳴謝

由 CraftOS 以及貢獻者 @zfoong 和 @ahmad-ajmal 開發和維護。
如果您覺得 White Collar Agent 有用，請給予儲存庫 ⭐ 並與他人分享！