SkillDock

本 skill 随独立的 skilldock 插件分发，可在 Codex 或 Claude 中使用，仅打开本地技能管理应用。两边打开的是同一个本地实例和同一份数据。在支持原生入口的 Codex 版本中，可从 More / Explore 的 SkillDock 打开完整主页面并固定到侧栏；在 Claude 中把本地技能管理器打开在内置浏览器面板里。GUI 按钮直接调用本地服务，打开即加载本机技能库。用户只要求打开界面时，不替其安装、禁用或移除实际技能。

Codex 原生入口

仅 Codex 有此入口（Claude 不加载它）。插件随包提供本地 MCP 服务及完整 UI。新会话/重载后，在 More / Explore 选择 SkillDock；可用 Pin to sidebar 固定。第一次打开会自动准备后台，后续复用已核实的实例。全局页面沿用已保存的项目，首次无选择时用用户主目录，用户可从项目选择器切换。后台中断时界面会重连，不自动重放写操作。原型 SkillDock Preview 是不同测试插件，正式入口需单独固定；不自动卸载用户的 Preview。

分发和生命周期说明见 原生应用接入。

启动与打开

从本次实际加载的 SKILL.md 所在目录定位 scripts/launch.sh，不要假定仓库 checkout 或插件缓存路径。启动器按固定顺序查找本机 Node.js 22.12+（Codex 工作区、已下载的专用版本、Homebrew、nvm/fnm/Volta/asdf/mise/nodenv、PATH），保存所选路径供两侧入口与后台任务复用，失效时重新查找；找不到时弹出安装引导（打开下载页或安装后“重新检测”），不再自动下载。

/bin/sh "/实际安装位置/skill-manager/scripts/launch.sh" start --project "/用户项目的绝对路径"

启动前确定用户项目目录，并用 --project 显式传入；不要先切换到下载目录或安装目录再把它作为用户项目。未指定时依次使用 SKILLDOCK_PROJECT_DIR、界面保存的项目、调用工作目录。界面“切换项目”可保存新的扫描选择。可用 SKILLDOCK_STATE_DIR 指定独立应用数据目录、PORT 指定端口；默认数据位于 ~/.local/share/skilldock，默认端口 4771。启动器把源文件复制到应用数据目录，按 lockfile 安装依赖并构建（输出写入数据目录的 build.log），不向安装的插件缓存写入运行数据。首次启动需要 npm registry 可达，后续复用相同构建。

Codex CLI 逐个验证 PATH、桌面应用内置 CLI 与 Codex 管理的副本；损坏的旧 wrapper 会被跳过。Claude 命令行依次取显式指定、用户手动指定的保存值、从 Claude 打开时会话提供的路径、Claude 桌面应用自带的最高版本、此前自动选中的保存值、PATH 与用户目录下的安装，选中后保存并在使用前核验版本，因此会跟上 Claude 的升级。指定 SKILLDOCK_CODEX_BIN 或 SKILLDOCK_CLAUDE_BIN 时必须是有效的绝对路径。SkillDock 的服务与它调用的命令行只继承白名单内的环境变量，不带入宿主会话变量。CLI 诊断也包含在 doctor 中，实际来源说明见 应用安装说明。

运行环境发现失败时先执行 launch.sh doctor（只读，不写任何文件）。宿主若提供 load_workspace_dependencies，可读取其返回的真实 Node 路径，以 SKILLDOCK_NODE_BIN 指定；自定义 Codex 应用位置使用 SKILLDOCK_CODEX_APP_DIR。无人值守或没有图形界面的环境可设 SKILLDOCK_NO_DIALOG=1 关闭安装引导对话框。不要修改 Codex 的签名或用户 shell 配置来绕过加载限制。诊断及兼容边界见 运行环境接入。

核对启动前后打印的请求目录和最终扫描目录、目录来源、Codex CLI 绝对路径，以及本机有 Claude 时所选的 Claude 命令行。真实路径与请求路径不同会有符号链接说明；若最终目录不符合用户意图，修正 --project 后重新打开，不把 HTTP 200 当作扫描目录正确的证据。

读取启动器返回的实际 URL，按当前宿主打开：

• Codex：宿主提供 open_in_codex 时，以 browser target、placement: right 打开 URL；否则使用已提供的浏览器工具，或给出可点击链接。原生全局入口已在 26.924.22138 验证；宿主未显示该入口时使用此浏览器路径。
• Claude：用宿主提供的浏览器工具在内置浏览器面板中打开 URL（例如桌面应用的浏览器面板）；没有此类工具时给出可点击链接。

工具不存在时不伪造面板已打开。不要自行改写宿主固定记录。

默认读取本机已知技能根和可用 CLI 证据，不声称扫描整台磁盘。界面显示每个对象的可用操作和原因。已运行的 Codex 或 Claude 会话不保证即时重新加载配置；按应用反馈提示重启、新开会话或重载插件。

状态与停止

/bin/sh "/实际安装位置/skill-manager/scripts/launch.sh" status
/bin/sh "/实际安装位置/skill-manager/scripts/launch.sh" stop

