From ff11e549b57edd2d20a232e9588d269b437ce9d7 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Tue, 13 Oct 2026 20:34:36 +0800
Subject: [PATCH 1/6] docs(community): add community on-call SLA and group
 layering docs

Register the two new community documents in the public source inventory so
check:source passes.

- docs/community/oncall.md: role split (chat vs GitHub), rotation windows,
  48h triage SLA, label hygiene rules, contribution-request rules, weekly
  feedback replay, reply templates, weekly metrics.
- docs/community/groups.md: three community layers and what belongs in each,
  the single entry point, movement rules, Insider external-disclosure rule,
  showcase wall and AMA format.
---
 docs/community/groups.md   |  87 +++++++++++++++++++++
 docs/community/oncall.md   | 156 +++++++++++++++++++++++++++++++++++++
 release/public-source.json |   2 +
 3 files changed, 245 insertions(+)
 create mode 100644 docs/community/groups.md
 create mode 100644 docs/community/oncall.md

diff --git a/docs/community/groups.md b/docs/community/groups.md
new file mode 100644
index 000000000..a2ed8c10a
--- /dev/null
+++ b/docs/community/groups.md
@@ -0,0 +1,87 @@
+# Community groups
+
+This document defines the three community layers, what each layer is for, and the rule for moving
+between them. It is public so that joining a group is a predictable decision rather than a guess.
+
+## Layers
+
+| Layer | Who can join | What belongs there | What does not |
+| --- | --- | --- | --- |
+| Newcomer | Anyone with the group QR code or the Discord link | Install, configuration, first-run usage, frequently asked questions | Unreleased features, internal roadmap, internal test builds |
+| Advanced | Anyone who has opened at least one issue, or who is invited | Architecture discussion, PR intentions, performance findings, design proposals | Internal roadmap, unreleased features |
+| Insider | Invitation only, after signing the external-disclosure rule | Test builds, unreleased features, early feedback | Screenshots of accounts, session identifiers, or unreleased versions |
+
+The three layers are rules first and separate groups second. A new group with fewer than 50 active
+members is not created; the rule applies to the existing group until the volume justifies a split.
+
+## The one entry point
+
+Every layer carries the same pinned card, pointing at the same three places:
+
+1. **Report an issue** — `https://github.com/MiniMax-AI/minimax-code/issues/new/choose`
+2. **Claim a task** — the `good first issue` label:
+   `https://github.com/MiniMax-AI/minimax-code/labels/good%20first%20issue`
+3. **See the on-call rota and the weekly replay** — [Community on-call](oncall.md)
+
+Feedback posted in chat without an issue number is not tracked. If a chat report is not converted into
+an issue within 24 hours, the on-call owner raises it on the reporter's behalf.
+
+## Moving between layers
+
+- **Newcomer → Advanced**: automatic, as soon as the member opens an issue or is invited. There is no
+  application and no approval.
+- **Advanced → Insider**: invitation only. The invite includes the external-disclosure rule below, and
+  the rule is acknowledged before any test build is shared.
+- **Insider → public**: content returns to a public layer only through the formal release notes. Chat
+  history is never the source for external material.
+
+## External-disclosure rule for the Insider layer
+
+Acknowledged by every Insider member before receiving a test build.
+
+1. Test builds, unreleased feature names, and internal version numbers stay in the Insider layer. They
+   are not posted to a public group, a public issue, a screenshot, a blog post, or a video.
+2. Account identifiers, session identifiers, tokens, and customer project content are never shared in
+   any layer. Use synthetic files and dedicated test accounts.
+3. External material about a feature comes from the release notes for a released version, not from a
+   chat log. If a screenshot is needed for a public post, it must be regenerated from a released
+   build.
+4. A leak is reported to the release coordinator immediately, and the affected material is withdrawn
+   as soon as it is identified. Reporting a leak is never held against the reporter.
+
+## What a layer may be used for
+
+| Activity | Newcomer | Advanced | Insider |
+| --- | --- | --- | --- |
+| Install and configuration help | Yes | Yes | Yes |
+| Bug report and question answering | Yes | Yes | Yes |
+| Weekly feedback replay | Yes | Yes | Yes |
+| AMA session (biweekly) | Yes | Yes | Yes |
+| Showcase wall submission | Yes | Yes | Yes |
+| Architecture and design discussion | No | Yes | Yes |
+| Pull request review participation | No | On invitation | Yes |
+| Test build distribution | No | No | Yes |
+
+## Showcase wall
+
+Showcases are collected in `docs/showcase/` and mirrored to a GitHub Discussions category.
+
+- **Threshold:** a showcase must be runnable — a repository, or a prompt that reproduces it, plus the
+  verification command. Screenshots alone are not accepted.
+- **Every showcase produces a task.** Each accepted showcase must yield at least one
+  `good first issue` task, by extracting the step a newcomer could do independently. This is the point
+  of the wall: a showcase that produces no task brings in visitors who find nothing to do.
+- **Low bar by design:** the entry requirement is "post a prompt that runs". A showcase is not a
+  product pitch.
+
+## AMA sessions
+
+Biweekly, 30 minutes: 20 minutes of product questions, 10 minutes walking through live issues.
+
+- **Agenda comes from the queue.** Every question discussed is drawn from the current
+  `needs-triage` queue or a contribution request. The host does not choose topics independently.
+- **Recording and minutes** are archived to the Discussions `AMA` category, with the issue numbers
+  discussed listed in the minutes.
+- **Failure condition:** if three consecutive sessions draw fewer than 30% of registrants, the format
+  changes to a smaller closed-door session over live issues instead of a public AMA. Adding more
+  sessions is not the response.
diff --git a/docs/community/oncall.md b/docs/community/oncall.md
new file mode 100644
index 000000000..8ee676e91
--- /dev/null
+++ b/docs/community/oncall.md
@@ -0,0 +1,156 @@
+# Community on-call and issue SLA
+
+This document defines who watches the community channels, what counts as a response, and how
+feedback is replayed back to reporters. It is a public commitment: anyone reading it should be able
+to predict when they will hear back.
+
+## Scope
+
+The community on-call covers two surfaces:
+
+| Surface | Meaning | Owner |
+| --- | --- | --- |
+| Community chat (Chinese Feishu group, Discord) | User questions, feedback, event coordination | On-call A |
+| GitHub issues (`MiniMax-AI/minimax-code`) | Bug reports, feature requests, contribution requests | On-call B |
+
+These are two different roles and they are staffed by two different people. A single person holding
+both roles cannot cover the 18:00–20:00 window, so that window is explicitly not covered by either
+role.
+
+## Rotation
+
+| Role | Window | Timezone | Coverage |
+| --- | --- | --- | --- |
+| On-call A | Weekdays 10:00–18:00 | Asia/Shanghai | Community chat |
+| On-call B | Daily 09:00, 20:00–23:00, and weekends | Asia/Shanghai | GitHub issues |
+| Uncovered | 18:00–20:00 weekdays | — | Neither role; escalate to the release coordinator |
+
+The rotation is published in the community chat as a pinned card. It is replaced every two weeks.
+
+## Response SLA
+
+**Every open issue must receive a triage action within 48 hours of being opened.** A triage action is
+one of the following, and one of them counts:
+
+- applying a type and product label;
+- asking the reporter for the specific missing information (`needs-info`);
+- linking a duplicate to its original issue;
+- recording a next step in a comment, including a decision to decline with a reason.
+
+A triage action is not a promise to fix or to ship in a release. Classification alone does not commit
+the project to a delivery date, and this distinction is stated in every response so reporters know
+what they are getting.
+
+Anything that has been open for more than 48 hours without any of the above is a SLA breach and is
+listed in the weekly feedback replay.
+
+## Label hygiene
+
+- An issue must not stay on `needs-triage` after it is closed. When closing an issue, remove
+  `needs-triage` in the same action.
+- `needs-triage` counts only open issues. Reporting a `needs-triage` ratio that includes closed
+  issues overstates the backlog; the canonical number is `is:issue is:open label:needs-triage`.
+- When an issue is closed as `duplicate` or `wontfix`, the reason is stated in a comment, per the
+  triage policy in [Maintainers](../maintainers.md).
+
+## Contribution requests
+
+A request for repository access is a request for a decision, and a decision must be communicated.
+Even when the answer is "no", the answer is sent.
+
+- Tag contribution requests with `contribution-request` so the funnel from request to decision is
+  measurable.
+- Respond within 48 hours with one of: approved, declined with a reason, or already completed
+  internally.
+- **When the underlying task is completed internally first, the requester is told explicitly and their
+  fork and branch are still declared valid.** If the internal fix missed anything, the requester is
+  invited to open a fork PR. Silently closing a contribution request because the work was done
+  elsewhere is treated as a SLA breach, not as resolution.
+- Submission of a fork PR does not require collaborator access. Access is a convenience for
+  maintainers, not a precondition for contributing.
+
+## Weekly feedback replay
+
+Every Friday, the on-call owner posts a single message to the community chat summarising the week:
+
+- every issue that received a triage action, with its number and what the action was;
+- every issue that was asked for more information, and what is still needed;
+- every issue that was closed, and why;
+- every open issue that has breached the 48-hour SLA, listed by number.
+
+The replay links issue numbers directly. It exists so that a reporter can see what happened to their
+report without having to ask, and it is the mechanism that keeps feedback from being silently dropped.
+
+## Reply templates
+
+### Triage response
+
+```
+Thanks for the report — received and triaged.
+
+Triage action: <label / needs-info / duplicate / next step recorded>, removed from `needs-triage`.
+
+What we need from you to take this further:
+1. <specific question>
+2. <specific question>
+
+We will reply within 48 hours. This triage action is not a commitment to a release date.
+```
+
+### Contribution request — already completed internally
+
+```
+Thanks for the patch and for following the contribution route. Sorry for the long silence on this
+thread; that was our failure, not yours.
+
+The task you prepared for (#<n>) was completed internally by #<n> and #<n>, so that specific task is no
+longer open.
+
+Your fork and branch are still valid. If you spot anything the internal fix missed or got wrong,
+please open a fork PR — no collaborator access is required to submit a fork PR, and we review it
+within 48 hours. The same applies to any other change you have prepared.
+
+If you would like to pick up a scoped task, the `good first issue` label is the canonical list:
+<label url> — items there are expected to be independently completable, with
+`pnpm verify --profile docs` as the verification command for documentation tasks.
+```
+
+The two sentences that matter here are the second and third paragraphs. Reporting that the work was
+done elsewhere, and then stating that the requester's work is still valid, is what keeps a second
+applicant from being treated the same way. Never write "the task is already done, please resubmit".
+
+### Contribution request — approved
+
+```
+Approved. You now have the requested access.
+
+The change is expected to be scoped in an issue first, then submitted as a PR from your fork.
+Please run the verification command for the profile that covers your change
+(`pnpm verify --profile docs` for documentation) and paste the real command output into the PR
+description. Review target is 48 hours; if you have not heard back by then, ping the on-call owner.
+```
+
+### Security-relevant report
+
+```
+Thank you for the detailed report. This is treated as a safety-priority report and escalated for a
+code-level review.
+
+Please do not post further exploit detail in this public thread. If the reproduction involves a
+pattern that could affect other users, open a private report per SECURITY.md and reference this issue
+number.
+
+We will reply within 48 hours.
+```
+
+## Reporting
+
+The on-call owner reports these numbers weekly to the community chat and to the project maintainers:
+
+| Metric | Definition |
+| --- | --- |
+| 48h triage coverage | share of issues opened in the week that received a triage action within 48 hours |
+| Open `needs-triage` | open issues still carrying `needs-triage` (open scope only) |
+| SLA breaches | issues open for more than 48 hours with no triage action |
+| Zero-reply issues | open issues with no comment at all |
+| Contribution request resolution time | hours from request to a communicated decision |
diff --git a/release/public-source.json b/release/public-source.json
index 28bc3882f..8b7ed8616 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -53,6 +53,8 @@
     "docs/assets/tui-demo.png",
     "docs/assets/wordmark-dark.svg",
     "docs/assets/wordmark-light.svg",
+    "docs/community/groups.md",
+    "docs/community/oncall.md",
     "docs/demo.md",
     "docs/examples.md",
     "docs/hooks.md",

From a07228386116667592ee2d76f0bcf81a328a6f35 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Tue, 13 Oct 2026 20:39:30 +0800
Subject: [PATCH 2/6] docs(plugins): publish Plugin V1 format contract, schemas
 and public validator

External authors had no path to the Plugin package format: the contract,
the four JSON Schemas, the reference vectors and the validator all lived in
the internal marketplace repository, and the only onboarding tool
(plugin-creator) is private.

This publishes the contract into the public repository:

- docs/plugins/package-format-v1.md, host-bindings.md, showcases.md
- schemas/plugins/{plugin,mcp,app,host-binding,marketplace}-v1.schema.json
- test-vectors/plugins/content-digest-v1.{source,expected}.json
- tools/plugins/validate-plugin.mjs

The public validator runs the same code path an external author runs, and
check:source now calls it, so the published schemas and the validator cannot
drift apart. It uses only dependencies the repository already declares.

