cotutor 0.2.0 → 0.3.0

package/dist/board/sections.js

@@ -0,0 +1,130 @@
+/**
+ * 最终文本里的「## 记账」「## 记忆」段:剥出来给应用,剩下的是给孩子的话。
+ * 宽容解析:段在但解析不出(没有 thread、没有 name…)就整段留在正文里——格式是增强不是门槛。
+ */
+import { BOOKKEEPING_HEADING, BookkeepingSchema, MEMORY_HEADING } from "../schema/index.js";
+const unquote = (s) => {
+    const t = s.trim();
+    return (t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")) ? t.slice(1, -1).trim() : t;
+};
+const H2 = /^##\s+(.+?)\s*$/;
+const SPECIAL = new Set([BOOKKEEPING_HEADING, MEMORY_HEADING]);
+/** 固定段里合法的行:key: value / 列表项 / 缩进的子键 */
+const FIELD_LINE = /^(?:[a-z]+:\s*.*|\s*-\s+.*|\s+[a-z]+:\s*.*)$/;
+/**
+ * 切段。普通 H2 段到下一个 H2 为止;「记账」这种固定段只吃字段行——
+ * 遇到空行且下一非空行不是字段行,段就结束,后面的话回到正文(老师把给孩子的话放最后一段时不能被吞掉)。
+ */
+function segments(text) {
+    const lines = text.split('\n');
+    const out = [{ title: null, titleLine: -1, lines: [] }];
+    let fence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\s*```/.test(line))
+            fence = !fence;
+        const m = !fence && H2.exec(line);
+        if (m) {
+            out.push({ title: m[1], titleLine: i, lines: [] });
+            continue;
+        }
+        const cur = out[out.length - 1];
+        if (cur.title !== null && SPECIAL.has(cur.title) && !line.trim()) {
+            let j = i + 1;
+            while (j < lines.length && !lines[j].trim())
+                j++;
+            const next = lines[j];
+            if (next !== undefined && !H2.test(next) && !FIELD_LINE.test(next)) {
+                out.push({ title: null, titleLine: -1, lines: [] });
+                continue;
+            }
+        }
+        cur.lines.push({ i, text: line });
+    }
+    return out;
+}
+/**
+ * 记账段:`- thread: x` 起一条,缩进的 `key: value` 是它的字段,`observations:` / `asked:` 后面缩进的 `- ` 是观察 / 孩子问;
+ * 老师漏写 `- thread:` 直接写 `thread:`(或只写字段)也认——记账任务一次只记一个话题。
+ */
+function parseBookkeepingBody(lines) {
+    const entries = [];
+    let cur;
+    let inList = null;
+    const start = () => {
+        const d = { observations: [], asked: [] };
+        entries.push(d);
+        return d;
+    };
+    for (const raw of lines) {
+        if (!raw.trim())
+            continue;
+        let m = /^-\s+thread:\s*(.*)$/.exec(raw);
+        if (m) {
+            cur = start();
+            cur.thread = unquote(m[1]);
+            inList = null;
+            continue;
+        }
+        m = /^\s*-?\s*([a-z]+):\s*(.*)$/.exec(raw);
+        if (m && (!inList || /^\s*[a-z]+:/.test(raw))) {
+            const c = cur ?? (cur = start());
+            const [, key, v] = m;
+            inList = null;
+            if (key === 'observations' || key === 'asked') {
+                inList = key;
+                const val = unquote(v);
+                if (val)
+                    c[key].push(val);
+            }
+            else if (key === 'thread' || key === 'name' || key === 'textbook' || key === 'summary' || key === 'steps')
+                c[key] = unquote(v);
+            continue;
+        }
+        const li = /^\s*-\s+(.*)$/.exec(raw);
+        if (li && inList && cur)
+            cur[inList].push(unquote(li[1]));
+    }
+    const r = BookkeepingSchema.safeParse({ entries: entries.filter((e) => e.thread && e.name).map(({ asked, ...e }) => (asked.length ? { ...e, asked } : e)) });
+    return r.success ? r.data : null;
+}
+export function parseSections(text) {
+    const segs = segments(text);
+    let bookkeeping = null;
+    const memory = [];
+    const keep = [];
+    const from = [];
+    for (const seg of segs) {
+        const body = seg.lines.map((l) => l.text);
+        if (seg.title === BOOKKEEPING_HEADING && !bookkeeping) {
+            const b = parseBookkeepingBody(body);
+            if (b) {
+                bookkeeping = b;
+                continue;
+            }
+        }
+        if (seg.title === MEMORY_HEADING) {
+            const items = body.map((l) => /^\s*[-*]\s+(.*)$/.exec(l)?.[1].trim() ?? '').filter(Boolean);
+            if (items.length) {
+                memory.push(...items);
+                continue;
+            }
+        }
+        if (seg.title !== null) {
+            keep.push(`## ${seg.title}`);
+            from.push(seg.titleLine);
+        }
+        for (const l of seg.lines) {
+            keep.push(l.text);
+            from.push(l.i);
+        }
+    }
+    // body 是 join 完 trim 的:掐头去尾的空行要同步掐掉,行号才对得上
+    let a = 0;
+    let b = keep.length;
+    while (a < b && !keep[a].trim())
+        a++;
+    while (b > a && !keep[b - 1].trim())
+        b--;
+    return { body: keep.join('\n').trim(), bookkeeping, memory, lineMap: from.slice(a, b) };
+}

