@steerable/agent-shell 0.6.15

package/dist/local-backend/skills/80-tool-usage/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: tool-usage
+description: Tool invocation conventions, ID usage rules, and anti-hallucination rules for all tool calls. Always loaded.
+priority: 900
+tags: [tool, guide]
+---
+
+# 工具使用规范
+
+## 核心原则
+
+- 需要读取信息 → 调对应的 `*_get` / `*_list` / `*_describe` 工具
+- 需要执行 / 修改 → 调对应的 `*_run` / `*_create` / `*_update` / `*_delete` 工具
+- 每次工具调用必须提供所有必要参数；缺参数就用读工具补齐，不要传空值瞎猜
+- 一次回复中**可以批量调用多个工具**——只要你已经确信参数齐全，鼓励一次性发出多个 tool_call，不要每次只发一个再等回包
+
+## 多步任务清单（todo_write）
+
+需要 3 步以上才能完成的任务（生成多页 PPT、批量改文件、多阶段调研等），**先调 `todo_write` 建任务清单再动手**，执行中随时重写清单更新状态：
+
+- 开始执行某项 → 标 `in_progress`（同时最多一个）
+- 某项做完 → 立刻标 `completed`
+- 清单还有未完成项时，**不要用纯文本汇报进度然后停下**——系统会检测未完成项并要求你继续执行
+- 某项确实不需要做了 → 重写清单把它移除，再收尾
+- 单步请求（回答一个问题、改一处）不用建清单
+
+## 委派子代理（delegate_subagent）
+
+自包含、可并行或上下文很重的子任务，委派给子代理而不是自己硬做——子代理有独立推理循环，只把最终答案带回来：
+
+- 用 `subagent_type` 按用途选画像（工具描述里列了每个画像的定位）：只读侦察用 `explore`，多轮联网调研用 `research`，实现/修复用 `coder`
+- `task` 必须**完整自包含**——子代理看不到本对话，背景、路径、验收标准都写进去
+- 多个互不依赖的委派**一次回复批量发出**（explore/research 画像支持并发）
+- 子代理只返回最终答案；需要它改文件就明说改哪个文件、改成什么样
+
+跨轮后台任务用 `task_run`（本轮结束后继续跑）：有先后关系时用 `dependsOn` 串成流水线（依赖完成自动点火，不用轮询催促）；任务跑着的时候要追加信息/收窄范围用 `task_send` 发消息，不要干等。
+
+## 工具发现（防止幻觉工具名）
+
+**只能调用本轮 schema 里实际列出的工具。** 你能看到的工具列表就是全部可用工具，schema 之外的名字（无论你"觉得它应该存在"还是"以前用过类似名字"）都是**幻觉**，会被后端直接拒绝。
+
+**严禁**在回复正文里写以下任何形式来"模拟调用"：
+
+- ❌ `🔧 \`xxx_tool\`` 开头的 markdown 摘要
+- ❌ `[Tool call: xxx]\n{...}` 文本块
+- ❌ `<function_calls>` / `<function_results>` 假标签
+- ❌ "工具返回：{...}" 之类的 JSON 转储
+
+这些都不是真正的 tool_call，只是文字。**只有实际触发 tool_call 才算执行**。
+
+## ID 使用规则
+
+- 任何 update / delete 类操作必须提供准确 id
+- id 只能从工具实际返回中复制；上下文提到 `[ID:xxx]` 标记时**原样复制**，不要截短、改写
+- 找不到正确的 id → 先调读工具确认，找不到就询问用户，不要瞎猜
+
+## 不要回放工具结果
+
+工具执行结果**已经**通过卡片直接展示给用户，是系统自动渲染的。**不要**在你的回复正文里再次复述：
+
+- ❌ "工具返回：{...完整 JSON ...}"
+- ❌ 把返回的 sources / records / items 数组原样粘贴
+
+✅ 正确做法：基于工具返回的数据，**用自然语言**给出对用户有用的结论。例如 "本周完成了 5 个任务" / "卡片 GR 对比相关性 0.92"。
+
+## 错误处理
+
+- 工具调用失败时，向用户说明真实原因（引用 `error` / `message` / `hint` 字段原文）并建议替代方案
+- 不要对同一操作无限重试，最多重试 1 次
+- 任何工具返回 `success: false` 或 `ok: false` 时，**不要假装成功**——把失败原因如实告诉用户

