dsh-lark-bot 0.18.0 → 0.19.1

package/README.md

@@ -49,10 +49,10 @@
 **基础能力**：
 
 - 私聊、群聊、话题（thread）里指挥本机 dsh coding agent，图片 / 文本文件直接发给 bot 即可；
-- 流式过程卡以飞书原生折叠面板实时展示阶段、耗时以及工具名称与状态，完成后最终回答单独发送，支持交互按钮（停止 / 计划门禁 / 审批 / 问答卡）；原始推理、工具输入输出与底层错误不会进入卡片；卡片更新失败会有限重试并降级为普通提示，Agent 与最终回答继续，不会拖垮 bridge 进程；
+- 流式过程卡以飞书原生折叠面板实时展示阶段、耗时以及工具名称与状态；完成但存在失败工具时汇总为“已完成（含警告）/Completed with warnings”，不把“任务轮次结束”冒充为“所有工具成功”。完成后最终回答单独发送，支持交互按钮（停止 / 计划门禁 / 审批 / 问答卡）；原始推理、工具输入输出与底层错误不会进入卡片；卡片更新失败会有限重试并降级为普通提示，Agent 与最终回答继续，不会拖垮 bridge 进程；
 - Git 仓库内为每个会话自动创建隔离 worktree 项目工作区，多项目互不干扰。
 
-**十一项全网独有组合**：
+**十二项全网独有组合**：
 
 - 🆘 **Guardian 安全网守护——“永远叫得应”**：DSH 崩溃后飞书仍会回复你，`/safemode` 进入仅核心安全模式直接重启。
 - 👥 **多角色 Agent——“一个机器人，一整个团队”**：`/role` 切换或指派 PM / 开发 / 文档等角色，每个角色独立人设、模型偏好与规则。
@@ -64,6 +64,7 @@
 - ⚙️ **dsh Web 可视化设置——“不用背环境变量”**：在官方 Settings → Plugins 页面点选应用、工作目录、模型、并行数与提醒，并可直达诊断。
 - 🔑 **对话内管理模型和密钥——“不用离开飞书”**：`/providers` `/provider` `/key` 直接查看、切换供应商、热更新密钥。
 - 🎚️ **快速 / 平衡 / 深度模式——“任务强度一键选”**：`/mode` 按 scope 持久选择，下一轮生效且不打断当前任务。
+- 🔄 **飞书内自更新——“离开命令行也能升级”**：管理员发送 `/upgrade` 检查 npm 官方包并通过确认卡交给 Guardian 后台更新、验证和重载；`/new` 发现新版本时只发一条简短提醒。
 - 🧭 **关键任务先拍板——“计划看清再动手”**：完整计划先单独发出，再用卡片批准执行或附意见继续规划，原任务自动续跑。
 
 ## 30 秒上手
@@ -117,6 +118,8 @@ Markdown、toast 与旧客户端降级路径同时显示中英文。agent 最终
 | `/ws use <name>` | 切换到命名工作空间|
 | `/ws remove <name>` | 删除命名工作空间|
 | `/status` | 查看可刷新状态卡（工作区 / 模型 / session / run / context / token / pending / 任务账本）|
+| `/version` | 查看当前版本与 npm 最新版本 |
+| `/upgrade` | 检查更新并通过确认卡让 Guardian 后台更新、验证和重载（管理员） |
 | `/doctor` | 生成脱敏诊断包并作为文件发送（管理员；可下载转发）|
 | `/jobs [list\|show <消息ID>\|retry <消息ID>]` | 对账排队/运行/完成/失败/中断任务；确认后显式重试 |
 | `/resume` | 查看当前会话最近上下文|
@@ -151,7 +154,8 @@ Markdown、toast 与旧客户端降级路径同时显示中英文。agent 最终
 | `/help` | 查看帮助|
 
 每轮 SDK / ACP / Web 请求都会注入结构化、无密钥的频道上下文，并注册官方 runtime Skill
