dsh-lark-bot

3. 基本使用 | Basic usage

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

Just send a normal message to the bot in Feishu to get started. Common commands:

命令 Command	作用 Description
/new /reset	开始新会话
Start a new session
/newg	自动新建群聊（拉你入群）并开新会话，当前会话保留
Auto-create a group chat (with you invited) and start a fresh session there; the current session is untouched
`/cd
`	切换工作目录并重置会话
Change working directory and reset the session
/ws list	查看命名工作空间
List named workspaces
/ws save	保存当前工作空间
Save the current workspace
/ws use	切换到命名工作空间
Switch to a named workspace
/ws remove	删除命名工作空间
Remove a named workspace
/status	查看当前状态
Show current status
/resume	查看当前会话最近上下文
Show the session's recent context
/stop	终止当前任务
Stop the current task
/timeout [N|off|default]	查看或设置当前会话运行超时
View or set the current session run timeout
/concurrency [N|default]	查看或设置当前 scope 并行任务数（默认 2）
View or set the concurrent-run limit for this scope (default 2)
/role list、/role show	查看角色列表 / 详情
List roles / show a role
/role set 、/role clear	为当前 scope 绑定 / 解除角色
Bind / unbind a role for this scope
/role save [--persona 文案] [--model ] [--tools ] [--rules 文案]	创建 / 更新角色（管理员）
Create / update a role (admin)
/role remove	删除角色（管理员）
Remove a role (admin)
/notify	跨会话发送通知（管理员）
Push a cross-session notification (admin)
/notify list	查看 bridge 已注册的 scope
List scopes known to the bridge
/retention [N|default]	查看或设置保留消息条数（超出自动归档）
View or set the live message retention window (overflow is archived)
/archive [note]、/archive list [N]、/archive clean	手动归档 / 查看 / 清理会话记录
Archive / list / clean session transcripts
/density [compact|standard|detailed]	查看或设置卡片密度
View or set card density
/model	查看当前模型、dsh 默认模型与可用模型列表
View current model, dsh default model and available models
/model use	热切换当前会话模型（下一轮生效，无需重启）
Hot-switch the current session model (effective next message, no restart)
/model default	写入 dsh 默认模型 agent-default-model（管理员）
Write the dsh default model agent-default-model (admin)
`/model add|remove
`	添加 / 删除 provider 的模型（管理员）
Add / remove a provider model (admin)
/providers	查看 dsh 已配置 providers、模型与凭据状态
View configured dsh providers, models and credential status
/provider add|update|remove	管理 provider（管理员；deepseek-official 与自定义 pi-ai）
Manage providers (admin; deepseek-official and custom pi-ai)
/key set|remove|list	管理 dsh 凭据（set / remove 需管理员）
Manage dsh credentials (set / remove require admin)
/ask	发送问答卡，回答写入会话上下文
Send a Q&A card; the answer is written back to session context
/invite user|admin|group 、/invite list、/invite remove user|group	管理访问白名单
Manage the access allowlist
/help	查看帮助
Show help

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

Images in Feishu messages are downloaded to the local media directory and passed to dsh; text files are read and their content is injected into the task context.

/newg ：通过飞书 API 自动新建一个私密群、把发送者拉入群，并回复群链接——在新群里发消息即为新 scope / 新会话，当前会话不受影响。需要应用具备 im:chat 与 im:chat.members:write_only 权限（在开发者后台「权限管理」申请）。

/newg : auto-creates a private group via the Feishu API, invites the sender, and replies with a group link — chatting in the new group starts a fresh scope/session while the current session is untouched. Requires the im:chat and im:chat.members:write_only scopes (apply in the developer console).

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

Each scope (DM / group / topic) runs up to 2 tasks in parallel by default (adjust with DSH_LARK_SCOPE_CONCURRENCY or /concurrency): successive messages become independent runs, each with its own dsh session and run id. /status lists every active run and /stop interrupts them all.

