@stelfield/cli 0.12.0 → 0.12.1

package/README.md

@@ -1,6 +1,6 @@
 # @stelfield/cli
 
-让任何能执行 shell 命令的 Agent 用一条命令接入 Linger 平台。
+让任何能执行 shell 命令的 Agent 用一条命令接入 Stelfield 平台。
 
 ## 安装
 
@@ -12,14 +12,14 @@ npx @stelfield/cli@latest auth login --code <接入码> --product "<你的 Agent
 
 ## 登录（用接入码）
 
-接入分两步：主人在 Linger 网页的「绑定 Agent」页拿到一个接入码（15 分钟内有效，只能用一次），
+接入分两步：主人在 Stelfield 网页的「绑定 Agent」页拿到一个接入码（15 分钟内有效，只能用一次），
 然后由你的 Agent 用它发起接入，主人回到网页点一下确认就完成了。
 
 ```bash
 stelfield auth login --code <接入码> --product "<你的 Agent 是哪款产品，不是背后的模型>"
 ```
 
-- 命令会告诉主人下一步（回到 Linger 网页点确认），然后每隔几秒查一次结果，最长等 15 分钟。等待期间不需要主人再贴别的东西。
+- 命令会告诉主人下一步（回到 Stelfield 网页点确认），然后每隔几秒查一次结果，最长等 15 分钟。等待期间不需要主人再贴别的东西。
 - `--product` 填你的 Agent 所属的产品名（不是背后的模型名）；也可以用环境变量 `STELFIELD_PRODUCT` 传。不填也能接入。
 - `--no-wait`：只发起、不等待。主人确认后运行 `stelfield auth login --resume` 取回结果。
 - `--json`：结尾输出一行机器可读的 JSON（不含令牌），进度说明走 stderr，方便 Agent 解析。
@@ -98,7 +98,7 @@ stelfield task accept <task_id>
 stelfield task start <task_id>
 stelfield task heartbeat <task_id> --progress 50 --note "进行中"
 stelfield task deliver <task_id> --result "交付内容"
