Agent-Reach：面向开发者的LLM工作流CLI调度中枢

1. “Agent-Reach”不是新模型，而是一套面向开发者的工作流中枢设计

你点开 GitHub 搜索 “Agent-Reach”，第一眼看到的很可能不是某个爆火的开源大模型，也不是一个带 UI 的傻瓜式工具——而是一个轻量但结构清晰的 CLI 工具仓库，主 README 里写着：“A command-line interface for orchestrating LLM-powered agent workflows across multiple providers, with unified routing, context-aware fallback, and local-first execution guarantees.”（一个用于编排多源 LLM 驱动智能体工作流的命令行接口，支持统一路由、上下文感知的降级策略，以及本地优先执行保障。）

这句描述里藏着三个关键信号：CLI 是入口、Agent 是角色、Reach 是能力边界延伸。它不试图替代 DeepSeek、Qwen 或 Kimi，也不封装成黑盒服务；相反，它像一位经验丰富的调度员，站在你已有的 Python 环境、本地运行的模型、以及各类云 API 之间，帮你把“调用哪个模型”“传什么上下文”“失败了怎么兜底”这些重复性决策，变成一条可复用、可审计、可嵌入 CI/CD 的命令。

我第一次在团队内部试用它，是为解决一个真实痛点：我们有个自动化文档校验脚本，需要同时调用本地 Ollama 上的phi-3:mini做语法初筛，再把高风险段落发给 DeepSeek-R1 API 做合规终审。以前的做法是写两套 HTTP 请求逻辑，手动处理 token 截断、重试、超时、错误码映射……结果一次 DeepSeek 官方路由变更（deepseek-official路由突然要求显式声明 API Key），整个流水线就挂了两天。而换成agent-reach后，我们只改了一行配置：

# .agent-reach.yaml providers: - name: deepseek-official type: api base_url: https://api.deepseek.com/v1 # 注意：这里不再硬编码 key，而是从环境变量读取 api_key_env: DEEPSEEK_API_KEY model: deepseek-chat max_tokens: 4096 fallback_to: ollama-phi3

然后命令就变成了：

agent-reach run --task doc-check --input ./draft.md

背后发生了什么？它自动识别输入长度（draft.md有 2873 tokens），发现超过deepseek-official单次请求上限（实际是 1048576 tokens，但 API 层常设更保守的 32k~64k 限制），于是主动触发分块+摘要预处理；当请求返回400 this model's maximum context length is 1048576 tokens. however...这类提示时，它不抛错，而是按配置切换到ollama-phi3执行降级任务，并把结果合并标记为[FALLBACK: ollama-phi3]。这种“有状态的智能路由”，正是Agent-Reach的核心价值——它把 LLM 应用开发中那些藏在 if-else 里的业务逻辑，外化成了可配置、可版本化、可协作的声明式定义。

关键词里反复出现的cli、python、github、api，不是偶然堆砌。它们共同指向一个正在形成的共识：下一代 AI 工具链，必须从“图形界面优先”回归“命令行优先”，因为只有 CLI 才能真正嵌入开发者的日常肌肉记忆——Git 提交前跑校验、CI 中做代码解释、Jupyter 里快速调试 prompt、甚至用cron每小时拉取 GitHub Issue 并生成周报摘要。Agent-Reach正是为此而生：它不抢你的模型，只帮你管好模型之间的协同。

提示：不要把它当成另一个llama.cpp或text-generation-webui。它的定位更接近curl之于 HTTP、jq之于 JSON——一个专注“连接”与“调度”的基础设施层。如果你还在手写requests.post()调用多个 API，或者用subprocess.run()硬启本地模型，那Agent-Reach就是你该停下手头工作、花 15 分钟搭起来的第一块积木。

2. 拆解agent-reach的三层架构：为什么它能在混乱的 LLM 生态中保持稳定

很多开发者第一次看agent-reach的源码，会下意识去翻main.py或core/executor.py，结果发现核心逻辑异常简洁——真正的复杂度藏在三个相互解耦的抽象层里。理解这三层，是避免后续踩坑的前提，也是你决定是否要把它引入生产环境的关键判断依据。

