cotutor 0.2.0 → 0.4.0

package/dist/app/cli/skeleton.js

@@ -0,0 +1,161 @@
+/**
+ * workspace骨架清单:init 建、doctor 查,同一张清单(两边各写一遍必然漂移)。
+ * workspace 布局:
+ *   cotutor.json / .cotutor/shipped.json(出厂 hash)/ .agents/skills/(技能;.claude/skills 是指过去的链,给 Claude Code)
+ *   agents/<name>.md(老师文件,拷自本包 grades/grade-<n>/agents/,是家长的;所有运行时都从这里拿老师正文)与 agents/<name>/(老师的家 = 会话 cwd)
+ *   ledger/(产物账本)/ conversations/(对话索引与转录)
+ * vault 侧(《obsidian仓库设计.md》):档案 / 课程表 / 日记 / 教材 / 计划 / 参考,init 只建档案与参考 README(缺了才写)
+ */
+import { readFileSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseAgentFile } from "../../runtime/agent-file.js";
+import { CONFIG_SCHEMA_FILE, DEFAULT_PORT, DICTATION_DEFAULT, cotutorJsonSchema } from "../../schema/index.js";
+import { FACTORY_API_RUNTIMES } from "../../brain/index.js";
+import { DEFAULT_GRADE, PACKAGE_GRADES_DIR } from "./grades.js";
+import { mkdir, writeFile } from 'node:fs/promises';
+export const DIRS = ['agents', 'ledger', 'conversations', 'bundles'];
+export const LEDGER_FILES = ['ledger/artifacts.jsonl'];
+/** 默认年级的出厂老师目录;workspace 的操作用 workspaceGradePack 选来源 */
+export const PACKAGE_AGENTS_DIR = join(PACKAGE_GRADES_DIR, `grade-${DEFAULT_GRADE}`, 'agents');
+/** 本包版本(出厂件的 hash 记录带它,升级时知道基于哪版) */
+export const PACKAGE_VERSION = JSON.parse(readFileSync(fileURLToPath(new URL('../../../package.json', import.meta.url)), 'utf8')).version;
+export async function shippedAgents(dir = PACKAGE_AGENTS_DIR) {
+    const out = [];
+    for (const f of (await readdir(dir)).filter((f) => f.endsWith('.md')).sort()) {
+        const file = join(dir, f);
+        const { frontmatter } = parseAgentFile(await readFile(file, 'utf8'));
+        if (frontmatter.name)
+            out.push({ name: frontmatter.name, file, description: frontmatter.description ?? '' });
+    }
+    return out;
+}
+export const GITIGNORE = `# 转录日志体积大、可从对话索引重建关键信息;要留全档就删掉下面这行
+conversations/**/*.log
+# 配音可重新合成
+conversations/**/*.mp3
+# 回放(cotutor replay)是调提示词与 vault 时的对照,不是孩子的对话
+evals/
+# 做好的课(课包、视频课)与课包截图:体积大,源在家长做课的地方
+bundles/
+lectures/
+snaps/
+# 口语课(孩子的原声、照片)
+talk/
+# 作业照片(孩子在老师页上拍的;paths.captures):体积大、只是这一轮的素材,认出的文字在日记里
+captures/
+# 家长在 workspace 里用 Claude Code 时它的个人设置
+.claude/settings.local.json
+# .cotutor/ 是机器文件(板书写法缓存、配音缓存、二维码、日志),只留出厂 hash 与 schema
+.cotutor/*
+!.cotutor/shipped.json
+!.cotutor/cotutor.schema.json
+node_modules/
+.DS_Store
+`;
+/** 档案模板(paths.profile,缺了才写):cotutor: profile 的那篇,原文整篇进每个话题的第一条 */
+export function profileTemplate(name) {
+    return `---
+cotutor: profile
+nickname: ${name}
+birthday:
+school_start:
+city:
+---
+
+(这篇是孩子的档案,文件名、放哪都行,认的是上面的 cotutor: profile。school_start 写读一年级的年月,如 2025-09,老师据此知道现在是几年级哪个学期。)
+
+(下面写孩子的情况:性格、喜欢什么、要避开什么。每位老师每个话题开头都会整篇读到。)
+`;
+}
+/** 参考目录的 README(缺了才写) */
+export const REFERENCE_README = `# 参考
+
+这里放政策与你自己的笔记:讲某类题的偏好、薄弱点、忌讳、按题型整理的东西——随便建,机器只读不写。
+让老师看到的办法:在档案或这位老师的入口文件(\`cotutor: subject\` 的那篇)里链过去(\`[[找规律填数]]\`);老师拿到路径,要用时自己读。
+`;
+/**
+ * 家长自己加老师时的文件模板:和出厂老师一样只有人设与这一科的做法;
+ * 公共的守则(上下文包、三种回复、记忆段、不变的规矩)在机器技能 cotutor-tutor,应用每个话题第一条放进上下文包。
+ */
+export function tutorTemplate(t) {
+    const what = t.subject ? `${t.subject}的事` : '孩子问的事';
+    const subject = t.subject ?? '这一科';
+    return `---
+name: ${t.name}
+description: ${t.description ?? `${t.display}。${what}都找它;随口问的一两句答完,要讲的在板书上一节一节讲`}
+maxTurns: 40
+permissionMode: bypassPermissions
+---
+你是这个家的${t.display},对面是一个孩子。(在这里写这位老师的性子和讲法,一两句:比如「说话慢一点,爱打比方」。)
+
+上下文包怎么看、三种回复、记忆段、不变的规矩,在每个话题第一条的 \`<cotutor-rules>\` 里,照着做;这里只写${t.display}自己的。
+
+## ${subject}
+
+(下面几节写这一科特有的做法,一条一句。只写对哪个孩子、哪个学期都成立的;关于这个孩子、这学期的,写进 vault 里这一科的入口文件。用不上的小节删掉。)
+
+### 讲之前
+
+(要对一下什么、教材里查什么。)
+
+### 讲
+
+(这一科怎么讲、什么内容用哪种卡。)
+
+### 练
+
+(一节末尾怎么问、用哪种卡。)
+
+### 孩子这样说时
+
+(孩子常见的说法或答偏了,怎么接。)
+`;
+}
+/** 出厂老师的条目;cards = 板书写法里讲哪几种卡(《卡片协议.md》「谁拿到哪些卡」,2026-10-07),text 总在;
+ *  不写 avatar:三门主科用包里的出厂头像(src/app/http/avatars.ts) */
+const TUTOR_DEFAULTS = {
+    // 数学多想一会儿:算错的代价大(别的老师用缺省 low);走 qwen3.8-max(同语文老师)。运行时 api = 应用直连百炼(2026-10-31 起出厂缺省)
+    'math-tutor': { display: '数学老师', subject: '数学', runtime: 'api', cards: ['text', 'choice', 'image', 'lecture', 'canvas', 'code'], policy: { effort: 'medium' } },
+    // 画图卡(paint)不在这里:只在「你说我画」activity 的话题里有(agents/chinese-tutor/activities/你说我画.md 头上的 cards)
+    // 语文老师走 qwen3.8-max(你说我画、看图说话两套 activity eval 在它上面验证;2026-10-31 Ray 上 API 与 Qwen Code 对照过)
+    'chinese-tutor': { display: '语文老师', subject: '语文', runtime: 'api', cards: ['text', 'read', 'choice', 'image', 'tianzige', 'lecture', 'canvas'] },
+    // 英语也走 api(qwen3.8-max):2026-10-31 api-flash 真跑英语四个 activity,13 次里 5 次第一轮只出一张拍照卡、没有讲稿(实时页嘴没话可念);max 在 Ray 上都过。
+    // 想省钱改 api-flash,先跑 activity eval。medium 是 2026-10-27 给 flash 加的(low 偶尔只出卡或念规则,详见年级教学包验证记录)
+    'english-tutor': { display: '英语老师', subject: '英语', runtime: 'api', cards: ['text', 'read', 'choice', 'image', 'word', 'lecture'], policy: { effort: 'medium' } },
+};
+/** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器代做)。 */
+export function configTemplate(input) {
+    const tutors = {};
+    for (const a of input.tutors) {
+        const p = TUTOR_DEFAULTS[a.name];
+        tutors[a.name] = p
+            ? { display: p.display, ...(p.subject ? { subject: p.subject } : {}), enabled: p.enabled ?? true, ...(p.hidden ? { hidden: true } : {}), ...(p.runtime ? { runtime: p.runtime } : {}), ...(p.cards ? { cards: p.cards } : {}), ...(p.policy ? { policy: p.policy } : {}) }
+            : { display: a.name, enabled: true };
+    }
+    const cfg = {
+        $schema: CONFIG_SCHEMA_FILE,
+        version: 1,
+        title: input.name ? `${input.name}的老师们` : 'cotutor',
+        kid: { slug: input.slug, ...(input.name ? { name: input.name } : {}) },
+        server: { port: input.port ?? DEFAULT_PORT },
+        paths: {},
+        policyDefaults: {},
+        tutors,
+        // 缺省 api:应用直连百炼,家长端「首页」填一次按量 key + 业务空间 id 就能用(2026-10-31);2026-11-02 起只有 API 运行时
+        runtimes: { default: 'api', ...FACTORY_API_RUNTIMES },
+        // 听写的拍照认词:模型与挑词要求(prompt 一行一个字符串)写进文件,家长看得见、改得动
+        dictation: DICTATION_DEFAULT,
+        // 字段说明不写在这里:一写进去就冻住(政策文件永不覆盖),$schema 指的 schema 文件每次 init / upgrade 从 zod 的 .describe() 刷新
+        _note: '一孩一 workspace 的政策文件,家长改这里,机器不覆盖(写坏了靠 git 回退,cotutor doctor 可体检);每个字段的说明在 $schema 指的 .cotutor/cotutor.schema.json,编辑器里悬停就能看到。',
+    };
+    return `${JSON.stringify(cfg, null, 2)}\n`;
+}
+/** 把 JSON Schema 写进 workspace(机器文件,每次 init / upgrade 都刷新);板书语法表出厂成技能 cotutor-board,见 skills.ts `writeBoardSkill` */
+export async function writeSchemaFile(root) {
+    const file = join(root, CONFIG_SCHEMA_FILE);
+    await mkdir(join(root, '.cotutor'), { recursive: true });
+    await writeFile(file, `${JSON.stringify(cotutorJsonSchema(), null, 2)}\n`);
+    return file;
+}

