dsh-lark-bot DeepSeek Plugin

<p align="center">🌏 英文版：[README_EN.md](README_EN.md)</p>

<p align="center"> <strong>把 DeepSeek Harness 接入飞书</strong> </p>

<br>

让 DeepSeek Harness（dsh） 成为你飞书里的一员：在手机、群聊、话题里指挥本机 coding agent，把对话、任务、卡片和项目工作区都收进同一个协作流。

</div>

<p align="center"> 🌐 官网落地页 <a href="https://dsh-lark-bot.arr2018.dpdns.org">dsh-lark-bot.arr2018.dpdns.org</a> · 备用 <a href="https://plutokeating.github.io/dsh-lark-bot/">GitHub Pages</a> </p>

> ⚠️ 仅认准官方渠道： 唯一官方仓库 PlutoKeating/dsh-lark-bot，唯一官方 npm 包 dsh-lark-bot（同源双包 dsh-feishu-bot，维护者 plutokeating）。本项目从不提供 Windows 可执行文件（.exe），也没有任何“下载即运行”的安装包——任何以本项目名义提供 exe / “下载后双击运行”的页面、仓库或第三方分发渠道均为假冒 / 恶意来源，请勿下载或运行。官方安装唯一命令：npx dsh-lark-bot@latest setup --profile dsh-lark。仿冒仓库取证与完整声明见文末「假冒仓库警告」及 [docs/security/2026-08-17-impostor-repo-evidence/](docs/security/2026-08-17-impostor-repo-evidence/README.md)。

---

场景

你的 DeepSeek Harness 只能“贴身”用？ dsh 跑在本机，每次看进度、改任务都得回到电脑前；离开工位后任务卡住、跑偏甚至 dsh 崩了，你都收不到任何消息——回来才发现白等半天。

dsh-lark-bot 把遥控器装进你的飞书：在私聊、群聊、话题里直接指挥本机 dsh coding agent，流式卡片实时看思考与工具调用；任务完成主动推送到你所在的任何群并 @ 你；即使 dsh 崩溃下线，飞书里依然叫得应——发 /safemode 进入仅核心安全模式，直接在聊天里定位问题、重启引擎。这是唯一“dsh 挂了你不会失联”的桥接方案。

适合谁：在飞书 / Lark（私聊、群聊、话题）里指挥本机 dsh coding agent 的开发者与团队，尤其是需要多项目隔离、角色分工、并行任务与会话归档的协作场景。

能做什么

基础能力：

私聊、群聊、话题（thread）里指挥本机 dsh coding agent，图片 / 文本文件直接发给 bot 即可；
流式卡片实时展示思考、工具调用与结果，支持交互按钮（停止 / 审批 / 问答卡）；
Git 仓库内为每个会话自动创建隔离 worktree 项目工作区，多项目互不干扰。

六项全网独有组合：

🆘 Guardian 安全网守护——“永远叫得应”：DSH 崩溃后飞书仍会回复你，/safemode 进入仅核心安全模式直接重启。
👥 多角色 Agent——“一个机器人，一整个团队”：/role 切换或指派 PM / 开发 / 文档等角色，每个角色独立人设、模型偏好与规则。
⚡ 并行多任务——“不用排队”：同一群聊同时跑多个任务、会话隔离；其他方案只能串行排队。
🗂 会话归档与清理——“会话列表不会烂掉”：/archive 归档旧任务、/retention 配置自动保留策略。
📣 跨会话主动通知 + @人——“活干完了它会来找你”：A 群跑完任务主动推送到 B 群 / 私聊并 @ 你。
🔑 对话内管理模型和密钥——“不用离开飞书”：/providers /provider /key 直接查看、切换供应商、热更新密钥。

30 秒上手

前置条件（先装好本体，再装遥控器）：

1. DeepSeek Harness（dsh）已安装并配置好 DEEPSEEK_API_KEY —— dsh-lark-bot 是 dsh 的插件，dsh 才是 agent 本体，缺一不可； 2. Node.js ≥ 22.19（见 package.json engines）与一个飞书 / Lark 账号。

