openany-cli-dev 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +23 -13
  2. package/package.json +1 -1
  3. package/skills/openany/calls.md +1 -1
  4. package/skills/openany/setup.md +88 -78
  5. package/skills/openany/topups.md +2 -2
  6. package/skills/openany-provider/SKILL.md +13 -5
  7. package/skills/openany-provider/SKILL.zh-CN.md +13 -5
  8. package/skills/openany-provider/references/apis.md +7 -5
  9. package/skills/openany-provider/references/apis.zh-CN.md +6 -4
  10. package/skills/openany-provider/references/application.md +2 -2
  11. package/skills/openany-provider/references/application.zh-CN.md +2 -2
  12. package/skills/openany-provider/references/connections.md +9 -9
  13. package/skills/openany-provider/references/connections.zh-CN.md +8 -8
  14. package/skills/openany-provider/references/hermes-files.md +131 -0
  15. package/skills/openany-provider/references/imports.md +5 -3
  16. package/skills/openany-provider/references/imports.zh-CN.md +5 -3
  17. package/skills/openany-provider/references/login.md +3 -3
  18. package/skills/openany-provider/references/login.zh-CN.md +3 -3
  19. package/skills/openany-provider/references/model-import.md +1 -1
  20. package/skills/openany-provider/references/model-import.zh-CN.md +1 -1
  21. package/skills/openany-provider/references/models.md +11 -9
  22. package/skills/openany-provider/references/models.zh-CN.md +8 -6
  23. package/skills/openany-provider/references/publishing.md +9 -5
  24. package/skills/openany-provider/references/publishing.zh-CN.md +9 -7
  25. package/skills/openany-provider/references/reviews.md +4 -2
  26. package/skills/openany-provider/references/reviews.zh-CN.md +2 -0
  27. package/skills/openany-provider/templates/bindings.json +1 -1
  28. package/skills/openany-provider/templates/models-v2.json +12 -12
  29. package/skills/openany-provider/templates/models.json +2 -2
  30. package/skills/openany-provider/templates/provider-agent-api-template.json +13 -13
  31. package/skills/openany-provider/templates/seller-agent-api-import-template.json +17 -17
  32. package/src/cli.js +15 -4
  33. package/src/http.js +7 -0
  34. package/src/poll-artifacts.js +77 -0
  35. package/src/provider-api-import-v2.js +1 -1
  36. package/src/provider-connections.js +2 -2
  37. package/src/provider-import-format.js +5 -5
  38. package/src/provider-imports.js +6 -5
  39. package/src/provider-model-import-v2.js +10 -1
  40. package/src/provider-models.js +3 -3
  41. package/src/provider-state.js +31 -14
  42. package/src/provider.js +9 -3
  43. package/src/seller-fields.js +57 -0
@@ -2,6 +2,8 @@
2
2
 
3
3
  先完成入口检查和[连接流程](connections.zh-CN.md),再收集资料。已有导入草稿时,从第 2 步使用返回的 `resourceId` 继续。
4
4
 
5
+ 按[主入口](../SKILL.zh-CN.md)的表单优先规则收集缺少的 API 字段,以及需要补充的测试或发布确认。
6
+
5
7
  ## 1. 准备并创建
6
8
 
7
9
  ```bash
@@ -9,7 +11,7 @@ openany-dev seller schema --type api --application APPLICATION_ID -j
9
11
  openany-dev seller apis create --application APPLICATION_ID --file api.json --operation TASK-api-create-1 -j
10
12
  ```
11
13
 
12
- 按当前 schema 准备 `api.json`,包括当前供应商拥有的 `upstreamKeyId`、`name`、`description`、`method`、`pathTemplate`、`requestContentType` 和 `config`。保留实际计费、请求参数、映射和扣费条件,只补缺项。`price_micro_usd` 等金额使用微美元字符串。连接负责注入凭据。记录返回的 `id` 为 `API_ID`。
14
+ 按当前 schema 准备 `api.json`,包括当前供应商拥有的 `connectionId`、`name`、`description`、`method`、`pathTemplate`、`requestContentType` 和 `config`。保留实际计费、请求参数、映射和扣费条件,只补缺项。`price_micro_usd` 等金额使用微美元字符串。连接负责注入凭据。记录返回的 `id` 为 `API_ID`。
13
15
 
14
16
  ### 资源分类
15
17
 
@@ -17,7 +19,7 @@ openany-dev seller apis create --application APPLICATION_ID --file api.json --op
17
19
 
18
20
  ## 2. 使用已保存的配置
19
21
 
20
- 使用创建或导入回执确认草稿 ID。只建草稿时,报告 ID 后结束。验证需要 `id`、`revision`、`upstreamKeyId` 和 `upstreamRevision`,回执缺少当前步骤所需字段时才回读一次。
22
+ 使用创建或导入回执确认草稿 ID。只建草稿时,报告 ID 后结束。验证需要 `id`、`revision`、`connectionId` 和 `connectionRevision`,回执缺少当前步骤所需字段时才回读一次。
21
23
 
22
24
  ```bash
23
25
  openany-dev seller apis get --application APPLICATION_ID --id API_ID -j
@@ -27,7 +29,7 @@ openany-dev seller apis get --application APPLICATION_ID --id API_ID -j
27
29
 
28
30
  判断回执是否验证了当前配置时,核对 `state: "passed"`、`stale: false`,以及 API ID、修订、连接 ID 和连接修订是否一致。发布资格另按下文的历史验证规则判断。先核实运行中或结果不明的验证。确实需要新验证且测试请求和费用范围已获授权时,只运行一次。
29
31
 
30
- 用当前 `revision`、`upstreamRevision` 填写 `verification.json` 的 `expectedRevision`、`expectedUpstreamRevision`,并提供获授权的 `request`。连接负责注入凭据。
32
+ 用当前 `revision`、`connectionRevision` 填写 `verification.json` 的 `expectedRevision`、`expectedConnectionRevision`,并提供获授权的 `request`。连接负责注入凭据。
31
33
 
32
34
  ```bash
33
35
  openany-dev seller apis verify --application APPLICATION_ID --id API_ID --file verification.json --operation TASK-api-test-1 -j
@@ -38,7 +40,7 @@ openany-dev seller apis get --application APPLICATION_ID --id API_ID --verificat
38
40
 
39
41
  ## 4. 发布
40
42
 
41
- 供应商为 `live` 且已获发布授权后才发布。用当前保存的 API 和连接修订填写 `expectedRevision` 与 `expectedUpstreamRevision`。首次发布或发布异步 API 时,服务端要求该 API 有成功验证。可复用匹配的成功回执,或服务端返回的 `passedVerificationId`。引用历史回执时仍使用当前修订。已发布的同步 API 满足服务端检查时可以直接重新发布。引用回执时填入 `verificationId`。发布无需单独提交资源审核。
43
+ 供应商为 `live` 且已获发布授权后才发布。用当前保存的 API 和连接修订填写 `expectedRevision` 与 `expectedConnectionRevision`。首次发布或发布异步 API 时,服务端要求该 API 有成功验证。可复用匹配的成功回执,或服务端返回的 `passedVerificationId`。引用历史回执时仍使用当前修订。已发布的同步 API 满足服务端检查时可以直接重新发布。引用回执时填入 `verificationId`。发布无需单独提交资源审核。
42
44
 
