@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.2

package/CONTRIBUTING.md

@@ -9,3 +9,21 @@ Skill installs must not overwrite existing directories. Local removal must reval
 The supported Harness cohort lives in `compatibility.json`. Keep all development packages on that exact cohort and document source/tag evidence before broadening support. Do not copy historical support ranges from another plugin.
 
 Commit regenerated `lib/` with source changes because Git installations consume it. Release metadata, compatibility, English/Chinese installation commands and release notes must agree. Follow `docs/RELEASE.md`; a passing test suite is not evidence that publication or real desktop acceptance happened.
+
+## CLI and local source installation
+
+For CLI users and local development, install a specific published version:
+
+```sh
+dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.2
+```
+
+Replace `desktop` with the target profile. To test a local source build:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm pack --pack-destination artifacts
+dsh plugin --profile desktop add ./artifacts/nanmicoder-dsh-skills-hub-0.0.2.tgz
+```
+
+Fully quit and reopen the target Harness instance after a CLI install. Advanced configuration is documented in [CONFIGURATION.md](./docs/CONFIGURATION.md).

package/README.md

@@ -3,118 +3,67 @@
 </p>
 
 <p align="center">
-  <img src="./assets/readme/hero-zh.png" width="100%" alt="Skills Hub：发现技能，装进你的工作流。3D 技能文档汇入蓝色收纳座的概念插画。">
+  <img src="./assets/readme/hero-zh.png" width="100%" alt="Skills Hub：发现技能，装进你的工作流。">
 </p>
 
 <p align="center">
   <strong>DeepSeek Harness 的技能市场与本机技能管理器</strong><br>
-  浏览 ClawHub 与 SkillHub，读懂 SKILL.md，再安装到你的 Harness。
+  浏览 ClawHub 与 SkillHub，找到适合你的技能。
 </p>
 
 <p align="center">
-  <a href="#快速开始">快速开始</a> · <a href="./docs/COMPATIBILITY.md">兼容性</a> · <a href="./docs/RELEASE.md">发布指南</a> · <a href="./LICENSE">MIT</a>
+  <a href="#快速开始">快速开始</a> · <a href="./docs/COMPATIBILITY.md">兼容性</a> · <a href="./LICENSE">MIT</a>
 </p>
 
-## 技能发现和本机管理，在同一个面板里
+## 在 Harness 里发现、安装和管理技能
 
-**Skills Hub** 把两个技能市场与本机用户技能放进 Harness 侧栏。无需在网站、下载目录和技能文件夹之间来回切换：搜索、查看文档、确认安装，再到「已安装技能」里统一管理。
+搜索 ClawHub 和 SkillHub 中的技能，阅读使用说明，再安装到 Harness。市场安装的技能和本机已有技能，都可以在「已安装技能」中查看和管理。
+
+当前版本：**0.0.2**。浏览过的列表、详情和文件预览默认缓存 60 分钟，退出桌面端后再次打开仍可复用。[更新说明](./release-notes/v0.0.2.md)
 
 <p align="center">
-  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub 在 DeepSeek Harness 中的实际界面：技能卡片、搜索与筛选、来源健康状态，以及已安装技能入口。">
+  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub 技能市场：搜索、筛选和技能卡片。">
 </p>
 
-*实际 Harness 0.2.0-rc.2 界面；市场内容随上游更新。顶部 3D Hero 为概念插画。*
-
-| 你要做的事 | Skills Hub 怎么帮你 |
+| 功能 | 说明 |
 | --- | --- |
-| **找一个技能** | 聚合 ClawHub 与 SkillHub，支持搜索和筛选；向下滚动自动加载更多。 |
-| **先看清，再安装** | 渲染 Markdown、表格和代码块，预览包内文件与上游安全报告；列表和详情都有骨架屏。 |
-| **整理已安装技能** | 搜索市场安装和本机用户技能，查看来源、实际路径与正文，再确认卸载。 |
+| **发现技能** | 聚合 ClawHub 与 SkillHub，支持搜索、筛选和滚动加载。 |
+| **安装前预览** | 阅读技能说明，查看文件内容和来源提供的安全报告。 |
+| **管理已安装技能** | 搜索本机技能，查看来源与安装位置，确认后卸载。 |
+| **本地缓存** | 缓存已浏览的分页、详情和文件预览，重启后继续使用。 |
 
 ## 快速开始
 
-**插件 `0.0.1` · 宿主 `0.2.0-rc.2`**。面向 DeepSeek Harness 0.2.0 桌面端产品线；其他宿主版本尚未验证。[查看验收范围 →](./docs/COMPATIBILITY.md)
-
-在运行桌面端的 profile 中安装：
-
-```sh
-dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.1
-```
+适用于 **DeepSeek Harness 0.2.0-rc.2**。[兼容版本](./docs/COMPATIBILITY.md)
 
-完全退出并重新打开 Harness，在侧栏点击 **技能市场**。使用其他 profile 时，把 `desktop` 替换成对应名称。
+打开 **DeepSeek Harness 桌面端 → 插件 → 添加插件**，粘贴以下任意一种内容：
 
-1. **浏览**：搜索关键词，或按来源、安全状态筛选。
-2. **预览**：打开技能，阅读概览和文件内容。
-3. **安装**：核对来源并确认；在「已安装技能」中查看、搜索或卸载。
+**GitHub 仓库地址（推荐）**
 
-> 包名必须带 `@nanmicoder/`。npm 上不带 scope 的 `dsh-skills-hub` 属于其他作者。
-
-<details>
-<summary><strong>从源码安装</strong></summary>
-
-需要 Node.js `^22.19.0 || >=24` 和 pnpm `10.33.0`。
-
-```sh
-pnpm install --frozen-lockfile
-pnpm pack --pack-destination artifacts
-dsh plugin --profile desktop add ./artifacts/nanmicoder-dsh-skills-hub-0.0.1.tgz
+```text
+https://github.com/NanmiCoder/dsh-skills-hub
 ```
 