三步上线：

# ① 一键安装（无需先全局安装任何东西；自动装进 dsh profile，并默认同时安装「安全网守护」）
npx dsh-lark-bot@latest setup --profile dsh-lark

# ② 启动
dsh --profile dsh-lark

③ 首次启动终端打印二维码 → 飞书 / Lark App 扫码创建或选择 PersonalAgent 应用 → 绑定后私聊直接发消息，群聊 / 话题里 @bot。

setup 自动完成：定位本机 dsh → 预批准 pnpm 构建策略 → 标准 dsh plugin add → 默认安装「安全网守护」系统服务，一条命令完成全部安装。

> 无需公网 IP / 域名 / 服务器 / 内网穿透（飞书 WebSocket 出站长连接），Linux / macOS / Windows 通用。 > 已有 PersonalAgent 应用时可跳过扫码（见「配置」）：DSH_LARK_APP_ID=cli_xxx DSH_LARK_APP_SECRET=<secret> DSH_LARK_TENANT=feishu dsh --profile dsh-lark > 升级同样一条命令：npx dsh-lark-bot@latest upgrade --profile dsh-lark --yes

完整使用方式

常用命令

在飞书里向 bot 发送普通消息即可开始工作，常用命令：

| 命令 | 作用 | | --- | --- | | /new /reset | 开始新会话| | /newg <群名> | 自动新建群聊（拉你入群）并开新会话，当前会话保留| | /cd <path> | 切换工作目录并重置会话| | /ws list | 查看命名工作空间| | /ws save <name> | 保存当前工作空间| | /ws use <name> | 切换到命名工作空间| | /ws remove <name> | 删除命名工作空间| | /status | 查看当前状态| | /resume | 查看当前会话最近上下文| | /stop | 终止当前任务| | /timeout [N\|off\|default] | 查看或设置当前会话运行超时| | /concurrency [N\|default] | 查看或设置当前 scope 并行任务数（默认 2）| | /role list、/role show <id> | 查看角色列表 / 详情| | /role set <id>、/role clear | 为当前 scope 绑定 / 解除角色| | /role save <id> <name> [--persona 文案] [--model <id>] [--tools <csv>] [--rules 文案] | 创建 / 更新角色（管理员）| | /role remove <id> | 删除角色（管理员）| | /notify <scope\|chatId> <text> | 跨会话发送通知（管理员）| | /notify list | 查看 bridge 已注册的 scope| | /retention [N\|default] | 查看或设置保留消息条数（超出自动归档）| | /archive [note]、/archive list [N]、/archive clean | 手动归档 / 查看 / 清理会话记录| | /density [compact\|standard\|detailed] | 查看或设置卡片密度| | /model、/providers、/provider、/key | 打开交互式管理卡片（BotFather 式多轮向导；选择用按钮、填写用卡片输入、写入前确认）| | /model use <id> | 热切换当前会话模型（下一轮生效，无需重启）| | /model default <id> | 写入 dsh 默认模型 agent-default-model（管理员）| | /model add\|remove <provider> <modelId> | 添加 / 删除 provider 的模型（管理员）| | /provider add\|update\|remove <id> | 管理 provider（管理员；deepseek-official 与自定义 pi-ai）| | /key set\|remove\|list <引用名> | 管理 dsh 凭据（set / remove 需管理员）| | /ask <问题> | 发送问答卡，回答写入会话上下文| | /invite user\|admin\|group <id>、/invite list、/invite remove user\|group <id> | 管理访问白名单（写操作需管理员）| | /help | 查看帮助|

飞书消息中的图片会下载到本地 media 目录并传给 dsh；文本类文件会读取内容并注入任务上下文。

/newg <群名>：自动新建私密群、拉发送者入群并回复群链接——新群即新 scope / 新会话，当前会话不受影响。需应用具备 im:chat 与 im:chat.members:write_only 权限。

