# @amaster\.ai/pi-goal 中文文档

规范地址：https://npmcn.com/package/%40amaster.ai/pi-goal/

版本：0\.1\.37
npm 元数据更新时间：2026-11-09T02:51:04.544Z
中文译文更新时间：2026-11-09T11:55:23.314Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/pi-goal
原文对照：https://npmcn.com/package/%40amaster.ai/pi-goal/?lang=original
项目主页：https://github.com/TGYD-helige/pi#readme
源码仓库：https://github.com/TGYD-helige/pi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.2 MB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \>=0\.80\.10，@earendil-works/pi-agent-core \>=0\.74\.0，@earendil-works/pi-coding-agent \>=0\.79\.1
- 首次发布：2026-07-17T07:11:34.628Z
- 最新版本发布：2026-11-09T02:51:04.228Z
- 近 30 天下载量：3715（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

Pi扩展从对话中获得一个目标,并保持代理工作直至满足条件

## 安装

```sh
npm install @amaster.ai/pi-goal
```

也可以使用：`pnpm add @amaster.ai/pi-goal`、`yarn add @amaster.ai/pi-goal`、`bun add @amaster.ai/pi-goal`

## README

# @ amaster.ai/pi-goal (英语)

![pi-goal preview](https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-goal/preview.png)

一个允许 Pi 的 Pi 扩展 **保持工作,直到达到目标**。您不需要自己写完成条件 。 运行 `/goal` 没有争论,扩展则从对话中得出一个可测量的条件,向您显示,以快速确认,然后让代理工作(每次运行后重新检查),直到条件维持.

以克洛德代码的停止条件机制为模型,从克洛德克思的入球模式中借入了符号/输入预算后站.

## 如何运作

1.  **定个入门.** 要么给出明确的条件(`/goal all tests pass and lint is clean`)或让扩展取自于对话(`/goal` ......没有争论.
2.  **衍生目标得到确认** 在它们开始前在交互式(TUI)模式中,因此一个被错误生成的入球不能自行跑出. 非交互模式跳过确认 .
3.  **每个探员跑后** (单位:千美元)`agent_end`),小评价模型判断该条件是否得到满足:
    -   **约会** 目标已经实现和清除。 皮停下来.
    -   **还没有** – 皮被逼要继续, 告诉剩下的.
    -   **绝对不可能** 皮停下来告诉你原因.
4.  **后举.** 继续停止 `maxIterations` 回合或一次可选 `tokenBudget` 所以一个坏球不能永远循环.

Goal state是分会话范围,并以内存进行(没有跨会话持续),匹配克洛德代码的行为.

## Pi 寿命周期( 引擎如何钩入)

入球引擎由皮的生命周期事件所驱动. 一个 `pi -p '<prompt>'` 运行( 非交互), 事件按此顺序点火 :

```
session_start                                 ← session-level, once
  │   pi-goal: load config, read the --goal flag
  ▼
[ per user prompt — the "agent-level" block below repeats ]
  │
  before_agent_start  { prompt, systemPrompt } ← carries the user's input for this turn, once per prompt
  │
  agent_start         { }
  │
  ├─ [ per turn, may repeat ]
  │    turn_start       { turnIndex }
  │    message_start    { message (user) }
  │    message_end      { message (user) }
  │    message_start    { message (assistant) }
  │    message_end      { message (assistant) }
  │    turn_end         { turnIndex, message, toolResults }
  │
  agent_end           { messages: [...] }       ← engine evaluates + stops/continues, once per prompt
  │   If a goal is active: build a transcript from `messages`, ask the
  │   evaluator ok / impossible / not-yet. Not-yet → sendUserMessage(continue)
  │   → triggers a new agent run (back to before_agent_start).
  │
  agent_settled       { }                        ← this prompt is fully done
  ▼
[ interactive: wait for next input · print mode: process exits here ]

session_shutdown                               ← on exit/switch; pi-goal clears state
```

事件 pi-目标用途:

| 活动 | 目标是什么 | 页:1 |
| --- | --- | --- |
| `session_start` | 装入配置; 读取 `--goal` 旗帜 | 课会一级,火灾一次 |
| `before_agent_start` | 如果有的话 `--goal` 条件来自 `event.prompt` (这个回合的用户输入),然后设定目标 | 每提示一次起火;由于目前还没有记录,自动起火的右锚 `session_start` |
| `agent_end` | 如果目标已激活, 请打开引擎 `event.messages`: 评价 + 标记已实现/不可能实现或队列 a `sendUserMessage` 后续行动 | 发动机核心. `event.messages` 是完整的对话,所以不需要单独的缓冲 |
| `session_shutdown` | 清除目标 | 清理 |

