cotutor 0.2.0 → 0.3.0

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

@@ -0,0 +1,14 @@
+export declare const DEFAULT_GRADE = 2;
+/** 历史出厂内容永远归二年级,不能随未来新安装的默认年级变化。 */
+export declare const LEGACY_GRADE = 2;
+export declare const PACKAGE_GRADES_DIR: string;
+export interface GradePack {
+    grade: number;
+    dir: string;
+    agentsDir: string;
+}
+/** 不把任意字符串拼进路径。缺文件的包不算可安装。 */
+export declare function gradePacks(base?: string): Promise<GradePack[]>;
+export declare function requireGradePack(grade: number, base?: string): Promise<GradePack>;
+/** 没有来源字段的旧版内容来自现在的二年级包;不据此修改孩子档案。 */
+export declare function workspaceGradePack(root: string): Promise<GradePack>;

package/dist/app/cli/grades.js

@@ -0,0 +1,44 @@
+/** 年级包只负责出厂来源;运行时继续读 workspace 里的家长文件。 */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readManifest } from "./shipped.js";
+import { UsageError } from "../workspace.js";
+export const DEFAULT_GRADE = 2;
+/** 历史出厂内容永远归二年级,不能随未来新安装的默认年级变化。 */
+export const LEGACY_GRADE = 2;
+export const PACKAGE_GRADES_DIR = fileURLToPath(new URL('../../../grades/', import.meta.url));
+/** 不把任意字符串拼进路径。缺文件的包不算可安装。 */
+export async function gradePacks(base = PACKAGE_GRADES_DIR) {
+    const entries = await readdir(base, { withFileTypes: true });
+    const packs = [];
+    for (const e of entries) {
+        const match = /^grade-([1-6])$/.exec(e.name);
+        if (!e.isDirectory() || !match)
+            continue;
+        const dir = join(base, e.name);
+        const agentsDir = join(dir, 'agents');
+        const required = ['chinese-tutor', 'math-tutor', 'english-tutor'];
+        if (!(await stat(join(dir, 'README.md')).catch(() => null))?.isFile())
+            continue;
+        if (!(await Promise.all(required.map(async (name) => (await stat(join(agentsDir, `${name}.md`)).catch(() => null))?.isFile()
+            && (await stat(join(agentsDir, name, 'activities')).catch(() => null))?.isDirectory()))).every(Boolean))
+            continue;
+        packs.push({ grade: Number(match[1]), dir, agentsDir });
+    }
+    return packs.sort((a, b) => a.grade - b.grade);
+}
+export async function requireGradePack(grade, base = PACKAGE_GRADES_DIR) {
+    if (!Number.isInteger(grade) || grade < 1 || grade > 6)
+        throw new UsageError('年级要是 1–6 的整数,如 --grade 2');
+    const packs = await gradePacks(base);
+    const pack = packs.find((p) => p.grade === grade);
+    if (!pack)
+        throw new UsageError(`本包没有完整的 ${grade} 年级教学包;可用年级:${packs.map((p) => p.grade).join('、') || '无'}。不会自动使用其他年级。`);
+    return pack;
+}
+/** 没有来源字段的旧版内容来自现在的二年级包;不据此修改孩子档案。 */
+export async function workspaceGradePack(root) {
+    const manifest = await readManifest(root);
+    return requireGradePack(manifest.teachingPack?.grade ?? LEGACY_GRADE);
+}

package/dist/{cli → app/cli}/init.d.ts