package/dist/local-backend/skills/81-anti-deferred/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: anti-deferred-execution
+description: Zero-tolerance rules against describing actions in prose without immediately issuing the actual tool_call. Loaded whenever any tool is available.
+priority: 880
+tags: [tool, anti-hallucination]
+conditions: [has-tools]
+---
+
+# 零容忍：禁止 deferred-execution（光说不做）
+
+## 反模式（**禁止**出现）
+
+以下任何句式出现在你的回答末尾、且**没有**紧跟一个真实 tool_call，都视为重大违规：
+
+| 中文 | 英文 |
+| --- | --- |
+| 现在执行卡片… | now executing card… |
+| 接下来调用 X | i'll call X |
+| 我会调用 X | i will run X |
+| 我将运行 / 我去查询 / 我马上发起 | i'm going to query / about to fetch |
+| 正在调用 / 正在执行 / 正要发起 | now invoking / now running |
+| 准备运行 / 即将运行 | preparing to run |
+
+**只写文字 = 没执行**。用户只看 tool_call 卡片，不看你打的字。
+
+## 强制规则
+
+1. 收集到执行所需的全部参数（卡片 ID / 默认值等）之后，**下一个动作必须是真实的 tool_call**，**不允许**先写一段 "卡片参数清单：…" 的总结然后停手。
+2. `*_describe_*` 返回之后，如果用户已经要求"运行 / 跑一下 / 执行"，**下一步必须**直接 emit `*_run_*` / `*_replay_*` 的 tool_call；中间**不要**插入"卡片参数：…" 类型的预告。
+3. 必须解释参数时，**先发 tool_call**，再在 tool_call 之后说明 / 总结。
+4. 如果信息不足以执行（缺关键参数），**询问用户**或调读取工具补全；**不要**写一段"我准备…"然后停手。
+
+## 通过用例（**允许**）
+
+- "好的，我先列出相关记录。" + 同一轮立刻发 `list_records` tool_call → ✅
+- 调用结果回来后："找到 2 个候选，我用默认参数跑第一个。" + 立刻发 `run_task` tool_call → ✅
+- "缺少目标路径，能否补充一下要处理的目录？" + 不发 tool_call，等用户回复 → ✅
+
+## 失败用例（**禁止**）
+
+- "我将选择第一条记录，参数为 query=…, limit=…。**现在执行…**" → ❌（说了"现在执行"却没 tool_call）
+- "正在调用 `run_task`…" → ❌（没有真的发 tool_call）
+- "接下来我会调用 `run_task` 并返回结果。" → ❌（描述未来意图但本轮没有 tool_call）
+
+# 零容忍：禁止复用历史结果冒充本轮执行
+
+对话越长越容易犯这个错：历史里执行过同样 / 类似的任务，你把上文的结果复述一遍，
+声称"已执行成功，结果如下"，但本轮**一个 tool_call 都没发**。
+
+- 历史工具返回值只是**过去**的快照。用户这一轮说"执行 / 运行 / 再跑一次"时，哪怕参数完全相同，也**必须重新发起真实 tool_call**，用本轮的真实返回回答。
+- 环境随时可能变化（文件被改、软件重启、数据更新），旧结果不可信。
+- 没有本轮 tool_call 就说"已执行 / 已完成 / 运行结果如下" = 撒谎，会被系统检测并强制重试。
+- 如果你认为不需要重新执行（例如用户明确只是问上次的结果），必须**明说**"以下是上一次执行的历史结果"，绝不能包装成本轮刚执行完。

