Pling 是什么，不是什么
设想一个订单页面，上面并排放着「通过」和「拒绝」两个按钮。人一眼就能看出区别。DOM 只会告诉 Agent 这里是两个按钮，截图只会告诉它按钮的位置。仅凭这些，Agent 仍不知道每个按钮对应哪项业务操作、当前用户能否执行、是否需要确认，以及操作会影响哪张订单。
Pling 处理的就是这段缺失的信息。
一句话定义
Pling 是面向 Web 应用的 Agent 能力层。 页面在业务代码旁声明一次可执行的操作，Pling 将动作、作用对象、有界上下文和执行结果提供给页面内助手，或经 Agent Surface 提供给外部 Agent。
页面仍然是应用本身。状态、校验、业务规则和访问决策由应用掌握。Pling 只规定应用如何描述自己愿意开放的动作，以及一次执行应如何被报告。
模型、Agent runtime 和浏览器自动化工具都不属于这一层。Pling 不决定 Agent 下一步应该做什么。
一次操作涉及哪些职责
这些职责经常被统称为“Agent”。拆开之后，各自能做什么、不能做什么会清楚很多。
| 职责 | 它决定什么 | 典型实现 |
|---|---|---|
| 宿主应用 | 在这个业务系统里，什么是真实的、合法的、被允许的 | Vue、React、原生 JavaScript 或 jQuery 应用及其后端 |
| Pling SDK 与页面运行时 | 有哪些动作，作用于哪条记录，当前是否可用，执行后发生了什么 | @plingjs/core、@plingjs/dom 与框架适配器 |
| 页面内助手（可选） | 下一步做什么，如何回复用户 | @plingjs/agent 与应用选择的助手界面 |
| Agent Surface | 外部 Agent 可以发现什么、调用什么 | 页面侧的 Surface 实现 |
| Surface 规范 | 独立实现之间必须遵守哪些共同规则 | pling.surface/0.1，当前为公开草案 |
| 外部 Agent runtime | 是哪个 Agent、模型或客户端在操作页面 | 用户自己的 Agent、另一个应用或浏览器扩展 |
这些职责可以由同一个产品一起提供，但不能互相替代。页面内助手只是其中一种客户端；定义 Pling 的是页面上的能力声明。
页面向 Agent 提供什么
对每个已声明的动作，Pling 提供 Agent 做决策所需的信息：业务含义、作用对象、当前可用性、确认要求，以及执行后的结果。
页面还可以按需提供相关记录、只读状态、校验信息和反馈。这个视图是刻意收窄的。Agent 不会收到整棵 DOM、整个前端 store 或全部后端字段。结构化且有限的信息更容易判断，也能减少无关数据和敏感数据进入模型上下文。
敏感值可以在页面保留真实内容，同时以掩码或引用形式提供给模型。例如，模型可以引用某位客户，但不需要知道完整证件号。
声明不是第二套业务实现
Agent 调用一个动作时，页面执行的是用户本来就会触发的同一个 handler、同一套校验和同一次状态转换。声明只描述入口和约束，不复制业务逻辑。
执行结果也不能停留在“完成”。它应当说明执行了哪个动作、作用于哪个目标、成功还是失败、页面随后观察到了什么，以及是否经过确认或人工接力。只有这样，助手或审计系统才能区分“已经执行”和“曾经尝试”。
没有声明的动作
没有声明的动作不属于页面能力面。页面内助手不能通过选择器寻找一个相似按钮，也不能根据截图猜测并补上兜底路径。
没有声明
→ 不在能力面中
→ 页面内助手不能调用
→ 不退回选择器或截图猜测这条规则有明确边界。拥有浏览器级权限的外部 Agent，例如通过 Chrome DevTools Protocol 操作页面的 Agent，仍然可以在 Pling 契约之外与页面交互。那是另一种权限边界，Pling 不声称能够阻止所有浏览器自动化。
无论是否经过 Pling，后端都保留最终授权责任。页面能证明 approve_order 这个动作存在，不能仅凭页面证明某位用户此时有权批准某个金额。
一份声明，两种客户端
应用可以在自己的界面中提供助手，也可以经 Agent Surface 把同一组声明开放给用户的外部 Agent。这是同一套页面模型的两种使用方式，不是两套独立接入。
页面内助手适合希望直接提供完整体验、又不要求用户安装软件的应用。外部 Agent 适合用户已经拥有自己的 Agent，并希望它按照应用规定的条件工作。更换客户端不应要求重新声明整个页面。
它不替代什么
Pling 不是模型，不提供推理或提示词管理；不是 Vue、React 等前端框架的替代品；也不是基于选择器的浏览器自动化工具。
它不替代后端授权、限流、租户隔离、密钥管理、工作流系统或人工复核。这些系统回答的是不同问题。Pling 让页面侧的契约变得明确，但不会把所有安全决定压缩进页面。
对于无法接入的第三方页面，浏览器自动化或视觉交互仍可能是实际选择。Pling 面向的是另一种情况：页面所有者能够声明页面做什么，以及 Agent 可以在什么条件下执行。
当前可以依赖的能力
当前 SDK 支持能力声明、目标解析、执行和结果反馈。参考实现同时提供页面内助手与外部 Surface 客户端。
pling.surface/0.1 仍是公开草案。它已经发布，供实现者比较和评审，仍可能变化。Pling 目前不是跨厂商标准，文档也不会把它描述成已经确立的标准。
现阶段可以确认的范围更窄：接入后的页面能够向 Agent 暴露一组有界的业务动作，通过页面执行这些动作，并返回结果。是否适合生产环境，还取决于应用自身的授权、数据和运维边界。
继续阅读
要理解声明、同意、委托和审计之间的关系，请阅读信任、授权与审计。
要开始接入应用，请从 Vue 快速上手 或 React 快速上手 开始。概念在各适配器之间一致，接入方式不同。