herdrchat 0.0.0-stage → 0.1.0

package/lib/readers/index.mjs

@@ -0,0 +1,24 @@
+// Readers: how the bot gets what an agent said from the agent's own records, so nothing
+// is lost and the group shows it while the agent works. hc stays the backbone (which
+// terminals exist, their status, when a turn ends, typing into them); a reader adds the
+// conversation. A program with no reader gets the default: its screen through `hc read`.
+//
+// A reader is a module that exports:
+//   app                              the name the agent gives in its hc status (`status.app`)
+//   after(session, address, cursor)  -> {items, file} | null: what is new since `cursor`
+//                                       (null: this terminal is not readable); `file` is
+//                                       the log it read, kept in the cursor
+//   rest(session, address, cursor)   -> items: what `cursor.file` still holds after the
+//                                       program is gone
+// Items are {role: 'you' | 'ai' | 'tool', text, at, id, end?} (`end` marks the turn's last
+// answer) or {role: 'image', from: 'you' | 'ai', media, data (base64), at, id}.
+// Cursors are in ../cursor.mjs.
+//
+// To add an agent: write lib/readers/<agent>.mjs and list it here.
+import * as claude from './claude.mjs';
+
+const READERS = new Map([claude].map((r) => [r.app, r]));
+
+export function readerFor(app) {
+  return READERS.get(app) || null;
+}

package/lib/userauth.mjs