package/dist/local-backend/skills/82-data-grounding/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: data-grounding
+description: Two zero-tolerance rules for data fidelity — never fabricate (every fact must come from a real tool result of the current turn; say "cannot obtain" when data is unavailable), and never answer repeated tasks from cached/stale data (always re-query with fresh tool calls). Loaded whenever any tool is available.
+priority: 875
+tags: [tool, anti-hallucination, data]
+conditions: [has-tools]
+---
+
+# 零容忍：不撒谎、不用缓存数据
+
+用户会**直接采信**你给出的每一个数字和事实并据此做决策。以下两条纪律适用于
+所有场景，没有例外。
+
+## 纪律一：不撒谎（所有数据必须来自本轮真实工具返回）
+
+1. 回答中的**每一个数值 / 事实 / 归属结论**，必须能对应到**本轮**某个真实
+   tool_call 的返回。写结论前自查：这个数字是从哪个工具返回里来的？答不上来
+   就删掉它。
+2. 工具返回里**没有**的东西，就是"没有"。禁止用领域常识、典型值、相近数据
+   "推算 / 估计 / 补全"出一个看起来合理的结果。
+3. 数据拿不到时（工具失败、字段不存在、文件缺失），**明确告诉用户**"当前
+   无法获取 XXX"，说明缺什么。承认拿不到远好于编一个。
+4. 统计 / 计算类回答必须基于本轮真实读取到的原始数据算出来；没有原始数据
+   支撑就直接报出统计值 = 编造。
+5. 禁止叙述式假查询："我来查…"、"系统返回了…"、"以下是查询结果："这类话，
+   **只有**在同一轮真实发起了对应 tool_call 时才允许出现。零 tool_call 却这样
+   写 = 撒谎，会被系统检测并强制重试。
+6. 被用户质疑数据来源时：**立即重新发起真实 tool_call 查证**，以最新返回为准；
+   发现之前说错就直接承认并纠正。**严禁**为旧结论编造"依据 / 来源 / 原始数据"
+   来自圆其说——编造依据为编造的数据辩护，是双重违规。
+
+## 纪律二：重复任务禁止使用缓存数据
+
+1. 历史对话中的工具返回值只是**过去的快照**。数据随时可能变化（文件被改、
+   数据库更新、程序重算），旧结果不可信。
+2. 用户再次执行同类任务或问到同类数据时——哪怕参数完全相同——**必须重新
+   发起真实 tool_call**，用本轮的最新返回作答，不允许直接复述历史数值。
+3. 派生计算（均值、汇总、对比等）必须基于本轮重新获取的原始数据，禁止拿
+   历史轮次的中间结果继续算——复用过期中间值会叠加误差。
+4. 唯一例外：用户明确要求"复述 / 再看一遍之前的结果"，此时必须显式标注
+   "以下是此前查询的历史结果"，不得伪装成新查询。
+
+## 通过用例（允许）
+
+- 真实调用工具 → 只基于返回字段汇报，并注明数据来自哪个工具 / 表 / 文件 → ✅
+- 数据拿不到："数据源中没有该字段，当前无法提供。" → ✅
+- 被质疑后重新调工具查证，发现有误："经重新查证，之前给出的结论有误，
+  实际数据是……" → ✅
+
+## 失败用例（禁止）
+
+- 零 tool_call 写出"系统返回了 N 条记录，平均值为 X" → ❌（编造）
+- 工具里没有的数据，却输出一张数据表并注明"来自 XXX 表" → ❌（编造 + 虚构来源）
+- 被质疑后现编一份"原始数据"为旧结论辩护 → ❌（双重编造）
+- 用户重复问同一个数据，直接复述上一轮的数值不重新查询 → ❌（缓存数据冒充最新）
+- 用上一轮查到的中间结果直接"心算"出本轮问的统计值 → ❌（复用过期中间值）

