feishu-codex-console 1.0.0-beta.6

package/scripts/migrate-legacy.mjs

@@ -0,0 +1,97 @@
+import path from "node:path";
+
+import {
+  mergeEnvContent,
+  parseEnvEntries,
+  readEnvContent,
+  writeManagedConfig,
+} from "./config-file.mjs";
+import { defaultSetupPaths, envValue, normalizeInstanceId, splitCsv, validateOpenIds } from "./setup-lib.mjs";
+
+const SINGLE_PATH_KEYS = [
+  "CODEX_PROJECT_STATE_FILE",
+  "BRIDGE_DATABASE_FILE",
+  "BRIDGE_STATE_FILE",
+  "CODEX_CLI_PATH",
+  "LARK_CLI_PATH",
+];
+
+export async function migrateLegacyInstallation({
+  sourceDir,
+  sourceConfig,
+  targetConfig,
+  instance,
+  home,
+  allowExisting = false,
+  now,
+}) {
+  const legacyRoot = path.resolve(sourceDir);
+  const legacyConfig = sourceConfig
+    ? path.isAbsolute(sourceConfig)
+      ? path.normalize(sourceConfig)
+      : path.resolve(legacyRoot, sourceConfig)
+    : path.join(legacyRoot, ".env");
+  const sourceContent = await readEnvContent(legacyConfig);
+  if (sourceContent === null) throw new Error(`没有找到旧源码配置：${legacyConfig}`);
+  const entries = parseEnvEntries(sourceContent);
+  validateLegacyEntries(entries, legacyConfig);
+
+  const instanceId = normalizeInstanceId(instance ?? entries.BRIDGE_INSTANCE_ID ?? "default");
+  const defaults = defaultSetupPaths(instanceId, home);
+  const destination = path.resolve(targetConfig ?? defaults.configFile);
+  if (destination === legacyConfig) {
+    throw new Error("迁移目标不能与旧源码 .env 相同。请使用新的用户配置目录。");
+  }
+  const existingTarget = await readEnvContent(destination);
+  if (existingTarget !== null && !allowExisting) {
+    throw new Error(`目标配置已存在：${destination}。确认合并时添加 --force。`);
+  }
+
+  const dataDir = resolveLegacyPath(entries.BRIDGE_DATA_DIR, legacyRoot, path.join(legacyRoot, "var"));
+  const workdir = resolveLegacyPath(entries.CODEX_WORKDIR, legacyRoot);
+  const overrides = [
+    "# Migrated by feishu-codex-console. The legacy source directory remains unchanged.",
+    `BRIDGE_INSTANCE_ID=${envValue(instanceId)}`,
+    `BRIDGE_DATA_DIR=${envValue(dataDir)}`,
+    `CODEX_WORKDIR=${envValue(workdir)}`,
+  ];
+  const roots = splitCsv(entries.CODEX_PROJECT_ROOTS ?? "").map((root) =>
+    resolveLegacyPath(root, legacyRoot),
+  );
+  if (roots.length > 0) overrides.push(`CODEX_PROJECT_ROOTS=${envValue(roots.join(","))}`);
+  for (const key of SINGLE_PATH_KEYS) {
+    const value = entries[key]?.trim();
+    if (value) overrides.push(`${key}=${envValue(resolveLegacyPath(value, legacyRoot))}`);
+  }
+
+  const migratedContent = mergeEnvContent(sourceContent, `${overrides.join("\n")}\n`);
+  const writeResult = await writeManagedConfig(destination, migratedContent, {
+    ...(now ? { now } : {}),
+  });
+  return {
+    sourceDir: legacyRoot,
+    sourceConfig: legacyConfig,
+    targetConfig: destination,
+    instanceId,
+    dataDir,
+    workdir,
+    reusedLegacyData: true,
+    backupFile: writeResult.backupFile,
+  };
+}
+
+function validateLegacyEntries(entries, configFile) {
+  if (!entries.ALLOWED_FEISHU_OPEN_IDS?.trim()) {
+    throw new Error(`旧配置缺少 ALLOWED_FEISHU_OPEN_IDS：${configFile}`);
+  }
+  validateOpenIds(entries.ALLOWED_FEISHU_OPEN_IDS, "旧配置操作者 open_id");
+  if (!entries.CODEX_WORKDIR?.trim()) {
+    throw new Error(`旧配置缺少 CODEX_WORKDIR：${configFile}`);
+  }
+}
+
+function resolveLegacyPath(value, legacyRoot, fallback) {
+  const selected = value?.trim() || fallback;
+  if (!selected) throw new Error("旧配置包含空路径。");
+  return path.isAbsolute(selected) ? path.normalize(selected) : path.resolve(legacyRoot, selected);
+}

