Metadata-Version: 2.4
Name: onebot-agent
Version: 0.1.2
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 /`（Web 設定頁）
- `GET /health`
- `GET /skills`
- `GET /adapters`
- `GET /config`
- `PUT /config`（更新設定並同步寫入 `.env` 與 `onebot_config.yaml`）
- `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。