同一 scope（私聊 / 群聊 / 话题）默认 2 个任务并行（DSH_LARK_SCOPE_CONCURRENCY 或 /concurrency 调整）：多条消息以独立 run 并行推进，每个 run 使用独立 dsh session 与 runId；/status 查看全部运行中的 run，/stop 一次性终止。

多角色 Agent：管理员用 /role save <id> <name> --persona <文案> [--model <id>] [--tools <csv>] [--rules <文案>] 定义 PM / 开发 / 文档等角色，/role set <id> 绑定到当前 scope；每个 run 携带角色 persona 与规则，角色模型低于每会话 /model use。角色定义持久化在 ~/.dsh-lark/profiles/<profile>/roles.json。

出站 @ 提及与跨会话通知：/notify <scope|chatId> <text> 可向其他会话推送汇报（管理员）；agent 侧内置 lark_notify dsh 工具（SDK / ACP runtime 均可装配），任务完成后主动向其他群 / 话题发消息并 @ 成员。回调走 127.0.0.1 本地端口 + 随机 token，不暴露公网。

任务中向你提问（问答卡）：agent 需要你拍板、确认或补充信息时，通过 lark_ask_user 工具弹问答卡（单选 / 多选 / 自由文本），回答后任务自动继续，等待期间运行超时看门狗暂停。（与 /ask 的“你主动提问”方向相反。）

安全网守护：独立于 dsh 进程、系统级常驻的最小守护进程（systemd / LaunchAgent / Windows 启动项），默认随 setup 安装。dsh 正常时静默；dsh 下线或无法 boot（如第三方插件破坏 profile 组合）时自动接管飞书通道，无需命令行即可自救：

/safemode：进入仅核心安全模式（仅 dsh-base + dsh-headless 官方核心，不加载第三方插件），优先 SDK 流式引擎、失败回退 headless，直接在聊天里定位 / 修复 / 禁用损坏插件；
/safemode plugins：列出故障 profile 的插件清单；/safemode status：查看状态；/safemode stop：终止当前安全任务（或点卡片 ⏹）；/safemode exit：重启完整 profile 并交还通道。

安全模式任务有空闲超时（DSH_LARK_GUARDIAN_SAFE_TIMEOUT_MS，默认 10 分钟，仅持续无活动事件才终止），超时 / 失败都给出明确终态。安装：

# 随 setup 默认安装；已安装后也可单独安装 / 重装：
dsh-lark-bot guardian install --dsh-profile dsh-lark

不需要时 setup --no-guardian 跳过；单独卸载用 dsh-lark-bot guardian uninstall。

模型 / Provider / 凭据管理

配置以 dsh 官方方式持久化（与 dsh Web Settings → Models 同一存储协议），改动下一请求生效、无需重启：

交互式管理卡片：/providers（或 /provider、/model、/key）打开管理卡片，按

BotFather 式的多轮向导完成增删改查——能选择的用按钮点选（API 协议、provider、模型、凭据引用），需要填值的用卡片输入（ID、Base URL、模型列表、密钥值），写入前有确认卡，随时可取消。

/model use <id>：按会话热切换模型（下一轮生效）；/model default <id>：写入 dsh 默认模型。
/providers：查看 provider、模型与凭据状态；/provider add|update|remove：管理自定义 provider

（需 --api / --base-url / 至少一个 --model，与官方 schema 一致）或 deepseek-official。

/key set|remove|list：读写 ~/.dsh/.credentials.yaml（0600）；settings 只存 apiKeyEnv 引用，

字面密钥不进 settings / 聊天记录。

凭据引用必须关联：/key set <引用名> <值> 只写入凭据文件；provider 要生效还须在其

apiKeyEnv 字段引用同一名字（/provider add|update ... --api-key-env <引用名>，或向导中填写）。

引用名与 provider ID 相同且 provider 未设 apiKeyEnv 时，/key set 会自动补关联；已存在的老配置在下次运行时也会自动补齐。

