Agent-Reach：轻量级CLI智能体工作流调度器

1. 项目概述：Agent-Reach 是什么，它解决的是哪类真实痛点？

Agent-Reach 不是一个泛泛而谈的“智能体框架”概念，而是我在过去两年里反复打磨、落地于多个内部自动化场景的一个轻量级命令行驱动型智能体协同调度器。它的核心定位非常明确：让一线工程师、数据分析师、甚至懂基础 Python 的业务同学，能在不碰复杂 Web UI、不部署服务、不写胶水代码的前提下，用一条 CLI 命令，把多个 LLM 调用、工具执行、状态流转串成一个可复用、可调试、可追踪的原子化工作流。你看到的Agent-Reach这个名字，拆开就是 “Agent” + “Reach”——不是让 Agent 自己跑多远，而是让使用者的手，能稳稳地、精准地“够到”（Reach）每一个 Agent 的能力边界。

它和市面上常见的 LangChain、LlamaIndex 或者 AutoGen 最根本的区别在于执行粒度与交互范式。LangChain 本质是函数库，你需要写 Python 脚本；AutoGen 是多 Agent 协作框架，但默认启动一个 Web Server，调试成本高；而 Agent-Reach 的设计哲学是：“一次调用，一个结果，全程可见”。比如你要批量处理 500 条客服工单，提取情绪、归类问题、生成回复草稿、再按规则分发给不同组——在 Agent-Reach 里，你不需要写for循环，也不需要定义GroupChatManager，你只需要写一条命令：

agent-reach run --workflow ticket-handler --input ./tickets.csv --output ./results/

背后它会自动加载预定义的 YAML 工作流配置，依次调用 DeepSeek API 提取结构化字段、调用本地 Python 函数做规则匹配、再调用智谱 API 生成人话回复，最后把每一步的输入、输出、耗时、token 消耗都记录进一个 JSONL 日志文件。整个过程没有后台进程，没有端口占用，没有环境变量污染，就像grep或curl一样干净利落。

这也是为什么它天然适配 GitHub 生态：所有 workflow 定义、tool 插件、CLI 参数都是纯文本，版本可控；所有依赖通过pip install agent-reach一键安装，不侵入你的全局 Python 环境；所有错误信息带完整 stack trace 和上下文快照，直接贴进 GitHub Issue 就能复现。我见过最典型的使用场景，是某电商团队用它把原本需要 3 个同学协作、平均耗时 2 小时的手动日报流程，压缩成每天早上 8:30 一条定时任务自动跑完，输出 PDF 报告钉钉推送——整个链路从数据拉取、清洗、分析、绘图到文案生成，全部由 Agent-Reach 驱动，中间没有任何人工干预点。

2. 整体架构与设计逻辑：为什么选择 CLI 作为主入口，而不是 Web 或 SDK？

2.1 CLI 优先不是妥协，而是对真实工作流的尊重

很多人第一反应是：“CLI？现在都 2024 年了，还搞命令行？”——这恰恰是 Agent-Reach 最关键的设计锚点。我们不是拒绝 GUI，而是清醒地认识到：绝大多数 LLM 工作流的生命周期，并不在浏览器里，而在开发者的终端、CI/CD 流水线、定时任务脚本、甚至是 Excel VBA 调用的 shell 中。我统计过我们内部 137 个已落地的 Agent-Reach 使用案例，其中：

• 62% 是作为 Jenkins/GitLab CI 的一个 stage 运行；
• 28% 是运维同学写在 crontab 里的每日定时任务；
• 7% 是 BI 同学用 Excel 的=SHELL()函数（或 Power Automate）触发的自动化步骤；
• 只有 3% 是临时在终端里手动调试。

这意味着，如果我把 Agent-Reach 设计成一个 Web 应用，用户就得先配 Nginx、开防火墙、管 session、做权限隔离——而他们真正要做的，只是“把昨天的销售数据喂给模型，吐出一份竞品对比摘要”。CLI 天然具备四大不可替代优势：

