# @cortexkit/aft-pi 中文文档

规范地址：https://npmcn.com/package/%40cortexkit/aft-pi/

版本：0\.63\.5
npm 元数据更新时间：2026-11-01T11:55:09.584Z
中文译文更新时间：2026-11-10T21:37:10.908Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.8 MB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：typebox \*，@earendil-works/pi-ai \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-04-20T11:54:05.931Z
- 最新版本发布：2026-11-01T11:55:09.287Z
- 近 30 天下载量：3590（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：125（近 12 个月 125 个）

## 中文简介

代理文件工具( AFT) 的 Pi 编码代理扩展名—— 树保姆和 LSP 驱动代码分析

## 安装

```sh
npm install @cortexkit/aft-pi
```

也可以使用：`pnpm add @cortexkit/aft-pi`、`yarn add @cortexkit/aft-pi`、`bun add @cortexkit/aft-pi`

## README

# @ cortexkit/ aft- pi

**AFT( 代理文件工具) 扩展名 [Pi 编码代理](https://github.com/badlogic/pi-mono) 财务报告和审定财务报表 [OMP (Oh- my- pi) (英语)](https://omp.sh/)**

AFT是AI编码代理的高性能文件管理工具包. 它取代了皮的内置 `read`, (中文(简体) ), `write`, (中文(简体) ), `edit`,以及 `grep` 带有索引的 Rust 后端的工具,这些后端添加了三克搜索、语义搜索、模糊编辑、自动格式、LSP诊断、书法导航,以及更多——都以一个温暖的长期运行为后盾 `aft` 进程.

## 安装

```bash
pi install npm:@cortexkit/aft-pi
```

就是这样。 扩展自动下载您的平台的右 AFT 二进制( 以 `~/.cache/aft/bin/v<version>/aft`) (中文(简体) ).

更喜欢给一个特定的版本贴上标签?

```bash
pi install npm:@cortexkit/aft-pi@0.13.1
```

## 你得到的东西

### 自动内置覆盖

皮的默认值 `read`, (中文(简体) ), `write`, (中文(简体) ), `edit`, (中文(简体) ), `grep`,以及 `bash` 改为AFT支持的版本。 列出名称 `disabled_tools` (例如 `["grep"]`),为那个槽保留了皮的原生工具. AFT背景组合 `bash_status`, (中文(简体) ), `bash_watch`, (中文(简体) ), `bash_write`,以及 `bash_kill` 独立注册 `bash`。 。 。 .

| 工具 | 皮内置 | AFT 替换 |
| --- | --- | --- |
| `read` | 节点 `fs.readFile` | 有行号输出、目录列表、二进制/图像检测的粗读器 |
| `write` | 节点 `fs.writeFile` | 原子书写,每个文件备份,自动格式(生物计量/氧化fmt/prettier/ruff/rustfmt),LSP诊断 |
| `edit` | 纯子字符串替换 | 渐进模糊匹配( 手持白空/ Unicode 漂移), 备份, 宽宽的编辑 |
| `grep` | 撕裂外壳 | 三进制索引搜索项目中, riggrep 在项目根外折返 |

四人都保留了与Pi内置相同的代理造型参数,因此你的提示,技能和肌肉记忆不会改变.

在Oh My Pi (OMP) 上,这五人在其内部URL路由器和内置工具时将内部资源下放给OMP的本地工具 `ctx.invokeTool` 备有。 读取和 grep 包括 MCP 资源 URI; 使用 OMP 写入策略编写和编辑代表方案( 包括无内容) `proc://<id>/kill`) OMP的只读 `issue://` 财务报告和审定财务报表 `pr://` 路由控件已读取, AFT 则保留其选择的 GitHub 注释写/编辑行为 。 Bash 代表内部- URL 工作目录和命令中注册的 URL 单词, 包括引用的 URL 和 `skill://`; OMP拥有由此而来的背景工作,并暴露其系统即时所装入的技能. 普通文件系统目标通过AFT继续. 上流派的策略和行为没有改变.

文件系统调用 OMP 使用 AFT 的参数表; 不支持的本地参数会产生命名字段及其 AFT 选项的错误. 扩展验证不执行二进制解析,下载,存储迁移,或传输启动:那些等待会话热身或文件系统工具请求需要AFT的人.

### AFT 专用工具

