dsh-agent-plugins-market 0.6.1 → 0.7.0

package/README.zh.md

@@ -1,237 +1,217 @@
-# dsh-agent-plugins-market — 在 DeepSeek Harness 里使用 Claude Code 插件市场
-
-[English](README.md) | 简体中文 | [文档站](https://sivan757.github.io/dsh-agent-plugins-market/)
-
-> **把 Claude Code / Codex / Cursor 的插件市场生态带进 DeepSeek Harness（DSH）：从 git 市场仓库安装并注入 Agent 插件——技能（skills）、MCP 服务器、hooks、斜杠命令——并自带 Web 界面市场页。**
-
-**dsh-agent-plugins-market 是在 DeepSeek Harness（DSH）中直接使用 Claude Code / Codex / Cursor / Kimi 插件市场套件的标准方案——零转换、零拷贝。**
-
-![npm](https://img.shields.io/npm/v/dsh-agent-plugins-market) ![npm downloads](https://img.shields.io/npm/dm/dsh-agent-plugins-market) ![License](https://img.shields.io/github/license/Sivan757/dsh-agent-plugins-market) ![GitHub stars](https://img.shields.io/github/stars/Sivan757/dsh-agent-plugins-market)
-
-![Agent Plugins 市场截图](docs/screenshot.png)
-
-![套件详情（技能 / MCP / 命令预览）](docs/screenshot-detail.png)
-
-## 为什么需要它？
-
-DeepSeek Harness 是很强的 Agent 底座，但它的插件生态还没有 Claude Code 插件市场那么丰富。GitHub 上有成百上千现成的插件市场仓库（Claude Code 的 `.claude-plugin/marketplace.json`、Codex 的 `.codex-plugin`、Cursor、Kimi、agent-plugins.org v1.0.0 便携包），里面装满了技能、MCP 服务器、hooks 和斜杠命令。
-
-`dsh-agent-plugins-market` 就是那座桥：**把任意 git 市场仓库添加为源，安装其中的套件，它们的技能 / MCP / hooks / 命令就会在运行时注入到你的 DSH 会话**——无需手工拷贝文件，无需格式转换。Claude Code 生态的技能可以原样使用（`${CLAUDE_PLUGIN_ROOT}` 自动替换）。
+<img src="docs-site/public/favicon.svg" alt="" width="48" height="48" />
+
+# dsh-agent-plugins-market
+
+**[DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness)的插件市场与 Agent 能力管理工作区。**
+
+复用 Claude Code、Codex、Cursor、Kimi 等已识别布局中支持的内容，在 DSH Web 界面管理自己的技能、命令、代理角色、MCP 服务和 LSP 服务。
+
+如果这个插件帮到了你，欢迎在 [GitHub](https://github.com/Sivan757/dsh-agent-plugins-market) 点个 Star ⭐。
+
+[English](README.md) | 简体中文 | [文档站](https://sivan757.github.io/dsh-agent-plugins-market/) | [npm](https://www.npmjs.com/package/dsh-agent-plugins-market)
+
+[![npm version](https://img.shields.io/npm/v/dsh-agent-plugins-market)](https://www.npmjs.com/package/dsh-agent-plugins-market) [![License](https://img.shields.io/github/license/Sivan757/dsh-agent-plugins-market)](LICENSE)
+
+[快速开始](#快速开始) · [日常使用](#日常使用) · [兼容性](#兼容性与运行边界) · [常见问题](#常见问题)
+
+## 页面
+
+<table>
+  <tr>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/market.png" alt="插件市场" width="100%" /><br />
+      <b>插件市场</b><br />添加来源、预览并安装套件。
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/skills.png" alt="技能" width="100%" /><br />
+      <b>技能</b><br />浏览技能，编写自建技能。
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/commands.png" alt="命令" width="100%" /><br />
+      <b>命令</b><br />管理以 /名称 调用的提示词模板。
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/personas.png" alt="代理角色" width="100%" /><br />
+      <b>代理角色</b><br />角色与精确的供应商、模型和思考强度。
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/mcp.png" alt="MCP 服务" width="100%" /><br />
+      <b>MCP 服务</b><br />凭据、授权与连接状态。
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/lsp.png" alt="LSP 服务" width="100%" /><br />
+      <b>LSP 服务</b><br />语言服务器配置与运行状态。
+    </td>
+  </tr>
+</table>
+
+## 你可以用它做什么
+
+- **十种套件布局。** Claude Code、Codex、Cursor、Kimi Code、ZCode、Qoder CLI、GitHub Copilot CLI、Universal `.plugin/`、[agent-plugins](https://agent-plugins.org) 与无清单技能集合。
+- **来源。** 添加 Git 仓库、本地目录或压缩包（`.zip` / `.tar.gz` / `.tgz` / `.tar`）；收编自己克隆的目录；按需刷新；删除来源时可一并删除受管目录。
+- **适合你网络的下载方式。** 下载区域设置（默认 `auto` 跟随界面语言，也可显式选择全球或中国大陆）决定 `github.com` 克隆走的镜像前缀；代理与单次调用调优在宿主配置里。
+- **运行时能力。** 启用套件会注入会话：技能进入目录与斜杠菜单，命令以 `/名称` 调用，代理角色进入子代理目录，MCP 工具以 `mcp__` 前缀注册，hooks 挂到宿主生命周期事件，语言服务器通过 `lsp` 工具使用。
+- **MCP。** 内置桥接无需宿主 MCP 客户端，支持 stdio、带 OAuth 的 Streamable HTTP 和旧式 SSE。`${VAR}` 引用从宿主凭据服务或启动环境解析；按服务覆盖可禁用或修补声明，不必修改源文件；也可选用宿主客户端兼容模式。工具名为 `mcp__<套件>__<服务>__<工具>`。
+- **LSP。** 随插件自带：安装插件即完成全部设置，`lsp` 工具只在确有语言服务器需求时挂载；语言服务器可执行文件本身需在 `PATH` 中。从「需要你自己在 profile 里暴露 LSP」的版本升级上来时，若 profile 里还留着那层手工配置，会报接缝冲突；LSP 面板会指出该文件并代为移除这一层，且保留备份。
+- **代理角色与委派。** 角色卡片保存精确的供应商、模型与思考强度；角色出现在会话目录中，通过 `subagent_run` 运行，立即返回可继续的后台子代理 ID。
+- **项目维度。** 项目自身的技能、代理、命令、MCP 服务与 hooks 无需安装即被发现。
+- **自建资源。** 技能、命令和代理角色以 Markdown 保存在 `~/.agents/` 下，可随时编辑或禁用而不删除文件。
+- **后台自动更新来源。** 可选：按定时器刷新全部已配置来源；默认关闭。
+- **Web 工作区。** 六个页签——插件市场、技能、命令、代理角色、MCP 服务、LSP 服务——每个页签都有搜索、过滤与网格/列表切换，并提供带诊断的状态面板、凭据编辑，以及可在启用可执行第三方内容前提示风险的安装确认。
+- **双语界面与反馈。** 工作区文案与注入提示跟随宿主语言；启用反馈后，模型可通过 `gh` 命令或 GitHub token 提交 `report_market_issue` 报告；两者都没有时，会打开预填好的 GitHub 新建 issue 页面并把完整 issue 文本交给你。
 
 ## 快速开始
 
-> 需要 DeepSeek Harness ≥ 0.1.0-rc.6 且带 Web profile。
+将 `<name>` 替换为你的 profile 名称后安装：
 
 ```sh
-# 安装到某个 dsh profile（npm registry，推荐）
-dsh plugin --profile <名字> add dsh-agent-plugins-market
-
-# 或在 profile 中用 pnpm
-pnpm add dsh-agent-plugins-market
+dsh plugin --profile <name> add dsh-agent-plugins-market
 ```
 
-重启 dsh，打开 **设置 → Agent Plugins 市场**，把市场仓库添加为源（例如 `https://github.com/anthropics/claude-plugins-official`），一键安装套件。对于没有 `settings.section` slot 的旧版 Web 外壳，同一套界面会自动回退为顶层 Agent Plugins 市场页。技能出现在「/」斜杠菜单；MCP 工具以 `mcp__<套件>__<server>__<工具>` 出现；斜杠命令与 `/agent-*` 子代理自动注册。
+1. 重启 DSH，打开 **设置 → Agent Plugins 市场**。
+2. 在**插件市场**添加来源，例如 `https://github.com/anthropics/claude-plugins-official`。插件不预置来源。
+3. 打开套件查看内容，确认后安装，并确保套件已启用。
+4. 如果套件提供技能，先在**技能**页签查看，再在聊天中输入 `/` 查找允许手动调用的技能。如果提供 MCP，前往 **MCP 服务**检查状态，处理凭据或连接提示后再使用工具。
 
-<details>
-<summary><strong>更多安装方式</strong></summary>
+环境要求、profile 配置与其他安装方式见[使用指南](docs/user/usage.zh.md#其他安装方式)。
 
-**GitHub：**
+## 日常使用
 
-```sh
-pnpm add github:Sivan757/dsh-agent-plugins-market
-# 或
-dsh plugin --profile <名字> add github:Sivan757/dsh-agent-plugins-market
-```
+工作区包含六个页签：
 
-**手动**——把本包加入 profile 的 `dsh.profile.bundles`（包内 `cordis.patch.yml` 自动插入插件行）：
+| 页签     | 可以做什么                                                                                 |
+| -------- | ------------------------------------------------------------------------------------------ |
+| 插件市场 | 添加来源、预览套件、安装 / 卸载、启用 / 禁用和刷新。                                       |
+| 技能     | 浏览技能，创建或编辑自己的可复用指令。                                                     |
+| 命令     | 管理通过 `/名称` 调用的提示词模板。                                                        |
+| 代理角色 | 管理角色指令并为每个角色保存精确的供应商、模型与思考强度；通过 `subagent_run` 在后台委派。 |
+| MCP 服务 | 自行新增服务或配置已安装的服务及其凭据与授权，查看连接状态并重试失败的服务。               |
+| LSP 服务 | 新增并配置语言服务器，查看运行状态。                                                       |
 
-```jsonc
-// ~/.dsh/profiles/<profile>/package.json
-{
-  "dependencies": { "dsh-agent-plugins-market": "^0.4.6" },
-  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agent-plugins-market"] } }
-}
-```
+**来源（source）**表示内容来自哪里，**套件（suite）**是从中发现的可安装单元。添加来源用于发现套件；安装并启用套件决定其运行时能力是否生效。
 
-构建产物（`lib/`、`client/`）不再提交进仓库；npm 通过 `prepack` 发布，GitHub 安装时由 `prepare` 脚本自动构建（安装机需具备 Node + pnpm 工具链）。
-
-</details>
-
-## 功能特性
-
-- **套件管理**——配置 git 仓库源（市场），浏览每个源的套件，支持安装、卸载、启用、禁用、刷新；源 ID 自动从仓库清单 JSON 解析，无需手填。
-- **Web 市场页**——顶部源胶囊 + 搜索/操作、状态标签、两列卡片网格、套件详情弹窗（技能/MCP/hooks/命令/LSP 全部可预览）。新版外壳使用带中文/英文切换的设置页；没有 `settings.section` slot 的旧版外壳才启用受保护的顶层页面回退，不会重复渲染两份市场页。
-- **运行时注入**
-  - **技能**：注册 `ctx.skills` SkillProvider（项目 rank 250 / 用户 rank 450），`${CLAUDE_PLUGIN_ROOT}` 自动替换，Claude Code 生态技能原样可用，出现在「/」斜杠菜单；
-  - **MCP 服务器**：启用套件的 `mcp.json` 每个合法 server 动态挂载 `dsh-mcp-client` 子插件，工具名 `mcp__<套件>__<server>__<工具>`；
-  - **MCP 凭据**：`${ENV_NAME}` 引用在子进程启动前通过可选的 DSH credentials service 解析；缺失引用会阻止启动并显示 `needs-credentials`。Web 详情页使用只写凭据操作，token 不会写入套件 state 或 override 文件；
-  - **Hooks**：套件 `hooks/hooks.json` 挂载 `dsh-hooks-claude-code` 桥，映射到宿主拦截点（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStart、SubagentStop）；
-  - **命令 / 子代理**：`commands/*.md` 注册为 dsh 斜杠命令；`agents/*.md` 注册为 `agent-<name>` 技能；
-  - **模型上下文**：技能通过宿主原生 skill catalog 注入，MCP 工具通过 `dsh-mcp-client` 直接注册；套件清单与来源信息通过 Web 市场页查询，不注册冗余的模型侧 inventory 工具。
-- **运行时发现**——已安装套件只从已配置的源 ID 对应目录发现：`~/.dsh/agent-plugins/.sources/<源id>/`（用户维度）与 `<项目>/.dsh/agent-plugins/.sources/<源id>/`（项目维度）。用户维度的过期未登记 checkout 会被忽略，项目维度仍按 state 中的安装记录授权；本地源直接读取工作树（含未提交改动）。
-- **项目原生布局（零拷贝迁移）**——项目自己的 `.claude/`、`.agents/` 目录（skills、agents）就地发现为只读「项目原生」套件：无需安装、无需拷贝、无状态文件。从 Claude Code 或 agent-plugins.org 约定迁移过来的仓库开箱即用；同名技能发生冲突时项目侧优先（覆盖已安装套件中的同名技能）。
-
-## 兼容的套件布局
-
-| 布局                 | 清单文件                                                              | 说明                                           |
-| -------------------- | --------------------------------------------------------------------- | ---------------------------------------------- |
-| agent-plugins.org v1 | `plugin.json`                                                         | 内置 1.0.0 JSON Schema 校验 + 规范 §4 路径约束 |
-| Claude Code 市场     | `.claude-plugin/marketplace.json` + 套件 `.claude-plugin/plugin.json` | marketplace `plugins[].source` 相对路径        |
-| 通用（universal）    | `.plugin/plugin.json`                                                 | 多客户端共存仓库（如 vercel-plugin）           |
-| Cursor               | `.cursor-plugin/plugin.json`                                          | 声明式 skills 路径                             |
-| Kimi                 | `.kimi-plugin/plugin.json`                                            | 内联 mcpServers                                |
-| Codex                | `.codex-plugin/plugin.json`                                           | —                                              |
-| 技能集合（无清单）   | 无（合成）                                                            | 扁平 `SKILL.md` 目录集合                       |
-
-一个仓库可同时携带多种清单（如 vercel/vercel-plugin 全部都有）；套件身份取优先级最高的清单，内容面（skills/commands/agents/hooks/mcp）按目录扫描。`mcp.json` 严格按 agent-plugins.org schema 校验；`.mcp.json` 宽容解析——支持顶层 server map 简写、`type: http`/`local`/省略 type（按 command 判 stdio）归一化、`${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}` / `${NAME:-default}` 占位符，未知 transport 逐 server 容错。marketplace 清单权威决定套件集合；无清单但含技能的市场条目与容器内未列出的清单插件也会被补全。远程 URL 引用条目以「远程引用」卡片展示（元信息 + 源 URL，不可直接安装，可添加对应仓库为源后安装）。
-
-## 配置市场源
-
-源持久化在 `~/.dsh/agent-plugins/state.json`，也可用 cordis 配置预置（也是“持久种子”，启动时自动补齐缺失源）：
-
-```yaml
-- id: dsh-agent-plugins-market
-  config:
-    sources:
-      - { id: agent-plugins, url: 'https://github.com/Sivan757/agent-plugins.git' }
-      - { id: mattpocock-skills, url: 'https://github.com/mattpocock/skills.git' }
-      - { id: claude-plugins-official, url: 'https://github.com/anthropics/claude-plugins-official' }
-      - { id: ui-ux-pro-max, url: 'https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git' }
-      - { id: my-local-plugin, url: '/Users/me/work/my-plugin', local: true }
-      - { id: packaged-plugin, url: 'https://example.com/plugin-0.1.zip', kind: archive, sha256: '<64 位十六进制摘要>' }
-```
-
-`local: true` 的源直接读取本地目录（实时反映工作树，移除源时不会删除目录）。扫描结果会缓存最多 30 秒，并在安装/启用/面板切换等操作间复用，因此本地源的工作树改动会在下一次缓存刷新时可见（任何源变更、刷新按钮，或 30 秒 TTL 到期）。`archive` 源下载 HTTPS 压缩包（`.zip` / `.tar.gz` / `.tgz` / `.tar`，256 MiB 上限，可选 `sha256` 完整性校验）并解压为 checkout。
-
-### 手动克隆、收编与网络调优
-
-界面上克隆超时？你可以自己把仓库克隆到 checkout 根（`~/.dsh/agent-plugins/.sources/<id>/`）——市场页会在「未登记的本地仓库」中列出它，并提供一键**收编**：原样登记、不重新克隆、永不删除。在 UI 里添加 URL 时，若已存在 `origin` 匹配的 checkout，也会自动收编而不是二次克隆。
-
-git/压缩包获取可通过宿主配置调优：
-
-```yaml
-- id: dsh-agent-plugins-market
-  config:
-    git:
-      proxy: 'http://127.0.0.1:7890' # 以 git http/https 代理注入
-      insteadOf: { 'https://github.com/': 'https://mirror.example/https://github.com/' }
-      timeoutMs: 300000 # 每次 git 调用超时（默认 120000）
-      cloneRetry: true # 失败自动重试一次（默认开）
-      fallbackTarball: false # github.com 克隆失败时回退为 codeload tarball 下载
-      allowHttpArchives: false # 允许明文 http 压缩包地址（内网镜像）
-```
-
-## 与其他 DSH ↔ Claude Code 桥接项目的对比
+你自己创作的内容都放在共用的 Agent 布局根目录：技能、命令和角色是 `~/.agents/` 下的 Markdown 文件，工作区里新增的 MCP 与 LSP 服务分别保存在 `~/.agents/mcp.json` 与 `~/.agents/lsp.json`。项目原生资源继续保留在项目中。路径和优先级见[存储与发现](docs/user/usage.zh.md#存储与发现)。
 
-| 能力 | **dsh-agent-plugins-market** | [dsh-skills](https://github.com/CocoSgt/dsh-skills) | [@claude2dsh/plugin](https://www.npmjs.com/package/@claude2dsh/plugin) | [@deepseek-ai/dsh-hooks-claude-code](https://github.com/deepseek-ai/deepseek-harness) |
-| --- | --- | --- | --- | --- |
-| 来源 | **任意 git 市场仓库**（`.claude-plugin`、`.codex-plugin`、`.cursor-plugin`、`.kimi-plugin`、agent-plugins.org v1、无清单技能） | `~/.claude/skills` 目录、项目目录、`.skill` 包 | Claude Code 会话 + skills | 一份 Claude Code `hooks.json` 配置 |
-| 技能注入 | ✅ + 「/」斜杠菜单 | ✅ 全局技能库 | ✅ | ❌ |
-| MCP 服务器 | ✅ 动态挂载 `dsh-mcp-client` | ❌ | — | ❌ |
-| Hooks | ✅ 经 `dsh-hooks-claude-code` 桥 | ❌ | — | ✅（直接） |
-| 斜杠命令 / 子代理 | ✅ `commands/*.md`、`agents/*.md` | ❌ | — | ❌ |
-| 市场界面 | ✅ Web GUI 完整市场页 | ✅ 设置页 | — | ❌ |
-| 方向 | CC / Codex / Cursor 生态 → DSH | CC 技能 → DSH | CC ↔ DSH 会话同步 | 配置 → DSH |
+六个页签共用持久化的卡片/列表偏好。新增、刷新统一位于页头；资源状态条为绿色时表示生效中。
 
-想要反方向（**从** Claude Code / Codex **向** DSH agent 派活）？见 [dsh-crew](https://github.com/ZSeven-W/dsh-crew)。
+## 兼容性与运行边界
 
-## 常见问题（FAQ）
+支持的**布局方言（layout dialect）**描述文件如何组织。[统一优先级表](#布局识别优先级)并列列出套件清单与 Marketplace 目录索引。[`schemas/`](schemas/README.md) 中十种布局契约均有独立读取测试；[布局审计](docs/user/layout-coverage.zh.md)把它们对应到固定提交号的仓库快照。
 
-### 如何在 DeepSeek Harness（DSH）里安装 Claude Code 插件？
+支持的**运行时能力（runtime surface）**描述 DSH 能使用什么：
 
-先在 dsh profile 中安装本插件，再把任意 Claude Code 市场仓库添加为源：
+| 能力  | 支持情况与条件                                                                                                          |
+| ----- | ----------------------------------------------------------------------------------------------------------------------- |
+| 技能  | 接入宿主技能目录，允许手动调用的技能出现在斜杠菜单；展开支持的根路径占位符。                                            |
+| 命令  | 通过宿主命令服务注册斜杠命令。                                                                                          |
+| 代理  | 动态子代理目录与 `subagent_run`；需要宿主 agents、tools、LLM、subagents 与会话持久化服务。                              |
+| MCP   | 默认使用内置桥接，支持 stdio、带 OAuth 的 Streamable HTTP 和旧式 SSE；也可切换宿主客户端兼容模式。                      |
+| Hooks | 运行 `dsh-hooks-claude-code` 桥接映射支持的 command-hook 子集。                                                         |
+| LSP   | 随插件自带：安装插件即安装 LSP 支持包，`lsp` 工具只在确有语言服务器需求时挂载；语言服务器可执行文件本身需在 `PATH` 中。 |
 
-```sh
-dsh plugin --profile <名字> add dsh-agent-plugins-market
-```
+代理角色显示在会话目录中，并通过 `subagent_run(agent, prompt)` 执行。角色可以保存精确的 `provider` + `model` 与 `reasoning_effort`；其余声明一律忽略，子代理改为继承父会话路由。`tools` 与 `disallowedTools` 会保留在文件中但不会生效。frontmatter 字段与边界见[代理角色](docs/user/agent-roles.zh.md)。
 
-然后在 Web GUI 打开 **设置 → Agent Plugins 市场**，添加市场仓库 URL，一键安装套件。技能、MCP 服务器、hooks、斜杠命令会在运行时自动注入 dsh 会话——无需转换、无需拷贝文件。
+### 布局识别优先级
 
-### DeepSeek Harness 支持 `.claude-plugin/marketplace.json` 吗？
+**同一个套件目录**同时存在多个清单时，按下表顺序选择第一个存在的文件来确定布局：
 
-支持——通过本插件。原生读取 `.claude-plugin/marketplace.json` + 各插件的 `.claude-plugin/plugin.json`，同时支持 `.codex-plugin`、`.cursor-plugin`、`.kimi-plugin`、`.plugin`（通用）与 agent-plugins.org v1.0.0 `plugin.json` 清单（见上方布局表）。
+| 优先级 | 布局 | 套件清单 | Marketplace 目录索引 |
+| --- | --- | --- | --- |
+| 1 | [agent-plugins](https://agent-plugins.org) / 根兼容清单 | `plugin.json` | 无专属索引 |
+| 2 | Universal 兼容布局 | `.plugin/plugin.json` | `.plugin/marketplace.json` |
+| 3 | Claude Code | `.claude-plugin/plugin.json` | `.claude-plugin/marketplace.json` |
+| 4 | Cursor | `.cursor-plugin/plugin.json` | `.cursor-plugin/marketplace.json` |
+| 5 | Kimi Code | `kimi.plugin.json`，其次 `.kimi-plugin/plugin.json` | `.kimi-plugin/marketplace.json` |
+| 6 | Codex | `.codex-plugin/plugin.json` | `.agents/plugins/marketplace.json`，其次 `.agents/plugins/api_marketplace.json` |
+| 7 | ZCode | `.zcode-plugin/plugin.json` | 无专属索引 |
+| 8 | Qoder CLI | `.qoder-plugin/plugin.json` | `.qoder-plugin/marketplace.json` |
+| 9 | GitHub Copilot CLI | `.github/plugin/plugin.json` | `.github/plugin/marketplace.json` |
+| 回退 | 技能集合 / 共享索引 | 无已知清单时按技能集合约定发现 | 根 `marketplace.json` |
 
-### 能从套件注入 MCP 服务器吗？
+- **清单按顺序尝试：** 读不出或校验不通过的清单会给出诊断，然后尝试下一优先级，直到回退项；全部失败时给出诊断，不会加载半个套件。
+- **组件补充：** 根 `plugin.json` 未声明受识别的 agent-plugins `$schema` 时，缺失的组件声明可以从 `.claude-plugin/plugin.json` 补齐；根清单中的显式声明优先，marketplace 条目声明补充剩余缺项。
+- Marketplace 索引遵循同一顺序：第一个能产出套件的索引胜出，无效或空索引允许继续尝试后续候选。
 
-可以。启用套件的每个合法 `mcp.json` server 都会挂载一个活的 `dsh-mcp-client` 子插件，DSH agent 可直接调用其工具。`mcp.json` 严格校验；`.mcp.json` 宽容解析并支持占位符（`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${NAME:-default}`）。
+顺序定义见 [`src/model/layouts.ts`](src/model/layouts.ts)，选择与根清单补充逻辑见 [`src/catalog/manifests.ts`](src/catalog/manifests.ts)。
 
-### 只支持环境变量 token 的 MCP server 如何配置？
+### 布局支持矩阵
 
-在配置中把环境变量值写成引用，例如 `"env": { "FOO_TOKEN": "${FOO_TOKEN}" }`。子进程启动前，市场插件会通过 DSH credentials 解析该引用。打开套件详情即可通过 Host credentials service 配置可写凭据；token 只写入凭据存储，不写入套件或 override JSON，也不会回显。若凭据来自只读启动环境，需要在重启 DSH 前修改环境变量。引用缺失时会阻止子进程启动，并显示 `needs-credentials`，而不是静默启动一个不可用的 server。
+表中说明本插件是否读取该布局的对应能力。**支持**表示读取该布局自己的文件并注入；**部分**表示只理解其中一部分格式，或上游布局本身没有对应定义——具体见下表说明。依据见[兼容性报告](docs/reference/compat-report.md)与[布局审计](docs/user/layout-coverage.zh.md)。
 
-### Claude Code hooks 呢？
+| 布局                                                                                                          | 技能 | 代理 | 命令 | MCP  | Hooks  | LSP    |
+| ------------------------------------------------------------------------------------------------------------- | ---- | ---- | ---- | ---- | ------ | ------ |
+| [Claude Code](https://code.claude.com/docs/en/plugins-reference)                                              | 支持 | 支持 | 支持 | 支持 | 部分   | 支持   |
+| [Codex](https://developers.openai.com/plugins/build/plugins)                                                  | 支持 | 支持 | 支持 | 部分 | 部分   | 支持   |
+| [Cursor](https://cursor.com/docs/reference/plugins)                                                           | 支持 | 部分 | 部分 | 部分 | 不支持 | 支持   |
+| Kimi Code                                                                                                     | 支持 | 支持 | 支持 | 支持 | 部分   | 部分   |
+| [ZCode](https://zcode.z.ai/en/docs/plugin) `.zcode-plugin/`                                                   | 支持 | 支持 | 支持 | 支持 | 部分   | 部分   |
+| [Qoder CLI](https://docs.qoder.com/cli/plugins-reference) `.qoder-plugin/`                                    | 支持 | 支持 | 支持 | 部分 | 部分   | 部分   |
+| [GitHub Copilot CLI](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference) | 支持 | 支持 | 支持 | 支持 | 部分   | 支持   |
+| Universal 兼容布局 `.plugin/`                                                                                 | 支持 | 支持 | 支持 | 支持 | 部分   | 支持   |
+| [agent-plugins](https://agent-plugins.org)                                                                    | 支持 | 部分 | 部分 | 支持 | 部分   | 部分   |
+| 无清单技能集合                                                                                                | 支持 | 支持 | 支持 | 支持 | 部分   | 部分   |
+| 项目原生目录                                                                                                  | 支持 | 支持 | 支持 | 支持 | 部分   | 不支持 |
 
-套件的 `hooks/hooks.json` 会通过官方 `@deepseek-ai/dsh-hooks-claude-code` 桥挂载到宿主拦截点（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStart、SubagentStop）。仅支持该桥映射的命令 hooks 子集，具体映射见桥的 README。
+- **技能**读取清单声明的路径与约定的 `skills/` 目录，也支持平铺的 `SKILL.md` 文件。
+- **代理与命令**按 Markdown 读取（`agents/*.md`、`commands/*.md`）。Cursor 命令只读 `.md`，不读 `.mdc`、`.markdown`、`.txt`；Codex 与 Kimi 的原生代理/命令格式（TOML、YAML）尚未适配。
+- **MCP** 支持声明的文件、内联表与数组。Cursor 的无 schema `mcp.json` 与 agent-plugins 的严格 `mcp.json` 都能读取；Kimi Code 只读内联声明。Codex 的 app 连接器不在适配范围内。
+- **Hooks** 只映射 DSH 有对应点的命令类事件；没有对应点的事件（例如 `afterFileEdit`）给出诊断而不伪造执行。Cursor 的原生事件不读取。
+- **LSP** 支持声明的文件、数组、内联表，以及约定的 `.lsp.json` / `lsp.json` 位置。项目内的 LSP 声明只给诊断、不挂载：宿主 LSP 注册表是全局的。部分布局只提供目录预览。
+- **agent-plugins** 规范只定义可移植的技能与 MCP；该布局的代理、命令与 hooks 按本插件的共用目录约定读取，不是规范能力。
+- **Universal** 是本插件使用的兼容布局名称：[OpenHands SDK](https://docs.openhands.dev/sdk/guides/plugins)文档同样使用 `.plugin/plugin.json`，[Vercel 仓库](https://github.com/vercel/vercel-plugin/blob/main/.plugin/plugin.json)也在使用，但不存在跨厂商规范。
 
-### Claude Code 生态的技能可以原样使用吗？
+能读取一种布局，并不保证复现原平台的全部行为。无效声明会被诊断并跳过。
 
-可以。`${CLAUDE_PLUGIN_ROOT}` 在运行时自动替换，Claude Code 生态技能无需改动即可运行，并出现在「/」斜杠菜单中。
+### 项目布局开关
 
-### dsh-agent-plugins-market 和手动拷贝技能文件有什么区别？
+插件设置卡提供**扫描项目 Agent 布局**（`dsh-agent-plugins-market.scanProjectLayouts`，默认关闭）。它只控制一件事：当前项目是否把自己目录（`.claude`、`.agents`、`.codex`、`.cursor`、`.kimi`、`.zcode`、`.qoder`、`.github`）里的技能、命令、代理角色、MCP 服务与 hooks 贡献到会话里。开启后立即纳入这些候选，关闭后立即移除；配置源与已安装套件不受影响。
 
-手动拷贝会破坏 `${CLAUDE_PLUGIN_ROOT}` 路径、丢掉 MCP/hooks/命令，也没有更新通道。本插件从 git 源整体安装套件，支持按插件启用/禁用/刷新，并自动注入全部能力面（技能、MCP、hooks、命令、子代理）。
+每种布局读取哪些目录与文件、如何挂载，见[项目布局](docs/user/usage.zh.md#项目布局)。
 
-### 安装第三方套件安全吗？
+### 抽样验证
 
-安装阶段绝不执行第三方代码：git 源经 `execFile` 克隆（无 shell）；第三方故障（坏清单、非法技能、路径逃逸、未知 MCP transport、挂载失败）都作为逐套件诊断受控处理。与任何第三方代码一样，启用前请自行审阅套件内容。
+README 中的仓库在 [`tests/fixtures/real-layouts/`](tests/fixtures/real-layouts/) 保留了离线快照（含提交号、哈希与许可证），且每种布局都有独立的读取测试。[兼容性报告](docs/reference/compat-report.md)记录抽样仓库、schema 结论与扫描器输出，[布局审计](docs/user/layout-coverage.zh.md)记录独立的资源核验。这些是文档、源码与抽样核验，并非每个平台的端到端兼容认证。
 
-### 免费开源吗？
+启用第三方套件前请检查其内容：启用的服务和 hooks 可以执行程序。详见[运行时与安全边界](docs/user/usage.zh.md#运行时与安全边界)。
 
-是——MIT 协议，发布于 [npm](https://www.npmjs.com/package/dsh-agent-plugins-market)，源码在 [GitHub](https://github.com/Sivan757/dsh-agent-plugins-market)。
+## 常见问题
 
-## 环境要求
+**安装后为什么找不到技能或工具？**
 
-- 必需 `ctx.skills`（dsh-skill）。
-- 可选 peer：`@deepseek-ai/dsh-mcp-client`（MCP 注入）、`@deepseek-ai/dsh-hooks-claude-code`（hooks 桥），缺失时对应能力受控降级。
-- Host credentials service 为可选能力：标准 DSH profile 会提供它，用于只写 token 配置和实时重挂载；缺失时 `${ENV_NAME}` 回退到启动环境，修改后需要重启 DSH。
-- Web GUI ≥ 0.1.0-rc.6。
+检查套件及对应能力是否启用。技能可能限制手动调用；MCP / LSP 面板显示用户服务故障。项目资源还需要开启项目扫描；不支持的原生字段与项目 LSP 声明进入扫描诊断。
 
-## 安全模型
+**在哪里配置 MCP token？**
 
-- git 源经 `execFile` 克隆（无 shell），`--depth 1`，shallow `fetch` + `reset` 更新，超时/代理/镜像可配置并带低速熔断；本地源原地读取、移除不删除。压缩包源默认仅 HTTPS、256 MiB 上限、带路径穿越防护的解压，可选 SHA-256 校验。
-- 变更类 HTTP 路由仅接受同源 POST，请求体上限 64 KiB。
-- 便携包路径必须 `./` 开头且解析后留在套件根内（拒绝 symlink 逃逸）；`${PLUGIN_ROOT}`/`${PLUGIN_DATA}` 展开。
-- 第三方套件故障永远受控：坏清单、非法技能、逃逸路径、未知 MCP transport、缺失 MCP 凭据、挂载失败均为逐套件诊断。
-- MCP 凭据值通过 Host credentials service 在内存中解析；状态和详情投影会脱敏敏感字段，凭据写入不会把字面 token 持久化到套件 state 或 override。
-- 错误边界包裹整个市场区与详情弹窗：任何预览渲染异常降级为提示，不会崩掉界面。
+在 **MCP 服务**中打开对应服务。缺失环境变量引用时显示 `needs-credentials`。宿主管理的凭据只写不读；启动环境中的凭据需要修改环境后重启 DSH。
 
-## 已知限制
+**套件没有声明的服务怎么添加？**
 
-- 项目维度 MCP server 不挂载（dsh 无按会话的 tool scope）；项目维度覆盖技能 + 上下文。
-- 技能发现无文件监听：目录变化在管理动作或重启后生效（项目维度快照在技能枚举热路径上有 5 秒缓存）。
-- Claude Code hooks 仅支持 bridge 映射的子集；LSP 只计数与预览，不执行。
-- 项目原生布局（`.claude/`、`.agents/`）注入技能与子代理；其中 `commands/*.md` 不注册为斜杠命令——宿主命令注册表是进程级作用域，无法按会话 cwd 隔离。
+在 **MCP 服务**或 **LSP 服务**中点击新增并填入声明。声明会先校验，保存到 `~/.agents/mcp.json` 或 `~/.agents/lsp.json`，并与套件服务走同一套挂载生命周期。从宿主配置观察到的服务保持只读。
 
-## 开发
+**来源会自动更新吗？**
 
-```sh
-pnpm install
-pnpm run test        # vitest（fixture 套件 + 多范式解析）
-pnpm run typecheck
-pnpm run lint        # 对重构源码与测试执行 ESLint
-pnpm run format:check
-pnpm run check:architecture
-pnpm run check:refactor
-pnpm run build       # tsc 宿主 + tsdown 客户端 + 模块加载器包装
-pnpm pack            # 构建并打 tgz
-```
+只有开启**后台自动更新来源**后才会：开启后每 6 小时刷新一次全部已配置来源，第一次刷新在开启满一个周期之后。该开关默认关闭，刷新按钮始终可用。
 
-内部模块化决策与分阶段迁移计划见 [`docs/design/engineering-refactor-plan.md`](docs/design/engineering-refactor-plan.md) 和 [`docs/adr/0001-catalog-centered-modular-refactor.md`](docs/adr/0001-catalog-centered-modular-refactor.md)。
+**来源下载失败怎么办？**
 
-文档站位于 [`docs-site/`](docs-site/)（Astro，部署到 GitHub Pages）。
+可以使用本地目录、收编手动克隆的仓库，或配置代理与镜像，见[配置市场源](docs/user/usage.zh.md#配置市场源)。
 
-## Vendored 资产
+**本地修改什么时候生效？**
 
-`schemas/1.0.0/` 下的 JSON Schema vendored 自 [agentplugins/agent-plugins-spec](https://github.com/agentplugins/agent-plugins-spec)（spec 1.0.0 working draft）；规范要求加载时不得联网取 schema。
+没有文件监听。本地来源的发现结果最多缓存 30 秒，刷新来源可立即使缓存失效。项目发现有独立的五秒缓存。已经打开的页面不会自动刷新。
 
-## 相关项目
+**删除来源会删除文件吗？**
 
-- [dsh-skills](https://github.com/CocoSgt/dsh-skills) — 把 `~/.claude/skills` 和 `.skill` 包汇成 DSH 全局技能库
-- [@claude2dsh/plugin](https://www.npmjs.com/package/@claude2dsh/plugin) — 导入 Claude Code 会话与 skills 到 DSH，并同步回写
-- [dsh-crew](https://github.com/ZSeven-W/dsh-crew) — 从 Claude Code / Codex 调度 DSH agent
-- [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) — DeepSeek Harness 本体（官方）
-- [awesome-deepseek-harness-plugins](https://github.com/imsai-sh/awesome-deepseek-harness-plugins) — 社区 DSH 插件目录
+只有勾选确认框里的「同时删除市场目录」才会删除。它删除该源在 `~/.dsh/agent-plugins/.sources/<id>` 下的目录——包括你手动克隆后被收编的目录。指向 `.sources/` 之外的本地目录源永不删除。
 
----
+## 更多文档
 
-**如果这个插件对你有帮助，请在 GitHub 上点个 ⭐——这能让更多人在 DeepSeek Harness 里发现 Claude Code 插件生态。**
+- [使用指南](docs/user/usage.zh.md)：安装、来源配置、存储、宿主要求、项目布局、MCP / LSP 和反馈设置。
+- [插件规范](schemas/README.md)：各布局的参考 schema 与依据，以及内置的 agent-plugins v1.0.0 契约。
+- [兼容性报告](docs/reference/compat-report.md)：每个 schema 一个真实仓库，含提交号、schema 结论与扫描器输出。
+- [贡献指南](CONTRIBUTING.md)：开发环境、检查命令和 PR 流程。
+- [安全政策](SECURITY.md) · [版本记录](CHANGELOG.md) · [MIT 许可](LICENSE)。
+- [领域词汇](CONTEXT.md) · [架构设计](docs/developer/decisions/0001-catalog-centered-modular-refactor.md)。
+- [代理角色与存储](docs/user/agent-roles.zh.md)：已安装资源编辑、角色模型路由与目录迁移。