@researai/deepscientist 1.5.13 → 1.5.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/docs/en/05_TUI_GUIDE.md +466 -96
  2. package/docs/en/README.md +2 -0
  3. package/docs/zh/05_TUI_GUIDE.md +465 -82
  4. package/docs/zh/README.md +2 -0
  5. package/package.json +1 -1
  6. package/pyproject.toml +1 -1
  7. package/src/deepscientist/__init__.py +1 -1
  8. package/src/deepscientist/artifact/service.py +125 -2
  9. package/src/deepscientist/connector/lingzhu_support.py +23 -4
  10. package/src/deepscientist/daemon/app.py +111 -30
  11. package/src/deepscientist/mcp/server.py +161 -19
  12. package/src/deepscientist/prompts/builder.py +13 -54
  13. package/src/deepscientist/quest/service.py +99 -0
  14. package/src/deepscientist/quest/stage_views.py +134 -29
  15. package/src/deepscientist/shared.py +6 -1
  16. package/src/prompts/system.md +220 -2065
  17. package/src/skills/baseline/SKILL.md +265 -994
  18. package/src/skills/baseline/references/baseline-checklist-template.md +21 -32
  19. package/src/skills/baseline/references/baseline-plan-template.md +41 -57
  20. package/src/tui/dist/app/AppContainer.js +1442 -52
  21. package/src/tui/dist/components/Composer.js +1 -1
  22. package/src/tui/dist/components/ConfigScreen.js +190 -36
  23. package/src/tui/dist/components/GradientStatusText.js +1 -20
  24. package/src/tui/dist/components/InputPrompt.js +41 -32
  25. package/src/tui/dist/components/LoadingIndicator.js +1 -1
  26. package/src/tui/dist/components/Logo.js +61 -38
  27. package/src/tui/dist/components/MainContent.js +10 -3
  28. package/src/tui/dist/components/WelcomePanel.js +4 -12
  29. package/src/tui/dist/components/messages/AssistantMessage.js +1 -1
  30. package/src/tui/dist/components/messages/BashExecOperationMessage.js +3 -3
  31. package/src/tui/dist/components/messages/OperationMessage.js +1 -1
  32. package/src/tui/dist/index.js +28 -1
  33. package/src/tui/dist/layouts/DefaultAppLayout.js +3 -3
  34. package/src/tui/dist/lib/api.js +17 -0
  35. package/src/tui/dist/lib/connectors.js +261 -0
  36. package/src/tui/dist/semantic-colors.js +29 -19
  37. package/src/tui/package.json +1 -1
  38. package/src/ui/dist/assets/{AiManusChatView-CnJcXynW.js → AiManusChatView-DaF9Nge_.js} +12 -12
  39. package/src/ui/dist/assets/{AnalysisPlugin-DeyzPEhV.js → AnalysisPlugin-BSVx6dXE.js} +1 -1
  40. package/src/ui/dist/assets/{CliPlugin-CB1YODQn.js → CliPlugin-C9gzJX41.js} +9 -9
  41. package/src/ui/dist/assets/{CodeEditorPlugin-B-xicq1e.js → CodeEditorPlugin-DU9G0Tox.js} +8 -8
  42. package/src/ui/dist/assets/{CodeViewerPlugin-DT54ysXa.js → CodeViewerPlugin-DoX_fI9l.js} +5 -5
  43. package/src/ui/dist/assets/{DocViewerPlugin-DQtKT-VD.js → DocViewerPlugin-C4FWIXuU.js} +3 -3
  44. package/src/ui/dist/assets/{GitDiffViewerPlugin-hqHbCfnv.js → GitDiffViewerPlugin-BgfFMgtf.js} +20 -20
  45. package/src/ui/dist/assets/{ImageViewerPlugin-OcVo33jV.js → ImageViewerPlugin-tcPkfY_x.js} +5 -5
  46. package/src/ui/dist/assets/{LabCopilotPanel-DdGwhEUV.js → LabCopilotPanel-_dKV60Bf.js} +11 -11
  47. package/src/ui/dist/assets/{LabPlugin-Ciz1gDaX.js → LabPlugin-Bje0ayoC.js} +2 -2
  48. package/src/ui/dist/assets/{LatexPlugin-BhmjNQRC.js → LatexPlugin-CVsBzAln.js} +7 -7
  49. package/src/ui/dist/assets/{MarkdownViewerPlugin-BzdVH9Bx.js → MarkdownViewerPlugin-xjmrqv_8.js} +4 -4
  50. package/src/ui/dist/assets/{MarketplacePlugin-DmyHspXt.js → MarketplacePlugin-mMM2A8wP.js} +3 -3
  51. package/src/ui/dist/assets/{NotebookEditor-BTVYRGkm.js → NotebookEditor-3kVDSOBo.js} +11 -11
  52. package/src/ui/dist/assets/{NotebookEditor-BMXKrDRk.js → NotebookEditor-SoJ8X-MO.js} +1 -1
  53. package/src/ui/dist/assets/{PdfLoader-CvcjJHXv.js → PdfLoader-DElVuHl9.js} +1 -1
  54. package/src/ui/dist/assets/{PdfMarkdownPlugin-DW2ej8Vk.js → PdfMarkdownPlugin-Bq88XT4G.js} +2 -2
  55. package/src/ui/dist/assets/{PdfViewerPlugin-CmlDxbhU.js → PdfViewerPlugin-CsCXMo9S.js} +10 -10
  56. package/src/ui/dist/assets/{SearchPlugin-DAjQZPSv.js → SearchPlugin-oUPvy19k.js} +1 -1
  57. package/src/ui/dist/assets/{TextViewerPlugin-C-nVAZb_.js → TextViewerPlugin-CRkT9yNy.js} +5 -5
  58. package/src/ui/dist/assets/{VNCViewer-D7-dIYon.js → VNCViewer-BgbuvWhR.js} +10 -10
  59. package/src/ui/dist/assets/{bot-C_G4WtNI.js → bot-v_RASACv.js} +1 -1
  60. package/src/ui/dist/assets/{code-Cd7WfiWq.js → code-5hC9d0VH.js} +1 -1
  61. package/src/ui/dist/assets/{file-content-B57zsL9y.js → file-content-D1PxfOrp.js} +1 -1
  62. package/src/ui/dist/assets/{file-diff-panel-DVoheLFq.js → file-diff-panel-DG1oT_Hj.js} +1 -1
  63. package/src/ui/dist/assets/{file-socket-B5kXFxZP.js → file-socket-BmdFYQlk.js} +1 -1
  64. package/src/ui/dist/assets/{image-LLOjkMHF.js → image-Dqe2X2tW.js} +1 -1
  65. package/src/ui/dist/assets/{index-Dxa2eYMY.js → index-DVsMKK_y.js} +1 -1
  66. package/src/ui/dist/assets/{index-C3r2iGrp.js → index-Duvz8Ip0.js} +12 -12
  67. package/src/ui/dist/assets/{index-CLQauncb.js → index-Nt9hS4ck.js} +470 -165
  68. package/src/ui/dist/assets/{index-hOUOWbW2.js → index-RDlNXXx1.js} +2 -2
  69. package/src/ui/dist/assets/{monaco-BGGAEii3.js → monaco-DIXge1CP.js} +1 -1
  70. package/src/ui/dist/assets/{pdf-effect-queue-DlEr1_y5.js → pdf-effect-queue-BBTTQaO-.js} +1 -1
  71. package/src/ui/dist/assets/{popover-CWJbJuYY.js → popover-BWlolyxo.js} +1 -1
  72. package/src/ui/dist/assets/{project-sync-CRJiucYO.js → project-sync-BM5PkFH4.js} +1 -1
  73. package/src/ui/dist/assets/{select-CoHB7pvH.js → select-D4dAtrA8.js} +2 -2
  74. package/src/ui/dist/assets/{sigma-D5aJWR8J.js → sigma-CKbE5jJT.js} +1 -1
  75. package/src/ui/dist/assets/{square-check-big-DUK_mnkS.js → square-check-big-CZNGMgiB.js} +1 -1
  76. package/src/ui/dist/assets/{trash-ChU3SEE3.js → trash-DaB37xAz.js} +1 -1
  77. package/src/ui/dist/assets/{useCliAccess-BrJBV3tY.js → useCliAccess-C2OmAcWe.js} +1 -1
  78. package/src/ui/dist/assets/{useFileDiffOverlay-C2OQaVWc.js → useFileDiffOverlay-Dowd1Ij4.js} +1 -1
  79. package/src/ui/dist/assets/{wrap-text-C7Qqh-om.js → wrap-text-BGjAhAUq.js} +1 -1
  80. package/src/ui/dist/assets/{zoom-out-rtX0FKya.js → zoom-out-dMZQMXzc.js} +1 -1
  81. package/src/ui/dist/index.html +1 -1
  82. package/uv.lock +1 -1
