pi-claude-style-tools-aft

English | 简体中文

为 Pi 提供 Claude Code 风格的工具渲染，并在原版基础上加入完整的 AFT 兼容支持。

[!IMPORTANT] 本仓库是 FammasMaz/pi-cc-tools 的 AFT 兼容增强分支。它保留原版的视觉体验，但重新设计了核心工具的接入方式：AFT 负责工具执行，本扩展只负责显示。

目录

• 为什么需要这个分支？
• 本分支的主要特点
• 安装
• 继承自原版的功能
• 配置
• 技术说明
• 致谢

为什么需要这个分支？

原版扩展通过重新注册 Pi 的核心工具来附加自定义渲染器。只使用 Pi 内置工具时，这种方式没有问题；但 AFT 也会用 Rust 后端替换 read、write、edit、grep 和 bash 等核心工具。两个扩展注册相同的工具名时，加载顺序会决定最终生效的实现，从而可能意外覆盖另一方的功能。

本分支将执行与显示彻底分离：

• AFT 负责执行：完整保留 Rust 后端、参数 Schema、权限检查、提示词元数据、索引、自动格式化、诊断和安全恢复能力。
• 本扩展负责显示：直接在 TUI 组件层注入 Claude 风格渲染，不再以同名工具覆盖 AFT。
• 加载顺序不再影响兼容性：无论 AFT 先加载还是本扩展先加载，AFT 的工具实现都不会丢失。

本分支与原版的区别

| 能力 | 原版 pi-claude-style-tools | 本分支 | |---|---|---| | Pi 内置工具的 Claude 风格显示 | 支持 | 支持 | | 核心工具接入方式 | 重新注册工具，并转发到 Pi 内置实现 | 只接管显示，保留当前实际后端 | | AFT 核心工具执行 | 可能因扩展同名冲突被替换 | 完整保留 | | AFT 专用布局 | 不支持 | 覆盖 AFT 0.46 的全部 22 个工具 | | 扩展加载顺序 | 可能影响最终生效的核心工具 | 两种顺序均兼容 | | 后续新增 AFT 工具 | 使用普通自定义工具显示 | 为 aft_*、ast_grep_* 和 Bash 控制工具提供结构化兜底 | | 原版主题、Diff、工具分组、Spinner、MCP 和 OpenAI 工具样式 | 支持 | 全部保留 |

本分支的主要特点

• 完整覆盖 AFT 工具：为 @cortexkit/aft-pi 0.46 暴露的全部 22 个工具提供专门的折叠和展开布局。
• 理解 AFT 参数格式：兼容 path、filePath、file_path，以及 oldString/newString、追加、批量编辑、行范围编辑、格式化结果和 LSP diagnostics。
• 针对结果类型设计布局：outline 和 callgraph 使用树状显示；语义搜索按文件分组；zoom 突出源码和符号；后台 Bash 显示任务状态；safety、conflicts 和文件操作提供清晰摘要；修改类工具显示 Diff。
• 默认保持紧凑：折叠状态只显示动作、目标、数量和状态；按 Ctrl+O 后展示完整源码、树、终端输出、诊断和 Diff。
• 兼容未来 AFT 工具：遇到未知的 AFT 系列工具时，会优先解析结构化 details 或 JSON 内容，避免直接显示原始对象。
• 不强制依赖 AFT：AFT 是可选组件；未安装 AFT 时，Pi 内置工具仍然使用同样的 Claude 风格显示。

支持的 AFT 工具

| 分类 | 工具 | |---|---| | 核心工具替换 | read、write、edit、grep、bash | | 后台终端 | bash_status、bash_watch、bash_write、bash_kill | | 阅读与搜索 | aft_outline、aft_zoom、aft_search、aft_inspect | | 代码关系 | aft_callgraph、aft_conflicts | | 代码修改 | aft_import、ast_grep_search、ast_grep_replace、aft_refactor | | 文件与恢复 | aft_delete、aft_move、aft_safety |

安装

通过 npm 将 AFT 和本分支作为两个独立的 Pi 扩展安装：

pi install npm:@cortexkit/aft-pi
pi install npm:pi-claude-style-tools-aft

如果希望直接跟随仓库最新源码，可将第二条命令替换为 pi install git:github.com/Aaalice233/pi-claude-style-tools-aft。

