cotutor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tarslab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# cotutor
+
+家里的 AI 助教团队。老师 = 一个可直接对话的 agent 文件 + 自己的会话;一孩一 workspace;家长看全部过程,孩子看精简后的对话与产物。
+
+设计文档在仓库的 [docs/](https://github.com/TarsLab/cotutor/tree/main/docs):《产品规划.md》《agent层设计.md》《契约草案.md》。
+
+> R1:骨架与契约。init / doctor / serve 可用,serve 只有查询接口;发消息与页面在 R2。
+
+## 装与用
+
+需要 Node ≥ 22.18,以及 `claude`(Claude Code)或 `qwen`(Qwen Code)至少一个。
+
+```sh
+npm i -g cotutor@next     # R1 只发在 next 标签下(孩子还不能对话),没有 latest;R2 起用 cotutor
+                          # 装全局,别用 npx:老师定义是链进 workspace 的,npx 缓存被回收链就断(doctor 会报断链)
+cotutor init ming --name 小明   # 建 ~/cotutor/ming/
+cotutor doctor                  # 逐项体检,不过的每条都带修复指南
+cotutor serve                   # 一 workspace 一进程
+```
+
+老师定义随包发布(数学老师、语文老师、朗读老师、作业助教、规划老师),init 把它们**链**进 workspace 的 `.claude/agents/` 与 `.qwen/agents/`——共享的是定义,不共享记忆与账本。人设、音色、开关、政策不在老师文件里,在 workspace 的 `cotutor.json`。从老师目录起会话:
+
+```sh
+cd ~/cotutor/ming/agents/math-teacher
+claude --agent math-teacher -p "<上下文包 + 消息>" --output-format stream-json
+```
+
+工作区解析顺序:`--workspace` > `COTUTOR_WORKSPACE` > cwd 或祖先有 `cotutor.json` > `~/.config/cotutor/config.json` > `~/cotutor/` 下唯一的孩子目录。
+
+## 当库用
+
+契约(zod)与纯函数层可以单独引,子路径导出、带类型:
+
+```ts
+import { CotutorConfigSchema, explainIssues } from 'cotutor/schema';  // 各文件的形状,校验失败变修复指南
+import { deriveKidView, parseSections } from 'cotutor/lib';           // 转录、精简视图、账本等纯函数
+import { loadWorkspace } from 'cotutor/workspace';                    // 解析链 + 校验
+```
+
+## 开发
+
+```sh
+pnpm i
+pnpm typecheck && pnpm test     # tests/*.test.ts 每文件一子进程
+node bin/cotutor.js --help      # bin 在仓库内直跑 src(Node 原生 type stripping,零构建)
+pnpm build && pnpm smoke        # 出厂检查:体检要发的那份(dist + agents/)
+```
+
+MIT。

package/agents/chinese-teacher.md

@@ -0,0 +1,19 @@
+---
+name: chinese-teacher
+description: 语文老师。生字、词语、课文、写话都找它;先一两句大白话回答,要范读要示范的以后再出课件
+maxTurns: 40
+permissionMode: bypassPermissions
+memory: project
+---
+你是这个家的语文老师,面对的是一个小学生和他的家长。cwd 是你的家(agents/chinese-teacher/),账本在 ../../ledger/,家规在 ../../CLAUDE.md。消息前面有一段 `cotutor:` 开头的上下文包,先看它再答。孩子问「这个字怎么读 / 什么意思」这类,直接答。
+
+回复只有两种,先分清:
+- **问答**(缺省,孩子或家长随口问):这次回复就是一两句大白话,不超过三句;不用工具,不读账本(上下文包里已经给了时段、正在看什么、本周计划、最近观察),想到的就直接说。
+- **任务**(消息前的上下文包里 `from: system`,或家长明确写了「出课包 / 补讲 / 记账 / 做计划」):按任务做,做完在最后一段报告结果。
+
+现在还没有出课件的通道(R5 才接上):**不要自己写 HTML 或任何课件文件**。要画要讲的,在最后一段对孩子说「这个要画给你看,等我准备好会出现在你的今天里」就够了。
+
+你说给孩子听的话放在回复的**最后一段**;孩子只看得到最后一段,中间的话和工具过程只有家长看。永远不评价孩子答得对不对,不打分;把孩子的话当问题,不当答案。
+
+记账与记忆(只在任务里做,问答不做):值得别的老师知道的观察,追加一行到 ../../ledger/observations.jsonl;你自己的经验记进你的记忆目录。
+需要家长拍板的事写成一段「## 待裁量」(question: 一句话;options: 列表),不要停下来等。

package/agents/homework-aide.md

@@ -0,0 +1,17 @@
+---
+name: homework-aide
+description: 作业助教。家长拍的作业照片先到它这里:认学科、认题号、交给对应的学科老师;自己不讲题
+maxTurns: 30
+permissionMode: bypassPermissions
+memory: project
+---
+你是这个家的作业助教,只和家长打交道。cwd 是你的家(agents/homework-aide/),账本在 ../../ledger/,家规在 ../../CLAUDE.md。消息前面有一段 `cotutor:` 开头的上下文包,先看它再答。
+
+你的活:
+- 家长发来作业照片或素材集引用时,看照片认学科、认有几道题、哪几道错了,写一句结论。
+- 然后写一段「## 转交」交给学科老师(to: math-teacher / chinese-teacher / reading-teacher;why: 一句话;refs: 照片或素材集路径)。第一期只允许一跳,你自己不讲题。
+- 认不出学科、或照片糊了拍不全,写一段「## 待裁量」问家长(question + options),不要猜。
+- 把「哪天、什么作业、错了几道」追加一行到 ../../ledger/observations.jsonl。
+- 家长随口问你别的,一两句话答,不用工具。
+
+回复的最后一段留给家长看的一句话结论。

package/agents/math-teacher.md

@@ -0,0 +1,19 @@
+---
+name: math-teacher
+description: 数学老师。孩子问数学题、家长发数学作业都找它;先一两句大白话回答,要画要讲的以后再出课包或补讲
+maxTurns: 40
+permissionMode: bypassPermissions
+memory: project
+---
+你是这个家的数学老师,面对的是一个小学生和他的家长。cwd 是你的家(agents/math-teacher/),账本在 ../../ledger/,家规在 ../../CLAUDE.md。消息前面有一段 `cotutor:` 开头的上下文包(谁在说、几点、正在看什么、本周计划、最近观察),先看它再答。
+
+回复只有两种,先分清:
+- **问答**(缺省,孩子或家长随口问):这次回复就是一两句大白话,不超过三句;不用工具,不读账本(上下文包里已经给了时段、正在看什么、本周计划、最近观察),想到的就直接说。
+- **任务**(消息前的上下文包里 `from: system`,或家长明确写了「出课包 / 补讲 / 记账 / 做计划」):按任务做,做完在最后一段报告结果。
+
+现在还没有出课件的通道(R5 才接上):**不要自己写 HTML 或任何课件文件**。要画要讲的,在最后一段对孩子说「这个要画给你看,等我准备好会出现在你的今天里」就够了。
+
+你说给孩子听的话放在回复的**最后一段**;孩子只看得到最后一段,中间的话和工具过程只有家长看。永远不评价孩子答得对不对,不打分;把孩子的话当问题,不当答案。
+
+记账与记忆(只在任务里做,问答不做):值得别的老师知道的观察,追加一行到 ../../ledger/observations.jsonl;你自己的经验记进你的记忆目录。
+需要家长拍板的事写成一段「## 待裁量」(question: 一句话;options: 列表),不要停下来等。

package/agents/planner.md

@@ -0,0 +1,18 @@
+---
+name: planner
+description: 规划老师。读账本和上周计划,出下周计划草稿到 vault 的计划目录;孩子端不露面
+maxTurns: 40
+permissionMode: bypassPermissions
+memory: project
+---
+你是这个家的规划老师,只和家长打交道,孩子看不到你。cwd 是你的家(agents/planner/),账本在 ../../ledger/,家规在 ../../CLAUDE.md。消息前面有一段 `cotutor:` 开头的上下文包,先看它再答。
+
+你的活:
+- 家长说「做下周计划」(或 `from: system` 的定时任务)时,读 ../../ledger/observations.jsonl(最近两周)、../../ledger/artifacts.jsonl、上周的计划文件,写下周计划**草稿**。
+- 计划文件放 vault 的计划目录(cotutor.json 的 paths.plans),文件名 `<YYYY-Www>.md`,形状固定:
+  frontmatter `week: 2026-W37`、`status: draft`、`author: planner`;正文按老师**显示名**分 `## 数学老师` `## 语文老师` `## 朗读老师` `## 家长`,每段几行,宁少勿多。
+- 家长改成 `status: confirmed` 才算数;你不改别人的计划文件。
+- 别的老师的记忆目录也是本地文件,想读可以读,但以账本为准。
+- 家长随口问你别的,一两句话答,不用工具。
+
+回复的最后一段写一句:计划草稿放在哪里、几条。

package/agents/reading-teacher.md

@@ -0,0 +1,19 @@
+---
+name: reading-teacher
+description: 朗读老师(英语)。教材页、单词、句子、跟读都找它;回答尽量短,英文后面跟中文
+maxTurns: 40
+permissionMode: bypassPermissions
+memory: project
+---
+你是这个家的英语朗读老师,面对的是一个刚开始学英语的小学生和他的家长。cwd 是你的家(agents/reading-teacher/),账本在 ../../ledger/,家规在 ../../CLAUDE.md。消息前面有一段 `cotutor:` 开头的上下文包,先看它再答。孩子问单词、句子怎么读怎么说,直接答:英文一句,后面跟中文意思,总共不超过两句。
+
+回复只有两种,先分清:
+- **问答**(缺省,孩子或家长随口问):这次回复就是一两句大白话,不超过三句;不用工具,不读账本(上下文包里已经给了时段、正在看什么、本周计划、最近观察),想到的就直接说。
+- **任务**(消息前的上下文包里 `from: system`,或家长明确写了「出课包 / 补讲 / 记账 / 做计划」):按任务做,做完在最后一段报告结果。
+
+现在还没有出课件的通道(R5 才接上):**不要自己写 HTML 或任何课件文件**。要画要讲的,在最后一段对孩子说「这个要画给你看,等我准备好会出现在你的今天里」就够了。
+
+你说给孩子听的话放在回复的**最后一段**;孩子只看得到最后一段,中间的话和工具过程只有家长看。永远不评价孩子答得对不对,不打分;把孩子的话当问题,不当答案。
+
+记账与记忆(只在任务里做,问答不做):值得别的老师知道的观察,追加一行到 ../../ledger/observations.jsonl;你自己的经验记进你的记忆目录。
+需要家长拍板的事写成一段「## 待裁量」(question: 一句话;options: 列表),不要停下来等。

package/bin/cotutor.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * 薄壳:仓库内直跑 src/cli/main.ts(Node ≥22.18 原生 type stripping,零构建迭代);
+ * npm 包不含 src,回退到 dist/cli/main.js(tsc 产物,prepublishOnly 保证已构建)。
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const src = new URL('../src/cli/main.ts', import.meta.url);
+const entry = existsSync(fileURLToPath(src)) ? src : new URL('../dist/cli/main.js', import.meta.url);
+try {
+  const { main } = await import(entry.href);
+  await main(process.argv.slice(2));
+} catch (err) {
+  console.error(`cotutor: 内部错误:${err?.stack ?? err}`);
+  process.exitCode = 4;
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,19 @@
+import { type ResolveOptions, type RootSource } from './workspace.ts';
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    required: boolean;
+    detail: string;
+    fix?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    root: string | null;
+    source: RootSource | null;
+    checks: DoctorCheck[];
+}
+/** 预设的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
+export declare function presetCli(run: readonly string[]): string;
+export declare function doctorWorkspace(override?: string, opts?: ResolveOptions & {
+    probeEnv?: boolean;
+}): Promise<DoctorReport>;

package/dist/cli/doctor.js

@@ -0,0 +1,190 @@
+/**
+ * cotutor doctor:环境 + 工作区逐项体检,失败项附修复命令(错误信息即修复指南)。
+ * 静默失败摆到明面:配置坏了、老师链断了、账本有坏行、角色指向踩空。
+ * exit 约定同 drawtell / voxtell doctor:必需项全过 exit 0,否则 1;--json 带 ok 与整份 checks。
+ */
+import { execFile } from 'node:child_process';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { parseAgentFile } from "../lib/agent-file.js";
+import { parseArtifactEvents, parseObservations } from "../lib/ledger.js";
+import { DIRS } from "./skeleton.js";
+import { CONFIG_FILE, ConfigError, USER_CONFIG, UsageError, assembleWorkspace, expandPath, parseConfig, readJson, redactHome, resolveRoot, } from "./workspace.js";
+const execFileP = promisify(execFile);
+async function statOrNull(p) {
+    return stat(p).catch(() => null);
+}
+async function evictedCount(dir) {
+    try {
+        return (await readdir(dir)).filter((f) => f.endsWith('.icloud')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** 预设的 CLI 名(run[0] 的 basename):决定链在 .claude 还是 .qwen 下 */
+export function presetCli(run) {
+    return basename(run[0] ?? '');
+}
+export async function doctorWorkspace(override, opts = {}) {
+    const probeEnv = opts.probeEnv ?? true;
+    const checks = [];
+    const push = (c) => checks.push(c);
+    const [maj, min] = process.versions.node.split('.').map(Number);
+    const nodeOk = maj > 22 || (maj === 22 && min >= 18);
+    push({ name: 'node', ok: nodeOk, required: true, detail: `node ${process.versions.node}`, fix: nodeOk ? undefined : '需要 Node ≥ 22.18' });
+    let root = null;
+    let source = null;
+    try {
+        ({ root, source } = resolveRoot(override, opts));
+    }
+    catch (err) {
+        if (!(err instanceof UsageError))
+            throw err;
+        push({
+            name: err instanceof ConfigError ? 'user-config' : 'workspace',
+            ok: false,
+            required: true,
+            detail: err.message,
+            fix: err instanceof ConfigError ? `修复 ${redactHome(err.file)} 的 JSON,或删掉它` : 'cotutor init <slug>,或用 --workspace / COTUTOR_WORKSPACE 指定',
+        });
+        return { ok: false, root: null, source: null, checks };
+    }
+    push({ name: 'workspace', ok: true, required: true, detail: `${redactHome(root)}(来源:${source})` });
+    // ---- cotutor.json ----
+    let ws = null;
+    const configFile = join(root, CONFIG_FILE);
+    try {
+        const raw = readJson(configFile);
+        if (raw === null) {
+            push({ name: CONFIG_FILE, ok: false, required: true, detail: '不存在', fix: `cotutor init <slug> --dir ${redactHome(root)}(已有文件不动)` });
+        }
+        else {
+            const config = parseConfig(raw, configFile);
+            ws = assembleWorkspace(root, source, config);
+            push({
+                name: CONFIG_FILE,
+                ok: true,
+                required: true,
+                detail: `kid ${config.kid.slug}、${Object.keys(config.teachers).length} 位老师、预设 ${config.agents.default}、端口 ${config.server.port}`,
+            });
+        }
+    }
+    catch (err) {
+        if (!(err instanceof ConfigError))
+            throw err;
+        push({ name: CONFIG_FILE, ok: false, required: true, detail: err.message, fix: '按上面逐条修;政策文件机器不重建,改坏了靠 git 回退' });
+    }
+    // ---- 骨架 ----
+    const missing = [];
+    for (const d of DIRS)
+        if (!(await statOrNull(join(root, d)))?.isDirectory())
+            missing.push(`${d}/`);
+    push({
+        name: 'skeleton',
+        ok: missing.length === 0,
+        required: true,
+        detail: missing.length ? `缺 ${missing.join(' ')}` : [...DIRS].map((d) => `${d}/`).join(' '),
+        fix: missing.length ? `cotutor init <slug> --dir ${redactHome(root)}(幂等补缺)` : undefined,
+    });
+    const rulesMissing = (await Promise.all(['CLAUDE.md', 'QWEN.md'].map(async (f) => ((await statOrNull(join(root, f))) ? null : f)))).filter(Boolean);
+    push({
+        name: 'rules',
+        ok: rulesMissing.length === 0,
+        required: false,
+        detail: rulesMissing.length ? `缺家规 ${rulesMissing.join(' ')}(老师少了常驻指令)` : '家规 CLAUDE.md QWEN.md 在',
+        fix: rulesMissing.length ? 'cotutor init 补上(已有的不动)' : undefined,
+    });
+    if (ws) {
+        // ---- 老师:定义链 + 名字一致 + 老师目录 ----
+        const defaultCli = presetCli(ws.config.agents[ws.config.agents.default]?.run ?? []);
+        for (const name of Object.keys(ws.config.teachers)) {
+            for (const [cli, dir] of [
+                ['claude', ws.dirs.claudeAgents],
+                ['qwen', ws.dirs.qwenAgents],
+            ]) {
+                const file = join(dir, `${name}.md`);
+                const required = cli === defaultCli;
+                let detail;
+                let ok = false;
+                try {
+                    const { frontmatter } = parseAgentFile(await readFile(file, 'utf8'));
+                    ok = frontmatter.name === name;
+                    detail = ok ? `${redactHome(file)} name 一致` : `${redactHome(file)} 的 frontmatter name 是 "${frontmatter.name ?? ''}",与老师键 ${name} 不一致`;
+                }
+                catch {
+                    detail = `${redactHome(file)} 读不到(链断了或没建)`;
+                }
+                push({
+                    name: `teacher.${name}.${cli}`,
+                    ok,
+                    required,
+                    detail,
+                    fix: ok ? undefined : `cotutor init 重链(链到本包 agents/${name}.md),或把老师键改成文件里的 name`,
+                });
+            }
+            const home = join(ws.dirs.agents, name);
+            const there = (await statOrNull(home))?.isDirectory() ?? false;
+            push({ name: `teacher.${name}.home`, ok: there, required: true, detail: there ? `agents/${name}/ 在(会话 cwd)` : `agents/${name}/ 不在`, fix: there ? undefined : 'cotutor init 补建' });
+        }
+        // ---- paths 角色指向:配了就该在 ----
+        for (const [role, value] of Object.entries(ws.config.paths)) {
+            const target = ws.paths[role] ?? expandPath(value, ws.root);
+            const st = await statOrNull(target);
+            if (!st) {
+                push({ name: `paths.${role}`, ok: false, required: true, detail: `指向不存在:${redactHome(target)}`, fix: `mkdir -p 该目录,或修正 cotutor.json 的 paths.${role};指向 Obsidian vault 时确认 vault 已建、iCloud 已同步` });
+                continue;
+            }
+            const evicted = target.includes('Mobile Documents') && st.isDirectory() ? await evictedCount(target) : 0;
+            push({ name: `paths.${role}`, ok: evicted === 0, required: false, detail: `${redactHome(target)}${evicted ? `——有 ${evicted} 个 .icloud 占位` : ''}`, fix: evicted ? '关掉 iCloud「优化 Mac 储存空间」,或把该目录下载到本地' : undefined });
+        }
+        // ---- 账本:坏行必须响(不可再生,别删)----
+        for (const [name, file, parse] of [
+            ['observations', ws.files.observations, parseObservations],
+            ['artifacts', ws.files.artifacts, parseArtifactEvents],
+        ]) {
+            try {
+                const text = await readFile(file, 'utf8');
+                const { rows, errors } = parse(text);
+                push({ name: `ledger.${name}`, ok: errors.length === 0, required: true, detail: errors.length ? errors.slice(0, 3).join(';') : `${rows.length} 行`, fix: errors.length ? '修那几行,或 git checkout 回退;账本不可再生,不要删了重来' : undefined });
+            }
+            catch {
+                push({ name: `ledger.${name}`, ok: true, required: false, detail: '没有(还没记过);cotutor init 会建空文件' });
+            }
+        }
+        // ---- 预设的 CLI 在不在 ----
+        if (probeEnv) {
+            for (const [preset, p] of Object.entries(ws.config.agents)) {
+                if (preset === 'default' || typeof p === 'string')
+                    continue;
+                const bin = presetCli(p.run);
+                const required = preset === ws.config.agents.default;
+                try {
+                    const { stdout } = await execFileP(bin, ['--version'], { timeout: 8000 });
+                    push({ name: `agents.${preset}`, ok: true, required, detail: `${bin} ${stdout.trim().split('\n')[0]}` });
+                }
+                catch {
+                    push({ name: `agents.${preset}`, ok: false, required, detail: `PATH 里没有 ${bin}`, fix: required ? `装 ${bin},或把 agents.default 改成装了的那个预设` : undefined });
+                }
+            }
+        }
+    }
+    // ---- 用户配置 ----
+    try {
+        const text = await readFile(USER_CONFIG, 'utf8');
+        try {
+            const u = JSON.parse(text);
+            push({ name: 'user-config', ok: true, required: false, detail: u.workspace ? `workspace → ${redactHome(expandPath(u.workspace, root))}` : '有,但未设 workspace' });
+        }
+        catch {
+            push({ name: 'user-config', ok: false, required: false, detail: `${redactHome(USER_CONFIG)} 解析失败`, fix: '修复 JSON 或删掉它' });
+        }
+    }
+    catch {
+        push({ name: 'user-config', ok: true, required: false, detail: `未配置(可选):{"workspace": "…"} 写进 ${redactHome(USER_CONFIG)};cotutor init 会代劳` });
+    }
+    const gitThere = (await statOrNull(join(root, '.git'))) !== null;
+    push({ name: 'git', ok: gitThere, required: false, detail: gitThere ? '工作区是 git 仓' : '工作区不在 git 里', fix: gitThere ? undefined : '建议 git init:老师记忆、账本、政策都是不可再生状态' });
+    return { ok: checks.filter((c) => c.required).every((c) => c.ok), root, source, checks };
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,17 @@
+export interface InitStep {
+    item: string;
+    action: 'created' | 'exists' | 'kept';
+    note?: string;
+}
+export interface InitResult {
+    root: string;
+    steps: InitStep[];
+    suggestions: string[];
+}
+export interface InitOptions {
+    slug: string;
+    dir?: string;
+    name?: string;
+    port?: number;
+}
+export declare function initWorkspace(opts: InitOptions): Promise<InitResult>;

package/dist/cli/init.js

@@ -0,0 +1,114 @@
+/**
+ * cotutor init <slug>:建 ~/cotutor/<slug>/ 骨架。语义是**幂等补缺**——已有的文件与目录一律不动,缺什么补什么。
+ * 三条边界(沿 drawtell init):政策文件只在缺失时写模板;用户配置只在还没指定 workspace 时补;不动 git。
+ * 老师定义不拷贝,**链**到本包 agents/(共享的是定义,不共享记忆与账本);链已存在(哪怕是实体文件)就不动。
+ */
+import { mkdir, readFile, stat, symlink, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { DIRS, GITIGNORE, LEDGER_FILES, RULES, configTemplate, shippedAgents } from "./skeleton.js";
+import { CONFIG_FILE, HOME_ROOT, USER_CONFIG, expandPath } from "./workspace.js";
+async function exists(p) {
+    return (await stat(p).catch(() => null)) !== null;
+}
+async function lexists(p) {
+    const { lstat } = await import('node:fs/promises');
+    return (await lstat(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 agents = await shippedAgents();
+    const rootExisted = await exists(root);
+    if (!rootExisted)
+        await mkdir(root, { recursive: true });
+    steps.push({ item: '.', action: rootExisted ? 'exists' : 'created' });
+    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' });
+    }
+    for (const a of agents) {
+        const home = join(root, 'agents', a.name);
+        if (await exists(home)) {
+            steps.push({ item: `agents/${a.name}/`, action: 'exists' });
+        }
+        else {
+            await mkdir(home, { recursive: true });
+            await writeFile(join(home, '.gitkeep'), '');
+            steps.push({ item: `agents/${a.name}/`, action: 'created' });
+        }
+        for (const sub of ['.claude/agents', '.qwen/agents']) {
+            const link = join(root, sub, basename(a.file));
+            if (await lexists(link)) {
+                steps.push({ item: `${sub}/${basename(a.file)}`, action: 'exists' });
+                continue;
+            }
+            await symlink(a.file, link);
+            steps.push({ item: `${sub}/${basename(a.file)}`, action: 'created', note: `→ ${a.file}` });
+        }
+    }
+    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' });
+        }
+    }
+    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, teachers: agents }));
+        steps.push({ item: CONFIG_FILE, action: 'created' });
+    }
+    for (const f of ['CLAUDE.md', 'QWEN.md']) {
+        const p = join(root, f);
+        if (await exists(p))
+            steps.push({ item: f, action: 'kept', note: '家规已有,不覆盖' });
+        else {
+            await writeFile(p, RULES);
+            steps.push({ item: f, action: 'created' });
+        }
+    }
+    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: '已指向本工作区' }
+            : { item: 'user-config', action: 'kept', note: '已指向别的工作区,未改;多孩子时一 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 指向本工作区' });
+    }
+    const suggestions = [];
+    if (!(await exists(join(root, '.git'))))
+        suggestions.push('git init(建议:老师记忆、账本、政策都是不可再生状态,git 是破坏后的兜底)');
+    suggestions.push(`改 ${CONFIG_FILE}:paths.vault 指到孩子的 Obsidian vault,teachers.*.voice 填 voxtell 音色 id`);
+    suggestions.push('cotutor doctor 逐项体检;cotutor serve 起服务');
+    return { root, steps, suggestions };
+}

package/dist/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;