-`dsh-lark-bot`。API Key、token 与 App Secret 必须经 `/key set <引用名>`、`/secret set …` 或 Agent
+`dsh-lark-bot`。上下文明确区分 bridge 预处理的用户斜杠命令与 Agent 可调用工具；后者的列表不代表
+前者不存在，Skill 暂时不可加载时仍以 `/help` 为当前版本权威命令入口。API Key、token 与 App Secret 必须经 `/key set <引用名>`、`/secret set …` 或 Agent
 工具 `lark_request_secret` 打开的密码表单提交；普通聊天、旧 `/key set <引用名> <值>` 与
 `--api-key` 不再消费值。表单只允许发起者提交，值直接写入本机受支持目标，不进入 prompt、session、
 任务账本、归档、日志、诊断包或回复。Guardian 安全模式是降级恢复面，不提供该完整配置与密钥工具。
@@ -244,7 +248,7 @@ guardian 仍只救援其配置的主实例。
 
 **结果文件直接回传**：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 / ACP / Web runtime 在任何本地快速通道和计划门裁决前，先通过鉴权回环读取当前 immutable scope 的 `ask|allow|deny`。`deny` 对低风险与高风险工具都先行拒绝并返回 `permission-policy` 来源；`ask` 对保守只读自省静默放行、对高风险调用弹“允许执行一次 / 拒绝”卡；`allow` 自动放行逐工具审批，但仍不替代高风险任务的计划确认或 Harness 文件沙箱。管理员可用 `/permission allow|deny|ask [scope]` 修改当前聊天内 scope；策略成功落盘后才确认，持久化到 profile 的 `permission-policies.json`（0600），重启不丢并显示在 `/status`。legacy `headless` 不具备工具回调能力。
+**逐操作审批与 scope 权限策略**：SDK / ACP / Web runtime 在任何本地快速通道和计划门裁决前，先通过鉴权回环同步读取当前 immutable scope 的 `ask|allow|deny`；该 policy-only 查询不创建卡片或进入人类等待传输。`deny` 对低风险与高风险工具都先行拒绝并返回 `permission-policy` 来源；`ask` 对保守只读自省静默放行、对高风险调用弹“允许执行一次 / 拒绝”卡；`allow` 自动放行逐工具审批，但仍不替代高风险任务的计划确认或 Harness 文件沙箱。管理员可用 `/permission allow|deny|ask [scope]` 修改当前聊天内 scope；策略成功落盘后才确认，持久化到 profile 的 `permission-policies.json`（0600），重启不丢并显示在 `/status`。legacy `headless` 不具备工具回调能力。
 
 **关键任务计划门禁**：SDK / ACP / Web agent 在修改文件、运行脚本等较大或高风险动作前使用
 `lark_request_plan_approval`；同一 turn 未获批准时，runtime pre-execute 策略会拒绝写入、删除、
@@ -330,6 +334,8 @@ profile 的前台进程会拒绝并提示先停止，生命周期锁阻止并发
 
 ### 升级
 
