cotutor 0.1.0 → 0.3.0

package/dist/brain/cli/qwen.js

@@ -0,0 +1,141 @@
+/**
+ * Qwen Code(`qwen`,0.25 起)的适配器。输出读法在 stream-json.ts,运行约定:
+ * - **隔离的家**:不用 `--bare`(它不读任何配置、不认 `--core-tools`、自带 read_file / edit / run_shell_command 一套)。
+ *   `QWEN_HOME` 指 workspace 的 `.cotutor/qwen/home/`(不改 HOME),里面的 settings.json 由这里生成:模型供应商(key 只写环境变量名)、
+ *   关掉它自己的记忆整理(不然一轮跑完在后台用 write_file 写文件)、使用统计、遥测、防休眠。会话落在 `.cotutor/qwen/runtime/`。
+ * - **工具**:`{toolArgs}` 展开成 `--core-tools` + `--exclude-tools`;不带 = 工具表为空,只读 = read_file / glob / grep_search。
+ *   模板带 `--approval-mode default`:shell、写、读 workspace 外都被拒(`--yolo` 会放行 workspace 外的读)。
+ * - **思考量**:没有旗标;按 effort 指一份系统配置(`QWEN_CODE_SYSTEM_SETTINGS_PATH`,`model.reasoningEffort`)。
+ * - **key 与端点**:settings.json 只写 `${COTUTOR_QWEN_BASE_URL}` 与环境变量名 `COTUTOR_QWEN_API_KEY`(qwen 读配置时展开);起进程时按 `src/shared/qianwen.ts`
+ *   定走 Token Plan 还是百炼按量,把这两个填进子进程的环境,不落盘。出厂的几个模型 Token Plan 都有,有它的 key 就走它。
+ * - 没有钱数,只报 token;超时(退出码 55)不吐 result;每轮一条 goal_state 事件(读法里不出事件)。
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { compatibleBase, qianwenKeys, qianwenLine } from "../../shared/qianwen.js";
+import { parseStreamJson, streamJsonUserMessage } from "./stream-json.js";
+const KINDS = {
+    read_file: 'read',
+    read_many_files: 'read',
+    zoom_image: 'read',
+    list_directory: 'read',
+    run_shell_command: 'shell',
+    glob: 'search',
+    grep_search: 'search',
+    edit: 'edit',
+    write_file: 'edit',
+    notebook_edit: 'edit',
+    skill: 'skill',
+};
+/** 只读那轮给的核心工具(读文件含图片、按名找、按内容找) */
+const READ_TOOLS = ['read_file', 'glob', 'grep_search'];
+/** `--core-tools` 管不到的非核心工具,要一个个排除(0.25 的 system/init 里出现过的;ask_user_question 与计划模式那两个是不加 --bare 时才有的,2026-10-09 真跑里核对出来) */
+const NON_CORE = ['agent', 'skill', 'list_agents', 'task_stop', 'send_message', 'record_artifact', 'get_goal', 'update_goal', 'tool_call', 'tool_search', 'report_findings', 'enter_worktree', 'exit_worktree', 'ask_user_question', 'enter_plan_mode', 'exit_plan_mode'];
+/** workspace 里归 qwen 的目录(机器文件,prepare 每次对一遍) */
+export const QWEN_DIR = '.cotutor/qwen';
+const homeOf = (root) => join(root, QWEN_DIR, 'home');
+const effortFile = (root, level) => join(root, QWEN_DIR, `effort-${level}.json`);
+/** 政策 effort → 模型的思考档:low 不想(孩子在等);qwen3.7 系列只有开关,none 以外都是开 */
+const EFFORT = { low: 'none', medium: 'low', high: 'xhigh' };
+/**
+ * 带工具的轮次(作业照片、记账)至少想一点:2026-10-09 真跑,同一道照片题 none 那次 read_file 都没调、请孩子说是哪页;
+ * low 那次读了图、认出题目(11 秒)。孩子随口的话不带工具,不想照旧(3–6 秒)
+ */
+const levelOf = (effort, tools) => (tools !== 'off' && EFFORT[effort] === 'none' ? 'low' : EFFORT[effort]);
+/** settings.json 里写的占位;qwen 读配置时拿子进程环境展开 */
+const BASE_ENV = 'COTUTOR_QWEN_BASE_URL';
+const KEY_ENV = 'COTUTOR_QWEN_API_KEY';
+const toggle = { thinking: true, toggleOnly: true, disableField: 'enable_thinking' };
+const tiers = { thinking: true, efforts: ['low', 'medium', 'xhigh'], defaultEffort: 'xhigh', disableField: 'reasoning_effort' };
+/** 出厂模型(2026-10-09 五个模型 7 道真题对比:不想时 2–8 秒,讲得准也细;3.7-plus 快但浅,3.8-flash 不想时把盘算写进讲稿——
+ * 2026-10-13 英语老师三问没再见到,出厂 qwen-flash 运行时给英语老师) */
+export const QWEN_DEFAULT_MODEL = 'qwen3.8-max';
+/** 千问上能用的几个(Token Plan 与百炼按量都有);运行时模板的 -m 选其中一个 */
+const MODELS = [
+    { id: 'qwen3.7-plus', capabilities: { reasoning: toggle }, generationConfig: { contextWindowSize: 1_000_000, modalities: { image: true } } },
+    { id: 'qwen3.7-max', capabilities: { reasoning: toggle }, generationConfig: { contextWindowSize: 1_000_000 } },
+    { id: 'qwen3.8-flash', capabilities: { reasoning: tiers }, generationConfig: { contextWindowSize: 1_000_000, modalities: { image: true, video: true } } },
+    { id: 'qwen3.8-max', capabilities: { reasoning: tiers }, generationConfig: { contextWindowSize: 1_000_000, modalities: { image: true, video: true } } },
+];
+/** 隔离的家里那份 settings.json(没有 key,只写环境变量名) */
+export function qwenHomeSettings() {
+    return {
+        $version: 4,
+        security: { auth: { selectedType: 'openai' } },
+        model: { name: QWEN_DEFAULT_MODEL },
+        modelProviders: { openai: MODELS.map((m) => ({ ...m, baseUrl: `\${${BASE_ENV}}`, envKey: KEY_ENV })) },
+        memory: { enableManagedAutoMemory: false, enableManagedAutoDream: false },
+        privacy: { usageStatisticsEnabled: false },
+        telemetry: { enabled: false },
+        general: { disableAutoUpdate: true, disableUpdateNag: true, preventSystemSleep: false },
+    };
+}
+/** 这几份机器文件:绝对路径 → 内容 */
+export function qwenFiles(root) {
+    const files = {
+        // 整个目录不进 git:会话记录(runtime/)是对话原文,同 conversations/ 只留本机;其余都是这里每次重新生成的
+        [join(root, QWEN_DIR, '.gitignore')]: '# qwen 的隔离家目录与会话记录(cotutor 生成,对话原文只留本机)\n*\n',
+        [join(homeOf(root), 'settings.json')]: `${JSON.stringify(qwenHomeSettings(), null, 2)}\n`,
+    };
+    for (const level of new Set(Object.values(EFFORT)))
+        files[effortFile(root, level)] = `${JSON.stringify({ $version: 4, model: { reasoningEffort: level } }, null, 2)}\n`;
+    return files;
+}
+/** 别处的设置会盖掉家里选的模型与供应商,起进程时去掉 */
+const FOREIGN = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_MODEL', 'QWEN_MODEL'];
+export const qwen = {
+    name: 'qwen',
+    parse: parseStreamJson,
+    stdinMessage: streamJsonUserMessage,
+    // qwen 的带工具只有只读一档(read / on 一样):shell 与写本来就不给
+    toolList: (set) => (set !== 'off' ? READ_TOOLS.join(',') : ''),
+    // --core-tools 是白名单,不带时也要给一个(给空等于不限),再把它排除掉;非核心工具不归 --core-tools 管,总要排除。
+    // 只读那轮把 workspace 根与 vault 加进可读范围:会话 cwd 是老师目录,作业照片(captures/)与教材在它外面,读外面要征得同意——
+    // 消息走 stdin 时它就停在那儿等,一直等到 --max-wall-time(2026-10-09 真跑,开了思考的那次读照片挂住)
+    toolArgs: (set, { readDirs }) => set !== 'off'
+        ? ['--core-tools', READ_TOOLS.join(','), '--exclude-tools', NON_CORE.join(','), ...readDirs.flatMap((d) => ['--include-directories', d])]
+        : ['--core-tools', 'read_file', '--exclude-tools', ['read_file', ...NON_CORE].join(',')],
+    toolKind: (name) => KINDS[name] ?? 'other',
+    expectedTools: (set) => (set !== 'off' ? READ_TOOLS : []),
+    planEnv: ({ root, effort, tools }) => root ? { QWEN_HOME: homeOf(root), QWEN_RUNTIME_DIR: join(root, QWEN_DIR, 'runtime'), QWEN_CODE_SYSTEM_SETTINGS_PATH: effortFile(root, levelOf(effort, tools)) } : {},
+    async prepare(root) {
+        for (const [file, text] of Object.entries(qwenFiles(root))) {
+            if ((await readFile(file, 'utf8').catch(() => null)) === text)
+                continue;
+            await mkdir(dirname(file), { recursive: true });
+            await writeFile(file, text);
+        }
+    },
+    env: (env) => {
+        const out = { ...env, QWEN_USAGE_STATISTICS_ENABLED: 'false', QWEN_CODE_MODELS_DEV: 'off', QWEN_CODE_SUPPRESS_YOLO_WARNING: '1' };
+        for (const k of FOREIGN)
+            delete out[k];
+        const line = qianwenLine(QWEN_DEFAULT_MODEL, qianwenKeys(out));
+        if (line) {
+            out[BASE_ENV] = compatibleBase(line.host);
+            out[KEY_ENV] = line.key;
+        }
+        return out;
+    },
+    check: ({ version, env }) => {
+        const v = /(\d+)\.(\d+)\.(\d+)/.exec(version);
+        const old = !v || Number(v[1]) === 0 && Number(v[2]) < 25;
+        const line = qianwenLine(QWEN_DEFAULT_MODEL, qianwenKeys(env));
+        return [
+            { name: 'version', ok: !old, detail: old ? `qwen ${version || '?'}:要 0.25 起(关工具的旗标、隔离的家、思考量配置都按 0.25 定的)` : `qwen ${version}`, fix: old ? 'qwen update(或 brew upgrade qwen-code)' : undefined },
+            line
+                ? { name: 'key', ok: true, detail: line.plan ? '走千问 Token Plan(QWENCLOUD_TOKEN_PLAN_API_KEY)' : '走百炼按量(DASHSCOPE_API_KEY,或本机 qwen / voxtell 的配置)' }
+                : { name: 'key', ok: false, detail: '千问的 key 一把都拿不到:老师进程起来就会 401', fix: '在起 serve 的 shell 里 export QWENCLOUD_TOKEN_PLAN_API_KEY(Token Plan,sk-sp-)或 DASHSCOPE_API_KEY(百炼按量)' },
+        ];
+    },
+    runtimes: () => {
+        // 消息走 stdin(预热能用;数组旗标 --core-tools 之类会吞掉跟在后面的消息,不进 argv 正好避开);-m 选模型(家里那份 settings.json 列着的);
+        // {systemBody} = 老师正文 + 板书写法,整份换掉 qwen 自己的系统提示;{toolArgs} 由适配器展开;--approval-mode default:shell、写、读 workspace 外都拒
+        // qwen-flash 只差模型(2026-10-13 英语老师出厂走它:Token Plan 上便宜、开口 2.5–4 秒)
+        const of = (model) => {
+            const flags = ['-m', model, '--system-prompt', '{systemBody}', '--input-format', 'stream-json', '--output-format', 'stream-json', '--include-partial-messages', '--approval-mode', 'default', '{toolArgs}', '--max-wall-time', '10m'];
+            return { stdin: 'stream-json', run: ['qwen', ...flags], resume: ['qwen', '--resume', '{session}', ...flags] };
+        };
+        return { qwen: of(QWEN_DEFAULT_MODEL), 'qwen-flash': of('qwen3.8-flash') };
+    },
+};

