@researai/deepscientist 1.5.8 → 1.5.11

package/docs/en/11_LICENSE_AND_RISK.md

@@ -0,0 +1,256 @@
+# 11 License And Risk Notice
+
+This document does two things:
+
+1. clarifies the DeepScientist open-source license and responsibility boundary
+2. lists the main risks that you, not the project maintainers, must control
+
+This is not legal advice. If you plan to use DeepScientist in a company environment, production environment, external-facing service, or regulated workflow, have your own legal, security, and operations teams review it again.
+
+## 1. License And Responsibility Boundary
+
+DeepScientist is released under the Apache License 2.0.
+
+The full license text is in the repository root:
+
+- [LICENSE](../../LICENSE)
+
+The practical meaning is:
+
+- DeepScientist is distributed under Apache 2.0
+- DeepScientist is provided on an "AS IS" basis, without warranties
+- the project authors and maintainers are not responsible for any direct or indirect consequence caused by using, deploying, modifying, redistributing, or exposing DeepScientist
+- you are responsible for runtime environment control, permission boundaries, public exposure, third-party account binding, output review, data handling, and compliance
+
+In other words, DeepScientist is a high-capability automation system. It is not a managed service and it is not a security-audited guarantee layer. You must control the operating boundary yourself.
+
+## 2. Main Risk Areas
+
+These risks are real, and they compound each other.
+
+### 2.1 Host And Server Damage
+
+DeepScientist can drive models to execute commands, modify files, install dependencies, run scripts, and read or write project directories.
+
+That means it can:
+
+- delete, overwrite, or corrupt files
+- modify Git state, branches, or worktree contents
+- install the wrong dependency set or contaminate the runtime environment
+- remove logs, caches, experiment results, or intermediate outputs
+- consume GPU, CPU, disk, or network resources incorrectly
+- interfere with other services on the same machine, or even make a server unstable
+
+If you run it directly on a high-privilege host, production machine, shared development server, or a system holding important data, the risk increases substantially.
+
+### 2.2 Fabricated Results, Wrong Conclusions, And Research Risk
+
+DeepScientist is model-driven. It does not guarantee truth.
+
+It may:
+
+- fabricate metrics, logs, tables, or experiment results
+- invent citations, prior work summaries, or baseline comparisons
+- drift away from the intended task or evaluation protocol
+- produce analyses that sound plausible but are not reproducible
+- write conclusions that are too strong for the available evidence
+
+Any experiment result, paper text, chart, citation, conclusion, or reviewer response must be reviewed by a human before you treat it as trustworthy.
+
+### 2.3 Data Loss, Corruption, And Irreversible Changes
+
+Even without obvious malicious behavior, automation can still produce irreversible damage.
+
+Examples:
+
+- quest files get overwritten
+- uncommitted local edits get polluted
+- auto-generated files mix into final result directories
+- a bad script corrupts datasets or experiment folders at scale
+- an external connector receives outputs that should not have been sent
+
+If your data, projects, or paper drafts are not backed up, this kind of damage may be difficult to recover from.
+
+### 2.4 Secret, Credential, And Privacy Leakage
+
+DeepScientist may touch sensitive material such as:
+
+- API keys
+- environment variables
+- private repository locations
+- research data
+- connector tokens
+- WeChat, QQ, Lingzhu, or other external account bindings
+
+If you:
+
+- expose the site publicly
+- share the DeepScientist page casually
+- allow untrusted users into the runtime environment
+- send config files, logs, screenshots, or quest files that contain sensitive material
+
+you may leak:
+
+- model credentials
+- connector identities
+- WeChat or QQ messaging authority
+- project data, experiment material, or private content
+
+Once connectors are bound, the risk is no longer only "can someone open the page?" but also "can someone misuse the linked external account?"
+
+### 2.5 Public Exposure And Unauthorized Access
+
+If you bind DeepScientist to `0.0.0.0`, a public IP, a reverse proxy, a tunnel, or a public domain, you are exposing an automation-capable system to the outside.
+
+That can lead to:
+
+- unauthorized access
+- session probing or replay
+- misuse of connector callback or polling contexts
+- external visibility into project pages, settings pages, or logs
+- accidental disclosure of internal paths, ports, or service topology
+
+If WeChat, QQ, or other connectors are also bound, the impact is larger.
+
+Unless you fully understand the consequences, do not casually share the site address and do not expose the operational UI to uncontrolled users.
+
+### 2.6 Third-Party Platform And Account Compliance
+
+DeepScientist can integrate with QQ, WeChat, Lingzhu, and other external platforms.
+
+You are responsible for:
+
+- third-party platform terms-of-service risk
+- account suspension, rate-limit, restriction, or audit risk
+- abuse complaints caused by automated outbound messages
+- privacy and compliance issues caused by relaying data or files through those platforms
+
+The project maintainers do not guarantee that your usage will satisfy local law, internal policy, or platform rules.
+
+### 2.7 Malicious Inputs, Prompt Injection, And Supply-Chain Risk
+
+DeepScientist can read:
+
+- repositories
+- papers
+- web pages
+- issues, PRs, or READMEs
+- uploaded attachments
+- connector messages and files
+
+Any of those can contain:
+
+- malicious commands
+- prompt injection
+- misleading instructions
+- fake benchmarks
+- dependency installation steps with backdoors
+
+If the model follows those instructions, the resulting behavior can become much more dangerous.
+
+### 2.8 Resource, Cost, And Abuse Risk
+
+DeepScientist may run for a long time, call models repeatedly, download dependencies, execute experiments, and produce large numbers of files.
+
+You are responsible for:
+
+- API cost growth
+- GPU or CPU occupation
+- disk growth caused by logs, caches, artifacts, or datasets
+- long-running load, overheating, or service contention
+
+## 3. Minimum Safety Practices Strongly Recommended
+
+If you plan to use DeepScientist seriously, at least do the following.
+
+### 3.1 Prefer Docker Or Another Isolated Environment
+
+Strongly prefer running DeepScientist inside Docker, a virtual machine, or an equivalent isolation boundary instead of running it directly on a privileged host.
+
+The goal is simple:
+
+- reduce filesystem blast radius
+- reduce process privilege
+- reduce network exposure
+- reduce recovery cost when something goes wrong
+
+### 3.2 Always Use A Non-Root Account
+
+Strong recommendation:
+
+- run DeepScientist under a dedicated non-root user
+- do not start it as `root`
+- do not give it default write access to the whole machine
+- do not let it touch sensitive host directories by default
+
+If you must run it on a server, least privilege matters even more.
+
+### 3.3 Do Not Run It Directly On Production Or Critical Machines
+
+Avoid running DeepScientist directly on:
+
+- production database hosts
+- live business servers
+- control machines that store core source code and secrets
+- shared bastion hosts
+- desktops that hold important personal or commercial data
+
+### 3.4 Do Not Casually Share The Site Address Or Public Entry
+
+Unless you already have proper access control in place, do not:
+
+- post the DeepScientist URL in public groups
+- map a `0.0.0.0`-bound port directly to the public internet
+- publish an unauthenticated reverse-proxy address
+- give other people direct operational access to a runtime that already has connectors bound
+
+This is not only a page-viewing risk. It is also a credential and connector-authority leakage risk.
+
+### 3.5 Minimize Credential And Connector Privilege
+
+Recommended:
+
+- use separate test accounts for QQ, WeChat, or Lingzhu bindings
+- avoid exposing your highest-value primary accounts to experimental runtimes
+- do not keep every token in a single shared home directory
+- rotate keys and connector tokens regularly
+- keep outbound authority as narrow as possible
+
+### 3.6 Review Every Important Result Manually
+
+Do not directly trust:
+
+- experiment metrics
+- charts
+- paper sections
+- related work summaries
+- citation lists
+- ablation claims
+- statuses like "reproduced successfully"
+
+The correct approach is to:
+
+- inspect raw files
+- inspect runtime logs
+- inspect scripts and configs
+- rerun key experiments
+- spot-check citations and numbers
+
+### 3.7 Prepare Backup And Rollback
+
+At minimum:
+
+- put important quests under Git
+- back up `~/DeepScientist`
+- snapshot important data directories
+- separate production data from experimental data
+
+## 4. Short Version
+
+The shortest safe summary is:
+
+1. DeepScientist is released under Apache 2.0.
+2. The project authors and maintainers are not responsible for any consequence caused by your use of DeepScientist.
+3. It may damage a server, delete files, leak credentials, send wrong external messages, or fabricate results.
+4. Strongly prefer Docker or an equivalent isolated environment, and always run under a non-root account.
+5. Do not casually share the site address, and do not expose a runtime with bound WeChat, QQ, or other connectors to uncontrolled users.

