larkit 0.0.0-stage → 0.1.0

package/verified_truths/card-json-2.0-official.md

@@ -0,0 +1,55 @@
+---
+topic: 卡片 JSON 2.0 全局结构与 chart_spec
+verified_at: 2026-11-15T00:00:00.000Z
+source: doc
+confidence: high
+tags: [card, json2.0, chart_spec, card_link]
+---
+
+## 结论
+
+飞书卡片 JSON 2.0 通过顶层 `"schema": "2.0"` 声明；全局字段包括 `config`、`card_link`、`header`、`body`。
+图表组件位于 `body.elements[]`，`tag` 为 `"chart"`，其图表定义字段名为 `chart_spec`（VChart spec）。
+平台会对 `chart_spec` 自动追加媒体查询；在 `chart_spec` 中设置 `"media": []` 可禁用默认追加。
+
+## card_link 结构
+
+```json
+{
+  "card_link": {
+    "url": "https://www.example.com",
+    "android_url": "https://developer.android.com/",
+    "ios_url": "https://developer.apple.com/",
+    "pc_url": "https://www.windows.com"
+  }
+}
+```
+
+## chart 组件骨架
+
+```json
+{
+  "schema": "2.0",
+  "body": {
+    "elements": [
+      {
+        "tag": "chart",
+        "element_id": "custom_id",
+        "aspect_ratio": "16:9",
+        "color_theme": "brand",
+        "chart_spec": {
+          "type": "bar",
+          "data": [{ "x": "A", "y": 1 }],
+          "media": []
+        }
+      }
+    ]
+  }
+}
+```
+
+## 证据
+
+- 卡片 JSON 2.0 结构：https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure
+- 图表组件（含 `chart_spec` 说明）：https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/content-components/chart
+- 通过 `document_portal/v1/document/get_detail?fullPath=...` 读取官方正文，确认 `chart_spec` 与 `card_link` 字段存在。

package/verified_truths/client-ws-gateway-boundaries.md

@@ -0,0 +1,33 @@
+---
+topic: 客户端 WS / gateway 探针实测边界
+verified_at: 2026-11-15T07:05:00.000Z
+source: probe
+confidence: high
+tags: [client, websocket, gateway, probe]
+---
+
+## 结论
+
+- `connect()` 用网页版 Cookie（必须含 `passport_web_did`）可以建立
+  `wss://msg-frontier.feishu.cn/ws/v2` 长连接；实测收到 `cmd=7001`
+  （`device.PushDeviceOnlineStatus`）与 `cmd=7017`
+  （`device.PushDeviceNetworkAccessEvent`），protobuf 能解出业务字段。
+- `PUSH_MESSAGES(6)` 是推送命令，不应主动发送；发送会收到
+  `packet.status=200, sid="command: 6 not found"`。探针应使用
+  `wait_push=true` 只监听。
+- 客户端 pb 网关 `POST https://internal-api-lark-api.feishu.cn/im/gateway/`
+  可以发送请求命令并解回 `improto.Packet`。读命令 `GET_CHAT_MESSAGES(1020)`
+  实测返回 HTTP 400，`sid="PullFeedGroups invalid request"`，说明读消息不在
+  这个网关路由；读消息走开放 API 或网页版另一条 HTTP 通道。
+- 官方 OpenAPI 探针可用应用凭据换 `tenant_access_token`，再请求
+  `/open-apis/im/v1/chats`；有权限时返回 `code:0`，无权限时返回真实错误码
+  （如 `99991672`），适合验证隐藏字段与权限边界。
+
+## 证据
+
+- `lark_probe(mode=client, command=PUSH_MESSAGES, transport=ws, wait_push=true)`
+  -> `handshake=true`，events 含 7001/7017 解码结果。
+- `lark_probe(mode=client, command=GET_CHAT_MESSAGES, transport=gateway)`
+  -> HTTP 400，decoded packet sid `PullFeedGroups invalid request`。
+- `lark_probe(mode=openapi, path=/im/v1/chats)` -> token 换取成功，返回真实
+  `code/msg/log_id`。

package/verified_truths/feishu-developer-console-apis.md

