@tianacloud/agent-skills 1.0.10 → 1.0.12

package/skills/tiana-git/references/source-releases.md

@@ -42,10 +42,10 @@ git remote add tiana 'tiana://HOST:PORT/repo.git'
 ## 发布对应源码的当前内容
 
 1. 提交应用源码、构建配置、锁文件、SQL 和迁移。生成物只包含模块与资源，不含 tiana.app.json。应用源码提交和推送仍须在用户授权范围内；验证远端分支/标签确实指向将要构建的提交，不改写已分配的源码引用。
-2. 从干净、已确认的源码提交按工程 README 构建。用实际 Git ID 和完整小写 40/64 位提交号更新项目参数；若构建脚本输出 `TIANA_PROJECT_PARAMS`，核对其值与真实源码及远端提交一致。项目参数不写进 dist。不得只修改参数冒充重新构建。
-3. 新建项目：`tiana web create NAME --entry assets/app.js --database-instance-id DB_ID --git-instance-id GIT_ID --source-commit FULL_HASH --json`。既有项目先读取最新 project_revision，再用 `tiana web update WEB_ID --expected-revision REV --git-instance-id GIT_ID --source-commit FULL_HASH --json`。Git ID 可先绑定、commit 可暂缺；commit 非空时必须有 Git。entry 创建后不可修改，没有 styles/rendering/routing 字段。
-4. 发布该提交产物：`tiana web publish WEB_ID --dir DIST --json`，保存 publish_id 和归档 SHA256，随后 `tiana web status WEB_ID --publish-id PUBLISH_ID --json` 确认 ACTIVATED 和 serving_sha256。项目参数和归档分别更新，MGR 不管理发布。参数更新成功但文件发布失败时报告部分完成；不伪称源码、项目参数、S3 对象原子一致。
-5. 保存 Web/实例 ID、Git ID、远端引用、源码 commit、publish_id、校验和及托管链接。没有 Web 版本列表或恢复接口；Git 源码历史由 Git 管理。发布结果未知时只查询，禁止自动重放 PUT。用户不采用 Tiana Git 时保留原托管平台，不填写虚构关联。
+2. 从干净、已确认且已推送的 Git 提交按工程 README 构建。记录 Git ID 和完整源码提交号，核对远程引用；提交号作为本次构建和交付证据，不作为 Web 项目参数。构建期间保持源码不变。
+3. 新建项目：`tiana web create NAME --entry assets/app.js --database-instance-id DB_ID --git-instance-id GIT_ID --json`。后端服务访问数据库的应用省略数据库绑定。已有项目沿用创建时固定的数据库、Git 和 entry；名称、备注在 Console 实例基础信息编辑。
+4. 发布该提交产物：`tiana web publish WEB_ID --dir DIST --json`，保存 publish_id 和归档 SHA256，随后 `tiana web status WEB_ID --publish-id PUBLISH_ID --json` 确认 ACTIVATED 和 serving_sha256。Web 创建受理后先核对实例就绪，再发布；结果未知时先查询，不重建资源。
+5. 保存 Web/实例 ID、Git ID、远端引用、源码 commit、publish_id、校验和及托管链接。Git 源码历史由 Git 管理。发布结果未知时只查询，禁止自动重放 PUT。用户不采用 Tiana Git 时保留原托管平台，不填写虚构关联。
 
 ## 构建时传入源码提交
 
