用途
用于读取或修改 Windmill 工作区设置，以及 wmill sync 持续维护的 settings.yaml 文件。管理员在工作区设置页设置的每一项内容构成同一份文档：顶层键的映射，布局与 settings.yaml 一致。只有工作区管理员可以读取或修改。
应用文档的规则
- 部分文档只改动它声明的键，省略的键保持原样。
- 每个键整体替换。因此需要先读取当前值，编辑后再发回；若嵌套对象只给一个字段，则存储的对象会被这个仅含一个字段的对象替换。
- 键设为 null 会清除该设置；以这种方式清除的开关读作 false。
- 每项设置都经由设置页使用的同一路径写入，具有相同的校验和审计日志。写入不是单个事务：某项失败时应用会停止，错误会说明已经写入了什么。
- dry run 只报告变更（逐键 before / after），不写入任何内容。
name永不应用：重命名工作区需在设置页进行。color只在设为某值时应用，因此 null 不会清除它。- 服务器不认识的键会被忽略并在 warnings 中列出：务必检查，否则拼写错误会被读成“无变更”。
- 当前版本不提供的设置（仅企业版）会被拒绝，dry run 也会拒绝。
密钥（Secrets）
slack_oauth_client_secret 是唯一的密钥。读取时，已设置的密钥显示为 __SENSITIVE_AND_UNCHANGED__；把该占位符发回会保留存储值。以 $encrypted: 开头的值会用工作区密钥解密，用其他工作区密钥加密的值会保持不变并给出警告；其他任何值按明文处理。不要写入未获提供的密钥：保留占位符。
键（Keys）
auto_invite：{ enabled, mode: invite | add, operator, instance_groups?, instance_groups_roles? }。仅当声明instance_groups时才管理实例组；清除某个组会移除它添加的成员。error_handler/success_handler：{ path, extra_args?, muted_on_cancel?, muted_on_user_path? }，path 为script/<path>或flow/<path>。error_handler_fallback_to_instance_alerts：未设置错误处理器时，将失败上报到实例关键告警渠道。webhook：每次工作区项目发生变更时向其 POST JSON 事件的 URL。ai_config：提供商、默认与补全模型、自定义提示词、copilot_disabled。large_file_storage：工作区对象存储：{ type, s3_resource_path | azure_blob_resource_path | gcs_resource_path, public_resource?, secondary_storage?, advanced_permissions? }。git_sync：{ repositories: [...] }，每项含git_repo_resource_path、script_path与设置（包含/排除路径与类型）。服务器拥有的字段（webhook 密钥、同步状态、凭据）永不读写。datatable：{ datatables: { <name>: { database: { resource_type, resource_path? } } } }。角色权限为datatable_permissions。datatable_permissions：{ <data table>: { default_role, roles: { <role>: [tenants] } } }，定义谁可以以哪种角色连接各数据表。租户为u/<user>、g/<group>、f/<folder>或*；admin 始终是一个角色，default_role: null表示无默认。值中省略的数据表不再处于 roles 之下。只有位于 Windmill 托管的集群上的数据表才能如此。protection_rules：{ <rule name>: { rules: [...], bypass_groups: [...], bypass_users: [...] } }，rules 可选DisableDirectDeployment、DisableWorkspaceForking、RestrictDeployToDeployers、RestrictAnonymousAppDeployment、RestrictPublicRunSharing、RestrictGuestAppDeployment。值中省略的规则会被删除。dev 工作区锁定不在列表中，不能在此设置。ducklake：{ ducklakes: { <name>: { catalog, storage, ... } } }。dbt_warehouses：dbt 仓库连接。default_app：作为工作区主页展示的应用路径。default_scripts：{ order?, hidden?, default_script_content? }，用于脚本语言选择器。deploy_ui：{ include_path?, include_type? }：部署到工作区 UI 提供的内容。operator_settings：操作员可见与可做的内容：页面可见性标志（runs、schedules、resources、variables、assets、audit_logs、groups、folders、workers、triggers）与写权限（manage_schedules、manage_triggers、builder_flows、builder_apps）。值中省略的写权限保持存储值。mute_critical_alerts：静音工作区的关键告警。slack_team_id、slack_name：只读；在设置页连接 Slack 时设置。slack_command_script/teams_command_script：处理 Slack / Teams 命令的脚本或流程。slack_oauth_client_id/slack_oauth_client_secret：工作区自己的 Slack OAuth 应用。清除任一项会同时移除两者。public_app_execution_limit_per_minute：公共应用的速率限制，null 表示不限制。guest_access_enabled、guest_jwt_public_key、guest_jwt_jwks_url：公共应用的访客访问及签名访客 JWT 的密钥。add_admins_and_developers_to_forks：将工作区的管理员与开发者加入每个 fork。color：工作区颜色，#rrggbb。
从命令行使用
wmill workspace get-settings打印该文档（--encrypted输出用工作区密钥加密的密钥，--json输出 JSON）。wmill workspace apply-settings <file>从 YAML 或 JSON 文件应用部分文档：显示变更并在写入前询问（--dry-run仅显示，-y跳过询问，--replace清除文件省略的内容）。
在同步仓库中使用
在 wmill.yaml 中设置 includeSettings: true 时：
wmill sync pull将文档写入 settings.yaml，密钥用工作区密钥加密（仅plainSecrets时为明文）。wmill sync push应用它。与部分应用不同，push 会把文件视为完整文档：文件中省略的设置会被清除，但operator_settings、color、自动邀请的实例组，以及键ducklake、dbt_warehouses、deploy_ui、teams_command_script、public_app_execution_limit_per_minute、guest_access_enabled、guest_jwt_public_key、guest_jwt_jwks_url、error_handler_fallback_to_instance_alerts和add_admins_and_developers_to_forks例外，它们仅在文件声明时管理。datatable_permissions仅在includeDatatablePermissions: true（或--include-datatable-permissions）时推送。- push 忽略
protection_rules：由 protection-rules.yaml 和wmill protection-rules push同步它们。