@klarkxy/dsh-blueprint 0.1.0-alpha.2 → 0.1.0-alpha.3

package/ACCEPTANCE.md

@@ -1,33 +1,76 @@
 # Acceptance record
 
-Date: 2026-09-27. Status: implementation/source preview; native end-to-end acceptance is pending.
+Verified on 2026-09-28 with Windows, Node.js 24.16.0 and official DSH 0.1.7-rc.2.
+This record describes the current plugin-only implementation.
 
-## Executed in this development environment
+## Scope
 
-Node.js 22.16.0, Linux, isolated temporary directories.
+Blueprint shares exact package identities and ordered bundles. It has one Import /
+Export menu. There is no settings document, settings RPC mode, field selection,
+sharing-policy schema, Settings/Loader service dependency or settings mutation.
+The validator accepts only the current blueprint schema; no migration or legacy
+compatibility path is maintained. Reusable defaults belong in native composition
+plugins and remain subject to the host's configuration-layer rules.
 
-- `npm test`: 84 passed, 0 failed, 0 skipped. Pure-core cases cover strict JSON/J/Z parsing, Unicode and size limits, default inclusion and exclusions, preserved order, two-stage imports, native revision fences, one-use plans, partial failure reporting, connection-target guarding, schema secrets including intersections and new dictionary entries, interruption and final-order verification.
-- Adapter contract fixtures exercise the actual `official.mjs` and `index.mjs` implementations against a synthetic Context with the inspected upstream signatures. They verify redacted native reads, page-independent scope, package/row ownership, malformed policy handling, native install/mutate/cancel arguments, sanitized results and explicit confirmation. They do not load a real DSH host.
-- A VM client-registration test executes `client.js` with a synthetic module loader and React facade. It verifies the official manager page and contextual share action registrations. This is not a browser visual or interaction test.
-- `npm run build`: JavaScript syntax checks of all six executable source files.
-- Distribution contents checked with `npm pack --dry-run` and a real local `npm pack`; tests and development files are not shipped. The packed core can be imported and its codec round-tripped without third-party dependencies.
+Import is additive: the entire existing active sequence remains unchanged, and
+only requested inactive bundles are appended in blueprint preference order.
+Different incoming order alone is not a conflict. Import never disables bundles.
 
-The alpha.2 scope revision adds ten tests: custom-only storage is not read, plugin-list sharing still works, unsupported imported settings block before writes, stale selections fail, author policy cannot widen native access, inactive/mismatched entries are excluded, browser page metadata is rejected, native defaults remain shareable, and the client does not enumerate configuration slots. Existing presentation tests now verify native support regardless of page slots or `autoGenerate`.
+Codes use only `DSHBP2:<payload>` with raw DEFLATE and Base64url. There is no
+encoding selector or JSON import/download. Export returns only the code. Blueprint
+metadata contains a name and optional description, without its own revision number.
 
-No real `~/.dsh`, model provider, credential store or network installation was touched.
+## Completed checks
 
-## GitHub Actions verification
+- All 97 package tests pass. Coverage includes strict code/JSON parsing, exact
+  package identity, ordered export, additive prefix preservation, repeated-import
+  idempotence, activation without reinstall, protocol vectors, package conflicts, bounded one-use plans,
+  stale-state rejection, cancellation, partial failure, native installation calls,
+  authenticated RPC, Creator guidance, discovery tools and client registration.
+- Regression tests cover 1 MiB malformed interior whitespace and preserve outer
+  ASCII whitespace / raw byte limits. A 64 KB case that previously took about 2.9 s
+  now rejects in 0.19 ms; a 1 MiB case rejects in 0.52 ms in isolated Node 24.
+- Request abort and engine disposal are checked at the initial snapshot, native
+  inspection and final snapshot boundaries. Late replies cannot save plans/results.
+  Actual HTTP disconnect and plugin unload tests abort the native inspect signal.
+- Adapter tests run with Settings, Loader, pluginPackages, credential and storage
+  accessors that throw if read. Catalog, export and preview still work. Settings
+  operation requests, disable operations and non-blueprint input fail without mutation.
+- The package syntax build passes. A real npm tarball was extracted and loaded by
+  an isolated official host. PROTOCOL.md, the JSON example and its single code vector are packed;
+  the retired settings-scope document is not packaged.
+- Browser interaction with that packed plugin verified export/copy and import of
+  a different preference order without any mutation, then a blueprint requesting
+  an already installed inactive bundle. Exactly one enable operation appended it;
+  existing order, dependencies and the user patch were preserved on readback.
+- The packed page exports only a share code with no blueprint revision or JSON
+  download. A malformed 64 KB code is rejected through the actual isolated host.
+- Reimport, an install-only request for active bundles, and the shipped single-format
+  empty-document code produced no-op previews. Desktop and 390px screenshots
+  were inspected; mobile content did not overflow, Escape restored menu focus,
+  and there were no browser exceptions.
+- Independent read-only review found the engine/native adapter and protocol
+  consistent with the accepted additive rule before the single-format simplification.
+  A fresh independent review of the current fixes found no surviving bypass or
+  regression, reran all 97 tests, and checked non-ASCII whitespace rejection.
+  The parent also verified the packed browser flow.
 
-Implementation commit: `420336f78444ea7e02db190e2c2676c848a78171`.
+Local evidence: `.scratch/blueprint-fix/`
+(tarball, browser report and screenshots). These are not shipped assets.
 