热重载：桥接在每轮运行前把模型解析为「provider + model」路由并传给 dsh runtime；SDK 适配器

在路由变化时自动重建 runtime（下一轮生效）。pi-ai 的 Base URL 填根域名（如 https://www.kingapi.xyz）会自动补全为 /v1。dsh runtime 启动后需几百毫秒才注册 pi-ai 路由，桥接会重试握手直到注册完成（避免 “no adapter registered for provider”）。

安全提醒：在飞书会话输入密钥会对可见成员暴露，建议私聊使用或 --api-key-env 引用环境变量；bot 不在任何回复中回显密钥值。

升级、禁用与卸载

升级

推荐：一行命令彻底升级（v0.12.0+ 新增，issue #10）

npx dsh-lark-bot@latest upgrade --profile dsh-lark --yes

upgrade 自动完成：检测当前已装版本 / 运行中 CLI / npm 最新版 → 升级包本体 （dsh plugin add <name>@<latest>）→ 幂等重装并重启 guardian 服务 → 升级后运行 doctor 验证。覆盖运行中实例的安全处理：

默认不打断运行中的 dsh profile，只提示重启命令（升级不影响配置 / 会话 / 凭据）；
--restart：升级后自动重启 guardian 服务与（受管/后台的）dsh profile 进程；
--check：只报告版本与运行状态，零改动；
--rollback：回滚到上一次升级前的版本（记录在 ~/.dsh-lark/upgrade-state.json）；
--force：无法访问 npm（离线）时按当前运行版本重装；
--no-guardian：跳过守护升级；
runtime profile 一致性修复：升级后自动把 dsh-lark-sdk / dsh-lark-acp 的

own-package 链接重指到新版本（避免下次启动重新预置）。

无需交互确认时加 --yes（非交互环境不带 --yes 会安全中止）。其余方式：

插件本体：重跑 setup（或 dsh plugin --profile <name> add dsh-lark-bot）拉取 npm 最新版。
安全网守护：随 upgrade / setup 一起安装 / 升级（幂等重装），也可单独

dsh-lark-bot guardian install。

CLI 工具（可选）：npm i -g dsh-lark-bot@latest；使用 npx 时无需全局安装。
升级后重启 profile（未用 --restart 时）：dsh --profile dsh-lark。

禁用

保持插件加载但停止桥接引擎：启动 profile 前导出 DSH_LARK_DISABLED=1。彻底移除见下节。

卸载

dsh plugin --profile dsh-lark remove dsh-lark-bot

卸载后 profile 不再加载本插件。本地状态（配置 / 会话 / 归档 / 角色）保留在 ~/.dsh-lark；如需清除，先备份再删除该目录。

更详细的安装、状态目录、日志和排障说明见 [docs/QUICK_START.md](docs/QUICK_START.md)。

---

FAQ（典型用例与常见问题）

典型用例

Q: 出门在外，想用手机指挥本机的 DeepSeek Harness？

A: 可以。安装并扫码绑定后，用飞书手机 App 发消息即可指挥本机 dsh coding agent；任务完成还能跨会话主动推送并 @ 你。安装：npx dsh-lark-bot@latest setup --profile dsh-lark → dsh --profile dsh-lark → 扫码 → 开聊。

Q: 多个项目 / 多人协作，怎么隔离与分工？

A: 每个会话自动落在独立 git worktree，项目级 AGENTS.md 自动注入；管理员用 /role 定义并绑定角色、用 /invite 管理白名单；同群默认 2 个任务并行（/concurrency 调整），/archive + /retention 控制归档与保留。

Q: dsh 崩溃 / 掉线后，飞书机器人还能用吗？

A: 能。setup 默认安装独立于 dsh 的「安全网守护」：dsh 崩溃时守护自动接管飞书通道并先尝试自动重启；仍失败时发 /safemode 进入仅核心安全模式定位 / 修复问题，/safemode exit 恢复完整 profile。全程不需要命令行。

常见问题

Q: DeepSeek Harness 怎么接入飞书？

