@jingyi0605/codingns 0.3.5 → 0.4.0

package/bin/codingns.mjs

@@ -139,6 +139,32 @@ async function runAssistantCommand(argv) {
       }));
       return;
     }
+    case "sessions:start": {
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/sessions/start",
+        argv: rest,
+        supportedOptions: [
+          "project",
+          "workspace",
+          "sandbox",
+          "message",
+          "provider",
+          "model",
+          "reasoning-level",
+          "permission-mode"
+        ],
+        helpTopic: "sessions.start"
+      }, (options) => ({
+        ...resolveAssistantSessionStartTarget(options.values),
+        content: requireOptionValue(options.values.message, "message"),
+        providerId: readOptionalTrimmedValue(options.values.provider),
+        model: readOptionalTrimmedValue(options.values.model),
+        reasoningLevel: readOptionalTrimmedValue(options.values["reasoning-level"]),
+        permissionMode: readOptionalTrimmedValue(options.values["permission-mode"])
+      })));
+      return;
+    }
     case "sessions:get": {
       const [sessionId, ...tail] = rest;
       await printAssistantResponse(await requestAssistant({
@@ -207,6 +233,237 @@ async function runAssistantCommand(argv) {
       })));
       return;
     }
+    case "automations:list":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/automations",
+        argv: rest,
+        supportedOptions: ["status", "control-session-id"],
+        helpTopic: "automations.list"
+      }, (options) => ({
+        status: readOptionalTrimmedValue(options.values.status),
+        controlSessionId: readOptionalTrimmedValue(options.values["control-session-id"])
+      })));
+      return;
+    case "automations:get": {
+      const [automationId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/automations/${requirePositional(automationId, "automationId")}`,
+        argv: tail,
+        helpTopic: "automations.get"
+      }));
+      return;
+    }
+    case "automations:create":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/automations",
+        argv: rest,
+        supportedOptions: [
+          "message",
+          "trigger",
+          "title",
+          "due-at",
+          "after-seconds",
+          "every-seconds",
+          "every-minutes",
+          "every-hours",
+          "stop-at",
+          "cron-minute",
+          "cron-hour",
+          "cron-day-of-week",
+          "condition-kind",
+          "repository-url",
+          "poll-interval-seconds",
+          "expires-at",
+          "max-checks",
+          "condition-session-id",
+          "control-session-id",
+          "project-id",
+          "session-id"
+        ],
+        supportedFlags: ["include-trigger-context"],
+        repeatableOptions: ["cron-day-of-week"],
+        helpTopic: "automations.create"
+      }, (options) => ({
+        content: requireOptionValue(options.values.message, "message"),
+        triggerType: readOptionalTrimmedValue(options.values.trigger),
+        title: readOptionalTrimmedValue(options.values.title),
+        dueAt: readOptionalTrimmedValue(options.values["due-at"]),
+        afterSeconds: readOptionalTrimmedValue(options.values["after-seconds"]),
+        everySeconds: readOptionalTrimmedValue(options.values["every-seconds"]),
+        everyMinutes: readOptionalTrimmedValue(options.values["every-minutes"]),
+        everyHours: readOptionalTrimmedValue(options.values["every-hours"]),
+        stopAt: readOptionalTrimmedValue(options.values["stop-at"]),
+        cronMinute: readOptionalTrimmedValue(options.values["cron-minute"]),
+        cronHour: readOptionalTrimmedValue(options.values["cron-hour"]),
+        cronDaysOfWeek: readMultiOptionValues(options.values["cron-day-of-week"]),
+        conditionKind: readOptionalTrimmedValue(options.values["condition-kind"]),
+        repositoryUrl: readOptionalTrimmedValue(options.values["repository-url"]),
+        pollIntervalSeconds: readOptionalTrimmedValue(options.values["poll-interval-seconds"]),
+        expiresAt: readOptionalTrimmedValue(options.values["expires-at"]),
+        maxChecks: readOptionalTrimmedValue(options.values["max-checks"]),
+        conditionSessionId: readOptionalTrimmedValue(options.values["condition-session-id"]),
+        includeTriggerContext: options.flags["include-trigger-context"] === true,
+        controlSessionId: readOptionalTrimmedValue(options.values["control-session-id"]),
+        projectId: readOptionalTrimmedValue(options.values["project-id"]),
+        targetSessionId: readOptionalTrimmedValue(options.values["session-id"])
+      })));
+      return;
+    case "automations:cancel": {
+      const [automationId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/automations/${requirePositional(automationId, "automationId")}/cancel`,
+        argv: tail,
+        helpTopic: "automations.cancel"
+      }));
+      return;
+    }
+    case "automations:runs": {
+      const [automationId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/automations/${requirePositional(automationId, "automationId")}/runs`,
+        argv: tail,
+        helpTopic: "automations.runs"
+      }));
+      return;
+    }
+    case "sandboxes:list":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/sandboxes",
+        argv: rest,
+        supportedOptions: ["status"],
+        helpTopic: "sandboxes.list"
+      }, (options) => ({
+        status: readOptionalTrimmedValue(options.values.status)
+      })));
+      return;
+    case "sandboxes:create":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/sandboxes",
+        argv: rest,
+        supportedOptions: [
+          "title",
+          "description",
+          "purpose",
+          "expires-at",
+          "source-kind",
+          "repository-url",
+          "directory-name",
+          "auth-mode",
+          "username",
+          "password",
+          "auth-token"
+        ],
+        helpTopic: "sandboxes.create"
+      }, (options) => ({
+        title: readOptionalTrimmedValue(options.values.title),
+        description: readOptionalTrimmedValue(options.values.description),
+        purpose: readOptionalTrimmedValue(options.values.purpose),
+        expiresAt: readOptionalTrimmedValue(options.values["expires-at"]),
+        sourceKind: readOptionalTrimmedValue(options.values["source-kind"]),
+        repositoryUrl: readOptionalTrimmedValue(options.values["repository-url"]),
+        directoryName: readOptionalTrimmedValue(options.values["directory-name"]),
+        auth: buildWorkspaceCloneAuth(options.values)
+      })));
+      return;
+    case "sandboxes:promote": {
+      const [sandboxId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/sandboxes/${requirePositional(sandboxId, "sandboxId")}/promote`,
+        argv: tail,
+        supportedOptions: ["mode", "project-name", "provider"],
+        helpTopic: "sandboxes.promote"
+      }, (options) => ({
+        mode: readOptionalTrimmedValue(options.values.mode),
+        projectName: readOptionalTrimmedValue(options.values["project-name"]),
+        defaultProvider: readOptionalTrimmedValue(options.values.provider)
+      })));
+      return;
+    }
+    case "sandboxes:expire": {
+      const [sandboxId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/sandboxes/${requirePositional(sandboxId, "sandboxId")}/expire`,
+        argv: tail,
+        helpTopic: "sandboxes.expire"
+      }));
+      return;
+    }
+    case "sandboxes:remove": {
+      const [sandboxId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "DELETE",
+        path: `/api/assistant/sandboxes/${requirePositional(sandboxId, "sandboxId")}`,
+        argv: tail,
+        helpTopic: "sandboxes.remove"
+      }));
+      return;
+    }
+    case "timers:list":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/timers",
+        argv: rest,
+        supportedOptions: ["status", "control-session-id"],
+        helpTopic: "timers.list"
+      }, (options) => ({
+        status: readOptionalTrimmedValue(options.values.status),
+        controlSessionId: readOptionalTrimmedValue(options.values["control-session-id"])
+      })));
+      return;
+    case "timers:get": {
+      const [timerId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/timers/${requirePositional(timerId, "timerId")}`,
+        argv: tail,
+        helpTopic: "timers.get"
+      }));
+      return;
+    }
+    case "timers:create":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/timers",
+        argv: rest,
+        supportedOptions: [
+          "message",
+          "title",
+          "due-at",
+          "after-seconds",
+          "control-session-id",
+          "project-id",
+          "session-id"
+        ],
+        helpTopic: "timers.create"
+      }, (options) => ({
+        content: requireOptionValue(options.values.message, "message"),
+        title: readOptionalTrimmedValue(options.values.title),
+        dueAt: readOptionalTrimmedValue(options.values["due-at"]),
+        afterSeconds: readOptionalTrimmedValue(options.values["after-seconds"]),
+        controlSessionId: readOptionalTrimmedValue(options.values["control-session-id"]),
+        projectId: readOptionalTrimmedValue(options.values["project-id"]),
+        targetSessionId: readOptionalTrimmedValue(options.values["session-id"])
+      })));
+      return;
+    case "timers:cancel": {
+      const [timerId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/timers/${requirePositional(timerId, "timerId")}/cancel`,
+        argv: tail,
+        helpTopic: "timers.cancel"
+      }));
+      return;
+    }
     case "terminals:list":
       await printAssistantResponse(await requestAssistant({
         method: "GET",
@@ -229,7 +486,7 @@ async function runAssistantCommand(argv) {
         helpTopic: "terminals.history"
       }, (options) => ({
         beforeSeq: readOptionalTrimmedValue(options.values["before-seq"]),
-        limit: readOptionalTrimmedValue(options.values.limit)
+        limit: readAssistantTerminalHistoryLimitOption(options.values.limit)
       })));
       return;
     }
@@ -246,6 +503,303 @@ async function runAssistantCommand(argv) {
       })));
       return;
     }
+    case "terminals:close": {
+      const [terminalId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "DELETE",
+        path: `/api/assistant/terminals/${requirePositional(terminalId, "terminalId")}`,
+        argv: tail,
+        helpTopic: "terminals.close"
+      }));
+      return;
+    }
+    case "debug-targets:compatibility-matrix":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/debug-targets/compatibility-matrix",
+        argv: rest,
+        helpTopic: "debug-targets.compatibility-matrix"
+      }));
+      return;
+    case "debug-targets:analyze":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/debug-targets/analyze",
+        argv: rest,
+        supportedOptions: ["workspace-id", "root-path", "command-hint"],
+        repeatableOptions: ["command-hint"],
+        helpTopic: "debug-targets.analyze"
+      }, (options) => ({
+        workspaceId: requireOptionValue(options.values["workspace-id"], "workspace-id"),
+        rootPath: requireOptionValue(options.values["root-path"], "root-path"),
+        commandHints: readMultiOptionValues(options.values["command-hint"])
+      })));
+      return;
+    case "debug-targets:framework-analysis": {
+      const [targetId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/debug-targets/${requirePositional(targetId, "targetId")}/framework-analysis`,
+        argv: tail,
+        helpTopic: "debug-targets.framework-analysis"
+      }));
+      return;
+    }
+    case "debug-targets:refresh-framework-analysis": {
+      const [targetId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/debug-targets/${requirePositional(targetId, "targetId")}/framework-analysis/refresh`,
+        argv: tail,
+        helpTopic: "debug-targets.refresh-framework-analysis"
+      }));
+      return;
+    }
+    case "debug-targets:launch-plan": {
+      const [targetId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/debug-targets/${requirePositional(targetId, "targetId")}/launch-plan`,
+        argv: tail,
+        supportedOptions: ["port-request"],
+        repeatableOptions: ["port-request"],
+        helpTopic: "debug-targets.launch-plan"
+      }, (options) => ({
+        portRequests: parseDebugPortRequests(options.values["port-request"])
+      })));
+      return;
+    }
+    case "debug-targets:run": {
+      const [targetId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/debug-targets/${requirePositional(targetId, "targetId")}/run`,
+        argv: tail,
+        supportedOptions: ["shell", "runtime-type", "port-request"],
+        repeatableOptions: ["port-request"],
+        helpTopic: "debug-targets.run"
+      }, (options) => ({
+        shell: readOptionalTrimmedValue(options.values.shell),
+        runtimeType: readOptionalTrimmedValue(options.values["runtime-type"]),
+        portRequests: parseDebugPortRequests(options.values["port-request"])
+      })));
+      return;
+    }
+    case "debug-targets:runtime-latest": {
+      const [targetId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/debug-targets/${requirePositional(targetId, "targetId")}/runtime-latest`,
+        argv: tail,
+        helpTopic: "debug-targets.runtime-latest"
+      }));
+      return;
+    }
+    case "debug-targets:runtimes": {
+      const [targetId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/debug-targets/${requirePositional(targetId, "targetId")}/runtimes`,
+        argv: tail,
+        supportedOptions: ["limit"],
+        helpTopic: "debug-targets.runtimes"
+      }, (options) => ({
+        limit: readOptionalTrimmedValue(options.values.limit)
+      })));
+      return;
+    }
+    case "debug-runtimes:get": {
+      const [runtimeId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/debug-runtimes/${requirePositional(runtimeId, "runtimeId")}`,
+        argv: tail,
+        helpTopic: "debug-runtimes.get"
+      }));
+      return;
+    }
+    case "workspaces:list":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/workspaces",
+        argv: rest,
+        helpTopic: "workspaces.list"
+      }));
+      return;
+    case "workspaces:browse":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/workspaces/browse",
+        argv: rest,
+        supportedOptions: ["path"],
+        helpTopic: "workspaces.browse"
+      }, (options) => ({
+        path: readOptionalTrimmedValue(options.values.path)
+      })));
+      return;
+    case "workspaces:mkdir":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/workspaces/directories",
+        argv: rest,
+        supportedOptions: ["parent-path", "directory-name"],
+        helpTopic: "workspaces.mkdir"
+      }, (options) => ({
+        parentPath: requireOptionValue(options.values["parent-path"], "parent-path"),
+        directoryName: requireOptionValue(options.values["directory-name"], "directory-name")
+      })));
+      return;
+    case "workspaces:import":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/workspaces/import",
+        argv: rest,
+        supportedOptions: ["path", "name"],
+        helpTopic: "workspaces.import"
+      }, (options) => ({
+        path: requireOptionValue(options.values.path, "path"),
+        name: readOptionalTrimmedValue(options.values.name)
+      })));
+      return;
+    case "workspaces:clone":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/workspaces/clone",
+        argv: rest,
+        supportedOptions: [
+          "repository-url",
+          "parent-path",
+          "directory-name",
+          "name",
+          "auth-mode",
+          "username",
+          "password",
+          "auth-token"
+        ],
+        helpTopic: "workspaces.clone"
+      }, (options) => ({
+        repositoryUrl: requireOptionValue(options.values["repository-url"], "repository-url"),
+        parentPath: requireOptionValue(options.values["parent-path"], "parent-path"),
+        directoryName: readOptionalTrimmedValue(options.values["directory-name"]),
+        name: readOptionalTrimmedValue(options.values.name),
+        auth: buildWorkspaceCloneAuth(options.values)
+      })));
+      return;
+    case "workspaces:reorder":
+      await printAssistantResponse(await requestAssistant({
+        method: "PUT",
+        path: "/api/assistant/workspaces/reorder",
+        argv: rest,
+        supportedOptions: ["workspace-id"],
+        repeatableOptions: ["workspace-id"],
+        helpTopic: "workspaces.reorder"
+      }, (options) => ({
+        workspaceIds: requireMultiOptionValues(options.values["workspace-id"], "workspace-id")
+      })));
+      return;
+    case "workspaces:management": {
+      const [workspaceId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/workspaces/${requirePositional(workspaceId, "workspaceId")}/management`,
+        argv: tail,
+        helpTopic: "workspaces.management"
+      }));
+      return;
+    }
+    case "workspaces:nav-state": {
+      const [workspaceId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "PUT",
+        path: `/api/assistant/workspaces/${requirePositional(workspaceId, "workspaceId")}/navigation-state`,
+        argv: tail,
+        supportedOptions: ["collapsed", "background-color"],
+        helpTopic: "workspaces.nav-state"
+      }, (options) => {
+        const payload = {};
+        const collapsed = readOptionalTrimmedValue(options.values.collapsed);
+        const backgroundColor = readOptionalTrimmedValue(options.values["background-color"]);
+
+        if (collapsed !== null) {
+          payload.collapsed = parseBooleanOption(collapsed, "collapsed");
+        }
+
+        if (backgroundColor !== null) {
+          payload.backgroundColor = normalizeBackgroundColorOption(backgroundColor);
+        }
+
+        return payload;
+      }));
+      return;
+    }
+    case "workspaces:remove": {
+      const [workspaceId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "DELETE",
+        path: `/api/assistant/workspaces/${requirePositional(workspaceId, "workspaceId")}`,
+        argv: tail,
+        helpTopic: "workspaces.remove"
+      }));
+      return;
+    }
+    case "worktrees:tree":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/worktrees/tree",
+        argv: rest,
+        supportedOptions: ["root-workspace-id"],
+        helpTopic: "worktrees.tree"
+      }, (options) => ({
+        rootWorkspaceId: requireOptionValue(options.values["root-workspace-id"], "root-workspace-id")
+      })));
+      return;
+    case "worktrees:create":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/worktrees",
+        argv: rest,
+        supportedOptions: ["source-workspace-id", "branch-name", "display-name", "base-ref"],
+        helpTopic: "worktrees.create"
+      }, (options) => ({
+        sourceWorkspaceId: requireOptionValue(options.values["source-workspace-id"], "source-workspace-id"),
+        branchName: requireOptionValue(options.values["branch-name"], "branch-name"),
+        displayName: readOptionalTrimmedValue(options.values["display-name"]),
+        baseRef: readOptionalTrimmedValue(options.values["base-ref"])
+      })));
+      return;
+    case "worktrees:merge-preview": {
+      const [workspaceId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/worktrees/${requirePositional(workspaceId, "workspaceId")}/merge-preview`,
+        argv: tail,
+        helpTopic: "worktrees.merge-preview"
+      }));
+      return;
+    }
+    case "worktrees:merge": {
+      const [workspaceId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/worktrees/${requirePositional(workspaceId, "workspaceId")}/merge-into-parent`,
+        argv: tail,
+        helpTopic: "worktrees.merge"
+      }));
+      return;
+    }
+    case "worktrees:cleanup": {
+      const [workspaceId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/worktrees/${requirePositional(workspaceId, "workspaceId")}/cleanup`,
+        argv: tail,
+        supportedFlags: ["delete-branch"],
+        helpTopic: "worktrees.cleanup"
+      }, (options) => ({
+        deleteBranch: options.flags["delete-branch"] === true
+      })));
+      return;
+    }
     default:
       console.error(`[codingns] 不支持的 assistant 子命令：${group}${action ? ` ${action}` : ""}`);
       printAssistantHelpTopic("assistant", 1);
