MSiang03/harness-agent-demo

Harness Agent · 企业采购智能工作台

Harness Agent 是一个面向企业采购场景的完整 Agent Harness 实战项目。它不是单纯的聊天机器人，而是一套能够规划任务、调用工具、委派子 Agent、管理上下文、记忆用户偏好，并在安全沙箱中执行文件与网络操作的采购工作平台。

项目采用 Vue 3 + FastAPI + DeepSeek + MCP/ERP + OpenSandbox 架构，覆盖产品寻源、供应商分析、库存查询、采购下单、人工审批、产品准入和报告下载等完整业务流程。

项目亮点

• —可执行的采购 Agent：不仅生成文字，还能查询供应商、物料、库存和订单，并通过工具完成真实业务动作。
• —任务规划与过程可视化：复杂任务会拆分为 pending / in_progress / completed 步骤，前端实时展示思考、工具调用和执行结果。
• —专业子 Agent 委派：主 Agent 可将分析和订单任务分别交给采购分析专家与订单专家；子任务上下文相互隔离，并支持并行执行。
• —Human-in-the-Loop：订单信息不完整时主动要求补充，创建或修改订单前必须经过用户最终确认。
• —上下文压缩与长期记忆：大工具结果自动卸载到文件；对话接近上下文上限时生成摘要；用户偏好和历史信息可跨会话保留。
• —渐进式 Skills 系统：技能以 SKILL.md + 文档 + 脚本 的方式组织，按需加载，并支持用户技能恢复与持久化。
• —OpenSandbox 安全边界：Agent 的命令执行、文件读写、网页访问、技能脚本和报告生成都在用户专属沙箱内完成。
• —用户级数据隔离：订单、已购库存、产品申请、会话、记忆与沙箱都使用登录用户身份隔离。
• —可下载分析报告：Agent 生成的 Markdown 报告会作为附件展示，并通过带身份认证的文件流安全下载。
• —企业级前端体验：提供响应式聊天工作台、执行过程、审批卡片、历史会话、个人设置和 ERP 资产看板。

业务能力

智能采购分析

• —按品牌、价格、质量和交期筛选产品
• —对比供应商报价与履约能力
• —查询物料、库存和低库存风险
• —汇总分析结果并生成可下载报告

采购订单工作流

1. 1.Agent 解析供应商、物料、数量和申请人。
2. 2.缺少必要字段时暂停任务，要求用户补充信息。
3. 3.信息完整后展示待执行参数，等待人工批准。
4. 4.批准后调用 ERP 工具创建或修改订单。
5. 5.将结果写入用户订单、库存和会话记录。

非正式产品准入

外部搜索结果如果没有企业正式 part_id，系统不会直接下单。用户可以提交 PR-* 产品准入申请，由 ERP 审核后生成 PART-NEW-* 正式物料编号；审核期间，Agent 会优先推荐企业目录中的可用替代品。

系统架构

flowchart LR
    U["用户浏览器"] --> F["Vue 3 工作台 · :3000"]
    F -->|"REST + SSE + Bearer Token"| B["FastAPI Backend · :8090"]
    B --> A["Harness 主 Agent"]
    A --> L["DeepSeek LLM"]
    A --> SA["采购分析 / 订单子 Agent"]
    A --> M["Middleware · Memory · Skills"]
    A --> S["用户专属 OpenSandbox · :8080"]
    A -->|"采购工具"| G["MCP / ERP 网关 · :8000"]
    G --> E["内置 SQLite ERP 或企业 ERP"]
    B --> D["MongoDB + Auth SQLite"]
    S --> R["报告 / 文件 / 网页执行结果"]
    R --> B --> F

Harness 核心能力

1. 任务规划

write_todos 和 update_todo 维护结构化任务列表。主 Agent 会先规划复杂目标，再逐步执行；同一时间只保留一个执行中的步骤，前端同步呈现状态。

2. 沙箱文件系统

Agent 的工作区、技能、报告和临时分析文件位于 OpenSandbox 内。宿主机文件系统默认不可见，所有路径经过安全校验，避免路径穿越和越界访问。

3. 子 Agent 隔离

项目内置两个声明式子 Agent：

每次 task 委派都会创建独立运行上下文；多个互不依赖的任务可以并行，避免中间数据污染主对话。

4. 上下文管理

• —工具结果超过 20,000 tokens 时写入文件，仅保留路径和预览。
• —对话达到上下文窗口的 85% 时自动生成摘要。
• —compact_conversation 支持 Agent 主动压缩长对话。
• —完整历史、摘要和子 Agent 报告保存在 context_store/。

5. 中间件与故障恢复

自定义中间件覆盖用户上下文注入、技能同步、技能恢复、记忆更新、沙箱健康检查和熔断。每个 Agent step 前检查沙箱状态；故障时可重建容器、原子替换代理句柄并恢复 AGENTS.md 与 Skills。

6. Skills 与记忆

Skills 在启动阶段只披露元数据，Agent 确定需要后再读取完整说明和脚本。用户偏好包括输出格式、图表类型、币种、语言、常用供应商与近期查询，可由用户设置或根据对话自动更新。

7. 安全控制

