# @crvouga/mockingbird-service-plane 中文文档

规范地址：https://npmcn.com/package/%40crvouga/mockingbird-service-plane/

版本：3\.10\.7
npm 元数据更新时间：2026-11-03T01:27:16.657Z
中文译文更新时间：2026-11-11T08:28:59.491Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40crvouga/mockingbird-service-plane
原文对照：https://npmcn.com/package/%40crvouga/mockingbird-service-plane/?lang=original
项目主页：https://github.com/crvouga/mockingbird/tree/main/packages/service/plane#readme
源码仓库：https://github.com/crvouga/mockingbird

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

- 包体积（解压后）：4.4 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-09-22T23:56:37.224Z
- 最新版本发布：2026-11-03T01:27:16.242Z
- 近 30 天下载量：2633（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

Plane REST API v1的状态仿真器:光标所标的工作项目,注释,链接,状态和标签,有Plane的速率限制和出错形状.

## 安装

```sh
npm install @crvouga/mockingbird-service-plane
```

也可以使用：`pnpm add @crvouga/mockingbird-service-plane`、`yarn add @crvouga/mockingbird-service-plane`、`bun add @crvouga/mockingbird-service-plane`

## README

# @crvouga/mockingbird-service-plane(英语:

> 本地模拟器。 真正的API合同. 部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

国家模拟器 **飞机** REST API (v1) 用于测试套房, 涵盖我们的错误报告 解析和解析任务需要一个项目:工作项目(Plane的光标被涂上列表,获取, 创建,补丁,注释,链接,状态和标签,带有Plane的速率限制和出错形状. 项目以 Plane 默认工作流程( Backlog, Todo, In) 提供第一使用 进展,完成,取消),所以不需要设置.

-   行动范围: [支助](https://github.com/crvouga/mockingbird/blob/main/packages/service/plane/SUPPORT.md)
-   合同`openapi.yaml`由Plane的API参考文献和消费者的 佐德计划( zod schemas )`plane-response.ts`) (中文(简体) ).

## 安装

```bash
npm install -D @crvouga/mockingbird-service-plane
```

仅限无害环境管理。 节点 22或 Bun 1.2. 无土生属地. 给它服务 `npx mockingbird-plane serve`, (中文(简体) ), `createServer` 从 `./server` (节点),或 `createRuntime` 与 任何获取服务器.

## 使用量

后端硬码 `https://api.plane.so` (单位:千美元)`plane-http-client.ts`连接 **G-Y1级**: 让它 (原始内容存档于2013-10-12). env-驱动. 把它指向模仿者; `PLANE_ACCESS_TOKEN`, (中文(简体) ), `PLANE_WORKSPACE_SLUG` 财务报告和审定财务报表 `PLANE_BUGS_PROJECT_ID` 可以是任意值( 工程 ID 必须是一个 UUID, 因为我们的配置 验证).

```bash
npx mockingbird-plane serve --port 8821 --rate-limit 60
```

在测试中,应用程序的Plane SDK(`@makeplane/plane-node-sdk`)将模拟器的 URL 当作 联合国 `baseUrl`数字 :

```ts
import { PlaneClient } from "@makeplane/plane-node-sdk"
import { createServer } from "@crvouga/mockingbird-service-plane/server"

// Test setup: a local Plane.
const server = await createServer()

// Application code: Plane's SDK. Only its base URL changes.
const plane = new PlaneClient({ baseUrl: server.url, apiKey: "plane_api_test" })
const projectId = "33333333-3333-4333-8333-333333333333"
const item = await plane.workItems.create("acme", projectId, { name: "Checkout fails on Safari" })

// Test control: resolve it the way a teammate would; the resolution watcher then sees group
// "completed".
await fetch(`${server.url}/__admin/work-items/${item.id}/state`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ state: "Done" }),
})

await server.close()
```

### 路线

全部在 `/api/v1/workspaces/{slug}/projects/{project_id}/`,与 `X-API-Key`。 。 。 . `{slug}` 这是你的 工作空间的弹片( r)`acme` (见例中).