-同样需要完全重启 Harness。构建产物随源码保留，打包前会重新构建和检查。
-
-</details>
+**或 npm 包名**
 
-## 已安装管理，路径清楚，操作明确
-
-列表覆盖配置的安装目录、`$DSH_HOME/skills` 与共享 agents 用户技能目录。目录式技能、平铺 Markdown 和符号链接都能识别；同名但不同路径的技能分别展示。
-
-- **确认后卸载**：展示将要删除的实际位置。
-- **链接只删链接**：保留它指向的原始技能文件。
-- **管理用户技能**：项目级和内置技能不在这个主机级列表中。
-
-安装过程不执行技能脚本，也不会覆盖已有目录。技能可能指示 agent 后续运行第三方代码；安全标签来自上游报告，不代表独立审计。请在安装前查看内容和发布者。
-
-<details>
-<summary><strong>配置与移除插件</strong></summary>
-
-默认配置即可使用。高级配置写在插件行中：
-
-```yaml
-- id: skills-hub
-  name: '@nanmicoder/dsh-skills-hub'
-  config:
-    allowUninstall: false
-    timeoutMs: 30000
+```text
+@nanmicoder/dsh-skills-hub@0.0.2
 ```
 
-| 配置项 | 默认值 | 说明 |
-| --- | --- | --- |
-| `skillsRoot` | `null` | 安装目录；默认是 Harness 用户技能目录。 |
-| `clawhubBaseUrl` | `https://clawhub.ai` | ClawHub API 地址。 |
-| `skillhubBaseUrl` | `https://api.skillhub.cn` | SkillHub API 地址。 |
-| `timeoutMs` | `15000` | 单次上游请求超时，单位毫秒。 |
-| `requestRetries` | `1` | 网络及服务器错误重试次数。 |
-| `allowUninstall` | `true` | 是否允许在面板卸载技能。 |
-| `pageSize` | `24` | 市场分页大小。 |
-
-移除插件本身：
+点击 **安装 → 立即启用**，然后从侧栏进入 **技能市场**。
 
-```sh
-dsh plugin --profile desktop remove @nanmicoder/dsh-skills-hub
-```
+## 使用
 
-这不会删除已安装的技能。文件扫描范围与接口见[实现约定](./docs/CONTRACT.md)。
+1. **查找**：输入关键词，或按来源和安全状态筛选。
+2. **预览**：打开技能，查看说明和文件内容。
+3. **安装与管理**：确认安装后，到「已安装技能」中查看或卸载。
 
-</details>
+技能由第三方作者提供，安装前请确认来源并阅读说明；安全报告供参考。
 
