tg-agent 1.2.2 → 1.2.4

package/README.cn.md

@@ -0,0 +1,199 @@
+# tg-agent
+
+一个在本地运行的 Telegram 机器人，支持多家 LLM 提供商（Codex、Claude Code、Antigravity 等），支持账号登录（OAuth）和 API 密钥认证。处理对话、工具调用与会话管理，支持多会话、会话持久化、/stop 中断、工具状态回写，适合在 macOS 上长期运行。
+
+## 功能
+
+- Telegram 私聊与群组交互（支持论坛话题）
+- 多会话管理：/new /list /use /close /reset
+- 会话持久化：默认保存到 `~/.tg-agent/tg-sessions`
+- 运行中可取消：/stop
+- 自动 Markdown 渲染：优先 MarkdownV2，失败回退 Markdown，再回退纯文本
+- 多 Provider / 多 Model 选择（支持 Codex / antigravity / Gemini CLI 等）
+- OAuth 登录与注销（/login, /logout）
+- 工具调用：内置 `fetch`，可选 MCP（HTTP/stdio）
+- 多媒体文件支持：图片、文档、音频、视频、语音、视频笔记
+- 代理支持：模型与工具请求可分别配置
+- 工作区管理：可为不同聊天设置独立工作目录
+
+## 快速开始
+
+1) 全局安装
+
+```bash
+npm install -g tg-agent
+```
+
+2) 运行
+
+```bash
+tg-agent
+```
+
+首次运行会提示输入 `telegram.bot_token`，并写入到 `~/.tg-agent/config.toml`。
+
+3) 配置文件（可选）
+
+你可以手动创建或编辑 `~/.tg-agent/config.toml`，最小示例如下：
+
+```toml
+[telegram]
+bot_token = "YOUR_BOT_TOKEN"
+```
+
+## 使用说明
+
+在 Telegram 中发送以下命令：
+
+### 会话管理
+
+- `/new [title]` - 创建新会话
+- `/list` - 列出所有会话
+- `/use <id>` - 切换到指定会话
+- `/close [id]` - 关闭会话（默认关闭当前会话）
+- `/reset` - 清空当前会话历史
+- `/stop` - 终止当前正在处理的请求
+
+### 模型与 Provider
+
+- `/providers` - 列出所有可用的 Provider
+- `/models [provider]` - 列出指定 Provider 的模型（不指定则显示当前会话的 Provider）
+- `/provider <name>` - 设置当前会话的 Provider
+- `/model <provider>/<model>` - 设置当前会话的模型
+
+### 工作区与工具
+
+- `/workspace [path]` - 查看或设置当前会话的工作区目录
+- `/mcp` - 查看 MCP 服务器与连接状态
+- `/mcp refresh` - 刷新 MCP 目录
+- `/status` - 查看当前会话的模型和工作区设置
+
+### 认证
+
+- `/login <provider>` - OAuth 登录到指定 Provider
+- `/logout <provider>` - 退出指定 Provider 的登录
+
+### 帮助
+
+- `/start` 或 `/help` - 显示命令帮助
+
+**注意**：默认仅支持私聊（DM）。如需在群组中使用，请配置 `telegram.allowed_user_ids` 白名单。
+
+### 图片与文件
+
+- 直接发送图片、文档、音频、视频、语音或视频笔记给机器人，文件会保存到 `~/.tg-agent/uploads`，并自动附加到提示词中
+- 图片会作为多模态输入传给模型（若模型支持图像）
+- Agent 可使用 `send_photo` / `send_file` 工具把本地文件发回 Telegram（路径需在工作目录或 uploads 下）
+
+## 配置文件
+
+所有配置统一放在 `~/.tg-agent/config.toml`。首次启动会提示输入 `telegram.bot_token`，其余字段使用默认值。
+
+### 完整配置示例
+
+```toml
+[telegram]
+bot_token = "YOUR_BOT_TOKEN"
+allowed_user_ids = ["123456789"]
+parse_mode = ""
+
+[model]
+provider = "openai-codex"
+model = "gpt-5.2"
+openai_api_key = ""
+
+[paths]
+workspace_dir = ""
+session_dir = "~/.tg-agent/tg-sessions"
+
+[workspace_mappings]
+# 为特定聊天 ID 设置独立工作区
+# "-123456789" = "~/projects/project-a"
+
+[limits]
+max_sessions = 5
+max_concurrent = 5
+max_history_messages = 40
+max_output_tokens = 0
+
+[timeouts]
+model_timeout_ms = 60000
+model_timeout_stream_ms = 300000
+fetch_timeout_ms = 60000
+
+[fetch]
+max_bytes = 200000
+proxy_url = ""
+
+[proxy]
+url = ""
+
+[auth]
+codex_home = "~/.codex"
+
+[logging]
+agent_events = true
+agent_stream = true
+
+[system]
+prompt = "You are running in user's personal computer or VPS, using telegram bot to interact with user. Be concise and practical."
+
+[tls]
+extra_ca_certs = ""
+reject_unauthorized = ""
+```
+
+### 配置说明
+
+- `telegram.allowed_user_ids`: 允许使用机器人的用户 ID 列表（空列表表示允许所有用户）
+- `paths.workspace_dir`: 默认工作区目录
+- `workspace_mappings`: 为特定聊天 ID 设置独立工作区（键为字符串格式的聊天 ID）
+- `limits.max_sessions`: 每个聊天最多保留的会话数
+- `limits.max_concurrent`: 最大并发请求数
+- `limits.max_history_messages`: 每个会话最多保留的历史消息数
+- `timeouts`: 各种操作的超时时间（毫秒）
+- `fetch.max_bytes`: fetch 工具下载文件的最大字节数
+- `tls.extra_ca_certs`: 额外的 CA 证书文件路径
+- `tls.reject_unauthorized`: 是否拒绝未授权的 TLS 证书（空字符串表示使用系统默认）
+
+## Codex 认证
+
+优先使用本机 Codex OAuth 凭据（`codex login` 写入的配置）。
+也可以在 Telegram 内执行 `/login openai-codex`，将凭据保存到 `~/.tg-agent/auth.json`。
+如果运行时提示缺少权限或无法找到凭据，请重新执行：
+
+```bash
+codex login
+```
+
+## MCP 配置
+
+在同一个 `~/.tg-agent/config.toml` 中添加 MCP 服务器：
+
+```toml
+[mcp_servers.context7]
+type = "stdio"
+command = "npx"
+args = ["-y", "@upstash/context7-mcp@latest"]
+
+[mcp_servers.Notion]
+url = "https://mcp.notion.com/mcp"
+```
+
+支持两种类型的 MCP 服务器：
+- `stdio`: 通过标准输入输出通信（使用 `command` 和 `args`）
+- HTTP: 通过 HTTP 请求通信（使用 `url`）
+
+## 常见问题
+
+- `Bad Request: can't parse entities`: 说明文本不符合 MarkdownV2 规则，当前实现会自动降级到 Markdown 或纯文本。
+- `No Codex OAuth credentials found`: 执行 `codex login` 或使用 `/login openai-codex`。
+- `insufficient permissions`: 检查组织/项目权限或 OAuth scope。
+- 网络错误：检查代理配置与 TLS 证书设置。
+- 文件上传失败：检查 `~/.tg-agent/uploads` 目录权限。
+
+## 安全说明
+
+- 不要提交 `~/.tg-agent/config.toml` 到仓库
+- 建议开启 `telegram.allowed_user_ids` 白名单，限制可访问的用户
+- 敏感信息（如 API keys）存储在配置文件中，请妥善保管

package/README.md

@@ -1,84 +1,95 @@
 # tg-agent
 
-一个在本地运行的 Telegram DM 机器人，用 Codex 账号驱动的 agent 来处理对话、工具调用与会话管理。支持多会话、会话持久化、/stop 中断、工具状态回写，适合在 macOS 上长期跑。
+A locally running Telegram bot that supports multiple LLM providers (Codex, Claude Code, Antigravity, etc.) with both account login (OAuth) and API key authentication. Handles conversations, tool calls, and session management. Supports multiple sessions, session persistence, `/stop` cancellation, and tool status updates. Suitable for long-term running on macOS.
 
-## 功能
+## Features
 
-- Telegram DM 交互（仅私聊）
-- 多会话管理：/new /list /use /close /reset
-- 会话持久化：默认保存到 `~/.tg-agent/tg-sessions`
-- 运行中可取消：/stop
-- 自动 Markdown 渲染：优先 MarkdownV2，失败回退 Markdown，再回退纯文本
-- 多 Provider / 多 Model 选择（支持 Codex / antigravity / Gemini CLI 等）
-- OAuth 登录与注销（/login, /logout）
-- 工具调用：内置 `fetch`，可选 MCP（HTTP/stdio）
-- 图片/文件上传与发送（Telegram 附件、`send_photo`/`send_file` 工具）
-- 代理支持：模型与工具请求可分别配置
+- Telegram private chat and group interactions (supports forum topics)
+- Multi-session management: /new /list /use /close /reset
+- Session persistence: saved to `~/.tg-agent/tg-sessions` by default
+- Cancellable during execution: /stop
+- Automatic Markdown rendering: prefers MarkdownV2, falls back to Markdown, then plain text
+- Multiple Provider / Model selection (supports Codex / antigravity / Gemini CLI, etc.)
+- OAuth login and logout (/login, /logout)
+- Tool calls: built-in `fetch`, optional MCP (HTTP/stdio)
+- Multimedia file support: images, documents, audio, video, voice, video notes
+- Proxy support: model and tool requests can be configured separately
+- Workspace management: set independent working directories for different chats
 
