一句话定位

把本机 DeepSeek Harness (dsh) 装进飞书/Lark 的 bot：在手机、私聊、群聊、话题里直接指挥 dsh coding agent，飞书原生折叠卡片实时展示思考与工具调用，任务完成可跨群主动推送并 @ 你，dsh 崩溃时仍能远程自救。

核心能力

• 在飞书/Lark 私聊、群聊、话题（thread）里直接给 dsh coding agent 发指令，图片和文本文件直接发给 bot 即可作为附件传入
• 用飞书原生折叠卡片实时展示思考过程和工具调用结果，最终回答单独成消息，支持审批卡、问答卡、计划门禁卡等交互按钮
• Git 仓库内为每个会话自动创建独立的 git worktree 项目工作区，多项目互不干扰
• 内置「安全网守护」：独立于 dsh 进程常驻，dsh 崩溃或掉线时接管飞书通道，发 /safemode 进入仅核心安全模式远程定位并修复问题
• 提供 dsh Web 可视化设置页面：账号凭据、服务区域、默认项目、默认模型、并行任务数、主动提醒策略等所有项可点选保存
• 跨会话主动通知 + @ 人，agent 可调用 lark_notify 把结果推到任意群；持久任务账本支持 /jobs 对账、重试失败任务

技术实现

• 语言: TypeScript（ESM，Node.js 22.19+）
• 关键依赖: @deepseek-ai/cordis（宿主服务总线）、@larksuite/channel（飞书 WebSocket 长连接）、@deepseek-ai/dsh-sdk-client（agent runtime）、@deepseek-ai/schemastery（设置 schema）
• 架构模式: 作为标准 dsh profile bundle 通过 cordis.patch.yml 一次性注入 5 个 Cordis 子插件：dsh-lark-bot/plugin（主引擎，含飞书通道、会话路由、agent adapter、notify 服务端）+ lark-notify/lark-file/lark-plan-approval/lark-approval-answerer（对应 host agent 的 lark_notify / lark_send_file / 计划门禁 / 工具审批挂载点）。同时向 dsh Web 注入 @deepseek-ai/dsh-client-ui-settings-plugins 提供可视化设置面板。
• 入口文件: src/plugin.ts（Cordis 入口，导出 apply / LarkBridgeService / Config）+ src/cli.ts（CLI 入口 setup / upgrade / bot / service / guardian / doctor）

适用场景

适合经常离开工位、需要用手机或在飞书群聊里继续驱动 dsh coding agent 的开发者与协作团队：远程发起任务、跨设备继续会话、多项目隔离、跨群派发结果通知，以及担心 dsh 崩溃后失联、希望「飞书始终叫得应」的工作流。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:PlutoKeating/dsh-lark-bot

推荐安装路径：先 npx dsh-lark-bot@latest setup --profile dsh-lark 一键完成本机定位 + guardian 守护安装 + 插件装载，再用 dsh --profile dsh-lark 启动扫码绑定飞书应用。

配置项

所有项均可在 dsh Web 的「设置 → 插件 → dsh-lark-bot」页点选保存，App Secret 标记为只写不回显；也可用同名环境变量（DSH_LARK_*）覆盖。

常见问题

Q: 安装后怎么开始使用？

A: 先确保本机已装好 DeepSeek Harness 并配置 DEEPSEEK_API_KEY，运行 dsh --profile <profile名> 启动。首次启动终端会打印二维码，飞书/Lark App 扫码创建或选择 PersonalAgent 应用即可绑定。私聊直接发消息，群聊/话题默认需要 @bot。

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

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

Q: dsh 进程崩溃或掉线后飞书 bot 还能用吗？

A: 可以。默认安装的安全网守护（guardian）独立于 dsh 常驻，dsh 掉线时自动接管飞书通道；发 /safemode 进入仅核心安全模式可远程定位/修复问题、禁用损坏插件，再 /safemode exit 交还通道。

Q: 多个项目/多人协作怎么隔离？

A: 每个会话自动落在独立 git worktree；群聊隔离可通过 /isolation 在整群共享/话题独立/成员独立之间切换；管理员可用 /role 定义 PM/开发/文档等多角色并绑定到不同 scope；多机器人实例用 dsh-lark-bot bot add 创建独立身份与凭据。

