devos/Docs/DevOS-Platform-v2/18_CONFIGURATION_SECRET_ENVIRONMENT_RUNTIME.md

18_CONFIGURATION_SECRET_ENVIRONMENT_RUNTIME.md

Version: 1.0 Status: Implementation Specification Target: Zcode Depends on:

• 03_RESOURCE_ACTION_MODEL.md
• 06_MCP_SKILL_AGENT_RUNTIME.md
• 09_TASK_JOB_QUEUE_RUNTIME.md
• 12_MIGRATION_VERSIONING_COMPATIBILITY.md
• 14_DATA_QUERY_SEARCH_INDEX_RUNTIME.md
• 15_FILE_ARTIFACT_STORAGE_RUNTIME.md
• 16_EVENT_STREAMING_NOTIFICATION_REALTIME_RUNTIME.md
• 17_OBSERVABILITY_AUDIT_LOGGING_RUNTIME.md

---

1. Document Purpose

本文件定义 DevOS 统一的：

• Configuration Runtime
• Environment Runtime
• Secret Runtime
• Provider Runtime
• Credential Runtime
• Variable Runtime
• Configuration Schema
• Configuration Version
• Configuration Override
• Configuration Validation
• Configuration Resolution
• Secret Rotation
• Secret Reference
• Environment Isolation

目标：

DevOS 中所有 Core、Plugin、MCP、Agent、Skill、Workflow、Task、Worker、Action、Storage、Search、Provider 都必须通过统一 Configuration Runtime 获取配置。

禁止各模块自己：

process.env
.env
config.json
yaml
Redis
数据库
Secret Manager

随意读取配置。

---

2. Core Principle

DevOS 必须明确区分：

Configuration
Secret
Environment
Provider
Credential
Runtime Variable

它们不是同一个东西。

---

3. Configuration

Configuration：

控制系统行为的普通配置。

例如：

task.defaultTimeout
worker.concurrency
search.defaultProvider
seo.scan.timeout
ui.theme

---

4. Secret

Secret：

不应该以明文暴露给普通用户、日志或 API 的敏感值。

例如：

API Key
Access Token
Password
Private Key
Webhook Secret
Database Password
OAuth Client Secret
Encryption Key

---

5. Environment

Environment：

一组隔离的运行环境和配置上下文。

例如：

development
staging
production

也可以是：

dev
test
preview
prod

---

6. Provider

Provider：

某种外部能力的实现来源。

例如：

LLM Provider
Storage Provider
Search Provider
Email Provider
DNS Provider
Git Provider
Browser Provider

例如：

OpenAI
Anthropic
AWS S3
Cloudflare
GitHub
SMTP

---

7. Credential

Credential：

Provider 所需要的认证信息。

例如：

GitHub Credential
AWS Credential
OpenAI Credential
Cloudflare Credential
SMTP Credential

---

8. Runtime Variable

Runtime Variable：

执行过程中临时产生或注入的变量。

例如：

TASK_ID
EXECUTION_ID
PROJECT_ID
ARTIFACT_ID

Runtime Variable 不应该持久化成普通 Configuration。

---

9. Architecture

                    Configuration Runtime
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
 Configuration          Environment          Secret
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
                      Resolution
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
     Provider            Credential        Runtime Variable
        │                   │                   │
        └───────────────────┼───────────────────┘
                            ↓
                      Runtime Context
                            ↓
        ┌───────────────────┼───────────────────┐
        ↓                   ↓                   ↓
      Action              Plugin              Agent
        ↓                   ↓                   ↓
      Task                Worker             Workflow

---

10. Configuration Hierarchy

DevOS 配置支持多层覆盖：

Global
  ↓
Organization
  ↓
Project
  ↓
Environment
  ↓
Plugin
  ↓
Resource
  ↓
Runtime

例如：

global.timeout = 30s

project.timeout = 60s

production.timeout = 90s

最终：

production
 ↓
90s

---

11. Configuration Precedence

必须定义稳定优先级：

Runtime Override
    >
Resource Override
    >
Plugin Environment
    >
Environment
    >
Project
    >
Organization
    >
Global
    >
Default

---

12. Configuration Definition

export interface ConfigDefinition<T = unknown> {
  key: string

  namespace: string

  description?: string

  schema: unknown

  defaultValue?: T

  required?: boolean

  sensitive?: boolean

  mutable?: boolean

  restartRequired?: boolean

  scope:
    | 'global'
    | 'organization'
    | 'project'
    | 'environment'
    | 'plugin'
    | 'resource'
}

---

13. Configuration Value

export interface ConfigValue {
  key: string

  value: unknown

  scope: ConfigScope

  scopeId?: string

  version: number

  updatedAt: string

  updatedBy?: string

  metadata?: Record<string, unknown>
}

---

14. Configuration Scope

export type ConfigScope =
  | 'global'
  | 'organization'
  | 'project'
  | 'environment'
  | 'plugin'
  | 'resource'

---

15. Configuration Runtime

export interface ConfigRuntime {
  get<T>(
    key: string,
    context: ConfigContext
  ): Promise<T | undefined>

  require<T>(
    key: string,
    context: ConfigContext
  ): Promise<T>

  set(
    key: string,
    value: unknown,
    context: ConfigContext
  ): Promise<void>

  delete(
    key: string,
    context: ConfigContext
  ): Promise<void>

  resolve(
    context: ConfigContext
  ): Promise<ResolvedConfig>

  validate(
    key: string,
    value: unknown
  ): Promise<ValidationResult>
}

