@researai/deepscientist 1.5.15 → 1.5.16

package/src/deepscientist/runners/codex.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import json
 import os
 import signal
-import shutil
 import subprocess
 import sys
 import threading
@@ -11,12 +10,16 @@ from pathlib import Path
 from typing import Any
 
 from ..artifact import ArtifactService
-from ..codex_cli_compat import adapt_profile_only_provider_config, normalize_codex_reasoning_effort
+from ..codex_cli_compat import (
+    materialize_codex_runtime_home,
+    normalize_codex_reasoning_effort,
+    provider_profile_metadata_from_home,
+)
 from ..config import ConfigManager
 from ..gitops import export_git_graph
 from ..prompts import PromptBuilder
 from ..runtime_logs import JsonlLogger
-from ..shared import append_jsonl, ensure_dir, generate_id, read_text, read_yaml, resolve_runner_binary, utc_now, write_json, write_text
+from ..shared import append_jsonl, ensure_dir, generate_id, read_yaml, resolve_runner_binary, utc_now, write_json, write_text
 from ..web_search import extract_web_search_payload
 from .base import RunRequest, RunResult
 
@@ -69,6 +72,11 @@ _BUILTIN_MCP_TOOL_APPROVALS: dict[str, tuple[str, ...]] = {
     ),
 }
 
+_PROVIDER_ENV_CONFLICT_KEYS = (
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+)
+
 
 def _compact_text(value: object, *, limit: int = 1200) -> str:
     if value is None:
@@ -195,7 +203,9 @@ def _iter_event_texts(event: dict[str, Any]) -> list[str]:
                     if isinstance(value, str) and value.strip():
                         texts.append(value)
     delta = event.get("delta")
-    if isinstance(delta, dict):
+    if isinstance(delta, str) and delta.strip():
+        texts.append(delta)
+    elif isinstance(delta, dict):
         for key in ("text", "content"):
             value = delta.get(key)
             if isinstance(value, str) and value.strip():
@@ -222,6 +232,36 @@ def _web_search_text_payload(item: dict[str, Any]) -> str:
     return _compact_text(payload, limit=2400)
 
 
