larkit 0.0.0-stage → 0.1.1

package/skills/larkit/references/tools.md

@@ -0,0 +1,115 @@
+# Tool & CLI reference
+
+All MCP tools are also available as CLI commands returning the same JSON. Prefer MCP when it is
+mounted; use the CLI for scripts, CI, or when MCP is not configured.
+
+## MCP tools
+
+### `lark_doc` — official documentation (zero config)
+
+| Param | Notes |
+| --- | --- |
+| `action` | `search` \| `read` \| `categories` |
+| `query` | title/path keyword for `search` |
+| `category` | taxonomy key, e.g. `服务端 API_即时通讯` |
+| `path` | document path returned by `search` |
+| `offset` / `limit` | line window for large docs (`limit <= 400`) |
+
+CLI: `larkit doc search 卡片`, `larkit doc read "<path>" --limit 80`, `larkit doc categories`.
+
+### `lark_truth_search` — local truth engine
+
+| Param | Notes |
+| --- | --- |
+| `query` | keyword, API path, card field, error code, IPC channel, command name |
+| `scope` | `all` \| `verified` \| `protocol` \| `web` \| `electron` |
+| `limit` | 1–50, default 10 |
+
+Returns compact hits with `kind`, coordinates (`file_path`, `line_number`, `line_start`), a
+320-char `context`/`snippet`, and protocol schema summaries. Always start with `scope=verified`.
+
+CLI: `larkit search card_link --scope electron --limit 5`.
+
+### `lark_truth_inspect` — read code / persist knowledge
+
+| Param | Notes |
+| --- | --- |
+| `action` | `read_slice` \| `save_verified` |
+| `file_path` | path from search results (`formatted`-relative or `verified_truths/...`) |
+| `line_number` | target line |
+| `mode` | `context` \| `function` (function prefers the enclosing body) |
+| `max_lines` | default 120, hard cap 200 |
+| `topic`, `content`, `evidence`, `source`, `confidence`, `tags` | for `save_verified` |
+
+CLI: `larkit inspect web/network/foo.js 120 --mode=function --max-lines=80`,
+`larkit save "topic" --content "..." --evidence "..." --source probe`.
+
+### `lark_auth` — local Feishu identity
+
+Actions: `whoami`, `check`, `list`, `use`, `cookie`, `login`, `login_status`, `import`, `logout`.
+
+- `login` is detached: it returns a status file; `login_status` returns `qr_path` to show the user.
+- `import` accepts a cookie string or a JSON file.
+- Profiles live in `~/.larkit/credentials.json`; the active profile in `~/.larkit/config.json`.
+
+CLI: `larkit auth check --profile geren`, `larkit auth login geren`, `larkit auth login_status geren`.
+
+### `lark_console` — developer console control
+
+| Action | Purpose |
+| --- | --- |
+| `list_apps`, `get_app` | inventory |
+| `create_app`, `update_app_info` | app lifecycle (`dry_run` supported) |
+| `get_credentials` | app_secret (never persist in knowledge files) |
+| `list_scopes`, `applied_scopes`, `grant_scopes` | permissions |
+| `enable_bot_ws` | robot + event WS + card callback WS |
+| `list_versions`, `publish` | versioning/release |
+| `browser_fallback` | Chrome + CDP fallback, captures internal APIs |
+
+Always `dry_run:true` first for writes. Full endpoint table: `console.md`.
+
+CLI: `larkit console enable_bot_ws --app cli_xxx --profile geren --dry-run`.
+
+### `lark_probe` — real traffic
+
+`mode="openapi"`:
+`app_id`, `app_secret` (or env), `method`, `path`, `query`, `body`, `timeout`.
+Automatically obtains/caches `tenant_access_token` (60s early expiry).
+
+`mode="client"`:
+`command` (e.g. `PUT_MESSAGE`), `payload`, `transport` (`ws` | `gateway`), `profile`,
+`wait_push`, `timeout`. Uses the bundled protobuf schema so it works without the deb.
+
+CLI: `larkit probe openapi --path=/im/v1/chats --app-id=... --app-secret=...`,
+`larkit probe client --command=PUSH_MESSAGES --wait-push --timeout=8000`.
+
+## CLI bootstrap commands
+
+```bash
+npx larkit                 # init on first run; status afterwards
+larkit init                # idempotent bootstrap
+larkit status --json
+larkit update              # refresh outdated truth/skill/CLI
+larkit skills list|install|remove [--target=agents,claude,project] [--project]
+larkit pack build|verify|embed|path|stats
+larkit doctor
+larkit mcp                 # stdio MCP server
+larkit mcp config          # print the MCP client JSON
+```
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `LARKIT_HOME` | override `~/.larkit` (state, CLI, skill records, downloads) |
+| `LARKIT_DATA_DIR` | truth.db + formatted corpus location |
+| `LARKIT_VERIFIED_DIR` | writable `verified_truths` directory |
+| `LARKIT_PACK_MANIFEST` | default truth pack manifest URL/path |
+| `LARKIT_DEB` / `LARKIT_WEB_DUMP` | inputs for `init --from-assets` |
+| `LARKIT_BIN_DIR` | where the `larkit` shim is written (default `~/.local/bin`) |
+| `FEISHU_APP_ID` / `FEISHU_APP_SECRET` | default probe credentials |
+| `CHROME_PATH` | Chrome for `browser_fallback` |
+| `LARKIT_PROFILE` | default auth profile |
+| `LARKIT_GATEWAY_HEADERS` | extra client gateway headers (JSON) |
+
+Config layers: `<data>/config.json` < `~/.larkit/config.json` < `./larkit.config.json`.