退出码 3 表示数据已由更高版本的 SkillDock 管理、需要先更新本侧 SkillDock：把输出中的提示原样告诉用户，不要重试，也不要改用其他数据目录。

退出码 4 表示某个 Agent 中还装有低于 0.10.3 的 SkillDock，0.11 暂不接管数据（旧版本照常工作，没有改动任何数据）：把 stderr 中的说明与处理步骤告诉用户，并询问是否由 SkillDock 一键更新 stderr 中列出的那个 Agent（Codex 或 Claude）里的 SkillDock。用户同意后，在原启动命令前加上 SKILLDOCK_UPDATE_AGENT=codex 或 SKILLDOCK_UPDATE_AGENT=claude 重新运行一次（只针对列出的 Agent），启动器会经该 Agent 的命令行更新、读回并重新检查；用户不同意时什么都不改动，请用户在对应 Agent 中更新或卸载旧版 SkillDock 后重新打开。两侧都被拦下时每次只指名一侧，更新后若仍被另一侧拦下，再询问用户一次；一键更新失败时把 stderr 中的原因与手动步骤告诉用户，不要反复重试；不要跳过检查，也不要改用其他数据目录。非 0 退出时 stdout 没有内容。

启动是网页后台服务操作，中断调用不一定停止已创建的服务；先用 status 核实实际结果，需要停止网页服务时执行 stop。自 0.4.0 起，自动更新由独立的 macOS 用户后台任务负责；stop 不关闭自动更新。用户要求停止自动更新时，在更新页关闭计划并读回后台任务已移除。

启动器只停止它自己记录的服务：经健康检查确认匹配的，或（0.11.3 起）进程还在、端口已经没有程序监听、而命令行与启动器当初启动它时逐字相同的；不要自己按端口或进程名称杀掉其他程序。出现端口占用、不可核实 PID 或 CLI 不可用时，保留实际错误并按 应用说明 排查。更新 app 源码后的 start 会重建并重启已核实的此实例。

用户将所属插件加入自动更新计划后，独立任务在整批结束时准备新版，下次任务使用新版；没有打开面板时不启动网页服务。已运行的网页服务检测到新版后自动重启，浏览器自动重连；同一安装跨版本保留原数据目录。构建失败保留旧服务，启动失败尝试恢复旧运行目录。失败时检查日志与重启状态，不删除数据目录或手改所有权记录来绕过校验。实现及验证见 自身更新重启。

macOS 计划首次开启时注册当前用户 LaunchAgent，结束即退出；Codex 和网页面板均可关闭。重启并登录、睡眠恢复后补一次到期检查。后台状态异常时读取更新页的实际注册状态与执行记录，不把“计划已启用”当作任务已运行。旧版已启用的计划在第一次启动 0.4.0 时自动迁移，更新后的自动重启也算；仅更新了插件文件而尚未运行新版时，才需手动启动一次。用户或系统禁用后台运行时不擅自重启用。设计、数据位置与验证见 独立后台更新。

从旧版迁移

旧版 SkillDock 0.1.0 属于 testany-eng。独立插件首次接续旧数据时，在明确打开新插件的请求下，用本 skill 的真实路径执行 start --project "/用户项目" --migrate-from testany-eng；启动器只接续同一 marketplace 和 Codex 根的固定旧身份。保留旧计划与历史，不自动卸载整个 testany-eng。新旧同名 skill 共存时以独立 skilldock 的安装路径为准；更新旧工具集到 2.4.1 会移除旧应用入口。旧计划的 testany-eng 目标保留，新应用自更新须选择 skilldock 目标。

使用示例

• “打开技能管理面板” → 启动并打开 GUI，交由用户选择对象。
• “设置技能自动更新” → 打开更新页的计划设置；让用户选择对象、间隔与自动应用开关。仅打开界面不代表授权创建本机计划。
• “查看这个项目有哪些同名技能” → 将项目目录作为扫描根，打开技能库并筛选重名项。
• “SkillDock 无法启动” → 读取启动结果、服务日志及 应用说明，只处理该实例。

维护与完成标准

跨 Agent（0.11）的需求、设计、接口契约与实施进度见 PRD、HLD、接口契约 与 实施计划；改动跨版本识别、启动转交或数据格式前先读契约。本轮独立分发与项目选择整改见 种子反馈记录。维护源码时读取 工程设计 与 测试计划；需求或交互变更分别读取 PRD 与 界面设计。第一轮 UAT 的主题、三语言、来源及定时更新变更见 变更基线。最新产品边界与验证见 第三轮整改交付；Sandbox 已从产品移除，隔离夹具仅供开发测试使用。本软件许可为 AGPL-3.0-only，第三方材料保留自己的许可。

启动成功须有实际健康检查和可访问页面；操作成功须由后端读回证明。缓存目录存在不等于有效安装，市场刷新不等于技能/插件升级；保护系统和来源不明确的托管组件。失败、部分完成、恢复和用户 UAT 各自如实报告。