@researai/deepscientist 1.5.15 → 1.5.16

package/docs/en/19_EXTERNAL_CONTROLLER_GUIDE.md

@@ -0,0 +1,226 @@
+# 19 External Controller Guide
+
+DeepScientist already exposes enough durable state to support an outer orchestration layer without patching core runtime code.
+
+This guide explains the minimal public pattern for external controllers that:
+
+- inspect recent quest state
+- decide whether the current run should continue
+- enqueue a routed follow-up message through the quest mailbox
+- optionally stop the current run through `quest_control`
+- record a durable report explaining why the guard fired
+
+This is intentionally lighter than a plugin framework.
+
+## When to use an external controller
+
+Use an external controller when the rule is:
+
+- project-specific
+- expensive to hard-code into global prompts or skills
+- better treated as outer governance than as core runtime behavior
+
+Examples:
+
+- publishability admission rules before paper-facing writing
+- repeated figure-polish loops that monopolize the frontier
+- lab-specific stop / branch policies
+
+## Public contracts you can rely on
+
+The safest extension surface is the existing durable runtime contract:
+
+- quest mailbox
+  - queued user-facing messages are stored under `.ds/user_message_queue.json`
+- recent quest state
+  - runtime state, artifact state, and connector-visible outputs are already durable files
+- daemon quest control
+  - `POST /api/quests/<quest_id>/control`
+- connector-visible durable reports
+  - write your own report under the quest tree so the next turn can cite it
+
+Prefer these contracts over prompt patching, private monkey-patching, or editing installed package files.
+
+## Minimal controller loop
+
+An external controller usually follows this sequence:
+
+1. Read the latest durable quest state.
+2. Decide whether a guard condition is active.
+3. Write a durable report describing:
+   - what was observed
+   - why it matters
+   - the recommended next route
+4. If intervention is needed:
+   - optionally stop the current run through `quest_control`
+   - enqueue one clear routed mailbox message for the next turn
+
+The mailbox message should explain the conclusion, not dump raw logs.
+
+## Example control flow
+
+```text
+read quest state
+-> detect low-yield loop or route violation
+-> write durable report
+-> stop current run if needed
+-> enqueue one mailbox message with the required next route
+```
+
+## Example `quest_control` request
+
+```bash
+curl -X POST http://127.0.0.1:20999/api/quests/<quest_id>/control \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "action": "stop",
+    "source": "external-controller"
+  }'
+```
+
+## Example mailbox intervention shape
+
+The exact queue file is runtime-owned, so your controller should preserve the existing schema and only append a normal user-style message payload.
+
+The message content should be short and actionable, for example:
+
+```text
+Hard control message from external orchestration layer: stop the current figure loop.
+Return to the main line and do one bounded route next:
+1. literature scout
+2. reference expansion
+3. manuscript body revision
+```
+
+## Example controllers you can adapt
+
+### Example 1: publishability admission guard
+
+This controller is useful when a quest is drifting into paper-facing writing before the evidence line is ready.
+
+Typical inputs:
+
+- the latest verification note
+- the current draft / summary state
+- recent baseline or utility results
+
+Typical stop condition:
+
+- the claimed paper direction still has weak support
+- one or more mandatory evidence items are still missing
+
+Typical intervention:
+
+1. Write `reports/publishability_guard.md` explaining the missing support.
+2. Stop the current write-heavy run through `quest_control`.
+3. Enqueue one mailbox message that routes the next turn back to `idea`, `analysis`, or a bounded evidence-repair step.
+
+Example mailbox text:
+
+```text
+External controller: do not continue manuscript-facing writing yet.
+Reason: the current evidence line does not pass the publishability admission gate.
+Next route: return to one bounded evidence-building step before write resumes.
+```
+
+### Example 2: figure-loop guard
+
+This controller is useful when the frontier is monopolized by repeated reopen / polish cycles on the same figure.
+
+Typical inputs:
+
+- recent figure artifact history
+- repeated reopen events
+- the latest review or summary note
+
+Typical stop condition:
+
+- the same figure has been reopened multiple times without improving the main claim
+- the next useful action is no longer figure polish, but evidence repair or manuscript revision
+
+Typical intervention:
+
+1. Write `reports/figure_loop_guard.md` summarizing the loop.
+2. Stop the current figure branch if needed.
+3. Enqueue one mailbox message that names exactly one next route.
+
+Example mailbox text:
+
+```text
+External controller: stop the current figure-polish loop.
+Reason: repeated reopen cycles are no longer improving the main evidence line.
+Next route: return to one bounded manuscript or analysis task.
+```
+
+## Example connector customization surface
+
+The control logic should stay connector-agnostic. In practice, adapting the same controller to a different connector usually means changing only the message profile, not the stop logic or durable report contract.
+
+For example:
+
+```yaml
+connector_profiles:
+  weixin:
+    summary_style: concise
+    max_route_options: 2
+    include_report_path: true
+  telegram:
+    summary_style: concise
+    max_route_options: 3
+    include_report_path: true
+  studio:
+    summary_style: detailed
+    max_route_options: 4
+    include_report_excerpt: true
+```
+
+The controller decision stays the same:
+
+- read durable state
+- decide whether to stop
+- write a durable report
+- enqueue one routed mailbox message
+
+What changes per connector is only how much detail you surface to the human operator.
+
+## Durable report shape
+
+Keep reports simple and auditable.
+
+A good report usually includes:
+
+- `generated_at`
+- `quest_id`
+- `status`
+- `recommended_action`
+- `blockers`
+- `evidence_summary`
+
+Markdown plus a machine-readable JSON companion is a practical pattern.
+
+## What not to rely on
+
+Avoid building controllers that depend on:
+
+- private prompt text offsets
+- internal temporary logs that are not documented durable state
+- patching installed package files inside `site-packages`
+- undocumented frontend-only state
+
+If a controller needs one of those, the contract is not stable enough yet.
+
+## Design recommendations
+
+- keep each controller focused on one question
+- prefer additive reports over hidden side effects
+- stop only when the next routed action is clear
+- keep domain- or lab-specific policy outside core defaults
+- treat external controllers as optional governance, not as required runtime plumbing
+
+## Good first controllers
+
+If you want to start small, begin with one of these:
+
+- a publishability admission guard for paper-mode quests
+- a figure-loop guard that stops repeated reopen cycles
+- a route-drift guard that blocks accidental `write` transitions before evidence is ready

