Oficio

面向现实世界行业业务的、以验证为先的智能体引擎。 LLM 负责对话；确定性引擎负责计算；评测负责证明。

Oficio 将一段与客户的自然对话转化为一份可证明正确的装修报价单。它建立在一项毫不妥协的规则之上：语言模型绝不计算价格。 智能体提取客户想要的内容——每一行都附有字面证据（source_quote）——然后由确定性定价引擎依据一份源自真实装修公司（已匿名化）的版本化价格手册，精确到分地完成计算。

为什么会存在

大多数 AI 演示都要求你信任它们。Oficio 的设计目标则是可被验证：

（本 README 中的评测表由 python -m oficio.evals.report 生成——绝非手写。）

Related MCP server: IntentForge MCP Server

现状——诚实且公开

v1.0——162 项测试全绿，评测套件已针对真实模型运行：所有门禁均通过。

已完成并通过验证：

• 确定性引擎——Decimal 金额运算、离散材料按整单位计费（你无法购买 3.2 袋水泥）、利润率下限强制、任何未定价项标记为 needs_info、基于内容哈希的可复现报价 ID。30 份冻结的黄金报价单在 CI 中复现到分毫不差。

• 加固的模型客户端——故障即关闭的定价（未定价的模型会直接报错，绝不产生 $0 费用）、每日预算在调用发出之前即被拒绝、仅在 429/5xx 时进行指数退避、每次调用生成一条包含 token、成本和延迟的 JSONL 追踪记录。

• 带强制证据的提取——模型只能从目录中选取 ID，每一行都必须逐字引用客户原话。在对话记录中找不到证据的内容会被丢弃并转化为一个问题。

• 评测套件——100 段标注对话和 20 段对抗性对话。测试框架本身也经过测试：评分器必须证明它能发现错误数量、遗漏项目和编造项目。

• MCP 服务器——get_catalog、create_quote、explain_quote。购买方智能体无需抓取表单即可报价，explain_quote 会逐行返回运算过程：一个无法解释某个数字的智能体，就不应该把它发送出去。

• API 与演示——/quote 完全不需要 API 密钥即可确定性定价，因为引擎本身就是产品；/chat 增加了提取功能，并在未设置密钥时明确拒绝，而不是退化为猜测。页面第三个面板智能体所见会显示每条已定价行背后的客户确切原话，以及所有在定价前被丢弃的内容。

评测结果

于 2026-08-27 针对 claude-haiku-4-5、价格手册 v1.0.0 测得。使用 python -m oficio.evals.run all --json evals/reports/latest.json 复现。该表由 python -m oficio.evals.report 生成——绝非手写。

完整运行的总成本：$0.27。

最值得读两遍的数字不是 F1，而是这两项放在一起：模型在那一百段对话中确实尝试编造了四个条目，而验证器在任何一个条目到达价格之前就全部拦截了下来。一个声称自己的模型从不产生幻觉的系统，是一个根本没有在看的系统。这个系统在看，并把它看到的展示给你看。

另一项是 asked instead of guessing：在全部 25 段无法按原话报价的对话中——条目不在目录内、数量从未给出——智能体返回的是一个问题，而不是一个数字。拒绝回答是一项特性，它必须像其他任何特性一样被测试。

线上运行会调用真实模型，因此它们是手动触发的，而不是每次推送都触发：一次提交绝不应该意外花钱。

这里没有任何东西是在运行之前就宣称成立的。

快速开始

git clone https://github.com/brayans7/oficio && cd oficio
pip install -e ".[dev,agent]"
pytest                                   # 162 tests, including the price-book leak gate
uvicorn oficio.service.api:app --reload  # then open http://localhost:8000

该演示无需 API 密钥即可为真实工程报价。设置 ANTHROPIC_API_KEY 以启用对话路径和线上评测套件。

工作原理

customer conversation
        │
        ▼
   extraction (LLM)          ← catalog-bounded; every line must quote the customer verbatim
        │                      no evidence in the transcript → dropped, becomes a question
        ▼
      JobSpec                ← validated: known ids, positive quantities, real evidence
        │
        ▼
   quote engine              ← deterministic. Decimal math, versioned price book,
        │                      whole units for discrete materials, margin floor enforced
        ▼
   QuoteResult               ← content-hashed id: same inputs, same quote, forever

模型提出方案，引擎做出裁决。任何无法追溯到客户原话的内容都不会获得价格。

从另一个智能体使用它（MCP）

from oficio.service.mcp_tools import call_tool

catalog = call_tool("get_catalog", {"category": "flooring"})
quote = call_tool("create_quote", {"line_items": [
    {"item_id": "ceramic_tile_standard", "qty": 12,
     "source_quote": "I need new floor tile for the kitchen"},
]})
print(call_tool("explain_quote", {"quote": quote})["summary"])

使用 python -m oficio.service.mcp_tools 将其作为 stdio MCP 服务器运行。

架构

src/oficio/
  core/     # deterministic: schemas, price book, quote engine — pure, no LLM imports
  agent/    # conversational: extraction w/ evidence, model routing, cost meter, guardrails
  evals/    # labeled datasets, runner, report generator — the public proof
  service/  # MCP tools for agents, FastAPI + demo page for humans
data/
  pricebook.v1.json   # anonymized real-world price book (labor + materials)
  evals/              # 100 labeled conversations + 20 attacks

硬性边界：agent/ 只能导入 core/。绝不允许反向。

设计决策（有意为之）

• 神经符号拆分——LLM 擅长理解，却不擅长算术问责。引擎拥有每一个数字。

• 没有证据就等于没发生——每一行报价都携带 source_quote，即证明其合理性的客户原话。没有证据的行是评测失败，而不是特性。

• 处处故障即关闭——未知条目 → needs_info（绝不估算）；没有价格条目的模型 → 抛异常（绝不产生 $0）；缺少密钥 → 拒绝启动。

• v1 不引入数据库——一份 JSON 价格手册和 JSONL 追踪记录对 MVP 来说已经足够。刻意排除在范围之外：支付、认证、多租户、调度、第二个垂直领域。

路线图

v1 刻意排除在范围之外的事项及原因：支付（报价单就是产品；收款是另一个问题）、认证与多租户（一家公司、一本价格手册——在第二本出现之前，这些都只是猜测）、调度（一个有着自身失败模式的领域）、第二个垂直领域（关键在于把模式证明一次，并且证明得好）。

真正接下来要做的是：基于真实对话记录而非合成对话构建标注集——目前的数字衡量的是这一分布，而非真实世界——以及让价格手册针对第二家公司进行校准，这才是把一套可用的引擎变成产品的关键。

来源与诚实性

价格手册源自一家家族装修公司的实际运营，姓名已移除，价格按未披露的系数缩放并加入逐项抖动——保留了真实的比例关系，同时保护了商业机密。匿名化管道本就有意设为私有，并由 CI 中的泄漏门禁测试强制保障。

评测对话是由模板组合而成的，并非真实客户的对话记录。这使它们可复现、可发布，也意味着所报告的准确率是针对这一分布的准确率。在此直说无妨，因为一个来源不明的基准，是没人应该信任的基准。

由 Brayan Molina 使用规范驱动开发与 Claude Code 构建。采用 MIT 许可证。