@@ -1,128 +1,511 @@
1
- # 05 TUI 使用指南:如何使用终端界面
1
+ # 05 TUI 端到端指南:如何在终端里跑通整个流程
2
2
 
3
- 这份文档是当前 DeepScientist TUI 的**单一权威使用说明**(以本仓库实现为准)。
3
+ 这份文档面向一个很具体的目标:
4
4
 
5
- 如果你想了解更完整的运行时控制流、Prompt/Skill 执行模型、MCP 语义、以及 Canvas(Git 图)如何被重建,请同时阅读 `docs/zh/06_RUNTIME_AND_CANVAS.md`。
5
+ - 你从 `ds --tui` 进入终端界面
6
+ - 你知道现在自己在什么模式里
7
+ - 你能创建或切换 quest
8
+ - 你能在 TUI 里把 QQ、微信、Lingzhu 这样的 connector 配好
9
+ - 你能把 connector 真正绑定到当前 quest
10
+ - 你能继续在 TUI、Web、QQ、微信之间切换,而不会把上下文弄乱
6
11
 
7
- ## 安装与启动
12
+ 如果你想看更底层的运行时和 Canvas 机制,再继续看 [06 Runtime 与 Canvas](./06_RUNTIME_AND_CANVAS.md)。
8
13
 