---

16. Config Context

export interface ConfigContext {
  organizationId?: string

  projectId?: string

  environmentId?: string

  pluginId?: string

  resourceType?: string

  resourceId?: string

  actorId?: string

  actorType?: 'user' | 'agent' | 'service' | 'system'

  runtimeVariables?: Record<string, unknown>
}

---

17. Configuration Resolution

调用：

config.get(
  'seo.scan.timeout',
  context
)

Runtime：

Default
 ↓
Global
 ↓
Organization
 ↓
Project
 ↓
Environment
 ↓
Plugin
 ↓
Resource
 ↓
Runtime Override
 ↓
Final Value

---

18. Resolved Configuration

export interface ResolvedConfig {
  values: Record<string, unknown>

  sources: Record<
    string,
    ConfigSource
  >

  version: number

  resolvedAt: string
}

---

19. Config Source

export interface ConfigSource {
  scope: ConfigScope

  scopeId?: string

  version: number

  updatedAt?: string
}

这样 UI 可以告诉用户：

seo.scan.timeout = 90s

Source:
Production Environment

---

20. Configuration Schema

配置必须拥有 Schema。

推荐：

Zod

例如：

const schema = z.object({
  timeout: z.number().min(1).max(3600),
  concurrency: z.number().min(1).max(100),
})

---

21. Configuration Validation

设置配置时：

Input
 ↓
Schema Validation
 ↓
Policy Validation
 ↓
Permission
 ↓
Save
 ↓
Audit
 ↓
Event

非法配置不得进入数据库。

---

22. Configuration Type

至少支持：

string
number
boolean
enum
array
object
json
duration
url
hostname
port
cron
resource reference
provider reference
secret reference

---

23. Configuration UI Metadata

export interface ConfigUI {
  label: string

  description?: string

  component:
    | 'text'
    | 'password'
    | 'number'
    | 'switch'
    | 'select'
    | 'multi-select'
    | 'textarea'
    | 'json'
    | 'cron'
    | 'provider'
    | 'credential'

  hidden?: boolean

  readonly?: boolean

  advanced?: boolean
}

---

24. Secret Runtime

定义：

export interface SecretRuntime {
  create(
    input: CreateSecretInput
  ): Promise<SecretReference>

  get(
    ref: SecretReference,
    context: SecretContext
  ): Promise<SecretValue>

  rotate(
    ref: SecretReference,
    context: SecretContext
  ): Promise<void>

  revoke(
    ref: SecretReference,
    context: SecretContext
  ): Promise<void>

  delete(
    ref: SecretReference,
    context: SecretContext
  ): Promise<void>
}

---

25. Secret Reference

业务系统绝对不要保存：

apiKey = "sk-xxxxx"

应该保存：

{
  "secretRef": "secret://openai/default"
}

---

26. Secret Reference Interface

export interface SecretReference {
  id: string

  namespace: string

  name: string

  version?: number

  provider: string
}

例如：

secret://openai/default
secret://github/production
secret://cloudflare/main

---

27. Secret Value

export interface SecretValue {
  value: string

  version: number

  expiresAt?: string

  metadata?: Record<string, unknown>
}

Secret Value：

只允许在需要执行时短暂进入内存。

---

28. Secret Storage

推荐抽象：

export interface SecretProvider {
  put(
    ref: SecretReference,
    value: string
  ): Promise<void>

  get(
    ref: SecretReference
  ): Promise<SecretValue>

  delete(
    ref: SecretReference
  ): Promise<void>

  rotate?(
    ref: SecretReference,
    value: string
  ): Promise<void>
}

支持：

Local encrypted storage
Vault
AWS Secrets Manager
GCP Secret Manager
Azure Key Vault
Kubernetes Secrets

---

29. Default Secret Provider

DevOS 默认可以提供：

PostgreSQL encrypted secret storage

但必须：

encryption at rest

并且：

secret value
≠
normal database field

---

30. Encryption

Secret 必须加密。

推荐：

Envelope Encryption

结构：

Master Key
   ↓
Data Encryption Key
   ↓
Secret

Master Key 不存数据库明文。

---

31. Secret Access

读取 Secret 必须：

Authentication
 ↓
Permission
 ↓
Scope
 ↓
Policy
 ↓
Audit
 ↓
Secret Provider

---

32. Secret Access Audit

读取 Secret 必须产生 Audit：

actor:
user_123

operation:
secret.read

secret:
openai/default

result:
success

但：

Audit 中绝对不能记录 Secret Value。

---

33. Secret Redaction

Secret 即使被传入：

Log
Error
Trace
Event
Audit

也必须自动：

[REDACTED]

与 17 的 Redaction Runtime 集成。

---

34. Secret Rotation

Secret 生命周期：

active
 ↓
rotation_pending
 ↓
rotating
 ↓
active_new_version
 ↓
revoked_old_version

---

35. Secret Version

export interface SecretVersion {
  version: number

  createdAt: string

  expiresAt?: string

  status:
    | 'active'
    | 'expired'
    | 'revoked'

  createdBy?: string
}

---

36. Zero Downtime Rotation

Rotation 不应该：

delete old
 ↓
create new

而应该：

new secret
 ↓
test
 ↓
activate
 ↓
switch consumers
 ↓
revoke old

---

37. Credential Runtime

Credential 是 Secret 的业务封装。

例如：

export interface Credential {
  id: string

  name: string

  providerId: string

  type: string

  secretRefs: SecretReference[]

  organizationId?: string

  projectId?: string