43
45
  ```bash
44
46
  openany-dev seller apis publish --application APPLICATION_ID --id API_ID --file publication.json --operation TASK-api-publish-1 -j
@@ -6,7 +6,7 @@ Complete login as described in the [main entry](../SKILL.md) before collecting a
6
6
 
7
7
  When the user asks to become a supplier or submit a supplier application, collect missing application information using the agent's **native interactive question/form tools**, such as the available `request_user_input_async`, `request_user_input` when available in the current mode, or `AskUserQuestion`. Do not substitute a plain-text questionnaire or ask users to write application JSON. Use the user's language, reuse supplied answers, and read the contact email from the intended signed-in account. Ask only for missing or invalid values and outstanding confirmations. Respect tool question limits by splitting the same field set into small groups; do not add fields. If the current mode has no native form tool, explain the limitation and fall back to local stdin under the rules above, collecting and validating the same fields. Do not claim a form was shown.
8
8
 
9
- After sending an asynchronous form, wait for the user's answers. An accepted response from the tool, a preselected option, silence, or a timeout is not an answer. Group independent missing fields within tool limits to reduce back-and-forth; do not ask again for supplied fields or explicit consent.
9
+ After sending an asynchronous form, wait for the user's answers without repeating the questions in chat. An accepted response from the tool, a preselected option, silence, or a timeout is not an answer. Group independent missing fields within tool limits to reduce back-and-forth; do not ask again for supplied fields or explicit consent.
10
10
 
11
11
  The website supplier application form defines the allowed field set:
12
12
 
@@ -28,7 +28,7 @@ Do not add questions about company registration, phone, address, prices, currenc
28
28
 
29
29
  Always write `seller_types` explicitly: models only → `["model"]`; APIs only → `["api"]`; both → `["model", "api"]`. Do not omit the field (the backend defaults to APIs only for legacy applications), copy template defaults, or infer the sales types from `resource.type`, documentation format, or the fact that models are also called through HTTP APIs. Before submission, check that the array matches the user's original choice and show the types in the summary. Do not reconfirm an already explicit choice. If the receipt includes `providerTypes`, check that they match; report and investigate a mismatch rather than resubmitting.
30
30
 
31
- After collecting form answers, validate required fields, formats, category choices, and required consents against the website application form. If validation fails, use the agent's native form to supplement or correct only the affected fields. Once all validation passes, construct `registration.json` internally using the website form mapping. For new applications, derive `resource.name` from the supplier name; set `resource.type` to `model` for Models only, otherwise `service`; set `resource.secondary_categories: []`, `connection.authentication: {"type":"none"}`, and `endpoints: []`. These are application request defaults, not extra user fields, and do not imply that future upstream access requires no authentication. Do not request or invent API credentials. If the current application contract rejects these fields/defaults, or category choices cannot be determined, report and resolve the inconsistency instead of expanding the form or guessing.
31
+ After collecting form answers, validate required fields, formats, category choices, and required consents against the website application form. If validation fails, use the agent's native form to supplement or correct only the affected fields. Once all validation passes, construct `registration.json` internally using the website form mapping. For new applications, derive `resource.name` from the supplier name; set `resource.type` to `model` for Models only, otherwise `service`; set `resource.secondary_categories: []`, `connection.authentication: {"type":"none"}`, and `endpoints: []`. These are application request defaults, not extra user fields, and do not imply that future service access requires no authentication. Do not request or invent API credentials. If the current application contract rejects these fields/defaults, or category choices cannot be determined, report and resolve the inconsistency instead of expanding the form or guessing.
32
32
 
33
33
  When the user has requested submission and both required consents have been provided, execute the creation command below. Report the returned application ID and review status, then stop. Submission does not mean approval or authorization to create, test, or publish resources.
34
34
 
@@ -8,7 +8,7 @@
8
8
 
9
9
  当用户要求申请成为供应商或提交供应商申请时,使用 Agent 的**原生交互式提问/表单工具**(例如当前可用的 `request_user_input_async`、当前模式可用的 `request_user_input` 或 `AskUserQuestion`)收集缺失的申请信息。不要用纯文本问卷替代,也不要要求用户编写申请 JSON。使用用户的语言,复用已提供的答案,并从目标已登录账号读取联系邮箱。只询问缺失或无效的值,以及尚未完成的确认。遵守工具的提问数量限制,将同一组字段分成若干小组询问;不要增加字段。如果当前模式没有可用的原生表单工具,说明限制并按上述规则回退到本地 stdin,仍按相同字段收集和校验;不要声称已经展示表单。
10
10
 
11
- 异步表单发出后必须等待用户答案;工具返回 accepted、预选项、沉默或超时都不代表回答。按工具限制合并独立的缺失字段,减少来回;已给出的字段和明确同意不重复询问。
11
+ 异步表单发出后等待用户作答,期间不在对话里重复提问。工具返回 accepted、预选项、沉默或超时都不代表回答。按工具限制合并独立的缺失字段,减少来回;已给出的字段和明确同意不重复询问。
12
12
 
13
13
  网站供应商申请表就是允许收集的字段清单:
14
14
 
@@ -30,7 +30,7 @@
30
30
 
31
31
  必须显式写入 `seller_types`:仅模型 → `["model"]`;仅 API → `["api"]`;两者 → `["model", "api"]`。不得遗漏该字段(后端兼容旧申请时会默认仅 API),不得照抄模板默认值,也不得从 `resource.type`、文档格式或“模型也通过 HTTP API 调用”反推销售类型。提交前核对数组与用户原始选择一致,在摘要中展示类型;已有明确选择不重复确认。回执包含 `providerTypes` 时核对是否一致,若不一致先报告并核实,不重复提交。
32
32
 
33
- 收集表单答案后,先按网站申请表校验必填项、格式、分类选项及必要同意项;校验不通过时,仅通过 Agent 原生表单补充或修正对应字段。校验全部通过后,按照网站申请表的映射在内部构造 `registration.json`。对于新申请,由供应商名称生成 `resource.name`;仅选择 Models 时将 `resource.type` 设为 `model`,否则设为 `service`;设置 `resource.secondary_categories: []`、`connection.authentication: {"type":"none"}` 和 `endpoints: []`。这些是申请请求数据的默认值,不是额外的用户字段,也不表示未来访问上游服务无须认证。不要索取或编造 API 凭据。如果当前申请接口约定拒绝这些字段/默认值,或无法确定分类选项,应报告并解决不一致问题,不要扩展表单或猜测。
33
+ 收集表单答案后,先按网站申请表校验必填项、格式、分类选项及必要同意项;校验不通过时,仅通过 Agent 原生表单补充或修正对应字段。校验全部通过后,按照网站申请表的映射在内部构造 `registration.json`。对于新申请,由供应商名称生成 `resource.name`;仅选择 Models 时将 `resource.type` 设为 `model`,否则设为 `service`;设置 `resource.secondary_categories: []`、`connection.authentication: {"type":"none"}` 和 `endpoints: []`。这些是申请请求数据的默认值,不是额外的用户字段,也不表示未来访问服务服务无须认证。不要索取或编造 API 凭据。如果当前申请接口约定拒绝这些字段/默认值,或无法确定分类选项,应报告并解决不一致问题,不要扩展表单或猜测。
34
34
 
35
35
  在用户已要求提交,且两个必选同意项均已给出的情况下,执行下文的创建命令。报告返回的申请 ID 和审核状态,然后停止;提交不代表审核通过,也不代表已获授权创建、测试或发布资源。
36
36
 
@@ -1,26 +1,26 @@
1
- # Select an upstream key
1
+ # Select a connection
2
2
 
3
- Use the confirmed CLI, email session, and supplier. In Dev, replace `openany-dev` in the commands below with `openany-dev`. When a resource needs an upstream key and the user has not specified one, ask only “Would you like to select an existing upstream key or add a new one?” Wait for the choice before continuing. If the user already selected a connection or requested a new one, go directly to that branch.
3
+ Use the confirmed CLI, email session, and supplier. In Dev, replace `openany-dev` in the commands below with `openany-dev`. When a resource needs a connection and the user has not specified one, open a native form with just two choices, “Use an existing connection” and “Add a new connection.” Wait for the choice before continuing. If the user already selected a connection or requested a new one, go directly to that branch.
4
4
 
5
- ## Select an existing key
5
+ ## Select an existing connection
6
6
 
7
- List the supplier's enabled connections as needed. Show the name, base URL, and authentication method and ask the user to choose one. Reuse any connection list you already have that contains no secrets. To see more results, pass the returned `nextCursor` to `--cursor`. If you confirm that there are no usable connections, ask whether to add one.
7
+ List the supplier's enabled connections as needed. Open a new native selection form to choose the exact connection. Use each connection as a separate selectable option and show its name, base URL, and authentication method. If the list exceeds the form's choice limit, show one page of candidates at a time and reserve a choice for viewing more when further candidates remain. If the available form cannot present selectable options, show the candidates in the form prompt and use its text input to collect the name or ID. Reuse any connection list you already have that contains no secrets. To see more results, pass the returned `nextCursor` to `--cursor`. If you confirm that there are no usable connections, use the native form to confirm whether to add one.
8
8
 
9
9
  ```bash