-## 快速开始
+## Quick Start
 
-1) 安装依赖
+1) Install globally
 
 ```bash
-npm install
+npm install -g tg-agent
 ```
 
-2) 配置文件（可选）
+2) Run
 
-你可以手动创建 `~/.tg-agent/config.toml`，最小示例如下：
+```bash
+tg-agent
+```
+
+On first run, you'll be prompted to enter `telegram.bot_token` which will be written to `~/.tg-agent/config.toml`.
+
+3) Configuration (optional)
+
+You can manually create or edit `~/.tg-agent/config.toml` with a minimal example:
 
 ```toml
 [telegram]
 bot_token = "YOUR_BOT_TOKEN"
 ```
 
-3) 运行
+## Usage
 
-```bash
-npm run dev
-```
+Send the following commands in Telegram:
 
-首次运行会提示输入 `telegram.bot_token` 并写入配置文件。
+### Session Management
 
-或构建后运行：
+- `/new [title]` - Create a new session
+- `/list` - List all sessions
+- `/use <id>` - Switch to a specific session
+- `/close [id]` - Close a session (defaults to current session)
+- `/reset` - Clear current session history
+- `/stop` - Cancel the currently processing request
 
-```bash
-npm run build
-npm start
-```
+### Models and Providers
+
+- `/providers` - List all available providers
+- `/models [provider]` - List models for a provider (shows current session's provider if not specified)
+- `/provider <name>` - Set the provider for current session
+- `/model <provider>/<model>` - Set the model for current session
 
-## 使用说明
+### Workspace and Tools
 
-在 Telegram 私聊中发送：
+- `/workspace [path]` - View or set the workspace directory for current session
+- `/mcp` - View MCP servers and connection status
+- `/mcp refresh` - Refresh MCP catalog
+- `/status` - View current session's model and workspace settings
 
-- `/new [title]` 创建会话
-- `/list` 列出会话
-- `/use <id>` 切换会话
-- `/close [id]` 关闭会话
-- `/reset` 清空当前会话历史
-- `/stop` 终止当前正在处理的请求
-- `/providers` 列出可用 Provider
-- `/models [provider]` 列出模型
-- `/provider <name>` 设置当前会话 Provider
-- `/model <provider>/<model>` 设置当前会话模型
-- `/mcp` 查看 MCP 服务器与连接状态
-- `/status` 查看当前会话模型设置
-- `/login <provider>` OAuth 登录
-- `/logout <provider>` 退出登录
+### Authentication
 
-默认仅支持私聊（DM）。
+- `/login <provider>` - OAuth login to a provider
+- `/logout <provider>` - Logout from a provider
 
-### 图片与文件
+### Help
 
-- 直接发送图片或文件给机器人，会保存到 `~/.tg-agent/uploads`，并自动附加到提示词中。
-- 图片会作为多模态输入传给模型（若模型支持图像）。
-- Agent 可使用 `send_photo` / `send_file` 工具把本地文件发回 Telegram（路径需在工作目录或 uploads 下）。
+- `/start` or `/help` - Show command help
 
-## 配置文件
+**Note**: By default, only private chats (DM) are supported. To use in groups, configure `telegram.allowed_user_ids` whitelist.
 
-所有配置统一放在 `~/.tg-agent/config.toml`。首次启动会提示输入 `telegram.bot_token`，其余字段使用默认值。
+### Images and Files
 
-常用字段示例：
+- Send images, documents, audio, video, voice, or video notes directly to the bot. Files are saved to `~/.tg-agent/uploads` and automatically attached to the prompt
+- Images are passed as multimodal input to the model (if the model supports images)
+- Agent can use `send_photo` / `send_file` tools to send local files back to Telegram (paths must be in workspace directory or uploads folder)
+
+## Configuration
+
+All configuration is stored in `~/.tg-agent/config.toml`. On first startup, you'll be prompted to enter `telegram.bot_token`, other fields use default values.
+
+### Complete Configuration Example
 
 ```toml
 [telegram]
@@ -95,26 +106,69 @@ openai_api_key = ""
 workspace_dir = ""
 session_dir = "~/.tg-agent/tg-sessions"
 
-[proxy]
-url = ""
+[workspace_mappings]
+# Set independent workspace for specific chat IDs
+# "-123456789" = "~/projects/project-a"
+
+[limits]
+max_sessions = 5
+max_concurrent = 5
+max_history_messages = 40
+max_output_tokens = 0
+
+[timeouts]
+model_timeout_ms = 60000
+model_timeout_stream_ms = 300000
+fetch_timeout_ms = 60000
 
 [fetch]
+max_bytes = 200000
 proxy_url = ""
+
+[proxy]
+url = ""
+
+[auth]
+codex_home = "~/.codex"
+
+[logging]
+agent_events = true
+agent_stream = true
+
+[system]
+prompt = "You are running in user's personal computer or VPS, using telegram bot to interact with user. Be concise and practical."
+
+[tls]
+extra_ca_certs = ""
+reject_unauthorized = ""
 ```
 
-## Codex 认证
+### Configuration Options
 
-优先使用本机 Codex OAuth 凭据（`codex login` 写入的配置）。
-也可以在 Telegram 内执行 `/login openai-codex`，将凭据保存到 `~/.tg-agent/auth.json`。
-如果运行时提示缺少权限或无法找到凭据，请重新执行：
+- `telegram.allowed_user_ids`: List of user IDs allowed to use the bot (empty list means all users are allowed)
+- `paths.workspace_dir`: Default workspace directory
+- `workspace_mappings`: Set independent workspace for specific chat IDs (keys are chat IDs as strings)
+- `limits.max_sessions`: Maximum number of sessions to keep per chat
+- `limits.max_concurrent`: Maximum number of concurrent requests
+- `limits.max_history_messages`: Maximum number of history messages per session
+- `timeouts`: Timeout settings for various operations (in milliseconds)
+- `fetch.max_bytes`: Maximum bytes for fetch tool file downloads
+- `tls.extra_ca_certs`: Path to additional CA certificate file
+- `tls.reject_unauthorized`: Whether to reject unauthorized TLS certificates (empty string means use system default)
+
+## Codex Authentication
+
+Prefers local Codex OAuth credentials (written by `codex login`).
+You can also execute `/login openai-codex` in Telegram to save credentials to `~/.tg-agent/auth.json`.
+If you see missing permissions or cannot find credentials at runtime, re-run:
 
 ```bash
 codex login
 ```
 
-## MCP 配置
+## MCP Configuration
 
-在同一个 `~/.tg-agent/config.toml` 中添加 MCP 服务器：
+Add MCP servers in the same `~/.tg-agent/config.toml`:
 
 ```toml
 [mcp_servers.context7]
@@ -126,40 +180,20 @@ args = ["-y", "@upstash/context7-mcp@latest"]
 url = "https://mcp.notion.com/mcp"
 ```
 
-## 打包发布
-
-构建并生成可执行入口：
-
-```bash
-npm run build
-```
-
-本地验证打包内容：
-
-```bash
-npm pack
-```
-
-发布到 npm（可选）：
-
-```bash
-npm publish
-```
-
-安装后可直接使用：
-
-```bash
-tg-agent
-```
+Two types of MCP servers are supported:
+- `stdio`: Communication via standard input/output (using `command` and `args`)
+- HTTP: Communication via HTTP requests (using `url`)
 
-## 常见问题
+## Troubleshooting
 
-- `Bad Request: can't parse entities`: 说明文本不符合 MarkdownV2 规则，当前实现会自动降级。
-- `No Codex OAuth credentials found`: 执行 `codex login`。
-- `insufficient permissions`: 检查组织/项目权限或 OAuth scope。
-- 网络错误：检查代理配置与 TLS 证书设置。
+- `Bad Request: can't parse entities`: Text doesn't conform to MarkdownV2 rules. The implementation automatically falls back to Markdown or plain text.
+- `No Codex OAuth credentials found`: Run `codex login` or use `/login openai-codex`.
+- `insufficient permissions`: Check organization/project permissions or OAuth scope.
+- Network errors: Check proxy configuration and TLS certificate settings.
+- File upload failures: Check permissions for `~/.tg-agent/uploads` directory.
 
-## 安全说明
+## Security
 
-- 不要提交 `~/.tg-agent/config.toml` 到仓库。
-- 建议开启 `telegram.allowed_user_ids` 白名单。
+- Do not commit `~/.tg-agent/config.toml` to the repository
+- It's recommended to enable `telegram.allowed_user_ids` whitelist to restrict access
+- Sensitive information (such as API keys) is stored in the config file, keep it secure

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tg-agent",
-  "version": "1.2.2",
-  "description": "Telegram Codex agent",
+  "version": "1.2.4",
+  "description": "Telegram Agent Bot",
   "type": "module",
   "bin": {
     "tg-agent": "dist/cli.js"