Skip to content

Commit 6294957

Browse files
turmindhalo
andcommitted
docs: sync design notes and channel docs for 1.3.2
WeCom (14050da shipped with no documentation) - guide/channels/wecom.md: onboarding — create the 智能机器人, switch to API mode + 长连接, copy Bot ID / Secret, add in admin, access levels, media rules, cron targets, common problems. - design/wecom.md: architecture over the SDK's WSClient, channel_accounts row shape, session strategy, auth / reconnect budgets, frame protocol, 5000-char stream split, 20 MB media, no-HTTP-send cron path. - README / README.zh-CN channel tables, INDEX.md, guide/channels/README.md (comparison + admin-form tables, diagram, design-doc pointer), dev/api.md (/api/wecom/accounts), design/cron.md dispatcher list + chatId rules, design/storage.md channel_type list. Design drift from this release's code changes - ws.md / session.md: exchange:delete carries the client's archiveCount anchor; only a mismatch is refused ('archived'). Types are sourced from @turmind/halo-core/protocol; __ping__ is in WsClientMessage. chat:system gains the refusal notice. - session.md: classifyModelError as the retry decision (kinds, first match wins); throttle keyed on ThrottlingException / 429 before keywords; refusal stop never enters the retry matrix. - storage.md: Schema change rules rewritten for PRAGMA user_version + ordered per-db migration lists (db/migrate.ts); SessionMessage type provenance; changelog row. - cron.md: run_at is CRON_MIGRATIONS slot 0. - evolution.md: sandbox copy is copyDereferenced, and why cpSync's dereference couldn't be trusted (nodejs/node#59168). Co-Authored-By: halo <[email protected]>
1 parent e228645 commit 6294957

12 files changed

Lines changed: 416 additions & 25 deletions

File tree

