@tianacloud/agent-skills 1.0.12 → 1.0.13

package/README.md

@@ -1,6 +1,6 @@
 # Tiana Agent Skills
 
-五个基础技能覆盖 Tiana 账号与实例、SQLite、Git、后端服务和 Web 应用。应用模板由在线目录提供，用户描述需求后，Agent 根据实时目录决定使用模板还是直接开发。
+六个基础技能覆盖 Tiana 账号与实例、SQLite、Git、后端服务、密钥和 Web 应用。应用模板由在线目录提供，用户描述需求后，Agent 根据实时目录决定使用模板还是直接开发。
 
 ## 从 npm 安装
 
@@ -24,9 +24,9 @@ npx --yes @tianacloud/agent-skills@latest install --dir /path/to/client/skills
 
 Windows PowerShell 使用 `npx.cmd`。目录可以含空格，用引号包住。重复安装会更新包内全部技能并补齐新版新增技能，其他技能保留。安装完成后让客户端重载技能或开始新会话。
 
-WorkBuddy、豆包按所用版本的目录／ZIP 导入方式加载这五个目录，保留 SKILL.md 和 references。若要求 ZIP，可将每个技能目录的内容打包，SKILL.md 位于包根部。WorkBuddy 专用本地化 ZIP 由维护者构建流程提供；本仓验证 ZIP 格式和内容，不声称已验收这些客户端的运行行为。
+WorkBuddy、豆包按所用版本的目录／ZIP 导入方式加载这六个目录，保留 SKILL.md 和 references。若要求 ZIP，可将每个技能目录的内容打包，SKILL.md 位于包根部。WorkBuddy 专用本地化 ZIP 由维护者构建流程提供；本仓验证 ZIP 格式和内容，不声称已验收这些客户端的运行行为。
 
-## 五个入口
+## 六个入口
 
 | 技能 | 职责 |
 | --- | --- |
@@ -34,6 +34,7 @@ WorkBuddy、豆包按所用版本的目录／ZIP 导入方式加载这五个目
 | [tiana-sqlite](skills/tiana-sqlite/SKILL.md) | SQL、表结构、SDK 连接和数据库分支 |
 | [tiana-git](skills/tiana-git/SKILL.md) | Git 实例、原生仓库操作和源码版本同步 |
 | [tiana-function](skills/tiana-function/SKILL.md) | Go 后端服务源码、构建发布、参数/CORS 与数据库后端 |
