Polli 机器人架构深度解析:Pollinations 开源平台的多入口工程助手设计

原创2026-10-12 13:52:151,992 阅读
文章标签:AI 应用媒体生成后端前端

Polli 机器人架构深度解析:Pollinations 开源平台的多入口工程助手设计

Polli 是 Pollinations.ai 开源仓库中面向 Discord 与 GitHub 的工程助理机器人,本文以其 架构文档 为主线,结合 config.json 与核心源码,完整剖析其多入口、分层、权限感知的系统设计。读完本文,你将掌握 Polli 从 Discord @提及、GitHub Webhook、HTTP API 三条入口进入后,如何经过配置层、Discord 层、AI 层、GitHub 层与各类支撑服务协作完成一次工具调用型问答的完整链路,以及其安全模型、会话管理与关键设计决策的落地细节。

架构总览:单进程内的多入口服务

Polli 的全部运行时组件运行在一个 Python 进程内:Discord Bot、内嵌的 OpenAI 兼容 HTTP API 服务器、以及可选的 GitHub Webhook 服务器共享同一事件循环与连接池。会话保存在进程内存中,并随时从 Discord 线程历史刷新。工具的调用方(GitHub、Discord、Pollinations、Web、本地仓库、Vectorize、渲染服务)则按配置动态挂载。

以下是架构文档给出的完整组件关系图(Mermaid 深色主题),它定义了本文后续所有章节的骨架:

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#bb86fc', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#bb86fc', 'lineColor': '#03dac6', 'secondaryColor': '#3700b3', 'tertiaryColor': '#1e1e1e', 'background': '#121212', 'mainBkg': '#1e1e1e', 'nodeBorder': '#bb86fc', 'clusterBkg': '#2d2d2d', 'clusterBorder': '#bb86fc', 'titleColor': '#ffffff', 'edgeLabelBackground': '#1e1e1e'}}}%%

