企业官网建设流程全解析

在 Hacker News 上看到 Stonefold 这个项目时，我第一反应不是“又一个 AI 网关”，而是它把 AI Agent 接入系统时最容易被忽略的问题说清楚了：模型可以自由发挥，但系统必须稳定可靠。

现在很多团队做大模型应用，最痛苦的点已经不是 Prompt 写不好、模型不够聪明，而是 Agent 一旦开始调用真实业务 API，你就要面对完全不可控的后果。模型可能产生幻觉、可能把参数名映射错、可能反复重试同一个写操作、可能在一个并未授权的上下文里访问内网服务。你很难靠“提示词约束”解决这些问题，因为提示词本质上是概率性的。

Stonefold 给出的答案是：在 Agent 和你的系统之间，加一层确定性的网关。所谓确定性，就是请求能不能通过、会去哪个后端、返回什么格式，都由规则和可验证的代码决定，而不是由模型在现场临时判断。

这个项目会在 Show HN 引起讨论，不是因为它是新的 Agent 框架，而是它把“控制的职责”从模型手里拿回了工程师手里。读完这篇文章，你会明白三件事：AI Agent 为什么不能直接调内网系统；一个最小可用的确定性网关应该怎么落地；如何用网关日志把 AI Agent 的评测（Evals）从“凭感觉打分”变成可断言的工程测试。

1. AI Agent 接入系统：痛点到底在哪里

先看一个非常常见的场景。团队基于大模型做了一个“智能客服助手”，它需要查询订单、创建售后单、更新用户地址。一开始，你直接给 Agent 暴露了三个后端 API 的 SDK。一切看起来很简单，但上线后问题不断。

1.1 模型输出天然不确定

大模型生成工具调用参数时，本质上是按概率采样。同一个用户问题，模型可能这次把customer_id解析成C001，下次却解析成001。如果后端 API 对参数有严格要求，这种细微不稳定就会变成线上错误。

更麻烦的是，模型偶尔会把amount和quantity搞混，甚至在没有得到用户确认时，直接发起一次“删除”操作。你可以在 Prompt 里写“未经确认不得删除”，但大模型对这类指令的理解并不是 100% 稳定。

1.2 权限边界难以收拢

直接让 Agent 调用后端 API，意味着 Agent 拥有的权限约等于后端 API 的权限。如果后端服务的 API Key 权限过宽，Agent 一旦被诱导或误用，可能访问到客户管理、订单导出、配置修改等高危接口。

传统服务间调用有明确的账号体系、IP 白名单、OAuth Scope，而 Agent 调用时，你很难判断“这次调用背后是哪个对话、哪个用户、哪条业务规则”。在不确定来源的请求进来之前，必须有一个确定的关卡把身份、权限、操作边界全部校完。

1.3 审计和排障困难

Agent 与后端之间如果只是点对点调用，出了问题你会看到两边的日志，但很难还原完整链路。Agent 决定调用什么工具，是模型推理的结果；后端是否接受，则取决于后端逻辑。中间缺一层记录“模型意图、实际请求、最终决策”的审计层。

换句话说，直接对接的架构里，“模型意图”和“系统事实”是脱节的。出了事故，你很难回答：到底是模型选错了工具，还是后端参数校验没做好？

1.4 评测（Evals）没有稳定锚点

现在 AI Agent 评测越来越受重视，但很多团队的 eval 还停留在“回答是否正确”。对于会调用系统的 Agent 来说，真正重要的不是“答了什么”，而是“做了什么”。如果中间没有一层确定性网关，你很难断言“这次 Agent 调用是否越权”“这个危险操作是否被拦截”。

Stonefold 这类确定性网关，正好把这些痛点收敛到了一层。它不负责让模型更聪明，它负责让 Agent 的行为更可预期。

2. 确定性网关是什么：Stonefold 带来的架构变化

Stonefold 的定位，从项目名称就可以看出：在 AI Agent 和你的系统之间，充当一个确定性的网关。这里的“网关”不是传统意义上的负载均衡或反向代理，而是一个专门面向 Agent 工具调用的控制层。