多角色 Agent：管理员用 /role save --persona [--model ] [--tools ] [--rules ] 定义 PM / 开发 / 文档等角色（persona、模型偏好、工具指引、角色规则）， /role set 把角色绑定到当前 scope：下一轮起该 scope 的每个 run 都携带角色 persona 与 规则，并优先使用角色模型（角色模型
--persona [--model ] [--tools ] [--rules ]— persona, model preference, tool guidance and role rules — then bind one to the current scope with/role set . Every run in that scope carries the role instructions, and the role model wins below the per-session /model useoverride. Role definitions persist in~/.dsh-lark/profiles/ /roles.json`.

出站 @ 提及与跨会话通知：bridge 出站契约支持 mentions（@ 提及）与跨 chat/thread 发送； /notify 可向其他会话推送汇报（管理员）。agent 侧还内置 lark_notify dsh 工具（SDK / ACP 两种 runtime 均可装配）：agent 完成任务后可主动向其他群 / 话题发消息并 @ 指定成员，桥接进程通过 127.0.0.1 本地回调端口 + 随机 token 校验，不暴露公网。

任务中向你提问（问答卡）：agent 需要你拍板、确认或补充缺失信息时，会通过 lark_ask_user 工具主动向当前会话弹一张问答卡（单选 / 多选 / 自由文本）， 你回答后任务自动继续——无需额外命令。问答卡等待期间任务不会被运行超时打断。 （与 /ask 的“你主动发结构化问题”方向相反：这是 agent 主动来问你。）

Outbound mentions & cross-session notify: the outbound contract supports mentions and cross-chat/thread sends; /notify pushes a report to another session (admin). The agent also gets a built-in lark_notify dsh tool (wired into both SDK and ACP runtime profiles): after a task finishes it can push messages to other groups/topics and @mention members. The bridge listens on 127.0.0.1 with a random per-boot token — nothing is exposed to the public network.

Mid-task questions (question cards): when the agent needs a decision, confirmation, or missing information, it proactively sends a question card to the current chat via the lark_ask_user tool (single choice / multi choice / free text) and resumes automatically once you answer — no extra command needed. The run-timeout watchdog pauses while a card is waiting. (This is the opposite direction of /ask, which is you asking the agent.)

安全网守护（Safe-mode guardian）：默认随 setup 一起安装的、独立于 dsh 进程、系统级常驻的 最小守护进程（Linux systemd user unit / macOS LaunchAgent / Windows 启动项）。dsh 正常运行时守护保持静默； 一旦 dsh 进程下线或无法 boot（例如某个第三方插件破坏了整个 profile 组合），守护自动接管飞书 通道，用户无需接触命令行即可发送控制信号自救：

• /safemode：进入仅核心安全模式——守护创建 ~/.dsh/profiles/ -safe（仅 dsh-base + dsh-headless 两个官方核心 bundle，不加载任何第三方插件），后续消息经 守护转发给该核心 dsh 逐条对话，配合代码执行能力定位 / 修复 / 禁用损坏插件；安全模式优先使用 官方 SDK 流式引擎（实时思考 / 工具调用 / web search / 打字机式文字输出，与正常模式同一张 流式卡），SDK runtime 不可用时自动回退 headless（任务期间卡片仍实时显示“正在思考 / 已运行 Ns / 无响应 Ns”活动状态）；
• /safemode plugins：列出故障 profile 已安装的插件清单（自愈诊断）；
• /safemode status：查看守护 / dsh / 安全模式状态；
• /safemode stop：终止当前正在运行的安全模式任务（也可点击任务卡片上的 ⏹ 按钮）；
• /safemode exit：退出安全模式，守护重启完整 profile 并把飞书通道交还给正常形态；

安全模式任务有空闲超时（DSH_LARK_GUARDIAN_SAFE_TIMEOUT_MS，默认 10 分钟：任务持续无 活动事件才被终止，活跃的流式任务不会被误杀），超时或失败都会在卡片上给出明确终态，不会无声 挂起。全程不需要命令行；dsh 恢复后守护自动断开并回归静默。安装：

## 配置 | Configuration

- 本地配置：`~/.dsh-lark/config.json`
- 状态根目录可用 `DSH_LARK_HOME` 覆盖
- 环境变量统一使用 `DSH_LARK_*` 前缀
- 模板见 [`.env.example`](https://github.com/PlutoKeating/dsh-lark-bot/blob/ce4a68c5c9adf9359ad0d943012480e3a3407be6/.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`](https://github.com/PlutoKeating/dsh-lark-bot/blob/ce4a68c5c9adf9359ad0d943012480e3a3407be6/.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/
/worktrees//` 创建隔离 worktree，并复制项目级 `AGENTS.md`。

When the session runs inside a Git repository, an isolated worktree is created at
`~/.dsh-lark/profiles/
/worktrees//` and a project-level `AGENTS.md` is copied in.

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

Each Feishu scope keeps the last 40 conversation messages by default (adjustable with
`/retention` or `DSH_LARK_RETENTION_MSGS`); messages beyond the retention window are archived to
`~/.dsh-lark/profiles/
/archives/` (Markdown + JSONL inside a Git repository, one commit
per archive), and `/archive` exports the full session on demand. The SDK mode continues the native
dsh session, while headless mode approximates memory by injecting history into the next prompt.

当前核心环境变量：

Core environment variables:

| 变量 Variable | 默认值 Default | 说明 Description |
| :--- | :--- | :--- |
| `DSH_LARK_HOME` | `~/.dsh-lark` | 本地状态根目录
Local state root directory |
| `DSH_LARK_TENANT` | `feishu` | `feishu` 或 `lark`
`feishu` or `lark` |
| `DSH_LARK_WORKSPACE` | 未设置 | 新会话默认工作目录
Default working directory for new sessions |
| `DSH_LARK_DSH_COMMAND` | `自动发现` | dsh 启动命令；通常无需设置
dsh launch command; usually not needed |
| `DSH_LARK_DSH_ARGS` | `自动发现` | dsh 启动参数，逗号分隔；通常无需设置
dsh launch args, comma-separated; usually not needed |
| `DSH_LARK_ADAPTER` | `sdk` | `sdk`（默认）/ `acp`（审批）/ `headless`（legacy）/ `web`（本地 dsh web agent，单写者）
`sdk` (default) / `acp` (approval) / `headless` (legacy) / `web` (local dsh web agent, single writer) |
| `DSH_LARK_PROVIDER` | `deepseek-official` | 模型 provider
Model provider |
| `DSH_LARK_MODEL` | `deepseek-v4-flash` | 默认模型
Default model |
| `DSH_LARK_MAX_TOKENS` | 未设置 | SDK agent 每请求输出 token 上限
Per-request output token cap for SDK agents |
| `DSH_LARK_WEB_URL` | `http://127.0.0.1:3080` | `web` 适配器：本地 dsh web agent 的 base URL
`web` adapter: base URL of the local dsh web agent |
| `DSH_LARK_WEB_PUSH` | `true` | `web` 适配器：网页端回合完成时推送到飞书并自动切换会话映射（`0` 关闭）
`web` adapter: push web-GUI turn completions to Feishu and auto-switch the chat mapping (`0` disables) |
| `DSH_LARK_ACCESS_DEFAULT_DENY` | `false` | 无白名单时拒绝私聊
Reject private chats when no allowlist is configured |
| `DSH_LARK_EVENT_FRESHNESS_MS` | `600000` | 过期消息拒绝窗口（0 关闭）
Stale-message rejection window (0 disables) |
| `DSH_LARK_RUN_TIMEOUT_MS` | `300000` | 单次运行空闲超时：持续无活动事件才终止（活跃任务不会被误杀）
Idle timeout for a single run: stops only after the run has been silent for this long |
| `DSH_LARK_STOP_GRACE_MS` | `5000` | SIGTERM 后等待优雅退出再 SIGKILL 的宽限期
Grace period after SIGTERM before SIGKILL |
| `DSH_LARK_SCOPE_CONCURRENCY` | `2` | 每个 scope 的并行任务数（1=严格串行）
Concurrent runs per scope (1 = strictly serial) |
| `DSH_LARK_RETENTION_MSGS` | `40` | 每个 scope 保留的消息条数（0=全部保留）
Messages kept per scope (0 keeps everything) |
| `DSH_LARK_ARCHIVE_MAX` | `50` | 每个 scope 最多保留的归档数（0=不清理）
Max archives kept per scope (0 disables pruning) |
| `DSH_LARK_ARCHIVE_MAX_AGE_DAYS` | `90` | 归档最大保留天数（0=不清理）
Max archive age in days (0 disables pruning) |
| `DSH_LARK_HEARTBEAT_MS` | `5000` | 桥接引擎心跳写入间隔（守护存活信号）
Bridge heartbeat write interval (guardian liveness signal) |
| `DSH_LARK_GUARDIAN_DISABLED` | `false` | `1` 时安全网守护进程保持停止
`1` keeps the safety-net guardian stopped |
| `DSH_LARK_GUARDIAN_PROFILE` | `dsh-lark` | 守护监视 / 重启的 dsh profile（首次安装时写入状态）
dsh profile the guardian watches / relaunches (persisted on install) |
| `DSH_LARK_GUARDIAN_BRIDGE_PROFILE` | `default` | 提供飞书凭据与白名单的桥接状态 profile
Bridge state profile providing Feishu credentials / allowlist |
| `DSH_LARK_GUARDIAN_POLL_MS` | `2000` | 守护看门狗轮询间隔
Guardian watchdog poll interval |
| `DSH_LARK_GUARDIAN_STALE_MS` | `15000` | 心跳超时阈值，超过且无 dsh 进程则接管飞书通道
Heartbeat staleness threshold before channel takeover |
| `DSH_LARK_GUARDIAN_ENGINE_DEAD_MS` | `120000` | dsh 进程存活但心跳持续超时该时长，判定桥接引擎已死并接管
Live dsh process with heartbeat stale this long is treated as engine-dead (takeover) |
| `DSH_LARK_GUARDIAN_SAFE_ADAPTER` | `auto` | 安全模式引擎：`auto` 优先 SDK 流式、失败回退 headless；`sdk` 强制 SDK；`headless` 跳过预置
Safe-mode engine: `auto` tries the SDK streaming runtime then falls back to headless; `sdk` requires it; `headless` skips provisioning |
| `DSH_LARK_GUARDIAN_SAFE_TIMEOUT_MS` | `600000` | 安全模式单任务空闲超时（持续无活动事件才停止并出超时卡）
Safe-mode per-task idle timeout (stops the run after it has been silent this long and renders a timeout card) |
| `DSH_LARK_GUARDIAN_CARD_DENSITY` | `detailed` | 安全模式任务卡片密度（compact / standard / detailed）
Card density for safe-mode run cards |
| `DSH_LARK_UPGRADE_REGISTRY` | `https://registry.npmjs.org` | `upgrade` 探测最新版本的 npm registry（可指向镜像）
npm registry used by `upgrade` to discover the latest version (mirrors supported) |
| `DSH_LARK_UPGRADE_CHECK` | `1` | `doctor` / `/version` 是否探测 npm 最新版本（`0` 关闭，best-effort）
Whether `doctor` / `/version` probe npm latest (`0` disables; best-effort) |
| `DSH_LARK_UPGRADE_CHECK_INTERVAL_MS` | `21600000` | 桥接引擎检查新版本的间隔（`0` 关闭，默认 6h）
Bridge new-version check interval (`0` disables; default 6h) |
| `DSH_LARK_UPGRADE_NOTIFY` | `false` | `true` 时发现新版本向指定 chat 推送飞书通知（默认仅日志）
Push a Feishu notification to the target chat when a newer version is found (default: log-only) |
| `DSH_LARK_UPGRADE_NOTIFY_CHAT` | — | 接收更新通知的 chat id（配合 `DSH_LARK_UPGRADE_NOTIFY=true`）
Chat receiving update notifications (with `DSH_LARK_UPGRADE_NOTIFY=true`) |

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

On startup the bot auto-discovers common local `@deepseek-ai/dsh` installations. Set these two
variables only when auto-discovery fails or a special profile is required.