9
- 在当前仓库目录中:
14
+ ## 1. 先记住 TUI 的三个面
15
+
16
+ 当前 TUI 不是“一个纯聊天框”,而是三个工作面来回切换:
17
+
18
+ 1. `home / request mode`
19
+ 你还没有把当前终端会话绑定到某个 quest。
20
+ 这个模式下可以预览 quest、创建 quest、打开配置,但普通文本不会自动发给任何 quest。
21
+ 2. `quest mode`
22
+ 你已经绑定到一个 quest。
23
+ 这个模式下直接输入普通文本,就是给当前 quest 发用户消息。
24
+ 3. `config mode`
25
+ 你在看本地配置、quest 配置、或者 connector 配置。
26
+ 这个模式主要靠 `↑/↓`、`Enter`、`Esc` 操作。
27
+
28
+ 你可以把它理解成:
29
+
30
+ - `home` 负责“选项目”
31
+ - `quest` 负责“推进项目”
32
+ - `config` 负责“接入外部协作面和编辑配置”
33
+
34
+ ## 2. 安装与启动
35
+
36
+ 在当前仓库根目录:
10
37
 
11
38
  ```bash
12
39
  uv sync
13
40
  npm install
14
41
  ```
15
42
 
16
- 常用启动方式:
43
+ 最常用的启动方式:
17
44
 
18
45
  ```bash
19
- ds
20
46
  ds --tui
47
+ ```
48
+
49
+ 也常用:
50
+
51
+ ```bash
52
+ ds
21
53
  ds --both
22
54
  ds --status
23
55
  ds --stop
24
56
  ```
25
57
 
