@researai/deepscientist 1.5.1 → 1.5.3

package/src/deepscientist/qq_profiles.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from .shared import slugify
+
+
+QQ_PROFILE_ID_PREFIX = "qq-profile"
+QQ_DEFAULT_SECRET_ENV = "QQ_APP_SECRET"
+
+
+def default_qq_profile() -> dict[str, Any]:
+    return {
+        "profile_id": None,
+        "enabled": True,
+        "app_id": None,
+        "app_secret": None,
+        "app_secret_env": QQ_DEFAULT_SECRET_ENV,
+        "bot_name": "DeepScientist",
+        "main_chat_id": None,
+    }
+
+
+def _as_text(value: Any) -> str | None:
+    text = str(value or "").strip()
+    return text or None
+
+
+def _profile_id_seed(*, profile_id: Any, app_id: Any, bot_name: Any, index: int) -> str:
+    explicit = _as_text(profile_id)
+    if explicit:
+        return explicit
+    app_text = _as_text(app_id)
+    if app_text:
+        return f"qq-{app_text}"
+    bot_text = slugify(str(bot_name or "").strip(), default="")
+    if bot_text:
+        return f"{QQ_PROFILE_ID_PREFIX}-{bot_text}"
+    return f"{QQ_PROFILE_ID_PREFIX}-{index:03d}"
+
+
+def _unique_profile_id(seed: str, *, used: set[str]) -> str:
+    base = slugify(seed, default=QQ_PROFILE_ID_PREFIX)
+    candidate = base
+    suffix = 2
+    while candidate in used:
+        candidate = f"{base}-{suffix}"
+        suffix += 1
+    used.add(candidate)
+    return candidate
+
+
+def list_qq_profiles(config: dict[str, Any] | None) -> list[dict[str, Any]]:
+    normalized = normalize_qq_connector_config(config)
+    profiles = normalized.get("profiles")
+    return [dict(item) for item in profiles] if isinstance(profiles, list) else []
+
+
+def find_qq_profile(
+    config: dict[str, Any] | None,
+    *,
+    profile_id: str | None = None,
+    app_id: str | None = None,
+) -> dict[str, Any] | None:
+    normalized_profile_id = _as_text(profile_id)
+    normalized_app_id = _as_text(app_id)
+    for profile in list_qq_profiles(config):
+        if normalized_profile_id and str(profile.get("profile_id") or "").strip() == normalized_profile_id:
+            return profile
+        if normalized_app_id and str(profile.get("app_id") or "").strip() == normalized_app_id:
+            return profile
+    return None
+
+
+def merge_qq_profile_config(shared_config: dict[str, Any] | None, profile: dict[str, Any]) -> dict[str, Any]:
+    normalized = normalize_qq_connector_config(shared_config)
+    merged = deepcopy(normalized)
+    merged.pop("profiles", None)
+    merged.update(
+        {
+            "profile_id": str(profile.get("profile_id") or "").strip() or None,
+            "app_id": _as_text(profile.get("app_id")),
+            "app_secret": _as_text(profile.get("app_secret")),
+            "app_secret_env": _as_text(profile.get("app_secret_env")) or QQ_DEFAULT_SECRET_ENV,
+            "bot_name": _as_text(profile.get("bot_name")) or str(normalized.get("bot_name") or "DeepScientist"),
+            "main_chat_id": _as_text(profile.get("main_chat_id")),
+            "enabled": bool(normalized.get("enabled", False)) and bool(profile.get("enabled", True)),
+            "transport": "gateway_direct",
+        }
+    )
+    return merged
+
+
+def qq_profile_label(profile: dict[str, Any] | None) -> str:
+    if not isinstance(profile, dict):
+        return "QQ"
+    bot_name = _as_text(profile.get("bot_name"))
+    app_id = _as_text(profile.get("app_id"))
+    if bot_name and app_id:
+        return f"{bot_name} · {app_id}"
+    if bot_name:
+        return bot_name
+    if app_id:
+        return f"QQ · {app_id}"
+    return "QQ"
+
+
+def normalize_qq_connector_config(config: dict[str, Any] | None) -> dict[str, Any]:
+    payload = deepcopy(config or {})
+    shared_defaults = {
+        "enabled": False,
+        "transport": "gateway_direct",
+        "app_id": None,
+        "app_secret": None,
+        "app_secret_env": QQ_DEFAULT_SECRET_ENV,
+        "bot_name": "DeepScientist",
+        "command_prefix": "/",
+        "main_chat_id": None,
+        "require_at_in_groups": True,
+        "auto_bind_dm_to_active_quest": True,
+        "gateway_restart_on_config_change": True,
+        "auto_send_main_experiment_png": True,
+        "auto_send_analysis_summary_png": True,
+        "auto_send_slice_png": True,
+        "auto_send_paper_pdf": True,
+        "enable_markdown_send": False,
+        "enable_file_upload_experimental": False,
+        "profiles": [],
+    }
+    shared = {**shared_defaults, **payload}
+    shared["transport"] = "gateway_direct"
+    shared["command_prefix"] = _as_text(shared.get("command_prefix")) or "/"
+    shared["bot_name"] = _as_text(shared.get("bot_name")) or "DeepScientist"
+    shared["app_secret_env"] = _as_text(shared.get("app_secret_env")) or QQ_DEFAULT_SECRET_ENV
+
+    raw_profiles = payload.get("profiles")
+    items = list(raw_profiles) if isinstance(raw_profiles, list) else []
+    legacy_profile_seed = {
+        "app_id": payload.get("app_id"),
+        "app_secret": payload.get("app_secret"),
+        "app_secret_env": payload.get("app_secret_env"),
+        "bot_name": payload.get("bot_name"),
+        "main_chat_id": payload.get("main_chat_id"),
+    }
+    if not items:
+        if any(_as_text(legacy_profile_seed.get(key)) for key in ("app_id", "app_secret", "main_chat_id", "bot_name")):
+            items = [legacy_profile_seed]
+
+    profiles: list[dict[str, Any]] = []
+    used_ids: set[str] = set()
+    for index, raw in enumerate(items, start=1):
+        if not isinstance(raw, dict):
+            continue
+        current = {**default_qq_profile(), **raw}
+        current["enabled"] = bool(current.get("enabled", True))
+        current["app_id"] = _as_text(current.get("app_id"))
+        current["app_secret"] = _as_text(current.get("app_secret"))
+        current["app_secret_env"] = _as_text(current.get("app_secret_env")) or shared["app_secret_env"]
+        current["bot_name"] = _as_text(current.get("bot_name")) or shared["bot_name"]
+        current["main_chat_id"] = _as_text(current.get("main_chat_id"))
+        current["profile_id"] = _unique_profile_id(
+            _profile_id_seed(
+                profile_id=current.get("profile_id"),
+                app_id=current.get("app_id"),
+                bot_name=current.get("bot_name"),
+                index=index,
+            ),
+            used=used_ids,
+        )
+        profiles.append(current)
+
+    shared["profiles"] = profiles
+    if len(profiles) == 1:
+        mirror = profiles[0]
+        shared["app_id"] = mirror.get("app_id")
+        shared["app_secret"] = mirror.get("app_secret")
+        shared["app_secret_env"] = mirror.get("app_secret_env")
+        shared["bot_name"] = mirror.get("bot_name")
+        shared["main_chat_id"] = mirror.get("main_chat_id")
+    else:
+        shared["app_id"] = None
+        shared["app_secret"] = None
+        shared["main_chat_id"] = None
+
+    return shared