@@ -1,6 +1,6 @@
 export interface InitStep {
     item: string;
-    action: 'created' | 'exists' | 'kept' | 'replaced';
+    action: 'created' | 'exists' | 'kept' | 'replaced' | 'removed' | 'moved';
     note?: string;
 }
 export interface InitResult {
@@ -13,5 +13,7 @@ export interface InitOptions {
     dir?: string;
     name?: string;
     port?: number;
+    /** 出厂教学包年级,不是孩子档案的覆盖值。 */
+    grade?: number;
 }
 export declare function initWorkspace(opts: InitOptions): Promise<InitResult>;

package/dist/app/cli/init.js

@@ -0,0 +1,155 @@
+/**
+ * cotutor init <slug>:建 ~/cotutor/<slug>/ 骨架。语义是**幂等补缺**——已有的文件与目录一律不动,缺什么补什么。
+ * 三条边界(沿 drawtell init):政策文件只在缺失时写模板;用户配置只在还没指定 workspace 时补;不动 git。
+ * 老师文件**拷贝**进 agents/<name>.md:拷进来就是家长的,想改就改;出厂 hash 记 .cotutor/shipped.json,
+ * cotutor upgrade 据此换新或报 diff。老布局(.claude/agents、.claude/skills)先原样挪到新位置(migrate.ts 的 migrateLayout)。
+ */
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { DIRS, GITIGNORE, LEDGER_FILES, REFERENCE_README, configTemplate, profileTemplate, shippedAgents, writeSchemaFile } from "./skeleton.js";
+import { installTutors, readManifest, writeManifest } from "./tutors.js";
+import { DEFAULT_GRADE, LEGACY_GRADE, requireGradePack } from "./grades.js";
+import { installActivities } from "./activities.js";
+import { installSkills, linkClaudeSkills } from "./skills.js";
+import { migrateLayout } from "./migrate.js";
+import { installThemes } from "./themes.js";
+import { scanVault } from "../../memory/vault.js";
+import { CONFIG_FILE, ConfigError, UsageError, HOME_ROOT, USER_CONFIG, expandPath, loadWorkspace, parseConfig, readJson, redactHome } from "../workspace.js";
+async function exists(p) {
+    return (await stat(p).catch(() => null)) !== null;
+}
+export async function initWorkspace(opts) {
+    const root = opts.dir ? expandPath(opts.dir, resolve(process.cwd())) : join(HOME_ROOT, opts.slug);
+    const steps = [];
+    const manifest = await readManifest(root);
+    const installed = manifest.teachingPack?.grade;
+    const existing = await exists(join(root, CONFIG_FILE));
+    const grade = opts.grade ?? installed ?? (existing ? LEGACY_GRADE : DEFAULT_GRADE);
+    const pack = await requireGradePack(grade);
+    if (existing && grade !== (installed ?? LEGACY_GRADE))
+        throw new UsageError('init 只补缺,不能切换已有 workspace 的年级包;请另建 workspace,原有自定义文件和话题保持不动。');
+    if (installed !== undefined && installed !== grade)
+        throw new UsageError(`已安装 ${installed} 年级包,init 不切换年级`);
+    const agents = await shippedAgents(pack.agentsDir);
+    const rootExisted = await exists(root);
+    if (!rootExisted)
+        await mkdir(root, { recursive: true });
+    manifest.teachingPack = { grade };
+    await writeManifest(root, manifest);
+    steps.push({ item: 'teachingPack', action: installed === undefined ? 'created' : 'exists', note: `${grade} 年级教学包${existing && installed === undefined ? '(旧版来源补记,保留原 hash)' : opts.grade === undefined && installed === undefined ? '(默认)' : ''};孩子当前年级仍读档案` });
+    steps.push({ item: '.', action: rootExisted ? 'exists' : 'created' });
+    // 老布局先搬,再补缺:不然出厂件先占了新位置,家长改过的那份晾在老位置
+    steps.push(...(await migrateLayout(root)));
+    for (const dir of DIRS) {
+        const p = join(root, dir);
+        if (await exists(p)) {
+            steps.push({ item: `${dir}/`, action: 'exists' });
+            continue;
+        }
+        await mkdir(p, { recursive: true });
+        steps.push({ item: `${dir}/`, action: 'created' });
+    }
+    const config = join(root, CONFIG_FILE);
+    if (await exists(config))
+        steps.push({ item: CONFIG_FILE, action: 'kept', note: '政策文件不覆盖(家长的决定)' });
+    else {
+        await writeFile(config, configTemplate({ slug: opts.slug, name: opts.name, port: opts.port, tutors: agents }));
+        steps.push({ item: CONFIG_FILE, action: 'created' });
+    }
+    // 老师按 cotutor.json 里有谁走(家长自己加的也补目录与链);配置坏了就只管出厂的,doctor 去报
+    let tutorNames = [];
+    try {
+        const raw = readJson(config);
+        if (raw !== null)
+            tutorNames = Object.keys(parseConfig(raw, config).tutors);
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError))
+            throw err;
+    }
+    steps.push(...(await installTutors(root, tutorNames)));
+    // 出厂 activity(老师的家里 agents/<老师>/activities/):缺的拷,有的不动
+    steps.push(...(await installActivities(root)));
+    const schemaThere = await exists(join(root, '.cotutor', 'cotutor.schema.json'));
+    await writeSchemaFile(root);
+    steps.push({ item: '.cotutor/cotutor.schema.json', action: schemaThere ? 'exists' : 'created', note: schemaThere ? '已按本包刷新(机器文件)' : 'cotutor.json 的 JSON Schema,编辑器补全用' });
+    // 出厂 skill(机器件 cotutor-board 等 + 做课包的四个 chalk-*)
+    steps.push(...(await installSkills(root)));
+    steps.push(await linkClaudeSkills(root));
+    // 出厂主题(孩子端板书的样子):拷进 themes/default/,是家长的
+    steps.push(...(await installThemes(root)));
+    for (const f of LEDGER_FILES) {
+        const p = join(root, f);
+        if (await exists(p))
+            steps.push({ item: f, action: 'exists' });
+        else {
+            await writeFile(p, '');
+            steps.push({ item: f, action: 'created' });
+        }
+    }
+    // vault 侧(《obsidian仓库设计.md》§2):只补档案与参考 README,缺了才写;档案按 cotutor: profile 找(2026-09-17),vault 里已有一篇就不补;
+    // 入口文件(每科每学期一篇)不自动建,doctor 提醒;日记由记账现建,计划家长自己写
+    try {
+        const ws = loadWorkspace(root);
+        const profile = ws.paths.profile;
+        const found = (await scanVault(ws)).notes.find((n) => n.props.cotutor === 'profile');
+        if (found)
+            steps.push({ item: redactHome(join(ws.paths.vault, found.path)), action: 'exists' });
+        else if (await exists(profile))
+            steps.push({ item: redactHome(profile), action: 'kept', note: '没有 cotutor: profile 属性,老师读不到;在 frontmatter 加上(cotutor doctor 有写法)' });
+        else {
+            await mkdir(dirname(profile), { recursive: true });
+            await writeFile(profile, profileTemplate(ws.config.kid.name ?? ws.config.kid.slug));
+            steps.push({ item: redactHome(profile), action: 'created', note: '档案:填 school_start 与孩子的情况,每个话题开头整篇进上下文包' });
+        }
+        const readme = join(ws.paths.reference, 'README.md');
+        if (await exists(readme))
+            steps.push({ item: redactHome(readme), action: 'exists' });
+        else {
+            await mkdir(ws.paths.reference, { recursive: true });
+            await writeFile(readme, REFERENCE_README);
+            steps.push({ item: redactHome(readme), action: 'created' });
+        }
+    }
+    catch {
+        /* 配置读不了(doctor 去体检):vault 侧不动 */
+    }
+    const gitignore = join(root, '.gitignore');
+    if (await exists(gitignore))
+        steps.push({ item: '.gitignore', action: 'kept' });
+    else {
+        await writeFile(gitignore, GITIGNORE);
+        steps.push({ item: '.gitignore', action: 'created' });
+    }
+    // 用户配置:补缺不改向;解析不了也不动(doctor 去体检)
+    let user = null;
+    let userBroken = false;
+    try {
+        user = JSON.parse(await readFile(USER_CONFIG, 'utf8'));
+    }
+    catch (err) {
+        userBroken = err.code !== 'ENOENT';
+    }
+    const configured = user && typeof user.workspace === 'string' && user.workspace ? user.workspace : null;
+    if (userBroken)
+        steps.push({ item: 'user-config', action: 'kept', note: '解析失败,未动(cotutor doctor 可体检)' });
+    else if (configured) {
+        steps.push(expandPath(configured, root) === root
+            ? { item: 'user-config', action: 'exists', note: '已指向本workspace' }
+            : { item: 'user-config', action: 'kept', note: '已指向别的workspace,未改;多孩子时一 workspace 一进程,用 --workspace / COTUTOR_WORKSPACE 指定' });
+    }
+    else {
+        await mkdir(dirname(USER_CONFIG), { recursive: true });
+        await writeFile(USER_CONFIG, `${JSON.stringify({ ...(user ?? {}), workspace: root }, null, 2)}\n`);
+        steps.push({ item: 'user-config', action: 'created', note: 'workspace 指向本workspace' });
+    }
+    const suggestions = [];
+    if (!(await exists(join(root, '.git'))))
+        suggestions.push('git init(建议:老师记忆、账本、政策都是不可再生状态,git 是破坏后的兜底)');
+    suggestions.push('档案里填 school_start(读一年级的年月,如 2025-09),老师才知道现在是几年级哪个学期;想用自己的 Obsidian 库,改 cotutor.json 的 paths.vault');
+    suggestions.push('cotutor serve 起服务,在这台电脑上打开家长端 /parent 的「首页」,填百炼的按量 API Key 与业务空间 ID(老师的嘴和脑都用它;没填孩子端只出「老师们还没到」)');
+    suggestions.push('在 iPad / iPhone 上用:cotutor cert 签证书(要 mkcert),根证书装到设备上并打开信任,步骤见 README 里的《iPad 与 iPhone》');
+    suggestions.push('可选:点读、单词卡的配音用百炼(和老师的嘴同一把 key),到工作台 /dev 的「音色」页给老师挑声音;cotutor pin 给家长端与工作台加锁');
+    suggestions.push('cotutor doctor 逐项体检');
+    return { root, steps, suggestions };
+}