@xyagent/cli 0.0.1

package/src-ext/core/bridgeSelfUninstall.mjs

@@ -0,0 +1,133 @@
+// bridge 自卸载工具 —— bridge 主循环检测到对端解绑（HTTP 404/410 on
+// /requests/next）时调用：清本地 pair state + spawn `agentlink uninstall`
+// 把 launchd / systemd-user / schtasks 服务也卸了，然后 bridge 进程 exit(0)。
+//
+// 为什么 spawn 子进程而不是直接调 serviceUninstall：
+//   - launchd 自己管理 plist 注销时机；当前进程是 plist 拉起来的，直接调
+//     launchctl unload 会让 launchd 立刻 kill 自己进程，cleanup 可能没跑完
+//     就被 SIGTERM。
+//   - 子进程拿到 plist 路径独立跑 unload，对父进程无影响；父进程 exit(0) 之后
+//     KeepAlive 仍可能拉起一次，那一次会 preflight-fail（pair state 已清，
+//     bridge_token 没了）直接退出，10s ThrottleInterval 之后子进程 unload
+//     完成 → 不会再拉起。
+//   - --keep-state / --skip-server-revoke 让 uninstall 跳过两个已完成的步骤
+//     （state 已清 + 对端已经主动解绑给我们了），只跑 serviceUninstall。
+//
+// findCliBinary：bridge 自身是被 \`agentlink-agent\` 拉起来的，但 process.argv[0]
+// 是 node 路径，argv[1] 是 src/agentlink-agent.js。要找 \`agentlink\` CLI 入口
+// （npm bin 链接），先看 \`which agentlink\`，再 fallback PATH 常见位置。
+
+import { execFile, spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function findCliBinary() {
+  try {
+    const r = spawnSync("which", ["agentlink"], { encoding: "utf8", timeout: 2000 });
+    if (r.status === 0) {
+      const p = String(r.stdout || "").trim().split("\n")[0];
+      if (p && fs.existsSync(p)) return p;
+    }
+  } catch { /* fall through */ }
+  // 常见 npm bin
+  for (const candidate of [
+    path.join(os.homedir(), ".local", "node-22", "bin", "agentlink"),
+    "/usr/local/bin/agentlink",
+    "/opt/homebrew/bin/agentlink",
+  ]) {
+    try { if (fs.existsSync(candidate)) return candidate; } catch { /* skip */ }
+  }
+  return null;
+}
+
+/**
+ * @param {{ runtime: string, log: any }} opts
+ *   runtime: hermes / claude / codex / openclaw / picoclaw
+ *   log:     bridge 自己的 logger（已经带 cid / gw context）
+ *
+ * 返回 Promise，不抛错 —— 任一步失败都 best-effort，最差也就是用户手动
+ * \`agentlink uninstall -r <runtime>\`。
+ */
+export async function bridgeSelfUninstall({ runtime, log } = {}) {
+  const slog = log?.child ? log.child({ comp: "self-uninstall" }) : log;
+  slog?.info?.("bridge.self_uninstall.start",
+    "binding revoked by remote, self-uninstalling", { runtime });
+
+  // 1. 清本地 pair state（best-effort，import 失败也无所谓）
+  try {
+    const { clearPairState, clearCursor } = await import("./pairCodeClient.mjs");
+    clearPairState(runtime);
+    clearCursor(runtime);
+    slog?.info?.("bridge.self_uninstall.state_cleared",
+      "local pair state cleared", { runtime });
+  } catch (err) {
+    slog?.warn?.("bridge.self_uninstall.state_err",
+      "clear pair state failed (continuing)",
+      { err: err?.message || String(err) });
+  }
+
+  // 2. spawn `agentlink uninstall` 卸 service plist（detached + unref，
+  //    我们 exit 之后子进程继续干活）
+  const bin = findCliBinary();
+  if (!bin) {
+    slog?.warn?.("bridge.self_uninstall.no_cli",
+      "找不到 agentlink CLI；service plist 需用户手动清理", {});
+    return { ok: false, reason: "no-cli" };
+  }
+  try {
+    const child = spawn(bin, [
+      "uninstall",
+      "-r", runtime,
+      "--keep-state",          // state 我们刚清了，不要重复
+      "--skip-server-revoke",  // server 那边已经解绑（404 触发的就是它）
+    ], {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+    });
+    child.unref();
+    slog?.info?.("bridge.self_uninstall.spawned",
+      "agentlink uninstall spawned (detached)",
+      { runtime, cli: bin, child_pid: child.pid });
+    return { ok: true, pid: child.pid };
+  } catch (err) {
+    slog?.warn?.("bridge.self_uninstall.spawn_err",
+      "spawn agentlink uninstall failed (continuing to exit)",
+      { err: err?.message || String(err) });
+    return { ok: false, reason: "spawn-fail" };
+  }
+}
+
+/**
+ * 包一层 worker.run() —— catch revoked 错误，调 self-uninstall 后 exit(0)；
+ * 其它错误按原逻辑 exit(1)。
+ *
+ * 各 runtime 的 bridge entry 现在只需把:
+ *   try { await worker.run(handleRequest); } catch (err) {
+ *     log.error("bridge.fatal", ...); process.exit(1);
+ *   }
+ * 替换为:
+ *   await runWorkerWithRevokeHandling({ worker, handler, runtime, log });
+ */
+export async function runWorkerWithRevokeHandling({
+  worker, handler, runtime, log,
+} = {}) {
+  try {
+    await worker.run(handler);
+    // 正常退出 —— worker 主动 stop() 才走这里
+    process.exit(0);
+  } catch (err) {
+    if (err?.revoked === true) {
+      await bridgeSelfUninstall({ runtime, log });
+      // exit 0 让 launchd KeepAlive 看到 SuccessfulExit；即使再被拉起,
+      // 下一轮 bridge 没 bridge_token 会 preflight-fail 退出,unload 完成
+      // 之后就不再拉起了。
+      process.exit(0);
+    }
+    log?.error?.("bridge.fatal", "worker run errored", {
+      err: err?.message || String(err),
+    });
+    process.exit(1);
+  }
+}

package/src-ext/core/claudeTrust.mjs

@@ -0,0 +1,74 @@
+/**
+ * claudeTrust.mjs — 向 ~/.claude.json 写入工作区信任记录
+ *
+ * writeCaudeTrust(absPath, { _claudeJsonPath? })
+ *   → Promise<void>
+ *
+ * 写入 projects[absPath] = { hasTrustDialogAccepted: true }
+ * 注意：key 必须是 hasTrustDialogAccepted（scanWorkspaces.mjs:263 检查此 key）
+ *
+ * 幂等：若已存在则不覆盖。
+ * 原子写回：write tmp → rename，避免并发写损坏。
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+
+/**
+ * 返回默认 ~/.claude.json 路径
+ */
+function defaultClaudeJsonPath() {
+  return path.join(os.homedir(), ".claude.json");
+}
+
+/**
+ * 向 ~/.claude.json 写入信任记录（原子写回）。
+ *
+ * @param {string} absPath  工作区绝对路径（作为 projects key）
+ * @param {{ _claudeJsonPath?: string }} opts  可注入路径（测试用）
+ */
+export async function writeCaudeTrust(absPath, { _claudeJsonPath } = {}) {
+  const claudeJsonPath = _claudeJsonPath ?? defaultClaudeJsonPath();
+
+  // 读取（不存在时用 {}）
+  let data = {};
+  let raw = "";
+  try {
+    raw = await fs.readFile(claudeJsonPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    // 文件不存在：从空对象开始
+  }
+  if (raw.trim().length > 0) {
+    try {
+      data = JSON.parse(raw);
+    } catch (err) {
+      // JSON 损坏：绝不静默重写整个文件（~/.claude.json 内含 auth/history 等关键数据，
+      // 从 {} 重来会把它全抹掉）。抛错让上层感知，由用户/调用方处置。
+      const e = new Error(`~/.claude.json parse failed, refusing to overwrite: ${err.message}`);
+      e.kind = "parse_failed";
+      throw e;
+    }
+  }
+
+  // 确保 projects 字段存在
+  if (!data.projects || typeof data.projects !== "object") {
+    data.projects = {};
+  }
+
+  // 幂等：已存在则不覆盖
+  if (data.projects[absPath] !== undefined) return;
+
+  // 写入信任记录
+  data.projects[absPath] = { hasTrustDialogAccepted: true };
+
+  // 原子写回（write tmp → rename）
+  const dir = path.dirname(claudeJsonPath);
+  await fs.mkdir(dir, { recursive: true });
+
+  const tmpPath = claudeJsonPath + ".tmp." + randomBytes(6).toString("hex");
+  await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+  await fs.rename(tmpPath, claudeJsonPath);
+}

package/src-ext/core/codexTrust.mjs

@@ -0,0 +1,77 @@
+/**
+ * codexTrust.mjs — 向 ~/.codex/config.toml 写入工作区信任记录
+ *
+ * writeCodexTrust(absPath, { _configPath? })
+ *   → Promise<void>
+ *
+ * 写入 [projects."<absPath>"] trust_level = "trusted"
+ * 复用 vendored smol-toml round-trip，与 mcpConfigAdapter.mjs 模式一致。
+ *
+ * 幂等：trust_level 已存在时不重写。
+ * mode 0o600，不销毁其它 section。
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TOML = await import(
+  path.join(__dirname, "../../src-shared/vendor/smol-toml/dist/index.js")
+);
+
+/**
+ * 返回默认 ~/.codex/config.toml 路径
+ */
+function defaultConfigPath() {
+  return path.join(os.homedir(), ".codex", "config.toml");
+}
+
+/**
+ * 向 ~/.codex/config.toml 写入工作区信任记录。
+ *
+ * @param {string} absPath  工作区绝对路径（作为 projects key）
+ * @param {{ _configPath?: string }} opts  可注入路径（测试用）
+ */
+export async function writeCodexTrust(absPath, { _configPath } = {}) {
+  const configPath = _configPath ?? defaultConfigPath();
+
+  // 读取（不存在时用空文档）
+  let raw = "";
+  try {
+    raw = await fs.readFile(configPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+
+  // TOML parse（空文档 → {}）
+  let cfg = {};
+  if (raw.trim().length > 0) {
+    try {
+      cfg = TOML.parse(raw);
+    } catch (err) {
+      const e = new Error(`codex config.toml parse failed: ${err.message}`);
+      e.kind = "parse_failed";
+      throw e;
+    }
+  }
+
+  // 确保 projects 字段存在
+  if (!cfg.projects || typeof cfg.projects !== "object") {
+    cfg.projects = {};
+  }
+
+  // 幂等：trust_level 已存在且为 "trusted" 则不重写
+  if (cfg.projects[absPath]?.trust_level === "trusted") return;
+
+  // 写入信任记录（merge，不覆盖已有其它字段）
+  cfg.projects[absPath] = {
+    ...(cfg.projects[absPath] ?? {}),
+    trust_level: "trusted",
+  };
+
+  // 确保 ~/.codex/ 目录存在
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configPath, TOML.stringify(cfg), { mode: 0o600 });
+}

package/src-ext/core/cosUploadClient.mjs

@@ -0,0 +1,326 @@
+// cosUploadClient.mjs — agentlink_attach_file 工具的 COS 直传客户端
+//
+// 三步走，与 relay 的 gateway-scoped /v1/gateways/{gw}/uploads/{sign,commit}
+// 完全对应：
+//   1. POST .../uploads/sign   { name, mime, size, sha256 }
+//      → { alreadyUploaded: true, cosObjectKey }  // dedup
+//      → { alreadyUploaded: false, upload: { uploadUrl, headers, ... } }
+//   2. 若 alreadyUploaded=false: PUT uploadUrl with file bytes (用 headers)
+//   3. POST .../uploads/commit { cosObjectKey }
+//      → { attachment: { cosObjectKey, ... } }
+//
+// 错误分类（throw 时挂 .kind）：
+//   kind=sign_failed    — sign 端点失败 (4xx/5xx/network)
+//   kind=put_failed     — PUT COS 失败
+//   kind=commit_failed  — commit 端点失败
+//
+// caller (tool dispatcher) 根据 .kind 映射到 tool result 的 reason 字段。
+//
+// spec ref: openspec/changes/cos-private-read-refactor/specs/host-file-attach-cos/spec.md
+//           openspec/changes/cos-private-read-refactor/specs/relay-gateway-uploads/spec.md
+
+const SIGN_PATH = (gw) => `/v1/gateways/${encodeURIComponent(gw)}/uploads/sign`;
+const COMMIT_PATH = (gw) => `/v1/gateways/${encodeURIComponent(gw)}/uploads/commit`;
+const SIGN_GET_PATH = (gw) => `/v1/gateways/${encodeURIComponent(gw)}/uploads/sign-get`;
+
+// 扩展名 → mime 映射。与 App 端 _AttachmentPreviewHelper.typeOf 的 ext 集合对齐,
+// 这样 CLI 上传的 mime 跟 App 渲染识别的扩展类型一致,避免渲染歧义。
+// 未知扩展走 application/octet-stream（COS 接受,只是 App 端会渲成 "binary"）。
+const EXT_TO_MIME = Object.freeze({
+  // text-like
+  txt: "text/plain",
+  md: "text/markdown",
+  markdown: "text/markdown",
+  log: "text/plain",
+  json: "application/json",
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  yaml: "application/yaml",
+  yml: "application/yaml",
+  xml: "text/xml",
+  html: "text/html",
+  htm: "text/html",
+  svg: "image/svg+xml",
+  // code
+  dart: "text/x-dart",
+  js: "text/javascript",
+  mjs: "text/javascript",
+  cjs: "text/javascript",
+  ts: "text/typescript",
+  tsx: "text/typescript",
+  jsx: "text/javascript",
+  py: "text/x-python",
+  java: "text/x-java",
+  kt: "text/x-kotlin",
+  swift: "text/x-swift",
+  go: "text/x-go",
+  rs: "text/x-rust",
+  c: "text/x-c",
+  h: "text/x-c",
+  cpp: "text/x-c++",
+  hpp: "text/x-c++",
+  // images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  // documents / archives
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  zip: "application/zip",
+  rar: "application/vnd.rar",
+  "7z": "application/x-7z-compressed",
+  // config
+  ini: "text/plain",
+  toml: "application/toml",
+  // shell
+  sh: "text/x-sh",
+  bash: "text/x-sh",
+  zsh: "text/x-sh",
+});
+
+/**
+ * 根据文件名推断 mime。caller 可以覆盖（比如 readFileSync 后用 file 命令猜
+ * binary 类型）。
+ *
+ * @param {string} name 文件名（含扩展名）
+ * @returns {string} mime；未知扩展返回 "application/octet-stream"
+ */
+export function inferMime(name) {
+  const trimmed = (name || "").trim();
+  const dotIdx = trimmed.lastIndexOf(".");
+  if (dotIdx < 0 || dotIdx === trimmed.length - 1) {
+    return "application/octet-stream";
+  }
+  const ext = trimmed.substring(dotIdx + 1).toLowerCase();
+  return EXT_TO_MIME[ext] || "application/octet-stream";
+}
+
+/**
+ * 抛出带 kind 标记的 Error，方便 caller 用 err.kind 分类。
+ */
+function throwKindedError(kind, message, cause) {
+  const err = new Error(message);
+  err.kind = kind;
+  if (cause !== undefined) err.cause = cause;
+  return err;
+}
+
+/**
+ * 三步 sign → conditional PUT → commit，返回最终结果。
+ *
+ * @param {object} opts
+ * @param {string} opts.name                 文件名（不含目录）
+ * @param {Buffer|Uint8Array} opts.content   文件 bytes
+ * @param {string} opts.mime                 MIME 类型
+ * @param {number} opts.size                 字节数（应等于 content.length）
+ * @param {string} opts.sha256               64-char 小写 hex（caller 已算好）
+ * @param {object} opts.relayConfig
+ * @param {string} opts.relayConfig.baseUrl  relay base URL (e.g. http://localhost:8090)
+ * @param {string} opts.relayConfig.gatewayId
+ * @param {string} opts.relayConfig.token    gateway / client bearer token
+ * @param {object} [opts.log]                bridge logger，可选；用于 debug 上传细节
+ * @returns {Promise<{ cosObjectKey: string, deduped: boolean }>}
+ * @throws {Error & { kind: "sign_failed"|"put_failed"|"commit_failed" }}
+ */
+export async function uploadFileToCos(opts) {
+  const { name, content, mime, size, sha256, relayConfig, log } = opts;
+  const childLog = log?.child?.({ comp: "cos-upload" }) || log || console;
+  childLog.info?.("cos-upload.start", "begin upload", {
+    name, mime, size, sha256: sha256?.slice(0, 12),
+  });
+
+  // ── 1. sign ──────────────────────────────────────────────────────
+  let signRes;
+  try {
+    signRes = await postJSON(
+      `${relayConfig.baseUrl}${SIGN_PATH(relayConfig.gatewayId)}`,
+      { name, mime, size, sha256 },
+      relayConfig.token,
+    );
+  } catch (err) {
+    throw throwKindedError("sign_failed", `sign request failed: ${err.message}`, err);
+  }
+  if (!signRes.ok) {
+    throw throwKindedError(
+      "sign_failed",
+      `sign HTTP ${signRes.status}: ${signRes.bodyText?.slice(0, 200)}`,
+    );
+  }
+
+  if (signRes.json?.alreadyUploaded === true) {
+    // dedup 命中:跳过 PUT,直接走 commit 路径(走 commit 是为了拿规范的 attachment
+    // shape；relay 端 commit 在 ledger 行不存在时会返回 deduped:true 但仍 200)
+    const dedupObjectKey = signRes.json.cosObjectKey || signRes.json.objectKey;
+    childLog.info?.("cos-upload.dedup", "sha256 already in COS, skipping PUT", {
+      cosObjectKey: dedupObjectKey,
+    });
+    const commitRes = await commitCall(dedupObjectKey, relayConfig);
+    const dedupResult = { cosObjectKey: commitRes.cosObjectKey, deduped: true };
+    if (commitRes.originalName !== undefined) dedupResult.originalName = commitRes.originalName;
+    return dedupResult;
+  }
+
+  // ── 2. PUT ──────────────────────────────────────────────────────
+  const upload = signRes.json?.upload;
+  if (!upload?.uploadUrl) {
+    throw throwKindedError("sign_failed", "sign response missing upload.uploadUrl");
+  }
+  let cosHost = "";
+  try { cosHost = new URL(upload.uploadUrl).host; } catch { /* swallow */ }
+  childLog.info?.("cos-upload.put.start", "PUT to COS", {
+    objectKey: upload.objectKey, cosHost, size,
+  });
+  const t0 = Date.now();
+  try {
+    const putHeaders = { ...(upload.headers || {}), "Content-Length": String(size) };
+    const putRes = await fetch(upload.uploadUrl, {
+      method: upload.method || "PUT",
+      headers: putHeaders,
+      body: content,
+    });
+    if (!putRes.ok) {
+      const body = await safeReadText(putRes);
+      throw throwKindedError(
+        "put_failed",
+        `COS PUT HTTP ${putRes.status}: ${body.slice(0, 200)}`,
+      );
+    }
+    childLog.info?.("cos-upload.put.ok", "PUT succeeded", {
+      objectKey: upload.objectKey, status: putRes.status, elapsedMs: Date.now() - t0,
+    });
+  } catch (err) {
+    if (err.kind) throw err;
+    throw throwKindedError("put_failed", `COS PUT failed: ${err.message}`, err);
+  }
+
+  // ── 3. commit ───────────────────────────────────────────────────
+  const commitObjectKey = upload.cosObjectKey || upload.objectKey;
+  const commitRes = await commitCall(commitObjectKey, relayConfig);
+  childLog.info?.("cos-upload.done", "commit ok", {
+    cosObjectKey: commitRes.cosObjectKey,
+  });
+  const commitResult = { cosObjectKey: commitRes.cosObjectKey, deduped: false };
+  if (commitRes.originalName !== undefined) commitResult.originalName = commitRes.originalName;
+  return commitResult;
+}
+
+// ── cos-prefix-cache（publicUrl 预测器）已随 publicUrl 字段移除而废弃 ──────────
+// cos-private-read-refactor (D5/D6): 服务端不再返回 publicUrl，改用 sign-get
+// 按需签发临时 GET URL。readCosPrefixCache 保留导出以保持现有调用方不报错，
+// 但始终返回 null；writeCosPrefixCache 已删除。
+
+/**
+ * @deprecated publicUrl 已废弃（cos-private-read-refactor）。此函数始终返回 null。
+ */
+export function readCosPrefixCache() {
+  return null;
+}
+
+/**
+ * 按 cosObjectKey 换取临时 GET URL（presigned）。
+ *
+ * P0「读取笔记内图片失败」: 消息正文里 agentlink-cos://<cosObjectKey> 引用
+ * 需要先换签名 URL 才能下载。失败时 throw kind=sign_get_failed。
+ *
+ * @param {{ baseUrl: string, gatewayId: string, token: string }} relayConfig
+ * @param {string} cosObjectKey
+ * @returns {Promise<{ getUrl: string, expiresAt: string|null, cosObjectKey: string }>}
+ */
+export async function signGetCosObject(relayConfig, cosObjectKey) {
+  let res;
+  try {
+    res = await postJSON(
+      `${relayConfig.baseUrl}${SIGN_GET_PATH(relayConfig.gatewayId)}`,
+      { cosObjectKey },
+      relayConfig.token,
+    );
+  } catch (err) {
+    throw throwKindedError("sign_get_failed", `sign-get request failed: ${err.message}`, err);
+  }
+  if (!res.ok) {
+    throw throwKindedError(
+      "sign_get_failed",
+      `sign-get HTTP ${res.status}: ${res.bodyText?.slice(0, 200)}`,
+    );
+  }
+  const getUrl = res.json?.getUrl;
+  if (!getUrl) {
+    throw throwKindedError("sign_get_failed", "sign-get response missing getUrl");
+  }
+  return {
+    getUrl,
+    expiresAt: res.json?.expiresAt ?? null,
+    cosObjectKey: res.json?.cosObjectKey ?? cosObjectKey,
+  };
+}
+
+/** commit 调用封装；失败时 throw kind=commit_failed */
+async function commitCall(cosObjectKey, relayConfig) {
+  let res;
+  try {
+    res = await postJSON(
+      `${relayConfig.baseUrl}${COMMIT_PATH(relayConfig.gatewayId)}`,
+      { cosObjectKey },
+      relayConfig.token,
+    );
+  } catch (err) {
+    throw throwKindedError("commit_failed", `commit request failed: ${err.message}`, err);
+  }
+  if (!res.ok) {
+    throw throwKindedError(
+      "commit_failed",
+      `commit HTTP ${res.status}: ${res.bodyText?.slice(0, 200)}`,
+    );
+  }
+  const attachment = res.json?.attachment;
+  if (!attachment?.cosObjectKey) {
+    throw throwKindedError("commit_failed", "commit response missing attachment.cosObjectKey");
+  }
+  // originalName：relay 从 app_user_attachments.file_name 读回的原始文件名（未编码），
+  // 供调用方传给 relay_object 构造时的 block.name，进而写入 source.name。
+  // 旧版 relay 不返回此字段；缺失时不写入返回对象（不写 undefined）。
+  const result = { cosObjectKey: attachment.cosObjectKey };
+  const originalName = attachment.originalName;
+  if (typeof originalName === "string" && originalName.length > 0) {
+    result.originalName = originalName;
+  }
+  return result;
+}
+
+/** JSON POST 助手。返回 { ok, status, json, bodyText }。 */
+async function postJSON(url, body, bearerToken) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${bearerToken}`,
+    },
+    body: JSON.stringify(body),
+  });
+  const bodyText = await safeReadText(res);
+  let json = null;
+  if (bodyText) {
+    try {
+      json = JSON.parse(bodyText);
+    } catch {
+      /* not JSON */
+    }
+  }
+  return { ok: res.ok, status: res.status, json, bodyText };
+}
+
+async function safeReadText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}