package/docs/en/19_LOCAL_BROWSER_AUTH.md

@@ -0,0 +1,70 @@
+# Local Browser Auth
+
+DeepScientist can optionally protect the local web workspace with a generated 16-character password.
+
+This protection is local-first:
+
+- it applies to the browser UI
+- it also applies to `/api/*` requests from the browser
+- it is disabled by default unless you launch with `ds --auth true` or set `ui.auth_enabled: true`
+
+## What Happens On Startup
+
+When you run `ds --auth true`, DeepScientist starts the daemon and prints two important things in the terminal:
+
+- the local browser URL, such as `http://127.0.0.1:20999`
+- the generated local access password for that launch
+
+The browser URL is no longer expected to carry `?token=...`.
+
+If the browser is not already authenticated, DeepScientist shows a password modal on top of the landing page before it loads quests, docs, settings, or workspace data.
+
+## How To View The Password
+
+Use either of these:
+
+```bash
+ds --status
+```
+
+Read the `auth_token` field from the JSON output, or look at the terminal where `ds` was started.
+
+## How Login Persistence Works
+
+After the first successful login:
+
+- the browser stores the local auth state
+- later visits from the same browser usually open directly
+- restarting or reusing the managed daemon can rotate the password again
+
+If the password rotates, the browser will be asked to log in again.
+
+## How To Disable It
+
+Enable the browser password gate for one launch:
+
+```bash
+ds --auth true
+```
+
+In that mode:
+
+- the password modal is enabled
+- browser requests to `/api/*` require the local auth token
+
+To disable it again explicitly for one launch:
+
+```bash
+ds --auth false
+```
+
+In that mode:
+
+- the password modal is disabled
+- browser requests to `/api/*` do not require the local auth token
+
+## Practical Notes
+
+- This is not intended as internet-grade authentication. It is a local browser gate for machines you control.
+- If you share the machine or expose the port remotely, enable auth explicitly.
+- If you script against the local daemon from a browser client, authenticate first or disable auth explicitly for that launch.

package/docs/en/20_WORKSPACE_MODES_GUIDE.md