26
- 说明:
27
-
28
- - `ds`:启动守护进程,打印醒目的本地 Web 链接,尝试自动打开浏览器,然后退出。
29
- - `ds --tui`:启动守护进程,并进入基于 Ink 的终端工作区。
30
- - `ds --both`:同时打开 Web 工作区,并保持终端工作区附着运行。
31
- - `ds --stop`:停止**守护进程本身**(不是仅停止某个 quest)。
32
- - 仍可使用 `python -m deepscientist.cli ...` 做底层操作,但推荐通过 launcher 使用。
33
- - 在源码仓库里,`node bin/ds.js` 与 `ds` 的行为一致
34
-
35
- ## TUI 内的核心操作
36
-
37
- 在 TUI 中:
38
-
39
- - `/home`:回到“未绑定 quest”的请求模式。
40
- - `/projects`:打开 quest 列表(浏览/切换)。
41
- - `/use <quest_id>`:绑定当前 TUI 会话到指定 quest。
42
- - `/new <goal>`:在 TUI 内创建新 quest。
43
- - `/new <goal>` 会创建 quest,并通过守护进程自动启动首轮执行。
44
- - `/delete <quest_id> --yes`:删除 quest(危险操作,需要确认)。
45
- - 直接输入普通文本:发送到当前绑定的 quest(作为用户消息)。
46
- - `/status`:查看当前 quest 状态。
47
- - `/graph`:查看当前 quest 的 Git 图(分支与研究过程)。
48
- - `/help`:在 TUI 内显示命令列表和控制键说明。
49
- - `/config`:打开本地配置浏览器。
50
- - `/pause`:暂停当前 quest(若未绑定 quest,会进入选择面板)。
51
- - `/resume`:恢复已暂停/停止的 quest(若未绑定 quest,会进入选择面板)。
52
- - `/stop`:停止当前 quest(若未绑定 quest,会进入选择面板)。
53
- - `/stop <quest_id>`:停止指定 quest。
54
- - 在输入框中输入 `/` 会显示实时命令列表;继续输入 `/re`、`/co` 等前缀时,会按前缀过滤命令行
55
- - 在 home 模式下,`↑/↓` 和 `Tab` 只会切换“当前预览选中的 quest”,不会直接硬切换一个已经绑定中的 quest。
56
- - 在 home 模式下,普通文本不会再隐式创建 quest,也不会隐式发消息;必须用 `/new <goal>` 创建,用 `/projects` 或 `/use <quest_id>` 绑定后再聊天。
57
-
58
- 如果你已经在某个 quest 中,`/pause`、`/resume`、`/stop` 默认作用于当前 quest。
59
-
60
- 页脚和欢迎区也会直接显示主要快捷提示:
58
+ 含义:
59
+
60
+ - `ds`:启动 daemon,打印本地 Web 地址,尝试打开浏览器,然后退出。
61
+ - `ds --tui`:启动 daemon,并进入终端工作区。
62
+ - `ds --both`:同时开 Web 和 TUI。
63
+ - `ds --status`:查看 daemon 状态。
64
+ - `ds --stop`:停止 daemon 本身,不只是停止某个 quest。
65
+
66
+ ## 3. 进入 TUI 后,第一眼应该怎么看
67
+
68
+ 如果你是第一次进来,欢迎区最重要的信息有三类:
69
+
70
+ - 当前是 `request mode` 还是 `quest mode`
71
+ - 当前本地 Web 地址
72
+ - 当前有哪些 quest 可以切换
73
+
74
+ 如果欢迎区显示的是 `request mode`,说明你还没有绑定 quest。
75
+
76
+ 这时正确动作不是直接输入普通文本,而是先做下面两件事之一:
77
+
78
+ - 创建一个新 quest:`/new <goal>`
79
+ - 绑定一个已有 quest:`/use <quest_id>`
80
+
81
+ 例如:
82
+
83
+ ```text
84
+ /new 复现当前项目的 baseline,并整理一个可比较的实验计划
85
+ ```
86
+
87
+ 或者:
88
+
89
+ ```text
90
+ /use 001
91
+ ```
92
+
93
+ ## 4. 最短可跑通路径:从 0 到第一个 quest
94
+
95
+ 这是我建议的第一条完整路径。
96
+
97
+ ### Step 1. 启动 TUI
98
+
99
+ ```bash
100
+ ds --tui
101
+ ```
102
+
103
+ ### Step 2. 创建 quest
104
+
105
+ 在输入框输入:
106
+
107
+ ```text
108
+ /new 用当前仓库跑一次 baseline,并给出后续实验计划
109
+ ```
110
+
111
+ 成功后,TUI 会自动切进这个新 quest。
112
+
113
+ ### Step 3. 等首轮执行开始
114
+
115
+ `/new <goal>` 不只是建目录,还会自动启动首轮运行。
116
+
117
+ 这时你会看到:
118
+
119
+ - quest 已经被绑定
120
+ - 历史区开始出现消息、artifact 或操作记录
121
+ - 状态栏显示当前 quest id
122
+
123
+ ### Step 4. 再发一条普通消息
124
+
125
+ 例如:
126
+
127
+ ```text
128
+ 先别发散,先把当前 baseline 跑通,然后告诉我缺什么配置。
129
+ ```
130
+
131
+ 这条消息会发给当前绑定的 quest。
132
+
133
+ ### Step 5. 用 `/status` 和 `/graph` 看状态
134
+
135
+ 常用两条命令:
136
+
137
+ ```text
138
+ /status
139
+ /graph
140
+ ```
141
+
142
+ - `/status`:看 quest 当前状态
143
+ - `/graph`:看 quest 图和研究过程
144
+
145
+ ### Step 6. 随时打开 Web
146
+
147
+ 在 TUI 里按:
148
+
149
+ - `Ctrl+O`:打开当前 quest 对应的 Web 工作区
150
+
151
+ 这很重要,因为 TUI 和 Web 看的是同一个 daemon、同一个 quest、同一套事件流。
152
+
153
+ ## 5. TUI 里最常用的命令和按键
154
+
155
+ ### 命令
156
+
157
+ - `/home`:回到未绑定 quest 的 request mode
158
+ - `/projects`:打开 quest 浏览面板
159
+ - `/use <quest_id>`:绑定到指定 quest
160
+ - `/new <goal>`:创建新 quest
161
+ - `/delete <quest_id> --yes`:删除 quest
162
+ - `/pause`:暂停当前 quest;未绑定时会先进入选择面板
163
+ - `/resume`:恢复当前 quest;未绑定时会先进入选择面板
164
+ - `/stop`:停止当前 quest;未绑定时会先进入选择面板
165
+ - `/stop <quest_id>`:显式停止指定 quest
166
+ - `/status`:看当前 quest 状态
167
+ - `/graph`:看当前 quest 图
168
+ - `/config`:进入配置面
169
+ - `/config connectors`:直接进 connector 列表
170
+ - `/config qq`:直接进 QQ 配置
171
+ - `/config weixin`:直接进微信配置
172
+ - `/config lingzhu`:直接进 Lingzhu 配置
173
+
174
+ ### 按键
61
175
 
62
176
  - `Enter`:发送输入或确认选择
63
- - `↑/↓`:浏览选择列表
64
- - `Esc`:关闭当前弹层
177
+ - `↑/↓`:切换选择项
178
+ - `Tab`:在列表中向下切换
179
+ - `Esc`:返回上一层或关闭当前面板
180
+ - `Ctrl+R`:强制刷新
65
181
  - `Ctrl+O`:打开 Web 工作区
182
+ - `Ctrl+G`:从任意位置直接打开配置首页
183
+ - `Ctrl+B`:离开当前 quest;如果你在配置页,则先关闭配置页
66
184
  - `Ctrl+C`:退出 TUI