10
10
  openany-dev seller connections list --application APPLICATION_ID -j
11
11
  ```
12
12
 
13
- Confirm that the selection belongs to the current supplier and is enabled. Record its `id` and `revision`. Fetch the details by ID only if the existing receipt lacks required fields. If the connection's base URL or authentication method conflicts with known upstream information, ask the user to confirm. The resource configuration supplies the endpoint path. Do not use that path to match connections.
13
+ Confirm that the selection belongs to the current supplier and is enabled. Record its `id` and `revision`. Fetch the details by ID only if the existing receipt lacks required fields. If the connection's base URL or authentication method conflicts with known service information, ask the user to confirm through the native form. The resource configuration supplies the endpoint path. Do not use that path to match connections.
14
14
 
15
- ## Add a new upstream key
15
+ ## Add a new connection
16
16
 
17
- If the user chooses to add a key and has not supplied connection fields, run the command below immediately and wait for the dialog result. The dialog collects the connection name, base URL, authentication method, required parameter name, and API key in one step. Use the confirmed supplier ID and the operation identifier to open the dialog. Skip the connection schema lookup and do not ask for connection fields beforehand.
17
+ If the user chooses to add a connection and has not supplied connection fields, run the command below immediately and wait for the dialog result. The dialog collects the connection name, base URL, authentication method, required parameter name, and API key in one step. Use the confirmed supplier ID and the operation identifier to open the dialog. Skip the connection schema lookup and do not ask for connection fields beforehand.
18
18
 
19
19
  ```bash
20
20
  openany-dev seller connections create --application APPLICATION_ID --operation OPERATION --gui -j
21
21
  ```
22
22
 
23
- On success, use the `id` and `revision` from the receipt. Read the connection back only if the receipt lacks required fields. For imports, use the connection ID as `upstreamKeyId`. If the user cancels the dialog or it times out, preserve the current progress and wait for instructions.
23
+ On success, use the `id` and `revision` from the receipt. Read the connection back only if the receipt lacks required fields. For imports, use the connection ID as `connectionId`. If the user cancels the dialog or it times out, preserve the current progress and wait for instructions.
24
24
 
25
25
  If the native dialog is unavailable and no connection fields have been supplied, ask the user to run the command below in their local interactive terminal in the same environment. The terminal collects the connection fields in one step and hides key input. When finished, the user only needs to provide the connection ID.
26
26
 
@@ -28,7 +28,7 @@ If the native dialog is unavailable and no connection fields have been supplied,
28
28
  openany-dev seller connections create --application APPLICATION_ID --operation OPERATION
29
29
  ```
30
30
 
31
- If the user has already supplied any connection fields, keep the valid values, ask only for missing fields, and prepare `connection.json`. Set `label`, `baseUrl`, and `authType`. For `query` or `path` authentication, set `authParamName` as well. Keep credentials, query strings, and fragments out of the base URL. Use authorized `OPENANY_DEV_UPSTREAM_API_KEY` injection or have the user pass the key through local stdin with hidden input. Use `authType: "none"` only when the upstream is confirmed to require no authentication.
31
+ If the user has already supplied any connection fields, keep the valid values, use the native form to ask only for missing non-secret fields, and prepare `connection.json`. Set `label`, `baseUrl`, and `authType`. For `query` or `path` authentication, set `authParamName` as well. Keep credentials, query strings, and fragments out of the base URL. Use authorized `OPENANY_CONNECTION_API_KEY` injection or have the user pass the key through local stdin with hidden input. Use `authType: "none"` only when the service is confirmed to require no authentication.
32
32
 
33
33
  ```bash
34
34
  openany-dev seller connections create --application APPLICATION_ID --operation OPERATION --file connection.json -j
@@ -1,18 +1,18 @@
1
- # 选择上游 Key
1
+ # 选择连接
2
2
 
3
- 沿用已确认的 CLI、邮箱会话和供应商。Dev 环境将下方命令中的 `openany-dev` 替换为 `openany-dev`。需要绑定上游 Key 且用户尚未指定时,先单独问「这次要从已有的上游 Key 中选择,还是新建上游 Key?」等用户选择后进入对应分支。用户已明确选定连接或要求新建时,直接进入对应分支。
3
+ 沿用已确认的 CLI、邮箱会话和供应商。Dev 环境将下方命令中的 `openany-dev` 替换为 `openany-dev`。需要绑定连接且用户尚未指定时,先用原生表单提供「使用已有连接」和「新建连接」两个选项。等用户选择后进入对应分支。用户已明确选定连接或要求新建时,直接进入对应分支。
4
4
 
5
- ## 从已有 Key 中选择
5
+ ## 选择已有连接
6
6
 
7
- 按需列出该供应商已启用的连接,展示名称、Base URL 和认证方式,让用户选一条。已有无秘密的连接列表时直接复用;需要查看更多时,将回执的 `nextCursor` 传给 `--cursor`。确认没有可用连接后,询问是否新建。
7
+ 按需列出该供应商已启用的连接,再打开原生选择表单。每条连接单独作为一个可点选的选项,并展示名称、Base URL 和认证方式。候选超过表单选项上限时分页展示,有后续候选的页面预留「查看更多」选项。当前表单不支持可选项时,在题面展示候选,再通过表单文本输入收集连接名称或 ID。已有无秘密的连接列表时直接复用;需要查看更多时,将回执的 `nextCursor` 传给 `--cursor`。确认没有可用连接后,用原生表单确认是否新建。
8
8
 
9
9
  ```bash
10
10
  openany-dev seller connections list --application APPLICATION_ID -j
11
11
  ```
12
12
 
13
- 核对所选连接归属当前供应商且已启用,记录 `id` 和 `revision`。已知 ID 且现有回执缺少必需字段时,按 ID 查详情。若连接的 Base URL 或认证方式与已知上游信息冲突,先请用户确认。接口路径由资源配置提供,不能用它判断连接是否匹配。
13
+ 核对所选连接归属当前供应商且已启用,记录 `id` 和 `revision`。已知 ID 且现有回执缺少必需字段时,按 ID 查详情。若连接的 Base URL 或认证方式与已知服务信息冲突,先通过原生表单请用户确认。接口路径由资源配置提供,不能用它判断连接是否匹配。
14
14
 
15
- ## 新建上游 Key
15
+ ## 新建连接
16
16
 
17
17
  用户选择新建且尚未提供连接字段时,Agent 直接执行下方命令并等待弹框结果。弹框一次完成连接名称、Base URL、认证方式、必要的参数名和 API Key 的填写。弹框前只使用已确认的供应商 ID 和本次操作标识,跳过连接 schema 查询和连接字段提问。
18
18
 
@@ -20,7 +20,7 @@ openany-dev seller connections list --application APPLICATION_ID -j
20
20
  openany-dev seller connections create --application APPLICATION_ID --operation OPERATION --gui -j
21
21
  ```
22
22
 
23
- 创建成功后使用回执中的 `id` 和 `revision`。回执缺必要字段时才回读;导入绑定使用连接 ID 作为 `upstreamKeyId`。弹框取消或超时时,保留当前任务进度,等待用户指示。
23
+ 创建成功后使用回执中的 `id` 和 `revision`。回执缺必要字段时才回读;导入绑定使用连接 ID 作为 `connectionId`。弹框取消或超时时,保留当前任务进度,等待用户指示。
24
24
 