package/src/deepscientist/quest/layout.py

@@ -29,6 +29,7 @@ QUEST_DIRECTORIES = (
     "memory/knowledge",
     "memory/papers",
     "paper",
+    "release/open_source",
     ".codex/skills",
     ".claude/agents",
     ".ds/bash_exec",

package/src/deepscientist/quest/service.py

@@ -1548,11 +1548,16 @@ class QuestService:
             if normalized in seen_files:
                 return
             seen_files.add(normalized)
+            resolved_document_id = document_id or self._path_to_document_id(
+                normalized,
+                quest_root=quest_root,
+                workspace_root=workspace_root,
+            )
             changed_files.append(
                 {
                     "path": normalized,
                     "source": source,
-                    "document_id": document_id,
+                    "document_id": resolved_document_id,
                     "writable": writable,
                 }
             )
@@ -1621,14 +1626,30 @@ class QuestService:
             "changed_files": changed_files[-30:],
         }
 
-    def events(self, quest_id: str, *, after: int = 0, limit: int = 200, tail: bool = False) -> dict:
+    def events(
+        self,
+        quest_id: str,
+        *,
+        after: int = 0,
+        before: int | None = None,
+        limit: int = 200,
+        tail: bool = False,
+    ) -> dict:
         records = self._read_cached_jsonl(self._quest_root(quest_id) / ".ds" / "events.jsonl")
         normalized_limit = max(limit, 0)