185
+ - `Shift+↑/↓`:滚动历史区
186
+ - `PageUp/PageDown`:整页滚动历史区
187
+
188
+ ## 6. 正确的日常节奏
189
+
190
+ 如果你准备把 TUI 当主工作面,推荐始终按这个顺序:
191
+
192
+ 1. 先确认自己是否已经绑定 quest
193
+ 2. 再发消息
194
+ 3. 需要切 quest 时用 `/projects` 或 `/use`
195
+ 4. 需要配 connector 时先确认“当前 quest”是谁,再进 `/config`
196
+
197
+ 原因很简单:
198
+
199
+ - connector 绑定动作是“绑定到当前 quest”
200
+ - 如果你先进了 `/config qq`,但当前没有 active quest,那么 TUI 只能保存 connector 配置,不能替你完成 quest 绑定
201
+
202
+ 所以推荐顺序是:
203
+
204
+ 1. `/new <goal>` 或 `/use <quest_id>`
205
+ 2. 确认已经进入 quest mode
206
+ 3. `/config qq` 或 `/config weixin` 或 `/config lingzhu`
207
+
208
+ ## 7. 在 TUI 里配置 connector 的推荐顺序
209
+
210
+ 当前 TUI 对 connector 的最佳实践顺序是:
211
+
212
+ 1. 先创建或切到你要继续推进的 quest
213
+ 2. 再进入 connector 配置页
214
+ 3. 先看顶部 guide
215
+ 4. 按 guide 的顺序完成平台侧操作
216
+ 5. 回到 TUI 执行保存、刷新或绑定动作
217
+
218
+ ### 为什么现在顶部 guide 很关键
219
+
220
+ connector 详情页顶部现在不是装饰性文案,而是“下一步怎么做”的实际操作提示。
221
+
222
+ - `QQ`:顶部会告诉你应该先填凭据、再发第一条私聊、再等待 OpenID / conversation_id 自动出现
223
+ - `Weixin`:顶部会告诉你应该先创建二维码,再用微信扫码确认
224
+ - `Lingzhu`:顶部会告诉你应该先设置公网 `public_base_url`,然后把哪些值填到 Rokid 平台
67
225
 
68
- ## 消息投递(Mailbox)模型
226
+ ## 8. QQ:在 TUI 里跑通完整链路
69
227
 
70
- TUI、Web UI、以及外部 Connector 共用同一套“邮箱”语义:
228
+ 这是当前最容易误操作的一条,所以单独展开。
71
229
 
72
- 1. 当 quest 空闲时,用户第一条普通消息会**直接触发一轮 turn**。
73
- 2. 这条启动消息会被本轮 run 认领,不会在后续“邮箱投递”中被重复投递。
74
- 3. 当 agent 正在运行时,后续用户消息会进入 `.ds/user_message_queue.json` 队列。
75
- 4. 这些排队消息只会在 agent 调用 `artifact.interact(...)` 时被投递给 agent。
76
- 5. 投递发生后,队列消息会从 `pending` 变成已完成的审计记录。
77
- 6. 如果没有新消息,运行时会明确告诉 agent“用户没有新消息”,便于继续推进而不是卡住等待。
230
+ ### 推荐路径
78
231
 
