@researai/deepscientist 1.5.7 → 1.5.9

package/docs/en/07_MEMORY_AND_MCP.md

@@ -209,7 +209,44 @@ Example:
 Do not replace an experiment artifact with a memory card.
 Do not replace a reusable lesson with a progress artifact.
 
-## 4. Bash exec usage
+## 4. Artifact metric-contract rules
+
+Use `artifact` as the authoritative submission surface for baseline and main-experiment metrics.
+
+### `artifact.confirm_baseline(...)`
+
+For a confirmed baseline:
+
+- the canonical metric contract should live in `<baseline_root>/json/metric_contract.json`
+- the canonical `metrics_summary` should be a flat top-level dictionary keyed by the paper-facing metric ids
+- if the raw evaluator output is nested, map each required canonical metric through explicit `origin_path` fields inside `metric_contract.metrics`
+- every canonical baseline metric entry should explain where the number came from:
+  - `description`
+  - either `derivation` or `origin_path`
+  - `source_ref`
+- keep `primary_metric` as the headline metric only; do not use it to erase the rest of the accepted paper-facing comparison surface
+
+### `artifact.record_main_experiment(...)`
+
+For a main experiment recorded against a confirmed baseline:
+
+- use the confirmed baseline metric-contract JSON as the canonical comparison contract
+- report every required baseline metric id in the main experiment submission
+- extra metrics are allowed, but missing required baseline metrics are not
+- keep the original evaluation code and metric definitions for the canonical baseline metrics
+- if an extra evaluator is genuinely necessary, record it as supplementary evidence instead of replacing the canonical comparator
+
+### Validation and temporary notes
+
+- when the MCP tool runs strict validation, contract failures return structured error payloads such as:
+  - `missing_metric_ids`
+  - `baseline_metric_ids`
+  - `baseline_metric_details`
+  - `evaluation_protocol_mismatch`
+- `Result/metric.md` may be used as temporary scratch memory while working, but it is optional and not authoritative
+- if `Result/metric.md` exists, reconcile it against the final baseline or main-experiment submission before calling the artifact tool
+
+## 5. Bash exec usage
 
 Use `bash_exec` for monitored commands:
 
@@ -226,7 +263,7 @@ bash_exec.bash_exec(mode="read", id="<bash_id>")
 
 Use `kill` only when the quest truly needs to stop the session.
 
-## 5. Prompt-level expectations
+## 6. Prompt-level expectations
 
 The agent should normally follow this discipline:
 
@@ -237,7 +274,7 @@ The agent should normally follow this discipline:
 5. `bash_exec` for durable shell work
 6. `memory.write(...)` only after a real durable finding appears
 
-## 6. UI expectation
+## 7. UI expectation
 
 In `/projects/{id}` Studio trace:
 

package/docs/en/99_ACKNOWLEDGEMENTS.md

@@ -11,6 +11,7 @@ We especially thank the following projects for their ideas, research direction,
 - AlphaEvolve
 - OpenEvolve
 - EvoScientist
+- Orchestra-Research
 - Orchestra-Research/AI-Research-SKILLs
 
 These projects have been important references for thinking about automated research, open-ended exploration, evolutionary search, experiment organization, and long-horizon research agents.

package/docs/zh/00_QUICK_START.md

@@ -39,13 +39,13 @@ DeepScientist 现在使用 `uv` 管理锁定的本地 Python 运行时。如果
 
 默认情况下，DeepScientist home 在 macOS / Linux 上是 `~/DeepScientist`，在 Windows 上是 `%USERPROFILE%\\DeepScientist`。如果你希望放到别的路径，可以直接使用 `ds --home <path>`。
 
-如果你希望直接把“当前工作目录”作为 DeepScientist home，可以运行：
+如果你希望把 DeepScientist home 放到当前工作目录下的 `./DeepScientist` 中，可以运行：
 
 ```bash
 ds --here
 ```
 
-它等价于 `ds --home "$PWD"`。
+它等价于 `ds --home "$PWD/DeepScientist"`。
 
 如果你是从源码仓库安装，并希望把默认的 CLI 安装基路径改到别的位置，可以使用：
 

package/docs/zh/07_MEMORY_AND_MCP.md

@@ -192,7 +192,44 @@ updated_at: 2026-03-11T18:00:00+00:00
 不要用 memory 代替实验 artifact。
 不要用 artifact 代替可复用知识卡。
 
-## 4. Bash exec 的基本用法
+## 4. Artifact 指标契约规则
+
+baseline 与主实验的正式指标提交，应以 `artifact` 为唯一权威入口。
+
+### `artifact.confirm_baseline(...)`
+
+对于已确认的 baseline：
+
+- canonical metric contract 应保存在 `<baseline_root>/json/metric_contract.json`
+- canonical `metrics_summary` 应是顶层扁平字典，key 直接使用论文面对比时的 metric id
+- 如果原始评测输出是嵌套结构，应在 `metric_contract.metrics` 中为每个必需 canonical metric 提供显式 `origin_path`，而不是直接提交嵌套 blob
+- 每个 canonical baseline metric 都应说明数值来源，至少包含：
+  - `description`
+  - `derivation` 或 `origin_path`
+  - `source_ref`
+- `primary_metric` 只是 headline metric，不能借此删掉其他论文面对比所需指标
+
+### `artifact.record_main_experiment(...)`
+
+对于基于已确认 baseline 的主实验：
+
+- 默认以已确认 baseline 的 metric-contract JSON 作为 canonical comparison contract
+- 主实验提交时必须覆盖 baseline 的全部必需 metric id
+- 可以多报额外指标，但不能缺少 baseline 的必需指标
+- canonical baseline metrics 应继续使用原有评测代码和指标定义
+- 如果确实需要额外评测器，应把它作为 supplementary evidence 记录，而不是替换 canonical comparator
+
+### 校验失败与临时记录
+
+- 当 MCP 工具开启严格校验时，失败会返回结构化错误字段，例如：
+  - `missing_metric_ids`
+  - `baseline_metric_ids`
+  - `baseline_metric_details`
+  - `evaluation_protocol_mismatch`
+- `Result/metric.md` 只可作为工作过程中的临时草稿/记忆文件，不是必需文件，也不是权威来源
+- 如果存在 `Result/metric.md`，请在调用 artifact 提交前用它核对最终 baseline 或主实验提交内容，避免遗漏或写错
+
+## 5. Bash exec 的基本用法
 
 用于可监控命令：
 