如果已经安装原版 npm 包，请先删除或禁用它，避免 Pi 同时加载两份显示扩展：

pi remove npm:pi-claude-style-tools

不需要调整扩展顺序，也不需要额外修改 AFT 配置。本分支已在 Pi 0.80.6 和 @cortexkit/aft-pi 0.46.0 环境中分别验证两种加载顺序。

继承自原版的功能

• 紧凑的内置工具显示：支持 read、bash、grep、find、ls、edit 和 write。
• Claude 风格的 OpenAI 工具显示：支持 apply_patch，以及 webfetch、web_search、fetch_content、任务工具和上下文工具等常见 Pi/OpenAI 风格工具。
• apply_patch Diff 预览：在工具调用阶段解析并显示文件补丁，与 edit/write 的体验一致。
• 自适应 edit/write Diff：支持并排或统一布局、语法高亮和行内单词级强调。
• Diff 统计栏：显示新增、删除、区块数量等信息。
• 渐进式折叠提示：在较窄终端中自动缩短 Diff 提示文本。
• Thinking 标签：在流式输出和最终消息中显示经过清理的思考状态。
• MCP 感知渲染：支持隐藏、摘要和预览模式。
• 可配置输出模式：可分别控制 read、search、bash 和 MCP 结果。
• 工具运行实时预览：工具执行中显示少量最新输出；Bash 默认展示尾部内容。
• Subagent 完成通知美化：使用统一的 Claude 风格工具行。
• RTK rewrite 集成：将重写提示合并到 Bash 工具行，并显示低调的 (RTK) 标记。
• 透明工具背景：支持 transparent 和 border 模式。
• 主题自适应颜色：边框、分支线、弱化文本、Spinner 和 Diff 背景会跟随 Pi 当前主题。
• 浅色 Ghostty 同步主题：浅色主题使用 github-light 语法高亮和浅色 Diff 背景。
• 透明 Diff 配色：edit/write Diff 使用通用红绿配色。
• 连续工具调用分组：将相邻或并发工具调用收拢到紧凑状态标题下。
• 额外详情开关：使用 Ctrl+Shift+O 提高展开预览上限。
• 全局工具边框：未知工具和自定义工具也能使用统一的上下边框。

配置

在项目的 .pi/settings.json 或用户目录的 ~/.pi/settings.json 中设置：

{
  "toolBackground": "border",
  "readOutputMode": "preview",
  "searchOutputMode": "preview",
  "mcpOutputMode": "preview",
  "previewLines": 8,
  "expandedPreviewMaxLines": 4000,
  "extraExpandedPreviewMaxLines": 12000,
  "extraToolOutputExpanded": false,
  "groupToolCalls": true,
  "bashOutputMode": "opencode",
  "bashCollapsedLines": 10,
  "liveToolPreview": true,
  "liveToolPreviewLines": 5,
  "diffCollapsedLines": 24,
  "themeAdaptive": true,
  "diffTheme": "github-dark"
}

主题集成

themeAdaptive 默认为 true。启用后，下列颜色会在每次渲染时从 Pi 当前主题派生，并在主题变化后重新计算：

| 元素 | 颜色来源 | |---|---| | 用户消息框、工具分隔线、代码围栏 | dim → muted → borderMuted → thinkingText | | 分支连接线（├─、└─、│） | 默认固定为 rgb(72)；使用 /cc-tools branch theme 可跟随 Pi 主题 | | 最终消息的 ✻ Turn took Ns | muted | | Thinking 块的灰色斜体文字 | muted | | Diff 新增/删除强调色 | toolDiffAdded / toolDiffRemoved | | Diff 背景色 | 基于 toolSuccessBg 混合生成 | | Spinner 动词文本（例如 Working…） | borderAccent，失败时回退到 accent | | Spinner 状态文本 | muted |

用户配置的 diffTheme 预设和 diffColors 始终优先于主题派生值。文件类型图标（例如 ts、py、rs）会保留对应语言的识别色。

将 themeAdaptive 设置为 false，可以始终使用固定的 Claude 风格配色。

在 /resume、/new 或 /fork 后，工具外观会重新绑定到 Pi 当前主题，不依赖 Ghostty 或其他主题扩展。如果使用 Ghostty 主题同步，建议在 settings.json 中将它放在本扩展之前。

