larkway 0.3.8 → 0.3.9

package/README.md

@@ -8,7 +8,7 @@
 
 You @ the bot in a Feishu thread. It runs on your machine — reading your real codebase, executing commands, opening MRs — and posts the result back. You define what the agent knows and what it can do. Larkway just carries the messages.
 
-**Current release: v0.3.6**
+**Current release: v0.3.9**
 
 ---
 

package/README.zh.md

@@ -8,7 +8,7 @@
 
 你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
 
-**当前版本：v0.3.6**
+**当前版本：v0.3.9**
 
 ---
 

package/dist/cli/index.js

@@ -119646,6 +119646,14 @@ var GitIdentitySchema = external_exports.object({
   name: external_exports.string().min(1),
   email: external_exports.string().email()
 });
+var GitCloneUrlSchema = external_exports.string().min(1).refine(
+  (value) => {
+    if (/^https?:\/\/\S+$/i.test(value)) return true;
+    if (/^ssh:\/\/\S+$/i.test(value)) return true;
+    return /^[A-Za-z0-9_.-]+@[^:\s]+:[^ \t\r\n]+$/.test(value);
+  },
+  "url must be an http(s), ssh://, or scp-like Git clone URL"
+);
 var BotConfigSchema = external_exports.object({
   /** Unique identifier, kebab-case. Used as key in sessionStore. */
   id: external_exports.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "id must be kebab-case"),
@@ -119720,7 +119728,7 @@ var BotConfigSchema = external_exports.object({
        * Agent workspace runtime: URL is a pointer only; the Agent decides clone
        * timing and destination.
        */
-      url: external_exports.string().url().optional()
+      url: GitCloneUrlSchema.optional()
     })
   ).default([]),
   /**
@@ -120016,7 +120024,7 @@ function renderBotYaml(config) {
   const header = [
     "# Larkway bot config (L1) \u2014 generated/edited via `larkway` CLI.",
     "# Credentials are env-var NAMES, never values:",
-    "#   app_secret_env / gitlab_token_env reference keys in ~/.larkway/.env (chmod 0600).",
+    "#   app_secret_env / git_token_env reference keys in ~/.larkway/.env (chmod 0600).",
     "# L2 \u804C\u80FD memory lives alongside in <id>.memory.md (memory_file points at it).",
     ""
   ].join("\n");
@@ -122196,14 +122204,14 @@ async function runAdd(ctx, args) {
     });
     if (repoSlug) {
       const repoBranch = await ui.prompt("\u9ED8\u8BA4\u5206\u652F:", {
-        default: setMap.get("repo_branch") ?? "master",
+        default: setMap.get("repo_branch") ?? "main",
         nonInteractive: flags.nonInteractive
       });
-      const repoUrl = await ui.prompt("clone URL (\u53EF\u9009,\u7559\u7A7A=\u7528\u9ED8\u8BA4 remote \u63A8\u5BFC):", {
+      const repoUrl = await ui.prompt("clone URL (\u5EFA\u8BAE\u586B\u5199;agent \u7528\u5B83 clone):", {
         default: setMap.get("repo_url") ?? "",
         nonInteractive: flags.nonInteractive
       });
-      const repoEntry = { slug: repoSlug, branch: repoBranch || "master" };
+      const repoEntry = { slug: repoSlug, branch: repoBranch || "main" };
       if (repoUrl) repoEntry.url = repoUrl;
       repos.push(repoEntry);
     }
@@ -122212,7 +122220,7 @@ async function runAdd(ctx, args) {
     if (repoSlug) {
       const repoEntry = {
         slug: repoSlug,
-        branch: setMap.get("repo_branch") ?? "master"
+        branch: setMap.get("repo_branch") ?? "main"
       };
       const repoUrl = setMap.get("repo_url");
       if (repoUrl) repoEntry.url = repoUrl;
@@ -122220,12 +122228,11 @@ async function runAdd(ctx, args) {
     }
   }
   let gitlab_token_env;
-  const defaultGitlabTokenEnv2 = repos.length > 0 ? `LARKWAY_${id.toUpperCase().replace(/-/g, "_")}_GITLAB_TOKEN` : "";
-  if (flags.advanced || setMap.has("gitlab_token_env") || repos.length > 0) {
+  if (flags.advanced || setMap.has("gitlab_token_env")) {
     const rawGitlab = await ui.prompt(
-      "Git access token \u73AF\u5883\u53D8\u91CF\u540D(\u4EC5\u8BB0\u5F55 KEY,\u771F\u503C\u5199 ~/.larkway/.env):",
+      "Git access token \u73AF\u5883\u53D8\u91CF\u540D(\u53EF\u9009;\u79C1\u6709\u5E93/push/MR \u624D\u9700\u8981):",
       {
-        default: setMap.get("gitlab_token_env") ?? defaultGitlabTokenEnv2,
+        default: setMap.get("gitlab_token_env") ?? "",
         nonInteractive: flags.nonInteractive
       }
     );
@@ -122236,10 +122243,6 @@ async function runAdd(ctx, args) {
       return 1;
     }
   }
-  if (repos.length > 0 && !gitlab_token_env) {
-    ui.failure("agent_workspace repo bot \u5FC5\u987B\u58F0\u660E git_token_env(\u6216 gitlab_token_env);v0.3 \u4E0D\u7EE7\u627F\u5168\u5C40 GITLAB_TOKEN\u3002");
-    return 1;
-  }
   let lark_cli_profile;
   if (flags.advanced || setMap.has("lark_cli_profile")) {
     const rawProfile = await ui.prompt(
@@ -124556,10 +124559,10 @@ function defaultOnboardPermissionRequests(input) {
     items.push(`Feishu chat allowlist: ${input.chats.join(", ")}`);
   }
   for (const repo of input.repos) {
-    items.push(`GitLab repo pointer: ${repo.slug} (${repo.branch})`);
+    items.push(`Git repo pointer: ${repo.slug} (${repo.branch})`);
   }
   if (input.gitlab_token_env) {
-    items.push(`GitLab token env name: ${input.gitlab_token_env}`);
+    items.push(`Agent-level Git token env name: ${input.gitlab_token_env}`);
   }
   items.push("Local shell inside the Agent Workspace for task execution and verification");
   return items;
@@ -124706,6 +124709,128 @@ async function cancelOnboard(sessionId) {
   return { cancelled: true };
 }
 
+// src/runtimeRequirements.ts
+import { execFileSync } from "node:child_process";
+function checkCli(command) {
+  try {
+    execFileSync("which", [command], { stdio: ["pipe", "pipe", "pipe"] });
+  } catch {
+    return { ok: false };
+  }
+  try {
+    const version = execFileSync(command, ["--version"], { stdio: ["pipe", "pipe", "pipe"] }).toString().trim().split("\n")[0];
+    return { ok: true, ...version ? { version } : {} };
+  } catch {
+    return { ok: true };
+  }
+}
+function repoLooksGitLab(urlOrSlug) {
+  return /(^|[./:@-])gitlab([./:@-]|$)/i.test(urlOrSlug);
+}
+function botUsesGitLab(bot) {
+  return bot.repos.some((repo) => repoLooksGitLab(repo.url ?? repo.slug));
+}
+function addCliRequirement(requirements, input) {
+  const existing = requirements.get(`cli:${input.command}`);
+  if (existing) {
+    existing.botIds = Array.from(/* @__PURE__ */ new Set([...existing.botIds, ...input.botIds])).sort();
+    if (existing.severity === "optional" && input.severity === "required") {
+      existing.severity = "required";
+    }
+    return;
+  }
+  const probe = checkCli(input.command);
+  requirements.set(`cli:${input.command}`, {
+    id: `cli:${input.command}`,
+    label: input.label ?? input.command,
+    command: input.command,
+    kind: "cli",
+    severity: input.severity,
+    ok: probe.ok,
+    ...probe.version ? { version: probe.version } : {},
+    reason: input.reason,
+    ...input.installHint ? { installHint: input.installHint } : {},
+    botIds: Array.from(new Set(input.botIds)).sort()
+  });
+}
+function addSecretRequirement(requirements, input) {
+  const id = `secret:${input.envName}`;
+  const existing = requirements.get(id);
+  if (existing) {
+    existing.botIds = Array.from(/* @__PURE__ */ new Set([...existing.botIds, ...input.botIds])).sort();
+    return;
+  }
+  const value = process.env[input.envName];
+  requirements.set(id, {
+    id,
+    label: input.envName,
+    kind: "secret",
+    severity: input.severity ?? "required",
+    ok: value != null && value !== "",
+    reason: input.reason,
+    installHint: `Set ${input.envName} in ~/.larkway/.env and restart Larkway.`,
+    botIds: Array.from(new Set(input.botIds)).sort()
+  });
+}
+function runtimeRequirementsForBots(bots) {
+  const requirements = /* @__PURE__ */ new Map();
+  if (bots.length > 0) {
+    addCliRequirement(requirements, {
+      command: "lark-cli",
+      label: "Feishu CLI",
+      severity: "required",
+      botIds: bots.map((bot) => bot.id),
+      reason: "Required for agents to read Feishu topic history, attachments, docs, and other context.",
+      installHint: "Install and configure lark-cli, then restart Larkway."
+    });
+  }
+  for (const bot of bots) {
+    addCliRequirement(requirements, {
+      command: bot.backend ?? "claude",
+      severity: "required",
+      botIds: [bot.id],
+      reason: `Required to run this bot's ${bot.backend ?? "claude"} backend.`
+    });
+    if (bot.runtime === "agent_workspace" && bot.repos.length > 0) {
+      const tokenEnvName = bot.git_token_env ?? bot.gitlab_token_env;
+      if (tokenEnvName) {
+        addSecretRequirement(requirements, {
+          envName: tokenEnvName,
+          botIds: [bot.id],
+          severity: "optional",
+          reason: "Optional Git identity material. When absent, agents use the host's normal Git auth."
+        });
+      } else {
+        requirements.set(`secret:missing-git-token:${bot.id}`, {
+          id: `secret:missing-git-token:${bot.id}`,
+          label: "Git access token env",
+          kind: "secret",
+          severity: "optional",
+          ok: false,
+          reason: `Bot "${bot.id}" has repo pointers but no git_token_env. It will use the host's normal Git auth.`,
+          installHint: "Add a Git access token only when you want this agent to use a specific GitHub/GitLab identity.",
+          botIds: [bot.id]
+        });
+      }
+    }
+    if (botUsesGitLab(bot)) {
+      addCliRequirement(requirements, {
+        command: "glab",
+        label: "GitLab CLI",
+        severity: "optional",
+        botIds: [bot.id],
+        reason: "Only needed when an agent uses GitLab-specific actions such as MRs, pipelines, or releases.",
+        installHint: "Install glab only for bots that need GitLab-specific workflow commands."
+      });
+    }
+  }
+  return [...requirements.values()].sort((a, b) => {
+    if (a.severity !== b.severity) return a.severity === "required" ? -1 : 1;
+    if (a.kind !== b.kind) return a.kind === "cli" ? -1 : 1;
+    return a.label.localeCompare(b.label);
+  });
+}
+
 // src/web/api.ts
 var execFileAsync7 = promisify8(execFileCallback2);
 var CHAT_NAME_CACHE_MS = 5 * 60 * 1e3;