Q: 卸载会影响本地数据吗？

A: 仅运行 dsh plugin --profile <profile名> remove dsh-lark-bot 不会删除本地数据。配置、会话、归档、角色、凭据默认保留在 ~/.dsh-lark；如需彻底清除请手动备份后删除该目录。

Q: 报 ERR_PNPM_IGNORED_BUILDS 怎么办？

A: 按官方指引在 profile 的 pnpm-workspace.yaml 中加 allowBuilds: { protobufjs: true } 后重试即可。setup 命令会自动预批准这些构建策略（仅在手动 dsh plugin add 时才会触发该报错）。

Q: agent 长连接掉了会怎样？

A: SDK 适配器会自动重连并在恢复后向最近活跃会话发送恢复提示。机器睡眠或断网期间 WebSocket 无法收消息，恢复连接后会触发提示，不需要人工重启。

Q: ACP / SDK / web / headless 这些 adapter 有什么区别？

A: sdk（默认）走官方 dsh-sdk-client，支持原生 session 续跑与 token 级流式；acp 走官方 ACP server，审批体验更接近协议原生；web 驱动本地 dsh web agent 由网页端作为唯一写者；headless 是兼容旧版的子进程 fallback。新部署建议保持 sdk 或 acp。

上手难度

进阶 — 需要预先安装并配置好 dsh 与 DEEPSEEK_API_KEY，并在飞书开放平台创建 PersonalAgent 应用完成扫码绑定；但所有运行参数都可在 dsh Web 可视化设置页点选，绑定成功后即可在飞书里开聊。

已知问题与限制

• ACP 模式每次会话全新启动（上游协议限制，无法续跑）— README.md:403
• SDK 协议暂无 mid-turn cancel；/stop 会关闭对应 runtime 并自动重建 — README.md:403
• 飞书文档评论与富文本回复为规划中能力，尚未实现 — README.md:409
• 多机器人附加实例不支持 web adapter：共享 Web agent 事件流无法提供实例级 session 隔离，bot add 会拒绝 web — src/cli/commands/bot.ts:126
• 桥接引擎作为 dsh 插件在 dsh 进程内运行（嵌套 runtime 是有意取舍，用于按工作区隔离的 runtime 池与 scope 内并行 run）；唯一进程级例外是独立常驻的安全网守护
• 系统睡眠或断网期间 WebSocket 无法接收消息，恢复后才会补偿；ACP 适配器对图片出站返回不支持（默认输出占位说明，不会静默丢弃）— src/adapters/dsh/acp-adapter.ts:54

dsh-lark-bot

🌏 英文版：[README_EN.md](README_EN.md)

把 DeepSeek Harness 接入飞书

🌐 官网落地页 dsh-lark-bot.arr2018.dpdns.org · 备用 GitHub Pages

⚠️ 仅认准官方渠道： 唯一官方仓库 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/。

---

场景

你的 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 / 开发 / 文档等角色，每个角色独立人设、模型偏好与规则。
• 🤝 多机器人交接——“一个群，多个独立 Agent”：bot add 增加独立身份/服务/凭据/上下文的实例，可信机器人可在同群通过真实 @ 交接，连续协作有硬上限。
• ⚡ 并行多任务——“不用排队”：同一群聊同时跑多个任务、会话隔离；其他方案只能串行排队。
• 🧾 崩溃后可对账——“发出去了不是石沉大海”：消息先写持久任务账本再入队；重启恢复排队项，中断任务保留 checkpoint 并由 /jobs 显式重试。
• 🗂 会话归档与清理——“会话列表不会烂掉”：/archive 归档旧任务、/retention 配置自动保留策略。
• 📣 跨会话主动通知 + @人——“活干完了它会来找你”：A 群跑完任务主动推送到 B 群 / 私聊并 @ 你。
• ⚙️ dsh Web 可视化设置——“不用背环境变量”：在官方 Settings → Plugins 页面点选应用、工作目录、模型、并行数与提醒，并可直达诊断。
• 🔑 对话内管理模型和密钥——“不用离开飞书”：/providers /provider /key 直接查看、切换供应商、热更新密钥。
• 🎚️ 快速 / 平衡 / 深度模式——“任务强度一键选”：/mode 按 scope 持久选择，下一轮生效且不打断当前任务。
• 🧭 关键任务先拍板——“计划看清再动手”：完整计划先单独发出，再用卡片批准执行或附意见继续规划，原任务自动续跑。

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 发送普通消息即可开始工作，常用命令：

