玩了一天的pi，让我来分享一下我的配置包

pi 可太上头了
核心配置：

{
  "lastChangelogVersion": "0.78.1",
  "packages": [
    "npm:pi-mcp-adapter",
    "npm:@ff-labs/pi-fff",
    "npm:@juicesharp/rpiv-ask-user-question",
    "npm:@gotgenes/pi-permission-system",
    "npm:@juicesharp/rpiv-args",
    "npm:@narumitw/pi-goal",
    "npm:@hsingjui/pi-hooks",
    "npm:@vanillagreen/pi-skills-manager",
    "npm:pi-cache-optimizer",
    "npm:pi-tool-display",
    "npm:pi-hash-anchored-edit",
    "npm:@tifan/pi-inline-skills",
    "npm:pi-agentsmd",
    "npm:@agnishc/edb-context-viewer",
    "npm:@sting8k/pi-vcc",
    "npm:@tintinweb/pi-subagents",
    "npm:@tintinweb/pi-tasks",
    "npm:pi-system-prompt",
    "npm:pi-bg-run",
    "npm:pi-aliases"
  ],
  "defaultProvider": "openai-responses",
  "defaultModel": "gpt-5.5",
  "images": {
    "blockImages": true,
    "autoResize": true
  },
  "showHardwareCursor": false,
  "terminal": {
    "showTerminalProgress": true,
    "clearOnShrink": false
  },
  "steeringMode": "all",
  "transport": "auto",
  "hideThinkingBlock": false,
  "quietStartup": true,
  "treeFilterMode": "all",
  "doubleEscapeAction": "tree",
  "theme": "dark",
  "defaultThinkingLevel": "high",
  "autocompleteMaxVisible": 1000000,
  "followUpMode": "all",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 32768
  },
  "collapseChangelog": true,
  "retry": {
    "enabled": true,
    "maxRetries": 10,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 360000
    }
  },
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 16384,
    "xHigh": 32768
  },
  "branchSummary": {
    "skipPrompt": true
  }
}

如果这些配置你不知道什么意思，那很简单，把pi安装后，让他为你解释每一个值。

# Pi 已安装扩展包配置整理

## 1. `pi-mcp-adapter` 2.9.0

**证据**：`pi-mcp-adapter/config.ts`, `pi-mcp-adapter/types.ts`, `pi-mcp-adapter/index.ts`。

### 配置文件读取顺序/位置

`loadMcpConfig()` 会合并这些来源，后面的源覆盖前面的同名 server：

1. 共享全局：`~/.config/mcp/mcp.json`
2. Pi 全局：`~/.pi/agent/mcp.json`（受 `PI_CODING_AGENT_DIR` 影响）
3. 项目共享：`<cwd>/.mcp.json`
4. 项目 Pi：`<cwd>/.pi/mcp.json`

也可用 Pi flag 覆盖全局 Pi 配置路径：

