# 用户手册 · User Manual > 面向普通用户和运维者的完整使用手册。 > Complete manual for end users and operators. ## 1. 安装 · Installation 唯一安装路径（标准 dsh profile bundle）： ```bash npx dsh-lark-bot@latest setup --profile dsh-lark ``` `setup` 自动完成：定位本机 dsh → 预批准 pnpm 构建策略 → 执行标准 `dsh plugin --profile dsh-lark add dsh-lark-bot`。安装后包名 `dsh-lark-bot` / `dsh-feishu-bot` 内容一致，`dsh-lark-bot --version` 可查看版本。 ### 1.1 升级 · Upgrade（v0.12.0+） **完全不接触命令行：** profile 管理员在飞书发送 `/upgrade`。有新版本时点击只允许发起人操作的 确认卡，Guardian 会安装卡片中确认的精确 npm 版本、修复 runtime profiles、重启并验证，然后回到 原 chat/thread 报告结果。升级 worker 使用 0700 中立工作目录和按请求隔离的 npm cache，不受当前 工作目录或 `~/.npm` 历史权限损坏影响；失败时只显示脱敏的可行动类别。取消不会更改任何内容。重载可能中断正在执行的任务，但配置、会话、归档 和凭据保留。每次 `/new` / `/reset` 也会检查一次 npm，只有发现更新才追加一条简短文本提醒。 **一行命令彻底升级（包本体 + guardian + 升级后验证）：** ```bash npx dsh-lark-bot@latest upgrade --profile dsh-lark --yes ``` - 默认不打断运行中的 dsh profile（只提示重启命令；配置 / 会话 / 凭据不受影响）； - `--check`：只报告已装 / 运行中 CLI / npm 最新版本与进程状态，零改动； - `--restart`：升级后自动重启 guardian 服务，并重启受管 / 后台的 dsh profile 进程； - `--rollback`：回滚到上次升级前版本（记录在 `~/.dsh-lark/upgrade-state.json`）； - `--force`：npm 不可达（离线）时按当前运行版本重装； - `--no-guardian`：跳过守护升级； - **runtime profile 一致性修复**：自动把 `dsh-lark-sdk` / `dsh-lark-acp` 的 own-package 链接重指到新版本，并当场幂等重装版本陈旧的 SDK server / ACP 依赖； - 非交互环境不带 `--yes` 会安全中止（不产生任何变更）。 未使用 `--restart` 时，升级后手动重启 profile 使新版本生效： ```bash dsh --profile dsh-lark ``` ## 2. 启动与首次扫码 · Start & first scan ```bash dsh --profile dsh-lark ``` 首次启动（无凭据时）在终端显示二维码，用飞书 / Lark App 扫码，选择或创建 PersonalAgent 应用。绑定后 `dsh-lark-bot/plugin` 在 dsh 进程内运行桥接引擎（飞书通道 / 会话工作区 / 卡片 / 通知回调）。桥接仍只在 dsh 宿主内运行；如需后台常驻，使用可选 OS 托管： ```bash dsh-lark-bot service install --profile dsh-lark dsh-lark-bot service status --profile dsh-lark dsh-lark-bot service logs --profile dsh-lark -f ``` 另有 `start|stop|restart|uninstall`。stop 保留登录自启入口，uninstall 删除入口与私有 env 快照， 但不删配置、会话、日志。异常退出由系统自动重启；guardian 与 `upgrade --restart` 会优先操作受管服务防双实例。 停止意图持久写入 `service/.intent.json`，因此 guardian 不会撤销显式 stop/uninstall； install/start 会拒绝同 profile 的既有前台进程，并以生命周期锁避免并发双启动。 机器睡眠 / 断网期间不能接收新消息，恢复后会自动重连并向最近活跃会话提示。 已拥有应用时，可跳过扫码： ```bash DSH_LARK_APP_ID=cli_xxx DSH_LARK_APP_SECRET= DSH_LARK_TENANT=feishu \ dsh --profile dsh-lark ``` ## 3. 卸载 · Uninstall ```bash dsh plugin --profile dsh-lark remove dsh-lark-bot ``` ## 4. 飞书内命令 · In-chat commands 命令帮助、状态/错误提示和 bot 自有卡片文案均提供中文 / English。支持 Card JSON 2.0 国际化的客户端 会按每位读者的语言显示同一张共享卡；普通 Markdown、toast 和旧客户端降级因服务端拿不到读者 locale， 会并列显示中英文。agent 生成的正文、推理、工具内容与用户输入保持原文，不做自动翻译。 | 命令 | 作用 | | --- | --- | | `/new` `/reset` | 清空当前会话 | | `/cd ` | 切换工作目录 | | `/ws list` | 查看工作空间导航卡片 | | `/ws save ` | 保存当前工作空间 | | `/ws use ` | 切换到命名工作空间 | | `/ws remove ` | 删除命名工作空间 | | `/status` | 查看并原位刷新 scope / cwd / 模型 / session / run / context / token / pending / 任务账本 | | `/version` | 查看当前版本与 npm 最新版本 | | `/upgrade` | 检查并通过 owner-bound 卡确认 Guardian 后台更新和重载（profile 管理员） | | `/doctor` | 管理员生成脱敏诊断 Markdown 文件并上传到原聊天/话题 | | `/jobs [list\|show <消息ID>\|retry <消息ID>]` | 对账任务状态、查看 checkpoint、确认后重试中断/失败任务 | | `/resume` | 查看最近上下文 | | `/session`、`/session bind `、`/session current` | 浏览当前 workspace 的 DSH session，经披露确认后显式绑定 / 查看当前绑定（仅 `web` adapter） | | `/stop` | 终止当前任务 | | `/timeout [N\|off\|default]` | 查看或设置运行超时 | | `/concurrency [N\|default]` | 查看或设置当前 scope 的并行任务数 | | `/permission [ask\|allow\|deny] [scope]` | 查看或设置工具权限策略（管理员可指定当前聊天内 scope） | | `/isolation [group\|topic\|member]` | 查看或设置本群会话隔离（设置仅管理员） | | `/role list` | 查看角色列表与当前 scope 绑定 | | `/role show ` | 查看角色详情 | | `/role set ` | 为当前 scope 绑定角色（下一轮生效） | | `/role clear` | 解除当前 scope 的角色绑定 | | `/role save [--persona ..] [--model ..] [--tools ..] [--rules ..]` | 创建 / 更新角色（管理员） | | `/role remove ` | 删除角色（管理员） | | `/notify ` | 向其他会话推送通知（管理员） | | `/notify list` | 查看 bridge 已注册的 scope | | `/notifications [show\|off\|default\|on …]` | 查看、关闭、恢复 Web 默认或开启当前 scope 的主动提醒（支持 `sinks=`） | | `/channels [list\|show\|add\|accept\|remove\|enable\|disable …]` | 管理出站通知渠道（管理员）；`add --qr ` 扫码即建 | | `/replies [show\|default\|set …]` | 查看或由 profile 管理员、当前群主/群管理员修改当前 scope 的回复流量策略 | | `/retention [N\|default]` | 查看或设置保留消息条数（超出自动归档） | | `/archive [note]` | 手动归档当前会话并把 Markdown + JSONL 上传到当前聊天 | | `/archive send [scope\|chatId]` | 重发当前 scope + workspace 的归档；管理员可发到指定已登记会话 | | `/archive list [N]` | 查看当前 workspace 最近 N 条归档 | | `/archive clean` | 清理当前 workspace 的过期归档 | | `/density [compact\|standard\|detailed]` | 查看或设置卡片密度 | | `/mode [quick\|balanced\|deep]`（兼容 `/effort`） | 选择当前会话任务强度；下一轮生效 | | `/config`（`/model`、`/providers`、`/provider`、`/key` 为到达同一张卡片的别名） | 打开交互式管理卡片（模型直接点选/恢复默认；写操作走多轮向导） | | `/model use ` | 精确路由并热切换当前会话模型（也兼容唯一模型 ID；下一轮生效） | | `/model default ` | 写入 dsh 默认模型 `agent-default-model`（管理员） | | `/model add\|remove [--input-modalities text,image]` | 添加 / 删除 provider 模型并声明视觉输入能力（管理员） | | `/provider add\|update\|remove ` | 管理 provider（管理员） | | `/key set <引用名>`、`/key remove\|list <引用名>` | 用仅请求者可提交的安全表单设置 dsh 凭据；写需管理员 | | `/secret status\|set\|remove <引用>` | 安全采集受支持密钥或查询配置状态 | | `/language show\|set plain\|agent …\|reset …` | 管理 plain fallback 与 Agent 回答语言策略 | | `/ask <问题>` | 发送问答卡，回答写入会话上下文 | | `/invite user\|admin\|group ` | 添加白名单 | | `/invite list` | 查看白名单 | | `/invite remove user\|group ` | 移除白名单 | | `/help` | 查看当前版本权威命令清单；即使 Agent runtime Skill 暂不可用仍由 bridge 直接处理 | 安全网守护接管期间（dsh 下线后）的额外命令： | 命令 | 作用 | | --- | --- | | `/safemode` | 进入仅核心安全模式（`dsh-base` + `dsh-headless`，无第三方插件） | | `/safemode status` | 查看守护 / dsh / 安全模式状态 | | `/safemode plugins` | 列出故障 profile 已安装的插件清单 | | `/safemode stop` | 终止当前正在运行的安全模式任务（也可点击任务卡片 ⏹ 按钮） | | `/safemode exit` | 退出安全模式，重启完整 profile 并交还飞书通道 | | `/safemode help` | 查看上述命令帮助 | ### 模型 / Provider / 凭据管理 常用 bridge 设置位于本机 dsh Web 的 **Settings → Plugins → Plugin configuration → dsh-lark-bot**。Host 半侧注册 `dsh-lark-bot` settings namespace，浏览器半侧由 npm 包的 `./client` 动态加载。页面展示实际 profile（包括扫码绑定）的 App ID、workspace 和模型，而不是只展示启动环境；App Secret 使用 secret role，任何 Web read 都会脱敏。 一次保存可修改服务区域、凭据、workspace、模型、并行数、adapter 与默认提醒。连接类配置会等待旧 generation 完整停止后再启动新 generation，避免双实例；模型/并行数/提醒热更新并从下一任务或提醒开始生效，不会中断 active run。快速诊断可先在页面直接检查脱敏配置，再复制 `/status` 或 `/doctor` 获取运行态详情。Web settings 不可用时，飞书命令和环境变量继续是兼容降级。 模型与 provider 的配置直接读写 dsh 官方配置存储（`~/.dsh/settings.yaml` 与 `~/.dsh/.credentials.yaml`，与 dsh Web **Settings → Models** 页面同一协议），改动在下一个 请求生效、无需重启 bot： - **交互式管理卡片（推荐）**：`/config`（或 `/providers`、裸 `/provider`、`/model`、`/key`，均为同一张卡片的别名）打开管理卡片； 当前模型带 ✅ 标记，可直接点选其他模型或恢复默认（下一轮生效且保留上下文）。增删改查按 BotFather 式多轮向导完成：能选择的用按钮点选（API 协议、provider、模型、凭据引用）， 需要填值的用卡片输入（ID、Base URL、模型列表、密钥值），写入前有确认卡，随时可取消； 向导 30 分钟无操作自动过期。文字命令与卡片向导等价、可混用。 - `/model use `：按会话精确路由并热切换模型（也兼容唯一模型 ID），下一轮消息即用新模型；`/model reset` 恢复默认。 - `/model default `：写入 dsh 的 `agent-default-model`（`{ provider, model }`，provider 由 桥接自动解析），作为新会话的默认模型。 - `/providers`：展示 dsh 已配置的 provider、模型与凭据状态（DeepSeek 官方 + 自定义 pi-ai）。 - `/provider add|update `：新增 / 更新自定义 provider（`llm-pi-ai`）或 `deepseek-official`； 自定义 provider 需要 `--api`（`openai-completions` / `openai-responses` / `anthropic-messages`）、 `--base-url`（根域名如 `https://www.kingapi.xyz` 自动补全为 `/v1`）与至少一个 `--model`。 `/provider remove ` 删除 provider。 - `/model add|remove [--input-modalities text,image]`：增删 provider 的模型目录； 视觉模型的 `inputModalities` 会被写入并从 settings 读回，交互向导也提供相同字段。 - provider 展示名、实时模型目录、模态与推理档位来自 models.dev，并缓存 15 分钟；目录不可用时 仅显示 dsh settings 的显式配置和默认选择。可用 `DSH_LARK_MODEL_CATALOG_URL` 切换兼容镜像。 - `/key set|remove|list`：引用名与状态读自 `~/.dsh/.credentials.yaml`（目录 0700、文件 0600）；set 只打开安全密码表单，值由本地 bridge 直接写入；普通聊天、旧的带值命令和 `--api-key` 不消费值。settings 只保存 `apiKeyEnv` 引用，字面密钥不进入 settings 或聊天记录。 - **凭据引用必须关联**：`/key set <引用名>` 安全写入凭据文件；provider 要使用该密钥，其 `apiKeyEnv` 必须引用同一名字（`/provider update --api-key-env <引用名>` 或向导中填写）。 引用名与 provider ID 相同且 provider 未设 `apiKeyEnv` 时，`/key set` 自动补关联；已存在的 老配置在下次运行时也会自动补齐。 - **热重载**：每轮运行前桥接把模型解析为「provider + model」路由并传给 dsh runtime；SDK 适配器 在路由变化时自动重建 runtime，`/model use` 的下一轮生效是真实行为（issue #47 修复）； 因 dsh runtime 启动后异步注册 llm-pi-ai 路由，桥接会轮询重试握手（issue #47 二次修复）。 命令执行失败会直接回复错误，不再被误转发给 agent；卡片发送失败自动降级为文字列表。 安全表单的数据仍需经过飞书/Lark 平台传输到本机 bridge；平台自身的审计、传输日志与保留策略不受 本项目控制，因此只应在受信私聊中操作。本项目保证该值不成为普通会话消息，并且 bridge 不把它送入 云端 LLM、prompt、session、任务账本、归档、结构化日志、诊断包、确认卡或回复。 除 `/model use`、`/model reset`、`/model`、`/providers`、`/key list` 外，其余写操作均需管理员 （`/invite admin ` 设置）。密钥值永不回显；在群聊中粘贴密钥会对群成员可见，建议仅在 私聊使用，或优先用 `--api-key-env` 引用环境变量 / 在 dsh Web 页面录入。 ### 任务执行模式 - `/mode` 打开 Card JSON 2.0 双语选择器；也可用 `/mode quick|balanced|deep`，`/effort` 等价。 - `quick` 直接回答并只做必要检查；`balanced` 兼顾速度与可靠性（默认）；`deep` 充分调查并验证假设与结果。 - 选择按 immutable scope 原子持久化到 `execution-modes.json`（0600），重启保留，`/status` 展示当前值。 - run 创建时固化模式，所以切换只影响下一轮；正在运行的任务、session/context、工具权限与计划门禁均不改变。 ### 多角色 Agent - `/role save --persona <文案>` 定义角色；`--model` 指定角色模型偏好，`--tools` 给出工具指引（逗号分隔），`--rules` 给出角色规则（等价于角色级 AGENTS.md）。 - `/role set ` 把角色绑定到当前 scope，`/role clear` 解除；`/status` 会显示当前角色。 - 角色定义持久化在 `~/.dsh-lark/profiles//roles.json`（0600），重启后绑定仍然生效。 - 模型优先级：每会话 `/model use` > 角色 `--model` > profile 偏好 > dsh 默认模型 > 环境默认。 - 角色 save / remove 仅管理员可执行；set / clear 任意被邀请用户可执行。 ### 多机器人实例与 @ 交接 ```bash dsh-lark-bot bot add reviewer --model gateway/review-model dsh-lark-bot bot list dsh-lark-bot bot status reviewer dsh-lark-bot bot remove reviewer ``` - `bot add` 为实例创建独立 bridge/dsh profile、`~/.dsh-lark/bots//dsh` DSH_HOME、 PersonalAgent 凭据与 OS 用户服务；可扫码，或同时传 `--app-id` / `--app-secret`。执行 add 时设置的 `DEEPSEEK_API_KEY` 只进入该实例 service；自定义 provider secret 可在启动后用 `/key set` 写入 独立 `.credentials.yaml`，模型目录和 provider 设置也位于该 DSH_HOME。 - 附加实例使用 `sdk` / `acp`（或 legacy `headless`）；不支持 `web`，因为共享 Web agent 的事件 广播不能保证多实例 session 隔离，命令与启动都会明确拒绝。 - 同群 peer 只有在 bot 类型事件、真实 @ 当前 bot、sender `open_id` 已登记且启用时才能交接； `DSH_LARK_BOT_HANDOFF_MAX` 控制连续 bot 回合上限（默认 6、最小 2），任意新鲜真人消息重置。 - `fleet.json` 与 `handoffs.json` 只保存身份/profile/计数元数据，不保存 App Secret；交接内容、卡片 与回复仍对共享群成员可见。member 隔离下的 bot 交接使用 group/topic scope。 - `bot remove` 删除实例飞书配置凭据、独立 `.credentials.yaml`、服务 env 与系统入口，但保留 profile 下会话、工作树、归档，以及 DSH_HOME 中不含字面密钥的 provider 设置/runtime session； 彻底删除须由用户备份后手工清理。 `default` 主机器人不能由 `bot remove` 删除，需使用标准 service/plugin 生命周期命令。 默认 guardian 只救援其配置的主实例；额外实例由各自 service 保活。 - 升级按 dsh profile 执行；有多个实例时逐个运行 `dsh-lark-bot upgrade --profile <实例的-dsh-profile> --yes [--restart]`。 ### 出站 @ 提及与跨会话通知 - 出站契约支持 `mentions`（`userId` + 可选 `name`），桥接层自动把 `` 提及标记拼入消息体。 - `/notify `：管理员向其他已注册会话推送消息；`/notify list` 查看 bridge 已知的 scope（`/scopes.json` 持久化 chat/thread 与最近入站 messageId；后者也作为 topic 问答卡的 reply anchor，重启不丢）。 - agent 侧工具 `lark_notify`：SDK / ACP runtime 均自动装配；参数 `text`、`scope`（目标会话， 缺省当前会话）、`chat_id`（直连兜底）、`mention_user_ids`（@ 提及的 open_id 列表）。 runtime 子进程通过 `http://127.0.0.1:<随机端口>/notify` + 每启动随机 token 回调 bridge， 不暴露公网。 - `/notifications on [current|scope|chatId] [events=completed,failed,approval,urgent] [mentions=self,ou_x|none] [sinks=channelId1,channelId2] [remind=10]` 显式开启当前 scope 的主动提醒；默认事件全选、@ 操作者、审批等待 10 分钟提醒一次。普通用户只能 使用当前会话，管理员可选已登记的跨会话目标；`show` 查看，`off` 关闭。偏好以 0600 原子持久化， `/status` 同步显示开关、事件、目标和审批延迟。通知失败只记日志，不改变任务终态。 - **通知转发到其他 IM（纯通知，issue #113）**：把完成 / 失败 / 审批与突发 / 故障通知，作为飞书 之外的**额外出站投递目标**。先由管理员配置渠道： - `/channels list`：查看已配置渠道（不显示凭据）。 - `/channels add --qr [--id ] [--label