智能体工作模式说明

本文说明智灵桌面端中主会话与子会话的工作模式（agent mode）：各模式在行为与工具上的差异、典型适用场景，以及如何选用。实现细节见智灵客户端（主）仓库源码；与 桌面端：AI 智能体 中的「工作模式」一节互为补充。

工作模式是什么

工作模式决定本轮对话中模型收到的模式说明（Markdown）、工具列表过滤（是否只读、是否可见科研专用工具等），以及部分产品流程（例如从计划「实施」切入时会切换到智能体模式）。

与模式相关的两层概念：

• 会话默认模式 session.mode：新建会话或切换会话时的默认选择。
• 单条用户消息上的模式 message.agentMode：用户发送该条消息时选中的模式；同一次多轮工具调用续跑时，实现上会优先沿用最后一条用户消息上的模式，避免底部输入框中途改模式干扰进行中的请求（实现见主仓库 front_ui/src/components/Agent/AgentPromptFactory.jsx 中 resolveAgentTurnRequestConfig）。

快捷键：主输入区可用 Shift-Tab 在模式列表中循环切换（实现见 front_ui/src/components/Agent/MessageInput.jsx 中 handleCycleAgentMode）。

内置模式一览

界面展示名通过软件本地化翻译；下表英文名为当前内置键对应常见译法。

* 说明：代码层面仅 ask 映射为只读工具策略（readonly）；plan 等其余内置模式均为 full。计划模式「以计划文档为主、不执行计划」主要来自模式前缀系统提示与主仓库 front_ui/src/assets/agent_modes/plan.md 的约束，而非只读工具集。若需要强约束不写文件，应使用 问答（ask） 或继承 ask 策略的自定义模式。

主输入区下拉顺序（不含子会话专用 ID）：agent → plan → research → debug → 自定义模式 → ask（见 buildAgentModeOptions）。

分模式说明与适用场景

智能体（agent）

• 适用：日常开发、写文档、改代码、跑工具链、需要持久化到仓库的落地工作。
• 要点：模式说明见主仓库 front_ui/src/assets/agent_modes/agent.md — 主动用工具、优先落地到文件、避免过度延伸。

计划（plan）

• 适用：需求较复杂、需要先结构化实施计划再动手；希望输出保存在 .zhiling/plans/<计划名>.plan.md 的计划书（含 YAML 元数据与 todos 等，详见 plan.md）。
• 要点：
• 每轮用户请求前会附加计划模式前缀说明（PLAN_MODE_PREFIX_SYSTEM_MESSAGE），强调简单问答可简答，否则先检索再写计划；并约束不做计划外写入（模型侧约定，非独立沙箱）。
• 从界面执行计划「实施」等流程时，AgentProvider.submitMessageToSession（front_ui/src/components/AgentManager/AgentProvider.jsx）会将会话切到 agent 并按需强制本轮 agentMode 为 agent，与「计划书写在 plan 模式、执行在智能体模式」一致。

科研（research）

• 适用：文献与证据链、假设与局限、学术写作风格、需要科研专用工具（工具可声明 for_modes 含 research；工具策略继承自 research 的自定义模式与内置 research 同等参与匹配，见 isResearchBasedAgentMode）。
• 要点：
• 模式说明见主仓库 front_ui/src/assets/agent_modes/research.md。
• 代码还会在科研相关上下文中附加 PDF→Markdown 来源约定（RESEARCH_MODE_PDF_MD_CACHE_PREREQUISITE）：复杂版式 PDF 优先使用 .md-cache/ 下高质量 *.pdf.high.md，避免误用标准或历史隐藏 md。

调试（debug）

• 适用：难以稳定复现或需运行时证据的问题；愿意按轮次插桩、看日志再迭代。
• 要点：见主仓库 front_ui/src/assets/agent_modes/debug.md — 日志建议放在 .zhiling/debug/，统一可搜注释如 ZHILING_DEBUG_HOOK，并通过 wait_for_debugger_log 与用户确认 mark_as_fixed / proceed。

问答（ask）

• 适用：概念解释、读代码给建议、方案讨论但不想动仓库；或希望降低误改风险。
• 要点：见主仓库 front_ui/src/assets/agent_modes/ask.md — 可只读检索；除非用户明确要求写入，否则不主动改文件。对应工具策略为 readonly。

子会话：image / plot

• 说明：不在主输入区模式中列出；由父 Agent 通过子会话工具派生（允许传入的模式 ID 见 SUBSESSION_AGENT_MODE_IDS：agent、research、plan）。子会话实现见 front_ui/src/components/Agent/agentFunctions/functions_sub_session.jsx。
• image：文生图子 Agent，见 front_ui/src/assets/agent_modes/image.md（generate_image、输出路径与正文内联预览等）。
• plot：偏数据可视化与媒体展示，见 front_ui/src/assets/agent_modes/plot.md。

自定义模式

在应用设置中可配置 customAgentModes 条目：id、名称、Markdown 正文、toolPolicy（工具策略来源）、可选 reuseBuiltinInstructions（为 true 时将所选内置模式的说明与用户正文拼接）。

• toolPolicy 为 readonly 时，继承 问答（ask） 的工具策略；为 full 或缺省/非法时，继承 智能体（agent）。
• 也可将 toolPolicy 设为内置模式 id（如 research、plan），则继承该模式的工具策略与对应内置说明拼接逻辑（见 normalizeCustomAgentModeToolPolicySource、resolveAgentModeMeta）。
• 正文长度上限与设置页一致：MAX_CUSTOM_AGENT_MODE_MARKDOWN（65536 字符）。

工具如何按模式过滤

合并 API 工具列表时，若工具定义含 for_modes：

• 未定义或非法：视为全模式可用。
• 空数组：全模式不可用。
• 非空：仅当当前模式 ID（归一化后）匹配其中一项时可用；若列表含 research，则 research 与所有「科研类」自定义模式（isResearchBasedAgentMode）均视为匹配。

逻辑见 front_ui/src/components/Agent/AgentManager.jsx 中 isFunctionAllowedForAgentMode。

选用原则（简要）

1. 先问清要不要改仓库：只咨询、要安全 — ask；要落地改代码/文件 — agent。
2. 先计划后动手：大需求、多步骤、要可交付的计划文档 — plan；执行计划或日常实现 — 切回 agent（或走产品「实施」流程自动切换）。
3. 要引用与论文式严谨：research（或自定义继承 research 工具策略）。
4. 要运行时证据与多轮确认：debug（配合日志路径与用户 wait_for_debugger_log 操作）。
5. 子会话：按父任务性质在 agent / research / plan 中选子 Agent 模式；文生图、图表展示等由父 Agent 触发对应子会话类型。

以下能力与模式正交，由设置单独控制，不在上表「模式」内：

• 联网搜索与抓页：agentAllowWebAccess（及兼容旧键 agentAllowWebSearch、agentAllowNetworkAccess），见 isAgentWebAccessAllowed。
• 任务看板类工具与提示：agentTaskBoardModeEnabled，见 isAgentTaskBoardModeEnabled。

默认配置示例可参考主仓库 assets/basic_config_import.js（如 customAgentModes、backgroundAgentModel 等）。

维护者速查（主仓库路径）

开发文档中与日志相关的写法示例见主仓库 docs/LOGGING.md。

相关文档

• 桌面端：AI 智能体
• 桌面端设置说明