@researai/deepscientist 1.5.0 → 1.5.1

package/docs/zh/03_QQ_CONNECTOR_GUIDE.md

@@ -0,0 +1,324 @@
+# 03 QQ 连接器指南：如何用 QQ 与 DeepScientist 沟通
+
+本文说明如何通过 QQ 与 DeepScientist 对话，以及如何在 DeepScientist 的 `Settings` 页面完成 QQ connector 配置。
+
+适用范围：
+
+- 当前 DeepScientist 内置 QQ 官方 Gateway 直连方案
+- 不需要公网 callback URL
+- 不需要 `relay_url`
+- 不需要额外安装 QQ 插件
+
+如果你此前参考过 OpenClaw / NanoClaw 一类的文章，请特别注意：DeepScientist 的 QQ 接入方式已经内置在运行时里，配置入口是 `Settings > Connectors > QQ`，而不是命令行安装插件。
+
+## 1. 你最终会得到什么
+
+完成本文档后，你应该可以做到：
+
+- 用 QQ 私聊 DeepScientist
+- 让 QQ 自动绑定到当前最新 quest
+- 在 QQ 中使用 `/new`、`/use latest`、`/status` 等命令
+- 在 `Settings` 页面看到自动检测到的 `openid`
+- 从 `Settings` 页面执行非破坏性的连接测试
+
+### 部署前检查清单
+
+开始前，建议先确认下面几项：
+
+- DeepScientist 已经成功安装，并且 daemon / web UI 正在运行
+- 你可以正常打开 `Settings > Connectors`
+- 你已经准备好 QQ 机器人的 `AppID` 和 `AppSecret`
+- 你有一个真实的 QQ 账号可以主动给机器人发送第一条私聊消息
+- 如果你修改过 QQ 配置，`Restart gateway on config change` 建议保持开启
+
+如果上面任意一项还没有满足，先补齐，再继续下面的配置流程，会省很多排查时间。
+
+## 2. 注册 QQ 机器人
+
+这一部分参考腾讯云开发者社区文章《OpenClaw 接入 QQ 机器人》中的注册流程与截图：
+
+- 原文链接：https://cloud.tencent.com/developer/article/2635190
+- QQ Bot 官方平台：https://bot.q.qq.com/
+
+建议以 QQ Bot 官方平台为准进行创建；下面的截图用于帮助你快速识别页面。
+
+### 2.1 打开机器人注册入口
+
+优先使用官方平台：
+
+```text
+https://bot.q.qq.com/
+```
+
+腾讯云文章中给出的快速入口也可以作为参考：
+
+```text
+https://q.qq.com/qqbot/openclaw/login.html
+```
+
+![QQ 机器人注册入口](../images/qq/tencent-cloud-qq-register.png)
+
+### 2.2 登录并创建机器人
+
+1. 使用 QQ 扫码登录。
+2. 创建一个新的 QQ 机器人。
+3. 按页面提示完成机器人的基础信息配置。
+
+### 2.3 立刻保存 `AppID` 和 `AppSecret`
+
+创建成功后，请立即记录下面两项：
+
+| 字段 | 说明 | 是否必填到 DeepScientist |
+| --- | --- | --- |
+| `AppID` | 机器人唯一标识 | 必填 |
+| `AppSecret` | 调用 QQ Bot API 的密钥 | 必填 |
+
+重要易错点：
+
+- `AppSecret` 往往只在创建或重置时显示一次。
+- 如果你没有保存 `AppSecret`，后续通常只能去控制台重置。
+- DeepScientist 只需要这两个凭据即可启动 QQ 官方 Gateway 直连。
+
+## 3. 在 DeepScientist 里，不需要做什么
+
+如果你是从 OpenClaw 相关文章迁移过来的，这一节很重要。
+
+在 DeepScientist 中，下面这些步骤都不需要做：
+
+- 不需要安装 `@sliverp/qqbot`
+- 不需要执行 `openclaw channels add ...`
+- 不需要配置公网 callback URL
+- 不需要配置 `relay_url`
+- 不需要在第一次联通前手动填写 `openid`
+
+DeepScientist 当前的 QQ 路径是：
+
+- 固定 `transport: gateway_direct`
+- 直接使用 `app_id + app_secret`
+- 首次私聊后自动检测并保存 `openid`
+
+## 4. 在 Settings 页面配置 QQ
+
+打开：
+
+- [Settings > Connectors > QQ](/settings/connectors#connector-qq)
+
+进入后会直接定位到 `QQ` 配置卡片。当前页面按步骤分成：
+
+- `#connector-qq-step-credentials`：填写 `App ID` 与 `App Secret`
+- `#connector-qq-step-bind`：保存后，提示你先从 QQ 发送第一条私聊消息
+- `#connector-qq-step-success`：OpenID 自动检测成功后的确认区域
+- `#connector-qq-step-advanced`：高级设置与里程碑投递开关
+
+### 4.1 建议按这个顺序填写
+
+| 字段 | 如何填写 | 建议 |
+| --- | --- | --- |
+| `Enabled` | 打开 | 必开 |
+| `Transport` | 保持 `gateway_direct` | 固定值，不需要改 |
+| `App ID` | 填 QQ 机器人后台拿到的 `AppID` | 必填 |
+| `App secret` | 填 QQ 机器人后台拿到的 `AppSecret` | 必填 |
+| `Detected OpenID` | 先留空 | 第一次私聊后自动填充 |
+
+其余高级项例如群内 @ 规则、命令前缀、自动绑定、里程碑投递，都放在 `#connector-qq-step-advanced` 里。当前默认是“里程碑投递全部开启”，只有你想减少外发内容时才需要手动关闭。
+
+### 4.2 推荐保存前先看清楚的几点
+
+- QQ 不需要 `public_callback_url`
+- QQ 不需要 `relay_url`
+- `Detected OpenID` 不是一开始就要填的字段
+- 如果你还没有给机器人发过私聊消息，那么 `Detected OpenID` 为空是正常的
+
+## 5. 推荐联通测试流程
+
+这是最稳妥、最少踩坑的一条路径。
+
+### 第一步：保存凭据
+
+先在 `QQ` 配置卡里填好：
+
+- `App ID`
+- `App secret`
+
+然后保存。
+
+### 第二步：点击“校验”
+
+在 `Settings` 页面点击：
+
+- `校验`
+
+期望结果：
+
+- 不再出现缺少 `app_id` 或 `app_secret` 的错误
+
+### 第三步：点击“全部测试”或单独“发送测试消息”
+
+在第一次私聊前，QQ 测试结果很可能出现这类提示：
+
+```text
+QQ readiness is healthy, but no OpenID has been learned yet. Save credentials, then send one private QQ message so DeepScientist can auto-detect and save the `openid`.
+```
+
+这通常不是致命错误，而是在提醒你：
+
+- DeepScientist 已经能做 `access_token` 交换和 `/gateway` 探测
+- 但还没有一个可以主动发消息的目标 `openid`
+
+换句话说：
+
+- “就绪性检查成功”不等于“已经知道该把测试消息发给谁”
+
+### 第四步：从你的 QQ 给机器人发第一条私聊消息
+
+推荐先用私聊，不要一开始就用群聊。
+
+![QQ 私聊机器人示意](../images/qq/tencent-cloud-qq-chat.png)
+
+可以发送：
+
+```text
+/help
+```
+
+或者：
+
+```text
+你好
+```
+
+如果接入正常，DeepScientist 会自动检测这次私聊对应的 `openid`，并写回 `main_chat_id`。
+
+### 第五步：回到 Settings 页面确认状态
+
+重新打开或刷新 `Settings > Connectors > QQ`，或者直接回到 [#connector-qq-step-success](/settings/connectors#connector-qq-step-success)，重点看：
+
+- `Detected OpenID` 是否已经自动出现
+- 右侧 `Snapshot` 中：
+  - `Transport` 是否是 `gateway_direct`
+  - `Connection` / `Auth` 是否接近 `ready`
+  - `Discovered targets` 是否大于 `0`
+  - `Bound target` 是否出现你的 `openid`
+
+### 第六步：再次点击“发送测试消息”
+
+这时再点：
+
+- `发送测试消息`
+
+如果成功，说明 DeepScientist 已经能够：
+
+- 主动向该 QQ 用户发送消息
+- 接收该 QQ 用户的新消息
+
+### 5.1 成功后应该看到什么
+
+如果整个链路正常，通常会同时看到下面这些现象：
+
+- QQ 机器人能回复 `/help`、`/status` 之类的命令
+- `Settings > Connectors > QQ` 中的 `Detected OpenID` 不再为空
+- `Snapshot` 里出现已经发现的目标会话，且绑定目标不是空
+- 再次点击“发送测试消息”时，不再提示 target 为空
+- 如果当前已经有最新 quest，普通文本会自动进入该 quest；如果还没有 quest，则优先返回帮助信息
+
+### 5.2 报错提示速查
+
+| 提示 | 代表什么 | 应该怎么做 |
+| --- | --- | --- |
+| `app_id is required` / `app_secret is required` | 凭据没填完整 | 回到 Settings 补全后重新保存 |
+| `401` / `invalid credential` / token 获取失败 | `AppID` 或 `AppSecret` 有误，或者 secret 已被重置 | 到 QQ 机器人后台重新核对并保存 |
+| `QQ readiness is healthy, but no OpenID has been learned yet...` | 凭据大概率已经生效，但系统还不知道要给哪个 QQ 用户发主动消息 | 先用你的 QQ 私聊机器人一条消息，让系统自动发现 `openid` |
+| `QQ callback flow usually needs public_callback_url...` | 这是旧式 callback/relay 思路下的提示，不是当前 DeepScientist 推荐路径 | 保持 `transport = gateway_direct`，不要额外配置 callback URL |
+| `QQ relay mode needs relay_url...` | 说明 transport 被错误切到了 relay 模式 | 改回 `gateway_direct` |
+| `Detected OpenID` 一直为空 | 机器人还没收到第一条私聊，或者配置改完后 gateway 没重启成功 | 确认先保存配置，再从 QQ 私聊机器人，必要时重启 gateway |
+
+## 6. 如何在 QQ 中和 DeepScientist 沟通
+
+常用命令：
+
+| 命令 | 作用 |
+| --- | --- |
+| `/help` | 查看帮助 |
+| `/projects` 或 `/list` | 查看 quest 列表 |
+| `/use <quest_id>` | 绑定指定 quest |
+| `/use latest` | 绑定最新 quest |
+| `/new <goal>` | 新建 quest 并把当前 QQ 会话绑定过去 |
+| `/status` | 查看当前 quest 状态 |
+
+日常沟通建议：
+
+- 如果已经有最新 quest，普通文本通常会继续那个 quest
+- 如果还没有 quest，优先发送 `/new <goal>`
+- 如果你想切换到另一个 quest，显式发送 `/use <quest_id>`
+
+## 7. 最容易踩坑的地方
+
+### 7.1 误以为 QQ 需要公网回调
+
+当前 DeepScientist 的 QQ 方案不需要公网 callback。
+
+看到这些字段时，请注意：
+
+- `public_callback_url`：不需要
+- `relay_url`：不需要
+
+### 7.2 误以为测试失败就是凭据错了
+
+如果提示 target 为空，通常只是因为：
+
+- 你还没给机器人发第一条私聊
+- 系统还没自动拿到 `openid`
+
+这和 `app_id/app_secret` 是否有效，不是同一类问题。
+
+### 7.3 误以为 `openid` 需要自己去找
+
+在 DeepScientist 里，最简单的方式不是手工查 `openid`，而是：
+
+1. 先保存 `App ID` 和 `App secret`
+2. 再用 QQ 给机器人发一条私聊消息
+3. 等系统自动检测并写回 `Detected OpenID`
+
+### 7.4 群聊里机器人没反应
+
+先检查：
+
+- 你是不是在群里没有 `@` 机器人
+- `Require @ mention in groups` 是否开启
+
+如果你还没有跑通私聊，先不要直接排查群聊。
+
+### 7.5 切换了另一个 QQ 操作者，但 `main_chat_id` 还是旧的
+
+如果之前已经绑定过一个 `main_chat_id`，新的私聊用户不一定会自动覆盖旧值。
+
+这时建议：
+
+- 先确认当前应该由谁作为主操作者
+- 如有必要，手动清空或重新配置 QQ 目标，再重新测试
+
+## 8. 推荐的最小可行部署顺序
+
+如果你只想最快跑通：
+
+1. 创建 QQ 机器人
+2. 保存 `AppID` 和 `AppSecret`
+3. 打开 [Settings > Connectors > QQ](/settings/connectors#connector-qq)
+4. 启用 QQ，并填入 `App ID` / `App secret`
+5. 保存并点击 `校验`
+6. 用你的 QQ 私聊机器人，发送 `/help`
+7. 回到设置页确认 `Detected OpenID` 已自动出现
+8. 再次点击 `发送测试消息`
+9. 用 `/new <goal>` 或 `/use latest` 开始正式使用
+
+## 9. 参考资料
+
+- 腾讯云开发者社区：《OpenClaw 接入 QQ 机器人》
+  - https://cloud.tencent.com/developer/article/2635190
+- QQ Bot 官方平台
+  - https://bot.q.qq.com/
+
+说明：
+
+- 本文中的“注册 QQ 机器人”流程和截图参考了上面的腾讯云文章
+- 但 DeepScientist 的配置方式以当前 DeepScientist 内置 QQ connector 为准

package/docs/zh/04_LINGZHU_CONNECTOR_GUIDE.md

@@ -0,0 +1,230 @@
+# 04 Lingzhu 连接器指南：如何配置 Lingzhu
+
+本文说明如何在 `Settings > Connectors > Lingzhu` 中完成 Lingzhu 伴生端点配置。
+
+适用范围：
+
+- 仅包含配置教程
+- 面向 OpenClaw 兼容的 Lingzhu bridge 参数
+- 本地健康检查与 SSE 冒烟测试
+- 说明需要把哪些值填回 Lingzhu 平台
+
+本文不展开讨论云部署架构。你只需要：
+
+- 一个已经跑起来的 OpenClaw gateway
+- 一个眼镜端可访问的公网 IP 或公网域名
+
+参考来源：
+
+- Rokid 论坛配置页面：https://forum.rokid.com/post/detail/2831
+- 仓库内置 bridge 目录：`assets/connectors/lingzhu/openclaw-bridge`
+- 仓库内置 OpenClaw 配置模板：`assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
+
+## 1. DeepScientist 现在会自动提供什么
+
+Lingzhu 设置卡会自动生成并校验：
+
+- 本地 health URL
+- 本地 SSE URL
+- 公网 SSE URL
+- `auth_ak`
+- OpenClaw 配置片段
+- 本地探测 `curl`
+
+当前随包 bridge 还额外做了三件事：
+
+- 在模型真正开始生成前，先自动发送一条可见的“已收到”回执
+- 保留 SSE 注释心跳
+- 在上游长时间静默时补发轻量可见进度心跳
+
+需要明确的是：
+
+- Lingzhu 在 DeepScientist 里被视为 companion endpoint
+- 它不是像 QQ 那样的完整双向聊天 connector
+
+## 2. 开始前请先确认
+
+建议先确认下面几项：
+
+- DeepScientist 已成功安装并运行
+- 本地 OpenClaw gateway 已启动
+- 你知道 OpenClaw HTTP gateway 的端口，通常是 `18789`
+- 你已经有公网 IP 或公网域名
+
+重要提醒：
+
+- `127.0.0.1` 只能用于本地健康检查
+- Lingzhu 设备侧必须访问公网地址
+
+## 3. 打开设置页
+
+打开：
+
+- `Settings > Connectors > Lingzhu`
+
+页面会分成几块：
+
+- 网关端点
+- 鉴权与身份
+- 自动生成值
+- 探测与校验
+- 高级调试
+
+![Lingzhu 设置概览](../images/lingzhu/lingzhu-settings-overview.svg)
+
+## 4. 先填写端点
+
+推荐值如下：
+
+| 字段 | 推荐值 | 说明 |
+| --- | --- | --- |
+| `Enabled` | `true` | 开启 companion 配置 |
+| `Transport` | `openclaw_sse` | 固定值，不要改 |
+| `Local host` | `127.0.0.1` | 只用于本地探测 |
+| `Gateway port` | `18789` | 与 OpenClaw gateway 保持一致 |
+| `Public base URL` | `http://<公网IP>:18789` | 必须是眼镜端真正能访问到的地址 |
+
+如果你不确定本地端点应该怎么填，可以直接点击：
+
+- `Use local defaults`
+
+## 5. 生成 AK 和身份值
+
+建议如下：
+
+| 字段 | 推荐值 |
+| --- | --- |
+| `Auth AK` | 点击 `Generate AK` 自动生成 |
+| `Agent ID` | `main` |
+| `Lingzhu system prompt` | 可选 |
+
+需要保证下面两处完全一致：
+
+- OpenClaw Lingzhu 插件配置
+- Lingzhu 平台配置
+
+也就是：
+
+- `auth_ak`
+- `agent_id`
+
+## 6. 使用自动生成值
+
+DeepScientist 会直接展示你需要复制的内容：
+
+- 本地 health URL
+- 本地 SSE URL
+- 公网 SSE URL
+- OpenClaw 配置片段
+- 探测 curl
+
+其中真正要填回 Lingzhu 平台的是：
+
+- 公网 SSE URL
+- AK
+
+![Lingzhu 平台填写值](../images/lingzhu/lingzhu-platform-values.svg)
+
+## 7. 更新 OpenClaw
+
+你可以直接使用：
+
+- 设置页里自动生成的配置片段
+- 或仓库内置模板 `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
+
+内置 bridge 的安装命令为：
+
+```bash
+openclaw plugins install ./assets/connectors/lingzhu/openclaw-bridge
+```
+
+至少应确保 OpenClaw 开启：
+
+```json
+{
+  "gateway": {
+    "port": 18789,
+    "http": {
+      "endpoints": {
+        "chatCompletions": {
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+DeepScientist 也会自动把完整的 Lingzhu 插件配置片段生成出来：
+
+![OpenClaw 配置片段](../images/lingzhu/lingzhu-openclaw-config.svg)
+
+## 8. 执行本地探测
+
+保存参数后，点击：
+
+- `Run Lingzhu probe`
+
+DeepScientist 会依次执行：
+
+1. `GET /metis/agent/api/health`
+2. `POST /metis/agent/api/sse`
+
+理想结果：
+
+- `Connection = reachable`
+- `Auth = ready`
+- 探测结果没有报错
+
+## 9. 需要填回 Lingzhu 平台的值
+
+只需要填：
+
+- `Public SSE URL`
+- `Auth AK`
+
+不要填：
+
+- `127.0.0.1`
+- 任意本地机器名
+
+## 10. 常见失败原因
+
+### Health 显示 offline
+
+通常说明：
+
+- OpenClaw 没启动
+- `gateway_port` 填错
+- `local_host` 填错
+
+### SSE probe 失败
+
+通常说明：
+
+- `auth_ak` 不一致
+- Lingzhu SSE 路径没有暴露出来
+- OpenClaw 的 `chatCompletions.enabled` 还没打开
+
+### 本地探测通过，但设备仍无法接入
+
+通常说明：
+
+- `Public base URL` 不是公网可达地址
+- 防火墙或反向代理还没有放行端口
+
+## 11. 说明
+
+这块配置保持 registry-first：
+
+- Lingzhu 仍然落在 `connectors.yaml`
+- 自动生成值来自同一份 structured config
+- 校验、测试、前端渲染都消费同一条 connector 记录
+
+对于长任务，更稳妥的实际策略是：
+
+- 先由 bridge 自动回执
+- 在上游静默阶段由 bridge 补发可见进度心跳
+- 通过 `per_user` 会话连续保持多轮上下文
+
+这会明显改善兼容性，但仍不能消除 Lingzhu 平台单次请求超时的硬限制。

package/docs/zh/05_TUI_GUIDE.md

@@ -0,0 +1,128 @@
+# 05 TUI 使用指南：如何使用终端界面
+
+这份文档是当前 DeepScientist TUI 的**单一权威使用说明**（以本仓库实现为准）。
+
+如果你想了解更完整的运行时控制流、Prompt/Skill 执行模型、MCP 语义、以及 Canvas（Git 图）如何被重建，请同时阅读 `docs/zh/06_RUNTIME_AND_CANVAS.md`。
+
+## 安装与启动
+
+在当前仓库目录中：
+
+```bash
+pip install -e .
+npm install
+```
+
+常用启动方式：
+
+```bash
+ds
+ds --tui
+ds --both
+ds --status
+ds --stop
+```
+
+说明：
+
+- `ds`：启动守护进程，打印醒目的本地 Web 链接，尝试自动打开浏览器，然后退出。
+- `ds --tui`：启动守护进程，并进入基于 Ink 的终端工作区。
+- `ds --both`：同时打开 Web 工作区，并保持终端工作区附着运行。
+- `ds --stop`：停止**守护进程本身**（不是仅停止某个 quest）。
+- 仍可使用 `python -m deepscientist.cli ...` 做底层操作，但推荐通过 launcher 使用。
+- 在源码仓库里，`node bin/ds.js` 与 `ds` 的行为一致
+
+## TUI 内的核心操作
+
+在 TUI 中：
+
+- `/home`：回到“未绑定 quest”的请求模式。
+- `/projects`：打开 quest 列表（浏览/切换）。
+- `/use <quest_id>`：绑定当前 TUI 会话到指定 quest。
+- `/new <goal>`：在 TUI 内创建新 quest。
+- `/new <goal>` 会创建 quest，并通过守护进程自动启动首轮执行。
+- `/delete <quest_id> --yes`：删除 quest（危险操作，需要确认）。
+- 直接输入普通文本：发送到当前绑定的 quest（作为用户消息）。
+- `/status`：查看当前 quest 状态。
+- `/graph`：查看当前 quest 的 Git 图（分支与研究过程）。
+- `/help`：在 TUI 内显示命令列表和控制键说明。
+- `/config`：打开本地配置浏览器。
+- `/pause`：暂停当前 quest（若未绑定 quest，会进入选择面板）。
+- `/resume`：恢复已暂停/停止的 quest（若未绑定 quest，会进入选择面板）。
+- `/stop`：停止当前 quest（若未绑定 quest，会进入选择面板）。
+- `/stop <quest_id>`：停止指定 quest。
+- 在输入框中输入 `/` 会显示实时命令列表；继续输入 `/re`、`/co` 等前缀时，会按前缀过滤命令行
+- 在 home 模式下，`↑/↓` 和 `Tab` 只会切换“当前预览选中的 quest”，不会直接硬切换一个已经绑定中的 quest。
+- 在 home 模式下，普通文本不会再隐式创建 quest，也不会隐式发消息；必须用 `/new <goal>` 创建，用 `/projects` 或 `/use <quest_id>` 绑定后再聊天。
+
+如果你已经在某个 quest 中，`/pause`、`/resume`、`/stop` 默认作用于当前 quest。
+
+页脚和欢迎区也会直接显示主要快捷提示：
+
+- `Enter`：发送输入或确认选择
+- `↑/↓`：浏览选择列表
+- `Esc`：关闭当前弹层
+- `Ctrl+O`：打开 Web 工作区
+- `Ctrl+C`：退出 TUI
+
+## 消息投递（Mailbox）模型
+
+TUI、Web UI、以及外部 Connector 共用同一套“邮箱”语义：
+
+1. 当 quest 空闲时，用户第一条普通消息会**直接触发一轮 turn**。
+2. 这条启动消息会被本轮 run 认领，不会在后续“邮箱投递”中被重复投递。
+3. 当 agent 正在运行时，后续用户消息会进入 `.ds/user_message_queue.json` 队列。
+4. 这些排队消息只会在 agent 调用 `artifact.interact(...)` 时被投递给 agent。
+5. 投递发生后，队列消息会从 `pending` 变成已完成的审计记录。
+6. 如果没有新消息，运行时会明确告诉 agent“用户没有新消息”，便于继续推进而不是卡住等待。
+
+相关持久化文件（均在 quest 内）：
+
+- `.ds/runtime_state.json`
+- `.ds/user_message_queue.json`
+- `.ds/interaction_journal.jsonl`
+- `.ds/events.jsonl`
+
+## Pause / Stop / Resume
+
+Quest 级控制：
+
+- `/pause`：中断当前 runner，并将 quest 标记为 `paused`。
+- `/resume`：把 `paused` 或 `stopped` 的 quest 重新置为 `active`。
+- `/stop`：更强的中断；清理 `active_run_id`，把 quest 标记为 `stopped`。
+- `/pause`、`/resume`、`/stop` 会写入一条可见的控制事件到 quest 历史，并按路由策略推送到绑定的 connectors。
+
+`/stop` 比 `/pause` 更强：
+
+- 未投递的邮箱消息会被取消（但会保留审计记录，如 `cancelled_by_stop`）
+- 当前轮启动消息会记录为 `accepted_by_run`
+- stop 后下一条新用户消息会启动新的一轮，不会静默重放旧队列
+- stop 不会改写 Git：当前分支/工作树/已写文件都保留，便于继续接续
+
+守护进程级 stop：
+
+- `ds --stop`：停止守护进程
+- 会尽量先优雅退出；必要时升级到 `SIGTERM`/`SIGKILL`
+- 成功停止后会清理 daemon state，并打印 `DeepScientist daemon stopped.`
+
+## Artifact 交互要求
+
+agent 应当把 `artifact.interact(...)` 作为长对话的“脊柱”：
+
+- `progress` / `milestone`：线程式进度更新（非阻塞）
+- `decision_request`：阻塞式决策请求（需给出 1~3 个选项、利弊、证据）
+
+## 排错
+
+若你发送消息后 TUI 看起来“没反应”：
+
+- 确认是否绑定了 quest
+- 用 `/status` 查看 quest 状态
+- 查看 `.ds/runtime_state.json`（`status`、`active_run_id`、`pending_user_message_count`）
+- 查看 `.ds/events.jsonl` 是否有 `runner.turn_error`、`quest.control`、`artifact.recorded`
+
+若“运行中”时发送的补充消息没有被 agent 看到：
+
+- 看 quest 是否仍在运行
+- 看 `.ds/user_message_queue.json`
+- 确认 agent 过程中有调用 `artifact.interact(...)`