角色创建器

概述

当用户想要创建、更新或排查由 [agents.<角色>] 和角色 配置文件 支持的自定义子智能体角色时，请使用此技能。

此技能将角色安装到 ~/.codex/config.toml（或用户选择的项目配置中），写入特定于角色的配置文件，并根据 codex-rs/core/config.schema.json 验证密钥支持。

默认行为是严格最小化：仅配置 model、model_reasoning_effort 和 developer_instructions，除非用户明确要求添加其他参数。

默认位置是 ~/.codex/config.toml，但是，如果用户要求项目范围内的角色，则该角色将安装在项目的 .codex/config.toml 中。也可以安装到仓库中的子文件夹中。

不可协商的输入

步骤 1 始终是输入收集。在运行任何写入/安装/验证命令之前，收集并确认：

• model（模型）
• model_reasoning_effort（模型推理努力程度）
• developer_instructions（开发者指令）
• 安装范围（global 全局 或 project 项目）
• role_name（角色名称）
• description（描述）
• role_config_file（角色配置文件，首选绝对路径）

提出简洁的问题：

1. 此角色应使用哪个模型？（推荐：gpt-5.3-codex）
2. 它应使用什么推理努力程度？（推荐：medium；选项 medium|high|xhigh）
3. 角色的开发者指令应优先考虑什么？（目标、边界、成功标准）
4. 您希望将其安装到全局（~/.codex/config.toml）还是项目中（.codex/config.toml）？
5. 您想要任何沙箱、网络搜索、MCP 或其他限制吗？
6. 在 spawn_agent 中应显示什么角色名称和描述？

执行关卡：

• 不要推断缺失的必需值。
• 在以上所有必需输入被明确提供或用户明确接受默认值之前，不要开始步骤 2（写入文件）。

可选参数的默认策略

• 除非明确要求，否则不要设置沙箱标志。
• 除非明确要求，否则不要设置 web_search。
• 除非明确要求，否则不要设置 MCP 标志/条目。
• 除非明确要求，否则不要添加任何其他可选的 config_file 键。
• 如果用户意图不明确，在添加可选键之前，先问一个简短的澄清问题。

知识与应用规则

角色创建器必须了解完整的配置面，但只能应用用户要求配置的键。

• 必需行为：
• 在有助于时解释可用的可选类别。
• 当用户询问可能配置时，提供具体示例/模板。
• 默认情况下，保持生成的配置最小化。
• 仅在用户明确要求时才添加可选键。
• 如果用户说“保留默认值/继承”，则省略可选键，而不是设置显式值。

角色配置面（可以自定义的内容）

角色 config_file 被解析为完整的配置层。如果省略某个键，它通常会从父级继承。

• 模型和推理：
• model
• model_reasoning_effort
• model_reasoning_summary
• model_verbosity
• personality
• 核心行为：
• developer_instructions
• 沙箱和权限：
• sandbox_mode
• [sandbox_workspace_write] 字段，如 network_access、writable_roots
• 网络搜索：
• web_search（disabled|cached|live）
• 功能切换：
• [features] 键，如 memory_tool、shell_tool
• MCP 服务器：
• [mcp_servers.<name>] 条目（enabled、required、command、args、env_vars）
• 应用程序/连接器：
• [apps.<name>] 条目（enabled）

当用户要求高级角色控制时，使用来自以下位置的具体示例：

• templates/minimal-role-config.toml
• templates/restricted-role-config.toml
• templates/full-role-config.toml
• templates/frontend-architecture-role.toml

支持的角色声明键

对于 [agents.<role_name>]，仅支持以下键：

• description（描述）
• config_file（配置文件）

不要在 [agents.<role_name>] 下添加任何其他内容。

工作流程

1. 收集并确认必需输入（硬关卡）。

• 询问模型、推理努力程度、开发者指令、安装范围、角色名称、描述和角色配置文件路径。
• 仅在用户明确同意时才确认是否使用默认值。
• 在此步骤中不要写入文件。

