第5章 核心对象与配置系统

第5章 核心对象与配置系统

5.1 Agent（底层运行时）/ Session（编码场景封装）/ SessionManager（存储）三级对象

📌 网传版本里的 HarnessAgent 不属于 Pi 本体（那是 Vercel 适配器的类名，见第一部分 1.5）。Pi 本体真实的核心对象体系是下面这三级：

真实对象	来源包	作用
Agent	pi-agent-core	最底层的代理实例，持有 systemPrompt、model，支持 subscribe() 订阅事件、prompt() 发起任务------"代理实例"概念最贴近的真实对应物
createAgentSession() / Session	pi-coding-agent	面向编码场景封装好的会话对象，内置 CLI 使用的工具集、会话持久化，日常编程集成时最常打交道的对象
SessionManager	pi-coding-agent	会话存储管理（SessionManager.inMemory() 临时会话，或落盘到 JSONL）
ModelRuntime / ModelRegistry	pi-coding-agent	负责模型解析、鉴权信息关联

初始化示例（最底层）：

import { Agent } from '@earendil-works/pi-agent-core';
import { getModel } from '@earendil-works/pi-ai';

const agent = new Agent({
  initialState: {
    systemPrompt: '你是一个乐于助人的编码助手。',
    model: getModel('anthropic', 'claude-sonnet-4-20250514'),
  },
});

编码场景更常用的封装：

import { createAgentSession, ModelRuntime, SessionManager } from '@earendil-works/pi-coding-agent';

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

5.2 分层配置：全局 ~/.pi/agent/settings.json + 项目级 .pi/settings.json

📌 "PI 内核配置"真实对应的是分层设置系统，不是传给某个构造函数的配置对象。

配置文件	作用域
~/.pi/agent/settings.json	全局配置，对所有项目生效
.pi/settings.json	项目级配置，覆盖全局配置（对象字段做合并而非整体覆盖）

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark"
}

配置系统覆盖的常用字段类别一览（各字段详细含义分散在后续章节展开）：

分类	关键字段
模型与思考	defaultProvider、defaultModel、defaultThinkingLevel、thinkingBudgets
项目信任	defaultProjectTrust（详见第四部分）
压缩	compaction.enabled、compaction.reserveTokens、compaction.keepRecentTokens
重试	retry.enabled、retry.maxRetries、retry.baseDelayMs、retry.provider.*
资源加载	packages、extensions、skills、prompts、enableSkillCommands
会话	sessionDir
Shell	shellPath

---