使用说明

pi工具显示

OpenCode样式工具渲染 Pi编码代理.

pi-tool-display 默认情况下保持工具调用简洁，为文件编辑添加更丰富的差异渲染，并改进了一些核心聊天UI细节，如思维标签和本机用户提示框。

特性

紧凑的内置工具渲染 为了 read, grep, find, ls, bash, edit，以及 write
MCP感知渲染 具有隐藏、摘要和预览模式
选择加入自定义工具覆盖 对于嘈杂的扩展工具，默认为通用渲染，除非 kind: "mcp" 选中的
自适应编辑/写入差异 具有拆分或统一布局、语法突出显示、内联强调和窄窗格宽度夹紧
工作区范围的预计待定编辑/写入预览 那个节目 pending edit, pending overwrite，以及 pending create 部分工具调用仍在流式传输时的差异
渐进式折叠差异提示 在小终端宽度上自动缩短，而不是溢出
斜拉索锚差排水沟 保护 LINE#HASH 当这些行在差异中呈现时，从锚定的读取/编辑输出中提取标签
三个预设: opencode, balanced，以及 verbose
思维标签 在流式传输和最终消息呈现期间，进行上下文净化，以避免将演示标签泄漏回未来的模型转换中
可选的本地用户消息框 具有markdown感知渲染和更安全的ANSI/后台处理
按工具所有权切换 因此，此扩展可以与其他渲染器扩展共存
能力感知设置 使MCP和RTK特定的控制与当前环境保持一致
适用于渲染器消费者的适配器API 通过 pi-tool-display/tool-display-api-consumer 子路径导出

安装

本地扩展文件夹

将此文件夹放置在Pi的自动发现位置之一：

# Global default (when PI_CODING_AGENT_DIR is unset)
~/.pi/agent/extensions/pi-tool-display

# Project-specific
.pi/extensions/pi-tool-display

npm包

pi install npm:pi-tool-display

Git仓库

pi install git:github.com/MasuRii/pi-tool-display

用法

交互式设置

打开设置模式：

/tool-display

该模式揭示了大多数人经常改变的日常控制：

预设配置文件
读取输出模式
grep/find/ls输出模式
MCP输出模式（当MCP可用时）
预览行数
bash折叠行数
diff布局模式
本地用户消息框切换

高级选项仍保留在 config.json.

直接命令

/tool-display show                    # Show the effective config summary
/tool-display reset                   # Reset to the default opencode preset
/tool-display preset opencode         # Apply opencode preset
/tool-display preset balanced         # Apply balanced preset
/tool-display preset verbose          # Apply verbose preset

工具显示适配器API

其他扩展可以选择加入 pi-tool-display 通过导入消费者助手进行渲染，而不直接依赖于其加载顺序：

import { decorateToolForDisplay, decorateMcpToolForDisplay } from "pi-tool-display/tool-display-api-consumer";

decorateToolForDisplay(tool, adapter) 在以下情况下立即应用运行时装饰 pi-tool-display 或者将装饰排队直到API变得可用。使用适配器选项，例如 kind: "read" | "edit" | "mcp" | "generic" 选择渲染器族； decorateMcpToolForDisplay(tool) 是MCP风格工具的快捷方式。

预设

预设	读取输出	搜索输出	MCP输出	Bash输出	预览行	Bash行
`opencode`	隐藏	隐藏	隐藏	opencode	8	10
`balanced`	摘要	计数	摘要	摘要	8	10
`verbose`	预览	预览	预览	12	20

opencode （默认）：最小内联显示；工具结果仍处于崩溃状态
balanced：精简摘要，包括行数和匹配总数；bash仅显示行数
verbose：读取/搜索/MCP/bash输出的更大预览

Bash输出模式

模式	行为
`opencode`	经典压缩输出使用 `bashCollapsedLines` 带扩展提示的限制
`summary`	仅显示行数（例如，“返回3行”）——不显示输出
`preview`	使用以下命令显示实际输出行 `previewLines` 限制

配置

运行时配置存储在：

Default global path: ~/.pi/agent/extensions/pi-tool-display/config.json
Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-tool-display/config.json when PI_CODING_AGENT_DIR is set

入门模板包含在 config/config.example.json.

配置选项