  environmentId?: string

  status:
    | 'active'
    | 'invalid'
    | 'expired'
    | 'revoked'

  metadata?: Record<string, unknown>
}

---

38. Provider Runtime

export interface ProviderDefinition {
  id: string

  type: string

  name: string

  capabilities: string[]

  configSchema: unknown

  credentialSchema?: unknown

  healthCheck?: string
}

---

39. Provider Example

例如 LLM：

provider.openai
provider.anthropic
provider.google

统一：

interface LLMProvider {
  generate(input: LLMInput): Promise<LLMOutput>
}

---

40. Provider Resolution

Agent 不应该写：

new OpenAI()

而应该：

provider.resolve(
  'llm',
  context
)

Runtime 决定：

Project Provider
 ↓
Environment Provider
 ↓
Default Provider

---

41. Provider Failover

可以配置：

Primary:
OpenAI

Fallback:
Anthropic

Fallback:
Google

Runtime：

OpenAI
 ↓ failure
Anthropic
 ↓ failure
Google

必须记录：

provider selected
provider failed
provider fallback

---

42. Provider Policy

Provider 可以受到：

organization policy
project policy
environment policy
agent policy

限制。

例如：

Production Agent
只能使用：
OpenAI
Anthropic

禁止：
Unknown Provider

---

43. Provider Health

Provider 必须注册：

health check
latency
error rate
rate limit
quota

与：

17_OBSERVABILITY_AUDIT_LOGGING_RUNTIME.md

集成。

---

44. Environment Resource

建议：

core.environment

定义：

export interface Environment {
  id: string

  name: string

  key: string

  type:
    | 'development'
    | 'test'
    | 'staging'
    | 'production'
    | 'preview'
    | 'custom'

  organizationId: string

  projectId?: string

  status:
    | 'active'
    | 'disabled'
    | 'archived'

  metadata?: Record<string, unknown>
}

---

45. Environment Isolation

环境必须隔离：

Development
    ≠
Production

尤其：

Secrets
Database
Storage
Queue
Providers
Credentials

---

46. Environment Context

所有执行都应该知道：

environmentId

例如：

interface ActionContext {
  environmentId?: string
}

这样：

Action
 ↓
Environment
 ↓
Configuration
 ↓
Credential
 ↓
Provider

全部一致。

---

47. Production Protection

Production 必须拥有额外 Policy。

例如：

production:
  requireApproval:
    - server.delete
    - database.delete
    - deployment.rollback

  forbidden:
    - test.provider

---

48. Environment Variables

DevOS 可以读取系统环境变量：

process.env

但是：

只能由 Configuration Runtime 在启动阶段读取。

业务代码禁止直接：

process.env.OPENAI_API_KEY

---

49. Bootstrap Configuration

启动阶段：

OS Environment
 ↓
Bootstrap Config
 ↓
Configuration Runtime
 ↓
Application Runtime

例如：

DATABASE_URL
REDIS_URL
DEVOS_MASTER_KEY

属于：

bootstrap secrets/config

---

50. Bootstrap vs Runtime Config

Bootstrap：

系统启动所必需。

Runtime：

系统运行期间可动态修改。

例如：

DATABASE_URL

通常 Bootstrap。

而：

worker.concurrency

可以 Runtime Config。

---

51. Dynamic Configuration

支持动态修改：

worker.concurrency
logging.level
alert.threshold
search.provider
agent.maxIterations

修改后：

validate
 ↓
persist
 ↓
publish config.changed
 ↓
runtime refresh

---

52. Configuration Event

与 16 集成：

config.created
config.updated
config.deleted
config.reset
config.reloaded

secret.created
secret.rotated
secret.revoked

credential.created
credential.updated
credential.revoked

provider.created
provider.updated
provider.health_changed

environment.created
environment.updated
environment.archived

---

53. Configuration Version

每次修改：

version++

例如：

v1
 ↓
v2
 ↓
v3

不能覆盖历史记录而无法追踪。

---

54. Configuration History

必须可以查询：

谁改的？
什么时候改的？
改了什么？
为什么？
从什么值？
改成什么？

例如：

worker.concurrency

v12:
4

v13:
8

Actor:
admin

Reason:
Increase production throughput

---

55. Configuration Audit

所有重要配置变更必须 Audit：

config.update
config.delete
config.reset
secret.create
secret.rotate
secret.revoke
credential.update
provider.update
environment.update

---

56. Configuration Rollback

支持：

current v13
 ↓
rollback
 ↓
v12

但是实际上应该创建：

v14

内容等于：

v12

而不是修改历史。

---

57. Configuration Lock

某些配置可以锁定：

export interface ConfigLock {
  key: string

  scope: ConfigScope

  scopeId?: string

  reason?: string

  lockedBy?: string
}

例如：

production.database.url

禁止普通用户修改。

---

58. Configuration Policy

配置修改必须经过：

Permission
 ↓
Policy
 ↓
Validation
 ↓
Approval if required
 ↓
Write

---

59. Sensitive Configuration

ConfigDefinition：

sensitive: true

例如：

smtp.password
provider.apiKey
database.password

UI 只能显示：

••••••••

---

60. Secret vs Sensitive Config

必须区分：

sensitive config

与：

secret

例如：

logging.redaction.enabled = true

可以是：

sensitive = false

而：

openai.apiKey

必须：

secret

---

61. No Secret in Config DB

禁止：

{
  "openai.apiKey": "sk-xxx"
}

应该：

{
  "openai.apiKey": {
    "secretRef": "secret://openai/default"
  }
}

