18 KiB
owner, backup, status, reviewed
| owner | backup | status | reviewed |
|---|---|---|---|
| @SivanCola | @esengine | active | 2026-10-20 |
会话级 Agent 预设
Studio 的「Agent 预设」把人设、工具、技能、MCP、扩展、Hook 和自定义命令 组合在一起。模型、推理强度与均衡/交付档位继续独立设置。 运行时复用 Reasonix，不加载 Harness 的 Cordis 插件。
选择和修改
选择「仅使用所选项」后，「添加模块」打开多选下拉菜单。可连续勾选多项、按 ID 或说明搜索，也可按来源分组全选。内置与自定义分组使用目录提供的来源信息； 旧服务端没有来源信息时显示「未分类」。
「全选」只作用于当前搜索结果，保留搜索结果之外的已选项，不会自动选择以后新增 的模块。「清空」移除全部已选 ID。「完成」、Escape 和点击外部都会关闭菜单并保留 草稿；点击「保存预设」才持久化。「继承当前配置」仍是独立模式。
批量修改保留已有模块的参数。目录中缺失的 ID 仍可编辑；「高级：手动输入模块 ID」 保留手动入口，填写 ID 不会安装资源或授予权限。
模式选择器默认隐藏。在「人设」管理页开启「显示模式选择器」后，所有窗格的聊天 输入框顶部显示选择器；设置搜索可直接定位此开关。关闭只隐藏入口，不改变会话模式。
初始使用日常搭档。点击内置卡片可明确 设置本机新任务默认模式，覆盖本地和远程新建任务；仅保存服务端首选项不会自动启用。 显示入口只读取目录，不会选择或绑定组合。隐藏时不挂载选择器，也不发起选择器的 目录读取；运行状态和 token 信息继续显示。
新建时明确指定的模式优先于卡片默认值，历史会话保留原绑定。点击卡片不切换已有 任务；按新建复用未使用的空白窗格时，应用所选默认模式。
首次提交前，在输入框顶部左侧打开 Agent 模式菜单；列表显示来源 和能力说明，分隔线下的「管理 Agent 预设…」打开管理页。接纳首条消息后，会话保留原绑定； 排队、待回答和后台工作期间也不能切换。锁定后可用其他组合新建会话。 清空或回退已开始的组合会话不会解除锁定。
入口只显示模式名与箭头，来源和锁定信息保留在菜单和无障碍说明中；运行状态、 耗时与 token 信息位于右侧，窄屏时换行。
管理列表按内置、个人和项目共享分组；新建和复制均在设置内容区打开独立编辑页：
内置采用响应式卡片，展示新任务默认标记、真实 ID、说明、模式详情、使用方法与 复制入口；个人和项目预设保留可编辑列表。详情、使用方法与复制不会更改默认模式。
| 模式 | 行为 |
|---|---|
日常搭档（builtin:general） |
创建会话时继承当前配置，处理日常代码、文件与资料任务；保留原稳定标识以兼容默认选择。 |
轻装搭档（builtin:minimal） |
使用简短人设和终端（bash），保留原生上下文压缩。所选模型支持读图且工具已启用时，额外提供图片读取（view_image）。 |
内置项的稳定 ID 继续兼容已有默认选择。已有会话保留保存时的名称、版本和模块要求。
人设提示参考 DeepSeek Harness 的提交 687f282e8625c6b8d11ff58211a90524be2e4317：
standard 使用简短的编程 Agent 身份提示；
minimal 使用简短的工程助手身份提示和较少的工具。
Reasonix 已使用相同的 minimal 开场提示。
日常搭档继续继承用户人设；轻装搭档保留 Reasonix 原生系统指令，没有采用 Harness 的完整提示词替换方式。本次文案更新不改变发送给模型的提示词或工具字节。
轻装搭档不装载自定义技能、命令、MCP、扩展、Hook 或子 Agent，保留回答和提问
所需的宿主控制工具。终端仍能修改文件和访问网络，继续遵守已有权限与沙箱；
轻装搭档不是只读模式。bash 是必需工具，缺失时会报告依赖错误；view_image
是可选工具，模型未启用读图能力或配置禁用该工具时，仍可使用终端。
代码审查、资料研究不再作为内置目录项提供；已有会话继续保留原绑定版本。 如果旧默认指向已移除的内置项，目录会提示用户明确选择新的默认项，不自动替换。
内置项只读，复制后才能修改。每类模块支持「跟随当前配置，包含之后启用的资源」或 「仅使用所选项」；显式空列表表示禁用。编辑器提供本机模块目录，导入先预览 缺失依赖，不会安装依赖或启动程序。
所选工具成员可声明 "optional": true，例如
{"id":"view_image","optional":true}。只有当前已可用的工具才会加入，不会因此
启用已禁用的工具或授予模型读图能力。不填写 optional 时仍为必需工具；
其他模块类型不接受可选成员。
设置导航显示为「人设」。编辑页直接展示名称、用途、两段人设文本和可选运行时 上下文开关；工具、技能与扩展按需展开。存放范围与自动生成的 ID 也直接展示， 保存后 ID 与范围不可修改。
底部固定提供取消和保存，返回列表、关闭设置或切换设置时会确认未保存的更改， 保存失败继续保留草稿。日常搭档的用户人设使用独立编辑入口，可从日常搭档详情 或设置搜索进入，与自定义预设分开保存。
保存产生新的定义版本，已存在的会话继续使用原先解析的人设、参数和权限规则。 按需会话使用当前已授权资源，旧快照会话继续使用保留资源。 页面分别显示定义版本和当前会话绑定版本。并发保存冲突时保留草稿并提示重载。
存储与兼容
绑定组合的会话不能移到其他项目，接口返回 agent_composition.workspace_bound，
复制或删除前即拒绝。请在目标项目新建会话；普通未绑定会话仍可按原流程移动。
| 内容 | 位置 |
|---|---|
| 用户声明 | <用户状态根>/agent-presets/definitions/<id>.json |
| 项目共享声明 | <工作区>/.reasonix/agent-presets/definitions/<id>.json |
| 定义版本和显式默认选择 | <用户状态根>/agent-presets/ |
| Studio 卡片选择 | 浏览器本地 rx-new-task-agent-preset |
| 本机授权记录和保留文件 | <用户状态根>/trusted/agent-presets/ |
选择器可见性沿用原本机浏览器键 rx-show-agent-composition，只有 on 启用；
缺失、off、未知值或不可读时均隐藏。写入失败保留旧值并报告错误。
原版本按相同的 on/off 值读取，中间默认显示的版本忽略此键；其他窗口同步存储
变化。可见性与卡片的新任务默认选择、已有会话绑定相互独立。
本地键只接受日常搭档和轻装搭档两种内置 ID，与服务端首选项独立，CLI 与 ACP 不读取它。
| 存储内容 | 当前版本读取 | 旧版本读取 |
|---|---|---|
| 缺失、不可读或未知值 | 保留原日常搭档行为 | 忽略此键 |
| 日常搭档或轻装搭档 ID | 在 Studio 新建请求中明确携带选择 | 忽略此键 |
写入失败时保留原选择并显示错误。新建请求继续执行既有选择权限与准入检查。
状态根遵守存储迁移设置。身份使用 builtin:、user:、project: 前缀；项目
绑定同时记录工作区。同名项按身份和来源并列显示。项目文件不能设置默认值，
项目默认组合必须由用户主动选择，并保存在个人状态中。
声明使用 schemaVersion: 1，保存采用原子替换和预期版本校验。
导出不包含凭据值或扩展二进制。MCP 参数包括 args、url、env、headers、
callTimeoutSeconds、startupTimeoutSeconds；扩展参数包括 args、env 和
timeoutMillis。
参数名会校验；env/headers 覆盖值只允许 ${NAME} 引用。
预设不能替换已安装扩展的可执行入口。
声明来源与权限
原生会话导入先把 HTTP 工作区选择解析为已登记的工作区值，再访问文件系统。 内部派发继承的绑定通过独立参数传递，不放入 HTTP 请求对象；传输格式保持不变。
个人人设声明读取和保留资源复制使用目录句柄。个人声明的链接可以指向存储目录 内部，不能逃逸到外部。会话目录名和资源相对路径在拼接前检查其范围。
Hook 资源读取有大小上限，检查后文件增长也不会无限读取。集合预分配避免未经检查 的容量相加，旧编码文本解码在分配前检查展开大小。
选择预设不会授予权限。内置声明是随程序发布的只读模板；用户声明由用户在个人 状态中明确编写；项目声明始终是仓库提供的不可信文件，信任工作区也不改变此边界。
| 内容 | builtin: |
user: |
project: |
|---|---|---|---|
| 人设及工具、模块选择 | 随程序发布 | 用户选择 | 仓库选择，但只能使用用户已授权的资源 |
MCP args、url、env、headers |
仅发布内容 | 允许；凭据值仍须使用引用 | 拒绝，包括空数组或空映射覆盖 |
| MCP 调用、启动超时 | 支持 | 支持 | 支持 |
扩展 args、env |
仅发布内容 | 允许；环境值仍须使用引用 | 拒绝 |
| 扩展超时 | 支持 | 支持 | 支持 |
| 扩展可执行入口、Hook/命令代码或模块安装 | 不新增权限 | 仍需已有授权 | 不能替换启动方式、批准或安装程序 |
当前内置项没有 MCP 或扩展参数覆盖。工具、技能、Hook 和命令在所有来源下均不 接受成员参数。项目预设只能选择用户已授权的资源，不能扩大能力或改写启动参数。 Hook 的项目程序授权与撤销检查继续生效；选择预设不等于批准程序。
声明读取、保存、导入、旧版本和执行绑定恢复会在模块启动前应用同一来源规则。 此前保存的项目绑定若含启动参数覆盖，历史仍可读取，但不能继续执行，即使本机 保留了旧授权记录；不会静默改写为其他组合。合法的仅超时项目绑定继续保留原版本。
按需会话与已有快照
新绑定使用 formatVersion: 2、resourceMode: "live"，保存权限规则，不保存资源文件内容。
切换时不捕获技能模板目录，也不加载全部技能的补充资料。读取或调用某个技能时，
才按普通会话的规则加载其正文和 references。命令与非阻断型 Hook 在使用时读取当前已授权资源。
继承模式跟随当前配置；明确勾选的模式保持白名单。两者都不能绕过资源启用状态和授权。 缺失的可选技能、离线 MCP 或纯工具扩展不阻止普通聊天，在实际使用该能力时报告问题。 撤销授权后，后续调用被拒绝；安全 Hook 仍然必须执行。
MCP 目录读取不连接未缓存的服务器，实际能力调用通过授权检查后才连接。
显式配置的自动连接独立于切换过程。MCP 与扩展工具使用稳定的 use_capability 入口，
不因连接状态改变模型可见的工具定义。
纯工具扩展按需从安装来源启动，不复制整个包。模型提供方、必需运行时及拦截器在对应 生命周期阶段初始化；改变这些启动契约后，需要新建会话或明确重载运行时，不能静默改写 已开始会话的系统提示。凭据仍由原凭据或配置机制提供，MCP 连接和进程状态按会话隔离。
没有新字段的已有绑定继续保留快照语义：继承项在绑定时解析一次，技能、非阻断型 Hook 和扩展代码使用保留副本，不跟随后续源文件修改。旧会话不自动转换。 原有信任、撤销、授权和沙箱规则继续生效。
Hook 保留直接引用的文件，并为常见脚本格式保留同目录依赖。脚本目录受资源 大小限制，不能包含凭据文件或越界、循环链接；目录内的合法源链接保存为普通文件， 已保存的快照不得被替换为链接。
建议将代码放在独立目录，凭据使用 环境引用。外部解释器和服务继续遵守原有平台及授权契约。 保留时按参数边界检查凭据，正确识别带引号的 Windows 文件路径；字面凭据参数和 无法解析的 Shell 启动命令仍被拒绝。
安全策略不属于可切换的组合
| Hook 或规则 | 能否由组合取消 |
|---|---|
PreToolUse、UserPromptSubmit、PermissionRequest |
不能，所有来源均保留，包括导入的 Claude 权限 Hook |
权限 ask/deny 规则及已撤销授权 |
不能，解析后的实际调用仍由原权限策略判断 |
| 其他 Hook 事件 | 可以，只保留所选非阻断型自动化 |
绑定组合中的扩展也只能收紧权限：拦截器与权限策略均不能把 ask/deny 改为
允许。未绑定会话的原有扩展契约不变。
装配和恢复时从当前已授权配置加载安全 Hook，包括旧版本中空 Hook 选择的绑定。 已安装包的安全 Hook 不受组合的扩展选择影响；项目程序批准与包启用状态仍须满足。
在设置中保存安全 Hook 会立即更新会话和子角色共享的运行器，不替换保留的自动化， 也不改写组合摘要。用户有权编辑安全策略，选择组合不能移除它。
绑定只进入本地会话元数据，不发送给 provider。快照会话使用原生事件日志 schema 4， 按需会话使用 schema 5。不支持该格式的旧程序明确拒绝，不回退到过期 checkpoint， 不截断或改写新日志。
无绑定历史仍走兼容路径，不套用当前默认组合。 无法授权或装配原绑定时，可以只读查看历史，不能继续执行。删除声明不会 删除已有会话所需的绑定版本。
快照原生导出使用 reasonix-native-session version 2，包含绑定和保留资源。
按需会话导出使用 version 3，只包含历史与权限规则，不包含本地资源文件或凭据。
当前版本可读取两种格式；旧客户端不能继续执行新格式会话。可在「设置 → 存储」
导入；导入不创建本机授权，不启动程序。
前端直接上传原始文件，不在渲染器读取或解析 JSON。后端复用同一原生解码器和 192 MiB／回放记录数限制。
| 拒绝原因 | 错误码 |
|---|---|
| 内容无效 | session.archive_invalid |
| 版本不支持 | session.archive_unsupported |
| 大小或记录数超限 | session.archive_too_large |
界面按错误码显示当前语言的提示。
POST /tree/sessions/import-native?workspace=... 接收原始 application/json 文件；
同一路径原有 {workspace, content} JSON 请求继续兼容。
会话导入提案 #13728 仍在开放中； 后续共用此解码器和限制，落地时把此入口接到统一流程，避免第二套解析规则。
配置备份 version 3 同时包含个人预设声明及个人默认选择。
旧快照的 MCP 在绑定时锁定工具契约。刷新或重连后若工具目录不兼容，会阻止继续执行， 不会静默替换 schema。扩展及包内 MCP 采用私有运行副本，关闭和装配失败时 释放对应临时目录。新按需会话在派发时检查当前授权和服务器身份。 Hook 命令中的凭据必须改用环境引用。
ACP 切换组合会保留本会话已校验的额外工作目录。派发新会话时继承精确绑定， 不重新选择当前默认组合；限定工作区的绑定不能派发到另一工作区，会在打开 运行时前明确拒绝。未绑定的日常搭档沿用原派发行为。新派发的绑定无法装配时， 不会降级为只读历史页面。
预设默认不启用：未选择和日常搭档不绑定，沿用原会话格式，不自动迁移人设。
保存的首选项不会自行启用；只有明确选择非日常搭档才绑定版本。
--agent-composition default 表示主动使用已保存的首选项。
/persona 保留 #13588 的用户配置行为，日常搭档设置复用原人设编辑器；
日常搭档在每次运行时构建时读取它。
显式组合保留所选人设；保存用户配置或预设都不改写已有绑定。前后缀补充
内置指令，不提供替换整个提示词的开关。
各入口
CLI 使用 --agent-composition builtin:minimal 或 --agent-composition user:my-agent。
交互会话的 /agent 列出目录，/agent user:my-agent 在首次提交前选择组合。
/preset 仍表示均衡/交付档位。ACP 增加独立的 agent_composition 选项，开始
对话后只保留当前选择。
远程会话使用远端目录、凭据和资源；新建时将所选组合 ID 交给远端解析，不上传本机可执行资源。
HTTP 路由、请求字段与稳定错误代码见 接口说明。
保存、删除、默认选择、导入预设及切换会话组合均要求请求具有配置编辑授权。
缺少时返回 HTTP 403 config.editing_disabled，不写文件或进入切换流程。
配对设备 不继承宿主的授权。目录、详情、导出及当前绑定查询保持可读。
远端面板代理在使用宿主凭据转发前，先拒绝配对设备的预设写入请求。读取和宿主
自身的请求仍可转发，远端再独立检查其配置编辑授权。
/status 和会话运行时列表返回 agentComposition。导入返回定义与依赖诊断，
需要用户检查后另行保存。错误代码在 Studio 中提供中英文翻译。
预设名称、版本和诊断不进入缓存前缀。切换到另一套组合首次使用时可能产生 冷缓存；编辑预设不会重写正在运行的会话前缀。