专业 Agent 不是角色扮演：定义职责和产物

“你是一位资深架构师，拥有二十年经验，思维严谨。”

这段人设可以改变语气，却没有回答最基本的工程问题：它负责哪一段任务，需要先读什么，能修改哪些对象，什么事情不能做，完成后留下什么，失败时又该返回给谁。换成“测试专家”或“安全大师”，问题依旧存在。

小编现阶段的判断是：专业 Agent 的最小单位不是人物性格，而是一份可以独立执行、独立验收的阶段责任。 名字方便我们称呼它，职责边界、输入、动作和产物才决定它能不能工作。

上一篇已经判断什么时候值得拆 Agent。本文假设拆分决定已经成立，只讨论怎样把角色定义清楚；跨角色交接时消息应携带哪些路径、状态和风险，留给下一篇。

一、正式配置只提供角色入口

Codex 当前支持在项目的 .codex/agents/ 下用单独的 TOML 文件定义项目级 custom agent。根据 OpenAI 的Subagents 官方说明，每个文件至少需要 name、description 和 developer_instructions。它还可以设置模型、推理强度、沙箱、MCP Server 和 Skills 等会话配置；未设置的会按官方规则从显式启动参数、项目默认或父 Agent 继承。

官方机制还规定了运行关系：subagent 在独立 agent thread 中工作，主线程负责启动、等待和汇总；subagent 默认继承父线程当前的沙箱或权限模式，custom agent 可以覆盖部分配置。权限继承说明它“技术上能做什么”，并不会自动生成项目里的职责分工。

当前 JVS 项目有三份正式 Agent 文件：

• .codex/agents/topic-master.toml
• .codex/agents/article-master.toml
• .codex/agents/article-reviewer.toml

Codex 会自动发现这个目录中的独立 TOML 文件。每个文件定义一个 Agent，角色身份以文件内的 name 为准，文件名只是便于维护的约定。这三份文件都提供了官方要求的三个字段，因此已经构成项目级 custom agent 的正式入口。

文件里的长段 developer_instructions 则承载 JVS 自己的协作约定，例如文章大师不能给自己的文章作最终质检，质检员默认不能修改正文。官方支持我们写入这些指令，但具体职责来自项目设计，不能表述成 Codex 对所有写作 Agent 的内置规则。

二、一张角色卡要解决哪些问题

人设通常只回答“像谁说话”，角色卡要回答“这份工作如何被验收”。在小编看来，一份可用的 Agent 定义至少要把下面这些对象钉住。

2.1 职责边界与所需输入

职责边界用一个可完成的阶段来描述。例如“完成一篇已规划文章”比“负责内容质量”更清楚。后者可能同时覆盖选题、写作、审阅和发布，没有退出位置。

输入要写成可检查对象。文章大师需要已确认的主题、文章编号、目标路径、前置文章和写作素材；缺少关键输入时不能靠猜测补齐。这里只定义“开工需要什么”，不展开上游怎样把这些字段组织成一条交接消息。

2.2 允许动作与禁止事项

“允许动作”说明角色在本阶段应完成哪些操作，例如读取规划、创建指定正文、执行自审和更新目标状态。“禁止事项”挡住邻近但不属于它的责任，例如重写主题规划、发布文章或宣布独立质检通过。

动作约定与沙箱配置要分开看。当前三份 JVS Agent TOML 没有单独设置 sandbox_mode，因此实际技术权限按当前运行环境继承；“质检员默认不改正文”目前主要由 developer_instructions 和项目规则约束。指令边界不能伪装成操作系统级强制隔离。需要更硬的限制时，应在适用场景中再收紧工具或沙箱，但权限设计仍要服从角色产物。

2.3 产物、完成条件与失败条件

一个 Agent 说“处理好了”，接收者仍然不知道该检查什么。产物要能落到文件、报告、状态或结构化结论；完成条件说明哪些证据齐全后可以返回，失败条件则说明什么情况下必须保留真实状态并停止。

文章大师的正文落盘、自审通过和状态一致，可以支撑“写作阶段完成”；它不能支撑“文章质量最终通过”。质检员的审阅报告可以给出质量结论，却不能因为发现问题就越过默认边界直接重写正文。两份产物分别对应两份责任。