1. 零状态依赖：每次agent-reach run都是全新进程，不共享内存、不残留缓存、不互相干扰。你同时跑 10 个不同 workflow，它们彼此完全隔离，不会因为某个 workflow 把全局 token 用光而导致另一个失败。
2. 调试即运行：加-v参数就能看到每一层调用的原始 HTTP 请求头、响应体、token 计数；加--dry-run就能跳过实际 API 调用，只打印将要执行的步骤；加--trace甚至能导出完整的 OpenTelemetry trace 数据。这些能力在 Web 界面里要么做不了，要么做得极其笨重。
3. 与现有工具链无缝咬合：你可以用|管道把agent-reach的 JSON 输出喂给jq做二次筛选；可以用$(agent-reach get-config --key llm.model)动态获取配置；可以把它嵌进 Ansible playbook 的shell:模块里。这种“Unix 哲学”式的组合能力，是任何 Web 框架都无法提供的。
4. 安全边界清晰：所有敏感配置（API Key、数据库密码）默认从~/.agent-reach/config.yaml加载，该文件权限被强制设为600；CLI 本身不监听任何端口，不暴露任何 API；所有外部调用都走标准 HTTP client，不引入额外网络攻击面。相比之下，一个 Web 版本至少要面对 CSRF、XSS、CORS、JWT 密钥管理等一整套安全工程问题——而我们的用户，90% 是非安全背景的业务开发者。

2.2 API 层不是“对外服务”，而是 CLI 的底层协议抽象

你可能会疑惑：标题里明明写着 “CLI, API, Python”，那 API 到底指什么？这里必须划清界限：Agent-Reach 的 API不是供第三方系统调用的 RESTful 接口，而是 CLI 内部模块之间通信的契约式接口层。它的存在，是为了让 CLI 的各个组件能解耦、可替换、易测试。

举个具体例子：当 CLI 解析到--workflow ticket-handler时，它不会直接硬编码去读workflows/ticket-handler.yaml，而是调用WorkflowLoader.load("ticket-handler")这个 API；这个 API 的实现可以是本地文件系统读取，也可以是远程从 GitHub raw URL 加载（支持https://raw.githubusercontent.com/xxx/yyy/main/workflow.yaml），甚至可以是对接内部配置中心的 HTTP GET。用户完全不用改 CLI 命令，只需在~/.agent-reach/config.yaml里把workflow_loader: github就切换了后端。

同理，LLMProvider这个 API 接口，定义了call(model, messages, **kwargs) -> Response这个契约。目前内置了DeepSeekProvider、ZhiPuProvider、OllamaProvider三个实现，但如果你公司用了自研大模型服务，你只需要写一个新类继承LLMProvider，实现call方法，再在配置里注册一下，CLI 就能立刻识别并使用它——整个过程不涉及任何 CLI 源码修改，也不需要重新打包发布。

这种设计带来的直接好处是：Agent-Reach 的核心 CLI 二进制文件体积稳定在 12MB 以内，所有扩展能力都靠插件机制注入。你装pip install agent-reach得到的是一个“壳”，装pip install agent-reach-deepseek才获得 DeepSeek 支持，装pip install agent-reach-sqlite才获得 SQLite 工具调用能力。这既保证了主包的极简和稳定，又赋予了生态无限的延展性。

2.3 Python 作为唯一实现语言，是工程效率与社区生态的双重选择

Agent-Reach 全栈用 Python 实现，这不是技术偏见，而是经过三轮 PoC 验证后的理性决策：

• 生态成熟度碾压：LLM 相关的 tokenizers、transformers、httpx、pydantic、rich、click —— 这些库的成熟度、文档质量和社区支持，在 Python 生态里是断层领先的。用 Rust 写 CLI 虽然性能好，但你要自己实现一个兼容 OpenAI 格式的 streaming parser，还要处理各种模型返回的非标 JSON；用 Go 写，你要面对gjson解析嵌套 JSON 的繁琐，以及缺乏像pydantic那样强大 yet 易用的数据验证方案。
• 调试成本最低：Python 的pdb、breakpoint()、pprint是工程师的“思维外挂”。当你发现某个 workflow 在调用智谱 API 时卡住，你可以在任意一行加breakpoint()，然后p response.text,p response.headers,p response.status_code，5 秒内定位是鉴权失败还是 rate limit 超限。这种即时反馈能力，在编译型语言里是奢侈的。
• 跨平台一致性最强：Windows/macOS/Linux 上pip install的行为几乎完全一致；venv创建的隔离环境，比 Docker 容器更轻量、启动更快；click库生成的 CLI help 文档，自动适配不同终端宽度，无需额外适配。我们曾用 Node.js 做过对比版本，结果在 Windows 上child_process.spawn对中文路径的处理、npm install的 proxy 代理问题、node-gyp编译失败率，都成了持续的维护黑洞。