| 工具 | 它会做什么 |
| --- | --- |
| `aft_outline` | 文件或目录的结构大纲; 与 `github.read`,索引 GitHub 问题与公关讨论 |
| `aft_zoom` | 带有书法说明的符号级检查 `github.read`,钻入 GitHub 讨论正文 |
| `aft_search` | 语义代码搜索(嵌入,本地 ONNX 或 OpenAI 兼容) |
| `aft_callgraph` | 书法导航:来电者,呼叫 树木,撞击,追踪 到,追踪 数据 |
| `aft_conflicts` | 对所有冲突文件进行一次性合并-冲突检查 |
| `aft_import` | 语言意识导入 添加/去除/ 组织 (TS, JS, Python, Rust, Go) |
| `aft_safety` | 每个文件撤销,命名检查站,恢复 |
| `ast_grep_search` | 整个文件系统中的 AST 认知模式搜索 |
| `ast_grep_replace` | AST 认知模式重写 |
| `lsp_diagnostics` | 按需进行LSP诊断(编辑/写入已自动内置诊断) |
| `aft_delete` | 删除带有备份的文件( 表面 : `all`(中文(简体) ) |
| `aft_move` | 移动/重命名文件( 表面 : `all`(中文(简体) ) |

### 斜线命令

-   `/aft-status` ——显示AFT版本,搜索/语义索引状态,LSP服务器,存储路径

## 配置

AFT从两个级别读取配置,项目覆盖用户:

-   **用户 :** `~/.config/cortexkit/aft.jsonc`
-   **项目:** `<project>/.cortexkit/aft.jsonc`

所有密钥都是可选的 。 示例

```jsonc
{
  // Auto-format on write/edit using project formatter config.
  "format_on_edit": true,

  // "syntax" (tree-sitter parse) | "full" (LSP typecheck)
  "validate_on_edit": "syntax",

  // When true, write-capable commands reject paths outside project_root.
  // Defaults to false to match Pi's built-in behavior.
  "restrict_to_project_root": false,

  // Background indexes, all on by default. The local semantic backend may
  // download an ONNX runtime and model and use CPU.
  "indexes": { "trigram": true, "semantic": true, "callgraph": true },

  // Tools that are not registered. Absent => ["aft_move", "aft_delete"];
  // an explicit list replaces that default ([] enables every tool).
  "disabled_tools": ["aft_move"],

  // Pi / OMP harness options:
  "pi": {
    // "top_level" (default) | "host_default"
    // On OMP, "top_level" registers tools with loadMode: "essential" so they appear
    // directly in the model tools array. "host_default" mounts tools under xd://.
    "tool_presentation": "top_level",
    // Plain Pi: ask before an outside-project access (default true; only user config can turn it off; print/JSON/RPC sessions never ask; on OMP, OMP's tools.approvalMode decides and outside-path calls report the "exec" tier).
    "external_access_ask": true
  },

  "formatter": {
    "typescript": "biome",
    "python": "ruff",
    "rust": "rustfmt"
  },
  "checker": {
    "typescript": "biome"
  },

  // Missing formatter/checker/LSP warnings after configure: "toast" (default), "log", or "chat".
  "configure_warnings_delivery": "toast",

  // Semantic backend for the semantic index.
  // "fastembed" (default, local ONNX) | "openai_compatible" | "ollama"
  "semantic": {
    "backend": "fastembed",
    "model": "all-MiniLM-L6-v2",
    "timeout_ms": 25000,
    "max_batch_size": 64
  }
}
```

敏感的语义后端字段( S)`backend`, (中文(简体) ), `base_url`, (中文(简体) ), `api_key_env`仅读取自 **用户级别** 相会. 试图设置它们的项目配置会被忽略,同时发出警告,防止通过恶意重置进行认证-渗透.

### 注册工具

每个 AFT 工具注册, 除非在 `disabled_tools`数字 : `read`, (中文(简体) ), `write`, (中文(简体) ), `edit`, (中文(简体) ), `grep`, (中文(简体) ), `bash` 及其伴侣, `aft_outline`, (中文(简体) ), `aft_zoom`, (中文(简体) ), `aft_search`, (中文(简体) ), `aft_callgraph`, (中文(简体) ), `aft_inspect`, (中文(简体) ), `aft_import`, (中文(简体) ), `aft_safety`, (中文(简体) ), `aft_conflicts`, (中文(简体) ), `ast_grep_search`, (中文(简体) ), `ast_grep_replace`, (中文(简体) ), `aft_delete` 财务报告和审定财务报表 `aft_move` (最后两个默认已禁用) 页:1 阿皮没有AFT `apply_patch` 或者说 `glob` 工具。 索引状态和运行时间设置从未 删除注册. `tool_surface`, (中文(简体) ), `hoist_builtin_tools` 编辑 `search_index` 编号 : `semantic_search` 密钥在v0.58期间被翻译并被从v0.59拒绝.

## 建筑

-   **每届持续进行一个Rust进程.** Pi 每会话加载扩展一次; AFT 产出一个 `aft` 用于会话工作目录并保持其活性的二进制. 三相索引,语义索引,树保姆缓存,LSP服务器都保持温暖.
-   **NDJSON桥.** TypeScript扩展对 Rust 二进制的会谈,在stdin/stdout上使用版本的JSON-RPC风格的协议.
-   **会话隔离.** 皮丝 `session_shutdown` 事件触发了干净的桥梁关闭——取消历史,检查站,LSP州不会在会话中漏出.
-   **自动下載+版本检查.** 每个插件版本将一个相容的二进制版本标出并按顺序解决:已版本缓存 ~ 平台 npm 包 → `PATH` → `~/.cargo/bin/aft` ~ GitHub 发布下载. 错配的二进制热洗透明.

## 日志

插件日志转到 `<storage_root>/logs/aft-plugin.log` 带有 `[aft-pi]` 标签。 档案卷在32 MiB上卷成一 `.1` 备份; Rust 模块进程使用相邻 `aft-<pid>.log` 文档.

设定 `AFT_LOG_STDERR=1` 以路径日志取而代之(用于管道或子进程测试).

## 许可证

麻省理工学院

* * *

**主要项目:** [https://github.com/cortexkit/aft (英语)](https://github.com/cortexkit/aft) **问题/专题请求:** [https://github.com/cortexkit/aft/issues (中文(简体) )](https://github.com/cortexkit/aft/issues)

## 常见问题

### @cortexkit/aft-pi 是什么？

代理文件工具\( AFT\) 的 Pi 编码代理扩展名—— 树保姆和 LSP 驱动代码分析

### 如何安装 @cortexkit/aft-pi？

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

### @cortexkit/aft-pi 支持 TypeScript 吗？

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

### @cortexkit/aft-pi 支持 ESM 还是 CommonJS？

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

### @cortexkit/aft-pi 可以商用吗？

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

### @cortexkit/aft-pi 的下载量有多少？

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

### @cortexkit/aft-pi 还在维护吗？

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