# @d3ara1n/pi-context-include 中文文档

规范地址：https://npmcn.com/package/%40d3ara1n/pi-context-include/

版本：3\.0\.0
npm 元数据更新时间：2026-09-20T02:25:20.207Z
中文译文更新时间：2026-11-11T08:11:46.835Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：40.8 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@earendil-works/pi-coding-agent \>=0\.86\.0
- 首次发布：2026-06-03T02:34:02.383Z
- 最新版本发布：2026-09-20T02:25:19.881Z
- 近 30 天下载量：8046（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

@ Path syntax for AGENTS. md – 通过引用递归分辨率包含文件

## 安装

```sh
npm install @d3ara1n/pi-context-include
```

也可以使用：`pnpm add @d3ara1n/pi-context-include`、`yarn add @d3ara1n/pi-context-include`、`bun add @d3ara1n/pi-context-include`

## README

# @d3ara1n/pi-context-包括:

[![npm version](https://img.shields.io/npm/v/@d3ara1n/pi-context-include)](https://www.npmjs.com/package/@d3ara1n/pi-context-include) [![npm downloads](https://img.shields.io/npm/dm/@d3ara1n/pi-context-include)](https://www.npmjs.com/package/@d3ara1n/pi-context-include) [![license](https://img.shields.io/npm/l/@d3ara1n/pi-context-include)](https://www.npmjs.com/package/@d3ara1n/pi-context-include)

`@path` aGENTS.md 的语法——包括参考文件.

要求pi 0.86.0或更新.

## 特征

-   **仅启动行**数字 : `@path` 坐在一行的开头,可选在 Markdown 列表标记之后(`-`, (中文(简体) ), `*`, (中文(简体) ), `+`,或 `1.`——防止电子邮件/代码出现虚假阳性
-   **安全栅栏**数字 : `@path` 三相后置区块内的行被忽略
-   **相对路径**数字 : `@CODEGRAPH.md`, (中文(简体) ), `@./docs/rules.md`, (中文(简体) ), `@../shared/AGENTS.md`
-   **绝对路径**数字 : `@/absolute/path/to/file.md`
-   **主目录**数字 : `@~/.pi/agent/includes/shared-rules.md`
-   **递归包括**: 包含的文件本身可以包含 `@` 参考文献
-   **循环检测**: 防止无限包括环
-   **大小警卫**: 500KB 总限值, 深为 (可配置) 10 级
-   **道路安全围栏**: 包含限制在允许的根; 默认屏蔽范围外路径

## 安装

```bash
pi install npm:@d3ara1n/pi-context-include
```

或加进 `~/.pi/agent/settings.json`数字 :

```json
{
  "extensions": [
    "/absolute/path/to/pi-extensions/packages/pi-context-include"
  ]
}
```

## 依赖关系

无.

## 使用量

在任何AGENTS.md文件中:

```markdown
# Project Rules

@./docs/api-conventions.md
@~/.pi/agent/includes/team-conventions.md
```

每次回合,扩展读取被引用的文件并更新自己的系统即时部分. 皮可以保持无变化的快分跨转弯.

**重要内容:** `@path` 必须是行的开头, 可选在 Markdown 列表标记之后(`-`编号 :`*`编号 :`+`编号 :`1.`) (中文(简体) ). 它不会被确认为中刑或内部代码块.

## 支持的文件类型

`.md` 只有这个 结构化格式`.json`编号 :`.yaml`编号 :`.toml`它被故意排除——它们通常持有配置或证书,而不是指示,而且最好按要求阅读.

## 配置

可选的 从 `~/.pi/agent/settings.json` (全球)或 `{project}/.pi/settings.json` (项目). 目前的项目 `contextInclude` 块取代全局块;省略字段后使用默认值. `maxDepth` 财务报告和审定财务报表 `maxBytes` 必须是有限、非负数; 无效值使用 默认值. `maxBytes` 以 UTF-8 字节计量。 可选 `allowedRoots` 编号 : `deniedRoots` 配置 [道路安全围栏](https://npmcn.com/package/%40d3ara1n/pi-context-include/#readme-path-safety-fence)。 。 。 .

```json
{
  "contextInclude": {
    "maxDepth": 15,
    "maxBytes": 1000000
  }
}
```

设置文件必须是有效的 JSON( 无注释) 。 设置已装入 开始-运行 `/reload` 或编辑后重新启动 pi .

### 道路安全围栏

包含的文件在系统中显示为 `<project_instructions>` 条目 内 `<context_include>` 节,所以意外 `@secrets.json` 或者说 `@../sibling/secret.md` 每一次都会泄露秘密 包括 因此,仅限于 **允许设置根**,带有 **拒绝设置** 那个 总是赢 :

```json
{
  "contextInclude": {
    "allowedRoots": ["./docs", "~/.pi/agent/includes"],
    "deniedRoots": ["./secrets", "node_modules"]
  }
}
```

-   `allowedRoots` ——可以包括的根. 相对条目解析 反对: **项目根**. (此表与 `@`\- 参考 决议:a `@path` 在 AGENTS.md 中,相对于 _那个 文件_和往常一样). 明确 `allowedRoots` **完全替换** 页:1 下方默认值; 空数组 `[]` 封锁一切.
-   `deniedRoots` - 可能永远不会包括的根源,总是首先加以评估 并优先于 `allowedRoots`。 。 。 .

**默认允许设置** (使用时 `allowedRoots` 被省略,所以已有 设置继续工作 :

-   每个上下文文件的目录树( 所以 in- repo) `@docs/rules.md` 工作内容 零配置),以及
-   `~/.pi/agent/includes/` ——跨repo规则共享之家.

其它任何东西`@/etc/...`, (中文(简体) ), `@../sibling/...`, (中文(简体) ), `@~/credentials.json`)为 默认被屏蔽并报告为 `/context-include:status` 作为"外面" 允许的根".

栅栏警卫防止事故和错位,而不是对手 任何能够编辑的人 `settings.json` 控制政策.

## 命令

`/context-include:status` - 显示有效的允许/拒绝根,已解决 包含和被跳过的文件(缺失、空出、超大小/深度) 限制,在允许的根外,被拒绝的Roots、重复,或 无法读取). 运行此选项以判断为何未包含引用文件 .

## 常见问题

### @d3ara1n/pi-context-include 是什么？

@ Path syntax for AGENTS\. md – 通过引用递归分辨率包含文件

### 如何安装 @d3ara1n/pi-context-include？

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

### @d3ara1n/pi-context-include 支持 TypeScript 吗？

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

### @d3ara1n/pi-context-include 支持 ESM 还是 CommonJS？

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

### @d3ara1n/pi-context-include 可以商用吗？

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

### @d3ara1n/pi-context-include 的下载量有多少？

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

### @d3ara1n/pi-context-include 还在维护吗？

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