pi-cli-workspace

Pi CLI 和工作区

仅根据下方列出的 pi-mono/ 源码作答。如果目录中没有相关信息，请说明无法从语料中确认。

依据（按顺序阅读）

1. pi-mono/packages/coding-agent/README.md — 产品界面、命令、自定义。
2. pi-mono/packages/coding-agent/docs/skills.md — 技能位置、/skill:name、frontmatter、名称冲突。
3. pi-mono/packages/coding-agent/docs/settings.md — 设置位置和键。
4. pi-mono/AGENTS.md — 编辑 pi-mono 本身时的维护规则。
5. pi-mono/packages/coding-agent/docs/compaction.md — 自动压缩触发条件、截断点算法、reserveTokens/keepRecentTokens 设置、连续压缩、分支摘要。
6. pi-mono/packages/coding-agent/docs/session.md — JSONL 会话格式、~/.pi/agent/sessions/ 路径、条目类型（message、compaction、branch_summary、custom、label）、buildSessionContext() 组装过程。
7. pi-mono/packages/coding-agent/docs/tree.md — /tree 与 /fork 的区别、分支导航、摘要选项、树形界面快捷键。
8. pi-mono/packages/coding-agent/docs/providers.md — 订阅 OAuth（/login）、API 密钥提供商、auth.json、环境变量凭据表、云提供商（Azure、Bedrock、Vertex）。
9. pi-mono/packages/coding-agent/docs/models.md — Ollama/vLLM/LM Studio 的 models.json、compat 标志、modelOverrides、提供商级配置。
10. pi-mono/packages/coding-agent/docs/custom-provider.md — 通过 registerProvider() 注册扩展提供商、OAuth 流程、代理模式。
11. pi-mono/packages/coding-agent/docs/terminal-setup.md — Kitty 键盘协议、Ghostty/iTerm/终端快捷键注意事项。
12. pi-mono/packages/coding-agent/docs/tmux.md — tmux extended-keys / csi-u，以便在 pi 中使用修饰键。
13. pi-mono/packages/coding-agent/docs/windows.md — Windows bash 查找顺序（shellPath 设置、Git Bash、PATH）。
14. pi-mono/packages/coding-agent/docs/termux.md — 通过 Termux 在 Android 上运行 pi（安装、剪贴板、存储）。
15. pi-mono/packages/coding-agent/docs/shell-aliases.md — 非交互式 bash 和 shellCommandPrefix，用于展开 dotfiles 中定义的别名。
16. pi-mono/packages/coding-agent/docs/development.md — 本地开发设置、pi-test.sh、通过 piConfig 派生/重塑品牌、测试命令。
17. 实现（用于确定优先级和提示词接线）：
    • pi-mono/packages/coding-agent/src/core/package-manager.ts — resourcePrecedenceRank 注释块（排序意图）。
    • pi-mono/packages/coding-agent/src/core/resource-loader.ts — reload() 中的技能路径合并（cliEnabledSkills、enabledSkills、additionalSkillPaths）。
    • pi-mono/packages/coding-agent/src/core/skills.ts — loadSkills、formatSkillsForPrompt、名称冲突处理。
    • pi-mono/packages/coding-agent/src/core/system-prompt.ts — 默认 harness 文本以及技能 XML 的 hasRead 门控。
    • pi-mono/packages/coding-agent/src/core/agent-session.ts — _expandSkillCommand 将 /skill:name 正文内联。
18. pi-mono/packages/coding-agent/README.md §Editor — @ 模糊搜索、Tab 补全、Ctrl+V 粘贴图片、!/!! bash 命令。
19. pi-mono/packages/coding-agent/README.md §Message Queue — steering（Enter）与 follow-up（Alt+Enter）、steeringMode/followUpMode/transport 设置。
20. pi-mono/packages/coding-agent/README.md §Modes、§CLI Reference — 交互模式、-p/--print、--mode json、--mode rpc、管道输入的 stdin。
21. pi-mono/packages/coding-agent/README.md §CLI Reference — 完整标志表、@files、--tools、--no-tools、--no-extensions、--no-skills、--no-prompt-templates、--no-themes、资源控制。
22. pi-mono/packages/coding-agent/README.md §Environment Variables — PI_CODING_AGENT_DIR、PI_PACKAGE_DIR、PI_SKIP_VERSION_CHECK、PI_CACHE_RETENTION、VISUAL/EDITOR。
23. pi-mono/packages/coding-agent/README.md §Philosophy — 核心有意省略的功能（不包含 MCP、子 Agent、权限弹窗、计划模式、内置待办事项、后台 bash）；所有功能都可以通过扩展实现。