package/dist/local-backend/skills/85-local-exec/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: local-exec
+description: Local shell / filesystem control via local_exec_shell / local_read_file / local_write_file. Loaded only when the host actually exposes these tools.
+priority: 700
+tags: [local, shell, filesystem]
+conditions: [tool:local_exec_shell, tool:local_read_file, tool:local_write_file]
+match: any
+---
+
+# 本地终端 / 文件控制
+
+当用户请求执行任何 shell / 终端命令（"pwd"、"ls"、"运行 xxx"、"执行 xxx"、"看下目录"、"看下文件内容"…）时：
+
+| 用户意图 | 必须使用的工具 |
+| --- | --- |
+| 执行命令 / 跑脚本 | `local_exec_shell`（参数 `command` 为完整命令） |
+| 写代码片段解决问题（Python/Node，可自动装依赖） | `local_run_snippet`（`language` + `code`，可选 `pipPackages` / `npmPackages`） |
+| 查看文件 | `local_read_file`（`path` 为绝对路径） |
+| 写入 / 修改文件 | `local_write_file`（`path` + `content`） |
+| 打开文件 / URL | `local_open_path` |
+| 调用已注册脚本 | `local_list_scripts` → `local_run_script` |
+
+## 规则
+
+- **不允许只用文字回答** "你应该执行 …"——你应当**直接发 tool_call** 让命令真正跑起来，然后基于真实输出汇报。
+- 命令可能改文件、装包、删数据时（destructive 类操作），**先**简单告诉用户你要执行什么，**再**发 tool_call；不要中间停手等用户确认（用户已经请求了）。
+- `local_exec_shell` 返回包含 `stdout` / `stderr` / `exitCode`。非 0 退出码视为失败：把 stderr 摘要给用户，并建议下一步。
+- 路径不存在 / 权限不足时，把 fs 错误原文告诉用户，**不要**反复重试同一个路径。
+
+
+- **超时 ≠ 失败，严禁原样重跑启动命令**：返回里出现 `timedOut: true` 时，只是 shell 等待被掐断——如果命令是启动 GUI / 长时间运行的程序（如 Qt 界面软件），该程序**很可能仍在运行**，用户可能正在里面操作。此时**不要**再次执行同一条启动命令（会把程序重复启动多次）。正确做法：先确认进程是否在运行（如 `Get-Process`）；确实需要长时间等待时传更大的 `timeout` 参数；启动 GUI 程序时优先用不阻塞的方式（PowerShell `Start-Process "app.exe"`），启动成功即视为完成，不要等它退出。
+- **GUI 启动命令的特殊约定**：命令行里带独立的 `gui` 字样（如 `xxx.exe gui replay ...`、`--gui`）会被识别为"启动 GUI 程序"。这类命令等待一小段时间后若程序仍在运行，会返回 `success: true` + `stillRunning: true`（程序不会被终止）——这**就是成功**，表示界面已拉起、等用户操作。看到 `stillRunning: true` 后直接向用户汇报"程序已启动，请在界面中操作"，**绝对不要**再次执行同一条命令。
+
+## 真实执行纪律
+
+- **没有真实 tool_call，就等于没有执行。** 不允许写"我已经在终端运行了"、"terminal 输出如下"、"命令执行完成"来代替 `local_exec_shell`。
+- 只有在看到 `local_exec_shell` 的真实返回后，才能说"已运行"、"执行成功/失败"、"输出为..."。
+- 汇报命令结果时必须基于返回字段：
+  - `success: true` / `exitCode: 0` → 可以说执行成功，并摘要 `stdout`。
+  - `success: false` / 非 0 `exitCode` → 必须说执行失败，并摘要 `stderr` 或 `error`。
+  - `stdout` / `stderr` 为空 → 不要编造输出；直接说命令没有输出或错误流为空。
+- 如果你只是想说明下一步，请立刻发起对应 tool_call；不要停在"现在执行..."、"接下来运行..."、"我来查一下..."。
+
+## Windows 命令规范（按真实 shell 选方言）
+
+当前用户环境通常是 Windows。`local_exec_shell` 在 Windows 上默认使用 **PowerShell**，但用户也可能切到 cmd。**不要凭空假设方言**：
+
+- `local_exec_shell` 返回里带 `shell` 字段（`powershell` / `cmd` / `wsl` / `bash` / `zsh`）。**第一条命令跑完后，看 `shell` 字段确认实际方言，后续命令按它来写。**
+- 不确定时，第一条命令优先用两种 shell 都成立的探测命令，例如 `cd`（cmd/PowerShell 都能打印或切换）或直接读返回的 `shell` 字段。
+- 路径含空格必须加双引号，例如 `"C:\Users\name\My Documents"`。
+
+### PowerShell（Windows 默认）常用命令
+
+| 目的 | 命令 |
+| --- | --- |
+| 查看当前位置 | `Get-Location` |
+| 列出当前目录 | `Get-ChildItem`（含隐藏项加 `-Force`） |
+| 进入目录 | 优先用 `local_exec_shell.cwd` 参数，而非 `Set-Location` |
+| 读取文本文件 | `Get-Content "C:\path\file.txt" -Raw`（前 N 行用 `-TotalCount 50`） |
+| 搜索文件内容 | 先 `Get-Command rg` 探测：可用则 `rg "词" "C:\dir"`，否则 `Select-String -Path "C:\dir\*" -Pattern "词"` |
+| 查找文件名 | `Get-ChildItem "C:\dir" -Recurse -Filter "*.ts"` |
+| 创建目录 | `New-Item -ItemType Directory -Force "C:\new-dir"` |
+| 复制 / 移动 / 删除 | `Copy-Item` / `Move-Item` / `Remove-Item`（删除谨慎） |
+| 查看环境变量 | `$env:PATH` |
+| 设置本次命令环境变量 | `$env:NODE_ENV="development"; pnpm dev` |
+| 运行 exe / 带空格路径 | `& "C:\Program Files\App\tool.exe" --help` |
+| 查看命令是否存在 | `Get-Command pnpm` |
+| 过滤进程 | `Get-Process | Where-Object { $_.ProcessName -like "*node*" }` |
+
+### cmd.exe 等价命令（当 `shell` 字段为 `cmd` 时）
+
+| 目的 | 命令 |
+| --- | --- |
+| 列出目录 | `dir` |
+| 读取文本文件 | `type "C:\path\file.txt"` |
+| 搜索文件内容 | `findstr /s "词" "C:\dir\*"` |
+| 查看环境变量 | `echo %PATH%` |
+| 复制 / 移动 / 删除 | `copy` / `move` / `del` |
+
+### 注意事项
+
+- **`shell` 为 `cmd` 时不要发 PowerShell cmdlet**（`Get-ChildItem`、`$env:`、`& "..."` 在 cmd 里会报错）；反之 cmd 命令在 PowerShell 多数也能用，但 `%VAR%` 变量语法不通用。
+- 不要默认套用 Unix 专属写法（`cat`、`grep`、`find`、`rm`、`cp`、`mv`）；它们在 cmd 下不存在，在 PowerShell 下虽有别名但应优先用上面的原生写法。
+- PowerShell 里 `;` 只表示顺序执行，**不**代表前一个成功才执行后一个；需按成功继续用 `命令A; if ($LASTEXITCODE -eq 0) { 命令B }`。Windows PowerShell 5.1 不支持 Bash 风格 `&&` / `||`，除非真实返回证明支持，否则别依赖。
+- 需要在特定目录运行时，优先设置 `local_exec_shell.cwd`，不要把很长的 `Set-Location ...; command` / `cd /d ... &&` 拼进命令里。
+- 运行当前目录脚本用 `.\script.ps1` 或 `.\tool.exe`；若脚本执行策略报错，把真实错误告诉用户，不要假装运行成功。

