Pi：极简 Agent Harness

┌─────────────────────────────────────────────────────────┐
│                       Agent 产品                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │                    Harness                        │  │
│  │  上下文组装 │ 工具注册 │ 主循环 │ 会话 │ 权限 │ 沙箱 │  │
│  └───────────────────────┬───────────────────────────┘  │
│                          │                              │
│                    ┌─────▼─────┐                        │
│                    │    LLM    │                        │
│                    └───────────┘                        │
└─────────────────────────────────────────────────────────┘

默认给你：
  read / write / edit / bash
  AGENTS.md 项目上下文
  会话树、分支、压缩
  多 Provider 模型切换
  TUI / print / JSON / RPC / SDK

需要自己加：
  子 Agent        → 扩展或第三方 package
  MCP             → pi-mcp 或 MCP 扩展
  权限审批        → 自定义扩展
  Plan Mode       → 工作流扩展
  自定义工具      → TypeScript Extension

┌────────────────────────────────────────────────────┐
│                   pi-coding-agent                  │
│  ┌────────────┐  ┌────────────┐  ┌──────────────┐  │
│  │  TUI 交互   │  │ print/JSON │  │  RPC / SDK   │  │
│  └─────┬──────┘  └─────┬──────┘  └──────┬───────┘  │
│        └───────────────┼────────────────┘          │
│                 ┌──────▼──────┐                    │
│                 │ Agent Core  │                    │
│                 │ 循环/状态/消息│                    │
│                 └──────┬──────┘                    │
│        ┌───────────────┼────────────────┐          │
│  ┌─────▼─────┐  ┌──────▼──────┐  ┌──────▼───────┐  │
│  │ pi-ai     │  │ 四个内置工具 │  │ 扩展/技能包   │  │
│  │ 多 Provider│  │ read/write  │  │ Extensions   │  │
│  └───────────┘  │ edit/bash   │  │ Skills       │  │
│                 └─────────────┘  └──────────────┘  │
└────────────────────────────────────────────────────┘

// 极度简化的 Pi 风格主循环（伪代码）
async function runAgentLoop(session: Session, userInput: string) {
  session.append({ role: "user", content: userInput });

  while (true) {
    // 1. 显式组装上下文：系统提示 + AGENTS.md + 历史 + 工具定义
    const context = contextBuilder.build(session, {
      includeAgentsMd: true,
      includeSkills: session.activeSkills,
      maxTokens: session.settings.contextBudget,
    });

    // 2. 调模型。流式输出，支持 abort 与超时
    const response = await llm.complete({
      messages: context.messages,
      tools: context.tools,
      signal: session.abortSignal,
    });

    session.append(response.message);

    // 3. 没有工具调用，任务结束
    if (!response.toolCalls?.length) break;

    // 4. 逐个执行工具。只读工具可并行，写操作按顺序串行
    const results = await executeTools(response.toolCalls, {
      concurrency: session.settings.toolConcurrency,
      timeoutMs: session.settings.toolTimeoutMs,
      truncate: { head: 200, tail: 200, maxBytes: 32_000 },
    });

    // 5. 工具结果写回会话，进入下一轮
    session.append({ role: "tool", results });

    // 6. 超过轮次或预算，强制收敛
    if (session.steps >= session.settings.maxSteps) {
      session.append({
        role: "system",
        content: "已达到最大步数，请总结当前进展",
      });
      break;
    }
  }

  return session.lastAssistantMessage;
}

session.jsonl
├── header
├── msg(user)            id=a1 parent=null
├── msg(assistant, tool_call) id=a2 parent=a1
├── msg(tool_result)     id=a3 parent=a2
├── msg(assistant)       id=a4 parent=a3      ← 分支点
├── msg(user)            id=b1 parent=a4      ← 分支 1 继续
├── compaction           id=c1 parent=b1
└── msg(user)            id=d1 parent=a4      ← 分支 2（/tree 跳回 a4）

┌──────────────────────────────────────────────┐
│ 1. 系统提示（默认很短；.pi/SYSTEM.md 可替换） │  稳定
│ 2. .pi/APPEND_SYSTEM.md 追加内容              │  半稳定
│ 3. 工具定义（read/write/edit/bash + 扩展工具） │  稳定，顺序固定
│ 4. AGENTS.md（agent 目录 → 父目录 → 当前目录） │  按仓库版本
│ 5. Skills 索引（name + description，≤1024 字符）│  半稳定
│ 6. 会话历史（含工具结果）                      │  增长
│ 7. 当前用户输入 / 排队消息                     │  每轮变化
└──────────────────────────────────────────────┘
        ↑ 缓存断点应放在 3 或 4 的末尾

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "repo_search",
    label: "Repo Search",
    description: "在当前仓库内搜索文本。只读，不修改文件。",
    parameters: Type.Object({
      query: Type.String({ description: "搜索词或正则" }),
      maxResults: Type.Optional(Type.Number({ default: 20 })),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      const res = await runRipgrep(params.query, { signal });
      return {
        content: [{ type: "text", text: truncate(res, 50_000, 2_000) }],
        details: { toolCallId, truncated: res.length > 50_000 },
        isError: false,
      };
    },
  });
}