选项	类型	默认值	描述
`debug`	布尔值	`false`	选择文件日志记录以进行扩展诊断；缺失的值被视为 `false`
`registerToolOverrides`	对象	全部 `true`	内置工具所有权标志
`customToolOverrides`	对象	`{}`	非内置扩展工具的显式选择加入渲染规则
`enableNativeUserMessageBox`	布尔值	`true`	启用带边框的用户提示渲染
`readOutputMode`	字符串	`"hidden"`	`hidden`, `summary`，或 `preview`
`searchOutputMode`	字符串	`"hidden"`	`hidden`, `count`，或 `preview`
`mcpOutputMode`	字符串	`"hidden"`	`hidden`, `summary`，或 `preview`
`previewLines`	编号	`8`	折叠预览模式下显示的线条
`expandedPreviewMaxLines`	编号	`4000`	完全展开时的最大预览行数
`bashOutputMode`	字符串	`"opencode"`	`opencode` （坍塌）， `summary` （行数），或 `preview` （显示线条）
`bashCollapsedLines`	编号	`10`	显示折叠bash输出的行（opencode模式）
`diffViewMode`	字符串	`"auto"`	`auto`, `split`，或 `unified`
`diffIndicatorMode`	字符串	`"bars"`	`bars` （垂直指示器）， `classic` （+/-标记），或 `none`
`diffSplitMinWidth`	编号	`120`	自动模式前的最小宽度更倾向于分割差异
`diffCollapsedLines`	编号	`24`	折叠前显示的不同线条
`diffWordWrap`	布尔值	`true`	需要时包裹长的差速器管路
`showTruncationHints`	布尔值	`false`	显示压缩输出的截断指示器
`showRtkCompactionHints`	布尔值	`false`	当RTK元数据存在时显示RTK压缩提示

工具所有权

使用 registerToolOverrides 要控制此扩展拥有哪些内置工具：

{
  "registerToolOverrides": {
    "read": true,
    "grep": true,
    "find": true,
    "ls": true,
    "bash": true,
    "edit": true,
    "write": true
  }
}

将任何条目设置为 false 如果另一个扩展应该处理该工具。

工具所有权的变更在以下时间生效 /reload.

自定义工具覆盖

使用 customToolOverrides 当另一个扩展注册了一个嘈杂的顶级工具，而你想要 pi-tool-display 呈现该工具的调用/结果输出。自定义覆盖仅显式选择加入：未列出或禁用的工具保留其原始渲染器。

{
  "customToolOverrides": {
    "ide_find_symbol": {
      "enabled": true,
      "kind": "generic",
      "outputMode": "summary"
    },
    "custom_mcp_gateway": {
      "enabled": true,
      "kind": "mcp",
      "outputMode": "preview"
    }
  }
}

每个条目支持：

字段	类型	默认值	描述
`enabled`	布尔值	`true`	是否 `pi-tool-display` 应该装饰这个自定义工具
`kind`	字符串	`"generic"`	`generic` 用于简单紧凑的输出，或 `mcp` 用于MCP风格的调用标签和结果处理
`outputMode`	字符串	`"summary"`	`hidden`, `summary`，或 `preview` 对于此自定义工具的结果输出

布尔简写也被接受：

{
  "customToolOverrides": {
    "ide_find_symbol": true,
    "noisy_tool_to_leave_alone": false
  }
}

笔记：

内置工具名称(read, grep, find, ls, bash, edit, write)这里忽略了；使用 registerToolOverrides 对于那些。
generic 调用呈现显示工具名称和参数计数，然后根据以下内容压缩结果 outputMode.
mcp 调用呈现理解MCP代理样式参数，例如 tool, server, search, describe，以及 connect.
已注册工具的更改将在以下时间生效 /reload稍后注册的工具可以在注册时进行装饰。

配置示例

{
  "debug": false,
  "registerToolOverrides": {
    "read": true,
    "grep": true,
    "find": true,
    "ls": true,
    "bash": true,
    "edit": true,
    "write": true
  },
  "customToolOverrides": {
    "ide_find_symbol": {
      "enabled": true,
      "kind": "generic",
      "outputMode": "summary"
    },
    "custom_mcp_gateway": {
      "enabled": true,
      "kind": "mcp",
      "outputMode": "preview"
    }
  },
  "enableNativeUserMessageBox": true,
  "readOutputMode": "summary",
  "searchOutputMode": "count",
  "mcpOutputMode": "summary",
  "previewLines": 12,
  "expandedPreviewMaxLines": 4000,
  "bashOutputMode": "opencode",
  "bashCollapsedLines": 15,
  "diffViewMode": "auto",
  "diffIndicatorMode": "bars",
  "diffSplitMinWidth": 120,
  "diffCollapsedLines": 24,
  "diffWordWrap": true,
  "showTruncationHints": false,
  "showRtkCompactionHints": false
}

