cotutor 0.1.0

package/dist/cli/main.js

@@ -0,0 +1,123 @@
+/**
+ * cotutor CLI 入口。命令:init / doctor / serve;全局 --workspace <dir>、--json。
+ * exit:0 通过 / 1 体检不过 / 2 用法错误 / 4 内部错误。
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { doctorWorkspace } from "./doctor.js";
+import { initWorkspace } from "./init.js";
+import { serveWorkspace } from "./serve.js";
+import { UsageError, redactDeep, redactHome, workspaceReport } from "./workspace.js";
+const USAGE = `用法:
+  cotutor init <slug> [--dir <path>] [--name <孩子名>] [--port <n>]   建 ~/cotutor/<slug>/ 骨架(幂等补缺)
+  cotutor doctor [--workspace <dir>] [--json]                          逐项体检
+  cotutor serve [--workspace <dir>] [--port <n>]                        起服务(一 workspace 一进程)
+  cotutor --version | --help
+工作区解析:--workspace > COTUTOR_WORKSPACE > cwd 或祖先有 cotutor.json > ~/.config/cotutor/config.json > ~/cotutor/ 下唯一的孩子目录
+`;
+function version() {
+    const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+    return pkg.version;
+}
+function parseArgs(argv, valued) {
+    const flags = {};
+    const positionals = [];
+    let cmd;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            if (valued.includes(key)) {
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith('--'))
+                    throw new UsageError(`选项 --${key} 需要一个值。\n${USAGE}`);
+                flags[key] = next;
+                i++;
+            }
+            else
+                flags[key] = true;
+        }
+        else if (cmd === undefined)
+            cmd = a;
+        else
+            positionals.push(a);
+    }
+    return { cmd, positionals, flags };
+}
+export async function main(argv) {
+    let json = false;
+    try {
+        const { cmd, positionals, flags } = parseArgs(argv, ['workspace', 'dir', 'name', 'port']);
+        json = flags.json === true;
+        const workspace = typeof flags.workspace === 'string' ? flags.workspace : undefined;
+        // --version / --help 是旗标不是命令,parseArgs 把它们收进 flags,cmd 拿不到,所以在 switch 前处理
+        if (flags.version === true || cmd === '-v') {
+            process.stdout.write(`${version()}\n`);
+            return;
+        }
+        if (flags.help === true || cmd === undefined || cmd === '-h') {
+            process.stdout.write(USAGE);
+            return;
+        }
+        switch (cmd) {
+            case 'init': {
+                const slug = positionals[0];
+                if (!slug || !/^[a-z0-9][a-z0-9-]*$/.test(slug))
+                    throw new UsageError(`init 需要一个 slug(小写字母数字连字符,是短名不是真名),如 cotutor init ming。\n${USAGE}`);
+                const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
+                if (port !== undefined && !(Number.isInteger(port) && port > 0 && port < 65536))
+                    throw new UsageError('--port 要是 1–65535 的整数');
+                const r = await initWorkspace({ slug, dir: typeof flags.dir === 'string' ? flags.dir : undefined, name: typeof flags.name === 'string' ? flags.name : undefined, port });
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    process.stdout.write(`cotutor init → ${redactHome(r.root)}\n`);
+                    for (const s of r.steps)
+                        process.stdout.write(`  ${s.action.padEnd(7)} ${s.item}${s.note ? `  (${s.note})` : ''}\n`);
+                    process.stdout.write('下一步:\n');
+                    for (const s of r.suggestions)
+                        process.stdout.write(`  - ${s}\n`);
+                }
+                return;
+            }
+            case 'doctor': {
+                const r = await doctorWorkspace(workspace);
+                if (json)
+                    process.stdout.write(`${JSON.stringify(redactDeep(r), null, 2)}\n`);
+                else {
+                    for (const c of r.checks) {
+                        process.stdout.write(`${c.ok ? '✓' : c.required ? '✗' : '!'} ${c.name.padEnd(28)} ${c.detail}\n`);
+                        if (!c.ok && c.fix)
+                            process.stdout.write(`    修复:${c.fix}\n`);
+                    }
+                    process.stdout.write(r.ok ? '体检通过\n' : '体检不过(✗ 是必需项)\n');
+                }
+                if (!r.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            case 'serve': {
+                const port = typeof flags.port === 'string' ? Number(flags.port) : undefined;
+                const r = await serveWorkspace({ workspace, port });
+                process.stdout.write(`cotutor serve ${JSON.stringify(workspaceReport(r.ws))}\n`);
+                for (const w of r.warnings)
+                    process.stdout.write(`  ! ${w}\n`);
+                process.stdout.write(`  ${r.url}\n`);
+                return;
+            }
+            default:
+                throw new UsageError(`未知命令 '${cmd}'。\n${USAGE}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            if (json)
+                process.stdout.write(`${JSON.stringify({ ok: false, error: 'usage', message: err.message })}\n`);
+            else
+                process.stderr.write(`cotutor: ${err.message}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        throw err;
+    }
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * cotutor serve:一 workspace 一进程(2026-09-08 拍板),端口读 cotutor.json(--port 覆盖)。
+ * 启动打印解析结果与体检警告(配置坏了直接不起,骨架缺失只警告)。
+ */
+import { type Server } from 'node:http';
+import { type ResolveOptions, type Workspace } from './workspace.ts';
+export interface ServeOptions extends ResolveOptions {
+    workspace?: string;
+    port?: number;
+    host?: string;
+}
+export interface ServeResult {
+    server: Server;
+    ws: Workspace;
+    port: number;
+    url: string;
+    warnings: string[];
+}
+export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;

