Halro 的设计目标与边界

直接在每个应用里配置 Provider Key，初期最省事。随着项目和模型服务增加，凭据、模型权限、重试记录与成本归因会逐渐分散到不同 SDK、日志和账单中。

Halro 把这些职责放到业务应用与模型服务之间。应用只需要 Gateway Key 和公开模型别名；上游凭据、真实模型、预算、路由策略和调用证据由网关统一管理。

我们缺的不是又一个 SDK，而是一个放在业务系统与模型服务之间的本地控制边界。

预算检查必须发生在 Provider I/O 之前

Agent 会规划、调用工具、读取结果、继续推理。终止条件或重试逻辑出现问题时，一次用户操作可能产生多次模型调用。月底账单无法阻止正在发生的消耗。

所以，每一次调用在发出之前，就应该知道它属于哪个项目、允许用什么模型、还有多少预算；结束之后，Token、成本、错误和重试必须落进同一条可追溯记录。

Project 是治理边界

一个 Project 可以对应一个产品、一支团队、一个环境，或者一个独立的 Agent。只要边界划清楚，之后的 Token、成本、速率限制、预算与异常策略就都有了归属。

预算预留与保守结算

Halro 会在访问 Provider 之前执行鉴权、模型权限、限流与预算预留；请求结束后，再根据 Provider 返回的真实 Usage 结算。如果网络中断造成不确定结果，它不会把未知当成零，而会按允许的最大输出保守结算。

Token Guard 进一步按单请求 Token、每分钟成本、并发、错误率与历史基线发现异常。我们推荐先观察，再告警，最后才在误报可接受时启用临时封禁。

部署形态与安全职责

Halro 是一个 Go 单二进制，React 管理后台直接嵌入其中。运行时不要求 PostgreSQL、Redis、CDN 或独立前端服务。但凭据加密、Gateway Key 哈希、预算预留、审计完整性、安全出站与失败语义，都不能因为部署轻量而被省略。

Halro 不是什么

它不是 Agent 编排平台，也不把工作流、记忆、工具执行和评测塞进网关。Halro 只负责模型访问前后那条边界：身份、授权、预算、路由、用量、证据、审计和失败语义。

当前 Halro 仍是 Standalone 单写实例，也不宣称支持 Realtime WebSocket / WebRTC。边界写清楚，比在功能清单里模糊过去更重要。