@jingyi0605/codingns 0.3.6 → 0.5.0

package/bin/codingns.mjs

@@ -7,6 +7,15 @@ import { fileURLToPath } from "node:url";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const distRoot = path.join(packageRoot, "dist");
+const ASSISTANT_REQUEST_SOURCE_HEADER = "X-CodingNS-Assistant-Source";
+const ASSISTANT_CLI_REQUEST_SOURCE = "assistant-cli";
+const PROVIDER_SESSION_DELETE_PROVIDERS = new Set([
+  "claude-code",
+  "codex",
+  "opencode",
+  "gemini",
+  "kimi"
+]);
 
 const [command, ...argv] = process.argv.slice(2);
 
@@ -21,6 +30,9 @@ switch (command) {
   case "assistant":
     await runAssistantCommand(argv);
     break;
+  case "provider-sessions":
+    await runProviderSessionsCommand(argv);
+    break;
   case "skills":
     await runSkillsCommand(argv);
     break;
@@ -139,6 +151,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({
@@ -174,6 +212,16 @@ async function runAssistantCommand(argv) {
       }));
       return;
     }
+    case "sessions:delete": {
+      const [sessionId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "DELETE",
+        path: `/api/assistant/sessions/${requirePositional(sessionId, "sessionId")}`,
+        argv: tail,
+        helpTopic: "sessions.delete"
+      }));
+      return;
+    }
     case "sessions:send": {
       const [sessionId, ...tail] = rest;
       await printAssistantResponse(await requestAssistant({
@@ -207,6 +255,341 @@ 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 "follow-ups:list":
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: "/api/assistant/follow-ups",
+        argv: rest,
+        supportedOptions: ["status", "project-id", "session-id", "limit"],
+        helpTopic: "follow-ups.list"
+      }, (options) => ({
+        status: readOptionalTrimmedValue(options.values.status),
+        projectId: readOptionalTrimmedValue(options.values["project-id"]),
+        sessionId: readOptionalTrimmedValue(options.values["session-id"]),
+        limit: readOptionalTrimmedValue(options.values.limit)
+      })));
+      return;
+    case "follow-ups:get": {
+      const [taskId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "GET",
+        path: `/api/assistant/follow-ups/${requirePositional(taskId, "taskId")}`,
+        argv: tail,
+        helpTopic: "follow-ups.get"
+      }));
+      return;
+    }
+    case "follow-ups:create":
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: "/api/assistant/follow-ups",
+        argv: rest,
+        supportedOptions: [
+          "project-id",
+          "butler-session-id",
+          "provider",
+          "objective",
+          "completion-criteria",
+          "max-auto-continue-count",
+          "check-interval-seconds"
+        ],
+        helpTopic: "follow-ups.create"
+      }, (options) => ({
+        projectId: requireOptionValue(options.values["project-id"], "project-id"),
+        butlerSessionId: requireOptionValue(options.values["butler-session-id"], "butler-session-id"),
+        providerId: readOptionalTrimmedValue(options.values.provider),
+        objective: requireOptionValue(options.values.objective, "objective"),
+        completionCriteria: readOptionalTrimmedValue(options.values["completion-criteria"]),
+        maxAutoContinueCount: readOptionalTrimmedValue(options.values["max-auto-continue-count"]),
+        checkIntervalSeconds: readOptionalTrimmedValue(options.values["check-interval-seconds"])
+      })));
+      return;
+    case "follow-ups:continue": {
+      const [taskId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/follow-ups/${requirePositional(taskId, "taskId")}/continue`,
+        argv: tail,
+        supportedOptions: ["summary", "continue-prompt"],
+        helpTopic: "follow-ups.continue"
+      }, (options) => ({
+        summary: requireOptionValue(options.values.summary, "summary"),
+        continuePrompt: requireOptionValue(options.values["continue-prompt"], "continue-prompt")
+      })));
+      return;
+    }
+    case "follow-ups:waiting-user": {
+      const [taskId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/follow-ups/${requirePositional(taskId, "taskId")}/waiting-user`,
+        argv: tail,
+        supportedOptions: ["summary", "waiting-reason"],
+        helpTopic: "follow-ups.waiting-user"
+      }, (options) => ({
+        summary: requireOptionValue(options.values.summary, "summary"),
+        waitingReason: requireOptionValue(options.values["waiting-reason"], "waiting-reason")
+      })));
+      return;
+    }
+    case "follow-ups:complete": {
+      const [taskId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/follow-ups/${requirePositional(taskId, "taskId")}/complete`,
+        argv: tail,
+        supportedOptions: ["summary"],
+        helpTopic: "follow-ups.complete"
+      }, (options) => ({
+        summary: requireOptionValue(options.values.summary, "summary")
+      })));
+      return;
+    }
+    case "follow-ups:fail": {
+      const [taskId, ...tail] = rest;
+      await printAssistantResponse(await requestAssistant({
+        method: "POST",
+        path: `/api/assistant/follow-ups/${requirePositional(taskId, "taskId")}/fail`,
+        argv: tail,
+        supportedOptions: ["summary", "reason"],
+        helpTopic: "follow-ups.fail"
+      }, (options) => ({
+        summary: requireOptionValue(options.values.summary, "summary"),
+        reason: readOptionalTrimmedValue(options.values.reason)
+      })));
+      return;
+    }
     case "terminals:list":
       await printAssistantResponse(await requestAssistant({
         method: "GET",
@@ -627,6 +1010,116 @@ async function runSkillsCommand(argv) {
   }
 }
 
+async function runProviderSessionsCommand(argv) {
+  const [action, ...rest] = argv;
+
+  if (!action || isHelpToken(action)) {
+    printProviderSessionsHelpTopic(buildProviderSessionsHelpTopic(rest[0]), 0);
+  }
+
+  if (rest.length > 0 && isHelpToken(rest[0])) {
+    printProviderSessionsHelpTopic(buildProviderSessionsHelpTopic(action), 0);
+  }
+
+  switch (action) {
+    case "delete": {
+      const options = parseArgs(rest, {
+        supportedOptions: ["provider", "provider-session-id", "raw-store-ref"]
+      });
+
+      if (options.help) {
+        printProviderSessionsHelpTopic("provider-sessions.delete", 0);
+      }
+
+      if (options.errors.length > 0) {
+        for (const error of options.errors) {
+          console.error(`[codingns] ${error}`);
+        }
+        printProviderSessionsHelpTopic("provider-sessions.delete", 1);
+      }
+
+      const provider = requireOptionValue(options.values.provider, "provider");
+      const providerSessionId = requireOptionValue(
+        options.values["provider-session-id"],
+        "provider-session-id"
+      );
+      const rawStoreRef = requireOptionValue(options.values["raw-store-ref"], "raw-store-ref");
+
+      if (!PROVIDER_SESSION_DELETE_PROVIDERS.has(provider)) {
+        fail(
+          `provider-sessions delete 仅支持 ${[...PROVIDER_SESSION_DELETE_PROVIDERS].join(", ")}`
+        );
+      }
+
+      const { SessionSyncService, ProviderRegistry } = await import("@codingns/session-sync-core");
+      const {
+        ClaudeCodeAdapter,
+        CodexAdapter,
+        GeminiAdapter,
+        KimiAdapter,
+        OpenCodeAdapter
+      } = await import("@codingns/session-sync-core");
+      const homeDir = os.homedir();
+      const registry = new ProviderRegistry([
+        new ClaudeCodeAdapter({
+          homeDir: readStringOption(
+            process.env.CODINGNS_CLAUDE_CODE_HOME,
+            path.join(homeDir, ".claude")
+          )
+        }),
+        new CodexAdapter({
+          homeDir: readStringOption(
+            process.env.CODINGNS_CODEX_HOME,
+            path.join(homeDir, ".codex")
+          )
+        }),
+        new GeminiAdapter({
+          homeDir: readStringOption(
+            process.env.CODINGNS_GEMINI_HOME,
+            path.join(homeDir, ".gemini")
+          ),
+          commandPath: readStringOption(process.env.CODINGNS_GEMINI_COMMAND, "gemini")
+        }),
+        new KimiAdapter({
+          homeDir: readStringOption(
+            process.env.CODINGNS_KIMI_HOME,
+            path.join(homeDir, ".kimi")
+          ),
+          defaultModel: readOptionalTrimmedValue(process.env.CODINGNS_KIMI_DEFAULT_MODEL)
+        }),
+        new OpenCodeAdapter({
+          baseUrl: readOptionalTrimmedValue(process.env.CODINGNS_OPENCODE_BASE_URL) ?? undefined,
+          dataDir:
+            readOptionalTrimmedValue(process.env.CODINGNS_OPENCODE_DATA_DIR) ?? undefined,
+          dbPath:
+            readOptionalTrimmedValue(process.env.CODINGNS_OPENCODE_DB_PATH) ?? undefined
+        })
+      ]);
+      const sessionSyncService = new SessionSyncService(registry);
+
+      try {
+        await sessionSyncService.deleteSession(provider, providerSessionId, rawStoreRef);
+      } catch (error) {
+        console.error(
+          JSON.stringify(normalizeProviderSessionDeleteFailure(error), null, 2)
+        );
+        process.exit(1);
+      }
+
+      await printAssistantResponse({
+        ok: true,
+        provider,
+        providerSessionId,
+        rawStoreRef
+      });
+      return;
+    }
+    default:
+      console.error(`[codingns] 不支持的 provider-sessions 子命令：${action}`);
+      printProviderSessionsHelpTopic("provider-sessions", 1);
+  }
+}
+
 async function requestAssistant(command, buildPayload) {
   const options = parseArgs(command.argv, {
     supportedOptions: [
@@ -670,6 +1163,7 @@ async function requestAssistant(command, buildPayload) {
       method: command.method,
       headers: {
         Authorization: `Bearer ${accessToken}`,
+        [ASSISTANT_REQUEST_SOURCE_HEADER]: ASSISTANT_CLI_REQUEST_SOURCE,
         ...(usesJsonBody ? { "Content-Type": "application/json" } : {})
       },
       body: usesJsonBody ? JSON.stringify(payload ?? {}) : undefined
@@ -1154,6 +1648,7 @@ codingns 用法：
 
   codingns start [--host 0.0.0.0] [--port 3002] [--data-dir ~/.codingns] [--demo]
   codingns assistant <group> <action> [options]
+  codingns provider-sessions <action> [options]
   codingns skills <action> [options]
 
 说明：
@@ -1173,6 +1668,7 @@ assistant 例子：
   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 follow-ups continue <taskId> --summary "目标还没完成" --continue-prompt "继续补齐剩余实现" --token <token>
   codingns assistant terminals send <terminalId> --input "npm test\\n" --token <token>
   codingns assistant terminals close <terminalId> --token <token>
 
@@ -1181,6 +1677,10 @@ skills 例子：
   codingns skills overview --token <token>
   codingns skills add --source ./my-skill --target codex --token <token>
   codingns skills sync <skillId> --target gemini --token <token>
+
+provider-sessions 例子：
+
+  codingns provider-sessions delete --provider codex --provider-session-id <id> --raw-store-ref <ref>
 `.trim();
 
   if (exitCode === 0) {
@@ -1216,6 +1716,18 @@ function printSkillsHelpTopic(topic, exitCode) {
   process.exit(exitCode);
 }
 
+function printProviderSessionsHelpTopic(topic, exitCode) {
+  const output = getProviderSessionsHelpText(topic);
+
+  if (exitCode === 0) {
+    console.log(output);
+  } else {
+    console.error(output);
+  }
+
+  process.exit(exitCode);
+}
+
 function getAssistantHelpText(topic) {
   switch (topic) {
     case "capabilities":
@@ -1376,14 +1888,17 @@ codingns assistant sessions
 
 可用动作：
   list      列出指定项目下的会话
+  start     按 project/workspace/sandbox 目标新建真实会话
   get       读取会话详情
   messages  读取消息窗口
   runtime   读取运行态
+  delete    删除真实会话
   send      向真实项目会话发送消息
   fork      从会话或消息点 fork 新会话
 
 示例：
   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":
@@ -1395,6 +1910,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 `
@@ -1435,6 +1960,16 @@ codingns assistant sessions send
 
 用法：
   codingns assistant sessions send <sessionId> --message "..." [--client-request-id <id>] [--model <model>] [--reasoning-level <level>] [--permission-mode <mode>] --token <token>
+`.trim();
+    case "sessions.delete":
+      return `
+codingns assistant sessions delete
+
+用途：
+  删除指定真实会话；这会同时清理助手侧关联记录和工作区索引。
+
+用法：
+  codingns assistant sessions delete <sessionId> --token <token>
 `.trim();
     case "sessions.fork":
       return `
@@ -1445,6 +1980,280 @@ 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 "follow-ups":
+      return `
+codingns assistant follow-ups
+
+可用动作：
+  list          列出跟进任务
+  get           读取单个跟进任务
+  create        创建新的跟进任务
+  continue      回写继续推进结论
+  waiting-user  回写等待用户结论
+  complete      回写已完成结论
+  fail          回写失败结论
+
+示例：
+  codingns assistant follow-ups list --status active --token <token>
+  codingns assistant follow-ups continue <taskId> --summary "目标还没做完" --continue-prompt "继续补齐剩余实现" --token <token>
+`.trim();
+    case "follow-ups.list":
+      return `
+codingns assistant follow-ups list
+
+用途：
+  查看当前用户可见的会话跟进任务。
+
+用法：
+  codingns assistant follow-ups list [--status active|waiting_user|completed|failed|cancelled] [--project-id <projectId>] [--session-id <sessionId>] [--limit <n>] --token <token>
+`.trim();
+    case "follow-ups.get":
+      return `
+codingns assistant follow-ups get
+
+用途：
+  读取单个跟进任务详情和历史轮次。
+
+用法：
+  codingns assistant follow-ups get <taskId> --token <token>
+`.trim();
+    case "follow-ups.create":
+      return `
+codingns assistant follow-ups create
+
+用途：
+  为指定 Butler 会话创建新的跟进任务。
+
+用法：
+  codingns assistant follow-ups create --project-id <projectId> --butler-session-id <butlerSessionId> --objective "..." [--provider codex|claude-code] [--completion-criteria "..."] [--max-auto-continue-count <n>] [--check-interval-seconds <n>] --token <token>
+`.trim();
+    case "follow-ups.continue":
+      return `
+codingns assistant follow-ups continue
+
+用途：
+  回写“继续推进”结论，并安排下一轮自动跟进。
+
+用法：
+  codingns assistant follow-ups continue <taskId> --summary "..." --continue-prompt "..." --token <token>
+`.trim();
+    case "follow-ups.waiting-user":
+      return `
+codingns assistant follow-ups waiting-user
+
+用途：
+  回写“需要等待用户”结论，并写明必须等待的原因。
+
+用法：
+  codingns assistant follow-ups waiting-user <taskId> --summary "..." --waiting-reason "..." --token <token>
+`.trim();
+    case "follow-ups.complete":
+      return `
+codingns assistant follow-ups complete
+
+用途：
+  回写“任务已完成”结论，并结束当前跟进。
+
+用法：
+  codingns assistant follow-ups complete <taskId> --summary "..." --token <token>
+`.trim();
+    case "follow-ups.fail":
+      return `
+codingns assistant follow-ups fail
+
+用途：
+  回写“任务失败”结论，并记录失败原因。
+
+用法：
+  codingns assistant follow-ups fail <taskId> --summary "..." [--reason "..."] --token <token>
 `.trim();
     case "terminals":
       return `
@@ -1687,10 +2496,11 @@ codingns assistant worktrees cleanup
       return `
 codingns assistant 用法：
 
-  codingns assistant help [capabilities|projects|sessions|terminals|debug-targets|debug-runtimes|workspaces|worktrees] [action]
+  codingns assistant help [capabilities|projects|sessions|sandboxes|automations|timers|follow-ups|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 follow-ups continue <taskId> --summary "..." --continue-prompt "..." --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>
@@ -1710,11 +2520,27 @@ codingns assistant 用法：
   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 delete <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>
@@ -1734,6 +2560,39 @@ codingns assistant 用法：
   }
 }
 
+function getProviderSessionsHelpText(topic) {
+  switch (topic) {
+    case "provider-sessions.delete":
+      return `
+codingns provider-sessions delete
+
+用途：
+  直接删除底层 provider 会话，不经过项目会话索引。适合给 Host 或脚本层做真实删除调用。
+
+用法：
+  codingns provider-sessions delete --provider <claude-code|codex|opencode|gemini|kimi> --provider-session-id <id> --raw-store-ref <ref>
+`.trim();
+    default:
+      return `
+codingns provider-sessions 用法：
+
+  codingns provider-sessions delete --provider <claude-code|codex|opencode|gemini|kimi> --provider-session-id <id> --raw-store-ref <ref>
+
+环境变量：
+
+  CODINGNS_CLAUDE_CODE_HOME   Claude Code 数据目录，默认 ~/.claude
+  CODINGNS_CODEX_HOME         Codex 数据目录，默认 ~/.codex
+  CODINGNS_GEMINI_HOME        Gemini 数据目录，默认 ~/.gemini
+  CODINGNS_GEMINI_COMMAND     Gemini CLI 路径，默认 gemini
+  CODINGNS_KIMI_HOME          Kimi 数据目录，默认 ~/.kimi
+  CODINGNS_KIMI_DEFAULT_MODEL Kimi 默认模型，可选
+  CODINGNS_OPENCODE_BASE_URL  OpenCode server 地址，可选
+  CODINGNS_OPENCODE_DATA_DIR  OpenCode 数据目录，可选
+  CODINGNS_OPENCODE_DB_PATH   OpenCode sqlite 路径，可选
+`.trim();
+  }
+}
+
 function getSkillsHelpText(topic) {
   switch (topic) {
     case "skills.overview":
@@ -1806,6 +2665,23 @@ 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"]);
 
@@ -1936,10 +2812,46 @@ function buildSkillsHelpTopic(action) {
   return `skills.${action}`;
 }
 
+function buildProviderSessionsHelpTopic(action) {
+  if (!action || action === "--help" || action === "-h") {
+    return "provider-sessions";
+  }
+
+  return `provider-sessions.${action}`;
+}
+
 function isHelpToken(value) {
   return value === "help" || value === "--help" || value === "-h";
 }
 
+function normalizeProviderSessionDeleteFailure(error) {
+  const errorCode =
+    error instanceof Error && typeof error.message === "string" && error.message.trim().length > 0
+      ? error.message.trim()
+      : "PROVIDER_DELETE_FAILED";
+
+  return {
+    ok: false,
+    errorCode,
+    detail: describeProviderSessionDeleteFailure(errorCode)
+  };
+}
+
+function describeProviderSessionDeleteFailure(errorCode) {
+  switch (errorCode) {
+    case "PROVIDER_DELETE_NOT_SUPPORTED":
+      return "当前 provider 还没有接入 CLI 删除能力";
+    case "PROVIDER_SESSION_NOT_FOUND":
+      return "provider 会话不存在或已经被删除";
+    case "PROVIDER_SESSION_ID_REQUIRED":
+      return "providerSessionId 不能为空";
+    case "PROVIDER_NOT_SUPPORTED":
+      return "当前 provider 不受支持";
+    default:
+      return errorCode;
+  }
+}
+
 function fail(message) {
   console.error(`[codingns] ${message}`);
   process.exit(1);