@@ -0,0 +1,119 @@
+// Acting as you (user_access_token), for the few chat-list settings Feishu lets only you
+// change: mute a group, put it in one of your feed groups (labels), pin it. You allow it
+// once with the OAuth device flow (`/auth` in the direct chat), which needs no public address: the bot shows a link
+// and a code, you confirm in Feishu, the bot polls for the token. The token is refreshed
+// before it expires and kept in user-token.json in the state folder (mode 600), never logged.
+// Only the calls in this file are made with it.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ACCOUNTS = 'https://accounts.feishu.cn';
+const OPEN = 'https://open.feishu.cn';
+export const USER_SCOPES = ['im:chat.user_setting:write', 'im:feed_group_v1:read', 'im:feed_group_v1:write', 'im:feed.shortcut:write', 'offline_access'];
+const EARLY_MS = 5 * 60 * 1000; // refresh this long before the token runs out
+
+export function createUserAuth(cfg, dir) {
+  const file = path.join(dir, 'user-token.json');
+  const basic = Buffer.from(`${cfg.appId}:${cfg.appSecret}`).toString('base64');
+
+  const load = () => {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      return null;
+    }
+  };
+  const save = (t) => {
+    fs.writeFileSync(`${file}.tmp`, JSON.stringify(t), { mode: 0o600 });
+    fs.renameSync(`${file}.tmp`, file);
+  };
+  const keep = (res) => {
+    const now = Date.now();
+    const old = load() || {};
+    const t = {
+      access: res.access_token,
+      accessUntil: now + (res.expires_in || 7200) * 1000,
+      refresh: res.refresh_token || old.refresh,
+      refreshUntil: res.refresh_token ? now + (res.refresh_token_expires_in || 7 * 86400) * 1000 : old.refreshUntil,
+      scope: res.scope || old.scope,
+    };
+    save(t);
+    return t;
+  };
+
+  async function form(url, body, auth) {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', ...(auth ? { Authorization: `Basic ${basic}` } : {}) },
+      body: new URLSearchParams(body),
+    });
+    return res.json();
+  }
+
+  // Step 1: a link and a code for you. Step 2 (`waitForToken`) polls until you confirm.
+  async function startDeviceFlow() {
+    const r = await form(`${ACCOUNTS}/oauth/v1/device_authorization`, { client_id: cfg.appId, scope: USER_SCOPES.join(' ') }, true);
+    if (!r.device_code) throw new Error(`device authorization: ${JSON.stringify(r).slice(0, 200)}`);
+    return r;
+  }
+
+  async function waitForToken(device) {
+    let interval = (device.interval || 5) * 1000;
+    const until = Date.now() + (device.expires_in || 240) * 1000;
+    while (Date.now() < until) {
+      await new Promise((ok) => setTimeout(ok, interval));
+      const r = await form(`${ACCOUNTS}/oauth/v3/token`, {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        device_code: device.device_code,
+        client_id: cfg.appId,
+        client_secret: cfg.appSecret,
+      });
+      if (r.access_token) return keep(r);
+      if (r.error === 'slow_down') interval += 5000;
+      else if (r.error !== 'authorization_pending') throw new Error(`authorization: ${r.error || JSON.stringify(r).slice(0, 200)}`);
+    }
+    throw new Error('authorization: the code expired before it was confirmed');
+  }
+
+  async function token() {
+    const t = load();
+    if (!t?.access) return null;
+    if (Date.now() < t.accessUntil - EARLY_MS) return t.access;
+    if (!t.refresh || Date.now() > (t.refreshUntil || 0)) return null;
+    const res = await fetch(`${ACCOUNTS}/oauth/v3/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      body: JSON.stringify({ grant_type: 'refresh_token', refresh_token: t.refresh, client_id: cfg.appId, client_secret: cfg.appSecret }),
+    });
+    const r = await res.json();
+    if (!r.access_token) throw new Error(`token refresh: ${r.error || JSON.stringify(r).slice(0, 200)}`);
+    return keep(r).access;
+  }
+
+  // One call as you; null when you have not allowed it (or it ran out).
+  async function call(method, apiPath, body) {
+    const access = await token();
+    if (!access) return null;
+    const res = await fetch(`${OPEN}${apiPath}`, {
+      method,
+      headers: { Authorization: `Bearer ${access}`, 'Content-Type': 'application/json; charset=utf-8' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const r = await res.json();
+    if (r.code) throw new Error(`${method} ${apiPath} ${r.code}: ${r.msg}`);
+    return r.data || {};
+  }
+
+  return {
+    startDeviceFlow,
+    waitForToken,
+    allowed: async () => Boolean(await token().catch(() => null)),
+    setMuted: (chatIds, muted) => call('POST', '/open-apis/im/v1/chat_user_setting/batch_update', { chat_settings: chatIds.map((chat_id) => ({ chat_id, is_muted: muted })) }),
+    feedGroups: () => call('GET', '/open-apis/im/v1/groups?page_size=50&page_token='),
+    createFeedGroup: (name) => call('POST', '/open-apis/im/v1/groups', { feed_group_creator: { name, type: 'normal' } }),
+    addToFeedGroup: (groupId, chatIds) => call('POST', `/open-apis/im/v1/groups/${groupId}/batch_add_item`, { items: chatIds.map((feed_id) => ({ feed_id, feed_type: 'chat' })) }),
+    removeFromFeedGroup: (groupId, chatIds) => call('POST', `/open-apis/im/v1/groups/${groupId}/batch_remove_item`, { items: chatIds.map((feed_id) => ({ feed_id, feed_type: 'chat' })) }),
+    pin: (chatId) => call('POST', '/open-apis/im/v2/feed_shortcuts', { is_header: true, shortcuts: [{ feed_card_id: chatId, type: 1 }] }),
+    unpin: (chatId) => call('POST', '/open-apis/im/v2/feed_shortcuts/remove', { shortcuts: [{ feed_card_id: chatId, type: 1 }] }),
+  };
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "herdrchat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Chat front-ends for hc: every terminal hc runs, in the chat app you use",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhangxiangliang/herdrchat.git"
+  },
+  "homepage": "https://github.com/zhangxiangliang/herdrchat#readme",
+  "bugs": "https://github.com/zhangxiangliang/herdrchat/issues",
+  "scripts": {
+    "start": "node bin/cli.mjs run",
+    "test": "node --test test/*.test.mjs"
+  },
+  "author": "zhangxiangliang",
+  "license": "MIT",
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.76.0"
+  },
+  "type": "module",
+  "bin": {
+    "herdrchat": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "docs/",
+    "config.env.example",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/README.md

@@ -0,0 +1,9 @@
+# Skills
+
+`herdrchat/` is the one skill: an agent that reads `SKILL.md` (Claude Code and others) uses
+it to set up, run and look after herdrchat. Its commands are `/herdrchat <command>`.
+
+Each part of the system has one reference under `herdrchat/references/`, named after the
+part: a chat app (`feishu.md`, later `slack.md`, `discord.md`, `telegram.md`) or a part of
+the core (`ops.md`, later `reader.md`). New work goes into the reference of its part, or
+a new one for a new part; `SKILL.md` only lists commands and points to references.

package/skills/herdrchat/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: herdrchat
+description: Set up, run and look after herdrchat, the chat front-end for hc that mirrors every hc terminal into Feishu (one group per terminal, dialog buttons, an overview, quiet phones) - first setup with the Feishu app, start and stop, status and logs, /auth, settings, fixing problems, and the Feishu developer console (with Ego, or guided click by click). Use for anything about herdrchat or its Feishu bot, even when the user only says "set up the Feishu bot", "is it running", "it doesn't post", "mute the workers" or "publish the bot". Trigger with "/herdrchat", "/herdrchat setup", "/herdrchat status", "/herdrchat fix".
+---
+
+# herdrchat
+
+herdrchat mirrors every terminal hc runs into a chat app, Feishu first: one group per
+terminal, the conversation as it happens, dialogs as buttons, an overview in the direct
+chat. Its command is `herdrchat` (`node bin/cli.mjs` in a clone): check with
+`command -v herdrchat`; when it is missing, ask before `npm install -g herdrchat`. A
+profile (`--profile`, default `default`) keeps its settings
+in `~/.config/herdrchat/<profile>/config.env` and its state in
+`~/.local/state/herdrchat/<profile>/`; `herdrchat status` prints both.
+
+## Commands
+
+| Command | Do |
+|---|---|
+| `/herdrchat setup` | First time, in order: `herdrchat init`; make the Feishu app (`references/feishu.md`: create, bot, scopes, events and callbacks); fill `config.env` with the user (app id, secret, `HERDR_SESSIONS`: the hc sessions herdr-app shows on this machine); `herdrchat start`; publish a version; get the user's open_id (they message the bot, it answers with it) into `FEISHU_OWNER_OPEN_ID`; start again. Optional: `/herdrchat auth`. |
+| `/herdrchat status` | `herdrchat status`; explain each line; on errors, `/herdrchat fix`. |
+| `/herdrchat start`, `/herdrchat stop` | Read `config.env` (its `HERDR_SESSIONS`) in one step, then `herdrchat start` / `stop` in the next; never both at once. |
+| `/herdrchat logs` | `herdrchat logs --errors` (or `-n 100`); explain them with `references/ops.md` "Logs". |
+| `/herdrchat auth` | The user sends `/auth` to the bot and allows it on Feishu's page; the app needs the user scopes in `references/feishu.md`. Then groups are muted, labels and pins follow. |
+| `/herdrchat config` | Change a setting in `config.env` with the user (sessions, `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES`, `HERDR_BOT_TAGS`, `HERDR_USER_TAGS`; each is explained in `config.env.example`), read the file back, then restart. |
+| `/herdrchat fix` | Find the cause from `herdrchat status`, the logs and the live result, then fix it: `references/ops.md`. |
+| `/herdrchat feishu <task>` | Anything in the Feishu developer console: scopes, callbacks, publishing, the icon, deleting an app: `references/feishu.md`. |
+
+With no subcommand, run `herdrchat status` and suggest the next step from it.
+
+## Rules
+
+- Ask before anything outward-facing: publishing a version, applying scopes, deleting or
+  disbanding anything, sending to a real group. One yes covers one action.
+- Never print, screenshot or paste `FEISHU_APP_SECRET` or `user-token.json`.
+- A check that decides an action runs on its own first (read the config, then start;
+  scan, then commit).
+- Say what was checked on the live bot and what was not.
+
+## References
+
+- `references/feishu.md`: the bot's app in the Feishu developer console, with Ego or as a
+  guided walk-through; the scopes this bot uses.
+- `references/ops.md`: running and checking the bot, its logs and state, the usual
+  problems, trying a Feishu API safely, committing without a leak.

package/skills/herdrchat/references/feishu.md

@@ -0,0 +1,150 @@
+# Feishu: the bot's app in the developer console
+
+herdrchat's Feishu bot has settings that live in Feishu, not in this repo; they are
+changed in the Feishu developer console (`https://open.feishu.cn/app`). This reference does
+that with ego-browser, in the user's own logged-in browser.
+
+## Before anything
+
+1. **ego-browser.** Run `command -v ego-browser`. When it is there, run
+   `ego-browser skill` and follow its usage guide. When it is missing, do not fall back
+   to another browser; ask the user which they want:
+   - install Ego Lite (https://lite.ego.app/), sign in to Feishu in it, and ask again,
+     so the agent does the clicking; or
+   - a guided walk-through instead (see "Guide mode" below): the user clicks, the agent
+     says what to click.
+2. **Which profile.** Ask which Ego profile is signed in to Feishu as an admin of the
+   tenant that owns the app (`await profiles()` lists them); never guess. Create one task
+   space for the whole job with that `profileId`, and close it at the end with
+   `await task.finish({ keep: [] })`.
+3. **Which app.** The app id is `FEISHU_APP_ID` in the profile's `config.env`
+   (`~/.config/herdrchat/<profile>/config.env`, or in `HERDRCHAT_HOME`). Read only that
+   key; never print, screenshot or paste `FEISHU_APP_SECRET`, and never write a real app
+   id, open_id, chat id or tenant name into a file of this repo.
+4. **Ask first** before anything outward-facing: publishing a version, applying scopes,
+   deleting or deactivating an app. One yes covers one action.
+
+## Guide mode (no Ego)
+
+The same procedures, done by the user. Give one step at a time, with the page link and
+the exact button text as Feishu shows it (the Chinese labels below), and wait for the
+user to say it is done before the next step. Where a procedure says to check something
+(the confirm list, 已开通, 已发布), ask the user what the page shows. Never ask the user
+to paste the app secret into the chat.
+
+## Pages
+
+| What | URL |
+|---|---|
+| Basic info, icon, credentials | `https://open.feishu.cn/app/<APP_ID>/baseinfo` |
+| Add capabilities (bot) | `https://open.feishu.cn/app/<APP_ID>/capability` |
+| Scopes | `https://open.feishu.cn/app/<APP_ID>/auth` |
+| Events and callbacks | `https://open.feishu.cn/app/<APP_ID>/event` (`?tab=callback` for callbacks) |
+| Versions and publishing | `https://open.feishu.cn/app/<APP_ID>/version` |
+
+The console is a slow single-page app: after `goto` or a click, wait (2-3 s, or
+`waitForFunction` on the text you expect) before reading it. Find buttons by their
+visible text with `page.evaluate` (`[...document.querySelectorAll("button")]`), not by
+position: the layout shifts when a banner appears. Take a screenshot before each click
+that applies or publishes something, and read it.
+
+## Procedures
+
+### Create the app (first setup only)
+
+Developer console home -> create a custom app (企业自建应用) with a name, a description
+and an icon -> Add capabilities -> Bot. Then import the scopes, set events and
+callbacks, start the bot (`herdrchat start`) and publish. The "Set up" section of `docs/guide.md`
+lists the same steps from the repo's side.
+
+### Import scopes
+
+Scopes page -> 批量处理 -> 批量导入/导出权限. Paste the JSON from "Scopes this bot uses"
+below (only the ones still missing is fine; the dialog skips what is there).
+
+- **Click inside the editor's text first, then select all and replace.** Pressing
+  select-all before the editor has focus selects the whole page, and the import then
+  submits the editor's default sample (`docx:document:readonly`) instead of yours.
+- Read the editor back before going on: the lines are in `.view-lines .view-line`.
+- Next step (下一步，确认新增权限) opens a confirm dialog listing the scopes it will add,
+  by their Chinese names, split into bot (应用身份) and user (用户身份) tabs. Check that
+  list matches what you meant to add, then (after the user's yes) 申请开通.
+- Verify on the scopes page that each one reads 已开通. Most of these are review-free
+  and live at once; the page header then still says 当前修改均已发布. When it says
+  版本发布后，当前修改方可生效 instead, publish a version.
+- Unknown scope names are dropped silently, so a missing one in the confirm list means
+  a typo or a scope that does not exist.
+
+### Events and card callbacks
+
+Both must use the long connection (长连接), which needs the bot running.
+
+- Events (事件配置): subscription mode -> long connection; add `im.message.receive_v1`.
+- Callbacks (回调配置): edit the subscription mode -> 使用长连接接收回调 -> 验证 (it must
+  answer 连接成功; if not, the bot is not running) -> 保存 -> 添加回调 -> card ->
+  `card.action.trigger` (not the old `card.action.trigger_v1`, which cannot use the long
+  connection) -> 添加. Without it, a click on a dialog button fails with error 200340.
+- Publish a version afterwards.
+
+### Publish a version
+
+Versions page -> 创建版本 (the form loads slowly; wait for the 保存 button). Check the
+version number (one above the last) and that the green bar says 本次发布免审核; if it
+does not, the version goes to the tenant admin for review - tell the user. 保存 ->
+确认发布 -> reload the versions page and check the new version reads 已发布.
+
+### Change the app icon (the bot's avatar)
+
+Basic info -> the edit pen next to 综合信息 -> `page.setInputFiles("input[type=file]",
+[<absolute path>])` with a square JPEG/PNG/SVG/BMP over 240x240 px, under 2 MB, without
+rounded corners -> 保存 in the crop dialog -> 保存 under the form. Then publish a
+version; the client may need a while or a restart to show it.
+
+### Delete an app
+
+The developer console's delete button stays disabled while the app is enabled.
+Deactivate it first in the tenant admin console,
+`https://<tenant>.feishu.cn/admin/appCenter/manage/<APP_ID>` (needs a tenant admin),
+then delete it in the developer console. Ask before each of the two steps.
+
+## Scopes this bot uses
+
+Bot identity (the bot itself) and user identity (only for `/auth`, acting as the user):
+
+```json
+{
+  "scopes": {
+    "tenant": [
+      "im:message:send_as_bot",
+      "im:message.p2p_msg:readonly",
+      "im:message.group_msg",
+      "im:message:readonly",
+      "im:message.reactions:write_only",
+      "im:resource",
+      "im:chat:create",
+      "im:chat:update",
+      "im:tag:write",
+      "im:biz_entity_tag_relation:write"
+    ],
+    "user": [
+      "im:chat.user_setting:write",
+      "im:feed_group_v1:read",
+      "im:feed_group_v1:write",
+      "im:feed.shortcut:write",
+      "offline_access"
+    ]
+  }
+}
+```
+
+What each is for is in `docs/guide.md` ("Set up" and "Optional: let the bot act as you").
+A scope the code does not call is not added.
+
+## Traps seen
+
+- Select-all before the editor has focus selects the page (see Import scopes).
+- A button found by position moved under a banner; find it by its text.
+- `evaluate` on the version form ran before it loaded and found no 保存; wait for it.
+- The callback "verify" fails when the bot is not running; start it first.
+- Changes on the scopes page that need a version say so in the header; review-free
+  scopes do not, and publishing for them is not needed.

package/skills/herdrchat/references/ops.md

@@ -0,0 +1,106 @@
+# Ops: running and looking after herdrchat
+
+The bot is `bin/herdrchat.mjs`. It runs in an hc terminal named `herdrchat`, in the first
+hc session listed in `HERDR_SESSIONS`; `herdrchat start` (re)starts it and keeps it
+running (`node bin/cli.mjs` from a clone). A profile (`--profile` or `HERDRCHAT_PROFILE`,
+default `default`; another one runs as the hc terminal `herdrchat-<profile>`) has its
+settings in `~/.config/herdrchat/<profile>/config.env` and writes to
+`~/.local/state/herdrchat/<profile>/` (call it `D` below), unless `HERDRCHAT_HOME` holds
+both (`config.env`, `state/`). Its settings in Feishu itself (scopes, callbacks, icon,
+versions) are in `references/feishu.md`.
+
+Below, `S` is the first session in `HERDR_SESSIONS`.
+
+## Is it running
+
+```sh
+HC_SESSION=S hc get herdrchat --json      # state "live"
+HC_SESSION=S hc read herdrchat --lines 40 # its terminal: start lines, "[feishu] connected"
+herdrchat status                              # running, folders, /auth, errors today
+herdrchat start                               # restart (stops the old one first)
+```
+
+A restart is needed after any code or `config.env` change. It is safe: what was posted
+is in `D/state.json`, so it picks up where it stopped.
+
+## Logs
+
+`D/logs/<YYYY-MM-DD>.log`, one file a day, 14 kept, lines `<time> <LEVEL> <text>`:
+
+```sh
+grep -h ERROR D/logs/*.log | tail -20   # what went wrong
+grep -h WARN  D/logs/*.log | tail -20   # retries that recovered, lost /auth
+grep -h ' <- \| -> ' D/logs/$(date -u +%F).log | tail   # posts out, your messages in
+```
+
+| Line | Means |
+|---|---|
+| `<- S/tN: 3 items (claude-code, live card)` | posted to a group, into the live card |
+| `<- S/tN: blocked (4 options)` | a dialog card went out |
+| `-> S/tN: picked 1. Yes` | a card button was pressed |
+| `-> S/tN: <text>` | your message was typed into the terminal |
+| `turn S/tN: done` | hc said a turn ended |
+| `acting as you: on` / `off` | `/auth` token usable / lost |
+| `uncaught:` + stack | the bot crashed; it was started again |
+
+## State
+
+`D/state.json` (never edit it while the bot runs: `herdrchat stop` first,
+`herdrchat start` after):
+
+| Key | Holds |
+|---|---|
+| `chats` | per terminal (`S|tN`, or `@machine|machine/tN`): group id, name, tags, label, muted, ended |
+| `cursors` | per terminal: what was posted (ids, time), the open live card |
+| `tags`, `labels`, `spaces` | ids of the bot tags, your labels, each space's avatar color |
+| `overview`, `pinned`, `reacts` | the overview card, pinned groups, messages waiting for their OK |
+
+Read it with a short `node -e` and print only what you need. `D/user-token.json` is
+your token after `/auth`: never print it.
+
+## Did the change take effect
+
+Check the live result, not only the code: count what actually happened in Feishu with
+the bot's own client (`lib/feishu.mjs` `createClient` with `loadConfig()`), for example:
+
+- mentions in a group since a time: `im.v1.message.list` on the chat, then each item's
+  `mentions` (a mention inside a card is not counted by Feishu, so it does not ring);
+- a group's bot tags: `im.v2.bizEntityTagRelation.get` with `tag_biz_type: 'chat'`;
+- whether a card was edited: `im.v1.message.get`, compare `update_time` with `create_time`.
+
+Say which checks were run and which were not; "the code is there" is not "it works".
+
+## Usual problems
+
+| You see | Likely cause | Do |
+|---|---|---|
+| nothing posts | bot down, or `FEISHU_OWNER_OPEN_ID` unset | check it runs; the log says "owner not set" |
+| a button gives error 200340 | the card callback is not set up | `references/feishu.md`: events and card callbacks |
+| a dialog had no card | answered in the terminal before the card; or no numbered menu on screen | log: `blocked`; the card says `/answer` when it saw no menu |
+| the phone rings too much | not `/auth`ed, or settings | `/auth`; `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES` |
+| a ⚠️ warning in the direct chat about acting as you | the token could not be refreshed | send `/auth` again |
+| a group keeps an old name | its terminal is not live | it renames when the terminal is back |
+| a Feishu call fails with 400 in a burst | a rate limit (tags: 5 a second) | space the calls; the bot queues tag calls |
+
+## Trying a Feishu API safely
+
+1. Read the official doc first (open.feishu.cn); write down the scope and limits.
+2. Make real calls only with this repo's own code (the SDK or `fetch`), never through a
+   third-party tool; reading another tool's docs or a dry run to learn a path is fine.
+3. Test in a throwaway group the bot creates for it (`zz-test ...`), never in a
+   terminal's group; label each test message ("Test 2/3: ...") so the user can tell
+   which one rang.
+4. Measure the result (an API field, a read-back) instead of assuming it; ask the user
+   only what only a phone shows (did it ring).
+5. Clean up in the same run: disband the test group, delete test labels and tags you
+   made, recall test messages, delete scratch files.
+
+## Before a commit
+
+1. `npm test` passes.
+2. Stage, then, as its own step, scan the staged files for anything real: session and
+   machine names, the app id (`cli_`), open_ids (`ou_`), chat ids (`oc_`), message ids
+   (`om_`), label ids (`ofg_`), the tenant's name, people's names, local paths. Read the
+   result before committing; never chain the scan and the commit in one command.
+3. Show the commit message (Conventional Commits; the body says why) and commit only
+   after the user's yes. No push without its own yes.