package/skills/larkit/references/truth-model.md

@@ -0,0 +1,117 @@
+# Truth model
+
+## What the index contains
+
+| Layer | Scope | Content |
+| --- | --- | --- |
+| `verified` | `verified_truths` | conclusions you wrote with `save_verified` (section-level FTS) |
+| `protocol` | `protocol_catalog`, `protocol_docs` | 2020 client commands (cmd/name/request/response/kind) + `PROTOCOL.md`/endpoints notes |
+| `web` | `code_anchors` | 531 deduplicated Web client resources (formatted, line-accurate) |
+| `electron` | `code_anchors` | 8500+ desktop renderer/preload/JSSDK/worker files from `webcontent/*.asar` |
+
+Index scale depends on the client version used to build the pack (current reference:
+2020 commands, 237,729 anchors, 12 verified sections, 17 protocol doc sections).
+
+`code_anchors` cover: OpenAPI paths, URLs, IPC channels, `tt.*`/`h5sdk.*`/`LarkAPI.*`, card schema
+keys, error codes, i18n keys, protocol constants, command names.
+
+## Coordinates and reading
+
+- Search returns `file_path` **relative to the formatted corpus** (e.g.
+  `electron/asar/messenger/35983/f7adb73684.js`) plus `line_number`.
+- Pass that path verbatim to `read_slice`; do not prepend anything.
+- `verified_truths/<slug>.md` paths are also readable; sections carry `line_start`/`line_end`.
+- `read_slice` is bounded (default 12 lines of context, `max_lines <= 120`). Reading a whole
+  formatted file is forbidden — the corpus is ~14M lines.
+
+## Writing knowledge (`save_verified`)
+
+File format (one topic per file):
+
+```md
+---
+topic: ...
+verified_at: ...
+source: probe | reverse | doc | console
+confidence: high | medium | low
+tags: [...]
+---
+
+## 结论
+...
+
+## 证据
+- probe log_id / URL / file:line
+```
+
+Rules:
+
+- Only verified facts. Guesses stay in the conversation.
+- Include a minimal reproduction (request/response/JSON snippet) so the conclusion is actionable.
+- Never write credentials, tokens, or full auth headers.
+- After writing, `lark_truth_search(scope="verified")` must hit immediately (SQLite incremental
+  sync). If sync fails, the Markdown is still saved and will be indexed on the next rebuild.
+
+## Storage layout
+
+```
+~/.larkit/
+├── data/
+│   ├── truth.db              # SQLite FTS5 index
+│   ├── truth.meta.json       # build stats
+│   ├── formatted/            # optional code corpus (search works without it)
+│   ├── cache/                # docs, tokens, screenshots, login logs
+│   └── console-api-recipes.json
+├── verified_truths/          # user-owned Markdown knowledge
+├── cli/                      # durable CLI install (npm prefix)
+├── downloads/                # cached truth/code pack archives
+├── install.json              # bootstrap state + seed hashes
+├── mcp.json                  # MCP client config
+├── config.json               # user-level config (profiles/apps)
+└── credentials.json          # auth profiles
+```
+
+Engineers can override `LARKIT_HOME`, `LARKIT_DATA_DIR`, `LARKIT_VERIFIED_DIR`. A git checkout
+continues to use `<repo>/.larkit-data` and `<repo>/verified_truths` for `pnpm index` / `pnpm verify`.
+
+## Installing / updating
+
+```bash
+npx larkit                  # truth pack (truth.db + code corpus) + skill + CLI + MCP config
+npx larkit update           # refresh only outdated pieces (truth check runs on every command)
+npx larkit status --json
+```
+
+Truth pack sources, in priority order:
+
+1. `--pack=<manifest.json|dir|.tar.gz|https://...>`
+2. `--from-assets --deb=... --web-dump=...` (local build; Linux + `dpkg-deb`)
+3. `--channel[=<url>]` — the official channel, also the default
+4. `LARKIT_PACK_MANIFEST`
+
+There is exactly one archive (`tiers.full`, ~161 MB): `truth.db` + verified seeds + `formatted/`.
+Nothing is optional — installing always brings the code corpus with it.
+
+Seed `verified_truths` files are content-hashed. On update they are replaced only if unmodified;
+user edits are preserved.
+
+## Rebuilding (maintainers)
+
+```bash
+pnpm index                                  # full pipeline into .larkit-data
+node scripts/build-index.mjs --only=protocol,db
+node scripts/build-index.mjs --only=anchors,protocol,db
+npx larkit pack build --out=dist/truth-pack --tag=2026.11.15 --base-url=https://host/path
+node scripts/publish-pack.mjs --pack-dir=dist/truth-pack --base-url=https://host/path
+npx larkit pack verify dist/truth-pack/manifest.json
+```
+
+## Boundaries
+
+- Desktop main process is native (`feishu`/`libiron`); there is no `app.asar`. The corpus covers
+  renderer/preload/JSSDK/worker/protocol assets only.
+- i18n bundles are excluded from formatting; query specific keys if needed.
+- Official docs endpoints and console APIs are public but may rate-limit or change; caches and
+  `browser_fallback` recordings are the fallback.
+- Private protocol routes and console internals drift with client versions. Record the version you
+  verified against.