package/docs/en/12_GUIDED_WORKFLOW_TOUR.md

@@ -0,0 +1,427 @@
+# 12 Guided Workflow Tour: From Landing Page to Real Workspace
+
+This guide is the shortest path to understanding how DeepScientist is actually used after installation.
+
+Use it when:
+
+- you already launched DeepScientist once
+- you can open the home page
+- you want a concrete walkthrough of what to click, what to fill, and what each surface is for
+
+If you still have not launched DeepScientist yet, start with [00 Quick Start](./00_QUICK_START.md).
+
+If you want the exact payload and field contract behind `Start Research`, then read [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md) after this page.
+
+## 1. First, choose the right mode
+
+There are two normal ways to use the product:
+
+1. real project mode
+2. guided tutorial mode
+
+Real project mode creates a real local quest repository and starts real work.
+
+Guided tutorial mode uses the same project-page layout, but the project contents are staged for learning. It is useful when you want to practice the interface before spending real time, compute, or connector resources.
+
+If your goal is real work, use real project mode.
+
+If your goal is to understand the interface safely, replay the tutorial first.
+
+## 2. Start from the home page
+
+The home page is not a chat box. It is the launch surface for a research workspace.
+
+The two primary entry points are:
+
+- `Start Research`
+- `Open Project`
+
+Use `Start Research` when you want to begin a new quest.
+
+Use `Open Project` when the quest already exists and you want to continue it.
+
+For a first run, click `Start Research`.
+
+## 3. Understand what the dialog is doing
+
+The `Start Research` dialog has two jobs:
+
+- the left side defines the project contract
+- the right side shows the kickoff prompt that will seed the workspace
+
+This means you should not treat the dialog as a casual form.
+
+You are deciding:
+
+- what problem the quest should solve
+- what evidence or references already exist
+- how autonomous the first round should be
+- whether any external connector should receive progress updates
+
+If the right-side generated prompt looks wrong, stop and fix the left side before you create the project.
+
+## 4. Fill the dialog step by step
+
+### 4.1 Project title
+
+Use a short human-facing title.
+
+Good pattern:
+
+- task name
+- benchmark or repository name
+- the main research direction
+
+Example:
+
+`Mandela-Effect Reproduction and Truth-Preserving Collaboration`
+
+Use the title so future-you can recognize the quest quickly in the project list.
+
+### 4.2 Project ID
+
+Usually leave this blank.
+
+Only fill it manually when you need a specific stable identifier such as:
+
+- a tutorial run
+- a reproduced paper case
+- a team convention
+
+If you do not need that, let the runtime assign the next sequential quest id.
+
+### 4.3 Primary research request
+
+This is the most important field in the dialog.
+
+Write:
+
+- the scientific goal
+- the success condition
+- the evidence requirement
+- the most important boundary or evaluation rule
+
+Bad input:
+
+- vague brainstorming
+- implementation-only instructions
+- a prompt that never says what must be verified
+
+Good pattern:
+
+1. what to reproduce or investigate
+2. what question should be answered
+3. what must stay aligned with prior work
+4. what kind of improvement is allowed
+
+### 4.4 Baseline links and reference papers
+
+Use these fields to reduce ambiguity before the first round starts.
+
+Put repositories in `Baseline links` when:
+
+- the quest should restore a known repo
+- the baseline must come from a specific official implementation
+
+Put papers or important external references in `Reference papers / repos` when:
+
+- the task is defined by a paper
+- the expected protocol comes from prior work
+- the system should read a known source first
+
+If you already know the baseline and paper, do not hide them in the main request. Put them in the dedicated fields.
+
+### 4.5 Reusable baseline
+
+Use this only when you already imported a trusted reusable baseline into the registry.
+
+If this field is selected:
+
+- the first round starts from an attached baseline instead of restoring from raw URLs
+- the contract becomes more grounded immediately
+
+If you are doing the task for the first time, leaving it empty is normal.
+
+### 4.6 Connector delivery
+
+Connector delivery is optional.
+
+Keep it `Local only` when:
+
+- this is your first run
+- you want the simplest setup
+- you do not need progress outside the web workspace
+
+Choose one connector target only when:
+
+- you want milestone delivery outside the browser
+- you already configured that connector correctly
+
+DeepScientist currently keeps one bound external connector target per quest.
+
+### 4.7 Research paper, intensity, decision mode, and launch mode
+
+These fields change the shape of the first round.
+
+Use these defaults if you are unsure:
+
+- `Research paper`: `On`
+- `Research intensity`: `Balanced`
+- `Decision mode`: `Autonomous`
+- `Launch mode`: `Standard`
+
+Why these defaults are usually correct:
+
+- `Balanced` is strong enough to do real work without overcommitting the first round
+- `Autonomous` avoids unnecessary blocking
+- `Standard` keeps the workflow on the ordinary path
+- `Research paper = On` keeps analysis and writing in scope
+
+### 4.8 Runtime constraints
+
+Use this field for hard rules, not wishes.
+
+Good things to put here:
+
+- which model or inference endpoint must be used
+- whether retries are required
+- whether evaluation must stay aligned with a baseline
+- whether the system must record failure honestly
+- hardware or runtime boundaries
+
+Bad things to put here:
+
+- generic goals already written in the main request
+- long literature summaries
+- content that belongs in references instead
+
+### 4.9 Goals
+
+Use this field for concrete milestones.
+
+Good goals are:
+
+- specific
+- verifiable
+- useful for later review
+
+Example shape:
+
+1. restore the official baseline
+2. verify key metrics
+3. propose one justified direction
+4. produce evidence strong enough for writing or further analysis
+
+### 4.10 Review the generated prompt
+
+Before clicking `Create project`, read the generated kickoff prompt on the right.
+
+Check for:
+
+- wrong scope
+- missing baseline information
+- missing runtime constraints
+- incorrect connector choice
+- a tone that no longer matches the real task
+
+This is the cheapest correction point in the whole workflow.
+
+## 5. Click Create project
+
+In real project mode, this creates a real local quest and opens its workspace.
+
+In guided tutorial mode, it opens a staged demo quest that uses the same project-page layout for training.
+
+After you click create, the most important mindset shift is:
+
+- the task is no longer a text idea
+- it is now a durable workspace with files, graph state, memory, and execution history
+
+## 6. Learn the workspace in the right order
+
+A good first order is:
+
+1. top bar
+2. explorer
+3. one real file
+4. canvas
+5. details
+6. memory
+7. copilot / studio
+
+### 6.1 Top bar
+
+The top bar is the global control strip.
+
+Use it to understand:
+
+- which quest you are in
+- whether you are on the expected branch
+- how to jump back, replay tutorial flow, or navigate globally
+
+### 6.2 Explorer
+
+Explorer is the file-first view of the quest.
+
+Use it when you want to answer:
+
+- what durable files exist now
+- whether the quest has produced anything reusable
+- where notes, plans, reports, or artifacts actually live
+
+Do not treat the graph as the only truth. The file tree is one of the most important evidence surfaces.
+
+### 6.3 ArXiv and Files tabs
+
+These two tabs serve different jobs:
+
+- `ArXiv` is the literature shelf
+- `Files` is the working tree
+
+In normal work you should switch between them repeatedly.
+
+Read a paper in one view.
+
+Open plans, experiment files, and notes in the other.
+
+### 6.4 Open a real file
+
+Once you see a useful file in Explorer, click it.
+
+This moves you from structure into actual project content.
+
+Common examples:
+
+- Markdown notes
+- plans
+- experiment summaries
+- result reports
+- paper drafts
+
+In practice, many users treat Markdown files in the quest as a private local-first notebook for:
+
+- notes
+- plans
+- handoffs
+- findings
+- team coordination
+
+### 6.5 Canvas
+
+Canvas makes the research map visible.
+
+A healthy quest should not feel like one long chat log.
+
+Canvas should help you see:
+
+- baseline work
+- candidate ideas
+- failed branches
+- successful paths
+- later analysis and writing
+
+The graph matters because it shows how the quest grew, not just where it ended.
+
+### 6.6 Click a node in Canvas
+
+Do not stop at looking.
+
+Click a node to inspect what it actually means.
+
+A useful node should lead you toward:
+
+- branch summary
+- linked files
+- stage state
+- durable evidence
+
+This is how Canvas becomes inspectable instead of decorative.
+
+### 6.7 Details
+
+Use `Details` when you want the fastest high-confidence answer to:
+
+`What is the current state of this quest right now?`
+
+This is usually the first page to open when:
+
+- you come back after a break
+- the quest has been running for a while
+- you want summary before intervention
+
+### 6.8 Memory
+
+Memory is how the quest keeps growing instead of restarting from zero.
+
+Use it to understand:
+
+- what reusable lessons were learned
+- which weak paths should not be repeated
+- what stable facts were extracted from prior work
+
+Without memory, every round risks becoming disposable.
+
+### 6.9 Copilot / Studio
+
+Keep this surface open when you want to stay close to execution.
+
+Use it to:
+
+- watch the run
+- intervene
+- ask for a summary
+- redirect the route
+- continue the thread later
+
+This is where the quest feels collaborative instead of static.
+
+## 7. A practical first operating rhythm
+
+Once the quest is running, the most useful rhythm is usually:
+
+1. let the first round move
+2. open the workspace instead of waiting in chat
+3. inspect one or two key files
+4. check Canvas for branching structure
+5. read Details for current state
+6. only then decide whether to intervene
+
+This avoids two common mistakes:
+
+- interrupting too early
+- trusting a summary before checking durable evidence
+
+## 8. Common mistakes
+
+### 8.1 Treating Start Research like casual chat
+
+It is not a casual chat box.
+
+It is a project contract.
+
+### 8.2 Leaving the goal vague
+
+If the goal does not define verification, the first round will be weaker.
+
+### 8.3 Hiding important references inside the main paragraph
+
+Use the dedicated baseline and reference fields instead.
+
+### 8.4 Ignoring the generated kickoff prompt
+
+This is the cheapest place to catch a misunderstanding.
+
+### 8.5 Treating Canvas as a pretty picture
+
+Click nodes and inspect files. Otherwise you are only seeing shape, not evidence.
+
+### 8.6 Waiting in the workspace without reading files
+
+The file tree is one of the main truth surfaces of the system.
+
+## 9. What to read next
+
+- [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
+- [06 Runtime and Canvas](./06_RUNTIME_AND_CANVAS.md)
+- [07 Memory and MCP](./07_MEMORY_AND_MCP.md)
+- [13 Core Architecture Guide](./13_CORE_ARCHITECTURE_GUIDE.md)