bot 自带的命令帮助、状态、错误提示与交互卡片均提供中文 / English。Card JSON 2.0 在各文本组件使用飞书原生 i18n_content，同一张群卡会按每位读者的客户端语言显示；无法取得读者语言的普通 Markdown、toast 与旧客户端降级路径同时显示中英文。agent 生成的回答、推理、工具输入输出和用户原文 保持原样，不自动翻译。

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

DSH session 消息级同步（web adapter）：发送 /session 只会列出当前 canonical workspace 的非 subagent session 元数据，不显示正文；选择后确认卡会列明标题、ID、workspace、更新时间、 回填数量、当前 scope，以及是否替换/独占迁移。只有确认后才发送有数量和字节双重上限的历史 transcript 卡并持久绑定。私聊允许已授权用户；member scope 仅本人；共享 group/topic 仅 profile 管理员；跨 scope 独占迁移也仅 profile 管理员。WebUI 或 dsh-TUI 的 open/resume/activity 永远不会 自动切换飞书绑定，也不会广播给所有 scope。绑定后，DSH session/event 是唯一真源：外部用户消息 镜像为带来源的 bot 消息，assistant chunk 节流更新同一张 bot-owned 卡，最终消息原位终态化；更新 失败才追加增量。bridge 以持久 seq cursor 重连补齐，并用 message ID / event seq / prompt rpcId 抑制飞书回显；tool/thinking 默认不投影。状态位于 profile 的 session-projections.json（0600），包含 路由、待确认历史水位/cursor、当前 turn 来源和消息映射；仅为跨重启续写流式卡保存其未终态正文， 不复制完整 transcript。历史确认完成前 live 事件保持串行等待，发送失败会在启动/重连时重试。 新投影卡使用稳定的飞书 uuid 幂等创建，覆盖发送成功但 cursor 尚未落盘时的崩溃重放。

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

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

会话状态卡：/status 展示工作区、有效模型、session、显式投影绑定/cursor、active runs、版本、上下文占用、 累计 input / output / cache token，以及待审批 / 待提问 / 待批准计划；点击“刷新”会原位更新同一张卡。 只展示 adapter 或模型目录明确提供的数据：ACP 可提供真实 context used / size 与累计 token， SDK 可提供每次模型调用的 token/cache 用量；上游未提供的字段显示“暂无”，不按文本长度估算。 累计用量随 scope 持久化；最近的 context 快照按 canonical provider/model 与 native session 分别保留， 并行 run 不会互相覆盖，当前身份不匹配时也不会复用旧占用值。会话与指标按 scope + workspace 持久化；/cd / /ws use 会中断原工作区仍在运行的任务，但不会删除其会话、指标或归档，切回即可 继续；只有 /new / /reset 清空当前 workspace。待处理卡与归档列表/清理也只统计当前 workspace。 成员 scope 的刷新只允许 owner 操作。

消息与任务可靠性：普通 agent 消息以飞书 messageId 去重，先原子写入 profile 的 jobs.json（0600）再进入内存队列。进程重启后，尚未开始的 queued 消息自动回到原 scope、thread 与 workspace；崩溃时已 running 的任务会转为 interrupted，保留最后安全阶段、run/native session 标识，但不会自动重复可能已有外部副作用的操作。用 /jobs 对账、/jobs show <消息ID> 查看，确认后 再 /jobs retry <消息ID>。/status 和重连提示会显示当前 workspace 的账本统计。保证范围从 bridge 已经收到并成功落盘开始；断网期间飞书从未投递给 bridge 的事件无法由本地账本恢复。 若首次落盘失败，bot 会明确回复“未接收/未执行，请重发”；若执行前 running receipt 失败，任务不会 启动，并明确落为 failed 或保留 queued 等待重启恢复。终态落盘失败也会提示对账；残留 running 会在 出站通道就绪后安全标为 interrupted，中断通知失败会跨启动继续投递。

