dsh-lark-bot 0.7.0 → 0.8.1

package/README.md

@@ -10,6 +10,7 @@
   <img src="https://img.shields.io/badge/runtime-Node.js%20%E2%89%A5%2022-339933" alt="Node">
   <img src="https://img.shields.io/badge/License-AGPLv3-blue" alt="License">
   <img src="https://img.shields.io/badge/status-released-blue" alt="Status">
+  <a href="https://dshfind.com/zh/plugins/PlutoKeating/dsh-lark-bot?ref=badge"><img src="https://dshfind.com/api/badge/PlutoKeating/dsh-lark-bot?lang=zh" alt="dshfind"></a>
 </p>
 
 <br>
@@ -24,6 +25,49 @@
 
 </div>
 
+<div align="center">
+
+<a href="https://dshfind.com/zh/plugins/PlutoKeating/dsh-lark-bot?ref=badge"><img src="https://dshfind.com/api/card/PlutoKeating/dsh-lark-bot?lang=zh" alt="dshfind" width="440"></a>
+
+</div>
+
+---
+
+## 项目介绍 | What & Why
+
+**用在什么场景？** 你在飞书 / Lark（私聊、群聊、话题）里指挥本机 DeepSeek Harness（`dsh`）
+coding agent：发消息就收流式卡片与工具调用过程，把项目工作区、并行任务、会话归档都收进同一
+个协作流。适合需要多项目隔离、角色分工、并行任务与故障自愈的开发者与团队。
+
+**Where does it fit?** Drive your local DeepSeek Harness (`dsh`) coding agent from Feishu /
+Lark — DMs, group chats and topics — with streaming cards, isolated project workspaces,
+parallel tasks, session archival and self-healing when things break.
+
+**功能亮点（以下六项为 dsh-lark-bot 全网独有组合）| Highlights (exclusive to dsh-lark-bot)**：
+
+- 🆘 **Guardian 安全网守护 —— “永远叫得应”**：DSH 进程一崩，其他方案的机器人就变成死号，只能回
+  服务器手动重启；dsh-lark-bot 的守护进程在 DSH 崩溃后**仍然会在飞书回复你**——告诉你引擎已挂、
+  可进入仅核心安全模式，直接在飞书对话里发控制信号把它重启。**唯一“出故障时用户不会失联”的项目。**
+  *When DSH crashes, this bot still answers in Feishu: enter core-only safe mode and send a
+  control signal to restart it. The only project where users never lose contact.*
+- 👥 **多角色 Agent —— “一个机器人，一整个团队”**：在飞书里用 `/role` 切换或指派 PM / 开发 /
+  文档等角色，每个角色有持久化的人设、模型偏好与规则。
+  *Switch or assign PM / dev / docs personas in chat with `/role` — each with its own
+  persisted persona. One bot, a whole team.*
+- ⚡ **并行多任务 —— “不用排队”**：同一群里可以**同时跑多个任务**，各自会话隔离；其他方案同聊
+  串行，上一个没跑完下一个只能等。
+  *Run multiple tasks in the same chat simultaneously with isolated sessions — no queueing.*
+- 🗂 **会话归档与清理 —— “会话列表不会烂掉”**：`/archive` 归档旧任务、`/retention` 配置自动保留
+  策略；长期使用也不会越积越多。
+  *Archive old tasks and auto-prune with retention policies — your session list stays clean.*
+- 📣 **跨会话主动通知 + @人 —— “活干完了它会来找你”**：Agent 在 A 群跑完任务，可以**主动发消息到
+  B 群或私聊并 @ 你**；而不是“你问它答”。
+  *Agents proactively report to other chats or DMs and @mention you when work finishes.*
+- 🔑 **对话内管理模型和密钥 —— “不用离开飞书”**：`/providers` `/provider` `/key` 直接在聊天里
+  查看、切换供应商、热更新密钥，全程闭环。
+  *View providers, switch vendors and hot-update API keys entirely in chat — no server-side
+  edits.*
+
 ---
 
 ## 快速开始 | Quick Start（普通用户先看这里 | for end users）
@@ -153,6 +197,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** 页面完全相同的
@@ -187,14 +272,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,
@@ -212,6 +339,13 @@ 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
 
 - **一条命令安装部署**：`npx dsh-lark-bot@latest setup --profile dsh-lark` 装进 dsh profile，
@@ -227,7 +361,7 @@ logs and troubleshooting.
 
 ## 兼容性 | 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)。
@@ -235,9 +369,9 @@ logs and troubleshooting.
 - **平台**：Linux / macOS / Windows（飞书 WebSocket 出站长连接，免公网服务器 / 域名 / 内网穿透）。
 - 默认 adapter 为官方 **`@deepseek-ai/dsh-sdk-client`**（SDK JSON-RPC runtime，原生 session 续跑 +
   token 级流式事件）；`DSH_LARK_ADAPTER=acp` 切到官方 **ACP server**（审批卡）；`headless` 保留旧版
