@tianacloud/agent-skills 1.0.1 → 1.0.3

package/README.md

@@ -37,7 +37,7 @@ WorkBuddy、豆包按所用版本的目录／ZIP 导入方式加载这四个目
 
 Web 技能每次任务都实际执行 `tiana web list-template --json`，使用当前 name/description 判断需求。模板 ZIP 原样下载解压到独立项目目录；Agent 按根部 metadata.json 替换变量、先 schema 后 seeds。模板源码和制作规范见 [template-apps](https://github.com/tianacloud/template-apps)，客户安装模板由 CLI 和 MGR 目录完成。
 
-技能安装器只安装技能。Agent 首次执行 Tiana 任务时检查 CLI，缺少时自动执行下面的安装并继续原任务；CLI 要求 1.0.0 或更新正式版，需要 Node.js 20+。
+技能安装器只安装技能。Agent 首次执行 Tiana 任务时检查 CLI，缺少时自动执行下面的安装并继续原任务；CLI 要求 1.0.1 或更新正式版，需要 Node.js 20+。
 
 ```sh
 npm install -g @tianacloud/cli@latest --registry=https://registry.npmjs.org/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianacloud/agent-skills",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Tiana Cloud Skills for accounts, SQLite, Git and Web applications",
   "license": "MIT",
   "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.1",
+  "version": "1.0.3",
   "description": "Tiana Cloud account, SQLite, Git and Web application workflows",
   "author": {
     "name": "Tiana Cloud",

package/skills/tiana/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana Cloud 管理实例、安装 CLI、登录和恢复账
 license: MIT
 metadata:
   author: Tiana Cloud
-  version: "1.0.1"
+  version: "1.0.3"
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana
 ---
 
@@ -14,7 +14,7 @@ metadata:
 
 ## 每个会话一次的更新检查
 
-四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.1 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
+四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.3 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
 
 仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](references/getting-started.md#更新)。
 

package/skills/tiana/references/cloud-cli.md

@@ -1,25 +1,27 @@
 # CLI 命令与恢复
 
-本分支使用以下命令。执行前查看对应 `--help`，管理命令不统一输出 JSON。
+以下 JSON 管理输出需使用配套修复后的 CLI 发行版，执行前查看对应 `--help` 确认 `--json`。当前版本缺少参数时报告需要升级，不把表格解析伪装成稳定 JSON。
 
 ```sh
-tiana status
-tiana sqlite list
-tiana sqlite show INSTANCE
+tiana status --json
+tiana sqlite list --json
+tiana sqlite show INSTANCE --json
 tiana sqlite create NAME --wait
-tiana git list
-tiana git show INSTANCE
+tiana git list --json
+tiana git show INSTANCE --json
 tiana git create NAME --wait
 tiana sqlite shell INSTANCE -f schema.sql --format json
 ```
 
-创建默认只返回异步受理回执；`--wait` 等待已绑定的原始任务和实例状态。记录完整实例 ID、Job ID、Operation ID。不要从实例名称推断另一条创建请求的身份。
+`sqlite/git list --json` 自动取完全部匹配页，返回完整的 `data.items`；空集合为数组，分页失败不报告部分列表成功。
+
+创建默认只返回异步受理回执；`--wait` 等待已绑定的原始任务和实例状态。记录完整实例 ID、Job ID、Operation ID。管理 JSON 使用 `status/data/error` 信封，默认变更返回 `accepted`，等待已确认完成返回 `succeeded`；`unknown` 不等于失败，保留目标和操作身份，只查询而不盲目重发。新列表/详情的任务 ID、配额和时间值保留十进制字符串精度。不要从实例名称推断另一条创建请求的身份。
 
 如果创建请求中断且仍有待完成记录，保持产品、名称和原始参数重试，CLI 复用请求 ID。若之前已成功返回，再次执行 create 是新请求。遇到未解决的其他待完成操作，应先调查原操作，不删除本地记录来强行创建。
 
 删除使用 `sqlite/git delete INSTANCE`；默认需要终端确认。仅在用户已授权相应删除时使用 `--force`。`--wait` 等待删除操作成功，不等于物理存储已经回收完毕。
 
-SQLite 分支操作使用 [SQLite 分支](../../tiana-sqlite/references/branches-cli.md)。`branch list` 每次只返回一页；创建和删除默认只报告受理。分支创建没有本地待完成请求恢复机制，不能套用上面的实例创建重试规则；结果未知时先核实，保留原 Operation ID。分支查询和连接用 `sqlite show/shell INSTANCE --branch NAME`，省略时选择默认分支（固定 ID `main`）。
+SQLite 分支操作使用 [SQLite 分支](../../tiana-sqlite/references/branches-cli.md)。`branch list --json` 自动取完所有匹配页，返回 `data.items`；`--after` 仅指定起始游标，`--search` 在所有页保持一致。创建和删除默认只报告受理。分支创建没有本地待完成请求恢复机制，不能套用上面的实例创建重试规则；结果未知时先核实，保留原 Operation ID。分支查询和连接用 `sqlite show/shell INSTANCE --branch NAME`，省略时选择默认分支（固定 ID `main`）。
 
 应用列表使用 `tiana web list`；脚本可用 `tiana web list --json` 取得全部分页的 `data.items`，保存真实 `id`。列表只包含当前账号拥有的应用；名称可以重复，不能仅凭同名断定是原应用。
 
@@ -27,6 +29,10 @@ Serverless Web 候选命令为 `web create NAME [-m DESCRIPTION] [--entry ENTRY]
 
 发布经 Gateway 业务管控 channel，接受有效且作用域覆盖目标的 Endpoint、Instance、Group、Tenant Token。CLI 优先使用互斥的 TIANA_TOKEN / TIANA_TOKEN_FILE，否则使用已登录账号 access token；不读取实例 Token 缓存，显式凭据拒绝时不回退。MGR 项目元数据仍通过登录账号读取。CLI 内部将目录打包为含空 `web.yaml` 和 `data/` 的单个 `.tweb`；普通文件可以发布，Site 包装使用 MGR 项目参数；不生成或读取旧清单。发布回执确认 S3 上传，不等待激活；记录 publish_id 和 SHA256，随后查询激活状态。结果未知时只查询、不自动重放 PUT；404 回执消失表示未知，检查 current 内容。没有 --version、upload 或 reload 命令，详细边界见[应用要求](../../tiana-web/references/csr-apps.md)。
 
+登录 JSON 的 `pending_auth:true` 表示待批准；`NO_PENDING_AUTH` / `pending_auth:false` 仅表示无待恢复授权。缺少 `logged_in` 或 `pending_auth` 时该状态未核实，不能推断已退出或丢失授权。用 `status --json` 核实当前账号；配额不可用时仍可能返回已核实的 `logged_in:true`。目录失败按 `LOCAL_STATE_UNAVAILABLE` 修复 XDG 路径/权限，锁占用先等待，过期才重新 start，拒绝不自动再次授权。
+
+本地配置根目录为 `$XDG_CONFIG_HOME/tiana`，未设置时为 `~/.config/tiana`；凭据、登录 pending、命令 pending、发布回执及更新检查状态共用该根目录。`LEGACY_PENDING_COMMAND` 表示旧平台目录仍有未完成命令：停止旧 CLI 进程，保留原参数、账号和请求身份，将错误中的旧路径设置为 `TIANA_PENDING_COMMAND_FILE`，在每个恢复调用中传递并执行原命令。不要另发创建或删除本地记录；恢复完成后取消该覆盖，使用新默认目录。旧发布回执保留在原目录，不自动迁移或删除。
+
 登录使用 `login --start --no-open --json` 和 `login --resume --json`，详见[开始使用](getting-started.md)。退出登录使用 `tiana logout`，会清理当前 origin 的账号凭据和未完成登录，不删除旧实例凭据文件。
 
 SQL 写入中断、输出丢失或响应未知时，先用只读查询确认，不自动重放。账号、配额、网络、证书或资源状态错误均不通过创建新数据库解决。

package/skills/tiana/references/getting-started.md

@@ -1,10 +1,10 @@
 # 开始使用
 
-在 Agent 实际执行命令的环境检查 `tiana version`。本技能要求 CLI 1.0.0 或更新正式版，具备分步登录、sqlite、git、web、list-template/init-template 和 version check。CLI 不存在时执行下面的 npm 安装并重新核验；已有版本过低时按更新流程取得用户确认后升级，再执行资源操作。不要仅凭同名命令存在跳过版本核验。
+在 Agent 实际执行命令的环境检查 `tiana version`。本技能要求 CLI 1.0.3 或更新正式版，具备分步登录、sqlite、git、web、files、list-template/init-template 和 version check。CLI 不存在时执行下面的 npm 安装并重新核验；已有版本过低时按更新流程取得用户确认后升级，再执行资源操作。不要仅凭同名命令存在跳过版本核验。
 
 最低版本核验独立于更新提醒：0.x、预发行版、dev 或无法核实的版本不满足本技能基线。即使 `should_notify=false` 或更新检查不可用，也不能据此跳过最低版本要求；先完成已获授权的升级，尚未获授权时说明需要升级，暂缓依赖新版 CLI 的资源操作。CLI 与 Skills 独立编号，`--skills-version` 仍传实际加载的 Skills 版本。
 
-最低版本升级已获授权但更新检查不可用时，可安装已发布基线 `npm install -g @tianacloud/cli@1.0.0 --registry=https://registry.npmjs.org/`，随后核验 `tiana version`；下载失败则报告实际错误，不继续资源操作。
+最低版本升级已获授权但更新检查不可用时，可安装已发布基线 `npm install -g @tianacloud/cli@1.0.3 --registry=https://registry.npmjs.org/`，随后核验 `tiana version`；下载失败则报告实际错误，不继续资源操作。
 
 ## 安装
 
@@ -65,3 +65,6 @@ Console/管理 API、用户 Web 地址、数据库 Endpoint 各有用途：全
 4. 链接失效后再 start。CLI 保存账号会话，不需要读取凭据文件。
 
 普通终端也可执行 `tiana login`。用量接口失败不代表退出登录；命令与恢复见 [CLI 指引](cloud-cli.md)。
+
+
+配套修复后的 CLI 在缺少 pending 时返回 `NO_PENDING_AUTH`、`pending_auth:false`，不据此否定当前登录；用 `tiana status --json` 单独核实。`logged_in` 仅在本次已确认登录成功时为 true，其他登录结果可能省略；省略 `pending_auth` 表示无法确认 pending 是否仍在，保存/网络失败后不能假定授权已丢失。按错误 code/message/next_action 处理目录、锁、过期或拒绝，不机械重复 start。先通过 `--help` 核实当前安装版本的新 JSON 能力。

package/skills/tiana-git/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana Git 管理 Git 实例和原生仓库，关联项目远
 license: MIT
 metadata:
   author: Tiana Cloud
-  version: "1.0.1"
+  version: "1.0.3"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-git
 ---
@@ -15,7 +15,7 @@ metadata:
 
 ## 每个会话一次的更新检查
 
-四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.1 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
+四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.3 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
 
 仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](../tiana/references/getting-started.md#更新)。
 

package/skills/tiana-sqlite/SKILL.md

@@ -4,7 +4,7 @@ description: 查询 Tiana SQLite 表结构、执行 SQL、选择数据库分支
 license: MIT
 metadata:
   author: Tiana Cloud
-  version: "1.0.1"
+  version: "1.0.3"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-sqlite
 ---
@@ -15,7 +15,7 @@ metadata:
 
 ## 每个会话一次的更新检查
 
-四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.1 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
+四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.3 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
 
 仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](../tiana/references/getting-started.md#更新)。
 

package/skills/tiana-sqlite/references/branches-cli.md

@@ -5,7 +5,7 @@
 ## 查询与连接
 
 ```sh
-tiana sqlite branch list INSTANCE
+tiana sqlite branch list INSTANCE --json
 tiana sqlite branch list INSTANCE --search preview
 tiana sqlite branch list INSTANCE --after BRANCH_CURSOR
 tiana sqlite show INSTANCE --branch preview
@@ -13,9 +13,12 @@ tiana sqlite show INSTANCE --branch preview --url
 tiana sqlite shell INSTANCE --branch preview -e 'SELECT 1' --format json
 ```
 
-`branch list` 每次只返回一页，显示名称、分支 ID、默认标记、生命周期、运行状态和 Endpoint。需要继续查找时将返回的 `Next cursor` 传给 `--after`，保持原实例及筛选条件；一页未找到不能认定分支不存在。`--search` 是名称子串过滤，创建来源、删除目标和连接选择使用精确名称。
+`branch list` 自动取完所有匹配页；`--json` 返回 `data.items`，包含名称、分支 ID、默认标记、生命周期、运行状态和 Endpoint。`--after` 仅指定起始游标，`--search` 是名称子串过滤并在所有页保持一致；创建来源、删除目标和连接选择使用精确名称。
+
+配套修复后的 CLI 为 branch list/create/delete 与 show 提供 `--json`，执行前检查 `--help`，不把尚未发布的源码能力当成当前安装版本支持。`show --json` 返回实例与所选分支信息；`--url` 只输出连接 URL，与 `--json` 互斥。未传 `--branch` 时选择 ID 为 `main` 的默认分支。`--branch` 接受名称，不是分支 ID。SQL 的 `--format json` 与非交互 `--json` 别名描述查询结果，不是管理信封。
+
+管理 JSON 使用 `status/data/error`：不等待为 `accepted`，等待确认成功为 `succeeded`；已知操作失败为 `failed`，回执/完成结果不可确认为 `unknown`。保留原实例、分支与 Operation ID；分支创建没有本地恢复记录，不能盲目重复创建。JSON 删除仍要求已授权该删除并显式传入 `--force`。
 
-`show` 显示所选分支信息；`--url` 只输出连接 URL。未传 `--branch` 时选择 ID 为 `main` 的默认分支。`--branch` 接受名称，不是分支 ID；SQL 与认证规则见 [CLI 连接](cli.md)。这些分支管理命令没有 `--json`，SQL 的 `--format json` 仅用于查询结果。
 
 ## 创建
 

package/skills/tiana-web/SKILL.md

@@ -4,7 +4,7 @@ description: 使用 Tiana 创建、修改、预览和发布 Web 应用。用户
 license: MIT
 metadata:
   author: Tiana Cloud
-  version: "1.0.1"
+  version: "1.0.3"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-web
 ---
@@ -15,7 +15,7 @@ metadata:
 
 ## 每个会话一次的更新检查
 
-四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.1 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
+四个 Tiana 技能共享当前会话的更新检查记录。CLI 已满足最低版本要求且本会话尚未尝试检查时，执行 `tiana version check --skills-version 1.0.3 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
 
 仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](../tiana/references/getting-started.md#更新)。
 
@@ -32,3 +32,7 @@ metadata:
 3. 直接开发时，使用 [固定 index.html](references/index.html)、哈希路由、支持动态账号鉴权的 SDK，按实际数据库结构编写应用及构建清单。
 4. **模板和直接开发都由 Agent 处理数据库初始化。** 模板先执行已配置且存在的 schema，再执行已配置且存在的 seeds；两项独立跳过，SQL 失败先核对结果并停止后续发布。
 5. 按用户需求完成交互和定制，安装依赖并从确定源码提交构建。按 [源码版本流程](../tiana-git/references/source-releases.md)完成源码同步，用 `web publish` 发布当前归档，再用 `web status --publish-id` 核对。除非用户仅要求本地开发，交付实际托管地址、资源 ID 和对应源码提交；未验证的阶段如实说明。
+
+## 文件上传、预览与下载
+
+应用需要文件存储时，阅读[WebApp 文件存储](references/files.md)，核对配套候选环境后使用平台提供的 `context.files`。先创建 WebApp 获得 ID 即可本地预览，无需先发布；文件路径相对于该 WebApp 的目录。

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

@@ -52,7 +52,7 @@ Site 参数来自 MGR 的 web_project：name、description、固定 entry、可
 
 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。
 
-归档和原始资源总量各最多 16 MiB、最多 4096 个资源、单路径最多 1024 个 UTF-8 字节；拒绝符号链接、特殊文件和旧清单。publish 上传前检查实际归档含固定 entry。资源 URL 为 `/web/<id>/assets/<relative_file>`，经过 Web→Gateway→Agent→app_web，不生成 OSS 签名直链。channel=0 透传原生 GET/HEAD，channel=1 提供 publish/status 等 HTTP 管控，协议版本保持不变。
+归档和原始资源总量各最多 16 MiB、最多 4096 个资源、单路径最多 1024 个 UTF-8 字节；拒绝符号链接、特殊文件和旧清单。publish 上传前检查实际归档含固定 entry。资源 URL 为 `/web/<id>/assets/<relative_file>`；例如归档内的 `assets/app.js` 对应 `/web/<id>/assets/assets/app.js`，路由前缀与文件目录各保留一层。经过 Web→Gateway→Agent→app_web，不生成 OSS 签名直链。channel=0 透传原生 GET/HEAD，channel=1 提供 publish/status 等 HTTP 管控，协议版本保持不变。
 
 ## 预览与发布
 
@@ -68,9 +68,11 @@ tiana web status WEB_ID --publish-id PUBLISH_ID --json
 tiana web status WEB_ID --json
 ```
 
-`publish` 经 Gateway 的业务管控 channel 上传单个归档。S3 覆盖固定 key，确认上传后返回，随后异步 reload；`uploaded: true` 不等于已激活。保存 `publish_id`、SHA256、Web/实例 ID，再查询到 `ACTIVATED` 并核对 `serving_sha256` 后报告当前内容已生效。CLI 在发送前保存不含凭据的本地回执。
+`publish` 经 Gateway 的业务管控 channel 上传单个归档。S3 覆盖固定 key，确认上传后返回，随后异步 reload；`uploaded: true` 不等于已激活。保存 `publish_id`、SHA256、Web/实例 ID。按同一 ID 查询的是上传回执，`REMOTE_COMMITTED` / `SUCCEEDED` 与 `uploaded: true` 表示归档上传事实；再执行不带 `--publish-id` 的当前内容查询，确认 `state: running`，且 `remote_sha256`、`serving_sha256` 都等于目标归档 SHA256，才报告目标内容正在提供服务。不要等待 `ACTIVATED`，也不能仅凭回执 `SUCCEEDED` 宣称已生效。CLI 在发送前保存不含凭据的本地回执。
 
-结果未知时只查询，禁止自动重放 PUT。回执仅在 App 内存有界保留，重启/过期后的 `404 PUBLISH_NOT_FOUND` 表示原回执未知；检查 `/current` 的远端与服务中校验和，不能据此宣称失败，也不自动重发。再次明确执行 publish 会生成新 ID 并覆盖当前对象。没有 Web 版本列表、版本 URL、版本恢复、显式 reload 命令。
+结果未知时只查询，禁止自动重放 PUT。回执仅在 App 内存有界保留，重启/过期后的 `404 PUBLISH_NOT_FOUND` 表示原回执未知；检查不带 `--publish-id` 的当前内容与保存的目标 SHA256：若应用为 `running` 且两种校验和均匹配，可报告目标内容正在服务，同时保留原上传回执结果未知；不匹配时不能报告目标内容生效，不能据回执丢失宣称失败，也不自动重发。相同归档可被多次发布，摘要匹配不能识别是哪一次上传触发生效。再次明确执行 publish 会生成新 ID 并覆盖当前对象。没有 Web 版本列表、版本 URL、版本恢复、显式 reload 命令。
+
+当前内容查询的 `state` 是应用运行状态；回执查询的 `state` 是上传操作状态。JSON 外层 `status: succeeded` 只表示这次查询成功。当前查询的 `publish` / `publish_id` 为空是合理的，不从摘要推导发布 ID。配套新版 CLI 的 `query_kind: current / receipt` 可区分两类查询；缺少该附加字段时依据是否传入 `--publish-id` 判断。
 
 4. 托管入口使用所属环境 Site origin 的 `/web/<id>/`，Console 详情为 `/console/web/<id>`。报告 Web/实例 ID、publish_id、归档校验和、上传与激活状态，以及可选数据库/Git 关联。环境不具备候选能力时报告具体阻塞并提供本地开发地址；不自行修改部署。
 
@@ -79,3 +81,7 @@ tiana web status WEB_ID --json
 用 `tiana web list --json` 核对当前账号拥有的 Web 应用，优先使用已保存的真实 ID。用户明确要求删除时，执行 `tiana web delete WEB_ID --force`；需要等待源站清理完成时加 `--wait --json`。不得把失败恢复、重新发布或清理本地构建目录当作删除云端应用的授权。
 
 删除会关闭应用入口并通过 Web 实例生命周期清理当前归档，关联 SQLite、Git 不随之删除。只收到 `state: deleting` 时报告已受理；收到 `state: deleted` 才报告本次源站清理完成。空应用、上传中和已发布的应用均可删除；本地仍有未完成的 CLI 创建操作时，先按原请求恢复该操作。已受理的删除等待 Control 确认实例存储删除完成，MGR 不枚举或删除 S3 对象；公开缓存按缓存策略失效。中断后保留待完成记录，用原 ID 恢复，详情见[CLI 命令](../../tiana/references/cloud-cli.md)。
+
+## 应用文件
+
+配套文件存储环境中，`mount` 的第二个参数提供 `files`。先创建 WebApp 取得 ID，再本地预览；文件范围与是否发布无关。上传、下载、图片续期和 CLI 路径见[WebApp 文件存储](files.md)。

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

@@ -0,0 +1,59 @@
+# WebApp 文件存储（配套候选能力）
+
+本页对应 `feat/file-storage` 的 CLI、MGR、Web 与 serverless-js 候选实现，须使用已验收的配套环境；CLI 1.0.1 和 Skills 1.0.2 的版本号本身不代表已包含这项能力。以实际候选 CLI 的 `tiana files --help`、目标环境与 Bootstrap 能力为准，不虚构 npm 已发布版本。
+
+## 归属和创建顺序
+
+文件归当前租户，租户成员共享，用量与数据库共用存储配额。Console 和 CLI 展示整个租户文件目录；WebApp 使用其中的 `<WebApp ID>/` 子目录。应用只传相对路径，服务端确定 tenant 和 WebApp 根，不能从 JavaScript 修改授权范围。
+
+先执行既有 `tiana web create` 获取 Web ID，再 `tiana web serve WEB_ID`。预览不要求先 publish，因此未发布应用也能访问自己的稳定文件目录。沿用已存在项目的真实 ID，不为一次预览另造 ID，也不把环境域名写死在应用里。
+
+## 挂载 API
+
+平台会在调用 `mount` 前准备文件访问。使用平台提供的 `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, 'images/cover.png');
+  return () => unbind();
+}
+```
+
+- `files.list(path, { cursor })`：一页文件和目录，`items` 加下一页 `cursor`；只按用户所需导航，不为统计遍历全部目录。
+- `files.get(path)`：下载 Response；`files.getUrl(path)`：下载域名 URL，仍需授权。
+- `files.put(path, blob, options)`：直传 OSS，返回上传记录；可用 `onPrepared` 保留 ID、`onProgress` 显示进度。
+- `files.delete(path)`：删除一个文件，UI 必须先确认用户意图。
+- `files.bindImage(image, path)`：准备 URL 并绑定一次授权失败恢复，返回卸载函数。
+
+Site Bootstrap 在导入应用模块前安装 15 分钟的 HttpOnly 文件 Cookie。`<img>` 请求会自动携带有效 Cookie，但原生标签不负责续期；优先用 `bindImage`，或在设置 `src` 前调用 `getUrl`。SDK 对授权失败最多刷新并重试一次，不把文件不存在当成授权过期。
+
+本地预览使用同源 CLI broker，文件授权 Header 保留在 CLI 中；应用仍用同一个 `context.files`。上传数据在两种场景都直接去 OSS，平台接口仅签发和结算。不要自行读取 HttpOnly Cookie、复制数据库 Token 到文件域名，或把凭据拼进 URL。
+
+```js
+let uploadID;
+const upload = await files.put('documents/note.txt', new Blob(['内容'], {
+  type: 'text/plain',
+}), {
+  onPrepared: receipt => { uploadID = receipt.id; },
+});
+const downloadURL = await files.getUrl(upload.path);
+```
+
+同名默认拒绝。用户明确替换时才用 `{ overwrite: true }`，其行为是删除旧文件再上传；新上传失败无法恢复旧文件。签发凭据有效 30 分钟，预留本次完整大小；完成确认或后台到期核验后结算。关闭浏览器不取消后台核验。
+
+上传结果不确定时保留 `uploadID`，调用 `files.uploadStatus(uploadID)`、`files.completeUpload(uploadID)` 检查，不重新执行替换。路径不能包含 `.`、`..`、反斜线和编码穿透片段。
+
+## CLI 操作同一目录
+
+```sh
+tiana files list WEB_ID/images/
+tiana files put ./cover.png WEB_ID/images/cover.png
+tiana files get WEB_ID/images/cover.png ./downloaded-cover.png
+tiana files get-url WEB_ID/images/cover.png
+tiana files delete WEB_ID/images/cover.png
+```
+
+保持本任务选择的 `TIANA_API_ORIGIN`。CLI 操作租户根，所以访问应用文件时显式带真实 Web ID 子目录。`get-url` 的 URL 不是匿名分享链接；CLI 下载会另取并发送文件授权 Header。`put --overwrite` 同样先删除后上传，不能作为不确定结果的自动重试手段。