79
- 相关持久化文件(均在 quest 内):
232
+ 1. 先进入目标 quest
233
+ 2. 输入 `/config qq`
234
+ 3. 先看顶部 guide
235
+ 4. 填 `Bot name`、`App ID`、`App Secret`
236
+ 5. 执行 `Save Connector`
237
+ 6. 从你自己的 QQ 给 bot 发第一条私聊
238
+ 7. 回到 TUI,等待自动刷新,或按 `Ctrl+R`
239
+ 8. 确认 `Detected OpenID` 与 `Last conversation` 不再为空
240
+ 9. 在下面出现的 target action 里,把当前 quest 绑定到正确的 QQ target
241
+
242
+ ### 你在 QQ 页面会看到什么
243
+
244
+ 顶部通常会给出两类信息:
245
+
246
+ - `Top Guide`
247
+ 这告诉你现在应该先做哪一步
248
+ - `Current Status`
249
+ 这告诉你当前卡在哪一步
250
+
251
+ 重点字段:
252
+
253
+ - `Detected OpenID`
254
+ 这是系统自动学到的,不是第一次就该手填的字段
255
+ - `Last conversation`
256
+ 这是运行时最后一次看到的会话 id
257
+ - `Discovered targets`
258
+ 这是 TUI 已经从运行时学到、可以拿来绑定 quest 的目标
259
+ - `Profile · ...`
260
+ 如果 QQ 配了多个 profile,TUI 现在会直接显示每个 profile 的运行时摘要,你可以在终端里看到它的 OpenID、偏好 target、当前绑定 quest 和就绪状态,不必先切回 Web。
261
+
262
+ ### 正确理解 QQ 绑定
263
+
264
+ 在当前 TUI 里,QQ 有两层事:
265
+
266
+ 1. 保存 QQ bot 自身凭据
267
+ 2. 把某个 runtime target 绑定到当前 quest
268
+
269
+ 只有第 1 层完成,还不算真正“跑通”。
270
+
271
+ 真正跑通的标志是:
272
+
273
+ - `Detected OpenID` 已出现
274
+ - target action 已出现
275
+ - 你把当前 quest 绑定到了正确 target
276
+
277
+ ### 当前 TUI 里的限制
278
+
279
+ - 如果你有多个 QQ profile,TUI 详情页仍会提示:profile 的新增、删除、凭据替换属于原始配置编辑任务
280
+ - 多 profile 的新增、删除、复杂编辑,仍建议回到原始 `connectors.yaml` 或 Web 设置页
281
+ - 但 profile 摘要和 runtime target 绑定动作现在会直接完整展示在 TUI 里
282
+
283
+ ## 9. 微信:在 TUI 里跑通完整链路
284
+
285
+ ### 推荐路径
286
+
287
+ 1. 先进入目标 quest
288
+ 2. 输入 `/config weixin`
289
+ 3. 执行 `Bind Weixin` 或 `Rebind Weixin`
290
+ 4. TUI 会进入二维码页
291
+ 5. 用目标微信账号所在手机扫码
292
+ 6. 在微信里确认登录
293
+ 7. 成功后 TUI 自动回到详情页
294
+ 8. 确认 `Bot account`、`Owner account`、`Known targets` 已刷新
295
+
296
+ ### 当前行为要点
297
+
298
+ - 微信绑定不需要你手动填 bot token
299
+ - 二维码是 DeepScientist 在 TUI 内直接生成的
300
+ - 扫码确认成功后,connector 配置会自动保存
301
+
302
+ ### 什么时候算跑通
303
+
304
+ 至少满足:
305
+
306
+ - 详情页不再是“未绑定”
307
+ - `Bot account` 不为空
308
+ - `Owner account` 不为空
309
+
310
+ 如果你还要继续用它推进 quest,后续再让 quest 绑定到微信会话即可。
311
+
312
+ ## 10. Lingzhu / Rokid:在 TUI 里跑通完整链路
313
+
314
+ Lingzhu 的关键不是“点一个按钮立即完成”,而是“TUI 生成平台字段,你拿去填 Rokid 平台”。
315
+
316
+ ### 推荐路径
317
+
318
+ 1. 先进入目标 quest
319
+ 2. 输入 `/config lingzhu`
320
+ 3. 先把 `Public base URL` 改成最终公网地址
321
+ 4. 如果需要,生成新的 `Custom agent AK`
322
+ 5. 看详情页里自动生成的 Rokid 字段
323
+ 6. 把里面的值填到 Rokid 平台
324
+ 7. 回到 TUI 执行 `Save Connector`
325
+
326
+ ### 你需要特别注意的点
327
+
328
+ - `public_base_url` 必须是最终可访问的公网 `http(s)` 地址
329
+ - `127.0.0.1`、`localhost`、内网地址不能作为真实 Rokid 绑定地址
330
+ - 详情页现在会展示和 Web 弹框一致的 Rokid 侧字段:
331
+ - `Custom agent ID`
332
+ - `Custom agent URL`
333
+ - `Custom agent AK`
334
+ - `Agent name`
335
+ - `Category`
336
+ - `Capability summary`
337
+ - `Opening message`
338
+ - `Input type`
339
+ - 如果终端一屏放不下,使用 `PgUp` / `PgDn` 往下翻
340
+
341
+ ### 什么时候算跑通
342
+
343
+ 至少满足:
344
+
345
+ - `Public base URL` 已改成公网地址
346
+ - `Custom agent AK` 已生成或已填入
347
+ - 你已经把顶部列出的字段复制进 Rokid 平台
348
+ - 当前 connector 已保存
349
+
350
+ ## 11. 一条完整推荐剧本
351
+
352
+ 如果你要在一台服务器上用 TUI 跑通“建 quest + 配 connector + 继续推进”,我建议直接照下面这条顺序:
353
+
354
+ ### 剧本 A:QQ
355
+
356
+ 1. `ds --tui`
357
+ 2. `/new <goal>`
358
+ 3. 等 quest 自动启动
359
+ 4. `/config qq`
360
+ 5. 填 `Bot name / App ID / App Secret`
361
+ 6. `Save Connector`
362
+ 7. 去 QQ 给 bot 发一条私聊
363
+ 8. 回 TUI,确认 `Detected OpenID` 和 target 出现
364
+ 9. 执行 `Bind ...` 动作,把当前 quest 绑定到该 QQ target
365
+ 10. 再去 QQ 继续发消息,或回 TUI / Web 继续推进
366
+
367
+ ### 剧本 B:微信
368
+
369
+ 1. `ds --tui`
370
+ 2. `/new <goal>` 或 `/use <quest_id>`
371
+ 3. `/config weixin`
372
+ 4. `Bind Weixin`
373
+ 5. 手机扫码并确认
374
+ 6. 等 TUI 自动回详情页
375
+ 7. 确认绑定信息已刷新
376
+ 8. 继续在 quest 内推进
377
+
378
+ ### 剧本 C:Lingzhu
379
+
380
+ 1. `ds --tui`
381
+ 2. `/new <goal>` 或 `/use <quest_id>`
382
+ 3. `/config lingzhu`
383
+ 4. 改 `Public base URL`
384
+ 5. 生成或填写 `Custom agent AK`
385
+ 6. 把顶部列出的值复制到 Rokid 平台
386
+ 7. `Save Connector`
387
+ 8. 再做设备侧联通验证
388
+
389
+ ## 12. TUI、Web、Connector 是同一个 quest
390
+
391
+ 这件事非常重要。
392
+
393
+ 你在 TUI 里做的这些事:
394
+
395
+ - `/new`
396
+ - `/use`
397
+ - 普通消息
398
+ - `/pause`、`/resume`、`/stop`
399
+ - connector 绑定
400
+
401
+ 都会进入同一个 daemon 和同一个 quest 持久状态。
402
+
403
+ 所以:
404
+
405
+ - 在 TUI 里建的 quest,Web 能立刻看到
406
+ - 在 TUI 里绑定的 connector,Web 能立刻看到
407
+ - 在 QQ / 微信里继续对话,TUI 和 Web 最终也会回到同一个 quest 上
408
+
409
+ TUI 不是“另起一套状态”,只是另一种操作面。
410
+
411
+ ## 13. 邮箱语义:为什么运行中发的消息不一定立刻被 agent 看见
412
+
413
+ TUI、Web、connector 共用同一套 mailbox 语义。
414
+
415
+ 核心规则:
416
+
417
+ 1. quest 空闲时,第一条普通用户消息直接启动一轮
418
+ 2. quest 正在运行时,后续用户消息先进入队列
419
+ 3. 只有 agent 调用 `artifact.interact(...)` 时,这些排队消息才会被真正投递
420
+
421
+ 持久化文件在 quest 内:
80
422
 