-        if tail and normalized_limit > 0:
+        direction = "after"
+        if before is not None:
+            direction = "before"
+            end = max(int(before) - 1, 0)
+            start = max(end - normalized_limit, 0)
+            sliced = records[start:end]
+        elif tail and normalized_limit > 0:
+            direction = "tail"
             start = max(len(records) - normalized_limit, 0)
+            sliced = records[start : start + normalized_limit]
         else:
             start = max(after, 0)
-        sliced = records[start : start + normalized_limit]
+            sliced = records[start : start + normalized_limit]
         enriched = []
         for index, item in enumerate(sliced, start=start + 1):
             enriched.append(
@@ -1638,11 +1659,23 @@ class QuestService:
                     **item,
                 }
             )
-        next_cursor = len(records) if tail else start + len(sliced)
+        if before is not None:
+            next_cursor = start + len(sliced)
+        else:
+            next_cursor = len(records) if tail else start + len(sliced)
+        oldest_cursor = enriched[0]["cursor"] if enriched else None
+        newest_cursor = enriched[-1]["cursor"] if enriched else None
+        if before is not None:
+            has_more = start > 0
+        else:
+            has_more = start > 0 if tail else next_cursor < len(records)
         return {
             "quest_id": quest_id,
             "cursor": next_cursor,
-            "has_more": start > 0 if tail else next_cursor < len(records),
+            "has_more": has_more,
+            "oldest_cursor": oldest_cursor,
+            "newest_cursor": newest_cursor,
+            "direction": direction,
             "events": enriched,
         }
 
@@ -1790,18 +1823,13 @@ class QuestService:
 
         quest_root = self._quest_root(quest_id)
         workspace_root = self.active_workspace_root(quest_root)
-        changed_paths = {
-            item["path"]: item
-            for item in self.workflow(quest_id).get("changed_files", [])
-            if item.get("path")
-        }
         git_status = self._git_status_map(workspace_root)
 
         root_nodes = self._tree_children(
             workspace_root,
             workspace_root,
             git_status=git_status,
-            changed_paths=changed_paths,
+            changed_paths={},
             profile=profile,
         )
         sections = self._group_explorer_sections(root_nodes)
@@ -2036,6 +2064,36 @@ class QuestService:
             return None, None
         return document_id, None
 
+    @staticmethod
+    def _path_to_document_id(
+        path: str | Path | None,
+        *,
+        quest_root: Path,
+        workspace_root: Path,
+    ) -> str | None:
+        if not path:
+            return None
+        try:
+            candidate = Path(path).expanduser()
+            if not candidate.is_absolute():
+                candidate = (workspace_root / candidate).resolve()
+            else:
+                candidate = candidate.resolve()
+        except OSError:
+            return None
+
+        try:
+            relative_to_workspace = candidate.relative_to(workspace_root.resolve()).as_posix()
+            return f"path::{relative_to_workspace}"
+        except ValueError:
+            pass
+
+        try:
+            relative_to_quest = candidate.relative_to(quest_root.resolve()).as_posix()
+            return f"questpath::{relative_to_quest}"
+        except ValueError:
+            return None
+
     @staticmethod
     def _markdown_asset_directory(relative_path: str) -> PurePosixPath:
         base_path = PurePosixPath(relative_path)