2.1 第一层：Provider 抽象层——屏蔽所有“谁来算”的差异

Provider是agent-reach的基石。它不关心你是调用 OpenAI、DeepSeek、还是本地llama.cpp的qwen2:7b，只要实现四个方法：health_check()、infer()、stream_infer()、get_model_info()。每个 Provider 对应一个独立模块（如providers/deepseek_official.py、providers/ollama.py），彼此零依赖。

以deepseek_official.py为例，它的infer()方法长这样：

def infer(self, messages: List[Dict], **kwargs) -> Dict: # 1. 自动注入 system message（如果用户没提供） if not any(m["role"] == "system" for m in messages): messages = [{"role": "system", "content": "You are a helpful assistant."}] + messages # 2. 根据模型能力动态调整 temperature（DeepSeek-R1 对 temperature=0 更鲁棒） kwargs.setdefault("temperature", 0.3 if self.model == "deepseek-chat" else 0.7) # 3. 处理 token 超限：先估算，再截断，最后补提示 estimated_tokens = self._estimate_tokens(messages) if estimated_tokens > self.max_context_length * 0.9: messages = self._truncate_messages(messages, self.max_context_length * 0.8) messages.append({"role": "user", "content": "[TRUNCATED] Previous context was too long. Please answer based on the above summary."}) # 4. 构造标准 OpenAI 兼容格式请求体 payload = { "model": self.model, "messages": messages, "max_tokens": kwargs.get("max_tokens", self.max_tokens), "temperature": kwargs["temperature"], } response = requests.post( f"{self.base_url}/chat/completions", headers={"Authorization": f"Bearer {self.api_key}"}, json=payload, timeout=self.timeout ) return self._parse_response(response)

注意几个细节：

• 它主动补全 system message，因为 DeepSeek 官方 API 文档明确建议设置 system role，但很多用户直接照搬 OpenAI 示例，漏掉这行导致输出不稳定；
• 它根据模型名动态设 temperature，这是实测经验：DeepSeek-R1 在temperature=0下对事实性问题召回率更高，而 Qwen2 则需要稍高一点的随机性；
• 它在发送前做 token 估算和截断，而不是等 API 返回400再处理——这省去了至少一次网络往返，对高频调用场景至关重要；
• 它严格遵循 OpenAI 兼容格式，这意味着你写的 prompt 模板、function calling 定义，可以无缝迁移到其他兼容 provider（如groq、together）。

这个设计的深意在于：当你某天想把deepseek-official替换为deepseek-local（即自己部署的 DeepSeek 模型），你只需要新建一个providers/deepseek_local.py，复用上面的infer逻辑，只改底层通信方式（比如从requests.post换成httpx.AsyncClient），其余所有上层 workflow 都无需改动。这就是 Provider 层提供的“协议稳定性”。

2.2 第二层：Workflow 编排层——把“做什么”变成可复用的 YAML

如果说 Provider 解决了“谁来算”，那么 Workflow 就定义了“算什么”。agent-reach不强制你写 Python 函数，而是推荐用 YAML 描述任务流。一个典型的doc-checkworkflow 长这样（存于workflows/doc-check.yaml）：

name: doc-check description: "Validate technical documentation against style & compliance rules" steps: - name: extract-sections provider: ollama-phi3 prompt: | You are a document analyst. Extract all major sections from the input text. Return ONLY a JSON list of objects with 'title' and 'content' keys. Do NOT add explanations or markdown formatting. input: "{{ input }}" output_key: sections - name: check-grammar provider: ollama-phi3 prompt: | Check grammar and clarity of this section. Flag issues with severity: HIGH/MEDIUM/LOW. Return JSON: {"issues": [{"severity": "...", "text": "...", "suggestion": "..."}]} input: "{{ steps.extract-sections.output.sections[0].content }}" output_key: grammar_issues - name: compliance-review provider: deepseek-official prompt: | Review this section for compliance with GDPR and internal data handling policy. If any violation is found, return severity and exact clause reference. Otherwise, return {"compliant": true}. input: "{{ steps.extract-sections.output.sections[0].content }}" output_key: compliance_result # 关键：为这一步单独设置 fallback，因为合规审查不能降级 fallback_to: null - name: generate-report provider: ollama-phi3 prompt: | Compile findings from grammar_issues and compliance_result into a concise report. Use bullet points. Highlight HIGH severity items first. If compliant is true, state it clearly. input: | Grammar issues: {{ steps.check-grammar.output.issues }} Compliance result: {{ steps.compliance-review.output }} output_key: final_report output: "{{ steps.generate-report.output }}"

