cotutor 0.1.0 → 0.2.0

package/dist/cards/image.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 图片卡:第一行是图(workspace 里的相对路径——产物、孩子拍的照片;或 http(s) 地址),后面几行是图注。
+ * 路径由 /api/kid/image?p= 供图,只认 workspace 根以内的图片文件;舞台里双指缩放。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const ImagePropsSchema: z.ZodObject<{
+    src: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ImageProps = z.infer<typeof ImagePropsSchema>;
+export declare const IMAGE_EXT: RegExp;
+export declare const image: CardKind<ImageProps>;

package/dist/cards/image.js

@@ -0,0 +1,35 @@
+/**
+ * 图片卡:第一行是图(workspace 里的相对路径——产物、孩子拍的照片;或 http(s) 地址),后面几行是图注。
+ * 路径由 /api/kid/image?p= 供图,只认 workspace 根以内的图片文件;舞台里双指缩放。
+ */
+import { z } from 'zod';
+import { bodyLines } from "./kind.js";
+export const ImagePropsSchema = z.object({
+    /** 相对 workspace 根的路径,或 http(s):// 地址 */
+    src: z.string().min(1),
+    caption: z.string().optional(),
+});
+export const IMAGE_EXT = /\.(png|jpe?g|webp|gif|svg)$/i;
+export const image = {
+    name: 'image',
+    props: ImagePropsSchema,
+    parse(body) {
+        const [src, ...rest] = bodyLines(body);
+        if (!src)
+            throw new Error('第一行要是图片路径或地址');
+        if (!/^https?:\/\//.test(src) && !IMAGE_EXT.test(src))
+            throw new Error('要是 png / jpg / webp / gif / svg 图片');
+        const caption = rest.join('\n');
+        return { src, ...(caption ? { caption } : {}) };
+    },
+    doc: `### image — 图片
+
+第一行是图:workspace 里的相对路径(产物、孩子拍的照片,如 \`vault/照片/2026-09-10-作业.jpg\`)或 http(s) 地址;后面几行是图注。孩子点开能放大。
+
+\`\`\`\`
+\`\`\`image
+vault/照片/2026-09-10-作业.jpg
+你昨天写的这道题,看第二行。
+\`\`\`
+\`\`\`\``,
+};

package/dist/cards/index.d.ts

@@ -0,0 +1,48 @@
+import type { BoardCard, BoardSection } from '../lib/kid-board.ts';
+import type { CardKind } from './kind.ts';
+export type { CardKind } from './kind.ts';
+export { text, TEXT_STYLES, type TextProps, type TextStyle } from './text.ts';
+export { read, type ReadProps } from './read.ts';
+export { choice, type ChoiceProps } from './choice.ts';
+export { fill, type FillProps } from './fill.ts';
+export { code, type CodeProps } from './code.ts';
+export { image, IMAGE_EXT, type ImageProps } from './image.ts';
+export { scene, BUNDLE_ID_RE, type SceneProps, type SceneState } from './scene.ts';
+export { canvas, type CanvasProps, type CanvasState } from './canvas.ts';
+export declare const CARD_KINDS: readonly CardKind<any>[];
+export declare function cardKind(name: string): CardKind | undefined;
+export interface ParsedCard {
+    card: BoardCard;
+    /** 没解析成时的一句(家长视图转录里显示);孩子端什么也不报 */
+    warning?: string;
+}
+/**
+ * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签当代码卡原样显示;
+ * 认识但正文解析不出 → 文字卡显示原文 + warning。永不抛错。
+ */
+export declare function parseCard(tag: string, body: string): ParsedCard;
+/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
+export declare function stripSecrets(section: BoardSection): BoardSection;
+/** 一张卡的标题(舞台顶栏、给老师的描述里用):文字卡的 title / text,选择题的问题,其余第一段有字的 */
+export declare function cardLabel(card: BoardCard): string;
+/** 这张卡要后台预生成的配音(文件名相对它的资产目录);没有的种类 → [] */
+export declare function cardAssets(card: BoardCard): {
+    file: string;
+    text: string;
+}[];
+export type CardStateResult = {
+    ok: true;
+    state: unknown;
+} | {
+    ok: false;
+    why: string;
+};
+/** 孩子端 PUT 上来的状态过本种卡的契约;这种卡没有状态、或不认识的 kind → 不收 */
+export declare function parseCardState(card: BoardCard, raw: unknown): CardStateResult;
+/**
+ * 给老师的一句:「choice「问题」 选了「B …」(答案:「…」)」。props 用索引里的(带答案),状态是孩子的;
+ * 没有 describe 的种类把状态原样 JSON。id 由调用方拼在前面(<job>/<n>)。
+ */
+export declare function describeCard(card: BoardCard, state: unknown): string;
+/** 给老师看的语法表(出厂到 workspace 的 .cotutor/板书语法.md;从各种卡的 doc 拼出来,不手写) */
+export declare function boardSyntaxDoc(): string;

package/dist/cards/index.js

@@ -0,0 +1,115 @@
+/**
+ * 卡的注册表:加一种卡 = 加一个文件 + 这里一行;解析器、语法表、孩子端剥秘密都从这里走。
+ * 页面那一半在 kid-page.ts(渲染)与 kid-board.ts(标注落点),按 kind 名对上。
+ */
+import { z } from 'zod';
+import { canvas } from "./canvas.js";
+import { choice } from "./choice.js";
+import { code } from "./code.js";
+import { fill } from "./fill.js";
+import { image } from "./image.js";
+import { read } from "./read.js";
+import { scene } from "./scene.js";
+import { text } from "./text.js";
+export { text, TEXT_STYLES } from "./text.js";
+export { read } from "./read.js";
+export { choice } from "./choice.js";
+export { fill } from "./fill.js";
+export { code } from "./code.js";
+export { image, IMAGE_EXT } from "./image.js";
+export { scene, BUNDLE_ID_RE } from "./scene.js";
+export { canvas } from "./canvas.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CARD_KINDS = [text, read, choice, fill, image, scene, canvas, code];
+export function cardKind(name) {
+    return CARD_KINDS.find((k) => k.name === name);
+}
+/**
+ * 围栏 → 卡。标签第一个词是 kind,其余是修饰;不认识的标签当代码卡原样显示;
+ * 认识但正文解析不出 → 文字卡显示原文 + warning。永不抛错。
+ */
+export function parseCard(tag, body) {
+    const [name, ...mods] = tag.trim().split(/\s+/).filter(Boolean);
+    if (!name)
+        return { card: { kind: 'code', props: code.parse(body, []) } };
+    const kind = cardKind(name.toLowerCase());
+    if (!kind)
+        return { card: { kind: 'code', props: code.parse(body, [name]) } };
+    try {
+        const props = kind.props.parse(kind.parse(body, mods));
+        return { card: { kind: kind.name, props } };
+    }
+    catch (err) {
+        const why = err instanceof z.ZodError ? err.issues.map((i) => `${i.path.join('.')}:${i.message}`).join(';') : err instanceof Error ? err.message : String(err);
+        return { card: { kind: 'text', props: { text: body.trim() || name } }, warning: `卡片没解析成:${name} — ${why}` };
+    }
+}
+/** 孩子端的一节:每张卡过本种卡的 strip(答案不下发);不认识的 kind 原样;孩子自己的状态与已生成的资产照给 */
+export function stripSecrets(section) {
+    return {
+        ...section,
+        cards: section.cards.map((c) => {
+            const k = cardKind(c.kind);
+            return k?.strip ? { ...c, props: k.strip(c.props) } : c;
+        }),
+    };
+}
+/** 一张卡的标题(舞台顶栏、给老师的描述里用):文字卡的 title / text,选择题的问题,其余第一段有字的 */
+export function cardLabel(card) {
+    const p = card.props;
+    const s = (v) => (typeof v === 'string' ? v.trim() : '');
+    const first = s(p.title) || s(p.question) || s(p.text) || s(p.caption) || s(p.prompt) || (Array.isArray(p.segments) ? s(p.segments[0]) : '');
+    const cps = Array.from(first.replace(/\s+/g, ' '));
+    return cps.length > 40 ? `${cps.slice(0, 40).join('')}…` : cps.join('');
+}
+/** 这张卡要后台预生成的配音(文件名相对它的资产目录);没有的种类 → [] */
+export function cardAssets(card) {
+    const k = cardKind(card.kind);
+    if (!k?.assets)
+        return [];
+    const r = k.props.safeParse(card.props);
+    return r.success ? k.assets(r.data) : [];
+}
+/** 孩子端 PUT 上来的状态过本种卡的契约;这种卡没有状态、或不认识的 kind → 不收 */
+export function parseCardState(card, raw) {
+    const k = cardKind(card.kind);
+    if (!k?.state)
+        return { ok: false, why: `${card.kind} 卡没有状态` };
+    const r = k.state.safeParse(raw);
+    if (!r.success)
+        return { ok: false, why: r.error.issues.map((i) => `${i.path.join('.')}:${i.message}`).join(';') };
+    return { ok: true, state: r.data };
+}
+/**
+ * 给老师的一句:「choice「问题」 选了「B …」(答案:「…」)」。props 用索引里的(带答案),状态是孩子的;
+ * 没有 describe 的种类把状态原样 JSON。id 由调用方拼在前面(<job>/<n>)。
+ */
+export function describeCard(card, state) {
+    const k = cardKind(card.kind);
+    const head = `${card.kind}「${cardLabel(card)}」`;
+    if (!k?.describe || !k.state)
+        return `${head} ${JSON.stringify(state)}`;
+    const r = k.state.safeParse(state);
+    return `${head} ${r.success ? k.describe(card.props, r.data) : JSON.stringify(state)}`;
+}
+/** 给老师看的语法表(出厂到 workspace 的 .cotutor/板书语法.md;从各种卡的 doc 拼出来,不手写) */
+export function boardSyntaxDoc() {
+    const kinds = CARD_KINDS.map((k) => k.doc.trim()).join('\n\n');
+    return `# 板书怎么写
+
+回复正文就是孩子看到的板书,只有两种东西:
+
+- **普通段落 = 你说的话。** 一行一句,每句会被念出来、显示在字幕行,所以不要写标题、列表、粗体、括号注释。句子里用方括号标出要在板上敲的词,如「这叫[底]」,那个词要在某张卡上出现。末句写成问句就停下等孩子。
+- **围栏 = 板上的卡。** 围栏的语言标签是卡的种类,后面的词是修饰;正文按各种卡的写法。卡写在讲它的那句话前面,卡与话交错。不认识的标签当代码卡原样显示;正文写得不对的卡退成一段文字,孩子端不会报错。
+
+一节 4–8 张卡、6–12 句话;一次只讲一个想法,讲完就问。随口问答就一两句话,没有卡。**板书写完就停**:最后一个字是问孩子的那句,后面不要再补总结、不要再用工具——孩子看到的是你这轮最后一段话,再补一句板书就丢了。
+
+孩子在卡上做的事(选了、填了)会在下一条消息的上下文包里以 \`cards:\` 段告诉你,一张卡一行(卡的编号、种类、标题、做了什么、答案);孩子只交答案没说话时消息正文是「(交了答案,没说话)」。孩子看到的卡上没有对错,对错由你口头说。上下文包里 \`focus.card\` 是孩子发消息时正开着的那张卡。
+
+对家长说的话、要拍板的事、要转交的事,用「## 家长」「## 待裁量」(question: 一句话;options: 列表)「## 转交」三个段放在正文末尾,孩子看不到;板书到第一个「## 」为止。
+
+## 卡的种类
+
+${kinds}
+`;
+}

package/dist/cards/kind.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 一种卡的服务端定义(《板书卡片设计.md》§1):props 契约、围栏正文怎么解析、哪些字段不下发孩子端、给老师看的写法;
+ * 有交互的卡再加 state 契约(孩子在卡上做的事,PUT 进来先过它)与 describe(把 props + state 说成给老师看的一句,进上下文包)。
+ * 页面那一半(紧凑态怎么画、舞台里怎么交互、标注落在哪些字上)在 kid-page.ts / kid-board.ts;两边靠 kind 名对上。
+ */
+import type { z } from 'zod';
+export interface CardKind<P = Record<string, unknown>, S = unknown> {
+    name: string;
+    props: z.ZodType<P>;
+    /** 围栏正文 + 标签后的修饰词 → props;抛错 = 没解析成(退成文字卡显示原文,家长视图报一行) */
+    parse(body: string, mods: readonly string[]): P;
+    /** 剥掉不下发孩子端的字段(答案);没有 = 全给 */
+    strip?(props: P): P;
+    /** 孩子在卡上做的事的形状;没有 = 这种卡没有状态,PUT 一律 400 */
+    state?: z.ZodType<S>;
+    /** props + state → 给老师看的一句(不含卡的标题,那句由注册表拼);没有 = 状态原样 JSON */
+    describe?(props: P, state: S): string;
+    /** 这张卡要在后台预生成的配音资产(点读的段):文件名相对这张卡的资产目录 <日期>.<job>.cards/<n>/,text 是要念的字 */
+    assets?(props: P): {
+        file: string;
+        text: string;
+    }[];
+    /** 语法表里的一段:写法 + 例子(给老师看),由 boardSyntaxDoc 拼成 .cotutor/板书语法.md */
+    doc: string;
+}
+/** 围栏正文 → 非空行(各自 trim) */
+export declare function bodyLines(body: string): string[];

package/dist/cards/kind.js

@@ -0,0 +1,7 @@
+/** 围栏正文 → 非空行(各自 trim) */
+export function bodyLines(body) {
+    return body
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+}

package/dist/cards/read.d.ts

@@ -0,0 +1,8 @@
+/** 点读卡:一行一段,孩子点哪段听哪段;配音在一轮跑完后后台按段合成到 .cards/<n>/<段>.mp3,还没好的段退浏览器合成声。 */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const ReadPropsSchema: z.ZodObject<{
+    segments: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ReadProps = z.infer<typeof ReadPropsSchema>;
+export declare const read: CardKind<ReadProps>;

package/dist/cards/read.js

@@ -0,0 +1,27 @@
+/** 点读卡:一行一段,孩子点哪段听哪段;配音在一轮跑完后后台按段合成到 .cards/<n>/<段>.mp3,还没好的段退浏览器合成声。 */
+import { z } from 'zod';
+import { bodyLines } from "./kind.js";
+export const ReadPropsSchema = z.object({ segments: z.array(z.string().min(1)).min(1) });
+export const read = {
+    name: 'read',
+    props: ReadPropsSchema,
+    parse(body) {
+        const segments = bodyLines(body);
+        if (!segments.length)
+            throw new Error('一行都没有(一行一段)');
+        return { segments };
+    },
+    assets(p) {
+        return p.segments.map((text, k) => ({ file: `${k + 1}.mp3`, text }));
+    },
+    doc: `### read — 点读
+
+一行一段(一句诗、一句课文、一个单词;英文后面可以跟中文),孩子点哪段听哪段。原文、古诗、生词、单词表用它。
+
+\`\`\`\`
+\`\`\`read
+床前明月光,疑是地上霜。
+举头望明月,低头思故乡。
+\`\`\`
+\`\`\`\``,
+};

package/dist/cards/scene.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 场景卡(《drawtell接入与场景卡.md》§2):正文是课包 id,课包在 workspace 的 bundles/<id>/(drawtell build 的产物,scene-maker 作业出)。
+ * 解析器只认 id;题面、步数、有没有做好(ready)、缩略图是服务端下发时从课包现读的快照(src/server/scene-props.ts),
+ * 所以课包落地后卡自己变成可播,不用老师再说一遍。状态 = 孩子看到第几步、看完没;紧凑态「N 步 ▷」,舞台是 drawtell 播放器。
+ */
+import { z } from 'zod';
+import { type CardKind } from './kind.ts';
+export declare const BUNDLE_ID_RE: RegExp;
+export declare const ScenePropsSchema: z.ZodObject<{
+    bundle: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    problem: z.ZodOptional<z.ZodString>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ready: z.ZodOptional<z.ZodBoolean>;
+    thumb: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SceneProps = z.infer<typeof ScenePropsSchema>;
+export declare const SceneStateSchema: z.ZodObject<{
+    step: z.ZodNumber;
+    done: z.ZodBoolean;
+}, z.core.$strip>;
+export type SceneState = z.infer<typeof SceneStateSchema>;
+export declare const scene: CardKind<SceneProps, SceneState>;

package/dist/cards/scene.js

@@ -0,0 +1,67 @@
+/**
+ * 场景卡(《drawtell接入与场景卡.md》§2):正文是课包 id,课包在 workspace 的 bundles/<id>/(drawtell build 的产物,scene-maker 作业出)。
+ * 解析器只认 id;题面、步数、有没有做好(ready)、缩略图是服务端下发时从课包现读的快照(src/server/scene-props.ts),
+ * 所以课包落地后卡自己变成可播,不用老师再说一遍。状态 = 孩子看到第几步、看完没;紧凑态「N 步 ▷」,舞台是 drawtell 播放器。
+ */
+import { z } from 'zod';
+import { bodyLines } from "./kind.js";
+export const BUNDLE_ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+export const ScenePropsSchema = z.object({
+    /** 课包 id(bundles/<id>/) */
+    bundle: z.string().regex(BUNDLE_ID_RE),
+    /** 老师在 id 后面写的一句(课包还没到时孩子看到它) */
+    text: z.string().optional(),
+    /** 以下是下发时从课包读的快照;没到就没有 */
+    title: z.string().optional(),
+    problem: z.string().optional(),
+    /** 每步讲稿 */
+    steps: z.array(z.string()).optional(),
+    /** 课包在不在(scene.json + manifest.json 都在) */
+    ready: z.boolean().optional(),
+    /** 终帧缩略图(相对 workspace 根,/api/kid/image?p= 供图);没截过就没有 */
+    thumb: z.string().optional(),
+});
+export const SceneStateSchema = z.object({
+    /** 看到第几步(1 起;0 = 还没开始) */
+    step: z.number().int().nonnegative(),
+    done: z.boolean(),
+});
+export const scene = {
+    name: 'scene',
+    props: ScenePropsSchema,
+    parse(body) {
+        const [first, ...rest] = bodyLines(body);
+        if (!first)
+            throw new Error('第一行要是课包 id');
+        if (first.startsWith('{'))
+            throw new Error('行内 JSON 场景还没接(下一步);先写课包 id');
+        if (!BUNDLE_ID_RE.test(first))
+            throw new Error(`课包 id 只能是小写字母、数字、连字符:${first}`);
+        const text = rest.join(' ').trim();
+        return { bundle: first, ...(text ? { text } : {}) };
+    },
+    state: SceneStateSchema,
+    describe(p, s) {
+        const total = p.steps?.length ?? 0;
+        if (!p.ready)
+            return '课包还没做好,孩子看不了';
+        if (s.done)
+            return `看完了(共 ${total} 步)`;
+        if (s.step <= 0)
+            return '还没开始看';
+        return `看到第 ${s.step} 步(共 ${total} 步)停在气口`;
+    },
+    doc: `### scene — 讲解动画(课包)
+
+正文第一行是课包 id(bundles/<id>/,由 scene-maker 作业做出来;id 形如 \`2026-09-10-guilv\`),第二行可以写一句给孩子的话。
+课包没做好之前孩子看到「图还在路上」,做好了卡自己变成可播,舞台里是逐笔画出来的讲解,自带讲稿与声音。
+讲作业题、要画图才讲得清的题用它:回复里放这张卡 + 一句「我去把图画出来」,同时「## 转交」给 scene-maker(to: scene-maker;why: 题面与讲法要点;refs: 课包 id)。
+讲稿里 \`[[play]]\` 锚到它,念到那句就把动画铺满播,播完接着念下一句。一天最多起两个作业(policy scenes.dailyMax)。
+
+\`\`\`\`
+\`\`\`scene
+2026-09-10-guilv
+我去把这道题画出来,画好了我们一起看。
+\`\`\`
+\`\`\`\``,
+};

package/dist/cards/text.d.ts

@@ -0,0 +1,18 @@
+/** 文字卡:一段字;样式是修饰词(cover / note / quote / formula / step),不占种类。 */
+import { z } from 'zod';
+import type { CardKind } from './kind.ts';
+export declare const TEXT_STYLES: readonly ["cover", "note", "quote", "formula", "step"];
+export type TextStyle = (typeof TEXT_STYLES)[number];
+export declare const TextPropsSchema: z.ZodObject<{
+    style: z.ZodOptional<z.ZodEnum<{
+        step: "step";
+        cover: "cover";
+        note: "note";
+        formula: "formula";
+        quote: "quote";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type TextProps = z.infer<typeof TextPropsSchema>;
+export declare const text: CardKind<TextProps>;

package/dist/cards/text.js

@@ -0,0 +1,41 @@
+/** 文字卡:一段字;样式是修饰词(cover / note / quote / formula / step),不占种类。 */
+import { z } from 'zod';
+export const TEXT_STYLES = ['cover', 'note', 'quote', 'formula', 'step'];
+export const TextPropsSchema = z.object({
+    style: z.enum(TEXT_STYLES).optional(),
+    /** cover 的标题 / step 的名字 */
+    title: z.string().optional(),
+    /** 正文;cover 时是副标题(可空) */
+    text: z.string(),
+});
+export const text = {
+    name: 'text',
+    props: TextPropsSchema,
+    parse(body, mods) {
+        const style = mods.map((m) => m.toLowerCase()).find((m) => TEXT_STYLES.includes(m));
+        const trimmed = body.replace(/^\s*\n/, '').trimEnd();
+        if (!trimmed.trim())
+            throw new Error('正文是空的');
+        if (style === 'cover' || style === 'step') {
+            const nl = trimmed.indexOf('\n');
+            const title = (nl < 0 ? trimmed : trimmed.slice(0, nl)).trim();
+            const rest = nl < 0 ? '' : trimmed.slice(nl + 1).trim();
+            return { style, title, text: rest };
+        }
+        return { ...(style ? { style } : {}), text: trimmed.trim() };
+    },
+    doc: `### text — 一段字
+
+\`\`\`text\` 后可加一个修饰词定样子:\`cover\`(封面:第一行标题,第二行副标题)、\`step\`(一步:第一行是这步的名字,下面是内容)、\`formula\`(算式,单独一行)、\`note\`(一句要记住的话)、\`quote\`(引一句原文);不加修饰就是普通一段。
+
+\`\`\`\`
+\`\`\`text cover
+三角形的面积
+两个一样的三角形拼成一个平行四边形
+\`\`\`
+
+\`\`\`text formula
+三角形面积 = 底 × 高 ÷ 2
+\`\`\`
+\`\`\`\``,
+};

package/dist/cli/cert.d.ts

@@ -0,0 +1,7 @@
+export interface CertResult {
+    cert: string;
+    key: string;
+    hosts: string[];
+    caRoot: string;
+}
+export declare function makeCert(extraHosts?: string[]): Promise<CertResult>;

package/dist/cli/cert.js

@@ -0,0 +1,36 @@
+/**
+ * cotutor cert:用 mkcert 给这台机器签一张证书到 ~/.config/cotutor/certs/(cert.pem + key.pem),serve 看到就走 HTTPS。
+ * 为什么要:iPad Safari 的录音 / 语音识别只在安全上下文里给;局域网 IP 不是 localhost,得自签。
+ * 为什么放机器级而不是 workspace:签的是本机名与局域网 IP,与孩子无关;多个 workspace 共用一张,IP 变了只重签一次(2026-09-09 拍板)。
+ * 主机名 = 本机名、本机名.local、所有局域网 IPv4、localhost、127.0.0.1,再加 --host 给的。已有证书就覆盖(证书可再生)。不需要 workspace。
+ */
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { lanAddresses } from "./serve.js";
+import { USER_CERT_DIR, UsageError } from "./workspace.js";
+const execFileP = promisify(execFile);
+export async function makeCert(extraHosts = []) {
+    let caRoot;
+    try {
+        caRoot = (await execFileP('mkcert', ['-CAROOT'], { timeout: 8000 })).stdout.trim();
+    }
+    catch {
+        throw new UsageError('PATH 里没有 mkcert。装:brew install mkcert && mkcert -install(在 Mac 上信任一次根证书);iPad 端见 cert 命令输出的提示。');
+    }
+    const host = hostname();
+    const hosts = [...new Set([host, host.endsWith('.local') ? host : `${host}.local`, ...lanAddresses(), 'localhost', '127.0.0.1', ...extraHosts])];
+    const dir = USER_CERT_DIR;
+    await mkdir(dir, { recursive: true });
+    const cert = join(dir, 'cert.pem');
+    const key = join(dir, 'key.pem');
+    try {
+        await execFileP('mkcert', ['-cert-file', cert, '-key-file', key, ...hosts], { timeout: 60_000 });
+    }
+    catch (err) {
+        throw new UsageError(`mkcert 签证书失败:${err instanceof Error ? err.message : String(err)}\n先跑 mkcert -install,再重试。`);
+    }
+    return { cert, key, hosts, caRoot };
+}

package/dist/cli/doctor.d.ts

@@ -12,8 +12,11 @@ export interface DoctorReport {
     source: RootSource | null;
     checks: DoctorCheck[];
 }
-/** 预设的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
-export declare function presetCli(run: readonly string[]): string;
+/** 运行时的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
+export declare function runtimeCli(run: readonly string[]): string;
+/** 已知的环境坑,从 CLI 的输出里认出来给修复命令(错误信息即修复指南) */
+export declare function explainLlmFailure(text: string, runtime: readonly string[]): string;
 export declare function doctorWorkspace(override?: string, opts?: ResolveOptions & {
     probeEnv?: boolean;
+    live?: boolean;
 }): Promise<DoctorReport>;