package/src/deepscientist/quest/stage_views.py

@@ -62,6 +62,38 @@ def _field(label: str, value: object, *, tone: str = "default") -> dict[str, Any
     }
 
 
+def _evaluation_summary(value: object) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    normalized: dict[str, Any] = {}
+    for key in (
+        "takeaway",
+        "claim_update",
+        "baseline_relation",
+        "comparability",
+        "failure_mode",
+        "next_action",
+    ):
+        raw = value.get(key)
+        text = str(raw).strip() if raw is not None else ""
+        if text:
+            normalized[key] = text
+    return normalized
+
+
+def _evaluation_summary_fields(value: object, *, prefix: str = "Evaluation") -> list[dict[str, Any]]:
+    summary = _evaluation_summary(value)
+    labels = (
+        ("takeaway", f"{prefix} Takeaway"),
+        ("claim_update", f"{prefix} Claim Update"),
+        ("baseline_relation", f"{prefix} Baseline Relation"),
+        ("comparability", f"{prefix} Comparability"),
+        ("failure_mode", f"{prefix} Failure Mode"),
+        ("next_action", f"{prefix} Next Action"),
+    )
+    return [_field(label, summary[key]) for key, label in labels if summary.get(key)]
+
+
 def _artifact_sort_key(item: dict[str, Any]) -> tuple[str, str]:
     payload = item.get("payload") if isinstance(item.get("payload"), dict) else {}
     return (
@@ -814,6 +846,9 @@ class QuestStageViewBuilder:
         )
         latest_metrics_summary = latest_experiment_payload.get("metrics_summary") or latest_result_payload.get("metrics_summary") or {}
         latest_run_id = str(latest_experiment_payload.get("run_id") or "").strip() or None
+        latest_evaluation_summary = _evaluation_summary(
+            latest_experiment_payload.get("evaluation_summary") or latest_result_payload.get("evaluation_summary")
+        )
 
         analysis_manifests = self._analysis_manifests()
         analysis_manifest = next(
@@ -883,6 +918,7 @@ class QuestStageViewBuilder:
                 _field("Latest Metrics", latest_metrics_summary or "Not recorded"),
                 _field("Delta vs Baseline", latest_progress_eval.get("delta_vs_baseline") or "Not recorded"),
                 _field("Breakthrough", latest_progress_eval.get("breakthrough_level") or "Not recorded"),
+                *_evaluation_summary_fields(latest_evaluation_summary),
             ],
             key_files=self._dedupe_files(
                 [
@@ -940,6 +976,7 @@ class QuestStageViewBuilder:
                         "verdict": latest_experiment_payload.get("verdict"),
                         "metrics_summary": latest_metrics_summary,
                         "progress_eval": latest_progress_eval,
+                        "evaluation_summary": latest_evaluation_summary,
                         "run_md_path": latest_experiment_paths.get("run_md"),
                         "result_json_path": latest_experiment_paths.get("result_json"),
                     }
@@ -979,6 +1016,7 @@ class QuestStageViewBuilder:
         result_payload = read_json(Path(paths.get("result_json")), {}) if str(paths.get("result_json") or "").strip() else {}
         progress_eval = payload.get("progress_eval") or result_payload.get("progress_eval") or {}
         baseline_ref = payload.get("baseline_ref") or result_payload.get("baseline_ref") or {}
+        evaluation_summary = _evaluation_summary(payload.get("evaluation_summary") or result_payload.get("evaluation_summary"))
         run_id = str(payload.get("run_id") or "pending").strip() or "pending"
         note = (
             str(payload.get("summary") or result_payload.get("conclusion") or (progress_eval or {}).get("reason") or "").strip()
@@ -1028,6 +1066,7 @@ class QuestStageViewBuilder:
                 _field("Metrics Summary", metrics_summary or "Not recorded"),
                 _field("Delta vs Baseline", (progress_eval or {}).get("delta_vs_baseline") or "Not recorded"),
                 _field("Breakthrough Level", (progress_eval or {}).get("breakthrough_level") or "Not recorded"),
+                *_evaluation_summary_fields(evaluation_summary),
             ],
             key_files=key_files,
             history=self._artifact_history(experiment_items),
@@ -1040,6 +1079,7 @@ class QuestStageViewBuilder:
                     "baseline_ref": baseline_ref,
                     "metrics_summary": metrics_summary,
                     "progress_eval": progress_eval,
+                    "evaluation_summary": evaluation_summary,
                     "result_payload": result_payload,
                 }
             },
