docs(feishu-bridge): spell out the two-identity setup, the scopes, and the failure modes

The Setup section said "a lark-cli you have already configured" and stopped
there. That is not enough, because the bridge reads and writes through different
identities and a half-configured app fails in a way the log does not make obvious.

The bridge calls `--as user` for +chat-messages-list and
+messages-resources-download, and `--as bot` for +messages-send, +messages-reply
and +messages-edit. A bot cannot see a p2p conversation history, and only a bot
may edit a message it sent, so both identities are genuinely required and they
fail independently. Documented:

- `lark-cli auth status` must show `identities.bot.status` and
  `identities.user.status` both `ready`.
- The minimum scope set, split by identity: `im:message:readonly` and
  `im:resource` on the user side; `im:message` and `im:message:update` on the bot
  side. Called out `offline_access` separately, because without it the user token
  stops working after a couple of hours and the bridge goes quiet at a moment when
  nothing reports an error.
- That the user identity is the user"s own account, so the bridge acts as them.
- A p2p chat with the app as the simplest arrangement, which is what this Plugin
  is built and tested for.
- First-run behaviour: the workspace is created on start and nothing historical
  is picked up, so the first message has to come after the bridge starts.
- Obtaining a chat id, including the `--page-all` that the listing needs.

Also added, because an operator hits them immediately and none were documented:

- Running it in the background, with the reason the Plugin ships no autostart and
  the specific trap that a supervisor inheriting the child"s std handles blocks
  forever. This is the defect that cost the most time during development.
- Uninstall: `--stop`, then delete the data directory. Removing the Plugin leaves
  that directory alone on purpose; it is user data.
- Network: outbound HTTPS to the Feishu/Lark Open Platform only, no inbound
  listener, and `lark-cli` owns proxy configuration.
- A symptom-to-cause table for the identity, scope, token-expiry, attachment,
  paging and lock failures, noting that every one of them writes a log line, so an
  empty log plus a silent chat means the watcher is not running.

skills/SKILL.md carries the same identity and scope requirements in its
pre-flight and troubleshooting sections, so the agent checks them before starting
rather than after a user reports silence.

Validation: `node scripts/validate.mjs` green, 84 passed / 0 failed.

Author: antianqi

plugins/antianqi/mcode-feishu-bridge/README.md

@@ -43,31 +43,123 @@ with its normal tool access, and the answer comes back **in the same message**.
 The intermediate states and the final answer are the same Feishu message, so the
 conversation stays readable and nothing is duplicated.
 
-## Install
+## Setup
 
-The Plugin is Skill-only and has no `mcp.json` and no `package.json`. It needs two
-CLIs that you already have or can install yourself:
+The Plugin is Skill-only: no `mcp.json`, no `package.json`, no install step. But it
+does need three things lined up, and two of them are easy to get half-right.
 
-| requirement | what it is | check |
+### 1. MiniMax Code
+
+Installed and runnable:
+
+```bash
+mcode --version
+```
+
+### 2. A Feishu/Lark app, with **two** working identities
+
+This is the part that trips people up. The bridge reads and writes through
+**different identities**, and both have to work:
+
+| what | identity | why |
 |---|---|---|
