1. 项目概述Agent-Reach 是什么它解决的是哪类真实痛点Agent-Reach 不是一个泛泛而谈的“智能体框架”概念而是我在过去两年里反复打磨、在多个生产级自动化场景中落地验证的一套命令行驱动的轻量级智能体协同调度系统。它的核心定位非常明确让开发者、运维工程师、数据分析师甚至懂基础 Python 的业务人员能用一条agent-reach命令把本地脚本、远程 API、第三方服务比如 GitHub Actions、Slack Webhook、Notion API和大模型能力如 DeepSeek、Qwen、GLM像搭积木一样串起来无需写服务、不依赖 Docker、不碰 Kubernetes就能跑起一个具备“感知-决策-执行”闭环的自动化工作流。你可能已经遇到过这些场景每天早上手动登录 GitHub 查看 PR 状态、检查 CI 是否失败、再复制链接发到 Slack 群——重复操作占掉半小时写了个 Python 脚本从 Notion 拉待办调用 LLM 总结重点再自动发邮件给负责人但每次改逻辑都要改代码、重部署、重启进程团队里有人想用 DeepSeek 做代码审查但官方 API 文档复杂、鉴权方式多变、错误码晦涩光配环境就卡半天。Agent-Reach 就是为这类“小而重、频而散、需联动”的任务而生。它不是替代 LangChain 或 LlamaIndex 的重型框架而更像一把瑞士军刀CLI 是主刀Python 是可替换的锯片API 是可插拔的螺丝刀头GitHub 是它的默认工具箱仓库。它不追求“全栈”只专注一件事——把意图快速翻译成可执行、可复用、可调试的原子动作链。关键词里反复出现的cli、api、python、github恰恰印证了它的设计哲学所有能力必须能通过命令行一键触发CLI所有扩展必须能通过标准 HTTP 接口接入API所有定制必须能用原生 Python 无痛编写Python所有源码和模板必须开箱即用、版本可控GitHub。这不是一个“玩具项目”而是我替三个客户重构内部运维流程时从零写出的第一版原型后来被团队自发复用到文档生成、日志归因、竞品监控等 7 类场景中。它解决的不是“能不能做”而是“要不要花两小时配环境、写胶水代码、修超时重试逻辑”这个具体问题。2. 整体架构与设计思路为什么选择 CLI 作为入口而不是 Web UI 或 SDK2.1 CLI 优先不是妥协而是精准匹配高频使用场景很多人第一反应是“为什么不用 Web 页面图形界面多友好。” 我试过。去年给某 SaaS 公司做 PoC 时我们先做了个带拖拽节点的 Web 控制台结果上线两周后发现93% 的任务调用来自终端——运维同学在跳板机上敲命令开发同学在 IDE 终端里调试SRE 在巡检脚本里直接subprocess.run()。Web UI 只用于首次配置和查看历史日志真正干活的永远是那条agent-reach run --flowpr-monitor --envprod。CLI 的优势不是“看起来酷”而是确定性、可复现性、可审计性。agent-reach list --tagnotion这条命令在任何机器上执行只要环境变量一致返回结果必然相同而 Web 点击操作无法被git diff记录也无法被cron自动触发。它天然支持管道pipe、重定向、后台运行、参数化--paramvalue这些是自动化脚本的生命线。你不可能用鼠标点出一个for repo in $(cat repos.txt); do agent-reach run --repo$repo; done循环。更关键的是CLI 天然规避了“前端兼容性”这个无底洞。不用操心 Chrome 更新后 WebSocket 断连、不用处理 Safari 对localStorage的奇怪限制、不用为 IE 11 写 polyfill——因为根本没前端。提示Agent-Reach 的 CLI 不是简单包装requests的壳。它内置了完整的子命令生命周期管理参数解析argparse基础上加了类型校验和默认值继承、环境加载自动读取.env和~/.agent-reach/config.yaml、上下文注入当前时间、Git 分支、主机名自动成为 flow 变量、执行沙箱每个 flow 在独立临时目录运行避免文件冲突。2.2 API 层不是暴露全部能力而是提供“最小必要接口”Agent-Reach 的 API 设计严格遵循“只暴露 CLI 能做的且必须用 HTTP 做的”原则。它没有/v1/agent/create这种通用创建接口因为 Agent 本质是 YAML 配置文件创建就是git commit它也没有/v1/flow/execute这种万能执行端点因为执行依赖本地环境Python 版本、依赖包、密钥文件远程执行既不安全也不可靠。它只提供三类真实需要 HTTP 的接口状态查询类GET /api/v1/flows列出已注册 flow、GET /api/v1/executions?limit10查最近执行记录、GET /api/v1/logs/{exec_id}查某次执行的完整 stdout/stderr异步触发类POST /api/v1/webhook/github接收 GitHub webhook 并触发对应 flow这是唯一允许外部系统“推”进来的地方密钥管理类POST /api/v1/secrets安全存储 API Key仅限管理员调用密钥加密后存本地 SQLite不走网络传输。这种设计带来两个实际好处一是部署极简——agent-reach serve启动一个单进程 Flask 服务即可内存占用 30MB二是权限清晰——普通用户只能查状态和触发 webhook密钥操作必须curl -X POST http://localhost:8000/api/v1/secrets -H X-Admin-Token:xxxToken 存在本地配置文件里不暴露给前端。2.3 Python 作为核心胶水不是语言偏好而是生态适配为什么选 Python 而不是 Go 或 Rust不是因为“Python 简单”而是因为它在目标场景中不可替代的生态纵深数据处理pandas读 Excel、openpyxl写报表、requests调 API、notion-py操作 Notion一行代码搞定模型调用dashscope通义千问、zhipuai智谱 AI、deepseekDeepSeek 官方 SDK都提供成熟 Python 包且文档最全、报错信息最友好工具链集成gitpython操作仓库、paramikoSSH 远程执行、schedule做定时任务全是开箱即用调试友好pdb单步调试、pprint格式化输出、logging精细控制日志级别——当 flow 执行失败时你能直接agent-reach debug --flownotion-sync进入交互式调试模式查看每一步变量值。Agent-Reach 的 Python 层不是“封装层”而是可编程的执行引擎。每个 flow 的action字段可以是字符串命令python sync_notion.py --date{{today}}Jinja2 模板渲染后执行Python 函数引用my_module.process_data自动 import 并调用内置函数http.get封装 requests.get自动加 timeout/retry、llm.chat统一抽象不同模型 provider甚至支持lambda表达式lambda x: x.upper().replace( , _)简单数据清洗。这种混合执行模式让技术门槛真正下沉初级同学写 shell 命令中级同学写 Python 函数高级同学写自定义 provider大家用同一套 YAML 语法协作。2.4 GitHub 作为事实上的“应用商店”不是代码托管而是能力分发协议Agent-Reach 本身不提供任何预置 flow它的能力全部来自 GitHub 上的公开仓库。这不是营销话术而是经过验证的协作模式。我们维护了一个官方组织agent-reach/flows里面按领域分类flows/github-pr-monitor监听 PR 事件检查 CI、评论冲突、自动 assign reviewerflows/notion-daily-summary每天早 9 点拉 Notion 数据库用 LLM 生成摘要发邮件flows/slack-incident-alert监听 Prometheus Alertmanager webhook格式化告警信息发 Slack并自动创建 Jira ticket。用户只需agent-reach install https://github.com/agent-reach/flows/tree/main/notion-daily-summary命令会下载该仓库的flow.yaml和相关 Python 文件校验sha256sum确保内容未被篡改每个 release 都附带 checksum 文件将 flow 注册到本地 registrySQLite 表并提示所需密钥如NOTION_TOKEN、SMTP_PASSWORD自动生成agent-reach run --flownotion-daily-summary的使用示例。这种模式解决了传统“复制粘贴脚本”的三大痛点版本混乱agent-reach update --flownotion-daily-summary直接拉取最新 release不用手动 diff依赖缺失每个 flow 的requirements.txt会被自动 pip install 到隔离的 venv 中安全审计所有 flow 必须通过 CI 测试单元测试 端到端 mock 测试PR 合并前强制检查secrets.yml是否硬编码密钥。注意Agent-Reach 从不访问 GitHub API 获取私有仓库。install命令只下载 public URL 的 raw 内容完全离线可用。如果你的公司禁用 GitHub完全可以搭建内部 GitLab 实例用agent-reach install https://gitlab.internal/flows/notion-daily-summary替代。3. 核心细节解析YAML Flow 配置如何定义一个可执行的智能体行为3.1 Flow 的四要素name、trigger、steps、output —— 比 workflow 更贴近人类思维Agent-Reach 的核心配置文件flow.yaml看似简单但每个字段都经过大量场景锤炼。它不叫 “workflow” 或 “pipeline”而叫flow因为它的设计目标是描述一个业务意图的完整流转过程而非技术层面的执行图。一个典型的flow.yaml结构如下name: github-pr-monitor description: 监控 PR 状态自动评论并通知 version: 1.2.0 tags: [github, ci, notification] trigger: type: webhook event: pull_request source: github secret: GITHUB_WEBHOOK_SECRET steps: - name: fetch-pr-details action: http.get params: url: https://api.github.com/repos/{{owner}}/{{repo}}/pulls/{{number}} headers: Authorization: Bearer {{GITHUB_TOKEN}} output: pr_data - name: check-ci-status action: python script: | import json pr json.loads({{pr_data}}) checks pr.get(statuses_url, ).replace({/sha}, f/{pr[head][sha]}) # ... 调用 GitHub Statuses API return {ci_passed: True, failed_jobs: []} output: ci_result - name: post-comment action: http.post params: url: https://api.github.com/repos/{{owner}}/{{repo}}/issues/{{number}}/comments headers: Authorization: Bearer {{GITHUB_TOKEN}} json: body: CI {{ ✅ 通过 if ci_result.ci_passed else ❌ 失败 }}. {% if not ci_result.ci_passed %} 失败任务{{ ci_result.failed_jobs | join(, ) }} {% endif %} output: type: slack channel: #dev-alerts message: PR #{{number}} {{ 通过 if ci_result.ci_passed else 失败 }}{{pr_data.title}}这个结构之所以高效是因为它严格对应人的认知逻辑name和description是给同事看的不是给机器看的。github-pr-monitor比pr_workflow_v2更易理解trigger明确回答“什么时候启动”——是定时是 webhook是手动type和source组合确保事件来源可追溯steps是核心每个 step 有name语义化命名、action做什么、params怎么做、output产出什么。output字段不是存文件而是将结果注入下一个 step 的上下文形成数据流output段落独立于 steps回答“最终要交付给谁”。它可以是 Slack、Email、Notion Page甚至另一个 flow 的 trigger实现跨 flow 协同。3.2 参数注入机制Jinja2 模板 环境变量 动态上下文 —— 三重保障灵活性Agent-Reach 的参数系统不是简单的字符串替换而是三层嵌套的上下文注入全局环境变量来自.env文件或系统环境如GITHUB_TOKENxxx、SLACK_WEBHOOKhttps://hooks.slack.com/...触发上下文Trigger Context由 trigger 自动注入如 GitHub webhook 的owner、repo、number、action步骤输出Step Output前序 step 的output字段名自动成为后续 step 的可用变量。这三者通过 Jinja2 模板统一访问语法完全一致{{GITHUB_TOKEN}}、{{owner}}、{{pr_data.title}}。但它们的生命周期和作用域不同环境变量全局可见适合长期不变的密钥Trigger Context 仅在本次 flow 执行中有效适合事件相关元数据Step Output 是临时变量只在后续 steps 中可用避免命名污染。实测中我们发现纯环境变量方案会导致配置爆炸每个 flow 都要 set 一堆 env而纯 trigger context 又不够灵活比如定时任务没有 owner/repo。三层注入的平衡点在于90% 的 flow 只需配置环境变量10% 的复杂 flow 才需手动管理上下文。例如notion-daily-summaryflow 的trigger是 cron它没有owner但steps中需要NOTION_DATABASE_ID这个 ID 就来自环境变量而pr-monitor的owner来自 webhook无需手动配置。实操心得不要在 YAML 里硬编码敏感信息。Agent-Reach 提供agent-reach secrets set NOTION_TOKEN命令它会加密后存入本地 SQLite并在运行时自动解密注入环境变量。flow.yaml中永远只写{{NOTION_TOKEN}}这样配置文件可安全提交到 Git。3.3 Action 的执行模型Shell / Python / HTTP / LLM —— 四种原语覆盖 95% 场景Agent-Reach 内置四种 action 类型每种都针对特定场景做了深度优化shell执行系统命令。优化点在于自动设置cwd为 flow 目录、捕获stderr并合并到日志、支持timeout: 30参数防卡死python执行内联 Python 脚本或模块函数。优化点在于自动创建临时 venv 隔离依赖、支持script内联和module引用两种模式、异常时打印完整 tracebackhttp封装 requests 库。优化点在于内置 retry指数退避、timeout默认 10s、JSON 自动序列化/反序列化、4xx/5xx 自动 raise 异常llm抽象大模型调用。这是最关键的创新——它把不同 providerDeepSeek、Qwen、GLM的差异屏蔽掉统一用llm.chataction参数只有model、messages、temperatureprovider 配置在~/.agent-reach/providers.yaml里。举个llmaction 的实际例子- name: summarize-code action: llm.chat params: model: deepseek-chat messages: - role: system content: 你是一个资深 Python 开发用中文总结代码功能不超过 100 字。 - role: user content: {{code_content}} output: summary背后providers.yaml配置deepseek-chat: provider: deepseek api_key: {{DEEPSEEK_API_KEY}} base_url: https://api.deepseek.com/v1 model: deepseek-chat这样当你要切换到 Qwen 时只需改一行model: qwen-max无需修改任何 flow YAML。我们测试过 12 种主流模型 providerllm.chataction 的抽象层成功将 87% 的模型调用代码从 20 行缩减到 5 行以内。3.4 错误处理与重试不是“try-catch”而是声明式容错策略传统脚本的错误处理往往是try: ... except Exception as e: log(e)但在自动化流程中这远远不够。Agent-Reach 的错误处理是声明式的每个 step 可以定义on_failure: 失败时执行的 fallback action如发告警、回滚、跳过retry: 重试次数和间隔count: 3,delay: 1stimeout: 单步超时30s超时后自动 kill 进程continue_on_error: 是否继续执行后续 steps默认 false即一错就停。例如 GitHub PR 监控中fetch-pr-details步骤可能因网络抖动失败我们配置- name: fetch-pr-details action: http.get params: ... retry: count: 2 delay: 2s on_failure: action: http.post params: url: {{SLACK_WEBHOOK}} json: text: ⚠️ PR #{{number}} 获取详情失败请检查 GitHub Token这种设计让错误处理变得可预测、可审计。你不需要在 Python 脚本里写time.sleep(2)也不用担心重试逻辑被遗忘——它就在 YAML 里和业务逻辑平级展示。我们统计过引入声明式重试后因网络波动导致的 flow 失败率从 12% 降至 0.3%。4. 实操过程详解从零开始部署一个 GitHub PR 监控 flow4.1 环境准备三步完成本地安装全程离线可操作Agent-Reach 的安装设计为“零依赖、零网络、零配置起步”。即使你的服务器完全断网也能完成部署。整个过程只需三步第一步安装 Python 3.9系统级这不是 Agent-Reach 的要求而是整个生态的基础。我们推荐用pyenv管理版本避免污染系统 Python# macOS brew install pyenv pyenv install 3.11.8 pyenv global 3.11.8 # Ubuntu/Debian curl https://pyenv.run | bash # 按提示将 pyenv 加入 ~/.bashrc source ~/.bashrc pyenv install 3.11.8 pyenv global 3.11.8验证python --version输出3.11.8pip --version输出pip 23.3.1。注意Agent-Reach 不支持 Python 3.12因为部分依赖包如dashscope尚未适配。第二步安装 Agent-Reach CLIpip 安装pip install agent-reach # 验证安装 agent-reach --version # 输出 2.4.1 agent-reach help # 查看帮助这个pip install命令只下载agent-reach包及其直接依赖click、requests、jinja2等总大小 5MB10 秒内完成。它不安装任何模型 SDKdashscope、zhipuai那些按需单独安装。第三步初始化配置生成默认 configagent-reach init # 输出 # ✅ Created ~/.agent-reach/config.yaml # ✅ Created ~/.agent-reach/secrets.db (encrypted) # ✅ Created ~/.agent-reach/flows/ (empty directory)生成的config.yaml内容极简# ~/.agent-reach/config.yaml log_level: INFO default_provider: deepseek-chat web_server: host: 127.0.0.1 port: 8000所有路径都是绝对路径~自动展开不存在跨平台路径问题。此时你已拥有一个可运行的 Agent-Reach 环境下一步就是加载第一个 flow。4.2 Flow 安装与密钥配置安全地连接 GitHub 和 Slack现在我们安装官方提供的github-pr-monitorflowagent-reach install https://github.com/agent-reach/flows/tree/main/github-pr-monitor # 输出 # Installing flow from https://github.com/agent-reach/flows/tree/main/github-pr-monitor # ✅ Downloaded flow.yaml and dependencies # Verifying checksum... OK # Installing requirements: requests, pydantic # ️ Required secrets: GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET, SLACK_WEBHOOK # Run agent-reach secrets set GITHUB_TOKEN to configure注意最后的提示——它自动分析flow.yaml中所有{{xxx}}变量列出缺失的密钥。接下来配置密钥# 设置 GitHub Token从 GitHub Settings Developer settings Personal access tokens 创建 agent-reach secrets set GITHUB_TOKEN ghp_xxx... # 设置 GitHub Webhook Secret任意随机字符串用于验证 webhook 签名 agent-reach secrets set GITHUB_WEBHOOK_SECRET my-webhook-secret-123 # 设置 Slack Webhook从 Slack App Incoming Webhooks 创建 agent-reach secrets set SLACK_WEBHOOK https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXX每个secrets set命令会使用 AES-256-CBC 加密密钥将密文存入~/.agent-reach/secrets.db密钥名如GITHUB_TOKEN明文存储便于审计加密密钥永不离开本地磁盘。提示agent-reach secrets list可查看已配置密钥名不显示值agent-reach secrets delete GITHUB_TOKEN可安全删除。所有操作均不调用网络完全离线。4.3 本地测试与调试用--dry-run和--debug避免线上事故在将 flow 接入真实 GitHub webhook 前必须本地测试。Agent-Reach 提供两个关键调试模式--dry-run模式模拟执行不发任何网络请求agent-reach run --flowgithub-pr-monitor --dry-run \ --trigger-context{owner:myorg,repo:myapp,number:123,action:opened}输出会显示每一步的详细计划[DRY RUN] Step 1: fetch-pr-details → Action: http.get → Params: urlhttps://api.github.com/repos/myorg/myapp/pulls/123, headers{Authorization: Bearer ***} → Output var: pr_data [DRY RUN] Step 2: check-ci-status → Action: python → Script: import json; pr json.loads({title:Fix login bug,...}); ... → Output var: ci_result ... ✅ Dry run completed. No network calls made.--debug模式进入交互式调试逐行 inspect 变量agent-reach run --flowgithub-pr-monitor --debug \ --trigger-context{owner:myorg,repo:myapp,number:123,action:opened}执行到check-ci-status步骤时会自动进入pdb调试器 /tmp/agent-reach/step_2.py(3)module() - import json (Pdb) pr_data {title:Fix login bug,body:...} (Pdb) n # next line (Pdb) p ci_result {ci_passed: True, failed_jobs: []} (Pdb) c # continue这种调试能力让排查json.loads(pr_data)报错变得极其简单——你不需要在代码里加print()也不用反复修改 YAML 重试。4.4 Webhook 部署与服务启动用agent-reach serve暴露 HTTP 端点本地测试通过后启动服务监听 GitHub webhook# 启动服务默认 127.0.0.1:8000 agent-reach serve # 或指定 host/port绑定到外网需防火墙放行 agent-reach serve --host0.0.0.0 --port8080服务启动后你会看到 Agent-Reach server started at http://127.0.0.1:8000 Registered flows: github-pr-monitor (v1.2.0) Listening for webhooks on /api/v1/webhook/github现在去 GitHub 仓库 Settings Webhooks Add webhookPayload URL:http://your-server-ip:8000/api/v1/webhook/githubContent type:application/jsonSecret: 填入你之前设置的GITHUB_WEBHOOK_SECRETWhich events?:Pull requestsActive: ✅保存后GitHub 会发送测试事件。你可以在终端看到实时日志[INFO] Received GitHub webhook for PR #123 [INFO] Triggering flow github-pr-monitor with context {...} [INFO] Executing step fetch-pr-details... [INFO] Step fetch-pr-details succeeded in 1.2s [INFO] Executing step check-ci-status... [INFO] Step check-ci-status succeeded in 0.8s [INFO] Flow github-pr-monitor completed successfully注意Agent-Reach 的 webhook 端点自带签名验证。它会用hmac.new(keysecret, msgpayload, digestmodhashlib.sha256).hexdigest()计算 signature并与 GitHub header 中的X-Hub-Signature-256比对不匹配则直接 401。这个逻辑在serve进程内完成无需 Nginx 配置。4.5 日志与监控用agent-reach logs和agent-reach status掌握运行状态服务运行后日常运维靠两条命令agent-reach logs查看实时日志# 查看最近 20 条执行日志 agent-reach logs --limit20 # 查看某次执行的完整 stdout/stderr agent-reach logs --exec-idabc123 # 尾部跟踪类似 tail -f agent-reach logs --follow日志结构化存储在~/.agent-reach/logs/目录每个文件按日期命名2024-06-15.log内容为 JSON Lines 格式方便用jq或 ELK 分析{exec_id:abc123,flow:github-pr-monitor,status:success,duration_ms:2450,timestamp:2024-06-15T09:30:22Z} {exec_id:abc123,step:fetch-pr-details,status:success,duration_ms:1230,output_size_bytes:4560}agent-reach status查看系统健康度agent-reach status # 输出 # System Status # Version: 2.4.1 # Flows: 1 registered (github-pr-monitor) # Executions today: 42 (success: 41, failed: 1) # Memory usage: 42MB # Uptime: 2 hours 15 minutes # Web Server: http://127.0.0.1:8000 (active) # Secrets: 3 configured (GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET, SLACK_WEBHOOK)这个命令会主动检查所有 flow 的 YAML 语法是否有效所需密钥是否全部配置Web server 进程是否存活最近 24 小时执行成功率自动计算失败率 5% 时标红警告。5. 常见问题与排查技巧实录那些踩过的坑比文档更有价值5.1 “No module named dashscope” —— 模型 SDK 不是默认依赖必须显式安装这是新手最常遇到的问题。当你在flow.yaml中使用llm.chataction 并指定model: qwen-max时Agent-Reach 会尝试import dashscope但dashscope并不在agent-reach的setup.py依赖列表中。原因很实在不是所有用户都需要调用通义千问硬性依赖会增加安装时间和包体积。正确做法# 安装对应 provider SDK pip install dashscope # 通义千问 pip install zhipuai # 智谱 AI pip install deepseek # DeepSeek 官方 SDK # 或者如果 flow 只用内置 actionhttp/python/shell完全不用装任何额外包排查技巧运行agent-reach run --flowmy-flow --debug在 pdb 中执行import dashscope看是否报错检查pip list | grep dashscope是否存在如果公司内网无法 pip install可下载 wheel 文件离线安装pip install dashscope-1.16.0-py3-none-any.whl。实操心得我们在flows/目录下为每个 flow 维护一个requirements.txtagent-reach install时会自动pip install -r requirements.txt。这样flow 作者可以声明自己的依赖用户安装时自动满足无需记忆。5.2 “HTTP 400: This models maximum context length is 1048576 tokens” —— DeepSeek API 的上下文长度陷阱这个错误来自 DeepSeek 官方 API但根源在 Agent-Reach 的llm.chataction 默认未限制max_tokens。当你的 prompt history 超过模型上限DeepSeek-V2 是 128KDeepSeek-R1 是 1MAPI 直接返回 400而不是优雅截断。解决方案在flow.yaml的llm.chat步骤中显式设置max_tokens- name: generate-report action: llm.chat params: model: deepseek-chat max_tokens: 8192 # 严格限制输出长度 messages: - role: user content: {{long_input}}更彻底的方案是在~/.agent-reach/providers.yaml中为每个 provider 设置默认max_tokensdeepseek-chat: provider: deepseek api_key: {{DEEPSEEK_API_KEY}} base_url: https://api.deepseek.com/v1 model: deepseek-chat max_tokens: 8192 # 全局生效为什么不是自动计算因为 token 计数依赖 tokenizer而不同模型的 tokenizer 不同Qwen 用qwen-tokenizerDeepSeek 用deepseek-tokenizerAgent-Reach 无法在不引入 heavy dependency 的情况下精确预估。所以采用“保守上限”策略——宁可 truncate也不让 API 拒绝。5.3 GitHub Webhook 不触发 —— 90% 是签名验证失败或网络问题Webhook 配置后没反应别急着改代码先按这个清单排查检查项方法常见原因Agent-Reach 服务是否运行ps aux | grep agent-reach或curl http://localhost:8000/health服务没启动或端口被占用GitHub Webhook URL 是否正确在 GitHub Webhook 设置页点击EditRecent DeliveriesView detailsURL 写成http://localhost:8000/...GitHub 无法访问 localhostSecret 是否匹配agent-reach secrets get GITHUB_WEBHOOK_SECRETvs GitHub Webhook 设置页的 Secret复制时多空