-## 开发与发布
+## 已安装技能
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check       # 类型、构建、回归测试与版本检查
-pnpm pack:check  # 另检查 npm 包内容及运行时依赖闭包
-```
+在「已安装技能」中，可以统一查看和卸载市场安装及本机已有的用户技能。项目内技能和 Harness 内置技能不在此列表中。
 
-[贡献指南](./CONTRIBUTING.md) · [维护规范](./AGENTS.md) · [兼容性与验收](./docs/COMPATIBILITY.md) · [0.0.1 发布流程](./docs/RELEASE.md)
+卸载前会显示具体位置，供你确认。若只想移除 Skills Hub 插件，在桌面端 **插件** 页面打开 **@nanmicoder/dsh-skills-hub**，点击 **卸载**；已安装的技能会保留。
 
-MIT 许可证。详见 [LICENSE](./LICENSE)。
+[反馈问题](https://github.com/NanmiCoder/dsh-skills-hub/issues) · [高级配置](./docs/CONFIGURATION.md) · [参与开发](./CONTRIBUTING.md) · [MIT 许可证](./LICENSE)

package/README_EN.md

@@ -3,118 +3,67 @@
 </p>
 
 <p align="center">
-  <img src="./assets/readme/hero-en.png" width="100%" alt="Skills Hub for DeepSeek Harness. Your skills. One place. A conceptual 3D library of skill documents in a blue dock.">
+  <img src="./assets/readme/hero-en.png" width="100%" alt="Skills Hub for DeepSeek Harness. Your skills. One place.">
 </p>
 
 <p align="center">
   <strong>A skill marketplace and local skill manager for DeepSeek Harness</strong><br>
-  Browse ClawHub and SkillHub, read SKILL.md, then install into Harness.
+  Browse ClawHub and SkillHub to find the skills you need.
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick start</a> · <a href="./docs/COMPATIBILITY.md">Compatibility</a> · <a href="./docs/RELEASE.md">Release guide</a> · <a href="./LICENSE">MIT</a>
+  <a href="#quick-start">Quick start</a> · <a href="./docs/COMPATIBILITY.md">Compatibility</a> · <a href="./LICENSE">MIT</a>
 </p>
 
-## Discovery and local management, in one panel
+## Discover, install and manage skills in Harness
 
-**Skills Hub** brings two marketplaces and your local user skills into the Harness sidebar. Search, inspect the instructions, confirm an installation, and manage it from the **Installed** view.
+Search ClawHub and SkillHub, read a skill’s instructions, and install it into Harness. Manage marketplace installations and existing local skills together in **Installed**.
+
+Current version: **0.0.2**. Browsed lists, details and file previews are cached locally for 60 minutes by default and remain available after restarting the desktop app. [Release notes](./release-notes/v0.0.2.md)
 
 <p align="center">
-  <img src="./assets/readme/marketplace.png" width="100%" alt="Actual Skills Hub panel in DeepSeek Harness: skill cards, search, filters, source health and the installed-skills entry.">
+  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub marketplace with search, filters and skill cards.">
 </p>
 
-*Actual Harness 0.2.0-rc.2 interface, shown in Chinese. Catalogue content changes upstream. The 3D hero is a conceptual illustration.*
-
-| What you want to do | How Skills Hub helps |
+| Feature | What it does |
 | --- | --- |
-| **Find a skill** | Search and filter ClawHub and SkillHub together. More results load as you scroll. |
-| **Inspect before installing** | Read Markdown, tables and code blocks; preview package files and upstream security reports. List and detail skeletons make loading visible. |
-| **Manage installed skills** | Search marketplace installations and local user skills, inspect their source, path and instructions, then confirm removal. |
+| **Discover skills** | Search and filter ClawHub and SkillHub together, with more results as you scroll. |
+| **Preview before installing** | Read instructions, inspect files and check security reports from the source. |
+| **Manage installed skills** | Search local skills, inspect their source and installation path, and confirm removal. |
+| **Local cache** | Reuse browsed pages, details and file previews across desktop restarts. |
 
 ## Quick start
 
-**Plugin `0.0.1` · Harness `0.2.0-rc.2`.** Targets the DeepSeek Harness 0.2.0 desktop release line; other host versions have not been validated. [See acceptance scope →](./docs/COMPATIBILITY.md)
-
-Install into your desktop profile:
-
-```sh
-dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.1
-```
+Supports **DeepSeek Harness 0.2.0-rc.2**. [Compatible versions](./docs/COMPATIBILITY.md)
 
-Fully quit and reopen Harness, then choose **Skills Hub** in the sidebar. Replace `desktop` with your profile name if needed.
+Open **DeepSeek Harness desktop → Plugins → Add plugin** and paste either of the following:
 
-1. **Browse**: search a keyword or filter by source and security status.
-2. **Preview**: open a skill and read its overview and files.
-3. **Install**: confirm its source; use **Installed** to inspect, search or remove it later.
+**GitHub repository URL (recommended)**
 
-> Keep the `@nanmicoder/` scope. The unscoped npm package `dsh-skills-hub` belongs to another author.
-
-<details>
-<summary><strong>Install from source</strong></summary>
-
-Requires Node.js `^22.19.0 || >=24` and pnpm `10.33.0`.
-
-```sh
-pnpm install --frozen-lockfile
-pnpm pack --pack-destination artifacts
-dsh plugin --profile desktop add ./artifacts/nanmicoder-dsh-skills-hub-0.0.1.tgz
+```text
+https://github.com/NanmiCoder/dsh-skills-hub
 ```
 
-Restart Harness afterward. Build artifacts are committed with source and rebuilt and checked before packing.
-
-</details>
+**Or the npm package name**
 
-## Local management with explicit paths
-
-The list covers the configured installation root, `$DSH_HOME/skills` and the shared agents user skills directory. It discovers directory-based skills, flat Markdown files and symlinks. Skills with the same name at different paths remain separate entries.
-
-- **Confirm removals** after checking the exact location.
-- **Unlink linked skills** without deleting their original files.
-- **Manage user skills**; project-specific and bundled skills are outside this host-level list.
-
-Installation does not execute skill scripts or overwrite existing directories. Skills may instruct an agent to run third-party code later. Security labels are upstream reports, not independent audits; review the contents and publisher before installing.
-
-<details>
-<summary><strong>Configuration and plugin removal</strong></summary>
-
-Defaults work out of the box. Advanced settings belong in the plugin row:
-
-```yaml
-- id: skills-hub
-  name: '@nanmicoder/dsh-skills-hub'
-  config:
-    allowUninstall: false
-    timeoutMs: 30000
+```text
+@nanmicoder/dsh-skills-hub@0.0.2
 ```
 
-| Key | Default | Meaning |
-| --- | --- | --- |
-| `skillsRoot` | `null` | Installation root; defaults to Harness's user skills directory. |
-| `clawhubBaseUrl` | `https://clawhub.ai` | ClawHub API origin. |
-| `skillhubBaseUrl` | `https://api.skillhub.cn` | SkillHub API origin. |
-| `timeoutMs` | `15000` | Per-request upstream timeout in milliseconds. |
-| `requestRetries` | `1` | Retries for network and server failures. |
-| `allowUninstall` | `true` | Allow skill removal from the panel. |
-| `pageSize` | `24` | Marketplace page size. |
-
-Remove the plugin itself:
+Click **Install → Enable now**, then open **Skills Hub** from the sidebar.
 