• —OpenSandbox 默认网络策略为 deny，通过白名单开放必要出口。
• —每个用户拥有独立的沙箱代理和业务数据范围。
• —Agent 工具执行设有最大迭代和工具调用限制。
• —订单写操作必须绑定可信用户上下文。
• —报告文件名采用严格白名单校验，并从当前用户沙箱读取。
• —登录密码使用 PBKDF2 加盐哈希保存，不存储明文。

技术栈

项目结构

.
├─ frontend/                       Vue 3 采购工作台
│  └─ src/components/              聊天、审批、设置、ERP 等组件
├─ backend/
│  ├─ src/api_view/                FastAPI 路由、认证与 SSE
│  └─ src/agent/
│     ├─ backends/                 OpenSandbox 生命周期与代理
│     ├─ middlewares/              上下文、技能、记忆、健康检查
│     ├─ subagents/                子 Agent 运行时与 YAML 配置
│     └─ tools/                    报告、搜索、审批和 MCP 工具
├─ mcp_server/                     ERP 网关与内置 SQLite 数据层
├─ skills/                         可复用 Agent Skills
├─ context_store/                  对话摘要、长期记忆与报告索引
├─ test/                           离线回归与集成测试脚本
├─ 项目/项目要求.md                 Harness 项目验收要求
└─ 项目简介.md                     详细设计说明

快速开始

环境要求

• —Windows 10/11 或兼容的 PowerShell 环境
• —Python 3.11+
• —Node.js 18+
• —Docker Desktop
• —MongoDB 7（可选；不可用时部分数据能力会降级）
• —DeepSeek API Key

1. 配置并启动 MCP / ERP 网关

cd mcp_server
Copy-Item .env.example .env
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn server_main:app --host 127.0.0.1 --port 8000

默认使用内置 SQLite ERP。配置 ERP_API_BASE_URL 后，可以切换到企业现有 ERP。

2. 配置 OpenSandbox

项目提供安全配置模板和自动配置脚本：

powershell -ExecutionPolicy Bypass -File backend/scripts/configure_opensandbox.ps1
uvx opensandbox-server

默认地址为 http://127.0.0.1:8080。脚本会生成 API Key，并同步设置 OpenSandbox 与 Backend 配置。

3. 启动 Backend

cd backend
Copy-Item .env.example .env
# 编辑 .env，至少填写 DEEPSEEK_API_KEY
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn src.api_view.web_main:app --host 127.0.0.1 --port 8090

4. 启动前端

cd frontend
npm install
npm run dev

浏览器访问 http://localhost:3000，注册账号后即可使用。

关键配置

Backend 配置位于 backend/.env，完整示例见 backend/.env.example。

生产环境请使用强随机 OPEN_SANDBOX_API_KEY，并按业务需要收紧网络白名单。

API 概览

Backend 启动后可访问 http://localhost:8090/docs 查看完整 OpenAPI 文档。

测试与构建

离线架构与功能回归测试无需真实 DeepSeek、MongoDB 或 Docker：

backend\.venv\Scripts\python.exe test\test_product_features.py
backend\.venv\Scripts\python.exe test\test_security_isolation.py
backend\.venv\Scripts\python.exe test\test_sandbox_architecture.py
backend\.venv\Scripts\python.exe test\test_chat_delivery.py
backend\.venv\Scripts\python.exe test\test_context_subagents.py
backend\.venv\Scripts\python.exe test\test_erp_api.py

需要 MCP 或外部服务的集成测试：

backend\.venv\Scripts\python.exe test\test_mcp.py
backend\.venv\Scripts\python.exe test\test_all_tools.py

前端生产构建：

cd frontend
npm run build

OpenSandbox 生命周期

Backend 启动时会预热一个沙箱。用户首次发起 Agent 请求时，系统原子认领预热容器，并在后台补充新的预热实例。之后每个用户持有稳定的 SandboxBackendProxy：

1. 1.请求前检查沙箱健康状态。
2. 2.沙箱不可达时尝试重连或新建容器。
3. 3.使用 replace_backend() 原子替换底层实例。
4. 4.恢复 AGENTS.md、系统 Skills 与用户 Skills。
5. 5.尽力清理失效容器；连续故障时由熔断器阻止调用风暴。

安全配置模板位于 backend/opensandbox.secure.example.toml，其中包含 capability drop、no-new-privileges、PID/CPU/内存限制和网络出口控制建议。

数据与隐私说明

• —backend/data/auth.db 保存本地账号凭证哈希。
• —mcp_server/data/erp.db 保存内置 ERP 示例数据。
• —context_store/ 保存本地对话上下文、摘要和长期记忆。
• —.env、数据库、日志和生成报告不应提交到公开仓库。
• —接入企业 ERP 或生产 MongoDB 时，应使用独立服务账号、最小权限和传输加密。

项目文档

• —`项目/项目要求.md`：项目验收目标与 Harness 能力要求
• —`项目简介.md`：更详细的架构、模块和设计背景
• —`backend/.env.example`：Backend 完整环境变量模板
• —`backend/opensandbox.secure.example.toml`：OpenSandbox 安全配置模板

Harness Agent 展示了如何把模型、工具、子 Agent、上下文、记忆、Skills、人工审批和容器安全组合成一个真正可运行、可追踪、可扩展的企业 Agent 系统。