cotutor 0.2.0 → 0.4.0

package/LICENSE

@@ -1,21 +1,249 @@
-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.
+cotutor License
+
+cotutor is licensed under the Apache License, Version 2.0 (the "Apache
+License"), with the following additional conditions. Where these
+conditions and the Apache License conflict, these conditions prevail.
+
+Definitions
+
+  "Workspace" means one directory created by `cotutor init` (or by a
+  derivative of it), holding one child's configuration, records and
+  vault.
+
+  "Household" means one family living together.
+
+  "Brand Marks" means the cotutor logo (two nested letter "C" shapes
+  opening to the right), the name "cotutor" and a link to the cotutor
+  repository (currently https://github.com/TarsLab/cotutor), as the
+  Software displays them.
+
+1. Multi-tenant service. Unless you have written permission from the
+   Licensor, you may not use the Software, or any work derived from it,
+   to operate a service in which Workspaces belonging to more than one
+   Household are run by you or on your infrastructure, or in which the
+   Software's functionality is made available to people outside your own
+   Household. This applies whether or not you charge for the service.
+   Running any number of Workspaces for your own Household is not
+   restricted by this condition.
+
+2. Brand Marks. You may not remove, hide, alter or replace the Brand
+   Marks in the Software or in any work derived from it. The pages the
+   Software provides for parents and its workbench, however they are
+   named or arranged, must continue to display them as the Software
+   does. You may change themes, tutor names and avatars, and Workspace
+   titles.
+
+3. Contributions. By contributing to the Software, you agree that:
+   (a) the Licensor may change the license of the Software, including
+       your contributions, to be more or less restrictive; and
+   (b) your contributions may be used for commercial purposes, including
+       services operated by the Licensor.
+
+For written permission or a commercial license, open an issue at
+https://github.com/TarsLab/cotutor.
+
+Copyright 2026 tarslab
+
+------------------------------------------------------------------------
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,42 @@
+cotutor
+Copyright 2026 tarslab
+
+This product includes code adapted from hanzi-writer 3.7.2
+(https://github.com/chanind/hanzi-writer), the stroke matching in
+src/dictation/lib/match.ts, under the MIT License:
+
+  Copyright (c) 2014 David Chanin
+
+  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.
+
+The stroke data used by the tianzige and dictation cards comes from the
+hanzi-writer-data package, which is derived from Make Me a Hanzi and the
+Arphic fonts and is licensed under the Arphic Public License. cotutor does
+not include that data; it reads it at runtime from the installed
+hanzi-writer-data dependency.
+
+The subject marks shown on the kid board are glyph outlines baked from these
+fonts, all licensed under the SIL Open Font License, Version 1.1
+(https://openfontlicense.org):
+
+  Ma Shan Zheng: Copyright 2018 The MaShanZheng Project Authors
+    (https://github.com/googlefonts/mashanzheng)
+  Noto Serif SC: (c) 2017-2024 Adobe (http://www.adobe.com/)
+  Barlow: Copyright 2017 The Barlow Project Authors (https://github.com/jpt/barlow)

package/README.md

@@ -1,40 +1,67 @@
 # cotutor
 
-家里的 AI 老师团,和家长一起教。几位可以直接对话的老师(数学、语文、朗读、作业老师、规划、画图),孩子在 iPad 上按住说话就能问,家长在自己的页面上看全部过程、管每位老师的性子和规矩。数据全在自家电脑上。
+家里的 AI 老师团,和家长一起教。几位可以直接对话的老师(数学、语文、英语),孩子在 iPad 上按住说话就能问,家长在自己的页面上看全部过程、管每位老师的性子和规矩。数据全在自家电脑上。
 
-> 现在到 R3 + 板书:家长端与孩子端都能用,老师的回复是一页板书(卡 + 逐句讲稿),画图老师能把一道题做成能播的课包;记账、作业照片、规划在后面的里程碑。iPad 真机试用还没开始。
+> 家长端与孩子端都能用:老师的回复是一页板书(卡 + 逐句讲稿),家长在幕后把要画出来讲的题做成小课堂;学完家长打星记账进 Obsidian 日记,作业照片在学科老师页上拍。
 
 ## 五分钟用起来
 
-需要 Node ≥ 22.18,以及 Claude Code 或 Qwen Code 至少一个(老师是它们跑出来的)。
+需要一台电脑(Mac 最省事)、Node ≥ 22.18,和一个百炼账号(北京地域,按量付费)。老师的嘴和脑都走百炼,由应用直接调用,不用另装模型客户端:嘴是 `qwen3.8-omni-flash-realtime`,听孩子说、照着讲稿念;脑是 `qwen3.8-max`,写讲稿和板书。
 
 ```sh
 npm i -g cotutor
-cotutor init ming --name 小明     # 建 ~/cotutor/ming/:六位老师、四个领域 skill、账本、对话目录、cotutor.json
-cotutor doctor                    # 逐项体检,不过的每条都带修复命令;--live 真起一次老师
-cotutor serve                     # 孩子端 http://<ip>:5180/,家长端 /parent
+cotutor init ming --name 小明 --grade 2     # 建 ~/cotutor/ming/:三位老师、技能、账本、对话目录、cotutor.json
+cotutor service install                    # 装成这台电脑的后台服务,打印家长端首页的地址,孩子的平板在那里扫码
+cotutor open                               # 打开家长端,不用记地址
 ```
 
-`init` 把出厂老师(含画图老师)拷进 `.claude/agents/`,把画图用的四个领域 skill 拷进 `.claude/skills/`;
-画图老师跑的 drawtell 随包装好,不用另外装。要在 iPad 上用(按住说话要 HTTPS):`cotutor cert` 签一张
-自签证书,把根证书装到 iPad,重启 `serve`。
+后台服务登录后自己起来、崩了自己再起、关了终端照样跑,日志按天落文件:`cotutor service status` 看在不在跑,`cotutor service logs` 看日志,`cotutor service restart` 重起。Mac 上用 launchd,Linux 上用 systemd 用户服务,Windows 上是一条用户自己的登录项(不用管理员、没有黑窗口);第一次起来 Windows 可能弹窗问「允许访问」,点允许,平板才连得进来。要在终端里调试用 `cotutor serve`,先 `cotutor service stop` 让出端口。
+
+Mac 和 Windows 上,`service install` 会一起装一个菜单栏(任务栏)图标,不用开终端就能看状态:正常时就是 logo;有事要处理出橙点;后台服务没在跑时 logo 变淡并出红点。状态变差时通知一次。点开图标能看原因、打开家长端、重启服务、看日志。「退出 cotutor」会停掉这台电脑上所有孩子的后台服务,平板打不开,下次登录自动恢复。Windows 的新图标先收在任务栏右下角的 `^` 里。不要图标就 `cotutor tray off`,装服务时加 `--no-tray` 也行。Linux 上没做,用 `cotutor service status` 看。
+
+地址认电脑名,换 Wi-Fi、路由器换 IP 都不用重签证书、不用重扫。端口在 `init` 时选一次写进 `cotutor.json`,以后不变:优先 443,地址里不用写端口(`https://<电脑名>.local/`);443 被占着或系统不让用(Linux 默认不让)就用 8443,再往后 8445、8447;几个孩子各用各的,自动让开。运行时被占只报错说明是谁占着,不会自己换,因为换了端口平板要重新扫码、重加图标。试用(`--sandbox`)的端口永远是真 workspace 的 +1,`cotutor open --sandbox` 打开。
+
+接着三件事:
+
+1. **填百炼**:在这台电脑上打开家长端 `/parent` 的「首页」,填百炼「按量付费」的 API Key 和业务空间 ID,保存前会先试连。API Key 在百炼控制台的「密钥管理」里创建,业务空间 ID 在控制台的业务空间详情里看,以百炼文档为准:[获取与配置 API Key](https://help.aliyun.com/zh/model-studio/get-api-key)、[首次调用千问 API](https://help.aliyun.com/zh/model-studio/first-api-call-to-qwen)(里面讲了业务空间 ID)。Key 跟地域绑定,控制台右上角先选北京。Token Plan 的 `sk-sp-` 不行。没填时孩子端只出「老师们还没到」。
+2. **填档案**:workspace 里的 `孩子.md` 填 `school_start`(读一年级的年月,如 `2025-09`),老师据此知道现在是几年级哪个学期。想用自己的 Obsidian 库,改 `cotutor.json` 的 `paths.vault`。
+3. **体检**:`cotutor doctor` 逐项检查,不过的每条都带修复命令。
+
+`init` 把出厂老师拷进 `agents/<老师>.md`,把做课包用的四个技能 chalk-* 和五个机器件 cotutor-tutor / cotutor-board / cotutor-analyze / cotutor-tune / cotutor-home 拷进 `.agents/skills/`(Codex、Qwen Code 直接读;Claude Code 读的 `.claude/skills` 是链到它的);
+做小课堂的课包用 `cotutor chalk`(check / build / bake / snap / dub),烤画面与截图用本机的 Chrome(Windows 上没有 Chrome 就用 Edge)。要在平板上用(按住说话要 HTTPS):`cotutor cert` 签一张
+自签证书(要 mkcert:Mac 上 `brew install mkcert && mkcert -install`;Windows 上 `winget install FiloSottile.mkcert`,重开终端再 `mkcert -install`),把根证书装到平板并打开信任,`cotutor service restart`(在终端里跑的就重开 `cotutor serve`),扫码打开。iPad 的步骤见 [iPad 与 iPhone](docs/iPad与iPhone.md)。
 
 然后在浏览器里:
 
-- **家长端 `/parent`**:和任何一位老师说话,看原始过程;老师团页改人设、政策、老师的性子(老师文件),加新老师;设置页改路径、端口、配音。
-- **孩子端 `/`**:一周小路、今天的时段、一排老师头像;点头像进板书页,按住说话或打字。老师的回答是一页板书:卡先铺开(选择题、填空、点读、图、动画课包、画板),讲稿一句句念、笔跟着声音标注,末句问句停下来等孩子。点一张卡进舞台做题,做完「交给老师」。孩子永远看不到工具、报错、评判。
+- **家长端 `/parent`**:「首页」设孩子的首页(按钮、这周的词、老师的先后),扫码打开(孩子的平板一张、家长自己的手机一张),给老师换头像和声音;「设置」定孩子的平板上按住说话那一栏放哪边;「记录」按天看孩子和每位老师的板书(答案不剥)、看录像、打星、记账、删话题,看这天写进 vault 的每一行,不要的一行一行撤回。右上角「工作台 ↗」去工作台。
+- **工作台 `/dev`**:给有技术背景的家长与开发者。和任何一位老师说话、看一轮的原文;老师团页改人设、政策、老师文件,加新老师;设置页改路径、端口。头像与声音只在家长端改。
+- **孩子端 `/`**:首页每位老师一张卡,卡上的按钮是家长排好的(新话题、接着以前的话题、带讲法的开场、先看一堂小课堂);点了进板书页,按住说话或打字。老师的回答是一页板书:卡先铺开(选择题、点读、田字格、单词、图、小课堂、画板、拍照),讲稿一句句念、笔跟着声音标注,末句问句停下来等孩子。点一张卡进舞台做题,做完「交给老师」。孩子永远看不到工具、报错、评判。
 
-想听老师的声音:装 [voxtell](https://github.com/tarslab/voxtell),给老师填音色;没装就退回浏览器合成的声音。
-不花钱先看孩子端长什么样:`cotutor mock` 起一份模拟接口,不经真实老师。细节见 [docs/家长手册.md](docs/家长手册.md)。
+实时老师的声音由 realtime 模型提供;点读、单词等卡片的配音也走百炼(同一把 key),出厂三位各有一个缺省的。在家长端「首页」点老师的「样子与声音」,再点「换一个」在弹窗里挑(全部音色都在,能搜,能按男女、口音、中英、年纪、场景筛,能试听)。
+不花钱先看孩子端长什么样:`cotutor mock` 起一份模拟接口,不经真实老师。
+
+## 年级教学包
+
+面向中国大陆小学一至六年级,当前提供二年级教学包。`cotutor grades` 查看可用年级;新建时未指定 `--grade` 默认二年级,未提供的年级不会自动回退。
+
+出厂文件在 `grades/grade-2/`。三科分别提供预习、检查作业、复习(孩子端老师牌上常驻三块方砖);语文有写话与看图写话,英语有口语课,数学小课堂配合提前做好的课包。家长按教材版本、学期和孩子实际进度设置材料。
+
+孩子当前学期仍由档案决定;升年级不会自动替换家长的老师文件。旧 workspace 执行 `cotutor upgrade` 补记二年级来源,保留自定义内容。贡献其他年级与验证方式见 [年级教学包设计](docs/年级教学包.md)。
 
 ## 老师是文件
 
-每位老师 = 一个 Markdown 文件(frontmatter + 正文即系统提示)+ cotutor.json 里的一条(显示名、头像、音色、开关、政策)+ 自己的目录与对话。出厂六位(数学、语文、朗读、作业、规划、画图)随包发布,init **拷贝**进你的老师们,改了就是你家的;`cotutor upgrade` 只换没改过的,改过的打印差异让你定。再加一位:
+每位老师 = 一个 Markdown 文件(frontmatter + 正文即系统提示)+ cotutor.json 里的一条(显示名、头像、音色、开关、政策)+ 自己的目录与对话。出厂三位(数学、语文、英语)随包发布,init **拷贝**进你的老师们,改了就是你家的;`cotutor upgrade` 只换没改过的,改过的打印差异让你定。再加一位:
 
 ```sh
 cotutor add science-tutor --display 科学老师 --subject 科学 --avatar 🔬
 ```
 
+名字以 `-tutor` 结尾的是老师(有脸),其余是孩子看不到的工具人。没设头像时,语文、数学、英语老师用包里自带的
+出厂头像(包根 `avatars/`,三个木钉娃娃),别的老师显示学科首字。头像可以是 emoji,也可以是
+workspace 里的一张图(`avatars/<老师>.png`):用 [figshot](https://github.com/tarslab/figshot)
+`figshot pick --workspace ~/cotutor/<孩子>` 让孩子自己搭一个乐高人仔当老师,存盘直接落到这里。
+`cotutor.json` 里加一行 `"figshot": { "port": 8477 }`,孩子端首页就多一张「给老师们换个样子」,iPad 上点了直接进去(figshot 没开着时这张卡不出现)。
+
 或者家长端老师团页点「新老师」。没有注册表,删掉文件和那条配置就是删老师。
 
 `cotutor.json` 首行指向一份 JSON Schema(`.cotutor/cotutor.schema.json`),编辑器里有补全与说明。
@@ -47,14 +74,82 @@ import { deriveKidView, parseSections } from 'cotutor/lib';               // 转
 import { loadWorkspace } from 'cotutor/workspace';                        // 解析链 + 校验
 ```
 
-## 开发
+## 配置模型
+
+**缺省:应用直连百炼。** 嘴和脑都用家长端「首页」填的那份百炼按量 API Key 与业务空间 ID,存在本机 `~/.config/cotutor/bailian.json`(几个孩子的 workspace 共用)。老师用哪个模型写在 `cotutor.json` 的 `runtimes` 里:出厂的 `api`(`qwen3.8-max`,三位老师都用它)和 `api-flash`(`qwen3.8-flash`,便宜些;换之前先跑 `cotutor activity eval` 看例子过不过)。卡的配音、听写认字、口语单、画图也用这份 key。
+
+**key 只放 `~/.config/cotutor/`**,所有命令(`serve`、`send`、`replay`、`doctor`……)读同一处,环境变量(`DASHSCOPE_API_KEY` 之类)和别的工具的配置都不看:
+
+| 文件 | 内容 | 谁写 |
+|---|---|---|
+| `bailian.json` | `{"apiKey": "sk-…", "workspaceId": "llm-…"}`,百炼按量 | 家长端「首页」;没有浏览器的机器照格式手写,或从别的机器拷过来 |
+| `token-plan.json` | `{"apiKey": "sk-sp-…"}`,千问 Token Plan | 订了 Token Plan 的开发者手写;有它,Token Plan 有的模型先走它 |
+
+手写的存成 UTF-8(不带 BOM)。配了什么、通不通看 `cotutor doctor`(`--live` 真连一次)。
+
+换了运行时,之前的话题接不上,也不导入历史:孩子接着说会开新话题;换之前聊的话题不记账,家长端卡上标「换过运行时 · 不记账」,记录照样能看。模型、预算与老师运行时都在 workspace 的 `cotutor.json` 里,编辑器按首行 `$schema` 提供字段说明。
+
+`cotutor doctor` 检查缺失配置并给修复建议;`--live` 会实际连接服务。页面上的老师起不来时,先看 doctor 和 `conversations/<老师>/<日期>.<job>.err.log`。家长端与工作台需要访问锁时,运行 `cotutor pin` 设置本机 PIN。
+
+## 数据与升级
+
+默认 workspace 是 `~/cotutor/<孩子>/`:配置在 `cotutor.json`,老师在 `agents/<老师>.md`,activity 在 `agents/<老师>/activities/`,技能在 `.agents/skills/`,对话在 `conversations/`,账本在 `ledger/`,照片在 `captures/`,课包在 `bundles/`,首页在 `home/`。长期档案、记忆和日记在配置的 Obsidian vault,规则见 [obsidian 仓库设计](docs/obsidian仓库设计.md)。备份时保留整个 workspace 与 vault。
 
-改代码的看 [docs/开发者手册.md](docs/开发者手册.md)(检出、冒烟、iPad 真机)与 [CONTRIBUTING.md](CONTRIBUTING.md);设计与拍板在 [docs/](docs/)(产品规划、agent 层设计、契约草案)。
+```sh
+cotutor upgrade                      # 更新未修改的出厂老师、activity、主题与技能
+cotutor upgrade --config --dry-run    # 预览 cotutor.json 的迁移
+cotutor upgrade --config              # 执行配置迁移
+cotutor doctor
+```
+
+家长改过的老师与主题保留并显示差异;机器技能会随版本覆盖。配置迁移补缺,并更新未自定义的旧命令模板,保留自定义配置。升级程序后 `cotutor service restart`(在终端里跑的就重开 `serve`);换了 Node 版本、或包装到了别处,再 `cotutor service install` 一次。
+
+2026-10-30 之前建的 workspace,老师在 `.claude/agents/`、技能在 `.claude/skills/`。`cotutor upgrade`(或 `init`)先把它们原样挪到新位置,再照常升级;新位置已有同名的不挪,会点名。`.claude/` 里别的文件不动。
+
+### 旧 workspace 换运行时
+
+2026-11-02 起不再起命令行(Qwen Code;Claude CLI 更早就去掉了),老师只走应用直连百炼。2026-10-31 之前建的 workspace 缺省走 Qwen Code,doctor 会报「命令行运行时不再支持」:先 `cotutor upgrade --config` 补上出厂的 `api` / `api-flash`,把 `runtimes.default` 和 `tutors.*.runtime` 改成 `api`,在家长端「首页」填好百炼,再删掉 `qwen`、`qwen-flash`(或更早的 Claude)条目。换之前聊的话题照上面「配置模型」说的办:记录照样能看,不导入、不记账。旧 `proxy` 字段可删除,对应命令已移除。
+
+### 试用不进孩子的记录
+
+自己手动试功能时,命令加 `--sandbox`:第一次从真 workspace 分出一份到旁边的 `.sandbox/<目录名>/`(`~/cotutor/ray` → `~/cotutor/.sandbox/ray`)。老师、activity、首页、主题、课包照拷,对话、照片、听写、账本不带,vault 拷一份;试的对话、记忆、日记都写在这份里。页面标题前带「试用」,端口是真的那个 +1,可以同时开;自动记账关着(要试记账,家长端点「记账」)。
 
 ```sh
-pnpm i && pnpm typecheck && pnpm test
-node bin/cotutor.js --help        # bin 在仓库内直跑 src,零构建
-pnpm build && pnpm smoke          # 出厂检查:体检要发的那份
+cotutor serve --sandbox               # 试用的那份;没有就先分出来
+cotutor send math-tutor 你好 --sandbox
+cotutor serve --sandbox --fresh       # 丢掉试过的,从真 workspace 重新分(真的那边改了老师文件、vault 也用这个带过来)
 ```
 
-MIT。
+## 开发
+
+```sh
+pnpm i
+pnpm typecheck
+pnpm test
+node bin/cotutor.js --help        # 仓库内直跑 src,Node ≥ 22.18
+pnpm build
+pnpm build:stage                 # build 清空 dist 后重建舞台
+pnpm smoke                      # 检查待发布内容
+node bin/cotutor.js mock         # 假模型接口,查看前端
+```
+
+改卡片文档或技能生成代码后运行 `pnpm gen:skills`。开发约定与分模块验证见 [AGENTS.md](AGENTS.md) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+正式文档只保留以下六篇,历史讨论查 Git:
+
+- [iPad 与 iPhone](docs/iPad与iPhone.md)
+- [obsidian 仓库设计](docs/obsidian仓库设计.md)
+- [写提示词](docs/写提示词.md)
+- [卡片协议](docs/卡片协议.md)
+- [年级教学包](docs/年级教学包.md)
+- [词表](docs/词表.md)
+
+## 许可
+
+cotutor 按 Apache-2.0 加附加条件授权,全文见 [LICENSE](LICENSE)。白话说:
+
+- 家里自己用、自己改都行,几个孩子几个 workspace 都算自己家。
+- 替别的家庭或别人运营 cotutor(收不收钱都算),要先拿到书面许可。
+- 家长端页脚和工作台的 cotutor 标记不能去掉(自己家用也一样);主题、老师的名字与头像、标题照常改。
+
+这段只是说明,以 LICENSE 原文为准。要许可或商业授权,到仓库开 issue。

package/bin/cotutor.js

@@ -1,16 +1,26 @@
 #!/usr/bin/env node
 /**
- * 薄壳:仓库内直跑 src/cli/main.ts(Node ≥22.18 原生 type stripping,零构建迭代);
- * npm 包不含 src,回退到 dist/cli/main.js(tsc 产物,prepublishOnly 保证已构建)。
+ * 薄壳:仓库内直跑 src/app/cli/main.ts(Node ≥22.18 原生 type stripping,零构建迭代);
+ * npm 包不含 src,回退到 dist/app/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);
+// 版本不够先说清楚:不然源码直跑报「Unknown file extension .ts」,npm 装的报「没有 stripTypeScriptTypes」,都带一串栈(Windows 自带的常是 Node 18)
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 18)) {
+  console.error(`cotutor: 要 Node ≥ 22.18,这台是 ${process.versions.node}。到 https://nodejs.org 装新的 LTS 版,装好重开终端再跑。`);
+  process.exit(2);
+}
+
+// 托盘进程一直开着,走轻入口:不把所有命令都加载进来(src/app/cli/tray-run.ts)
+const argv = process.argv.slice(2);
+const name = argv[0] === 'tray' && argv[1] === 'run' ? 'tray-run' : 'main';
+const src = new URL(`../src/app/cli/${name}.ts`, import.meta.url);
+const entry = existsSync(fileURLToPath(src)) ? src : new URL(`../dist/app/cli/${name}.js`, import.meta.url);
 try {
   const { main } = await import(entry.href);
-  await main(process.argv.slice(2));
+  await main(argv);
 } catch (err) {
   console.error(`cotutor: 内部错误:${err?.stack ?? err}`);
   process.exitCode = 4;

package/cards/canvas/card.css

@@ -0,0 +1,8 @@
+/* 画板(cards/canvas/card.md):题目 + 「点开画一画」;交过之后是缩略图;舞台是 iframe 里的工作台 */
+/* 画板 */
+.c.c-canvas { gap:8px; }
+.c.c-canvas .cp { font-weight:600; } .c.c-canvas .cb { border:2px dashed var(--tint-plum-head); border-radius:12px; padding:22px 12px; text-align:center; color:var(--tint-plum-head); background:#fff; white-space:normal; }
+.c.c-canvas .th { position:relative; border-radius:12px; overflow:hidden; background:#fff; border:1px solid var(--tint-plum-line); }
+.c.c-canvas .th img { display:block; width:100%; max-height:240px; object-fit:contain; }
+.c.c-canvas .th.base img { opacity:.7; }
+.c.c-canvas .th .pl { position:absolute; right:10px; bottom:10px; background:#000000aa; color:#fff; border-radius:14px; padding:3px 10px; font-size:13px; }

package/cards/canvas/card.md

@@ -0,0 +1,68 @@
+# canvas — 画板
+
+## 是什么
+
+孩子自己在上面画的一块板:笔、橡皮、黑红蓝三色、撤销、清空。可以给一幅底图(课包的终帧、几个骨架元素,或孩子刚拍的作业照片)让孩子在上面标画,也可以空白只给题目。「给老师看」会导出一张 png 给你。
+
+## 什么时候用 / 别用
+
+- 用:「画一画」「标出来」「圈出来」这类要孩子动手的题:画高、标直角、圈出错的那步。
+- 用:一节末尾,末句讲稿就是这个要求。
+- 用:上下文包里有 photos 时,把那张照片做底图,让孩子在自己的作业上圈出错的那道、把答案写上去。
+- 别用:答案是一个数或一个词 → 讲稿里问,孩子开口说;能选的 → `choice`。
+- 别用:一节里放两张画板。
+
+## 写法
+
+- 第一行是底,后面的行是题目。标签后面的词也可以当题目。
+- 底有四种:
+  - 课包 id:那幅图的终帧做底,孩子在上面标画。
+  - 一张图的路径:照 `photos:` 里那样的 `captures/…` 相对路径写,照片做底。
+  - 一段行内骨架 JSON:`{"skeletons":[…]}`,课包场景的元素写法(chalk),不超过 40 个。
+  - 什么底都没有:只写题目,就是空白画板。
+
+## 例子
+
+<!-- expect {"kind":"canvas","props":{"base":null,"prompt":"画一个三角形,标出它的一条高。"}} -->
+```canvas
+画一个三角形,标出它的一条高。
+```
+
+<!-- expect {"kind":"canvas","props":{"base":{"bundle":"2026-09-10-guilv"},"prompt":"把每次少的那个数圈出来。"}} -->
+```canvas
+2026-09-10-guilv
+把每次少的那个数圈出来。
+```
+
+<!-- expect {"kind":"canvas","props":{"base":{"image":"captures/2026-09-14/1620-1.jpg"},"prompt":"把算错的那道圈出来。"}} -->
+```canvas
+captures/2026-09-14/1620-1.jpg
+把算错的那道圈出来。
+```
+
+## 反例
+
+行内骨架不是合法 JSON,解析不成:
+
+<!-- expect {"kind":"text","warning":true} -->
+```canvas
+{"skeletons": [
+```
+
+## 孩子看到什么
+
+紫色卡:题目 + 「点开画一画」(照片做底的,卡上先是那张照片的小图)。点开铺满整屏:顶栏是题目一行和「给老师看」;左边一列七个大钮(笔 / 橡皮 / 黑红蓝 / 撤销 / 清空),最底下是你的小头像;你给的底图是灰的。
+
+他画的时候可以按住你的小头像说话,嘴看着画接一句,不交给你。嘴有时也会主动看着画说一句、问一句。轻点「给老师看」是交画;按住它说话,是画和这句话一起交给你。
+
+交过之后卡上就是孩子画的那张图,锁住了,只能看、不能再画;要他再画,出一张新卡。
+
+## 你会收回什么
+
+`<job>/<n> canvas「题目」 画了 12 笔(红 8、蓝 4),画了约 3 分钟,清空重画过 1 次,清掉的那几版:/…/captures/2026-09-10/1621-2.jpg(用 Read 看),图:/…/conversations/math-tutor/2026-09-10.1620-1.cards/3.png(用 Read 看)`。没清空过就没有那一段。
+
+图是绝对路径,交了画的那轮有 Read,先看图再回;看不了图就靠笔数。他画的时候说过的话在上下文包 `live:` 的 `draw:` 里。
+
+## 状态的形状
+
+`{"ink": [...], "image": "conversations/…/3.png", "cleared": [{"at": …, "from": …, "strokes": 12, "image": "captures/…jpg"}]}` —— 孩子画的元素(画板的 ink 层)、导出的 png 路径(服务端写)、清空过的几版(清空的时刻、那一版第一笔的时刻、几笔、清空前存的图)。

package/cards/choice/card.css

@@ -0,0 +1,18 @@
+/* 选择题(cards/choice/card.md):紧凑态只读的选项行;舞台里的大按钮 .so */
+/* 选择:问题 + 选项;短选项横排成胶囊;选了的紫 */
+.c.c-choice { gap:8px; }
+.ch-q { font-weight:600; }
+.ch-os { display:flex; flex-direction:column; gap:8px; }
+.ch-os.short { flex-direction:row; flex-wrap:wrap; }
+.ch-os.short .ch-o { flex:1 1 auto; min-width:88px; }
+.ch-o { display:flex; align-items:center; gap:10px; padding:10px 14px; border-radius:12px; background:#ffffff; border:2px solid #ece8de; font-size:16px; }
+.ch-o i { flex:0 0 auto; width:24px; height:24px; border-radius:50%; border:2px solid #d8d3c6; background:#fff; display:grid; place-items:center; font-style:normal; font-size:12px; font-weight:700; color:var(--dim); }
+.ch-o.on { border-color:var(--tint-plum-head); background:var(--tint-plum-bg); }
+.ch-o.on i { background:var(--tint-plum-head); border-color:var(--tint-plum-head); color:#fff; }
+/* 舞台 */
+.sq { font-size:22px; font-weight:600; line-height:1.5; }
+.so { display:flex; align-items:center; gap:14px; padding:16px 18px; border-radius:16px; background:#ffffff; border:2px solid #ece8de; font-size:20px; text-align:left; width:100%; transition:transform .1s; }
+.so:active { transform:scale(.985); }
+.so i { flex:0 0 auto; width:34px; height:34px; border-radius:50%; border:2px solid #d8d3c6; background:#fff; display:grid; place-items:center; font-style:normal; font-size:15px; font-weight:700; color:var(--dim); }
+.so.on { border-color:var(--tint-plum-head); background:var(--tint-plum-bg); }
+.so.on i { background:var(--tint-plum-head); border-color:var(--tint-plum-head); color:#fff; }