package/src/auth/login.js

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import path from "node:path";
+import QRCode from "qrcode";
+import { CACHE_DIR } from "../shared/paths.js";
+import { ensureDir } from "../shared/util.js";
+import { launchBrowser } from "../shared/browser.js";
+import { saveProfile } from "./store.js";
+
+const LOGIN_URL =
+  "https://accounts.feishu.cn/accounts/page/login?app_id=11&force_login=1&no_trap=1&redirect_uri=https%3A%2F%2Fwww.feishu.cn%2F";
+const NAV_TIMEOUT = 45_000;
+const TOKEN_TIMEOUT = 30_000;
+
+function safeName(name) {
+  return String(name || "default").replace(/[^\p{L}\p{N}_-]+/gu, "_");
+}
+
+function writeStatus(file, data) {
+  if (!file) return;
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export async function loginWithQr({
+  name = "default",
+  timeoutMs = 120_000,
+  headless = true,
+  statusFile,
+} = {}) {
+  ensureDir(path.join(CACHE_DIR, "login"));
+  const base = `${safeName(name)}-${Date.now()}`;
+  const qrPath = path.join(CACHE_DIR, "login", `${base}.png`);
+  const screenshotPath = path.join(CACHE_DIR, "login", `${base}-page.png`);
+  const status = (phase, extra = {}) =>
+    writeStatus(statusFile, {
+      phase,
+      profile: name,
+      updated_at: new Date().toISOString(),
+      ...extra,
+    });
+
+  status("starting");
+  let browser;
+  let page;
+  try {
+    browser = await launchBrowser({ headless });
+    page = await browser.newPage();
+    status("loading", { login_url: LOGIN_URL });
+
+    const tokenPromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error("waiting for qrlogin/init timed out")),
+        TOKEN_TIMEOUT,
+      );
+      page.on("response", async (response) => {
+        if (!response.url().includes("/accounts/qrlogin/init")) return;
+        try {
+          const body = await response.json();
+          const token = body?.data?.step_info?.token;
+          if (token) {
+            clearTimeout(timer);
+            resolve(token);
+          }
+        } catch {
+          // ignore non-JSON responses
+        }
+      });
+    });
+
+    try {
+      await page.goto(LOGIN_URL, {
+        waitUntil: "networkidle2",
+        timeout: NAV_TIMEOUT,
+      });
+    } catch (error) {
+      if (!page.url().includes("accounts.feishu.cn")) throw error;
+    }
+
+    const token = await tokenPromise;
+    const qrData = JSON.stringify({ qrlogin: { token } });
+    await QRCode.toFile(qrPath, qrData, {
+      width: 640,
+      margin: 2,
+      errorCorrectionLevel: "M",
+    });
+    status("qr_ready", { qr_path: qrPath, final_url: page.url() });
+
+    const deadline = Date.now() + Math.max(5_000, Number(timeoutMs) || 120_000);
+    let lastCookies = [];
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+      try {
+        lastCookies = await browser.cookies();
+      } catch {
+        break;
+      }
+      const session = lastCookies.find((cookie) => cookie.name === "session");
+      const device = lastCookies.find(
+        (cookie) => cookie.name === "passport_web_did",
+      );
+      if (session?.value && device?.value) {
+        const cookie = lastCookies
+          .filter((item) => item.domain.includes("feishu.cn"))
+          .map((item) => `${item.name}=${item.value}`)
+          .join("; ");
+        const saved = saveProfile({ name, cookie, active: true });
+        status("success", {
+          qr_path: qrPath,
+          final_url: page.url(),
+          cookies: saved.cookies,
+        });
+        return {
+          ok: true,
+          profile: name,
+          cookies: saved.cookies,
+          qr_path: qrPath,
+          final_url: page.url(),
+        };
+      }
+    }
+
+    try {
+      await page.screenshot({ path: screenshotPath, fullPage: false });
+    } catch {
+      // ignore
+    }
+    status("timeout", {
+      qr_path: qrPath,
+      screenshot_path: screenshotPath,
+      final_url: page.url(),
+      cookie_names: lastCookies.map((cookie) => cookie.name),
+    });
+    return {
+      ok: false,
+      profile: name,
+      error: "QR login timed out",
+      qr_path: qrPath,
+      screenshot_path: screenshotPath,
+      final_url: page.url(),
+      hint: "Open qr_path and scan with Feishu, then retry. Or use lark_auth action=import with a cookie string/file.",
+    };
+  } catch (error) {
+    try {
+      if (page) {
+        await page.screenshot({ path: screenshotPath, fullPage: false });
+      }
+    } catch {
+      // ignore
+    }
+    status("error", {
+      error: error instanceof Error ? error.message : String(error),
+      qr_path: fs.existsSync(qrPath) ? qrPath : null,
+      screenshot_path: fs.existsSync(screenshotPath) ? screenshotPath : null,
+      final_url: page?.url?.(),
+    });
+    return {
+      ok: false,
+      profile: name,
+      error: error instanceof Error ? error.message : String(error),
+      qr_path: fs.existsSync(qrPath) ? qrPath : null,
+      screenshot_path: fs.existsSync(screenshotPath) ? screenshotPath : null,
+      final_url: page?.url?.(),
+    };
+  } finally {
+    try {
+      await browser?.close();
+    } catch {
+      // ignore
+    }
+  }
+}

