larkit 0.0.0-stage → 0.1.1

package/scripts/verify-index.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import "../src/shared/quiet.js";
+import process from "node:process";
+import { searchTruth, getProtocolEntry, readSlice, truthStats } from "../src/truth/search.js";
+import { TRUTH_DB, FORMATTED_DIR } from "../src/shared/paths.js";
+
+const queries = process.argv.slice(2).filter((x) => !x.startsWith("--"));
+const list = queries.length
+  ? queries
+  : ["chart_spec", "card_link", "PUT_MESSAGE", "PUSH_MESSAGES"];
+
+let failed = 0;
+const stats = truthStats();
+console.log(JSON.stringify({ truth_db: TRUTH_DB, formatted_dir: FORMATTED_DIR, stats }, null, 2));
+
+for (const query of list) {
+  const result = searchTruth({ query, scope: "all", limit: 5 });
+  const ok = result.results.length > 0;
+  const fast = result.elapsed_ms < 50;
+  if (!ok || !fast) failed++;
+  console.log(
+    `\n${ok ? "PASS" : "FAIL"} ${fast ? "fast" : "SLOW"} ${result.elapsed_ms}ms  query=${JSON.stringify(query)}  hits=${result.results.length}`,
+  );
+  for (const hit of result.results.slice(0, 3)) {
+    if (hit.kind === "protocol") {
+      console.log(
+        `  protocol cmd=${hit.cmd} ${hit.name} ${hit.request_type || ""} schema=${(hit.schema || "").slice(0, 100)}`,
+      );
+    } else {
+      console.log(
+        `  ${hit.kind} ${hit.file_path}:${hit.line_number ?? hit.line_start} ${hit.anchor_type || hit.section || hit.title || ""} ${(hit.literal || "").slice(0, 90)}`,
+      );
+    }
+  }
+  if (query === list[0]) {
+    const first = result.results[0];
+    if (first && !first.kind.includes("protocol")) {
+      const slice = readSlice({
+        filePath: first.file_path,
+        lineNumber: first.line_number || first.line_start || 1,
+        context: 3,
+        maxLines: 12,
+      });
+      console.log(
+        `  slice ${slice.file_path}:${slice.range.start}-${slice.range.end} (${slice.lines.length} lines)`,
+      );
+    }
+  }
+}
+
+const protocol = getProtocolEntry("PUT_MESSAGE");
+console.log(`\nprotocol lookup PUT_MESSAGE: ${protocol.length} entr${protocol.length === 1 ? "y" : "ies"}`);
+if (!protocol.length) failed++;
+
+if (failed) {
+  console.error(`\n${failed} verification check(s) failed`);
+  process.exit(1);
+}
+console.log("\nall index checks passed");