---

62. Provider Credential Binding

例如：

Provider:
OpenAI

Credential:
openai-production

Secret:
secret://openai/production

关系：

Provider
 ↓
Credential
 ↓
Secret

---

63. Credential Selection

Runtime 根据：

organization
project
environment
provider
policy

选择 Credential。

例如：

production
 ↓
OpenAI Provider
 ↓
openai-production credential

而：

development
 ↓
OpenAI Provider
 ↓
openai-development credential

---

64. Configuration Resolver

export interface ConfigResolver {
  resolve(
    key: string,
    context: ConfigContext
  ): Promise<ResolvedValue>
}

解析过程：

Schema
 ↓
Defaults
 ↓
Scope values
 ↓
Overrides
 ↓
References
 ↓
Secrets
 ↓
Runtime Variables
 ↓
Validation
 ↓
Final Value

---

65. Secret Reference Resolution

例如配置：

{
  "apiKey": {
    "secretRef": "secret://github/production"
  }
}

最终：

Config Resolver
 ↓
Secret Runtime
 ↓
Secret Provider
 ↓
memory only

绝对不要把解析后的 Secret 再持久化。

---

66. Runtime Context

Action 执行时：

export interface RuntimeConfigContext {
  config: ResolvedConfig

  providers: ProviderContext

  credentials: CredentialContext

  environment: Environment

  variables: Record<string, unknown>
}

---

67. Action Integration

Action：

async execute(input, ctx) {
  const timeout = await ctx.config.get(
    'seo.scan.timeout'
  )

  const provider = await ctx.providers.resolve(
    'search'
  )
}

Action 不需要：

process.env
database.config
secret table

---

68. Agent Integration

Agent 可以读取：

agent.model
agent.maxIterations
agent.maxTokens
agent.temperature

但必须经过：

Agent Policy
 ↓
Configuration Runtime

Agent 不能自己修改：

production secrets

---

69. Skill Integration

Skill Manifest 可以声明：

interface SkillConfigRequirement {
  key: string

  required: boolean

  description: string
}

例如：

seo.content-generation
requires:
  llm.provider
  llm.model

Runtime 自动检查。

---

70. Plugin Configuration

Plugin Manifest：

interface PluginManifest {
  id: string

  config?: ConfigDefinition[]

  providers?: ProviderDefinition[]

  credentials?: CredentialDefinition[]
}

Plugin 安装：

Plugin
 ↓
Config Definitions
 ↓
Provider Definitions
 ↓
Credential Definitions
 ↓
Registry

---

71. Plugin Settings Page

Plugin 可以声明：

Settings

例如：

SEO
├── General
├── Scan
├── Search Engine
├── AI
├── Credentials
└── Advanced

但 UI 使用：

DevOS Configuration UI

而不是每个 Plugin 自己实现配置存储系统。

---

72. MCP Configuration

MCP Server：

MCP Server
 ├── endpoint
 ├── transport
 ├── auth
 ├── timeout
 ├── credential
 └── enabled

统一：

MCP Configuration Runtime

---

73. MCP Credential

例如：

MCP Server:
github

Credential:
github-mcp-production

Secret:
secret://github/mcp-production

---

74. Workflow Configuration

Workflow 可以使用：

${project.id}
${environment.id}
${task.id}
${config.xxx}
${secret.xxx}

但：

${secret.xxx}

只能在安全 Runtime Context 中解析。

---

75. Template Variables

定义：

export interface VariableResolver {
  resolve(
    expression: string,
    context: RuntimeVariableContext
  ): Promise<unknown>
}

例如：

${task.id}
${project.name}
${environment.name}

---

76. Variable Security

禁止模板执行任意代码。

不能：

${eval(...)}

只能：

property lookup
approved functions

---

77. Configuration Expression

可以支持：

${config.seo.timeout}
${environment.name}
${project.id}

但必须是：

sandboxed expression

---

78. Configuration Cache

Configuration Runtime 可以缓存：

global
organization
project
environment

但是 Secret 缓存必须：

short TTL
memory only
never Redis plaintext

---

79. Configuration Invalidation

配置改变：

config.updated
 ↓
Event Runtime
 ↓
Config Cache invalidation
 ↓
Runtime refresh

---

80. Worker Configuration

Worker 启动：

Bootstrap Config
 ↓
Environment
 ↓
Worker Config
 ↓
Provider Config

动态配置：

worker.concurrency
worker.queues
worker.pollInterval

可以热更新。

---

81. Scheduler Configuration

Scheduler：

scheduler.enabled
scheduler.maxConcurrent
scheduler.pollInterval
scheduler.misfirePolicy

通过 Configuration Runtime。

---

82. Queue Configuration

例如：

queue.default.concurrency
queue.ai.concurrency
queue.browser.concurrency
queue.retry.maxAttempts

禁止 Queue Runtime 自己读取：

process.env

---

83. Database Configuration

Database Bootstrap：

DATABASE_URL

但是：

pool.max
pool.timeout
query.timeout

可以由 Config Runtime 管理。

---

84. Storage Configuration

例如：

storage.defaultProvider
storage.bucket
storage.region
storage.maxUploadSize
storage.signedUrlTTL

Credential：

storage credential

通过：

Credential Runtime

---

85. Search Configuration

例如：

search.defaultProvider
search.semantic.enabled
search.embeddingProvider
search.maxResults

Provider：

PostgreSQL
OpenSearch
Meilisearch

---

86. Email Configuration

例如：

