Usora Dock

Usora Dock 是一个独立的 VS Code 扩展，把本机可被发现的 Agent Skills 汇总到一个面板里，并可选接入 Usora Foundry 工作台。普通 Skills 浏览保持只读；Foundry 的业务写操作仍由真实 MCP 和 Foundry 权限负责。它不是 Skill marketplace，也不在 Dock 内复制 Hub 后端。

Global Skills · Workspace Skills · Usora Hub  ->  搜索 / 过滤 / 预览 SKILL.md
Foundry MCP -> 概览 / 实践记录 / 候选能力 / 技能草稿 / 已发布技能

它解决什么Copy Anchor Link

Usora 把能力沉淀成 Hub 里的 Skill，但 Skill 文件本身散落在各宿主约定目录中。Usora Dock 用一个视图回答“这台机器上有哪些 Skill、在哪、内容是什么”，不需要记住几十个目录路径。

面板按三类来源分组：

• Global Skills：~ 下各 Agent 的全局技能目录。
• Workspace Skills：当前 workspace 各文件夹内的项目级技能目录，多根 workspace 按文件夹分组。
• Usora Hub：本地 Hub 的知识目录 <knowledgeHome>/skills。

列表显示名称、描述、来源和路径；Hub 条目额外并排显示真实生命周期状态（DRAFT / EVALUATED / REJECTED / PUBLISHED）。空、缺失和损坏的来源会给出说明，而不是静默隐藏。

安装Copy Anchor Link

在 VS Code 的扩展视图（Ctrl+Shift+X）搜索 Usora Dock（扩展标识 veyra.usora-dock，发布者 Veyra），点击 Install，然后按提示重载窗口。要求 VS Code ^1.85.0。

安装成功的标志：活动栏出现 Usora Dock 图标，命令面板能搜到 Usora Dock: 开头的 6 条命令。

使用Copy Anchor Link

打开面板Copy Anchor Link

点击活动栏的 Usora Dock 图标，或 Ctrl+Shift+P → Usora Dock: Open Usora Dock Panel。面板是三栏布局：左侧导航栏（品牌区、Skills Explorer、各来源及数量），中间是搜索工具栏、agent 标签行和可折叠分组列表，右侧是详情面板。

找到 SkillCopy Anchor Link

1. 在左侧导航栏选来源：Global Skills、Workspace Skills、Usora Hub。括号里的数字是该来源发现的技能数。
2. 点 agent 标签行，或用工具栏的 来源 菜单，把列表收窄到单个 agent。
3. 按 Ctrl/Cmd+K 聚焦搜索框，关键词匹配名称、描述、标签、来源标签、路径和 Hub 状态。

方向键可以在列表中移动，所有控件都键盘可达。

如果已安装并启用 Usora Foundry MCP，左侧还会显示 Foundry 工作台。工作台的安装、连接、筛选、时间排序和生命周期操作见Usora Dock Foundry 工作台。

查看内容Copy Anchor Link

选中一行后，右侧详情面板显示标签、三列事实卡片和四个页签：

• 详情：摘要与元数据（名称、描述、来源、路径）。
• 文档：渲染后的 SKILL.md。
• 使用示例：技能给出的调用示例。
• 相关技能：同一来源里发现的兄弟技能。

底部操作按钮对应 Usora Dock: Open Skill File、Usora Dock: Preview Skill、Usora Dock: Copy Skill Path、Usora Dock: Open Source Folder。

保持最新Copy Anchor Link

新建或修改 Skill 后执行 Usora Dock: Refresh 重新扫描；扩展也监听 **/SKILL.md，文件变化 500 ms 后自动刷新。

普通 Skills 面板不能新增、编辑或删除 Skill——它是只读视图，Skill 的增删改仍然通过 Usora Hub 完成。Foundry 工作台是独立的可选业务区域，所有写操作都经过真实 MCP、权限门禁和确认。配色跟随 VS Code 主题变量，切换主题不需要重载。

命令Copy Anchor Link

所有命令都是只读的。

设置Copy Anchor Link

usoraSkillsExplorer.globalSkillDirectories 的默认值来自 npx skills（vercel-labs/skills）记录的 Agent 目录列表，加上各工具自己文档化的布局，例如 ~/.claude/skills、~/.codex/skills、~/.codebuddy/skills、~/.cursor/skills、~/.gemini/skills、~/.trae/skills。它们是尽力而为的约定，不代表某个工具版本一定读取该目录。

Skill 发现规则Copy Anchor Link

扫描是刻意浅层的：只读配置的根目录及其直接子目录，不会递归进入 home、node_modules、构建产物或 .git。只有存在 SKILL.md 的子目录才算 Skill，普通文件夹会被忽略而不是变成坏行。

• Global：~ 展开为 os.homedir()；缺失目录静默跳过，从不创建。
• Workspace：与全局使用同一份注册表，按 workspace 文件夹解析。通用名字（skills、data/skills、agent/skills）被刻意排除在默认值之外，避免在无关仓库里误匹配。
• Usora Hub：knowledgeHome 取 USORA_HOME，否则 ~/.usora，技能位于 <knowledgeHome>/skills。config.hub_path 移动的是 host 数据（activities、sessions、runtime）而不会移动 skills，因此扩展不读取 config.json。
• Codex system Skills：<全局 Codex 根目录>/.system/<skill>/SKILL.md，仅当 .system/.codex-system-skills.marker 存在时识别。

Hub 条目由 skill.json（name、description、state、revision、updated_at）构建，并用 SKILL.md 补充内容。state 原样展示，不会被翻译成“已启用”或“已安装”；缺失 SKILL.md 只报告警告，不会自动生成。

只读边界Copy Anchor Link

扩展刻意不做以下事情：

• 不执行任何 SKILL.md、脚本或命令。
• 不写入、删除、移动或重命名技能。
• 不安装、卸载、启用或禁用任何东西。
• 没有 marketplace、账号、同步、数据库、MCP 或 HTTP server。
• 不创建目录；缺失的根目录会被跳过并报告。

发现一个文件不等于任何 Agent 已启用该技能。

常见问题Copy Anchor Link

• USORA_HOME 读取自 Extension Host 进程环境，只在另一个 shell 中导出的变量不可见；这种情况请改用 usoraSkillsExplorer.usoraHome。
• 没有找到 Hub 时，分组会说明原因并提示设置路径，不会自动初始化。
• Windows 上 profile 被重定向时 ~ 可能不指向预期位置，请写显式路径。
• 默认不跟随符号链接；开启后同一物理技能可能出现多个路径。
• 超过 maxMetadataFileSizeKb 的 SKILL.md 仍会列出，但不会解析描述。
• 文件监听基于全局 **/SKILL.md 并在 500 ms 去抖后刷新。