package/dist/brain/api-tools.d.ts

@@ -0,0 +1,8 @@
+import { type ToolSet } from 'ai';
+/**
+ * 这轮的只读工具。roots[0] 是相对路径的起点(workspace 根);images = 本轮已经附在消息里的照片(绝对路径),老师去读它们时告诉它已经看得到了。
+ * 返回类型要写明:推断出的类型引到 pnpm 里 @ai-sdk 的深路径,build 出 .d.ts 时报 TS2742(typecheck 不出 .d.ts,看不见)。
+ */
+export declare function readOnlyTools(roots: readonly string[], opts?: {
+    images?: readonly string[];
+}): ToolSet;

package/dist/brain/api-tools.js

@@ -0,0 +1,190 @@
+/**
+ * API 脑的只读工具:read_file、glob、grep_search,名字与参数同 qwen 那三样(家长端的工具清单、工具分类照旧认)。
+ * 只读 roots 里的(workspace 根与 vault,runner 的 readDirsOf):真实路径出了 roots 不读(符号链接越界也算),隐藏目录(.cotutor、.git、.obsidian)不读;
+ * 单文件、每次返回的字数、查找的文件数都有上限;只读文本(教材、日记、档案),图片读不了——本轮的照片已经附在消息里。
+ * 从 cotutor-api-prototype 的 materials.ts 来,那边验过越界与大文件。
+ */
+import { constants } from 'node:fs';
+import { open, readdir, realpath } from 'node:fs/promises';
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { tool } from 'ai';
+import { z } from 'zod';
+const TEXT = new Set(['.md', '.txt', '.json', '.csv', '.tsv', '.yaml', '.yml']);
+const IMAGE = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.heic']);
+/** 单个文件最大多少字节;一次 read_file 回多少字(长的分页,offset 接着读) */
+const FILE_MAX = 512 * 1024;
+const PAGE = 12_000;
+/** 一次查找最多看多少个条目、多深;最多回几条 */
+const WALK_MAX = 3000;
+const DEPTH_MAX = 8;
+const GLOB_MAX = 50;
+const GREP_FILES = 200;
+const GREP_MAX = 30;
+async function boundedRead(path, limit, signal) {
+    signal?.throwIfAborted();
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile())
+            throw new Error('只读普通文件');
+        if (stat.size > limit)
+            throw new Error(`文件太大(${stat.size} 字节,上限 ${limit})`);
+        const buf = Buffer.alloc(limit + 1);
+        let n = 0;
+        while (n < buf.length) {
+            signal?.throwIfAborted();
+            const { bytesRead } = await file.read(buf, n, buf.length - n, null);
+            if (!bytesRead)
+                break;
+            n += bytesRead;
+        }
+        if (n > limit)
+            throw new Error('文件太大');
+        return buf.subarray(0, n);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** 通配:* 任意字符(含 /),? 一个字符;不跑模型给的正则 */
+function wildcard(pattern, text) {
+    let p = 0;
+    let t = 0;
+    let star = -1;
+    let retry = 0;
+    while (t < text.length) {
+        if (pattern[p] === '?' || pattern[p] === text[t]) {
+            p++;
+            t++;
+        }
+        else if (pattern[p] === '*') {
+            star = p++;
+            retry = t;
+        }
+        else if (star >= 0) {
+            p = star + 1;
+            t = ++retry;
+        }
+        else
+            return false;
+    }
+    while (pattern[p] === '*')
+        p++;
+    return p === pattern.length;
+}
+const hidden = (rel) => rel.split(sep).some((s) => s.startsWith('.'));
+/** relative(root, p) 出了 root */
+const outside = (rel) => rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+/**
+ * 这轮的只读工具。roots[0] 是相对路径的起点(workspace 根);images = 本轮已经附在消息里的照片(绝对路径),老师去读它们时告诉它已经看得到了。
+ * 返回类型要写明:推断出的类型引到 pnpm 里 @ai-sdk 的深路径,build 出 .d.ts 时报 TS2742(typecheck 不出 .d.ts,看不见)。
+ */
+export function readOnlyTools(roots, opts = {}) {
+    let real = null;
+    const realRoots = () => (real ??= Promise.all(roots.map((r) => realpath(r).catch(() => null))).then((rs) => [...new Set(rs.filter((r) => r !== null))]));
+    const attached = new Set(opts.images ?? []);
+    /** 路径 → roots 里的真实路径;出界、隐藏的抛 */
+    async function inside(path) {
+        const abs = isAbsolute(path) ? path : resolve(roots[0] ?? '.', path);
+        const file = await realpath(abs).catch(() => {
+            throw new Error(`没有这个文件:${path}`);
+        });
+        for (const root of await realRoots()) {
+            const rel = relative(root, file);
+            if (!outside(rel)) {
+                if (hidden(rel))
+                    throw new Error('隐藏目录里的文件不读');
+                return file;
+            }
+        }
+        throw new Error('只能读 workspace 与 vault 里的文件');
+    }
+    async function textOf(path, signal) {
+        const file = await inside(path);
+        const ext = extname(file).toLowerCase();
+        if (IMAGE.has(ext))
+            throw new Error(attached.has(path) || attached.has(file) ? '这张图已经附在这条消息里了,直接看图' : '图片读不了;要看的图请孩子拍了交上来');
+        if (!TEXT.has(ext))
+            throw new Error('只读 md / txt / json / csv / tsv / yaml');
+        return (await boundedRead(file, FILE_MAX, signal)).toString('utf8');
+    }
+    /** roots 里的文本文件(绝对路径);under 给了就只看那个目录 */
+    async function files(signal, under) {
+        const found = [];
+        let seen = 0;
+        const walk = async (dir, depth) => {
+            if (depth > DEPTH_MAX || seen > WALK_MAX)
+                return;
+            signal?.throwIfAborted();
+            const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+            for (const e of entries) {
+                if (++seen > WALK_MAX)
+                    return;
+                if (e.name.startsWith('.') || e.isSymbolicLink())
+                    continue;
+                const p = join(dir, e.name);
+                if (e.isDirectory())
+                    await walk(p, depth + 1);
+                else if (e.isFile() && TEXT.has(extname(e.name).toLowerCase()))
+                    found.push(p);
+            }
+        };
+        const starts = under ? [await inside(under)] : await realRoots();
+        for (const s of starts)
+            await walk(s, 0);
+        return { paths: [...new Set(found)].sort(), truncated: seen > WALK_MAX };
+    }
+    const relOf = async (p) => {
+        for (const root of await realRoots()) {
+            const rel = relative(root, p);
+            if (!outside(rel))
+                return rel;
+        }
+        return p;
+    };
+    return {
+        read_file: tool({
+            description: '读 workspace 或 vault 里的一个文本文件(教材、日记、档案)。file_path 给绝对路径(上下文包里给的就是);长文件分页,offset 是从第几个字接着读。图片读不了,本轮的照片已经附在消息里。',
+            inputSchema: z.object({ file_path: z.string().min(1).max(1000), offset: z.number().int().min(0).max(FILE_MAX).optional() }),
+            execute: async ({ file_path, offset = 0 }, { abortSignal }) => {
+                const text = await textOf(file_path, abortSignal);
+                return { file_path, text: text.slice(offset, offset + PAGE), ...(text.length > offset + PAGE ? { more: true, next: offset + PAGE } : {}) };
+            },
+        }),
+        glob: tool({
+            description: '按文件名找 workspace 与 vault 里的文本文件。pattern 里 * 是任意字符(含 /),? 是一个字符,如 *期中*.md;回绝对路径。',
+            inputSchema: z.object({ pattern: z.string().min(1).max(200) }),
+            execute: async ({ pattern }, { abortSignal }) => {
+                const all = await files(abortSignal);
+                const hits = [];
+                for (const p of all.paths)
+                    if (wildcard(pattern, await relOf(p)) || wildcard(pattern, p))
+                        hits.push(p);
+                return { paths: hits.slice(0, GLOB_MAX), ...(all.truncated || hits.length > GLOB_MAX ? { truncated: true } : {}) };
+            },
+        }),
+        grep_search: tool({
+            description: '在 workspace 与 vault 的文本文件里找一个词(照字面找,不是正则);path 给了就只找那个目录。回文件、行号与那一行。',
+            inputSchema: z.object({ pattern: z.string().min(1).max(200), path: z.string().min(1).max(1000).optional() }),
+            execute: async ({ pattern, path }, { abortSignal }) => {
+                const all = await files(abortSignal, path);
+                const matches = [];
+                for (const p of all.paths.slice(0, GREP_FILES)) {
+                    abortSignal?.throwIfAborted();
+                    const text = await boundedRead(p, FILE_MAX, abortSignal).then((b) => b.toString('utf8'), () => null);
+                    if (text === null)
+                        continue;
+                    const lines = text.split('\n');
+                    for (let i = 0; i < lines.length; i++) {
+                        if (!lines[i].includes(pattern))
+                            continue;
+                        matches.push({ file_path: p, line: i + 1, text: lines[i].slice(0, 200) });
+                        if (matches.length >= GREP_MAX)
+                            return { matches, truncated: true };
+                    }
+                }
+                return { matches, ...(all.truncated || all.paths.length > GREP_FILES ? { truncated: true } : {}) };
+            },
+        }),
+    };
+}