群聊会话隔离：管理员可用 /isolation group|topic|member 在“整群共享 / 话题独立 / 成员独立”之间切换；默认 topic 保持既有行为。切换只改变后续消息的 scope 路由，不迁移或 删除已有会话，切回即可继续；切换前已发出的停止 / 审批 / 问答卡仍绑定原 scope，/stop 也会 覆盖当前成员可达的切换前 scope。成员模式的任务卡会显示发送者 open_id，避免误把别人的上下文 当成当前对话。策略持久化在 ~/.dsh-lark/profiles/<profile>/isolation.json。

多角色 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。

多机器人实例与 @ 交接：

dsh-lark-bot bot add reviewer --model gateway/review-model # 无凭据参数时扫码创建独立 PersonalAgent
dsh-lark-bot bot list
dsh-lark-bot bot status reviewer
dsh-lark-bot bot remove reviewer                       # 保留会话/工作树数据

每个实例使用独立的 bridge profile、dsh-lark-<name> profile、 ~/.dsh-lark/bots/<name>/dsh DSH_HOME、OS 用户服务、飞书与 provider 凭据、模型目录、 session/scope/worktree/archive；添加/移除不会重启其他实例。可在执行 bot add 时为当前进程设置 该实例专用的 DEEPSEEK_API_KEY；自定义 provider 凭据可在实例启动后通过 /key set 写入独立凭据库。 连接后，本机共享的 fleet.json 只把已登记 bot open_id 视为可信 peer。agent 获得 peer 的精确 open_id，可用 lark_notify 在当前群真实 @ 对方并附交接摘要；未知 bot、未 @、system/anonymous 消息不进入 agent， bot 发来的 /... 也只作为任务文本。共享 handoffs.json 对 messageId 去重并在全 fleet 统计连续 交接，默认 6 轮；任一新鲜真人消息（即使未 @）立即重置。成员隔离群中的 bot 交接使用该实例的 group/topic scope，避免生成无人可操作的 bot-owned 审批卡。额外实例由自己的 service 常驻；默认 guardian 仍只救援其配置的主实例。 default 主机器人不能通过 bot remove 删除，避免附加实例管理误伤既有机器人。 附加实例仅支持各自隔离 runtime 的 sdk / acp（以及 legacy headless）；bot add 与运行时都会 拒绝 web，因为共享 Web agent 的广播事件流无法提供实例级 session 隔离。

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

可配置主动提醒：Web 设置默认关闭、不刷屏，也可为未单独设置的会话选择“完成与失败”或“全部”。普通用户可用 /notifications on current 覆盖当前 scope，默认 @ 自己并在审批等待 10 分钟后只提醒一次；可用 events=、mentions=、remind= 调整。管理员还可把目标设为已登记的其他 scope|chatId。偏好原子持久化到 profile，重启不丢，并在 /status 显示；/notifications off 显式关闭，/notifications default 恢复 Web 默认值。

回复流量控制：默认保持即时逐条回复。profile 管理员或当前群的群主/群管理员可用 /replies set merge=5 batch=3 interval=10 dedupe=60 为当前 scope 开启 5 秒合并窗口、每条合并最多 3 个任务、两批至少间隔 10 秒，并在 60 秒内抑制同一发送者在同 workspace 的近似重复任务；超出批量上限的答案在 bridge 进程存活期间继续排队，不会因批量上限被丢弃。/replies 与 /status 显示有效策略，/replies default 恢复默认。

任务执行模式：发送 /mode 可用双语卡片选择 quick（快速：直接回答，只做必要检查）、balanced（平衡：兼顾速度与可靠性，默认）或 deep（深度：充分调查并验证假设与结果）；也可直接发送 /mode quick|balanced|deep，/effort 是等价别名。选择按隔离 scope 持久化并显示在 /status。每个 run 启动时固化模式，因此切换只影响下一轮，不会中断当前任务、清空上下文或绕过权限/计划审批。

结果文件直接回传：SDK / ACP / Web agent 可调用 lark_send_file，把当前会话 workspace、实际执行 worktree、当前 scope 归档或实例日志中的文件直接上传到原飞书聊天 / 话题；普通 /archive [note] 会在落盘后立即发送 Markdown + JSONL，失败时保留路径并可用 /archive send <id> [scope|chatId] 重试或由管理员转发到指定会话。上传只接受普通文件，默认单文件不超过 20 MiB；真实路径必须位于 bridge 计算的会话目录内，runtime 自报 cwd 不能扩大边界。

