visualize-cli-loading.md

Visualize 技能的 CLI 加载边界

行为

内置 visualize@zcode-plugins-official 提供对话内交互视图，普通终端没有对应宿主。 该插件保留内置，默认关闭。升级后首次读取旧配置时，将已保存的 visualize 启用值统一改为 false，并在同一配置文件写入 plugins.visualizeDefaultOffMigrated: true。旧值的来源不可区分， 因此此次迁移同时覆盖过去的默认开启和手动开启。迁移完成后，用户可以重新开启，后续启动保留新值。

读取用户 / 项目配置 → 尚未迁移且有旧开关 → 文件锁内重读 → 原子保存 false + 完成标记
                   → 写入 / 锁失败      → warn + 该层内存关闭 → 继续合并和启动
                   → 已迁移             → 沿用保存值
用户重新开启       → 同一文件锁          → 原子保存 true + 完成标记 → 后续启动保持开启

配置文件是开关及迁移标记的唯一数据源，不新增 UI 开关或独立状态库。迁移只处理本次加载的用户、 祖先项目和显式项目配置；未打开的项目在首次读取时迁移，不扫描磁盘。没有旧开关的配置不改写， 沿用默认关闭；开关写入入口同时写完成标记，避免新用户首次开启又被当成旧配置关闭。 不同配置层各自迁移，原有 workspace > user 优先级不变。并发迁移、重新开启及其他配置写入 共用文件锁，锁内重读，迁移标记和开关一起原子落盘；迁移写入或文件锁失败时不记录成功，只输出一条包含配置路径和错误码的 warn； 本次加载将失败配置层的 visualize 视为关闭，再参与原有优先级合并，不阻断 App 装配和插件、技能查询。 较高层已重新开启的配置和 CLI 覆盖仍然有效；磁盘恢复可写后，下次加载再次尝试迁移。 配置源只读取和发现一次；无待迁移项时直接合并，有待迁移项时只在文件锁内复核该文件， 使用锁内观察到的开关更新该层。配置诊断只在最终合并入口输出一次。 迁移在插件发现和新建 / 冷恢复会话装配前完成，桌面、手机及远端共用执行端的同一入口。 已运行会话仍按原有重载时机生效，不改写历史提示、渲染能力或控件状态。

非 --stdio 入口（TUI、-p / --prompt / --target、skills list/inspect）默认不注入 该插件的技能根，模型可用技能目录和 Skill 正文加载使用同一份发现结果。 即使 -p 使用 --surface desktop 模拟呈现面，也不自动启用该技能。

--stdio 协议入口在创建 App 和扫描草稿技能目录时显式传入 includeVisualize: true。 这是 bootstrap 内部装配选项，不是用户配置、环境变量或协议请求字段；缺省为关闭。 它与 Desktop context 的 presentation surface 灰度独立，只允许协议端加载已启用的插件，不自动开启插件。 用户禁用插件、禁用技能或卸载内置插件后仍然不可加载，不允许该选项覆盖用户配置。

单一发现链路

普通 CLI ── includeVisualize 缺省 ──┐
                                    ├─ 官方插件技能根过滤 → 技能发现 / Skill 加载
协议宿主 ─ includeVisualize=true ───┘                       ├─ 主会话目录
                                                           └─ workflow child 继承
协议草稿目录 ─ includeVisualize=true → 同一过滤规则 → 引用目录

只按官方插件 identity 过滤，保留其他插件和用户/项目自定义的同名技能。 插件市场目录、缓存 seed、安装记录不变；plugins list 仍可管理该插件。 过滤在 App 启动解析插件技能根时完成，主会话与 workflow child 使用同一份结果； 普通 subagent 继续继承父会话技能端口。恢复会话同样按当前启动入口重新装配。

Desktop 本地和附着的 SSH/WSL/Docker workspace 继续走 stdio 协议；手机 /remote 复用同一个 shared host。此变更不改 workspace identity、owner/lease、队列、事件流、 snapshot 或恢复逻辑；桌面 continuous 与手机 replayable 边界保持不变。

验证

• 默认/显式关闭时，正式技能目录没有内置 visualize，按名称和限定名加载均报不存在。

• 插件默认关闭时，协议入口也不发现技能、不注入 Gen UI 上下文；显式启用时可发现并读取完整技能。

• 主会话启动和 workflow child 共享过滤后的根，其他内置技能保持可用。

• 插件启用时协议 App 装配与草稿目录都保留 visualize；普通项目同名技能不受影响。

• 构建实际 CLI，验证非 stdio 的 list/inspect 和 stdio 的技能目录请求。

• 没有修改 Renderer 交互和协议 schema；用 CLI/协议集成验证加载边界，无新增 UI E2E。

• 升级前的用户级、项目级 true 均关闭一次；重新开启后重复加载及并发启动不会再次关闭。

• 缺失配置不创建文件，迁移保留其他插件及未知字段；写入失败不产生完成标记。

• 只读项目目录下技能发现成功，visualize 关闭且原文件不变；锁超时和原子写入失败同样降级。

• 降级只影响失败的配置层；高优先级已迁移配置和 CLI 覆盖保持有效。

• 无迁移时每个配置文件只加载一次，配置诊断每次调用只记录一次。