# @pmate/cli 中文文档

规范地址：https://npmcn.com/package/%40pmate/cli/

版本：0\.42\.6
npm 元数据更新时间：2026-11-02T03:48:10.325Z
中文译文更新时间：2026-11-02T05:51:00.294Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40pmate/cli
原文对照：https://npmcn.com/package/%40pmate/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，23 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：22 个
- 首次发布：2025-12-24T09:54:09.709Z
- 最新版本发布：2026-11-02T03:48:10.103Z
- 已发布版本数：247（近 12 个月 247 个）

## 中文简介

pMate项目的CLI实用程序

## 安装

```sh
npm install @pmate/cli
```

也可以使用：`pnpm add @pmate/cli`、`yarn add @pmate/cli`、`bun add @pmate/cli`

## README

# pMate CLI

一个typescript驱动的命令行工具脚手架，用于未来的pMate自动化。

## 从独立的签出部署

虚拟部署拒绝 `--cwd`． 它们使用已注册存储库的传统本地签出(`~/dev/pmate/<repository>`)，拒绝任何未提交的更改（包括未跟踪的文件），获取最新的GitHub `main`，切换到 `main` 快进到那个修正版。丢失的遥控器 `main`在依赖项安装、构建或上传之前，切换/提取失败，或未推送/分歧提交的本地主程序终止。没有任何更改被存储、重置或丢弃。将依赖项安装为 `pnpm install --frozen-lockfile`;打印部署的提交SHA。提交和推送更改到 `main` 在部署之前。

静态业务和FC业务可以在不修改常规的情况下释放 `~/dev/pmate` 结账。使用 `pmate service deploy pmate:<service> --env prod --cwd /absolute/path/to/repo` 用于静态或FC服务。注册的服务目录相对于存储库根目录进行解析； `--cwd` 不会更改服务的已注册存储库或环境。

远程Node/Python/Rust部署仍然使用注册的存储库并拒绝 `--cwd` 而不是默默地忽略它。合并并推送预期的发布到 `main` 在部署之前。正常的服务部署历史和日志流保持不变。

## 开发

```bash
npm install
npm run dev -- --help
```

