Agent Harness 实战：从本地部署到批量任务与API接入的完整指南

Harness 这个词最近在开发者社区里热度上升得很快。它频繁和 DeepSeek、Codex 放在一起讨论，已经不再只是 CI/CD 工具链里的那个 Harness 产品名，而是一类被称为agent harness的工作流控制层。简单说，光有大模型还不够，你要给 Agent 规定它能调用哪些工具、最多跑几轮、执行哪些命令前需要审批、出错之后怎么重试，这一整套约束就是 harness。

这次我以一个面向地产行业流程的助手型应用CI Buddy为例，梳理一条从本地部署、功能测试、批量任务到接口 API 调用的完整落地路线。如果你关注本地部署、资源占用、接口能力和批量任务，这篇文章可以收藏起来当参考。

需要先说明一个前提：无论 Harness 生态里的具体框架，还是地产团队的内部工具，都很少有开箱即用、双击完事的版本。下面给出的是一套通用部署与验证方案，涉及端口、路径、模型名的地方，需要按实际项目替换。

1. 核心能力速览

从这组能力可以看到，Harness 解决的不是“模型智商”问题，而是“模型行为可控性”问题。CI Buddy 这类行业助手，正是在这个基础上，把日常业务操作固化成可执行、可批量、可审计的工作流。

2. Harness 为什么突然火了

2.1 从“调接口”到“套流程”

过去一年里，开发者的关注点已经从“怎么调用大模型接口”切换到“怎么让模型在复杂任务里不失控”。单独发一个 prompt，模型能回答问题；但让它连续读文件、改代码、执行命令、把结果写回系统，就需要一层流程外壳。

这层外壳就是 harness。常见的控制点包括：

• 模型一次会话能执行多少轮工具调用；
• 哪些命令需要人工审批；
• 文件读写的权限边界；
• 上下文长度用完后如何压缩或截断；
• 日志如何保存，审计如何追踪。

2.2 DeepSeek Harness、Codex Harness 和 harness engineering

现在社区里讨论最多的，是DeepSeek harness和Codex harness这类具体玩法。它们的共同点是：把编程大模型接入一个比裸终端更受控的运行环境，让 Agent 既能操作文件、执行命令，又不会无限放任。

于是，“harness engineering” 这个词也跟着热起来。它并不是一个新的编程语言，而是一套工程能力：

• 设计 Agent 的工具集和权限边界；
• 定义重试、暂停、恢复机制；
• 把输出规范成 JSON、Markdown、表格等结构化格式；
• 把成功的工作流沉淀为模板，供非技术同学复用。

你可以把 harness 理解为“给 Agent 装了一个有刹车的驾驶舱”。真正进入生产环境，模型能力只是下限，刹车和流程才是稳定性的上限。

3. CI Buddy 的定位：为什么地产人需要“专属路线”

3.1 地产行业的工作流痛点

地产人的日常工作，并不是只有“看懂图纸”和“销售案场”。更普遍的场景是：土地踏勘后的指标整理、项目节点表的进度同步、案场销售周报汇总、合同台账的到期提醒、投资测算里的多版本对比。这些任务有很强的共性问题：

• 数据散落在 Excel、邮件、OA、ERP 里；
• 流程依赖人肉转发和审批；
• 报表格式经常变化，SQL 和 Python 脚本跟不上业务调整；
• 批量更新和提醒没有统一的执行入口。

这些场景并不需要特别强的“创造力”，而是需要稳定的流程执行、格式化和批量处理能力。这正是 Harness 类工作流擅长的地方。

3.2 CI Buddy 提供什么

从定位看，CI Buddy 是“地产人的 AI 工作流助手”，它做的事情是把常见业务动作封装成带约束的 Agent 工作流。比如：

• 输入一份土地指标 Excel，自动生成投资测算摘要；
• 输入一段销售日报，自动改写为周报格式并抽取出关键指标；
• 输入一批合同台账，按日期批量生成到期提醒清单；
• 把上述操作统一暴露成 API，让 OA 或企微机器人直接调用。

它不是要替代 ERP，而是在 ERP、OA 和人工决策之间，加一层“自然语言 + 流程控制”的中间层。对地产团队的数字化部门来说，这层最大的价值是：业务人员不需要写 Python，也能用一套固定流程跑出结构化结果。

3.3 为什么强调“专属路线”

