cotutor 0.1.0

package/dist/schema/ledger.js

@@ -0,0 +1,44 @@
+/**
+ * 公共账本(《cotutor契约草案.md》§5):observations.jsonl 与 artifacts.jsonl,追加式、一行一条、id 唯一;
+ * 改状态追加新行,同 id 后者为准,不改历史。retracted 用追加行(2026-09-08 拍板)。
+ */
+import { z } from 'zod';
+export const EvidenceSchema = z.union([
+    z.object({ conversation: z.string().min(1), job: z.string().optional() }),
+    z.object({ artifact: z.string().min(1) }),
+]);
+/** 完整观察行 */
+export const ObservationSchema = z.object({
+    id: z.string().min(1),
+    date: z.string().min(1),
+    /** 写它的老师(agent 名)或 parent */
+    author: z.string().min(1),
+    subject: z.string().optional(),
+    topic: z.string().optional(),
+    /** 一句话 */
+    claim: z.string().min(1),
+    evidence: EvidenceSchema.optional(),
+    retracted: z.boolean().default(false),
+});
+/** 纠错行:只带 id + retracted + 谁 + 何时 */
+export const ObservationRetractSchema = z.object({
+    id: z.string().min(1),
+    retracted: z.literal(true),
+    by: z.string().min(1),
+    date: z.string().min(1),
+});
+export const ObservationLineSchema = z.union([ObservationSchema, ObservationRetractSchema]);
+export const ARTIFACT_KINDS = ['课包', '补讲', '批改', '计划', '其它'];
+export const ARTIFACT_STATUS = ['draft', 'ready', 'accepted', 'retired'];
+/** 产物事件行:首行要带 kind / by / path,后续行只带变化的字段 */
+export const ArtifactEventSchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum(ARTIFACT_KINDS).optional(),
+    by: z.string().optional(),
+    at: z.string().min(1),
+    status: z.enum(ARTIFACT_STATUS).optional(),
+    path: z.string().optional(),
+    source: z.object({ conversation: z.string().min(1), job: z.string().optional() }).optional(),
+    /** manifest 指纹,同内容重出验收延续;验收开关关掉时可以没有 accepted 行 */
+    hash: z.string().optional(),
+});