```bash
pi --mcp-config /path/to/mcp.json

可导入外部 MCP 配置

根字段 imports 支持：

{
  "imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "vscode"]
}

对应候选路径包括：

• cursor: ~/.cursor/mcp.json
• claude-code: ~/.claude/mcp.json, ~/.claude.json, ~/.claude/claude_desktop_config.json
• claude-desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• codex: ~/.codex/config.json
• windsurf: ~/.windsurf/mcp.json
• vscode: <cwd>/.vscode/mcp.json

根配置结构

{
  "mcpServers": {
    "serverName": {
      "command": "npx",
      "args": ["-y", "some-mcp"],
      "env": {},
      "cwd": "/optional/cwd",
      "url": "https://example.com/mcp",
      "headers": {},
      "auth": "oauth",
      "bearerTokenEnv": "TOKEN_ENV",
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "exposeResources": true,
      "directTools": false,
      "excludeTools": [],
      "debug": false
    }
  },
  "imports": [],
  "settings": {}
}

mcpServers.* 配置项

字段 类型/可选值 默认/行为 建议 command string stdio MCP 命令 本地 MCP 用 command + args args string[] [] 固定版本优于裸 latest env object 传给子进程 API key 用环境变量，不写明文 cwd string 当前目录 需要项目上下文时设置 url string HTTP MCP 远程 MCP 用 headers object HTTP headers 避免写 secret，优先 bearerTokenEnv auth "oauth" / "bearer" / false URL 存在时可自动检测 OAuth OAuth 服务用默认/oauth；静态 token 用 bearer bearerToken string 静态 Bearer 不建议，除非临时测试 bearerTokenEnv string 从环境变量取 Bearer 推荐 oauth object / false SDK 动态注册 优先省略；需要固定 client 时再填 lifecycle "keep-alive" / "lazy" / "eager" 源码未在类型处写默认 多数用 lazy；高频服务用 keep-alive idleTimeout number 分钟；0 禁用 覆盖全局 settings.idleTimeout 默认 10 左右；耗资源服务不要 0 exposeResources boolean 是否暴露资源 需要 MCP resources 才开 directTools boolean / string[] 覆盖全局 direct tools 常用少量工具可用 string[] 精确暴露 excludeTools string[] 排除工具/资源 建议排除危险或噪声工具 debug boolean 显示 server stderr 排错时 true，日常 false

settings 配置项

字段 可选值 建议值 toolPrefix "server" / "none" / "short" server，避免工具重名 idleTimeout number 分钟，0 禁用 10；不要长期 keep-alive 太多 server directTools boolean 少量高频 MCP 可设 true，否则默认即可 disableProxyTool boolean 保持 false，除非只想 direct tools autoAuth boolean 可信 MCP 可 true；不确定用 false/默认 sampling boolean 默认关闭更安全；需要 MCP sampling 才开 samplingAutoApprove boolean 建议 false，避免无确认模型调用 elicitation boolean 需要 MCP 交互式 elicitation 才开 elicitationAutoOpenUrls boolean 建议 false authRequiredMessage string，支持 ${server} 可自定义为团队提示

推荐示例

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/rao/project"],
      "lifecycle": "lazy",
      "idleTimeout": 10,
      "debug": false
    }
  },
  "settings": {
    "toolPrefix": "server",
    "idleTimeout": 10,
    "directTools": false,
    "disableProxyTool": false,
    "sampling": false,
    "samplingAutoApprove": false,
    "elicitationAutoOpenUrls": false
  }
}

---

2. @ff-labs/pi-fff 0.9.1

证据：@ff-labs/pi-fff/src/index.ts, README。

配置入口

pi-blackhole

无 JSON 配置文件。配置来源优先级：Pi flag > 环境变量 > 默认值。

配置 来源 可选值/含义 默认 建议 mode --fff-mode / PI_FFF_MODE tools-and-ui / tools-only / override tools-and-ui 当前默认很好；若与其他编辑器 UI 冲突用 tools-only frecency DB --fff-frecency-db / FFF_FRECENCY_DB 自定义 frecency 数据库路径 fff-node 默认 通常不设 history DB --fff-history-db / FFF_HISTORY_DB 自定义 query history 数据库路径 fff-node 默认 通常不设 multi grep PI_FFF_MULTIGREP=1 启用实验性 multi_grep 关闭 不建议开启，源码注释称可能有害

推荐：保持默认；如你只想要 ffgrep/fffind 工具、不想替换 editor mention UI：

PI_FFF_MODE=tools-only pi

---

3. pi-tool-display 0.4.2

证据：pi-tool-display/src/config-store.ts, src/types.ts, config/config.example.json。

配置文件

~/.pi/agent/extensions/pi-tool-display/config.json

受 PI_CODING_AGENT_DIR 影响。

配置项

字段 可选值/范围 默认 建议 registerToolOverrides.read/grep/find/ls/bash/edit/write boolean 全 true 保持 true；若与其它工具展示扩展冲突，再关闭对应项 enableNativeUserMessageBox boolean true 保持 true readOutputMode hidden / summary / preview hidden hidden，避免重复占屏；想看 read 摘要可 summary searchOutputMode hidden / count / preview hidden hidden 或 count mcpOutputMode hidden / summary / preview hidden summary 更利于排查 MCP；安静模式用 hidden previewLines 1–80 8 8–12 expandedPreviewMaxLines 0–20000 4000 2000–4000 bashOutputMode opencode / summary / preview opencode 保持 opencode bashCollapsedLines 0–80 10 10–20 diffViewMode auto / split / unified auto 保持 auto diffIndicatorMode bars / classic / none bars 保持 bars diffSplitMinWidth 70–240 120 宽屏 120；窄屏 100 diffCollapsedLines 4–240 24 24–60 diffWordWrap boolean true 保持 true showTruncationHints boolean false 排查截断时 true showRtkCompactionHints boolean false 通常 false

推荐示例：

{
  "registerToolOverrides": {
    "read": true,
    "grep": true,
    "find": true,
    "ls": true,
    "bash": true,
    "edit": true,
    "write": true
  },
  "enableNativeUserMessageBox": true,
  "readOutputMode": "hidden",
  "searchOutputMode": "count",
  "mcpOutputMode": "summary",
  "previewLines": 10,
  "expandedPreviewMaxLines": 4000,
  "bashOutputMode": "opencode",
  "bashCollapsedLines": 12,
  "diffViewMode": "auto",
  "diffIndicatorMode": "bars",
  "diffSplitMinWidth": 120,
  "diffCollapsedLines": 32,
  "diffWordWrap": true,
  "showTruncationHints": false,
  "showRtkCompactionHints": false
}

---

4. @juicesharp/rpiv-ask-user-question 1.18.2

证据：@juicesharp/rpiv-ask-user-question/config.ts, @juicesharp/rpiv-config/config.ts。

配置文件

~/.config/rpiv-ask-user-question/config.json

配置项

只读 guidance：

{
  "guidance": {
    "promptSnippet": "Ask structured clarification questions",
    "promptGuidelines": ["Use ask_user_question when concrete decisions are required."]
  }
}

字段 类型 默认 建议 guidance.promptSnippet non-empty string 包内默认 tool prompt 通常不设 guidance.promptGuidelines non-empty string[] 包内默认 guidelines 除非你要覆盖/增强 LLM 使用策略，否则不设

备注：README 提到 locale 由 --locale → ~/.config/rpiv-i18n/locale.json → LANG/LC_ALL → English 解析，这是共享 i18n 行为，不是此包专属配置。

---

5. @juicesharp/rpiv-todo 1.18.2

证据：@juicesharp/rpiv-todo/config.ts, @juicesharp/rpiv-config/config.ts。

配置文件

~/.config/rpiv-todo/config.json

配置项

同样只读 guidance：

{
  "guidance": {
    "promptSnippet": "Track multi-step work with todo",
    "promptGuidelines": ["Use todo for work with 3+ steps."]
  }
}

建议：通常不配置；保持包默认即可。locale 同上可由 ~/.config/rpiv-i18n/locale.json 或环境变量控制。

---

7. pi-cache-optimizer 2.5.5

证据：pi-cache-optimizer/index.ts。

配置入口

没有 JSON 配置文件；使用环境变量和 slash 命令。会写状态文件：

~/.pi/agent/pi-cache-optimizer-stats.json

legacy 状态文件：

~/.pi/agent/deepseek-cache-optimizer-stats.json

环境变量

环境变量 值 默认/行为 建议 PI_CACHE_RETENTION long 扩展加载时自动设置为 long 保持自动 PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY string，最长 64 给 OpenAI prompt cache/session affinity 用 多会话/代理需要稳定命中时设置 PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY 任意非空常用于 opt-out 禁用 OpenAI cache key 行为 通常不设 PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION 1 禁用 skill block 压缩 仅发现 skill 提示异常时设置 PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE 1 禁用 system prompt 重排/改写 排查 prompt 被破坏时设置

命令

/cache-optimizer 支持诊断/开关（源码注册命令描述：Diagnose Pi cache configuration）。常用：

• /cache-optimizer stats
• /cache-optimizer doctor
• /cache-optimizer compat
• /cache-optimizer enable
• /cache-optimizer disable

建议：保持启用；如果遇到 system prompt 结构异常，临时：

PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1 pi

---

8. pi-btw 0.4.0

证据：pi-btw/README.md, pi-btw/extensions/btw.ts。

无独立 JSON 配置文件。配置通过 slash 命令写入当前 session 的 hidden custom entries，随会话保存。

可配置项/命令

命令 含义 建议
`/btw:model [ clear]` 设置 BTW 侧线程专用模型；无参数显示当前有效模型 默认继承主线程；只有侧聊想用便宜/快模型时设置 `/btw:thinking [ clear]` 设置 BTW 侧线程 thinking level 默认继承；侧聊建议 off/low /btw:new 新建继承当前上下文的 BTW thread 按需
/btw:tangent 新建不继承主上下文的 tangent thread 做头脑风暴时用
/btw:inject 把 BTW 全线程注入主 agent 只在结论明确后用
/btw:summarize 总结 BTW thread 后注入主 agent 推荐优先于 inject，减少上下文污染
/btw:clear 清空 BTW thread 任务完成后清理

建议：不需要文件配置。BTW-only 模型建议设置为便宜快速模型；如果主线程是高成本模型，侧聊可用：

/btw:model openai gpt-5-mini openai-responses
/btw:thinking off

---

9. @gotgenes/pi-permission-system 10.2.0

证据：src/config-paths.ts, src/config-loader.ts, config/config.example.json, src/types.ts。

配置文件

新路径：

• 全局：~/.pi/agent/extensions/pi-permission-system/config.json
• 项目：<cwd>/.pi/extensions/pi-permission-system/config.json

legacy 路径仍会检测/读取并提示迁移：

• ~/.pi/agent/pi-permissions.jsonc
• <cwd>/.pi/agent/pi-permissions.jsonc
• 扩展根目录 config.json

合并顺序：legacy global → legacy extension → new global → legacy project → new project。项目新配置优先级最高。

顶层配置项

字段 类型 默认/行为 建议 debugLog boolean 未配置为空/false 行为 日常 false permissionReviewLog boolean example 为 true 建议 true，便于审计 yoloMode boolean false 强烈建议 false permission object 未配置时按扩展内部策略 强烈建议显式配置

example 里还有 toolInputPreviewMaxLength, toolTextSummaryMaxLength, piInfrastructureReadPaths；当前 normalizeUnifiedConfig() 只归一化 debugLog, permissionReviewLog, yoloMode, permission，这几个字段在本版本主配置 loader 中不会进入 UnifiedPermissionConfig。是否被其它路径使用需以后单独验证；保守起见不依赖它们。

permission 规则

PermissionState 只有：allow / deny / ask。

规则形态：

{
  "permission": {
    "*": "ask",
    "read": "allow",
    "write": "deny",
    "bash": {
      "*": "ask",
      "git status": "allow"
    }
  }
}

每个 surface 可以是字符串（相当于 *）或 pattern→action map。

常见 surface：

• *：默认兜底
• path：路径规则
• built-in tools: read, write, edit, bash
• mcp：MCP 工具
• skill：skill 调用
• external_directory：外部目录访问

推荐全局配置

{
  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
  "debugLog": false,
  "permissionReviewLog": true,
  "yoloMode": false,
  "permission": {
    "*": "ask",
    "path": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "read": "allow",
    "write": "ask",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "git log*": "allow",
      "ls*": "allow",
      "pwd": "allow"
    },
    "mcp": {
      "*": "ask",
      "mcp_status": "allow",
      "mcp_list": "allow"
    },
    "skill": { "*": "ask" },
    "external_directory": { "*": "ask" }
  }
}

建议：项目级配置可以比全局更严格；不要开 yoloMode，除非是在一次性、可恢复的 sandbox。

---

10. @juicesharp/rpiv-args 1.18.2

证据：@juicesharp/rpiv-args/args.ts, index.ts。

无独立配置文件。它增强 /skill:<name> <args> 行为：

• 支持 $1, $2, $ARGUMENTS, $@, ${@:N[:L]} 参数替换
• 支持 ${SKILL_DIR}, ${SESSION_ID} 变量替换
• 支持 skill body 中 shell 执行：inline !`cmd`、block ! ...
• shell 超时可通过 skill frontmatter 配置：shell-timeout

skill frontmatter 配置项

字段 类型/值 默认 建议 shell-timeout number 秒；0 禁用超时 120 秒 有 shell 的 skill 建议显式 30–120；不建议 0

示例：

---
shell-timeout: 60
---
请分析：$ARGUMENTS

当前目录文件：
!`find . -maxdepth 2 -type f | head -50`

---

11. pi-mono-multi-edit 1.7.3

证据：pi-mono-multi-edit/index.ts。

无配置文件、无环境变量。它替换/增强内置 edit 工具，新增：

• multi: 多个 exact replace 顺序执行
• patch: Codex-style patch

建议：无需配置。使用层面建议：

• 小范围精确替换：path + oldText + newText
• 多处重复替换：multi
• 多文件/hunk：patch
• 不要同时使用 patch 和 classic 参数（源码会报错）

---

12. @narumitw/pi-goal 0.1.36

证据：@narumitw/pi-goal/src/goal.ts。

状态文件

~/.pi/agent/pi-goal-state.json

若设置 PI_CODING_AGENT_DIR，路径为：

$PI_CODING_AGENT_DIR/pi-goal-state.json

可配置/命令

无独立配置文件；通过 /goal 命令控制 active goal：

/goal [--tokens 100k] <goal_to_complete>
/goal pause
/goal resume
/goal clear
/goal edit ...

--tokens 是 per-goal token budget，不是全局配置。

建议：不要手改状态文件；通过 /goal 管理。

---

13. @hsingjui/pi-hooks 0.0.2

证据：@hsingjui/pi-hooks/src/config.ts, src/types.ts, README.zh-CN。

配置文件

读取并合并：

1. 全局：~/.pi/agent/settings.json
2. 项目：<cwd>/.pi/settings.json

字段为顶层 hooks。同一事件的 global hooks + project hooks 会拼接执行。

支持事件名

大小写/下划线别名都支持：

• SessionStart / session_start
• SessionEnd / session_end
• PreCompact / pre_compact
• PostCompact / post_compact
• PreToolUse / pre_tool_use
• PostToolUse / post_tool_use
• PostToolUseFailure / post_tool_use_failure
• UserPromptSubmit / user_prompt_submit
• Stop / stop

配置结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $PI_HOOK_CONTEXT",
            "timeout": 10,
            "async": false,
            "if": "true"
          }
        ]
      }
    ]
  }
}

字段 类型/可选值 默认/行为 建议 group matcher regex string；undefined/""/"*" 匹配全部 匹配事件值（toolName/prompt/source 等） 尽量写窄，避免全局误触发 group hooks Hook[] 空则无动作 按顺序少量执行 hook type 目前只有 "command" 必填 固定 hook command shell command 必填 命令要幂等，避免破坏性操作 hook if string 可选 复杂条件建议先不用 hook timeout number 秒 可选 建议 5–30 秒 hook async boolean false/同步 不影响主流程的通知类 hook 可 true

建议：用于审计、格式化、通知很适合；不要在 hook 里做慢任务或危险写操作。

---

14. @tintinweb/pi-subagents 0.10.0

证据：src/settings.ts, src/custom-agents.ts, src/types.ts, src/agent-manager.ts, src/agent-runner.ts, README/CHANGELOG。

运行设置文件

• 全局：~/.pi/agent/subagents.json（只读；手工维护）
• 项目：<cwd>/.pi/subagents.json（/agents → Settings 会写入；覆盖全局）

subagents.json 配置项

字段 类型/范围 默认 建议 maxConcurrent int 1–1024 4 3–4；机器弱/模型慢用 2 defaultMaxTurns int 0–10000；0=unlimited unlimited 建议 20–40，防 runaway；探索类可 10–20 graceTurns int 1–1000 5 3–5 defaultJoinMode async / group / smart smart 保持 smart schedulingEnabled boolean true 不用定时 agent 可 false，减少 tool schema scopeModels boolean false 若你使用 /scoped-models 控成本，建议 true

推荐项目配置：

{
  "maxConcurrent": 3,
  "defaultMaxTurns": 30,
  "graceTurns": 5,
  "defaultJoinMode": "smart",
  "schedulingEnabled": false,
  "scopeModels": true
}

自定义 agent 文件

发现路径：

• 项目：<cwd>/.pi/agents/*.md
• 全局：~/.pi/agent/agents/*.md（受 PI_CODING_AGENT_DIR 影响）

项目同名覆盖全局；同名也可覆盖默认 agent（如 Explore.md）。

frontmatter 字段：

字段 类型/可选值 默认/行为 建议 display_name string 文件名 可读名称 description string 文件名 写清何时使用/何时不要用 tools CSV；*/all=全部内置；可含 ext:<tool> 全部内置 最小权限原则，只给需要的工具 disallowed_tools CSV 无 明确禁用 bash,write,edit 等 extensions / inherit_extensions true / false / none / CSV true 默认 true；安全敏感 agent 设 false skills / inherit_skills true / false / none / CSV true 只预加载必要 skills model provider/modelId 或可解析模型名 继承/调用参数 成本敏感 agent 固定便宜模型 thinking Pi thinking level 未设 探索 low/off；计划 medium max_turns non-negative int；0=unlimited 全局 default 建议显式 10–30 prompt_mode replace / append replace 专用 agent 用 replace；需继承主系统提示用 append inherit_context boolean 调用方决定 默认 false；需要父会话上下文才 true run_in_background boolean 调用方决定 通常不在 frontmatter 固定 isolated boolean 调用方决定 安全探索 true；需要扩展工具则 false memory user / project / local 无 少用；长期专业 agent 可 project isolation worktree 无 改代码型 agent 可用，但需 git repo enabled boolean true 临时禁用设 false

示例：

---
description: "只读探索代码位置，禁止修改文件。"
tools: read, grep, find, ls
disallowed_tools: bash, write, edit
extensions: none
skills: none
thinking: low
max_turns: 12
prompt_mode: replace
---
你是只读代码探索 agent。只查找和总结，不修改文件。

schedule 状态文件

启用 schedule 且创建定时任务后写入：

<cwd>/.pi/subagent-schedules/<sessionId>.json

建议：如果你不用定时 agent，把 schedulingEnabled 设为 false。

---

15. @narumitw/pi-statusline 0.1.36

证据：@narumitw/pi-statusline/src/statusline.ts, README。

无 JSON 配置文件。唯一用户配置：

环境变量 可选值 默认 建议 PI_STATUSLINE_PRESET tokyo-night / classic tokyo-night 喜欢 powerline 样式用默认；兼容性/简洁优先用 classic

示例：

PI_STATUSLINE_PRESET=classic pi

内部默认配置（源码固定，当前版本不可通过文件改）：

• palette: candy
• density: compact
• separator: dot
• showLabels: false
• segments: brand, model, thinking, cwd, branch, tools, context, tokens, cost, time

还会读取 ~/.pi/agent/settings.json 和 <cwd>/.pi/settings.json 的 packages，用于检测重复安装来源；这不是用户可调的 statusline 配置。

---

建议优先级

1. 先配权限：@gotgenes/pi-permission-system，至少保护 .env、写操作、bash、MCP。
2. 再配 MCP：如果用 MCP，集中维护 ~/.pi/agent/mcp.json；项目私有 MCP 放 <cwd>/.pi/mcp.json。
3. 再配 subagents：建议限制 maxConcurrent/defaultMaxTurns，不用 schedule 就关掉。
4. UI 类默认即可：pi-tool-display, pi-statusline, pi-fff 大多默认值可用。
5. 高风险/强行为扩展谨慎：pi-blackhole, pi-cache-optimizer 会改 compaction/prompt/cache 行为；出问题优先用 env 临时关闭相关能力。

快速推荐配置清单

~/.pi/agent/extensions/pi-permission-system/config.json

{
  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
  "debugLog": false,
  "permissionReviewLog": true,
  "yoloMode": false,
  "permission": {
    "*": "ask",
    "path": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "read": "allow",
    "write": "ask",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "git log*": "allow",
      "ls*": "allow",
      "pwd": "allow"
    },
    "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
    "skill": { "*": "ask" },
    "external_directory": { "*": "ask" }
  }
}

<project>/.pi/subagents.json

{
  "maxConcurrent": 3,
  "defaultMaxTurns": 30,
  "graceTurns": 5,
  "defaultJoinMode": "smart",
  "schedulingEnabled": false,
  "scopeModels": true
}

~/.pi/agent/extensions/pi-tool-display/config.json

{
  "registerToolOverrides": {
    "read": true,
    "grep": true,
    "find": true,
    "ls": true,
    "bash": true,
    "edit": true,
    "write": true
  },
  "enableNativeUserMessageBox": true,
  "readOutputMode": "hidden",
  "searchOutputMode": "count",
  "mcpOutputMode": "summary",
  "previewLines": 10,
  "expandedPreviewMaxLines": 4000,
  "bashOutputMode": "opencode",
  "bashCollapsedLines": 12,
  "diffViewMode": "auto",
  "diffIndicatorMode": "bars",
  "diffSplitMinWidth": 120,
  "diffCollapsedLines": 32,
  "diffWordWrap": true,
  "showTruncationHints": false,
  "showRtkCompactionHints": false
}

复核清单

已覆盖用户列出的 15 个包：

• npm:pi-mcp-adapter
• npm:@ff-labs/pi-fff
• npm:pi-tool-display
• npm:@juicesharp/rpiv-ask-user-question
• npm:@juicesharp/rpiv-todo
• npm:pi-blackhole
• npm:pi-cache-optimizer
• npm:pi-btw
• npm:@gotgenes/pi-permission-system
• npm:@juicesharp/rpiv-args
• npm:pi-mono-multi-edit
• npm:@narumitw/pi-goal
• npm:@hsingjui/pi-hooks
• npm:@tintinweb/pi-subagents
• npm:@narumitw/pi-statusline

---

2026-06-06 当前 agent/settings.json packages 快照（本机安装版本）

追加方式：按用户确认，不重写上文历史内容，只在末尾追加当前快照。
版本来源：本机 /Users/rao/.pi/agent/npm/node_modules/*/package.json。未联网查询、未执行 pi update。
settings 来源：/Users/rao/.pi/agent/settings.json 当前 packages 共 16 个。

当前已安装包总览

# settings 条目 本机版本 主要配置入口 是否建议配置 1 npm:pi-blackhole 0.3.5 ~/.pi/agent/pi-blackhole/pi-blackhole-config.json + env 已有配置，建议保守复核 2 npm:pi-mcp-adapter 2.9.0 ~/.pi/agent/mcp.json、项目 .pi/mcp.json、--mcp-config 已有 MCP server，建议持续维护 3 npm:@ff-labs/pi-fff 0.9.1 flags / env 默认即可 4 npm:pi-tool-display 0.4.2 ~/.pi/agent/extensions/pi-tool-display/config.json 可按 TUI 偏好配置 5 npm:@juicesharp/rpiv-ask-user-question 1.18.2 ~/.config/rpiv-ask-user-question/config.json 通常不用 6 npm:@juicesharp/rpiv-todo 1.18.2 ~/.config/rpiv-todo/config.json 通常不用 7 npm:@gotgenes/pi-permission-system 10.3.0 ~/.pi/agent/extensions/pi-permission-system/config.json + 项目同路径 已有配置，建议补齐 surface 8 npm:@juicesharp/rpiv-args 1.18.2 skill frontmatter / skill body 仅写 skill 时需要 9 npm:@narumitw/pi-goal 0.1.36 /goal 命令 + ~/.pi/agent/pi-goal-state.json 状态文件 不建议手改状态 10 npm:@hsingjui/pi-hooks 0.0.2 settings.json 顶层 hooks 需要 hooks 时配置 11 npm:@vanillagreen/pi-skills-manager 1.1.1 settings.json 的 vstack.extensionManager.config 可选，按 UI 偏好配置 12 npm:pi-nano-context 0.1.1 无独立配置 不需要 13 npm:pi-subagents 0.28.0 ~/.pi/agent/extensions/subagent/config.json + settings.json.subagents 建议按并发/安全策略配置 14 npm:pi-intercom 0.6.0 ~/.pi/agent/intercom/config.json 多 session 协作时建议配置 15 npm:pi-cache-optimizer 2.5.5 env + /cache-optimizer + stats 文件 默认启用即可 16 npm:@narumitw/pi-plan-mode 0.1.36 /plan、--plan、/plan tools 不需要持久配置

当前本机已有相关配置文件（只记录结构，不展开 secret）

配置文件 当前状态 结构摘要 ~/.pi/agent/mcp.json 存在 顶层 mcpServers；server 名称：tavily, context7 ~/.pi/agent/pi-blackhole/pi-blackhole-config.json 存在 包含 compaction, compactionEngine, tailBehavior, token 阈值、memory, debugLog 等 ~/.pi/agent/extensions/pi-permission-system/config.json 存在 顶层 $schema, debugLog, permissionReviewLog, yoloMode, permission；当前 permission surfaces：*, external_directory, path, bash ~/.pi/agent/extensions/pi-tool-display/config.json 不存在 使用包默认值 ~/.config/rpiv-ask-user-question/config.json 不存在 使用包默认 guidance ~/.config/rpiv-todo/config.json 不存在 使用包默认 guidance ~/.pi/agent/intercom/config.json 不存在 使用包默认值 ~/.pi/agent/extensions/subagent/config.json 不存在 使用包默认值 ~/.pi/agent/pi-goal-state.json 不存在 当前未发现持久 active goal 状态文件

---

1. pi-blackhole 0.3.5

配置入口

• 主配置：~/.pi/agent/pi-blackhole/pi-blackhole-config.json
• legacy fallback：~/.pi/agent/pi-vcc-config.json、settings.json 中的 pi-blackhole / observational-memory
• env override：PI_BLACKHOLE_PASSIVE, PI_BLACKHOLE_COMPACTION, PI_BLACKHOLE_COMPACTION_ENGINE 等

关键配置建议

场景 建议 稳定优先 compaction: "manual", compactionEngine: "pi-default", tailBehavior: "pi-default", memory: false 长会话 + 想用 blackhole memory compaction: "auto", compactionEngine: "blackhole", tailBehavior: "minimal", memory: true 临时停用 启动时设置 PI_BLACKHOLE_PASSIVE=1 排错 临时 debug: true / debugLog: true，排完关闭

当前本机已有该配置文件，建议只做复核，不建议在不了解效果时扩大 token 阈值或开启 debug 日志。

---

2. pi-mcp-adapter 2.9.0

配置入口

读取/合并顺序：

1. ~/.config/mcp/mcp.json
2. ~/.pi/agent/mcp.json
3. <cwd>/.mcp.json
4. <cwd>/.pi/mcp.json
5. 可用 pi --mcp-config /path/to/mcp.json 指定路径

当前本机 ~/.pi/agent/mcp.json 存在，server 名称为 tavily, context7。

关键配置建议

• API token 优先放环境变量，配 bearerTokenEnv，不要在 JSON 写明文 bearerToken。
• 默认建议 settings.toolPrefix: "server"，避免 MCP direct tool 重名。
• 多数 server 用 lifecycle: "lazy" + idleTimeout: 10；高频且稳定的 server 再考虑 keep-alive。
• sampling, samplingAutoApprove, elicitationAutoOpenUrls 默认关闭更安全。
• direct tools 建议精确白名单，而不是全局无脑 directTools: true。

---

3. @ff-labs/pi-fff 0.9.1

配置入口：无 JSON 配置文件；使用 Pi flags / env。

配置 来源 默认/建议 mode --fff-mode / PI_FFF_MODE 默认 tools-and-ui；若 UI 冲突，用 tools-only frecency DB --fff-frecency-db / FFF_FRECENCY_DB 通常不设 history DB --fff-history-db / FFF_HISTORY_DB 通常不设 experimental multi grep PI_FFF_MULTIGREP=1 不建议日常开启

---

4. pi-tool-display 0.4.2

配置入口：~/.pi/agent/extensions/pi-tool-display/config.json（当前不存在，使用默认值）。

常用建议值

{
  "readOutputMode": "hidden",
  "searchOutputMode": "count",
  "mcpOutputMode": "summary",
  "previewLines": 10,
  "expandedPreviewMaxLines": 4000,
  "bashOutputMode": "opencode",
  "bashCollapsedLines": 12,
  "diffViewMode": "auto",
  "diffIndicatorMode": "bars",
  "diffSplitMinWidth": 120,
  "diffCollapsedLines": 32,
  "diffWordWrap": true,
  "showTruncationHints": false,
  "showRtkCompactionHints": false
}

建议：如果当前 TUI 输出没有干扰，先不建配置文件；只在想改变 read/search/MCP 输出展示时配置。

---

5. @juicesharp/rpiv-ask-user-question 1.18.2

配置入口：~/.config/rpiv-ask-user-question/config.json（当前不存在）。

只读 guidance 配置，通常不需要覆盖：

{
  "guidance": {
    "promptSnippet": "Ask structured clarification questions",
    "promptGuidelines": ["Use ask_user_question when concrete decisions are required."]
  }
}

建议：保持包默认 guidance，除非你要改变 agent 何时使用结构化提问。

---

6. @juicesharp/rpiv-todo 1.18.2

配置入口：~/.config/rpiv-todo/config.json（当前不存在）。

同样只读 guidance：

{
  "guidance": {
    "promptSnippet": "Track multi-step work with todo",
    "promptGuidelines": ["Use todo for work with 3+ steps."]
  }
}

建议：保持默认即可。

---

7. @gotgenes/pi-permission-system 10.3.0

配置入口

• 全局：~/.pi/agent/extensions/pi-permission-system/config.json
• 项目：<cwd>/.pi/extensions/pi-permission-system/config.json
• legacy：~/.pi/agent/pi-permissions.jsonc, <cwd>/.pi/agent/pi-permissions.jsonc

当前本机已有全局配置；当前 permission surfaces 为 *, external_directory, path, bash。

建议复核点

• 保持 yoloMode: false。
• 建议 permissionReviewLog: true，便于审计。
• 如果希望权限更明确，可补齐这些 surface：read, write, edit, mcp, skill。
• .env/secret 文件建议 deny 或至少 ask；bash 建议只 allow 明确安全命令（如 git status, git diff, pwd, ls*）。

保守示例

{
  "debugLog": false,
  "permissionReviewLog": true,
  "yoloMode": false,
  "permission": {
    "*": "ask",
    "path": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "read": "allow",
    "write": "ask",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff": "allow",
      "git log*": "allow",
      "ls*": "allow",
      "pwd": "allow"
    },
    "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
    "skill": { "*": "ask" },
    "external_directory": { "*": "ask" }
  }
}

---

8. @juicesharp/rpiv-args 1.18.2

配置入口：无独立配置文件；作用在 skill 调用和 skill body。

支持：

• 参数替换：$1, $2, $ARGUMENTS, $@, ${@:N[:L]}
• 变量替换：${SKILL_DIR}, ${SESSION_ID}
• skill body shell substitution：inline !`cmd` 与 block ! ...
• skill frontmatter：shell-timeout（秒；默认 120，0 为禁用超时）

建议：包含 shell substitution 的 skill 显式配置 shell-timeout: 30 到 120，避免无限等待。

---

9. @narumitw/pi-goal 0.1.36

配置入口：无独立配置文件；通过 /goal 管理。

• 状态文件：~/.pi/agent/pi-goal-state.json（当前未发现）
• 常用命令：/goal <goal>, /goal pause, /goal resume, /goal clear, /goal edit ...
• --tokens 是 per-goal token budget，不是全局配置。

建议：不要手动编辑状态文件；需要清理时用 /goal clear。

---

10. @hsingjui/pi-hooks 0.0.2

配置入口：全局/项目 settings.json 顶层 hooks。

读取并合并：

1. ~/.pi/agent/settings.json
2. <cwd>/.pi/settings.json

当前全局 settings 未发现顶层 hooks。

支持事件：SessionStart, SessionEnd, PreCompact, PostCompact, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop（也支持 snake_case 别名）。

配置建议

• hook 命令要幂等、短时、低风险。
• matcher 尽量写窄，例如只匹配 bash 或某类 tool。
• timeout 建议 5–30 秒。
• 通知类 hook 可用 async: true；会影响主流程的 hook 谨慎使用。

---

11. @vanillagreen/pi-skills-manager 1.1.1

配置入口：写入 Pi settings 的 vstack 配置块，而不是独立 JSON 文件。

全局：~/.pi/agent/settings.json；项目：<cwd>/.pi/settings.json。

{
  "vstack": {
    "extensionManager": {
      "config": {
        "@vanillagreen/pi-skills-manager": {
          "enabled": true,
          "hideStartupSkillsBlock": true,
          "aiGenerationEnabled": true,
          "defaultCreateLocation": "project",
          "popupWidth": "82%",
          "popupMaxHeight": "86%",
          "listRows": 14,
          "glyphStyle": "unicode"
        }
      }
    }
  }
}

命令/行为

命令 作用 /skill 打开 skills manager /skill disable 禁用 manager feature toggle，需 /reload 卸载 /skill:enable 被禁用后的恢复命令 /skill:<name> 仍走 Pi 原生 skill invocation

配置建议

• 默认 enabled: true、hideStartupSkillsBlock: true 可减少启动噪声。
• 如果不希望用当前模型生成 skill 草稿，设 aiGenerationEnabled: false。
• defaultCreateLocation 建议项目技能用 project，跨项目通用技能才用 global。
• 终端 glyph 兼容性差时设 glyphStyle: "ascii"，或用 @vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii 做全局覆盖。

---

12. pi-nano-context 0.1.1

配置入口：无独立配置文件、无用户 env 配置。

作用：替换默认 context meter，在 editor 下方显示紧凑 segmented bar，分段包括：

• sys：system prompt
• pr：用户 prompts / images
• assistant：assistant replies / tool calls
• think：thinking blocks
• tools：tool results
• free：剩余 context

建议：保持默认即可；如果和其它 statusline/context UI 冲突，再考虑移除该包。

---

13. pi-subagents 0.28.0

配置入口

1. 扩展运行配置：~/.pi/agent/extensions/subagent/config.json（当前不存在）
2. builtin agent overrides：~/.pi/agent/settings.json 或 <cwd>/.pi/settings.json 的顶层 subagents
3. 自定义 agents：~/.pi/agent/agents/**/*.md, <cwd>/.pi/agents/**/*.md（也读 legacy .agents/**/*.md）
4. packaged agents/prompts/skills：来自包自身 agents/, prompts/, skills/

扩展配置项

字段 作用 建议 asyncByDefault 未显式指定时默认后台执行 通常 false，需要长任务再开 forceTopLevelAsync 强制顶层 single/parallel/chain 后台 谨慎开启 parallel.maxTasks 顶层 parallel 任务上限，默认 8 4–8 parallel.concurrency 顶层并发，默认 4 2–4 更稳 defaultSessionDir 子会话保存目录 需要集中归档时配置 maxSubagentDepth nested delegation 深度 1–2；避免无限嵌套 control active_long_running / needs_attention 通知 长任务建议启用默认即可 chain.dynamicFanout.maxItems dynamic fanout 最大 item 数 大任务时设置上限 worktreeSetupHook git worktree 初始化 hook 仅成熟 repo 使用 intercomBridge.mode always / fork-only / off 装了 pi-intercom 时默认可用；保守用 fork-only

示例

{
  "parallel": { "maxTasks": 8, "concurrency": 3 },
  "maxSubagentDepth": 1,
  "intercomBridge": { "mode": "fork-only" }
}

builtin override 示例

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "model": "anthropic/claude-sonnet-4",
        "thinking": "high",
        "fallbackModels": ["openai/gpt-5-mini"]
      }
    }
  }
}

建议：不要复制 builtin agent 文件做小改；常规模型、tools、skills、context、prompt 修改优先用 subagents.agentOverrides。

---

14. pi-intercom 0.6.0

配置入口：~/.pi/agent/intercom/config.json（当前不存在，使用默认值）。

配置示例

{
  "brokerCommand": "npx",
  "brokerArgs": ["--no-install", "tsx"],
  "confirmSend": false,
  "enabled": true,
  "replyHint": true,
  "status": "researching"
}

字段 默认 建议 brokerCommand npx 如果更想用 Bun，可设为 bun brokerArgs ["--no-install", "tsx"] Bun 时可设 [] confirmSend false 想手动确认非 reply send 时设 true enabled true 临时禁用设 false replyHint true 保持 true，方便回复 pending ask status 未设 可填自定义状态后缀

运行文件：~/.pi/agent/intercom/ 下会有 broker socket / pid / config 等运行文件。

建议：多 Pi session 协作时使用；同机 1:1 通信，不是网络通信。和 pi-subagents 配合时可让 child 通过 contact_supervisor 向父会话请求决策。

---

15. pi-cache-optimizer 2.5.5

配置入口：无 JSON 配置文件；使用 env、slash 命令和 stats 文件。

命令

命令 作用 /cache-optimizer 打开菜单/打印帮助和当前状态 /cache-optimizer enable 当前进程启用优化并重置当前统计 /cache-optimizer disable 当前进程禁用优化；/reload/重启恢复启动行为 /cache-optimizer doctor 诊断当前模型/provider/API/base URL/compat /cache-optimizer compat 输出当前模型兼容性建议 /cache-optimizer stats 显示当天 session 级缓存统计 /cache-optimizer reset 只重置本地统计，不影响 provider cache

env

env 作用 建议 PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1 禁用 prompt mutation，保留 footer stats/cache key fallback 排查 prompt 异常时用 PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1 不压缩 skill XML 仅 skill 提示异常时用 PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY=1 禁用 OpenAI-compatible prompt_cache_key fallback 需要显式 opt-out 时用 PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY=0 legacy inverse opt-out 新配置优先用上一项

Stats 文件：~/.pi/agent/pi-cache-optimizer-stats.json，只保存日期和数值统计，不保存 API key、prompt、payload、headers、responses 或模型输出。

建议：默认启用即可；第三方 OpenAI-compatible proxy 低命中时，优先跑 /cache-optimizer doctor / /cache-optimizer compat。

---

16. @narumitw/pi-plan-mode 0.1.36

配置入口：无持久 JSON 配置；通过 slash command / CLI flag / session state 工作。

入口 作用 /plan 进入或管理 Plan mode /plan <prompt> 进入 Plan mode 并立即提交 planning prompt /plan tools 选择 Plan mode 中允许的工具 /plan exit 退出并丢弃 latest proposed plan --plan 启动时进入 Plan mode plan_mode_question Plan mode 下必需的结构化提问工具

Plan mode 默认允许 read-only 内置工具，阻止 edit/write 和危险 bash；extension/custom tools 默认禁用，需要用户通过 /plan tools 显式 opt-in。

建议：适合较大修改前的只读探索和方案确认；不要把它当 TODO/progress tracker。最终 plan 应输出一个 <proposed_plan>...</proposed_plan>，用户选择实现后才恢复完整工具访问。

---

当前快照建议优先级

1. 权限优先：当前已有 pi-permission-system 配置，但 surface 只覆盖 *, external_directory, path, bash；建议后续补齐 read/write/edit/mcp/skill，让行为更明确。
2. MCP 继续维护：当前 mcp.json 有 tavily 和 context7；确认 token 不写明文，优先用 env。
3. Subagents + Intercom 可轻量配置：当前两者都使用默认配置；如果经常使用子代理，建议给 pi-subagents 设置并发/深度上限，给 pi-intercom 设置 replyHint/confirmSend 偏好。
4. UI 类默认可用：pi-tool-display, pi-nano-context, pi-skills-manager 多数场景默认即可；只在 TUI 展示冲突或偏好明确时配置。
5. 强行为扩展保守复核：pi-blackhole, pi-cache-optimizer, pi-plan-mode 会影响上下文压缩、prompt/cache、工具权限边界；遇到异常优先用 env/slash 临时关闭相关能力。

当前快照复核清单

当前 settings.json 的 16 个 packages 已覆盖：

• npm:pi-blackhole
• npm:pi-mcp-adapter
• npm:@ff-labs/pi-fff
• npm:pi-tool-display
• npm:@juicesharp/rpiv-ask-user-question
• npm:@juicesharp/rpiv-todo
• npm:@gotgenes/pi-permission-system
• npm:@juicesharp/rpiv-args
• npm:@narumitw/pi-goal
• npm:@hsingjui/pi-hooks
• npm:@vanillagreen/pi-skills-manager
• npm:pi-nano-context
• npm:pi-subagents
• npm:pi-intercom
• npm:pi-cache-optimizer
• npm:@narumitw/pi-plan-mode

---

2026-06-07 当前 agent/settings.json packages 快照（本机安装版本）

追加方式：按用户确认，不重写上文历史内容，只在末尾追加当前快照。
版本来源：本机 /Users/rao/.pi/agent/npm/node_modules/*/package.json。未联网查询、未执行 pi update。
settings 来源：/Users/rao/.pi/agent/settings.json 当前 packages 共 23 个。
注意：node_modules 下还存在一些旧快照包目录，但本节只按当前 settings.json 实际加载列表整理。

当前已加载包总览

# settings 条目 本机版本 主要配置入口 是否建议配置 1 npm:pi-mcp-adapter 2.9.0 mcp.json 多路径 + --mcp-config 如果用 MCP，建议维护 2 npm:@ff-labs/pi-fff 0.9.3 flags / env 默认即可 3 npm:@juicesharp/rpiv-ask-user-question 1.18.2 ~/.config/rpiv-ask-user-question/config.json 通常不用 4 npm:@gotgenes/pi-permission-system 10.3.1 全局/项目 extensions/pi-permission-system/config.json 强烈建议复核 5 npm:@juicesharp/rpiv-args 1.18.2 skill frontmatter / skill body 仅写 skill 时需要 6 npm:@narumitw/pi-goal 0.1.37 /goal + ~/.pi/agent/pi-goal-state.json 不建议手改状态 7 npm:@hsingjui/pi-hooks 0.0.2 settings.json 顶层 hooks 需要 hooks 时配置 8 npm:@vanillagreen/pi-skills-manager 1.1.1 /extensions:settings 或 settings.json.vstack.extensionManager.config 可选 9 npm:pi-cache-optimizer 2.5.6 env + /cache-optimizer + stats 文件 默认启用即可 10 npm:@narumitw/pi-plan-mode 0.1.37 /plan、--plan、/plan tools 不需要持久配置 11 npm:pi-tool-display 0.4.2 ~/.pi/agent/extensions/pi-tool-display/config.json 已有配置，按偏好维护 12 npm:pi-claude-sandbox 0.6.0 ~/.pi/agent/sandbox.json、项目 .pi/sandbox.json、--no-sandbox 已有配置，建议复核 13 npm:pi-hash-anchored-edit 0.1.4 无独立配置；注册 hash-anchored read/edit 工具 不需要 14 npm:@tifan/pi-inline-skills 1.0.3 无独立配置；读取当前 skills/commands 不需要 15 npm:pi-agentsmd 0.1.0 /init、--force；安装遥测受 settings/env 控制 按需使用 16 npm:pi-nano-context 0.1.1 无独立配置 不需要 17 npm:@agnishc/edb-context-viewer 0.14.3 /context 不需要 18 npm:@sting8k/pi-vcc 0.3.15 ~/.pi/agent/pi-vcc-config.json + PI_VCC_CONFIG_PATH 已有配置，建议复核 19 npm:@tintinweb/pi-subagents 0.10.0 subagents.json、.pi/agents/*.md、schedule 文件 建议按并发/安全策略配置 20 npm:@tintinweb/pi-tasks 0.7.0 <cwd>/.pi/tasks-config.json + 内存/session/project task store 可选 21 npm:pi-system-prompt 0.1.4 slash command 查看 system prompt 不需要 22 npm:pi-bg-run 1.1.4 settings.json 顶层 bgRun 可选，长任务建议配置 23 npm:pi-aliases 1.0.7 无独立配置；命令别名 不需要

当前本机已有相关配置文件（只记录结构，不展开 secret）

配置文件 当前状态 结构摘要 / 当前值 ~/.pi/agent/mcp.json 存在 顶层 mcpServers ~/.pi/agent/extensions/pi-permission-system/config.json 存在 顶层 $schema, debugLog, permissionReviewLog, yoloMode；当前未发现 permission/permissions 规则块；yoloMode: true, permissionReviewLog: false ~/.pi/agent/extensions/pi-tool-display/config.json 存在 已设置输出展示项；当前模式：readOutputMode: "summary", searchOutputMode: "count", mcpOutputMode: "summary", bashOutputMode: "summary", diffViewMode: "auto" ~/.pi/agent/sandbox.json 存在 enabled: true；含 network.allowedDomains/deniedDomains 与 filesystem.denyRead/allowRead/allowWrite/denyWrite <cwd>/.pi/sandbox.json（当前 cwd 为 /Users/rao/.pi） 不存在 使用全局 sandbox 配置和包默认值 ~/.pi/agent/pi-vcc-config.json 存在 overrideDefaultCompaction: true, debug: false <cwd>/.pi/tasks-config.json（当前 cwd 为 /Users/rao/.pi） 不存在 @tintinweb/pi-tasks 使用默认配置 ~/.pi/agent/pi-cache-optimizer-stats.json 存在 顶层 version, sessions, legacyFamily；统计文件，不含 prompt/API key ~/.pi/agent/extensions/pi-agentsmd-install.json 存在 顶层 lastReportedVersion ~/.config/rpiv-ask-user-question/config.json 不存在 使用包默认 guidance ~/.pi/agent/pi-goal-state.json 不存在 当前未发现持久 active goal 状态文件

重点配置与建议

1. pi-mcp-adapter 2.9.0

• 配置来源仍为 ~/.config/mcp/mcp.json、~/.pi/agent/mcp.json、<cwd>/.mcp.json、<cwd>/.pi/mcp.json，后者覆盖前者同名 server。
• 当前 ~/.pi/agent/mcp.json 存在；建议继续避免在 JSON 中写明文 token，优先使用 env 或 bearerTokenEnv。
• settings.toolPrefix 建议保持 server 或默认策略，避免 MCP direct tools 与本地工具重名。

2. @ff-labs/pi-fff 0.9.3

• 相比旧快照从 0.9.1 更新到 0.9.3。
• 仍无 JSON 配置文件；配置入口为 --fff-mode / PI_FFF_MODE、FFF_FRECENCY_DB、FFF_HISTORY_DB、PI_FFF_MULTIGREP。
• 建议保持默认 tools-and-ui；如 editor mention UI 冲突，再用 PI_FFF_MODE=tools-only。

3. @juicesharp/rpiv-ask-user-question 1.18.2

• 当前未发现 ~/.config/rpiv-ask-user-question/config.json。
• 只需要在想覆盖结构化提问 guidance 时创建配置；日常建议保持包默认。

4. @gotgenes/pi-permission-system 10.3.1

• 相比旧快照从 10.3.0 更新到 10.3.1。
• 当前全局配置存在，但只看到运行开关：$schema, debugLog, permissionReviewLog, yoloMode；未发现实际 permission/permissions 规则块。
• 当前 yoloMode: true 且 permissionReviewLog: false：这会减少交互确认和审计记录，建议根据安全需求复核。
• 建议补齐 flat permission 规则块，至少覆盖 *, path, read, write, edit, bash, mcp, skill, external_directory。
• 规则语义：surface 内 pattern map 为“最后匹配规则生效”；path 是跨工具路径保护面，适合统一 deny .env, ~/.ssh/* 等敏感路径。

5. @juicesharp/rpiv-args 1.18.2

• 无独立配置文件；作用在 skill invocation。
• 支持 $1, $ARGUMENTS, $@, ${@:N[:L]}, ${SKILL_DIR}, ${SESSION_ID}，以及 ! shell substitution。
• 写含 shell substitution 的 skill 时，建议在 frontmatter 设置 shell-timeout。

6. @narumitw/pi-goal 0.1.37

• 相比旧快照从 0.1.36 更新到 0.1.37。
• 当前未发现 ~/.pi/agent/pi-goal-state.json。
• 通过 /goal, /goal pause, /goal resume, /goal clear 管理；不建议手改状态文件。

7. @hsingjui/pi-hooks 0.0.2

• 当前全局 settings.json 未发现顶层 hooks。
• 支持 SessionStart, SessionEnd, PreCompact, PostCompact, PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop 及 snake_case 别名。
• 建议 hook 命令短时、幂等、matcher 写窄；通知类 hook 可考虑 async: true。

8. @vanillagreen/pi-skills-manager 1.1.1

• 配置主要通过 /extensions:settings 写入 settings.json 的 vstack.extensionManager.config["@vanillagreen/pi-skills-manager"]。
• 当前全局 settings 未发现 vstack 配置块，使用包默认。
• 关键项：enabled, hideStartupSkillsBlock, aiGenerationEnabled, defaultCreateLocation, glyphStyle。
• 注意：该扩展可在 UI 中删除用户自有 project/global skills；删除前应按本机协议单独确认。

9. pi-cache-optimizer 2.5.6

• 相比旧快照从 2.5.5 更新到 2.5.6。
• 无 JSON 配置文件；使用 /cache-optimizer 命令、env 和 stats 文件。
• 当前 stats 文件存在；仅保存统计，不保存 API key、prompt、payload、headers、responses 或模型输出。
• 排错优先使用 /cache-optimizer doctor / /cache-optimizer compat，或临时 env：PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE=1。

10. @narumitw/pi-plan-mode 0.1.37

• 相比旧快照从 0.1.36 更新到 0.1.37。
• 无持久 JSON 配置；通过 /plan, /plan tools, /plan exit, --plan 工作。
• Plan mode 默认偏 read-only；适合大修改前探索与确认，不应当作 TODO/progress tracker。

11. pi-tool-display 0.4.2

• 当前全局配置文件存在，已从旧快照的“未配置”变为“已配置”。
• 当前展示偏摘要：read/search/MCP/bash 输出分别为 summary/count/summary/summary。
• 如排查工具输出缺失，可临时把对应 *OutputMode 调整为更展开的模式；日常维持摘要有利于降低 TUI 噪声。

12. pi-claude-sandbox 0.6.0

• 当前新增加载；提供 bash 子进程 OS-level sandbox，不覆盖 in-process read/write/edit 工具权限。
• 配置合并顺序：~/.pi/agent/sandbox.json + <cwd>/.pi/sandbox.json，项目配置优先。
• 可用 --no-sandbox 临时禁用；/sandbox 查看当前配置。
• 当前全局 sandbox 已启用，包含 network 与 filesystem allow/deny 规则；建议定期复核 allowWrite 是否过宽、denyRead/denyWrite 是否覆盖 secret 路径。
• 规则语义：read 中 allowRead 可覆盖 denyRead；write 中 denyWrite 优先于 allowWrite。

13. pi-hash-anchored-edit 0.1.4

• 当前新增加载；替换/注册 hash-anchored read 与 edit 工具。
• 无独立配置文件；核心规则是必须先 read 获取 LINE#HASH anchor，再用 edit 校验 hash 后修改。
• 建议继续按协议使用：hash mismatch 时重新 read，不要强行编辑。

14. @tifan/pi-inline-skills 1.0.3

• 当前新增加载；在 editor 中提供 inline /skill autocomplete，并可把 inline skill token 转成加载指令。
• 无独立配置文件；读取当前注册的 skill commands 和 session custom entries。
• 如果与其它 autocomplete 扩展冲突，再考虑调整加载列表。

15. pi-agentsmd 0.1.0

• 当前新增加载；提供 /init 生成仓库根目录 AGENTS.md，已有文件时需要 /init --force。
• 包自身不会直接写出完整文档，而是向当前模型发送结构化生成提示。
• 安装遥测：PI_OFFLINE 可禁用；PI_TELEMETRY 可覆盖；settings.enableInstallTelemetry === false 时禁用。当前存在安装状态文件 pi-agentsmd-install.json。

16. pi-nano-context 0.1.1

• 无独立配置；替换默认 context meter，显示 sys, pr, assistant, think, tools, free 等分段。
• 如与其它 statusline/context UI 冲突，再考虑移除或调整加载顺序。

17. @agnishc/edb-context-viewer 0.14.3

• 当前新增加载；提供 /context 查看 Stats/System/Tools/Messages/Full 五类上下文信息。
• 无独立配置文件；适合排查 system prompt、工具定义、消息历史和 token 分布。

18. @sting8k/pi-vcc 0.3.15

• 当前新增加载；算法式 conversation compactor，并提供 vcc_recall 与 /pi-vcc-recall。
• 配置文件：~/.pi/agent/pi-vcc-config.json，可用 PI_VCC_CONFIG_PATH 覆盖。
• 当前 overrideDefaultCompaction: true，表示 /compact 和自动阈值 compaction 也由 pi-vcc 处理；debug: false。
• 如需要回到 Pi 默认 LLM compaction，把 overrideDefaultCompaction 改为 false。

19. @tintinweb/pi-subagents 0.10.0

• 当前仍加载该包，而不是旧快照中的 pi-subagents 0.28.0。
• 支持内置 agents、用户 .pi/agents/*.md / ~/.pi/agent/agents/*.md、schedule store 与 worktree isolation。
• schedule 文件路径为 <cwd>/.pi/subagent-schedules/<sessionId>.json。
• 还会读取 Pi global/project settings.json 的 enabledModels 用于模型范围校验。
• 建议按实际使用补充并发、嵌套深度、worktree 策略；涉及 git worktree 的操作需单独征询用户许可。

20. @tintinweb/pi-tasks 0.7.0

• 当前新增加载；提供任务列表、任务执行、后台进程关联与任务 widget。
• 项目配置文件：<cwd>/.pi/tasks-config.json；当前 cwd 未发现该文件。
• 配置项包括 taskScope（memory / session / project）、autoCascade、autoClearCompleted、showAll、maxVisible、hiddenAt、sortOrder 等。
• 当前建议保持默认，只有在任务跨会话保存或自动清理策略明确时再配置。

21. pi-system-prompt 0.1.4

• 当前新增加载；用于查看完整 system prompt、注入工具、guidelines、context files、skills 等。
• 无独立配置文件；仅作为诊断/审计工具使用。

22. pi-bg-run 1.1.4

• 当前新增加载；提供 bg_run, bg_list, bg_kill 和 /bg 面板。
• 配置入口为 global/project settings.json 顶层 bgRun；当前未设置，使用默认。
• 默认项：maxConcurrentJobs: 10, completedTtlMs: 604800000, widgetRefreshMs: 3000, killTimeoutMs: 10000。
• 长任务、测试、训练、批处理建议用 bg_run，避免阻塞当前 tool call；但通知不能中断正在运行的工具调用。

23. pi-aliases 1.0.7

• 当前新增加载；提供命令别名，例如 /clear → /new、/exit → /quit。
• 无独立配置文件；通常不需要维护。

3 个帖子 - 3 位参与者

阅读完整话题