dsh-lark-bot 0.6.0 → 0.8.0

package/README.md

@@ -28,107 +28,53 @@
 
 ## 快速开始 | Quick Start（普通用户先看这里 | for end users）
 
-### 1. 安装 | Install
+### 1. 安装（唯一路径）| Install (the only path)
 
-两个包名内容完全一致，任选一个即可：
+本项目以 **dsh 标准 profile bundle** 交付：一行命令把它装进一个 dsh profile，dsh 启动时以
+标准插件方式加载桥接引擎（`dsh.bundle.patch` 已声明，`dsh plugin add` 可直接安装）。
 
-Both package names ship identical content — pick either one:
+This project ships as a **standard dsh profile bundle**: one command installs it into a dsh
+profile, and dsh loads the bridge engine as a standard plugin on boot (the package declares
+`dsh.bundle.patch`, so `dsh plugin add` works directly).
 
 ```bash
-# 推荐 | Recommended
-npm install -g dsh-lark-bot
-
-# 或飞书命名版本 | or the Feishu-named edition
-npm install -g dsh-feishu-bot
+# 唯一安装命令（无需先全局安装任何东西）| the only install command (no prior global install)
+npx dsh-lark-bot@latest setup --profile dsh-lark
 ```
 
-安装完成后，对应命令分别为 `dsh-lark-bot` 和 `dsh-feishu-bot`。
-
-After installation, the commands are `dsh-lark-bot` and `dsh-feishu-bot` respectively.
+`setup` 会自动完成：发现本机 dsh → 预批准 pnpm 构建策略 → 执行标准的
+`dsh plugin --profile dsh-lark add dsh-lark-bot`。
 
-也可以作为 **dsh 标准 profile bundle** 安装到任意 dsh profile（`dsh.bundle.patch` 已声明）：
+`setup` automatically: locates your dsh install → pre-approves pnpm's build policy → runs the
+standard `dsh plugin --profile dsh-lark add dsh-lark-bot`.
 
-It is also installable as a **standard dsh profile bundle** (the package declares
-`dsh.bundle.patch`):
+### 2. 启动并扫码绑定 | Start and bind with one scan
 
 ```bash
-dsh plugin --profile <name> add dsh-lark-bot
+dsh --profile dsh-lark
 ```
 
-安装后 profile 启动时会装配 `dsh-lark-bot/plugin`（在 `ctx.larkBridge` 暴露 bridge 后台服务的
-status / start / restart / stop，不阻塞 profile 启动；`DSH_LARK_AUTOSTART=1` 可在 profile
-启动时自动拉起 bridge）。SDK / ACP runtime 还会自动装配 `lark_notify` 工具（见下文）。
-
-The profile then mounts `dsh-lark-bot/plugin` on boot — it exposes `ctx.larkBridge`
-(status / start / restart / stop of the standalone bridge service) without blocking boot; set
-`DSH_LARK_AUTOSTART=1` to start the bridge when the profile boots. The SDK / ACP runtimes also
-auto-mount the `lark_notify` tool (see below).
-
-> pnpm ≥ 10 默认拒绝依赖构建脚本：若 `dsh plugin add` 报 `ERR_PNPM_IGNORED_BUILDS`
-> （protobufjs 等），按官方指引在 profile 目录的 `pnpm-workspace.yaml` 加
-> `allowBuilds:\n  protobufjs: true` 后重试（与官方 `dsh-lark-channel` 相同的处理方式）。
-
-> pnpm ≥ 10 blocks dependency build scripts by default: if `dsh plugin add` reports
-> `ERR_PNPM_IGNORED_BUILDS` (e.g. protobufjs), add `allowBuilds:\n  protobufjs: true` to the
-> profile's `pnpm-workspace.yaml` and retry — the same handling as the official
-> `dsh-lark-channel`.
+首次启动会在终端打印二维码：用飞书 / Lark App 扫码创建或选择 PersonalAgent 应用，绑定后
+dsh-lark-bot 的桥接引擎即在 dsh 进程内运行（飞书通道、会话/工作区、卡片、通知回调），
+私聊直接发消息，群聊 / 话题里 `@bot`。常驻与守护由 dsh 自己负责。
 
-### 2. 启动后台服务并绑定飞书 | Start the background service and bind Feishu
+On first boot the terminal prints a QR code: scan it with the Feishu / Lark app to create or
+choose a PersonalAgent app. After binding, the bridge engine runs **inside the dsh process**
+(Feishu channel, sessions/workspaces, cards, notify callback); message it directly in private
+chat, or use `@bot` in groups/topics. dsh owns the daemon lifecycle.
 
-```bash
-dsh-lark-bot start
-```
+已有 PersonalAgent 应用时可在 profile 环境变量中直接提供凭据跳过扫码（见「配置」）：
 
-或： | or:
+With an existing PersonalAgent app, provide credentials via profile env to skip the QR step
+(see Configuration):
 
 ```bash
-dsh-feishu-bot start
+DSH_LARK_APP_ID=cli_xxx DSH_LARK_APP_SECRET=<secret> DSH_LARK_TENANT=feishu \
+  dsh --profile dsh-lark
 ```
 