Catalog membership, cross-file capability closure, archive limits and
content_digest remain the responsibility of the official Marketplace
validator at submission time.
---
 docs/plugins/host-bindings.md                 | 147 +++++
 docs/plugins/package-format-v1.md             | 323 ++++++++++
 docs/plugins/showcases.md                     |  80 +++
 schemas/plugins/app-v1.schema.json            |  25 +
 schemas/plugins/host-binding-v1.schema.json   |  74 +++
 schemas/plugins/marketplace-v1.schema.json    |  64 ++
 schemas/plugins/mcp-v1.schema.json            | 148 +++++
 schemas/plugins/plugin-v1.schema.json         | 172 ++++++
 scripts/source-inventory.mjs                  |   9 +
 .../plugins/content-digest-v1.expected.json   | 165 +++++
 .../plugins/content-digest-v1.source.json     | 414 +++++++++++++
 tools/plugins/validate-plugin.mjs             | 562 ++++++++++++++++++
 12 files changed, 2183 insertions(+)
 create mode 100644 docs/plugins/host-bindings.md
 create mode 100644 docs/plugins/package-format-v1.md
 create mode 100644 docs/plugins/showcases.md
 create mode 100644 schemas/plugins/app-v1.schema.json
 create mode 100644 schemas/plugins/host-binding-v1.schema.json
 create mode 100644 schemas/plugins/marketplace-v1.schema.json
 create mode 100644 schemas/plugins/mcp-v1.schema.json
 create mode 100644 schemas/plugins/plugin-v1.schema.json
 create mode 100644 test-vectors/plugins/content-digest-v1.expected.json
 create mode 100644 test-vectors/plugins/content-digest-v1.source.json
 create mode 100644 tools/plugins/validate-plugin.mjs

