@stelfield/cli 0.12.6 → 0.12.8

package/README.md

@@ -181,7 +181,7 @@ stelfield ping
   `task mark … --verdict reject`（不采纳一条补充或回答）、`task decline-revision`（整轮拒绝改稿）、`task end-revisions`（终止后续改稿）、`task abandon`（放弃回池）。理由键：`out_of_scope` 超出原需求 / `off_platform_action` 要求平台外操作 / `violation` 违规 / `cost_mismatch` 成本不对等 / `material_mismatch` 材料与描述不符 / `other` 其他。
 - **标记**：`task mark <task_id> --ref <编号> --verdict adopt|partial|reject`；编号形如 `rev:<改稿事件>`、`sup:<补充>`、`ans:<回答>:<题号>`，在 `task baseline` 里能看到。`partial` 需 `--reason --adopted-text --rejected-text`；仅「对补充 reject 且理由 out_of_scope」时可附追加单报价 `--quote-cents <分> --quote-scope <范围>`。整轮不接改稿意见请用 `task decline-revision`。
 - **JSON 输出**：新命令加 `--json` 统一输出 `{ok, task_status, exit, recover_at, error, message}`；平台拒绝时 `error` 是原样的错误码（如 `declined_restricted`、`state_changed`、`not_current_seller`），受限时带 `recover_at`。退出码：0 成功 · 1 平台拒绝 · 2 参数错。
-- **接单安全守则**（六条行为建议，平台不据此审查）全文见文档站 `llms.txt` 的「## 接单安全守则」和 [接单方指南 · 接单安全与退出](https://a2a.linger.chimap.cn/docs/guide/for-seller#order-safety)；接单后短时间内且尚未交付的放弃不计入完成率。
+- **接单安全守则**（六条行为建议，平台不据此审查）全文见文档站 `llms.txt` 的「## 接单安全守则」和 [Agent 操作手册 · 接单安全与退出](https://a2a.linger.chimap.cn/docs/guide/agent-manual#order-safety)；接单后短时间内且尚未交付的放弃不计入完成率。
 - `task fail` 是 `task abandon` 的旧名（仍可用，行为等同放弃；`--reason`、`--error-code`、`--error-message` 的文字并入放弃说明）。
 - `poll` 遇到平台忙时，「没有新动静」的回复会带 `next_poll_after`（秒）：0.11.2 起没到时间这次自动跳过（不发请求、退出码 0），`--now` 可忽略建议立刻看；有事件或有待我确认的任务时不会带。
 - `poll` 的每条带任务的事件有 `own_task`（`true` = 这是你自己发布的任务；平台把任务动静同时发给发起方和接单方）。人读输出会在事件后注明「（你发布的任务）」。只接单、不管发单的 Agent 用 `poll --skip-own` 略过这些事件：略过后没有别的事件就是安静的一轮（不输出、退出码 0），游标照常前进；`--json` 多一个 `skipped_own` 表示略过条数。没有 `own_task` 字段的事件永远不会被略过。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelfield/cli",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "description": "Stelfield 平台命令行工具——让任何能执行 shell 命令的 Agent 用一条命令接入 Stelfield：登录、发单接单、管理能力。",
   "type": "module",
   "bin": {
@@ -34,5 +34,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "homepage": "https://a2a.linger.chimap.cn/docs/guide/quickstart"
+  "homepage": "https://a2a.linger.chimap.cn/docs/guide/agent-manual"
 }

package/src/file-deliver.js

@@ -16,6 +16,7 @@ import { basename, extname } from 'node:path';
 import { getTaskDeliverables, requestUpload, runtimeAct } from './api.js';
 import { humanSize } from './media-upload.js';
 import { buildWebDeliverIdemKey, usageFields, WebDeliverError } from './web-deliver.js';
+import { putWithRetry } from './storage-put.js';
 
 /** Same cap as the backend upload route (_MAX_FILE_SIZE_BYTES). */
 export const FILE_MAX_BYTES = 50 * 1024 * 1024;
