Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

docs(api): document and expose the skill env var surface

wizardchen989907fe6ec9
diff --git a/client/README.md b/client/README.md
index f4162c600..7b1c0456f 100644
--- a/client/README.md
+++ b/client/README.md
@@ -15,7 +15,7 @@
7. **分块管理**:查询、更新和删除知识分块
8. **消息管理**:获取和删除会话消息
9. **模型管理**:创建、获取、更新和删除模型
-10. **沙箱技能**:向沙箱配置安装技能(zip 上传,或从 ClawHub / SkillHub / GitHub 等来源)
+10. **沙箱技能**:向沙箱配置安装技能(zip 上传,或从 ClawHub / SkillHub / GitHub 等来源),并配置技能所需的环境变量
## 使用方法
@@ -427,6 +427,37 @@ _ = files
_ = content
```
+### 示例:配置技能的环境变量
+
+技能安装时会声明它需要哪些环境变量。值分两层:空间级由管理员设置、对所有人生效;个人级只对**当前调用身份**生效,并覆盖空间级。任何接口都不会回读已保存的值,只报告是否已设置。
+
+用 API Key 调用与网页登录是两种不同身份:在网页里填的个人级值不会作用于 API Key 发起的执行。集成场景请优先用空间级值。
+
+```go
+// 空间级:对该空间所有人生效,需要 Admin 及以上权限
+skill, err := apiClient.SetSandboxSkillEnvValues(
+ context.Background(), sandboxConfigID, skillID,
+ map[string]string{"TAVILY_API_KEY": "tvly-xxxxx"})
+if err != nil {
+ // 处理错误
+}
+
+// 个人级:只对当前调用身份生效
+err = apiClient.SetMySkillEnvVar(
+ context.Background(), skillID, "TAVILY_API_KEY", "tvly-yyyyy")
+if err != nil {
+ // 处理错误
+}
+
+// 查看哪些变量还没填。清空一个值用 Delete,而不是写入空字符串
+groups, err := apiClient.ListMyEnvVars(context.Background())
+if err != nil {
+ // 处理错误
+}
+_ = skill
+_ = groups
+```
+
## 完整示例
请参考 `example.go` 文件中的 `ExampleUsage` 函数,其中展示了客户端的完整使用流程。
\ No newline at end of file
diff --git a/client/README_EN.md b/client/README_EN.md
index 303f54130..2527fe2a6 100644
--- a/client/README_EN.md
+++ b/client/README_EN.md
@@ -15,7 +15,7 @@ The client includes the following main functional modules:
7. **Message Management**: Retrieve and delete session messages
8. **Model Management**: Create, retrieve, update, and delete models
9. **Evaluation Function**: Start evaluation tasks and get evaluation results
-10. **Sandbox skills**: Install a skill onto a sandbox config (zip upload, or ClawHub / SkillHub / GitHub source)
+10. **Sandbox skills**: Install a skill onto a sandbox config (zip upload, or ClawHub / SkillHub / GitHub source) and configure the environment variables it needs
## Usage
@@ -241,6 +241,37 @@ _ = files
_ = content
```
+### Example: Configure a skill's environment variables
+
+A skill declares the environment variables it needs when it is installed. Values live in two layers: a workspace value an admin sets for everybody, and a per-identity value that overrides it for the caller alone. No endpoint reads a stored value back; they only report whether one is set.
+
+An API key and a web login are different identities: a personal value entered through the web UI does not apply to runs driven by an API key. Prefer workspace values for integrations.
+
+```go
+// Workspace-wide, applies to everybody; requires Admin or above
+skill, err := apiClient.SetSandboxSkillEnvValues(
+ context.Background(), sandboxConfigID, skillID,
+ map[string]string{"TAVILY_API_KEY": "tvly-xxxxx"})
+if err != nil {
+ // Handle error
+}
+
+// Applies to the calling identity alone
+err = apiClient.SetMySkillEnvVar(
+ context.Background(), skillID, "TAVILY_API_KEY", "tvly-yyyyy")
+if err != nil {
+ // Handle error
+}
+
+// See what is still unset. Clearing a value is a delete, not a write of ""
+groups, err := apiClient.ListMyEnvVars(context.Background())
+if err != nil {
+ // Handle error
+}
+_ = skill
+_ = groups
+```
+
## Complete Example
Please refer to the `ExampleUsage` function in the `example.go` file, which demonstrates the complete usage flow of the client.
diff --git a/client/env_var.go b/client/env_var.go
new file mode 100644
index 000000000..426168e92
--- /dev/null
+++ b/client/env_var.go
@@ -0,0 +1,156 @@
+package client
+
+import (
+ "context"
+ "fmt"
+ "net/http"
+ "time"
+)
+
+// Environment variable sources, as reported by ListMyEnvVars. The three states
+// are distinct: a value the workspace filled in for everybody and one the
+// caller filled in for themselves lead to different actions, and neither is
+// "nobody has filled this in".
+const (
+ EnvSourceUnset = "unset"
+ EnvSourceWorkspace = "workspace"
+ EnvSourceUser = "user"
+)
+
+// EnvVarView is one environment variable as its owner may see it. There is
+// deliberately no value field: the API never reads a stored value back out.
+type EnvVarView struct {
+ Name string `json:"name"`
+ Description string `json:"description,omitempty"`
+ Required bool `json:"required,omitempty"`
+ // Source is one of EnvSourceUnset, EnvSourceWorkspace or EnvSourceUser,
+ // and reports which layer an execution would actually take the value from.
+ Source string `json:"source"`
+ // UpdatedAt is set only for the caller's own value.
+ UpdatedAt *time.Time `json:"updated_at,omitempty"`
+}
+
+// SkillEnvGroup is one skill's declared credentials.
+type SkillEnvGroup struct {
+ SkillID string `json:"skill_id"`
+ SkillName string `json:"skill_name"`
+ Vars []EnvVarView `json:"vars"`
+}
+
+// ConfigEnvGroup is one sandbox config: the caller's own config-wide variables
+// plus the declared credentials of the skills installed on it.
+type ConfigEnvGroup struct {
+ SandboxConfigID string `json:"sandbox_config_id"`
+ SandboxConfigName string `json:"sandbox_config_name"`
+ Vars []EnvVarView `json:"vars"`
+ Skills []SkillEnvGroup `json:"skills"`
+}
+
+type myEnvVarsResponse struct {
+ Success bool `json:"success"`
+ Data []ConfigEnvGroup `json:"data"`
+}
+
+// envVarRequest is the body every write endpoint takes. It carries no identity:
+// the server derives whose values are touched from the credentials on the
+// request, so one caller can never write another's.
+type envVarRequest struct {
+ SkillID string `json:"skill_id,omitempty"`
+ SandboxConfigID string `json:"sandbox_config_id,omitempty"`
+ Name string `json:"name"`
+ Value string `json:"value,omitempty"`
+}
+
+// ListMyEnvVars returns every sandbox config of the workspace with the caller's
+// own config-wide variables and the credentials its skills declared, each
+// reporting whether it is unset, filled in workspace-wide, or filled in by the
+// caller. Values are never returned.
+//
+// Values are stored per calling identity, not per user: a run driven by an API
+// key does not see values entered through the web UI, and vice versa. Use
+// SetSandboxSkillEnvValues for a credential that should apply to everybody.
+func (c *Client) ListMyEnvVars(ctx context.Context) ([]ConfigEnvGroup, error) {
+ resp, err := c.doRequest(ctx, http.MethodGet, "/api/v1/me/env-vars", nil, nil)
+ if err != nil {
+ return nil, err
+ }
+ var response myEnvVarsResponse
+ if err := parseResponse(resp, &response); err != nil {
+ return nil, err
+ }
+ return response.Data, nil
+}
+
+// SetMySkillEnvVar stores the caller's own value for one variable a skill
+// declared. It overrides the workspace-wide value for this caller only, and is
+// injected only into executions that name the skill. A name the skill did not
+// declare is refused.
+func (c *Client) SetMySkillEnvVar(ctx context.Context, skillID, name, value string) error {
+ if skillID == "" {
+ return fmt.Errorf("skill ID is required")
+ }
+ if name == "" {
+ return fmt.Errorf("environment variable name is required")
+ }
+ body := envVarRequest{SkillID: skillID, Name: name, Value: value}
+ resp, err := c.doRequest(ctx, http.MethodPut, "/api/v1/me/env-vars/skill", body, nil)
+ if err != nil {
+ return err
+ }
+ return parseResponse(resp, nil)
+}
+
+// DeleteMySkillEnvVar removes the caller's own value. The workspace-wide value,
+// if there is one, applies again afterwards. Deleting a value that was never
+// set returns a 404. Clearing is a delete rather than a write of "", so there
+// is one unambiguous way to revoke.
+func (c *Client) DeleteMySkillEnvVar(ctx context.Context, skillID, name string) error {
+ if skillID == "" {
+ return fmt.Errorf("skill ID is required")
+ }
+ if name == "" {
+ return fmt.Errorf("environment variable name is required")
+ }
+ body := envVarRequest{SkillID: skillID, Name: name}
+ resp, err := c.doRequest(ctx, http.MethodDelete, "/api/v1/me/env-vars/skill", body, nil)
+ if err != nil {
+ return err
+ }
+ return parseResponse(resp, nil)
+}
+
+// SetMySandboxEnvVar stores the caller's own value for one config-wide
+// variable. Unlike a skill variable the name is free-form, and the value is
+// injected into every skill script and shell command this caller runs on that
+// sandbox config. Names starting with WEKNORA_, and names the sandbox relies on
+// such as PATH, are refused.
+func (c *Client) SetMySandboxEnvVar(ctx context.Context, configID, name, value string) error {
+ if configID == "" {
+ return fmt.Errorf("sandbox config ID is required")
+ }
+ if name == "" {
+ return fmt.Errorf("environment variable name is required")
+ }
+ body := envVarRequest{SandboxConfigID: configID, Name: name, Value: value}
+ resp, err := c.doRequest(ctx, http.MethodPut, "/api/v1/me/env-vars/sandbox", body, nil)
+ if err != nil {
+ return err
+ }
+ return parseResponse(resp, nil)
+}
+
+// DeleteMySandboxEnvVar removes the caller's own config-wide variable.
+func (c *Client) DeleteMySandboxEnvVar(ctx context.Context, configID, name string) error {
+ if configID == "" {
+ return fmt.Errorf("sandbox config ID is required")
+ }
+ if name == "" {
+ return fmt.Errorf("environment variable name is required")
+ }
+ body := envVarRequest{SandboxConfigID: configID, Name: name}
+ resp, err := c.doRequest(ctx, http.MethodDelete, "/api/v1/me/env-vars/sandbox", body, nil)
+ if err != nil {
+ return err
+ }
+ return parseResponse(resp, nil)
+}
diff --git a/client/skill.go b/client/skill.go
index 4548c4374..7555ac072 100644
--- a/client/skill.go
+++ b/client/skill.go
@@ -146,6 +146,97 @@ func (c *Client) ReinstallSandboxSkill(
return response.Data.SkillID, nil
}
+// SandboxSkillEnv is one environment variable an installed skill declared. It
+// reports whether a workspace-wide value exists and never what it is.
+type SandboxSkillEnv struct {
+ Name string `json:"name"`
+ Description string `json:"description,omitempty"`
+ Required bool `json:"required,omitempty"`
+ IsSet bool `json:"is_set"`
+}
+
+// SandboxSkill is one installed skill of a sandbox config.
+type SandboxSkill struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Version string `json:"version,omitempty"`
+ Description string `json:"description,omitempty"`
+ Enabled bool `json:"enabled"`
+ Status string `json:"status"`
+ Error string `json:"error,omitempty"`
+ BundleSHA256 string `json:"bundle_sha256,omitempty"`
+ InstalledSnapshotID string `json:"installed_snapshot_id,omitempty"`
+ InstallSessionID string `json:"install_session_id,omitempty"`
+ InstallMessageID string `json:"install_message_id,omitempty"`
+ Envs []SandboxSkillEnv `json:"envs,omitempty"`
+}
+
+type sandboxSkillResponse struct {
+ Success bool `json:"success"`
+ Data SandboxSkill `json:"data"`
+}
+
+// SandboxSkillUpdate is what one PATCH may change. Both fields are optional,
+// but a request carrying neither is refused: a nil Enabled is not a request to
+// hide the skill, and a nil Envs must leave every stored value alone.
+type SandboxSkillUpdate struct {
+ Enabled *bool `json:"enabled,omitempty"`
+ Envs *map[string]string `json:"envs,omitempty"`
+}
+
+// UpdateSandboxSkill shows or hides an installed skill and sets the
+// workspace-wide values of the environment variables it declared. Visibility is
+// metadata only: the files stay in the image either way.
+//
+// Only declared names are written; a name outside the declaration is ignored
+// rather than refused, so a stale form cannot fail an otherwise valid save. An
+// empty string clears a value and keeps the declaration, because "nobody filled
+// this in" and "this is not needed" are different states.
+//
+// A stored value is never read back: the returned Envs report IsSet only.
+func (c *Client) UpdateSandboxSkill(
+ ctx context.Context, configID, skillID string, update SandboxSkillUpdate,
+) (*SandboxSkill, error) {
+ if configID == "" {
+ return nil, fmt.Errorf("sandbox config ID is required")
+ }
+ if skillID == "" {
+ return nil, fmt.Errorf("skill ID is required")
+ }
+ if update.Enabled == nil && update.Envs == nil {
+ return nil, fmt.Errorf("enabled or envs is required")
+ }
+ path := "/api/v1/sandbox-configs/" + url.PathEscape(configID) +
+ "/skills/" + url.PathEscape(skillID)
+ resp, err := c.doRequest(ctx, http.MethodPatch, path, update, nil)
+ if err != nil {
+ return nil, err
+ }
+ var response sandboxSkillResponse
+ if err := parseResponse(resp, &response); err != nil {
+ return nil, err
+ }
+ return &response.Data, nil
+}
+
+// SetSandboxSkillEnabled is the visibility half of UpdateSandboxSkill.
+func (c *Client) SetSandboxSkillEnabled(
+ ctx context.Context, configID, skillID string, enabled bool,
+) (*SandboxSkill, error) {
+ return c.UpdateSandboxSkill(ctx, configID, skillID,
+ SandboxSkillUpdate{Enabled: &enabled})
+}
+
+// SetSandboxSkillEnvValues is the credentials half of UpdateSandboxSkill: it
+// stores values that apply to everybody in the workspace. For a value that
+// applies to the calling identity alone, use SetMySkillEnvVar.
+func (c *Client) SetSandboxSkillEnvValues(
+ ctx context.Context, configID, skillID string, values map[string]string,
+) (*SandboxSkill, error) {
+ return c.UpdateSandboxSkill(ctx, configID, skillID,
+ SandboxSkillUpdate{Envs: &values})
+}
+
// SandboxSkillFile is one path in an installed skill's stored archive.
type SandboxSkillFile struct {
Path string `json:"path"`
diff --git a/docs/api/README.md b/docs/api/README.md
index 47c116282..4b3685613 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -131,7 +131,7 @@ WeKnora API 按功能分为以下几类:
| 系统管理 | 系统信息、解析引擎、存储引擎 | [system.md](./system.md) |
| MCP 服务 | MCP 工具服务管理 | [mcp-service.md](./mcp-service.md) |
| 组织管理 | 组织、成员、知识库/智能体共享 | [organization.md](./organization.md) |
-| Skills | 预装智能体技能 | [skill.md](./skill.md) |
+| Skills | 预装与已安装的智能体技能、技能环境变量 | [skill.md](./skill.md) |
| 网络搜索 | 网络搜索服务商 | [web-search.md](./web-search.md) |
| 向量存储 | 向量数据库连接管理 | [vector-store.md](./vector-store.md) |
| 存储后端 | 对象/文件存储实例(多实例)管理 | [storage-backend.md](./storage-backend.md) |
diff --git a/docs/api/skill.md b/docs/api/skill.md
index b13f9c008..948c383e1 100644
--- a/docs/api/skill.md
+++ b/docs/api/skill.md
@@ -9,6 +9,12 @@
| POST | `/sandbox-configs/{id}/skills/{skillId}/reinstall` | 用已保存的安装包重试安装 |
| GET | `/sandbox-configs/{id}/skills/{skillId}/files` | 列出已安装技能的文件 |
| GET | `/sandbox-configs/{id}/skills/{skillId}/files/content` | 读取已安装技能中的单个文件 |
+| PATCH | `/sandbox-configs/{id}/skills/{skillId}` | 启用/停用技能,或设置空间级环境变量 |
+| GET | `/me/env-vars` | 列出自己的环境变量与各技能的声明 |
+| PUT | `/me/env-vars/skill` | 设置自己在某个技能上的变量值 |
+| DELETE | `/me/env-vars/skill` | 删除自己在某个技能上的变量值 |
+| PUT | `/me/env-vars/sandbox` | 设置自己在某个沙箱配置上的变量值 |
+| DELETE | `/me/env-vars/sandbox` | 删除自己在某个沙箱配置上的变量值 |
## GET `/skills` - 获取预装 Skills 列表
@@ -174,3 +180,95 @@ curl --location 'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skill
}
}
```
+
+## 技能的环境变量
+
+技能安装时会声明自己需要哪些环境变量(名称、说明、是否必填)。变量的**值**分两层,执行时按「本人的值 → 空间级值」的顺序取,取不到必填项则拒绝执行:
+
+| 层级 | 谁能写 | 作用范围 | 接口 |
+| --- | --- | --- | --- |
+| 空间级 | Admin+ | 该空间所有人 | `PATCH /sandbox-configs/{id}/skills/{skillId}` |
+| 个人级 | 任何登录成员 | 仅本人 | `PUT /me/env-vars/skill` |
+
+任何接口都**不会**回读已保存的值,只返回 `unset` / `workspace` / `user` 三种状态。清空一个值用 DELETE,而不是写入空字符串——「没填」和「不需要」是两种状态。
+
+个人级的值按**调用身份**存放,而不是按用户 ID。用 API Key 驱动的调用与网页登录是不同身份:在网页 Settings 里填的值不会作用于 API Key 发起的执行,反之亦然。集成方若通过 API Key 运行需要凭据的技能,请让管理员配置空间级值。
+
+### PATCH `/sandbox-configs/{id}/skills/{skillId}` - 更新技能
+
+`enabled` 与 `envs` 都是可选的,可只送其一,但不能都不送(400)。`envs` 只写技能已声明的名称,未声明的名称会被忽略而不是报错;值为空字符串表示清空该值并保留声明。
+
+```curl
+curl --location --request PATCH \
+'http://localhost:8080/api/v1/sandbox-configs/{id}/skills/{skillId}' \
+--header 'X-API-Key: sk-xxxxx' \
+--header 'Content-Type: application/json' \
+--data '{"enabled":true,"envs":{"TAVILY_API_KEY":"tvly-xxxxx"}}'
+```
+
+### GET `/me/env-vars` - 列出自己的环境变量
+
+按沙箱配置分组,返回本人的配置级变量,以及该配置下每个已启用技能声明的变量。`source` 表示这次执行实际会用哪一层的值。
+
+```curl
+curl --location 'http://localhost:8080/api/v1/me/env-vars' \
+--header 'Authorization: Bearer <token>'
+```
+
+**响应**:
+
+```json
+{
+ "success": true,
+ "data": [
+ {
+ "sandbox_config_id": "cfg-1",
+ "sandbox_config_name": "默认沙箱",
+ "vars": [
+ { "name": "HTTP_PROXY", "source": "user", "updated_at": "2026-08-27T10:00:00Z" }
+ ],
+ "skills": [
+ {
+ "skill_id": "sk-1",
+ "skill_name": "web-search",
+ "vars": [
+ { "name": "TAVILY_API_KEY", "description": "Tavily 搜索密钥", "required": true, "source": "workspace" },
+ { "name": "REGION", "source": "unset" }
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
+
+### PUT / DELETE `/me/env-vars/skill` - 设置或删除自己在技能上的值
+
+`name` 必须是该技能声明过的名称,否则 400。删除后该技能重新回落到空间级值(若有)。
+
+```curl
+curl --location --request PUT 'http://localhost:8080/api/v1/me/env-vars/skill' \
+--header 'Authorization: Bearer <token>' \
+--header 'Content-Type: application/json' \
+--data '{"skill_id":"sk-1","name":"TAVILY_API_KEY","value":"tvly-xxxxx"}'
+```
+
+```curl
+curl --location --request DELETE 'http://localhost:8080/api/v1/me/env-vars/skill' \
+--header 'Authorization: Bearer <token>' \
+--header 'Content-Type: application/json' \
+--data '{"skill_id":"sk-1","name":"TAVILY_API_KEY"}'
+```
+
+删除一个本就没设过的值返回 404。
+
+### PUT / DELETE `/me/env-vars/sandbox` - 设置或删除自己的配置级变量
+
+配置级变量不依附于任何技能,名称自定,会注入本人在该沙箱配置上的每一次技能脚本与 shell 命令。`WEKNORA_` 前缀与 `PATH` 等保留名会被拒绝。
+
+```curl
+curl --location --request PUT 'http://localhost:8080/api/v1/me/env-vars/sandbox' \
+--header 'Authorization: Bearer <token>' \
+--header 'Content-Type: application/json' \
+--data '{"sandbox_config_id":"cfg-1","name":"HTTP_PROXY","value":"http://127.0.0.1:7890"}'
+```
diff --git a/docs/docs.go b/docs/docs.go
index 5214272a5..378dda235 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -8960,6 +8960,219 @@ const docTemplate = `{
}
}
},
+ "/me/env-vars": {
+ "get": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "List every sandbox config of this workspace with the caller's own config-wide variables and the credentials its skills declared, each reporting whether it is unset, filled in workspace-wide, or filled in by the caller. Values are never returned.",
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "List my environment variables",
+ "responses": {
+ "200": {
+ "description": "One group per sandbox config",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ }
+ }
+ },
+ "/me/env-vars/sandbox": {
+ "put": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Store the caller's own value for one variable on a sandbox config. It is injected into every skill script and shell command this caller's turns run on that config.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Set one of my sandbox environment variables",
+ "parameters": [
+ {
+ "description": "Sandbox config, variable name and value",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Stored",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "400": {
+ "description": "Invalid request",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ },
+ "delete": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Remove the caller's own value for one variable on a sandbox config.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Delete one of my sandbox environment variables",
+ "parameters": [
+ {
+ "description": "Sandbox config and variable name",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Deleted",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "404": {
+ "description": "Not set",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ }
+ },
+ "/me/env-vars/skill": {
+ "put": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Store the caller's own value for one variable the skill declared. It overrides the workspace-wide value for this caller only, and is injected only into executions that name this skill.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Set one of my skill credentials",
+ "parameters": [
+ {
+ "description": "Skill, variable name and value",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Stored",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "400": {
+ "description": "Invalid request",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ },
+ "delete": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Remove the caller's own value. The workspace-wide value, if there is one, applies again afterwards.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Delete one of my skill credentials",
+ "parameters": [
+ {
+ "description": "Skill and variable name",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Deleted",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "404": {
+ "description": "Not set",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ }
+ },
"/me/invitations": {
"get": {
"security": [
@@ -11841,7 +12054,7 @@ const docTemplate = `{
"ApiKeyAuth": []
}
],
- "description": "Show or hide an installed skill. The files stay in the image either way; removal is a separate flow.",
+ "description": "Show or hide an installed skill and set the workspace-wide values of the environment variables it declared. Either field may be sent, or both. The files stay in the image either way; removal is a separate flow.",
"consumes": [
"application/json"
],
@@ -24389,6 +24602,24 @@ const docTemplate = `{
}
}
},
+ "internal_handler.meEnvVarRequest": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "sandbox_config_id": {
+ "type": "string"
+ },
+ "skill_id": {
+ "type": "string"
+ },
+ "value": {
+ "description": "Value is unused by the delete endpoints. Clearing a value is a delete\nrather than a write of \"\", so a member always has one unambiguous way to\nrevoke.",
+ "type": "string"
+ }
+ }
+ },
"internal_handler.platformAPIKeyCreateRequest": {
"type": "object",
"properties": {
@@ -24462,8 +24693,15 @@ const docTemplate = `{
"type": "object",
"properties": {
"enabled": {
- "description": "Enabled is a pointer because its absence is a bad request rather than a\nrequest to disable the skill.",
+ "description": "Enabled is a pointer because its absence is not a request to disable the\nskill; a body may carry envs instead.",
"type": "boolean"
+ },
+ "envs": {
+ "description": "Envs is a pointer to a map because \"sent an empty object\" and \"did not\nmention envs\" are different requests: the first clears what it names,\nthe second must leave every stored value alone.",
+ "type": "object",
+ "additionalProperties": {
+ "type": "string"
+ }
}
}
},
diff --git a/docs/swagger.json b/docs/swagger.json
index 2f6d0c8e5..afe34a478 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -8953,6 +8953,219 @@
}
}
},
+ "/me/env-vars": {
+ "get": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "List every sandbox config of this workspace with the caller's own config-wide variables and the credentials its skills declared, each reporting whether it is unset, filled in workspace-wide, or filled in by the caller. Values are never returned.",
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "List my environment variables",
+ "responses": {
+ "200": {
+ "description": "One group per sandbox config",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ }
+ }
+ }
+ },
+ "/me/env-vars/sandbox": {
+ "put": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Store the caller's own value for one variable on a sandbox config. It is injected into every skill script and shell command this caller's turns run on that config.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Set one of my sandbox environment variables",
+ "parameters": [
+ {
+ "description": "Sandbox config, variable name and value",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Stored",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "400": {
+ "description": "Invalid request",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ },
+ "delete": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Remove the caller's own value for one variable on a sandbox config.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Delete one of my sandbox environment variables",
+ "parameters": [
+ {
+ "description": "Sandbox config and variable name",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Deleted",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "404": {
+ "description": "Not set",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ }
+ },
+ "/me/env-vars/skill": {
+ "put": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Store the caller's own value for one variable the skill declared. It overrides the workspace-wide value for this caller only, and is injected only into executions that name this skill.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Set one of my skill credentials",
+ "parameters": [
+ {
+ "description": "Skill, variable name and value",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Stored",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "400": {
+ "description": "Invalid request",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ },
+ "delete": {
+ "security": [
+ {
+ "Bearer": []
+ }
+ ],
+ "description": "Remove the caller's own value. The workspace-wide value, if there is one, applies again afterwards.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "Me"
+ ],
+ "summary": "Delete one of my skill credentials",
+ "parameters": [
+ {
+ "description": "Skill and variable name",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/internal_handler.meEnvVarRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Deleted",
+ "schema": {
+ "type": "object",
+ "additionalProperties": true
+ }
+ },
+ "404": {
+ "description": "Not set",
+ "schema": {
+ "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+ }
+ }
+ }
+ }
+ },
"/me/invitations": {
"get": {
"security": [
@@ -11834,7 +12047,7 @@
"ApiKeyAuth": []
}
],
- "description": "Show or hide an installed skill. The files stay in the image either way; removal is a separate flow.",
+ "description": "Show or hide an installed skill and set the workspace-wide values of the environment variables it declared. Either field may be sent, or both. The files stay in the image either way; removal is a separate flow.",
"consumes": [
"application/json"
],
@@ -24382,6 +24595,24 @@
}
}
},
+ "internal_handler.meEnvVarRequest": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "sandbox_config_id": {
+ "type": "string"
+ },
+ "skill_id": {
+ "type": "string"
+ },
+ "value": {
+ "description": "Value is unused by the delete endpoints. Clearing a value is a delete\nrather than a write of \"\", so a member always has one unambiguous way to\nrevoke.",
+ "type": "string"
+ }
+ }
+ },
"internal_handler.platformAPIKeyCreateRequest": {
"type": "object",
"properties": {
@@ -24455,8 +24686,15 @@
"type": "object",
"properties": {
"enabled": {
- "description": "Enabled is a pointer because its absence is a bad request rather than a\nrequest to disable the skill.",
+ "description": "Enabled is a pointer because its absence is not a request to disable the\nskill; a body may carry envs instead.",
"type": "boolean"
+ },
+ "envs": {
+ "description": "Envs is a pointer to a map because \"sent an empty object\" and \"did not\nmention envs\" are different requests: the first clears what it names,\nthe second must leave every stored value alone.",
+ "type": "object",
+ "additionalProperties": {
+ "type": "string"
+ }
}
}
},
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index ff0bf02b0..c76997ec2 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -5969,6 +5969,21 @@ definitions:
tenant_name:
type: string
type: object
+ internal_handler.meEnvVarRequest:
+ properties:
+ name:
+ type: string
+ sandbox_config_id:
+ type: string
+ skill_id:
+ type: string
+ value:
+ description: |-
+ Value is unused by the delete endpoints. Clearing a value is a delete
+ rather than a write of "", so a member always has one unambiguous way to
+ revoke.
+ type: string
+ type: object
internal_handler.platformAPIKeyCreateRequest:
properties:
capabilities:
@@ -6019,9 +6034,17 @@ definitions:
properties:
enabled:
description: |-
- Enabled is a pointer because its absence is a bad request rather than a
- request to disable the skill.
+ Enabled is a pointer because its absence is not a request to disable the
+ skill; a body may carry envs instead.
type: boolean
+ envs:
+ additionalProperties:
+ type: string
+ description: |-
+ Envs is a pointer to a map because "sent an empty object" and "did not
+ mention envs" are different requests: the first clears what it names,
+ the second must leave every stored value alone.
+ type: object
type: object
internal_handler.skillSourceRequest:
properties:
@@ -11996,6 +12019,149 @@ paths:
summary: MCP OAuth 回调
tags:
- MCP服务
+ /me/env-vars:
+ get:
+ description: List every sandbox config of this workspace with the caller's own
+ config-wide variables and the credentials its skills declared, each reporting
+ whether it is unset, filled in workspace-wide, or filled in by the caller.
+ Values are never returned.
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: One group per sandbox config
+ schema:
+ additionalProperties: true
+ type: object
+ "401":
+ description: Unauthorized
+ schema:
+ additionalProperties: true
+ type: object
+ security:
+ - Bearer: []
+ summary: List my environment variables
+ tags:
+ - Me
+ /me/env-vars/sandbox:
+ delete:
+ consumes:
+ - application/json
+ description: Remove the caller's own value for one variable on a sandbox config.
+ parameters:
+ - description: Sandbox config and variable name
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/internal_handler.meEnvVarRequest'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: Deleted
+ schema:
+ additionalProperties: true
+ type: object
+ "404":
+ description: Not set
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ security:
+ - Bearer: []
+ summary: Delete one of my sandbox environment variables
+ tags:
+ - Me
+ put:
+ consumes:
+ - application/json
+ description: Store the caller's own value for one variable on a sandbox config.
+ It is injected into every skill script and shell command this caller's turns
+ run on that config.
+ parameters:
+ - description: Sandbox config, variable name and value
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/internal_handler.meEnvVarRequest'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: Stored
+ schema:
+ additionalProperties: true
+ type: object
+ "400":
+ description: Invalid request
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ security:
+ - Bearer: []
+ summary: Set one of my sandbox environment variables
+ tags:
+ - Me
+ /me/env-vars/skill:
+ delete:
+ consumes:
+ - application/json
+ description: Remove the caller's own value. The workspace-wide value, if there
+ is one, applies again afterwards.
+ parameters:
+ - description: Skill and variable name
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/internal_handler.meEnvVarRequest'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: Deleted
+ schema:
+ additionalProperties: true
+ type: object
+ "404":
+ description: Not set
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ security:
+ - Bearer: []
+ summary: Delete one of my skill credentials
+ tags:
+ - Me
+ put:
+ consumes:
+ - application/json
+ description: Store the caller's own value for one variable the skill declared.
+ It overrides the workspace-wide value for this caller only, and is injected
+ only into executions that name this skill.
+ parameters:
+ - description: Skill, variable name and value
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/internal_handler.meEnvVarRequest'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: Stored
+ schema:
+ additionalProperties: true
+ type: object
+ "400":
+ description: Invalid request
+ schema:
+ $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+ security:
+ - Bearer: []
+ summary: Set one of my skill credentials
+ tags:
+ - Me
/me/invitations:
get:
description: 返回当前登录用户的待接受邀请(默认仅 pending),用于头像入口和 /invitations 收件箱页。
@@ -13830,8 +13996,9 @@ paths:
patch:
consumes:
- application/json
- description: Show or hide an installed skill. The files stay in the image either
- way; removal is a separate flow.
+ description: Show or hide an installed skill and set the workspace-wide values
+ of the environment variables it declared. Either field may be sent, or both.
+ The files stay in the image either way; removal is a separate flow.
parameters:
- description: Sandbox config ID
in: path