{"_id":"@010subagent/pi-subagent-framework","name":"@010subagent/pi-subagent-framework","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@010subagent/pi-subagent-framework","version":"0.1.0","description":"Agent-neutral Pi framework for discovering and delegating work to Markdown-defined subagents.","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/SeasyecN/pi-subagent-framework.git"},"private":false,"keywords":["pi-package","pi-extension","pi","subagents","agents","automation"],"pi":{"extensions":["./dist/index.ts"]},"piExtension":{"lifecycle":"stable"},"scripts":{"build":"node scripts/build-runtime.mjs","check":"npm run build && biome check . && npm run typecheck","format":"biome check --write .","prepack":"npm run build","test":"tsx --test test/**/*.test.ts","typecheck":"tsc --noEmit"},"peerDependencies":{"@earendil-works/pi-agent-core":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"devDependencies":{"@biomejs/biome":"2.5.10","@earendil-works/pi-agent-core":"0.84.3","@earendil-works/pi-ai":"0.84.3","@earendil-works/pi-coding-agent":"0.84.3","@earendil-works/pi-tui":"0.84.3","@types/proper-lockfile":"^4.1.4","esbuild":"0.28.2","tsx":"^4.23.13","typebox":"1.3.18","typescript":"7.0.2"},"dependencies":{"@narumitw/pi-tui-kit":"^0.59.0","proper-lockfile":"^4.1.2"},"gitHead":"9c2f9b4be7f6476b5c1aec61701fc1ddf3194f84","_id":"@010subagent/pi-subagent-framework@0.1.0","bugs":{"url":"https://github.com/SeasyecN/pi-subagent-framework/issues"},"homepage":"https://github.com/SeasyecN/pi-subagent-framework#readme","_nodeVersion":"22.19.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-H3AuZlOYjy/GiWROQS0Yj9a6PCgF1gjB4eMrETQn2rF6RJ8PgN4Aeue3CmXGmkQD0SqnynH2+P8LxGBjmw9Oqw==","shasum":"115da858c4a443b10e71e8355d60d1555ab96ecb","tarball":"https://registry.npmjs.org/@010subagent/pi-subagent-framework/-/pi-subagent-framework-0.1.0.tgz","fileCount":295,"unpackedSize":3957761,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCS28z4vnzzMkudlCstTA7btUygMxt3mw+HPnZsVGXIUwIhAOP9wii0eV3sZDKOaGenTWH8VoQeQ5dwZIoeqi9N3C4q"}]},"_npmUser":{"name":"010sea","email":"1192526749b@gmail.com"},"directories":{},"maintainers":[{"name":"010sea","email":"1192526749b@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-subagent-framework_0.1.0_1788165992229_0.5281874402290001"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:46:31.916Z","0.1.0":"2026-08-31T08:46:32.414Z","modified":"2026-08-31T08:46:32.700Z"},"maintainers":[{"name":"010sea","email":"1192526749b@gmail.com"}],"description":"Agent-neutral Pi framework for discovering and delegating work to Markdown-defined subagents.","homepage":"https://github.com/SeasyecN/pi-subagent-framework#readme","keywords":["pi-package","pi-extension","pi","subagents","agents","automation"],"repository":{"type":"git","url":"git+https://github.com/SeasyecN/pi-subagent-framework.git"},"bugs":{"url":"https://github.com/SeasyecN/pi-subagent-framework/issues"},"license":"MIT","readme":"# @010subagent/pi-subagent-framework\n\n`@010subagent/pi-subagent-framework` 是一个面向 [Pi Coding Agent](https://pi.dev) 的 **Agent 中立（Agent-neutral）子代理执行与治理框架**，衍生自 upstream [`@narumitw/pi-subagents@2.1.3`](https://github.com/narumiruna/pi-extensions/tree/@narumitw/pi-subagents@2.1.3/packages/pi-subagents)（MIT License）。\n\n## 核心特性\n\n- **纯框架设计**：完全移除了原项目中的硬编码内置 Agent（无内置 `explorer` / `worker`，无隐式 fallback）。框架本身只负责 Agent 发现、执行生命周期、状态并发控制与策略校验。\n- **Markdown 定义 Agent**：通过全局 `~/.pi/agent/agents/*.md` 与项目级 `.pi/agents/*.md` 声明 Agent 的元数据与系统提示词（System Prompt）。\n- **统一 JSON 治理与覆盖**：通过 `~/.pi/agent/subagent-framework.json` 集中管理搜索源路径、参数覆盖（`overrides`）、旧版工具策略与运行时限制。\n- **内置动态策略拦截**：集成 `subagent-policy`，自动基于发现的 Agent 注册表进行动态调用校验与参数防御，无需维护额外策略扩展。\n\n---\n\n## Agent Markdown 定义\n\nAgent 的基础信息与 Prompt 完全由 Markdown 文件管理。\n\n### 默认发现路径\n- **用户级（全局）**：`~/.pi/agent/agents/*.md`\n- **项目级（受信任项目）**：`.pi/agents/*.md`\n\n### Markdown 定义示例\n\n在 `~/.pi/agent/agents/code.md` 中定义：\n\n```markdown\n---\nname: code\ndescription: 通用资深软件工程专家，负责除前端以外的代码实现、重构、调试与系统脚本编写\ntools:\n  - read\n  - bash\n  - edit\n  - write\n  - replace\n  - insert\n  - grep\nmodel: openai/gpt-5.6-sol\nthinkingLevel: xhigh\n---\n\n你是一个通用的资深软件工程专家。\n\n### 职责边界\n- 负责后端服务、系统编程、CLI、脚本、自动化、数据库及 API 开发。\n- 不负责前端 UI/CSS/组件相关工作。\n```\n\n> **说明**：\n> - Frontmatter 中支持字段：`name`（必需）、`description`（必需）、`tools`（可选，默认 `[\"read\", \"bash\", \"edit\", \"write\"]`）、`model`（可选）、`thinkingLevel`（可选，支持 `off` | `minimal` | `low` | `medium` | `high` | `xhigh` | `max`）、`capabilityManifest`（可选）。\n> - Markdown 正文直接作为该 Agent 的 `systemPrompt`。\n\n---\n\n## 配置文件 (`subagent-framework.json`)\n\n配置文件路径固定为：\n```text\n~/.pi/agent/subagent-framework.json\n```\n\n框架遵循**关注点分离**原则：\n- Agent 的描述（`description`）、系统提示词（`systemPrompt`）与能力清单（`capabilityManifest`）仅在 Markdown 文件中维护，**JSON 配置中不重复定义，也不支持内联 JSON Agent 定义**。\n- JSON 用于定义源目录路径（`sources`）、针对特定 Agent 的运行参数覆盖（`overrides`）、策略开关（`policy`）与各运行时子系统的设置。\n\n### 完整配置示例\n\n```json\n{\n  \"registry\": {\n    \"sources\": {\n      \"user\": [\"~/.pi/agent/agents\"],\n      \"project\": [\".pi/agents\"]\n    },\n    \"overrides\": {\n      \"code\": {\n        \"enabled\": true,\n        \"model\": \"openai/gpt-5.6-sol\",\n        \"thinkingLevel\": \"xhigh\",\n        \"tools\": [\n          \"read\",\n          \"bash\",\n          \"edit\",\n          \"write\",\n          \"replace\",\n          \"insert\",\n          \"grep\"\n        ],\n        \"timeoutMs\": 600000\n      },\n      \"deprecated-worker\": {\n        \"enabled\": false\n      }\n    }\n  },\n  \"policy\": {\n    \"blockDeprecatedSubagent\": true\n  },\n  \"blocking\": {\n    \"enabled\": true,\n    \"maxParallelTasks\": 8\n  },\n  \"stateful\": {\n    \"enabled\": true,\n    \"transport\": \"subprocess\",\n    \"completionDelivery\": \"next-turn\",\n    \"maxAgents\": 16,\n    \"maxActiveTurns\": 4,\n    \"maxDepth\": 3,\n    \"maxChildrenPerAgent\": 8,\n    \"maxMailboxMessages\": 100,\n    \"maxMailboxMessageBytes\": 65536,\n    \"idleTtlMs\": 300000,\n    \"retentionDays\": 7,\n    \"maxStoredAgents\": 50\n  },\n  \"consult\": {\n    \"resources\": \"project-context\"\n  },\n  \"cwdPolicy\": {\n    \"consultation\": \"anywhere\",\n    \"delegation\": \"trusted-targets\"\n  },\n  \"usageRecording\": {\n    \"enabled\": true\n  }\n}\n```\n\n### 参数覆盖优先级 (Precedence)\n\n运行参数按以下优先级自低到高解析生效：\n1. **Markdown Frontmatter 定义**（基础配置）\n2. **JSON Overrides** (`registry.overrides.<name>`，若显式设为 `null` 则清空 Markdown 设置）\n3. **单次调用入参**（`subagent_spawn` / `subagent_consult` 传入的临时参数）\n\n---\n\n## 运行时行为与安全机制\n\n### 1. 作用域与项目信任 (Scope & Trust)\n- 调用参数 `agentScope` 支持 `\"user\"`（默认）、`\"project\"`、`\"both\"`。\n- **项目信任保护**：只有当前工作区为受信任项目（`ctx.isProjectTrusted()` 为 `true`）时，框架才会加载和执行项目目录（`.pi/agents`）下的 Agent。在不受信任的项目中指定 `agentScope: \"project\"` 或 `\"both\"` 会被策略拦截并拒绝执行。\n\n### 2. 异常配置阻断 (Invalid Config Blocks Delegation)\n- 若 `subagent-framework.json` 存在语法错误（Malformed JSON）或不符合 Schema 规范（如含有非法字段或非法取值），框架将在会话中发出警告并**阻断 spawn / consult / send 等新委派操作**；状态检查（inspection）与生命周期管理（lifecycle management，如 `subagent_inspect`、`subagent_manage` 等）保持可用，方便排查与恢复。\n\n### 3. 空注册表行为 (Zero-Agent Behavior)\n- 当未发现任何 Markdown Agent 定义或所有 Agent 均被 `enabled: false` 禁用时，注册表为空（`available: none`）。\n- 此时调用任何 Agent 均会返回明确的错误提示（包含当前可用列表 `none`），不会回退到任何隐式 Agent。\n\n### 4. 热重载 (`/reload`)\n- 在 Pi 交互会话中输入 `/reload` 即可重新读取 `subagent-framework.json` 并重新扫描 Markdown 目录发现最新 Agent。\n\n### 5. 安全说明 (Security Note)\n- **子代理非操作系统级沙箱**：子代理进程运行在当前宿主系统的用户权限下。赋予子代理 `bash`、`write` 等工具意味着其对文件系统和命令行具备与当前用户一致的操作权限。请务必审慎配置工具权限。\n\n---\n\n## 本地开发、构建与安装\n\n### 构建与校验命令\n\n```bash\n# 安装依赖\nnpm install\n\n# 构建运行时产物\nnpm run build\n\n# 运行 TypeScript 类型检查\nnpm run typecheck\n\n# 运行完整规范与类型检查\nnpm run check\n```\n\n### 安装到 Pi\n\n通过 npm 包安装：\n\n```bash\npi install npm:@010subagent/pi-subagent-framework\n```\n\n或通过本地路径安装：\n\n```bash\n# 在框架根目录下或使用绝对路径安装\npi install /home/xmz/pi-subagent-framework\n\n# 查看已安装包\npi list\n```\n\n---\n\n## 迁移指南 (Migration)\n\n如果你之前单独安装了 `@narumitw/pi-subagents` 或配置了独立的 `subagent-policy.ts`，请按以下步骤迁移，避免扩展重复注册或策略冲突：\n\n1. **卸载原运行器包**：\n   ```bash\n   pi remove npm:@narumitw/pi-subagents\n   ```\n2. **移除独立策略扩展**：\n   删除手写的 `~/.pi/agent/extensions/subagent-policy.ts`（本框架已内置完整基于当前注册表的策略控制）。\n3. **安装新框架**：\n   ```bash\n   pi install /home/xmz/pi-subagent-framework\n   ```\n4. **验证与重载**：\n   在 Pi 会话中运行 `/reload`，确保子代理工具及策略正常加载。\n\n---\n\n## 开源许可与致谢 (License & Attribution)\n\n本项目采用 [MIT License](./LICENSE)。\n\n本项目基于 [@narumitw/pi-subagents](https://github.com/narumiruna/pi-extensions/tree/@narumitw/pi-subagents@2.1.3/packages/pi-subagents) (v2.1.3, Copyright (c) 2026 narumiruna) 分叉并重构，在此感谢原作者及社区的贡献。\n","readmeFilename":"README.md","_rev":"1-2b7e8f84455b2c4893bde2e8de642429"}