25
25
  原生弹框不可用且尚未提供连接字段时,请用户在同一环境的本地交互终端运行下方命令。终端一次收集连接资料并隐藏 Key 输入;用户完成后只需提供连接 ID。
26
26
 
@@ -28,7 +28,7 @@ openany-dev seller connections create --application APPLICATION_ID --operation O
28
28
  openany-dev seller connections create --application APPLICATION_ID --operation OPERATION
29
29
  ```
30
30
 
31
- 用户已提供部分或全部连接字段时,复用有效值,只补缺项,由 Agent 准备 `connection.json`。配置包含 `label`、`baseUrl` 和 `authType`,`query` 或 `path` 认证还需 `authParamName`。Base URL 不含凭据、查询串或片段。通过已授权的 `OPENANY_DEV_UPSTREAM_API_KEY` 注入,或请用户在本地使用隐藏输入将 Key 通过 stdin 传给 CLI。只有已确认无需认证时才使用 `authType: "none"`。
31
+ 用户已提供部分或全部连接字段时,复用有效值,只通过原生表单补齐缺少的非秘密字段,由 Agent 准备 `connection.json`。配置包含 `label`、`baseUrl` 和 `authType`,`query` 或 `path` 认证还需 `authParamName`。Base URL 不含凭据、查询串或片段。通过已授权的 `OPENANY_CONNECTION_API_KEY` 注入,或请用户在本地使用隐藏输入将 Key 通过 stdin 传给 CLI。只有已确认无需认证时才使用 `authType: "none"`。
32
32
 
33
33
  ```bash
34
34
  openany-dev seller connections create --application APPLICATION_ID --operation OPERATION --file connection.json -j
@@ -0,0 +1,131 @@
1
+ # Hermes 文件类 Skill 接入 OpenAny 托管交付
2
+
3
+ 本文示例使用 Dev 环境和 `openany-dev`。2026-11-16 本次交付为本地代码与测试,没有部署、发布 npm 包或修改服务商 Hermes;现网旧 CLI 不包含新命令。接入前应确认目标环境已支持下述接口,且所安装 CLI 的 `--help` 包含 `seller tasks upload`。
4
+
5
+ ## 责任和工作方式
6
+
7
+ Hermes 由服务商运行和管理。OpenAny 提供上传接口、CLI、私有对象存储和买家鉴权下载;平台不访问服务商服务器磁盘,也不要求修改 Hermes 源码。
8
+
9
+ 保留 Hermes 原生 `POST /v1/runs` 与 `GET /v1/runs/{run_id}`。买家提交商品后得到 OpenAny 的 `task_id` 与 `status_url`,继续使用自己的 API Key 查询该地址。文件上传为独立步骤,服务商不能通过上传接口声明任务执行成功或指定扣费金额。
10
+
11
+ ## 商品配置
12
+
13
+ 在现有异步商品配置中使用原生 HTTP JSON、轮询和 Hermes 服务接口 `/v1/runs`,输出合同增加布尔字段:
14
+
15
+ ```json
16
+ {
17
+ "adapter_type": "http_json",
18
+ "delivery_mode": "poll",
19
+ "timeout_secs": 600,
20
+ "output_contract": {
21
+ "format": "json",
22
+ "artifacts_required": true
23
+ },
24
+ "poll": {"interval_secs": 2}
25
+ }
26
+ ```
27
+
28
+ 现有固定字段配置 `config.fixed_body.instructions` 继续指定业务 Skill。启用 `artifacts_required` 后,每次成功任务必须交付一个真实文件;多个文件先打 ZIP。文字商品不设置该字段,保持原有行为。价格沿用该商品明确配置的价格,不由文件上传命令决定。
29
+
30
+ 当前版本此选项针对 Hermes 原生异步轮询。后端在发布文件类商品前要求该服务商已配置服务商回调密钥;该密钥同时用于文件上传鉴权。
31
+
32
+ ## 服务商一次性准备
33
+
34
+ 1. 在自己的 Hermes 执行环境安装包含本功能的 CLI。不要只在个人电脑安装;Hermes 调用终端工具时必须能找到 `openany-dev`。
35
+ 2. 在宿主进程的受限配置中,给实际运行上传工具的进程注入 `OPENANY_DEV_SELLER_KEY`。值使用 OpenAny 控制台为该服务商生成的服务商回调密钥。它不是买家 API Key、Hermes API Key、模型 API Key或邮箱登录会话。不要写进 SKILL.md、提示词、普通业务 JSON、日志或聊天。
36
+ 3. 配置绝对路径 `OPENANY_TASK_ROOT`,例如 `/home/ubuntu/openany-tasks`,并让 Hermes 执行用户可写。每个任务使用其下独立的 `<OpenAny任务UUID>/` 目录。
37
+ 4. 为文件类业务 Skill 加上下一节的交付规则,并确保允许其调用终端工具和上传 CLI。
38
+
39
+ 上传 CLI 只需要以上执行端配置,不要求邮箱交互登录或买家 Key。其他环境以对应 CLI 的 `--help` 为准,禁止混用环境凭据。
40
+
41
+ ## 加入业务 Skill 的交付规则
42
+
43
+ 可将以下内容加入服务商自己的文件类 Skill 指南。只负责执行上传操作的配套 Skill 也可以,但业务 Skill 必须实际调用它,不能只写一句“已上传”。
44
+
45
+ ```text
46
+ 当任务包含 OpenAny 文件交付上下文时:
47
+ 1. 使用平台给出的 OpenAny task_id;不要自己生成,不要使用 Hermes run_id。
48
+ 2. 在 $OPENANY_TASK_ROOT/<task_id>/ 中生成该任务的交付文件。
49
+ 3. 多个文件打包成一个 ZIP。准备最终、完整且不再修改的文件。
50
+ 4. 调用 openany-dev seller tasks upload --id <task_id> --file <文件绝对路径> --content-type <文件MIME> -j。
51
+ 5. 只有返回 task_id 匹配且 status=stored 才确认上传成功。stored 只代表文件暂存成功,不代表平台已结算。
52
+ 6. 网络错误或返回不确定时,保留文件并对同一任务重试同一内容;不要另建任务,也不要覆盖为另一份文件。
53
+ 7. 上传完成后,再结束 Hermes 运行并给出非空的业务结果摘要。上传一直失败时明确报告失败,不要谎报成功。
54
+ 8. 不读取、不打印、不输出任何凭据。不要处理其他任务目录。
55
+ 普通、没有 OpenAny 文件交付上下文的运行,按原业务规则执行。
56
+ ```
57
+
58
+ 网关对文件任务追加平台任务 ID、截止时间、上传命令及接口说明到 Hermes `instructions`,保留商品原有固定指令。平台不会把上传密钥放进请求正文或提示词。
59
+
60
+ 下面是上传命令示例,`TASK_ID` 应替换为本次任务指令中给出的 UUID:
61
+
62
+ ```bash
63
+ TASK_ID='<OPENANY_TASK_UUID>'
64
+ openany-dev seller tasks upload \
65
+ --id "$TASK_ID" \
66
+ --file "$OPENANY_TASK_ROOT/$TASK_ID/report.pdf" \
67
+ --content-type application/pdf \
68
+ -j
69
+ ```
70
+
71
+ 返回示例:
72
+
73
+ ```json
74
+ {
75
+ "task_id": "<OPENANY_TASK_UUID>",
76
+ "status": "stored",
77
+ "artifact": {
78
+ "artifact_id": "<ARTIFACT_UUID>",
79
+ "size": 125600,
80
+ "content_type": "application/pdf",
81
+ "sha256": "<SHA256>"
82
+ }
83
+ }
84
+ ```
85
+
86
+ 上传请求为 `POST /v1/agent-api-tasks/{task_id}/artifacts`,沿用 multipart 格式:`metadata` 固定为 `{"status":"completed"}`,`files` 为单个文件。`metadata` 字段仅复用已有解析格式;此接口不接受业务 result、结算字段或执行状态变更。调用方应优先使用 CLI。
87
+
88
+ ## 买家查询与下载
89
+
90
+ 买家提交商品后读取响应的 `status_url`,使用同一个买家 API Key 查询。完成响应中包含:
91
+
92
+ ```json
93
+ {
94
+ "task_id": "<OPENANY_TASK_UUID>",
95
+ "status": "completed",
96
+ "billing_status": "settled",
97
+ "result": "报告已生成。",
98
+ "artifacts": [
99
+ {"artifact_id":"<ARTIFACT_UUID>","size":125600,"content_type":"application/pdf"}
100
+ ],
101
+ "result_expires_at": "<实际过期时间>"
102
+ }
103
+ ```
104
+
105
+ 买家使用附件 ID 下载;此处用占位符,未包含真实凭据:
106
+
107
+ ```bash
108
+ curl --fail-with-body \
109
+ 'https://api-dev.openany.si/v1/agent-api-tasks/<OPENANY_TASK_UUID>/artifacts/<ARTIFACT_UUID>' \
110
+ --header 'Authorization: Bearer <BUYER_DEV_API_KEY>' \
111
+ --output report.pdf
112
+ ```
113
+
114
+ 未结算前不开放文件;其他 Key 或其他账号不能下载该任务文件。默认结果保留 72 小时,实际以 `result_expires_at` 为准。过期后需重新购买任务,不能把私有存储地址直接公开给买家。
115
+
116
+ ## 结算、重试和限制
117
+
118
+ - 两项都满足才结算:Hermes 运行成功且有非空输出;必交文件已上传并通过可读性与 SHA-256 校验。
119
+ - 仅上传成功不结算;Hermes 已完成但尚无文件时继续等待,直至截止时间。
120
+ - 执行失败、取消、中断或缺文件超时,释放预留费用。文件存储失败或校验失败不登记产物、不进入成功结算;可以在截止时间前重试。
121
+ - 同任务、同内容、同 MIME 的重复上传返回同一个附件;不同内容/MIME 不允许覆盖。上传并发不会重复扣费。上传不确定时人工或程序重试相同文件,CLI 不盲目自动重试。
122
+ - 单任务一个文件,最大 10,000,000 字节,不能为空。支持 PDF、ZIP、DOCX、XLSX、旧版 Excel、JSON、TXT、CSV;图片、HTML 和其他 MIME 当前不在允许列表。
123
+ - CLI 校验文件位于 `OPENANY_TASK_ROOT/<task_id>/` 内,拒绝越界及逃逸软链接。它不替代 Hermes 的进程权限、独立会话和文件沙箱;执行环境的实际隔离由服务商落实。
124
+ - 上传凭据目前为服务商级密钥,不是每任务短期令牌。需限制其可读范围;平台会按任务归属校验,并在登记时复核密钥轮换。
125
+ - 不需要把服务改成 callback 模式。原 `/result` 回调入口仍按原协议工作,不接受 poll 任务;新 `/artifacts` 入口只暂存文件。
126
+
127
+ ## 接入验收
128
+
129
+ 在本地或已部署测试环境验证一次真实生成与下载:先确认无文件时不结算;上传文件后确认仍在等待执行;执行完成后应出现一个附件和一笔成功费用。下载后核对字节/哈希;重复上传、重复查询和重复原请求均不能增加费用。最后覆盖错误凭据、存储失败、缺文件超时和执行失败。
130
+
131
+ 本次仓库内的端到端测试使用真实本机 HTTP、PostgreSQL/Redis,以及 Hermes 和 S3 协议测试服务;不等同于已经在服务商真实 Hermes 上安装验证,也不代表现网功能已启用。
@@ -1,10 +1,12 @@
1
1
  # Batch imports