package/dist/app/cli/skills.d.ts

@@ -0,0 +1,59 @@
+import { BOARD_SKILL } from '../../board/cards/docs.ts';
+import { ANALYZE_SKILL } from '../skills/analyze-doc.ts';
+import { TUNE_SKILL } from '../skills/tune-doc.ts';
+import { HOME_SKILL } from '../skills/home-doc.ts';
+import { TUTOR_SKILL } from '../../runtime/context/tutor-rules.ts';
+export { ANALYZE_SKILL, BOARD_SKILL, HOME_SKILL, TUNE_SKILL, TUTOR_SKILL };
+export interface ShippedSkill {
+    name: string;
+    /** 机器件:每次 init / upgrade 都按包里的覆盖,不认家长的改动 */
+    machine?: boolean;
+}
+export declare const SHIPPED_SKILLS: readonly ShippedSkill[];
+/**
+ * 不再出厂的技能:upgrade 时 workspace 里还有(出厂记录里有它)就删掉,免得编程助手照旧技能干活。
+ * 机器件(machine)向来不认家长的改动,照删;别的家长改过就留着,只是不再记在出厂清单里。
+ * cotutor-vault(2026-10-30,机器件):老师从没读过它(孩子的话不带工具,记账那条消息自带写法),要紧的几句并进了守则 cotutor-tutor。
+ * drawtell-*(2026-10-31):drawtell 并进本包,改名 chalk-*,命令是 cotutor chalk
+ */
+export declare const RETIRED_SKILLS: readonly ShippedSkill[];
+export type ShippedSkillName = string;
+/** 本包自带的技能目录(仓库检出与 npm 安装都在包根 skills/) */
+export declare const PACKAGE_SKILLS_DIR: string;
+/** 这个技能在包里的目录 */
+export declare function skillSourceDir(skill: ShippedSkill): string;
+/** 一个目录的内容 hash:相对路径 + 内容,按路径排序 */
+export declare function dirHash(dir: string): Promise<string>;
+export type SkillState = 'latest' | 'upgradable' | 'custom' | 'untracked' | 'missing';
+export interface SkillStatus {
+    name: ShippedSkillName;
+    state: SkillState;
+    dir: string;
+    basedOn?: string;
+    machine: boolean;
+}
+export declare function skillDir(root: string, name: string): string;
+export declare function skillStatuses(root: string): Promise<SkillStatus[]>;
+export interface SkillStep {
+    item: string;
+    action: 'created' | 'exists' | 'kept' | 'replaced' | 'removed';
+    note?: string;
+}
+/** init 用:缺的拷,有的不动;机器件每次按包里的刷 */
+export declare function installSkills(root: string): Promise<SkillStep[]>;
+export interface SkillUpgradeStep {
+    name: string;
+    action: 'upgraded' | 'latest' | 'kept-custom' | 'installed' | 'retired';
+    basedOn?: string;
+    machine?: boolean;
+}
+/** upgrade 用:latest 跳过;upgradable 换新(机器件改过也换);custom / untracked 保留只报;缺的补;不再出厂的删(改过的留) */
+export declare function upgradeSkills(root: string): Promise<SkillUpgradeStep[]>;
+/** Claude Code 只认 .claude/skills(Codex、Qwen Code 认 .agents/skills):在那里放一条相对链,两边看到的是同一份 */
+export declare const CLAUDE_SKILLS_LINK = ".claude/skills";
+/**
+ * init / upgrade 用:没有就建链;已经是链不动;是实体目录(老 workspace 没搬完)不碰,报一声。
+ * Windows 上建目录联接(junction):符号链接要「创建符号链接」权限,家长平常开的终端没有(UAC 拿掉了,开发者模式也多半没开)。
+ * 联接读回来是绝对路径,所以按指到哪儿比、不按字面比。还是建不了就跳过:这条链只给在 workspace 里用 Claude Code 的人,cotutor 自己不读它。
+ */
+export declare function linkClaudeSkills(root: string): Promise<SkillStep>;