-- [CI #42, push](https://github.com/klarkxy/dsh-plugins/actions/runs/36299619992) completed successfully. Its complete job log was inspected: Node.js 24.21.0, pnpm 10.29.2, `pnpm install --frozen-lockfile` and the full root `pnpm check` passed. The blueprint package ran all 84 tests with zero failures and zero skips. Release-target checks, site tests, existing TypeScript checks, other plugin tests, build and pack checks also passed.
-- [CI #43, pull request](https://github.com/klarkxy/dsh-plugins/actions/runs/36299637488) also completed successfully; its job steps confirm the frozen installation and full root check.
-- The package added no dependencies and did not change the root lockfile, workflows or unrelated packages. All 18 initial remote blobs were checked against the tested local source, tests and documentation. This record is a later documentation-only addition; the linked runs identify the implementation commit they actually tested.
+## Host and verification boundaries
 
-## Not established by those tests
+Stock rc.2 has no `plugins.list.actions` slot. The browser run used an isolated
+copy of its official client with the equivalent four-file host integration patch;
+the plugin's own configuration page remains available without that slot. This is
+not an upstream host release or an update of the user's installed application.
 
-The local shell cannot resolve GitHub and pnpm is not installed; dependency installation and the root monorepo checks were not run locally. They were verified in CI as recorded above, not by claiming a local run. No claim is made that a particular released DSH npm/desktop build has passed the whole workflow. Genuine HTTP authentication, HMR/plugin lifecycle behavior, cross-editor races and a real browser remain to be checked in a configured runtime.
+The installed package fixtures exercise native activation/order handling; a fresh
+public npm network installation and a packaged desktop titlebar were not tested.
+No production profile, credential store, publication or deployment was touched.
 
-Before a stable release, use a fresh throwaway DSH Home and a non-production profile to install the actual tarball, verify Plugins-page mounting, export/import a real npm bundle in both modes, inspect bundle order, confirm secrets remain local, exercise post-install configuration preview and native restart/failure cases, and test browser reload/cancellation. Repeat on supported hosts. Do not claim a green unit-test run covers these steps.
-
-The package remains a prerelease; it is not added to the site's npm-backed catalog until a published `latest` version exists. This change does not remove the source repository's v1 runtime, delete user blueprints, merge a PR or publish to npm.
+The prior full workspace check passed release checks, site tests, editor-build
+checks and typechecking, then failed in the unrelated dsh-safe-auto suite on
+Windows path expectations and file-symlink permissions. This removal was verified
+with the current package suite/build and packaging; it does not claim a green full
+workspace check.

package/NOTICE.md

@@ -11,4 +11,4 @@ The original MIT notice is retained in LICENSE. New code in this package is also
 
 The application engine, strict v2 JSON validation, optional policy, host adapter and client integration here target the official current-profile plugin manager. Spaces Supervisor, space creation, LLM connection bindings, workbench RPC, Electron integration and private filesystem write paths are not runtime dependencies and were not copied.
 
-Upstream API inspection: deepseek-ai/deepseek-harness at `477b4f420553e8a52c2fbccc464d7561b239c443`, particularly `packages/boot/plugin-manager`, `packages/settings/settings`, `packages/client/connection`, `packages/client/ui-plugin-manager` and the official settings-page controllers. This inspection is source evidence, not a claim that the same APIs are shipped by every npm or desktop version.
+Upstream API inspection: deepseek-ai/deepseek-harness at `477b4f420553e8a52c2fbccc464d7561b239c443`, particularly `packages/boot/plugin-manager`, `packages/client/connection`, `packages/client/ui-plugin-manager`. This inspection is source evidence, not a claim that the same APIs are shipped by every npm or desktop version.

package/PROTOCOL.md

@@ -0,0 +1,143 @@
+# DSH 蓝图码协议
+
+本文定义当前实现的蓝图数据、文本编码和导入语义。协议标识为 **DSHBP2**，
+JSON 的 `formatVersion` 为 **2**。这是插件组合分享协议，不是环境备份或设置迁移协议。
+
+参考实现：`blueprint.mjs`（数据校验）、`codec.mjs`（文本编解码）、
+`engine.mjs`（导出、预览及执行）。三个层次分别负责结构、编码和操作，
+解码成功不等于数据符合蓝图结构，更不等于可以直接执行。
+
+## 1. 数据结构
+
+```json
+{
+  "kind": "dsh-blueprint",
+  "formatVersion": 2,
+  "metadata": {
+    "name": "示例组合",
+    "description": "以下包名仅用于展示协议结构"
+  },
+  "packages": [
+    { "name": "example-a", "version": "1.2.3", "source": "npm" },
+    { "name": "example-b", "version": "2.0.0", "source": "npm" }
+  ],
+  "bundles": ["example-a", "example-b"]
+}
+```
+
+示例包名不表示真实可安装包。可直接用于编解码验证的空组合及对应蓝图码见
+[`examples/empty.dsh-blueprint.json`](examples/empty.dsh-blueprint.json)、
+[`examples/empty.code.txt`](examples/empty.code.txt)。空组合导入不会停用或删除任何现有插件。
+
+| 字段 | 必需 | 规则 |
+| --- | --- | --- |
+| `kind` | 是 | 固定字符串 `dsh-blueprint` |
+| `formatVersion` | 是 | 固定整数 `2` |
+| `metadata` | 是 | 只允许 `name`、`description` |
+| `metadata.name` | 是 | 1–120 个 UTF-16 代码单元，不含 U+0000–U+001F |
+| `metadata.description` | 否 | 存在时为 1–4000 个 UTF-16 代码单元，不含 U+0000–U+001F |
+| `packages` | 是 | 最多 128 项；按顶层安装请求的建议顺序排列 |
+| `packages[].name` | 是 | 包名字符串，最多 214 个代码单元；包名不能重复，不能引用 `@klarkxy/dsh-blueprint` 本身 |
+| `packages[].version` | 是 | 精确 SemVer，包括可选预发布／构建标识；不接受 `latest`、范围或未固定版本 |
+| `packages[].source` | 是 | `npm` 或 `builtin` |
+| `bundles` | 是 | 最多 128 个互不重复的包名；必须全部存在于 `packages`，表达请求启用的组合层及建议先后 |
+
+包名语法为 `^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$`。
+当前协议只允许以上字段；每个 package 对象只允许 `name`、`version`、`source`。
+不包含设置、凭据、组件行状态、执行脚本、其他蓝图的嵌套引用或自动更新链接。
+
+`packages` 和 `bundles` 分别表达安装与启用意图。某项在 `packages` 中但不在
+`bundles` 中，表示只请求它存在，**不表示接收方应停用它**。
+`npm` 包缺失时由官方管理器安装精确版本；`builtin` 必须由接收方宿主提供。
+顶层安装请求顺序不替代包管理器的依赖解析，也不定义异步插件启动顺序。
+
+## 2. 导入语义
+
+导入是向当前组合补充插件，不能把蓝图顺序当作强制重排或依赖声明。
+
+1. 已存在、来源和版本匹配的可管理包复用；不同来源、不同版本或受保护／不可用的目标列为阻碍，不自动升级、降级或换源。
+2. 缺失的 npm 包按 `packages` 顺序安装，安装时不启用。
+3. 当前启用的完整列表记作 `L`，蓝图的 `bundles` 记作 `B`。
+   最终顺序为 `L + B 中尚未存在于 L 的项`，保留这些新增项在 B 中的先后。
+4. 只启用尚未启用且在 `bundles` 中的项，不重装已匹配的包，不停用或移动任何现有层。
+5. 未出现在蓝图中的本地插件保留；重复导入同一蓝图且本地状态未变化时，无需执行任何动作。
+6. 先预览安装／启用动作和最终顺序，确认后执行。顺序不同本身不构成冲突。
+
+| 当前 L | 外来 B | 结果 |
+| --- | --- | --- |
+| A → B → C | C → D → A | A → B → C → D |
+| A → X → B → C | A → D → B | A → X → B → C → D |
+| A → B → C | C → A | A → B → C（无操作） |
+| A → C，B 已安装但未启用 | B → A | A → C → B（只启用 B） |
+
+当前协议没有 `before`、`after` 或其他硬顺序约束字段，不从排列或包名猜测依赖。
+需要严格封装组件及默认配置关系时，使用 DSH 原生组合插件。顺序合并成功不证明
+任意插件之间语义兼容；组合包自身的配置层仍可能改变最终生效默认值。
+
+导入后保存的是宿主的一份平面组合，外来蓝图不会成为持续同步的子蓝图。
+安装与启用使用宿主接口；整个多步骤导入不提供跨插件事务、自动重试或整体回滚。
+状态变化会使预览失效；需要重启、操作失败或中断时停止并报告已完成部分。
+
+## 3. 文本编码
+
+导入只接受以下一种大小写敏感的蓝图码。JSON 只用于内部数据结构和开发调试，不作为界面的导入或导出格式：
+
+```text
+DSHBP2:<payload>
+```
+
+- 固定流程：JSON 的 UTF-8 字节 → **raw DEFLATE** → 无填充 Base64url。
+  raw DEFLATE 没有 zlib／gzip 头尾，不得使用 gzip 或普通 zlib 包装流替代。
+- Base64url 字符集为 `A–Z a–z 0–9 - _`；不允许 `=` 填充或空载荷，且重新编码必须逐字一致。
+- 解码前只裁去文本首尾的空格、Tab、CR、LF；不移除码内空白，不接受 Markdown 围栏。
+- UTF-8 必须有效，不接受 BOM。JSON 字段顺序和普通 JSON 空白不具有语义。
+- 参考编码器使用紧凑 JSON，始终压缩后编码，不提供编码模式参数。
+  不要求不同压缩库生成完全相同的压缩字节，只要求能正确解码。
+
+蓝图码不提供加密、签名或作者认证。导入方仍须检查包身份和将执行的动作。
+
+## 4. 限制与拒绝规则
+
+- 输入文本最大 **2 MiB（UTF-8 字节数）**；解码／解压后的 JSON 最大 **1 MiB**。
+- JSON 最多 **64 层容器嵌套**；压缩数据只能包含一个完整 raw DEFLATE 流，禁止尾随字节。
+- 拒绝重复 JSON 成员（含转义后同名）、非法 Unicode、非有限数和不安全整数。
+- 任意对象层级禁止键 `__proto__`、`prototype`、`constructor`。
+- 不支持的前缀、编码、协议版本、文档类型、字段、包来源或不明确版本均拒绝；不做格式猜测或迁移。
+- 宿主传输层可以另有请求体限制，协议上限不保证所有宿主接受同样大小的 RPC 请求。
+
+## 5. 使用参考实现生成与验证
+
+```js
+import { validate } from '@klarkxy/dsh-blueprint/core';
+import { encode, decode } from '@klarkxy/dsh-blueprint/codec';
+
+const document = validate({
+  kind: 'dsh-blueprint',
+  formatVersion: 2,
+  metadata: { name: '空组合' },
+  packages: [],
+  bundles: [],
+});
+const code = encode(document);             // 生成唯一格式的蓝图码
+const checked = validate(decode(code));   // 解码之后仍须校验文档
+```
+
+`encode`／`decode` 负责 JSON 和编码安全边界，`validate` 负责蓝图结构。
+制作工具应在编码前、解码后调用 `validate`。随后还需要当前宿主的导入预览；
+不要把生成蓝图码当作执行授权。
+
+## English summary
+
+DSHBP2 transports a plugin-only JSON document with exact package identities.
+`packages` gives top-level installation request order; `bundles` gives requested
+activations in preferred order. Import keeps the full current active sequence and
+appends only requested names not already active. Matching packages are reused;
+version/source conflicts block application. Absence never disables a local bundle.
+There are no hard ordering constraints, settings transfers or nested blueprint links.
+
+`DSHBP2:` is the only code format and carries unpadded canonical Base64url of
+raw-DEFLATE-compressed UTF-8 JSON. Raw JSON is not accepted for import. The caps are
+2 MiB input, 1 MiB decoded JSON, and 64 JSON container levels. No signatures or
+encryption are implied. Use `validate(decode(text))` before host preview and
+`encode(validate(document))` when authoring. The shipped empty-document vectors
+are safe no-op examples; compressed byte-for-byte equality is not required.

package/README.md

@@ -1,14 +1,14 @@
-# DSH Blueprint
+# Blueprint
 
 [中文](README.zh-CN.md)
 
-Export and import DSH plugin compositions from the **official Plugins page**. Share either the plugin list and layer order, or the same composition with saved configuration. No Spaces installation, workspace supervisor, separate desktop application or cloud account is required.
+Export and import DSH plugin compositions from the **official Plugins page**. Blueprint codes share only the plugin list, exact versions and order. Reusable default configuration belongs in native composition/preset plugins. No Spaces installation, workspace supervisor, separate desktop application or cloud account is required.
 
 **Source preview, not a published or end-to-end-certified release.** See [ACCEPTANCE.md](ACCEPTANCE.md) for actual test coverage and outstanding runtime verification.
 
 ## Install this checkout
 
-Requires a DSH Web host exposing the official `pluginManager`, profile-backed volatile `settings`, `pluginPackages`, `loader`, authenticated `connection.rpc` and plugin-manager configuration slots. The adapter checks capabilities instead of assuming a version string guarantees support. The current source contracts were reviewed at upstream commit `477b4f420553e8a52c2fbccc464d7561b239c443`; compatibility with a particular npm/desktop release still needs a runtime test.
+Requires a DSH Web host exposing the official `pluginManager`, `profileContext`, authenticated Connection/WebServer and plugin-manager configuration slots. The adapter checks capabilities instead of assuming a version string guarantees support. The current source contracts were reviewed at upstream commit `477b4f420553e8a52c2fbccc464d7561b239c443`; compatibility with a particular npm/desktop release still needs a runtime test.
 
 ```sh
 cd plugins/dsh-blueprint
@@ -23,81 +23,68 @@ This package has no npm dependencies and no compilation requirement. It calls na
 
 ## Use
 
-Open **Plugins → DSH Blueprint**. A **Share blueprint** action on another bundle's detail page opens the same export screen focused on that bundle.
+On hosts with the `plugins.list.actions` slot, use **Plugins → Blueprint → Import blueprint / Export blueprint** in the list toolbar. The Blueprint plugin page offers the same controls on hosts without that slot. Other plugin detail pages no longer show a Share blueprint button.
 
-Select bundles, choose **Plugins only** or **Include saved settings**, and generate a preview. Settings mode also records editable plugin-row enabled states. Ordinary fields are included by default. Uncheck a form or individual field before generating. Copy the share code or save UTF-8 JSON. Nothing is published or sent to a third-party service.
+**Export blueprint:** select plugins, review or adjust their preferred order, generate a code and copy it. Paste it into **Import blueprint**, preview package operations and final order, then confirm. Missing packages are installed disabled through the official manager before explicit activation; unrelated packages are preserved. No configuration or row states enter a blueprint.
 
-On the receiving host, paste a code/JSON or open a file, then **Preview import changes**. Inspect versions, operations, the resulting complete layer order, settings values and warnings. Confirm the trust notice before applying. Missing packages are installed disabled through the official manager; requested bundle activation is an explicit, previewed operation and executes plugin code.
+The official DSH 0.1.7-rc.2 host lacks the list-toolbar slot. See the source patch in [host integration](https://github.com/klarkxy/dsh-plugins/tree/main/host-integration/blueprint-list-actions). Shipping this plugin alone cannot add a toolbar control to the stock host.
 
-When composition changes are needed, apply those first, then run **Preview settings after installation**. This second preview binds configuration writes to the real installed plugin's native schema and revision. The plugin never invents configuration metadata for code that has not been loaded. Native `restart-required`, rejected writes or failures stop the plan and are reported rather than called success.
+
+## Creator mode
+
+When this plugin is loaded, Creator (`cordis`) receives the bundled [blueprint skill](skills/dsh-blueprint/SKILL.md), covering blueprint codes, import previews and native composition plugins. The body is injected directly into the Creator system prompt so it does not depend on a skill catalog or a separate skill tool. Other presets receive no guidance; switching away removes it on the next prompt assembly. Registration follows plugin and prompt-service lifetimes. Hosts without prompt services retain the Plugins-page workflow.
+
+The skill uses the read-only discovery tools below and the existing page and validation/codec exports. It adds no model-facing install/apply tools and does not imply permission to import or publish a blueprint. Without page access, the agent can prepare/review JSON and explain the remaining steps, but must not claim the import ran.
+
+## Plugin search and versions
+
+Blueprint owns two read-only host tools (subject to the host's tool policies); it does not depend on the official-documentation plugin:
+
+- `blueprint_search_plugins({ query, source?, limit?, offset? })`: the default `catalog` source searches the site's published Chinese/English [plugin catalog](https://klarkxy.github.io/dsh-plugins/plugins.json). `source: "npm"` searches npm's `dsh-plugin` keyword candidates and filters for DSH names/keywords. Neither source is exhaustive; use exact package lookup for known packages. Results include source, fetch time and pagination, and remain candidates until version verification.
+- `blueprint_plugin_versions({ package, version?, limit?, offset? })`: queries public npm metadata, lists published releases and tags, and returns the selected exact version's bundle declaration, DSH/Node engine ranges, dependencies, peer dependencies and deprecation. `version` accepts an exact release or dist-tag, defaulting to `latest`; ranges are rejected. Versions are paged by publication time, not semver precedence. Use `selected.version` in the blueprint.
+
+Queries fetch current metadata without caching or a stale fallback. They do not download packages, execute scripts, install plugins or alter the profile. Native import preview remains the authority for installation and target compatibility. Built-in bundles still come from the current host; these tools do not discover private registry packages. Missing tool services leave the page operational; plugin/service unload unregisters tools and aborts pending requests. Tool registration uses the DSH 0.1.7-rc.2 output contract.
 
 ## Scope and defaults
 
 - Only bundles listed by the official manager are selected. Exact npm versions and installation-provided bundles are supported. Local links, git/tarball sources, aliases, unreadable metadata and version conflicts are reported, not silently rewritten as npm packages. Dependencies without a bundle remain the native package manager's responsibility.
-- The native manifest supplies layer order, not the alphabetically sorted cards. Unshared bundles are not removed or disabled. If relative order must change, selected active bundles are disabled and then enabled in blueprint order, after unshared layers. The preview shows this placement and every resulting operation. A bundle with no activation change is not cycled unnecessarily.
-- Settings come exclusively from the official Config/Settings **native editable descriptors**: saved effective values, including defaults, not browser drafts, raw Config files or plugin data directories. No page ledger or per-page mapping is maintained. Custom UI over native Settings works without UI-specific handling; custom-only pages, APIs and storage are deliberately unsupported.
-- Only active, uniquely owned, writable native forms are eligible. Ordinary nonvolatile fields are not shared. Unavailable native settings are reported; package-list sharing remains available. An incoming unsupported form or path blocks the settings preview instead of being silently dropped. A custom page may display fewer fields than the native descriptor: review the actual export fields, not the page's appearance.
-- See [Settings scope](SETTINGS-SCOPE.md) for the normative boundary, author responsibilities, alpha.1 behavior change and upstream evidence. There is no planned per-plugin custom-storage adapter or migration layer.
-- Host-redacted secrets never enter the blueprint. A secret-bearing array is omitted as a whole rather than reindexed or copied incompletely. The plugin does not read the credential service. **Unmarked private text is not reliably recognizable as a secret.** Preview the output before publishing it.
-- Import applies explicit field edits with the native revision check, preserving unmentioned values. It is not a whole-form replacement. Nonsecret arrays are replaced atomically; they are not guessed or merged by index. Connection-target changes (`baseURL`, `endpoint`, `url`, `host`, `apiKeyEnv` and spelling variants) require local changes in the official page before importing, even when the secret lives outside the Settings form. This avoids silently combining an imported endpoint with a receiver's existing key.
-- Native type/schema validation still applies. Directory strings and provider/model route names are ordinary settings, not copied resources; the recipient must ensure they refer to available local resources. Import does not transfer directories, model connections, keys, sessions, attachments, histories, databases or caches.
+- Export starts from native order and records a preference. Import preserves the full local active sequence and appends only requested activations that are not already active. Matching packages are reused; omitted or install-only entries never disable local bundles. Different sequence order is not a conflict, and repeating an unchanged import is a no-op.
+- Blueprint does not read or write settings, schemas, credentials or plugin data. There is no settings-transfer or field-sharing policy.
 
-## Optional author policy
+## Reuse configuration through composition plugins
 
-No contribution means **include the native public form by default**. In the owning package's `package.json`, an author can narrow sharing for an exact native row id:
+A native bundle can depend on plugin packages and explicitly insert their components with reusable configuration defaults in its cordis.patch.yml. Another bundle can override existing rows. Dependency installation alone does not recursively activate every dependency bundle; declare the intended component rows and avoid loading the same row twice.
 
-```json
-{
-  "dshBlueprint": {
-    "version": 1,
-    "entries": {
-      "my-plugin": {
-        "exclude": [["privateNote"], ["connection", "machineId"]]
-      },
-      "another-instance": { "share": false },
-      "theme": { "include": [["appearance"]] }
-    }
-  }
-}
-```
-
-Paths are arrays of exact segments, not globs or JavaScript. `share: false` excludes the entire form; `include` narrows it; `exclude`, native editability and host secret annotations always win. The receiver rechecks its installed policy. Invalid declarations make that package's configuration unavailable with a warning; they never degrade to exporting everything. Metadata is read as JSON without executing export callbacks. This policy only narrows native fields; it cannot register another storage source. This is this plugin's contribution contract, not an official DSH manifest extension.
+This uses the host's existing configuration layers. Later layers take precedence, and a row patch replaces the entire config value rather than deep-merging its fields. Users' profile/home overrides can supersede bundle defaults. Do not package keys, credentials or machine-specific personal data as reusable defaults. See the [version-matched official bundle guide](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.2/docs/user/develop/basic/publish.md#the-loading-order).
 
+Enabling a bundle can change the effective defaults contributed by its own patch. The newly appended layer still participates in native configuration precedence; review the package operation preview.
 ## Portable format v2
 
+See the [blueprint-code protocol](PROTOCOL.md) for the complete fields, additive import semantics, encoding rules and shipped test vectors.
+
 ```json
 {
   "kind": "dsh-blueprint",
   "formatVersion": 2,
-  "metadata": { "name": "My setup", "version": "1.0.0" },
+  "metadata": { "name": "My setup" },
   "packages": [
     { "name": "example-plugin", "version": "1.2.3", "source": "npm" }
   ],
-  "bundles": ["example-plugin"],
-  "settings": [
-    {
-      "package": "example-plugin",
-      "row": "example",
-      "module": "example-plugin",
-      "fields": [{ "path": ["theme"], "value": "paper" }]
-    }
-  ]
+  "bundles": ["example-plugin"]
 }
 ```
 
-The package is illustrative, not an install recommendation. `settings` and `rows` are optional; plugin-only exports omit both. `rows` entries carry `package`, `row`, `module` and boolean `enabled`. `source` is `npm` or `builtin`. Exact row/module/package identity is verified on the recipient. Unknown root/entry fields and unsupported versions are rejected.
-
-Codes are `DSHBP2:J:<unpadded-base64url-UTF8-JSON>` or `DSHBP2:Z:<unpadded-base64url-raw-DEFLATE-JSON>`. The encoder chooses the shorter form. Limits: 1 MiB decoded JSON, 2 MiB input code, 64 JSON container levels. Duplicate JSON members, unsafe numbers, prototype keys, malformed Unicode, noncanonical Base64url and trailing compressed streams are rejected. Codes are **not encryption, signatures or proof of trust**.
+The package is illustrative, not an install recommendation. `source` is `npm` or `builtin`. Blueprint documents contain only the fields shown above; unknown fields and other document kinds are rejected.
 
-Spaces `DSHBP1` / format v1 described creation of a new isolated space, including Spaces-specific bindings. The v2 reader rejects those codes rather than silently applying them to the current profile. Re-export through the new manager integration. This extraction does not delete or rewrite the legacy v1 implementation in the source repository; no in-place v1 migration is claimed.
+Codes use one format: `DSHBP2:<payload>`, where the payload is unpadded canonical Base64url of raw-DEFLATE-compressed UTF-8 JSON. The interface imports and exports only this code; JSON is an internal data structure. Limits: 1 MiB decoded JSON, 2 MiB input code, 64 JSON container levels. Duplicate JSON members, unsafe numbers, prototype keys, malformed Unicode, noncanonical Base64url and trailing compressed streams are rejected. Codes are **not encryption, signatures or proof of trust**.
 
 ## Operation and security contract
 
-All management goes through the official manager; all setting writes go through native Settings. The package registers an authenticated logical RPC channel through official Connection, not a second server. The native transport's request cap also applies.
+All package management goes through the official manager. The package registers an authenticated logical RPC channel through official Connection, not a second server. The native transport's request cap also applies.
 
-A preview creates a process-local, five-minute, one-use plan bound to the observed profile and form revisions. At most eight plans/results are retained. Changed observations invalidate a plan; completed results can be read without rerunning operations. No automatic retries, upgrades, downgrades, script approvals, removals, cross-profile writes or blueprint-level rollback are performed. The native installer retains its own documented failure behavior.
+A preview creates a process-local, five-minute, one-use plan bound to the observed package/profile state. At most eight plans/results are retained. Changed observations invalidate a plan; completed results can be read without rerunning operations. No automatic retries, upgrades, downgrades, script approvals, removals, cross-profile writes or blueprint-level rollback are performed. The native installer retains its own documented failure behavior.
 
-A multi-step import is **not a transaction or a lock against every other editor**. It checks observed state between operations and uses native per-operation serialization/revision checks. Stop editing that profile elsewhere while applying. Failures preserve visible partial outcomes; a lost response is not a reason to replay an import. Closing the page requests cancellation where supported. Already-completed changes may remain.
+A multi-step import is **not a transaction or a lock against every other editor**. It checks observed state between operations and uses native per-operation serialization. Stop editing that profile elsewhere while applying. Failures preserve visible partial outcomes; a lost response is not a reason to replay an import. Closing the page requests cancellation where supported. Already-completed changes may remain.
 
 ## Development
 

package/README.zh-CN.md

@@ -1,14 +1,14 @@
-# DSH 蓝图
+# 蓝图
 
 [English](README.md)
 
-在 **DSH 官方插件管理器**内导入、导出插件组合：可以只分享插件列表与生效顺序，也可以连已保存的配置一起分享。无需安装 Spaces，无需独立客户端、Supervisor 或云账户。
+在 **DSH 官方插件管理器**内导入、导出插件组合：蓝图码只分享插件、精确版本和顺序；可复用的默认配置交给原生组合插件。无需安装 Spaces，无需独立客户端、Supervisor 或云账户。
 
 **当前为源码预览版本，尚未发布到 npm，也未完成真实 DSH 端到端验收。** 已执行检查与剩余验收见 [ACCEPTANCE.md](ACCEPTANCE.md)。
 
 ## 安装与入口
 
-需要提供官方 `pluginManager`、基于 profile 的 volatile `settings`、`pluginPackages`、`loader`、已鉴权 `connection.rpc` 和插件配置 slot 的 DSH Web 宿主。启动会检查所需能力；仅凭版本号不声称兼容。接口核对基于上游提交 `477b4f420553e8a52c2fbccc464d7561b239c443`，具体 npm 或桌面版本仍需实际验收。
+需要提供官方 `pluginManager`、`profileContext`、已鉴权 Connection/WebServer 和插件配置 slot 的 DSH Web 宿主。启动会检查所需能力；仅凭版本号不声称兼容。接口核对基于上游提交 `477b4f420553e8a52c2fbccc464d7561b239c443`，具体 npm 或桌面版本仍需实际验收。
 
 ```sh
 cd plugins/dsh-blueprint
@@ -19,60 +19,51 @@ npm pack
 dsh plugin --profile <目标profile> add /绝对路径/klarkxy-dsh-blueprint-0.1.0-alpha.2.tgz
 ```
 
-包没有 npm 依赖和编译要求，复用宿主服务与 React。安装后打开 **插件 → DSH 蓝图**。其他组合包详情页的 **分享蓝图** 按钮会进入同一界面并选中该包。
+包没有 npm 依赖和编译要求，复用宿主服务与 React。支持 `plugins.list.actions` 的宿主在插件列表顶部显示 **蓝图 → 导入蓝图 / 导出蓝图**。未接入该插槽的宿主可通过 **插件 → 蓝图** 使用相同的蓝图操作；其他包详情页不再放“分享蓝图”。
 
-## 导出
+官方 DSH 0.1.7-rc.2 尚无列表顶部插槽，需要配套[宿主接入补丁](https://github.com/klarkxy/dsh-plugins/tree/main/host-integration/blueprint-list-actions)。仅安装本插件不能让当前官方宿主顶部出现按钮。
 
-选择插件，选择 **仅插件组合** 或 **包含已保存设置**。后者还记录可修改的插件行启停状态。普通配置默认包含，不要求作者专门适配；生成前可取消某个表单或字段。检查生成的 JSON，然后复制分享码或保存 JSON。不会自动上传或发布。
+## 创造模式
 
-**唯一设置来源是官方 Config／Settings 暴露的可编辑描述符。** 导出原生已保存的生效值（包括默认值），不读取浏览器草稿、普通非 volatile Config 字段、任意配置文件或插件数据目录。不再枚举页面 slots，也不维护页面专用字段映射。
+加载插件后，创造模式（`cordis`）自动收到随包分发的[蓝图 skill](skills/dsh-blueprint/SKILL.md)，包含蓝图码制作、分享、导入预览和原生组合插件的复用边界。指引正文直接注入系统提示，不依赖技能目录或单独的 skill 工具；其他模式不注入，切换离开创造模式后下一次提示组装不再包含它。注册跟随插件及提示词服务的生命周期；没有提示词服务的宿主仍可正常使用插件页面。
 
-自己画 UI、但仍使用原生 Settings 的插件，在数据层照常支持；完全自建页面、接口或存储的配置不读取、不推断、不适配。自定义页面可能只显示原生字段的子集，蓝图不尝试识别该子集；请按实际导出预览选择字段。不可用的原生设置会报告，但插件清单仍可分享；导入不支持的设置会阻止设置预览，不默默丢弃。
+该 skill 使用下述只读发现工具及现有页面、格式校验和编解码接口，不新增模型安装或应用工具，也不把制作蓝图视为导入或发布授权。没有页面操作能力时，智能体可以准备、检查 JSON 并说明剩余操作，但不能声称已经导入。
 
-完整范围、作者责任、与 alpha.1 的行为区别及官方依据见 [设置范围说明](SETTINGS-SCOPE.md)。自建配置适配与自动迁移明确不在本产品范围内。
+## 插件搜索与版本查询
 
-关闭的插件没有活动表单，不能读取其不可见设置，但仍可分享安装清单与 bundle 选择。共享前请核对列出的配置项。凭据服务不被读取；宿主已标记的秘密不会导出。数组含秘密或排除字段时，整段数组被排除，避免索引错位。**未标记的私密文本不能保证被自动识别，公开分享前应查看预览。**
+蓝图插件提供两个只读宿主工具，受宿主工具策略约束，不依赖官方文档插件：
 
-## 导入
+- `blueprint_search_plugins({ query, source?, limit?, offset? })`：默认 `catalog` 搜索本站已发布插件的中英文名称和简介；`source: "npm"` 扩展到 npm 的 `dsh-plugin` 关键词候选，并按 DSH 名称或关键词过滤。两者都不是全量目录，已知包名可直接查询版本。结果带来源、抓取时间和下一页位置，搜索命中不代表兼容性已经验证。
+- `blueprint_plugin_versions({ package, version?, limit?, offset? })`：查询公开 npm 的发布版本、标签及选定版本的组合包声明、DSH／Node 版本要求、依赖和弃用说明。`version` 可填精确版本或标签，默认 `latest`，不接受范围；版本列表按发布时间分页，不按语义版本优先级排序。制作蓝图使用返回的 `selected.version`。
 
-粘贴分享码、JSON 或读取文件，选择 **预览导入变更**，核对版本、操作、完整生效顺序和设置值，再确认信任提示并执行。安装、启停都调用官方管理器，不另建安装器；不自动授权构建脚本，但宿主已有的脚本授权仍可能生效。启用插件会执行其代码。
+查询实时读取元数据，不缓存或在失败后回退过期数据；不下载包、不执行脚本、不安装插件、不修改 profile。实际安装与目标兼容性仍由原生导入预览核验。宿主内置组合包以当前宿主为准，私有 registry 不在查询范围内。没有工具服务时页面仍可用；卸载插件或工具服务会注销工具并取消进行中的查询。工具注册按 DSH 0.1.7-rc.2 输出契约验证。
 
-需要新增或重排组合时，先执行组合阶段，再点 **安装后重新预览设置**。第二次预览依据真正安装后的原生 schema 和修订号生成设置操作。宿主要求重启、配置拒绝或中途失败都会停止，不会报告为整体成功。
+## 导出
 
-只修改所选组合包，不卸载未选包。需要改变相对顺序时，先关闭所选已启用层，再按蓝图顺序开启，放到未选层之后；预览会展示全部操作和最终顺序。无须重排时不重复启停。安装清单与生效顺序分别记录，不使用页面的字母排序冒充顺序。
+**导出蓝图**：选择插件，检查并用上移／下移调整建议顺序，生成蓝图码并复制。建议顺序用于安装缺失包和追加尚未启用的组合层，不会覆盖接收方已有顺序。蓝图不包含配置或插件行启停状态。
 
-设置采用带原生 revision 的逐字段写入，保留未提及的值，不用脱敏后的对象整段覆盖配置。普通数组作为整体替换，不猜测按下标合并。`baseURL`、`endpoint`、`url`、`host`、`apiKeyEnv` 等连接目标发生变化时，需要先在接收者的官方配置页本地处理，再导入其余设置，避免将分享者的地址和接收者的密钥自动配对。
+## 导入与现有环境
 
-目录字符串和模型路由名只是设置值，不代表相关资源被复制；接收者应确认本机可用性。不会搬运模型连接库、API Key、会话、附件、数据库或缓存。
+在文本框粘贴蓝图码，预览版本、安装／启用操作和最终顺序，确认后执行。安装通过官方管理器完成，不自动授权构建脚本；启用会执行插件代码。版本或来源冲突会阻止执行，不自动升级、降级或换源。
 
-## 插件作者声明
+已有的完整启用顺序保持不变，匹配的包直接复用。缺失的包按蓝图清单安装，蓝图请求启用但当前未启用的组合层按建议顺序追加到末尾。顺序不同本身不构成冲突；不会因为分享方未启用某项而停用本地插件。重复导入且状态未变时无新动作。
 
-缺省规则为 **包含对应原生表单内的公开字段**。作者可在自己包的 `package.json` 中按原生插件行 id 声明：
+## 用组合插件复用默认配置
 
-```json
-{
-  "dshBlueprint": {
-    "version": 1,
-    "entries": {
-      "my-plugin": { "exclude": [["privateNote"], ["connection", "machineId"]] },
-      "another-instance": { "share": false },
-      "theme": { "include": [["appearance"]] }
-    }
-  }
-}
-```
+原生组合包可以声明所需插件依赖，并在自己的 `cordis.patch.yml` 中明确加载组件、指定默认配置；配置预设包也可以覆盖已有组件行。只声明依赖不会自动递归启用所有依赖包，组合作者需要明确加载哪些组件，避免同一组件行被重复加载。
 
-路径是精确段落数组，不是 glob、表达式或 JavaScript。`share: false` 关闭整个表单的分享；`include` 缩小范围；`exclude`、原生可编辑范围和宿主秘密标记优先。接收端重新检查本机安装版本的声明。无效声明会明确使该包的配置不可分享，不退回“全量导出”。声明只读取 JSON，不执行自定义导出回调，也不能注册自建存储来源。这是本插件的扩展约定，不冒充官方 DSH manifest 标准。
+沿用 DSH 原有配置层规则：后面的层优先，行补丁替换整段 `config`，并非字段深度合并；用户自己的 profile／home 配置可以覆盖组合包默认值。密钥、凭据和本机私有数据不应打进共享包。参见[对应版本的官方说明](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.2/docs/user/develop/basic/publish.md#the-loading-order)。
 
-## 格式与迁移
+蓝图不提供设置导入／导出、设置字段筛选或分享策略，也不读取或写入设置、schema、凭据或插件存储。组合包本身的补丁仍可能影响生效默认值，因此新启用的组合层仍需核对预览。
+## 格式
 
-新格式为 `kind: "dsh-blueprint"`、`formatVersion: 2`。`packages` 记录精确版本和 `npm` / `builtin` 来源；`bundles` 记录有序启用层；可选 `settings` 记录 `{package,row,module,fields:[{path,value}]}`；可选 `rows` 记录 `{package,row,module,enabled}`。最小示例及字段规则见英文文档的 Portable format v2。
+完整字段、导入语义、编码规则和可验证示例见 [蓝图码协议](PROTOCOL.md)。
 
-分享码为 `DSHBP2:J:`（UTF-8 JSON 的无填充 Base64url）或 `DSHBP2:Z:`（先 raw DEFLATE 压缩）。最大 JSON 1 MiB、输入分享码 2 MiB、64 层 JSON 容器；宿主传输的请求大小限制也生效。重复键、不安全数字、原型键、损坏 Unicode、非规范 Base64url 和压缩尾随数据拒绝读取。编码不是加密、签名或作者认证。
+格式为 `kind: "dsh-blueprint"`、`formatVersion: 2`。`packages` 记录精确版本和 `npm` / `builtin` 来源；`bundles` 记录请求启用的组合层及建议顺序。蓝图禁止包含 `settings` 或 `rows`，未知字段和其他文档类型会被拒绝。最小示例及字段规则见英文文档的 Portable format v2。
 
-只支持可确认的精确 npm 来源与宿主内置组合包。本地链接、git/tarball、别名和版本冲突会列出，不悄悄改源。官方管理器不列为组合包的普通依赖由包管理器负责。
+分享码统一为 `DSHBP2:<内容>`：JSON → UTF-8 → raw DEFLATE → 无填充 Base64url。界面导入、导出都只使用这种蓝图码；JSON 是内部数据结构。最大 JSON 1 MiB、输入分享码 2 MiB、64 层 JSON 容器；宿主传输的请求大小限制也生效。重复键、不安全数字、原型键、损坏 Unicode、非规范 Base64url 和压缩尾随数据拒绝读取。编码不是加密、签名或作者认证。
 
-Spaces 的 `DSHBP1` / v1 原义是创建新隔离空间，包含专属绑定；这里明确拒绝，不偷偷把旧码解释成修改当前 profile。应通过新入口重新导出。本次独立实现没有删除或改写原仓库的历史 v1 实现，不宣称已完成旧空间数据迁移。
+只支持可确认的精确 npm 来源与宿主内置组合包。本地链接、git/tarball、别名和版本冲突会列出，不悄悄改源。官方管理器不列为组合包的普通依赖由包管理器负责。
 
 ## 执行边界