WORKFLOW.md 配置

每个项目可以在仓库根目录放置 WORKFLOW.md 文件，配置 AI Agent 行为、质量门禁、钩子等。

格式

WORKFLOW.md 使用 YAML front-matter 进行配置：

---
orchestration:
  mode: polling
  interval_seconds: 30

agents:
  primary: claude
  fallback: codex
  type_mapping:
    design: claude
    coding: claude
    testing: claude
    review: claude
  fallback_chain:
    - claude
    - codex
    - opencode

gate_scores:
  auto_merge_threshold: 85
  human_review_threshold: 60
  block_threshold: 40

hooks:
  pre_task:
    - npm install
  test:
    - npm test
  lint:
    - npm run lint
  build:
    - npm run build

limits:
  max_parallel_tasks: 3

daemon:
  selection_strategy: least_loaded
  prefer_agent_match: true

sandbox:
  enabled: true
  base_image: node:22-alpine
  memory: 2g
  cpus: 2
  network: none
---

# 项目工作流

关于项目工作流的额外 Markdown 文档写在这里。

配置段

orchestration

字段	类型	默认值	说明
mode	string	polling	编排模式：polling、event_driven、hybrid
interval_seconds	number	30	轮询间隔（≥ 5）

agents

字段	类型	默认值	说明
primary	string	claude	主要 Agent
fallback	string	codex	后备 Agent
type_mapping	object	—	将节点类型映射到特定 Agent
fallback_chain	list	—	有序后备链

请使用 claude、codex、copilot、gemini、opencode、kimi、mimo、qwen、codebuddy、qoder、trae、zcode 等规范 ID。MiMo Code、Qwen Code、CodeBuddy、Qoder CLI、TraeCode CLI 与 ZCode 是受支持的显式选择集成，请通过 primary、type_mapping 或节点/执行级覆写显式选择。它们的认证、端点和模型由实际执行它们的机器上的本机 CLI profile 管理；通用 LLM Integration 不配置这些 Coding Agent。Smart Router 选优和系统生成的默认后备顺序会有意排除 mimo、qwen、codebuddy、qoder、trae 与 zcode；把任意一个写入自定义 fallback_chain 都属于显式启用，应先在目标 Runtime 验证。TraeCode CLI 与 ZCode 在真实 live gate 前会保持 installed_but_not_ready；ZCode 还必须配置批准的 FORGEXA_ZCODE_ALLOWED_SHA256。

Harness 是独立显式 ID deepseek，只能在验收后的个人 Runtime 上使用，例如：

agents:
  primary: deepseek
  fallback_chain: []

这不会使 Harness 成为 RouterAgent 自动候选或默认 fallback。其受管 profile、模型覆写与认证只读引用在本机配置，不通过通用 LLM Integration。自定义 fallback 条目同样属于显式启用。参阅固定构件验收与限制；原生 Windows 与共享池保持阻断。

gate_scores

字段	类型	默认值	说明
auto_merge_threshold	number	85	自动合并分数线
human_review_threshold	number	60	需要人工评审的分数线
block_threshold	number	40	阻断进度的分数线

阈值必须满足：auto_merge ≥ human_review ≥ block。

hooks

钩子命令经过白名单校验以确保安全。允许的前缀包括：

• npm install/ci/run/test、yarn install/run/test、pnpm install/run/test
• pip install、poetry install/run
• python -m pytest/ruff/mypy
• go mod/build/test/vet
• make、git、docker run
• mvn、gradle、cargo

设置 hooks.allow_custom: true 可绕过白名单（需要管理员权限）。

钩子	触发时机	示例
pre_task	每个任务之前	npm install
post_task	每个任务之后	npm run format
test	测试执行	npm test
lint	Lint 执行	npm run lint
build	构建执行	npm run build

sandbox

字段	类型	默认值	说明
enabled	boolean	false	启用 Docker 沙箱运行测试
base_image	string	自动检测	使用的 Docker 镜像
memory	string	2g	容器内存限制
cpus	number/string	2	容器 CPU 限制
network	string	none	网络模式（none 表示隔离）

daemon

字段	类型	默认值	说明
selection_strategy	string	least_loaded	选择策略：least_loaded、round_robin、affinity、random
prefer_agent_match	boolean	true	优先选择匹配 Agent 的守护进程
locality_aware	boolean	false	优先选择靠近 Git 仓库的守护进程

热重载

WORKFLOW.md 在检测到变更时自动重载。如果新配置无效：

• 旧配置保持生效
• 无效快照以 invalid 状态存储
• 发布警告事件