@@ -0,0 +1,104 @@
+---
+topic: 飞书开发者后台内部 REST API（Console）
+verified_at: 2026-11-15T07:00:00.000Z
+source: probe
+confidence: high
+tags: [console, developer, app, scopes, websocket, publish]
+---
+
+## 结论
+
+飞书开发者后台（`https://open.feishu.cn/app`）的内部 API 前缀是
+`https://open.feishu.cn/developers`，默认 `POST application/json`，返回
+`{ code, msg, data }`。带 Cookie 登录后，还必须带 `x-csrf-token`，其值取自
+后台 HTML 的 `window.csrfToken`（88 字符），并且 Cookie 中要有页面响应下发的
+`lark_oapi_csrf_token`（44 字符）。只带 `swp_csrf_token` 会返回
+`{"code":9499,"msg":"lark_oapi_csrf_token not exist in cookie"}`。
+
+## 应用
+
+```http
+POST /developers/v1/app/list
+body: {"Count":20,"Cursor":0}
+# data.apps[] -> appID/name/ability/version/owner...
+
+POST /developers/v1/app/create
+body: {"fromProduct":0,"appSceneType":0,"name":"x","desc":"","avatar":"",
+       "primaryLang":"zh_cn","i18n":{"zh_cn":{"name":"x","description":""}}}
+# data.ClientID / data.Avatar
+
+POST /developers/v1/app/:clientId
+body: {}
+
+POST /developers/v1/secret/:clientId
+body: {}
+# data.secret
+
+POST /developers/v1/base_info/:clientId
+body: {"clientId":"cli_x","name":"new","desc":"...","i18n":{"zh_cn":{"name":"new"}}}
+```
+
+## 权限
+
+```http
+POST /developers/v1/scope/all/:clientId
+body: {"clientId":"cli_x"}
+# data.scopes[] {id,name,bizId,status,levels,...}, data.scopeBizs[]
+
+POST /developers/v1/scope/update/:clientId
+body: {"clientId":"cli_x","operation":"add","scopeIds":[],
+       "appScopeIDs":["20001"],"userScopeIDs":[]}
+```
+
+`im:message` 的 scope id 是 `20001`（实测）。批量开通时按 scope 名称从
+`scope/all` 解析 id，再放入 `appScopeIDs`（应用身份）或 `userScopeIDs`（用户身份）。
+
+## 机器人 / 事件 / 卡片回调（长连接）
+
+```http
+POST /developers/v1/robot/:clientId          # data.enable, data.cardCallbackMode
+POST /developers/v1/robot/switch/:clientId   # {"clientId":"cli_x","enable":true}
+
+POST /developers/v1/event/:clientId          # data.eventMode; 4 = WebSocket
+POST /developers/v1/event/switch/:clientId   # {"clientId":"cli_x","eventMode":4}
+
+POST /developers/v1/callback/:clientId       # data.callbackMode; 4 = WebSocket
+POST /developers/v1/callback/switch/:clientId# {"clientId":"cli_x","callbackMode":4}
+```
+
+- `eventMode=4` 与 `callbackMode=4` 即事件订阅/卡片回调的 WebSocket 长连接模式。
+- `robot.cardCallbackMode` 是卡片请求地址模式（1=Webhook），不是长连接开关；
+  不要把它当成 `callbackMode`。实测向 `/v2/robot/push_mode/switch/:clientId`
+  传 `callbackMode:4` 会返回 `ParamInvalid`。
+
+## 版本与发布
+
+```http
+POST /developers/v1/app_version/list/:clientId
+body: {"clientId":"cli_x"}
+# data.versions[] {versionId,appVersion,versionStatus,publishTime,...}
+
+POST /developers/v1/app_version/create/:clientId
+body: {"clientId":"cli_x","appVersion":"1.0.0","updateRemark":"...",
+       "visibleSuggest":{},"changeLog":"..."}
+# data.versionId
+
+POST /developers/v1/publish/commit/:clientId/:versionId
+body: {"clientId":"cli_x","versionId":"...","is_full_release":false}
+
+POST /developers/v1/publish/release/:clientId/:versionId
+body: {"clientId":"cli_x","versionId":"...","is_full_release":false}
+```
+
+## 证据
+
+- 2026-11-15 使用 `geren` profile 实测：`POST /developers/v1/app/list` 返回 `code:0`，15 个应用。
+- 创建测试应用 `larkit-e2e-20261115` -> `cli_aa73eb66fcb89cf4`，返回 `code:0`。
+- `POST /developers/v1/secret/:clientId` 返回 32 字符 secret。
+- `switch_robot` / `switch_event` / `switch_callback` 均返回 `code:0`；
+  复查 `eventMode=4`、`callbackMode=4`。
+- `scope/update` 添加 `im:message` 返回 `code:0`。
+- `app_version/create` + `publish/commit` 返回 `code:0`，版本 `1.0.0` 进入提交状态。
+- 浏览器兜底实测捕获到 `/developers/v1/tenant_app/auth_info/get`、
+  `/developers/v1/message/unread_list` 等真实请求，并写入
+  `.larkit-data/console-api-recipes.json`。

