DEEPSEEK HARNESS · HTTP INTERFACE · 0.1.11

Review Outbox HTTP 接口参考

Review Outbox 在 DSH 的 Web 服务上注册一个前缀 /review-outbox/api,下面有 12 条路由。它们在 DSH 进程内运行,读写的是同一个 store,也就是左侧「成果审阅」面板看到的那份数据。这份文档按代码里的实际分支写,不是按设计意图写。

鉴权

没有 token,也没有 API key。

路由在每次请求进来时调用宿主的 connection.requestRejection({ headers }):只有在 DSH 的 connection 服务不可用时才一律返回 403。也就是说,能不能调取决于 DSH 自己认不认这条连接,插件不额外加一层。

因此:浏览器里任何网页都能向你本机的这个前缀发请求,和它能不能调其它 DSH 插件路由的风险相同。这不是一个可以暴露到公网的接口,host 不要绑 0.0.0.0。需要把成果给别人看,用 GET /receipt 导出的独立验收单,那是纯 HTML,不依赖本机服务。

通用约定

GET /review-outbox/api/health

存活与规模。面板启动时先调这条。

curl -s http://127.0.0.1:PORT/review-outbox/api/health
{
  "ok": true,
  "version": 1,
  "items": [],
  "pending": 0,
  "stateError": null,
  "backfill": {
    "status": "idle",
    "listed": 0,
    "scanned": 0,
    "discovered": 0,
    "changed": 0,
    "truncated": false,
    "errors": [],
    "startedAt": null,
    "finishedAt": null
  }
}

stateError 非空表示状态文件读写出过问题,此时 items 可能是上一份内存快照而不是磁盘内容。

backfill.status 取值:idle、running、done、unavailable、disabled(插件配置了 backfill: false)。listed 是列出的条目数,scanned 是真正读过的数,truncated 为 true 表示这一轮达到上限提前收尾。

GET /review-outbox/api/packs

可用的验收包清单,也就是「用哪套清单来审」。

curl -s http://127.0.0.1:PORT/review-outbox/api/packs
{
  "packs": [
    {
      "id": "research-report",
      "version": 1,
      "label": "研究报告验收",
      "summary": "核对结论、引用、数据口径和方法限制。",
      "checks": [
        {
          "id": "claims-evidence",
          "label": "核心结论有对应证据",
          "required": true,
          "requirement": "逐条核对核心结论,记录能支撑结论的正文位置、数据或原始来源。",
          "placeholder": "例:结论 1 见第 3 节表 2;样本数据与结论一致。"
        }
      ]
    }
  ]
}

GET /review-outbox/api/items

全部成果,加一次汇总。可选 ?status=pending|approved|returned|archived 过滤。

curl -s 'http://127.0.0.1:PORT/review-outbox/api/items?status=pending'
{
  "version": 1,
  "items": [
    {
      "id": "3f2a…",
      "status": "pending",
      "title": "华东区渠道回款变化",
      "path": "/Users/me/reports/q3.md",
      "firstSeenAt": "2026-11-19T03:40:00.000Z",
      "updatedAt": "2026-11-19T03:40:00.000Z",
      "reviewPack": {
        "id": "research-report",
        "version": 1,
        "checks": {
          "claims-evidence": { "checked": false, "detail": "" },
          "citations-accessible": { "checked": false, "detail": "" },
          "data-scope": { "checked": false, "detail": "" },
          "method-limitations": { "checked": false, "detail": "" },
          "reproduction": { "checked": false, "detail": "" }
        }
      },
      "reviewProgress": {
        "completed": 0,
        "total": 5,
        "requiredCompleted": 0,
        "requiredTotal": 4,
        "complete": false,
        "incomplete": ["claims-evidence", "citations-accessible", "data-scope", "method-limitations"]
      }
    }
  ],
  "pending": 1,
  "stateError": null,
  "backfill": { "running": false, "scanned": 0, "queued": 0, "errors": [] }
}

GET /review-outbox/api/item

单条成果,带验收进度。必须给 ?id=。

curl -s 'http://127.0.0.1:PORT/review-outbox/api/item?id=3f2a…'
{
  "item": {
    "id": "3f2a…",
    "status": "pending",
    "reviewProgress": { "completed": 2, "total": 5, "requiredCompleted": 2, "requiredTotal": 4, "complete": false, "incomplete": ["data-scope", "method-limitations"] }
  }
}

