Skip to content
Closed
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
44 commits
Select commit Hold shift + click to select a range
0635538
fix(qqbot): restore per-group session isolation under thread scope
Eric-GoodBoy-Tech Jul 31, 2026
f9cc1bc
fix(qqbot): address review — release anchors on cancel, purge seq orp…
Eric-GoodBoy-Tech Aug 1, 2026
7f1912b
fix(qqbot): set reply anchor deterministically at prompt start, respe…
Eric-GoodBoy-Tech Aug 1, 2026
f2daf02
fix(qqbot): release reply anchor after the final send, guard seq cont…
Eric-GoodBoy-Tech Aug 1, 2026
a41cdad
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Aug 1, 2026
2fd94e3
fix(qqbot): address review — purge own-key orphans only, extract anch…
Eric-GoodBoy-Tech Aug 1, 2026
2d9c4f3
fix(qqbot): address round-6 review — guard seq cleanup, turn-scoped s…
Eric-GoodBoy-Tech Aug 1, 2026
5bf5498
fix(qqbot): address round-7 review — clear flush flags on stale-state…
Eric-GoodBoy-Tech Aug 2, 2026
d4b99e6
fix(qqbot): address round-8 review — turn-aware anchor release, flush…
Eric-GoodBoy-Tech Aug 2, 2026
f5ace0c
fix(qqbot): address wenshao review — flush on cancel, chat_thread war…
Eric-GoodBoy-Tech Aug 2, 2026
2189179
fix(qqbot): address round-9 review — close release-cascade and cancel…
Eric-GoodBoy-Tech Aug 2, 2026
bdd4b86
fix(qqbot): address round-10 review — turn-guard onResponseComplete, …
Eric-GoodBoy-Tech Aug 2, 2026
cbd7faa
fix(qqbot): address round-11 review — purge ownership, orphan side-bu…
Eric-GoodBoy-Tech Aug 3, 2026
144b63f
fix(qqbot): bound the orphan purge to single-scope keys and guard msg…
Eric-GoodBoy-Tech Aug 6, 2026
216d201
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Aug 6, 2026
ca7c546
fix(qqbot): order anchor release before stream-state teardown and cle…
Eric-GoodBoy-Tech Aug 6, 2026
f5c3317
fix(cli): accept chat_thread in channel-settings sessionScope validation
Eric-GoodBoy-Tech Aug 6, 2026
8c74b9d
Merge branch 'main' into fix/qqbot-session-scope-thread
Eric-GoodBoy-Tech Sep 25, 2026
9f96313
Merge branch 'main' into fix/qqbot-session-scope-thread
Eric-GoodBoy-Tech Sep 25, 2026
e7064f5
fix(qqbot): keep the reply anchor and label across the deferred-flush…
Eric-GoodBoy-Tech Sep 25, 2026
bd5f969
fix(qqbot): own the deferred-flush state in every teardown path
Eric-GoodBoy-Tech Sep 26, 2026
78799a2
fix(qqbot): hand a parked residual to the chain that can settle it
Eric-GoodBoy-Tech Sep 26, 2026
aa2a4e3
Merge remote-tracking branch 'origin/main' into HEAD
Eric-GoodBoy-Tech Sep 26, 2026
0c24ed2
fix(qqbot): keep the streamed buffer across a response boundary and a…
Eric-GoodBoy-Tech Sep 26, 2026
85bdc20
fix(qqbot): protect the msg_seq counter with one predicate and keep t…
Eric-GoodBoy-Tech Sep 27, 2026
1a27a2b
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Sep 27, 2026
870f74c
fix(qqbot): reclaim the counter the teardown destroys, and hand the s…
Eric-GoodBoy-Tech Sep 27, 2026
62cc80a
test(qqbot): label the two self-review cases apart from the review's …
Eric-GoodBoy-Tech Sep 27, 2026
e3a671b
fix(qqbot): give the msg_seq counter and the sealed head a single owner
Eric-GoodBoy-Tech Sep 28, 2026
8ad692a
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Sep 28, 2026
99cb80c
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Sep 28, 2026
9616c55
fix(qqbot): seal the live turn's buffer-resident prefix at a response…
Eric-GoodBoy-Tech Sep 28, 2026
381806f
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Sep 28, 2026
0eb9d23
fix(qqbot): scope the flush success clear to the seal that send carried
Eric-GoodBoy-Tech Sep 28, 2026
9f2562e
fix(qqbot): deliver the sealed head when its turn's completion alread…
Eric-GoodBoy-Tech Sep 28, 2026
f5e7d29
fix(qqbot): fail closed before purging routes, and seal stashes the h…
Eric-GoodBoy-Tech Sep 29, 2026
b2c8c0c
fix(qqbot): retry a rate-limited cancelled stash, and rescue the rout…
Eric-GoodBoy-Tech Sep 29, 2026
5e61155
fix(qqbot): bound the completion record to its turn, and record cwd i…
Eric-GoodBoy-Tech Sep 30, 2026
80d306f
fix(qqbot): recover a carried seal, keep its turn's anchor, and gate …
Eric-GoodBoy-Tech Sep 30, 2026
b04e31f
fix(qqbot): seal what a boundary cleared, bound the diverted stash, and
Eric-GoodBoy-Tech Sep 30, 2026
ae09388
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Oct 1, 2026
e857c0f
fix(qqbot): gate the settling flush chain on session and turn ownership
Eric-GoodBoy-Tech Oct 1, 2026
2c3f3c2
fix(qqbot): bound the handoff stash write and keep the sealed head whole
Eric-GoodBoy-Tech Oct 1, 2026
a7c79f5
Merge remote-tracking branch 'origin/main' into fix/qqbot-session-sco…
Eric-GoodBoy-Tech Oct 1, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 26 additions & 25 deletions docs/users/features/channels/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,30 +50,30 @@ Channels are configured under the `channels` key in `settings.json`. Each channe

