Agent-Reach：面向AI工程化的CLI优先大模型调用工具

1. 项目概述：Agent-Reach 是什么，它解决的到底是什么问题？

Agent-Reach 这个名字一出现，我就立刻联想到当前大模型应用落地中最棘手的一类现实困境——不是模型不够强，而是“用不起来”。你手上有开源的 Llama3、Qwen2、DeepSeek-V2，本地跑得飞快，但想把它嵌进一个自动化流程里，比如每天自动抓取竞品价格、生成分析报告并邮件发送；或者想让销售同事在 Slack 里直接输入“查一下华东区上季度TOP5客户复购率”，后台就调用数据库+BI接口+LLM做推理再返回结构化结果——这时候你会发现，光有模型权重和推理代码远远不够。缺的是那个“能被命令行一键触发、能被其他服务稳定调用、能快速验证逻辑、能无缝集成进CI/CD流水线”的轻量级胶水层。Agent-Reach 正是为这个缺口而生的。

它不是一个新模型，也不是一个大而全的平台，而是一个面向开发者与运维人员的 CLI-first 工具链。核心定位非常清晰：把 LLM 的能力，封装成像curl或git那样可预测、可脚本化、可管道化的终端命令。你不需要写 Flask 接口、不用配 Nginx 反向代理、不用设计 RESTful 路由，只需要一条命令，就能完成从输入提示词（prompt）、选择模型（local 或远程 API）、注入上下文（如 JSON 数据、文件内容）、到输出结构化结果（JSON/YAML/纯文本）的完整链路。比如agent-reach --model qwen2:7b --prompt "总结以下销售数据" --input sales_q3.json --output-format json，执行完直接得到一个带 key-value 的 JSON 对象，后续脚本可以直接jq '.summary'提取内容。

这背后解决的，是工程化落地中的三个硬伤：第一是环境隔离难——不同项目依赖不同版本的 transformers、vLLM、Ollama，全局 pip install 容易冲突；第二是调试成本高——每次改 prompt 都要重启服务、重发 HTTP 请求、看日志找错，不如终端里--verbose一行命令看清 token 流转；第三是集成门槛高——运维同学不会写 Python，但会写 Bash；测试工程师熟悉 Postman 却不熟悉 FastAPI 文档。Agent-Reach 把所有复杂性收在二进制里，对外只暴露最朴素的 POSIX 命令语义。它不是替代 LangChain 或 LlamaIndex，而是给它们提供一个“可交付的最小运行单元”——你可以把它看作 LLM 应用的make工具，或者大模型时代的ffmpeg：不教你怎么造轮子，但让你能立刻把轮子装上车跑起来。

我去年帮一家电商公司做智能客服知识库更新自动化时，就踩过所有这些坑。他们用的是自研的 RAG 流程，本地部署了 Qwen2-7B，但每次更新 FAQ 文档都要手动跑 Python 脚本、检查 embedding 向量维度、确认 ChromaDB collection 名称拼写、再等 20 分钟索引重建。后来我们用 Agent-Reach 重构后，整个流程变成一条 Jenkins pipeline 命令：agent-reach rag-index --collection faq_v2 --docs ./new_faq/ --embedder bge-m3 --chunk-size 512。失败时直接返回非零退出码，Jenkins 自动告警；成功后自动触发下游 QA 测试任务。整个过程从 45 分钟缩短到 3 分钟，而且运维同事自己就能修改文档路径参数，不再需要开发介入。这就是 CLI-first 设计带来的真实生产力跃迁——它不炫技，但极其务实。

2. 整体架构与设计思路：为什么选择 CLI 作为主入口？背后的权衡逻辑

2.1 CLI 优先并非技术倒退，而是对交付场景的精准匹配

很多人看到 “CLI” 第一反应是“过时”“原始”，尤其在 Web UI 和低代码平台盛行的今天。但 Agent-Reach 的 CLI 设计，恰恰是对当前 AI 工程化真实场景的深度反刍。我们拆开来看三个关键决策点：

