# 包格式与命名

## 命名空间与包名称

注册名称为 `namespace/name`。每段以小写字母开头，使用小写字母、数字及单个分隔短横线，
最多63字节。不自动转换大小写或下划线；名称创建后不可更改。

先在工作台的「命名空间」申请名称，由管理员批准。namespace owner 控制其全部包。
待审核请求不占用名称；所有权转移需要整体转移 namespace 并由管理员审核。

```sh
pluginctl namespace-claim --name my-team --command-id <uuid> --endpoint https://market.example/v1/graphql --json
pluginctl namespace-requests --endpoint https://market.example/v1/graphql --json
```

管理员使用 `namespace-review --approve <request-id> --command-id <uuid>` 批准，或用
`--reject <request-id>` 拒绝。CLI 与 Dashboard 调用相同协议。

## 三种包类别

创建时选择 `agent-plugin`、`runtime-components` 或 `preset`，后续版本不可变更类别。

| 类别               | 根描述文件       | 内容                                     |
| ------------------ | ---------------- | ---------------------------------------- |
| Agent Plugin       | plugin.json      | Agent Skills、MCP 定义及 bin             |
| Runtime Components | marketplace.json | 带种类、格式、placement 和摘要的组件目录 |
| Preset             | marketplace.json | 精确固定版本与摘要的声明式预设           |

Agent Plugin 的 `plugin.json.name` 为注册名中的 name 段；source-release index 使用完整
namespace/name。manifest `$schema` 仍为 `urn:marketplace:plugin-manifest:v1`。
各平台 manifest 和 portable tree 必须一致，只有 bin/ 下的字节可不同。

新类别使用 `marketplace.artifact/v1` envelope。机器 schema 位于仓库
`api/admission/marketplace/artifact-v1.schema.json`，八组示例位于
`api/fixtures/artifact-families.json`。组件目录为 `components/<component_id>/`，摘要绑定
该目录的精确文件树。只允许 snapshot，不发布本机 link 或工作区 AGENTS.md。
未知组件种类只做结构准入，发布成功不表示 Runtime 能执行该组件。

Preset 文档保留 runtime 的规范摘要算法。所有 includes 和 plugin pins 必须在当前
Marketplace 有匹配的已发布 release；传递依赖停用或 yank 后，当前 snapshot 的 preset
正常选择拒绝。隐藏不阻止已知身份读取。预设只含可公开配置和凭据引用，不得包含秘密或运行授权。

## 平台与归档

发布可以包含一个 universal 包，或1到6个精确 OS/architecture 包，不能混合。
Preset 必须 universal；Native 组件必须精确平台。下载显式选择实际公布的 target。

```sh
pluginctl pack --root ./package --out ./artifacts --platform universal --json
pluginctl publish --name my-team/my-package --metadata ./metadata.json --artifacts-dir ./artifacts --journal ./publish.json --endpoint https://market.example/v1/graphql --json
```

CLI 从已校验的本地归档确定类别；URL 导入必须显式提供 `--family`。
归档为 tar.gz ustar/pax，发布保留原始字节，不重新打包。禁止链接、绝对路径、遍历、重复及
大小写冲突。压缩上限512MiB、解压2GiB、单文件256MiB、条目50000。
组件与预设的根 marketplace.json 上限256KiB。内容变化必须发布新版本。

## URL 导入

source-release index 使用 `marketplace.source-release/v1`，包含完整注册名、精确版本、
实际 target 集合、HTTPS 地址、tar.gz 格式、归档 SHA-256 与大小。universal target 为
`{"os":"universal","arch":"universal"}`。导入受 origin、DNS 与重定向规则限制。

静态校验不运行代码、不连接包中服务、不下载描述符 schema。账号权限来自 namespace
所有权与当前身份，不来自 manifest 作者、名称或源地址。