From 6a0d409dd69fc25e034c5978507d1e508d850f90 Mon Sep 17 00:00:00 2001 From: "Yuyao Huang (Sam)" Date: Sat, 28 Mar 2026 12:54:15 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E7=A7=98=E5=A1=94AI?= =?UTF-8?q?=E6=90=9C=E7=B4=A2MCP=E6=9C=8D=E5=8A=A1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E5=92=8C=E6=9B=B4=E6=96=B0README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加秘塔AI搜索MCP服务的详细文档metaso.md，包含API说明和配置指南 更新README文件中的命令说明和功能描述 新增ROADMAP.md文件记录未来开发计划 --- README.md | 51 ++++++++++--- ROADMAP.md | 189 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/metaso.md | 134 +++++++++++++++++++++++++++++++++++ 3 files changed, 364 insertions(+), 10 deletions(-) create mode 100644 ROADMAP.md create mode 100644 docs/metaso.md diff --git a/README.md b/README.md index 5674006..6001a36 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,8 @@ Feishu bot that lets users control Claude Code CLI from their phone. | `main.py` | FastAPI entry point, starts WebSocket client + session manager | | `bot/handler.py` | Receives Feishu events via long-connection WebSocket | | `bot/feishu.py` | Sends text/file/card replies back to Feishu | -| `bot/commands.py` | Slash command handler (`/new`, `/list`, `/close`, `/switch`, `/help`) | -| `orchestrator/agent.py` | LangChain agent with per-user history + passthrough mode | +| `bot/commands.py` | Slash command handler (`/new`, `/status`, `/switch`, `/direct`, `/smart`, etc.) | +| `orchestrator/agent.py` | LangChain agent with per-user history + direct/smart mode toggle | | `orchestrator/tools.py` | Tools: `create_conversation`, `send_to_conversation`, `list_conversations`, `close_conversation` | | `agent/manager.py` | Session registry with persistence and idle timeout reaper | | `agent/pty_process.py` | Runs `claude -p` headlessly, manages session continuity via `--resume` | @@ -148,18 +148,49 @@ Active sessions: `GET /sessions` | `/new [msg]` | Create a new Claude Code session in `` | | `/new [msg] --timeout N` | Create with custom CC timeout (seconds) | | `/new [msg] --idle N` | Create with custom idle timeout (seconds) | -| `/list` | List your active sessions | -| `/switch ` | Switch active session to number `` from `/list` | +| `/status` | Show your sessions and current mode | +| `/switch ` | Switch active session to number `` from `/status` | | `/close [n]` | Close active session (or session ``) | +| `/direct` | Direct mode: messages go straight to Claude Code (no LLM overhead) | +| `/smart` | Smart mode: messages go through LLM for intelligent routing (default) | | `/help` | Show command reference | -Any message without a `/` prefix is forwarded directly to the active Claude Code session. +### Message Routing Modes + +**Smart mode (default):** Messages are analyzed by the LLM, which decides whether to create a new session, send to an existing one, or ask for clarification. Useful when you want the bot to understand natural language requests. + +**Direct mode:** Messages go straight to the active Claude Code session, bypassing the LLM. Faster and more predictable, but requires an active session. Use `/direct` to enable. + +### Claude Code Commands + +Claude Code slash commands (like `/help`, `/clear`, `/compact`, `/cost`) are passed through to Claude Code when you have an active session. Bot commands (`/new`, `/status`, `/switch`, etc.) are handled by the bot first. --- -## Security +## Features -- **Allowlist** (`ALLOWED_OPEN_IDS`): only listed `open_id`s can use the bot. Empty = open to all. -- **Path sandbox**: all session directories must be under `WORKING_DIR`; path traversal is blocked. -- **Session ownership**: sessions are tied to the creating user; other users cannot send to them. -- **Audit log**: all prompts and responses are written to `agent/audit.log`. +### Core Reliability + +- **Message splitting** - Long responses automatically split into multiple messages instead of getting cut off +- **Concurrent handling** - Multiple users can message the bot simultaneously without conflicts +- **Session persistence** - Active sessions survive server restarts (saved to disk) +- **Direct mode** - Messages go straight to Claude Code, skipping the LLM for faster responses + +### Better Interaction + +- **Slash commands** - Direct control via `/new`, `/status`, `/switch`, `/close`, `/direct`, `/smart` +- **Multi-session switching** - Multiple projects open simultaneously, switch between them +- **Interactive cards** - Session status displayed in Feishu message cards + +### Operational Quality + +- **Health checks** - `/health` endpoint shows WebSocket status and can test Claude Code connectivity +- **Auto-reconnection** - WebSocket automatically reconnects if the connection drops +- **Configurable timeouts** - Each session can have custom idle and execution timeout settings +- **Audit logging** - All conversations logged to files for debugging and accountability + +### Security + +- **User allowlist** - Configure which Feishu users are allowed to use the bot +- **Session isolation** - Each user can only see and access their own sessions +- **Path sandboxing** - Sessions can only run inside the allowed working directory, blocking path traversal attacks diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..d592c9b --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,189 @@ +# PhoneWork — Roadmap + +## Milestone 2: Mailboy as a Versatile Assistant + +**Goal:** Elevate the mailboy (GLM-4.7 orchestrator) from a mere Claude Code relay into a +fully capable phone assistant. Users should be able to control their machine, manage files, +search the web, get direct answers, and track long-running tasks — all without necessarily +opening a Claude Code session. + +### M2.1 — Direct Q&A (no CC session required) + +The mailboy already has an LLM; it just needs permission to answer. +When no active session exists and the user asks a general question, the mailboy should +reply with its own knowledge instead of asking "which project?". + +**Changes:** +- Update the system prompt: give the mailboy explicit permission to answer questions directly +- Add a heuristic in `_run_locked`: if there's no active session and the message looks like a + question (ends with `?`, contains `what/how/why/explain`), skip tool loop and reply directly +- Zero new code; pure prompt + logic tweak in `orchestrator/agent.py` + +--- + +### M2.2 — Shell Tool + +Run arbitrary shell commands on the host machine and return stdout/stderr. +Covers: check git status, tail logs, kill a process, `ps aux | grep`, `pip list`, etc. + +**New tool:** `orchestrator/tools.py` → `ShellTool` +``` +name: "run_shell" +args: command (str), cwd (str, optional, defaults to WORKING_DIR), timeout (int, default 30) +returns: {stdout, stderr, exit_code} +``` + +**Safety guards:** +- Blocklist of destructive patterns (`rm -rf /`, `format`, `mkfs`, `shutdown`, `reboot`, + `dd if=`, `:(){:|:&};:`) — refuse with a clear error +- `cwd` must be under `WORKING_DIR` (reuse `_resolve_dir`) or be an explicit absolute path + approved by the user (raise a confirmation request) +- Timeout hard cap: 120 s; for longer tasks see M2.4 + +**New slash command:** `/shell ` (bypasses LLM; runs directly) + +--- + +### M2.3 — File Operations Tool + +Read files, list directories, search content, and send files back to the user in Feishu. +Covers: "show me the error log", "what files are in my project?", "search for TODO comments" + +**New tool:** `orchestrator/tools.py` → `FileOpsTool` (single tool, `action` dispatch) +``` +name: "file_ops" +args: action ("read" | "list" | "search" | "send"), path (str), query (str, for search), + max_bytes (int, default 8000) +``` + +- `read`: read file, truncate to `max_bytes`, return content +- `list`: recursive directory tree (depth-limited to 3), file sizes +- `search`: grep-like ripgrep/Python search for `query` in `path` +- `send`: upload and send file via `bot/feishu.py::send_file()` (already implemented) + — tool receives `chat_id` via context var (add alongside `current_user_id`) + +**Safety:** all paths must be under `WORKING_DIR` + +--- + +### M2.4 — Long-Running Task Manager + +This is the key UX upgrade. `claude -p` and shell commands that take minutes need +fire-and-forget with completion notification. + +**Design:** +- Add `BackgroundTask` dataclass: `{task_id, description, started_at, status, conv_id_or_none}` +- `TaskRunner` singleton in `agent/task_runner.py`: + - `submit(coro, description, notify_chat_id) -> task_id` + - wraps coroutine in `asyncio.create_task`; on completion sends a Feishu notification + via `send_text(notify_chat_id, ...)` + - stores tasks in-memory dict `{task_id: BackgroundTask}` +- When `manager.send()` is called for a CC session: + - if `cc_timeout > 60`: automatically run in background, return immediately with + `"⏳ Task # started. I'll notify you when it's done."` + - otherwise run inline as today + +**New tool:** `run_background` — explicitly submits any shell command or CC prompt as a +background task and returns `task_id` immediately. + +**New slash command:** `/tasks` — list running/completed background tasks with status. + +**New tool:** `task_status` — check status of a specific `task_id`, optionally get output so far. + +**Notification format:** +``` +✅ Task #abc123 done (42s) +/new todo_app: fix the login bug + +[CC output truncated to 800 chars]... +``` + +--- + +### M2.5 — Web Tool + +Let the mailboy fetch URLs and search the web for quick answers. +Covers: "最新的 LangChain 有什么变化?", "fetch this GitHub issue", "帮我搜索这篇论文" + +**Backend:** 秘塔AI Search MCP (`https://metaso.cn/api/mcp`) — mainland China accessible, +official API, Bearer token auth. Requires `METASO_API_KEY` in `keyring.yaml`. +Get key at: https://metaso.cn/search-api/api-keys + +**New tool:** `WebTool` (three actions dispatched via one tool) +``` +name: "web" +args: action ("search" | "fetch" | "ask"), query (str), url (str), scope (str), max_chars (int) +``` + +- `search`: calls `metaso_web_search` — returns top results (title + snippet + URL) + - `scope` options: `webpage` (default), `paper`, `document`, `video`, `podcast` +- `fetch`: calls `metaso_web_reader` with `format=markdown` — extracts clean content from URL +- `ask`: calls `metaso_chat` — RAG answer combining search + generation (for quick factual Q&A) + +**Implementation:** HTTP POST to `https://metaso.cn/api/mcp` with JSON-RPC body, +`Authorization: Bearer ` header. Use `httpx.AsyncClient` (already installed). + +**New config key:** `METASO_API_KEY` in `keyring.yaml` and `config.py` (optional — WebTool +disabled gracefully if not set) + +--- + +### M2.6 — Scheduling & Reminders + +Set a one-shot reminder or run a recurring check. +Covers: "remind me in 30 minutes", "check if the tests pass every 5 minutes" + +**Design:** `agent/scheduler.py` — thin wrapper around `asyncio` with: +- `schedule_once(delay_seconds, coro, description)` — fire once +- `schedule_recurring(interval_seconds, coro_factory, description, max_runs)` — repeat N times +- All scheduled jobs send a Feishu notification on completion (same as M2.4) +- Jobs stored in-memory; cleared on server restart (acceptable for now) + +**New tool:** `scheduler` +``` +args: action ("remind" | "repeat"), delay_seconds (int), interval_seconds (int), + message (str), conv_id (str, optional — if set, forward to that CC session) +``` + +**New slash command:** `/remind m|h|s ` — set a reminder without LLM + +--- + +## Implementation Order + +1. **M2.1** — Direct Q&A (prompt + 10-line logic change; highest ROI, zero risk) +2. **M2.4** — Background task runner (unblocks long CC jobs; foundational for M2.5/M2.6) +3. **M2.2** — Shell tool (most-used phone use case) +4. **M2.3** — File ops tool (`send_file` already done; rest is straightforward) +5. **M2.5** — Web tool (秘塔AI MCP; needs `METASO_API_KEY`) +6. **M2.6** — Scheduling (builds on M2.4 notification infra) + +--- + +## Files to Create / Modify + +| File | Change | +|------|--------| +| `orchestrator/agent.py` | M2.1 prompt update + question heuristic | +| `orchestrator/tools.py` | Add `ShellTool`, `FileOpsTool`, `WebTool`, `TaskStatusTool`, `SchedulerTool` | +| `agent/task_runner.py` | New — `TaskRunner` singleton, `BackgroundTask` dataclass | +| `agent/scheduler.py` | New — `schedule_once`, `schedule_recurring` | +| `bot/commands.py` | Add `/shell`, `/tasks`, `/remind` commands | +| `bot/feishu.py` | Add `chat_id` context var for file send from tool | +| `bot/handler.py` | Pass `chat_id` into context var alongside `user_id` | +| `requirements.txt` | Add `httpx` (if not already present as transitive dep) | + +--- + +## Verification Checklist + +- [ ] M2.1: Ask "what is a Python generator?" — mailboy replies directly, no tool call +- [ ] M2.2: Send "check git status in todo_app" — `ShellTool` runs, output returned +- [ ] M2.2: Send "rm -rf /" — blocked by safety guard +- [ ] M2.3: Send "show me the last 50 lines of audit/abc123.jsonl" — file content returned +- [ ] M2.3: Send "send me the sessions.json file" — file arrives in Feishu chat +- [ ] M2.4: Start a long CC task (e.g. `--timeout 120`) — bot replies immediately, notifies on finish +- [ ] M2.4: `/tasks` — lists running task with elapsed time +- [ ] M2.5: "Python 3.13 有哪些新特性？" — `web ask` returns RAG answer from metaso +- [ ] M2.5: "帮我读取这个URL: https://example.com" — page content extracted as markdown +- [ ] M2.6: `/remind 10m deploy check` — 10 min later, message arrives in Feishu diff --git a/docs/metaso.md b/docs/metaso.md new file mode 100644 index 0000000..81f8258 --- /dev/null +++ b/docs/metaso.md @@ -0,0 +1,134 @@ +秘塔AI搜索的MCP服务 +简介 +秘塔AI搜索的MCP服务是一个基于Model Context Protocol (MCP) 的智能搜索和问答服务，为AI助手提供强大的网络搜索、内容读取和智能问答能力。通过集成本服务，AI助手可以实时获取网络信息，读取网页内容，并基于RAG技术提供准确的智能问答。 + +服务地址 +ModelScope地址: https://www.modelscope.cn/mcp/servers/metasota/metaso-search + +API端点: https://metaso.cn/api/mcp + +功能特性 +🔍 多维度搜索 +支持网页、文档、论文、图片、视频、播客等多种内容类型搜索 +灵活的搜索范围配置 +可自定义返回结果数量 +📖 网页内容读取 +支持任意URL的网页内容提取 +提供JSON和Markdown两种输出格式 +智能内容解析和结构化处理 +💬 智能问答服务 +基于RAG（检索增强生成）技术 +多模型支持，默认使用快速模型 +结合搜索结果提供准确回答 +工具列表 +1. metaso_web_search - 网络搜索工具 +功能描述: 根据关键词搜索网页、文档、论文、图片、视频、播客等内容 + +参数说明: + +q (必填, string): 搜索查询关键词 +scope (可选, string): 搜索范围，可选值：webpage, document, paper, image, video, podcast +includeSummary (可选, boolean): 通过网页摘要信息提升搜索结果的召回率 +includeRawContent (可选, boolean): 抓取所有来源网页原文 +size (可选, integer): 返回结果数量，默认为10 +使用示例: + +{ + "q": "人工智能最新发展", + "scope": "paper", + "includeSummary": true, + "size": 5 +} +2. metaso_web_reader - 网页内容读取工具 +功能描述: 读取指定URL的网页内容 + +参数说明: + +url (必填, string): 要读取的URL地址 +format (必填, string): 输出格式，可选值：json, markdown +使用示例: + +{ + "url": "https://example.com/article", + "format": "markdown" +} +3. metaso_chat - 智能问答工具 +功能描述: 基于RAG的智能问答服务 + +参数说明: + +message (必填, string): 用户问题 +model (可选, string): 使用的模型，默认为"fast" +使用示例: + +{ + "message": "请解释一下量子计算的基本原理", + "model": "fast" +} +配置方法 +1. 基础配置 +在您的MCP客户端配置文件中添加以下配置： + +请将YOUR_API_KEY替换为你自己的ApiKey + +{ + "mcpServers": { + "metaso": { + "url": "https://metaso.cn/api/mcp", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +VSCode配置 + +{ + "servers": { + "metaso": { + "url": "https://metaso.cn/api/mcp", + "type": "http", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + }, + "inputs": [] +} +2. API密钥获取 +访问秘塔AI搜索官网 +注册并登录账户 +访问API控制台(https://metaso.cn/search-api/api-keys)中获取API密钥 +将密钥替换配置中的 YOUR_API_KEY +使用场景 +📚 学术研究 +搜索最新论文和研究资料 +获取特定领域的学术文档 +快速获取研究背景信息 +📰 信息获取 +实时新闻和资讯搜索 +网页内容快速提取 +多媒体内容发现 +🤖 AI增强 +为AI助手提供实时信息检索能力 +增强对话系统的知识库 +支持基于最新信息的智能问答 +💼 商业应用 +市场调研和竞品分析 +行业趋势监控 +客户服务知识库构建 +技术优势 +高性能: 基于秘塔AI搜索的强大搜索引擎 +多格式支持: 支持多种内容类型和输出格式 +RAG技术: 结合检索和生成，提供准确回答 +易于集成: 标准MCP协议，兼容性强 +灵活配置: 丰富的参数选项，满足不同需求 +注意事项 +API配额: 请注意API调用配额限制，合理使用服务。2. 内容合规: 搜索和获取的内容请遵守相关法律法规。 +缓存策略: 建议实施适当的缓存策略以提高效率。 +错误处理: 请在应用中实现合适的错误处理机制。 +支持与反馈 +如果您在使用过程中遇到问题或有改进建议，欢迎通过以下方式联系我们： + +官方技术支持邮箱: support-1@metasota.ai +官网客服: 19980541467（微信同号） \ No newline at end of file