Agent 定义参考

Agent 使用 markdown frontmatter + prompt 正文定义。Subagents 总览见 subagents.md，调用入口见 subagent-tool.md，执行结果结构见 result-schema.md。

发现路径

当前会发现三类 agents：

来源	路径	说明
builtin	仓库 agents/	devkit-pi 内置 5 个 agents
user	~/.pi/agent/agents/	用户级自定义 agents
project	从 cwd 向上查找 .pi/agents/ 或 .agents/	项目级自定义 agents

同名去重优先级：

project > user > builtin

文件格式

支持 .md 和 .markdown 文件。

当前 parser 只支持简单 frontmatter，不是完整 YAML parser：

• 文件必须以 --- 开头才会解析 frontmatter。
• 结束标记是下一段 ---。
• 每行匹配 key: value。
• key 支持 word/hyphen：[\w-]+。
• value 会 trim；成对单引号或双引号会被去掉。
• 不支持 YAML list、嵌套对象、多行字符串或复杂类型。

支持的 frontmatter 字段

字段	必填	文件中的类型	行为
name	是	string	agent 名称；缺失则该文件不会被加载
description	否	string	agent 描述；缺失时为空字符串
readonly	否	string	只有 true 或 1 会解析为 true；否则 false
tools	否	comma-separated string	逗号分隔工具名，trim 后去空
model	否	string	传给 child pi 的 --model

Prompt 正文作为 agent 的 systemPrompt。如果正文为空，执行时会回退使用 description 或默认角色文本。

不支持的字段

以下字段当前没有特殊语义，不应写入 public 文档为已实现功能：

package, inheritSkills, defaultContext, tags, routingHints, disabled,
permissions, temperature, maxTokens, provider, tools as YAML list

其中 disabled 当前不被解析；没有 per-agent disable public config。

内置 agents

Agent	描述	Readonly	Tools	源码
explorer	Read-only codebase navigator — finds files, patterns, and architecture	true	read, grep, find, ls, lsp	agents/explorer.md
researcher	Read-only web researcher — searches and synthesizes information	true	web_search, fetch_content, get_search_content, convert_content	agents/researcher.md
reviewer	Read-only code reviewer — inspects diffs, plans, and codebase health	true	read, grep, find, ls, lsp	agents/reviewer.md
implementer	Read-only implementation planner — creates detailed, actionable implementation plans	true	read, grep, find, ls, lsp	agents/implementer.md
tester	Read-only test planner — analyzes requirements and designs comprehensive test strategies	true	read, grep, find, ls, lsp	agents/tester.md

自定义 agent 示例

---
name: api-reviewer
description: Project-specific API reviewer
readonly: true
tools: read, grep, find, ls, lsp
---

You are a project-specific API review subagent.

Only handle the delegated task. Do not call other subagents.
Use the available readonly tools to inspect API code and report findings with file paths.
If evidence is insufficient, report uncertainty.

Web researcher 示例：

---
name: docs-researcher
description: External documentation researcher
readonly: true
tools: web_search, fetch_content, get_search_content, convert_content
---

You research external documentation and return concise findings with source URLs.
Do not write files. Do not call other subagents.

命名建议

• 使用小写短横线：api-reviewer、docs-researcher。
• 避免覆盖 builtin agent 名称，除非确实想在 project/user scope 替换它。
• description 简短说明用途，方便 /toolkit agents 展示。
• readonly agent 只声明只读 tools。
• prompt 中明确任务边界、不可调用 subagents、不确定时如何汇报。

工具过滤和 readonly 行为

执行时，filterToolsForReadonly() 会基于 agent 的 readonly 与 subagents.allowWrite 过滤 tools：

• readonly agent：只保留 readonly tools。
• non-readonly agent 且 subagents.allowWrite=false：仍只保留 readonly tools。
• non-readonly agent 且 subagents.allowWrite=true：保留 agent 声明的 tools。

Readonly tools 当前包括：

read, grep, find, ls, web_search, fetch_content, get_search_content, convert_content

lsp 只有在 subagents.allowLspTools=true 且 subagents.allowedLspActions 非空时保留。子代理中 LSP privileged actions 始终禁用。

可写自定义 subagents 目前属于实验性能力。默认且推荐的模式是 readonly。subagents.allowWrite=true 只表示放宽委派策略，不代表已经具备完整权限沙箱、审计日志、自动回滚机制或稳定的写入能力契约。仅建议在可信仓库中使用，并且必须人工 review 所有变更。

对于自定义 agent：

• 子代理的实际工具可用性取决于 child pi runtime、当前工具注册、执行环境和配置。
• 不要把 readonly: false 或 allowWrite=true 理解为稳定、可控、可审计的工具权限模型。
• 文件写入、命令执行、修改项目等 write-like 行为不应被视为默认安全能力。
• 当前没有稳定的自动回滚保证；启用可写行为时应使用 Git diff、人工 review 和测试命令兜底。

无效定义

以下情况会导致 agent 文件被跳过或能力不符合预期：

• 缺少 name：文件不会被加载。
• frontmatter 不是简单 key: value：无法解析为预期字段。
• tools 使用 YAML list：不会按列表解析。
• 声明不存在的工具：工具名会被传入 child pi，但是否可用取决于 pi runtime；devkit-pi 不会在 discovery 阶段校验每个工具是否存在。
• readonly 写成 yes / True：不会解析为 true；只有 true 或 1 生效。

Source map

主题	源码
Agent discovery	src/modules/subagents/agents.ts
Frontmatter parser	src/modules/subagents/frontmatter.ts
Tool filtering	src/modules/subagents/executor.ts
Built-in agents	agents/*.md
Tests	tests/subagents/agents.test.ts, tests/subagents/frontmatter.test.ts