# @aelinrezende/pipa 中文文档

规范地址：https://npmcn.com/package/%40aelinrezende/pipa/

版本：2\.7\.8
npm 元数据更新时间：2026-11-04T23:31:13.685Z
中文译文更新时间：2026-11-06T12:09:53.061Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40aelinrezende/pipa
原文对照：https://npmcn.com/package/%40aelinrezende/pipa/?lang=original
项目主页：https://github.com/aelinrezende/pipa#readme
源码仓库：https://github.com/aelinrezende/pipa

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

- 包体积（解压后）：626 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-agent-core \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-10-18T23:04:34.906Z
- 最新版本发布：2026-11-04T23:31:13.518Z
- 近 30 天下载量：3265（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

皮包 que Carrega 外接 Pipa

## 安装

```sh
npm install @aelinrezende/pipa
```

也可以使用：`pnpm add @aelinrezende/pipa`、`yarn add @aelinrezende/pipa`、`bun add @aelinrezende/pipa`

## README

# 皮巴语

Pipa是一个管弦乐和 执行纪律的一揽子计划 [Pi 编码代理](https://github.com/earendil-works/pi)。 。 。 .

将Pi扩展为结构化的任务执行,分散的队友,持续 项目规划、知识管理、许可警卫和背景卫生.

## 安装

### 从 npm

```bash
pi install npm:@aelinrezende/pipa
```

锁定特定版本 :

```bash
pi install npm:@aelinrezende/pipa@2.3.2
```

### 来自 GitHub

```bash
pi install git:github.com/aelinrezende/pipa
```

### 项目安装

使用 `--local` 将 Pipa 注册在当前项目中 `.pi/settings.json`数字 :

```bash
pi install --local npm:@aelinrezende/pipa
```

## 何为 Pipa 添加

-   设置任意域的 Pipa 交互式登入 .
-   特定领域 `plan`, (中文(简体) ), `execute`,以及 `finish` 为项目创造的技能.
-   分散,坚持队友直接合作.
-   结构化的任务包括所有权、依赖性、班级和生命周期执行.
-   小执行步骤的会话级待办事宜列表 .
-   持续积压的史诗、故事、任务和错误修正项目.
-   一个有Markdown文件和模糊搜索的项目知识库.
-   授权守护终端命令和直接文件修改.
-   自动清理吵闹的模型上下文 .
-   英语和巴西葡萄牙语接口消息.

## 登入和配置

皮帕不以预先确定的专业重点为航线. 何时 `.pi/PROFILE.md` 不存在, 它开始一个互动的登入过程 来学习哪种 环境将支持、代理人应如何沟通、 它们必须尊重制约因素,以及应如何评价质量.

Pipa使用单一语言中性登机提示. 它首先试图推断 用户初始消息中的谈话语言。 如果信息也一样 pipa问道: 用户在继续前喜欢哪种语言。 在发现的时候,它也 确定生成的物剂和文物的工作语文;这可能有所不同 从第一个消息语言和配置的 UI 语言.

预先定义的答案只是发现辅助. 免费答复和后续 问题允许Pipa配置任何专门或混合的工作流程.

### 示例简介

| 简介 | 上载可能配置的 |
| --- | --- |
| 软件工程 | 堆放和建筑规则、代码质量、测试、部署、审查作用和技术文物 |
| 产品管理 | 发现、确定优先次序、用户研究、计量、决策记录和产品专家团队成员 |
| 财务 | 来源要求、分析假设、审查控制、报告标准和核准界限 |
| 游戏 | 设计或工程学科、发动机或中型设备、生产管道、创造性限制和游戏测试 |
| 写作和研究 | 听众、编辑声音、源标准、事实检查、审查流程和出版物格式 |
| 自定义或混合 | 用户自己的词汇、工作流程、制约因素、工具、质量标准和专家角色 |

上载创建项目的操作系统:

-   `.pi/PROFILE.md`: 共同目的,领域,语言,词汇,全球规则,约束,以及文物公约.
-   `.pi/skills/plan/SKILL.md`:工作如何理解,调查,分解,风险评估,审批.
-   `.pi/skills/execute/SKILL.md`:核定工作是如何下放、执行、验证和记录的.
-   `.pi/skills/finish/SKILL.md`:如何审查、报告、保存和关闭或移交结果.
-   `.pi/teammates/*.md`: 初步专家角色由简介提出并获得用户批准.

```mermaid
flowchart LR
    Start[First message] --> Language{Language clear?}
    Language -->|Yes| Discovery[Discover domain, working language, constraints]
    Language -->|No| Ask[Ask preferred language]
    Ask --> Discovery
    Discovery --> Profile[Create PROFILE.md]
    Profile --> Skills[Generate plan, execute, finish]
    Skills --> Roles[Propose specialist roles]
    Roles --> Team[Create approved teammates]
    Team --> Restart[Restart Pi]
    Restart --> Ready[Domain-configured Pipa]
```

`plan`, (中文(简体) ), `execute`,以及 `finish` 是为选定的域生成的;它们是 不是通用软件开发指令。 简介、技能和队友 定义是正则的Markdown文件,可以随环境而演化.

队友默认使用不偏重地方,基于角色的标识符. 如果人类的名字 首选时,登机请求使用语言、文化或命名风格 推断出一个来自UI本地或Pipa的起源.

## 有意见的工作流程

大部分的代理管弦乐手使用中央协调员. 工作流动情况 计划员或路由器,每个子代理都是为单一工作而创建的,然后 丢弃。 很简单,但它使协调员成为一个瓶颈,而且 交接会失去上下文.

Pipa采取不同的做法: **队友是分散的,自主的 持续.**

### 自治权

队友不等待主干员批准每一步. 它配置它指定的 报告结果。 任务警卫 保持这种自主性:队友必须先履行积极的任务,然后才能完成 可使用非管理工具.

### 没有中心路由器的协作

队友可以直接交谈.

-   `teammates → chat` 通过ID打开与另一名队友的同步对话. 这是状态检查、验证和调整的默认.
-   `teammates → send-inbox` 给一个忙碌且不应被打断的队友留下同步消息.
-   `spawnableTeammates` 让队友代表特定专家,每个专家都有明确的理由。 审查者可以要求开发者进行更正,也可以要求测试者进行更多的验证,而无需返回主代理.

主干员留监督. 它可以即兴发挥任何队友,但它是 不是在每一次交易的关键道路上.

### 队友在有用的时候留下来

队友不是一次性工人. 一旦队友有关于 项目、任务历史和以前的决定,其届会仍然可用.

-   这个 `online` 动作显示哪些队友有活动会话.
-   一个队友只能通过 `dismiss`有明确的理由,一旦不再需要.
-   任务动作后的可选会话收缩使得长寿的队友无法填补自己的上下文.

```mermaid
flowchart LR
    Main[Main agent / supervisor]
    Specialist[Domain specialist]
    Reviewer[Reviewer]
    Researcher[Researcher]

    Main -->|goal| Specialist
    Main -->|goal| Reviewer
    Specialist <-->|chat| Reviewer
    Reviewer -->|spawnableTeammates| Researcher
    Researcher <-->|inbox / chat| Specialist
```

|  | 集中式管弦乐 | 皮巴语 |
| --- | --- | --- |
| 协调 | 一切经过一个协调员 | 直接的队友聊天和收件箱 |
| 队友一生 | 每个请求创建, 然后丢弃 | 会话一直在线,直到解散 |
| 代表团 | 只有协调员代表 | 代表通过 `spawnableTeammates` |
| 问责制 | 取决于协调员 | 任务分配、依附关系和生命周期执行 |

## 工具

| 工具 | 目的 | 主要行动 |
| --- | --- | --- |
| `task` | 管理分配给代理人的业务工作 | `instantiate`, (中文(简体) ), `setup`, (中文(简体) ), `start`, (中文(简体) ), `update`, (中文(简体) ), `get`, (中文(简体) ), `list` 和进一步生命周期行动 |
| `teammates` | 发现、启动、沟通和开除队友 | `instantiate`, (中文(简体) ), `list`, (中文(简体) ), `online`, (中文(简体) ), `chat`, (中文(简体) ), `send-inbox`, (中文(简体) ), `read-inbox`, (中文(简体) ), `dismiss` |
| `todo` | 跟踪当前工作流程中的小执行步骤 | `instantiate`, (中文(简体) ), `update`, (中文(简体) ), `remove`, (中文(简体) ), `list`, (中文(简体) ), `clear` |
| `backlog` | 管理持续的项目工作 | `instantiate`, (中文(简体) ), `list`, (中文(简体) ), `select`, (中文(简体) ), `update-frontmatter`, (中文(简体) ), `update-body`, (中文(简体) ), `update-metadata`, (中文(简体) ), `remove` |
| `docs` | 维持项目知识库 | `instantiate`, (中文(简体) ), `list`, (中文(简体) ), `select`, (中文(简体) ), `update-frontmatter`, (中文(简体) ), `update-body`, (中文(简体) ), `update-metadata`, (中文(简体) ), `remove`, (中文(简体) ), `publish` |

## 任务执行

任务可以包含一个简短的名称,一个详细的描述,硬或软 依赖性 父母的任务 和团队.

依赖性可以是:

-   `hard`: 完全屏蔽执行直到依赖完成.
-   `soft`:记录信息依赖性而不阻碍执行.

队友在调用非管理工具前必须配置指定的任务. 这个 `task`, (中文(简体) ), `teammates`,以及 `todo` 工具仍然可用,以便代理人能够组织 其工作和从缺失的任务中恢复过来。 主要代理人担任主管 并且不受这个守卫的约束.

## 队友

队友是通过Markdown文件定义的本地专业特工. 管道载荷 与包捆绑在一起的队友和项目队友 `.pi/teammates/`。 。 。 .

在下放工作之前,代理人可以列出可用的队友. 队友是 附有一个包含必要背景、制约因素的具体目标, 和接受标准.

### 团队定义

创建诸如 Markdown 文件 `.pi/teammates/reviewer.md`数字 :

```markdown
---
name: reviewer
description: Reviews deliverables, verifies requirements, and identifies risks.
thinking: medium
spawnableTeammates:
  specialist: Requests a domain-specific correction
  researcher: Requests additional evidence
---

You are a rigorous reviewer for the domain defined in `.pi/PROFILE.md`.

Review the assigned artifact against its requirements. Identify correctness
issues, missing validation, risks, and unnecessary complexity.

Return actionable findings ordered by severity.
```

支持的前题字段 :

| 外地 | 需求 | 说明 |
| --- | --- | --- |
| `name` | 对 | 用于引用队友的独有小写标识符 |
| `description` | 对 | 对队友角色的简短解释 |
| `thinking` | 没有 | 队友使用的思维水平 |
| `spawnableTeammates` | 没有 | 队友可以即时攻击,每个代表团都有理由 |

主干员可以即时通知任何队友. 其他队友只能即兴表演 本人或队友名单 `spawnableTeammates`。 。 。 .

### 模型货币

皮帕可以将队友分配到候选模式中,以避免每一次发送 并行代理通过相同的模型队列。 模型循环可以通过 `error` 或者说 `concurrency` 事件和通过 `pipa.config.ts`。 。 。 .

## 待办事宜列表

这个 `todo` 工具跟踪当前执行流中的小步骤。 项目 支持状态 `pending`, (中文(简体) ), `in_progress`,以及 `completed`启用 `todo` 页:1 短清单, `task` 授权的工作,以及 `backlog` 长期 项目规划.

## 项目后置日志

这个 `backlog` 工具维护持续的项目工作,作为 Markdown 文档 结构化元数据.

-   项目类型: `epic`, (中文(简体) ), `story`, (中文(简体) ), `task`, (中文(简体) ), `bugfix`。 。 。 .
-   优先事项: `low`, (中文(简体) ), `medium`, (中文(简体) ), `high`, (中文(简体) ), `critical`。 。 。 .
-   物品可以有一个标题,Markdown正文,状态,域,标记,一个父项,以及任意的JSON元数据.

该工具支持筛选、排序、按标题、代码或标签选择元数据 更新、身体更新和删除.

## 项目文档

这个 `docs` 工具维持当地Markdown知识库。 文件支持 标题、摘要、标签、亲子关系、Markdown内容、, 任意的元数据、模糊的搜索、排序和过滤.

这个 `publish` 动作将文档导出至 Markdown 并生成静态 网站.

## 权限和护卫

Pipa在工具行刑时增加了护栏 但这不是安全沙盒.

-   终端命令根据命令政策进行验证,被归类为危险命令被屏蔽.
-   队友必须在使用非管理工具之前配置指定的任务.

这些检查补充了皮自己的安全模式. 它们不会取代操作 系统权限、寄存器保护、隔离环境或人 检讨.

## 二. 背景卫生

长期运行的代理工作流程可以累积被屏蔽的呼叫和被屏蔽的消息. 当一个工具调用因没有任务活动而被屏蔽时, Pipa 会崩溃重复 尝试进入一个单一的通知,所以模型上下文保持干净.

## 配置

创建 `.pi/pipa.config.ts` 在项目。 每个选项都是可选的.

```typescript
export default {
  // Interface and built-in Pipa message language: 'en' or 'pt-BR'.
  locale: 'en',

  // Persist teammate messages.
  persistMessages: false,

  teammate: {
    // How a teammate processes an incoming nudge.
    nudgeMode: 'steer',

    // Hide teammate tool calls from the terminal interface.
    hideTools: false,

    // Hide the model name used by teammates.
    hideModelName: false,

    // Models allowed to run concurrently.
    concurrentlyModels: [],

    cycling: {
      // Events that trigger model rotation: 'error' and/or 'concurrency'.
      events: [],

      // Candidate model IDs used during rotation.
      models: []
    },

    // Compact the teammate session after a task action.
    compactAfterTaskAction: false
  },

  tasks: {
    // Maximum number of tasks displayed simultaneously in the TUI.
    maxVisible: 5
  }
};
```

在上述默认情况下,项目配置被合并。 矩阵替换 对应的默认数组,而不是被压缩.

## 本地化

管道支持 `en` (英文)和 `pt-BR` (巴西葡萄牙语) 和内置消息。 设定 `locale` 内 `.pi/pipa.config.ts`。 。 。 .

登机由一个语言中性快取驱动. 代理人推断或要求 语言,然后确认 简介、生成的技能、队友和文物。 工作语言不是 仅限于 Pipa 支持的界面本地化.

## 软件包内容

已分发的 Pi 包包括编译的 Pipa 扩展, 语言中性 即时登入,共享管弦乐指令,以及配置模板, 技能、队友、任务和积压物品.

在入职和储存期间产生具体项目的技能和队友 项目之下 `.pi/` 目录.

## 分发

这个 `aelinrezende/pipa` 库中包含生成的分布文物. 这个 源执行在 `pipa-source`。释放建立 扩展并发布结果到 GitHub 和 npm。 不编辑分布 直接存储库.

## 许可证

皮帕根据麻省理工学院的许可证获得执照.

## 常见问题

### @aelinrezende/pipa 是什么？

皮包 que Carrega 外接 Pipa

### 如何安装 @aelinrezende/pipa？

在项目目录运行 npm install @aelinrezende/pipa，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-ai（\*）、@earendil-works/pi-tui（\*）、@earendil-works/pi-agent-core（\*）、@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aelinrezende/pipa 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/aelinrezende\_\_pipa 是否存在。

### @aelinrezende/pipa 支持 ESM 还是 CommonJS？

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

### @aelinrezende/pipa 可以商用吗？

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

### @aelinrezende/pipa 的下载量有多少？

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

### @aelinrezende/pipa 还在维护吗？

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