flowchart TB
    subgraph ENTRY["**ENTRY POINTS**"]
        direction TB
        MAIN["main.py<br/>Entry Point"]
        DISCORD_EVENT["Discord Events<br/>@mention / reply / context menu"]
        WEBHOOK_IN["GitHub Webhook<br/>@mention in issues/PRs"]
        HTTP_API["HTTP API<br/>polli_api.py"]
    end

    subgraph DISCORD_LAYER["**DISCORD LAYER** - src/bot.py"]
        direction TB
        POLLIBOT["PolliBot<br/>(commands.Bot)"]

        subgraph EVENTS["Event Handlers"]
            ON_READY["on_ready()"]
            ON_MESSAGE["on_message()"]
            ASSIST_CTX["@assist_context_menu"]
        end

        subgraph MSG_FLOW["Message Processing"]
            START_CONV["start_conversation()<br/>Create thread"]
            HANDLE_THREAD["handle_thread_message()<br/>Thread responses"]
            PROCESS_MSG["process_message()<br/>Main processing"]
            FETCH_HISTORY["fetch_thread_history()<br/>Discord memory"]
        end

        subgraph ADMIN["Admin System"]
            IS_ADMIN["is_admin()<br/>Role-based check"]
            ADMIN_ROLES["admin_role_ids<br/>from config"]
        end

        subgraph TASKS["Background Tasks"]
            CLEANUP_SESSIONS["cleanup_sessions<br/>1 min loop"]
            UPDATE_DOCS["update_doc_embeddings<br/>6 hour loop"]
        end
    end

    subgraph CONFIG_LAYER["**CONFIGURATION** - src/config.py + src/constants.py"]
        direction TB
        CONFIG["Config class<br/>config.json + .env"]

        subgraph CONFIG_VALS["Config Values"]
            DISCORD_TOKEN["discord_token"]
            GITHUB_APP["github_app_id<br/>github_private_key<br/>installation_id"]
            WEBHOOKS["webhook_port<br/>webhook_secret"]
            AI_CFG["pollinations_model<br/>pollinations_token"]
            FEATURES["local_embeddings_enabled<br/>doc_embeddings_enabled"]
        end

        subgraph CONSTANTS["Constants - Tool Definitions"]
            GITHUB_TOOLS["GITHUB_TOOLS<br/>github_issue, github_pr<br/>github_project, github_custom<br/>github_overview"]
            CODE_SEARCH["CODE_SEARCH_TOOL"]
            DOC_SEARCH["DOC_SEARCH_TOOL"]
            WEB_SEARCH["WEB_SEARCH_TOOL"]
            WEB_SCRAPE["WEB_SCRAPE_TOOL"]
            DISCORD_SEARCH_TOOL["DISCORD_SEARCH_TOOL"]
            WEB_TOOL["WEB_TOOL (nomnom)"]
        end

        subgraph SECURITY["Security Filters"]
            ADMIN_ACTIONS["ADMIN_ACTIONS<br/>per-tool admin sets"]
            FILTER_ADMIN["filter_admin_actions_from_tools()"]
            FILTER_INTENT["filter_tools_by_intent()<br/>Regex matching"]
            TOOL_KEYWORDS["TOOL_KEYWORDS<br/>Compiled patterns"]
        end

        SYSTEM_PROMPT["TOOL_SYSTEM_PROMPT<br/>AGENTS.md pattern<br/>Embedded knowledge"]
    end

    subgraph AI_LAYER["**AI LAYER** - src/services/pollinations.py"]
        direction TB
        POLL_CLIENT["PollinationsClient"]

        subgraph AI_METHODS["Core Methods"]
            PROCESS_TOOLS["process_with_tools()<br/>Main entry"]
            CALL_WITH_TOOLS["_call_with_tools()<br/>Tool loop (max 20)"]
            CALL_API["_call_api_with_tools()<br/>HTTP to API"]
            EXEC_PARALLEL["_execute_tools_parallel()<br/>Parallel execution"]
        end

        subgraph AI_FEATURES["Features"]
            RESPONSE_CACHE["ResponseCache<br/>60s TTL"]
            RETRY_LOGIC["Retry Logic<br/>3 attempts, 5s delay"]
            RANDOM_SEED["Random seed<br/>per request"]
        end

        WEB_SEARCH_HANDLER["web_search_handler()<br/>Web search models"]
    end

    subgraph GITHUB_LAYER["**GITHUB LAYER**"]
        direction TB

        subgraph AUTH["Authentication - github_auth.py"]
            GH_APP_AUTH["GitHubAppAuth<br/>JWT generation"]
            INSTALL_TOKEN["Installation token<br/>1 hour TTL"]
        end

        subgraph REST["REST API - github.py"]
            GH_MANAGER["GitHubManager<br/>REST operations"]
            ISSUE_OPS["create/update/close<br/>label/assign<br/>comment"]
            TOOL_HANDLERS["TOOL_HANDLERS<br/>github_issue handler"]
        end

        subgraph GRAPHQL["GraphQL - github_graphql.py"]
            GH_GRAPHQL["GitHubGraphQL<br/>Fast queries"]
            BATCH_ISSUES["get_issues_batch()<br/>One call, N issues"]
            SEARCH_FULL["search_issues_full()<br/>With metadata"]
            PROJECT_OPS["ProjectV2 ops<br/>add/remove/set_status"]
            REPO_OVERVIEW["get_repo_overview()<br/>Combined query"]
            SUB_ISSUES["sub-issue management"]
        end

        subgraph PR["PR Operations - github_pr.py"]
            GH_PR["GitHubPRManager"]
            PR_REVIEW["post_review()"]
            PR_MERGE["merge_pr()"]
            PR_INLINE["inline_comment()"]
            PR_FILES["get_pr_files()<br/>get_pr_diff()"]
        end
    end

    subgraph WEBHOOK_SERVER["**WEBHOOK SERVER** - webhook_server.py"]
        direction TB
        WH_SERVER["GitHubWebhookServer<br/>aiohttp web.Application"]

        subgraph WH_ROUTES["Routes"]
            WH_HEALTH["/health"]
            WH_WEBHOOK["/webhook POST"]
        end

        subgraph WH_HANDLERS["Event Handlers"]
            ISSUE_COMMENT["handle_issue_comment()"]
            ISSUE_EVENT["handle_issue_event()"]
            PR_EVENT["handle_pr_event()"]
            PR_REVIEW_COMMENT["handle_pr_review_comment()"]
        end

        VERIFY_SIG["verify_signature()<br/>HMAC SHA256"]
        PROCESS_MENTION["process_mention()<br/>AI + respond"]
    end

    subgraph SUBSCRIPTION_LAYER["**SUBSCRIPTIONS** - subscriptions.py"]
        direction TB
        SUB_MANAGER["SubscriptionManager<br/>aiosqlite"]

        subgraph SUB_DB["SQLite Database"]
            SUB_TABLE["subscriptions table<br/>user_id, issue_number<br/>channel_id, last_state"]
        end

        ISSUE_NOTIFIER["IssueNotifier<br/>Background poller"]
        POLL_LOOP["_poll_loop()<br/>2 min interval"]
        SEND_NOTIF["_send_notification()<br/>DM or channel fallback"]
    end

    subgraph EMBEDDINGS["**EMBEDDINGS**"]
        direction TB

        subgraph CODE_EMB["Code - embeddings.py"]
            EMB_MODEL["OpenAI text-embedding-3-small"]
            CHROMADB["ChromaDB<br/>PersistentClient"]
            SEARCH_CODE_FN["search_code()<br/>Semantic search"]
            CLONE_PULL["clone_or_pull_repo()"]
        end

        subgraph DOC_EMB["Docs - doc_embeddings.py"]
            DOC_CRAWL["_crawl_site()<br/>Multi-page crawler"]
            DOC_EMBED["embed_site()<br/>Hash-based dedup"]
            DOC_SEARCH_FN["search_docs()<br/>Semantic search"]
        end

        SCHEDULE_UPDATE["schedule_update()<br/>30s debounce"]
    end

    subgraph SCRAPER["**WEB SCRAPER** - web_scraper.py"]
        direction TB
        CRAWL4AI["Crawl4AI<br/>AsyncWebCrawler"]

        subgraph SCRAPE_OPS["Operations"]
            SCRAPE_URL["scrape_url()"]
            SCRAPE_MULTI["scrape_multiple()<br/>Concurrent"]
            LLM_EXTRACT["_llm_extract()<br/>Smart extraction"]
        end

        SCRAPE_CACHE["_scrape_cache<br/>5 min TTL"]
    end

    subgraph CONTEXT["**SESSION CONTEXT** - src/context/"]
        direction TB
        SESSION_MGR["SessionManager<br/>LRU cache"]
        CONV_SESSION["ConversationSession<br/>Dataclass"]

        subgraph SESSION_DATA["Session Data"]
            THREAD_ID["thread_id"]
            USER_INFO["user_id, user_name"]
            MESSAGES["messages list"]
            TOPIC["topic_summary"]
            IMAGES["image_urls"]
        end

        LRU_EVICT["LRU Eviction<br/>max 1000 sessions"]
        TIMEOUT_CLEAN["Timeout cleanup<br/>1 hour"]
    end

    %% ============== CONNECTIONS ==============

    %% Entry flow
    MAIN --> POLLIBOT
    DISCORD_EVENT --> ON_MESSAGE
    WEBHOOK_IN --> WH_SERVER
    HTTP_API --> POLL_CLIENT

    %% Discord flow
    POLLIBOT --> ON_READY
    POLLIBOT --> ON_MESSAGE
    POLLIBOT --> ASSIST_CTX
    ON_READY --> SYNC_CMD["Sync slash commands"]
    ON_MESSAGE --> IS_ADMIN
    ON_MESSAGE --> START_CONV
    ON_MESSAGE --> HANDLE_THREAD
    START_CONV --> PROCESS_MSG
    HANDLE_THREAD --> FETCH_HISTORY
    HANDLE_THREAD --> PROCESS_MSG
    PROCESS_MSG --> POLL_CLIENT

    %% Admin checks
    IS_ADMIN --> ADMIN_ROLES
    ADMIN_ROLES --> CONFIG

    %% AI Layer
    POLL_CLIENT --> PROCESS_TOOLS
    PROCESS_TOOLS --> CALL_WITH_TOOLS
    CALL_WITH_TOOLS --> CALL_API
    CALL_WITH_TOOLS --> EXEC_PARALLEL
    EXEC_PARALLEL --> TOOL_HANDLERS
    EXEC_PARALLEL --> WEB_SEARCH_HANDLER

    %% Tool filtering
    PROCESS_TOOLS --> FILTER_ADMIN
    PROCESS_TOOLS --> FILTER_INTENT
    FILTER_ADMIN --> ADMIN_ACTIONS
    FILTER_INTENT --> TOOL_KEYWORDS

    %% GitHub connections
    TOOL_HANDLERS --> GH_MANAGER
    TOOL_HANDLERS --> GH_GRAPHQL
    TOOL_HANDLERS --> GH_PR
    GH_MANAGER --> GH_APP_AUTH
    GH_GRAPHQL --> GH_APP_AUTH
    GH_PR --> GH_APP_AUTH

    %% Webhook flow
    WH_SERVER --> WH_WEBHOOK
    WH_WEBHOOK --> VERIFY_SIG
    WH_WEBHOOK --> ISSUE_COMMENT
    WH_WEBHOOK --> PR_EVENT
    ISSUE_COMMENT --> PROCESS_MENTION
    PROCESS_MENTION --> POLL_CLIENT
    PROCESS_MENTION --> GH_MANAGER

    %% Subscriptions
    POLL_LOOP --> GH_GRAPHQL
    POLL_LOOP --> SEND_NOTIF
    SEND_NOTIF --> POLLIBOT

    %% Embeddings
    SEARCH_CODE_FN --> EMB_MODEL
    SEARCH_CODE_FN --> CHROMADB
    SCHEDULE_UPDATE --> CLONE_PULL

    %% Web scraper
    SCRAPE_URL --> CRAWL4AI
    LLM_EXTRACT --> POLL_CLIENT

    %% Session management
    PROCESS_MSG --> SESSION_MGR
    CLEANUP_SESSIONS --> SESSION_MGR
    SESSION_MGR --> CONV_SESSION

    %% Background tasks
    POLLIBOT --> TASKS
    UPDATE_DOCS --> DOC_CRAWL

    %% Config connections
    CONFIG --> CONFIG_VALS
    CONFIG --> FEATURES

    classDef entry fill:#ff7043,stroke:#ff5722,color:#000
    classDef discord fill:#5865f2,stroke:#4752c4,color:#fff
    classDef ai fill:#bb86fc,stroke:#9965f4,color:#000
    classDef github fill:#238636,stroke:#1a7f37,color:#fff
    classDef storage fill:#f9a825,stroke:#f57f17,color:#000
    classDef config fill:#78909c,stroke:#546e7a,color:#fff

    class MAIN,DISCORD_EVENT,WEBHOOK_IN,HTTP_API entry
    class POLLIBOT,EVENTS,MSG_FLOW,ADMIN,TASKS discord
    class POLL_CLIENT,AI_METHODS,AI_FEATURES ai
    class AUTH,REST,GRAPHQL,PR,WH_SERVER github
    class SUB_MANAGER,CHROMADB,SCRAPE_CACHE,SESSION_MGR storage
    class CONFIG,CONSTANTS,SECURITY,SYSTEM_PROMPT config