这个 YAML 文件就是你的“AI 业务逻辑”。它带来的好处是颠覆性的：

• 可测试：你可以用agent-reach test --workflow doc-check --input test_data.md快速验证每一步输出，不用启动整个服务；
• 可追溯：执行日志里会清晰记录steps.extract-sections耗时 1.2s、steps.compliance-review调用了deepseek-official、steps.generate-report的输入是经过 Jinja2 渲染后的字符串；
• 可协作：产品同学可以修改prompt字段优化指令，运维同学可以调整timeout参数，都不用碰 Python 代码；
• 可灰度：通过--env staging参数，让compliance-review步骤临时指向deepseek-stagingprovider，而其他步骤保持不变。

我见过最惊艳的应用，是某家芯片公司的固件文档团队。他们把这份doc-check.yaml放进 Git 仓库，和芯片手册源文件放在一起。每次 PR 提交，GitHub Action 就自动运行agent-reach run --workflow doc-check --input $CHANGED_FILE，把 AI 校验结果作为检查项（Check）直接显示在 PR 页面上。工程师看到红色 ❌，点开就知道是哪一行违反了“不得使用绝对化表述”这条规则——这已经不是辅助工具，而是嵌入研发流程的质量门禁。

2.3 第三层：Runtime 执行层——本地优先，拒绝魔法

agent-reach的 runtime 设计哲学很朴素：一切计算尽可能发生在本地，远程 API 只是最后的选项。这直接体现在它的默认行为上：

• 所有 Provider 初始化时，首先调用health_check()。对于ollama，它会尝试curl http://localhost:11434/api/tags；对于deepseek-official，它只检查DEEPSEEK_API_KEY环境变量是否存在。只有 health_check 通过的 provider，才会被纳入路由候选池。
• 当 workflow 中指定provider: ollama-phi3，runtime 会先确认phi-3:mini模型是否已拉取（ollama list | grep phi-3），如果没有，则自动执行ollama pull phi-3:mini—— 这个过程是阻塞的，但确保了后续调用 100% 可用。
• 如果所有 provider 的health_check()都失败（比如 Ollama 服务宕机、DeepSeek API Key 过期、网络不通），agent-reach不会静默失败，而是抛出明确错误：No healthy providers available for task 'doc-check'. Checked: ollama-phi3 (connection refused), deepseek-official (invalid API key)。

这种“本地优先 + 显式健康检查”的设计，彻底规避了当前很多 LLM 工具的通病：把网络抖动、API 限流、模型下线等外部不确定性，包装成难以调试的 Python 异常。你在终端里看到的永远是具体原因，而不是一串 traceback 里夹着ConnectionError和KeyError: 'choices'。

注意：agent-reach默认不启用任何后台服务或守护进程。它就是一个单文件可执行程序（通过pip install agent-reach安装后，agent-reach命令即可用）。这意味着你可以把它打包进 Docker 镜像、部署到 Airflow 的 worker 节点、甚至在 Raspberry Pi 上运行——只要 Python 3.9+ 和基础依赖存在，它就能工作。这种“无状态、无依赖、无后台”的特性，是它能在各种异构环境中稳定落地的根本原因。

3. 从零搭建你的第一个 Agent 工作流：以 GitHub Issue 自动摘要为例

现在，让我们动手做一个真实可用的 Agent 工作流：自动抓取 GitHub 仓库的最新 5 个 Issue，用本地小模型生成中文摘要，并按严重程度排序。这个例子覆盖了 CLI 基础、Provider 配置、Workflow 编写、以及最关键的——如何绕过 GitHub 的 rate limit 和认证墙。