package/scripts/verify-mcp.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import "../src/shared/quiet.js";
+import { spawn } from "node:child_process";
+import process from "node:process";
+
+const child = spawn(process.execPath, ["bin/larkit-mcp.js"], {
+  cwd: process.cwd(),
+  stdio: ["pipe", "pipe", "pipe"],
+  env: { ...process.env, LARKIT_MCP_TEST: "1" },
+});
+
+let buffer = "";
+const pending = new Map();
+let nextId = 1;
+let stderr = "";
+const received = [];
+
+child.stderr.on("data", (chunk) => {
+  stderr += chunk.toString();
+  if (stderr.length > 8000) stderr = stderr.slice(-8000);
+});
+
+child.stdout.on("data", (chunk) => {
+  buffer += chunk.toString();
+  let index;
+  while ((index = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, index).trim();
+    buffer = buffer.slice(index + 1);
+    if (!line) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      console.error("non-JSON stdout:", line.slice(0, 300));
+      continue;
+    }
+    received.push(message);
+    if (message.id && pending.has(message.id)) {
+      pending.get(message.id)(message);
+      pending.delete(message.id);
+    }
+  }
+});
+
+function send(method, params, timeout = 60_000) {
+  const id = nextId++;
+  const payload = { jsonrpc: "2.0", id, method, params };
+  child.stdin.write(`${JSON.stringify(payload)}\n`);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`timeout waiting for ${method}`));
+    }, timeout);
+    pending.set(id, (message) => {
+      clearTimeout(timer);
+      if (message.error) reject(new Error(JSON.stringify(message.error)));
+      else resolve(message.result);
+    });
+  });
+}
+
+function notify(method, params = {}) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+}
+
+function textOf(result) {
+  return result?.content?.map((item) => item.text).join("\n") || "";
+}
+
+async function main() {
+  const init = await send("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "larkit-verify", version: "1.0.0" },
+  });
+  console.log("initialize:", init.serverInfo?.name, init.serverInfo?.version);
+  notify("notifications/initialized");
+
+  const list = await send("tools/list", {});
+  console.log(
+    "tools:",
+    list.tools.map((tool) => tool.name).join(", "),
+  );
+  if (list.tools.length !== 6) {
+    throw new Error(`expected 6 tools, got ${list.tools.length}`);
+  }
+
+  const search = await send("tools/call", {
+    name: "lark_truth_search",
+    arguments: { query: "chart_spec", scope: "all", limit: 3 },
+  });
+  const searchJson = JSON.parse(textOf(search));
+  console.log(
+    "truth_search:",
+    `${searchJson.results.length} hits, ${searchJson.elapsed_ms}ms, first=${searchJson.results[0]?.file_path}:${searchJson.results[0]?.line_start || searchJson.results[0]?.line_number}`,
+  );
+  if (!searchJson.results.length) throw new Error("truth search returned no hits");
+
+  const firstCode = searchJson.results.find((hit) => hit.kind === "code") || {
+    file_path: "verified_truths/card-json-2.0-official.md",
+    line_number: 10,
+  };
+  const slice = await send("tools/call", {
+    name: "lark_truth_inspect",
+    arguments: {
+      action: "read_slice",
+      file_path: firstCode.file_path,
+      line_number: firstCode.line_number || 1,
+      context: 3,
+      max_lines: 20,
+    },
+  });
+  const sliceJson = JSON.parse(textOf(slice));
+  console.log(
+    "truth_inspect:",
+    `${sliceJson.file_path}:${sliceJson.range?.start}-${sliceJson.range?.end}, ${sliceJson.lines?.length} lines`,
+  );
+  if (!sliceJson.lines?.length) throw new Error("read_slice returned no lines");
+
+  const who = await send("tools/call", {
+    name: "lark_auth",
+    arguments: { action: "whoami", profile: "geren" },
+  });
+  const whoJson = JSON.parse(textOf(who));
+  console.log("auth whoami:", whoJson.ok, whoJson.profile, whoJson.user?.name || "");
+
+  const doc = await send("tools/call", {
+    name: "lark_doc",
+    arguments: { action: "search", query: "图表", limit: 3 },
+  });
+  const docJson = JSON.parse(textOf(doc));
+  console.log("doc search:", docJson.ok, docJson.total, docJson.docs?.[0]?.title || "");
+  if (!docJson.docs?.length) throw new Error("doc search returned no docs");
+  const docRead = await send("tools/call", {
+    name: "lark_doc",
+    arguments: { action: "read", path: docJson.docs[0].path, limit: 20 },
+  });
+  const docReadJson = JSON.parse(textOf(docRead));
+  console.log("doc read:", docReadJson.ok, docReadJson.total_lines, "lines");
+
+  const consoleList = await send("tools/call", {
+    name: "lark_console",
+    arguments: { action: "list_apps", profile: "geren", limit: 50 },
+  });
+  const consoleJson = JSON.parse(textOf(consoleList));
+  console.log("console list_apps:", consoleJson.ok, consoleJson.total, consoleJson.apps?.[0]?.app_id || "");
+  if (!consoleJson.apps?.length) throw new Error("console list_apps returned no apps");
+  const testApp = consoleJson.apps[0].app_id;
+  const probeApp =
+    (process.env.LARKIT_VERIFY_APP_ID &&
+      consoleJson.apps.find(
+        (app) => app.app_id === process.env.LARKIT_VERIFY_APP_ID,
+      )) ||
+    consoleJson.apps.find((app) => app.status === 2) ||
+    consoleJson.apps[0];
+
+  const consoleDry = await send("tools/call", {
+    name: "lark_console",
+    arguments: { action: "enable_bot_ws", app_id: testApp, profile: "geren", dry_run: true },
+  });
+  const consoleDryJson = JSON.parse(textOf(consoleDry));
+  console.log("console dry-run ws:", consoleDryJson.ok, consoleDryJson.calls?.length || 0, "calls");
+
+  const credResult = await send("tools/call", {
+    name: "lark_console",
+    arguments: { action: "get_credentials", app_id: probeApp.app_id, profile: "geren" },
+  });
+  const cred = JSON.parse(textOf(credResult));
+  console.log("console credentials:", cred.ok, cred.app_id, "secret_len=" + (cred.app_secret?.length || 0));
+
+  const openapi = await send("tools/call", {
+    name: "lark_probe",
+    arguments: {
+      mode: "openapi",
+      app_id: cred.app_id,
+      app_secret: cred.app_secret,
+      method: "GET",
+      path: "/im/v1/chats",
+      query: { page_size: 1 },
+    },
+  }, 60_000);
+  const openapiJson = JSON.parse(textOf(openapi));
+  console.log("openapi probe:", openapiJson.ok, openapiJson.status, openapiJson.code, openapiJson.ms || openapiJson.elapsed_ms);
+
+  const probe = await send("tools/call", {
+    name: "lark_probe",
+    arguments: {
+      mode: "client",
+      command: "PUSH_MESSAGES",
+      profile: "geren",
+      transport: "ws",
+      wait_push: true,
+      timeout: 5000,
+    },
+  }, 30_000);
+  const probeJson = JSON.parse(textOf(probe));
+  console.log(
+    "client probe:",
+    `handshake=${probeJson.handshake} ok=${probeJson.ok} events=${probeJson.events?.length || 0}`,
+  );
+
+  console.log("\nMCP verification passed");
+  if (stderr.trim()) console.log("server stderr tail:\n", stderr.trim().split("\n").slice(-8).join("\n"));
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error("MCP verification failed:", error);
+  if (stderr.trim()) console.error("stderr:\n", stderr.trim().slice(-3000));
+  process.exitCode = 1;
+} finally {
+  child.kill("SIGTERM");
+  setTimeout(() => process.exit(process.exitCode || 0), 200);
+}