传统架构中，Agent 直接调用业务系统：

Agent -> 企业内部系统

引入确定性网关后，调用链路变成：

Agent -> Stonefold 确定性网关 -> 企业内部系统

这个中间层会做几件非常关键的事：

• 身份认证：确认当前 Agent 是谁，属于哪个应用，拥有哪些权限范围。
• 需求映射：把 Agent 的“自然语言意图”映射成“系统允许执行的操作”。
• 白名单校验：目标服务、路径、方法必须在配置里存在。
• 参数校验：请求体是否符合 JSON Schema，字段名、类型、取值范围是否合法。
• 操作审计：记录每一次调用的完整决策过程，供后续追查和评估。

真正容易忽略的是“确定性”这三个字。

在 Agent 链路里，模型选择调用哪个工具，本身是概率性的。但网关的决策不应该是概率性的。网关不应该问“这个请求看起来合理，要不要放行”，而应该问“这个请求是否匹配某条明确规则”。规则存在就是放行，规则不存在就是拦截。这个二元决策模型，才是 Stonefold 这类项目最核心的价值。

用一个类比来理解：大模型像一位很有创造力的员工，他能在不确定的信息里做判断；但企业系统不应该是这位员工想改什么就改什么。你必须给他一张“门禁卡”，规定他只能进哪些门、只能动哪些东西。Stonefold 就是发门禁卡的保安，而且是完全按手册办事、不讲情面的保安。

所以，Stonefold 并不是要和 LangChain、AutoGPT 这样的 Agent 框架抢位置，它是 Agent 框架与真实系统之间的基础设施层。无论 Agent 用的是 OpenAI Function Calling、Claude Tools，还是自己实现的工具调度逻辑，最终的工具调用命令都应该先经过这一层。

3. 确定性网关和传统 API 网关有什么区别

很多人一听到“网关”就会想到 Kong、Nginx、Spring Cloud Gateway。但 Stonefold 这类确定性网关，和传统 API 网关解决的问题并不完全一样。两者有重叠，但不能互相替代。

从这个表格可以看出，确定性网关是“更有立场”的一层。传统 API 网关通常假设调用方是可信的，只要认证通过、限流未超，就把请求转发到后端。但 AI Agent 的调用不能默认可信，因为同一个 Agent 可能面对完全不同的用户、对话和多轮上下文。

传统 API 网关也能做鉴权，但它的粒度往往是“应用级”的。Stonefold 强调的则是“操作级”甚至“参数级”的约束：不仅判断你能不能调用订单服务，还要判断你调用的参数是否符合业务规则。

举个例子，一个 Agent 在对话里说“帮我把订单 12345 的金额改成 100 元”。如果只靠传统 API 网关，只要 Agent 有订单服务的写权限，这个请求就会被转发。但 Stonefold 这类网关可以额外校验：当前 Agent 是否被允许修改订单金额？修改金额的参数是否来自业务允许的枚举？有没有对应的审批单号？

这些规则不需要大模型理解，它们写在配置里，由工程师审核并发布。Stonefold 的确定性，本质上就是把“业务的不可谈判规则”从模型能力中剥离出来。

4. 核心组件与工作流程拆解

虽然 Stonefold 的源码和安装方式需要参考官方项目，但从“确定性网关”这一类系统的通用设计来看，核心组件可以拆成这样五块。理解了这五块，你就能自己实现一个最小版本，也能读明白 Stonefold 设计的思路。

4.1 请求接入层

接入层接收 Agent 发来的工具调用请求。它通常是 HTTP 接口，也可以是 SDK 或消息队列入口。请求里必须带 Agent 身份信息和操作意图。

在 Stonefold 场景里，请求体不应该只是一个“自然语言问句”，而应该是结构化的工具调用，例如：

{ "intent": "创建发票", "service": "invoice_service", "path": "/v1/invoices", "payload": { "customer_id": "C001", "amount": 100, "currency": "CNY" } }

这个格式看起来很简单，但它给下游校验提供了明确输入。如果没有这个结构化入口，网关就需要去解析自然语言，那又回到了不确定的怪圈。

