@michengai/dsh-skills-manager 0.1.32 → 0.1.34

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The five most recent published versions are listed below.
 
 ## Unreleased
 
+## 0.1.34 — 2026-09-02
+
+- Made direct Skill entries the canonical owner when the same real bundle is also exposed through Agent distribution links. The canonical provider candidate inherits the strongest distribution rank, so disabling CC Switch cannot fall back to a linked public-Agent copy.
+- Required discovered real bundle and document paths for both user and project Provider candidates, revalidated both paths at load time, and aligned policy toggles with real-document reads.
+- Scanned user roots concurrently and reused one resolved set of trusted read-only roots per scan without caching external filesystem state across requests.
+- Preserved a per-Skill disable while its current distribution entry changes ownership to a canonical source. A canonical source's explicit policy still takes precedence over inherited distribution-link policies.
+- Made detail visibility reproduce the same user-root deduplication as state snapshots from the requested entry's physical owner, avoiding unrelated Skill document reads; entry resolution, detail reads, and Provider reads fail closed when files disappear during a filesystem race.
+
+Published package: [`@michengai/dsh-skills-manager@0.1.34`](https://www.npmjs.com/package/@michengai/dsh-skills-manager/v/0.1.34).
+
+## 0.1.33 — 2026-09-02
+
+- Added an enabled-by-default, read-only `CC Switch` source at `~\.cc-switch\skills` with source-wide and per-Skill local policy toggles. Legacy state files gain the new source without failing closed.
+- Allowed top-level linked Skill bundles in user-level read-only sources only when they target a direct child of another known read-only Skills root. Provider loading revalidates the real target and deduplicates CC Switch deployments by real path.
+- Kept writable DSH roots, project sources, linked roots, hidden or invalid targets, arbitrary external targets, and import symlinks rejected.
+
+Published package: [`@michengai/dsh-skills-manager@0.1.33`](https://www.npmjs.com/package/@michengai/dsh-skills-manager/v/0.1.33).
+
 ## 0.1.32 — 2026-08-31
 
 - Unified every per-Skill enable/disable action—user DSH, shared Agents, Codex, Claude, Gemini, OpenCode, project DSH, and project Agents—under manager-local tri-state policy; toggles never rewrite a source Skill file.

package/CHANGELOG.zh-CN.md

@@ -6,6 +6,24 @@
 
 ## 未发布
 
+## 0.1.34 — 2026-09-02
+
+- 同一真实 Skill 同时存在直接条目和 Agent 分发链接时，改为由直接条目归属；规范候选继承所有分发入口中的最强 rank，停用 CC Switch 后不会回流到公共 Agent 链接副本。
+- 用户级与项目级 Provider 候选必须携带扫描时发现的真实 bundle 和文档路径，加载时同时复验；启停读取也统一使用真实文档路径。
+- 用户根改为并发扫描，并在单次扫描内复用已解析的受信只读根；不跨请求缓存外部文件系统状态。
+- 当前分发条目归属迁移到规范来源时，保留原来源的逐 Skill 停用；规范来源自身的显式策略优先于继承的分发链接策略。
+- 详情接口按被请求条目的物理所有者复现状态快照的用户根去重结果，避免读取无关 Skill 文档；文件在扫描后消失时，条目解析、详情读取和 Provider 读取均失败关闭。
+
+发布包：[`@michengai/dsh-skills-manager@0.1.34`](https://www.npmjs.com/package/@michengai/dsh-skills-manager/v/0.1.34)。
+
+## 0.1.33 — 2026-09-02
+
+- 新增默认开启的只读 `CC Switch` 来源，固定读取 `~\.cc-switch\skills`，支持来源级与逐 Skill 本地启停；旧状态文件自动补齐新来源，不会因缺少新键失败关闭。
+- 用户级只读来源支持指向已知只读 Skills 根直接子目录的顶层技能链接；Provider 在加载时复验真实目标，并按真实路径去重 CC Switch 分发到 Codex、Claude 等目录的副本。
+- 可写 DSH、项目来源、技能根链接、隐藏或非法目标以及任意根外目标继续拒绝，导入符号链接边界不变。
+
+发布包：[`@michengai/dsh-skills-manager@0.1.33`](https://www.npmjs.com/package/@michengai/dsh-skills-manager/v/0.1.33)。
+
 ## 0.1.32 — 2026-08-31
 
 - 将用户 DSH、公共 Agent、Codex、Claude、Gemini、OpenCode、项目 DSH 与项目 Agent 的逐 Skill 启停全部统一为 manager 本地三态策略；启停不再改写任何来源 Skill 文件。

package/README.md

@@ -22,7 +22,7 @@
 
 ## Features
 
-- Discover and load user-level skills from `.agents`, Codex, Claude, Gemini, and OpenCode into DSH.
+- Discover and load user-level skills from `.agents`, CC Switch, Codex, Claude, Gemini, and OpenCode into DSH.
 - Discover project-level `.dsh/skills` and `.agents/skills` from active Session workspaces, grouped by project; every valid Skill can be enabled or disabled through non-mutating local policy.
 - Persist every per-Skill toggle under `$DSH_HOME/skills-manager/state.json` without rewriting any source Skill file.
 - Inspect Markdown bodies, frontmatter, invocation state, duplicate shadowing, and format diagnostics in a source-first UI.
@@ -152,6 +152,7 @@ Escape closes only the frontmost upload or confirmation dialog and leaves Settin
 | --- | --- | --- | --- | --- |
 | `$DSH_HOME\skills` | Yes | Manager state only | Yes | Moves to Trash |
 | `$DSH_AGENTS_HOME\skills` | Yes | Manager state only | No | No |
+| `~\.cc-switch\skills` | Yes, enabled by default | Manager state only | No | No |
 | `~/.codex/skills`, `~/.claude/skills`, `~/.gemini/skills`, `~/.config/opencode/skills` | Yes | Manager state only | No | No |
 | `<project>/.dsh/skills` | Yes, for active Session workspaces | Manager state only | Create in Settings | Moves to Trash and restores to the original project |
 | `<project>/.agents/skills` | Yes, for active Session workspaces | Manager state only | No | No |
@@ -162,6 +163,7 @@ Escape closes only the frontmost upload or confirmation dialog and leaves Settin
 - Trash falls back to copy-then-hide when a project and `$DSH_HOME` are on different volumes; restore uses the same guarded cross-volume path in reverse.
 - Project Trash entries retain their original opaque source identity. Restore is allowed only while that original project is still represented by an active Session workspace; the client cannot nominate a replacement path.
 - Project writes reject linked `.dsh` or `.dsh/skills` directories so a repository cannot redirect creation, deletion, or restore outside its own project root.
+- User-level read-only sources accept top-level linked Skill bundles only when the real target is an ordinary direct child of another known read-only Skills root. The same real Skill is displayed and loaded once according to source rank; writable DSH roots, project roots, linked roots, and arbitrary external targets remain rejected.
 - Rows and summaries say **Enabled/Disabled**, not **Loaded**: these labels describe invocation policy, while full Skill bodies are loaded on demand by DSH. Use Refresh after IDE, Git, or shell changes; the official provider remains responsible for project catalog watching and invalidation.
 - Empty project roots stay out of the main source list to reduce noise, but remain selectable in Create Skill so the first project Skill can still be created. Project DSH supports per-Skill toggles only, not a source-wide switch.
 - Replacements copy to a temporary sibling path first and keep the original until that succeeds.

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 
 ## 功能概览
 
-- 自动发现并把 `.agents`、Codex、Claude、Gemini 和 OpenCode 的用户级技能真正加载进 DSH。
+- 自动发现并把 `.agents`、CC Switch、Codex、Claude、Gemini 和 OpenCode 的用户级技能真正加载进 DSH。
 - 从活动 Session 工作区发现项目级 `.dsh/skills` 与 `.agents/skills` 并按项目分组；所有有效 Skill 都可通过不改源文件的本地策略启停。
 - 所有逐 Skill 启停都只写入 `$DSH_HOME\skills-manager\state.json`，绝不改写任何来源 Skill 文件。
 - 按来源折叠、搜索和筛选，并查看技能正文、frontmatter、调用状态、重名遮蔽与格式诊断。
@@ -152,6 +152,7 @@ dsh --profile web --dump-config
 | --- | --- | --- | --- | --- |
 | `$DSH_HOME\skills` | 支持 | 仅写 manager 状态 | 支持 | 进入回收站 |
 | `$DSH_AGENTS_HOME\skills` | 支持 | 仅写 manager 状态 | 不支持 | 不支持 |
+| `~\.cc-switch\skills` | 支持，默认开启 | 仅写 manager 状态 | 不支持 | 不支持 |
 | `~/.codex/skills`、`~/.claude/skills`、`~/.gemini/skills`、`~/.config/opencode/skills` | 支持 | 仅写 manager 状态 | 不支持 | 不支持 |
 | `<project>/.dsh/skills` | 支持活动 Session 工作区 | 仅写 manager 状态 | 设置页支持创建 | 进入回收站并恢复到原项目 |
 | `<project>/.agents/skills` | 支持活动 Session 工作区 | 仅写 manager 状态 | 不支持 | 不支持 |
@@ -162,6 +163,7 @@ dsh --profile web --dump-config
 - 当项目与 `$DSH_HOME` 位于不同磁盘时，回收站会降级为“复制后在源盘原子隐藏”；恢复使用反向的同一安全流程。
 - 项目回收站条目保存原始不透明来源身份。仅当原项目仍由活动 Session 工作区提供时才允许恢复；客户端不能指定替代路径。
 - 项目写入会拒绝链接形式的 `.dsh` 或 `.dsh/skills` 目录，避免仓库把创建、删除或恢复重定向到项目根之外。
+- 用户级只读来源允许顶层技能目录链接，但真实目标必须是另一个已知只读 Skills 根的普通直接子目录；同一真实技能按来源优先级只展示和加载一次。可写 DSH、项目来源、技能根链接和任意外部目标仍被拒绝。
 - 列表和摘要统一使用“已启用/已停用”，不再使用“已加载”：这里描述的是调用策略，完整 Skill 正文仍由 DSH 按需加载。IDE、Git 或 shell 改动后可点击“刷新”；项目 catalog 的 watcher 与 invalidation 仍由官方 provider 负责。
 - 没有 Skill 的项目根不会出现在主来源列表中，但仍保留在“创建技能”的目标选择中，确保可以创建第一个项目 Skill。项目 DSH 只提供逐 Skill 启停，不提供整个项目来源总开关。
 - 覆盖前先复制到同目录临时路径；复制成功前不会改动现有技能。

package/lib/client.js

@@ -35,7 +35,7 @@ window.__ModuleLoader__.load({
         "error.proto.forbidden": "禁止的修改请求（缺少客户端标记）", "error.proto.forbiddenHost": "禁止的请求来源（非法 Host）", "error.proto.contentType": "请求体必须是 application/json", "error.proto.method": "不支持的请求方法", "error.proto.unknownAction": "未知操作", "error.proto.bodyTooLarge": "请求体过大", "error.proto.invalidJson": "请求体不是合法 JSON", "error.proto.nonJson": "服务端返回非 JSON 响应（HTTP {status}）",
         "diagnostic.frontmatter.missing": "缺少完整 YAML frontmatter", "diagnostic.name.missing": "frontmatter 缺少 name", "diagnostic.name.invalid": "技能名称不是合法 kebab-case：{name}", "diagnostic.description.missing": "frontmatter 缺少 description", "diagnostic.invocation.invalid": "调用策略字段值无效", "diagnostic.shadowed": "被更高优先级来源 {root} 覆盖",
         "action.enable": "启用", "action.disable": "停用", "action.create": "创建", "action.delete": "删除", "action.restore": "恢复", "action.toggle": "启用或停用",
-        "root.dsh": "DSH 技能", "root.agents": "公共 Agent", "root.projectDsh": "项目 DSH", "root.projectAgents": "项目 Agent", "root.codex": "Codex", "root.claude": "Claude", "root.gemini": "Gemini", "root.opencode": "OpenCode"
+        "root.dsh": "DSH 技能", "root.agents": "公共 Agent", "root.ccswitch": "CC Switch", "root.projectDsh": "项目 DSH", "root.projectAgents": "项目 Agent", "root.codex": "Codex", "root.claude": "Claude", "root.gemini": "Gemini", "root.opencode": "OpenCode"
       },
       en: {
         "title": "Skills", "desc": "Load and manage Agent Skills on this computer in one place.",
@@ -62,7 +62,7 @@ window.__ModuleLoader__.load({
         "error.proto.forbidden": "Forbidden mutation request (missing client marker)", "error.proto.forbiddenHost": "Forbidden request origin (invalid host)", "error.proto.contentType": "Content type must be application/json", "error.proto.method": "Method not allowed", "error.proto.unknownAction": "Unknown action", "error.proto.bodyTooLarge": "Request body too large", "error.proto.invalidJson": "Invalid JSON request body", "error.proto.nonJson": "Server returned a non-JSON response (HTTP {status})",
         "diagnostic.frontmatter.missing": "Missing complete YAML frontmatter", "diagnostic.name.missing": "Frontmatter is missing name", "diagnostic.name.invalid": "Skill name is not valid kebab-case: {name}", "diagnostic.description.missing": "Frontmatter is missing description", "diagnostic.invocation.invalid": "Invocation policy value is invalid", "diagnostic.shadowed": "Shadowed by higher-priority source {root}",
         "action.enable": "enable", "action.disable": "disable", "action.create": "create", "action.delete": "delete", "action.restore": "restore", "action.toggle": "enabling or disabling",
-        "root.dsh": "DSH skills", "root.agents": "Shared Agent", "root.projectDsh": "Project DSH", "root.projectAgents": "Project Agent", "root.codex": "Codex", "root.claude": "Claude", "root.gemini": "Gemini", "root.opencode": "OpenCode"
+        "root.dsh": "DSH skills", "root.agents": "Shared Agent", "root.ccswitch": "CC Switch", "root.projectDsh": "Project DSH", "root.projectAgents": "Project Agent", "root.codex": "Codex", "root.claude": "Claude", "root.gemini": "Gemini", "root.opencode": "OpenCode"
       }
     };
 

package/lib/core.js

@@ -68,6 +68,7 @@ export function userRoots() {
   return [
     { key: "dsh", path: join(resolveDshHome(), "skills"), label: "DSH 技能", mutable: true, toggleable: true, native: true, rank: 400 },
     { key: "agents", path: join(resolveAgentsHome(), "skills"), label: "公共 Agent", mutable: false, toggleable: true, native: true, rank: 450 },
+    { key: "ccswitch", path: join(homedir(), ".cc-switch", "skills"), label: "CC Switch", mutable: false, toggleable: true, native: false, rank: 510 },
     { key: "codex", path: join(process.env.DSH_CODEX_HOME || join(homedir(), ".codex"), "skills"), label: "Codex", mutable: false, toggleable: true, native: false, rank: 520 },
     { key: "claude", path: join(process.env.DSH_CLAUDE_HOME || join(homedir(), ".claude"), "skills"), label: "Claude", mutable: false, toggleable: true, native: false, rank: 530 },
     { key: "gemini", path: join(process.env.DSH_GEMINI_HOME || join(homedir(), ".gemini"), "skills"), label: "Gemini", mutable: false, toggleable: true, native: false, rank: 540 },
@@ -76,7 +77,7 @@ export function userRoots() {
 }
 
 function projectIdentity(path) {
-  const canonical = process.platform === "win32" ? resolve(path).toLowerCase() : resolve(path);
+  const canonical = pathIdentity(path);
   return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
 
@@ -126,7 +127,7 @@ export async function projectRoots(projectCwds = [], diagnostics) {
       }
       continue;
     }
-    const identity = process.platform === "win32" ? found.root.toLowerCase() : found.root;
+    const identity = pathIdentity(found.root);
     const existing = projects.get(identity) || { root: found.root, cwds: new Set() };
     existing.cwds.add(found.cwd);
     projects.set(identity, existing);
@@ -336,6 +337,11 @@ async function isInsideResolvedRoot(rootReal, path) {
   return isSameOrDescendant(rootReal, await resolvedPath(path));
 }
 
+function pathIdentity(path) {
+  const canonical = resolve(path);
+  return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+
 async function lstatOrNull(path) {
   try {
     return await fs.lstat(path);
@@ -344,6 +350,58 @@ async function lstatOrNull(path) {
   }
 }
 
+/** 预解析可作为用户级链接目标的只读根，供一次扫描中的所有链接复用。 */
+async function resolvedReadonlyUserRoots() {
+  const roots = userRoots().filter((root) => !root.mutable && root.scope !== "project");
+  const resolvedRoots = await Promise.all(roots.map(async (root) => {
+    const stat = await lstatOrNull(root.path);
+    if (!stat || !stat.isDirectory() || stat.isSymbolicLink()) return null;
+    try {
+      return { root, realPath: await fs.realpath(root.path) };
+    } catch {
+      return null;
+    }
+  }));
+  return resolvedRoots.filter(Boolean);
+}
+
+/**
+ * 只接受用户级只读来源中的顶层目录链接，且目标必须是另一个已知只读 Skills 根的直接子目录。
+ * 这样可以兼容 CC Switch 的分发链接，同时不把任意文件系统路径扩展成技能来源。
+ */
+async function resolveTrustedLinkedBundle(root, bundlePath, trustedReadonlyRoots = resolvedReadonlyUserRoots()) {
+  const sourceRoot = rootDefinition(root);
+  if (!sourceRoot || sourceRoot.mutable || sourceRoot.scope === "project") return null;
+
+  let realEntryPath;
+  try {
+    realEntryPath = await fs.realpath(bundlePath);
+  } catch {
+    return null;
+  }
+  const realEntryStat = await lstatOrNull(realEntryPath);
+  if (!realEntryStat || !realEntryStat.isDirectory() || realEntryStat.isSymbolicLink()) return null;
+
+  const resolvedRoots = await trustedReadonlyRoots;
+  const resolvedSourceRoot = resolvedRoots.find((candidate) => pathIdentity(candidate.root.path) === pathIdentity(sourceRoot.path));
+  if (!resolvedSourceRoot) return null;
+  let trusted = false;
+  for (const targetRoot of resolvedRoots) {
+    if (pathIdentity(targetRoot.realPath) === pathIdentity(resolvedSourceRoot.realPath)) continue;
+    const acceptedTarget = entryPath(targetRoot.realPath, basename(realEntryPath));
+    if (acceptedTarget && pathIdentity(acceptedTarget) === pathIdentity(realEntryPath)) {
+      trusted = true;
+      break;
+    }
+  }
+  if (!trusted) return null;
+
+  const realDocPath = join(realEntryPath, "SKILL.md");
+  const docStat = await lstatOrNull(realDocPath);
+  if (!docStat || !docStat.isFile() || docStat.isSymbolicLink()) return null;
+  return { realEntryPath, realDocPath };
+}
+
 /** 名称只允许一个普通路径段；不把既有技能名称限制为 kebab-case。 */
 export function entryPath(root, name) {
   if (typeof name !== "string" || name === "" || name === "." || name === ".." || name.startsWith(".") || name.length > MAX_ENTRY_NAME_LENGTH || /[\\/:*?"<>|\0]/.test(name) || /[. ]$/.test(name) || WINDOWS_DEVICE_NAME_RE.test(name) || basename(name) !== name) return null;
@@ -524,27 +582,37 @@ export function parseBoolValue(raw) {
 
 /** 按名称解析条目（bundle 优先，其次 flat）。找不到返回 null。 */
 export async function resolveEntry(root, name) {
-  const bundlePath = entryPath(root, name);
-  if (bundlePath === null) return null;
-  const rootPath = resolve(root);
-  const rootStat = await lstatOrNull(rootPath);
-  if (!rootStat || !rootStat.isDirectory() || rootStat.isSymbolicLink()) return null;
-  const rootReal = await resolvedPath(rootPath);
-  const bundleStat = await lstatOrNull(bundlePath);
-  if (bundleStat && bundleStat.isDirectory() && !bundleStat.isSymbolicLink()) {
-    const bundleDoc = join(bundlePath, "SKILL.md");
-    const docStat = await lstatOrNull(bundleDoc);
-    if (docStat && docStat.isFile() && !docStat.isSymbolicLink() && await isInsideResolvedRoot(rootReal, bundleDoc)) {
-      return { kind: "bundle", docPath: bundleDoc, entryPath: bundlePath };
+  try {
+    const bundlePath = entryPath(root, name);
+    if (bundlePath === null) return null;
+    const rootPath = resolve(root);
+    const rootStat = await lstatOrNull(rootPath);
+    if (!rootStat || !rootStat.isDirectory() || rootStat.isSymbolicLink()) return null;
+    const rootReal = await resolvedPath(rootPath);
+    const bundleStat = await lstatOrNull(bundlePath);
+    if (bundleStat && bundleStat.isDirectory() && !bundleStat.isSymbolicLink()) {
+      const bundleDoc = join(bundlePath, "SKILL.md");
+      const docStat = await lstatOrNull(bundleDoc);
+      if (docStat && docStat.isFile() && !docStat.isSymbolicLink() && await isInsideResolvedRoot(rootReal, bundleDoc)) {
+        return { kind: "bundle", docPath: bundleDoc, entryPath: bundlePath, realDocPath: await fs.realpath(bundleDoc), realEntryPath: await fs.realpath(bundlePath), linked: false };
+      }
     }
+    if (bundleStat && bundleStat.isSymbolicLink()) {
+      const linked = await resolveTrustedLinkedBundle(rootPath, bundlePath);
+      if (linked) return { kind: "bundle", docPath: join(bundlePath, "SKILL.md"), entryPath: bundlePath, ...linked, linked: true };
+    }
+    const flatDoc = resolve(rootPath, `${name}.md`);
+    if (!isSameOrDescendant(rootPath, flatDoc) || rootPath === flatDoc) return null;
+    const flatStat = await lstatOrNull(flatDoc);
+    if (flatStat && flatStat.isFile() && !flatStat.isSymbolicLink() && await isInsideResolvedRoot(rootReal, flatDoc)) {
+      const realDocPath = await fs.realpath(flatDoc);
+      return { kind: "flat", docPath: flatDoc, entryPath: flatDoc, realDocPath, realEntryPath: realDocPath, linked: false };
+    }
+    return null;
+  } catch {
+    // lstat 与 realpath/readFile 之间允许来源变化，调用方统一按不存在处理。
+    return null;
   }
-  const flatDoc = resolve(rootPath, `${name}.md`);
-  if (!isSameOrDescendant(rootPath, flatDoc) || rootPath === flatDoc) return null;
-  const flatStat = await lstatOrNull(flatDoc);
-  if (flatStat && flatStat.isFile() && !flatStat.isSymbolicLink() && await isInsideResolvedRoot(rootReal, flatDoc)) {
-    return { kind: "flat", docPath: flatDoc, entryPath: flatDoc };
-  }
-  return null;
 }
 
 function entryOf(name, kind, docPath, doc) {
@@ -578,7 +646,7 @@ function entryOf(name, kind, docPath, doc) {
 }
 
 /** 扫描一个技能根（只扫一层）。返回 { exists, entries }。 */
-export async function scanEntries(root) {
+export async function scanEntries(root, options = {}) {
   const rootStat = await lstatOrNull(resolve(root));
   if (!rootStat || !rootStat.isDirectory() || rootStat.isSymbolicLink()) return { exists: false, entries: [] };
   let items;
@@ -589,22 +657,33 @@ export async function scanEntries(root) {
   }
   const byName = new Map();
   const rootReal = await resolvedPath(root);
+  let trustedReadonlyRoots = options.trustedReadonlyRoots;
   for (const it of items) {
     try {
-      if (it.isSymbolicLink()) continue;
+      if (it.isSymbolicLink()) {
+        const bundlePath = entryPath(root, it.name);
+        if (bundlePath === null) continue;
+        trustedReadonlyRoots ||= resolvedReadonlyUserRoots();
+        const linked = await resolveTrustedLinkedBundle(root, bundlePath, trustedReadonlyRoots);
+        if (!linked) continue;
+        const doc = parseSkillDoc(await fs.readFile(linked.realDocPath, "utf8"));
+        byName.set(it.name, { ...entryOf(it.name, "bundle", join(bundlePath, "SKILL.md"), doc), entryPath: bundlePath, ...linked, linked: true });
+        continue;
+      }
       if (it.isDirectory() && entryPath(root, it.name) !== null) {
         const docPath = join(root, it.name, "SKILL.md");
         const st = await lstatOrNull(docPath);
         if (!st || !st.isFile() || st.isSymbolicLink() || !(await isInsideResolvedRoot(rootReal, docPath))) continue;
         const doc = parseSkillDoc(await fs.readFile(docPath, "utf8"));
-        byName.set(it.name, entryOf(it.name, "bundle", docPath, doc));
+        byName.set(it.name, { ...entryOf(it.name, "bundle", docPath, doc), entryPath: join(root, it.name), realDocPath: await fs.realpath(docPath), realEntryPath: await fs.realpath(join(root, it.name)), linked: false });
       } else if (it.isFile() && it.name.toLowerCase().endsWith(".md") && it.name.toLowerCase() !== "skill.md" && entryPath(root, it.name.slice(0, -3)) !== null) {
         const skillName = it.name.slice(0, -3);
         if (byName.has(skillName)) continue;
         const docPath = join(root, it.name);
         if (!(await isInsideResolvedRoot(rootReal, docPath))) continue;
         const doc = parseSkillDoc(await fs.readFile(docPath, "utf8"));
-        byName.set(skillName, entryOf(skillName, "flat", docPath, doc));
+        const realDocPath = await fs.realpath(docPath);
+        byName.set(skillName, { ...entryOf(skillName, "flat", docPath, doc), entryPath: docPath, realDocPath, realEntryPath: realDocPath, linked: false });
       }
     } catch {
       /* 跳过不可读条目 */
@@ -614,6 +693,53 @@ export async function scanEntries(root) {
   return { exists: true, entries };
 }
 
+/** 同一真实技能优先归属直接 SSOT；同类条目再按来源 rank 决胜。 */
+async function scanDeduplicatedUserRoots(roots = userRoots()) {
+  const trustedReadonlyRoots = resolvedReadonlyUserRoots();
+  const results = await Promise.all(roots.map(async (root) => [root, await scanEntries(root.path, { trustedReadonlyRoots })]));
+  const scans = new Map();
+  const groups = new Map();
+  for (const [root, scan] of results) {
+    scans.set(root.key, scan);
+    for (const entry of scan.entries) {
+      const identity = pathIdentity(entry.realEntryPath || entry.entryPath || entry.docPath);
+      const group = groups.get(identity) || [];
+      group.push({ root, entry });
+      groups.set(identity, group);
+    }
+  }
+  const winners = new Set();
+  for (const group of groups.values()) {
+    group.sort((left, right) => Number(left.entry.linked) - Number(right.entry.linked) || left.root.rank - right.root.rank);
+    const winner = group[0];
+    winner.entry.providerRank = Math.min(...group.map((item) => item.root.rank));
+    winner.entry.policyRootKeys = group.map((item) => item.root.key);
+    winners.add(winner.entry);
+  }
+  for (const scan of scans.values()) {
+    scan.entries = scan.entries.filter((entry) => winners.has(entry));
+  }
+  return scans;
+}
+
+/**
+ * 详情只解析被请求的条目，再从物理路径确定其直接所有者。
+ * 受信链接只能指向已知只读根的顶层目录，故无需扫描并读取全部技能文档即可复现去重归属。
+ */
+async function visibleEntryForRoot(root, name) {
+  if (root.scope === "project") return resolveEntry(root.path, name);
+  const entry = await resolveEntry(root.path, name);
+  if (!entry) return null;
+  const identity = pathIdentity(entry.realEntryPath || entry.entryPath || entry.docPath);
+  const owners = (await resolvedReadonlyUserRoots())
+    .filter((candidate) => {
+      const expected = entryPath(candidate.realPath, basename(entry.realEntryPath || entry.entryPath || entry.docPath));
+      return expected !== null && pathIdentity(expected) === identity;
+    })
+    .sort((left, right) => left.root.rank - right.root.rank);
+  return owners.length === 0 || owners[0].root.key === root.key ? entry : null;
+}
+
 // ── Manager 本地策略（外部源只读，启停状态写入 DSH_HOME）────────────────────
 
 function defaultManagerState() {
@@ -667,6 +793,15 @@ function validManagerStateDocument(value) {
   return true;
 }
 
+/** 仅对可识别的 version 1 状态补齐 CC Switch 键，其余结构仍交由严格校验失败关闭。 */
+function migrateManagerStateDocument(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== 1) return value;
+  if (value.sources && typeof value.sources === "object" && !Array.isArray(value.sources) && value.sources.ccswitch === undefined) value.sources.ccswitch = true;
+  if (value.disabledSkills && typeof value.disabledSkills === "object" && !Array.isArray(value.disabledSkills) && value.disabledSkills.ccswitch === undefined) value.disabledSkills.ccswitch = [];
+  if (value.enabledSkills && typeof value.enabledSkills === "object" && !Array.isArray(value.enabledSkills) && value.enabledSkills.ccswitch === undefined) value.enabledSkills.ccswitch = [];
+  return value;
+}
+
 function normalizeManagerState(value) {
   const normalized = defaultManagerState();
   if (!value || typeof value !== "object" || Array.isArray(value)) return normalized;
@@ -692,7 +827,7 @@ function normalizeManagerState(value) {
 export async function readManagerState() {
   try {
     const raw = await fs.readFile(managerStatePath(), "utf8");
-    const parsed = JSON.parse(raw);
+    const parsed = migrateManagerStateDocument(JSON.parse(raw));
     if (!validManagerStateDocument(parsed)) throw codedError("invalid manager state schema", "error.state.invalid");
     return { state: normalizeManagerState(parsed), warning: null, writable: true };
   } catch (error) {
@@ -710,14 +845,21 @@ async function writeManagerState(value) {
   await writeFileAtomically(managerStatePath(), `${JSON.stringify(normalizeManagerState(value), null, 2)}\n`);
 }
 
-function managerSkillOverride(policy, rootKey, name) {
+function managerSkillOverride(policy, rootKey, name, policyRootKeys = []) {
   if ((policy.enabledSkills[rootKey] || []).includes(name)) return true;
   if ((policy.disabledSkills[rootKey] || []).includes(name)) return false;
+  let inheritedEnable = false;
+  for (const key of policyRootKeys) {
+    if (key === rootKey) continue;
+    if ((policy.disabledSkills[key] || []).includes(name)) return false;
+    if ((policy.enabledSkills[key] || []).includes(name)) inheritedEnable = true;
+  }
+  if (inheritedEnable) return true;
   return undefined;
 }
 
 function effectiveSkillPolicy(policyResult, root, entry) {
-  const override = managerSkillOverride(policyResult.state, root.key, entry.name);
+  const override = managerSkillOverride(policyResult.state, root.key, entry.name, entry.policyRootKeys);
   const sourceEnabled = root.key === "dsh" || root.scope === "project" || policyResult.state.sources[root.key] !== false;
   if (policyResult.writable === false || !sourceEnabled || override === false) {
     return { override, sourceEnabled, modelInvocable: false, userInvocable: false, enabled: false };
@@ -776,7 +918,12 @@ async function setPolicySkillEnabled(root, name, enabled, log) {
   if (!definition) return readonlyError("toggle");
   const resolved = await resolveEntry(definition.path, name);
   if (resolved === null) return { ok: false, error: `技能不存在: ${name}`, code: "error.skill.notFound", params: { name } };
-  const summary = entryOf(name, resolved.kind, resolved.docPath, parseSkillDoc(await fs.readFile(resolved.docPath, "utf8")));
+  let summary;
+  try {
+    summary = entryOf(name, resolved.kind, resolved.docPath, parseSkillDoc(await fs.readFile(resolved.realDocPath || resolved.docPath, "utf8")));
+  } catch {
+    return { ok: false, error: `技能不存在: ${name}`, code: "error.skill.notFound", params: { name } };
+  }
   if (!summary.hasFrontmatter) {
     return { ok: false, error: `技能缺少完整 frontmatter，无法${enabled ? "启用" : "停用"}: ${name}`, code: "error.skill.noFrontmatter", params: { name, action: enabled ? "enable" : "disable" } };
   }
@@ -893,8 +1040,8 @@ async function restoreRootDefinition(metadata, options = {}) {
     || !isAbsolute(metadata.root.projectRoot)
   ) return { ok: false, error: `回收站条目来源非法: ${metadata.id}`, code: "error.trash.invalid", params: { id: metadata.id } };
   const roots = await projectRoots(options.projectCwds);
-  const normalizedProjectRoot = process.platform === "win32" ? resolve(metadata.root.projectRoot).toLowerCase() : resolve(metadata.root.projectRoot);
-  const root = roots.find((item) => item.key === metadata.root.key && item.kind === "project-dsh" && (process.platform === "win32" ? resolve(item.projectRoot).toLowerCase() : resolve(item.projectRoot)) === normalizedProjectRoot);
+  const normalizedProjectRoot = pathIdentity(metadata.root.projectRoot);
+  const root = roots.find((item) => item.key === metadata.root.key && item.kind === "project-dsh" && pathIdentity(item.projectRoot) === normalizedProjectRoot);
   if (!root) {
     return {
       ok: false,
@@ -1447,9 +1594,14 @@ export async function skillDetail(key, name, options = {}) {
   const scopedRoots = await projectRoots(options.projectCwds);
   const root = rootByKey(key) || scopedRoots.find((item) => item.key === key);
   if (!root) return { ok: false, error: `未知技能来源: ${key}`, code: "error.root.unknown", params: { root: key } };
-  const entry = await resolveEntry(root.path, name);
+  const entry = await visibleEntryForRoot(root, name);
   if (!entry) return { ok: false, error: `技能不存在: ${name}`, code: "error.skill.notFound", params: { name } };
-  const raw = await fs.readFile(entry.docPath, "utf8");
+  let raw;
+  try {
+    raw = await fs.readFile(entry.realDocPath || entry.docPath, "utf8");
+  } catch {
+    return { ok: false, error: `技能不存在: ${name}`, code: "error.skill.notFound", params: { name } };
+  }
   const doc = parseSkillDoc(raw);
   const summary = entryOf(name, entry.kind, entry.docPath, doc);
   return {
@@ -1471,8 +1623,10 @@ export async function skillDetail(key, name, options = {}) {
 export async function listProviderCandidates(options = {}) {
   const policyResult = await readManagerState();
   const candidates = [];
-  for (const root of userRoots()) {
-    const scanned = await scanEntries(root.path);
+  const user = userRoots();
+  const userScans = await scanDeduplicatedUserRoots(user);
+  for (const root of user) {
+    const scanned = userScans.get(root.key);
     for (const entry of scanned.entries) {
       if (!entry.loadable) continue;
       const policy = effectiveSkillPolicy(policyResult, root, entry);
@@ -1484,9 +1638,9 @@ export async function listProviderCandidates(options = {}) {
         invocation: { modelInvocable: policy.modelInvocable, userInvocable: policy.userInvocable },
         provider: "dsh-skills-manager-external",
         source: root.key === "dsh" ? "user-dsh" : `agent-${root.key}`,
-        rank: root.key === "dsh" ? USER_DSH_POLICY_RANK : root.rank,
-        locator: { rootKey: root.key, entryName: entry.name, path: entry.docPath },
-        resourceBase: { kind: "directory", path: entry.kind === "bundle" ? dirname(entry.docPath) : root.path },
+        rank: root.key === "dsh" ? USER_DSH_POLICY_RANK : entry.providerRank ?? root.rank,
+        locator: { rootKey: root.key, entryName: entry.name, path: entry.docPath, realEntryPath: entry.realEntryPath, realDocPath: entry.realDocPath },
+        resourceBase: { kind: "directory", path: entry.kind === "bundle" ? entry.realEntryPath : root.path },
         path: entry.docPath,
         metadata: { dshSkillsManager: { root: root.key, readOnly: !root.mutable, sourceReadOnly: !root.mutable, policyOnly: root.key === "dsh" } },
       });
@@ -1510,8 +1664,8 @@ export async function listProviderCandidates(options = {}) {
           provider: "dsh-skills-manager-external",
           source: root.kind,
           rank: root.rank - 1,
-          locator: { rootKey: root.key, entryName: entry.name, path: entry.docPath },
-          resourceBase: { kind: "directory", path: entry.kind === "bundle" ? dirname(entry.docPath) : root.path },
+          locator: { rootKey: root.key, entryName: entry.name, path: entry.docPath, realEntryPath: entry.realEntryPath, realDocPath: entry.realDocPath },
+          resourceBase: { kind: "directory", path: entry.kind === "bundle" ? entry.realEntryPath : root.path },
           path: entry.docPath,
           metadata: { dshSkillsManager: { root: root.key, readOnly: !root.mutable, sourceReadOnly: !root.mutable, policyOnly: true } },
         });
@@ -1523,28 +1677,34 @@ export async function listProviderCandidates(options = {}) {
 
 export async function getProviderSkill(candidate, options = {}) {
   const locator = candidate && candidate.locator;
-  if (!locator || typeof locator.path !== "string" || typeof locator.rootKey !== "string") return undefined;
+  if (!locator || typeof locator.path !== "string" || typeof locator.rootKey !== "string" || typeof locator.realEntryPath !== "string" || typeof locator.realDocPath !== "string") return undefined;
   let root = rootByKey(locator.rootKey);
   if (!root && PROJECT_ROOT_KEY_RE.test(locator.rootKey) && typeof options.cwd === "string") {
     root = (await projectRoots([options.cwd])).find((item) => item.key === locator.rootKey);
   }
   if (!root) return undefined;
-  const entry = await resolveEntry(root.path, String(locator.entryName || ""));
-  if (!entry || resolve(entry.docPath) !== resolve(locator.path)) return undefined;
-  const doc = parseSkillDoc(await fs.readFile(entry.docPath, "utf8"));
-  const summary = entryOf(locator.entryName, entry.kind, entry.docPath, doc);
-  if (!summary.loadable || summary.declaredName !== candidate.name) return undefined;
-  return {
-    name: candidate.name,
-    description: candidate.description,
-    invocation: candidate.invocation,
-    provider: candidate.provider,
-    source: candidate.source,
-    resourceBase: candidate.resourceBase,
-    path: candidate.path,
-    metadata: candidate.metadata,
-    content: doc.body.trim(),
-  };
+  try {
+    const entry = await resolveEntry(root.path, String(locator.entryName || ""));
+    if (!entry || resolve(entry.docPath) !== resolve(locator.path)) return undefined;
+    if (pathIdentity(entry.realEntryPath) !== pathIdentity(locator.realEntryPath)) return undefined;
+    if (pathIdentity(entry.realDocPath) !== pathIdentity(locator.realDocPath)) return undefined;
+    const doc = parseSkillDoc(await fs.readFile(entry.realDocPath || entry.docPath, "utf8"));
+    const summary = entryOf(locator.entryName, entry.kind, entry.docPath, doc);
+    if (!summary.loadable || summary.declaredName !== candidate.name) return undefined;
+    return {
+      name: candidate.name,
+      description: candidate.description,
+      invocation: candidate.invocation,
+      provider: candidate.provider,
+      source: candidate.source,
+      resourceBase: candidate.resourceBase,
+      path: candidate.path,
+      metadata: candidate.metadata,
+      content: doc.body.trim(),
+    };
+  } catch {
+    return undefined;
+  }
 }
 
 // ── 状态快照 ────────────────────────────────────────────────────────────────
@@ -1575,6 +1735,7 @@ function markWinners(items, options = {}) {
 /** DSH、常见 Agent 与活动 Session 项目根的技能快照。 */
 export async function state(options = {}) {
   const user = userRoots();
+  const userScans = await scanDeduplicatedUserRoots(user);
   const projectWarnings = [];
   const scoped = await projectRoots(options.projectCwds, projectWarnings);
   const policyResult = await readManagerState();
@@ -1582,7 +1743,7 @@ export async function state(options = {}) {
   const result = { roots: [], projects: [], trash, warnings: [...(policyResult.warning ? [policyResult.warning] : []), ...projectWarnings] };
   const all = [];
   for (const root of [...scoped, ...user]) {
-    const { exists, entries } = await scanEntries(root.path);
+    const { exists, entries } = root.scope === "project" ? await scanEntries(root.path) : userScans.get(root.key);
     // 即使项目 .dsh/skills 尚不存在，也要把可写根返回给创建表单；只读项目根仍按实际存在性展示。
     if (root.scope === "project" && !exists && root.kind !== "project-dsh") continue;
     const skills = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michengai/dsh-skills-manager",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "NPM-installable DSH Web plugin for safely loading and managing skills across DSH and common local Agents.",
   "license": "Apache-2.0",
   "repository": {