package/scripts/package-smoke.mjs

@@ -0,0 +1,163 @@
+import { spawnSync } from "node:child_process";
+import { access, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sandbox = await mkdtemp(path.join(tmpdir(), "feishu-codex-bridge-package-"));
+let archive;
+
+try {
+  archive = pack();
+  const archivePath = path.join(packageRoot, archive);
+  const installDir = path.join(sandbox, "consumer");
+  const configFile = path.join(sandbox, "config", "smoke.env");
+  const dataDir = path.join(sandbox, "data");
+
+  run("npm", [
+    "install",
+    "--ignore-scripts",
+    "--no-audit",
+    "--no-fund",
+    "--prefix",
+    installDir,
+    archivePath,
+  ]);
+
+  const cli = path.join(installDir, "node_modules", ".bin", "feishu-codex-console");
+  const compatibilityCli = path.join(installDir, "node_modules", ".bin", "feishu-codex-bridge");
+  await access(cli);
+  await access(compatibilityCli);
+  run(cli, ["help"], installDir);
+  run(compatibilityCli, ["help"], installDir);
+  const versionInfo = JSON.parse(run(cli, ["version", "--json"], installDir));
+  if (versionInfo.product !== "feishu-codex-console" || !versionInfo.version) {
+    throw new Error("Installed CLI did not expose version and compatibility metadata.");
+  }
+  runExpectFailure(
+    cli,
+    [
+      "init",
+      "--yes",
+      "--no-service",
+      "--skip-feishu-check",
+      "--preset",
+      "personal",
+      "--open-id",
+      "ou_package_smoke",
+      "--workdir",
+      path.join(sandbox, "missing-workdir"),
+      "--config",
+      configFile,
+      "--data-dir",
+      dataDir,
+    ],
+    installDir,
+  );
+  const interruptedStateFile = configFile.replace(/\.env$/, ".install-state.json");
+  const interruptedState = JSON.parse(await readFile(interruptedStateFile, "utf8"));
+  if (interruptedState.status !== "environment_ready" || !interruptedState.lastError) {
+    throw new Error("Interrupted installation did not persist a resumable safe checkpoint.");
+  }
+  run(
+    cli,
+    [
+      "init",
+      "--yes",
+      "--no-service",
+      "--skip-feishu-check",
+      "--preset",
+      "personal",
+      "--open-id",
+      "ou_package_smoke",
+      "--workdir",
+      packageRoot,
+      "--config",
+      configFile,
+      "--data-dir",
+      dataDir,
+    ],
+    installDir,
+  );
+
+  const config = await readFile(configFile, "utf8");
+  if (!config.includes("ALLOWED_FEISHU_OPEN_IDS=ou_package_smoke")) {
+    throw new Error("Installed CLI did not generate the expected configuration.");
+  }
+  const resumedState = JSON.parse(await readFile(interruptedStateFile, "utf8"));
+  if (!resumedState.completedSteps?.includes("config_written")) {
+    throw new Error("Second initialization did not resume through configuration write.");
+  }
+  const runbookProject = path.join(sandbox, "runbook-project");
+  await mkdir(runbookProject);
+  run(cli, ["init-runbooks", "--project", runbookProject], installDir);
+  const runbookFile = path.join(runbookProject, ".feishu-codex-runbooks.json");
+  const runbookCatalog = JSON.parse(await readFile(runbookFile, "utf8"));
+  if (runbookCatalog.version !== 1 || !Array.isArray(runbookCatalog.runbooks)) {
+    throw new Error("Installed package did not create a valid runbook template.");
+  }
+  await writeFile(runbookFile, '{"teamOwned":true}\n');
+  run(cli, ["init-runbooks", "--project", runbookProject], installDir);
+  if ((await readFile(runbookFile, "utf8")) !== '{"teamOwned":true}\n') {
+    throw new Error("Runbook initialization overwrote an existing team catalog.");
+  }
+  const upgradePreview = run(cli, ["upgrade", "--config", configFile], installDir);
+  if (!upgradePreview.includes("未做任何修改")) {
+    throw new Error("Safe upgrade preview did not remain read-only without --yes.");
+  }
+  const backupList = run(cli, ["backups", "--config", configFile], installDir);
+  if (!backupList.includes("可用运行数据备份（0）")) {
+    throw new Error("Installed CLI could not inspect runtime backups.");
+  }
+  if (process.platform !== "win32") {
+    const configMode = (await stat(configFile)).mode & 0o777;
+    const dataMode = (await stat(dataDir)).mode & 0o777;
+    if (configMode !== 0o600) throw new Error(`Config mode is ${configMode.toString(8)}, expected 600.`);
+    if (dataMode !== 0o700) throw new Error(`Data mode is ${dataMode.toString(8)}, expected 700.`);
+  }
+  console.log("Package smoke test passed: packed, installed, resumed, initialized runbooks, and previewed a safe upgrade.");
+} finally {
+  await rm(sandbox, { recursive: true, force: true });
+  if (archive) await rm(path.join(packageRoot, archive), { force: true });
+}
+
+function pack() {
+  const result = spawnSync("npm", ["pack", "--silent"], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"],
+  });
+  if (result.status !== 0) throw new Error("npm pack failed.");
+  const filename = result.stdout.trim().split("\n").at(-1);
+  if (!filename?.endsWith(".tgz")) throw new Error(`Unexpected npm pack output: ${result.stdout}`);
+  return filename;
+}
+
+function run(command, args, cwd = packageRoot) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env: process.env,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed.\n${result.stdout ?? ""}\n${result.stderr ?? ""}`,
+    );
+  }
+  return result.stdout;
+}
+
+function runExpectFailure(command, args, cwd = packageRoot) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env: process.env,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+  if (result.status === 0) {
+    throw new Error(`${command} ${args.join(" ")} unexpectedly succeeded.`);
+  }
+  return `${result.stdout ?? ""}${result.stderr ?? ""}`;
+}

package/scripts/release-dist-tag.mjs

@@ -0,0 +1,7 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const manifest = JSON.parse(await readFile(path.join(packageRoot, "package.json"), "utf8"));
+console.log(String(manifest.version).includes("-") ? "next" : "latest");

package/scripts/runbook-template.mjs

@@ -0,0 +1,36 @@
+import { constants } from "node:fs";
+import { chmod, copyFile, lstat } from "node:fs/promises";
+import path from "node:path";
+
+export const RUNBOOK_TEMPLATE_NAME = ".feishu-codex-runbooks.json";
+
+export async function initializeRunbookTemplate({ projectDir, sourceFile }) {
+  const project = path.resolve(projectDir);
+  const source = path.resolve(sourceFile);
+  await assertDirectory(project, "项目目录");
+  await assertRegularFile(source, "运行手册示例");
+  const target = path.join(project, RUNBOOK_TEMPLATE_NAME);
+
+  try {
+    await copyFile(source, target, constants.COPYFILE_EXCL);
+    await chmod(target, 0o644);
+    return { created: true, target };
+  } catch (error) {
+    if (error?.code === "EEXIST") return { created: false, target };
+    throw error;
+  }
+}
+
+async function assertDirectory(directory, label) {
+  const details = await lstat(directory).catch(() => null);
+  if (!details?.isDirectory() || details.isSymbolicLink()) {
+    throw new Error(`${label}不存在或不是安全目录：${directory}`);
+  }
+}
+
+async function assertRegularFile(file, label) {
+  const details = await lstat(file).catch(() => null);
+  if (!details?.isFile() || details.isSymbolicLink()) {
+    throw new Error(`${label}不存在或不是安全文件：${file}`);
+  }
+}

package/scripts/service-health.mjs

@@ -0,0 +1,110 @@
+import { lstat, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const BRIDGE_HEALTH_FILE = "bridge-health.json";
+
+export function serviceHealthPath(dataDir) {
+  return path.join(dataDir, BRIDGE_HEALTH_FILE);
+}
+
+export async function readServiceHealth(dataDir) {
+  const file = serviceHealthPath(dataDir);
+  const details = await lstat(file);
+  if (!details.isFile() || details.isSymbolicLink()) {
+    throw new Error(`服务健康文件不安全：${file}`);
+  }
+  return JSON.parse(await readFile(file, "utf8"));
+}
+
+export function validateServiceHealth(
+  health,
+  {
+    instanceId,
+    configFile,
+    now = Date.now(),
+    maxHeartbeatAgeMs = 45_000,
+    processAlive = isProcessAlive,
+  },
+) {
+  if (!health || typeof health !== "object" || Array.isArray(health)) {
+    return invalid("健康文件格式无效");
+  }
+  if (health.version !== 1) return invalid("健康文件版本不受支持");
+  if (health.status !== "ready") {
+    return invalid(`服务尚未就绪（当前状态：${String(health.status ?? "unknown")}）`);
+  }
+  if (health.instanceId !== instanceId) {
+    return invalid(`服务实例不一致（期望 ${instanceId}，实际 ${String(health.instanceId)}）`);
+  }
+  if (!Number.isSafeInteger(health.pid) || health.pid <= 0 || !processAlive(health.pid)) {
+    return invalid("健康文件对应的后台进程不存在");
+  }
+  if (typeof health.configFile !== "string" || health.configFile.length === 0) {
+    return invalid("后台服务没有报告配置文件路径");
+  }
+  if (path.resolve(health.configFile) !== path.resolve(configFile)) {
+    return invalid(
+      `后台服务读取了另一份配置（期望 ${path.resolve(configFile)}，实际 ${path.resolve(health.configFile)}）`,
+    );
+  }
+  const updatedAt = Date.parse(health.updatedAt);
+  if (!Number.isFinite(updatedAt)) return invalid("健康时间戳无效");
+  if (now - updatedAt > maxHeartbeatAgeMs) return invalid("后台服务健康心跳已过期");
+  if (updatedAt - now > 5_000) return invalid("后台服务健康时间戳来自未来");
+  if (!Array.isArray(health.consumers) || health.consumers.length < 2) {
+    return invalid("飞书事件消费者尚未完整启动");
+  }
+  if (health.consumers.some((consumer) => !consumer || consumer.ready !== true)) {
+    return invalid("至少一个飞书事件消费者尚未就绪");
+  }
+  return { ok: true, reason: "服务健康且配置一致" };
+}
+
+export async function waitForServiceHealth({
+  dataDir,
+  instanceId,
+  configFile,
+  timeoutMs = 30_000,
+  pollIntervalMs = 250,
+  processAlive,
+}) {
+  const deadline = Date.now() + timeoutMs;
+  let lastReason = "尚未生成健康文件";
+  while (Date.now() <= deadline) {
+    try {
+      const health = await readServiceHealth(dataDir);
+      const validation = validateServiceHealth(health, {
+        instanceId,
+        configFile,
+        ...(processAlive ? { processAlive } : {}),
+      });
+      if (validation.ok) return health;
+      lastReason = validation.reason;
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        lastReason = error instanceof Error ? error.message : String(error);
+      }
+    }
+    await delay(pollIntervalMs);
+  }
+  throw new Error(
+    `后台服务在 ${Math.ceil(timeoutMs / 1_000)} 秒内未就绪：${lastReason}。请查看服务日志后重新运行安装。`,
+  );
+}
+
+function invalid(reason) {
+  return { ok: false, reason };
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/scripts/service.mjs

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
+const action = process.argv[2] ?? "status";
+const script =
+  process.platform === "darwin"
+    ? path.join(scriptsDir, "launchd.mjs")
+    : process.platform === "linux"
+      ? path.join(scriptsDir, "systemd.mjs")
+      : null;
+
+if (!script) {
+  console.error("后台服务安装目前支持 macOS LaunchAgent 和 Linux systemd user service。");
+  process.exit(1);
+}
+
+const result = spawnSync(process.execPath, [script, action], {
+  cwd: path.resolve(scriptsDir, ".."),
+  env: process.env,
+  stdio: "inherit",
+});
+process.exitCode = result.status ?? 1;

package/scripts/setup-lib.mjs

@@ -0,0 +1,118 @@
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const SETUP_PRESETS = Object.freeze({
+  personal: Object.freeze({
+    label: "个人安全（推荐）",
+    sandboxMode: "workspace-write",
+    operatorSandboxMode: "workspace-write",
+    networkAccess: false,
+    webSearchMode: "disabled",
+  }),
+  team: Object.freeze({
+    label: "团队安全",
+    sandboxMode: "workspace-write",
+    operatorSandboxMode: "workspace-write",
+    networkAccess: false,
+    webSearchMode: "disabled",
+  }),
+  power: Object.freeze({
+    label: "高级模式",
+    sandboxMode: "danger-full-access",
+    operatorSandboxMode: "workspace-write",
+    networkAccess: false,
+    webSearchMode: "disabled",
+  }),
+});
+
+export function normalizeInstanceId(value = "default") {
+  const normalized = value
+    .trim()
+    .toLocaleLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  if (!normalized) throw new Error("实例名称至少需要包含一个字母或数字。");
+  return normalized;
+}
+
+export function splitCsv(value = "") {
+  return [...new Set(value.split(",").map((item) => item.trim()).filter(Boolean))];
+}
+
+export function validateOpenIds(value, label = "open_id") {
+  const ids = Array.isArray(value) ? value : splitCsv(value);
+  if (ids.length === 0) throw new Error(`${label} 不能为空。`);
+  for (const id of ids) {
+    if (!/^ou_[A-Za-z0-9_-]+$/.test(id)) {
+      throw new Error(`${label}“${id}”格式不正确，应以 ou_ 开头。`);
+    }
+  }
+  return ids;
+}
+
+export function validateChatIds(value, label = "chat_id") {
+  const ids = Array.isArray(value) ? value : splitCsv(value);
+  for (const id of ids) {
+    if (!/^oc_[A-Za-z0-9_-]+$/.test(id)) {
+      throw new Error(`${label}“${id}”格式不正确，应以 oc_ 开头。`);
+    }
+  }
+  return ids;
+}
+
+export function defaultSetupPaths(instanceId = "default", home = homedir()) {
+  const instance = normalizeInstanceId(instanceId);
+  return {
+    instance,
+    configDir: path.join(home, ".config", "feishu-codex-bridge"),
+    configFile: path.join(home, ".config", "feishu-codex-bridge", `${instance}.env`),
+    dataDir: path.join(home, ".local", "share", "feishu-codex-bridge", instance),
+  };
+}
+
+export function buildEnvFile(options) {
+  const preset = SETUP_PRESETS[options.preset];
+  if (!preset) throw new Error(`未知权限预设：${options.preset}`);
+  const operators = validateOpenIds(options.operatorIds, "操作者 open_id");
+  const admins = validateOpenIds(options.adminIds?.length ? options.adminIds : operators, "管理员 open_id");
+  const viewers = splitCsv((options.viewerIds ?? []).join?.(",") ?? options.viewerIds ?? "");
+  if (viewers.length > 0) validateOpenIds(viewers, "只读成员 open_id");
+  const chats = splitCsv((options.chatIds ?? []).join?.(",") ?? options.chatIds ?? "");
+  validateChatIds(chats, "群聊 chat_id");
+  const workdir = path.resolve(options.workdir);
+  const roots = splitCsv((options.projectRoots ?? []).join?.(",") ?? options.projectRoots ?? "")
+    .map((root) => path.resolve(root));
+  const lines = [
+    "# Generated by feishu-codex-bridge init. Keep this file private.",
+    "BRIDGE_CONFIG_VERSION=1",
+    `BRIDGE_INSTANCE_ID=${envValue(options.instanceId)}`,
+    `BRIDGE_DATA_DIR=${envValue(path.resolve(options.dataDir))}`,
+    `ALLOWED_FEISHU_OPEN_IDS=${envValue(operators.join(","))}`,
+    `FEISHU_ADMIN_OPEN_IDS=${envValue(admins.join(","))}`,
+    `FEISHU_VIEWER_OPEN_IDS=${envValue(viewers.join(","))}`,
+    `FEISHU_MEMBER_LABELS_JSON=${envValue(options.memberLabelsJson ?? "")}`,
+    `ALLOWED_FEISHU_CHAT_IDS=${envValue(chats.join(","))}`,
+    "FEISHU_GROUP_SESSION_SCOPE=member",
+    `CODEX_WORKDIR=${envValue(workdir)}`,
+    "CODEX_SYNC_SAVED_PROJECTS=true",
+    `CODEX_PROJECT_ROOTS=${envValue(roots.join(","))}`,
+    `CODEX_SANDBOX_MODE=${preset.sandboxMode}`,
+    `CODEX_OPERATOR_SANDBOX_MODE=${preset.operatorSandboxMode}`,
+    `CODEX_NETWORK_ACCESS=${preset.networkAccess}`,
+    `CODEX_WEB_SEARCH_MODE=${preset.webSearchMode}`,
+    "CODEX_MULTI_AGENT_ENABLED=false",
+    "FEISHU_AUTO_ONBOARDING=true",
+    "FEISHU_COMPLETION_NOTIFICATIONS=false",
+    "LOG_MESSAGE_CONTENT=false",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+export function envValue(value) {
+  const text = String(value ?? "");
+  if (text === "") return "";
+  if (!/[\s#'"\\]/.test(text)) return text;
+  return `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}

