# @cratis/pi 中文文档

规范地址：https://npmcn.com/package/%40cratis/pi/

版本：7\.125\.1
npm 元数据更新时间：2026-10-31T20:27:13.003Z
中文译文更新时间：2026-10-31T21:39:02.219Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cratis/pi
原文对照：https://npmcn.com/package/%40cratis/pi/?lang=original
项目主页：https://www.cratis.io/ai/
源码仓库：https://github.com/Cratis/AI

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

- 包体积（解压后）：9.2 MB，1153 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-09-10T20:04:37.664Z
- 最新版本发布：2026-10-31T20:27:12.683Z
- 已发布版本数：290（近 12 个月 290 个）

## 中文简介

Pi的配置感知Cratis AI集成

## 安装

```sh
npm install @cratis/pi
```

也可以使用：`pnpm add @cratis/pi`、`yarn add @cratis/pi`、`bun add @cratis/pi`

## README

# Pi的Cratis AI集成

这是 **插件的路径** 对于不使用 `cratis ai`. 将它安装到一个Pi项目中：

```bash
pi install -l npm:@cratis/pi
```

包读取存储库的 `.cratis/ai.json`，解析其配置文件和 语言通过打包的概要文件目录，并且只提供匹配 技能。它还会加载打包好的规则、路径引导、提示、代理等 子代理工具和Cratis质量钩子。当没有 `.cratis/ai.json` 存在，就暴露了完整 打包的技能集。因此，它给了Pi完整的单线束克拉提斯 不需要Cratis CLI的经验。