@@ -80,7 +80,7 @@ if ($LASTEXITCODE -ne 0) { throw '读取构建后的 Git 提交失败' }
 if ($buildStatus -or $buildCommit -ne $sourceCommit) { throw '构建期间源码变化，请从确认的提交重新构建' }
 ```
 
-以上命令在同一次工具调用中执行；构建期间保持源码不变。核对构建输出参数的 `source_commit` 与本次 `$sourceCommit`、远程版本引用一致后再上传。脚本只检查提交号格式，不证明源码归属；调用方的 Git 核验是发布流程的一部分。
+以上命令在同一次工具调用中执行；构建期间保持源码不变。核对本次 `$sourceCommit` 与远程版本引用一致，并从该提交构建后再上传。脚本只检查提交号格式，不证明源码归属；调用方的 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.10"
+  version: "1.0.12"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-sqlite
 ---
@@ -17,13 +17,16 @@ metadata:
 
 **本会话首次使用任一 Tiana 技能时，先完成以下步骤，再开始登录、查询模板或操作应用：**
 
-1. 执行 `tiana version`，按[开始使用](../tiana/references/getting-started.md)核验最低版本；缺少 CLI 或版本过低时，先完成安装或经用户确认的升级。
-2. CLI 满足最低版本后，**仍须实际执行** `tiana version check --skills-version 1.0.10 --json`；版本号取实际加载的 metadata.version。这一步检查是否有更新版本。
-3. 实际发起检查命令后，才在会话中记为已尝试，并保留返回结果或执行错误。仅运行 `tiana version` 只完成第 1 步。
+CLI 与 Skills 各自独立比较本包的 npm 最新正式版。下面的版本检查与安装只访问公共包仓库，不需要 Tiana 登录，不操作 Tiana 云端资源；用户要求暂不登录或不操作云端资源时仍执行。用户明确要求离线、禁止联网或禁止安装时遵从该限制。
 
-四个技能共享这份实际调用记录；后续轮次、重复加载或切换技能复用记录，失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
+1. 执行 `tiana version`，按[开始使用](../tiana/references/getting-started.md)核验最低版本；缺少 CLI 或版本过低时，自动安装 npm latest 正式版并重新核验。
+2. CLI 满足最低版本后，从本会话实际加载的 SKILL.md 的 `metadata.version` 取得 `SKILLS_VERSION`，在同一次 shell 调用中赋值并**实际执行** `tiana version check --skills-version "$SKILLS_VERSION" --json`。这一步检查是否有更新版本。
+3. `updates` 中 CLI 或 Skills 有新正式版时，**自动安装各项实际返回的 `latest_version`，无需再次询问**；`should_notify=false` 也执行。Skills 按新版包完整安装，覆盖已有技能并补齐新增技能。各连接器初始版本仅用于分发，后续更新独立于连接器发版；安装目标及重载按[更新流程](../tiana/references/getting-started.md#更新)，连接器内使用时再读其中链接的宿主说明。
+4. 在对话中简短报告实际 CLI/Skills 版本、检查状态与更新结果（包括新增技能及是否需要重载）；检查不可用时明确说明未能确认是否有新版，更新失败时说明实际错误。
 
-仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](../tiana/references/getting-started.md#更新)。
+实际发起检查命令后才记录已尝试，保留检查结果或执行错误，以及两个包的安装与核验结果。各 Tiana 技能共享这份记录；后续轮次、重复加载或切换技能复用记录，每个包失败后本会话不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。仅运行 `tiana version` 只完成第 1 步。
+
+CLI 仍管理检查缓存和共同的 24 小时提醒额度；该额度不限制自动更新或本会话首次结果报告。更新核验完成后继续原任务；失败时按更新流程判断可否继续。
 
 ## 查询与命令行
 

package/skills/tiana-web/SKILL.md

@@ -1,29 +1,36 @@
 ---
 name: tiana-web
-description: 使用 Tiana 创建、修改、预览和发布 Web 应用。用户要求制作账单、笔记、日历或其他 Web app 时使用；根据实时模板目录和需求决定采用模板或直接开发，并连接 SQLite 和 Git。用户要求把已有 Web app 发布为模板、分享可安装应用链接时也使用。
+description: 使用 Tiana 创建、修改、预览和发布 Web 应用。用户要求制作账单、笔记、日历或其他 Web app 时使用；根据实时模板目录和需求决定采用模板或直接开发，并按业务选择直接连接 SQLite 或通过后端服务访问数据库。用户要求把已有 Web app 发布为模板、分享可安装应用链接时也使用。
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.10"
+  version: "1.0.12"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-web
 ---
 
 # Tiana Web
 
-安装、登录和通用实例管理见 [Tiana](../tiana/SKILL.md)，SQL 与连接见 [Tiana SQLite](../tiana-sqlite/SKILL.md)，源码见 [Tiana Git](../tiana-git/SKILL.md)。
+安装、登录和通用实例管理见 [Tiana](../tiana/SKILL.md)，SQL 与连接见 [Tiana SQLite](../tiana-sqlite/SKILL.md)，后端服务见 [Tiana Function](../tiana-function/SKILL.md)，源码见 [Tiana Git](../tiana-git/SKILL.md)。
 
 ## 每个会话一次的更新检查
 
 **本会话首次使用任一 Tiana 技能时，先完成以下步骤，再开始登录、查询模板或操作应用：**
 
-1. 执行 `tiana version`，按[开始使用](../tiana/references/getting-started.md)核验最低版本；缺少 CLI 或版本过低时，先完成安装或经用户确认的升级。
-2. CLI 满足最低版本后，**仍须实际执行** `tiana version check --skills-version 1.0.10 --json`；版本号取实际加载的 metadata.version。这一步检查是否有更新版本。
-3. 实际发起检查命令后，才在会话中记为已尝试，并保留返回结果或执行错误。仅运行 `tiana version` 只完成第 1 步。
+CLI 与 Skills 各自独立比较本包的 npm 最新正式版。下面的版本检查与安装只访问公共包仓库，不需要 Tiana 登录，不操作 Tiana 云端资源；用户要求暂不登录或不操作云端资源时仍执行。用户明确要求离线、禁止联网或禁止安装时遵从该限制。
 
-四个技能共享这份实际调用记录；后续轮次、重复加载或切换技能复用记录，失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
+1. 执行 `tiana version`，按[开始使用](../tiana/references/getting-started.md)核验最低版本；缺少 CLI 或版本过低时，自动安装 npm latest 正式版并重新核验。
+2. CLI 满足最低版本后，从本会话实际加载的 SKILL.md 的 `metadata.version` 取得 `SKILLS_VERSION`，在同一次 shell 调用中赋值并**实际执行** `tiana version check --skills-version "$SKILLS_VERSION" --json`。这一步检查是否有更新版本。
+3. `updates` 中 CLI 或 Skills 有新正式版时，**自动安装各项实际返回的 `latest_version`，无需再次询问**；`should_notify=false` 也执行。Skills 按新版包完整安装，覆盖已有技能并补齐新增技能。各连接器初始版本仅用于分发，后续更新独立于连接器发版；安装目标及重载按[更新流程](../tiana/references/getting-started.md#更新)，连接器内使用时再读其中链接的宿主说明。
+4. 在对话中简短报告实际 CLI/Skills 版本、检查状态与更新结果（包括新增技能及是否需要重载）；检查不可用时明确说明未能确认是否有新版，更新失败时说明实际错误。
 
-仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](../tiana/references/getting-started.md#更新)。
+实际发起检查命令后才记录已尝试，保留检查结果或执行错误，以及两个包的安装与核验结果。各 Tiana 技能共享这份记录；后续轮次、重复加载或切换技能复用记录，每个包失败后本会话不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。仅运行 `tiana version` 只完成第 1 步。
+
+CLI 仍管理检查缓存和共同的 24 小时提醒额度；该额度不限制自动更新或本会话首次结果报告。更新核验完成后继续原任务；失败时按更新流程判断可否继续。
+
+## 数据与素材存储
+
+创建、修改应用或制作模板前，按[数据与素材存储](references/storage-and-assets.md)核对现有实现与干净构建。程序随 Web 打包；优化后、编码前不超过 16 KiB 的静态小图片内嵌 JS；其他外置素材与用户文件使用文件存储，持久业务记录使用数据库。含预置素材时读取[模板素材文件](references/template-files.md)，准备本次应用目录或格式 2 安装材料，并核验目标环境能力。
 
 ## 将已有应用发布为模板
 
@@ -35,15 +42,27 @@ metadata:
 
 用户只需描述应用。根据本次返回的 `name`、`description` 判断核心功能、数据模型与可定制范围：合适的模板可加速制作，局部差异在工程中修改；没有合适模板就直接开发。已有工程继续修改自己的工程。以需求为依据决定，不要求用户选择模板，也不硬编码模板名称或模板版本。
 
+## 选择数据访问方式
+
+简单应用优先直接访问 SQLite。复杂业务、敏感数据或配置、需要限制用户可见数据时，采用后端服务，必须阅读[带后端服务的 Web 开发流程](references/backend-apps.md)。默认复用 Web 的 Git，后端私有数据库不绑定 Web。
+
+本 skill 负责选择访问方式、前端开发、Web 资源绑定、预览、发布与分享验收。后端的创建、源码、参数配置与读取、数据库访问和编译发布由 [Tiana Function](../tiana-function/SKILL.md)负责；取得后端发布结果后回到本流程完成前端接入。
+
+## 展示当前用户
+
+应用需要展示登录用户、昵称或区分用户与应用所属租户时，阅读[当前用户信息](references/csr-apps.md#当前用户信息)，使用同源会话接口取得实际字段。
+
+需要 App 作者专属界面或初始权限管理时，用会话的 `is_app_owner` 判断当前用户是否为该 Web 的创建者，具体见[App 作者判断](references/csr-apps.md#app-作者判断)。后端权限校验交由 Tiana Function 的 `caller.IsAppOwner()`，前端只控制展示。
+
 ## 创建、初始化和发布
 
-1. 阅读 [Web 开发与发布](references/csr-apps.md)及 [JavaScript 连接](../tiana-sqlite/references/js-sdk.md)。新应用默认为本次需求创建所需的 SQLite 和 Git 实例，并等待就绪、保存实际 ID；仅在用户明确指定已有实例时核实后复用。修改已有工程时沿用其已确认绑定。实例名称按当前应用命名，模板变量使用 CLI 回执中的 ID。先确定最终入口路径；创建 Web 时用 `--entry` 固定入口，配置实际数据库和 Git 绑定，并等就绪。Web ID 取 `web create` 返回的 `data.id`。
+1. 阅读 [Web 开发与发布](references/csr-apps.md)；前端直连模式再读 [JavaScript 连接](../tiana-sqlite/references/js-sdk.md)。新应用默认为本次需求创建所需的 SQLite 和 Git 实例，并等待就绪、保存实际 ID；仅在用户明确指定已有实例时核实后复用。修改已有工程时沿用其已确认绑定。实例名称按当前应用命名，模板变量使用 CLI 回执中的 ID。先确定最终入口路径；创建 Web 时用 `--entry` 固定入口，按所选访问方式配置数据库或后端服务绑定，并配置 Git 绑定，并等就绪。Web ID 取 `web create` 返回的 `data.id`。
 2. 采用模板时，执行 `tiana web init-template NAME --dir PROJECT_DIR --json`。PROJECT_DIR 是用户项目的不存在目录，位于技能安装目录之外。CLI 下载并原样解压；按 [模板初始化](references/template-init.md)读取工程根部 `metadata.json`，由 Agent 完成全部变量替换及 SQLite 数据初始化。
 3. 直接开发时，使用 [固定 index.html](references/index.html)、哈希路由、支持动态账号鉴权的 SDK，按实际数据库结构编写应用及构建清单。
-4. **模板和直接开发都由 Agent 处理数据库初始化。** 模板先执行已配置且存在的 schema，再执行已配置且存在的 seeds；两项独立跳过，SQL 失败先核对结果并停止后续发布。
+4. **模板和直接开发都由 Agent 处理数据库初始化。** 模板先执行已配置且存在的 schema，再执行已配置且存在的 seeds；两项独立跳过，SQL 失败先核对结果并停止后续发布。普通源码开发还须按[模板素材文件](references/template-files.md)准备新 Web ID 的预置素材；`web publish` 只发布程序包。
 5. 构建前按[应用图标](references/csr-apps.md#应用图标)准备真实 PNG：使用用户指定图片或已有的合适图标；需要制作时优先调用可用的 AI 生图工具，以应用核心功能设计图形图标。图片保存到源码，查看缩小后的效果，并核验干净构建根目录和发布包中都有该图片。
-6. 按用户需求完成交互和定制，安装依赖并从确定源码提交构建。按 [源码版本流程](../tiana-git/references/source-releases.md)完成源码同步，用 `web publish` 发布当前归档，再用 `web status --publish-id` 核对。除非用户仅要求本地开发，交付实际托管地址、资源 ID 和对应源码提交；未验证的阶段如实说明。
+6. 按用户需求完成交互和定制。采用后端服务时，先完成[后端交接与接入验证](references/backend-apps.md)，再交付可用前端。安装依赖并从确定源码提交构建；按 [源码版本流程](../tiana-git/references/source-releases.md)完成源码同步，用 `web publish` 发布当前归档，再用 `web status --publish-id` 核对。除非用户仅要求本地开发，交付实际托管地址、资源 ID 和对应源码提交；未验证的阶段如实说明。
 
-## 文件上传、预览与下载
+## 素材、文件上传、预览与下载
 
-应用需要文件存储时，阅读[WebApp 文件存储](references/files.md)，核对配套候选环境后使用平台提供的 `context.files`。先创建 WebApp 获得 ID 即可本地预览，无需先发布；文件路径相对于该 WebApp 的目录。
+应用有外置素材或用户文件时，阅读[WebApp 文件存储](references/files.md)，核对配套目标环境后使用平台提供的 `context.files`。先创建 WebApp 获得 ID 即可本地预览，无需先发布；文件路径相对于该 WebApp 的目录。没有上传 UI 的应用也须核对预置素材，不能依赖作者的文件链接。

package/skills/tiana-web/references/backend-apps.md

@@ -0,0 +1,40 @@
+# 带后端服务的 Web 开发流程
+
+仅在应用需要后端时使用。Web skill 负责以下编排与浏览器验收；后端实现交给 [Tiana Function](../../tiana-function/SKILL.md)，具体命令、参数格式和 Go 示例由该 skill 维护。
+
+## 1. 确定共仓资源
+
+修改已有 Web 时读取实际 Git 绑定和后端服务列表，复用对应资源。新建应用时先创建一份 Git，在创建 Web 与后端服务时共同关联。已有 Web 沿用创建时固定的关联；未关联 Git 时为后端服务创建仓库，并记录前端与后端的实际源码位置。用户指定其他仓库时按其选择，模板工程按已声明的仓库关系处理。
+
+将实际 Git ID、已知后端服务 ID、接口需求和数据库依赖交给 Tiana Function。新服务明确使用这个 Git；由 Function skill 确定并保存 source_dir。前端和后端编辑保持同仓其他文件，共享仓库的后续提交基于最新 main，避免用前端旧副本覆盖后端或构建写回的依赖文件。
+
+Web 只绑定前端实际需要直连的数据库；仅供后端使用的数据库不绑定 Web。纯后端访问模式创建 Web 时省略 `--database-instance-id`，并用 `--git-instance-id` 关联已确定的共享 Git。
+
+## 2. 完成后端交接
+
+向 Tiana Function 提供业务接口、所需参数的名称和用途、目标数据库及表结构；敏感值按该 skill 的参数配置流程处理，不作为前端构建变量。由它完成源码保存、编译发布和后端核验，返回：
+
+- 后端服务 ID、Git ID 和实际 source_dir。
+- 已发布的源码提交、构建回执及接口路径、方法、请求和响应格式。
+- 必需参数的名称及配置／生效结果，不返回参数值；缺失配置或待生效状态明确列出。
+
+仅保存 Git 或构建受理不能视为后端就绪。后端失败时留在后端步骤处理；前端可以继续开发，但不能将真实调用未通过的应用交付为可用。
+
+## 3. 绑定并接入前端
+
+```sh
+tiana web functions get WEB_ID --json
+tiana web functions set WEB_ID --function-id FUNCTION_ID --expected-revision REVISION --json
+```
+
+使用实际 ID 和 get 返回的 revision。set 替换完整列表；保留仍需使用的服务，多个服务重复传 `--function-id`，冲突后重读列表。不传 ID 会清空绑定。
+
+前端使用平台提供的 `context.functions.fetch(FUNCTION_ID, "/orders", {method: "GET"})`。页面只保存服务 ID 和业务接口契约，所需调用凭据由平台提供；数据库 Token、第三方 API Key 等只留在后端参数中。按 [Web 开发与发布](csr-apps.md)处理入口、交互、构建和发布。
+
+## 4. 验证实际可用
+
+先用 `tiana web serve WEB_ID --dir dist` 验证接口及页面，再发布前端并核对实际托管页面。已有后端可能仍运行旧版本：按 Function skill 核对实际接口结果，不能仅凭最新构建成功判断当前请求使用新版。
+
+需要分享时，用另一账号通过 Site 登录打开应用，完成业务读写，确认只取得所绑定后端服务的调用权限，浏览器的 Bootstrap、网络响应和发布产物中没有后端私有数据库凭据或第三方密钥。本地预览的开发者账号不能替代此验收。按业务要求验证各用户的数据范围。
+
+交付托管地址、资源关联、源码提交及实测结果；缺少配置、未执行的环境验收如实列出。制作可安装模板另按[后端服务模板](function-templates.md)处理复制、参数映射与跨账号安装。

package/skills/tiana-web/references/csr-apps.md

@@ -12,7 +12,59 @@
 
 模板提供 `<div id="app"></div>`。`entry` 指定的模块按正常方式启动并渲染应用。需要数据库连接时，调用 `window.tiana.connection()` 获取连接元信息，使用 `window.tiana.auth` provider 提供动态凭据；凭据只保存在内存中。加载指示器是临时的，与应用样式隔离。
 
-## 确认账号与数据库
+## 当前用户信息
+
+托管 Web App 使用 `GET ./_tiana/session` 读取当前登录用户，路径相对于应用入口 `/web/<web_id>/`，请求携带同源 Cookie。成功响应的关键字段如下：
+
+| 字段 | 用途 |
+| --- | --- |
+| `status` | 登录有效时为 `SESSION_ACTIVE`。 |
+| `user.user_id` | 稳定的用户 ID，用于关联应用内的用户资料。 |
+| `user.username` | 账号用户名。 |
+| `user.display_name` | 显示昵称；展示时优先用它，空值时使用 username。 |
+| `tenant_id` | 当前访问用户的租户 ID。 |
+| `app_tenant_id` | Web App 所属租户 ID；跨租户分享时可与 tenant_id 不同。 |
+| `role` | 用户在其当前租户中的角色。 |
+| `is_app_owner` | 当前用户是否为这个 Web App 的创建者；布尔值，与租户 role 独立。 |
+| `membership_revision` | 当前租户成员关系的版本。 |
+| `session.client`、`session.expires_at` | 会话类型（`web`）和到期时间。 |
+
+例如在入口中显示当前用户的昵称：
+
+```js
+export async function mount(root) {
+  const response = await fetch('./_tiana/session', {
+    credentials: 'same-origin',
+    cache: 'no-store',
+  });
+  if (!response.ok) throw new Error('无法读取当前用户，请重新登录。');
+  const session = await response.json();
+  const nickname = session.user.display_name || session.user.username;
+  const greeting = document.createElement('p');
+  greeting.textContent = `你好，${nickname}`;
+  root.append(greeting);
+}
+```
+
+只需身份 ID 时，托管运行时也提供 `window.tiana.user.id`、`window.tiana.user.tenantId` 和 `window.tiana.appTenantId`，或从 mount 的第二个参数 context 读取相同属性；context.user 当前只有 id 与 tenantId，昵称使用上述会话接口读取。
+
+当前 Site 会话接口不返回头像。需要应用内头像或自定义昵称时，以 user.user_id 关联应用自己的资料记录。会话失效时停止使用旧资料并提示重新登录；身份和资料只作为运行时数据，不固化到前端发布产物。
+
+### App 作者判断
+
+需要只向 App 作者展示初始化、成员或权限管理入口时，读取上面的同源会话后使用：
+
+```js
+const canManageApp = session.is_app_owner === true;
+```
+
+App 作者是当前 Web 的创建者，`role` 的 `tenant_owner` 表示访问者自己所选租户的所有者，不能用来判断 App 作者。模板安装产生的新 Web 以新创建者为作者。前端判断用于展示；敏感操作交给 [Tiana Function](../../tiana-function/references/go-backend.md#app-作者与初始权限)在后端通过 `caller.IsAppOwner()` 校验。初始化数据和权限管理接口在每次请求中检查，不能仅隐藏按钮。配套 CLI Web 本地预览也返回 `is_app_owner`，正式分享仍需用作者与其他账号分别验收。
+
+## 选择后端与确认资源
+
+简单应用优先采用下文的浏览器直连 SQLite；复杂或敏感应用必须按[带后端服务的 Web 开发流程](backend-apps.md)完成后端交接和前端接入。下面两个直连章节只适用于浏览器访问数据库的部分；后端模式完成该流程后继续本文件的体验、图标与发布步骤。
+
+## 直连 SQLite：确认账号与数据库
 
 已确认 CLI 具备本流程命令时直接使用。命令缺失时按[开始使用](../../tiana/references/getting-started.md)安装匹配版本。
 
@@ -20,9 +72,9 @@
 2. 项目已记录且已核实可用的数据库实例 ID 可直接复用，无需列举实例。否则用 `tiana sqlite list/show` 查找；确实没有可用数据库时执行一次 `tiana sqlite create NAME --wait`，保存完整实例 ID。中断后核实原请求和实例，不重复创建。
 3. 复用已提供的实际表结构；缺少时执行 `tiana sqlite shell INSTANCE -e "SELECT name, sql FROM sqlite_schema WHERE type='table' ORDER BY name LIMIT 100" --format json`。将表结构和迁移文件保存在项目中。对已核对的 SQL 文件执行 `tiana sqlite shell INSTANCE -f schema.sql --format json`。`-e` 接受一条语句，多语句使用 `-f`。动态数据按 [JavaScript 数据库连接](../../tiana-sqlite/references/js-sdk.md)使用参数化 SQL。
 4. 复用项目中已记录、已核实的 Web ID；未记录时先用 `tiana web list --json` 查找并核实，重名时依据实际 ID 确认归属；首次创建时执行一次 `tiana web create "应用名称" -m "应用描述" --entry assets/app.js --database-instance-id DATABASE_ID --json`，保存返回的 `data.id`。Web ID 仅由 MGR 生成；CLI 不生成或提交 Web ID；描述为可选元数据（`-m`/`--description`，最多 1024 个 UTF-8 字节），名称仅用于展示，不能用名称推导 ID，不能自行指定 ID。结果未知时保持名称、描述和所有创建参数不变，重复同一条 create 命令恢复原请求，不删除待完成记录、不另发创建请求。成功后继续构建、预览或发布时复用该 ID，不重复创建。
-5. 将非敏感 Web ID 和数据库 ID 保存在项目交付记录中。entry 仅能在 create 指定，包括省略后的纯文件托管类型；创建后不可修改，publish/serve/update 都不能覆盖。数据库、Git、名称、描述可用带 expected_revision 的 web update 修改。
+5. 将非敏感 Web ID 和数据库 ID 保存在项目交付记录中。entry 仅能在 create 指定，包括省略后的纯文件托管类型；创建后不可修改，publish/serve 都不能覆盖。数据库和 Git 绑定在创建时确定；名称、备注在 Console 实例基础信息编辑。
 
-## 运行时数据库连接
+## 直连 SQLite：运行时数据库连接
 
 SDK、参数化 SQL 和结果解析按 [JavaScript 数据库连接](../../tiana-sqlite/references/js-sdk.md)处理。应用必须使用支持 `auth` 的 SDK 和 `window.tiana.auth` provider；`window.tiana.connection()` 用于获取连接元信息。共享 provider 和 adapter，不读取 Token 快照，不保留旧 SDK、旧 Bootstrap 或实例 Token 回退路径。
 
@@ -48,7 +100,7 @@ CLI 本地预览优先复用已保存的 CLI 登录，通过一次性本地启
 
 输出浏览器可直接执行的 ES 模块、CSS 和资源，引用使用相对路径。Vite 库模式在顶层配置 `define: { 'process.env.NODE_ENV': JSON.stringify('production') }`，并验证产物无残留引用。入口与资源路径以实际工程的构建配置为准；入口模块自行加载 CSS。不要生成或读取 tiana.app.json，不提交 style、rendering、routing 参数。
 
-Site 参数来自 MGR 的 web_project：name、description、固定 entry、可选 database_instance_id、git_instance_id、source_commit。实例只保存通用 Serverless 属性。首次创建可传 `--entry assets/app.js --database-instance-id DATABASE_ID --git-instance-id GIT_ID`；Git commit 可以稍后用 `web update ID --expected-revision REV --source-commit FULL_COMMIT` 录入，完整小写 40/64 位 commit 要求已有 Git 绑定。MGR 验证关联实例属于当前租户、产品正确且可用。源码构建和远端引用核验见[源码发布](../../tiana-git/references/source-releases.md)，参数更新与归档发布是分开的操作，不假称两者跨服务原子提交。
+Site 参数来自 MGR 的 web_project：name、description、固定 entry、可选 database_instance_id 和 git_instance_id。首次创建可传 `--entry assets/app.js --database-instance-id DATABASE_ID --git-instance-id GIT_ID`，后端模式省略数据库绑定。已有项目沿用创建时的固定关联，名称、备注在 Console 实例基础信息编辑；后端绑定使用 `web functions get/set`。源码提交记录与远程引用核验见[源码发布](../../tiana-git/references/source-releases.md)，从确定提交构建并保存对应发布回执。
 
 CLI 将目录打包为 ZIP Store/Deflate 的一个 `.tweb`，根目录是零字节 web.yaml 与 data/。web.yaml 预留 Web server 配置，与 Site 参数无关，目前为空。data/ 前缀不对外暴露，底层只提供 GET/HEAD 精确文件访问，没有目录索引、默认 index.html 或 SPA fallback；底层可托管 HTML，带 entry 的 Site 使用固定 CSR/hash Bootstrap。
 

package/skills/tiana-web/references/files.md

@@ -2,6 +2,10 @@
 
 CLI 文件操作要求 1.0.4 或更新正式版，使用 `tiana file --help` 核验命令入口。WebApp 文件能力还需目标环境提供配套的 MGR、Web 与 serverless-js Bootstrap；使用前核对目标环境能力。
 
+存储分工及静态小图片的 16 KiB 上限见[数据与素材存储](storage-and-assets.md)。
+外置预置素材按[模板素材文件](template-files.md)使用 `template-assets/` 相对路径，
+业务记录和文件关联信息使用数据库，文件二进制不放入 SQL 或 Web 包。
+
 ## 归属和创建顺序
 
 文件归当前租户，租户成员共享，用量与数据库共用存储配额。Console 和 CLI 展示整个租户文件目录；WebApp 使用其中的 `<WebApp ID>/` 子目录。应用只传相对路径，服务端确定 tenant 和 WebApp 根，不能从 JavaScript 修改授权范围。

package/skills/tiana-web/references/function-templates.md

@@ -0,0 +1,74 @@
+# 带后端服务的 Web 模板
+
+配套 Function CLI 与模板安装扩展部署后使用。先确认 `tiana function --help`、`tiana web functions --help` 可用；未部署环境不能当作已支持。
+
+## 确认资源关系
+
+从目标 Web 的 `web functions get WEB_ID --json` 取得后端服务 ID，逐个 `function show` 读取源码 Git。每个 Git 固定一个 main commit；共享同一 Git 的前端和多个后端服务只取这一份快照。后端服务源码位置从元信息的 source_dir 取得。
+
+后端数据库依据后端服务参数和实际源码确认。读取参数名与 Endpoint，再用已知 SQLite ID 的元信息核对 Endpoint；不要因为 Web 未直接绑定数据库就认为没有数据库，也不要默认复制当前租户的任意数据库。源码动态选择数据库或依赖多个数据库、无法确认对应实例时，先向用户明确该依赖，本格式目前声明一个安装 SQLite。报告只包含实例 ID、参数名和用途，不打印 Token。
+
+沿用[分享模板](share-template.md)对结构、seed 和公开内容的筛选。后端服务参数只导出明确可公开的业务初值；数据库 Endpoint/Token 在安装时生成。源码、JSON、SQL、前端 bundle、source map 和展示材料均检查凭据和私有数据。
+
+第三方 API Key 等不能作为公开参数初值分发；在模板说明中列出参数名与用途，由安装者按 [Tiana Function 参数配置](../../tiana-function/references/commands.md#参数配置与生效)填写自己的值并验证。数据库参数映射不代替第三方密钥配置；尚未配置的功能明确标为待配置。
+
+## 组织 metadata.json
+
+将各仓库快照放在一个公开工作副本的 `repositories/<key>/` 下，根部放 metadata.json、showcase 和数据库初始化 SQL。同仓前后端保持原有目录布局。例如：
+
+```json
+{
+  "name": "orders",
+  "display_name": "订单管理",
+  "description": "由后端服务处理业务并访问私有 SQLite",
+  "database_required": true,
+  "private_database": true,
+  "schema": "db/schema.sql",
+  "web_repository": "app",
+  "repositories": [{
+    "key": "app",
+    "path": "repositories/app",
+    "variables": [{
+      "name": "FUNCTION_ID:api",
+      "placeholder": "__TIANA_FUNCTION_API_91ad47ef__",
+      "description": "本次安装的订单后端服务 ID",
+      "files": ["src/app.js"]
+    }]
+  }],
+  "functions": [{
+    "key": "api",
+    "name": "订单接口",
+    "repository": "app",
+    "source_dir": "/services/orders",
+    "parameters": {"MESSAGE": "欢迎使用订单服务"},
+    "database": {"endpoint_parameter": "SQLITE_ENDPOINT", "token_parameter": "SQLITE_TOKEN"}
+  }],
+  "site_variables": [{
+    "name": "FUNCTION_ID:api",
+    "placeholder": "__TIANA_FUNCTION_API_91ad47ef__",
+    "description": "本次安装的订单后端服务 ID",
+    "files": ["app.js"]
+  }]
+}
+```
+
+- `private_database: true` 创建并初始化 SQLite，但不把它绑定到 Web 的浏览器连接。后端服务通过参数访问数据库。
+- `repositories` 的 key 标识逻辑仓库，path 选择 source.zip 内的快照子树。每个后端服务引用一个 repository；Web 引用 web_repository。共享关系在安装后保持。
+`source_dir` 填写服务元信息中保存的仓库内目录，支持 `/` 根目录；入口目录包含 package main 的 Go 文件，所属 go.mod 可位于入口目录或仓库内上级目录；多个入口可共享同一模块。安装保留仓库目录结构，为新服务 ID 关联同一个 source_dir，不改名源码目录。同仓同目录允许多个服务引用。源码 variables 的文件路径相对于原仓库，资源 ID 引用仍按声明替换；数据库 Token 只写入运行参数。
+- `parameters` 只放公开业务初值，`database` 指定接收新数据库 Endpoint/Token 的参数名。可选 `cors` 使用后端服务 CORS 配置对象。
+- 仓库 variables 的 files 相对于该仓库，保持原路径；site_variables 的 files 相对于前端 dist。必须检查构建后的真实文件名及占位符仍然存在，不能照抄 `app.js`。
+- `FUNCTION_ID:<key>`、`GIT_INSTANCE_ID:<key>` 引用新资源，WEB_ID、SQLITE_INSTANCE_ID 沿用本次安装值。目录结构与相对模块引用保留，Token 不作为替换变量。
+
+前端直接调用 `context.functions.fetch('__TIANA_FUNCTION_API_91ad47ef__', '/orders', {...})`。占位符是普通字符串，干净构建后应保留在声明的 site_variables 文件中。数据库凭据只在后端服务运行参数中，不能进入这些文件。
+
+## 打包与安装验证
+
+从固定提交导出整个公开工作副本为 source.zip；在其中 `web_repository` 选择的目录安装依赖、干净构建，再给 [pack-template.py](../scripts/pack-template.py) 传入该 dist。脚本把这些字段写入 install.json。后端服务模板必须包含源码供安装时编译，不使用 `--without-source`。用户安装时可以不额外保留纯前端仓库；后端服务使用的 Git 始终创建，同仓 Web 保留该 Git 关联。
+
+安装会先创建 SQLite、各 Git 和后端服务，取得所有新 ID 后关联原 source_dir、替换声明值，再保存 Git。设置新数据库参数，逐个编译后端服务并绑定 Web 后发布前端。同仓后端服务顺序构建，后一个读取前一个依赖整理后的 commit。安装失败时保留资源和回执，通过安装任务的重试继续，不能重新执行一组无关联的创建命令。
+
+发布分享前用另一个租户实际安装：核对一个共享 Git、两个新后端服务的原 source_dir、实际发布版本和 Web 绑定；通过另一账号的 Site Cookie 打开分享应用，执行读写，确认访问的是新 SQLite、原数据库未变且浏览器不能取得 SQLite 连接或 Token。单纯编译通过不代表分享与隔离验收通过。
+
+## 下载源码后继续开发
+
+`web init-template` / `init-share-template` 只解压，不代替资源安装。读到 repositories/functions 后按逻辑 key 创建或按用户指定复用资源：每个 Git 一份、后端服务关联对应 Git；创建时传入原 source_dir，保留目录结构并替换声明的变量。初始化目标数据库，把新凭据放入后端服务参数；从 web_repository 构建前端。用 `web functions set` 保存后端服务列表后预览与发布。保留真实资源回执，重试时复用；不得将原作者后端服务或数据库 ID 留作默认值。

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

@@ -2,11 +2,20 @@
 
 分享的是可独立安装的材料。发布流程在工作副本中准备材料，最后更新源 Web 的稳定分享链接。
 
+带后端服务时先读[后端服务模板](function-templates.md)，核对 Web → Function → SQLite 和共享 Git 关系，再按以下公开材料流程准备。
+
 ## 1. 核实应用与交付范围
 
 读取 `tiana web publish-share-template --help` 和 `tiana web status-share-template --help`，确认当前 CLI 支持这组命令。读取目标 Web 详情，记录当前租户、真实 Web ID、固定入口、SQLite/Git 绑定和可构建源码位置。取得对应源码，在技能目录之外建立独立工作副本，保留用户原工程和数据。
 
-默认分享源码；根据工程情况可让用户选择「包含源码，允许安装和做同款」或「仅安装，不分享源码」。仅安装仍需准备同份经过公开检查的构建、安装说明、预览和封面。明确 `database_required`：运行需要 SQLite 就填 `true`，纯前端且没有 SQLite 调用就填 `false`；是否有 schema.sql 不能代替这个判断。
+默认分享源码；先按[数据与素材存储](storage-and-assets.md)检查持久化和预置素材。
+含后端服务的模板必须包含经过公开检查的后端源码，供安装时编译；安装始终创建所需后端 Git，前端源码库按安装选择处理。
+没有后端服务且没有外置素材时，可根据用户选择制作「仅安装，不分享源码」的旧格式包。含素材的
+格式 2 包需要保留 source.zip 供服务端核对；没有后端服务的模板仍可直接安装，不创建源码库。
+发布者要求不提供源码时说明此边界，不默默公开源码或删除必要素材。
+两类包都准备经过公开检查的构建、安装说明、预览和封面。需要持久保存业务记录时
+接入 SQLite 并将 `database_required` 填为 `true`；只有确实不需要数据库持久化时才填
+`false`，不能根据旧 localStorage 实现或缺少 schema 就推断无数据库需求。
 
 完成条件：应用身份、源码选择、SQLite 依赖、真实入口和构建方法都有依据。
 
@@ -21,7 +30,7 @@
 | 系统初值和用户自定义内容混合 | 只有可靠区分条件时才导出通用初值 |
 | 用途、归属或可公开性不明确 | 提问后再生成 seed |
 
-有疑问时说明表和字段的用途，给出「留空」「合成示例」「仅保留列出的通用初值」供用户选择。问题与报告使用字段名和统计数量，不回显隐私值。分享应用不等于授权分享个人数据；不要直接把整库 dump 当作模板。用户文件默认不带，明确可公开且应用必需的静态素材才能进入材料。
+有疑问时说明表和字段的用途，给出「留空」「合成示例」「仅保留列出的通用初值」供用户选择。问题与报告使用字段名和统计数量，不回显隐私值。分享应用不等于授权分享个人数据；不要直接把整库 dump 当作模板。用户文件默认不带。必需且可公开的预置素材按[模板素材文件](template-files.md)进入 `template-files/` 和独立安装材料，源码和 SQL 只引用应用相对路径；不复制作者链接，不把外置文件塞入 Web 包或 SQL BLOB。小图片与平台图标按存储规则处理。
 
 在临时空 SQLite 中依次执行 schema、seed；遇到第一个错误就停止修正。核对行数、主外键、约束及应用首次启动。完成条件：每张 seed 表都有明确的数据来源说明，初始化可在空库成功完成。
 
@@ -61,15 +70,19 @@
    python3 /技能实际路径/scripts/pack-template.py --source /绝对路径/source.zip --dist /干净构建目录/dist --entry assets/app.js --output /绝对路径/install.zip
    ```
 
