@tibame201020/queqiao-http

English | 繁體中文

Queqiao 的官方 curl-like HTTP extension。

@tibame201020/queqiao-http 讓已 attach 的 Queqiao Worker 取得方便的 http_request 能力，可直接發送 HTTP/HTTPS request。安裝／attach extension 本身就是信任決策；extension 不再維護 origin allowlist。

底層直接使用 Worker 執行環境的 native fetch，不執行 curl、shell 或 child_process。

狀態

v0.1.3 對應 Queqiao 0.9.7。Canonical npm package 為 @tibame201020/queqiao-http。

自 v0.1.1 起，npm 發布由 GitHub Release workflow 透過 npm Trusted Publishing + provenance 自動處理。

目前 request path：

MCP client / LLM
→ Queqiao Gateway
→ Queqiao Worker
→ stable extension proxy
→ queqiao-http
→ direct HTTP/HTTPS request
→ target service

已驗證行為包括：

• JSON GET/POST request；
• JSON request 自動 serialize、JSON response 自動 parse；
• backend HTTP 4xx 保留為正常 HTTP response；
• 可呼叫任意 HTTP/HTTPS origin，包括 localhost、WSL/private-network IP 與網際網路 origin；
• 安裝或更新 extension 不會擴張 Queqiao 公開 connector manifest。

安裝

queqiao extension install npm:@tibame201020/queqiao-http --attach-all

或先安裝到 Extension Hub，再 attach 到指定 Worker：

queqiao extension install npm:@tibame201020/queqiao-http
queqiao extension attach dev.queqiao.http --worker windows

attach 即 activation。

Network authority

queqiao-http 不再有 per-origin grant list。

安裝並 attach 此 extension，即明確授權它從 Worker 發送 HTTP/HTTPS request。這是刻意設計：此 extension 的定位是方便的 curl-like network capability，而不是綁定某個服務的 adapter。

Package manifest 因此不宣告 managed-runtime HTTP origin：

{
  "runtime": {
    "processes": { "allow": [] },
    "outboundHttp": { "allowOrigins": [] }
  }
}

allowOrigins 為空是刻意的，因為 v0.1.3 已不再透過 context.runtime.http.request() 發送 request。

Capability

queqiao-http 只註冊一個 capability：http_request。

輸入欄位：

• workspaceId — 選定的 Queqiao Workspace；
• url — 完整 HTTP 或 HTTPS URL；
• method — GET | POST | PUT | PATCH | DELETE | HEAD，預設 GET；
• headers — optional string header map；
• body — optional raw string body；
• json — optional JSON value，與 body 互斥；
• timeoutMs — 100 到 120000，預設 30000。

提供 json 時，extension 會自動 serialize，且 caller 未提供 Content-Type 時會補上 content-type: application/json。

範例

{
  "workspaceId": "codes",
  "operation": "call",
  "extensionId": "dev.queqiao.http",
  "capability": "http_request",
  "arguments": {
    "url": "http://172.31.39.34:9889/api/meal/types",
    "method": "GET"
  }
}

Response contract

非 2xx status 會保留為普通 downstream HTTP response：

{
  "status": 200,
  "headers": { "content-type": "application/json" },
  "body": "{\"ok\":true}",
  "json": { "ok": true }
}

只有 response body 能成功 parse 為 JSON 時才提供 json；body 保留文字 response。

信任邊界

Queqiao extension 屬於 trusted plugin code。安裝並 attach queqiao-http，代表授權此 extension 從該 Worker 對外發送 open-world HTTP/HTTPS request。

Queqiao 仍負責 package install/attach、Extension contract validation、Gateway → Worker routing 與 ExtensionHost lifecycle。Extension 本身負責 request schema、限制 URL scheme 為 HTTP/HTTPS、timeout、直接 fetch 與 response normalize。

process allowlist: empty
shell access: none
curl execution: none
child_process: none
origin allowlist: none
direct global fetch: yes
risk: execute
openWorldHint: true

開發

npm ci
npm run check
npm pack --ignore-scripts --dry-run

發布

main CI passes
→ tag v<package-version>
→ publish matching GitHub Release
→ Publish npm workflow
→ npm Trusted Publishing + provenance

另見 docs/releasing.md。

授權

MIT