@turmind/halo 0.1.9

package/bundled-docs/design/feishu.md

@@ -0,0 +1,224 @@
+# Feishu/Lark Channel — Design
+
+Let the user talk to Halo from Feishu (Lark) on their phone, sharing the same workspace + sessions as the web side. All channels are peers — each one is a subscriber + caller against SessionManager.
+
+## Architecture
+
+```
+                       ┌── ws/ (web channel)            ─┐
+                       ├── channels/telegram/            │
+Halo server (9527) ──┤├── channels/wechat/              ├── SessionManager
+                       ├── channels/slack/               │    (per workspace, via Registry)
+                       └── channels/feishu/ ←─ long-connect (wss) ─┘
+                                    ↕ Lark.WSClient
+                           https://open.feishu.cn
+```
+
+Feishu uses the official SDK's `Lark.WSClient` to maintain a persistent WebSocket connection for event delivery. Unlike Slack/Telegram (which use webhooks + polling respectively), Feishu's long-connect receives `im.message.receive_v1` events pushed by the server over wss.
+
+## Data model
+
+### Workspace ↔ Bot mapping
+
+One Feishu app (= one appId + appSecret pair) is bound to one workspace. A workspace can bind multiple apps.
+
+### Session strategy
+
+- **One Feishu user → many sessions (one active at a time, per thread)**
+- Session ID format: `feishu_<chatId>:<rootId>_<createdAtBase36>`
+- In p2p (DM): rootId anchored to `dm` for a stable key across multiple messages
+- In group: each thread is its own bounded session, keyed by the thread's root message id
+- Sessions live under the bot's bound workspace and use the highest-priority agent (falls back to `default` only when none exists)
+- Access level inherited from the account's `accessLevel` field (see below)
+
+### Access level
+
+Each account carries `accessLevel: 'full' | 'workspace' | 'readonly'` (default `readonly`):
+- `full` — no restrictions (no sandbox)
+- `workspace` — tool execution runs inside a bwrap sandbox with the workspace mounted read-write
+- `readonly` — tool execution runs inside a bwrap sandbox with the workspace mounted read-only; readonly sessions only receive read-only tools
+
+### Storage
+
+Feishu bot accounts are stored in the unified channel DB: `~/.halo/secrets/channels/channels.db`, table `channel_accounts` with `channel_type = 'feishu'`. See [storage.md](storage.md#channel_accounts) for the full schema.
+
+Feishu-specific config JSON fields: `appId`, `appSecret`, `verificationToken` (legacy), `encryptKey` (optional), `botOpenId`, `lastActiveChatId`.
+
+- `lastActiveChatId` is a runtime cache of the most recent `<chatId>:<rootId>` pair. Written by `rememberLastActiveChat()` in `channels/shared/accounts.ts` on every inbound message (idempotent). Not consumed by cron dispatch (the dispatcher requires an explicit `chatId`); it is kept as a runtime cache for any future "reply to whoever talked last" feature.
+
+### Authentication model
+
+- `appId` + `appSecret` are long-lived credentials from the Feishu open platform
+- Used to mint short-lived `tenant_access_token` (~2 hour lifetime) for all API calls
+- `verificationToken` and `encryptKey` handle webhook security (for legacy webhook setups; not used with long-connect)
+- `botOpenId` is the bot's own open_id, used to detect mentions in group chats
+
+Token caching is in-memory per-app in `api.ts:tokenCache`; refresh happens on-demand 60s before expiry.
+
+### Proactive sending (cron)
+
+The feishu cron-dispatcher (`channels/feishu/cron-dispatcher.ts`) requires an explicit `chatId` — there is no fallback to `lastActiveChatId`. When a cron fires:
+
+1. **Explicit `chatId` on the target** — set when the cron was created from inside a Feishu chat (e.g. cron created from a group thread auto-pins to that thread). Sends only to that chat (top-level message, not nested in the thread — Feishu's open API v1 doesn't support thread-targeting in sendMessage).
+2. **Admin-UI cron without explicit target** — runs silently if no chatId is provided.
+
+## Modules
+
+Files: `packages/server/src/channels/feishu/`
+
+- `types.ts` — FeishuAccount, FeishuEventEnvelope, FeishuMessageEvent interfaces
+- `accounts.ts` — DAL (listAccounts / getAccount / insertAccount / updateAccount / deleteAccount / findAccountByAppId)
+- `handler.ts` — Lark.WSClient setup, event dispatch, message handling, session routing, mention detection, media ingestion
+- `event-adapter.ts` — AgentSessionEvent stream → coalesced Feishu message replies (buffer + flush at paragraph boundaries)
+- `api.ts` — HTTP client (tenant token caching / getBotInfo / sendMessage / replyMessage / uploadImage / uploadFile / downloadResource / decryptWebhookBody / searchFeishuTargets / openLongConnection)
+- `cron-dispatcher.ts` — registers the cron dispatcher, requires explicit chatId targets
+- `descriptor.ts` — ServerChannelDescriptor entry point
+
+Routes: `packages/server/src/routes/feishu.ts`
+
+- `GET /api/feishu/accounts` — list bot accounts (admin)
+- `POST /api/feishu/accounts` — register a bot (validates credentials via `getBotInfo`, auto-resolves botOpenId)
+- `PATCH /api/feishu/accounts/:id` — update config / enable / disable
+- `DELETE /api/feishu/accounts/:id` — remove + stop
+- `GET /api/feishu/accounts/:id/search` — search chats by name (for cron target picker)
+
+## Bot lifecycle
+
+1. User registers a bot via the API (provides appId + appSecret + workspace)
+2. Server calls `getBotInfo` to validate credentials and auto-resolve botOpenId; stores account; starts long-connect
+3. Lark.WSClient handles the wss connection, ping/pong, URL rotation (~30 min), and automatic reconnection
+4. On graceful shutdown, `wsClient.close()` is called for each active bot
+
+## Long-connect frame protocol
+
+On connect to `wss://…` (negotiated via `POST /callback/ws/endpoint`):
+
+1. Client sends a `register` frame containing the `conn_id` received from the negotiation response
+2. Server pushes event frames typed by `type`:
+   - `1` = `frame` (event payload — `im.message.receive_v1` event data we care about)
+   - `2` = `pong` (heartbeat reply)
+   - `8` = `disconnect` (server is rotating the URL)
+3. Client periodically sends `ping` (type=0) to keep the connection alive
+
+The SDK wraps protobuf marshalling; we just register an `EventDispatcher` callback for `im.message.receive_v1` events.
+
+## Message handling flow
+
+`im.message.receive_v1` event:
+
+1. Extract sender (open_id or user_id), message content, chat_type (p2p or group), mentions array
+2. Check if bot was mentioned (p2p: always yes; group: check mentions array for bot's open_id)
+3. Drop non-user senders (bots, apps)
+4. Determine session key: p2p → `(chatId, 'dm')`; group → `(chatId, rootId ?? messageId)` to anchor each thread
+5. Parse content (text / image / file / post) — images extracted as base64 for vision, files noted as `[文件: name]` markers
+6. Download inbound images, save to workspace, generate base64 payloads
+7. Strip mention markup from text (Feishu inserts `<at user_id="ou_xxx">@bot</at>` or `@_user_123` tokens)
+8. Slash command dispatch (p2p only — group threads don't benefit from `/session new`, `/session list`, etc. since each thread is already its own session)
+9. Create or retrieve active session for this thread (with inherited access level)
+10. If session is compacting → reply "⏳ 正在整理上下文，请稍后再发消息（通常 30 秒内完成）" and skip queueing
+11. If session is busy → reply "已收到，会在当前轮结束后处理。" and enqueue
+12. Register a `FeishuResponder` event listener (once per session) that coalesces outbound text
+13. `sm.sendUserMessage(sessionId, agentInput, images?)` with channel + user + thread context
+
+## Slash commands (native Feishu /commands)
+
+Implemented via `channels/shared/commands.ts` (shared across Telegram, WeChat, Slack, Feishu):
+
+| Command | Purpose |
+|---|---|
+| `/start` | Welcome message (p2p only) |
+| `/session new` | Create a new session (p2p only) |
+| `/session list` | List recent sessions (p2p only) |
+| `/session switch <index>` | Switch active session (p2p only) |
+| `/session stop` | Abort running task |
+| `/session compact` | Compress context |
+| `/workspace info` | Show workspace; `/workspace switch <path>` changes it (full access only) |
+| `/help` | List commands |
+
+## Event coalescing (FeishuResponder)
+
+Feishu's text message limit (~5000 chars), smaller than Slack. Strategy:
+
+- Buffer streamed text until `complete` event
+- Flush fires on **any** `complete` — the responder doesn't read its `batchBoundary` flag, so a multi-round queue drain ships each merged turn as its own message instead of one blob (see [session.md](session.md#message-queue-and-drain))
+- If buffer exceeds 4500 chars, split at paragraph boundary (`\n\n`)
+- Otherwise hard-cut at 4500 chars
+- `system` and `error` events flush early so users always see something before the run ends
+- Media markers (`MEDIA:<path>`) intercepted and sent via native media upload
+- Sub-agent events dropped (visible in web UI only)
+
+## Media support
+
+**Inbound:** text, images (base64 attached to agent message), files (noted as `[文件: name]` markers), voice, video, rich posts.
+
+**Outbound routing:**
+- `.jpg/.png/.gif/.webp/.bmp` → `uploadImage` → `msg_type: 'image'`
+- `.opus` → `uploadFile(fileType: 'opus')` → `msg_type: 'audio'` (non-opus voice files sent as generic files)
+- `.mp4/.mov/.webm/.m4v/.avi` → `uploadFile(fileType: 'mp4')` → `msg_type: 'media'` (with optional cover frame)
+- everything else → `uploadFile(fileType: 'stream')` → `msg_type: 'file'`
+
+Inbound images are downloaded via `/im/v1/messages/{messageId}/resources/{imageKey}?type=image`, decrypted if needed, saved under `<workspace>/.halo/assets/feishu/inbound/<accountId>/<date>/`, and fed to vision.
+
+## Message routing (thread vs p2p)
+
+**p2p (DM):** Replies sent via `sendMessage` targeting the chat (Feishu p2p doesn't support threads).
+
+**Group (chat):** Replies sent via `replyMessage` with `reply_in_thread: true` and the inbound message id. This auto-creates a thread rooted at the inbound message if it doesn't exist, or appends to the existing thread.
+
+## Similarities vs Slack and Telegram
+
+| Aspect | Feishu | Slack | Telegram |
+|--------|--------|-------|----------|
+| **Inbound delivery** | Long-connect (wss) | Webhook + slash commands | Long-polling |
+| **Session model** | Per-thread in groups, p2p anchored | Per-thread + channels | Per-user (one active) |
+| **Mention required** | Yes in groups, no in p2p | Yes in channels, no in DMs | No (all messages routed to agent) |
+| **Cron target** | Explicit chatId only | Explicit chatId only (DM / channel / thread) | Explicit numeric chatId only |
+| **Media upload** | Separate image + file endpoints | Unified File upload API | Bot API sendPhoto / sendVideo / sendDocument |
+| **Text limit** | ~5000 chars | ~4000 chars | ~4000 chars |
+| **Thread support** | Native (root_id in messages) | Native (thread_ts replies) | N/A (group chats not supported) |
+
+## Configuration
+
+### Feishu app setup
+
+1. Go to https://open.feishu.cn/
+2. Create a new app (register as a custom app in your org, or create ISV app)
+3. Under Settings → Permissions, enable:
+   - `im:message:readonly` — receive message events
+   - `im:message` — send messages
+   - `im:resource` — upload images / files
+   - `im:chat:readonly` — search chats (for cron target picker)
+4. Under Settings → Bot, enable long-connect: "Get Card / Bot / Message Callbacks" → subscribe to `im.message.receive_v1`
+5. Copy `App ID` and `App Secret` (displayed on the settings page, or regenerate if lost)
+
+### Register to Halo
+
+```bash
+curl -X POST http://localhost:9527/api/feishu/accounts \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "appId": "cli_xxxxxxxxxxxxxxxx",
+    "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "workspacePath": "/home/user/my-workspace",
+    "accessLevel": "full",
+    "label": "My Feishu Bot"
+  }'
+```
+
+Server auto-resolves `botOpenId` from the credentials, validates them, and starts the long-connect immediately.
+
+## Scope and out-of-scope
+
+Supported: p2p text, group text with mention-required; threads; images (base64 attached to agent); audio, video, files (uploaded and referenced); slash commands (p2p only); per-session access level; media sending.
+
+Not supported: group chat without mention (we require explicit @mention for groups to avoid noise); rich message composition in responses (text only, plus media as separate messages); reactions; bot callbacks for button clicks / form submissions.
+
+## Key file references
+
+- Long-connect: `packages/server/src/channels/feishu/handler.ts:connect()` (line 241)
+- Token caching: `packages/server/src/channels/feishu/api.ts:getTenantAccessToken()` (line 39)
+- Message parsing: `packages/server/src/channels/feishu/handler.ts:parseContent()` (line 135)
+- Event dispatch: `packages/server/src/channels/feishu/handler.ts:handleInbound()` (line 301)
+- Cron dispatch: `packages/server/src/channels/feishu/cron-dispatcher.ts:dispatch()` (line 27)
+- Event coalescing: `packages/server/src/channels/feishu/event-adapter.ts:FeishuResponder` (line 24)
+- REST routes: `packages/server/src/routes/feishu.ts` (all account CRUD + search)

package/bundled-docs/design/halo-city.md

@@ -0,0 +1,112 @@
+# Halo City · 像素街区可视化
+
+Halo 服务器运行态的**街景式**像素可视化:侧视、剖面的像素城,实时天色下，
+每个 **workspace 是一栋楼**，每个 **agent session 是一只 Q 版动物市民**，爬真楼梯
+到真工位上班。点任何人打开他的**真实会话日志**（服务端流式拉取，和 admin 面板同源）。
+
+只读、零构建、零贴图素材（每个像素都是代码画的）。网络流量：一个
+`GET /api/show/state` 轮询，外加面板打开时的 `GET /api/show/session`。
+
+> 接口契约见 [dev/api.md](../dev/api.md#show-world-snapshot)（`/api/show/state`、
+> `/api/show/session` 的字段与鉴权）。本文只讲前端可视化设计。
+
+## 街区结构
+
+```
+   ☀/☾  parallax skyline · clouds · stars ──────────────────────────
+   ┌─[roof: water tank / AC / antenna / billboard]─┐
+   │ W3  desks ×3 · skill station · flavor prop    │
+   ├───────────────────────────────────────────────┤   ┌──────────┐
+   │ C   公共层: 冰箱·水吧·书架·沙发·街机/鱼缸/猫 ─[阳台]│   │ next     │
+   ├───────────────────────────────────────────────┤   │ building │
+   │ W2 / W1  work floors …                        │   │          │
+   ├───────────────────────────────────────────────┤   │          │
+   │ 大堂: 前台 · 咖啡机 · 沙发 · 大门               │   │          │
+   └─⌐stairs──────────────────────────────awning───┘   └──────────┘
+ ──┴── sidewalk · 餐车 · 野餐桌 · 篮筐 · 单车架 · 路灯 ──┴───────────
+      road        (楼距加宽:巷子就是楼下放风的地方)
+```
+
+| 看到的 | 意思 |
+|---|---|
+| 🏬 一栋楼 | 一个 workspace。**每 3 个工作层插 1 个公共层**(楼够高时),楼层数**贴合当前 root 会话数**(每层对应一个真实会话,顶上不留空层;增减都跟,但保留 1 层缓冲——会话数在两次轮询间 ±1 抖动不会让楼顶反复抽搐);砖材/霓虹竖牌/楼顶装置由 id hash 决定 |
+| 🐾 动物市民 | 一个 agent session。**制服**(衬衫+条纹)认 agent 名 → 在哪都认得出"researcher";**物种/毛色/花纹/配件**(10 物种 × 多毛色 × 眼镜/耳机/斑纹)认 session id → 同 agent 并发的 session 是穿同款衬衫的不同动物。会眨眼,说话动嘴,狗走路摇尾巴 |
+| 🪜 楼梯间 | 大楼左侧,真的逐层爬上爬下(没有传送) |
+| 💺 工作层 | 每层 3 张工位(按 agent 名固定)+ 1 个技能站 + 随机小设施(盆栽/小书架/白板/售货机);干活时屏幕滚代码 |
+| 🍵 公共层 | 冰箱(偶尔开门漏光)、水吧(水壶冒汽)、书报架、沙发,外加街机/鱼缸/猫爬架三选一;右侧伸出**阳台**(烟灰桶+盆栽)——抽烟点 |
+| 🚬 习惯 | 每个 session 由 id hash 派生 **3 个固定偏好**(抽烟/咖啡/泡茶/翻冰箱/看书/街机/看鱼/撸猫/打电话/下楼遛弯/沙发),摸鱼时偏好权重 ~4×——"这个会话就爱在阳台抽烟"是稳定人设,不是随机骰子 |
+| 🧭 就近原则 | 市民**生在自己的归属层**(自己的工位层;子代理用父代理的工位层),不再从大堂爬上来。休息活动以**归属层**为锚点就近找公共层(每 3 层就有),不会为了倒杯茶爬通天,**也不会随时间往低层漂**——12 楼的人永远回 F11 休息,不会一路沉到大堂。高层会话不下大堂:`下楼遛弯` 只有 F5 及以下才真下街,F6+ 改在就近休息层放风 |
+| 💡 灯光 | 有人在的楼层灯亮(running 或 idle 都算——摸鱼也开灯),只有彻底 stopped 的层才熄;天黑后街灯/霓虹/远景窗火全亮 |
+| ↳ 小一号 | 子代理:生在并聚在父代理那层桌边,不占工位 |
+
+进出有戏:新会话直接出现在自己的工位层(从本层楼梯口走到工位,不再从街上爬通天);结束的走出门沿街远去淡出。
+
+## 点击 = 真实数据
+
+点任何市民,面板里是**真东西**:
+
+- **会话日志**:`/api/show/session` 拉来的最近 40 条消息流——用户输入、助手回复、
+  工具调用(带耗时),像 `tail -f` 一样贴底自动滚,面板开着每 6s 只刷日志框
+  (面板本体原地补丁,不再整页重建闪烁)
+- **上下文仪表**:`134k / 200k (67%)` —— 分母是该会话的**真实** `maxContextTokens`
+- **委派链**:父/子会话可点击跳转,每行带 token 数和消息数
+- **点楼层**:该层的会话委派关系树(缩进、可点跳转)——工作层看"谁在这层干活、
+  带着哪些子代理",公共层看"谁在摸鱼"
+- 点大楼:全员 roster + token 合计;点技能站:谁在用
+
+## 街景与载具
+
+街区不只是静态背景,会按**真实时间**自己演(`traffic.js`):
+
+| 事件 | 节奏 | 说明 |
+|---|---|---|
+| 🛸 UFO | 每天 0:00 | 午夜从街头飘过 |
+| ✈️ 飞机 | 每半点(`:30`) | 高空掠过,方向随机 |
+| 🚌 巴士 | 每 3 分钟 | 进站、开门、接走在站台等车的人,再开走 |
+| 🚗 进出场载具 | 跟随会话 | 新会话打车/电动车/跑车送到门口;结束的会话走到站台**体面地等车离场**,不再凭空消失 |
+| 🏗️ 盖楼 / 拆楼 | 跟随楼层增减 | 长楼层有施工动效;拆楼留 ~30s 缓冲(先让人撤离再慢慢消散,不穿帮) |
+
+> 定时全用真实 `Date.now()` 计算(`?hour=` 只冻结天色、不冻结这些事件)。
+
+## 交互与显示
+
+操作:滚轮缩放(九档 `0.3×–6×`)· 拖拽平移 · 点击查看 · **双击**在 1×/3× 间快速切 ·
+**F** 全街区 · **H**(或点左上角 logo)切纯净模式 · **Esc** 逐层退(先关面板,再退纯净)·
+右上角 **中/EN** 一键切语言。闲置 10s 后镜头沿街慢慢巡游。
+
+- **纯净模式(zen)**:淡出所有 HUD(统计/动态/图例/缩放条/面板),只留街景,适合大屏常驻展示
+- **多语言(i18n)**:中文 / English 一键切;`?lang=en`/`?lang=zh` 直达,选择存 localStorage。
+  运行时文案走 `t()`,静态 DOM 走 `data-i18n` 属性填充
+
+## 调试参数
+
+- `?hour=22.5` — 把昼夜定格在某个时刻(支持小数;只冻结天色,不冻结街景事件)
+- `?lang=en` / `?lang=zh` — 指定语言
+- kiosk 直链:`/#api=…&token=…`(token 立即从地址栏抹掉)
+
+## 文件结构
+
+```
+js/
+  main.js      入口:setup → world → 输入/轮询
+  api.js       state 轮询 + session 详情客户端(content-type 防呆)
+  world.js     快照 → 城市/市民 diff,渲染循环,拾取
+  city.js      街区:楼(材质/楼层/霓虹/楼顶)、大堂、街道、视差天际线
+  citizen.js   市民:楼层×楼梯 2D 路径规划 + 行为 FSM
+  people.js    人物绘制:动物物种×毛色×配件池,眨眼/口型
+  props.js     家具:工位/技能站/咖啡机/街机/鱼缸/猫爬架/窗/灯
+  palette.js   EDG32 + 建筑材质 ramp + 关键帧天空
+  camera.js    整数吸附镜头(九档缩放 0.3×–6×)
+  inspector.js 面板 + 实时会话日志查看器
+  ticker.js    街区动态 feed
+  traffic.js   街景事件:UFO(0点)/飞机(每半点)/进出场载具/每 3 分钟 bus/盖楼·拆楼
+  i18n.js      多语言词典(zh/en)+ 运行时 t() + 静态 data-i18n 填充
+  util.js      hash/PRNG/格式化
+```
+
+## 服务端配套
+
+- `GET /api/show/session?ws=&id=` — 只读会话详情:裁剪后的消息日志 + 真实
+  token 上限。鉴权同 `/api/show/state`(x-token;非 full 只能看自己 workspace)
+- `/api/show/state` — 无活跃 UIState 的会话(idle/stopped/重启后)token
+  从会话文件头读取(mtime 缓存,不随轮询刷盘),不显示 0;含 `messageCount` 字段