@@ -336,7 +890,9 @@ async function requestAssistant(command, buildPayload) {
       "base-url",
       "token",
       ...(command.supportedOptions ?? [])
-    ]
+    ],
+    repeatableOptions: command.repeatableOptions ?? [],
+    supportedFlags: command.supportedFlags ?? []
   });
 
   if (options.help) {
@@ -366,13 +922,14 @@ async function requestAssistant(command, buildPayload) {
   let response;
 
   try {
+    const usesJsonBody = command.method === "POST" || command.method === "PUT";
     response = await fetch(url, {
       method: command.method,
       headers: {
         Authorization: `Bearer ${accessToken}`,
-        ...(command.method === "POST" ? { "Content-Type": "application/json" } : {})
+        ...(usesJsonBody ? { "Content-Type": "application/json" } : {})
       },
-      body: command.method === "POST" ? JSON.stringify(payload ?? {}) : undefined
+      body: usesJsonBody ? JSON.stringify(payload ?? {}) : undefined
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : "未知网络错误";
@@ -571,10 +1128,14 @@ function parseArgs(argv, input = {}) {
 }
 
 function resolveAssistantBaseUrl(input) {
-  const baseUrl = readStringOption(
+  const configuredBaseUrl = readStringOption(
     input,
     process.env.CODINGNS_BASE_URL,
-    process.env.CODINGNS_SERVER_BASE_URL,
+    process.env.CODINGNS_SERVER_BASE_URL
+  );
+  const baseUrl = readStringOption(
+    configuredBaseUrl,
+    configuredBaseUrl ? "" : readAssistantCredentialField("apiBaseUrl"),
     "http://127.0.0.1:3002"
   );
 
@@ -586,19 +1147,109 @@ function resolveAssistantBaseUrl(input) {
 }
 
 function resolveAssistantAccessToken(input) {
-  const accessToken = readStringOption(
+  const configuredAccessToken = readStringOption(
     input,
     process.env.CODINGNS_ACCESS_TOKEN,
     process.env.CODINGNS_TOKEN
   );
-
+  const accessToken = readStringOption(
+    configuredAccessToken,
+    configuredAccessToken ? "" : readAssistantCredentialField("accessToken")
+  );
+
   if (!accessToken) {
-    fail("缺少助手调用 access token，请传 --token 或设置 CODINGNS_ACCESS_TOKEN");
+    fail(
+      "缺少助手调用 access token，请传 --token、设置 CODINGNS_ACCESS_TOKEN，或在当前目录/上级目录提供 BUTLER_AUTH.json（也可用 CODINGNS_AUTH_FILE 指定）"
+    );
   }
 
   return accessToken;
 }
 
+var cachedAssistantCredential;
+
+function readAssistantCredentialField(field) {
+  const credential = readAssistantCredential();
+
+  if (!credential) {
+    return "";
+  }
+
+  const value = credential[field];
+  return typeof value === "string" ? value : "";
+}
+
+function readAssistantCredential() {
+  if (cachedAssistantCredential !== undefined) {
+    return cachedAssistantCredential;
+  }
+
+  const credentialFilePath = resolveAssistantCredentialFilePath();
+
+  if (!credentialFilePath) {
+    cachedAssistantCredential = null;
+    return cachedAssistantCredential;
+  }
+
+  let rawContent;
+
+  try {
+    rawContent = fs.readFileSync(credentialFilePath, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "未知错误";
+    fail(`读取助手认证文件失败：${credentialFilePath}（${message}）`);
+  }
+
+  let parsed;
+
+  try {
+    parsed = JSON.parse(rawContent);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "未知错误";
+    fail(`助手认证文件不是合法 JSON：${credentialFilePath}（${message}）`);
+  }
+
+  cachedAssistantCredential = {
+    filePath: credentialFilePath,
+    accessToken: typeof parsed?.accessToken === "string" ? parsed.accessToken.trim() : "",
+    apiBaseUrl: typeof parsed?.apiBaseUrl === "string" ? parsed.apiBaseUrl.trim() : ""
+  };
+  return cachedAssistantCredential;
+}
+
+function resolveAssistantCredentialFilePath() {
+  const configuredPath = readStringOption(
+    process.env.CODINGNS_AUTH_FILE,
+    process.env.BUTLER_AUTH_FILE
+  );
+
+  if (configuredPath) {
+    return path.resolve(configuredPath);
+  }
+
+  return findFileUpward(process.cwd(), "BUTLER_AUTH.json");
+}
+
+function findFileUpward(startPath, fileName) {
+  let currentPath = path.resolve(startPath);
+
+  while (true) {
+    const candidatePath = path.join(currentPath, fileName);
+
+    if (fs.existsSync(candidatePath) && fs.statSync(candidatePath).isFile()) {
+      return candidatePath;
+    }
+
+    const parentPath = path.dirname(currentPath);
+
+    if (parentPath === currentPath) {
+      return null;
+    }
+
+    currentPath = parentPath;
+  }
+}
+
 function readStringOption(...values) {
   for (const value of values) {
     if (typeof value === "string" && value.trim().length > 0) {
@@ -614,6 +1265,27 @@ function readOptionalTrimmedValue(value) {
   return normalized.length > 0 ? normalized : null;
 }
 
+function readAssistantTerminalHistoryLimitOption(value) {
+  const normalized = readOptionalTrimmedValue(value);
+
+  if (!normalized) {
+    return null;
+  }
+
+  const parsed = Number.parseInt(normalized, 10);
+
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return normalized;
+  }
+
+  if (parsed <= 100) {
+    return normalized;
+  }
+
+  console.warn("[codingns] assistant terminals history 的 --limit 最大为 100，已自动收敛到 100。");
+  return "100";
+}
+
 function readMultiOptionValues(value) {
   const values = Array.isArray(value)
     ? value
@@ -753,8 +1425,13 @@ assistant 例子：
 
   codingns assistant capabilities list --token <token>
   codingns assistant projects list --status active --token <token>
+  codingns assistant workspaces list --token <token>
+  codingns assistant debug-targets analyze --workspace-id <id> --root-path <path> --token <token>
+  codingns assistant debug-targets launch-plan <targetId> --port-request role=backend,cwd=apps/api,port=44001 --token <token>
+  codingns assistant worktrees tree --root-workspace-id <id> --token <token>
   codingns assistant sessions send <sessionId> --message "继续修复类型错误" --token <token>
   codingns assistant terminals send <terminalId> --input "npm test\\n" --token <token>
+  codingns assistant terminals close <terminalId> --token <token>
 
 skills 例子：
 
@@ -840,6 +1517,115 @@ codingns assistant projects get
 
 用法：
   codingns assistant projects get <projectId> --token <token>
+`.trim();
+    case "workspaces":
+      return `
+codingns assistant workspaces
+
+可用动作：
+  list        列出当前工作区
+  browse      浏览可导入目录
+  mkdir       创建目录
+  import      导入工作区
+  clone       克隆并导入工作区
+  reorder     调整工作区顺序
+  management  读取工作区管理摘要
+  nav-state   更新导航状态
+  remove      移除工作区
+
+示例：
+  codingns assistant workspaces list --token <token>
+  codingns assistant workspaces import --path /repo/demo --token <token>
+`.trim();
+    case "workspaces.list":
+      return `
+codingns assistant workspaces list
+
+用途：
+  列出当前可见工作区。
+
+用法：
+  codingns assistant workspaces list --token <token>
+`.trim();
+    case "workspaces.browse":
+      return `
+codingns assistant workspaces browse
+
+用途：
+  浏览本地目录，给导入或 clone 选目标位置。
+
+用法：
+  codingns assistant workspaces browse [--path <path>] --token <token>
+`.trim();
+    case "workspaces.mkdir":
+      return `
+codingns assistant workspaces mkdir
+
+用途：
+  在指定父目录下创建新目录。
+
+用法：
+  codingns assistant workspaces mkdir --parent-path <path> --directory-name <name> --token <token>
+`.trim();
+    case "workspaces.import":
+      return `
+codingns assistant workspaces import
+
+用途：
+  把已有目录导入成工作区。
+
+用法：
+  codingns assistant workspaces import --path <path> [--name <name>] --token <token>
+`.trim();
+    case "workspaces.clone":
+      return `
+codingns assistant workspaces clone
+
+用途：
+  克隆 Git 仓库并导入成工作区。
+
+用法：
+  codingns assistant workspaces clone --repository-url <url> --parent-path <path> [--directory-name <name>] [--name <name>] [--auth-mode none|basic|token] [--username <name>] [--password <password>] [--auth-token <token>] --token <token>
+`.trim();
+    case "workspaces.reorder":
+      return `
+codingns assistant workspaces reorder
+
+用途：
+  调整工作区显示顺序，必须提交当前全部可见工作区。
+
+用法：
+  codingns assistant workspaces reorder --workspace-id <id> [--workspace-id <id>] --token <token>
+`.trim();
+    case "workspaces.management":
+      return `
+codingns assistant workspaces management
+
+用途：
+  读取工作区 Git 和代码构成摘要。
+
+用法：
+  codingns assistant workspaces management <workspaceId> --token <token>
+`.trim();
+    case "workspaces.nav-state":
+      return `
+codingns assistant workspaces nav-state
+
+用途：
+  更新工作区导航状态，比如折叠状态和背景色。
+
+用法：
+  codingns assistant workspaces nav-state <workspaceId> [--collapsed true|false] [--background-color #RRGGBB|none] --token <token>
+`.trim();
+    case "workspaces.remove":
+      return `
+codingns assistant workspaces remove
+
+用途：
+  移除工作区入口，不直接删除磁盘目录。
+
+用法：
+  codingns assistant workspaces remove <workspaceId> --token <token>
 `.trim();
     case "sessions":
       return `
@@ -847,6 +1633,7 @@ codingns assistant sessions
 
 可用动作：
   list      列出指定项目下的会话
+  start     按 project/workspace/sandbox 目标新建真实会话
   get       读取会话详情
   messages  读取消息窗口
   runtime   读取运行态
@@ -855,6 +1642,7 @@ codingns assistant sessions
 
 示例：
   codingns assistant sessions list --project <projectId> --token <token>
+  codingns assistant sessions start --project <projectId> --message "继续处理这个问题" --token <token>
   codingns assistant sessions send <sessionId> --message "继续修复" --token <token>
 `.trim();
     case "sessions.list":
@@ -866,6 +1654,16 @@ codingns assistant sessions list
 
 用法：
   codingns assistant sessions list --project <projectId> --token <token>
+`.trim();
+    case "sessions.start":
+      return `
+codingns assistant sessions start
+
+用途：
+  在指定 project/workspace/sandbox 目标下新建真实会话；如果不显式传 provider/model，会默认继承当前助手控制会话的配置。
+
+用法：
+  codingns assistant sessions start (--project <projectId> | --workspace <workspaceId> | --sandbox <sandboxId>) --message "..." [--provider <provider>] [--model <model>] [--reasoning-level <level>] [--permission-mode <mode>] --token <token>
 `.trim();
     case "sessions.get":
       return `
@@ -916,6 +1714,193 @@ codingns assistant sessions fork
 
 用法：
   codingns assistant sessions fork <sessionId> [--source-type session|message] [--message-id <id>] [--strategy auto|native-only|reconstruct-only] [--target-provider <provider>] --token <token>
+`.trim();
+    case "sandboxes":
+      return `
+codingns assistant sandboxes
+
+可用动作：
+  list     列出当前助手沙箱
+  create   创建新的临时沙箱工作区
+  promote  把沙箱保留为 pinned，或晋升成正式项目
+  expire   标记沙箱过期
+  remove   清理沙箱
+
+示例：
+  codingns assistant sandboxes list --status active --token <token>
+  codingns assistant sandboxes create --title "CodingNS 临时沙箱" --source-kind clone --repository-url <url> --token <token>
+`.trim();
+    case "sandboxes.list":
+      return `
+codingns assistant sandboxes list
+
+用途：
+  列出当前用户可见的助手沙箱。
+
+用法：
+  codingns assistant sandboxes list [--status active|archived|expired|deleted] --token <token>
+`.trim();
+    case "sandboxes.create":
+      return `
+codingns assistant sandboxes create
+
+用途：
+  创建新的临时沙箱工作区；默认空白沙箱，也可以直接 clone 仓库。
+
+用法：
+  codingns assistant sandboxes create [--title <title>] [--description <text>] [--purpose <text>] [--expires-at <isoTime>] [--source-kind blank|clone] [--repository-url <url>] [--directory-name <name>] [--auth-mode none|basic|token] [--username <name>] [--password <password>] [--auth-token <token>] --token <token>
+`.trim();
+    case "sandboxes.promote":
+      return `
+codingns assistant sandboxes promote
+
+用途：
+  把沙箱保留为 pinned，或者直接晋升成正式项目。
+
+用法：
+  codingns assistant sandboxes promote <sandboxId> [--mode pin|project] [--project-name <name>] [--provider <provider>] --token <token>
+`.trim();
+    case "sandboxes.expire":
+      return `
+codingns assistant sandboxes expire
+
+用途：
+  把指定沙箱标记为过期，后续不能再拿它启动会话。
+
+用法：
+  codingns assistant sandboxes expire <sandboxId> --token <token>
+`.trim();
+    case "sandboxes.remove":
+      return `
+codingns assistant sandboxes remove
+
+用途：
+  删除指定沙箱并尝试清理对应工作区入口。
+
+用法：
+  codingns assistant sandboxes remove <sandboxId> --token <token>
+`.trim();
+    case "automations":
+      return `
+  codingns assistant automations
+
+可用动作：
+  list    列出正式自动化任务
+  get     读取单个自动化详情
+  create  创建正式自动化任务
+  cancel  取消自动化任务
+  runs    查看自动化执行记录
+
+示例：
+  codingns assistant automations create --after-seconds 3600 --message "1 小时后检查 codingns 新 tag" --session-id <sessionId> --project-id <projectId> --token <token>
+  codingns assistant automations create --trigger interval --every-hours 1 --message "每小时检查一次" --token <token>
+  codingns assistant automations create --trigger cron --cron-minute 30 --cron-hour 9 --cron-day-of-week 1 --cron-day-of-week 2 --message "工作日早上检查" --token <token>
+  codingns assistant automations create --trigger condition --condition-kind git.remote_tag_changed --repository-url <url> --poll-interval-seconds 3600 --message "发现新 tag 后通知我" --include-trigger-context --token <token>
+  codingns assistant automations list --status active --token <token>
+`.trim();
+    case "automations.list":
+      return `
+codingns assistant automations list
+
+用途：
+  查看当前助手控制会话下的正式自动化任务。
+
+用法：
+  codingns assistant automations list [--status active|completed|cancelled|failed] [--control-session-id <id>] --token <token>
+`.trim();
+    case "automations.get":
+      return `
+codingns assistant automations get
+
+用途：
+  读取单个自动化任务详情。
+
+用法：
+  codingns assistant automations get <automationId> --token <token>
+`.trim();
+    case "automations.create":
+      return `
+codingns assistant automations create
+
+用途：
+  创建正式自动化；支持 once / interval / cron / condition 四种触发器。
+
+用法：
+  codingns assistant automations create --message "..." [--trigger once|interval|cron|condition] [--title <title>] [--due-at <isoTime> | --after-seconds <seconds>] [--every-seconds <n> | --every-minutes <n> | --every-hours <n>] [--stop-at <isoTime>] [--cron-minute <0-59>] [--cron-hour <0-23>] [--cron-day-of-week <0-6>] [--condition-kind git.remote_tag_changed|session.runtime_idle] [--repository-url <url>] [--condition-session-id <sessionId>] [--poll-interval-seconds <n>] [--expires-at <isoTime>] [--max-checks <n>] [--include-trigger-context] [--control-session-id <id>] [--project-id <projectId>] [--session-id <sessionId>] --token <token>
+`.trim();
+    case "automations.cancel":
+      return `
+codingns assistant automations cancel
+
+用途：
+  取消一个尚未执行的自动化任务。
+
+用法：
+  codingns assistant automations cancel <automationId> --token <token>
+`.trim();
+    case "automations.runs":
+      return `
+codingns assistant automations runs
+
+用途：
+  查看某个自动化任务的执行记录。
+
+用法：
+  codingns assistant automations runs <automationId> --token <token>
+`.trim();
+    case "timers":
+      return `
+codingns assistant timers
+
+可用动作：
+  list    列出当前助手会话相关的计时器
+  get     读取单个计时器详情
+  create  创建到点后继续助手会话的计时器
+  cancel  取消计时器
+
+示例：
+  codingns assistant timers create --after-seconds 300 --message "5 分钟后检查真实会话最新回复" --session-id <sessionId> --project-id <projectId> --token <token>
+  codingns assistant timers list --status active --token <token>
+`.trim();
+    case "timers.list":
+      return `
+codingns assistant timers list
+
+用途：
+  查看当前助手会话下仍在等待、已完成或已失败的计时器。
+
+用法：
+  codingns assistant timers list [--status active|completed|cancelled|failed] [--control-session-id <id>] --token <token>
+`.trim();
+    case "timers.get":
+      return `
+codingns assistant timers get
+
+用途：
+  读取单个计时器详情，包括计划触发时间和最后错误。
+
+用法：
+  codingns assistant timers get <timerId> --token <token>
+`.trim();
+    case "timers.create":
+      return `
+codingns assistant timers create
+
+用途：
+  创建一个一次性计时器；到期后系统会自动向同一个助手控制会话发送消息，继续工作。
+
+用法：
+  codingns assistant timers create --message "..." [--title <title>] [--due-at <isoTime> | --after-seconds <seconds>] [--control-session-id <id>] [--project-id <projectId>] [--session-id <sessionId>] --token <token>
+`.trim();
+    case "timers.cancel":
+      return `
+codingns assistant timers cancel
+
+用途：
+  取消一个尚未触发的计时器。
+
+用法：
+  codingns assistant timers cancel <timerId> --token <token>
 `.trim();
     case "terminals":
       return `
@@ -925,6 +1910,7 @@ codingns assistant terminals
   list     列出项目或工作区下的终端
   history  读取终端历史输出
   send     向受控终端发送输入
+  close    关闭受控终端
 
 示例：
   codingns assistant terminals list --project-id <projectId> --token <token>
@@ -959,29 +1945,262 @@ codingns assistant terminals send
 
 用法：
   codingns assistant terminals send <terminalId> --input "npm test\\n" --token <token>
+`.trim();
+    case "terminals.close":
+      return `
+codingns assistant terminals close
+
+用途：
+  关闭指定受控终端，常用于停止调试进程或回收运行资源。
+
+用法：
+  codingns assistant terminals close <terminalId> --token <token>
+`.trim();
+    case "debug-targets":
+      return `
+codingns assistant debug-targets
+
+可用动作：
+  compatibility-matrix       读取框架兼容矩阵
+  analyze                    分析工作区调试目标
+  framework-analysis         读取框架分析结果
+  refresh-framework-analysis 刷新框架分析结果
+  launch-plan                生成启动计划，可显式请求端口
+  run                        启动调试目标，可显式请求端口
+  runtime-latest             读取最近一次运行态
+  runtimes                   读取运行历史
+
+示例：
+  codingns assistant debug-targets analyze --workspace-id <id> --root-path /repo/demo --token <token>
+  codingns assistant debug-targets launch-plan <targetId> --port-request role=backend,cwd=apps/api,port=44001 --token <token>
+`.trim();
+    case "debug-targets.compatibility-matrix":
+      return `
+codingns assistant debug-targets compatibility-matrix
+
+用途：
+  读取平台当前支持的框架兼容矩阵和建议注入方式。
+
+用法：
+  codingns assistant debug-targets compatibility-matrix --token <token>
+`.trim();
+    case "debug-targets.analyze":
+      return `
+codingns assistant debug-targets analyze
+
+用途：
+  分析指定工作区下的调试目标、服务和框架兼容性。
+
+用法：
+  codingns assistant debug-targets analyze --workspace-id <id> --root-path <path> [--command-hint "pnpm dev"] [--command-hint "node server.js"] --token <token>
+`.trim();
+    case "debug-targets.framework-analysis":
+      return `
+codingns assistant debug-targets framework-analysis
+
+用途：
+  读取指定调试目标当前的框架分析结果。
+
+用法：
+  codingns assistant debug-targets framework-analysis <targetId> --token <token>
+`.trim();
+    case "debug-targets.refresh-framework-analysis":
+      return `
+codingns assistant debug-targets refresh-framework-analysis
+
+用途：
+  刷新指定调试目标的框架分析结果。
+
+用法：
+  codingns assistant debug-targets refresh-framework-analysis <targetId> --token <token>
+`.trim();
+    case "debug-targets.launch-plan":
+      return `
+codingns assistant debug-targets launch-plan
+
+用途：
+  生成调试目标启动计划，可通过重复的 --port-request 显式请求服务端口。
+
+用法：
+  codingns assistant debug-targets launch-plan <targetId> [--port-request role=frontend,cwd=apps/web,port=43001] [--port-request role=backend,cwd=apps/api,port=44001] --token <token>
+`.trim();
+    case "debug-targets.run":
+      return `
+codingns assistant debug-targets run
+
+用途：
+  启动调试目标，可选指定 shell、runtimeType 和显式端口请求。
+
+用法：
+  codingns assistant debug-targets run <targetId> [--shell zsh] [--runtime-type tmux|embedded-pty|conpty-powershell|conpty-cmd|conpty-git-bash] [--port-request role=backend,cwd=apps/api,port=44001] --token <token>
+`.trim();
+    case "debug-targets.runtime-latest":
+      return `
+codingns assistant debug-targets runtime-latest
+
+用途：
+  读取指定调试目标最近一次运行态，没有运行记录时返回 null。
+
+用法：
+  codingns assistant debug-targets runtime-latest <targetId> --token <token>
+`.trim();
+    case "debug-targets.runtimes":
+      return `
+codingns assistant debug-targets runtimes
+
+用途：
+  读取指定调试目标最近几次运行历史。
+
+用法：
+  codingns assistant debug-targets runtimes <targetId> [--limit 5] --token <token>
+`.trim();
+    case "debug-runtimes":
+      return `
+codingns assistant debug-runtimes
+
+可用动作：
+  get  读取单个调试运行时详情
+
+示例：
+  codingns assistant debug-runtimes get <runtimeId> --token <token>
+`.trim();
+    case "debug-runtimes.get":
+      return `
+codingns assistant debug-runtimes get
+
+用途：
+  读取指定调试运行时详情，包括服务、绑定、租约和终端实例。
+
+用法：
+  codingns assistant debug-runtimes get <runtimeId> --token <token>
+`.trim();
+    case "worktrees":
+      return `
+codingns assistant worktrees
+
+可用动作：
+  tree           读取工作树结构
+  create         创建子工作树
+  merge-preview  读取合并预览
+  merge          合并回父工作区
+  cleanup        清理子工作树
+
+示例：
+  codingns assistant worktrees tree --root-workspace-id <id> --token <token>
+  codingns assistant worktrees create --source-workspace-id <id> --branch-name feature/demo --token <token>
+`.trim();
+    case "worktrees.tree":
+      return `
+codingns assistant worktrees tree
+
+用途：
+  读取某个根工作区下面的工作树结构。
+
+用法：
+  codingns assistant worktrees tree --root-workspace-id <id> --token <token>
+`.trim();
+    case "worktrees.create":
+      return `
+codingns assistant worktrees create
+
+用途：
+  从指定工作区创建新的子工作树。
+
+用法：
+  codingns assistant worktrees create --source-workspace-id <id> --branch-name <name> [--display-name <name>] [--base-ref <ref>] --token <token>
+`.trim();
+    case "worktrees.merge-preview":
+      return `
+codingns assistant worktrees merge-preview
+
+用途：
+  查看子工作树合并回父工作区前的阻塞项和预览。
+
+用法：
+  codingns assistant worktrees merge-preview <workspaceId> --token <token>
+`.trim();
+    case "worktrees.merge":
+      return `
+codingns assistant worktrees merge
+
+用途：
+  把子工作树合并回父工作区。
+
+用法：
+  codingns assistant worktrees merge <workspaceId> --token <token>
+`.trim();
+    case "worktrees.cleanup":
+      return `
+codingns assistant worktrees cleanup
+
+用途：
+  清理已经完成的子工作树，可选同时删除分支。
+
+用法：
+  codingns assistant worktrees cleanup <workspaceId> [--delete-branch] --token <token>
 `.trim();
     default:
       return `
 codingns assistant 用法：
 
-  codingns assistant help [capabilities|projects|sessions|terminals] [action]
+  codingns assistant help [capabilities|projects|sessions|sandboxes|automations|timers|terminals|debug-targets|debug-runtimes|workspaces|worktrees] [action]
   codingns assistant capabilities list [--base-url http://127.0.0.1:3002] --token <token>
   codingns assistant projects list [--workspace-id <id>] [--status active|paused|archived] [--risk-level low|medium|high] --token <token>
   codingns assistant projects get <projectId> [--base-url ...] --token <token>
+  codingns assistant debug-targets compatibility-matrix [--base-url ...] --token <token>
+  codingns assistant debug-targets analyze --workspace-id <id> --root-path <path> [--command-hint <command>] [--command-hint <command>] [--base-url ...] --token <token>
+  codingns assistant debug-targets framework-analysis <targetId> [--base-url ...] --token <token>
+  codingns assistant debug-targets refresh-framework-analysis <targetId> [--base-url ...] --token <token>
+  codingns assistant debug-targets launch-plan <targetId> [--port-request role=backend,cwd=apps/api,port=44001] [--base-url ...] --token <token>
+  codingns assistant debug-targets run <targetId> [--shell zsh] [--runtime-type tmux|embedded-pty|conpty-powershell|conpty-cmd|conpty-git-bash] [--port-request role=backend,cwd=apps/api,port=44001] [--base-url ...] --token <token>
+  codingns assistant debug-targets runtime-latest <targetId> [--base-url ...] --token <token>
+  codingns assistant debug-targets runtimes <targetId> [--limit 5] [--base-url ...] --token <token>
+  codingns assistant debug-runtimes get <runtimeId> [--base-url ...] --token <token>
+  codingns assistant workspaces list [--base-url ...] --token <token>
+  codingns assistant workspaces browse [--path <path>] [--base-url ...] --token <token>
+  codingns assistant workspaces mkdir --parent-path <path> --directory-name <name> [--base-url ...] --token <token>
+  codingns assistant workspaces import --path <path> [--name <name>] [--base-url ...] --token <token>
+  codingns assistant workspaces clone --repository-url <url> --parent-path <path> [--directory-name <name>] [--name <name>] [--auth-mode none|basic|token] [--username <name>] [--password <password>] [--auth-token <token>] [--base-url ...] --token <token>
+  codingns assistant workspaces reorder --workspace-id <id> [--workspace-id <id>] [--base-url ...] --token <token>
+  codingns assistant workspaces management <workspaceId> [--base-url ...] --token <token>
+  codingns assistant workspaces nav-state <workspaceId> [--collapsed true|false] [--background-color #RRGGBB|none] [--base-url ...] --token <token>
+  codingns assistant workspaces remove <workspaceId> [--base-url ...] --token <token>
   codingns assistant sessions list --project <projectId> [--base-url ...] --token <token>
+  codingns assistant sessions start (--project <projectId> | --workspace <workspaceId> | --sandbox <sandboxId>) --message "..." [--provider <provider>] [--model <model>] [--reasoning-level <level>] [--permission-mode <mode>] --token <token>
   codingns assistant sessions get <sessionId> [--base-url ...] --token <token>
   codingns assistant sessions messages <sessionId> [--cursor <cursor>] [--limit 40] [--direction forward|backward] --token <token>
   codingns assistant sessions runtime <sessionId> [--base-url ...] --token <token>
   codingns assistant sessions send <sessionId> --message "..." [--client-request-id <id>] [--model <model>] [--reasoning-level <level>] [--permission-mode <mode>] --token <token>
   codingns assistant sessions fork <sessionId> [--source-type session|message] [--message-id <id>] [--strategy auto|native-only|reconstruct-only] [--target-provider <provider>] --token <token>
+  codingns assistant sandboxes list [--status active|archived|expired|deleted] [--base-url ...] --token <token>
+  codingns assistant sandboxes create [--title <title>] [--description <text>] [--purpose <text>] [--expires-at <isoTime>] [--source-kind blank|clone] [--repository-url <url>] [--directory-name <name>] [--auth-mode none|basic|token] [--username <name>] [--password <password>] [--auth-token <token>] [--base-url ...] --token <token>
+  codingns assistant sandboxes promote <sandboxId> [--mode pin|project] [--project-name <name>] [--provider <provider>] [--base-url ...] --token <token>
+  codingns assistant sandboxes expire <sandboxId> [--base-url ...] --token <token>
+  codingns assistant sandboxes remove <sandboxId> [--base-url ...] --token <token>
+  codingns assistant automations list [--status active|completed|cancelled|failed] [--control-session-id <id>] --token <token>
+  codingns assistant automations get <automationId> [--base-url ...] --token <token>
+  codingns assistant automations create --message "..." [--trigger once|interval|cron|condition] [--title <title>] [--due-at <isoTime> | --after-seconds <seconds>] [--every-seconds <n> | --every-minutes <n> | --every-hours <n>] [--stop-at <isoTime>] [--cron-minute <0-59>] [--cron-hour <0-23>] [--cron-day-of-week <0-6>] [--condition-kind git.remote_tag_changed|session.runtime_idle] [--repository-url <url>] [--condition-session-id <sessionId>] [--poll-interval-seconds <n>] [--expires-at <isoTime>] [--max-checks <n>] [--include-trigger-context] [--control-session-id <id>] [--project-id <projectId>] [--session-id <sessionId>] --token <token>
+  codingns assistant automations cancel <automationId> [--base-url ...] --token <token>
+  codingns assistant automations runs <automationId> [--base-url ...] --token <token>
+  codingns assistant timers list [--status active|completed|cancelled|failed] [--control-session-id <id>] --token <token>
+  codingns assistant timers get <timerId> [--base-url ...] --token <token>
+  codingns assistant timers create --message "..." [--title <title>] [--due-at <isoTime> | --after-seconds <seconds>] [--control-session-id <id>] [--project-id <projectId>] [--session-id <sessionId>] --token <token>
+  codingns assistant timers cancel <timerId> [--base-url ...] --token <token>
   codingns assistant terminals list [--workspace-id <id> | --project-id <id>] --token <token>
   codingns assistant terminals history <terminalId> [--before-seq <n>] [--limit 20] --token <token>
   codingns assistant terminals send <terminalId> --input "npm test\\n" --token <token>
+  codingns assistant terminals close <terminalId> [--base-url ...] --token <token>
+  codingns assistant worktrees tree --root-workspace-id <id> [--base-url ...] --token <token>
+  codingns assistant worktrees create --source-workspace-id <id> --branch-name <name> [--display-name <name>] [--base-ref <ref>] [--base-url ...] --token <token>
+  codingns assistant worktrees merge-preview <workspaceId> [--base-url ...] --token <token>
+  codingns assistant worktrees merge <workspaceId> [--base-url ...] --token <token>
+  codingns assistant worktrees cleanup <workspaceId> [--delete-branch] [--base-url ...] --token <token>
 
 环境变量：
 
   CODINGNS_BASE_URL      默认 Host 地址，未传时默认 http://127.0.0.1:3002
   CODINGNS_ACCESS_TOKEN  默认 Bearer token
+  CODINGNS_AUTH_FILE     可选认证文件，支持读取 apiBaseUrl/accessToken
 `.trim();
   }
 }
@@ -1041,6 +2260,7 @@ codingns skills 用法：
 
   CODINGNS_BASE_URL      默认 Host 地址，未传时默认 http://127.0.0.1:3002
   CODINGNS_ACCESS_TOKEN  默认 Bearer token
+  CODINGNS_AUTH_FILE     可选认证文件，支持读取 apiBaseUrl/accessToken
 `.trim();
   }
 }
@@ -1057,6 +2277,145 @@ function buildAssistantHelpTopic(action, rest) {
   return `${action}.${rest[0]}`;
 }
 
+function resolveAssistantSessionStartTarget(values) {
+  const projectId = readOptionalTrimmedValue(values.project);
+  const workspaceId = readOptionalTrimmedValue(values.workspace);
+  const sandboxId = readOptionalTrimmedValue(values.sandbox);
+  const targets = [
+    projectId ? { projectId } : null,
+    workspaceId ? { workspaceId } : null,
+    sandboxId ? { sandboxId } : null
+  ].filter((item) => item !== null);
+
+  if (targets.length !== 1) {
+    fail("sessions start 必须且只能提供 --project、--workspace、--sandbox 其中一个");
+  }
+
+  return targets[0];
+}
+
+function buildWorkspaceCloneAuth(values) {
+  const authMode = readOptionalTrimmedValue(values["auth-mode"]);
+
+  if (!authMode || authMode === "none") {
+    return authMode === "none" ? { mode: "none" } : undefined;
+  }
+
+  if (authMode === "basic") {
+    return {
+      mode: "basic",
+      username: readOptionalTrimmedValue(values.username),
+      password: readOptionalTrimmedValue(values.password)
+    };
+  }
+
+  if (authMode === "token") {
+    return {
+      mode: "token",
+      username: readOptionalTrimmedValue(values.username),
+      token: readOptionalTrimmedValue(values["auth-token"])
+    };
+  }
+
+  fail(`不支持的 --auth-mode：${authMode}`);
+}
+
+function parseDebugPortRequests(value) {
+  const values = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? [value]
+      : [];
+
+  return values
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0)
+    .map((item) => parseDebugPortRequest(item));
+}
+
+function parseDebugPortRequest(value) {
+  const segments = value
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+  const request = {
+    serviceId: null,
+    role: null,
+    cwd: null,
+    name: null,
+    command: null,
+    port: null
+  };
+
+  for (const segment of segments) {
+    const [rawKey, ...rest] = segment.split("=");
+    const key = rawKey?.trim().toLowerCase() ?? "";
+    const parsedValue = rest.join("=").trim();
+
+    if (!key || !parsedValue) {
+      fail(`无效的 --port-request：${value}`);
+    }
+
+    switch (key) {
+      case "service-id":
+        request.serviceId = parsedValue;
+        break;
+      case "role":
+        request.role = parsedValue;
+        break;
+      case "cwd":
+        request.cwd = parsedValue;
+        break;
+      case "name":
+        request.name = parsedValue;
+        break;
+      case "command":
+        request.command = parsedValue;
+        break;
+      case "port": {
+        const port = Number.parseInt(parsedValue, 10);
+
+        if (!Number.isInteger(port)) {
+          fail(`--port-request 中的 port 非法：${parsedValue}`);
+        }
+
+        request.port = port;
+        break;
+      }
+      default:
+        fail(`--port-request 不支持的键：${rawKey}`);
+    }
+  }
+
+  if (!Number.isInteger(request.port)) {
+    fail(`--port-request 缺少 port：${value}`);
+  }
+
+  if (!request.serviceId && !request.role && !request.cwd && !request.name && !request.command) {
+    fail(`--port-request 至少要提供 service-id、role、cwd、name、command 之一：${value}`);
+  }
+
+  return request;
+}
+
+function parseBooleanOption(value, field) {
+  const normalized = value.toLowerCase();
+
+  if (normalized === "true") {
+    return true;
+  }
+
+  if (normalized === "false") {
+    return false;
+  }
+
+  fail(`参数 --${field} 只接受 true 或 false`);
+}
+
+function normalizeBackgroundColorOption(value) {
+  return value.toLowerCase() === "none" ? null : value;
+}
+
 function buildSkillsHelpTopic(action) {
   if (!action || action === "--help" || action === "-h") {
     return "skills";