调试记录

默认情况下禁用调试日志记录。集 debug 到 true 在扩展根中 config.json 仅在收集诊断信息时；缺失或无-true 值被视为 false启用后，诊断将附加到 debug/debug.log 在创建的运行时下 debug/ 目录，并且没有调试输出写入终端。

渲染注释

编辑和编写差异

edit 和 write 结果使用相同的diff渲染器。在 auto 扩展程序根据可用宽度选择拆分或统一布局。在窄窗格上，它夹住渲染的线条并缩短折叠的提示文本，这样差异就保持可读性，而不是溢出终端宽度。

虽然工具参数仍在流动，但部分 edit 和 write 呼叫可以显示预计的挂起预览。确定性编辑呈现为 pending edit 与当前文件内容的差异，写入呈现为 pending overwrite 或 pending create，未解决的投影显示了一个清晰的预览通知，而不是猜测。预览文件读取的范围仅限于活动工作区，因此挂起的预览会避免读取当前项目之外的路径。

当diff输入包括Pi锚定读取线时，例如 12#AB:content，渲染器将锚点视为行元数据，并显示 LINE#HASH 同时保持内容对齐，以实现拆分、统一和紧凑的差异布局。

撰写总结

当内容可用时， write 调用摘要内嵌了行数和字节大小信息，因此您可以在展开结果之前快速查看待处理写入的大小。

思维标签

在流媒体播放和最终消息上标记思维块。在下一个模型转换之前，扩展程序会将这些演示标签从存储的助手上下文中清除，这样它们就不会累积或污染未来的提示。

本地用户消息框

启用后，用户提示将使用Pi的本机用户消息组件在带边框的框内渲染。渲染器更安全地保留了markdown内容，并规范了ANSI/背景处理，以避免奇怪的嵌套背景伪影。

能力检测

该扩展检查当前的Pi环境并自动调整行为：

启动时MCP工具不可用：MCP设置可以从模式中隐藏，但配置的MCP输出模式会被保留，因为MCP工具稍后可能会注册
RTK优化器不可用：RTK提示设置被隐藏，RTK压缩提示被禁用

这使UI与当前环境保持一致，同时仍然允许动态注册的MCP工具在出现时进行样式设置。

故障排除

重新装载安全

/reload 完全支持。在重新加载时，扩展通过其内置的处置注册表清理所有工具覆盖、原型补丁、计时器和事件处理程序，然后在下一个会话生命周期事件上重新注册所有内容。不需要手动清理。

工具所有权冲突

如果另一个扩展已经在渲染其中一个内置工具：

集 registerToolOverrides.<tool> 到 false
跑 /reload
使用 /tool-display show 确认有效所有权状态

内置工具替代（包括 bash)在延迟所有权发现中注册——扩展通过以下方式发现它拥有哪些工具 pi.getAllTools() 在...期间 before_agent_start 在重写之前，防止与也注册重写的其他扩展发生冲突。

配置未加载

如果您的设置未被应用：

检查全局Pi工具显示配置是否存在（默认值： ~/.pi/agent/extensions/pi-tool-display/config.json，尊重 PI_CODING_AGENT_DIR)
确保JSON有效
跑 /tool-display show 检查有效的配置摘要

MCP或自定义工具渲染未出现

MCP工具通过以下方式装饰 pi.registerTool 拦截，因此无论生命周期事件顺序如何，它们在注册后都会被捕获。如果MCP工具仍然显示为未样式，请检查工具的名称或参数模式是否与支持的MCP检测启发式方法之一相匹配（名称包含 mcp, server:, ctx_，或参数模式 mcpServer/serverUrl/server_name).

对于非MCP扩展工具或与启发式方法不匹配的MCP类工具，请在下面添加确切的工具名称 customToolOverrides 然后跑 /reload.使用 kind: "generic" 对于普通工具和 kind: "mcp" 用于MCP代理样式参数。