package/dist/cli/serve.js

@@ -0,0 +1,22 @@
+/**
+ * cotutor serve:一 workspace 一进程(2026-09-08 拍板),端口读 cotutor.json(--port 覆盖)。
+ * 启动打印解析结果与体检警告(配置坏了直接不起,骨架缺失只警告)。
+ */
+import { createServer } from 'node:http';
+import { hostname } from 'node:os';
+import { doctorWorkspace } from "./doctor.js";
+import { createHandler } from "../server/app.js";
+import { loadWorkspace } from "./workspace.js";
+export async function serveWorkspace(opts = {}) {
+    const ws = loadWorkspace(opts.workspace, opts);
+    const report = await doctorWorkspace(ws.root, { ...opts, probeEnv: false });
+    const warnings = report.checks.filter((c) => !c.ok).map((c) => `${c.name}:${c.detail}${c.fix ? `(${c.fix})` : ''}`);
+    const port = opts.port ?? ws.config.server.port;
+    const server = createServer(createHandler(ws));
+    await new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(port, opts.host ?? '0.0.0.0', () => resolveListen());
+    });
+    const actual = server.address().port;
+    return { server, ws, port: actual, url: `http://${hostname()}:${actual}/`, warnings };
+}

package/dist/cli/skeleton.d.ts