81
423
  - `.ds/runtime_state.json`
82
424
  - `.ds/user_message_queue.json`
83
425
  - `.ds/interaction_journal.jsonl`
84
426
  - `.ds/events.jsonl`
85
427
 
86
- ## Pause / Stop / Resume
428
+ 这意味着:
429
+
430
+ - 你追加的一句补充,不一定在 1 秒内就被 agent 看见
431
+ - 但它没有丢,只是进入邮箱,等待下一次交互点被投递
432
+
433
+ ## 14. Pause / Resume / Stop 怎么理解
87
434
 
88
- Quest 级控制:
435
+ - `/pause`:中断当前 runner,把 quest 置为 `paused`
436
+ - `/resume`:把 `paused` 或 `stopped` 的 quest 拉回 `active`
437
+ - `/stop`:更强的中断,把 quest 置为 `stopped`
89
438
 
90
- - `/pause`:中断当前 runner,并将 quest 标记为 `paused`。
91
- - `/resume`:把 `paused` 或 `stopped` 的 quest 重新置为 `active`。
92
- - `/stop`:更强的中断;清理 `active_run_id`,把 quest 标记为 `stopped`。
93
- - `/pause`、`/resume`、`/stop` 会写入一条可见的控制事件到 quest 历史,并按路由策略推送到绑定的 connectors。
439
+ `/stop` `/pause` 更强,因为:
94
440
 
95
- `/stop` 比 `/pause` 更强:
441
+ - 未投递的邮箱消息会被取消
442
+ - 旧消息不会在下一轮被静默重放
443
+ - 但 Git 分支、工作树、已经写过的文件都保留
444
+
445
+ 所以如果你只是“先停一下”,优先用 `/pause`。
446
+ 如果你要明确切断当前一轮,优先用 `/stop`。
447
+
448
+ ## 15. 排错
449
+
450
+ ### 问题 1:我进了 TUI,但输入普通文本没反应
451
+
452
+ 先检查:
453
+
454
+ - 你是不是还在 `request mode`
455
+ - 你有没有先 `/use <quest_id>` 或 `/new <goal>`
456
+
457
+ 如果没有绑定 quest,普通文本不会自动发出去。
458
+
459
+ ### 问题 2:QQ 的 `Detected OpenID` 一直为空
460
+
461
+ 按顺序排查:
462
+
463
+ 1. 你有没有先保存 `App ID / App Secret`
464
+ 2. 你有没有真的从 QQ 发过第一条私聊
465
+ 3. 你有没有等一次自动刷新,或者按 `Ctrl+R`
466
+
467
+ ### 问题 3:我在 `/config qq` 里能看到 target,但没有绑定动作
468
+
469
+ 通常是因为:
470
+
471
+ - 你当前没有 active quest
472
+
473
+ 先:
474
+
475
+ ```text
476
+ /use <quest_id>
477
+ ```
478
+
479
+ 再回到:
480
+
481
+ ```text
482
+ /config qq
483
+ ```
96
484
 
