aisc-cli 0.1.3__tar.gz → 0.1.9__tar.gz

{aisc_cli-0.1.3/src/aisc_cli.egg-info → aisc_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aisc-cli
-Version: 0.1.3
+Version: 0.1.9
 Summary: AISC CLI — Super Claude workstation management
 Author: AISC contributors
 License-Expression: MIT
@@ -33,23 +33,25 @@ Dynamic: license-file
 
 AISC 是一个在 Docker 容器中运行 Claude Code、OpenAI Codex 和 cc-switch 的个人开发工作站，提供两种使用方式：
 
-- **AISC Workbench（推荐）**——桌面应用（Windows）。图形界面完成工作区选择、镜像构建、容器启动、终端、文件管理、Provider 配置与诊断，适合绝大多数用户。
-- **AISC CLI（`aisc`）**——命令行入口。既随 Workbench 内置（作为后端 sidecar），也可独立安装用于脚本化与精细管理。
+- **AISC Workbench（推荐）**——桌面应用（Windows）。图形界面完成工作区选择、镜像构建、容器启动、终端、文件管理、Provider 配置与诊断；还可经 SSH 驱动装有 aisc 的远程机器（见[远程机器](#远程机器)）。
+- **AISC CLI（`aisc`）**——命令行入口。既随 Workbench 内置（作为后端 sidecar），也可独立安装用于脚本化、远程环境与精细管理。
 
 容器内的 AI CLI、Provider、凭据、路由和 Skills 均由 cc-switch 统一管理；宿主机不保存第二份凭据。
 
-> **状态：Alpha（0.x）。** 当前版本以仓库 [`VERSION`](https://github.com/wangyuncepu/AISC/blob/develop/src/aisc/VERSION) 与 [Releases](https://github.com/wangyuncepu/AISC/releases) 页为准。Alpha 版本的命令、配置和持久化契约仍可能变化，升级前请阅读 Release Notes 并备份重要工作区。Alpha 版本的命令、配置和持久化契约仍可能变化，升级前请阅读 Release Notes 并备份重要工作区。
+> **状态：Alpha（0.x）。** 当前版本：Workbench **v2.1.14** / CLI **0.1.3**（`pip install -U aisc-cli`）。命令、配置和持久化契约仍可能变化，升级前请阅读 [Releases](https://github.com/Wifabric/AISC/releases) 的 Release Notes 并备份重要工作区。
 
 ## 目录
 
 - [安全边界](#安全边界)
 - [安装前提](#安装前提)
 - [Workbench 使用指南](#workbench-使用指南)
+- [远程机器](#远程机器)
 - [CLI 使用指南](#cli-使用指南)
 - [配置与持久化](#配置与持久化)
 - [升级](#升级)
 - [卸载](#卸载)
 - [故障排查](#故障排查)
+- [反馈渠道](#反馈渠道)
 - [许可](#许可)
 - [推荐服务](#推荐服务)
 
@@ -66,7 +68,7 @@ AISC 以开发便利为优先，不是生产级安全沙箱：
 
 ## 安装前提
 
-运行 AISC 需要自行安装并启动 **Docker**（AISC 不代装，检测到缺失时会给出指引）：
+运行 AISC 需要自行安装并启动 **Docker**（AISC 不代装，检测到缺失时会给出指引；Windows 安装器可一键引导安装 Docker/Python/WebView2）：
 
 | 平台 | 官方产物 | Docker |
 | --- | --- | --- |
@@ -88,7 +90,7 @@ docker version
 
 ### 安装
 
-从 [GitHub Releases](https://github.com/wangyuncepu/AISC/releases) 下载 Windows 安装器（`AISC Workbench_<版本>_x64-setup.exe`）及 `.sha256`，校验后运行。安装器默认写入 `%LOCALAPPDATA%\Programs\AISC`，并添加用户 `PATH`。
+从 [GitHub Releases](https://github.com/Wifabric/AISC/releases) 下载 Windows 安装器（`AISC Workbench_<版本>_x64-setup.exe`）及 `.sha256`，校验后运行。安装器默认写入 `%LOCALAPPDATA%\Programs\AISC`，并添加用户 `PATH`。
 
 AISC 尚未代码签名。SmartScreen 提示时，请先确认文件来自项目 Release 且 SHA256 正确，再选择“更多信息 -> 仍要运行”。
 
@@ -96,25 +98,29 @@ AISC 尚未代码签名。SmartScreen 提示时，请先确认文件来自项目
 
 1. **启动 Workbench**——直接进入工作区选择页（无强制引导）。
 2. **选择工作区**——输入或浏览一个空目录/项目目录作为工作区；最近使用的工作区会列在下方（上限 8 条 + 展开更多；失效路径可一键清除记录，绝不触碰磁盘文件）。
-3. **构建工作站镜像**——首次使用会引导构建镜像。构建页显示实时进度与百分比，完整日志可展开、可定位到磁盘日志文件；初次构建通常需要 10–20 分钟。构建可随时取消。网络受限环境下会自动回退国内镜像源继续构建（页面会明确提示“未钉版”）。
+3. **构建工作站镜像**——首次使用会引导构建镜像。构建页显示实时进度与百分比，完整日志可展开、可定位到磁盘日志文件；初次构建通常需要 10–20 分钟，构建可随时取消。构建与宿主网络环境解耦：npm 主包与 yazi 已预置进安装器（GitHub 完全不可达也能离线完成构建），其余下载受限时自动回退国内镜像源（页面会明确提示“未钉版”）。
 4. **启动运行时**——点击「启动」。首次启动需初始化容器环境（最长约 3 分钟，页面有进度提示）；之后启动快得多。
 5. **进入工作区**——左侧为资源管理器与「变更」面板，右侧为终端区。
 
 ### 日常使用
 
-- **终端**：`bash` / `claude` / `codex` 多页签，支持分屏；首次进入有上手速查卡，容器内输入 `help` 查看常用操作。`Ctrl+Shift+V` 粘贴、`Ctrl+F` 终端内搜索。
+- **终端**：`bash` / `claude` / `codex` 多页签，支持分屏；首次进入有上手速查卡，容器内输入 `help` 查看常用操作。`Ctrl+Shift+V` 粘贴、`Ctrl+F` 终端内搜索、`Ctrl+Alt+hjkl`（或方向键）移动分屏焦点、`Ctrl+Shift+W` 关闭当前分屏。codex 中 `Ctrl+/` 可在 `/btw` 旁路与主线对话间往返切换。
 - **资源管理器（文件）**：目录树懒加载、右键新建/重命名/复制/粘贴、拖拽文件进终端（自动转容器路径）、顶部搜索（支持模糊与 `/正则/`）。
 - **变更面板**：Agent 产出与文件改动统一呈现——徽章区分类型（新增/修改/删除/移动）与来源（Agent 登记或系统检测），支持分类筛选与搜索。
+- **历史会话**：会话列表可查看聊天式只读对话记录（claude/codex 双侧）。
+- **工作记录**：把 provider 会话聚合成 Work Record / Collection。active Collection 自动收容新开的 Claude/Codex 会话；支持重命名、设为 Active、归档/恢复、手动加入/移出。删除 Collection 前会普通确认一次，然后级联删除成员 transcript；删除失败会列出成员、阶段和原因。`bash` / `cc-switch` 不进入工作记录。
 - **服务面板**：容器内通过 `aisc-web-expose <端口>` 注册的 Web 服务，可从面板一键在宿主浏览器打开。
-- **Provider 管理**：顶栏进入 Providers 页。镜像已预置常见供应商（见下），点击行即可激活；填入 API Key 即可使用，切换即时生效，无需重启。
+- **Provider 管理**：顶栏进入 Providers 页。基于内置模板清单添加（见下），填入 API Key 即可使用，切换即时生效、无需重启；添加时可直接「拉取模型」验证 Key 与端点（无效 Key 会明确报「API Key 无效或被上游拒绝」）。
 - **网络与用量**（设置页）：代理模式可导入机场订阅（自动转换为容器 TUN 配置）；用量面板聚合各工作区 token 消耗与余量。
-- **多工作区**：最多同时打开 3 个工作区，页签条切换；关闭即自动停止并清理对应容器。
+- **Docker 资源管理**（设置页）：AISC 名下容器/镜像的扫描、清理与重建；破坏性操作仅限 AISC 自有资产，绝不触碰其它容器/镜像。
+- **多工作区**：最多同时打开 3 个工作区，页签条切换；关闭即自动停止并清理对应容器。顶栏「关闭工作区」可随时回到选择页重选（清理运行环境，窗口保留）。
 - **彻底忘记工作区**：工作区历史右键 -> 彻底忘记，单事务清理 AISC 数据根内该工作区的状态与记录（容器先停止删除，失败自动回滚）；你磁盘上的原始文件永不被触碰。
 - **诊断**：任何页面可打开诊断对话框（环境检查、最近日志、导出诊断包）。
+- **应用自更新**：设置页「检查更新」直接升级——下载带可视化进度条，确认后静默安装并**自动重启**新版（升级链含镜像重建，最长约 30 分钟）。
 
-### 预配置供应商
+### Provider 模板清单
 
-镜像内置以下预置 Provider，用户只需填 API Key：
+「添加 provider」时镜像内置以下模板，用户只需填 API Key：
 
 | 供应商 | 说明 |
 | --- | --- |
@@ -125,7 +131,21 @@ AISC 尚未代码签名。SmartScreen 提示时，请先确认文件来自项目
 | **Codesome V3** | 月卡/按量中转（`sk-` Key，后台建 Key 选分组） |
 | **Codesome 二合一** | V5 月卡中转（`cr-` 卡密即 Key，Claude/GPT 双端通用） |
 
-2.1.12 起（D-6.7）镜像**不再预置**任何 provider 行——以上为「添加 provider」的模板清单（Codesome 置顶默认）。所有模板的 Codex 上游走 S9a 形态（本地路由把 Responses 翻译为 Anthropic Messages，直连模板声明的 Anthropic 端点）；Codesome 两模板的 Claude 侧不含模型键（官方要求，模型由 Key 的服务端分组路由），并预填官方推荐的自动压缩水位（claude 150k / codex 900k）。
+模板模式下模型映射/模型目录随首次保存生效；手动填写的端点不会被模板清单静默改写。模板的 Codex 上游走 S9a 形态（本地路由把 Responses 翻译为 Anthropic Messages，直连模板声明的 Anthropic 端点）；Codesome 两模板的 Claude 侧不含模型键（官方要求，模型由 Key 的服务端分组路由），并预填官方推荐的自动压缩水位（claude 150k / codex 900k）。也支持自定义 Provider（OpenAI 兼容格式，端点/模型/上下文窗口全手填）。
+
+## 远程机器
+
+Workbench 可以像操作本机一样驱动远程机器上的工作站：在远程机器上安装 aisc CLI 并保持 SSH 可达，Workbench 通过 `ssh <机器> aisc serve` 通道执行构建、运行、Provider 等操作，构建产物与容器都在远程机器上。
+
+**远程机器侧准备**（一次性）：
+
+1. 安装 Docker 与 aisc CLI：`pipx install aisc-cli`（或见[CLI 独立安装](#独立安装)）；
+2. 配置 SSH 密钥认证——Workbench **仅支持密钥登录，不支持密码**：
+   - 本机 `ssh-keygen -t ed25519` 生成密钥（口令可留空）；
+   - 把公钥 `~/.ssh/id_ed25519.pub` 追加到远程机器的 `~/.ssh/authorized_keys`；
+   - 首次连接先在终端手动 `ssh` 一次，确认主机指纹。
+
+**Workbench 侧**：设置页「远程机器」填名称 / 主机 / 用户 / 端口 / 私钥路径；之后在**选择工作区页顶部切换目标机器**即可。设置页还提供远程 CLI 版本检测：与本机 CLI 比对并显示「需更新 / 版本一致 / 远程较新」软提示（不阻断使用），需要更新时会给出可复制的升级命令（如 `pip install -U aisc-cli`）。远程 CLI 版本过旧导致协议不匹配时，连接会明确报协议版本不符。
 
 ## CLI 使用指南
 
@@ -133,6 +153,21 @@ CLI 适合脚本化、远程环境或不使用 GUI 的场景。Workbench 安装
 
 ### 独立安装
 
+**pip / pipx（0.1.0 起，最常用）**：
+
+```bash
+pipx install aisc-cli        # 首选：自动隔离 + 独立 bin 目录（Windows 同样适用）
+# 或 uv tool install aisc-cli / 裸 pip（请在 venv 内）
+```
+
+三点须知：① 分发名是 `aisc-cli`，但命令仍是 `aisc`；② **需要自备 Docker**，装完先跑 `aisc doctor`；③ pip 安装**不含构建资源**——`aisc build` / `maintenance docker-rebuild` 前需先 `aisc bundle fetch`（从 GitHub Releases 拉同版本 bundle 到数据根）；此时 `aisc version` 的 `bundle_version=null` 与 `doctor` 的 aisc-bundle WARN 属预期。
+
+安装陷阱 FAQ：
+
+- **`EXTERNALLY-MANAGED`（PEP 668）**：系统 Python 拒绝裸装 → 改用 `pipx install aisc-cli`。
+- **Windows 裸 pip `--user`**：Scripts 目录（`%APPDATA%\Python\Scripts`）默认不在 PATH → 把它加入 PATH 或改用 pipx。
+- **`python -m aisc`**：永远可用，是 shim 失效时的诊断后门。
+
 **Linux x86_64**（便携）：
 
 ```bash
@@ -155,28 +190,13 @@ bash packaging/install.sh /path/to/AISC-<ver>-linux-x86_64.tar.gz
 **从源码**：
 
 ```bash
-git clone https://github.com/wangyuncepu/AISC.git
+git clone https://github.com/Wifabric/AISC.git
 cd AISC
 uv tool install --editable .
 ```
 
 editable 安装记录仓库绝对路径，移动仓库前先 `uv tool uninstall aisc`。
 
-**pip / pipx（0.1.0 起）**：
-
-```bash
-pipx install aisc-cli        # 首选：自动隔离 + 独立 bin 目录（Windows 同样适用）
-# 或 uv tool install aisc-cli / 裸 pip（请在 venv 内）
-```
-
-三点须知：① 分发名是 `aisc-cli`，但命令仍是 `aisc`；② **需要自备 Docker**，装完先跑 `aisc doctor`；③ pip 安装**不含构建资源**——`aisc build` / `maintenance docker-rebuild` 前需先 `aisc bundle fetch`（从 GitHub Releases 拉同版本 bundle 到数据根）；此时 `aisc version` 的 `bundle_version=null` 与 `doctor` 的 aisc-bundle WARN 属预期。
-
-安装陷阱 FAQ：
-
-- **`EXTERNALLY-MANAGED`（PEP 668）**：系统 Python 拒绝裸装 → 改用 `pipx install aisc-cli`。
-- **Windows 裸 pip `--user`**：Scripts 目录（`%APPDATA%\Python\Scripts`）默认不在 PATH → 把它加入 PATH 或改用 pipx。
-- **`python -m aisc`**：永远可用，是 shim 失效时的诊断后门。
-
 ### 快速开始
 
 ```bash
@@ -201,7 +221,7 @@ aisc run --workspace /path/to/project
 - 镜像为 `super-claude:latest`，工作区为当前目录并挂载到 `/root/app`。
 - 网络为 `direct`。
 - 前台交互终端 `-it`，容器退出后由 `--rm` 自动删除。
-- 自动生成 `<name>-<8位十六进制>` 容器名，并登记到 registry。
+- 自动生成 `<name>-<8位十六进制>` 容器名，并登记到 registry；已有同工作区容器在运行时拒绝重复进入（防重入守卫）。
 
 容器初始化时先选择作用域：
 
@@ -245,30 +265,37 @@ aisc run --non-interactive   # 脚本/CI：无 TTY，项目作用域
 | --- | --- | --- |
 | `aisc version` | 全局选项 | 显示 CLI、Python、bundle 和声明依赖版本信息 |
 | `aisc doctor` | 全局选项 | 只读检查 Docker、权限、buildx、TUN、Git、资源根和目录可写性 |
-| `aisc build` | `--tag/-t`, `--no-cache`, `--pull`, `--dry-run`, `--require-pin` | 构建镜像；默认 tag 为 `super-claude:latest` |
-| `aisc run` | `--image/-i`, `--workspace`, `--name`, `--label`, `--network`, `--keep-alive`, `--non-interactive`, `--dry-run` | 启动并登记容器 |
+| `aisc build` | `--tag/-t`, `--no-cache`, `--pull`, `--dry-run`, `--require-pin` | 构建镜像；默认 tag 为 `super-claude:latest`；网络受限时预置/镜像源保底 |
+| `aisc run` | `--image/-i`, `--workspace`, `--name`, `--label`, `--network`, `--keep-alive`, `--non-interactive`, `--dry-run` | 启动并登记容器（防重入） |
 | `aisc ps` | 全局选项 | 列出 registry 中容器的 label、实时状态、镜像和工作区 |
 | `aisc status` | `--name`, `--label` | 查看目标容器状态 |
-| `aisc stop` | `--name`, `--label` | 停止目标容器；已停止时幂等成功 |
-| `aisc restart` | `--name`, `--label` | 重启目标容器 |
+| `aisc stop` / `aisc restart` | `--name`, `--label` | 停止（幂等）/ 重启目标容器 |
 | `aisc shell` | `--name`, `--label` | 执行 `docker exec -it <name> bash` |
 | `aisc session open` | — | 打开托管会话终端（Workbench 内部使用同一通道） |
+| `aisc serve` | — | 长驻远程通道（stdin/stdout JSON 帧协议；Workbench 经 SSH 调用，一般无需手动运行） |
 | `aisc switch` | `--name`, `--label`, `--quick PROVIDER` | 打开 cc-switch TUI，或快速切换 Claude Provider |
 | `aisc provider set-key` | `PROVIDER_ID`, `--name`, `--label`, `--agent` | 打开 cc-switch provider 安全交互编辑器；凭据不进命令行参数 |
+| `aisc conversation read` | 会话定位参数 | 聊天式只读对话查看器（历史会话阅读） |
+| `aisc work-record list/reconcile` | `--workspace` | 列出或重新对账 Work Record / Collection 与未归档会话 |
+| `aisc work-record create/rename/activate/deactivate/archive/restore` | `--workspace`, `--title`, `--collection-id` 等 | 管理 Work Record 元数据与生命周期 |
+| `aisc work-record add/remove/delete` | `--workspace`, `--collection-id`, `--agent`, `--conversation-id` 等 | 手动整理成员或级联删除 Collection（CLI 只删除 transcript；live PTY 由 Workbench 预先编排关闭） |
+| `aisc worklog list/rename/archive` | `--id` 等 | 工作区 PTY 会话账本（开关钩子自动记账，fail-open） |
 | `aisc config validate/effective` | `--config`, `--workspace` | 校验/展示合并配置与来源 |
 | `aisc profile list/show` | 全局选项 | 只读列出/显示 Profile |
 | `aisc logs show/path` | `--source app\|cli\|ui\|all` | 查看统一 JSONL 日志时间线 |
 | `aisc usage overview` | 全局选项 | 跨工作区聚合用量 |
 | `aisc network subscription …` | `import/import-file/refresh/show/clear` | 代理订阅数据面（URL 与内容走 stdin） |
-| `aisc maintenance docker-scan/cleanup/rebuild` | `--context`, `--root`, `--tag` | Docker 资源归属扫描/清理/重建（卸载与升级同一服务） |
+| `aisc maintenance docker-scan/cleanup/rebuild` | `--context`, `--root`, `--tag` | Docker 资源归属扫描/清理/重建（owned-only，卸载与升级同一服务） |
+| `aisc maintenance container-action/image-rm/image-tag` | `--id` 等 | AISC 自有容器的启动/停止/删除、镜像删除与重命名（仅 owned 资源，执行前锁内重扫判权） |
 | `aisc bundle fetch/list/remove/path` | `--version`, `--from-file`, `--sha256`, `--allow-mismatch` | pip 安装的构建资源管理：从 GitHub Releases 拉取同版本 bundle 到数据根（API digest 校验、fail-closed、离线 --from-file） |
-| `aisc update` | `--check`, `--version`, `--from-file`, `--sha256`, `--rebuild` | CLI 自更新（冻结形态：rename dance 原子换 exe+相邻 bundle，旧件保留可回退；pip 形态给 pipx 指引；Workbench 池 mtime 驱逐免重启生效；`--pin-tool KEY=VALUE` 钉工具版本于数据根用户层、更新不丢；`--check` 附三工具版本对照） |
+| `aisc update` | `--check`, `--version`, `--from-file`, `--sha256`, `--rebuild` | CLI 自更新：`--check` 查看计划。**不再从网络下载 CLI 归档**——pip/pipx 形态走各自渠道（`pipx upgrade aisc-cli` 或 venv 内 `pip install -U aisc-cli`）；便携/冻结形态可用 `--from-file <archive> --sha256 <hex>` 本地换装；Workbench 内置 CLI 随安装器自更新 |
 
 多容器寻址顺序：显式 `--name` -> 唯一匹配的 `--label` -> registry 默认目标 -> 唯一登记容器；无法消歧时列出候选并要求指定。
 
 构建相关补充：
 
-- 网络受限时，cc-switch 版本解析按「在线 → 缓存 → 本地回执 → 无钉版国内镜像源构建」递进；`--require-pin`（或 `AISC_REQUIRE_PIN=1`）恢复严格失败。
+- 网络受限时按「在线 → 缓存 → 本地回执 → 国内镜像源」递进；npm 主包与 yazi 已预置，GitHub 全阻亦可完成构建；`--require-pin`（或 `AISC_REQUIRE_PIN=1`）恢复严格失败。
+- 构建失败时会给出网络归因诊断与三条出路（本地预置 / 显式代理 `GH_PROXY` / 容器 TUN）。
 - `aisc build --events` 输出 JSONL 进度事件（`build.progress` 等），供前端/脚本消费。
 
 ### 容器内使用
@@ -323,12 +350,12 @@ Workbench 与 CLI 共享统一数据根：
 
 ## 升级
 
-- **Windows Workbench**：运行新版安装器覆盖安装。安装器会先停止并删除 AISC 管理的容器，替换文件后对默认镜像执行**无缓存重建**（可能需要几分钟），成功后清理旧镜像；Docker 不可用时文件照常更新，镜像重建转为待办并给出手动命令。
+- **Windows Workbench**：推荐应用内「设置 -> 检查更新」直接升级——下载（带进度条）→ 确认 → 静默安装 → 自动重建镜像 → **自动重启新版**。也可手动运行新版安装器覆盖安装（效果相同）。升级会先停止并删除 AISC 管理的容器，替换文件后对默认镜像执行**无缓存重建**（可能需要几分钟到 30 分钟）；Docker 不可用时文件照常更新，镜像重建转为待办并给出手动命令。用户配置、工作区状态与持久工具链全部保留。
 - **macOS PKG / 便携脚本**：覆盖安装或重新执行 `packaging/install.sh <new-archive>`。
 - **uv tool**：`git pull` 后 `uv tool upgrade aisc` 或重装；镜像内容变化时需重新 `aisc build`。
-- **pipx/pip**：`pipx upgrade aisc-cli`（或 venv 内 `pip install -U aisc-cli`）；新版 bundle 用 `aisc bundle fetch` 更新（更新镜像再 `aisc maintenance docker-rebuild`）。CLI 自身更新也可用 `aisc update`（冻结形态适用）。
+- **pipx/pip**：`pipx upgrade aisc-cli`（或 venv 内 `pip install -U aisc-cli`）；新版 bundle 用 `aisc bundle fetch` 更新（更新镜像再 `aisc maintenance docker-rebuild`）。
 
-用户配置、工作区状态与持久工具链在升级中全部保留。
+注：Workbench 内置的 CLI 随安装器一同更新（无独立升级通道）；远程机器上的 CLI 用 `pipx upgrade aisc-cli` / `pip install -U aisc-cli` 独立升级。
 
 ## 卸载
 
@@ -372,18 +399,25 @@ Workbench 内：打开诊断对话框查看环境检查与最近日志，可导
 | --- | --- |
 | 找不到 `aisc` | 重开终端；Linux/macOS 确认 `~/.local/bin` 在 `PATH`；便携包保持 `aisc` 与 `aisc-bundle/` 相邻 |
 | Docker 未运行 | 启动 Docker Desktop / Engine；Workbench 摘要页有「启动 Docker」唤起与自动重试 |
-| Docker 未安装 | 自行安装（见[安装前提](#安装前提)）；Workbench 会给出指引并自动识别 |
+| Docker 未安装 | 自行安装（见[安装前提](#安装前提)）；Windows 安装器可一键引导安装 |
 | `Image not found` | 先构建镜像（Workbench 构建页或 `aisc build`） |
-| 构建卡在下载/网络受限 | v2.1.7 起自动回退国内镜像源；仍失败时查看构建日志的真实错误原因 |
+| 构建失败（网络受限） | v2.1.14 起 npm 主包/yazi 已预置，GitHub 全阻也能离线构建，其余下载自动回退国内镜像源；仍失败时看构建日志末尾的网络归因提示（本地预置 / 显式代理 `GH_PROXY` / 容器 TUN 三出路） |
 | 首次启动很久 | 首启需初始化容器环境（最长约 3 分钟）；二次启动恢复正常速度 |
 | Windows 报「无可用网关端口」(47000-47999) | WSL2 系统级端口保留所致：管理员执行 `wsl --shutdown`，再 `netsh int ipv4 add excludedportrange protocol=tcp startport=47000 numberofports=1000`，然后重启 Docker Desktop |
 | cc-switch daemon/路由异常 | 容器内 `cc-switch daemon status` / `proxy show`；daemon 日志在 `/tmp/cc-switch-daemon.log` |
+| 远程机器连不上 | 确认 SSH 密钥认证已配置（不支持密码登录）；远程 `aisc` 在 PATH 上；协议版本不符时按设置页提示升级远程 CLI |
+| `aisc update` 报「不再下载 CLI 归档」 | 属预期：pip/pipx 渠道用 `pipx upgrade aisc-cli` / `pip install -U aisc-cli`；Workbench 内置 CLI 随安装器更新 |
+
+提交问题时附上操作系统、CPU 架构、Docker 版本、`aisc version`、复现命令和已脱敏日志。不要上传 API Key、Cookie、登录令牌、Provider 数据库或完整配置目录。
+
+## 反馈渠道
 
-提交 [GitHub Issues](https://github.com/wangyuncepu/AISC/issues) 时附上操作系统、CPU 架构、Docker 版本、`aisc version`、复现命令和已脱敏日志。不要上传 API Key、Cookie、登录令牌、Provider 数据库或完整配置目录。
+- **GitHub Issues**：[github.com/Wifabric/AISC/issues](https://github.com/Wifabric/AISC/issues)——适合功能讨论与明确 bug。
+- **反馈站**：[feedback.alanevergarden.xyz](https://feedback.alanevergarden.xyz)——网页表单提交（可带截图与日志附件），处理进度公开可见；提交后在反馈站查看开发者回复与版本修复情况。
 
 ## 许可
 
-MIT License，详见 [LICENSE](https://github.com/wangyuncepu/AISC/blob/main/LICENSE)。镜像还包含第三方组件，其来源、校验和与许可证记录在 `vendor/` 中。
+MIT License，详见 [LICENSE](https://github.com/Wifabric/AISC/blob/main/LICENSE)。镜像还包含第三方组件，其来源、校验和与许可证记录在 `vendor/` 中。
 
 ## 推荐服务
 
@@ -393,7 +427,7 @@ MIT License，详见 [LICENSE](https://github.com/wangyuncepu/AISC/blob/main/LIC
 
 Codesome 提供 API 调用形式的接入服务，有两条产品线：**V3**（Claude/GPT 月卡 + 按量，`sk-...` Key，在后台建 Key 并选分组）与**二合一/V5**（月卡，订单里的 `cr-...` 卡密直接就是 Key，Claude/GPT 双端通用，无分组）。这是 API 服务，不是 Claude 或 Codex 成品账号。
 
-**2.1.12 起内置两个 Codesome 模板**（`codesome-v3` / `codesome-2in1`）——Workbench Providers 页「添加 provider」默认选中 Codesome，选对产品线、填入 Key 即可（表单下方「获取服务」直达注册/购买页）。两条线的地址不可混用，V3 的 `sk-` Key 不能配二合一，反之亦然。
+**AISC 内置两个 Codesome 模板**（`codesome-v3` / `codesome-2in1`）——Workbench Providers 页「添加 provider」默认选中 Codesome，选对产品线、填入 Key 即可（表单下方「获取服务」直达注册/购买页）。两条线的地址不可混用，V3 的 `sk-` Key 不能配二合一，反之亦然。
 
 手动配置时的端点（两线各自两端通用，URL 不同不可混用）：
 

{aisc_cli-0.1.3 → aisc_cli-0.1.9}/README.md

@@ -2,23 +2,25 @@
 
 AISC 是一个在 Docker 容器中运行 Claude Code、OpenAI Codex 和 cc-switch 的个人开发工作站，提供两种使用方式：
 
-- **AISC Workbench（推荐）**——桌面应用（Windows）。图形界面完成工作区选择、镜像构建、容器启动、终端、文件管理、Provider 配置与诊断，适合绝大多数用户。
-- **AISC CLI（`aisc`）**——命令行入口。既随 Workbench 内置（作为后端 sidecar），也可独立安装用于脚本化与精细管理。
+- **AISC Workbench（推荐）**——桌面应用（Windows）。图形界面完成工作区选择、镜像构建、容器启动、终端、文件管理、Provider 配置与诊断；还可经 SSH 驱动装有 aisc 的远程机器（见[远程机器](#远程机器)）。
+- **AISC CLI（`aisc`）**——命令行入口。既随 Workbench 内置（作为后端 sidecar），也可独立安装用于脚本化、远程环境与精细管理。
 
 容器内的 AI CLI、Provider、凭据、路由和 Skills 均由 cc-switch 统一管理；宿主机不保存第二份凭据。
 
-> **状态：Alpha（0.x）。** 当前版本以仓库 [`VERSION`](https://github.com/wangyuncepu/AISC/blob/develop/src/aisc/VERSION) 与 [Releases](https://github.com/wangyuncepu/AISC/releases) 页为准。Alpha 版本的命令、配置和持久化契约仍可能变化，升级前请阅读 Release Notes 并备份重要工作区。Alpha 版本的命令、配置和持久化契约仍可能变化，升级前请阅读 Release Notes 并备份重要工作区。
+> **状态：Alpha（0.x）。** 当前版本：Workbench **v2.1.14** / CLI **0.1.3**（`pip install -U aisc-cli`）。命令、配置和持久化契约仍可能变化，升级前请阅读 [Releases](https://github.com/Wifabric/AISC/releases) 的 Release Notes 并备份重要工作区。
 
 ## 目录
 
 - [安全边界](#安全边界)
 - [安装前提](#安装前提)
 - [Workbench 使用指南](#workbench-使用指南)
+- [远程机器](#远程机器)
 - [CLI 使用指南](#cli-使用指南)
 - [配置与持久化](#配置与持久化)
 - [升级](#升级)
 - [卸载](#卸载)
 - [故障排查](#故障排查)
+- [反馈渠道](#反馈渠道)
 - [许可](#许可)
 - [推荐服务](#推荐服务)
 
@@ -35,7 +37,7 @@ AISC 以开发便利为优先，不是生产级安全沙箱：
 
 ## 安装前提
 
-运行 AISC 需要自行安装并启动 **Docker**（AISC 不代装，检测到缺失时会给出指引）：
+运行 AISC 需要自行安装并启动 **Docker**（AISC 不代装，检测到缺失时会给出指引；Windows 安装器可一键引导安装 Docker/Python/WebView2）：
 
 | 平台 | 官方产物 | Docker |
 | --- | --- | --- |
@@ -57,7 +59,7 @@ docker version
 
 ### 安装
 
-从 [GitHub Releases](https://github.com/wangyuncepu/AISC/releases) 下载 Windows 安装器（`AISC Workbench_<版本>_x64-setup.exe`）及 `.sha256`，校验后运行。安装器默认写入 `%LOCALAPPDATA%\Programs\AISC`，并添加用户 `PATH`。
+从 [GitHub Releases](https://github.com/Wifabric/AISC/releases) 下载 Windows 安装器（`AISC Workbench_<版本>_x64-setup.exe`）及 `.sha256`，校验后运行。安装器默认写入 `%LOCALAPPDATA%\Programs\AISC`，并添加用户 `PATH`。
 
 AISC 尚未代码签名。SmartScreen 提示时，请先确认文件来自项目 Release 且 SHA256 正确，再选择“更多信息 -> 仍要运行”。
 
@@ -65,25 +67,29 @@ AISC 尚未代码签名。SmartScreen 提示时，请先确认文件来自项目
 
 1. **启动 Workbench**——直接进入工作区选择页（无强制引导）。
 2. **选择工作区**——输入或浏览一个空目录/项目目录作为工作区；最近使用的工作区会列在下方（上限 8 条 + 展开更多；失效路径可一键清除记录，绝不触碰磁盘文件）。
-3. **构建工作站镜像**——首次使用会引导构建镜像。构建页显示实时进度与百分比，完整日志可展开、可定位到磁盘日志文件；初次构建通常需要 10–20 分钟。构建可随时取消。网络受限环境下会自动回退国内镜像源继续构建（页面会明确提示“未钉版”）。
+3. **构建工作站镜像**——首次使用会引导构建镜像。构建页显示实时进度与百分比，完整日志可展开、可定位到磁盘日志文件；初次构建通常需要 10–20 分钟，构建可随时取消。构建与宿主网络环境解耦：npm 主包与 yazi 已预置进安装器（GitHub 完全不可达也能离线完成构建），其余下载受限时自动回退国内镜像源（页面会明确提示“未钉版”）。
 4. **启动运行时**——点击「启动」。首次启动需初始化容器环境（最长约 3 分钟，页面有进度提示）；之后启动快得多。
 5. **进入工作区**——左侧为资源管理器与「变更」面板，右侧为终端区。
 
 ### 日常使用
 
-- **终端**：`bash` / `claude` / `codex` 多页签，支持分屏；首次进入有上手速查卡，容器内输入 `help` 查看常用操作。`Ctrl+Shift+V` 粘贴、`Ctrl+F` 终端内搜索。
+- **终端**：`bash` / `claude` / `codex` 多页签，支持分屏；首次进入有上手速查卡，容器内输入 `help` 查看常用操作。`Ctrl+Shift+V` 粘贴、`Ctrl+F` 终端内搜索、`Ctrl+Alt+hjkl`（或方向键）移动分屏焦点、`Ctrl+Shift+W` 关闭当前分屏。codex 中 `Ctrl+/` 可在 `/btw` 旁路与主线对话间往返切换。
 - **资源管理器（文件）**：目录树懒加载、右键新建/重命名/复制/粘贴、拖拽文件进终端（自动转容器路径）、顶部搜索（支持模糊与 `/正则/`）。
 - **变更面板**：Agent 产出与文件改动统一呈现——徽章区分类型（新增/修改/删除/移动）与来源（Agent 登记或系统检测），支持分类筛选与搜索。
+- **历史会话**：会话列表可查看聊天式只读对话记录（claude/codex 双侧）。
+- **工作记录**：把 provider 会话聚合成 Work Record / Collection。active Collection 自动收容新开的 Claude/Codex 会话；支持重命名、设为 Active、归档/恢复、手动加入/移出。删除 Collection 前会普通确认一次，然后级联删除成员 transcript；删除失败会列出成员、阶段和原因。`bash` / `cc-switch` 不进入工作记录。
 - **服务面板**：容器内通过 `aisc-web-expose <端口>` 注册的 Web 服务，可从面板一键在宿主浏览器打开。
-- **Provider 管理**：顶栏进入 Providers 页。镜像已预置常见供应商（见下），点击行即可激活；填入 API Key 即可使用，切换即时生效，无需重启。
+- **Provider 管理**：顶栏进入 Providers 页。基于内置模板清单添加（见下），填入 API Key 即可使用，切换即时生效、无需重启；添加时可直接「拉取模型」验证 Key 与端点（无效 Key 会明确报「API Key 无效或被上游拒绝」）。
 - **网络与用量**（设置页）：代理模式可导入机场订阅（自动转换为容器 TUN 配置）；用量面板聚合各工作区 token 消耗与余量。
-- **多工作区**：最多同时打开 3 个工作区，页签条切换；关闭即自动停止并清理对应容器。
+- **Docker 资源管理**（设置页）：AISC 名下容器/镜像的扫描、清理与重建；破坏性操作仅限 AISC 自有资产，绝不触碰其它容器/镜像。
+- **多工作区**：最多同时打开 3 个工作区，页签条切换；关闭即自动停止并清理对应容器。顶栏「关闭工作区」可随时回到选择页重选（清理运行环境，窗口保留）。
 - **彻底忘记工作区**：工作区历史右键 -> 彻底忘记，单事务清理 AISC 数据根内该工作区的状态与记录（容器先停止删除，失败自动回滚）；你磁盘上的原始文件永不被触碰。
 - **诊断**：任何页面可打开诊断对话框（环境检查、最近日志、导出诊断包）。
+- **应用自更新**：设置页「检查更新」直接升级——下载带可视化进度条，确认后静默安装并**自动重启**新版（升级链含镜像重建，最长约 30 分钟）。
 
-### 预配置供应商
+### Provider 模板清单
 
-镜像内置以下预置 Provider，用户只需填 API Key：
+「添加 provider」时镜像内置以下模板，用户只需填 API Key：
 
 | 供应商 | 说明 |
 | --- | --- |
@@ -94,7 +100,21 @@ AISC 尚未代码签名。SmartScreen 提示时，请先确认文件来自项目
 | **Codesome V3** | 月卡/按量中转（`sk-` Key，后台建 Key 选分组） |
 | **Codesome 二合一** | V5 月卡中转（`cr-` 卡密即 Key，Claude/GPT 双端通用） |
 
-2.1.12 起（D-6.7）镜像**不再预置**任何 provider 行——以上为「添加 provider」的模板清单（Codesome 置顶默认）。所有模板的 Codex 上游走 S9a 形态（本地路由把 Responses 翻译为 Anthropic Messages，直连模板声明的 Anthropic 端点）；Codesome 两模板的 Claude 侧不含模型键（官方要求，模型由 Key 的服务端分组路由），并预填官方推荐的自动压缩水位（claude 150k / codex 900k）。
+模板模式下模型映射/模型目录随首次保存生效；手动填写的端点不会被模板清单静默改写。模板的 Codex 上游走 S9a 形态（本地路由把 Responses 翻译为 Anthropic Messages，直连模板声明的 Anthropic 端点）；Codesome 两模板的 Claude 侧不含模型键（官方要求，模型由 Key 的服务端分组路由），并预填官方推荐的自动压缩水位（claude 150k / codex 900k）。也支持自定义 Provider（OpenAI 兼容格式，端点/模型/上下文窗口全手填）。
+
+## 远程机器
+
+Workbench 可以像操作本机一样驱动远程机器上的工作站：在远程机器上安装 aisc CLI 并保持 SSH 可达，Workbench 通过 `ssh <机器> aisc serve` 通道执行构建、运行、Provider 等操作，构建产物与容器都在远程机器上。
+
+**远程机器侧准备**（一次性）：
+
+1. 安装 Docker 与 aisc CLI：`pipx install aisc-cli`（或见[CLI 独立安装](#独立安装)）；
+2. 配置 SSH 密钥认证——Workbench **仅支持密钥登录，不支持密码**：
+   - 本机 `ssh-keygen -t ed25519` 生成密钥（口令可留空）；
+   - 把公钥 `~/.ssh/id_ed25519.pub` 追加到远程机器的 `~/.ssh/authorized_keys`；
+   - 首次连接先在终端手动 `ssh` 一次，确认主机指纹。
+
+**Workbench 侧**：设置页「远程机器」填名称 / 主机 / 用户 / 端口 / 私钥路径；之后在**选择工作区页顶部切换目标机器**即可。设置页还提供远程 CLI 版本检测：与本机 CLI 比对并显示「需更新 / 版本一致 / 远程较新」软提示（不阻断使用），需要更新时会给出可复制的升级命令（如 `pip install -U aisc-cli`）。远程 CLI 版本过旧导致协议不匹配时，连接会明确报协议版本不符。
 
 ## CLI 使用指南
 
@@ -102,6 +122,21 @@ CLI 适合脚本化、远程环境或不使用 GUI 的场景。Workbench 安装
 
 ### 独立安装
 
+**pip / pipx（0.1.0 起，最常用）**：
+
+```bash
+pipx install aisc-cli        # 首选：自动隔离 + 独立 bin 目录（Windows 同样适用）
+# 或 uv tool install aisc-cli / 裸 pip（请在 venv 内）
+```
+
+三点须知：① 分发名是 `aisc-cli`，但命令仍是 `aisc`；② **需要自备 Docker**，装完先跑 `aisc doctor`；③ pip 安装**不含构建资源**——`aisc build` / `maintenance docker-rebuild` 前需先 `aisc bundle fetch`（从 GitHub Releases 拉同版本 bundle 到数据根）；此时 `aisc version` 的 `bundle_version=null` 与 `doctor` 的 aisc-bundle WARN 属预期。
+
+安装陷阱 FAQ：
+
+- **`EXTERNALLY-MANAGED`（PEP 668）**：系统 Python 拒绝裸装 → 改用 `pipx install aisc-cli`。
+- **Windows 裸 pip `--user`**：Scripts 目录（`%APPDATA%\Python\Scripts`）默认不在 PATH → 把它加入 PATH 或改用 pipx。
+- **`python -m aisc`**：永远可用，是 shim 失效时的诊断后门。
+
 **Linux x86_64**（便携）：
 
 ```bash
@@ -124,28 +159,13 @@ bash packaging/install.sh /path/to/AISC-<ver>-linux-x86_64.tar.gz
 **从源码**：
 
 ```bash
-git clone https://github.com/wangyuncepu/AISC.git
+git clone https://github.com/Wifabric/AISC.git
 cd AISC
 uv tool install --editable .
 ```
 
 editable 安装记录仓库绝对路径，移动仓库前先 `uv tool uninstall aisc`。
 
-**pip / pipx（0.1.0 起）**：
-
-```bash
-pipx install aisc-cli        # 首选：自动隔离 + 独立 bin 目录（Windows 同样适用）
-# 或 uv tool install aisc-cli / 裸 pip（请在 venv 内）
-```
-
-三点须知：① 分发名是 `aisc-cli`，但命令仍是 `aisc`；② **需要自备 Docker**，装完先跑 `aisc doctor`；③ pip 安装**不含构建资源**——`aisc build` / `maintenance docker-rebuild` 前需先 `aisc bundle fetch`（从 GitHub Releases 拉同版本 bundle 到数据根）；此时 `aisc version` 的 `bundle_version=null` 与 `doctor` 的 aisc-bundle WARN 属预期。
-
-安装陷阱 FAQ：
-
-- **`EXTERNALLY-MANAGED`（PEP 668）**：系统 Python 拒绝裸装 → 改用 `pipx install aisc-cli`。
-- **Windows 裸 pip `--user`**：Scripts 目录（`%APPDATA%\Python\Scripts`）默认不在 PATH → 把它加入 PATH 或改用 pipx。
-- **`python -m aisc`**：永远可用，是 shim 失效时的诊断后门。
-
 ### 快速开始
 
 ```bash
@@ -170,7 +190,7 @@ aisc run --workspace /path/to/project
 - 镜像为 `super-claude:latest`，工作区为当前目录并挂载到 `/root/app`。
 - 网络为 `direct`。
 - 前台交互终端 `-it`，容器退出后由 `--rm` 自动删除。
-- 自动生成 `<name>-<8位十六进制>` 容器名，并登记到 registry。
+- 自动生成 `<name>-<8位十六进制>` 容器名，并登记到 registry；已有同工作区容器在运行时拒绝重复进入（防重入守卫）。
 
 容器初始化时先选择作用域：
 
@@ -214,30 +234,37 @@ aisc run --non-interactive   # 脚本/CI：无 TTY，项目作用域
 | --- | --- | --- |
 | `aisc version` | 全局选项 | 显示 CLI、Python、bundle 和声明依赖版本信息 |
 | `aisc doctor` | 全局选项 | 只读检查 Docker、权限、buildx、TUN、Git、资源根和目录可写性 |
-| `aisc build` | `--tag/-t`, `--no-cache`, `--pull`, `--dry-run`, `--require-pin` | 构建镜像；默认 tag 为 `super-claude:latest` |
-| `aisc run` | `--image/-i`, `--workspace`, `--name`, `--label`, `--network`, `--keep-alive`, `--non-interactive`, `--dry-run` | 启动并登记容器 |
+| `aisc build` | `--tag/-t`, `--no-cache`, `--pull`, `--dry-run`, `--require-pin` | 构建镜像；默认 tag 为 `super-claude:latest`；网络受限时预置/镜像源保底 |
+| `aisc run` | `--image/-i`, `--workspace`, `--name`, `--label`, `--network`, `--keep-alive`, `--non-interactive`, `--dry-run` | 启动并登记容器（防重入） |
 | `aisc ps` | 全局选项 | 列出 registry 中容器的 label、实时状态、镜像和工作区 |
 | `aisc status` | `--name`, `--label` | 查看目标容器状态 |
-| `aisc stop` | `--name`, `--label` | 停止目标容器；已停止时幂等成功 |
-| `aisc restart` | `--name`, `--label` | 重启目标容器 |
+| `aisc stop` / `aisc restart` | `--name`, `--label` | 停止（幂等）/ 重启目标容器 |
 | `aisc shell` | `--name`, `--label` | 执行 `docker exec -it <name> bash` |
 | `aisc session open` | — | 打开托管会话终端（Workbench 内部使用同一通道） |
+| `aisc serve` | — | 长驻远程通道（stdin/stdout JSON 帧协议；Workbench 经 SSH 调用，一般无需手动运行） |
 | `aisc switch` | `--name`, `--label`, `--quick PROVIDER` | 打开 cc-switch TUI，或快速切换 Claude Provider |
 | `aisc provider set-key` | `PROVIDER_ID`, `--name`, `--label`, `--agent` | 打开 cc-switch provider 安全交互编辑器；凭据不进命令行参数 |
+| `aisc conversation read` | 会话定位参数 | 聊天式只读对话查看器（历史会话阅读） |
+| `aisc work-record list/reconcile` | `--workspace` | 列出或重新对账 Work Record / Collection 与未归档会话 |
+| `aisc work-record create/rename/activate/deactivate/archive/restore` | `--workspace`, `--title`, `--collection-id` 等 | 管理 Work Record 元数据与生命周期 |
+| `aisc work-record add/remove/delete` | `--workspace`, `--collection-id`, `--agent`, `--conversation-id` 等 | 手动整理成员或级联删除 Collection（CLI 只删除 transcript；live PTY 由 Workbench 预先编排关闭） |
+| `aisc worklog list/rename/archive` | `--id` 等 | 工作区 PTY 会话账本（开关钩子自动记账，fail-open） |
 | `aisc config validate/effective` | `--config`, `--workspace` | 校验/展示合并配置与来源 |
 | `aisc profile list/show` | 全局选项 | 只读列出/显示 Profile |
 | `aisc logs show/path` | `--source app\|cli\|ui\|all` | 查看统一 JSONL 日志时间线 |
 | `aisc usage overview` | 全局选项 | 跨工作区聚合用量 |
 | `aisc network subscription …` | `import/import-file/refresh/show/clear` | 代理订阅数据面（URL 与内容走 stdin） |
-| `aisc maintenance docker-scan/cleanup/rebuild` | `--context`, `--root`, `--tag` | Docker 资源归属扫描/清理/重建（卸载与升级同一服务） |
+| `aisc maintenance docker-scan/cleanup/rebuild` | `--context`, `--root`, `--tag` | Docker 资源归属扫描/清理/重建（owned-only，卸载与升级同一服务） |
+| `aisc maintenance container-action/image-rm/image-tag` | `--id` 等 | AISC 自有容器的启动/停止/删除、镜像删除与重命名（仅 owned 资源，执行前锁内重扫判权） |
 | `aisc bundle fetch/list/remove/path` | `--version`, `--from-file`, `--sha256`, `--allow-mismatch` | pip 安装的构建资源管理：从 GitHub Releases 拉取同版本 bundle 到数据根（API digest 校验、fail-closed、离线 --from-file） |
-| `aisc update` | `--check`, `--version`, `--from-file`, `--sha256`, `--rebuild` | CLI 自更新（冻结形态：rename dance 原子换 exe+相邻 bundle，旧件保留可回退；pip 形态给 pipx 指引；Workbench 池 mtime 驱逐免重启生效；`--pin-tool KEY=VALUE` 钉工具版本于数据根用户层、更新不丢；`--check` 附三工具版本对照） |
+| `aisc update` | `--check`, `--version`, `--from-file`, `--sha256`, `--rebuild` | CLI 自更新：`--check` 查看计划。**不再从网络下载 CLI 归档**——pip/pipx 形态走各自渠道（`pipx upgrade aisc-cli` 或 venv 内 `pip install -U aisc-cli`）；便携/冻结形态可用 `--from-file <archive> --sha256 <hex>` 本地换装；Workbench 内置 CLI 随安装器自更新 |
 
 多容器寻址顺序：显式 `--name` -> 唯一匹配的 `--label` -> registry 默认目标 -> 唯一登记容器；无法消歧时列出候选并要求指定。
 
 构建相关补充：
 
-- 网络受限时，cc-switch 版本解析按「在线 → 缓存 → 本地回执 → 无钉版国内镜像源构建」递进；`--require-pin`（或 `AISC_REQUIRE_PIN=1`）恢复严格失败。
+- 网络受限时按「在线 → 缓存 → 本地回执 → 国内镜像源」递进；npm 主包与 yazi 已预置，GitHub 全阻亦可完成构建；`--require-pin`（或 `AISC_REQUIRE_PIN=1`）恢复严格失败。
+- 构建失败时会给出网络归因诊断与三条出路（本地预置 / 显式代理 `GH_PROXY` / 容器 TUN）。
 - `aisc build --events` 输出 JSONL 进度事件（`build.progress` 等），供前端/脚本消费。
 
 ### 容器内使用
@@ -292,12 +319,12 @@ Workbench 与 CLI 共享统一数据根：
 
 ## 升级
 
-- **Windows Workbench**：运行新版安装器覆盖安装。安装器会先停止并删除 AISC 管理的容器，替换文件后对默认镜像执行**无缓存重建**（可能需要几分钟），成功后清理旧镜像；Docker 不可用时文件照常更新，镜像重建转为待办并给出手动命令。
+- **Windows Workbench**：推荐应用内「设置 -> 检查更新」直接升级——下载（带进度条）→ 确认 → 静默安装 → 自动重建镜像 → **自动重启新版**。也可手动运行新版安装器覆盖安装（效果相同）。升级会先停止并删除 AISC 管理的容器，替换文件后对默认镜像执行**无缓存重建**（可能需要几分钟到 30 分钟）；Docker 不可用时文件照常更新，镜像重建转为待办并给出手动命令。用户配置、工作区状态与持久工具链全部保留。
 - **macOS PKG / 便携脚本**：覆盖安装或重新执行 `packaging/install.sh <new-archive>`。
 - **uv tool**：`git pull` 后 `uv tool upgrade aisc` 或重装；镜像内容变化时需重新 `aisc build`。
-- **pipx/pip**：`pipx upgrade aisc-cli`（或 venv 内 `pip install -U aisc-cli`）；新版 bundle 用 `aisc bundle fetch` 更新（更新镜像再 `aisc maintenance docker-rebuild`）。CLI 自身更新也可用 `aisc update`（冻结形态适用）。
+- **pipx/pip**：`pipx upgrade aisc-cli`（或 venv 内 `pip install -U aisc-cli`）；新版 bundle 用 `aisc bundle fetch` 更新（更新镜像再 `aisc maintenance docker-rebuild`）。
 
-用户配置、工作区状态与持久工具链在升级中全部保留。
+注：Workbench 内置的 CLI 随安装器一同更新（无独立升级通道）；远程机器上的 CLI 用 `pipx upgrade aisc-cli` / `pip install -U aisc-cli` 独立升级。
 
 ## 卸载
 
@@ -341,18 +368,25 @@ Workbench 内：打开诊断对话框查看环境检查与最近日志，可导
 | --- | --- |
 | 找不到 `aisc` | 重开终端；Linux/macOS 确认 `~/.local/bin` 在 `PATH`；便携包保持 `aisc` 与 `aisc-bundle/` 相邻 |
 | Docker 未运行 | 启动 Docker Desktop / Engine；Workbench 摘要页有「启动 Docker」唤起与自动重试 |
-| Docker 未安装 | 自行安装（见[安装前提](#安装前提)）；Workbench 会给出指引并自动识别 |
+| Docker 未安装 | 自行安装（见[安装前提](#安装前提)）；Windows 安装器可一键引导安装 |
 | `Image not found` | 先构建镜像（Workbench 构建页或 `aisc build`） |
-| 构建卡在下载/网络受限 | v2.1.7 起自动回退国内镜像源；仍失败时查看构建日志的真实错误原因 |
+| 构建失败（网络受限） | v2.1.14 起 npm 主包/yazi 已预置，GitHub 全阻也能离线构建，其余下载自动回退国内镜像源；仍失败时看构建日志末尾的网络归因提示（本地预置 / 显式代理 `GH_PROXY` / 容器 TUN 三出路） |
 | 首次启动很久 | 首启需初始化容器环境（最长约 3 分钟）；二次启动恢复正常速度 |
 | Windows 报「无可用网关端口」(47000-47999) | WSL2 系统级端口保留所致：管理员执行 `wsl --shutdown`，再 `netsh int ipv4 add excludedportrange protocol=tcp startport=47000 numberofports=1000`，然后重启 Docker Desktop |
 | cc-switch daemon/路由异常 | 容器内 `cc-switch daemon status` / `proxy show`；daemon 日志在 `/tmp/cc-switch-daemon.log` |
+| 远程机器连不上 | 确认 SSH 密钥认证已配置（不支持密码登录）；远程 `aisc` 在 PATH 上；协议版本不符时按设置页提示升级远程 CLI |
+| `aisc update` 报「不再下载 CLI 归档」 | 属预期：pip/pipx 渠道用 `pipx upgrade aisc-cli` / `pip install -U aisc-cli`；Workbench 内置 CLI 随安装器更新 |
+
+提交问题时附上操作系统、CPU 架构、Docker 版本、`aisc version`、复现命令和已脱敏日志。不要上传 API Key、Cookie、登录令牌、Provider 数据库或完整配置目录。
+
+## 反馈渠道
 
-提交 [GitHub Issues](https://github.com/wangyuncepu/AISC/issues) 时附上操作系统、CPU 架构、Docker 版本、`aisc version`、复现命令和已脱敏日志。不要上传 API Key、Cookie、登录令牌、Provider 数据库或完整配置目录。
+- **GitHub Issues**：[github.com/Wifabric/AISC/issues](https://github.com/Wifabric/AISC/issues)——适合功能讨论与明确 bug。
+- **反馈站**：[feedback.alanevergarden.xyz](https://feedback.alanevergarden.xyz)——网页表单提交（可带截图与日志附件），处理进度公开可见；提交后在反馈站查看开发者回复与版本修复情况。
 
 ## 许可
 
-MIT License，详见 [LICENSE](https://github.com/wangyuncepu/AISC/blob/main/LICENSE)。镜像还包含第三方组件，其来源、校验和与许可证记录在 `vendor/` 中。
+MIT License，详见 [LICENSE](https://github.com/Wifabric/AISC/blob/main/LICENSE)。镜像还包含第三方组件，其来源、校验和与许可证记录在 `vendor/` 中。
 
 ## 推荐服务
 
@@ -362,7 +396,7 @@ MIT License，详见 [LICENSE](https://github.com/wangyuncepu/AISC/blob/main/LIC
 
 Codesome 提供 API 调用形式的接入服务，有两条产品线：**V3**（Claude/GPT 月卡 + 按量，`sk-...` Key，在后台建 Key 并选分组）与**二合一/V5**（月卡，订单里的 `cr-...` 卡密直接就是 Key，Claude/GPT 双端通用，无分组）。这是 API 服务，不是 Claude 或 Codex 成品账号。
 
-**2.1.12 起内置两个 Codesome 模板**（`codesome-v3` / `codesome-2in1`）——Workbench Providers 页「添加 provider」默认选中 Codesome，选对产品线、填入 Key 即可（表单下方「获取服务」直达注册/购买页）。两条线的地址不可混用，V3 的 `sk-` Key 不能配二合一，反之亦然。
+**AISC 内置两个 Codesome 模板**（`codesome-v3` / `codesome-2in1`）——Workbench Providers 页「添加 provider」默认选中 Codesome，选对产品线、填入 Key 即可（表单下方「获取服务」直达注册/购买页）。两条线的地址不可混用，V3 的 `sk-` Key 不能配二合一，反之亦然。
 
 手动配置时的端点（两线各自两端通用，URL 不同不可混用）：
 

aisc_cli-0.1.9/src/aisc/VERSION

@@ -0,0 +1 @@
+0.1.9

{aisc_cli-0.1.3 → aisc_cli-0.1.9}/src/aisc/adapters/docker_gateway.py

@@ -286,7 +286,15 @@ class InteractiveStreamHandle:
     def _pump_loop(self) -> None:
         try:
             while not self._stopped.is_set():
-                chunk = _sock_recv(self._sock, 65536)
+                try:
+                    chunk = _sock_recv(self._sock, 65536)
+                except (socket.timeout, TimeoutError, InterruptedError):
+                    # An upgraded exec socket may inherit a read timeout.
+                    # A timed-out idle read is not EOF; EINTR is also merely
+                    # "retry this read". Only a zero-byte read below is EOF.
+                    if self._stopped.is_set():
+                        break
+                    continue
                 if not chunk:
                     break
                 self._on_output(chunk)