package/dist/brain/cli/run-plan.d.ts

@@ -0,0 +1,59 @@
+import { streamJsonUserMessage } from './stream-json.ts';
+import type { ToolSet } from './types.ts';
+import { type ConversationIndex, type CotutorConfig, type Policy, type Runtime } from '../../schema/index.ts';
+export interface RunPlan {
+    /** 运行时名(runtimes 里的键) */
+    runtime: string;
+    /** 适配器名(src/brain/cli/;认不出的是 stream-json) */
+    cli: string;
+    /** 这轮带不带工具(模板管不了工具的运行时也照记,只是没用上) */
+    tools: ToolSet;
+    /** 完整命令行,argv[0] 是可执行文件 */
+    argv: string[];
+    /** 这次是 resume 还是新开 */
+    resume: boolean;
+    /** resume 的会话 id */
+    session: string | null;
+    /** 运行时 stdin: "stream-json":要写进 stdin 的那一行(用户消息,带换行);消息不在 argv 里 */
+    stdin?: string;
+    /** 适配器按这轮的计划定的环境变量(qwen 的思考量配置之类);和 argv 一起进预热的比对 */
+    env: Record<string, string>;
+}
+export declare class RuntimeError extends Error {
+}
+export declare function getRuntime(config: CotutorConfig, name?: string): {
+    name: string;
+    runtime: Runtime;
+};
+/** 模板里有没有用到某个占位符(决定要不要去读老师正文)。API 运行时没有模板:系统提示由应用给,算用了 {systemBody} */
+export declare function runtimeUses(runtime: Runtime, placeholder: string): boolean;
+/**
+ * 这个运行时把板书写法预载进系统提示了吗:模板用了 {boardFile} / {systemBody},或者(2026-09-19 头一版)写死了 cotutor-board/SKILL.md 的路径。
+ * 没有 → 应用在话题第一条注入 <cotutor-board>。
+ */
+export declare function boardPreloaded(runtime: Runtime): boolean;
+export declare function planRun(config: CotutorConfig, index: Pick<ConversationIndex, 'session'>, vars: {
+    agent: string;
+    prompt: string;
+    agentBody?: string;
+    systemBody?: string;
+    boardFile?: string;
+    runtime?: string;
+    effort?: Policy['effort'];
+    tools?: ToolSet;
+    root?: string;
+    readDirs?: readonly string[];
+}): RunPlan;
+/** stream-json 输入的一条用户消息(Qwen 的 `--input-format stream-json` 一行一条;别的 CLI 看它的适配器) */
+export declare const stdinMessage: typeof streamJsonUserMessage;
+/**
+ * 断流后接着跑的那条消息(policy.stall):resume 同一个会话发给老师。被杀的那段回复只流到了 stdout,没进会话,
+ * 所以断在半截的正文(open)原样递回去,让它从断处接着写;应用把 open 拼在这次的收尾正文前面。
+ * open 为空 = 这一段一个字没出来,已经做完的工具调用与整段都在会话里,接着把这一轮做完。
+ */
+export declare function stallPrompt(open: string): string;
+/**
+ * 老师把工具调用写成了正文、停在那里等结果(这轮没给它那个工具,qwen 照自己的格式写出来;板书解析器把那块剥掉了):
+ * resume 同一个会话,告诉它不会有结果,接着直接回孩子。那块前面写的话已经进了会话,应用拼在这次的前面
+ */
+export declare function toolLeakPrompt(): string;