-```sh
-dsh plugin --profile desktop remove @nanmicoder/dsh-skills-hub
-```
+## Use
 
-This does not delete installed skills. See the [implementation contract](./docs/CONTRACT.md) for discovery scope and APIs.
+1. **Find**: enter a keyword or filter by source and security status.
+2. **Preview**: open a skill to read its instructions and inspect its files.
+3. **Install and manage**: confirm installation, then find or remove it in **Installed**.
 
-</details>
+Skills come from third-party authors. Check the source and instructions before installing; security reports are provided for reference.
 
-## Develop and release
+## Installed skills
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check       # types, build, regression tests and release metadata
-pnpm pack:check  # also inspect package contents and runtime import closure
-```
+Use **Installed** to view and remove marketplace installations and existing local user skills. Project-specific skills and skills bundled with Harness are not included.
 
-[Contributing](./CONTRIBUTING.md) · [Maintenance rules](./AGENTS.md) · [Compatibility and acceptance](./docs/COMPATIBILITY.md) · [0.0.1 release guide](./docs/RELEASE.md)
+The removal dialog shows the exact location for you to confirm. To remove Skills Hub itself, open **@nanmicoder/dsh-skills-hub** on the desktop **Plugins** page and click **Uninstall**. Your installed skills will remain.
 
-MIT. See [LICENSE](./LICENSE).
+[Report an issue](https://github.com/NanmiCoder/dsh-skills-hub/issues) · [Advanced configuration](./docs/CONFIGURATION.md) · [Contribute](./CONTRIBUTING.md) · [MIT license](./LICENSE)

package/README_ZH.md

@@ -2,4 +2,6 @@
 
 中文文档已成为仓库默认首页，请查看 [README.md](./README.md)。
 
+当前版本：**0.0.2**。[更新说明](./release-notes/v0.0.2.md)
+
 [English documentation](./README_EN.md)

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "pluginVersion": "0.0.1",
+  "pluginVersion": "0.0.2",
   "recommendedHost": "0.2.0-rc.2",
   "hostTag": "dsh-v0.2.0-rc.2",
   "hostCommit": "639ed015397290b3745d163aafe02ffee4aa3f84",

package/docs/COMPATIBILITY.md

@@ -29,3 +29,37 @@ Ego Lite drove the actual host UI. Slow fixture upstream responses made the load
 `pnpm pack:check` passed 44 tests without failures or skips, including live provider list/detail/file/install/uninstall, request-origin fencing, local removal policy, duplicate paths, symlink preservation, bounded file reads, Markdown rendering and controller concurrency. A final clean build and tarball closure check followed the visual/style fixes. npm publication dry-run and registry name/version preflight succeeded. No package was published, Git tag created, repository visibility changed or active user profile modified. Local npm authentication was absent (`npm whoami`: `ENEEDAUTH`); publication requires an authorized login or the documented CI secret.
 
 Local-only logs and screenshots are kept in the ignored `artifacts/` directory. CI covers Node 22.19 and 24; those CI jobs and a native desktop launch were not run in this local acceptance.
+
+## Installed-skill detail revision — 2026-09-30
+
+The local skill detail moved from the primitive's 380px modal to a full-panel page on the shared detail shell. Re-verified on the same cohort (`@deepseek-ai/dsh@0.2.0-rc.2` from npm, macOS arm64 / Node 26.7.0) with an isolated `DSH_HOME`/`DSH_AGENTS_HOME`, a disposable Web profile and a tarball install of this revision; the user's real profile was not touched.
+
+The run covered: the installed inventory (six rows), a search query surviving the round trip to the detail and back (with focus returned to the row that was opened), the market-installed skill's page (provenance badge, path line, 4-file inventory, rendered GFM table, collapsed YAML metadata, rail facts, "view in marketplace" opening the provider-backed page), a hand-placed skill (market rows absent rather than zero, no marketplace link), a symlink entry (linked badge), the Files tab with per-file preview switching, and removal from the detail page — confirmation showing the exact path, then row and directory both gone. Focus lands on the heading when the page opens; there is no horizontal overflow at 760px; light and dark themes were both inspected; the console stayed clean.
+
+One defect was found and fixed by this run: the uninstall confirmation was rendered only in the list branch, so the detail page's removal button did nothing.
+
+Deviation from the procedure above: Ego Lite's browser skill was not available to this session, so the drive used headless Chromium (Playwright 1.60.0) instead. Screenshots are in `artifacts/local-detail-acceptance/`; the results are recorded as observed, not inferred from fixture tests.
+
+## Markdown file preview revision — 2026-09-30
+
+The Files tab now renders markdown (frontmatter split into the structured metadata panel, body through the bundled GFM renderer) and keeps the exact bytes behind a preview/source switch. Verified with **ego-browser 0.5.1.13** against an isolated profile on the same host cohort, driving the real UI: an installed skill (`skillhub:anti-fraud`, 4 files) and a market skill (`clawhub:skill-vetter`, 2 files, live upstream).
+
+Recorded results — installed skill, Files tab: preview showed 1 table, 4 headings, 6 list items and 1 code block with the metadata panel and no literal `**`; the source view showed 67 line-number spans, the raw `name: anti-fraud` header and the literal `**先定级，再开口**`. Selecting another file returned to the rendered form. Market skill, Files tab: preview showed 12 headings, 15 list items, 5 code blocks and 1 table, again with no literal `**`; source showed 278 line-number spans and the raw `name: skill-vetter` header. Screenshots are in `artifacts/markdown-preview-verify/`.
+
+This run used the Ego Lite browser as the project procedure requires; the earlier Playwright deviation applied only to the revision above.
+
+## Provenance and look-ahead revision — 2026-09-30
+
+Cache answers now carry the moment they were read from upstream instead of being restamped with the current clock, a reader-requested refresh (`refresh=1`) reaches upstream, the panel prints the snapshot age, and the next catalogue page is fetched one screen before it is needed. Verified in an isolated profile on the same cohort, driving the real UI and the plugin's own endpoints.
+
+Recorded results: two identical list reads returned `fromCache: false` then `fromCache: true` **with the same `fetchedAt`**; `refresh=1` returned `fromCache: false` with a newer timestamp while `forcedRefreshes` and `upstreamRequests` advanced by one each; `refresh=maybe` was rejected with 400; the status bar rendered `ClawHub 正常 快照 刚刚`; a fresh page with no scrolling issued **0** cursor requests; scrolling to within 708px of the container's end (sentinel still 639px below the fold) issued cursor requests immediately, which is the look-ahead — measured with a viewport-rooted observer reporting "not intersecting" for the same sentinel, confirming the container root is required. Screenshots are in `artifacts/p0-p1-verify/`.
+
+## Persistent cache regression — 2026-09-30
+
+The previous cache lived only in the host process's `Map`; the provenance revision above did not persist it across exits. The host now stores snapshots under its Harness home and defaults to a one-hour TTL (`cacheTtlMinutes` can change it).
+
+Automated regression uses the compiled plugin in separate Node HTTP host processes with a minimal Cordis context, isolated `DSH_HOME`/`DSH_AGENTS_HOME` and fixture upstreams. After reading three cursor pages, a search, both providers' details and both file previews, the test kills the host with `SIGKILL` and boots a new process against the same temporary home. Every repeated read is served without additional upstream requests; original `fetchedAt` values survive, and a skill installed while the host was stopped is annotated from the new filesystem scan. Further restarts verify refreshed snapshots, expiry, stale list/detail fallback during upstream failure, and isolation when provider URLs change. Unit coverage includes corrupt records, failed disk writes, concurrent atomic publication, count limits and a shorter configured TTL. Install-time manifest reads reject upstream failure even when a snapshot exists.
+
+Adversarial review also covered the actual HTTP install entry point (a withdrawn manifest is rejected despite a fresh disk snapshot), first-response installation annotations without an `/installed` warmup, browser revalidation and per-page provenance, configuration changes during asynchronous cache reads and multi-step installation, snapshot integrity, oversized replacement invalidation, and abandoned temporary writes. Regression tests cover each behavior.
+
+The automated evidence above is process-restart coverage rather than a full native acceptance run. Separately, the user authorized installation into the active desktop: a locally packed build was installed using the desktop's bundled package manager while it was stopped, then DeepSeek Harness **0.2.0-rc.2** was relaunched. The actual market loaded 24 entries from each source and wrote two list snapshots with a 60-minute lifetime. This smoke check does not claim a native restart-after-warm acceptance of every cached path. The supported Harness cohort remains unchanged.

package/docs/CONFIGURATION.md

@@ -0,0 +1,38 @@
+# 高级配置
+
+日常使用可直接在桌面端安装和管理插件，无需修改配置。以下内容供需要自定义安装目录、数据源或移除权限的用户参考。
+
+配置写在插件行中：
+
+```yaml
+- id: skills-hub
+  name: '@nanmicoder/dsh-skills-hub'
+  config:
+    allowUninstall: false
+    timeoutMs: 30000
+```
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `skillsRoot` | `null` | 安装目录；默认是 Harness 用户技能目录。 |
+| `clawhubBaseUrl` | `https://clawhub.ai` | ClawHub API 地址。 |
+| `skillhubBaseUrl` | `https://api.skillhub.cn` | SkillHub API 地址。 |
+| `timeoutMs` | `15000` | 单次上游请求超时，单位毫秒。 |
+| `requestRetries` | `1` | 网络及服务器错误重试次数。 |
+| `allowUninstall` | `true` | 是否允许在面板卸载技能。 |
+| `pageSize` | `24` | 市场分页大小。 |
+| `cacheTtlMinutes` | `60` | 列表分页、搜索、技能详情及文件预览的本地缓存有效期，单位分钟，范围 1–1440。 |
+
+## 市场缓存
+
+浏览过的市场分页、详情及文件预览会自动保存到 `$DSH_HOME/cache/skills-hub/v1`（未设置 `DSH_HOME` 时为 `~/.dsh/cache/skills-hub/v1`），退出并重启 Harness 后仍可复用。默认从上游获取成功时起保留 1 小时，再次浏览不会延长有效期；超过有效期会重新请求上游。面板中的列表或详情手动刷新会立即重新拉取并替换对应快照；文件预览按自身有效期读取。重开详情时可先显示上一份快照，随后向本地 Host 核对有效期和当前安装状态，缓存有效时不会请求上游。
+
+缓存按数据源地址、查询条件、分页游标和分页大小区分，不受技能安装目录影响。安装状态仍根据当前本地文件计算。安装技能时会重新读取上游清单，失败时不会使用缓存清单继续安装。
+
+磁盘最多保留 500 条快照、64 MiB，旧快照优先清理。过期的列表和详情仅在上游失败时用于浏览兜底，最多保留 7 天；缓存损坏或无法写入时，市场仍可通过内存缓存和上游请求工作。
+
+## 技能发现范围
+
+列表覆盖配置的安装目录、`$DSH_HOME/skills` 与共享 agents 用户技能目录。支持目录式技能、平铺 Markdown 和符号链接；同名但不同路径的技能分别展示。删除符号链接时仅移除链接，保留目标文件。项目级与内置技能不在此列表中。
+
+接口和路径校验规则见[实现约定](./CONTRACT.md)。