-   `npm run dev` 来执行TypeScript入口点 `ts-node`.
-   `npm run build` 将编译后的JavaScript发送到 `dist/`.
-   `npm start` 运行编译后的CLI (`dist/index.js`）。

## 使用

在运行 `npm run build`，你可以通过以下方式在本地调用CLI：

```bash
node dist/index.js --name Alice
```

当发布或链接(例如， `npm link`)，二进制文件将作为 `pmate`：

```bash
pmate --help
pmate --name Bob
pmate add-dns --type A --value 1.2.3.4 --rr api
pmate login
pmate login --app @pmate/chat
pmate sts
pmate oss list
pmate oss upload --file ./path/to/file --key assets/file.txt
pmate oss upload --file ./path/to/file --key upload/file.txt --bucket parrot-static
pmate pr
pmate commit
pmate commit --push
pmate pr merge
pmate linear update ENG-123 --title "Updated title"
pmate linear update ENG-123 --desc $'line1\nline2'
pmate linear create --account work --title "Issue title"
pmate linear cycle
pmate linear teams --account pcs
pmate notion view <page-id-or-url>
pmate notion create --parent <page-id-or-url> --title "Sprint Notes" --content "Initial notes"
pmate notion create --private --title "Private Notes" --file ./notes.md
pmate notion update <page-id-or-url> --file ./notes.md --append
pmate vercel projects
pmate vercel deploys --project web --last-week
pmate im1 health
pmate im1 threads --limit 20
pmate im1 threads --search "titlte" --limit 5
pmate im1 messages --thread "<conversationId-or-thread-name>" --limit 50
pmate im1 pending-mentions --hours 24 --context 10
pmate im1 reply --thread "<conversationId-or-thread-name>" --text "hello"
```

注:

-   `pmate pr` 开始规范化生成的PR标题 `feat:` ， `fix:` ，或者 `chore:` (正好后面一个空格 `:`）。
-   `pmate commit` 从本地更改创建ai生成的提交。
-   `pmate commit --push` 也将当前分支推到原点。
-   `pmate pr merge` 默认情况下使用squash merge并删除分支(`--squash --delete-branch`）。
-   每个应用程序 `.pmate.yaml` 两者都必须定义 `app` （CLI键）和 `dir` (仓库相对目录，例如： `apps/auth`）。

## 阿里云证书配置

你可以在里面设置阿里云的证书 `~/.pmate/config.yaml`：

```bash
aliyun:
  ak: your_ak
  sk: your_sk
  region: cn-hangzhou
  domain: example.com
```

## 线性导通

### 背景资料

当多个团队或工作空间共享一台机器时，由于混合API密钥和不明确的团队默认值，从CLI运行线性操作经常会失败。 `pmate linear` 通过支持多账户配置、每个回购覆盖和明确的团队/账户标志来解决这个问题。

目标是使票据操作在脚本和本地工作流中可重现：选择正确的帐户，确定地解析目标团队，然后运行create/view/update/list命令，而无需在浏览器中重新创建。

### 1)增加线性账户

添加一个或多个线性帐户到 `~/.pmate/config.yaml`：

```yaml
linear:
  teamKey: ENG
  accounts:
    - title: work
      apiKey: your_linear_api_key
      # optional default team for this account
      teamKey: ENG
    - title: personal
      apiKey: your_other_linear_api_key
```

规则:

-   `accounts[].title` 必须是独一无二的。
-   `accounts[].apiKey` 是必需的。
-   如果存在多个帐户，而您没有通过 `--account`， `pmate` 请求一次并缓存选择 `~/.pmate/linear-selection.json`.

### 2)（可选）每个存储库Pin帐户/团队

添加repo-local默认值 `.pmate.yaml`：

```yaml
linear:
  teamKey: ENG
  account:
    title: repo-work
    apiKey: your_repo_specific_linear_api_key
```

当 `linear.account` 存在于 `.pmate.yaml`，它默认用于该回购。

### 3)验证访问

使用这些命令来确认凭据和团队可见性：

```bash
pmate linear whoami --account work
pmate linear teams --account work
pmate linear cycle --account work --team-key ENG
```

### 4)通用工作流

```bash
# create
pmate linear create --account work --team-key ENG --title "Fix login timeout"
pmate linear create --account work --repl

# read
pmate linear view ENG-123 --account work
pmate linear comments ENG-123 --account work
pmate linear sub-issues ENG-123 --account work

# update
pmate linear update ENG-123 --account work --title "Updated title"
pmate linear update ENG-123 --account work --desc $'line1\nline2'
pmate linear comment ENG-123 --account work --body "Investigated and reproduced"

# list/filter
pmate linear user-issues "Ryan" --account work --status "In Progress"
pmate linear issues --account work --team-key ENG --cycle 82 --status "Todo" --limit 100

# create issue from current GitHub PR
pmate linear pr --account work
```

## 身份验证会话

`pmate login` 将会话存储在 `~/.pmate/session.json`． 文件现在保存了 多应用程序会话注册由应用程序id键，所以登录到一个应用程序不再 覆盖另一个应用程序的会话。使用 `--app <app-id>` 进行身份验证 一个特定的应用程序；默认值保持不变 `@pmate/cli`.

注:

-   现有的单会话文件在第一次读取时自动迁移。
-   平台命令，例如 `pmate sts`， `pmate function`, `pmate app` 仍然 默认为 `@pmate/cli` 会话。

## IM1 / CC消息

`pmate im1` 通过local读取抄送消息 `cc-bot` 服务 `http://localhost:39223` 默认情况下。用覆盖基URL `PMATE_IM1_BASE_URL` 仅在调试另一个本地服务实例时使用。

有用的命令:

```bash
pmate im1 health
pmate im1 threads --limit 20
pmate im1 threads --q Bug --limit 10
pmate im1 threads --search "titlte" --limit 5
pmate im1 messages --thread "<conversationId-or-thread-name>" --limit 50
pmate im1 reply --thread "<conversationId-or-thread-name>" --text "hello"
```

`threads` 和 `messages` 默认输出JSON。线程行包括 `conversationId` 和 `threadKey`;更喜欢 `conversationId` 当编写脚本或 返回一个线程 `messages`/`reply`． 添加 `--text` 为紧凑 人类可读的输出。

使用 `pmate im1 threads --search "<title>"` 用于模糊标题查找。比较 针对具有编辑距离的线程标题的小写搜索文本，包括 附近的token/window匹配诸如 `titlte` vs `title`． JSON输出 包括 `searchDistance` 和 `searchScore`.

中的CC同步由后台服务拥有 `~/dev/pcs/cc-bot`，它运行 在PM2下，保持TimescaleDB运行，侦听新的CC消息并执行 限定3天回填。 `pmate im1` 是CC-only，不接受 `--source` 或自定义 `--endpoint` 选项。

## 配置概念

将一个概念集成令牌添加到 `~/.pmate/config.yaml`：

```bash
notion:
  token: your_notion_integration_token
```

## Vercel配置

添加默认的Vercel作用域到 `~/.pmate/config.yaml`：

```yaml
vercel:
  scope: pancakeswap
```

用法:

```bash
pmate vercel projects
pmate vercel projects --scope another-team
pmate vercel deploys --project web --last-week
pmate vercel deploys --project web --scope pancakeswap
```

注:

-   `pmate vercel` 是否安装了薄包装 `vercel` CLI。
-   V1只支持 `vercel.scope` 在PMate配置。
-   `pmate vercel deploys` 需要 `--project <name>`.

# 服务日志

服务日志使用相同的经过身份验证的API `dev.pmate.chat`． 源是专用服务器上注册的服务/主题对 `log` 链。

```sh
pmate service log pmate:issues-api --topic application --page 0 --json
pmate service log pmate:issues-api --topic nginx --field status=500
pmate service log pmate:issues-api --field requestId=<id>
```

页面是从零开始的。列表和 `--search` 覆盖链条配置的留存期（生产中30天）。 `--since-ms` 添加epoch-millisecond的下界。 `--field name=value` （可重复的标量JSON值）和 `--env` 服务器上的过滤器。主题是独立的来源，例如 `application`， `nginx`， `pm2`， `deployment`， `pv`, `vitals`;自定义字段 `data`． 老 `--type`， `--level`， `--source`, `--request-id` 旗帜被移除。遗留 `--app` 参数是可选的，不会选择不同的源。

当前CLI会话在内存中交换为 `pmate:developers`;激活的App和会话文件保持不变。如果需要，运行 `pmate login --app pmate:developers`． 权限拒绝永远不会退回到匿名Indexer读取。凭证永远不会打印。

### 日志分析工具

`pmate logs` 公开美丽所使用的相同的只读工具。服务器使用查询id和覆盖率元数据计算有界保留窗口的结果；该模型不计算采样页面。

```sh
pmate logs schema --json
pmate logs query pmate:apps-api --topic application --field level=error --json
pmate logs aggregate pmate:hello --topic pv --from 2026-10-08T00:00:00+08:00 --to 2026-10-08T10:00:00+08:00 --group-by path --interval hour --timezone Asia/Shanghai --json
pmate logs trace pmate:developers-api --request-id REQUEST_ID --json
pmate logs compare pmate:hello --topic pv --from 2026-10-08T00:00:00+08:00 --to 2026-10-08T10:00:00+08:00 --compare-from 2026-10-07T00:00:00+08:00 --compare-to 2026-10-07T10:00:00+08:00 --json
```

PV计算页面浏览事件；sessions deduplicate appId/accessId；Profile UV删除appId/profileId。丢失的id和匿名事件是分开的。查询/跟踪默认应用程序；聚合/比较默认值pv。重要百分位数要求 `--field name=LCP` （或其他特定指标）。当前用户分类是查询窗口内的访问频次；首次/新用户不能从保留有限的历史中推断出来。

时间窗口是 `[from,to)` 最多31天，在配置的保留时间内。时间接受Unix毫秒或带有明确时区的ISO。比较需要相同的时间。超过10,000条记录/100页/100组将被拒绝，而不是报告部分总数。索引和浏览器遥测仍然是最好的努力； `completeRead` 并不是真实世界活动的证明。查询页是从零开始的。

美丽的主人可能会通过 `--actor-profile-id` 与 `PMATE_LOG_DELEGATE_TOKEN` 在儿童环境中。该模式从不读取或交换主机的个人CLI会话。Auth API在每次调用时验证allowlist Bot和实际发送方的pmate:dev权限。模型不能提供参与者或令牌。

### 打包桌面应用

已打包的安装程序会自动上传到阿里云OSS (`parrot-static`)，使用与Android APK版本相同的凭据。完成输出和构建报告包括公共下载url、SHA-256校验和和 `release.json` URL。配置 `oss.public.region` 和 `aliyun.ak/sk` 在PMate配置中。冲突的发布版本需要应用程序版本碰撞。 `--dir` 只产生本地未打包的输出； `--dry-run` 不能上传。电子构建器完成后CLI拥有发布权；electron-builder仅接收不可变的通用发布URL以生成有效的包元数据，并在禁用发布的情况下运行。

`pmate service deploy <ns:electron-service>` 打包一个本机shell，直接加载其配置的HTTPS源，不需要构建或嵌入web资源，并生成macOS DMG/ZIP或Windows NSIS/ZIP工件。打包发布需要CLI登录，并在app命名空间中拥有admin权限； `--dry-run` 只打印计划； `--local` 使构建工件保持本地，并且是必需的 `--unsigned` 或者 `--dir`． 有符号的构建是默认的； `--signed` 仍然接受了。服务类型必须是electron， repository/dir定位源，appid必须只包含一个应用程序标识，可选的构建设置包括config（相对于服务目录，默认是desktop.config）。Json)，平台和arch。桌面配置应用必须与关联的应用匹配，而不是与服务ID匹配。平台和架构默认为主机和节点架构；输出默认为release/在存储库根。 可选桌面配置notyprofile选择本地Keychain配置文件；APPLE\_KEYCHAIN\_PROFILE会覆盖它。macOS的发布需要Developer ID签名、公证和Gatekeeper验收。第一个构建下载固定的Electron和电子构建器版本。当前目标：macOS和Windows； `arm64` 和 `x64`;macOS包需要一个macOS构建主机。

```sh
pmate service deploy pmate:merry-electron
```

配置模式2 (`icon` 是相对于配置文件的；通过移除迁移模式1 `web` 和改变 `schemaVersion` 2):

```json
{
  "schemaVersion": 2,
  "app": "pmate:hello",
  "productName": "Going Merry",
  "bundleId": "chat.pmate.goingmerry",
  "version": "0.1.0",
  "origin": "https://hello.pmate.chat",
  "authOrigins": ["https://auth.pmate.chat"],
  "externalOrigins": ["https://github.com"],
  "icon": "desktop/icon.png"
}
```

`externalOrigins` 是可选的。当应用程序文档启动时，在系统浏览器中打开指向这些确切源的链接，即使相同的源也被允许进入 `authOrigins`;隔离的身份验证窗口继续在内部导航。

使用 `--dry-run` 为了检查计划， `--dir` 打开包装 `.app`，或者 `--signed` 要求配置macOS签名身份。默认构建是临时签名的，供本地使用；它们不是经过公证的发行版本。签名构建使用电子构建器的标准签名/公证环境变量；出具公证书前需单独核实。

shell加载部署的HTTPS网站。打包只需要桌面配置、图标和本机运行时依赖项：不需要前端包管理器、源代码树或 `dist` 是必要的。Web UI，业务逻辑和兼容的前端桥SDK更改通过Web部署；下一次打开或用户刷新接收它们。不要自动重新加载正在进行的对话或呼叫。仅当安装的预加载/主进程桥接代码、本机功能/权限或Electron运行时必须更改时，才重新构建安装程序。第一次从嵌入式渲染器迁移需要一个新的安装程序。

`@pmate/bridge` 提供了 `getDesktopBridge()`、运行时 `appVersion`， `electronVersion`， `bridgeVersion`， `contentSource`，以及可调用能力检测。npm SDK版本与安装的主机协议无关。缺失的主机功能必须显示为不支持或需要shell升级；永远不要从电子引擎版本中推断它们。预加载api只暴露给配置好的origin的主框架；验证窗口不接收本机api。IPC在禁用Node、启用沙箱和上下文隔离的情况下验证发送方和帧。 本地脱机页面提供重试，而不清除现有的用户数据分区。网站CSP和缓存策略适用于远程页面。

验证更改 `pnpm exec vitest run src/tests/electron*.test.ts` 和 `pnpm typecheck`． 与 `PMATE_TEST_ELECTRON_PATH` 指向一个电子可执行文件，运行 `node scripts/test-electron-online-runtime.cjs` 用于真正的HTTPS加载，web修订更改而无需重建，IPC隔离，离线重试和数据持久化。集 `PMATE_TEST_LIVE_ORIGIN=https://merry.pmate.chat` 包括生产SPA装载。运行 `node scripts/test-electron-calls-runtime.cjs` 用于隔离的呼入流。证书绕过仅限于本地测试过程；生产代码保持启用证书验证。

本机应用程序菜单包括 **检查更新…**，通过apps-api检查已安装的shell版本，并在确认后打开经过验证的安装程序。安装仍然是手动的。每个构建都打印其工件目录和签名报告；打包发行版上传安装程序并注册版本； `--dir` 保持当地。

### 日志统计默认口径

请求次数与日均可使用 `pmate logs aggregate pmate:issues-api --metric count --topic application --field event=http.access --interval day --timezone Asia/Shanghai --from <ISO> --to <ISO> --json`。计数由数据库完成，返回 `count`、`durationDays`、`averagePerDay`1、、、、、、、、、Json: http://jin `error.code`，区分权限、保留期、查询预算和上游故障，避免泄露上游原始错误。

### 桌面版注册表

桌面客户端需要一种稳定的方式来发现发布版本，而不需要知道它们的版本化OSS路径。Apps-api拥有这个索引；安装程序元数据和校验和保留在OSS中 `release.json`.

`GET https://apps-api.pmate.chat/versions/pmate:hello?platform=mac&arch=arm64` 是公共的并返回 `{ success: true, data: { app, version, platform, arch, manifestUrl, publishedAt, publishedBy, id } }`． 丢失的版本返回404；这并不意味着安装的客户端是当前的。支持的目标有 `mac|win` 和 `arm64|x64`． 只有稳定的 `major.minor.patch` 发布版本。

安装程序及其不可变清单上传成功后，构建调用 `POST /versions/:appRef` 与 `{ version, platform, arch, manifestUrl }` 使用现有的CLI会话。Apps-api需要名称空间管理员权限，并验证官方清单标识和安装程序元数据。旧版本永远不会取代相同目标的更高版本。 `PMATE_APPS_API_BASE_URL` 选择发布者API；分布式客户端查询生产API。

注册失败会导致发布命令失败，同时保留已经上传的安装程序。一旦修复了API访问，在构建报告中重试带有清单URL的相同POST；不要在该版本下重新构建不同的字节。手动注册已经发布的版本是幂等的。原生检查有一个超时，拒绝不匹配的目标和外部下载主机，从不清除用户数据或重新启动应用。

### Android发布签名

`pmate service deploy <ns:android-service>` 解析来自该服务的服务器端环境的签名凭证（不使用主机变量和本地签名环境变量）。配置 `ANDROID_KEYSTORE_BASE64`， `ANDROID_KEYSTORE_PASSWORD`， `ANDROID_KEY_ALIAS`, `ANDROID_KEY_PASSWORD` 再加上机密 `ANDROID_SIGNING_CERT_SHA256` 如预期的证书指纹。Android SDK `apksigner` 必须安装。CLI对Gradle发布APK进行签名，并在上传前验证其证书；缺少凭据、无效签名或指纹不匹配将停止发布。Keystore文件使用受限制的临时存储，并在签名后删除。现有的应用程序必须保留其兼容的签名密钥。调试版本会保留现有的Gradle签名行为。

### iOS TestFlight构建

在带有Xcode的macOS上，一个已登录的苹果开发者帐户，有效的签名配置文件和一个现有的App Store Connect应用程序：

```sh
# First build on this machine: import the highest Build already used in Apple.
pmate service deploy td:time-duck-ios --last-build 2026101501
# Subsequent builds on this machine:
pmate service deploy td:time-duck-ios
```

`service deploy` 对于ios存档类型的服务，直接上传到App Store Connect for TestFlight。它保留了营销版本(例如 `0.1.0`)，只对整型Build加1。它没有发布App Store版本。 `uploaded-processing` 表示苹果接受了上传；处理和TestFlight下载可用性需要单独验证。

注册一个 `ios` 服务与 `repository` 和 `dir`. `--cwd` 覆盖存储库根； `--project` / `--workspace` 路径是相对于app目录的。除非明确选择，否则只需要一个已发现的项目/工作空间。总是提供 `--scheme`； `--team` 覆盖项目的签名团队。 `--json` 返回上传后的版本、构建、存档和日志路径。

每个营销版本的第一次调用需要 `--last-build <highest-used-build-for-this-version>` （0只适用于新版本）。下一个Build比该版本的项目值、导入值和本地保留序列的最大值大一个。保留，包括失败的构建，在每个版本中单独保存。要迁移发布的基于日期的数字，首先增加MARKETING\_VERSION并将CURRENT\_PROJECT\_VERSION设置为0，然后导入0以使新版本从构建1开始。 在本命令行外或其他机器上上传后再次导入当前Apple maximum；此命令不查询Apple的构建历史。不要降低或删除序列来重复使用一个数字。Burgess自动执行Apple历史检查和版本迁移。

序列，保留的档案，派生的数据和日志 `~/.pmate/ios-builds/`． 不更改项目/源版本文件。bundle级别的排他锁防止在同一台机器上同时构建；它不协调不同的机器。构建/上传失败保留保留的数量和日志；重试消耗下一个号码。在一个中断的过程之后，去掉剩余的 `.lock` 只有在确认没有构建仍在运行后才使用。构建需要自动签名；解决Xcode中的Apple帐户/证书/配置文件错误。具有固定plist版本的扩展或应用目标必须生成匹配的存档元数据，否则上传将停止。

`pmate service deploy <ns:service>` 默认为 `--env prod` 对于每个服务。使用显式的 `--env preview` 或者 `--env dev` 来推翻它。例如, `pmate service deploy pmate:merry` 部署生产站点 [https://merry.pmate.chat](https://merry.pmate.chat/).

### 统一的本地服务部署

Web、iOS和Electron使用不同的服务。按注册类型部署分派，不带——target。iOS商店方案/团队和可选项目/正在构建的工作空间；现有的移动捆绑包身份保持不变。iOS和Electron部署目前只支持prod；Android支持dev/preview/prod。用——cwd、——scheme、——team、——project、——workspace或电子专用的——config、——platform、——arch和——out-dir覆盖注册的设置。不支持的选项显式失败。 iOS——dry-run在不运行Xcode或上传的情况下解析注册计划。

```sh
pmate service deploy pmate:merry
pmate service deploy pmate:merry-ios
pmate service deploy pmate:merry-electron
pmate service deploy pmate:merry-electron --local --unsigned
```

App构建和ios服务构建被移除；使用服务部署。本地运行和演练运行不会创建成功的部署历史记录条目。iOS上传成功被记录为上传处理，而不是TestFlight可用性。

### Android通过服务部署

Android服务的使用 `pmate service deploy pmate:merry-android`． 主要服务是pmate:merry-android。它的建立。artifactServiceId是pmate:factory-android: APK路径和旧的更新清单仍然与已安装的客户端兼容，这也限制了APK下载到旧路径。生产部最新出版相同。将Json转换为新服务和遗留工件标识。包factory.pmate.app和签名身份不变。迁移时复制现有的服务器端签名秘密。 服务构建设置接受变体（发布/调试）和碰撞（补丁/次要/主要）；默认是release和patch。生产环境拒绝调试变量。Android支持dev/preview/prod；预览版不会更新生产版的latest.json。

使用——variant、——bump、——force、——release-notes或——minimal -version-code来覆盖发布选项。-dry-run打印计划，不增加版本，解决签名秘密，构建或上传。Android目前不支持——local/——unsigned。服务apk版本被移除；服务apk列表仍然是一个查询。

HarmonyOS NEXT项目存在于parrot-native （apps/pmate-app-harmony和apps/time-duck-harmony）中。他们已经签署了构建脚本和GitHub动作工作流；CLI 0.42.0+还支持通过业务部署方式创建harmonyos服务。AppGallery提交是单独的。

Android生产版本在更改源代码版本或加载签名秘密之前会检查现有的当前和兼容性更新清单。候选版本码必须超过所有已发布的版本码；过期的签出被拒绝，必须显式更新。上传前APK包标识必须与注册服务匹配。

### HarmonyOS分布

`pmate service deploy pmate:merry-harmony` 调度和谐服务。mobile持有bundleName、repository和dir；构建。脚本默认为scripts/build-release.sh。服务必须只关联一个应用ID。源AppScope/app。Json5控制发布版本。只支持prod。——在没有SDK或秘密的情况下，预演检查计划；本地构建验证签名工件而不需要上传；——out-dir覆盖本地输出基。其他平台的标志被拒绝。

安装DevEco SDK、ohpm、Hvigor和Java。配置DEVECO\_SDK\_HOME， OHPM\_BIN, HVIGORW\_BIN，可选NODE\_BIN， JAVA\_BIN和HAP\_SIGN\_TOOL非默认安装。服务prod秘密：HARMONY\_KEYSTORE\_BASE64、HARMONY\_CERTIFICATE\_BASE64、HARMONY\_PROFILE\_BASE64、HARMONY\_STORE\_PASSWORD、HARMONY\_KEY\_ALIAS和HARMONY\_KEY\_PASSWORD。不使用本地签名变量。缺少工具或凭证会阻止真正的构建。

构建运行在私有的临时源/SDK副本中。CLI验证APP、HAP和嵌入式模块签名、签名者证书和编译的身份/版本，然后上传文件和不可变发布。Json在harmony下///// in parrot-static，然后是latest.json。现有或更旧的版本将被拒绝。本机服务历史记录了清单URL。清除签名密钥和临时源；日志和验证的本地输出保持在~/下。默认为Pmate /harmony-builds/。 出版是指OSS发行，而不是AppGallery提交、批准或设备安装。

HarmonyOS发布在未版本的OSS桶中使用所有权检查服务锁，并禁止覆盖不可变文件。它在锁下再次检查最新版本。中断的出版商可能会留下一个锁；在清理之前确认他们已经停止。CLI不会自动窃取过期的锁。

## Bot配置文件昵称

### 背景

聊天显示一个机器人的配置文件 `nickName`． 要更改显示名称而不更改bot的内部名称、帐户、凭据或代理配置，请更新现有配置文件：

```bash
pmate account bot profile update --app pmate:merry --name blackbeard --nickname "黑胡子BOT" --json
# Equivalent shortcut:
pmate account bot nickname --app pmate:merry --name blackbeard --nickname "黑胡子BOT" --json
```

`--name` 返回的bot的内部名称是 `pmate account bot list --app pmate:merry --json`． 这两个命令都需要现有的CLI登录，使用活动会话，并依赖于身份验证API的配置文件更新权限。在指定的应用程序中，它们只需要一个bot帐户的配置文件；缺少或多个配置文件导致错误而不进行写操作。这些命令从不创建配置文件。

CLI只更新 `nickName` 通过 `PUT /profile`，然后轮询配置文件索引大约10秒，并返回经过验证的配置文件。匹配的昵称是不允许的。如果验证超时，则可能已经应用了更新；重试前检查配置文件。 `--base-url` 为所有请求选择验证API。

## 常见问题

### @pmate/cli 是什么？

pMate项目的CLI实用程序

### 如何安装 @pmate/cli？

在项目目录运行 npm install @pmate/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pmate，可以用 npx pmate 直接运行。

### @pmate/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @pmate/cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @pmate/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @pmate/cli 可以商用吗？

@pmate/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @pmate/cli 还在维护吗？

最新版本 0\.42\.6 发布于 2026/11/02（1 天前）；至今共发布 247 个版本，其中过去 12 个月发布了 247 个；首次发布于 2025/12/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。