不变量

• 技能名称冲突：先注册的名称优先；后续路径会输出冲突诊断信息（pi-mono/packages/coding-agent/src/core/skills.ts）。路径顺序在 resource-loader.ts 中组装，然后传入 loadSkills。
• 资源优先级（数值越小，在已排序的包管理器列表中越靠前）：项目本地（0）、项目自动发现（1）、用户本地（2）、用户自动发现（3）、包（4）——pi-mono/packages/coding-agent/src/core/package-manager.ts。
• 合并后的技能路径：mergePaths([...cliEnabledSkills, ...enabledSkills], additionalSkillPaths)——CLI 路径排在包管理器列表之前；参见 pi-mono/packages/coding-agent/src/core/resource-loader.ts。
• 只有选定的工具中包含 read 工具时，才会将 <available_skills> 附加到系统提示词中——pi-mono/packages/coding-agent/src/core/system-prompt.ts。
• 默认系统提示词已指引模型查看打包的文档路径（readmePath、docsPath、示例）——pi-mono/packages/coding-agent/src/core/system-prompt.ts。此技能补充的是工作区和优先级详情，而不是重复 README。
• 会话格式版本为 v3（基于树结构的 id/parentId）；buildSessionContext 会组装压缩摘要、分支摘要，以及压缩点之后的消息——参见 pi-mono/packages/coding-agent/docs/session.md。
• 压缩切分点的选择会避免拆分工具结果；firstKeptEntryId 用于链接连续压缩——参见 pi-mono/packages/coding-agent/docs/compaction.md。
• 凭据解析顺序：--api-key 标志 > auth.json > 环境变量 > models.json 自定义密钥——参见 pi-mono/packages/coding-agent/docs/providers.md。
• SYSTEM.md / APPEND_SYSTEM.md：使用 .pi/SYSTEM.md（项目级）或 ~/.pi/agent/SYSTEM.md（全局级）替换默认系统提示词。在相同位置使用 APPEND_SYSTEM.md 可追加内容，而不替换默认提示词。覆盖后仍会附加上下文文件和技能——pi-mono/packages/coding-agent/README.md §上下文文件。
• 消息队列：按 Enter 会排入一条引导消息（在工具调用之间传递）；按 Alt+Enter 会排入一条后续消息（Agent 完成所有工作后传递）。按 Escape 中止；按 Alt+Up 取回排队的消息。设置：steeringMode 和 followUpMode（默认值为 "one-at-a-time"，也可设为 "all"）；transport（"sse"、"websocket"、"auto"）——pi-mono/packages/coding-agent/README.md §消息队列，pi-mono/packages/coding-agent/docs/settings.md。
• 内置工具：默认提供四个：read、bash、edit、write。其他可用工具：grep、find、ls。可通过 --tools <list> 控制（例如，使用 --tools read,grep,find,ls 实现只读）和 --no-tools（禁用所有内置工具；扩展工具仍可用）——pi-mono/packages/coding-agent/README.md §工具选项。
• 编辑器功能：@ 可模糊搜索项目文件；Tab 可补全路径；Ctrl+V 可粘贴图片（Windows 上使用 Alt+V）；!command 会运行命令并将输出发送给大模型；!!command 会运行命令但不发送输出——pi-mono/packages/coding-agent/README.md §编辑器，pi-mono/packages/coding-agent/docs/keybindings.md。
• 打印模式：使用 -p/--print 可将非交互式输出写入 stdout。可读取管道传入的 stdin：cat README.md | pi -p "Summarize"。结合 --mode json 可输出 JSON 行——pi-mono/packages/coding-agent/README.md §模式。
• CLI 会话标志：-c/--continue（最近的会话）、-r/--resume（浏览/选择）、--session <path>（指定文件或部分 UUID）、--fork <path>（从 CLI 分叉）、--no-session（临时会话）、--session-dir <dir>（自定义存储目录）——pi-mono/packages/coding-agent/README.md §会话选项。
• @文件 CLI 参数：在 CLI 中为文件添加 @ 前缀：pi @screenshot.png "What's in this?"、pi @code.ts @test.ts "Review"。这些内容会作为初始消息的一部分——pi-mono/packages/coding-agent/README.md §文件参数。
• 资源控制标志：--no-extensions、--no-skills、--no-prompt-templates、--no-themes 可禁用自动发现。-e/--extension、--skill、--prompt-template、--theme 可用于显式加载。将 --no-* 与显式标志组合使用，可实现精确控制（例如，--no-extensions -e ./my-ext.ts）——pi-mono/packages/coding-agent/README.md §资源选项。
• 模型简写：--model provider/id（例如，openai/gpt-4o）、--model name:thinking（例如，sonnet:high）、--models <patterns> 用于通过 Ctrl+P 切换模型、--list-models——pi-mono/packages/coding-agent/README.md §模型选项。
• 斜杠命令（完整交互式列表）：/login、/logout、/model、/scoped-models、/settings、/resume、/new、/name、/session、/tree、/fork、/compact、/copy、/export、/share、/reload、/hotkeys、/changelog、/quit。扩展可注册自定义命令；技能可提供 /skill:name；提示词模板可通过 /templatename 展开——pi-mono/packages/coding-agent/README.md §命令。
• 环境变量：PI_CODING_AGENT_DIR（覆盖配置目录）、PI_PACKAGE_DIR（覆盖包目录）、PI_SKIP_VERSION_CHECK、PI_CACHE_RETENTION（设为 long 可延长提示词缓存保留时间）、VISUAL/EDITOR（Ctrl+G 使用的外部编辑器）——pi-mono/packages/coding-agent/README.md §环境变量。
• 设计理念（pi 刻意省略的功能）：不提供 MCP（使用 CLI 工具或扩展）、不提供子 Agent（使用 tmux 或扩展）、不提供权限弹窗（使用容器或扩展）、不提供计划模式（使用文件或扩展）、不提供内置待办事项、不提供后台 bash（使用 tmux）。所有功能都可通过扩展实现——pi-mono/packages/coding-agent/README.md §设计理念。