@@ -209,7 +246,7 @@ bash_exec.bash_exec(mode="read", id="<bash_id>")
 
 只有在确实需要停止时才使用 `kill`。
 
-## 5. Prompt 级纪律（建议）
+## 6. Prompt 级纪律（建议）
 
 通常推荐遵循：
 
@@ -220,7 +257,7 @@ bash_exec.bash_exec(mode="read", id="<bash_id>")
 5. 长任务 shell 用 `bash_exec`
 6. 有真正的可复用发现才 `memory.write(...)`
 
-## 6. UI 期望
+## 7. UI 期望
 
 在 `/projects/{id}` 的 Studio trace 中：
 

package/docs/zh/99_ACKNOWLEDGEMENTS.md

@@ -11,6 +11,7 @@ DeepScientist 的构思、架构设计与实现过程中，受到了许多优秀
 - AlphaEvolve
 - OpenEvolve
 - EvoScientist
+- Orchestra-Research
 - Orchestra-Research/AI-Research-SKILLs
 
 这些项目在自动化科研、开放式探索、进化式搜索、实验组织与智能研究代理等方向上的探索，为 DeepScientist 的设计提供了重要参照。

package/install.sh

@@ -421,6 +421,40 @@ write_global_wrapper() {
   cat >"$target_path" <<EOF
 #!/usr/bin/env bash
 set -euo pipefail
+WRAPPER_PATH="\${BASH_SOURCE[0]}"
+WRAPPER_DIR="\$(cd "\$(dirname "\$WRAPPER_PATH")" && pwd)"
+PREFERRED_COMMAND="$command_name"
+LOOKUP_PATH=""
+OLD_IFS="\$IFS"
+IFS=:
+for ENTRY in \$PATH; do
+  if [ -z "\$ENTRY" ]; then
+    continue
+  fi
+  ENTRY_REAL="\$ENTRY"
+  if ENTRY_CANONICAL="\$(cd "\$ENTRY" 2>/dev/null && pwd)"; then
+    ENTRY_REAL="\$ENTRY_CANONICAL"
+  fi
+  if [ "\$ENTRY_REAL" = "\$WRAPPER_DIR" ]; then
+    continue
+  fi
+  if [ -z "\$LOOKUP_PATH" ]; then
+    LOOKUP_PATH="\$ENTRY"
+  else
+    LOOKUP_PATH="\$LOOKUP_PATH:\$ENTRY"
+  fi
+done
+IFS="\$OLD_IFS"
+if [ -n "\$LOOKUP_PATH" ]; then
+  if RESOLVED_LAUNCHER="\$(PATH="\$LOOKUP_PATH" command -v "\$PREFERRED_COMMAND" 2>/dev/null)"; then
+    if [ -n "\$RESOLVED_LAUNCHER" ] && [ "\$RESOLVED_LAUNCHER" != "\$WRAPPER_PATH" ]; then
+      if [ -z "\${DEEPSCIENTIST_HOME:-}" ]; then
+        export DEEPSCIENTIST_HOME="$BASE_DIR"
+      fi
+      exec "\$RESOLVED_LAUNCHER" "\$@"
+    fi
+  fi
+fi
 if [ -z "\${DEEPSCIENTIST_HOME:-}" ]; then
   export DEEPSCIENTIST_HOME="$BASE_DIR"
 fi

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@researai/deepscientist",
-  "version": "1.5.7",
+  "version": "1.5.9",
   "description": "Local-first research operating system with a Python runtime and npm launcher",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "files": [
     "AGENTS.md",
     "README.md",

package/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepscientist"
-version = "1.5.7"
+version = "1.5.9"
 description = "DeepScientist Core skeleton"
 readme = "README.md"
 requires-python = ">=3.11"
-license = { text = "MIT" }
+license = { text = "Apache-2.0" }
 authors = [
   { name = "OpenAI Codex" }
 ]

package/src/deepscientist/__init__.py

@@ -5,4 +5,4 @@ __all__ = ["__version__"]
 try:
     __version__ = _package_version("deepscientist")
 except PackageNotFoundError:  # pragma: no cover - source checkout fallback
-    __version__ = "1.5.7"
+    __version__ = "1.5.9"

package/src/deepscientist/acp/envelope.py

@@ -85,6 +85,7 @@ def build_session_descriptor(
         "mcp_servers": [
             {"name": "memory", "transport": "stdio", "scope": "quest-local"},
             {"name": "artifact", "transport": "stdio", "scope": "quest-local"},
+            {"name": "bash_exec", "transport": "stdio", "scope": "quest-local"},
         ],
         "slash_commands": build_slash_commands(quest_id),
         "meta": {