agents-pod 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,81 @@ All notable changes to agents-pod. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] — 2026-11-04
+
+Two measurements decided this patch: a standing pod with an empty inbox is no
+longer woken, and `spawn_pod` finally says what it is for. The first is the gate
+ADR 0026 deferred until "the ticking hurts" — it hurt, one whole agent run per
+minute on a router with nothing to do (issue #20). The second is a discovery
+failure measured headlessly: neither a router request nor "每天早上 9 点汇总 CI"
+ever reached the tool, because its description promised a pod that ends and a
+guideline made turn 1 a survey (issue #21).
+
+### Changed
+
+- **`spawn_pod`'s model-facing text now names standing work** (issue #21).
+  Measured headless runs never called the tool — 18 turns and 31 tool calls for
+  a router request, 7 turns and 10 for "每天 9 点汇总 CI", zero spawns — because
+  the description promised a pod that ends "until its goal is done", said
+  nothing about intake, and a guideline made turn 1 a `/pod list` survey. The
+  description now says a pod stands while its goal is open, is fed from a
+  source or inbox, and routes by writing inbox items; the guidelines map
+  常驻／路由／收消息／每天 onto `spawn_pod` as the first tool call. Both measured
+  prompts now reach `spawn_pod` in the first call, 2 turns
+  (`scripts/first-turn-check.sh`, which runs against a throwaway store).
+
+### Fixed
+
+- **A standing pod bound by a listener sleeps until its `## Inbox` has
+  something** (issue #20). `wakeDuePods` woke every idle, goal-open pod on
+  every tick, so a pod that exists to serve an inbox burned one whole agent run
+  per minute with nothing to do — the shape that got the first router pod
+  cancelled. The intake phase now records the batch it owes
+  (`policy.intakePending`) and the wake phase admits an intake-driven pod on
+  that debt alone; a clean exit pays it, a `failed`/`lost` wake-up leaves it for
+  the retry, and a capacity-blocked launch keeps it for the next pass. An
+  unbound pod keeps ADR 0011's rule unchanged (ADR 0026 amendment).
+
+## [0.3.0] — 2026-11-04
+
+A machine whose IM surface has never been exercised can now say so. Discovery
+was the one thing ADRs 0024/0025 left without a home: credentials and sockets
+moved into operator commands, so core could not check any of it, and every
+failure mode — a drain that runs and yields nothing, a missing deliverer, no
+channels, no cron line — was exit-`0`-silent by design (issue #19).
+
+### Added
+
+- **`agents-pod doctor [--probe] [--json]`** — a read-only Health Report over
+  the store (ADR 0027): store and registry, the last pass, each Source (command,
+  cursor, drain age and yield, last failure), each Listener (Source or inbox,
+  template, project, bound Pod), the deliverer with pending and dead Outbox
+  entries, and the notification config including a `passwordEnv` that is not
+  set. `✓` nothing to do, `✗` blocks a channel, `?` worth knowing; exit `0`
+  clean, `1` otherwise, `2` for usage errors.
+- **The first run, printed** — with no Source, no deliverer and no channel,
+  `doctor` prints the ordered recipe instead of a report, shrinking to the
+  missing steps once anything exists. A bare `agents-pod` now names `doctor`
+  instead of answering `Unknown command`.
+- **`<cmd> --check`** — the operator command's own self-check (exit `0`
+  healthy, `3` none here, anything else unhealthy), run by `doctor --probe`
+  under the ten-second budget and quoted verbatim. Core still holds no
+  credentials; the side that owns them does the checking.
+- **`examples/feishu/`** — a worked Source and deliverer pair for Feishu with
+  `--check` implemented, a `.env.example`, and the platform facts measured
+  while wiring it to a real tenant: the four scopes, `230027`/`99991672`, the
+  group that must be created by a human, and the endpoints that are not there.
+- **Two facts that end the silence**: `sources.json` now records
+  `lastDrainItems`, `lastError` and `lastFailureAt` (a zero-yield drain is
+  visible; a failure is reportable without tailing `cron.log`), and every pass
+  writes `last-pass.json`, so "cron is not installed" and "cron runs and finds
+  nothing" read differently.
+
+### Changed
+
+- A failed drain's record keeps the failure fact; the cursor, drain horizon and
+  yield still do not move (ADR 0024, amended in ADR 0027).
+
 ## [0.2.0] — 2026-11-04
 
 Work that arrives in a chat can now be picked up there, and answered there,

package/README.md

@@ -137,6 +137,7 @@ package until both plugins demonstrably need one.
 ## CLI
 
 ```text
+agents-pod doctor [--probe] [--json]                     # what is missing, and the command that fixes it
 agents-pod spawn <goal prompt> [--project <dir>] [--agent <id>] [--model <id>] [--cwd <dir>]
                               [--after <podId>]                 # wait for the upstream pod to reach done
 agents-pod project cap [n|unlimited] [--project <dir>]          # per-project live wake-up cap
@@ -168,8 +169,8 @@ upstream pod's `done`; a cancelled upstream never releases it. When the
 project's cap is full, the new pod likewise waits idle with its document store
 ready. Manual `wake` overrides park/backoff, never dependencies or capacity.
 Exit codes follow the house rule: `0` success
-or nothing to do, `1` at least one pod failed, `2` configuration or storage
-error.
+or nothing to do, `1` at least one pod failed (or `doctor` found something
+that blocks a channel), `2` configuration or storage error.
 
 Every goal prompt carries the wake-up protocol: read the pod documents
 first, record before exiting.
@@ -222,6 +223,10 @@ policy, per record:
   pod's default agent — which agent, which model, after how much backoff,
   is pod-record policy, written by reconcile from outcomes
   ([ADR 0011](docs/adr/0011-minimal-wake-policy.md));
+- idle + **bound by a listener** + nothing owed → no-op. An intake-driven pod
+  is woken on the batch it owes (`policy.intakePending`), never on the tick, so
+  a standing router with an empty inbox costs nothing
+  ([ADR 0026 amendment](docs/adr/0026-affinity-root-message-and-delivery-address.md));
 - idle + parked (consecutive-failure stop) → no-op until a human `wake`
   clears it;
 - live but progressless (no document change for 60 min) → killed via the
@@ -251,7 +256,9 @@ section — below the agent-owned `## Waiting`, and appended only while no
 wake-up is live, then one batch, one wake on the ordinary wake path; the
 agent serves entries and flips their checkboxes. A block with a Delivery
 Address carries ` — to: <Delivery Address>` on its checkbox line, never in
-the copied body (ADRs 0014, 0026).
+the copied body (ADRs 0014, 0026). Between batches the pod is not merely idle
+but **asleep**: the tick alone does not wake a bound pod, which is what makes
+"serve this inbox" a shape that can stand for days (ADR 0026 amendment).
 
 Overlapping passes: one TTL'd single-flight lock (`reconcile.lock`, stale
 after 5 minutes by wall clock — never PID liveness) skips fresh-held ticks
@@ -262,7 +269,53 @@ registry-lock CAS on every state transition, so two passes — or a human
 Notifications (P1): two events only — park (with the failure verdict)
 and done — through the copied channels (webhook/email/system) in
 `~/.agents/pods/config.json`; once per episode; individual outcomes
-never notify (ADR 0021).
+never notify (ADR 0021). A store with no channels at all stays silent by
+design, so `agents-pod doctor` reports it as a `?` line rather than letting
+silence look like health.
+
+## First run
+
+`agents-pod doctor` answers one question, read-only: what does this machine
+still lack for a conversation to reach a Pod, and a reply to leave one? With
+nothing configured it prints the ordered first run instead of a report — write
+a Source command, `source add`, `listener add`, `deliver add`, the cron line,
+`doctor` again — and exits `1` until every line is `✓`
+([ADR 0027](docs/adr/0027-discovery-doctor-and-the-self-check.md)).
+
+```text
+store     ✓ 1 pods, 0 active
+pass      ✓ last pass 41s ago
+intake    ✗ source feishu: the last drain (2s ago) failed — exit 1
+                  run: agents-pod doctor --probe
+listeners ✓ listener-4f1a: source feishu → template triage.md → /work/app
+outbound  ✓ deliverer feishu-reply: ~/.agents/pods/adapters/feishu_deliver.py
+notify    ? no notification channels: parks and dones stay silent
+```
+
+`✓` nothing to do, `✗` the channel cannot work, `?` worth knowing — a quiet
+chat, no channels, a pass that has not run. Exit `0` when nothing is `✗`, `1`
+otherwise, `2` for store or usage errors; `--json` prints the same report as
+data. Two small records make the silent cases visible: `sources.json` keeps
+the last drain's yield and its last failure, and every pass marks
+`last-pass.json`, so "cron is not installed" and "cron runs and finds nothing"
+stop looking identical.
+
+**Credentials belong to the operator command, so only it can check them.** The
+convention is `<cmd> --check`: exit `0` healthy, `3` no self-check here,
+anything else unhealthy. `doctor --probe` runs it once for each Source and
+once for the deliverer and quotes its lines verbatim — which is how a missing
+platform scope, with its console URL, reaches the person who can grant it:
+
+```text
+checks    ✗ source feishu: self-check failed (exit 1)
+                  read failed in 联调: code=230027 msg=Lack of necessary permissions, ext=need scope: im:message.group_msg
+                  https://open.feishu.cn/app/cli_…/auth?q=im:message.group_msg&op_from=openapi&token_type=tenant
+```
+
+Plain `doctor` never executes operator code. `examples/feishu/` is a worked
+pair that implements `--check` and records the platform facts measured while
+wiring it up: the four scopes, the error codes, and the two traps that cost an
+afternoon.
 
 ## IM intake and outbound
 
@@ -320,8 +373,11 @@ inbox namespace and the item's platform id, shared by every Listener on that
 Source. Claims are written to `listeners.json` before the Source's cursor is
 atomically written to `sources.json`, so a crash between those writes replays
 into id deduplication. A committed drain also advances the record's
-`lastDrainAt`; claims from the current and previous successful drain
-generations are retained and older timestamped claims are pruned. Claims with
+`lastDrainAt` and records its yield as `lastDrainItems` — zero is a fact, not a
+gap, and it is what makes a pull that is pointed at nothing visible to
+`agents-pod doctor` (ADR 0027). Claims from the current and previous
+successful drain generations are retained and older timestamped claims are
+pruned. Claims with
 no generation timestamp are retained. For a Source bound to a standing Pod,
 the claimed batch must also be appended to `TASKS.md` before cursor and
 `lastDrainAt` commit; a live wake-up holds that append, so the next pass drains
@@ -329,9 +385,18 @@ from the unchanged cursor again.
 
 A non-zero exit, termination by a signal, spawn failure, timeout, or total
 stdout larger than **1 MiB** abandons the whole drain: no items are claimed,
-neither cursor nor `lastDrainAt` moves, no claims are pruned, and exactly one
-`cron.log` line records the failure. Reconcile still exits `0`; the next pass
-retries the whole drain from the same cursor (ADR 0024).
+neither cursor nor `lastDrainAt` nor `lastDrainItems` moves, no claims are
+pruned, and exactly one `cron.log` line records the failure. The record also
+keeps `lastError` and `lastFailureAt`, cleared by the next success, so the
+report can name a Source that fails every pass without tailing the log
+(ADR 0027). Reconcile still exits `0`; the next pass retries the whole drain
+from the same cursor (ADR 0024).
+
+A Source command may also answer `<cmd> --check` (exit `0` healthy, `3` no
+self-check here, anything else unhealthy) with its own diagnosis on
+stdout/stderr; `agents-pod doctor --probe` runs it and quotes it (ADR 0027).
+The drain invocation never passes an argument — the check is a second calling
+convention, opted into by the command that implements it.
 
 ### Writing the deliverer
 
@@ -397,6 +462,11 @@ no deliverer configured, the Wrapper flush is a no-op; each reconcile pass
 writes one `cron.log` line per Pod with waiting entries, and the same one-hour
 aging still applies (ADR 0025).
 
+A deliverer may answer `<cmd> --check` on the same convention as a Source
+command (exit `0` healthy, `3` no self-check here, anything else unhealthy);
+`agents-pod doctor --probe` runs it, and `agents-pod doctor` reports any
+entries waiting in Pod outboxes while no deliverer is configured (ADR 0027).
+
 ### Role Instructions for replying agents
 
 Save the following as the replying Agent's instructions file and pass it to
@@ -430,7 +500,9 @@ rename, delete, or rewrite pending or dead entries yourself.
 ├── agents.json        # named agents: adapter type, model, role instructions, 0600
 ├── listeners.json     # listeners, bounds, claimed item ids, 0600
 ├── sources.json       # named drain commands, committed cursors, lastDrainAt
+│                      # + lastDrainItems and the last failure (ADR 0027)
 ├── deliverer.json     # the single outbound delivery command
+├── last-pass.json     # when a pass last finished, so "never ran" is a fact
 ├── inboxes/<id>/      # default listener inboxes; any dir/file may serve instead
 └── registry.lock      # short-lived registry write lock, 0600
 
@@ -529,3 +601,8 @@ is refused at the surface and at launch. The extension lives in
 `src/extension/` (one module per plane, plus `handoff.ts` for the document
 rendering), with `index.mjs` at the package root as Pi's entry so the footer
 label stays `agents-pod`.
+
+`examples/` ships operator commands that core never imports — today the Feishu
+Source/deliverer pair — as copyable starting points. `src/doctor.ts` is the
+read-only Health Report; it is tested through the CLI like everything else,
+with fake operator commands that answer `--check` on each exit code.

package/examples/feishu/.env.example

@@ -0,0 +1,23 @@
+# A copy of this file is your own: `cp .env.example .env` (0600), then fill in.
+# Nothing here is ever committed; core never reads these — the commands do
+# (ADRs 0024, 0025), and `agents-pod doctor --probe` asks the commands.
+
+# Self-built app credentials: open platform → app → 凭证与基础信息.
+FEISHU_APP_ID=
+FEISHU_APP_SECRET=
+
+# Comma-separated chat_id allowlist; empty = every group chat the app is in.
+# Read a chat_id from state.json's known_chats after one successful drain.
+FEISHU_CHATS=
+
+# 1 = only messages that @-mention the bot (a mixed-use group); 0 = everything.
+FEISHU_REQUIRE_MENTION=0
+
+# First-run window when there is no cursor yet, and the re-read overlap behind
+# an existing one, in seconds.
+FEISHU_LOOKBACK_SECONDS=3600
+FEISHU_OVERLAP_SECONDS=60
+
+# Per-pass item cap; the cursor stops at the last item printed, so a bigger
+# burst simply arrives over several passes.
+FEISHU_MAX_ITEMS=40

package/examples/feishu/README.md

@@ -0,0 +1,92 @@
+# A Feishu command pair for agents-pod
+
+Two operator commands that hold every platform concern — app credentials, token
+rotation, chat and thread paging, message flattening, reply addressing — so
+core stays credential- and socket-free (ADRs [0024](../../docs/adr/0024-sources-pull-drain-and-cursor.md),
+[0025](../../docs/adr/0025-outbox-operator-delivery-and-entry-files.md)).
+
+| file | role | registered as |
+|---|---|---|
+| `feishu_drain.py` | Source: chats + threads → JSONL items + a cursor line | `agents-pod source add feishu --cmd <path>` |
+| `feishu_deliver.py` | Deliverer: one Outbox entry → one Feishu reply | `agents-pod deliver add feishu-reply --cmd <path>` |
+| `feishu_client.py` | shared client: token cache, paging, message flattening | — |
+| `.env.example` | the switchboard; copy to `.env` (0600) and fill | — |
+
+Copy all four next to each other anywhere outside this repository — the pair is
+meant to be *yours*, not core's. `chmod +x feishu_drain.py feishu_deliver.py`.
+`state.json` and `.token.json` appear on first use; both are rebuilt if lost.
+
+```bash
+cp examples/feishu/*.py ~/.agents/pods/adapters/          # or wherever
+cp examples/feishu/.env.example ~/.agents/pods/adapters/.env && chmod 600 …
+agents-pod source add feishu --cmd ~/.agents/pods/adapters/feishu_drain.py --timeout 60
+agents-pod deliver add feishu-reply --cmd ~/.agents/pods/adapters/feishu_deliver.py --timeout 20
+agents-pod doctor --probe      # the pair answers for itself; fix what it names
+```
+
+## The one thing this cannot do for you: the app
+
+Feishu's console is a human surface. In order:
+
+1. **Create a self-built app** (自建应用) and take `App ID` / `App Secret` from
+   凭证与基础信息 into `.env`.
+2. **Grant four tenant permissions**, then **publish a version** (权限变更 only
+   takes effect with a new version; sensitive ones need an admin's approval):
+
+   | scope | why | measured failure without it |
+   |---|---|---|
+   | `im:message.group_msg` | read group history | `GET /im/v1/messages` → `code=230027 lack of necessary permissions` |
+   | `im:message:readonly` | read messages generally | same class of refusal |
+   | `im:message:send_as_bot` | post as the bot | send refused |
+   | `im:chat:readonly` | enumerate the chats the bot is in | chat list comes back empty |
+
+3. **Add the bot to a group chat** — 群设置 → 群机器人 → 添加机器人. Create that
+   group yourself, in the Feishu app: see the trap table below.
+4. **Say one thing in the group**, then run the smoke test below.
+
+## Smoke test
+
+```bash
+cd ~/.agents/pods/adapters
+env AGENTS_POD_SOURCE_ID=feishu AGENTS_POD_CURSOR= ./feishu_drain.py   # JSONL items, then {"cursor":"…"}
+printf '%s' '{"to":"chat=oc_xxx;affinity=om_xxx","text":"通道自检"}' | ./feishu_deliver.py
+```
+
+`exit 0` on both is the wiring. A drain that prints nothing **and** exits `0`
+is not proof of health — it is the shape of "the pull is pointed at nothing",
+which is why `sources.json` records `lastDrainItems` and why
+`agents-pod doctor` prints a `?` line for a zero-yield drain (ADR 0027).
+
+Both commands answer `--check` (exit `0` healthy, `1` not) with their own
+diagnosis, including the console URL for a missing scope; `agents-pod doctor
+--probe` runs those and quotes them.
+
+## Measured traps
+
+Facts observed while wiring this pair to a real tenant, in the order they bite:
+
+| trap | what actually happens |
+|---|---|
+| **Send works while read is denied** | The bot can post into a group and cannot read a word of it, so a half-granted app looks alive. `im:message.group_msg` is the one that blocks intake (`230027`), and the error message carries its own console link. |
+| **An app-created chat is invisible to humans** | `POST /im/v1/chats` succeeds (so does the local test above), but the group is created *by the app*: you do not see it in Feishu, and you cannot join it without another write scope. Create the group in the client and add the bot — that is the only shape a human can also type into. |
+| **A new chat can take a moment to appear** | `GET /im/v1/chats` may return `items: []` for a chat that exists; a retry a few seconds later lists it. Treat one empty page as inconclusive before concluding the bot is in no group. |
+| **p2p is not enumerable** | The chat list excludes p2p conversations, so a pull drain cannot see a direct message (ADR 0024). Group chats are the supported intake shape. |
+| **`/im/v1/chats/:chat_id/link` is 404** | Not every endpoint in older notes exists on the tenant's version; do not build an invite flow on it. |
+| **A version must be published** | Granting scopes without 版本管理与发布 changes nothing at runtime, and the refusal looks identical to "scope not granted". |
+| **Chat anonymity hides history** | A group with 保密模式 or hidden history answers intake with `230050`/`231203` and no item ever arrives — a configuration fact, not a bug. |
+| **Tokens and dedup windows are hours long** | `tenant_access_token` lives 2 h (`.token.json` caches it), so a 1-minute pass is cheap; the reply `uuid` window is 1 h, which is exactly what core's dead-lettering assumes (ADR 0025). |
+
+## Switchboard (`.env`, or the environment — the environment wins)
+
+- `FEISHU_CHATS` — comma-separated `chat_id` allowlist; empty = every chat.
+- `FEISHU_REQUIRE_MENTION` — `1` reads only messages that @-mention the bot.
+- `FEISHU_LOOKBACK_SECONDS` (3600) / `FEISHU_OVERLAP_SECONDS` (60) /
+  `FEISHU_MAX_ITEMS` (40) — first-run window, re-read overlap behind the
+  cursor, per-pass cap. The cap never loses messages: the cursor stops at the
+  last item printed.
+
+## Two independent commands, one platform
+
+The pair shares a client file and nothing else. A different platform is a
+second pair of commands and needs nothing from core; a second Feishu app needs
+nothing from this directory but another `.env`.

package/examples/feishu/feishu_client.py

@@ -0,0 +1,220 @@
+"""Shared Feishu client for the agents-pod operator adapters (ADR 0024 / 0025).
+
+No third-party dependencies: urllib only, so a cron tick can run an adapter
+without a virtualenv. Credentials come from this directory's `.env` (0600) and
+never appear on a command line or in stdout.
+"""
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BASE = "https://open.feishu.cn/open-apis"
+HERE = os.path.dirname(os.path.abspath(__file__))
+ENV_FILE = os.path.join(HERE, ".env")
+TOKEN_FILE = os.path.join(HERE, ".token.json")
+STATE_FILE = os.path.join(HERE, "state.json")
+BOT_FILE = os.path.join(HERE, ".bot.json")
+
+
+class FeishuError(RuntimeError):
+    def __init__(self, path, code, msg, ext=None):
+        super().__init__("%s: code=%s msg=%s" % (path, code, msg))
+        self.path = path
+        self.code = code
+        self.msg = msg
+        # Feishu puts the actionable part - the scope name, often a console
+        # link - in `ext` rather than `msg`, so keep it (ADR 0027's --check).
+        self.ext = ext or ""
+
+
+def load_env():
+    """Reads `.env` without clobbering the environment operators set explicitly."""
+    values = {}
+    try:
+        with open(ENV_FILE, "r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, val = line.partition("=")
+                values[key.strip()] = val.strip().strip('"').strip("'")
+    except FileNotFoundError:
+        pass
+    for key, val in values.items():
+        os.environ.setdefault(key, val)
+    return values
+
+
+def _request(method, path, token=None, body=None, params=None, timeout=10):
+    url = BASE + path
+    if params:
+        url += "?" + urllib.parse.urlencode({k: v for k, v in params.items() if v not in (None, "")})
+    data = None
+    headers = {"Content-Type": "application/json; charset=utf-8"}
+    if token:
+        headers["Authorization"] = "Bearer " + token
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    raw = None
+    for attempt in range(3):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                raw = resp.read().decode("utf-8", "replace")
+            break
+        except urllib.error.HTTPError as err:
+            raw = err.read().decode("utf-8", "replace")
+            if err.code == 429 and attempt < 2:
+                time.sleep(1 + attempt)
+                continue
+            break
+        except urllib.error.URLError as err:
+            if attempt < 2:
+                time.sleep(1 + attempt)
+                continue
+            raise FeishuError(path, "network", str(err))
+    try:
+        return json.loads(raw or "{}")
+    except ValueError:
+        raise FeishuError(path, "not-json", (raw or "")[:200])
+
+
+def api(method, path, token=None, body=None, params=None, timeout=10):
+    answer = _request(method, path, token, body, params, timeout)
+    code = answer.get("code")
+    if code not in (0, None):
+        raise FeishuError(path, code, answer.get("msg"), answer.get("ext"))
+    return answer.get("data", answer)
+
+
+def _read_json(path):
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except (FileNotFoundError, ValueError):
+        return {}
+
+
+def _write_json(path, value, mode=0o600):
+    tmp = path + ".tmp"
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        json.dump(value, fh, ensure_ascii=False)
+    os.replace(tmp, path)
+
+
+def tenant_token(force=False):
+    """`tenant_access_token` lives 2 h; caching keeps a 1-minute tick cheap."""
+    cached = _read_json(TOKEN_FILE)
+    if not force and cached.get("token") and cached.get("expires_at", 0) > time.time() + 60:
+        return cached["token"]
+    app_id = os.environ.get("FEISHU_APP_ID", "").strip()
+    app_secret = os.environ.get("FEISHU_APP_SECRET", "").strip()
+    if not app_id or not app_secret:
+        raise FeishuError("/auth/v3/tenant_access_token/internal", "no-credentials",
+                          "FEISHU_APP_ID / FEISHU_APP_SECRET missing (see %s)" % ENV_FILE)
+    answer = _request("POST", "/auth/v3/tenant_access_token/internal",
+                      body={"app_id": app_id, "app_secret": app_secret})
+    if answer.get("code") != 0 or not answer.get("tenant_access_token"):
+        raise FeishuError("/auth/v3/tenant_access_token/internal",
+                          answer.get("code"), answer.get("msg"))
+    token = answer["tenant_access_token"]
+    expires_at = time.time() + int(answer.get("expire", 7200))
+    _write_json(TOKEN_FILE, {"token": token, "expires_at": expires_at})
+    return token
+
+
+def bot_open_id(token):
+    """The bot's own `open_id`, used to spot an @-mention of us."""
+    cached = _read_json(BOT_FILE)
+    if cached.get("open_id"):
+        return cached["open_id"]
+    data = api("GET", "/bot/v3/info", token=token)
+    bot = data.get("bot") or {}
+    open_id = bot.get("open_id")
+    if open_id:
+        _write_json(BOT_FILE, {"open_id": open_id, "app_name": bot.get("app_name")})
+    return open_id
+
+
+def load_state():
+    state = _read_json(STATE_FILE)
+    state.setdefault("known_chats", [])
+    state.setdefault("threads", {})
+    return state
+
+
+def save_state(state):
+    _write_json(STATE_FILE, state)
+
+
+def flatten_message(msg):
+    """Plain text for a Feishu message, whatever its `msg_type`."""
+    msg_type = msg.get("msg_type") or ""
+    try:
+        content = json.loads((msg.get("body") or {}).get("content") or "{}")
+    except ValueError:
+        content = {}
+    if isinstance(content, str):
+        try:
+            content = json.loads(content)
+        except ValueError:
+            return content
+
+    if msg_type == "text":
+        return str(content.get("text", "")).strip()
+    if msg_type == "post":
+        return _flatten_post(content).strip()
+    if msg_type in ("image",):
+        return "[图片]"
+    if msg_type in ("file", "folder"):
+        return "[文件] %s" % (content.get("file_name") or "")
+    if msg_type in ("audio",):
+        return "[语音]"
+    if msg_type in ("media",):
+        return "[视频]"
+    if msg_type == "sticker":
+        return "[表情]"
+    if msg_type == "merge_forward":
+        return "[合并转发消息]"
+    if msg_type == "interactive":
+        return "[卡片]"
+    if msg_type == "share_chat":
+        return "[群名片]"
+    return "[%s]" % (msg_type or "unknown")
+
+
+def _flatten_post(node):
+    """A post may nest a locale layer: {zh_cn: {title, content}}."""
+    if isinstance(node, dict):
+        if "content" in node or "title" in node:
+            lines = []
+            title = (node.get("title") or "").strip()
+            if title:
+                lines.append(title)
+            for paragraph in node.get("content") or []:
+                parts = []
+                for element in paragraph if isinstance(paragraph, list) else []:
+                    if not isinstance(element, dict):
+                        continue
+                    if element.get("tag") in ("text", "a", "md"):
+                        parts.append(str(element.get("text") or ""))
+                    elif element.get("tag") == "at":
+                        parts.append("@" + str(element.get("user_name") or "某人"))
+                    elif element.get("tag") == "img":
+                        parts.append("[图片]")
+                if parts:
+                    lines.append("".join(parts))
+            return "\n".join(lines)
+        for value in node.values():
+            text = _flatten_post(value)
+            if text:
+                return text
+        return ""
+    if isinstance(node, list):
+        return "\n".join(t for t in (_flatten_post(v) for v in node) if t)
+    return ""