pi-inline-marker — 通用内联标记工具包

让 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