@researai/deepscientist 1.5.13 → 1.5.14

package/docs/en/05_TUI_GUIDE.md

@@ -1,141 +1,511 @@
-# 05 TUI Guide: Use the Terminal Interface
+# 05 TUI End-To-End Guide: Run The Full Flow In Terminal
 
-This document is the single repo-level reference for the current DeepScientist TUI workflow.
+This guide is for one concrete goal:
 
-For the current runtime control flow, prompt/skill execution model, MCP surface, and Canvas reconstruction logic, also see `docs/en/06_RUNTIME_AND_CANVAS.md`.
+- start from `ds --tui`
+- understand which mode the TUI is in
+- create or switch quests correctly
+- configure QQ, Weixin, and Lingzhu from the TUI
+- bind the right connector target to the current quest
+- continue the same quest across TUI, Web, QQ, Weixin, and Rokid without losing context
 
-## Install And Start
+If you want the lower-level runtime and Canvas details afterward, also read [06 Runtime and Canvas](./06_RUNTIME_AND_CANVAS.md).
 
-Use the current workspace install:
+## 1. Learn The Three TUI Surfaces First
+
+The current TUI is not just one chat box. It moves between three working surfaces:
+
+1. `home / request mode`
+   The current terminal session is not bound to a quest yet.
+   You can preview quests, create a new quest, and open config, but plain text does not go to any quest.
+2. `quest mode`
+   The current terminal session is already bound to one quest.
+   Plain text becomes a normal user message for that quest.
+3. `config mode`
+   You are browsing local config, quest config, or connector config.
+   This mode is mainly operated with `↑/↓`, `Enter`, and `Esc`.
+
+In practice:
+
+- `home` is for choosing work
+- `quest` is for advancing work
+- `config` is for wiring external collaboration surfaces and editing configuration
+
+## 2. Install And Start
+
+From the repository root:
 
 ```bash
 uv sync
 npm install
 ```
 
-Common launcher commands:
+The most common start command:
 
 ```bash
-ds
 ds --tui
+```
+
+Also useful:
+
+```bash
+ds
 ds --both
 ds --status
 ds --stop
 ```
 
