lark-coding-assistant 0.1.1 → 0.1.2

package/README.md

@@ -271,6 +271,25 @@ npm uninstall -g lark-coding-assistant
 
 daemon 的常规日志、stdout、stderr 和启动崩溃都会写入 `logs/assistant.log`。
 
+## 错误与调试
+
+CLI 默认只显示简洁的中文错误和可执行的解决建议，不会把 Node.js 堆栈、源码路径或内部异常直接输出到终端。例如 session 已经运行时，可以按提示连接现有 session 或换一个名称。
+
+查看 daemon 状态和日志：
+
+```bash
+lark-coding-assistant daemon status
+lark-coding-assistant logs
+```
+
+需要排查未知异常时，可以只为当前命令开启调试输出：
+
+```bash
+LARK_CODING_ASSISTANT_DEBUG=1 lark-coding-assistant <command>
+```
+
+调试模式会在友好提示后追加原始错误堆栈，请勿把可能包含本机路径或环境信息的完整输出直接发布到公开渠道。
+
 ## 常见问题
 
 ### 飞书消息进入了错误的 session

package/dist/cli.js

@@ -127,6 +127,36 @@ function runFile(file, args, options = {}) {
 // src/daemon/client.ts
 import { randomUUID } from "crypto";
 import { createConnection } from "net";
+
+// src/core/errors.ts
+var AppError = class extends Error {
+  code;
+  context;
+  constructor(code, message, context = {}, options = {}) {
+    super(message, options);
+    this.name = "AppError";
+    this.code = code;
+    this.context = context;
+  }
+};
+function isAppError(error) {
+  return error instanceof AppError;
+}
+function asAppError(error, code = "UNKNOWN", context = {}) {
+  if (isAppError(error)) {
+    if (Object.keys(context).length === 0) return error;
+    return new AppError(error.code, error.message, { ...context, ...error.context }, { cause: error });
+  }
+  return new AppError(code, errorMessage(error), context, { cause: error });
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function systemErrorCode(error) {
+  return error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
+}
+
+// src/daemon/client.ts
 function requestDaemon(socketPath, request, timeoutMs = 5e3) {
   return new Promise((resolve2, reject) => {
     const id = randomUUID();
@@ -134,7 +164,7 @@ function requestDaemon(socketPath, request, timeoutMs = 5e3) {
     let buffer = "";
     const timer = setTimeout(() => {
       socket.destroy();
-      reject(new Error("daemon request timed out"));
+      reject(new AppError("REQUEST_TIMEOUT", "daemon request timed out"));
     }, timeoutMs);
     socket.setEncoding("utf8");
     socket.once("connect", () => socket.write(`${JSON.stringify({ ...request, id })}
@@ -153,6 +183,11 @@ function requestDaemon(socketPath, request, timeoutMs = 5e3) {
     });
     socket.once("error", (error) => {
       clearTimeout(timer);
+      const code = systemErrorCode(error);
+      if (code === "ENOENT" || code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EPIPE") {
+        reject(new AppError("DAEMON_UNAVAILABLE", "unable to connect to daemon", {}, { cause: error }));
+        return;
+      }
       reject(error);
     });
   });
@@ -161,7 +196,13 @@ function requestDaemon(socketPath, request, timeoutMs = 5e3) {
 // src/agents/resume.ts
 function resolveResumeOption(options) {
   const modes = [options.resume !== void 0, options.resumeLast, options.resumeAll].filter(Boolean).length;
-  if (modes > 1) throw new Error("--resume, --resume-last, and --resume-all cannot be used together");
+  if (modes > 1) {
+    throw new AppError(
+      "INVALID_OPTIONS",
+      "--resume, --resume-last, and --resume-all cannot be used together",
+      { reason: "--resume\u3001--resume-last \u548C --resume-all \u4E0D\u80FD\u540C\u65F6\u4F7F\u7528" }
+    );
+  }
   if (options.resumeLast) return { mode: "last" };
   if (options.resumeAll) return { mode: "picker", all: true };
   if (typeof options.resume === "string") return { mode: "session", sessionId: options.resume };
@@ -728,6 +769,125 @@ var registrationDomains = {
   larkDomain: "accounts.larksuite.com"
 };
 
+// src/cli-errors.ts
+function withCliOperation(error, operation) {
+  return asAppError(error, "UNKNOWN", operation ? { operation } : {});
+}
+function formatCliError(error, debug = false) {
+  const appError = asAppError(error);
+  const context = appError.context;
+  const lines = formatKnownError(appError, context);
+  if (!debug) return lines.join("\n");
+  return [...lines, "", "\u8C03\u8BD5\u4FE1\u606F\uFF1A", debugStack(appError)].join("\n");
+}
+function cliDebugEnabled(env = process.env) {
+  return env.LARK_CODING_ASSISTANT_DEBUG === "1";
+}
+function formatKnownError(error, context) {
+  const sessionId = safeValue(context.sessionId, "default");
+  switch (error.code) {
+    case "SESSION_EXISTS":
+      return [
+        `\u65E0\u6CD5\u542F\u52A8 session\u300C${sessionId}\u300D\uFF1A\u8BE5 session \u5DF2\u5728\u8FD0\u884C\u3002`,
+        "",
+        "\u4F60\u53EF\u4EE5\uFF1A",
+        `  lark-coding-assistant attach ${sessionId}`,
+        "  lark-coding-assistant start --name <\u65B0\u540D\u79F0>"
+      ];
+    case "SESSION_NOT_FOUND":
+      return [
+        `\u627E\u4E0D\u5230 session\u300C${sessionId}\u300D\u3002`,
+        "",
+        "\u8BF7\u5148\u67E5\u770B\u6216\u521B\u5EFA session\uFF1A",
+        "  lark-coding-assistant status",
+        `  lark-coding-assistant start --name ${sessionId}`
+      ];
+    case "INVALID_SESSION_NAME":
+      return [
+        `session \u540D\u79F0\u300C${safeValue(context.sessionId, "")}\u300D\u65E0\u6548\u3002`,
+        "\u540D\u79F0\u53EA\u80FD\u5305\u542B\u5B57\u6BCD\u3001\u6570\u5B57\u3001\u4E0B\u5212\u7EBF\u548C\u77ED\u6A2A\u7EBF\uFF0C\u957F\u5EA6\u4E3A 1\u201340 \u4E2A\u5B57\u7B26\u3002"
+      ];
+    case "NOT_INITIALIZED":
+      return ["\u5C1A\u672A\u5B8C\u6210\u521D\u59CB\u5316\u3002", "", "\u8BF7\u8FD0\u884C\uFF1A", "  lark-coding-assistant init"];
+    case "INVALID_CWD":
+      return [
+        `\u5DE5\u4F5C\u76EE\u5F55\u4E0D\u53EF\u7528\uFF1A${safeValue(context.cwd, "\u672A\u77E5\u76EE\u5F55")}`,
+        "",
+        "\u8BF7\u68C0\u67E5\u76EE\u5F55\u662F\u5426\u5B58\u5728\u4E14\u6709\u8BBF\u95EE\u6743\u9650\uFF0C\u6216\u91CD\u65B0\u6307\u5B9A --cwd\u3002"
+      ];
+    case "BINARY_NOT_FOUND":
+      return [
+        `\u627E\u4E0D\u5230\u6240\u9700\u547D\u4EE4\uFF1A${safeValue(context.binary, "\u672A\u77E5\u547D\u4EE4")}`,
+        "",
+        "\u8BF7\u5148\u5B89\u88C5\u8BE5\u547D\u4EE4\uFF0C\u6216\u68C0\u67E5 PATH \u548C\u521D\u59CB\u5316\u914D\u7F6E\u3002"
+      ];
+    case "INVALID_OPTIONS":
+      return [
+        `\u547D\u4EE4\u53C2\u6570\u65E0\u6548\uFF1A${safeValue(context.reason, error.message)}`,
+        "",
+        "\u8BF7\u8FD0\u884C lark-coding-assistant --help \u67E5\u770B\u53EF\u7528\u53C2\u6570\u3002"
+      ];
+    case "DAEMON_UNAVAILABLE":
+      return [
+        "\u65E0\u6CD5\u8FDE\u63A5 bridge daemon\u3002",
+        "",
+        "\u8BF7\u5C1D\u8BD5\uFF1A",
+        "  lark-coding-assistant daemon restart",
+        "  lark-coding-assistant logs"
+      ];
+    case "REQUEST_TIMEOUT":
+      return [
+        "bridge daemon \u672A\u53CA\u65F6\u54CD\u5E94\u3002",
+        "",
+        "\u8BF7\u5C1D\u8BD5\uFF1A",
+        "  lark-coding-assistant daemon status",
+        "  lark-coding-assistant daemon restart",
+        "  lark-coding-assistant logs"
+      ];
+    case "UNKNOWN":
+      return [
+        `\u64CD\u4F5C\u5931\u8D25\uFF1A${operationLabel(context.operation)} \u65F6\u53D1\u751F\u5F02\u5E38\u3002`,
+        "",
+        "\u8BF7\u5C1D\u8BD5\uFF1A",
+        "  lark-coding-assistant status",
+        "  lark-coding-assistant logs",
+        "",
+        "\u9700\u8981\u67E5\u770B\u5B8C\u6574\u9519\u8BEF\uFF1A",
+        "  LARK_CODING_ASSISTANT_DEBUG=1 lark-coding-assistant ..."
+      ];
+  }
+}
+function operationLabel(value) {
+  const labels = {
+    init: "\u521D\u59CB\u5316",
+    start: "\u542F\u52A8 session",
+    attach: "\u8FDE\u63A5 session",
+    "bind-code": "\u751F\u6210\u7ED1\u5B9A\u7801",
+    status: "\u8BFB\u53D6\u72B6\u6001",
+    stop: "\u505C\u6B62 session",
+    logs: "\u8BFB\u53D6\u65E5\u5FD7",
+    "reset-owner": "\u91CD\u7F6E owner",
+    daemon: "\u7BA1\u7406 bridge daemon"
+  };
+  return typeof value === "string" ? labels[value] ?? "\u6267\u884C\u547D\u4EE4" : "\u6267\u884C\u547D\u4EE4";
+}
+function safeValue(value, fallback) {
+  if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") return fallback;
+  const normalized = String(value).replace(/[\u0000-\u001f\u007f\u009b]|\u001b\[[0-?]*[ -/]*[@-~]/g, " ").trim();
+  return normalized.slice(0, 160) || fallback;
+}
+function debugStack(error) {
+  const values = [];
+  let current = error;
+  const seen = /* @__PURE__ */ new Set();
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current);
+    values.push(current.stack ?? `${current.name}: ${current.message}`);
+    current = current.cause;
+  }
+  return values.join("\nCaused by:\n");
+}
+
 // src/cli.ts
 var program = new Command();
 var paths = resolveAppPaths();
@@ -749,7 +909,14 @@ daemonCommand.command("start").description("Start the bridge daemon").action(run
 daemonCommand.command("stop").description("Stop the bridge daemon without stopping coding-agent sessions").action(runDaemonStop);
 daemonCommand.command("restart").description("Restart the bridge daemon without stopping coding-agent sessions").action(runDaemonRestart);
 daemonCommand.command("status").description("Show bridge daemon status and version").action(runDaemonStatus);
-await program.parseAsync();
+try {
+  await program.parseAsync();
+} catch (error) {
+  const cliError = withCliOperation(error, commandOperation(process.argv));
+  process.stderr.write(`${formatCliError(cliError, cliDebugEnabled())}
+`);
+  process.exitCode = 1;
+}
 async function runInit() {
   await store.ensure();
   const tenantAnswer = await p.select({
@@ -816,19 +983,19 @@ ${url}
 async function runStart(options) {
   const cwd = resolve(options.cwd ?? process.cwd());
   const resume = resolveResumeOption(options);
-  await access(cwd);
+  await access(cwd).catch((error) => {
+    throw new AppError("INVALID_CWD", `working directory is unavailable: ${cwd}`, { cwd }, { cause: error });
+  });
   await ensureInitialized();
   await preflight(options.agent);
   await ensureDaemon();
-  const response = await requestDaemon(paths.socket, {
+  const value = await daemonValue({
     method: "start",
     cwd,
     sessionId: options.name,
     agent: options.agent,
     resume
   });
-  if (!response.ok) throw new Error(response.error);
-  const value = response.value;
   if (value.binding.mode === "reused") {
     console.log("\n\u5DF2\u81EA\u52A8\u6CBF\u7528\u539F\u6709\u98DE\u4E66/Lark \u79C1\u804A\u7ED1\u5B9A\u3002\n");
   } else if (value.binding.mode === "awaiting-owner-message") {
@@ -851,9 +1018,7 @@ async function runAttach(name) {
 async function runBindCode() {
   await ensureInitialized();
   await ensureDaemon();
-  const response = await requestDaemon(paths.socket, { method: "bindCode" });
-  if (!response.ok) throw new Error(response.error);
-  const value = response.value;
+  const value = await daemonValue({ method: "bindCode" });
   console.log(`\u98DE\u4E66/Lark \u79C1\u804A\u7ED1\u5B9A\u547D\u4EE4\uFF08${value.expiresInSeconds / 60} \u5206\u949F\u6709\u6548\uFF09\uFF1A`);
   console.log(`/attach ${value.bindCode}`);
 }
@@ -861,11 +1026,31 @@ async function attachLocal(name) {
   const state = await store.loadState();
   const config = await store.loadConfig();
   const session = state.sessions?.[name];
-  if (!session) throw new Error(`no managed session: ${name}`);
-  if (!config) throw new Error("not initialized");
+  if (!session) throw new AppError("SESSION_NOT_FOUND", `no managed session: ${name}`, { sessionId: name });
+  if (!config) throw new AppError("NOT_INITIALIZED", "not initialized");
+  try {
+    await runFile(config.tmuxBinary, ["has-session", "-t", `=${session.sessionName}`]);
+  } catch (error) {
+    if (systemErrorCode(error) === "ENOENT") {
+      throw new AppError("BINARY_NOT_FOUND", `command not found: ${config.tmuxBinary}`, {
+        binary: config.tmuxBinary
+      }, { cause: error });
+    }
+    throw new AppError("SESSION_NOT_FOUND", `managed session is no longer running: ${name}`, {
+      sessionId: name
+    }, { cause: error });
+  }
   const child = spawn3(config.tmuxBinary, ["attach-session", "-t", `=${session.sessionName}`], { stdio: "inherit" });
   const code = await new Promise((resolveExit, reject) => {
-    child.once("error", reject);
+    child.once("error", (error) => {
+      if (systemErrorCode(error) === "ENOENT") {
+        reject(new AppError("BINARY_NOT_FOUND", `command not found: ${config.tmuxBinary}`, {
+          binary: config.tmuxBinary
+        }, { cause: error }));
+        return;
+      }
+      reject(error);
+    });
     child.once("exit", resolveExit);
   });
   if (code && code !== 0) process.exitCode = code;
@@ -881,13 +1066,11 @@ async function runStatus(name) {
   }
 }
 async function runStop(name) {
-  const response = await requestDaemon(paths.socket, { method: "stop", sessionId: name });
-  if (!response.ok) throw new Error(response.error);
+  await daemonValue({ method: "stop", sessionId: name });
   console.log(`Coding-agent tmux session stopped${name ? `: ${name}` : "."}`);
 }
 async function runResetOwner() {
-  const response = await requestDaemon(paths.socket, { method: "resetOwner" });
-  if (!response.ok) throw new Error(response.error);
+  await daemonValue({ method: "resetOwner" });
   console.log("Owner cleared.");
 }
 async function runLogs(options) {
@@ -933,19 +1116,23 @@ CLI version: ${packageInfo.version}`);
 }
 async function ensureInitialized() {
   if (!await store.loadConfig() || !await store.loadSecrets()) {
-    throw new Error("not initialized; run lark-coding-assistant init first");
+    throw new AppError("NOT_INITIALIZED", "not initialized; run lark-coding-assistant init first");
   }
 }
 async function preflight(agentId) {
   const config = await store.loadConfig();
   const adapter = getAgentAdapter(agentId);
   await Promise.all([
-    runFile(config.tmuxBinary, ["-V"]),
-    runFile(adapter.binary(config), [...adapter.versionArgs])
+    preflightBinary(config.tmuxBinary, ["-V"]),
+    preflightBinary(adapter.binary(config), [...adapter.versionArgs])
   ]);
 }
 function parseAgentId(value) {
-  if (!isAgentId(value)) throw new Error(`unsupported coding agent: ${value}`);
+  if (!isAgentId(value)) {
+    throw new AppError("INVALID_OPTIONS", `unsupported coding agent: ${value}`, {
+      reason: `\u4E0D\u652F\u6301 coding agent\u300C${value}\u300D`
+    });
+  }
   return value;
 }
 async function ensureDaemon() {
@@ -960,4 +1147,29 @@ async function ensureDaemon() {
 function daemonEntryPath() {
   return fileURLToPath(new URL("./daemon-entry.js", import.meta.url));
 }
+async function daemonValue(request) {
+  const response = await requestDaemon(paths.socket, request);
+  if (!response.ok) throw daemonResultError(response);
+  return response.value;
+}
+function daemonResultError(response) {
+  return new AppError(
+    response.errorCode ?? "UNKNOWN",
+    response.error,
+    response.errorContext ?? {}
+  );
+}
+async function preflightBinary(binary, args) {
+  try {
+    await runFile(binary, args);
+  } catch (error) {
+    if (systemErrorCode(error) === "ENOENT") {
+      throw new AppError("BINARY_NOT_FOUND", `command not found: ${binary}`, { binary }, { cause: error });
+    }
+    throw error;
+  }
+}
+function commandOperation(argv) {
+  return argv.slice(2).find((argument) => !argument.startsWith("-"));
+}
 //# sourceMappingURL=cli.js.map