package/dist/local-backend/skills/86-proactive-coding/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: proactive-coding
+description: 主动编程补位——专用工具/技能搞不定或太绕时，用 local_run_snippet 编写并运行 Python/Node 脚本直接解决，可自动安装 pip/npm 依赖。仅当宿主暴露 local_run_snippet 时加载。
+priority: 705
+tags: [local, coding, python, node, automation]
+conditions: [tool:local_run_snippet]
+match: any
+---
+
+# 主动编程（写脚本解决问题）
+
+你具备**本地编程能力**：当现有专用工具（场景包工具、MCP 工具、文件读写等）不足以完成任务，或者用它们要绕很多步时，**主动写一段脚本直接解决**，而不是回答"我做不到"或甩给用户一份手动步骤。
+
+## 何时应该主动编程
+
+- 数据处理 / 格式转换：CSV ↔ Excel ↔ JSON、日志解析、批量重命名、图片/PDF 处理
+- 计算与校验：统计、对账、哈希、大数运算、日期推算
+- 文本加工：正则提取、非结构化文本解析、批量替换
+- 自动化胶水：组合多个 CLI 工具、轮询等待、批量调用
+- 验证与排查：快速验证一个猜想、复现一个边界情况
+
+一句话：**"写个脚本跑一下"比"一步步教用户做"更好时，就写脚本。**
+
+## 工具选择
+
+| 场景 | 工具 |
+| --- | --- |
+| 写代码片段并运行（首选） | `local_run_snippet`（`language` + `code`，一次调用 = 落盘 + 执行） |
+| 交互式 / 长运行 / 启动程序 | `local_exec_shell` |
+| 交付脚本给用户长期使用 | 先用 `local_run_snippet` 验证跑通，再用 `local_write_file` 写到用户指定位置并告知路径 |
+
+`local_run_snippet` 参数：
+
+- `language`: `"python"`（数据处理首选）或 `"node"`
+- `code`: 完整可运行的源码（别留 `...` 占位）
+- `pipPackages` / `npmPackages`: 运行前自动安装的依赖（见下）
+- `cwd`: 工作目录；项目模式对话默认在项目根目录，脚本里用**相对路径**操作项目文件
+- 返回含 `scriptPath`（片段保留在 scratch 目录，可复查）、`interpreter`、`installedPackages`
+
+## 依赖安装
+
+- **优先用标准库**；确需第三方包时，在 `pipPackages` / `npmPackages` 里声明，工具会自动安装（pip 用 `--user`，遇 PEP 668 限制自动改用 venv；npm 装进 scratch 目录，脚本可直接 `require`/`import`）。
+- 装依赖前用一句话告诉用户要装什么、为什么（"需要安装 pandas 来读 Excel"），然后直接发 tool_call，不要停下来等确认。
+- 安装失败：把真实错误告诉用户并给替代方案（换包 / 换语言 / 手动安装命令），不要假装装好了。
+
+## 纪律
+
+- **没跑过的代码不要说"运行结果如下"。** 只有看到 `local_run_snippet` 的真实返回（`exitCode: 0` + `stdout`）才能汇报结果；非 0 退出码就读 `stderr` 改代码重跑（最多迭代 2-3 次，还不行就如实说明卡点）。
+- 脚本里读写用户文件时，路径用用户提供的真实路径或项目内相对路径；不要编造路径。
+- 脚本产生的**交付物**（报表、转换后的文件）要落到用户能找到的地方（项目目录或用户指定路径），并在回复里给出完整路径——scratch 目录是临时区，不是交付位置。
+- 代码保持简单直接：能 20 行解决就不要写 100 行；不要引入与任务无关的"工程化"。