-`start` 会自动在本机安装一个**后台服务**：加入系统开机自启列表，并在进程退出、崩溃或出错时自动重启。首次启动会：
-
-`start` automatically installs a **background service** locally: it joins the OS autostart
-list and restarts automatically whenever the process exits, crashes or errors. On first launch:
-
-1. 在终端显示二维码。
-2. 用飞书 / Lark App 扫码。
-3. 选择或创建 PersonalAgent 应用。
-4. 绑定成功后，bot 会向你的私聊发送欢迎卡片。
-5. 私聊直接发消息；群聊或话题里 `@bot`。
-
-1. A QR code is shown in the terminal.
-2. Scan it with the Feishu / Lark app.
-3. Choose or create a PersonalAgent app.
-4. Once bound, the bot sends a welcome card to your private chat.
-5. Message it directly in private chat; use `@bot` in group chats or topics.
-
-绑定完成后 bot 转入后台运行，终端可以随时关闭。
-
-After binding, the bot runs in the background; you can close the terminal anytime.
-
-如果你已经有 PersonalAgent 应用，也可以跳过扫码：
-
-If you already have a PersonalAgent app, you can skip the QR step:
-
-```bash
-dsh-lark-bot start \
-  --app-id cli_xxx \
-  --app-secret <secret> \
-  --tenant feishu
-```
-
-### 3. 服务管理命令 | Service management commands
-
-| 命令 Command | 作用 Description |
-| :--- | :--- |
-| `dsh-lark-bot start` | 安装后台服务、加入开机自启并启动（首次运行会先扫码绑定）<br>Install the background service, enable autostart and start it (first run prompts QR binding) |
-| `dsh-lark-bot status` | 查看服务状态（退出码 0=运行中，1=未运行）<br>Show service status (exit code 0=running, 1=not running) |
-| `dsh-lark-bot restart` | 重启后台服务（保留开机自启）<br>Restart the background service (keeps autostart) |
-| `dsh-lark-bot stop` | 停止后台服务并移出开机自启<br>Stop the background service and remove autostart |
-
-后台服务的运行日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`。
-
-Background service logs are written to `~/.dsh-lark/profiles/<profile>/logs/bot.log`.
+> 卸载：`dsh plugin --profile dsh-lark remove dsh-lark-bot`。
+> Uninstall: `dsh plugin --profile dsh-lark remove dsh-lark-bot`.
 
 ### 4. 基本使用 | Basic usage
 
@@ -207,6 +153,47 @@ runtime profiles): after a task finishes it can push messages to other groups/to
 members. The bridge listens on 127.0.0.1 with a random per-boot token — nothing is exposed to the
 public network.
 
+**安全网守护（Safe-mode guardian）**：可选安装一个独立于 dsh 进程、系统级常驻的最小守护进程
+（Linux systemd user unit / macOS LaunchAgent / Windows 启动项）。dsh 正常运行时守护保持静默；
+一旦 dsh 进程下线或无法 boot（例如某个第三方插件破坏了整个 profile 组合），守护自动接管飞书
+通道，用户无需接触命令行即可发送控制信号自救：
+
+- `/safemode`：进入**仅核心安全模式**——守护创建 `~/.dsh/profiles/<profile>-safe`（仅
+  `dsh-base` + `dsh-headless` 两个官方核心 bundle，**不加载任何第三方插件**），后续消息经
+  守护转发给该核心 dsh 逐条对话，配合代码执行能力定位 / 修复 / 禁用损坏插件；
+- `/safemode plugins`：列出故障 profile 已安装的插件清单（自愈诊断）；
+- `/safemode status`：查看守护 / dsh / 安全模式状态；
+- `/safemode exit`：退出安全模式，守护重启完整 profile 并把飞书通道交还给正常形态；
+
+全程不需要命令行；dsh 恢复后守护自动断开并回归静默。安装：
+
+```bash
+npx dsh-lark-bot@latest setup --profile dsh-lark --guardian
+# 或已安装后单独安装：dsh-lark-bot guardian install
+```
+
+**Safety-net guardian**: optionally install a minimal system-level resident process that is
+independent of the dsh process. While dsh runs, the guardian stays silent; once dsh goes down or
+fails to boot (e.g. a third-party plugin breaks the whole profile composition), the guardian
+takes over the Feishu channel so you can self-heal without touching the command line:
+
+- `/safemode`: enter **core-only safe mode** — the guardian provisions
+  `~/.dsh/profiles/<profile>-safe` with only the two official core bundles (`dsh-base` +
+  `dsh-headless`, **no third-party plugins**) and proxies a restricted conversation to that core
+  dsh so you can locate / fix / disable the offending plugin;
+- `/safemode plugins`: list the plugins installed into the broken profile;
+- `/safemode status`: show guardian / dsh / safe-mode state;
+- `/safemode exit`: leave safe mode — the guardian relaunches the full profile and hands the
+  Feishu channel back;
+
+No command line is needed for the whole rescue flow; once dsh is back, the guardian releases the
+channel automatically. Install:
+
+```bash
+npx dsh-lark-bot@latest setup --profile dsh-lark --guardian
+# or later: dsh-lark-bot guardian install
+```
+
 ### 模型 / Provider / 凭据管理 | Models / Providers / Credentials
 
 模型与 provider 的配置以 dsh 官方方式持久化（与 dsh Web **Settings → Models** 页面完全相同的
@@ -241,14 +228,56 @@ Security note: typing a key in a Feishu conversation exposes it to everyone who
 chat; prefer private chats, `--api-key-env` references to existing environment variables, or the
 dsh Web UI. The bot never echoes key values in any reply.
 
-### 5. 卸载 | Uninstall
+## 安装与卸载 | Install & Uninstall
+
+### 安装 | Install
+
+唯一安装方式（标准 dsh profile bundle）：
+
+The only install path (a standard dsh profile bundle):
 
 ```bash