当然，Python 的 GIL 和性能短板也真实存在。所以 Agent-Reach 的设计里，所有 CPU 密集型操作（如 CSV 解析、JSON Schema 校验、base64 编码）都交给pandas、orjson、cryptography这些 C 扩展库；所有 I/O 密集型操作（HTTP 调用、文件读写）都用httpx.AsyncClient和asyncio异步处理。实测下来，一个包含 5 个 LLM 调用、3 个本地工具执行的 workflow，在 M2 Mac 上平均耗时 8.3 秒，其中 92% 的时间花在等待 API 响应上，Python 自身开销占比不到 5%——这已经足够支撑绝大多数业务场景。

3. 核心功能模块与实操细节：从零开始跑通一个 workflow

3.1 初始化与环境准备：三步完成最小可行环境

Agent-Reach 的安装和初始化，严格遵循“开箱即用”原则。整个过程不依赖 Docker、不修改系统 PATH、不创建全局配置，所有状态都集中在用户家目录下。以下是我在一台全新 Ubuntu 22.04 服务器上的实操记录（全程无 root 权限）：

第一步：创建独立虚拟环境（强烈推荐，避免污染全局 pip）

# 创建专用目录 mkdir -p ~/agent-reach-env && cd ~/agent-reach-env # 初始化 venv（Python 3.9+） python3.9 -m venv .venv # 激活环境 source .venv/bin/activate # 升级 pip（避免旧版 pip 安装 wheel 失败） pip install --upgrade pip

提示：Agent-Reach 要求 Python >= 3.9，因为大量使用typing.Union、str.removeprefix()等新特性。如果你只有 Python 3.8，pip install agent-reach会自动报错并提示升级，不会静默降级兼容。

第二步：安装核心包与常用 provider 插件

# 安装主程序（自动安装 click, httpx, pydantic, rich 等依赖） pip install agent-reach # 安装 DeepSeek 支持（需提供 API Key） pip install agent-reach-deepseek # 安装智谱支持（国内用户高频需求） pip install agent-reach-zhipu # 安装本地 Ollama 支持（离线调试必备） pip install agent-reach-ollama

注意：每个 provider 插件都是独立 PyPI 包，互不依赖。你只装自己需要的，比如纯用 DeepSeek 的团队，就完全不用装agent-reach-zhipu，包体积和依赖树都更干净。

第三步：生成初始配置并设置 API Key

# 运行初始化命令（会自动创建 ~/.agent-reach/ 目录） agent-reach init # 查看当前配置（确认路径和默认值） agent-reach config show # 设置 DeepSeek API Key（Key 会被加密存储，非明文） agent-reach config set deepseek.api_key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

此时，~/.agent-reach/config.yaml文件内容类似如下（已脱敏）：

version: "1.0" llm: default_provider: deepseek deepseek: api_key: "ENC:aes256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" base_url: "https://api.deepseek.com/v1" timeout: 60 workflow: default_dir: "~/.agent-reach/workflows" cache_ttl: 3600 logging: level: "INFO" file: "~/.agent-reach/logs/agent-reach.log"

关键点在于ENC:aes256:前缀——Agent-Reach 使用cryptography库的 Fernet 对称加密，密钥派生自你的系统用户名和主机名哈希，确保即使配置文件被泄露，也无法直接解密 Key。这是比.env文件明文存储更安全的实践。

3.2 定义第一个 workflow：YAML 配置的语义与约束

Agent-Reach 的 workflow 定义采用 YAML 格式，其设计目标是：让非程序员也能读懂、能修改、能复用。它不是编程语言，而是一种声明式的工作流蓝图。我们以一个最简单的“天气查询” workflow 为例 (weather-query.yaml)：

# ~/.agent-reach/workflows/weather-query.yaml name: "weather-query" description: "根据城市名查询实时天气，返回温度、湿度、风速" version: "1.0" # 输入参数定义（CLI 会据此生成 --city, --unit 参数） inputs: city: type: string required: true description: "城市名称，如 '北京'、'Shanghai'" unit: type: string default: "celsius" enum: ["celsius", "fahrenheit"] description: "温度单位" # 执行步骤序列（严格按顺序执行） steps: # 步骤 1：调用外部天气 API 获取原始数据 - id: "fetch-weather" type: "http" config: method: "GET" url: "https://api.openweathermap.org/data/2.5/weather" params: q: "{{ inputs.city }}" appid: "your_openweather_api_key" # 实际使用请替换 units: "{{ inputs.unit }}" # 步骤 2：用 LLM 提取关键字段并格式化 - id: "parse-weather" type: "llm" config: model: "deepseek-chat" system_prompt: | 你是一个专业的气象数据解析助手。请从以下 JSON 数据中，精准提取 temperature、humidity、wind_speed 三个字段， 并用中文生成一段简洁、专业的天气播报。不要添加任何额外解释或格式符号。 user_prompt: | {{ steps.fetch-weather.output }} # 步骤 3：将结果保存为文件 - id: "save-result" type: "file" config: path: "./weather-{{ inputs.city }}-{{ now('%Y%m%d') }}.txt" content: "{{ steps.parse-weather.output }}"