通用 Agent 和行业专用工作流的差距，主要在模板、指标口径和合规要求上。地产行业有自己的术语和规则，比如“楼面地价”“可售比”“去化周期”这些概念，通用模型很容易给出模糊定义。CI Buddy 的做法，是把这些指标口径固化到工作流提示词和校验逻辑里，让模型在受限范围内生成内容，而不是自由发挥。

这就是“专属路线”的含义：不是重新做一个大模型，而是围绕行业术语、指标规则和审批流程，配置一套专属的 harness 工作流。

4. 适用场景与使用边界

4.1 适合做什么

• 报表类：如销售周报、月报、土地台账摘要的自动生成；
• 提醒类：合同到期、回款节点、工程节点的批量提醒；
• 解析类：从 PDF、Excel、邮件中抽取结构化字段，写入指定系统；
• 文档类：把非结构化会议纪要按照模板整理成待办；
• 流程接入类：作为 OA、企微、钉钉机器人的后端逻辑层。

4.2 不适合做什么

• 不能直接用于对外投资决策，最终结论必须由专业岗复核；
• 不能处理未经脱敏的客户隐私数据和敏感合同全文；
• 不适合做实时交易型系统的主链路，模型延迟和偶发错误不可控；
• 不适合完全代替审批人，“AI 自动审批”在大多数地产企业里还不具备合规基础。

4.3 数据合规与安全边界

这部分必须单独提醒。

• 涉及客户信息、合同金额、营销数据的场景，先做脱敏，再进入模型工作流；
• 如果使用公网模型 API，确认数据出域是否符合公司安全制度；
• 敏感业务建议用私有化部署模型，或至少在网关层做日志脱敏；
• 所有 AI 生成结果都要保留操作日志，方便追溯和复核；
• 不得用该方案处理与国家安全、违法活动相关的内容。

5. 环境准备与部署方案

5.1 前置环境清单

在开始部署前，先确认以下基础环境：

5.2 快速启动一个 Harness 工作流服务

下面是一份参考用的docker-compose.yml。它通过环境变量注入模型 API Key，把工作流服务映射到本机端口。按实际项目替换镜像名、环境变量和挂载目录即可。

version: "3.8" services: harness-worker: image: your-registry/ci-buddy-harness:latest container_name: ci-buddy-worker restart: unless-stopped ports: - "8000:8000" environment: - LLM_PROVIDER=deepseek - LLM_API_KEY=${LLM_API_KEY} - LLM_MODEL=deepseek-chat - WORKFLOW_DIR=/app/workflows - OUTPUT_DIR=/app/outputs - LOG_LEVEL=INFO volumes: - ./workflows:/app/workflows - ./outputs:/app/outputs - ./logs:/app/logs command: ["python", "main.py", "--host", "0.0.0.0", "--port", "8000"]

如果不用 Docker，也可以用命令行直接启动：

export LLM_PROVIDER=deepseek export LLM_API_KEY=your_api_key_here export LLM_MODEL=deepseek-chat export WORKFLOW_DIR=./workflows export OUTPUT_DIR=./outputs python main.py --host 127.0.0.1 --port 8000

启动后访问http://127.0.0.1:8000/health，能看到健康检查结果，说明服务已经起来。

5.3 工作流配置示例

Harness 的核心是工作流文件。下面这份 YAML 定义了一个面向地产销售周报的流程，包含输入格式、处理步骤和输出规范。具体字段以实际框架为准。

name: sales_weekly_report description: 从销售日报生成周报摘要 version: 1.0.0 input: type: csv columns: - 日期 - 项目名称 - 认购套数 - 签约套数 - 回款金额 steps: - name: parse_input action: read_csv path: ./inputs/sales_weekly.csv - name: summarize action: llm_generate prompt: | 你是地产销售运营助理。请根据以下销售数据生成周报摘要。 需要输出：本周总认购套数、总签约套数、总回款金额、环比变化、风险提示。 只输出 Markdown 表格，不要输出多余解释。 input_key: parsed_data output_key: summary_markdown - name: save_markdown action: write_markdown input_key: summary_markdown path: ./outputs/sales_weekly_report.md output: - 周报摘要 Markdown 文件 - 结果写入 outputs 目录

这份配置表达了一个很重要的产品逻辑：业务人员只需要替换输入 CSV，不需要修改代码；开发者负责把 parse、summarize、save 这些动作封装成可复用模块。

