@010subagent/pi-subagent-framework

@010subagent/pi-subagent-framework

@010subagent/pi-subagent-framework 是一个面向 Pi Coding Agent 的 Agent 中立（Agent-neutral）子代理执行与治理框架，衍生自 upstream @narumitw/pi-subagents@2.1.3（MIT License）。

核心特性

• 纯框架设计：完全移除了原项目中的硬编码内置 Agent（无内置 explorer / worker，无隐式 fallback）。框架本身只负责 Agent 发现、执行生命周期、状态并发控制与策略校验。
• Markdown 定义 Agent：通过全局 ~/.pi/agent/agents/*.md 与项目级 .pi/agents/*.md 声明 Agent 的元数据与系统提示词（System Prompt）。
• 统一 JSON 治理与覆盖：通过 ~/.pi/agent/subagent-framework.json 集中管理搜索源路径、参数覆盖（overrides）、旧版工具策略与运行时限制。
• 内置动态策略拦截：集成 subagent-policy，自动基于发现的 Agent 注册表进行动态调用校验与参数防御，无需维护额外策略扩展。

---

Agent Markdown 定义

Agent 的基础信息与 Prompt 完全由 Markdown 文件管理。

默认发现路径

• 用户级（全局）：~/.pi/agent/agents/*.md
• 项目级（受信任项目）：.pi/agents/*.md

Markdown 定义示例

在 ~/.pi/agent/agents/code.md 中定义：

---
name: code
description: 通用资深软件工程专家，负责除前端以外的代码实现、重构、调试与系统脚本编写
tools:
  - read
  - bash
  - edit
  - write
  - replace
  - insert
  - grep
model: openai/gpt-5.6-sol
thinkingLevel: xhigh
---

你是一个通用的资深软件工程专家。

### 职责边界
- 负责后端服务、系统编程、CLI、脚本、自动化、数据库及 API 开发。
- 不负责前端 UI/CSS/组件相关工作。

说明：

• Frontmatter 中支持字段：name（必需）、description（必需）、tools（可选，默认 ["read", "bash", "edit", "write"]）、model（可选）、thinkingLevel（可选，支持 off | minimal | low | medium | high | xhigh | max）、capabilityManifest（可选）。
• Markdown 正文直接作为该 Agent 的 systemPrompt。

---

配置文件 (subagent-framework.json)

配置文件路径固定为：

~/.pi/agent/subagent-framework.json

框架遵循关注点分离原则：

• Agent 的描述（description）、系统提示词（systemPrompt）与能力清单（capabilityManifest）仅在 Markdown 文件中维护，JSON 配置中不重复定义，也不支持内联 JSON Agent 定义。
• JSON 用于定义源目录路径（sources）、针对特定 Agent 的运行参数覆盖（overrides）、策略开关（policy）与各运行时子系统的设置。

完整配置示例

{
  "registry": {
    "sources": {
      "user": ["~/.pi/agent/agents"],
      "project": [".pi/agents"]
    },
    "overrides": {
      "code": {
        "enabled": true,
        "model": "openai/gpt-5.6-sol",
        "thinkingLevel": "xhigh",
        "tools": [
          "read",
          "bash",
          "edit",
          "write",
          "replace",
          "insert",
          "grep"
        ],
        "timeoutMs": 600000
      },
      "deprecated-worker": {
        "enabled": false
      }
    }
  },
  "policy": {
    "blockDeprecatedSubagent": true
  },
  "blocking": {
    "enabled": true,
    "maxParallelTasks": 8
  },
  "stateful": {
    "enabled": true,
    "transport": "subprocess",
    "completionDelivery": "next-turn",
    "maxAgents": 16,
    "maxActiveTurns": 4,
    "maxDepth": 3,
    "maxChildrenPerAgent": 8,
    "maxMailboxMessages": 100,
    "maxMailboxMessageBytes": 65536,
    "idleTtlMs": 300000,
    "retentionDays": 7,
    "maxStoredAgents": 50
  },
  "consult": {
    "resources": "project-context"
  },
  "cwdPolicy": {
    "consultation": "anywhere",
    "delegation": "trusted-targets"
  },
  "usageRecording": {
    "enabled": true
  }
}

参数覆盖优先级 (Precedence)

运行参数按以下优先级自低到高解析生效：

1. Markdown Frontmatter 定义（基础配置）
2. JSON Overrides (registry.overrides.<name>，若显式设为 null 则清空 Markdown 设置）
3. 单次调用入参（subagent_spawn / subagent_consult 传入的临时参数）

---

运行时行为与安全机制

1. 作用域与项目信任 (Scope & Trust)

• 调用参数 agentScope 支持 "user"（默认）、"project"、"both"。
• 项目信任保护：只有当前工作区为受信任项目（ctx.isProjectTrusted() 为 true）时，框架才会加载和执行项目目录（.pi/agents）下的 Agent。在不受信任的项目中指定 agentScope: "project" 或 "both" 会被策略拦截并拒绝执行。

2. 异常配置阻断 (Invalid Config Blocks Delegation)

• 若 subagent-framework.json 存在语法错误（Malformed JSON）或不符合 Schema 规范（如含有非法字段或非法取值），框架将在会话中发出警告并阻断 spawn / consult / send 等新委派操作；状态检查（inspection）与生命周期管理（lifecycle management，如 subagent_inspect、subagent_manage 等）保持可用，方便排查与恢复。

3. 空注册表行为 (Zero-Agent Behavior)

• 当未发现任何 Markdown Agent 定义或所有 Agent 均被 enabled: false 禁用时，注册表为空（available: none）。
• 此时调用任何 Agent 均会返回明确的错误提示（包含当前可用列表 none），不会回退到任何隐式 Agent。

4. 热重载 (/reload)

• 在 Pi 交互会话中输入 /reload 即可重新读取 subagent-framework.json 并重新扫描 Markdown 目录发现最新 Agent。

5. 安全说明 (Security Note)

• 子代理非操作系统级沙箱：子代理进程运行在当前宿主系统的用户权限下。赋予子代理 bash、write 等工具意味着其对文件系统和命令行具备与当前用户一致的操作权限。请务必审慎配置工具权限。

---

本地开发、构建与安装

构建与校验命令

# 安装依赖
npm install

# 构建运行时产物
npm run build

# 运行 TypeScript 类型检查
npm run typecheck

# 运行完整规范与类型检查
npm run check

安装到 Pi

通过 npm 包安装：

pi install npm:@010subagent/pi-subagent-framework

或通过本地路径安装：

# 在框架根目录下或使用绝对路径安装
pi install /home/xmz/pi-subagent-framework

# 查看已安装包
pi list

---

迁移指南 (Migration)

如果你之前单独安装了 @narumitw/pi-subagents 或配置了独立的 subagent-policy.ts，请按以下步骤迁移，避免扩展重复注册或策略冲突：

1. 卸载原运行器包：

   pi remove npm:@narumitw/pi-subagents
   

2. 移除独立策略扩展： 删除手写的 ~/.pi/agent/extensions/subagent-policy.ts（本框架已内置完整基于当前注册表的策略控制）。
3. 安装新框架：

   pi install /home/xmz/pi-subagent-framework
   

4. 验证与重载： 在 Pi 会话中运行 /reload，确保子代理工具及策略正常加载。

---

开源许可与致谢 (License & Attribution)

本项目采用 MIT License。

本项目基于 @narumitw/pi-subagents (v2.1.3, Copyright (c) 2026 narumiruna) 分叉并重构，在此感谢原作者及社区的贡献。