@@ -1141,6 +1181,9 @@ class QuestStageViewBuilder:
                     "reviewer_resolution": detail_payload.get("reviewer_resolution"),
                     "manuscript_update_hint": detail_payload.get("manuscript_update_hint"),
                     "next_recommendation": detail_payload.get("next_recommendation"),
+                    "evaluation_summary": _evaluation_summary(
+                        run_payload.get("evaluation_summary") or detail_payload.get("evaluation_summary")
+                    ),
                     "deviations": detail_payload.get("deviations") or [],
                     "evidence_paths": detail_payload.get("evidence_paths") or [],
                     "plan_path": item.get("plan_path"),
@@ -1233,8 +1276,11 @@ class QuestStageViewBuilder:
             self._file_entry("paper/writing_plan.md", label="Writing Plan", description="Paper writing plan."),
             self._file_entry("paper/references.bib", label="References", description="Bibliography file."),
             self._file_entry("paper/claim_evidence_map.json", label="Claim-Evidence Map", description="Claim to evidence mapping."),
+            self._file_entry("paper/baseline_inventory.json", label="Baseline Inventory", description="Canonical and supplementary baseline inventory for writing."),
             self._file_entry("paper/build/compile_report.json", label="Compile Report", description="Paper build/compile report."),
             self._file_entry("paper/paper_bundle_manifest.json", label="Bundle Manifest", description="Final paper bundle manifest."),
+            self._file_entry("release/open_source/manifest.json", label="Open Source Manifest", description="Open-source cleanup and release preparation manifest."),
+            self._file_entry("release/open_source/cleanup_plan.md", label="Open Source Cleanup Plan", description="Checklist for cleaning the paper branch into a public release."),
             self._file_entry(latex_root_rel, label="LaTeX Sources", description="LaTeX source folder.", expected_kind="directory"),
             self._file_entry(main_tex_rel, label="Main TeX", description="Primary TeX source file."),
         ]

package/src/deepscientist/runners/codex.py

@@ -530,6 +530,7 @@ class CodexRunner:
 
         env = dict(**os.environ)
         env["CODEX_HOME"] = str(codex_home)
+        env["DEEPSCIENTIST_HOME"] = str(self.home)
         env["DS_HOME"] = str(self.home)
         env["DS_QUEST_ID"] = request.quest_id
         env["DS_QUEST_ROOT"] = str(request.quest_root)
@@ -846,6 +847,7 @@ class CodexRunner:
             tool_timeout_sec = None
 
         shared_env = {
+            "DEEPSCIENTIST_HOME": str(self.home),
             "DS_HOME": str(self.home),
             "DS_QUEST_ID": quest_id,
             "DS_QUEST_ROOT": str(quest_root),

package/src/deepscientist/shared.py

@@ -71,7 +71,8 @@ def write_json(path: Path, payload: Any) -> None:
     )
 
 
-def read_json(path: Path, default: Any = None) -> Any:
+def read_json(path: Path | str, default: Any = None) -> Any:
+    path = Path(path)
     if not path.exists():
         return default
     payload = path.read_text(encoding="utf-8").strip()
@@ -155,35 +156,61 @@ def which(binary: str) -> str | None:
     return shutil.which(binary)
 
 
