# rinco-pi-rule **让 Pi 一条命令识别项目技术栈，并把匹配的 ECC 规则安全写入 `AGENTS.md`。** [![Pi Extension](https://img.shields.io/badge/Pi-extension-6f42c1?style=flat-square)](https://pi.dev) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.6-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Tests](https://img.shields.io/badge/tests-Vitest-6E9F18?style=flat-square&logo=vitest&logoColor=white)](https://vitest.dev/) [![License](https://img.shields.io/badge/license-MIT-C7B8F5?style=flat-square)](LICENSE) [功能](#功能) · [安装](#安装) · [使用](#使用) · [技术栈检测](#技术栈检测) · [工作原理](#工作原理) · [开发](#开发) · [常见问题](#常见问题) [English](README.md)
`rinco-pi-rule` 是一个离线、确定性的 [Pi](https://pi.dev) 扩展。它通过 `/rules:init` 扫描当前项目，识别 Python、JavaScript/TypeScript 与 React，并将对应的 [Everything Claude Code（ECC）](https://github.com/affaan-m/ECC)规则合并到项目级 `AGENTS.md`。重复运行只会替换托管区块，不会覆盖团队手写内容。 ## 功能 - **零配置识别技术栈**：根据项目标记、依赖和源码扩展名自动选择规则，无需配置文件。 - **保留人工规则**：只管理带标记的 ECC 区块，其他 `AGENTS.md` 内容原样保留。 - **离线且可复现**：规则固定到明确的 ECC commit，运行时不访问网络。 - **安全写入**：原子替换文件；遇到损坏标记、重复标记或符号链接时主动停止。 - **避免命令冲突**：使用命名空间命令 `/rules:init`，不占用常见的 `/init`。 - **确定性的输出**：按规则层和文件名稳定排序，所有交叉引用链接均固定到 commit 级别的 GitHub URL。 ## 安装 ### 从 npm 安装（推荐） ```bash pi install npm:rinco-pi-rule ``` 该包已发布至 [npm](https://www.npmjs.com/package/rinco-pi-rule)。 ### 从 GitHub 安装 ```bash pi install git:github.com/Rinisnotarobot/rinco-pi-rule ``` ### 从本地目录安装 ```bash git clone https://github.com/Rinisnotarobot/rinco-pi-rule.git cd rinco-pi-rule pi install "$PWD" ``` 仅为当前项目安装： ```bash pi install -l "$PWD" ``` > [!IMPORTANT] > Pi 扩展以当前用户权限运行。安装任何第三方扩展前，请先审查其源码。 ## 使用 ### 环境要求 | 依赖 | 版本要求 | | --- | --- | | Node.js | `>=20.6.0` | | `@earendil-works/pi-coding-agent` | 任意兼容版本（peer dependency） | 在目标项目目录中启动 Pi，然后运行： ```text /rules:init ``` 扩展会扫描项目、识别技术栈，并以原子方式创建或更新 `AGENTS.md` 中的 ECC 托管规则区块。后续运行仅更新两个标记之间的内容。 ### 生成结果 首次运行会创建 `AGENTS.md`；如果文件已经存在，则在保留原内容的同时添加托管区块： ```markdown # 团队自定义规则 这里的内容由团队维护，不会被插件修改。 ## 面向 Pi 的 ECC 衍生规则（托管） ...根据项目技术栈选择的规则... ``` 再次运行 `/rules:init` 时，仅两个标记之间的内容会被更新。 > [!WARNING] > 不要手动复制标记，也不要只删除其中一个标记。发现缺失、倒置或重复标记时，扩展会停止写入，避免破坏 `AGENTS.md`。 ## 技术栈检测 规则始终按 `common → python → typescript → react` 的顺序分层；越靠后的规则越具体，发生冲突时优先级越高。

通用规则 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 等混合仓库会同时加载所有匹配层。 扫描会忽略常见依赖和构建目录，包括： ```text .git node_modules dist build coverage .next .turbo .venv venv __pycache__ vendor target .cache ``` 为避免在超大型目录中无限扫描，单次检测最多处理 5,000 个条目。 ## 工作原理 ```mermaid 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/ecc/SHA256SUMS)；经过审查的衍生规则位于 `rules/pi/`。`/rules:init` 不执行远程下载，也不会修改托管标记以外的手写规则。 为了防止意外覆盖，扩展会拒绝以下情况： - `AGENTS.md` 是符号链接。 - `AGENTS.md` 不是普通文件。 - 托管标记缺失一端、顺序错误或重复出现。 - 命令携带不支持的参数。 ## 项目内容 | 路径 | 说明 | | --- | --- | | [`index.ts`](index.ts) | Pi 扩展入口和 `/rules:init` 命令注册 | | [`src/init.ts`](src/init.ts) | 基于文件变异队列的原子化 AGENTS.md 合并 | | [`src/detect-project.ts`](src/detect-project.ts) | 技术栈检测：项目标记、依赖和源码扩展名 | | [`src/agents-md.ts`](src/agents-md.ts) | 规则转换、渲染和托管区块合并 | | [`src/rules.ts`](src/rules.ts) | ECC 快照加载、Pi 覆盖规则选择和规则层排序 | | [`rules/ecc/`](rules/ecc/) | 未修改的固定 ECC 规则快照与 SHA256 校验值 | | [`rules/pi/`](rules/pi/) | 按相同相对路径组织的、经过审查的 Pi 适配规则 | | [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | 本地开发、测试规范和 PR 检查清单 | | [`tests/`](tests/) | Vitest 测试套件，覆盖检测、合并和扩展行为 | ## 开发 ### 环境要求 - [Node.js](https://nodejs.org/) 20.6 或更高版本 - [Pi](https://pi.dev) 安装开发依赖： ```bash 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` 检查发布包内容，不生成正式发布。 | 运行测试： ```bash npm test ``` 监听文件变化： ```bash npm run test:watch ``` 验证测试、类型检查和包内容： ```bash npm run check ``` Vitest 覆盖了检测逻辑、托管区块合并、规则转换和扩展生命周期。贡献代码前请阅读 [`docs/CONTRIBUTING.md`](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`](THIRD-PARTY-NOTICES)，项目许可见 [`LICENSE`](LICENSE)。