两个形状容易混:包的 checks 是数组(定义,来自 /packs),成果里的 reviewPack.checks 是以 checkId 为键的对象(状态,带 checked 与 detail)。reviewProgress 里没有 ready 字段,判断能不能通过看 complete;incomplete 直接列出还没完成的 checkId。

找不到返回 404:

{ "error": "Item not found" }

GET /review-outbox/api/preview

成果内容的预览。图片走 dataUrl,文本走原文,二进制走 unsupported。

curl -s 'http://127.0.0.1:PORT/review-outbox/api/preview?id=3f2a…'
{
  "preview": {
    "kind": "text",
    "path": "/Users/me/reports/q3.md",
    "bytes": 2048,
    "text": "# 华东区渠道回款变化\n…"
  }
}

kind 取值:text、image(带 mime、dataUrl)、unsupported(带 extension)、unavailable。文件在工作区外时,除非插件配置了 allowOutsideWorkspace,否则拒绝读取。

GET /review-outbox/api/receipt

导出独立验收单。返回 HTML,content-disposition: attachment,文件名形如 review-receipt-<id>.html。这份文件不依赖本机服务,可以直接发给别人。

curl -s -OJ 'http://127.0.0.1:PORT/review-outbox/api/receipt?id=3f2a…'

响应不是 JSON,是一个完整的 HTML 文档,内含当前证据的 SHA-256 摘要与每条决策的时间。

GET /review-outbox/api/diff

工作区变更类的成果,取这次改动的 diff。其它来源的成果返回 400。

curl -s 'http://127.0.0.1:PORT/review-outbox/api/diff?id=3f2a…'
{ "preview": { "kind": "text", "text": "--- a/q3.md\n+++ b/q3.md\n@@ -1,3 +1,4 @@\n…" } }

宿主没有提供 workspaceChanges 服务,或 diff 超时(5 秒),都会返回 { "preview": { "kind": "unavailable" } },状态码仍是 200。

POST /review-outbox/api/sample

在空配置里造一条示例成果,让整条流程(预览 → 处置 → 验收单)在第一个真实成果出现前就能走一遍。写一个小 Markdown 文件到 ~/review-outbox/sample/ 并入队,带 research-report 验收包。

curl -s -X POST http://127.0.0.1:PORT/review-outbox/api/sample
{
  "version": 1,
  "items": [
    {
      "id": "8b71…",
      "status": "pending",
      "path": "/Users/me/review-outbox/sample/sample-review-m3x1p2.md",
      "reviewPack": { "id": "research-report", "version": 1 },
      "reviewProgress": { "completed": 0, "total": 5, "requiredCompleted": 0, "requiredTotal": 4, "complete": false }
    }
  ],
  "pending": 1
}

状态码是 201,不是 200——这是这份文档里唯一一条非 200 的成功响应。写客户端时按 2xx 判断,别按 200。

POST /review-outbox/api/pack

给一条成果换验收包。传空 packId 表示清空,回到无清单状态。

curl -s -X POST http://127.0.0.1:PORT/review-outbox/api/pack \
  -H 'content-type: application/json' \
  -d '{"id":"3f2a…","packId":"research-report"}'
{ "item": { "id": "3f2a…", "reviewPack": { "id": "research-report" } }, "pending": 1 }

packId 不存在返回 400 {"error":"Review pack not found"}。

POST /review-outbox/api/check

勾选或取消一项验收证据。checked 必须是布尔值,detail 是书面证据,非字符串会被当成空串。

curl -s -X POST http://127.0.0.1:PORT/review-outbox/api/check \
  -H 'content-type: application/json' \
  -d '{"id":"3f2a…","checkId":"claims","checked":true,"detail":"第 1 节的三个结论各自对应一份渠道回款明细"}'
{
  "item": {
    "id": "3f2a…",
    "reviewPack": { "checks": { "claims-evidence": { "checked": true, "detail": "第 1 节的三个结论各自对应一份渠道回款明细" } } },
    "reviewProgress": { "completed": 1, "total": 5, "requiredCompleted": 1, "requiredTotal": 4, "complete": false, "incomplete": ["citations-accessible", "data-scope", "method-limitations"] }
  },
  "pending": 1
}