2
2
 
3
+ Follow the [main entry](../SKILL.md) form-first rule for missing fields, connection choices, conflicts, and model family selection.
4
+
3
5
  ## Shortest workflow
4
6
 
5
- 1. Follow the [connection workflow](connections.md) first. Confirm an enabled upstream connection owned by the supplier. Reuse a confirmed connection or ask the user to select or add one. Confirm the connection before requesting or reading source materials. Use the [bindings template](../templates/bindings.json) when creating or changing bindings.
7
+ 1. Follow the [connection workflow](connections.md) first. Confirm an enabled connection owned by the supplier. Reuse a confirmed connection or ask the user to select or add one. Confirm the connection before requesting or reading source materials. Use the [bindings template](../templates/bindings.json) when creating or changing bindings.
6
8
  2. Follow the [publishing workflow](publishing.md) to collect and read the resource URL, documentation, or file. Reuse a compliant file, and ask only about gaps or conflicts. Check the selected connection against the source base URL and authentication method. If they conflict, ask the user to confirm which connection to use.
7
- 3. Run the appropriate `preview` once. Include `--bindings-file bindings.json` if bindings are already available. Record the batch `id` and check `summary`, `stage`, `missingFields`, and `errorCode` for anything to supply. Preview only validates. It creates no resources and makes no upstream calls.
9
+ 3. Run the appropriate `preview` once. Include `--bindings-file bindings.json` if bindings are already available. Record the batch `id` and check `summary`, `stage`, `missingFields`, and `errorCode` for anything to supply. Preview only validates. It creates no resources and makes no service calls.
8
10
  4. Run `run` to create drafts. For bindings completed after preview, use the returned item IDs and submit them with `run --bindings-file bindings.json`. Read each item's status, `operation`, and `resourceId` from the receipt. If the user requested only drafts, report the result and stop. For verification or publication, apply the [publishing workflow](publishing.md) to each item.
9
11
 
10
12
  ```bash
@@ -17,7 +19,7 @@ Each batch can contain up to 100 items. JSON files can be up to 8 MiB. Use strin
17
19
 
18
20
  ### V2 standard API or Agent API file
19
21
 
20
- If you already have a `provider-agent-api-v2` file, use its `apis` directly. To create a file from business materials, use the [standard API template](../templates/provider-agent-api-template.json) for a standard API or the [Agent API template](../templates/seller-agent-api-import-template.json) for Skill, Bot, Service, Data, or Goods. Preserve the selected [resource type](publishing.md) in `catalogType`. These resources require valid HTML body content in `includedContentHtml`, `usageInstructionsHtml`, and `effectContentHtml`, up to 32 KiB each. Standard APIs can omit them. For these imports, `apiDescription` must be at least 150 characters after trimming. The template's explanatory section is ignored during import. The API item ID is `METHOD /path` and the binding points to `upstreamKeyId`.
22
+ If you already have a `provider-agent-api-v2` file, use its `apis` directly. To create a file from business materials, use the [standard API template](../templates/provider-agent-api-template.json) for a standard API or the [Agent API template](../templates/seller-agent-api-import-template.json) for Skill, Bot, Service, Data, or Goods. Preserve the selected [resource type](publishing.md) in `catalogType`. These resources require valid HTML body content in `includedContentHtml`, `usageInstructionsHtml`, and `effectContentHtml`, up to 32 KiB each. Standard APIs can omit them. For these imports, `apiDescription` must be at least 150 characters after trimming. The template's explanatory section is ignored during import. The API item ID is `METHOD /path` and the binding points to `connectionId`.
21
23
 
22
24
  ```bash
23
25
  openany-dev seller imports preview --type api --file api-v2.json --application ID -j
@@ -1,10 +1,12 @@
1
1
  # 批量导入
2
2
 
3
+ 按[主入口](../SKILL.zh-CN.md)的表单优先规则补齐字段、选择连接、确认冲突和选择模型家族。
4
+
3
5
  ## 最短流程
4
6
 