async function withDeadline<T>(
  fn: (signal: AbortSignal) => Promise<T>,
  ms: number,
) {
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(new Error("tool timeout")), ms);
  try {
    return await fn(ac.signal);
  } finally {
    clearTimeout(timer);
  }
}

type ToolFailure = {
  ok: false;
  code:
    | "INVALID_ARGUMENT"
    | "PERMISSION_DENIED"
    | "NOT_FOUND"
    | "TIMEOUT"
    | "RATE_LIMITED"
    | "UPSTREAM_ERROR";
  message: string; // 写给模型：怎么修
  retryable: boolean; // 写给运行时：是否重试
};

Agent A（worktree A）
  └─ write/report.md
       │ stage：临时文件 + sha256 + mediaType
       ▼
  ArtifactStore.commit()
       │ manifest: id/version/sha256/owner/producedBy/lineage/ttl
       ▼
  对象存储（按 tenant/run 前缀）
       │
       ├─ Agent A 的下一步：artifact_read(id, range)
       ├─ Agent B（另一个 worktree/进程）：按 id 读取 + 鉴权 + checksum
       └─ 清理任务：TTL / 引用计数 / 合规保留

type Artifact = {
  id: string;
  version: number;
  sha256: string;
  mediaType: string;
  bytes: number;
  visibility: "run" | "tenant" | "public";
  owner: { tenantId: string; userId: string };
  producedBy: { sessionId: string; toolCallId: string; agentId?: string };
  inputs?: string[];
  createdAt: string;
  expiresAt?: string;
};

handoff = {
    "artifact_id": art.id,
    "sha256": art.sha256,
    "media_type": art.mediaType,
    "read_with": "artifact_read(id, offset, length)",
    "acceptance": {"schema": "report.v2", "must_parse": True},
}

type Route = {
  provider: string;
  model: string;
  maxContext: number;
  tier: "fast" | "standard" | "deep";
};

async function routeAndCall(req: ModelRequest, ladder: Route[]) {
  for (const r of ladder) {
    if (req.estimatedTokens > r.maxContext) continue;
    if (breaker(r).isOpen()) continue;
    try {
      return await piAi.complete({ ...adapt(req, r), signal: req.signal });
    } catch (e) {
      if (!retryable(e)) throw e;
      breaker(r).recordFailure();
      await sleep(backoffWithJitter(r));
    }
  }
  throw new Error("all routes failed");
}

// ~/.pi/extensions/jira.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function jiraExtension(pi: ExtensionAPI) {
  pi.registerTool({
    name: "jira_search",
    description:
      "当用户需要查询 Jira 工单、缺陷或需求状态时使用。不要用它查询代码或文档。",
    parameters: {
      type: "object",
      properties: {
        jql: {
          type: "string",
          description: "JQL 查询语句，例如 project = FE AND status = Open",
        },
        limit: { type: "number", description: "返回条数，默认 10，最大 50" },
      },
      required: ["jql"],
      additionalProperties: false,
    },
    async execute({ jql, limit = 10 }) {
      const res = await fetch(`${process.env.JIRA_BASE}/rest/api/3/search`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.JIRA_TOKEN}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ jql, maxResults: Math.min(limit, 50) }),
      });
      if (!res.ok) {
        return {
          ok: false,
          error: `Jira 查询失败：HTTP ${res.status}`,
          retryable: res.status >= 500,
        };
      }
      return { ok: true, data: await res.json() };
    },
  });
}

你要的是什么？
├─ 马上写代码、少折腾
│   ├─ 团队已经用 Anthropic 生态        → Claude Code
│   └─ 团队偏 OpenAI / 需要开源可控     → Codex CLI
├─ 完全掌控上下文与循环
│   ├─ 只跑单 Agent、能接受自己补生产化 → Pi
│   └─ 需要插件化、可回放、企业多租户   → DeepSeek Harness
├─ 复杂业务流程、多 Agent 图编排        → LangGraph
└─ 只是想接个模型做 Chat                → 直接用官方 SDK

[稳定前缀] 系统提示 + 工具定义 + AGENTS.md
[半稳定]   项目结构摘要、当前任务计划
[高频变化] 用户消息、工具结果
                 ↑ 缓存断点应放在这里之前

// 概念示意：把 Pi 的事件挂到 OTel span 上
const runSpan = tracer.startSpan("agent.run", {
  attributes: { "gen_ai.operation.name": "invoke_agent" },
});

const stepSpan = tracer.startSpan(
  "agent.step",
  { attributes: { "agent.step.index": i } },
  runSpan,
);
const toolSpan = tracer.startSpan(
  `tool.${toolName}`,
  {
    attributes: {
      "gen_ai.tool.name": toolName,
      "gen_ai.tool.call.id": toolCallId,
    },
  },
  stepSpan,
);