email.provider
email.from
email.replyTo

Credential：

SMTP password
API key

通过 Secret Runtime。

---

87. Environment Promotion

支持：

development
 ↓
staging
 ↓
production

但：

Secret 不应该简单复制。

应该：

Config Promotion

与：

Secret Binding

分离。

---

88. Config Promotion

例如：

staging:
seo.scan.timeout = 60

production:
seo.scan.timeout = 60

可以 promote：

staging config
 ↓
production config

但：

staging OpenAI key

不能 promote。

生产环境重新绑定：

production credential

---

89. Environment Diff

必须提供：

dev vs staging
staging vs production

配置 Diff：

worker.concurrency
dev: 2
prod: 16

seo.scan.timeout
dev: 30
prod: 90

Secret：

production secret differs

只显示：

configured

不能显示值。

---

90. Environment Import / Export

允许导出：

configuration definitions
configuration values
provider definitions
credential references

不允许导出：

secret values

---

91. Configuration Bundle

可以生成：

configuration bundle

通过：

Artifact Runtime

保存。

内容：

config.json
providers.json
credentials.json
environment.json

Secret：

secret references only

---

92. Configuration Migration

与 12 集成。

例如：

v1:
llm.provider

v2:
llm.defaultProvider

Migration：

llm.provider
 ↓
llm.defaultProvider

---

93. Configuration Schema Version

每个 Config Definition 可以：

interface ConfigDefinition {
  key: string

  schemaVersion: number
}

升级：

schema v1
 ↓
migration
 ↓
schema v2

---

94. Plugin Upgrade

Plugin 升级：

Plugin v1
 ↓
Config compatibility check
 ↓
Config migration
 ↓
Secret compatibility
 ↓
Provider compatibility
 ↓
Plugin v2

---

95. Configuration Validation During Upgrade

升级前必须检查：

required configs
schema changes
removed configs
renamed configs
provider changes
credential changes
secret changes

如果：

breaking

必须进入：

UpgradePlan

---

96. Configuration Snapshot

每次 Task/Execution 开始时，可以记录：

interface ConfigurationSnapshot {
  id: string

  createdAt: string

  platformVersion: string

  configVersion: number

  environmentId?: string

  valuesHash: string
}

不一定保存全部 Secret。

---

97. Reproducibility

结合 12：

每个 Execution 应该知道：

runtimeVersion
pluginVersion
actionVersion
skillVersion
mcpVersion
configurationVersion
environmentId

这样才能回答：

为什么昨天这个 Action 成功，今天失败？

---

98. Configuration Hash

生成：

SHA-256

例如：

configHash:
a9c7...

Execution 记录：

configurationHash

Secret Value 不进入 Hash。

可以记录：

secretRef
secretVersion

---

99. Secret Version Binding

高可靠执行可以锁定：

secret://openai/prod
version = 7

这样：

Execution

不会因为 Secret Rotation 导致执行中途变化。

---

100. Task Configuration Snapshot

Task：

Task
 ↓
Configuration Snapshot
 ↓
Jobs

批量 Task 的所有 Job 默认使用：

Task configuration context

这样不会出现：

Job 1 → config v10
Job 2 → config v11
Job 3 → config v12

除非明确允许动态配置。

---

101. Dynamic vs Pinned Configuration

配置可以：

dynamic
pinned

Dynamic：

每次读取最新配置

Pinned：

Task 创建时锁定版本

生产任务推荐：

pinned

---

102. Agent Configuration

Agent Run 应记录：

model
provider
temperature
maxTokens
maxIterations
budget
configurationVersion

如果 Agent 中途改变配置：

replan

并记录原因。

---

103. Configuration Permissions

建议：

config.read
config.create
config.update
config.delete
config.rollback
config.export

Secret：

secret.read
secret.create
secret.rotate
secret.revoke
secret.delete

Provider：

provider.read
provider.create
provider.update
provider.delete
provider.test

Environment：

environment.read
environment.create
environment.update
environment.archive

---

104. Secret Read Policy

Secret 权限应该比 Config 更严格。

例如：

config.read

允许：

OpenAI credential = configured

但：

secret.read

才允许：

实际读取 Secret

---

105. Secret Access Without Exposure

Provider Action 最好：

Provider Runtime
 ↓
Secret Runtime
 ↓
Provider SDK

而不是：

Agent
 ↓
Secret Value

Agent 通常只需要：

credentialId

---

106. Provider Test Action

提供：

provider.test

例如：

provider.openai.test
provider.github.test
provider.cloudflare.test

流程：

Provider
 ↓
Credential
 ↓
Secret
 ↓
Health/Test
 ↓
Result

完整走：

Action Runtime

---

107. Secret Rotation Task

Rotation 如果复杂：

Secret Rotate
 ↓
Task
 ↓
Job
 ↓
Worker
 ↓
Provider
 ↓
Validation
 ↓
Activate
 ↓
Audit

不要在 HTTP 请求中执行长时间 Rotation。

---

108. Environment Lifecycle

creating
 ↓
active
 ↓
disabled
 ↓
archived

删除 Environment 默认不允许直接物理删除。

推荐：

archive

---

109. Environment Delete Protection

Production：

delete

必须：

approval

甚至默认：

forbidden

---

110. Environment Resource Scope

所有 Resource 可以绑定：

environmentId

例如：

core.server
core.database
core.storage
seo.website

从而支持：

production resource
staging resource

隔离。

---

111. Environment-aware Search

Search Runtime 自动加入：

environmentId

