pi-inline-marker

August 7, 2026 · View on GitHub

让 LLM 在回答正文里直接写 [[tool:op:...]] 内联标记来驱动"纯状态类"工具 （todo、通知、开关等），免除"调用工具 → 等待结果回喂 → 续写一轮"的 LLM 往返。

  • 零工具往返：状态操作变成正文里几个字符，不再暂停等一次续写。
  • 不改写原文：保留 assistant 原始文本，不破坏 provider 前缀缓存，无孤立反引号。
  • 可扩展：任何插件都能通过 registerMarker() 把状态工具接进来，共享解析/落库/overlay。
  • 状态绑分支：状态作为会话条目快照存储，/new /fork /resume 时自动跟随历史点。

安装

pi install npm:pi-inline-marker

或单次试用：

pi -e npm:pi-inline-marker

标记语法

通用形式：[[tool:op:pos1,pos2,k=v]]

标记含义
[[todo:new:<主题>]]新建 pending 任务
[[todo:set:<id>,completed|in_progress|pending]]改任务状态（可带 activeForm=）
[[todo:remove:<id>]]删除（tombstone）
[[todo:dep:<id>,blocks=<依赖id,逗号分隔>]]设依赖
[[notify:<级别>:<内容>]]非打断通知（info/warning/error）

AI 会把引导注入 system prompt，自动用标记而不是调工具做状态操作。读操作 （需要回喂结果的查询）用 markers_list 工具或 /markers 命令。

命令

  • /markers — 查看当前任务/状态
  • /markers diagnose — 诊断：已注册标记、当前快照、语法示例
  • /markers clear:todo — 清空某个命名空间

机制

  1. before_agent_start 注入标记 guidance。
  2. message_end 解析助手终稿中的 [[...]]，逐个执行、校验、落库、更新 overlay。
    • 保留原文：不剥除、不替换消息 → 缓存零影响。
    • 成功 → 状态入库；失败/未知标记 → 不执行、原文保留供补救。
  3. 状态写入会话 custom entry 快照，绑定当前分支。

扩展你自己的标记工具

标记框架默认内置 todo / notify。要加自己的标记工具，在 src/builtins/ 里新增一个 符合 MarkerTool 接口的模块，并在 src/index.ts 顶部 registerMarker(...) 注册即可。

MarkerTool 接口（见 src/marker.ts）：

interface MarkerTool<State> {
  name: string;                    // 标记前缀，如 "flag"
  guidance: string[];              // 注入 system prompt 的约定说明
  apply(token, ctx, state): Promise<ApplyResult> | ApplyResult;
  overlay?(state, ctx): MarkerOverlay | undefined;
  init?(): State;                  // 首次创建时的默认状态
}

// 示例：一个"开关"标记
registerMarker({
  name: "flag",
  guidance: ["- [[flag:on:<名>]] 开；[[flag:off:<名>]] 关。"],
  apply(token, ctx, state) {
    if (token.op === "on") { state[token.args[0]] = true; return { applied: true, feedback: "on" }; }
    if (token.op === "off") { state[token.args[0]] = false; return { applied: true, feedback: "off" }; }
    return { applied: false, error: "未知 flag 操作" };
  },
  init: () => ({}),
} as MarkerTool);

结构

pi-inline-marker/
├── src/
│   ├── index.ts        # 主入口：引导注入 / message_end 解析执行落库 / overlay / /markers
│   ├── marker.ts       # MarkerTool 接口 + 解析器
│   ├── store.ts        # 会话分支绑定的状态持久化
│   ├── registry.ts     # registerMarker() 注册表
│   └── builtins/
│       └── todo.ts     # 内置 todo + notify 标记
├── package.json        # pi manifest + pi-package 关键字
├── README.md
└── LICENSE

许可证

MIT