MemeMeow/openspec/specs/backend-settings/spec.md

backend-settings Specification

Purpose

为后端运行参数提供经过校验、脱敏且可操作的配置工作面，使操作者能够区分部署配置、后端状态和安全可调整的 Agent 并发数量，而不把前端偏好或敏感凭据暴露给浏览器。

Requirements

Requirement: 后端设置必须使用统一的有效配置模型

系统 MUST 使用统一的类型化设置模型读取进程环境变量、.env 和默认值，并保持进程环境变量优先于 .env 的现有优先级。无效的并发配置 MUST 在启动或保存时返回稳定校验错误，不得静默使用不可预测的值。

Scenario: 读取并发默认值

• WHEN 环境变量和 .env 都未提供 OpenCode 并发数量
• THEN 有效配置使用 1，并在后端状态中标记为默认值

Scenario: 环境变量覆盖 dotenv

• WHEN 进程环境变量和 .env 同时提供并发数量
• THEN 系统使用进程环境变量的值，并向设置页显示该值由环境覆盖且不能通过页面持久化覆盖

Scenario: 拒绝越界并发数量

• WHEN 并发数量不是正整数或超过系统允许的安全上限
• THEN 启动或设置更新失败，返回字段级校验错误，当前有效配置保持不变

Requirement: 系统必须提供独立的后端设置工作面

系统 MUST 提供独立于搜索、上传和前端偏好的“后端设置”页面及对应的后端设置查询接口。页面 MUST 将配置分为只读后端状态、安全可调整参数和仅部署环境可修改的高风险参数。

Scenario: 查看后端设置

• WHEN 操作者打开后端设置页
• THEN 页面展示当前有效模型、provider 状态、runtime 状态、任务并发数量、缓存状态和重启提示，并将后端设置与前端偏好分开

Scenario: 敏感配置脱敏

• WHEN 后端设置接口返回配置
• THEN 响应只返回密钥是否配置、受控的非敏感状态和字段元数据，不返回 API key、完整 secret、内部 prompt 或原始任务日志

Scenario: 高风险参数只读

• WHEN 页面展示 OpenCode 可执行路径、runtime/data 根目录、任意 provider URL、接口白名单或密钥字段
• THEN 这些字段显示为部署环境管理的只读项，页面不提供浏览器写入控件

Requirement: Agent 并发数量必须可受保护地持久化

系统 MUST 允许授权操作者只修改 OpenCode Agent 并发数量；保存值 MUST 经过范围校验并以原子方式持久化到 .env 的非敏感字段。修改 MUST 明确标记为重启后生效，当前运行中的任务和服务不得被半途切换到新配置。

Scenario: 保存有效并发数量

• WHEN 授权操作者提交安全范围内的并发数量
• THEN 后端更新 .env 中对应的非敏感字段，返回新的待生效配置版本和 restart_required=true，当前有效配置保持不变

Scenario: 未授权更新被拒绝

• WHEN 请求缺少有效设置管理凭据或设置管理未启用
• THEN 更新接口返回 403，不修改 .env，页面保持只读状态

Scenario: 并发更新与环境覆盖冲突

• WHEN 当前并发数量由进程环境变量覆盖而请求尝试更新 .env
• THEN 系统拒绝该更新并说明环境变量优先级，.env 和当前有效配置均不改变

Scenario: 重启后加载新值

• WHEN 服务使用已保存的 .env 重启
• THEN 新的并发数量成为有效 Agent lane 上限，任务页显示该配置版本，且仍遵守并行提取 change 的去重和背压语义