-def resolve_runner_binary(binary: str, *, runner_name: str | None = None) -> str | None:
-    normalized = str(binary or "").strip()
+def _resolve_executable_reference(reference: str) -> str | None:
+    normalized = str(reference or "").strip()
     if not normalized:
         return None
 
     candidate = Path(normalized).expanduser()
     if candidate.is_absolute() or os.path.sep in normalized or (os.path.altsep and os.path.altsep in normalized):
         return str(candidate) if candidate.exists() else None
+    return shutil.which(normalized)
+
+
+def _codex_repo_roots() -> list[Path]:
+    roots: list[Path] = []
+    configured = str(os.environ.get("DEEPSCIENTIST_REPO_ROOT") or "").strip()
+    if configured:
+        roots.append(Path(configured).expanduser().resolve())
+    roots.append(Path(__file__).resolve().parents[2])
+
+    deduped: list[Path] = []
+    seen: set[str] = set()
+    for root in roots:
+        key = str(root)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(root)
+    return deduped
 
-    discovered = shutil.which(normalized)
-    if discovered:
-        return discovered
+
+def resolve_runner_binary(binary: str, *, runner_name: str | None = None) -> str | None:
+    normalized = str(binary or "").strip()
+    if not normalized:
+        return None
+
+    resolved_reference = _resolve_executable_reference(normalized)
+    candidate = Path(normalized).expanduser()
+    if candidate.is_absolute() or os.path.sep in normalized or (os.path.altsep and os.path.altsep in normalized):
+        return resolved_reference
 
     normalized_runner = str(runner_name or candidate.name or normalized).strip().lower()
     if normalized_runner != "codex":
-        return None
+        return resolved_reference
 
     for env_name in ("DEEPSCIENTIST_CODEX_BINARY", "DS_CODEX_BINARY"):
         override = os.environ.get(env_name)
         if override:
-            override_path = Path(override).expanduser()
-            if override_path.exists():
-                return str(override_path)
+            resolved_override = _resolve_executable_reference(override)
+            if resolved_override:
+                return resolved_override
 
-    repo_root = Path(__file__).resolve().parents[2]
-    node_bin_root = repo_root / "node_modules" / ".bin"
     names = ["codex.cmd", "codex.exe", "codex"] if sys.platform.startswith("win") else ["codex"]
-    for name in names:
-        package_local = node_bin_root / name
-        if package_local.exists():
-            return str(package_local)
-    return None
+    for root in _codex_repo_roots():
+        node_bin_root = root / "node_modules" / ".bin"
+        for name in names:
+            package_local = node_bin_root / name
+            if package_local.exists():
+                return str(package_local)
+    return resolved_reference

package/src/prompts/connectors/lingzhu.md

@@ -10,3 +10,6 @@
 - lingzhu_progress_rule: for long-running work, your first substantive reply should contain either the direct answer or the first concrete checkpoint, not a duplicate transport acknowledgement
 - lingzhu_safety_rule: request only actions that are clearly justified by the current quest and understandable to the human user
 - lingzhu_text_rule: even when requesting `surface_actions`, always include a clear text explanation of what is happening and why
+- lingzhu_reply_style_rule: for Lingzhu-facing user-visible text sent through `artifact.interact(...)`, keep the message clear, concise, respectful, and high-information-density
+- lingzhu_reply_length_rule: for each Lingzhu-facing `artifact.interact(...)` message, normally answer in at most 2 to 3 sentences unless the user explicitly asks for more detail
+- lingzhu_summary_first_rule: in Lingzhu-facing `artifact.interact(...)` messages, usually give only the synopsis and key facts needed for the user's next decision or understanding; avoid long preambles, repetition, and low-signal detail

package/src/prompts/connectors/qq.md

@@ -4,6 +4,14 @@
 - connector_contract_scope: loaded only when QQ is the active or bound external connector for this quest
 - connector_contract_goal: use `artifact.interact(...)` as the main durable user-visible thread on QQ instead of exposing raw internal runner or tool chatter
 - qq_reply_style: keep QQ replies concise, milestone-first, respectful, and easy to scan on a phone