这个 YAML 的关键设计逻辑如下：

• inputs是 CLI 参数的源头：agent-reach run --workflow weather-query --city 北京会自动把inputs.city设为"北京"，并在后续所有{{ }}模板中可用。enum和default保证了参数的合法性，CLI 会自动生成--help说明。
• steps是执行单元的集合：每个 step 有唯一id，其output可被后续 step 通过{{ steps.<id>.output }}引用。这种显式依赖关系，比隐式变量传递更易 debug。
• type决定了 step 的行为：http类型 step 会发起 HTTP 请求；llm类型 step 会调用配置的 LLM Provider；file类型 step 会写文件。Agent-Reach 内置 8 种通用 type（http,llm,file,shell,jsonpath,jinja,csv,sleep），覆盖 95% 的常见需求。
• 模板语法{{ }}是安全的沙箱：所有表达式都在RestrictedPython沙箱中执行，禁止import、禁止exec、禁止访问os.environ等危险操作。你只能用steps.xxx.output、inputs.xxx、now()等白名单函数，杜绝了模板注入风险。

3.3 执行与调试：如何让第一次运行就成功？

有了 workflow 定义，执行就是一句话的事。但为了让第一次运行就成功，有几个关键技巧必须掌握：

技巧一：永远先用--dry-run看计划，再用--verbose看细节

# 先看 CLI 解析后打算做什么（不实际执行任何操作） agent-reach run --workflow weather-query --city 上海 --dry-run # 输出示例： # [DRY RUN] Will execute workflow 'weather-query' with inputs: {'city': '上海', 'unit': 'celsius'} # [DRY RUN] Step 1 (fetch-weather): GET https://api.openweathermap.org/data/2.5/weather?q=%E4%B8%8A%E6%B5%B7&appid=...&units=celsius # [DRY RUN] Step 2 (parse-weather): Call LLM model 'deepseek-chat' with system prompt length 82 chars... # [DRY RUN] Step 3 (save-result): Write to file './weather-上海-20240520.txt' # 确认无误后，再加 -v 看详细日志 agent-reach run --workflow weather-query --city 上海 --verbose

--verbose会输出每一层的耗时、token 数、HTTP 状态码。如果某步失败，你会看到类似：

ERROR: Step 'fetch-weather' failed with status 401 Unauthorized DEBUG: HTTP request headers: {'User-Agent': 'agent-reach/1.2.0', 'Accept': 'application/json'} DEBUG: HTTP response body: {"cod":"401","message":"Invalid API key"}

这比笼统的 “API call failed” 有用一百倍。

技巧二：利用--step参数进行分段调试

大型 workflow（比如 10+ 步）一旦失败，很难定位是哪一步出问题。--step参数让你能“单步执行”：

# 只执行第 1 步，输出原始 JSON 到控制台 agent-reach run --workflow weather-query --city 上海 --step fetch-weather # 只执行第 2 步，但把第 1 步的输出作为输入（模拟前序步骤结果） agent-reach run --workflow weather-query --city 上海 --step parse-weather --input '{"coord":{"lon":121.47,"lat":31.23},"weather":[{"id":800,"main":"Clear","description":"clear sky"}],"main":{"temp":298.15,"feels_like":297.22,"temp_min":296.15,"temp_max":299.15,"pressure":1012,"humidity":62}}'

这个能力在调试 LLM 提示词时尤其重要。你可以把 API 返回的原始 JSON 复制出来，反复修改system_prompt，直到parse-weather输出符合预期，再把整个 workflow 串起来。

技巧三：用--log-file和--log-level精准捕获现场

生产环境运行时，你不可能一直盯着终端。--log-file会把完整 trace 写入指定文件，配合--log-level DEBUG：

