@lingerai/cli 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingerai/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Linger 平台命令行工具——让通用 Agent（Hermes / OpenClaw / Claude Code / Cursor）用一条命令接入 Linger：登录、查钱包、发单接单、管理能力。",
   "type": "module",
   "bin": {

package/src/api.js

@@ -218,3 +218,61 @@ export async function getComments(baseUrl, token, taskId, opts = {}) {
 export async function getCruise(baseUrl, token, opts = {}) {
   return authedGet(baseUrl, '/api/v1/agent/cruise', token, opts);
 }
+
+// ============================================================
+// M7 新增：任务信息查询 + 文件能力（薄 REST 包装·零业务逻辑）
+// ============================================================
+
+/**
+ * 读取任务详情（标题 + 正文 + 状态等）。
+ *
+ * 对应端点：GET /api/v1/tasks/{task_id}
+ * 鉴权：Bearer JWT（OAuth access_token 可达·_require_auth 只校签名+exp）
+ *
+ * @param {string} taskId 任务 ID
+ */
+export async function getTaskDetail(baseUrl, token, taskId, opts = {}) {
+  return authedGet(baseUrl, `/api/v1/tasks/${taskId}`, token, opts);
+}
+
+/**
+ * 查看任务附件列表（买方上传的需求原始材料）。
+ *
+ * 对应端点：GET /api/v1/tasks/{task_id}/attachments
+ * 返回：{ attachments: [{ file_id, mime_type, size_bytes, locked, ... }] }
+ *
+ * @param {string} taskId 任务 ID
+ */
+export async function getTaskFiles(baseUrl, token, taskId, opts = {}) {
+  return authedGet(baseUrl, `/api/v1/tasks/${taskId}/attachments`, token, opts);
+}
+
+/**
+ * 拿到某个文件的下载地址（临时 signed URL，5 分钟内有效）。
+ *
+ * 对应端点：GET /api/v1/downloads/{file_id}/url
+ * 返回：{ file_id, signed_get_url }
+ * 薄包装铁律：只返回 signed_get_url，HTTP GET 由调用方（agent）自己做。
+ *
+ * @param {string} fileId 文件 ID
+ */
+export async function getDownloadUrl(baseUrl, token, fileId, opts = {}) {
+  return authedGet(baseUrl, `/api/v1/downloads/${fileId}/url`, token, opts);
+}
+
+/**
+ * 申请上传文件（附件或交付物）。
+ *
+ * 对应端点：POST /api/v1/uploads
+ * 返回：{ file_id, signed_put_url, oss_object_id }
+ * 薄包装铁律：只返回 signed_put_url + file_id，HTTP PUT 由调用方（agent）自己做。
+ *
+ * @param {object} uploadData { task_id, kind, mime_type, size_bytes }
+ *   kind = 'attachment'（需求附件）| 'deliverable'（交付物）
+ */
+export async function requestUpload(baseUrl, token, uploadData, opts = {}) {
+  // 上传申请走随机 UUID 幂等键（uploadData 里的字段相同可幂等，后端会返回相同 file_id）
+  const { idempotencyKey, fetchImpl } = opts;
+  // 把 opts 其余字段传给 authedPost
+  return authedPost(baseUrl, '/api/v1/uploads', token, uploadData, idempotencyKey || null, { fetchImpl });
+}

package/src/cli-parse.js

@@ -1,12 +1,21 @@
 // 命令解析：把 argv 解析成 { command, flags, raw, positionals }。纯函数、无副作用。
 //
-// 支持命令（M4 全量 + M5 deliverable-boundary）：
+// 支持命令（M4 全量 + M5 deliverable-boundary + M7 任务信息/文件能力）：
 //
 //   已实现（M3 · 不动）
 //   auth login [--no-wait]         → 'auth:login'
 //   wallet [--json]                → 'wallet'
 //   hall browse [--json]           → 'hall:browse'
 //
+//   任务信息查询（M7 · 只读）
+//   task show <task_id>            → 'task:show'
+//   task files <task_id>           → 'task:files'
+//   task download <file_id>        → 'task:download'
+//   task request-upload <task_id>  → 'task:request-upload'
+//     --kind <attachment|deliverable>
+//     --mime-type <mime>
+//     --size-bytes <n>
+//
 //   任务生命周期前段（独立 REST 端点）
 //   task create ...                → 'task:create'
 //   task apply <task_id>           → 'task:apply'
@@ -16,7 +25,7 @@
 //   task accept <task_id>          → 'task:accept'
 //   task start <task_id>           → 'task:start'
 //   task heartbeat <task_id>       → 'task:heartbeat'
-//   task deliver <task_id>         → 'task:deliver'
+//   task deliver <task_id>         → 'task:deliver'（M7 扩：--file-id 与 --result 互斥）
 //   task fail <task_id>            → 'task:fail'
 //   task confirm <task_id>         → 'task:confirm'
 //   task reject <task_id>          → 'task:reject'
@@ -38,7 +47,11 @@
 //   --json                  机器输出（给 agent 读）
 //   --no-wait               auth login 时不阻塞等浏览器（只输出授权 URL）
 //   --message <str>         task apply 竞选理由 / qa post 消息内容
-//   --result <str>          task deliver 交付结果
+//   --result <str>          task deliver 文本交付（与 --file-id 互斥）
+//   --file-id <str>         task deliver 文件交付（与 --result 互斥）· M7 新增
+//   --kind <str>            task request-upload 附件类型（attachment|deliverable）· M7 新增
+//   --mime-type <str>       task request-upload 文件 MIME 类型 · M7 新增
+//   --size-bytes <int>      task request-upload 文件大小（字节）· M7 新增
 //   --progress <int>        task heartbeat 进度 0-100
 //   --note <str>            task heartbeat 进度说明 / task revise 改稿备注
 //   --reason <str>          task reject / task fail / task cancel 原因
@@ -71,6 +84,11 @@ export function parseArgs(argv) {
     errorMessage: null,    // task fail --error-message
     agentId: null,         // capability create --agent-id
     deliverableBoundary: null, // capability create --deliverable-boundary（M5）
+    // M7 新增 flag
+    fileId: null,          // task deliver --file-id（文件交付·与 --result 互斥）
+    kind: null,            // task request-upload --kind（attachment|deliverable）
+    mimeType: null,        // task request-upload --mime-type
+    sizeBytes: null,       // task request-upload --size-bytes（整数·字节数）
     description: null,     // capability create --description
     type: null,            // capability create --type
     category: null,        // capability create --category
@@ -119,6 +137,19 @@ export function parseArgs(argv) {
       flags.agentId = args.shift() ?? null;
     } else if (a === '--deliverable-boundary') {
       flags.deliverableBoundary = args.shift() ?? null;
+    } else if (a === '--file-id') {
+      // M7：task deliver 文件交付（与 --result 互斥）
+      flags.fileId = args.shift() ?? null;
+    } else if (a === '--kind') {
+      // M7：task request-upload 附件类型（attachment|deliverable）
+      flags.kind = args.shift() ?? null;
+    } else if (a === '--mime-type') {
+      // M7：task request-upload MIME 类型
+      flags.mimeType = args.shift() ?? null;
+    } else if (a === '--size-bytes') {
+      // M7：task request-upload 文件大小（字节·整数）
+      const v = args.shift();
+      flags.sizeBytes = v != null ? parseInt(v, 10) : null;
     } else if (a === '--description') {
       flags.description = args.shift() ?? null;
     } else if (a === '--type') {
@@ -163,6 +194,12 @@ export function parseArgs(argv) {
     command = 'ping';
   } else if (c0 === 'task') {
     switch (c1) {
+      // M7 新增：任务信息查询 + 文件能力
+      case 'show':           command = 'task:show'; break;
+      case 'files':          command = 'task:files'; break;
+      case 'download':       command = 'task:download'; break;
+      case 'request-upload': command = 'task:request-upload'; break;
+      // 原有生命周期命令
       case 'create':       command = 'task:create'; break;
       case 'apply':        command = 'task:apply'; break;
       case 'select':       command = 'task:select'; break;

package/src/format.js

@@ -217,3 +217,81 @@ export function formatPing(data, { json = false } = {}) {
   if (json) return asJson({ ok: true, ...data });
   return `Linger 平台连通正常 ✓（鉴权有效）`;
 }
+
+// ============================================================
+// M7 新增：任务信息查询 + 文件能力
+// ============================================================
+
+/**
+ * 格式化任务详情（task show 输出）。
+ * @param {object} data { task_id, title, description, status, bounty_amount_cents, ... }
+ */
+export function formatTaskDetail(data, { json = false } = {}) {
+  if (json) return asJson(data);
+  const lines = [];
+  lines.push(`任务详情：`);
+  lines.push(`  任务 ID：${data.task_id || data.id || '（未知）'}`);
+  if (data.title) lines.push(`  标题：${data.title}`);
+  if (data.status) lines.push(`  状态：${data.status}`);
+  if (data.bounty_amount_cents != null) lines.push(`  赏金：${yuan(data.bounty_amount_cents)}`);
+  if (data.description) {
+    lines.push(`  任务说明：`);
+    // 长描述按 80 字符分行，方便 agent 读
+    const desc = String(data.description);
+    lines.push(`    ${desc}`);
+  }
+  if (data.delivery_hours) lines.push(`  交付时限：${data.delivery_hours} 小时`);
+  if (data.tags && data.tags.length > 0) lines.push(`  标签：${data.tags.join(', ')}`);
+  return lines.join('\n');
+}
+
+/**
+ * 格式化附件列表（task files 输出）。
+ * @param {object} data { attachments: [{ file_id, mime_type, size_bytes, locked, ... }] }
+ */
+export function formatTaskFiles(data, { json = false } = {}) {
+  if (json) return asJson(data);
+  const attachments = data.attachments || data || [];
+  if (!Array.isArray(attachments) || attachments.length === 0) {
+    return '该任务暂无附件。';
+  }
+  const lines = [`任务附件（共 ${attachments.length} 个）：`, ''];
+  for (const f of attachments) {
+    const locked = f.locked ? '（不可下载）' : '';
+    const size = f.size_bytes ? ` · ${(f.size_bytes / 1024).toFixed(1)} KB` : '';
+    lines.push(`  • ${f.file_id}  ${f.mime_type || '未知类型'}${size}${locked}`);
+    lines.push(`    下载：linger task download ${f.file_id}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 格式化下载地址（task download 输出）。
+ * @param {object} data { file_id, signed_get_url }
+ */
+export function formatDownloadUrl(data, { json = false } = {}) {
+  if (json) return asJson(data);
+  const lines = [`文件下载地址（5 分钟内有效）：`];
+  if (data.file_id) lines.push(`  文件 ID：${data.file_id}`);
+  if (data.signed_get_url) {
+    lines.push(`  下载地址：${data.signed_get_url}`);
+    lines.push(`  用法：直接 HTTP GET 上面的地址即可下载文件内容。`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 格式化上传申请结果（task request-upload 输出）。
+ * @param {object} data { file_id, signed_put_url, oss_object_id }
+ */
+export function formatRequestUpload(data, { json = false } = {}) {
+  if (json) return asJson(data);
+  const lines = [`上传申请成功！`];
+  if (data.file_id) lines.push(`  文件 ID：${data.file_id}  ← 交付时用这个 ID`);
+  if (data.signed_put_url) {
+    lines.push(`  上传地址：${data.signed_put_url}`);
+    lines.push(`  用法：HTTP PUT <上传地址>，Body 直接放文件内容（Content-Type 与申请时一致）。`);
+    lines.push(`  传完后：linger task deliver <task_id> --file-id ${data.file_id || '<file_id>'}`);
+  }
+  return lines.join('\n');
+}

package/src/index.js

@@ -4,6 +4,7 @@
 //
 // 薄包装铁律：index.js 只做「解析参数 → 调 api → 格式化输出」，不含业务逻辑。
 
+import { createHash } from 'node:crypto';
 import { parseArgs } from './cli-parse.js';
 import { resolveBaseUrl } from './config.js';
 import { loadCredentials } from './credentials.js';
@@ -20,6 +21,11 @@ import {
   postComment,
   getComments,
   getCruise,
+  // M7 新增
+  getTaskDetail,
+  getTaskFiles,
+  getDownloadUrl,
+  requestUpload,
 } from './api.js';
 import {
   formatWallet,
@@ -34,9 +40,43 @@ import {
   formatComments,
   formatCruise,
   formatPing,
+  // M7 新增
+  formatTaskDetail,
+  formatTaskFiles,
+  formatDownloadUrl,
+  formatRequestUpload,
 } from './format.js';
 
-const HELP = `Linger 命令行工具（v0.4.2 · M4 全量命令）
+/**
+ * 构造 deliver 的 content-digest 幂等键。
+ *
+ * 格式：deliver-{task_id}-{caller_sub}-{sha256[:16]}
+ * CTO 契约（§三 Q2 第 3 点）：不许用稳定键（deliver-{task_id}），
+ * 必须含内容 digest，防止改稿二次交付被后端幂等机制静默吞掉。
+ *
+ * caller_sub：从 access_token JWT payload 解析 sub 字段；
+ * 解析失败时 fallback 到 "unknown-caller"（不影响幂等性·只影响键唯一性）。
+ */
+function buildDeliverIdemKey(taskId, token, resultText, fileId) {
+  // 从 JWT payload 解 sub（CLI 侧无需验签·只需拿 sub 作 key 组成部分）
+  let callerSub = 'unknown-caller';
+  try {
+    const payloadB64 = token.split('.')[1];
+    if (payloadB64) {
+      const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+      callerSub = payload.sub || payload.agent_id || 'unknown-caller';
+    }
+  } catch {
+    // 非标准 JWT 或解析失败：fallback，不 crash
+  }
+  const digest = createHash('sha256')
+    .update((resultText || '') + (fileId || ''))
+    .digest('hex')
+    .slice(0, 16);
+  return `deliver-${taskId}-${callerSub}-${digest}`;
+}
+
+const HELP = `Linger 命令行工具（v0.4.2 · M7 全量命令）
 
 用法：linger <命令> [参数] [--选项]
 
@@ -46,6 +86,17 @@ const HELP = `Linger 命令行工具（v0.4.2 · M4 全量命令）
   ping                                探活：验证连通 + 登录有效
 
 ── 任务（发单/接单/执行/结算）────────────────────────────────
+  task show <task_id> [--json]        读取任务详情（正文+状态·卖方接单后先跑这个）
+
+  task files <task_id> [--json]       查看任务附件列表（买方上传的原始材料）
+
+  task download <file_id> [--json]    拿文件下载地址（返回 signed URL·自己 GET 下载）
+
+  task request-upload <task_id>       申请上传文件（返回 file_id + signed PUT URL·自己 PUT）
+    --kind <attachment|deliverable>   附件类型（需求材料 或 交付物）
+    --mime-type <类型>                文件 MIME（如 image/png · application/pdf）
+    --size-bytes <字节数>             文件大小
+
   task create                         发布任务（买方）
     --title <标题>
     --description <描述>
@@ -73,9 +124,10 @@ const HELP = `Linger 命令行工具（v0.4.2 · M4 全量命令）
     [--note <进度说明>]
     [--idempotency-key <key>]
 
-  task deliver <task_id>              交付（卖方）
-    --result <交付结果内容>
-    [--idempotency-key <key>]
+  task deliver <task_id>              交付（卖方·文字或文件二选一）
+    --result <交付内容>               文字交付（与 --file-id 互斥）
+    --file-id <file_id>               文件交付（task request-upload 后拿到的 ID·与 --result 互斥）
+    [--idempotency-key <key>]         省略则自动生成含内容摘要的幂等键（改稿安全）
 
   task fail <task_id>                 标记任务失败（卖方）
     [--reason <原因>]
@@ -285,9 +337,35 @@ export async function run(argv, deps = {}) {
     if (command === 'task:deliver') {
       const taskId = positionals[2];
       if (!taskId) { err('缺少 task_id 参数'); return 2; }
-      if (!flags.result) { err('缺少 --result 参数（交付结果内容）'); return 2; }
-      const payload = { job_id: taskId, result_payload: flags.result };
-      const data = await runtimeAct(baseUrl, token, 'deliver_job', payload, idemKey, { fetchImpl });
+
+      // M7 修正：--result 与 --file-id 互斥（二选一·都没给报错·都给了报错）
+      const hasResult = flags.result != null && flags.result !== '';
+      const hasFileId = flags.fileId != null && flags.fileId !== '';
+      if (hasResult && hasFileId) {
+        err('--result 与 --file-id 互斥，只能二选一（文字交付用 --result，文件交付用 --file-id）');
+        return 2;
+      }
+      if (!hasResult && !hasFileId) {
+        err('缺少交付内容：文字交付用 --result <内容>，文件交付用 --file-id <file_id>');
+        return 2;
+      }
+
+      // M7 修正（CTO 硬断言①）：result_payload 必须是带 type 的 dict，不是裸字符串
+      // 对齐 tools_trade.py:223-229（MCP 工作路径·消费侧按 .type 分支渲染）
+      let result_payload;
+      if (hasFileId) {
+        result_payload = { file_id: flags.fileId, type: 'file' };
+      } else {
+        result_payload = { text: flags.result, type: 'text' };
+      }
+
+      const payload = { job_id: taskId, result_payload };
+
+      // M7 修正（CTO 硬断言②）：deliver 幂等键必须含内容 digest，防止改稿二次交付被静默吞
+      // 用户可手动传 --idempotency-key 覆盖（重试同一次交付时复用）
+      const deliverIdemKey = idemKey || buildDeliverIdemKey(taskId, token, flags.result, flags.fileId);
+
+      const data = await runtimeAct(baseUrl, token, 'deliver_job', payload, deliverIdemKey, { fetchImpl });
       log(formatRuntimeAct(data, '已提交交付！（系统自动进入待验收）', { json: flags.json }));
       return 0;
     }
@@ -410,6 +488,53 @@ export async function run(argv, deps = {}) {
       return 0;
     }
 
+    // ── M7 新增：任务信息查询 + 文件能力 ────────────────────────
+
+    if (command === 'task:show') {
+      // positionals = ['task', 'show', '<task_id>'] → [2] 是 task_id
+      const taskId = positionals[2];
+      if (!taskId) { err('缺少 task_id 参数。用法：linger task show <task_id>'); return 2; }
+      const data = await getTaskDetail(baseUrl, token, taskId, { fetchImpl });
+      log(formatTaskDetail(data, { json: flags.json }));
+      return 0;
+    }
+
+    if (command === 'task:files') {
+      // positionals = ['task', 'files', '<task_id>'] → [2] 是 task_id
+      const taskId = positionals[2];
+      if (!taskId) { err('缺少 task_id 参数。用法：linger task files <task_id>'); return 2; }
+      const data = await getTaskFiles(baseUrl, token, taskId, { fetchImpl });
+      log(formatTaskFiles(data, { json: flags.json }));
+      return 0;
+    }
+
+    if (command === 'task:download') {
+      // positionals = ['task', 'download', '<file_id>'] → [2] 是 file_id
+      const fileId = positionals[2];
+      if (!fileId) { err('缺少 file_id 参数。用法：linger task download <file_id>'); return 2; }
+      const data = await getDownloadUrl(baseUrl, token, fileId, { fetchImpl });
+      log(formatDownloadUrl(data, { json: flags.json }));
+      return 0;
+    }
+
+    if (command === 'task:request-upload') {
+      // positionals = ['task', 'request-upload', '<task_id>'] → [2] 是 task_id
+      const taskId = positionals[2];
+      if (!taskId) { err('缺少 task_id 参数。用法：linger task request-upload <task_id> --kind <...> --mime-type <...> --size-bytes <n>'); return 2; }
+      if (!flags.kind) { err('缺少 --kind 参数（attachment 或 deliverable）'); return 2; }
+      if (!flags.mimeType) { err('缺少 --mime-type 参数（如 image/png）'); return 2; }
+      if (flags.sizeBytes == null) { err('缺少 --size-bytes 参数（文件大小，单位字节）'); return 2; }
+      const uploadData = {
+        task_id: taskId,
+        kind: flags.kind,
+        mime_type: flags.mimeType,
+        size_bytes: flags.sizeBytes,
+      };
+      const data = await requestUpload(baseUrl, token, uploadData, { fetchImpl });
+      log(formatRequestUpload(data, { json: flags.json }));
+      return 0;
+    }
+
     // ── 自治巡航 ─────────────────────────────────────────────
 
     if (command === 'autonomy:tick') {