+- qq_reply_length_rule: for ordinary QQ progress updates, normally use only 2 to 4 short sentences, or 3 short bullets at most
+- qq_summary_first_rule: start with the conclusion the user cares about, then what it means, then the next action
+- qq_progress_shape_rule: make the current task, the main difficulty or latest real progress, and the next concrete measure explicit whenever possible
+- qq_eta_rule: for baseline reproduction, main experiments, analysis experiments, and other important long-running research phases, include a rough ETA for the next meaningful result or the next update; if uncertain, say that and still give the next check-in window
+- qq_tool_call_keepalive_rule: for ordinary active work, if roughly 10 to 30 tool calls pass without a user-visible checkpoint, send one concise QQ progress update before continuing
+- qq_internal_detail_rule: omit worker names, heartbeat timestamps, retry counters, pending/running/completed counts, file names, and monitor-window narration unless the user asked for them or the detail changes the recommended action
+- qq_translation_rule: convert internal execution and file-management work into user value, such as saying the baseline record is now organized for easier later comparison instead of listing touched files
+- qq_preflight_rule: before sending a QQ progress update, rewrite it if it still sounds like a monitoring log, execution diary, or file inventory
 - qq_operator_surface_rule: treat QQ as an operator surface for coordination and milestone delivery, not as a full artifact browser
 - qq_default_text_rule: plain text is the default and safest QQ mode
 - qq_absolute_path_rule: when you request native QQ image or file delivery via an attachment `path`, prefer an absolute path
@@ -39,12 +47,44 @@
 
 ## Examples
 
+### 0. Bad vs good QQ progress update
+
+Bad:
+
+```text
+我刚结束新的 60 秒监控窗，当前还是 15 pending / 2 running / 3 completed。local-gptoss + tare + GSM8K_DSPy 的 heartbeat 已推进到 00:07:10 UTC，local-qwen + atare + BBH_tracking_shuffled_objects_five_objects 也推进到 00:06:38 UTC。我已经同步更新 status、summary、execution 和 inventory，接下来继续看下一段 120 秒恢复窗。
+```
+
+Why bad:
+
+- it forces the user to infer the conclusion from telemetry
+- it exposes internal counters, timestamps, worker labels, and file actions that usually do not help the user
+- it reads like a monitoring transcript, not like a collaborator update
+
+Good:
+
+```text
+公开 baseline 还在继续推进，暂时不需要额外修补。当前主要情况是整体在往前走，但其中一条线仍然更慢、更不稳定。接下来我会继续盯下一轮结果，预计 20 到 30 分钟内会有下一次关键判断；如果更早出现完成、再次卡住，或者需要干预，我会提前同步给您。
+```
+
+Why good:
+
+- it starts with the conclusion the user actually needs
+- it keeps the meaningful risk but removes unnecessary internal telemetry
+- it tells the user exactly what will happen next
+
+English-style reference shape:
+
+```text
+I'm working on {current task}. The main issue right now is {difficulty or risk}, but {latest real progress or current judgment}. Next I'll {concrete next measure}. You should hear from me again in about {ETA}, or sooner if {important condition} happens.
+```
+
 ### 1. Plain-text QQ progress update
 
 ```python
 artifact.interact(
     kind="progress",
-    message="主实验第一轮已经跑完，结果稳定。我正在继续做消融，下一次会同步关键变化。",
+    message="主实验第一轮已经跑完，结果目前比较稳定。接下来我会继续补消融，确认这个提升是不是稳得住。下一次我只同步关键变化给您。",
     reply_mode="threaded",
 )
 ```
@@ -56,7 +96,7 @@ Use the normal `artifact.interact(...)` call. When DeepScientist already knows t
 ```python
 artifact.interact(
     kind="progress",
-    message="我已经看完您刚才提到的那篇论文，正在整理它和当前 baseline 的核心差异，稍后给您一个更完整的结论。",
+    message="我已经看完您刚才提到的那篇论文，也确认了它和当前 baseline 的核心差异。接下来我会把真正影响路线选择的部分整理出来，再给您一个更完整的结论。",
     reply_mode="threaded",
 )
 ```