4.2 身份与权限解析

接入层下一步是认证。每个 Agent 有自己独立的身份标识，网关根据身份解析出它可以访问的服务和操作范围。这里要强调的是最小权限原则：一个用于查询订单的 Agent，不应该拥有删除订单的权限；一个用于测试的 Agent，不应该拥有生产环境的权限。

身份解析和权限解析应该全部是确定性的。它不依赖模型判断，也不依赖请求文本。只要 Token 没有匹配到身份，请求立即失败。

4.3 路由白名单校验

网关里要维护一份“该 Agent 能访问的服务、路径、方法”的清单。这份清单通常放到配置中心或代码仓库里，经过评审后发布。

校验逻辑很简单：

1. 目标服务是否存在于配置中？
2. 服务下的路径是否允许？
3. HTTP 方法是否允许？

如果有一个不符合，直接拒绝。这里最忌“宽松匹配”。比如配置了/v1/invoices，那/v1/invoices/delete_all这些额外路径就应该被当作不存在，而不是按前缀放行。

4.4 参数 Schema 校验

Agent 生成的参数经常不靠谱。比如数字类型写成字符串、必填字段缺失、枚举值不在业务允许范围、多传了不该传的字段。网关应基于 JSON Schema 或类似的校验机制，对请求体做强校验。

additionalProperties: false这个配置在 Agent 场景里非常重要。模型经常会在用户要求外附加一些字段，如果网关不拦截，这些字段可能被后端意外消费。严格模式会让 Agent 学会只发送系统声明的字段。

4.5 审计与观测

每一次被允许或被拒绝的请求，都应该记录成一条审计事件。这条事件至少要包含：

• 请求时间
• Agent 身份
• 目标服务与路径
• 请求内容
• 决策结果（allow / deny）
• 拒绝原因
• 后端返回结果

这些数据不只是给人看的，在后面做 Agent 评测时，它就是“事实标准”。Stonefold 这类网关把安全控制和可观测性绑定在一起，这是它和普通 API 网关的重要差异。

一个完整的请求流程可以概括为：

1. Agent 生成结构化工具调用请求。
2. 请求携带身份 Token 发给网关。
3. 网关完成身份认证，拒绝未知 Token。
4. 网关检查目标服务、路径、方法白名单。
5. 网关校验请求体是否符合 Schema。
6. 网关记录一条请求审计事件。
7. 网关转发到内部系统，并校验返回结果。
8. 网关把后端响应返回给 Agent。

整个过程里，没有任何一步需要大模型参与理解。这就是“确定性网关”的含义。

5. 从零实现一个最小确定性网关

虽然 Stonefold 本身值得关注，但不用等官方中文文档出来，你也能用半小时写一个最小可用的确定性网关，把核心思路跑通。下面这个示例不依赖特定发行版，重点演示通用实现路径。

5.1 环境准备

本文示例使用 Python 3.10+，需要安装以下依赖：

pip install fastapi uvicorn pyyaml jsonschema

如果使用更低版本，注意str.removeprefix需要 Python 3.9+。

工程目录结构建议如下：

gateway_demo/ ├── gateway.py ├── gateway_config.yaml └── schemas/ └── invoice_create.json

5.2 配置文件

首先定义一份最小配置。配置里包含 Agent 身份和允许访问的服务路径。

# gateway_demo/gateway_config.yaml agents: - name: billing-agent token: demo-secret-token-123 services: - name: invoice_service paths: - path: /v1/invoices methods: [POST, GET] schema_file: schemas/invoice_create.json

这个配置的含义是：只有billing-agent能使用 Tokendemo-secret-token-123，而且只能访问invoice_service下的/v1/invoices路径。默认情况下，其他服务、其他路径都不可访问。

5.3 参数 Schema

为创建发票定义严格的 JSON Schema。这里故意设置additionalProperties: false，用来拦截模型产生的多余字段。

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": ["customer_id", "amount"], "properties": { "customer_id": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "minimum": 0.01 }, "currency": { "type": "string", "enum": ["CNY", "USD", "EUR"] } }, "additionalProperties": false }