‎.halo/INDEX.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ Halo currently supports these input channels — onboarding guides at [guide/cha
5151
- **Telegram**: Bot API long polling, register with token — onboarding [guide/channels/telegram.md](docs/guide/channels/telegram.md), design [design/telegram.md](docs/design/telegram.md)
5252
- **Slack**: Socket Mode (wss long-connect), no public webhook required — onboarding [guide/channels/slack.md](docs/guide/channels/slack.md), design [design/slack.md](docs/design/slack.md)
5353
- **Feishu / Lark**: long-connect with appId + appSecret — onboarding [guide/channels/feishu.md](docs/guide/channels/feishu.md), design [design/feishu.md](docs/design/feishu.md)
54+
- **WeCom (企业微信)**: 智能机器人 long-connect with bot id + secret, no HTTP send API (replies, cron pushes and media all ride the same wss) — onboarding [guide/channels/wecom.md](docs/guide/channels/wecom.md), design [design/wecom.md](docs/design/wecom.md)
5455
- **WeChat**: Scan to bind via mobile WeChat, uses default agent — onboarding [guide/channels/wechat.md](docs/guide/channels/wechat.md), design [design/wechat.md](docs/design/wechat.md)
5556
- **CLI/TUI**: Standalone terminal client, embedded agent loop (no server required) — see [guide/cli.md](docs/guide/cli.md)
5657
- **ACP adapter**: stdio JSON-RPC bridge for Claude Code etc., rides on the Web channel — onboarding [guide/channels/acp.md](docs/guide/channels/acp.md), protocol [dev/acp-adapter.md](docs/dev/acp-adapter.md)
@@ -93,7 +94,7 @@ Key state:
9394
- `~/.halo/global/cron.db` — global tables `cron_jobs` (with `run_at` column for at-mode) + `cron_runs`
9495
- `~/.halo/global/logs/cron/<runId>.log` — per-run cli stdout/stderr (30-day retention)
9596

96-
Driven from `packages/server/src/cron/` (runner + registry) + per-channel `cron-dispatcher.ts` files (telegram / wechat / slack / feishu) + `packages/server/templates/skills/cron/` (the agent-facing skill, which receives `{{channel.type/account_id/chat_id}}` placeholders so it can default targets to the current chat when invoked from any of the four channels, and uses `list --chat-id <id>` to reverse-look-up subscriptions when the user asks "delete my cron" from inside a chat).
97+
Driven from `packages/server/src/cron/` (runner + registry) + per-channel `cron-dispatcher.ts` files (telegram / wechat / slack / feishu / wecom) + `packages/server/templates/skills/cron/` (the agent-facing skill, which receives `{{channel.type/account_id/chat_id}}` placeholders so it can default targets to the current chat when invoked from any of the five channels, and uses `list --chat-id <id>` to reverse-look-up subscriptions when the user asks "delete my cron" from inside a chat).
9798

9899
## Goal Mode
99100

‎.halo/docs/design/cron.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ cron_jobs (global db) registered at boot:
99
│ ┌── slack/cron-dispatcher
1010
▼ reloadAll / reconcileFromDb ├── feishu/cron-dispatcher
1111
runner.ts ──── croner schedule ──┐ ├── telegram/cron-dispatcher
12-
│ │ └── wechat/cron-dispatcher
12+
│ │ ├── wechat/cron-dispatcher
13+
│ │ └── wecom/cron-dispatcher
1314
│ fire │ ▲
1415
▼ │ │ registerCronDispatcher
1516
spawn `halo cli -n -s cron-<id>` │ dispatcher.ts (registry)
@@ -27,7 +28,7 @@ Two halves, cleanly split:
2728
Schedules are **durable** — the source of truth is the `cron_jobs` table; in-memory croner state is rebuilt on every server boot (`startCronDaemon` → `reloadAll`). A restart never loses a schedule.
2829

2930
- **Recurring**: standard cron expression (`job.schedule`), optional `timezone`.
30-
- **One-shot**: `job.runAt` (epoch ms) — croner fires once at that instant. After it completes, `finalize` sets `enabled=0` so it never re-fires. A `runAt` already in the past at schedule time is marked `lastRunStatus='missed'` and disabled (rather than firing immediately or retrying every reconcile).
31+
- **One-shot**: `job.runAt` (epoch ms) — croner fires once at that instant. After it completes, `finalize` sets `enabled=0` so it never re-fires. A `runAt` already in the past at schedule time is marked `lastRunStatus='missed'` and disabled (rather than firing immediately or retrying every reconcile). The `run_at` column is `CRON_MIGRATIONS` slot 0 in `db/cron-db.ts`, run through the shared `runMigrations` / `PRAGMA user_version` mechanism (see [storage.md](storage.md#schema-change-rules)).
3132

3233
### Trigger-mode exclusivity (the db contract)
3334

@@ -90,11 +91,11 @@ interface CronChannelDispatcher {
9091
- `dispatchToTargets` is **never throws** — every target's outcome (ok / error) is captured into a `DispatchResult[]` persisted to `cron_runs.dispatch_results`. One channel being down doesn't block the others.
9192
- **`MEDIA:` attachments**: the runner passes raw stdout down untouched; `dispatchToTargets(rawText, targets, workspacePath)` extracts the agent's `MEDIA:<path>` marker lines once, then decides **per target** (one run can mix both kinds of channel):
9293
- `supportsMedia: true` (wechat, slack) → marker-stripped text + a `CronMedia { paths, workspacePath }`; the channel sends real file uploads, one `DispatchResult` row per attachment. Both skip the text send when a marker-only run leaves it empty.
93-
- no `supportsMedia` (telegram, feishu) → the **original text with `MEDIA:` lines intact** — the attachment degrades to a visible path instead of silently vanishing.
94+
- no `supportsMedia` (telegram, feishu, wecom) → the **original text with `MEDIA:` lines intact** — the attachment degrades to a visible path instead of silently vanishing.
9495
- `CronMedia.workspacePath` is the **job's** workspace (where the run produced its files), not the target account's — it's the sandbox root for `isMediaPathAllowed` (paths outside workspace/OS-tmp are rejected with a failed result row).
9596
- Wiring telegram/feishu up for real requires refactoring first, not copying: telegram's file send is an inline `sendPhoto/…/sendDocument` switch in `handler.ts`'s responder; feishu's `sendFeishuMedia` is anchored to an inbound `messageId` a cron run doesn't have. Extract the send-to-chat half in the channel module, then flip `supportsMedia: true` (details in each `cron-dispatcher.ts` header).
9697
- **Per-channel size limits are the dispatcher's job**, not the runner's: wechat splits the text at `WECHAT_TEXT_LIMIT` (3500 chars, shared `splitText` from `channels/shared/chunk.ts`) and sends the chunks in order — the ilink gateway rejects any single `sendmessage` over 16 KB with `ret=-2`. A failure on chunk *i* of *n* is recorded as `chunk i/n: <error>` in the target's `DispatchResult`, so the admin run row shows how much of the report already landed (a `failed` row no longer means "nothing arrived"). Telegram still sends one shot (Bot API caps at 4096) — same class of gap, unfixed.
97-
- **`chatId` semantics**: when a job is created from inside a chat, the target pins to that conversation (`chatId` set). When unset, the channel's own fan-out / default-recipient logic decides (e.g. Telegram fans out to its whitelist; Slack/Feishu require an explicit `chatId`).
98+
- **`chatId` semantics**: when a job is created from inside a chat, the target pins to that conversation (`chatId` set). When unset, the channel's own fan-out / default-recipient logic decides (e.g. Telegram fans out to its whitelist; Slack/Feishu/WeCom require an explicit `chatId`). WeCom is the one dispatcher with **no HTTP send path**: it borrows the handler's live long-connect `WSClient` (`liveClients`), so a stopped / kicked / auth-exhausted account fails the target loudly (`wecom long-connect not active`) instead of queueing.
9899
- `listTargets()` aggregates across all dispatchers (`listAllCronTargets`) to feed the admin create-form dropdown without the routes knowing any channel.
99100

100101
## Retention

‎.halo/docs/design/evolution.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ The `target` can be any file in the prompt surface — `INSTRUCTIONS.md`, the ag
106106

107107
Sandbox is whitelist-cp from main workspace (only: `INSTRUCTIONS.md`, `INDEX.md`, `USER.md`, `agents/`, `prompts/`, `skills/`, `docs/`). Agent reads via `file_read`, writes only to `.halo/` subset.
108108

109+
The copy is `copyDereferenced` (`evo-wrapper.ts:1419`), a hand-rolled recursive walk that resolves every symlink to its target's bytes, so the sandbox holds contents and never a link back into the live workspace (an evo edit through a link would write straight into main). It replaced `fs.cpSync({ dereference: true })` because Node ≥ 22.17 ignores `dereference` for symlinks nested below the top level (nodejs/node#59168; fix merged 2026-09-18, unreleased at the time).
110+
109111
### Phase B — Dry-run + Fix Loop
110112

111113
```

0 commit comments

Comments
 (0)