package/docs/CONTRACT.md

@@ -1,10 +1,10 @@
-# Skills Hub 0.0.1 implementation contract
+# Skills Hub 0.0.2 implementation contract
 
 This document describes the shipped code, not a migration plan. The TypeScript models in `src/market/types.ts`, `src/skills/installed.ts` and `src/client/api.ts` define the detailed wire shapes. Update this document with API changes.
 
 ## 1. Package and host
 
-The package is `@nanmicoder/dsh-skills-hub`, version `0.0.1`. Its supported host package cohort is exactly `0.2.0-rc.2`; the desktop release line is 0.2.0. The exact upstream tag and commit are recorded in `compatibility.json` and [COMPATIBILITY.md](COMPATIBILITY.md).
+The package is `@nanmicoder/dsh-skills-hub`, version `0.0.2`. Its supported host package cohort is exactly `0.2.0-rc.2`; the desktop release line is 0.2.0. The exact upstream tag and commit are recorded in `compatibility.json` and [COMPATIBILITY.md](COMPATIBILITY.md).
 
 `cordis.patch.yml` inserts one row (`id: skills-hub`) named after the scoped package. `lib/index.js` is the host entry. `lib/client.js` is the browser factory registered with `window.__ModuleLoader__.load` under that same package name. The plugin adds a global sidebar panel and does not replace built-in components or require an agent session.
 