### Options

| Option | Required | Description |
| ------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | Yes | Channel type: `telegram`, `weixin`, `qq`, `dingtalk`, `wecom`, `feishu`, `github`, or a custom type from an extension (see [Plugins](./plugins)) |
| `token` | Telegram | Bot token. Supports `$ENV_VAR` syntax to read from environment variables. Not needed for WeChat, DingTalk, WeCom, or Feishu |
| `clientId` | DingTalk, Feishu | DingTalk AppKey or Feishu App ID. Supports `$ENV_VAR` syntax |
| `clientSecret` | DingTalk, Feishu | DingTalk AppSecret or Feishu App Secret. Supports `$ENV_VAR` syntax |
| `botId` | WeCom | WeCom intelligent robot Bot ID. Supports `$ENV_VAR` syntax. See [WeCom](./wecom) |
| `secret` | WeCom | WeCom intelligent robot Secret. Supports `$ENV_VAR` syntax. See [WeCom](./wecom) |
| `model` | No | Model to use for this channel (e.g., `qwen3.5-plus`). Overrides the default model. Useful for multimodal models that support image input |
| `senderPolicy` | No | Who can talk to the bot: `allowlist` (default), `open`, or `pairing` |
| `allowedUsers` | No | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies) |
| `sessionScope` | No | How sessions are scoped: `user` (default), `thread`, or `single` |
| `cwd` | No | Working directory for the agent. Defaults to the current directory |
| `approvalMode` | No | Tool approval mode for channel sessions. Unattended webhook tasks require `yolo`; the setting applies to every session on the channel |
| `instructions` | No | Custom instructions prepended to the first message of each session |
| `webhooks` | No | Webhook sources and delivery targets for daemon-managed channels. See [Webhook-triggered tasks](#webhook-triggered-tasks) |
| `groupPolicy` | No | Group chat access: `disabled` (default), `allowlist`, or `open`. See [Group Chats](#group-chats) |
| `dmPolicy` | No | Private/DM access: `open` (default) or `disabled` (silently drop all DMs). Useful for group-only bots |
| `groupHistoryLimit` | No | Opt-in group history backfill. `0` or omitted disables it. A positive number persists that many authorized, unmentioned group messages for the next bot mention/reply. |
| `groups` | No | Per-group settings. Keys are group chat IDs or `"*"` for defaults. See [Group Chats](#group-chats) |
| `dispatchMode` | No | What happens when you send a message while the bot is busy: `steer` (default), `collect`, or `followup`. See [Dispatch Modes](#dispatch-modes) |
| `blockStreaming` | No | Progressive response delivery: `on` or `off` (default). See [Block Streaming](#block-streaming) |
| `blockStreamingChunk` | No | Chunk size bounds: `{ "minChars": 400, "maxChars": 1000 }`. See [Block Streaming](#block-streaming) |
| `blockStreamingCoalesce` | No | Idle flush: `{ "idleMs": 1500 }`. See [Block Streaming](#block-streaming) |
| Option | Required | Description |
| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | Yes | Channel type: `telegram`, `weixin`, `qq`, `dingtalk`, `wecom`, `feishu`, `github`, or a custom type from an extension (see [Plugins](./plugins)) |
| `token` | Telegram | Bot token. Supports `$ENV_VAR` syntax to read from environment variables. Not needed for WeChat, DingTalk, WeCom, or Feishu |
| `clientId` | DingTalk, Feishu | DingTalk AppKey or Feishu App ID. Supports `$ENV_VAR` syntax |
| `clientSecret` | DingTalk, Feishu | DingTalk AppSecret or Feishu App Secret. Supports `$ENV_VAR` syntax |
| `botId` | WeCom | WeCom intelligent robot Bot ID. Supports `$ENV_VAR` syntax. See [WeCom](./wecom) |
| `secret` | WeCom | WeCom intelligent robot Secret. Supports `$ENV_VAR` syntax. See [WeCom](./wecom) |
| `model` | No | Model to use for this channel (e.g., `qwen3.5-plus`). Overrides the default model. Useful for multimodal models that support image input |
| `senderPolicy` | No | Who can talk to the bot: `allowlist` (default), `open`, or `pairing` |
| `allowedUsers` | No | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies) |
| `sessionScope` | No | How sessions are scoped: `user` (default), `thread`, `chat_thread`, or `single`. Channel plugins may declare a different default (QQ defaults to `thread`; GitHub and GitLab default to `chat_thread`) |
| `cwd` | No | Working directory for the agent. Defaults to the current directory |
| `approvalMode` | No | Tool approval mode for channel sessions. Unattended webhook tasks require `yolo`; the setting applies to every session on the channel |
| `instructions` | No | Custom instructions prepended to the first message of each session |
| `webhooks` | No | Webhook sources and delivery targets for daemon-managed channels. See [Webhook-triggered tasks](#webhook-triggered-tasks) |
| `groupPolicy` | No | Group chat access: `disabled` (default), `allowlist`, or `open`. See [Group Chats](#group-chats) |
| `dmPolicy` | No | Private/DM access: `open` (default) or `disabled` (silently drop all DMs). Useful for group-only bots |
| `groupHistoryLimit` | No | Opt-in group history backfill. `0` or omitted disables it. A positive number persists that many authorized, unmentioned group messages for the next bot mention/reply. |
| `groups` | No | Per-group settings. Keys are group chat IDs or `"*"` for defaults. See [Group Chats](#group-chats) |
| `dispatchMode` | No | What happens when you send a message while the bot is busy: `steer` (default), `collect`, or `followup`. See [Dispatch Modes](#dispatch-modes) |
| `blockStreaming` | No | Progressive response delivery: `on` or `off` (default). See [Block Streaming](#block-streaming) |
| `blockStreamingChunk` | No | Chunk size bounds: `{ "minChars": 400, "maxChars": 1000 }`. See [Block Streaming](#block-streaming) |
| `blockStreamingCoalesce` | No | Idle flush: `{ "idleMs": 1500 }`. See [Block Streaming](#block-streaming) |

### Sender Policy

Expand All @@ -87,8 +87,9 @@ Controls who can interact with the bot:

Controls how conversation sessions are managed:

- **`user`** (default) — One session per user. All messages from the same user share a conversation.
- **`user`** (default) — One session per user. All messages from the same user share a conversation. `user` is the global default, but a channel plugin can declare a different default for its type: the QQ channel defaults to `thread`, while the GitHub and GitLab channels default to `chat_thread`.
- **`thread`** — One session per thread/topic. Useful for group chats with threads.
- **`chat_thread`** — One session per chat and thread, shared across participants even outside a group (for example, an issue or PR discussion).
- **`single`** — One shared session for all users. Everyone shares the same conversation.

### Channel Memory
Expand Down
12 changes: 11 additions & 1 deletion docs/users/features/channels/qqbot.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ export QQ_APP_SECRET=<your-app-secret>
"appSecret": "$QQ_APP_SECRET",
"sandbox": false,
"senderPolicy": "open",
"sessionScope": "user",
"sessionScope": "thread",
"cwd": "/path/to/your/project",
"instructions": "你是一个通过 QQ Bot 对话的 AI 助手。回复控制在 2000 字符以内。",
"blockStreaming": "on",
Expand All @@ -73,6 +73,8 @@ export QQ_APP_SECRET=<your-app-secret>
}
```

> `sessionScope` defaults to `"thread"`. With `groupPolicy: "disabled"` this is a DM-only setup, where both `"thread"` and `"user"` behave identically — each direct message gets its own context. `"thread"` is shown here for consistency with the [Session Isolation](#session-isolation) section below.

### QQ-Specific Options

| Option | Default | Description |
Expand Down Expand Up @@ -106,6 +108,14 @@ To use the bot in QQ groups:

QQ Bot API V2 only delivers group messages that @mention the bot — the bot does not see all group messages. By default, `requireMention` is `true` and should be left that way for QQ.

### Session Isolation

The QQ channel defaults to `sessionScope: "thread"`: members of the same group share a single conversation context keyed by `<channel>:<group_openid>`, while different groups are isolated from each other. Each direct message gets its own context keyed by `<channel>:<user_openid>`.

A group thread session is a **shared session**: every member of the group reads and continues the same conversation history. Session-control commands (`/clear`, `/cancel`) and the `!` host-shell gate act on that shared session — in `"thread"` scope they affect the whole group, restricted to `allowedUsers` members when the list is non-empty. Permission-request answers are gated separately, by **chat + thread**: you can answer a pending permission request only for the same chat and thread you are in, and in a shared group session any member may do so — this gating is independent of `sessionScope`. If group members should not share history or control each other's turns, set `sessionScope: "user"` (each member gets a private session) or restrict membership via `senderPolicy` / `allowedUsers`.

For full-message mode this default is already what you want — with `groupAllPolicy: "all"`, keeping `"thread"` gives you shared context within a group and isolation across groups. If you instead set `sessionScope: "user"`, full-message traffic is fragmented per sender (a separate session for every member), which is not suitable for group full-message scenarios.

See [Group Chats](./overview#group-chats) for full details on group policies and mention gating.

## Markdown Support
Expand Down
Loading
Loading