5
- 1. 先按[中文连接流程](connections.zh-CN.md)确认归属当前供应商且已启用的上游连接。复用已确认的连接,或请用户选择已有连接或新建。连接确认后再读取或索取资料。创建或修改绑定时使用[绑定模板](../templates/bindings.json)。
7
+ 1. 先按[中文连接流程](connections.zh-CN.md)确认归属当前供应商且已启用的连接。复用已确认的连接,或请用户选择已有连接或新建。连接确认后再读取或索取资料。创建或修改绑定时使用[绑定模板](../templates/bindings.json)。
6
8
  2. 按[上架流程](publishing.zh-CN.md)收集并读取资源网址、文档或文件。直接复用合规文件,仅补缺项或冲突。根据资料核对已选连接的 Base URL 和认证方式,如不匹配,先请用户确认适用的连接。
7
- 3. 执行对应分支的 `preview` 一次。已有绑定就带上 `--bindings-file bindings.json`。记录批次 `id`,从 `summary`、`stage`、`missingFields` 和 `errorCode` 判断要补什么。预览只校验,不创建资源或调用上游。
9
+ 3. 执行对应分支的 `preview` 一次。已有绑定就带上 `--bindings-file bindings.json`。记录批次 `id`,从 `summary`、`stage`、`missingFields` 和 `errorCode` 判断要补什么。预览只校验,不创建资源或调用服务。
8
10
  4. 执行 `run` 创建草稿。预览后才补齐的绑定按返回项目 ID 填写,直接随 `run --bindings-file bindings.json` 提交。读取回执中的逐项状态、`operation` 和 `resourceId`。只要求草稿时报告结果即结束;需要验证或发布时按[上架流程](publishing.zh-CN.md)逐项处理。
9
11
 
10
12
  ```bash
@@ -17,7 +19,7 @@ openany-dev seller imports run --batch BATCH_ID --application ID -j
17
19
 
18
20
  ### V2 API 或服务文件
19
21
 
20
- 已有 `provider-agent-api-v2` 文件就直接用其中的 `apis`。从业务资料新建文件时,普通 API 用[普通 API 模板](../templates/provider-agent-api-template.json),Skill、Bot、Service、Data 和 Goods 用 [Agent API 模板](../templates/seller-agent-api-import-template.json),按[资源上架流程](publishing.zh-CN.md)保留所选的 `catalogType`。这些资源的 `includedContentHtml`、`usageInstructionsHtml`、`effectContentHtml` 均需有效 HTML 正文,每字段最多 32 KiB;普通 API 可省略。这些导入条目的 `apiDescription` 去掉首尾空白后至少 150 个字符。说明区不参与导入。API 项目 ID 为 `METHOD /path`,绑定指向 `upstreamKeyId`。
22
+ 已有 `provider-agent-api-v2` 文件就直接用其中的 `apis`。从业务资料新建文件时,普通 API 用[普通 API 模板](../templates/provider-agent-api-template.json),Skill、Bot、Service、Data 和 Goods 用 [Agent API 模板](../templates/seller-agent-api-import-template.json),按[资源上架流程](publishing.zh-CN.md)保留所选的 `catalogType`。这些资源的 `includedContentHtml`、`usageInstructionsHtml`、`effectContentHtml` 均需有效 HTML 正文,每字段最多 32 KiB;普通 API 可省略。这些导入条目的 `apiDescription` 去掉首尾空白后至少 150 个字符。说明区不参与导入。API 项目 ID 为 `METHOD /path`,绑定指向 `connectionId`。
21
23
 
22
24
  ```bash
23
25
  openany-dev seller imports preview --type api --file api-v2.json --application ID -j
@@ -1,6 +1,6 @@
1
1
  # Login and sessions
2
2
 
3
- Follow the input rules in the [main entry](../SKILL.md). Use the same confirmed CLI and execution environment for authentication and subsequent Seller commands.
3
+ Follow the form-first input rules in the [main entry](../SKILL.md). Use the same confirmed CLI and execution environment for authentication and subsequent Seller commands.
4
4
 
5
5
  ## Install and configure the CLI
6
6
 
@@ -26,13 +26,13 @@ If the user is known to be signed out, skip `seller status` and go straight to e
26
26
 
27
27
  ## Complete email login
28
28
 
29
- If the email address is missing, ask only for that address and wait for the user's reply. Once the target CLI, email address, and login authorization are confirmed, the agent runs:
29
+ If the email address is missing, use a native text-input form to ask only for that address and wait for the user's reply. Once the target CLI, email address, and login authorization are confirmed, the agent runs:
30
30
 
31
31
  ```bash
32
32
  openany-dev auth email send --email EMAIL_ADDRESS -j
33
33
  ```
34
34
 
35
- Use an authorized mailbox tool to read the code for this attempt. Otherwise, ask only “The verification code has been sent. Please enter the 6-digit code you received for this attempt.” Preserve leading zeros. Do not echo the code or resend it. Reuse the successful verification receipt before continuing with the Seller task.
35
+ Use an authorized mailbox tool to read the code for this attempt. Otherwise, use the native text-input form to ask only “The verification code has been sent. Please enter the 6-digit code you received for this attempt.” Preserve leading zeros. Do not echo the code or resend it. Reuse the successful verification receipt before continuing with the Seller task.
36
36
 
37
37
  ```bash
38
38
  openany-dev auth email verify --code SIX_DIGITS -j
@@ -1,6 +1,6 @@
1
1
  # 登录与会话
2
2
 
3
- 遵守[主入口](../SKILL.zh-CN.md)的提问规则。认证和后续 Seller 命令使用同一已确认入口与执行环境。
3
+ 遵守[主入口](../SKILL.zh-CN.md)的表单优先规则。认证和后续 Seller 命令使用同一已确认入口与执行环境。
4
4
 
5
5
  ## 安装与配置
6
6
 
@@ -26,13 +26,13 @@ openany-dev --help
26
26
 
27
27
  ## 完成邮箱登录
28
28
 
29
- 缺邮箱时只询问登录邮箱并等待用户回复。目标入口、邮箱和登录授权齐备后,由 Agent 执行发送命令:
29
+ 缺邮箱时只用原生文本输入表单索取登录邮箱,等待用户作答。目标入口、邮箱和登录授权齐备后,由 Agent 执行发送命令:
30
30
 
31
31
  ```bash
32
32
  openany-dev auth email send --email EMAIL_ADDRESS -j
33
33
  ```
34
34
 
35
- 用获授权的邮箱工具读取本次验证码,否则单独提示「验证码已发送,请输入本次收到的 6 位验证码。」保留前导零,不回显或重复发送。验证成功后复用回执,再继续 Seller 任务。
35
+ 用获授权的邮箱工具读取本次验证码,否则用原生文本输入表单单独提示「验证码已发送,请输入本次收到的 6 位验证码。」保留前导零,不回显或重复发送。验证成功后复用回执,再继续 Seller 任务。
36
36
 
37
37
  ```bash
38
38
  openany-dev auth email verify --code SIX_DIGITS -j
@@ -2,7 +2,7 @@
2
2
 
3
3
  Use the bundled [model template](../templates/models-v2.json) with `schemaVersion: "seller-model-config-v2"` and `models`. Fill in actual prices and the required configuration. Specify connections and model families in the [bindings file](../templates/bindings.json) using confirmed values. Model files can contain up to 100 items and be up to 2 MiB. Keep keys out of these files.
4
4
 
5
- Follow [Batch imports](imports.md) to confirm connections and preview once. Use `summary`, each item's `stage`, `missingFields`, `errorCode`, and `items[].families` to fill in only missing fields. Submit existing bindings with preview. For bindings completed later, use the returned item IDs and pass them to `run`. Record each draft's `resourceId` from the run or resume result. Query `status` only if the result is uncertain or incomplete. Follow the [publishing workflow](publishing.md) to continue with verification and publication.
5
+ Follow [Batch imports](imports.md) to confirm connections and preview once. Use `summary`, each item's `stage`, `missingFields`, `errorCode`, and `items[].families` to identify missing fields. Follow the [main entry](../SKILL.md) form-first rule to collect only those fields. Submit existing bindings with preview. For bindings completed later, use the returned item IDs and pass them to `run`. Record each draft's `resourceId` from the run or resume result. Query `status` only if the result is uncertain or incomplete. Follow the [publishing workflow](publishing.md) to continue with verification and publication.
6
6
 
