devkit-pi

English | 中文

面向个人工作流的一体化 pi coding 工具包。

将 subagent 任务委派、Web 研究、LSP 代码智能、自动诊断 hook 和开发者命令整合为一个模块化 pi 扩展。

模块

模块	说明	默认状态
subagents	将任务委派给 5 个专职 readonly agent；支持通过 markdown frontmatter 自定义 user/project agent	启用
web	web_search、fetch_content、get_search_content — 多供应商搜索、URL 内容提取、结果缓存	启用
lsp	LSP 工具（definition、references、hover、symbols、diagnostics）+ agent_end 后自动诊断 hook	启用
commands	统一 /toolkit 命令中心：doctor、modules、logs、agents、lsp、activity	启用

快速开始

作为 pi 包安装

pi install devkit-pi

或本地链接开发

{
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

git clone https://github.com/0xnayuta/devkit-pi.git
cd devkit-pi
pnpm install
pnpm test

内置 Agent

Agent	专长	权限
explorer	代码导航、文件搜索、LSP 符号导航	readonly
researcher	文档/API 研究、Web 搜索	readonly
reviewer	代码审查、架构分析、LSP diagnostics	readonly
implementer	实现规划，辅以 LSP definition/references	readonly
tester	测试策略、边界用例规划、LSP diagnostics	readonly

所有 agent 默认 readonly。主代理是唯一编排者 — 子代理不能再调度其他子代理。

可写自定义 subagents 目前属于实验性能力。默认且推荐模式是 readonly；subagents.allowWrite=true 不代表完整沙箱、审计日志或自动回滚保证。详见 Subagents 参考 和 安全模型。

自定义 agent

在 .pi/agents/（项目级）或 ~/.pi/agent/agents/（用户级）放置 markdown 文件：

---
name: custom-reviewer
description: 项目专用审查 agent
readonly: true
tools: read, grep, find, ls
---

You are a custom review subagent.

工具

Subagent 工具

subagent({ agent: "explorer", task: "查找认证相关代码" })

将聚焦任务委派给专职 agent，结果经 sanitize 后返回给父代理。

Web 工具

工具	说明
web_search	多供应商 Web 搜索，支持自动降级。供应商：ddgs（默认）、brave、tavily、serper、openserp、searxng
fetch_content	抓取 URL 并提取可读文本，支持 Jina reader 降级（适用于 JS 重度渲染页面）
get_search_content	通过 responseId 检索已存储的搜索/抓取结果

LSP 工具

暴露语言服务器能力：definition、references、hover、signature、symbols、diagnostics、workspace-diagnostics、servers。

变更类操作（rename、codeAction、restart）默认禁用，且在子代理进程中始终被阻止。

LSP 诊断 hook

在每轮 agent 交互后自动运行 LSP diagnostics（可配置：agent_end | edit_write | disabled）。

命令

/toolkit 命令提供诊断和检查子命令：

子命令	说明
/toolkit doctor	运行统一诊断检查
/toolkit modules	显示各模块启用状态
/toolkit logs	查看近期 Web 活动日志
/toolkit agents	列出所有已发现的 agent
/toolkit lsp	显示 LSP 工具/hook 配置
/toolkit activity	打开交互式活动面板
/toolkit help	显示用法帮助

配置

配置文件路径：~/.pi/agent/extensions/devkit-pi/config.json。

每个模块均可独立启用或禁用。完整默认值与 normalize 规则见 配置参考。

错误码

Subagent 错误

INVALID_INPUT | SUBAGENTS_DISABLED | UNKNOWN_AGENT | SUBAGENT_DISABLED | SUBAGENT_DEPTH_EXCEEDED | SUBAGENT_TIMEOUT | SUBAGENT_FAILED | SUBAGENT_OUTPUT_TRUNCATED

Web 工具错误

Web 工具返回包含 error.code 和 error.message 的结构化错误。常见错误码包括 INVALID_INPUT、WEB_SEARCH_INVALID_QUERY、WEB_SEARCH_FAILED、WEB_SEARCH_TIMEOUT、PROVIDER_AUTH_FAILED、PROVIDER_RATE_LIMITED、PROVIDER_UNAVAILABLE、NETWORK_ERROR、CONTENT_FETCH_INVALID_URL、CONTENT_FETCH_FAILED、CONTENT_FETCH_TIMEOUT 和 NOT_FOUND。

完整 canonical 清单见 Web tools 错误码。

项目结构

src/
├─ index.ts                 # 薄入口 — 注册所有模块
├─ modules/
│  ├─ subagents/            # 任务委派、agent 发现、执行
│  │  └─ commands/          # doctor、list、logs 格式化逻辑
│  ├─ web/                  # 搜索、抓取、内容提取、缓存
│  │  └─ providers/         # ddgs、brave、tavily、serper、openserp、searxng
│  ├─ lsp/                  # LSP 工具、诊断 hook、server 管理
│  └─ commands/             # 统一 /toolkit 命令注册
├─ config/                  # 配置加载与默认值
└─ shared/                  # 类型、错误码、通用工具
agents/                     # 5 个内置 agent 定义（markdown）
tests/                      # 镜像 src/modules 结构
docs/                       # 文档、指南、ADR

设计边界

1. 主代理是唯一编排者
2. 子代理不能再调度其他子代理（maxDepth = 1）
3. 默认 readonly — 自定义 subagents 的写入能力需要显式配置且仍属于实验性能力
4. LSP 变更类操作（rename、codeAction、restart）默认禁用，且在子代理进程中始终被阻止
5. 每个模块均可独立启用或禁用

开发

pnpm typecheck    # 类型检查
pnpm lint         # 使用 Biome 检查代码
pnpm lint:fix     # 自动修复 lint 问题
pnpm format       # 使用 Biome 格式化代码
pnpm test         # 运行单元测试
pnpm docs:check   # 验证文档

文档站

线上文档站：https://devkit-pi.wangyan.life/

可以在本地预览 VitePress 文档站：

pnpm docs:dev
pnpm docs:build
pnpm docs:preview

文档

• 文档总入口
• Reference 索引
• 目标与范围
• 架构
• 配置参考
• Subagents 参考
• Subagent tool 参考
• Agent 定义
• 结果 schema
• Toolkit commands 参考
• LSP tools 参考
• Web tools 参考
• Web providers 参考
• Web tools 错误码
• 安全模型
• 架构决策记录

许可证

MIT © Izayoi Nayuta