package/dist/brain/api.d.ts

@@ -0,0 +1,62 @@
+import { type ModelMessage } from 'ai';
+import type { CliEvent } from './cli/types.ts';
+import { type RunPlan } from './cli/run-plan.ts';
+import { type ApiRuntime, type CotutorConfig, type Policy } from '../schema/index.ts';
+import type { BrainHooks, BrainRequest, BrainRun, WarmKey } from './index.ts';
+/** 计划里记的 cli 名:API 的轮次按它分流 */
+export declare const API_CLI = "api";
+/**
+ * 出厂的 API 运行时(2026-10-31 起新装缺省 api,Qwen Code 那两条留作备用):模型同那两条——api 对 qwen(qwen3.8-max),api-flash 对 qwen-flash(qwen3.8-flash)
+ */
+export declare const FACTORY_API_RUNTIMES: Record<string, ApiRuntime>;
+/** .log 的一行 → 统一事件(API 轮次的日志就是一行一条统一事件);不是这种行回 [] */
+export declare function parseEventLine(line: string): CliEvent[];
+/** 政策 effort → 思考开关与思考量(同 qwen:low 不想,孩子在等;带工具的轮次至少想一点,不然照片题连资料都不查) */
+export declare function thinkingOf(effort: Policy['effort'] | undefined, tools: BrainRequest['tools']): {
+    enableThinking: boolean;
+    thinkingBudget?: number;
+};
+/**
+ * 有思考档的模型照 qwen 运行时发 reasoning_effort(src/brain/cli/qwen.ts 的 EFFORT):想一点 = low、不限 = xhigh;不想或没有档 → null,照 thinkingOf 发。
+ * low 是它自己看着想:闲聊想一两百 token,认照片题想得多;thinking_budget 是死卡,1024 时有照片的话题每轮都想满(2026-10-31)
+ */
+export declare function effortOf(model: string, effort: Policy['effort'] | undefined, tools: BrainRequest['tools']): 'low' | 'xhigh' | null;
+/** AI SDK 的 alibaba 只认 thinking_budget:在 fetch 这一层把请求体里的换成 reasoning_effort(SDK 给的中间件口子) */
+export declare function effortFetch(effort: 'low' | 'xhigh', base?: typeof fetch): typeof fetch;
+/**
+ * 百炼 Chat Completions 的端点:知道业务空间 id 就走它的域名(原型验过,同 realtime);只有按量 key 就走公网域名(qwen 那边按量的线也走它,2026-10-29 真跑通)
+ */
+export declare function bailianBase(workspaceId: string | null): string;
+/**
+ * 已经结束的一轮,拼回历史时的老师那条:正文照原样,思考不带,工具往返换成一句「(用了 …,回了 N 字;结果这里不再带,要看再查)」。
+ * 只剩一条纯文字的回复,历史里永远没有配不上对的工具消息
+ */
+export declare function slimTurn(messages: readonly ModelMessage[]): string;
+export declare class ApiBrain {
+    private readonly workspace;
+    private readonly auth;
+    /** 测试与探针:…/compatible-mode/v1(假百炼);不给按业务空间 id 拼 */
+    private readonly endpoint;
+    constructor(opts: {
+        workspace: () => {
+            config: CotutorConfig;
+            root: string;
+        };
+        auth: () => {
+            key: string;
+            workspaceId: string | null;
+        } | null;
+        endpoint?: string;
+    });
+    plan(req: BrainRequest): RunPlan;
+    start(req: BrainRequest, plan: RunPlan, ctx: {
+        tutor: string;
+        key: WarmKey;
+        files: {
+            log: string;
+            err: string;
+            history: string;
+        };
+        stall: Policy['stall'];
+    }, hooks: BrainHooks): BrainRun;
+}