逐操作审批与 scope 权限策略：默认 SDK 与 Web 宿主在 tools/pre-execute 强制拦截高风险调用，并接入 dsh rc.8 官方 approval/request seam；ACP 走原生 session/request_permission。默认 ask 会弹出“允许执行一次 / 拒绝”卡。管理员可用 /permission allow 对当前隔离 scope 自动放行逐工具审批，或用 /permission deny 直接拒绝并向聊天给出明确反馈；/permission ask 恢复逐次询问。member 隔离下可从目标 /status 复制 scope，执行 /permission <策略> <scope>；只允许修改当前聊天内 scope。策略成功落盘后才确认，持久化到 profile 的 permission-policies.json（0600），重启不丢，且显示在 /status。该策略不绕过较大/高风险任务的计划门禁；legacy headless 不具备工具回调能力。

关键任务计划门禁：SDK / ACP / Web agent 在修改文件、运行脚本等较大或高风险动作前使用 lark_request_plan_approval；同一 turn 未获批准时，runtime pre-execute 策略会拒绝写入、删除、 移动、命令执行与 run_code。bridge 先把完整 Markdown 计划作为普通消息发出，再弹出“批准，开始执行 / 继续规划”决策卡；卡内可填写修改意见。工具在等待期间阻塞且暂停空闲超时，批准后原任务自动继续； 继续规划时 agent 会收到意见、修订计划并再次请求确认。门禁无固定十分钟截止，跟随所属 run 的取消 信号；停止任务会精确取消该 session 的 pending 卡并撤回。legacy headless adapter 不具备工具回调能力。

任务中向你提问（问答卡）：agent 需要你拍板、确认或补充信息时，通过 lark_ask_user 工具弹问答卡（单选 / 多选 / 自由文本）。可提交卡片，也可直接回复该卡片输入任意文字；单选/多选没有合适项时，回复文字就是补充答案。系统按被回复的 card messageId 精确匹配 pending 问题，回答后任务自动继续，等待期间运行超时看门狗暂停。（与 /ask 的“你主动提问”方向相反。）

计划、审批与问答卡提交后会立即显示成功提示、发送一条终态确认并撤回原卡，避免按钮仍停留在聊天中造成“未生效”的误解；确认或撤回失败不会影响已经提交给 agent 的决策、审批结果或答案。

安全网守护：独立于 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。

正常引擎后台服务（issue #23）：安装仍只有 setup 这一条路径；如需登录后自动运行、退出终端 仍在线，可再用一条命令把同一个标准 dsh profile 交给系统用户服务托管（不会启动第二套桥接引擎）：

dsh-lark-bot service install --profile dsh-lark
dsh-lark-bot service status --profile dsh-lark
dsh-lark-bot service logs --profile dsh-lark -n 200 -f
dsh-lark-bot service restart --profile dsh-lark
dsh-lark-bot service stop --profile dsh-lark
dsh-lark-bot service start --profile dsh-lark
dsh-lark-bot service uninstall --profile dsh-lark

Linux 优先使用 systemd user unit，无 user systemd 时回退 XDG supervisor；macOS 使用 LaunchAgent， Windows 使用登录计划任务。服务异常退出会自动重启，doctor 会报告已安装服务的状态。guardian 发现正常引擎掉线时会优先重启该受管服务，避免重复拉起；upgrade --restart 也走同一路径。 stop / uninstall 会持久记录“期望停止”，guardian 不会擅自拉起；install/start 若检测到同 profile 的前台进程会拒绝并提示先停止，生命周期锁阻止并发双启动。 机器睡眠或断网期间 WebSocket 无法收消息；恢复后 SDK 自动重连，并向最近活跃会话发送恢复提示。

模型 / Provider / 凭据管理

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

• 交互式管理卡片：/providers（或 /provider、/model、/key）打开管理卡片；当前模型带 ✅ 标记，可直接点选其他模型或“恢复默认”，下一轮生效且保留上下文。增删改查按 BotFather 式的多轮向导完成——能选择的用按钮点选（API 协议、provider、模型、凭据引用）， 需要填值的用卡片输入（ID、Base URL、模型列表、密钥值），写入前有确认卡，随时可取消。
• /model use <provider/model>：按会话精确路由并热切换模型（也兼容唯一模型 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 链接重指到新版本，并当场幂等重装版本陈旧的 SDK server / ACP 依赖。