这里amount必须是数字类型。如果 Agent 把100传成字符串"100"，网关要立即拒绝，避免下游系统做隐式转换后产生错误。

5.4 网关主体代码

下面实现一个 Stonefold 风格的最小确定性网关：

# gateway_demo/gateway.py # 这是一个演示确定性网关思路的最小实现 import json from typing import Optional import jsonschema import yaml from fastapi import FastAPI, Header, HTTPException from pydantic import BaseModel app = FastAPI(title="Deterministic Agent Gateway Demo") def load_config(path: str = "gateway_config.yaml"): with open(path, "r", encoding="utf-8") as f: return yaml.safe_load(f) CONFIG = load_config() service_map = {} for svc in CONFIG["services"]: service_map[svc["name"]] = svc class AgentAction(BaseModel): intent: str service: str path: str payload: dict class Gateway: """所有 Agent 请求都先经过这个类做确定性校验。""" def __init__(self, config): self.config = config self.audit_log: list = [] def authorize(self, token: str) -> Optional[str]: for agent in self.config.get("agents", []): if agent["token"] == token: return agent["name"] return None def check_service_and_path(self, service_name: str, path: str) -> bool: service = service_map.get(service_name) if not service: return False for rule in service["paths"]: if rule["path"] == path: return True return False def validate_payload(self, service_name: str, path: str, payload: dict) -> Optional[str]: service = service_map.get(service_name) if not service: return "unknown_service" for rule in service["paths"]: if rule["path"] != path: continue schema_file = rule.get("schema_file") if not schema_file: return None with open(schema_file, "r", encoding="utf-8") as f: schema = json.load(f) try: jsonschema.validate(instance=payload, schema=schema) except jsonschema.ValidationError as e: return e.message return None return "path_not_found" def execute(self, action: AgentAction, agent_name: str) -> dict: # 真实项目中，这里应调用内部系统，并记录返回结果 return { "agent": agent_name, "service": action.service, "path": action.path, "payload": action.payload, "backend_result": "ok", } gateway = Gateway(CONFIG) @app.post("/agent/execute") async def agent_execute(action: AgentAction, authorization: str = Header(...)): token = authorization.removeprefix("Bearer ").strip() agent_name = gateway.authorize(token) if not agent_name: raise HTTPException(status_code=401, detail="invalid token") if not gateway.check_service_and_path(action.service, action.path): raise HTTPException(status_code=403, detail="service or path not allowed") error = gateway.validate_payload(action.service, action.path, action.payload) if error: raise HTTPException(status_code=422, detail=f"payload invalid: {error}") result = gateway.execute(action, agent_name) gateway.audit_log.append({ "agent": agent_name, "service": action.service, "path": action.path, "action": action.dict(), "decision": "allow", }) return {"decision": "allow", "result": result}

这段代码的逻辑顺序非常重要：先认证，再白名单，再 Schema 校验，最后才执行。任何一个环节失败，请求都不能到达后端。

这里我用audit_log内存列表表示审计日志。真实项目里，这一步应该持久化到 ClickHouse、Elasticsearch、PostgreSQL 或 S3 这类适合审计存储的系统。你可以看到，这个设计并不复杂，但它把“能不能调”和“怎么调”完全从模型推理里隔离出来了。

6. 用 curl 验证网关的放行与拦截

启动服务：

uvicorn gateway_demo.gateway:app --host 0.0.0.0 --port 8000

如果文件路径不在gateway_demo目录下，可在启动前调整配置文件路径。启动成功后，先发一个合法请求：

curl -X POST http://127.0.0.1:8000/agent/execute \ -H "Content-Type: application/json" \ -H "Authorization: Bearer demo-secret-token-123" \ -d '{ "intent": "创建一张100元的发票", "service": "invoice_service", "path": "/v1/invoices", "payload": { "customer_id": "C001", "amount": 100, "currency": "CNY" } }'

预期返回：

{ "decision": "allow", "result": { "agent": "billing-agent", "service": "invoice_service", "path": "/v1/invoices", "payload": { "customer_id": "C001", "amount": 100, "currency": "CNY" }, "backend_result": "ok" } }

