[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F24Y832GFZPH5SCRV86XDM":3,"skill-same:01M7F24Y832GFZPH5SCRV86XDM":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":13,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7F24Y832GFZPH5SCRV86XDM","agentdock-user-guide",null,"当用户询问 AgentDock 是什么、如何使用、配置在哪里、不同平台或安装方式怎样修改配置并生效、如何重启或验证配置、如何发现并配置 Codex\u002FClaude\u002FGrok 等 Coding Agent 的 ACP，以及常见运行问题时使用；覆盖 macOS Desktop、Windows Desktop、Linux 服务、Docker 和直接运行二进制，不用于源码开发与贡献流程。","kkda49\u002FAgentDock-Workbench","kkda49","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F87223383?v=4","01M7F24WDCX75FK5HAJB3ZY94B","01M7F24WE679RD64MTCSYTWFVY",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: agentdock-user-guide\ndescription: 当用户询问 AgentDock 是什么、如何使用、配置在哪里、不同平台或安装方式怎样修改配置并生效、如何重启或验证配置、如何发现并配置 Codex\u002FClaude\u002FGrok 等 Coding Agent 的 ACP，以及常见运行问题时使用；覆盖 macOS Desktop、Windows Desktop、Linux 服务、Docker 和直接运行二进制，不用于源码开发与贡献流程。\nversion: 1.6.0\n---\n\n# AgentDock User Guide\n\n这是随 AgentDock 发布的官方用户指南 Skill。目标是让模型基于用户当前真实安装方式，正确解释和操作 AgentDock，而不是依赖固定路径、旧版本经验或猜测。\n\n回答使用用户当前语言；命令、路径和配置键保持原样。\n\n## AgentDock 是什么\n\nAgentDock 是面向 AI Agent 的独立工具运行层。它把文件、命令、Git、Skill、动态 MCP、浏览器、任务等能力通过 MCP 提供给 ChatGPT、Claude、Codex 等客户端；它本身不是聊天界面，也不负责模型推理。\n\n一个 AgentDock 实例对应一个实际运行环境。客户端可以连接本机 AgentDock，也可以连接远程服务器、容器或其他设备上的 AgentDock。多设备场景下，先确认当前工具实际连到哪一个实例，再解释或修改该实例的配置。\n\n通常通过 AgentDock 暴露的 MCP 地址连接，默认 HTTP 端口是 8765，MCP 路径是 `\u002Fmcp`；实际地址、认证方式和端口始终以当前安装\u002F部署配置为准。公网访问必须保留认证并使用 HTTPS，不要把 Token、OAuth 密码或其他凭据发到公开聊天、截图或 Issue。\n\n如果当前 AgentDock 暴露 `agentdock_context`，把它作为识别版本、平台、运行目录、可用 Skill 与能力的首选入口；具体文件、进程、服务和容器状态仍应通过真实工具继续验证。\n\n## AgentDock 生态项目\n\n### Windows Tailscale Funnel\n\n包含原生 Tailscale 支持的 Windows 版本可在“公网访问”页选择 Tailscale Funnel。先检测已安装并登录的官方客户端，设备域名由 CLI 自动读取，不要求 Tunnel Token，也不保存 Auth Key。配置会转发完整 AgentDock Origin，验证 OAuth 与认证接口后才提交就绪状态。遇到其他根映射、私有 Serve 路径或已变化的所有权时保留原配置，不执行全局 reset、down 或 logout。使用前读取 [Tailscale 配置与恢复](references\u002Ftailscale.md)，并以当前 Core 的 `tunnel status --provider tailscale` 能力为准。\n\n### NexusDock\n\n[NexusDock](https:\u002F\u002Fgithub.com\u002Fuvwt\u002Fnexusdock) 是 AgentDock 的自托管中心服务。它把多台 AgentDock、长期记忆和 Workflow 集中到一个入口；单台 AgentDock 仍可独立使用，NexusDock 不是运行 AgentDock 的必需组件。\n\n以下场景尤其适合使用 NexusDock：\n\n- **ChatGPT 只接入一个 MCP**：把多台 AgentDock 与 NexusDock 配对后，ChatGPT 只需要配置 NexusDock 的统一 `\u002Fmcp` 地址。NexusDock 会向客户端提供统一工具入口；需要执行某台设备上的文件、命令、浏览器、Skill、动态 MCP 等能力时，先通过 `agentdock_context` 确认节点，再用对应 `node_id` 把工具调用路由到那台 AgentDock。这样不需要在 ChatGPT 中分别维护多台设备的 MCP 连接。\n- **需要长期记忆能力**：NexusDock 提供集中式 Recall 工作区和 `recall_*` 工具，用于搜索、读取、维护长期项目记忆、运行手册和经验记录。多台 AgentDock 可以使用同一份中心记忆，而不是各自在本机保存彼此不可见的长期上下文。\n- **需要 Workflow 能力**：NexusDock 集中保存和匹配可复用 Workflow 模板，并通过 `workflow_template_manage` 提供给模型；多步骤任务仍可结合 `task_manage` 持久化执行进度。基础 Workflow 不依赖 Embedding，配置向量服务后还可以使用语义匹配。\n- **需要多设备统一管理**：Web 控制台可以查看设备在线状态、版本和运行时能力，并集中查看 Recall、Workflow、任务、Skill 和动态 MCP 状态。\n\nNexusDock 不替代设备端 AgentDock：实际文件、命令、浏览器、Skill、动态 MCP 等设备能力仍由目标 AgentDock 节点执行；NexusDock 负责中心管理、共享 Recall\u002FWorkflow、统一 MCP 接入和跨设备路由。只有一台 AgentDock、也不需要中心记忆或 Workflow 时，可以直接连接 AgentDock，不必额外部署 NexusDock。\n\n统一 MCP 地址形式为：`https:\u002F\u002F\u003C你的 NexusDock 域名>\u002Fmcp`。支持 OAuth 的客户端可以直接授权；其他客户端也可以使用 NexusDock 的 MCP Access Token。具体认证方式以 NexusDock 当前部署为准。\n\n官方仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fuvwt\u002Fnexusdock>\n\n### AgentDock Documentation\n\nAgentDock 的用户文档独立维护在 [uvwt\u002Fagentdock-docs](https:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-docs)。安装、平台配置、部署、升级、工具和用户可见行为等说明应优先参考这里，而不是只依赖主仓库 README。\n\n在线文档：\u003Chttps:\u002F\u002Fuvwt.github.io\u002Fagentdock-docs\u002Fzh-CN\u002F>\n\n文档源码仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-docs>\n\n### AgentDock Skills\n\n[AgentDock Skills](https:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-skills) 是 AgentDock 官方与社区 Skill 的源码与测试仓库。普通业务集成、个人效率工具和社区 Skill 在这里独立维护，内容演进由 Git 历史追踪，避免与 AgentDock Core 版本强耦合。\n\nAgentDock 主仓库的 `core-skills\u002F` 只保留必须随 AgentDock 运行时一起安装和升级的内置核心 Skill；需要查找、阅读、贡献或发布其他 Skill 时，应优先查看 AgentDock Skills 仓库。安装第三方或社区 Skill 前仍应进行来源和安全审查。\n\n官方仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-skills>\n\n### Skill 与标准插件\n\n独立 Skill 使用 `~\u002F.agentdock\u002Fskills\u002F\u003Cname>\u002F`，内置 Skill 使用 `skills\u002F.system\u002F\u003Cname>\u002F`。多版本与回滚数据继续由 `skill_package` 管理。\n\n插件采用 Agent Plugins 1.0.0，自包含目录直接安装在 `~\u002F.agentdock\u002Fplugins\u002F\u003Cname>\u002F`。根目录 `plugin.json` 只保存标准元数据与命名空间扩展，`mcp.json` 保存标准 MCP 定义，Skill 位于 `skills\u002F\u003Cname>\u002FSKILL.md`。不创建第二层插件缓存，不把启停状态或凭据打进插件包。\n\n插件管理位于“功能与插件”页，每张卡片可展开或收起。普通插件的已启用 Skill\u002FMCP 直接进入顶层索引。只有 Heavy 插件先显示摘要，命中后调用 `plugin_load` 展开成员。Heavy 开关与成员开关保存在宿主状态中，切换不改写原插件包。普通工具检索会搜索普通插件，Heavy 插件使用 `plugin_load` 返回的服务器名或完整工具名继续调用。\n\n安装、更新、卸载使用 `plugin_manage`；插件内成员不能通过独立 Skill\u002FMCP 接口重复安装或删除。更新保留总开关、Heavy 覆盖值和仍存在的成员开关。外部数据、凭据保留，卸载插件不会自动删除它们。\n\n从 `.agentdock-plugin\u002Fplugin.json` 旧格式升级时，使用当前 Windows Setup。安装事务会停止旧实例、迁移清单及宿主状态、验证后启动新版，失败时按安装事务恢复。普通 Core 启动不进行隐式迁移。离线副本可以使用当前版本的 `agentdock plugin migrate --home \u003C绝对数据目录>`；先停止写入该目录的进程，不在运行中的真实目录手工转换。\n\n需要从旧 `skill-store` 和逻辑分组迁移整个目录时，使用源码内 `scripts\u002Fmigrate\u002Fmigrate-agentdock-home.ps1`，显式提供不同的源\u002F目标目录及当前 `-AgentDockBinary`，必要时提供仓库外的 `-PluginPlanPath`。源目录保持不变，结果报告保存在目标目录。\n\nWindows“运行配置”页可编辑默认全局工作区、AGENTS.md 自动加载、额外指令文件、浏览器程序、可信代理 CIDR、命令环境变量引用及 ACP 并发\u002F超时。额外指令文件通常留空；明确配置的文件仍须存在、非空且符合 UTF-8\u002F64 KiB 限制。保存会校验并重启，细节见 `references\u002Fwindows.md`。\n\n### ChatGPT 的工具 Schema 缓存\n\n使用 ChatGPT 平台连接 AgentDock 时，工具定义还存在一层平台侧缓存。AgentDock 已经完成工具变更，不代表当前 ChatGPT 会话会立即拿到新的 Schema。\n\n以下变化都应按“工具 Schema 已变更”处理：\n\n- 新增或删除工具；\n- 修改工具名称、描述、输入参数或输出 Schema；\n- AgentDock 升级后导致当前暴露的 MCP 工具集合发生变化。\n\n让变更在 ChatGPT 中生效时：\n\n1. 先确认 AgentDock Core 已经升级\u002F重启并暴露新的工具定义；\n2. 进入 GPT 的 AgentDock 插件页面，点击**刷新**按钮，让 ChatGPT 重新获取 AgentDock 的工具 Schema；\n3. **新开一个会话**再进行验证。旧会话可能继续使用创建会话时缓存的旧 Schema。\n\n因此，如果出现“AgentDock 代码和 Core 都已经更新，但 ChatGPT 仍看不到新工具\u002F新参数”的情况，不要继续反复重启 Core；先检查 ChatGPT 侧是否已经刷新插件并新建会话。这个缓存属于 ChatGPT 平台侧，不是 AgentDock 本地配置未生效。\n\n## 适用场景\n\n使用本 Skill 处理：\n\n- AgentDock 的定位、能力和基本使用方式；\n- “配置文件在哪里”“这个配置怎么改”“改完为什么没生效”；\n- macOS、Windows、Linux、Docker、直接运行二进制之间的配置差异；\n- Core 的启动、停止、重启、健康检查和配置生效验证；\n- 浏览器、MCP Apps UI、端口、日志、OAuth 等运行配置的入口；\n- 发现本机已有 Codex、Claude、Grok 等 Coding Agent，补齐缺失 ACP Adapter，并把 ACP 正确接入 AgentDock；\n- 多台 AgentDock 设备中，确认应该修改哪一台设备的运行配置。\n\n不要用本 Skill 代替：\n\n- AgentDock 源码开发、重构、测试和 PR 流程；\n- 第三方 Skill 的创作或安全审查；\n- NexusDock、ChatDock 等其他项目自己的配置说明。\n\n## 最重要的配置模型\n\nAgentDock Core 在启动时从**进程环境**读取运行配置。不同发行方式负责把自己的持久化配置转换成 Core 的启动环境：\n\n- macOS Desktop：AgentDock.app 管理自己的运行环境文件；\n- Windows Desktop：控制面板设置、运行清单和受保护凭据共同生成 Core 环境；\n- Linux 服务：systemd\u002FOpenRC 从安装时选择的环境文件加载配置；\n- Docker：容器的 environment \u002F env_file 等启动配置决定 Core 环境；\n- 直接运行二进制：当前 shell 或进程管理器提供环境。\n\n因此：\n\n1. **不存在一个适用于所有平台的 `agentdock.yaml`。不要创建或建议创建它。**\n2. `~\u002F.agentdock` 主要是 AgentDock 状态、Skill、会话等数据目录，不等于所有平台的 Core 运行配置文件。\n3. 改文件不等于已生效。大多数运行配置只有在对应 Core 进程重新启动后才会重新读取。\n4. 多设备之间的运行配置默认彼此独立。修改前先确认目标设备，不要假定一个设备的配置会同步到其他设备。\n\n常用运行配置和边界见 `references\u002Fconfiguration.md`。\n\n## 标准处理流程\n\n### 1. 先确认真实运行环境\n\n优先确认以下事实：\n\n- 当前操作的是哪台 AgentDock 设备；\n- Core 实际运行在 macOS、Windows、Linux 还是容器里；\n- 安装方式是 Desktop、Linux 服务、Docker，还是直接启动二进制；\n- 当前 AgentDock 版本；\n- Core 当前是否运行、健康检查是否通过。\n\n如果宿主提供 `agentdock_context`，优先用它读取当前设备的 `os`、`version`、AgentDock 状态目录和默认工作目录。它只能帮助确认当前 AgentDock 实例，不能替代对 Desktop runtime、service unit、Compose 配置等真实启动来源的检查。\n\n不要因为用户在 macOS 或 Windows 上聊天，就推断 AgentDock Core 一定直接运行在该系统：它也可能实际运行在 Docker、WSL、远程 Linux 或另一台设备。\n\n### 2. 按安装方式读取对应说明\n\n- macOS Desktop：`references\u002Fmacos.md`\n- Windows Desktop：`references\u002Fwindows.md`\n- Linux systemd\u002FOpenRC\u002F手工服务：`references\u002Flinux.md`\n- Docker \u002F Docker Compose：`references\u002Fdocker.md`\n- Coding Agent \u002F ACP：`references\u002Facp.md`\n- 直接运行 `agentdock`：继续使用本文件的“直接运行二进制”说明\n\n只读取与当前环境相关的 reference；处理 ACP 时除平台 reference 外，再读取 `references\u002Facp.md`。不要一次把所有平台的命令都丢给用户选择。\n\n### 3. 修改前先查看现状\n\n涉及配置变更时，先读取当前真实配置来源，再决定修改方式：\n\n- Desktop 优先使用官方设置界面；\n- Linux 先确认 service unit 实际引用的 EnvironmentFile；\n- Docker 先读取当前 Compose\u002Fcontainer 配置；\n- 直接运行二进制先确认启动命令和进程环境来源。\n\n不要只根据默认路径直接覆盖文件。安装器通常允许用户改变安装目录、服务名、环境文件路径或容器配置。\n\n涉及认证 Token、OAuth 密码、签名密钥、Tunnel Token 等秘密时，只确认“是否已配置”或使用安全的专用配置入口，不在回复、日志或截图中回显真实值。\n\n### 4. 让配置真正生效\n\n配置修改后，重启**实际承载 Core 的运行单元**：\n\n- Desktop：由桌面控制器保存并重启，或按平台 reference 使用对应 Core 重启方式；\n- systemd\u002FOpenRC：重启实际 AgentDock service；\n- Docker：环境或 Compose 配置变化后重建\u002F重建容器，不能只依赖 `docker compose restart`；\n- 直接运行二进制：结束旧进程，并从新环境重新启动。\n\n如果只修改 Skill 环境、动态 MCP 注册等由 AgentDock 自己管理的独立状态，应使用对应 Tool 的管理能力，不要误重写 Core 运行配置。\n\n### 5. 修改后必须验证\n\n至少验证两层：\n\n1. **进程层**：Core 已运行，`\u002Fhealthz` 正常，或平台 service status 显示 healthy；\n2. **行为层**：本次修改对应能力真的变化，例如端口、MCP Apps UI、browser、ACP 或子进程环境行为符合预期。\n\n如果当前对话连接的就是被重启的 AgentDock，连接可能短暂中断；恢复后重新读取 `agentdock_context` 或实际状态，不要把“命令执行成功”当成“新配置已经生效”。\n\n配置失败时保留原配置和错误证据，优先恢复到已知可工作的配置，再报告具体失败点。\n\n## 直接运行二进制\n\n直接从终端、脚本或其他进程管理器启动 `agentdock` 时，没有额外的通用持久化配置层：Core 使用启动进程收到的环境变量。\n\n处理方式：\n\n1. 找出真正负责启动 `agentdock` 的 shell、脚本或进程管理器；\n2. 在那个启动来源里修改环境变量，而不是只在另一个终端临时 `export`；\n3. 停止旧 Core；\n4. 从更新后的环境重新启动；\n5. 检查 `\u002Fhealthz` 和目标功能。\n\n如果用户实际使用 systemd、OpenRC、Docker 或 Desktop，不要按“直接运行二进制”处理。\n\n## 回答要求\n\n给用户的最终操作说明应尽量包含：\n\n- 当前识别出的平台和安装方式；\n- 实际配置事实源；\n- 要修改的具体设置；\n- 正确的生效动作；\n- 一条明确的验证方法；\n- 如果发现当前环境与预期不一致，说明证据，而不是继续猜测。\n\n涉及修改时优先直接使用当前可用 AgentDock 工具检查和验证真实环境；只有缺少操作能力时，才让用户手工执行必要步骤。\n\n## 上下文复用\n\n首次缺少规则时调用一次 `agentdock_context`。同一规则作用域后续直接使用业务工具，无新增 AGENTS.md 的子目录操作不重载。后台命令继续观察原 session；普通失败或短暂网络错误先核对原调用；MCP 变化只定向刷新该服务。工作区\u002F规则变化或模型压缩后缺少必要内容时可以再次请求，返回完整有效快照，不需要每次填写 conversation_id\u002Ftask_id。\n","# AgentDock User Guide\n\n这是随 AgentDock 发布的官方用户指南 Skill。目标是让模型基于用户当前真实安装方式，正确解释和操作 AgentDock，而不是依赖固定路径、旧版本经验或猜测。\n\n回答使用用户当前语言；命令、路径和配置键保持原样。\n\n## AgentDock 是什么\n\nAgentDock 是面向 AI Agent 的独立工具运行层。它把文件、命令、Git、Skill、动态 MCP、浏览器、任务等能力通过 MCP 提供给 ChatGPT、Claude、Codex 等客户端；它本身不是聊天界面，也不负责模型推理。\n\n一个 AgentDock 实例对应一个实际运行环境。客户端可以连接本机 AgentDock，也可以连接远程服务器、容器或其他设备上的 AgentDock。多设备场景下，先确认当前工具实际连到哪一个实例，再解释或修改该实例的配置。\n\n通常通过 AgentDock 暴露的 MCP 地址连接，默认 HTTP 端口是 8765，MCP 路径是 `\u002Fmcp`；实际地址、认证方式和端口始终以当前安装\u002F部署配置为准。公网访问必须保留认证并使用 HTTPS，不要把 Token、OAuth 密码或其他凭据发到公开聊天、截图或 Issue。\n\n如果当前 AgentDock 暴露 `agentdock_context`，把它作为识别版本、平台、运行目录、可用 Skill 与能力的首选入口；具体文件、进程、服务和容器状态仍应通过真实工具继续验证。\n\n## AgentDock 生态项目\n\n### Windows Tailscale Funnel\n\n包含原生 Tailscale 支持的 Windows 版本可在“公网访问”页选择 Tailscale Funnel。先检测已安装并登录的官方客户端，设备域名由 CLI 自动读取，不要求 Tunnel Token，也不保存 Auth Key。配置会转发完整 AgentDock Origin，验证 OAuth 与认证接口后才提交就绪状态。遇到其他根映射、私有 Serve 路径或已变化的所有权时保留原配置，不执行全局 reset、down 或 logout。使用前读取 [Tailscale 配置与恢复](references\u002Ftailscale.md)，并以当前 Core 的 `tunnel status --provider tailscale` 能力为准。\n\n### NexusDock\n\n[NexusDock](https:\u002F\u002Fgithub.com\u002Fuvwt\u002Fnexusdock) 是 AgentDock 的自托管中心服务。它把多台 AgentDock、长期记忆和 Workflow 集中到一个入口；单台 AgentDock 仍可独立使用，NexusDock 不是运行 AgentDock 的必需组件。\n\n以下场景尤其适合使用 NexusDock：\n\n- **ChatGPT 只接入一个 MCP**：把多台 AgentDock 与 NexusDock 配对后，ChatGPT 只需要配置 NexusDock 的统一 `\u002Fmcp` 地址。NexusDock 会向客户端提供统一工具入口；需要执行某台设备上的文件、命令、浏览器、Skill、动态 MCP 等能力时，先通过 `agentdock_context` 确认节点，再用对应 `node_id` 把工具调用路由到那台 AgentDock。这样不需要在 ChatGPT 中分别维护多台设备的 MCP 连接。\n- **需要长期记忆能力**：NexusDock 提供集中式 Recall 工作区和 `recall_*` 工具，用于搜索、读取、维护长期项目记忆、运行手册和经验记录。多台 AgentDock 可以使用同一份中心记忆，而不是各自在本机保存彼此不可见的长期上下文。\n- **需要 Workflow 能力**：NexusDock 集中保存和匹配可复用 Workflow 模板，并通过 `workflow_template_manage` 提供给模型；多步骤任务仍可结合 `task_manage` 持久化执行进度。基础 Workflow 不依赖 Embedding，配置向量服务后还可以使用语义匹配。\n- **需要多设备统一管理**：Web 控制台可以查看设备在线状态、版本和运行时能力，并集中查看 Recall、Workflow、任务、Skill 和动态 MCP 状态。\n\nNexusDock 不替代设备端 AgentDock：实际文件、命令、浏览器、Skill、动态 MCP 等设备能力仍由目标 AgentDock 节点执行；NexusDock 负责中心管理、共享 Recall\u002FWorkflow、统一 MCP 接入和跨设备路由。只有一台 AgentDock、也不需要中心记忆或 Workflow 时，可以直接连接 AgentDock，不必额外部署 NexusDock。\n\n统一 MCP 地址形式为：`https:\u002F\u002F\u003C你的 NexusDock 域名>\u002Fmcp`。支持 OAuth 的客户端可以直接授权；其他客户端也可以使用 NexusDock 的 MCP Access Token。具体认证方式以 NexusDock 当前部署为准。\n\n官方仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fuvwt\u002Fnexusdock>\n\n### AgentDock Documentation\n\nAgentDock 的用户文档独立维护在 [uvwt\u002Fagentdock-docs](https:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-docs)。安装、平台配置、部署、升级、工具和用户可见行为等说明应优先参考这里，而不是只依赖主仓库 README。\n\n在线文档：\u003Chttps:\u002F\u002Fuvwt.github.io\u002Fagentdock-docs\u002Fzh-CN\u002F>\n\n文档源码仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-docs>\n\n### AgentDock Skills\n\n[AgentDock Skills](https:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-skills) 是 AgentDock 官方与社区 Skill 的源码与测试仓库。普通业务集成、个人效率工具和社区 Skill 在这里独立维护，内容演进由 Git 历史追踪，避免与 AgentDock Core 版本强耦合。\n\nAgentDock 主仓库的 `core-skills\u002F` 只保留必须随 AgentDock 运行时一起安装和升级的内置核心 Skill；需要查找、阅读、贡献或发布其他 Skill 时，应优先查看 AgentDock Skills 仓库。安装第三方或社区 Skill 前仍应进行来源和安全审查。\n\n官方仓库：\u003Chttps:\u002F\u002Fgithub.com\u002Fuvwt\u002Fagentdock-skills>\n\n### Skill 与标准插件\n\n独立 Skill 使用 `~\u002F.agentdock\u002Fskills\u002F\u003Cname>\u002F`，内置 Skill 使用 `skills\u002F.system\u002F\u003Cname>\u002F`。多版本与回滚数据继续由 `skill_package` 管理。\n\n插件采用 Agent Plugins 1.0.0，自包含目录直接安装在 `~\u002F.agentdock\u002Fplugins\u002F\u003Cname>\u002F`。根目录 `plugin.json` 只保存标准元数据与命名空间扩展，`mcp.json` 保存标准 MCP 定义，Skill 位于 `skills\u002F\u003Cname>\u002FSKILL.md`。不创建第二层插件缓存，不把启停状态或凭据打进插件包。\n\n插件管理位于“功能与插件”页，每张卡片可展开或收起。普通插件的已启用 Skill\u002FMCP 直接进入顶层索引。只有 Heavy 插件先显示摘要，命中后调用 `plugin_load` 展开成员。Heavy 开关与成员开关保存在宿主状态中，切换不改写原插件包。普通工具检索会搜索普通插件，Heavy 插件使用 `plugin_load` 返回的服务器名或完整工具名继续调用。\n\n安装、更新、卸载使用 `plugin_manage`；插件内成员不能通过独立 Skill\u002FMCP 接口重复安装或删除。更新保留总开关、Heavy 覆盖值和仍存在的成员开关。外部数据、凭据保留，卸载插件不会自动删除它们。\n\n从 `.agentdock-plugin\u002Fplugin.json` 旧格式升级时，使用当前 Windows Setup。安装事务会停止旧实例、迁移清单及宿主状态、验证后启动新版，失败时按安装事务恢复。普通 Core 启动不进行隐式迁移。离线副本可以使用当前版本的 `agentdock plugin migrate --home \u003C绝对数据目录>`；先停止写入该目录的进程，不在运行中的真实目录手工转换。\n\n需要从旧 `skill-store` 和逻辑分组迁移整个目录时，使用源码内 `scripts\u002Fmigrate\u002Fmigrate-agentdock-home.ps1`，显式提供不同的源\u002F目标目录及当前 `-AgentDockBinary`，必要时提供仓库外的 `-PluginPlanPath`。源目录保持不变，结果报告保存在目标目录。\n\nWindows“运行配置”页可编辑默认全局工作区、AGENTS.md 自动加载、额外指令文件、浏览器程序、可信代理 CIDR、命令环境变量引用及 ACP 并发\u002F超时。额外指令文件通常留空；明确配置的文件仍须存在、非空且符合 UTF-8\u002F64 KiB 限制。保存会校验并重启，细节见 `references\u002Fwindows.md`。\n\n### ChatGPT 的工具 Schema 缓存\n\n使用 ChatGPT 平台连接 AgentDock 时，工具定义还存在一层平台侧缓存。AgentDock 已经完成工具变更，不代表当前 ChatGPT 会话会立即拿到新的 Schema。\n\n以下变化都应按“工具 Schema 已变更”处理：\n\n- 新增或删除工具；\n- 修改工具名称、描述、输入参数或输出 Schema；\n- AgentDock 升级后导致当前暴露的 MCP 工具集合发生变化。\n\n让变更在 ChatGPT 中生效时：\n\n1. 先确认 AgentDock Core 已经升级\u002F重启并暴露新的工具定义；\n2. 进入 GPT 的 AgentDock 插件页面，点击**刷新**按钮，让 ChatGPT 重新获取 AgentDock 的工具 Schema；\n3. **新开一个会话**再进行验证。旧会话可能继续使用创建会话时缓存的旧 Schema。\n\n因此，如果出现“AgentDock 代码和 Core 都已经更新，但 ChatGPT 仍看不到新工具\u002F新参数”的情况，不要继续反复重启 Core；先检查 ChatGPT 侧是否已经刷新插件并新建会话。这个缓存属于 ChatGPT 平台侧，不是 AgentDock 本地配置未生效。\n\n## 适用场景\n\n使用本 Skill 处理：\n\n- AgentDock 的定位、能力和基本使用方式；\n- “配置文件在哪里”“这个配置怎么改”“改完为什么没生效”；\n- macOS、Windows、Linux、Docker、直接运行二进制之间的配置差异；\n- Core 的启动、停止、重启、健康检查和配置生效验证；\n- 浏览器、MCP Apps UI、端口、日志、OAuth 等运行配置的入口；\n- 发现本机已有 Codex、Claude、Grok 等 Coding Agent，补齐缺失 ACP Adapter，并把 ACP 正确接入 AgentDock；\n- 多台 AgentDock 设备中，确认应该修改哪一台设备的运行配置。\n\n不要用本 Skill 代替：\n\n- AgentDock 源码开发、重构、测试和 PR 流程；\n- 第三方 Skill 的创作或安全审查；\n- NexusDock、ChatDock 等其他项目自己的配置说明。\n\n## 最重要的配置模型\n\nAgentDock Core 在启动时从**进程环境**读取运行配置。不同发行方式负责把自己的持久化配置转换成 Core 的启动环境：\n\n- macOS Desktop：AgentDock.app 管理自己的运行环境文件；\n- Windows Desktop：控制面板设置、运行清单和受保护凭据共同生成 Core 环境；\n- Linux 服务：systemd\u002FOpenRC 从安装时选择的环境文件加载配置；\n- Docker：容器的 environment \u002F env_file 等启动配置决定 Core 环境；\n- 直接运行二进制：当前 shell 或进程管理器提供环境。\n\n因此：\n\n1. **不存在一个适用于所有平台的 `agentdock.yaml`。不要创建或建议创建它。**\n2. `~\u002F.agentdock` 主要是 AgentDock 状态、Skill、会话等数据目录，不等于所有平台的 Core 运行配置文件。\n3. 改文件不等于已生效。大多数运行配置只有在对应 Core 进程重新启动后才会重新读取。\n4. 多设备之间的运行配置默认彼此独立。修改前先确认目标设备，不要假定一个设备的配置会同步到其他设备。\n\n常用运行配置和边界见 `references\u002Fconfiguration.md`。\n\n## 标准处理流程\n\n### 1. 先确认真实运行环境\n\n优先确认以下事实：\n\n- 当前操作的是哪台 AgentDock 设备；\n- Core 实际运行在 macOS、Windows、Linux 还是容器里；\n- 安装方式是 Desktop、Linux 服务、Docker，还是直接启动二进制；\n- 当前 AgentDock 版本；\n- Core 当前是否运行、健康检查是否通过。\n\n如果宿主提供 `agentdock_context`，优先用它读取当前设备的 `os`、`version`、AgentDock 状态目录和默认工作目录。它只能帮助确认当前 AgentDock 实例，不能替代对 Desktop runtime、service unit、Compose 配置等真实启动来源的检查。\n\n不要因为用户在 macOS 或 Windows 上聊天，就推断 AgentDock Core 一定直接运行在该系统：它也可能实际运行在 Docker、WSL、远程 Linux 或另一台设备。\n\n### 2. 按安装方式读取对应说明\n\n- macOS Desktop：`references\u002Fmacos.md`\n- Windows Desktop：`references\u002Fwindows.md`\n- Linux systemd\u002FOpenRC\u002F手工服务：`references\u002Flinux.md`\n- Docker \u002F Docker Compose：`references\u002Fdocker.md`\n- Coding Agent \u002F ACP：`references\u002Facp.md`\n- 直接运行 `agentdock`：继续使用本文件的“直接运行二进制”说明\n\n只读取与当前环境相关的 reference；处理 ACP 时除平台 reference 外，再读取 `references\u002Facp.md`。不要一次把所有平台的命令都丢给用户选择。\n\n### 3. 修改前先查看现状\n\n涉及配置变更时，先读取当前真实配置来源，再决定修改方式：\n\n- Desktop 优先使用官方设置界面；\n- Linux 先确认 service unit 实际引用的 EnvironmentFile；\n- Docker 先读取当前 Compose\u002Fcontainer 配置；\n- 直接运行二进制先确认启动命令和进程环境来源。\n\n不要只根据默认路径直接覆盖文件。安装器通常允许用户改变安装目录、服务名、环境文件路径或容器配置。\n\n涉及认证 Token、OAuth 密码、签名密钥、Tunnel Token 等秘密时，只确认“是否已配置”或使用安全的专用配置入口，不在回复、日志或截图中回显真实值。\n\n### 4. 让配置真正生效\n\n配置修改后，重启**实际承载 Core 的运行单元**：\n\n- Desktop：由桌面控制器保存并重启，或按平台 reference 使用对应 Core 重启方式；\n- systemd\u002FOpenRC：重启实际 AgentDock service；\n- Docker：环境或 Compose 配置变化后重建\u002F重建容器，不能只依赖 `docker compose restart`；\n- 直接运行二进制：结束旧进程，并从新环境重新启动。\n\n如果只修改 Skill 环境、动态 MCP 注册等由 AgentDock 自己管理的独立状态，应使用对应 Tool 的管理能力，不要误重写 Core 运行配置。\n\n### 5. 修改后必须验证\n\n至少验证两层：\n\n1. **进程层**：Core 已运行，`\u002Fhealthz` 正常，或平台 service status 显示 healthy；\n2. **行为层**：本次修改对应能力真的变化，例如端口、MCP Apps UI、browser、ACP 或子进程环境行为符合预期。\n\n如果当前对话连接的就是被重启的 AgentDock，连接可能短暂中断；恢复后重新读取 `agentdock_context` 或实际状态，不要把“命令执行成功”当成“新配置已经生效”。\n\n配置失败时保留原配置和错误证据，优先恢复到已知可工作的配置，再报告具体失败点。\n\n## 直接运行二进制\n\n直接从终端、脚本或其他进程管理器启动 `agentdock` 时，没有额外的通用持久化配置层：Core 使用启动进程收到的环境变量。\n\n处理方式：\n\n1. 找出真正负责启动 `agentdock` 的 shell、脚本或进程管理器；\n2. 在那个启动来源里修改环境变量，而不是只在另一个终端临时 `export`；\n3. 停止旧 Core；\n4. 从更新后的环境重新启动；\n5. 检查 `\u002Fhealthz` 和目标功能。\n\n如果用户实际使用 systemd、OpenRC、Docker 或 Desktop，不要按“直接运行二进制”处理。\n\n## 回答要求\n\n给用户的最终操作说明应尽量包含：\n\n- 当前识别出的平台和安装方式；\n- 实际配置事实源；\n- 要修改的具体设置；\n- 正确的生效动作；\n- 一条明确的验证方法；\n- 如果发现当前环境与预期不一致，说明证据，而不是继续猜测。\n\n涉及修改时优先直接使用当前可用 AgentDock 工具检查和验证真实环境；只有缺少操作能力时，才让用户手工执行必要步骤。\n\n## 上下文复用\n\n首次缺少规则时调用一次 `agentdock_context`。同一规则作用域后续直接使用业务工具，无新增 AGENTS.md 的子目录操作不重载。后台命令继续观察原 session；普通失败或短暂网络错误先核对原调用；MCP 变化只定向刷新该服务。工作区\u002F规则变化或模型压缩后缺少必要内容时可以再次请求，返回完整有效快照，不需要每次填写 conversation_id\u002Ftask_id。\n",{"name":5,"version":23,"description":7},"1.6.0","main","538f75a39df62b23ea9c7927bc5afe7741ff05a4","core-skills\u002Fagentdock-user-guide","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench","https:\u002F\u002Fgithub.com\u002Fkkda49","2026-10-18 04:59:59",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add kkda49\u002FAgentDock-Workbench --skill agentdock-user-guide",{"tool":36,"command":37},"bunx","bunx skills add kkda49\u002FAgentDock-Workbench --skill agentdock-user-guide",{"tool":39,"command":40},"pnpm","pnpm dlx skills add kkda49\u002FAgentDock-Workbench --skill agentdock-user-guide","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002FSKILL.md",true,[44,50,54,58,62,66,70],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Facp.md","REFERENCE","参考文档",12704,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Facp.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fconfiguration.md",5962,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Fconfiguration.md",{"path":55,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fdocker.md",3138,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Fdocker.md",{"path":59,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Flinux.md",4039,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Flinux.md",{"path":63,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fmacos.md",2487,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Fmacos.md",{"path":67,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Ftailscale.md",3824,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Ftailscale.md",{"path":71,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Fwindows.md",5185,"https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fagentdock-user-guide\u002Freferences\u002Fwindows.md",[75,82,89],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":18},"01M7F2596WXYBQMRJSNW1EQMD1","portable-check","Check portable plugin installation without modifying user data.","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Finternal\u002Fplugin\u002Ftestdata\u002Fportable-demo\u002Fskills\u002Fportable-check\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":18},"01M7F256RMEEDD96VSS6HCH7DF","skill-installation","审查、安装、配置、激活、验证、更新、回滚和卸载 AgentDock Skill 时使用；负责来源校验、安全评估、环境配置和已安装版本验收。","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fskill-installation\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":18},"01M7F252K9C7TJ0PHXTDNSXK6H","skill-authoring","创建、设计、修改、升级、重构和验证 AgentDock Skill 时使用；负责可移植核心、文档、引用、辅助脚本、测试、版本和本地安装验证。","https:\u002F\u002Fgithub.com\u002Fkkda49\u002FAgentDock-Workbench\u002Fblob\u002Fmain\u002Fcore-skills\u002Fskill-authoring\u002FSKILL.md",[],[]]