agentic-coding-workflow/config.example.yaml

# AgentCodingWorkflow 配置文件示例
#
# 用法：
#   1. 复制为 config.yaml（已被 .env / 真实凭据建议放在 .gitignore 之外管理）
#   2. 启动时设置环境变量：APP_CONFIG_FILE=./config.yaml ./bin/server
#
# 加载优先级（后者覆盖前者）：默认值 → 本配置文件 → 环境变量（APP_ 前缀）
# 即同名键存在 APP_xxx 环境变量时，会覆盖此处的值。

# 运行环境：development / production / test
env: development

# 本地数据目录（用于落地文件、缓存等）
data_dir: ./data

# 主加密密钥（必填）：32 字节的 hex 编码字符串，长度恰好 64 个十六进制字符
# 生成示例：openssl rand -hex 32
master_key: "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"

http:
  # HTTP 监听地址，格式 host:port，留空 host 表示监听所有网卡
  addr: ":8080"
  # 可选 TLS：enabled=true 时以 HTTPS 提供服务，读取 cert/key 文件。
  tls:
    enabled: false
    cert_file: ""
    key_file: ""
  # 跨域中间件：默认 off，避免误配破坏 SPA + WS 握手。开启时填 origin 白名单。
  cors:
    enabled: false
    allowed_origins: []          # 如 ["https://app.example.com"]
    allowed_methods: []          # 留空 = GET,POST,PUT,PATCH,DELETE,OPTIONS
    allowed_headers: []          # 留空 = Authorization,Content-Type,X-Client-Request-ID
    allow_credentials: true
    max_age_seconds: 600
  # 安全响应头：默认 on（透传安全）。HSTS 仅在 tls.enabled 时下发。
  security:
    enabled: true
    hsts_max_age_seconds: 31536000
    frame_options: "DENY"
    referrer_policy: "no-referrer"
    content_security_policy: ""   # 默认不下发 CSP（可能破坏 SPA/WS）；按需显式配置

# secret 加密 key provider：env（默认，APP_MASTER_KEY=version 1）| vault | kms。
# 轮换时把新版本 key 暂存到 APP_MASTER_KEY_V<n>，再调 POST /api/v1/admin/security/rotate-key。
crypto:
  provider: env
  vault:
    address: ""
    token: ""
    key_name: ""
  kms:
    key_id: ""
    region: ""

# user 模块：登录暴力破解节流（key = ip + 小写 email，固定窗口计数）。
user:
  login_throttle:
    enabled: true
    max_failures: 10
    window: 15m

db:
  # PostgreSQL DSN（必填）
  dsn: "postgres://acw:acw@localhost:5432/acw?sslmode=disable"

# 首次启动时的管理员种子账号
bootstrap:
  admin_email: "admin@local"
  admin_password: "changeme"

# Workspace 模块（git clone / worktree 落盘 + 各 git verb 超时）
workspace:
  # workspace clone/worktree 的根目录（程序会在其下自建 workspaces/ 与 tmp/ 子目录）
  data_dir: "./data"
  # 大仓库 clone 上限，按需调高；timeout 走 ctx 优先于 git 进程超时
  clone_timeout: "30m"
  fetch_timeout: "5m"
  push_timeout: "5m"
  # commit / status / worktree 等轻量操作
  ops_timeout: "60s"

# git CLI 配置（默认走 PATH 里的 git）
git:
  binary: "git"

# VCS / PR 集成（v1 支持 Gitea）。change_requests 与 done 阶段网关会使用这里的配置。
vcs:
  require_ci_pass: false
  gitea:
    base_url: "https://git.example.com"
    token: ""                  # 平台级 PAT；也可用 APP_VCS_GITEA_TOKEN 注入
    timeout: 15s
    merge_method: "merge"      # merge / squash / rebase，取决于 Gitea 实例支持

