@keyou007/agent-bot 0.1.14-alpha.0 → 0.1.14-alpha.2

package/src/cli.ts

@@ -8,8 +8,16 @@ import { sendControlRequest, isServerReachable } from "./cli/LocalControlClient.
 import {
   controlEndpoint,
   type ControlResponse,
+  type TaskAgentControlData,
+  type TaskDirectoryControlData,
+  type TaskForkControlData,
+  type TaskGoalControlData,
   type TaskGroupControlData,
+  type TaskMuteControlData,
+  type TaskSettingsControlData,
+  type TaskShellControlData,
   type TaskStatusControlData,
+  type TaskTurnsControlData,
 } from "./cli/controlProtocol.js";
 import {
   acquireInitializationLock,
@@ -17,10 +25,14 @@ import {
   initializeAgentBot,
   readConfiguredAgentSelection,
   readFeishuCredentials,
+  readGroupMessageResponseMode,
   shouldCreateFeishuApp,
   shouldConfigureAgentsDuringInitialization,
+  shouldConfigureGroupMessagesDuringInitialization,
   writeConfiguredAgentSelection,
   writeFeishuCredentials,
+  writeGroupMessageResponseMode,
+  type GroupMessageResponseMode,
   type InitializationResult,
   type InitializationStatus,
 } from "./cli/Initializer.js";
@@ -77,13 +89,18 @@ import { taskChatRoute } from "./cli/taskChatRoute.js";
 import {
   currentAppServerThreadIds,
   formatTaskList,
-  resolveCurrentTask,
   taskStateLabel,
 } from "./cli/taskListOutput.js";
+import {
+  resolveCurrentTaskFromEnvironment,
+  resolveTask,
+  resolveTaskCommandTarget,
+} from "./cli/taskTarget.js";
 import { isThreadContextKey } from "./feishu/contextKey.js";
 import { refreshedSystemEnvironment } from "./supervision/systemEnvironment.js";
 import {
   parseTaskForkGroupOptions,
+  parseTaskNewOptions,
   parseTaskNewGroupOptions,
 } from "./cli/taskGroupOptions.js";
 import { StateStore, type SessionRecord } from "./state/StateStore.js";
@@ -93,6 +110,20 @@ import {
   resolveSupervisorDiagnosticsPaths,
 } from "./supervision/SupervisorDiagnostics.js";
 import { agentBotHome, defaultSqlitePath } from "./config/paths.js";
+import {
+  finalizeSelfUpdatePlan,
+  launchSelfUpdateRunner,
+  parseSelfUpdateOptions,
+  prepareSelfUpdate,
+  releaseSelfUpdatePlan,
+  requireNpmSelfUpdateInstallation,
+} from "./cli/SelfUpdater.js";
+import { createCurrentAutostartManager } from "./cli/AutostartManager.js";
+import {
+  formatAutostartStatus,
+  type AutostartServerStatus,
+  type CombinedAutostartStatus,
+} from "./cli/autostartOutput.js";
 
 const args = process.argv.slice(2);
 
@@ -119,6 +150,10 @@ async function main(input: string[]): Promise<void> {
     await initCommand(rest, parsed.configPath, Boolean(parsed.profilePath));
     return;
   }
+  if (command === "update") {
+    await updateCommand(rest);
+    return;
+  }
   if (command === "console") {
     await consoleCommand(rest);
     return;
@@ -141,6 +176,88 @@ async function main(input: string[]): Promise<void> {
   ));
 }
 
+async function updateCommand(input: string[]): Promise<void> {
+  const options = parseSelfUpdateOptions(input);
+  requireNpmSelfUpdateInstallation();
+  const config = loadConfig();
+  const endpoint = controlEndpoint(config.storage.sqlitePath);
+  const serverRunning = await isServerReachable(endpoint);
+  if (!options.json) process.stdout.write(cliText(
+    "Checking the installed Agent Bot package and npm release channel...\n",
+    "正在检查已安装的 Agent Bot 包和 npm 发布通道……\n",
+  ));
+  const prepared = await prepareSelfUpdate({
+    channel: options.channel,
+    version: options.version,
+    allowDowngrade: options.allowDowngrade,
+  });
+  if (prepared.status === "current") {
+    if (options.json) printJson(prepared);
+    else process.stdout.write(cliText(
+      `Agent Bot ${prepared.currentVersion} is already current on the ${prepared.channel} channel.\n`,
+      `Agent Bot ${prepared.currentVersion} 已是 ${prepared.channel} 通道的当前版本。\n`,
+    ));
+    return;
+  }
+
+  const reason = cliText(
+    `Update Agent Bot from ${prepared.currentVersion} to ${prepared.targetVersion}`,
+    `将 Agent Bot 从 ${prepared.currentVersion} 更新到 ${prepared.targetVersion}`,
+  );
+  try {
+    const notificationSessionId = serverRunning
+      ? resolveRestartNotificationSessionId(
+          config.storage.sqlitePath,
+          options.taskReference ? ["--task", options.taskReference] : [],
+        )
+      : undefined;
+    finalizeSelfUpdatePlan(prepared.planPath, {
+      controlEndpoint: endpoint,
+      databasePath: config.storage.sqlitePath,
+      restartService: serverRunning,
+      workingDirectory: process.cwd(),
+      reason,
+      notificationSessionId,
+    });
+    if (serverRunning) {
+      ensureOk(await sendControlRequest(endpoint, {
+        action: "server_update",
+        planPath: prepared.planPath,
+        reason,
+        notificationSessionId,
+      }, 15_000));
+    } else {
+      launchSelfUpdateRunner(prepared.planPath, { waitPids: [process.pid] });
+    }
+  } catch (error) {
+    releaseSelfUpdatePlan(prepared.planPath);
+    throw error;
+  }
+
+  const result = {
+    status: serverRunning ? "scheduled" : "started",
+    fromVersion: prepared.currentVersion,
+    toVersion: prepared.targetVersion,
+    channel: prepared.channel,
+    serviceWasRunning: serverRunning,
+    logPath: prepared.logPath,
+    resultPath: prepared.resultPath,
+  };
+  if (options.json) printJson(result);
+  else {
+    process.stdout.write(serverRunning
+      ? cliText(
+          `Agent Bot ${prepared.targetVersion} is verified and ready. The update will run after active tasks finish and the server becomes idle.\n`,
+          `Agent Bot ${prepared.targetVersion} 已通过预检。更新将在活动任务完成且服务空闲后执行。\n`,
+        )
+      : cliText(
+          `Agent Bot ${prepared.targetVersion} is verified. Installation will continue after this command exits.\n`,
+          `Agent Bot ${prepared.targetVersion} 已通过预检。本命令退出后将继续安装。\n`,
+        ));
+    process.stdout.write(`${cliText("Update log: ", "更新日志：")}${prepared.logPath}\n`);
+  }
+}
+
 type FeishuInitializationStatus = "created" | "existing" | "skipped";
 
 interface InitCommandResult extends InitializationResult {
@@ -150,12 +267,17 @@ interface InitCommandResult extends InitializationResult {
     name: string;
     status: "selected" | "existing";
   };
+  groupMessages: {
+    mode: GroupMessageResponseMode;
+    status: "selected" | "existing";
+  };
   feishu: {
     status: FeishuInitializationStatus;
     appId?: string;
     userOpenIdStatus?: "configured" | "pending";
     configuration?: EnsureFeishuAppConfigurationResult;
   };
+  skill: ReturnType<SkillRegistry["install"]>;
   server: InitializationServerResult;
   welcome: InitializationWelcomeResult;
 }