+**完全不接触命令行：** profile 管理员在飞书发送 `/upgrade`。有新版本时 bot 弹出只允许发起人操作的确认卡；点击“确认更新”后，Guardian 通过独立 worker 安装卡片中确认的精确 npm 版本，复用完整升级、runtime profile 修复、guardian/profile 重启和 doctor 验证链，并在重载后回到原会话报告结果。点击“取消”不会产生任何变更。更新会重启机器人，正在执行的任务可能被中断；配置、会话、归档和凭据保持不变。每次 `/new` / `/reset` 都会 best-effort 查询一次 npm；仅在有新版本时额外发送一条简短普通消息。
+
 **推荐：一行命令彻底升级（v0.12.0+ 新增，issue #10）**
 
 ```bash
@@ -402,7 +408,7 @@ dsh plugin --profile dsh-lark remove dsh-lark-bot
 
 **Q: dsh-lark-bot 和其他 DeepSeek Harness 飞书插件（如 harness-lark）有什么区别？**
 
-**A:** 功能组合最全：安全网守护、多角色 Agent、多机器人可信交接、并行多任务、持久任务对账、会话归档、跨会话主动通知、dsh Web 可视化设置、对话内模型 / 密钥管理、执行模式与关键任务计划门禁十一项合一；标准 dsh profile bundle，`setup` 是唯一安装路径；可选 `service install` 只负责把同一 profile 交给 OS 常驻，不是第二套运行时。
+**A:** 功能组合最全：安全网守护、多角色 Agent、多机器人可信交接、并行多任务、持久任务对账、会话归档、跨会话主动通知、dsh Web 可视化设置、对话内模型 / 密钥管理、执行模式、关键任务计划门禁与飞书内自更新十二项合一；标准 dsh profile bundle，`setup` 是唯一安装路径；可选 `service install` 只负责把同一 profile 交给 OS 常驻，不是第二套运行时。
 
 **Q: 项目从哪下载？会不会有假冒版本？**
 
@@ -514,7 +520,7 @@ SDK 模式下 dsh 原生 session 续跑，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` | `1` | `doctor` / `/version` / `/upgrade` / `/new` 是否探测 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`）|
@@ -523,6 +529,8 @@ SDK / ACP 启动会先解析完整 provider/model route：显式双字段优先
 `agent-default-model: { provider, model }`；仍无法得到完整 route 时在 bridge/doctor 入口给出本项目的
 明确配置错误，不把空 provider 传给上游 runtime。受管 service 的 install/start/restart 会把旧 env
 文件中的受管键与当前 shell 合并（当前 shell 显式值优先），避免从另一个终端重启时静默丢失已有 route。
+模型目录在进程冷启动时暂时不可达，也会保留该对象形式默认 route 作为最小离线条目；这不会放行
+settings 中没有明确配置的未知模型。
 
 启动时会自动查找本机常见的 `@deepseek-ai/dsh` 安装位置。只有自动发现失败或需要指定特殊 profile 时，才需要设置这两个变量。
 
@@ -781,7 +789,7 @@ pnpm publish:dual
 - omdsh-dev/community 收录：[Discussion #11](https://github.com/orgs/omdsh-dev/discussions/11) — ✅ 通过，讨论活跃（最新更新说明 v0.10.2）；v0.15.1 更新说明 — 📨 已备妥，待人工粘贴
 - 平台数据刷新（v0.14.0 → v0.15.1）— ✅ 已恢复提交（2026-08-17）：awesome-dsh-plugins [PR #230](https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/230) · dshfind [#6 跟进](https://github.com/hikariming/dshfind/issues/6#issuecomment-5317081509) · omdsh 说明备妥
 
-**历史亮点跟进**（当时六项独家能力与 issue #6 设计实现；当前能力见上方十一项清单）：
+**历史亮点跟进**（当时六项独家能力与 issue #6 设计实现；当前能力见上方十二项清单）：
 
 - awesome-dsh-plugins 榜单行同步（仓库描述 → 最新）与 agent-test 报告名称异常：[#139](https://github.com/AdamPlatin123/awesome-dsh-plugins/issues/139) — 📨 已提交（维护方已确认，等待渲染周期同步）
 - dshfind 详情页补「对话内管理模型和密钥」亮点：[#2 跟进评论](https://github.com/hikariming/dshfind/issues/2#issuecomment-5301019067) — 📨 已提交

package/README_EN.md

@@ -51,10 +51,10 @@ Bot-owned command help, status/error messages and interactive cards are availabl
 **Core**:
 
 - Drive your local dsh coding agent from private chats, group chats and threads; images / text files can be sent straight to the bot;
-- A streaming process card with a native collapsible panel for phase, elapsed time, and tool names/statuses; raw reasoning, tool payloads, and underlying errors stay out of the card. The final answer arrives separately, with interactive buttons for stop / plan gate / approval / questions. Failed card patches are retried finitely and degrade to a plain notice—the agent and final reply continue instead of taking down the bridge;
+- A streaming process card with a native collapsible panel for phase, elapsed time, and tool names/statuses. A completed turn containing a failed tool is summarized as **Completed with warnings** in native and legacy views without changing the completed job outcome. Raw reasoning, tool payloads, and underlying errors stay out of the card. The final answer arrives separately, with interactive buttons for stop / plan gate / approval / questions. Failed card patches are retried finitely and degrade to a plain notice—the agent and final reply continue instead of taking down the bridge;
 - Automatic session archival and retention policies; per-session isolated git worktrees inside Git repositories, so multiple projects never interfere with each other.
 
-**Eleven exclusive capabilities**:
+**Twelve exclusive capabilities**:
 
 - 🆘 **Guardian safety net — "always reachable"**: Feishu still replies after dsh crashes; `/safemode` enters core-only safe mode to locate the problem and restart directly.
 - 👥 **Multi-role agents — "one bot, a whole team"**: switch or assign PM / dev / docs roles with `/role`; each role has its own persona, model preference and rules.
@@ -67,6 +67,7 @@ Bot-owned command help, status/error messages and interactive cards are availabl
 - ⚙️ **Visual dsh Web settings — "no environment variables to memorize"**: edit the app, workspace, model, concurrency and reminders from the official Plugins settings page, with diagnostic shortcuts.
 - 🔑 **In-chat model & key management — "never leave Feishu"**: `/providers` `/provider` `/key` to view, switch vendors and hot-update keys.
 - 🎚️ **Quick / balanced / deep modes — "pick the right task intensity"**: `/mode` persists per scope and applies on the next turn without interrupting active work.
+- 🔄 **In-chat self-update — "upgrade without a terminal"**: an admin sends `/upgrade`, confirms an owner-bound card, and Guardian updates, verifies, and reloads the bot in the background; `/new` emits only a short reminder when a newer version exists.
 
 ## Quick Start
 
@@ -115,6 +116,8 @@ Send a normal message to the bot in Feishu to get started. Common commands:
 | `/ws use <name>` | Switch to a named workspace |
 | `/ws remove <name>` | Remove a named workspace |
 | `/status` | Show a refreshable status card (workspace / model / session / runs / context / tokens / pending cards / job ledger) |
+| `/version` | Show the running version and npm latest version |
+| `/upgrade` | Check for an update and confirm a Guardian-managed background update, verification, and reload (admin) |
 | `/doctor` | Generate and upload a redacted diagnostic bundle (admin; downloadable and forwardable) |
 | `/jobs [list\|show <message-id>\|retry <message-id>]` | Reconcile queued/running/completed/failed/interrupted jobs and explicitly retry after review |
 | `/resume` | Show the session's recent context |
@@ -149,7 +152,9 @@ Send a normal message to the bot in Feishu to get started. Common commands:
 | `/help` | Show help |
 
 Every SDK, ACP, and Web turn receives structured, secret-free channel context and the official runtime
-`dsh-lark-bot` skill. API keys, tokens, and App Secrets must be entered through the owner-only password form opened
+`dsh-lark-bot` skill. The context distinguishes bridge-side slash commands from model-callable tools: the tool list
+does not imply that slash commands are absent, and `/help` remains the authoritative command list if the runtime
+skill cannot be loaded. API keys, tokens, and App Secrets must be entered through the owner-only password form opened
 by `/key set <ref>`, `/secret set …`, or `lark_request_secret`. Ordinary chat, legacy `/key set <ref> <value>`, and
 `--api-key` no longer consume values. The value never enters prompts, sessions, jobs, archives, logs, diagnostics,
 or replies. Guardian safe mode is a degraded recovery surface without the full configuration/secret seam.
@@ -165,7 +170,8 @@ The `/model` card merges the dsh default into its switchable catalogue even when
 list omits it, and uses compact distinguishing labels with at most two buttons per mobile row. Provider
 names, models, input modalities, and reasoning-effort options are discovered from the models.dev runtime
 catalogue and cached in memory for 15 minutes. If it is unavailable, only explicit dsh settings and the
-configured default are shown—there is no hardcoded fallback list. Override the feed with
+configured default are shown, and an object-form `agent-default-model` remains a minimally resolvable offline
+route—there is no hardcoded fallback list and other unknown models remain rejected. Override the feed with
 `DSH_LARK_MODEL_CATALOG_URL`; model commands and the wizard preserve `inputModalities`.
 
 **Message-level DSH session sync (`web` adapter)**: `/session` lists metadata only for non-subagent sessions
@@ -253,7 +259,7 @@ reject `web`, because a shared Web agent broadcast stream cannot isolate session
 
 **Direct result-file delivery**: SDK / ACP / Web agents can call `lark_send_file` to upload a file from the current session workspace, its actual execution worktree, its scope archive, or the instance logs to the originating Feishu chat/topic. `/archive [note]` uploads its Markdown and JSONL after the durable local write; `/archive send <id> [scope|chatId]` retries locally or lets an admin forward it to a registered session. Only regular files up to 20 MiB are accepted by default. The resolved path must remain inside roots computed by the bridge; a runtime-supplied cwd never expands access.
 
-**Per-action approval and scope policy**: the default SDK and Web host enforce a `tools/pre-execute` gate and wire dsh rc.8's official `approval/request` seam into Feishu; ACP uses native `session/request_permission`. The default `ask` policy shows **Allow once** / **Reject**. An admin may use `/permission allow` to auto-allow tool approvals in the current isolated scope, `/permission deny` to reject them with an explicit chat notice, or `/permission ask` to restore prompts. In member isolation, copy the target from `/status` and use `/permission <policy> <scope>`; cross-chat targets are rejected. Success is confirmed only after the owner-only `permission-policies.json` write completes, so policies survive restarts and appear in `/status`. They never bypass the separate plan gate; legacy `headless` has no tool callback channel.
+**Per-action approval and scope policy**: the default SDK and Web host enforce a `tools/pre-execute` gate and wire dsh rc.8's official `approval/request` seam into Feishu; ACP uses native `session/request_permission`. Before any fast path or plan gate, the runtime synchronously queries the immutable scope policy through the authenticated policy-only callback; this response is `ask|allow|deny`, requires no approval outcome, and never creates or waits for a card. The default `ask` policy shows **Allow once** / **Reject** for high-risk calls. An admin may use `/permission allow` to auto-allow tool approvals in the current isolated scope, `/permission deny` to reject them with an explicit chat notice, or `/permission ask` to restore prompts. In member isolation, copy the target from `/status` and use `/permission <policy> <scope>`; cross-chat targets are rejected. Success is confirmed only after the owner-only `permission-policies.json` write completes, so policies survive restarts and appear in `/status`. They never bypass the separate plan gate; legacy `headless` has no tool callback channel.
 
 **Plan gate for substantial tasks**: SDK / ACP / Web agents use `lark_request_plan_approval` before file
 changes, scripts, or other substantial/high-risk actions. A runtime pre-execute policy denies writes, deletes,
@@ -336,6 +342,8 @@ Security note: never type a key in ordinary Feishu chat. Use the secure form or
 
 ### Upgrade
 
+**No terminal required:** a profile admin sends `/upgrade` in Feishu/Lark. When a newer release exists, the bot sends an owner-bound confirmation card. Confirming hands the exact npm version to an isolated Guardian worker, which runs the full package/runtime-profile/guardian/profile upgrade and verification path, reloads the bot, and reports the result back to the original chat or thread. Cancel makes no changes. Reloading can interrupt active tasks; configuration, sessions, archives, and credentials are preserved. Every `/new` or `/reset` performs a best-effort npm check and emits one short plain reminder only when a newer version exists.
+
 **Recommended: one-command full upgrade (new in v0.12.0, issue #10)**
 
 ```bash
@@ -490,7 +498,7 @@ Core environment variables:
 | `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` | Card density for safe-mode run cards (compact / standard / detailed) |
 | `DSH_LARK_UPGRADE_REGISTRY` | `https://registry.npmjs.org` | npm registry used by `upgrade` to discover the latest version (mirrors supported) |
-| `DSH_LARK_UPGRADE_CHECK` | `1` | Whether `doctor` / `/version` probe npm latest (`0` disables; best-effort) |
+| `DSH_LARK_UPGRADE_CHECK` | `1` | Whether `doctor` / `/version` / `/upgrade` / `/new` probe npm latest (`0` disables; best-effort) |
 | `DSH_LARK_UPGRADE_CHECK_INTERVAL_MS` | `21600000` | Bridge new-version check interval (`0` disables; default 6h) |
 | `DSH_LARK_UPGRADE_NOTIFY` | `false` | Push a Feishu notification to the target chat when a newer version is found (default: log-only) |
 | `DSH_LARK_UPGRADE_NOTIFY_CHAT` | — | Chat receiving update notifications (with `DSH_LARK_UPGRADE_NOTIFY=true`) |