@rotart/pi-ex-command

@rotart/pi-ex-command 是一个 Pi 扩展，用于创建、编辑、组织和浏览本地 prompt 模板。模板可激活为当前会话的系统提示词，通过 before_agent_start 事件自动注入。

亮点

• 🧩 三大子命令：create、edit、list，简洁统一。
• 🔌 系统提示词注入：激活模板后，后续 agent 会话自动注入模板内容作为系统提示词。
• 📂 三级交互浏览器：分类 → 模板 → 操作（注入 / 预览 / 编辑 / 删除）。
• 🏷️ YAML 前置元数据：每个模板自带标题、描述、分类、子分类、来源章节和标签。
• 🔎 自动补全：子命令和已有模板名均支持自动补全。
• 🧹 清空正文：编辑时可选清空正文，保留模板名和元数据。
• ⚡ 三级缓存系统：目录快照（1s TTL）+ 元数据缓存（mtime 驱动 + 5s TTL）+ 描述索引，自动补全热路径零系统调用。
• 💾 本地存储：模板以自包含 Markdown 文件存储在 ~/.pi/orders/ 下。

安装

从 npm 安装：

pi install npm:@rotart/pi-ex-command

安装后重载 Pi：

/reload

快速开始

快速创建模板（标题 + 正文）：

/order create code-review

完整创建模板（含分类、标签等所有字段）：

/order create code-review --full

浏览、激活和管理模板：

/order list

在交互浏览器中，选择 注入为系统提示词 即可将模板内容注入当前会话。

命令参考

命令	说明
/order create <name>	快速创建模板（标题 + 正文）
/order create <name> --full	完整创建模板（含分类、子分类、标签、来源章节）
/order edit <name>	编辑模板。子菜单：编辑正文 / 编辑元数据 / 清空正文
/order list	三级交互浏览器：分类 → 模板 → 操作

模板浏览器操作

在 /order list 中，对每个模板可执行：

• 注入为系统提示词 — 激活模板，后续 agent 会话自动注入该模板内容
• 取消激活 — 恢复默认系统提示词
• 预览正文内容 — 以只读编辑器查看模板正文
• 编辑 — 进入编辑流程
• 删除 — 删除模板（若已激活则自动取消激活）

模板名只允许字母、数字、_ 和 -。

存储

模板以自包含 Markdown 文件存储，YAML 前置元数据包含完整描述信息：

~/.pi/orders/<name>.md

每个 .md 文件包含 YAML frontmatter 元数据块：

---
title: 代码审查模板
description: 标准代码审查流程
category: 开发流程
subcategory: 代码质量
source_section: "3.2"
tags: 审查, 代码质量, 团队协作
updated: 2026-06-11
---

# 代码审查流程

## 前置检查

确保所有自动化检查通过，解决合并冲突...

前端元数据结构：

字段	类型	说明
title	string	模板标题（默认等同文件名）
description	string	模板描述，用于自动补全识别
category	string	分类名称，用于 /order list 分组浏览
subcategory	string	子分类（可选）
source_section	string	来源章节（可选）
tags	string	逗号分隔标签（可选）
updated	string	最后更新时间（写入时自动生成）

本扩展不会上传模板内容到任何地方。

外部编辑模板

可使用任何文本编辑器直接编辑 ~/.pi/orders/ 下的 .md 文件。前端元数据在文件顶部，与正文一同编辑。缓存系统会在约 1 秒内自动检测外部变更。

迁移工具

从旧版 descriptions.json 迁移到新前端元数据格式：

npx pi-ex-command-migrate

SDK 编程接口

TemplateStore 类和模板管理函数已导出，供 agent 或脚本使用：

import { TemplateStore } from "@rotart/pi-ex-command/store";
import { activateTemplate, deactivateTemplate, getActiveTemplate } from "@rotart/pi-ex-command";

const store = new TemplateStore();

// 创建并写入模板（含前端元数据）
await store.createTemplate("my-template");
await store.writeTemplate("my-template", "正文内容", {
  title: "我的模板",
  description: "这是我的模板描述",
  category: "AI方法",
  tags: "元提示词, RTF",
});

// 读取模板（含元数据）
const { meta, body } = await store.readTemplateWithMeta("my-template");

// 获取所有分类
const categories = await store.getCategories();

// 按分类获取模板
const templates = await store.getByCategory("AI方法");

// 激活模板（注入系统提示词）
activateTemplate("my-template");

// 取消激活
deactivateTemplate();

事件：before_agent_start

激活模板后，每次 agent 启动前会自动注入模板内容：

pi.on?.("before_agent_start", async (event, _ctx) => {
  const active = getActiveTemplate();
  if (!active) return;

  const store = new TemplateStore();
  const content = await store.readTemplate(active);
  return {
    systemPrompt: `<order_template name="${active}">\n${content}\n</order_template>\n\n${event.systemPrompt}`,
  };
});

注意：通过文件系统直接写入 ~/.pi/orders/（绕过 TemplateStore）后，调用 store.clearCache() 刷新缓存。

缓存架构

三级缓存设计，最大程度减少文件系统 I/O：

层级	说明	TTL
目录快照	文件名 + mtime 列表	1 秒
模板元数据	单个模板的 frontmatter + mtime 校验	5 秒
描述索引	全量 name→description 映射	随目录快照失效

自动补全热路径在首次触发后零系统调用。

开发

git clone https://github.com/LinMingjing007/pi-order.git
cd pi-order
npm install
npm run build
npm test

常用脚本：

npm run build          # 编译 TypeScript
npm test               # 构建 + 运行测试
npm pack --dry-run     # 检查发布包内容

发布

本仓库通过 GitHub Actions 发布到 npm。

1. 更新代码和测试

2. 升级版本号：

   npm version patch --no-git-tag-version
   

3. 提交并打标签：

   git add .
   git commit -m "Release vX.Y.Z"
   git tag -a vX.Y.Z -m "vX.Y.Z"
   git push origin main
   git push origin vX.Y.Z
   

4. GitHub Actions 自动运行测试并发布到 npm。

许可证

MIT © LinMingjing007