97
- - 未投递的邮箱消息会被取消(但会保留审计记录,如 `cancelled_by_stop`)
98
- - 当前轮启动消息会记录为 `accepted_by_run`
99
- - stop 后下一条新用户消息会启动新的一轮,不会静默重放旧队列
100
- - stop 不会改写 Git:当前分支/工作树/已写文件都保留,便于继续接续
485
+ ### 问题 4:微信二维码扫了,但页面没回去
101
486
 
102
- 守护进程级 stop:
487
+ 先看:
103
488
 
104
- - `ds --stop`:停止守护进程
105
- - 会尽量先优雅退出;必要时升级到 `SIGTERM`/`SIGKILL`
106
- - 成功停止后会清理 daemon state,并打印 `DeepScientist daemon stopped.`
489
+ - 手机里是否真的确认了登录
490
+ - 当前 daemon 是否还在线
107
491
 
108
- ## Artifact 交互要求
492
+ 如果不确定,按 `Ctrl+R` 强制刷新一次。
109
493
 
110
- agent 应当把 `artifact.interact(...)` 作为长对话的“脊柱”:
494
+ ### 问题 5:Lingzhu 已经填了,但设备还是不通
111
495
 
112
- - `progress` / `milestone`:线程式进度更新(非阻塞)
113
- - `decision_request`:阻塞式决策请求(需给出 1~3 个选项、利弊、证据)
496
+ 先确认:
114
497
 
115
- ## 排错
498
+ - `Public base URL` 是公网可达地址
499
+ - 不是 `localhost` / `127.0.0.1` / 内网地址
500
+ - Rokid 平台里填的是顶部 guide 给出的值,而不是本地地址
116
501
 
117
- 若你发送消息后 TUI 看起来“没反应”:
502
+ ## 16. 最后给一个简单判断标准
118
503
 
119
- - 确认是否绑定了 quest
120
- - 用 `/status` 查看 quest 状态
121
- - 查看 `.ds/runtime_state.json`(`status`、`active_run_id`、`pending_user_message_count`)
122
- - 查看 `.ds/events.jsonl` 是否有 `runner.turn_error`、`quest.control`、`artifact.recorded`
504
+ 如果你想判断自己是否真的“会用 TUI 跑通流程”,看下面四条是否都能做到:
123
505
 
124
- 若“运行中”时发送的补充消息没有被 agent 看到:
506
+ 1. 你能从 `request mode` 创建或绑定 quest
507
+ 2. 你能在 `quest mode` 给当前 quest 发消息并看状态
508
+ 3. 你能在 `/config` 里把至少一个 connector 配好
509
+ 4. 你知道 connector 配好不等于 quest 已绑定,并且你知道在哪里做 quest 绑定
125
510
 
126
- - 看 quest 是否仍在运行
127
- - 看 `.ds/user_message_queue.json`
128
- - 确认 agent 过程中有调用 `artifact.interact(...)`
511
+ 如果这四条都能做到,TUI 的主流程你就已经跑通了。
package/docs/zh/README.md CHANGED
@@ -76,6 +76,8 @@ DeepScientist 灵活且易于使用,支持:
76
76
 
77
77
  - [00 快速开始](./00_QUICK_START.md)
78
78
  从安装、启动,到创建第一个项目,先看这一篇。
79
+ - [05 TUI 端到端指南](./05_TUI_GUIDE.md)
80
+ 如果你主要在服务器或终端里工作,这篇会带你从 `ds --tui` 一路走到 quest、connector 和跨端协作跑通。
79
81
  - [15 Codex Provider 配置](./15_CODEX_PROVIDER_SETUP.md)
80
82
  如果你准备通过 MiniMax、GLM、火山方舟、阿里百炼或其他 Codex profile 来运行 DeepScientist,先看这一篇。
81
83
  - [12 引导式工作流教程](./12_GUIDED_WORKFLOW_TOUR.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@researai/deepscientist",
3
- "version": "1.5.13",
3
+ "version": "1.5.14",
4
4
  "description": "DeepScientist is not just a fully open-source autonomous scientific discovery system. It is also a research map that keeps growing from every round.",
5
5
  "license": "Apache-2.0",
6
6
  "files": [
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "deepscientist"
7
- version = "1.5.13"
7
+ version = "1.5.14"
8
8
  description = "DeepScientist Core skeleton"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -5,4 +5,4 @@ __all__ = ["__version__"]
5
5
  try:
6
6
  __version__ = _package_version("deepscientist")
7
7
  except PackageNotFoundError: # pragma: no cover - source checkout fallback
8
- __version__ = "1.5.13"
8
+ __version__ = "1.5.14"