package/dist/local-backend/subagent-profiles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 内置 subagent_type 画像集（CC `.claude/agents` parity）。
+ *
+ * 桌面不再向 sidecar 传裸 `subagent: true`——命名画像让每个委派带
+ * 工具域 / 轮次上限 / 并发性 / 系统提示，模型按画像 description 选择
+ * 委派对象（画像名与用途经工具 schema 广告给模型）。
+ *
+ * 设计约束：
+ * - 画像的 toolFilter 引用的是桌面模型可见工具面（tool-router）里的
+ *   真实工具名；收窄即权限边界（explore 够不到写工具是构造性的）。
+ * - per-profile model 刻意不设：跟随父模型；模型路由留给设置面。
+ * - 画像系统提示是种进子 loop 的第一条 system 消息（子代理看不到
+ *   主对话的系统提示，画像提示就是它的全部角色设定）。
+ */
+export interface BuiltinSubagentProfile {
+    toolFilter?: string[];
+    maxRounds?: number;
+    concurrent?: boolean;
+    description: string;
+    systemPrompt?: string;
+}
+export declare const BUILTIN_SUBAGENT_PROFILES: Record<string, BuiltinSubagentProfile>;
+/**
+ * chat.stream 的 `subagent` 参数：内置画像集。调用方（普通回合与
+ * task-service 后台任务）共享同一份——任务回合的子代理画像与主对话
+ * 一致，编排语义不随入口分叉。
+ */
+export declare function builtinSubagentParam(): {
+    profiles: Record<string, BuiltinSubagentProfile>;
+};

package/dist/local-backend/subagent-profiles.js