仓库中还提供了一张对应的运行时架构示意图 assets/readme/architecture.svg,展示了 Discord、签名后的 GitHub Webhook 与本地 API 如何进入权限过滤与上下文组装,再流向 Pollinations 推理与权限相关的工具。

需要说明的是:架构文档以模块名(如 src/config.py、src/constants.py、src/services/pollinations.py、embeddings.py、github_pr.py)描述逻辑分层;当前仓库源码已经重组为 src/core/config.py、src/ai/tools.py、src/ai/client.py、src/search/、src/integrations/github/ 等目录,下文引用以实际源码路径为准,逻辑职责与架构文档一一对应。

入口点:四条进入路径

入口 触发方式 处理者
main.py 进程启动入口 初始化日志与 Discord 客户端,运行事件循环
Discord 事件 @Polli 提及、回复、Apps → Assist 右键菜单 src/bot.py 的事件处理器
GitHub Webhook 在 issue / PR / 评论中 @提及机器人账号 src/integrations/webhook_server.py
HTTP API OpenAI 兼容 REST 请求 src/api/server.py

main.py 是启动入口:它先尝试安装 uvloop(Linux 下可获得 2–4 倍的事件循环加速,安装失败则静默跳过),随后调用 setup_logging() 与 config.validate() 做启动前校验,最后 bot.run(...) 启动 Discord 客户端。源码中还对两类常见启动失败做了显式提示:未启用 Message Content Intent(抛出 PrivilegedIntentsRequired)时提示去 Discord 开发者后台开启;DISCORD_TOKEN 错误导致登录失败(LoginFailure)时直接提示检查环境变量。