@@ -0,0 +1,250 @@
+# 20 Workspace Modes Guide: Copilot vs Autonomous
+
+This page explains the two normal project-start modes in DeepScientist:
+
+- `Copilot`
+- `Autonomous`
+
+Use this when:
+
+- you are about to create a new project
+- you are unsure which launch mode to choose
+- you want to understand why one project waits for you while another starts moving immediately
+
+If you only want the shortest install-and-launch path, read [00 Quick Start](./00_QUICK_START.md) first.
+
+If you want the exact startup payload and form field contract, read [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md) after this page.
+
+## 1. One-sentence summary
+
+- `Copilot`: quiet start, user-directed, stops after the current requested unit unless you ask it to continue
+- `Autonomous`: standard DeepScientist, keeps pushing the quest forward on its own
+
+## 2. Where You Choose This
+
+On the home / projects surface, start a new project and then choose the start style:
+
+- `Copilot Mode`
+- `Autonomous Mode`
+
+Current UI wording may appear in two layers:
+
+- outer launcher step: `Start Research` or `Start Experiment`
+- mode picker title: `Choose the start style`
+
+After that choice, the two flows diverge.
+
+## 3. Copilot Mode
+
+### 3.1 What it is
+
+Copilot mode is the user-directed workspace.
+
+It is for cases where you want DeepScientist to help actively, but you still want to steer each unit of work:
+
+- inspect a repo
+- read a paper
+- debug code
+- design an experiment
+- check a running process
+- rewrite a section
+- summarize a result
+
+The system should not assume that one request means “run the whole autonomous research loop”.
+
+### 3.2 What happens after creation
+
+After you create a Copilot project:
+
+- the project is created
+- the quest stays idle
+- the agent waits for your first real instruction
+
+In practical terms:
+
+- there is no immediate autonomous launch
+- no baseline / experiment / writing loop starts just because the project exists
+- the first substantial action begins when you send the first message
+
+### 3.3 Continuation behavior
+
+Copilot mode is intentionally conservative about continuation.
+
+After the current requested unit is complete, DeepScientist should normally:
+
+- summarize what changed
+- preserve context durably
+- wait for your next message or `/resume`
+
+This is the right mode when you want:
+
+- tight human control
+- short request-scoped help
+- less background churn
+- clearer handoff points
+
+### 3.4 Good fit
+
+Choose `Copilot` when:
+
+- you want to inspect before launching expensive work
+- the task is still ambiguous
+- you expect to iterate interactively
+- you want DeepScientist to behave more like a strong research IDE partner than a long-running autonomous operator
+
+### 3.5 Bad fit
+
+Avoid `Copilot` when:
+
+- you already know the quest should keep running for hours
+- you want detached experiments, monitoring, and follow-up routing without repeated user nudges
+- the goal is full quest ownership, not request-by-request collaboration
+
+## 4. Autonomous Mode
+
+### 4.1 What it is
+
+Autonomous mode is the standard DeepScientist path.
+
+It is meant for quests where the system should keep making ordinary route choices on its own and continue until the next real checkpoint is reached.
+
+This is the right mode for:
+
+- baseline establishment
+- long experiments
+- analysis campaigns
+- durable writing / finalize loops
+- connector-facing project progress over time
+
+### 4.2 What happens after creation
+
+After you create an Autonomous project:
+
+- the quest is created
+- the first turn is launched immediately
+- the system begins turning the startup contract into real work
+
+This may mean:
+
+- reading the baseline and references
+- checking environment and constraints
+- preparing scripts
+- selecting the next route
+- launching detached `bash_exec` work
+
+### 4.3 Continuation behavior
+
+Autonomous mode has two practical continuation regimes.
+
+#### A. No real long-running external task yet
+
+If no real long-running external task exists yet, DeepScientist should not park.
+
+It should keep using the next turns to:
+
+- prepare the real task
+- launch the real task
+- or make a durable route decision about what the real next task must be
+
+This is the “active preparation / launch” phase.
+
+#### B. A real long-running external task is already active
+
+Once a real detached task is already running, continuation changes shape.
+
+At that point, DeepScientist should not busy-loop through rapid model turns just to imitate continuous execution.
+
+Instead:
+
+- the real work should remain alive in detached `bash_exec` sessions or the runtime process they launched
+- agent turns become lower-frequency monitoring / synthesis passes
+- the current default monitoring cadence is roughly every `240` seconds
+
+This is the “background progress monitoring” phase.
+
+### 4.4 Good fit
+
+Choose `Autonomous` when:
+
+- the quest should keep moving on its own
+- you expect real long-running experiment or analysis work
+- you want DeepScientist to keep routing after milestones
+- you want the standard research-operating-system behavior
+
+### 4.5 Bad fit
+
+Avoid `Autonomous` when:
+
+- you only want a quiet project shell first
+- you want to inspect the repo manually before any real movement
+- you want every next unit to be explicitly user-directed
+
+## 5. The Most Important Practical Difference
+
+The easiest way to remember the split is:
+
+- `Copilot` asks: “What single useful unit should I help with right now?”
+- `Autonomous` asks: “What is the next real quest step, and how do I keep the quest moving?”
+
+That difference matters more than the labels themselves.
+
+## 6. How Resume Works
+
+Both modes preserve context durably, but they resume differently.
+
+On later turns, DeepScientist now carries a compact resume spine that can include:
+
+- the latest durable user message
+- the latest assistant checkpoint
+- the latest run summary
+- recent memory cues
+- current `bash_exec` state
+
+But the continuation policy still differs:
+
+- `Copilot`: resume only when you speak again or explicitly resume
+- `Autonomous`: keep going unless a real blocker or explicit waiting state applies
+
+## 7. Choosing Quickly
+
+Use this fast rule:
+
+1. If you want the project to wait quietly until you tell it what to do, choose `Copilot`.
+2. If you want DeepScientist to begin turning the quest contract into real work immediately, choose `Autonomous`.
+3. If you are unsure, start with `Copilot`; you can still move into longer-running work once the route is clearer.
+
+## 8. Common Misunderstandings
+
+### “Autonomous means it should always spin rapidly”
+
+No.
+
+Autonomous means the quest should keep moving.
+
+When there is no real long-running task yet, that can mean rapid preparation / launch turns.
+When a real long-running task is already active, it should usually mean lower-frequency monitoring, not constant model churn.
+
+### “Copilot means it cannot run experiments”
+
+Also no.
+
+Copilot can still help launch, inspect, analyze, and write.
+The difference is that it should not assume long autonomous continuation unless you ask for it.
+
+### “The two modes only change wording”
+
+No.
+
+They affect:
+
+- initial launch behavior
+- continuation policy
+- when the quest parks
+- how much autonomous routing is appropriate
+
+## 9. Related Docs
+
+- [00 Quick Start](./00_QUICK_START.md)
+- [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
+- [12 Guided Workflow Tour](./12_GUIDED_WORKFLOW_TOUR.md)
+- [14 Prompt, Skills, and MCP Guide](./14_PROMPT_SKILLS_AND_MCP_GUIDE.md)

package/docs/en/README.md

@@ -4,6 +4,8 @@ DeepScientist is not just a long-running autonomous scientific discovery system.
 
 2 minutes to install. 2 minutes to bind Weixin. 2 minutes to launch. Extremely fast and easy to use.
 
+Local Web access now starts without a password gate by default. If you want a generated 16-character browser password for one launch, run `ds --auth true`; DeepScientist then prints the password in the terminal and the browser can reuse the stored login after the first successful entry.
+
 It is also a workshop-style collaboration environment: let it keep moving autonomously, or step in anytime to collaborate, edit code, run the terminal yourself, or keep notes and plans in a Notion-style workspace.
 
 Use DeepScientist anywhere: on the server through TUI, in the browser through Web, on the phone through Weixin or QQ, and even on glasses through Rokid Glasses.
@@ -30,6 +32,10 @@ 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.
+- [20 Workspace Modes Guide](./20_WORKSPACE_MODES_GUIDE.md)
+  Read this if you want to choose correctly between Copilot and Autonomous before creating a project.
+- [19 Local Browser Auth](./19_LOCAL_BROWSER_AUTH.md)
+  Read this if you want to understand the local password prompt, where to find the password, and how to disable it.
 - [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)
@@ -43,6 +49,8 @@ This page is the shortest path to the right document.
 
 - [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
   Explains the current frontend fields, derived contract fields, and practical examples.
+- [20 Workspace Modes Guide](./20_WORKSPACE_MODES_GUIDE.md)
+  Use this when the main question is not “how do I fill the form?” but “should this project start as Copilot or Autonomous?”.
 - [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
   Use this when you need to configure runners, connectors, runtime defaults, or home paths.
 - [11 License And Risk Notice](./11_LICENSE_AND_RISK.md)
@@ -73,6 +81,8 @@ This page is the shortest path to the right document.
   Explains how the daemon, workspace, canvas, and connector views fit together.
 - [07 Memory and MCP](./07_MEMORY_AND_MCP.md)
   Explains memory, artifacts, and built-in MCP behavior.
+- [19 External Controller Guide](./19_EXTERNAL_CONTROLLER_GUIDE.md)
+  Shows how to build optional outer-orchestration guards on top of mailbox and `quest_control` without patching core runtime code.
 
 ## If something is broken
 
@@ -89,3 +99,11 @@ This page is the shortest path to the right document.
   High-level system contracts and repository structure.
 - [91 Development](./91_DEVELOPMENT.md)
   Maintainer-facing workflow and implementation notes.
+
+## Community
+
+Welcome to join the WeChat group for discussion.
+
+<p align="center">
+  <img src="../../assets/readme/wechat.jpg" alt="DeepScientist WeChat group" width="360" />
+</p>