-dsh-lark-bot stop
-npm uninstall -g dsh-lark-bot
-rm -rf ~/.dsh-lark
+npx dsh-lark-bot@latest setup --profile dsh-lark
 ```
 
+`setup` 自动完成：定位本机 dsh → 预批准 pnpm 构建策略（protobufjs）→ 执行标准
+`dsh plugin --profile dsh-lark add dsh-lark-bot`。加 `--guardian` 会同时安装「安全网守护」
+（见「安全网守护」一节）。已安装时重复执行即升级到最新版。
+
+`setup` locates your dsh, pre-approves pnpm's build policy (protobufjs) and runs the standard
+`dsh plugin --profile dsh-lark add dsh-lark-bot`. Adding `--guardian` also installs the
+safety-net guardian (see "Safety-net guardian" above). Re-running it upgrades to the latest version.
+
+### 升级 | Upgrade
+
+- 插件本体：重跑 `setup`（或 `dsh plugin --profile <name> add dsh-lark-bot`）拉取 npm 最新版。
+- CLI 工具（可选）：`npm i -g dsh-lark-bot@latest`；使用 `npx` 时无需全局安装。
+- 升级后重启 profile：`dsh --profile dsh-lark`。
+
+- Plugin: re-run `setup` (or `dsh plugin --profile <name> add dsh-lark-bot`) to pull the latest
+  npm release.
+- CLI tool (optional): `npm i -g dsh-lark-bot@latest`; not needed when using `npx`.
+- Restart the profile after upgrading: `dsh --profile dsh-lark`.
+
+### 禁用 | Disable
+
+保持插件加载但停止桥接引擎：启动 profile 前导出 `DSH_LARK_DISABLED=1`。彻底移除见下节。
+
+Keep the plugin loaded but stop the bridge engine: export `DSH_LARK_DISABLED=1` before booting
+the profile. For full removal see the next subsection.
+
+### 卸载 | Uninstall
+
+```bash
+dsh plugin --profile dsh-lark remove dsh-lark-bot
+```
+
+卸载后 profile 不再加载本插件。本地状态（配置 / 会话 / 归档 / 角色）保留在 `~/.dsh-lark`；
+如需清除，先备份再删除该目录。
+
+Removal unloads the plugin from the profile. Local state (config / sessions / archives / roles)
+stays in `~/.dsh-lark`; back it up before deleting it.
+
 更详细的安装、状态目录、日志和排障说明见 [`docs/QUICK_START.md`](docs/QUICK_START.md)。
 
 See [`docs/QUICK_START.md`](docs/QUICK_START.md) for installation details, state directories,
@@ -266,19 +295,29 @@ logs and troubleshooting.
 
 **dsh-lark-bot** is a lightweight bridge that connects your local DeepSeek Harness (`dsh`) into Feishu / Lark, recreating the beloved OpenCode / MiMoCode Telegram-bot experience — chat with your coding agent, receive streaming cards, review diffs — and adds **full project workspace management** on top.
 
+**适合谁 / Who it is for**：在飞书 / Lark（私聊、群聊、话题）里指挥本机 dsh coding agent 的
+开发者与团队，尤其是需要多项目隔离、角色分工、并行任务与会话归档的协作场景。
+
+Developers and teams who drive a local dsh coding agent from Feishu / Lark (DMs, groups,
+topics) — especially those needing multi-project isolation, role-based collaboration, parallel
+tasks and session archival.
+
 ## 目标 | Goals
 
-- **一条命令启动**：clone 后一键安装运行，已发布到 npm，`npm i -g dsh-lark-bot && dsh-lark-bot start` 即可拉起后台服务。
+- **一条命令安装部署**：`npx dsh-lark-bot@latest setup --profile dsh-lark` 装进 dsh profile，
+  随后 `dsh --profile dsh-lark` 启动并扫码，桥接引擎作为标准插件在 dsh 进程内运行。
 - **飞书原生体验**：流式卡片、交互按钮、图片 / 文件，全程双语（文档评论为规划中能力）。
 - **完整工作区管理**：多项目隔离、git worktree、项目级规则注入、上下文持久化。
 
-- **One-command start**: clone and run in one step, published to npm — `npm i -g dsh-lark-bot && dsh-lark-bot start`.
+- **One-command install & deploy**: `npx dsh-lark-bot@latest setup --profile dsh-lark`, then
+  `dsh --profile dsh-lark` and scan once — the bridge engine runs as a standard plugin inside
+  the dsh process.
 - **Native Feishu experience**: streaming cards, interactive buttons, images / files, doc comments.
 - **Full workspace management**: multi-project isolation, git worktrees, per-project rules, persistent context.
 
 ## 兼容性 | Compatibility
 
-- **DeepSeek Harness（`dsh`）**：已验证 **dsh 0.1.0-rc.6**（2026-08-14：SDK JSON-RPC / ACP runtime 握手 +
+- **DeepSeek Harness（`dsh`）**：已验证 **dsh 0.1.0-rc.6**（最后验证 2026-08-15：SDK JSON-RPC / ACP runtime 握手 +
   真实任务流式验证），通过官方 `@deepseek-ai/dsh-sdk-client` / `@deepseek-ai/dsh-acp` 接入；
   具体锁定版本、升级政策与自动化探测见 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md)，
   adapter 接入细节见 [`docs/adapter-notes.md`](docs/adapter-notes.md)。
@@ -288,7 +327,7 @@ logs and troubleshooting.
   token 级流式事件）；`DSH_LARK_ADAPTER=acp` 切到官方 **ACP server**（审批卡）；`headless` 保留旧版
   子进程 fallback。首次启动自动在 `~/.dsh/profiles/dsh-lark`（或 `dsh-lark-acp`）创建 runtime profile。
 
-- **DeepSeek Harness (`dsh`)**: verified against **dsh 0.1.0-rc.6** (2026-08-14: SDK JSON-RPC / ACP
+- **DeepSeek Harness (`dsh`)**: verified against **dsh 0.1.0-rc.6** (last verified 2026-08-15: SDK JSON-RPC / ACP
   runtime handshake + real streaming task verification), connected through the official
   `@deepseek-ai/dsh-sdk-client` / `@deepseek-ai/dsh-acp`; see
   [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) for pinned versions, the upgrade policy and
@@ -302,17 +341,46 @@ logs and troubleshooting.
   fallback. On first start the bot creates the runtime profile at
   `~/.dsh/profiles/dsh-lark` (or `dsh-lark-acp`).
 
+## 已知限制 | Known limitations
+
+- ACP 模式会话每次全新（上游限制，无续跑）；SDK 协议暂无 mid-turn cancel，`/stop` 会关闭
+  对应 runtime 并自动重建。
+- 桥接引擎作为 dsh 插件在 dsh 进程内运行，agent 执行使用官方 dsh SDK runtime 子进程
+  （嵌套 runtime 是有意取舍，用于按工作区隔离的 runtime 池与 scope 内并行 run）。
+  唯一的进程级例外是可选安装的「安全网守护」——它独立于 dsh / Cordis 常驻，仅在 dsh
+  下线后接管飞书通道，正常运行时保持静默。
+- 飞书文档评论、富文本回复为规划中能力，尚未实现。
+- pnpm ≥ 10 的构建脚本策略由 `setup` 自动处理；手动 `dsh plugin add` 时若报
+  `ERR_PNPM_IGNORED_BUILDS`，按官方指引在 profile 的 `pnpm-workspace.yaml` 加
+  `allowBuilds: { protobufjs: true }` 后重试。
+
+- ACP sessions are always fresh (an upstream limit); the SDK protocol has no mid-turn cancel,
+  so `/stop` closes and recreates the runtime.
+- The engine runs in-process as a dsh plugin; agent execution uses the official dsh SDK runtime
+  subprocess — a deliberate nested-runtime design for per-workspace runtime pools and parallel
+  runs. The one process-level exception is the optional safety-net guardian — a minimal
+  resident process independent of dsh / Cordis that only takes over the Feishu channel after
+  dsh goes down and stays silent otherwise.
+- Feishu doc comments and rich-text replies are planned, not yet implemented.
+- pnpm ≥ 10 build policy is handled by `setup`; when installing manually and
+  `ERR_PNPM_IGNORED_BUILDS` appears, add `allowBuilds: { protobufjs: true }` to the profile's
+  `pnpm-workspace.yaml` and retry.
+
 ## 配置 | Configuration
 
 - 本地配置：`~/.dsh-lark/config.json`
 - 状态根目录可用 `DSH_LARK_HOME` 覆盖
 - 环境变量统一使用 `DSH_LARK_*` 前缀
 - 模板见 [`.env.example`](.env.example)
+- 敏感项：`DSH_LARK_APP_SECRET`、`DEEPSEEK_API_KEY` 等凭据只保存在本机配置 / 环境中，日志与
+  卡片自动脱敏，仓库只提交 `.env.example` 模板。
 
 - Local config: `~/.dsh-lark/config.json`
 - The state root can be overridden with `DSH_LARK_HOME`
 - Environment variables use the `DSH_LARK_*` prefix
 - Template: [`.env.example`](.env.example)
+- Sensitive values: credentials (`DSH_LARK_APP_SECRET`, `DEEPSEEK_API_KEY`, …) stay in local
+  config/env only; logs and cards are redacted; only `.env.example` is committed.
 
 会话运行在 Git 仓库中时，会自动在 `~/.dsh-lark/profiles/<profile>/worktrees/<scope>/` 创建隔离 worktree，并复制项目级 `AGENTS.md`。
 
@@ -353,6 +421,13 @@ Core environment variables:
 | `DSH_LARK_RETENTION_MSGS` | `40` | 每个 scope 保留的消息条数（0=全部保留）<br>Messages kept per scope (0 keeps everything) |
 | `DSH_LARK_ARCHIVE_MAX` | `50` | 每个 scope 最多保留的归档数（0=不清理）<br>Max archives kept per scope (0 disables pruning) |
 | `DSH_LARK_ARCHIVE_MAX_AGE_DAYS` | `90` | 归档最大保留天数（0=不清理）<br>Max archive age in days (0 disables pruning) |
+| `DSH_LARK_HEARTBEAT_MS` | `5000` | 桥接引擎心跳写入间隔（守护存活信号）<br>Bridge heartbeat write interval (guardian liveness signal) |
+| `DSH_LARK_GUARDIAN_DISABLED` | `false` | `1` 时安全网守护进程保持停止<br>`1` keeps the safety-net guardian stopped |
+| `DSH_LARK_GUARDIAN_PROFILE` | `dsh-lark` | 守护监视 / 重启的 dsh profile（首次安装时写入状态）<br>dsh profile the guardian watches / relaunches (persisted on install) |
+| `DSH_LARK_GUARDIAN_BRIDGE_PROFILE` | `default` | 提供飞书凭据与白名单的桥接状态 profile<br>Bridge state profile providing Feishu credentials / allowlist |
+| `DSH_LARK_GUARDIAN_POLL_MS` | `2000` | 守护看门狗轮询间隔<br>Guardian watchdog poll interval |
+| `DSH_LARK_GUARDIAN_STALE_MS` | `15000` | 心跳超时阈值，超过且无 dsh 进程则接管飞书通道<br>Heartbeat staleness threshold before channel takeover |
+| `DSH_LARK_GUARDIAN_ENGINE_DEAD_MS` | `120000` | dsh 进程存活但心跳持续超时该时长，判定桥接引擎已死并接管<br>Live dsh process with heartbeat stale this long is treated as engine-dead (takeover) |
 
 启动时会自动查找本机常见的 `@deepseek-ai/dsh` 安装位置。只有自动发现失败或需要指定特殊 profile 时，才需要设置这两个变量。
 
@@ -374,6 +449,10 @@ This tool runs **locally**; before installing, be aware that it accesses:
 - **dsh 配置**：`/model` `/providers` `/provider` `/key` 命令按 dsh 官方存储协议读写
   `~/.dsh/settings.yaml` 与 `~/.dsh/.credentials.yaml`（仅管理员可写；settings 只存 `apiKeyEnv`
   引用，凭据文件权限 0600、目录 0700，字面密钥不进入 settings 或聊天记录）。
+- **安全网守护（可选）**：安装后为系统级常驻进程，读取 `~/.dsh-lark/config.json` 中的飞书
+  凭据；dsh 下线时接管同一 bot 的飞书长连接并扫描本机进程（仅 `ps` 命令行，不读内存）；
+  `/safemode` 时在 `~/.dsh/profiles/<profile>-safe` 创建仅核心的 dsh profile 并逐条执行
+  `dsh --profile <safe> "<prompt>"` 子进程。
 
 - **Feishu credentials**: the PersonalAgent app `app_id` / `app_secret`, stored in plaintext at
   `~/.dsh-lark/config.json` (file mode 600).
@@ -389,6 +468,11 @@ This tool runs **locally**; before installing, be aware that it accesses:
   `~/.dsh/settings.yaml` and `~/.dsh/.credentials.yaml` using the official dsh storage protocol
   (admin-only writes; settings keep only `apiKeyEnv` references; credentials file mode 0600,
   directory 0700; literal keys never enter settings or chat history).
+- **Safety-net guardian (optional)**: when installed, a system-level resident process reads the
+  Feishu credentials from `~/.dsh-lark/config.json`; it takes over the same bot's Feishu long
+  connection only after dsh goes down and scans local processes (command lines via `ps` only, no
+  memory access). On `/safemode` it provisions a core-only dsh profile at
+  `~/.dsh/profiles/<profile>-safe` and runs `dsh --profile <safe> "<prompt>"` per message.
 
 所有数据仅在本机与飞书、DeepSeek 之间流转，不收集、不上传任何遥测。密钥不会提交进仓库（见 `.gitignore`）。
 
@@ -420,11 +504,19 @@ Common issues:
   is reachable; with an existing App ID/Secret you can skip scanning via `--app-id` /
   `--app-secret`.
 
-以后台服务方式运行时，日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`（JSON Lines，
-stdout 与 stderr 合并）；当前进程的 stderr 仍为 JSON Lines。
+桥接引擎日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`（JSON Lines）；dsh 宿主日志走
+dsh 自己的日志体系。
+
+The bridge engine logs to `~/.dsh-lark/profiles/<profile>/logs/bot.log` (JSON Lines); the dsh
+host uses its own logging.
 
-When running as a background service, logs go to `~/.dsh-lark/profiles/<profile>/logs/bot.log`
-(JSON Lines, stdout and stderr merged); the current process's stderr is still JSON Lines.
+**回滚 / Rollback**：`dsh plugin --profile dsh-lark remove dsh-lark-bot` 后重装固定版本即可
+（如 `dsh plugin --profile dsh-lark add dsh-lark-bot@0.6.0`）；`~/.dsh-lark` 状态独立于插件
+本体，升级 / 回滚不会丢失配置与会话。
+
+To roll back: remove the plugin and reinstall a pinned version (e.g.
+`dsh plugin --profile dsh-lark add dsh-lark-bot@0.6.0`); `~/.dsh-lark` state is independent of
+the package, so config and sessions survive upgrades / rollbacks.
 
 ## 开发 | Development
 
@@ -447,6 +539,13 @@ module contracts, and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the arc
 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) for the compatibility matrix, upgrade policy
 and automation.
 
+**贡献 / Contributing**：欢迎 Issue 与 PR。开发流程见 [`AGENTS.md`](AGENTS.md)（必读文档、
+提交规范与推送边界），生态交付标准见 [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md)。
+
+Contributions are welcome via Issues and PRs; see [`AGENTS.md`](AGENTS.md) for the workflow
+(required reading, commit conventions, push policy) and [`docs/ECOSYSTEM.md`](docs/ECOSYSTEM.md)
+for ecosystem delivery standards.
+
 发布双包（`dsh-lark-bot` 与 `dsh-feishu-bot` 共享同一份 dist / 版本 / 依赖）：
 
 Publishing both packages (`dsh-lark-bot` and `dsh-feishu-bot` share the same dist / version /
@@ -469,14 +568,31 @@ create a Release automatically.
 The same dist is also published to GitHub Packages as `@plutokeating/dsh-lark-bot` and
 `@plutokeating/dsh-feishu-bot`, viewable on the GitHub Packages page.
 
+## 维护与支持 | Maintenance
+
+- 状态：**活跃维护（Active）**。主维护者：**PlutoKeating**。
+- 问题 / 建议：优先在 GitHub Issues 提交；安全漏洞请走 [`SECURITY.md`](SECURITY.md) 的私下报告渠道。
+
+- Status: **active**. Primary maintainer: **PlutoKeating**.
+- Bugs / feature requests: GitHub Issues; security issues via the private channel in
+  [`SECURITY.md`](SECURITY.md).
+
+社区收录情况见下节「社区收录情况 | Community Listings」。
+
+See "Community Listings" in the next section for ecosystem registration status.
+
 ## 许可与安全 | License & Security
 
 - **许可证**：GNU Affero General Public License v3.0（见 `LICENSE`）。
+- **版权归属**：源码版权归项目维护者所有，按 AGPL-3.0 授权；「DeepSeek」「飞书 / Lark」等
+  商标归各自权利人所有。
 - **安全报告**：如发现安全漏洞，请通过 GitHub Security Advisory 私下报告，勿公开 issue。
 - **安全模型**：默认拒绝、密钥脱敏、路径 containment、SSRF 防护、过期事件拒绝与交互工具
   默认禁用——详见 [`SECURITY.md`](SECURITY.md)。
 
 - **License**: GNU Affero General Public License v3.0 (see `LICENSE`).
+- **Copyright**: source is owned by the maintainers and licensed under AGPL-3.0; "DeepSeek" and
+  "Feishu / Lark" trademarks belong to their respective owners.
 - **Security reports**: report vulnerabilities privately via GitHub Security Advisory; do not
   open a public issue.
 - **Security model**: default-deny, secret redaction, path containment, SSRF protection, stale
@@ -513,8 +629,17 @@ The same dist is also published to GitHub Packages as `@plutokeating/dsh-lark-bo
 
 核心思路：**飞书通道与 agent 后端解耦**。桥接层复刻 `lark-channel-bridge` 的成熟做法（WebSocket 长连接 + 流式卡片 + 会话路由），agent 后端通过 adapter 抽象，默认挂接官方 DeepSeek Harness SDK（`DSH_LARK_ADAPTER=sdk`），可选 ACP 审批模式与 legacy headless。
 