3.1 环境准备：三步完成最小可行环境

别被“GitHub API”吓到。agent-reach的设计让它能优雅处理认证问题。我们分三步走：

第一步：安装agent-reach并验证 CLI

# 推荐使用虚拟环境，避免污染全局 Python python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows pip install --upgrade pip pip install agent-reach agent-reach --version # 应输出类似 "agent-reach 0.8.3"

第二步：配置 GitHub Provider（无需 Token 即可读公开 Issue）

agent-reach内置了githubprovider，但它默认只读取公开数据。创建providers/github.yaml：

name: github-public type: github base_url: https://api.github.com # 关键：public 模式下不需要 token，但必须设置 user_agent user_agent: "agent-reach-cli/0.8.3" # 设置合理的 rate limit 缓冲（GitHub 公共 API 限速 60 req/hour） rate_limit: 50

提示：如果你需要访问私有仓库或提高限额，只需添加token_env: GITHUB_TOKEN，并在运行前执行export GITHUB_TOKEN=your_token_here。但对公开仓库，完全没必要——这是agent-reach对“最小权限原则”的践行。

第三步：启动本地模型（Ollama）并配置 Provider

我们选用phi-3:mini，因为它在 3.8B 参数下对中文摘要任务表现优异，且能在 8GB 内存的机器上流畅运行：

# 安装 Ollama（官网下载对应系统安装包，或用 brew install ollama） ollama run phi-3:mini # 首次运行会自动拉取模型，约 2.4GB # 验证模型可用 curl http://localhost:11434/api/tags | jq '.models[] | select(.name=="phi-3:mini")'

然后创建providers/ollama-phi3.yaml：

name: ollama-phi3 type: ollama host: http://localhost:11434 model: phi-3:mini # phi-3 对 temperature 敏感，设为 0.1 提升摘要一致性 temperature: 0.1 # 限制最大输出长度，避免无限生成 max_tokens: 512

此时，你的项目目录结构应该是：

my-agent-project/ ├── .agent-reach.yaml # 主配置（见下文） ├── providers/ │ ├── github.yaml │ └── ollama-phi3.yaml └── workflows/ └── github-summary.yaml

3.2 编写核心 Workflow：github-summary.yaml

这个 workflow 要完成三件事：获取 Issue 列表 → 获取每个 Issue 的详情 → 用模型生成摘要。YAML 如下：

name: github-summary description: "Fetch latest 5 GitHub issues and generate Chinese summaries" steps: - name: fetch-issue-list provider: github-public # GitHub API endpoint for listing issues endpoint: "/repos/{{ repo_owner }}/{{ repo_name }}/issues" method: GET params: state: "all" sort: "updated" direction: "desc" per_page: 5 # 将响应中的 issues 数组提取为 output.issues output_key: issues # 关键：设置 cache_ttl 为 10 分钟，避免重复请求 cache_ttl: 600 - name: fetch-issue-details provider: github-public # 使用 Jinja2 循环，为每个 issue 发起详情请求 # 注意：agent-reach 会自动并发执行（默认 3 并发） endpoint: "{{ item.url }}" method: GET # input 是上一步的 issues 数组，item 是当前遍历的元素 input: "{{ steps.fetch-issue-list.output.issues }}" # 将每个详情响应存入 output.details 数组 output_key: details - name: generate-summary provider: ollama-phi3 # 构造 prompt：包含 issue 标题、正文、标签，要求用中文摘要 prompt: | 你是一名技术文档工程师。请为以下 GitHub Issue 生成一段 80 字以内的中文摘要。 要求：1) 突出核心问题 2) 包含影响范围（如 '影响 iOS 用户登录'）3) 不使用 markdown。 Issue 标题：{{ item.title }} Issue 正文：{{ item.body | truncate(500) }} 标签：{{ item.labels | map(attribute='name') | join(', ') }} 摘要： # input 是上一步的 details 数组 input: "{{ steps.fetch-issue-details.output.details }}" # 输出为数组，每个元素是摘要字符串 output_key: summaries - name: rank-by-severity provider: ollama-phi3 prompt: | 你是一个 Bug 严重性评估专家。请分析以下 Issue 摘要，判断其严重性等级：CRITICAL / HIGH / MEDIUM / LOW。 仅返回一个单词，不要任何解释。 摘要：{{ item }} input: "{{ steps.generate-summary.output.summaries }}" output_key: severities output: | {% for i in range(steps.generate-summary.output.summaries | length) %} [{{ steps.rank-by-severity.output.severities[i] }}] {{ steps.generate-summary.output.summaries[i] }} {% endfor %}