HTTP API 入口的定位

内嵌 API 位于 src/api/server.py,默认绑定 127.0.0.1:55288。它不是通往 Polli 的通用后门:只接受调用方预先持有、由周边可信系统签发的短时效 ag_ 前缀 Bearer token(源码 _authorization() 中校验 token.startswith("ag_"),持久型 sk_、pk_ key 一律拒绝);同时以非管理员上下文运行,剥离变更与订阅类操作、排除自定义 GitHub 请求与视觉渲染、屏蔽 Discord 成员/角色查询,并将 Discord 检索结果限制为公开 HTTP 作用域。

curl http://127.0.0.1:55288/v1/chat/completions \
  -H "Authorization: Bearer $POLLI_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "polli",
    "messages": [{"role": "user", "content": "Summarize the open image API issues"}]
  }'

请求体中 metadata: {"model": "model-id"} 用于选择 Polli 的内部模型(在 Chat Completions 与 Responses 两条路径上都生效,优先级高于 model 字段);model: "polli" 是服务默认上游模型的别名,可触发配置的 fallback 模型;显式指定非空上游模型名则原样转发且不使用 fallback。/v1/models 只公布稳定的 polli 别名,因此显式上游模型不必出现在该列表中。API 同时支持 SSE 流式输出(/v1/chat/completions?stream=true 与 /v1/responses)以及客户端自定义工具调用。

配置层:config.json 与 .env 的分工

架构文档明确:非敏感配置在 config.json,敏感配置在 .env。这一约定在 src/core/config.py 中被强制为单一事实来源——代码库中其他模块一律通过 from src.core.config import config 读取配置,不得直接读取 config.json 或环境变量。模块启动时调用 load_dotenv() 合并 .env,并通过 config.validate() 快速失败:缺少 DISCORD_TOKEN、GitHub 认证(App 与 PAT 二选一)、POLLINATIONS_TOKEN 任一必需项即打印错误并 sys.exit(1)。