A: 安装 Node.js ≥ 22 与 DeepSeek Harness（已配置 DEEPSEEK_API_KEY），执行 npx dsh-lark-bot@latest setup --profile dsh-lark，再 dsh --profile dsh-lark 扫码绑定即可。私聊直接发消息，群聊 / 话题里 @bot。

Q: 需要公网 IP、域名或服务器吗？

A: 不需要。飞书通道使用 WebSocket 长连接（出站连接），本机在 NAT 后面也能用，免公网服务器、免域名、免内网穿透。

Q: dsh-lark-bot 和其他 DeepSeek Harness 飞书插件（如 harness-lark）有什么区别？

A: 功能组合最全：安全网守护、多角色 Agent、并行多任务、会话归档、跨会话主动通知、对话内模型 / 密钥管理六项合一；标准 dsh profile bundle，npx dsh-lark-bot@latest setup 一条命令安装，无需独立 Docker / 后台服务。

Q: 项目从哪下载？会不会有假冒版本？

A: 唯一官方仓库是 github.com/PlutoKeating/dsh-lark-bot，唯一官方 npm 包是 dsh-lark-bot / dsh-feishu-bot（维护者 plutokeating）。本项目从不提供 .exe 或“下载即运行”的安装包；任何以项目名义分发 exe 的仓库或页面都是假冒来源，请勿运行（详见文末「假冒仓库警告」）。

---

关键词

dsh · deepseek · deepseek harness · feishu · lark · bridge · bot · chatbot · messaging · qrcode · typescript · feishu-bot · lark-bot · dsh-plugin · deepseek-harness · im-bridge · ai-agent · workspace · self-healing

兼容性

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)。

运行时：Node.js ≥ 22.19（见 package.json engines）。
平台：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_LARK_ADAPTER=web 驱动本地 dsh web agent（session.prompt + /api/events.mux，网页端成为唯一写者，从根上消除多写者会话损坏）。首次启动自动在 ~/.dsh/profiles/dsh-lark-sdk（或 dsh-lark-acp）创建 runtime profile。

已知限制

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 } 后重试。

配置

本地配置：~/.dsh-lark/config.json
状态根目录可用 DSH_LARK_HOME 覆盖
环境变量统一使用 DSH_LARK_* 前缀
模板见 [.env.example](.env.example)
敏感项：DSH_LARK_APP_SECRET、DEEPSEEK_API_KEY 等凭据只保存在本机配置 / 环境中，日志与

卡片自动脱敏，仓库只提交 .env.example 模板。

会话运行在 Git 仓库中时，会自动在 ~/.dsh-lark/profiles/<profile>/worktrees/<scope>/ 创建隔离 worktree，并复制项目级 AGENTS.md。

每个飞书 scope 默认保存最近 40 条对话消息（可用 /retention 或 DSH_LARK_RETENTION_MSGS 调整）；超出保留窗口的消息自动归档到 ~/.dsh-lark/profiles/<profile>/archives/（Markdown + JSONL，目录本身是 Git 仓库，每次归档独立 commit），支持 /archive 手动归档与保留策略清理。 SDK 模式下 dsh 原生 session 续跑，headless 模式则把历史注入下一次 prompt 实现近似记忆。

当前核心环境变量：