7
7
  ```text
8
8
  openany-dev seller imports preview --type model --file MODEL_FILE --application ID -j
@@ -2,7 +2,7 @@
2
2
 
3
3
  使用技能内的[模型模板](../templates/models-v2.json)(`schemaVersion: "seller-model-config-v2"`、`models`)。模板须填入实际报价和必需配置;连接和模型家族通过[绑定文件](../templates/bindings.json)指定,不得猜测。模型文件最多 100 项、最大 2 MiB,不得包含密钥。
4
4
 
5
- 按[批量导入](imports.zh-CN.md)核对连接、预览一次。结合 `summary`、各项 `stage`、`missingFields`、`errorCode` 和 `items[].families`,只补缺失字段。已有绑定随预览提交;后补的绑定按返回项目 ID 直接传给 `run`。从运行或恢复结果记录草稿 `resourceId`;仅结果不确定或缺字段时查 `status`。继续验证和发布时遵循[上架流程](publishing.zh-CN.md)。
5
+ 按[批量导入](imports.zh-CN.md)核对连接、预览一次。结合 `summary`、各项 `stage`、`missingFields`、`errorCode` 和 `items[].families`,按[主入口](../SKILL.zh-CN.md)的表单优先规则只补缺失字段。已有绑定随预览提交;后补的绑定按返回项目 ID 直接传给 `run`。从运行或恢复结果记录草稿 `resourceId`;仅结果不确定或缺字段时查 `status`。继续验证和发布时遵循[上架流程](publishing.zh-CN.md)。
6
6
 
7
7
  ```text
8
8
  openany-dev seller imports preview --type model --file MODEL_FILE --application ID -j
@@ -2,6 +2,8 @@
2
2
 
3
3
  Complete main-skill preflight and [connections](connections.md) first. For an imported draft, start at step 2 with its `resourceId`; do not create it again.
4
4
 
5
+ Follow the [main entry](../SKILL.md) form-first rule for missing model fields, family selection, and any needed test or publication confirmation.
6
+
5
7
  ## 1. Prepare and create
6
8
 
7
9
  ```bash
@@ -9,9 +11,9 @@ openany-dev seller schema --type model --application APPLICATION_ID -j
9
11
  openany-dev seller models create --application APPLICATION_ID --file model.json --operation TASK-model-create-1 -j
10
12
  ```
11
13
 
12
- Prepare `model.json` against the current schema: `price` and `routes`, using the supplier's actual model identity, capabilities, quote, currency, upstream endpoints, mappings, and route choices. Prices are decimal strings with at most six fractional digits; token prices use the existing per-million-token unit. Bind routes to owned connection IDs and required connection revisions. Never copy response-only ownership, activation, or publication fields into a write payload. Record the returned `price.id` as `MODEL_ID`.
14
+ Prepare `model.json` against the current schema: `price` and `routes`, using the supplier's actual model identity, capabilities, quote, currency, service endpoints, mappings, and route choices. Prices are decimal strings with at most six fractional digits; token prices use the existing per-million-token unit. Bind routes to owned connection IDs and required connection revisions. Never copy response-only ownership, activation, or publication fields into a write payload. Record the returned `price.id` as `MODEL_ID`.
13
15
 
14
- `price.model` is the supplier's upstream model ID (`key_market_model_prices.public_model`). `routes[0].publicModel` is the OpenAny route model ID (`key_market_model_routes.public_model`) used in client requests. These may differ: for example, `price.model: "vendor-chat-v2"` and `routes[0].publicModel: "my-chat"`. Saving derives the route's upstream model from `price.model`; do not add a third writable identity. Editing either ID does not rename the other. Manage one route per model.
16
+ `price.model` is the supplier's service model ID. `routes[0].publicModel` is the OpenAny route model ID used in client requests. These may differ: for example, `price.model: "vendor-chat-v2"` and `routes[0].publicModel: "my-chat"`. Saving derives the route's service model from `price.model`; do not add a third writable identity. Editing either ID does not rename the other. Manage one route per model.
15
17
 
16
18
  ### Non-token pricing
17
19
 