config.json 中的核心分区与关键项如下:

分区 关键配置项 默认值 / 取值说明
bot name、default_repo、session_timeout_seconds、thread_auto_archive_minutes、thread_history_limit 默认仓库 pollinations/pollinations;会话超时 300 秒;线程归档 60 分钟;历史拉取上限 50 条
discord admin_role_ids、collaborator_role_ids、api_base、max_message_length、max_images_per_reply、guild_id、pr_merge_channel_id、pr_merge_webhook_id 管理员/协作者角色 ID 列表;单条消息 2000 字符;每次回复最多 10 张图
github bot_username、admin_user_ids、whitelisted_repos、admin_only_mentions、api_base、graphql_url、多档超时、cache_ttl_seconds admin_only_mentions: true 表示 Webhook 仅响应配置的管理员 GitHub 账号
ai api_base、model、fallback_model、request_timeout_seconds、max_tokens、temperature、task_models 上游 https://gen.pollinations.ai;task_models.web_search 可指定独立搜索模型
code_search enabled、vectorize_index、embed_model、embed_dimensions、local_repo_enabled、local_repo_url、local_repo_branch、graph_enabled、default_top_k、max_top_k 默认 default_top_k: 5、max_top_k: 10;语义索引使用 Cloudflare Vectorize
api enabled、bind、port、cors_origins 默认 127.0.0.1:55288
webhook enabled、port 默认关闭(false),端口 8002

.env 侧的必需与可选密钥(模板见 .env.example):

DISCORD_TOKEN=...
POLLINATIONS_TOKEN=...

# 选择 GitHub App 认证…
GITHUB_APP_ID=...
GITHUB_INSTALLATION_ID=...
GITHUB_PRIVATE_KEY=./polly.pem

# …或个人访问令牌。
POLLI_PAT=...

GITHUB_PROJECT_PAT(Projects V2)、GITHUB_WEBHOOK_SECRET(Webhook 签名密钥)、CLOUDFLARE_ACCOUNT_ID 与 VECTORIZE_API_TOKEN(语义检索)均为可选,只启用对应功能。GitHub App 认证与 PAT 二选一:config.py 中 use_app_auth 属性判断逻辑是 app_id + installation_id + private_key 三者齐备即走 App 认证,否则用 POLLI_PAT。注意:Discord 侧使用的 POLLINATIONS_TOKEN 是运维配置的服务凭据,与 HTTP API 请求级 ag_ token 是完全不同的凭据契约。

Discord 层:PolliBot 的消息处理与后台任务

src/bot.py 中的 PolliBot 继承 discord.ext.commands.Bot,开启 message_content 与 members 两个特权 intent(setup_hook 中若未启用 Message Content Intent,启动会失败并给出明确报错)。它承载了四条核心职责:

事件处理。 on_ready() 负责同步斜杠命令与全局命令(先清空 guild 级命令避免重复);on_message() 按"快速路径"原则先做廉价判断——非线程消息仅响应 @提及,线程消息响应 @提及或对机器人消息的回复;@assist_context_menu 让用户在任意消息上右键 → Apps → Assist,等效于一次 @提及。

线程化会话。 新会话由 start_conversation() 创建 Discord 线程;handle_thread_message() 处理线程内消息;fetch_thread_history() 从 Discord 实时拉取线程历史作为"记忆"——它会先取线程起始消息作为第一条 user 消息,再把历史按时间正序注入,并跳过当前/排队消息的 ID 以避免竞态。

管理员检查。 is_admin() 与 is_collaborator() 按 config.discord.admin_role_ids / collaborator_role_ids 做角色比对(src/bot.py 中 is_admin 的实现会遍历成员角色 ID 与配置集合求交集)。非 Member 对象(如 DM 场景)一律视为非管理员。

后台任务。 cleanup_sessions 每 1 分钟清理过期会话(@tasks.loop(minutes=1));rotate_status 每 1 分钟轮换彩蛋状态文案;此外还有文档嵌入更新循环。值得注意的细节:on_message 中若检测到 PR 合并频道(pr_merge_channel_id + pr_merge_webhook_id 匹配),会异步触发本地仓库同步与符号图刷新,保证 code_search 立即反映 main 分支。

AI 层:PollinationsClient 的工具调用循环

AI 层是架构文档中标注为 src/services/pollinations.py 的部分,当前实现位于 src/ai/client.py。PollinationsClient 是唯一的上游入口,使用带连接池的 aiohttp 会话(TCPConnector 上限 100 连接、单主机 30、keepalive 90 秒贴合 Cloudflare 空闲超时),并在启动时预热到 gen.pollinations.ai 的 TLS 连接。

process_with_tools:主入口

process_with_tools() 按调用面组装消息:

  • Discord 模式:注入系统提示、可信的 Discord 位置元数据(源频道、父频道、当前频道、线程 ID)、线程历史(区分 system 消息与对话消息,用分隔线标注"TASK STATE"与"THREAD CONVERSATION HISTORY"),并按 discord_username 标识当前用户;图片以 image_url 块注入(静态图上限 10),视频/GIF 只作为文本上下文提示(避免不支持的媒体破坏请求),文本/代码文件则提示模型用 web_scrape(action="fetch_file") 读取;
  • API 模式:调用方原样提供 OpenAI 对话,Polli 只附加私有系统提示。

_call_with_tools:工具循环与防循环机制

_call_with_tools() 是核心循环。架构文档描述的"max 20 迭代"在当前源码中以 max_iterations=500 的高上限实现(注释说明 Polli 需要处理复杂多步任务),真正约束来自防循环引导:当模型连续调用同一组工具时,系统会注入递进式指导消息——连续 3 次提示"检查是否已有足够信息作答,否则换工具或换查询";连续 6 次展示已尝试过的查询列表并强制要求改变策略;连续 10 次则给出完整的"STOP AND RE-PLAN"三段式自检(换工具/坦承信息缺口/直接作答)。此外,本回合失败的调用签名会被记录(_call_signature 按名称+排序后的参数稳定哈希),完全相同的调用再次出现时直接返回"该调用已失败"而不重复派发。

每轮调用还会累计 usage token 统计,收集 content_blocks(如图片侧信道),并在无工具调用时通过 _call_api_with_tools_stream 以 SSE 流式输出最终答案(Discord 模式则缓冲私有规划文本,避免泄露)。

并行执行、缓存与重试

_execute_tools_parallel() 用 asyncio.gather 并行执行一轮内的全部工具调用,并区分可缓存操作(get、search、list、view 等只读动作)与不可缓存操作:可缓存结果进入 TTLCache(maxsize=256, ttl=60)(60 秒 TTL,与架构文档一致);_call_api_with_tools() 实现 MAX_RETRIES = 3、RETRY_DELAY = 5 秒的重试逻辑——402(余额耗尽)立即放弃,其余错误在未显式指定模型时切换到 config.ai.fallback_model 重试,API 模式的 401/403 则抛 UpstreamAuthError 直接透传。随机种子机制以 api_params 中的显式 seed 透传形式保留(流式与非流式均支持)。响应缓存与重试策略可分别在 src/ai/client.py 顶部与 _call_api_with_tools 中核对。

系统提示:AGENTS.md 模式

系统提示生成于 src/ai/prompts.py,采用架构文档强调的 AGENTS.md 模式:把稳定的仓库知识(context/repo_info.txt 的 REPO_INFO)内嵌进提示,工具只留给动态数据。提示还按权限追加模式声明(ADMIN MODE / COLLABORATOR MODE / USER MODE),并给出代码检索动作的选择判断(精确标识符用 grep 而非 search;用 symbols 消歧后再做 callers/callees;"改动会破坏什么"用 impact)。

GitHub 层:认证、REST、GraphQL 与 PR 四件套

GitHub 集成在 src/integrations/github/ 目录下,与架构文档的四个模块一一对应:

认证(auth.py)。 GitHubAppAuth 用 jwt 库生成 RS256 签名 JWT(iat 提前 30 秒、exp 60 秒),换取 installation access token,TTL 1 小时、提前 300 秒刷新(TOKEN_REFRESH_BUFFER)。Projects V2 操作优先使用 App token,未配置时回退 GITHUB_PROJECT_PAT。

REST(client.py)。 GitHubManager 负责变更类操作(创建/更新/关闭、标签、指派、评论),使用带连接池的会话与 X-GitHub-Api-Version: 2022-11-28 头,实现分页搜索(每页 100 条、最多 10 页)。

GraphQL(graphql.py)。 GitHubGraphQL 承载读取类高频操作并贯彻 GraphQL First 策略:get_issues_batch() 一次 GraphQL 调用批量拉取最多 20 个 issue;search_issues_full() 支持原生 GitHub 查询语法并自动追加 repo: 与 is:issue 限定(冲突限定符返回错误);get_repo_overview() 用单条组合查询返回 issue 计数、近期 issue、标签、里程碑与项目;execute_custom_request() 支持 graphql_query / rest_endpoint / rest_url / 自然语言四种模式且强制只读(mutation 被拒绝);get_edit_history() 通过 userContentEdits 与 RenamedTitleEvent 还原标题/正文编辑历史。

PR 操作(pull_requests.py)。 github_pr_manager 提供 post_review()、merge_pr()、inline_comment()、get_pr_files() / get_pr_diff() 等完整 PR 生命周期能力,并支持基于 complexity(low/mid/high)路由到不同内部模型的 AI 代码评审。

