paseo/public-docs/plugins/publishing.zh-CN.md

title, description, nav

title	description	nav
发布插件	准备、发布 Paseo 插件，并把它提交到经过审查的注册表。	发布

发布插件

从一个可用的插件项目开始。准备好它的展示页，把它发布到 npm 或推送到 GitHub，然后提交到注册表。获得批准后，用户可以用 paseo plugin add owner/slug 安装经过审查的版本。

1. 准备你的展示页；对于可视化插件，还要准备一张界面图片。
2. 发布到 npm或通过 Git 分享。
3. 提交到插件注册表。

对于私有插件，请使用直接从 Git 安装或私有 npm 包。

你的展示页

你可以不带 OVERVIEW.md 提交；审查者会根据你的 README 和经过验证的行为创建展示页。要自己维护这个页面，请把 OVERVIEW.md 放在 paseo-plugin.json 旁边，并把它包含在发布的包中。脚手架已经在 files 中包含了它。你随包发布的概览会替换审查者编写的页面。

按以下顺序说明这些要点，只在有帮助时使用标题：

1. 插件做什么。
2. 它如何工作（当这一点不明显时）。
3. 设置：设置项、账号、令牌、外部工具、支持的操作系统和 Paseo 版本。
4. 有用的能力、设置项、数据访问、权限和限制。

说明数据会流向哪里，包括发送给 Agent Provider 的提示词和工具结果。本地存储并不意味着数据留在主机上。如果插件在运行时下载或安装软件，请说明它安装什么以及来源，并在下载之前要求用户明确确认。这同样适用于激活和连接测试；用户拒绝时，软件必须保持未安装状态。

使用平实、客观的语言，标题只把首字母大写。省略营销内容、无依据的说法、徽章、更新日志、贡献和许可证章节，以及无助于他人选择插件的实现细节。展示页已经提供了插件的安装说明。

发布校验器会拒绝概览中任何位置出现的 paseo plugin add、npm install 和 npm i，包括开发或设置示例。请为这些命令链接到你的 README。

还要提供一句话的描述：npm 插件使用 package.json 的 description，Git 插件使用 manifest 的 description。缺少描述时，审查者可以在注册表中补上。

其他语言

展示页以英文和简体中文显示。英文是必需的，翻译是可选的。在 paseo-plugin.json 中添加翻译后的 name 和 description，以语言标签为键：

{
  "id": "review-tools",
  "name": "Review tools",
  "description": "Reviews changes before merge",
  "translations": {
    "zh-CN": { "name": "审查工具", "description": "在合并前审查改动" }
  }
}

每个字段都是可选的，缺少的字段会显示英文。注册表在发布插件时检查 translations：键必须是除 en 之外的标准语言标签，每个值只能设置 name 或 description，且必须是非空字符串。Paseo 本身不读取 translations，因此这里的错误会导致发布失败，而不会影响安装。

要翻译概览，请在 OVERVIEW.md 旁边发布一份以语言命名的完整副本，例如 OVERVIEW.zh-CN.md。脚手架的 files 列表已经包含 OVERVIEW.*.md。当标签是语言代码为两个或三个字母、且不是 en 的标准语言标签时，注册表会把 OVERVIEW.<标签>.md 当作翻译，并忽略 OVERVIEW.backup.md、OVERVIEW.zh-cn.md 这类其他名称。OVERVIEW.old.md 这样的三字母名称会被当作一种语言，因此不要用它命名非翻译文件。使用该语言的读者会看到翻译；其他读者会看到英文概览和一条提示。上面的概览规则同样适用于翻译，因此 OVERVIEW.md 变更时请同步更新翻译。审查者可以在注册表中补充或修正翻译。

图标和截图

主题、面板以及其他带可视界面的插件，需要至少一张展示当前界面的图片。请使用示例数据并隐藏隐私信息。只有图标不满足这项要求；没有自己可视界面的插件不需要截图。

发布之前，在 paseo-plugin.json 中声明本地图片：

{
  "id": "review-tools",
  "name": "Review tools",
  "description": "Reviews changes before merge",
  "icon": "assets/icon.png",
  "media": ["assets/screenshot.png"],
  "requirements": { "paseo": ">=0.11.0" }
}