第一，交付即安装。Python 生态里最头疼的问题之一，就是“pip install xxx 后报错 ModuleNotFoundError”。Agent-Reach 采用 PyOxidizer 或Nuitka 打包成单文件二进制（Linux/macOS/Windows 均支持），用户下载agent-reach-v0.8.3-linux-x86_64这个 42MB 的文件，chmod +x后直接运行，所有依赖（包括 torch、transformers、ollama-py）全部静态链接进二进制。这意味着你不需要用户装 Python、不用管 conda 环境、甚至不用联网——内网隔离环境也能秒级部署。我实测过，在一台只有 OpenSSH 和 wget 的 CentOS 7 服务器上，从下载到执行agent-reach --help全程 8.3 秒。对比 Flask 服务，光是 pipenv install 就可能卡在 gcc 编译 numpy 上半小时。这种“零依赖交付”能力，在金融、政务等强合规场景里，是压倒性的优势。

第二，调试即所见。LLM 应用最大的调试黑洞，是 prompt 工程中的“黑盒感”——你不知道模型到底看到了什么 context，tokenization 后实际输入多长，stop token 是否被正确识别。Agent-Reach 的--debug模式会逐层打印：原始 prompt 字符串 → 经过 jinja2 渲染后的模板 → tokenizer.encode() 后的 token ID 列表（含长度）→ 实际发送给模型的 payload（含 system message、user message 分割）→ 模型返回的 raw response → 解析后的 structured output。这种透明度，让 prompt 工程师能像调试 C 语言指针一样，精准定位是模板变量没传进去，还是 tokenizer 对 emoji 处理异常，或是模型返回了意外的 XML 标签。而 Web UI 通常只展示最终结果，中间链路全被封装掉。

第三，集成即标准。所有现代运维体系（Ansible、Terraform、Jenkins、GitHub Actions）都原生支持 shell 命令执行。Agent-Reach 的 exit code 严格遵循 POSIX 规范：0 表示成功，1 表示用户错误（如参数缺失），2 表示模型调用失败（API timeout 或 4xx 错误），3 表示解析失败（JSON schema 不匹配）。这意味着你可以在 GitHub Actions 的 workflow 文件里这样写：

- name: Validate LLM output run: | result=$(agent-reach --model deepseek-coder:33b --prompt "Check if this PR description follows our template" --input pr_body.txt --output-format json) if [ $? -ne 0 ]; then echo "LLM validation failed" exit 1 fi echo "$result" | jq -e '.valid == true' > /dev/null

这种能力，远比对接一个需要 OAuth 认证、有 rate limit、返回格式不稳定的 HTTP API 来得可靠。CLI 是 Unix 哲学的终极体现——“每个程序只做一件事，并做好”。

2.2 架构分层：如何平衡灵活性与开箱即用？

Agent-Reach 的代码结构非常克制，只有四个核心模块，却覆盖了 90% 的生产需求：

• cli/：命令行解析层，基于click构建，支持子命令嵌套（agent-reach rag、agent-reach llm、agent-reach eval），参数校验严格（如--max-tokens必须是正整数，--temperature限定在 0.0–2.0 区间）。
• providers/：模型适配器层，目前支持 Ollama（本地）、OpenAI（官方 API）、ZhiPu（智谱）、DashScope（阿里云）、Minimax（自研）五种 provider。每个 provider 实现统一的generate()接口，内部处理认证头、endpoint 拼接、response 解析（如 Minimax 返回的choices[0].message.contentvs OpenAI 的choices[0].message.content）。新增 provider 只需继承BaseProvider并实现 3 个方法，平均 200 行代码。
• templates/：提示词模板引擎，使用 Jinja2，预置了 12 个常用场景模板（summarize.j2、sql_generate.j2、json_schema_validate.j2等）。用户可通过--template-path指定自定义模板，支持变量注入（{{ input_text }}、{{ context }}）和条件判断（{% if format == 'csv' %}）。
• utils/：工具函数层，包含load_json_or_yaml()（自动识别文件格式）、parse_output_format()（将--output-format json映射到json.dumps()）、get_model_info()（从 Ollama registry 或 API 获取模型元数据）。