+可选「安全网守护」（`src/guardian/`）独立于 dsh 进程常驻：dsh 在线时静默，下线时接管飞书
+通道接收 `/safemode` 控制信号，以仅核心 profile（`dsh-base` + `dsh-headless`）拉起受限对话
+用于自愈，`/safemode exit` 重启完整 profile 并交还通道。
+
 The core idea: **decouple the Feishu channel from the agent backend**. The bridge layer follows the battle-tested `lark-channel-bridge` approach (WebSocket long-connection + streaming cards + session routing); the agent backend is abstracted behind an adapter, defaulting to the official DeepSeek Harness SDK (`DSH_LARK_ADAPTER=sdk`), with an optional ACP approval mode and the legacy headless fallback.
 
+The optional safety-net guardian (`src/guardian/`) runs as a separate resident process: silent
+while dsh is up, it takes over the Feishu channel when dsh goes down, accepts `/safemode` control
+signals, runs a restricted core-only conversation (`dsh-base` + `dsh-headless`) for self-healing,
+and relaunches the full profile on `/safemode exit`.
+
 ## 目录结构 | Directory Structure
 
 | 目录 Dir | 职责 Responsibility |
@@ -527,12 +652,12 @@ The core idea: **decouple the Feishu channel from the agent backend**. The bridg
 | `src/card/` | 流式卡片状态与渲染<br>Streaming card state & rendering |
 | `src/bot/` | 运行注册、消息排队、审批/问答注册表<br>Run registry, queueing, approval/question registries |
 | `src/commands/` | 斜杠命令（/cd /ws /new …）<br>Slash commands |
