1. 项目概述Agent-Reach 是什么它解决的不是“调用 API”而是“调度智能体”的根本问题Agent-Reach 不是一个 API 封装库也不是一个 CLI 工具包装器更不是另一个“免费大模型接口聚合站”。如果你在 Reddit 或小红书上看到有人发帖问“deepseek api如何调用”“codex cli安装”“超稳-q绑在线查询api”然后顺手搜到 Agent-Reach那大概率你会失望——因为它压根不提供 API Key、不托管模型、不转发请求、不中转流量。它干的是更底层、更系统性的一件事把分散在 CLI、HTTP API、本地进程、甚至浏览器扩展里的异构智能体Agent统一纳管、按需编排、上下文协同、状态可溯。我第一次接触这个概念是在帮一家做海外社媒舆情分析的团队重构数据采集链路。他们当时有 7 个独立脚本一个用yt-dlp抓 YouTube 视频元数据一个用praw调 Reddit API 拉热帖评论一个跑 ComfyUI 的本地 Stable Diffusion pipeline 做图像特征提取一个用zcode cli处理多模态文本摘要还有一个手动维护的gitlab cli任务同步 GitHub Issue 到内部看板……这些工具彼此割裂参数硬编码失败后无法重试输出格式五花八门调试靠print()和日志 grep。他们真正需要的不是“又一个能调 deepseek 的命令行”而是“让这 7 个工具像乐高一样插在一起自动判断什么时候该用哪个、传什么参数、怎么兜底、失败了从哪继续”。Agent-Reach 正是为此而生。它的核心抽象非常朴素每个可执行单元无论它是 Python 脚本、Shell 命令、HTTP 端点、还是浏览器扩展注入的 JS 函数都被建模为一个 Agent每个 Agent 暴露一组明确的输入 Schema 和输出 SchemaAgent-Reach 负责解析用户意图自然语言或结构化指令匹配可用 Agent组装执行图注入上下文捕获输出并将结果结构化返回。它不碰模型权重不存 token不代理请求——它只做“智能体路由层”Intelligent Agent Router Layer就像 TCP/IP 协议栈里的 IP 层负责寻址、分片、重组、错误通知但不管应用层协议是 HTTP 还是 WebSocket。所以当你看到热搜词里混着cli、api、YouTube、Reddit这不是巧合而是真实场景的映射Agent-Reach 的设计哲学就是“不造轮子只连轮子”。它默认支持的 Agent 类型包括CLI Agent封装任意命令行工具如yt-dlp --get-title https://youtu.be/xxx自动解析 stdout/stderr 为 JSONHTTP Agent对接任意 RESTful API如 Reddit 的/r/learnprogramming/hot.json自动处理 auth、rate limit、paginationProcess Agent启动并管理长期运行的本地服务如 ComfyUI 的/prompt接口带健康检查和优雅退出Extension Agent通过 Chrome/Edge 扩展 API 注入沙箱环境执行 JS如小红书页面 DOM 解析、Facebook 评论情感分析规避 CORS 限制LLM Agent作为“协调者”而非“执行者”调用 DeepSeek、Qwen、Claude 等模型生成下一步 Agent 调用计划Plan-and-Execute 模式但绝不硬编码 provider route。提示Agent-Reach 本身不提供“免费大模型 API”它也不解决llm-deepseek: no api key for provider route deepseek-official这类报错。那个错误说明你的 LLM Agent 配置里写了deepseek-official这个 provider 名但本地没配对应密钥或路由规则。Agent-Reach 只负责把“调用 deepseek”这个动作翻译成你配置好的实际执行路径比如走你自建的 Ollama 服务、或你公司内网的 DeepSeek-R1 部署实例它不替你申请 Key也不帮你绕过厂商风控。适合谁用三类人最受益数据工程师厌倦了写一堆胶水代码粘合不同数据源想用声明式 YAML 定义整个 ETL 流程AI 应用开发者正在构建 RAG、Agent 工作流但被“怎么把 PDF 解析、网页抓取、模型推理串成一条线”卡住技术型产品经理需要快速验证一个跨平台功能比如“自动汇总 Reddit 热帖 YouTube 评论 小红书笔记生成周报”不想从零搭服务只想组合现有工具。它不是银弹但能让你少写 70% 的调度胶水代码。接下来我会从设计逻辑、核心机制、实操细节到踩坑记录一层层拆开给你看。2. 架构设计与核心思路为什么放弃“统一 API 网关”选择“Agent 原生编排”Agent-Reach 的架构选择源于对当前 AI 工具生态的三个深刻观察2.1 观察一API 不是万能的“CLI 本地执行”在特定场景不可替代很多高频需求天然适合 CLIYouTube 下载yt-dlp支持 1000 网站解析逻辑复杂HTTP API 很难覆盖所有 edge caseComfyUI 图像生成本地 GPU 推理延迟低、成本低、隐私好远胜于调用远程 API浏览器自动化小红书、Facebook 的反爬策略不断升级Headless Chrome Puppeteer 的鲁棒性远高于模拟 HTTP 请求。如果强行把所有能力都塞进 REST API会带来三大问题性能损耗一次 YouTube 标题提取要经过 Nginx → Flask → yt-dlp subprocess → JSON 序列化 → HTTP 响应比直接yt-dlp --get-title慢 3~5 倍部署负担为每个 CLI 工具单独写 Web Service意味着要维护 N 个 Docker 容器、N 套监控告警、N 份日志配置权限失控yt-dlp需要访问网络ffmpeg需要读写文件系统puppeteer需要 GUI 权限——把这些能力暴露成 API安全边界极难划定。Agent-Reach 的解法是承认 CLI 的正当性把它变成一等公民。它不把 CLI 当“黑盒命令”而是用pydantic定义其输入输出 Schema用subprocess.run封装执行用json.loads(stdout)结构化结果。例如一个 YouTube Agent 的定义长这样name: youtube-title type: cli command: yt-dlp --get-title --no-warnings --quiet {url} input_schema: url: string output_schema: title: string error: string? # 可选字段便于错误分类Agent-Reach 启动时扫描所有.agent.yaml文件自动注册这个 Agent。调用时它会校验url是否符合 URL 格式拼接命令执行解析 JSON 输出。整个过程CLI 工具完全 unaware它只当自己被 shell 调用。2.2 观察二“HTTP API”不是同质化的不同服务的 auth、rate limit、pagination 机制天差地别Reddit API 用 OAuth2 Bearer TokenYouTube Data API 用 API KeyGitLab CI API 用 Personal Access Token而某些内部服务用 JWT Cookie。更麻烦的是分页Reddit 用after参数 next字段YouTube 用pageTokenGitLab 用pageper_page。如果写一个通用 API Client要么写一堆 if-else要么引入复杂配置 DSL。Agent-Reach 选择“每个 HTTP Agent 自带适配器”。它不提供http_client.get()这样的通用方法而是要求你在 Agent 定义里明确写出request和response的转换逻辑name: reddit-hot-posts type: http url: https://www.reddit.com/r/{subreddit}/hot.json method: GET headers: User-Agent: Agent-Reach/1.0 params: limit: 10 after: {{ context.last_after }} # 支持 Jinja2 模板引用上下文 input_schema: subreddit: string output_schema: posts: - id: string title: string score: integer next_after: string关键点在于params.after的{{ context.last_after }}。Agent-Reach 在执行前会把上一次调用的output.next_after注入context下次调用自动带上。Pagination 不再是 SDK 里的 magic 方法而是显式定义在 Agent 行为里。这牺牲了一点便利性换来的是完全可控的重试、断点续传、状态追踪——当你拉取 1000 条 Reddit 帖子失败在第 800 条时Agent-Reach 能精确知道last_after是什么下次从那里继续而不是重头再来。2.3 观察三“浏览器扩展”不是补充而是突破 CSP 和反爬的关键入口很多平台小红书、Facebook、Instagram的公开 API 功能残缺、额度苛刻、或根本不开放。但它们的前端页面却包含最全的数据。puppeteer或playwright可以解决但需要长期维护无头浏览器集群。Agent-Reach 的破局点是把浏览器扩展变成轻量级 Agent 运行时。它提供一个最小化 Chrome 扩展模板只含content_script.js和manifest.json。开发者只需在content_script.js里写 DOM 解析逻辑Agent-Reach 通过chrome.runtime.sendMessage与之通信。例如一个小红书笔记 Agent// content_script.js const notes Array.from(document.querySelectorAll(.note-item)).map(el ({ id: el.dataset.id, title: el.querySelector(.title)?.innerText, likes: parseInt(el.querySelector(.likes)?.innerText.replace(/[^0-9]/g, )) || 0 })); chrome.runtime.sendMessage({ type: result, data: notes });Agent-Reach 的 CLI 启动时会自动加载这个扩展并监听chrome.runtime.onMessage。调用时它发送一个消息触发脚本执行等待响应。整个过程无需启动完整浏览器扩展运行在用户已登录的 Chrome 实例里天然绕过登录态和 CSP 限制。这是curl或requests永远做不到的。综上Agent-Reach 的核心设计决策是拒绝“统一抽象”拥抱“原生能力”。它不试图把 CLI、HTTP、Browser 统一成一种接口而是为每种能力设计最贴合其特性的接入方式。这种“不优雅”的设计恰恰带来了最强的工程鲁棒性——你能用yt-dlp就用yt-dlp能用puppeteer就用puppeteerAgent-Reach 只负责把它们串起来不越俎代庖。3. 核心机制详解Schema 驱动、Context 传递、Plan-and-Execute 协同Agent-Reach 的运转依赖三个相互咬合的核心机制Schema 驱动的类型安全、Context 传递的状态管理、以及 Plan-and-Execute 的 LLM 协同模式。它们共同构成了“智能体可编排”的基础。3.1 Schema 驱动为什么必须用 Pydantic 定义输入输出很多类似项目用dict或jsonschema做参数校验Agent-Reach 坚持用 Pydantic v2原因有三第一类型推导即文档。当你定义一个 Agent 的input_schemafrom pydantic import BaseModel, HttpUrl, Field class YouTubeInput(BaseModel): url: HttpUrl Field(..., descriptionValid YouTube video URL) format: str Field(mp4, pattern^(mp4|webm|mkv)$) timeout: int Field(30, ge5, le300, descriptionDownload timeout in seconds)Agent-Reach 自动生成 CLI help 文档Usage: agent-reach run youtube-download --url URL [--format FORMAT] [--timeout TIMEOUT] Options: --url TEXT Valid YouTube video URL [required] --format TEXT Format to download (default: mp4) [choices: mp4, webm, mkv] --timeout INTEGER Download timeout in seconds (default: 30) [range: 5-300]更重要的是它能在运行时做深度校验HttpUrl不仅检查是否含https://还尝试 DNS 解析pattern不仅正则匹配还捕获错误位置ge/le在参数超出范围时给出精准提示“--timeout must be 5”。这比argparse的typeint强太多。第二Schema 是 Agent 间契约。假设你有一个youtube-transcriptAgent输出是class TranscriptOutput(BaseModel): text: str segments: - start: float end: float text: str而下游的summarize-textAgent输入必须匹配class SummarizeInput(BaseModel): text: str max_length: int 300Agent-Reach 在编排时会静态检查TranscriptOutput.text是否能赋值给SummarizeInput.text。如果summarize-text需要text是 Markdown 格式而youtube-transcript输出纯文本它会报错“Type mismatch: TranscriptOutput.text (str) → SummarizeInput.text (str with markdown constraint)”。这种编译期检查避免了运行时才发现“上游输出不能喂给下游”的尴尬。第三Schema 支持动态生成。LLM Agent 的输出常是 JSON但结构不确定。Agent-Reach 提供DynamicSchema工具# LLM 返回的 JSON 示例 { next_step: reddit-search, params: {query: LLM deployment best practices, sort: relevance} } # Agent-Reach 动态生成 Schema 并校验 schema DynamicSchema.from_example(llm_output) validated schema.validate(llm_output) # 返回 Pydantic model 实例这使得 Plan-and-Execute 流程中LLM 生成的调用计划能被严格约束在预设的 Agent 能力范围内防止它胡乱调用不存在的 Agent 或传非法参数。3.2 Context 传递不只是“传参”而是构建可追溯的执行图谱Context 在 Agent-Reach 中不是简单的 dict而是一个带版本、可快照、支持回滚的执行上下文对象。它的设计目标是让一次复杂任务如“分析本周 Reddit 热帖并生成 PPT”的所有中间状态都能被完整还原。Context 包含三部分Static Context任务启动时注入的全局变量如user_id: u123,workspace: /home/u123/projectsDynamic ContextAgent 执行中动态写入的键值对如last_reddit_after: t3_abc123Execution Trace一个链表式日志记录每次 Agent 调用的时间戳、Agent 名、输入参数脱敏、输出摘要、耗时、状态success/error、错误堆栈如有。关键特性是Context Snapshot。当某个 Agent 执行成功Agent-Reach 会自动保存当前 Context 快照。如果后续 Agent 失败你可以agent-reach resume --snapshot-id 20240520-142301从第 3 步快照恢复跳过前两步agent-reach debug --step 5加载第 5 步的 Context进入交互式调试 shell手动修改context[transcript]后重试agent-reach export-trace --format json trace.json导出完整执行链用于审计或复现。这解决了传统脚本最头疼的问题失败后你不知道是哪一步错了也不知道上一步输出是什么。在 Reddit 数据采集任务中我曾遇到praw因 rate limit 返回 429但日志只显示 “praw call failed”。有了 Context Trace我能直接看到[Step 4] reddit-hot-posts (2024-05-20 14:22:15) Input: {subreddit: learnprogramming, limit: 10} Output: {error: 429 Too Many Requests, retry_after: 60} Duration: 1.2s于是立刻知道要 sleep 60 秒再重试而不是盲目重启整个流程。3.3 Plan-and-Execute 协同LLM 不是执行者而是“智能调度员”Agent-Reach 对 LLM 的定位非常清晰它不处理原始数据只负责“决策”。整个流程分两阶段Phase 1: Plan规划用户输入自然语言指令如“帮我找最近一周 Reddit 上关于 ‘DeepSeek API’ 的热门讨论提取关键观点再用 YouTube 视频评论验证这些观点最后生成一份对比报告。”Agent-Reach 启动一个 LLM Agent如 Qwen2-72B给它一套 System PromptYou are an Agent Orchestrator. Your job is to break down user requests into sequential calls to available Agents. Available Agents: [youtube-search, reddit-search, youtube-comments, reddit-comments, text-summarize, report-gen] Output ONLY valid JSON with keys: plan: [{agent: agent-name, params: {...}}, ...]LLM 输出{ plan: [ {agent: reddit-search, params: {query: DeepSeek API, time_filter: week}}, {agent: youtube-search, params: {query: DeepSeek API tutorial}}, {agent: reddit-comments, params: {post_id: {{ step0.output.posts[0].id }}}}, {agent: youtube-comments, params: {video_id: {{ step1.output.videos[0].id }}}}, {agent: text-summarize, params: {text: {{ step2.output.comments | join }}\n{{ step3.output.comments | join }}}}, {agent: report-gen, params: {summary: {{ step4.output.summary }}}} ] }注意{{ step0.output... }}这种模板语法——它表示“引用第 0 步的输出”。Agent-Reach 的 Planner 会静态解析这个 plan检查所有stepX是否存在、output字段是否可访问确保 plan 语法正确。Phase 2: Execute执行Agent-Reach 按 plan 顺序执行Step 0: 调用reddit-search结果存入context.step0;Step 1: 调用youtube-search结果存入context.step1;Step 2: 渲染{{ step0.output.posts[0].id }}得到真实 post_id调用reddit-comments;……如果 Step 2 失败如 Reddit API 404Agent-Reach 不会终止而是记录错误到 Trace尝试 fallback查context.step0.output.posts[1].id调用第二个帖子如果 fallback 也失败才标记整个 plan 失败并返回{error: Failed to fetch comments from top Reddit post, fallback_tried: true}。这种分离让 LLM 专注“思考”Agent-Reach 专注“执行”各司其职。LLM 不用关心praw怎么初始化Agent-Reach 也不用理解“DeepSeek API”是什么技术——它们通过 Schema 和 Context 无缝协作。4. 实操全流程从零搭建一个“Reddit YouTube 舆情分析”Agent 工作流现在我们动手实现一个真实场景自动监控 Reddit 和 YouTube 上关于 “Agent-Reach” 的讨论提取高频关键词生成简明日报。这个工作流会用到 CLI、HTTP、LLM 三种 Agent覆盖 Agent-Reach 的核心能力。4.1 环境准备与 Agent-Reach 安装Agent-Reach 是 Python 项目推荐用pipx隔离安装避免污染全局环境# 安装 pipx如未安装 python3 -m pip install --user pipx python3 -m pipx ensurepath # 安装 Agent-Reach最新稳定版 pipx install agent-reach # 验证安装 agent-reach --version # 输出agent-reach 1.2.0注意不要用pip install agent-reach全局安装。因为 Agent-Reach 会调用yt-dlp、praw等工具它们的依赖可能冲突。pipx为每个 CLI 工具创建独立虚拟环境互不干扰。接着安装依赖工具yt-dlppipx install yt-dlp比旧版 youtube-dl 更活跃支持更多网站prawpipx install prawReddit API 客户端Ollama本地 LLM从 https://ollama.com/download 下载安装然后拉取模型ollama pull qwen2:7bChrome 浏览器确保已安装用于后续浏览器扩展 Agent可选。4.2 定义第一个 AgentReddit 搜索HTTP Agent创建目录~/agents/新建文件reddit-search.agent.yamlname: reddit-search type: http url: https://www.reddit.com/r/{subreddit}/search.json method: GET headers: User-Agent: Agent-Reach/1.0 (by u/your_reddit_username) params: q: {query} restrict_sr: true sort: {sort} t: {time_filter} limit: 25 input_schema: subreddit: string all query: string sort: string relevance time_filter: string week output_schema: posts: - id: string title: string score: integer num_comments: integer permalink: string after: string?关键点解析headers.User-Agent必须设置否则 Reddit 会 403。格式为Agent-Reach/1.0 (by u/your_username)这是 Reddit API 的强制要求params.q是搜索关键词{query}会被 Agent-Reach 替换output_schema.posts定义了返回的帖子列表结构after字段可选用于分页subreddit: all设为默认值意味着不指定 subreddit 时搜索全站。测试这个 Agentagent-reach run reddit-search --query Agent-Reach --subreddit learnprogramming如果返回 JSON 且posts非空说明配置成功。如果报错401 Unauthorized说明User-Agent格式不对如果429说明请求太频繁加--time-filter day降低频率。4.3 定义第二个 AgentYouTube 搜索CLI Agent新建文件youtube-search.agent.yamlname: youtube-search type: cli command: yt-dlp --dump-json --no-playlist --max-downloads 10 --match-filter duration 3600 --skip-download ytsearch:{query} | jq -r .[] | select(.id and .title) | {id: .id, title: .title, duration: .duration} input_schema: query: string max_results: integer 10 output_schema: videos: - id: string title: string duration: integer这里用了yt-dlp的--dump-json输出原始信息再用jq提取关键字段。--match-filter duration 3600过滤掉超过 1 小时的视频避免处理长直播。--skip-download确保只获取元数据不下载视频。实操心得yt-dlp的 JSON 输出有时包含非 UTF-8 字符如 emojijq可能报错。解决方案是在command前加LC_ALLCcommand: LC_ALLC yt-dlp --dump-json ... | jq -r ...这个坑我踩过三次每次都是中文标题里有 emoji 导致 pipeline 中断。测试agent-reach run youtube-search --query Agent-Reach tutorial4.4 定义第三个 Agent文本摘要LLM Agent新建文件text-summarize.agent.yamlname: text-summarize type: llm provider: ollama model: qwen2:7b system_prompt: | 你是一个专业的技术文档摘要助手。请用中文用不超过 100 字总结以下文本的核心观点。不要添加任何解释或额外信息。 input_schema: text: string max_length: integer 100 output_schema: summary: stringAgent-Reach 内置 Ollama 支持它会自动调用http://localhost:11434/api/chat。确保 Ollama 正在运行ollama serve且qwen2:7b已拉取。测试agent-reach run text-summarize --text Agent-Reach 是一个智能体编排框架它连接 CLI、API、浏览器扩展等异构工具...4.5 编排工作流编写 workflow.yaml创建workflow.yamlname: reddit-youtube-monitor description: 监控 Reddit 和 YouTube 上关于 Agent-Reach 的讨论生成日报 plan: - agent: reddit-search params: query: Agent-Reach subreddit: all time_filter: week - agent: youtube-search params: query: Agent-Reach - agent: text-summarize params: text: {{ step0.output.posts | map(attributetitle) | join(\n) }}\n{{ step1.output.videos | map(attributetitle) | join(\n) }}这个 plan 很简单先搜 Reddit再搜 YouTube最后把所有标题拼起来交给 LLM 摘要。运行工作流agent-reach run-workflow --workflow workflow.yaml首次运行可能较慢Ollama 加载模型成功后输出{ summary: 社区讨论聚焦于 Agent-Reach 的 CLI 本地执行优势和跨平台 Agent 编排能力普遍认为其比传统 API 网关更适合复杂数据采集场景。 }4.6 进阶添加错误处理与重试逻辑上面的工作流没有容错。现实中Reddit 搜索可能因 rate limit 失败YouTube 搜索可能因网络超时失败。我们在workflow.yaml中加入重试plan: - agent: reddit-search params: query: Agent-Reach subreddit: all time_filter: week retry: max_attempts: 3 backoff: exponential conditions: - status_code 429 - error contains rate limit - agent: youtube-search params: query: Agent-Reach retry: max_attempts: 2 backoff: fixed delay: 5 conditions: - exit_code ! 0 - output contains ERRORretry.conditions支持表达式status_code、exit_code、error、output都是可用变量。backoff: exponential表示重试间隔按 1s, 2s, 4s 指数增长fixed则固定 5 秒。实操心得重试不是越多越好。我曾设max_attempts: 10结果一次 Reddit 429 错误导致任务卡住 10 分钟。后来改成max_attempts: 3conditions精准匹配既保证鲁棒性又避免无谓等待。5. 常见问题与排查技巧实录那些文档里不会写的实战经验在真实项目中Agent-Reach 的问题往往不在代码而在环境、权限、网络这些“软性”环节。以下是我在 12 个客户现场踩过的坑整理成速查表。5.1 CLI Agent 执行失败Permission Denied / Command Not Found现象agent-reach run youtube-search报错Command yt-dlp not found或Permission denied。排查步骤在终端直接运行yt-dlp --version确认命令全局可用如果用pipx安装检查pipx list是否显示yt-dlp关键点Agent-Reach 的 CLI Agent 是在子进程里执行的它继承的是Agent-Reach 进程的 PATH不是你 shell 的 PATH。解决方案在youtube-search.agent.yaml的command前显式指定路径command: /home/yourname/.local/bin/yt-dlp --dump-json ...或者在启动 Agent-Reach 前用export PATH$PATH:/home/yourname/.local/bin。现象yt-dlp报错Permission denied但ls -l $(which yt-dlp)显示权限正常。真相某些 Linux 发行版如 Ubuntu 22.04默认启用kernel.unprivileged_userns_clone0禁止非 root 用户创建 user namespace而yt-dlp的某些 downloader 依赖此特性。解决临时启用需 sudosudo sysctl kernel.unprivileged_userns_clone1或永久生效echo kernel.unprivileged_userns_clone1 | sudo tee -a /etc/sysctl.conf。5.2 HTTP Agent 403 ForbiddenUser-Agent 不是摆设现象reddit-search总是返回 403即使User-Agent看起来正确。深挖原因Reddit 的 403 不只看User-Agent还检查请求头是否含Accept: application/jsonReferer是否为空某些 CDN 会拦截IP 是否在短时间被标记为爬虫。解决方案在 Agent 定义中补全 headersheaders: User-Agent: Agent-Reach/1.0 (by u/your_reddit_username) Accept: application/json Referer: https://www.reddit.com/实操心得我曾用curl -H User-Agent: ... https://www.reddit.com/r/all/search.json?qtest测试成功但 Agent-Reach 失败。最后发现是curl默认带Accept: */*而 Reddit 要求application/json。这个细节Reddit 官方文档只在一行小字里提过。5.3 LLM Agent 调用超时Ollama 响应慢的 3 个优化点现象text-summarize执行超过 60 秒Agent-Reach 报TimeoutError。优化方案模型量化qwen2:7b默认是 FP16显存占用大。用ollama run qwen2:7b-q4_k_m4-bit 量化速度提升 2.3 倍精度损失可忽略调整 Ollama 参数编辑~/.ollama/config.json增加{ options: { num_ctx: 4096, num_predict: 256, temperature: 0.1 } }num_ctx控制上下文长度num_predict限制生成 token 数避免 LLM “写个不停”Agent-Reach 端超时设置在text-summarize.agent.yaml中加timeout: 120覆盖默认 60 秒。5.4 Context 丢失为什么{{ step0.output }}是 null现象Workflow 中引用{{ step0.output }}但报错KeyError: step0。根本原因Agent-Reach 的 Context 是按执行顺序写入的。如果 Step 0 失败返回 errorstep0键就不会被创建。正确写法永远用{{ step0.output.posts | default([]) }}default([])提供安全 fallback。高级技巧用selectattr过滤{{ step0.output.posts | selectattr(score, , 10) | list }}这行模板会安全地过滤出 score 10 的帖子如果step0.output.posts不存在selectattr返回空 generatorlist转成[]不会报错。5.5 浏览器扩展 Agent 不触发Content Script 加载时机问题现象Chrome 扩展已安装但