@lark-apaas/coding-steering 0.1.18-dev.4e64c13 → 0.1.18-dev.61b3ece

package/steering/design-html/skills/slide-deck/scripts/check_local_references.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+
+import re
+import sys
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+
+CSS_URL_PATTERN = re.compile(r"""url\(\s*(['"]?)(.*?)\1\s*\)""", re.IGNORECASE)
+CSS_IMPORT_PATTERN = re.compile(
+    r"""@import\s+(?:url\(\s*)?(['"])(.*?)\1\s*\)?""",
+    re.IGNORECASE,
+)
+CSS_COMMENT_PATTERN = re.compile(r"/\*.*?\*/", re.DOTALL)
+HREF_RESOURCE_TAGS = {"image", "link", "use"}
+SRC_RESOURCE_TAGS = {
+    "audio",
+    "embed",
+    "iframe",
+    "img",
+    "input",
+    "script",
+    "source",
+    "track",
+    "video",
+}
+
+
+class ReferenceParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.references: set[str] = set()
+        self.in_style = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        if tag == "style":
+            self.in_style = True
+        attributes = dict(attrs)
+        if tag in HREF_RESOURCE_TAGS and attributes.get("href"):
+            self.references.add(attributes["href"])
+        if tag in SRC_RESOURCE_TAGS and attributes.get("src"):
+            self.references.add(attributes["src"])
+        if tag == "object" and attributes.get("data"):
+            self.references.add(attributes["data"])
+        if tag == "video" and attributes.get("poster"):
+            self.references.add(attributes["poster"])
+
+        srcset = attributes.get("srcset")
+        if tag in {"img", "source"} and srcset:
+            self.references.update(
+                candidate.strip().split()[0]
+                for candidate in srcset.split(",")
+                if candidate.strip()
+            )
+
+        style = attributes.get("style")
+        if style:
+            self.references.update(css_references(style))
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag.lower() == "style":
+            self.in_style = False
+
+    def handle_data(self, data: str) -> None:
+        if self.in_style:
+            self.references.update(css_references(data))
+
+
+def css_references(content: str) -> set[str]:
+    content_without_comments = CSS_COMMENT_PATTERN.sub("", content)
+    references = {
+        match.group(2).strip() for match in CSS_URL_PATTERN.finditer(content_without_comments)
+    }
+    references.update(
+        match.group(2).strip() for match in CSS_IMPORT_PATTERN.finditer(content_without_comments)
+    )
+    return references
+
+
+def resolve_local_reference(
+    raw_reference: str,
+    source: Path,
+    project_root: Path,
+) -> Path | None:
+    reference = raw_reference.strip()
+    parsed = urlsplit(reference)
+    if (
+        not reference
+        or reference.startswith(("#", "//"))
+        or (parsed.scheme and parsed.scheme.lower() != "file")
+        or parsed.netloc
+    ):
+        return None
+
+    path_text = unquote(parsed.path)
+    if not path_text:
+        return None
+
+    if parsed.scheme.lower() == "file":
+        return Path(path_text).resolve()
+    if path_text.startswith("/"):
+        return (project_root / path_text.lstrip("/")).resolve()
+    return (source.parent / path_text).resolve()
+
+
+def collect_references(entry: Path, project_root: Path) -> list[tuple[Path, str, Path]]:
+    pending = [entry]
+    visited: set[Path] = set()
+    local_references: list[tuple[Path, str, Path]] = []
+
+    while pending:
+        source = pending.pop()
+        if source in visited or not source.is_file():
+            continue
+        visited.add(source)
+
+        content = source.read_text(encoding="utf-8")
+        if source.suffix.lower() == ".css":
+            references = css_references(content)
+        else:
+            parser = ReferenceParser()
+            parser.feed(content)
+            references = parser.references
+
+        for raw_reference in sorted(references):
+            target = resolve_local_reference(raw_reference, source, project_root)
+            if target is None:
+                continue
+            local_references.append((source, raw_reference, target))
+            if target.suffix.lower() == ".css" and target.is_file():
+                pending.append(target)
+
+    return local_references
+
+
+def display_path(path: Path, project_root: Path) -> str:
+    try:
+        return path.relative_to(project_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: check_local_references.py <entry.html>", file=sys.stderr)
+        return 2
+
+    project_root = Path.cwd().resolve()
+    entry = (project_root / sys.argv[1]).resolve()
+    if not entry.is_file():
+        print(f"RESOURCE_CHECK: FAIL entryNotFound={sys.argv[1]}")
+        return 1
+
+    missing: list[tuple[Path, str, Path]] = []
+    for source, raw_reference, target in collect_references(entry, project_root):
+        try:
+            target.relative_to(project_root)
+        except ValueError:
+            missing.append((source, raw_reference, target))
+            continue
+        if not target.is_file():
+            missing.append((source, raw_reference, target))
+
+    if not missing:
+        print("RESOURCE_CHECK: PASS")
+        return 0
+
+    print(f"RESOURCE_CHECK: FAIL missingLocalReferences={len(missing)}")
+    for source, raw_reference, target in missing:
+        source_name = display_path(source, project_root)
+        target_name = display_path(target, project_root)
+        print(f"- {source_name}: {raw_reference} -> {target_name}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/steering/nestjs-react-fullstack/skills/plugin-guide/SKILL.md

@@ -215,7 +215,7 @@ const structured = await capabilityClient
 - **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
 - **PluginInstance（插件实例配置）**：基于某个 Plugin 的表单做"业务封装"，以 **单文件 JSON** 的形式存储（每个插件实例一个文件，语义化 id）。
   - 通过 `paramsSchema` 暴露业务入参
-  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{{input.xxx}}`）
+  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{% raw %}{{input.xxx}}{% endraw %}`）
 - **PluginInstanceAIJson（pluginInstance.ai.json）**：工程转化层产物，是 pluginInstance 的**运行时投影 / 调用合同（Runtime Spec）**。
   - 包含插件定位信息、actions 入口列表、input/output schema、outputMode、readme 等
   - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（Server 侧用 `CapabilityService`，Client 侧用 `capabilityClient`）
@@ -258,6 +258,7 @@ Plugin 的具体内容以JSON格式给出，例如：
 
 
 PluginInstance 的配置以 JSON 形式输出，例如：
+{% raw %}
 ```json
 {
   "id": "create_feishu_group",       // 全局唯一语义化 ID
@@ -279,6 +280,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
   }
 }
 ```
+{% endraw %}
 
 **注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
 
@@ -560,7 +562,7 @@ PluginInstanceAIJson 的配置以 JSON 形式输出，例如：
 | 未按 `outputSchema` 解析返回值，猜测返回结构 | 严格按 `get_plugin_ai_json` 返回的 `outputSchema` 读取字段，流式和非流式均适用 |
 | 未输出 Schema 摘录卡就直接写调用代码 | 先完成“编码前闸门”中的摘录卡，再开始编码 |
 | 改完未做真实调用冒烟就宣告完成 | 至少完成一次 unary/stream 真实调用验证，并附最小日志字段 |
-| formValue 中用 `["{{input.xxx}}"]` 包装已经是 `type: array` 的 paramsSchema 参数 | 当 paramsSchema 定义为 array 时，formValue 应透传 `"{{input.xxx}}"`，不要再包一层数组 |
+| formValue 中用 `{% raw %}["{{input.xxx}}"]{% endraw %}` 包装已经是 `type: array` 的 paramsSchema 参数 | 当 paramsSchema 定义为 array 时，formValue 应透传 `{% raw %}"{{input.xxx}}"{% endraw %}`，不要再包一层数组 |
 | 通过 `getDataloom().capability` 或 `(dataloom as any).capability` 调用插件 | `capabilityClient` 是独立导入，不通过 dataloom 访问。dataloom 仅提供 storage 和 service |
 | Client 侧调用插件时，先通过 dataloom 上传文件拿 URL 再传给插件 | Client 侧可直接传 File/Blob 对象给 `capabilityClient`，SDK 自动处理上传。适用于所有文件类型字段（`format` 为 `file`/`picture`/`plugin-file-url`）。Server 侧仍需传 URL |
 | 前端调用插件后不保存结果到数据库，导致页面刷新后数据丢失 | 需要持久化时：优先在 Server 侧调用并直接落库（方案A）；若在 Client 侧调用，必须通过已有 CRUD 接口立即保存结果（方案B） |
@@ -642,7 +644,7 @@ try {
 | 场景 | 正确做法 | 示例 |
 |------|---------|------|
 | 需求明确的**固定**接收人/配置 | 在 `plugin_instance CREATE` 的 `formValue` 中直接写死 | `formValue.receiverUserList: ["1854102143505690"]` |
-| **动态**接收人/配置（按角色/条件变化） | 从配置/平台 API/DB 获取，传入 `input` 参数 | `formValue.receiverUserList: "{{input.receiverIds}}"` |
+| **动态**接收人/配置（按角色/条件变化） | 从配置/平台 API/DB 获取，传入 `input` 参数 | `{% raw %}formValue.receiverUserList: "{{input.receiverIds}}"{% endraw %}` |
 
 > **关键区分**：`formValue` 中配置固定值 ≠ 代码中硬编码。`formValue` 是插件实例的声明式配置，修改不需要改代码；而代码中硬编码的值散落在业务逻辑中，难以维护。
 

package/steering/nestjs-react-fullstack/skills_local/plugin-guide/SKILL.md

@@ -8,6 +8,8 @@ steering-topic: plugin_guide
 match-template-name: nestjs-react-fullstack
 ---
 
+{% raw %}
+
 # Plugin 集成指南（本地开发）
 
 AI 插件集成规范，使用 lark-cli 命令管理插件包与实例，通过 capabilityClient / CapabilityService 生成调用代码。
@@ -578,3 +580,5 @@ npx @lark-apaas/miaoda-cli plugin list --id <instance_id>
 5. **禁止用 `npm install` 安装插件包** — 插件包和 npm 包是两套独立机制。
 6. **禁止 Mock** — 必须走真实插件实例调用链路。
 7. **formValue 禁止 Handlebars 控制语法** — 仅允许 `{{input.xxx}}`。
+
+{% endraw %}

package/steering/vite-react/skills/plugin-guide/SKILL.md

@@ -180,7 +180,7 @@ const structured = await (jsonExtractor as any).call('textToJson', { text: rawRe
 - **Plugin（插件）**：底层承载单元，包含插件元信息与表单定义（form.schema）。模型侧只感知插件及其表单字段，不感知插件内部实现细节。
 - **PluginInstance（插件实例配置）**：基于某个 Plugin 的表单做"业务封装"，以 **单文件 JSON** 的形式存储（每个插件实例一个文件，语义化 id）。
   - 通过 `paramsSchema` 暴露业务入参
-  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{{input.xxx}}`）
+  - 通过 `formValue` 将业务入参映射到插件表单字段（可常量或引用 `{% raw %}{{input.xxx}}{% endraw %}`）
 - **PluginInstanceAIJson（pluginInstance.ai.json）**：工程转化层产物，是 pluginInstance 的**运行时投影 / 调用合同（Runtime Spec）**。
   - 包含插件定位信息、actions 入口列表、input/output schema、outputMode、readme 等
   - Code Agent 在生成**调用代码**前，必须读取它作为权威依据（使用 `capabilityClient` 调用）
@@ -224,6 +224,7 @@ Plugin 的具体内容以JSON格式给出，例如：
 
 PluginInstance 的配置以 JSON 形式输出，例如：
 
+{% raw %}
 ```json
 {
   "id": "create_feishu_group",       // 全局唯一语义化 ID
@@ -245,6 +246,7 @@ PluginInstance 的配置以 JSON 形式输出，例如：
   }
 }
 ```
+{% endraw %}
 
 **注意**paramsSchema 支持以下 4 种参数类型,需要按下面规定的格式进行填充：
 

package/steering/vite-react/skills/react-three-fiber/SKILL.md

@@ -5,6 +5,8 @@ steering: true
 steering-topic: react_three_fiber
 ---
 
+{% raw %}
+
 # React Three Fiber (R3F) 编码指南
 
 实现 3D 场景 / 3D 游戏 / 3D 数据可视化时, MUST 用 **react-three-fiber + drei** 声明式栈, 严禁用 React + CSS / SVG / `transform: rotateX` 伪 3D.
@@ -220,3 +222,5 @@ npm install react-error-boundary        # 必装! Canvas 外包 ErrorBoundary
 
 - `client-coding-guide` - vite-react 通用编码规范
 - `component-conventions` - React 组件命名 / 文件结构
+
+{% endraw %}