@metagptx/deepflow-suite-cli 0.3.0 → 0.3.2

package/runtime/df-workbench/df-workbench.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
-import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { randomUUID, createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 
@@ -39,6 +40,7 @@ export function parseArgs(argv, env = process.env) {
     baseUrl: env.DF_WORKBENCH_BASE_URL || DEFAULT_BASE_URL,
     token: env.DF_WORKBENCH_TOKEN || "",
     workspace: env.DF_WORKBENCH_WORKSPACE_ID || "",
+    expectedActor: undefined,
     json: false,
     idempotencyKey: "",
     message: "",
@@ -46,8 +48,11 @@ export function parseArgs(argv, env = process.env) {
     after: "",
     limit: "",
     scope: "mine",
+    offset: "",
     squadId: undefined,
     file: undefined,
+    attachmentIds: [],
+    participantIds: [],
   };
   const positionals = [];
   for (let index = 0; index < argv.length; index += 1) {
@@ -56,6 +61,7 @@ export function parseArgs(argv, env = process.env) {
       options.json = true;
       continue;
     }
+    if(argument==='--receipt-only'){options.receiptOnly=true;continue;}
     if (argument === "--help" || argument === "-h") {
       options.help = true;
       continue;
@@ -67,29 +73,71 @@ export function parseArgs(argv, env = process.env) {
       [
         "--base-url",
         "--workspace",
+        "--expected-actor",
         "--idempotency-key",
         "--message",
         "--title",
         "--after",
         "--limit",
         "--scope",
+        "--offset",
         "--squad-id",
         "--file",
+        "--attachment-id",
+        "--member-id",
+        "--assignee-id",
+        "--expected-assignee",
+        "--participant-id",
+        "--creation-mode",
+        "--request-seq",
+        "--followup-context",
       ].includes(name)
     ) {
       const parsed =
         inline === undefined ? valueAfter(argv, index, name) : inline;
       if (inline === undefined) index += 1;
       if (name === "--base-url") options.baseUrl = parsed;
+      if (name === "--creation-mode") {
+        if(!['atomic','staged'].includes(parsed))throw new UsageError('--creation-mode 需为 atomic 或 staged。');
+        options.creationMode=parsed;
+      }
       if (name === "--workspace") options.workspace = parsed;
+      if (name === "--expected-actor") {
+        if (!parsed.trim() || parsed.length > 160 || /[\r\n]/.test(parsed))
+          throw new UsageError("--expected-actor 需要有效的用户 ID。");
+        options.expectedActor = parsed;
+      }
       if (name === "--idempotency-key") options.idempotencyKey = parsed;
       if (name === "--message") options.message = parsed;
       if (name === "--title") options.title = parsed;
       if (name === "--after") options.after = parsed;
       if (name === "--limit") options.limit = parsed;
       if (name === "--scope") options.scope = parsed;
+      if (name === "--offset") options.offset = parsed;
       if (name === "--squad-id") options.squadId = parsed;
       if (name === "--file") options.file = parsed;
+      if (name === "--attachment-id") options.attachmentIds.push(parsed);
+      if (name === "--member-id") options.memberId = parsed;
+      if (name === "--request-seq") options.requestSeq=parsed;
+      if (name === "--followup-context") {
+        let value;try{value=JSON.parse(parsed);}catch{throw new UsageError('--followup-context 需要原提醒关联 JSON。');}
+        if(!value||Array.isArray(value)||Object.keys(value).length!==4||Object.keys(value).some(k=>!['task_instance_id','recipient_id','request_seq','version'].includes(k))||
+          typeof value.task_instance_id!=='string'||!value.task_instance_id||value.task_instance_id.length>2048||/[\u0000-\u001f\u007f]/.test(value.task_instance_id)||
+          typeof value.recipient_id!=='string'||!/^[\w-]{1,160}$/.test(value.recipient_id)||!Number.isSafeInteger(value.request_seq)||value.request_seq<1||typeof value.version!=='string'||!/^[a-f0-9]{64}$/.test(value.version))throw new UsageError('--followup-context 原提醒关联无效。');
+        options.followupContext=value;
+      }
+      if (name === "--assignee-id") options.assigneeId = parsed;
+      if (name === "--expected-assignee") {
+        let baseline;
+        try { baseline=JSON.parse(parsed); } catch { throw new UsageError('--expected-assignee 需要 JSON 原值基线。'); }
+        const v=baseline?.value;
+        if(!baseline || Array.isArray(baseline) || typeof baseline.present!=='boolean' ||
+          Object.keys(baseline).some(k=>!['present','value'].includes(k)) ||
+          (baseline.present ? !Object.hasOwn(baseline,'value') || v!==null && (!v || !['human','agent'].includes(v.kind) || !/^[\w-]{1,100}$/.test(v.id||'') || Object.keys(v).some(k=>!['kind','id'].includes(k))) : Object.hasOwn(baseline,'value')))
+          throw new UsageError('--expected-assignee 原值基线无效。');
+        options.expectedAssignee=baseline;
+      }
+      if (name === "--participant-id") options.participantIds.push(parsed);
       continue;
     }
     if (argument.startsWith("--"))
@@ -180,6 +228,7 @@ async function request(options, path, requestOptions = {}, context = {}) {
   const baseUrl = normalizeBaseUrl(options.baseUrl);
   const url = new URL(path, `${baseUrl}/`);
   const headers = requestHeaders(options, context, requestOptions.key);
+  if(requestOptions.receiptOnly)headers['X-Deepflow-Message-Receipt']='lookup';
   if (requestOptions.body !== undefined)
     headers["Content-Type"] = "application/json";
   let response;
@@ -221,7 +270,7 @@ async function request(options, path, requestOptions = {}, context = {}) {
   return data;
 }
 
-async function currentContext(options) {
+async function currentContext(options,requireWorkspace=true) {
   const me = await request(
     options,
     "/api/v1/me",
@@ -229,12 +278,12 @@ async function currentContext(options) {
     options.workspace ? { workspace: options.workspace } : {},
   );
   const workspace = options.workspace || me.workspaceId;
-  if (!workspace)
+  if (!workspace&&requireWorkspace)
     throw new RequestError("Workbench 没有返回当前工作区。", {
       code: "workspace_missing",
     });
   if (
-    Array.isArray(me.workspaces) &&
+    workspace && Array.isArray(me.workspaces) &&
     !me.workspaces.some((item) => item.id === workspace)
   )
     throw new RequestError(`当前用户无权访问工作区：${workspace}`, {
@@ -245,11 +294,20 @@ async function currentContext(options) {
     throw new RequestError("Workbench 没有返回当前用户。", {
       code: "identity_missing",
     });
+  if (
+    options.expectedActor !== undefined &&
+    options.expectedActor !== me.user.id
+  )
+    throw new RequestError("Workbench 操作身份已变化；未提交业务请求。", {
+      code: "identity_changed",
+    });
   return { me, workspace, actorId: me.user.id };
 }
 
 async function loadConfig(options) {
   const context = await currentContext(options);
+  if(context.me.user.principalKind==='bot')return {baseUrl:normalizeBaseUrl(options.baseUrl),identity:context.me.user,workspaces:context.me.workspaces,
+    workspace:context.me.workspaces.find(w=>w.id===context.workspace),authentication:context.me.authentication,capabilities:context.me.capabilities};
   const [platform, auth, readiness, capabilities] = await Promise.all([
     request(options, "/api/v1/platform-state"),
     request(options, "/api/v1/auth/config"),
@@ -423,18 +481,31 @@ function help() {
   df-workbench squad get <squad-id> [--json]
   df-workbench squad create --file <配置.json> [--idempotency-key <key>] [--json]
   df-workbench squad update <squad-id> --file <配置.json> [--idempotency-key <key>] [--json]
-  df-workbench task create --message <消息> [--title <标题>] [--squad-id <squad-id>] [--idempotency-key <key>]
+  df-workbench workspace members [--json]
+  df-workbench task create --message <消息> [--title <标题>] [--squad-id <squad-id>] [--assignee-id <user-id>] [--creation-mode <atomic|staged>] [--participant-id <user-id>] [--idempotency-key <key>]
+  df-workbench task assign <task-id> --member-id <user-id> [--expected-assignee <JSON基线>] [--idempotency-key <key>]
+  df-workbench task member-options <task-id>
+  df-workbench task invite <task-id> --member-id <user-id> [--idempotency-key <key>]
   df-workbench task send <task-id> --message <消息> [--idempotency-key <key>]
+  df-workbench task followup-context <task-id> --member-id <user-id> [--request-seq <seq>]
+  df-workbench task delivery-context <task-id> --member-id <user-id>
+  df-workbench task lookup <DF-number> [--json]
   df-workbench task get <task-id> [--json]
   df-workbench task facts <task-id> [--after <seq>] [--limit <n>] [--json]
-  df-workbench task list [--scope <mine|workspace>] [--limit <n>] [--json]
+  df-workbench task list [--scope <mine|workspace>] [--limit <n>] [--offset <n>] [--json]
+  df-workbench attachment upload --file <文件> [--idempotency-key <key>] [--json]
+
+task create/send 可重复传入 --attachment-id <id>，每次最多 10 个。
+task send 可携带 --followup-context <原提醒JSON>；--receipt-only 仅核对原幂等键的消息回执，不创建新消息。
 
 全局配置：
   DF_WORKBENCH_BASE_URL       Workbench 根地址，默认 http://127.0.0.1:8793
   DF_WORKBENCH_TOKEN          OIDC 环境使用的 personal token
   DF_WORKBENCH_WORKSPACE_ID   当前工作区覆盖值
+  Token 获取：公司账号登录 → 个人设置 → 个人 Token
   --base-url <url>             覆盖 Workbench 根地址
   --workspace <id>             覆盖当前工作区
+  --expected-actor <user-id>    固定操作身份；身份变化时停止请求
   --json                      输出机器可读 JSON`;
 }
 
@@ -444,6 +515,13 @@ async function run(options) {
     process.stdout.write(`${help()}\n`);
     return;
   }
+  if ((options.assigneeId !== undefined || options.participantIds.length) && !(command === "task" && subject === "create")) throw new UsageError("--assignee-id 和 --participant-id 仅用于 task create。");
+  if (options.assigneeId !== undefined && !/^[\w-]{1,100}$/.test(options.assigneeId)) throw new UsageError("初始负责人 ID 无效。");
+  if (options.memberId !== undefined && !(command === "task" && ["invite","assign","followup-context","delivery-context"].includes(subject))) throw new UsageError("--member-id 仅用于邀请、指定负责人或核对提醒对象。");
+  if(options.followupContext && !(command==='task'&&subject==='send'))throw new UsageError('--followup-context 仅用于向原任务回复。');
+  if(options.receiptOnly && !(command==='task'&&subject==='send'))throw new UsageError('--receipt-only 仅用于核对原消息回执。');
+  if(options.requestSeq!==undefined && !(command==='task'&&subject==='followup-context'))throw new UsageError('--request-seq 仅用于核对原提醒。');
+
   if (
     options.squadId !== undefined &&
     !(command === "task" && subject === "create")
@@ -453,9 +531,57 @@ async function run(options) {
     );
   if (
     options.file !== undefined &&
-    !(command === "squad" && ["create", "update"].includes(subject))
+    !(command === "squad" && ["create", "update"].includes(subject)) &&
+    !(command === "attachment" && subject === "upload")
   )
-    throw new UsageError("--file 仅用于 squad create/update。");
+    throw new UsageError(
+      "--file 仅用于 squad create/update 或 attachment upload。",
+    );
+  if (
+    options.attachmentIds.length &&
+    !(command === "task" && ["create", "send"].includes(subject))
+  )
+    throw new UsageError("--attachment-id 仅用于 task create/send。");
+  if (
+    options.attachmentIds.length > 10 ||
+    new Set(options.attachmentIds).size !== options.attachmentIds.length ||
+    options.attachmentIds.some((id) => !/^[\w-]{1,100}$/.test(id))
+  )
+    throw new UsageError("附件列表无效，每次最多发送 10 个不同附件。");
+  if (command === "attachment" && subject === "upload") {
+    if (!options.file) throw new UsageError("attachment upload 需要 --file。");
+    const fileInfo = await stat(options.file);
+    if (!fileInfo.isFile() || !fileInfo.size || fileInfo.size > 4 * 1024 * 1024)
+      throw new UsageError("每个附件需为 1 字节至 4 MiB。");
+    const bytes = await readFile(options.file);
+    const filename = basename(options.file);
+    if (!bytes.length || bytes.length > 4 * 1024 * 1024)
+      throw new UsageError("每个附件需为 1 字节至 4 MiB。");
+    if (
+      !filename.trim() ||
+      filename.length > 180 ||
+      /[\x00-\x1f\x7f\\]/.test(filename)
+    )
+      throw new UsageError("附件名称无效。");
+    const context = await currentContext(options);
+    const value = await request(
+      options,
+      "/api/v1/task-attachments",
+      {
+        method: "POST",
+        key: idempotencyKey(options),
+        body: { filename, bytesBase64: bytes.toString("base64") },
+      },
+      context,
+    );
+    writeResult(
+      value,
+      options,
+      (value) =>
+        `已上传附件：${value.attachment?.filename} (${value.attachment?.id})`,
+    );
+    return;
+  }
   if (command === "squad") return squadCommand(options, subject, rest);
   if (command === "health") {
     const value = await request(options, "/healthz");
@@ -463,12 +589,12 @@ async function run(options) {
     return;
   }
   if (command === "me") {
-    const context = await currentContext(options);
+    const context = await currentContext(options,false);
     writeResult(
       context.me,
       options,
       (value) =>
-        `用户: ${value.user.name} (${value.user.id})\n工作区: ${value.workspaceId}`,
+        `身份: ${value.user.principalKind||"human"} · ${value.user.name} (${value.user.id})\n工作区: ${value.workspaceId}`,
     );
     return;
   }
@@ -482,16 +608,84 @@ async function run(options) {
     );
     return;
   }
+  if (command === "workspace" && subject === "members") {
+    const context = await currentContext(options);
+    const value = await request(options,"/api/v1/members",{},context);
+    if (!Array.isArray(value.members)) throw new RequestError("工作区成员目录回执无效。",{code:"invalid_member_directory"});
+    writeResult(value,options,value => value.members.map(member=>`${member.userId} ${member.name || ""}`).join("\n"));return;
+  }
   if (command !== "task") throw new UsageError(`不支持的命令：${command}`);
+  if (subject === 'transfer-owner') throw new UsageError('此任务操作已停用。');
+  if(subject==='capabilities') {
+    const context=await currentContext(options),value=await request(options,'/api/v1/task-ui/capabilities',{},context);
+    writeResult(value,options,value=>JSON.stringify(value));return;
+  }
+  if(['followup-context','delivery-context'].includes(subject)) {
+    const taskId=rest[0];
+    if(!/^[\w-]{1,160}$/.test(taskId||'')||!/^[\w-]{1,160}$/.test(options.memberId||''))throw new UsageError('需要任务 ID 和 --member-id 提醒对象。');
+    const context=await currentContext(options),query=new URLSearchParams({recipient_id:options.memberId});
+    if(options.requestSeq!==undefined)query.set('request_seq',String(integerOption(options.requestSeq,'--request-seq',0,1,Number.MAX_SAFE_INTEGER)));
+    const value=await request(options,`/api/v1/task-ui/tasks/${encodeURIComponent(taskId)}/${subject}?${query}`,{},context);
+    if(value?.taskId!==taskId||value.recipientId!==options.memberId||typeof value.taskInstanceId!=='string'||!value.taskInstanceId||!Number.isSafeInteger(value.requestSeq)||value.requestSeq<1||!/^[a-f0-9]{64}$/.test(value.version||''))throw new RequestError('原提醒关联回执不匹配。',{code:'task_lookup_mismatch'});
+    if(subject==='delivery-context'&&(value.kind!=='delivery'||!Array.isArray(value.artifacts)||!value.artifacts.length||!Number.isSafeInteger(value.startedSeq)||!Number.isSafeInteger(value.endedSeq)))throw new RequestError('交付版本回执不匹配。',{code:'task_lookup_mismatch'});
+    writeResult(value,options,value=>`原请求 #${value.requestSeq}：${value.text}`);return;
+  }
+  if (["member-options", "invite", "assign"].includes(subject)) {
+    const taskId = rest[0];
+    if (!taskId || !/^[\w-]{1,160}$/.test(taskId)) throw new UsageError("需要有效的 Task ID。");
+    const writes = subject !== "member-options";
+    if (writes && !/^[\w-]{1,100}$/.test(options.memberId || "")) throw new UsageError("需要 --member-id 指定有效的 DF 用户 ID。");
+    const context = await currentContext(options);
+    let value;
+    if(subject==='assign') {
+      const current=(await request(options,`/api/v1/tasks/${encodeURIComponent(taskId)}`,{},context)).task;
+      if(current?.id!==taskId||current.metadata?.data?.workspace_id!==context.workspace)throw new RequestError('任务范围未确认。',{code:'task_metadata_mismatch'});
+      const presentation=current.metadata.data.presentation||{},key=idempotencyKey(options);
+      const assignee=Object.hasOwn(presentation,'assignee')?{present:true,value:presentation.assignee}:{present:false};
+      if(options.expectedAssignee) {
+        const expected=options.expectedAssignee;
+        const same=expected.present===assignee.present && (!expected.present || expected.value===null&&assignee.value===null || expected.value?.kind===assignee.value?.kind&&expected.value?.id===assignee.value?.id);
+        const alreadyAssigned=presentation.assignee?.kind==='human' && presentation.assignee.id===options.memberId;
+        if(!same&&!alreadyAssigned)throw new RequestError('负责人已变化，请重新核对分配要求。',{code:'task_assignee_changed',status:409});
+      }
+      // The original baseline is part of the idempotent command, including after
+      // a successful write whose response was lost.
+      const baselineAssignee=options.expectedAssignee || assignee;
+      value=await request(options,`/api/v1/tasks/${encodeURIComponent(taskId)}/presentation`,{method:'POST',key,body:{changes:{assignee:{kind:'human',id:options.memberId}},baseline:{assignee:baselineAssignee}}},context);
+      const saved=value?.task,data=saved?.metadata?.data;
+      if(saved?.id!==taskId||data?.workspace_id!==context.workspace||data.presentation?.assignee?.kind!=='human'||data.presentation.assignee.id!==options.memberId)
+        throw new RequestError('负责人保存回执未确认，请保留原幂等键核对。',{code:'task_metadata_mismatch',outcome:'unknown',taskId,idempotencyKey:key});
+    } else {
+      const path=subject==='member-options'?`/api/v1/task-ui/tasks/${encodeURIComponent(taskId)}/property-options`:`/api/v1/tasks/${encodeURIComponent(taskId)}/member-invitations`;
+      value=await request(options,path,writes?{method:'POST',key:idempotencyKey(options),body:{invitee_ids:[options.memberId]}}:{},context);
+    }
+    writeResult(value, options, value => JSON.stringify(value));
+    return;
+  }
   if (subject === "create") {
     const body = buildCreateBody(
       options.message,
       options.title,
       options.squadId,
     );
+    if (options.assigneeId) {
+      if (![options.assigneeId,...options.participantIds].every(id=>/^[\w-]{1,100}$/.test(id))) throw new UsageError("初始负责人和参与人 ID 无效。");
+      if(options.creationMode==='atomic') {body.initial_presentation={assignee:{kind:'human',id:options.assigneeId}};body.first_message=messageValue(options.message);}
+      else {body.initial_assignee_id=options.assigneeId;body.first_message="";}
+      body.invitee_ids=[...new Set(options.participantIds)].sort();
+    } else if(options.participantIds.length) throw new UsageError("--participant-id 需要同时指定 --assignee-id。");
+    if (options.attachmentIds.length && (!options.assigneeId || options.creationMode==='atomic'))
+      body.attachment_ids = options.attachmentIds;
     const context = await currentContext(options);
+    if(context.me.user.principalKind==='bot') {
+      if(options.assigneeId||options.squadId||options.attachmentIds.length)throw new UsageError('Bot 创建任务不支持指定人工负责人、小队或初始附件；附件可在创建后通过 task send 提交。');
+      delete body.conversation;
+      body.title ||= Array.from(body.description.split('\n')[0]).slice(0,80).join('');
+    }
     const key = idempotencyKey(options);
-    const value = await request(
+    let atomicCreation=options.creationMode==='atomic';
+    let value;
+    try {value = await request(
       options,
       "/api/v1/tasks",
       {
@@ -500,7 +694,17 @@ async function run(options) {
         body,
       },
       context,
-    );
+    );} catch(error) {
+      // A checked validation rejection has not applied the staged command. An
+      // idempotency conflict can also be an atomic receipt from before upgrade.
+      // Reuse the original key; never fall back after an unknown write outcome.
+      const rejected=error instanceof RequestError && (error.status===422 && error.code==='invalid_input' || error.status===409 && error.code==='idempotency_conflict');
+      if(!options.assigneeId || atomicCreation || !rejected)throw error;
+      const atomicBody={...body,first_message:messageValue(options.message),initial_presentation:{assignee:{kind:'human',id:options.assigneeId}},...(options.attachmentIds.length?{attachment_ids:options.attachmentIds}:{})};
+      delete atomicBody.initial_assignee_id;
+      value=await request(options,'/api/v1/tasks',{method:'POST',key,body:atomicBody},context);
+      atomicCreation=true;
+    }
     if (
       body.squad_id &&
       value?.task?.metadata?.data?.squad?.squadId !== body.squad_id
@@ -514,6 +718,27 @@ async function run(options) {
           idempotencyKey: key,
         },
       );
+    if (options.assigneeId) {
+      const task=value?.task,data=task?.metadata?.data;
+      if (!task?.id || data?.workspace_id!==context.workspace || (data.presentation?.assignee?.kind!=='human'||data.presentation.assignee.id!==options.assigneeId) || data.created_by!==context.actorId ||
+        ![context.actorId,options.assigneeId,...options.participantIds].every(id=>data.members?.includes(id))) throw new RequestError("已创建的任务初始负责人或成员回执不匹配，请保留原幂等键核对，不要重建。",{code:"task_metadata_mismatch",outcome:"unknown",taskId:task?.id,idempotencyKey:key});
+      // Atomic creation freezes the initial message and squad in the server's
+      // creation receipt; only the staged protocol needs a second message.
+      if(!atomicCreation) {
+      // Current squad edits must never change a retry of the original message.
+      const agentId=data.initial_message_context?.agentId;
+      if (!agentId) throw new RequestError("任务已创建，但创建时的小队快照没有可接收首条消息的伙伴；请保留原任务与幂等键核对。",{code:"initial_agent_unavailable",outcome:"unknown",taskId:task.id,idempotencyKey:key});
+      const firstKey="initial-message:"+createHash("sha256").update(key).digest("hex");
+      let first;
+      try {
+        first=await request(options,`/api/v1/tasks/${encodeURIComponent(task.id)}/messages`,{method:"POST",key:firstKey,body:{text:messageValue(options.message),agentIds:[agentId],...(options.attachmentIds.length?{attachment_ids:options.attachmentIds}:{})}},context);
+      } catch(error) {
+        throw new RequestError(`任务 ${task.id} 已创建，首条消息回执尚待确认；保留幂等键 ${key} 重试，不换键或重建。`,{code:"initial_message_unconfirmed",outcome:"unknown",taskId:task.id,idempotencyKey:key,causeCode:error.code});
+      }
+      if (!Number.isSafeInteger(first?.fact?.seq) || first.fact.task_id!==task.id) throw new RequestError("初始消息回执不匹配；保留原任务与幂等键重试。",{code:"initial_message_unconfirmed",outcome:"unknown",taskId:task.id,idempotencyKey:key});
+      value={...value,first_fact:first.fact,first_fact_seq:first.fact.seq};
+      }
+    }
     writeResult(value, options, taskSummary);
     return;
   }
@@ -525,7 +750,18 @@ async function run(options) {
     const value = await request(
       options,
       `/api/v1/tasks/${encodeURIComponent(taskId)}/messages`,
-      { method: "POST", key, body: { text: messageValue(options.message) } },
+      {
+        method: "POST",
+        key,
+        receiptOnly:options.receiptOnly===true,
+        body: {
+          text: messageValue(options.message),
+          ...(options.followupContext?{followup_context:options.followupContext}:{}),
+          ...(options.attachmentIds.length
+            ? { attachment_ids: options.attachmentIds }
+            : {}),
+        },
+      },
       context,
     );
     writeResult(
@@ -535,6 +771,29 @@ async function run(options) {
     );
     return;
   }
+  if (subject === "lookup") {
+    const number = String(rest[0] || "").toUpperCase();
+    if (!/^DF-\d+$/.test(number)) throw new UsageError("task lookup 需要 DF 编号。");
+    const context = await currentContext(options);
+    for (let page = 0, offset = 0; page < 20; page++) {
+      const result = await request(options, `/api/v1/tasks?${new URLSearchParams({scope:"workspace",limit:"200",offset:String(offset)})}`, {}, context);
+      if (!Array.isArray(result.tasks) || typeof result.hasMore !== "boolean") throw new RequestError("工作区任务分页回执不完整，尚不能判断该编号是否存在。",{code:"task_lookup_incomplete"});
+      const matches = result.tasks.filter(task => task.number === number);
+      if (matches.length > 1) throw new RequestError("工作区中出现重复任务编号，请核实目标。",{code:"task_lookup_ambiguous"});
+      if (matches.length) {
+        const task = matches[0];
+        if (task.access === "overview") throw new RequestError(`${number} 存在，但当前账号尚未加入任务，请先获得参与权限。`,{code:"task_participation_required",status:403});
+        const value = await request(options, `/api/v1/tasks/${encodeURIComponent(task.id)}`, {}, context);
+        if (value.task?.id !== task.id || value.task?.number !== number || value.task?.metadata?.data?.workspace_id !== context.workspace || value.task?.access === "overview")
+          throw new RequestError("DF 编号、工作区或内容权限读回不一致，暂停操作。",{code:"task_lookup_mismatch"});
+        writeResult(value, options, taskSummary);return;
+      }
+      if (!result.hasMore) throw new RequestError(`当前工作区未找到 ${number}，请确认编号。`,{code:"task_not_found",status:404});
+      if (!result.tasks.length) break;
+      offset += result.tasks.length;
+    }
+    throw new RequestError("工作区任务查询尚未完成，请稍后再试；不会新建任务。",{code:"task_lookup_incomplete"});
+  }
   if (subject === "get") {
     const taskId = rest[0];
     if (!taskId) throw new UsageError("task get 需要 Task ID。");
@@ -583,6 +842,7 @@ async function run(options) {
       `/api/v1/tasks?${new URLSearchParams({
         scope: options.scope,
         limit: String(limit),
+        offset: String(integerOption(options.offset, "--offset", 0, 0, 1048576)),
         include_state: "1",
       })}`,
       {},

package/runtime/df-workbench/release.json

@@ -1 +1 @@
-{"version":"0.3.0","project":"deepflow-workbench","sourceCommit":"6afd4dec2000e93a971c94d4f18126c10f74a300","sourceDirty":false}
+{"version":"0.3.2","project":"deepflow-workbench","sourceCommit":"adfb558b1c3532b338b5a8b0d5c11a43739e4ca6","sourceDirty":false}