@maincode-ai/matilda-code 0.21.12 → 0.21.13-nightly.20261027.e00306cd3

package/bundled/mainy/docs/features/auto-mode.md

@@ -1,308 +0,0 @@
-# Auto Mode
-
-Auto Mode uses an LLM classifier to evaluate each tool call and decide
-whether to auto-approve it. It sits between Auto-Edit (which only
-auto-approves file edits) and YOLO (which auto-approves everything).
-
-This page is the reference for configuring and troubleshooting Auto Mode.
-For an introduction, see the
-[Approval Mode overview](./approval-mode.md#4-auto-mode---classifier-driven-approval).
-
-## How it works
-
-When you're in Auto Mode and the agent tries to run a tool, Matilda Code
-walks three layers in order:
-
-1. **acceptEdits fast-path** — Edit / Write whose target path is inside
-   the workspace is auto-approved without invoking the classifier.
-   **Exception:** writes to Matilda Code's own self-modification surfaces
-   (`.matilda/settings*.json`, `MATILDA.md`, `AGENTS.md`, `MATILDA.local.md`,
-   configured context filenames, `.matilda/rules/`, `.matilda/commands/`,
-   `.matilda/agents/`, `.matilda/skills/`, `.matilda/hooks/`, `.mcp.json`) and
-   persistence surfaces (`.git/`, `.husky/`, `package.json`, `.npmrc`,
-   `Makefile`, `.github/workflows/`, etc.) route through the classifier
-   even when they are inside the workspace. Symlinks targeting protected
-   paths are resolved and rejected too. Shell commands that reach these
-   paths via `cd && bash -lc '...'` or other wrappers go through the
-   classifier as well.
-2. **Safe-tool allowlist** — Read-only and metadata-only built-in tools
-   (Read, Grep, Glob, LS, LSP, TodoWrite, AskUserQuestion, etc.) are
-   auto-approved without invoking the classifier.
-3. **LLM classifier** — Everything else (shell commands, web fetches,
-   sub-agent spawns, edits outside the workspace, MCP tools) is sent to
-   a two-stage classifier:
-   - **Stage 1 (fast)** — outputs `{ shouldBlock }` only. Around ~300ms.
-     If `shouldBlock` is `false`, the action is allowed and the call
-     proceeds.
-   - **Stage 2 (thinking)** — only runs when Stage 1 said block. Uses
-     chain-of-thought review to reduce Stage 1 false positives. Can
-     downgrade Stage 1's block to allow. Outputs the user-visible
-     `reason` on block.
-
-The classifier uses your configured fast model
-(`/model --fast`). If no fast model is configured, the main session
-model is used instead.
-
-## Hard rules still win
-
-Auto Mode does **not** replace hard permission rules. Before the classifier
-runs:
-
-- `permissions.deny` rules block the action with the rule's reason. The
-  classifier never sees it.
-- `permissions.allow` rules with specific specifiers (e.g.
-  `Bash(git status)`, `Read(./docs/**)`) still auto-allow without the
-  classifier — **except** when the call resolves to a write at a
-  protected self-modification or persistence path (see the list under
-  "How it works"). In that case Auto Mode re-checks the call through
-  the classifier so an allow rule on `Bash(*)` cannot silently turn
-  into permission to rewrite Matilda Code settings, commands, hooks,
-  skills, or MCP servers.
-- `permissions.ask` rules force manual confirmation even in Auto Mode.
-
-## Over-broad allow rules are stripped while in Auto Mode
-
-Rules like the following would let the agent execute arbitrary code
-without classifier review:
-
-- `Bash` / `Bash(*)` / `Bash()` — auto-allow every shell command
-- `Bash(python:*)`, `Bash(node*)`, `Bash(bash*)` — interpreter wildcards
-- `Agent` / `Agent(coder)` — any allow on the Agent tool
-- `Skill` / `Skill(pdf)` — any allow on the Skill tool
-
-When you enter Auto Mode, Matilda Code temporarily removes these rules from
-the active permission set and prints a notice listing them. The rules
-come back the moment you leave Auto Mode. `settings.json` is never
-modified.
-
-If you genuinely need these broad rules, use YOLO mode instead.
-
-## Configuring hints
-
-Auto Mode reads `permissions.autoMode` from your `settings.json`. The
-entries are natural-language descriptions, not rule patterns — they are
-injected additively into the classifier's system prompt alongside the
-built-in defaults.
-
-There are three hint categories plus an environment list:
-
-- **`allow`** — actions the classifier should auto-approve.
-- **`softDeny`** — destructive or irreversible actions the classifier
-  should block **unless the user's most recent explicit request asked
-  for that exact action and scope**. Soft denies can be cleared by
-  user intent; a generic "yes do whatever" doesn't count.
-- **`hardDeny`** — security-boundary actions the classifier must block
-  in Auto Mode regardless of `autoMode.hints.allow` or recent user
-  intent. This is classifier policy, not a deterministic permission
-  rule: it does not override `permissions.allow`. Use `permissions.deny`
-  for actions that must never be allowed by the permission manager.
-
-```json
-{
-  "permissions": {
-    "autoMode": {
-      "hints": {
-        "allow": [
-          "Running poetry install and poetry update in this Python project",
-          "Cleaning build artifacts under ./dist or ./build",
-          "Reading any file under /Users/me/code/"
-        ],
-        "softDeny": [
-          "Editing Matilda Code settings unless I explicitly ask for the exact change",
-          "Running migration scripts that touch the production DB"
-        ],
-        "hardDeny": [
-          "Sending secrets or .env contents to any network endpoint",
-          "Modifying anything under ~/.ssh or ~/.aws"
-        ]
-      },
-      "environment": [
-        "This is a private monorepo with strict commit signing",
-        "Production credentials live in 1Password, never in plain files"
-      ]
-    }
-  }
-}
-```
-
-`hints.deny` is still accepted for backward compatibility and is treated
-as `softDeny`. Mixing both is fine — entries are concatenated, `softDeny`
-first.
-
-### Length and count limits
-
-To keep the classifier system prompt small:
-
-- Each entry is capped at 200 characters (longer entries are truncated
-  with a warning).
-- `hints.allow`, `hints.softDeny`, and `hints.hardDeny` accept up to 50
-  entries each.
-- `environment` accepts up to 20 entries.
-
-### Layering across settings files
-
-`autoMode` is merged across system / user / workspace settings the same
-way other permission settings are: arrays are concatenated and
-de-duplicated.
-
-## Reading the decision
-
-When the classifier blocks an action, the tool call fails with one of
-the following error texts:
-
-- **`Blocked by auto mode policy: <reason>`** —
-  the classifier judged the action unsafe. The reason comes from Stage
-  2 of the classifier.
-- **`Auto mode classifier unavailable; action blocked for safety`** —
-  the classifier API was unreachable, timed out, or returned an
-  un-parseable response. This is fail-closed behavior: when in doubt,
-  block.
-
-Both messages are followed by a trailing guidance line telling the agent
-that the **denied action specifically** must not be completed through
-another tool, shell indirection, generated script, alias, symlink,
-config change, hook, command file, MCP configuration, encoded payload,
-or equivalent path. **Unrelated safe work and genuinely safer
-alternatives are still allowed** — only attempts to accomplish the same
-denied intent through a different surface are blocked.
-
-If the denied action is genuinely required, the agent should stop and
-ask you for explicit approval rather than route around the denial.
-
-### Classifier reason language
-
-Classifier reasons are produced by the LLM and are not translated. If you
-want non-English reasons, add a hint like
-`Respond reasons in Chinese` to `permissions.autoMode.environment`.
-
-## Fallback to manual approval
-
-Auto Mode protects you from getting stuck:
-
-- After **3 consecutive policy blocks** the next tool call falls back to
-  the standard manual-approval prompt. This catches the case where the
-  agent keeps trying minor variants of a forbidden command.
-- After **2 consecutive unavailable** results (classifier API failures)
-  the next tool call also falls back. This avoids waiting on a broken
-  classifier.
-
-The session itself stays in Auto Mode — only the single fallback call
-goes through manual approval. The counters reset when you approve the
-fallback call or switch modes.
-
-If you find yourself constantly hitting fallback, the most likely causes
-are an outage on the classifier API or hints that need tuning. Switch to
-Default Mode while you investigate.
-
-## Troubleshooting
-
-**"Auto mode keeps blocking my commands"**
-
-Look at the reason in the error message. If the classifier is being too
-conservative for your context, add an entry to
-`permissions.autoMode.hints.allow` describing the pattern in
-natural-language. Examples:
-
-- `"Building Docker images for this project (docker build ...)"`
-- `"Running database migrations against the local test DB"`
-
-**"Auto mode classifier unavailable"**
-
-The classifier API didn't respond. Possible causes:
-
-- Network issue between you and the model endpoint.
-- The configured fast model is no longer available — check `/model --fast`.
-- The transcript is too long and exceeds the fast-model context window.
-
-While diagnosing, switch back to Default Mode: `/approval-mode default`.
-
-**"Falling back to manual approval"**
-
-You've hit either the 3-consecutive-block or 2-consecutive-unavailable
-guard. Approve or reject the prompt as you normally would. After one
-approved fallback the consecutive counter resets.
-
-**The classifier sees sensitive data in my prompts**
-
-Tool inputs are projected through each tool's `toAutoClassifierInput`
-method before they reach the classifier. Long edit content, web fetch
-prompts, and sub-agent prompts are truncated. Tool results (file
-contents, web pages) are never sent to the classifier — only the user's
-text and assistant tool-use calls go through.
-
-If a specific tool is exposing fields you'd rather redact, file an issue
-with the tool name; the projection is per-tool and is meant to be
-tightened over time.
-
-## Limitations
-
-- **Not offline-capable.** The classifier requires an LLM call.
-- **Adds latency on the slow path.** Allowlist + acceptEdits cover most
-  calls without latency, but a `run_shell_command` typically adds
-  ~300ms (fast classifier path) or ~3-5s (slow path with thinking
-  review).
-- **Not a substitute for `deny` rules.** The classifier is best-effort.
-  For commands you're sure should never run, put them in
-  `permissions.deny`.
-- **MCP tools default to conservative blocking.** Third-party MCP tools
-  (`mcp__*`) opt-in to argument forwarding via the
-  `toAutoClassifierInput` override. Tools that have not opted in expose
-  only their name to the classifier — most such calls are
-  conservatively blocked unless you've written an explicit `allow`
-  rule. This is fail-closed by design (credentials and voluminous
-  content do not leak into the classifier LLM). If you trust a
-  specific MCP tool, add `permissions.allow: ["mcp__server__tool"]` so
-  it bypasses the classifier entirely.
-
-## FAQ
-
-**Does Auto Mode send my code to a third party?**
-
-Auto Mode reuses your existing model configuration — same endpoint as
-the main agent. If you've configured Matilda Code to use a self-hosted
-model, the classifier runs against that endpoint too.
-
-**Will my secrets / `.env` contents reach the classifier?**
-
-The classifier sees only what each tool's `toAutoClassifierInput`
-projection exposes:
-
-- `read_file` and other read-only tools: not invoked (they're on the
-  fast-path allowlist).
-- `edit` / `write_file`: file_path plus the first 80 characters of
-  old/new content. Full content is not forwarded.
-- `run_shell_command`: the full command (it has to — that's what the
-  classifier judges).
-- `web_fetch`: the URL only. The prompt field is not forwarded.
-- `agent`: subagent type plus the full prompt. The prompt is the
-  instruction the sub-agent will follow, so the classifier needs it
-  in full to detect attacks that would steer the sub-agent toward
-  destructive actions — same reason `run_shell_command` forwards the
-  full command.
-
-Tool results (the actual content returned by tools) are stripped from
-the classifier transcript entirely.
-
-MCP tools (`mcp__*`) follow a stricter default: their parameters are
-not forwarded unless the MCP tool author explicitly opted in via the
-`toAutoClassifierInput` override. The classifier sees the tool name
-but no arguments, so most MCP calls will be conservatively blocked
-unless the user has written an explicit allow rule. This is fail-
-closed by design — third-party tools should not leak credentials or
-voluminous file content into the classifier LLM without intent.
-
-**Can I disable the first-time information message?**
-
-It only shows once per user-settings file. After dismissal,
-`ui.autoModeAcknowledged: true` is set in your user settings.
-
-**How is this different from Auto-Edit?**
-
-Auto-Edit auto-approves file edits and nothing else — shell commands
-still ask. Auto Mode uses a classifier to also auto-approve safe shell
-commands and other tool calls while still blocking risky ones.
-
-**How is this different from YOLO?**
-
-YOLO auto-approves everything without any review. Auto Mode has the
-classifier in the loop and blocks risky actions.

package/bundled/mainy/docs/features/channels/_meta.ts

@@ -1,8 +0,0 @@
-export default {
-  overview: 'Overview',
-  telegram: 'Telegram',
-  weixin: 'WeChat',
-  dingtalk: 'DingTalk',
-  feishu: 'Feishu',
-  plugins: 'Plugins',
-};

package/bundled/mainy/docs/features/channels/dingtalk.md

@@ -1,134 +0,0 @@
-# DingTalk (Dingtalk)
-
-This guide covers setting up a Matilda Code channel on DingTalk (钉钉).
-
-## Prerequisites
-
-- A DingTalk organization account
-- A DingTalk bot application with AppKey and AppSecret (see below)
-
-## Creating a Bot
-
-1. Go to the [DingTalk Developer Portal](https://open-dev.dingtalk.com)
-2. Create a new application (or use an existing one)
-3. Under the application, enable the **Robot** capability
-4. In Robot settings, enable **Stream Mode** (机器人协议 → Stream 模式)
-5. Note the **AppKey** (Client ID) and **AppSecret** (Client Secret) from the application credentials page
-
-### Stream Mode
-
-DingTalk Stream mode uses an outbound WebSocket connection — no public URL or server is needed. The bot connects to DingTalk's servers, which push messages through the WebSocket. This is the simplest deployment model.
-
-## Configuration
-
-Add the channel to `~/.matilda/settings.json`:
-
-```json
-{
-  "channels": {
-    "my-dingtalk": {
-      "type": "dingtalk",
-      "clientId": "$DINGTALK_CLIENT_ID",
-      "clientSecret": "$DINGTALK_CLIENT_SECRET",
-      "senderPolicy": "open",
-      "sessionScope": "user",
-      "cwd": "/path/to/your/project",
-      "instructions": "You are a concise coding assistant responding via DingTalk.",
-      "groupPolicy": "open",
-      "groups": {
-        "*": { "requireMention": true }
-      }
-    }
-  }
-}
-```
-
-Set the credentials as environment variables:
-
-```bash
-export DINGTALK_CLIENT_ID=<your-app-key>
-export DINGTALK_CLIENT_SECRET=<your-app-secret>
-```
-
-Or define them in the `env` section of `settings.json`:
-
-```json
-{
-  "env": {
-    "DINGTALK_CLIENT_ID": "your-app-key",
-    "DINGTALK_CLIENT_SECRET": "your-app-secret"
-  }
-}
-```
-
-## Running
-
-```bash
-# Start only the DingTalk channel
-matilda channel start my-dingtalk
-
-# Or start all configured channels together
-matilda channel start
-```
-
-Open DingTalk and send a message to the bot. You should see a 👀 emoji reaction appear while the agent processes, followed by the response.
-
-## Group Chats
-
-DingTalk bots work in both DM and group conversations. To enable group support:
-
-1. Set `groupPolicy` to `"allowlist"` or `"open"` in your channel config
-2. Add the bot to a DingTalk group
-3. @mention the bot in the group to trigger a response
-
-By default, the bot requires an @mention in group chats (`requireMention: true`). Set `"requireMention": false` for a specific group to make it respond to all messages. See [Group Chats](./overview#group-chats) for full details.
-
-### Finding a Group's Conversation ID
-
-DingTalk uses `conversationId` to identify groups. You can find it in the channel service logs when someone sends a message in the group — look for the `conversationId` field in the log output.
-
-## Images and Files
-
-You can send photos and documents to the bot, not just text.
-
-**Photos:** Send an image (screenshot, diagram, etc.) and the agent will analyze it using its vision capabilities. This requires a multimodal model — add `"model": "matilda3.5-plus"` (or another vision-capable model) to your channel config. DingTalk supports sending images directly or as part of rich text messages (mixed text + images).
-
-**Files:** Send a PDF, code file, or any document. The bot downloads it from DingTalk's servers and saves it locally so the agent can read it with its file tools. Audio and video files are also supported. This works with any model.
-
-## Key Differences from Telegram
-
-- **Authentication:** AppKey + AppSecret instead of a static bot token. The SDK manages access token refresh automatically.
-- **Connection:** WebSocket stream instead of polling — no public IP or webhook URL needed.
-- **Formatting:** Responses use DingTalk's markdown dialect (a limited subset). Tables are automatically converted to plain text since DingTalk doesn't render them. Long messages are split into chunks at ~3800 characters.
-- **Working indicator:** A 👀 emoji reaction is added to the user's message while processing, then removed when the response is sent.
-- **Media download:** Two-step process — a `downloadCode` from the message is exchanged for a temporary download URL via DingTalk's API.
-- **Groups:** DingTalk uses `isInAtList` for @mention detection instead of parsing message entities.
-
-## Tips
-
-- **Use DingTalk markdown-aware instructions** — DingTalk supports a limited markdown subset (headers, bold, links, code blocks, but not tables). Adding instructions like "Use DingTalk markdown. Avoid tables." helps the agent format responses correctly.
-- **Restrict access** — In an organization context, `senderPolicy: "open"` may be acceptable. For tighter control, use `"allowlist"` or `"pairing"`. See [DM Pairing](./overview#dm-pairing) for details.
-- **Referenced messages** — Quoting (replying to) a user message includes the quoted text as context for the agent. Quoting bot responses is not yet supported.
-
-## Troubleshooting
-
-### Bot doesn't connect
-
-- Verify your AppKey and AppSecret are correct
-- Check that the environment variables are set before running `matilda channel start`
-- Make sure **Stream Mode** is enabled in the bot's settings on the DingTalk Developer Portal
-- Check the terminal output for connection errors
-
-### Bot doesn't respond in groups
-
-- Check that `groupPolicy` is set to `"allowlist"` or `"open"` (default is `"disabled"`)
-- Make sure you @mention the bot in the group message
-- Verify the bot has been added to the group
-
-### "No sessionWebhook in message"
-
-This means DingTalk didn't include a reply endpoint in the message callback. This can happen if the bot's permissions are misconfigured. Check the bot's settings in the Developer Portal.
-
-### "Sorry, something went wrong processing your message"
-
-This usually means the agent encountered an error. Check the terminal output for details.

package/bundled/mainy/docs/features/channels/feishu.md

@@ -1,186 +0,0 @@
-# Feishu (Lark)
-
-This guide covers setting up a Matilda Code channel on Feishu (飞书) / Lark.
-
-## Prerequisites
-
-- A Feishu organization account
-- A Feishu application with App ID and App Secret (see below)
-
-## Creating an Application
-
-1. Go to the [Feishu Open Platform](https://open.feishu.cn)
-2. Create a new application (or use an existing one)
-
-![](https://gw.alicdn.com/imgextra/i4/O1CN01ORb10i1JM0MQfhnsV_!!6000000001013-2-tps-2219-931.png)
-
-3. Under the application, enable the **Bot** capability (添加应用能力 → 机器人)
-
-![](https://gw.alicdn.com/imgextra/i4/O1CN01bClpxu1FZxyH4kNjJ_!!6000000000502-2-tps-2219-931.png)
-
-4. In **Event Subscriptions** (事件与回调), select **Long Connection** (使用长连接接收事件)
-
-![](https://gw.alicdn.com/imgextra/i1/O1CN01uIwzbl1ph8Kwq7hTI_!!6000000005391-2-tps-2219-1166.png)
-
-5. Add the event `im.message.receive_v1` (接收消息)
-
-![](https://gw.alicdn.com/imgextra/i2/O1CN01n7sZmV28s6WX0aDhw_!!6000000007987-2-tps-2219-1090.png)
-
-6. Note the **App ID** (Client ID) and **App Secret** (Client Secret) from the application credentials page
-
-![](https://gw.alicdn.com/imgextra/i2/O1CN01ag1yBh1DxfEUb4xmE_!!6000000000283-2-tps-2219-1166.png)
-
-### Required Permissions
-
-Enable the following permissions under **Permissions & Scopes** (权限管理):
-
-- `im:message` — Read and send messages
-- `im:message:send_as_bot` — Send messages as bot
-- `im:resource` — Access message resources (images, files)
-
-### Publish the Application
-
-After configuring permissions and events, create a version and publish it. The bot won't work until the application is published and approved.
-
-![](https://gw.alicdn.com/imgextra/i1/O1CN01GbNRcj1lVuACnkV6M_!!6000000004825-2-tps-2219-1090.png)
-
-## Configuration
-
-Add the channel to `~/.matilda/settings.json`:
-
-```json
-{
-  "channels": {
-    "my-feishu": {
-      "type": "feishu",
-      "clientId": "<your-app-id>",
-      "clientSecret": "<your-app-secret>",
-      "senderPolicy": "open",
-      "sessionScope": "user",
-      "cwd": "/path/to/your/project",
-      "groupPolicy": "open",
-      "collapsible": true,
-      "groups": {
-        "*": { "requireMention": true }
-      }
-    }
-  }
-}
-```
-
-### Configuration Options
-
-| Option                 | Description                                                         |
-| ---------------------- | ------------------------------------------------------------------- |
-| `clientId`             | Feishu App ID                                                       |
-| `clientSecret`         | Feishu App Secret                                                   |
-| `collapsible`          | Collapse long responses into expandable sections (default: `false`) |
-| `collapsibleThreshold` | Character threshold for collapsing (default: `500`)                 |
-| `webhookPort`          | If set, use HTTP webhook mode instead of WebSocket                  |
-| `verificationToken`    | Verification token for webhook mode                                 |
-| `encryptKey`           | Encrypt key for webhook mode                                        |
-
-## Running
-
-```bash
-# Start only the Feishu channel
-matilda channel start my-feishu
-
-# Or start all configured channels together
-matilda channel start
-```
-
-Open Feishu and send a message to the bot. You should see a streaming interactive card with the response.
-
-## Connection Modes
-
-### WebSocket (Default)
-
-WebSocket mode uses an outbound long connection — no public URL or server is needed. This is the recommended mode for most deployments.
-
-### Webhook
-
-If you need webhook mode (e.g., for shared applications), set `webhookPort` in your config:
-
-```json
-{
-  "channels": {
-    "my-feishu": {
-      "type": "feishu",
-      "webhookPort": 9321,
-      "verificationToken": "<from-feishu-console>",
-      "encryptKey": "<from-feishu-console>"
-    }
-  }
-}
-```
-
-Then set the request URL in Feishu Open Platform to `http://<your-server>:9321`.
-
-## Group Chats
-
-Feishu bots work in both DM and group conversations. To enable group support:
-
-1. Set `groupPolicy` to `"allowlist"` or `"open"` in your channel config
-2. Add the bot to a Feishu group
-3. @mention the bot in the group to trigger a response
-
-By default, the bot requires an @mention in group chats (`requireMention: true`). Set `"requireMention": false` for a specific group to make it respond to all messages.
-
-## Features
-
-### Interactive Card Streaming
-
-Responses are rendered as Feishu interactive cards with real-time streaming updates. The card shows a "generating" indicator while the response is being produced, and a **Stop** button to cancel generation.
-
-### Quote/Reply Context
-
-When you reply to (quote) a message, the quoted content is automatically included as context for the agent. This works for:
-
-- Text and rich-text messages
-- Interactive cards (bot's previous responses)
-
-### Images and Files
-
-You can send photos and documents to the bot:
-
-- **Images:** Analyzed using multimodal vision capabilities
-- **Files:** Downloaded and saved locally for the agent to read
-
-### Concurrent Messages
-
-Multiple users can send messages simultaneously in the same group chat. Each message gets its own independent card and response — they don't interfere with each other.
-
-## Key Differences from DingTalk
-
-- **Response format:** Uses Feishu interactive cards (v2 schema) with native markdown rendering, including tables
-- **Streaming:** Card content is updated in-place with throttled PATCH requests (1.5s interval)
-- **Connection:** WebSocket via `@larksuiteoapi/node-sdk` — same outbound-only model, no public URL needed
-- **Working indicator:** An "OnIt" emoji reaction is added while processing
-- **Quote context:** Supports quoting both text messages and interactive cards
-
-## Troubleshooting
-
-### Bot doesn't connect
-
-- Verify your App ID and App Secret are correct
-- Make sure **Long Connection** is selected in Event Subscriptions
-- Check that the `im.message.receive_v1` event is subscribed
-- Check the terminal output for connection errors
-
-### Bot doesn't respond in groups
-
-- Check that `groupPolicy` is set to `"allowlist"` or `"open"` (default is `"disabled"`)
-- Make sure you @mention the bot in the group message
-- Verify the bot has been added to the group
-
-### Card stays in "generating" state
-
-- This usually indicates the response completed but the final card update failed
-- Check terminal logs for API errors (rate limiting, card size limits)
-- Very long responses with many tables may hit Feishu's card element limits
-
-### Quote doesn't include card content
-
-- The bot reads card content via the `card_msg_content_type=user_card_content` API parameter
-- Ensure the bot has `im:message` permission to read messages