两种 400 的判定顺序是先查清单、后查类型:id 指向的成果不存在或没有验收包时,无论如何都先得到 {"error":"Review check not found"};只有当 checkId 确实在当前包里,checked 不是布尔才会得到 {"error":"checked must be a boolean"}。

POST /review-outbox/api/backfill

触发一次回填扫描:把历史上已经交过、但没进队列的成果补进来。立即返回,扫描在后台继续,进度看 backfill。

curl -s -X POST http://127.0.0.1:PORT/review-outbox/api/backfill
{
  "version": 1,
  "items": [],
  "pending": 0,
  "backfill": { "status": "running", "listed": 0, "scanned": 0, "discovered": 0, "changed": 0, "truncated": false, "errors": [], "startedAt": "2026-11-19T04:30:00.000Z", "finishedAt": null }
}

扫描过程中 status 为 running,结束后变 done。errors 里每条是 { path, message }——单个文件读不了不会中断整轮。宿主没有提供会话持久化服务时,status 直接是 unavailable。

POST /review-outbox/api/action

对一条成果做处置。action 取 approve、return、archive、reopen。

curl -s -X POST http://127.0.0.1:PORT/review-outbox/api/action \
  -H 'content-type: application/json' \
  -d '{"id":"3f2a…","action":"approve","note":"四项证据齐了"}'
{ "item": { "id": "3f2a…", "status": "approved" }, "pending": 0 }

approve 与 return 会先快照当前证据(SHA-256),并检查四项必填证据是否齐全;没齐返回 400,不会写入状态。archive 不要求证据。

按会话批量处置:传 sessionId 而不是 id 时走批量路径,且只允许 archive。传其它动作返回 400 {"error":"Bulk actions are limited to archive"}。这是有意为之:批准与打回各自携带一个人的决策和证据,只能一条一条来。

curl -s -X POST http://127.0.0.1:PORT/review-outbox/api/action \
  -H 'content-type: application/json' \
  -d '{"sessionId":"sess-9c1","action":"archive","note":"本轮无关成果,整批归档"}'
{ "archived": 47, "pending": 52 }

该会话里没有待处置成果时返回 400,而不是 archived: 0:

{ "error": "No pending items in this session" }

错误形状

所有错误都是 {"error": "<一句话>"},没有错误码字段,也没有 envelope。按状态码区分:

状态码何时
400请求体不是合法 JSON、必填字段缺失、checkId/packId 不存在、checked 不是布尔、批量处置用了 archive 以外的动作、批量归档了一个没有待处置成果的会话(No pending items in this session)、对非工作区变更取 diff
403DSH 的 connection 服务不可用,整条前缀一律拒绝
404路由不存在({"error":"Route not found"})、?id= 找不到成果、GET /receipt 的目标文件已不在磁盘
405不会出现:方法不匹配时落到 404,而不是 405

405 那一行是照代码写的实测结论:分发用的是「方法 + 末段路径」的精确比较,没有单独的方法校验分支,所以 PUT /items 返回的是 404 而不是 405。写接口客户端时不要依赖 405。

复现

这份文档里的每个形状都可以用两条命令核对:

npm test                      # 含路由与面板的一致性测试
node -e 'import("./src/host.js").then(m=>console.log(typeof m.apply))'

接口的实际分支在 src/host.js 的 handler 里,路径常量是同一文件顶部的 API_PREFIX。

test/route-contract.test.js 把这份文档里的每个状态码和响应形状都对着真 handler 断言了一遍,包括上面那个 404-而不是-405 的怪处和批量处置只收 archive 的约束。文档与代码不一致时以代码为准;不一致到那条测试会红,所以通常轮不到你来发现。

第一版这份文档里写错了六处,全部是先写文档、后跑探针才发现的:backfill 的字段名(写成 running/queued,实际是 status 加四个计数器)、批量归档空会话的返回(以为 200 带 archived: 0,实际 400)、check 两种 400 的判定顺序、reviewProgress 的字段(写成 checked/total/ready,实际是 completed/requiredCompleted/complete/incomplete)、以及包的 checks 是数组而成果里的 reviewPack.checks 是对象。最后两条是前端最常读的字段。第六处是 POST /sample:第一版根本没写这条路由,而且它返回 201 而不是 200。

原文:docs/API.md · 状态码由 test/route-contract.test.js 对着真 handler 断言。