Repository navigation
docs: align installed skill with desktop runtime selection - #6748
Conversation
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent — gpt-6-astra — OpenAI — runtime_reported — reasoning_effort=xhigh
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
Exact reviewed head: d92b0264f23aa60354dae1a58993922a97c98a0c. 这是我对自己修正的独立逐句自审记录;未发现阻塞性问题。
动机
通过已安装的 loopx-project skill 升级桌面 App 的 Agent 会读取这一段指导。旧文字说当前 App 会要求版本配对,并建议让 CLI 对齐内置 bundle;当 CLI 较新时,这可能引出多余确认或降级。新版按现有原生选择逻辑保留合格且已证明较新的运行时。已验证真实 workflow-skills 安装后的文件包含修正内容,并与当前源码完全一致;原生运行时选择代码保持不变。此次不安装或升级用户的 App/CLI,不改运行时选择、授权、调度或持久化协议。
该问题在原 PR #6725 的合并后独立审查中被发现:它搬迁了旧指导,但旧指导已落后于同一源码树内的 Desktop contract。本修正完成这个具体缺口,不把文案修改当作一次运行时升级。
改动思路
复用现有 scenario reference,直接修正过时段落;不为文档再建选择器或版本字段。当前 Rust owner 仍决定合格性、版本顺序、同一安装的 fallback 和开发者显式 pin。新指导让 Agent 先读安装版本及服务身份,再沿已有升级路线处理;未知 ancestry 不能被写成已证明较新。用户授权、私有数据边界与真实 readback 要求均保留,正常启动不增加版本选择确认。
具体改动
关键内容讲解
仅 skills/loopx-project/references/installation-and-diagnosis.md:13-21 改动,9 行新增、3 行删除。它说明当前 App 自动选择能够建立顺序的最新合格 runtime,保留已证明较新的版本;需要 bundle 时使用 App-owned snapshot,不覆盖用户通过 uv/pip/pipx 管理的 CLI。旧 App 仍须按实际版本诊断,建议升级 App,而不是把较新的 CLI 降到旧 bundle。显式开发者 pin 和相关诊断保留。
规范:apps/desktop/loopx-control-plane/README.md,不可变基线 1ac26edb6ada2c72a3fa5ee07608049cd77deaf9,验收项 Updates And Recovery。我同时阅读该基线的 runtime_selection.rs 与 maintenance.rs,核对 package version、source ancestry、ownership fallback 与 environment override 的分支。这里映射已有行为,未用新文案反过来定义运行时语义。
真实安装路径为分发资源 → workflow-skills --install --skills-dir <isolated directory> → 安装后文件与 manifest/readback。旧安装文件仍包含配对指示;新安装文件与修正源码逐字节一致,包含自动选择、不降级、未知 ancestry、App-owned fallback 与 pin 五类边界。
对主干的风险
最值得防范的是把“自动选最新”说成无条件升级,掩盖资格、未知关系或 pin。逐句对照现有 owner 后,新文字明确限定为能够建立的合格顺序,并保留未知关系和显式 pin,不赋予安装权限。失败路径仍是读实际版本/服务身份和原有诊断;没有通过删掉 gate 或增加新命令让问题表面消失。
我运行了安装、打包元数据和仓库指令的 58 个相关测试,全部通过;真实 CLI 安装与独立文件读回通过。提交后的双语 RFC 检查、diff whitespace 与公开边界检查通过。没有新增 RFC、可执行程序、UI 或 runtime 改动,因此这组风险覆盖足够;未重新打包或运行原生 App,也没有读取远端 CI。泛用 shell 安装路径是既有公开示例,不是本机路径。
语义与 CI 对齐
这是现有已安装指令的明确修正,没有 default-off 能力、激活开关或新状态词汇。重复安装、修改/缺失文件的检测仍由原安装器和现有测试保护。指导描述当前 machine owner 的行为,不声称 prose 自身强制执行;也不把安装可用视为执行授权。遵循当前 wait_for_ci=false,远端 CI 不作为本审查证据。
我的整体评价
修正实现了所选文案缺口。长程执行方面保留原生状态机与恢复路径;用户体验方面减少错误配对/降级建议,不增加确认轮次。有界重构检查结论是无需新增结构:现有 runtime owner 与安装参考已足够,保留原文档入口和分发合同最容易验证及回滚。新文件的宿主加载和模型实际遵从尚未观察,不能从安装成功推导现有会话已采纳。当前 exact head 的自审、相关验证与实际安装读回齐备,合并仍需原生 merge-readiness 返回 ready。
English verdict: APPROVE — d92b026; narrow correction of stale installed Desktop instructions. 58 focused tests, actual isolated skill installation/readback, bilingual and diff checks passed. Native runtime behavior is unchanged; live App upgrade and model adoption were not performed.
The installed project skill still described a version-pairing confirmation and suggested aligning the CLI with the App's bundle. That guidance predates the current native runtime selector and could lead an upgrade agent to add an unnecessary confirmation or downgrade a newer CLI.
Align the moved installation reference from #6725 with the existing Desktop contract: automatic qualified-runtime selection, preservation of a provably newer runtime, explicit treatment of unknown ancestry, App-owned fallback without replacing a separately managed CLI, and preservation of developer pins. Older App behavior still requires inspecting the actual installed version and readback.
This is the bounded refinement found during an independent post-merge audit of #6725. Only the installed skill's prose changes; the existing Rust selector and installation authority remain the owners. No new capability, runtime policy, UI, command or storage contract is introduced.
Validation at the proposed commit:
uv run --extra test python -m pytest -q --no-cov tests/test_workflow_skill_install.py tests/test_packaged_skill_metadata.py tests/test_repository_instruction_delivery.py.apps/desktop/loopx-control-plane/README.md,runtime_selection.rsandmaintenance.rsat base1ac26edb6ada2c72a3fa5ee07608049cd77deaf9.Future-facing pass: reuse the existing native selection owner and scenario reference; no second runtime policy helper or additional test-only framework is needed.