@@ -0,0 +1,21 @@
+export declare const DIRS: readonly ["agents", "ledger", "conversations", ".claude/agents", ".qwen/agents"];
+export declare const LEDGER_FILES: readonly ["ledger/observations.jsonl", "ledger/artifacts.jsonl"];
+/** 本包自带的老师定义目录(仓库检出与 npm 安装都在包根 agents/) */
+export declare const PACKAGE_AGENTS_DIR: string;
+export interface ShippedAgent {
+    name: string;
+    file: string;
+    description: string;
+}
+export declare function shippedAgents(dir?: string): Promise<ShippedAgent[]>;
+export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u4F1A\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\nnode_modules/\n.DS_Store\n";
+/** 家规:所有老师常驻(CLAUDE.md 与 QWEN.md 同一份)。故意短。 */
+export declare const RULES = "# \u5BB6\u89C4\n\n- \u5173\u4E8E\u5B69\u5B50\u7684\u89C2\u5BDF,\u5199\u4E00\u6761\u5230 ledger/observations.jsonl(\u4E00\u884C JSON:id\u3001date\u3001author=\u4F60\u7684\u540D\u5B57\u3001claim \u4E00\u53E5\u8BDD\u3001evidence \u6307\u5411\u4F1A\u8BDD\u6216\u4EA7\u7269),\u522B\u7684\u8001\u5E08\u548C\u89C4\u5212\u8001\u5E08\u4ECE\u90A3\u91CC\u8BFB\u3002\n- \u4F60\u81EA\u5DF1\u7684\u7ECF\u9A8C\u8BB0\u8FDB\u4F60\u7684\u8BB0\u5FC6\u76EE\u5F55(MEMORY.md \u4E00\u884C\u7D22\u5F15 + \u4E3B\u9898\u6587\u4EF6)\u3002\n- \u4F60\u8BF4\u7ED9\u5B69\u5B50\u542C\u7684\u8BDD\u653E\u5728\u56DE\u590D\u7684**\u6700\u540E\u4E00\u6BB5**,\u5B69\u5B50\u53EA\u770B\u5F97\u5230\u6700\u540E\u4E00\u6BB5;\u4E2D\u95F4\u7684\u8BDD\u548C\u5DE5\u5177\u8FC7\u7A0B\u53EA\u6709\u5BB6\u957F\u770B\u3002\n- \u9700\u8981\u5BB6\u957F\u62CD\u677F\u7684\u4E8B\u5199\u6210\u4E00\u6BB5\u300C## \u5F85\u88C1\u91CF\u300D(question: \u4E00\u53E5\u8BDD;options: \u5217\u8868),\u4E0D\u8981\u505C\u4E0B\u6765\u7B49\u3002\n- \u8981\u4EA4\u7ED9\u522B\u7684\u8001\u5E08\u7684\u4E8B\u5199\u6210\u4E00\u6BB5\u300C## \u8F6C\u4EA4\u300D(to: \u8001\u5E08\u540D;why: \u4E00\u53E5\u8BDD;refs: \u76F8\u5173\u6587\u4EF6),\u7B2C\u4E00\u671F\u53EA\u5141\u8BB8\u4E00\u8DF3\u3002\n- \u4F1A\u8BDD\u6309\u5929,\u660E\u5929\u4ECE\u8D26\u672C\u548C\u4F60\u7684\u8BB0\u5FC6\u63A5\u7740\u6765,\u4E0D\u8981\u6307\u671B\u4ECA\u5929\u7684\u5BF9\u8BDD\u8FD8\u5728\u3002\n";
+export interface ConfigTemplateInput {
+    slug: string;
+    name?: string;
+    port?: number;
+    teachers: ShippedAgent[];
+}
+/** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器替她拍板)。 */
+export declare function configTemplate(input: ConfigTemplateInput): string;

package/dist/cli/skeleton.js