package/workers/truth-api/src/index.js

@@ -0,0 +1,180 @@
+/**
+ * larkit truth channel API (Cloudflare Worker).
+ *
+ * A single stable URL that always answers "what is the current truth pack, and
+ * where do I download it from":
+ *
+ *   GET /v1/truth/latest        → manifest of the current pack (schemaVersion 1)
+ *   GET /v1/truth/<tag>         → manifest of a pinned pack (immutable)
+ *   GET /v1/truth               → index: every published tag + sha256
+ *   GET /health                 → liveness
+ *
+ * The Worker reads the objects that `scripts/publish-pack.mjs` writes into the
+ * R2 bucket (manifest.json / <tag>.json / index.json) and turns them into an
+ * API response: no duplicated state, no rebuild step, publishing stays one
+ * upload.  `ETag` is the archive sha256, so clients can do conditional GETs.
+ */
+
+const CACHE_LATEST = "public, max-age=60, stale-while-revalidate=600";
+const CACHE_IMMUTABLE = "public, max-age=31536000, immutable";
+
+function jsonHeaders(extra = {}) {
+  return {
+    "content-type": "application/json; charset=utf-8",
+    "access-control-allow-origin": "*",
+    "access-control-allow-headers": "if-none-match, content-type",
+    "access-control-allow-methods": "GET, HEAD, OPTIONS",
+    ...extra,
+  };
+}
+
+function json(payload, { status = 200, headers = {} } = {}) {
+  return new Response(`${JSON.stringify(payload, null, 2)}\n`, {
+    status,
+    headers: jsonHeaders(headers),
+  });
+}
+
+function fail(status, message) {
+  return json({ error: message, status }, { status });
+}
+
+function archiveSha(manifest) {
+  return (
+    manifest?.tiers?.full?.sha256 ||
+    manifest?.tiers?.core?.sha256 ||
+    null
+  );
+}
+
+/** Pin absolute download URLs to the public bucket host, if configured. */
+function rewriteUrls(manifest, base) {
+  if (!base) return manifest;
+  const root = String(base).replace(/\/+$/, "");
+  for (const tier of Object.values(manifest.tiers || {})) {
+    if (!tier?.file) continue;
+    tier.url = `${root}/${tier.file}`;
+  }
+  return manifest;
+}
+
+async function readJson(env, key) {
+  const object = await env.TRUTH.get(key);
+  if (!object) return null;
+  const text = await object.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function decodeTag(tag) {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(tag) ? tag : null;
+}
+
+async function serveManifest(request, env, key, { immutable }) {
+  const manifest = await readJson(env, key);
+  if (!manifest) return fail(404, `no such pack manifest: ${key}`);
+
+  const payload = rewriteUrls({ ...manifest }, env.PUBLIC_BASE);
+  const sha = archiveSha(payload);
+  const tag = payload.packVersion || payload.larkitVersion || null;
+  const etag = sha ? `"${sha.slice(0, 32)}"` : null;
+  if (etag && request.headers.get("if-none-match") === etag) {
+    return new Response(null, { status: 304, headers: jsonHeaders({ etag, "cache-control": immutable ? CACHE_IMMUTABLE : CACHE_LATEST }) });
+  }
+
+  const headers = {
+    "cache-control": immutable ? CACHE_IMMUTABLE : CACHE_LATEST,
+    "x-larkit-pack": tag || "unknown",
+  };
+  if (etag) headers.etag = etag;
+  return json(
+    {
+      ...payload,
+      channel: "stable",
+      api: { version: 1, servedAt: new Date().toISOString(), tag },
+    },
+    { headers },
+  );
+}
+
+async function serveIndex(env) {
+  const index = await readJson(env, "index.json");
+  if (!index) return fail(503, "channel index is not published yet");
+  const base = new URL(env.PUBLIC_API || "https://larkit-api.tapeless.eu.org");
+  const packs = (index.packs || []).map((entry) => ({
+    tag: entry.tag,
+    builtAt: entry.builtAt || null,
+    larkitVersion: entry.larkitVersion || null,
+    clientVersion: entry.clientVersion || null,
+    stats: entry.stats || null,
+    manifest: entry.tag ? `${base.origin}/v1/truth/${entry.tag}` : null,
+    tiers: entry.tiers || {},
+  }));
+  return json(
+    {
+      api: { version: 1, servedAt: new Date().toISOString() },
+      latest: index.latest || packs[packs.length - 1]?.tag || null,
+      packs,
+    },
+    { headers: { "cache-control": CACHE_LATEST } },
+  );
+}
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (request.method === "OPTIONS") {
+      return new Response(null, { status: 204, headers: jsonHeaders() });
+    }
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return fail(405, "method not allowed");
+    }
+
+    const path = url.pathname.replace(/\/+$/, "");
+
+    // Tombstone for the retired core/code split archives.  The objects are
+    // deleted from R2, but the edge may still hold `immutable` copies for up to
+    // a year; a Worker route bypasses that cache and answers immediately.
+    if (/^\/larkit-truth-(core|code)-/.test(path)) {
+      return json(
+        {
+          error: "gone",
+          status: 410,
+          message:
+            "The core/code split packs were retired. larkit now installs one unified archive: " +
+            "GET /v1/truth/latest for the current pack manifest.",
+        },
+        { status: 410, headers: { "cache-control": "public, max-age=300" } },
+      );
+    }
+
+    if (path === "/health") {
+      return json({ ok: true, service: "larkit-truth", time: new Date().toISOString() });
+    }
+    if (path === "" || path === "/") {
+      return json({
+        service: "larkit-truth",
+        docs: "https://github.com/…", // placeholder, see README
+        endpoints: {
+          latest: "/v1/truth/latest",
+          pinned: "/v1/truth/<tag>",
+          index: "/v1/truth",
+          health: "/health",
+        },
+      });
+    }
+    if (!path.startsWith("/v1/truth")) return fail(404, "not found");
+
+    const rest = path.slice("/v1/truth".length).replace(/^\//, "");
+    if (!rest || rest === "index") return serveIndex(env);
+    if (rest === "latest") {
+      return serveManifest(request, env, "manifest.json", { immutable: false });
+    }
+    const tag = decodeTag(rest);
+    if (!tag) return fail(400, "invalid tag");
+    return serveManifest(request, env, `${tag}.json`, { immutable: true });
+  },
+};