package/dist/schema/plan.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 计划文件 vault/计划/<周>.md(《cotutor契约草案.md》§8):frontmatter week / status / author,
+ * 正文按老师分 H2(用显示名,2026-09-08 拍板),行内自由。家长改成 confirmed 即真相。
+ */
+import { z } from 'zod';
+export declare const PLAN_STATUS: readonly ["draft", "confirmed"];
+export type PlanStatus = (typeof PLAN_STATUS)[number];
+export declare const WEEK_RE: RegExp;
+export declare const PlanSectionSchema: z.ZodObject<{
+    title: z.ZodString;
+    lines: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type PlanSection = z.infer<typeof PlanSectionSchema>;
+export declare const PlanSchema: z.ZodObject<{
+    week: z.ZodString;
+    status: z.ZodEnum<{
+        draft: "draft";
+        confirmed: "confirmed";
+    }>;
+    author: z.ZodOptional<z.ZodString>;
+    sections: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        lines: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Plan = z.infer<typeof PlanSchema>;

package/dist/schema/plan.js

@@ -0,0 +1,19 @@
+/**
+ * 计划文件 vault/计划/<周>.md(《cotutor契约草案.md》§8):frontmatter week / status / author,
+ * 正文按老师分 H2(用显示名,2026-09-08 拍板),行内自由。家长改成 confirmed 即真相。
+ */
+import { z } from 'zod';
+export const PLAN_STATUS = ['draft', 'confirmed'];
+export const WEEK_RE = /^\d{4}-W\d{2}$/;
+export const PlanSectionSchema = z.object({
+    /** H2 标题原文(老师显示名,或「家长」等对不上老师的段) */
+    title: z.string().min(1),
+    /** 该段的非空行(去掉列表符号) */
+    lines: z.array(z.string()),
+});
+export const PlanSchema = z.object({
+    week: z.string().regex(WEEK_RE),
+    status: z.enum(PLAN_STATUS),
+    author: z.string().optional(),
+    sections: z.array(PlanSectionSchema),
+});

package/dist/schema/sections.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 老师最终文本里的两种固定段(《cotutor契约草案.md》§4 / §6):
+ *  - 「## 待裁量」需要家长拍板的问题 + 选项(HoldupAskV0,沿用 growth-apps 的形状);
+ *  - 「## 转交」交给另一位老师(HandoffV0,第一期只允许一跳)。
+ * 孩子视图剥掉它们;家长视图渲染成按钮;应用按转交 resume 目标老师。解析不出整段当正文——格式是增强不是门槛。
+ */
+import { z } from 'zod';
+export declare const HoldupOptionSchema: z.ZodObject<{
+    label: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    recommended: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type HoldupOption = z.infer<typeof HoldupOptionSchema>;
+export declare const HoldupAskSchema: z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        note: z.ZodOptional<z.ZodString>;
+        recommended: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type HoldupAsk = z.infer<typeof HoldupAskSchema>;
+export declare const HandoffSchema: z.ZodObject<{
+    to: z.ZodString;
+    why: z.ZodOptional<z.ZodString>;
+    refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type Handoff = z.infer<typeof HandoffSchema>;
+export declare const HOLDUP_HEADING = "\u5F85\u88C1\u91CF";
+export declare const HANDOFF_HEADING = "\u8F6C\u4EA4";

package/dist/schema/sections.js

@@ -0,0 +1,26 @@
+/**
+ * 老师最终文本里的两种固定段(《cotutor契约草案.md》§4 / §6):
+ *  - 「## 待裁量」需要家长拍板的问题 + 选项(HoldupAskV0,沿用 growth-apps 的形状);
+ *  - 「## 转交」交给另一位老师(HandoffV0,第一期只允许一跳)。
+ * 孩子视图剥掉它们;家长视图渲染成按钮;应用按转交 resume 目标老师。解析不出整段当正文——格式是增强不是门槛。
+ */
+import { z } from 'zod';
+import { AGENT_NAME_RE } from "./config.js";
+export const HoldupOptionSchema = z.object({
+    label: z.string().min(1),
+    note: z.string().optional(),
+    recommended: z.boolean().optional(),
+});
+export const HoldupAskSchema = z.object({
+    question: z.string().min(1),
+    options: z.array(HoldupOptionSchema).default([]),
+});
+export const HandoffSchema = z.object({
+    /** 目标老师(agent 名) */
+    to: z.string().regex(AGENT_NAME_RE),
+    why: z.string().optional(),
+    /** 相关文件或产物引用 */
+    refs: z.array(z.string()).default([]),
+});
+export const HOLDUP_HEADING = '待裁量';
+export const HANDOFF_HEADING = '转交';

package/dist/server/app.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 服务的路由层:纯函数 route(method, path, ws) → {status, json|html},测试不用起端口。
+ * R1 只有查询接口;发消息 / 会话 / 页面在 R2。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type Workspace } from '../cli/workspace.ts';
+export interface RouteResult {
+    status: number;
+    json?: unknown;
+    html?: string;
+}
+export declare function route(method: string, path: string, ws: Workspace): RouteResult;
+export declare function createHandler(ws: Workspace): (req: IncomingMessage, res: ServerResponse) => void;

package/dist/server/app.js

@@ -0,0 +1,45 @@
+import { listTeachers } from "../schema/index.js";
+import { workspaceReport } from "../cli/workspace.js";
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] ?? c);
+export function route(method, path, ws) {
+    if (method !== 'GET')
+        return { status: 405, json: { error: 'method_not_allowed' } };
+    const url = new URL(path, 'http://x');
+    switch (url.pathname) {
+        case '/api/health':
+            return { status: 200, json: { ok: true } };
+        case '/api/workspace':
+            return { status: 200, json: workspaceReport(ws) };
+        case '/api/config':
+            return {
+                status: 200,
+                json: { title: ws.config.title, kid: ws.config.kid, server: ws.config.server, agent: ws.config.agents.default, teachers: listTeachers(ws.config) },
+            };
+        case '/api/teachers':
+            return { status: 200, json: listTeachers(ws.config, { kidOnly: url.searchParams.get('kid') === '1' }) };
+        case '/': {
+            const teachers = listTeachers(ws.config, { kidOnly: true })
+                .map((t) => `<li>${esc(t.avatar ?? '')} ${esc(t.display)}${t.subject ? `<small> · ${esc(t.subject)}</small>` : ''}</li>`)
+                .join('');
+            return {
+                status: 200,
+                html: `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(ws.config.title)}</title><h1>${esc(ws.config.title)}</h1><p>R1 骨架:老师们已就位,对话页在 R2。</p><ul>${teachers}</ul>`,
+            };
+        }
+        default:
+            return { status: 404, json: { error: 'not_found', path: url.pathname } };
+    }
+}
+export function createHandler(ws) {
+    return (req, res) => {
+        const r = route(req.method ?? 'GET', req.url ?? '/', ws);
+        if (r.html !== undefined) {
+            res.writeHead(r.status, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(r.html);
+        }
+        else {
+            res.writeHead(r.status, { 'content-type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify(r.json ?? null));
+        }
+    };
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "cotutor",
+  "version": "0.1.0",
+  "description": "家里的 AI 助教团队:老师 = 可直接对话的 agent 文件 + 自己的会话;一孩一 workspace",
+  "type": "module",
+  "license": "MIT",
+  "repository": "github:TarsLab/cotutor",
+  "homepage": "https://github.com/TarsLab/cotutor#readme",
+  "bugs": "https://github.com/TarsLab/cotutor/issues",
+  "keywords": [
+    "ai",
+    "agent",
+    "claude-code",
+    "qwen-code",
+    "tutor",
+    "education",
+    "homeschool",
+    "cli"
+  ],
+  "bin": {
+    "cotutor": "bin/cotutor.js"
+  },
+  "exports": {
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "default": "./dist/schema/index.js"
+    },
+    "./workspace": {
+      "types": "./dist/cli/workspace.d.ts",
+      "default": "./dist/cli/workspace.js"
+    },
+    "./lib": {
+      "types": "./dist/lib/index.d.ts",
+      "default": "./dist/lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types scripts/test.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build && pnpm run smoke",
+    "smoke": "node --experimental-strip-types scripts/smoke.ts"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.6.0"
+  }
+}