chuxin-agentdesk 0.1.1 → 0.1.2

package/README.md

@@ -1,23 +1,25 @@
 # AgentDesk CLI
 
-复用 AgentDesk 引擎的独立本地 CLI。支持后台服务、模型配置、流式聊天、持久化任务、工具审批与诊断。
+复用 AgentDesk 引擎的独立 CLI，内置浏览器工作台。支持后台服务、模型配置、多轮交互会话、流式聊天、持久化任务、工具审批与诊断，也可通过电脑连接器配对自部署远程工作台。
 
-npm 包名为 `chuxin-agentdesk`，安装后命令是 `agentdesk`。许可证目前为 `UNLICENSED`（保留权利，不是开源许可）。远程机器、团队账号和 Web 工作台尚未提供。
+npm 包名为 `chuxin-agentdesk`，安装后命令是 `agentdesk`。许可证目前为 `UNLICENSED`（保留权利，不是开源许可）。`agentdesk web` 打开本机工作台；手机访问需要另行部署远程网关与 Runner，并对电脑项目完成配对授权，见[电脑连接器](#电脑连接器与远程工作台)。
+
+当前界面与功能展示见[主 README](../../README.md#界面预览)。
 
 ## 安装
 
-需要 Node.js 22.12+、Git。
+需要 Node.js 22.12+、Git。当前随包提供的 Autoloop 自动化运行时面向 Windows x64。
 
 ```powershell
 npm install -g chuxin-agentdesk
 agentdesk --help
-agentdesk init
-agentdesk
+agentdesk              # 配置模型，然后选择浏览器工作台或终端对话
+agentdesk web          # 随时打开浏览器工作台
 ```
 
 ## 本地构建
 
-源码构建还需要项目的 pnpm 开发环境。
+源码构建使用仓库声明的 `pnpm@10.33.3`（要求 pnpm 10+），并需要 Rust 工具链和[固定的 Autoloop Node 运行时](../../packages/autoloop-runtime/README.md#固定版本与构建)。请在仓库根目录执行以下命令。`build:cli` 会打包 CLI、运行时、公开技能和浏览器工作台（调用桌面前端的 Vite CLI 模式构建），不构建或安装桌面应用。`pack` 的 `prepack` 脚本也会执行构建。tarball 名称基于 npm 包名与版本，例如当前 `0.1.2` 对应 `chuxin-agentdesk-0.1.2.tgz`；以实际输出为准。
 
 ```powershell
 pnpm install
@@ -29,13 +31,14 @@ npm install --prefix <安装目录> <tarball路径>
 <安装目录>/node_modules/.bin/agentdesk --help
 ```
 
-运行包不包含构建机的 Node 二进制、预编译数据库模块、开发环境配置或私有技能。`better-sqlite3` 与 `playwright-core` 作为正式依赖在目标环境安装。原生依赖没有匹配预编译文件时需要对应平台的构建工具。`playwright-core` 不下载浏览器，浏览器工具需要机器上可用的 Chrome 或 Edge。
+CLI 主进程使用目标机器的 Node；Autoloop 自动化另行包含经过哈希校验的固定 Node 运行时与 Supervisor，当前发行目标为 Windows x64，详见 [runtime 文档](../../packages/autoloop-runtime/README.md)。运行包不包含开发环境配置或私有技能。`better-sqlite3` 与 `playwright-core` 作为正式依赖在目标环境安装。原生依赖没有匹配预编译文件时需要对应平台的构建工具。`playwright-core` 不下载浏览器，浏览器工具需要机器上可用的 Chrome 或 Edge。
 
 ## 使用
 
 ```powershell
 agentdesk start
 agentdesk init
+agentdesk web                                # 打开浏览器工作台，与 CLI 共用数据
 agentdesk chat                               # 打开持久化交互式会话
 agentdesk chat "我有哪些项目"                 # 一次性流式对话并退出
 agentdesk chat "帮我分析这个问题" --agent code
@@ -47,9 +50,28 @@ agentdesk doctor
 agentdesk stop
 ```
 
-`init`、`chat`、`run`、`tasks`、`inspect`、`cancel`、`resume`、`approvals`、`approve`、`reject` 等命令在本地服务未运行时会自动在后台拉起服务并等待就绪后继续执行（交互终端下会看到一行启动提示），不需要每次手动先执行 `agentdesk start`；仍然可以显式用 `start`/`stop`/`restart`/`status` 管理服务生命周期，这四个命令的行为不受影响。
+`web`、`init`、`chat`、`run`、`tasks`、`inspect`、`cancel`、`resume`、`approvals`、`approve`、`reject` 等命令在本地服务未运行时会自动在后台拉起服务并等待就绪后继续执行（交互终端下会看到一行启动提示），不需要每次手动先执行 `agentdesk start`；仍然可以显式用 `start`/`stop`/`restart`/`status` 管理服务生命周期。
+
+在真实交互终端下，不带任何子命令直接执行 `agentdesk` 会先检查模型配置，未配置时完成 `init` 向导，然后提供「打开浏览器工作台」和「继续终端对话」两个选项。显式执行 `agentdesk init`，完成配置或选择保留已有配置后，也会展示这个入口。希望直接进入终端对话时执行 `agentdesk chat`。脚本、CI 或管道等非交互环境下，裸执行仍打印帮助，`init` 只保存配置并提示下一步命令。
+
+### 浏览器工作台与桌面端
+
+```powershell
+agentdesk web
+agentdesk web --data-dir D:/AgentDesk/data
+agentdesk web --no-open                      # 只打印连接地址，手动复制到浏览器
+agentdesk web --json                         # 只输出 { url, expiresAt }，不打开浏览器
+```
 
-在真实交互终端下，不带任何子命令直接执行 `agentdesk` 会跳过帮助页：已配置模型时直接进入持久化交互式会话（等同于 `agentdesk chat`）；未配置模型时先完成一次 `init` 配置向导，正常完成后进入同一会话。显式执行 `agentdesk init` 也一样：填完地址和密钥，或选择保留已有配置后，直接进入对话界面。脚本、CI 或管道等非交互环境下，裸执行仍打印帮助，`init` 只保存配置并提示下一步命令。
+工作台页面随 npm 包安装，不需要克隆源码、启动 Vite 或安装桌面端。`web` 自动打开系统默认浏览器，无法自动打开时打印可复制的连接地址。进入后可以使用 Bot、编码现场、项目、成长中心、面试题库、工作流、自动化与设置等页面；自动化依赖可用的 Autoloop 运行时。在设置里添加模型和项目，也可先用 `agentdesk init` 配置模型。
+
+浏览器与使用相同 `--data-dir` 的 CLI 共用模型、对话、任务和审批。「编码现场」会显示当前实例的任务，不需要再次切换到 CLI 会话。关闭终端或页面后，后台服务与持久化任务继续运行；实时聊天断开则会取消当前轮次。使用 `agentdesk stop` 停止服务。
+
+连接地址仅限本机使用，2 分钟内有效且只能使用一次，请勿分享。连接成功后地址栏会清除连接凭据，刷新页面仍保持登录；会话在 24 小时后或服务重启后失效，重新运行 `agentdesk web` 即可连接。浏览器不持有 CLI 主令牌。
+
+桌面模式使用独立的 AgentDesk 安装包，安装后从系统应用入口打开。桌面默认数据目录与 CLI 不同，不会自动同步。npm 安装提供终端和浏览器入口，不安装桌面客户端。
+
+交互终端里执行 `agentdesk`、`init`、`chat` 或 `run` 时，如果 npm 上有更新版本，会先询问：立即更新、本次跳过，或在下一个版本前不再提示。选择更新会从官方 npm registry 执行 `npm install -g chuxin-agentdesk@<检测到的版本>`，成功后重新启动当前入口和参数；安装失败则继续使用当前版本。版本检查结果缓存 1 小时。非交互或 `--json` 模式，以及设置了非空 `CI`、`AGENTDESK_SKIP_UPDATE` 或 `AGENTDESK_NO_UPDATE` 环境变量时跳过检查。本地安装或源码运行建议跳过全局更新，按原安装方式手动更新；自动更新不会替你迁移安装入口或重启旧后台服务。
 
 `init` 在服务启动后交互配置模型地址、名称和 API Key，密钥输入不回显，并由现有 sidecar 密钥存储加密保存。CLI 独立运行使用本地密钥文件，和桌面端的系统钥匙串方式不同。`init` 保存配置但不自动调用模型；进入对话后使用自己的有效模型完成一轮聊天，才算连通验证。
 
@@ -68,7 +90,7 @@ New-Item -ItemType Directory -Force D:/AgentDesk/tmp | Out-Null
 $env:TEMP = 'D:/AgentDesk/tmp'
 $env:TMP = $env:TEMP
 $env:AGENTDESK_CLI_HOME = 'D:/AgentDesk/data'
-npm install --prefix D:/AgentDesk/install D:/agent/AgentDesk/release/agentdesk-cli-0.1.0.tgz --cache D:/AgentDesk/npm-cache
+npm install --prefix D:/AgentDesk/install D:/agent/AgentDesk/release/chuxin-agentdesk-0.1.2.tgz --cache D:/AgentDesk/npm-cache
 
 & D:/AgentDesk/install/node_modules/.bin/agentdesk.cmd start
 & D:/AgentDesk/install/node_modules/.bin/agentdesk.cmd init
@@ -90,9 +112,9 @@ agentdesk init --base-url https://api.example.com/v1 --model <模型名称> --ap
 - CLI 默认数据根目录为 `~/.agentdesk`，通过全局参数 `--data-dir <目录>` 或 `AGENTDESK_CLI_HOME` 修改。对同一实例执行命令时使用同一数据目录。
 - 根目录保存实例状态和后台日志，`data/` 保存数据库、加密凭据、用户技能和浏览器资料。
 - 默认监听 `127.0.0.1:17891`；`start --port 0` 自动选空闲端口，或 `--port <端口>` 指定。
-- CLI 与桌面默认使用不同数据目录、数据库和端口，当前不自动同步两者的数据。
+- CLI 与它打开的浏览器工作台共用数据；桌面默认使用不同数据目录、数据库和端口，当前不自动同步桌面数据。
 - 每次服务启动生成随机认证令牌。CLI 从本地实例状态读取，正常命令不会打印令牌。
-- `start` 默认脱离终端后台运行，`start --foreground` 在当前终端运行，适合交给 systemd、pm2 或容器管理。首版不包含开机自启或崩溃自动拉起；可由外部进程管理器提供。
+- `start` 默认脱离终端后台运行，`start --foreground` 在当前终端运行，适合交给外部进程管理器。Windows 电脑连接器可用 `connect install` 安装当前用户登录自启动与连接进程恢复。
 - `stop` 通过带认证且身份匹配的服务接口关闭实例，不对无法确认身份的 PID 强制结束。
 - `restart` 保留当前端口，已停止实例默认回到 17891；指定端口可覆盖。
 - 后台日志超过 10 MB 时在下次启动轮转，保留一份 `.1`。前台日志由当前终端或外部进程管理器收集。
@@ -116,13 +138,71 @@ agentdesk chat --conversation <会话ID>        # 显式续接已有会话，跳
 
 会话内支持：
 
-- 已完成的轮次滚动保留在历史区，当前这一轮实时显示流式文本、路由与工具调用卡片。
-- 按 `o` 整体展开/折叠当前这一轮所有工具调用的参数与结果。
-- 当前这一轮有工具调用步骤时，按 `Tab` 在输入框焦点与步骤导航焦点之间切换；步骤导航焦点下用 `↑↓` 或 `j`/`k` 移动高亮行（左侧竖线标记），`Enter` 或空格单独展开/折叠该行，`Esc` 或再按一次 `Tab` 返回输入框。已经滚入历史区的过往轮次不支持这种逐行焦点导航。
-- 遇到需要审批的工具调用会弹出卡片，按 `y` 批准、按 `n` 或 `Esc` 拒绝；审批期间输入框暂停，连接保持不断开。
-- 空闲时 `Ctrl+C` 退出会话；流式或等待审批时 `Ctrl+C` 只中断当前这一轮，回到可继续输入的状态。
-- 顶部状态栏每 15 秒刷新跨会话的待处理审批数量（来自其他客户端或工作流产生的审批），处理这些审批仍使用 `agentdesk approvals`/`approve`/`reject`。
-- 一轮对话完成后最终回答按 Markdown 渲染；流式阶段显示原始文本，避免半截 markdown 渲染错乱。`--plain`/`--no-color`/`NO_COLOR` 下不做终端着色。
+- 已完成的轮次滚动保留在历史区，当前这一轮实时显示流式文本、路由与工具调用卡片。实时区高度随终端行数调整；长输出超出视口时，按 `PgUp`/`PgDn` 向上/向下翻页，底部会显示当前可见行范围与总行数。翻页只移动实时区内容，不会把整屏反复推入终端回滚区；历史区内容仍通过终端自身的回滚查看。
+- 实时区默认自动跟随输出末尾；向上翻页后停留在所查看的位置，不随新输出跳到底部。按 `PgDn` 回到末尾后恢复自动跟随。
+- 文件写入成功后，默认显示带行号的代码差异卡片，绿色表示新增、红色表示删除，并显示增删行数；长差异可在实时区翻页，完成后保留在终端历史中。
+- 按 `Ctrl+O` 整体展开/折叠工具调用详情；普通字母 `o` 会作为输入，不再是快捷键。
+- 当前这一轮有工具调用步骤时，按 `Tab` 在输入框焦点与步骤导航焦点之间切换；步骤导航焦点下用 `↑↓` 或 `j`/`k` 移动高亮行（左侧竖线标记），`Enter` 或空格单独展开/折叠该行。焦点步骤会自动滚入视口，展开后也会调整可见位置；若该步骤本身高于视口，则从步骤顶部显示，可继续用 `PgUp`/`PgDn` 查看。`Esc` 或再按一次 `Tab` 返回输入框，并恢复自动跟随末尾。已经滚入历史区的过往轮次不支持这种逐行焦点导航。
+- 输入框支持左右移动、`Home`/`End`、`Ctrl+A`/`Ctrl+E` 移到首尾、`Ctrl+U`/`Ctrl+K` 删除光标前后内容、`Ctrl+W` 删除前一个词；`Enter` 提交，`Shift+Enter` 换行（需终端支持）。没有指令菜单时，`↑↓` 浏览本次终端进程的输入历史，并可返回尚未提交的草稿。
+- 空闲时 `Ctrl+C` 先清空非空草稿，输入为空时才退出；流式时 `Esc` 或 `Ctrl+C` 中断当前轮次，不退出会话。指令面板或加载期间按 `Esc`/`Ctrl+C` 关闭或取消指令。
+- 一轮对话完成后最终回答按 Markdown 渲染；流式阶段显示原始文本，避免半截 Markdown 渲染错乱。`--plain`/`--no-color`/`NO_COLOR` 下不做终端着色。
+
+### 斜杠指令
+
+以下指令仅在持久化交互式 `agentdesk chat` 输入框中解析，不是 shell 子命令，也不作为聊天消息发送给模型；部分指令会查询或更新本地服务，`/export` 会写入本地文件。一次性 `chat "消息"`、`--json` 与非交互输入不会进入这套指令处理流程。
+
+空闲时输入 `/` 展示指令菜单，用 `↑↓` 选择、`Enter` 执行、`Tab` 补全命令后继续输入参数；模型等选择面板支持输入关键词筛选，`Esc` 关闭且不改变选择。`/help <命令>` 或 `/<命令> help` 查看具体用法。未知指令会显示错误，不会交给模型执行。
+
+| 指令                         | 作用与别名                                                                                                                              |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `/help [命令]`               | 查看指令与快捷键；别名 `/?`                                                                                                             |
+| `/model [模型或子命令]`      | 选择模型，详见下节                                                                                                                      |
+| `/clear`                     | 开始新上下文，不删除历史；别名 `/new`、`/reset`                                                                                         |
+| `/resume [会话 ID 或标题]`   | 恢复历史聊天，标题按包含关系匹配；无参数或多个匹配时打开选择器；别名 `/continue`                                                        |
+| `/rename <标题>`             | 重命名已开始的会话                                                                                                                      |
+| `/agents [名称]`             | 选择 Agent：`orchestrator`、`code`、`project`、`deploy`、`research`、`reviewer`；别名 `/agent`                                          |
+| `/config [选项] [on 或 off]` | 调整当前终端的 `color`、`motion`、`emoji`、`verbose`；无参数打开菜单；别名 `/settings`                                                  |
+| `/theme [default 或 plain]`  | 恢复启动时显示设置，或关闭颜色、动效和 Emoji；不修改持久化配置                                                                          |
+| `/status`                    | 查看当前会话、Agent、模型、工作目录和服务状态                                                                                           |
+| `/context`                   | 统计已保存消息数、正文字符数和工具调用数，不是 token 统计，不包含系统提示和自动召回记忆                                                 |
+| `/permissions`               | 查看工具风险等级与待处理审批，仅查看，不直接授权；别名 `/approvals`                                                                     |
+| `/tools [搜索词]`            | 查看工具、说明与风险等级                                                                                                                |
+| `/skills [搜索词]`           | 查看已加载的 Skills                                                                                                                     |
+| `/tasks [状态]`              | 查看后台任务；不会创建任务                                                                                                              |
+| `/memory [搜索词]`           | 查看并筛选长期记忆；不会新增或删除记忆                                                                                                  |
+| `/export [文件路径]`         | 导出已保存会话为 Markdown（含工具记录）；默认写入当前工作目录下的 `agentdesk-<会话ID>.md`，相对路径也基于当前工作目录，已有文件不会覆盖 |
+| `/doctor`                    | 检查服务连接和 Provider 配置，不发起模型推理请求；不同于 shell 中的完整 `agentdesk doctor` 环境诊断                                     |
+| `/version`                   | 显示 CLI 版本                                                                                                                           |
+| `/exit`                      | 退出终端会话；别名 `/quit`                                                                                                              |
+
+注意：聊天内的 `/resume` 恢复的是聊天会话；shell 中的 `agentdesk resume <任务ID>` 重跑的是失败或已取消的持久化任务。启动参数 `--agent` 当前仅接受 `orchestrator`、`project`、`deploy`、`research`、`code`，与交互菜单额外提供的 `reviewer` 不同。
+
+### 模型选择
+
+```text
+/model                         # 打开模型选择面板，可输入关键词筛选
+/model <模型名称>              # 在可用模型中选择；未列出的名称使用当前/默认 Provider
+/model <Provider ID>/<模型>    # 明确指定 Provider，也支持 Provider 名称前缀
+/model info                    # 查看当前覆盖或默认模型（也支持 status）
+/model refresh                 # 从已启用且有密钥的 Provider 拉取远端模型列表并打开菜单
+/model default                 # 清除覆盖，恢复 Agent 默认绑定和回退策略
+```
+
+- 菜单只列出已启用且有 API Key 的 Provider，合并其默认模型、已配置模型和 Agent 绑定模型。同名模型存在于多个 Provider 时必须明确指定 Provider 或从菜单选择。
+- 可以输入未列出的自定义模型名称，但切换本身不验证模型是否真实可用；无认证本地接口仍需先保存其允许的非空占位 Key。
+- 选择从下一轮聊天请求起生效，只保存在当前终端进程内，不写入全局 Provider 或 Agent 绑定，也不随聊天记录恢复。`/clear` 和 `/resume` 不重置此覆盖，退出后重新进入则回到默认配置。
+- 显式选择只使用指定 Provider/模型，不自动回退到其他 Provider。默认模式按当前 Agent 绑定（没有时使用总控绑定）、备用 Provider、其余 Provider 的顺序尝试，跳过停用或无密钥的 Provider。`/agents` 切换 Agent 时，已有显式模型覆盖仍保留。
+- `/model refresh` 会使用已保存的凭据请求远端模型列表，但不发起推理；结果只合并到本次面板，不保存到 Provider 配置。部分 Provider 刷新失败会提示并保留已配置模型。
+- `chat` 和 `run` 没有 `--model` 参数；`init --model` 用于保存初始化配置，不是单轮覆盖。需要持久修改时使用工作台设置或重新执行 `agentdesk init`。
+
+### 工具审批与跨端同步
+
+- `git status`、`diff`、`log`、`show`、`rev-parse`、`ls-files` 等已识别的只读查询直接执行，包括由 `;`、`&&`、`||` 串联的只读 Git 查询。写入、提交、推送及未识别命令仍按具体操作审批。
+- 已批准或拒绝的审批收为一行记录，不再重复显示整个详情卡片。
+- 交互聊天遇到审批会弹出卡片，按 `y` 批准，按 `n` 或 `Esc` 拒绝；审批期间输入框暂停，连接保持不断开。`Ctrl+C` 中断当前轮次，不等同于批准。等待审批表示任务暂停，核对详情并按 y 后会继续执行；完成后返回输入状态。
+- 待审批卡片的标题与详情从顶部开始显示，不自动跟随末尾；内容过长时可用 `PgUp`/`PgDn` 翻页，也可用 `↑↓` 逐行滚动，超出视口时显示当前可见行范围与总行数。卡片顶部的「需要审批」和底部的「按 y 批准 · 按 n 或 Esc 拒绝」提示固定在滚动详情之外，翻页时仍保持可见；翻页不会提交审批决定。
+- 待审批数量及当前等待的审批决定每 1.5 秒轮询同步；在浏览器工作台或其他 CLI 中处理同一审批后，终端会同步结果并继续，不重复提交决定。
+- `/permissions` 只展示权限与审批。其他会话或工作流的待处理审批，可在工作台处理，或使用下面的 shell 命令。一次性聊天、任务事件流在非交互或 JSON 模式下遇到工具审批会明确拒绝，不自动授权。
 
 ```powershell
 agentdesk approvals
@@ -130,7 +210,29 @@ agentdesk approve <审批ID>
 agentdesk reject <审批ID>
 ```
 
-`chat` 仍使用实时对话。中断终端或断开连接会取消当前这一轮。持久化任务使用下面的 `run`，不走这条会随连接取消的路径。远程机器接入仍不在本版范围内。
+`chat` 仍使用实时对话。中断终端或断开连接会取消当前这一轮，已保存历史可续接。持久化任务使用下面的 `run`，不走这条会随连接取消的路径。
+
+## 电脑连接器与远程工作台
+
+需要先按 [Linux / 宝塔部署文档](../../deploy/cloud/README.md) 部署 HTTPS 网关与 Runner，配置所有者邮箱及 SMTP。手机登录后，在「公司电脑连接」创建配对码；电脑先通过本机工作台登记要授权的项目，再在交互终端执行：
+
+```powershell
+agentdesk connect pair --server https://agent.example.com
+agentdesk connect status
+agentdesk connect start
+```
+
+配对过程会列出本地项目供选择，要求电脑与手机核对设备指纹和项目范围并分别确认。配对码在隐藏输入中填写，不作为命令行参数。配对成功后，连接器随本地服务在后台发起出站连接；手机可在授权项目内发起任务、处理审批与 Git 操作。配对可能重启当前服务，存在未结束任务时会要求先处理任务，再执行 `connect start`。
+
+Windows 可安装当前用户登录后的自动启动和连接进程恢复：
+
+```powershell
+agentdesk connect install
+agentdesk connect uninstall
+agentdesk connect revoke
+```
+
+`uninstall` 移除登录自启动，`revoke` 断开并撤销本实例的设备连接；若服务器暂不可达，还应在手机设备页撤销记录。电脑睡眠、关机或离线时无法连接。本机 `web` 的一次性地址仍仅限本机使用。远程部署面向单个所有者，完整配对、取回改动与恢复流程以部署文档为准。
 
 ## 持久化任务
 
@@ -157,13 +259,13 @@ agentdesk resume <任务ID> --message "从失败的测试继续"
 - 带 `--plan` 的任务在方案获批后进入 `running`，这一步不会自动再开执行轮。批准后用 `run "按已批准方案执行" --conversation <任务ID>` 继续。方案和验收审批都用 `approvals`、`approve`、`reject` 处理。
 - `resume` 用于失败或已取消的任务。不传 `--message` 时使用「继续执行」，并把上次失败原因和已完成的工具摘要带进新的一轮。
 - 服务重启后，中断时仍标记为运行中的任务会标为失败，可用 `resume` 继续。尚未开始、仍在排队的运行会重新调度。
-- CLI 还没有单独的验收放弃或归档关闭命令。桌面端的「编码现场」可查看任务、执行事件与文件差异。
+- CLI 还没有单独的验收放弃或归档关闭命令。运行 `agentdesk web`，在「编码现场」查看任务、执行事件与文件差异。
 
 `status` 在服务未运行时返回非零退出码，`doctor` 在必要条件未就绪时返回非零退出码；聊天收到错误或未收到完成事件时同样返回非零退出码。
 
 ## 发行验证
 
-更新本地预览版时，先执行 `agentdesk stop`，在原安装目录重新安装新 tarball，再执行 `agentdesk start`。指定相同的 `--data-dir` 即继续使用已有配置和数据库；替换安装包不会自动删除用户数据。源码方式重新运行 `pnpm build:cli` 后重启服务。正式 npm 发布后的升级与版本兼容策略将在相应版本提供。
+更新时先执行 `agentdesk stop`，再运行 `npm install -g chuxin-agentdesk@latest`，最后执行 `agentdesk web`。若已更新安装包但旧服务还在运行，先执行 `agentdesk restart`。指定相同的 `--data-dir` 即继续使用已有配置和数据库；替换安装包不会自动删除用户数据。本地 tarball 更新使用相同流程；源码方式重新运行 `pnpm build:cli` 后重启服务。
 
 ```powershell
 pnpm --filter ./apps/cli test
@@ -171,9 +273,10 @@ pnpm --filter ./apps/cli typecheck
 pnpm build:cli
 pnpm --filter ./apps/cli test:dist
 pnpm --filter ./apps/cli test:package
+pnpm --filter @agentdesk/desktop test:cli-workbench
 ```
 
-先检查 tarball 文件列表，在仓库外安装并验证 help、start、认证、重复启动、init、chat、status、logs、restart 与 stop，再发布。已发布版本可用 `npm install -g chuxin-agentdesk` 安装。
+先检查 tarball 文件列表包含 `dist/web/index.html` 和前端资源，在仓库外安装并验证 help、start、浏览器连接、认证、重复启动、init、chat、status、logs、restart 与 stop，再发布。浏览器验证使用系统 Edge，可用 `E2E_BROWSER_CHANNEL` 指定已安装的 Chrome；`test:cli-workbench` 可附加已安装包目录，验证独立安装产物。
 
 ## TypeScript 开发入口
 

package/dist/autoloop/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 数字生命卡兹克
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.