-Notes:
-
-- `ds` starts the managed daemon, prints the local web URL, tries to open the browser, and exits.
-- `ds --tui` starts daemon plus the Ink-based terminal workspace.
-- `ds --both` starts the daemon, opens the web workspace, and keeps the terminal workspace attached.
-- `ds --stop` stops the managed daemon itself, not just one quest.
-- `python -m deepscientist.cli ...` remains available for low-level commands, but the launcher is the normal path.
-- from a source checkout, `node bin/ds.js` behaves the same as `ds`
-
-## Core TUI Flow
-
-Inside the TUI:
-
-- `/home`: leave the current quest and return to request mode.
-- `/projects`: open the quest browser.
-- `/use <quest_id>`: bind the current TUI session to one quest.
-- `/new`: create a quest from inside the TUI.
-- `/new <goal>` creates the quest and auto-starts it through the daemon.
-- `/delete <quest_id> --yes`: delete a quest (destructive; requires confirmation).
-- plain text: send a normal user message to the bound quest.
-- `/status`: inspect the current quest state.
-- `/graph`: inspect the current quest graph.
-- `/help`: show the in-TUI command list and control keys.
-- `/config`: open the local config browser.
-- `/pause`: pause the current quest; if no quest is bound, choose one in the panel.
-- `/resume`: resume the current quest; if no quest is bound, choose one in the panel.
-- `/stop`: stop the current quest; if no quest is bound, choose one in the panel.
-- `/stop <quest_id>`: stop a specific quest explicitly.
-- typing `/` in the input box shows a live command list; typing `/re`, `/co`, and similar prefixes filters the visible command rows
-- in home mode, `↑/↓` and `Tab` only change the selected quest preview; they do not hard-switch an already bound quest
-- in home mode, plain text does not create or send anything implicitly; use `/new <goal>` to create and `/projects` or `/use <quest_id>` to bind before chatting
-
-If you are already inside a quest, `/pause`, `/resume`, and `/stop` target that quest automatically.
-
-The footer and welcome banner also expose the main shortcuts directly:
-
-- `Enter`: send or confirm
-- `↑/↓`: browse selectors
-- `Esc`: close the active overlay
-- `Ctrl+O`: open the web workspace
+Meaning:
+
+- `ds`: start the daemon, print the local Web URL, try to open the browser, then exit.
+- `ds --tui`: start the daemon and enter the terminal workspace.
+- `ds --both`: open Web and TUI together.
+- `ds --status`: inspect daemon status.
+- `ds --stop`: stop the daemon itself, not just one quest.
+
+## 3. What To Look At First After Entering TUI
+
+When the TUI opens, the first useful signals are:
+
+- whether you are in `request mode` or `quest mode`
+- the local Web URL
+- which quests are available to switch to
+
+If the welcome area says `request mode`, the current terminal session is not bound to a quest yet.
+
+The correct next move is not plain text. Do one of these first:
+
+- create a new quest: `/new <goal>`
+- bind an existing quest: `/use <quest_id>`
+
+For example:
+
+```text
+/new Reproduce the current baseline and turn it into a comparable experiment plan
+```
+
+or:
+
+```text
+/use 001
+```
+
+## 4. Shortest Working Path: From Zero To The First Quest
+
+This is the first path I recommend.
+
+### Step 1. Start TUI
+
+```bash
+ds --tui
+```
+
+### Step 2. Create a quest
+
+Enter:
+
+```text
+/new Run the baseline in this repo once and tell me what configuration is still missing
+```
+
+The TUI will automatically switch into that new quest.
+
+### Step 3. Wait for the first run to start
+
+`/new <goal>` does not only create the quest. It also starts the first run.
+
+You should then see:
+
+- the quest is already bound
+- the history area starts showing messages, artifacts, or operations
+- the status line shows the active quest id
+
+### Step 4. Send one normal message
+
+For example:
+
+```text
+Stay narrow. First get the baseline running, then tell me exactly which settings are still missing.
+```
+
+That message goes to the currently bound quest.
+
+### Step 5. Check `/status` and `/graph`
+
+Useful commands:
+
+```text
+/status
+/graph
+```
+
+- `/status`: inspect the current quest state
+- `/graph`: inspect the quest graph and research progress
+
+### Step 6. Open Web anytime
+
+Inside TUI:
+
+- `Ctrl+O`: open the Web workspace for the current quest
+
+That matters because TUI and Web are looking at the same daemon, the same quest, and the same event stream.
+
+## 5. Most Useful Commands And Keys
+
+### Commands
+
+- `/home`: return to unbound request mode
+- `/projects`: open the quest browser
+- `/use <quest_id>`: bind to a specific quest
+- `/new <goal>`: create a new quest
+- `/delete <quest_id> --yes`: delete a quest
+- `/pause`: pause the current quest; if no quest is bound, open the selector
+- `/resume`: resume the current quest; if no quest is bound, open the selector
+- `/stop`: stop the current quest; if no quest is bound, open the selector
+- `/stop <quest_id>`: stop a specific quest explicitly
+- `/status`: inspect the current quest status
+- `/graph`: inspect the current quest graph
+- `/config`: open config
+- `/config connectors`: open the connector list directly
+- `/config qq`: open QQ config directly
+- `/config weixin`: open Weixin config directly
+- `/config lingzhu`: open Lingzhu config directly
+
+### Keys
+
+- `Enter`: send input or confirm the current selection
+- `↑/↓`: move selection
+- `Tab`: move forward in list selection
+- `Esc`: go back one layer or close the current panel
+- `Ctrl+R`: force refresh
+- `Ctrl+O`: open the Web workspace
+- `Ctrl+G`: open the config home directly
+- `Ctrl+B`: leave the current quest; if you are in config first, close config
 - `Ctrl+C`: quit the TUI
+- `Shift+↑/↓`: scroll the history area by one line
+- `PageUp/PageDown`: scroll the history area by one page
+
+## 6. Recommended Daily Rhythm
+
+If TUI is your main surface, keep this order:
+
+1. confirm whether a quest is already bound
+2. then send messages
+3. use `/projects` or `/use` when you need to switch quests
+4. before touching connectors, confirm which quest is current
+
+The reason is simple:
+
+- connector binding actions bind to the current quest
+- if you open `/config qq` without an active quest, TUI can save the connector config, but it cannot bind a detected runtime target to a quest for you
+
+So the normal order should be:
+
+1. `/new <goal>` or `/use <quest_id>`
+2. confirm you are in quest mode
+3. then open `/config qq`, `/config weixin`, or `/config lingzhu`
+
+## 7. The Right Order For Connector Setup In TUI
+
+The current best-practice order is:
+
+1. create or switch to the quest you want to continue
+2. open the connector detail page
+3. read the top guide first
+4. finish the platform-side action in that order
+5. come back to TUI and run save, refresh, or bind
+
+### Why the top guide matters now
+
+The connector detail header is no longer decorative text. It is the actual next-step instruction.
 
