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