变量	默认值	说明
`DSH_LARK_HOME`	`~/.dsh-lark`	本地状态根目录
`DSH_LARK_TENANT`	`feishu`	`feishu` 或 `lark`
`DSH_LARK_WORKSPACE`	未设置	新会话默认工作目录
`DSH_LARK_DSH_COMMAND`	`自动发现`	dsh 启动命令；通常无需设置
`DSH_LARK_DSH_ARGS`	`自动发现`	dsh 启动参数，逗号分隔；通常无需设置
`DSH_LARK_ADAPTER`	`sdk`	`sdk`（默认）/ `acp`（审批）/ `headless`（legacy）/ `web`（本地 dsh web agent，单写者）
`DSH_LARK_PROVIDER`	`deepseek-official`	模型 provider
`DSH_LARK_MODEL`	`deepseek-v4-flash`	默认模型
`DSH_LARK_MAX_TOKENS`	未设置	SDK agent 每请求输出 token 上限
`DSH_LARK_WEB_URL`	`http://127.0.0.1:3080`	`web` 适配器：本地 dsh web agent 的 base URL
`DSH_LARK_WEB_PUSH`	`true`	`web` 适配器：网页端回合完成时推送到飞书并自动切换会话映射（`0` 关闭）
`DSH_LARK_ACCESS_DEFAULT_DENY`	`false`	无白名单时拒绝私聊
`DSH_LARK_EVENT_FRESHNESS_MS`	`600000`	过期消息拒绝窗口（0 关闭）
`DSH_LARK_RUN_TIMEOUT_MS`	`300000`	单次运行空闲超时：持续无活动事件才终止（活跃任务不会被误杀）
`DSH_LARK_STOP_GRACE_MS`	`5000`	SIGTERM 后等待优雅退出再 SIGKILL 的宽限期
`DSH_LARK_SCOPE_CONCURRENCY`	`2`	每个 scope 的并行任务数（1=严格串行）
`DSH_LARK_RETENTION_MSGS`	`40`	每个 scope 保留的消息条数（0=全部保留）
`DSH_LARK_ARCHIVE_MAX`	`50`	每个 scope 最多保留的归档数（0=不清理）
`DSH_LARK_ARCHIVE_MAX_AGE_DAYS`	`90`	归档最大保留天数（0=不清理）
`DSH_LARK_HEARTBEAT_MS`	`5000`	桥接引擎心跳写入间隔（守护存活信号）
`DSH_LARK_GUARDIAN_DISABLED`	`false`	`1` 时安全网守护进程保持停止
`DSH_LARK_GUARDIAN_PROFILE`	`dsh-lark`	守护监视 / 重启的 dsh profile（首次安装时写入状态）
`DSH_LARK_GUARDIAN_BRIDGE_PROFILE`	`default`	提供飞书凭据与白名单的桥接状态 profile
`DSH_LARK_GUARDIAN_POLL_MS`	`2000`	守护看门狗轮询间隔
`DSH_LARK_GUARDIAN_STALE_MS`	`15000`	心跳超时阈值，超过且无 dsh 进程则接管飞书通道
`DSH_LARK_GUARDIAN_ENGINE_DEAD_MS`	`120000`	dsh 进程存活但心跳持续超时该时长，判定桥接引擎已死并接管
`DSH_LARK_GUARDIAN_SAFE_ADAPTER`	`auto`	安全模式引擎：`auto` 优先 SDK 流式、失败回退 headless；`sdk` 强制 SDK；`headless` 跳过预置
`DSH_LARK_GUARDIAN_SAFE_TIMEOUT_MS`	`600000`	安全模式单任务空闲超时（持续无活动事件才停止并出超时卡）
`DSH_LARK_GUARDIAN_CARD_DENSITY`	`detailed`	安全模式任务卡片密度（compact / standard / detailed）
`DSH_LARK_UPGRADE_REGISTRY`	`https://registry.npmjs.org`	`upgrade` 探测最新版本的 npm registry（可指向镜像）
`DSH_LARK_UPGRADE_CHECK`	`1`	`doctor` / `/version` 是否探测 npm 最新版本（`0` 关闭，best-effort）
`DSH_LARK_UPGRADE_CHECK_INTERVAL_MS`	`21600000`	桥接引擎检查新版本的间隔（`0` 关闭，默认 6h）
`DSH_LARK_UPGRADE_NOTIFY`	`false`	`true` 时发现新版本向指定 chat 推送飞书通知（默认仅日志）
`DSH_LARK_UPGRADE_NOTIFY_CHAT`	—	接收更新通知的 chat id（配合 `DSH_LARK_UPGRADE_NOTIFY=true`）

启动时会自动查找本机常见的 @deepseek-ai/dsh 安装位置。只有自动发现失败或需要指定特殊 profile 时，才需要设置这两个变量。

