@tianacloud/agent-skills 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianacloud/agent-skills",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Tiana Cloud Skills for accounts, SQLite, Git, Functions and Web applications",
   "license": "Apache-2.0",
   "repository": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tiana",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Tiana Cloud account, SQLite, Git, Functions and Web application workflows",
   "author": {
     "name": "Tiana Cloud",

package/skills/tiana/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana Cloud 管理实例、安装 CLI、登录和恢复账
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.18"
+  version: "1.0.20"
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana
 ---
 

package/skills/tiana-function/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana 创建和管理 Go 后端服务，读取及保存 Git
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.18"
+  version: "1.0.20"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-function
 ---

package/skills/tiana-git/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana Git 管理 Git 实例和原生仓库，关联项目远
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.18"
+  version: "1.0.20"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-git
 ---

package/skills/tiana-sqlite/SKILL.md

@@ -4,7 +4,7 @@ description: 查询 Tiana SQLite 表结构、执行 SQL、选择数据库分支
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.18"
+  version: "1.0.20"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-sqlite
 ---

package/skills/tiana-web/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana 创建、修改、预览和发布 Web 应用。用户
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.18"
+  version: "1.0.20"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-web
 ---

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

@@ -73,6 +73,10 @@
    没有外置素材且发布者选择不分享源码时增加 `--without-source`。声明素材时保留
    source.zip，并生成与其逐字节相同的独立 `files/`、固定格式/能力及文件清单。
    复核目标环境已支持并启用该能力。脚本不替代数据、公开内容或应用行为检查。
+
+   若返回 `[preflight/...]`，保存原始报告，并逐项向作者说明阶段、字段／文件位置、原因和修复办法，可等义整理，不只转述为“打包失败”。字段位置中的数组下标从0开始；报告截断时说明仍有问题未展示，修复后再次检查。在既有任务授权内修正明确的机械错误；数据库需求、私有数据库访问方式或内容可公开性不明确时，先让作者判断。
+
+   修正公开副本后，重新执行第1–2步，直到原命令成功并返回本轮回执；编辑本地文件不会更新已有source.zip。这类前置失败不读取dist、不生成或覆盖安装包；已有output未更新，不能当作本次成功产物。尚未执行的构建材料和服务端检查仍需继续完成。
 3. 复查脚本输出的大小、SHA-256、源码选择及数据库依赖。有素材时再核对 file_count、file_bytes、file_manifest_sha256、源/独立素材字节和干净构建。安装包上限 32 MiB，单材料 16 MiB，所有解析层累计展开 128 MiB、5,000 个条目；site.tweb 同时遵守 16 MiB 和 4,097 条目的 Web 归档限制。超限时先移除无用依赖、压缩资源或精简材料。
 4. 执行 `tiana web publish-share-template WEB_ID --file /绝对路径/install.zip --wait --json`。上传峰值包含原模板材料、中转 ZIP 和新材料，全部计入当前租户额度。CLI 申请精确对象授权、直传上传并提交异步发布。
 5. 用 `tiana web status-share-template WEB_ID --json` 核对当前 `share.package_id`、Web ID、模板名称和 URL。支持配套字段的 CLI 还会保留 share.version、material_version 和 manifest.files；材料版本应等于本次完整安装包摘要。上传响应未知或等待被中断时先查询原状态，不把新上传当作恢复。发布失败时核对错误和中转清理。完整历史能力上线后旧版发布材料继续保留和计费，中转 ZIP 确认删除后才释放其占用额度。

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

@@ -15,6 +15,7 @@ MAX_FILE = 16 * MIB
 MAX_EXPANDED = 128 * MIB
 MAX_ENTRIES = 5000
 MAX_FILE_SEEDS = 256
+MAX_PREFLIGHT_ISSUES = 20
 FILE_TYPES = {
     ".webp": "image/webp", ".png": "image/png", ".jpg": "image/jpeg",
     ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml",
@@ -27,6 +28,16 @@ FILE_TYPES = {
 }
 
 
+class TemplatePreflightError(ValueError):
+    def __init__(self, issues):
+        super().__init__("\n".join([
+            "Template preflight failed; install.zip was not written or updated.",
+            *issues,
+            "Fix the source copy, re-export source.zip and rebuild from the same reviewed commit, then pack again.",
+            "Remaining packaging checks have not run; this is not publishing approval.",
+        ]))
+
+
 def archive(files):
     output = io.BytesIO()
     with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as result:
@@ -164,32 +175,220 @@ def unique_json_object(pairs):
     result = {}
     for key, value in pairs:
         if key in result:
-            raise ValueError(f"Duplicate metadata JSON key: {key}")
+            raise TemplatePreflightError([
+                "[preflight/metadata] metadata.json: duplicate object key.\n"
+                "  Fix: keep one intended value per key; remove the duplicate declaration.",
+            ])
         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']}")
+def preflight(snapshot, without_source):
+    # Only fixed fields and material names enter diagnostics, never input values.
+    if "metadata.json" not in snapshot:
+        raise TemplatePreflightError([
+            "[preflight/metadata] metadata.json: missing.\n"
+            "  Fix: include metadata.json at the root of the source snapshot.",
+        ])
+    raw_metadata = snapshot["metadata.json"]
+    if len(raw_metadata) > MIB:
+        raise TemplatePreflightError([
+            "[preflight/metadata] metadata.json: exceeds 1 MiB.\n"
+            "  Fix: reduce metadata to at most 1 MiB; keep application data outside metadata.",
+        ])
+    try:
+        metadata = json.loads(raw_metadata.decode("utf-8"), object_pairs_hook=unique_json_object)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        raise TemplatePreflightError([
+            "[preflight/metadata] metadata.json: invalid UTF-8 or JSON.\n"
+            "  Fix: save a valid UTF-8 JSON object before checking its fields.",
+        ]) from None
+    if type(metadata) is not dict:
+        raise TemplatePreflightError([
+            "[preflight/metadata] metadata.json: must be an object.\n"
+            "  Fix: put the template fields in a JSON object, not a list or scalar.",
+        ])
+
+    issues = []
+    missing = object()
+
+    def issue(location, problem, fix, stage="metadata"):
+        if len(issues) < MAX_PREFLIGHT_ISSUES:
+            if stage == "metadata":
+                location = "metadata.json:" + location
+            issues.append(f"[preflight/{stage}] {location}: {problem}.\n  Fix: {fix}")
+        elif len(issues) == MAX_PREFLIGHT_ISSUES:
+            issues.append(f"More problems found; showing the first {MAX_PREFLIGHT_ISSUES}. Fix these and run again.")
+
+    def string(value, location):
+        if value is missing:
+            issue(location, "missing required field", "add a nonempty string for this field.")
+        elif type(value) is not str or not value.strip():
+            issue(location, "requires a nonempty string", "supply text, not null, a number, a list or an object.")
+        else:
+            try:
+                value.encode("utf-8")
+                return value
+            except UnicodeEncodeError:
+                issue(location, "contains invalid Unicode", "replace unpaired Unicode surrogates with valid text.")
+        return None
+
+    def objects(value, location):
+        if type(value) is not list:
+            issue(location, "requires an array", "use an array of objects; omit this optional field if unused.")
+            return
+        for index, item in enumerate(value):
+            where = f"{location}[{index}]"
+            if type(item) is not dict:
+                issue(where, "requires an object", "supply the fields of this declaration in a JSON object.")
+            else:
+                yield where, item
+
+    def variables(value, location, prefix):
+        for where, variable in objects(value, location):
+            for field in ("name", "description"):
+                string(variable.get(field, missing), f"{where}.{field}")
+            placeholder = string(variable.get("placeholder", missing), f"{where}.placeholder")
+            files = variable.get("files")
+            if type(files) is not list or not files:
+                issue(f"{where}.files", "requires a nonempty array of file paths",
+                      "list the files that contain this variable's placeholder.")
+                continue
+            for index, value in enumerate(files):
+                at = f"{where}.files[{index}]"
+                name = string(value, at)
+                # site_variables refer to dist, which is checked only after preflight.
+                if name is None or prefix is None:
+                    continue
+                content = snapshot.get(prefix + name)
+                if content is None:
+                    issue(at, "declared source file is missing",
+                          "include this file in source.zip or correct its path relative to the declared source root.")
+                elif placeholder is not None and placeholder.encode("utf-8") not in content:
+                    issue(at, "Source placeholder missing",
+                          "restore the declared placeholder in this file or correct the variable declaration.")
+
+    for field in ("name", "display_name", "description"):
+        string(metadata.get(field, missing), field)
+    if type(metadata.get("database_required")) is not bool:
+        issue("database_required", "requires a JSON boolean",
+              "use true or false, not a quoted value, after confirming the app's database needs.\n"
+              "  Declared schema/seeds require true; do not remove required SQL just to pass.")
+    if "private_database" in metadata and type(metadata["private_database"]) is not bool:
+        issue("private_database", "requires a JSON boolean",
+              "use true or false without quotes; true keeps the database off the browser's Web binding.")
+
+    sql = []
+    for field in ("schema", "seeds"):
+        if field not in metadata:
+            continue
+        name = string(metadata[field], field)
+        if name is not None:
+            sql.append(name)
+            if name not in snapshot:
+                issue(field, "declared SQL file is missing",
+                      "include the declared SQL file in source.zip or correct its path relative to the snapshot root.")
+    if sql and metadata.get("database_required") is False:
+        issue("database_required", "SQL materials require database_required=true",
+              "confirm the database dependency and use true for SQL-backed apps; do not remove required SQL just to pass.")
+    has_file_seeds = any(name == "template-files" or name.startswith("template-files/") for name in snapshot)
+    if "file_seeds" in metadata:
+        if metadata["file_seeds"] != "template-files":
+            issue("file_seeds", "must be the string template-files",
+                  "use the declared template-files directory; omit this optional field only when no file seeds are needed.")
+        elif not has_file_seeds:
+            issue("file_seeds", "declared material files are missing",
+                  "include the reviewed files under template-files/ in source.zip.")
+    elif has_file_seeds:
+        issue("file_seeds", "missing declaration for template-files",
+              "declare file_seeds as template-files after reviewing the files for public distribution.")
+
+    variables(metadata.get("variables", []), "variables", "")
+    repositories = {}
+    for where, repo in objects(metadata.get("repositories", []), "repositories"):
+        key = string(repo.get("key", missing), f"{where}.key")
+        path = string(repo.get("path", missing), f"{where}.path")
+        prefix = None
+        if path is not None:
+            if path != "." and ("\\" in path or any(part in ("", ".", "..") for part in path.split("/"))):
+                issue(f"{where}.path", "requires a relative source directory",
+                      "use '.' or a relative directory without empty, dot or parent segments.")
+            else:
+                prefix = "" if path == "." else path + "/"
+                if not any(name.startswith(prefix) for name in snapshot):
+                    issue(f"{where}.path", "Repository source missing",
+                          "include the reviewed repository snapshot under this directory.")
+                    prefix = None
+        if key is not None:
+            if key in repositories:
+                issue(f"{where}.key", "duplicate repository key", "give each logical repository a unique key.")
+            else:
+                repositories[key] = prefix
+        variables(repo.get("variables", []), f"{where}.variables", prefix)
+    repositories_typed = type(metadata.get("repositories", [])) is list
+    if "web_repository" in metadata:
+        key = string(metadata["web_repository"], "web_repository")
+        if key is not None and repositories_typed and key not in repositories:
+            issue("web_repository", "references an undeclared repository",
+                  "use the key of the declared repository containing the Web source.")
+
+    function_keys = set()
+    for where, fn in objects(metadata.get("functions", []), "functions"):
+        key = string(fn.get("key", missing), f"{where}.key")
+        string(fn.get("name", missing), f"{where}.name")
+        repo = string(fn.get("repository", missing), f"{where}.repository")
+        directory = string(fn.get("source_dir", missing), f"{where}.source_dir")
+        if key is not None:
+            if key in function_keys:
+                issue(f"{where}.key", "duplicate function key", "give each function a unique key.")
+            function_keys.add(key)
+        if repo is not None and repositories_typed and repo not in repositories:
+            issue(f"{where}.repository", "Function repository missing", "reference a declared repository key.")
+        if directory is not None:
+            directory = directory.rstrip("/")
+            if fn["source_dir"] != "/" and (not directory.startswith("/") or any(part in ("", ".", "..") for part in directory[1:].split("/")) or "\\" in directory or "\0" in directory):
+                issue(f"{where}.source_dir", "requires a repository path starting with /",
+                      "use the function's actual source directory, without dot or parent segments.")
+            elif repo in repositories and repositories[repo] is not None:
+                prefix = repositories[repo] + (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):
+                    issue(f"{where}.source_dir", "Function entry Go source missing",
+                          "include the function's Go entry source directly in this repository directory.")
+        for field in ("parameters", "cors", "database"):
+            if field in fn and type(fn[field]) is not dict:
+                issue(f"{where}.{field}", "requires an object", "use the documented object fields or omit this optional declaration.")
+        database = fn.get("database")
+        if type(database) is dict:
+            endpoint = string(database.get("endpoint_parameter", missing), f"{where}.database.endpoint_parameter")
+            token = string(database.get("token_parameter", missing), f"{where}.database.token_parameter")
+            if endpoint is not None and endpoint == token:
+                issue(f"{where}.database", "requires distinct endpoint and token parameter names",
+                      "declare separate backend parameters; credentials are supplied during installation.")
+            if metadata.get("database_required") is False:
+                issue(f"{where}.database", "requires database_required=true",
+                      "confirm the backend database dependency; do not remove required configuration just to pass.")
+    variables(metadata.get("site_variables", []), "site_variables", None)
+
+    names = ["showcase/preview.html", "showcase/cover.webp"]
+    if not without_source:
+        names.append("showcase/prompt.md")
+    fixes = [
+        "add the self-contained preview HTML to the source snapshot.",
+        "add the WebP cover made from the reviewed preview to the source snapshot.",
+        "add the customization prompt for source-sharing mode to the source snapshot.",
+    ]
+    for name, fix in zip(names, fixes):
+        if name not in snapshot:
+            issue(name, "missing", fix, "showcase")
+        elif name == "showcase/preview.html" and len(snapshot[name]) > 500_000:
+            issue(name, "exceeds 500,000 bytes",
+                  "simplify the self-contained preview to at most 500,000 bytes before compression.", "showcase")
+    if issues:
+        raise TemplatePreflightError(issues)
+    return metadata, names
+
+
+def validate_site_variables(metadata, site):
     for variable in metadata.get("site_variables", []):
         for name in variable["files"]:
             if variable["placeholder"].encode() not in site.get("data/" + name, b""):
@@ -199,25 +398,13 @@ def validate_backend_materials(metadata, snapshot, site):
 def pack(source_zip, dist, entry, output, without_source=False):
     source = read_file(Path(source_zip))
     snapshot, source_size, source_count = source_files(source)
-    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")
+    metadata, names = preflight(snapshot, without_source)
     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")
     files = {name: snapshot[name] for name in names}
-    if len(files["showcase/preview.html"]) > 500_000:
-        raise ValueError("showcase/preview.html exceeds 500,000 bytes")
     sql_names = {}
     for field, target in (("schema", "schema.sql"), ("seeds", "seed.sql")):
         name = metadata.get(field)
@@ -248,7 +435,7 @@ def pack(source_zip, dist, entry, output, without_source=False):
             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)
+    validate_site_variables(metadata, site)
     compiled = archive(site)
     if len(compiled) > MAX_FILE:
         raise ValueError("site.tweb exceeds 16 MiB")
@@ -295,4 +482,8 @@ if __name__ == "__main__":
     parser.add_argument("--output", required=True, help="Destination install.zip")
     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))
+    try:
+        result = pack(args.source, args.dist, args.entry, args.output, args.without_source)
+    except TemplatePreflightError as error:
+        parser.exit(1, f"{error}\n")
+    print(json.dumps(result, ensure_ascii=False))