给 AI 团队设角色，最容易犯的错是把所有设定堆在一起——用户偏好、角色人设、团队规则全塞一个文件，结果改一处全队都变。WorkSwarm（openjiuwen 出品，曾用名 JiuwenSwarm）这套设定的逻辑其实是分层的。这篇用我给鸿蒙开发团队分别设定角色的实操，把全局设定、角色设定、团队设定分别放哪讲清楚，照着做就行。版本 0.2.6（以实际发布为准）。

一、为什么设定要分角色

先讲清楚一个概念：设定是分层的，不是一锅烩。

• 全局设定管「跟谁对话 + 基础设施」：USER.md（用户是谁）、AGENT.md、config.yaml（模型/通道/权限）；
• 角色设定管「每个 Agent 是谁」：IDENTITY.md（身份定位）、SOUL.md（价值观）；
• 团队设定管「大家怎么协作」：团队共享区、TEAM_MEMORY.md、技能可见性。

放错位置的后果很直接：把用户偏好写进某个角色的身份文件，换个人用就乱套；把角色人设堆进全局配置，改一个角色全队都变。

这篇用我给鸿蒙开发团队分别设定角色的实操，讲清楚每层设定放哪、怎么管理，包括我踩的那个坑——角色文件建了，里面却是空的。

二、建角色：给鸿蒙开发团队分别设定角色

先建团队，再分别设定角色。我给鸿蒙应用开发场景设了 3 个角色：

角色	干什么
pm负责人	需求探索与规划，leader 角色
应用开发者	编码实现
应用测试	测试验证

【图：d4-用户角色创建1.png】

每个角色都有两份「人设」文件：IDENTITY.md 决定它是谁（身份定位、性格、行为原则），SOUL.md 决定它的底层风格（价值观）。角色建好后，团队里就有三个「各是各的」成员了。我原本以为三个角色的身份文件会自动生成、各就各位——实际跑起来并不是这样，具体踩的坑放下一章说。

三、踩坑记录：角色文件建了但内容是空的

建完角色，我发现一个奇怪的现象：点了之后，只有 pm负责人（leader）那边创建了对应文件，而且文件里没有写入任务相关信息——空的。

我当时有点懵：角色建了，文件也建了，怎么内容是空的？后来才想明白，这不一定是 bug，是「角色文件默认行为」和我的预期有落差——文件建好归建好，任务信息不会自己长出来，得靠后续流程往里面写。

这个坑不算大，但值得记一笔：建角色 ≠ 建好角色，文件建完还要确认里面有没有该有的内容。

四、分层放设定：全局（USER.md）vs 角色（IDENTITY/SOUL）

把「放哪」讲透，就看 USER.md 和 IDENTITY.md 的分工。

USER.md 管「用户是谁」——你的偏好、习惯、身份，全局生效，跨会话、跨角色都继承。它描述的是「跟这台 Agent 对话的人」。

IDENTITY.md/SOUL.md 管「每个 Agent 是谁」——这个角色的定位、性格、行为原则，角色级生效。pm负责人是策划的、应用开发者是写代码的、应用测试是挑毛病的，各管各的。

【图：SVG-三级设定体系结构图】

我注意到一个细节：USER.md 没配置的时候，默认归属 teamleader 文件夹——也就是「面向用户的整体人设」默认由 Leader 承担（精确语义以实际版本为准，待核实）。

放错位置会怎样？两个例子：

• 把用户偏好写进某个角色的 IDENTITY——换项目、换角色就丢，还污染这个角色的人设；
• 把角色人设塞进全局配置——改一个角色，全队都变。

【图：d4-user文件写入.png】

一句话记住：「用户是谁」放全局，「每个 Agent 是谁」放角色。

五、角色文件落盘：把身份当配置管理（roles/ 目录）

这一步是我觉得最值的：把每个角色的 IDENTITY.md/SOUL.md 按成员分别落盘到 roles/ 目录，像管代码一样管人设。

好处有两个，都是我自己试出来的。

版本化。文件在目录里、能进版本管理，改没改、改了什么，有迹可循。不像在界面里随手改一句，过两天就忘了。

可独立复用。三个角色的人设是三个独立文件，换项目直接拷一份角色包过去，不用重新写。我给别的项目搭团队时，直接把这套角色文件搬过去改改就用。

落盘之后还有个附带好处：文件路径一眼能看出来是谁的——团队里谁是谁、谁管什么，看目录结构就清楚，不用翻聊天记录。

【图：d4-配置角色文件3.png】

【图：SVG-角色文件结构图】

说白了，这就是把「身份」当「配置」管理——目录化、版本化、可复用。

六、加一个「唱反调」的角色：对抗审查角色怎么设

3 个角色搭好后，我又加了一个：「需求对抗审查」角色，并设定了一条流程：

需求探索 → 需求对抗审查 → 需求收敛 → 用户故事排序开发

为什么加它？因为需求不是被确认出来的，是被质疑出来的。如果只有 pm负责人自己做需求探索，没人唱反调，需求就永远是「顺着我」的样子。

【图：d4-新增角色2.png】

这里有个关键：探索的人和唱反调的人必须是两个独立身份。让同一个 Agent 又当运动员又当裁判，它大概率给自己打高分；把「唱反调」独立成一个角色，它才有立场真挑毛病。这就是角色隔离的意义——身份各是各的，流程才不混。

七、诚实复盘：什么时候不用这么麻烦

说句实话，这套精细的分角色、落盘管理，不是所有场景都需要。

单 Agent 处理简单任务，直接做就行，不用建团队、不用分层设角色。我之前用单 Agent 直接做完过一个用户订单管理系统，根本用不上这套。

角色分层、roles/ 目录落盘，是团队/复杂任务场景才需要的工程——角色多、要协作、流程长，才值得把「身份」当配置精细管理。任务简单的话，这么折腾反而是负担。

【图：d3-集群模式体验.png】

八、下一步：把角色包当资产复用

这次落盘的 roles/ 目录，别删，留着当资产。

1. 下个项目直接复用——拷一份角色包，改改人设就能用；
2. 想深入可以研究团队记忆和技能可见性——哪些知识团队共享、哪些技能谁能用，又是一层隔离；
3. 多试几次不同角色组合，沉淀出你自己顺手的一套。

你给 AI 团队设角色时踩过什么坑？评论区聊聊。