请求与信封

本页介绍本地 connect、publish 和 status 请求。输入一个请求文档，返回一个 JSON 信封；智能体或脚本依据本文档记录的结构进行分支。可选的自托管 Server 使用自己的信封。

信封

{
  "protocolVersion": 1,
  "operation": "publish",
  "ok": true,
  "result": {},
  "error": null
}

{
  "protocolVersion": 1,
  "operation": "publish",
  "ok": false,
  "result": null,
  "error": { "code": "INPUT_INVALID", "message": "The request document is not valid." }
}

对于本地请求，operation 是 connect、publish 和 status 之一。消息是由代码选择的静态文本，绝不会根据堆栈、路径、响应正文或参数生成，因此诊断信息不会携带机密。

Server 信封

自托管 Server。Server 命令是独立路径，使用 @syndroo/[email protected] 和 @syndroo/[email protected]。其 JSON 使用 operation: "server"，并通过 result.subcommand 区分 init、doctor、deploy、connect、ci 和 publish。

Server 请求和结果结构与下文的本地请求族不同。请按照部署服务器操作；其结果、恢复 ID 和验收限制汇总在Server 命令参考中。

connect

共有四种请求结构。start 开始连接，resume 完成待处理步骤，update 和 disconnect 维护已保存的连接。

{
  "type": "start",
  "provider": "bluesky",
  "label": "work",
  "connectionId": "conn_existing",
  "options": {}
}

{
  "type": "resume",
  "connectSessionId": "cs_...",
  "stepRevision": 0,
  "input": { "type": "credentials", "credentials": { "identifier": "you.bsky.social", "password": "..." } }
}

{
  "type": "update",
  "connectionId": "conn_...",
  "changes": { "label": "writing", "isDefault": true }
}

继续输入要么是携带提供商凭证对象的 credentials，要么是用于已通过带外方式交付授权回调的会话的 callback_complete。stepRevision 必须与会话匹配，因此过期步骤会被拒绝，而不会应用两次。

{
  "status": "action_required",
  "connectSessionId": "cs_...",
  "stepRevision": 1,
  "expiresAt": "2026-10-08T00:15:00.000Z",
  "action": { "type": "credential_input", "fields": [{ "name": "password", "label": "Bluesky app password", "secret": true }] }
}

动作可以是 credential_input、open_url 或 wait_for_callback。完成的步骤返回 "status": "done" 和已保存的 connection。

publish

共有三种请求结构：prepare 冻结内容，execute 发送内容，retry 只重新发送较早操作中符合条件的目标。不带 type 的文档是普通准备请求。

{
  "type": "prepare",
  "content": { "text": "One document, chosen targets." },
  "targets": [
    { "provider": "bluesky" },
    { "provider": "devto", "connection": "conn_...", "options": { "title": "Hello", "body_markdown": "Body" } }
  ]
}

{ "type": "execute", "approvalToken": "<token>" }

{
  "type": "retry",
  "retryOf": "op_...",
  "targets": [{ "provider": "bluesky", "connection": "conn_..." }]
}

目标包含 provider，可选包含 connection 和提供商专用的 options。一个文档包含一到二十个目标。目标未指定连接时，使用提供商的默认连接；存在歧义时会被拒绝，而不是猜测。

{
  "status": "confirmation_required",
  "operationId": "op_example",
  "approvalToken": "<approvalToken>",
  "expiresAt": "2026-10-08T00:15:00.000Z",
  "preview": [
    {
      "deliveryId": "dl_example",
      "connectionId": "conn_example",
      "account": { "provider": "bluesky", "accountId": "acct_example", "origin": "https://bsky.social" },
      "provider": "bluesky",
      "preview": { "content": { "text": "One document, chosen targets." }, "fields": [] },
      "presentation": { "accountName": "Example account", "profileUrl": "https://bsky.app/profile/example", "label": "work" }
    }
  ]
}

{
  "phase": "execution",
  "operationId": "op_example",
  "status": "succeeded",
  "deliveries": [
    {
      "deliveryId": "dl_example",
      "connectionId": "conn_example",
      "account": { "provider": "bluesky", "accountId": "acct_example", "origin": "https://bsky.social" },
      "attempts": 1,
      "state": "settled",
      "outcome": { "status": "succeeded", "remoteId": "at://example/post/1", "url": "https://bsky.app/profile/example/post/1" },
      "presentation": { "accountName": "Example account", "profileUrl": "https://bsky.app/profile/example", "label": "work" }
    }
  ]
}

执行状态是 pending、running、succeeded、partial、failed 或 unknown 之一。每次投递结果为 succeeded；带处置状态 not_applied 的 failed；unknown；或目标从未进入调用时的 not_started。符合条件且失败的结果可能带有 retryable、原因和 retryAfter 时间。失败和未开始表示写入已确认未应用；未知结果始终不可重试。

目标的稳定身份由 provider、origin 和 accountId 构成。可选 presentation 仅用于显示，包含可读的 accountName、公开 profileUrl 和连接 label：它绝不会改变目标选择、账号去重或绑定，而且允许缺少可选元数据。提供商返回的不安全可选值会在进入冻结快照前被丢弃；这不会放宽请求模式验证。

该 presentation 会随其他意图一起冻结，并纳入意图摘要，因此之后重命名不会改变本次操作的历史；只有个人资料链接是安全 HTTPS URL 时才显示，否则显示稳定的 HTTPS 地址（域名）。单次投递的冻结快照由 deliveryId 和产生其状态的执行轮次关联，绝不根据数组位置、平台名称或最近一次准备的意图推断。

syndroo status --operation <operationId> 读取已记录的结果：不加载提供商、不读取输入文件，也绝不重写历史。投递会显示其自身轮次的历史冻结名称、标签和预览，而不是当前连接；如果旧版本记录无法根据持久化证据证明其轮次，预览会报告为不可用，而不是猜测。每个请求无论格式是否有效，都会在运行任何内容前按协议验证。

status

共有五种查询结构，没有查询语言。未提供选择器时返回概览。

提供商可用性是 available、untrusted、unavailable 或 stale，来源是 official 或 third_party。状态命令读取已保存的观察结果；不会联系平台刷新它们。

本地执行状态与退出码

发布结果映射到进程退出码：unknown 退出 4，failed 和 partial 退出 6，其他所有执行状态退出 0。预检或用法拒绝退出 2，在确认提示中明确拒绝退出 5。