cotutor 0.4.3 → 0.4.5

package/skills/cotutor-home/references//345/221/275/344/273/244.md

@@ -1,14 +1,82 @@
 # 命令(机器生成,别改)
 
-在 workspace 根跑;完整用法 cotutor --help。
+在 workspace 根跑;每条就是 cotutor <命令> --help 的内容。
 
 ```
-  cotutor show <老师> <job> [<日期>] [--json] [--evals] [--workspace <dir>]   看一轮:问了什么、上下文包、当时的老师文件与技能 hash、讲稿与卡、读了什么、token 与用时、给家长的尾巴;--json 是家长端「看原文」同一份数据,给编程助手分析用
-  cotutor rate <老师> <话题> <1-5> [--date <日期>]                       给一个话题打星(与家长端同一条路;≥ vault.keepScore 的话题记账时摘要才进日记)
-  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>]...           记账:这天每个还没记过的话题各起一轮记账任务,老师回「## 记账」,应用写进 vault 的日记(话题名、孩子问、摘要、观察)
-  cotutor home check [--published] [--json]                           检查首页草稿 home/draft.md(或已发布的那份):孩子会看到哪几张卡、每位老师的按钮、要改的与提醒(带行号);不花钱
-  cotutor home publish [--force] [--from <文件>] [--json]              发布首页:检查 → 留历史 home/history/<id>.md → 写 home/published.json(孩子端只读它);有要改的不发,--force 丢掉那几张照发;--from 发另一份(如历史)
-  cotutor home show [--json]                                          现在发布的是哪份、几天前、每个按钮被点了几次(哪天、哪个话题)
+这些命令都认 --workspace <目录>(在 workspace 根跑可以不写)和 --sandbox(在试用副本里跑,不进孩子的记录)。
+
+cotutor home — 检查和发布孩子端首页
+
+用法:
+  cotutor home check [--published] [--json]
+  cotutor home publish [--force] [--from <文件>] [--json]
+  cotutor home show [--json]
+
+选项:
+  --published    [check] 查已发布的那份(缺省查草稿 home/draft.md)
+  --force        [publish] 有要改的卡,丢掉它们照发
+  --from <文件>  [publish] 发另一份(比如历史里的)
+  --json         机器可读的输出
+
+说明:
+  - check 不花钱:孩子会看到哪几张卡、每位老师的按钮、要改的(带行号)
+  - publish 先检查,留历史 home/history/,写 home/published.json;孩子端刷新就是新的
+  - show:现在发布的是哪份、每个按钮被点了几次
+
+例子:
+  cotutor home check
+  cotutor home publish
+
+cotutor show — 看一轮:问了什么、上下文包、讲稿与卡、读了什么
+
+用法:
+  cotutor show <老师> <job> [<日期>] [--evals] [--json]
+
+选项:
+  --evals  看回放的那轮(evals/ 里的)
+  --json   机器可读的输出
+
+说明:
+  - 日期缺省今天;--json 和家长端「看原文」是同一份
+
+例子:
+  cotutor show math-tutor 1620-1 2026-09-12 --json
+
+cotutor rate — 给一个话题打星(1–5)
+
+用法:
+  cotutor rate <老师> <话题> <1-5> [--date <日期>] [--json]
+
+选项:
+  --date <日期>  哪天(YYYY-MM-DD,缺省今天)
+  --json         机器可读的输出
+
+说明:
+  - 和家长端同一条路;到 vault.keepScore 星的话题,记账时摘要才进日记
+
+例子:
+  cotutor rate math-tutor 1620-1 4
+
+cotutor bookkeep — 记账:把这天的话题写进日记
+
+用法:
+  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>] [--quiet] [--json]
+
+选项:
+  --date <日期>    哪天(YYYY-MM-DD,缺省今天)
+  --thread <话题>  只记这个话题
+  --quiet          不打印过程
+  --json           机器可读的输出
+
+说明:
+  - 每个还没记过的话题起一轮记账,应用写进笔记文件夹的日记
+
+注意:
+  - 花钱
+  - 写孩子的笔记文件夹
+
+例子:
+  cotutor bookkeep math-tutor
 ```
 
 ## 文件

package/skills/cotutor-tune/SKILL.md