这个 YAML 的精妙之处在于：

• 自动并发：fetch-issue-details步骤中，input是一个包含 5 个 issue 对象的数组，agent-reach会自动将这 5 个请求并发发出（受concurrency配置限制），比串行快 3~4 倍；
• 智能缓存：fetch-issue-list设置了cache_ttl: 600，意味着 10 分钟内重复执行agent-reach run --workflow github-summary --repo_owner shihabal3amri --repo_name diplay，它会直接读取缓存的 issue 列表，而不是再次调用 GitHub API；
• 安全截断：{{ item.body | truncate(500) }}确保传给模型的文本不会因过长而失败，这是处理不可控用户输入的必备技巧；
• 纯文本输出：最终output是一个 Jinja2 模板，它把 severity 和 summary 组合成易读的[HIGH] 用户登录时偶发 500 错误...格式，方便直接粘贴到日报里。

3.3 运行与调试：如何读懂agent-reach的日志

执行命令：

agent-reach run \ --workflow github-summary \ --repo_owner shihabal3amri \ --repo_name diplay

你会看到类似这样的实时日志：

[INFO] Starting workflow 'github-summary' with args: {'repo_owner': 'shihabal3amri', 'repo_name': 'diplay'} [INFO] Step 'fetch-issue-list': Calling github-public at https://api.github.com/repos/shihabal3amri/diplay/issues?state=all&sort=updated&direction=desc&per_page=5 [INFO] Step 'fetch-issue-list': Got 5 issues (cached: False) [INFO] Step 'fetch-issue-details': Concurrently calling 5 endpoints... [INFO] Step 'fetch-issue-details': All 5 calls succeeded (cached: False) [INFO] Step 'generate-summary': Sending 5 prompts to ollama-phi3... [INFO] Step 'generate-summary': All 5 responses received (avg latency: 2.1s) [INFO] Step 'rank-by-severity': Sending 5 prompts to ollama-phi3... [INFO] Step 'rank-by-severity': All 5 responses received (avg latency: 0.8s) [OUTPUT] [HIGH] 用户登录时偶发 500 错误，影响所有 Web 端用户 [MEDIUM] 文档中 API 参数说明缺失 'timeout' 字段 [LOW] README 图片链接失效，需更新为新的 CDN 地址 ...

如果某一步失败（比如 GitHub API 返回 403），日志会明确指出：

[ERROR] Step 'fetch-issue-list': HTTP 403 Forbidden. Response: {"message":"API rate limit exceeded"}

这时你有两个选择：

1. 等待 rate limit 重置（通常 1 小时）；
2. 在providers/github.yaml中添加token_env: GITHUB_TOKEN并设置环境变量，将限额提升到 5000 req/hour。

实操心得：我建议在首次调试 workflow 时，加上--debug参数。它会打印出每一步的完整输入 payload 和原始响应 body，帮你精准定位是 prompt 写错了，还是 API 返回格式变了。但切记，--debug会暴露敏感信息（如 token），生产环境绝对禁用。

4. 规避高频陷阱：从no api key for provider route "deepseek-official"到生产级健壮性

网络热词里反复出现的llm-deepseek: no api key for provider route "deepseek-official"; store deeps，暴露了一个普遍痛点：开发者在配置 LLM 工具时，最容易栽在“认证凭据管理”这个看似简单、实则暗坑无数的环节。agent-reach提供了一套系统性解法，但需要你理解其设计逻辑才能用好。