回传对象也应明确。主题大师把写作阶段交给文章大师，文章大师完成后把结果返回流程负责人；质检员同样向流程负责人返回审阅结论。这里先确定“谁接收结果”，下一篇再讨论返回内容怎样完整携带事实和路径。

三、用三个真实配置核对职责边界

这张角色卡由当前项目的三份 TOML、根目录 AGENTS.md 和相关 Skill 规则压缩而来。它只代表 JVS 项目的设计，不能当作 Codex 预置的写作模板。

Agent	阶段责任与所需输入	允许动作	禁止事项	明确产物	完成、失败与回传对象
topic_master	澄清真实写作需求；需要用户回答、主题现场和当前 topic.md	调研需求、提出推荐、执行确认门禁、收集素材、协调下游	未确认时写入主题或启动下游；自己代写正文、代替质检	已确认的 topic.md 与写作素材包	用户确认且素材包齐全后返回流程状态；关键选择未确认则停留在主题阶段
article_master	完成一篇指定文章；需要已确认主题、素材包、文章编号、路径和前置内容	使用 jvs-write 写作或修订、执行第二遍自审、回写草稿状态	重新定义主题、越出指定文章、给自己最终放行	单篇正文与 drafted 状态	正文、自审和写后校验通过后返回 topic_master；输入缺失或审计未过则报告真实状态
article_reviewer	独立质检指定草稿；需要正文、规划、风格规范和待核事实	使用 jvs-review 重新检查事实与质量、生成分级问题和审阅结论	默认修改正文；相信实现者自述直接通过；把个人偏好当质量问题	独立审阅报告与审阅状态	报告、统计和结论一致后返回 topic_master；事实无法核验则标明待验证，不伪造结论

这张表刻意没有把所有交接字段写进去。它只检查三个角色有没有不同的阶段责任、工作对象和放行条件。完整路径、授权范围、风险和未决事项怎样随角色移动，是 03-03 的实践产物。

四、共享工作区里要有单一写入责任

多个 Agent 可以拥有独立 thread，却可能仍在同一个项目工作区中读写文件。官方 Subagents 文档提醒，并行写入会增加冲突和协调成本。对于有前后依赖的任务，启动更多 Agent 不会让事实来源自动保持一致。

JVS 项目选择串行链路：topic_master 先完成并确认主题，article_master 再写单篇正文，正文达到草稿状态后才由 article_reviewer 审阅。这个顺序让同一时刻只有一个角色对当前阶段的核心产物负责。

“单一写入责任”不要求整个项目永远只有一个 Agent 工作。它要求为共享事实指定所有者：主题阶段由主题角色维护规划，写作阶段由文章角色维护指定正文，质检阶段由质检角色维护审阅报告。其他角色可以读取，但不能同时改写同一来源。

并行适合真正互不依赖的只读调查，例如分别核对几份官方资料。只要两个角色需要修改同一正文、状态文件或计划，就应先拆开所有权，或按依赖顺序执行。本文只给出这个调度原则，不展开具体交接格式。

五、用反例识别“换皮 Agent”

角色定义完成后，可以做一次很便宜的反向检查：去掉名称和人设，只比较剩余内容。

假设“文章大师”和“质量大师”都读取同一篇文章，都可以直接改正文，都以“文章已优化”为产物，也都能宣布通过。两份配置即使语气完全不同，工程上仍是同一个角色。它们会争抢写入权，出现问题时也找不到独立责任人。

另一个反例是只写禁止事项：“不得越权、不得遗漏、不得出错”。这种角色看起来谨慎，却没有允许动作和明确产物，遇到边界时只能不断停下来请示。

检查时保留几个具体问题即可：

• 去掉角色名后，它的职责是否仍能与其他 Agent 区分；
• 输入缺少哪一项时必须停止；
• 哪些动作属于它，哪些邻近动作明确不属于它；
• 是否只有一个角色能修改当前核心产物；
• 完成和失败分别会留下什么可检查结果；
• 结果最终返回给谁。

这些问题都答得出来，人物设定才有资格成为可选的表达层。答不出来时，先别补更响亮的专家称号，回到任务阶段重新画责任边界。

专业 Agent 的价值不在于模拟几个专家同时开会。它把一项复杂工作拆成少量有所有者的阶段：拿到明确输入，在允许范围内动作，避开禁止事项，留下可以独立验收的产物，并在完成或失败时把结果返回给确定对象。到这一步，角色才从人设变成工程组件。