-   用户选择仅安装时增加 `--without-source`。脚本封装 install.json、site.tweb、预览、封面、实际提供的 SQL 和可选源码；它不代替数据和公开内容检查。
-3. 复查脚本输出的大小、SHA-256、源码选择及数据库依赖。安装包上限 32 MiB，单材料 16 MiB，所有解析层累计展开 128 MiB、5,000 个条目；site.tweb 同时遵守 16 MiB 和 4,097 条目的 Web 归档限制。超限时先移除无用依赖、压缩资源或精简材料。
+   没有外置素材且发布者选择不分享源码时增加 `--without-source`。声明素材时保留
+   source.zip，并生成与其逐字节相同的独立 `files/`、固定格式/能力及文件清单。
+   复核目标环境已支持并启用该能力。脚本不替代数据、公开内容或应用行为检查。
+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。上传响应未知或等待被中断时先查询该状态；发布失败时检查错误和清理进度，再准备新的发布。发布完成后后台立即清理中转 ZIP，确认删除后释放其占用额度；再次上传时重新申请授权。
+5. 用 `tiana web status-share-template WEB_ID --json` 核对当前 `share.package_id`、Web ID、模板名称和 URL。支持配套字段的 CLI 还会保留 share.version、material_version 和 manifest.files；材料版本应等于本次完整安装包摘要。上传响应未知或等待被中断时先查询原状态，不把新上传当作恢复。发布失败时核对错误和中转清理。完整历史能力上线后旧版发布材料继续保留和计费，中转 ZIP 确认删除后才释放其占用额度。
 
 完成条件：服务端当前分享指向本次发布的 package_id，才能报告发布成功。交付稳定安装链接、材料摘要、源码选择、数据库结构和 seed 处理说明。链接在应用详情的“分享模板”页可复制，并显示成功安装次数。更新模板沿用该链接；同租户再次安装会复用已安装的应用。
 
 ## 撤回和做同款
 