@@ -192,6 +314,11 @@ async function initCommand(
       options.json,
       shouldConfigureAgentsDuringInitialization(paths.config.status),
     );
+    const groupMessages = await configureGroupMessageResponse(
+      paths.config.path,
+      options.json,
+      shouldConfigureGroupMessagesDuringInitialization(paths.config.status),
+    );
     const configuredAgents = readConfiguredAgentSelection(paths.config.path).agents.map((agent) => agent.name);
     const configuredAgentNames = new Set(configuredAgents);
     const agents = inspectedAgents.map((agent) => ({
@@ -203,8 +330,10 @@ async function initCommand(
     const feishu = await initializeFeishu(
       paths,
       options,
+      groupMessages.mode === "all",
     );
-    initialized = { ...paths, agents, configuredAgents, defaultAgent, feishu };
+    const skill = bundledSkillRegistry().install();
+    initialized = { ...paths, agents, configuredAgents, defaultAgent, groupMessages, feishu, skill };
   } finally {
     initializationLock?.release();
   }
@@ -415,6 +544,76 @@ async function configureAgentsAndDefault(
   return { name: selectedDefault.name, status: updated ? "selected" : "existing" };
 }
 
+async function configureGroupMessageResponse(
+  configPath: string,
+  json: boolean,
+  configure: boolean,
+): Promise<InitCommandResult["groupMessages"]> {
+  const output = json ? process.stderr : process.stdout;
+  if (!configure) {
+    return { mode: readGroupMessageResponseMode(configPath), status: "existing" };
+  }
+
+  let mode: GroupMessageResponseMode = "mention-only";
+  if (process.stdin.isTTY) {
+    output.write(cliText(
+      "\nChoose how Agent Bot responds to group messages:\n  1. Receive all group messages\n     The bot can respond without an @ mention. This requires an additional Lark permission.\n  2. Require an explicit @ mention\n     The additional all-group-message permission will not be requested.\n",
+      "\n请选择 Agent Bot 响应群消息的方式：\n  1. 接收所有群消息\n     无需 @ 机器人即可响应，需要额外开通飞书权限。\n  2. 明确 @ 机器人才能接收消息\n     不会申请“免 @ 机器人”所需的额外权限。\n",
+    ));
+    mode = await promptForGroupMessageResponseMode();
+  } else {
+    output.write(cliText(
+      "No interactive terminal is available. Group messages will require an explicit @ mention, and the all-group-message permission will not be requested.\n",
+      "当前没有交互式终端。群消息将要求明确 @ 机器人，并且不会申请接收所有群消息的额外权限。\n",
+    ));
+  }
+
+  writeGroupMessageResponseMode(configPath, mode);
+  output.write(cliText(
+    `Group message response: ${mode === "all" ? "receive all group messages" : "require an explicit @ mention"}\n`,
+    `群消息响应方式：${mode === "all" ? "接收所有群消息" : "必须明确 @ 机器人"}\n`,
+  ));
+  return { mode, status: "selected" };
+}
+
+function promptForGroupMessageResponseMode(): Promise<GroupMessageResponseMode> {
+  const readline = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (mode: GroupMessageResponseMode): void => {
+      settled = true;
+      readline.close();
+      resolve(mode);
+    };
+    const ask = (): void => {
+      readline.question(cliText(
+        "Select 1 or 2 [2]: ",
+        "请选择 1 或 2 [2]：",
+      ), (answer) => {
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === "1") {
+          finish("all");
+          return;
+        }
+        if (normalized === "" || normalized === "2") {
+          finish("mention-only");
+          return;
+        }
+        process.stderr.write(cliText(
+          "Enter 1 to receive all group messages, or 2 to require an @ mention.\n",
+          "请输入 1 接收所有群消息，或输入 2 要求明确 @ 机器人。\n",
+        ));
+        ask();
+      });
+    };
+    listenForPromptCancellation(readline, () => {
+      settled = true;
+      reject(new Error(cliText("Initialization was cancelled.", "初始化已取消。")));
+    }, () => settled);
+    ask();
+  });
+}
+
 function promptForAgentMaintenance(choiceCount: number): Promise<number[]> {
   const readline = createInterface({ input: process.stdin, output: process.stderr });
   return new Promise((resolve, reject) => {
@@ -577,6 +776,7 @@ function refreshCurrentProcessPath(): void {
 async function initializeFeishu(
   paths: InitializationResult,
   options: InitCommandOptions,
+  respondToAllGroupMessages: boolean,
 ): Promise<InitCommandResult["feishu"]> {
   const existing = readFeishuCredentials(paths.env.path);
   if (options.skipFeishu) {
@@ -634,6 +834,7 @@ async function initializeFeishu(
     const optionalSkip = new AbortController();
     let skipListener: OptionalAuthorizationSkipListener | undefined;
     const configuration = await ensureFeishuAppConfiguration(credentials, {
+      respondToAllGroupMessages,
       signal: controller.signal,
       manualPermissionSkipSignal: manualPermissionSkip.signal,
       optionalSkipSignal: optionalSkip.signal,
@@ -686,9 +887,8 @@ async function assertResetProfileServerStopped(configPath?: string): Promise<voi
 
 function skillsCommand(input: string[]): void {
   const [action = "status", ...rest] = input;
-  const sourcePath = fileURLToPath(new URL("../skills/agent-bot/", import.meta.url));
   const targetRoot = optionValue(rest, "--target") ?? resolveSystemSkillsRoot();
-  const registry = new SkillRegistry(sourcePath, targetRoot);
+  const registry = bundledSkillRegistry(targetRoot);
   const json = rest.includes("--json");
 
   if (action === "install" || action === "register") {
@@ -738,6 +938,11 @@ function skillsCommand(input: string[]): void {
   throw new Error(cliText(`Unknown skills command: ${action}`, `未知的 skills 命令：${action}`));
 }
 
+function bundledSkillRegistry(targetRoot = resolveSystemSkillsRoot()): SkillRegistry {
+  const sourcePath = fileURLToPath(new URL("../skills/agent-bot/", import.meta.url));
+  return new SkillRegistry(sourcePath, targetRoot);
+}
+
 async function consoleCommand(input: string[]): Promise<void> {
   const config = loadConfig();
   const endpoint = controlEndpoint(config.storage.sqlitePath);
@@ -791,6 +996,10 @@ async function serverCommand(input: string[]): Promise<void> {
     printServerStartResult(await startServer(config));
     return;
   }
+  if (action === "autostart") {
+    await serverAutostartCommand(config, endpoint, rest);
+    return;
+  }
   if (action === "stop") {
     ensureOk(await sendControlRequest(endpoint, { action: "server_stop" }));
     process.stdout.write(cliText("Agent Bot server stop requested.\n", "已请求停止 Agent Bot 服务。\n"));
@@ -815,6 +1024,64 @@ async function serverCommand(input: string[]): Promise<void> {
   throw new Error(cliText(`Unknown server command: ${action}`, `未知的 server 命令：${action}`));
 }
 
+async function serverAutostartCommand(
+  config: ReturnType<typeof loadConfig>,
+  endpoint: string,
+  input: string[],
+): Promise<void> {
+  const actionIndex = input.findIndex((value) => !value.startsWith("--"));
+  const action = actionIndex < 0 ? "status" : input[actionIndex]!;
+  const rest = input.filter((_value, index) => index !== actionIndex);
+  const json = rest.includes("--json");
+  const linger = rest.includes("--linger");
+  const unsupported = rest.filter((value) => value !== "--json" && value !== "--linger");
+  if (unsupported.length > 0) throw new Error(cliText(
+    `Unsupported server autostart options: ${unsupported.join(" ")}`,
+    `不支持这些 server autostart 参数：${unsupported.join(" ")}`,
+  ));
+  if (action !== "enable" && linger) {
+    throw new Error(cliText(
+      "--linger can be used only with server autostart enable.",
+      "--linger 只能与 server autostart enable 一起使用。",
+    ));
+  }
+
+  const manager = createCurrentAutostartManager(config);
+  let registration;
+  if (action === "enable") {
+    registration = manager.enable({ linger });
+  } else if (action === "disable") {
+    registration = manager.disable();
+  } else if (action === "status") {
+    registration = manager.status();
+  } else {
+    throw new Error(cliText(
+      `Unknown server autostart command: ${action}`,
+      `未知的 server autostart 命令：${action}`,
+    ));
+  }
+
+  const result: CombinedAutostartStatus = {
+    registration,
+    server: await readAutostartServerStatus(endpoint),
+  };
+  if (json) printJson(result);
+  else process.stdout.write(formatAutostartStatus(result));
+}
+
+async function readAutostartServerStatus(endpoint: string): Promise<AutostartServerStatus> {
+  try {
+    const response = await sendControlRequest(endpoint, { action: "health" }, 1_500);
+    if (!response.ok) return { running: true, ready: false };
+    const data = response.data && typeof response.data === "object"
+      ? response.data as Record<string, unknown>
+      : {};
+    return { running: true, ready: data.ready !== false };
+  } catch {
+    return { running: false, ready: false };
+  }
+}
+
 function resolveRestartNotificationSessionId(sqlitePath: string, args: string[]): string | undefined {
   const store = new StateStore(sqlitePath);
   try {
@@ -857,6 +1124,10 @@ async function taskCommand(input: string[]): Promise<void> {
   const store = new StateStore(config.storage.sqlitePath);
   try {
     const allSessions = store.listAllSessions();
+    if (action === "help" || action === "--help" || action === "-h") {
+      printHelp();
+      return;
+    }
     if (action === "current") {
       const unsupported = rest.filter((value) => value !== "--json");
       if (unsupported.length > 0) throw new Error(cliText(
@@ -868,29 +1139,296 @@ async function taskCommand(input: string[]): Promise<void> {
       return;
     }
     if (action === "prompt" || action === "send") {
-      const [reference, ...promptParts] = rest;
-      if (!reference) throw new Error(cliText(
-        `task ${action} requires a task number or task ID.`,
-        `task ${action} 需要任务序号或任务 ID。`,
-      ));
-      const text = promptParts.join(" ").trim();
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const text = target.args.join(" ").trim();
       if (!text) throw new Error(cliText(
         `task ${action} requires a Prompt.`,
         `task ${action} 需要提示词。`,
       ));
-      const session = resolveTask(allSessions, reference);
       const endpoint = controlEndpoint(config.storage.sqlitePath);
       ensureOk(await sendControlRequest(endpoint, {
         action: "task_prompt",
-        localSessionId: session.localSessionId,
+        localSessionId: target.session.localSessionId,
         text,
       }, 60_000));
       process.stdout.write(cliText("Prompt submitted.\n", "提示词已提交。\n"));
       return;
     }
+    if (action === "new") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const options = parseTaskNewOptions([target.session.localSessionId, ...target.args]);
+      const source = target.session;
+      const targetAgent = options.agentName ? config.agents[options.agentName] : undefined;
+      if (options.agentName && !targetAgent) throw new Error(cliText(
+        `Unknown Agent standard name: ${options.agentName}.`,
+        `未知的 Agent 标准名：${options.agentName}。`,
+      ));
+      if (options.projectless && targetAgent && targetAgent.kind !== "app-server") throw new Error(cliText(
+        "task new --nodir is only available for App Server agents.",
+        "task new --nodir 仅适用于 App Server Agent。",
+      ));
+      const created = controlData<SessionRecord>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_new",
+        localSessionId: source.localSessionId,
+        ...(options.title ? { title: options.title } : {}),
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.agentName ? { agentName: options.agentName } : {}),
+        ...(options.projectless ? { projectless: true } : {}),
+      }, 120_000));
+      if (options.json) printJson(created);
+      else printCreatedTask(created, "Task created");
+      return;
+    }
+    if (action === "fork") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const options = target.args;
+      rejectUnsupportedTaskOptions(action, options, ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task fork accepts only one task reference.",
+        "task fork 只接受一个任务引用。",
+      ));
+      const result = controlData<TaskForkControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_fork",
+        localSessionId: target.session.localSessionId,
+      }, 120_000));
+      if (options.includes("--json")) printJson(result);
+      else {
+        printCreatedTask(result.task, "Fork created");
+        process.stdout.write(`${cliText("Source turn: ", "来源 Turn：")}${result.sourceTurnId}\n`);
+      }
+      return;
+    }
+    if (action === "archive") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const options = target.args;
+      rejectUnsupportedTaskOptions(action, options, ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task archive accepts only one task reference.",
+        "task archive 只接受一个任务引用。",
+      ));
+      const archived = controlData<{
+        localSessionId: string;
+        remoteSessionId: string;
+        title: string;
+      }>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_archive",
+        localSessionId: target.session.localSessionId,
+      }, 60_000));
+      if (options.includes("--json")) printJson(archived);
+      else process.stdout.write(cliText(
+        `Task archived: ${archived.title} (${archived.remoteSessionId})\n`,
+        `任务已归档：${archived.title}（${archived.remoteSessionId}）\n`,
+      ));
+      return;
+    }
+    if (action === "switch") {
+      const targetSelection = resolveTaskCommandTarget(allSessions, rest, action, { preferCurrent: true });
+      const switchArgs = targetSelection.args;
+      rejectUnsupportedTaskOptions(action, switchArgs, ["--json", "--previous"]);
+      const previous = switchArgs.includes("--previous");
+      const targetReferences = switchArgs.filter((value) => !value.startsWith("--"));
+      if (targetReferences.length > 1) throw new Error(cliText(
+        "task switch accepts at most one target task.",
+        "task switch 最多接受一个目标任务。",
+      ));
+      const targetReference = targetReferences[0];
+      if (previous && targetReference) throw new Error(cliText(
+        "task switch cannot combine a target task with --previous.",
+        "task switch 不能同时指定目标任务和 --previous。",
+      ));
+      const target = targetReference ? resolveTask(allSessions, targetReference) : undefined;
+      const switched = controlData<SessionRecord>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_switch",
+        localSessionId: targetSelection.session.localSessionId,
+        ...(target ? { targetLocalSessionId: target.localSessionId } : {}),
+        ...(previous ? { previous: true } : {}),
+      }));
+      if (switchArgs.includes("--json")) printJson(switched);
+      else printCreatedTask(switched, "Current task");
+      return;
+    }
+    if (action === "queue" || action === "nosteer") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const text = target.args.join(" ").trim();
+      if (!text) throw new Error(cliText(
+        `task ${action} requires a Prompt.`,
+        `task ${action} 需要提示词。`,
+      ));
+      const result = controlData<{ promptId: string; queued: number }>(await sendControlRequest(
+        controlEndpoint(config.storage.sqlitePath),
+        { action: "task_queue", localSessionId: target.session.localSessionId, text },
+      ));
+      process.stdout.write(cliText(
+        `Prompt queued (${result.queued} waiting): ${result.promptId}\n`,
+        `提示词已排队（当前 ${result.queued} 条）：${result.promptId}\n`,
+      ));
+      return;
+    }
+    if (action === "agent") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const [agentName, ...options] = target.args;
+      rejectUnsupportedTaskOptions(action, [agentName, ...options].filter((value): value is string => value !== undefined), ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task agent accepts at most one Agent name.",
+        "task agent 最多接受一个 Agent 名称。",
+      ));
+      const result = controlData<TaskAgentControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_agent",
+        localSessionId: target.session.localSessionId,
+        ...(agentName && !agentName.startsWith("--") ? { agentName } : {}),
+      }));
+      const json = options.includes("--json") || agentName === "--json";
+      if (json) printJson(result);
+      else printTaskAgentSettings(result);
+      return;
+    }
+    if (["provider", "model", "thinking", "permissions"].includes(action)) {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const [rawValue, ...options] = target.args;
+      rejectUnsupportedTaskOptions(action, [rawValue, ...options].filter((value): value is string => value !== undefined), ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        `task ${action} accepts at most one value.`,
+        `task ${action} 最多接受一个值。`,
+      ));
+      const value = rawValue && !rawValue.startsWith("--") ? rawValue : undefined;
+      const json = options.includes("--json") || rawValue === "--json";
+      const result = controlData<TaskSettingsControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_settings",
+        localSessionId: target.session.localSessionId,
+        ...(value ? { setting: action as "provider" | "model" | "thinking" | "permissions", value } : {}),
+      }, 60_000));
+      if (json) printJson(result);
+      else printTaskSettings(result, action as "provider" | "model" | "thinking" | "permissions");
+      return;
+    }
+    if (action === "goal") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const goalArgs = target.args;
+      const json = goalArgs.includes("--json");
+      const args = goalArgs.filter((value) => value !== "--json");
+      rejectUnsupportedTaskOptions(action, goalArgs, ["--json"]);
+      const parsedGoal = parseTaskGoal(args);
+      const result = controlData<TaskGoalControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_goal",
+        localSessionId: target.session.localSessionId,
+        goalAction: parsedGoal.action,
+        ...(parsedGoal.objective ? { objective: parsedGoal.objective } : {}),
+      }));
+      if (json) printJson(result);
+      else printTaskGoal(result);
+      return;
+    }
+    if (action === "turns") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const options = target.args;
+      rejectUnsupportedTaskOptions(action, options, ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task turns accepts only one task reference.",
+        "task turns 只接受一个任务引用。",
+      ));
+      const result = controlData<TaskTurnsControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_turns",
+        localSessionId: target.session.localSessionId,
+      }, 60_000));
+      if (options.includes("--json")) printJson(result);
+      else printTaskTurns(result);
+      return;
+    }
+    if (action === "reset") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const [turnId, ...options] = target.args;
+      if (!turnId || turnId.startsWith("--")) throw new Error(cliText(
+        "task reset requires a Turn ID.",
+        "task reset 需要 Turn ID。",
+      ));
+      rejectUnsupportedTaskOptions(action, options, ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task reset accepts one task reference and one Turn ID.",
+        "task reset 只接受一个任务引用和一个 Turn ID。",
+      ));
+      const result = controlData<SessionRecord>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_reset",
+        localSessionId: target.session.localSessionId,
+        turnId,
+      }, 120_000));
+      if (options.includes("--json")) printJson(result);
+      else process.stdout.write(cliText(`Task reset to turn ${turnId}.\n`, `任务已 Reset 到 Turn ${turnId}。\n`));
+      return;
+    }
+    if (action === "mute") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const [rawMode, ...options] = target.args;
+      rejectUnsupportedTaskOptions(action, [rawMode, ...options].filter((value): value is string => value !== undefined), ["--json"]);
+      if (options.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task mute accepts at most one mode.",
+        "task mute 最多接受一个模式。",
+      ));
+      const mode = rawMode && !rawMode.startsWith("--") ? rawMode.toLowerCase() : "on";
+      if (mode && mode !== "on" && mode !== "off") throw new Error(cliText(
+        "task mute accepts on or off.",
+        "task mute 只接受 on 或 off。",
+      ));
+      const result = controlData<TaskMuteControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_mute",
+        localSessionId: target.session.localSessionId,
+        enabled: mode === "on",
+      }));
+      const json = options.includes("--json") || rawMode === "--json";
+      if (json) printJson(result);
+      else process.stdout.write(cliText(
+        `Mention-only mode: ${result.enabled ? "on" : "off"}\n`,
+        `仅 @ 响应模式：${result.enabled ? "开启" : "关闭"}\n`,
+      ));
+      return;
+    }
+    if (action === "shell") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const command = target.args.join(" ").trim();
+      if (!command) throw new Error(cliText("task shell requires a command.", "task shell 需要命令。"));
+      const result = controlData<TaskShellControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_shell",
+        localSessionId: target.session.localSessionId,
+        command,
+      }, 130_000));
+      printTaskShellResult(result);
+      if (result.exitCode && result.exitCode !== 0) process.exitCode = result.exitCode;
+      return;
+    }
+    if (action === "dir") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const parsedDirectory = parseTaskDirectoryArgs([target.session.localSessionId, ...target.args]);
+      const result = controlData<TaskDirectoryControlData>(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_directory",
+        localSessionId: target.session.localSessionId,
+        ...(parsedDirectory.directory ? { directory: parsedDirectory.directory } : {}),
+        ...(parsedDirectory.page !== undefined ? { page: parsedDirectory.page } : {}),
+      }, 60_000));
+      if (parsedDirectory.json) printJson(result);
+      else printTaskDirectory(result);
+      return;
+    }
+    if (action === "file") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const filePath = target.args.join(" ").trim();
+      if (!filePath) throw new Error(cliText("task file requires a path.", "task file 需要文件路径。"));
+      ensureOk(await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
+        action: "task_send_file",
+        localSessionId: target.session.localSessionId,
+        filePath,
+      }, 120_000));
+      process.stdout.write(cliText("File sent to the task conversation.\n", "文件已发送到任务会话。\n"));
+      return;
+    }
+    if (action === "restart") {
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const translated = target.args.flatMap((value) => value === "--force" ? ["--immediate"] : [value]);
+      await serverCommand(["restart", "--task", target.session.localSessionId, ...translated]);
+      return;
+    }
     if (action === "newgroup") {
-      const options = parseTaskNewGroupOptions(rest);
-      const session = resolveTask(allSessions, options.reference);
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const options = parseTaskNewGroupOptions([target.session.localSessionId, ...target.args]);
+      const session = target.session;
       const targetAgentName = options.agentName ?? session.agentName;
       const targetAgent = config.agents[targetAgentName];
       if (!targetAgent) {
@@ -920,8 +1458,9 @@ async function taskCommand(input: string[]): Promise<void> {
       return;
     }
     if (action === "forkgroup") {
-      const options = parseTaskForkGroupOptions(rest);
-      const session = resolveTask(allSessions, options.reference);
+      const target = resolveTaskCommandTarget(allSessions, rest, action);
+      const options = parseTaskForkGroupOptions([target.session.localSessionId, ...target.args]);
+      const session = target.session;
       requireCliGroupUser(config.feishu.userOpenId);
       const response = await sendControlRequest(controlEndpoint(config.storage.sqlitePath), {
         action: "task_fork_group",
@@ -933,37 +1472,50 @@ async function taskCommand(input: string[]): Promise<void> {
       else printTaskGroupResult(result, "forkgroup");
       return;
     }
-    const sessions = filterSessions(allSessions, rest);
-    if (action === "list") {
+    const sessions = filterSessions(
+      allSessions,
+      rest,
+      action === "sessions" ? taskSessionsSearchTerm(rest) : undefined,
+    );
+    if (action === "list" || action === "sessions") {
       if (rest.includes("--json")) printJson(sessions);
       else printTaskList(sessions);
       return;
     }
-    const reference = rest.find((value) => !value.startsWith("--"));
-    if (!reference) throw new Error(cliText(
-      `task ${action} requires a task number or task ID.`,
-      `task ${action} 需要任务序号或任务 ID。`,
-    ));
-    const session = resolveTask(sessions, reference);
+    const target = resolveTaskCommandTarget(allSessions, rest, action);
+    const session = target.session;
     if (action === "chat") {
+      rejectUnsupportedTaskOptions(action, target.args, ["--json"]);
+      if (target.args.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task chat accepts only one task reference.",
+        "task chat 只接受一个任务引用。",
+      ));
       const route = taskChatRoute(session);
-      if (rest.includes("--json")) printJson(route);
+      if (target.args.includes("--json")) printJson(route);
       else process.stdout.write(`${route.chatId}\n`);
       return;
     }
     if (action === "status") {
-      await outputTaskStatus(config.storage.sqlitePath, store, session, rest.includes("--json"));
+      rejectUnsupportedTaskOptions(action, target.args, ["--json"]);
+      if (target.args.some((value) => !value.startsWith("--"))) throw new Error(cliText(
+        "task status accepts only one task reference.",
+        "task status 只接受一个任务引用。",
+      ));
+      await outputTaskStatus(config.storage.sqlitePath, store, session, target.args.includes("--json"));
       return;
     }
     const endpoint = controlEndpoint(config.storage.sqlitePath);
     if (action === "stop") {
+      if (target.args.length > 0) throw new Error(cliText(
+        "task stop accepts only one task reference.",
+        "task stop 只接受一个任务引用。",
+      ));
       ensureOk(await sendControlRequest(endpoint, { action: "task_stop", localSessionId: session.localSessionId }));
       process.stdout.write(cliText("Task stop requested.\n", "已请求停止任务。\n"));
       return;
     }
     if (action === "title") {
-      const referenceIndex = rest.indexOf(reference);
-      const titleArgs = rest.slice(referenceIndex + 1);
+      const titleArgs = target.args;
       const optionIndex = titleArgs.findIndex((value) => value.startsWith("--"));
       const title = titleArgs.slice(0, optionIndex < 0 ? undefined : optionIndex).join(" ").trim();
       if (!title) throw new Error(cliText(
@@ -984,20 +1536,179 @@ async function taskCommand(input: string[]): Promise<void> {
   }
 }
 
-function resolveCurrentTaskFromEnvironment(sessions: SessionRecord[]): SessionRecord {
-  const resolution = resolveCurrentTask(sessions, currentAppServerThreadIds(process.env));
-  if (resolution.status === "found") return resolution.session;
-  if (resolution.status === "missing-thread-id") throw new Error(cliText(
-    "The current task cannot be detected because neither CODEX_THREAD_ID nor TRAECLI_THREAD_ID is set. Run this command from a Codex or TraeX task.",
-    "无法检测当前任务：CODEX_THREAD_ID 和 TRAECLI_THREAD_ID 均未设置。请从 Codex 或 TraeX 任务中运行此命令。",
-  ));
-  if (resolution.status === "not-found") throw new Error(cliText(
-    `No AgentBot task matches the current App Server Thread ID (${resolution.threadIds.join(", ")}). Check that the correct Profile is selected.`,
-    `没有 AgentBot 任务匹配当前 App Server Thread ID（${resolution.threadIds.join("，")}）。请检查是否选择了正确的 Profile。`,
+function requireTaskCommandReference(action: string, reference: string | undefined): asserts reference is string {
+  if (reference && !reference.startsWith("--")) return;
+  throw new Error(cliText(
+    `task ${action} requires a task number or task ID.`,
+    `task ${action} 需要任务序号或任务 ID。`,
   ));
+}
+
+function rejectUnsupportedTaskOptions(action: string, args: string[], supported: string[]): void {
+  const unsupported = args.find((value) => value.startsWith("--") && !supported.includes(value));
+  if (!unsupported) return;
   throw new Error(cliText(
-    "The current task is ambiguous because multiple injected Thread IDs match AgentBot tasks. Use task status <task> with an explicit AgentBot task ID.",
-    "当前任务存在歧义：多个注入的 Thread ID 匹配到了 AgentBot 任务。请使用明确的 AgentBot 任务 ID 执行 task status <任务>。",
+    `task ${action} does not support option: ${unsupported}.`,
+    `task ${action} 不支持参数：${unsupported}。`,
+  ));
+}
+
+function parseTaskGoal(args: string[]): {
+  action: "show" | "set" | "edit" | "pause" | "resume" | "clear";
+  objective?: string;
+} {
+  if (args.length === 0 || args[0]?.toLowerCase() === "show") return { action: "show" };
+  const first = args[0]!.toLowerCase();
+  if (first === "pause" || first === "resume" || first === "clear") {
+    if (args.length > 1) throw new Error(cliText(
+      `task goal ${first} does not accept extra arguments.`,
+      `task goal ${first} 不接受额外参数。`,
+    ));
+    return { action: first };
+  }
+  const action = first === "set" || first === "edit" ? first : "set";
+  const objective = (action === "set" && first !== "set" ? args : args.slice(1)).join(" ").trim();
+  if (!objective) throw new Error(cliText(
+    `task goal ${action} requires an objective.`,
+    `task goal ${action} 需要目标。`,
+  ));
+  return { action, objective };
+}
+
+function parseTaskDirectoryArgs(args: string[]): {
+  reference: string;
+  directory?: string;
+  page?: number;
+  json: boolean;
+} {
+  const positionals: string[] = [];
+  let page: number | undefined;
+  let json = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index]!;
+    if (value === "--json") {
+      json = true;
+      continue;
+    }
+    if (value === "--page") {
+      const rawPage = args[index + 1];
+      const parsedPage = rawPage === undefined ? Number.NaN : Number(rawPage);
+      if (!Number.isSafeInteger(parsedPage) || parsedPage < 1) throw new Error(cliText(
+        "task dir --page requires a positive page number.",
+        "task dir --page 需要正整数页码。",
+      ));
+      page = parsedPage - 1;
+      index += 1;
+      continue;
+    }
+    if (value.startsWith("--")) throw new Error(cliText(
+      `task dir does not support option: ${value}.`,
+      `task dir 不支持参数：${value}。`,
+    ));
+    positionals.push(value);
+  }
+  const [reference, ...directoryParts] = positionals;
+  requireTaskCommandReference("dir", reference);
+  return {
+    reference,
+    directory: directoryParts.join(" ").trim() || undefined,
+    page,
+    json,
+  };
+}
+
+function controlData<T>(response: ControlResponse): T {
+  ensureOk(response);
+  if (response.data === undefined) throw new Error(cliText(
+    "Agent Bot returned no control result.",
+    "Agent Bot 没有返回控制结果。",
+  ));
+  return response.data as T;
+}
+
+function printCreatedTask(session: SessionRecord, label: string): void {
+  process.stdout.write(`${cliText(`${label}: `, `${label === "Current task" ? "当前任务" : label === "Fork created" ? "分支任务已创建" : "任务已创建"}：`)}${session.title ?? "-"}\n`);
+  process.stdout.write(`${cliText("Local ID: ", "本地 ID：")}${session.localSessionId}\n`);
+  if (session.remoteSessionId) process.stdout.write(`${cliText("Agent task ID: ", "Agent 任务 ID：")}${session.remoteSessionId}\n`);
+  process.stdout.write(`${cliText("Agent: ", "Agent：")}${session.agentName}\n`);
+  process.stdout.write(`${cliText("Directory: ", "目录：")}${session.cwd}\n`);
+}
+
+function printTaskAgentSettings(result: TaskAgentControlData): void {
+  process.stdout.write(`${cliText("Default Agent: ", "默认 Agent：")}${result.current}\n`);
+  process.stdout.write(`${cliText("Available Agents: ", "可用 Agent：")}${result.agents.map((agent) => `${agent.name} (${agent.title})`).join(", ")}\n`);
+}
+
+function printTaskSettings(
+  result: TaskSettingsControlData,
+  setting: "provider" | "model" | "thinking" | "permissions",
+): void {
+  const session = result.session;
+  process.stdout.write(`${cliText("Provider: ", "Provider：")}${session.modelProvider ?? cliText("Agent default", "Agent 默认")}\n`);
+  process.stdout.write(`${cliText("Model: ", "模型：")}${session.model ?? cliText("default", "默认")}\n`);
+  process.stdout.write(`${cliText("Thinking: ", "思考强度：")}${session.reasoningEffort ?? cliText("automatic", "自动")}\n`);
+  process.stdout.write(`${cliText("Permissions: ", "权限：")}${session.permissionMode ?? "auto"}\n`);
+  if (setting === "provider") {
+    process.stdout.write(`${cliText("Available Providers: ", "可用 Provider：")}${result.providers.map((item) => item.id).join(", ") || "-"}\n`);
+  } else if (setting === "model") {
+    process.stdout.write(`${cliText("Available Models: ", "可用模型：")}${result.models.map((item) => item.id).join(", ") || "-"}\n`);
+  } else if (setting === "thinking") {
+    process.stdout.write(`${cliText("Available Thinking Levels: ", "可用思考强度：")}${result.reasoningOptions.map((item) => item.value).join(", ") || "-"}\n`);
+  } else {
+    process.stdout.write(`${cliText("Available Permission Modes: ", "可用权限模式：")}${result.permissionModes.join(", ")}\n`);
+  }
+}
+
+function printTaskGoal(result: TaskGoalControlData): void {
+  if (!result.goal) {
+    process.stdout.write(result.cleared
+      ? cliText("Goal cleared.\n", "Goal 已清除。\n")
+      : cliText("No Goal is configured.\n", "当前没有 Goal。\n"));
+    return;
+  }
+  process.stdout.write(`${cliText("Goal: ", "Goal：")}${result.goal.objective}\n`);
+  process.stdout.write(`${cliText("Status: ", "状态：")}${result.goal.status}\n`);
+  process.stdout.write(`${cliText("Tokens used: ", "已用 Tokens：")}${result.goal.tokensUsed}\n`);
+  process.stdout.write(`${cliText("Time used: ", "已用时间：")}${result.goal.timeUsedSeconds}s\n`);
+}
+
+function printTaskTurns(result: TaskTurnsControlData): void {
+  process.stdout.write(`${cliText("Task: ", "任务：")}${result.session.title ?? result.session.localSessionId}\n`);
+  if (result.turns.length === 0) {
+    process.stdout.write(cliText("No completed turns.\n", "没有已完成的 Turn。\n"));
+    return;
+  }
+  for (const turn of result.turns) {
+    const marker = turn.current ? "*" : " ";
+    const parent = turn.parentTurnId ? ` <- ${turn.parentTurnId}` : "";
+    process.stdout.write(`${marker} ${turn.sequence}. ${turn.prompt?.replace(/\s+/g, " ").trim() || "-"}\n`);
+    process.stdout.write(`    ${turn.turnId}${parent}\n`);
+  }
+}
+
+function printTaskShellResult(result: TaskShellControlData): void {
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (!result.stdout && !result.stderr) process.stdout.write(cliText("(no output)\n", "（无输出）\n"));
+  if (result.timedOut) process.stderr.write(cliText("Command timed out after 120 seconds.\n", "命令在 120 秒后超时。\n"));
+}
+
+function printTaskDirectory(result: TaskDirectoryControlData): void {
+  process.stdout.write(`${cliText("Directory: ", "目录：")}${result.directory}\n`);
+  if (result.parentDirectory) process.stdout.write(`  [D] .. -> ${result.parentDirectory}\n`);
+  for (const entry of result.entries) {
+    const marker = entry.kind === "directory" || entry.kind === "drive"
+      ? "D"
+      : entry.kind === "image"
+        ? "I"
+        : entry.kind === "binary"
+          ? "B"
+          : "F";
+    process.stdout.write(`  [${marker}] ${entry.name}\n`);
+  }
+  process.stdout.write(cliText(
+    `Page ${result.page + 1}/${result.totalPages}; ${result.totalEntries} entries.\n`,
+    `第 ${result.page + 1}/${result.totalPages} 页；共 ${result.totalEntries} 项。\n`,
   ));
 }
 
@@ -1031,37 +1742,35 @@ async function outputTaskStatus(
   else printTaskStatus(statusSession, snapshot, live?.remote);
 }
 
-function filterSessions(sessions: SessionRecord[], args: string[]): SessionRecord[] {
+function filterSessions(sessions: SessionRecord[], args: string[], aliasSearchTerm?: string): SessionRecord[] {
   const context = optionValue(args, "--context");
   const status = optionValue(args, "--status");
+  const search = (optionValue(args, "--search") ?? aliasSearchTerm)?.trim().toLowerCase();
   return sessions.filter((session) =>
     (!context || session.contextKey === context)
-    && (!status || session.status === status || session.lastTurnStatus === status));
+    && (!status || session.status === status || session.lastTurnStatus === status)
+    && (!search || [
+      session.localSessionId,
+      session.remoteSessionId,
+      session.acpSessionId,
+      session.title,
+      session.agentName,
+      session.cwd,
+    ].some((value) => value?.toLowerCase().includes(search))));
 }
 
-function resolveTask(sessions: SessionRecord[], reference: string): SessionRecord {
-  if (/^\d+$/.test(reference)) {
-    const index = Number(reference) - 1;
-    const session = sessions[index];
-    if (!session) throw new Error(cliText(
-      `Task number is out of range: ${reference}`,
-      `任务序号超出范围：${reference}`,
-    ));
-    return session;
-  }
-  const exact = sessions.find((session) =>
-    session.localSessionId === reference || session.remoteSessionId === reference || session.acpSessionId === reference);
-  if (exact) return exact;
-  const matches = sessions.filter((session) =>
-    session.localSessionId.startsWith(reference)
-    || session.remoteSessionId?.startsWith(reference)
-    || session.acpSessionId?.startsWith(reference));
-  if (matches.length === 1) return matches[0]!;
-  if (matches.length > 1) throw new Error(cliText(
-    `Task ID prefix is ambiguous: ${reference}`,
-    `任务 ID 前缀不唯一：${reference}`,
-  ));
-  throw new Error(cliText(`Task not found: ${reference}`, `未找到任务：${reference}`));
+function taskSessionsSearchTerm(args: string[]): string | undefined {
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index]!;
+    if (value === "--json") continue;
+    if (value === "--context" || value === "--status" || value === "--search") {
+      index += 1;
+      continue;
+    }
+    if (!value.startsWith("--")) positionals.push(value);
+  }
+  return positionals.join(" ").trim() || undefined;
 }
 
 function printTaskList(sessions: SessionRecord[]): void {
@@ -1136,6 +1845,13 @@ function printInitializationResult(result: Omit<InitCommandResult, "server" | "w
   ));
   process.stdout.write(`${cliText("Configured Agents: ", "已配置 Agent：")}${result.configuredAgents.join(", ")}\n`);
   process.stdout.write(`${cliText("Default Agent: ", "默认 Agent：")}${result.defaultAgent.name}\n`);
+  process.stdout.write(cliText(
+    `Group message response: ${result.groupMessages.mode === "all" ? "receive all group messages" : "require an explicit @ mention"}\n`,
+    `群消息响应方式：${result.groupMessages.mode === "all" ? "接收所有群消息" : "必须明确 @ 机器人"}\n`,
+  ));
+  process.stdout.write(result.skill.updated
+    ? `${cliText("Agent Bot Skill: installed or updated at ", "Agent Bot Skill：已安装或更新至 ")}${result.skill.status.targetPath}\n`
+    : `${cliText("Agent Bot Skill: already up to date at ", "Agent Bot Skill：已是最新版本，位于 ")}${result.skill.status.targetPath}\n`);
   if (result.feishu.status === "created") {
     process.stdout.write(cliText(
       `Lark app: created and credentials saved (${result.feishu.appId})\n`,