-  子进程 fallback。首次启动自动在 `~/.dsh/profiles/dsh-lark`（或 `dsh-lark-acp`）创建 runtime profile。
+  子进程 fallback。首次启动自动在 `~/.dsh/profiles/dsh-lark-sdk`（或 `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
@@ -249,7 +383,32 @@ logs and troubleshooting.
   native session continuation and token-level streaming events); `DSH_LARK_ADAPTER=acp` switches
   to the official **ACP server** (approval cards); `headless` keeps the legacy subprocess
   fallback. On first start the bot creates the runtime profile at
-  `~/.dsh/profiles/dsh-lark` (or `dsh-lark-acp`).
+  `~/.dsh/profiles/dsh-lark-sdk` (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
 
@@ -257,11 +416,15 @@ logs and troubleshooting.
 - 状态根目录可用 `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`。
 
@@ -302,6 +465,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 时，才需要设置这两个变量。
 
@@ -323,6 +493,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).
@@ -338,6 +512,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`）。
 
@@ -375,6 +554,14 @@ dsh 自己的日志体系。
 The bridge engine logs to `~/.dsh-lark/profiles/<profile>/logs/bot.log` (JSON Lines); the dsh
 host uses its own logging.
 
+**回滚 / 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
 
 ```bash
@@ -396,6 +583,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 /
@@ -418,14 +612,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
@@ -462,8 +673,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 |
@@ -477,6 +697,7 @@ The core idea: **decouple the Feishu channel from the agent backend**. The bridg
 | `src/bot/` | 运行注册、消息排队、审批/问答注册表<br>Run registry, queueing, approval/question registries |
 | `src/commands/` | 斜杠命令（/cd /ws /new …）<br>Slash 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 |
@@ -496,6 +717,41 @@ 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（[PR #127](https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/127) 已合并）<br>Shown as `✅ 运行级可用` in the community leaderboard; agent-tested on 2026-08-14; the v0.8.0 entry update ([PR #127](https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/127)) is merged |
+| [dshfind](https://dshfind.com/zh/plugins/PlutoKeating/dsh-lark-bot) | ✅ 已收录 · 详情页已上线<br>Listed · detail page live | 中英日韩四语详情页已上线（含安装命令与亮点），条目名称正常（[issue #2](https://github.com/hikariming/dshfind/issues/2) 已关闭）；顶部徽章 / 展示卡来自 dshfind<br>Four-language detail page is live (install command & highlights), entry name fixed ([issue #2](https://github.com/hikariming/dshfind/issues/2) closed); the header badge / card comes from dshfind |
+| [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 request status**：
+
+- awesome-dsh-plugins 收录条目更新：[#127](https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/127) — ✅ 已合并
+- dshfind 数据刷新请求（含条目名称异常修正）：[#2](https://github.com/hikariming/dshfind/issues/2) — ✅ 已关闭，详情页已更新
+- omdsh-dev/community 收录讨论更新：[Discussion #12 更新评论](https://github.com/orgs/omdsh-dev/discussions/12#discussioncomment-18021998) — ✅ 已发布
+
+**Update requests**:
+
+- awesome-dsh-plugins entry refresh: [#127](https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/127) — ✅ merged
+- dshfind data-refresh request (incl. fixing the entry name): [#2](https://github.com/hikariming/dshfind/issues/2) — ✅ closed, detail page updated
+- omdsh-dev/community listing update: [Discussion #12 update comment](https://github.com/orgs/omdsh-dev/discussions/12#discussioncomment-18021998) — ✅ posted
+
+**亮点跟进 / Highlights follow-ups**（六项独家能力与 issue #6 设计实现）：
+
+- awesome-dsh-plugins 榜单行同步（仓库描述 → v0.8.0）与 agent-test 报告名称异常：[#139](https://github.com/AdamPlatin123/awesome-dsh-plugins/issues/139) — 📨 已提交
+- dshfind 详情页补「对话内管理模型和密钥」亮点：[#2 跟进评论](https://github.com/hikariming/dshfind/issues/2#issuecomment-5301019067) — 📨 已提交
+- omdsh 六项独家亮点补充（含 Guardian 设计实现）：[Discussion #12 亮点评论](https://github.com/orgs/omdsh-dev/discussions/12#discussioncomment-18026370) — 📨 已提交
+
+**Highlights follow-ups** (six exclusive capabilities & the issue #6 design):
+
+- awesome-dsh-plugins leaderboard row sync (repo description → v0.8.0) & agent-test name anomaly: [#139](https://github.com/AdamPlatin123/awesome-dsh-plugins/issues/139) — 📨 submitted
+- dshfind detail page: add the in-chat model/key management highlight: [#2 follow-up](https://github.com/hikariming/dshfind/issues/2#issuecomment-5301019067) — 📨 submitted
+- omdsh six-exclusive-highlights summary (incl. the Guardian design): [Discussion #12 highlights comment](https://github.com/orgs/omdsh-dev/discussions/12#discussioncomment-18026370) — 📨 submitted
+
 ## 免责声明 | Disclaimer
 
 > [!NOTE]

package/SECURITY.md

@@ -11,6 +11,8 @@
 - **SSRF**：agent 或桥接层被诱导访问内网 / 环回地址。
 - **消息重放 / 过期事件**：旧消息或重复事件被当作新指令处理。
 - **交互工具不可达**：`ask_user_question`、终端类工具在 IM 场景下无法回达，应默认禁用。
+- **救援通道被滥用**：dsh 下线后由守护接管飞书通道，若控制信号无鉴权，任何能私聊 bot 的人
+  都能触发安全模式或重启完整 profile。
 
 ## 安全姿态 · Security posture
 
@@ -35,6 +37,16 @@
    `/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
 
@@ -47,6 +59,9 @@
   引用，不落字面密钥）与 `~/.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