package/skills/larkit/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: larkit
+description: >
+  Feishu/Lark full-stack development and reverse-engineering with a local truth engine. Use when the
+  task involves Feishu/Lark official docs, cards (卡片/JSON 2.0/chart_spec/card_link), messages,
+  bots or event subscriptions, WebSocket long connections, app creation and publishing in the
+  developer console (open.feishu.cn/app), permission scopes, tenant_access_token, OpenAPI probing,
+  client private protocol commands (PUT_MESSAGE/PUSH_MESSAGES/2020 commands), protobuf schemas,
+  hidden fields, error codes (99991672/9499), or reading reverse-engineered web/Electron client code.
+  Provides MCP tools `lark_doc`, `lark_truth_search`, `lark_truth_inspect`, `lark_auth`,
+  `lark_console`, `lark_probe` and the equivalent `larkit` CLI.
+---
+
+# Larkit — Feishu full-stack truth engine
+
+Larkit answers Feishu questions from **evidence**, not guesses: 4800+ official docs, 2020 client
+protocol commands, 237k code anchors from the web/Electron client, and a `verified_truths`
+knowledge base that grows as you verify things. It can also create/configure/publish real apps in
+the developer console and send real API/protocol probes.
+
+## 1. Preflight (do this once per session)
+
+```bash
+larkit status --json          # fastest: truth.db? code corpus? skill? MCP config?
+larkit doctor                 # auth profiles, tokens, Chrome, install state
+```
+
+- `truth.installed=false` → have the user run `npx larkit` (or `larkit init`).
+- `code.installed=false` → the truth pack is half-extracted; rerun `larkit init` (the code corpus
+  ships in the same archive, there is nothing optional to add).
+- If the MCP tools are not mounted, use the CLI equivalents in `references/tools.md`; they return
+  the same JSON.
+
+Never invent Feishu behavior when the truth engine or the official docs can answer it.
+
+## 2. Route the question
+
+| User asks | Start with | Then |
+| --- | --- | --- |
+| "Is card field X supported?" / card JSON 2.0 | `lark_truth_search(scope="verified")` | `lark_doc search` → `read` → code anchors |
+| "What does this error code mean?" | `lark_truth_search(scope="all")` | doc error-code pages → `lark_probe` |
+| "Create a bot that receives events over WebSocket" | `references/playbooks.md` §B | `lark_auth` → `lark_console` → `lark_probe` |
+| "Why does this OpenAPI call fail?" | `lark_probe(mode="openapi")` | read `code/msg/log_id`, then scope/CSRF checks |
+| "What is command N / PUT_MESSAGE?" | `lark_truth_search(scope="protocol")` | `read_slice` on protocol docs or client code |
+| "Show me the client implementation" | search `scope="web"`/`"electron"` | `read_slice` with `mode="function"` |
+| "Configure/publish an app" | `lark_console` (`dry_run` first) | `references/console.md` |
+| "Log me in / switch account" | `lark_auth(action="list")` | `check` → QR login → `check` |
+| "Set up larkit / install the skill" | §6 below | |
+
+Full playbooks: `references/playbooks.md`. Console API recipes and failure matrix:
+`references/console.md`. Tool/CLI/env reference: `references/tools.md`.
+
+## 3. Token discipline (hard rules)
+
+1. **Always try `scope="verified"` first.** If a prior conclusion exists, stop there.
+2. `limit <= 10`; results contain coordinates + a 320-char snippet, not whole files.
+3. Never read a formatted client file end-to-end. `search` → `read_slice`.
+4. `read_slice`: prefer `mode="function"`, `max_lines <= 120`.
+5. Docs: `lark_doc search` → `read` with `offset/limit`; use returned `headings` to jump.
+6. Probes: `GET` before `POST`; `dry_run=true` before every console write; `wait_push=true` for
+   listener-only protocol commands.
+7. `save_verified` only with evidence (probe output/log_id, doc URL, `file:line`). No secrets,
+   cookies or tokens in the knowledge base.
+8. Never echo credentials or auth headers back to the user.
+
+## 4. Standard loop
+
+```
+lark_auth check
+  → lark_truth_search(scope=verified)
+  → lark_doc search/read
+  → lark_truth_search(scope=protocol|web|electron)
+  → lark_truth_inspect(read_slice)
+  → lark_probe(openapi|client)
+  → lark_truth_inspect(save_verified)
+  → lark_console(dry_run → apply)
+  → lark_probe re-verify
+```
+
+Stop as soon as the answer is certain. Each step exists only to cover the previous step's gap.
+
+## 5. Evidence boundaries
+
+- Desktop client main process is a native binary (`feishu`/`libiron`); the corpus covers renderer,
+  preload, JSSDK, worker and protocol assets, not native main-process logic.
+- `read_slice` paths are relative to `formatted/` (web/electron) or `verified_truths/`.
+- i18n bundles are not indexed; search specific keys if needed.
+- Feishu internal console APIs and private protocol routes drift between client versions. Record
+  what you verified, with the client/doc version, in `verified_truths`.
+- Official doc endpoints and console APIs are rate-limited; back off instead of retrying blindly.
+
+## 6. Installing / repairing larkit (when the user asks)
+
+```bash
+npx larkit                     # init on first run, status afterwards
+npx larkit init --channel      # (re)install from the official truth channel
+npx larkit init --pack=<manifest.json|dir|.tar.gz>   # offline / pinned install
+npx larkit init --from-assets --deb=./feishu-linux.deb --web-dump=./feishu-web-dump
+# ↑ 构建资产不随包分发，需自备 deb + web dump；常规安装用上面两条命令即可
+npx larkit status              # verify truth.db / skill / CLI / MCP
+npx larkit update              # refresh outdated pieces
+npx larkit skills install      # reinstall the agent skill
+npx larkit pack verify <manifest.json>   # maintainers: verify a truth pack
+```
+
+Layout: `~/.larkit/{data/truth.db, verified_truths, cli, install.json, mcp.json}`. The MCP client
+config is written to `~/.larkit/mcp.json`; the skill lands in existing agent skill directories
+(`~/.agents/skills/larkit`, `~/.claude/skills/larkit`) or `--target=`/`--project`.
+
+## 7. When a tool fails
+
+| Symptom | Action |
+| --- | --- |
+| `truth.db not found` | `npx larkit` (or `larkit init`) |
+| `file not found: formatted/...` | `larkit init` (corpus ships with the truth pack) |
+| `needs_login` / `9499` | `lark_auth(action="login")` then poll `login_status`; or `import` cookies |
+| `99991672` | missing scope → `lark_console grant_scopes` → re-probe |
+| `command: N not found` | re-check cmd/kind with `lark_truth_search(scope="protocol")` |
+| `PullFeedGroups invalid request` | read operations belong on OpenAPI, not the private gateway |
+| MCP tool missing | use the CLI (`larkit search/inspect/doc/console/probe`) |

