Pi Native Task

一个极简的 Pi 子代理插件。

它只向模型暴露一个工具：task。

task({ description, prompt, subagent_type, systemPrompt? })
  → 创建一个真实的 Pi 子会话
  → 在该子会话中执行任务
  → 使用 Pi 原生 JSONL 自动持久化
  → 返回精确的 sessionId 和 sessionFile

为什么是这个插件

这个插件不模拟会话，也不维护第二套历史记录。每次调用都会直接创建一个真实的 Pi child session：

• 子会话拥有 Pi 生成的真实 sessionId。
• 子会话拥有真实的 sessionFile。
• 消息、工具调用、工具结果、错误和中断都写入标准 Pi JSONL。
• 调用结束后文件保留，可以使用同一个 sessionFile 重新打开并继续。
• 不使用 persist_session: true，持久化由 Pi 原生会话机制负责。

工具

插件只注册：

task

输入

{
  "description": "检查项目测试",
  "prompt": "请检查这个项目的测试是否通过",
  "subagent_type": "reviewer",
  "systemPrompt": "你是一个专注于验证的子代理"
}

• description：必填，任务的简短名称，用于宿主界面标题。
• prompt：必填，要交给子会话执行的任务。
• subagent_type：必填，子代理角色名，例如 reviewer、explore、general。
• systemPrompt：可选，只为本次子会话设置 system prompt。

输出

{
  "description": "检查项目测试",
  "subagent_type": "reviewer",
  "sessionId": "01...",
  "sessionFile": "...jsonl",
  "status": "completed",
  "output": "任务结果"
}

status 可能是：

• running
• completed
• error
• aborted

如果子会话已经创建，即使执行失败或被中断，也会返回已经创建的真实身份；不会返回假 ID，也不会丢弃已有 JSONL 历史。

npm 安装

在已安装 Pi 的环境中直接安装：

pi install npm:pi-native-task

升级到最新版本：

pi update npm:pi-native-task

卸载：

pi remove npm:pi-native-task

安装依赖

要求：

• Node.js >= 22.19.0
• npm
• 可用的 Pi SDK provider 和凭据

npm install
npm run check

加载插件

直接加载

使用 Pi CLI 的扩展参数：

pi -e .\src\index.ts

在 PiUI 中加载

将插件目录放在 PiUI 的 temp/pi-native-task，开发环境会自动发现。

生产环境或独立安装时，设置插件目录：

$env:PIUI_NATIVE_TASK_ROOT = "C:\\opt\\pi-native-task"

也可以直接指定入口文件：

$env:PIUI_NATIVE_TASK_EXTENSION = "C:\\opt\\pi-native-task\\src\\index.ts"

然后启动 PiUI worker：

npm run pi-worker -- web

如果显式路径不存在，PiUI 会以 NATIVE_TASK_EXTENSION_NOT_FOUND 错误失败，而不会静默退回其他子代理实现。

持久化和恢复

一次调用对应一个真实 child session：

父会话
  → task
  → 创建 child session
  → child JSONL 持续写入
  → 返回 sessionId/sessionFile
  → 关闭宿主后仍可用 sessionFile 恢复

恢复时使用 Pi 原生 session API 或 Pi CLI 指向返回的 sessionFile。插件不会创建外置数据库、sidecar transcript、session registry 或虚拟 transcript。

真实验证

单元测试和类型检查：

npm run check

使用真实 provider 验证创建、持久化和恢复：

npm run test:real

真实验证会检查：

• 返回的 sessionId 与 JSONL header 中的 ID 一致。
• sessionFile 在任务结束后仍然存在。
• JSONL 中包含真实 user/assistant history。
• 重新打开同一个 session 文件后，可以继续追加新的对话轮次。

设计边界

本插件刻意不提供：

• retained agent
• agent registry
• task_status、task_resume、task_list
• mailbox、workflow、review、synthesis
• 虚拟会话或投影 transcript
• 外部关系存储或平行 session store

目标只有一个：

一次 task 调用
→ 一个真实 Pi JSONL 子会话
→ 返回精确身份
→ 调用方读取同一个原生会话

许可证

MIT