-| `src/cli/` | CLI 入口与 start / status / restart / stop / doctor 命令<br>CLI entry & service commands |
+| `src/cli/` | CLI 入口：`setup`（唯一安装命令）/ `doctor`（诊断）/ 隐藏 `run`<br>CLI entry: setup / doctor / hidden run |
+| `src/guardian/` | 安全网守护：心跳、进程观察、仅核心安全 profile、接管状态机、系统服务安装<br>Safety-net guardian: heartbeat, process watch, core-only safe profile, takeover state machine, service install |
 | `src/config/` | profile / 配置 / 访问白名单 / dsh 配置管理<br>Profile, config, access & dsh config management |
 | `src/core/` | 结构化日志<br>Structured logging |
 | `src/media/` | 附件下载与文本注入<br>Attachment download & text injection |
 | `src/platform/` | 跨平台原子写入<br>Cross-platform atomic writes |
-| `src/service/` | 后台服务管理（systemd / launchd / 计划任务 / 便携 supervisor）<br>Background service management |
 | `docs/` | 架构、路线图等文档<br>Architecture, roadmap & docs |
 | `reference/` | 参考研究用的克隆仓库（不提交）<br>Cloned reference repos (not committed) |
 
@@ -548,6 +673,29 @@ The core idea: **decouple the Feishu channel from the agent backend**. The bridg
 | [`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness) | DeepSeek Harness（`dsh`），agent 后端<br>DeepSeek Harness (`dsh`), the agent backend |
 | [`grinev/opencode-telegram-bot`](https://github.com/grinev/opencode-telegram-bot) | OpenCode 的 Telegram 手机端，另一参照<br>Telegram mobile client for OpenCode; another reference |
 
+## 社区收录情况 | Community Listings
+
+> 本项目的社区收录 / 推荐状态，随提交的更新请求持续维护。截至 v0.8.0：
+> Community listing & recommendation status, kept current as update requests land. As of v0.8.0:
+
+| 平台 Platform | 状态 Status | 说明 Notes |
+| :--- | :--- | :--- |
+| [awesome-dsh-plugins](https://github.com/AdamPlatin123/awesome-dsh-plugins) | ✅ 已收录 · 运行级可用<br>Listed · runtime-verified | 社区榜单标注 `✅ 运行级可用`，2026-08-14 agent 实测通过；v0.8.0 更新已提交（见下文链接）<br>Shown as `✅ 运行级可用` in the community leaderboard; agent-tested on 2026-08-14; v0.8.0 update submitted (see below) |
+| [dshfind](https://github.com/hikariming/dshfind) | ✅ 已收录（自动聚合）<br>Listed (auto-aggregated) | 插件市场从 GitHub `dsh-plugin` topic 自动聚合；本仓库已带该 topic，刷新后展示最新版本与数据<br>Marketplace auto-aggregates from the GitHub `dsh-plugin` topic; this repo carries the topic, so the latest version shows after the next refresh |
+| [omdsh-dev/community](https://github.com/orgs/omdsh-dev/discussions/12) | ✅ 已提交收录申请<br>Submission submitted | `[Plugin]` 收录申请（Discussion #12）已通过；v0.8.0 更新说明已发布在该讨论<br>`[Plugin]` submission (Discussion #12) accepted; v0.8.0 update posted there |
+
+**更新请求 / Update requests**：
+
+- awesome-dsh-plugins 收录条目更新：`https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/<PR>`（v0.8.0 描述同步）
+- dshfind 数据刷新请求（含快照条目名称异常修正）：`https://github.com/hikariming/dshfind/issues/<ISSUE>`
+- omdsh-dev/community 收录讨论更新：https://github.com/orgs/omdsh-dev/discussions/12
+
+**Update requests**:
+
+- awesome-dsh-plugins entry refresh: `https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/<PR>` (v0.8.0 description)
+- dshfind data-refresh request (incl. fixing the snapshot entry name): `https://github.com/hikariming/dshfind/issues/<ISSUE>`
+- omdsh-dev/community listing update: https://github.com/orgs/omdsh-dev/discussions/12
+
 ## 免责声明 | Disclaimer
 
 > [!NOTE]

package/SECURITY.md

@@ -11,6 +11,8 @@
 - **SSRF**：agent 或桥接层被诱导访问内网 / 环回地址。
 - **消息重放 / 过期事件**：旧消息或重复事件被当作新指令处理。
 - **交互工具不可达**：`ask_user_question`、终端类工具在 IM 场景下无法回达，应默认禁用。
+- **救援通道被滥用**：dsh 下线后由守护接管飞书通道，若控制信号无鉴权，任何能私聊 bot 的人
+  都能触发安全模式或重启完整 profile。
 
 ## 安全姿态 · Security posture
 
@@ -35,19 +37,31 @@
    `/invite admin <open_id>` 定义）；查看类命令（`/model`、`/providers`、`/key list`）开放。
 10. **本地回调隔离**：`lark_notify` 工具的回调服务只绑定 `127.0.0.1`，每次启动生成随机
     token 鉴权（不落盘、不进日志），请求体限 1MB；`/notify` 与角色 / 配置写命令同为管理员操作。
+11. **安全网守护（可选安装）**：
+    - 守护是独立于 dsh / Cordis 的最小进程，只读取本地状态与进程命令行（`ps`，不读内存），
+      不导入任何 dsh 代码、不监听公网端口；
+    - dsh 在线时守护**不连接飞书**（同 app 长连接仅允许单连接，避免抢占正常通道）；仅在
+      「曾观察 dsh 在线 且 心跳过期 + 无 dsh 进程」时接管通道；
+    - 控制信号默认拒绝：仅管理员（`access.admins`，无管理员时回退 `allowedUsers`）可触发
+      `/safemode` 系列命令，未授权消息静默丢弃；
+    - 过期事件复用 `DSH_LARK_EVENT_FRESHNESS_MS` 窗口拒绝；
+    - 心跳 / 守护状态文件以 `0600` 写入；安全模式仅挂载官方核心 bundle（`dsh-base` +
+      `dsh-headless`），不加载任何第三方插件，避免把故障面带进救援通道。
 
 ## 数据与凭据 · Data & credentials
 
 - 本地配置 `~/.dsh-lark/config.json` 以 `0600` 权限写入。
 - 飞书凭据明文保存在本机配置文件；日志与卡片不输出真实密钥。
-- 后台服务把 `DEEPSEEK_API_KEY`、`DSH_LARK_*`、`PATH` 等环境快照到
-  `~/.dsh-lark/service/service.env`（`0600`）；systemd / launchd 单元文件中的 `EnvironmentFile`
-  只引用该文件，不内联密钥。
+- 桥接引擎在 dsh 宿主进程内运行，凭据与 `DSH_LARK_*` 环境直接随 dsh 进程提供，无独立服务
+  环境快照文件；敏感值不进日志与卡片。
 - 后台运行日志写入 `~/.dsh-lark/profiles/<profile>/logs/bot.log`（JSON Lines，密钥字段脱敏后输出）。
 - 聊天命令管理的 dsh 配置按官方存储协议写入：`~/.dsh/settings.yaml`（只存 `apiKeyEnv`
   引用，不落字面密钥）与 `~/.dsh/.credentials.yaml`（目录 0700、文件 0600）。bot 永不回显
   密钥值；群聊中粘贴密钥会对群成员可见，建议私聊使用或改用环境变量 / dsh Web 页面录入。
 - 所有数据仅在本机、飞书开放平台与 DeepSeek API 之间流转；无遥测。
+- 安全网守护相关文件：`~/.dsh-lark/guardian.json` 与
+  `~/.dsh-lark/profiles/<profile>/guardian/heartbeat.json`（均 `0600`）；守护读取的飞书凭据
+  来自 `~/.dsh-lark/config.json`（`0600`），日志按既有规则脱敏。
 
 ## 报告渠道 · Reporting
 

package/cordis.patch.yml

@@ -1,12 +1,30 @@
 # dsh-lark-bot as a profile bundle.
 
-# Installed with `dsh plugin --profile <name> add dsh-lark-bot`. The row
-# mounts the bridge-management plugin (`dsh-lark-bot/plugin`) and exposes
-# `ctx.larkBridge` without blocking profile boot. Set DSH_LARK_AUTOSTART=1
-# to start the standalone bridge when the profile boots.
+# Installed with `dsh plugin --profile <name> add dsh-lark-bot` (or the
+# single `dsh-lark-bot setup` command), dsh appends this package to the profile's
+# `dsh.profile.bundles` and applies this patch on boot:
+#   - `dsh-lark-bot/plugin` starts the full bridge engine IN-PROCESS (Feishu
+#     channel, workspace/session layers, notify server, nested dsh SDK
+#     runtime) and exposes `ctx.larkBridge` (status / stop).
+#   - `dsh-lark-bot/notify` mounts the `lark_notify` tool for the host agent.
+# First boot without credentials prints a QR code for one-time binding.
+# Set DSH_LARK_DISABLED=1 to keep the engine stopped.
 
 - insert:
     - id: dsh-lark-bot
       name: 'dsh-lark-bot/plugin'
       config:
-        autostart: !!js process.env.DSH_LARK_AUTOSTART === '1'
+        home: !!js process.env.DSH_LARK_HOME
+        tenant: !!js process.env.DSH_LARK_TENANT ?? 'feishu'
+        appId: !!js process.env.DSH_LARK_APP_ID
+        appSecret: !!js process.env.DSH_LARK_APP_SECRET
+        workspace: !!js process.env.DSH_LARK_WORKSPACE
+        adapter: !!js process.env.DSH_LARK_ADAPTER
+        model: !!js process.env.DSH_LARK_MODEL
+        disabled: !!js process.env.DSH_LARK_DISABLED === '1'
+
+    - id: lark-notify
+      name: 'dsh-lark-bot/notify'
+      config:
+        endpoint: !!js process.env.DSH_LARK_NOTIFY_URL
+        token: !!js process.env.DSH_LARK_NOTIFY_TOKEN