无需交互确认时加 --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。

---

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 Web 可视化设置、对话内模型 / 密钥管理、执行模式与关键任务计划门禁十一项合一；标准 dsh profile bundle，setup 是唯一安装路径；可选 service install 只负责把同一 profile 交给 OS 常驻，不是第二套运行时。

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.8（最后验证 2026-08-20：临时安装 + SDK JSON-RPC / ACP runtime initialize、工具/审批、live session 续接与 restart collision 探针），通过官方 @deepseek-ai/dsh-sdk-client / @deepseek-ai/dsh-acp 接入； 具体锁定版本、升级政策与自动化探测见 docs/COMPATIBILITY.md， adapter 接入细节见 docs/adapter-notes.md，rc.8 差异、已知风险和 自动/人工验证边界见 docs/DSH_RC8_AUDIT.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 Web 可视化设置（推荐）

打开本机 dsh Web，进入 Settings → Plugins → Plugin configuration → dsh-lark-bot。页面可直接查看和修改服务区域、App ID、App Secret、默认项目文件夹、默认模型、每会话并行任务数、adapter 与默认提醒策略：

• App Secret 标记为 secret，只能写入，Web 响应、卡片和日志都不会回显；扫码绑定后实际生效的 profile 会作为页面初始值，App ID 不会错误显示为空。

• 点击“保存设置”后，凭据、区域、工作目录和 adapter 会安全停止旧 generation 后自动重连；模型、并行数和提醒会热更新到下一任务/提醒，不中断正在执行的任务，页面逐项标明时机。

• “快速诊断”可在本页直接检查设置连接、App ID、工作目录、模型和远程只读状态；需要运行态详情时可继续复制 /status 或 /doctor 到飞书会话。

• 浏览器半侧由本包的 ./client 动态加载并注册到官方插件配置页，不需要 fork 或重建 dsh Web。没有 Web 设置服务时，现有飞书命令和下列环境变量仍可使用。

• 本地配置：~/.dsh-lark/config.json

• 状态根目录可用 DSH_LARK_HOME 覆盖

• 环境变量统一使用 DSH_LARK_* 前缀

• 模板见 .env.example

• 敏感项：DSH_LARK_APP_SECRET、DEEPSEEK_API_KEY 等凭据只保存在本机配置 / 环境中，日志与 卡片自动脱敏，仓库只提交 .env.example 模板。

会话运行在 Git 仓库中时，会自动在 ~/.dsh-lark/profiles/<profile>/worktrees/<scope-slug>-<path-hash>/ 创建隔离 worktree，并复制项目级 AGENTS.md。升级时会先从 Git registry 核验旧版 <scope-slug> worktree 的 owning repo：会话与旧 retention 归档归回真实项目，匹配时原位迁移并保留分支与未提交文件；当前指针已切到其他项目时则保留旧树并为新项目独立建树。

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

当前核心环境变量：

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

权限与数据

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

