chore(workflow): add markdown header check rules and update readme te… (#104)

Author: yaozheng-fang

template/README.md

@@ -1,5 +1,44 @@
 # AgentKit 样例模板
 
+您提交的样例应当在 README.md 中添加 Yaml 格式的元数据，用于描述您的样例，具体内容包括：
+
+```markdown
+---
+name:                     # 中文名称（255字符）
+name_en:                  # 英文名称（255字符）
+description:              # 简介（10-20字）
+details:                  # 详细介绍（10-40字）
+type:                     # 类型，可选项为 tutorial | application
+senarios:                 # 应用场景（2-6个），type 为 application 时必填
+    - name:               # 应用场景名称（2-15字）
+    desc:                 # 应用场景描述（10-20字）
+    - name:
+    desc:
+prompts:                  # Prompt 样例
+    - text:               # Prompt 文本（简洁精炼）
+      resource_url:       # 必要的多模态数据 URL（公网可访问）
+    - prompt:
+      resource_url:
+envs:                     # 所需的环境变量（用于第三方依赖服务）
+    - name:               # 环境变量中文名
+      key:                # 环境变量名
+      url:                # 引导链接
+components:               # Agentkit 依赖服务
+    - type:               # 服务类型，可选项为 tool | knowledgebase | memory
+      # 对应产品（不区分大小写）
+      # tool: AIO_Sandbox | Skills_Sandbox
+      # knowledgebase: VikingKnowledge
+      # memory: VikingMem | Mem0
+      product:
+models:                   # 涉及到的具体模型列表
+    - doubao-seed-1-8-251215
+---
+
+# Markdown 正文
+
+...
+```
+
 > 您向 `agentkit-samples` 项目提交的样例，需要符合以下目录结构，并保证内容完整：
 >
 > ```bash

workflow_utils/check_readme_metadata.py

@@ -1,11 +1,20 @@
 # pip install python-frontmatter
-from typing import Any
-from pathlib import Path
 import argparse
 import subprocess
 import sys
+from pathlib import Path
+from typing import Any
+
 import frontmatter
 
+SAMPLE_TYPES = ["tutorial", "application"]
+
+COMPONENT_OPTIONS = {
+    "sandbox": ["AIO_Sandbox", "Skills_Sandbox"],
+    "knowledgebase": ["VikingKnowledge"],
+    "memory": ["VikingMem", "Mem0"],
+}
+
 
 def should_skip(metadata: dict[str, Any]) -> bool:
     return not metadata
@@ -16,37 +25,122 @@ def check_name(metadata: dict[str, Any]):
     if not name:
         raise ValueError("name is required")
 
+    if len(name) > 255:
+        raise ValueError("name should be less than 255 characters")
+
+
+def check_name_en(metadata: dict[str, Any]):
+    name_en = metadata.get("name_en")
+    if not name_en:
+        raise ValueError("name_en is required")
+
+    if len(name_en) > 255:
+        raise ValueError("name_en should be less than 255 characters")
+
 
 def check_description(metadata: dict[str, Any]):
     description = metadata.get("description")
     if not description:
         raise ValueError("description is required")
 
+    if len(description) < 10 or len(description) > 20:
+        raise ValueError("description should be between 10-20 characters")
+
+
+def check_details(metadata: dict[str, Any]):
+    details = metadata.get("details")
+    if not details:
+        raise ValueError("details is required")
+
+    if len(details) < 10 or len(details) > 40:
+        raise ValueError("details should be between 10-40 characters")
+
+
+def check_type(metadata: dict[str, Any]):
+    type = metadata.get("type")
+    if not type:
+        raise ValueError("type is required")
+
+    if type not in SAMPLE_TYPES:
+        raise ValueError(f"type should be one of {SAMPLE_TYPES}")
+
 
 def check_senarios(metadata: dict[str, Any]):
-    senarios = metadata.get("senarios")
-    if not senarios:
-        raise ValueError("senarios is required")
-    if len(senarios) != 4:
-        raise ValueError("senarios should have 4 items")
+    type = metadata.get("type")
+    senarios: list = metadata.get("senarios", [])
+    if not senarios and type == "application":
+        raise ValueError("senarios is required when type is `application`")
 
+    if len(senarios) < 2 or len(senarios) > 6:
+        raise ValueError("senarios should have 2-6 items")
 
-def check_components(metadata: dict[str, Any]):
-    standard_components = ["Identity", "MCP Toolset"]
-    components = metadata.get("components")
-    if not components:
-        raise ValueError("components is required")
-    if len(components) == 0:
-        raise ValueError("components should have at least 1 item")
-    for component in components:
-        name = component.get("name")
+    for scenario in senarios:
+        name = scenario.get("name")
         if not name:
-            raise ValueError("component name is required")
-        desc = component.get("desc")
+            raise ValueError("scenario name is required")
+        if len(name) < 2 or len(name) > 15:
+            raise ValueError("scenario name should be between 2-15 characters")
+
+        desc = scenario.get("desc")
         if not desc:
-            raise ValueError("component desc is required")
-        if component["name"] not in standard_components:
-            raise ValueError(f"component name should be one of {standard_components}")
+            raise ValueError("scenario desc is required")
+        if len(desc) < 10 or len(desc) > 20:
+            raise ValueError("scenario desc should be between 10-20 characters")
+
+
+def check_prompts(metadata: dict[str, Any]):
+    prompts: list = metadata.get("prompts", [])
+    if not prompts:
+        raise ValueError("prompts field is required")
+
+    for prompt in prompts:
+        text = prompt.get("text")
+        if not text:
+            raise ValueError("prompt text is required")
+
+        resource_url = prompt.get("resource_url")
+        if resource_url:
+            assert resource_url.startswith("https://") or resource_url.startswith(
+                "http://"
+            ), "resource_url must start with `https://` or `http://`"
+
+
+def check_models(metadata: dict[str, Any]):
+    models: list = metadata.get("models", [])
+    if not models:
+        raise ValueError("models field is required")
+
+
+def check_envs(metadata: dict[str, Any]):
+    envs: list = metadata.get("envs", [])
+
+    for env in envs:
+        assert env.get("name"), "env name is required"
+        assert env.get("key"), "env key is required"
+
+        url = env.get("url")
+        assert url, "env url is required"
+        assert url.startswith("https://") or url.startswith("http://"), (
+            "env url must start with `https://` or `http://`"
+        )
+
+
+def check_components(metadata: dict[str, Any]):
+    components = metadata.get("components", [])
+
+    for component in components:
+        assert component.get("type"), "component type is required"
+        assert component.get("product"), "component product is required"
+
+        component_type = component["type"].lower()
+        component_product = component["product"].lower()
+
+        assert component_type in COMPONENT_OPTIONS, (
+            f"component type should be one of {COMPONENT_OPTIONS.keys()}"
+        )
+        assert component_product in COMPONENT_OPTIONS[component_type], (
+            f"component product should be one of {COMPONENT_OPTIONS[component_type]}"
+        )
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -109,8 +203,14 @@ def main(argv: list[str] | None = None) -> int:
 
         try:
             check_name(post.metadata)
+            check_name_en(post.metadata)
             check_description(post.metadata)
+            check_details(post.metadata)
+            check_type(post.metadata)
             check_senarios(post.metadata)
+            check_prompts(post.metadata)
+            check_models(post.metadata)
+            check_envs(post.metadata)
             check_components(post.metadata)
         except ValueError as exc:
             sys.stderr.write(f"{rel}: {exc}\n")