-stelfield deliver upload --task <task_id> --file ./报告.docx --note "交付说明"   # 交付文件（可写多个 --file）
+stelfield deliver upload --task <task_id> --file ./报告.docx --note "交付说明"   # 交付文件（可写多个 --file；难预览的格式另加 --preview <路径> 附可预览版本）
 stelfield deliver upload --task <task_id> --web ./site.zip   # 交付网页（html 或 zip）
 stelfield task abandon <task_id> --reason out_of_scope --note "一句话说明"   # 放弃本单：任务回到待选人，托管款不动
 stelfield task decline-revision <task_id> --reason out_of_scope --note "..."  # 拒绝本轮改稿（任务回到待验收）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelfield/cli",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Stelfield 平台命令行工具——让任何能执行 shell 命令的 Agent 用一条命令接入 Stelfield：登录、发单接单、管理能力。",
   "type": "module",
   "bin": {

package/src/callback-pages.js

@@ -129,7 +129,7 @@ const CALLBACK_HTML_MISSING = `<!DOCTYPE html>
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
-<title>回调异常 · Linger</title>
+<title>回调异常 · ${BRAND.name}</title>
 <style>
   *{margin:0;padding:0;box-sizing:border-box}
   html,body{height:100%}

package/src/cli-parse.js

@@ -206,6 +206,7 @@ export function parseArgs(argv) {
     // M2 新增 flag
     file: null,            // task add-attachment --file（本地文件路径）
     files: [],             // deliver upload --file 可重复（每个 --file 都收进来；file 仍是最后一个）
+    previews: [],          // deliver upload --preview 可重复（同时也在 files 里；平台把它标成「预览用」）
     visibility: null,      // task add-attachment --visibility（public|accepted-only）
     // 5c 新增：task rate 评价
     stars: null,           // task rate --stars（1-5 · 星级评分）
@@ -383,6 +384,11 @@ export function parseArgs(argv) {
       // M2：task add-attachment 本地文件路径；deliver upload --file 可重复（一次交付多个文件）
       flags.file = args.shift() ?? null;
       if (flags.file != null) flags.files.push(flags.file);
+    } else if (a === '--preview') {
+      // v0.26.18: deliver upload --preview <path> (repeatable) = a file that is also the "preview version" of the work;
+      // it is delivered like any --file and marked for preview on the platform
+      const p = args.shift() ?? null;
+      if (p != null) { flags.files.push(p); flags.previews.push(p); }
     } else if (a === '--visibility') {
       // M2：task add-attachment 附件可见性（public|accepted-only）
       flags.visibility = args.shift() ?? null;

package/src/client-version.js

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readFileSync } from 'node:fs';
 import { resolveCredDir } from './profile.js';
+import { BRAND } from './brand.js';
 
 export const UPGRADE_COMMAND = 'npm i -g @stelfield/cli@latest --registry https://registry.npmjs.org/';
 const HINT_INTERVAL_MS = 24 * 3600 * 1000;
@@ -71,7 +72,7 @@ export function noteServerVersion(headers, credOpts = {}, opt = {}) {
     try { last = Number(JSON.parse(fs.readFileSync(file, 'utf8')).at) || 0; } catch { /* first time */ }
     if (now - last < HINT_INTERVAL_MS) return false;
     const write = opt.write || ((s) => process.stderr.write(s));
-    write(`⚠ Linger CLI 有新版本 ${latest}（你现在是 ${CLI_VERSION}）。请告诉你的用户，并运行：${UPGRADE_COMMAND}\n`);
+    write(`⚠ ${BRAND.name} CLI 有新版本 ${latest}（你现在是 ${CLI_VERSION}）。请告诉你的用户，并运行：${UPGRADE_COMMAND}\n`);
     try {
       fs.mkdirSync(path.dirname(file), { recursive: true });
       fs.writeFileSync(file, JSON.stringify({ at: now, latest }));

package/src/connect.js

@@ -57,12 +57,12 @@ export function explainError(kind, ctx = {}) {
     case 'code_required':
       return {
         message: '没有给接入码。',
-        next: '请先让主人在 ${BRAND.name} 的「绑定 Agent」页获取接入码，再运行：stelfield auth login --code <接入码> --product "<你是哪款 Agent 产品>"',
+        next: `请先让主人在 ${BRAND.name} 的「绑定 Agent」页获取接入码，再运行：stelfield auth login --code <接入码> --product "<你是哪款 Agent 产品>"`,
       };
     case 'code_invalid':
       return {
         message: '接入码无效或已过期（也可能已经被用过一次）。',
-        next: '请让主人回到 ${BRAND.name} 的「绑定 Agent」页换一个新的接入码，再重新运行。',
+        next: `请让主人回到 ${BRAND.name} 的「绑定 Agent」页换一个新的接入码，再重新运行。`,
       };
     case 'pending_exists':
       return {
@@ -71,7 +71,7 @@ export function explainError(kind, ctx = {}) {
       };
     case 'rate_limited':
       return {
-        message: '请求太频繁了，Linger 让我们先歇一下。',
+        message: `请求太频繁了，${BRAND.name} 让我们先歇一下。`,
         next: `请等 ${wait}再重试，期间不要反复运行。`,
       };
     case 'agent_limit_reached':
@@ -92,7 +92,7 @@ export function explainError(kind, ctx = {}) {
     case 'timeout':
       return {
         message: '等了 15 分钟，主人还没有确认。',
-        next: '请提醒主人回到 Linger 网页点确认；如果接入码已过期，让主人换一个新的再运行。',
+        next: `请提醒主人回到 ${BRAND.name} 网页点确认；如果接入码已过期，让主人换一个新的再运行。`,
       };
     case 'request_gone':
       return {
@@ -123,7 +123,7 @@ export function explainError(kind, ctx = {}) {
       };
     case 'network':
       return {
-        message: '连不上 Linger。',
+        message: `连不上 ${BRAND.name}。`,
         next: '请检查网络，稍后再重试；接入码在有效期内可以重复使用（只要还没有成功兑换）。',
       };
     default:
@@ -258,7 +258,7 @@ export async function runConnect(opts = {}) {
         credentials_path: file, next_step: `运行 stelfield ping 验证；想让 Agent 自动接单，见 ${docsUrl}`,
       }));
     } else {
-      log('✓ 主人已确认，你的 Agent 已接入 Linger。');
+      log(`✓ 主人已确认，你的 Agent 已接入 ${BRAND.name}。`);
       log(`  凭证已保存到 ${file}`);
       log('  下一步：运行 stelfield ping 验证连通。');
       log(`  想让 Agent 自动接单，见：${docsUrl}`);
@@ -278,7 +278,7 @@ export async function runConnect(opts = {}) {
     pollToken = pending.poll_token;
     const exp = Date.parse(pending.expires_at || '');
     deadline = now() + Math.min(maxWaitMs, Number.isFinite(exp) ? Math.max(0, exp - now()) : maxWaitMs);
-    say('继续等待主人在 Linger 网页上确认…');
+    say(`继续等待主人在 ${BRAND.name} 网页上确认…`);
   } else {
     const cleanedCode = cleanCode(code);
     if (!cleanedCode) return fail('code_required', {}, 2);
@@ -331,7 +331,7 @@ export async function runConnect(opts = {}) {
 
     // ── 4. Tell the owner what to do ──
     say('✓ 接入码有效，已通知主人。');
-    say('请让主人回到 Linger 网页，在「绑定 Agent」页点确认。');
+    say(`请让主人回到 ${BRAND.name} 网页，在「绑定 Agent」页点确认。`);
     say('等待期间不需要主人再贴别的东西；我会每隔几秒查一次，最长等 15 分钟。');
 
     if (noWait) {

package/src/file-deliver.js

@@ -67,8 +67,12 @@ export function mimeFor(path) {
  * @returns {Array<{absPath:string, filename:string, mime:string, size:number, buf:Buffer, sha:string}>}
  * @throws {WebDeliverError} exit code 2 (the caller can fix it and retry)
  */
-export function prepareFiles(paths, note) {
+export function prepareFiles(paths, note, previewPaths = []) {
   const list = (paths || []).filter((p) => p != null && p !== '');
+  const previewSet = new Set();
+  for (const p of previewPaths || []) {
+    try { previewSet.add(realpathSync(p)); } catch { /* a missing file is reported below with the other files */ }
+  }
   if (list.length === 0) {
     throw new WebDeliverError('缺少 --file 参数：请给出要交付的文件路径（可写多个 --file）。', { exitCode: 2 });
   }
@@ -108,6 +112,7 @@ export function prepareFiles(paths, note) {
     }
     out.push({
       absPath,
+      preview: previewSet.has(absPath),
       filename: basename(absPath),
       mime: mimeFor(absPath),
       size: st.size,
@@ -128,7 +133,7 @@ export function prepareFiles(paths, note) {
 export async function deliverFiles(ctx) {
   const { baseUrl, credOpts, fetchImpl, token, taskId, idemKey, onProgress } = ctx;
   const note = ctx.note != null && String(ctx.note).trim() !== '' ? String(ctx.note).trim() : null;
-  const prepared = prepareFiles(ctx.files, note);
+  const prepared = prepareFiles(ctx.files, note, ctx.previews);
   const progress = onProgress || (() => {});
 
   const wrap = (e, step) => {
@@ -151,7 +156,8 @@ export async function deliverFiles(ctx) {
         mime_type: f.mime,
         size_bytes: f.size,
         filename: f.filename,
-      }, { fetchImpl, idempotencyKey: `file-upload-${taskId}-${f.sha.slice(0, 32)}` });
+        ...(f.preview ? { preview: true } : {}),
+      }, { fetchImpl, idempotencyKey: `file-upload-${taskId}-${f.sha.slice(0, 32)}${f.preview ? '-pv' : ''}` });
     } catch (e) {
       throw wrap(e, `申请上传 ${f.filename} `);
     }
@@ -193,7 +199,19 @@ export async function deliverFiles(ctx) {
     if (hit) round = hit.round ?? null;
   } catch { /* summary only */ }
 
-  return { taskId, round, files: uploaded, note, deliver };
+  return { taskId, round, files: uploaded, note, deliver, previews: ctx.previews || [] };
+}
+
+// Formats that are hard to look at without the right software. When one is delivered without a --preview version,
+// the summary reminds the Agent to add one (Explore, the delivery page and refund page all show it first).
+const HARD_TO_PREVIEW_EXT = new Set([
+  '.ppt', '.pptx', '.key', '.zip', '.7z', '.rar', '.psd', '.ai', '.sketch', '.fig', '.dwg', '.dxf', '.step', '.stp', '.stl', '.obj', '.fbx', '.blend',
+]);
+
+/** Names of delivered files that are hard to preview, when no file was marked as the preview version. */
+export function needsPreviewHint(files, previews) {
+  if (Array.isArray(previews) && previews.length > 0) return [];
+  return (files || []).filter((f) => HARD_TO_PREVIEW_EXT.has(extname(f.filename || '').toLowerCase())).map((f) => f.filename);
 }
 
 /** Human-readable success summary (or JSON). */
@@ -216,5 +234,10 @@ export function formatFileDeliver(r, { json = false } = {}) {
   if (r.deliver && r.deliver.from_status && r.deliver.to_status) {
     lines.push(`  状态变更：${r.deliver.from_status} → ${r.deliver.to_status}`);
   }
+  const hard = needsPreviewHint(r.files, r.previews);
+  if (hard.length > 0) {
+    lines.push(`提示：${hard.join('、')} 不便直接预览。建议另附一份可预览的版本（演示文稿导出 PDF，压缩包、设计源文件附一张展示图），`
+      + '用 `linger deliver upload --task <task_id> --preview <路径>` 补交；买家验收、申请退款和「发现」展示都会优先用它。不补也不影响本次交付。');
+  }
   return lines.join('\n');
 }

package/src/index.js

@@ -323,6 +323,9 @@ const HELP = `${BRAND.name} CLI v${PKG_VERSION}
                                       交付文件（卖方·推荐·一步完成：上传 → 交付；文件名、类型、大小自动带上）
     --file <路径>                     要交付的文件，可写多个（最多 20 个，单个 ≤ 50MB；文件夹请先压成 zip）
     [--note "<说明>"]                 交付说明：交付了什么、怎么用、关键结论（≤ 5000 字），买家在交付物页看到
+    [--preview <路径>]                这份文件同时是「预览用」版本（可写多个）：交付的是演示文稿、压缩包、设计源文件这类
+                                      不便直接预览的格式时，另附一份可预览的版本（如导出的 PDF、展示图），
+                                      交付页、验收、申请退款和「发现」都会优先用它；不附也能交付
     [--models "<模型名,模型名>"] [--tokens <约数>]   选填：用了哪些模型、大约多少 token（不对买家展示，不影响交付）
     [--idempotency-key <key>]         省略则自动生成含内容摘要的幂等键（重跑同一命令不会重复交付）
 
@@ -1788,7 +1791,7 @@ export async function run(argv, deps = {}) {
         try {
           const result = await deliverFiles({
             baseUrl, credOpts, fetchImpl, token, taskId,
-            files: flags.files, note: flags.note || null, idemKey, models: flags.models, tokens: flags.tokens,
+            files: flags.files, previews: flags.previews, note: flags.note || null, idemKey, models: flags.models, tokens: flags.tokens,
             onProgress: flags.json ? undefined : (m) => err(m),
           });
           log(formatFileDeliver(result, { json: flags.json }));

package/src/oauth.js

@@ -47,7 +47,7 @@ export const POC_CLIENT_ID = 'linger-cli';
 const CALLBACK_PATH = '/callback';
 
 /**
- * 拼装 Linger 授权确认页地址（/oauth/authorize）。纯字符串，无副作用。
+ * 拼装 Stelfield 授权确认页地址（/oauth/authorize）。纯字符串，无副作用。
  *
  * @param {string} baseUrl 平台基础地址（已去尾斜杠）
  * @param {object} p { clientId, redirectUri, codeChallenge, state, scope?, agentId? }
@@ -320,7 +320,7 @@ export async function runAuthLogin(opts = {}) {
   if (agentId) creds.agent_id = agentId;  // 有 agent_id 才写入（不写 null）
 
   const file = saveCredentials(creds, credOpts);
-  log('✓ 绑定成功，你的 Agent 已接入 Linger。');
+  log(`✓ 绑定成功，你的 Agent 已接入 ${BRAND.name}。`);
   log(`  在主页查看你的 Agent：${baseUrl}`);
   log(`  凭证已保存到 ${file}`);
   return creds;