返回 DeepSeek-Reasonix
SUBAGENT_PROFILES.zh-CN.md
根目录 / docs / SUBAGENT_PROFILES.zh-CN.md
1 # 子智能体 Profile
2
3 子智能体 Profile 是可复用、显式调用的专用智能体，适合代码评审、问题调查、文档整理等
4 聚焦任务。每个 Profile 都是带有 `runAs: subagent` 的手动 Skill：Reasonix 会启动隔离的
5 子智能体，把 Profile 提示词和任务交给它执行，并且只把最终答案返回父智能体。
6
7 桌面端、交互式 CLI 和 Headless CLI 共用这些 Profile。它们直接复用现有 Skill 文件格式和
8 目录，不引入独立数据库。
9
10 ## 创建 Profile
11
12 从提示词文件创建项目级 Profile：
13
14 ```bash
15 reasonix subagent create reviewer \
16 --description "检查改动的正确性和回归风险" \
17 --prompt-file reviewer.md \
18 --tools read_file,grep,bash \
19 --model deepseek-pro \
20 --effort high
21 ```
22
23 在 workspace 中，`create` 默认使用 project scope；不在 workspace 中时默认使用 global
24 scope。也可以通过 `--scope project` 或 `--scope global` 明确指定。项目级 Profile 存放在
25 `.reasonix/skills/<name>/SKILL.md`，全局 Profile 存放在 Reasonix home 的 Skill 目录中，
26 具体路径见[配置路径](./CONFIG_PATHS.zh-CN.md)。
27
28 提示词可来自 `--prompt`、`--prompt-file PATH`、`--prompt-file -` 或标准输入：
29
30 ```bash
31 printf '%s\n' '检查任务，只报告可执行的问题。' | \
32 reasonix subagent create reviewer --description "代码评审"
33 ```
34
35 名称可以包含字母、数字、`_`、`-` 和 `.`。如果名称已经被项目级、全局、自定义或内置 Skill
36 占用，Reasonix 会拒绝创建，避免覆盖已有内容。
37
38 ## 调用 Profile
39
40 在交互式 CLI 或桌面聊天中使用斜杠命令：
41
42 ```text
43 /reviewer 评审当前 diff
44 ```
45
46 这会真正启动隔离子智能体，并非把提示词文本注入父智能体。父会话只保留任务和子智能体的
47 最终答案，不保留子智能体的完整工作上下文。
48
49 父模型也可以在调用时选择 Profile，且不会把 Profile 名称列表写进工具 schema（保持
50 prompt-cache 稳定）：
51
52 ```text
53 task(profile="doc-rewriter", prompt="重写 docs/01.md", write_paths=["docs/01.md"])
54 fleet(tasks=[
55 {profile="doc-rewriter", prompt="重写 docs/01.md", write_paths=["docs/01.md"]},
56 {profile="doc-rewriter", prompt="重写 docs/02.md", write_paths=["docs/02.md"]}
57 ])
58 ```
59
60 - `task` / `fleet` 项上的 `profile` 按名称解析 `runAs: subagent` Skill（显式名称可调用
61 `invocation: manual` Profile）。
62 - Profile 正文成为子智能体的**完整**系统提示词，不再隐式叠加 concise 默认提示。
63 - `write_paths` 声明互不重叠的写入目标，使多个写入子智能体可共享同一工作区并行。
64 写入任务若省略 `write_paths`，则声明整个工作区（与其他写入 claim 互斥）。
65 在 `fleet` 中，多个整工作区 claim 或任何路径重叠会在预检阶段整批失败，不会启动任何任务。
66 - 会话默认：`agent.max_subagent_concurrency = 6`、`agent.max_parallel_writers = 3`
67 （均可配置为 1–32，且写入上限不得超过总上限）。
68
69 脚本和其他 Headless 场景应使用显式命令：
70
71 ```bash
72 # 使用只读工具预览。
73 reasonix subagent try reviewer "评审当前 diff"
74
75 # 按正常权限和沙盒策略运行。
76 reasonix subagent run reviewer "评审并修复当前 diff"
77
78 # 从标准输入读取任务，并限制工具调用轮次。
79 git diff | reasonix subagent run reviewer --max-steps 20
80 ```
81
82 `run`/`try` 的参数应放在任务文本之前。两个命令都支持 `--model REF` 和 `--dir PATH`。
83 `try` 始终选择只读 runner；`run` 使用正常的隔离 runner，权限中的 `deny` 规则和沙盒限制
84 仍然有效。普通 `reasonix run` 仍是单次任务入口，不会隐式解释 `/<profile>` 语法。
85
86 ## 管理 Profile
87
88 ```text
89 reasonix subagent list [--dir PATH]
90 reasonix subagent create <name> --description TEXT (--prompt TEXT | --prompt-file PATH)
91 [--scope project|global] [--model REF] [--effort LEVEL]
92 [--tools a,b] [--color NAME] [--dir PATH]
93 reasonix subagent edit <name> [--description TEXT]
94 [--prompt TEXT | --prompt-file PATH] [--model REF] [--effort LEVEL]
95 [--tools a,b] [--color NAME] [--dir PATH]
96 reasonix subagent delete <name> --yes [--dir PATH]
97 reasonix subagent try <name> [--model REF] [--max-steps N] [--dir PATH] <task>
98 reasonix subagent run <name> [--model REF] [--max-steps N] [--dir PATH] <task>
99 ```
100
101 `edit` 只修改命令行中显式提供的字段。用显式空值清除可选字段：
102
103 ```bash
104 reasonix subagent edit reviewer --model= --effort= --tools= --color=
105 ```
106
107 省略工具列表或将其清空，表示 Profile 不额外添加工具白名单；runner 原有的工具可用性、权限、
108 沙盒和只读规则仍然有效。`delete` 必须带 `--yes`，不会发生隐式删除。
109
110 内置 Profile 没有可写的 Skill 文件。对它们执行 `edit` 时只支持 `--model` 和 `--effort`，
111 保存的位置与桌面设置页使用的按 Profile 覆盖配置相同；传入空值会删除对应覆盖。
112
113 ## 文件格式与高级 Profile
114
115 CLI 和桌面 Profile 编辑器会生成精简的 Skill 文件：
116
117 ```yaml
118 ---
119 name: reviewer
120 description: 检查改动的正确性和回归风险
121 color: orange
122 invocation: manual
123 runAs: subagent
124 model: deepseek-pro
125 effort: high
126 read-only: true
127 allowed-tools: [read_file, grep, bash]
128 ---
129 你是专注的代码评审员。检查指定改动，只返回可执行的问题，并按严重程度排序。
130 ```
131
132 `invocation: manual` 表示模型不会从固定 Skill 索引中自动发现该 Profile，但用户仍可显式
133 调用。`allowed-tools` 是 Profile 级工具白名单，不能绕过权限系统。`read-only: true`
134 强制使用只读工具 registry（剥离写入工具）；省略/`false` 保持旧版默认可写。
135
136 也可以手写更丰富的 `runAs: subagent` Skill，例如使用自定义 Skill path 或额外 frontmatter。
137 这些 Profile 可以被列出和调用，但 Profile 编辑器会拒绝编辑或删除以下内容：
138
139 - 不属于 project/global scope 的 Profile；
140 - `invocation` 不是 `manual` 的 Profile；
141 - 含有编辑器无法管理的 frontmatter 的文件；
142 - 含有 `references/` 或 `scripts/` 目录的 Skill。
143
144 这样可以防止精简编辑器静默丢弃高级 Skill 内容。此类 Profile 应直接按 Skill 文件管理。
145
146 ## 模型与推理强度选择
147
148 有效模型和推理强度按以下优先级选择：
149
150 1. `agent.subagent_models` 和 `agent.subagent_efforts` 中按 Profile 设置的覆盖；
151 2. 本次 `task` / `fleet` 调用参数中的 `model` / `effort`；
152 3. Profile frontmatter 中的 `model` 和 `effort`；
153 4. `agent.subagent_model` 和 `agent.subagent_effort` 默认值；
154 5. 已配置的 executor/默认模型及其默认推理强度。
155
156 例如：
157
158 ```toml
159 [agent]
160 subagent_model = "deepseek-pro"
161 subagent_effort = "high"
162 subagent_models = { reviewer = "deepseek/deepseek-v4-pro" }
163 subagent_efforts = { reviewer = "max" }
164 ```
165
166 `subagent run` 或 `subagent try` 的 `--model` 参数用于选择该 Headless 命令初始化时的默认
167 模型；Profile 专属配置仍按上述优先级生效。
168
169 ## 桌面端同步与排障
170
171 桌面设置页和 `reasonix subagent create` 创建的 Profile 共用同一批文件。修改 Profile 后，
172 请刷新或新建会话，让已经运行的会话重新加载 Skill registry。
173
174 如果调用时报 Profile 未知或已禁用，请检查 `reasonix subagent list`、当前 `--dir` 和
175 `skills.disabled_skills`。如果编辑时报 custom 或 rich Profile，应直接编辑其 `SKILL.md`，
176 不要强行经过 Profile 编辑器。Reasonix 在解析有效模型时会拒绝未知模型引用和无效 effort。
177
177 lines MARKDOWN