• 飞书凭据：PersonalAgent 应用的 app_id / app_secret，明文写入本机 ~/.dsh-lark/config.json（文件权限 600）。
• 多机器人身份与消息：fleet.json（0600）保存实例名、dsh/bridge profile、独立 DSH_HOME、bot open_id/名称，不保存密钥； handoffs.json（0600）保存 chat id、最近交接 message id 与轮数。只有已登记 peer 的真实 @ 消息会进入 agent；已登记 peer 的 name/open_id 会注入每轮 agent prompt 并随任务上下文发送给模型 provider， 以便生成精确 @ 交接。交接提示、卡片和回复仍发送到共享群，对群成员可见。移除实例会删除其 飞书配置凭据、独立 .credentials.yaml 与 service env；DSH_HOME 中的 provider 设置/runtime session 默认保留以便恢复， 默认保留 profiles/<name>/ 会话/工作树；需要删除这些数据时由用户另行处理。
• 文件系统：读取 / 写入你通过 /cd、/ws 指定的工作目录（含执行 shell 命令、修改文件）。
• 网络：向飞书开放平台建立 WebSocket 出站长连接收发消息；向 DeepSeek API 发送任务上下文。
• 群消息与可选历史：为识别“直接回复问答卡”，群实时事件先进入 bridge，再由 bridge 忽略未 @ 且未命中 pending 卡的消息。仅当 DSH_LARK_GROUP_NO_AT=true 时，实时无 @ 消息会进入任务管线，并轮询曾经通过事件登记的群聊 / 话题；两条路径都只处理白名单真人消息（及可选群白名单），历史消息还须为启动后的未删除消息，并与实时事件按 message ID 去重。该模式需管理员授予 im:message.group_msg 权限并确认符合团队隐私政策。
• 成员隔离标识与群可见性：member 模式把发送者 open_id 写入本机 isolation.json 派生的 session / scope directory / worktree / archive 索引或路径，并显示在共享群任务卡。它只隔离 agent 上下文，不隐藏群消息：输入、进度卡与回复仍对群成员可见；其他成员不能操作该成员的任务卡。
• 本地会话用量：adapter 上报的 input/output/cache token 与 context used/limit 随 scope 写入 ~/.dsh-lark/profiles/<profile>/sessions.json（0600），并显示在 /status 卡；成员 scope 仅 owner 可刷新，但群内已经发送的状态卡仍遵循共享群消息可见性。
• 诊断包：管理员可在会话发送 /doctor，bridge 在内存中生成 Markdown 文件并上传到原聊天 / 话题；包含版本、平台、非敏感配置计数、当前 workspace 的运行/pending/任务账本摘要、服务状态与 当前 bridge 进程内有界最近结构化事件（不读取 dsh 宿主共享 stdout）。不包含 App ID/Secret、凭据值、消息正文或 session transcript；常见密钥形态、 当前进程已知敏感环境值及主目录会再次脱敏。文件一旦发到群中即对群成员可见，建议在私聊生成并在 转发前人工复核。生成等待有超时边界，底层服务命令也会被有界终止；上传等待超时时会明确提示 结果未知及文件可能迟到，避免用户立即重试造成重复投递。
• 持久任务账本：profiles/<profile>/jobs.json（0600）保存 bridge 已接收任务的原始消息正文、 附件/提及元数据、chat/thread/scope、workspace、状态与安全 checkpoint，最多保留 500 条终态记录。 /jobs 输出会脱敏并按当前 scope + workspace 隔离；文件内容与 sessions.json 一样可能包含用户在 prompt 中主动提供的敏感文本，应保护 profile 目录并在分享前清理。账本不保存隐藏推理或工具参数。
• scope 路由：scopes.json 保存 chat/thread 与最近入站 messageId；messageId 仅用于把 agent 后续问答卡作为 reply 正确发回原话题。
• 本地回调：运行 lark_notify、lark_send_file、lark_ask_user、lark_request_plan_approval 或逐工具审批时，dsh runtime 子进程通过 127.0.0.1 随机端口 + 每启动随机 token 回调 bridge 进程（仅本机回环， 不监听公网）；计划内容、待执行工具的理由/参数与决策卡会发送到当前飞书 / Lark 会话。群聊中的审批内容对群成员可见。
• 进程：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 子进程提供实时流式事件。
• 正常引擎后台服务（可选）：service install 将标准 dsh --profile <name> 交给当前用户的 systemd / launchd / Windows 计划任务托管。服务环境只按白名单快照到 ~/.dsh-lark/service/<profile>.env（POSIX 0600；Windows owner-only ACL）；plist / 计划任务不嵌入密钥。日志写入 profiles/<profile>/logs/service.log。service uninstall 删除系统入口与 env 快照，但保留配置、会话与日志。

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

排障

先运行 dsh-lark-bot doctor，它会检查 profile、工作目录，并对当前 adapter 做真实可用性探测 （sdk / acp / headless 对应 runtime 的初始化握手）；启用无 @ 群消息后，还会使用一个已登记群聊探测历史消息权限。 无法接触终端时，管理员可直接在飞书发送 /doctor 获取可下载的脱敏诊断包；聊天版为运行态快照， 不会另起 adapter 做破坏性探测，终端版仍是完整可用性检查。

常见问题：