这说明合法请求被成功放行。接着尝试访问一个不存在的服务：

curl -X POST http://127.0.0.1:8000/agent/execute \ -H "Content-Type: application/json" \ -H "Authorization: Bearer demo-secret-token-123" \ -d '{ "intent": "导出用户列表", "service": "user_service", "path": "/v1/users/export", "payload": {} }'

预期返回 403：

{ "detail": "service or path not allowed" }

这正是“拒绝默认”策略的效果。即使 Agent 有导出意图，如果配置里没有这个服务路径，网关也会拦截。

再试一个参数错误的请求：

curl -X POST http://127.0.0.1:8000/agent/execute \ -H "Content-Type: application/json" \ -H "Authorization: Bearer demo-secret-token-123" \ -d '{ "intent": "创建一张非法发票", "service": "invoice_service", "path": "/v1/invoices", "payload": { "customer_id": "C002", "amount": "abc", "currency": "CNY" } }'

预期返回 422。因为 Schema 里定义了amount必须是数字类型，而 Agent 传了字符串。这个校验就是确定性网关最关键的价值之一：它不假设 Agent 能生成正确的参数，而是假设 Agent 可能出错，然后用规则兜底。

如果你想让 Agent 在请求被拒绝后自我修正，可以把网关返回的错误信息拼回给 Agent，让模型看到“参数类型不匹配”后重新生成一次工具调用。这比直接让 Agent 面对一个封闭的后端错误更有效。

7. 把网关日志变成 AI Agent 评测的确定性地基

最近有个热门词叫“demystifying evals for AI agents”，意思是 AI Agent 评测并没有那么神秘，但很多团队不知道从哪里测起。如果你的 Agent 只是聊天机器人，评测可以看生成文本的相似度；但如果 Agent 会调用系统，评测就必须包含“工具调用行为”的断言。

Stonefold 这类确定性网关，天然为 Agent 评测提供了非常扎实的 ground truth。网关日志里记录了每次请求的完整决策，你不需要用另一个大模型去判断“这次 Agent 是否越权”，你用断言直接比对状态码和日志即可。

下面用pytest写一组基于网关接口的 eval 用例。它把评测从“感觉”变成了确定性的资产：

# tests/test_agent_evals.py from fastapi.testclient import TestClient from gateway_demo.gateway import app client = TestClient(app) HEADERS = {"Authorization": "Bearer demo-secret-token-123"} def test_allowed_invoice_creation(): response = client.post( "/agent/execute", json={ "intent": "创建一张100元的发票", "service": "invoice_service", "path": "/v1/invoices", "payload": { "customer_id": "C001", "amount": 100, "currency": "CNY", }, }, headers=HEADERS, ) assert response.status_code == 200 assert response.json()["decision"] == "allow" def test_unexpected_service_blocked(): response = client.post( "/agent/execute", json={ "intent": "导出所有用户", "service": "user_service", "path": "/v1/users/export", "payload": {}, }, headers=HEADERS, ) assert response.status_code == 403 assert response.json()["detail"] == "service or path not allowed" def test_wrong_schema_rejected(): response = client.post( "/agent/execute", json={ "intent": "创建一张非法发票", "service": "invoice_service", "path": "/v1/invoices", "payload": { "customer_id": "C002", "amount": "100", "currency": "CNY", }, }, headers=HEADERS, ) assert response.status_code == 422

这样一组用例跑完后，你的 Agent 评测就有两个层面：

• 模型层面：评估 Agent 是否选择了正确的服务、路径、参数。
• 系统层面：即使模型选择错误，网关是否成功拦截。

真正进入生产环境的 Agent，不应该只依赖“模型层面正确”。系统层面必须有一道确定性防线，而这道防线是否有效，完全可以用上面这种 eval 用例持续回归。

如果你的 Agent 评测还没跑起来，我建议从这三步开始：

1. 先定义 10 个最常见的高风险操作，例如删除、导出、改价、转账。
2. 为每个操作写一条 eval 用例，断言“如果没有授权，必须被网关拒绝”。
3. 把每条被拒绝的请求写入测试报告，形成 Agent 行为基线。