创建所引用的文件；对于 npm，把 assets/ 加入 package.json 的 files 列表。路径相对于 manifest，使用正斜杠，并且必须位于插件目录之内。这些元数据字段需要 Paseo 0.11.0 或更高版本。

字段	展示行为
name	可选的显示名称；默认是把插件 ID 转换成易读形式。
icon	可选的、相对于包的 PNG 路径。Provider 注册图标有单独的 SVG 约定。
media	相对于包的路径或公开的 HTTPS URL。图片：PNG、JPG、JPEG、WebP 或 GIF。视频：MP4 或 WebM。第一张图片是卡片缩略图；视频作为补充。

公开的媒体 URL 需要带有受支持的文件扩展名（不区分大小写），并且必须以对应的图片或视频内容类型返回 HTTP 200。SVG 和没有扩展名的附件 URL 不能作为注册表媒体。

除了声明 media，你也可以在提交或审查 PR 中提供合适的公开图片 URL。审查者可以把它们添加到展示页，无需发布新的插件版本。

发布到 npm

1. 设置包的标识

使用一个你有发布权限的 npm scope，并通过 npm login 登录。在插件目录中，把下面的 @acme 和仓库替换为你自己的值：

npm pkg set name=@acme/paseo-review version=1.0.0
npm pkg delete private
npm pkg set repository.type=git repository.url=git+https://github.com/acme/paseo-review.git

当前的注册表工具要求通过 package.json 或 npm provenance 提供一个 GitHub 仓库，用来确定 npm 展示页的归属。请把 repository 设置为你公开的源码仓库，以便固定版本时可以确定展示页的所有者。provenance 本身是可选的；如果存在，它的仓库必须与包的仓库一致。审查制品时不需要匹配的源码检出。

2. 锁定安装的依赖

把 Paseo 宿主提供的库和仅用于类型的依赖放在 devDependencies 中。把其他运行时库加入 dependencies。提交到注册表时，每棵安装的依赖树都需要一个锁文件，包含确切的版本、解析来源和完整性校验，传递依赖也不例外。

对于带有运行时依赖的 npm 包，请在不运行生命周期脚本的情况下更新它的锁文件，然后创建可发布的锁文件：

npm install --package-lock-only --ignore-scripts
npm shrinkwrap

npm shrinkwrap 会把 package-lock.json 转换为 npm-shrinkwrap.json。npm 会在包的根目录发布 shrinkwrap 文件，但不会发布 package-lock.json。只存在于仓库中的锁文件或确切的直接依赖版本，并不能锁定用户安装的依赖树。

只使用宿主提供的库和开发依赖的插件不需要运行时锁文件，除非某个准备命令会安装这些依赖。你也可以把库打包进插件，并移除运行时依赖声明。如果你的插件会安装一棵单独的依赖树，请参阅准备与额外设置。

3. 检查包并发布

在检查包之前生成所有需要的文件；dry run 会跳过打包脚本。

npm run typecheck
npm pack --dry-run --ignore-scripts

检查文件列表是否包含 paseo-plugin.json、至少一个运行时入口、每个被导入的本地模块、你声明的所有概览和资源文件，以及需要时的 shrinkwrap 文件。只在仓库中存在的导入别名和包外的文件不会到达用户手中。脚手架已经包含了入口以及 client/、server/ 和 shared/；请把其他资源目录加入 files。

确认所有声明的准备命令在你支持的 Node/npm 版本下都能成功；不同步或不兼容的锁文件仍然会阻止安装。

发布检查过的版本：

npm publish --access public

在测试用的 daemon 上，安装这个确切的已发布版本，并试用它的各项贡献：

paseo plugin install npm:@acme/paseo-review@1.0.0
paseo plugin ls

确认状态为 running 且没有错误，然后提交这个包。

通过 GitHub 或 Git 分享

对于公开注册表，请把插件推送到一个公开的 GitHub 仓库。包含它的 manifest、运行时入口、被导入的文件和展示页资源。提交时 Git 标签和提交是可选的；提供一个即可选择某个修订，否则审查者会解析 main。

如果准备过程会安装运行时 npm 依赖，请提交一个同步的 package-lock.json，并把以下命令加入 paseo-plugin.json：