2. 验证环境和解析后的路径。

• 确保仓库模式存在：codex-rs/core/config.schema.json
• 根据范围解析配置目标：
• global（全局） -> ~/.codex/config.toml
• project（项目） -> <项目路径>/.codex/config.toml

3. 创建或更新角色配置文件。

• 使用 scripts/write_role_config.sh 写入必需字段。
• 仅在用户明确要求时才添加可选控制。
• 脚本支持的可选控制：
• sandbox_mode + workspace-write 设置
• web_search 模式（设置为 disabled 以防止网络搜索）
• MCP 控制（mcp_clear、mcp_enable、mcp_disable）
• 如果用户想要超出脚本标志范围的选项（例如 model_reasoning_summary、features、apps、丰富的 MCP 服务器定义），则从 templates/ 下的模板开始，手动编辑，然后运行验证。
• 在输出中清晰沟通：
• 目前已配置： 已写入的键
• 可用但未设置： 留待继承的相关可选键

4. 在主配置中安装角色。

• 使用 scripts/install_role.sh。
• 此操作会写入/更新：
• features.multi_agent = true
• [agents.<role_name>] description/config_file
• 添加的安全性：
• 安装程序只修改与角色相关的键，并保持 config.toml 的其余部分不变。
• 安装程序在写入之前总是会为目标 config.toml 创建一个带时间戳的备份。
• 除非传递 --update-existing，否则不会覆盖现有的角色定义。

5. 在报告成功之前进行验证。

• 使用 scripts/validate_role.sh。
• 确认必需的 role-config 字段存在。
• 确认角色声明键仅为 description/config_file。
• 确认顶级角色配置键相对于模式是有效的。

6. 分享可运行的 spawn 示例。

• 示例：

{"agent_type":"<角色名称>","message":"<任务>"}

命令

# 1) 写入角色配置文件（仅必需字段；默认行为）
.codex/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/researcher.toml \
  --role-name researcher \
  --model gpt-5.3-codex \
  --reasoning medium \
  --developer-instructions "仅研究代码和文档；不进行编辑；返回文件：行证据。"

# 1b) 可选控制（仅在明确要求时）
.codex/skills/role-creator/scripts/write_role_config.sh \
  --output ~/.codex/agents/researcher.toml \
  --role-name researcher \
  --model gpt-5.3-codex \
  --reasoning medium \
  --developer-instructions "仅研究代码和文档；不进行编辑；返回文件：行证据。" \
  --sandbox-mode workspace-write \
  --network-access false \
  --writable-roots "/home/willr/Applications/codex1" \
  --web-search disabled

# 2) 在 ~/.codex/config.toml 中注册角色
.codex/skills/role-creator/scripts/install_role.sh \
  --role-name researcher \
  --description "只读代码库研究专家" \
  --role-config-file ~/.codex/agents/researcher.toml

# 2b) 有意更新现有角色定义
.codex/skills/role-creator/scripts/install_role.sh \
  --role-name researcher \
  --description "已更新的角色描述" \
  --role-config-file ~/.codex/agents/researcher.toml \
  --update-existing

# 3) 验证角色配置和声明键
.codex/skills/role-creator/scripts/validate_role.sh \
  --role-name researcher \
  --config ~/.codex/config.toml \
  --role-config ~/.codex/agents/researcher.toml \
  --schema /home/willr/Applications/codex1/codex-rs/core/config.schema.json

防护措施

• 如果运行时返回 未知的 agent_type，请验证角色是否存在于活动配置中，以及 config_file 路径是否存在/可读。
• 如果运行时返回 代理类型当前不可用，请检查角色文件的 TOML 有效性和不支持的键。
• 保持指令是针对具体角色的且可操作（范围、做/不做、交付格式）。
• 未经运行验证，不得声称成功。

参考资料

• 角色键矩阵和运行时行为：references/role-config-reference.md
• 可重用模板：templates/