返回课程首页

附录 G

配置与环境速查

Provider、认证、模型、项目、用户与资源配置。

源码基线：Pi v0.82.0 · commit 518855d

1. 配置分层

Process/CLI fixed input
→ User/Agent directory
→ Workspace/CWD settings
→ Project resources（受 Trust 控制）
→ Session entries/state
→ Run/Turn overrides

越靠后越接近当前运行，但不是所有字段都简单“后者覆盖前者”。具体合并由 SettingsManager、 ResourceLoader、ModelRuntime 与 AgentSession 分别负责。

2. CWD 与 Agent Directory

  • cwd：当前 Workspace/Session 工作目录；
  • agentDir：用户级 Pi 配置、认证、模型与资源目录。

切换 Session CWD 时要重建 CWD-bound Services，不能只修改一个字符串。Runtime Factory 必须把 传入的 agentDir 继续传给 Services。

3. Provider 与 Model

选择模型至少涉及：

  • Provider ID；
  • Model ID；
  • API Type；
  • Base URL；
  • Auth；
  • Context Window；
  • Thinking/Image/Tool 能力；
  • Cost/Max Tokens。

模型切换会追加 Session model_change Entry，并更新相应 Settings；不是改写 JSONL Header。

4. Auth

认证数据应进入：

  • ModelRuntime/Auth Storage；
  • OS Credential Store 或受控文件；
  • Provider 的 Resolve/Refresh 流程。

不要进入：

  • Prompt；
  • Custom Message；
  • ToolResult Content；
  • Desktop Serializable Store；
  • 普通日志。

完整 Provider 的 ApiKeyAuth、OAuthAuth 与 Legacy OAuth 契约不同，见第 28 章。

5. Project Trust

正确流程：

untrusted settings
→ load global/CLI pre-trust extensions
→ project_trust decision
→ full reload project settings/resources/extensions

简单 createAgentSession() 不自动弹桌面 Trust Dialog。SDK 宿主通过 createAgentSessionServices({ resourceLoaderReloadOptions: { resolveProjectTrust } })，或 自建带 Resolver 的 ResourceLoader 再传给 createAgentSession() 接线。

Trust Project 不等于 OS Sandbox，也不等于所有 Package 均可信。

6. Resource 来源

ResourceLoader 可组合：

  • 用户级目录；
  • 项目级目录；
  • Package；
  • CLI/宿主额外路径；
  • Extension 动态发现路径；
  • Inline Extension。

项目来源受 Trust；冲突与错误通过各 Resource Result 的 Diagnostics 暴露。

7. Skills/Prompt/Extension 开关

宿主可以：

  • 增加额外路径；
  • 禁用某类资源；
  • 注入 Inline Extension；
  • 限制 Built-in Tool；
  • 提供 Custom Tool；
  • 设置 Extension Flag。

Tool tools 是全工具 Allowlist，Custom Tool 也会被它过滤；若指定 tools: ["read", "controlled_write"]，Custom Tool 的实际名称必须在列表内。

8. Tool 环境

模型可调用的 Bash Tool 默认可注入：

PI_SESSION_ID
PI_SESSION_FILE       # 仅持久 Session 有文件时
PI_PROVIDER
PI_MODEL
PI_REASONING_LEVEL

可用 exposeSessionEnvironment: false 关闭。这不清除进程继承的其他环境变量；生产 Sandbox 仍需 Env Allowlist。

宿主另行实现的直接 Shell 路径不自动获得上述模型 Bash Tool 环境。

9. RPC Worker 启动配置

宿主要固定：

  • Worker Binary/Version；
  • CWD；
  • Session/Session Directory；
  • Provider/Model；
  • Trust Override/Policy；
  • Environment Allowlist；
  • Filesystem/Network Sandbox；
  • stdin/stdout/stderr；
  • Restart Budget。

不要从任意系统 PATH 发现未知版本 Pi。当前 RPC 没有内置 Version/Capabilities Handshake。

10. 多窗口配置

不要把 UI Preference 写进 Agent Session Entry，除非它确实属于 Agent Branch 语义。建议：

数据 保存位置
Window Layout App Store
Runtime Owner App Runtime Registry
Model Change Session Entry/Settings
Branch Tool State Tool Details/Custom Entry
API Token Credential Store
Skill/Extension Paths Settings/Resource Config

11. 诊断来源

  • getExtensions().errors；
  • getSkills().diagnostics；
  • getPrompts().diagnostics；
  • getThemes().diagnostics；
  • runtime.diagnostics；
  • runtime.modelFallbackMessage；
  • Session/Replacement Exception；
  • RPC Parse/Exit；
  • Host Policy/Audit。

没有一个单独的 runtime.diagnostics 能覆盖全部。

12. 配置变更检查

  • 是否需要 Reload；
  • 是否改变 Trust；
  • 是否重建 CWD-bound Services；
  • 是否使旧 Extension Context 失效；
  • 是否改变 Tool Allowlist；
  • 是否影响 Session 恢复；
  • 是否需要兼容迁移；
  • 是否会把 Secret 暴露给模型或日志。