6. 功能测试与效果验证

下面给出三个验证维度。测试前，先准备好三组模拟数据。

6.1 测试一：土地指标摘要生成

测试目的：验证模型能否从结构化表格中提取关键指标，并输出特定格式。

操作步骤：

• 准备land_data.csv，包含地块编号、容积率、用地面积、建筑面积、起拍总价；
• 调用工作流接口，传入该文件路径或内容；
• 观察输出是否包含楼面地价、可售比、风险提示等字段；
• 校验数字计算是否准确。

预期结果：

• 输出 Markdown 或 JSON，字段完整；
• 模型不会生成表格之外不存在的编号；
• 计算类字段需要与 Excel 公式结果一致。

常见失败：

• 模型把“楼面地价”算错，说明提示词里没有给出公式，需要补充；
• 模型输出不存在的编号，说明结构化约束不够严格，可以在工作流里加正则校验。

6.2 测试二：销售周报批量生成

测试目的：验证批量任务能力和输出稳定性。

操作步骤：

• 在inputs/下放多个 CSV 文件，例如多个项目的日报表；
• 启动批量任务，让工作流按文件循环处理；
• 检查outputs/目录下是否生成一一对应的 Markdown 文件；
• 抽查其中 2-3 个文件，确认关键指标提取正确。

判断标准：

• 每个输入文件都有对应输出，不遗漏；
• 输出格式一致，方便后续合并到周报；
• 单个文件失败时，不影响其他文件继续执行。

如果批量任务卡住，优先检查模型 API 超时设置和单文件输入大小。

6.3 测试三：合同到期提醒任务

测试目的：验证日期计算和提醒消息生成。

操作步骤：

• 输入一份合同台账，包含合同名称、到期日期、负责部门；
• 工作流筛选出 7 天内到期的合同；
• 生成一条待办清单或企微消息文本；
• 人工核对日期筛选逻辑。

预期结果：

• 到期日期计算准确；
• 输出中包含合同名称、到期日、责任部门；
• 没有到期日期字段的行会进入异常列表而不是被静默跳过。

这个场景尤其适合接入 OA 机器人。通过 API 把生成的待办推送到企微群，能显著减少人工催办成本。

7. 接口 API 与批量任务

7.1 参考 API 服务

下面是 FastAPI 风格的通用接口示例，用于接收任务请求、返回执行结果。实际项目需要按框架和路由调整。

from fastapi import FastAPI, BackgroundTasks from pydantic import BaseModel app = FastAPI() class TaskRequest(BaseModel): workflow: str input_path: str output_path: str = "./outputs" @app.post("/api/run") async def run_task(req: TaskRequest, background_tasks: BackgroundTasks): # 这里应根据 req.workflow 加载对应 YAML 配置 # 并调用 harness 执行器 background_tasks.add_task(execute_workflow, req) return {"status": "accepted", "workflow": req.workflow} def execute_workflow(req: TaskRequest): # 伪代码：加载配置、执行步骤、写日志 print(f"run workflow: {req.workflow}") print(f"input: {req.input_path}") @app.get("/health") async def health(): return {"status": "ok"}

调用方式：

curl -X POST "http://127.0.0.1:8000/api/run" \ -H "Content-Type: application/json" \ -d '{ "workflow": "sales_weekly_report", "input_path": "./inputs/sales_weekly.csv", "output_path": "./outputs/sales_weekly_report.md" }'

Python 调用示例：

import requests url = "http://127.0.0.1:8000/api/run" payload = { "workflow": "sales_weekly_report", "input_path": "./inputs/sales_weekly.csv", "output_path": "./outputs/sales_weekly_report.md" } response = requests.post(url, json=payload, timeout=120) print(response.json())

7.2 批量任务的组织方式

建议使用目录扫描 + 任务队列的方式：

inputs/ land_park_a.csv land_park_b.csv sales_weekly.csv outputs/ land_park_a.md land_park_b.md sales_weekly.md logs/ run_20250101.log

后台脚本可以这样循环：