# Chat 模块（多模态对话 + LLM endpoints）
chat:
  attachment:
    # 单文件上限（MB）
    max_file_size_mb: 20
    # 单条消息中所有附件总和上限（MB）
    max_message_size_mb: 50
    # 允许的 MIME 类型白名单。"text/*" 通配任意 text/ 子类型。
    mime_whitelist:
      - image/png
      - image/jpeg
      - image/webp
      - image/gif
      - application/pdf
      - text/*
  stream:
    # SSE ring buffer 在流结束后保留多久，方便前端断线重连。
    ring_buffer_retention_seconds: 300
  history:
    # token 预算的安全余量百分比（5.0 表示在 (context_window - max_output) 上再保留 5%）
    safety_margin_pct: 5.0

# 附件存储驱动（当前仅支持 localfs）。生产建议挂载到独立卷。
storage:
  driver: "localfs"
  localfs:
    base_path: "./data/uploads"

# 后台 job runner 配置
jobs:
  enabled: true
  workers: 2
  shutdown_grace: 30s
  workspace_fetch:
    enabled: true
    interval: 5m
  worktree_prune:
    enabled: true
    interval: 24h
    idle_threshold: 720h
    warning_lead: 72h
  attachment_cleanup:
    enabled: true
    interval: 24h
    retention: 720h
  job_reaper:
    enabled: true
    interval: 1m
    # 须 > orchestrator.turn_timeout：编排器步骤的 handler 超时 = lease_timeout*9/10，
    # 必须容纳一次完整 agent 回合（默认 turn_timeout 10m → lease 15m，handler 13.5m）。
    lease_timeout: 15m
  job_purge:
    enabled: true
    interval: 24h
    completed_retention: 168h
  acp_events_purge:
    enabled: true
    interval: 24h
    retention: 168h          # 7 天
  mcp_tokens_purge:
    enabled: true
    interval: 24h
    retention: 168h  # 7 days
  # 审计日志保留期清理（observability roadmap §11）：删除早于 retention 的 audit_logs。
  audit_retention:
    enabled: true
    interval: 24h
    retention: 2160h  # 90 天

# Prometheus /metrics 端点（observability roadmap §11）。
# 暴露成本/会话数：auth_token 非空时要求 Authorization: Bearer <token> 或 ?token=<token>；
# 为空仅适用于绑定内网 / 由反向代理鉴权的部署。
metrics:
  enabled: true
  auth_token: ""

# 通知通道配置
notify:
  webhook:
    enabled: false
    url: ""
    secret: ""
    timeout: 10s
    # 默认空白名单 ⇒ 所有 webhook 投递被丢弃。生产部署需要显式列出要外发的 topics：
    topics: []
    # 可选 topics：
    # - workspace.sync_failed
    # - worktree.prune_pending
    # - webhook.dead_letter
    # - acp.session_crashed
  email:
    enabled: false
    smtp_host: ""
    port: 587
    from: ""
    username: ""
    password: ""
  im:
    enabled: false

# ACP module: agent subprocess pool + WebSocket fanout + event retention
acp:
  enabled: true
  max_active_global: 20
  max_active_per_user: 3
  spawn_timeout: 30s
  kill_grace: 5s
  stderr_buffer_lines: 100
  stderr_tail_bytes: 2000
  ws_ping_interval: 30s
  ws_pong_timeout: 60s
  ws_send_buffer: 256
  event_max_payload_bytes: 65536
  event_truncate_field_bytes: 4096
  event_retention_days: 7
  shutdown_grace: 30s
  permission_timeout: 5m
  brief_token_budget: 6000
  default_project_budget_usd: 0
  # per-session 执行沙箱（mode=none 默认；uid/container 仅 Linux）。
  # none      : 不隔离（Windows 开发 / CI / 任何非 Linux 机器）
  # uid       : 降权到低权 UID + setrlimit（+ egress 代理 env）
  # container : rootless 容器（UID + 文件系统屏蔽 + 网络策略 + cgroup 限额）
  sandbox:
    mode: none
    base_uid: 0                   # 低权 UID 基址；per-session uid = base + offset
    proxy_url: ""                 # 注入子进程的 HTTP(S)_PROXY（egress 白名单代理）
    address_space_bytes: 0        # RLIMIT_AS / --memory（0 = 不限）
    nproc: 0                      # RLIMIT_NPROC（0 = 不限）
    cpu_seconds: 0                # RLIMIT_CPU（0 = 不限）
    pids: 0                       # 容器 --pids-limit（0 = 取 nproc）
    disk_bytes: 0                 # RLIMIT_FSIZE（0 = 不限）

# Orchestrator / Planner module configuration（per-requirement run 状态机）
orchestrator:
  enabled: true
  max_attempts_per_phase: 3     # 单阶段 step 在 dead-letter 前的最大尝试次数
  turn_timeout: 10m             # 单回合（SendPromptAndWait）超时，须 < jobs.job_reaper.lease_timeout
  max_depth: 3                  # request_subtask 递归深度上限
  fan_out_limit: 3              # 单 step 并发子任务上限
  # 阶段→默认 agent-kind 名映射（run.config 未覆盖时用）。app 层按名解析为 agent_kind_id。
  # 为空时 StartRun 必须在 phase_agent_kinds 入参里显式提供每阶段 agent-kind id。
  phase_agent_kinds:
    # planning: "codex"
    # prototyping: "codex"
    # auditing: "codex"
    # implementing: "codex"
    # reviewing: "codex"
    # done: "codex"
  # 任务分解并行调度器（autonomy roadmap §10）：拓扑选取就绪子任务并扇出到并行 ACP session。
  # 注册为 jobs 周期 RunnerFn（单实例、单 tick，跨重启存活）。默认关闭，须显式开启。
  scheduler:
    enabled: false
    interval: 30s                          # 调度 tick 周期
    max_fanout_per_tick: 8                 # 每 project 每 tick 最多派发的 session 数
    max_concurrent_per_project: 4          # project 内活跃 session 软上限（<=0 不预检，仅靠 acp 硬上限）

# MCP (Model Context Protocol) module configuration
mcp:
  enabled: true
  public_url: http://localhost:8080/mcp        # 注入到 ACP 子进程的 ACW_MCP_URL
  system_token_ttl: 24h
  rate_limit:
    per_token_per_minute: 100
    global_per_minute: 1000

# Run profiles (后端托管 workspace 仓库启动) configuration
run:
  enabled: true
  kill_grace: 5s              # stop 时优雅终止宽限，超时后整树 SIGKILL
  out_buffer_lines: 1000      # 单次运行的合并 stdout+stderr 内存环形缓冲行数
  out_tail_bytes: 2000        # crash 时落 last_error 的尾部字节上限
  ws_send_buffer: 256         # 每个 WS 日志订阅者的发送缓冲
  shutdown_grace: 30s         # 服务关停时整体终止所有 run 进程的总时限
  # 透传给被托管命令的宿主环境变量白名单。APP_MASTER_KEY / DB DSN / git 凭据
  # 等敏感变量绝不应加入此名单。
  env_whitelist:
    - PATH
    - HOME
    - LANG
    - LC_ALL
    - TZ
    - USER
    - SHELL
    - SystemRoot
    - TEMP
    - TMP
    - USERPROFILE
    - APPDATA
    - LOCALAPPDATA
    - PATHEXT
    - ComSpec
    - NUMBER_OF_PROCESSORS
  # 一次性 exec 原语（MCP: run_command / run_tests）。默认保持命令白名单非空；
  # 生产环境不要设成 []，否则 system token 会得到任意命令执行能力。
  exec:
    default_timeout: 60s
    max_timeout: 600s
    max_output_bytes: 1048576
    allowed_commands:
      - go
      - npm
      - pnpm
      - yarn
      - node
      - python
      - python3
      - pytest
      - uv
      - cargo
      - rustc
      - make
      - cmake
      - ctest
      - git

# 管理员网页终端。仅 admin 可用；命令在 server 宿主进程/运行容器内执行。
terminal:
  enabled: true
  shell: "/bin/bash"            # Windows 开发环境可用 APP_TERMINAL_SHELL 覆盖为 powershell.exe
  max_sessions: 5
  kill_grace: 5s
  env_whitelist:
    - PATH
    - HOME
    - LANG
    - LC_ALL
    - TZ
    - USER
    - SHELL
    - TERM
    - NPM_CONFIG_PREFIX
    - NODE_PATH
    - NODE_ENV
    - SystemRoot
    - TEMP
    - TMP
    - USERPROFILE
    - APPDATA
    - LOCALAPPDATA
    - PATHEXT
    - ComSpec
    - NUMBER_OF_PROCESSORS

# 代码索引 / 项目记忆。embedding_endpoint_id 为空时自动降级：向量检索不可用，
# memory_search 走 keyword/tag 回退，grep/list 文件类工具仍可用。
code_index:
  enabled: true
  embedding_endpoint_id: ""
  embedding_model: "text-embedding-3-small"
  chunk_window_lines: 60
  chunk_overlap_lines: 10
  max_file_bytes: 524288
  search_top_k_cap: 50
  grep_max_matches: 200
  grep_max_file_bytes: 1048576

# 自动文档 / PR 摘要。默认关闭，避免每次提交都调用 LLM 产生成本。
docs:
  enabled: false