create-ccc-tutor 0.2.0 → 0.3.0

package/README.md

@@ -23,12 +23,25 @@ course/
 
 `course/course_code(example)/` 是带两个示例课件的样板，复制改名即可开始。
 
+## 更新已安装的环境
+
+已经装过、想升级到新版（拿到新功能/修复，如 PDF 看图与检索引擎）时，在项目目录里跑：
+
+```
+npx create-ccc-tutor@latest --update
+```
+
+`--update` 会更新框架、技能与功能文件，但**保护你的用户数据**：`course/` 课件、`.harness/state/install.json` 配置、`constitution.md` 项目身份都不会被覆盖。
+
+> 不加 `--update` 直接重装会跳过所有已存在文件（改过的技能不会更新，等于半更新）；检测到老环境时安装器会提示你改用 `--update`。
+
 ## 选项
 
 | 选项 | 作用 |
 |---|---|
 | `--dry-run` | 只预览要写哪些文件，不实际写入 |
-| `--force` | 覆盖已存在的同名文件 |
+| `--update` | 更新已装环境：覆盖框架/技能/功能，但保护 `course/`、`install.json`、`constitution.md` |
+| `--force` | 全量覆盖所有已存在文件（含用户配置，慎用） |
 
 ## 要求
 

package/bin/cli.js

@@ -6,6 +6,7 @@ const path = require("path");
 const argv = process.argv.slice(2);
 const dryRun = argv.includes("--dry-run");
 const force = argv.includes("--force");
+const update = argv.includes("--update");
 
 const SRC = path.join(__dirname, "..", "template");
 const DEST = process.cwd();
@@ -15,8 +16,28 @@ function destName(name) {
   return name === "gitignore" ? ".gitignore" : name;
 }
 
+// --update 模式下「保护」的用户数据/配置：即使已存在也绝不覆盖（除非 --force 全量重置）。
+// 这样老环境能更新框架（技能/脚本/文档/引擎），又不会冲掉用户的课件和项目身份。
+const PROTECTED_FILES = [
+  ".harness/state/install.json", // 用户的科目/配置（/init 结果）
+  "constitution.md",             // 项目身份（/init 填的槽位）
+];
+const PROTECTED_DIRS = [
+  "course", // 用户的课件与题目，整棵子树都不动
+];
+
+function relPosix(p) {
+  return path.relative(DEST, p).split(path.sep).join("/");
+}
+function isProtected(absDest) {
+  const rel = relPosix(absDest);
+  if (PROTECTED_FILES.includes(rel)) return true;
+  return PROTECTED_DIRS.some((d) => rel === d || rel.startsWith(d + "/"));
+}
+
 let written = 0;
 let skipped = 0;
+let protectedCount = 0;
 
 function copyDir(src, dest) {
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -26,21 +47,38 @@ function copyDir(src, dest) {
       if (!dryRun) fs.mkdirSync(d, { recursive: true });
       copyDir(s, d);
     } else {
-      const rel = path.relative(DEST, d);
-      if (fs.existsSync(d) && !force) {
-        console.log(`  跳过（已存在，用 --force 覆盖）: ${rel}`);
-        skipped++;
-        continue;
+      const rel = relPosix(d);
+      const exists = fs.existsSync(d);
+      if (exists && !force) {
+        if (update) {
+          // 更新模式：保护用户数据，其余框架文件覆盖
+          if (isProtected(d)) {
+            console.log(`  保护（不覆盖用户文件）: ${rel}`);
+            protectedCount++;
+            continue;
+          }
+          console.log(`  ${dryRun ? "[预览] " : ""}更新: ${rel}`);
+        } else {
+          // 默认模式（全新安装）：已存在就跳过，避免误覆盖
+          console.log(`  跳过（已存在；更新用 --update，全量覆盖用 --force）: ${rel}`);
+          skipped++;
+          continue;
+        }
+      } else {
+        console.log(`  ${dryRun ? "[预览] " : ""}写入: ${rel}`);
       }
-      console.log(`  ${dryRun ? "[预览] " : ""}写入: ${rel}`);
       if (!dryRun) fs.copyFileSync(s, d);
       written++;
     }
   }
 }
 
+const hasExistingInstall = fs.existsSync(
+  path.join(DEST, ".harness", "state", "install.json")
+);
+const mode = force ? "全量覆盖 (--force)" : update ? "更新 (--update)" : "全新安装";
 console.log(
-  `\nCCC-tutor 安装到: ${DEST}${dryRun ? "  (--dry-run 预览，不写文件)" : ""}\n`
+  `\nCCC-tutor ${mode} → ${DEST}${dryRun ? "  (--dry-run 预览，不写文件)" : ""}\n`
 );
 
 if (!fs.existsSync(SRC)) {
@@ -48,6 +86,16 @@ if (!fs.existsSync(SRC)) {
   process.exit(1);
 }
 
+// 检测到老环境却没带 --update/--force：提示用户，避免「只新增、改过的技能被跳过」的半更新。
+if (hasExistingInstall && !update && !force) {
+  console.log(
+    "⚠️  检测到这里已经装过 CCC-tutor。直接安装会跳过所有已存在文件（改过的技能不会更新）。\n" +
+      "    想更新到新版请改用：  npx create-ccc-tutor@latest --update\n" +
+      "    （--update 会更新框架与功能，但保护你的 course/ 课件、install.json、constitution.md）\n" +
+      "    仍要按全新安装继续会跳过已存在文件。\n"
+  );
+}
+
 copyDir(SRC, DEST);
 
 // 给 shell 脚本加执行权限
@@ -62,8 +110,20 @@ if (!dryRun) {
   if (fs.existsSync(codexInstall)) fs.chmodSync(codexInstall, 0o755);
 }
 
-console.log(`
-✓ 完成！写入 ${written} 个文件${skipped ? `，跳过 ${skipped} 个已存在文件（加 --force 覆盖）` : ""}。
+const tail = [];
+if (skipped) tail.push(`跳过 ${skipped} 个已存在文件（加 --update 更新 / --force 全量覆盖）`);
+if (protectedCount) tail.push(`保护 ${protectedCount} 个用户文件未动`);
+
+if (update) {
+  console.log(`
+✓ 更新完成！更新 ${written} 个文件${tail.length ? "，" + tail.join("，") : ""}。
+
+已保护你的 course/ 课件、install.json 配置、constitution.md 项目身份。
+框架、技能与功能（含 PDF 看图/检索引擎）已更新到本版。
+`);
+} else {
+  console.log(`
+✓ 完成！写入 ${written} 个文件${tail.length ? "，" + tail.join("，") : ""}。
 
 接下来：
   1. 把课件放进  course/<科目>/slide/ ，题目放进  course/<科目>/exam/
@@ -74,3 +134,4 @@ console.log(`
 
 已预填 install.json，首次启动无需走 /init 配置。
 `);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ccc-tutor",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "一行命令装好的多科目 AI 复习助手（基于 CCC-MAGI）：slide 查课件、exam 解题目，严格依据课件、标出处、不编造。",
   "bin": {
     "create-ccc-tutor": "bin/cli.js"