@aiyiran/myclaw 1.1.24 → 1.1.26

package/server/sync_workspace.py

@@ -51,10 +51,136 @@ SYNC_ARTIFACTS_JSON_TO_OSS = False
 
 
 # 忽略的目录名（路径中只要包含这些目录段就跳过）
-IGNORE_DIR_PATTERNS = {'.git', 'node_modules', '__pycache__', '.myclaw'}
+IGNORE_DIR_PATTERNS = {'.git', 'node_modules', '__pycache__', '.myclaw', '__history__', 'history'}
 
 # 忽略的文件名
-IGNORE_FILE_PATTERNS = {'.myclaw-sync.pid', '.DS_Store', '.gitignore', '.gitkeep'}
+IGNORE_FILE_PATTERNS = {'.myclaw-sync.pid', '.DS_Store', '.gitignore', '.gitkeep', 'history.json'}
+
+# 历史版本目录名和索引文件名
+HISTORY_DIR = "__history__"
+HISTORY_FILENAME = "history.json"
+
+# 回滚压制表：{ abs_path: 写入时间戳 }
+# 回滚时往 workspace 写文件会触发 on_modified，用此表跳过快照，避免产生多余版本
+_rollback_suppressed: dict = {}
+_ROLLBACK_SUPPRESS_TTL = 3.0  # 秒
+
+
+def _is_rollback_suppressed(abs_path: str) -> bool:
+    ts = _rollback_suppressed.get(abs_path)
+    if ts and time.time() - ts < _ROLLBACK_SUPPRESS_TTL:
+        return True
+    _rollback_suppressed.pop(abs_path, None)
+    return False
+
+
+def _load_history_json(history_json_path: str, workspace_id: str) -> dict:
+    if os.path.exists(history_json_path):
+        try:
+            with open(history_json_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            pass
+    return _empty_history(workspace_id)
+
+
+def save_history_version(workspace_id: str, relative_path: str, file_path: str):
+    """把当前文件内容作为新快照写入 __history__/vN/，并更新 history.json。"""
+    base_path = get_openclaw_path()
+    history_base = os.path.join(base_path, workspace_id, HISTORY_DIR)
+    history_json_path = os.path.join(history_base, HISTORY_FILENAME)
+
+    os.makedirs(history_base, exist_ok=True)
+
+    history_data = _load_history_json(history_json_path, workspace_id)
+
+    next_ver = history_data.get("next_version", 1)
+    ver_dir_name = f"v{next_ver}"
+
+    # 复制当前文件内容到 __history__/vN/<relative_path>
+    rel_parts = relative_path.replace("\\", "/").split("/")
+    dest_path = os.path.join(history_base, ver_dir_name, *rel_parts)
+    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+    try:
+        with open(file_path, "rb") as src, open(dest_path, "wb") as dst:
+            dst.write(src.read())
+    except Exception as e:
+        print(f"[history] 快照写入失败: {e}")
+        return
+
+    # 更新 next_version、records、current_versions
+    history_data["next_version"] = next_ver + 1
+    history_data["records"].append({
+        "version": next_ver,
+        "version_dir": ver_dir_name,
+        "path": relative_path,
+        "snapshot_at": now_iso()
+    })
+    if "current_versions" not in history_data:
+        history_data["current_versions"] = {}
+    history_data["current_versions"][relative_path] = next_ver
+
+    with open(history_json_path, "w", encoding="utf-8") as f:
+        json.dump(history_data, f, ensure_ascii=False, indent=2)
+
+    print(f"[history] 已保存快照 {ver_dir_name}: {relative_path}")
+
+
+def rollback_to_version(workspace_id: str, relative_path: str, version_dir: str):
+    """
+    将指定历史版本的文件复制回 workspace，更新 current_versions。
+    返回错误信息字符串，成功返回 None。
+    """
+    base_path = get_openclaw_path()
+    history_base = os.path.join(base_path, workspace_id, HISTORY_DIR)
+    history_json_path = os.path.join(history_base, HISTORY_FILENAME)
+
+    # 安全检查
+    if ".." in version_dir or ".." in relative_path:
+        return "invalid path"
+
+    rel_parts = relative_path.replace("\\", "/").split("/")
+    src_path = os.path.join(history_base, version_dir, *rel_parts)
+    if not os.path.exists(src_path):
+        return f"历史文件不存在: {version_dir}/{relative_path}"
+
+    workspace_path = os.path.join(base_path, workspace_id)
+    dest_path = os.path.join(workspace_path, *rel_parts)
+
+    # 压制本次写盘触发的 on_modified 快照
+    _rollback_suppressed[dest_path] = time.time()
+
+    try:
+        os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+        with open(src_path, "rb") as src, open(dest_path, "wb") as dst:
+            dst.write(src.read())
+    except Exception as e:
+        _rollback_suppressed.pop(dest_path, None)
+        return f"文件写入失败: {e}"
+
+    # 更新 current_versions（从 version_dir 解析版本号）
+    history_data = _load_history_json(history_json_path, workspace_id)
+    if "current_versions" not in history_data:
+        history_data["current_versions"] = {}
+    try:
+        ver_num = int(version_dir.lstrip("v"))
+    except ValueError:
+        ver_num = -1
+    history_data["current_versions"][relative_path] = ver_num
+    with open(history_json_path, "w", encoding="utf-8") as f:
+        json.dump(history_data, f, ensure_ascii=False, indent=2)
+
+    print(f"[history] 已回滚 {relative_path} → {version_dir}")
+    return None
+
+
+def _empty_history(workspace_id: str) -> dict:
+    return {
+        "workspace_id": workspace_id,
+        "next_version": 1,
+        "current_versions": {},
+        "records": []
+    }
 
 
 def _path_has_ignored_dir(filepath):
@@ -217,7 +343,12 @@ def file_gen(path, method):
         init_config(space_id, relative_path, method="delete")
         print(f"🗑️ 已删除配置记录: {relative_path}")
     else:
-        # 添加或修改时进行上传
+        # ── 历史版本：把当前内容作为快照存档（仅覆盖行为，非配置文件）──
+        # 回滚写盘触发的 on_modified 跳过，避免产生多余版本
+        if os.path.basename(path) != ARTIFACTS_FILENAME and not _is_rollback_suppressed(path):
+            save_history_version(space_id, relative_path, path)
+
+        # ── 上传到 OSS ───────────────────────────────────────────
         try:
             token = q.upload_token(bucket_name, key, 3600)
             # 直接使用 put_file_v2 上传文件路径，避免读取到空内容时导致 SDK 报错缺少 data 参数
@@ -440,28 +571,28 @@ def _do_fork(job_id, src_clawname, src_workspace, src_version, entry_rel_path=No
 
         print(f"[Fork] 找到 {len(files)} 个文件，开始下载...")
         success = 0
+        downloaded_rels = []
         for item in files:
             key = item['key']
-            # 去掉前缀，得到相对路径（CDN key 是 URL 编码过的，decode 成实际文件名）
             rel_path = unquote(key[len(prefix):])
             if not rel_path:
                 continue
             local_path = os.path.join(target_dir, rel_path)
             if _download_from_cdn(key, local_path):
                 success += 1
+                downloaded_rels.append(rel_path)
                 print(f"  ✓ {rel_path}")
 
         print(f"[Fork] 完成: 成功 {success}/{len(files)} 个文件")
 
-        # 更新入口文件 mtime，使其在列表中排最前
-        # entry_rel_path 可能是 URL 编码（含中文），需 decode 为本地文件名
-        if entry_rel_path:
-            entry_local = os.path.join(target_dir, unquote(entry_rel_path))
-            if os.path.exists(entry_local):
-                os.utime(entry_local, None)
-                print(f"[Fork] 已更新入口文件 mtime: {entry_rel_path}")
-            else:
-                print(f"[Fork] 警告: 入口文件不存在，跳过 mtime 更新: {entry_rel_path}")
+        # 写入 JSON 记录，入口文件最后写，确保其 updated_at 最新排第一
+        entry_decoded = unquote(entry_rel_path) if entry_rel_path else None
+        for rel in downloaded_rels:
+            if rel != entry_decoded:
+                init_config(new_workspace, rel, method="add")
+        if entry_decoded and entry_decoded in downloaded_rels:
+            init_config(new_workspace, entry_decoded, method="add")
+            print(f"[Fork] 入口文件已置顶: {entry_decoded}")
 
         # 文件到位后再发分析消息，确保 AI 能读到 fork 的内容
         fork_message = (
@@ -529,7 +660,7 @@ def start_fork(remote_url):
 # 内嵌 HTTP API 服务
 # ═══════════════════════════════════════════════════════════════
 
-API_PORT = int(os.environ.get("MYCLAW_API_PORT", "8080"))
+API_PORT = int(os.environ.get("MYCLAW_API_PORT", "18800"))
 
 
 class MyclawAPIHandler(BaseHTTPRequestHandler):
@@ -588,6 +719,14 @@ class MyclawAPIHandler(BaseHTTPRequestHandler):
             return self._handle_resync(params)
         elif path == '/api/fork':
             return self._handle_fork()
+        elif path == '/api/history/rollback':
+            return self._handle_rollback()
+        elif path == '/api/agents/trash':
+            return self._handle_agents_trash()
+        elif path == '/api/template/copy':
+            return self._handle_template_copy()
+        elif path == '/api/template/deploy':
+            return self._handle_template_deploy()
         else:
             self._send_json({"error": "not found"}, 404)
 
@@ -598,11 +737,67 @@ class MyclawAPIHandler(BaseHTTPRequestHandler):
             return self._handle_config()
         elif path == '/api/artifacts':
             return self._handle_artifacts(params)
+        elif path == '/api/history':
+            return self._handle_history(params)
+        elif path == '/api/history/file':
+            return self._handle_history_file(params)
         elif path == '/api/fork/status':
             return self._handle_fork_status(params)
+        elif path == '/api/agents':
+            return self._handle_agents_list()
+        elif path == '/api/file':
+            return self._handle_file(params)
         else:
             self._send_json({"error": "not found"}, 404)
 
+    def _handle_agents_list(self):
+        """GET /api/agents → 复用 mc list-agents --json"""
+        try:
+            ret = subprocess.run(
+                ['mc', 'list-agents', '--json'],
+                capture_output=True, timeout=15, text=True
+            )
+            if ret.returncode == 0:
+                self._send_json_raw(ret.stdout.strip().encode('utf-8'))
+            else:
+                self._send_json({'error': ret.stderr.strip() or 'mc list-agents 执行失败'}, 500)
+        except FileNotFoundError:
+            self._send_json({'error': 'mc 命令未找到，请确认 MyClaw 已安装'}, 500)
+        except subprocess.TimeoutExpired:
+            self._send_json({'error': 'mc list-agents 超时'}, 500)
+        except Exception as e:
+            self._send_json({'error': str(e)}, 500)
+
+    def _handle_agents_trash(self):
+        """POST /api/agents/trash  Body: {"paths": [...]} → 复用 mc trash-paths"""
+        try:
+            length = int(self.headers.get('Content-Length', 0))
+            body = json.loads(self.rfile.read(length).decode('utf-8')) if length else {}
+        except Exception:
+            self._send_json({'error': '请求体解析失败'}, 400)
+            return
+
+        paths = [p for p in body.get('paths', []) if p and isinstance(p, str)]
+        if not paths:
+            self._send_json({'error': '缺少有效的 paths 参数'}, 400)
+            return
+
+        try:
+            ret = subprocess.run(
+                ['mc', 'trash-paths', '--json'] + paths,
+                capture_output=True, timeout=30, text=True
+            )
+            if ret.returncode in (0, 1):  # 1 = 部分失败，仍返回 JSON
+                self._send_json_raw(ret.stdout.strip().encode('utf-8'))
+            else:
+                self._send_json({'error': ret.stderr.strip() or 'mc trash-paths 执行失败'}, 500)
+        except FileNotFoundError:
+            self._send_json({'error': 'mc 命令未找到，请确认 MyClaw 已安装'}, 500)
+        except subprocess.TimeoutExpired:
+            self._send_json({'error': 'mc trash-paths 超时'}, 500)
+        except Exception as e:
+            self._send_json({'error': str(e)}, 500)
+
     def _handle_config(self):
         """GET /api/config → 返回 claw 名称和 CDN base_url"""
         self._send_json({"claw": claw, "base_url": BASE_URL})
@@ -628,6 +823,95 @@ class MyclawAPIHandler(BaseHTTPRequestHandler):
         except Exception as e:
             self._send_json({"error": str(e)}, 500)
 
+    def _handle_history(self, params):
+        """GET /api/history?workspace=xxx → 返回 __history__/history.json"""
+        workspace = params.get('workspace', [''])[0]
+        if not workspace:
+            self._send_json({"error": "missing workspace param"}, 400)
+            return
+
+        base_path = get_openclaw_path()
+        json_path = os.path.join(base_path, workspace, HISTORY_DIR, HISTORY_FILENAME)
+
+        if not os.path.exists(json_path):
+            self._send_json({"workspace_id": workspace, "next_version": 1, "records": []})
+            return
+
+        try:
+            with open(json_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+            self._send_json_raw(content.encode('utf-8'))
+        except Exception as e:
+            self._send_json({"error": str(e)}, 500)
+
+    def _handle_history_file(self, params):
+        """GET /api/history/file?workspace=xxx&version=v1&path=xxx → 返回历史版本文件内容"""
+        workspace = params.get('workspace', [''])[0]
+        version = params.get('version', [''])[0]
+        rel_path = params.get('path', [''])[0]
+
+        if not workspace or not version or not rel_path:
+            self._send_json({"error": "missing params"}, 400)
+            return
+
+        # 安全检查：防止路径穿越
+        if '..' in version or '..' in rel_path:
+            self._send_json({"error": "invalid path"}, 400)
+            return
+
+        base_path = get_openclaw_path()
+        rel_parts = rel_path.replace('\\', '/').split('/')
+        file_path = os.path.join(base_path, workspace, HISTORY_DIR, version, *rel_parts)
+
+        if not os.path.exists(file_path):
+            self._send_json({"error": "file not found"}, 404)
+            return
+
+        try:
+            with open(file_path, 'rb') as f:
+                content = f.read()
+            # 根据扩展名设置 Content-Type
+            ext = rel_path.rsplit('.', 1)[-1].lower() if '.' in rel_path else ''
+            ct_map = {
+                'html': 'text/html; charset=utf-8',
+                'htm': 'text/html; charset=utf-8',
+                'css': 'text/css; charset=utf-8',
+                'js': 'application/javascript; charset=utf-8',
+                'json': 'application/json; charset=utf-8',
+            }
+            content_type = ct_map.get(ext, 'text/plain; charset=utf-8')
+            self.send_response(200)
+            self._cors_headers()
+            self.send_header('Content-Type', content_type)
+            self.send_header('Content-Length', str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+        except Exception as e:
+            self._send_json({"error": str(e)}, 500)
+
+    def _handle_rollback(self):
+        """POST /api/history/rollback  Body: {"workspace":"...","version":"v2","path":"..."}"""
+        try:
+            length = int(self.headers.get('Content-Length', 0))
+            body = json.loads(self.rfile.read(length).decode('utf-8')) if length else {}
+        except Exception:
+            self._send_json({"error": "请求体解析失败"}, 400)
+            return
+
+        workspace = body.get('workspace', '')
+        version = body.get('version', '')
+        rel_path = body.get('path', '')
+
+        if not workspace or not version or not rel_path:
+            self._send_json({"error": "缺少参数"}, 400)
+            return
+
+        err = rollback_to_version(workspace, rel_path, version)
+        if err:
+            self._send_json({"ok": False, "error": err}, 400)
+        else:
+            self._send_json({"ok": True})
+
     def _handle_resync(self, params):
         """POST /api/resync?workspace=xxx → 触发全量同步"""
         workspace = params.get('workspace', [''])[0]
@@ -671,6 +955,152 @@ class MyclawAPIHandler(BaseHTTPRequestHandler):
             return
         self._send_json(_fork_jobs[job_id])
 
+    def _skill_scripts_root(self):
+        """返回 yiran-playground-template-use/scripts 的绝对路径"""
+        return os.path.join(
+            get_openclaw_path(), 'workspace-ai-demo', 'skills',
+            'yiran-playground-template-use', 'scripts'
+        )
+
+    def _resolve_template_path(self, folder):
+        """校验 folder 并返回模板绝对路径；非法时直接响应并返回 None"""
+        if not folder or '..' in folder or '/' in folder or '\\' in folder:
+            self._send_json({'error': 'invalid folder'}, 400)
+            return None
+        path = os.path.join(
+            get_openclaw_path(), 'workspace-ai-demo', 'skills',
+            'yiran-playground-template-use', 'templates', folder
+        )
+        if not os.path.isdir(path):
+            self._send_json({'error': f'模板目录不存在: {folder}'}, 404)
+            return None
+        return path
+
+    def _run_skill_script(self, cmd, timeout=60):
+        """运行 skill 脚本，解析 stdout JSON 并返回 (data, err)"""
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+            output = (result.stdout or '').strip()
+            if output:
+                try:
+                    return json.loads(output), None
+                except json.JSONDecodeError:
+                    pass
+            return None, result.stderr.strip() or output or '未知错误'
+        except subprocess.TimeoutExpired:
+            return None, f'执行超时（{timeout}s）'
+        except Exception as e:
+            return None, str(e)
+
+    def _handle_template_copy(self):
+        """POST /api/template/copy  Body: {"folder": "a100_...", "workspace": "workspace-xxx"}
+        → deploy_to_workspace.py <template_path> <workspace_abs_path>   （不加 --with-tui）"""
+        try:
+            length = int(self.headers.get('Content-Length', 0))
+            body = json.loads(self.rfile.read(length).decode('utf-8')) if length else {}
+        except Exception:
+            self._send_json({'error': '请求体解析失败'}, 400)
+            return
+
+        folder = body.get('folder', '')
+        workspace = body.get('workspace', '')  # e.g. "workspace-xxx"
+        if not workspace:
+            self._send_json({'error': '缺少 workspace 参数'}, 400)
+            return
+
+        template_path = self._resolve_template_path(folder)
+        if template_path is None:
+            return
+
+        workspace_abs = os.path.join(get_openclaw_path(), workspace)
+        script = os.path.join(self._skill_scripts_root(), 'deploy_to_workspace.py')
+
+        data, err = self._run_skill_script(
+            [sys.executable, script, template_path, workspace_abs],
+            timeout=30
+        )
+        if err:
+            self._send_json({'ok': False, 'error': err}, 500)
+        else:
+            self._send_json(data)
+
+    def _handle_template_deploy(self):
+        """POST /api/template/deploy  Body: {"folder": "a100_..."}
+        → run_playgrounds_flow.py <template_path>   （prepare + deploy + --with-tui）"""
+        try:
+            length = int(self.headers.get('Content-Length', 0))
+            body = json.loads(self.rfile.read(length).decode('utf-8')) if length else {}
+        except Exception:
+            self._send_json({'error': '请求体解析失败'}, 400)
+            return
+
+        folder = body.get('folder', '')
+        template_path = self._resolve_template_path(folder)
+        if template_path is None:
+            return
+
+        script = os.path.join(self._skill_scripts_root(), 'run_playgrounds_flow.py')
+
+        data, err = self._run_skill_script(
+            [sys.executable, script, template_path],
+            timeout=60
+        )
+        if err:
+            self._send_json({'ok': False, 'error': err}, 500)
+        else:
+            self._send_json(data)
+
+    def _handle_file(self, params):
+        """GET /api/file?path=relative/path → 通用文件服务，路径相对于 .openclaw 根目录
+        安全：os.path.realpath 解析后必须以 openclaw 根为前缀，防止路径穿越"""
+        rel_path = params.get('path', [''])[0]
+        if not rel_path:
+            self._send_json({"error": "missing path param"}, 400)
+            return
+
+        base_path = os.path.realpath(get_openclaw_path())
+        abs_path = os.path.realpath(os.path.join(base_path, rel_path))
+
+        # 路径必须在 .openclaw 目录内
+        if not abs_path.startswith(base_path + os.sep):
+            self._send_json({"error": "forbidden"}, 403)
+            return
+
+        if not os.path.isfile(abs_path):
+            self._send_json({"error": "file not found"}, 404)
+            return
+
+        try:
+            with open(abs_path, 'rb') as f:
+                content = f.read()
+
+            ext = abs_path.rsplit('.', 1)[-1].lower() if '.' in abs_path else ''
+            ct_map = {
+                'html': 'text/html; charset=utf-8',
+                'htm':  'text/html; charset=utf-8',
+                'css':  'text/css; charset=utf-8',
+                'js':   'application/javascript; charset=utf-8',
+                'json': 'application/json; charset=utf-8',
+                'txt':  'text/plain; charset=utf-8',
+                'md':   'text/plain; charset=utf-8',
+                'png':  'image/png',
+                'jpg':  'image/jpeg',
+                'jpeg': 'image/jpeg',
+                'gif':  'image/gif',
+                'svg':  'image/svg+xml',
+                'webp': 'image/webp',
+            }
+            content_type = ct_map.get(ext, 'application/octet-stream')
+
+            self.send_response(200)
+            self._cors_headers()
+            self.send_header('Content-Type', content_type)
+            self.send_header('Content-Length', str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+        except Exception as e:
+            self._send_json({"error": str(e)}, 500)
+
     def log_message(self, format, *args):
         # 静默日志，避免轮询刷屏
         pass

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

@@ -0,0 +1,127 @@
+# 课程模板流水线 Skill
+
+这个 skill 面向中文课堂的小专题课程设计流程。
+
+它的目标不是只生成某一个页面，而是把一个“题目灵感 / 设计角度”逐步变成一整套可用的课程任务文件。
+
+---
+
+# 当前工作流
+
+## 阶段一：灵感 -> demo 页面
+最开始输入的是：
+- 题目灵感
+- 设计角度
+- 课堂上的切入想法
+
+这一阶段最重要的事情是：
+**先做出 __demo__.html（效果演示页）**
+
+阶段一到阶段三的产物，统一放在：
+**当前工作目录下新建的 `任务名称/` 文件夹里。**
+
+也就是说：
+- 不先放到 templates
+- 不先放到 skill 目录根部
+- 而是在当前工作目录里，先建立一个任务临时文件夹，再往里写 `__demo__.html`、`__student__.json`、`__teacher__.json`
+
+---
+
+## 阶段二：生成 __student__.json
+这一阶段不要求一定已经有 __teacher__.json。
+这一阶段甚至不要求一定已经有完整作品。
+
+这一阶段的核心目标是：
+**先把学生任务的步骤和评价结构 JSON 确立下来。**
+
+对应输出：
+`__student__.json`
+
+---
+
+## 阶段三：生成 __teacher__.json
+在 __student__.json 已经明确后，再整理教师侧信息。
+
+这一阶段的核心目标是：
+**明确题目设计目的、训练重点、适合学生类型，以及老师上课时如何判断和引导。**
+
+对应输出：
+`__teacher__.json`
+
+---
+
+## 阶段四：JSON -> HTML，并按目录打包
+第4阶段现在拆成两个脚本：
+
+### 1）build_template_views.py
+校验通过后，在原文件夹中直接生成：
+- `__student-view__.html`
+- `__teacher-view__.html`
+- `index.html`
+
+其中 `index.html` 采用固定脚本规则：
+- 只展示两块内容
+- 左边是“评价目标”
+- 右边是“步骤”
+- 不显示任务标题
+- 不显示一句话说明
+- 不再依赖临时提示词拼装
+- 统一由脚本直接根据 `__student__.json` 渲染
+
+### 2）move_template_task.py
+在页面已经生成好的前提下，把整个文件夹移动到：
+`yiran-playground-template-use` skill 的 `templates/`
+
+同时按规则改名，例如：
+`a100_给依然老师设计一个AI画像`
+
+并且：
+**move 成功后会自动触发 `yiran-playground-template-use` 的索引重建。**
+
+---
+
+# 当前目录结构
+
+- `SKILL.md`：技能总说明
+- `prompts/阶段1-demo生成.md`：如何把灵感先做成 demo 页面
+- `prompts/阶段2-student生成.md`：如何生成 __student__.json
+- `prompts/阶段3-teacher生成.md`：如何生成 __teacher__.json
+- `prompts/阶段4-打包落盘.md`：如何组织文件并调用第4阶段脚本
+- `scripts/render_teacher_view.py`：把 __teacher__.json 渲染成教师查看页
+- `scripts/render_student_page.py`：把 __student__.json 渲染成学生页
+- `scripts/build_template_views.py`：在原目录生成 __student-view__.html 和 __teacher-view__.html
+- `scripts/move_template_task.py`：移动整个任务文件夹到 templates 并改名，同时自动重建索引
+- `references/teacher-fields.md`：教师侧字段设计与标签规则说明
+- `references/student-fields.md`：学生侧字段说明
+- `references/student-example.json`：学生侧 JSON 示例
+- `references/student-scaffold.json`：学生侧 JSON 脚手架
+- `references/teacher-scaffold.json`：教师侧 JSON 脚手架
+- `assets/student-template.html`：独立学生页模板
+- 模板库和搜索索引统一维护在 `yiran-playground-template-use` skill 中
+
+---
+
+# 模板索引
+
+模板库和索引统一维护在 `yiran-playground-template-use` skill 中。
+
+`move_template_task.py` 成功执行后会自动触发索引重建。如需手动重建，在 `yiran-playground-template-use` skill 中运行：
+
+```bash
+python3 scripts/build_template_index.py
+```
+
+---
+
+# 核心原则
+
+1. 先有灵感，再做 demo，再定 __student__.json，再定 __teacher__.json
+2. 阶段一到三的产物，统一放在当前工作目录下新建的任务文件夹里
+3. __student__.json 先解决学生任务结构
+4. __teacher__.json 再解决题目设计目的与教师判断
+5. 第4阶段拆成 build 和 move 两个独立脚本
+6. templates 作为 skill 的资产目录统一维护
+7. 模板有变化后，要重新构建索引
+8. demo 中的媒体资源优先使用 CDN 链接，不使用本地相对路径；当前固定前缀为 `https://cdn.yiranlaoshi.com/yiran/workspace-ai-demo`，后面拼接资源相对路径
+9. 模板负责布局，提示词负责填内容，脚本负责稳定输出
+10. 所有内容优先服务中文课堂和小学生阅读场景