皮帕-核心

后面的SDK车 皮巴语用于 Pi 编码代理的扩展 .

皮帕将一个特工变成一个团队. 它协调副代理人,交付业务任务,跟踪项目积压情况,保持知识基础,并长期保存背景. pipa-core 是使得这成为可能的地层:特性系统,会话感知执行 API,以及这些特性通过输入的域事件.

用它来构建你自己的特性 在相同的运行时间 Pipa运行, 或将被捆绑的 编成不同的扩展.

安装

软件包发布于 npm:

npm install @aelinrezende/pipa-core

它还与下列机构合作:

bun add @aelinrezende/pipa-core
pnpm add @aelinrezende/pipa-core

地方发展

要从源头构建 SDK, 克隆 github.com/aelinrezende/pipa-source 并运行建筑内部 .pi 文件夹 :

bun run scripts/build-core.ts

建筑生成 dist-core/,包括: index.js,类型脚本声明, package.json,还有一份这个读取.

使用量

将所需特性登记在 ExtensionAPI数字 :

import { applyFeatures, DocsFeature, PipaBaseFeature } from '@aelinrezende/pipa-core';
import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';

class AuditFeature extends PipaBaseFeature {
  initialize(pi: ExtensionAPI): void {
    pi.registerTool({ name: 'audit' /* ... */ });
  }
}

await applyFeatures(pi, [DocsFeature, AuditFeature]);

applyFeatures 注册特性运行时间 session_start。此时,每个特性及其混合物都与当前 PipaApi, (中文(简体) ), initialize() 已执行,由 initialize() 注册,并附有装饰处理器.

该特征的 pipa API为会话意识. 当装饰处理器运行时,请使用其 PipaApi 参数或 this.pipa 访问当前背景和身份.

包含的特性

DocsFeature - 工具 docs

项目知识基础. 将文档存储为下调 .pi/docs/ 并揭露一个单身 docs 涵盖整个生命周期的工具:

• instantiate 创建文档 title, (中文(简体) ), summary, (中文(简体) ), tags,可选 parentCode。 。 。 .
• list - 列出文档,可选过滤由 tags 并排序为 title, (中文(简体) ), createdAt,或 updatedAt。 。 。 .
• select 整个标题和正文的全文搜索.
• update-frontmatter ——重写单个元数据字段(title, (中文(简体) ), tags,或 parentCode) (中文(简体) ).
• update-body ——用 append, (中文(简体) ), replace,或 set 模式.
• update-metadata ——将任意的JSON对象合并到文档元数据中.
• remove 删除文档.
• publish –通过出口每份文件来标记并建立一个静态站点 retypeapp。 。 。 .

输出 doc_created, (中文(简体) ), doc_updated, (中文(简体) ), doc_removed,以及 doc_published。 。 。 .

TeammateFeature - 工具 teammates

