rinco-pi-rule

让 Pi 一条命令识别项目技术栈，并把匹配的 ECC 规则安全写入 AGENTS.md。

功能 · 安装 · 使用 · 技术栈检测 · 工作原理 · 开发 · 常见问题

English

rinco-pi-rule 是一个离线、确定性的 Pi 扩展。它通过 /rules:init 扫描当前项目，识别 Python、JavaScript/TypeScript 与 React，并将对应的 Everything Claude Code（ECC）规则合并到项目级 AGENTS.md。重复运行只会替换托管区块，不会覆盖团队手写内容。

功能

• 零配置识别技术栈：根据项目标记、依赖和源码扩展名自动选择规则，无需配置文件。
• 保留人工规则：只管理带标记的 ECC 区块，其他 AGENTS.md 内容原样保留。
• 离线且可复现：规则固定到明确的 ECC commit，运行时不访问网络。
• 安全写入：原子替换文件；遇到损坏标记、重复标记或符号链接时主动停止。
• 避免命令冲突：使用命名空间命令 /rules:init，不占用常见的 /init。
• 确定性的输出：按规则层和文件名稳定排序，所有交叉引用链接均固定到 commit 级别的 GitHub URL。

安装

从 npm 安装（推荐）

pi install npm:rinco-pi-rule

该包已发布至 npm。

从 GitHub 安装

pi install git:github.com/Rinisnotarobot/rinco-pi-rule

从本地目录安装

git clone https://github.com/Rinisnotarobot/rinco-pi-rule.git
cd rinco-pi-rule
pi install "$PWD"

仅为当前项目安装：

pi install -l "$PWD"

[!IMPORTANT] Pi 扩展以当前用户权限运行。安装任何第三方扩展前，请先审查其源码。

使用

环境要求

| 依赖 | 版本要求 | | --- | --- | | Node.js | >=20.6.0 | | @earendil-works/pi-coding-agent | 任意兼容版本（peer dependency） |

在目标项目目录中启动 Pi，然后运行：

/rules:init

扩展会扫描项目、识别技术栈，并以原子方式创建或更新 AGENTS.md 中的 ECC 托管规则区块。后续运行仅更新两个标记之间的内容。

生成结果

首次运行会创建 AGENTS.md；如果文件已经存在，则在保留原内容的同时添加托管区块：

# 团队自定义规则

这里的内容由团队维护，不会被插件修改。

<!-- rinco-pi-rule:ecc:start -->
## 面向 Pi 的 ECC 衍生规则（托管）

...根据项目技术栈选择的规则...
<!-- rinco-pi-rule:ecc:end -->

再次运行 /rules:init 时，仅两个标记之间的内容会被更新。

[!WARNING] 不要手动复制标记，也不要只删除其中一个标记。发现缺失、倒置或重复标记时，扩展会停止写入，避免破坏 AGENTS.md。

技术栈检测

规则始终按 common → python → typescript → react 的顺序分层；越靠后的规则越具体，发生冲突时优先级越高。

| 规则层 | 选择条件 | | --- | --- | | common | 始终加载 | | python | 发现 .py、.pyi、pyproject.toml、requirements*.txt、setup.py、uv.lock 等 Python 标记 | | typescript | 发现 JS/TS 源码、package.json、JS 锁文件、Deno 配置或 TypeScript 配置 | | react | package.json 声明 React 生态依赖，或项目包含 .jsx / .tsx 文件 |

React 会自动包含 TypeScript 规则；JavaScript 项目同样使用 ECC 的 typescript 规则层。Python 与 React 等混合仓库会同时加载所有匹配层。

扫描会忽略常见依赖和构建目录，包括：

.git  node_modules  dist  build  coverage  .next  .turbo
.venv  venv  __pycache__  vendor  target  .cache

为避免在超大型目录中无限扫描，单次检测最多处理 5,000 个条目。

工作原理

flowchart LR
    command["/rules:init"] --> detect["扫描项目标记、依赖与源码"]
    detect --> layers["选择 common / python / typescript / react"]
    layers --> snapshot["加载内置 ECC 固定快照"]
    snapshot --> adapt["应用已审查的 Pi 覆盖规则"]
    adapt --> transform["移除 frontmatter、调整标题、固定链接"]
    transform --> merge["合并 AGENTS.md 托管区块"]
    merge --> atomic["原子写入"]

规则资源从扩展自身的 rules/ecc/ 加载，不依赖目标项目的当前工作目录。每一条上游规则都在 rules/pi/ 下拥有相同相对路径的、经过审查的衍生版本。Pi 规则集保留适用的语言与框架指导，同时将上游特定于其他 harness 的 agent、hooks、skills、配置、模型、任务和自动化假设替换为按当前能力工作的原生 Pi 流程。