互动 `/goal` 命令(无参数)来自会话本身的历史,通过 `ctx.sessionManager` 这个扩展所维持的不是缓冲.

关于衍生时间的注释:只有当对话产生时,才能得出条件. `session_start` 时间太早(还没有记录); `before_agent_start` 是第一个带用户提示转弯的点,所以自动衍生键取出,而不是在启动时开火.

## 使用量

```
/goal <condition>   Set an explicit completion condition.
/goal               No active goal → derive one from the conversation (with confirmation).
                    Active goal → show its status.
/goal clear         Clear the active goal (also: stop, off, reset, none, cancel).
```

斜线命令是供交互式(TUI)使用的;打印模式无法发送. 对于 CLI / 非交互运行,请使用 `--goal` 替换为:

```
pi --goal '<condition>' -p '<prompt>'   Set an explicit goal, then run the prompt.
pi --goal '' -p '<prompt>'              Derive the goal from the prompt (at before_agent_start).
```

## 配置

设置密钥 : `pi-goal` (单位:千美元) `~/.pi/agent/settings.json`,代理目录,或项目 `.pi/settings.json`) (中文(简体) ). 项目设置仅在项目信任被接受后才被加载. 在用户和代理设置中可以使用环境可变插值,但在项目设置中则不能使用.

```json
{
  "pi-goal": {
    "model": { "provider": "anthropic", "model": "claude-haiku-4-5-20251001" },
    "maxIterations": 10,
    "tokenBudget": 200000,
    "transcriptMaxChars": 8000,
    "requireConfirmForDerived": true
  }
}
```

| 密钥 | 默认 | 目的 |
| --- | --- | --- |
| `model` | —— 说 | 确定和评价条件的提供者/模式. **关闭自动引擎** —— 说 `/goal <condition>` 仍然设定了一个目标,但没有任何自动跳动或自动继续. |
| `maxIterations` | `10` | 在Pi停止推前,最大续发. |
| `tokenBudget` | —— 说 | 可选硬标志天花板;目标被暂停(`budget_limited`)一度超过. |
| `transcriptMaxChars` | `8000` | 最大笔录字符输入以获取/评价 . |
| `requireConfirmForDerived` | `true` | 在开始一个派生目标前询问(仅限TUI). |

喜欢一个小而便宜的模型 `model` ——评估员在每一个代理人运行后运行.

## 与克洛德代码/代码的关系

-   **引擎( 来自 Claude 代码):** goal = 停止状态;Pi一直持续,直到评估师判断它满足. 被动——它驱使续作被关闭 `agent_end`,而不是背景排程器.
-   **提示( 来自 Claude 代码) :** 评估员和激活提示几乎是按Claude Code自己的截断提示逐字改编的——包括引用证据要求,"笔录中证据不足"倒计时,无法判断的纪律(助理的声称是) _证据,不是证据_),并取出被截取的"笔记".
-   **自动构造 :** 你不必说出这个条件。 (没有CC模拟——CC总是采取明确的条件. )
-   **预算支持站( 来自 Codex ) :** 符号 + 重复限制 防止跑出循环 .
-   **不包括:** Codex的闲置自动重置,暂停/重置对话框,文件后置目标,并跨会话持续.

转写限制包括角色标签和分隔符. 超大的最新消息保留了在所配置的限度内的起始和结论,并报告为部分省略的证据。 如果评价报告证据不足,继续请代理人在重新运行无法进行的检查之前收回原始文件或记录结果.

### 诊断失败

评估员的失败使目标保持活跃,使无法进行的评价变得明显;它们不会触发继续或标记目标完成. 无效的补全 API 保存, 可选 `onError` 携带安全诊断的回调 `completeOnce`, (中文(简体) ), `EvaluateOptions`,以及 `DeriveOptions`。 。 。 .

## 常见问题

### @amaster\.ai/pi-goal 是什么？

Pi扩展从对话中获得一个目标,并保持代理工作直至满足条件

### 如何安装 @amaster\.ai/pi-goal？

在项目目录运行 npm install @amaster\.ai/pi-goal，或使用 pnpm add / yarn add / bun add。

### @amaster\.ai/pi-goal 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amaster\.ai/pi-goal 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @amaster\.ai/pi-goal 可以商用吗？

@amaster\.ai/pi-goal 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @amaster\.ai/pi-goal 的下载量有多少？

根据 npm 官方下载统计，@amaster\.ai/pi-goal 在 2026/10/06 – 2026/11/04 这 30 天内被下载 3,715 次，日均约 124 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @amaster\.ai/pi-goal 还在维护吗？

最新版本 0\.1\.37 发布于 2026/11/09（今天）；至今共发布 82 个版本，其中过去 12 个月发布了 82 个；首次发布于 2026/07/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。