例如：

Search production servers

不能返回：

development servers

除非权限允许跨 Environment。

---

112. Environment-aware Storage

Artifact：

environmentId

File：

environmentId

Storage Policy 可以要求：

production artifacts

存储在：

production bucket

---

113. Environment-aware Queue

可以：

production queue
staging queue

例如：

queue.production.ai
queue.staging.ai

防止：

staging job

跑到：

production worker

---

114. Worker Environment Binding

Worker：

interface Worker {
  environmentIds?: string[]

  capabilities: string[]
}

Worker 只能领取允许 Environment 的 Job。

---

115. Provider Environment Binding

Provider Credential：

environmentId

例如：

OpenAI Production
OpenAI Staging

不能混用。

---

116. Configuration Registry

建立：

Configuration Registry

负责：

definitions
schemas
defaults
scope
validation
UI metadata
version
migration

---

117. Secret Registry

负责：

secret metadata
references
versions
provider
scope
rotation
expiration

不负责：

business configuration

---

118. Provider Registry

负责：

provider definitions
provider implementations
capabilities
configuration schema
credential schema
health

---

119. Environment Registry

负责：

environment definitions
status
scope
configuration binding
provider binding
storage binding
queue binding

---

120. Runtime Resolution Chain

完整：

Execution
 ↓
Environment
 ↓
Config Resolver
 ↓
Configuration
 ↓
Provider Resolver
 ↓
Credential Resolver
 ↓
Secret Runtime
 ↓
External Provider

---

121. Unified Example

例如：

Agent:
“扫描网站 a.com”

Agent：

seo.website.scan

Action Runtime：

Action
 ↓
Environment = production
 ↓
Config:
seo.scan.timeout = 90
 ↓
Provider:
search.google
 ↓
Credential:
google-search-console-production
 ↓
Secret:
secret://google/search-console/prod
 ↓
Execution

整个过程：

Audit
Log
Trace
Metric
Usage
Cost
Event

都自动生成。

---

122. Configuration UI

DevOS Settings：

Settings
├── General
├── Organizations
├── Projects
├── Environments
├── Configuration
├── Secrets
├── Credentials
├── Providers
└── Runtime

---

123. Configuration UI Detail

配置页面：

Configuration
├── Global
├── Organization
├── Project
├── Environment
├── Plugin
└── Resource

支持：

Search
Filter
Edit
Reset
History
Diff
Rollback
Lock
Export

---

124. Secret UI

Secret 页面：

Secrets
├── Active
├── Expiring
├── Expired
├── Revoked
└── Rotation

显示：

OpenAI Production
Status: Active
Version: 7
Expires: ...

不显示：

secret value

---

125. Credential UI

Credentials
├── OpenAI Production
├── GitHub Production
├── Cloudflare Production
└── SMTP Production

操作：

Test
Rotate
Revoke
Edit
View Usage
View Audit

---

126. Provider UI

Providers
├── LLM
├── Search
├── Storage
├── Git
├── DNS
├── Email
└── Browser

显示：

Provider
Status
Health
Latency
Credential
Environment
Usage
Cost

---

127. Environment UI

Environments

Development
  Active

Staging
  Active

Production
  Active

点击：

Production

显示：

Configuration
Providers
Credentials
Resources
Workers
Queues
Tasks
Health
Usage
Cost

---

128. Environment Diff UI

例如：

Production vs Staging

worker.concurrency
Production: 16
Staging: 4

search.provider
Production: google
Staging: bing

openai credential
Production: configured
Staging: configured

Secret：

Never show values.

---

129. API

Configuration：

GET    /api/config
GET    /api/config/:key
POST   /api/config
PUT    /api/config/:key
DELETE /api/config/:key
GET    /api/config/history
POST   /api/config/rollback

Secrets：

GET    /api/secrets
POST   /api/secrets
POST   /api/secrets/:id/rotate
POST   /api/secrets/:id/revoke
DELETE /api/secrets/:id

Credentials：

GET    /api/credentials
POST   /api/credentials
PUT    /api/credentials/:id
POST   /api/credentials/:id/test
POST   /api/credentials/:id/rotate
POST   /api/credentials/:id/revoke

---

130. Environment API

GET    /api/environments
POST   /api/environments
GET    /api/environments/:id
PUT    /api/environments/:id
POST   /api/environments/:id/disable
POST   /api/environments/:id/archive
GET    /api/environments/:id/config
GET    /api/environments/:id/diff

---

131. Provider API

GET    /api/providers
GET    /api/providers/:id
POST   /api/providers
PUT    /api/providers/:id
DELETE /api/providers/:id
POST   /api/providers/:id/test
GET    /api/providers/:id/health

---

132. CLI

devos config list
devos config get seo.scan.timeout
devos config set seo.scan.timeout 90
devos config history seo.scan.timeout
devos config rollback seo.scan.timeout 12

devos secrets list
devos secrets rotate openai-production
devos secrets revoke old-key

devos credentials list
devos credentials test openai-production

devos providers list
devos providers test openai

devos environments list
devos environments diff staging production

---

133. CLI Security

CLI：

devos secrets get

默认：

禁止

除非明确拥有：

secret.read

即使允许，也应该：

explicit confirmation

避免：

shell history

记录 Secret。

---

134. Logging Integration

禁止：

logger.info('credential', credential)

因为可能泄漏 Secret。

必须：

logger.info('credential resolved', {
  credentialId: credential.id,
  providerId: credential.providerId,
})

---

135. Error Integration

错误：

