# s10: Runtime Modes — 同一个 core，不同的展示

> *core 只管产生，怎么展示外层说了算。*
> **Pi 边界**：运行方式边界 —— core 产生事件，展示方式是外层的事，换展示不改 core。

[上一节：s09](../s09_extension_runtime/) → `s10` → [下一节：s11](../s11_trust_and_execution_boundary/)

---

## 问题

前面几节里，core 一产生结果就直接打印出来——展示方式写死在代码里。

但"展示"这件事，不同场景要的不一样：给人看，要人类可读的文本；给别的程序看，要结构化的 JSON；以后可能还要 GUI 渲染。如果展示方式写死在 core 里，每换一种就得复制或改动 core。

core 只该管**产生**什么，**怎么展示**应该分离出去。

---

## 解决方案

core 把要做的事变成一批 `RuntimeEvent`，外层用一个 `RuntimeMode` 决定怎么展示。

```text
createDemoRuntimeEvents()  →  RuntimeEvent[]  →  RuntimeMode.render()
```

同一个 core、同一批事件，接不同的 mode 就有不同输出：

| mode | 展示成 |
| --- | --- |
| `PrintMode` | 人类可读文本（只打印 message） |
| `JsonMode` | 结构化 JSON（每事件一行） |

> **[R7 收获]** 回想 s01：那时候 core 不直接 `console.log`，而是走了一层 `Output.log`。那是一个最小的"输出抽象"种子。s10 把它正式化、可切换了——同一个 core 的事件，想打印就 PrintMode，想 JSON 就 JsonMode，core 一个字都不用改。

这里不是替换 s01-s09 的 `runEventedToolLoop`。为了让本节输出短一点，demo 用 `createDemoRuntimeEvents()` 造一批最小事件；真正的主线里，这批事件来自前面已经累积出来的 core。

---

## 工作原理

**先准备一批事件。** `createDemoRuntimeEvents` 把输入变成一批最小 RuntimeEvent。它只是本节的演示事件源，不是新的主循环。

```ts
export function createDemoRuntimeEvents(input: string): RuntimeEvent[] {
  return [
    { type: "message", content: `收到：${input}` },
    { type: "done" },
  ];
}
```

**mode 消费事件。** RuntimeMode 只有一个方法 `render`。PrintMode 挑出 message 打印文本；JsonMode 把每个事件序列化成 JSON。

```ts
export type RuntimeMode = { render(events: RuntimeEvent[]): void };

export class PrintMode implements RuntimeMode {
  render(events) {
    for (const event of events) {
      if (event.type === "message") console.log(event.content);
    }
  }
}

export class JsonMode implements RuntimeMode {
  render(events) {
    for (const event of events) console.log(JSON.stringify(event));
  }
}
```

> 这一节真正建立的是**运行方式边界**：core 产生事件，展示是外层 mode 的事。RuntimeEvent 是 core 对外的"输出语言"，mode 是"翻译器"。换展示方式只是换 mode，core 不动——这正是 s01 那层 Output 抽象要长成的样子。

---

## 试一下

运行：

```sh
npm run s10
```

输出类似：

```text
s10: Runtime Modes

[print mode]
收到：你好，mini Pi

[json mode]
{"type":"message","content":"收到：你好，mini Pi"}
{"type":"done"}
```

观察重点：两种输出来自**同一批事件**——`[print mode]` 只显示了 message 内容，`[json mode]` 把每个事件都序列化了，包括 `done`。

---

## 接入主线

s10 在 s09 上累积。相对 s09 的变更：

| 组件 | s09 | s10 |
| --- | --- | --- |
| 新增类/函数 | — | `createDemoRuntimeEvents`（演示事件源）/ `PrintMode` / `JsonMode` |
| 新增类型 | — | `RuntimeMode` |
| 输出抽象 | `Output.log`（s01 起，逐行） | `RuntimeMode.render`（可切换展示） |
| 主循环 / `ProviderInput` | — | **不变**（纯新增，无 U1 升级） |

**焊接点**：前面主线产出的 `RuntimeEvent[]` 交给 `RuntimeMode.render`；本节 demo 只用 `createDemoRuntimeEvents` 代替真实事件源。`PrintMode` / `JsonMode` 各自 `render` 同一批事件，core 与展示彻底分开。

---

## 接下来

core 会接触本地项目：要加载项目资料，也可能要执行本地动作。这两件事的风险不一样，得分开管。

下一节会把"能不能加载资料"和"能不能执行动作"拆成两个独立的开关。

进入下一节：[s11](../s11_trust_and_execution_boundary/)。

---

<details>
<summary>Pi 源码溯源：四种 AppMode 和自动分流</summary>

教学版两种 mode（Print/Json）消费同一批事件。Pi 的 `packages/coding-agent` 有四种运行模式，按终端环境自动分流。

### 源码在哪

- `packages/coding-agent/src/cli/args.ts:10` — `AppMode` 类型
- `packages/coding-agent/src/main.ts:98` — `resolveAppMode`（分流逻辑）
- `packages/coding-agent/src/main.ts:768` — 各模式入口
- `packages/coding-agent/src/modes/print-mode.ts` — print 模式

### 四种模式

```ts
type AppMode = "interactive" | "print" | "json" | "rpc";
```

| 模式 | 什么时候用 | 怎么输出 |
| --- | --- | --- |
| interactive | stdin 和 stdout 都是 TTY | TUI 差分渲染（`pi-tui`） |
| print | `--print` 或管道输入 | 纯文本，跑完退出 |
| json | `--mode json` | 结构化 JSON 事件流 |
| rpc | `--mode rpc` | JSON-RPC 接口，给编辑器/工具集成 |

教学版的 PrintMode/JsonMode 是 print 和 json 两种的极简版。

### 自动分流

`resolveAppMode`（`main.ts:98`）的判定顺序：

```ts
function resolveAppMode(parsed, stdinIsTTY, stdoutIsTTY): AppMode {
  if (parsed.mode === "rpc") return "rpc";      // 显式 rpc 最优先
  if (parsed.mode === "json") return "json";    // 显式 json
  if (parsed.print || !stdinIsTTY || !stdoutIsTTY) return "print";  // 管道自动 print
  return "interactive";                          // 默认交互
}
```

关键设计：**管道自动降级到 print**。把 pi 接到管道（`echo hi | pi`）时，它检测到 stdin 不是 TTY，自动用 print 模式——不会傻乎乎起一个 TUI。教学版没有这个自动检测。

### TUI 用差分渲染

interactive 模式（`main.ts:770`）用 `@earendil-works/pi-tui`，这是个专门的终端 UI 库，做差分渲染（只重绘变化的部分）——流式输出时不会闪烁。教学版的 mode 只是 console.log，没有渲染层。

### 一句话

教学版的 RuntimeMode 立的是"core 产事件、外层决定展示"。Pi 把它坐实成四种 AppMode + 管道自动降级 + TUI 差分渲染。同一个 agent core，接 TTY 是交互式、接管道是 print、接工具是 json/rpc——core 一个字不用改。

</details>