# 装仔 CLI：安装与一键升级

发布方：丁满信息科技（上海）有限公司。CLI：0.7.0a9；升级程序：0.2.0。

给当前 AI Agent 的执行说明。用户说“安装装仔CLI”时走首次安装；说“更新装仔CLI和配套技能”时走升级。先用于桌面电脑，授权浏览器和 CLI 在同一台电脑。

## 1. 获取当前固定版本

- 安装/升级程序：https://timon-smart-app.oss-cn-shanghai.aliyuncs.com/official-site/agent/cli-pilot/0.7.0a9/5edbd6621a72ef2f/install-zhuangzai-cli.py
- 程序 SHA256：`5edbd6621a72ef2f06ec03912ab8bfd505491cf2f276505238361e648b0c7be7`
- 固定清单：https://timon-smart-app.oss-cn-shanghai.aliyuncs.com/official-site/agent/cli-pilot/0.7.0a9/956de399afece027/release.json
- 清单 SHA256：`956de399afece027038f0a06f630eadba03a30172a411257c2afc0a0c84439f5`

每次更新都重新读取本页，不能复用旧任务缓存的安装程序。下载到当前任务目录，用 Python 标准库 hashlib 核对完整 SHA256，匹配后执行。检查 Python 3.9 或更新版本；macOS 通常是 python3，Windows 可用 py -3。以下命令中的 python3 替换为已确认的入口。

## 2. 安装或升级

**WorkBuddy 桌面版首次安装**：

```sh
python3 install-zhuangzai-cli.py --workbuddy --connect
```

**更新装仔 CLI 和配套技能**：

```sh
python3 install-zhuangzai-cli.py --upgrade --workbuddy --connect
```

升级也可用于尚未安装的电脑。程序按顺序完成：

1. 校验并准备独立 CLI 环境和固定依赖，运行版本自检。
2. 更新六组配套技能，并把命令绑定到新版完整 Python 路径。
3. 更新自己托管的 `zhuangzai-cli` stdio 连接入口。保留其他连接、公司配置、env、超时设置和禁用状态。
4. 复用 CLI 自己已有的授权，实际查询当前公司和工地。有效授权不需要重新登录；失效或尚未授权时，打开一起装页面引导用户登录、选公司并授权。
5. 返回 CLI 版本、验证结果、需要刷新的客户端，以及保留的自定义文件（如有）。

程序记录安装清单和文件哈希。未修改的官方技能自动更新；用户修改过的技能和额外文件保留，新官方文件放在返回的 `incoming` 路径供对照，不擅自合并客户口径。遇到自定义连接入口也保留，说明需要核对的位置。不得把这些保留项说成已更新成功。

默认安装根目录 `~/.local/share/zhuangzai-cli`，WorkBuddy 技能目录 `~/.workbuddy/skills/`、配置文件 `~/.workbuddy/mcp.json`。先读取既有 `installation.json`；若不在默认根目录，从已安装技能绑定的完整 Python 入口定位其所属安装根目录，核对收据。有自定义安装路径时使用原来的 `--prefix`；有自定义宿主目录时沿用 `--skills-dir`、`--mcp-config`，不要另建一套默认安装。新版会同时更新安装收据中已登记的宿主路径。

旧官网 0.7.0a6、0.7.0a7 都可以直接升级。0.7.0a6 的技能目录尚未登记在收据中，需带上原来的 `--workbuddy` 或 `--skills-dir`；已登记的宿主目录会自动沿用。无法识别旧安装时停止并保留原文件，不删目录重装。CLI 自己的授权独立保存，程序不会从其他连接器复制凭据。

**其他桌面 Agent**：使用宿主明确支持的技能目录和 MCP JSON 配置文件，传入 `--skills-dir`、`--mcp-config`；不猜路径。首次配置若通过客户端界面完成，升级后按程序输出的 `run[0]` 更新该本地连接 command，args 为 `["-m","zhuangzai_cli","mcp"]`。没有传入配置文件的界面连接不会被程序自动改写。

## 3. 登录与刷新连接

需要登录时，保持当前进程运行，引导用户完成扫码或手机号登录、选择公司和授权。浏览器没有自动打开时，把该进程输出的授权链接交给用户，在同一台电脑打开，不另开第二个登录进程。

程序验证成功后，在当前客户端刷新或重启 `zhuangzai-cli` 连接；客户端要求信任连接时，由用户确认。需要时新建任务加载新版技能。通过这条连接调用 `get_company_context`，再调用 `list_projects`（page=1、pageSize=5），核对公司和工地。CLI 查询成功和宿主已加载连接分别核对，不能相互替代。多家公司、多条连接时不混用数据。

## 4. 保留任务与故障恢复

旧运行环境不删除。正在执行或尚未完成的任务沿用原来的 Python 入口和输出目录恢复；新任务使用新版。不要为了升级重复取数。

升级先备份再写入；写入或升级后的连接验证失败，会恢复上一版托管文件和配置，授权保留。中断后重跑同一命令可恢复。重复升级到同版且文件未变时，不再改写配置。

需要手动撤销最近一次升级时，用已下载并核验的程序执行：

```sh
python3 install-zhuangzai-cli.py --rollback
```

自定义根目录需加原 `--prefix`。回滚只读取本地备份，不联网；升级后又被用户修改的文件保留，提示手工对照。备份与安装收据在安装根目录，配置备份可能含敏感信息，不发送到聊天或上传。

## 5. 开始使用

本版月报的设备领用历史已接入服务端cursor：自动找到历史起点、取全后核验行数和SHA256，继续生成原标准报告；其他来源和客户口径保持原方式。

月报和派工履约按完整自然月；指定日期的问题、验收等专题使用技能提供的起止日期。先试：“分析这家公司上个月的派工履约情况，给我网页看板、Excel和管理重点。”CLI 尚未覆盖的灵活问题，沿用当前授权的 MCP 工具查询，不不断重试不支持的 CLI 命令。

完整报告的交付条件是 `verification.json` 为 PASS 且 releaseEligible=true。执行失败保留已落盘的任务，只恢复失败部分，不把失败当作没有数据。环境问题持续出现时保留错误和阶段，停止重复执行。