生成时会：

1. 应用匹配的 Pi 适配规则，同时保留原始 ECC 快照。
2. 移除 ECC 文件中的路径 frontmatter。
3. 将规则标题降级到托管区块之下。
4. 把相对 ECC 文档链接改写为 commit 固定的 GitHub URL。
5. 按规则层和文件名稳定排序。
6. 保留现有文件权限后执行原子重命名。

安全与可复现性

上游规则固定于 ECC commit 623f2c0。原始 Markdown 保留在 rules/ecc/，文件校验值记录在 rules/ecc/SHA256SUMS；经过审查的衍生规则位于 rules/pi/。/rules:init 不执行远程下载，也不会修改托管标记以外的手写规则。

为了防止意外覆盖，扩展会拒绝以下情况：

• AGENTS.md 是符号链接。
• AGENTS.md 不是普通文件。
• 托管标记缺失一端、顺序错误或重复出现。
• 命令携带不支持的参数。

项目内容

| 路径 | 说明 | | --- | --- | | index.ts | Pi 扩展入口和 /rules:init 命令注册 | | src/init.ts | 基于文件变异队列的原子化 AGENTS.md 合并 | | src/detect-project.ts | 技术栈检测：项目标记、依赖和源码扩展名 | | src/agents-md.ts | 规则转换、渲染和托管区块合并 | | src/rules.ts | ECC 快照加载、Pi 覆盖规则选择和规则层排序 | | rules/ecc/ | 未修改的固定 ECC 规则快照与 SHA256 校验值 | | rules/pi/ | 按相同相对路径组织的、经过审查的 Pi 适配规则 | | docs/CONTRIBUTING.md | 本地开发、测试规范和 PR 检查清单 | | tests/ | Vitest 测试套件，覆盖检测、合并和扩展行为 |

开发

环境要求

• Node.js 20.6 或更高版本
• Pi

安装开发依赖：

npm install

可用命令

| 命令 | 说明 | | --- | --- | | npm test | 使用 Vitest 运行一次完整测试套件。 | | npm run test:watch | 以监听模式运行 Vitest，并在文件变化后重新测试。 | | npm run test:coverage | 运行所有测试并使用 V8 覆盖率（最低 80%）。 | | npm run typecheck | 执行 TypeScript 类型检查，不生成 JavaScript。 | | npm run check | 依次执行类型检查、测试和 npm 打包预检。 | | npm run pack:dry-run | 使用 npm pack --dry-run 检查发布包内容，不生成正式发布。 |

运行测试：

npm test

监听文件变化：

npm run test:watch

验证测试、类型检查和包内容：

npm run check

Vitest 覆盖了检测逻辑、托管区块合并、规则转换和扩展生命周期。贡献代码前请阅读 docs/CONTRIBUTING.md。

常见问题

原生 Pi 不安装任何插件也能使用生成的规则吗？

可以。使用 /rules:init 生成或更新托管区块需要本扩展，但消费规则不需要插件。AGENTS.md 创建后，原生 Pi 会通过内置的上下文文件机制加载它。所有强制工作流都可以只用 Pi 核心的 read、write、edit、bash 工具完成；Skills、Extensions、评审工具、任务列表、浏览器工具和子 Agent 都只是可选增强，并且规则中提供了回退路径。

已使用 Pi 0.84.1 和隔离配置实测：在同时启用 --no-extensions --no-skills --no-prompt-templates --no-themes 时，原生 Pi 成功从 AGENTS.md 加载了全部 26 条 common、Python、TypeScript 和 React 规则。如果希望未安装本扩展的用户也自动获得规则，应把生成后的 AGENTS.md 提交到仓库。未安装扩展时，/rules:init 命令本身不可用，规则更新需要在其他环境生成或手动完成。

会覆盖现有的 AGENTS.md 吗？

不会。没有托管区块时，扩展会将其追加到文件末尾；已有托管区块时，只替换该区块。所有区块外内容都会保留。

为什么不在运行时拉取最新 ECC 规则？

固定快照能保证离线使用、稳定测试和可重复生成，也避免上游更新在没有审查的情况下改变项目规则。

为什么 React 项目的 AGENTS.md 比较大？

React 层会同时加载 common、typescript 和 react。该实现有意嵌入完整规则，让 Pi 能直接将其作为项目上下文使用。

支持 /rules:init --force 吗？

不支持，也不需要。命令默认安全更新托管区块；任何额外参数都会显示用法提示且不会写入文件。

能否只加载部分规则文件？

当前版本按技术栈加载完整规则层，尚未提供单文件筛选配置。

第三方规则的来源与许可信息见 THIRD-PARTY-NOTICES，项目许可见 LICENSE。