-## Message Delivery Model
+- `QQ`: it tells you to fill credentials first, then send the first private QQ message, then wait for OpenID and conversation targets to appear
+- `Weixin`: it tells you to create the QR code first and scan it with WeChat
+- `Lingzhu`: it tells you to set a public `public_base_url` first and then copy the generated values into Rokid
 
-The TUI, web UI, and connectors now share the same mailbox semantics.
+## 8. QQ: Run The Full Binding Chain In TUI
 
-1. The first plain user message for an idle quest starts a turn directly.
-2. That first launch message is claimed by the run and does not get re-delivered later through the mailbox.
-3. Later user messages that arrive while the agent is already running are written into `.ds/user_message_queue.json`.
-4. Those queued messages are delivered only when the agent calls `artifact.interact(...)`.
-5. When delivery happens, the agent receives the queued bundle as the latest user requirements and the queue entries move from `pending` to completed audit records.
-6. If there is no new user message and the quest is still unfinished, the runtime can auto-start another turn so the agent keeps advancing from durable state instead of idling.
-7. If there is no new user message, the runtime returns recent interaction records plus the instruction that the user did not send anything new.
+This is the easiest flow to misuse, so it needs its own section.
 
-Durable files used by this flow:
+### Recommended path
+
+1. enter the target quest first
+2. run `/config qq`
+3. read the top guide
+4. fill `Bot name`, `App ID`, and `App Secret`
+5. run `Save Connector`
+6. send the bot one private QQ message from your own QQ account
+7. return to TUI and wait for auto-refresh, or press `Ctrl+R`
+8. confirm that `Detected OpenID` and `Last conversation` are no longer empty
+9. use the target action shown below to bind the current quest to the correct QQ target
+
+### What you will see on the QQ page
+
+Usually two top sections matter:
+
+- `Top Guide`
+  This tells you what to do next.
+- `Current Status`
+  This tells you what step is still missing.
+
+Key fields:
+
+- `Detected OpenID`
+  This is learned automatically from runtime activity. It is not supposed to be typed first.
+- `Last conversation`
+  This is the latest conversation id seen by the runtime.
+- `Discovered targets`
+  These are the runtime targets that TUI can already use for quest binding.
+- `Profile · ...`
+  When QQ has multiple profiles, TUI now shows one runtime summary block per profile so you can see the detected OpenID, preferred target, current bound quest, and readiness state without switching back to Web first.
+
+### The right way to think about QQ binding
+
+There are two separate layers:
+
+1. save QQ bot credentials
+2. bind one runtime target to the current quest
+
+Finishing only layer 1 does not mean the flow is complete.
+
+A fully working QQ flow means:
+
+- `Detected OpenID` is visible
+- target actions are visible
+- the current quest is bound to the correct QQ target
+
+### Current TUI limits
+
+- if you have multiple QQ profiles, the TUI detail page still warns that profile add, delete, and credential replacement are raw-config tasks
+- adding or deleting multiple profiles is still better done in raw `connectors.yaml` or in Web settings
+- per-profile summaries and runtime target bindings are visible directly in TUI
+
+## 9. Weixin: Run The Full Binding Chain In TUI
+
+### Recommended path
+
+1. enter the target quest first
+2. run `/config weixin`
+3. choose `Bind Weixin` or `Rebind Weixin`
+4. TUI switches into the QR page
+5. scan with the target WeChat account on the phone
+6. confirm the login in WeChat
+7. after success, TUI returns to the detail page automatically
+8. confirm that `Bot account`, `Owner account`, and `Known targets` are refreshed
+
+### Current behavior that matters
+
+- you do not need to type a bot token manually
+- the QR code is generated directly inside TUI
+- after the QR login succeeds, the connector config is saved automatically
+
+### When the flow is actually done
+
+At minimum:
+
+- the detail page no longer looks unbound
+- `Bot account` is not empty
+- `Owner account` is not empty
+
+If you want to use Weixin to keep advancing a quest, bind the relevant Weixin conversation to that quest afterward.
+
+## 10. Lingzhu / Rokid: Run The Full Binding Chain In TUI
+
+The key point for Lingzhu is not "click once and finish". The TUI generates platform fields, and you copy them into Rokid.
+
+### Recommended path
+
+1. enter the target quest first
+2. run `/config lingzhu`
+3. set `Public base URL` to the final public address
+4. if needed, generate a new `Custom agent AK`
+5. read the generated Rokid fields shown on the detail page
+6. copy those values into the Rokid platform
+7. return to TUI and run `Save Connector`
+
+### What to watch carefully
+
+- `public_base_url` must be the final public `http(s)` address
+- `127.0.0.1`, `localhost`, and private LAN addresses are not valid for a real Rokid device
+- the detail page now shows the same Rokid-facing generated fields as the Web popup:
+  - `Custom agent ID`
+  - `Custom agent URL`
+  - `Custom agent AK`
+  - `Agent name`
+  - `Category`
+  - `Capability summary`
+  - `Opening message`
+  - `Input type`
+- use `PgUp` / `PgDn` if the full generated field list does not fit in one terminal screen
+
+### When the flow is actually done
+
+At minimum:
+
+- `Public base URL` is a public address
+- `Custom agent AK` is generated or filled
+- the fields shown in the top guide have been copied into Rokid
+- the connector has been saved
+
+## 11. Three Full Recommended Scripts
+
+If you want to run "create quest + configure connector + continue work" on a server through TUI, follow one of these.
+
+### Script A: QQ
+
+1. `ds --tui`
+2. `/new <goal>`
+3. wait for the quest to auto-start
+4. `/config qq`
+5. fill `Bot name / App ID / App Secret`
+6. `Save Connector`
+7. send one private QQ message to the bot
+8. return to TUI and confirm `Detected OpenID` plus a target are visible
+9. run the `Bind ...` action to bind the current quest to that QQ target
+10. continue through QQ, TUI, or Web
+
+### Script B: Weixin
+
+1. `ds --tui`
+2. `/new <goal>` or `/use <quest_id>`
+3. `/config weixin`
+4. `Bind Weixin`
+5. scan and confirm on the phone
+6. wait until TUI returns to the detail page
+7. confirm the binding fields are refreshed
+8. continue inside the quest
+
+### Script C: Lingzhu
+
+1. `ds --tui`
+2. `/new <goal>` or `/use <quest_id>`
+3. `/config lingzhu`
+4. update `Public base URL`
+5. generate or fill `Custom agent AK`
+6. copy the top guide values into Rokid
+7. `Save Connector`
+8. then do the device-side connectivity check
+
+## 12. TUI, Web, And Connectors Are The Same Quest
+
+This point matters.
+
+These TUI actions:
+
+- `/new`
+- `/use`
+- plain messages
+- `/pause`, `/resume`, `/stop`
+- connector binding
+
+all write into the same daemon and the same durable quest state.
+
+So:
+
+- a quest created in TUI is visible in Web immediately
+- a connector bound in TUI is visible in Web immediately
+- a conversation continued in QQ or Weixin returns to the same quest that TUI and Web see
+
+TUI is not a second state system. It is another surface over the same quest.
+
+## 13. Mailbox Semantics: Why The Agent May Not See A New Message Immediately
+
+TUI, Web, and connectors share the same mailbox semantics.
+
+Core rules:
+
+1. when a quest is idle, the first normal user message starts a turn directly
+2. while a quest is already running, later messages are queued first
+3. queued messages are only delivered when the agent calls `artifact.interact(...)`
+
+Durable quest files involved:
 
 - `.ds/runtime_state.json`
 - `.ds/user_message_queue.json`
 - `.ds/interaction_journal.jsonl`
 - `.ds/events.jsonl`
 