SecretProviderError

允许：

code
provider
secretRef

但不能：

secret value

---

136. Audit Integration

Config 修改：

config.update

Secret：

secret.rotate

Provider：

provider.update

Environment：

environment.update

全部进入：

Audit Runtime

---

137. Observability Integration

Metrics：

config_read_total
config_update_total

secret_access_total
secret_rotation_total

provider_request_total
provider_failure_total

credential_test_total

Tracing：

config.resolve
secret.resolve
provider.resolve
credential.resolve

---

138. Security Events

与 Event Runtime 集成：

security.secret.accessed
security.secret.rotated
security.secret.revoked

security.credential.created
security.credential.revoked

security.config.changed

security.environment.changed

---

139. Package Structure

建议：

packages/
├── config/
│   ├── runtime/
│   ├── registry/
│   ├── resolver/
│   ├── schema/
│   ├── validation/
│   └── migration/
│
├── secret/
│   ├── runtime/
│   ├── providers/
│   ├── encryption/
│   ├── rotation/
│   └── policy/
│
├── credential/
│   ├── runtime/
│   ├── registry/
│   └── providers/
│
├── provider/
│   ├── runtime/
│   ├── registry/
│   ├── resolver/
│   └── health/
│
└── environment/
    ├── runtime/
    ├── registry/
    └── policy/

---

140. NestJS Structure

src/
├── config/
│   ├── config.module.ts
│   ├── runtime/
│   ├── registry/
│   ├── resolver/
│   ├── controllers/
│   └── repositories/
│
├── secret/
│   ├── secret.module.ts
│   ├── runtime/
│   ├── providers/
│   ├── encryption/
│   └── repositories/
│
├── credential/
│   ├── credential.module.ts
│   ├── runtime/
│   └── repositories/
│
├── provider/
│   ├── provider.module.ts
│   ├── runtime/
│   ├── registry/
│   └── health/
│
└── environment/
    ├── environment.module.ts
    ├── runtime/
    └── repositories/

---

141. Database Tables

建议：

config_definitions
config_values
config_versions
config_locks

environments

providers
provider_bindings

credentials
credential_bindings

secrets
secret_versions

configuration_snapshots

---

142. config_values

核心：

id
definition_id
key
scope
scope_id
value_json
version
created_at
updated_at
updated_by

敏感值不能直接放这里。

---

143. secrets

核心：

id
namespace
name
provider
organization_id
project_id
environment_id
current_version
status
expires_at
created_at
created_by

Secret Value：

不作为普通业务 JSON 返回。

---

144. secret_versions

id
secret_id
version
encrypted_value
status
created_at
expires_at
revoked_at

加密后的 Value。

---

145. credentials

id
name
provider_id
organization_id
project_id
environment_id
status
metadata_json
created_at
updated_at

关联：

credential_secret_refs

---

146. providers

id
type
name
version
status
config_json
capabilities_json
created_at
updated_at

---

147. environments

id
organization_id
project_id
name
key
type
status
created_at
updated_at

---

148. Secret Encryption Requirements

Zcode 必须：

[ ] Secret never stored plaintext
[ ] Secret never returned by generic API
[ ] Secret never logged
[ ] Secret never included in Event payload
[ ] Secret never included in Audit
[ ] Secret never included in Trace attributes
[ ] Secret never included in Error message
[ ] Secret never included in configuration export

---

149. Configuration Security Requirements

必须：

[ ] RBAC
[ ] Scope policy
[ ] Validation
[ ] Audit
[ ] Versioning
[ ] Rollback
[ ] Lock
[ ] Redaction
[ ] Multi-tenant isolation

---

150. Testing

至少测试：

Configuration Resolution
Configuration Precedence
Configuration Validation
Configuration Version
Configuration Rollback
Configuration Lock

Secret Encryption
Secret Access
Secret Rotation
Secret Revocation
Secret Redaction

Credential Binding
Provider Resolution
Provider Failover
Environment Isolation
Environment Promotion

Agent
Plugin
MCP
Task
Job
Worker
Action

---

151. Configuration Precedence Test

输入：

Default = 10
Global = 20
Organization = 30
Project = 40
Environment = 50
Plugin = 60
Resource = 70
Runtime = 80

最终必须：

80

---

152. Configuration Rollback Test

v1 = 10
v2 = 20
v3 = 30

Rollback v3 → v1。

必须产生：

v4 = 10

而不是：

delete v2
delete v3

---

153. Secret Rotation Test

Secret v1 active
 ↓
create v2
 ↓
validate v2
 ↓
activate v2
 ↓
revoke v1

验证：

v1 revoked
v2 active

---

154. Secret Leak Test

模拟：

logger
error
trace
audit
event
diagnostic

都不能出现 Secret Value。

---

155. Environment Isolation Test

Production

不能读取：

Staging Secret

除非明确 Policy 允许。

---

156. Worker Environment Test

production job

不能被：

staging worker

领取。

---

157. Provider Credential Test

Production OpenAI Provider

只能使用：

Production Credential

不能自动 fallback 到：

Development Credential

---

158. Agent Security Test

Agent：

read production secret

如果没有：

secret.read

必须：

DENIED

Agent 不能通过：

MCP
Plugin
Workflow
Action

绕过。

---

159. Plugin Security Test

Plugin 尝试：

process.env.OPENAI_API_KEY

架构层面应该：

不依赖该机制获取运行时 Secret。

Plugin 必须使用：

Credential Runtime

---

160. MCP Security Test

MCP Tool：

get_secret

