dsh-agent-plugins-market 0.4.6 → 0.5.1

package/README.md

@@ -53,7 +53,7 @@ dsh plugin --profile <name> add github:Sivan757/dsh-agent-plugins-market
 }
 ```
 
-The built entry point (`lib/`, `client/`) is committed to the repository, so GitHub installs work without a `prepare` step.
+Build artifacts (`lib/`, `client/`) are not committed; npm publishes them via `prepack`, and GitHub installs build them automatically through the `prepare` script (requires Node + pnpm toolchain on the installing machine).
 
 </details>
 
@@ -68,18 +68,19 @@ The built entry point (`lib/`, `client/`) is committed to the repository, so Git
   - **Commands / subagents** — `commands/*.md` register as dsh slash commands; `agents/*.md` register as `agent-<name>` skills.
   - **Context** — the enabled-plugin catalog (user + project sections) is injected at session start; the `agent_plugins` tool queries it.
 - **Runtime discovery** — installed plugins are discovered from configured source ids under `~/.dsh/agent-plugins/.sources/<sourceId>/` (user dimension) and `<project>/.dsh/agent-plugins/.sources/<sourceId>/` (project dimension). Stale unmanaged user checkouts are ignored, while project checkouts remain state-authorized. Local sources read the working tree directly, including uncommitted changes.
+- **Native project layouts (zero-copy migration)** — a repository's own `.claude/` and `.agents/` directories (skills, agents) are discovered in place as read-only `project-native` suites: no install, no copying, no state file. Repositories migrating from Claude Code or agent-plugins.org conventions work as-is; a project skill shadows an installed suite skill of the same name (project wins).
 
 ## Supported plugin layouts
 
-| Layout | Manifest | Notes |
-| --- | --- | --- |
-| agent-plugins.org v1 | `plugin.json` | vendored 1.0.0 JSON Schema validation + spec §4 path rules |
-| Claude Code market | `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json` | marketplace `plugins[].source` relative paths |
-| Universal | `.plugin/plugin.json` | multi-client repos (e.g. vercel-plugin) |
-| Cursor | `.cursor-plugin/plugin.json` | declared skills paths |
-| Kimi | `.kimi-plugin/plugin.json` | inline mcpServers |
-| Codex | `.codex-plugin/plugin.json` | — |
-| Skill collection (manifest-less) | none (synthetic) | flat `SKILL.md` directory collections |
+| Layout                           | Manifest                                                         | Notes                                                      |
+| -------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
+| agent-plugins.org v1             | `plugin.json`                                                    | vendored 1.0.0 JSON Schema validation + spec §4 path rules |
+| Claude Code market               | `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json` | marketplace `plugins[].source` relative paths              |
+| Universal                        | `.plugin/plugin.json`                                            | multi-client repos (e.g. vercel-plugin)                    |
+| Cursor                           | `.cursor-plugin/plugin.json`                                     | declared skills paths                                      |
+| Kimi                             | `.kimi-plugin/plugin.json`                                       | inline mcpServers                                          |
+| Codex                            | `.codex-plugin/plugin.json`                                      | —                                                          |
+| Skill collection (manifest-less) | none (synthetic)                                                 | flat `SKILL.md` directory collections                      |
 
 One repo may carry several dialects at once (vercel/vercel-plugin ships all of them); the suite identity comes from the highest-precedence manifest while surfaces are scanned from the directories. `mcp.json` is validated strictly against the agent-plugins.org schema; `.mcp.json` is parsed leniently — top-level server-map shorthand, `type: http` / `local` / omitted `type` (stdio by `command`) normalization, `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}` / `${NAME:-default}` placeholders, and unknown transports are tolerated per server. The marketplace manifest is authoritative for the suite set; manifest-less marketplace entries that carry skills and manifest-bearing container dirs not listed there are supplemented. Remote URL entries show as "remote reference" cards (metadata + source URL, not directly installable; add the repo as a source to install).
 
@@ -171,8 +172,9 @@ Yes — MIT licensed, published on [npm](https://www.npmjs.com/package/dsh-agent
 ## Known limitations
 
 - Project-dimension MCP servers are not mounted (dsh has no per-session tool scope); the project dimension covers skills and context.
-- Skill discovery has no file watcher: catalog changes apply after a manager action or a host restart.
+- Skill discovery has no file watcher: catalog changes apply after a manager action or a host restart (project-dimension snapshots are cached for 5 seconds on the skill-list hot path).
 - Claude Code hooks support the mapped bridge subset; LSP is counted and previewed but not executed.
+- Native project layouts (`.claude/`, `.agents/`) inject skills and subagents; their `commands/*.md` are not registered as slash commands because the harness command registry is process-scoped, not session-cwd-scoped.
 
 ## Development
 
@@ -180,10 +182,16 @@ Yes — MIT licensed, published on [npm](https://www.npmjs.com/package/dsh-agent
 pnpm install
 pnpm run test        # vitest over fixture suites + multi-dialect parsing
 pnpm run typecheck
+pnpm run lint        # ESLint over the refactored source and tests
+pnpm run format:check
+pnpm run check:architecture
+pnpm run check:refactor
 pnpm run build       # tsc host + tsdown client + module-loader banner
 pnpm pack
 ```
 
+The internal modularization decision and staged migration are documented in [`docs/design/engineering-refactor-plan.md`](docs/design/engineering-refactor-plan.md) and [`docs/adr/0001-catalog-centered-modular-refactor.md`](docs/adr/0001-catalog-centered-modular-refactor.md).
+
 The docs website lives in [`docs-site/`](docs-site/) (Astro, deployed to GitHub Pages).
 
 ## Vendored assets

package/README.zh.md

@@ -53,7 +53,7 @@ dsh plugin --profile <名字> add github:Sivan757/dsh-agent-plugins-market
 }
 ```
 
-构建产物（`lib/`、`client/`）已提交到仓库，GitHub 安装无需 `prepare` 步骤。
+构建产物（`lib/`、`client/`）不再提交进仓库；npm 通过 `prepack` 发布，GitHub 安装时由 `prepare` 脚本自动构建（安装机需具备 Node + pnpm 工具链）。
 
 </details>
 
@@ -68,18 +68,19 @@ dsh plugin --profile <名字> add github:Sivan757/dsh-agent-plugins-market
   - **命令 / 子代理**：`commands/*.md` 注册为 dsh 斜杠命令；`agents/*.md` 注册为 `agent-<name>` 技能；
   - **上下文**：会话启动注入启用套件清单（用户级 + 项目级），`agent_plugins` 工具可查询。
 - **运行时发现**——已安装套件只从已配置的源 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` 目录集合 |
+| 布局                 | 清单文件                                                              | 说明                                           |
+| -------------------- | --------------------------------------------------------------------- | ---------------------------------------------- |
+| 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，不可直接安装，可添加对应仓库为源后安装）。
 
@@ -171,8 +172,9 @@ dsh plugin --profile <名字> add dsh-agent-plugins-market
 ## 已知限制
 
 - 项目维度 MCP server 不挂载（dsh 无按会话的 tool scope）；项目维度覆盖技能 + 上下文。
-- 技能发现无文件监听：目录变化在管理动作或重启后生效。
+- 技能发现无文件监听：目录变化在管理动作或重启后生效（项目维度快照在技能枚举热路径上有 5 秒缓存）。
 - Claude Code hooks 仅支持 bridge 映射的子集；LSP 只计数与预览，不执行。
+- 项目原生布局（`.claude/`、`.agents/`）注入技能与子代理；其中 `commands/*.md` 不注册为斜杠命令——宿主命令注册表是进程级作用域，无法按会话 cwd 隔离。
 
 ## 开发
 
@@ -180,10 +182,16 @@ dsh plugin --profile <名字> add dsh-agent-plugins-market
 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
 ```
 
+内部模块化决策与分阶段迁移计划见 [`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）。
 
 ## Vendored 资产