权限与数据

本工具在本机运行，安装前请知悉它会访问：

飞书凭据：PersonalAgent 应用的 app_id / app_secret，明文写入本机 ~/.dsh-lark/config.json（文件权限 600）。
文件系统：读取 / 写入你通过 /cd、/ws 指定的工作目录（含执行 shell 命令、修改文件）。
网络：向飞书开放平台建立 WebSocket 出站长连接收发消息；向 DeepSeek API 发送任务上下文。
本地回调：运行 lark_notify 工具时，dsh runtime 子进程通过 127.0.0.1 随机端口 +

每启动随机 token 回调 bridge 进程（仅本机回环，不监听公网）。

进程：spawn 本机 dsh runtime 子进程（dsh-sdk-jsonrpc-server / dsh-acp profile）执行 agent 任务。
dsh 配置：/model /providers /provider /key 命令按 dsh 官方存储协议读写

~/.dsh/settings.yaml 与 ~/.dsh/.credentials.yaml（仅管理员可写；settings 只存 apiKeyEnv 引用，凭据文件权限 0600、目录 0700，字面密钥不进入 settings 或聊天记录）。

安全网守护（默认随 setup 安装）：系统级常驻进程，读取 ~/.dsh-lark/config.json 中的飞书

凭据；dsh 下线时接管同一 bot 的飞书长连接并扫描本机进程（仅 ps 命令行，不读内存）； /safemode 时创建仅官方核心的 dsh profile（headless 或 SDK JSON-RPC runtime，均无第三方插件）并逐条执行任务；SDK 引擎会以官方 dsh-sdk-jsonrpc-server 子进程提供实时流式事件。

所有数据仅在本机与飞书、DeepSeek 之间流转，不收集、不上传任何遥测。密钥不会提交进仓库（见 .gitignore）。

排障

先运行 dsh-lark-bot doctor，它会检查 profile、工作目录，并对当前 adapter 做真实可用性探测（sdk / acp / headless 对应 runtime 的初始化握手）。

常见问题：

bot 静默 / 长连接失败：查看 stderr 上的 JSONL 日志，关注 channel 与 channel-command 类别；SDK 会自动重连。
agent 无响应：发送 /status 查看当前 scope、cwd 和 active run；发送 /stop 终止当前任务；持续无响应超过 DSH_LARK_RUN_TIMEOUT_MS 时看门狗会自动终止（空闲超时，活跃任务不会被误杀）。
首次扫码失败：确认本机时间准确、网络可访问飞书开放平台；已拿到 App ID/Secret 时可用 --app-id / --app-secret 跳过扫码。

桥接引擎日志以 JSON Lines 输出到 stderr（由 dsh 宿主进程捕获；logs/bot.log 是 0.6.0 独立服务时代的遗留路径，0.7.0 起不再写入）；dsh 宿主日志走 dsh 自己的日志体系。

回滚：dsh plugin --profile dsh-lark remove dsh-lark-bot 后重装固定版本即可（如 dsh plugin --profile dsh-lark add dsh-lark-bot@0.6.0）；~/.dsh-lark 状态独立于插件本体，升级 / 回滚不会丢失配置与会话。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm check:publish-bundle   # 校验 dist 与全部 exports/bin 入口一致（发布前防线）
pnpm ci:local
pnpm release:check   # ci:local + 上游一致性检查
pnpm compat:probe    # 临时 DSH_HOME 安装锁定版 dsh，跑真实 SDK 握手
pnpm dsh:upstream    # 对比 npm 上游 stable 与锁定矩阵
pnpm security:monitor # 假冒仓库与仿冒包监控（建议每周）

开发规范见 [AGENTS.md](AGENTS.md)，模块契约见 [docs/API.md](docs/API.md)，架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。兼容矩阵的升级政策与自动化见 [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md)。