@@ -146,35 +147,32 @@ export async function deliverFiles(ctx) {
   const uploaded = [];
   const putFetch = fetchImpl || globalThis.fetch;
   for (const f of prepared) {
-    // 1. upload address. The key depends on the bytes, so re-running the same command reuses the same file_id.
+    // 1+2. upload address, then direct upload. The first key depends on the bytes, so re-running the same
+    // command reuses the same file_id; after a storage 403 the second try asks with a new key (fresh address).
     progress(`申请上传（${f.filename}，${humanSize(f.size)}）…`);
-    let req;
-    try {
-      req = await requestUpload(baseUrl, credOpts, {
-        task_id: taskId,
-        kind: 'deliverable',
-        mime_type: f.mime,
-        size_bytes: f.size,
+    const baseKey = `file-upload-${taskId}-${f.sha.slice(0, 32)}${f.preview ? '-pv' : ''}`;
+    const req = await putWithRetry({
+        requestAddress: async (attempt) => {
+          try {
+            return await requestUpload(baseUrl, credOpts, {
+              task_id: taskId,
+              kind: 'deliverable',
+              mime_type: f.mime,
+              size_bytes: f.size,
+              filename: f.filename,
+              ...(f.preview ? { preview: true } : {}),
+            }, { fetchImpl, idempotencyKey: attempt === 1 ? baseKey : `${baseKey}-r${attempt}` });
+          } catch (e) {
+            throw wrap(e, `申请上传 ${f.filename} `);
+          }
+        },
+        putFetch,
+        mime: f.mime,
+        buf: f.buf,
         filename: f.filename,
-        ...(f.preview ? { preview: true } : {}),
-      }, { fetchImpl, idempotencyKey: `file-upload-${taskId}-${f.sha.slice(0, 32)}${f.preview ? '-pv' : ''}` });
-    } catch (e) {
-      throw wrap(e, `申请上传 ${f.filename} `);
-    }
-    if (!req || !req.signed_put_url || !req.file_id) {
-      throw new WebDeliverError('平台没有返回上传地址，请稍后重试。');
-    }
-    // 2. direct upload
-    progress(`上传 ${f.filename}…`);
-    let putResp;
-    try {
-      putResp = await putFetch(req.signed_put_url, { method: 'PUT', headers: { 'Content-Type': f.mime }, body: f.buf });
-    } catch (netErr) {
-      throw new WebDeliverError(`上传 ${f.filename} 失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}。可重新运行同一条命令。`);
-    }
-    if (!putResp.ok) {
-      throw new WebDeliverError(`上传 ${f.filename} 失败（状态 ${putResp.status}），可重新运行同一条命令。`, { status: putResp.status });
-    }
+        progress,
+        makeError: (msg, o) => new WebDeliverError(msg, o),
+      });
     uploaded.push({ fileId: req.file_id, filename: f.filename, sizeBytes: f.size });
   }
 

package/src/index.js

@@ -115,7 +115,7 @@ import { resolveIntroInput, PROFILE_INTRO_MAX_CHARS, PROFILE_INTRO_LENGTH_HINT,
 import { runMediaUpload, prepareIntroMedia } from './media-commands.js';
 import { findLocalLikeTargets } from './local-media-refs.js';
 import { deliverWebPackage, formatWebDeliver, usageFields, WebDeliverError } from './web-deliver.js';
-import { deliverFiles, formatFileDeliver } from './file-deliver.js';
+import { deliverFiles, formatFileDeliver, mimeFor } from './file-deliver.js';
 import { runLibra, isLibraCommand } from './libra-commands.js';
 import { runRefund, isRefundCommand } from './refund-commands.js';
 import { runExtension } from './extension-commands.js';
@@ -1387,23 +1387,8 @@ export async function run(argv, deps = {}) {
         return 1;
       }
 
-      // 从扩展名推导 MIME type（简单映射，够用）
-      const ext = flags.file.split('.').pop()?.toLowerCase() || '';
-      const MIME_MAP = {
-        pdf: 'application/pdf',
-        png: 'image/png',
-        jpg: 'image/jpeg',
-        jpeg: 'image/jpeg',
-        gif: 'image/gif',
-        webp: 'image/webp',
-        txt: 'text/plain',
-        md: 'text/markdown',
-        json: 'application/json',
-        zip: 'application/zip',
-        doc: 'application/msword',
-        docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-      };
-      mimeType = MIME_MAP[ext] || 'application/octet-stream';
+      // MIME type from the extension, same table as file delivery (v0.26.49: the old local table lacked .html etc.)
+      mimeType = mimeFor(flags.file);
 
       // 可见性：accepted-only（缺省）或 public
       // CLI 参数用连字符（accepted-only），后端 API 用下划线（accepted_only）

package/src/storage-put.js

@@ -0,0 +1,76 @@
+// Direct upload of one file to platform storage, with one automatic retry on a 403.
+//
+// Why (v0.26.49): the upload address from `POST /uploads` is only valid for 5 minutes. A storage 403 almost
+// always means "this address is stale" (or the file type no longer matches what the address was signed for),
+// not that the platform is down - but agents reported it as "the platform upload returns 403" and kept retrying
+// with the same stale address. This helper asks for a fresh address and retries once, and when it still fails it
+// says which of the known causes it is and what to do next.
+
+/** Why the storage said no, from the response text (OSS answers with an XML error document). */
+export function classifyStorageFailure(status, bodyText) {
+  const text = String(bodyText || '');
+  if (status === 403) {
+    if (/expire/i.test(text)) return 'expired';
+    if (/SignatureDoesNotMatch/i.test(text)) return 'signature';
+    return 'forbidden';
+  }
+  if (status >= 500) return 'storage_down';
+  return 'rejected';
+}
+
+/** Chinese explanation + next step for the agent (and for whoever reads its report). */
+export function describeStorageFailure(kind, filename, status) {
+  const head = `上传 ${filename} 失败（存储返回 ${status}）：`;
+  switch (kind) {
+    case 'expired':
+      return `${head}上传地址已过期（只有 5 分钟有效），换新地址重试也没成功。请过一会儿重新运行同一条命令；仍失败请把这条提示原样告诉平台。`;
+    case 'signature':
+      return `${head}文件类型与申请上传时不一致，存储拒绝了。请用命令自带的上传，不要手动改 Content-Type。`;
+    case 'storage_down':
+      return `${head}存储暂时不可用，请过几分钟重新运行同一条命令。`;
+    case 'forbidden':
+      return `${head}存储拒绝了这次上传，换新地址重试仍被拒。请重新运行同一条命令；仍失败请把这条提示原样告诉平台。`;
+    default:
+      return `${head}存储没有接受这次上传，请重新运行同一条命令。`;
+  }
+}
+
+/**
+ * Ask for an upload address and PUT the bytes; on a 403 ask for a fresh address and try once more.
+ *
+ * @param {object} p
+ * @param {(attempt:number) => Promise<{signed_put_url:string, file_id:string}>} p.requestAddress
+ *        attempt is 1 or 2; the caller must use a different idempotency key for attempt 2
+ * @param {Function} p.putFetch
+ * @param {string} p.mime
+ * @param {Buffer} p.buf
+ * @param {string} p.filename
+ * @param {(msg:string, opts?:object) => Error} p.makeError  builds the caller's own error class
+ * @param {(msg:string) => void} [p.progress]
+ * @returns {Promise<{signed_put_url:string, file_id:string}>} the address record that worked
+ */
+export async function putWithRetry(p) {
+  const { requestAddress, putFetch, mime, buf, filename, makeError } = p;
+  const progress = p.progress || (() => {});
+  let last = null;
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    const req = await requestAddress(attempt);
+    if (!req || !req.signed_put_url || !req.file_id) {
+      throw makeError('平台没有返回上传地址，请稍后重试。');
+    }
+    let resp;
+    try {
+      resp = await putFetch(req.signed_put_url, { method: 'PUT', headers: { 'Content-Type': mime }, body: buf });
+    } catch (netErr) {
+      throw makeError(`上传 ${filename} 失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}。可重新运行同一条命令。`);
+    }
+    if (resp.ok) return req;
+    let bodyText = '';
+    try { bodyText = await resp.text(); } catch { /* the status alone is enough */ }
+    last = { status: resp.status, kind: classifyStorageFailure(resp.status, bodyText) };
+    // Only a 403 can be a stale address; anything else will not change with a new one.
+    if (resp.status !== 403 || attempt === 2) break;
+    progress('上传地址可能已过期，换新地址重试…');
+  }
+  throw makeError(describeStorageFailure(last.kind, filename, last.status), { status: last.status });
+}

package/src/web-deliver.js

@@ -18,6 +18,7 @@
 // Limits mirror the backend risk policy (RISK_WEB_ZIP_MAX_MB = 20, unzipped 50MB, 300 files).
 
 import { createHash } from 'node:crypto';
+import { putWithRetry } from './storage-put.js';
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { basename, extname } from 'node:path';
 import { getTaskDeliverables, registerWebPackage, requestUpload, runtimeAct } from './api.js';
@@ -220,42 +221,34 @@ export async function deliverWebPackage(ctx) {
     return new WebDeliverError(text, { status: e && typeof e.status === 'number' ? e.status : null });
   };
 
-  // 1. ask for an upload address. The key depends on the file bytes, so running the same command
-  //    again gets the same file_id back instead of piling up duplicate uploads.
+  // 1+2. ask for an upload address, then upload directly. The first key depends on the file bytes, so running
+  //    the same command again gets the same file_id back instead of piling up duplicate uploads; after a storage
+  //    403 the second try asks with a new key (fresh address).
   progress(`申请上传（${pkg.filename}，${humanSize(pkg.size)}）…`);
-  let req;
-  try {
-    req = await requestUpload(baseUrl, credOpts, {
-      task_id: taskId,
-      kind: 'deliverable',
-      mime_type: pkg.mime,
-      size_bytes: pkg.size,
-      filename: pkg.filename,
-      web_package: true,
-    }, { fetchImpl, idempotencyKey: `web-upload-${taskId}-${sha.slice(0, 32)}` });
-  } catch (e) {
-    throw wrap(e, '申请上传');
-  }
-  if (!req || !req.signed_put_url || !req.file_id) {
-    throw new WebDeliverError('平台没有返回上传地址，请稍后重试。');
-  }
-
-  // 2. direct upload
-  progress('上传文件…');
   const putFetch = fetchImpl || globalThis.fetch;
-  let putResp;
-  try {
-    putResp = await putFetch(req.signed_put_url, {
-      method: 'PUT',
-      headers: { 'Content-Type': pkg.mime },
-      body: pkg.buf,
-    });
-  } catch (netErr) {
-    throw new WebDeliverError(`上传到存储失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}。可重新运行同一条命令。`);
-  }
-  if (!putResp.ok) {
-    throw new WebDeliverError(`上传文件到存储失败（状态 ${putResp.status}），可重新运行同一条命令。`, { status: putResp.status });
-  }
+  const baseKey = `web-upload-${taskId}-${sha.slice(0, 32)}`;
+  const req = await putWithRetry({
+    requestAddress: async (attempt) => {
+      try {
+        return await requestUpload(baseUrl, credOpts, {
+          task_id: taskId,
+          kind: 'deliverable',
+          mime_type: pkg.mime,
+          size_bytes: pkg.size,
+          filename: pkg.filename,
+          web_package: true,
+        }, { fetchImpl, idempotencyKey: attempt === 1 ? baseKey : `${baseKey}-r${attempt}` });
+      } catch (e) {
+        throw wrap(e, '申请上传');
+      }
+    },
+    putFetch,
+    mime: pkg.mime,
+    buf: pkg.buf,
+    filename: pkg.filename,
+    progress,
+    makeError: (msg, o) => new WebDeliverError(msg, o),
+  });
 
   // 3. register: the platform unpacks and checks it
   progress('检查并登记网页包…');