@tianacloud/agent-skills 1.0.1 → 1.0.2

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.2",
   "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.2",
   "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.2"
   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.2 --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.1 或更新正式版，具备分步登录、sqlite、git、web、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.1 --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.2"
   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.2 --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.2"
   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.2 --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.2"
   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.2 --json`，使用实际加载的 metadata.version。调用前在会话上下文中记为已尝试；后续轮次、重复加载或切换技能均复用该记录，检查失败也不自动重试。上下文压缩或任务交接时保留记录，新会话重新检查。
 
 仅在 `should_notify=true` 时简短提醒并询问是否升级；用户选择稍后或检查不可用时继续原任务。CLI 仍管理检查缓存和共同的 24 小时提醒额度。升级及重载见[开始使用](../tiana/references/getting-started.md#更新)。
 

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 关联。环境不具备候选能力时报告具体阻塞并提供本地开发地址；不自行修改部署。