4.1 为什么no api key错误如此顽固？根源在 Provider 的初始化时机

当你看到no api key for provider route "deepseek-official"，第一反应可能是“我明明设置了DEEPSEEK_API_KEY环境变量！”。但agent-reach的报错逻辑是：它只在 Provider 实例化时检查一次 API Key，且只检查环境变量，不读取配置文件或命令行参数。

这意味着，如果你的.agent-reach.yaml长这样：

providers: - name: deepseek-official type: api base_url: https://api.deepseek.com/v1 api_key: "sk-xxxxxx" # ❌ 危险！硬编码密钥 model: deepseek-chat

agent-reach会忽略api_key字段，因为它严格遵循“密钥不落地”原则——api_key字段只在文档中作为占位符存在，实际运行时必须通过环境变量注入。正确的做法是：

providers: - name: deepseek-official type: api base_url: https://api.deepseek.com/v1 # 删除 api_key 字段，改为声明环境变量名 api_key_env: DEEPSEEK_API_KEY # ✅ 正确 model: deepseek-chat

然后在运行前设置：

export DEEPSEEK_API_KEY="sk-xxxxxx" agent-reach run --workflow my-task

为什么这样设计？因为硬编码密钥会导致三个灾难性后果：

• Git 泄露风险：.agent-reach.yaml很可能被提交到公共仓库，密钥瞬间暴露；
• 多环境冲突：开发环境用测试 Key，生产环境用正式 Key，硬编码无法区分；
• 轮换困难：Key 过期时，你得改 N 个配置文件，而不是只改一个环境变量。

agent-reach的解决方案是：所有敏感凭据，必须通过环境变量注入；所有 Provider 配置，只声明“我要读哪个环境变量”。这符合 12-Factor App 的第三条原则（Store config in the environment）。

4.2store deeps是什么？——理解agent-reach的上下文存储机制

热词中的store deeps让很多人困惑。它其实指agent-reach的context_store功能：一个轻量级的、基于 SQLite 的本地上下文缓存系统。当你在 workflow 中使用cache_ttl，或者在 CLI 中使用--cache参数时，agent-reach会把请求的输入、输出、时间戳存入~/.agent-reach/cache.db。

例如，fetch-issue-list步骤的缓存记录长这样：

这个设计解决了两个关键问题：

• 网络稳定性：即使 GitHub API 临时不可用，只要缓存未过期，workflow 仍能返回上次成功的结果；
• 成本控制：对付费 API（如 DeepSeek），缓存能显著降低调用次数，尤其适合定时任务（如每小时同步一次 Issue）。

但要注意：context_store默认只缓存GET请求（如获取 Issue 列表），不缓存POST请求（如模型推理），因为后者输入高度动态，缓存价值低。如果你想强制缓存模型输出（比如固定 prompt 的模板生成），可以在 step 中显式设置cache_ttl：

- name: generate-template provider: ollama-phi3 prompt: "Generate a standard PR description template..." cache_ttl: 86400 # 缓存 24 小时 output_key: pr_template

4.3400 this model's maximum context length is 1048576 tokens：如何让agent-reach主动应对超长上下文

这个错误是 LLM 开发者的噩梦。它不是agent-reach的 bug，而是模型服务端的硬性限制。但agent-reach提供了两种主动防御机制：

方案一：Provider 层预检（推荐）
在providers/deepseek_official.py的infer()方法开头，加入 token 估算逻辑：

def _estimate_tokens(self, messages: List[Dict]) -> int: # 简单估算：英文字符数 / 4，中文字符数 / 2 total_chars = sum(len(m["content"]) for m in messages) # 假设 60% 是中文 chinese_chars = total_chars * 0.6 english_chars = total_chars * 0.4 return int(chinese_chars / 2 + english_chars / 4) + len(messages) * 10 # +10 为 role 和标点开销 def infer(self, messages: List[Dict], **kwargs) -> Dict: estimated = self._estimate_tokens(messages) if estimated > self.max_context_length * 0.95: # 预留 5% 余量 raise ContextLengthExceededError( f"Estimated {estimated} tokens exceeds {self.max_context_length} limit. " f"Please truncate input or use a larger-context model." ) # ... rest of inference

