agent-config

Agent Config

agent-config 会将经验证的 Agent Host 能力和用户确认的配置文件等级映射为适当的执行拓扑、模型和工作量。它原生支持主要的编码 Agent 框架（Codex、Claude Code、Antigravity、DSH、OpenCode、ZCode、Cursor、Grok Build、Hermes、Pi），并为其他框架提供安全的通用／手动回退方案。它不需要配套能力、外部 Skill 或外部服务。

适用场景

• 在拓扑、模型等级或工作量很重要的复杂多 Agent 或分区任务开始前。
• 有明确的设置意图（agent-config setup），需要配置或重新配置主机模型和等级时。
• 由 light-implement 或 ask-light 调用或提供时。

输入

• 范围明确的任务、SPEC 或工单图。
• 有证据支持的主机能力和已确认的配置文件（通过配套 MCP 或会话输入提供）。

脚本入口 scripts/agent_config.py 接受规范的 Host 和 Profile 证据；缺失、过期或不匹配的证据会返回 NEED_INPUT。 标志和规则：host-evidence-schema.md。

设置门控

• 明确设置： 如果以设置意图（agent-config setup）调用，则运行设置模式以准备或修复运行环境和 Profile（参见 references/setup.md）。设置模式不会为当前任务规划执行。
• 常规调用： 只有 agent-config 模式会为当前工作规划执行拓扑和路由。通过配套工具 get_setup_status 检查设置状态；健康状态规则见 companion-contract.md。如果配套工具缺失或过期，则提供设置选项或仅继续规划。如果 Profile 缺失或过期，则提供设置选项，或在安全可行的情况下仅在当前会话内继续。绝不静默进入设置模式、自动安装 MCP 工具或修改主机文件。

输出契约：AgentConfigResult

agent-config 会生成规范的 AgentConfigResult 信封：

• readiness：READY | NEED_INPUT | NEED_PROJECT_TICKETS | BLOCKED | UNSUPPORTED（具有权威性的执行就绪状态；已移除冗余状态）。
• mode：persisted | session-local | plan-only
• setup_state：companion（ready | missing | stale），profile（persisted | session-local | missing）。
• handoff："project-tickets" | "setup" | "light-implement" | null
• execution_config：ExecutionConfig | null（仅当 readiness === "READY" 时才会存在；对于所有未就绪状态，必须为 null）。

核心流程

1. 设置检查： 通过状态正常的配套工具或会话输入，验证已确认的配置文件。没有配置文件时，绝不猜测使用单模型。
2. 检查宿主： 读取活动模型、支持的推理强度值和并发限制。
3. 确定任务形态： 将任务归类为 single-pass 或 decomposed（绝不依据字数判断）。
4. 分解门槛： 如果任务已分解且尚无正式工单，则输出 readiness: NEED_PROJECT_TICKETS、handoff: "project-tickets"、execution_config: null，并向调用方返回工单建议。
5. 难度与层级： 对于多模型，将工作难度（routine..critical）映射到用户确认的配置文件层级（routine、standard、high、review）。如果未说明难度或推理需求，脚本可以询问类型化决策来源（参见可选功能）。
6. 解析推理强度： 将抽象策略（如 highest-supported）严格解析为已验证的宿主支持字符串（如 high），绝不输出未经验证的字面值 max。
7. 选择执行模式：
   • 情况 A（固定单模型 + 单轮处理）： 在主会话中直接执行，使用单个模型和已解析的推理强度，不使用虚构角色。
   • 情况 B（固定单模型 + 已分解，P0）： 控制器主会话协调全新的工作器上下文，使用相同模型和实际推理强度。
   • 情况 C（分层多模型 + 单轮处理）： 根据任务难度映射到用户配置的层级，并采用最精简的拓扑。
   • 情况 D（分层多模型 + 已分解，P0）： 将工单难度映射到用户配置的层级，解析推理强度，并由控制器整合。
8. 输出计划并应用： 输出符合 references/plan-schema.md 和 AgentConfigResult 的计划。修改宿主配置必须先预览并获批（preview_configuration → 用户批准 → apply_configuration → validate_configuration）。

不变量

• 不猜测智能水平： 绝不根据名称或元数据推断模型能力；模型层级必须由用户严格确认。
• 单模型是一等选择： 单模型是与其他拓扑并列的选择，不是降级后的备用方案。情况 B 和情况 D 都是 P0 路径。
• 不静默修改： 未经明确同意，不自动安装软件包、不启动后台守护进程，也不编辑宿主文件。
• 反字数规则： 由语义复杂度和依赖关系决定任务形态，绝不依据文本长度。

交接

• 向调用方返回 AgentConfigResult；handoff 表示建议，不代表获准启动另一个 Skill。
• 如果当前调用方 light-implement 已处于活动状态，则当 readiness === "READY" 时，可以继续执行其已获准且范围有限的事项。
• 对于独立调用，准备就绪时建议明确调用 $light-implement，需要工单时建议调用 $project-tickets，然后停止。启动任一由用户调用的阶段，都需要用户明确批准该确切目标，并且宿主转换支持已通过验证；否则显示其准确调用方式。
• 代码审查通过 review-loop 收敛；最终验收由 project-review 负责。

可选功能

• 未说明复杂度或推理需求 → 任务分析器通过 light-decide 脚本路径提问；如果你不使用脚本自行判断，则调用 light-decide，问题 ID 为 agent-config/task-complexity 或 agent-config/reasoning-need。它只会在项目的 Decision data: 限制范围内提问（没有限制行表示在设备端处理），仅当用户策略文件针对该问题进行了校准时才应用答案，且只有当分数明确落在较低档位内时才应用降级。不可用或未经校准 → 保持确定性配置文件。判断不会确认 Profile，也不会更改 Host 配置。

参考资料

• references/setup.md — 设置问卷和等级绑定流程
• references/routing.md — 4 种对等执行模式和拓扑选择
• references/task-assessment.md — 任务类型和难度标准
• references/companion-contract.md — Companion MCP 工具协议（8 个工具）
• references/harness-support.md — 主要编码 Agent harness（10 个原生适配器）和通用回退方案
• references/profile-schema.md — 主机范围的配置文件架构
• references/plan-schema.md — 执行计划格式和审核语义
• references/host-evidence-schema.md — 主机证据架构 v2
• references/provider-adapter-contract.md — 适配器边界和预览-应用