同一工作空间的子剂的寿命周期和通信. 它从捆绑的标记文件以及从 .pi/teammates/*.md,合并全球规则 SYSTEM_AGENTS.md 当在现相.

该工具支持 instantiate, (中文(简体) ), list, (中文(简体) ), online, (中文(简体) ), chat (同步通讯), send-inbox (延迟消息 一个忙的队友, read-inbox,以及 dismiss它会发出 teammate_created 财务报告和审定财务报表 teammate_removed。 。 。 .

除了工具,它处理执行上下文,关闭上下文,可观察性,以及TUI面板. 它跟踪每个会话的闲置和繁忙状态,哪个模型循环用来决定旋转.

要求数 TaskFeature。 。 。 . 授权工作不跟踪就毫无意义了 所以 TeammateFeature 期望同时登记业务任务. TaskFeature 导出于 scripts/pipa-core.index.ts 并且必须纳入同一条款 applyFeatures 电话 :

await applyFeatures(pi, [TaskFeature, TeammateFeature]);

登记 TeammateFeature 无 TaskFeature 留队友没有任务工具来对付他们.

TaskFeature - 工具 task

业务任务。 与积压不同,任务是短暂的:它们的存在是为了在跑步中将工作交给队友,而不是通过会话跟踪项目. 它们一直坚持到 TaskRepository 并在需要时由仓库加载.

该工具支持 instantiate, (中文(简体) ), get, (中文(简体) ), setup, (中文(简体) ), update, (中文(简体) ), list, (中文(简体) ), list-by-squad, (中文(简体) ), squad-status, (中文(简体) ), start, (中文(简体) ), complete, (中文(简体) ), reopen, (中文(简体) ), pause, (中文(简体) ), resume,以及 remove任务包含 a squad页:1 parentTaskId,并输入依赖性 : hard (断章取义地执行)和 soft (信息警告).

该功能包括一个在代理机没有活动任务的情况下屏蔽修改工具的守护,以及一个TUI面板. 还有TUI面板 它发出 task_created, (中文(简体) ), task_updated, (中文(简体) ), task_completed,以及 task_removed。 。 。 .

TaskFeature 需要时 TeammateFeature 见上文.

TodoFeature - 工具 todo

特工本身的业务清单。 它故意不是项目文物:每届都有自己的作品 TodoRepository,存储在来自当前会话身份的路径下.

对于主会话,目录取自: session.id。对于子剂,目录包括两个 parentSessionId 财务报告和审定财务报表 session.id。 。 。 .

特性将其会话本地状态挂起于 before_agent_start,在会话身份之后。 它支持 instantiate, (中文(简体) ), update, (中文(简体) ), remove, (中文(简体) ), list,以及 clear输出 todo_created, (中文(简体) ), todo_updated, (中文(简体) ), todo_removed,以及 todo_cleared。 。 。 .

BacklogFeature - 工具 backlog

长期项目积压,作为JSON存放 BACKLOG_BASE_DIR。这就是长寿活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活.

支助 instantiate, (中文(简体) ), list, (中文(简体) ), select, (中文(简体) ), update-frontmatter, (中文(简体) ), update-body, (中文(简体) ), update-metadata,以及 remove它会发出 backlog_created, (中文(简体) ), backlog_updated,以及 backlog_removed。 。 。 .

包括一个挡住的警卫 write, (中文(简体) ), edit, (中文(简体) ), read,以及 find 反对 backlog.json迫使突变通过 backlog 工具,使项目保持计划一致,事件继续起火.

PermissionFeature - 没有工具

使用工具呼叫警卫 tool_call 事件, 分为两个钩:

• 终端警卫 拒绝危险的击打命令 isBlockedCommand 和另外一项项目级指挥政策validateCommandPolicy) (中文(简体) ). 对于主要代理人, edit 财务报告和审定财务报表 write 需要明确的UI确认,但登入期间除外.
• 自定义工具守护 ——拒绝为主干员限制的工具,并终止已经被解雇的队友的来电(isStopping),因此被停止的副剂不能继续演绎.

已注册工具名列表由特征组成来维护,而不是依赖硬码列表.

OnboardingFeature - 没有工具

框架的靴子 何时 .pi/PROFILE.md 不存在, 它注入捆绑 onboarding.md 快速并引导主代理配置的初步设置 。 在登机活动期间,主代理写入确认被压制.

ReminderCleanerFeature - 没有工具

环境卫生. 从 LLM 上下文中删除已经达到目的的磁盘和通知, 不论它们具有何种特性:任务、队友、文件、积压或其他特性.

ToolResultCompactorFeature - 没有工具

环境卫生. 将旧的和大块化的工具结果的内容取而代之的是指向持久文件路径的活字根并运行定期的微分集而无需用户干预.

ReminderCleanerFeature 财务报告和审定财务报表 ToolResultCompactorFeature 由 Pipa 扩展用于环境卫生。 它们不列入出口的公用特性列表 scripts/pipa-core.index.ts。 。 。 .

设计:默认分散

皮帕岛和 pipa-core 旨在下放权力。 没有一个中央指挥者认为每一项工作都必须经过——这是深思熟虑的.

特工有自主权. 队友获得一个入球及其上下文,然后决定如何达到:用何种工具召唤,以何种顺序,如何分出工作,何时停止. 框架提供能力和合同,而不是脚本。 副剂,每一步都要请求许可,会增加耐性并让主剂成为瓶颈.

没有瓶颈节点. 跑道上没有任何东西能通过一个协调员。 特性是独立的混合体,由下列单位组成: applyFeatures;队友在自己的会话中运行并直接与对方沟通(chat, (中文(简体) ), send-inbox),而未经过主剂. 团队任务, 他们不序列化.

主代理便利, 它不序列化. 它的工作是踢出正确的主人,让开. 把工作交给别人看结果是协调,而不是排队。 监测每个步骤都是反模式的,而不是特征.

扩大框架的影响:

• 不要在代理之间引入新的需要的跳动 。 如果一个特性可以被需要它的代理人直接发现,就在那里曝光.
• 将数据和合同置于指令之上。 给予代理标准;让它选择路径.
• 保持特性可独立堆肥。 一个特性不能假定它是唯一的切入点,也不能假定另一个特性会永远被注册.
• 当一个特性真正需要另一个特性时(例如: TeammateFeature 需求 TaskFeature,而不是把它隐藏在一个隐含的全球.

活动

@PipaEvent 接受 Pi 代理事件和 Pipa 域事件。 代理事件注册于 pi.on; 域事件在 pi.events处理器接收事件有效载荷和 PipaApi数字 :

import { PipaBaseFeature, PipaEvent } from '@aelinrezende/pipa-core';
import type { PipaApi, PipaPayload } from '@aelinrezende/pipa-core';

class ListenerFeature extends PipaBaseFeature {
  @PipaEvent('doc_created')
  onDocCreated(item: PipaPayload<'doc_created'>, pipa: PipaApi): void {
    console.log(`${item.code}: ${item.title}`);
  }
}

域处理者对已经发生的事实作出反应. 要发布一个域事件, 使用处理器或特性中可用的 API :

this.pipa.events.emit('doc_created', item);

域事件地图

读取操作不会放出域事. A 类 task_updated 当儿童任务的变化使父母地位同步时,事件也可以被释放.

扩展地图

DomainEventMap 是一个接口,并支持声明合并:

import type { PipaPayload } from '@aelinrezende/pipa-core';

declare module '@aelinrezende/pipa-core' {
  interface DomainEventMap {
    audit_recorded: { id: string };
  }
}

this.pipa.events.emit('audit_recorded', { id: 'audit-1' });

@PipaEvent('audit_recorded')
onAuditRecorded(item: PipaPayload<'audit_recorded'>): void {
  console.log(item.id);
}

地物储存和依赖性注射

每个数据拥有特性都有一个存储器,负责CRUD,加载,持久性,以及特定特性的查询. 目前储存库包括:

• TaskRepository。 。 。 .
• TeammateRepository。 。 。 .
• BacklogRepository。 。 。 .
• DocsRepository。 。 。 .
• TodoRepository,这是每个会话的地方性,不是共享特征构成的一部分.

业务规则仍保留在自有特征或存储器特定域码中. 地物不再通过静态外观或直接地物导入读取另一个地物的状态.

仓库合同

PipaRepository<T> 提供共同业务:

• all() 返回每个实体.
• findBy(predicate) ——返回匹配上游的实体.
• findOneBy(predicate) 返回第一个匹配实体或 undefined。 。 。 .
• getOneById(id) - 返回一个实体或 undefined。 。 。 .
• getOneByIdOrFail(id) ——在实体不存在时返回实体或抛出.
• add(item) - 增加并坚持一个实体.
• update(id, patch) ——用浅地补地并坚持到底.
• delete(id) ——清除并坚持一个实体.

地物寄存器通过自己的查询和规则来扩展这一基础. 譬如说, TaskRepository 包含任务资格、依赖性、活动任务、团队和父身份逻辑. DocsRepository 财务报告和审定财务报表 BacklogRepository 包含自己的 listBy 执行.

特征依赖性申报

一个特征的 initialize() 可能返回嵌入式依赖对象。 提供方键成为装饰者用来构建消费工具的注射符:

type Dependencies = {
  [dependency: string]: {
    retrieve: () => unknown;
    dependencies?: Dependencies;
  };
};

由叶向上游览所依. 网状提供者在包含它们的提供者之前被检索和注册. 注册为同位素:如果一个符号已经存在,则保留第一个已注册值.

没有嵌入要求的特性宣布单一提供者:

class CatalogFeature extends PipaBaseFeature {
  initialize() {
    return {
      catalog: { retrieve: () => withDependenciesResolved(CatalogRepository, this.pipa) }
    };
  }
}

一个需要另一个的特性 嵌入它。 这个 order 提供者取决于 catalog,所以框架解决 catalog 先说 order数字 :

class OrderFeature extends PipaBaseFeature {
  initialize() {
    return {
      order: {
        retrieve: () => withDependenciesResolved(OrderRepository, this.pipa),
        dependencies: {
          catalog: { retrieve: () => withDependenciesResolved(CatalogRepository, this.pipa) }
        }
      }
    };
  }
}

提供者的钥匙也是注射符. 一个工具声明其构造参数为 @InjectRepository(token),符号必须与密钥完全匹配:

class OrderTool {
  constructor(
    readonly pipa: PipaApi,
    @InjectRepository('order') protected readonly orderRepository: OrderRepository,
    @InjectRepository('catalog') protected readonly catalogRepository: CatalogRepository
  ) {}
}

该功能通过 withDependenciesResolved,通过任何额外的构造参数:

const tool = withDependenciesResolved(OrderTool, this.pipa);

@InjectParam 记录一个构造参数符号,同时 @InjectRepository 是寄存器的特定包装. withDependenciesResolved 读取所记录的元数据,解决提供者,并创建类实例.

这些是捆绑的Pipa特性所使用的执行细节。 公众切入点不会暴露全球 Repositories 登记处或公众 createRepository 工厂。 消费者应通过 applyFeatures 而不是导入内部仓库文件.

一个提供者的密钥只有在它自己的特性注册时才可用. 注入另一个特性的符号的工具要求该特性成为同一构成的一部分——该要求载于 包含的特性。 。 。 .

身份属于 PipaApi

会话身份不通过寄存器解决 . PipaApi.session 曝光当前身份 :

interface PipaSessionIdentity {
  id: string;
  role: 'main' | 'subagent';
  name: string;
  parentSessionId?: string;
  depth: number;
  isStopping: boolean;
}

session 是一个取出器,所以角色和生命周期状态被读取为新鲜,而不是在API建成时被捕获一次.

通知和大门

有三个不同的渠道。 选对了:

• 域事件 : 使用情况 pi.events 对于会期事实,应注意其他特征。 火灾和遗忘,不能否决任何东西.
• 敬酒: 使用情况 this.pipa.toast.show(message) 用于针对人类的桌面通知.
• 门: 使用情况 pi.on('tool_call') 返回时 { block: true, reason } 当一个工具呼叫必须被拒绝时.

域事和土司不能否决工具呼吁。 只有一个门可以.

桌面土司

PipaApi.toast 属于公共API,并且 ToastService 属于公共合同类型的一部分,因此消费者可以从自己的特性中提出桌面通知:

export class DeployFeature extends PipaBaseFeature {
  @PipaEvent('deploy_finished')
  onDeployFinished(result: PipaPayload<'deploy_finished'>, pipa: PipaApi): void {
    void pipa.toast.show(`Deploy finished: ${result.environment}`);
  }
}

show(message, options?) 是整个地表。 它回报一个承诺; options 接受 node-notifier 通知字段除外 message 财务报告和审定财务报表 title,服务拥有.

在依赖它之前值得知道的行为:

• 在终端集中时被压制. 服务会检查活动窗口, 当它属于已知的终端或编辑器进程时会提前返回. 敬酒是当用户寻找别处时的;随着终端的集中,它被悄悄地抛出.
• 被贬. 与仍在屏幕上的信件完全相同的信件不会发送两次 .
• 内出. 信件占位符由会话插值填充.
• 失败宽容. 如果活动窗口的搜索抛出, 错误会被记录为警告.

因为交付是最佳的,并且可以被压制,所以永远不要让敬酒者携带用户必须看到的信息. 在总是可见的频道上方用它来做个软块.

这个 Toast 类本身不导出——您通过 PipaApi,您不构造一个.

会话范围数据

Todo数据属于一个Pi会话. 其存储器按会话创建,并坚持 todo.json 根据来自会话身份的目录:

• 主要会议: ~/.pi/sessions/<sessionId>/todo.json。 。 。 .
• 分机会话: ~/.pi/sessions/<parentSessionId>/<sessionId>/todo.json。 。 。 .

TodoFeature 挂载此寄存器时 before_agent_start,当 PipaApi.session 已提供.

主要出口

公共入境点包括:

• 特征 : BacklogFeature, (中文(简体) ), DocsFeature, (中文(简体) ), OnboardingFeature, (中文(简体) ), PermissionFeature, (中文(简体) ), TaskFeature, (中文(简体) ), TeammateFeature, (中文(简体) ), TodoFeature, (中文(简体) ), PipaBaseFeature,则 PipaBaseFeatureConstructor 类型. TaskFeature 需要时 TeammateFeature。 。 。 .
• 核心 API : applyFeatures, (中文(简体) ), buildPipaApi, (中文(简体) ), pipa, (中文(简体) ), config, (中文(简体) ), PipaEvent, (中文(简体) ), PipaException, (中文(简体) ), PI_EVENTS,以及 PI_EVENTS_SYMBOLS。 。 。 .
• 枢纽和仓库: BacklogHub, (中文(简体) ), DocsHub, (中文(简体) ), TaskHub, (中文(简体) ), TeammateHub,以及 PipaStore。 。 。 .
• 域事件类型 : DomainEventMap, (中文(简体) ), DomainEventName, (中文(简体) ), PipaPayload,以及 DomainEventHandler。 。 。 .
• 实体类型 : BacklogItem, (中文(简体) ), DocItem, (中文(简体) ), Task, (中文(简体) ), Teammate, (中文(简体) ), TeammateFrontmatter, (中文(简体) ), TeammateInboxMessage, (中文(简体) ), TeammateStatus, (中文(简体) ), TeammatesStore,以及 TodoItem。 。 。 .
• 合同类型: PipaApi, (中文(简体) ), PipaConfig, (中文(简体) ), PipaTasksConfig, (中文(简体) ), PipaTeammateConfig, (中文(简体) ), Intercom, (中文(简体) ), CommandPolicy, (中文(简体) ), ToastService,以及 PiEvent。 。 。 .
• 仓库类型声明 : RepositoryKey, (中文(简体) ), RepositoryMap,以及 RepositoryOf。 。 。 .