onebot-agent 0.1.0__tar.gz

onebot_agent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Sync dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest -q
+

onebot_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish (PyPI)
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+

onebot_agent-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtualenv / uv
+.venv/
+!.python-version
+!uv.lock
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

onebot_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

onebot_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onebot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

onebot_agent-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: onebot-agent
+Version: 0.1.0
+Summary: Minimal single-agent gateway with ACP backends, skills, and messaging adapters
+Author: onebot contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: claude-code-acp>=0.4.4
+Requires-Dist: fastapi>=0.128.8
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: python-telegram-bot>=21
+Requires-Dist: rich>=14.3.2
+Requires-Dist: typer>=0.23.0
+Requires-Dist: uvicorn>=0.40.0
+Description-Content-Type: text/markdown
+
+# onebot
+
+`onebot` 是一個以 Python + uv 打造的精簡 single-agent 框架，支援：
+
+- CLI 與 Web（FastAPI + Uvicorn）
+- Telegram / LINE 作為訊息 I/O
+- Skills（相容 OpenClaw / SKILLS 的 `SKILL.md` 規範）
+- ClawHub skill 搜尋 / 安裝（透過官方 `clawhub` CLI）
+- ACP backend 切換：`gemini --acp`、`copilot --acp`、`claude-code-acp`
+- MCP servers（透過 ACP backend 傳入）
+
+> PyPI distribution 名稱：`onebot-agent`（CLI 指令：`onebot`）
+
+---
+
+## 1) 需求
+
+- Python 3.11+
+- [uv](https://github.com/astral-sh/uv)
+
+依你選的 backend，還需要：
+
+- Claude：`claude-code-acp`（由 Python 套件安裝），以及 Claude CLI 已完成登入
+- Gemini：`gemini` CLI（ACP 模式）
+- Copilot：`copilot` CLI（ACP 模式）
+
+若要使用 ClawHub skills：
+
+- `clawhub` CLI（例如：`npm i -g clawhub`）
+
+---
+
+## 2) 安裝與開發
+
+```bash
+# 進入專案
+cd onebot
+
+# 安裝（含 dev）
+uv sync --dev
+
+# 看指令
+uv run onebot --help
+```
+
+---
+
+## 3) 快速開始
+
+### 3.1 本地單次對話（ACP backend）
+
+```bash
+export ONEBOT_ACP_BACKEND=claude
+uv run onebot chat "請幫我建立一個 hello.py"
+```
+
+切換 backend：
+
+```bash
+# Gemini
+export ONEBOT_ACP_BACKEND=gemini
+export ONEBOT_ACP_COMMAND=gemini
+export ONEBOT_ACP_ARGS="--experimental-acp"
+
+# Copilot
+export ONEBOT_ACP_BACKEND=copilot
+export ONEBOT_ACP_COMMAND=copilot
+export ONEBOT_ACP_ARGS="--acp"
+```
+
+### 3.2 啟動 Web API
+
+```bash
+uv run onebot web --host 127.0.0.1 --port 18790
+```
+
+可用端點：
+
+- `GET /health`
+- `GET /skills`
+- `GET /adapters`
+- `GET /config`
+- `POST /line/webhook`
+
+### 3.3 啟動 Telegram polling
+
+```bash
+export ONEBOT_TELEGRAM_TOKEN=<your-bot-token>
+uv run onebot telegram
+```
+
+### 3.4 LINE webhook
+
+1. 設定：
+
+```bash
+export ONEBOT_LINE_CHANNEL_SECRET=<secret>
+export ONEBOT_LINE_CHANNEL_ACCESS_TOKEN=<token>
+```
+
+2. 啟動 Web：
+
+```bash
+uv run onebot web --host 0.0.0.0 --port 18790
+```
+
+3. 在 LINE Developers 把 webhook URL 設為：
+
+```text
+https://<your-domain>/line/webhook
+```
+
+---
+
+## 4) Skills / ClawHub
+
+列本地 skills：
+
+```bash
+uv run onebot skill list
+uv run onebot skill list --all
+```
+
+搜尋 / 安裝 / 更新（透過 clawhub CLI）：
+
+```bash
+uv run onebot skill search "postgres backups"
+uv run onebot skill install my-skill
+uv run onebot skill update my-skill
+uv run onebot skill update --all
+```
+
+進階 passthrough：
+
+```bash
+uv run onebot skill clawhub list
+```
+
+---
+
+## 5) MCP 設定
+
+透過 `ONEBOT_MCP_SERVERS` 以 JSON 陣列提供（會傳入 ACP backend）：
+
+```bash
+export ONEBOT_MCP_SERVERS='[
+  {
+    "name": "my-mcp",
+    "command": "uvx",
+    "args": ["my-mcp-server"]
+  }
+]'
+```
+
+> 注意：不同 backend 對 MCP 的支援程度不同（例如 Gemini 通常需要先在 CLI 內預先配置）。
+
+---
+
+## 6) 主要環境變數
+
+- `ONEBOT_WORKSPACE`（預設 `~/.onebot`）
+- `ONEBOT_ACP_BACKEND`：`claude|gemini|copilot`
+- `ONEBOT_ACP_COMMAND`：覆寫 backend command
+- `ONEBOT_ACP_ARGS`：覆寫 backend args（shell 字串）
+- `ONEBOT_MCP_SERVERS`：MCP servers JSON 陣列
+- `ONEBOT_TELEGRAM_TOKEN`
+- `ONEBOT_LINE_CHANNEL_SECRET`
+- `ONEBOT_LINE_CHANNEL_ACCESS_TOKEN`
+
+---
+
+## 7) 測試與品質
+
+```bash
+uv run ruff check .
+uv run pytest -q
+```
+
+---
+
+## 8) 發佈流程（GitHub Release -> PyPI）
+
+本專案已提供：
+
+- `.github/workflows/ci.yml`：push / PR 執行 lint + test
+- `.github/workflows/publish.yml`：Release published 時 build + publish
+
+建議使用 PyPI Trusted Publisher（OIDC）：
+
+1. 在 PyPI 專案設定 Trusted Publisher 指向本 GitHub repo/workflow
+2. GitHub 建立 Release（Published）
+3. workflow 自動 `uv build` 並上傳 `dist/*` 到 PyPI
+
+---
+
+## 9) 安全說明（目前）
+
+- ACP 的檔案讀寫與終端執行有 workspace 限制與危險指令 deny patterns。
+- 目前屬 MVP 安全層；高隔離場景建議後續加 Docker sandbox。

onebot_agent-0.1.0/README.md

@@ -0,0 +1,199 @@
+# onebot
+
+`onebot` 是一個以 Python + uv 打造的精簡 single-agent 框架，支援：
+
+- CLI 與 Web（FastAPI + Uvicorn）
+- Telegram / LINE 作為訊息 I/O
+- Skills（相容 OpenClaw / SKILLS 的 `SKILL.md` 規範）
+- ClawHub skill 搜尋 / 安裝（透過官方 `clawhub` CLI）
+- ACP backend 切換：`gemini --acp`、`copilot --acp`、`claude-code-acp`
+- MCP servers（透過 ACP backend 傳入）
+
+> PyPI distribution 名稱：`onebot-agent`（CLI 指令：`onebot`）
+
+---
+
+## 1) 需求
+
+- Python 3.11+
+- [uv](https://github.com/astral-sh/uv)
+
+依你選的 backend，還需要：
+
+- Claude：`claude-code-acp`（由 Python 套件安裝），以及 Claude CLI 已完成登入
+- Gemini：`gemini` CLI（ACP 模式）
+- Copilot：`copilot` CLI（ACP 模式）
+
+若要使用 ClawHub skills：
+
+- `clawhub` CLI（例如：`npm i -g clawhub`）
+
+---
+
+## 2) 安裝與開發
+
+```bash
+# 進入專案
+cd onebot
+
+# 安裝（含 dev）
+uv sync --dev
+
+# 看指令
+uv run onebot --help
+```
+
+---
+
+## 3) 快速開始
+
+### 3.1 本地單次對話（ACP backend）
+
+```bash
+export ONEBOT_ACP_BACKEND=claude
+uv run onebot chat "請幫我建立一個 hello.py"
+```
+
+切換 backend：
+
+```bash
+# Gemini
+export ONEBOT_ACP_BACKEND=gemini
+export ONEBOT_ACP_COMMAND=gemini
+export ONEBOT_ACP_ARGS="--experimental-acp"
+
+# Copilot
+export ONEBOT_ACP_BACKEND=copilot
+export ONEBOT_ACP_COMMAND=copilot
+export ONEBOT_ACP_ARGS="--acp"
+```
+
+### 3.2 啟動 Web API
+
+```bash
+uv run onebot web --host 127.0.0.1 --port 18790
+```
+
+可用端點：
+
+- `GET /health`
+- `GET /skills`
+- `GET /adapters`
+- `GET /config`
+- `POST /line/webhook`
+
+### 3.3 啟動 Telegram polling
+
+```bash
+export ONEBOT_TELEGRAM_TOKEN=<your-bot-token>
+uv run onebot telegram
+```
+
+### 3.4 LINE webhook
+
+1. 設定：
+
+```bash
+export ONEBOT_LINE_CHANNEL_SECRET=<secret>
+export ONEBOT_LINE_CHANNEL_ACCESS_TOKEN=<token>
+```
+
+2. 啟動 Web：
+
+```bash
+uv run onebot web --host 0.0.0.0 --port 18790
+```
+
+3. 在 LINE Developers 把 webhook URL 設為：
+
+```text
+https://<your-domain>/line/webhook
+```
+
+---
+
+## 4) Skills / ClawHub
+
+列本地 skills：
+
+```bash
+uv run onebot skill list
+uv run onebot skill list --all
+```
+
+搜尋 / 安裝 / 更新（透過 clawhub CLI）：
+
+```bash
+uv run onebot skill search "postgres backups"
+uv run onebot skill install my-skill
+uv run onebot skill update my-skill
+uv run onebot skill update --all
+```
+
+進階 passthrough：
+
+```bash
+uv run onebot skill clawhub list
+```
+
+---
+
+## 5) MCP 設定
+
+透過 `ONEBOT_MCP_SERVERS` 以 JSON 陣列提供（會傳入 ACP backend）：
+
+```bash
+export ONEBOT_MCP_SERVERS='[
+  {
+    "name": "my-mcp",
+    "command": "uvx",
+    "args": ["my-mcp-server"]
+  }
+]'
+```
+
+> 注意：不同 backend 對 MCP 的支援程度不同（例如 Gemini 通常需要先在 CLI 內預先配置）。
+
+---
+
+## 6) 主要環境變數
+
+- `ONEBOT_WORKSPACE`（預設 `~/.onebot`）
+- `ONEBOT_ACP_BACKEND`：`claude|gemini|copilot`
+- `ONEBOT_ACP_COMMAND`：覆寫 backend command
+- `ONEBOT_ACP_ARGS`：覆寫 backend args（shell 字串）
+- `ONEBOT_MCP_SERVERS`：MCP servers JSON 陣列
+- `ONEBOT_TELEGRAM_TOKEN`
+- `ONEBOT_LINE_CHANNEL_SECRET`
+- `ONEBOT_LINE_CHANNEL_ACCESS_TOKEN`
+
+---
+
+## 7) 測試與品質
+
+```bash
+uv run ruff check .
+uv run pytest -q
+```
+
+---
+
+## 8) 發佈流程（GitHub Release -> PyPI）
+
+本專案已提供：
+
+- `.github/workflows/ci.yml`：push / PR 執行 lint + test
+- `.github/workflows/publish.yml`：Release published 時 build + publish
+
+建議使用 PyPI Trusted Publisher（OIDC）：
+
+1. 在 PyPI 專案設定 Trusted Publisher 指向本 GitHub repo/workflow
+2. GitHub 建立 Release（Published）
+3. workflow 自動 `uv build` 並上傳 `dist/*` 到 PyPI
+
+---
+
+## 9) 安全說明（目前）
+
+- ACP 的檔案讀寫與終端執行有 workspace 限制與危險指令 deny patterns。
+- 目前屬 MVP 安全層；高隔離場景建議後續加 Docker sandbox。

onebot_agent-0.1.0/plan.md

@@ -0,0 +1,170 @@
+onebot 計劃（可正式發佈版）
+
+本文件是「可一路做到正式發佈、可用、可維護」的完整工作計劃；接下來會依此逐步實作並以 commit 方式交付。
+
+---
+
+## 0. 目標 / 範圍
+
+### 目標
+
+- 建立可發佈至 PyPI 的 Python 套件（distribution 名稱暫定：`onebot-agent`；import module：`onebot`）。
+- 提供單一 agent（single-agent）架構：
+  - **CLI**（Typer）：啟動、狀態、技能管理、ACP backend 設定。
+  - **Web**（FastAPI + Uvicorn）：健康檢查、技能/adapter 列表、基本管理 API。
+- 支援通訊通道作為 I/O：
+  - Telegram（MVP：polling；後續可加 webhook）
+  - LINE（M1：webhook）
+- 支援兩種執行能力：
+  - **Skills**：相容 OpenClaw / SKILLS 規範（`skills/<name>/SKILL.md` YAML frontmatter）。
+  - **MCP**：可配置 MCP servers 並交由 ACP agent 使用（支援程度依 backend 而定）。
+- 支援 **ACP 相容 agent backend**（可切換）：
+  - `gemini --acp`（實際多為 `--experimental-acp`；以設定檔可覆寫）
+  - `copilot --acp`
+  - Python ClaudeAcpAgent：採用 `claude-code-acp`（https://github.com/yazelin/claude-code-acp-py）
+- 依 GitHub Release 自動發佈至 PyPI（GitHub Actions）。
+
+### 非目標（先不做）
+
+- 多 agent / 多租戶（multi-tenant）路由。
+- 內建大型前端 SPA（MVP 只提供 API，必要時加最小靜態頁）。
+
+---
+
+## 1. 技術選型
+
+- Python：3.12（最低支援 3.11；依依賴調整）
+- Web：FastAPI + Uvicorn
+- CLI：Typer + Rich
+- 設定：pydantic-settings（env + config 檔）
+- 套件/環境管理：**uv（Astral uv）**
+  - 開發：`uv sync` / `uv run ...`
+  - 建置：`uv build`
+- ACP：使用 `claude-code-acp` 的 `AcpClient`（避免自行實作 ACP 協議）
+- Telegram：python-telegram-bot（async）
+- LINE：line-bot-sdk（webhook）
+
+---
+
+## 2. 架構（最小可用、可擴充）
+
+### 核心元件
+
+- `Workspace`
+  - 管理 workspace 路徑、skills 安裝位置、暫存、設定檔。
+- `SkillRegistry`
+  - 掃描/解析 skills（`SKILL.md` frontmatter）。
+  - 建立 skills summary（供 prompt 注入）。
+  - gating：requires.bins/env/os（缺少則標示 unavailable）。
+- `AcpBackend`
+  - 包裝 `claude_code_acp.AcpClient`。
+  - 支援 backend profile：`claude|gemini|copilot`（command/args 可覆寫）。
+  - 提供：start session / prompt / stream text。
+  - 實作 hooks：permission / file read-write / terminal exec（安全限制）。
+- `TransportAdapter`
+  - Telegram / LINE / CLI。
+  - 統一 `start()`、`stop()`、`send()`、`on_message(cb)`。
+- `Gateway`
+  - inbound message -> (build prompt) -> acp backend -> outbound reply。
+
+### Skills 與 ClawHub
+
+- Skills 格式：遵循 OpenClaw 慣例：`skills/<name>/SKILL.md`（YAML frontmatter：name/description/metadata）。
+- ClawHub 搜尋/安裝：
+  - **MVP：包裝 ClawHub 官方 CLI**（`clawhub search/install/update/list`）。
+  - 預設安裝路徑：`<workspace>/skills`（與 OpenClaw 的 workspace skills 相容）。
+  - 若未安裝 `clawhub`：回傳明確指引（npm/pnpm/bun 安裝）。
+
+### Skills 執行隔離
+
+- 預設：subprocess + per-skill virtualenv
+  - venv：**Python 標準 `venv` 模組**（每個 skill 一個 `.venv`）
+  - 安裝依賴：可用 `uv pip` 或 `pip`（依環境）
+  - 執行：`asyncio.create_subprocess_shell` / `create_subprocess_exec`
+  - 安全 guard：deny patterns（參考 nanobot ExecTool）+ 限制 cwd 於 workspace
+- 選配（M2）：Docker sandbox（高隔離）
+
+### MCP 支援
+
+- 以「backend 能力」為主：
+  - `claude-code-acp`：可動態帶入 MCP servers
+  - `gemini`：通常需先用 gemini CLI 設定 MCP，再以 allowlist 啟用（依 CLI 行為）
+- onebot 先提供：
+  - config 中的 mcp server 定義
+  - 啟動 backend session 時傳入（若 backend 支援）
+
+---
+
+## 3. 設定（Config）
+
+MVP 先做：env + 可選 `onebot.toml`。
+
+必要設定（MVP）：
+
+- Workspace
+  - `ONEBOT_WORKSPACE`（預設：`~/.onebot`）
+
+- ACP backend
+  - `ONEBOT_ACP_BACKEND`：`claude|gemini|copilot`
+  - `ONEBOT_ACP_COMMAND`：覆寫 command（例：`gemini`）
+  - `ONEBOT_ACP_ARGS`：覆寫 args（例：`--experimental-acp`）
+
+- Telegram
+  - `ONEBOT_TELEGRAM_TOKEN`
+
+- LINE（M1）
+  - `ONEBOT_LINE_CHANNEL_SECRET`
+  - `ONEBOT_LINE_CHANNEL_ACCESS_TOKEN`
+
+---
+
+## 4. 測試與品質
+
+- Ruff（lint）
+- Pytest + pytest-asyncio
+- FastAPI：httpx ASGI 測試
+- 覆蓋範圍（最低）：
+  - skill parser / registry
+  - guard（deny patterns / workspace restriction）
+  - clawhub wrapper（以 mock subprocess）
+  - acp backend wrapper（以 mock / 或 integration 標記）
+
+---
+
+## 5. CI/CD（GitHub Release -> PyPI）
+
+- PR/Push：lint + test
+- Release（published）：
+  - `uv build`
+  - 發佈到 PyPI
+
+建議：PyPI Trusted Publisher（OIDC）。備援：`PYPI_API_TOKEN`。
+
+---
+
+## 6. 工作拆解（以 commit 逐步交付）
+
+> 每一項至少 1 個 commit；完成後會回來更新本清單。
+
+- [x] C01：初始化 git + uv 專案骨架（pyproject、src layout、README、LICENSE）
+- [x] C02：核心 Workspace/Config（pydantic-settings）
+- [x] C03：Skills：SKILL.md 解析 + SkillRegistry + list/summary
+- [x] C04：ClawHub wrapper：`onebot skill search/install/update/list`（subprocess 呼叫 clawhub）
+- [x] C05：ACP backend：整合 `claude-code-acp` 的 `AcpClient`（claude/gemini/copilot profiles）
+- [x] C06：Terminal/FS 安全層：workspace 限制 + deny patterns（參考 nanobot）
+- [x] C07：Gateway：inbound message -> acp prompt -> outbound reply
+- [x] C08：Telegram adapter（polling）：可收訊息並回覆
+- [x] C09：FastAPI：`/health` `/skills` `/adapters`（最小可用）
+- [x] C10：測試（pytest）+ GitHub Actions（lint/test/release）
+- [x] C11：文件補齊：快速上手、設定、skill/MCP/ACP、發佈流程
+
+---
+
+## 7. 驗收標準（正式可用）
+
+- `uv sync` 後可用 `uv run onebot --help`
+- `uv run onebot web` 可啟動 FastAPI（`/health` 回 200）
+- `uv run onebot telegram` 可 polling 並回覆訊息（需 token）
+- `uv run onebot skill list` 可列出 skills（內建 + workspace）
+- `uv run onebot skill search <q>` 可透過 clawhub CLI 查詢（已安裝 clawhub 時）
+- GitHub Release 觸發 build/publish workflow（可先 dry-run 驗證）