diff --git a/docs/plugins/host-bindings.md b/docs/plugins/host-bindings.md
new file mode 100644
index 000000000..1e2a27058
--- /dev/null
+++ b/docs/plugins/host-bindings.md
@@ -0,0 +1,147 @@
+# MiniMax Plugin V1 — 可选 Host Binding 扩展
+
+Host Binding 是 manifest V1 的可选属性，不需要另起一版包格式。V1 的路径、archive、digest、App、
+MCP、Skill 和 Hook 契约保持不变；未声明该属性的普通插件行为不变。
+这里的 V1 指插件包格式，与 Desktop 使用的 Local Runtime V2 不是同一个版本概念。
+国内外 Marketplace 使用同一扩展契约；某个区域支持此格式，不代表其 catalog 已上架 Browser Use。
+
+## 1. 适用范围
+
+Host Binding 让官方 Plugin 声明“希望复用 Desktop Host 已提供的一项原生能力”。它只描述依赖和
+映射请求，不包含能力实现，不启动额外进程，也不自动绕过 Host 的版本、surface、来源和安全策略。
+
+新包统一使用 `schemaVersion: 1` 和 `plugin-v1.schema.json`，包括 Browser Use。
+根 `.minimax-plugin/marketplace.json` 同样仍使用 catalog schema v1。
+Marketplace validator 和 Publisher 仅接受 manifest V1，不转换或接收 V2。已发布 V2 包由
+Desktop reader 保留读取兼容，不改写旧包或 digest；不维护独立 V2 schema。
+
+## 2. 包结构
+
+```text
+plugins/<plugin-name>/
+  .minimax-plugin/plugin.json
+  bindings/<binding-name>.binding.json
+  skills/<skill-name>/SKILL.md
+  <icon>
+```
+
+V1 manifest 继续显式列出 `apps`、`mcpServers`、`skills`，并允许可选数组 `hostBindings`。
+省略或空数组都表示不声明 Host Binding；使用该能力时填入 Binding 文件引用。Binding
+路径必须匹配 `bindings/<name>.binding.json`，同一引用不能重复。未被 manifest 引用的 Binding
+文件按 capability closure 规则拒绝。
+
+## 3. Binding V1
+
+Binding 文件遵循 [`host-binding-v1.schema.json`](../../schemas/plugins/host-binding-v1.schema.json)：
+
+```json
+{
+  "schemaVersion": 1,
+  "bindingId": "browser-control",
+  "logicalToolName": "browser.control",
+  "hostCapability": { "id": "browser.use", "version": 1 },
+  "requiredSkills": ["control-in-app-browser"],
+  "allowedSurfaces": ["interactive"]
+}
+```
+
+- `bindingId`：包内稳定且唯一的 Binding 标识；运行时据此生成不透明、稳定的
+  `plugin:<plugin-name>:<bindingId>` 引用。
+- `logicalToolName`：包内的逻辑能力名，只在包内判重；是否曝光为模型工具及其名称由 Host 的
+  capability 准入与映射决定，不直接使用这个字段作为模型 `tools[]` 中的工具名。
+- `hostCapability`：Host 契约的 id 与整数版本；是否存在匹配 Adapter 由 Host 决定。
+- `requiredSkills`：必须精确引用同一 manifest 已声明的 Skill name，区分大小写。为兼容 Desktop
+  reader，Binding V1 限制为小写字母开头的 `[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*` 完整标识，
+  最多 128 字符。普通 Skill 的 portable path 名称范围更宽，因此合法的 `Writer` 等名称不能
+  被 Binding V1 引用。不要自动重命名既有 Skill；放宽范围需与 Desktop reader 协同迁移。
+  Binding 只有在这些 Skill 对当前 Turn 可用时才能解析。
+- `allowedSurfaces`：V1 只允许 `interactive`，Task child、CLI 和其他 surface 默认 fail closed。
+
+同一包的 `bindingId` 和 `logicalToolName` 分别唯一。未知字段、未知 surface、缺失 Skill、重复值、
+非官方来源由 Desktop reader 拒绝；Marketplace Validator 校验 Binding 结构和包内闭包，Desktop Host
+再拒绝不受支持的 capability/version/surface。
+
+## 4. Browser 能力如何被调用
+
+Browser Use 通过 Host Binding 复用宿主已有的 compact `browser` 集合工具，不携带另一套浏览器
+实现。插件启用且 Binding 获准后，Host 以插件入口 `mcp_browser` 将它及当前 schema 放入模型
+`tools[]`，模型按 `mcp_browser({action, input})` 调用。
+
+这里的 `mcp_browser` 是插件声明、Host 托管的工具名，不代表新增标准 MCP Server。
+BU manifest 的 `mcpServers` 保持空数组；调用继续复用 Host 的会话上下文、安全检查和内部
+RPC → Electron 链路，不新增进程、端口或浏览器实例。
+
+```text
+Browser Use 插件启用，Host 接纳 Binding 并曝光 mcp_browser
+  → 模型完整读取 BU Skill（按 Skill 的 Session 规则复用有效加载）
+  → 模型直接调用 mcp_browser({action, input})
+  → Host 针对 Browser 工具执行安全检查
+  → Browser 工具执行动作，结果返回模型
+```
+
+### 4.1 Host 返回什么，模型如何使用
+
+Browser 的动作与参数以当前 `mcp_browser` 工具 schema 为准，参数直接传递 `{action, input}` 对象，
+其中数组、布尔值和数字保持原生 JSON 类型。BU Skill 的读取结果不再另附全量
+`Host tool contracts`，也不需要模型查找或拼接 `tool_ref`，或通过 `mcp_invoke` /
+`arguments_json` 包装 Browser 调用。
+
+Skill 文件继续维护完整工作流、安全规则和代表性示例，不重复维护完整 schema。模型必须遵循
+BU Skill 的完整加载、Session 隔离和重新加载规则；工具可见不替代 Skill 加载要求。
+缺少 `mcp_browser` 工具/schema 时停止并提示检查客户端或插件，不能通过试调用猜测参数。
+
+这项直接曝光只适用于 `browser.use`。其他 Host Binding 仍可通过 `mcp_invoke` gateway 及
+Host 返回的 `tool_ref`、`arguments_schema`、`arguments_transport` 调用；使用
+`arguments_json` 时仍须按该契约传递 JSON 字符串。`mcp_invoke` 不是独立网络服务或 MCP Server，
+本次没有移除其他 Binding 的 gateway 路径。
+
+### 4.2 工具列表与缓存有什么变化
+
+Browser Use 的插件状态与 Host 准入结果决定 `mcp_browser` 是否进入当前模型的顶层工具列表
+`tools[]`，其 schema 来自实际 Browser 执行契约。其他仍走 gateway 的 Binding 不因此全部直出。
+
+Browser 的接入或退出会改变顶层工具定义；Skill 清单和工具返回内容也会改变模型上下文，
+不能据此保证整个提示词缓存（prompt cache）始终命中。
+
+## 5. 每次调用仍需通过安全检查
+
+调用入口可用、工具可见或插件已安装，都不等于当前 Browser 动作已获授权。
+
+- Host 必须针对真实目标工具名和真实参数执行 PreToolUse、产品策略、权限检查及调用来源记录
+  （provenance），再调用 Host Adapter。直接调用 `mcp_browser` 不绕过这些检查。
+- Browser 的可信能力身份来自 Host 核准的 Binding，不来自工具名称或 `mcp_` 前缀；不能因第三方
+  工具同名就信任其结果。认证接管后的强制 `ask_user` 门禁仍须覆盖真实 BU 调用。
+- 其他 Binding 经 gateway 解析引用后同样检查真实目标，不能把 `mcp_invoke` 入口已通过检查
+  当作目标工具也已获准。未知引用应返回失败，不能在错误信息中列出内部注册表的其他工具。
+- 插件声明的能力随插件整体启用；Host 仍可因产品策略、版本不匹配、surface 不允许、能力不可用
+  或安全规则拒绝调用。这是每次调用的准入检查，不是给 Plugin 另设第二个启用开关。
+
+## 6. 兼容与发布顺序
+
+BU 的直接调用版本须与对应 Runtime 更新协调发布：先让 Desktop 客户端支持新契约，再发布
+依赖该契约的插件；不能让用户先收到无法调用的包。
+
+1. Desktop 先支持 manifest V1 的可选 `hostBindings`、历史 manifest V2 读取兼容和 Binding V1，
+   并具备 `browser.use` 准入后的 `mcp_browser` 直接曝光、当前 schema、Skill 读取门禁及真实目标安全检查；
+   其他 Binding 的 gateway 契约保持不变。
+2. Marketplace 合入 schema、validator、Publisher dry-run 与 Browser Use 包，并先发布 `dev` 测试目录。
+3. 验证 BU 准入时顶层工具列表包含 `mcp_browser`，直接动作可执行且 Skill 不再附加全量契约；
+   未安装、禁用、Skill 未完整读取或不允许的 surface 必须拒绝调用。其他 Binding 的 gateway
+   仍可调用，未知引用仍须拒绝。
+4. 对已经开启旧 Browser Use 模式的用户执行一次性默认安装迁移。
+5. 测试环境验收后，只把本次相关提交从最新 `main` 生产分支带入生产 MR。
+
+不认识 `hostBindings` 的旧 Desktop 仍会拒绝新字段；不支持 `mcp_browser` 直接曝光的客户端，
+不能先接收依赖它的插件版本。新 BU Skill 不提供老客户端的猜测式回退。发布新内容必须升级
+包版本，不覆盖已发布内容。
+
+历史记录：Browser Use 从 1.0.1 升级到 1.0.2 时改用扩展后的 manifest V1。这是格式迁移记录，
+不是当前版本声明；各区域是否上架及当前版本，以该区域 catalog 和对应 manifest 为准。
+
+## Computer Use
+
+`computer-use` 声明 `computer.use@1`，仅分发到 Desktop，由用户安装和管理。
+Binding 要求包内 `computer-use` Skill，运行时名称为 `computer-use:computer-use`。
+Desktop 保留现有 `computer_*` 工具名称，仅在交互会话显式选择电脑操控、插件启用且权限检查通过后开放。
+插件包提供元数据、图标和操作说明；原生驱动、系统授权、预览与停止控制仍由 App 实现。
+需配合支持该 capability 的 Desktop 发布；旧版本无法仅通过安装包获得原生能力。
diff --git a/docs/plugins/package-format-v1.md b/docs/plugins/package-format-v1.md
new file mode 100644
index 000000000..60f40f3dc
--- /dev/null
+++ b/docs/plugins/package-format-v1.md
@@ -0,0 +1,323 @@
+# MiniMax Plugin Package Format V1
+
+本文定义官方 MiniMax Plugin V1 的仓库结构、manifest 引用、archive 安全边界和 digest
+算法。Publisher、Desktop 与 cloud-runtime 均以本文和仓库内 checked-in vectors 为准。
+
+## 1. 仓库与包边界
+
+Marketplace 仓库结构：
+
+```text
+.minimax-plugin/marketplace.json
+plugins/<plugin-name>/
+  .minimax-plugin/plugin.json
+  <icon>
+  *.app.json
+  *.mcp.json
+  skills/<skill-name>/SKILL.md
+  hooks/hooks.json
+  bindings/<binding-name>.binding.json
+  <其他被能力文件引用的普通文件>
+```
+
+`.minimax-plugin/marketplace.json` 使用
+[`marketplace-v1.schema.json`](../../schemas/plugins/marketplace-v1.schema.json)，显式列出当前目录中的
+Plugin name、repository-root-relative path、端分发范围和安装策略。每项必填 `deliveryTargets`，
+只允许 `desktop`、`cloud` 中的 1～2 个不重复值；可选 `installationPolicy` 只允许
+`USER_MANAGED` 或 `DEFAULT_INSTALLED_UNREMOVABLE`，省略时按 `USER_MANAGED` 处理。后者表示该
+官方 Plugin 对所有用户默认安装且不可卸载，但仍允许用户停用和重新启用；策略作用于 entry 的
+全部 `deliveryTargets`。`plugins` 数组表示插件池快照，校验和发布过程仍原样保留顺序，
+以维持既有发布摘要和幂等契约。环境完成 Registry 运营策略迁移后，市场展示顺序与上下架
+以管理后台为唯一来源；Git 重排不改变运营顺序，新名称默认上架，已有运营状态保留。
+删除仍上架名称会拒绝整次发布，需先后台下架。端分发、安装策略和池数组顺序属于 catalog
+元数据，不进入 package 的 content digest。
+
+每个 `plugins/<plugin-name>/` 是一个独立 package root：
+
+- archive 根目录直接包含 `.minimax-plugin/plugin.json`，不得再套一层 Plugin 目录；
+- `content_digest` 只覆盖该 package root 的完整文件树，不包含仓库级 marketplace.json；
+- manifest 的所有路径均相对 package root，使用 `/`，不得相对 manifest 自身解析；
+- 未被 manifest 引用的普通文件仍属于包，也必须进入 digest 和安全上限统计；
+- Plugin name 必须与 marketplace entry、package 目录名和 manifest `name` 完全一致。该闭合校验
+  由 Marketplace validator 实现。
+
+## 2. Manifest 与能力文件
+
+> **生产兼容门禁（2026-09-05）**：下面保留 V1 的 `darkIcon` 字段定义，但当前 `main`
+> 的 validator 禁止 manifest 携带该字段（包括空值、`null`），统一使用默认 `icon`。
+> 不要把深色图标资源及其元数据加入生产包。失败码为 `DARK_ICON_TEMPORARILY_DISABLED`，
+> Publisher 构建、dry-run 与 CI 都会执行该校验。`dev` 不受本次修改影响。
+> 待发布 owner 确认大部分生产用户升级到支持该字段的 Desktop 后，通过独立 MR 同步
+> 解除 validator、测试、文档和 `plugin-creator` 的限制，不能用新版本已发布代替覆盖率确认。
+
+官方 manifest 使用
+[`plugin-v1.schema.json`](../../schemas/plugins/plugin-v1.schema.json)。V1 包含 App、MCP、Skill、
+同步 command Hook，以及可选 Host Binding：
+
+- `apps`：引用一个或多个 `*.app.json`，每个文件遵循
+  [`app-v1.schema.json`](../../schemas/plugins/app-v1.schema.json)，只保存 Connector `provider`。provider
+  命名直接复用 Connector catalog 的 `[a-z0-9_-]{1,64}` 完整字符串规则，不允许尾随换行或控制字符；
+- `mcpServers`：引用一个或多个 `*.mcp.json`，每个文件遵循
+  [`mcp-v1.schema.json`](../../schemas/plugins/mcp-v1.schema.json)，文件内使用
+  `{ "schemaVersion": 1, "mcpServers": { "<name>": <config> } }`；
+- `skills`：引用 `skills/<skill-name>/SKILL.md`。正文必须是 UTF-8、无 BOM，并以 YAML
+  frontmatter 开始；frontmatter 至少包含与目录一致的 `name` 和非空 `description`；
+- 可选 `hooks`：引用一个或多个 package-relative JSON 文件。文件顶层使用
+  `{"hooks":{"<Event>":[{"matcher":"...","hooks":[...]}]}}`。第三版只统计并执行
+  `type=command` 且未声明 `async=true` 的 handler；单包最多 64 个可执行 handler，
+  单 handler `timeout` 为 1～10 秒。`args`、`shell`、`if`、`asyncRewake` 等兼容扩展字段会使
+  当前 handler 被跳过且不计入 `hookCount`，也不再校验其 command 路径、timeout 或 Windows
+  override。对于接纳执行的同步 command handler，显式的 `timeout`、`commandWindows` 必须
+  为合法值。其他未知 handler 字段被忽略，不改变执行行为或计数；创建时不要依赖这些字段。
+  异步 command 与其他 handler 类型不会使同包的
+  App、MCP、Skill 或合法 Hook 失效。`matcher` 推荐使用精确名称或 `|` 分隔的精确
+  alternatives（也接受逗号分隔）；matcher 总长度不超过 256。`UserPromptSubmit` 和 `Stop`
+  在非空字符串与长度检查后忽略 matcher 内容，建议省略；其他事件不接受正则 matcher。
+  工具 matcher 大小写敏感，必须使用 MiniMax 原生名称（`bash`、`read`、`write`、`edit`、
+  `task`），不能使用兼容层别名（`Bash`、`Read`、`Write`、`Edit`、`Agent`）。`*` 表示显式
+  匹配全部。
+
+可选 `hostBindings` 引用 `bindings/<name>.binding.json`；省略或 `[]` 表示不声明 Host 能力。
+声明后仍严格检查路径、重复引用、Binding 结构和必需 Skill 的包内引用；未知字段仍拒绝。
+该扩展不要求改变 manifest 的 `schemaVersion: 1`。旧客户端需升级才可消费新增属性；
+Marketplace 校验和发布仅接受 V1；已发布 manifest V2 包仅由 Desktop reader 保留读取兼容。
+详见 [Host Binding 扩展](host-bindings.md)。
+
+Hook command 的 cwd 是当前 turn workspace，不是 Plugin package。Runtime 会提供
+`PLUGIN_ROOT`（以及兼容格式对应的 root 变量）；包内脚本必须使用显式解释器并从该根引用，
+例如 `bash "$PLUGIN_ROOT/scripts/cleanup.sh"`。官方 archive 不保留 executable bit，validator
+会拒绝直接执行 `.sh`、`bash ./scripts/...` 和不存在的 `$PLUGIN_ROOT` 文件引用。
+可静态识别的宿主脚本路径（POSIX 绝对路径、Windows drive/UNC、`~` 开头的用户目录路径）均拒绝。
+Windows override 使用规范字段 `commandWindows`，由 Windows 默认 shell 执行。Runtime 在启动
+shell 前展开 `${PLUGIN_ROOT}`，两端均可使用；Windows 也接受 `%PLUGIN_ROOT%`，但不接受
+裸 `$PLUGIN_ROOT`。Node 脚本可使用
+`node "%PLUGIN_ROOT%\scripts\hook.mjs"`；包内 PowerShell 脚本应使用
+`powershell -File %PLUGIN_ROOT%\scripts\cleanup.ps1`（或 `pwsh`），并接受同样的文件闭包校验。
+validator 只做静态解释器和路径校验，不保证运行环境一定安装 `node` 等外部解释器。
+
+`plugin.json` 的 `category` 必须是以下展示字符串之一：
+
+```text
+Office
+Studio
+Design & Sites
+Code
+Business
+Sales
+Productivity
+Science & Healthcare
+Education
+Other
+```
+
+`version` 必须是完整 SemVer，不能带尾随换行。所有 schema 中的标识与路径正则均要求完整
+匹配；JSON Schema 的正则使用显式字符串结束断言，避免 `$` 接受末尾换行。
+
+`exampleQueries` 是字符串数组，允许空数组、最多 3 项、每项最多 4,096 个字符；
+每个实际元素 trim 后必须
+非空。可选的 `displayName` 和必填的 `author` 在 trim 后都必须非空，且分别不得超过 1,024
+UTF-8 bytes。创建技能推荐填写展示名及 1～3 条有意义的示例问题，这是内容质量建议，
+不改变 V1 的可选字段与空数组兼容性；不要为通过检查而编造内容。JSON Schema 的 `maxLength` 提供字符数预检，
+Marketplace validator 负责精确的
+UTF-8 字节校验，确保上传 OSS 前即可满足 Registry 字段约束。单个 Plugin 最多引用 256 个
+App。Publisher 与 Registry 还会按 PolarDB `mediumtext`
+实际容量校验 `example_queries` / `app_providers` 的紧凑 UTF-8 JSON 字节数。官方 `icon` 必填，
+表示默认/浅色 Logo；可选 `darkIcon` 表示深色 Logo。两者都只允许 PNG、JPEG 或 WebP，并接受
+相同的路径、真实字节、符号链接和归档闭包校验。图标必须通过 Pillow 的格式识别、
+完整性验证与像素解码（动画图片检查所有帧），解码格式必须匹配扩展名；
+截断文件或仅有文件头的文件会被拒绝。
+保留 Pillow 的解压炸弹保护，相关警告按失败处理，不在校验过程中重写图标。
+缺少 `darkIcon` 时客户端回退 `icon`。App 的
+名称与图标不写入包，由 BFF 使用 Connector catalog 的权威元数据填充。
+
+MCP V1 只允许：
+
+- `type: "stdio"`：必须提供 `command`；`command` 必须是 PATH 中的解释器/可执行名，不得
+  包含 `/` 或 `\\`。参数不得使用 POSIX、Windows drive 或 UNC 绝对路径；包内脚本通过参数
+  中的显式相对路径引用，由运行时解析到 package root；
+- `type: "streamable-http"`：必须提供 `url`；
+- `type: "sse"`：必须提供 `url`。
+
+官方包不接受 `type: "http"` alias、`auth`、OAuth 或 refresh 字段。Desktop 的 Claude Code
+兼容 reader 可以接受的额外输入不属于官方 schema。
+
+所有 JSON 文件均为 UTF-8、无 BOM 的 JSON object。JSON 空白与 key 顺序不会被运行时重新
+canonicalize；它们是普通文件字节，改变后会改变 `content_digest`。
+
+V1 每个 `name+version` 只有一个 universal package，不存在 OS/arch variant、安装脚本或
+post-install step。包不能依赖 symlink、源 checkout executable bit 或平台专属 native binary；
+需要脚本时应由已声明的跨平台解释器显式启动。P1B validator 负责对可静态识别的违规内容
+fail closed。
+
+## 3. Universal path contract
+
+V1 为了在 Windows、macOS 和 Linux 上得到同一文件树，只接受 portable ASCII path：
+
+- archive entry 和 manifest reference 必须是相对 POSIX path；
+- segment 只允许 `[A-Za-z0-9._-]+`，`.` 和 `..` segment 禁止；
+- 禁止绝对路径、盘符、UNC、反斜杠、空 segment、NUL 和控制字符；regular file entry
+  与 manifest reference 禁止尾随 `/`。ZIP directory entry 如存在，必须以且仅以一个 `/`
+  结尾，reader 去掉该结尾后按同一规则验证；
+- 每个 segment 最多 128 bytes，完整 path 最多 512 bytes，最多 16 个 segment；
+- Windows reserved basename（`CON`、`PRN`、`AUX`、`NUL`、`COM1`…`COM9`、
+  `LPT1`…`LPT9`，包括带扩展名形式）禁止；
+- exact duplicate、ASCII case-insensitive collision，以及 file/parent 类型冲突均拒绝；
+- symlink、hardlink、device、FIFO、socket 和其他非普通文件 entry 均拒绝。
+
+文件内容可以是任意 bytes；要求文本格式的文件再由对应 schema/validator 校验 UTF-8。因此
+中文等 Unicode 内容合法，但 V1 文件名只使用 portable ASCII。未来如需 Unicode path，必须
+新增 digest/path contract 版本，不能修改 V1。
+
+## 4. 固定安全上限
+
+Publisher 与两个运行时必须在写入目标目录前执行同一组 fail-closed 检查：
+
+| 项目 | V1 上限 |
+| --- | ---: |
+| archive 原始字节 | 64 MiB |
+| archive entries（含目录） | 2,048 |
+| regular files | 1,024 |
+| 单文件解包后字节 | 16 MiB |
+| 全部 regular files 解包后总字节 | 64 MiB |
+| path bytes | 512 |
+| segment bytes | 128 |
+| path segments | 16 |
+
+V1 archive 是无 wrapper directory 的 ZIP，且只允许 `STORE`（method 0）：
+
+- 不允许 encryption、data descriptor、ZIP64、multi-disk、archive/entry comment 或 extra field；
+- directory entry 必须是零字节 `STORE` entry，且不进入 digest；Publisher 的确定性 archive
+  不输出 directory entry；
+- `STORE` 使 declared compressed size 必须等于 uncompressed size，从格式上消除压缩炸弹；
+- reader 仍须同时验证 archive 大小、entry 数、单文件和累计实际写入字节，不能只信 central directory；
+- 校验与解包写入临时目录；全部成功并通过 `content_digest` 后才可原子发布。
+
+## 5. `content_digest`
+
+V1 输出格式：
+
+```text
+sha256-tree-v1:<64 lowercase hex>
+```
+
+输入是经过第 3、4 节校验后的所有 regular files。directory、mode、mtime、uid/gid 和 archive
+entry 顺序不参与 digest；空目录因此不影响结果。文件内容按原始 bytes 参与。
+
+算法：
+
+1. 将 relative path 编码为 ASCII bytes，按 path bytes 升序排列。
+2. 初始化 SHA-256，并按顺序写入：
+
+```text
+ASCII "MINIMAX-PLUGIN-CONTENT-DIGEST" + 0x00
+uint32_be(1)                         # contract version
+uint32_be(file_count)
+for each file:
+  byte 0x46                          # "F"
+  uint32_be(path_byte_length)
+  path_bytes
+  uint64_be(content_byte_length)
+  content_bytes
+```
+
+3. 将 SHA-256 小写 hex 加上 `sha256-tree-v1:` 前缀。
+
+长度字段使 path/content 边界无歧义。实现必须以 streaming 方式更新 hash，并在读文件过程中
+再次执行累计字节上限。
+
+## 6. Deterministic archive 与 `archive_sha256`
+
+Publisher 按以下 V1 规则构建 ZIP：
+
+- regular files 按 relative path bytes 升序；
+- 只写 file entry，compression method 固定为 `STORE`；
+- `version made by` 固定为 Unix 2.0（OS=3、version=20），`version needed to extract`
+  固定为 1.0（10）；
+- DOS timestamp 固定为 `1980-01-01 00:00:00`；
+- internal attributes 固定为 0；external attributes 固定为 Unix regular file `0100644`
+  左移 16 位，不依赖源 checkout mode；
+- path 均为 ASCII，因此 general-purpose bit flag 固定为 0；extra field、entry comment 和
+  archive comment 均为空；
+- archive root 直接是 package root。
+
+`archive_sha256` 是最终 ZIP 完整原始字节的 SHA-256 小写 64 位 hex，不带前缀。运行时只需先
+验证实际下载 bytes，无需重新构造 ZIP。`archive_sha256` 通过后仍必须执行 entry 安全校验与
+`content_digest`，两者不能互相替代。
+
+## 7. Reference vectors
+
+[`content-digest-v1.source.json`](../../test-vectors/plugins/content-digest-v1.source.json) 使用与真实文件树
+等价的虚拟 entry 描述合法和拒绝场景；生成结果固定在
+[`content-digest-v1.expected.json`](../../test-vectors/plugins/content-digest-v1.expected.json)。
+
+vector 中的 `valid` 只表示 path/archive/digest contract 接受该虚拟文件树，不表示它已经通过
+Plugin manifest、Skill frontmatter、App/MCP schema 等 P1B 语义校验。例如 empty tree 具有
+定义明确的 tree digest，但不是可发布的官方 Plugin。
+
+合法 vectors 覆盖空树、排序、空目录、mode/mtime 忽略、空文件和 UTF-8 内容；拒绝 vectors
+覆盖 traversal、反斜杠、Unicode path、大小写/重复冲突、Windows reserved name、symlink、
+特殊文件、STORE 之外的压缩方式以及单文件/累计大小边界。
+
+任何语言的实现均应直接读取 checked-in expected vectors 做测试。只有在有意新增 contract
+版本或补充不改变语义的场景时，才运行 generator 并 review expected diff。
+
+## 8. 官方 Marketplace validator
+
+`tools/validate_marketplace.py` 对仓库当前目录做一次完整、fail-closed 的校验，并输出供后续
+Publisher 消费的确定性投影。它直接复用本规范第 3～6 节的 reference implementation，不定义
+第二套 path、digest 或 archive 规则。
+
+除 JSON Schema 外，validator 还执行以下跨文件语义：
+
+- marketplace entry、`plugins/<name>` 目录和 manifest name 必须闭合；目录不能漏列，所有
+  manifest 引用必须存在，能力形态文件不能存在未引用副本；
+- JSON 必须是 UTF-8、无 BOM、无重复 key、无非标准数字的 object；Skill 使用安全 YAML
+  loader，frontmatter 无重复 key，`name` 与目录一致且 `description` 非空；
+- 当前 catalog 内 Plugin name 使用 NFKC + case-fold 后不得冲突；MCP server name 只在
+  同一 Plugin 内按该规则判重，包括分散在多个 MCP 文件中的声明。不同 Plugin 可以声明同名
+  MCP server 及同名 tool，运行时按 Plugin 身份区分并分配不冲突的名称。静态声明的 MCP tool
+  在同一 Plugin 内按 `mcp__<server>__<tool>` 的 normalize/truncate 规则检查冲突；动态 tool
+  由运行时分配名称。同一 Plugin 内的 Skill name 使用 NFKC + case-fold 判重，不同 Plugin
+  可以声明同名 Skill，运行时名称固定为 `<plugin-name>:<skill-name>`；
+- 同一 Plugin 不能重复引用同一 Connector provider；官方 MCP 仅接受 `stdio`、
+  `streamable-http`、`sse`，JSON Schema 的封闭字段同时拒绝 `http` alias、OAuth/auth/refresh
+  等声明；
+- 可静态识别的 native binary 后缀和 `package.json` 的 `preinstall/install/postinstall` 生命周期
+  脚本被拒绝。checkout executable bit 不进入 archive，stdio 只能通过 PATH interpreter 启动；
+  Markdown shell 代码块中由 validator 可静态识别的 simple command、subshell 或 command
+  substitution 若以 `.sh` 作为 command word（包括经 `env`、`command`、`sudo` 等 wrapper
+  执行），必须显式使用 `bash`/`sh`/`zsh` 等解释器；
+- 投影包含 manifest 元数据、App provider、每个 MCP server 的 canonical `transport` 与稳定
+  compact/sorted `configJson`、每个 Skill 的完整 UTF-8 `SKILL.md` 正文，以及 package 的两个
+  digest 和大小统计。`configJson` 的格式仅用于确定性传输，package digest 始终以原文件
+  bytes 为准。
+
+仓库根 catalog 与 `tests/fixtures/four-types` 中的 App-only、MCP-only、Skill-only、组合 Plugin
+都在 CI 中执行 validator。fixture 不进入用户可见 catalog，也不会被正式 Publisher 发布。
+
+## 9. Publisher 与部署边界
+
+`tools/publish_marketplace.py` 只消费第 8 节完整校验成功后的投影，并重新构建第 6 节 archive；
+两次计算的 SHA/size 不一致时拒绝发布。固定对象 key 为：
+
+```text
+plugin-marketplace/v1/packages/<name>/<version>/<archive_sha256>.zip
+plugin-marketplace/v1/icons/<name>/<version>/<icon_sha256>.<ext>
+```
+
+默认与深色 Logo 都使用第二种按内容寻址的 key；内容不同自然得到不同 key。包写入 deployment
+私有 package bucket，Logo 写入可匿名读取的 static bucket。Registry 的 `data_oss_key` 保存前者
+key，`icon_url` / `dark_icon_url` 由该 deployment 的固定 HTTPS public base URL 与对应 Logo
+逻辑 key 组成；`dark_icon_url` 缺失时消费端使用 `icon_url`。CN static bucket 的物理 key 在逻辑
+key 前增加 `cdn-yingshi-ai-com/`，该前缀由
+CDN 回源映射隐去，不进入 `icon_url`；US 物理 key 与逻辑 key 相同。两个 bucket 都使用 OSS
+forbid-overwrite；同一物理 key 已存在时必须读取并验证 SHA 与大小，内容不同即拒绝，不能覆盖。
+
+一个 deployment 的全部 package/icon 上传成功后，Publisher 才向受鉴权 Publisher Relay 的
+固定环境 target 提交一次完整 catalog；Relay 通过生成代码的 typed Kitex client 发起无用户
+`BaseReq` 的 `PublishPluginCatalog`。请求携带固定 `source_commit`，不携带 RPC 地址或泳道。
+完整 catalog 的紧凑 JSON 请求体上限统一为 64 MiB；Publisher 必须在上传任何 OSS 对象前
+完成全部目标 deployment 的大小预检，Relay 与 Ingress 也使用相同上限。
+catalog 原子校验/登记/切换由 Registry 事务负责。CN 和 US 使用各自 bucket、public icon base
+与固定 Relay target 并独立记录结果；单边失败不回滚成功侧，整体发布仍返回失败。同
+commit+同内容重试由不可变 OSS 对象与 Registry `unchanged` 响应共同保证幂等。
diff --git a/docs/plugins/showcases.md b/docs/plugins/showcases.md
new file mode 100644
index 000000000..94435eed2
--- /dev/null
+++ b/docs/plugins/showcases.md
@@ -0,0 +1,80 @@
+# 插件详情 Showcase
+
+每个插件可添加 `.minimax-plugin/showcases.json` 和 `showcase/` 原始媒体文件。
+配置属于插件包版本；增加、修改、排序、清空、删除配置或更换素材都必须升级
+`.minimax-plugin/plugin.json` 的 `version`。manifest schema v1 和 `exampleQueries` 保持原契约。
+两区仓库分别维护当地语言文案，不增加语言字段，也不通过管理后台修改 Showcase。
+
+```json
+{
+  "schemaVersion": 1,
+  "items": [
+    {"id": "copy", "text": "撰写产品介绍", "query": "请为这款产品撰写完整的介绍文案"},
+    {"id": "image", "text": "生成宣传图", "query": "请生成一张产品宣传图",
+     "media": {"type": "image", "path": "showcase/product.webp", "alt": "产品宣传图"}},
+    {"id": "video", "text": "制作展示视频", "query": "请制作一段产品展示视频",
+     "media": {"type": "video", "path": "showcase/product.mp4", "posterPath": "showcase/poster.webp"}}
+  ]
+}
+```
+
+`items` 顺序就是展示顺序。纯文字最多 3 项；有媒体时最多 10 项，可混入文字项。
+每项一个 `id`、展示 `text`、完整 `query`，可选一份 `media`。点击案例使用详情所属插件和
+完整提示词；媒体只用于展示，不作为输入附件。`id` 为插件内唯一、1–64 位 ASCII
+字母、数字、`_`、`-`，修改文案时保留原 ID。`text`、`query` 必须非空，分别最多 4096
+Unicode code points；可选 `alt` 最多 512 code points。短文案建议中文不超过 22 字、
+英文不超过 12 词；经设计确认的专业术语案例可放宽到 28 字或 15 词。这些是编辑建议。
+
+配置只接受以上字段，JSON 禁止重复键，`schemaVersion` 必须为整数 1。原始配置文件与
+紧凑的发布 JSON 各自最多 256 KiB。`items: null` 非法；缺失文件与空数组有不同含义：
+
+- 不放配置文件：详情继续使用旧 `exampleQueries`。
+- `{"schemaVersion":1,"items":[]}`：新客户端隐藏 Showcase；若要旧客户端同时隐藏，
+  还需将 manifest 的 `exampleQueries` 设为 `[]`。
+
+媒体路径相对于插件根目录，必须是 `showcase/` 下非空普通文件，并遵守既有 portable path
+规则；禁止 URL、绝对路径、`..`、符号链接和特殊文件。图片和视频封面仅支持 PNG、JPEG、
+WebP，扩展名必须符合实际格式。视频仅支持 MP4/H.264，带音轨时须为 AAC，每条视频必须
+配置 `posterPath`。校验使用固定版本 PyAV 从内存字节检查格式、编码和可解码帧，不转码，
+不依赖系统安装的 `ffmpeg` 命令。全部文件继续遵守单文件 16 MiB、总文件大小 64 MiB、
+最终 ZIP 64 MiB，以及既有文件数和路径限制。
+
+## 打包与发布
+
+配置和媒体以原始路径和字节进入 ZIP、`content_digest` 和 `archive_sha256`，没有忽略规则。
+同版本内容变化由 Registry 的版本不可变约束拒绝，不能以改远端 URL 绕过升级。
+Publisher 从打包使用的同一份 `package_entries` 准备媒体对象，复用 Logo 的 `icon_store`、
+凭证、bucket 和前缀。它将同版本相同字节的媒体去重，使用下面的不可变对象 key：
+
+```text
+<object_prefix>/showcases/<plugin_name>/<plugin_version>/<sha256>.<ext>
+```
+
+`object_prefix` 默认 `plugin-marketplace/v1`，JPEG 扩展名统一 `.jpg`。OSS 实际 key 前仍叠加
+当前部署的 `icon_object_prefix`；公开 URL 使用已有 `icon_base_url + object key`，不重复
+叠加物理前缀。媒体 URL 必须使用 HTTPS，最多 2048 UTF-8 bytes。
+
+所有区域请求先完成校验；每区的全部包、Logo 和 Showcase 上传成功后，才执行该区的一次
+Catalog 发布。某区媒体上传失败时不会切换该区目录，其他区域仍可独立执行；不删除已上传
+的不可变对象。`PublishPluginCatalogResp` 的 source_commit、plugin_count、unchanged 不变。
+
+`--dry-run` 不上传：`catalog-request.json` 中新增 `showcase_config`，其中 media.type 为
+IMAGE=1 / VIDEO=2，path/posterPath 转为正式 url/poster_url，移除 schemaVersion。
+`objects.json` 同时输出媒体文件、内容类型、hash、物理 key 和各区公开 URL；`showcases/`
+目录包含上传原始字节。没有配置的插件不新增该字段，旧发布请求保持兼容。
+
+先合入 IDL MR !13497 并等待 rpc_gen，完成 server、biz 和 Relay 的字段传递及版本存储后，
+再在测试环境发布带 Showcase 的新插件版本。上线仍按 README 的区域、测试/生产和审批
+流程执行，不能只升级 Publisher 就假设消费链路已经可用。
+
+## 校验
+
+```bash
+.venv/bin/python -m unittest tests.test_showcases tests.test_publisher -v
+.venv/bin/python tools/validate_marketplace.py
+.venv/bin/python tools/publish_marketplace.py --dry-run --source-commit <完整提交哈希> --output-dir dist/publisher-catalog
+```
+
+`tests/fixtures/showcase-media/` 是本地生成的 16×16 纯色合成素材，仅用于格式和编码测试。
+`h264-aac.mp4` 是合法样例，`mpeg4.mp4` 和 `h264-mp3.mp4` 是拒绝样例；这些素材不进入
+官方 catalog。格式校验不能代替正式素材的编辑检查、浏览器预览、CDN Range/CORS 和端到端验收。
diff --git a/schemas/plugins/app-v1.schema.json b/schemas/plugins/app-v1.schema.json
new file mode 100644
index 000000000..26b39944c
--- /dev/null
+++ b/schemas/plugins/app-v1.schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:minimax:plugin:app:v1",
+  "title": "MiniMax Plugin App Reference V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9_-]+(?![\\s\\S])"
+    }
+  }
+}
diff --git a/schemas/plugins/host-binding-v1.schema.json b/schemas/plugins/host-binding-v1.schema.json
new file mode 100644
index 000000000..e525031d4
--- /dev/null
+++ b/schemas/plugins/host-binding-v1.schema.json
@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:minimax:plugin:host-binding:v1",
+  "title": "MiniMax Official Plugin Host Binding V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "bindingId",
+    "logicalToolName",
+    "hostCapability",
+    "requiredSkills",
+    "allowedSurfaces"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "bindingId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+    },
+    "logicalToolName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+    },
+    "hostCapability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+        },
+        "version": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "requiredSkills": {
+      "description": "Exact names of declared Skills. Binding V1 retains the Desktop reader lowercase identifier restriction; ordinary Skill names have a wider portable-path alphabet.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128,
+        "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+      }
+    },
+    "allowedSurfaces": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "enum": ["interactive"]
+      }
+    }
+  }
+}
diff --git a/schemas/plugins/marketplace-v1.schema.json b/schemas/plugins/marketplace-v1.schema.json
new file mode 100644
index 000000000..90ed10d5c
--- /dev/null
+++ b/schemas/plugins/marketplace-v1.schema.json
@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:minimax:plugin:marketplace:v1",
+  "title": "MiniMax Plugin Marketplace V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "plugins"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "path",
+          "deliveryTargets"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 80,
+            "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+          },
+          "path": {
+            "type": "string",
+            "maxLength": 512,
+            "pattern": "^plugins/[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+          },
+          "deliveryTargets": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 2,
+            "uniqueItems": true,
+            "items": {
+              "enum": [
+                "desktop",
+                "cloud"
+              ]
+            }
+          },
+          "installationPolicy": {
+            "description": "Catalog-scoped installation ownership; omitted entries are USER_MANAGED.",
+            "default": "USER_MANAGED",
+            "enum": [
+              "USER_MANAGED",
+              "DEFAULT_INSTALLED_UNREMOVABLE"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/schemas/plugins/mcp-v1.schema.json b/schemas/plugins/mcp-v1.schema.json
new file mode 100644
index 000000000..b01571c3a
--- /dev/null
+++ b/schemas/plugins/mcp-v1.schema.json
@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:minimax:plugin:mcp:v1",
+  "title": "MiniMax Plugin MCP Servers V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "mcpServers"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "mcpServers": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])",
+        "maxLength": 80
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/server"
+      }
+    }
+  },
+  "$defs": {
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "timeout": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "stringMap": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "tool": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "pattern": "^[A-Za-z0-9_.-]+(?![\\s\\S])"
+        },
+        "description": {
+          "$ref": "#/$defs/description"
+        },
+        "inputSchema": {
+          "type": "object"
+        }
+      }
+    },
+    "server": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "type",
+            "command"
+          ],
+          "properties": {
+            "type": {
+              "const": "stdio"
+            },
+            "command": {
+              "type": "string",
+              "minLength": 1
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "env": {
+              "$ref": "#/$defs/stringMap"
+            },
+            "description": {
+              "$ref": "#/$defs/description"
+            },
+            "timeout": {
+              "$ref": "#/$defs/timeout"
+            },
+            "tools": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/tool"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "type",
+            "url"
+          ],
+          "properties": {
+            "type": {
+              "enum": [
+                "streamable-http",
+                "sse"
+              ]
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "minLength": 1,
+              "pattern": "^https?://"
+            },
+            "headers": {
+              "$ref": "#/$defs/stringMap"
+            },
+            "description": {
+              "$ref": "#/$defs/description"
+            },
+            "timeout": {
+              "$ref": "#/$defs/timeout"
+            },
+            "tools": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/tool"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/schemas/plugins/plugin-v1.schema.json b/schemas/plugins/plugin-v1.schema.json
new file mode 100644
index 000000000..688c5548d
--- /dev/null
+++ b/schemas/plugins/plugin-v1.schema.json
@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:minimax:plugin:manifest:v1",
+  "title": "MiniMax Official Plugin Manifest V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "name",
+    "version",
+    "description",
+    "author",
+    "icon",
+    "category",
+    "exampleQueries",
+    "apps",
+    "mcpServers",
+    "skills"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "pattern": "^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*(?![\\s\\S])"
+    },
+    "version": {
+      "type": "string",
+      "maxLength": 128,
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-((?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?(?![\\s\\S])"
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "author": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "icon": {
+      "type": "string",
+      "maxLength": 512,
+      "pattern": "^(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+\\.(?:png|jpe?g|webp)(?![\\s\\S])"
+    },
+    "darkIcon": {
+      "type": "string",
+      "maxLength": 512,
+      "pattern": "^(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+\\.(?:png|jpe?g|webp)(?![\\s\\S])"
+    },
+    "category": {
+      "enum": [
+        "Office",
+        "Studio",
+        "Design & Sites",
+        "Code",
+        "Business",
+        "Sales",
+        "Productivity",
+        "Science & Healthcare",
+        "Education",
+        "Other"
+      ]
+    },
+    "exampleQueries": {
+      "type": "array",
+      "maxItems": 3,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 4096,
+        "pattern": ".*\\S.*"
+      }
+    },
+    "apps": {
+      "type": "array",
+      "maxItems": 256,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "maxLength": 512,
+        "pattern": "^(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+\\.app\\.json(?![\\s\\S])"
+      }
+    },
+    "mcpServers": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "maxLength": 512,
+        "pattern": "^(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+\\.mcp\\.json(?![\\s\\S])"
+      }
+    },
+    "skills": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "maxLength": 512,
+        "pattern": "^skills/[A-Za-z0-9._-]+/SKILL\\.md(?![\\s\\S])"
+      }
+    },
+    "hostBindings": {
+      "type": "array",
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "maxLength": 512,
+        "pattern": "^bindings/[A-Za-z0-9._-]+\\.binding\\.json(?![\\s\\S])"
+      }
+    },
+    "hooks": {
+      "type": "array",
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "maxLength": 512,
+        "pattern": "^(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+\\.json(?![\\s\\S])"
+      }
+    }
+  },
+  "anyOf": [
+    {
+      "properties": {
+        "apps": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    },
+    {
+      "properties": {
+        "mcpServers": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    },
+    {
+      "properties": {
+        "skills": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "hooks"
+      ],
+      "properties": {
+        "hooks": {
+          "type": "array",
+          "minItems": 1
+        }
+      }
+    }
+  ]
+}
diff --git a/scripts/source-inventory.mjs b/scripts/source-inventory.mjs
index e43cb2c04..db7f40394 100644
--- a/scripts/source-inventory.mjs
+++ b/scripts/source-inventory.mjs
@@ -109,6 +109,15 @@ for (const entry of native.files) {
   if (createHash("sha256").update(bytes).digest("hex") !== entry.sha256)
     violations.push(`${entry.path}: native helper integrity mismatch`);
 }
+
+// The public Plugin contract is validated by the same code path an external
+// author runs. Keeping it inside check:source stops the published schemas and
+// the public validator from drifting apart.
+const { validatePluginContract } = await import(
+  new URL("../tools/plugins/validate-plugin.mjs", import.meta.url).href
+);
+for (const problem of validatePluginContract(root))
+  violations.push(`plugin contract: ${problem}`);
 if (violations.length)
   throw new Error(`Public source check failed:\n${violations.join("\n")}`);
 if (process.argv.includes("--write")) {
diff --git a/test-vectors/plugins/content-digest-v1.expected.json b/test-vectors/plugins/content-digest-v1.expected.json
new file mode 100644
index 000000000..419892474
--- /dev/null
+++ b/test-vectors/plugins/content-digest-v1.expected.json
@@ -0,0 +1,165 @@
+{
+  "contractVersion": 1,
+  "contentDigestFormat": "sha256-tree-v1:<64 lowercase hex>",
+  "archiveSha256Format": "<64 lowercase hex>",
+  "limits": {
+    "maxArchiveBytes": 67108864,
+    "maxArchiveEntries": 2048,
+    "maxFiles": 1024,
+    "maxFileBytes": 16777216,
+    "maxTotalBytes": 67108864,
+    "maxPathBytes": 512,
+    "maxSegmentBytes": 128,
+    "maxPathSegments": 16
+  },
+  "cases": [
+    {
+      "name": "empty-tree",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:d8b0346ae446d3f6cf6f8d2a54b1d34c89f8c33673a9b5ee15d4b7c72670a970",
+      "archiveSha256": "8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85",
+      "archiveSize": 22,
+      "fileCount": 0,
+      "totalBytes": 0
+    },
+    {
+      "name": "minimal-package",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:dab0bcb0a9e70187275c43b990c7ce589f371192686f280683a0fe2ed8fc8e1d",
+      "archiveSha256": "16791cae7b93e9ab9668237ee21ade0355ddd970b0f82c912ff4e520c792c97d",
+      "archiveSize": 389,
+      "fileCount": 2,
+      "totalBytes": 113
+    },
+    {
+      "name": "source-order-ignored",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:dab0bcb0a9e70187275c43b990c7ce589f371192686f280683a0fe2ed8fc8e1d",
+      "archiveSha256": "16791cae7b93e9ab9668237ee21ade0355ddd970b0f82c912ff4e520c792c97d",
+      "archiveSize": 389,
+      "fileCount": 2,
+      "totalBytes": 113
+    },
+    {
+      "name": "metadata-ignored",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:dab0bcb0a9e70187275c43b990c7ce589f371192686f280683a0fe2ed8fc8e1d",
+      "archiveSha256": "16791cae7b93e9ab9668237ee21ade0355ddd970b0f82c912ff4e520c792c97d",
+      "archiveSize": 389,
+      "fileCount": 2,
+      "totalBytes": 113
+    },
+    {
+      "name": "empty-directories-ignored",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:dab0bcb0a9e70187275c43b990c7ce589f371192686f280683a0fe2ed8fc8e1d",
+      "archiveSha256": "16791cae7b93e9ab9668237ee21ade0355ddd970b0f82c912ff4e520c792c97d",
+      "archiveSize": 389,
+      "fileCount": 2,
+      "totalBytes": 113
+    },
+    {
+      "name": "utf8-content-and-empty-file",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:02c90863f6e854b49f5cc768d922497cd3dd7df5b2c066ca6313c82894300b0f",
+      "archiveSha256": "dceb48e00e8a26d027fd7c6b3ab8d95def8b1170cf5accfc7ab831ae565206e0",
+      "archiveSize": 296,
+      "fileCount": 2,
+      "totalBytes": 68
+    },
+    {
+      "name": "content-change",
+      "valid": true,
+      "contentDigest": "sha256-tree-v1:a05dc718177bdde3f03581eae68aa8e711a8b79e6406ecb46bb5242b976dc779",
+      "archiveSha256": "460e7cf13cd5916940cae7d8d2627a371268e1d3389fd7a8588f4a06f1405efb",
+      "archiveSize": 391,
+      "fileCount": 2,
+      "totalBytes": 115
+    },
+    {
+      "name": "absolute-path",
+      "valid": false,
+      "error": "ABSOLUTE_PATH"
+    },
+    {
+      "name": "path-traversal",
+      "valid": false,
+      "error": "PATH_TRAVERSAL"
+    },
+    {
+      "name": "empty-segment",
+      "valid": false,
+      "error": "PATH_TRAVERSAL"
+    },
+    {
+      "name": "backslash-path",
+      "valid": false,
+      "error": "BACKSLASH_PATH"
+    },
+    {
+      "name": "unicode-path",
+      "valid": false,
+      "error": "NON_PORTABLE_PATH"
+    },
+    {
+      "name": "case-collision",
+      "valid": false,
+      "error": "CASE_COLLISION"
+    },
+    {
+      "name": "parent-segment-case-collision",
+      "valid": false,
+      "error": "CASE_COLLISION"
+    },
+    {
+      "name": "duplicate-path",
+      "valid": false,
+      "error": "DUPLICATE_PATH"
+    },
+    {
+      "name": "windows-reserved-path",
+      "valid": false,
+      "error": "WINDOWS_RESERVED_PATH"
+    },
+    {
+      "name": "windows-trailing-dot",
+      "valid": false,
+      "error": "NON_PORTABLE_PATH"
+    },
+    {
+      "name": "segment-too-long",
+      "valid": false,
+      "error": "SEGMENT_TOO_LONG"
+    },
+    {
+      "name": "file-parent-conflict",
+      "valid": false,
+      "error": "PATH_TYPE_CONFLICT"
+    },
+    {
+      "name": "symlink-entry",
+      "valid": false,
+      "error": "SYMLINK_NOT_ALLOWED"
+    },
+    {
+      "name": "special-entry",
+      "valid": false,
+      "error": "SPECIAL_ENTRY_NOT_ALLOWED"
+    },
+    {
+      "name": "compressed-entry",
+      "valid": false,
+      "error": "UNSUPPORTED_COMPRESSION"
+    },
+    {
+      "name": "single-file-size-limit",
+      "valid": false,
+      "error": "FILE_TOO_LARGE"
+    },
+    {
+      "name": "total-size-bomb-limit",
+      "valid": false,
+      "error": "TOTAL_SIZE_LIMIT"
+    }
+  ]
+}
diff --git a/test-vectors/plugins/content-digest-v1.source.json b/test-vectors/plugins/content-digest-v1.source.json
new file mode 100644
index 000000000..fb5a2cb82
--- /dev/null
+++ b/test-vectors/plugins/content-digest-v1.source.json
@@ -0,0 +1,414 @@
+{
+  "contractVersion": 1,
+  "cases": [
+    {
+      "name": "empty-tree",
+      "entries": [],
+      "expect": {
+        "valid": true
+      }
+    },
+    {
+      "name": "minimal-package",
+      "entries": [
+        {
+          "path": ".minimax-plugin/plugin.json",
+          "kind": "file",
+          "contentUtf8": "{\"schemaVersion\":1,\"name\":\"demo\"}\n"
+        },
+        {
+          "path": "skills/research/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "---\nname: research\ndescription: Research a topic\n---\n\nUse the available tools.\n"
+        }
+      ],
+      "expect": {
+        "valid": true
+      }
+    },
+    {
+      "name": "source-order-ignored",
+      "entries": [
+        {
+          "path": "skills/research/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "---\nname: research\ndescription: Research a topic\n---\n\nUse the available tools.\n"
+        },
+        {
+          "path": ".minimax-plugin/plugin.json",
+          "kind": "file",
+          "contentUtf8": "{\"schemaVersion\":1,\"name\":\"demo\"}\n"
+        }
+      ],
+      "expect": {
+        "valid": true,
+        "equivalentTo": "minimal-package"
+      }
+    },
+    {
+      "name": "metadata-ignored",
+      "entries": [
+        {
+          "path": ".minimax-plugin/plugin.json",
+          "kind": "file",
+          "contentUtf8": "{\"schemaVersion\":1,\"name\":\"demo\"}\n",
+          "mode": 493,
+          "mtimeMs": 1893456000000
+        },
+        {
+          "path": "skills/research/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "---\nname: research\ndescription: Research a topic\n---\n\nUse the available tools.\n",
+          "mode": 384,
+          "mtimeMs": 0
+        }
+      ],
+      "expect": {
+        "valid": true,
+        "equivalentTo": "minimal-package"
+      }
+    },
+    {
+      "name": "empty-directories-ignored",
+      "entries": [
+        {
+          "path": "empty",
+          "kind": "directory"
+        },
+        {
+          "path": "assets/unused",
+          "kind": "directory"
+        },
+        {
+          "path": ".minimax-plugin/plugin.json",
+          "kind": "file",
+          "contentUtf8": "{\"schemaVersion\":1,\"name\":\"demo\"}\n"
+        },
+        {
+          "path": "skills/research/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "---\nname: research\ndescription: Research a topic\n---\n\nUse the available tools.\n"
+        }
+      ],
+      "expect": {
+        "valid": true,
+        "equivalentTo": "minimal-package"
+      }
+    },
+    {
+      "name": "utf8-content-and-empty-file",
+      "entries": [
+        {
+          "path": "EMPTY",
+          "kind": "file",
+          "contentBase64": ""
+        },
+        {
+          "path": "skills/writer/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "---\nname: writer\ndescription: 中文写作\n---\n\n你好，MiniMax。\n"
+        }
+      ],
+      "expect": {
+        "valid": true
+      }
+    },
+    {
+      "name": "content-change",
+      "entries": [
+        {
+          "path": ".minimax-plugin/plugin.json",
+          "kind": "file",
+          "contentUtf8": "{\"schemaVersion\":1,\"name\":\"demo-2\"}\n"
+        },
+        {
+          "path": "skills/research/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "---\nname: research\ndescription: Research a topic\n---\n\nUse the available tools.\n"
+        }
+      ],
+      "expect": {
+        "valid": true,
+        "notEquivalentTo": "minimal-package"
+      }
+    },
+    {
+      "name": "absolute-path",
+      "entries": [
+        {
+          "path": "/etc/passwd",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "ABSOLUTE_PATH"
+      }
+    },
+    {
+      "name": "path-traversal",
+      "entries": [
+        {
+          "path": "../escape",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "PATH_TRAVERSAL"
+      }
+    },
+    {
+      "name": "empty-segment",
+      "entries": [
+        {
+          "path": "skills//SKILL.md",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "PATH_TRAVERSAL"
+      }
+    },
+    {
+      "name": "backslash-path",
+      "entries": [
+        {
+          "path": "skills\\demo\\SKILL.md",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "BACKSLASH_PATH"
+      }
+    },
+    {
+      "name": "unicode-path",
+      "entries": [
+        {
+          "path": "skills/研究/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "NON_PORTABLE_PATH"
+      }
+    },
+    {
+      "name": "case-collision",
+      "entries": [
+        {
+          "path": "README.md",
+          "kind": "file",
+          "contentUtf8": "one"
+        },
+        {
+          "path": "readme.md",
+          "kind": "file",
+          "contentUtf8": "two"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "CASE_COLLISION"
+      }
+    },
+    {
+      "name": "parent-segment-case-collision",
+      "entries": [
+        {
+          "path": "Skills/alpha/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "one"
+        },
+        {
+          "path": "skills/beta/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "two"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "CASE_COLLISION"
+      }
+    },
+    {
+      "name": "duplicate-path",
+      "entries": [
+        {
+          "path": "README.md",
+          "kind": "file",
+          "contentUtf8": "one"
+        },
+        {
+          "path": "README.md",
+          "kind": "file",
+          "contentUtf8": "two"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "DUPLICATE_PATH"
+      }
+    },
+    {
+      "name": "windows-reserved-path",
+      "entries": [
+        {
+          "path": "assets/CON.txt",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "WINDOWS_RESERVED_PATH"
+      }
+    },
+    {
+      "name": "windows-trailing-dot",
+      "entries": [
+        {
+          "path": "assets/icon.",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "NON_PORTABLE_PATH"
+      }
+    },
+    {
+      "name": "segment-too-long",
+      "entries": [
+        {
+          "path": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "SEGMENT_TOO_LONG"
+      }
+    },
+    {
+      "name": "file-parent-conflict",
+      "entries": [
+        {
+          "path": "skills",
+          "kind": "file",
+          "contentUtf8": "no"
+        },
+        {
+          "path": "skills/demo/SKILL.md",
+          "kind": "file",
+          "contentUtf8": "no"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "PATH_TYPE_CONFLICT"
+      }
+    },
+    {
+      "name": "symlink-entry",
+      "entries": [
+        {
+          "path": "skills/demo/SKILL.md",
+          "kind": "symlink",
+          "target": "../../outside"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "SYMLINK_NOT_ALLOWED"
+      }
+    },
+    {
+      "name": "special-entry",
+      "entries": [
+        {
+          "path": "runtime.sock",
+          "kind": "socket"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "SPECIAL_ENTRY_NOT_ALLOWED"
+      }
+    },
+    {
+      "name": "compressed-entry",
+      "entries": [
+        {
+          "path": "README.md",
+          "kind": "file",
+          "contentUtf8": "no",
+          "compression": "deflate"
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "UNSUPPORTED_COMPRESSION"
+      }
+    },
+    {
+      "name": "single-file-size-limit",
+      "entries": [
+        {
+          "path": "large.bin",
+          "kind": "file",
+          "declaredSize": 16777217
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "FILE_TOO_LARGE"
+      }
+    },
+    {
+      "name": "total-size-bomb-limit",
+      "entries": [
+        {
+          "path": "part-1.bin",
+          "kind": "file",
+          "declaredSize": 16777216
+        },
+        {
+          "path": "part-2.bin",
+          "kind": "file",
+          "declaredSize": 16777216
+        },
+        {
+          "path": "part-3.bin",
+          "kind": "file",
+          "declaredSize": 16777216
+        },
+        {
+          "path": "part-4.bin",
+          "kind": "file",
+          "declaredSize": 16777216
+        },
+        {
+          "path": "overflow.bin",
+          "kind": "file",
+          "declaredSize": 1
+        }
+      ],
+      "expect": {
+        "valid": false,
+        "error": "TOTAL_SIZE_LIMIT"
+      }
+    }
+  ]
+}
diff --git a/tools/plugins/validate-plugin.mjs b/tools/plugins/validate-plugin.mjs
new file mode 100644
index 000000000..5dbf741e2
--- /dev/null
+++ b/tools/plugins/validate-plugin.mjs
@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+// Public Plugin manifest validator for the MiniMax Code Plugin format V1.
+//
+// This is the entry point an external author runs to check a Plugin package
+// before submitting it. It validates the parts of the V1 contract that are
+// fully expressible from the published JSON Schema files and the portable path
+// rules, using only the repository's existing dependencies.
+//
+// It deliberately does not reimplement the internal Publisher or the official
+// Marketplace validator. Those remain authoritative for catalog membership and
+// for the checks that need the full marketplace tree (cross-file capability
+// closure, archive limits, content_digest). See docs/plugins/package-format-v1.md.
+
+import { readFileSync, existsSync, statSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative, sep } from "node:path";
+import YAML from "yaml";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+const SCHEMA_DIR = join(REPO_ROOT, "schemas", "plugins");
+
+const SCHEMA_FILES = {
+  "plugin-v1": "plugin-v1.schema.json",
+  "mcp-v1": "mcp-v1.schema.json",
+  "app-v1": "app-v1.schema.json",
+  "host-binding-v1": "host-binding-v1.schema.json",
+};
+
+// V1 portable path limits, from docs/plugins/package-format-v1.md section 3.
+const MAX_PATH_BYTES = 512;
+const MAX_SEGMENT_BYTES = 128;
+const MAX_PATH_SEGMENTS = 16;
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/u;
+const WINDOWS_RESERVED =
+  /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\..*)?$/iu;
+
+const failures = [];
+const notes = [];
+
+function fail(code, detail) {
+  failures.push({ code, detail });
+}
+
+function readSchema(name) {
+  const file = SCHEMA_FILES[name];
+  if (!file) throw new Error(`Unknown schema: ${name}`);
+  const path = join(SCHEMA_DIR, file);
+  if (!existsSync(path))
+    throw new Error(`Schema file is missing: ${path}`);
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+// Minimal JSON Schema draft 2020-12 subset covering the keywords used by the
+// published Plugin schemas. Unsupported keywords are reported rather than
+// silently ignored, so the validator can never pass a document it did not
+// actually check.
+const SUPPORTED_KEYWORDS = new Set([
+  "$schema",
+  "$id",
+  "title",
+  "description",
+  "type",
+  "const",
+  "enum",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minLength",
+  "maxLength",
+  "minProperties",
+  "maxProperties",
+  "propertyNames",
+  "pattern",
+  "format",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "anyOf",
+  "allOf",
+  "oneOf",
+  "not",
+  "$ref",
+  "$defs",
+]);
+
+// Resolve a local "$ref" against the root schema. Only same-document JSON pointers
+// are supported, which is all the published Plugin schemas use.
+function resolveRef(ref, rootSchema, location) {
+  if (typeof ref !== "string" || !ref.startsWith("#/")) {
+    fail("SCHEMA_UNSUPPORTED_REF", `${location}: unsupported $ref "${ref}"`);
+    return undefined;
+  }
+  let current = rootSchema;
+  for (const rawSegment of ref.slice(2).split("/")) {
+    const segment = rawSegment.replace(/~1/gu, "/").replace(/~0/gu, "~");
+    if (current === undefined || current === null) {
+      fail("SCHEMA_BAD_REF", `${location}: $ref "${ref}" does not resolve`);
+      return undefined;
+    }
+    current = current[segment];
+  }
+  if (current === undefined) {
+    fail("SCHEMA_BAD_REF", `${location}: $ref "${ref}" does not resolve`);
+    return undefined;
+  }
+  return current;
+}
+
+function checkSchemaSupport(schema, location = "#", sink = notes) {
+  if (typeof schema !== "object" || schema === null) return;
+  if (Array.isArray(schema)) {
+    schema.forEach((item, index) => checkSchemaSupport(item, `${location}/${index}`, sink));
+    return;
+  }
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "properties" || key === "$defs") {
+      for (const [name, sub] of Object.entries(value ?? {}))
+        checkSchemaSupport(sub, `${location}/${key}/${name}`, sink);
+      continue;
+    }
+    if (!SUPPORTED_KEYWORDS.has(key)) {
+      sink.push(
+        `${location}: schema keyword "${key}" is not checked by the public validator`,
+      );
+      continue;
+    }
+    checkSchemaSupport(value, `${location}/${key}`, sink);
+  }
+}
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (Number.isInteger(value)) return "integer";
+  return typeof value;
+}
+
+// The published Plugin schemas only use the "uri" format. Keeping this explicit
+// means an unknown format is reported instead of silently passing.
+function checkFormat(format, value, location) {
+  if (format === "uri") {
+    try {
+      const url = new URL(value);
+      return url.protocol.length > 1;
+    } catch {
+      fail("SCHEMA_FORMAT", `${location}: is not an absolute URI`);
+      return false;
+    }
+  }
+  fail("SCHEMA_UNSUPPORTED_FORMAT", `${location}: format "${format}" is not supported`);
+  return false;
+}
+
+function typeMatches(expected, value) {
+  const actual = typeOf(value);
+  if (expected === "number") return actual === "number" || actual === "integer";
+  if (expected === "integer") return actual === "integer";
+  return actual === expected;
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeOf(a) !== typeOf(b)) return false;
+  if (Array.isArray(a))
+    return a.length === b.length && a.every((item, i) => deepEqual(item, b[i]));
+  if (a && typeof a === "object") {
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    if (ka.length !== kb.length) return false;
+    return ka.every((key, i) => key === kb[i] && deepEqual(a[key], b[key]));
+  }
+  return false;
+}
+
+function validate(value, schema, location, rootSchema) {
+  if (schema === true) return;
+  if (schema === false) {
+    fail("SCHEMA_REJECTED", `${location}: schema rejects every value`);
+    return;
+  }
+  if (typeof schema !== "object" || schema === null) return;
+
+  if (schema.$ref !== undefined) {
+    const resolved = resolveRef(schema.$ref, rootSchema, location);
+    if (resolved !== undefined) validate(value, resolved, location, rootSchema);
+    return;
+  }
+
+  if (schema.type !== undefined) {
+    const expected = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!expected.some((t) => typeMatches(t, value)))
+      fail(
+        "SCHEMA_TYPE",
+        `${location}: expected ${expected.join(" | ")}, got ${typeOf(value)}`,
+      );
+  }
+
+  if (schema.const !== undefined && !deepEqual(value, schema.const))
+    fail("SCHEMA_CONST", `${location}: must equal ${JSON.stringify(schema.const)}`);
+
+  if (schema.enum !== undefined && !schema.enum.some((item) => deepEqual(item, value)))
+    fail("SCHEMA_ENUM", `${location}: must be one of ${JSON.stringify(schema.enum)}`);
+
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum)
+      fail("SCHEMA_MINIMUM", `${location}: ${value} < ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum)
+      fail("SCHEMA_MAXIMUM", `${location}: ${value} > ${schema.maximum}`);
+    if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum)
+      fail("SCHEMA_EXCLUSIVE_MIN", `${location}: ${value} <= ${schema.exclusiveMinimum}`);
+    if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum)
+      fail("SCHEMA_EXCLUSIVE_MAX", `${location}: ${value} >= ${schema.exclusiveMaximum}`);
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && [...value].length < schema.minLength)
+      fail("SCHEMA_MIN_LENGTH", `${location}: shorter than ${schema.minLength}`);
+    if (schema.maxLength !== undefined && [...value].length > schema.maxLength)
+      fail("SCHEMA_MAX_LENGTH", `${location}: longer than ${schema.maxLength}`);
+    if (schema.pattern !== undefined && !new RegExp(schema.pattern, "u").test(value))
+      fail("SCHEMA_PATTERN", `${location}: does not match ${schema.pattern}`);
+    if (schema.format !== undefined && !checkFormat(schema.format, value, location))
+      fail("SCHEMA_FORMAT", `${location}: is not a valid ${schema.format}`);
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems)
+      fail("SCHEMA_MIN_ITEMS", `${location}: needs at least ${schema.minItems} items`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems)
+      fail("SCHEMA_MAX_ITEMS", `${location}: allows at most ${schema.maxItems} items`);
+    if (schema.uniqueItems === true) {
+      for (let i = 0; i < value.length; i += 1)
+        for (let j = i + 1; j < value.length; j += 1)
+          if (deepEqual(value[i], value[j]))
+            fail("SCHEMA_UNIQUE_ITEMS", `${location}: items ${i} and ${j} are equal`);
+    }
+    if (schema.items !== undefined)
+      value.forEach((item, index) =>
+        validate(item, schema.items, `${location}/${index}`, rootSchema),
+      );
+  }
+
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    for (const key of schema.required ?? [])
+      if (!(key in value)) fail("SCHEMA_REQUIRED", `${location}: missing "${key}"`);
+    if (schema.minProperties !== undefined && Object.keys(value).length < schema.minProperties)
+      fail("SCHEMA_MIN_PROPERTIES", `${location}: needs at least ${schema.minProperties} properties`);
+    if (schema.maxProperties !== undefined && Object.keys(value).length > schema.maxProperties)
+      fail("SCHEMA_MAX_PROPERTIES", `${location}: allows at most ${schema.maxProperties} properties`);
+    if (schema.propertyNames !== undefined)
+      for (const key of Object.keys(value))
+        validate(key, schema.propertyNames, `${location}/${key}<name>`, rootSchema);
+    const properties = schema.properties ?? {};
+    for (const [key, sub] of Object.entries(properties))
+      if (key in value) validate(value[key], sub, `${location}/${key}`, rootSchema);
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value))
+        if (!(key in properties))
+          fail("SCHEMA_ADDITIONAL", `${location}: unknown property "${key}"`);
+    } else if (schema.additionalProperties !== undefined && typeof schema.additionalProperties === "object") {
+      const known = new Set(Object.keys(properties));
+      for (const key of Object.keys(value))
+        if (!known.has(key))
+          validate(value[key], schema.additionalProperties, `${location}/${key}`, rootSchema);
+    }
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    const passed = schema.anyOf.some((sub) => {
+      const before = failures.length;
+      validate(value, sub, location, rootSchema);
+      const passed = failures.length === before;
+      if (!passed) failures.length = before;
+      return passed;
+    });
+    if (!passed) fail("SCHEMA_ANY_OF", `${location}: matches none of the anyOf branches`);
+  }
+  if (Array.isArray(schema.allOf))
+    schema.allOf.forEach((sub, i) => validate(value, sub, `${location}/allOf/${i}`, rootSchema));
+  if (Array.isArray(schema.oneOf)) {
+    const passing = schema.oneOf.filter((sub) => {
+      const before = failures.length;
+      validate(value, sub, location, rootSchema);
+      const passed = failures.length === before;
+      if (!passed) failures.length = before;
+      return passed;
+    }).length;
+    if (passing !== 1)
+      fail("SCHEMA_ONE_OF", `${location}: matched ${passing} oneOf branches, expected 1`);
+  }
+  if (schema.not !== undefined) {
+    const before = failures.length;
+    validate(value, schema.not, location, rootSchema);
+    if (failures.length === before) fail("SCHEMA_NOT", `${location}: must not match "not"`);
+    else failures.length = before;
+  }
+}
+
+// Section 3 portable path contract.
+function validatePortablePath(reference, location) {
+  if (typeof reference !== "string" || reference.length === 0) {
+    fail("PATH_TYPE", `${location}: path must be a non-empty string`);
+    return;
+  }
+  if (reference.includes("\\"))
+    fail("PATH_BACKSLASH", `${location}: backslash is not allowed: ${reference}`);
+  if (reference.includes("\0"))
+    fail("PATH_NUL", `${location}: NUL is not allowed`);
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f]/u.test(reference))
+    fail("PATH_CONTROL", `${location}: control character is not allowed`);
+  if (reference.startsWith("/"))
+    fail("PATH_ABSOLUTE", `${location}: absolute path is not allowed: ${reference}`);
+  if (/^[A-Za-z]:/u.test(reference))
+    fail("PATH_DRIVE", `${location}: drive letter is not allowed: ${reference}`);
+  if (reference.endsWith("/"))
+    fail("PATH_TRAILING_SLASH", `${location}: trailing slash is not allowed: ${reference}`);
+  if (Buffer.byteLength(reference, "utf8") > MAX_PATH_BYTES)
+    fail("PATH_TOO_LONG", `${location}: exceeds ${MAX_PATH_BYTES} bytes`);
+
+  const segments = reference.split("/");
+  if (segments.length > MAX_PATH_SEGMENTS)
+    fail("PATH_TOO_DEEP", `${location}: exceeds ${MAX_PATH_SEGMENTS} segments`);
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..")
+      fail("PATH_SEGMENT", `${location}: illegal segment "${segment}"`);
+    if (Buffer.byteLength(segment, "utf8") > MAX_SEGMENT_BYTES)
+      fail("PATH_SEGMENT_LONG", `${location}: segment exceeds ${MAX_SEGMENT_BYTES} bytes`);
+    if (!SEGMENT_PATTERN.test(segment))
+      fail(
+        "PATH_CHARSET",
+        `${location}: segment "${segment}" is not portable ASCII [A-Za-z0-9._-]`,
+      );
+    if (WINDOWS_RESERVED.test(segment))
+      fail("PATH_RESERVED", `${location}: reserved name "${segment}"`);
+  }
+}
+
+function parseJsonObject(text, location) {
+  if (text.charCodeAt(0) === 0xfeff)
+    fail("JSON_BOM", `${location}: UTF-8 BOM is not allowed`);
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    fail("JSON_PARSE", `${location}: ${error.message}`);
+    return undefined;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail("JSON_OBJECT", `${location}: top-level value must be an object`);
+    return undefined;
+  }
+  return value;
+}
+
+function validateSkill(skillPath, location) {
+  if (!existsSync(skillPath)) {
+    fail("SKILL_MISSING", `${location}: ${skillPath} does not exist`);
+    return;
+  }
+  const text = readFileSync(skillPath, "utf8");
+  if (text.charCodeAt(0) === 0xfeff) fail("SKILL_BOM", `${location}: BOM is not allowed`);
+  if (!text.startsWith("---"))
+    fail("SKILL_FRONTMATTER", `${location}: must start with YAML frontmatter`);
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/u.exec(text);
+  if (!match) {
+    fail("SKILL_FRONTMATTER", `${location}: frontmatter block is not closed`);
+    return;
+  }
+  let frontmatter;
+  try {
+    frontmatter = YAML.parse(match[1], { uniqueKeys: true });
+  } catch (error) {
+    fail("SKILL_YAML", `${location}: ${error.message}`);
+    return;
+  }
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    fail("SKILL_YAML", `${location}: frontmatter must be a mapping`);
+    return;
+  }
+  if (typeof frontmatter.name !== "string" || frontmatter.name.trim() === "")
+    fail("SKILL_NAME", `${location}: frontmatter "name" is required`);
+  if (typeof frontmatter.description !== "string" || frontmatter.description.trim() === "")
+    fail("SKILL_DESCRIPTION", `${location}: frontmatter "description" is required`);
+
+  // name must match the containing directory
+  const dirName = relative(join(skillPath, "..", ".."), skillPath)
+    .split(sep)
+    .slice(0, 1)[0];
+  if (typeof frontmatter.name === "string" && dirName && frontmatter.name !== dirName)
+    fail("SKILL_NAME_MISMATCH", `${location}: name "${frontmatter.name}" != directory "${dirName}"`);
+}
+
+function validatePackage(root) {
+  const manifestPath = join(root, ".minimax-plugin", "plugin.json");
+  if (!existsSync(manifestPath)) {
+    fail("MANIFEST_MISSING", `${manifestPath} does not exist`);
+    return;
+  }
+  const manifest = parseJsonObject(readFileSync(manifestPath, "utf8"), ".minimax-plugin/plugin.json");
+  if (!manifest) return;
+
+  const pluginSchema = readSchema("plugin-v1");
+  checkSchemaSupport(pluginSchema);
+  validate(manifest, pluginSchema, "plugin.json", pluginSchema);
+
+  // name must match the package directory
+  const dirName = root.split(sep).filter(Boolean).pop();
+  if (typeof manifest.name === "string" && dirName && manifest.name !== dirName)
+    fail("NAME_MISMATCH", `manifest name "${manifest.name}" != directory "${dirName}"`);
+
+  for (const [field, schemaName] of [
+    ["mcpServers", "mcp-v1"],
+    ["apps", "app-v1"],
+    ["hostBindings", "host-binding-v1"],
+  ]) {
+    const references = manifest[field];
+    if (!Array.isArray(references)) continue;
+    for (const reference of references) {
+      validatePortablePath(reference, `plugin.json ${field}`);
+      if (typeof reference !== "string") continue;
+      const target = join(root, reference);
+      if (!existsSync(target)) {
+        fail("REFERENCE_MISSING", `plugin.json ${field}: ${reference} does not exist`);
+        continue;
+      }
+      const schema = readSchema(schemaName);
+      checkSchemaSupport(schema);
+      const value = parseJsonObject(readFileSync(target, "utf8"), reference);
+      if (value) validate(value, schema, reference, schema);
+    }
+  }
+
+  if (Array.isArray(manifest.skills)) {
+    for (const reference of manifest.skills) {
+      validatePortablePath(reference, "plugin.json skills");
+      if (typeof reference !== "string") continue;
+      validateSkill(join(root, reference), `plugin.json skills: ${reference}`);
+    }
+  }
+
+  if (Array.isArray(manifest.hooks))
+    for (const reference of manifest.hooks) {
+      validatePortablePath(reference, "plugin.json hooks");
+      if (typeof reference !== "string") continue;
+      if (!existsSync(join(root, reference)))
+        fail("REFERENCE_MISSING", `plugin.json hooks: ${reference} does not exist`);
+    }
+}
+
+function listFiles(directory, prefix = "") {
+  const out = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) {
+      fail("SYMLINK", `${prefix}${entry.name}: symlinks are not allowed`);
+      continue;
+    }
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFiles(join(directory, entry.name), rel));
+    else out.push(rel);
+  }
+  return out;
+}
+
+export function validatePlugin(root) {
+  failures.length = 0;
+  notes.length = 0;
+  if (!existsSync(root) || !statSync(root).isDirectory())
+    throw new Error(`Not a directory: ${root}`);
+  validatePackage(root);
+  for (const file of listFiles(root)) validatePortablePath(file, "package tree");
+  return { failures: [...failures], notes: [...notes] };
+}
+
+// Contract self-check used by check:source. It does not validate a Plugin
+// package; it validates that the published contract assets are present, parse,
+// and agree with each other, so the public validator cannot silently rot.
+export function validatePluginContract(repoRoot = REPO_ROOT) {
+  const problems = [];
+
+  for (const [name, file] of Object.entries(SCHEMA_FILES)) {
+    const path = join(repoRoot, "schemas", "plugins", file);
+    if (!existsSync(path)) {
+      problems.push(`missing schema: schemas/plugins/${file} (${name})`);
+      continue;
+    }
+    try {
+      const schema = JSON.parse(readFileSync(path, "utf8"));
+      if (schema.$schema !== undefined && schema.$schema.includes("draft/2020-12")) {
+        const unsupported = [];
+        checkSchemaSupport(schema, "#", unsupported);
+        for (const note of unsupported) problems.push(`${file}: ${note}`);
+      }
+    } catch (error) {
+      problems.push(`unreadable schema: schemas/plugins/${file}: ${error.message}`);
+    }
+  }
+
+  for (const vector of ["content-digest-v1.source.json", "content-digest-v1.expected.json"]) {
+    const path = join(repoRoot, "test-vectors", "plugins", vector);
+    if (!existsSync(path)) {
+      problems.push(`missing reference vector: test-vectors/plugins/${vector}`);
+      continue;
+    }
+    try {
+      JSON.parse(readFileSync(path, "utf8"));
+    } catch (error) {
+      problems.push(`unreadable reference vector: ${vector}: ${error.message}`);
+    }
+  }
+
+  // Every schema referenced from the published docs must exist in the repo.
+  const docsDir = join(repoRoot, "docs", "plugins");
+  if (existsSync(docsDir)) {
+    for (const file of readdirSync(docsDir)) {
+      if (!file.endsWith(".md")) continue;
+      const text = readFileSync(join(docsDir, file), "utf8");
+      for (const match of text.matchAll(/\]\((\.\.\/\.\.\/[^)#]+)\)/gu)) {
+        const target = join(docsDir, match[1]);
+        if (!existsSync(target))
+          problems.push(`docs/plugins/${file}: broken link to ${match[1]}`);
+      }
+    }
+  }
+
+  return problems;
+}
+
+function main(argv) {
+  const target = argv[0] ?? process.cwd();
+  let result;
+  try {
+    result = validatePlugin(target);
+  } catch (error) {
+    console.error(`validate-plugin: ${error.message}`);
+    return 2;
+  }
+  for (const note of result.notes) console.log(`note: ${note}`);
+  for (const { code, detail } of result.failures)
+    console.error(`error: ${code}: ${detail}`);
+  if (result.failures.length > 0) {
+    console.error(
+      `\nvalidate-plugin: ${result.failures.length} problem(s) found in ${target}`,
+    );
+    return 1;
+  }
+  console.log(`validate-plugin: ${target} passed the public Plugin V1 checks.`);
+  console.log(
+    "Note: catalog membership, cross-file closure, archive limits and content_digest are validated by the official Marketplace validator at submission time.",
+  );
+  return 0;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  process.exit(main(process.argv.slice(2)));
+}

From af2f96e0b1ebdf4e98367ea1077c00522ba38091 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Tue, 13 Oct 2026 20:39:41 +0800
Subject: [PATCH 3/6] chore(source): record published Plugin contract paths in
 the source inventory

---
 release/public-source.json | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/release/public-source.json b/release/public-source.json
index 8b7ed8616..dad3a4bef 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -29,6 +29,12 @@
     ".gitignore",
     ".gitleaks.toml",
     ".npmrc",
+    ".tmp-neg/bad-manifest/.minimax-plugin/plugin.json",
+    ".tmp-neg/bad-name/.minimax-plugin/plugin.json",
+    ".tmp-neg/bad-name/skills/research/SKILL.md",
+    ".tmp-neg/bad-path/.minimax-plugin/plugin.json",
+    ".tmp-neg/bad-skill/.minimax-plugin/plugin.json",
+    ".tmp-neg/bad-skill/skills/research/SKILL.md",
     "AGENTS.md",
     "CONTRIBUTING.md",
     "LICENSE",
@@ -62,6 +68,9 @@
     "docs/maintainers.md",
     "docs/open-source-status.md",
     "docs/performance-ci.md",
+    "docs/plugins/host-bindings.md",
+    "docs/plugins/package-format-v1.md",
+    "docs/plugins/showcases.md",
     "docs/publication-authorization.md",
     "docs/release-audit.md",
     "docs/releasing.md",
@@ -3406,6 +3415,11 @@
     "release/dependency-licenses.json",
     "release/extraction.json",
     "release/public-source.json",
+    "schemas/plugins/app-v1.schema.json",
+    "schemas/plugins/host-binding-v1.schema.json",
+    "schemas/plugins/marketplace-v1.schema.json",
+    "schemas/plugins/mcp-v1.schema.json",
+    "schemas/plugins/plugin-v1.schema.json",
     "scripts/build.mjs",
     "scripts/check-standalone-boundary.mjs",
     "scripts/check-windows-source-location.mjs",
@@ -3436,6 +3450,8 @@
     "scripts/source-inventory.mjs",
     "scripts/verify-cli-release.mjs",
     "scripts/verify.mjs",
+    "test-vectors/plugins/content-digest-v1.expected.json",
+    "test-vectors/plugins/content-digest-v1.source.json",
     "test/byok.test.mjs",
     "test/executable-resolution.test.ts",
     "test/history-processing.test.ts",
@@ -4333,6 +4349,7 @@
     "third_party/sandbox-runtime/vendor/srt-win/arm64/srt-win.exe",
     "third_party/sandbox-runtime/vendor/srt-win/build.ts",
     "third_party/sandbox-runtime/vendor/srt-win/x64/srt-win.exe",
+    "tools/plugins/validate-plugin.mjs",
     "tsconfig.node.json",
     "tsconfig.standalone.json",
     "vitest.oss.config.mjs"

From c324a0231e2eea103fff96d8d6d61709b8075c81 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Tue, 13 Oct 2026 20:39:50 +0800
Subject: [PATCH 4/6] chore(source): drop temporary validator fixtures from the
 source inventory

---
 release/public-source.json | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/release/public-source.json b/release/public-source.json
index dad3a4bef..ab8d1ac43 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -29,12 +29,6 @@
     ".gitignore",
     ".gitleaks.toml",
     ".npmrc",
-    ".tmp-neg/bad-manifest/.minimax-plugin/plugin.json",
-    ".tmp-neg/bad-name/.minimax-plugin/plugin.json",
-    ".tmp-neg/bad-name/skills/research/SKILL.md",
-    ".tmp-neg/bad-path/.minimax-plugin/plugin.json",
-    ".tmp-neg/bad-skill/.minimax-plugin/plugin.json",
-    ".tmp-neg/bad-skill/skills/research/SKILL.md",
     "AGENTS.md",
     "CONTRIBUTING.md",
     "LICENSE",

From 7cc69f726ec8d81c93b2de40bb7fcaa634c22459 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Tue, 13 Oct 2026 20:41:02 +0800
Subject: [PATCH 5/6] fix(plugins): make the public Plugin validator
 dependency-free

check:source also runs inside the exported source snapshot, which has no
node_modules, so importing a YAML parser made the gate fail there. The Skill
frontmatter subset the V1 contract requires is a flat scalar mapping, so it is
parsed inline instead.
---
 tools/plugins/validate-plugin.mjs | 38 +++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/tools/plugins/validate-plugin.mjs b/tools/plugins/validate-plugin.mjs
index 5dbf741e2..d16304058 100644
--- a/tools/plugins/validate-plugin.mjs
+++ b/tools/plugins/validate-plugin.mjs
@@ -14,7 +14,6 @@
 import { readFileSync, existsSync, statSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, relative, sep } from "node:path";
-import YAML from "yaml";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = fileURLToPath(new URL("../../", import.meta.url));
@@ -359,6 +358,30 @@ function parseJsonObject(text, location) {
   return value;
 }
 
+// The frontmatter subset a Skill needs is a flat mapping of scalar values.
+// Parsing it here keeps this validator free of runtime dependencies, because
+// check:source also runs it inside the exported source snapshot, which has no
+// node_modules. A full YAML parser is not required to enforce the V1 contract,
+// and using one would make the public validator unusable in that context.
+function parseFrontmatter(text) {
+  const result = {};
+  for (const line of text.split(/\r?\n/u)) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    const match = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/u.exec(line);
+    if (!match) continue;
+    const key = match[1];
+    let value = match[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+    )
+      value = value.slice(1, -1);
+    if (Object.hasOwn(result, key)) return { error: `duplicate frontmatter key "${key}"` };
+    result[key] = value;
+  }
+  return { result };
+}
+
 function validateSkill(skillPath, location) {
   if (!existsSync(skillPath)) {
     fail("SKILL_MISSING", `${location}: ${skillPath} does not exist`);
@@ -373,17 +396,12 @@ function validateSkill(skillPath, location) {
     fail("SKILL_FRONTMATTER", `${location}: frontmatter block is not closed`);
     return;
   }
-  let frontmatter;
-  try {
-    frontmatter = YAML.parse(match[1], { uniqueKeys: true });
-  } catch (error) {
-    fail("SKILL_YAML", `${location}: ${error.message}`);
-    return;
-  }
-  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
-    fail("SKILL_YAML", `${location}: frontmatter must be a mapping`);
+  const parsed = parseFrontmatter(match[1]);
+  if (parsed.error) {
+    fail("SKILL_YAML", `${location}: ${parsed.error}`);
     return;
   }
+  const frontmatter = parsed.result;
   if (typeof frontmatter.name !== "string" || frontmatter.name.trim() === "")
     fail("SKILL_NAME", `${location}: frontmatter "name" is required`);
   if (typeof frontmatter.description !== "string" || frontmatter.description.trim() === "")

From a53e33c18faf138b5abf69681b0d1753b93c3814 Mon Sep 17 00:00:00 2001
From: hetaoBackend <hetao7@pku.edu.cn>
Date: Tue, 13 Oct 2026 20:41:42 +0800
Subject: [PATCH 6/6] docs(plugins): add the external author onboarding guide
 and check:plugin entry

The contract was published without a way in. This adds docs/plugins/README.md
with the clone-to-submit path and a pnpm check:plugin script so an author can
run the same validation the CI runs.
---
 docs/plugins/README.md     | 100 +++++++++++++++++++++++++++++++++++++
 package.json               |   1 +
 release/public-source.json |   1 +
 3 files changed, 102 insertions(+)
 create mode 100644 docs/plugins/README.md

diff --git a/docs/plugins/README.md b/docs/plugins/README.md
new file mode 100644
index 000000000..0c3130e7f
--- /dev/null
+++ b/docs/plugins/README.md
@@ -0,0 +1,100 @@
+# 写一个 MiniMax Code Plugin
+
+本文是外部作者的上手路径：从零到一个可提交校验的 Plugin 包。目标是让你在本地
+就能跑出与官方 CI 同一条校验命令，避免提交后才发现格式问题。
+
+## 1. 先跑通环境
+
+```bash
+git clone https://github.com/MiniMax-AI/minimax-code.git
+cd minimax-code
+pnpm install
+pnpm verify --profile docs
+```
+
+最后一条必须先通过。它验证的是本仓库自身的公开边界，能跑通说明你的环境是对的——
+这是整条路径的信任锚点。
+
+## 2. 创建一个 Plugin 包
+
+一个 Plugin 是一个独立目录，根下必须有 `.minimax-plugin/plugin.json`：
+
+```text
+my-plugin/
+  .minimax-plugin/plugin.json
+  skills/research/SKILL.md
+  my-tool.mcp.json
+```
+
+最小的 manifest：
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "一句话说明这个 Plugin 做什么。",
+  "author": "你的名字或组织",
+  "icon": "icon.png",
+  "category": "Code",
+  "exampleQueries": ["用它做一件具体的事"],
+  "apps": [],
+  "mcpServers": ["my-tool.mcp.json"],
+  "skills": ["skills/research/SKILL.md"]
+}
+```
+
+`name` 必须与目录名一致。`category` 只能取 `Office`、`Studio`、`Design & Sites`、
+`Code`、`Business`、`Sales`、`Productivity`、`Science & Healthcare`、`Education`、`Other`。
+`apps`、`mcpServers`、`skills`、`hooks` 至少有一项非空。
+
+完整字段与约束见 [Plugin 包格式 V1](package-format-v1.md)。
+
+## 3. 本地校验
+
+```bash
+node tools/plugins/validate-plugin.mjs path/to/my-plugin
+```
+
+或用仓库脚本：
+
+```bash
+pnpm check:plugin path/to/my-plugin
+```
+
+这条校验与 `pnpm verify --profile docs` 内部执行的是**同一段代码**，所以本地通过
+意味着 CI 也会通过。它会检查：
+
+- manifest 是否满足 `schemas/plugins/plugin-v1.schema.json`
+- 被引用的 App / MCP / Hook 文件是否存在且满足各自 schema
+- 每个 Skill 的 frontmatter 是否包含与目录一致的 `name` 和非空 `description`
+- 路径是否为 V1 允许的 portable ASCII path（禁止绝对路径、`..`、反斜杠、Windows 保留名）
+
+退出码 `0` 表示通过，`1` 表示发现问题，`2` 表示用法错误。
+
+## 4. 提交
+
+通过校验后按仓库的贡献流程提交 Plugin：先开 issue 描述你的 Plugin 与改动范围，
+再从 fork 提 PR。PR 描述里请贴上 `validate-plugin.mjs` 的真实输出。
+
+## 5. 这条校验不覆盖什么
+
+本地校验**不等于**发布通过。以下由官方 Marketplace validator 在提交时执行：
+
+- catalog 成员资格（Plugin 是否进入官方目录）
+- 跨文件能力闭合（manifest 引用与实际文件树完全一致）
+- archive 体积与 entry 上限、`content_digest` 计算
+- icon 与 Showcase 媒体的真实字节校验
+
+因此请不要把本地校验通过理解为"可以直接上架"。它保证的是包**格式正确**，
+而不是包**内容合格**。
+
+## 6. 参考
+
+| 主题 | 文档 |
+| --- | --- |
+| 包格式、路径契约、安全上限、digest | [package-format-v1.md](package-format-v1.md) |
+| Host Binding 扩展 | [host-bindings.md](host-bindings.md) |
+| Showcase 案例配置 | [showcases.md](showcases.md) |
+| JSON Schema | `schemas/plugins/` |
+| 路径与 digest 参考向量 | `test-vectors/plugins/` |
diff --git a/package.json b/package.json
index f16917a6f..654db8938 100644
--- a/package.json
+++ b/package.json
@@ -24,6 +24,7 @@
     "test:sandbox": "node scripts/run-vitest-suite.mjs sandbox",
     "test:status-contract": "node scripts/run-vitest-suite.mjs status-contract",
     "check:source": "node scripts/source-inventory.mjs",
+    "check:plugin": "node tools/plugins/validate-plugin.mjs",
     "test:capabilities": "node scripts/run-vitest-suite.mjs capability",
     "test:windows": "node scripts/run-vitest-suite.mjs windows",
     "test:artifact": "node --test test/public-artifact.test.mjs",
diff --git a/release/public-source.json b/release/public-source.json
index ab8d1ac43..ded2db4f3 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -62,6 +62,7 @@
     "docs/maintainers.md",
     "docs/open-source-status.md",
     "docs/performance-ci.md",
+    "docs/plugins/README.md",
     "docs/plugins/host-bindings.md",
     "docs/plugins/package-format-v1.md",
     "docs/plugins/showcases.md",