@@ -14,7 +14,7 @@ The host performs provider requests and filesystem operations. It binds the avai
 
 The browser only calls same-origin `/api/skills-hub/*` endpoints, with same-origin credentials. Shared market imports in browser code are type-only. Browser runtime externals must belong to the Harness platform module table; host services and Node modules must not enter the browser bundle.
 
-`react-markdown` and `remark-gfm` are development dependencies compiled into the browser artifact. Rendering supports headings, tables, task lists and fenced code without relying on an optional host renderer. Raw HTML is skipped; dangerous URL protocols are filtered by the renderer, and external links use `noopener noreferrer`.
+`react-markdown` and `remark-gfm` are development dependencies compiled into the browser artifact. Rendering supports headings, tables, task lists and fenced code without relying on an optional host renderer. Raw HTML is skipped; dangerous URL protocols are filtered by the renderer, and external links use `noopener noreferrer`. `src/client/skill-markdown.ts` splits a document's YAML frontmatter from its body with a small subset parser compiled into the same bundle (scalars, inline/block sequences, `|`/`>` block scalars, one level of nested mapping kept as raw YAML): no YAML dependency enters the browser program, and the metadata block is rendered as structure instead of reaching the renderer, where its closing `---` would turn the whole block into a setext heading.
 
 The bundler explicitly selects the browser platform even though its output is a CommonJS factory. Both build-time import checks and manifest checks guard this boundary. CSS Modules use `--dsw-*` theme tokens and relative source IDs for portable output.
 
@@ -47,6 +47,8 @@ An `InstalledSkillRecord` has:
 
 Duplicate names/market IDs in separate roots remain separate rows with separate keys. Local endpoints accept keys, never arbitrary client-supplied paths. They freshly scan the allowed roots to resolve the entry. Removal renames the selected entry to a hidden temporary sibling before deletion; removing a link preserves its target. A flat file removal preserves its sibling files.
 
+A local detail read resolves the entry, reads its `SKILL.md`/flat document (2 MiB bound) and inventories the entry's own files: relative POSIX paths with size and detected language, dot-entries (including the provenance sidecar) excluded, at most 500 rows, symlinked files never followed. The document's frontmatter is returned verbatim as YAML text — the structured panel of a market detail is fed by upstream JSON that a hand-written skill does not have. A file read takes the same key plus a relative path: the path is validated (no absolute paths, no `..`, no empty segment), resolved inside the entry's real path, and rejected when a symlink would leave it, so the endpoint is never an arbitrary-file reader. A flat entry exposes only itself, never its siblings in the same root. Truncation at 300 KiB is reported, not thrown.
+
 Market installation uses staging and atomic publication, rejects directory conflicts, validates file paths and hashes when supplied, and writes a `.skills-hub.json` sidecar. The market-ID uninstall endpoint requires valid matching provenance; the explicit local-management endpoint can remove unmanaged entries after the UI confirmation. Both honor `allowUninstall`.
 
 After mutations the plugin refreshes its installed lookup. Harness's filesystem watcher handles skill catalog invalidation; the plugin does not forge filesystem observation events. Reading the catalog is best-effort and does not replace that watcher.
@@ -59,7 +61,11 @@ Providers normalize ClawHub and SkillHub into `NormalizedSkill`. A market ID is
 
 Source status is `ok`, `degraded`, `failed` or `cached`, with optional fetch time/cache/error metadata. Provider failures remain visible independently; an unavailable source must not silently look like an empty marketplace.
 