工作流

• 查找技能的发现位置：遍历 docs/skills.md 中的位置，然后交叉核对 package-manager.ts 的自动发现机制和 settings.json 中的 skills 数组。
• 说明遮蔽行为：结合 resourcePrecedenceRank 排序以及 mergePaths / loadSkills 的“名称优先”规则，只使用文件引用。
• 用户强制加载：/skill:name 展开机制 — pi-mono/packages/coding-agent/src/core/agent-session.ts。
• 调试压缩：阅读 compaction.md 算法；检查 settings.json 中的 reserveTokens / keepRecentTokens；通过 firstKeptEntryId 跟踪连续压缩。
• 添加自定义模型：参照 models.md 中适用于 Ollama/vLLM/LM Studio 的最简示例；对于非标准的 OpenAI 兼容服务，检查 compat 标志。
• 会话考古：使用 session.md 中的 switch 示例解析 .jsonl；按照 tree.md 中的说明，通过 /tree 浏览分支。
• 配置提供商：查看 providers.md，了解订阅 OAuth（/login）与 API 密钥流程；参阅 auth.json 布局和环境变量表。
• 平台设置：对于 tmux，阅读 tmux.md（extended-keys）；对于 Windows，阅读 windows.md（shellPath）；对于 Android，阅读 termux.md；对于终端问题，阅读 terminal-setup.md。
• Shell 别名：阅读 shell-aliases.md 中的 shellCommandPrefix，让 pi 的 bash 工具能够识别点文件中的别名。
• 从源代码开发 pi：阅读 development.md，了解克隆、构建、测试和 pi-test.sh 运行器。
• 控制工具：使用 --tools read,grep,find,ls 启用只读模式；使用 --no-tools 禁用所有内置工具（扩展工具仍可用）。默认值为 read,bash,edit,write。
• 非交互模式：使用 pi -p "prompt"，或使用 cat file | pi -p "Summarize" 运行 CI/脚本。搭配 --mode json 可输出机器可读的 JSON 行格式。
• 自定义系统提示词：在项目中放置 .pi/SYSTEM.md，或在全局范围内放置 ~/.pi/agent/SYSTEM.md，以替换默认提示词。在相同位置使用 APPEND_SYSTEM.md 可追加内容而不替换。

反模式

• 不要臆造 MCP 或子 Agent 是“核心内置”行为；查看 pi-mono/packages/coding-agent/README.md 的理念部分，了解核心未包含哪些内容。
• 未引用 resource-loader.ts 和 skills.ts 时，不要声称合并行为的具体细节。
• 不要凭记忆描述压缩截断点的行为；请引用 compaction.md 的算法部分。
• 不要猜测凭据解析顺序；请引用 providers.md 中的确切优先级。