使用 /cc-theme 动态切换

/cc-theme           # 显示当前设置和主题名称
/cc-theme status    # 显示当前设置和颜色预览（包含 Spinner）
/cc-theme on        # 跟随 Pi 主题
/cc-theme off       # 使用固定 Claude 配色
/cc-theme toggle    # 切换当前状态

设置会写入 ~/.pi/settings.json，并从下一次工具渲染开始生效，无需重启。

使用 /cc-spinner 调整 Spinner

Spinner 图形本身仍由 Pi loader 使用 accent 着色。动词文本（例如 Cooking…）默认使用 borderAccent，状态后缀（例如 (thinking · ↓ 10 tokens · 2s)）默认使用 muted。

/cc-spinner preview          # 预览常用主题颜色键
/cc-spinner verb <key>       # 修改动词颜色
/cc-spinner status <key>     # 修改状态后缀颜色
/cc-spinner reset            # 恢复 verb=borderAccent、status=muted

设置会作为 spinnerVerbColor / spinnerStatusColor 保存在 ~/.pi/settings.json 中，并在下一次 Spinner 刷新时应用。

工具背景模式

| 值 | 行为 | |---|---| | default | 使用 Pi 默认工具背景 | | transparent | 使用透明工具背景 | | border | 使用透明背景，并显示上下边框 |

通过 /cc-tools 动态控制工具界面：

/cc-tools status          # 显示样式、分组和额外详情状态
/cc-tools outlines        # 切换 outlines、transparent 或 default
/cc-tools group toggle    # 切换相邻/并发工具分组
/cc-tools group off       # 关闭分组，并拆分当前分组行
/cc-tools detail toggle   # 等同于 Ctrl+Shift+O

输出模式

| 设置 | 可选值 | 默认值 | |---|---|---| | readOutputMode | hidden、summary、preview | preview | | searchOutputMode | hidden、count、preview | preview | | mcpOutputMode | hidden、summary、preview | preview | | bashOutputMode | opencode、summary、preview | opencode |

显示设置

| 设置 | 默认值 | 说明 | |---|---|---| | previewLines | 8 | 折叠预览显示的行数 | | expandedPreviewMaxLines | 4000 | 使用 Ctrl+O 展开后的最大行数 | | extraExpandedPreviewMaxLines | 12000 | 使用 Ctrl+Shift+O 后的最大展开行数 | | extraToolOutputExpanded | false | 启动时是否默认启用额外详情模式 | | groupToolCalls | true | 是否将相邻/并发工具调用放入紧凑分组 | | bashCollapsedLines | 10 | Bash 折叠输出行数 | | liveToolPreview | true | 工具执行期间是否显示实时预览 | | liveToolPreviewLines | 5 | 折叠状态下实时预览的行数 | | diffCollapsedLines | 24 | Diff 超过多少行后折叠 |

技术说明

本扩展面向使用以下工具渲染器接口的较新 Pi 版本：

• renderCall(args, theme, context)
• renderResult(result, { expanded, isPartial }, theme, context)

Pi 目前没有公开的全局未知工具渲染钩子，因此本扩展会补丁 Container 渲染，使所有工具在 border 模式下都能显示上下边框。

AFT 兼容实现

显示层会识别 AFT 接管的核心工具，但不会包装或替换它们的定义。对于 AFT 专用工具，会根据工具名选择对应的专用渲染器；后续未知的 aft_*、ast_grep_* 和 AFT Bash 控制工具则进入结构化兜底渲染路径。

该设计严格限制在显示层：本扩展会读取工具参数和结果用于渲染，但不会修改 AFT 的 execute 函数、参数 Schema、权限检查、提示词指导或返回数据。

致谢

本项目继承并参考了以下优秀项目：

• @heyhuynhgiabuu/pi-pretty，作者 huynhgiabuu：提供带语法高亮的文件读取、彩色 Bash 输出和树状目录显示。
• @heyhuynhgiabuu/pi-diff，作者 huynhgiabuu：提供基于 Shiki 的终端 Diff 和单词级并排/统一 Diff 显示。
• pi-tool-display，作者 MasuRii：提供紧凑工具调用显示、Diff 可视化和输出截断设计。