-用户要求撤回时执行 `tiana web withdraw-share-template WEB_ID --json`，再查询状态说明当前分享和清理进度。撤回影响后续安装，已安装应用继续独立使用；重新发布保留链接和累计安装次数。
+用户要求撤回时执行 `tiana web withdraw-share-template WEB_ID --json`，再查询原状态。
+完整历史能力上线后，撤回停止新安装，保留历史材料和已受理任务的原版恢复资格；
+已有应用继续独立使用。不能把 cleanup_job_id 为 0 当作历史材料已经删除或存储已释放。
 
 用户拿分享链接要求做同款时，执行 `tiana web init-share-template LINK --dir PROJECT_DIR --json`。读取回执中的 prompt 和工程 metadata.json，再按[模板初始化](template-init.md)及普通 Web 开发流程创建自己的新应用。没有源码的分享只支持落地页安装。做同款从新工程开始，原模板的安装来源与统计不跟踪这次开发。

package/skills/tiana-web/references/storage-and-assets.md

@@ -0,0 +1,49 @@
+# 数据与素材存储
+
+制作或修改应用、制作可安装模板时，先检查当前代码、绑定与构建产物，再决定数据库
+和素材初始化。旧 metadata、来源应用的 localStorage 实现或已有截图不足以证明存储正确。
+
+| 内容 | 正式应用的存放方式 |
+| --- | --- |
+| JavaScript、CSS、运行必需的代码依赖 | 随 Web 构建打包；CSS 可独立随包或内嵌 JS |
+| 需要持久保存的记录、成绩、设置、文件业务关联 | Tiana 数据库；文件关联保存相对路径、名称及关联字段 |
+| 随应用分发且单张不超过 16 KiB 的静态小图片 | 构建时内嵌 JS，复用同一份 data URL 或 SVG 字符串 |
+| 其他需外置的图片、附件、音视频、字体、模型 | Tiana 文件存储，通过文件 API 访问 |
+| 用户上传文件、需要长期保存的生成文件 | 不论大小，使用文件存储 |
+| 尚未保存的输入、本局计算、短期缓存 | 可留在页面；缓存不能替代云端持久化 |
+
+应用需要持久业务记录时接入 SQLite，不能把 localStorage、IndexedDB 或文件 BLOB
+当作数据库，再据此声明 `database_required: false`。确实没有数据库持久化需求时
+可无库，不为临时计算增加业务数据。数据库连接遵循当前 SQLite 技能的动态账号鉴权。
+
+文件使用平台 `context.files`，详细调用见[文件存储](files.md)。数据库保存可重新解析
+的应用相对路径，不保存二进制/base64 正文、作者 URL 或临时授权 URL。文件访问保留
+当前租户与应用的授权范围，不能把文件存储当作跨租户匿名 CDN。
+
+## 静态小图片的大小
+
+- 单张上限为 16,384 字节，等于上限仍可内嵌，16,385 字节及以上使用文件存储。
+- 测量缩放、压缩、格式优化后的实际文件，位于 base64/data URL 编码之前。
+  SVG 测量优化后的完整 UTF-8 字节，不用像素数、原图或 HTTP 压缩后大小代替。
+- 只适用于随应用分发的静态图片。用户上传图片和需长期保存的生成图片仍用文件存储。
+- 检查干净构建中实际已进入 JS，不能只看 import，或把一张大图切碎来规避上限。
+
+## 随包例外与预览
+
+平台要求的根部 `icon.png` 按规范随包提供；不能据此把其他外置图片复制进 Web 包。
+`showcase/preview.html` 保持自包含，使用合成示例和页面内状态，不访问作者或安装后
+应用的正式数据库、文件。保留“示例体验／恢复示例”工具条，恢复仅重置本页示例。
+
+临时绘制的 Canvas、图表或导出文件可以先在内存生成；用户需要长期保存时再写入
+文件存储，不因此扩大应用功能。按实际接入描述数据库与文件的保存位置，尚未验证
+的云端持久化不得写成已完成。
+
+## 预置素材和验收
+
+需外置的预置素材按[模板素材文件](template-files.md)进入当前安装的独立目录。
+程序用 `template-assets/<相对路径>` 访问，数据库保留同一路径。仅作者应用能访问，
+或仅源码中存在文件，都不足以证明新安装可用。
+
+检查源码和构建、平台图标及自包含预览的例外；实际写入业务记录，刷新并在另一
+授权会话读回。需要预置素材时核对新安装文件；有用户上传功能时另验证上传和原有
+预览/下载操作。按实际功能验收，不为测试添加规格外的文件管理界面。

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

