错误与校验

返回 Err(ActionError)，Agent 收到的就是一个带固定错误码的结构化错误，而不是一段还得靠它自己解析的文字。

构造函数	含义
ActionError::field(name, msg)	某个字段不合法
ActionError::validation([(f, e), …])	一次性报告多个字段——表单场景优先使用
ActionError::action_not_available()	当前状态下不可调用
ActionError::blocked_by_modal()	此刻输入被某个模态占用
ActionError::window_not_found()	目标窗口已不存在
ActionError::action_timeout()	操作耗时过长
ActionError::stale_state(version)	调用方的 expectedVersion 已过期
ActionError::custom(code, msg)	固定错误码集合内的其他情况

一次性报告全部问题

// Shared by the on-screen notice and the error path, so they never disagree.
fn problems(&self) -> Vec<(&'static str, &'static str)> {
    let mut out = Vec::new();
    if self.recipient.is_empty() { out.push(("recipient", "required")); }
    if self.amount <= 0          { out.push(("amount", "must be positive")); }
    out
}

// In the handler:
let problems = this.problems();
if !problems.is_empty() {
    return Err(ActionError::validation(problems));
}

提示

让界面上的 notice 内容块和返回的错误都来自同一个 problems() 方法。这样人和 Agent 永远不会看到两种结论。

你很少需要自己构造 stale_state

Purview 会在你的处理器运行之前自行校验 expectedVersion——参见开箱即得的协议行为。这个构造函数只留给一种少见的情况：你自己的业务逻辑发现了投影无法察觉的冲突。