-Current market limits are 5 MiB per file, 20 MiB total and 200 files per install. Market previews truncate after 300 KiB. ClawHub search results are capped at 50 because that search endpoint does not paginate. Local installed Markdown previews are limited to 2 MiB and reject oversized content.
+Upstream list pages (including each cursor), search pages, normalized details with their file inventory, and file previews are cached in memory and persisted under `$DSH_HOME/cache/skills-hub/v1` (default `~/.dsh/cache/skills-hub/v1`). Writes use a temporary file and atomic rename, and complete before the response returns. Restarted hosts read snapshots lazily, checking a versioned SHA-256 digest of the key, timestamps and payload before using them. Keys include the source's configured base URL as well as all payload-affecting request parameters; each operation captures its provider configuration and cache instance so a profile reload cannot mix them. Local install annotations are computed after reading the cache, and HTTP reads wait for the initial local inventory scan.
+
+All snapshots default to a 60-minute TTL, configurable through `cacheTtlMinutes` (1–1440). `storedAt` and `expiresAt` survive restart; a hit does not extend them, and reducing the configured TTL also limits existing snapshots. Browser display copies revalidate through the Host on each detail opening or file selection; each list card retains its own page's provenance for installation confirmation. Expired list/detail snapshots may be served on upstream errors for at most seven days. Actual install-time manifest reads bypass both fresh cache hits and stale fallback. Persisted snapshots are capped at 500 entries / 64 MiB, evict older writes first, and reject entries larger than 5 MiB while invalidating any older snapshot at that key. Writes also reclaim abandoned plugin temporary files older than one hour, leaving recent files alone for concurrent publishers. Unsupported/corrupt records or filesystem failures fall back to ordinary upstream reads and memory storage; the host logs a filesystem/parse failure once per activation.
+
+Current market limits are 5 MiB per file, 20 MiB total and 200 files per install. Market previews truncate after 300 KiB. ClawHub search results are capped at 50 because that search endpoint does not paginate. Local installed Markdown previews are limited to 2 MiB and reject oversized content; a single local file preview truncates after 300 KiB, matching the market preview policy.
 
 ## 5. HTTP and browser behavior
 
@@ -76,15 +82,19 @@ All paths below are relative to `/api/skills-hub`.
 | Method | Path / input | Success body |
 | --- | --- | --- |
 | GET | `/status` | `{ sources }` keyed by market source. |
-| GET | `/skills?q=&source=&security=&installed=&cursor=&limit=` | `{ items, nextCursor, sources }`. |
-| GET | `/skills/:source/:slug` | `{ skill, sourceStatus }`. |
+| GET | `/stats` | `{ stats }` cache counters: `hits`, `misses`, `staleServed`, `upstreamRequests`, `forcedRefreshes`. |
+| GET | `/skills?q=&source=&security=&installed=&cursor=&limit=&refresh=` | `{ items, nextCursor, sources }`. |
+| GET | `/skills/:source/:slug?refresh=` | `{ skill, sourceStatus }`. |
 | GET | `/skills/:source/:slug/file?path=…` | `{ file }`. |
 | POST | `/install`, JSON `{ id }` | `{ ok: true, installedPath, skill }`. |
 | POST | `/uninstall`, JSON `{ id }` | `{ ok: true, removedPath, skill }`; market-managed installation only. |
 | GET | `/installed` | `{ items: InstalledSkillRecord[] }`; no provider request. |
-| GET | `/installed/detail?key=…` | `{ item, markdown }`; reads the selected local copy. |
+| GET | `/installed/detail?key=…` | `{ item, markdown, frontmatter, files }`; reads the selected local copy, its raw YAML header and its own file inventory. |
+| GET | `/installed/file?key=…&path=…` | `{ file }` with `content`, `size`, `language`, `truncated`; the path must resolve inside the selected entry. |
 | POST | `/installed/uninstall`, JSON `{ key }` | `{ ok: true, removedPath, item }`; exact discovered entry. |
 
+`refresh` is `1`/`true` or `0`/`false` (absent means false); any other value is a `BAD_REQUEST`, because a refresh the Host cannot honour would let the panel present a cached answer as a fresh one. A refresh skips fresh cache entries for that request and rewrites them with what upstream returned.
+
 List `source` is `all`, `clawhub` or `skillhub`. `security` is `all`, `verified`, `benign`, `unknown` or `flagged`. `installed` is `all`, `installed` or `installable`; this filters the remote catalog and is distinct from the independent Installed view. `limit` is 1–100, defaulting to configured `pageSize`. Cursors are opaque and `null` means exhausted.
 
 ### 5.3 Interaction contract
@@ -93,6 +103,14 @@ The marketplace shows skeleton cards on initial loading and a detail skeleton im
 
 Search/filter changes cancel superseded requests, reset pagination and reject stale responses. Installed management has its own loading, empty, error, search and refresh states. Its local detail reads the exact selected entry, and removal requires a confirmation showing its path; symlink removals explain that the target is preserved. Successful mutations update the displayed list and installed state. Buttons expose disabled/pending state during mutations.
 