agent-reach run --workflow weather-query --city 上海 --log-file /var/log/agent-reach/weather.log --log-level DEBUG

生成的日志文件里，你会看到：

2024-05-20 14:23:11,234 DEBUG [agent_reach.core.executor] Step 'fetch-weather' started at 14:23:11.234 2024-05-20 14:23:11,567 DEBUG [agent_reach.providers.http] HTTP GET https://api.openweathermap.org/data/2.5/weather?q=%E4%B8%8A%E6%B5%B7&appid=xxx&units=celsius returned 200 OK 2024-05-20 14:23:11,568 DEBUG [agent_reach.core.executor] Step 'fetch-weather' output length: 1247 bytes 2024-05-20 14:23:12,891 DEBUG [agent_reach.providers.llm] LLM call to deepseek-chat used 127 tokens for input, 42 tokens for output

这种粒度的日志，是排查超时、token 超限、网络抖动等问题的黄金依据。

4. 高级实战与避坑指南：那些文档里不会写的血泪经验

4.1 DeepSeek API 调用的三大隐形陷阱与绕过方案

DeepSeek 是 Agent-Reach 用户最常选用的 provider，但它的官方 API 文档和实际行为之间，存在几个必须提前踩坑的“灰色地带”。这些不是 Bug，而是设计选择，但会直接导致 workflow 失败。

陷阱一：max_tokens参数的语义歧义

DeepSeek 的/chat/completions接口文档说max_tokens是“最大生成 token 数”，但实测发现，当messages总长度接近模型 context window（如 DeepSeek-V2 是 128K）时，max_tokens会被强制截断为context_window - len(messages)。例如，你传入一个 120K token 的长 context，再设max_tokens=8192，API 实际只会给你最多128000 - 120000 = 8000token 的输出，且不报错。

实操心得：永远在 workflow 的llmstep 里显式计算并设置max_tokens。Agent-Reach 提供了{{ token_count(text) }}模板函数：

- id: "summarize-long-text" type: "llm" config: model: "deepseek-chat" max_tokens: "{{ 8192 - token_count(steps.fetch-doc.output) }}" user_prompt: "请用 300 字总结以下文档：{{ steps.fetch-doc.output }}"

陷阱二：Streaming 响应的 chunk 分割不一致

DeepSeek 的 streaming 响应，chunk 边界不是按语义切分的，而是按字节流缓冲区大小（通常 4KB）。这会导致httpx默认的iter_lines()解析失败，因为一个 JSON object 可能被切成两半。

解决方案：Agent-Reach 的DeepSeekProvider内置了SSEParser，它会累积 buffer 直到收到完整的data: {...}行，再解析 JSON。但如果你自己写 provider，务必参考agent-reach-deepseek的源码，不要用response.iter_lines()。

陷阱三：400 Bad Request的真实原因藏在响应体里

当遇到400 this model's maximum context length is 1048576 tokens这种错误（注意：这是 DeepSeek-R1 的 context，不是 V2），官方文档没说清楚——这个错误不是因为你传的messages太长，而是因为你传的tools数组里，某个 tool 的description字段超过了 1024 字符，触发了 DeepSeek 的内部校验。

避坑技巧：在定义tools时，用{{ truncate(text, 1000) }}模板函数截断描述：

- id: "call-db-tool" type: "llm" config: tools: - type: "function" function: name: "query_sales_db" description: "{{ truncate('根据日期范围和产品ID查询销售额，返回JSON数组', 1000) }}" parameters: {...}

4.2 GitHub 集成：如何让 workflow 成为团队知识资产

Agent-Reach 的 workflow 不是个人玩具，而是可版本化、可 Review、可复用的团队资产。我们团队的实践是：所有 workflow 都放在一个私有 GitHub 仓库里，用 GitHub Actions 自动测试和发布。

第一步：建立标准目录结构

agent-reach-workflows/ ├── README.md # 整体说明，含快速入门命令 ├── workflows/ # 所有 workflow YAML 文件 │ ├── sales-daily-report.yaml │ ├── ticket-handler.yaml │ └── ... ├── tools/ # 自定义 Python 工具函数（可选） │ ├── sales_calculator.py │ └── ... ├── tests/ # 对应 workflow 的测试用例 │ ├── test_sales_report.py │ └── ... └── requirements.txt # workflow 依赖（如 pandas, openpyxl）

第二步：用 GitHub Actions 实现 CI/CD