package/skills/larkit/references/console.md

@@ -0,0 +1,86 @@
+# Developer console (`open.feishu.cn/app`) — recipes and failure matrix
+
+## Session / CSRF
+
+- Read the active profile from `~/.larkit/credentials.json`.
+- Open `https://open.feishu.cn/app`, extract `window.csrfToken`, and merge response cookies
+  (`lark_oapi_csrf_token`, `sl_session`).
+- Headers: `Cookie`, `x-csrf-token`, `Origin`, `Referer`, `User-Agent`, `X-Timezone-Offset`.
+- `swp_csrf_token` alone → `9499 lark_oapi_csrf_token not exist in cookie`.
+- Mismatched header token → `9499 csrf token check fail`.
+
+## Internal HTTP recipes
+
+| Capability | Method / path | Key body |
+| --- | --- | --- |
+| App list | `POST /developers/v1/app/list` | `{Count,Cursor}` |
+| Create app | `POST /developers/v1/app/create` | `{name,desc,avatar,primaryLang,i18n,appSceneType}` |
+| App detail | `POST /developers/v1/app/:clientId` | `{}` |
+| Credentials | `POST /developers/v1/secret/:clientId` | `{}` → `data.secret` |
+| Update info | `POST /developers/v1/base_info/:clientId` | `{name,desc,i18n,avatar,languages}` |
+| All scopes | `POST /developers/v1/scope/all/:clientId` | `{clientId}` |
+| Apply scopes | `POST /developers/v1/scope/update/:clientId` | `{operation:"add",scopeIds:[],appScopeIDs:[...]}` |
+| Robot state | `POST /developers/v1/robot/:clientId` | `{clientId}` |
+| Enable robot | `POST /developers/v1/robot/switch/:clientId` | `{enable:true}` |
+| Event mode | `POST /developers/v1/event/switch/:clientId` | `{eventMode:4}` |
+| Card callback mode | `POST /developers/v1/callback/switch/:clientId` | `{callbackMode:4}` |
+| Version list | `POST /developers/v1/app_version/list/:clientId` | `{clientId}` |
+| Create version | `POST /developers/v1/app_version/create/:clientId` | `{appVersion,updateRemark,visibleSuggest,changeLog}` |
+| Commit release | `POST /developers/v1/publish/commit/:clientId/:versionId` | `{is_full_release}` |
+| Release | `POST /developers/v1/publish/release/:clientId/:versionId` | `{is_full_release}` |
+
+`eventMode=4` and `callbackMode=4` mean WebSocket long connection. `robot.cardCallbackMode` is the
+card request-address mode (1=Webhook), not the long-connection switch. Sending `callbackMode:4` to
+`/v2/robot/push_mode/switch` returns `ParamInvalid`.
+
+## HTTP first, browser fallback second
+
+Use plain HTTP when `lark_console` already has a recipe: milliseconds, dry-runnable, reproducible.
+Use `browser_fallback` when:
+
+- the internal endpoint is not covered (avatar upload, complex forms, review flows),
+- HTTP returns 9499/403 while the session is known-good,
+- you need to capture a new console API shape.
+
+Example:
+
+```
+lark_console({
+  action:"browser_fallback",
+  profile:"geren",
+  url:"https://open.feishu.cn/app",
+  wait_ms:3000,
+  actions:[
+    {type:"click_text", text:"创建应用"},
+    {type:"fill", fields:[{placeholder:"应用名称", value:"my-app"}]}
+  ],
+  screenshot:true,
+  record_as:"create_app"
+})
+```
+
+It reuses system Chrome (`CHROME_PATH`) with the larkit cookie and records `/developers/` +
+`/open-apis/` requests (sanitized headers, body shape, status) into
+`<data>/console-api-recipes.json`. Promote stable paths into `src/console/client.js`
+`DEFAULT_RECIPES`, then reproduce via `lark_console` HTTP.
+
+## Failure matrix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `9499 lark_oapi_csrf_token not exist in cookie` | only `swp_csrf_token` sent | re-resolve session (`lark_auth check`), merge Set-Cookie |
+| `9499 csrf token check fail` | header/page/cookie token mismatch | use page `window.csrfToken` + `lark_oapi_csrf_token` |
+| `99991672` | app lacks scope | `grant_scopes` then re-probe |
+| WS `timeout waiting for cmd=6` | push command was sent instead of listened | use `wait_push:true` |
+| Gateway `PullFeedGroups invalid request` | read command not routed on the gateway | use OpenAPI for reads |
+| `command: N not found` | wrong command id/name or wrong transport | re-check via `lark_truth_search(scope=protocol)` |
+| `ParamInvalid` on `/v2/robot/push_mode/switch` | `callbackMode:4` misuse | use `/v1/callback/switch` |
+| `truth.db not found` | no truth source installed | `npx larkit` / `larkit init` |
+| `file not found` in `read_slice` | code corpus missing | `larkit init` |
+| `needs_login` from browser fallback | cookie expired | `lark_auth login` |
+
+## Evidence rules for console work
+
+- Writes have real side effects (apps, versions, releases). Always dry-run first.
+- Record `app_id`, action, `code`, `msg`, and verification fields in `save_verified`.
+- Never persist credentials, tokens, or full auth headers.