这样，错误会在请求发出前就抛出，附带清晰的修复建议，而不是等 API 返回一个晦涩的 400。

方案二：Workflow 层降级（兜底）
在 workflow 中为关键步骤设置fallback_to：

- name: deepseek-analysis provider: deepseek-official prompt: "{{ long_input }}" fallback_to: ollama-qwen2 # 当 deepseek 失败时，自动切到本地 qwen2 output_key: analysis

agent-reach会捕获ContextLengthExceededError或HTTP 400，然后自动用ollama-qwen2重试。这要求你的 fallback provider 必须支持相同输入格式——这也是为什么agent-reach强制所有 Provider 实现统一的infer()接口。

实战避坑：我曾在一个客户项目中遇到deepseek-official突然将max_context_length从 32768 调整为 16384，导致所有长文档分析任务失败。当时我们没有用方案一（预检），而是紧急上线了方案二（fallback），用ollama-qwen2:7b作为降级模型，保证了业务连续性。第二天再补上预检逻辑。这印证了一个原则：生产环境的 AI 工作流，必须同时具备“事前预防”和“事后兜底”双保险。

5. 进阶实战：将agent-reach集成到 GitHub Actions，实现全自动周报生成

前面的例子展示了单机 CLI 的能力。现在，我们把它升级为一个真正的自动化服务：每周一上午 9 点，自动抓取公司所有重要仓库的 Issue、PR、Discussions，用 DeepSeek-R1 生成中文周报，并推送到企业微信。这个案例覆盖了 CI/CD 集成、多仓库聚合、以及跨平台通知，是agent-reach生产落地的典型范式。

5.1 构建可复用的跨仓库 Workflow

核心挑战是：不同仓库的 Issue 结构不同，但周报模板要统一。agent-reach的解决方案是“模板继承”：

创建workflows/base-weekly.yaml（基础模板）：

name: base-weekly description: "Base weekly report template for any repo" steps: - name: fetch-data provider: github-public endpoint: "/repos/{{ repo_owner }}/{{ repo_name }}/{{ resource_type }}" method: GET params: state: "{{ state }}" since: "{{ since }}" per_page: 100 output_key: raw_items - name: enrich-items provider: ollama-phi3 prompt: | You are a repo analyst. For each item in the list below, extract: - title (short, <20 chars) - type (issue/pr/discussion) - severity (CRITICAL/HIGH/MEDIUM/LOW) - one-sentence summary Return as JSON list. Items: {{ steps.fetch-data.output.raw_items | tojson }} input: "{{ steps.fetch-data.output.raw_items }}" output_key: enriched_items output: "{{ steps.enrich-items.output.enriched_items }}"

然后为每个仓库创建特化 workflow，如workflows/frontend-weekly.yaml：

# 继承 base-weekly，只覆盖必要参数 name: frontend-weekly description: "Weekly report for frontend repository" extends: base-weekly # ✅ agent-reach 支持 YAML 继承 args: repo_owner: "mycompany" repo_name: "frontend-app" resource_type: "issues" state: "all" # 时间范围：上周一到本周日 since: "{{ (now() - timedelta(days=7)).strftime('%Y-%m-%dT%H:%M:%SZ') }}"

agent-reach的extends机制，让你能像写 CSS 一样复用逻辑，避免在 10 个仓库配置中复制粘贴相同的enrich-itemsprompt。

5.2 GitHub Actions 配置：安全、可靠、可观测

创建.github/workflows/weekly-report.yml：

name: Weekly Report Generator on: schedule: # 每周一上午 9 点（UTC） - cron: '0 9 * * 1' workflow_dispatch: # 手动触发，方便调试 inputs: repo: description: 'Repository to generate report for' required: false default: 'frontend-app' jobs: generate-report: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.11' - name: Install agent-reach run: pip install agent-reach - name: Configure GitHub Token # 使用 GitHub Actions 自带