不应该默认暴露。

MCP 应该使用：

Provider / Credential Capability

完成外部调用，而不是把 Secret 交给 Agent。

---

161. Dynamic Config Test

修改：

worker.concurrency

验证：

Config Update
 ↓
Event
 ↓
Cache Invalidation
 ↓
Worker Reload

无需重启。

---

162. Configuration Failure

如果 Configuration Runtime 暂时不可用：

cached config

可以根据配置策略继续。

但：

security critical config

不能使用不确定的旧值。

---

163. Secret Provider Failure

如果 Secret Provider 无法访问：

Action
 ↓
Secret resolve
 ↓
failure

必须：

Action failed

而不能：

使用空 Secret

---

164. Provider Failure

Provider 失败：

Primary Provider
 ↓
Retry Policy
 ↓
Fallback Provider

但必须满足：

Policy
Compatibility
Credential availability

---

165. Configuration Export Security

Export：

config
providers
credentials metadata
environment

不允许：

secret values

---

166. Environment Promotion Test

测试：

staging config
 ↓
production

验证：

configuration promoted
secret not promoted
credential rebound
environmentId changed
audit generated

---

167. Acceptance Criteria

Zcode 完成后：

Configuration

[ ] Config Registry
[ ] Config Schema
[ ] Config Runtime
[ ] Scope
[ ] Precedence
[ ] Validation
[ ] Version
[ ] History
[ ] Rollback
[ ] Lock
[ ] Dynamic Reload

Secret

[ ] Secret Runtime
[ ] Encryption
[ ] Secret Provider
[ ] Reference
[ ] Version
[ ] Rotation
[ ] Revocation
[ ] Expiration
[ ] Redaction

Credential

[ ] Credential Registry
[ ] Provider Binding
[ ] Environment Binding
[ ] Test
[ ] Rotation
[ ] Revocation

Provider

[ ] Provider Registry
[ ] Provider Resolver
[ ] Health
[ ] Failover
[ ] Policy

Environment

[ ] Environment Resource
[ ] Isolation
[ ] Promotion
[ ] Diff
[ ] Environment Policy

---

168. Final Integration Acceptance

必须验证：

User
 ↓
Agent
 ↓
Skill
 ↓
Capability
 ↓
Action
 ↓
Environment
 ↓
Config Runtime
 ↓
Provider Runtime
 ↓
Credential Runtime
 ↓
Secret Runtime
 ↓
External Provider
 ↓
Execution

并且自动关联：

Audit
Log
Metric
Trace
Usage
Cost
Event

---

169. Zcode Golden Rules

Rule 1

禁止业务代码：

process.env.X

直接读取 Runtime Configuration。

---

Rule 2

禁止业务代码：

database.query(config)

自行读取配置表。

必须：

Config Runtime

---

Rule 3

禁止：

Plugin → Secret DB

必须：

Plugin
 ↓
Credential Runtime
 ↓
Secret Runtime

---

Rule 4

禁止：

Agent → Secret Value

除非明确 Permission + Policy + Action。

---

Rule 5

禁止：

MCP → Secret Store

MCP 必须通过：

Capability
 ↓
Action Runtime
 ↓
Credential / Provider Runtime

---

Rule 6

禁止：

Plugin → process.env

获取业务级 API Key。

---

Rule 7

禁止：

Plugin
 ↓
自己实现 config.json

必须注册：

ConfigDefinition

到 DevOS Configuration Registry。

---

Rule 8

禁止：

Plugin
 ↓
自己实现 Secret Manager

必须使用：

Secret Runtime

---

Rule 9

Production Environment 必须拥有：

额外权限
额外 Policy
Approval
Audit
Isolation

---

Rule 10

所有配置修改必须能够回答：

谁？
什么时候？
改了什么？
为什么？
从哪里改？
改之前是什么？
改之后是什么？

---

170. Final Architecture

完成 18 后：

                         DEVOS
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
     Resource            Action             Data
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                       Task / Job
                           │
                       Execution
                           │
             ┌─────────────┼─────────────┐
             │             │             │
          Config        Provider      Environment
             │             │             │
          Resolver      Resolver        Scope
             │             │             │
          Credential ──────┤             │
             │             │             │
           Secret          │             │
             │             │             │
             └─────────────┼─────────────┘
                           │
                    External Capability
                           │
          ┌────────────────┼────────────────┐
          │                │                │
         MCP            Plugin           Agent
          │                │                │
          └────────────────┼────────────────┘
                           │
                    Observability
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
       Log               Trace              Audit
        │                  │                  │
      Metric             Error             Usage
        │                  │                  │
        └──────────────────┼──────────────────┘
                           │
                     Event Runtime

---

171. DevOS Configuration Golden Rule

最终规则：

Configuration
      ↓
Configuration Runtime
      ↓
Environment Resolution
      ↓
Provider Resolution
      ↓
Credential Resolution
      ↓
Secret Resolution
      ↓
Runtime Context
      ↓
Action
      ↓
Execution

业务代码不应该知道 Secret 存在哪里。

Plugin 不应该知道配置存在哪里。

Agent 不应该知道 Provider Credential 存在哪里。

MCP 不应该接触 Secret Store。

Worker 不应该直接读取 .env。

所有这些都应该由：

DevOS Runtime

统一解决。

Configuration 决定系统怎么运行，Environment 决定在哪运行，Provider 决定使用谁，Credential 决定以什么身份访问，Secret 决定敏感凭证是什么；而这些都必须通过统一 Runtime 解析。