| 路线 | 行为 |
| --- | --- |
| `GET work-items/` | `per_page` (≤100), `cursor=<per_page>:<page>:<is_prev>`, (中文(简体) ), `order_by` (默认) `-created_at`) (中文(简体) ). 飞机的信封: `results`, (中文(简体) ), `next_cursor`, (中文(简体) ), `prev_cursor`, (中文(简体) ), `next_page_results`, (中文(简体) ), `prev_page_results`, (中文(简体) ), `count`, (中文(简体) ), `total_count`, (中文(简体) ), `total_pages`, (中文(简体) ), `total_results`, (中文(简体) ), `grouped_by`, (中文(简体) ), `sub_grouped_by`, (中文(简体) ), `extra_stats`。一个错误的光标是 400 . |
| `POST work-items/` | `{name, description_html?, state?, labels?, priority?}` − 201带UUID `id`每个项目 `sequence_id`, (中文(简体) ), `state` (默认后台日志), `labels`, (中文(简体) ), `created_at`...未知状态/标签代号为 DRF 400s(`{"state": ["Invalid pk \"…\" - object does not exist."]}`); 缺少名称为 `{"name": ["This field is required."]}`。 。 。 . |
| `GET` 编号 : `PATCH work-items/{id}/` | 读取或部分更新`state`, (中文(简体) ), `labels`, (中文(简体) ), `name`, (中文(简体) ), `description_html`, (中文(简体) ), `priority`) (中文(简体) ). `completed_at` 随州之群. |
| `GET` 编号 : `POST work-items/{id}/comments/` | `{comment_html, access?}` • 201条评论. |
| `GET` 编号 : `POST work-items/{id}/links/` | `{url, title?}` ~ 201 链接; 相同的 URL 两次是 409 `{error, id}`。 。 。 . |
| `GET states/` | 该项目的工作流程规定:`id`, (中文(简体) ), `name`, (中文(简体) ), `group`, (中文(简体) ), `color`, (中文(简体) ), `sequence`, (中文(简体) ), `default`) (中文(简体) ). |
| `GET` 编号 : `POST labels/` | `{name, color?, description?}` − 201个标签;重复名称为409 `{error, id: <existing>}`。 。 。 . |
| `GET` 编号 : `POST cycles/` | 创建方式 `{name, description?, start_date?, end_date?, external_source?, external_id?}`。这两个日期必须同时存在或无效。 列表使用光标信封(默认为20行); `cycle_view=current` 返回空阵列。 其他意见: `all`, (中文(简体) ), `upcoming`, (中文(简体) ), `completed`, (中文(简体) ), `draft`, (中文(简体) ), `incomplete`。 。 。 . |
| `GET` 编号 : `POST cycles/{id}/cycle-issues/` | 邮政 `{issues: [<work item UUID>]}` 添加或移动项目并返回成员行,不重复。 获得最新字段的返回已分解的工作项目 。 未知/外国项目ID被忽略;缺失周期为404. 已完成周期拒绝添加 `CYCLE_COMPLETED`。 。 。 . |
| `GET work-item-types/` | 包括稳定的UUID、名称、, `project_ids`,默认/活性旗帜和时间戳。 此端点没有光标 pagination . |