+Both detail pages are full-panel views built on one shell (`SkillDetailShell`): the list is replaced, focus moves to the heading, and a back control returns to it. The market page keeps its tab and selected file in `MarketState`; the local page keeps them in its own state and never unmounts the inventory list, so the query and rows survive the round trip. The local page shows only what the filesystem proves — path, provenance, size, installed time, layout, the rendered SKILL.md and its own files — and omits market-only rows (author, downloads, security reports) rather than showing zeros. A skill with valid market provenance also offers "view in marketplace", which switches to the market section and opens its provider-backed page: upstream facts stay upstream, and the local page stays readable offline.
+
+Provenance is part of every answer. `sourceStatus.fetchedAt` is the moment the payload was *read from upstream* — a cache hit keeps the original timestamp instead of restamping it with the current clock — and `fromCache` says whether the answer came from a stored copy. The panel prints that age next to each source and, when a detail is a snapshot, offers the one action that reaches upstream (`refresh=1`). Installing never relies on a snapshot: the manifest is re-read with `refresh` semantics before the files are fetched and hash-verified, so a cached security verdict or file list can never authorize an install.
+
+The catalogue fetches the next page about one screen before the reader reaches the end of the list, and only after the reader has scrolled at least once: opening the panel and leaving must not cost a page nobody looked at. The request count is unchanged — the same page is fetched either way — it simply happens while the reader is still scrolling, so arriving at the sentinel finds data instead of starting a request. The look-ahead observer must be rooted at the list's own scroll container: the catalogue scrolls inside the host dock, and a viewport-rooted observer is clipped by that dock, which makes `rootMargin` a no-op there.
+
+Inside the Files tab, a markdown document opens rendered — frontmatter as structured metadata, body through the same GFM renderer — because SKILL.md is prose meant to be read. Installing remains a trust decision, so a preview/source switch keeps the exact bytes (line numbers, and a copy button pointed at what is on disk) one click away; selecting another file returns to the rendered form. Every other language is source-only, since a toggle there would promise a rendering that does not exist.
+
 ## 6. Configuration
 
 `src/config.ts` is the configuration source of truth. Defaults:

package/docs/RELEASE.md

@@ -1,8 +1,8 @@
-# Release 0.0.1
+# Release 0.0.2
 
-Package: `@nanmicoder/dsh-skills-hub`. Repository: `NanmiCoder/dsh-skills-hub`. Tag: `v0.0.1`. npm channel: `latest`. This is an initial plugin release, independent of the host's `0.2.0-rc.2` version.
+Package: `@nanmicoder/dsh-skills-hub`. Repository: `NanmiCoder/dsh-skills-hub`. Tag: `v0.0.2`. npm channel: `latest`. This plugin release is independent of the host's `0.2.0-rc.2` version and retains that exact compatibility cohort.
 
-## Before making the repository public
+## Before publication
 
 1. Run `pnpm install --frozen-lockfile` and `pnpm pack:check` on the intended release commit.
 2. Perform the exact-host acceptance described in [COMPATIBILITY.md](COMPATIBILITY.md), including a browser mount and real install/uninstall in a temporary skills root. Record the host tag, plugin commit, commands and results; fixture tests alone do not prove host acceptance.
@@ -11,7 +11,7 @@ Package: `@nanmicoder/dsh-skills-hub`. Repository: `NanmiCoder/dsh-skills-hub`.
 
 ## GitHub Actions publication
 
-Publication runs online in `.github/workflows/release.yml`, matching the AgentTeams release model. Push `v0.0.1` to trigger it, or dispatch the workflow with an explicit version. Both Node 22.19 and 24 must pass validation. The Node 24 job uploads the built tarball and SHA-256 checksum; the publication job verifies and publishes that exact artifact using npm 11.19.0. It does not rebuild during publication. A GitHub Release is published only after npm succeeds.
+Publication runs online in `.github/workflows/release.yml`, matching the AgentTeams release model. Push `v0.0.2` to trigger it, or dispatch the workflow with an explicit version. Both Node 22.19 and 24 must pass validation. The Node 24 job uploads the built tarball and SHA-256 checksum; the publication job verifies and publishes that exact artifact using npm 11.19.0. It does not rebuild during publication. A GitHub Release is published only after npm succeeds.
 
 Configure npm Trusted Publishing for GitHub owner `NanmiCoder`, repository `dsh-skills-hub`, workflow `release.yml`, environment `npm`, allowing direct publication. OIDC uses `id-token: write`; routine releases need no local npm login and no stored npm token. The existing AgentTeams trust binding is package-specific and does not authorize this new package.
 
@@ -21,4 +21,4 @@ Before tagging, commit all source and generated artifacts, confirm the version a
 
 ## After publication / recovery
 
-Install `@nanmicoder/dsh-skills-hub@0.0.1` into an isolated profile and repeat the smoke flow. Compare the downloaded package and expected version before announcing availability. If a release is faulty, publish a new fixed version or deprecate the faulty version with a clear message; do not rewrite published Git tags or assume deleting a GitHub Release retracts npm. Preserve user skills when removing or replacing the plugin.
+Install `@nanmicoder/dsh-skills-hub@0.0.2` into an isolated profile and repeat the smoke flow. Compare the downloaded package and expected version before announcing availability. If a release is faulty, publish a new fixed version or deprecate the faulty version with a clear message; do not rewrite published Git tags or assume deleting a GitHub Release retracts npm. Preserve user skills when removing or replacing the plugin.