无本地文件读取权限 / 渠道不一致

你会遇到什么

Codex 桌面端装完读不到技能（无本地文件读取权限）；CodeBuddy 等产品装 OpenSpec/Superpowers 报渠道不一致错误。同一个包，换个产品就装不上。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

• 桌面端未授予本地文件读取权限时，技能目录读不到；
• 不同产品对「插件/技能」的格式与目录约定不同：Codex 桌面端、CodeBuddy、Claude Code 各一套，混用就报渠道不一致。

“插件/技能”在不同产品里不是同一个东西：每个产品自己定义“技能长什么样、放在哪个目录、怎么被扫描”。Codex 桌面端是纯文件 skills 目录（启动时扫描目录，每个含 SKILL.md 的子目录一个技能）；Claude Code 是插件市场或 skills 目录；CodeBuddy 有自己的渠道。

把 A 产品的目录搬到 B 产品，等于拿 B 的扫描器去读 A 的布局——读不到就报“缺文件/渠道不一致”。

桌面端还有一层系统权限：桌面应用读用户目录之外的位置需要用户显式授予权限，没授权时“目录存在但读不到”。所以接入任何产品都固定两步：先查该产品认什么形态（文档/官方说明），再按它的目录约定放置（并处理桌面端权限）。判断“为什么读不到”也分层：目录位置对不对（约定层）→ 权限给没给（系统层）→ 格式对不对（内容层）。

一步步来

1. 在对应产品的设置里授予本地文件读取权限 — 必做

Codex 桌面端：设置里开本地文件读取权限（CSDN 2026-06 案例）。

2. 按产品形态安装 — 必做

cp -r skills ~/.codex/skills/superpowers

Codex 用 skills 目录；Claude Code 用插件市场或 skills 目录；CodeBuddy 用其自身渠道。

3. 渠道不一致报错时以产品自带渠道为准 — 必做

不要混用安装路径；以产品自带插件安装渠道为准。

怎么确认修好了

Codex 形态安装与卸载闭环（本市场实测输出）：

[install] superpowers installed: OK（cp -r skills ~/.codex/skills/superpowers）
[uninstall] superpowers removed: OK（rm -rf，零残留）

新会话技能可见；CodeBuddy/Claude Code 各按自身渠道验证。

其它环境的表现

症状

Codex 桌面端装完读不到技能（无本地文件读取权限）；CodeBuddy 等产品装 OpenSpec/Superpowers 渠道不一致报错。

原因

桌面端未授予本地文件读取权限；不同产品对「插件/技能」的格式与目录约定不同（Codex 桌面端、CodeBuddy、Claude Code 各一套）。

解法

1. 在对应产品的设置里授予本地文件读取权限。
2. 按产品形态安装：Codex 用 skills 目录；Claude Code 用插件市场或 skills 目录；CodeBuddy 用其自身渠道（先查该产品支持 Superpowers 的形态）。
3. 渠道不一致报错时，以产品自带插件安装渠道为准，不要混用。

本市场实测安装 / 卸载（2026-08-27/28）

安装（站内安装说明 superpowers，隔离 HOME 复现）：

[install][WARN] 注意：superpowers 与以下条目存在未验证组合（可能冲突）: ruflo
[probe][PASS] github：GitHub 源码下载 / GitHub 网页 / GitHub API 可用
[install] 执行: curl -sL -o /tmp/superpowers.tar.gz https://codeload.github.com/obra/superpowers/tar.gz/refs/tags/v6.3.0 && ... && cp -r .../skills ~/.codex/skills/superpowers
superpowers installed: OK
[install] 已记录本地安装回执（匿名；~/.trove/receipts/）
[install][PASS] superpowers 安装完成

卸载（站内卸载说明 superpowers，green 档一键执行）：

[uninstall] 执行: rm -rf ~/.codex/skills/superpowers
[uninstall] 验证: test ! -d ~/.codex/skills/superpowers
superpowers removed: OK
[uninstall][PASS] superpowers 卸载完成，零残留

完整日志：实测记录（本地留存）；连通性：实测记录（本地留存） + 站内文档。

冲突标注

• possible-compatible：oh-my-claudecode / agent-governance-toolkit / deepcode（无共享写面，共装判定见冲突矩阵）
• possible-conflict：ruflo（Claude 形态共享 ~/.claude/skills 写面，未实测）——同机装 ruflo 时建议用 Codex 形态
• 形态维度：Codex 形态只写 ~/.codex/skills/superpowers，与其他条目共享面最小；Claude 插件市场形态写面在 Claude 插件目录，按形态分别评估

名称混淆

无同名高危条目（检索时注意 superpower 单复数拼写差异）。

判据（验证状态）

• 症状清单：
• [x] /plugin install 报 fatal: Failed to connect to github.com port 443（CSDN，2026-05；解包核实 + 探针证据）
• [x] ZIP 下载超时 → git clone/换网络/离线解压（CSDN，2026-06）
• [x] Plugin not found → 市场源配置错误（CSDN，2026-01；掘金教程整合）
• [x] Plugin hook error → 更新版本或手动跑 session-start.sh（CSDN，2026-01；上游 Issue #420）
• [x] 装完看不到技能 → 完全退出重启 + 路径检查（CSDN，2026-06；掘金 FAQ；上游 Issue #818）
• [x] 无本地文件读取权限 / 渠道不一致（CSDN，2026-06/07）
• [x] 本地插件缺 dist 产物显示不可用（CSDN 2026-05 + aicoding 案例；tarball 解包核实无 dist/）
• 实测步骤：

本站实测记录

• [x] 卸载验证（green 档一键卸载 → verify 零残留）
• [x] 网络/镜像场景（network-probe full：codeload 1.91s / gh-proxy 7.8s / raw 超时）
• [x] 未能实测项：Claude Code 插件市场场景本机不可测（无登录态）——网页方案整合，如实标注

验收

• [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（7 症状）
• [x] 名称混淆已点名：无同名高危条目
• [x] check-words HARD 0
• [x] validate 通过
• [x] 未碰 GitHub / 未用任何账号