内置工具
内置工具是 Mirri Code 随核心引擎提供的工具集，无需安装 MCP server 即可使用。Agent 在每次对话中会根据任务需要自动选择并调用这些工具；用户可以通过权限审批界面查看每次工具调用的细节。
与 MCP 工具相比，内置工具由运行时直接管理，生命周期与会话绑定，无需外部进程。两者都遵循统一的审批机制：只读类工具（如 Read、Grep、Glob）默认自动放行，写入与执行类工具（如 Write、Edit、Bash）默认需要用户审批。YOLO 模式下普通工具调用的审批会被跳过，但 Plan 模式下的退出审批不受影响。
文件类
文件类工具负责读取、写入、搜索本地文件系统，是代码分析和修改任务的基础工具。
| 工具 | 默认审批 | 说明 |
|---|---|---|
Read | 自动放行 | 读取文本文件内容 |
Write | 需审批 | 创建或覆盖文件 |
Edit | 需审批 | 精确字符串替换 |
Grep | 自动放行 | 基于 ripgrep 的全文搜索 |
Glob | 自动放行 | 按 glob 模式查找文件 |
ReadMediaFile | 自动放行 | 读取图片或视频文件 |
Read 接受文件路径（path）以及可选的 line_offset（起始行号，支持负数从末尾倒数）和 n_lines（读取行数上限）。单次最多返回 1000 行或 100 KB，超出部分会附带截断提示。如果文件是图片或视频，工具会提示改用 ReadMediaFile。
Write 接受 path、content 和可选的 mode（overwrite 或 append，默认覆盖）。缺失的父目录会自动创建；append 模式将内容追加到文件末尾，不自动添加换行。
Edit 接受 path、old_string（要替换的精确文本）和 new_string（替换后的文本）。默认只替换唯一一处匹配，若文件中存在多处相同内容会报错并提示使用 replace_all: true。old_string 与 new_string 不能相同。
Grep 调用 ripgrep 搜索文件内容，支持正则表达式（pattern）、搜索路径（path）、文件类型过滤（type，如 ts、py）、glob 过滤（glob）和输出模式（output_mode：files / content / count，默认 files）。content 模式支持上下文行（-A、-B、-C）、忽略大小写（-i）、行号（-n，默认 true）、跨行匹配（multiline）。所有模式支持 offset + head_limit 分页，head_limit 默认 250、传 0 表示不限。.env、私钥等敏感文件会被自动过滤；include_ignored=true 可搜索被 .gitignore 忽略的文件，但敏感文件仍保持过滤。
Glob 按 glob 模式（pattern）在指定目录（path，默认工作目录）中匹配文件，结果按修改时间倒序排列，最多返回 100 条。默认尊重 .gitignore、.ignore 和 .rgignore；设置 include_ignored=true 可包含构建产物等被忽略的文件，但敏感文件仍会被过滤。支持 *.{ts,tsx} 这类花括号模式，也允许宽泛通配符模式，但通常会在匹配上限处截断。
ReadMediaFile 将图片或视频以多模态内容发送给模型，仅接受 path，文件大小上限 100 MB。是否可用取决于当前模型的视觉能力（image_in / video_in）。
Shell
| 工具 | 默认审批 | 说明 |
|---|---|---|
Bash | 需审批 | 执行 Shell 命令 |
PowerShell | 需审批 | 执行 PowerShell 命令（仅 Windows） |
Bash 是权限要求最严格的工具，也是功能最通用的工具。参数：
command（必填）：要执行的 Shell 命令cwd：工作目录timeout：超时时间（毫秒）；前台默认 60 秒、最长 5 分钟run_in_background：是否以后台任务运行；后台默认 10 分钟超时description：后台任务描述，run_in_background=true时必填disable_timeout：后台任务是否取消超时限制
前台模式会阻塞当前轮次，直到命令结束或超时；命令运行期间，界面会把 stdout 和 stderr 流式显示在正在运行的 Bash 工具卡片中。后台模式立即返回任务 ID，任务结束时自动通知 Agent。stdin 始终被关闭，交互式命令会立即收到 EOF。两阶段终止策略（SIGTERM → 5 秒宽限期 → SIGKILL）确保超时后进程可靠结束。Windows 上，Bash 工具通过 Git Bash 执行（不可用时给出可操作的指引并报错）；原生 Windows 命令由独立的 PowerShell 工具承接。
网络类
| 工具 | 默认审批 | 说明 |
|---|---|---|
WebSearch | 自动放行 | 网络搜索 |
FetchURL | 自动放行 | 获取指定 URL 的内容 |
WebSearch 接受 query（搜索词）。需要宿主提供搜索实现，未注入时不会出现在工具列表中。
FetchURL 接受单个 url 参数，返回页面内容。对 HTML 页面，宿主会提取正文而非返回完整 HTML；纯文本或 Markdown 页面直接透传。同样需要宿主注入实现。
Plan 模式
| 工具 | 默认审批 | 说明 |
|---|---|---|
EnterPlanMode | 自动放行 | 进入 Plan 模式 |
ExitPlanMode | 自动放行（需用户确认计划） | 退出 Plan 模式并提交计划 |
Plan 模式是一种受约束的工作状态：进入后 Write 与 Edit 只允许写入当前的计划文件，TaskStop 被完全拦截。其余工具（包括 Bash）仍按当前权限规则处理。
EnterPlanMode 不接受任何参数，进入成功后返回工作流指引及计划文件路径。
ExitPlanMode 读取当前计划文件内容，将计划呈现给用户审批后退出 Plan 模式。可选参数 options 允许 Agent 提供 1–3 个备选方案（每项含 label 与 description，label 最长 80 字符），供用户在审批时选择；label 不能重复，也不能使用 Approve、Reject、Reject and Exit、Revise 等保留词。
状态管理
| 工具 | 默认审批 | 说明 |
|---|---|---|
TodoList | 自动放行 | 管理任务待办列表 |
TodoList 在多步骤操作中维护一份可见的子任务列表，状态存储在 Agent 会话内。todos 参数接受一个数组，每项含 title 和 status（pending / in_progress / done）；省略 todos 则仅查询当前列表，传入空数组则清空列表。
协作类
协作类工具负责 Agent 间协作、用户交互和 Skill 调用。
| 工具 | 默认审批 | 说明 |
|---|---|---|
Agent | 自动放行 | 派生子 Agent 执行子任务 |
AgentSwarm | swarm mode 中自动放行，否则需审批 | 启动基于 item 的子 Agent，或恢复已有子 Agent |
AskUserQuestion | 自动放行 | 向用户提问以获取结构化输入 |
Skill | 自动放行 | 调用已注册的 inline Skill |
Agent 将子任务委托给子 Agent 执行。必填参数：prompt（完整任务描述）和 description（3–5 个词的简短说明）。可选参数：subagent_type（默认 coder）、resume（恢复已有 Agent 的 ID，与 subagent_type 互斥）和 run_in_background（默认 false）。Agent 任务使用固定 30 分钟超时。前台模式下父 Agent 等待子 Agent 完成再继续；后台模式立即返回任务 ID，完成时通过合成 User 消息自动回到主 Agent。多个前台 Agent 调用在同一步运行时，界面会合并展示，并为每个子 Agent 显示运行、等待、完成或失败状态以及已耗时长。子 Agent 体系细节见 Agent 与子 Agent。
AgentSwarm 可以从共享的 prompt_template 和 items 数组启动子 Agent，也可以通过 resume_agent_ids 恢复已有子 Agent，或在一次调用中同时使用两者。模板必须包含 占位符；每个 item 会替换该占位符，并启动一个新的子 Agent。传入 subagent_type 可以指定整个 swarm 中所有新启动的子 Agent 使用的 profile；省略时默认使用 coder。不传 resume_agent_ids 时，本工具要求至少 2 个 item；传入 resume_agent_ids 时，可以恢复 1 个或多个已有子 Agent。默认情况下，本工具每次调用最多支持 3 个子 Agent（这是 Rust 引擎相对 TS 引擎硬编码 128 的刻意偏差）；可通过 [subagent] maxSwarmItems 配置键调整或解除该上限，也可将 MIRRI_AGENT_SWARM_MAX_ITEMS（或别名 MIRRICODE_AGENT_SWARM_MAX_ITEMS）设为正整数以覆盖前两者——0 表示不限制，非法值将被忽略并告警。本工具会等待全部子 Agent 完成，并返回聚合报告。前台 swarm 会在界面上显示实时 Agent swarm 进度。若一次模型响应调用 AgentSwarm，该调用必须是该响应中的唯一工具调用；如需运行多个 swarm，应先调用一个 AgentSwarm 并等待结果，再调用下一个，若单个模板可以覆盖这些工作，也可以合并为一个 swarm。在 manual 权限模式下，未处于 swarm mode 时调用 AgentSwarm 会触发审批，除非已有权限规则允许；swarm mode 已开启时，AgentSwarm 本身会自动放行。权限规则只能按工具名 AgentSwarm 匹配，不支持 AgentSwarm(swarm) 这类参数模式。默认情况下，本工具会逐步提升并发且不设上限（立即启动 5 个子 Agent，之后每 700 毫秒再启动 1 个）；将 MIRRICODE_AGENT_SWARM_MAX_CONCURRENCY 设为正整数可限制该阶段同时运行的子 Agent 数量，不设置则表示不限制。若设置为非正整数的值，本次 AgentSwarm 调用会立即失败。
AskUserQuestion 以结构化多选题的形式向用户提问，适用于需要消歧或选择方案的场景。questions 参数接受 1–4 道题，每道题需提供 question（以 ? 结尾）、options（2–4 个选项，每项含 label 和 description）以及可选的 header（最多 12 字符）和 multi_select（默认 false）。系统自动附加"其他"选项。background 为 true 时启动后台问题任务并立即返回任务 ID。宿主未实现交互式提问能力时返回失败提示，Agent 应改为在文本回复中直接提问。
Skill 允许 Agent 主动调用已注册的 inline 类型 Skill。接受 skill（Skill 名称）和可选的 args（附加参数文本）。只有 type = "inline" 的 Skill 能通过此工具调用；disableModelInvocation: true 的 Skill 会被拒绝。嵌套调用深度上限 3 层。Skill 体系细节见 Agent Skills。
后台任务
后台任务工具用于管理通过 Bash、Agent 或 AskUserQuestion 启动的后台任务。任务进入终止状态时会自动把状态和已保存的输出路径送回 Agent；如需提前检查进度，使用 TaskOutput。
| 工具 | 默认审批 | 说明 |
|---|---|---|
TaskList | 自动放行 | 列出后台任务 |
TaskOutput | 自动放行 | 查看后台任务的输出 |
TaskStop | 需审批 | 停止正在运行的后台任务 |
TaskList 返回后台任务列表。可选参数 active_only（默认 true，仅列出运行中的任务）和 limit（默认 20，取值范围 1–100）。
TaskOutput 根据 task_id 返回任务状态与输出。内联预览最多包含最近 32 KB 的内容；完整日志保存在磁盘上，工具会一并返回 output_path 并提示通过 Read 分页读取。可选 block（默认 false）和 timeout（等待秒数，默认 30，取值范围 0–3600）参数可用于等待任务完成后再返回。
TaskStop 接受 task_id 和可选的 reason（默认 Stopped by TaskStop）。对已处于终止状态的任务也能安全调用。
定时任务
定时任务是对「之后再做一件事」的两种表达，Agent 各有一把工具：
- 定时器（
SetTimer）——在当前会话里延时回调一次。适合「10 分钟后帮我看下构建结果」这类会话题材的跟进。 - 定时任务（
CreateScheduledTask）——在所属工作区里建一个例行任务，可周期运行、有独立身份与运行历史。适合每日巡检、每周报表、部署监控等长期事项。
定时器无需审批；新的定时任务一律需要你在审批卡上确认。任务建好后可在设置里的「定时任务」页查看、编辑、暂停或删除。设置 MIRRICODE_DISABLE_CRON=1 可整体禁用这两个工具，详见环境变量。
| 工具 | 默认审批 | 说明 |
|---|---|---|
SetTimer | 自动放行 | 在当前会话中安排一次延时回调 |
CreateScheduledTask | 必需审批 | 在所属工作区创建一个定时任务 |
SetTimer 接受两个参数：delay_minutes（从现在起经过多少个整分钟，小于 1 分钟按 1 分钟计）和 message（到点时注入会话的文本——写成你希望那时收到的指令）。它只触发一次，触发后自动消失，会话里不需要再收拾。到点检测每 30 秒一轮，因此实际送达可能与请求的分钟略有出入；如果到点时本轮对话仍在进行，消息会等这一轮结束后再注入，错过的周期会合并为一次。
CreateScheduledTask 需要一个 cron（标准 5 段表达式：分 时 日 月 周）与一段 prompt（每次运行要执行的指令，审批卡上原样呈现给你确认）。可选参数：recurring（默认 true，每次触发后重新排程；false 表示只运行一次）、timezone（IANA 时区名，默认跟随本机）、max_fires（周期任务的触发次数上限，不填为不设限）、permission_mode（运行时的权限模式：manual / auto / yolo，与新建会话同款——manual 模式下运行遇到需要审批的操作会停下等你，运行记录显示「等待审批」，到该次运行的会话里批准或拒绝）、title（任务标题）、model（运行时使用的模型）、effort（思考深度）以及 reason（给审批卡看的说明）。每次调用都会弹出一张审批卡，用人话列出任务名、执行时间、工作区、模型、权限与执行内容，任何权限模式下都需要你批准。批准即创建，调用结果直接返回新任务的编号；拒绝则不会创建任何内容，Agent 会在这次调用的结果里看到你给的原因。
为避免所有用户在同一分钟触发，调度器会做确定性抖动：周期任务向后偏移 min(周期的 10%, 15 分钟)；一次性任务若恰好落在 :00 或 :30 则向前提前最多 90 秒。如果调度器错过了若干触发时刻（如笔记本合盖），唤醒后只会触发一次，prompt 会包裹在 <cron-fire> 信封里并附带 coalescedCount。周期任务存活超过 7 天后会以 stale="true" 做最后一次触发后自动删除。
「定时任务」页
除了让 Agent 代为排定，你也可以在网页端设置面板的「定时任务」页直接管理工作区的任务。
- 列表：两列卡片，每张卡片是标题、指示摘要与「周期规则 · 下次运行 · 运行次数」；点整张卡片进入详情。列表上方是状态筛选（全部 / 进行中 / 已暂停 / 失败），卡片本身不放状态徽章、也没有单独的操作按钮。
说明：新建与编辑表单目前呈现工作区、权限模式、模型与思考深度四项；创建接口同时仍接受旧姿态字段以兼容旧客户端。
- 新建：自上而下四块——任务标题；日程（结构化选择：每小时 / 每天 / 每个工作日 / 每周 / 每月 / 自定义，无需书写表达式，周期任务还可设触发次数上限）；预测时间轴；每次运行要执行的指示。底部一行依次是工作区、权限模式、模型、思考深度四个选择器，与新开会话时的选项同款，未改动则按工作区默认执行。
- 预测时间轴：显示「理论上次 → 下次 → 下下次」三个时刻，每点都标注时区。理论上次是推算值而非运行记录，用弱化样式并标「理论值」；真正跑过什么只看详情的「历史」页签。
- 详情：设置页签复用创建表单（预填后修改，任务身份与历史不变），历史页签查看运行记录；可以暂停与恢复，暂停期间错过的运行不会被补跑。
- 运行记录：历史页签里每次运行显示触发方式（定时 / 立即运行 / 排队接续）、比计划晚了多久、以及当前状态（含「等待审批」）。运行结果只有在回合真正产出内容时才记为成功。
自定义日程支持「每 N 天/周/月」的流逝间隔与结束日期（结束当天仍执行最后一次）；结束日期恰为首次运行日即为一次性任务。实际投递时刻相对计划时刻有防拥塞抖动（周期任务最多数分钟），表单与列表中显示的均为理想计划时刻。
下一步
- Agent 与子 Agent —
Agent工具的调度机制与上下文隔离 - Hooks — 在工具调用前后触发本地脚本
- 斜杠命令 — 输入框内置控制命令速查