@researai/deepscientist 1.5.0 → 1.5.1

package/assets/connectors/lingzhu/openclaw.lingzhu.config.template.json

@@ -0,0 +1,39 @@
+{
+  "gateway": {
+    "port": 18789,
+    "http": {
+      "endpoints": {
+        "chatCompletions": {
+          "enabled": true
+        }
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "lingzhu": {
+        "enabled": true,
+        "config": {
+          "authAk": "",
+          "agentId": "main",
+          "includeMetadata": true,
+          "requestTimeoutMs": 60000,
+          "systemPrompt": "",
+          "defaultNavigationMode": "0",
+          "enableFollowUp": true,
+          "followUpMaxCount": 3,
+          "maxImageBytes": 5242880,
+          "sessionMode": "per_user",
+          "sessionNamespace": "lingzhu",
+          "autoReceiptAck": true,
+          "visibleProgressHeartbeat": true,
+          "visibleProgressHeartbeatSec": 10,
+          "debugLogging": false,
+          "debugLogPayloads": false,
+          "debugLogDir": "",
+          "enableExperimentalNativeActions": false
+        }
+      }
+    }
+  }
+}

package/bin/ds.js

@@ -21,10 +21,12 @@ const pythonCommands = new Set([
   'note',
   'approve',
   'graph',
-  'metrics',
+  'doctor',
+  'docker',
   'push',
   'memory',
   'baseline',
+  'latex',
   'config',
 ]);
 
@@ -34,17 +36,21 @@ function printLauncherHelp() {
   console.log(`DeepScientist launcher
 
 Usage:
-  research
-  research --web
-  research --both
-  research --stop
-  research --restart
-  research --home ~/DeepScientist --port 20999
+  ds
+  ds --tui
+  ds --both
+  ds --stop
+  ds --restart
+  ds doctor
+  ds latex status
+  ds --home ~/DeepScientist --port 20999
 
 Advanced Python CLI:
   ds init
-  ds new "reproduce baseline and test idea"
-  ds run decision --quest-id q-001 --message "review current state"
+  ds new "reproduce baseline and test one stronger idea"
+  ds doctor
+  ds latex install-runtime
+  ds run decision --quest-id 001 --message "review current state"
 `);
 }
 
@@ -88,6 +94,146 @@ function bindUiUrl(host, port) {
   return `http://${formatHttpHost(normalized)}:${port}`;
 }
 
+function normalizeMode(value) {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase();
+  if (normalized === 'tui' || normalized === 'both' || normalized === 'web') {
+    return normalized;
+  }
+  return 'web';
+}
+
+function parseBooleanSetting(rawValue, fallback = false) {
+  if (typeof rawValue === 'boolean') {
+    return rawValue;
+  }
+  const normalized = String(rawValue || '')
+    .trim()
+    .toLowerCase();
+  if (['true', 'yes', 'on', '1'].includes(normalized)) {
+    return true;
+  }
+  if (['false', 'no', 'off', '0'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function supportsAnsi() {
+  return Boolean(process.stdout.isTTY && process.env.TERM !== 'dumb');
+}
+
+function stripAnsi(text) {
+  return String(text || '')
+    .replace(/\u001B]8;;[^\u0007]*\u0007/g, '')
+    .replace(/\u001B]8;;\u0007/g, '')
+    .replace(/\u001B\[[0-9;]*m/g, '');
+}
+
+function visibleWidth(text) {
+  return stripAnsi(text).length;
+}
+
+function centerText(text, width) {
+  const targetWidth = Math.max(visibleWidth(text), width || 0);
+  const padding = Math.max(0, Math.floor((targetWidth - visibleWidth(text)) / 2));
+  return `${' '.repeat(padding)}${text}`;
+}
+
+function hyperlink(url, label = url) {
+  if (!supportsAnsi()) {
+    return label;
+  }
+  return `\u001B]8;;${url}\u0007${label}\u001B]8;;\u0007`;
+}
+
+function colorize(code, text) {
+  if (!supportsAnsi()) {
+    return text;
+  }
+  return `${code}${text}\u001B[0m`;
+}
+
+function renderBrandArtwork() {
+  const brandPath = path.join(repoRoot, 'assets', 'branding', 'deepscientist-mark.png');
+  const chafa = resolveExecutableOnPath('chafa');
+  if (!supportsAnsi() || !chafa || !fs.existsSync(brandPath)) {
+    return [];
+  }
+  const width = Math.max(18, Math.min(30, Math.floor((process.stdout.columns || 100) / 3)));
+  const height = Math.max(8, Math.floor(width / 2));
+  try {
+    const result = spawnSync(
+      chafa,
+      ['--size', `${width}x${height}`, '--format', 'symbols', '--colors', '16', brandPath],
+      { encoding: 'utf8' }
+    );
+    if (result.status === 0 && result.stdout && result.stdout.trim()) {
+      return result.stdout.replace(/\s+$/, '').split(/\r?\n/);
+    }
+  } catch {}
+  return [];
+}
+
+function printLaunchCard({ url, bindUrl, mode, autoOpenRequested, browserOpened, daemonOnly }) {
+  const width = Math.max(72, Math.min(process.stdout.columns || 100, 108));
+  const divider = colorize('\u001B[38;5;245m', '─'.repeat(Math.max(36, width - 6)));
+  const title = colorize('\u001B[1;38;5;39m', 'ResearAI');
+  const subtitle = colorize('\u001B[38;5;110m', 'Local-first research operating system');
+  const urlLabel = colorize('\u001B[1;38;5;45m', hyperlink(url, url));
+  const workspaceMode =
+    mode === 'both'
+      ? 'Web workspace + terminal workspace'
+      : mode === 'tui'
+        ? 'Terminal workspace'
+        : 'Web workspace';
+  const browserLine = autoOpenRequested
+    ? browserOpened
+      ? 'Browser launch requested successfully.'
+      : 'Browser auto-open was requested but is not available in this terminal session.'
+    : 'Browser auto-open is disabled. Open the URL manually if needed.';
+  const nextStep = daemonOnly
+    ? 'Use ds --tui to enter the terminal workspace.'
+    : mode === 'web'
+      ? 'Use ds --tui to enter the terminal workspace.'
+      : mode === 'both'
+        ? 'The terminal workspace starts below.'
+        : 'Use Ctrl+O inside TUI to reopen the web workspace.';
+
+  console.log('');
+  const artwork = renderBrandArtwork();
+  for (const line of artwork) {
+    console.log(centerText(line, width));
+  }
+  if (artwork.length === 0) {
+    console.log(centerText(colorize('\u001B[1;38;5;39m', '⛰'), width));
+  }
+  const wordmark = [
+    '  ____                  ____       _            _   _     _   ',
+    ' |  _ \\  ___  ___ _ __ / ___|  ___(_) ___ _ __ | |_(_)___| |_ ',
+    " | | | |/ _ \\/ _ \\ '_ \\\\___ \\ / __| |/ _ \\ '_ \\| __| / __| __|",
+    ' | |_| |  __/  __/ |_) |___) | (__| |  __/ | | | |_| \\__ \\ |_ ',
+    ' |____/ \\___|\\___| .__/|____/ \\___|_|\\___|_| |_|\\__|_|___/\\__|',
+    '                 |_|                                          ',
+  ];
+  console.log(centerText(title, width));
+  for (const line of wordmark) {
+    console.log(centerText(colorize('\u001B[1;38;5;39m', line), width));
+  }
+  console.log(centerText(subtitle, width));
+  console.log('');
+  console.log(centerText(divider, width));
+  console.log(centerText(colorize('\u001B[1m', workspaceMode), width));
+  console.log(centerText(urlLabel, width));
+  console.log(centerText(divider, width));
+  console.log(centerText(browserLine, width));
+  console.log(centerText(`Daemon bind: ${bindUrl}`, width));
+  console.log(centerText(nextStep, width));
+  console.log(centerText('Run ds --stop to stop the managed daemon.', width));
+  console.log('');
+}
+
 function escapeHtml(value) {
   return String(value ?? '')
     .replaceAll('&', '&')
@@ -274,13 +420,13 @@ function createCodexPreflightError(home, probe) {
 
 function parseLauncherArgs(argv) {
   const args = [...argv];
-  let mode = 'both';
+  let mode = null;
   let host = null;
   let port = null;
   let home = null;
   let stop = false;
   let restart = false;
-  let openBrowser = false;
+  let openBrowser = null;
   let questId = null;
   let status = false;
   let daemonOnly = false;
@@ -305,7 +451,7 @@ function parseLauncherArgs(argv) {
     else if (arg === '--port' && args[index + 1]) port = Number(args[++index]);
     else if (arg === '--home' && args[index + 1]) home = path.resolve(args[++index]);
     else if (arg === '--quest-id' && args[index + 1]) questId = args[++index];
-    else if (arg === '--mode' && args[index + 1]) mode = args[++index];
+    else if (arg === '--mode' && args[index + 1]) mode = normalizeMode(args[++index]);
     else if (arg === '--help' || arg === '-h') return { help: true };
     else if (!arg.startsWith('--')) return null;
   }
@@ -962,30 +1108,53 @@ async function readConfiguredUiAddress(home, venvPython, fallbackHost, fallbackP
     const text = result.stdout || '';
     const hostMatch = text.match(/^\s*host:\s*["']?([^"'\n]+)["']?\s*$/m);
     const portMatch = text.match(/^\s*port:\s*(\d+)\s*$/m);
+    const modeMatch = text.match(/^\s*default_mode:\s*["']?([^"'\n]+)["']?\s*$/m);
+    const autoOpenMatch = text.match(/^\s*auto_open_browser:\s*([^\n]+)\s*$/m);
     return {
       host: fallbackHost || (hostMatch ? hostMatch[1].trim() : '0.0.0.0'),
       port: fallbackPort || (portMatch ? Number(portMatch[1]) : 20999),
+      defaultMode: normalizeMode(modeMatch ? modeMatch[1].trim() : 'web'),
+      autoOpenBrowser: parseBooleanSetting(autoOpenMatch ? autoOpenMatch[1].trim() : true, true),
     };
   } catch {
-    return { host: fallbackHost || '0.0.0.0', port: fallbackPort || 20999 };
+    return {
+      host: fallbackHost || '0.0.0.0',
+      port: fallbackPort || 20999,
+      defaultMode: 'web',
+      autoOpenBrowser: true,
+    };
   }
 }
 
 function readConfiguredUiAddressFromFile(home, fallbackHost, fallbackPort) {
   const configPath = path.join(home, 'config', 'config.yaml');
   if (!fs.existsSync(configPath)) {
-    return { host: fallbackHost || '0.0.0.0', port: fallbackPort || 20999 };
+    return {
+      host: fallbackHost || '0.0.0.0',
+      port: fallbackPort || 20999,
+      defaultMode: 'web',
+      autoOpenBrowser: true,
+    };
   }
   try {
     const text = fs.readFileSync(configPath, 'utf8');
     const hostMatch = text.match(/^\s*host:\s*["']?([^"'\n]+)["']?\s*$/m);
     const portMatch = text.match(/^\s*port:\s*(\d+)\s*$/m);
+    const modeMatch = text.match(/^\s*default_mode:\s*["']?([^"'\n]+)["']?\s*$/m);
+    const autoOpenMatch = text.match(/^\s*auto_open_browser:\s*([^\n]+)\s*$/m);
     return {
       host: fallbackHost || (hostMatch ? hostMatch[1].trim() : '0.0.0.0'),
       port: fallbackPort || (portMatch ? Number(portMatch[1]) : 20999),
+      defaultMode: normalizeMode(modeMatch ? modeMatch[1].trim() : 'web'),
+      autoOpenBrowser: parseBooleanSetting(autoOpenMatch ? autoOpenMatch[1].trim() : true, true),
     };
   } catch {
-    return { host: fallbackHost || '0.0.0.0', port: fallbackPort || 20999 };
+    return {
+      host: fallbackHost || '0.0.0.0',
+      port: fallbackPort || 20999,
+      defaultMode: 'web',
+      autoOpenBrowser: true,
+    };
   }
 }
 
@@ -1080,38 +1249,42 @@ async function startDaemon(home, venvPython, host, port) {
 }
 
 function openBrowser(url) {
-  try {
-    if (process.platform === 'darwin') {
-      const child = spawn('open', [url], { detached: true, stdio: 'ignore' });
-      child.on('error', () => {
-        console.log(`Open this URL in your browser: ${url}`);
-      });
+  const spawnDetached = (command, args) => {
+    try {
+      const child = spawn(command, args, { detached: true, stdio: 'ignore' });
       child.unref();
       return true;
+    } catch {
+      return false;
     }
-    if (process.platform === 'win32') {
-      const child = spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' });
-      child.on('error', () => {
-        console.log(`Open this URL in your browser: ${url}`);
-      });
-      child.unref();
-      return true;
+  };
+
+  if (process.platform === 'darwin') {
+    const opener = resolveExecutableOnPath('open');
+    return opener ? spawnDetached(opener, [url]) : false;
+  }
+  if (process.platform === 'win32') {
+    return spawnDetached('cmd', ['/c', 'start', '', url]);
+  }
+
+  const commands = [
+    { command: 'xdg-open', args: [url] },
+    { command: 'gio', args: ['open', url] },
+    { command: 'sensible-browser', args: [url] },
+    { command: 'gnome-open', args: [url] },
+    { command: 'kde-open', args: [url] },
+    { command: 'kde-open5', args: [url] },
+  ];
+  for (const candidate of commands) {
+    const resolved = resolveExecutableOnPath(candidate.command);
+    if (!resolved) {
+      continue;
     }
-    const probe = spawnSync('xdg-open', ['--help'], { stdio: 'ignore' });
-    if (probe.error || probe.status !== 0) {
-      console.log(`Open this URL in your browser: ${url}`);
-      return false;
+    if (spawnDetached(resolved, candidate.args)) {
+      return true;
     }
-    const child = spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
-    child.on('error', () => {
-      console.log(`Open this URL in your browser: ${url}`);
-    });
-    child.unref();
-    return true;
-  } catch {
-    console.log(`Open this URL in your browser: ${url}`);
-    return false;
   }
+  return false;
 }
 
 function handleCodexPreflightFailure(error) {
@@ -1199,7 +1372,15 @@ async function launcherMain(rawArgs) {
   ensureInitialized(home, venvPython);
   maybePrintOptionalLatexNotice(home);
 
-  const { host, port } = await readConfiguredUiAddress(home, venvPython, options.host, options.port);
+  const configuredUi = await readConfiguredUiAddress(home, venvPython, options.host, options.port);
+  const host = configuredUi.host;
+  const port = configuredUi.port;
+  const mode = normalizeMode(options.mode ?? 'web');
+  const shouldOpenBrowser = options.daemonOnly
+    ? false
+    : options.openBrowser === null
+      ? configuredUi.autoOpenBrowser !== false && mode !== 'tui'
+      : options.openBrowser;
   if (options.restart) {
     await stopDaemon(home);
   }
@@ -1212,21 +1393,20 @@ async function launcherMain(rawArgs) {
     if (handleCodexPreflightFailure(error)) return true;
     throw error;
   }
-  console.log('');
-  console.log('DeepScientist is ready.');
-  console.log(`Web: ${started.url}`);
-  console.log(`Daemon bind: ${started.bindUrl}`);
-  console.log('The web workspace opens automatically when supported.');
-  console.log('Use Ctrl+O in TUI to open the web workspace again.');
-  console.log('');
+  const browserOpened = shouldOpenBrowser ? openBrowser(started.url) : false;
+  printLaunchCard({
+    url: started.url,
+    bindUrl: started.bindUrl,
+    mode,
+    autoOpenRequested: shouldOpenBrowser,
+    browserOpened,
+    daemonOnly: options.daemonOnly,
+  });
 
-  if (options.mode === 'web' || options.mode === 'both' || options.openBrowser) {
-    openBrowser(started.url);
-  }
   if (options.daemonOnly) {
     process.exit(0);
   }
-  if (options.mode === 'web') {
+  if (mode === 'web') {
     process.exit(0);
   }
   launchTui(started.url, options.questId, home, venvPython);

package/docs/en/00_QUICK_START.md

@@ -0,0 +1,134 @@
+# 00 Quick Start: Launch DeepScientist and Run Your First Quest
+
+This is the fastest way to go from installation to a running quest.
+
+You will do four things:
+
+1. install DeepScientist
+2. start the local runtime
+3. create a new quest from the home page
+4. reopen old quests from the quest list
+
+The screenshots in this guide use the current live web UI at `deepscientist.cc:20999` as an example. Your local UI at `127.0.0.1:20999` should look the same or very close.
+
+## 1. Install
+
+Install Codex and DeepScientist globally:
+
+```bash
+npm install -g @openai/codex @researai/deepscientist
+```
+
+If you plan to compile LaTeX locally later, you can also install the lightweight PDF runtime:
+
+```bash
+ds latex install-runtime
+```
+
+## 2. Start DeepScientist
+
+Start the local daemon and web workspace:
+
+```bash
+ds
+```
+
+By default, the web UI is served at:
+
+```text
+http://127.0.0.1:20999
+```
+
+If the browser does not open automatically, paste that address into your browser manually.
+
+## 3. Understand the Home Page
+
+When DeepScientist starts, open the home page at `/`.
+
+![DeepScientist home page](../images/quickstart/00-home.png)
+
+The home page is intentionally simple. The two main entry buttons are:
+
+- `Start Research`: create a new quest and launch a new research run
+- `List Quest`: reopen an existing quest
+
+If you are using DeepScientist for the first time, start with `Start Research`.
+
+## 4. Create a New Quest With Start Research
+
+Click `Start Research` to open the launch dialog.
+
+![Start Research dialog](../images/quickstart/01-start-research.png)
+
+This dialog creates a new quest repository and writes the startup contract for the agent.
+
+The most important fields are:
+
+- `Quest ID`: usually auto-generated in sequence such as `00`, `01`, `02`
+- `Primary request` / research goal: the actual scientific task you want the agent to work on
+- `Reuse Baseline`: optional; choose an existing baseline if you want to continue from an earlier result
+- `Research intensity`: how aggressive the run should be
+- `Decision mode`: `Autonomous` means the agent should keep going by itself unless a true approval is needed
+- `Research paper`: choose whether the run should also aim to produce paper-style output
+- `Language`: choose the user-facing language for the run
+
+For a first test, keep it simple:
+
+- write one clear research question
+- leave baseline empty unless you already have one
+- use `Balanced` or `Sprint`
+- keep decision mode on `Autonomous`
+
+Then click the final `Start Research` action in the dialog.
+
+## 5. Reopen an Existing Quest With List Quest
+
+Click `List Quest` on the home page to open the existing quest list.
+
+![List Quest dialog](../images/quickstart/02-list-quest.png)
+
+Use this dialog when you want to:
+
+- reopen a quest that is already running or already finished
+- search by quest title or quest id
+- jump back into a previous workspace quickly
+
+Each row corresponds to one quest repository. Click a quest card to open it.
+
+## 6. What Happens After Opening a Quest
+
+After you create or open a quest, DeepScientist takes you to the workspace page for that quest.
+
+Inside the workspace, the usual flow is:
+
+1. watch agent progress in Copilot / Studio
+2. inspect files, notes, and generated artifacts
+3. use Canvas to understand the current quest graph and stage progress
+4. stop the run only when you intentionally want to interrupt it
+
+## 7. Useful Runtime Commands
+
+Check status:
+
+```bash
+ds --status
+```
+
+Stop the current local daemon:
+
+```bash
+ds --stop
+```
+
+Run diagnostics if something looks broken:
+
+```bash
+ds doctor
+```
+
+## 8. What To Read Next
+
+- [01 Settings Reference: Configure DeepScientist](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research Guide: Fill the Start Research Contract](./02_START_RESEARCH_GUIDE.md)
+- [03 QQ Connector Guide: Use QQ With DeepScientist](./03_QQ_CONNECTOR_GUIDE.md)
+- [05 TUI Guide: Use the Terminal Interface](./05_TUI_GUIDE.md)