cotutor 0.2.0 → 0.4.0

package/dist/brain/api.js

@@ -0,0 +1,394 @@
+/**
+ * 脑执行的 API 实现(2026-10-29):不起 CLI,应用在服务进程里直连百炼的 Chat Completions(AI SDK + @ai-sdk/alibaba,cotutor-api-prototype 验过这条路)。
+ * - 发到哪按模型选(src/shared/qianwen.ts 的 compatibleLine):Token Plan 有这个模型、本机有 token-plan.json 就走 Token Plan(2026-11-02 起),否则百炼按量
+ * - 系统提示 = runner 给的 systemBody(老师正文或 activity + 板书写法);消息 = 上下文包 + 孩子的话,本轮的照片直接附成图,不靠老师自己去读
+ * - 同一话题的模型历史应用自己存:<日期>.<话题>.brain.jsonl,一行一轮(会话 id、模型、这轮的用户消息、模型回的全部消息、成没成);
+ *   接着话题时把同一会话的那几行拼回去。照片只记相对 workspace 根的路径,发的时候再编码。没回完的一轮只留写出来的正文,下一条消息前头注明
+ * - 拼回去的已经结束的轮是瘦过的(slimTurn):思考不带(只在本轮工具来回里回传),工具往返换成一句话;照片只附最近交的那组,更早的换成一句占位。
+ *   瘦法只由那一轮自己的记录定,下一轮发出去的开头和上一轮一样,百炼的缓存接得上;原始记录不动
+ * - 整段压缩(runner 在上下文过了 32k 的下一轮给 compact):之前的历史不再发,前情(应用照索引拼的)放在这一轮的消息前头,
+ *   最近交的照片带过来;这一轮记 compacted,以后从它算起
+ * - 工具:这轮带工具(read / on)就给只读的三样(./api-tools.ts),不带就一样没有;一轮最多来回 maxSteps 次
+ * - 思考:同 qwen 的档(low 不想、medium 想一点、high 不限;带工具的轮次至少想一点)。qwen3.8 系列和 Qwen Code 一样发 reasoning_effort(effortOf),
+ *   别的模型按 thinking_budget 卡;2026-10-31 Ray 上对照过:qwen3.8-max 卡 1024 时有照片的话题每轮想满,首句 18 秒,qwen 运行时 6 秒
+ * - .log 落统一事件(一行一条 CliEvent,parseEventLine 认),孩子端的流式板书、家长端看原文、转录、工具清单都走原来那套读法;
+ *   用量按每次请求累计,有一次没回 usage 就不记(不当成零);另记命中缓存的输入与最后一次请求的输入(这一轮结束时上下文多大)
+ * - 没有断流接着跑:流 stall.ms 没动静就停,这轮记没成(重发会把念过的再念一遍,先不做)
+ * 请求体与 key 都不落盘:报错只记状态码(SDK 的异常里带着整个请求,孩子的照片也在里面)。
+ */
+import { createAlibaba } from '@ai-sdk/alibaba';
+import { isStepCount, streamText } from 'ai';
+import { randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { appendFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
+import { getRuntime } from "./runtime.js";
+import { parseEventLine } from "./log.js";
+import { createPartialReader } from "./stream.js";
+import { parseTranscript, toolCalls, toolSummary } from "./transcript.js";
+import { isApiRuntime } from "../schema/index.js";
+import { readOnlyTools } from "./api-tools.js";
+/** 计划里记的 cli 名:API 的轮次按它分流 */
+export const API_CLI = 'api';
+/**
+ * 出厂的 API 运行时(2026-10-31 起新装缺省 api,Qwen Code 那两条留作备用):模型同那两条——api 对 qwen(qwen3.8-max),api-flash 对 qwen-flash(qwen3.8-flash)
+ */
+export const FACTORY_API_RUNTIMES = {
+    api: { api: 'bailian', model: 'qwen3.8-max' },
+    'api-flash': { api: 'bailian', model: 'qwen3.8-flash' },
+};
+const DEFAULT_STEPS = 6;
+/** 想一点:没有思考档的模型思考最多多少 token(有档的发 reasoning_effort,见 effortOf) */
+const THINK_LITTLE = 1024;
+/** 有思考档的模型:qwen3.8 系列(2026-10-31 照当时 Qwen Code 的档对过),百炼兼容接口认 reasoning_effort */
+const TIERED = /^qwen3\.8-/;
+/** 一张照片最大多少字节(百炼按 base64 收,太大的不附,记一条提醒) */
+const IMAGE_MAX = 10 * 1024 * 1024;
+const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' };
+/** 历史里模型消息的编码:AI SDK 7 的 ModelMessage 原样存;换大版本时按它转 */
+const CODEC = 'ai-sdk@7';
+/** 上一轮没回完:接在下一条消息前头 */
+const UNFINISHED = '(应用注:上一轮你没有回完,上面是写出来的那部分;孩子可能听到了一些,也可能没有,别当它已经说完。)';
+/** 政策 effort → 思考开关与思考量(同 qwen:low 不想,孩子在等;带工具的轮次至少想一点,不然照片题连资料都不查) */
+export function thinkingOf(effort, tools) {
+    if (effort === 'high')
+        return { enableThinking: true };
+    if (effort === 'medium' || tools !== 'off')
+        return { enableThinking: true, thinkingBudget: THINK_LITTLE };
+    return { enableThinking: false };
+}
+/**
+ * 有思考档的模型发 reasoning_effort(照当时 Qwen Code 的档):想一点 = low、不限 = xhigh;不想或没有档 → null,照 thinkingOf 发。
+ * low 是它自己看着想:闲聊想一两百 token,认照片题想得多;thinking_budget 是死卡,1024 时有照片的话题每轮都想满(2026-10-31)
+ */
+export function effortOf(model, effort, tools) {
+    if (!TIERED.test(model))
+        return null;
+    const t = thinkingOf(effort, tools);
+    return !t.enableThinking ? null : t.thinkingBudget ? 'low' : 'xhigh';
+}
+/** AI SDK 的 alibaba 只认 thinking_budget:在 fetch 这一层把请求体里的换成 reasoning_effort(SDK 给的中间件口子) */
+export function effortFetch(effort, base = fetch) {
+    return (input, init) => {
+        if (typeof init?.body !== 'string')
+            return base(input, init);
+        const { thinking_budget: _budget, ...body } = JSON.parse(init.body);
+        return base(input, { ...init, body: JSON.stringify({ ...body, reasoning_effort: effort }) });
+    };
+}
+/** 报错只说状态码:SDK 的异常里带着整个请求 */
+function failure(err) {
+    const status = err && typeof err === 'object' && 'statusCode' in err ? err.statusCode : undefined;
+    return typeof status === 'number' ? `api:HTTP ${status}` : 'api:请求或流断了';
+}
+const outputText = (o) => (o && typeof o === 'object' && typeof o.text === 'string' ? o.text : JSON.stringify(o) ?? '');
+const errorText = (e) => (e instanceof Error ? e.message : String(e));
+async function imagePart(file) {
+    const mediaType = MIME[extname(file).toLowerCase()];
+    if (!mediaType)
+        return '格式附不了';
+    const size = await stat(file).then((s) => s.size, () => -1);
+    if (size < 0)
+        return '不在了';
+    if (size > IMAGE_MAX)
+        return `太大(${Math.round(size / 1024 / 1024)}MB),没附`;
+    const data = await readFile(file);
+    return { type: 'file', data: `data:${mediaType};base64,${data.toString('base64')}`, mediaType };
+}
+/** 一条用户消息:文字 + 照片(相对 root 的或绝对的);附不了的照片在文字后面说一句,也进 warnings */
+async function userMessage(text, images, root, warnings) {
+    if (!images.length)
+        return { role: 'user', content: text };
+    const parts = [{ type: 'text', text }];
+    for (const p of images) {
+        const r = await imagePart(isAbsolute(p) ? p : join(root, p));
+        if (typeof r === 'string') {
+            parts.push({ type: 'text', text: `(照片 ${p} ${r})` });
+            warnings?.push(`照片 ${p} ${r}`);
+        }
+        else
+            parts.push(r);
+    }
+    return { role: 'user', content: parts };
+}
+/** 工具结果多少字;报错的给报错那句 */
+function resultOf(output) {
+    const o = (output ?? {});
+    const text = typeof o.value === 'string' ? o.value : JSON.stringify(o.value ?? '');
+    return o.type === 'error-text' || o.type === 'error-json' ? { chars: 0, error: text.slice(0, 80) } : { chars: text.length, error: null };
+}
+/**
+ * 已经结束的一轮,拼回历史时的老师那条:正文照原样,思考不带,工具往返换成一句「(用了 …,回了 N 字;结果这里不再带,要看再查)」。
+ * 只剩一条纯文字的回复,历史里永远没有配不上对的工具消息
+ */
+export function slimTurn(messages) {
+    const results = new Map();
+    for (const m of messages)
+        if (m.role === 'tool')
+            for (const p of m.content)
+                if (p.type === 'tool-result')
+                    results.set(p.toolCallId, resultOf(p.output));
+    const out = [];
+    for (const m of messages) {
+        if (m.role !== 'assistant')
+            continue;
+        if (typeof m.content === 'string') {
+            if (m.content.trim())
+                out.push(m.content.trim());
+            continue;
+        }
+        for (const p of m.content) {
+            if (p.type === 'text' && p.text.trim())
+                out.push(p.text.trim());
+            else if (p.type === 'tool-call') {
+                const what = toolSummary(p.toolName, (p.input && typeof p.input === 'object' ? p.input : {}));
+                const r = results.get(p.toolCallId);
+                out.push(r?.error ? `(用了 ${what},没成:${r.error})` : `(用了 ${what}${r ? `,回了 ${r.chars} 字` : ''};结果这里不再带,要看再查)`);
+            }
+        }
+    }
+    return out.join('\n\n') || '(这一轮没有说话)';
+}
+/**
+ * 同一会话的前几轮拼回模型消息;note = 最后一轮没回完时,接在这条消息前头的那句。
+ * 照片只附最近交的那组(这一轮自己带了照片就一张都不附),更早的换成一句占位:看图说话那种一张图聊十几轮的,图一直在。
+ * 从最近一次整段压缩的那一轮算起;这一轮要压缩(current.compact)就不拼,只回 note 与最近交的那组照片(带进压缩这一轮)
+ */
+async function pastOf(file, session, root, current) {
+    const raw = await readFile(file, 'utf8').catch(() => '');
+    const records = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (r.v === 1 && r.session === session)
+                records.push(r);
+        }
+        catch {
+            /* 写到一半的末行 */
+        }
+    }
+    records.splice(0, Math.max(0, records.map((r) => r.compacted === true).lastIndexOf(true)));
+    const withPhotos = records.map((r) => r.user.images.length > 0).lastIndexOf(true);
+    const photos = withPhotos >= 0 ? records[withPhotos].user.images : [];
+    if (current.compact)
+        return { messages: [], note: records.at(-1)?.ok === false ? UNFINISHED : null, photos };
+    const lastPhotos = current.images ? -1 : withPhotos;
+    const messages = [];
+    let note = null;
+    for (const [i, r] of records.entries()) {
+        const text = note ? `${note}\n\n${r.user.text}` : r.user.text;
+        const shown = i === lastPhotos ? r.user.images : [];
+        const gone = r.user.images.filter((p) => !shown.includes(p)).map((p) => `(照片 ${p}:前面交过,这里不再附图)`);
+        messages.push(await userMessage(gone.length ? `${text}\n\n${gone.join('\n')}` : text, shown, root));
+        note = null;
+        if (r.ok)
+            messages.push({ role: 'assistant', content: slimTurn(r.messages) });
+        else {
+            // 没回完的:工具往返不进历史(配不上对),只留写出来的正文
+            if (r.partial)
+                messages.push({ role: 'assistant', content: r.partial });
+            note = UNFINISHED;
+        }
+    }
+    return { messages, note, photos };
+}
+export class ApiBrain {
+    workspace;
+    line;
+    /** 测试与探针:…/compatible-mode/v1(假百炼);不给按模型选线 */
+    endpoint;
+    constructor(opts) {
+        this.workspace = opts.workspace;
+        this.line = opts.line;
+        this.endpoint = opts.endpoint;
+    }
+    plan(req) {
+        const { name } = getRuntime(this.workspace().config, req.runtime);
+        const session = req.session && req.session.runtime === name ? req.session.id : null;
+        return { runtime: name, cli: API_CLI, tools: req.tools, argv: [], resume: session !== null, session, env: {} };
+    }
+    start(req, plan, ctx, hooks) {
+        const reader = createPartialReader(parseEventLine);
+        const go = async () => {
+            const { config, root } = this.workspace();
+            const { runtime } = getRuntime(config, plan.runtime);
+            if (!isApiRuntime(runtime))
+                throw new Error(`运行时 ${plan.runtime} 不是 API 运行时`);
+            const { files, stall } = ctx;
+            await mkdir(dirname(files.log), { recursive: true });
+            const out = createWriteStream(files.log);
+            await writeFile(files.err, '');
+            const warnings = [];
+            const event = (e) => {
+                out.write(`${JSON.stringify(e)}\n`);
+                if (reader.apply([e]))
+                    hooks.onText();
+            };
+            hooks.onStart({ cli: API_CLI, runtime: plan.runtime, resume: plan.resume });
+            const session = plan.session ?? `api-${randomUUID()}`;
+            event({ kind: 'session', id: session });
+            const images = req.images ?? [];
+            const stored = images.map((p) => { const rel = relative(root, p); return rel.startsWith('..') || isAbsolute(rel) ? p : rel.split(sep).join('/'); });
+            const record = { v: 1, session, at: new Date().toISOString(), model: runtime.model, codec: CODEC, user: { text: req.prompt, images: stored }, messages: [], ok: false };
+            let final;
+            const line = this.line(runtime.model);
+            if (!line && !this.endpoint) {
+                final = { ok: false, text: null, reason: 'auth:没有百炼按量 key' };
+                warnings.push('百炼还没配好(按量 key):家长端「首页」里填,这位老师的运行时是 API 的,没有它说不了话');
+            }
+            else {
+                const { messages: past, note, photos } = plan.resume ? await pastOf(files.history, session, root, { images: stored.length > 0, compact: Boolean(req.compact) }) : { messages: [], note: null, photos: [] };
+                const head = [note, req.compact?.digest].filter((x) => Boolean(x)).join('\n\n');
+                const text = head ? `${head}\n\n${req.prompt}` : req.prompt;
+                // 压缩这一轮:前情与没回完的那句都在消息里了,最近交的照片带过来;记下来,以后从这一轮算起
+                const attach = req.compact && !stored.length ? photos : stored;
+                if (req.compact) {
+                    record.compacted = true;
+                    record.user = { text, images: attach };
+                }
+                const user = await userMessage(text, attach, root, warnings);
+                const tier = effortOf(runtime.model, req.effort, req.tools);
+                const alibaba = createAlibaba({ apiKey: line?.key ?? 'sk-endpoint', baseURL: this.endpoint ?? line.baseURL, includeUsage: true, ...(tier ? { fetch: effortFetch(tier) } : {}) });
+                // 断流看门狗:stall.ms 没有一块流到就停(工具在本进程里跑,几毫秒的事,不另算)
+                const abort = new AbortController();
+                let stalled = false;
+                let idle = null;
+                const arm = () => {
+                    if (idle)
+                        clearTimeout(idle);
+                    if (stall.ms)
+                        idle = setTimeout(() => { stalled = true; abort.abort(); }, stall.ms);
+                };
+                let streamError;
+                let finishReason;
+                let steps = 0;
+                let withUsage = 0;
+                let inTokens = 0;
+                let outTokens = 0;
+                let cachedTokens = 0;
+                let contextTokens = 0;
+                // 这一步的正文、工具调用与结果:步收尾时按 CLI 的先后发(整条回复,再是工具结果)
+                let stepText = '';
+                let lastText = '';
+                let thought = false;
+                let calls = [];
+                let results = [];
+                arm();
+                try {
+                    const result = streamText({
+                        model: alibaba(runtime.model),
+                        ...(req.systemBody ? { system: req.systemBody } : {}),
+                        messages: [...past, user],
+                        ...(req.tools !== 'off' ? { tools: readOnlyTools(req.readDirs, { images }) } : {}),
+                        stopWhen: isStepCount(runtime.maxSteps ?? DEFAULT_STEPS),
+                        maxRetries: 0,
+                        abortSignal: abort.signal,
+                        // 换掉 SDK 缺省的 console.error(它连请求体一起打)
+                        onError: ({ error }) => { streamError = error; },
+                        providerOptions: { alibaba: { ...thinkingOf(req.effort, req.tools), preserveThinking: true, parallelToolCalls: false } },
+                    });
+                    for await (const part of result.fullStream) {
+                        arm();
+                        if (part.type === 'start-step') {
+                            stepText = '';
+                            thought = false;
+                            calls = [];
+                            results = [];
+                            event({ kind: 'start', sub: false });
+                        }
+                        else if (part.type === 'reasoning-delta') {
+                            if (!thought)
+                                event({ kind: 'thinking', sub: false });
+                            thought = true;
+                        }
+                        else if (part.type === 'text-delta') {
+                            stepText += part.text;
+                            event({ kind: 'delta', text: part.text, sub: false });
+                        }
+                        else if (part.type === 'tool-call') {
+                            const input = (part.input && typeof part.input === 'object' ? part.input : {});
+                            calls.push({ id: part.toolCallId, name: part.toolName, input });
+                            hooks.onTool({ name: toolSummary(part.toolName, input), sub: false });
+                        }
+                        else if (part.type === 'tool-result') {
+                            results.push({ id: part.toolCallId, ok: true, text: outputText(part.output) });
+                        }
+                        else if (part.type === 'tool-error') {
+                            results.push({ id: part.toolCallId, ok: false, text: errorText(part.error) });
+                        }
+                        else if (part.type === 'finish-step') {
+                            steps++;
+                            if (part.usage.inputTokens !== undefined && part.usage.outputTokens !== undefined) {
+                                withUsage++;
+                                inTokens += part.usage.inputTokens;
+                                cachedTokens += part.usage.inputTokenDetails?.cacheReadTokens ?? 0;
+                                contextTokens = part.usage.inputTokens;
+                                outTokens += part.usage.outputTokens;
+                            }
+                            const parts = [...(stepText ? [{ type: 'text', text: stepText }] : []), ...calls.map((c) => ({ type: 'tool', tool: c }))];
+                            event({ kind: 'assistant', parts, sub: false });
+                            if (results.length)
+                                event({ kind: 'results', results, sub: false });
+                            lastText = stepText;
+                        }
+                        else if (part.type === 'finish')
+                            finishReason = part.finishReason;
+                        else if (part.type === 'error')
+                            streamError = part.error;
+                    }
+                    if (!stalled && !streamError && finishReason && finishReason !== 'error' && finishReason !== 'tool-calls')
+                        record.messages = await result.responseMessages;
+                }
+                catch (err) {
+                    if (!stalled)
+                        streamError ??= err;
+                }
+                finally {
+                    if (idle)
+                        clearTimeout(idle);
+                }
+                const usage = steps > 0 && withUsage === steps ? { inTokens, outTokens, cachedTokens, contextTokens } : {};
+                if (steps > 0 && withUsage < steps)
+                    warnings.push(`用量没回全(${steps} 次请求里 ${steps - withUsage} 次没回 usage),这轮不记 token`);
+                if (stalled) {
+                    final = { ok: false, text: null, reason: `stalled:${stall.ms}ms 没有动静`, numTurns: steps, ...usage };
+                    warnings.push(`API 流 ${stall.ms / 1000} 秒没动静,停了;这轮没收尾(不重发:念过的会再念一遍)`);
+                }
+                else if (streamError || !finishReason || finishReason === 'error') {
+                    final = { ok: false, text: null, reason: streamError ? failure(streamError) : 'api:没有收尾', numTurns: steps, ...usage };
+                }
+                else if (finishReason === 'tool-calls') {
+                    final = { ok: false, text: null, reason: `steps:来回 ${steps} 次还在用工具,到了上限`, numTurns: steps, ...usage };
+                    warnings.push(`老师一轮里用工具来回到了上限(${steps} 次),这轮没收尾;要多给几次改 cotutor.json 的 runtimes.${plan.runtime}.maxSteps`);
+                }
+                else {
+                    final = { ok: true, text: lastText.trim() || null, reason: null, numTurns: steps, ...usage };
+                    if (finishReason === 'length')
+                        warnings.push('回复到了模型的输出上限,后面截掉了');
+                    if (finishReason === 'content-filter')
+                        warnings.push('回复被模型的内容审核截住了');
+                }
+                record.ok = final.ok;
+                if (!final.ok) {
+                    const partial = reader.text().trim();
+                    if (partial)
+                        record.partial = partial;
+                    await appendFile(files.err, `cotutor: ${final.reason}\n`).catch(() => { });
+                }
+            }
+            event({ kind: 'result', final });
+            hooks.onExit(Date.now());
+            await new Promise((r) => out.end(r));
+            // 没配凭证的那轮连请求都没发:不进历史
+            if (line || this.endpoint)
+                await appendFile(files.history, `${JSON.stringify(record)}\n`).catch(() => { });
+            const logText = await readFile(files.log, 'utf8').catch(() => '');
+            const transcript = parseTranscript(logText, parseEventLine);
+            const tools = toolCalls(logText, parseEventLine).slice(0, 200);
+            return { transcript: { ...transcript, final: transcript.final ?? final }, tools, warnings };
+        };
+        return { text: () => reader.text(), done: go() };
+    }
+}

