@tianacloud/agent-skills 1.0.10 → 1.0.12

package/skills/tiana-web/references/template-init.md

@@ -1,6 +1,6 @@
 # 使用模板工程
 
-模板目录来自本次 `tiana web list-template --json` 实际返回的数据。每页 `data.items` 含 name、display_name、description、status 和变量摘要；CLI 的 `--after` 查询下一页。选择符合用户核心功能与数据结构的工程；没有匹配项时按通用 Web 方法制作。
+模板目录来自本次 `tiana web list-template --json` 实际返回的数据。每页 `data.items` 含 name、display_name、description、status 和变量摘要；CLI 的 `--after` 查询下一页。即使 items 为空，存在 next_cursor 时仍继续需要的页。选择符合用户核心功能与数据结构的工程；没有匹配项时按通用 Web 方法制作。
 
 新应用默认由 Agent 创建所需的 SQLite 和 Git，按当前应用命名并保存 CLI 返回的实际实例 ID；用户明确指定已有实例时核实后复用。保存资源回执后执行：
 
@@ -10,6 +10,8 @@ tiana web init-template NAME --dir PROJECT_DIR --json
 
 成功结果的 `data.directory` 是工程根目录，`data.metadata_path` 是元信息文件。CLI 负责下载校验和解压，工程仍保留占位符、SQL 和原始文件。下载失败先核对实际结果，再重新运行；不用链接地址当作创建成功依据。
 