package/workers/truth-api/wrangler.toml

@@ -0,0 +1,31 @@
+name = "larkit-truth-api"
+main = "src/index.js"
+compatibility_date = "2025-01-01"
+workers_dev = true
+
+# 真相源对象（manifest.json / <tag>.json / index.json + tar.gz 归档）
+[[r2_buckets]]
+binding = "TRUTH"
+bucket_name = "larkit-truth"
+
+[vars]
+# 归档的公开域名（R2 自定义域名）；Worker 会把 manifest 里的下载链接重写到它上面
+PUBLIC_BASE = "https://larkit.tapeless.eu.org"
+# 本 API 自己的公开地址，用于在 index 里生成 <tag> 的 API 链接
+PUBLIC_API = "https://larkit.tapeless.eu.org"
+
+# 固定入口：https://larkit.tapeless.eu.org/v1/truth/latest
+# 首选入口：和下载域名同一个 host，只管 /v1/*，其余路径继续由 R2 提供
+[[routes]]
+pattern = "larkit.tapeless.eu.org/v1/*"
+zone_name = "tapeless.eu.org"
+
+# 已下线的 core/code 分体归档：对象已从 R2 删除，但边缘仍可能命中 immutable 缓存
+# （最长 1 年）。这两条 route 让 Worker 直接回 410，绕开缓存。
+[[routes]]
+pattern = "larkit.tapeless.eu.org/larkit-truth-core-*"
+zone_name = "tapeless.eu.org"
+
+[[routes]]
+pattern = "larkit.tapeless.eu.org/larkit-truth-code-*"
+zone_name = "tapeless.eu.org"