@jingyi0605/codingns 0.3.0 → 0.3.6

package/bin/codingns.mjs

@@ -229,7 +229,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 +246,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 +633,9 @@ async function requestAssistant(command, buildPayload) {
       "base-url",
       "token",
       ...(command.supportedOptions ?? [])
-    ]
+    ],
+    repeatableOptions: command.repeatableOptions ?? [],
+    supportedFlags: command.supportedFlags ?? []
   });
 
   if (options.help) {
@@ -366,13 +665,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 +871,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 +890,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 +1008,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 +1168,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 +1260,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 `
@@ -925,6 +1454,7 @@ codingns assistant terminals
   list     列出项目或工作区下的终端
   history  读取终端历史输出
   send     向受控终端发送输入
+  close    关闭受控终端
 
 示例：
   codingns assistant terminals list --project-id <projectId> --token <token>
@@ -959,15 +1489,226 @@ 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|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 get <sessionId> [--base-url ...] --token <token>
   codingns assistant sessions messages <sessionId> [--cursor <cursor>] [--limit 40] [--direction forward|backward] --token <token>
@@ -977,11 +1718,18 @@ codingns assistant 用法：
   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 +1789,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 +1806,128 @@ function buildAssistantHelpTopic(action, rest) {
   return `${action}.${rest[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";