package/dist/brain/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 脑执行:一轮教学里「让脑想、写出正文」的那一步。
+ * runner 拼好上下文包与系统提示交到这里;这里请模型(应用直连百炼,./api.ts)、读输出,随流回报正文与工具,收尾给出整轮的转录。
+ * 执行完不等于这一轮交付完:板书解析、配音、记忆与日记的收尾归 runner。
+ * 2026-11-02 以前还能起 Qwen Code(命令行);那时的轮次照样读得出(./log.ts),运行时用不了了(./runtime.ts)。
+ */
+import type { ToolCall, Transcript } from './transcript.ts';
+import type { CotutorConfig, Policy } from '../schema/index.ts';
+import type { ToolSet } from './types.ts';
+import type { RunPlan } from './runtime.ts';
+import { type BrainLine } from './api.ts';
+export type { ToolKind, ToolSet } from './types.ts';
+export { toolKind } from './types.ts';
+export { parseLogLine } from './log.ts';
+export { RuntimeError, getRuntime, runtimeIssue, type RunPlan } from './runtime.ts';
+export { FACTORY_API_RUNTIMES } from './api.ts';
+/** 一轮要脑做的:哪个运行时、接哪个会话、系统提示、这条消息(上下文包 + 孩子的话)、思考量、工具 */
+export interface BrainRequest {
+    /** 运行时名,缺省 cotutor.json 的 runtimes.default */
+    runtime?: string;
+    /** 接着的会话;null = 新开 */
+    session: {
+        id: string;
+        runtime: string;
+    } | null;
+    agent: string;
+    prompt: string;
+    /** 系统提示:老师正文(或 activity)+ 板书写法 */
+    systemBody?: string;
+    effort?: Policy['effort'];
+    tools: ToolSet;
+    /** 只读工具读得到的目录(workspace 根、vault) */
+    readDirs: readonly string[];
+    /** 本轮附的照片(绝对路径),直接附成图 */
+    images?: readonly string[];
+    /** 整段压缩(上一轮结束时上下文过了 32k):之前的模型历史不再发,digest 是应用照索引拼的前情;prompt 这一轮带笔记全文 */
+    compact?: {
+        digest: string;
+    };
+}
+export interface BrainHooks {
+    onStart(s: {
+        cli: string;
+        runtime: string;
+        resume: boolean;
+    }): void;
+    /** 当前回复的正文变了(读 BrainRun.text()) */
+    onText(): void;
+    onTool(t: {
+        name: string;
+        sub: boolean;
+    }): void;
+    /** 模型回完了,还没读日志收尾;at = Date.now() */
+    onExit(at: number): void;
+}
+export interface BrainRun {
+    /** 当前这条回复的正文 */
+    text(): string;
+    done: Promise<BrainResult>;
+}
+export interface BrainResult {
+    /** final 总有:没收尾的记成没成 */
+    transcript: Transcript & {
+        final: NonNullable<Transcript['final']>;
+    };
+    /** 这轮用了哪些工具、读了什么(最多 200 条) */
+    tools: ToolCall[];
+    /** 给家长端这一轮的提醒,按出现顺序 */
+    warnings: string[];
+}
+/** 这一轮落在哪:统一事件、stderr、这个话题的模型历史 */
+export interface BrainFiles {
+    log: string;
+    err: string;
+    history: string;
+}
+export interface BrainExecutor {
+    /** 定这一轮怎么跑:哪个运行时、接不接着会话(run 文件照记) */
+    plan(req: BrainRequest): RunPlan;
+    /** 跑一轮。files:统一事件与 stderr 落哪;stall:断流看门狗 */
+    start(req: BrainRequest, plan: RunPlan, ctx: {
+        tutor: string;
+        files: BrainFiles;
+        stall: Policy['stall'];
+    }, hooks: BrainHooks): BrainRun;
+}
+/**
+ * line:这个模型发到哪、带哪把 key(runner 给 compatibleLine);endpoint:测试与探针指到假百炼(…/compatible-mode/v1)
+ */
+export declare function createBrain(opts: {
+    workspace: () => {
+        config: CotutorConfig;
+        root: string;
+    };
+    line?: BrainLine;
+    endpoint?: string;
+}): BrainExecutor;

