# sema-core

> **本文件是消费者集成文档(usage),主要读者是 AI。** 内容力求精确、完整、可直接执行：确切的类型签名、所有导出、
> 事件协议、状态语义、可复制的集成代码、安全契约。看完即可独立集成，不需要再读源码。
>
> 🧭 **要理解架构 / 编译发版 / 当前 bug / 路线图与难点,或刚接手本仓?先读 [`docs/HANDOFF.md`](docs/HANDOFF.md)(唯一权威入口)。** 本 README 只覆盖"如何调用引擎"。

一个**无状态、任务化**的 AI agent 核心，推理循环最初蒸馏自 [openclaw](https://github.com/openclaw/openclaw)，现已全量重写为 first-party（design/118；血统史 `docs/vendor-history.md`）。

设计取向：**大脑在外**（你提供一个模型网关）、**执行靠工具/MCP**、**session 默认内存化**（重启丢、不重启默认留 7 天；接 durable `SessionStore`/`SessionRepo` 即升级为持久会话中心，§11）、
**MCP/skill 不持久化**（随每个任务传、跑完即弃）。一个"任务"自带它的全套配置（模型、提示词、工具、MCP、skill、限额），
跑完返回一个机器可读的结果（完成 / 受阻 / 失败 / 超时）。

- 语言/运行时：TypeScript + Node（ESM, NodeNext）。
- 外部依赖：**仅 `typebox` 与 `@modelcontextprotocol/sdk`**（design/71 P1 已删除 vendored 磁盘 skill 面，连带移除 `ignore`/`yaml` 两个旧依赖；如本文别处仍提及它们即为过时）。
- 已在真实网关（Qwen3.5-35B, vLLM, OpenAI 兼容）上全链路 live 验证。

> 📌 **当前版本状态（2026-06-29 核实，权威实时状态见 [`docs/HANDOFF.md`](docs/HANDOFF.md)）**：已干净发布 + 打 tag **`1.162.0`**（`package.json`、`git tag v1.162.0`、`npm view @sema-ai/core version` 三处一致）。**1.151~1.162 见 CHANGELOG**——含 **🖥️ 1.162 K-8 第二批 后台 shell seam**（design/103：`Bash(run_in_background)`/`BashOutput`/`KillShell` 让引擎跑真实开发循环；`BackgroundShellCapability` 接口导出单源 + NodeExecutionEnv naturalize + dispose-before-suspendVM + 三安全红线；codex+workflow 双轨复审两轮；TOB 实现归 service）、**🔴 1.161 K-8「CC full-body」第一批**（full-body profile 切片 `FULL_BODY_SYSTEM_PROMPT`/`assembleFullBodyTools` + **BREAKING 工具名对齐 CC**：read_file→Read 等，模型 tool-call 保真度，consumer 锁步翻名）、**1.160 message-identity Phase 1**（`TaskEvent.message_committed`，解锁 `compacted.preserved_segment`）+ **service [325] env-teardown 时序修**、1.155~1.159（shell §K / manual /compact / per-principal 授权轴 / P-13 / CC Plan 模式）。早段脉络：`1.104.0`（design/80 supervisor 封顶）→ `1.111~1.114`（metrics→`/bench` / ask 冒泡 / `tightenTaskSpec`）→ `1.115~1.118`（CC-parity：推理强度真切换 / S1 workflow 引擎 / S8 LLM 自助编排 / goal 模式 S2+S4）→ `1.119.0`（**改名 `@ai-only/ai-agent-core`→`@sema-ai/core`，仓库 `sema-core`**）→ `1.120~1.128`（**sema-shell 主权契约 E1–E25**，design/99）→ `1.129~1.139`（**多轮对抗 bug-hunt + vendored 硬化**，1.139 含 36 修）→ `1.135~1.143`（**2c session-sync** 云↔本地会话同步）→ `1.144~1.145`（workflow-parity CORE-1~9：`WorkflowJournalStore` scope-keyed durable resume + steerable agents `agentStream`/`onWorkflowAgentSpawn` + worktree 隔离 + per-agent activity 流；CORE-1~9 × SVC-1~5 全 SHIPPED）→ **`1.146~1.150`（当前）= sema-shell 数据契约 MF-\***（引擎↔sema-shell `/workflows` monitor↔service 的可观测数据契约，与 service 协调：MF-24 `TaskResult.stats.humanReview.gates[]` 权限门/denial 账本 + 脱敏边界 `src/core/arg-summary.ts` / MF-10 `TaskEvent.task_progress` subagent usage tick / MF-25 `TaskResult.model` 回声 effective model / MF-18 `compacted.trigger` / MF-14 `CheckpointSummary.contentKind` / MF-W WorkflowRun monitor header+活动 arg；MF-Fleet 由 service 进程内 live 聚合，core 只产 fact/signal 不建 durable 父系血缘）。**最近建造线 = sema-shell 数据契约（MF-\*/MF-Fleet）+ P2 design-review / workflow-parity（design/97）/ sema-shell 主权契约（design/99）/ 2c session-sync**；**已封顶降为基座**：CC-parity 编排 + 推理强度 + goal + S8（design/96/97/98，§4.15）· design/80 Supervisor + 价值判决 GOAL 达成（§4.14）。**当前焦点**（快速移动，真相=`git log`+`团队/`通道+memory）= sema-shell 数据契约 loop（MF-\*/MF-Fleet）+ P2 design-review，与 service 协调。默认仍是 `DEFAULT_MAX_TURNS=100` / `DEFAULT_MAX_SUSPENDS=5`（保守安全网，长自治任务由 leader 显式设上限）。`npm test` 全绿（以实跑为准；**3351 passed / 25 skipped**，每发布版都跑全维度）。design/74（资源切片 suspend/resume，长自治跑）已**落地并 make-real LIVE 验证**。

---

## 目录

1. [要求与安装](#1-要求与安装)
2. [60 秒集成](#2-60-秒集成)
3. [核心概念](#3-核心概念)
4. [API 参考](#4-api-参考)
5. [流式事件协议（SSE）](#5-流式事件协议sse)
6. [任务状态语义](#6-任务状态语义)
7. [安全模型](#7-安全模型必读)
8. [多 agent：subagent 与 team](#8-多-agentsubagent-与-team)
9. [Session、内存化与自动压缩](#9-session内存化与自动压缩)
10. [模型网关接入](#10-模型网关接入)
11. [扩展点](#11-扩展点)
12. [示例与自检](#12-示例与自检)
13. [vendored 内核与许可](#13-vendored-内核与许可)
14. [已知限制 / TODO](#14-已知限制--todo)

---

## 1. 要求与安装

- Node ≥ 20（用到全局 `fetch`、`zlib.crc32`；开发机实测 Node 22/24）。
- 模型网关：一个 **OpenAI 兼容**的 `/v1/chat/completions` 端点（流式 + function calling）。

```bash
npm install          # 安装 typebox / @modelcontextprotocol/sdk 等
npx tsc --noEmit     # 类型检查（应为 0 错误）
npm run smoke        # 用 mock brain 跑 e2e（无需网关）
```

**作为 npm 包安装**（公开发布在 npmjs，scope `@sema-ai`，无需任何 token）：

```bash
npm install @sema-ai/core
```

导入：`import { Runner, createOpenAIBrain } from "@sema-ai/core";`。
包发布的是编译产物 `dist/`（`.js` + `.d.ts`）；在本仓开发时直接用 `tsx` 跑 `src/`。

---

## 2. 60 秒集成

```ts
import { Runner, createOpenAIBrain, createSqlTool, pgQuery, type Model } from "@sema-ai/core";
import { Type } from "typebox";

// 1) 定义模型（指向你的网关）
const model: Model = {
  id: "Qwen3.5-35B", name: "Qwen3.5-35B",
  api: "openai-completions", provider: "local-vllm",
  baseUrl: "http://172.30.228.10:8000/v1",     // 你的网关，结尾不带 /chat/completions
  reasoning: true, input: ["text", "image"],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 262144, maxTokens: 4096,
};

// 2) 建 Runner（brain = 外部大脑；models = ref 目录）
const runner = new Runner({
  brain: createOpenAIBrain(),                   // 直连 model.baseUrl
  models: { qwen: model },
});

// 3) 跑一个任务
const res = await runner.runTask({
  objective: "查 orders 表里华东区(East)的总销售额，并说出数字。",
  model: "qwen",
  sessionId: "chat-42",                         // 传则续聊，不传则新建
  tools: [
    createSqlTool({
      allowTables: ["orders"],
      query: pgQuery(readonlyPgPool),           // 你的【只读】连接池
    }),
  ],
});

console.log(res.status);   // "completed" | "blocked" | "failed" | "timeout"
console.log(res.result);   // 最终文本
console.log(res.sessionId);// 用于下一轮续聊
```

流式版（OA 聊天框逐字输出）见 [§5](#5-流式事件协议sse)；HTTP 服务见 [§4.10](#410-createtaskserver--http--sse-服务)。

---

## 3. 核心概念

| 概念 | 是什么 | 对应类型/函数 |
|------|--------|--------------|
| **Brain（大脑）** | 外部 LLM。一个流式补全函数。你提供它，全局共用。 | `Brain` / `createOpenAIBrain` |
| **Task（任务）** | 一次自带全套配置的运行单元（模型/提示/工具/MCP/skill/限额）。 | `TaskSpec` → `TaskResult` |
| **Runner** | 持有 brain + 模型目录 + 内存 session 仓库；执行任务。 | `Runner` |
| **Session** | 一段对话的工作记忆。**内存**存储，传同一个 `sessionId` 即续聊。 | `TtlSessionStore` |
| **Tool（工具）** | 模型能调用的原生函数（typebox 参数 + execute）。 | `defineTool` / `ToolSpec` |
| **MCP** | 任务级临时连接的 MCP server，工具被 materialize，跑完断开。 | `materializeMcpTools` / `McpServerSpec` |
| **ExecutionEnv** | "在哪执行 shell/文件"的抽象。本包默认 stub（不需要 shell）。 | `StubExecutionEnv` |

**一句话数据流**：`TaskSpec` →（Runner 装配 harness：注入 brain、工具、内存 session）→ agent 循环（模型↔工具）→ 自动压缩 → `TaskResult`。

---

## 4. API 参考

所有导出见 `src/index.ts`。下面是确切签名与语义。

### 4.1 `Runner`

```ts
class Runner {
  constructor(deps: RunnerDeps);                 // 含可选 sessionStore(持久化见 §4.11)
  readonly sessions: SessionStore;

  runTask(spec: TaskSpec): Promise<TaskResult>;
  runTaskStream(spec: TaskSpec): TaskStream;   // AsyncIterable<TaskEvent> & { result(): Promise<TaskResult> }
}

interface RunnerDeps {
  brain: Brain;
  models?: Record<string, Model>;              // 解析字符串 ModelRef 用
  roles?: ModelRoles;                          // 角色→模型默认表(见 §4.12)
  sessionStore?: SessionStore;                 // 持久化会话(见 §4.11)
  // … memoryStore / promptProvider / toolPolicy / allowImageUrl / onError
}

// 便捷一次性：runTask(spec, deps)  —— 内部建临时 Runner
function runTask(spec: TaskSpec, deps: RunnerDeps): Promise<TaskResult>;
```

- `runTask` = 跑到结束返回结果。`runTaskStream` = 边跑边吐事件、`.result()` 取最终结果。
- 同一个 `Runner` 实例共享内存 session 仓库（续聊、TTL 都在这里）。

### 4.2 `TaskSpec`（任务输入）

```ts
interface TaskSpec {
  taskId?: string;                  // 缺省用 sessionId
  objective: string;               // ★ 本轮指令 / 用户消息
  images?: ImageInput[];           // 图文输入（模型需支持 vision）
  sessionId?: string;              // 传=续聊；不传=新建（隔离）
  model?: ModelRef;                // "qwen" 这类 ref（查 RunnerDeps.models）或完整 Model 对象；省略则按 modelRole 解析(见 §4.12)
  modelRole?: ModelRole;           // model 省略时解析哪个角色，默认 "default"
  roles?: ModelRoles;              // 按任务/场景覆盖 RunnerDeps.roles
  compactionModel?: ModelRef;      // 压缩用的便宜模型（可选；不传则用 summarize 角色，若配置了）
  thinking?: ThinkingLevel;        // "off"|"minimal"|"low"|"medium"|"high"|"xhigh"|"max"
  systemPrompt?: string;           // 预设系统提示
  tools?: ToolSpec[];              // 原生工具
  mcp?: McpServerSpec[];           // 任务级 MCP（跑完即弃）
  skills?: SkillSpec[];            // 任务级 skill（对象，不落盘）
  limits?: { maxTurns?: number; timeoutSec?: number };
  enableBlockedReport?: boolean;   // 注入 report_blocked 工具，默认 true（见 §6/§7）
  shellGate?: "off"|"always"|"classify"; // design/80 D-2：hands `bash` 的不可逆门控原则（见 §4.14/§7）。默认 "off"
  signal?: AbortSignal;            // 外部取消：abort 即停（取消 brain 请求 + 释放审批闸）
  getApiKeyAndHeaders?: (model: Model) =>
    Promise<{ apiKey: string; headers?: Record<string,string> } | undefined>;
}

type ImageInput =
  | { data: string; mimeType: string }   // base64（无 data: 前缀）
  | { url: string };                      // runner 端 fetch→base64

type ModelRef = string | Model;
```

### 4.3 `TaskResult`（任务输出，机器可读）

```ts
interface TaskResult {
  taskId: string;
  sessionId: string;               // ★ 下一轮续聊用
  status: "completed" | "blocked" | "failed" | "timeout";
  result: string;                  // 最终 assistant 文本（已 trim）
  blockedReason?: string;          // status==="blocked" 时：为何卡住
  errorMessage?: string;           // status==="failed"/"timeout" 时
  stats: {
    turns: number; tokens: number; costUsd?: number;
    promptTokens?: number;           // 跨 provider 归一的输入 token(命中率分母)
    cachedTokens?: number;           // 前缀缓存命中的 token
    cacheWriteTokens?: number;       // 写入缓存的 token(Anthropic cache_creation)
    cacheHitRate?: number;           // cachedTokens/promptTokens ∈[0,1]，成本关键，按会话趋势监控
    nested?: { tokens; turns; tasks; costUsd? };  // 子 agent 委派用量
    costBreakdown?: {                // design/80 D-E-core：LLM 派生成本的财务分类（micro-USD），供监督面分摊
      llmRootMicroUsd;               //   根 agent LLM 成本 = costMicroUsd − compactionMicroUsd
      nestedSubagentMicroUsd;        //   委派子 agent（nested）LLM 成本
      memoryConsolidationMicroUsd;   //   任务后记忆固化 LLM 成本（独立预算外行，异步补填）
      compactionMicroUsd;            //   任务内压缩 LLM 成本（含在 costMicroUsd 内）
    };                               //   恒等式：llmRoot+nestedSubagent+compaction === costMicroUsd（infra 轴由 service 补）
  };
}
```
> **缓存可观测**:`cacheHitRate` 是前缀缓存命中率(成本命脉)。多轮任务(≥2)+ 大提示(≥8000 token)+ 命中 <15%
> 时,core 经 `onError({ phase:"prompt-cache" })` **告警**(前缀不稳/被污染的信号);单轮冷启动不会误报。
> 按任务记录 `cacheHitRate`、按 `sessionId` 聚合成趋势即可做你们的成本看板/告警。
> - **命中率分母按 `model.api` 自动判 family**(Anthropic 的 input 不含缓存、OpenAI 含)。若你**按 provider 路由、
>   `model.api` 与实际 brain 不符**(会导致命中率 >100%),用 `model.params.promptCacheFamily =
>   "input-includes-cached"|"input-excludes-cached"`(别名 `"openai"`/`"anthropic"`)**显式覆盖**;core 还会在
>   `cachedTokens>promptTokens` 时 clamp 到 1 并经 `onError` 报错,不会给你荒谬值。

状态判定见 [§6](#6-任务状态语义)。

### 4.4 `Brain` 与 `createOpenAIBrain`

```ts
interface Brain {
  stream: StreamFn;                                  // 流式补全（核心）
  complete?: (model, ctx, options?) => Promise<...>; // 非流式；缺省由 stream 派生
}

function createOpenAIBrain(config?: OpenAIBrainConfig): Brain;

interface OpenAIBrainConfig {
  baseUrl?: string;                       // 缺省用 model.baseUrl
  apiKey?: string;                        // 被 options.apiKey / getApiKeyAndHeaders 覆盖
  headers?: Record<string, string>;
  fetchImpl?: typeof fetch;               // 测试/代理用
  maxRetries?: number;                    // 瞬时失败(网络/5xx/429)重试，默认 2；流开始后不重试，abort 不重试
  retryDelayMs?: number;                  // 退避基数，默认 400（指数：base*2^attempt）
  replayThinking?: boolean;               // 回灌 assistant reasoning_content（DeepSeek V4 等需要；R1/多数不要）。默认关
  connectTimeoutMs?: number;              // 建连超时：fetch 未在时限内返回响应头 → 可重试的 [network]。默认关
  firstTokenTimeoutMs?: number;           // 首-token 超时：SSE 已开但迟迟不吐第一个 delta → cancel + [network]。默认关
}
```

> 网关偶发抖动（5xx/429/连接重置）会被自动重试（仅在响应体开始流式之前）。4xx 不重试，abort 不重试。

> **分级超时（1.38.1）**：任务级 `timeoutSec` 之下补两级 brain 超时（`OpenAIBrainConfig`/`AnthropicBrainConfig`
> 共有的 `BrainTimeoutConfig`，默认关）。`connectTimeoutMs` 管"建连"（`fetch` 返回响应头前），`firstTokenTimeoutMs`
> 管"首字"（SSE 已开但网关 hang、迟迟不吐 delta —— 最常见的故障症状），两者超时都记为**可重试的 `[network]`**，
> 自动走重试 / 断路器 / failover；total 仍由 `timeoutSec` 兜底。**reasoning 模型的首个 thinking delta 也算首 token**，
> 长思考模型不会因"迟迟不出可见字"被误杀。

`createOpenAIBrain` 把统一上下文翻译成 OpenAI `/chat/completions` 请求，并把流式响应（含 **native 工具调用增量**、
`delta.reasoning`/`reasoning_content` 思考流、图片多模态）翻译回统一事件协议。**这是模型兼容性的核心**——覆盖
Qwen / Gemini / DeepSeek / GPT / OpenRouter 等所有 OpenAI 兼容网关。要接非 OpenAI 协议的网关,自己实现一个 `Brain`。

> **思考模式(reasoning)按 provider 不同**:有的 provider(DeepSeek V4)在 assistant 工具调用轮**要求回灌** reasoning，
> 否则报错/降级;有的(DeepSeek R1、多数)要丢掉。用 `replayThinking` 开关(默认丢)。截断的工具参数(`finish_reason:"length"`)
> 不会再被静默当 `{}` 执行——会以 `errorMessage` 暴露,调用方可重试。

### Anthropic 大脑(云 API):`createAnthropicBrain`

接 Anthropic Messages API(`/v1/messages`),给**云部署**用(不止本地 vLLM)。同一 `Brain` 契约,直接进 Runner,
和 failover/routing 组合(**云 Anthropic ↔ 本地 vLLM** 路由/兜底)。

```ts
import { createAnthropicBrain, createRoutingBrain, createOpenAIBrain } from "@sema-ai/core";

const brain = createRoutingBrain(
  { anthropic: createAnthropicBrain({ apiKey: process.env.ANTHROPIC_API_KEY }),
    "local-vllm": createOpenAIBrain() },
  { by: "provider", fallback: "local-vllm" },
);
```
- **提示词缓存**:`cache_control:{type:"ephemeral"}` 断点打在 system 块 + 最后一个工具(照 Claude Code);
  `cache_read/creation_input_tokens` → `usage.cacheRead/cacheWrite` → `TaskResult.stats.cachedTokens` **真实命中可见**。`cacheBreakpoints` 开关。
- **extended thinking + tool use**:thinking 块带 `signature` 捕获并**回灌**(Anthropic 硬要求)。
  思考预算 `budget_tokens` 自动钳到 `1024 ≤ budget < max_tokens`(否则 Anthropic 422);`max_tokens`
  太小时上调到能容纳"最小思考预算 + 回答余量"。用 `thinkingBudgetShare`(占 `max_tokens` 的比例,默认 0.5)
  或 `thinkingBudgetTokens`(固定值)给爱长思考的模型(如 deepseek-v4-pro)**留足回答空间**。
- **截断即报错,不再空成功**:`max_tokens`/`length` 截断且**没产出任何回答文本**(思考吃光预算)时,
  turn 以 `stopReason:"error"` + 清晰 `errorMessage` 收尾(OpenAI/Anthropic 两条路一致),不再伪装成 `completed`。
  截断的 `tool_use` 参数 JSON 同理:不带空参执行,直接报错暴露。
- 真机验证脚本:`ANTHROPIC_API_KEY=… npx tsx src/examples/anthropic-live.ts`(连跑两遍看第二遍 `cachedTokens`>0)。

> **前缀缓存对成本极关键**(见 `design/09`):提示词排版 STABLE→VARIABLE(稳定 base 在前、记忆在尾),时间戳/当前日期/id
> **绝不进前缀**,工具顺序要稳定。core 1.12 修了默认 prompt 排序;`stats.cachedTokens` + 离线 cache-guard 测试量化命中率。

**多网关故障转移**：`createFailoverBrain([primary, backup, …])` 把多个 brain 组合成主备。正常路径实时流式;
仅当某 brain **在吐任何内容之前**就失败(如网关挂)才切到下一个(不会出现重复 start/文本)。每个 brain 各自保留重试策略。
```ts
const brain = createFailoverBrain([
  createOpenAIBrain({ baseUrl: PRIMARY }),
  createOpenAIBrain({ baseUrl: BACKUP }),
]);
```

### 4.5 `defineTool` / `ToolSpec`

```ts
interface ToolSpec<TParams extends TSchema = TSchema> {
  name: string;
  aliases?: string[];                     // 旧 wire 名兼容；新工具调用应使用 name
  description: string;                    // 模型据此决定何时调用——写清楚
  label?: string;
  parameters: TParams;                    // typebox schema（Type.Object({...})）
  execute: (args: unknown, ctx: ToolExecuteContext) => Promise<ToolReturn> | ToolReturn;
}
interface ToolExecuteContext { toolCallId: string; signal?: AbortSignal }
type ToolReturn =
  | string                                                  // 文本结果
  | { content: Array<TextContent|ImageContent> | string; details?: unknown; terminate?: boolean };

function defineTool(spec: ToolSpec): AgentTool;             // ToolSpec 也可直接放进 TaskSpec.tools（内部会转）
```

- `parameters` 用 typebox。模型看到的是它序列化出的 JSON Schema。
- `execute` 抛异常 = 工具失败（循环会把错误编码成工具结果让模型看到，不会 crash 任务）。
- `terminate: true` = 提示 agent 本轮工具批次后停止。

> 注意：`TaskSpec.tools` 接受的就是 `ToolSpec[]`，无需手动 `defineTool`（Runner 内部转）。`defineTool` 用于你想拿到底层 `AgentTool`（如包一层）。

### 4.6 SQL 工具：`createSqlTool` + 适配器

```ts
function createSqlTool(opts: SqlToolOptions): ToolSpec;
interface SqlToolOptions {
  query: (sql: string) => Promise<unknown[]>;  // ★ 你注入【只读】执行器
  allowTables?: string[];                      // 表白名单（大小写不敏感）
  maxRows?: number;                            // 返回给模型的行上限，默认 100
  name?: string;                               // 默认 "query_sql"
  description?: string;
}
function validateReadOnlySql(sql: string, allowTables?: string[]): void;  // 单独可用；非法则 throw

// 适配器（零依赖，结构化类型；你传已建好的【只读】客户端）
function pgQuery(pool):    (sql:string)=>Promise<unknown[]>;   // node-postgres
function mysqlQuery(conn): (sql:string)=>Promise<unknown[]>;   // mysql2/promise（也用于 TiDB）
function sqliteQuery(db):  (sql:string)=>Promise<unknown[]>;   // better-sqlite3
```

> **TiDB**：TiDB 是 MySQL 线协议兼容的，直接用 `mysql2` 建一个**只读**连接池指向 TiDB，
> 再 `createSqlTool({ query: mysqlQuery(pool), allowTables: [...] })`。例：
> ```ts
> import mysql from "mysql2/promise";
> const pool = mysql.createPool({ host, port: 4000, user: READONLY_USER, password, database });
> const tool = createSqlTool({ query: mysqlQuery(pool), allowTables: ["orders"], maxRows: 200 });
> ```
> 务必用只读账号；TiDB 可按用户授予 `SELECT`-only 权限作为第一层保证。

安全分层（详见 [§7](#7-安全模型必读)）：①只读 DB 凭据（你的责任）②静态校验（仅 SELECT/WITH、拒多语句/注释/DML-DDL/`INTO`）③表白名单 ④行上限。

### 4.7 Gitea Issue 工具：`createGiteaIssueTool`

让 agent **给维护者开 Gitea issue**(报 bug / 提需求)。按场景注入,仓库/鉴权/默认标签由 config 固定,模型只选 `title`/`body`:
```ts
import { createGiteaIssueTool } from "@sema-ai/core";
const issueTool = createGiteaIssueTool({
  baseUrl: "https://gitea.example.com",
  owner: "AI-Only", repo: "sema-core",
  token: process.env.GITEA_ISSUE_TOKEN!,   // ★ 从环境变量取,绝不硬编码/提交
  defaultLabels: [/* Gitea 数字 label ID */], // 给所有 AI 开的 issue 打标
});
runner.runTask({ objective, model, tools: [issueTool] });
```
- `effect:"write"`(非幂等:每次开新 issue,中断**不自动重试**,避免重复 issue)。
- token **只进 `Authorization` 头**,不进 body、不进任何返回/日志文本。
- 失败(HTTP 4xx/5xx、网络)返回**可恢复的工具结果**(非抛错),模型可重试或 `report_blocked`。
- 可选 `allowModelLabels` 让模型自带 label ID(与 `defaultLabels` 合并去重)。

### 4.7 MCP：`materializeMcpTools`

```ts
function materializeMcpTools(specs: McpServerSpec[]): Promise<MaterializedMcp>;
interface MaterializedMcp { tools: AgentTool[]; dispose: () => Promise<void> }

type McpServerSpec = {
  name: string;                              // 工具会被命名空间化为 `<name>__<tool>`
  transport:
    | { kind: "stdio"; command: string; args?: string[]; env?: Record<string,string> }
    | { kind: "http"; url: string; headers?: Record<string,string> };
  allowTools?: string[];                     // 仅暴露这些工具
};
```

通常**不用直接调**：把 `McpServerSpec[]` 放进 `TaskSpec.mcp`，Runner 会在任务开始时连接、materialize 成工具，
任务结束 `dispose()` 断开。MCP 工具的 `inputSchema`(JSON Schema) 直接作为参数 schema，模型看到真实结构、循环原生校验。

### 4.8 `createSubagentTool`（委派）

见 [§8](#8-多-agentsubagent-与-team)。

### 4.9 `runTeamDiscussion`（多 agent 讨论）

见 [§8](#8-多-agentsubagent-与-team)。

### 4.10 `createTaskServer`（HTTP + SSE 服务）

```ts
function createTaskServer(opts: TaskServerOptions): http.Server;
interface TaskServerOptions {
  runner: Runner;
  resolveSpec: (body: TaskRequestBody, req) => TaskSpec | Promise<TaskSpec>;  // ★ 服务端注入 model/tools
  authorize?: (req) => boolean | Promise<boolean>;   // 返回 false → 401
  corsOrigin?: string;                               // 如 "*"
  maxBodyBytes?: number;                             // 默认 5 MiB
}
interface TaskRequestBody { objective: string; sessionId?: string; images?: ImageInput[]; [k:string]: unknown }
```

端点：
- `POST /task` → 跑到结束，返回 `TaskResult` JSON。
- `POST /task/stream` → SSE，逐条 `data: <TaskEvent JSON>\n\n`，`done` 事件后结束。

**关键安全设计**：请求体只带内容（objective/sessionId/images），**工具与模型由服务端 `resolveSpec` 注入**——
因为工具的 `execute` 函数无法、也不应通过网络传输。前端/外部 AI 不能注入可执行工具。

```ts
const server = createTaskServer({
  runner,
  corsOrigin: "https://oa.internal",
  authorize: (req) => verify(req.headers.authorization),
  resolveSpec: (body) => ({
    objective: body.objective,
    sessionId: body.sessionId,
    images: body.images,
    model: "qwen",
    tools: [ createSqlTool({ allowTables: ["orders"], query: pgQuery(readonlyPool) }) ],
    limits: { timeoutSec: 120 },
  }),
});
server.listen(8090);
```

### 4.11 `TtlSessionStore`

```ts
class TtlSessionStore {
  constructor(opts?: {
    defaultTtlDays?: number;          // 默认 7 天
    sweepIntervalMs?: number;
    repo?: SessionRepo;               // ★ 注入【持久】会话仓 → 重启/多副本续话
    evict?: "delete" | "forget";      // 空闲/release:删库 or 只清缓存(custom repo 默认 forget)
  });
  acquire(sessionId?: string): Promise<{ session: Session; sessionId: string }>;
  touch(sessionId: string): void;
  release(sessionId: string): Promise<void>;   // 一次性任务跑完想立刻丢就调它
  sweep(now?: number): void;
  get size(): number;
  dispose(): void;                              // 关定时器
}
```

`Runner` 默认自带一个(内存,重启丢)。**持久化("会话中心"):** 给 `TtlSessionStore` 传一个 durable `SessionRepo`
(如 TiDB 后端),`acquire` 会经 `repo.open` **从事件日志续话**——任意无状态 runner 重启后、或另一副本都能接上同一对话;
custom repo 下 `evict` 默认 `"forget"`(空闲只清缓存、**不删库**)。完整实现契约(CAS 乐观锁、TiDB 表草图、两条路线)见
**`design/10-会话持久化与会话中心.md`**;`test/sessions.test.ts` 有 `DbSessionRepo`/`DbSessionStore` 真跑续话。
```ts
new Runner({ brain, sessionStore: new TtlSessionStore({ repo: myTiDbSessionRepo }) }); // 持久、可横向扩
```

### 4.12 模型角色(`roles`)与 `@-model`

**角色表**:声明一次模型,主任务/压缩/子代理/team **各按角色解析**,不必每处重复模型名。角色:
`default`(主任务,`TaskSpec.model` 省略时用它)、`summarize`(压缩总结,= aider weak-model)、`subagent`、`team`、`synthesize`;
带回退链(`summarize→default`、`synthesize→team→default`)。`TaskSpec.roles` **按任务/场景覆盖** `RunnerDeps.roles`。
```ts
const runner = new Runner({
  brain, models: { strong, cheap },
  roles: { default: "strong", summarize: "cheap", subagent: "cheap" },  // 两行做成本分级
});
runner.runTask({ objective });                       // model 省略 → 走 default 角色
runner.runTask({ objective, roles: { default: "cheap" } });            // 本任务/场景覆盖
createSubagentTool({ runner });                       // 无 model → subagent 角色(→ default)
```
- `RoleSpec` 可是 `ModelRef`,也可 `{ model, thinking }` —— 角色还能带**默认 thinking 档**(显式 `TaskSpec.thinking` 仍胜)。
- 压缩:`compactionModel` 显式 > `summarize` 角色(若配置)> 主模型(不变)。
- 设计/调研(含 aider/Claude Code/LiteLLM/RouteLLM 对照、能力角色与 Layer 2 规划)见 **`design/11-模型路由与选择层.md`**。
- **两轴一起的真机示例**:`src/examples/deepseek-routing-roles.ts` —— 一个 Runner 里 `createRoutingBrain` 按 `provider`
  路由到 DeepSeek 的 Anthropic(`/v1/messages`)与 OpenAI(`/chat/completions`)两条传输,叠加 `roles` 把 pro/flash 分工
  (父任务走 pro/Anthropic、子代理走 flash/OpenAI)。`DEEPSEEK_API_KEY=… npx tsx src/examples/deepseek-routing-roles.ts`。

**`@-model`**(聊天框内联选模型):`parseModelMention(text, allowedNames)` → `{ model?, cleanedText }`。
**只返回 allowlist 内的名字、绝不内联 Model 对象**——终端用户能选*哪个已配置模型*,但注入不了任意 `baseUrl`/`apiKey`(安全边界)。
```ts
const { model, cleanedText } = parseModelMention(userMsg, Object.keys(deps.models));
runner.runTask({ objective: cleanedText, model });   // model 为空则回落 default 角色
```

### 4.13 老师模式:`runWithTeacher`(便宜学生 + 强老师升级)

**便宜小模型干主要活,卡住/答错才请教强"老师"**(escalation cascade,见 `design/12`/`design/13`)。
配 `roles: { default: 便宜学生, advisor: 强老师 }`,跑 `runWithTeacher`:

> **适用前提:任务要有"可判定的 verify 信号"**——升级只在能判断学生答错时才触发(Tier 0 同工具+同错卡住 / Tier 1 终态 rubric 质检 / `blocked`/`failed` 终态)。**不适用于开放式"完整性/质量"判断**(如 code-review"找全 bug"、创意质量):没有 oracle 知道"该有几个、漏了哪个",学生找到一个明显问题就过 verifier、却静默漏掉其余,触发机制空转(verifier 纯增本)。这类任务靠**广度 + 对抗(`team` council/debate)**而非**深度升级**——两者正交。亦提醒:**小而明确的任务上"强模型"未必更贵**(强模型输出简洁、弱模型啰嗦),"便宜学生省钱"在小任务上前提会被削弱。(service 实测反馈,2026-06,详见 `design/12` §六)
```ts
const r = await runWithTeacher(runner, { objective, tools }, {
  // 全部可选,下面是默认值
  maxEscalations: 3,            // 每次运行最多升级几次
  teacherSpendRatioCap: 0.4,    // 老师花费 ≤ 学生花费 × 此比例就停(止损)
  stuckThreshold: 3,            // 同一工具连续失败几次算"卡住"
  verifyOutput: true,           // 终态产出过一次"便宜模型 + rubric"语义质检
  takeoverAfter: 2,             // 纠正再失败几次 → 老师直接接管
});
console.log(r.status, r.result, r.escalations, r.teacherStats); // teacherStats={tokens,tasks,costUsd}
```
- **两层触发**:Tier 0 —— 重复同工具失败 → **提前中止止损**(可选便宜 stuck-monitor 二次确认);Tier 1 —— **语义 rubric 质检**(便宜模型)抓"通过了但语义错"(纯确定性触发的盲区);外加 `blocked`/`failed` 终态。
- **老师 = 隔离的 `advisor` 角色子运行**,只回 JSON `{strategy,correction,nextStep,takeover,confidence}`;**对话丢弃、只把结构化建议注回同一学生 session**(护前缀缓存),并要求学生**先用工具输出核验建议再照做**。
- **纠正→接管**:纠正多次仍不行(或 `takeover:true`)→ 老师直接做完。
- **硬护栏**:升级上限、老师/学生花费比、老师每次 ≤4 turn;全程接 `studentSpec.signal`。
- `r.escalations`(每次升级的 trigger/建议/是否接管)+ `r.teacherStats`(老师用量 `{tokens,tasks,costUsd}`,与学生 `stats` 分开)。
- 老师/helper 未配 advisor 角色时**优雅退化**到学生模型(escalation 退化为"带结构化指导重试")。真机已验(DeepSeek flash 学生 / pro 老师,pro 返回的 JSON 建议解析正常)。
- **策略仓库(可选,二期 design/14)**:配 `strategyStore` + `scope` 后,老师"奏效的通用策略"会被存下,后续**相似问题**把策略注入学生 objective(前缀缓存安全),省得再请教老师(跨会话复用)。`scope` **强制隔离**(多租户不串)。检索**高精度低召回**(每个有意义词都要命中),注入带"过去*不同*任务、可能不适用、请核验"的否定前言。`new InMemoryStrategyStore()` 默认实现;可换 TiDB/embedding 后端。
  ```ts
  const store = new InMemoryStrategyStore();
  runWithTeacher(runner, spec, { strategyStore: store, scope: "user:42" });
  ```
- **触发可调**:Tier 0 卡住检测按"同工具+**同错误**"计数(变错=进展);`escalationPolicy` 可**否决**某次升级(独立监测解耦);`verifierSamples` 让 rubric verifier 多数表决(校准)。硬护栏:`maxEscalations`、`teacherSpendRatioCap`(老师 token ≤ 学生×此比例;老师远贵于学生时调大)、老师每次 ≤4 turn。
- **真机示例**:`src/examples/teacher-mode.ts`(DeepSeek flash 学生 / pro 老师 + 策略仓库):`DEEPSEEK_API_KEY=… npx tsx src/examples/teacher-mode.ts`。

### 4.14 Supervisor 公共面(design/80 人在环监督式编排,core 侧已 shipped 至 1.104.0;已封顶降为基座)

design/80 给"人在环监督式编排"加了一组 **durable-checkpoint substrate** 公共面。**全部 ADDITIVE / 多数 INERT**——
core 只**铸造/附带**这些字段,**从不**用它们去 gate / 限额 / 抑制(结构性 ask 经 `combinePolicies` 严格胜出);由
profile / 监督面 / 部署侧去**读取并据此编排**。新增公共面如下(导出件全在 `src/index.ts`):

**① `ToolCallRequest.budget`(只读 durable 预算快照)** —— 让**无状态** `ToolPolicy.check(req)` 能针对**跨 suspend/resume
存活**的预算自限(进程内计数器每段会清零=监督升级预算缺口)。core 在 prepare 期从 durable 资源账本 + suspend 链构造,
**策略无法写回放宽**:
```ts
req.budget?: {
  resourceRemainingMicroUsd?: number;  // 本 run 还可花的 durable $（micro-USD）；undefined=无上限。
                                       //   ⚠️ 绝不 falsy-test：0=已耗尽 ≠ 无上限（只有 undefined 才是无上限）
  resourceSpentMicroUsd: number;       // 跨所有 leg 累计已花 $（micro-USD）
  suspendCount: number;               // 本 run 已 suspend 次数（durable 链）；策略可随链增长收紧
}
```
> SAFETY ask(egress / 不可逆)**永远忽略 budget、永远 ask**(不变量结构性保住,core 对安全工具照铸 `irreversible_ask`)。

**② `CheckpointGate.riskDescriptor`(监督收件箱分诊元数据,INERT)** —— 铸造在 `human` / `irreversible_ask` 升级门上的
**确定性、已脱敏**风险摘要,让监督收件箱无需重算风险即可按真严重度排序/分诊:
```ts
riskDescriptor?: {
  severity: 1|2|3|4|5;   // ToolEmu 风格分层（5 最严重），收件箱按此降序排。= riskSeverity(axes) 的纯函数
  axes: { egress?: boolean; irreversible?: boolean; shell?: boolean };  // 触发的安全轴；{} = 纯可预算 human ask
  toolName: string;
  summary?: string;      // 单行已脱敏预览（经 inlineUntrusted + 长度截断；绝不含原始密钥/全参/env）
  touchedPaths?: string[]; // fs 工具 path 参数（best-effort，每条 inlineUntrusted 截断；shell 不解析）
};
```
> INERT(trace 验证):core 从不读它去 gate/限额/抑制。`summary`/`touchedPaths` 经脱敏硬化——所有模型可控值过
> `inlineUntrusted` + 码点上限,只摘**顶层 DATA 属性标量**(嵌套对象/数组/getter 永不进收件箱),`buildRiskDescriptor`
> **结构上 TOTAL**(对抗性 / 被 hook 改写的 args 都不会让铸造崩溃或让显示输出变化)。

**③ 新增门类(`CheckpointGate.kind`)与 `ResumeOutcome` arm**:
- `irreversible_ask`(design/80 D-2):安全 mint-site ask,带 `safetyAxis { egress?, irreversible? }`(来自工具**静态** spec 标记
  `ToolSpec.egress` / `ToolSpec.irreversibility`,非可伪造的 per-call decisionReason)+ 可选 `riskDescriptor`。**非可预算**——
  budget 解析器对它永不自动批准。
- `plan_review`(design/80 D-B):**动作前**计划评审门(distinct kind,非复用 `resource_limit` 占位)。**没有待裁决的工具**——
  人评审的是**计划**而非工具调用,故此 arm **无 tool 字段**;`ResumeOutcome` 有对应 `{ kind: "plan_review" }` arm。**每个读
  `tool_approval` 字段的消费者都必须先 branch on `kind`**(契约测试钉死),计划工件本身是 profile 关注(REF)。

**④ `pendingSteer`(durable steering on a paused checkpoint)** —— 监督者可在一个**已暂停的 checkpoint** 上 park 一条
转向指令,resume 时注入(runtask)。`Checkpoint.state.pendingSteer { text: string; trusted: boolean }`;`trusted` 在
`setPendingSteer` 时从 service 的已验证 principal 检查**冻结**(operator 角色)。脏内容在 `setPendingSteer` 即被拒
(typed `steering.invalid_content`)。CheckpointStore 新增 `setPendingSteer(...)` 方法 + 导出 `validatePendingSteer(steer)`
(每个 impl 在持久化前都跑的同一套校验)。**last-writer-wins**;只写 `state.pendingSteer`,绝不动 status / 审批通道。

**⑤ `AskUserQuestion`(模型可调的结构化提问合成工具)** —— 让 agent 向**用户**提一个结构化问题。
`createAskUserQuestionTool(onQuestion?)`,工具名固定为 `"AskUserQuestion"`(内部常量 `ASK_USER_QUESTION_TOOL_NAME`,未从根导出)。
durable 模式下一次提问会**durably suspend** 任务(在工具执行前),由部署侧路由到真人/UI、答完 resume。配套导出:
`createDurableQuestionPolicy`、`QUESTION_AWAITS_RESUME` 及类型 `OnQuestion`/`AskQuestion`/`AskQuestionOption`/
`AskQuestionRequest`/`QuestionAnswer`/`QuestionAnswerItem`。无 live human 时工具仍挂载、返回 placeholder。

**⑥ 导出的辅助函数 + `Checkpoint.deadline` D-D 契约**:
- `riskSeverity(axes)` → `1|2|3|4|5`:纯函数(无 LLM / 无 clock / 无 random),收件箱排序的稳定 key。规则:
  不可逆+egress→**5** / 仅不可逆→**4** / 仅 egress→**3** / shell-gated tighten→**3** / 纯 human ask→**2**。
- `buildRiskDescriptor(input)` → `RiskDescriptor`:在门铸造处由 D-2 `safetyAxis` + shell-gate 上下文 + **SHOWN** 工具参数
  确定性派生,TOTAL by construction。
- `Checkpoint.deadline`(epoch-ms)承载 **§D-D 过期语义契约**(写在该字段 + `CheckpointStore` 接口的文档上):FACET A
  审批门=`deadline` 是 SLA resolve-deny 时间 + 更晚的 `terminalAt` 弃用 backstop;FACET B(`resource_limit`/`needs_review`/
  `plan_review`)=`deadline` 是 abandonment-TTL,只过期/reap、**绝不** resolve-deny(否则 `gate_mismatch`)。**reaper 循环 +
  gate.kind 策略 + 铸 `terminalAt` 都是部署侧(service)的活**;core 只保证 durable 字段(`deadline` + 持久化的 `gate.kind`)。
- （注:`isDurablePause(status)` 仍是 core 内部 helper、**未**从 `src/index.ts` 导出;监督 substrate 对外的辅助函数即上述
  `riskSeverity` / `buildRiskDescriptor` / `validatePendingSteer`。）

> **何处用**:这是给**自建监督客户端**(steer box / 计划评审 / decision-with-token / riskDescriptor 收件箱渲染)与
> **service 编排**(durable 审批 + steering + plan-review + worker 自修复环)消费的 substrate。core 侧已 TOP OUT;§5 序列里
> 仍属 service 的有 D-G(direct-connect client principal 加密绑定,server 侧已建+双 council+canary e2e、激活待 M2)、
> D-C(leader 监督视图=seam 注记非实现切片)。完整保证/不保证边界见 [`docs/durability-boundary.md`](docs/durability-boundary.md)。

### 4.15 CC-parity 编排 + 推理强度公共面(design/96/97/98,1.114–1.118;已封顶基座)

> 注:此后还 ship 了 **workflow-parity**(design/97 CORE-1~9,1.144~1.145:`runWorkflow`/`WorkflowRunContext` 的 steerable `agentStream`/`onWorkflowAgentSpawn` + worktree 隔离 + `WorkflowJournalStore` durable resume + per-agent activity)、**sema-shell 主权契约**(design/99 E1–E25:`tool_end.output`/`workspace_changed`/`status` 事件/`McpServerStatus`/`onElicit`/`SessionPolicyStore`)、**2c session-sync**(`SessionRepo.export/importEntries`/`FileSnapshotStore`/`StreamingImportValidator`)。这些新公共面的契约速查见 `docs/ARCHITECTURE.md` §4 能力矩阵 + `docs/SERVICE-INTEGRATION-GUIDE.md` §13/§14,完整签名以 `src/index.ts` 导出为准。
>
> 注(1.146~1.150):还 ship 了 **sema-shell 数据契约 MF-\***(引擎↔sema-shell `/workflows` monitor↔service 的可观测公共面):`TaskResult.stats.humanReview.gates[]`(MF-24 权限门/denial 账本,toolArg 经共享脱敏边界 `src/core/arg-summary.ts`)、`TaskEvent.task_progress`(MF-10 subagent usage tick,ephemeral)、`TaskResult.model`(MF-25 回声 effective/resolved model id)、`compacted.trigger`(MF-18)、`CheckpointSummary.contentKind`(MF-14)。这些数据契约的服务侧消费见 `docs/SERVICE-INTEGRATION-GUIDE.md`,完整签名以 `src/index.ts` 导出为准。

design/80 封顶后,主线转向 **CC-parity 编排 + 推理强度**。新增以下公开 API(导出件全在 `src/index.ts`):

**① Workflow 模式(`src/orchestration/workflow.ts`,design/97 S1)** —— **确定性脚本编排** thin helper,**非** LLM 动态
planner(脚本显式调 `ctx.parallel`/`ctx.pipeline`/`ctx.phase`/`ctx.agent`,而不是让模型自己规划 DAG)。
- `runWorkflow(script, deps, opts?)` → `Promise<RunWorkflowResult>`:跑一个 `(ctx: WorkflowRunContext) => Promise<...>` 脚本。
- `WorkflowRunContext` 方法:`agent(spec, opts?)`(跑一个记录在案的 agent-run,任何终态都不 throw)/ `parallel(thunks)`
  (并发,**有 barrier**=等全部;throw 的 thunk 解析为 `null`)/ `pipeline(items, ...stages)`(每项独立流过各 stage,
  **无 barrier**)/ `phase(title, body)`(可观测分组)/ `log(message)`(narrator 日志);只读字段 `runId` / `budget`。
- `WorkflowBudgetExceededError`:`opts.budget`(token 上限)耗尽时 `ctx.agent` 抛出。`MAX_WORKFLOW_ITEMS`=单次 `parallel`/
  `pipeline` 的项数上限(对齐 CC Workflow 工具)。配套类型 `WorkflowRun`/`WorkflowEvent`/`WorkflowBudget`/`RunWorkflowOptions`/
  `RunWorkflowResult` 等。

**② `/workflows` 可观测(`src/core/workflow-run-store.ts` + `src/orchestration/workflow-observe.ts`,S1b/S1c)** ——
让 workflow run 进 `/workflows` 历史 + 跨副本可见(**opt-in**,无 store 仍跑+进程内可订阅;持久化 best-effort,store throw
绝不破坏 workflow)。
- `WorkflowRunStore`(接口)+ `InMemoryWorkflowRunStore`(core 自带)+ `FileWorkflowRunStore`(`src/stores/file/workflow-run-store.ts`,
  `FileWorkflowRunStoreOptions`)。**PG 归 service**(部署 persist 轴=部署外壳实现,不在 core)。
- `summarizeWorkflowRun(run)` → `WorkflowRunSummary`、`workflowRunStoreContract`(跨后端等价契约)、`isTerminalWorkflowStatus`、
  `WorkflowRunStoreError`。
- 读取面:`listWorkflowRuns` / `getWorkflowRun` / `subscribeWorkflow`(`workflow-observe.ts`)。

**③ 推理强度(`src/brain/reasoning.ts`,design/96 S3/S5/S6)** —— 复用 vendor 7 档 `ThinkingLevel` 的 `ReasoningIntensity`
抽象 + per-endpoint clamp + effective-intensity surfacing。
- `resolveReasoning(requested, endpoint)` → `ResolvedReasoning`(`{ requested, effective, graded, clamped, format, endpoint }`):
  task 启动时由 runner 调用,发出 `reasoning.resolved` TraceEvent,让部署看到 tier 为何被降级(binary provider →`graded:false`)
  或被夹(effort-set cap →`clamped:true`)而非静默吞掉(§E honesty)。
- `resolveEffort(...)`(per-endpoint effort 档夹)、`reasoningBudgetShare` / `REASONING_BUDGET_SHARE`、`DEFAULT_EFFORT_LEVELS`、
  `isThinkingLevel` / `rankOf` / `resolveBinary`;配套类型 `ReasoningIntensity`/`ResolvedReasoning`/`ReasoningResolution`/
  `ReasoningFormat`。默认强度常量 `DEFAULT_REASONING_INTENSITY`(`src/scenarios/env.js`)。

**④ `CheckpointSummary` 新字段(`src/core/checkpoint-store.ts`,S1e)** —— 让 service inbox 一次投影即拿到展示所需,免 N+1 回取:
- `createdAt?`(epoch-ms 标量,checkpoint 创建时间,从 `Checkpoint.createdAt` 投影)。
- `toolInput?`:`tool_approval` 工具 args 的 **bounded raw 预览**(超过 `MAX_TOOL_INPUT_PREVIEW_CHARS=512` 字符截断 + `…` 标记)。
  **ECHO-ONLY**(无 gate / CAS / resume 读它——同 `riskDescriptor` 的 INERT 不变量);**脱敏归 consumer**(core 只做长度
  上限,不替 consumer 决定 redaction 策略)。

**⑤ `tightenTaskSpec`(`src/core/tighten-task-spec.ts`,config-center §10,1.114.0)** —— **tighten-only** TaskSpec merge
治理原语:把 `overrides` 层叠到 `base`,但**放松任何安全字段**(如把 `handsReadOnly` 从 `true` 降到 `false`、或两边冲突的
不可合成字段)即 `throw TaskSpecTightenError`,而不是静默选边。两件导出:`tightenTaskSpec` + `TaskSpecTightenError`。

---

## 5. 流式事件协议（SSE）

`runTaskStream(spec)` 返回 `TaskStream`（`AsyncIterable<TaskEvent>` + `.result()`）。事件类型：

```ts
type TaskEvent =
  | { type: "text_delta";      delta: string }        // 正文增量（推给前端逐字显示）
  | { type: "reasoning_delta"; delta: string }        // 思考增量（可折叠显示；不进最终结果）
  | { type: "tool_start";      toolCallId: string; toolName: string; args: unknown }
  | { type: "tool_end";        toolCallId: string; toolName: string; isError: boolean }
  | { type: "turn_end" }                              // 一轮（assistant + 工具）结束
  | { type: "compacted";       tokensBefore: number; trigger: "auto" | "manual"; preserved_segment?: { firstKeptEntryId: string } } // 压缩边界（preserved_segment = 保留尾起点的 entryId）
  | { type: "message_committed"; entryId: string; role: "user" | "assistant" | "toolResult"; toolCallId?: string } // message-identity：刚持久化的消息→其 SessionTreeEntry id（消费者据此解析 preserved_segment）
  | { type: "done";            result: TaskResult };  // 终止，携带最终结果
```
> 注：内容类事件还各带一个 ephemeral `eventId`（uuidv7，§E2 message identity）+ 子代理运行时的 `parentToolCallId`。`message_committed`（message-identity Phase 1）在每条可渲染消息（user/assistant/toolResult）持久化后发出其稳定的 `entryId`（= `SessionTreeEntry.id`，与 `compacted.preserved_segment.firstKeptEntryId` / E18 `resumeAt` / E19 `rewindFiles` 同一 id 空间）：消费者自建 `entryId→消息` 映射（tool result 用 `toolCallId` 关联、assistant/user 用流序），即可把 `firstKeptEntryId` 解析到「哪条渲染消息是压缩保留尾的起点」并画分隔线——无需 service 侧的 eventId↔entryId 旁路映射。

前端消费（SSE）：
```ts
for await (const ev of runner.runTaskStream(spec)) {
  if (ev.type === "reasoning_delta") ui.appendThinking(ev.delta);
  if (ev.type === "text_delta")      ui.appendAnswer(ev.delta);
  if (ev.type === "tool_start")      ui.showStatus(`调用 ${ev.toolName}…`);
  if (ev.type === "done")            ui.finalize(ev.result);   // {status,result,blockedReason,sessionId,stats}
}
```

`POST /task/stream` 把上面每个事件按 `data: <json>\n\n` 发出，语义一致。

---

## 6. 任务状态语义

`TaskResult.status` 的判定优先级（见 `assembleResult`）：

| status | 触发 | 附带字段 |
|--------|------|----------|
| `timeout` | `limits.timeoutSec` 到点被 abort（或异常发生在超时后） | `errorMessage` |
| `failed` | 抛异常 / 模型 `stopReason:"error"` / 被 abort（非超时，如 `maxTurns`）/ 无 assistant 消息 | `errorMessage` |
| `blocked` | 模型调用了内置 `report_blocked` 工具 | `blockedReason`（模型给的理由） |
| `completed` | 正常结束（`stopReason:"stop"`/`"toolUse"` 收尾） | — |

`blocked` 是给"外部 AI 大脑"看的关键信号：当 agent 缺信息/缺权限/请求歧义无法继续时，它会调用 `report_blocked({reason})`，
任务即以 `blocked` + `blockedReason` 返回。用 `enableBlockedReport: false` 可关掉该工具（则永远不会是 blocked）。

---

## 7. 安全模型（必读）

本系统会让 LLM 调用你提供的工具、查你的库、连 MCP。务必在集成层守住边界：

1. **工具只在服务端定义**。HTTP 层 (`createTaskServer`) 的请求体**不能**携带可执行工具——`execute` 是函数，不过网络。
   外部只传 `objective/sessionId/images`，`resolveSpec` 决定 model + tools。**不要**把任意工具集暴露给不可信调用方。
   - **工具策略 / 写审批（ToolPolicy）**：用 `TaskSpec.toolPolicy` 或 `RunnerDeps.toolPolicy` 在**每次工具调用前**拦截。
     ```ts
     toolPolicy: createApprovalPolicy({
       requireApproval: ["delete_order", "send_email"],   // 高危写操作
       approve: async (req) => await askOperator(req),     // 人工确认(可 await);拒则模型收到拒绝、不执行
       deny: ["drop_table"],
     });
     // 或 createAllowDenyPolicy({ allow:[...] }) / combinePolicies(...)
     ```
     被拒的工具 `execute` **绝不执行**,模型拿到拒绝原因可继续或上报。`approve` 可 await 操作员决定(`limits.timeoutSec` 兜底)。
   - **安全 ask 的结构性优先(design/80 D-2)**:被 `ToolSpec.egress`(外部写:push/开 PR/发送)或 `ToolSpec.irreversibility`(`always`/`maybe`)
     标记的工具,即便预算允许也**永远** ask——core 据**静态 spec 标记**(非可伪造的 per-call 值)铸 `irreversible_ask` 门并附
     `safetyAxis`/`riskDescriptor`(见 §4.14);budget 解析器对它永不自动批准。`TaskSpec.shellGate`(`off`/`always`/`classify`)
     按部署原则门控 hands `bash`:`classify` 下可证 benign 的只读单命令自动放行,其余(写/egress/管道/未知)收紧到 ask。
     **resume 必须重传 `shellGate`**(同 `toolPolicy`/`tools`),否则恢复后的后续 `bash` 不受门控。
2. **SQL 只读是你的责任**。`createSqlTool` 的静态校验（仅 SELECT/WITH、拒多语句/注释/DML-DDL/`INTO`/危险关键字、表白名单、行上限）
   是**纵深防御**，不是唯一保证。**必须**用只读 DB 账号（`pgQuery(readonlyPool)`）。把 `allowTables` 收到最小集。
3. **Prompt 注入防御**：用户输入与工具/MCP 返回的数据**是数据，不是指令**。本包内部已遵循此约定（subagent/team 的他人内容
   都以 `<statement>`/`<...>` 块"引用为数据"）。你的工具返回、SQL 结果同理——不要让其中的文本被当成可执行指令。
   子 agent 的 handoff 报告也是"证据待核验"，不能覆盖系统/用户策略。
4. **执行环境**：默认 `StubExecutionEnv`（无 shell、无文件系统）。若将来需要真执行 shell，自己实现 `ExecutionEnv` 并施加沙箱；
   不要随便给不可信任务开 shell。
5. **限额**：给每个任务设 `limits.timeoutSec` 和 `limits.maxTurns`，防失控循环与超长占用。
6. **鉴权**：`createTaskServer({ authorize })` 必接；按 token/来源校验。`corsOrigin` 收紧到你的 OA 域名。
7. **MCP**：任务级 MCP server 来自你的 `resolveSpec`（服务端），不要接受外部传入的任意 MCP 端点（可能是 SSRF/数据外泄面）。

---

## 8. 多 agent：subagent 与 team

> 两者都**显式告知模型**当前处于何种结构（subagent 的工具描述 + `SUBAGENT_SYSTEM_NOTE`；team 的角色提示块），
> 满足"需要显式提示说明"的要求。

### 8.1 subagent（委派，单向）

父任务把一个**自包含子任务**委派给隔离的子 agent；子在干净上下文里跑（看不到父对话），同步返回结构化报告。

```ts
import { createSubagentTool, SUBAGENT_SYSTEM_NOTE } from "@sema-ai/core";

const subagent = createSubagentTool({
  runner,
  model: "qwen",                       // 子模型（可与父不同，如更便宜）
  purpose: "隔离的检索/长任务/计算",
  tools: [ /* 子可用的工具子集 */ ],
  limits: { timeoutSec: 120 },
});

await runner.runTask({
  objective: "把 X 的调研委派给子 agent，拿到结果后汇总。",
  model: "qwen",
  systemPrompt: SUBAGENT_SYSTEM_NOTE,  // 可选：强化"你可以委派"的说明
  tools: [subagent],
});
```

子 agent 通过工具 `Agent({ description, prompt, subagent_type? })` 调起（旧名 `Task` 仍作为 alias 兼容），返回给父的工具结果形如：
```
[Sub-agent report · <taskName>]
status: completed
stats: turns=.. tokens=..

result:
<子的最终文本>

Verify this result before concluding. ...
```
父据此核验、续做或再委派。子默认 `enableBlockedReport: true`（子也能上报受阻）。

### 8.2 team（多 agent 讨论 + 收敛）

N 个角色化成员多轮讨论，最后由 synthesizer 合成结论。

```ts
import { runTeamDiscussion } from "@sema-ai/core";

const team = await runTeamDiscussion({
  runner,
  model: "qwen",                       // 默认模型（成员可各自覆盖）
  topic: "MVP 用单体还是微服务？",
  members: [
    { role: "求快的实用派" },
    { role: "可扩展性架构师", model: "qwen", systemPrompt: "你偏好长期可演进性。" },
  ],
  rounds: 2,                           // 默认 2
  synthesizer: { role: "facilitator" },// 默认中立主持合成
  onEvent: (e) => { /* member_start/member_end/synthesis_start/done */ },
  limits: { timeoutSec: 120 },
});

team.conclusion;   // 合成的最终结论
team.transcript;   // [{ round, role, text }, ...] 全过程
team.stats;        // { tokens, turns }
team.failures;     // 重试后仍失败的成员/合成轮数（失败会显式标记 [unavailable: ...]，不再静默）
```

> 健壮性：某成员一轮失败（网关错误/空结果）会**自动重试一次**；仍失败则该发言标记为 `[unavailable: <status>]`
> 并计入 `failures`，不会静默变成空发言污染讨论。

机制：每轮每个成员收到「`<team-discussion round=N your_role=X>` + 此前所有发言（以 `<statement>` 数据块引用）」，
只从本角色视角发言；成员每轮无状态（共享 transcript 提供连续性），编排简单、隔离。

**subagent vs team**：subagent = 父→子单向"干活"；team = 多成员互见多轮"讨论收敛"。

---

## 9. Session、内存化与自动压缩

- **内存化**：session 只在进程内存（`TtlSessionStore` 包 vendored `InMemorySessionRepo`）。**重启即丢**。
- **续聊**：传相同 `sessionId` → 复用该 session（带完整历史 + 模型/思考档位回放）。不传 → 新建隔离 session。
- **TTL 清理**：空闲 session 由 store 清理 —— 用 `TtlSessionStore({ defaultTtlDays })`（store 级，非 per-task）。一次性任务想立刻释放：`runner.sessions.release(sessionId)`。
- **自动压缩（零配置）**：每个任务结束后（idle 时）检查上下文 token，超阈值就用 LLM 生成结构化摘要替换旧历史
  （默认 `reserveTokens 16384 / keepRecentTokens 20000`）。可用 `TaskSpec.compactionModel` 指定更便宜的压缩模型。
  压缩对前端透明；发生时流式会有一个 `{type:"compacted"}` 事件。
- **自动裁剪**：超长工具/shell 输出在 vendored 层截断（保留头尾）。
- **MCP / skill 不持久化**：它们是"任务配置"的一部分，每次随 `TaskSpec` 传入，跑完即弃——不进 session 历史。

### 长期记忆（L2，跨会话）

session(L1) 是单段对话的工作记忆;**长期记忆(L2)** 让模型跨会话记住稳定的事实/偏好(用户/组织画像、约定)。
对标 Anthropic memory tool / CodeWhale user-memory:模型用 `remember` 工具存"声明性事实",下次任务自动注入系统提示。

```ts
import { Runner, InMemoryMemoryStore } from "@sema-ai/core";
const runner = new Runner({ brain, models, memoryStore: new InMemoryMemoryStore() }); // 生产用 TiDB 后端
const res = await runner.runTask({
  objective, model: "qwen", sessionId: chatId,
  memory: { scope: "user:42" },   // 开启;按用户/组织分租户
});
```
启用后:① 该 scope 的记忆作为 `<user_memory>` 块注入系统提示(稳定前缀);② 加一个 `remember` 工具(模型自存,
"durable 声明性事实,不存临时任务态")。后端 `MemoryStore` 可插拔(默认内存,生产实现 TiDB)。记忆是**事实不是命令**,
用户当前请求永远优先。

### 默认提示词 / harness 层

不传 `systemPrompt` 时,任务用内置 **`DEFAULT_SYSTEM_PROMPT`**(通用 agent 纪律:真相/行动/验证/工具使用强制/权威层级,
harvested from CodeWhale Constitution, MIT)。传了 `systemPrompt` 则原样用(非破坏)。可用 `RunnerDeps.promptProvider`
完全接管提示词组装;`DEFAULT_SYSTEM_PROMPT` 已导出供拼接你的领域提示。

> **⚠️ 自定义 promptProvider:用 `stableSystem`,别手工拼顺序。** 前缀缓存要求**稳定内容在前、易变内容(per-user
> memory / 时间戳 / id)在尾**;手工 `system()` 拼装很容易把 memory 放错(这个错从 core 一路继承到 service、OA)。
> 新口子让场景**只给稳定 base**,由 core 按纪律把 memory 追加到**最后**——结构上不可能摆错:
> ```ts
> // ✅ 推荐:只返回稳定 base,core 负责把 memory 放到最后
> const reviewer: PromptProvider = { stableSystem: ({ userSystemPrompt }) => `审查 harness…\n\n${userSystemPrompt ?? DEFAULT_SYSTEM_PROMPT}` };
> // ⛔ 旧式 system():你自己负责顺序(memory 必须放最后),Runner 会在放错时经 onError(phase:"prompt-cache") 报警
> ```
> - **`composeSystemPrompt(stable, memoryBlock?)`** — 把易变 memory 追加到尾的同一套纪律(core 内部就用它)。
> - **`assertPromptCacheFriendly(provider)`** / `analyzePromptCacheFriendliness(provider)` — 放进 CI/单测,
>   用两份只在 memory 处不同的提示词比对公共前缀,**自动揪出前缀污染**(任何把易变内容前置的写法,不止 memory)。
>   `stableSystem` provider 永远安全(core 拥有尾部),恒过。
- **可调阈值**：`TaskSpec.compaction = { enabled?, reserveTokens?, keepRecentTokens?, instructions? }`。
  `instructions` 会拼进摘要提示，用于**保住关键事实**（如 `"逐字保留所有代码/ID/名称/数字与用户显式指令"`）。
- **context-editing（工具结果清理，最轻）**：任务内上下文超窗口 ~70% 时，把**较旧 toolResult 的内容**替换成标记
  （保留轮次结构、保最近 N 条）。**请求级、非破坏**——session 仍存全量。对标 Anthropic（单清理 +29%）。`clearStaleToolResults` 可单用。
- **任务内安全网（context guard）**：若清理后仍超(~85%)，按滑动窗口裁剪（保留摘要+最近，绝不在 orphan toolResult 处开头），防顶爆。
- **空摘要保护**：若摘要模型返回空（网关抖动），**不会**用空摘要替换历史（避免上下文丢失），本轮跳过压缩。

> **触发时机**：自动压缩在**任务之间**（idle）与**任务内每个请求边界**（turn-boundary，1.88.0 起、默认开，
> `compaction.withinTask: false` 可关）都会触发；超长单任务（多日级）不再只靠 context guard 兜底。
> 内置防抖：连续压缩失败 3 次熔断、anti-thrash 再增长地板、病态配置自修复（`sanitizeCompactionSettings`）。
>
> ⚠️ **摘要质量取决于模型**。实测 Qwen3.5-35B(int4) 在**激进压缩**下会丢掉"很早之前、只提过一次、被大量无关内容淹没"的事实，
> 即便加了保留指令；split-turn 摘要也可能偏空。**这不是流程 bug**（流程正确性见单测），是模型摘要保真度的限制。
> OA 实践建议：① 用真实 256K 窗口（压缩极少触发，事实在原文里存活很久）② 调大 `keepRecentTokens`
> ③ 用更强的 `compactionModel` ④ 关键事实在对话中复述。`compaction.instructions` 能改善但不保证。

---

## 10. 模型网关接入

默认 `createOpenAIBrain()` 走 `model.baseUrl + "/chat/completions"`，标准 OpenAI 兼容（vLLM/Ollama/各类网关都适用）。

已验证网关：`http://172.30.228.10:8000/v1`，模型 `Qwen3.5-35B`（vLLM, MoE, 256K 上下文, 图文, reasoning）。要点：
- 流式 `delta.reasoning`（思考）已被解析成 `reasoning_delta` 事件；`delta.content`（正文）→ `text_delta`。
- 工具调用是标准 OpenAI 流式增量格式，brain 原生处理。
- 思考内容**不写回最终消息**（省 token、不回灌）。

`Model` 对象字段（`api` 取 `openai-completions` 等；详见 vendored `llm-core` 类型）：
```ts
interface Model {
  id; name; api; provider; baseUrl;
  reasoning: boolean; input: ("text"|"image")[];
  cost: { input; output; cacheRead; cacheWrite };   // $/百万 token，仅用于 stats.costUsd
  contextWindow: number; contextTokens?: number;     // 压缩预算用 contextTokens ?? contextWindow
  charsPerToken?: number;  // design/123 D2：结构估算系数（默认 4；新家族/代码密集 3、中文重 2-3），
                           // 贯穿压缩触发 fallback / 请求层防线 / cut-point 记账 / prompt-overhead
  maxTokens: number; params?; headers?; compat?; thinkingLevelMap?;
}
```

切模型/思考档位：在 `TaskSpec` 里改 `model`/`thinking` 即可（每任务独立）。

---

## 11. 扩展点

三个注入接口让你在不改核心的前提下替换实现：

1. **大脑** = `Brain.stream: StreamFn`。接非 OpenAI 协议网关 / 多 provider 路由 → 自己实现 `Brain`。
2. **持久化(session)** = `SessionStore` 接口(0.3.0 起一等公民)。`Runner` 接受任意 `SessionStore`:
   ```ts
   new Runner({ brain, sessionStore: myStore });   // 默认 TtlSessionStore(内存,7天TTL)
   ```
   要落"持久化中心"(如 TiDB):实现 `SessionStore`,其 `acquire` 从持久事件日志**重建** session(= wake/resume)。
   底层用导出的 `BaseSessionStorage`(extend 它,override `appendEntry`/`setLeafId` 落库) → `Session` → 自定义 `SessionStore`。
   导出件:`SessionStore` `AcquiredSession` `Session` `BaseSessionStorage` `InMemorySessionRepo` `InMemorySessionStorage`
   `uuidv7` + 类型 `SessionStorage` `SessionRepo` `SessionMetadata` `SessionTreeEntry`。
   (test/sessions.test.ts 有一个"DB rehearsal":落外部 map + 新进程 wake 续聊,即 TiDB 的接法。)

   > **崩溃一致性(1.2.0)**:若任务在一轮中途被打断(工具调用已落库、结果未落),wake 重建出的尾部会是一个**没有结果的 tool_call**
   > → 多数网关报 `tool_calls must be followed by tool messages`,该 session 之后每轮起不来。续聊 session 时 `Runner` 会自动调
   > `reconcileInterruptedSession()`:为悬空 tool_call 合成 `isError` 的 "interrupted, 结果未知" 结果,**绝不重放工具**,把"是否重做"交给模型。
   > 给工具标 `effect: "read" | "write" | "idempotent"`(`ToolSpec.effect`,默认 `write` 保守)可让该提示更精准——read/idempotent 安全重做,
   > write 需确认。自定义 `SessionStore` 也可在 `acquire` 里直接调用导出的 `reconcileInterruptedSession`。
   >
   > **跨实例并发的乐观锁(1.3.0)**:`appendEntry`/`setLeafId` 接受可选 `{ expectedLeafId }`(`SessionWriteOptions`)。`Session` 自动以
   > `entry.parentId` 为 expected leaf 传入;durable 后端把它实现成**条件写**(TiDB:`(session_id, seq)` 唯一键),两个实例 wake 同一 session
   > 并发 append 时输家抛 `SessionError("conflict")`(用导出的 `isSessionConflict(err)` 捕获后重试),**不会静默分叉**。
   > (快照 seam 等其余地基项见 `design/07`。)

   > **PostgreSQL reference adapters(1.94.0,`src/stores/pg.ts`)**:四个 durable seam 的现成 PG 实现,驱动中立
   > (传任意 `(text, params) => {rows}`,如 `(t, p) => pool.query(t, p)`),零新增运行时依赖:
   > ```ts
   > await ensurePgAgentSchema(q);                       // 幂等 DDL(可选 { memoryVector: { dimensions, pgvector: true } })
   > new Runner({
   >   brain,
   >   sessionStore: new TtlSessionStore({ repo: new PgSessionRepo(q) }),  // 会话中心(乐观锁=(session_id,seq)唯一键)
   >   checkpointStore: new PgCheckpointStore(q),        // design/45 durable suspend/resume(原子 CAS resolve)
   >   toolResultStore: new PgToolResultStore(q),        // durable offload(durable suspend 的前置)
   >   memoryStore: new PgMemoryStore(q, { embedder, pgvectorSql: true }), // 记忆:词面 / 进程内 cosine / pgvector SQL 三档可切
   > });
   > ```
   > 召回三档共用同一 cosine-distance 契约(score∈[0,2],0=最近),升级召回是配置切换不是重标定。
3. **执行环境** = `ExecutionEnv = FileSystem & Shell`。需要真跑 shell/远程 SSH 时实现它(vendored 有本地 `NodeExecutionEnv` 可参考;
   openclaw 有 SSH/Docker 实现思路)。当前 `StubExecutionEnv` 适用于"只用工具/MCP"的场景。
4. **提示词/harness(prompt)** = `PromptProvider`(组装整套 system+memory+harness)。可在 `Runner` 级注入,
   也可**每个任务热插拔**(1.1.0 起):`TaskSpec.promptProvider` 覆盖 `RunnerDeps.promptProvider`。
   → 一个 Runner 服务多场景、各自不同的整套 harness 提示词(用 `stableSystem`,core 自动把 memory 放尾,见上方 ⚠️):
   ```ts
   const reviewer: PromptProvider = { stableSystem: ({ userSystemPrompt }) => `...审查 harness...` };
   runner.runTask({ objective, model, promptProvider: reviewer });  // 仅本任务换整套提示词
   ```

### 默认即"零配置"(集成方可只传两个字段)

什么都不指定时,最简用法 `new Runner({ brain }).runTask({ objective, model })` 即可跑。安全/重型能力**全部 opt-in**:

| 维度 | 不指定时的默认 | 想要时怎么开 |
|------|----------------|--------------|
| session 持久化 | 内存 `TtlSessionStore`(7 天 TTL) | `new Runner({ brain, sessionStore })` |
| 工具审查/审批 | **无**(工具自由执行,适合长时自治跑) | `runTask({ toolPolicy })` |
| 记忆 | 关 | `new Runner({ brain, memoryStore })` + `runTask({ memory:{scope} })` |
| 提示词 | `DEFAULT_SYSTEM_PROMPT`(或任务 `systemPrompt`) | `promptProvider`(见上,可热插拔) |
| 上下文管理 | 自动压缩 + context-editing **开**(保证长跑不超窗) | `compaction` 调参 |
| 轮次/超时上限 | 都不设时套用 `DEFAULT_MAX_TURNS`(100,保守安全网——拦住工具死循环;长自治任务设自己的显式上限,如 leader 给 worker 设 10000/超时/预算)防跑飞;设任一即用你的边界 | `runTask({ limits: { maxTurns, timeoutSec } })`(`maxTurns:0` 关闭) |
| 审批闸超时 | 不挂死:Runner 把 `ToolPolicy.check` 与 task abort 信号 race,超时/取消必释放 | `createApprovalPolicy({ approve(req, signal?) })` 自行 race signal |

> "默认去除所有审查以保证长运行"=不传 `toolPolicy` 即得;长跑稳定性靠默认开启的压缩 + context-editing。

> **durable 挂起/恢复的诚实边界**：`durableApproval` + `CheckpointStore` 提供的是**审批边界的 human-in-the-loop 挂起/恢复 + exactly-once 续跑 + 跨副本恢复**，**不是**通用确定性重放 workflow 引擎；resume token 是单因子 bearer，高风险场景请在 `resume` 外包自己的授权。完整保证/不保证清单见 [`docs/durability-boundary.md`](docs/durability-boundary.md)。

---

## 12. 示例与自检

`src/examples/`（运行需网关可达，url-image/advanced 会起本地端口）：

```bash
npm test                              # vitest 单测+集成（mock brain，含真实 stdio MCP server），CI 友好
npm run smoke                         # mock brain e2e（循环/工具/session/续聊）
npx tsx src/examples/live.ts          # 真实网关：工具调用 + 续聊
npx tsx src/examples/features.ts      # 流式 / 图片(base64) / SQL / blocked
npx tsx src/examples/advanced.ts      # reasoning流 / subagent / team / HTTP-SSE
npx tsx src/examples/url-image.ts     # URL 图片（本地起静态服务供图）
npx tsx src/examples/team-bugs.ts     # 两个不同基础提示的 agent 讨论代码 bug
npx tsx src/examples/mcp-demo.ts      # 真实 stdio MCP server：模型发现→校验→调用→dispose
```

全部应打印 `... OK ✅`。改网关地址：编辑各示例顶部的 `model.baseUrl`。

### 测试按维度组织

`test/` 一个文件一个维度，覆盖矩阵见 [`test/COVERAGE.md`](test/COVERAGE.md)（brain / tools / tasks / sessions /
streaming / compaction / multiagent / mcp / server / concurrency / primitives）。每个发布版本都须保持全维度绿。
确定性单测用 mock brain（离线）；真实网关行为由 `src/examples/*` 手动验证。

### 构建与发布（npm 包）

源码为 TS（NodeNext, ESM）。构建产出 `dist/`（`.js` + `.d.ts`），`exports` 指向 `dist`：

```bash
npm run build     # tsc -p tsconfig.build.json → dist/
npm test          # 全维度回归（prepublishOnly 会跑 build + test）
```

**发布到 Gitea registry**（已配好：`name=@sema-ai/core`，`publishConfig.registry` 指向 Gitea，`files` 只发 `dist`+文档）：

```bash
# .npmrc（本地，已 gitignore；模板见 .npmrc.example）需带一个有 write:package 权限的 Gitea token
npm run build && npm publish     # prepublishOnly 会自动 build + 全维度 test
```

> ⚠️ 发布前提：Gitea PAT 需要 **`write:package`（+ `read:package`）** scope。仓库现用的 token 只有 org/repo 权限，
> 发布会报 `E401`。在 Gitea「设置 → 应用 → 生成令牌」勾选 package 读写即可。版本遵循 semver；原 vendored 内核 MIT，归属史见 `docs/vendor-history.md`。

---

## 13. vendored 内核与许可

- `src/core` `src/brain` `src/tools` `src/agents` `src/server` `src/engine` `src/prompts`：**本项目编写的蒸馏层**（**~24k 行**非 vendor 非 test，2026-06 已远超早期 ~1.9k）。
- `src/engine/`：first-party 引擎层（llm/loop/harness/session/compaction/execution-env；原 openclaw 蒸馏内核已全量 naturalize，历史见 `docs/vendor-history.md`）。
- 内核未发布 npm（openclaw 内部 private workspace 包），故以 vendored 源码方式纳入。
- vendored 层里"磁盘 session / nodejs-exec / 磁盘 skill"等本蒸馏层不用（`StubExecutionEnv` 代替 exec），可按需裁剪。

---

## 14. 已知限制 / TODO

- **真实 DB**：示例用假 executor；接你们库需把 `query` 换成只读连接（`pgQuery(pool)` 等）。
- **图片**：支持 base64 与 URL（URL 由 runner 进程 fetch）。无图片输出生成。
- **subagent**：当前是**同步委派**（父等子）；并行靠 `team`（fan-out/council）与 `cascade`。push-based 异步委派是后续项。
- **持久化中心**：`SessionStore` 接口（§11）+ durable suspend/resume（`CheckpointStore`，design/45/49）已就绪；具体后端（TiDB）在 `ai-agent-service` 仓实现。
- **brain**：内置 OpenAI 兼容 + Anthropic 两个适配器；其他协议自行实现 `Brain`。

> 历史备注：任务内自动压缩（超长单任务的 turn-boundary 压缩）自 **1.88.0** 起支持且**默认开启**
> （`compaction.withinTask`，§9）；更早版本只在任务之间压缩。

---

### 速查：最小可用清单

```
[ ] 一个 OpenAI 兼容网关 baseUrl + 可达
[ ] Model 对象（id / baseUrl / contextWindow / input）
[ ] new Runner({ brain: createOpenAIBrain(), models })
[ ] 工具：createSqlTool({ query: pgQuery(只读池), allowTables }) 或自定义 defineTool
[ ] createTaskServer({ runner, resolveSpec(服务端注入tools), authorize, corsOrigin }).listen(port)
[ ] 前端 POST /task/stream 消费 SSE：reasoning_delta / text_delta / tool_* / done
[ ] 每任务设 limits.timeoutSec；DB 只读；CORS/鉴权收紧
```

---
> 📍 本 README 是**消费者集成(usage)活文档**。架构/编译/bug/路线图入口见 [`docs/HANDOFF.md`](docs/HANDOFF.md)。
> **如何重验本文仍准**:`grep -c export src/index.ts`(导出面,现 105)、`npm run build && echo $?`(签名编译)、`npm test`(行为,现 3351 passed)、`grep -A3 '"dependencies"' package.json`(依赖仅 typebox+MCP)、`npm view @sema-ai/core version`(已发布版本=`1.150.0`)。最后核实 2026-06-27。