• bot 静默 / 长连接失败：运行 service status 并查看 service logs -f（前台运行则看 stderr），关注 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 [email protected]）；~/.dsh-lark 状态独立于插件 本体，升级 / 回滚不会丢失配置与会话。

开发

dsh-TUI 兼容边界：本包以唯一根 dsh-plugin.json 声明 v0.15 host facet，并在构建后运行 pnpm check:tui-admission 与真实 PTY pnpm check:tui-tty。可选 TUI seam 缺失时安全 no-op；同步 仍只依赖 DSH history/event，不监听 TUI input/session switch。该 facet 为 trusted-in-process， 不是安全沙箱。项目继续采用 GNU AGPLv3；生态 listing 不改变许可证，也不代表兼容认证、安全审查 或官方背书。

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，验证 SDK/ACP 握手及 SDK 工具/续接
pnpm dsh:upstream    # 对比 npm 上游 stable 与锁定矩阵
pnpm security:monitor # 假冒仓库与仿冒包监控（建议每周）

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

贡献：欢迎 Issue 与 PR。开发流程见 AGENTS.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 自动发布两个 npm 包并创建 Release。

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

维护与支持

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

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

作者

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

贡献者

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

说明：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。

文档

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

架构

详见 docs/ARCHITECTURE.md。

飞书 / Lark ──WebSocket 长连接──▶ bridge/ ──▶ session/ ──▶ workspace/ ──▶ adapters/ ──▶ dsh ──▶ DeepSeek V4

核心思路：飞书通道与 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 并交还通道。

目录结构

路线图

见 docs/roadmap.md。

参考项目

社区收录情况

本项目的社区收录 / 推荐状态，随提交的更新请求持续维护。截至 v0.15.9（2026-08-20 复核）：

更新请求进度（截至 2026-08-20 复核）：

• awesome-dsh-plugins 收录条目 v0.8.0：#127 — ✅ 已合并；榜单行同步：#139 — ✅ 已关闭
• awesome-dsh-plugin 大榜收录：#1408 — 📨 已提交（2026-08-17，v0.15.0 数据；v0.15.1 跟进评论 已提交）
• dshfind 条目名称修正 + v0.8.0 刷新：#2 — ✅ 已关闭；v0.10.1 刷新：#6 — 📨 待处理（v0.15.1 跟进评论 已提交）
• dsh-plugin.org 官方源收录与寄生条目下架：收录申请 #1 / 安全举报 #2 — ✅ 维护者已处理并关闭；官方详情页与专题教程已上线
• omdsh-dev/community 收录：Discussion #11 — ✅ 通过，讨论活跃（最新更新说明 v0.10.2）；v0.15.1 更新说明 — 📨 已备妥，待人工粘贴
• 平台数据刷新（v0.14.0 → v0.15.1）— ✅ 已恢复提交（2026-08-17）：awesome-dsh-plugins PR #230 · dshfind #6 跟进 · omdsh 说明备妥

历史亮点跟进（当时六项独家能力与 issue #6 设计实现；当前能力见上方十一项清单）：

• awesome-dsh-plugins 榜单行同步（仓库描述 → 最新）与 agent-test 报告名称异常：#139 — 📨 已提交（维护方已确认，等待渲染周期同步）
• dshfind 详情页补「对话内管理模型和密钥」亮点：#2 跟进评论 — 📨 已提交
• omdsh 当时六项独家亮点补充（含 Guardian 设计实现）：Discussion #11 亮点评论 — 📨 已提交

假冒仓库警告

2026-08-17 发现假冒仓库 tarraencompassing61/dsh-lark-bot：非 fork 重新上传、114 个 commit 中 113 个作者为 PlutoKeating、删除全部 CI、关闭 Issues、Releases 为 0，却以“下载 Windows exe 双击运行”的 SEO 诱饵 README 冒充官方分发。本项目从不提供 exe，任何此类下载均为假冒 / 恶意来源。

取证存档：docs/security/2026-08-17-impostor-repo-evidence/ · 官方下载渠道：docs/DOWNLOAD.md · 持续监控：pnpm security:monitor

免责声明

本项目为非官方社区工具，与 DeepSeek、字节跳动 / 飞书（Lark）无关联，亦未获得其背书。DeepSeek Harness、Feishu / Lark 及相关商标归各自权利人所有。