@tianacloud/agent-skills 1.0.16 → 1.0.17

package/README.md

@@ -38,7 +38,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.4 或更新正式版，需要 Node.js 20+。
+技能安装器只安装技能。Agent 首次执行 Tiana 任务时检查 CLI，缺少时自动执行下面的安装并继续原任务；CLI 要求 1.0.17 或更新正式版，需要 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.16",
+  "version": "1.0.17",
   "description": "Tiana Cloud Skills for accounts, SQLite, Git, Functions and Web applications",
   "license": "Apache-2.0",
   "repository": {
@@ -45,10 +45,11 @@
     "validate:plugin": "node scripts/validate-plugin.mjs",
     "validate:versions": "node scripts/validate-versions.mjs",
     "validate:workbuddy": "node scripts/validate-workbuddy.mjs",
-    "validate:ci": "npm run validate:skills && npm run validate:references && npm run validate:plugin && npm run validate:versions && npm run validate:workbuddy && npm run validate:connector && npm run test:doubao-auth",
+    "validate:ci": "npm run validate:skills && npm run validate:references && npm run validate:plugin && npm run validate:versions && npm run validate:workbuddy && npm run validate:connector && npm run test:doubao-auth && npm run test:packaging",
     "test:templates": "python3 -B -m unittest discover -s tests -p test_share_template_pack.py",
     "test:installer": "node --test scripts/installer.test.mjs",
     "test:release": "node --test scripts/release.test.mjs",
+    "test:packaging": "python3 -B scripts/doubao-packaging.test.py && python3 -B scripts/qwen-packaging.test.py",
     "build:doubao": "python3 scripts/build-doubao.py"
   },
   "devDependencies": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tiana",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "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.16"
+  version: "1.0.17"
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana
 ---
 

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

@@ -1,6 +1,6 @@
 # 开始使用
 
-在 Agent 实际执行命令的环境检查 `tiana version`。本技能要求 CLI 1.0.4 或更新正式版，具备分步登录、sqlite、git、web、file、list-template/init-template 和 version check。CLI 不存在、版本过低或无法核实时，直接执行下面的 npm latest 安装并重新核验，无需再次询问；核验通过后再执行资源操作。
+在 Agent 实际执行命令的环境检查 `tiana version`。本技能要求 CLI 1.0.17 或更新正式版，具备分步登录、sqlite、git、web、file、list-template/init-template 和 version check。CLI 不存在、版本过低或无法核实时，直接执行下面的 npm latest 安装并重新核验，无需再次询问；核验通过后再执行资源操作。
 
 连接器环境中，安装或更新前先按[宿主说明](connector-updates.md)定位实际 Node/npm、CLI 安装 prefix 和技能根目录，沿用宿主运行环境。
 

package/skills/tiana-function/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: tiana-function
-description: 使用 Tiana 创建和管理 Go 后端服务，读取及保存 Git 源码、编译发布、修改参数与 CORS；为 Web 应用开发访问 SQLite 的后端服务，或初始化用户密钥库、列出密钥名称与版本、写入和删除密钥时使用。前端页面开发配合 tiana-web。
+description: 使用 Tiana 创建和管理 Go 后端服务，读取及保存 Git 源码、编译发布、修改参数与 CORS、开发 WebSocket 实时接口；为 Web 应用开发访问 SQLite 的后端服务，或初始化用户密钥库、列出密钥名称与版本、写入和删除密钥时使用。前端页面开发配合 tiana-web。
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.16"
+  version: "1.0.17"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-function
 ---