+metadata.json 包含 `repositories` 或 `functions` 时，按[后端服务模板的源码开发步骤](function-templates.md#下载源码后继续开发)保留资源关系；后端私有数据库不绑定给 Web。以下单仓库、Web 直连 SQLite 的步骤适用于相应模板。
+
 ## metadata.json 和变量
 
 读取根部 metadata.json、README、依赖锁文件及构建脚本，按实际工程开发。元信息示例：
@@ -19,6 +21,7 @@ tiana web init-template NAME --dir PROJECT_DIR --json
   "name": "notes",
   "display_name": "记事本",
   "description": "个人笔记、文件夹、全文搜索和自动保存。",
+  "database_required": true,
   "variables": [
     {
       "name": "SQLITE_INSTANCE_ID",
@@ -55,10 +58,18 @@ JSON 中要正确转义字符串，SQL 中按实际语法处理，源码中保
 
 SQL 返回失败、断线或未知结果时停止后续发布，用独立只读查询核对已完成的结构与数据，不自动重放写入。初始化成功后进行应用定制、依赖安装、源码同步、构建及发布；工程 README 中的步骤与实际帮助一起核对。
 
+## 预置素材
+
+按[数据与素材存储](storage-and-assets.md)检查声明及现有实现。`file_seeds` 为
+`template-files` 时，按[模板素材文件](template-files.md)核对源字节、相对路径、
+当前 Web ID 的首次文件准备和干净构建。CLI 解压成功不会自动上传素材，普通
+`web publish` 也不会灌入文件。没有素材声明时沿用原流程；已有应用不因再次发布
+而恢复被用户修改或删除的初始文件。
+
 ## 模板图标
 
 模板的源 `icon.png` 是用户应用的初始图标，复用工程的静态资源复制配置。变量替换时不把 PNG 当文本处理。新应用缺图、继承的是通用占位／标题首字图片或图形与本次功能不符时，按[应用图标](csr-apps.md#应用图标)优先调用 AI 生图制作并保存体现功能的图标，用户明确指定的图片优先。干净构建后确认产物根目录 `icon.png` 可以解码且与选定源图一致，再发布；以后更新模板本身不会直接改变已有用户应用的图标。
 
 ## 构建和来源
 
-模板 `source.repository`、`source.commit` 说明下载包的源工程来源，区别于用户应用自己的 Git 提交。创建用户仓库后记录实际 git_instance_id；提交和构建按 [源码流程](../../tiana-git/references/source-releases.md)。按下载工程的 README 和构建脚本确定命令、入口与产物目录。若脚本接收源码提交号并输出 TIANA_PROJECT_PARAMS，核对其中的 entry、database_instance_id、git_instance_id 和 source_commit，再用于配置 MGR Web 项目；database_instance_id 必须与本次执行 schema/seeds 的 SQLite 一致。核对模块、资源及 MGR Web 项目的 SQLite/Git 绑定后执行 `web publish`，再用 publish_id 查询状态。
+模板 `source.repository`、`source.commit` 说明下载包的源工程来源，区别于用户应用自己的 Git 提交。创建用户仓库后记录实际 git_instance_id；提交和构建按 [源码流程](../../tiana-git/references/source-releases.md)。按下载工程的 README 和构建脚本确定命令、入口与产物目录。创建 Web 时传入实际 entry 和 Git 绑定；直连模式的数据库绑定必须与本次执行 schema/seeds 的 SQLite 一致。源码提交号记录为构建证据。核对模块、资源及 MGR Web 项目的 SQLite/Git 绑定后执行 `web publish`，再用 publish_id 查询状态。

package/skills/tiana-web/scripts/pack-template.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """Package a reviewed source snapshot and its clean build as an installable template."""
 import argparse
+import base64
 import hashlib
 import io
 import json
@@ -13,6 +14,17 @@ MIB = 1 << 20
 MAX_FILE = 16 * MIB
 MAX_EXPANDED = 128 * MIB
 MAX_ENTRIES = 5000
+MAX_FILE_SEEDS = 256
+FILE_TYPES = {
+    ".webp": "image/webp", ".png": "image/png", ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml",
+    ".avif": "image/avif", ".pdf": "application/pdf", ".txt": "text/plain",
+    ".json": "application/json", ".csv": "text/csv", ".md": "text/markdown",
+    ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg",
+    ".mp4": "video/mp4", ".webm": "video/webm", ".woff": "font/woff",
+    ".woff2": "font/woff2", ".ttf": "font/ttf", ".otf": "font/otf",
+    ".glb": "model/gltf-binary", ".gltf": "model/gltf+json",
+}
 
 
 def archive(files):
@@ -58,17 +70,31 @@ def directory_count(data):
 
 def source_files(data):
     count = directory_count(data)
-    files, total, seen = {}, 0, set()
+    files, directories, total, seen = {}, set(), 0, set()
     with zipfile.ZipFile(io.BytesIO(data)) as source:
         for item in source.infolist():
-            name = item.filename.rstrip("/")
+            decoded = item.orig_filename
+            if not item.flag_bits & 0x800:
+                decoded = decoded.encode("cp437").decode("utf-8")
+            name = decoded.removesuffix("/")
             parts = name.split("/")
             mode = item.external_attr >> 16
             if (not name or "\\" in name or "\0" in name or ":" in name
                     or any(part in ("", ".", "..") or part.lower() == ".git" for part in parts)
                     or PurePosixPath(name).is_absolute() or name in seen
-                    or stat.S_IFMT(mode) not in (0, stat.S_IFREG, stat.S_IFDIR)):
+                    or stat.S_IFMT(mode) not in (0, stat.S_IFREG, stat.S_IFDIR)
+                    or item.is_dir() and stat.S_IFMT(mode) == stat.S_IFREG
+                    or not item.is_dir() and stat.S_IFMT(mode) == stat.S_IFDIR
+                    or name in directories and not item.is_dir()):
                 raise ValueError(f"Unsafe source ZIP path or type: {name}")
+            for parent in PurePosixPath(name).parents:
+                if str(parent) == ".":
+                    continue
+                if str(parent) in files:
+                    raise ValueError(f"Source ZIP file/directory collision: {name}")
+                directories.add(str(parent))
+            if item.is_dir():
+                directories.add(name)
             seen.add(name)
             if item.file_size > MAX_FILE or total + item.file_size > MAX_EXPANDED:
                 raise ValueError("Source ZIP exceeds expanded size budget")
@@ -77,17 +103,115 @@ def source_files(data):
             if len(value) > MAX_FILE or total + len(value) > MAX_EXPANDED:
                 raise ValueError("Source ZIP exceeds actual expanded size budget")
             total += len(value)
+            if item.is_dir() and value:
+                raise ValueError(f"Source ZIP directory contains file bytes: {name}")
             if not item.is_dir():
                 files[name] = value
     return files, total, count
 
 
+def template_file_materials(snapshot, metadata):
+    names = [name for name in snapshot if name == "template-files" or name.startswith("template-files/")]
+    if "file_seeds" not in metadata:
+        if names:
+            raise ValueError("template-files requires a file_seeds declaration")
+        return None
+    if metadata["file_seeds"] != "template-files":
+        raise ValueError("file_seeds must be template-files")
+    if not 1 <= len(names) <= MAX_FILE_SEEDS:
+        raise ValueError("template-files requires 1..256 files")
+    entries, materials, total = [], {}, 0
+    for name in sorted(names, key=lambda value: value.encode("utf-8")):
+        relative = name[len("template-files/"):]
+        if (not relative or len(relative.encode("utf-8")) > 1024
+                or any(part in ("", ".", "..") for part in relative.split("/"))
+                or any(character in "\\%" or ord(character) < 32 or 127 <= ord(character) <= 159 for character in relative)):
+            raise ValueError(f"Invalid template file path: {relative}")
+        value = snapshot[name]
+        total += len(value)
+        if len(value) > MAX_FILE or total > MAX_FILE:
+            raise ValueError("template-files exceeds 16 MiB")
+        entries.append({"path": relative, "size": len(value),
+                        "sha256": hashlib.sha256(value).hexdigest(),
+                        "content_type": FILE_TYPES.get(PurePosixPath(relative).suffix.lower(), "application/octet-stream")})
+        materials["files/" + relative] = value
+    return {"manifest": {"version": 1, "root": "template-assets/", "entries": entries},
+            "materials": materials, "bytes": total}
+
+
+def check_seed_build_output(name, data, seeds):
+    if seeds is None:
+        return
+    if any(part in ("template-files", "template-assets") for part in PurePosixPath(name).parts):
+        raise ValueError(f"External template files must not enter the Web build: {name}")
+    # The platform requires this exact root icon independently of file seeds.
+    if name == "icon.png":
+        return
+    for seed, content in seeds["materials"].items():
+        if content and (data == content or len(content) >= 16 and (content in data or base64.b64encode(content) in data)):
+            raise ValueError(f"External template file embedded in Web build: {seed} in {name}")
+
+
+def encode_install_manifest(manifest, seeds):
+    if seeds is None:
+        return (json.dumps(manifest, ensure_ascii=False, allow_nan=False) + "\n").encode(), None
+    raw_files = json.dumps(seeds["manifest"], ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode()
+    base = json.dumps({**manifest, "format_version": 2, "requires": ["template_files_v1"]}, ensure_ascii=False, allow_nan=False).encode()
+    return base[:-1] + b',"files":' + raw_files + b"}\n", hashlib.sha256(raw_files).hexdigest()
+
+
+def unique_json_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"Duplicate metadata JSON key: {key}")
+        result[key] = value
+    return result
+
+
+def validate_backend_materials(metadata, snapshot, site):
+    repositories = {r["key"]: r for r in metadata.get("repositories", [])}
+    for repo in repositories.values():
+        prefix = "" if repo["path"] == "." else repo["path"] + "/"
+        if not any(name.startswith(prefix) for name in snapshot):
+            raise ValueError(f"Repository source missing: {repo['key']}")
+        for variable in repo.get("variables", []):
+            for name in variable["files"]:
+                if variable["placeholder"].encode() not in snapshot.get(prefix + name, b""):
+                    raise ValueError(f"Source placeholder missing: {repo['key']}/{name}")
+    for fn in metadata.get("functions", []):
+        repo = repositories.get(fn["repository"])
+        if repo is None:
+            raise ValueError(f"Function repository missing: {fn['key']}")
+        prefix = "" if repo["path"] == "." else repo["path"] + "/"
+        directory = fn.get("source_dir", "").rstrip("/")
+        if fn.get("source_dir") != "/" and (not directory.startswith("/") or any(part in ("", ".", "..") for part in directory[1:].split("/")) or "\\" in directory or "\0" in directory):
+            raise ValueError("Function source_dir must be a repository path starting with /")
+        prefix += directory[1:] + "/" if directory else ""
+        if not any(name.startswith(prefix) and "/" not in name[len(prefix):] and name.endswith(".go") for name in snapshot):
+            raise ValueError(f"Function entry Go source missing: {fn['key']}")
+    for variable in metadata.get("site_variables", []):
+        for name in variable["files"]:
+            if variable["placeholder"].encode() not in site.get("data/" + name, b""):
+                raise ValueError(f"Built site placeholder missing: {name}")
+
+
 def pack(source_zip, dist, entry, output, without_source=False):
     source = read_file(Path(source_zip))
     snapshot, source_size, source_count = source_files(source)
-    metadata = json.loads(snapshot["metadata.json"])
+    raw_metadata = snapshot["metadata.json"]
+    if len(raw_metadata) > MIB:
+        raise ValueError("metadata.json exceeds 1 MiB")
+    metadata = json.loads(raw_metadata.decode("utf-8"), object_pairs_hook=unique_json_object)
+    if type(metadata) is not dict:
+        raise ValueError("metadata.json must be an object")
     if type(metadata.get("database_required")) is not bool:
         raise ValueError("metadata.json requires an explicit database_required boolean")
+    if without_source and metadata.get("functions"):
+        raise ValueError("Function templates require source.zip to compile their backends")
+    seeds = template_file_materials(snapshot, metadata)
+    if seeds is not None and without_source:
+        raise ValueError("File templates require source.zip for server byte verification; --without-source is only available for templates without file_seeds")
     names = ["showcase/preview.html", "showcase/cover.webp"]
     if not without_source:
         names.append("showcase/prompt.md")
@@ -104,18 +228,27 @@ def pack(source_zip, dist, entry, output, without_source=False):
             sql_names[name] = target
     site = {"web.yaml": b""}
     dist = Path(dist)
+    if dist.is_symlink() or not dist.is_dir():
+        raise ValueError("Build directory must be a real directory")
     site_size = 0
     for file in sorted(dist.rglob("*")):
         if file.is_symlink():
             raise ValueError(f"Build contains a symlink: {file.relative_to(dist)}")
+        relative = file.relative_to(dist).as_posix()
+        if seeds is not None and any(part in ("template-files", "template-assets") for part in file.relative_to(dist).parts):
+            raise ValueError(f"External template files must not enter the Web build: {relative}")
         if file.is_file():
             data = read_file(file)
+            check_seed_build_output(relative, data, seeds)
             site_size += len(data)
             if site_size > MAX_FILE or len(site) >= 4097:
                 raise ValueError("Build exceeds the Web archive resource budget")
             site["data/" + file.relative_to(dist).as_posix()] = data
+        elif not file.is_dir():
+            raise ValueError(f"Build contains a nonregular entry: {relative}")
     if not entry or "data/" + entry not in site:
         raise ValueError("Build is missing its fixed entry")
+    validate_backend_materials(metadata, snapshot, site)
     compiled = archive(site)
     if len(compiled) > MAX_FILE:
         raise ValueError("site.tweb exceeds 16 MiB")
@@ -132,7 +265,14 @@ def pack(source_zip, dist, entry, output, without_source=False):
         files["icon.png"] = site["data/icon.png"]
     files["site.tweb"] = compiled
     manifest = {"metadata": metadata, "entry": entry, "database_required": metadata["database_required"], "variables": variables}
-    files["install.json"] = (json.dumps(manifest, ensure_ascii=False) + "\n").encode()
+    for field in ("private_database", "web_repository", "repositories", "functions", "site_variables"):
+        if field in metadata:
+            manifest[field] = metadata[field]
+    files["install.json"], file_manifest_digest = encode_install_manifest(manifest, seeds)
+    if len(files["install.json"]) > MIB:
+        raise ValueError("install.json exceeds 1 MiB")
+    if seeds is not None:
+        files.update(seeds["materials"])
     expanded = sum(map(len, files.values())) + site_size + (0 if without_source else source_size)
     entries = len(files) + len(site) + (0 if without_source else source_count)
     if expanded > MAX_EXPANDED or entries > MAX_ENTRIES or any(len(value) > MAX_FILE for value in files.values()):
@@ -141,7 +281,10 @@ def pack(source_zip, dist, entry, output, without_source=False):
     if len(data) > 32 * MIB:
         raise ValueError("install.zip exceeds 32 MiB")
     Path(output).write_bytes(data)
-    return {"name": metadata["name"], "file": str(Path(output).resolve()), "size": len(data), "sha256": hashlib.sha256(data).hexdigest(), "has_source": not without_source, "database_required": metadata["database_required"], "expanded_bytes": expanded, "entries": entries}
+    result = {"name": metadata["name"], "file": str(Path(output).resolve()), "size": len(data), "sha256": hashlib.sha256(data).hexdigest(), "has_source": not without_source, "database_required": metadata["database_required"], "expanded_bytes": expanded, "entries": entries}
+    if seeds is not None:
+        result.update({"format_version": 2, "file_count": len(seeds["manifest"]["entries"]), "file_bytes": seeds["bytes"], "file_manifest_sha256": file_manifest_digest})
+    return result
 
 
 if __name__ == "__main__":
@@ -150,6 +293,6 @@ if __name__ == "__main__":
     parser.add_argument("--dist", required=True, help="Clean build output directory")
     parser.add_argument("--entry", required=True, help="Fixed entry relative to dist")
     parser.add_argument("--output", required=True, help="Destination install.zip")
-    parser.add_argument("--without-source", action="store_true", help="Publish installation materials without source or customization prompt")
+    parser.add_argument("--without-source", action="store_true", help="No-file templates only: omit source and customization prompt")
     args = parser.parse_args()
     print(json.dumps(pack(args.source, args.dist, args.entry, args.output, args.without_source), ensure_ascii=False))