这个 `subagent` 当另一个扩展已经存在时，工具将停止会话 提供名为。的委托工具 `Agent` (例如pi-subagents，它列出了 同样的代理)。它在会话开始时将自己从活动工具中移除 当Pi有UI时显示一个通知，因此模型没有提供两个委托 工具。包通过声明生成的pi本机代理 `pi.subagents.agents` 用于支持包资源的外部加载器。他们用逗号分隔 `tools:` allowlists已经使用Pi名(`read`， `grep`， `find`， `bash`， `edit`， `write`)， 所以两个加载器都不需要解释claude风格的名称。看到 [代理适配器](https://github.com/Cratis/AI/blob/main/Documentation/agent-adapters.md) 用于再生和漂移检查。

当一个存储库必须配置和时，仍然可以选择托管的CLI路径 同步多个线束。将解析后的语料库写入 `.cratis/ai`， 创建每个线束集成，并记录哈希以便安全更新和 卸载。管理设置通过它自己加载规则 `.pi/extensions/cratis-rules` 和 `.pi/extensions/cratis-path-guidance` 扩展和不需要这个包。如果两个路径都存在，则包 生成托管安装，以避免重复的资源和钩子。π 包只管理Pi；它既不配置其他线束，也不拥有本地线束 语料库管理。

## 语料库中的MCP服务器

打包的 `cratis-mcp` 扩展启动中声明的每个工作室服务器 `mcp-servers.json` 谁的 `profiles` 交叉列出的配置文件 `.cratis/ai.json` (一个只有通过另一个侧面才能到达的侧面 `composes` 做 不启动服务器；剧本保留其组合选择)(用于 例子 `codescene` 用于 `cratis/codescene`， `playwright` 用于 `cratis/playwright`）。 每个服务器都有自己的连接，所以一个启动失败不会影响其他服务器， 其工具的命名空间由服务器id (`playwright_browser_navigate`）. 这个 `command`， `args` 可选文字 `env` 都是逐字使用的，没有外壳。一个 一个通知跳过格式不正确的选定服务器；集 `mcpServers.<id>.enabled` 来 `false` 在 `.cratis/ai.json` 选择一个服务器退出。 `capabilities.json` 旁边的扩展声明此行为的Cratis CLI。

## 剧本MCP工具

打包的 `cratis-mcp` 扩展启动剧本MCP服务器 （`cratis screenplay mcp`)，当解析的配置文件包括 `cratis/screenplay`. 后端应用程序概要文件组成它，因此应用程序存储库得到 当安装Cratis CLI 3.46.1或更高版本时 剧本工具;服务器在第一次写入之前不会创建模型文件夹。 安装它们并不会将存储库选择为模型优先工作。

当剧本只通过这样的配置文件而没有模型根时 一个缺失的CLI，一个比3.46.1早的CLI（创建模型） 文件夹在服务器启动时)或服务器启动失败离开剧本 当Pi有UI时，工具不活动，只有一个信息通知，否则就静默。 选择任何不通过应用程序也到达剧本的配置文件 概要文件(包括 `cratis/screenplay`， `cratis/modeling/screenplay-stage`， `cratis/full/*` 或者 `cratis`)，或者配置 `mcpServers.screenplay.root` 在 `.cratis/ai.json`，将启动失败显示为错误。

## 路径引导和子代理

打包的 `cratis-path-guidance` 扩展将路径范围的规则附加到 工具结果第一次触及匹配文件，并成功后 `write` 或者 `edit` 增加了一条建议线，命名每个技能 `SKILL.md` `metadata.cratis-hint-paths` 前文（一串由空格分隔的globs） 匹配文件。(它位于 `metadata` 因为特工技能只允许一个固定的集合 这个键是克拉迪斯特有的，因为克劳德代码给出了一个简单的 `paths` 关键字自己的意思。)暗示了一项技能 大多数情况下，每个会话一次，而不是当它已经在上下文中：read （shell命令） 只有当 `cat`， `sed`， `head`， `tail`， `less`， `bat`， `rg` 或者 `grep` 打开 它的 `SKILL.md` 或者一个文件 `references/`)，由pi-子代理预加载，或 增长了 `/skill:name`． 一个pi-subagents标题，没有技能的文本（its） 加载程序无法读取符号链接 `.pi/skills`)不算作预加载。这个 考虑的技能是Pi加载的技能加上存储库选择的技能 （`.cratis/ai.json`)，所以在Pi技能列表中只包含个人技能的课程中， 或者没有（例如） `skills: false`)，仍然得到提示；未选择的技能是 没有提示，如果无法解决选择，则不添加任何提示。遵循规则 与系统提示相同的语言和文档选择。没有什么是 已阻止，系统提示符未受影响。系统提示符中只包含 通用规则，因此路径范围的规则不会交付两次。扩建工程 在没有UI的会话中。它在托管安装时停止运行 （`.cratis/ai.manifest.json`)已经提供了路径指导：通过它自己 `.pi/extensions/cratis-path-guidance`，或透过任何 `.pi/extensions/cratis-rules` 这不是当前的通用版本，因为每一个早期版本 本身交付路径范围的规则。一个 `cratis-rules` 这是无法识别的 作为一个交付它们的人。在这种较旧的托管安装中，子代理 只加载下面允许列出的扩展，直到 `cratis ai update` 安装托管 `cratis-path-guidance`.

通用规则为每个会话添加约26k个令牌。一个pi-subagents代理 （`@tintinweb/pi-subagents`)用… `extensions:` Allowlist只加载 扩展它的名字，所以默认情况下它不会得到这个包。说出这两个 便宜的扩展给它路径引导和写和存储保护没有 普遍的规则：

```yaml
extensions: cratis-path-guidance, cratis-hooks
```

这个 `subagent` 工具的这个包启动一个完整的 `pi` 处理和加载 扩展。

## 常见问题

### @cratis/pi 是什么？

Pi的配置感知Cratis AI集成

### 如何安装 @cratis/pi？

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

### @cratis/pi 支持 TypeScript 吗？

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

### @cratis/pi 支持 ESM 还是 CommonJS？

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

### @cratis/pi 可以商用吗？

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

### @cratis/pi 还在维护吗？

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