package/dist/app/cli/skills.js

@@ -0,0 +1,199 @@
+/**
+ * 出厂 skill:与老师文件同一套「拷不链」机制——init 拷进 workspace 的 .agents/skills/<name>/,hash 记 .cotutor/shipped.json 的 skills,
+ * (2026-10-30 从 .claude/skills/ 挪来:Codex、Qwen Code 认 .agents/skills;Claude Code 只认 .claude/skills,那里是一条指过来的链,见 linkClaudeSkills。)
+ * 出厂表 SHIPPED_SKILLS 每项带 machine 标记(2026-09-15,照 hyperframes 的 skills/ 目录),都在本包根 skills/<name>/(进 npm files;
+ * cotutor-board 整个、其余几个的 references/ 是 scripts/gen-skills.ts 生成后入库的,tests/skills.test.ts 断言一致):
+ * - machine: true 的是机器件(cotutor-tutor / cotutor-board / cotutor-analyze / cotutor-tune / cotutor-home:它们和解析器、契约、CLI 要一起变),init / upgrade 每次按包里的覆盖、家长改了也刷,状态只有 latest / upgradable;
+ *   其余拷进来就是家长的:upgrade 没改过的换新、改过的报 diff 保留(custom / untracked)。chalk-* 四个是做课包的(2026-10-31 随 drawtell 并进来,原名 drawtell-*)。
+ */
+import { createHash } from 'node:crypto';
+import { cp, lstat, mkdir, readFile, readdir, readlink, rm, symlink } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BOARD_SKILL } from "../../board/cards/docs.js";
+import { ANALYZE_SKILL } from "../skills/analyze-doc.js";
+import { TUNE_SKILL } from "../skills/tune-doc.js";
+import { HOME_SKILL } from "../skills/home-doc.js";
+import { TUTOR_SKILL } from "../../runtime/context/tutor-rules.js";
+import { SKILLS_DIR } from "../../schema/index.js";
+export { ANALYZE_SKILL, BOARD_SKILL, HOME_SKILL, TUNE_SKILL, TUTOR_SKILL };
+import { PACKAGE_VERSION } from "./skeleton.js";
+import { readManifest, writeManifest } from "./tutors.js";
+export const SHIPPED_SKILLS = [
+    { name: TUTOR_SKILL, machine: true },
+    { name: BOARD_SKILL, machine: true },
+    { name: ANALYZE_SKILL, machine: true },
+    { name: TUNE_SKILL, machine: true },
+    { name: HOME_SKILL, machine: true },
+    { name: 'chalk-scene' },
+    { name: 'chalk-teaching' },
+    { name: 'chalk-cli' },
+    { name: 'chalk-verify' },
+];
+/**
+ * 不再出厂的技能:upgrade 时 workspace 里还有(出厂记录里有它)就删掉,免得编程助手照旧技能干活。
+ * 机器件(machine)向来不认家长的改动,照删;别的家长改过就留着,只是不再记在出厂清单里。
+ * cotutor-vault(2026-10-30,机器件):老师从没读过它(孩子的话不带工具,记账那条消息自带写法),要紧的几句并进了守则 cotutor-tutor。
+ * drawtell-*(2026-10-31):drawtell 并进本包,改名 chalk-*,命令是 cotutor chalk
+ */
+export const RETIRED_SKILLS = [{ name: 'cotutor-vault', machine: true }, { name: 'drawtell-scene' }, { name: 'drawtell-teaching' }, { name: 'drawtell-cli' }, { name: 'drawtell-verify' }];
+/** 本包自带的技能目录(仓库检出与 npm 安装都在包根 skills/) */
+export const PACKAGE_SKILLS_DIR = fileURLToPath(new URL('../../../skills/', import.meta.url));
+/** 这个技能在包里的目录 */
+export function skillSourceDir(skill) {
+    return join(PACKAGE_SKILLS_DIR, skill.name);
+}
+/** 一个目录的内容 hash:相对路径 + 内容,按路径排序 */
+export async function dirHash(dir) {
+    const files = [];
+    const walk = async (d) => {
+        for (const e of (await readdir(d, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                await walk(p);
+            else if (e.isFile())
+                files.push(p);
+        }
+    };
+    await walk(dir);
+    const h = createHash('sha256');
+    for (const f of files.sort()) {
+        h.update(relative(dir, f));
+        h.update('\0');
+        h.update(await readFile(f));
+        h.update('\0');
+    }
+    return `sha256:${h.digest('hex')}`;
+}
+export function skillDir(root, name) {
+    return join(root, SKILLS_DIR, name);
+}
+async function readState(root, skill, manifest) {
+    const { name } = skill;
+    const base = { name, machine: Boolean(skill.machine) };
+    const dir = skillDir(root, name);
+    const st = await lstat(dir).catch(() => null);
+    if (!st?.isDirectory())
+        return { ...base, state: 'missing', dir };
+    const rec = manifest.skills?.[name];
+    const mine = await dirHash(dir);
+    const shipped = await dirHash(skillSourceDir(skill)).catch(() => null);
+    if (shipped && mine === shipped)
+        return { ...base, state: 'latest', dir, basedOn: rec?.version };
+    // 机器件不认家长的改动:和包里不一样就是该换
+    if (skill.machine)
+        return { ...base, state: 'upgradable', dir, basedOn: rec?.version };
+    if (rec && rec.hash === mine)
+        return { ...base, state: 'upgradable', dir, basedOn: rec.version };
+    return { ...base, state: rec ? 'custom' : 'untracked', dir, basedOn: rec?.version };
+}
+export async function skillStatuses(root) {
+    const manifest = await readManifest(root);
+    const out = [];
+    for (const skill of SHIPPED_SKILLS)
+        out.push(await readState(root, skill, manifest));
+    return out;
+}
+/** 整个目录换成包里的(先删再拷),hash 记进清单;顺手清旧位置 */
+async function installOne(root, skill, src, manifest) {
+    const dir = skillDir(root, skill.name);
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dirname(dir), { recursive: true });
+    await cp(src, dir, { recursive: true });
+    manifest.skills ??= {};
+    manifest.skills[skill.name] = { hash: await dirHash(dir), version: PACKAGE_VERSION };
+}
+/** init 用:缺的拷,有的不动;机器件每次按包里的刷 */
+export async function installSkills(root) {
+    const steps = [];
+    const manifest = await readManifest(root);
+    let touched = false;
+    for (const skill of SHIPPED_SKILLS) {
+        const { name } = skill;
+        const s = await readState(root, skill, manifest);
+        const src = skillSourceDir(skill);
+        const item = `${SKILLS_DIR}/${name}/`;
+        if (s.state === 'missing') {
+            await installOne(root, skill, src, manifest);
+            touched = true;
+            steps.push({ item, action: 'created', note: skill.machine ? '机器件,从包里生成的技能,别改' : '拷自本包' });
+        }
+        else if (skill.machine) {
+            await installOne(root, skill, src, manifest);
+            touched = true;
+            steps.push({ item, action: 'exists', note: s.state === 'latest' ? '已按本包刷新(机器件)' : '已按本包换新(机器件,不认改动)' });
+        }
+        else
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+    }
+    if (touched)
+        await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** upgrade 用:latest 跳过;upgradable 换新(机器件改过也换);custom / untracked 保留只报;缺的补;不再出厂的删(改过的留) */
+export async function upgradeSkills(root) {
+    const steps = [];
+    const manifest = await readManifest(root);
+    for (const skill of SHIPPED_SKILLS) {
+        const { name } = skill;
+        const machine = Boolean(skill.machine);
+        const s = await readState(root, skill, manifest);
+        const src = skillSourceDir(skill);
+        if (s.state === 'latest')
+            steps.push({ name, action: 'latest', basedOn: s.basedOn, machine });
+        else if (s.state === 'missing') {
+            await installOne(root, skill, src, manifest);
+            steps.push({ name, action: 'installed', machine });
+        }
+        else if (s.state === 'upgradable') {
+            await installOne(root, skill, src, manifest);
+            steps.push({ name, action: 'upgraded', basedOn: s.basedOn, machine });
+        }
+        else
+            steps.push({ name, action: 'kept-custom', basedOn: s.basedOn, machine });
+    }
+    for (const { name, machine } of RETIRED_SKILLS) {
+        const rec = manifest.skills?.[name];
+        if (!rec)
+            continue;
+        const dir = skillDir(root, name);
+        delete manifest.skills[name];
+        // 家长改过的不删:那份已经是她的了,只是不再记在出厂清单里(机器件不算)
+        if (!machine && (await lstat(dir).catch(() => null))?.isDirectory() && (await dirHash(dir)) !== rec.hash) {
+            steps.push({ name, action: 'kept-custom', basedOn: rec.version });
+            continue;
+        }
+        await rm(dir, { recursive: true, force: true });
+        steps.push({ name, action: 'retired', machine: Boolean(machine) });
+    }
+    await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** Claude Code 只认 .claude/skills(Codex、Qwen Code 认 .agents/skills):在那里放一条相对链,两边看到的是同一份 */
+export const CLAUDE_SKILLS_LINK = '.claude/skills';
+/**
+ * init / upgrade 用:没有就建链;已经是链不动;是实体目录(老 workspace 没搬完)不碰,报一声。
+ * Windows 上建目录联接(junction):符号链接要「创建符号链接」权限,家长平常开的终端没有(UAC 拿掉了,开发者模式也多半没开)。
+ * 联接读回来是绝对路径,所以按指到哪儿比、不按字面比。还是建不了就跳过:这条链只给在 workspace 里用 Claude Code 的人,cotutor 自己不读它。
+ */
+export async function linkClaudeSkills(root) {
+    const link = join(root, CLAUDE_SKILLS_LINK);
+    const target = join('..', SKILLS_DIR);
+    const item = `${CLAUDE_SKILLS_LINK} → ${SKILLS_DIR}`;
+    const st = await lstat(link).catch(() => null);
+    if (st?.isSymbolicLink()) {
+        const to = await readlink(link);
+        const key = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+        return key(resolve(dirname(link), to.replace(/^\\\\\?\\/, ''))) === key(resolve(root, SKILLS_DIR)) ? { item, action: 'exists' } : { item, action: 'kept', note: `已经是指向 ${to} 的链,没动` };
+    }
+    if (st)
+        return { item, action: 'kept', note: `${CLAUDE_SKILLS_LINK} 是实体目录,没建链:把里面的技能挪进 ${SKILLS_DIR}/、删掉它,再跑 cotutor upgrade` };
+    await mkdir(dirname(link), { recursive: true });
+    try {
+        await symlink(target, link, process.platform === 'win32' ? 'junction' : undefined);
+    }
+    catch (err) {
+        return { item, action: 'kept', note: `建不了链(${err.code ?? err}),跳过:只影响在 workspace 里用 Claude Code 看技能,cotutor 照常用` };
+    }
+    return { item, action: 'created', note: 'Claude Code 只认 .claude/skills,链到同一份' };
+}

package/dist/app/cli/themes.d.ts

@@ -0,0 +1,52 @@
+import { type ThemeManifest } from '../../schema/index.ts';
+import { UsageError } from '../workspace.ts';
+/** 本包自带的主题目录(仓库检出与 npm 安装都在包根 themes/) */
+export declare const PACKAGE_THEMES_DIR: string;
+export declare const SHIPPED_THEMES: readonly ["default"];
+export declare function themeDir(root: string, name: string): string;
+export declare class ThemeError extends UsageError {
+    readonly dir: string;
+    constructor(dir: string, message: string);
+}
+export interface LoadedTheme {
+    name: string;
+    dir: string;
+    manifest: ThemeManifest;
+    css: string;
+}
+/** 读一个主题目录:清单过契约、css 在;坏了抛 ThemeError(消息就是修复指南) */
+export declare function readTheme(dir: string): Promise<LoadedTheme>;
+/** 出厂主题(包里那份);包坏了是开发错误,直接抛 */
+export declare function packageTheme(name?: string): Promise<LoadedTheme>;
+export type ThemeState = 'latest' | 'upgradable' | 'custom' | 'untracked' | 'missing';
+export interface ThemeStatus {
+    name: string;
+    state: ThemeState;
+    dir: string;
+    basedOn?: string;
+    /** 出厂件与否(自家加的主题 upgrade 不碰) */
+    shipped: boolean;
+}
+/** workspace 里所有主题的状态:出厂的 + themes/ 下自家建的 */
+export declare function themeStatuses(root: string): Promise<ThemeStatus[]>;
+export interface ThemeStep {
+    item: string;
+    action: 'created' | 'exists' | 'kept';
+    note?: string;
+}
+/** init 用:缺的拷,有的不动 */
+export declare function installThemes(root: string): Promise<ThemeStep[]>;
+export interface ThemeUpgradeStep {
+    name: string;
+    action: 'upgraded' | 'latest' | 'kept-custom' | 'installed';
+    basedOn?: string;
+}
+/** upgrade 用:latest 跳过;upgradable 换新;custom / untracked 保留只报;缺的补 */
+export declare function upgradeThemes(root: string): Promise<ThemeUpgradeStep[]>;
+export interface AddThemeResult {
+    name: string;
+    dir: string;
+    from: string;
+}
+/** cotutor add-theme <name> [--from <主题>]:拷一份(缺省 default)来改;清单里的 name 改成新名 */
+export declare function addTheme(root: string, name: string, from?: string): Promise<AddThemeResult>;

package/dist/app/cli/themes.js

@@ -0,0 +1,148 @@
+/**
+ * 主题(themes/<name>/theme.json + kid.css):孩子端板书的样子。样子的真相在主题里,不在卡的协议里。
+ * 出厂主题 default 在包根 themes/default/;init **拷贝**进 workspace 的 themes/default/(拷进来就是家长的,改了刷新就有),
+ * 目录 hash 记 .cotutor/shipped.json 的 themes,与老师文件 / skill 同一套:没改过的随 cotutor upgrade 换新,改过的报 diff 保留。
+ * 自家的主题(cotutor add-theme <name> 拷一份 default 来改,或直接建目录)永远 untracked,upgrade 不碰。
+ */
+import { cp, lstat, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { THEME_CSS_FILE, THEME_MANIFEST_FILE, THEME_NAME_RE, THEMES_DIR, ThemeManifestSchema, explainIssues } from "../../schema/index.js";
+import { PACKAGE_VERSION } from "./skeleton.js";
+import { dirHash } from "./skills.js";
+import { readManifest, writeManifest } from "./tutors.js";
+import { UsageError } from "../workspace.js";
+/** 本包自带的主题目录(仓库检出与 npm 安装都在包根 themes/) */
+export const PACKAGE_THEMES_DIR = fileURLToPath(new URL('../../../themes/', import.meta.url));
+export const SHIPPED_THEMES = ['default'];
+export function themeDir(root, name) {
+    return join(root, THEMES_DIR, name);
+}
+export class ThemeError extends UsageError {
+    dir;
+    constructor(dir, message) {
+        super(message);
+        this.name = 'ThemeError';
+        this.dir = dir;
+    }
+}
+/** 读一个主题目录:清单过契约、css 在;坏了抛 ThemeError(消息就是修复指南) */
+export async function readTheme(dir) {
+    const mf = join(dir, THEME_MANIFEST_FILE);
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(mf, 'utf8'));
+    }
+    catch (err) {
+        throw new ThemeError(dir, `${mf} 读不到或不是 JSON:${err instanceof Error ? err.message : String(err)}`);
+    }
+    const r = ThemeManifestSchema.safeParse(raw);
+    if (!r.success)
+        throw new ThemeError(dir, `${mf} 不合契约:\n${explainIssues(r.error.issues)}`);
+    let css;
+    try {
+        css = await readFile(join(dir, THEME_CSS_FILE), 'utf8');
+    }
+    catch {
+        throw new ThemeError(dir, `${join(dir, THEME_CSS_FILE)} 不在(主题的样式文件)`);
+    }
+    return { name: r.data.name, dir, manifest: r.data, css };
+}
+/** 出厂主题(包里那份);包坏了是开发错误,直接抛 */
+export function packageTheme(name = 'default') {
+    return readTheme(join(PACKAGE_THEMES_DIR, name));
+}
+async function readState(root, name, manifest) {
+    const dir = themeDir(root, name);
+    const shipped = SHIPPED_THEMES.includes(name);
+    const st = await lstat(dir).catch(() => null);
+    if (!st?.isDirectory())
+        return { name, state: 'missing', dir, shipped };
+    if (!shipped)
+        return { name, state: 'untracked', dir, shipped };
+    const rec = manifest.themes?.[name];
+    const mine = await dirHash(dir);
+    const factory = await dirHash(join(PACKAGE_THEMES_DIR, name)).catch(() => null);
+    if (factory && mine === factory)
+        return { name, state: 'latest', dir, basedOn: rec?.version, shipped };
+    if (rec && rec.hash === mine)
+        return { name, state: 'upgradable', dir, basedOn: rec.version, shipped };
+    return { name, state: rec ? 'custom' : 'untracked', dir, basedOn: rec?.version, shipped };
+}
+/** workspace 里所有主题的状态:出厂的 + themes/ 下自家建的 */
+export async function themeStatuses(root) {
+    const manifest = await readManifest(root);
+    const names = new Set(SHIPPED_THEMES);
+    for (const e of await readdir(join(root, THEMES_DIR), { withFileTypes: true }).catch(() => []))
+        if (e.isDirectory() && THEME_NAME_RE.test(e.name))
+            names.add(e.name);
+    const out = [];
+    for (const name of [...names].sort())
+        out.push(await readState(root, name, manifest));
+    return out;
+}
+async function installOne(root, name, manifest) {
+    const dir = themeDir(root, name);
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    await cp(join(PACKAGE_THEMES_DIR, name), dir, { recursive: true });
+    manifest.themes ??= {};
+    manifest.themes[name] = { hash: await dirHash(dir), version: PACKAGE_VERSION };
+}
+/** init 用:缺的拷,有的不动 */
+export async function installThemes(root) {
+    const steps = [];
+    const manifest = await readManifest(root);
+    let touched = false;
+    for (const name of SHIPPED_THEMES) {
+        const s = await readState(root, name, manifest);
+        const item = `${THEMES_DIR}/${name}/`;
+        if (s.state === 'missing') {
+            await installOne(root, name, manifest);
+            touched = true;
+            steps.push({ item, action: 'created', note: '孩子端的主题(theme.json 槽的清单 + kid.css 样式),拷自本包,改了刷新就有' });
+        }
+        else
+            steps.push({ item, action: 'exists', note: s.state === 'custom' ? `自定义(基于 ${s.basedOn})` : s.state === 'upgradable' ? '可升级(cotutor upgrade)' : s.state === 'untracked' ? '已有(没有出厂记录);升级时当自定义对待' : undefined });
+    }
+    if (touched)
+        await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** upgrade 用:latest 跳过;upgradable 换新;custom / untracked 保留只报;缺的补 */
+export async function upgradeThemes(root) {
+    const manifest = await readManifest(root);
+    const steps = [];
+    for (const name of SHIPPED_THEMES) {
+        const s = await readState(root, name, manifest);
+        if (s.state === 'latest')
+            steps.push({ name, action: 'latest', basedOn: s.basedOn });
+        else if (s.state === 'missing') {
+            await installOne(root, name, manifest);
+            steps.push({ name, action: 'installed' });
+        }
+        else if (s.state === 'upgradable') {
+            await installOne(root, name, manifest);
+            steps.push({ name, action: 'upgraded', basedOn: s.basedOn });
+        }
+        else
+            steps.push({ name, action: 'kept-custom', basedOn: s.basedOn });
+    }
+    await writeManifest(root, { ...manifest, version: PACKAGE_VERSION });
+    return steps;
+}
+/** cotutor add-theme <name> [--from <主题>]:拷一份(缺省 default)来改;清单里的 name 改成新名 */
+export async function addTheme(root, name, from = 'default') {
+    if (!THEME_NAME_RE.test(name))
+        throw new UsageError(`主题名只能是小写字母、数字、连字符:${name}`);
+    const dir = themeDir(root, name);
+    if (await lstat(dir).catch(() => null))
+        throw new UsageError(`${dir} 已经在了`);
+    const srcDir = (await lstat(themeDir(root, from)).catch(() => null))?.isDirectory() ? themeDir(root, from) : join(PACKAGE_THEMES_DIR, from);
+    const src = await readTheme(srcDir);
+    await mkdir(dir, { recursive: true });
+    await cp(srcDir, dir, { recursive: true });
+    const raw = JSON.parse(await readFile(join(dir, THEME_MANIFEST_FILE), 'utf8'));
+    await writeFile(join(dir, THEME_MANIFEST_FILE), `${JSON.stringify({ ...raw, name }, null, 2)}\n`);
+    return { name, dir, from: src.name };
+}

package/dist/app/cli/tray-icons.d.ts

@@ -0,0 +1,11 @@
+export declare const TRAY_DOT: {
+    r: number;
+    cx: number;
+};
+/** 没在跑时 logo 的不透明度(#F3F3F3 上墨色对比度 3.3,#202020 上白色 5.8) */
+export declare const TRAY_DIM = 0.55;
+export declare const TRAY_WIN_SIZES: readonly [16, 20, 24, 32, 40, 48];
+/** 文件名 → 内容:macOS 那几张 */
+export declare function macTrayIcons(): Record<string, Buffer>;
+/** 文件名 → 内容:Windows 那几张(<white|ink>-<ok|warn|bad>-<尺寸>.png、dot-<状态>.png) */
+export declare function windowsTrayIcons(): Record<string, Buffer>;