贡献：欢迎 Issue 与 PR。开发流程见 [AGENTS.md](AGENTS.md)（必读文档、提交规范与推送边界），生态交付标准见 [docs/ECOSYSTEM.md](docs/ECOSYSTEM.md)。

发布双包（dsh-lark-bot 与 dsh-feishu-bot 共享同一份 dist / 版本 / 依赖）：

pnpm publish:dual:dry-run
pnpm publish:dual

scripts/publish-dual-packages.mjs 从根 package.json 生成两份仅 name / bin 不同的发布清单，避免两份源码漂移。发布时整目录同步 dist/，并在发布前校验 package.json 每个 exports 子路径与 CLI 入口在产物中都存在——任何缺失（如 v0.9.0 的 ask 入口漏拷）都会直接中止发布。GitHub tag v* 会触发 [release.yml](.github/workflows/release.yml) 自动发布两个 npm 包并创建 Release。

同一份 dist 还会以 @plutokeating/dsh-lark-bot 和 @plutokeating/dsh-feishu-bot 发布到 GitHub Packages，便于在 GitHub Packages 页面查看。

维护与支持

状态：活跃维护。主维护者：PlutoKeating。
问题 / 建议：优先在 GitHub Issues 提交；安全漏洞请走 [SECURITY.md](SECURITY.md) 的私下报告渠道。

社区收录情况见下节「社区收录情况」。

作者

本项目由 PlutoKeating 开发并维护。作者专注于自动化与开发者工具，习惯从真实使用场景出发做软件：本项目正是从“用飞书 / Lark 群聊驱动 DeepSeek Agent”的日常需求长出来的，逐步演进为一套带守护、自愈与一键升级能力的完整桥接方案。更多信息见个人主页： PlutoKeating。

贡献者

感谢以下贡献者（按合入 / 提交时间）：

贡献者	贡献	状态
koprivnikarurnaa-oss	PR #9：web 单写者适配器 + self-heal v2 + 守护自动重启	✅ 已合入
Normanyin	PR #11：`/newg` 自动建群命令	✅ 已合入（cherry-pick）

> 说明：GitHub 贡献者图按 commit 作者邮箱归因。PR #9 合入时的提交使用了本地通用身份 > dsh-user <dsh-user@local>（未绑定 GitHub 账号），因此未自动计入贡献者图；本表为仓库侧 > 的明确署名，PR #11 的提交身份已绑定其账号，合入后会自动计入。 >

许可与安全

许可证：GNU Affero General Public License v3.0（见 LICENSE）。
版权归属：源码版权归项目维护者所有，按 AGPL-3.0 授权；「DeepSeek」「飞书 / Lark」等

商标归各自权利人所有。

安全报告：如发现安全漏洞，请通过 GitHub Security Advisory 私下报告，勿公开 issue。
安全模型：默认拒绝、密钥脱敏、路径 containment、SSRF 防护、过期事件拒绝与交互工具

默认禁用——详见 [SECURITY.md](SECURITY.md)。

文档

> 接手本项目的工程师：先读 [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) 和 [docs/RESEARCH.md](docs/RESEARCH.md)，即可完整理解项目诉求与来龙去脉，无需线下沟通。

| 文档 | 内

…

dsh-lark-bot

Install

Check the source files

场景

能做什么

30 秒上手

完整使用方式

常用命令

模型 / Provider / 凭据管理

升级、禁用与卸载

升级

禁用

卸载

FAQ（典型用例与常见问题）

典型用例

常见问题

关键词

兼容性

已知限制

配置

权限与数据

排障

开发

维护与支持

作者

贡献者

许可与安全

文档

Source facts

Install

Check the source files

场景

能做什么

30 秒上手

完整使用方式

常用命令

模型 / Provider / 凭据管理

升级、禁用与卸载

升级

禁用

卸载

FAQ（典型用例与常见问题）

典型用例

常见问题

关键词

兼容性

已知限制

配置

权限与数据

排障

开发

维护与支持

作者

贡献者

许可与安全

文档

More related plugins

openpets#dsh

dsh-pocket

dsh-notification