12 · 路线 A：把 Pi 变成你的个人 Agent¶

12.1 最小方案是什么¶

先不要 fork。用四样东西表达你的习惯：项目规则、任务模板、专业 skill、确实需要的工具扩展。课程已经准备 examples/pi-package 研究包，你可以复制后改自己的名字与流程。

它会增加 research_checklist 工具、/research 模板、source-research skill 和 /research-status 命令，并拦截内建 bash / powershell / edit / write。

这是研究工作流限制，不是完整沙箱；第三方扩展或其他 MCP 工具仍可能有副作用。不要给这个包写「绝对安全只读」这样的产品说明。

12.2 在自己的测试项目安装¶

cd /path/to/your/test-project
pi install -l /home/debian/codex/learn/pi/examples/pi-package
pi --tools read,grep,find,ls,research_checklist

-l 把 package 配置写到当前项目，先在测试项目里试。项目 resources 需要信任；确认该包就是你刚读过的内容后允许加载。

进入 Pi：

/research-status
/research src/main.ts
/skill:source-research 解释这个项目的初始化顺序

改资源后 /reload。卸载：

pi remove -l /home/debian/codex/learn/pi/examples/pi-package

如果你只用临时扩展路径，可 pi -e /absolute/path/research.ts；它不会自动同时安装 package 的 skill 和 template。

12.3 写自己的 AGENTS.md¶

规则写成可检查的行为：

# 工作规则

先阅读实际文件，再给修改方案。
研究结论给出文件路径和函数名。
代码修改后运行该项目已有的相关检查。
不能验证的内容标注为未验证。
最终说明修改、证据、检查与剩余问题。

避免泛泛地写「你是世界上最聪明的工程师」。模型需要知道怎样工作和什么算完成，不需要角色夸张描述。

如果任务要求改文件，别用本课程研究包同时拦截 edit/write 然后又期待修改成功。按工作场景建立研究与实施两套配置，而不是把一个模板写成所有能力集合。

12.4 Prompt template¶

prompts/research.md 的变量 ${1:-...} 给默认路径；也可用 $@ 获取全部参数。展开后是 user message，所以模板没有自动执行检查或权限约束。

自己的模板可以是 /weekly、/review、/explain。适用场景是反复发同一结构的请求，不必为一段纯文字写复杂 Extension。

12.5 Skill：写清什么时候用¶

skill 包含 frontmatter 的 name / description 和正文步骤。description 在启动 prompt 中作为路由提示，正文按需读取。

例如你的研究 skill：

---
name: source-research
description: 研究源码设计、调用链与状态边界，输出可核对的文件证据。
---

先固定版本，再找入口和核心循环。
把正常、失败与取消三条路径分别描述。
每个结论给文件路径，无法验证的内容说明限制。

目录里可以放 references 和 scripts。引用相对路径相对于 skill 目录，不是用户当前 cwd。用 /skill:name 明确触发，解决模型没主动加载的问题。

12.6 Extension：把要求变成真实行为¶

研究包的拦截：

pi.on("tool_call", async (event) => {
  if (["bash", "powershell", "edit", "write"].includes(event.toolName)) {
    return { block: true, reason: "研究工作流禁止这些内建工具" };
  }
  return undefined;
});

比只写「不要修改」更可靠，因为 execute 前真的会阻断。还要考虑自定义工具名、嵌套调用、远程服务和 extension 自己的代码能力。

registerTool 加一个有 schema 的工具；registerCommand 给人用的 slash command；两者不要混用。模型通常调用工具，不通过终端字符串假装用户输入 /command。

12.7 Package：把配方分发出去¶

{
  "name": "my-research-kit",
  "version": "1.0.0",
  "type": "module",
  "pi": {
    "extensions": ["./extensions/research.ts"],
    "skills": ["./skills"],
    "prompts": ["./prompts"]
  }
}

用本地路径、git 或 npm 发布都可以。本课程没有替你发布 npm 包。将来发布前应确认没有 secrets、测试过实际包内容，并使用自己的组织命名。

12.8 第一套个人 Agent 的验收¶

启动 diagnostics 无资源加载错误。
/research-status 可执行，/research 模板可展开。
research_checklist 的参数和结果清楚。
真实调用一个被禁止工具时返回 error，不执行动作。
关闭再恢复，配置仍能加载。
卸载后相关命令和工具消失。

源码完整文件见配套代码下载，以及扩展机制。

12.9 把它改成自己的领域助手¶

如果目标是运维：先做状态查询 skill，再新增窄工具 get_service_status；部署工具另加授权与幂等。目标是写作：重点放模板、资料检索和风格规则。目标是业务分析：先定义数据来源和口径，再写检索工具。

一个属于你的 Agent 的差异，应主要体现在知识、工具、约束和评测样例上，而不是给通用 coding agent 换一个名字。