-## Stop, Pause, Resume
+So:
+
+- a follow-up sentence may not reach the agent within one second
+- it is not lost; it is waiting in the mailbox for the next interaction point
 
-Quest-level control:
+## 14. How To Think About Pause / Resume / Stop
 
-- `/pause` interrupts the active runner and marks the quest as `paused`.
-- `/resume` moves a `paused` or `stopped` quest back to `active`.
-- `/stop` interrupts the active runner, clears `active_run_id`, and marks the quest as `stopped`.
-- `/pause`, `/resume`, and `/stop` also append a visible assistant-side control notice into the quest chat history and push the same notice to bound connectors using the normal connector routing policy.
+- `/pause`: interrupt the current runner and mark the quest as `paused`
+- `/resume`: move a `paused` or `stopped` quest back to `active`
+- `/stop`: a stronger interruption that marks the quest as `stopped`
 
-`/stop` semantics are intentionally stronger than `/pause`:
+`/stop` is stronger than `/pause` because:
 
-- queued but not yet delivered user mailbox messages are cancelled
-- those cancelled messages are preserved in the queue audit trail with terminal status fields such as `cancelled_by_stop`
-- the currently executing launch message is recorded as `accepted_by_run`
-- the next user message after stop starts a fresh turn in the same quest context without silently replaying stale queued text
-- stop does not rewrite Git state: the current branch, worktree, and already written files remain in place, so follow-up work resumes from the same repository context
+- undelivered mailbox messages are cancelled
+- stale messages are not silently replayed on the next turn
+- but Git branches, worktrees, and already written files remain intact
 