package/skills/larkit/references/playbooks.md

@@ -0,0 +1,177 @@
+# Playbooks
+
+Each playbook is a closed loop: evidence → action → verification → `save_verified`.
+Load only the one that matches the task.
+
+## A. Card field / hidden property support (e.g. `chart_spec`, `card_link`, `streaming_mode`)
+
+1. `lark_truth_search({query:"chart_spec", scope:"verified"})`
+   - Hit in `verified_truths/card-json-2.0-official.md` → read that section and stop.
+2. Miss → official docs:
+   - `lark_doc({action:"search", query:"卡片 JSON 2.0"})`
+   - `lark_doc({action:"read", path, limit:120})`, jump with `offset` from `headings`.
+3. Docs ambiguous → client code:
+   - `lark_truth_search({query:"chart_spec", scope:"all"})`
+   - `lark_truth_inspect({action:"read_slice", file_path, line_number, mode:"function", max_lines:80})`
+4. Need server truth → `lark_probe({mode:"openapi", method:"POST", path:"/im/v1/messages", body:{...}})`
+   or `PATCH /open-apis/im/v1/messages/:message_id` to update a card; inspect `code/msg`.
+5. Persist:
+   ```
+   lark_truth_inspect({
+     action:"save_verified",
+     topic:"卡片 chart_spec 的 media 行为",
+     content:"## 结论 ...\n## 最小 JSON ...",
+     evidence:"doc URL + probe log_id/response",
+     source:"doc|probe",
+     confidence:"high"
+   })
+   ```
+
+Note: `chart_spec` is **not** present in the current desktop/Web code; only the official docs
+describe it. Do not claim a code location you have not seen.
+
+## B. Create a bot that receives events over WebSocket (from zero)
+
+### B1. Auth
+
+```
+lark_auth({action:"check", profile:"geren"})
+```
+
+- `needs_login` → `lark_auth({action:"login", name:"geren"})`, then poll
+  `lark_auth({action:"login_status", name:"geren"})` and show the user `qr_path`.
+- Headless/import path: `lark_auth({action:"import", name:"geren", cookie:"..."})`.
+- `lark_auth list` to find a non-expired profile. Do not use stale `tapeless-*` profiles.
+
+### B2. Create the app (dry-run first)
+
+```
+lark_console({action:"create_app", profile:"geren", name:"my-agent-app", desc:"...", dry_run:true})
+```
+
+Review the plan, then run without `dry_run`. Capture `app_id` (`cli_xxx`).
+
+### B3. Credentials
+
+```
+lark_console({action:"get_credentials", app_id:"cli_xxx", profile:"geren"})
+```
+
+Store in `larkit.config.json` / env vars, never in `verified_truths`.
+
+### B4. Scopes
+
+```
+lark_console({action:"list_scopes", app_id:"cli_xxx", profile:"geren"})
+lark_console({action:"grant_scopes", app_id:"cli_xxx",
+  scopes:["im:message","im:chat:readonly","im:message:send_as_bot"],
+  scope_type:"app", dry_run:true})
+```
+
+Check `resolved.missing` is empty before applying.
+
+### B5. Robot + event/card WebSocket
+
+```
+lark_console({action:"enable_bot_ws", app_id:"cli_xxx", profile:"geren", dry_run:true})
+lark_console({action:"enable_bot_ws", app_id:"cli_xxx", profile:"geren"})
+```
+
+It performs three writes:
+
+- `/developers/v1/robot/switch/:id` → `{enable:true}`
+- `/developers/v1/event/switch/:id` → `{eventMode:4}`
+- `/developers/v1/callback/switch/:id` → `{callbackMode:4}`
+
+Verification must show `bot_enabled=true, event_mode=4, callback_mode=4`.
+`robot.cardCallbackMode` is the card request-address mode (1=Webhook), **not** the long-connection
+switch. Do not send `callbackMode:4` to `/v2/robot/push_mode/switch` (returns `ParamInvalid`).
+
+### B6. Publish
+
+```
+lark_console({action:"publish", app_id:"cli_xxx", version:"1.0.0",
+  remark:"agent bootstrap", full_release:false, dry_run:true})
+```
+
+Apply after reviewing. `commit.code=0` means submitted; `list_versions` confirms status.
+
+### B7. Probe
+
+```
+lark_probe({mode:"openapi", app_id:"cli_xxx", app_secret:"...",
+  method:"GET", path:"/im/v1/chats", query:{page_size:1}})
+```
+
+`code:0` = credentials + scope OK. `99991672` = missing scope (back to B4). `9499` = CSRF/login
+(back to B1).
+
+### B8. Persist
+
+```
+lark_truth_inspect({action:"save_verified", topic:"my-agent-app 的长连接配置",
+  content:"## 结论\napp_id=... eventMode=4 / callbackMode=4 ...",
+  evidence:"enable_bot_ws verification=...; probe log_id=...",
+  source:"console", confidence:"high"})
+```
+
+## C. Verify an undocumented API / error code
+
+1. `lark_truth_search({query:"99991672", scope:"all"})` (or the path/field).
+2. `lark_doc` for permission/error-code pages.
+3. Send the minimal request:
+   ```
+   lark_probe({mode:"openapi", app_id, app_secret, method:"POST",
+     path:"/open-apis/...", query:{...}, body:{...}})
+   ```
+   Keep `status/code/msg/log_id/body` verbatim. Do not retry dozens of times; read `msg` to
+   distinguish permission vs parameter vs route errors.
+4. Not an OpenAPI capability → search the private protocol:
+   `lark_truth_search({query:"COMMAND_OR_ENDPOINT", scope:"protocol"})`.
+5. `lark_probe({mode:"client", command:"...", transport:"gateway"|"ws", profile})`.
+6. Save conclusion + evidence.
+
+## D. Reverse-engineer the private client protocol
+
+1. `lark_truth_search({query:"PUT_MESSAGE", scope:"protocol"})`
+   → `cmd=5`, `messages.PutMessageRequest`, schema summary.
+2. Field details:
+   - `lark_truth_search({query:"PutMessageRequest", scope:"protocol", limit:5})`
+   - or read `src/protocol/data/reference/PROTOCOL.md`.
+3. Client implementation evidence:
+   ```
+   lark_truth_search({query:"PUT_MESSAGE", scope:"electron"})
+   lark_truth_inspect({action:"read_slice", file_path, line_number, mode:"function", max_lines:100})
+   ```
+4. Send:
+   ```
+   lark_probe({mode:"client", command:"PUT_MESSAGE", transport:"gateway",
+     profile:"geren", payload:{...}})
+   ```
+   - Writes go through `gateway`; pushes/signals through `ws`.
+   - `PUSH_MESSAGES` is listen-only: `wait_push:true`, never send it.
+   - `GET_CHAT_MESSAGES` over the gateway returns `PullFeedGroups invalid request`; use OpenAPI for reads.
+5. Save new commands/fields/boundaries.
+
+## E. Inspect the developer console / capture a new internal API
+
+Use `lark_console action=browser_fallback` only when the HTTP recipes are insufficient:
+
+```
+lark_console({
+  action:"browser_fallback",
+  profile:"geren",
+  url:"https://open.feishu.cn/app",
+  wait_ms:3000,
+  actions:[
+    {type:"click_text", text:"创建应用"},
+    {type:"fill", fields:[{placeholder:"应用名称", value:"my-app"}]}
+  ],
+  screenshot:true,
+  record_as:"create_app"
+})
+```
+
+Returns `network[]` (sanitized headers/body shape), `recipes_recorded`, `needs_login`,
+`screenshot_path`. Add stable paths to `src/console/client.js` `DEFAULT_RECIPES`, then reproduce
+over plain HTTP.