for f in ./inputs/*.csv; do echo "processing $f" curl -X POST "http://127.0.0.1:8000/api/run" \ -H "Content-Type: application/json" \ -d "{\"workflow\":\"sales_weekly_report\",\"input_path\":\"$f\"}" done

批量任务建议加三个机制：

• 任务 ID：每个任务生成唯一 ID，方便追踪日志；
• 失败重试：请求失败时退避重试，最多 3 次；
• 限流：控制并发数，避免模型 API 被限流。

8. 资源占用与性能观察

8.1 观察什么

如果服务只是做 API 转发，不加载本地模型，显存占用通常很低，更多资源消耗在 CPU 和内存上。你可以用以下命令观察：

docker stats nvidia-smi top -p $(pgrep -f "python main.py")

docker stats能看容器整体的 CPU 和内存占用；如果部署了本地推理，nvidia-smi才是显存判断依据。

8.2 模型规模与显存的关系

纯 API 模式不依赖本机显卡。本地部署模型时，显存占用主要取决于模型参数量、量化精度和输入长度。一个 7B 级别的量化模型，不同精度下显存差异很大；未量化模型通常需要更高显存。稳妥的做法是：

• 先用小模型跑通流程；
• 再用目标模型接入，观察峰值显存和首 token 延迟；
• 如果显存不足，优先降低 batch size、缩短输入文本、关闭多余的并发任务。

8.3 影响性能的主要因素

• 输入长度：越长，首次响应越慢；
• 输出长度：影响整体耗时；
• 批量并发数：并发过高会被模型服务限流；
• 日志存储：长时间批量任务会产生大量日志，建议按天切分并定期清理；
• 工作流中的文件读写：如果频繁读取大 Excel，IO 也会成为瓶颈。

8.4 如何避免端口冲突

如果8000被占用，可以先查端口占用情况：

lsof -i :8000

再启动时换成其他端口，例如8080或7860。服务端口需要与前端机器人的回调地址、流程系统的 Webhook 保持一致。

9. 常见问题与排查方法

排查时记住一个原则：先看日志，再查上游，最后改配置。不要一上来就调模型参数。

10. 最佳实践与工程建议

10.1 第一次先跑通最小工作流

不要一开始就接全部系统。先用一个最简流程，比如“读 CSV -> 生成摘要 -> 写 Markdown”，把链路跑通，再逐步增加权限、审批、批量任务。

10.2 配置、输入、输出、日志分目录管理

建议目录结构固定：

workflows/ # YAML 工作流定义 inputs/ # 输入数据 outputs/ # 结果文件 logs/ # 运行日志

这样做的好处是批量任务和审计追溯都方便。

10.3 接口服务要限制访问范围

如果服务部署在服务器上，不要默认监听0.0.0.0，至少限制到内网 IP 或加 API Token 鉴权。生产环境下建议放在网关后面，由统一网关做权限控制。

10.4 给批量任务加日志和失败重试

每个任务都要有唯一 ID、开始时间、结束时间、输入路径、输出路径。失败重试要设置最大次数，避免死循环。

10.5 合规与授权

• 不要用未经脱敏的客户数据直接测试公网模型接口；
• 涉及人脸、声音、肖像、合同稿等素材，必须确认授权范围；
• AI 生成的投资测算、风险预警、合同摘要不能直接作为最终决策依据；
• 保留完整操作日志，方便问题回溯。

11. 总结与下一步

Harness 的热度，本质上是大家在思考同一个问题：大模型接入真实业务时，如何保证行为可控。独立跑一次 prompt 很简单，但要做成批量、稳定、可审计的行业工作流，就需要 harness 这层约束。

CI Buddy 的地产路线，核心不是模型有多聪明，而是把土地测算、销售周报、合同提醒这些高频场景固化成了业务模板。你可以先验证三件事：第一，一个最小工作流能否稳定输出指定格式；第二，批量任务在多次运行后是否稳定；第三，接口 API 能否被 OA 或企微机器人正常调用。

最容易踩的坑也先说在前面：数据没脱敏就接公网模型、提示词里没写输出格式、批量任务没有日志。这三个问题排掉，这个方案已经能进入内部试用阶段。

后续扩展方向很明确：把工作流模板做成可视化配置页面，让地产运营人员在界面上拖拽生成流程；把输出结果接到企业微信或钉钉机器人，在群聊里直接触发周报生成；再进一步，和 OA 审批流打通，让 AI 负责整理数据和草拟意见，人工只做最终确认。

这套路线对地产团队是轻量、低成本的解决方案，对开发者来说也是一次理解 harness engineering 的好机会。建议先按文章里的最小流程跑通一遍，再逐步往生产环境搬。