-Daemon-level stop:
+So if you only want to pause for a while, prefer `/pause`.
+If you want to cut off the current turn clearly, prefer `/stop`.
+
+## 15. Troubleshooting
+
+### Problem 1: I entered TUI, but plain text does nothing
+
+Check first:
+
+- are you still in `request mode`
+- did you run `/use <quest_id>` or `/new <goal>` first
+
+Without a bound quest, plain text is not sent.
+
+### Problem 2: `Detected OpenID` stays empty in QQ
+
+Check in order:
+
+1. did you save `App ID / App Secret` first
+2. did you really send the bot the first private QQ message
+3. did you wait for one refresh cycle or press `Ctrl+R`
+
+### Problem 3: I can see QQ targets, but there is no bind action
+
+Usually that means:
+
+- there is no active quest right now
+
+Run:
+
+```text
+/use <quest_id>
+```
+
+Then go back to:
+
+```text
+/config qq
+```
 
-- `ds --stop` shuts down the managed daemon
-- it validates both `home` and `daemon_id` before touching the daemon
-- it first asks the daemon to stop cleanly
-- if needed it escalates to `SIGTERM`, then `SIGKILL`
-- if shutdown succeeds, the launcher clears the daemon state file and prints `DeepScientist daemon stopped.`
-- a clean daemon shutdown stops any actively running quests first, emits the same stop notice, and leaves Git/worktree state untouched for the next daemon start
+### Problem 4: I scanned the Weixin QR code, but the page did not return
 
-## Artifact Interaction Expectations
+Check:
 
-The agent should use `artifact.interact(...)` as the long-lived conversation thread:
+- whether the login was really confirmed on the phone
+- whether the daemon is still online
 
-- `progress` and `milestone` updates are threaded, non-blocking status messages
-- `decision_request` is the blocking form
-- a blocking decision request should provide 1 to 3 concrete options, explain pros and cons, wait up to 1 day when feasible, then self-resolve and notify the user if the timeout expires
-- true quest completion is separate from a normal decision request: the agent should first ask for explicit completion approval with `reply_schema.decision_type = quest_completion_approval`, and only then call `artifact.complete_quest(...)`
+If unsure, press `Ctrl+R` once.
 
-## Troubleshooting
+### Problem 5: Lingzhu is filled, but the device still cannot connect
 
-If the TUI looks idle after you send text:
+Confirm:
 
-- confirm the quest is actually bound
-- check the quest status with `/status`
-- inspect `.ds/runtime_state.json` for `status`, `active_run_id`, and `pending_user_message_count`
-- inspect `.ds/events.jsonl` for `runner.turn_error`, `quest.control`, or `artifact.recorded`
+- `Public base URL` is publicly reachable
+- it is not `localhost`, `127.0.0.1`, or a private LAN address
+- the Rokid platform is using the values shown in the top guide, not a local address
 
-If a follow-up user message does not seem to reach the agent:
+## 16. A Simple Final Check
 
-- check whether the quest is currently running
-- inspect `.ds/user_message_queue.json`
-- confirm the agent is calling `artifact.interact(...)` during long work
+If you want to know whether you can really run the TUI flow end to end, check whether all four are true:
 
-If stop appears ineffective:
+1. you can create or bind a quest from `request mode`
+2. you can send messages and inspect status in `quest mode`
+3. you can configure at least one connector inside `/config`
+4. you understand that "connector saved" is not always the same as "quest bound", and you know where the quest binding action lives
 
-- use `/stop` inside the quest first
-- verify the quest becomes `stopped`
-- for a full daemon shutdown use `ds --stop`
+If all four are true, you can already run the main TUI workflow end to end.

package/docs/en/README.md

@@ -30,6 +30,8 @@ This page is the shortest path to the right document.
 
 - [00 Quick Start](./00_QUICK_START.md)
   Start here if you want to install DeepScientist, launch it locally, and create your first project.
+- [05 TUI Guide](./05_TUI_GUIDE.md)
+  Read this if your main surface is the terminal and you want one end-to-end path through `ds --tui`, quests, connectors, and cross-surface work.
 - [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
   Read this when you want to run DeepScientist through MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another Codex profile.
 - [12 Guided Workflow Tour](./12_GUIDED_WORKFLOW_TOUR.md)