Skip to content

fix(data-aisa): 命令与 schema 描述只讲客户口径,不写服务端实现 - #75

Merged
KevinZhang19870314 merged 1 commit into
mainfrom
fix/data-aisa-customer-facing-wording
Nov 4, 2026
Merged

KevinZhang19870314 merged 1 commit into
mainfrom
fix/data-aisa-customer-facing-wording

Conversation

@KevinZhang19870314

Copy link
Copy Markdown
Collaborator

data 域的命令描述与 verb-schema 声明是对接方与 agent 直接读到的文本,
此前有几处在讲服务端怎么实现,而不是调用方该怎么用。

改了什么

六处 answered from the bundled index, no upstream call → Free and read-only.:

  • data-aisa/list-categories.ts、search.ts、describe.ts 的 .description()
  • verb-schema.ts 的 dataListCategoriesSchema / dataSearchSchema / dataDescribeSchema

「免费」是调用方要知道的(决定调用顺序与预算),「答案来自内置索引、不发上游请求」
是我们的实现方式 —— 换了实现这句就得改,而调用方的用法一个字都不用变。

另两处:

  • dataSearchSchema.keyword 的 constraints:matched against the capability index (identifier, summary, tags) → matched against capability identifiers, summaries and tags。保留「匹配哪些字段」(拼关键词时要用),去掉 index 这个实现概念。
  • dataQuerySchema 的 idempotency-key:删掉 de-duplication falls back to the result cache。这句除了暴露缓存,还有个更实际的毛病 —— 它暗示重发会被去重,
    而计费规则是重发照常计费,两边自相矛盾。改为只说做法
    (Pass the same key when retrying the same params.),不承诺去重效果。

没动的地方

出行域的 no upstream call / local_cache 保持原样:前者是在告知「读的是本地
订单、未查供应商」,后者是 source 字段的真实返回值、属契约本身,调用方要
据此判断数据新鲜度。两者都与定价无关。

版本

@agenzo/merchant-cli 0.10.1 → 0.10.2(patch:纯描述文本,无行为变更、无 flag 增减)。

验证

  • npm run type-check → 退出码 0
  • npm run test → 66 个测试文件 / 1007 passed(含 data-aisa.test.ts 18 项)
  • npm run build → 五个包全部 Build success

data 域的命令描述与 verb-schema 声明是**对接方与 agent 直接读到的文本**,
此前有几处在讲服务端怎么实现,而不是调用方该怎么用。

## 改了什么

六处 `answered from the bundled index, no upstream call` → `Free and read-only.`:

- `data-aisa/list-categories.ts`、`search.ts`、`describe.ts` 的 `.description()`
- `verb-schema.ts` 的 `dataListCategoriesSchema` / `dataSearchSchema` / `dataDescribeSchema`

「免费」是调用方要知道的(决定调用顺序与预算),「答案来自内置索引、不发上游请求」
是我们的实现方式 —— 换了实现这句就得改,而调用方的用法一个字都不用变。

另两处:

- `dataSearchSchema.keyword` 的 constraints:`matched against the capability index
  (identifier, summary, tags)` → `matched against capability identifiers, summaries
  and tags`。保留「匹配哪些字段」(拼关键词时要用),去掉 index 这个实现概念。
- `dataQuerySchema` 的 `idempotency-key`:删掉 `de-duplication falls back to the
  result cache`。这句除了暴露缓存,还有个更实际的毛病 —— 它暗示重发会被去重,
  而计费规则是**重发照常计费**,两边自相矛盾。改为只说做法
  (`Pass the same key when retrying the same params.`),不承诺去重效果。

## 没动的地方

出行域的 `no upstream call` / `local_cache` 保持原样:前者是在告知「读的是本地
订单、未查供应商」,后者是 `source` 字段的**真实返回值**、属契约本身,调用方要
据此判断数据新鲜度。两者都与定价无关。

## 版本

`@agenzo/merchant-cli` 0.10.1 → 0.10.2(patch:纯描述文本,无行为变更、无 flag 增减)。

## 验证

- `npm run type-check` → 退出码 0
- `npm run test` → 66 个测试文件 / 1007 passed(含 `data-aisa.test.ts` 18 项)
- `npm run build` → 五个包全部 Build success
@KevinZhang19870314
KevinZhang19870314 merged commit 2be4a70 into main Nov 4, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant