@aiyiran/myclaw 1.1.64 → 1.1.66

package/skills/yiran-course-template-pipeline/references/student-example.json

@@ -34,5 +34,5 @@
     }
   ],
   "示例区标题": "示范样例",
-  "示例页面文件": "example.html"
-}
+  "示例页面文件": "__demo__.html"
+}

package/skills/yiran-course-template-pipeline/references/student-fields.md

@@ -175,7 +175,7 @@
 
 例如：
 ```json
-"示例页面文件": "example.html"
+"示例页面文件": "__demo__.html"
 ```
 
 ---

package/skills/yiran-course-template-pipeline/scripts/identify_template.py

@@ -7,7 +7,6 @@ identify_template.py
 
 写入字段：
   _id       : 8位十六进制，首次颁发，后续不变
-  _version  : 首次=1，更新=已有版本+1
   任务类别  : 校准后的系列（A/B/C）
   任务编号  : 校准后的3位编号（100起）
 
@@ -163,7 +162,6 @@ def main():
 
     # ── 3. 写回 __teacher__.json ───────────────────────────────────────────
     teacher['_id'] = tid
-    teacher['_version'] = new_version
     teacher['任务类别'] = category
     teacher['任务编号'] = f'{calibrated:03d}'
     save_json(teacher_path, teacher)

package/skills/yiran-course-template-pipeline/scripts/move_template_task.py

@@ -42,6 +42,19 @@ def sanitize_name(name: str) -> str:
     return re.sub(r'[/\\ ]', '_', str(name).strip())
 
 
+def get_latest_version_num(folder: Path) -> int:
+    """返回 folder 下最大的版本号，没有则返回 0"""
+    if not folder.exists():
+        return 0
+    max_v = 0
+    for d in folder.iterdir():
+        if d.is_dir():
+            m = re.match(r'^v(\d+)$', d.name)
+            if m:
+                max_v = max(max_v, int(m.group(1)))
+    return max_v
+
+
 def main():
     if len(sys.argv) < 2:
         print('用法: python3 move_template_task.py <模板目录> [目标根目录]')
@@ -69,10 +82,10 @@ def main():
     category = teacher.get('任务类别', '').upper()
     number = teacher.get('任务编号', '100')
     name = sanitize_name(teacher.get('任务名称', 'untitled'))
-    version = teacher.get('_version', 1)
 
     folder_name = f'{category.lower()}{number}_{name}'
-    version_str = f'v{version}'
+    next_version = get_latest_version_num(target_root / folder_name) + 1
+    version_str = f'v{next_version}'
     target_dir = target_root / folder_name / version_str
 
     if target_dir.exists():