+| [tiana-secrets](skills/tiana-secrets/SKILL.md) | 用户密钥库初始化、名称与版本列表、写入和删除 |
 | [tiana-web](skills/tiana-web/SKILL.md) | 实时模板选择、工程与数据初始化、通用开发、构建发布 |
 
 Web 技能每次任务都实际执行 `tiana web list-template --json`，使用当前 name/description 判断需求。模板 ZIP 原样下载解压到独立项目目录；Agent 按根部 metadata.json 替换变量、先 schema 后 seeds。模板源码和制作规范见 [template-apps](https://github.com/tianacloud/template-apps)，客户安装模板由 CLI 和 MGR 目录完成。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianacloud/agent-skills",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "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.12",
+  "version": "1.0.13",
   "description": "Tiana Cloud account, SQLite, Git, Functions and Web application workflows",
   "author": {
     "name": "Tiana Cloud",

package/skills/tiana/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: tiana
-description: 使用 Tiana Cloud 管理实例、安装 CLI、登录和恢复账号会话。通用 Tiana 任务从此技能开始；Web 应用创建发布使用 tiana-web，数据库和分支使用 tiana-sqlite，Git 仓库和源码同步使用 tiana-git，后端服务与数据库后端使用 tiana-function。
+description: 使用 Tiana Cloud 管理实例、安装 CLI、登录和恢复账号会话。通用 Tiana 任务从此技能开始；Web 应用创建发布使用 tiana-web，数据库和分支使用 tiana-sqlite，Git 仓库和源码同步使用 tiana-git，后端服务与数据库后端使用 tiana-function，用户密钥管理使用 tiana-secrets。
 license: Apache-2.0
 metadata:
   author: Tiana Cloud
-  version: "1.0.12"
+  version: "1.0.13"
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana
 ---
 
@@ -35,6 +35,7 @@ CLI 仍管理检查缓存和共同的 24 小时提醒额度；该额度不限制
 | Go 后端服务、源码、参数及编译发布 | [tiana-function](../tiana-function/SKILL.md) |
 | SQLite 查询、连接、建表及数据库分支 | [tiana-sqlite](../tiana-sqlite/SKILL.md) |
 | Git 实例、仓库、源码版本同步 | [tiana-git](../tiana-git/SKILL.md) |
+| 用户密钥库初始化、名称列表、写入与删除 | [tiana-secrets](../tiana-secrets/SKILL.md) |
 | 登录、账号、额度、通用实例管理 | 本技能 |
 
 组合请求中，安装完成后继续用户要求的任务。按需读取对应技能和直接链接的参考资料，跨技能文件按宿主返回的安装目录解析。

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.12"
+  version: "1.0.13"
   parent: tiana
   source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-function
 ---
@@ -27,7 +27,7 @@ metadata:
 
 涉及数据库 Token、第三方 API Key 等敏感配置时，必须先按[参数配置与生效](references/commands.md#参数配置与生效)配置，再按 [Go 后端服务开发](references/go-backend.md)读取与使用。参数更新无需重新编译，但要核对保存回执的应用状态和实际请求结果。
 
-数据库 Endpoint、Token 和第三方密钥保存在后端服务参数中，不写入 Git、前端源码、业务响应或日志。缺少实际凭据时说明待配置项，不使用占位值宣称联调成功。Web 的数据访问方式、资源绑定与模板制作由 Tiana Web 负责。
+数据库 Endpoint 使用明文参数；Token 和第三方密钥先通过 [Tiana Secrets](../tiana-secrets/SKILL.md) 写入用户密钥库，再保存为后端服务的密钥引用参数，不写入 Git、前端源码、业务响应或日志。缺少实际凭据时说明待配置项，不使用占位值宣称联调成功。Web 的数据访问方式、资源绑定与模板制作由 Tiana Web 负责。
 
 调用方身份通过 SDK 从请求上下文读取，业务需要区分用户数据时使用该身份，不能相信请求体中自报的用户 ID。完成接口核验后，将所需调用身份与数据范围一并交给 Web skill 验证。
 

package/skills/tiana-function/references/commands.md

@@ -60,10 +60,12 @@ set 替换整个参数对象。get 的 JSON 回执从 `data.parameters` 取出
 {
   "MESSAGE": {"kind": "plain", "value": "欢迎使用订单服务"},
   "SQLITE_ENDPOINT": {"kind": "plain", "value": "<实际数据库 Endpoint>"},
-  "SQLITE_TOKEN": {"kind": "plain", "value": "<实际数据库实例 Token>"}
+  "SQLITE_TOKEN": {"kind": "secret", "value": "production/database/token"}
 }
 ```
 
+先通过 [Tiana Secrets](../../tiana-secrets/SKILL.md) 写入敏感值，再将其 key 配为 secret；plain 保存明文，secret 只保存引用名称。
+
 含凭据的文件放在 Git 和前端构建目录之外，使用仅当前用户可读写的临时文件，用完删除。get 和 set 回执都可能包含参数值，同样写入受限临时文件处理，不打印到对话或交付日志。仅报告参数名称与生效状态。
 
 核对 set 返回的 `data.application`：
@@ -74,7 +76,7 @@ set 替换整个参数对象。get 的 JSON 回执从 `data.parameters` 取出
 | `next_start` | 配置已保存，下次启动使用；调用已发布的服务完成唤醒并验证。 |
 | `pending` | 已保存但当前执行尚未确认收到。可在 Console 点击「重试下发」，再核对结果；不能报告已生效。 |
 
-更新参数无需重新编译。Go 读取与使用按[Go 后端服务开发](go-backend.md)；验证数据库连接或上游调用是否成功，不通过回显密钥来验证。参数读取、必需值缺失和下游拒绝都要有明确业务错误。轮换凭据后再验证新请求，避免代码启动时缓存旧值造成“配置改了仍失败”。
+更新参数无需重新编译。Go 读取与使用按[Go 后端服务开发](go-backend.md)；验证数据库连接或上游调用是否成功，不通过回显密钥来验证。参数读取、必需值缺失和下游拒绝都要有明确业务错误。密钥引用变化在下次冷启动生效；当前执行首次读取成功后缓存值，验证轮换时需要新的冷启动。
 
 ## CORS
 

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

@@ -1,6 +1,10 @@
 # Go 后端服务开发
 
-后端服务是监听 `PORT` 环境变量指定端口的 Go HTTP 程序。平台固定 Go 1.26 工具链。source_dir 包含 package main，所属 go.mod 可在该目录或仓库内上级目录，多个入口可共享模块；依赖由构建流程下载。使用 SDK 时选择包含 function 包的已发布版本，记录在 go.mod 中，具体版本以当前配套 SDK 发布为准。
+后端服务是监听 `PORT` 环境变量指定端口的 Go HTTP 程序。平台固定 Go 1.26 工具链。source_dir 包含 package main，所属 go.mod 可在该目录或仓库内上级目录，多个入口可共享模块；依赖由构建流程下载。本页的 Get(value, error) 与密钥引用示例使用下列配套 SDK；将解析后的 go.mod、go.sum 一起保存到源码仓库。
+
+```sh
+go get github.com/tianacloud/sdk-go@v1.1.0-function.4.0.20261102183840-52d162f75066
+```
 
 最小程序返回 JSON：
 
@@ -36,14 +40,14 @@ if err != nil {
     http.Error(w, "读取参数失败", http.StatusInternalServerError)
     return
 }
-message, ok := params.Get("MESSAGE")
-if !ok {
+message, err := params.Get("MESSAGE")
+if err != nil {
     http.Error(w, "尚未配置欢迎语", http.StatusInternalServerError)
     return
 }
 ```
 
-导入 `github.com/tianacloud/sdk-go/function`。SDK 使用平台提供的 `FUNCTION_CONFIG_FILE` 读取配置，不自行拼接宿主路径。Get 返回字符串和是否存在；已配置空字符串也会返回 true，必需且非空的业务凭据还需检查空值。不要返回整个参数对象，其中可能有数据库凭据。
+导入 `github.com/tianacloud/sdk-go/function`。SDK 使用平台提供的 `FUNCTION_CONFIG_FILE` 读取配置，不自行拼接宿主路径。Get 返回字符串和 error；不存在时返回 function.ErrNotExist，已配置空字符串返回 ("", nil)，必需且非空的业务凭据还需检查空值。不要返回整个参数对象，其中可能有数据库凭据。
 
 ## 使用敏感配置
 
@@ -52,24 +56,24 @@ if !ok {
 例如 `PAYMENT_API_KEY` 是业务自定义的第三方密钥参数名，req 是业务已创建的上游 HTTP 请求：
 
 ```go
-apiKey, ok := params.Get("PAYMENT_API_KEY")
-if !ok || apiKey == "" {
+apiKey, err := params.Get("PAYMENT_API_KEY")
+if err != nil || apiKey == "" {
     http.Error(w, "支付服务尚未配置", http.StatusServiceUnavailable)
     return
 }
 req.Header.Set("Authorization", "Bearer "+apiKey)
 ```
 
-按上游真实协议设置凭据，并检查调用结果。密钥仅用于后端向上游发请求；响应只返回业务需要的结果，不返回密钥或原始请求头。配置热更新时每次请求读取；如果复用依赖密钥的客户端，须在参数变化后更新客户端，不能一直使用启动时的旧凭据。
+按上游真实协议设置凭据，并检查调用结果。密钥仅用于后端向上游发请求；响应只返回业务需要的结果，不返回密钥或原始请求头。明文参数按配置更新；密钥参数首次读取成功后在本次执行内缓存，后续密钥变化需要新的冷启动才能读取当前值。
 
 ## 访问 SQLite
 
 先用 [Tiana SQLite](../../tiana-sqlite/SKILL.md)核实数据库实例、表结构及初始化 SQL。数据库 Endpoint 和实例 Token 分别保存为后端服务参数 `SQLITE_ENDPOINT`、`SQLITE_TOKEN`，Token 在该数据库的连接管理中创建。只在后端服务内读取并传给 SDK：
 
 ```go
-endpoint, endpointOK := params.Get("SQLITE_ENDPOINT")
-secret, tokenOK := params.Get("SQLITE_TOKEN")
-if !endpointOK || !tokenOK || endpoint == "" || secret == "" {
+endpoint, endpointErr := params.Get("SQLITE_ENDPOINT")
+secret, tokenErr := params.Get("SQLITE_TOKEN")
+if endpointErr != nil || tokenErr != nil || endpoint == "" || secret == "" {
     http.Error(w, "数据库参数未配置", http.StatusInternalServerError)
     return
 }
@@ -96,7 +100,7 @@ defer db.Close()
 
 ## App 作者与初始权限
 
-在需要作者权限的 HTTP handler 内使用 Go SDK `v1.1.0-function.4` 或包含 IsAppOwner 的后续配套版本，并将实际依赖固定到 go.mod：
+在需要作者权限的 HTTP handler 内使用 Go SDK `v1.1.0-function.4.0.20261102183840-52d162f75066`（包含参数 Get 错误语义和密钥引用），并将实际依赖固定到 go.mod：
 
 ```go
 caller, present := function.CallerFromRequest(r)

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

package/skills/tiana-secrets/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: tiana-secrets
+description: 管理 Tiana 用户密钥库：初始化、列出密钥名称和当前版本号、写入与删除密钥。函数参数引用密钥时配合 tiana-function；不提供密钥明文读取或导出。
+license: Apache-2.0
+metadata:
+  author: Tiana Cloud
+  version: "1.0.13"
+  parent: tiana
+  source: https://github.com/tianacloud/agent-skills/tree/main/skills/tiana-secrets
+---
+
+# Tiana Secrets
+
+安装、登录、环境选择和本会话的 CLI／Skills 更新检查复用 [Tiana](../tiana/SKILL.md)。执行前核实 `tiana secrets --help` 包含 init、list、set、remove；若正式 CLI 尚未提供，说明配套能力未发布，使用用户已指定的候选版本或等待配套发布，不猜造其他访问方式。
+
+## 初始化与列表
+
+```sh
+tiana secrets init --json
+tiana secrets list --keyword database --page-size 50 --json
+```
+
+每个用户一个密钥库。init 复用已有实例及创建任务，只占一个实例名额；已有实例停用时不会自动启用。accepted 仅表示创建已受理，保留 instance_id、job_id 及实际状态。失败时使用 Console 原任务的重试入口；结果未知时再次 init 查询同一实例，不创建替代实例。
+
+list 只返回名称与当前版本号，支持任意位置包含关键词。需要下一页时将返回的 next_cursor 原样传给 `--after`。只查询当前任务需要的页面，不把没有结果误认为未启用。
+
+## 写入与删除
+
+```sh
+tiana secrets set production/database/password --file /private/input/secret.txt --json
+tiana secrets remove production/database/password --force --json
+```
+
+Set 的值从用户指定文件或 `--stdin` 输入，保留空字符串、空格和换行。不要把值放入命令参数、源码、对话或日志。使用运行时管道传递标准输入，避免包含值的 shell 字面量。自行创建的输入临时文件放在 Git 外、仅当前用户可读写，完成后删除；用户原文件保持原样。
+
+Set 直接写入，不先读取密钥。新 key 从 v1 开始，值变化则版本号增加，同值不变；只保留当前值。Remove 删除整个 key，重新创建从 v1 开始。`--force` 用于已确认的删除意图；交互终端可省略并确认提示。
+
+仅根据返回的 key、version、changed、删除结果或 List 元数据报告操作。失败和未知结果不要自动重复写入；先核对状态，不能以版本变化证明密钥值内容。普通输出、JSON、错误、诊断都不回显密钥值。
+
+## 函数引用
+
+写入后，把 key 交给 [Tiana Function](../tiana-function/SKILL.md)。函数参数使用 `{"kind":"secret","value":"production/database/password"}`，value 是引用名称，不是密钥明文；函数执行首次读取成功后缓存，下次冷启动读取当前值。
+
+本技能不提供 Get、明文回显或导出，也不通过 curl、SDK 或函数接口绕过 CLI 读取明文。需要人工查看时，引导用户到 Console 输入安全口令自行操作。平台 HashiCorp Vault 运维不属于本技能。

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