package/dist/brain/cli/run-plan.js

@@ -0,0 +1,71 @@
+/**
+ * 一次运行的命令规划(纯函数):按运行时选 run 还是 resume、填占位符、定 cwd 相对路径。
+ * 规则:当天索引里已有会话**且**是同一运行时跑出来的 → resume;否则新开(跨天索引本来就是新的,零点后第一条自然不带 --resume;
+ * 换了运行时也新开——不同运行时的会话不混用)。{agentBody} 只给模板里真用到它的运行时读老师正文。
+ */
+import { adapterFor, fillArgs } from "./adapters.js";
+import { streamJsonUserMessage } from "./stream-json.js";
+import { POLICY_DEFAULTS, isApiRuntime } from "../../schema/index.js";
+export class RuntimeError extends Error {
+}
+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('、')}`);
+    }
+    return { name: n, runtime: p };
+}
+/** 模板里有没有用到某个占位符(决定要不要去读老师正文)。API 运行时没有模板:系统提示由应用给,算用了 {systemBody} */
+export function runtimeUses(runtime, placeholder) {
+    if (isApiRuntime(runtime))
+        return placeholder === '{systemBody}';
+    return [...runtime.run, ...runtime.resume].some((a) => a.includes(placeholder));
+}
+/**
+ * 这个运行时把板书写法预载进系统提示了吗:模板用了 {boardFile} / {systemBody},或者(2026-09-19 头一版)写死了 cotutor-board/SKILL.md 的路径。
+ * 没有 → 应用在话题第一条注入 <cotutor-board>。
+ */
+export function boardPreloaded(runtime) {
+    return runtimeUses(runtime, '{boardFile}') || runtimeUses(runtime, '{systemBody}') || runtimeUses(runtime, 'cotutor-board/SKILL.md');
+}
+export function planRun(config, index, vars) {
+    const { name, runtime } = getRuntime(config, vars.runtime);
+    if (isApiRuntime(runtime))
+        throw new RuntimeError(`运行时 "${name}" 是 API 运行时,不起命令行(src/brain/api.ts)`);
+    const adapter = adapterFor(runtime);
+    const session = index.session && index.session.runtime === name ? index.session.id : null;
+    const template = session ? runtime.resume : runtime.run;
+    const effort = vars.effort ?? POLICY_DEFAULTS.effort;
+    return {
+        runtime: name,
+        cli: adapter.name,
+        tools: vars.tools ?? 'on',
+        argv: fillArgs(adapter, template, { agent: vars.agent, prompt: vars.prompt, session: session ?? undefined, agentBody: vars.agentBody, systemBody: vars.systemBody, boardFile: vars.boardFile, effort: vars.effort, tools: vars.tools, readDirs: vars.readDirs }),
+        resume: session !== null,
+        session,
+        ...(runtime.stdin ? { stdin: adapter.stdinMessage(vars.prompt) } : {}),
+        env: adapter.planEnv?.({ root: vars.root, effort, tools: vars.tools ?? 'on' }) ?? {},
+    };
+}
+/** stream-json 输入的一条用户消息(Qwen 的 `--input-format stream-json` 一行一条;别的 CLI 看它的适配器) */
+export const stdinMessage = streamJsonUserMessage;
+/**
+ * 断流后接着跑的那条消息(policy.stall):resume 同一个会话发给老师。被杀的那段回复只流到了 stdout,没进会话,
+ * 所以断在半截的正文(open)原样递回去,让它从断处接着写;应用把 open 拼在这次的收尾正文前面。
+ * open 为空 = 这一段一个字没出来,已经做完的工具调用与整段都在会话里,接着把这一轮做完。
+ */
+export function stallPrompt(open) {
+    const rule = '不道歉,不提断了,不重复前面的。';
+    return open
+        ? `(应用注)你刚才那段回复传到一半网络断了。孩子那边已经看到、听到的就是下面 <<< 与 >>> 之间这些:\n<<<\n${open}\n>>>\n从断的地方直接接着写,字要接得上;${rule}`
+        : `(应用注)你刚才那段回复网络断了,一个字没传出来。已经做完的工具调用和写完的段都还在,接着把这一轮做完;${rule}`;
+}
+/**
+ * 老师把工具调用写成了正文、停在那里等结果(这轮没给它那个工具,qwen 照自己的格式写出来;板书解析器把那块剥掉了):
+ * resume 同一个会话,告诉它不会有结果,接着直接回孩子。那块前面写的话已经进了会话,应用拼在这次的前面
+ */
+export function toolLeakPrompt() {
+    return '(应用注)你刚才写的工具调用没有执行,孩子也看不到。这一轮不用工具,接着直接回孩子;不提工具,不道歉,不重复前面的。';
+}

package/dist/brain/cli/run.d.ts

@@ -0,0 +1,35 @@
+import { type RunPlan } from './run-plan.ts';
+import type { CliRuntime, CotutorConfig, Policy } from '../../schema/index.ts';
+import type { BrainExecutor, BrainHooks, BrainRequest, BrainRun, WarmKey } from '../index.ts';
+import { type Slot } from './warm.ts';
+export declare class CliBrain implements BrainExecutor {
+    private readonly spares;
+    private readonly workspace;
+    /** 起子进程用的环境(测试注入);缺省 process.env */
+    private readonly env;
+    constructor(opts: {
+        workspace: () => {
+            config: CotutorConfig;
+            root: string;
+        };
+        env?: NodeJS.ProcessEnv;
+        warmIdleMs?: number;
+    });
+    plan(req: BrainRequest): RunPlan;
+    prepare(plan: RunPlan): Promise<void>;
+    canWarm(runtime: CliRuntime): boolean;
+    warm(tutor: string, slot: Slot, plan: RunPlan, key: WarmKey): void;
+    warmed(tutor: string, slot?: Slot): boolean;
+    dropWarm(tutor: string, slot?: Slot): void;
+    close(): void;
+    private processEnv;
+    start(req: BrainRequest, plan: RunPlan, ctx: {
+        tutor: string;
+        key: WarmKey;
+        files: {
+            log: string;
+            err: string;
+        };
+        stall: Policy['stall'];
+    }, hooks: BrainHooks): BrainRun;
+}

package/dist/brain/cli/run.js

@@ -0,0 +1,256 @@
+/**
+ * 脑执行的 CLI 实现:按 cotutor.json 的运行时起老师进程(qwen 之类,读输出、关工具、环境都在同目录的适配器 adapters.ts 与各家的文件),
+ * stream-json 落 <日期>.<job>.log、stderr 落 .err.log;每行读成统一事件,一行只解析一次,同一批事件给拼正文、工具、会话 id 用。
+ * - 预热(./warm.ts):消息走 stdin 的运行时,下一轮的进程提前起好,对得上就接过来
+ * - 断流看门狗:stall.ms 没吐一个字节、也没有工具在跑 → 杀掉,resume 同一个会话接着写(最多 stall.retries 次)。
+ *   CLI 自己的断流重试可能要等很久(2026-09-21 真跑一轮连断两次,等了 6 分钟)
+ * - 回复停在写成正文的工具调用上(这轮没给它那个工具,qwen 照自己的格式写出来):resume 同一个会话告诉它不会有结果、接着回孩子,只一次
+ * - 收尾:从 .log 读整轮转录;断流接着跑的,断在半截的那段拼回最后一段前面
+ */
+import { spawn } from 'node:child_process';
+import { closeSync, createWriteStream, openSync, writeSync } from 'node:fs';
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { parserOf, prepareCli, processEnv, toolsOf, unexpectedTools } from "./adapters.js";
+import { planRun, stallPrompt, toolLeakPrompt } from "./run-plan.js";
+import { createPartialReader } from "../stream.js";
+import { parseTranscript, toolCalls, toolSummary } from "../transcript.js";
+import { WarmPool } from "./warm.js";
+const cliName = (p) => p.argv[0].slice(p.argv[0].lastIndexOf('/') + 1);
+export class CliBrain {
+    spares;
+    workspace;
+    /** 起子进程用的环境(测试注入);缺省 process.env */
+    env;
+    constructor(opts) {
+        this.workspace = opts.workspace;
+        this.env = opts.env;
+        this.spares = new WarmPool({ idleMs: opts.warmIdleMs });
+    }
+    plan(req) {
+        const { config, root } = this.workspace();
+        return planRun(config, { session: req.session }, { agent: req.agent, prompt: req.prompt, agentBody: req.agentBody, systemBody: req.systemBody, boardFile: req.boardFile, runtime: req.runtime, effort: req.effort, tools: req.tools, root, readDirs: req.readDirs });
+    }
+    prepare(plan) {
+        return prepareCli(plan.cli, this.workspace().root).catch(() => { });
+    }
+    canWarm(runtime) {
+        return Boolean(runtime.stdin);
+    }
+    warm(tutor, slot, plan, key) {
+        this.spares.warm(tutor, slot, { argv: plan.argv, env: plan.env, ...key }, this.processEnv(plan));
+    }
+    warmed(tutor, slot) {
+        return this.spares.has(tutor, slot);
+    }
+    dropWarm(tutor, slot) {
+        this.spares.drop(tutor, slot);
+    }
+    close() {
+        this.spares.dropAll();
+    }
+    processEnv(p) {
+        return processEnv(p, { ...(this.env ?? process.env), COTUTOR_WORKSPACE: this.workspace().root });
+    }
+    start(req, plan, ctx, hooks) {
+        // 预热的进程:resume 的接那个位置(对得上 = 这个话题从它起来之后没人写过),新开的接 fresh;对不上(或这轮不走 stdin)就杀掉
+        const spare = this.spares.claim(ctx.tutor, plan.resume ? 'resume' : 'fresh', { argv: plan.argv, env: plan.env, ...ctx.key });
+        // 断流接着跑:carried = 被杀那次已经拼出的正文(接着跑的那次换新读取器,正文 = carried + 新的);
+        // open = 断在半截、没进会话的那段(递回给老师,收尾时拼在最后一段前面)
+        let reader = createPartialReader();
+        let carried = '';
+        let open = '';
+        const liveText = () => { const t = reader.text(); return !carried ? t : !t ? carried : open ? carried + t : `${carried}\n\n${t}`; };
+        const resumePlan = (id, prompt) => this.plan({ ...req, runtime: plan.runtime, session: { id, runtime: plan.runtime }, prompt });
+        const stall = ctx.stall;
+        const files = ctx.files;
+        const cwd = ctx.key.cwd;
+        const go = async () => {
+            await mkdir(cwd, { recursive: true });
+            const out = createWriteStream(files.log);
+            const err = openSync(files.err, 'w');
+            hooks.onStart({ cli: cliName(plan), runtime: plan.runtime, resume: plan.resume, ...(spare ? { warmBornAt: spare.bornAt } : {}) });
+            // 工具调用回报一条(子代理的标 sub);顺手记哪些顶层工具还没回结果:工具在跑时进程不吐字是正常的,断流看门狗不算这段
+            const parse = parserOf(plan.cli);
+            let lineBuf = '';
+            const toolsRunning = new Set();
+            // 消息走 stdin 的运行时:看到收尾就关 stdin,进程自己退(每次 runOnce 换一个)
+            let onResult = null;
+            // 进程起来报的工具表里不该有的(适配器核对;不带工具那轮却有工具 = 关工具的旗标失效了,CLI 升版本最先坏的地方)
+            let unexpected = [];
+            let session = plan.session;
+            // 新会话要等模型开始回了(开始回复、吐字、在想、整条回复)才在盘上、才 resume 得了
+            // (2026-09-22 真跑:init 吐了会话 id 就被杀,resume 报 No conversation found;吐过三个字再杀,盘上有这条用户消息)
+            let persisted = plan.resume;
+            let stalls = 0;
+            // warm:预热好的进程(只给第一次;断流接着跑的那次照旧冷起)
+            const runOnce = (p, warm = null) => new Promise((resolveExit) => {
+                // 被杀的那次没收完的半行不要了
+                lineBuf = '';
+                const child = warm?.child ?? spawn(p.argv[0], p.argv.slice(1), {
+                    cwd,
+                    env: this.processEnv(p),
+                    stdio: [p.stdin ? 'pipe' : 'ignore', 'pipe', err],
+                });
+                if (warm) {
+                    // 预热的进程 stderr 是管道(起它时还没有这轮的 err.log):攒下的和之后的都写进来(池子交出来时暂停着,这里 resume)
+                    const toErr = (c) => { try {
+                        writeSync(err, c);
+                    }
+                    catch { /* err.log 已关 */ } };
+                    warm.stderr.forEach(toErr);
+                    child.stderr?.on('data', toErr);
+                    child.stderr?.resume();
+                }
+                if (p.stdin) {
+                    child.stdin?.on('error', () => { });
+                    child.stdin?.write(p.stdin);
+                    onResult = () => { onResult = null; child.stdin?.end(); };
+                }
+                else
+                    onResult = null;
+                let stalled = false;
+                let idle = null;
+                let lastByte = Date.now();
+                const arm = () => {
+                    if (idle)
+                        clearTimeout(idle);
+                    if (!stall.ms)
+                        return;
+                    idle = setTimeout(() => {
+                        idle = null;
+                        if (toolsRunning.size)
+                            return arm();
+                        stalled = true;
+                        child.kill('SIGTERM');
+                        setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                            child.kill('SIGKILL'); }, 2000).unref();
+                    }, stall.ms);
+                };
+                arm();
+                child.stdout?.on('data', (chunk) => {
+                    lastByte = Date.now();
+                    arm();
+                    out.write(chunk);
+                    lineBuf += chunk.toString('utf8');
+                    const lines = lineBuf.split('\n');
+                    lineBuf = lines.pop() ?? '';
+                    let changed = false;
+                    for (const line of lines) {
+                        const events = parse(line);
+                        for (const e of events) {
+                            if (e.kind === 'session') {
+                                if (!session)
+                                    session = e.id;
+                            }
+                            else if (e.kind === 'init')
+                                unexpected = unexpectedTools(plan.cli, plan.tools, e.tools);
+                            else if (e.kind === 'result')
+                                onResult?.();
+                            else if (e.kind === 'results') {
+                                if (!e.sub)
+                                    for (const r of e.results)
+                                        toolsRunning.delete(r.id);
+                            }
+                            else {
+                                if (e.kind === 'start' || e.kind === 'delta' || e.kind === 'thinking' || e.kind === 'assistant')
+                                    persisted = true;
+                                if (e.kind === 'assistant')
+                                    for (const tool of toolsOf(e.parts)) {
+                                        if (!e.sub && tool.id)
+                                            toolsRunning.add(tool.id);
+                                        hooks.onTool({ name: toolSummary(tool.name, tool.input), sub: e.sub });
+                                    }
+                            }
+                        }
+                        if (reader.apply(events))
+                            changed = true;
+                    }
+                    if (changed)
+                        hooks.onText();
+                });
+                const done = (r) => {
+                    if (idle)
+                        clearTimeout(idle);
+                    resolveExit({ ...r, ...(stalled ? { stalled: true } : {}) });
+                };
+                child.once('error', (e) => done({ code: null, spawnError: e }));
+                child.once('close', (code) => { if (stalled)
+                    void appendFile(files.err, `cotutor: ${Date.now() - lastByte}ms 没有输出,当断流杀掉\n`).catch(() => { }); done({ code }); });
+                if (warm) {
+                    // 开口前吐的按顺序补喂,再放开暂停;接手之前就退了的,close 已经错过,直接收尾
+                    for (const c of warm.stdout)
+                        child.stdout?.emit('data', c);
+                    child.stdout?.resume();
+                    if (warm.closed())
+                        done({ code: child.exitCode });
+                }
+            });
+            let exit = await runOnce(plan, spare);
+            while (exit.stalled) {
+                stalls++;
+                if (persisted)
+                    open += reader.current();
+                else {
+                    session = plan.session;
+                    open = '';
+                }
+                const retry = stalls <= stall.retries ? stalls : 0;
+                hooks.onStall({ idleMs: stall.ms, retry, kept: Array.from(open).length });
+                if (!retry)
+                    break;
+                carried = persisted ? liveText() : '';
+                reader = createPartialReader();
+                toolsRunning.clear();
+                // 会话还没落盘(进程起来就卡住、一条整的回复都没有):原样从头再起一次;落了盘就 resume 接着写
+                const next = persisted && session ? resumePlan(session, stallPrompt(open)) : plan;
+                hooks.onStart({ cli: cliName(next), runtime: next.runtime, resume: next.resume });
+                exit = await runOnce(next);
+            }
+            // 回复停在写成正文的工具调用上(板书解析器已剥掉,孩子没看到):老师在等结果,resume 同一个会话告诉它不会有结果、接着回孩子,只一次。
+            // 这次的正文接在前面那段后面
+            let leaked = '';
+            if (!exit.stalled && exit.code === 0 && session && req.stuckOnTool?.(liveText())) {
+                leaked = liveText();
+                carried = leaked;
+                open = '';
+                reader = createPartialReader();
+                toolsRunning.clear();
+                const next = resumePlan(session, toolLeakPrompt());
+                hooks.onStart({ cli: cliName(next), runtime: next.runtime, resume: next.resume });
+                exit = await runOnce(next);
+            }
+            hooks.onExit(Date.now());
+            await new Promise((r) => out.end(r));
+            closeSync(err);
+            if (exit.spawnError)
+                await appendFile(files.err, `cotutor: 起不来 ${plan.argv[0]}:${exit.spawnError.message}\n`);
+            const logText = await readFile(files.log, 'utf8').catch(() => '');
+            const transcript = parseTranscript(logText, parse);
+            // 断流接着跑的:断在半截的那段没进会话、也不在最后的 result 里,拼回最后一段前面(老师是从断处接着写的)
+            // (result 的正文被 trim 过,断在句末 / 围栏上的补回换行,免得两句粘成一行)
+            if (open && transcript.final?.text)
+                transcript.final.text = open + (/[。!！?？;；`\n]\s*$/.test(open) ? '\n' : '') + transcript.final.text;
+            if (leaked && transcript.final?.text)
+                transcript.final.text = `${leaked}\n\n${transcript.final.text}`;
+            if (exit.stalled && !transcript.final)
+                transcript.final = { text: null, ok: false, reason: `stalled:${stalls} 次断流(每次 ${stall.ms}ms 没输出),接着跑的次数用完了` };
+            // 这轮用了哪些工具、读了什么:从 .log 抽出来物化(家长端「看原文」一站、cotutor show)
+            const tools = toolCalls(logText, parse).slice(0, 200);
+            if (!transcript.final) {
+                // 进程退了但没有 result 事件:起不来、被杀、或 CLI 崩了;标 error,原因指向 err.log
+                transcript.final = { text: null, ok: false, reason: exit.spawnError ? `spawn:${exit.spawnError.message}` : `exit:${exit.code ?? 'signal'}` };
+                transcript.items.push({ kind: 'done', text: `本轮没有收尾(${transcript.final.reason}),看 ${basename(files.err)}` });
+            }
+            const warnings = [];
+            if (unexpected.length)
+                warnings.push(`${plan.cli} 起来时带着这轮不该有的工具:${unexpected.join('、')}(${plan.tools === 'off' ? '这轮应该一个工具都不带' : '这轮只该带只读的几样'});关工具的旗标可能随 CLI 升级失效了,看 src/brain/cli/${plan.cli}.ts`);
+            if (leaked)
+                warnings.push('老师把工具调用写成了正文、停在那里等结果(板上没出、嘴没念),应用 resume 同一个会话叫它直接回孩子');
+            if (stalls)
+                warnings.push(`API 流断了 ${stalls} 次(每次 ${stall.ms / 1000} 秒没动静),应用杀掉进程、resume 会话接着写的${exit.stalled ? ';次数用完还断,这轮没收尾' : ''}`);
+            return { transcript: { ...transcript, final: transcript.final }, tools, warnings };
+        };
+        return { warm: Boolean(spare), text: liveText, done: go() };
+    }
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Qwen Code 的 stream-json(`--output-format stream-json`,一行一个 JSON)读成统一事件。
+ * 同时保留历史日志的费用字段解析,让已有对话仍能查看。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[];
+/** stream-json 输入的一条用户消息(`--input-format stream-json` 一行一条) */
+export declare function streamJsonUserMessage(prompt: string): string;