MCP或RTK设置缺失

这些控件仅在当前Pi环境中具有相应功能时才会出现。

项目结构

pi-tool-display/
├── index.ts                         # Extension entrypoint for Pi auto-discovery
├── src/
│   ├── index.ts                     # Bootstrap and extension registration
│   ├── capabilities.ts              # MCP/RTK capability detection
│   ├── config-modal.ts              # /tool-display settings UI and command handling
│   ├── config-store.ts              # Config load/save and normalization
│   ├── disposable.ts                # Reload-safe cleanup registry for tool overrides, patches, and timers
│   ├── diff-renderer.ts             # Edit/write diff rendering engine
│   ├── line-width-safety.ts         # Width clamping helpers for narrow panes
│   ├── pending-diff-preview.ts      # Partial edit/write preview projection helpers
│   ├── presets.ts                   # Preset definitions and matching
│   ├── render-utils.ts              # Shared rendering helpers
│   ├── thinking-label.ts            # Thinking label formatting and context sanitization
│   ├── tool-overrides.ts            # Built-in, MCP, and opt-in custom renderer overrides
│   ├── types.ts                     # Shared config and type definitions
│   ├── user-message-box-markdown.ts # Markdown extraction for user message rendering
│   ├── user-message-box-native.ts   # Native user message box registration
│   ├── user-message-box-patch.ts    # Safe native render patching helpers
│   ├── user-message-box-renderer.ts # User message border renderer
│   ├── user-message-box-utils.ts    # ANSI/background normalization helpers
│   ├── write-display-utils.ts       # Write summary helpers
│   └── zellij-modal.ts              # Modal UI primitives
├── config/
│   └── config.example.json          # Starter config template
└── tests/
    ├── ansi-utils.test.ts           # ANSI utility tests including foreground RGB preservation
    ├── bash-display.test.ts         # Bash display and spinner tests
    ├── capabilities-edge.test.ts    # Capability detection edge cases
    ├── config-modal.test.ts         # Config modal tests
    ├── custom-tool-overrides.test.ts # Opt-in custom tool override tests
    ├── debug-logger-edge.test.ts    # Debug logger edge cases
    ├── diff-renderer-ansi.test.ts   # ANSI/background handling tests for diff rendering
    ├── diff-renderer-edge.test.ts   # Diff renderer edge case tests
    ├── diff-renderer-width.test.ts  # Width and background coverage tests for diff rendering
    ├── index-integration.test.ts    # Integration tests for extension lifecycle
    ├── presets-edge.test.ts         # Preset edge case tests
    ├── reload-behavior.test.ts      # Reload-safe cleanup and re-registration tests
    ├── tool-overrides-config.test.ts    # Tool override config tests
    ├── tool-overrides-registration.test.ts # Tool override registration tests
    └── tool-ui-utils.test.ts        # Utility tests for user message and diff helpers

发展

# Type check
npm run build

# Run tests
npm run test

# Full verification
npm run check

许可证

麻省理工学院

工具渲染扩展

使用说明

pi工具显示

特性

安装

本地扩展文件夹

npm包

Git仓库

用法

交互式设置

直接命令

工具显示适配器API

预设

Bash输出模式

配置

配置选项

工具所有权

自定义工具覆盖

配置示例

调试记录

渲染注释

编辑和编写差异

撰写总结

思维标签

本地用户消息框

能力检测

故障排除

重新装载安全

工具所有权冲突

配置未加载

MCP或自定义工具渲染未出现

MCP或RTK设置缺失

项目结构

发展

相关Pi扩展

许可证

使用说明

pi工具显示

特性

安装

本地扩展文件夹

npm包

Git仓库

用法

交互式设置

直接命令

工具显示适配器API

预设

Bash输出模式

配置

配置选项

工具所有权

自定义工具覆盖

配置示例

调试记录

渲染注释

编辑和编写差异

撰写总结

思维标签

本地用户消息框

能力检测

故障排除

重新装载安全

工具所有权冲突

配置未加载

MCP或自定义工具渲染未出现

MCP或RTK设置缺失

项目结构

发展

相关Pi扩展

许可证

相关 MCP

差异比较服务器

网页内容抓取服务器

知识图谱记忆服务器

顺序思维服务器

Figma MCP服务器

GitHub API服务器