@@ -29,7 +31,7 @@ If the live CLI schema disagrees with the current website fields (for example, m
29
31
 
30
32
  ### Credential-free examples
31
33
 
32
- `SECRET_IN_DOCUMENT` can come from the CLI's local scan before any backend request. It also rejects `Authorization: Bearer YOUR_API_KEY` in `price.curlExample`: a placeholder is still credential-like text. Use the returned `field` to locate the problem, omit authentication headers from the example, and configure authentication through the connection. Never replace the placeholder with a real key. There is no need to remove every standalone occurrence of the word Bearer.
34
+ Keep placeholder headers such as `-H "Authorization: Bearer $OPENANY_DEV_API_KEY"` or `-H "Authorization: Bearer YOUR_API_KEY"` in model cURL examples (`price.curlExample` or `models[].requestCurlExample`). Enter real credentials through the secure connection. If the CLI returns `SECRET_IN_DOCUMENT`, use the reported `field` to locate the credential and replace it with a placeholder in the example.
33
35
 
34
36
  ## 2. Read the saved configuration
35
37
 
@@ -37,7 +39,7 @@ If the live CLI schema disagrees with the current website fields (for example, m
37
39
  openany-dev seller models get --application APPLICATION_ID --id MODEL_ID -j
38
40
  ```
39
41
 
40
- Save `version`, `price.id`, and each route's `id`, `upstreamKeyId`, and `upstreamRevision`. Use saved route IDs, not array indices or local import item IDs. Read `price.upstreamPath` to choose the authorized endpoint. If this is a draft-only task, report the draft ID and stop here.
42
+ Save `version`, `price.id`, and each route's `id`, `connectionId`, and `connectionRevision`. Use saved route IDs, not array indices or local import item IDs. Read `price.servicePath` to choose the authorized endpoint. If this is a draft-only task, report the draft ID and stop here.
41
43
 
42
44
  ## 3. Verify every route
43
45
 
@@ -50,8 +52,8 @@ For each route, create a separate non-secret verification file with these fields
50
52
  | --- | --- |
51
53
  | `expectedVersion` | Saved model `version` |
52
54
  | `routeId` | Saved `routes[].id` for this route |
53
- | `expectedUpstreamRevision` | That route's current `upstreamRevision`; recheck the connection if needed |
54
- | `endpointIndex` | Zero-based index of the selected endpoint in `price.upstreamPath` |
55
+ | `expectedConnectionRevision` | That route's current `connectionRevision`; recheck the connection if needed |
56
+ | `endpointIndex` | Zero-based index of the selected endpoint in `price.servicePath` |
55
57
  | `request` | Authorized test request (`path`, `query`, `headers`, `body` as applicable), without credentials |
56
58
 
57
59
  ```bash
@@ -65,7 +67,7 @@ openany-dev seller models get --application APPLICATION_ID --id MODEL_ID --verif
65
67
  {
66
68
  "expectedVersion": "SAVED_MODEL_VERSION",
67
69
  "routeId": "SAVED_ROUTE_ID",
68
- "expectedUpstreamRevision": 1,
70
+ "expectedConnectionRevision": 1,
69
71
  "endpointIndex": 0,
70
72
  "request": {
71
73
  "path": {},
@@ -79,9 +81,9 @@ openany-dev seller models get --application APPLICATION_ID --id MODEL_ID --verif
79
81
  }
80
82
  ```
81
83
 
82
- Replace the version, route ID, revision, endpoint index and test body with the saved configuration and authorized test inputs. For models, `request.path` must be an empty object `{}` when supplied, never `"/v1/chat/completions"` or a nonempty parameter map. The actual URL path comes from `price.upstreamPath[endpointIndex]`. A string fails backend JSON decoding before URL construction or an upstream call; the CLI now rejects it locally. API path parameter objects are a separate contract. A generic 400 alone is not evidence that CLI permissions are insufficient or that verification requires the web UI.
84
+ Replace the version, route ID, revision, endpoint index and test body with the saved configuration and authorized test inputs. For models, `request.path` must be an empty object `{}` when supplied, never `"/v1/chat/completions"` or a nonempty parameter map. The actual URL path comes from `price.servicePath[endpointIndex]`. A string fails backend JSON decoding before URL construction or a service call; the CLI now rejects it locally. API path parameter objects are a separate contract. A generic 400 alone is not evidence that CLI permissions are insufficient or that verification requires the web UI.
83
85
 
84
- Record the verification response `id` before querying it. Use a distinct operation/file for each route. A usable receipt has `state: "passed"`, is not stale, and matches this `modelId`, `modelVersion`, `routeId`, `upstreamKeyId`, and `upstreamRevision`. Testing may incur costs; obey the authorized scope and budget. Query an unfinished known receipt within the task deadline instead of repeating verify. For unknown outcomes, follow [recovery](reviews.md).
86
+ Record the verification response `id` before querying it. Use a distinct operation/file for each route. A usable receipt has `state: "passed"`, is not stale, and matches this `modelId`, `modelVersion`, `routeId`, `connectionId`, and `connectionRevision`. Testing may incur costs; obey the authorized scope and budget. Query an unfinished known receipt within the task deadline instead of repeating verify. For unknown outcomes, follow [recovery](reviews.md).
85
87
 
86
88
  ## 4. Publish
87
89
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  先完成入口检查和[连接流程](connections.zh-CN.md),再收集资料。已有导入草稿时,从第 2 步使用返回的 `resourceId` 继续。
4
4
 
5
+ 按[主入口](../SKILL.zh-CN.md)的表单优先规则收集缺少的模型字段、选择家族,以及补充所需的测试或发布确认。
6
+
5
7
  ## 1. 准备并创建
6
8
 
7
9
  ```bash
@@ -9,9 +11,9 @@ openany-dev seller schema --type model --application APPLICATION_ID -j
9
11
  openany-dev seller models create --application APPLICATION_ID --file model.json --operation TASK-model-create-1 -j
10
12
  ```
11
13
 
12
- 按当前 schema 准备 `model.json` 的 `price` 和 `routes`。使用实际模型标识、能力、报价、币种、上游端点和映射。价格用最多六位小数的字符串。按 token 计价时沿用每百万 token 单位。绑定归属当前供应商的连接及其修订,省略仅在响应中提供的归属、启用和发布字段。记录返回的 `price.id` 为 `MODEL_ID`。
14
+ 按当前 schema 准备 `model.json` 的 `price` 和 `routes`。使用实际模型标识、能力、报价、币种、服务端点和映射。价格用最多六位小数的字符串。按 token 计价时沿用每百万 token 单位。绑定归属当前供应商的连接及其修订,省略仅在响应中提供的归属、启用和发布字段。记录返回的 `price.id` 为 `MODEL_ID`。
13
15
 
14
- `price.model` 是供应商的上游模型 ID,`routes[0].publicModel` 是客户端使用的 OpenAny 路由模型 ID。两者可以不同,例如 `vendor-chat-v2` 和 `my-chat`。保存时从 `price.model` 得到路由的上游模型,每个模型管理一条路由。
16
+ `price.model` 是供应商的服务模型 ID,`routes[0].publicModel` 是客户端使用的 OpenAny 路由模型 ID。两者可以不同,例如 `vendor-chat-v2` 和 `my-chat`。保存时从 `price.model` 得到路由的服务模型,每个模型管理一条路由。
15
17
 
16
18
  ### 非 token 计价
17
19
 
@@ -25,7 +27,7 @@ V2 导入的 `inputPrice` 和 `outputPrice` 分别映射到这两个价格字段
25
27
 
26
28
  更新时保留已有路由并传 `expectedVersion`。`pricingEditable: false` 时省略价格字段。导入要求 cURL 示例,直接创建按其 schema 判断。遇到 CLI 与网站字段不一致时,报告具体差异,保留原输入,先解决该差异再写入。
27
29
 
28
- `SECRET_IN_DOCUMENT` 可能来自 CLI 本地检查。即使是 `Authorization: Bearer YOUR_API_KEY` 占位符也会触发检查。按返回的 `field` 定位,从示例中移除认证头,由连接提供认证。
30
+ 在模型 cURL 示例(`price.curlExample` 或 `models[].requestCurlExample`)中保留 `-H "Authorization: Bearer $OPENANY_DEV_API_KEY"` 或 `-H "Authorization: Bearer YOUR_API_KEY"` 这样的占位符。真实凭证通过安全连接录入。如果 CLI 返回 `SECRET_IN_DOCUMENT`,按返回的 `field` 定位凭证,并在示例中将其替换为占位符。
29
31
 
30
32
  ## 2. 读取已保存的配置
31
33
 
@@ -33,13 +35,13 @@ V2 导入的 `inputPrice` 和 `outputPrice` 分别映射到这两个价格字段
33
35
  openany-dev seller models get --application APPLICATION_ID --id MODEL_ID -j
34
36
  ```
35
37
 
36
- 记录 `version`、`price.id` 和各路由的 `id`、`upstreamKeyId`、`upstreamRevision`。验证使用保存的路由 ID。按 `price.upstreamPath` 选择获授权的端点。只建草稿时报告 ID 后结束。
38
+ 记录 `version`、`price.id` 和各路由的 `id`、`connectionId`、`connectionRevision`。验证使用保存的路由 ID。按 `price.servicePath` 选择获授权的端点。只建草稿时报告 ID 后结束。
37
39
 
38
40
  ## 3. 验证每条路由
39
41
 
40
- 先核对已有回执。仅复用 `state: "passed"`、未过期且 `modelId`、`modelVersion`、`routeId`、`upstreamKeyId` 和 `upstreamRevision` 均匹配的结果。遇到运行中或结果未知的测试,先查询或核实。只有需要新验证且已获测试和费用授权时才运行一次。
42
+ 先核对已有回执。仅复用 `state: "passed"`、未过期且 `modelId`、`modelVersion`、`routeId`、`connectionId` 和 `connectionRevision` 均匹配的结果。遇到运行中或结果未知的测试,先查询或核实。只有需要新验证且已获测试和费用授权时才运行一次。
41
43
 
42
- 每条路由分别准备验证数据和操作名。字段为当前 `expectedVersion`、保存的 `routeId`、当前 `expectedUpstreamRevision`、从 0 开始的 `endpointIndex` 和获授权的 `request`。`request` 可包含 `path`、`query`、`headers`、`body`,凭据由连接提供。模型的 `request.path` 如有填写,只能是空对象 `{}`,实际路径来自 `price.upstreamPath[endpointIndex]`。可用 `--file PATH` 或 `--input 'JSON'` 传入同一结构,二选一。通用 400 错误需核对具体报错,再判断原因。
44
+ 每条路由分别准备验证数据和操作名。字段为当前 `expectedVersion`、保存的 `routeId`、当前 `expectedConnectionRevision`、从 0 开始的 `endpointIndex` 和获授权的 `request`。`request` 可包含 `path`、`query`、`headers`、`body`,凭据由连接提供。模型的 `request.path` 如有填写,只能是空对象 `{}`,实际路径来自 `price.servicePath[endpointIndex]`。可用 `--file PATH` 或 `--input 'JSON'` 传入同一结构,二选一。通用 400 错误需核对具体报错,再判断原因。
43
45
 
44
46
  ```bash
45
47
  openany-dev seller models verify --application APPLICATION_ID --id MODEL_ID --file route-verification.json --operation TASK-model-route1-test-1 -j