这种分层不是为了炫技，而是为了解决一个根本矛盾：用户既要“开箱即用”，又要“深度定制”。比如某银行客户要求所有 prompt 必须经过内部合规审查，禁止使用任何外部 API。这时他们只需：

1. 下载agent-reach二进制；
2. mkdir -p ~/.agent-reach/templates && cp internal_summarize.j2 ~/.agent-reach/templates/；
3. 运行agent-reach --model qwen2:14b --template internal_summarize.j2 --input report.pdf。

整个过程不碰代码、不改配置、不启服务，完全符合其安全审计流程。而另一家游戏公司需要对接自研的 MoE 模型，他们 fork 仓库，在providers/下新增my_moe_provider.py，编译后替换二进制，同样无需改动 CLI 层。这种“核心稳定、插件可换”的设计，让 Agent-Reach 既能作为通用工具分发，又能成为企业私有化 AI 基础设施的一部分。

2.3 为什么放弃 Web UI？一个被低估的性能真相

Agent-Reach 官方明确声明：“不提供 Web UI，也不计划提供”。这不是傲慢，而是基于一个被多数人忽略的性能事实：HTTP 协议栈的开销，在 LLM 推理场景下是不可忽视的常数项。

我们做过一组对照实验：同一台机器（RTX 4090 + 128GB RAM），运行 Qwen2-7B-Int4 模型，输入 512 tokens 的 prompt，生成 256 tokens 的 response。

• 直接调用transformers.pipeline()：平均延迟 1.8s（GPU warmup 后）
• 通过 FastAPI 封装成/v1/chat/completions接口，curl 调用：平均延迟 2.7s（+0.9s）
• 通过 Agent-Reach CLI 调用本地 Ollama：平均延迟 2.1s（+0.3s）

多出来的 0.3s，主要消耗在：FastAPI 的 request parsing（Pydantic model validation）、ASGI server 的 event loop 调度、HTTP header 构建与解析、JSON serialization/deserialization。而 CLI 方式，Agent-Reach 直接调用ollama.generate()的 Python SDK，走的是本地进程间调用（IPC），没有网络协议栈参与。在批量处理场景下（如每小时处理 1000 份合同摘要），这 0.3s 的差异会放大为 5 分钟的总耗时差——足够让一个 CI 任务从“准实时”降级为“准离线”。

更关键的是，Web UI 带来的不仅是延迟，还有运维复杂度。你需要管理 Uvicorn 进程、配置 Gunicorn worker 数、处理 WebSocket 连接泄漏、监控/healthendpoint、升级 TLS 证书……而 CLI 工具，只要二进制文件存在，它就“永远在线”。我们有个客户把 Agent-Reach 集成进他们的电子病历系统，医生在 Windows 桌面双击一个.bat文件就能启动病情摘要生成，整个流程不经过任何网络请求，完全满足医疗数据不出院的要求。这种“无服务架构”（Serviceless Architecture）的价值，在特定领域里，远超一个漂亮的前端界面。

3. 核心功能详解与实操要点：从零开始跑通第一个命令

3.1 安装与环境准备：三分钟完成全平台部署

Agent-Reach 的安装设计极度简化，目标是“让一个刚学会ls和cd的实习生也能完成”。以下是各平台实操步骤，附带我踩过的坑和避坑技巧：

Linux/macOS（推荐方式：直接下载二进制）

# 1. 下载最新版（以 v0.8.3 为例） curl -L https://github.com/shihabal3amri/agent-reach/releases/download/v0.8.3/agent-reach-v0.8.3-linux-x86_64 -o agent-reach # 2. 添加执行权限 chmod +x agent-reach # 3. 移动到 PATH 目录（推荐 /usr/local/bin，避免 sudo） sudo mv agent-reach /usr/local/bin/ # 4. 验证安装 agent-reach --version # 输出：agent-reach 0.8.3