{
  "build": [["npm", "ci", "--omit=dev", "--ignore-scripts"]]
}

npm ci 使用已提交的锁文件，如果它与 package.json 不一致就会失败。--omit=dev 排除开发工具，--ignore-scripts 禁止依赖的生命周期脚本。daemon 的命令路径中需要有 npm。只使用宿主提供的库的插件不需要准备命令。生成文件或显式脚本见准备。

用户可以不经注册表展示页，直接从 Git 安装：

paseo plugin add git:acme/paseo-review
paseo plugin add git:acme/monorepo:plugins/review

使用 --ref 为首次安装选择分支、标签或提交。只要 daemon 有访问权限，直接安装也支持私有仓库和其他 Git 托管平台；见插件来源。注册表提交接受公开的 GitHub 来源和公开的 npm 包。

插件注册表

打开提交表单。请使用该表单，这样 issue 才会获得启动收录流程的提交标签。

1. 用插件的名称作为标题。
2. 在 Source 中填写公开的 npm 包名或页面，或 GitHub 仓库/文件夹的 URL。如果你希望审查某个特定版本，请附上版本号或 Git 引用。npm 默认使用 latest。注册表 ID 和本地目录不能作为提交来源。
3. 选择合适的分类。把所有界面图片的 URL 写在 issue 描述中。

机器人会打开一个审查 PR。审查者在不运行插件代码的情况下检查制品和依赖，完善展示页，并记录被批准的确切版本或提交。发布需要符合审查政策，包括锁定的安装输入和恰当的数据访问，即使自动校验已经通过。

如果被要求修改，请在审查 PR 中回复修正后的版本或修订，或所要求的图片 URL。审查者会更新固定的版本和展示页。收录服务的错误会自动重试；缺少图片或概览不会妨碍打开审查 PR。

获得批准并发布后，用户可以这样安装你的插件：

paseo plugin add owner/slug

npm 发布会自动收到更新 PR。Git 更新需要手动提交所需的修订。已有的注册表安装使用被批准的固定版本；直接通过 npm/Git 安装的插件遵循来源参考中各自的更新规则。

带构建步骤的插件

Paseo 会编译 TypeScript，因此普通插件不需要单独的发布构建。请把生成的模块放在它们的运行时目录中，并把宿主提供的模块保留为外部依赖。

Paseo 在获取包时会禁止 npm 生命周期脚本。manifest 的 build 中显式声明的命令仍然会运行，包括它们调用的脚本。请说明这些命令的用途，并让它们的输入保持锁定且可检查。当 npm 已经安装了生产依赖时，请从 npm manifest 中移除只用于 Git 的依赖安装命令。

之后安装另一棵依赖树的设置步骤需要它自己的完整锁文件，即使你的插件已经有一个开发用的锁文件。对于 npm 设置，请把运行时 manifest 和锁文件一起发布，并使用 npm ci。对于 Python 设置，请发布一个 requirements 文件，其中包含所有传递依赖包的确切版本和 SHA-256 哈希，然后这样安装：

python -m pip install --require-hashes -r requirements-documents.txt

该命令会拒绝未固定版本或没有哈希的依赖。运行时安装还需要满足上文所述的确认和披露要求。

私有 npm 包

:::example[用 GitHub Packages 发布私有包 {#publish-a-private-package-with-github-packages}]

你可以把公司内部的插件发布到 GitHub Packages。按照上面的 npm 步骤操作，使用你组织的 scope，并把发布命令替换为：

npm publish --registry=https://npm.pkg.github.com

发布之前，请先配置 GitHub 身份验证和包访问权限。

要安装插件，请在 daemon 主机上，以运行 Paseo 的用户身份配置 npm：

1. 把你组织的注册表加入 ~/.npmrc：

   @acme:registry=https://npm.pkg.github.com
   

2. 用你的 GitHub 用户名登录，并以一个 personal access token (classic) 作为密码。该令牌需要 read:packages 以及对该包的访问权限。

   npm login --scope=@acme --auth-type=legacy --registry=https://npm.pkg.github.com
   

3. 安装插件：

   paseo plugin install npm:@acme/paseo-review
   

Paseo 在安装和更新时使用主机的 npm 注册表设置和凭据。在应用中，只需输入来源标识符。

:::