bounded-backend

有界后端

Bounded 应用的服务端：管理已记录支持的变更界面的策略、运行时强制执行的不变量、运行可信代码的函数，以及决定当前操作者的角色模型。 bounded deploy 会验证、编译并推送；运行时规则和不变量检查会在已记录支持的变更界面上，于提交前拒绝违规操作。使用具体的策略测试（bounded tests run）和部署来检查策略。不要将此覆盖范围泛化到不受支持的平面、未记录的存储路径或继承语料库。关于 CLI/部署，请参阅 bounded-deploy 技能；关于客户端 SDK 和身份验证 UI，请参阅 bounded-frontend；要在整个系列中选择路由，请参阅根目录下的 bounded 技能。

从一开始就牢记角色模型：编写规则前，先弄清楚 @user 是谁、函数以哪个主体身份执行（runAs/actAs），以及授权来自何处（@origin）。

参考路由器

正在构建五种最常见应用形态之一？请走快捷路径——每种构建对应一个目标页面——而不是浏览此表。否则，只阅读与当前任务或术语相匹配的行。

任务或术语	阅读
一屏了解语法：字段类型、层级、变量、运算符、逻辑放在哪里	策略速查表
根据应用描述生成或修复策略	策略生成
按意图分类的完整策略示例（市场、托管交易、金库、质押、代币等）	示例索引
多集合策略详解（团队 SaaS、市场、实时游戏）	示例
规则配方：仅所有者、管理员或所有者、成员资格、时间窗口、验证、不可变字段、原子批次	访问模式
在规则中要求或复制用户已验证的 X 账号，get(/__connections__/@user.id).xHandle，测试已关联 X 的规则、关联前输入的账号名、链上应用	已连接账号
规则、字段、表达式、@user、@data、@newData、@time、get()、getAfter()、所有权字段	策略参考
上限、余额、供应量、租户隔离、硬性边界；rollingSum、windowSum、flowBound、conserve、tenantTag、tenantEdge、bound	不变量
趋势动态、排行榜、排名式 windowSum 读取	趋势动态
浏览器 CSP／限制应用页面可访问的内容	浏览器边界
常量、可复用规则、@const、@def	常量和定义
选择规则、不变量、钩子或函数	何时使用函数
函数；声明、auth、entry、secrets、actAs、ctx.user、ctx.bounded、ctx.env、ctx.secrets、调用、部署	函数
公共函数：无需 Bounded 会话的 HTTP 路由，位于 <slug>-api.bounded.page，public、methods、cors、公共 JWKS、机器调用方、Webhook 和浏览器公共模式	公共函数
ctx.ai.run、ctx.ai.generateImage、ctx.ai.generateVideo、getJob、无需 API 密钥的 AI	ctx.ai
ctx.services、托管第三方 API、bounded services	ctx.services
ctx.browser、函数中的无头浏览器、以登录状态驱动自己的应用、@const.AGENT、Agent 身份	ctx.browser
ctx.enqueue、后台任务、队列、重放身份	ctx.enqueue
ctx.build、发起受治理应用构建的函数、图像和视频构建、mediaSlots	ctx.build
从简单方案开始，逐步过渡到函数	函数进阶
用户自有的提供商 API 密钥	密钥
计划任务、dueRows、钩子、Webhook、verifyWebhook	计划钩子和 Webhook
无需完整扫描的周期性舰队扫描	计划扫描
反作弊证明限制	钩子和反作弊
原子写入、子集攻击、requiresInBatch、incomplete_batch	数据平面
查询、分页、queryAggregate、count、筛选器、缺失与 null 的区别、$exists、排序、游标	查询
文件、setFile、存储、全文搜索	文件和搜索
实时房间；session.tick、settleTo、settleFrom、战争迷雾视图	实时功能和游戏
原生实时模块；session.live、tick、views、@effect、live.intent	实时运行时
输入频率、插值、预测	实时网络代码
AI NPC／AI 玩家	AI NPC
长时间运行的后端运行时或托管服务	后端运行时
多步骤 Flue Agent	Flue Agent
所有者、协作者、范围受限的管理员	管理员和所有权
顶层 roles、members、read:"*"、读写范围	角色
access、自定义／外部角色、__owners__、__admins__、__developers__、__viewers__	访问控制 · 身份和日志
服务密钥、付款机器人、后端身份、runAs、actAs、@origin、ctx.origin	服务密钥 · 主体和来源
具体的允许／拒绝测试；policy-tests/*.json、bounded tests run/push/list/pull	策略测试
已认证应用的端到端测试	已认证应用测试
完成审查	质量检查清单
面向 Agent 或仅限后端的应用	为 Agent 构建 · 构建后端

错误路由

错误/状态	含义
403	写入或函数调用未通过规则检查。请检查身份验证、所有权、角色或函数 auth。被拒绝的读取会以数据为空的 200 响应隐藏，而不是返回 403。
500 rule_evaluation_failed	已执行到规则，但无法完成评估——没有规则拒绝你，也没有读取或写入任何内容。这不是拒绝，也不是可重试的冲突。请阅读 bounded decisions 了解原因；该行会记录为 decision: error。
409 + 不变量名称	该事务会违反不变量。请修正状态或策略。
403 incomplete_batch	集合的 requiresInBatch 声明列出了原子批次中缺失的配套路径。请提交完整的 setMany。
部署验证错误	部署在发生任何更改之前拒绝了该策略。请根据错误消息修正策略语法、字段类型、层级/不变量配对、常量或表达式用法。

经验法则

• 对于常规所有权和成员资格检查，请使用 @user.id；仅在钱包/链上语义中使用 @user.address。

• 被拒绝的读取会返回空数据的 200 响应。在策略测试的 expect 中使用 get()，会跳过读取规则并读取沙盒状态，因此要证明读取被拒绝，请使用第二个真实会话。写入和删除被拒绝时，仍使用 shouldFail。

• 固定总量使用 conserve，时间范围内的上限使用 rollingSum，每个分区的累计流出量 ≤ 流入量使用 flowBound；当正确性涉及多次写入时，使用一次原子的 set-many。

• 当某次写入在没有配套写入的情况下无效时，请声明 requiresInBatch，以免恶意客户端只提交单独有效的子集。

• 将服务提供商 API 密钥存放在 Bounded secrets 中，不要放在前端代码里。

• 编写规则前，请明确执行主体：函数的 runAs/actAs 和 @origin 决定了 @user 的身份，以及调用是否获得授权。

• 对于经过身份验证的应用操作，请使用客户端 SDK 的 functions.invoke，声明函数的 auth 规则，并使用 ctx.user。不要在函数参数中发送 Bounded 会话令牌，也不要在公开 HTTP 函数中构建 JWT 验证器。请将有意公开的数据（例如今日提示词）放在独立的公开函数中，并确保该函数无法访问用户状态。

• 请以非所有者用户验证私有函数流程；如果应用支持访客，也要包含匿名会话。保存状态后重新加载并恢复；所有者 CLI 调用可能会掩盖数据读取权限失败。读取被拒绝时可能表现为数据缺失，因此在重新创建状态或放宽规则之前，请先排查授权问题。