@@ -0,0 +1,82 @@
+/**
+ * 工作区骨架清单:init 建、doctor 查,同一张清单(两边各写一遍必然漂移)。
+ * 布局见《cotutor-agent层设计.md》§2:
+ *   cotutor.json / CLAUDE.md QWEN.md(家规)/ .claude/agents .qwen/agents(老师定义链自本包 agents/)
+ *   agents/<name>/(老师的家 = 会话 cwd)/ ledger/(两本账)/ conversations/(会话索引与转录)
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseAgentFile } from "../lib/agent-file.js";
+export const DIRS = ['agents', 'ledger', 'conversations', '.claude/agents', '.qwen/agents'];
+export const LEDGER_FILES = ['ledger/observations.jsonl', 'ledger/artifacts.jsonl'];
+/** 本包自带的老师定义目录(仓库检出与 npm 安装都在包根 agents/) */
+export const PACKAGE_AGENTS_DIR = fileURLToPath(new URL('../../agents/', import.meta.url));
+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
+node_modules/
+.DS_Store
+`;
+/** 家规:所有老师常驻(CLAUDE.md 与 QWEN.md 同一份)。故意短。 */
+export const RULES = `# 家规
+
+- 关于孩子的观察,写一条到 ledger/observations.jsonl(一行 JSON:id、date、author=你的名字、claim 一句话、evidence 指向会话或产物),别的老师和规划老师从那里读。
+- 你自己的经验记进你的记忆目录(MEMORY.md 一行索引 + 主题文件)。
+- 你说给孩子听的话放在回复的**最后一段**,孩子只看得到最后一段;中间的话和工具过程只有家长看。
+- 需要家长拍板的事写成一段「## 待裁量」(question: 一句话;options: 列表),不要停下来等。
+- 要交给别的老师的事写成一段「## 转交」(to: 老师名;why: 一句话;refs: 相关文件),第一期只允许一跳。
+- 会话按天,明天从账本和你的记忆接着来,不要指望今天的对话还在。
+`;
+const TEACHER_PRESETS = {
+    'math-teacher': { display: '数学老师', subject: '数学', avatar: '🧮' },
+    'chinese-teacher': { display: '语文老师', subject: '语文', avatar: '📚' },
+    'reading-teacher': { display: '朗读老师', subject: '英语', avatar: '📖' },
+    'homework-aide': { display: '作业助教', avatar: '📷' },
+    planner: { display: '规划老师', avatar: '🗓', hidden: true },
+};
+/** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器替她拍板)。 */
+export function configTemplate(input) {
+    const teachers = {};
+    for (const a of input.teachers) {
+        const p = TEACHER_PRESETS[a.name];
+        teachers[a.name] = p
+            ? { display: p.display, ...(p.subject ? { subject: p.subject } : {}), avatar: p.avatar, enabled: true, ...(p.hidden ? { hidden: true } : {}) }
+            : { display: a.name, enabled: true };
+    }
+    const cfg = {
+        version: 1,
+        title: input.name ? `${input.name}的书房` : 'cotutor',
+        kid: { slug: input.slug, ...(input.name ? { name: input.name } : {}) },
+        server: { port: input.port ?? 5180 },
+        paths: {},
+        policyDefaults: {},
+        teachers,
+        agents: {
+            default: 'claude',
+            claude: {
+                run: ['claude', '--agent', '{agent}', '-p', '{prompt}', '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', '--max-budget-usd', '2'],
+                resume: ['claude', '--agent', '{agent}', '-p', '--resume', '{session}', '{prompt}', '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', '--max-budget-usd', '2'],
+            },
+            qwen: {
+                run: ['qwen', '-p', '{prompt}', '--append-system-prompt', '{agentBody}', '--yolo', '--output-format', 'stream-json', '--max-wall-time', '10m'],
+                resume: ['qwen', '-p', '{prompt}', '--resume', '{session}', '--append-system-prompt', '{agentBody}', '--yolo', '--output-format', 'stream-json', '--max-wall-time', '10m'],
+            },
+        },
+        _note: '一孩一 workspace 的政策文件,家长改这里;机器不会自动重建或覆盖,写坏了靠 git 回退,cotutor doctor 可体检。' +
+            'teachers = 老师表(key 与 .claude/agents/<key>.md 的 name 一致):display 显示名、avatar、voice 用 voxtell 音色 id、enabled 开关、hidden 孩子端不露、policy 覆盖 policyDefaults。' +
+            'policyDefaults 缺省:replyMaxChars 60、dailyMessages 30、dailyRegen 3、reviewGate false、contextPack {recent 10, planLines 10}。' +
+            'paths = 角色映射:vault 指 Obsidian vault 根(一孩一 vault),photos/diary/plans/profile/timetable 相对 vault。' +
+            'agents = 运行时预设,占位 {agent} {agentBody} {prompt} {session};政策旋钮(预算、时限)写进模板。',
+    };
+    return `${JSON.stringify(cfg, null, 2)}\n`;
+}

package/dist/cli/workspace.d.ts

@@ -0,0 +1,61 @@
+import { type CotutorConfig, type PathRole } from '../schema/index.ts';
+/** 用法错误:main 捕获后 exit 2,错误信息即修复指南。 */
+export declare class UsageError extends Error {
+}
+/** 配置文件损坏或形状不对:文件在,但用不了。 */
+export declare class ConfigError extends UsageError {
+    readonly file: string;
+    constructor(file: string, cause: string);
+}
+export declare const CONFIG_FILE = "cotutor.json";
+export declare const USER_CONFIG: string;
+export declare const HOME_ROOT: string;
+export type RootSource = 'flag' | 'env' | 'cwd' | 'user-config' | 'home-single';
+export interface ResolvedRoot {
+    root: string;
+    source: RootSource;
+}
+export declare function expandPath(p: string, base: string): string;
+export declare function redactHome(value: string): string;
+export declare function redactDeep<T>(value: T): T;
+/** 读 JSON:不存在 → null;坏 → ConfigError */
+export declare function readJson(file: string): unknown | null;
+/** 从 dir 向上找 cotutor.json,找到返回目录 */
+export declare function findUp(dir: string): string | null;
+/** ~/cotutor/ 下带 cotutor.json 的子目录 */
+export declare function homeWorkspaces(homeRoot?: string): string[];
+export interface ResolveOptions {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    homeRoot?: string;
+}
+export declare function resolveRoot(override?: string, opts?: ResolveOptions): ResolvedRoot;
+export interface Workspace {
+    root: string;
+    source: RootSource;
+    config: CotutorConfig;
+    /** 角色 → 绝对路径;vault 侧角色相对 vault 解析,没配 vault 就相对 workspace 根 */
+    paths: Record<PathRole, string> & Record<string, string>;
+    dirs: {
+        agents: string;
+        ledger: string;
+        conversations: string;
+        claudeAgents: string;
+        qwenAgents: string;
+    };
+    files: {
+        config: string;
+        observations: string;
+        artifacts: string;
+        rulesClaude: string;
+        rulesQwen: string;
+    };
+}
+/** 校验 cotutor.json 的形状;失败 → ConfigError,信息是逐条修复指南 */
+export declare function parseConfig(raw: unknown, file: string): CotutorConfig;
+export declare function resolvePaths(root: string, paths: Record<string, string>): Workspace['paths'];
+export declare function assembleWorkspace(root: string, source: RootSource, config: CotutorConfig): Workspace;
+/** 定根 + 读配置 + 校验 + 展开角色。cotutor.json 缺失也是错(它是必需的)。 */
+export declare function loadWorkspace(override?: string, opts?: ResolveOptions): Workspace;
+/** --json / 启动日志里回报工作区(脱敏) */
+export declare function workspaceReport(ws: Workspace): Record<string, unknown>;

package/dist/cli/workspace.js

@@ -0,0 +1,199 @@
+/**
+ * 工作区解析:一孩一 workspace(`~/cotutor/<slug>/`,2026-09-08 拍板)。
+ * 解析链(定根):`--workspace <dir>` → 环境变量 COTUTOR_WORKSPACE → cwd 或其祖先有 cotutor.json
+ * (老师的 cwd 是 <ws>/agents/<name>/,从那里跑 doctor 也要找得到根)→ 用户配置
+ * ~/.config/cotutor/config.json 的 workspace → ~/cotutor/ 下**唯一**的一个孩子目录 → 都没有就报错附修复指南。
+ * 没有"cwd 兜底":cotutor.json 是必需的政策文件(老师表在里面),没有它什么都跑不了。
+ * 配置"在但解析不了"响亮报错,不静默走缺省(沿 drawtell 的教训)。
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { CotutorConfigSchema, PATH_ROLES, ROLE_DEFAULTS, explainIssues, } from "../schema/index.js";
+/** 用法错误:main 捕获后 exit 2,错误信息即修复指南。 */
+export class UsageError extends Error {
+}
+/** 配置文件损坏或形状不对:文件在,但用不了。 */
+export class ConfigError extends UsageError {
+    file;
+    constructor(file, cause) {
+        super(`配置文件用不了:${redactHome(file)}\n${cause}\n修好它;文件在 git 里就 git diff 看改动、git checkout 回退。cotutor doctor 可逐项体检。`);
+        this.file = file;
+    }
+}
+export const CONFIG_FILE = 'cotutor.json';
+export const USER_CONFIG = join(homedir(), '.config', 'cotutor', 'config.json');
+export const HOME_ROOT = join(homedir(), 'cotutor');
+export function expandPath(p, base) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    return isAbsolute(p) ? p : resolve(base, p);
+}
+export function redactHome(value) {
+    const home = homedir();
+    return home && value.startsWith(home) ? '$HOME' + value.slice(home.length) : value;
+}
+export function redactDeep(value) {
+    if (typeof value === 'string')
+        return redactHome(value);
+    if (Array.isArray(value))
+        return value.map(redactDeep);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v)]));
+    }
+    return value;
+}
+const isDir = (p) => {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const isFile = (p) => {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** 读 JSON:不存在 → null;坏 → ConfigError */
+export function readJson(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new ConfigError(file, `不是合法 JSON:${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** 从 dir 向上找 cotutor.json,找到返回目录 */
+export function findUp(dir) {
+    let cur = resolve(dir);
+    for (;;) {
+        if (isFile(join(cur, CONFIG_FILE)))
+            return cur;
+        const parent = dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+/** ~/cotutor/ 下带 cotutor.json 的子目录 */
+export function homeWorkspaces(homeRoot = HOME_ROOT) {
+    try {
+        return readdirSync(homeRoot)
+            .map((d) => join(homeRoot, d))
+            .filter((p) => isDir(p) && isFile(join(p, CONFIG_FILE)))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export function resolveRoot(override, opts = {}) {
+    const env = opts.env ?? process.env;
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    if (override !== undefined) {
+        const root = expandPath(override, cwd);
+        if (!isDir(root)) {
+            throw new UsageError(`--workspace 指向的目录不存在:${redactHome(root)}(由 '${redactHome(override)}' 解析)。先 cotutor init <slug>(缺省建在 ~/cotutor/<slug>/),或改指向已有的 workspace 根。`);
+        }
+        return { root, source: 'flag' };
+    }
+    if (env.COTUTOR_WORKSPACE) {
+        const root = expandPath(env.COTUTOR_WORKSPACE, cwd);
+        if (!isDir(root))
+            throw new UsageError(`COTUTOR_WORKSPACE 指向的目录不存在:${redactHome(root)}。改环境变量,或先 cotutor init。`);
+        return { root, source: 'env' };
+    }
+    const up = findUp(cwd);
+    if (up)
+        return { root: up, source: 'cwd' };
+    const user = readJson(USER_CONFIG);
+    if (user && typeof user.workspace === 'string' && user.workspace) {
+        return { root: expandPath(user.workspace, cwd), source: 'user-config' };
+    }
+    const homes = homeWorkspaces(opts.homeRoot);
+    if (homes.length === 1)
+        return { root: homes[0], source: 'home-single' };
+    if (homes.length > 1) {
+        throw new UsageError(`~/cotutor/ 下有 ${homes.length} 个 workspace(${homes.map((h) => redactHome(h)).join('、')}),不知道要哪个。` +
+            '用 --workspace <dir> 或 COTUTOR_WORKSPACE 指定,或在 workspace 目录里跑;一 workspace 一进程。');
+    }
+    throw new UsageError('找不到 workspace:没有 --workspace、COTUTOR_WORKSPACE、cwd 里的 cotutor.json、用户配置,~/cotutor/ 下也没有。先 cotutor init <slug>。');
+}
+/** 校验 cotutor.json 的形状;失败 → ConfigError,信息是逐条修复指南 */
+export function parseConfig(raw, file) {
+    const r = CotutorConfigSchema.safeParse(raw);
+    if (r.success)
+        return r.data;
+    throw new ConfigError(file, explainIssues(r.error.issues).map((l) => `  - ${l}`).join('\n'));
+}
+export function resolvePaths(root, paths) {
+    const vault = expandPath(paths.vault ?? ROLE_DEFAULTS.vault, root);
+    const out = { vault };
+    for (const role of PATH_ROLES) {
+        if (role === 'vault')
+            continue;
+        out[role] = expandPath(paths[role] ?? ROLE_DEFAULTS[role], vault);
+    }
+    for (const [role, value] of Object.entries(paths))
+        if (!(role in out))
+            out[role] = expandPath(value, vault);
+    return out;
+}
+export function assembleWorkspace(root, source, config) {
+    return {
+        root,
+        source,
+        config,
+        paths: resolvePaths(root, config.paths),
+        dirs: {
+            agents: join(root, 'agents'),
+            ledger: join(root, 'ledger'),
+            conversations: join(root, 'conversations'),
+            claudeAgents: join(root, '.claude', 'agents'),
+            qwenAgents: join(root, '.qwen', 'agents'),
+        },
+        files: {
+            config: join(root, CONFIG_FILE),
+            observations: join(root, 'ledger', 'observations.jsonl'),
+            artifacts: join(root, 'ledger', 'artifacts.jsonl'),
+            rulesClaude: join(root, 'CLAUDE.md'),
+            rulesQwen: join(root, 'QWEN.md'),
+        },
+    };
+}
+/** 定根 + 读配置 + 校验 + 展开角色。cotutor.json 缺失也是错(它是必需的)。 */
+export function loadWorkspace(override, opts = {}) {
+    const { root, source } = resolveRoot(override, opts);
+    const file = join(root, CONFIG_FILE);
+    const raw = readJson(file);
+    if (raw === null)
+        throw new ConfigError(file, `不存在。cotutor init <slug> --dir ${redactHome(root)} 可生成模板(已有文件不动)。`);
+    return assembleWorkspace(root, source, parseConfig(raw, file));
+}
+/** --json / 启动日志里回报工作区(脱敏) */
+export function workspaceReport(ws) {
+    return redactDeep({
+        workspace: ws.root,
+        workspaceSource: ws.source,
+        kid: ws.config.kid.slug,
+        title: ws.config.title,
+        port: ws.config.server.port,
+        vault: ws.paths.vault,
+        teachers: Object.keys(ws.config.teachers),
+        agent: ws.config.agents.default,
+    });
+}

package/dist/lib/agent-file.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 老师定义文件(.claude/agents/<name>.md 同一份链到 .qwen/agents/):YAML frontmatter + 正文即系统提示。
+ * 这里只认平铺的 `key: value` frontmatter(两个 CLI 的公共子集:name / description / maxTurns / permissionMode / memory);
+ * 正文给没有 --agent 的 CLI 经 {agentBody} 塞进 --append-system-prompt。
+ */
+export interface AgentFile {
+    frontmatter: Record<string, string>;
+    body: string;
+}
+export declare function parseAgentFile(text: string): AgentFile;

package/dist/lib/agent-file.js

@@ -0,0 +1,16 @@
+export function parseAgentFile(text) {
+    const open = /^---[^\S\n]*\n/.exec(text);
+    if (!open)
+        return { frontmatter: {}, body: text.trim() };
+    const rest = text.slice(open[0].length);
+    const end = /\n---[^\S\n]*(\n|$)/.exec(rest);
+    if (!end)
+        return { frontmatter: {}, body: text.trim() };
+    const frontmatter = {};
+    for (const raw of rest.slice(0, end.index).split('\n')) {
+        const m = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(raw);
+        if (m)
+            frontmatter[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, '$2');
+    }
+    return { frontmatter, body: rest.slice(end.index + end[0].length).trim() };
+}

package/dist/lib/context-pack.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 上下文包序列化(《cotutor契约草案.md》§2):固定 YAML 块 + `---` + 消息原文。
+ * 手写 YAML 子集:标量能裸写就裸写,其余 JSON 双引号(合法 YAML);空的 plan / recent 不写。
+ */
+import { type ContextPack } from '../schema/index.ts';
+export declare function yamlScalar(v: string | number | boolean): string;
+export declare function renderContextPack(pack: ContextPack): string;
+/** 按政策截 plan / recent,再拼成「YAML 块 --- 消息」 */
+export declare function buildContextPack(pack: ContextPack, message: string, limits: {
+    recent: number;
+    planLines: number;
+}): string;

package/dist/lib/context-pack.js

@@ -0,0 +1,46 @@
+/**
+ * 上下文包序列化(《cotutor契约草案.md》§2):固定 YAML 块 + `---` + 消息原文。
+ * 手写 YAML 子集:标量能裸写就裸写,其余 JSON 双引号(合法 YAML);空的 plan / recent 不写。
+ */
+import { ContextPackSchema } from "../schema/index.js";
+const BARE = /^[A-Za-z0-9_][A-Za-z0-9_\-.:T]*$/;
+export function yamlScalar(v) {
+    if (typeof v !== 'string')
+        return String(v);
+    return BARE.test(v) && !/^(true|false|null|~|yes|no)$/i.test(v) ? v : JSON.stringify(v);
+}
+export function renderContextPack(pack) {
+    const p = ContextPackSchema.parse(pack);
+    const out = ['cotutor:', `  from: ${p.from}`, `  at: ${yamlScalar(p.at)}`];
+    if (p.slot)
+        out.push(`  slot: ${yamlScalar(p.slot)}`);
+    if (p.focus && (p.focus.artifact || p.focus.step !== undefined || p.focus.circled?.length)) {
+        out.push('  focus:');
+        if (p.focus.artifact)
+            out.push(`    artifact: ${yamlScalar(p.focus.artifact)}`);
+        if (p.focus.step !== undefined)
+            out.push(`    step: ${p.focus.step}`);
+        if (p.focus.circled?.length)
+            out.push(`    circled: [${p.focus.circled.map(yamlScalar).join(', ')}]`);
+    }
+    if (p.plan.length) {
+        out.push('  plan:');
+        for (const l of p.plan)
+            out.push(`    - ${yamlScalar(l)}`);
+    }
+    if (p.recent.length) {
+        out.push('  recent:');
+        for (const r of p.recent)
+            out.push(`    - ${yamlScalar(`${r.date} ${r.claim}`)}`);
+    }
+    return out.join('\n');
+}
+/** 按政策截 plan / recent,再拼成「YAML 块 --- 消息」 */
+export function buildContextPack(pack, message, limits) {
+    const trimmed = {
+        ...pack,
+        plan: (pack.plan ?? []).slice(0, limits.planLines),
+        recent: (pack.recent ?? []).slice(-limits.recent),
+    };
+    return `${renderContextPack(trimmed)}\n---\n${message.trim()}\n`;
+}

package/dist/lib/conversation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 会话索引的纯函数:日期与 job 命名、空索引、把一次运行的结果并进索引(不改旧对象)。
+ */
+import { type ConversationIndex, type ConversationMessage } from '../schema/index.ts';
+import type { KidView } from './kid-view.ts';
+import type { Transcript } from './transcript.ts';
+/** 本地日期 YYYY-MM-DD(会话按本地日切) */
+export declare function localDate(d: Date): string;
+/** 本地时间到分钟 YYYY-MM-DDTHH:MM(上下文包的 at) */
+export declare function localMinute(d: Date): string;
+/** HHMM-<序号>,同一天内不重复 */
+export declare function jobId(d: Date, seq: number): string;
+export declare function emptyIndex(teacher: string, date: string): ConversationIndex;
+export interface ConversationFiles {
+    index: string;
+    log: (job: string) => string;
+    err: (job: string) => string;
+}
+/** conversations/<teacher>/<date>.json 与 <date>.<job>.log / .err.log */
+export declare function conversationFiles(conversationsDir: string, teacher: string, date: string): ConversationFiles;
+export declare function addMessage(index: ConversationIndex, msg: ConversationMessage): ConversationIndex;
+/** 一次运行收尾:写 result / cost / kidText / artifacts,首次拿到 session 就记下 */
+export declare function applyRun(index: ConversationIndex, job: string, run: {
+    transcript: Transcript;
+    kidView: KidView;
+    agent: string;
+    artifacts?: string[];
+}): ConversationIndex;