这条路径比给模型算一个“平均分”有价值得多。

8. 常见问题与排查思路

在实际落地确定性网关时，遇到的问题往往不在“好不好用”，而在“为什么我的请求被拒绝了”。这里整理一份高频问题对照表。

需要特别提醒：在真实系统中调整网关配置时，一定要先在测试环境验证，并做好配置备份。任何白名单变更都可能导致 Agent 功能从“可用”变成“不可用”，也可能打开一条原本不该打开的风险路径。

9. 生产落地建议与安全边界

Stonefold 这类确定性网关能不能跑好，不完全取决于功能，更多地取决于你如何设计规则和运营这套系统。下面这些建议是我在实际项目里见过的最有价值的做法。

9.1 默认拒绝，而不是默认放行

很多人写配置时，习惯只把允许的路径列出来，剩下的交给后端处理。这在 Agent 场景里风险很高。更安全的策略是默认拒绝：只有配置里明确列出的服务、路径、方法，才允许请求通过。这样即使模型出现了你完全没见过的调用，网关也不会放行。

9.2 规则入代码库，走评审流程

网关的规则不应该在运行时被随意修改，而应该以 YAML、JSON 或代码形式纳入版本管理。每次新增路径、放开权限，都要像修改业务代码一样做 Code Review。至少保证一条：谁改规则，谁负责解释这条规则对应的业务场景。

9.3 最小权限和独立身份

每个 Agent 使用独立的 Token 或身份标识。不要把多个 Agent 共用一个长期凭证。即使两个 Agent 都需要访问订单服务，一个只读订单，另一个需要创建售后单，那么它们的权限范围也应该分开。网关应该支持“身份 + 服务 + 路径 + 方法 + 参数规则”的多级权限控制。

9.4 响应也要做校验

确定性网关不仅管请求，也建议管响应。后端返回的数据可能包含敏感字段，或者体积过大。如果 Agent 被套入一个外部诱导场景，它可能把订单列表里的客户手机号返回给用户。网关在把后端响应交给 Agent 前，可以做字段脱敏、白名单过滤和体积限制。

9.5 幂等与重试策略

Agent 经常重试。一个创建发票的请求，如果因为网络超时被 Agent 重试两次，生产环境可能产生两张重复发票。网关应该支持幂等键检查：同一个 Agent、同一个业务操作、同一个幂等键，只能成功执行一次。这个能力在写场景非常重要。

9.6 审计日志要能支撑溯源

审计日志是确定性网关安全价值的一部分。每条日志至少包含请求 ID、Agent ID、目标服务、路径、完整 payload、决策结果、时间戳和关联的后端响应。日志保留周期要符合公司数据管理规范，并且建议做冷热分离，方便事故追查和合规审计。

9.7 用 fake 后端做测评

在测试环境里，不要直接连接生产数据库或真实供应商接口。搭建一层 fake backend，用它来验证网关逻辑，也用它来跑 Agent 评测。这样可以在不产生真实业务影响的情况下，验证 Agent 的“危险操作是否会被拦截”。

10. 结尾与下一步

Stonefold 给 AI Agent 工程化提供了一个很清晰的思路：想让 Agent 进入生产环境，不只要把模型调好，更要在模型和系统之间建立一个确定性边界。这个边界可以是 Stonefold，也可以是你自己写的十几行规则代码。关键不在于用哪个项目，而在于你是否愿意把“安全、权限、审计、错误校验”从模型能力中剥离出来，交给确定性的工程系统。

如果你正在团队里讨论“要不要给 Agent 加网关”，我建议你先别急着争论架构。找一个人，用最少代码把带身份认证、白名单路径和 Schema 校验的最小网关跑起来，再写一组 eval 用例圈住它。然后你再去对比 Stonefold 这类项目，会发现很多设计选择突然就说得通了。

真正的 AI Agent 工程化，不是让模型拥有越来越多权限，而是让模型在可控边界里发挥能力。边界定清楚了，Agent 才值得被信任。