@@ -33,6 +33,10 @@ metadata:
 
 App 作者专属的初始化和权限管理接口，按 [App 作者与初始权限](references/go-backend.md#app-作者与初始权限)使用 `caller.IsAppOwner()` 校验；作者指本次来源 Web 的创建者，与租户角色分开。前端的 `is_app_owner` 展示由 Tiana Web 负责。
 
+## WebSocket
+
+开发实时连接时，按 [WebSocket 实时连接](references/go-backend.md#websocket-实时连接)完成 Go 服务、浏览器原生连接、源码保存和发布验证，再交给 Web skill 绑定与托管验收。
+
 ## 用户密钥库
 
 初始化密钥库、查询名称与版本、写入或删除密钥时，阅读[密钥管理](references/secrets.md)。按操作回执报告 key、版本和结果；需要供函数使用时，继续配置密钥引用参数并核验生效。

package/skills/tiana-function/references/go-backend.md

@@ -118,3 +118,156 @@ if !present || !caller.IsAppOwner() {
 在启动后台 goroutine 前调用 `job, err := function.StartJob(jobID)`，成功后才启动任务，任务结束调用 `job.Finish()` 并处理错误。不同任务使用不同 ID；活跃期间相同 ID 的重复 Start 幂等，Finish 可重试，Finish 后复用 ID 表示新任务。已登记 Job 会阻止自动休眠；重启会清空登记，强制休眠和故障仍可中断任务。需要恢复的进度写入持久存储。
 
 本地参数文件采用 `{"MESSAGE":{"kind":"plain","value":"欢迎使用订单服务"}}`，设置 `FUNCTION_CONFIG_FILE` 指向它即可使用 SDK，不需解密密钥。平台提供的加密参数由 SDK 解密，业务继续使用 Get；读取错误应返回业务错误，不泄露参数内容。
+
+## WebSocket 实时连接
+
+先在 Web 应用概览的「允许调用的后端服务」中添加并保存目标服务，再编写页面。托管 Web 和 CLI 本地预览都提供 `window.tiana.functions.websocket(instanceId, path, {protocols?, signal?})`，返回在连接打开后兑现的 `Promise<WebSocket>`；普通 HTTP 继续使用 `functions.fetch`。
+
+### Go 服务：HTTP 与文本／二进制回声
+
+将下面完整程序保存为 `main.go`。它监听平台提供的 `PORT`，普通 HTTP 路由是 `/health`，WebSocket 路由是 `/ws`，握手及帧处理由标准 WebSocket 库负责。
+
+```go
+package main
+
+import (
+    "log"
+    "net/http"
+    "os"
+
+    "github.com/gorilla/websocket"
+)
+
+func main() {
+    mux := http.NewServeMux()
+    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+        _, _ = w.Write([]byte("ok"))
+    })
+    upgrader := websocket.Upgrader{
+        CheckOrigin: func(r *http.Request) bool { return true },
+    }
+    mux.HandleFunc("/ws", func(w http.ResponseWriter, r *http.Request) {
+        conn, err := upgrader.Upgrade(w, r, nil)
+        if err != nil {
+            return
+        }
+        defer conn.Close()
+        for {
+            kind, data, err := conn.ReadMessage()
+            if err != nil {
+                return
+            }
+            if err := conn.WriteMessage(kind, data); err != nil {
+                return
+            }
+        }
+    })
+    log.Fatal(http.ListenAndServe(":"+os.Getenv("PORT"), mux))
+}
+```
+
+示例的 `CheckOrigin` 显式允许跨来源页面，便于托管 Web 调用；业务需要限制来源时在自己的 handler 中实现 Origin 策略。普通 HTTP CORS 配置与 WebSocket Origin 校验独立。需要用户身份时，在 Upgrade 前通过 `function.CallerFromRequest(r)` 读取，并将本次调用者保存在该连接的局部状态中；Go SDK 的导入和版本沿用本页配套 SDK；从 `function.CallerFromRequest(r)` 获取身份后，在 Upgrade 前完成业务判断。
+
+在仅含此示例的新目录中执行：
+
+```sh
+go mod init example.com/function-echo
+go get github.com/gorilla/websocket@v1.5.3
+go mod tidy
+go build .
+PORT=8080 go run .
+# 另一终端验证普通 HTTP：
+curl http://127.0.0.1:8080/health
+```
+
+保存 `main.go`、`go.mod`、`go.sum`，再编译发布：
+
+```sh
+tiana function create "实时回声" --source-dir /services/echo --wait --json
+tiana function source list FUNCTION_ID --json
+tiana function source save FUNCTION_ID --base-commit COMMIT --file main.go=./main.go --file go.mod=./go.mod --file go.sum=./go.sum --json
+tiana function publish FUNCTION_ID --commit SAVED_COMMIT --wait --json
+```
+
+将 `FUNCTION_ID` 替换为创建回执 ID，`COMMIT` 使用 source list 返回的提交；完全空仓库首次保存才使用 `empty`。`SAVED_COMMIT` 使用 save 返回的新提交。已有 Web 共仓时，create 增加 `--git-instance-id GIT_ID`，保留该仓库其他文件。
+
+### 浏览器完整入口模块
+
+将下面保存为 Web 的 `app.js`，替换服务 ID。按钮提供连接、取消尚未完成的握手、正常关闭和手动重连；页面直接显示错误与回声结果。
+
+```javascript
+const functionId = "<后端服务实例 ID>";
+const panel = document.createElement("section");
+panel.innerHTML = `<button id="connect">连接 / 重新连接</button>
+  <button id="cancel">取消连接</button><button id="close">关闭</button>
+  <pre role="status"></pre>`;
+document.body.append(panel);
+const status = panel.querySelector("pre");
+let socket;
+let pending;
+function show(message) { status.textContent = message; }
+panel.querySelector("#connect").onclick = async () => {
+  if (pending || (socket && socket.readyState < WebSocket.CLOSING)) return;
+  const controller = new AbortController();
+  pending = controller;
+  show("正在连接…");
+  try {
+    const ws = await window.tiana.functions.websocket(functionId, "/ws", {
+      signal: controller.signal,
+    });
+    socket = ws; // Promise 在 open 后返回，此时注册 message/error/close。
+    ws.binaryType = "arraybuffer";
+    ws.addEventListener("message", (event) => {
+      show(typeof event.data === "string"
+        ? `文本回声：${event.data}` : `二进制回声：${event.data.byteLength} bytes`);
+    });
+    ws.addEventListener("error", () => show("连接发生错误，请检查服务后手动重连"));
+    ws.addEventListener("close", (event) => {
+      show(`连接已关闭：code=${event.code}，clean=${event.wasClean}`);
+      if (socket === ws) socket = undefined;
+    });
+    show("已连接，正在发送文本和二进制消息");
+    ws.send("hello");
+    ws.send(new Uint8Array([1, 2, 3]));
+  } catch (error) {
+    show(error?.name === "AbortError" ? "已取消连接" : "连接失败，请检查应用授权和后端服务");
+  } finally {
+    if (pending === controller) pending = undefined;
+  }
+};
+panel.querySelector("#cancel").onclick = () => pending?.abort();
+panel.querySelector("#close").onclick = () => socket?.close(1000, "done");
+window.addEventListener("pagehide", () => {
+  pending?.abort();
+  socket?.close(1000, "page exit");
+});
+```
+
+平台通过现有 Site 授权提供短期凭据，以 `access_token` 查询参数用于握手；页面只保存服务 ID，不管理 Token，也不要记录 `socket.url`。浏览器握手失败通常只给通用错误，无法据此确定准确的 HTTP 原因。`signal` 只取消待完成的握手；连接打开后使用原生 `close()`。SDK 客户端 dispose、页面退出或检测到会话失效会关闭其连接；应用自己决定何时重新连接，不自动重连或重放消息。
+
+示例没有申请子协议，成功连接的 `socket.protocol` 可以为空。设置 `protocols` 时，业务服务端应从客户端提供的列表中选择并确认一个双方支持的协议。平台透明转发协商，业务双方约定协议。
+
+新建 Web 时指定固定入口，并先绑定服务：
+
+```sh
+tiana web create "实时回声页面" --entry app.js --json
+tiana web functions get WEB_ID --json
+tiana web functions set WEB_ID --function-id FUNCTION_ID --expected-revision REVISION --json
+# 将 app.js 放在 dist/，已有 Web 使用其创建时固定的入口文件名。
+tiana web serve WEB_ID --dir dist --port 4174
+tiana web publish WEB_ID --dir dist --json
+tiana web status WEB_ID --publish-id PUBLISH_ID --json
+tiana web status WEB_ID --json
+```
+
+绑定 set 替换完整列表，保留仍需调用的其他服务；`REVISION` 来自 get。新 Web 初始停用，发布后在 Console Web 概览点击「启用应用」。核对当前内容 `state: running`，并确认 `remote_sha256`、`serving_sha256` 均等于发布回执的目标摘要；上传成功本身不代表正在服务。通过实际托管入口登录，验证文本、二进制回声、关闭 code 1000 和手动重连，同时用 `functions.fetch(FUNCTION_ID, "/health")` 验证普通 HTTP。
+
+### 连接与服务生命周期
+
+连接建立后没有固定时长上限，并阻止 Function 自动休眠。最后一条连接关闭后，平台结合现有 HTTP 请求、Jobs 和 idleN 判断休眠。连接准入计一次请求，消息不逐条计为请求；连接和普通调用共享并发预算。凭据到期或撤销影响后续新连接，不主动切断已经建立的连接。
+
+发布代码在下次唤醒时使用；当前连接继续使用旧执行。Console「强制休眠」会断开连接，应用需自行处理关闭并按业务需要手动重连。
+
+
+源码回执和构建失败恢复见[后端服务命令](commands.md#构建和发布)；Web 资源关联与托管验收继续按 `tiana-web` 技能的“后端交接与接入验证”和“预览与发布”流程完成。报告实际验证环境与未完成项，配套平台验证通过后再交付使用。

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.16"
+  version: "1.0.17"
   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.16"
+  version: "1.0.17"
   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.16"
+  version: "1.0.17"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-web
 ---

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

@@ -1,6 +1,6 @@
 # WebApp 文件存储
 
-CLI 文件操作要求 1.0.4 或更新正式版，使用 `tiana file --help` 核验命令入口。WebApp 文件能力还需目标环境提供配套的 MGR、Web 与 serverless-js Bootstrap；使用前核对目标环境能力。
+CLI 文件操作要求 1.0.17 或更新正式版，使用 `tiana file --help` 核验命令入口。WebApp 文件能力还需目标环境提供配套的 MGR、Web 与 serverless-js Bootstrap；使用前核对目标环境能力。
 
 存储分工及静态小图片的 16 KiB 上限见[数据与素材存储](storage-and-assets.md)。
 外置预置素材按[模板素材文件](template-files.md)使用 `template-assets/` 相对路径，