package/scripts/systemd.mjs

@@ -0,0 +1,96 @@
+import "dotenv/config";
+
+import { spawnSync } from "node:child_process";
+import { chmod, mkdir, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const instanceId = safeInstanceId(process.env.BRIDGE_INSTANCE_ID);
+const configFile = process.env.DOTENV_CONFIG_PATH?.trim();
+const unitName = `feishu-codex-bridge-${instanceId}.service`;
+const unitDir = path.join(homedir(), ".config", "systemd", "user");
+const unitPath = path.join(unitDir, unitName);
+const action = process.argv[2] ?? "status";
+
+if (process.platform !== "linux") {
+  console.error("systemd user service 仅支持 Linux。");
+  process.exit(1);
+}
+
+if (action === "install") await install();
+else if (action === "uninstall") await uninstall();
+else if (action === "status") process.exitCode = systemctl(["status", unitName], true).status ?? 1;
+else if (action === "stop") process.exitCode = systemctl(["stop", unitName], true).status ?? 1;
+else if (action === "restart") process.exitCode = systemctl(["restart", unitName], true).status ?? 1;
+else {
+  console.error("用法：node scripts/systemd.mjs install|uninstall|status|stop|restart");
+  process.exitCode = 2;
+}
+
+async function install() {
+  await mkdir(unitDir, { recursive: true, mode: 0o700 });
+  await chmod(unitDir, 0o700);
+  await writeFile(unitPath, unit(), { encoding: "utf8", mode: 0o600 });
+  systemctl(["daemon-reload"], true);
+  const result = systemctl(["enable", "--now", unitName], true);
+  if (result.status !== 0) process.exit(result.status ?? 1);
+  console.log(`已安装并启动 ${unitName}`);
+  console.log(`查看日志：journalctl --user -u ${unitName} -f`);
+}
+
+async function uninstall() {
+  systemctl(["disable", "--now", unitName], false);
+  await rm(unitPath, { force: true });
+  systemctl(["daemon-reload"], false);
+  console.log(`已卸载 ${unitName}`);
+}
+
+function systemctl(args, inherit) {
+  return spawnSync("systemctl", ["--user", ...args], {
+    cwd: projectDir,
+    env: process.env,
+    encoding: "utf8",
+    stdio: inherit ? "inherit" : "ignore",
+  });
+}
+
+function unit() {
+  const environmentPath = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
+  const configEnvironment = configFile
+    ? `Environment=${systemdQuote(`DOTENV_CONFIG_PATH=${path.resolve(configFile)}`)}\n`
+    : "";
+  return `[Unit]
+Description=Feishu Codex Bridge (${instanceId})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${systemdQuote(projectDir)}
+ExecStart=${systemdQuote(process.execPath)} --disable-warning=ExperimentalWarning ${systemdQuote(path.join(projectDir, "dist", "index.js"))}
+Environment=${systemdQuote(`PATH=${environmentPath}`)}
+Environment=NODE_ENV=production
+${configEnvironment}Restart=always
+RestartSec=5
+UMask=0077
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function systemdQuote(value) {
+  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function safeInstanceId(value) {
+  const normalized = (value?.trim() || "default")
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  if (!normalized) throw new Error("BRIDGE_INSTANCE_ID must contain letters or numbers");
+  return normalized;
+}