工具 handler 注册发生在 src/bot.py 的 setup_hook:从 TOOL_HANDLERS 注册全部 GitHub 工具,随后按配置条件注册 code_search(Vectorize + 本地克隆任一生效即可)、常驻的 web_search、web_scrape(Crawl4AI)、render_visual 与 discord_search。

工具集与权限过滤:调用者决定可见性

架构文档列出的工具常量为 src/ai/tools.py 中的 JSON Schema 定义。当前生效的自定义工具为:github_issue(30 种 action,含子 issue 层级)、github_pr(28 种 action)、github_project(Projects V2 八种操作)、github_overview(单调用仓库总览)、github_custom(只读自定义请求)、code_search(search/grep/read/list/tree/symbols/callers/callees/impact/status 十种动作)、web_search(Perplexity sonar 搜索)、web_scrape(Crawl4AI 八种提取策略)、discord_search(消息/成员/频道/线程/角色检索)、render_visual。架构文档中提到的 DOC_SEARCH_TOOL 与 WEB_TOOL (nomnom) 在当前工具集中已由文档抓取/web_search 等能力取代。

权限过滤集中在 src/ai/tool_filters.py,分三层:

  1. 管理操作过滤:ADMIN_ACTIONS 定义了各工具的管理员 action 集合(如 github_issue 的 close/reopen/edit/label/assign/milestone/lock/link 等);filter_admin_actions_from_tools() 对非管理员剥离描述行与 action 枚举,协作者(collaborator)保留 close/reopen/label/assign 子集;
  2. API 模式过滤:filter_api_tools() 在 API_RESTRICTED_ACTIONS(含 create/comment 等)与 API_EXCLUDED_TOOLS(github_custom、订阅系列、render_visual)之上执行,比 Discord 非管理员更严格;
  3. 意图过滤:filter_tools_by_intent() 用 TOOL_KEYWORDS 的预编译正则对用户消息快速匹配(如 #\d+ 命中 github_issue、charts?|diagrams? 命中 render_visual),无命中时回退到 DEFAULT_TOOLS(code_search、web_search、web_scrape、discord_search、render_visual、github_overview、github_issue),并始终保留 AI 自主控制的工具。结合权限矩阵(README 明确):Discord 成员可读 GitHub + 建 issue/评论;协作者可关闭/重开、管理标签与指派;管理员才有其余变更权;高危动作(merge、delete、lock 等)即使有权限也要求模型先确认。

Webhook 服务器:HMAC 签名验证与 @提及处理

src/integrations/webhook_server.py 用 aiohttp 实现,默认关闭,enabled: true 时监听 0.0.0.0:8002。两个路由:GET /health 健康检查、POST /webhook 事件入口。安全模型与架构文档一致:

  • verify_signature() 对 payload 计算 HMAC-SHA256 并与 X-Hub-Signature-256 头做 hmac.compare_digest 恒时比较;未配置 GITHUB_WEBHOOK_SECRET 时拒绝一切请求;
  • 仓库白名单校验(is_repo_whitelisted)拦截非白名单仓库;
  • 按 X-GitHub-Event 路由到 handle_issue_comment / handle_issue_event / handle_pr_event / handle_pr_review_comment / handle_pr_review,仅处理 created/opened/edited/submitted 等有意义动作;
  • 事件正文须包含对 config.github.bot_username 的 @提及,且 _mentioned_actor 拒绝 Bot 类型用户;
  • process_mention() 中按 admin_user_ids 判定权限,admin_only_mentions: true 时非管理员直接收到拒绝回复;
  • 回复通过 GitHub REST API 回贴(issue comment 场景回 issues 评论端点,PR review comment 场景回 review 回复端点),错误时返回 200 防止 GitHub 重试风暴。

订阅系统:SQLite 存储与轮询通知

src/integrations/subscriptions.py 实现可选订阅:SubscriptionManager 使用 aiosqlite,数据库位于 data/subscriptions.db,启用 WAL 模式与 secure_delete,表结构含 user_id、issue_number、channel_id、guild_id、last_state、last_comment_count、last_labels 等字段(UNIQUE(user_id, issue_number)),并在 data/ 目录上应用 0o700 私有权限。DM 中支持 subscribe #123、unsubscribe #123、unsubscribe all、list subscriptions、privacy 命令。

IssueNotifier 以 _poll_loop() 每 2 分钟轮询:用 GraphQL get_issues_batch 一次拉取全部订阅 issue,比对状态/评论数/标签差异,由 Pollinations 模型格式化通知文案,优先 DM,DM 失败回退到订阅频道并 @提及用户;频道被删除则自动清理订阅。

支撑服务:代码检索与网络抓取

代码检索(code_search)。 架构文档中的 embeddings 模块(OpenAI text-embedding-3-small + ChromaDB)在当前实现中已被替换,README 明确"当前实现不使用 ChromaDB 或 OpenAI embeddings 服务"。code_search 合并三类后端(见 src/search/):本地克隆(精确 grep、文件读取、目录树,仓库默认 pollinations/pollinations 的 main 分支,PR 合并后自动同步)、Cloudflare Vectorize 语义索引(配置 vectorize_index、embed_model、default_top_k/max_top_k,查询端点按 account/index 动态拼接)、本地 CodeGraph 符号图(symbols/callers/callees/impact 遍历,要求先解析出稳定符号 ID,模糊名会被拒绝)。

网络抓取(web_scraper)。 src/integrations/web_scraper.py 以 Crawl4AI 为核心但采用分层降级策略:x.com 走 fxtwitter 公开 JSON API(绕过登录墙)→ 基本 markdown 走 rnet(Chrome TLS 指纹)/ scrapling(curl_cffi)/ Jina Reader → 需要浏览器能力(JS 执行、截图、防爬、提取策略)时再启动共享的 Crawl4AI 浏览器池(专用线程承载事件循环,隔离 Granian 与 Discord 的 ASGI 循环,并发上限 2 个活动标签)。实现还包含登录墙识别(_looks_like_login_wall)、反爬标记检测、LLM 提取走 Pollinations 网关而非 Crawl4AI 内置 dummy provider、语义聚类提取在独立 spawn 子进程中硬超时执行,避免阻塞主事件循环。架构文档中的 _scrape_cache 5 min TTL 对应于工具级 TTLCache 与 5 分钟缓存 TTL 的配置项。

会话上下文:内存 LRU 缓存

src/context/manager.py 实现架构文档描述的会话层,但参数与文档略有演进:当前 MAX_SESSIONS = 500(README 确认内存会话上限 500,而非文档早期版本的 1000),超时由 config.bot.session_timeout_seconds(默认 300 秒)驱动。SessionManager 按线程 ID 索引 ConversationSession(src/context/session.py 中的 dataclass:channel/thread ID、topic_summary、messages、participants、image_urls、时间戳),get_session 命中过期会话即清理并返回 None,容量满时按 last_activity 排序 LRU 淘汰最旧 10 个,cleanup_expired 由 bot 的 1 分钟后台任务周期性调用。Discord 线程历史本身保留在 Discord 平台,内存会话过期不删除任何平台内容。

数据流:一次 @提及的完整旅程

架构文档给出了七步数据流,结合源码可还原为:

  1. 用户在 Discord 频道 @提及 Polli(或回复其消息、右键 Assist);
  2. on_message / assist_context_menu 创建线程,fetch_thread_history 拉取线程历史;
  3. is_admin / is_collaborator 依据角色 ID 判定调用者权限;
  4. process_message 调用 PollinationsClient.process_with_tools,系统提示按 AGENTS.md 模式内嵌知识 + 附加权限模式声明,工具列表经过 filter_admin_actions_from_tools 与 filter_tools_by_intent 双层过滤;
  5. AI 在 _call_with_tools 循环中发起工具调用,_execute_tools_parallel 并行执行(仅动态数据走工具),结果回注消息上下文继续迭代,直至产出最终回答;
  6. 回复经 deliver_reply 格式化发送(含表格/图表/LaTeX/代码块的媒体渲染路径);
  7. 会话经 SessionManager 更新,随后由 1 分钟清理循环管理生命周期。

关键设计决策与演进说明

架构文档总结的四项核心决策在源码中均有印证:

  1. AGENTS.md 模式:静态知识内嵌于系统提示(src/ai/prompts.py 的 BASE_SYSTEM_PROMPT + REPO_INFO),工具仅服务于动态数据;
  2. 原生工具调用:AI 直接以 JSON Schema 调用工具,无正则解析层;防循环引导替代了机械的迭代上限;
  3. GraphQL First:批量查询一次调用覆盖 N 个 issue(get_issues_batch),配合 5 分钟 TTL 的 TTLCache 显著压缩 API 调用量;
  4. LRU 会话缓存:500 会话上限 + 300 秒超时 + 1 分钟清理循环。

此外可观察到两项演进:工具集已加入 render_visual(Discord 可视化渲染)并强化 discord_search(消息/成员/角色检索),架构文档中的 ChromaDB 语义检索已替换为 Cloudflare Vectorize + 本地克隆 + CodeGraph 符号图的三后端组合。部署上,README 提供本地安装(Python 3.11 + Node 22 + Playwright Chromium)、配置(cp .env.example .env)、运行(python main.py)与容器化(docker build -t polli . && docker run --rm --env-file .env polli)的完整指引,测试可通过 python -m unittest discover -s tests -p "test_*.py" 运行,其中 tests/test_openai_api.py、tests/test_subscription_storage.py 等用例直接覆盖了上述关键路径。

登录后查看全文
pollinations