@@ -5,7 +5,7 @@ description: 调 cotutor 的老师团:改某位老师的提示词(口气、规
 
 <!-- 给人看
 谁读:家长在 workspace 根开的编程助手
-能改:机器件,upgrade 覆盖;references/字段.md 由 src/app/skills/tune-doc.ts 生成
+能改:机器件,refresh 覆盖;references/字段.md 由 src/app/skills/tune-doc.ts 生成
 改了:在试用 workspace 里开编程助手说一句「老师话太多」(《写提示词.md》§一)
 -->
 
@@ -27,9 +27,9 @@ description: 调 cotutor 的老师团:改某位老师的提示词(口气、规
   - 改 vault:pack 干跑(不花钱)。
   - 加老师:doctor,再 pack。
 - 不改 conversations/、evals/、ledger/。
-- 不碰 .cotutor/、.agents/skills/:那是机器件,upgrade 会覆盖。
+- 不碰 .cotutor/、.agents/skills/:那是机器件,refresh 会覆盖。
 - .claude/skills 是链到 .agents/skills 的,同一份,也不碰。
-- 出厂老师的文件改过之后,cotutor upgrade 不再覆盖它,只报 diff。告诉家长这个代价;想回出厂的,用 `cotutor upgrade --force <老师>`。
+- 出厂老师的文件改过之后,cotutor refresh 不再覆盖它,只报 diff。告诉家长这个代价;想回出厂的,用 `cotutor reset <老师>`。
 - agents/<name>.md 是老师文件,由 cotutor 读正文传给 Qwen,**不要把它们当子代理派**。
 
 ## 一、改某位老师的提示词
@@ -48,7 +48,7 @@ description: 调 cotutor 的老师团:改某位老师的提示词(口气、规
 
 - 老师文件要通用:换个孩子、换个学期也能用。关于孩子的事不进老师文件。
 - 老师文件只管自由话题。某个 activity 的做法不写进老师文件:activity 话题不读老师文件,写了也用不上。
-- 有脸的老师共同的守则(上下文包怎么看、三种回复、记忆段、不说错、不写文件、不派子代理)在机器技能 .agents/skills/cotutor-tutor/。应用每个话题第一条把原文放进上下文包,upgrade 会覆盖,别改它。
+- 有脸的老师共同的守则(上下文包怎么看、三种回复、记忆段、不说错、不写文件、不派子代理)在机器技能 .agents/skills/cotutor-tutor/。应用每个话题第一条把原文放进上下文包,refresh 会覆盖,别改它。
 - 某位老师要和守则不一样的做法,写进那位老师文件里这一科那一节,它优先。只有守则的「不变的规矩」改不了。
 
 ### 路子
@@ -91,7 +91,7 @@ vault 里的文件**按属性找,不认文件名与目录**。
 - 记忆太长了(doctor 的 vault.memory 报),就帮家长合并、删旧的。
 - 每个 activity 的记忆各是一篇,老师之间、activity 之间不共享。家长想让「你说我画」也知道语文老师记的某条,就把那一行复制过去,一处一处确认。关于孩子本人的,挪进孩子的记忆,大家都看得到。
 
-vault 是 Obsidian 仓库,可能在 iCloud 里:
+vault 不在 workspace 里:位置看 cotutor.json 的 `paths.vault`(相对 workspace 根,`~/` 是家目录),缺省是旁边的 `<目录名>-vault/`;旧版建的没写 `paths.vault`,vault 就是 workspace 根。家长可能用 Obsidian 打开它,也可能放在 iCloud 里:
 
 - 只改文本,不加标签,不放图片。
 - 新学期的入口文件要新建,不改上学期的,属性写全。
@@ -116,7 +116,7 @@ vault 是 Obsidian 仓库,可能在 iCloud 里:
    - 费用或时限要不一样的,配自己的 runtime。
 4. 验:cotutor doctor(它会查文件、目录、链),再 `cotutor pack <name> "你好"`,看它拿到的上下文包对不对:学期、档案、入口文件、这学科的观察、计划里它那段。
    - 要试真回答,就 `cotutor send <name> "<一句>"`(花钱,先问)。
-5. 自家加的老师 upgrade 永远不碰。要删,就在 cotutor.json 里删条目,文件改名留着。
+5. 自家加的老师 refresh 永远不碰。要删,就在 cotutor.json 里删条目,文件改名留着。
 
 ## 四、改一个 activity
 
@@ -138,10 +138,10 @@ activity 是孩子从首页一个按钮进去的一种做法,一个文件在 `ag
 - 改完先 `cotutor activity check <老师> <名>`(不花钱),红了先修。
 - 验:`cotutor activity eval <老师> <名> --runs 1`,真老师 + 模拟孩子把旁边 `<名>.例子.md` 的例子跑一遍(花钱,先说要跑几个例子、几轮)。也可以 `cotutor replay` 那一轮。
 - 家长看到一次跑偏,就在 `<名>.例子.md` 里记成一个例子,写上「判:」,以后改它都要跑过。
-- 出厂的 activity 改过之后,upgrade 不再覆盖它,只报 diff;回出厂用 `cotutor upgrade --force <老师>/<名>`。
+- 出厂的 activity 改过之后,refresh 不再覆盖它,只报 diff;回出厂用 `cotutor reset <老师>/<名>`。
 
 ## 报告怎么写
 
 1. 先说改了哪个文件的哪一处,为什么放那里(归属)。
 2. 再贴验证结果:pack 的来源行、replay 的 diff、doctor 的那几项。
-3. 最后说副作用:改了出厂老师 upgrade 只报 diff、改了档案所有老师都会看到、花了多少钱。
+3. 最后说副作用:改了出厂老师 refresh 只报 diff、改了档案所有老师都会看到、花了多少钱。

package/skills/cotutor-tune/references//345/255/227/346/256/265.md

@@ -38,16 +38,170 @@ frontmatter 只写应用支持的这几个键:`name`、`description`、`maxTurns
 | `stall.ms` | 必需 | 30000 | 老师进程多少毫秒没有任何输出就当断流(缺省 30000;工具在跑时不算;0 = 不看,交给 CLI 自己约 180 秒的重试) |
 | `stall.retries` | 必需 | 2 | 一轮里断流后最多接着跑几次(缺省 2);用完还断,这轮按出错收尾 |
 
-## 相关命令(完整用法 cotutor --help)
+## 相关命令(每条就是 cotutor <命令> --help 的内容)
 
 ```
-  cotutor doctor [--workspace <dir>] [--json] [--live] [--fix]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send);--json 里不过的项带 cmd(能直接跑)或 human(要人来);--fix 把带 cmd 的一条条修掉,要人来的留着
-  cotutor upgrade [--workspace <dir>] [--force <老师>]...                老师文件、activity 与 skill 换新版:没改过的直接换,改过的只报 diff(--force <老师> 或 --force <老师>/<名> 才覆盖,原文留 .bak)
-  cotutor upgrade --config [--dry-run] [--workspace <dir>]              cotutor.json 补缺:新出厂老师 / 运行时 / 命令模板旗标(只加缺的,你改过的值不动)
-  cotutor add <老师名> --display <显示名> [--subject <学科>] [--avatar <emoji|图片相对路径>] [--hidden]   加一位自家的老师:出模板文件、进 cotutor.json、建目录(名字以 -tutor 结尾的是老师,figshot 给它做头像)
-  cotutor add-theme <主题名> [--from <主题>] [--workspace <dir>]       加一个自家的主题:拷一份(缺省出厂的 default)到 themes/<主题名>/,改 cotutor.json 的 kid.theme 换过去
-  cotutor pack <老师> [<消息>] [--from kid|system] [--at <ISO时间>] [--activity <名> [--param '名=值;名=值']] [--json]   干跑上下文包(--activity 看 activity 话题第一条老师拿到什么):不起模型,打印现在会发给老师的那份 + 每段来自哪个文件、那里一共几条、按政策带了几条(改了档案 / 日记 / 计划立刻看效果)
-  cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]   回放一轮:同一问按现在的 vault 与提示词再跑一遍(落 evals/,不进孩子的对话、不配音),跑完并排打印上下文包 / 讲稿 / 卡 / 读了什么的 diff
-  cotutor compare <老师> [<evalJob>] [<日期>] [--json]                   再看一次回放的对照(不给 evalJob 就列这天回放过哪些)
-  cotutor show <老师> <job> [<日期>] [--json] [--evals] [--workspace <dir>]   看一轮:问了什么、上下文包、当时的老师文件与技能 hash、讲稿与卡、读了什么、token 与用时、给家长的尾巴;--json 是家长端「看原文」同一份数据,给编程助手分析用
+这些命令都认 --workspace <目录>(在 workspace 根跑可以不写)和 --sandbox(在试用副本里跑,不进孩子的记录)。
+
+cotutor add — 加一位自家的老师
+
+用法:
+  cotutor add <老师名> --display <显示名> [--subject <学科>] [--avatar <emoji|图片>] [--description <一句话>] [--hidden] [--json]
+
+选项:
+  --display <显示名>      孩子看到的名字(必填)
+  --subject <学科>        学科
+  --avatar <emoji|图片>   emoji,或 workspace 里图片的相对路径
+  --description <一句话>  写进老师文件的一句介绍
+  --hidden                孩子端不露(只和系统、家长打交道的工具人)
+  --json                  机器可读的输出
+
+说明:
+  - 名字以 -tutor 结尾的是有脸的老师,其余是工具人
+  - 出老师文件、写进 cotutor.json、建它的家;服务不用重启
+
+例子:
+  cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬
+
+cotutor add-theme — 加一个自家的主题
+
+用法:
+  cotutor add-theme <主题名> [--from <主题>] [--json]
+
+选项:
+  --from <主题>  从哪个主题拷(缺省 default)
+  --json         机器可读的输出
+
+说明:
+  - 拷到 themes/<主题名>/;cotutor.json 的 kid.theme 改成它就换过去
+
+例子:
+  cotutor add-theme dark
+
+cotutor refresh — 换新这个孩子的出厂文件(不升级程序)
+
+用法:
+  cotutor refresh [--json]
+  cotutor refresh --config [--dry-run] [--json]
+
+选项:
+  --config   改的是 cotutor.json:只补缺的、删不再用的出厂段,改过的值不动
+  --dry-run  和 --config 一起:只看要改什么
+  --json     机器可读的输出
+
+说明:
+  - 出厂的老师、activity、技能、主题:没改过的换新,改过的保留并报 diff;换之前自动备份一份
+  - 升级程序用 cotutor update,它会对每个孩子跑这条;这条只在程序已经换过(手动 npm i -g、从仓库跑)时单独用
+  - 改过的想回出厂的:cotutor reset
+
+例子:
+  cotutor refresh
+  cotutor refresh --config --dry-run
+
+cotutor reset — 把改过的出厂老师或 activity 换回出厂的
+
+用法:
+  cotutor reset <老师>|<老师>/<activity>... [--json]
+
+选项:
+  --json  机器可读的输出
+
+说明:
+  - 只动点名的这几份;你那份存成旁边的 .bak,换之前还自动备份一份
+  - 自家加的老师、activity 没有出厂那份,换不了
+
+注意:
+  - 盖掉家长改过的老师文件:家长明确说要回出厂的才跑
+
+例子:
+  cotutor reset math-tutor
+  cotutor reset chinese-tutor/你说我画
+
+cotutor doctor — 体检;--fix 修掉能自动修的
+
+用法:
+  cotutor doctor [--json]
+  cotutor doctor --fix
+  cotutor doctor --live
+
+选项:
+  --fix   修掉能自动修的(幂等,不碰孩子的数据,不用人输东西),要人来的留着
+  --live  真连一次百炼的嘴、真配一句音
+  --json  机器可读的输出
+
+说明:
+  - --json 里没过的项带 cmd(能直接跑)或 human(要人来)
+  - 有必需项没过,退出码 1
+
+注意:
+  - --live 花一分钱
+
+例子:
+  cotutor doctor --fix
+  cotutor doctor --json
+
+cotutor pack — 干跑上下文包:不起模型,看老师会拿到什么
+
+用法:
+  cotutor pack <老师> [<消息>] [--activity <名> [--param '名=值;名=值']] [--from kid|system] [--at <ISO时间>] [--json]
+
+选项:
+  --activity <名>        像孩子点了首页的 activity 按钮,新开话题
+  --param '名=值;名=值'  activity 的参数(按钮下面那几行)
+  --from kid|system      谁说的(缺省 kid;system 不算孩子说的)
+  --at <ISO时间>         当作这个时间
+  --json                 机器可读的输出
+
+说明:
+  - 每段来自哪个文件、一共几条、按政策带了几条;改了档案、日记、计划立刻看效果
+
+例子:
+  cotutor pack math-tutor "讲讲退位"
+
+cotutor replay — 同一问按现在的提示词再跑一遍,并排对照
+
+用法:
+  cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]
+
+选项:
+  --runtime <名>  换个运行时
+  --json          机器可读的输出
+
+说明:
+  - 落 evals/,不进孩子的对话、不配音
+
+注意:
+  - 花钱
+
+例子:
+  cotutor replay math-tutor 1620-1 2026-09-12
+
+cotutor compare — 再看一次回放的对照
+
+用法:
+  cotutor compare <老师> [<evalJob>] [<日期>] [--json]
+
+选项:
+  --json  机器可读的输出
+
+说明:
+  - 不给 evalJob 就列这天回放过哪些
+
+例子:
+  cotutor compare math-tutor
+
+cotutor show — 看一轮:问了什么、上下文包、讲稿与卡、读了什么
+
+用法:
+  cotutor show <老师> <job> [<日期>] [--evals] [--json]
+
+选项:
+  --evals  看回放的那轮(evals/ 里的)
+  --json   机器可读的输出
+
+说明:
+  - 日期缺省今天;--json 和家长端「看原文」是同一份
+
+例子:
+  cotutor show math-tutor 1620-1 2026-09-12 --json
 ```

package/skills/cotutor-tutor/SKILL.md

@@ -5,7 +5,7 @@ description: cotutor 有脸的老师共同的守则:上下文包怎么看、三
 
 <!-- 给人看
 谁读:有脸的老师。应用去掉 frontmatter 和独占一行的注释,在话题第一条放进 <cotutor-rules>
-能改:机器件,init / upgrade 每次覆盖。某位老师要不一样的做法,写进那位老师文件的学科一节,它优先
+能改:机器件,init / refresh 每次覆盖。某位老师要不一样的做法,写进那位老师文件的学科一节,它优先
 改了:cotutor pack 看注入,再 cotutor replay 对照(《写提示词.md》§一)
 {{有 x}} 到 {{/有}} 之间的,这位老师的卡里有 x 才留(cotutor.json tutors.<老师>.cards;没写 = 全有)
 -->