package/src/auth/service.js

@@ -0,0 +1,213 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import {
+  CACHE_DIR,
+  LOCAL_CONFIG_FILE,
+  ROOT,
+} from "../shared/paths.js";
+import { ensureDir, readJson, writeJson } from "../shared/util.js";
+import { resolveConsoleSession } from "../console/client.js";
+import {
+  authPaths,
+  getProfileCookies,
+  importProfiles,
+  listProfiles,
+  removeProfile,
+  resolveProfileName,
+  setActiveProfile,
+} from "./store.js";
+import { loginWithQr } from "./login.js";
+
+function statusFileFor(name) {
+  const safe = String(name || "default").replace(/[^\p{L}\p{N}_-]+/gu, "_");
+  return path.join(CACHE_DIR, "login", `${safe}.status.json`);
+}
+
+export function authList() {
+  return {
+    ...listProfiles(),
+    home: authPaths().home,
+    credentials_file: authPaths().credentials,
+  };
+}
+
+export async function whoami({ profile } = {}) {
+  const name = resolveProfileName(profile);
+  if (!name) {
+    return { ok: false, error: "no larkit profiles; run lark_auth action=login or import" };
+  }
+  getProfileCookies(name);
+  try {
+    const session = await resolveConsoleSession(name, { force: true });
+    return {
+      ok: session.valid,
+      profile: name,
+      user: session.user,
+      console_logged_in: session.valid,
+      hint: session.valid
+        ? undefined
+        : "cookie expired; run lark_auth action=login or import a fresh cookie",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      profile: name,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function checkAuth({ profile } = {}) {
+  const name = resolveProfileName(profile);
+  if (!name) {
+    return { ok: false, error: "no larkit profiles; run lark_auth action=login or import" };
+  }
+  try {
+    const session = await resolveConsoleSession(name, { force: true });
+    return {
+      ok: session.valid,
+      profile: name,
+      user: session.user,
+      console_logged_in: session.valid,
+      page_status: session.page_status,
+      csrf_present: Boolean(session.csrf),
+      hint: session.valid
+        ? undefined
+        : "cookie expired; run lark_auth action=login or import a fresh cookie",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      profile: name,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function useProfile(name) {
+  if (!name) throw new Error("profile name is required");
+  const result = setActiveProfile(name);
+  const local = readJson(LOCAL_CONFIG_FILE, {});
+  writeJson(LOCAL_CONFIG_FILE, { ...local, defaultProfile: name });
+  return { ...result, default_profile: name };
+}
+
+export function cookieFor(profile) {
+  const { name, cookies } = getProfileCookies(profile);
+  return { ok: true, profile: name, cookie: cookies, length: cookies.length };
+}
+
+export function startLogin(
+  name = "default",
+  { timeoutMs = 120_000, headless = true, wait = false } = {},
+) {
+  ensureDir(path.join(CACHE_DIR, "login"));
+  const statusFile = statusFileFor(name);
+  if (wait) {
+    const result = loginWithQr({ name, timeoutMs, headless, statusFile });
+    return result;
+  }
+  const logPath = path.join(CACHE_DIR, "login", `${name.replace(/[^\w.-]+/g, "_")}.log`);
+  const fd = fs.openSync(logPath, "w");
+  const child = spawn(
+    process.execPath,
+    [
+      path.join(ROOT, "scripts", "login-worker.mjs"),
+      "--name",
+      name,
+      "--timeout",
+      String(timeoutMs),
+      "--status",
+      statusFile,
+      headless ? "--headless" : "--headful",
+    ],
+    {
+      detached: true,
+      stdio: ["ignore", fd, fd],
+      cwd: ROOT,
+      env: { ...process.env },
+    },
+  );
+  child.unref();
+  fs.closeSync(fd);
+  return {
+    ok: true,
+    started: true,
+    profile: name,
+    pid: child.pid,
+    status_file: statusFile,
+    log_path: logPath,
+    qr_path: path.join(CACHE_DIR, "login", "*.png"),
+    hint:
+      "Login worker started. Wait a few seconds, read status_file for qr_path, scan the PNG with Feishu, then call lark_auth action=check.",
+  };
+}
+
+export function loginStatus(name = "default") {
+  const statusFile = statusFileFor(name);
+  if (!fs.existsSync(statusFile)) {
+    return { ok: false, profile: name, status_file: statusFile, error: "no login status yet" };
+  }
+  return { ok: true, profile: name, status_file: statusFile, ...readJson(statusFile, {}) };
+}
+
+export function logout(name) {
+  if (!name) throw new Error("profile name is required");
+  return removeProfile(name);
+}
+
+export function importAuth({ file, cookie, name = "default", active = true } = {}) {
+  let input = cookie;
+  if (file) {
+    const text = fs.readFileSync(path.resolve(file), "utf8");
+    try {
+      input = JSON.parse(text);
+    } catch {
+      input = text;
+    }
+  }
+  if (!input) throw new Error("cookie or file is required");
+  return importProfiles(input, { active });
+}
+
+export function authDispatch({
+  action,
+  profile,
+  name,
+  browser,
+  file,
+  cookie,
+  wait,
+  timeout_ms: timeoutMs,
+  headless,
+} = {}) {
+  switch (action) {
+    case "list":
+      return authList();
+    case "whoami":
+      return whoami({ profile });
+    case "check":
+      return checkAuth({ profile });
+    case "use":
+      return useProfile(name || profile);
+    case "cookie":
+      return cookieFor(profile);
+    case "login":
+      return startLogin(name || profile || "default", {
+        timeoutMs,
+        wait,
+        headless: headless !== false && browser !== "headful",
+      });
+    case "login_status":
+      return loginStatus(name || profile || "default");
+    case "import":
+      return importAuth({ file, cookie, name: name || profile || "default" });
+    case "logout":
+      return logout(name || profile);
+    default:
+      throw new Error(
+        `unknown auth action: ${action}; expected list|whoami|check|use|cookie|login|login_status|import|logout`,
+      );
+  }
+}