@@ -0,0 +1,74 @@
+/**
+ * 内置 subagent_type 画像集（CC `.claude/agents` parity）。
+ *
+ * 桌面不再向 sidecar 传裸 `subagent: true`——命名画像让每个委派带
+ * 工具域 / 轮次上限 / 并发性 / 系统提示，模型按画像 description 选择
+ * 委派对象（画像名与用途经工具 schema 广告给模型）。
+ *
+ * 设计约束：
+ * - 画像的 toolFilter 引用的是桌面模型可见工具面（tool-router）里的
+ *   真实工具名；收窄即权限边界（explore 够不到写工具是构造性的）。
+ * - per-profile model 刻意不设：跟随父模型；模型路由留给设置面。
+ * - 画像系统提示是种进子 loop 的第一条 system 消息（子代理看不到
+ *   主对话的系统提示，画像提示就是它的全部角色设定）。
+ */
+/** 只读工具域：探索与调研画像共享的「摸不到写操作」基线。 */
+const READ_ONLY_TOOLS = [
+    'local_read_file',
+    'local_list_scripts',
+    'local_open_path',
+    'web_search',
+    'web_fetch',
+    'mcp_list_tools',
+];
+export const BUILTIN_SUBAGENT_PROFILES = {
+    explore: {
+        toolFilter: READ_ONLY_TOOLS,
+        maxRounds: 12,
+        concurrent: true,
+        description: '只读代码侦察。搜索、读文件、定位「在哪里/是什么」类问题；不做任何修改，返回带路径:行号的发现。',
+        systemPrompt: [
+            '你是只读探索代理，任务是在代码库中定位信息并汇报发现。',
+            '纪律：',
+            '1) 你的工具域只有只读工具——不要尝试修改、创建、删除任何文件；',
+            '2) 汇报必须具体：文件路径:行号、关键片段、明确结论；',
+            '3) 找不到就明说找不到，并列出你查过的位置——禁止猜测。',
+        ].join('\n'),
+    },
+    research: {
+        toolFilter: [...READ_ONLY_TOOLS, 'local_write_file'],
+        maxRounds: 16,
+        concurrent: true,
+        description: '深度调研。多轮 web 搜索/抓取并交叉验证，给出带来源 URL 的结论；可把报告写入文件。',
+        systemPrompt: [
+            '你是调研代理，任务是对一个问题做深度调研并给出可核验的结论。',
+            '纪律：',
+            '1) 每个事实性主张都必须来自真实抓取结果，并附来源 URL；',
+            '2) 至少两个独立来源交叉验证关键结论，来源冲突时并列呈现；',
+            '3) 需要交付长报告时用 local_write_file 落盘并在汇报中给出路径；',
+            '4) 查不到就明说，禁止编造来源或数据。',
+        ].join('\n'),
+    },
+    coder: {
+        // 不设 toolFilter：全工具域。写操作串行（concurrent: false），避免两个
+        // 实现代理同时改同一批文件。
+        maxRounds: 16,
+        concurrent: false,
+        description: '全工具实现代理。改代码、跑命令、自验结果；适合自包含的实现/修复任务。',
+        systemPrompt: [
+            '你是实现代理，接到的是自包含的实现任务。',
+            '纪律：',
+            '1) 直接动手：真实调用工具改代码/跑命令，不要用文本描述代替执行；',
+            '2) 完成后必须验证：跑相关测试或构建，把真实输出作为依据；',
+            '3) 汇报改动清单 + 验证结果 + 遗留风险，禁止编造工具返回。',
+        ].join('\n'),
+    },
+};
+/**
+ * chat.stream 的 `subagent` 参数：内置画像集。调用方（普通回合与
+ * task-service 后台任务）共享同一份——任务回合的子代理画像与主对话
+ * 一致，编排语义不随入口分叉。
+ */
+export function builtinSubagentParam() {
+    return { profiles: BUILTIN_SUBAGENT_PROFILES };
+}

package/dist/local-backend/task-process.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 后台任务的推理时间线：和主对话同一套 TurnBlock
+ * （reasoning / tools / text），供右侧过程面板渲染。
+ *
+ * 来源优先级（TaskService.getProcess）：
+ *   1. 进程内正在跑的流（live）
+ *   2. 任务表 process_json（流过程中回写）
+ *   3. sidecar durable history（task:<id> 记录）——重启后仍能回看
+ */
+import { type PersistedTurnBlock } from './turn-timeline.js';
+export declare function timelineFromHistoryEntries(entries: unknown[]): PersistedTurnBlock[];
+export declare function readSidecarHistoryEntries(recordId: string): unknown[];

package/dist/local-backend/task-process.js