种子类型通过 `POST /__admin/work-item-types`,然后发送 `type_id` 关于工作项目的创建或 补丁。 都回来 `type_id` 财务报告和审定财务报表 `type`和飞机一样 [工作项目序列器](https://github.com/makeplane/plane/blob/c7a5afee6afd15f16038ebda1ec1489ebd8af67d/apps/api/plane/api/serializers/issue.py) 已经 未知的ID 以 DRF 失败 `type_id` 在任何字段或序列编号改变之前出错. 创建继承种子默认类型; 明确的补丁 `type_id: null` 释出.

周期日期使用 UTC 项目日及模拟时钟, 遵循 Plane [周期终点](https://github.com/makeplane/plane/blob/c7a5afee6afd15f16038ebda1ec1489ebd8af67d/apps/api/plane/api/views/cycle.py) 财务报告和审定财务报表 [日期转换器](https://github.com/makeplane/plane/blob/c7a5afee6afd15f16038ebda1ec1489ebd8af67d/apps/api/plane/utils/timezone_converter.py)数字 : 未来/过去开始时间为00:00:01,今天的开始时间是创作时间,结束时间为23:59:00. 当前过滤器包括两个端点. 周期计数随工作项目状态变化而来.

错误: 无密钥 401 `{"detail": "Authentication credentials were not provided."}`,外部键 `apiKeys` 401 (中文(简体) ) `{"detail": "Given API token is not valid"}`,未知项目/项目404 `{"error": "The requested resource does not exist."}`节奏429 `{"detail": "Request was throttled. Expected available in N seconds."}` 与 `x-ratelimit-*` 头.

### 管理员(超过标准合同)

| 路线 | 效果 |
| --- | --- |
| `POST /__admin/work-items/:id/state` | `{state: "<id or name>"}`: 移动项目(例如: `Done`就像队友一样. |
| `GET /__admin/work-items` | 命名空间的工作项目 . |
| `POST /__admin/projects` | `{workspace, project}`:现在提供一个项目;回答其状态和标签. |
| `POST /__admin/work-item-types` | `{workspace, project, types: [{name, description?, is_default?}]}`:种子项目类型元数据有稳定的ID;重复调用更新元数据并保存创建时间. 类型开始为空 。 无效的批次不会部分写入 . |
| `GET/PUT /__admin/settings` | `{apiKeys?, rateLimitPerMinute?: number | null, projects?: ["<slug>/<uuid>"]}`。 。 。 . `rateLimitPerMinute: 60` 复制模拟时钟上的平面限制; `projects` 已存在的指针(其他404). |

错误预设( E)`POST /__admin/faults {"preset": "<name>", "count"?: n}`: `rate_limited` (429个), `server_error` (500个), `bad_gateway` (502 HTML), (中文(简体) ), `unauthorized` (401个), `invalid_json` (200个) 非JSON读取, `network_drop`, (中文(简体) ), `slow` (15秒,超过10秒), `pagination_missing_cursor`, (中文(简体) ), `pagination_repeated_cursor`我们的客户在0,2和 8个,所以 `count: 2` 在第三次尝试中恢复 `count: 3` 预算用完; 写到 从来没有重复过.

### 命名空间

`x-mockingbird-namespace`页:1 `/__admin/ns/<name>` 前缀在基址上,或用 API 键: `PUT /__admin/credentials {"credentials": {"<PLANE_ACCESS_TOKEN>": "<namespace>"}}`。 。 。 .

### 故意不模拟

-   Plane webhooks(我们的应用民调),周期编辑/删除和非UTC项目时区,模块,页面,收录,附件,成员, 估计数、工作日志和 `expand=`。 。 。 .
-   删除工作项目,注释,链接或标签;存档.
-   供应商工作项目类型管理,定制类型计划,史诗和跨项目类型共享. 具有此列表/任务表面管理器控制的种子类型 .
-   丰富文本处理 : `description_stripped` 编号 : `comment_stripped` 是标记的文本.

## API 密码

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `PlaneAPI` | 类 | 进程模拟器 : `fetch(request)`, (中文(简体) ), `reset()`, (中文(简体) ), `ensureProject(slug, id)`, (中文(简体) ), `statesOf(id)`, (中文(简体) ), `labelsOf(id)`, (中文(简体) ), `moveToState(itemId, stateIdOrName)`, (中文(简体) ), `applyPatch(item, patch)`, (中文(简体) ), `workItems()`选项: `sqlite`, (中文(简体) ), `now`, (中文(简体) ), `namespace`, (中文(简体) ), `settings`。 。 。 . |
| `createRuntime` | 函数 | 全面服务合同的仿真器(保健、管理员、命名空间、证书、预设)。 选项 : `settings`, (中文(简体) ), `clock`, (中文(简体) ), `seed`, (中文(简体) ), `adminKey`, (中文(简体) ), `onLog`, (中文(简体) ), `sqlite`。 。 。 . |
| `PLANE_PRESETS` | 对象 | 每个命名的断层预设. |
| `PLANE_NAMESPACE` | 字符串 | 服务名称, `"plane"`。 。 。 . |
| `DEFAULT_STATES` | 数组 | 新项目开始的工作流程. |
| `apiKeyCredential` | 函数 | 这个 `X-API-Key` 请求包含( 如何绘制命名空间的证书映射) . |
| `uuidFrom` | 函数 | 确定 v4 形状的 UUID 模拟器来自字符串 . |
| `document`, (中文(简体) ), `operationIds`, (中文(简体) ), `supportedOperationIds` | 数值 | OpenAPI合同及其操作代号. |
| `createServer`, (中文(简体) ), `serveTarget`, (中文(简体) ), `DEFAULT_PORT` (单位:千美元)`./server`(中文(简体) ) | 节点 | 服务过来 `node:http`; 数据 `serve` CLI目标(`--api-key`, (中文(简体) ), `--rate-limit`; 第8821号口. |

部分 [嘲笑鸟](https://github.com/crvouga/mockingbird)。 。 。 .

## 常见问题

### @crvouga/mockingbird-service-plane 是什么？

Plane REST API v1的状态仿真器:光标所标的工作项目,注释,链接,状态和标签,有Plane的速率限制和出错形状\.

### 如何安装 @crvouga/mockingbird-service-plane？

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

### @crvouga/mockingbird-service-plane 支持 TypeScript 吗？

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

### @crvouga/mockingbird-service-plane 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @crvouga/mockingbird-service-plane 可以商用吗？

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

### @crvouga/mockingbird-service-plane 的下载量有多少？

根据 npm 官方下载统计，@crvouga/mockingbird-service-plane 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,633 次，日均约 88 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crvouga/mockingbird-service-plane 还在维护吗？

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