dsh-lark-bot 0.11.0 → 0.12.0

package/README.md

@@ -328,17 +328,61 @@ to the latest version.
 
 ### 升级 | Upgrade
 
+**推荐：一行命令彻底升级（v0.12.0+ 新增，issue #10）**
+
+```bash
+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 最新版。
-- 安全网守护：随 `setup` 一起安装 / 升级（幂等重装），也可单独 `dsh-lark-bot guardian install`。
+- 安全网守护：随 `upgrade` / `setup` 一起安装 / 升级（幂等重装），也可单独
+  `dsh-lark-bot guardian install`。
 - CLI 工具（可选）：`npm i -g dsh-lark-bot@latest`；使用 `npx` 时无需全局安装。
-- 升级后重启 profile：`dsh --profile dsh-lark`。
+- 升级后重启 profile（未用 `--restart` 时）：`dsh --profile dsh-lark`。
+
+- **Recommended: one-command full upgrade (new in v0.12.0, issue #10)**
+
+```bash
+npx dsh-lark-bot@latest upgrade --profile dsh-lark --yes
+```
+
+`upgrade` detects the installed / running / npm-latest versions, upgrades the **package**
+(`dsh plugin add <name>@<latest>`), **idempotently reinstalls and restarts the guardian
+service**, then runs `doctor` verification. Running instances are handled safely:
+
+- By default the running dsh profile is never interrupted — you only get the restart command
+  (config / sessions / credentials are untouched);
+- `--restart`: also restarts the guardian service and (managed/detached) dsh profile processes;
+- `--check`: report versions and running state only, no changes;
+- `--rollback`: reinstall the version recorded before the last upgrade
+  (`~/.dsh-lark/upgrade-state.json`);
+- `--force`: reinstall the running version when npm is unreachable (offline);
+- `--no-guardian`: skip the guardian upgrade.
+
+Pass `--yes` to skip the interactive confirmation (non-interactive runs fail closed without it).
+Alternatives:
 
 - Plugin: re-run `setup` (or `dsh plugin --profile <name> add dsh-lark-bot`) to pull the latest
   npm release.
-- Safety-net guardian: installed / upgraded together with `setup` (idempotent), or standalone via
-  `dsh-lark-bot guardian install`.
+- Safety-net guardian: installed / upgraded together with `upgrade` / `setup` (idempotent), or
+  standalone via `dsh-lark-bot guardian install`.
 - CLI tool (optional): `npm i -g dsh-lark-bot@latest`; not needed when using `npx`.
-- Restart the profile after upgrading: `dsh --profile dsh-lark`.
+- Restart the profile after upgrading (when not using `--restart`): `dsh --profile dsh-lark`.
 
 ### 禁用 | Disable
 
@@ -518,6 +562,7 @@ Core environment variables:
 | `DSH_LARK_GUARDIAN_SAFE_ADAPTER` | `auto` | 安全模式引擎：`auto` 优先 SDK 流式、失败回退 headless；`sdk` 强制 SDK；`headless` 跳过预置<br>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` | 安全模式单任务空闲超时（持续无活动事件才停止并出超时卡）<br>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）<br>Card density for safe-mode run cards |
+| `DSH_LARK_UPGRADE_REGISTRY` | `https://registry.npmjs.org` | `upgrade` 探测最新版本的 npm registry（可指向镜像）<br>npm registry used by `upgrade` to discover the latest version (mirrors supported) |
 
 启动时会自动查找本机常见的 `@deepseek-ai/dsh` 安装位置。只有自动发现失败或需要指定特殊 profile 时，才需要设置这两个变量。
 
@@ -740,11 +785,12 @@ and relaunches the full profile on `/safemode exit`.
 | `src/onboard/` | 首次扫码创建 / 绑定 PersonalAgent 应用<br>First-run QR onboarding |
 | `src/session/` | 会话路由、排队、访问控制<br>Session routing, queueing, access control |
 | `src/workspace/` | 项目工作区、git worktree 隔离与规则注入<br>Project workspace, git worktree isolation & rule injection |
-| `src/adapters/` | agent 后端适配器（sdk 默认 / acp 审批 / headless legacy）<br>Agent backend adapters (sdk / acp / headless) |
+| `src/adapters/` | agent 后端适配器（sdk 默认 / acp 审批 / headless legacy / web 单写者）<br>Agent backend adapters (sdk / acp / headless / web single-writer) |
 | `src/card/` | 流式卡片状态与渲染<br>Streaming card state & rendering |
 | `src/bot/` | 运行注册、消息排队、审批/问答注册表<br>Run registry, queueing, approval/question registries |
 | `src/commands/` | 斜杠命令（/cd /ws /new …）<br>Slash commands |
-| `src/cli/` | CLI 入口：`setup`（唯一安装命令）/ `doctor`（诊断）/ 隐藏 `run`<br>CLI entry: setup / doctor / hidden run |
+| `src/cli/` | CLI 入口：`setup`（唯一安装命令）/ `doctor`（诊断）/ `upgrade`（一键升级）/ 隐藏 `run`<br>CLI entry: setup / doctor / upgrade / hidden run |
+| `src/upgrade/` | 一键升级（issue #10）：版本探测、升级状态、运行检测、guardian/profile 重启助手、runtime 链接修复<br>One-command upgrade (issue #10): version probe, upgrade state, running-state detection, restart helpers, runtime link repair |
 | `src/guardian/` | 安全网守护：心跳、进程观察、仅核心安全 profile、接管状态机、系统服务安装<br>Safety-net guardian: heartbeat, process watch, core-only safe profile, takeover state machine, service install |
 | `src/config/` | profile / 配置 / 访问白名单 / dsh 配置管理<br>Profile, config, access & dsh config management |
 | `src/core/` | 结构化日志<br>Structured logging |