# @jyyyeung/pi-retro 中文文档

规范地址：https://npmcn.com/package/%40jyyyeung/pi-retro/

版本：0\.1\.3
npm 元数据更新时间：2026-11-01T11:17:49.699Z
中文译文更新时间：2026-11-01T15:17:47.842Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：51.2 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：typebox \>=0\.32\.0，@earendil-works/pi-coding-agent \>=1\.3\.0
- 首次发布：2026-11-01T10:58:07.265Z
- 最新版本发布：2026-11-01T11:02:33.305Z
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

pi编码代理设置的回顾循环：成本过滤的摩擦分类账，试验裁决，每周采用/评估/拒绝审查。

## 安装

```sh
npm install @jyyyeung/pi-retro
```

也可以使用：`pnpm add @jyyyeung/pi-retro`、`yarn add @jyyyeung/pi-retro`、`bun add @jyyyeung/pi-retro`

## README

# pi-retro

[![npm](https://img.shields.io/npm/v/@jyyyeung/pi-retro?style=flat&logo=npm&logoColor=white)](https://www.npmjs.com/package/@jyyyeung/pi-retro) [![CI](https://img.shields.io/github/actions/workflow/status/jyyyeung/pi-retro/test.yml?style=flat&logo=github&label=CI)](https://github.com/jyyyeung/pi-retro/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) [![Pi](https://img.shields.io/badge/pi-%E2%89%A51.3-6366F1?style=flat)](https://pi.dev/) [![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/)

回顾你的循环 [π](https://pi.dev/) 编码代理设置 摩擦变成了变化，而不是振动的记忆。

## 它是做什么的

代理收集数据 **摩擦** 整整一周——工具不当，令牌/上下文痛苦， 幻觉或规范漂移，git麻烦，安全隐患，工作流程漏洞 进入成本过滤分类帐。一周一次，一个评论汇总它，判定你的 活跃的 **试用**，并提出 `adopt / evaluate / reject` 的变化。你批准; 没有什么auto-applies。

如果你每周都注意到同样的摩擦，并且从不更换，就安装它 任何东西，或者如果您正在运行多个扩展并且无法确定是哪个扩展 都在赚钱。

没有内存存储（没有经过验证的事实），没有可观察性（没有调用痕迹）- a 有一个人在循环中管理改进队列。

## 安装

```bash
pi install npm:@jyyyeung/pi-retro
```

然后重启pi(或 `/reload`）。

从当地的收银台：

```bash
pi install ./pi-retro
pi -e ./pi-retro/extensions/retro.ts
```

## 快速启动

1.  在任意会话中击中摩擦→座席呼叫 `log_friction` ( 捆绑 `friction-log` 技能在真正的摩擦中触发它，无需询问)。
2.  运行 `/retro` 每周。评审人员会写一份注明日期的报告，并提出修改建议。
3.  那么，批准→申请 `friction_archive` 清理已审核的分类账。

第一个 `log_friction` 调用引导带有标题的分类帐文件 编辑（区域配置-见下文）。 `friction_stats` 在那之前就可以了 报告0和它将创建的路径，并且永远不会抛出 还没有任何记录。

`/retro-stats` 打印聚合而不调用模型转换-最便宜的 检查每周复习是否到期的方法。（`/retro` 是评论本身， 由捆绑的提示模板加上 `weekly-review` 技能。)

## 作用域

|  | 用户(默认) | 项目 |
| --- | --- | --- |
| 路径 | `~/.pi/agent/meta/problems-ledger.md` | `<repo>/.pi/retro/ledger.md` |
| 观众 | 你,跨项目 | 这个团队 |
| 为 | 个人设置摩擦（配额、主机、扩展） | 团队可以采取行动的摩擦（CI、测试、审查、工作流） |

隐私规则：条目永远不会在作用域之间复制。项目分类账为 直到有人登录才创建 `scope: "project"` 在回购中；团队 共享（提交）是团队的明确决策——忽略它直到 然后。

## 分类帐格式

每个事件一行：

```
YYYY-MM-DD | project | area | phase | problem | fix?
```

托管标记（工具编写它们；它们保持人类可读）：

-   `[x3 last 2026-10-15]` -复发：同样的摩擦在30年内再次发生 天撞了一下计数器，而不是加一条线。
-   `→ RESOLVED 2026-10-14: note` -分辨率：最强的积极信号 审查得到。

一个文字 `|` 在字段内被转义(`\|`)，读时未转义； 所以 `a || b fails` 保持与写入的完全相同，而不是被重写为 `a / b`． 旧版本编写的条目（未转义管道）仍然可以解析。行 报告那些看起来像条目但无法解析的 `friction_stats` （带有行号），而不是从总数中无声地删除。

### 配置保存在文件中

```
<!-- pi-retro: areas = tooling|tokens|hallucination|isolation|security|workflow|quality -->
```

编辑标题行以更改区域分类。文件是 自描述，包更新后仍然有效，并且可以根据作用域而有所不同。

## 工具

| 工具 | 它是做什么的 |
| --- | --- |
| `log_friction` | 追加一个条目（或碰撞一个递归）。参数: `project`， `area`， `phase`， `problem`、可选 `fix`， `cost` (S / M / L), `scope`， `force`. |
| `friction_stats` | 只读聚合：按区域/项目、打开的与已解析的、顶部重复出现的、格式错误的行计数计数。使用而不是读取整个文件。 |
| `friction_resolve` | 向匹配明确的打开条目追加解析标记。 |
| `friction_archive` | 将解析后的项移动到 `archive/YYYY-MM-DD.md`； `resolvedOnly: false` 还将未解析的项移动到空闲时间大于 `days` (默认30)。 |

## 每周的仪式(`/retro`）

1.  `friction_stats` 范围;读取未解析的条目。
2.  从试验注册表中评估ACTIVE试验(惯例： `~/.pi/agent/meta/extension-trials.md`)，反对他们的预先登记 成功标准→每次试验保留/删除/延长。
3.  可选地研究顶端摩擦区域的趋势。
4.  写一份注明日期的报告(`~/.pi/agent/meta/weekly-reviews/YYYY-MM-DD.md`） 与 `adopt` / `evaluate` / `reject` 桶——拒绝是有原因的， 而未来的建议则与之背道而驰。
5.  的建议。业主同意。然后应用，存档，并促进持久 项目文档中的经验教训。

建议是有证据支持的 `fix` 摩擦入口的场IS 以摩擦为理由的建议。故意没有 自由形式的建议收件箱。

## 范围和非目标

-   **没有记忆。** 分类帐中没有任何内容被视为已证实的事实；这个 特工的记忆系统是另一回事。
-   **不是可观察性。** 没有呼叫跟踪，计时，或令牌会计-一个 每个摩擦事件的线，只有当它确实花费了你一些东西的时候。
-   **不是自动的。** 审查建议；你批准。没有包配置 它本身是因为一个复古的说法。
-   **不是共享收件箱。** 范围永远不会合并：个人摩擦永远是私人的， 团队摩擦留在您选择共享的回购中。

## 安全与信任

-   没有网络访问，没有遥测，除了pi的主机提供之外没有任何依赖 packages（仅限peerDependencies）。
-   写操作仅限于分类帐文件及其 `archive/` 目录;否 工具接受一个路径参数。
-   附加使用 `O_APPEND`;重写写临时文件并重命名，这样就崩溃了 写入中间不能截断分类帐。
-   足够小，可以一次阅读（约850行） 它的分类模块)-请这样做。

## 要求

| 要求 | 所需 | 如果失踪 |
| --- | --- | --- |
| PI≥1.3 | 工具和 `/retro` | \- - - - - - |
| 节点≥20（22.6+才能运行测试） | 一切 | \- - - - - - |
| 一个可写的 `~/.pi/agent/meta/` (或 `PI_RETRO_LEDGER`） | 用户分类账 | `log_friction` 报告无法写入的路径 |

## 故障排除

**`friction_stats` 说账簿不存在。** 预计在第一次之前 日志：它报告0加上它将创建的路径。 `log_friction` 白手起家 第一次使用时的文件（带有可编辑的头文件）。

**我手工编辑的那一行在总数中少了。** 它无法解析。运行 `friction_stats` 同样，格式错误的行现在用行号列出 而不是被默默丢弃。通常的原因是现场秩序的改变；这个 格式是 `date | project | area | phase | problem | fix?`.

**`/retro` 没有发表任何报告。** `/retro` 是提示模板加 `weekly-review` 技巧，所以它需要一个模型转弯。 `/retro-stats` 给你 没有模型参与的相同聚合，和 `friction_stats` 把它作为 工具调用。

**账簿转错回购账户了。** 项目条目从会话中解析 慢性消耗病。 `PI_RETRO_LEDGER` 覆盖用户分类账路径；项目分类账如下 `<repo>/.pi/retro/ledger.md` 只有登录后才会出现 `scope: "project"`.

## 相关的包

针对同一个问题（代理会话共享一个签出）的五个扩展 覆盖不同时刻：

| 包 | 时刻 | 防范 |
| --- | --- | --- |
| [pi-rc-gate](https://github.com/jyyyeung/pi-rc-gate) | 在执行 | 故障信号被销毁，因此红色命令被报告为绿色 |
| [pi-checkout-guard](https://github.com/jyyyeung/pi-checkout-guard) | 在 | 并发会话擦除彼此未提交的工作 |
| [pi-closeout](https://github.com/jyyyeung/pi-closeout) | 会话结束时 | 会话为下一个会话留下的脏状态 |
| **pi-retro** (这) | 每周 | 摩擦不断出现，因为没人写下来 |
| [pi-handoff](https://github.com/jyyyeung/pi-handoff) | 之间的会话 | 会话结束时上下文丢失 |

## 开发

```bash
npm install
npm run typecheck   # tsc --noEmit
npm test            # node --test (type-stripped TS, node >= 22.6)
```

## 许可证

MIT©jyyyeung

## 常见问题

### @jyyyeung/pi-retro 是什么？

pi编码代理设置的回顾循环：成本过滤的摩擦分类账，试验裁决，每周采用/评估/拒绝审查。

### 如何安装 @jyyyeung/pi-retro？

在项目目录运行 npm install @jyyyeung/pi-retro，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\>=0\.32\.0）、@earendil-works/pi-coding-agent（\>=1\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @jyyyeung/pi-retro 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/jyyyeung\_\_pi-retro 是否存在。

### @jyyyeung/pi-retro 支持 ESM 还是 CommonJS？

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

### @jyyyeung/pi-retro 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @jyyyeung/pi-retro 可以商用吗？

@jyyyeung/pi-retro 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @jyyyeung/pi-retro 还在维护吗？

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