+def _message_stream_id(event: dict[str, Any], item: dict[str, Any], *, run_id: str, kind: str) -> str:
+    for value in (
+        event.get("stream_id"),
+        item.get("stream_id"),
+        event.get("message_id"),
+        item.get("message_id"),
+        event.get("item_id"),
+        item.get("id"),
+        event.get("output_item_id"),
+        event.get("response_id"),
+    ):
+        if value:
+            return str(value)
+    normalized_kind = str(kind or "message").strip().lower() or "message"
+    return f"{run_id}:{normalized_kind}"
+
+
+def _message_id(event: dict[str, Any], item: dict[str, Any], *, stream_id: str) -> str:
+    for value in (
+        event.get("message_id"),
+        item.get("message_id"),
+        event.get("item_id"),
+        item.get("id"),
+        event.get("output_item_id"),
+    ):
+        if value:
+            return str(value)
+    return stream_id
+
+
 def _message_events(
     event: dict[str, Any],
     *,
@@ -238,6 +278,8 @@ def _message_events(
 
     if item_type == "agent_message":
         texts = _dedupe_texts(_iter_event_texts(event))
+        stream_id = _message_stream_id(event, item, run_id=run_id, kind="assistant")
+        message_id = _message_id(event, item, stream_id=stream_id)
         for text in texts:
             quest_events.append(
                 {
@@ -248,6 +290,8 @@ def _message_events(
                     "source": "codex",
                     "skill_id": skill_id,
                     "text": text,
+                    "stream_id": stream_id,
+                    "message_id": message_id,
                     "created_at": created_at,
                 }
             )
@@ -255,6 +299,8 @@ def _message_events(
 
     if item_type in {"reasoning", "reasoning_summary"} or "reasoning" in event_type:
         texts = _dedupe_texts(_iter_event_texts(event))
+        stream_id = _message_stream_id(event, item, run_id=run_id, kind=item_type or "reasoning")
+        message_id = _message_id(event, item, stream_id=stream_id)
         for text in texts:
             quest_events.append(
                 {
@@ -265,6 +311,8 @@ def _message_events(
                     "source": "codex",
                     "skill_id": skill_id,
                     "text": text,
+                    "stream_id": stream_id,
+                    "message_id": message_id,
                     "kind": item_type or "reasoning",
                     "created_at": created_at,
                 }
@@ -278,6 +326,8 @@ def _message_events(
         return [], []
 
     texts = _dedupe_texts(_iter_event_texts(event))
+    stream_id = _message_stream_id(event, item, run_id=run_id, kind="assistant")
+    message_id = _message_id(event, item, stream_id=stream_id)
     for text in texts:
         quest_events.append(
             {
@@ -288,6 +338,8 @@ def _message_events(
                 "source": "codex",
                 "skill_id": skill_id,
                 "text": text,
+                "stream_id": stream_id,
+                "message_id": message_id,
                 "created_at": created_at,
             }
         )
@@ -729,6 +781,7 @@ class CodexRunner:
                 continue
             env[env_key] = env_value
         env["CODEX_HOME"] = str(codex_home)
+        env = self._sanitize_provider_env(env, runner_config=runner_config)
         env["DEEPSCIENTIST_HOME"] = str(self.home)
         env["DS_HOME"] = str(self.home)
         env["DS_QUEST_ID"] = request.quest_id
@@ -975,6 +1028,8 @@ class CodexRunner:
         resolved_runner_config = runner_config if isinstance(runner_config, dict) else self._load_runner_config()
         profile = str(resolved_runner_config.get("profile") or "").strip()
         normalized_model = str(request.model or "").strip()
+        if profile and normalized_model.lower() not in {"", "inherit", "default", "codex-default"}:
+            normalized_model = "inherit"
         command = [
             resolved_binary or self.binary,
             "--search",
@@ -1019,36 +1074,16 @@ class CodexRunner:
         run_id: str,
         runner_config: dict[str, Any] | None = None,
     ) -> Path:
-        target = ensure_dir(workspace_root / ".codex")
+        target = ensure_dir(workspace_root / ".ds" / "codex-home")
         resolved_runner_config = runner_config if isinstance(runner_config, dict) else self._load_runner_config()
         configured_home = str(resolved_runner_config.get("config_dir") or os.environ.get("CODEX_HOME") or str(Path.home() / ".codex"))
         profile = str(resolved_runner_config.get("profile") or "").strip()
-        source = Path(configured_home).expanduser()
-        for filename in ("config.toml", "auth.json"):
-            source_path = source / filename
-            target_path = target / filename
-            if not source_path.exists():
-                continue
-            if source_path.resolve() == target_path.resolve():
-                continue
-            shutil.copy2(source_path, target_path)
-        config_path = target / "config.toml"
-        if profile and config_path.exists():
-            adapted_text, _ = adapt_profile_only_provider_config(read_text(config_path), profile=profile)
-            write_text(config_path, adapted_text)
-        ensure_dir(target / "skills")
-        quest_skills_root = quest_root / ".codex" / "skills"
-        if quest_skills_root.exists():
-            for source_path in sorted(quest_skills_root.rglob("*")):
-                relative = source_path.relative_to(quest_skills_root)
-                target_path = target / "skills" / relative
-                if source_path.is_dir():
-                    ensure_dir(target_path)
-                    continue
-                if source_path.resolve() == target_path.resolve():
-                    continue
-                ensure_dir(target_path.parent)
-                shutil.copy2(source_path, target_path)
+        materialize_codex_runtime_home(
+            source_home=configured_home,
+            target_home=target,
+            profile=profile,
+            quest_codex_root=quest_root / ".codex",
+        )
         self._inject_built_in_mcp(
             target,
             quest_root=quest_root,
@@ -1157,3 +1192,23 @@ class CodexRunner:
         except (TypeError, ValueError):
             return None
         return timeout if timeout > 0 else None
+
+    @staticmethod
+    def _sanitize_provider_env(
+        env: dict[str, str],
+        *,
+        runner_config: dict[str, Any] | None = None,
+    ) -> dict[str, str]:
+        resolved_runner_config = runner_config if isinstance(runner_config, dict) else {}
+        profile = str(resolved_runner_config.get("profile") or "").strip()
+        config_home = str(resolved_runner_config.get("config_dir") or env.get("CODEX_HOME") or "").strip()
+        if not profile or not config_home:
+            return env
+        metadata = provider_profile_metadata_from_home(config_home, profile=profile)
+        requires_openai_auth = metadata.get("requires_openai_auth")
+        if requires_openai_auth is not False:
+            return env
+        sanitized = dict(env)
+        for key in _PROVIDER_ENV_CONFLICT_KEYS:
+            sanitized.pop(key, None)
+        return sanitized

package/src/deepscientist/skills/__init__.py

@@ -1,4 +1,4 @@
 from .installer import SkillInstaller
-from .registry import SkillBundle, discover_skill_bundles
+from .registry import SkillBundle, companion_skill_ids, discover_skill_bundles, stage_skill_ids
 
-__all__ = ["SkillBundle", "SkillInstaller", "discover_skill_bundles"]
+__all__ = ["SkillBundle", "SkillInstaller", "discover_skill_bundles", "stage_skill_ids", "companion_skill_ids"]

package/src/deepscientist/skills/installer.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import hashlib
+import re
 import shutil
 from pathlib import Path
 from uuid import uuid4
@@ -8,6 +10,10 @@ from ..memory.frontmatter import load_markdown_document
 from ..shared import ensure_dir, read_json, utc_now, write_json
 from .registry import discover_skill_bundles
 
+_PROMPT_SYNC_STATE_FILENAME = ".deepscientist-prompt-sync.json"
+_PROMPT_VERSIONS_DIRNAME = "prompt_versions"
+_PROMPT_VERSIONS_INDEX_FILENAME = "index.json"
+
 
 class SkillInstaller:
     def __init__(self, repo_root: Path, home: Path) -> None:
@@ -40,9 +46,9 @@ class SkillInstaller:
             "notes": [],
         }
 
-    def sync_quest(self, quest_root: Path) -> dict:
+    def sync_quest(self, quest_root: Path, *, installed_version: str | None = None) -> dict:
+        prompt_sync = self.sync_quest_prompts(quest_root, installed_version=installed_version)
         prompts_root = ensure_dir(quest_root / ".codex" / "prompts")
-        self._sync_prompt_tree(prompts_root)
         codex_root = ensure_dir(quest_root / ".codex" / "skills")
         claude_root = ensure_dir(quest_root / ".claude" / "agents")
         copied_codex: list[str] = []
@@ -61,12 +67,13 @@ class SkillInstaller:
         self._prune_bundle_targets(claude_root, expected_claude)
         return {
             "prompts": [str(path) for path in sorted(prompts_root.rglob("*")) if path.is_file()],
+            "prompt_sync": prompt_sync,
             "codex": copied_codex,
             "claude": copied_claude,
             "notes": [],
         }
 
-    def sync_existing_quests(self) -> dict:
+    def sync_existing_quests(self, *, installed_version: str | None = None) -> dict:
         quests_root = self.home / "quests"
         synced: list[dict[str, object]] = []
         if not quests_root.exists():
@@ -79,13 +86,15 @@ class SkillInstaller:
                 continue
             if not (quest_root / "quest.yaml").exists():
                 continue
-            result = self.sync_quest(quest_root)
+            result = self.sync_quest(quest_root, installed_version=installed_version)
             synced.append(
                 {
                     "quest_id": quest_root.name,
                     "quest_root": str(quest_root),
                     "codex_count": len(result.get("codex") or []),
                     "claude_count": len(result.get("claude") or []),
+                    "prompt_backup_id": (result.get("prompt_sync") or {}).get("backup_id"),
+                    "prompt_fingerprint": (result.get("prompt_sync") or {}).get("prompt_fingerprint"),
                 }
             )
         return {
@@ -127,11 +136,193 @@ class SkillInstaller:
             summary["global"] = self.sync_global()
             summary["global_synced"] = True
         if sync_existing_quests_enabled:
-            summary["existing_quests"] = self.sync_existing_quests()
+            summary["existing_quests"] = self.sync_existing_quests(installed_version=normalized_version)
             summary["existing_quests_synced"] = True
         self._write_release_sync_state(summary)
         return summary
 
+    def sync_quest_prompts(
+        self,
+        quest_root: Path,
+        *,
+        installed_version: str | None = None,
+    ) -> dict[str, object]:
+        prompts_root = ensure_dir(quest_root / ".codex" / "prompts")
+        source_root = self.repo_root / "src" / "prompts"
+        normalized_version = self._normalized_installed_version(installed_version)
+        previous_state = self._read_prompt_sync_state(prompts_root)
+        current_fingerprint = self._prompt_tree_fingerprint(prompts_root, exclude_state_file=True)
+        source_fingerprint = self._prompt_tree_fingerprint(source_root, exclude_state_file=False)
+        backup_id: str | None = None
+        updated = False
+
+        if current_fingerprint != source_fingerprint:
+            if current_fingerprint:
+                backup_id = self._backup_prompt_tree(
+                    quest_root,
+                    prompts_root=prompts_root,
+                    installed_version=str(previous_state.get("installed_version") or normalized_version),
+                    prompt_fingerprint=current_fingerprint,
+                )
+            self._sync_prompt_tree(prompts_root)
+            updated = True
+
+        prompt_state = {
+            "installed_version": normalized_version,
+            "prompt_fingerprint": self._prompt_tree_fingerprint(prompts_root, exclude_state_file=True),
+            "synced_at": utc_now(),
+            "backup_id": backup_id,
+            "source_root": str(source_root),
+        }
+        write_json(self._prompt_sync_state_path(prompts_root), prompt_state)
+        return {
+            "updated": updated,
+            "backup_id": backup_id,
+            "prompt_fingerprint": prompt_state["prompt_fingerprint"],
+            "installed_version": normalized_version,
+            "source_root": str(source_root),
+            "active_root": str(prompts_root),
+            "versions_root": str(self._prompt_versions_root(quest_root)),
+        }
+
+    def list_prompt_versions(self, quest_root: Path) -> list[dict[str, object]]:
+        payload = read_json(self._prompt_versions_index_path(quest_root), {})
+        versions = payload.get("versions") if isinstance(payload.get("versions"), list) else []
+        return [dict(item) for item in versions if isinstance(item, dict)]
+
+    def resolve_prompt_version_root(self, quest_root: Path, selection: str) -> Path | None:
+        normalized = str(selection or "").strip()
+        if not normalized:
+            return None
+        exact_root = self._prompt_versions_root(quest_root) / normalized
+        if exact_root.exists():
+            return exact_root
+        candidates = [
+            dict(item)
+            for item in self.list_prompt_versions(quest_root)
+            if str(item.get("installed_version") or "").strip() == normalized
+        ]
+        if not candidates:
+            return None
+        candidates.sort(key=lambda item: str(item.get("created_at") or ""))
+        selected_path = Path(str(candidates[-1].get("path") or "")).expanduser()
+        return selected_path if selected_path.exists() else None
+
+    @staticmethod
+    def _normalized_installed_version(installed_version: str | None) -> str:
+        normalized = str(installed_version or "").strip()
+        if normalized:
+            return normalized
+        from .. import __version__
+
+        return str(__version__ or "").strip() or "unknown"
+
+    def _backup_prompt_tree(
+        self,
+        quest_root: Path,
+        *,
+        prompts_root: Path,
+        installed_version: str,
+        prompt_fingerprint: str,
+    ) -> str:
+        versions_root = ensure_dir(self._prompt_versions_root(quest_root))
+        backup_id = ""
+        target_root: Path | None = None
+        for _attempt in range(8):
+            backup_id = self._unique_prompt_backup_id(
+                versions_root,
+                installed_version=installed_version,
+                prompt_fingerprint=prompt_fingerprint,
+            )
+            target_root = versions_root / backup_id
+            try:
+                shutil.copytree(prompts_root, target_root)
+                break
+            except FileExistsError:
+                # Another sync run may have created the same backup directory between
+                # name selection and copy. Regenerate a fresh id and retry.
+                continue
+        else:
+            raise FileExistsError(
+                f"Failed to allocate a unique prompt backup directory under `{versions_root}` after multiple attempts."
+            )
+        assert target_root is not None
+        entry = {
+            "backup_id": backup_id,
+            "installed_version": str(installed_version or "").strip() or "unknown",
+            "prompt_fingerprint": prompt_fingerprint,
+            "created_at": utc_now(),
+            "path": str(target_root),
+        }
+        versions = self.list_prompt_versions(quest_root)
+        versions = [item for item in versions if str(item.get("backup_id") or "").strip() != backup_id]
+        versions.append(entry)
+        versions.sort(key=lambda item: str(item.get("created_at") or ""))
+        write_json(self._prompt_versions_index_path(quest_root), {"versions": versions})
+        return backup_id
+
+    @staticmethod
+    def _prompt_versions_root(quest_root: Path) -> Path:
+        return ensure_dir(quest_root / ".codex" / _PROMPT_VERSIONS_DIRNAME)
+
+    @staticmethod
+    def _prompt_versions_index_path(quest_root: Path) -> Path:
+        return SkillInstaller._prompt_versions_root(quest_root) / _PROMPT_VERSIONS_INDEX_FILENAME
+
+    @staticmethod
+    def _prompt_sync_state_path(prompts_root: Path) -> Path:
+        return prompts_root / _PROMPT_SYNC_STATE_FILENAME
+
+    def _read_prompt_sync_state(self, prompts_root: Path) -> dict[str, object]:
+        payload = read_json(self._prompt_sync_state_path(prompts_root), {})
+        return payload if isinstance(payload, dict) else {}
+
+    @staticmethod
+    def _sanitize_prompt_label(value: str) -> str:
+        normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", str(value or "").strip()).strip("-")
+        return normalized or "unknown"
+
+    def _unique_prompt_backup_id(
+        self,
+        versions_root: Path,
+        *,
+        installed_version: str,
+        prompt_fingerprint: str,
+    ) -> str:
+        version_label = self._sanitize_prompt_label(installed_version)
+        timestamp_label = self._sanitize_prompt_label(
+            utc_now().replace(":", "").replace("+00:00", "Z")
+        )
+        fingerprint_label = (str(prompt_fingerprint or "").strip() or "unknown")[:12]
+        base = f"{version_label}__prompts-{fingerprint_label}__{timestamp_label}"
+        candidate = base
+        counter = 2
+        while (versions_root / candidate).exists():
+            candidate = f"{base}__{counter}"
+            counter += 1
+        return candidate
+
+    @staticmethod
+    def _prompt_tree_fingerprint(root: Path, *, exclude_state_file: bool) -> str:
+        if not root.exists():
+            return ""
+        files = [
+            path
+            for path in sorted(root.rglob("*"))
+            if path.is_file()
+            and not (exclude_state_file and path.name == _PROMPT_SYNC_STATE_FILENAME)
+        ]
+        if not files:
+            return ""
+        hasher = hashlib.sha256()
+        for path in files:
+            relative = path.relative_to(root).as_posix()
+            hasher.update(relative.encode("utf-8"))
+            hasher.update(b"\0")
+            hasher.update(hashlib.sha256(path.read_bytes()).hexdigest().encode("ascii"))
+            hasher.update(b"\0")
+        return hasher.hexdigest()
+
     def _sync_claude_projection(self, bundle, target_root: Path) -> Path:
         target = target_root / f"deepscientist-{bundle.skill_id}.md"
         if bundle.claude_md and bundle.claude_md.exists():

package/src/deepscientist/skills/registry.py

@@ -2,9 +2,34 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Any
 
 from ..memory.frontmatter import load_markdown_document
 
+_DEFAULT_STAGE_SKILLS = (
+    "scout",
+    "baseline",
+    "idea",
+    "optimize",
+    "experiment",
+    "analysis-campaign",
+    "write",
+    "finalize",
+    "decision",
+)
+
+_DEFAULT_COMPANION_SKILLS = (
+    "figure-polish",
+    "intake-audit",
+    "review",
+    "rebuttal",
+)
+
+_SKILL_ROLE_FALLBACK_ORDER = {
+    **{skill_id: index for index, skill_id in enumerate(_DEFAULT_STAGE_SKILLS, start=10)},
+    **{skill_id: 100 + index for index, skill_id in enumerate(_DEFAULT_COMPANION_SKILLS, start=10)},
+}
+
 
 @dataclass(frozen=True)
 class SkillBundle:
@@ -13,6 +38,8 @@ class SkillBundle:
     description: str
     root: Path
     skill_md: Path
+    role: str
+    metadata: dict[str, Any]
     openai_yaml: Path | None = None
     claude_md: Path | None = None
 
@@ -24,6 +51,29 @@ def _parse_frontmatter(path: Path) -> dict:
     return metadata
 
 
+def _normalize_skill_role(skill_id: str, metadata: dict[str, Any]) -> str:
+    raw = str(metadata.get("skill_role") or metadata.get("role") or "").strip().lower()
+    if raw in {"stage", "companion", "custom"}:
+        return raw
+    if skill_id in _DEFAULT_STAGE_SKILLS:
+        return "stage"
+    if skill_id in _DEFAULT_COMPANION_SKILLS:
+        return "companion"
+    return "custom"
+
+
+def _skill_order(skill_id: str, metadata: dict[str, Any]) -> tuple[int, str]:
+    raw = metadata.get("skill_order")
+    if isinstance(raw, int):
+        return raw, skill_id
+    if isinstance(raw, str):
+        try:
+            return int(raw.strip()), skill_id
+        except ValueError:
+            pass
+    return _SKILL_ROLE_FALLBACK_ORDER.get(skill_id, 10_000), skill_id
+
+
 def discover_skill_bundles(repo_root: Path) -> list[SkillBundle]:
     bundles: list[SkillBundle] = []
     skills_root = repo_root / "src" / "skills"
@@ -41,8 +91,24 @@ def discover_skill_bundles(repo_root: Path) -> list[SkillBundle]:
                 description=metadata.get("description", ""),
                 root=skill_md.parent,
                 skill_md=skill_md,
+                role=_normalize_skill_role(skill_id, metadata),
+                metadata=metadata,
                 openai_yaml=(skill_md.parent / "agents" / "openai.yaml") if (skill_md.parent / "agents" / "openai.yaml").exists() else None,
                 claude_md=(skill_md.parent / "agents" / "claude.md") if (skill_md.parent / "agents" / "claude.md").exists() else None,
             )
         )
+    bundles.sort(key=lambda bundle: _skill_order(bundle.skill_id, bundle.metadata))
     return bundles
+
+
+def skill_ids_for_role(repo_root: Path, role: str) -> tuple[str, ...]:
+    normalized = str(role or "").strip().lower()
+    return tuple(bundle.skill_id for bundle in discover_skill_bundles(repo_root) if bundle.role == normalized)
+
+
+def stage_skill_ids(repo_root: Path) -> tuple[str, ...]:
+    return skill_ids_for_role(repo_root, "stage")
+
+
+def companion_skill_ids(repo_root: Path) -> tuple[str, ...]:
+    return skill_ids_for_role(repo_root, "companion")

package/src/prompts/connectors/qq.md

@@ -6,15 +6,25 @@
 - qq_runtime_ack_rule: the QQ bridge itself emits the immediate transport-level receipt acknowledgement before the model turn starts
 - qq_no_duplicate_ack_rule: do not waste your first model response or first `artifact.interact(...)` call on a redundant receipt-only acknowledgement such as "received", "已收到", or "I am processing" when the bridge already sent that
 - qq_reply_style: keep QQ replies concise, milestone-first, respectful, and easy to scan on a phone
+- qq_report_style_rule: write QQ updates like a short operator report, not like an internal lab notebook; the user should understand the point from the first sentence
 - 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_plain_chinese_rule: when the user is using Chinese, keep the whole QQ message in natural Chinese by default; avoid sudden full-English paragraphs or untranslated internal terms
+- qq_jargon_ban_rule: avoid internal words or team black-talk such as `slice`, `taxonomy`, `claim boundary`, `route`, `surface`, `trace`, `sensitivity`, `checkpoint`, `pending/running/completed`, or similar control jargon unless the user explicitly asked for that layer of detail
+- qq_milestone_tone_rule: for real wins, deliveries, or unblock moments, a short energetic opener such as `报告：`、`有结果了：`、`都搞定了：` is good, but only if the next sentence immediately gives the concrete result
+- qq_energy_rule: keep QQ text lively and warm rather than bureaucratic; sound like a capable research buddy who proactively reports progress, not like a monitoring bot
+- qq_cute_rule: a little cuteness is welcome in Chinese replies, but keep it lightweight and competent rather than overly sweet or role-play-heavy
+- qq_emoji_rule: in Chinese QQ messages, you may use at most one light kaomoji or emoji for milestones, delivery, or encouraging progress, such as `(•̀ᴗ•́)و` or `✨`; avoid stacking multiple symbols, and avoid playful symbols on blockers or bad news
+- qq_english_emoji_rule: in English QQ messages, use emoji instead of kaomoji when a light expressive touch helps, and keep it to at most one per message
+- qq_user_value_rule: every QQ update should make one user-facing payoff explicit, such as whether the user needs to act, whether the result is trustworthy, or what will be delivered next
 - 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, prefer one concise QQ progress update after roughly 6 tool calls when there is already a human-meaningful delta, and do not let work drift beyond roughly 12 tool calls or about 8 minutes without a user-visible checkpoint
 - qq_read_plan_keepalive_rule: if the active work is still mostly reading, comparison, or planning, do not wait too long for a "big result"; send a short QQ-facing checkpoint after about 5 consecutive tool calls if the user would otherwise see silence
 - 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_report_template_rule: the default QQ template is `结论 / 当前判断 -> 一条最关键的结果或阻塞 -> 下一步和回报时间`; if one sentence does not help the user decide what happened, it is not ready to send
 - 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
@@ -68,7 +78,7 @@ Why bad:
 Good:
 
 ```text
-公开 baseline 还在继续推进，暂时不需要额外修补。当前主要情况是整体在往前走，但其中一条线仍然更慢、更不稳定。接下来我会继续盯下一轮结果，预计 20 到 30 分钟内会有下一次关键判断；如果更早出现完成、再次卡住，或者需要干预，我会提前同步给您。
+先跟您报个平安：这轮 baseline 还在稳定推进，目前不用您额外处理。最新变化是主线结果已经开始收敛，只剩一条对照线还比较慢。接下来我会盯住这条慢线，预计 20 到 30 分钟内给您下一次关键判断；如果更早跑完或再次卡住，我会提前同步。
 ```
 
 Why good:
@@ -77,10 +87,10 @@ Why good:
 - it keeps the meaningful risk but removes unnecessary internal telemetry
 - it tells the user exactly what will happen next
 
-English-style reference shape:
+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.
+Conclusion first. Then say the one concrete result or blocker. Then say the next step and when the user should expect the next update.
 ```
 
 ### 1. Plain-text QQ progress update
@@ -88,7 +98,7 @@ I'm working on {current task}. The main issue right now is {difficulty or risk},
 ```python
 artifact.interact(
     kind="progress",
-    message="主实验第一轮已经跑完，结果目前比较稳定。接下来我会继续补消融，确认这个提升是不是稳得住。下一次我只同步关键变化给您。",
+    message="有新进展啦：主实验第一轮已经跑完，而且结果目前比较稳定。接下来我会继续补关键消融，确认这个提升是不是稳得住；下一次我只同步真正影响判断的变化给您。",
     reply_mode="threaded",
 )
 ```
@@ -100,7 +110,7 @@ Use the normal `artifact.interact(...)` call. When DeepScientist already knows t
 ```python
 artifact.interact(
     kind="progress",
-    message="我已经看完您刚才提到的那篇论文，也确认了它和当前 baseline 的核心差异。接下来我会把真正影响路线选择的部分整理出来，再给您一个更完整的结论。",
+    message="我已经看完您刚才提到的那篇论文，并确认了它和当前 baseline 的关键差异。接下来我会把真正影响路线选择的部分整理成一版清楚结论，再给您完整汇报。",
     reply_mode="threaded",
 )
 ```
@@ -112,7 +122,7 @@ Use this only when the active-surface block says `qq_enable_markdown_send: True`
 ```python
 artifact.interact(
     kind="milestone",
-    message="## 主实验完成\n- 指标已稳定超过基线\n- 当前最主要风险是泛化边界仍需补充验证",
+    message="## 报告！主实验完成啦 ✨\n- 当前指标已稳定超过基线\n- 接下来只需要补一轮泛化验证，就能判断这条路线是否可以正式升级",
     reply_mode="threaded",
     connector_hints={"qq": {"render_mode": "markdown"}},
 )
@@ -125,7 +135,7 @@ Use this only when the active-surface block says `qq_enable_file_upload_experime
 ```python
 artifact.interact(
     kind="milestone",
-    message="主实验已经完成。我发一张汇总图给您，便于手机上快速查看。",
+    message="报告！主实验已经完成啦 (•̀ᴗ•́)و 我发一张汇总图给您，方便直接在手机上快速看结论。",
     reply_mode="threaded",
     attachments=[
         {
@@ -144,7 +154,7 @@ artifact.interact(
 ```python
 artifact.interact(
     kind="milestone",
-    message="论文初稿已整理完成。我把 PDF 一并发给您。",
+    message="都整理好啦 📄 论文初稿已经出炉，我把 PDF 一并发给您，您可以直接查看当前版本。",
     reply_mode="threaded",
     attachments=[
         {