cotutor 0.1.0

package/dist/schema/config.d.ts

@@ -0,0 +1,182 @@
+/**
+ * cotutor.json:每个 workspace 一份,一孩一 workspace。承接 drawtell.json 的做法——
+ * `paths` 角色映射 + `agents` 的 {run, resume} 命令模板——再加老师表与政策。
+ * 字段归属铁律:老师的 .md 文件里只有 name / description / maxTurns / permissionMode / memory + 正文;
+ * 人设(display / avatar / voice)、政策、开关全在这里。助教团页只改本文件,永不改链进来的定义文件。
+ */
+import { z } from 'zod';
+/** 回复形式阶梯(《cotutor产品规划.md》):L0 确定性资源 / L1 口答 / L2 快卡 / L3 补讲 / L4 整包 */
+export declare const REPLY_FORMS: readonly ["L0", "L1", "L2", "L3", "L4"];
+export type ReplyForm = (typeof REPLY_FORMS)[number];
+export declare const PolicySchema: z.ZodObject<{
+    replyMaxChars: z.ZodNumber;
+    dailyMessages: z.ZodNumber;
+    dailyRegen: z.ZodNumber;
+    reviewGate: z.ZodBoolean;
+    forms: z.ZodArray<z.ZodEnum<{
+        L0: "L0";
+        L1: "L1";
+        L2: "L2";
+        L3: "L3";
+        L4: "L4";
+    }>>;
+    contextPack: z.ZodObject<{
+        recent: z.ZodNumber;
+        planLines: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Policy = z.infer<typeof PolicySchema>;
+/** 政策补丁:老师条目与 policyDefaults 都是补丁,逐层盖在 POLICY_DEFAULTS 上 */
+export declare const PolicyPatchSchema: z.ZodObject<{
+    replyMaxChars: z.ZodOptional<z.ZodNumber>;
+    dailyMessages: z.ZodOptional<z.ZodNumber>;
+    dailyRegen: z.ZodOptional<z.ZodNumber>;
+    reviewGate: z.ZodOptional<z.ZodBoolean>;
+    forms: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        L0: "L0";
+        L1: "L1";
+        L2: "L2";
+        L3: "L3";
+        L4: "L4";
+    }>>>;
+    contextPack: z.ZodOptional<z.ZodObject<{
+        recent: z.ZodOptional<z.ZodNumber>;
+        planLines: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PolicyPatch = z.infer<typeof PolicyPatchSchema>;
+/** 2026-09-08 拍板的缺省:60 字、30 条/日、3 次重生、验收关、上下文包各 10 */
+export declare const POLICY_DEFAULTS: Policy;
+/** agent 名:与 .claude/agents/<name>.md 的 frontmatter name 一致,小写字母数字连字符 */
+export declare const AGENT_NAME_RE: RegExp;
+export declare const TeacherSchema: z.ZodObject<{
+    display: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    avatar: z.ZodOptional<z.ZodString>;
+    voice: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    hidden: z.ZodDefault<z.ZodBoolean>;
+    policy: z.ZodOptional<z.ZodObject<{
+        replyMaxChars: z.ZodOptional<z.ZodNumber>;
+        dailyMessages: z.ZodOptional<z.ZodNumber>;
+        dailyRegen: z.ZodOptional<z.ZodNumber>;
+        reviewGate: z.ZodOptional<z.ZodBoolean>;
+        forms: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            L0: "L0";
+            L1: "L1";
+            L2: "L2";
+            L3: "L3";
+            L4: "L4";
+        }>>>;
+        contextPack: z.ZodOptional<z.ZodObject<{
+            recent: z.ZodOptional<z.ZodNumber>;
+            planLines: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Teacher = z.infer<typeof TeacherSchema>;
+/**
+ * 运行时预设:一个 CLI 一组 {run, resume} 命令模板。占位符:
+ * {agent} 老师名 / {agentBody} 老师文件正文(给没有 --agent 的 CLI 塞系统提示)/ {prompt} 消息 / {session} 会话 id。
+ * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换预设。
+ */
+export declare const AgentPresetSchema: z.ZodObject<{
+    run: z.ZodArray<z.ZodString>;
+    resume: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type AgentPreset = z.infer<typeof AgentPresetSchema>;
+export declare const AgentsSchema: z.ZodObject<{
+    default: z.ZodString;
+}, z.core.$catchall<z.ZodObject<{
+    run: z.ZodArray<z.ZodString>;
+    resume: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>>;
+/** paths 里 CLI 认识的角色;其余角色原样保留给应用层。vault 侧角色相对 vault 解析,没配 vault 就相对 workspace 根 */
+export declare const PATH_ROLES: readonly ["vault", "photos", "diary", "plans", "profile", "timetable"];
+export type PathRole = (typeof PATH_ROLES)[number];
+export declare const ROLE_DEFAULTS: Record<PathRole, string>;
+export declare const CotutorConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    title: z.ZodDefault<z.ZodString>;
+    kid: z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        grade: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    server: z.ZodDefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    paths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    policyDefaults: z.ZodDefault<z.ZodObject<{
+        replyMaxChars: z.ZodOptional<z.ZodNumber>;
+        dailyMessages: z.ZodOptional<z.ZodNumber>;
+        dailyRegen: z.ZodOptional<z.ZodNumber>;
+        reviewGate: z.ZodOptional<z.ZodBoolean>;
+        forms: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            L0: "L0";
+            L1: "L1";
+            L2: "L2";
+            L3: "L3";
+            L4: "L4";
+        }>>>;
+        contextPack: z.ZodOptional<z.ZodObject<{
+            recent: z.ZodOptional<z.ZodNumber>;
+            planLines: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    teachers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        display: z.ZodString;
+        subject: z.ZodOptional<z.ZodString>;
+        avatar: z.ZodOptional<z.ZodString>;
+        voice: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        hidden: z.ZodDefault<z.ZodBoolean>;
+        policy: z.ZodOptional<z.ZodObject<{
+            replyMaxChars: z.ZodOptional<z.ZodNumber>;
+            dailyMessages: z.ZodOptional<z.ZodNumber>;
+            dailyRegen: z.ZodOptional<z.ZodNumber>;
+            reviewGate: z.ZodOptional<z.ZodBoolean>;
+            forms: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                L0: "L0";
+                L1: "L1";
+                L2: "L2";
+                L3: "L3";
+                L4: "L4";
+            }>>>;
+            contextPack: z.ZodOptional<z.ZodObject<{
+                recent: z.ZodOptional<z.ZodNumber>;
+                planLines: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    agents: z.ZodObject<{
+        default: z.ZodString;
+    }, z.core.$catchall<z.ZodObject<{
+        run: z.ZodArray<z.ZodString>;
+        resume: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CotutorConfig = z.infer<typeof CotutorConfigSchema>;
+/** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← teachers[name].policy */
+export declare function resolvePolicy(config: CotutorConfig, teacher: string): Policy;
+export interface TeacherView {
+    name: string;
+    display: string;
+    subject?: string;
+    avatar?: string;
+    voice?: string;
+    enabled: boolean;
+    hidden: boolean;
+    policy: Policy;
+}
+/** 老师列表(带有效政策);kidOnly = 只要孩子端能看到的(enabled 且不 hidden) */
+export declare function listTeachers(config: CotutorConfig, opts?: {
+    kidOnly?: boolean;
+}): TeacherView[];
+/** 预设模板填占位符;{agentBody} 只在给了正文时替换,否则原样留着(doctor 会报) */
+export declare function fillPreset(argv: readonly string[], vars: {
+    agent: string;
+    prompt: string;
+    session?: string;
+    agentBody?: string;
+}): string[];

package/dist/schema/config.js

@@ -0,0 +1,144 @@
+/**
+ * cotutor.json:每个 workspace 一份,一孩一 workspace。承接 drawtell.json 的做法——
+ * `paths` 角色映射 + `agents` 的 {run, resume} 命令模板——再加老师表与政策。
+ * 字段归属铁律:老师的 .md 文件里只有 name / description / maxTurns / permissionMode / memory + 正文;
+ * 人设(display / avatar / voice)、政策、开关全在这里。助教团页只改本文件,永不改链进来的定义文件。
+ */
+import { z } from 'zod';
+/** 回复形式阶梯(《cotutor产品规划.md》):L0 确定性资源 / L1 口答 / L2 快卡 / L3 补讲 / L4 整包 */
+export const REPLY_FORMS = ['L0', 'L1', 'L2', 'L3', 'L4'];
+export const PolicySchema = z.object({
+    /** 老师单条回复给孩子看的字数上限;超出截断并改走 L3(《cotutor契约草案.md》§4) */
+    replyMaxChars: z.number().int().positive(),
+    /** 每孩每日消息上限;超限老师头像灰掉 */
+    dailyMessages: z.number().int().nonnegative(),
+    /** 每日重生上限 */
+    dailyRegen: z.number().int().nonnegative(),
+    /** 验收开关:false = 产物直接给孩子(缺省);true = 先经家长验收 */
+    reviewGate: z.boolean(),
+    /** 这位老师可用的回复形式 */
+    forms: z.array(z.enum(REPLY_FORMS)),
+    /** 上下文包的两个数:最近观察条数、计划行数 */
+    contextPack: z.object({ recent: z.number().int().nonnegative(), planLines: z.number().int().nonnegative() }),
+});
+/** 政策补丁:老师条目与 policyDefaults 都是补丁,逐层盖在 POLICY_DEFAULTS 上 */
+export const PolicyPatchSchema = z.object({
+    replyMaxChars: PolicySchema.shape.replyMaxChars.optional(),
+    dailyMessages: PolicySchema.shape.dailyMessages.optional(),
+    dailyRegen: PolicySchema.shape.dailyRegen.optional(),
+    reviewGate: PolicySchema.shape.reviewGate.optional(),
+    forms: PolicySchema.shape.forms.optional(),
+    contextPack: z.object({ recent: z.number().int().nonnegative().optional(), planLines: z.number().int().nonnegative().optional() }).optional(),
+});
+/** 2026-09-08 拍板的缺省:60 字、30 条/日、3 次重生、验收关、上下文包各 10 */
+export const POLICY_DEFAULTS = {
+    replyMaxChars: 60,
+    dailyMessages: 30,
+    dailyRegen: 3,
+    reviewGate: false,
+    forms: ['L0', 'L1', 'L3', 'L4'],
+    contextPack: { recent: 10, planLines: 10 },
+};
+/** agent 名:与 .claude/agents/<name>.md 的 frontmatter name 一致,小写字母数字连字符 */
+export const AGENT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+export const TeacherSchema = z.object({
+    /** 显示名(孩子端头像下的字、计划文件的 H2 标题) */
+    display: z.string().min(1),
+    subject: z.string().optional(),
+    /** 头像:一个 emoji 或图片相对路径 */
+    avatar: z.string().optional(),
+    /** voxtell 音色 id(2026-09-08 拍板);没有 = 用 voxtell 缺省 */
+    voice: z.string().optional(),
+    enabled: z.boolean().default(true),
+    /** 孩子端不露(规划老师、记账员这类) */
+    hidden: z.boolean().default(false),
+    policy: PolicyPatchSchema.optional(),
+});
+/**
+ * 运行时预设:一个 CLI 一组 {run, resume} 命令模板。占位符:
+ * {agent} 老师名 / {agentBody} 老师文件正文(给没有 --agent 的 CLI 塞系统提示)/ {prompt} 消息 / {session} 会话 id。
+ * 政策旋钮(预算、轮数、模型)写进模板,换 agent 只换预设。
+ */
+export const AgentPresetSchema = z.object({ run: z.array(z.string()).min(1), resume: z.array(z.string()).min(1) });
+export const AgentsSchema = z.object({ default: z.string().min(1) }).catchall(AgentPresetSchema);
+/** paths 里 CLI 认识的角色;其余角色原样保留给应用层。vault 侧角色相对 vault 解析,没配 vault 就相对 workspace 根 */
+export const PATH_ROLES = ['vault', 'photos', 'diary', 'plans', 'profile', 'timetable'];
+export const ROLE_DEFAULTS = {
+    vault: '.',
+    photos: 'photos',
+    diary: 'diary',
+    plans: 'plans',
+    profile: 'profile.md',
+    timetable: 'timetable.md',
+};
+export const CotutorConfigSchema = z
+    .object({
+    version: z.literal(1),
+    /** 孩子端标题,无品牌 */
+    title: z.string().default('cotutor'),
+    kid: z.object({
+        /** 短名,进路径 ~/cotutor/<slug>/,不是真名 */
+        slug: z.string().regex(AGENT_NAME_RE),
+        name: z.string().optional(),
+        grade: z.string().optional(),
+    }),
+    server: z.object({ port: z.number().int().min(1).max(65535).default(5180) }).default({ port: 5180 }),
+    paths: z.record(z.string(), z.string()).default({}),
+    policyDefaults: PolicyPatchSchema.default({}),
+    teachers: z.record(z.string().regex(AGENT_NAME_RE), TeacherSchema).default({}),
+    agents: AgentsSchema,
+})
+    .superRefine((c, ctx) => {
+    if (!(c.agents.default in c.agents) || c.agents.default === 'default') {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['agents', 'default'],
+            message: `预设 "${c.agents.default}" 不存在;agents 里要有同名的 {run, resume}`,
+        });
+    }
+});
+/** 老师的有效政策 = POLICY_DEFAULTS ← policyDefaults ← teachers[name].policy */
+export function resolvePolicy(config, teacher) {
+    const layers = [config.policyDefaults, config.teachers[teacher]?.policy ?? {}];
+    const out = { ...POLICY_DEFAULTS, contextPack: { ...POLICY_DEFAULTS.contextPack } };
+    for (const p of layers) {
+        if (p.replyMaxChars !== undefined)
+            out.replyMaxChars = p.replyMaxChars;
+        if (p.dailyMessages !== undefined)
+            out.dailyMessages = p.dailyMessages;
+        if (p.dailyRegen !== undefined)
+            out.dailyRegen = p.dailyRegen;
+        if (p.reviewGate !== undefined)
+            out.reviewGate = p.reviewGate;
+        if (p.forms !== undefined)
+            out.forms = [...p.forms];
+        if (p.contextPack?.recent !== undefined)
+            out.contextPack.recent = p.contextPack.recent;
+        if (p.contextPack?.planLines !== undefined)
+            out.contextPack.planLines = p.contextPack.planLines;
+    }
+    return out;
+}
+/** 老师列表(带有效政策);kidOnly = 只要孩子端能看到的(enabled 且不 hidden) */
+export function listTeachers(config, opts = {}) {
+    return Object.entries(config.teachers)
+        .filter(([, t]) => !opts.kidOnly || (t.enabled && !t.hidden))
+        .map(([name, t]) => ({
+        name,
+        display: t.display,
+        subject: t.subject,
+        avatar: t.avatar,
+        voice: t.voice,
+        enabled: t.enabled,
+        hidden: t.hidden,
+        policy: resolvePolicy(config, name),
+    }));
+}
+/** 预设模板填占位符;{agentBody} 只在给了正文时替换,否则原样留着(doctor 会报) */
+export function fillPreset(argv, vars) {
+    return argv.map((a) => a
+        .replaceAll('{agent}', vars.agent)
+        .replaceAll('{prompt}', vars.prompt)
+        .replaceAll('{session}', vars.session ?? '')
+        .replaceAll('{agentBody}', vars.agentBody ?? '{agentBody}'));
+}

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

@@ -0,0 +1,33 @@
+/**
+ * 上下文包:应用在每条消息前拼的固定 YAML 块(《cotutor契约草案.md》§2)。老师不用自己找上下文。
+ * 孩子由 workspace 决定,不进包。
+ */
+import { z } from 'zod';
+export declare const MESSAGE_FROM: readonly ["kid", "parent", "system"];
+export type MessageFrom = (typeof MESSAGE_FROM)[number];
+export declare const FocusSchema: z.ZodObject<{
+    artifact: z.ZodOptional<z.ZodString>;
+    step: z.ZodOptional<z.ZodNumber>;
+    circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Focus = z.infer<typeof FocusSchema>;
+export declare const ContextPackSchema: z.ZodObject<{
+    from: z.ZodEnum<{
+        kid: "kid";
+        parent: "parent";
+        system: "system";
+    }>;
+    at: z.ZodString;
+    slot: z.ZodOptional<z.ZodString>;
+    focus: z.ZodOptional<z.ZodObject<{
+        artifact: z.ZodOptional<z.ZodString>;
+        step: z.ZodOptional<z.ZodNumber>;
+        circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    plan: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    recent: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        claim: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ContextPack = z.infer<typeof ContextPackSchema>;

package/dist/schema/context-pack.js

@@ -0,0 +1,26 @@
+/**
+ * 上下文包:应用在每条消息前拼的固定 YAML 块(《cotutor契约草案.md》§2)。老师不用自己找上下文。
+ * 孩子由 workspace 决定,不进包。
+ */
+import { z } from 'zod';
+export const MESSAGE_FROM = ['kid', 'parent', 'system'];
+export const FocusSchema = z.object({
+    /** 当前对象(产物 id) */
+    artifact: z.string().optional(),
+    /** 正在看的 step */
+    step: z.number().int().nonnegative().optional(),
+    /** 圈了什么 */
+    circled: z.array(z.string()).optional(),
+});
+export const ContextPackSchema = z.object({
+    from: z.enum(MESSAGE_FROM),
+    /** 本地时间,分钟精度,如 2026-09-08T16:20 */
+    at: z.string().min(1),
+    /** 课程表命中的时段,如「数学 16:00-17:00」 */
+    slot: z.string().optional(),
+    focus: FocusSchema.optional(),
+    /** 本周计划里与本老师相关的行(已按 planLines 截) */
+    plan: z.array(z.string()).default([]),
+    /** 最近 N 条本学科观察(已按 recent 截) */
+    recent: z.array(z.object({ date: z.string(), claim: z.string() })).default([]),
+});

package/dist/schema/conversation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 会话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
+ * 索引里的 kidText / artifacts 是精简视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
+ */
+import { z } from 'zod';
+export declare const DATE_RE: RegExp;
+export declare const ConversationMessageSchema: z.ZodObject<{
+    job: z.ZodString;
+    at: z.ZodString;
+    from: z.ZodEnum<{
+        kid: "kid";
+        parent: "parent";
+        system: "system";
+    }>;
+    text: z.ZodString;
+    focus: z.ZodOptional<z.ZodObject<{
+        artifact: z.ZodOptional<z.ZodString>;
+        step: z.ZodOptional<z.ZodNumber>;
+        circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    result: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        running: "running";
+        ok: "ok";
+    }>>;
+    costUsd: z.ZodOptional<z.ZodNumber>;
+    kidText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ConversationMessage = z.infer<typeof ConversationMessageSchema>;
+export declare const ConversationIndexSchema: z.ZodObject<{
+    teacher: z.ZodString;
+    date: z.ZodString;
+    session: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        agent: z.ZodString;
+    }, z.core.$strip>>>;
+    messages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        job: z.ZodString;
+        at: z.ZodString;
+        from: z.ZodEnum<{
+            kid: "kid";
+            parent: "parent";
+            system: "system";
+        }>;
+        text: z.ZodString;
+        focus: z.ZodOptional<z.ZodObject<{
+            artifact: z.ZodOptional<z.ZodString>;
+            step: z.ZodOptional<z.ZodNumber>;
+            circled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        result: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            running: "running";
+            ok: "ok";
+        }>>;
+        costUsd: z.ZodOptional<z.ZodNumber>;
+        kidText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    costUsd: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type ConversationIndex = z.infer<typeof ConversationIndexSchema>;

package/dist/schema/conversation.js

@@ -0,0 +1,30 @@
+/**
+ * 会话索引:一老师一天一份(《cotutor契约草案.md》§3)。每条消息 = 一次 -p 运行 = 一份 NDJSON 转录;
+ * 索引里的 kidText / artifacts 是精简视图的物化结果,孩子端不解析日志。跨天自动新开(2026-09-08 拍板)。
+ */
+import { z } from 'zod';
+import { FocusSchema, MESSAGE_FROM } from "./context-pack.js";
+export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export const ConversationMessageSchema = z.object({
+    /** 任务 id,同时是转录文件名的一段:<date>.<job>.log */
+    job: z.string().min(1),
+    at: z.string().min(1),
+    from: z.enum(MESSAGE_FROM),
+    /** 消息原文(不含上下文包) */
+    text: z.string(),
+    focus: FocusSchema.optional(),
+    result: z.enum(['running', 'ok', 'error']).default('running'),
+    costUsd: z.number().optional(),
+    /** 孩子视图文本;null = 这次运行没有给孩子的话(出错或空) */
+    kidText: z.string().nullable().optional(),
+    /** 本次运行新增的产物 id */
+    artifacts: z.array(z.string()).default([]),
+});
+export const ConversationIndexSchema = z.object({
+    teacher: z.string().min(1),
+    date: z.string().regex(DATE_RE),
+    /** 当天会话;首条消息跑完后写入,之后每条 --resume 它 */
+    session: z.object({ id: z.string().min(1), agent: z.string().min(1) }).nullable().default(null),
+    messages: z.array(ConversationMessageSchema).default([]),
+    costUsd: z.number().default(0),
+});

package/dist/schema/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * cotutor 契约(类型即文档)。每个文件一个契约面:
+ *  config        cotutor.json(老师表、政策、运行时预设、paths 角色)
+ *  context-pack  每条消息前的上下文包
+ *  conversation  一老师一天一份的会话索引
+ *  ledger        观察与产物两本追加式账本
+ *  sections      最终文本里的「待裁量」「转交」段
+ *  plan          计划文件
+ * 运行时校验用 zod,失败信息经 explainIssues 变成修复指南。
+ */
+export * from './issues.ts';
+export * from './config.ts';
+export * from './context-pack.ts';
+export * from './conversation.ts';
+export * from './ledger.ts';
+export * from './sections.ts';
+export * from './plan.ts';

package/dist/schema/index.js

@@ -0,0 +1,17 @@
+/**
+ * cotutor 契约(类型即文档)。每个文件一个契约面:
+ *  config        cotutor.json(老师表、政策、运行时预设、paths 角色)
+ *  context-pack  每条消息前的上下文包
+ *  conversation  一老师一天一份的会话索引
+ *  ledger        观察与产物两本追加式账本
+ *  sections      最终文本里的「待裁量」「转交」段
+ *  plan          计划文件
+ * 运行时校验用 zod,失败信息经 explainIssues 变成修复指南。
+ */
+export * from "./issues.js";
+export * from "./config.js";
+export * from "./context-pack.js";
+export * from "./conversation.js";
+export * from "./ledger.js";
+export * from "./sections.js";
+export * from "./plan.js";

package/dist/schema/issues.d.ts

@@ -0,0 +1,6 @@
+/**
+ * zod 问题 → 修复指南行。契约校验失败时给人和 agent 看的不是 zod 的英文 issue,
+ * 是「哪个字段、该是什么、现在是什么」——错误信息即修复指南(仓库老规矩)。
+ */
+import type { z } from 'zod';
+export declare function explainIssues(issues: z.core.$ZodIssue[]): string[];

package/dist/schema/issues.js

@@ -0,0 +1,37 @@
+const EXPECT = {
+    string: '字符串',
+    number: '数字',
+    boolean: '布尔值(true/false)',
+    object: '对象',
+    array: '数组',
+    int: '整数',
+};
+export function explainIssues(issues) {
+    return issues.map((i) => {
+        const path = i.path.length ? i.path.map(String).join('.') : '(根)';
+        switch (i.code) {
+            case 'invalid_type':
+                return `${path}:应为${EXPECT[i.expected] ?? i.expected}${i.input === undefined ? ',现在缺失' : ''}`;
+            case 'invalid_value':
+                return `${path}:只能是 ${i.values.map((v) => JSON.stringify(v)).join(' / ')}`;
+            case 'too_small':
+                return `${path}:${i.origin === 'string' ? '不能为空' : `不能小于 ${i.minimum}`}`;
+            case 'too_big':
+                return `${path}:不能大于 ${i.maximum}`;
+            case 'invalid_format':
+                return `${path}:格式不对(${i.format}${i.pattern ? ` ${i.pattern}` : ''})`;
+            case 'unrecognized_keys':
+                return `${path}:不认识的字段 ${i.keys.join(', ')}`;
+            case 'invalid_union': {
+                // 挑问题最少的那个分支解释(如观察行:缺 claim 比缺 retracted+by 更接近)
+                const branches = i.errors ?? [];
+                const best = branches.slice().sort((a, b) => a.length - b.length)[0];
+                if (best?.length)
+                    return explainIssues(best.map((e) => ({ ...e, path: [...i.path, ...e.path] }))).join(';');
+                return `${path}:不符合任何一种允许的形状`;
+            }
+            default:
+                return `${path}:${i.message}`;
+        }
+    });
+}

package/dist/schema/ledger.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 公共账本(《cotutor契约草案.md》§5):observations.jsonl 与 artifacts.jsonl,追加式、一行一条、id 唯一;
+ * 改状态追加新行,同 id 后者为准,不改历史。retracted 用追加行(2026-09-08 拍板)。
+ */
+import { z } from 'zod';
+export declare const EvidenceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    conversation: z.ZodString;
+    job: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    artifact: z.ZodString;
+}, z.core.$strip>]>;
+export type Evidence = z.infer<typeof EvidenceSchema>;
+/** 完整观察行 */
+export declare const ObservationSchema: z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    author: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    topic: z.ZodOptional<z.ZodString>;
+    claim: z.ZodString;
+    evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        conversation: z.ZodString;
+        job: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        artifact: z.ZodString;
+    }, z.core.$strip>]>>;
+    retracted: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Observation = z.infer<typeof ObservationSchema>;
+/** 纠错行:只带 id + retracted + 谁 + 何时 */
+export declare const ObservationRetractSchema: z.ZodObject<{
+    id: z.ZodString;
+    retracted: z.ZodLiteral<true>;
+    by: z.ZodString;
+    date: z.ZodString;
+}, z.core.$strip>;
+export type ObservationRetract = z.infer<typeof ObservationRetractSchema>;
+export declare const ObservationLineSchema: z.ZodUnion<readonly [z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    author: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    topic: z.ZodOptional<z.ZodString>;
+    claim: z.ZodString;
+    evidence: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        conversation: z.ZodString;
+        job: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        artifact: z.ZodString;
+    }, z.core.$strip>]>>;
+    retracted: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    retracted: z.ZodLiteral<true>;
+    by: z.ZodString;
+    date: z.ZodString;
+}, z.core.$strip>]>;
+export type ObservationLine = z.infer<typeof ObservationLineSchema>;
+export declare const ARTIFACT_KINDS: readonly ["课包", "补讲", "批改", "计划", "其它"];
+export declare const ARTIFACT_STATUS: readonly ["draft", "ready", "accepted", "retired"];
+export type ArtifactStatus = (typeof ARTIFACT_STATUS)[number];
+/** 产物事件行:首行要带 kind / by / path,后续行只带变化的字段 */
+export declare const ArtifactEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        课包: "课包";
+        补讲: "补讲";
+        批改: "批改";
+        计划: "计划";
+        其它: "其它";
+    }>>;
+    by: z.ZodOptional<z.ZodString>;
+    at: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        ready: "ready";
+        accepted: "accepted";
+        retired: "retired";
+    }>>;
+    path: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        conversation: z.ZodString;
+        job: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    hash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ArtifactEvent = z.infer<typeof ArtifactEventSchema>;
+/** 折叠后的产物 */
+export interface Artifact {
+    id: string;
+    kind: (typeof ARTIFACT_KINDS)[number];
+    by: string;
+    at: string;
+    status: ArtifactStatus;
+    path?: string;
+    source?: ArtifactEvent['source'];
+    hash?: string;
+    /** 最后一次事件时间 */
+    updatedAt: string;
+}