-| [`lark-cli`](https://www.npmjs.com/package/@larksuite/cli) | the official Lark/Feishu CLI, already configured for your account | `lark-cli auth status` |
-| MiniMax Code | the agent, installed and runnable | `mcode --version` |
+| read the conversation, download attachments | **user** | the bot cannot see a p2p conversation's history |
+| send, reply, and edit the answer | **bot** | only a bot may edit a message it sent |
+
+```bash
+lark-cli auth status
+```
 
-Then configure a conversation and start the bridge:
+Both `identities.bot.status` and `identities.user.status` must read `ready`.
+If either is not, fix that before going further — otherwise the bridge reads
+nothing or writes nothing, and the log only says `fetch messages failed`.
+
+The app needs at least these scopes, derived from the operations it performs:
+
+| scope | needed for | identity |
+|---|---|---|
+| `im:message:readonly` | reading messages in the conversation | user |
+| `im:resource` | downloading an image or file you send | user |
+| `im:message` | sending the placeholder and the answer | bot |
+| `im:message:update` | editing that placeholder into the answer | bot |
+| `offline_access` | letting the user token refresh instead of expiring | user |
+
+`offline_access` is the one people miss. Without it the user token stops working
+after a couple of hours and the bridge goes quiet, with no error at the time it
+happens. Note also that the user identity here is **your** account: the bridge acts
+as you, with everything that implies.
+
+Publish the app (Feishu requires an app to be published before another user can
+talk to it), then open a chat with it. A p2p chat with your own app is the simplest
+arrangement and the one this Plugin is built and tested for.
+
+### 3. A chat id
+
+There is deliberately no default: a chat id is a private identifier, so it has to be
+yours to supply.
+
+```bash
+lark-cli im +chat-list --types=p2p,group --page-all --as user --format json
+```
+
+Find your conversation in the output. The `--page-all` matters — without it the
+listing silently truncates and you may not see the conversation you are looking for.
+
+### 4. Start it
 
 ```bash
 node scripts/mcode-feishu-bridge.mjs --watch --chat <your-chat-id>
 ```
 
-How to obtain a chat id: send a message in the conversation, then
+On the first run the bridge creates a workspace for that conversation and picks up
+nothing historical: it starts from the newest message at the time it launches. Send
+it a message after starting, not before.
+
+Full operating instructions are in
+[`skills/mcode-feishu-bridge/SKILL.md`](skills/mcode-feishu-bridge/SKILL.md).
+
+## Running it in the background
+
+The Plugin ships no service manager, on purpose: a login hook that runs a hidden
+process forever is exactly the kind of thing that should be a deliberate, visible
+choice by the person running the machine, not a default a Plugin installs.
+
+If you do want it always on, run the watcher under whatever supervisor you already
+use, and make sure it inherits a real `PATH` so the bridge can find `lark-cli` and
+`mcode`:
+
+```bash
+nohup node scripts/mcode-feishu-bridge.mjs --watch --chat <chat-id> >> bridge.log 2>&1 &
+```
+
+Two rules that follow from how this is built:
+
+- **Do not redirect the watcher's stdout from a supervisor that waits on the
+  child's pipe.** A long-lived child spawned with inherited std handles keeps that
+  pipe open, and the supervisor blocks forever. Start the watcher with std handles
+  closed or detached, or let the bridge write its own log via `--log`.
+- **The bridge takes a single-instance lock, so a second copy is refused with exit
+  code 3** rather than corrupting state. If that is not what you wanted, find the
+  first one: `bridge.lock` in the data directory holds its pid.
+
+## Uninstall
+
+There is nothing to uninstall. To stop it and remove its data:
 
 ```bash
-lark-cli im +chat-messages-list --chat-id <chat-id> --as user --format json
+node scripts/mcode-feishu-bridge.mjs --stop
 ```
 
-or list your conversations with `lark-cli im +chat-list --types=p2p,group --page-all --as user`.
+Then delete the data directory (`$PLUGIN_DATA`, else `~/.mcode-feishu-bridge`).
+That removes the per-conversation workspaces and the downloaded media. Removing the
+Plugin from MiniMax Code leaves that directory alone, by design — it is the user's
+data, and a Plugin should not delete it on uninstall.
 
-Full operating instructions are in [`skills/mcode-feishu-bridge/SKILL.md`](skills/mcode-feishu-bridge/SKILL.md).
+## Network
+
+Outbound HTTPS to the Feishu/Lark Open Platform, through `lark-cli`. No inbound
+listener, no local port, no other host. If your machine reaches Feishu through a
+proxy, `lark-cli` needs it configured; the bridge does not set one.
 
 ## How it works
 
@@ -225,6 +317,22 @@ next to the fix.
    if you write a launcher script for it; not applicable to this Plugin, which ships
    no `.ps1`.
 
+## When it does not work
+
+| symptom | most likely cause | check |
+|---|---|---|
+| no reply at all, log says `fetch messages failed` | the **user** identity is not usable: token expired, or `offline_access` was never granted | `lark-cli auth status` — look at `identities.user` |
+| the bridge never starts, exits 1 at launch | `lark-cli` or `mcode` is not on the `PATH` the bridge inherited | run `which lark-cli` / `which mcode` in that same environment |
+| a reply appears, but it is always the failure notice | the **bot** identity cannot send, so even the fallback reply fails | `lark-cli auth status` — look at `identities.bot` |
+| works for hours, then goes quiet | the user token expired because `offline_access` was not granted at authorisation time | re-authorise with `lark-cli auth login` and request that scope |
+| attachments are ignored | missing `im:resource` | the app's permission list |
+| nothing happens, and the log says the watermark is not on the page | the bridge fell too far behind and the full-pagination fallback also failed | restart the watcher; it re-reads the newest page |
+| a second watcher refuses to start with exit 3 | one is already running, which is the point | `bridge.lock` holds its pid; use `--stop` |
+| a turn is reported as timed out | mcode hung, most often on an interactive prompt | the notice names how many tool calls had already run; check the workspace |
+
+None of these are silent: every one of them produces a line in `bridge.log`. If the
+log is empty and the chat is silent, the watcher is not running at all.
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

plugins/antianqi/mcode-feishu-bridge/skills/SKILL.md

@@ -28,8 +28,20 @@ be configured for the user. Check first:
 lark-cli auth status
 ```
 
-If that is not signed in, do not attempt to sign in for the user. Tell them to run
-`lark-cli config init` and `lark-cli auth login` themselves, and stop there.
+Two things must both be true, and they are the two that actually go wrong:
+
+- `identities.bot.status` is `ready` — the bridge **reads with the user identity but
+  writes with the bot identity**, because only a bot may edit a message it sent, and
+  a bot cannot see a p2p conversation's history.
+- `identities.user.status` is `ready` and the token is `valid`.
+
+The app needs at least `im:message:readonly` and `im:resource` for the user side, and
+`im:message` plus `im:message:update` for the bot side. `offline_access` matters most
+in practice: without it the user token stops working after a couple of hours and the
+bridge goes quiet with no error at the time it happens.
+
+If `lark-cli` is not signed in, do not attempt to sign in for the user. Tell them to
+run `lark-cli config init` and `lark-cli auth login` themselves, and stop there.
 
 `mcode` must be installed and runnable. The bridge discovers both CLIs from `PATH`
 and the install layout; it never hardcodes a path.
@@ -97,23 +109,33 @@ Useful flags:
 
 ## If the user says a message got no reply
 
-Work through this order; the first three are the ones that actually happen:
+Work through this order; the first four are the ones that actually happen.
 
 1. **Read the log.** The bridge logs to `<data-dir>/bridge.log` and the file is
-   readable while it runs.
+   readable while it runs. An empty log plus a silent chat means the watcher is not
+   running at all — start it.
    - No `✓` line for that message means it was never picked up.
-   - `✗ fetch messages failed` means `lark-cli` failed: the usual cause is an
-     expired user token. Have the user re-run `lark-cli auth login`.
-   - `✗ the watermark is not on this page` means the bridge fell too far behind;
-     it escalates to full pagination on its own, so this line means that also failed.
-2. **Check the process and the lock.** `bridge.lock` in the data directory holds a
+   - `✗ fetch messages failed` means the **user** identity failed. Usually an expired
+     token, or `offline_access` was never granted. Have the user re-run
+     `lark-cli auth login`.
+   - The answer is a failure notice even though the message was picked up: the **bot**
+     identity cannot send, so even the fallback reply failed.
+   - `✗ the watermark is not on this page` means the bridge fell too far behind; it
+     escalates to full pagination on its own, so this line means that also failed.
+2. **Check both identities.** `lark-cli auth status`. `identities.user` covers
+   reading and attachments; `identities.bot` covers sending, replying and editing.
+   They fail independently and the symptoms differ.
+3. **Check the process and the lock.** `bridge.lock` in the data directory holds a
    pid. A lock whose pid no longer exists is stale and is reclaimed automatically.
-3. **Check the watermark.** `state.json` records the last processed message per
+4. **Check the watermark.** `state.json` records the last processed message per
    chat. If it is ahead of the user's message, the message was already handled.
-4. **Run the tests.** `node scripts/mcode-feishu-bridge.test.mjs` is self-contained
+5. **Run the tests.** `node scripts/mcode-feishu-bridge.test.mjs` is self-contained
    and prints a pass/fail summary. It is the fastest way to tell whether the host
    is broken or the conversation simply outgrew one page.
 
+`README.md` has a symptom-to-cause table covering the permission and identity
+failures, which are the ones users cannot diagnose from the log alone.
+
 ## Tests
 
 ```bash
@@ -128,6 +150,14 @@ module rather than a copy, so a green run says something about the shipped code.
 Two cases (`O` and `V`) read this plugin's own source. If you add a spawn call,
 keep `shell: false`; case `O` fails otherwise.
 
+## Running it unattended
+
+The Plugin ships no autostart mechanism, deliberately. If the user wants it always
+on, put it under a supervisor they already run, and warn them about one specific
+trap: **do not start a long-lived child with std handles inherited from a parent that
+waits on the pipe.** The caller blocks until the child closes it, which is forever.
+Start it detached, or let the bridge write its own log with `--log`.
+
 ## Network destinations
 
 - `open.feishu.cn` / `open.larksuite.com`, through `lark-cli`, for message read,

plugins/antianqi/mcode-feishu-bridge/skills/mcode-feishu-bridge/SKILL.md

@@ -28,8 +28,20 @@ be configured for the user. Check first:
 lark-cli auth status
 ```
 
-If that is not signed in, do not attempt to sign in for the user. Tell them to run
-`lark-cli config init` and `lark-cli auth login` themselves, and stop there.
+Two things must both be true, and they are the two that actually go wrong:
+
+- `identities.bot.status` is `ready` — the bridge **reads with the user identity but
+  writes with the bot identity**, because only a bot may edit a message it sent, and
+  a bot cannot see a p2p conversation's history.
+- `identities.user.status` is `ready` and the token is `valid`.
+
+The app needs at least `im:message:readonly` and `im:resource` for the user side, and
+`im:message` plus `im:message:update` for the bot side. `offline_access` matters most
+in practice: without it the user token stops working after a couple of hours and the
+bridge goes quiet with no error at the time it happens.
+
+If `lark-cli` is not signed in, do not attempt to sign in for the user. Tell them to
+run `lark-cli config init` and `lark-cli auth login` themselves, and stop there.
 
 `mcode` must be installed and runnable. The bridge discovers both CLIs from `PATH`
 and the install layout; it never hardcodes a path.
@@ -97,23 +109,33 @@ Useful flags:
 
 ## If the user says a message got no reply
 
-Work through this order; the first three are the ones that actually happen:
+Work through this order; the first four are the ones that actually happen.
 
 1. **Read the log.** The bridge logs to `<data-dir>/bridge.log` and the file is
-   readable while it runs.
+   readable while it runs. An empty log plus a silent chat means the watcher is not
+   running at all — start it.
    - No `✓` line for that message means it was never picked up.
-   - `✗ fetch messages failed` means `lark-cli` failed: the usual cause is an
-     expired user token. Have the user re-run `lark-cli auth login`.
-   - `✗ the watermark is not on this page` means the bridge fell too far behind;
-     it escalates to full pagination on its own, so this line means that also failed.
-2. **Check the process and the lock.** `bridge.lock` in the data directory holds a
+   - `✗ fetch messages failed` means the **user** identity failed. Usually an expired
+     token, or `offline_access` was never granted. Have the user re-run
+     `lark-cli auth login`.
+   - The answer is a failure notice even though the message was picked up: the **bot**
+     identity cannot send, so even the fallback reply failed.
+   - `✗ the watermark is not on this page` means the bridge fell too far behind; it
+     escalates to full pagination on its own, so this line means that also failed.
+2. **Check both identities.** `lark-cli auth status`. `identities.user` covers
+   reading and attachments; `identities.bot` covers sending, replying and editing.
+   They fail independently and the symptoms differ.
+3. **Check the process and the lock.** `bridge.lock` in the data directory holds a
    pid. A lock whose pid no longer exists is stale and is reclaimed automatically.
-3. **Check the watermark.** `state.json` records the last processed message per
+4. **Check the watermark.** `state.json` records the last processed message per
    chat. If it is ahead of the user's message, the message was already handled.
-4. **Run the tests.** `node scripts/mcode-feishu-bridge.test.mjs` is self-contained
+5. **Run the tests.** `node scripts/mcode-feishu-bridge.test.mjs` is self-contained
    and prints a pass/fail summary. It is the fastest way to tell whether the host
    is broken or the conversation simply outgrew one page.
 
+`README.md` has a symptom-to-cause table covering the permission and identity
+failures, which are the ones users cannot diagnose from the log alone.
+
 ## Tests
 
 ```bash
@@ -128,6 +150,14 @@ module rather than a copy, so a green run says something about the shipped code.
 Two cases (`O` and `V`) read this plugin's own source. If you add a spawn call,
 keep `shell: false`; case `O` fails otherwise.
 
+## Running it unattended
+
+The Plugin ships no autostart mechanism, deliberately. If the user wants it always
+on, put it under a supervisor they already run, and warn them about one specific
+trap: **do not start a long-lived child with std handles inherited from a parent that
+waits on the pipe.** The caller blocks until the child closes it, which is forever.
+Start it detached, or let the bridge write its own log with `--log`.
+
 ## Network destinations
 
 - `open.feishu.cn` / `open.larksuite.com`, through `lark-cli`, for message read,