# @amaster\.ai/pi-attachments 中文文档

规范地址：https://npmcn.com/package/%40amaster.ai/pi-attachments/

版本：0\.1\.37
npm 元数据更新时间：2026-11-09T02:50:52.801Z
中文译文更新时间：2026-11-09T07:29:40.893Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.9 MB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@earendil-works/pi-coding-agent \>=0\.74\.0
- 首次发布：2026-05-16T07:35:37.826Z
- 最新版本发布：2026-11-09T02:50:52.593Z
- 近 30 天下载量：4110（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：132（近 12 个月 132 个）

## 中文简介

附加处理的 Pi 扩展名 — 分类、 剖析并让文件附件成为 LLM 可见的快捷上下文

## 安装

```sh
npm install @amaster.ai/pi-attachments
```

也可以使用：`pnpm add @amaster.ai/pi-attachments`、`yarn add @amaster.ai/pi-attachments`、`bun add @amaster.ai/pi-attachments`

## README

# @amaster.ai/pi-attachments (英语)

![pi-attachments preview](https://raw.githubusercontent.com/TGYD-helige/pi/master/packages/pi-attachments/preview.png)

截取用户输入的 Pi 扩展 `@`\- 参考本地资源,并在模型看到前将其内容注入提示.

钩上 `input` 事件 `@earendil-works/pi-coding-agent`当用户信息中出现识别的提及时,原提及被剥去并被结构化上下文所取代(技能块、附件列表或 `<system-reminder>`) (中文(简体) ). 图像附件作为多模式传递 `ImageContent`。 。 。 .

## 公认提及

| 语法 | 决定 |
| --- | --- |
| `@path/to/file.ts` | 文件内容(文本/doc)或 Base64 图像 |
| `@"/path with spaces/file.pdf"` | 和上面一样,支持路径中的空白 |
| `@path/to/file.ts#L10-20` | 参考文献中保留了行距语法(下行范围) |
| `@path/to/dir` | 目录列表( 文件 + 子目录, 忽略) `.git`编号 :`node_modules`/建立产出) |
| `@skill:<name>` | 装入 `SKILL.md` 注册技能 |

`@http(s)://...` 实值 **没有** 作为文件参考。 未知的命名空间( 例如 ). `@app:erp-prod`——既不能作为技能解决,也不能作为文件解决.

## 技能分辨率

`@skill:<name>` 按此顺序搜索, 首先击出胜负 :

1.  `<cwd>/.pi/skills/<name>/SKILL.md` 项目一级的技能
2.  `<agentDir>/skills/<name>/SKILL.md` ——用户级技能(通过 `@amaster.ai/pi-shared`是因为 `resolveAgentDir()`,以 `PI_AGENT_HOME`(中文(简体) )

顺序匹配 `loadSkillsFromAllLocations` 在 pi-coding- agent SDK 中,所以一个工程技能可以覆盖一个用户安装的. 前题被剥去,尸体被包裹 `<skill name="..." location="...">…</skill>` 并准备用于用户消息.

## 输出组件

当至少提到一个解决时,输入会按此顺序重写为三个可选部分:

````
<skill name="..." location="...">…</skill>   ← skill blocks (if any)

<original user text with mentions stripped>

<system-reminder>
## file.ts: /abs/path/file.ts
```text
…contents…
````

\`\`\`

没有可解析引用的纯文本输入不受影响( 处理器返回) `undefined`) (中文(简体) ).

## 配置

| 新闻 var | 默认 | 含义 |
| --- | --- | --- |
| `PI_ATTACHMENT_MAX_TEXT_CHARS` | `128000` | 共享文件/指令区块每个输入的文本预算 |
| `PI_AGENT_HOME` | (从平分) | 覆盖用户级技能搜索根 |

## 限制

文本文件被读取为被绑定的UTF-8前缀,而不是装入完整的文件. 文件和目录块共享 `PI_ATTACHMENT_MAX_TEXT_CHARS` (默认值128 000);预算用完后省略后的内容,保留其参考文献。 无效或非正环境值使用默认值. `renderAttachmentContext(attachments, options)` 呼叫者通过 `options.maxTextChars`; 零预算只发出引用和省略说明.

图像附件共享每个输入的20 MiB生字节预算,包括拖放上传和文件引用. 愿景预算外的图像保留有可见的调整大小/裁剪提示的源路径;拖曳上传在单独的128 MiB存储预算内每输入一次被递增地坚持. 超过存储预算的上传需要文件引用或更小的图像. 接受视觉图像和Markdown引用保留匹配顺序.

-   **目录列表**: 上限为每个目录200个条目;其余部分概述为 `[Listing truncated: showing 200 of N entries]`。 。 。 .
-   **被忽略的目录条目**数字 : `.git`, (中文(简体) ), `node_modules`, (中文(简体) ), `.DS_Store`, (中文(简体) ), `.next`, (中文(简体) ), `.turbo`, (中文(简体) ), `dist`, (中文(简体) ), `build`, (中文(简体) ), `.cache`。 。 。 .
-   **提及命令**: 技能在文件前匹配, 所以解析 `mentions[]` 组合,而不是保留文字顺序。 下游消费者不得依赖文字顺序.

### 诊断失败

缺少或无法读取的引用文件作为每个附件的明显故障通知列入。 其他可读附件仍然可用,并告知该模型哪些来源没有检查.

## 常见问题

### @amaster\.ai/pi-attachments 是什么？

附加处理的 Pi 扩展名 — 分类、 剖析并让文件附件成为 LLM 可见的快捷上下文

### 如何安装 @amaster\.ai/pi-attachments？

在项目目录运行 npm install @amaster\.ai/pi-attachments，或使用 pnpm add / yarn add / bun add。

### @amaster\.ai/pi-attachments 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @amaster\.ai/pi-attachments 支持 ESM 还是 CommonJS？

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

### @amaster\.ai/pi-attachments 可以商用吗？

@amaster\.ai/pi-attachments 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @amaster\.ai/pi-attachments 的下载量有多少？

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

### @amaster\.ai/pi-attachments 还在维护吗？

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