dsh-agent-plugins-market 0.5.3 → 0.6.1

package/README.md

@@ -64,6 +64,7 @@ Build artifacts (`lib/`, `client/`) are not committed; npm publishes them via `p
 - **Runtime injection**
   - **Skills** — a `ctx.skills` SkillProvider (project rank 250 / user rank 450); `${CLAUDE_PLUGIN_ROOT}` is substituted so Claude Code-authored skills work verbatim, and appear in the `/` slash menu.
   - **MCP servers** — every valid `mcp.json` server of an enabled plugin mounts a live `dsh-mcp-client` child; tools appear as `mcp__<plugin>__<server>__<tool>`.
+  - **MCP credentials** — `${ENV_NAME}` references resolve through the optional DSH credentials service before a child starts; missing references block the spawn and surface as `needs-credentials`. The Web detail view uses write-only credentials operations and never persists token values in suite state or overrides.
   - **Hooks** — a plugin's `hooks/hooks.json` mounts the `dsh-hooks-claude-code` bridge on the harness interception points (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop).
   - **Commands / subagents** — `commands/*.md` register as dsh slash commands; `agents/*.md` register as `agent-<name>` skills.
   - **Model context** — skills flow through the host-native skill catalog and MCP tools register directly through `dsh-mcp-client`; suite inventory and source metadata remain available in the Web market page without adding a redundant model-facing inventory tool.
@@ -97,9 +98,28 @@ Sources persist in `~/.dsh/agent-plugins/state.json`; cordis config seeds them (
       - { 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-hex digest>' }
 ```
 
-A `local: true` source reads the directory in place (live working tree; never deleted on removal).
+A `local: true` source reads the directory in place (live working tree; never deleted on removal). Discovery results are cached for up to 30 seconds and reused across install/enable/panel actions, so working-tree edits of local sources appear on the next cache refresh (any source mutation, the refresh button, or the 30 s TTL). An `archive` source downloads an HTTPS `.zip` / `.tar.gz` / `.tgz` / `.tar` payload (256 MiB cap, optional `sha256` integrity pin) and extracts it as the checkout.
+
+### Manual clones, adoption, and network tuning
+
+Cloning from the UI times out on a restricted network? Clone the repository yourself into the checkout root (`~/.dsh/agent-plugins/.sources/<id>/`) — the market page lists it under **unregistered local checkouts** with a one-click **adopt** action that registers it in place (no re-clone, no deletion, ever). Adding a URL whose checkout already exists with a matching `origin` remote adopts it automatically instead of cloning a second copy.
+
+Git/archive acquisition is tunable through the host config:
+
+```yaml
+- id: dsh-agent-plugins-market
+  config:
+    git:
+      proxy: 'http://127.0.0.1:7890' # injected as git http/https proxy
+      insteadOf: { 'https://github.com/': 'https://mirror.example/https://github.com/' }
+      timeoutMs: 300000 # per git invocation (default 120000)
+      cloneRetry: true # one automatic retry (default)
+      fallbackTarball: false # retry a failed github.com clone as a codeload tarball download
+      allowHttpArchives: false # permit plain-http archive URLs (intranet mirrors)
+```
 
 ## Comparison with other DSH ↔ Claude Code bridges
 
@@ -135,6 +155,10 @@ Yes — through this plugin. It reads `.claude-plugin/marketplace.json` + per-pl
 
 Yes. Every valid `mcp.json` server of an enabled suite mounts a live `dsh-mcp-client` child, so MCP tools are callable by the DSH agent. `mcp.json` is validated strictly; `.mcp.json` is parsed leniently with placeholder support (`${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${NAME:-default}`).
 
+### How do MCP servers that require an environment token work?
+
+Declare the server's environment value as a reference, for example `"env": { "FOO_TOKEN": "${FOO_TOKEN}" }`. Before starting the child, the market resolves that reference through DSH credentials. Open the suite detail view to configure a writable credential through the Host credentials service; the value is write-only and is never stored in the suite or override JSON. A read-only launch-environment credential must be changed before restarting DSH. Missing references block the child start and show `needs-credentials` instead of silently starting an unusable server.
+
 ### What about Claude Code hooks?
 
 A suite's `hooks/hooks.json` is mounted through the official `@deepseek-ai/dsh-hooks-claude-code` bridge onto the harness interception points (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop). Only the mapped command-hook subset runs — see the bridge's README for the exact mapping.
@@ -159,14 +183,16 @@ Yes — MIT licensed, published on [npm](https://www.npmjs.com/package/dsh-agent
 
 - `ctx.skills` (dsh-skill) is required.
 - Optional peers: `@deepseek-ai/dsh-mcp-client` (MCP injection), `@deepseek-ai/dsh-hooks-claude-code` (hooks bridge); missing capabilities degrade gracefully.
+- The Host credentials service is optional: standard DSH profiles provide it for write-only token configuration and live remounts; without it, `${ENV_NAME}` falls back to the launch environment and requires a restart after changes.
 - Web GUI ≥ 0.1.0-rc.6.
 
 ## Security model
 
-- Git sources clone through `git` via `execFile` (no shell), depth 1, `--ff-only` pulls, 120s timeouts; local sources are read in place and never deleted.
+- Git sources clone through `git` via `execFile` (no shell), depth 1, shallow `fetch` + `reset` updates, configurable timeouts/proxy/mirrors with a low-speed guard; local sources are read in place and never deleted. Archive sources are HTTPS-only by default, capped at 256 MiB, extracted with path-traversal guards, and optionally pinned to a SHA-256 digest.
 - Mutating HTTP routes accept same-origin POSTs only; bodies capped at 64 KiB.
 - Portable paths must start with `./` and resolve inside the plugin root (symlink escapes rejected); `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` expand.
-- Third-party failures are always contained: broken manifests, invalid skills, escaping paths, unknown MCP transports, and mount failures are per-plugin diagnostics.
+- Third-party failures are always contained: broken manifests, invalid skills, escaping paths, unknown MCP transports, missing MCP credentials, and mount failures are per-plugin diagnostics.
+- MCP credential values are resolved in memory through the Host credentials service; status/detail projections redact sensitive fields and credential writes never persist literal values in suite state or overrides.
 - An error boundary wraps the whole market section and the detail modal: any preview render failure degrades to a notice instead of crashing the UI.
 
 ## Known limitations

package/README.zh.md

@@ -64,6 +64,7 @@ dsh plugin --profile <名字> add github:Sivan757/dsh-agent-plugins-market
 - **运行时注入**
   - **技能**：注册 `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 工具。
@@ -97,9 +98,28 @@ dsh plugin --profile <名字> add github:Sivan757/dsh-agent-plugins-market
       - { 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` 的源直接读取本地目录（实时反映工作树，移除源时不会删除目录）。
+`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 桥接项目的对比
 
@@ -135,6 +155,10 @@ dsh plugin --profile <名字> add dsh-agent-plugins-market
 
 可以。启用套件的每个合法 `mcp.json` server 都会挂载一个活的 `dsh-mcp-client` 子插件，DSH agent 可直接调用其工具。`mcp.json` 严格校验；`.mcp.json` 宽容解析并支持占位符（`${CLAUDE_PLUGIN_ROOT}`、`${CLAUDE_PLUGIN_DATA}`、`${NAME:-default}`）。
 
+### 只支持环境变量 token 的 MCP server 如何配置？
+
+在配置中把环境变量值写成引用，例如 `"env": { "FOO_TOKEN": "${FOO_TOKEN}" }`。子进程启动前，市场插件会通过 DSH credentials 解析该引用。打开套件详情即可通过 Host credentials service 配置可写凭据；token 只写入凭据存储，不写入套件或 override JSON，也不会回显。若凭据来自只读启动环境，需要在重启 DSH 前修改环境变量。引用缺失时会阻止子进程启动，并显示 `needs-credentials`，而不是静默启动一个不可用的 server。
+
 ### Claude Code hooks 呢？
 
 套件的 `hooks/hooks.json` 会通过官方 `@deepseek-ai/dsh-hooks-claude-code` 桥挂载到宿主拦截点（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStart、SubagentStop）。仅支持该桥映射的命令 hooks 子集，具体映射见桥的 README。
@@ -159,14 +183,16 @@ dsh plugin --profile <名字> add 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。
 
 ## 安全模型
 
-- git 源经 `execFile` 克隆（无 shell），`--depth 1`，`--ff-only`，120s 超时；本地源原地读取、移除不删除。
+- 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 transport、缺失 MCP 凭据、挂载失败均为逐套件诊断。
+- MCP 凭据值通过 Host credentials service 在内存中解析；状态和详情投影会脱敏敏感字段，凭据写入不会把字面 token 持久化到套件 state 或 override。
 - 错误边界包裹整个市场区与详情弹窗：任何预览渲染异常降级为提示，不会崩掉界面。
 
 ## 已知限制