package/dist/brain/index.js

@@ -0,0 +1,11 @@
+import { ApiBrain } from "./api.js";
+export { toolKind } from "./types.js";
+export { parseLogLine } from "./log.js";
+export { RuntimeError, getRuntime, runtimeIssue } from "./runtime.js";
+export { FACTORY_API_RUNTIMES } from "./api.js";
+/**
+ * line:这个模型发到哪、带哪把 key(runner 给 compatibleLine);endpoint:测试与探针指到假百炼(…/compatible-mode/v1)
+ */
+export function createBrain(opts) {
+    return new ApiBrain({ workspace: opts.workspace, line: opts.line ?? (() => null), endpoint: opts.endpoint });
+}

package/dist/brain/log.d.ts

@@ -0,0 +1,5 @@
+import type { CliEvent } from './types.ts';
+/** 统一事件的一行;不是这种行回 [] */
+export declare function parseEventLine(line: string): CliEvent[];
+/** .log 的一行 → 统一事件:先当统一事件,不是再当旧的 stream-json */
+export declare function parseLogLine(line: string): CliEvent[];

package/dist/brain/log.js

@@ -0,0 +1,22 @@
+/**
+ * 一轮的 .log 怎么读:API 轮次一行一条统一事件({"kind": 开头,./api.ts 写的);2026-11-02 以前的轮次是 Qwen Code 的 stream-json(./stream-json.ts)。
+ * 两种行长得不一样,一行一行认,同一份记录里换过也读得出。
+ */
+import { parseStreamJson } from "./stream-json.js";
+/** 统一事件的一行;不是这种行回 [] */
+export function parseEventLine(line) {
+    if (!line.startsWith('{"kind":'))
+        return [];
+    try {
+        const e = JSON.parse(line);
+        return typeof e.kind === 'string' ? [e] : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** .log 的一行 → 统一事件:先当统一事件,不是再当旧的 stream-json */
+export function parseLogLine(line) {
+    const e = parseEventLine(line);
+    return e.length ? e : parseStreamJson(line);
+}

package/dist/brain/runtime.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 这一轮用哪个运行时、接不接着会话。运行时只有 API 一种(`{api: "bailian", model}`,./api.ts)。
+ * 2026-11-02 起不再起命令行(Qwen Code;Claude CLI 10-28 就去掉了):旧 cotutor.json 里写着 `{run, resume}` 的照样读得进来,
+ * 但用不了——doctor 报出来,用到它的那位老师发不出去,说怎么改。以前那种运行时下聊的话题照样能看(sameRuntime:接不上、不记账)。
+ */
+import { type ApiRuntime, type CotutorConfig, type Runtime } from '../schema/index.ts';
+import type { ToolSet } from './types.ts';
+export interface RunPlan {
+    /** 运行时名(runtimes 里的键) */
+    runtime: string;
+    /** 哪种脑跑的(API 的是 api;旧轮次的 run.json 里是 CLI 的适配器名) */
+    cli: string;
+    /** 这轮带不带工具 */
+    tools: ToolSet;
+    /** 旧轮次起 CLI 的命令行;API 的是空 */
+    argv: string[];
+    /** 这次是接着会话还是新开 */
+    resume: boolean;
+    /** 接着的会话 id */
+    session: string | null;
+    env: Record<string, string>;
+}
+export declare class RuntimeError extends Error {
+}
+/** 命令行运行时(旧配置里的 `{run, resume}`)用不了,说怎么改;API 运行时 null */
+export declare function runtimeIssue(runtime: Runtime): string | null;
+export declare function getRuntime(config: CotutorConfig, name?: string): {
+    name: string;
+    runtime: ApiRuntime;
+};

package/dist/brain/runtime.js

@@ -0,0 +1,23 @@
+/**
+ * 这一轮用哪个运行时、接不接着会话。运行时只有 API 一种(`{api: "bailian", model}`,./api.ts)。
+ * 2026-11-02 起不再起命令行(Qwen Code;Claude CLI 10-28 就去掉了):旧 cotutor.json 里写着 `{run, resume}` 的照样读得进来,
+ * 但用不了——doctor 报出来,用到它的那位老师发不出去,说怎么改。以前那种运行时下聊的话题照样能看(sameRuntime:接不上、不记账)。
+ */
+import { isApiRuntime } from "../schema/index.js";
+export class RuntimeError extends Error {
+}
+/** 命令行运行时(旧配置里的 `{run, resume}`)用不了,说怎么改;API 运行时 null */
+export function runtimeIssue(runtime) {
+    return isApiRuntime(runtime) ? null : '命令行运行时(Qwen Code 等)2026-11-02 起不再支持:把 runtimes.default 和 tutors.*.runtime 改成 api 或 api-flash(应用直连百炼),再删掉这一条';
+}
+export function getRuntime(config, name) {
+    const n = name ?? config.runtimes.default;
+    const p = config.runtimes[n];
+    if (n === 'default' || !p || typeof p === 'string') {
+        const known = Object.keys(config.runtimes).filter((k) => k !== 'default');
+        throw new RuntimeError(`运行时 "${n}" 不存在;cotutor.json 的 runtimes 里有:${known.join('、')}`);
+    }
+    if (!isApiRuntime(p))
+        throw new RuntimeError(`运行时 "${n}":${runtimeIssue(p)}`);
+    return { name: n, runtime: p };
+}

package/dist/brain/stream-json.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 旧轮次的 .log:2026-11-02 以前老师的脑是起 Qwen Code(或更早的 Claude Code),输出是 stream-json(一行一个 JSON),这里读成统一事件,
+ * 那时的记录照样能看(看原文、读了什么、转录)。不再起 CLI,只读。Qwen Code 0.25 的输出:
+ * - `{"type":"system","subtype":"init","session_id","tools":[…]}`(qwen 的 json 模式叫 session_start)
+ * - `{"type":"stream_event","event":{…}}`:`--include-partial-messages` 才有;message_start 开新的一条,content_block_delta 的 text_delta 是正文、thinking_delta 是在想
+ * - `{"type":"assistant","message":{"id","content":[text / tool_use 块],"usage"}}`:一条整的回复;usage 是这一次请求自己的
+ * - `{"type":"user","message":{"content":[tool_result 块]}}`:工具结果
+ * - `{"type":"result","subtype","is_error","result","num_turns","usage"}`:收尾;记账只认 usage 的 token(total_cost_usd 有也不读)。
+ *   qwen 续会话时这里的 usage 是整个会话的累计(2026-10-30 在 ray 上量出来的:续了 28 轮的话题,索引里加起来 15.6M,实际约 1.2M),
+ *   所以 assistant 那几行的 usage 也读出来,parseTranscript 按它们加总
+ * parent_tool_use_id 非空的是子代理的。
+ */
+import type { CliEvent } from './types.ts';
+/** 结果块的文字:字符串原样,块数组拼各块的 text */
+export declare const blockText: (c: unknown) => string;
+export declare function parseStreamJson(line: string): CliEvent[];