@@ -125395,6 +125520,22 @@ var getBridgeLogs = async (req) => {
     json: result
   };
 };
+var getRuntimeRequirements = async (req) => {
+  const { ctx } = req;
+  const ids = await ctx.stores.botsStore.listBots();
+  const bots = await Promise.all(
+    ids.map(async (id) => ctx.stores.botsStore.readBot(id))
+  );
+  const requirements = runtimeRequirementsForBots(bots);
+  return {
+    status: 200,
+    json: {
+      requirements,
+      missingRequired: requirements.filter((req2) => req2.severity === "required" && !req2.ok),
+      missingOptional: requirements.filter((req2) => req2.severity === "optional" && !req2.ok)
+    }
+  };
+};
 var BACKEND_META = {
   claude: { id: "claude", name: "Claude Code", short: "Claude", vendor: "Anthropic \u8BA2\u9605", mono: "CC" },
   codex: { id: "codex", name: "Codex", short: "Codex", vendor: "OpenAI \u8BA2\u9605", mono: "CX" }
@@ -125436,6 +125577,7 @@ var ROUTES = {
   "GET /api/bridge": getBridge,
   "POST /api/bridge/restart": postBridgeRestart,
   "GET /api/bridge/logs": getBridgeLogs,
+  "GET /api/runtime/requirements": getRuntimeRequirements,
   "GET /api/backends": getBackends
 };
 function matchRoute(method, pathname, routes = ROUTES) {

package/dist/main.js

@@ -107360,7 +107360,6 @@ var require_main = __commonJS({
 });
 
 // src/main.ts
-import { execSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import path13 from "node:path";
 
@@ -112529,9 +112528,11 @@ ${recent.join("\n")}` : recent.join("\n");
     });
     elements.push({ tag: "hr" });
   }
+  const mentionPrefix = atMentionMarkdown(opts.mentionOpenId);
   const cleanBody = opts.bodyText ? stripLeakedToolMarkup(opts.bodyText) : "";
-  if (cleanBody) {
-    const chunks = chunkMarkdown(cleanBody);
+  const bodyWithMention = [mentionPrefix, cleanBody].filter(Boolean).join("\n\n");
+  if (bodyWithMention) {
+    const chunks = chunkMarkdown(bodyWithMention);
     for (let i = 0; i < chunks.length; i++) {
       elements.push({
         tag: "markdown",
@@ -112573,6 +112574,11 @@ ${chunks[i]}`
   };
   return JSON.stringify(card);
 }
+function atMentionMarkdown(userId) {
+  if (!userId) return "";
+  if (!/^[A-Za-z0-9_:-]+$/.test(userId)) return "";
+  return `<at id=${userId}></at>`;
+}
 var CardHandleImpl = class {
   messageId;
   /** Transport for the leaf PATCH network call (default = lark-cli). */
@@ -112624,6 +112630,7 @@ var CardHandleImpl = class {
       showToolSummary: this.showToolSummary,
       status: cardStatus,
       failureReason: opts.failureReason,
+      mentionOpenId: opts.mentionOpenId,
       // V2 dynamic-choice buttons — agent-declared, only on finalize.
       choices: opts.choices,
       choicePrompt: opts.choicePrompt,
@@ -113353,6 +113360,33 @@ function renderTurnTakingHint(limit) {
     "</turn-taking>"
   ];
 }
+function renderRuntimeWarningsBlock(warnings) {
+  if (warnings.length === 0) return [];
+  const hasMissingLarkCli = warnings.some((warning) => warning.command === "lark-cli");
+  return [
+    "<runtime-warnings>",
+    "Bridge \u68C0\u6D4B\u5230\u4EE5\u4E0B\u672C\u673A\u80FD\u529B\u6682\u4E0D\u53EF\u7528\u3002\u8FD9\u662F\u63D0\u793A,\u4E0D\u662F\u5F3A\u5236\u505C\u6B62\u6761\u4EF6:",
+    ...warnings.map((warning) => {
+      const name = warning.command ? `${warning.label} (${warning.command})` : warning.label;
+      const reason = warning.reason ? `: ${warning.reason}` : "";
+      const installHint = warning.installHint ? ` Fix hint: ${warning.installHint}` : "";
+      return `- ${name}${reason}${installHint}`;
+    }),
+    "",
+    "\u5904\u7406\u539F\u5219:",
+    "- \u80FD\u4EC5\u51ED\u5F53\u524D\u6D88\u606F\u7EE7\u7EED\u7684\u4EFB\u52A1,\u7EE7\u7EED\u5904\u7406,\u4E0D\u8981\u56E0\u4E3A warning \u76F4\u63A5\u62D2\u7EDD\u3002",
+    "- \u53EA\u6709\u5F53\u4EFB\u52A1\u786E\u5B9E\u9700\u8981\u7F3A\u5931\u80FD\u529B\u65F6,\u518D\u5728 last_message \u91CC\u7528\u4EA7\u54C1\u5316\u8BED\u8A00\u544A\u8BC9\u7528\u6237\u7F3A\u4EC0\u4E48\u3001\u4F1A\u5F71\u54CD\u4EC0\u4E48\u3001\u5982\u4F55\u7EE7\u7EED\u3002",
+    ...hasMissingLarkCli ? [
+      "- \u5BF9\u7F3A\u5C11 lark-cli \u7684\u60C5\u51B5:\u4E0D\u8981\u989D\u5916 @ \u7528\u6237;\u5728\u5361\u7247\u91CC\u8F7B\u91CF\u8BF4\u660E\u5F53\u524D\u65E0\u6CD5\u81EA\u52A8\u8BFB\u53D6\u98DE\u4E66\u8BDD\u9898\u5386\u53F2\u3001\u9644\u4EF6\u6216\u6587\u6863\u5373\u53EF\u3002",
+      '- \u5982\u679C\u5F53\u524D\u4EFB\u52A1\u9700\u8981\u8FD9\u4E9B\u4E0A\u4E0B\u6587,\u7528 choices \u95EE\u662F\u5426\u5141\u8BB8\u5B89\u88C5\u6700\u65B0\u7248\u98DE\u4E66 CLI\u3002\u5EFA\u8BAE: `choice_prompt: "\u8BFB\u53D6\u98DE\u4E66\u5386\u53F2\u9700\u8981\u672C\u673A\u5B89\u88C5\u6700\u65B0\u7248\u98DE\u4E66 CLI,\u662F\u5426\u5141\u8BB8\u6211\u5C1D\u8BD5\u5B89\u88C5?"`, `choices: [{label:"\u5141\u8BB8\u5B89\u88C5", value:"\u5141\u8BB8\u5B89\u88C5 lark-cli"}, {label:"\u5148\u4E0D\u5B89\u88C5", value:"\u5148\u4E0D\u5B89\u88C5 lark-cli,\u6211\u4F1A\u628A\u8981\u5904\u7406\u7684\u5185\u5BB9\u8D34\u5230\u8BDD\u9898\u91CC"}]`\u3002',
+      "- \u7528\u6237\u660E\u786E\u9009\u62E9/\u56DE\u590D\u5141\u8BB8\u5B89\u88C5\u540E,\u518D\u5C1D\u8BD5\u5B89\u88C5;\u4E0D\u8981\u5728\u672A\u786E\u8BA4\u524D\u6539\u5BBF\u4E3B\u673A\u5168\u5C40\u73AF\u5883\u3002",
+      "- \u63A8\u8350\u5B89\u88C5\u547D\u4EE4: `npx -y @larksuite/cli@latest install`,\u7136\u540E\u8FD0\u884C `lark-cli --version` \u9A8C\u8BC1\u3002",
+      '- \u5982\u9047 npm \u5168\u5C40\u76EE\u5F55\u6743\u9650\u9519\u8BEF(EACCES/permission denied),\u4F7F\u7528\u7528\u6237\u7EA7 prefix \u540E\u91CD\u8BD5: `mkdir -p ~/.npm-global && npm config set prefix "$HOME/.npm-global" && export PATH="$HOME/.npm-global/bin:$PATH" && npx -y @larksuite/cli@latest install`\u3002\u4E0D\u8981\u9ED8\u8BA4\u8981\u6C42 sudo\u3002',
+      "- \u5B89\u88C5\u6210\u529F\u540E,\u5982\u679C\u672C\u8F6E\u9700\u8981\u7ACB\u5373\u8BFB\u53D6\u98DE\u4E66\u4E0A\u4E0B\u6587,\u53EF\u5728\u5F53\u524D shell \u4E2D\u5E26\u4E0A\u4FEE\u590D\u540E\u7684 PATH \u7EE7\u7EED\u5C1D\u8BD5;\u82E5\u9700\u8981 bridge \u540E\u7EED\u8F6E\u6B21\u7A33\u5B9A\u4F7F\u7528,\u8BF7\u63D0\u793A owner \u91CD\u542F Larkway\u3002"
+    ] : [],
+    "</runtime-warnings>"
+  ];
+}
 function renderWorkspaceBlock(primarySlug, primaryCachePath, defaultBranch, extraRepos) {
   const lines = [
     "<workspace>",
@@ -113423,7 +113457,17 @@ function sceneFacts(parsed, isNewThread) {
   };
 }
 function renderPrompt(input) {
-  const { parsed, isNewThread, conventions, peers, turn_taking_limit, agentMemory, extraRepoPaths, larkCliProfile } = input;
+  const {
+    parsed,
+    isNewThread,
+    conventions,
+    peers,
+    turn_taking_limit,
+    agentMemory,
+    extraRepoPaths,
+    larkCliProfile,
+    runtimeWarnings = []
+  } = input;
   const backend = input.backend ?? "claude";
   const profileFlag = larkCliProfile ? ` --profile ${larkCliProfile}` : "";
   const attachmentKeys = parsed.attachments.map((a) => a.fileKey);
@@ -113436,6 +113480,7 @@ function renderPrompt(input) {
   const stateContract = renderStateContract(conventions.stateFilePath);
   const peersBlock = peers && peers.length > 0 ? renderPeersBlock(peers) : [];
   const turnTakingBlock = turn_taking_limit && turn_taking_limit > 0 ? renderTurnTakingHint(turn_taking_limit) : [];
+  const runtimeWarningsBlock = renderRuntimeWarningsBlock(runtimeWarnings);
   const extraRepos = extraRepoPaths ?? conventions.extraRepoPaths ?? [];
   const workspaceBlock = isAgentWorkspace ? renderAgentWorkspaceBlock(conventions, extraRepos) : hasRepo ? renderWorkspaceBlock(
     conventions.defaultProjectSlug ?? "repo",
@@ -113491,6 +113536,7 @@ function renderPrompt(input) {
       "",
       ...agentMemoryBlock,
       ...skillIntroNew,
+      ...runtimeWarningsBlock.length > 0 ? [...runtimeWarningsBlock, ""] : [],
       "<thread-context>",
       `thread_id:        ${parsed.threadId}`,
       `message_id:       ${parsed.messageId}`,
@@ -113558,6 +113604,7 @@ function renderPrompt(input) {
   return [
     ...agentMemoryBlock,
     ...skillIntroCont,
+    ...runtimeWarningsBlock.length > 0 ? [...runtimeWarningsBlock, ""] : [],
     "<thread-context>",
     `thread_id:        ${parsed.threadId}`,
     `message_id:       ${parsed.messageId}`,
@@ -114441,6 +114488,11 @@ var BridgeHandler = class {
   constructor(deps) {
     this.deps = deps;
   }
+  runtimeWarnings() {
+    return (this.deps.runtimeRequirements ?? []).filter(
+      (req) => !req.ok && (req.severity === "required" || req.kind === "secret")
+    );
+  }
   /**
    * Enter the main loop: for-await over client.events(), per-thread concurrent dispatch.
    *
@@ -114742,7 +114794,8 @@ var BridgeHandler = class {
           botName: this.deps.botConfig?.name,
           backend: this.deps.botConfig?.backend,
           agentMemory: this.deps.agentMemory,
-          larkCliProfile: this.deps.larkCliProfile
+          larkCliProfile: this.deps.larkCliProfile,
+          runtimeWarnings: this.runtimeWarnings()
         });
         const backend = this.deps.botConfig?.backend ?? "claude";
         const permissionMode = this.deps.permissionMode ?? (isAgentWorkspace ? "acceptEdits" : "bypassPermissions");
@@ -117852,6 +117905,14 @@ var GitIdentitySchema = external_exports.object({
   name: external_exports.string().min(1),
   email: external_exports.string().email()
 });
+var GitCloneUrlSchema = external_exports.string().min(1).refine(
+  (value) => {
+    if (/^https?:\/\/\S+$/i.test(value)) return true;
+    if (/^ssh:\/\/\S+$/i.test(value)) return true;
+    return /^[A-Za-z0-9_.-]+@[^:\s]+:[^ \t\r\n]+$/.test(value);
+  },
+  "url must be an http(s), ssh://, or scp-like Git clone URL"
+);
 var BotConfigSchema = external_exports.object({
   /** Unique identifier, kebab-case. Used as key in sessionStore. */
   id: external_exports.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "id must be kebab-case"),
@@ -117926,7 +117987,7 @@ var BotConfigSchema = external_exports.object({
        * Agent workspace runtime: URL is a pointer only; the Agent decides clone
        * timing and destination.
        */
-      url: external_exports.string().url().optional()
+      url: GitCloneUrlSchema.optional()
     })
   ).default([]),
   /**
@@ -118284,12 +118345,12 @@ var SIGKILL_GRACE_MS = 5e3;
 function buildEnv(botGitIdentity, gitlabToken) {
   const env = { ...process.env };
   delete env["ANTHROPIC_API_KEY"];
-  const name = botGitIdentity?.name ?? "larkway-bot";
-  const email = botGitIdentity?.email ?? "bot@larkway.local";
-  env["GIT_AUTHOR_NAME"] = name;
-  env["GIT_AUTHOR_EMAIL"] = email;
-  env["GIT_COMMITTER_NAME"] = name;
-  env["GIT_COMMITTER_EMAIL"] = email;
+  if (botGitIdentity) {
+    env["GIT_AUTHOR_NAME"] = botGitIdentity.name;
+    env["GIT_AUTHOR_EMAIL"] = botGitIdentity.email;
+    env["GIT_COMMITTER_NAME"] = botGitIdentity.name;
+    env["GIT_COMMITTER_EMAIL"] = botGitIdentity.email;
+  }
   if (gitlabToken !== void 0) {
     env["GITLAB_TOKEN"] = gitlabToken;
   }
@@ -118598,12 +118659,12 @@ function buildCodexEnv(botGitIdentity, gitlabToken) {
   const env = { ...process.env };
   delete env["OPENAI_API_KEY"];
   delete env["ANTHROPIC_API_KEY"];
-  const name = botGitIdentity?.name ?? "larkway-bot";
-  const email = botGitIdentity?.email ?? "bot@larkway.local";
-  env["GIT_AUTHOR_NAME"] = name;
-  env["GIT_AUTHOR_EMAIL"] = email;
-  env["GIT_COMMITTER_NAME"] = name;
-  env["GIT_COMMITTER_EMAIL"] = email;
+  if (botGitIdentity) {
+    env["GIT_AUTHOR_NAME"] = botGitIdentity.name;
+    env["GIT_AUTHOR_EMAIL"] = botGitIdentity.email;
+    env["GIT_COMMITTER_NAME"] = botGitIdentity.name;
+    env["GIT_COMMITTER_EMAIL"] = botGitIdentity.email;
+  }
   if (gitlabToken !== void 0) {
     env["GITLAB_TOKEN"] = gitlabToken;
   }
@@ -118989,33 +119050,144 @@ function checkGrantMatchesBot(normalizedGrantText, bot) {
   return { ok: true };
 }
 
-// src/main.ts
-var STATUS_WRITE_INTERVAL_MS = 3e4;
-var VERSION = resolveLarkwayVersion(import.meta.url);
-function checkCli(name) {
+// src/runtimeRequirements.ts
+import { execFileSync } from "node:child_process";
+function checkCli(command) {
   try {
-    const p = execSync(`which ${name}`, { stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
-    if (!p) return { ok: false, version: "" };
-    const version = execSync(`${name} --version`, {
-      stdio: ["pipe", "pipe", "pipe"]
-    }).toString().trim().split("\n")[0] ?? "";
-    return { ok: true, version };
+    execFileSync("which", [command], { stdio: ["pipe", "pipe", "pipe"] });
   } catch {
-    return { ok: false, version: "" };
+    return { ok: false };
   }
+  try {
+    const version = execFileSync(command, ["--version"], { stdio: ["pipe", "pipe", "pipe"] }).toString().trim().split("\n")[0];
+    return { ok: true, ...version ? { version } : {} };
+  } catch {
+    return { ok: true };
+  }
+}
+function repoLooksGitLab(urlOrSlug) {
+  return /(^|[./:@-])gitlab([./:@-]|$)/i.test(urlOrSlug);
 }
-function externalClisForBots(bots) {
-  const backendBins = bots.map((bot) => bot.backend ?? "claude");
-  return Array.from(/* @__PURE__ */ new Set(["lark-cli", ...backendBins, "glab"]));
+function botUsesGitLab(bot) {
+  return bot.repos.some((repo) => repoLooksGitLab(repo.url ?? repo.slug));
 }
+function addCliRequirement(requirements, input) {
+  const existing = requirements.get(`cli:${input.command}`);
+  if (existing) {
+    existing.botIds = Array.from(/* @__PURE__ */ new Set([...existing.botIds, ...input.botIds])).sort();
+    if (existing.severity === "optional" && input.severity === "required") {
+      existing.severity = "required";
+    }
+    return;
+  }
+  const probe = checkCli(input.command);
+  requirements.set(`cli:${input.command}`, {
+    id: `cli:${input.command}`,
+    label: input.label ?? input.command,
+    command: input.command,
+    kind: "cli",
+    severity: input.severity,
+    ok: probe.ok,
+    ...probe.version ? { version: probe.version } : {},
+    reason: input.reason,
+    ...input.installHint ? { installHint: input.installHint } : {},
+    botIds: Array.from(new Set(input.botIds)).sort()
+  });
+}
+function addSecretRequirement(requirements, input) {
+  const id = `secret:${input.envName}`;
+  const existing = requirements.get(id);
+  if (existing) {
+    existing.botIds = Array.from(/* @__PURE__ */ new Set([...existing.botIds, ...input.botIds])).sort();
+    return;
+  }
+  const value = process.env[input.envName];
+  requirements.set(id, {
+    id,
+    label: input.envName,
+    kind: "secret",
+    severity: input.severity ?? "required",
+    ok: value != null && value !== "",
+    reason: input.reason,
+    installHint: `Set ${input.envName} in ~/.larkway/.env and restart Larkway.`,
+    botIds: Array.from(new Set(input.botIds)).sort()
+  });
+}
+function runtimeRequirementsForBots(bots) {
+  const requirements = /* @__PURE__ */ new Map();
+  if (bots.length > 0) {
+    addCliRequirement(requirements, {
+      command: "lark-cli",
+      label: "Feishu CLI",
+      severity: "required",
+      botIds: bots.map((bot) => bot.id),
+      reason: "Required for agents to read Feishu topic history, attachments, docs, and other context.",
+      installHint: "Install and configure lark-cli, then restart Larkway."
+    });
+  }
+  for (const bot of bots) {
+    addCliRequirement(requirements, {
+      command: bot.backend ?? "claude",
+      severity: "required",
+      botIds: [bot.id],
+      reason: `Required to run this bot's ${bot.backend ?? "claude"} backend.`
+    });
+    if (bot.runtime === "agent_workspace" && bot.repos.length > 0) {
+      const tokenEnvName = bot.git_token_env ?? bot.gitlab_token_env;
+      if (tokenEnvName) {
+        addSecretRequirement(requirements, {
+          envName: tokenEnvName,
+          botIds: [bot.id],
+          severity: "optional",
+          reason: "Optional Git identity material. When absent, agents use the host's normal Git auth."
+        });
+      } else {
+        requirements.set(`secret:missing-git-token:${bot.id}`, {
+          id: `secret:missing-git-token:${bot.id}`,
+          label: "Git access token env",
+          kind: "secret",
+          severity: "optional",
+          ok: false,
+          reason: `Bot "${bot.id}" has repo pointers but no git_token_env. It will use the host's normal Git auth.`,
+          installHint: "Add a Git access token only when you want this agent to use a specific GitHub/GitLab identity.",
+          botIds: [bot.id]
+        });
+      }
+    }
+    if (botUsesGitLab(bot)) {
+      addCliRequirement(requirements, {
+        command: "glab",
+        label: "GitLab CLI",
+        severity: "optional",
+        botIds: [bot.id],
+        reason: "Only needed when an agent uses GitLab-specific actions such as MRs, pipelines, or releases.",
+        installHint: "Install glab only for bots that need GitLab-specific workflow commands."
+      });
+    }
+  }
+  return [...requirements.values()].sort((a, b) => {
+    if (a.severity !== b.severity) return a.severity === "required" ? -1 : 1;
+    if (a.kind !== b.kind) return a.kind === "cli" ? -1 : 1;
+    return a.label.localeCompare(b.label);
+  });
+}
+
+// src/main.ts
+var STATUS_WRITE_INTERVAL_MS = 3e4;
+var VERSION = resolveLarkwayVersion(import.meta.url);
 function printExternalCliProbe(bots) {
-  console.log("External CLIs:");
-  for (const name of externalClisForBots(bots)) {
-    const { ok, version } = checkCli(name);
-    if (ok) {
-      console.log(`  ${name.padEnd(10)}  \u2713  ${version}`);
+  console.log("Runtime requirements:");
+  for (const req of runtimeRequirementsForBots(bots)) {
+    const icon = req.ok ? "\u2713" : "\u2717";
+    const tag = req.severity === "optional" ? "optional" : "required";
+    const target = req.command ?? req.label;
+    const botScope = req.botIds.length > 0 ? ` [${req.botIds.join(", ")}]` : "";
+    if (req.ok) {
+      console.log(`  ${target.padEnd(14)} ${icon}  ${req.version ?? tag}${botScope}`);
     } else {
-      console.warn(`  ${name.padEnd(10)}  \u2717  (not found \u2014 install before running bots that use it)`);
+      const message = req.kind === "secret" ? req.reason : `not found \u2014 ${req.reason}`;
+      console.warn(`  ${target.padEnd(14)} ${icon}  (${tag}) ${message}${botScope}`);
+      if (req.installHint) console.warn(`  ${"".padEnd(14)}    ${req.installHint}`);
     }
   }
 }
@@ -119049,18 +119221,16 @@ async function runV2Mode({
     if (bot.runtime === "agent_workspace") {
       const _agentTokenEnvName = bot.git_token_env ?? bot.gitlab_token_env;
       if (bot.repos.length > 0 && !_agentTokenEnvName) {
-        console.error(
-          `[larkway] SKIPPING bot "${bot.id}": runtime=agent_workspace has repo pointers but no git_token_env (or gitlab_token_env). v0.3 workspace repo bots must reference an explicit per-agent token env name; they do not inherit global GITLAB_TOKEN.`
+        console.warn(
+          `[larkway] bot "${bot.id}": runtime=agent_workspace has repo pointers but no git_token_env. Starting anyway; the agent will use the host's normal Git identity/auth.`
         );
-        continue;
       }
       if (_agentTokenEnvName) {
         const agentToken = process.env[_agentTokenEnvName];
         if (agentToken == null || agentToken === "") {
-          console.error(
-            `[larkway] SKIPPING bot "${bot.id}": runtime=agent_workspace declares token env "${_agentTokenEnvName}", but that env var is unset/empty. Set the real token in ~/.larkway/.env; v0.3 workspace bots do not fall back to global GITLAB_TOKEN.`
+          console.warn(
+            `[larkway] bot "${bot.id}": runtime=agent_workspace declares token env "${_agentTokenEnvName}", but that env var is unset/empty. Starting anyway; the agent will use the host's normal Git identity/auth.`
           );
-          continue;
         }
       }
       const permissionGate = await checkWorkspacePermissionGrant(resolveAgentWorkspacePath(bot.id), bot);
@@ -119091,7 +119261,7 @@ async function runV2Mode({
     const gitlabToken = tokenEnvName != null ? process.env[tokenEnvName] : void 0;
     if (tokenEnvName != null && (gitlabToken == null || gitlabToken === "")) {
       console.warn(
-        `[larkway] bot "${bot.id}" declares token env "${tokenEnvName}" but that env var is unset/empty \u2014 falling back to global GITLAB_TOKEN.`
+        `[larkway] bot "${bot.id}" declares token env "${tokenEnvName}" but that env var is unset/empty \u2014 leaving the host Git auth environment unchanged.`
       );
     }
     const larkCliProfile = deriveLarkCliProfile(bot.lark_cli_profile, bot.app_id);
@@ -119162,7 +119332,7 @@ async function runV2Mode({
       readOnly: bot.read_only,
       gitlabTokenEnvName: tokenEnvName
     };
-    const effectiveGitlabToken = bot.runtime === "agent_workspace" ? gitlabToken ?? "" : gitlabToken;
+    const effectiveGitlabToken = gitlabToken;
     const resolvedPeers = bot.peers.flatMap((peerId) => {
       const peer = bots.find((b) => b.id === peerId);
       if (!peer) return [];
@@ -119189,6 +119359,7 @@ async function runV2Mode({
       gitlabToken: effectiveGitlabToken,
       agentMemory: bot.agent_memory,
       larkCliProfile,
+      runtimeRequirements: runtimeRequirementsForBots([bot]),
       recordRuntimeEvent: async (patch) => {
         await upsertRuntimeEvent(larkwayHome(), bot.id, patch);
       }

package/dist/web/public/app.js

@@ -377,6 +377,8 @@ const state = {
   selected: null,
   /** Bridge 进程状态(来自 GET /api/bridge;null = 未知)。 */
   bridge: /** @type {{running:boolean,pid:number|null,platform:string,mode:string}|null} */ (null),
+  /** Runtime requirement diagnostics from GET /api/runtime/requirements. */
+  requirements: /** @type {{requirements:Array<any>,missingRequired:Array<any>,missingOptional:Array<any>}|null} */ (null),
   /**
    * 每个 bot 的实时在线状态(来自 GET /api/status 的 bots[]),按 id 索引。
    * "serving"=🟢正常服务中 / "degraded"=🟡连接异常 / "offline"=🔴未运行掉线 / null=状态未知。
@@ -867,6 +869,34 @@ function effLive(id) {
   return bridgeRunning ? botLiveness(id) : "offline";
 }
 
+function missingRequiredForBot(id) {
+  const missing = state.requirements?.missingRequired;
+  if (!Array.isArray(missing)) return [];
+  return missing.filter((req) => Array.isArray(req.botIds) && req.botIds.includes(id));
+}
+
+function missingRequiredAll() {
+  return Array.isArray(state.requirements?.missingRequired) ? state.requirements.missingRequired : [];
+}
+
+function requirementShortLabel(req) {
+  if (!req) return "运行依赖";
+  if (req.command === "lark-cli") return "飞书 CLI";
+  if (req.kind === "secret") return req.label === "Git access token env" ? "Git 访问令牌" : req.label;
+  return req.label || req.command || "运行依赖";
+}
+
+function requirementInstallText(req) {
+  if (!req) return "";
+  if (req.command === "lark-cli") return "安装并配置 lark-cli 后重启服务。";
+  if (req.kind === "secret") return req.installHint || "在看板里粘贴 Git access token，或补齐 bot yaml 的 git_token_env。";
+  return req.installHint || "安装缺失的 CLI 后重启服务。";
+}
+
+function primaryMissingForBot(id) {
+  return missingRequiredForBot(id)[0] ?? null;
+}
+
 /**
  * pendingNew:bridge 在跑且存在从未上报过 status 的 bot(unknown liveness)的数量。
  * 对应 LkServiceIndicator pendingNew prop。
@@ -988,6 +1018,8 @@ function buildStatusActionPanel(liveKey, busyAction = null, moreOpen = false) {
   };
 
   const primaryBusy = busyAction === fx.primary.action;
+  const heading = fx.heading;
+  const say = fx.say;
 
   // Build "more" section for degraded
   let moreSection = "";
@@ -1045,8 +1077,8 @@ function buildStatusActionPanel(liveKey, busyAction = null, moreOpen = false) {
     iconSvg + `</span>` +
     `<div style="min-width:0;flex:1">` +
     `<div style="font-size:12.5px;font-weight:700;letter-spacing:.04em;color:${sc.text};margin-bottom:4px">` +
-    esc(fx.heading) + `</div>` +
-    `<p style="margin:0;font-size:14px;line-height:1.55;color:#334155">${esc(fx.say)}</p>` +
+    esc(heading) + `</div>` +
+    `<p style="margin:0;font-size:14px;line-height:1.55;color:#334155">${esc(say)}</p>` +
     `<div style="display:flex;gap:10px;flex-wrap:wrap;margin-top:13px;align-items:center">` +
     fixBtnPrimary(primaryBusy) +
     (fx.secondary ? fixBtnSecondary(fx.secondary) : "") +
@@ -2295,37 +2327,44 @@ function normalizeRepos(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.map((r) => {
     if (typeof r === "string") {
-      const [slug, branch = "master"] = r.split(":").map((s) => s.trim());
+      const [slug, branch = "main"] = r.split(":").map((s) => s.trim());
       return { slug, branch, url: "" };
     }
-    return { slug: r.slug ?? "", branch: r.branch ?? "master", url: r.url ?? "" };
+    return { slug: r.slug ?? "", branch: r.branch ?? "main", url: r.url ?? "" };
   });
 }
 
+function inferRepoSlugFromUrl(url) {
+  const text = String(url ?? "").trim();
+  if (!text) return "";
+  const stripGit = (s) => s.replace(/\.git$/i, "").replace(/^\/+|\/+$/g, "");
+
+  const scp = /^[A-Za-z0-9_.-]+@[^:\s]+:(.+)$/.exec(text);
+  if (scp) return stripGit(scp[1] ?? "");
+
+  try {
+    const parsed = new URL(text);
+    return stripGit(parsed.pathname);
+  } catch {
+    return "";
+  }
+}
+
 /**
- * 生成一个仓库行的 HTML(可读 / 可删)。
+ * 生成一个仓库行的 HTML。UI 只暴露 Git 地址;slug/branch 都是内部细节。
  * @param {number} idx
  * @param {{slug:string,branch:string,url:string}} repo
  */
 function acRepoRowHTML(idx, repo) {
   const xIcon = `<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg>`;
+  const displayUrl = repo.url || "";
   return (
     `<div class="ac-repo-row" data-repo-idx="${idx}">` +
-    `<div class="ac-repo-grid">` +
     `<div class="ac-field">` +
-    `<label class="ac-label" for="ac-repo-slug-${idx}">组 / 项目</label>` +
-    `<input id="ac-repo-slug-${idx}" class="ac-input ac-mono" type="text" placeholder="chuckwu0/larkway" spellcheck="false" data-repo="slug" data-repo-idx="${idx}" value="${esc(repo.slug)}" />` +
-    `</div>` +
-    `<div class="ac-field">` +
-    `<label class="ac-label" for="ac-repo-branch-${idx}">分支</label>` +
-    `<input id="ac-repo-branch-${idx}" class="ac-input ac-mono" type="text" placeholder="main" spellcheck="false" data-repo="branch" data-repo-idx="${idx}" value="${esc(repo.branch)}" />` +
-    `</div>` +
-    `</div>` +
-    `<div class="ac-field" style="margin-top:8px">` +
-    `<label class="ac-label" for="ac-repo-url-${idx}">clone 地址 <span class="ac-optional">私有库必需</span></label>` +
-    `<input id="ac-repo-url-${idx}" class="ac-input ac-mono" type="text" placeholder="git@github.com:org/repo.git" spellcheck="false" data-repo="url" data-repo-idx="${idx}" value="${esc(repo.url)}" />` +
+    `<label class="ac-label" for="ac-repo-url-${idx}">仓库 Git 地址 <span class="ac-required">必填</span></label>` +
+    `<input id="ac-repo-url-${idx}" class="ac-input ac-mono" type="text" placeholder="git@github.com:org/repo.git" spellcheck="false" data-repo="url" data-repo-idx="${idx}" value="${esc(displayUrl)}" />` +
     `</div>` +
-    `<button type="button" class="ac-repo-del" title="移除这个仓库" data-repo-idx="${idx}" aria-label="移除仓库 ${esc(repo.slug || idx + 1)}">` +
+    `<button type="button" class="ac-repo-del" title="移除这个仓库" data-repo-idx="${idx}" aria-label="移除仓库 ${esc(repo.slug || repo.url || idx + 1)}">` +
     xIcon +
     `</button>` +
     `</div>`
@@ -2367,7 +2406,8 @@ function buildAgentConfigHTML(bot, memContent, mode, prefill) {
   // 层二 summary 药丸(收起态)
   const permSummaryHTML = codeAccess
     ? acPillHTML("brand", "m16 18 6-6-6-6M8 6l-6 6 6 6", "可访问代码仓库") +
-      acPillHTML("muted", "M21 8 12 3 3 8v8l9 5 9-5ZM3 8l9 5 9-5M12 13v8", repos.length ? `预热 ${repos.length} 个仓库` : "agent 自己 clone")
+      acPillHTML("muted", "M21 8 12 3 3 8v8l9 5 9-5ZM3 8l9 5 9-5M12 13v8", repos.length ? `${repos.length} 个仓库` : "待添加仓库") +
+      acPillHTML("muted", "M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4", gitlabConfigured ? "Agent 级 Git 身份" : "沿用本机 Git 身份")
     : acPillHTML("muted", "M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4", "纯对话 · 不碰任何代码仓库");
 
   // 层三 summary 药丸
@@ -2450,7 +2490,7 @@ function buildAgentConfigHTML(bot, memContent, mode, prefill) {
     `<div class="ac-access-toggle-row${codeAccess ? " is-on" : ""}" id="ac-access-row">` +
     `<div class="ac-access-info">` +
     `<div class="ac-access-title">给它访问代码仓库的权限</div>` +
-    `<p class="ac-access-desc">通过配一个 <b>Git 访问令牌</b> 来表达。读和改都用这一个令牌 —— <b>没有读 / 写之分</b>，agent 看任务自己定。不开 = 纯对话 / 自带知识答疑。</p>` +
+    `<p class="ac-access-desc">打开后给这个 Agent 配一组仓库地址；它只有这些 repo 作为默认工作范围。Git 身份是 Agent 级的：不填就沿用这台机器现有的 SSH key、credential helper 或环境变量。</p>` +
     `</div>` +
     `<button type="button" class="ac-toggle${codeAccess ? " is-on" : ""}" id="ac-code-access-btn" role="switch" aria-checked="${codeAccess}" title="开 / 关代码访问权限">` +
     `<span class="ac-toggle-thumb"></span>` +
@@ -2461,40 +2501,43 @@ function buildAgentConfigHTML(bot, memContent, mode, prefill) {
     `<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" style="flex-shrink:0;color:var(--faint)"><path d="M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4"/></svg>` +
     `当前这个 agent 不访问任何代码仓库。需要它读 / 改代码时，再打开上面的开关。` +
     `</div>` +
-    // 开启态:令牌 + 仓库
+    // 开启态:仓库 + Agent 级 Git 身份
     `<div class="ac-access-fields" id="ac-access-fields" ${codeAccess ? "" : 'style="display:none"'}>` +
+    // 仓库列表
+    `<div class="ac-repos-section">` +
+    `<div class="ac-repos-header">` +
+    `<span class="ac-repos-title">这个 Agent 可碰的仓库</span>` +
+    `<span class="ac-optional-badge">可多个</span>` +
+    `</div>` +
+    `<p class="ac-hint">每行只填 clone 地址。分支默认 main；同一个 Agent 的所有仓库共用下面的 Git 身份。</p>` +
+    `<div class="ac-repos-empty" id="ac-repos-empty" ${repos.length ? 'style="display:none"' : ""}><svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" style="flex-shrink:0"><path d="M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3Z"/></svg>还没有仓库。需要访问代码时，请添加仓库 Git 地址。</div>` +
+    `<div class="ac-repos-list" id="ac-repos-list" ${repos.length ? "" : 'style="display:none"'}>${repos.map((r, i) => acRepoRowHTML(i, r)).join("")}</div>` +
+    `<button type="button" class="ac-add-repo-btn" id="ac-add-repo-btn">` +
+    `<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>` +
+    ` 添加仓库` +
+    `</button>` +
+    `</div>` + // ac-repos-section
+    `<details class="ac-token-advanced">` +
+    `<summary>Git 身份 <span>可选，作用于上面所有仓库</span></summary>` +
     `<div class="ac-field">` +
-    `<label class="ac-label" for="ac-gitlab-token">Git Access Token</label>` +
-    `<p class="ac-hint">把 Git access token 粘这里。只存本机 <code>~/.larkway/.env</code>（权限 0600），不回显、不外发。</p>` +
+    `<label class="ac-label" for="ac-gitlab-token">Agent 级 Git Access Token <span class="ac-optional">可选</span></label>` +
+    `<p class="ac-hint">只配置一个，供这个 Agent 的所有仓库使用。GitHub fine-grained PAT 可以在 GitHub 里只勾选这些仓库；这里只保存 token 真值到本机 <code>~/.larkway/.env</code>（权限 0600），页面不回显。</p>` +
     (gitlabConfigured
       ? `<div class="ac-token-configured" id="ac-token-configured">` +
-        `<span class="ac-token-mask">${ICONS.lock} 已配置 <span style="letter-spacing:.12em">••••••</span></span>` +
+        `<span class="ac-token-mask">${ICONS.lock} 已配置此 Agent 的 Git 身份 <span style="letter-spacing:.12em">••••••</span></span>` +
         `<button type="button" class="btn btn-sm ac-token-reset-btn" id="ac-token-reset-btn">重新设置</button>` +
         `</div>` +
         `<div class="ac-secret-wrap" id="ac-token-input-wrap" style="display:none">` +
         `<svg class="ac-secret-icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4"/></svg>` +
-        `<input id="ac-gitlab-token" name="gitlab_token_value" class="ac-input ac-secret-input" type="password" autocomplete="new-password" placeholder="粘贴新 token（只存本机，不回显）" value="" />` +
+        `<input id="ac-gitlab-token" name="gitlab_token_value" class="ac-input ac-secret-input" type="password" autocomplete="new-password" placeholder="粘贴新的 Agent 级 token" value="" />` +
         `</div>`
       : `<div class="ac-secret-wrap" id="ac-token-input-wrap">` +
         `<svg class="ac-secret-icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4"/></svg>` +
-        `<input id="ac-gitlab-token" name="gitlab_token_value" class="ac-input ac-secret-input" type="password" autocomplete="new-password" placeholder="粘贴 Git access token（只存本机，不回显）" value="" />` +
+        `<input id="ac-gitlab-token" name="gitlab_token_value" class="ac-input ac-secret-input" type="password" autocomplete="new-password" placeholder="可留空，或粘贴 Agent 级 token" value="" />` +
         `</div>`
     ) +
     `</div>` +
-    // 仓库列表
-    `<div class="ac-repos-section">` +
-    `<div class="ac-repos-header">` +
-    `<span class="ac-repos-title">预热这些仓库</span>` +
-    `<span class="ac-optional-badge">可选</span>` +
-    `</div>` +
-    `<p class="ac-hint">列出主要会用到的仓库 → 我们提前 clone 好，agent 一上来就有，提速。<b>留空也行</b> —— agent 会用上面的令牌自己判断需要哪些、自己 clone。</p>` +
-    `<div class="ac-repos-empty" id="ac-repos-empty" ${repos.length ? 'style="display:none"' : ""}><svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" style="flex-shrink:0"><path d="M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3Z"/></svg>未列仓库 —— agent 会用令牌自己理解需要哪些、自己 clone。</div>` +
-    `<div class="ac-repos-list" id="ac-repos-list" ${repos.length ? "" : 'style="display:none"'}>${repos.map((r, i) => acRepoRowHTML(i, r)).join("")}</div>` +
-    `<button type="button" class="ac-add-repo-btn" id="ac-add-repo-btn">` +
-    `<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>` +
-    ` 添加仓库` +
-    `</button>` +
-    `</div>` + // ac-repos-section
+    `</details>` +
     `</div>` + // ac-access-fields
     `</div>` + // ac-perm-body
     `</section>` +
@@ -2652,17 +2695,9 @@ function wireAgentConfigEvents(panel, id, bot) {
     if (accessRow) accessRow.classList.toggle("is-on", on);
     if (noAccessHint) noAccessHint.style.display = on ? "none" : "";
     if (accessFields) accessFields.style.display = on ? "" : "none";
-    // 关 → 清令牌 + 仓库
-    if (!on) {
-      if (gitlabInput) gitlabInput.value = "";
-      // 隐藏密码框,重置 tokenReset 标记(关闭等于「清除」)
-      const configured = ac.querySelector("#ac-token-configured");
-      const inputWrap = ac.querySelector("#ac-token-input-wrap");
-      if (configured) configured.style.display = "none";
-      if (inputWrap) { inputWrap.style.display = ""; } // 关闭态直接露空框,保存时会带 ""
-      delete ac.dataset.tokenReset;
-      acClearRepos(ac);
-    }
+    // 关掉代码访问只改变本次保存的序列化结果,不立即清空表单里的仓库行。
+    // 这样用户误点开关后再打开,未保存的仓库地址还在。
+    if (!on && gitlabInput) gitlabInput.value = "";
     // open 徽标
     if (permLayerTitleRow) {
       let badge = permLayerTitleRow.querySelector(".ac-open-badge");
@@ -2770,11 +2805,10 @@ function readAgentConfigValues(panel) {
   if (codeAccess) {
     const repoRows = ac.querySelectorAll(".ac-repo-row");
     for (const row of repoRows) {
-      const slug   = (row.querySelector("[data-repo='slug']")?.value ?? "").trim();
-      const branch = (row.querySelector("[data-repo='branch']")?.value ?? "").trim() || "master";
-      const url    = (row.querySelector("[data-repo='url']")?.value ?? "").trim();
-      if (slug) {
-        const r = { slug, branch };
+      const url = (row.querySelector("[data-repo='url']")?.value ?? "").trim();
+      const inferredSlug = inferRepoSlugFromUrl(url);
+      if (inferredSlug || url) {
+        const r = { slug: inferredSlug, branch: "main" };
         if (url) r.url = url;
         repos.push(r);
       }
@@ -2803,12 +2837,46 @@ function readAgentConfigValues(panel) {
 
 function acGetRepos(ac) {
   const rows = ac.querySelectorAll(".ac-repo-row");
-  return Array.from(rows).map((row) => ({
-    slug:   (row.querySelector("[data-repo='slug']")?.value ?? "").trim(),
-    branch: (row.querySelector("[data-repo='branch']")?.value ?? "").trim() || "master",
-    url:    (row.querySelector("[data-repo='url']")?.value ?? "").trim(),
-    _idx:   parseInt(row.dataset.repoIdx ?? "-1", 10),
-  }));
+  return Array.from(rows).map((row) => {
+    const url = (row.querySelector("[data-repo='url']")?.value ?? "").trim();
+    return {
+      slug: inferRepoSlugFromUrl(url),
+      branch: "main",
+      url,
+      _idx: parseInt(row.dataset.repoIdx ?? "-1", 10),
+    };
+  });
+}
+
+function validateCodeAccessConfig(panel) {
+  const ac = panel?.querySelector?.("#ac-panel") ?? panel;
+  if (!ac) return true;
+  const codeAccessBtn = ac.querySelector("#ac-code-access-btn");
+  const codeAccess = codeAccessBtn?.getAttribute("aria-checked") === "true";
+  if (!codeAccess) return true;
+
+  const repos = acGetRepos(ac);
+  if (repos.length === 0) {
+    toast("已打开代码访问，请至少添加一个仓库。", "warn");
+    ac.querySelector("#ac-add-repo-btn")?.focus();
+    return false;
+  }
+
+  for (const repo of repos) {
+    const row = ac.querySelector(`.ac-repo-row[data-repo-idx="${repo._idx}"]`);
+    const urlInput = row?.querySelector("[data-repo='url']");
+    if (!repo.url) {
+      toast("请填写代码仓库 Git 地址。Git Access Token 是选填。", "warn");
+      urlInput?.focus();
+      return false;
+    }
+    if (!repo.slug) {
+      toast("无法从 Git 地址识别仓库，请检查地址格式。", "warn");
+      urlInput?.focus();
+      return false;
+    }
+  }
+  return true;
 }
 
 function acRebuildRepoRows(ac) {
@@ -2836,8 +2904,7 @@ function acAddRepo(ac) {
   list.appendChild(tmp.firstElementChild);
   list.style.display = "";
   if (empty) empty.style.display = "none";
-  // 聚焦新行 slug 输入
-  list.querySelector(`#ac-repo-slug-${newIdx}`)?.focus();
+  list.querySelector(`#ac-repo-url-${newIdx}`)?.focus();
   acUpdatePermSummary(ac);
   ac.dispatchEvent(new Event("ac-change", { bubbles: true }));
 }
@@ -2855,14 +2922,6 @@ function acRemoveRepo(ac, idx) {
   ac.dispatchEvent(new Event("ac-change", { bubbles: true }));
 }
 
-function acClearRepos(ac) {
-  const list = ac.querySelector("#ac-repos-list");
-  const empty = ac.querySelector("#ac-repos-empty");
-  if (list) { list.innerHTML = ""; list.style.display = "none"; }
-  if (empty) empty.style.display = "";
-  acUpdatePermSummary(ac);
-}
-
 // ── summary 药丸实时更新 ─────────────────────────────────────────────────────
 
 function acUpdatePermSummary(ac) {
@@ -2874,11 +2933,19 @@ function acUpdatePermSummary(ac) {
   const repoCount = ac.querySelectorAll(".ac-repo-row").length;
   const html = codeAccess
     ? acPillHTML("brand", "m16 18 6-6-6-6M8 6l-6 6 6 6", "可访问代码仓库") +
-      acPillHTML("muted", "M21 8 12 3 3 8v8l9 5 9-5ZM3 8l9 5 9-5M12 13v8", repoCount ? `预热 ${repoCount} 个仓库` : "agent 自己 clone")
+      acPillHTML("muted", "M21 8 12 3 3 8v8l9 5 9-5ZM3 8l9 5 9-5M12 13v8", repoCount ? `${repoCount} 个仓库` : "待添加仓库") +
+      acPillHTML("muted", "M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4", acHasAgentGitIdentity(ac) ? "Agent 级 Git 身份" : "沿用本机 Git 身份")
     : acPillHTML("muted", "M5 11h14a1 1 0 0 1 1 1v7a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1ZM8 11V7a4 4 0 0 1 8 0v4", "纯对话 · 不碰任何代码仓库");
   summaryEl.innerHTML = html;
 }
 
+function acHasAgentGitIdentity(ac) {
+  const typedValue = ac.querySelector("#ac-gitlab-token")?.value ?? "";
+  if (typedValue.trim()) return true;
+  const configuredEl = ac.querySelector("#ac-token-configured");
+  return !!(configuredEl && configuredEl.style.display !== "none");
+}
+
 function acUpdateAdvSummary(ac) {
   const summaryEl = ac.querySelector("#ac-adv-summary");
   if (!summaryEl) return;
@@ -3400,7 +3467,7 @@ function readFormValues(form) {
     .map((s) => s.trim())
     .filter(Boolean)
     .map((line) => {
-      const [slug, branch = "master"] = line.split(":").map((p) => p.trim());
+      const [slug, branch = "main"] = line.split(":").map((p) => p.trim());
       return { slug, branch };
     });
   const peers = peersRaw
@@ -3504,6 +3571,8 @@ async function saveMemory(panel, id) {
  * memory 随「保存」一起提交。序列化字段见 readAgentConfigValues。
  */
 async function saveAcBot(panel, id) {
+  if (!validateCodeAccessConfig(panel)) return;
+
   const vals = readAgentConfigValues(panel);
   const memContent = vals._memContent ?? "";
 
@@ -3602,22 +3671,10 @@ function renderServiceIndicator() {
         icon + label +
         `</button>`;
 
-  if (!running) {
-    // running=false → 红报警条(+ indigo 启动按钮,只读时省略)
-    container.innerHTML =
-      `<div class="lk-svc-indicator lk-svc-indicator--offline">` +
-      `<span class="lk-svc-label">` +
-      `<span class="bridge-dot is-stopped" style="margin-right:6px"></span>` +
-      `服务未运行` +
-      `<span class="lk-svc-sublabel"> · 助手都不会回复</span>` +
-      `</span>` +
-      svcBtn("btn-svc-start", "#fecaca", ICONS.zap, "启动服务", "start") +
-      `</div>`;
-    container.querySelector("#btn-svc-start")?.addEventListener("click", () => doFixAction("start"));
-    return;
-  }
-
-  // ── BL-18:重启过渡态 ─────────────────────────
+  // ── BL-18:启动/重启过渡态 ─────────────────────
+  // Must run before the `!running` branch: after clicking "启动服务", the
+  // backend has accepted the start but detectBridgeStatus may still report
+  // running=false for a few seconds while bridge boots and bots reconnect.
   if (!readonly) {
     const rs = state.restart;
 
@@ -3664,6 +3721,21 @@ function renderServiceIndicator() {
     }
   }
 
+  if (!running) {
+    // running=false → 红报警条(+ indigo 启动按钮,只读时省略)
+    container.innerHTML =
+      `<div class="lk-svc-indicator lk-svc-indicator--offline">` +
+      `<span class="lk-svc-label">` +
+      `<span class="bridge-dot is-stopped" style="margin-right:6px"></span>` +
+      `服务未运行` +
+      `<span class="lk-svc-sublabel"> · 助手都不会回复</span>` +
+      `</span>` +
+      svcBtn("btn-svc-start", "#fecaca", ICONS.zap, "启动服务", "start") +
+      `</div>`;
+    container.querySelector("#btn-svc-start")?.addEventListener("click", () => doFixAction("start"));
+    return;
+  }
+
   // 综合 pendingRestart(后端感知新增/已删)与本地 pendingNewCount(客户端推算)
   // 后端字段更权威;本地计算作回退(后端未返回时)。
   const pr = state.pendingRestart;
@@ -3781,29 +3853,33 @@ async function doFixAction(action, triggerEl = null) {
     const errMsg = res.json?.message ?? res.json?.error ?? res.status;
     toast(`操作失败：${errMsg}`, "error");
     // Refresh status even on failure
+    await refreshRuntimeRequirements();
     await refreshBridgeStatus();
     await pollStatus();
     if (state.selected) rerenderStatusAction(state.selected);
     return;
   }
 
-  // ── BL-18:POST 成功后 → 进入 restarting 过渡态(仅 restart 动作) ─────────
-  if (action === "restart") {
-    // 重置任何旧的机器状态,进入 restarting
-    stopRestartTicker();
-    state.restart = { status: "restarting", startedAt: Date.now(), elapsed: 0 };
-    toast("正在重启服务 —— 好了会自动转回正常,不用重复点", "info");
-    // 全量刷新三触点(顶栏+名册+hero)
-    renderServiceIndicator();
-    renderBotList();
-    if (state.selected) refreshDetailHero();
-    // 启动 1s ticker 刷新已用时显示
-    startRestartTicker();
-  } else {
-    toast("服务已启动", "ok");
-  }
+  // ── BL-18:POST 成功后 → 进入 restarting 过渡态(start/restart 都走同一套) ──
+  // "启动服务" 和 "重启服务" 都调用同一个后端 restart endpoint。返回成功只
+  // 代表 supervisor 已接受请求,不代表 bridge 已连回飞书或 bot 已写心跳。
+  stopRestartTicker();
+  state.restart = { status: "restarting", startedAt: Date.now(), elapsed: 0 };
+  toast(
+    action === "start"
+      ? "正在启动服务 —— 连上后会自动转回正常,不用重复点"
+      : "正在重启服务 —— 好了会自动转回正常,不用重复点",
+    "info",
+  );
+  // 全量刷新三触点(顶栏+名册+hero)
+  renderServiceIndicator();
+  renderBotList();
+  if (state.selected) refreshDetailHero();
+  // 启动 1s ticker 刷新已用时显示
+  startRestartTicker();
 
   // Refresh bridge + liveness
+  await refreshRuntimeRequirements();
   await refreshBridgeStatus();
   await pollStatus();
   if (state.selected) rerenderStatusAction(state.selected);
@@ -3819,6 +3895,7 @@ async function doFixAction(action, triggerEl = null) {
   const BURST_INTERVAL = 2000;
   _restartPollHandle = setInterval(async () => {
     burstCount++;
+    await refreshRuntimeRequirements();
     await refreshBridgeStatus();
     await pollStatus();
     if (state.selected) rerenderStatusAction(state.selected);
@@ -4326,6 +4403,7 @@ function renderOnboardNameForm(prefill, sessionId) {
 async function submitOnboardName(prefill, sessionId, modal) {
   if (!modal) modal = document.getElementById("onboard-modal");
   const sid = sessionId ?? onboard.sessionId;
+  if (!validateCodeAccessConfig(modal)) return;
 
   // 从 AC 面板读取表单值
   const vals = readAgentConfigValues(modal);
@@ -4553,6 +4631,7 @@ async function boot() {
 
   // 拉 bot 列表(先于首次状态轮询,确保左侧条目存在好让圆点落上去)
   await loadBots();
+  await refreshRuntimeRequirements();
 
   // 拉 bridge 服务状态并渲染顶栏指示
   await refreshBridgeStatus();
@@ -4560,6 +4639,7 @@ async function boot() {
   // 首次拉状态 + 每 15s 轮询(实时在线状态可视化)
   await pollStatus();
   setInterval(pollStatus, 15000);
+  setInterval(refreshRuntimeRequirements, 30000);
 }
 
 /**
@@ -4571,4 +4651,11 @@ async function pollStatus() {
   renderStatus(res.ok ? res.json : null);
 }
 
+async function refreshRuntimeRequirements() {
+  const res = await api("GET", "/api/runtime/requirements");
+  state.requirements = res.ok ? res.json : null;
+  renderServiceIndicator();
+  if (state.selected) rerenderStatusAction(state.selected);
+}
+
 boot();

package/dist/web/public/style.css

@@ -3266,18 +3266,12 @@ textarea.input {
 .ac-repo-row {
   position: relative;
   padding: 13px 14px;
+  padding-right: 52px;
   border-radius: 11px;
   border: 1px solid var(--border);
   background: #fff;
 }
 
-.ac-repo-grid {
-  display: grid;
-  grid-template-columns: 1fr 120px;
-  gap: 10px;
-  margin-bottom: 10px;
-}
-
 .ac-repo-del {
   position: absolute;
   top: 11px;
@@ -3358,6 +3352,39 @@ textarea.input {
   gap: 16px;
 }
 
+.ac-token-advanced {
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: #fff;
+  padding: 0;
+}
+
+.ac-token-advanced > summary {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 11px 13px;
+  cursor: pointer;
+  list-style: none;
+  font-size: 13.5px;
+  font-weight: 700;
+  color: var(--text);
+}
+
+.ac-token-advanced > summary::-webkit-details-marker {
+  display: none;
+}
+
+.ac-token-advanced > summary span {
+  font-size: 12.5px;
+  font-weight: 500;
+  color: var(--muted);
+}
+
+.ac-token-advanced > .ac-field {
+  padding: 0 13px 13px;
+}
+
 /* ── 保存栏(edit 模式 sticky,复用 .form-actions-sticky 的 sticky + gradient) ── */
 .ac-save-bar {
   display: flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkway",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Thin bridge: Feishu thread to local Claude Code CLI",
   "license": "MIT",
   "author": "Chuck Wu (chuckwu0)",