Example

让模型所知的内容跟随活动工具

从 pi.getActiveTools() 写出一个 before_agent_start 提示词节,并给落定守卫加上边界,让它恰好催促一次。

注册 run_checks 并没有告诉模型它存在。这个示例从 pi.getActiveTools() 推导提示词指引,并给落定守卫加上只催促一次的边界——一切都观察自一个脚本化的模型,而不是真实模型。

运行它

使用 Pi 1.0.4 和示例仓库的测试运行器。下面是那些规范扩展的摘录:

	pi.on("before_agent_start", (event) => {
		// getActiveTools(), not getAllTools(). getAllTools() reports every
		// *registered* tool, so a tool the session disabled would still be
		// described here — and the model would be told to use something it
		// cannot call. The active set is what is declared to the model.
		const active = pi.getActiveTools();
		if (!active.includes("run_checks")) {
			// Delete rather than leave stale: a section written for a previous
			// turn outlives the condition that produced it.
			delete event.systemPromptOptions.sections.review_guard;
			return;
		}

		event.systemPromptOptions.sections.review_guard =
			"- `run_checks` runs this repository's type check and unit tests. " +
			"Use it instead of running a command yourself before reporting on a change. " +
			"- Force pushes are blocked by an extension. If a push is refused, do not retry with a different form.";
	});

这个节跟随活动集合,而不是已注册的集合:pi.getAllTools() 报告这个会话已定义的每一个工具,所以一个被停用的工具仍然会被描述。同一个处理器可以为内置工具写一个 tool_guidance 节,并在什么都不匹配时丢掉它。

坚持某一步在落定之前发生:

	pi.on("agent_before_settle", async (event) => {
		const ranChecks = event.context.contextMessages.some(
			(m) => m.role === "toolResult" && m.toolName === "run_checks",
		);
		if (ranChecks) return;

		// Nudge once. Without this, a model that never runs the checks is asked
		// again after every answer, forever.
		const alreadyNudged = event.context.contextMessages.some(
			(m) => m.role === "custom" && m.customType === "review-guard",
		);
		if (alreadyNudged) return;

		return {
			entries: [
				{
					type: "custom_message",
					customType: "review-guard",
					content: "You reported on a change without running `run_checks`. Run it now and revise.",
					display: false,
				},
			],
			continue: true,
		};
	});

预期结果

提示词状态 provider 的系统消息
run_checks 已激活 一个指明该工具的 review_guard 节
run_checks 已注册但未激活 被删除;该工具不被描述
模型没有运行 run_checks 就做出了回答 一次继续,然后落定——恰好两个请求

机制与局限

有文档记载: before_agent_start 暴露 event.systemPromptOptions.sections;agent_before_settle 可以为再一次请求返回 { entries, continue: true };extensions.md 警告一次无条件的继续可能循环。已观察: knowledge.test.ts 用一个脚本化的 provider 和一个 AgentSession 驱动每一个处理器,并检查 provider 收到了什么——一个 tool_guidance 节作为一个具名的 <tool_guidance>…</tool_guidance> 块到达。那个探针钉住了访问器之间的分歧:run_checks 在每一个会话里都注册了,然而只有活动的集合看得见那份指引。落定守卫恰好问一次——一个从不运行那些检查的模型产生两个请求,而一个运行了的则不会被问。在 1.0.4 上,那个节没有出现在 session.systemPrompt 中;去检查请求,而不是那个访问器。

这是模型周围的代码,而不是一个遵循它的真实模型:一个提示词节可以描述 run_checks,它无法强制那次调用。

完整源码与测试 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.