问题 vs 方案 为什么需要 Harness

分层目标（同场三档） 按需取用

• 会用：跑通 pi --print 最小闭环，理解消息与工具流
• 会选型：为自建网关选 Api/compat，判断何时用 Harness
• 会扩展：写一个 tool_call 审计拦截 + 一个自定义 Tool

兜底 混合兜底：有 ANTHROPIC_API_KEY 等走真实模型，无 Key 自动走 faux + 本地 mock，全程可动手。

Message 模型 packages/ai/src/types.ts:422

type Message = UserMessage | AssistantMessage | ToolResultMessage;
// AgentMessage 支持通过声明合并扩展自定义类型：
type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
// coding-agent 的 CustomMessage 即由此注入
type Context = { systemPrompt?: string; messages: Message[]; tools?: Tool[] };

设计意图：低层循环无需理解 CustomMessage，convertToLlm 在 LLM 边界过滤。

Session Entry DAG 可 fork 的关键

Entry { id: uuidv7, parentId, type: message|custom|compaction|branchSummary }
branchTip(name) -> tipId          // 分支叶指针（values.ts）
scanBranch({ start: tipId, order: "newestFirst"|"oldestFirst" })

每条 Entry 追加写入，branchTip 移动即分支；fork(entryId) 复制历史前缀。

现成品 #2 — DAG 来自版本控制思想的拼贴

循环不变量 agent-loop.ts:156

• 内层：只要有 toolCalls 或 steering，继续下一 turn。
• 外层：内层结束后再问 getFollowUpMessages()，有则继续。
• prepareNextTurn 前条件性再 poll steering，避免 one-at-a-time 在同一 turn 吞两条。
• stopReason=="length" 时当批次工具调用视为“可能截断”，全部失败重试（保守但安全）。

并发契约 agent-loop.ts:409

单工具可覆为 executionMode:"sequential"（如写文件）；terminate 需批次全体一致才终止。

Hands-on 1 · 最小闭环（faux，无需 Key）

import { Agent } from "@earendil-works/pi-agent-core";
import { faux } from "@earendil-works/pi-ai/providers/faux";
const model = { id:"faux", api:"openai-completions", provider:"faux", baseUrl:"",
  reasoning:false, input:["text"], cost:{input:0,output:0,cacheRead:0,cacheWrite:0},
  contextWindow:8192, maxTokens:1024 };
const agent = new Agent({ streamFn: faux.streamSimple, initialState:{ model, messages:[] }});
agent.subscribe(e => console.log(e.type)); // agent_start → turn_start → message_* → agent_end
await agent.prompt("hi");
await agent.waitForIdle();

Notebook §3 有可运行版（/tmp/h1.mjs + npx tsx）；有 Key 者将 fauxModel 替换为真实 Model 对比延迟与 usage。

分层与加载 tree-shake 友好

providers/anthropic.ts → api/anthropic-messages.ts
providers/openai.ts    → api/openai-completions.ts
                                  ↘ api/openai-responses.ts
api/lazy.ts 按需加载，避免全量打包
index.ts 仅导出 core，无副作用

Model 关键字段 types.ts:845

Model<TApi> {
  id, api: TApi, provider, baseUrl,
  reasoning: boolean,
  thinkingLevelMap?: Record<ThinkingLevel, string|null>,
  input: ("text"|"image")[],
  cost: { input, output, cacheRead, cacheWrite, tiers? },
  contextWindow, maxTokens,
  compat?: OpenAICompat | AnthropicCompat | BedrockCompat
}

兼容开关（接入网关的抓手） 节选

Hands-on 2 · 注册自建 Provider

export default function(pi){
  pi.registerProvider("my-proxy", {
    baseUrl:"https://proxy.example.com", // 或 http://localhost:8787
    api:"anthropic-messages",
    models:[{ id:"my-model", name:"My", reasoning:false, input:["text"],
      cost:{input:0,output:0,cacheRead:0,cacheWrite:0}, contextWindow:200_000, maxTokens:8192 }]
  });
}
// 落盘：~/.pi/agent/extensions/my-proxy/index.ts → 重启后 /model 可见

AgentSession 的精确职责 core/agent-session.ts:306

• prompt()：命令拦截 → input handlers → Skill/Template 展开 → 校验 model/auth → before_agent_start 注入 CustomMessage → runAgentLoop
• _handlePostAgentRun：可重试错误 → 溢出压缩 → 队列续跑（有其一则 continue()）
• _handleAgentEvent：message_end 双写 AgentState.messages + SessionManager JSONL；turn_end 才 flush CustomMessage（避免夹在 tool_call/result 间）

压缩三类 reason

Hands-on 3 · 观察与操作

pi --print "在 /tmp/pi-ws 创建 hello.txt"
ls -lh ~/.pi/agent/sessions/*.jsonl
head -1 ~/.pi/agent/sessions/*.jsonl | python3 -m json.tool
# fork / 导航（扩展命令或 SDK）
# pi --help | grep -E "fork|navigate"

Notebook §5：若本地有会话，Python 直接解析 JSONL 并还原为树；否则用模拟数据演示。

事件拼贴（精确列表） types.ts:1252

project_trust resources_discover session_start session_before_* context before_provider_request before_agent_start agent_start/end/settled turn_* message_* tool_execution_* tool_call tool_result model_select input user_bash

要点：tool_call 的 input 就地可变，多扩展链式改同一对象；block 任一即阻断；单扩展异常仅产 handler_error。

export default function(pi){
  pi.on("tool_call", e=>{
    if(e.toolName==="bash" && e.input.command.includes("rm -rf /"))
      return { block:true, reason:"Refusing destructive command" };
  });
  pi.registerTool(defineTool({
    name:"jira", description:"Fetch Jira",
    parameters: Type.Object({ key: Type.String() }),
    execute: async (id,{key})=>({ content:[{type:"text", text:key}], details:{} })
  }));
}

8 内置工具（均可被覆写）

UI 覆盖能力

select/confirm/input/notify · setWidget/setFooter/setHeader · custom(Component) · setEditorComponent · theme。扩展自带 TUI，无需改主程序。

check 门禁 package.json:21, AGENTS.md

biome check --write --error-on-warnings .
+ check:pinned-deps / runtime-deps / ts-imports / entry-graphs
+ check:shrinkwrap / install-lock
+ tsgo --noEmit
+ check:browser-smoke
# 每次改代码后必跑，未全绿不提交

供应链（精确）

• save-exact=true + min-release-age=2（避同日投毒）
• npm-shrinkwrap.json + install-lock/ 锁定传递依赖
• --ignore-scripts 安装（CI 与 pi update --self）
• npm audit 定时 + 生命周期脚本 allowlist
• release:local 隔离 npm/Bun 冒烟

演进路线 wulutech/08

选题（抽签盒决定）

Track A · 工程化：为团队 pi 增加声明式权限（allow/deny）+ npm run check 门禁。
Track B · 扩展：Jira 关联扩展：tool_result 注入链接或 jira Tool。
Track C · 会话产品化：基于 SessionManager 的“会话回放 HTML 导出”后处理脚本（参考 core/export-html/）。

DADA 抽签：随机选题，精确交付

评审（精确权重）

产出

每组 1 个可运行扩展或脚本 + 1 张架构拼贴（可用本页 Mermaid 导出）+ 1 次 5 分钟路演。投票选“最佳现成品”。