全链路 filter 参数协议与兼容性问题：格式混乱、AST转换缺失、属性污染、命名不统一

[hotlong]

概述

本 issue 合并报告了 objectstack-ai/spec 中发现的所有 filter 参数相关协议和兼容问题，建议统一整改。

---

问题1：filter/filters/$filter 参数命名混乱（协议/实现/客户端不一致）

• HTTP Protocol 文档要求 filter（单数）作为 JSON 查询参数，API Reference 用 $filter，Client SDK 实际用的是 filters（复数）。
• 服务端 protocol.ts 同时兼容 filter/filters 字段，存在混用、处理混乱风险。

建议： 尽快统一 filter ���数命名，建议全部采用 filter（单数），支持向后兼容。文档、SDK、协议、Dispatcher/Adapter 层都要同步。

---

问题2：AST 数组格式 filter → FilterCondition 对象转换缺失

• Client SDK、query-builder 产出的 filter 带数组 AST 结构：如 ["and", ["priority", "=", "high"], ...]，服务端 protocol.ts 直接用 JSON.parse 赋值，底层 engine 期待收到对象格式（如 { $and: [...] }）。
• Dispatcher 层与 Broker 传递格式不一致，filter 易丢失或无法生效。

建议： Server 层需增加 AST 数组格式的转换处理（如自动兑现为 FilterCondition 对象 { $and: [...] }）；SDK 需输出规范格式。

---

问题3：Dispatcher handleApiEndpoint 响应属性名不匹配

• eg: find 操作返回 result.data 和 result.count，但 engine 返回的是 { object, records, total }。结果字段总是 undefined，统计数丢失。

建议： Dispatcher 层需统一处理返回体，严格按照 Spec Contract 进行字段映射。

---

问题4：GET by ID 参数污染风险

• eg: GET /data/:object/:id 会将所有 URL 查询参数 ...query 展开到 data.get 调用中，实际只需要 select/expand 等少量字段，容易引入未知参数。

建议： 限制只传递 select/expand 等允许参数，其余参数丢弃。

---

问题5：isFilterAST 检测不严谨/易误判

• Client SDK isFilterAST 方法只判断 Array.isArray，无法区分合法 AST 与错误数组。误传数组会被错误处理。

建议： 采用更精确 AST 检测方案，或通过 schema 校验。

---

建议整改细节

• 同步所有相关协议、实现、测试和文��中的 filter 格式，统一命名和支持格式。
• 完善 server-side AST 数组格式处理，对 filter/filters 参数加入安全转换。
• Dispatcher 层严格字段验证与映射。
• Client SDK filter 结构校验与构建辅助。
• 增加测试覆盖率，覆盖所有 format/命名/AST 转换的边界场景。

---

代码片段举例

1. Dispatcher GET List：

const result = await broker.call('data.query', { object: objectName, query }, ...);

2. Dispatcher APIEndpoint find：

const result = await broker.call('data.query', { object, query }, ...);
// result.data 实实际应该是 result.records

3. Client SDK isFilterAST：

return Array.isArray(filter); // 仅此判断

---

影响范围

• 数据 API 列表筛选、复杂筛选
• 子协议定制、批量操作、聚合等
• 所有涉及 filter 参数的 REST API 和 SDK 通用层

---

请优先安排规范整改与单元测试覆盖更新

如需英文 issue 或细节补充请告知。