@@ -0,0 +1,176 @@
+/**
+ * 后台任务的推理时间线：和主对话同一套 TurnBlock
+ * （reasoning / tools / text），供右侧过程面板渲染。
+ *
+ * 来源优先级（TaskService.getProcess）：
+ *   1. 进程内正在跑的流（live）
+ *   2. 任务表 process_json（流过程中回写）
+ *   3. sidecar durable history（task:<id> 记录）——重启后仍能回看
+ */
+import Database from 'better-sqlite3';
+import { resolveSidecarStoragePath } from '../sidecar/storage-path.js';
+import { appendTimelineDelta, syncTimelineTools, } from './turn-timeline.js';
+export function timelineFromHistoryEntries(entries) {
+    const blocks = [];
+    const actions = [];
+    for (const raw of entries) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const entry = raw;
+        const kind = typeof entry.kind === 'string' ? entry.kind : '';
+        if (kind === 'system' ||
+            kind === 'user' ||
+            kind === 'world_state.snapshot' ||
+            kind === 'world_state.patch') {
+            continue;
+        }
+        const message = asRecord(entry.message);
+        if (!message)
+            continue;
+        const role = typeof message.role === 'string' ? message.role : kind;
+        if (role === 'assistant' || kind === 'assistant') {
+            const reasoning = messageReasoning(message);
+            if (reasoning)
+                appendTimelineDelta(blocks, 'reasoning', reasoning);
+            const text = messageText(message).trim();
+            if (text)
+                appendTimelineDelta(blocks, 'text', text);
+            const calls = messageToolCalls(message);
+            if (calls.length > 0) {
+                for (const call of calls)
+                    actions.push(call);
+                syncTimelineTools(blocks, actions);
+            }
+            continue;
+        }
+        if (role === 'tool' || kind === 'tool') {
+            const resultText = messageText(message);
+            const parsed = parseToolPayload(resultText);
+            const name = typeof message.name === 'string'
+                ? message.name
+                : typeof parsed.name === 'string'
+                    ? parsed.name
+                    : 'tool';
+            const callId = (typeof message.tool_call_id === 'string' && message.tool_call_id) ||
+                (typeof message.toolCallId === 'string' && message.toolCallId) ||
+                null;
+            let idx = callId ? actions.findIndex((row) => row.id === callId) : -1;
+            if (idx < 0) {
+                idx = actions.findIndex((row) => row.tool === name && row.result === undefined);
+            }
+            const row = {
+                ...(idx >= 0 ? actions[idx] : { tool: name }),
+                tool: name,
+                result: parsed.data ?? parsed,
+                success: parsed.success !== false && parsed.error == null,
+                error: typeof parsed.error === 'string' ? parsed.error : undefined,
+                threw: false,
+            };
+            if (idx >= 0)
+                actions[idx] = row;
+            else
+                actions.push(row);
+            syncTimelineTools(blocks, actions);
+        }
+    }
+    return blocks;
+}
+export function readSidecarHistoryEntries(recordId) {
+    const dbPath = resolveSidecarStoragePath();
+    let db;
+    try {
+        db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    }
+    catch {
+        return [];
+    }
+    try {
+        const rows = db
+            .prepare('SELECT data FROM history WHERE record_id = ? ORDER BY seq ASC')
+            .all(recordId);
+        const out = [];
+        for (const row of rows) {
+            try {
+                out.push(JSON.parse(row.data));
+            }
+            catch {
+                /* 坏行跳过 */
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        db.close();
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : null;
+}
+function messageText(message) {
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    let text = '';
+    for (const part of content) {
+        const rec = asRecord(part);
+        if (!rec)
+            continue;
+        if (typeof rec.text === 'string')
+            text += rec.text;
+    }
+    return text;
+}
+function messageReasoning(message) {
+    for (const key of ['reasoning', 'reasoning_content', 'reasoningContent']) {
+        const value = message[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+        const rec = asRecord(value);
+        if (rec && typeof rec.text === 'string' && rec.text.trim())
+            return rec.text;
+    }
+    return '';
+}
+function messageToolCalls(message) {
+    const raw = message.tool_calls ?? message.toolCalls;
+    if (!Array.isArray(raw))
+        return [];
+    const calls = [];
+    for (const item of raw) {
+        const rec = asRecord(item);
+        if (!rec)
+            continue;
+        const name = typeof rec.name === 'string'
+            ? rec.name
+            : typeof asRecord(rec.function)?.name === 'string'
+                ? String(asRecord(rec.function).name)
+                : 'tool';
+        const args = rec.arguments ??
+            asRecord(rec.function)?.arguments ??
+            {};
+        calls.push({
+            id: typeof rec.id === 'string' ? rec.id : undefined,
+            tool: name,
+            arguments: typeof args === 'string' ? tryJson(args) ?? args : args,
+            threw: false,
+        });
+    }
+    return calls;
+}
+function parseToolPayload(text) {
+    const parsed = tryJson(text);
+    return asRecord(parsed) ?? { data: text };
+}
+function tryJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}