package/skills/yiran-course-template-pipeline/scripts/release_template.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""
+release_template.py
+
+一键发布脚本：合并 build → move → publish 三个步骤。
+
+传入原始模板目录（或已有 vN/ 目录），自动执行：
+  Step 1: build_template_views.py <source_dir>   → 生成/更新 HTML 视图
+  Step 2: move_template_task.py <source_dir>     → 创建新版本目录 vN+1/
+  Step 3: publish_template.py <templates/xxx/>   → 上传 CDN + 上传 index
+
+用法：
+    python3 scripts/release_template.py <模板目录>
+"""
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+BUILD_SCRIPT   = ROOT / 'scripts' / 'build_template_views.py'
+MOVE_SCRIPT    = ROOT / 'scripts' / 'move_template_task.py'
+PUBLISH_SCRIPT = ROOT / 'scripts' / 'publish_template.py'
+TEMPLATES_DIR  = ROOT / 'templates'
+
+
+def load_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception:
+        return {}
+
+
+def sanitize_name(name: str) -> str:
+    return re.sub(r'[/\\ ]', '_', str(name).strip())
+
+
+def main():
+    if len(sys.argv) < 2:
+        print('用法: python3 scripts/release_template.py <模板目录>')
+        sys.exit(1)
+
+    source_dir = Path(sys.argv[1]).expanduser().resolve()
+
+    if not source_dir.is_dir():
+        print(f'❌ 目录不存在: {source_dir}')
+        sys.exit(1)
+
+    teacher_path = source_dir / '__teacher__.json'
+    if not teacher_path.exists():
+        print(f'❌ 找不到 __teacher__.json: {teacher_path}')
+        sys.exit(1)
+
+    # ── Step 1: Build HTML views ──────────────────────────────────────────
+    print('\n══ Step 1: 生成 HTML 视图 ══════════════════════════════')
+    subprocess.run([sys.executable, str(BUILD_SCRIPT), str(source_dir)], check=True)
+
+    # ── Step 2: Move to templates/ ────────────────────────────────────────
+    print('\n══ Step 2: 移入 templates/ ═════════════════════════════')
+    subprocess.run([sys.executable, str(MOVE_SCRIPT), str(source_dir)], check=True)
+
+    # ── Determine publish target from updated teacher.json ────────────────
+    teacher = load_json(teacher_path)
+    category = teacher.get('任务类别', '').upper()
+    number   = teacher.get('任务编号', '100')
+    name     = sanitize_name(teacher.get('任务名称', 'untitled'))
+    folder_name = f'{category.lower()}{number}_{name}'
+    publish_target = TEMPLATES_DIR / folder_name
+
+    if not publish_target.is_dir():
+        print(f'❌ 发布目标目录不存在: {publish_target}')
+        sys.exit(1)
+
+    # ── Step 3: Publish to CDN ────────────────────────────────────────────
+    print('\n══ Step 3: 上传 CDN ════════════════════════════════════')
+    subprocess.run([sys.executable, str(PUBLISH_SCRIPT), str(publish_target)], check=True)
+
+    print('\n✅ 发布完成！')
+    print(f'   模板目录: {publish_target}')
+
+
+if __name__ == '__main__':
+    main()

package/skills/yiran-course-template-pipeline/template-index.json

@@ -1,5 +1,5 @@
 {
-  "index_updated_at": "2026-04-22T15:32:50Z",
+  "index_updated_at": "2026-04-22T17:22:47Z",
   "templates": {
     "696de592": {
       "id": "696de592",
@@ -7,9 +7,9 @@
       "编号": "100",
       "名称": "给依然老师设计一个AI画像",
       "文件夹名": "a100_给依然老师设计一个AI画像",
-      "version": "v1",
-      "路径": "templates/a100_给依然老师设计一个AI画像/v1",
-      "入口文件": "templates/a100_给依然老师设计一个AI画像/v1/index.html",
+      "version": "v5",
+      "路径": "templates/a100_给依然老师设计一个AI画像/v5",
+      "入口文件": "templates/a100_给依然老师设计一个AI画像/v5/index.html",
       "一句话说明": "先让 AI 生成一个老师形象，再用网页把它展示出来，重点练习描述和小修改。",
       "主能力标签": "表达构建",
       "任务类型标签": "视听表达",
@@ -26,7 +26,7 @@
         "表达构建",
         "视听表达"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:22:41Z"
     },
     "d0ff11ee": {
       "id": "d0ff11ee",
@@ -34,9 +34,9 @@
       "编号": "101",
       "名称": "做3张同主题图片",
       "文件夹名": "a101_做3张同主题图片",
-      "version": "v1",
-      "路径": "templates/a101_做3张同主题图片/v1",
-      "入口文件": "templates/a101_做3张同主题图片/v1/__demo__.html",
+      "version": "v2",
+      "路径": "templates/a101_做3张同主题图片/v2",
+      "入口文件": "templates/a101_做3张同主题图片/v2/index.html",
       "一句话说明": "先确定一个有趣的主题，再用 AI 生成 3 张风格统一、但情节不同的系列图片。",
       "主能力标签": "表达构建",
       "任务类型标签": "视听表达",
@@ -52,7 +52,7 @@
         "表达构建",
         "视听表达"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:15:44Z"
     },
     "d48d94b6": {
       "id": "d48d94b6",
@@ -60,9 +60,9 @@
       "编号": "102",
       "名称": "图片资源展示",
       "文件夹名": "a102_图片资源展示",
-      "version": "v1",
-      "路径": "templates/a102_图片资源展示/v1",
-      "入口文件": "templates/a102_图片资源展示/v1/index.html",
+      "version": "v2",
+      "路径": "templates/a102_图片资源展示/v2",
+      "入口文件": "templates/a102_图片资源展示/v2/index.html",
       "一句话说明": "把图片放到网页上，做成一个方便点击查看的小展示页。",
       "主能力标签": "第二能力：表达构建",
       "任务类型标签": "视听表达",
@@ -78,7 +78,7 @@
         "第二能力：表达构建",
         "视听表达"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:15:47Z"
     },
     "e1aab9bf": {
       "id": "e1aab9bf",
@@ -86,9 +86,9 @@
       "编号": "103",
       "名称": "做一个介绍页面",
       "文件夹名": "a103_做一个介绍页面",
-      "version": "v1",
-      "路径": "templates/a103_做一个介绍页面/v1",
-      "入口文件": "templates/a103_做一个介绍页面/v1/__demo__.html",
+      "version": "v2",
+      "路径": "templates/a103_做一个介绍页面/v2",
+      "入口文件": "templates/a103_做一个介绍页面/v2/index.html",
       "一句话说明": "用一张图片加一段文字，做一个属于自己的介绍页面，练一练图文组合的技巧。",
       "主能力标签": "表达构建",
       "任务类型标签": "视听表达",
@@ -104,7 +104,7 @@
         "表达构建",
         "视听表达"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:15:55Z"
     },
     "3c61e07d": {
       "id": "3c61e07d",
@@ -112,9 +112,9 @@
       "编号": "104",
       "名称": "做一个会出招的神奇按钮",
       "文件夹名": "a104_做一个会出招的神奇按钮",
-      "version": "v1",
-      "路径": "templates/a104_做一个会出招的神奇按钮/v1",
-      "入口文件": "templates/a104_做一个会出招的神奇按钮/v1/index.html",
+      "version": "v3",
+      "路径": "templates/a104_做一个会出招的神奇按钮/v3",
+      "入口文件": "templates/a104_做一个会出招的神奇按钮/v3/index.html",
       "一句话说明": "先试试按钮效果，再改一点，最后加一个你自己的新按钮。",
       "主能力标签": "迭代推进",
       "任务类型标签": "游戏机制",
@@ -132,7 +132,7 @@
         "迭代推进",
         "游戏机制"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:22:44Z"
     },
     "c360e192": {
       "id": "c360e192",
@@ -140,9 +140,9 @@
       "编号": "100",
       "名称": "做一个按钮页面",
       "文件夹名": "b100_做一个按钮页面",
-      "version": "v1",
-      "路径": "templates/b100_做一个按钮页面/v1",
-      "入口文件": "templates/b100_做一个按钮页面/v1/__demo__.html",
+      "version": "v2",
+      "路径": "templates/b100_做一个按钮页面/v2",
+      "入口文件": "templates/b100_做一个按钮页面/v2/index.html",
       "一句话说明": "亲手做一个会“变魔术”的按钮，学习网页是如何接收指令并产生变化的。",
       "主能力标签": "表达构建",
       "任务类型标签": "游戏机制",
@@ -158,7 +158,35 @@
         "表达构建",
         "游戏机制"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:16:00Z"
+    },
+    "8a7e39dd": {
+      "id": "8a7e39dd",
+      "系列": "B",
+      "编号": "101",
+      "名称": "会跳舞的机器人",
+      "文件夹名": "b101_会跳舞的机器人",
+      "version": "v2",
+      "路径": "templates/b101_会跳舞的机器人/v2",
+      "入口文件": "templates/b101_会跳舞的机器人/v2/index.html",
+      "一句话说明": "先把机器人视频放到网页上，再配上音乐，最后调一调播放效果，让机器人更像在跳舞。",
+      "主能力标签": "表达构建",
+      "任务类型标签": "视听表达",
+      "关键词": [
+        "b101_会跳舞的机器人",
+        "先把机器人视频放到网页上，再配上音乐，最后调一调播放效果，让机器人更像在跳舞。",
+        "已经能开始动手，但还不太会把多种素材组织到一起的学生",
+        "会做简单网页，但还不太会处理视频、音乐和动画配合的学生",
+        "想从静态页面进入多媒体网页表达的学生",
+        "把机器人视频放进网页中",
+        "让视频和音乐形成基本配合",
+        "尝试处理循环播放和播放节奏",
+        "让网页从静态展示变成更有动态感的作品",
+        "会跳舞的机器人",
+        "表达构建",
+        "视听表达"
+      ],
+      "updated_at": "2026-04-22T16:52:16Z"
     },
     "6490af0a": {
       "id": "6490af0a",
@@ -166,9 +194,9 @@
       "编号": "100",
       "名称": "给小组作品做一次小修改",
       "文件夹名": "c100_给小组作品做一次小修改",
-      "version": "v1",
-      "路径": "templates/c100_给小组作品做一次小修改/v1",
-      "入口文件": "templates/c100_给小组作品做一次小修改/v1/index.html",
+      "version": "v2",
+      "路径": "templates/c100_给小组作品做一次小修改/v2",
+      "入口文件": "templates/c100_给小组作品做一次小修改/v2/index.html",
       "一句话说明": "先看这 3 个小组作品，找出一个你最想改的小地方，再把这个修改要求说给 AI。",
       "主能力标签": "问题判断",
       "任务类型标签": "改编优化",
@@ -186,7 +214,7 @@
         "问题判断",
         "改编优化"
       ],
-      "updated_at": "2026-04-22T11:09:12Z"
+      "updated_at": "2026-04-22T17:16:03Z"
     }
   }
 }

package/skills/yiran-course-template-pipeline/template-index.md

@@ -4,63 +4,72 @@
 
 ## A100 给依然老师设计一个AI画像
 - ID：696de592
-- 版本：v1
-- 路径：templates/a100_给依然老师设计一个AI画像/v1
-- 入口文件：templates/a100_给依然老师设计一个AI画像/v1/index.html
+- 版本：v5
+- 路径：templates/a100_给依然老师设计一个AI画像/v5
+- 入口文件：templates/a100_给依然老师设计一个AI画像/v5/index.html
 - 主能力标签：表达构建
 - 任务类型标签：视听表达
 - 关键词：a100_给依然老师设计一个AI画像, 先让 AI 生成一个老师形象，再用网页把它展示出来，重点练习描述和小修改。, 初次接触, 需要明确目标, 持续迭代, 围绕明确对象生成形象, 把人物图片放进网页中完成展示, 通过小幅修改让作品逐步变好, 给依然老师设计一个AI画像, 表达构建, 视听表达
 
 ## A101 做3张同主题图片
 - ID：d0ff11ee
-- 版本：v1
-- 路径：templates/a101_做3张同主题图片/v1
-- 入口文件：templates/a101_做3张同主题图片/v1/__demo__.html
+- 版本：v2
+- 路径：templates/a101_做3张同主题图片/v2
+- 入口文件：templates/a101_做3张同主题图片/v2/index.html
 - 主能力标签：表达构建
 - 任务类型标签：视听表达
 - 关键词：a101_做3张同主题图片, 先确定一个有趣的主题，再用 AI 生成 3 张风格统一、但情节不同的系列图片。, 初次接触, 需要明确目标, 练习通过提示词锁定画面风格, 理解作品一致性的价值, 初步接触提示词的模块化修改, 做3张同主题图片, 表达构建, 视听表达
 
 ## A102 图片资源展示
 - ID：d48d94b6
-- 版本：v1
-- 路径：templates/a102_图片资源展示/v1
-- 入口文件：templates/a102_图片资源展示/v1/index.html
+- 版本：v2
+- 路径：templates/a102_图片资源展示/v2
+- 入口文件：templates/a102_图片资源展示/v2/index.html
 - 主能力标签：第二能力：表达构建
 - 任务类型标签：视听表达
 - 关键词：a102_图片资源展示, 把图片放到网页上，做成一个方便点击查看的小展示页。, 刚开始接触网页展示的学生, 需要先从添加素材开始动手的学生, 把本地图片放进网页里, 理解图片展示卡片的基本结构, 为后续继续扩充图片资源做准备, 图片资源展示, 第二能力：表达构建, 视听表达
 
 ## A103 做一个介绍页面
 - ID：e1aab9bf
-- 版本：v1
-- 路径：templates/a103_做一个介绍页面/v1
-- 入口文件：templates/a103_做一个介绍页面/v1/__demo__.html
+- 版本：v2
+- 路径：templates/a103_做一个介绍页面/v2
+- 入口文件：templates/a103_做一个介绍页面/v2/index.html
 - 主能力标签：表达构建
 - 任务类型标签：视听表达
 - 关键词：a103_做一个介绍页面, 用一张图片加一段文字，做一个属于自己的介绍页面，练一练图文组合的技巧。, 初次接触网页制作, 有一点基础想练排版, 图片与文字的组合方式, 网页结构的基本层次感, 排版的视觉优先级, 做一个介绍页面, 表达构建, 视听表达
 
 ## A104 做一个会出招的神奇按钮
 - ID：3c61e07d
-- 版本：v1
-- 路径：templates/a104_做一个会出招的神奇按钮/v1
-- 入口文件：templates/a104_做一个会出招的神奇按钮/v1/index.html
+- 版本：v3
+- 路径：templates/a104_做一个会出招的神奇按钮/v3
+- 入口文件：templates/a104_做一个会出招的神奇按钮/v3/index.html
 - 主能力标签：迭代推进
 - 任务类型标签：游戏机制
 - 关键词：a104_做一个会出招的神奇按钮, 先试试按钮效果，再改一点，最后加一个你自己的新按钮。, 想先动手再思考的学生, 刚开始学网页互动的学生, 容易卡在空白页不知从哪开始的学生, 先运行现成示例，快速进入任务, 从已有功能里挑一个做小改动, 理解一个按钮对应一个功能, 把新增功能接入现有页面结构, 做一个会出招的神奇按钮, 迭代推进, 游戏机制
 
 ## B100 做一个按钮页面
 - ID：c360e192
-- 版本：v1
-- 路径：templates/b100_做一个按钮页面/v1
-- 入口文件：templates/b100_做一个按钮页面/v1/__demo__.html
+- 版本：v2
+- 路径：templates/b100_做一个按钮页面/v2
+- 入口文件：templates/b100_做一个按钮页面/v2/index.html
 - 主能力标签：表达构建
 - 任务类型标签：游戏机制
 - 关键词：b100_做一个按钮页面, 亲手做一个会“变魔术”的按钮，学习网页是如何接收指令并产生变化的。, 喜欢做项目, 需要明确目标, 掌握基础的 JavaScript 点击事件绑定, 理解 HTML/CSS/JS 三者如何协作完成交互, 学习利用 CSS Class 切换来实现视觉变化, 做一个按钮页面, 表达构建, 游戏机制
 
+## B101 会跳舞的机器人
+- ID：8a7e39dd
+- 版本：v2
+- 路径：templates/b101_会跳舞的机器人/v2
+- 入口文件：templates/b101_会跳舞的机器人/v2/index.html
+- 主能力标签：表达构建
+- 任务类型标签：视听表达
+- 关键词：b101_会跳舞的机器人, 先把机器人视频放到网页上，再配上音乐，最后调一调播放效果，让机器人更像在跳舞。, 已经能开始动手，但还不太会把多种素材组织到一起的学生, 会做简单网页，但还不太会处理视频、音乐和动画配合的学生, 想从静态页面进入多媒体网页表达的学生, 把机器人视频放进网页中, 让视频和音乐形成基本配合, 尝试处理循环播放和播放节奏, 让网页从静态展示变成更有动态感的作品, 会跳舞的机器人, 表达构建, 视听表达
+
 ## C100 给小组作品做一次小修改
 - ID：6490af0a
-- 版本：v1
-- 路径：templates/c100_给小组作品做一次小修改/v1
-- 入口文件：templates/c100_给小组作品做一次小修改/v1/index.html
+- 版本：v2
+- 路径：templates/c100_给小组作品做一次小修改/v2
+- 入口文件：templates/c100_给小组作品做一次小修改/v2/index.html
 - 主能力标签：问题判断
 - 任务类型标签：改编优化
 - 关键词：c100_给小组作品做一次小修改, 先看这 3 个小组作品，找出一个你最想改的小地方，再把这个修改要求说给 AI。, 已经能看懂图片内容，但不太会说哪里有问题的学生, 会说喜欢或不喜欢，但不太会提出具体修改点的学生, 已经能做第一版作品，想练习小步修改的学生, 先发现一个具体问题, 把大问题收成一个最小修改点, 用简单的话把修改要求说清楚, 比较修改前后有没有更接近自己的想法, 给小组作品做一次小修改, 问题判断, 改编优化

package/skills/yiran-playground-template-use/scripts/deploy_to_workspace.py

@@ -144,17 +144,10 @@ def choose_entry_file(target_dir: Path):
 
 def build_instance_name(source_dir: Path, remix_dir: Path):
     import re
-    # source_dir 可能是版本子目录（如 v1/），拆出业务名和版本号
-    if re.match(r'^v\d+$', source_dir.name):
-        folder_name = source_dir.parent.name
-        version_str = source_dir.name
-    else:
-        folder_name = source_dir.name
-        version_str = ''
-    now = datetime.now()
-    base = f"{now.strftime('%m%d')}_{folder_name}_{now.strftime('%H%M')}"
-    if version_str:
-        base = f"{base}_{version_str}"
+    folder_name = source_dir.parent.name if re.match(r'^v\d+$', source_dir.name) else source_dir.name
+    # 去掉 a104_ 这样的系列编号前缀，只保留业务名
+    name = re.sub(r'^[a-z]+\d+_', '', folder_name) or folder_name
+    base = f"{name}_{datetime.now().strftime('%H%M')}"
     candidate = base
     suffix = 2
     while (remix_dir / candidate).exists():

package//347/264/257/345/220/220/350/241/200/345/220/216/347/232/204/346/200/273/347/273/223.md

@@ -0,0 +1,196 @@
+# 模板系统设计经验总结
+
+## 一、版本化目录结构
+
+### 问题
+CDN 有缓存，更新模板后旧内容仍被访问。
+
+### 方案
+```
+templates/
+  a104_做一个会出招的神奇按钮/
+    v1/   ← 每次更新递增版本号，CDN 路径变了，缓存自然失效
+    v2/
+```
+
+### 经验
+- **本地只保留一个版本**：下载新版前先删旧版目录，避免就绪状态歧义
+- **目录存在即就绪**：不需要额外标记文件（`.sync-done`），目录本身就是状态
+- **原子性替换**：下载到 `.tmp/`，完成后 `rename .tmp/ → v1/`，不会出现"半完成"状态
+
+---
+
+## 二、稳定 ID 设计
+
+### 问题
+模板可能改编号（A100 → A105）、改名，如果用路径/编号做唯一标识会丢失对应关系。
+
+### 方案
+```json
+// __teacher__.json
+{
+  "_id": "696de592",   // 8位hex，颁发一次永不变
+  "_version": 1        // 每次更新递增
+}
+```
+
+### 经验
+- ID 在 `move` 阶段颁发，之后不再改变
+- CDN index 以 `_id` 为 key（平铺字典），而不是 `{系列: {编号: record}}` 嵌套结构
+- 本地/CDN 比对：用 `_id` 找记录，再比较 `version` 字段判断是否需要更新
+
+---
+
+## 三、非阻塞同步 + 轮询进度
+
+### 问题
+下载几十个文件要几分钟，HTTP handler 不能阻塞。
+
+### 方案
+```python
+# 立刻写 index（前端列表立刻出现），然后后台下载
+with open(TEMPLATE_LOCAL_INDEX, 'w') as f:
+    json.dump(cdn_index, f)
+
+t = threading.Thread(target=_do_sync_templates, args=(...), daemon=True)
+t.start()
+self._send_json({'syncing': True, 'total': len(pending)})
+```
+前端每 3 秒轮询 `/api/sync-status`。
+
+### 经验
+- **先写 index 再下载**：用户立刻看到列表，下载在后台进行
+- **守卫变量防重复轮询**：`if (_pollTimer) return`
+- **轮询 vs WebSocket**：简单场景轮询够用，不要过度设计
+
+---
+
+## 四、前端就绪状态简化
+
+### 反面教材（复杂版）
+维护 `_readyFolders` Set + `_rowMap` + `updateActionBtns()` + 开屏预取状态，
+按钮 disabled/opacity 联动，约 40 行状态管理代码。
+
+### 正确做法（简单版）
+- 按钮永远可点
+- 点击后服务端检查就绪状态，未就绪返回 `{code: 'not_ready'}`
+- 前端只需在 `.then()` 里判断 `res.code === 'not_ready'` 显示提示
+
+```js
+if (res.code === 'not_ready') {
+  setFooterStatus('⟳ 模板文件下载中，完成后即可使用', '#f59e0b');
+}
+```
+
+### 经验
+**让服务端做校验，前端做展示**，不要在前端维护服务端状态的镜像。
+
+---
+
+## 五、同一文件存在两个副本
+
+### 问题
+`deploy_to_workspace.py` 存在于两个路径：
+- `.openclaw/skills/.../deploy_to_workspace.py` ← 服务端实际运行
+- `.openclaw/workspace-yiranclaw/myclaw/skills/.../deploy_to_workspace.py` ← 源文件
+
+`mc patch` 会用源文件覆盖服务端文件，导致修改被还原。
+
+### 经验
+- **改脚本必须改两处**，或者建立符号链接
+- 发现改动被还原时，先查是哪个路径在被覆盖，再两处同步修改
+
+---
+
+## 六、Pipeline 职责拆分
+
+### 原则：每个脚本只做一件事
+
+| 脚本 | 职责 |
+|------|------|
+| `identify_template.py` | 颁发 `_id`、校准编号、设置 `_version` |
+| `move_template_task.py` | 调用 identify、创建 `v{N}/` 子目录、复制文件 |
+| `build_template_index.py` | 扫描本地目录、生成 JSON index |
+| `publish_template.py` | 上传到 CDN（带版本路径）、上传 index |
+| `migrate_templates.py` | 一次性迁移旧结构到新结构 |
+
+### 经验
+- `move` 不再删除原文件夹（改为复制），避免误操作丢失源文件
+- 版本号在 `move` 阶段确定，`publish` 不决定版本号
+- 迁移脚本加 `--dry-run` 参数，先验证再执行
+
+---
+
+## 七、API 设计：参数复用代替接口重复
+
+### 问题
+"复制到 playgrounds" 和 "创建新 workspace" 流程完全相同，只是目标 workspace 名不同。
+
+### 反面做法
+新增 `/api/template/new-workspace` 接口，重复了 90% 的代码。
+
+### 正确做法
+```python
+# POST /api/template/deploy
+# body: {"folder": "...", "agent": "playgrounds"}  ← 已有 workspace
+# body: {"folder": "..."}                           ← 不传则自动生成唯一名
+agent_name = body.get('agent') or '{}-{}-{}'.format(series, version, hhmm)
+```
+
+### 经验
+**加参数，不加接口**。两个行为只有一个变量不同时，用参数区分而不是新建接口。
+
+---
+
+## 八、mc 命令扩展
+
+### 方法
+在 `index.js` 里添加两处：
+
+```js
+// 1. 路由
+} else if (command === 'sync-templates') {
+  runSyncTemplates();
+
+// 2. 函数（调本地 API，轮询进度）
+function runSyncTemplates() {
+  const http = require('http');
+  const apiPort = process.platform === 'linux' ? '8080' : '18800';
+  // apiGet → /api/sync-templates → 轮询 /api/sync-status
+}
+```
+
+### 经验
+- `mc` 命令本质是 Node.js 脚本，扩展成本极低
+- 本地 API 端口：Mac=18800，Linux=8080
+- 轮询用 `setTimeout` 递归，而不是 `setInterval`（更容易控制退出）
+
+---
+
+## 九、命名规范
+
+### 实例目录命名
+```
+{业务名}_{HH:MM}
+做一个会出招的神奇按钮_1911
+```
+
+### 新建 workspace 命名
+```
+{作品编号}-{版本号}-{小时分钟}
+a104-v1-1911
+→ workspace-a104-v1-1911
+```
+
+### 原则
+- 去掉冗余信息（日期、系列前缀 `a104` 在实例名里不需要）
+- 保留区分信息（时间保证唯一，版本号便于追溯）
+- 用 `-` 分隔 workspace 名的各段，用 `_` 分隔实例名各段
+
+---
+
+## 十、window.open vs window.location.href
+
+- `window.open('url', '_blank')` 会被浏览器弹窗拦截器阻止（非用户直接触发的点击）
+- setTimeout 内的跳转用 `window.location.href` 更可靠
+- 如果必须新标签，需要在用户点击的同步代码里调用 `window.open`