提示：不要用pip install agent-reach！官方已明确弃用 PyPI 包，因为 pip 安装无法打包 torch 等大依赖，会导致运行时报ImportError: libtorch.so not found。二进制方式才是唯一支持的安装途径。

Windows（PowerShell 一键脚本）

# 在 PowerShell 中执行（需管理员权限） Invoke-WebRequest -Uri "https://github.com/shihabal3amri/agent-reach/releases/download/v0.8.3/agent-reach-v0.8.3-windows-amd64.exe" -OutFile "$env:ProgramFiles\agent-reach\agent-reach.exe" # 添加到系统 PATH（需重启终端） [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:ProgramFiles\agent-reach", "Machine") # 验证 agent-reach --help

注意：Windows 用户务必关闭 Windows Defender 的“基于信誉的保护”，否则首次运行会被误报为“潜在不需要的程序”并拦截。这是 PyOxidizer 打包的常见误报，添加信任即可。

Docker（生产环境推荐）

FROM ubuntu:22.04 RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/* # 下载并安装 RUN curl -L https://github.com/shihabal3amri/agent-reach/releases/download/v0.8.3/agent-reach-v0.8.3-linux-x86_64 -o /usr/local/bin/agent-reach && \ chmod +x /usr/local/bin/agent-reach # 设置默认工作目录 WORKDIR /workspace CMD ["agent-reach", "--help"]

构建命令：docker build -t agent-reach .
运行命令：docker run --rm -v $(pwd):/workspace agent-reach --model ollama/qwen2:7b --prompt "Hello"

3.2 第一个命令：理解参数组合的底层逻辑

让我们从最简单的命令开始，逐步拆解每个参数的实际作用：

agent-reach --model qwen2:7b --prompt "你好，请用中文自我介绍"

• --model qwen2:7b：这不是一个字符串，而是一个模型路由标识符。Agent-Reach 内部会根据前缀判断 provider：

  • ollama/xxx→ 调用本地 Ollama（需提前ollama pull qwen2:7b）
  • openai/xxx→ 调用 OpenAI API（需设置OPENAI_API_KEY环境变量）
  • zhipu/xxx→ 调用智谱 API（需ZHIPU_API_KEY）
  • qwen2:7b（无前缀）→ 默认使用 Ollama，等价于ollama/qwen2:7b

• --prompt "你好，请用中文自我介绍"：这里的 prompt 会被原样传递给模型，不经过任何预处理。Agent-Reach 不内置 system message，完全交由用户控制。如果你想强制模型用中文回答，必须写在 prompt 里，比如"请用中文回答，不要使用英文。你好，请用中文自我介绍"。

执行后，你会看到类似输出：

Qwen2 是阿里巴巴研发的开源大语言模型，具有强大的语言理解和生成能力...

现在，我们加一个关键参数--output-format json：

agent-reach --model qwen2:7b --prompt "列出三个中国一线城市，用 JSON 格式返回，key 为 cities" --output-format json

输出变为：

{"cities": ["北京", "上海", "广州"]}

这里发生了什么？Agent-Reach 在收到模型原始输出后，会启动一个轻量级 JSON 解析器，尝试提取符合{"cities": [...]}结构的内容。如果模型返回了乱码或格式错误，它会返回非零退出码并打印错误详情。这个机制让 CLI 工具具备了“结构化输出保证”能力，是自动化脚本可靠性的基石。

3.3 进阶实操：文件输入、模板渲染与多步管道

真实业务中，prompt 很少是纯文本，更多来自文件、API 或数据库。Agent-Reach 提供了三类输入方式：

1. 文件输入（--input）

# 创建测试文件 echo '{"product": "iPhone 15", "price": 5999, "specs": ["A17芯片", "4800万像素"]}' > product.json # 用 JSON 文件内容作为 prompt 上下文 agent-reach --model qwen2:7b \ --prompt "根据以下产品信息生成一段电商详情页文案，要求突出卖点，不超过100字：" \ --input product.json \ --output-format text

Agent-Reach 会自动识别product.json是 JSON 格式，将其解析为 Python dict，然后在 prompt 渲染时注入{{ input }}变量。等效于 prompt 变成：

根据以下产品信息生成一段电商详情页文案，要求突出卖点，不超过100字：{"product": "iPhone 15", "price": 5999, "specs": ["A17芯片", "4800万像素"]}

2. 模板渲染（--template）预置模板summarize.j2内容如下：

请为以下文本生成一段简洁摘要，要求： - 用中文书写 - 不超过 150 字 - 保留所有关键数据（数字、人名、地名） 原文：{{ input_text }}

使用方式：

echo "2023年全球新能源汽车销量达1000万辆，其中中国占比60%，比亚迪销量186万辆位居第一。" > report.txt agent-reach --model qwen2:7b \ --template summarize.j2 \ --input report.txt \ --output-format text

输出：

2023年全球新能源汽车销量达1000万辆，中国占60%。比亚迪以186万辆销量居首。

3. Unix 管道（Pipeline）这才是 CLI 的灵魂。我们可以把 Agent-Reach 当作一个“智能过滤器”：

# 从 CSV 文件提取所有产品名称，逐行送入 LLM 生成卖点 cat products.csv | cut -d',' -f1 | while read name; do echo "产品：$name，生成一句吸引眼球的广告语" done | agent-reach --model qwen2:7b --output-format text

或者更优雅的写法（利用--batch参数）：

# 将多行 prompt 批量处理 printf "iPhone 15\nSamsung S24\nPixel 8" | agent-reach --model qwen2:7b --batch --output-format json

输出为一个 JSON 数组，每个元素对应一行输入的响应。

3.4 模型配置与性能调优：参数背后的物理意义

Agent-Reach 的模型参数不是随意设计的，每个都对应着 GPU 推理的底层资源约束。理解它们，才能避免 OOM（内存溢出）和长延迟：

实测案例：在一台 RTX 3060（12GB）上运行qwen2:7b，--max-tokens 2048时显存占用 11.2GB，几乎打满；将--num-gpu-layers从 -1 改为 24 后，显存降至 8.7GB，且推理速度仅慢 12%，但稳定性大幅提升。

4. 实操全流程演示：构建一个自动化的周报生成器

4.1 需求分析：为什么周报是 Agent-Reach 的典型场景？

周报看似简单，却是企业里最典型的“高重复、低价值、强规则”任务。销售要填 CRM 数据，研发要汇总 Git 提交，运营要统计流量指标——每个人都在 Excel 里复制粘贴，再用 Word 写一段“本周工作顺利，下周继续努力”的套话。而 Agent-Reach 能把它变成一个./generate_weekly_report.sh脚本，输入是几个 CSV/JSON 文件，输出是格式统一的 Markdown 周报。

我们的目标：每周一上午 9 点，自动从公司 BI 系统导出sales_data.csv、从 GitLab 导出commits.json、从 Jira 导出tickets.json，然后生成一份包含“销售亮点”、“研发进展”、“风险预警”三部分的周报，最后邮件发送给管理层。

4.2 数据准备与清洗：让原始数据符合 Agent-Reach 输入规范

首先，确保数据源输出为 Agent-Reach 可读格式：

sales_data.csv（BI 系统导出）：

region,product,sales_amount,week_over_week 华东,iPhone,1250000,0.12 华南,MacBook,890000,-0.05 华北,iPad,670000,0.08

commits.json（GitLab API 获取）：

[ {"author": "张三", "message": "feat: add user profile page", "date": "2024-06-10"}, {"author": "李四", "message": "fix: login timeout bug", "date": "2024-06-11"} ]

tickets.json（Jira API 获取）：

[ {"key": "PROJ-123", "summary": "支付接口超时", "priority": "High", "status": "In Progress"}, {"key": "PROJ-456", "summary": "用户头像上传失败", "priority": "Medium", "status": "To Do"} ]

注意：Agent-Reach 要求 JSON 文件必须是 UTF-8 编码，且不能有 BOM 头。Windows 记事本保存的 JSON 常带 BOM，会导致解析失败。推荐用 VS Code 或iconv -f utf-8 -t utf-8-bom//ignore input.json > output.json清理。

4.3 模板编写：用 Jinja2 控制输出结构

创建weekly_report.j2模板：

# {{ week_start }} - {{ week_end }} 周报 ## 销售亮点 {% for row in sales_data %} - {{ row.region }}区{{ row.product }}销售额{{ row.sales_amount | int | format_currency }}元，环比增长{{ (row.week_over_week * 100) | round(1) }}% {% endfor %} ## 研发进展 共提交 {{ commits | length }} 次代码： {% for commit in commits %} - {{ commit.author }}：{{ commit.message }}（{{ commit.date }}） {% endfor %} ## 风险预警 {% for ticket in tickets if ticket.priority == 'High' %} - {{ ticket.key }}：{{ ticket.summary }}（{{ ticket.status }}） {% endfor %} {% if tickets | selectattr('priority', 'equalto', 'High') | list | length == 0 %} - 本周无高优先级风险 {% endif %}

关键技巧：Jinja2 的selectattr过滤器能高效筛选数据，format_currency是自定义 filter（需在 Agent-Reach 启动时注册），这里我们用 Python 的locale.format_string实现。

4.4 脚本编排：串联数据获取与 LLM 生成

创建generate_weekly_report.sh：

#!/bin/bash # 设置日期范围 WEEK_START=$(date -d "last monday" +%Y-%m-%d) WEEK_END=$(date -d "last sunday" +%Y-%m-%d) # 1. 获取数据（模拟，实际替换为 curl 命令） curl -s "https://bi.internal/api/sales?start=$WEEK_START&end=$WEEK_END" > sales_data.csv curl -s "https://gitlab.internal/api/v4/projects/123/repository/commits?since=$WEEK_START&until=$WEEK_END" | jq '[.[] | {author: .author.name, message: .title, date: .committed_date}]' > commits.json curl -s "https://jira.internal/rest/api/3/search?jql=project=PROJ+AND+updated>=${WEEK_START}" | jq '.issues[] | {key: .key, summary: .fields.summary, priority: .fields.priority.name, status: .fields.status.name}' > tickets.json # 2. 生成周报 agent-reach \ --model qwen2:7b \ --template weekly_report.j2 \ --input sales_data.csv \ --input commits.json \ --input tickets.json \ --set week_start="$WEEK_START" \ --set week_end="$WEEK_END" \ --output-format markdown \ > weekly_report.md # 3. 发送邮件（使用 mail 命令） mail -s "【周报】$WEEK_START 至 $WEEK_END" manager@company.com < weekly_report.md

实操心得：--set参数用于注入模板变量，比在 JSON 里硬编码更灵活。--input可多次使用，Agent-Reach 会自动合并为一个 context dict，键名为文件名（sales_data、commits、tickets），完美匹配模板中的{{ sales_data }}引用。

4.5 部署与监控：让自动化真正可靠

将脚本加入 crontab：

# 每周一上午 8:30 执行 30 8 * * 1 /path/to/generate_weekly_report.sh >> /var/log/agent-reach-weekly.log 2>&1

监控要点：

• 日志检查：tail -f /var/log/agent-reach-weekly.log，关注exit code和ERROR关键字
• 显存监控：nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits，设置告警阈值 90%
• 输出验证：在脚本末尾添加if [ ! -s weekly_report.md ]; then echo "ERROR: report is empty" | mail -s "Agent-Reach Alert" ops@company.com; exit 1; fi

我曾在一个客户现场发现，某次周报为空，排查后发现是 Jira API 返回了 503 错误，但curl默认不报错。解决方案是在curl命令后加-f参数（curl -f -s ...），让 HTTP 错误码触发 shell 退出，从而中断整个流程并告警。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 模型加载失败：Failed to load model 'qwen2:7b'

现象：执行agent-reach --model qwen2:7b --prompt "test"报错Error: model not found，但ollama list显示该模型存在。

根因分析：Ollama 的模型 registry 是按命名空间隔离的。ollama list显示qwen2:7b，但 Agent-Reach 默认查找ollama/qwen2:7b。如果你是用ollama run qwen2:7b启动的，模型实际注册在library/qwen2:7b。

解决方案：

• 方法一（推荐）：统一用完整命名agent-reach --model library/qwen2:7b
• 方法二：重命名模型ollama tag qwen2:7b ollama/qwen2:7b
• 方法三：修改 Agent-Reach 配置~/.agent-reach/config.yaml，添加default_provider: "library"

实操心得：Ollama 的模型命名规则是namespace/model:tag，library是官方镜像源，ollama是本地构建源。Agent-Reach 默认优先ollama，所以用ollama create构建的模型最省心。

5.2 输出格式错乱：JSON 解析失败但 exit code 为 0

现象：--output-format json时，终端输出一堆乱码，echo $?返回 0，但后续jq命令失败。

根因分析：Agent-Reach 的 JSON 解析是“尽力而为”（best-effort）。当模型返回{"result": "success"}\n\n{"data": [1,2,3]}这样的多 JSON 对象时，它只提取第一个，剩余内容被丢弃，但不报错。

解决方案：

• 强制模型只输出单个 JSON：在 prompt 末尾加约束"请只输出一个 JSON 对象，不要有任何额外文字，不要用代码块包裹。"
• 使用--strict-json参数：启用严格模式，任何非 JSON 输出都返回 exit code 2
• 用--debug查看原始 response，确认模型是否真的返回了干净 JSON

5.3 性能骤降：同一命令，第一次慢，后续快

现象：首次运行agent-reach --model qwen2:7b耗时 15 秒，第二次只要 2 秒。

根因分析：这是 Ollama 的模型加载机制。首次调用时，Ollama 需要将 GGUF 模型文件 mmap 到内存，并初始化 CUDA context，这个过程不可跳过。Agent-Reach 本身无缓存，它只是 Ollama 的客户端。

优化方案：

• 预热：在服务启动脚本中加入ollama run qwen2:7b "test"，让 Ollama 提前加载
• 持久化 context：用ollama serve启动守护进程，Agent-Reach 通过 HTTP 调用，避免重复加载
• 模型量化：使用qwen2:7b-q4_k_m（4-bit 量化）替代qwen2:7b，加载时间减少 40%，显存占用减半

5.4 权限错误：Permission denied while trying to connect to the docker api

现象：在 Docker 容器中运行 Agent-Reach 调用 Ollama，报错Permission denied。

根因分析：Docker 默认不挂载宿主机的 Docker socket（/var/run/docker.sock），而 Ollama 客户端需要访问它来拉取模型。

解决方案：

# 启动容器时挂载 socket docker run -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd):/workspace \ agent-reach --model qwen2:7b --prompt "test"

注意：挂载 Docker socket 有安全风险，生产环境应使用 Ollama 的 HTTP API（OLLAMA_HOST=http://host.docker.internal:11434）替代 socket 方式。

5.5 中文乱码：Windows 终端显示方框

现象：在 Windows CMD 中运行，中文输出显示为□□□。

根因分析：CMD 默认代码页是 GBK，而 Agent-Reach 输出 UTF-8。

解决方案：

• 临时切换：chcp 65001（UTF-8 代码页）
• 永久设置：在 CMD 属性 → 字体 → 选择“Lucida Console”或“Consolas”，然后reg add "HKCU\Console" /v "CodePage" /t REG_DWORD /d 65001 /f
• 推荐：改用 Windows Terminal，它原生支持 UTF