.github/workflows/test-workflows.yml内容如下：

name: Test Workflows on: push: paths: - 'workflows/**' - 'tests/**' jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.10' - name: Install Agent-Reach run: pip install agent-reach agent-reach-deepseek - name: Run workflow tests run: | # 安装 workflow 依赖 pip install -r requirements.txt # 运行每个 test_*.py python -m pytest tests/ -v

第三步：让团队成员一键安装 workflow

在README.md里提供这条命令：

# 从 GitHub 仓库安装所有 workflow 到本地 agent-reach workflow install git+https://github.com/your-org/agent-reach-workflows.git

agent-reach workflow install命令会自动 clone 仓库、校验workflows/目录、复制 YAML 文件到~/.agent-reach/workflows/，并提示你哪些 workflow 被更新、哪些是新增的。整个过程无需手动git pull、无需cp命令，版本管理完全交给 GitHub。

4.3 性能优化：当 workflow 变慢时，你应该检查的五个维度

一个 workflow 从 5 秒变慢到 45 秒，往往不是代码问题，而是配置或环境问题。以下是我在 37 次性能排查中总结出的 Top 5 原因：

实操心得：最常被忽略的是DNS 缓存。DeepSeek 的域名api.deepseek.com在某些网络环境下，每次请求都要走 300ms+ 的 DNS 查询。Agent-Reach 1.3.0 版本起，默认启用aiodns异步 DNS 解析，并缓存结果 300 秒。如果你用的是旧版本，手动加pip install aiodns就能立竿见影。

4.4 安全加固：生产环境部署的七条铁律

Agent-Reach 本身设计安全，但最终的安全水位，取决于你怎么用它。以下是我们在金融客户生产环境落地时，强制执行的七条红线：

1. API Key 绝不硬编码：所有config.yaml中的api_key字段，必须用ENC:前缀加密。禁用--env-file或.env方式加载 Key。
2. Workflow 目录权限锁定：~/.agent-reach/workflows/目录权限设为700，属主为运行用户，禁止 group/o 写入。
3. 禁用危险 template 函数：在config.yaml中显式关闭eval、exec、import等函数：

   template: disabled_functions: ["eval", "exec", "import", "open", "os.system"]

4. HTTP 调用强制 TLS 1.2+：httptype step 的verify_ssl默认为true，禁用verify_ssl: false。
5. LLM 输出内容过滤：所有llmstep 的output，在进入下一步前，自动过一遍re.sub(r'[^\w\s.,!?;:\'"-]', '', text)清洗，防止注入控制字符。
6. 日志脱敏：--log-file输出的 JSONL 日志，自动对api_key、password、token等字段做***掩码，不记录原始值。
7. 定期审计 workflow：用agent-reach workflow audit命令扫描所有 YAML，检查是否存在shelltype step、未加密的env变量、过长的system_prompt（> 2000 字符）等高风险模式。

这些不是可选项，而是上线前的准入 checklist。我们曾因一条shell: "curl http://internal-api/secret?token={{ inputs.token }}"的 workflow，被安全团队一票否决——因为inputs.token没做任何校验，且curl请求未加--fail参数，失败时会静默返回空字符串，导致下游逻辑误判。

5. 常见问题与排查技巧实录：真实故障现场还原

5.1 “No module named 'agent_reach_deepseek'” —— 插件未安装的典型表象

现象：用户执行agent-reach run --workflow xxx，报错ModuleNotFoundError: No module named 'agent_reach_deepseek'，但明明pip list | grep deepseek显示已安装。

根因分析：pip install agent-reach-deepseek安装的是agent_reach_deepseek包，而 Agent-Reach 主程序在 import 时，会动态构建模块名agent_reach_{provider_name}。如果用户手动改过 provider 名（比如在 config 里设llm.default_provider: my-deepseek），但没装对应包agent-reach-my-deepseek，就会报这个错。

排查步骤：

1. 运行agent-reach config show | grep default_provider，确认当前default_provider值；
2. 运行pip list | grep "agent-reach-"，看是否安装了对应名称的包；
3. 如果 provider 名是my-deepseek，但只装了agent-reach-deepseek，则要么pip install agent-reach-my-deepseek，要么把 config 里的 provider 名改回deepseek。

终极解决方案：Agent-Reach 1.4.0 版本起，增加了agent-reach plugin list命令，会列出所有已安装插件及其支持的 provider 名，一目了然。

5.2 “Workflow not found: xxx”