@@ -0,0 +1,95 @@
+# 模板素材文件
+
+本参考描述配套格式 2 的源码候选行为。实际使用前核对目标服务端已经部署并启用
+`template_files_v1`；兼容版 C 会拒绝新格式。本地脚本存在或打包成功不代表已上线。
+程序、数据库、小图片与预览的分工见[数据与素材存储](storage-and-assets.md)。
+
+## 声明与路径
+
+有安装必需且可公开的外置素材时，在原有 `metadata.json` 增加
+`"file_seeds": "template-files"`，将其实际字节放在工程根部 `template-files/`。
+保留原来的名称、说明、数据库需求与变量。目录内全部文件参与安装；不得混入用户
+附件、凭据、作者环境文件或私人记录。
+
+| 位置 | 同一文件的路径 |
+| --- | --- |
+| 源码 | `template-files/images/cover.webp` |
+| 安装包独立材料 | `files/images/cover.webp` |
+| 应用和初始 SQL | `template-assets/images/cover.webp` |
+| Console / CLI 租户目录 | `WEB_ID/template-assets/images/cover.webp` |
+
+素材为 1..256 个普通文件，单个和合计均不超过 16 MiB。路径为 UTF-8，相对路径
+最长 1,024 字节；拒绝重复、文件/目录冲突、软链接、特殊文件、绝对路径、`.`/`..`、
+反斜线、控制字符和百分号编码。未声明素材时省略字段与目录，不造空素材流程。
+
+程序按[文件 API](files.md)使用 `context.files`：
+
+```js
+export async function mount(root, { files }) {
+  const image = document.createElement('img');
+  image.alt = '封面';
+  root.append(image);
+  const unbind = await files.bindImage(image, 'template-assets/images/cover.webp');
+  return () => unbind();
+}
+```
+
+数据库保存这条应用相对路径。实际 Web ID 由当前应用上下文提供，不将作者 URL、
+临时授权 URL、租户前缀或 OSS key 固化到源码/SQL，也不替换二进制素材中的变量。
+
+## CLI 初始化后的普通开发
+
+`web init-template` / `init-share-template` 校验并原样解压源码，其中的 `template-files/`
+仍在本地。它们不创建应用，也不上传素材。读取声明、确认每份素材和来源后，保存
+本次新建应用的真实 `data.id`，为这个尚未初始化的新目录逐项准备文件：
+
+```sh
+tiana file put ./template-files/images/cover.webp WEB_ID/template-assets/images/cover.webp --json
+tiana file put ./template-files/documents/guide.pdf WEB_ID/template-assets/documents/guide.pdf --json
+tiana file list WEB_ID/template-assets/ --json
+tiana file get WEB_ID/template-assets/images/cover.webp ./verified-cover.webp --json
+```
+
+把 `WEB_ID` 替换为创建回执中的真实 ID。下载目标必须不存在。核对字节数和 SHA-256，
+在 `web serve WEB_ID` 中实际读取，再普通发布。`web publish` 只更新程序包，不自动
+复制 `template-files/`。同名默认拒绝；未知上传先检查原上传标识，不能用 overwrite
+重试未知写入。已存在应用沿用其实际文件，不能因改名、更新程序或用户删除素材而
+重新灌入。用户明确要求修改的文件按普通文件操作单独处理。
+
+## 制作格式 2 安装包
+
+从同一个确定 Git 提交导出源码，在该提交的干净目录安装依赖、构建。
+使用[分享流程](share-template.md#4-打包和发布)中的打包脚本；素材从传入的固定
+`source.zip` 读取，不能只存在于作者工作目录。声明素材时，脚本生成：
+
+- `source.zip` 中的 `template-files/`，用于服务端逐字节核对。
+- `files/` 中的独立素材，包含相同字节，供两种安装模式直接复制。
+- `install.json` 的 `format_version: 2`、`requires: ["template_files_v1"]` 及 `files`。
+  文件清单 version 为 1，root 固定 `template-assets/`，按路径的 UTF-8 字节顺序排列。
+  每项包含路径、大小、SHA-256 和合法 Content-Type。
+
+清单摘要取 `files` 对象在安装清单中的原始 UTF-8 字节；整包摘要取最终完整
+`install.zip`。不能把源码包摘要代替整包摘要，或重排 JSON 后重算清单摘要。
+支持两种安装模式的是这份完整包：安装者直接安装时不创建源码库，素材仍取自
+独立材料。发布者的 `--without-source` 则只支持无素材旧格式包，不能省略新格式
+用于核对的源码，也不能未经授权默默改为提供源码。
+
+检查干净 `dist` 和 `site.tweb`，排除外置素材目录、改名副本、原始字节和 base64
+内嵌；脚本能检查常见复制/内嵌，不能证明所有自定义编码或转换后的资源都已排除。
+平台根图标仍按例外保留，小图片按 16 KiB 规则确实进入 JS。由 Agent 复核源码、
+构建过程及实际文件访问。无素材包继续省略格式、必需能力与文件清单字段。
+
+## 实际验收与恢复
+
+至少覆盖“保留源码/直接安装 × 桌面/手机”四种组合。使用独立测试模板，包含
+超过 16 KiB 的图片、附件、内嵌小图片和引用相对路径的合成 SQL 记录。另验证
+无素材包跳过文件步骤且不占素材预留，不能用无素材样例替代素材验收。
+
+核对原任务/安装回执、文件数量与字节、CLI 路径、数据库和实际应用读回。
+首次打开、刷新、重开和另一授权会话均能访问；修改一份安装不影响其他安装，
+未授权租户无法读取，预览的恢复示例不修改真实应用。存在上传功能时另验证上传。
+
+安装失败或响应未知时刷新原安装记录，沿原根任务恢复，不新建安装替代未知结果。
+模板 V1 中断后发布 V2，恢复仍固定 V1 材料；重试不重复复制或入账。用户改动、
+删除已安装文件后，不自动补齐或覆盖。保存各组合的真实回执、哈希及读取证据，
+未验证步骤保留未完成状态，不将本地打包或脚本测试当作云端安装通过。