@researai/deepscientist 1.5.0 → 1.5.2

package/docs/zh/06_RUNTIME_AND_CANVAS.md

@@ -0,0 +1,271 @@
+# 06 运行时与 Canvas：理解运行流程和图结构
+
+本文描述的是本仓库里 **DeepScientist Core 的当前实现行为**（以代码为准），而不是旧的架构草案。
+
+## 1. 以哪些文件为准
+
+本文的结论来自这些核心文件（不需要全部读完，按需定位即可）：
+
+- Prompt / Skills
+  - `src/prompts/system.md`
+  - `src/skills/*/SKILL.md`
+  - `src/deepscientist/prompts/builder.py`
+- 运行时与 API
+  - `src/deepscientist/daemon/app.py`
+  - `src/deepscientist/daemon/api/handlers.py`
+  - `src/deepscientist/daemon/api/router.py`
+- 任务状态 / Artifact / Memory
+  - `src/deepscientist/quest/service.py`
+  - `src/deepscientist/artifact/service.py`
+  - `src/deepscientist/memory/service.py`
+- 前端 Canvas（Lab）
+  - `src/ui/src/lib/api/lab.ts`
+  - `src/ui/src/lib/plugins/lab/components/LabQuestGraphCanvas.tsx`
+
+## 2. 一句话总结
+
+当前系统不是“重型的阶段机（stage engine）”。
+
+它更像是一个 **Prompt-led + Skill-led + File-led** 的本地研究运行时：
+
+- daemon 负责：排队、turn 调度、API、connector、恢复
+- prompt/skills 负责：研究纪律、产物规范、什么时候需要决策
+- 持久化真相在文件中：quest 文档、artifacts、memory 卡片、Git、bash 日志
+- Canvas 从 Git + artifacts + events 重建，而不是维护一份中心化图数据库
+
+## 3. Anchor（阶段）模型
+
+system prompt 定义的 canonical anchors（会写入 `quest.yaml.active_anchor`）：
+
+- `scout`
+- `baseline`
+- `idea`
+- `experiment`
+- `analysis-campaign`
+- `write`
+- `finalize`
+
+`decision` **不是**一个固定 stage；它是跨阶段的 skill：当继续/停止/分支/归零/需要用户决策时使用。
+
+本系统默认允许“非线性回退”：
+
+- `write -> analysis-campaign / experiment / scout`
+- `experiment -> idea`
+- `analysis-campaign -> experiment`
+
+## 4. 用户发来一条命令/消息后发生什么
+
+有两条路径：
+
+### 4.1 结构化命令（daemon 直接处理）
+
+例如：
+
+- `GET /api/quests/<id>/workflow`
+- `GET /api/quests/<id>/node-traces`
+- `GET /api/quests/<id>/artifacts`
+- `GET /api/quests/<id>/events?format=raw|acp`
+- `GET /api/quests/<id>/git/branches`
+- `POST /api/quests/<id>/control`（pause/stop/resume）
+
+这类请求通常不会启动 runner（除非某个动作明确触发 turn 调度）。
+
+### 4.2 普通对话文本（走 mailbox + turn 调度）
+
+顺序大致为：
+
+1. UI/TUI/connector 提交用户消息
+2. daemon 把消息写入 quest history
+3. 如果 quest 空闲：立刻调度新 turn
+4. 如果 quest 正在运行：消息进入 mailbox 队列，等待 agent 调用 `artifact.interact(...)` 时再投递
+
+关键点：第一条消息往往启动 turn；后续消息通过 `artifact.interact(...)` 才会被“送达 agent”。
+
+## 5. Turn 生命周期（实际实现）
+
+概略流程：
+
+1. `submit_user_message(...)`
+2. `schedule_turn(...)`
+3. worker 线程 `_drain_turns(...)`
+4. `_run_quest_turn(...)`
+5. 选择 runner（当前主要是 Codex）
+6. 选择 skill
+7. 构建 prompt
+8. 运行 runner
+9. agent 使用 MCP / 文件 / Git / shell
+10. 退出并记录 run 输出
+
+### 5.1 如果当前 quest 已经在运行
+
+daemon 维护 per-quest turn state（`running/pending/stop_requested`）。
+
+当 quest 已运行时，新消息不会启动第二个 runner，而是标记为 `pending` 并进入 mailbox，随后通过 `artifact.interact(...)` 投递。
+
+### 5.2 本轮用哪个 skill
+
+当前规则（很重要）：
+
+1. 若用户消息是在回复一个阻塞交互（waiting interaction）：使用 `decision`
+2. 否则读取 `quest.yaml.active_anchor`
+3. 若 `active_anchor` 是标准 skill：使用该 skill
+4. 否则 fallback 到 `decision`
+
+实现位置：`src/deepscientist/daemon/app.py` 的 `_turn_skill_for(...)`。
+
+## 6. 现实：Anchor 推进不是强自动化的
+
+新 quest 通常从：
+
+- `active_anchor: baseline`
+
+开始。但 daemon 目前不会像严格 workflow engine 那样自动把每个 quest 从 A 推到 B。
+
+实践上系统更依赖：
+
+- prompt 的“研究纪律说明”
+- `quest.yaml.active_anchor` 决定本轮 skill
+- agent 写出 artifacts / memory / 文档来维持连续性
+- 遇到路线变化时用 `decision` 明确理由与证据
+
+## 7. Prompt 如何构建
+
+每个 turn 的 prompt 由 `PromptBuilder.build(...)` 组装，主要包含：
+
+1. `src/prompts/system.md`
+2. 运行时上下文（home、quest_root、branch、anchor、runner、locale…）
+3. 当前交互 surface
+4. skills 的根目录与路径（让 agent 去读取对应 SKILL.md）
+5. quest 核心文档（brief/plan/status/summary 等）
+6. 相关 memory（按 stage 偏置）
+7. 最近对话窗口
+8. 当前 turn 的附件摘要
+9. 当前用户消息
+
+### 7.1 当前交互 surface
+
+builder 现在会注入一个 surface block，明确告诉 agent：这一轮主要是在哪个用户表面上交流。
+
+典型字段包括：
+
+- 最新用户消息来源
+- 当前是本地 surface 还是 connector surface
+- 如果是 connector，则给出 connector 名称与 chat type
+- 若当前 turn 来自 QQ，则补充 QQ 的里程碑媒体策略
+
+这仍然是轻量做法：
+
+- 不会把系统变成每个 connector 一套独立 workflow
+- 只是把“这一轮的沟通契约”显式化
+
+### 7.2 当前 turn 的附件摘要
+
+如果最新一条入站用户消息携带了附件元信息，builder 会注入一个很小的附件摘要 block。
+
+这个 block 的作用是：
+
+- 告诉 agent 当前确实有附件
+- 如果已经有可读 sidecar（如提取文本 / OCR / manifest），优先提示它先读这些
+- 避免 agent 对二进制附件是否相关完全靠猜
+
+它只是“摘要层”，不是完整的附件处理流水线。
+
+### 7.3 Skill 以“路径引用”为主
+
+系统并不把 skill 内容全部内联进 prompt，而是把 skill 文件路径注入，然后 prompt 指示 agent 去读对应 `SKILL.md`。
+
+这保证：
+
+- prompt 简洁
+- skill 可独立维护
+- 支持注册表式扩展
+
+### 7.4 Memory 注入是“按阶段偏置”的
+
+不同 stage 会优先检索不同 kind 的 memory（例如 baseline 更看 `episodes/knowledge/decisions`，idea 更看 `ideas/papers` 等）。
+
+## 8. MCP（内建）只有三个 namespace
+
+本仓库的核心约束：只提供 3 个内建 MCP namespace：
+
+- `memory`
+- `artifact`
+- `bash_exec`
+
+### 8.1 `memory`
+
+用于可复用知识的持久化与检索（Markdown + YAML 头）。
+
+### 8.2 `artifact`
+
+用于 quest 状态改变 / 结构化产物 / Git 相关操作（例如 checkpoint、分支准备、实验记录、summary 刷新、git graph 渲染、交互投递）。
+
+### 8.3 `bash_exec`
+
+用于可审计、可恢复的 shell 运行（训练、评测、长脚本等）。
+
+## 9. 为什么 `artifact.interact(...)` 是中枢
+
+`artifact.interact(...)` 同时承担：
+
+1. 写入结构化 artifact（形成可追踪的研究过程）
+2. 可选 checkpoint
+3. 维护交互线程状态（thread/blocking）
+4. 向绑定的 connectors 推送进展（按路由策略）
+5. 消费 mailbox 中排队的用户消息并返还给 agent
+6. 返回近期交互上下文（便于长任务不中断）
+
+这就是为什么“运行中”时用户补充消息不会丢：它们会在下一次 `interact` 时被投递。
+
+## 10. Connector 推送与路由策略（简述）
+
+当允许向外推送时，目标来自 quest bindings：
+
+- `<quest_root>/.ds/bindings.json`
+- home 的 `connectors.yaml` 以及 `_routing` 配置
+
+常见策略：
+
+- `fanout_all`：广播所有
+- `primary_only`：只推送 primary
+- `primary_plus_local`：primary + 本地
+
+默认行为通常是：本地保留 + 一个 preferred connector。
+
+## 11. Canvas（Git 图）如何构建
+
+Canvas 不依赖一份中心化 graph 文件。
+
+当前主要从两类来源重建：
+
+1. Git refs/branches + worktree 元信息（用于“分支视图”）
+2. artifacts + events（用于“事件视图/研究轨迹”）
+
+其中“分支视图”可以表达两种模式（后端已有字段支持）：
+
+1. 不同 idea / 不同主实现的 major branches
+2. 在同一主实验线下分出多个 analysis branches，最终合并回主线写论文
+
+额外实验的当前运行时约束也已经固定：
+
+- 只要某个已完成节点之后还需要补做额外实验，就应通过 `artifact.create_analysis_campaign(...)` 启动
+- 即使只需要 1 个额外实验，也应该作为一个只含 1 个 slice 的 campaign 来创建
+- 这个 campaign 应该从“当前工作节点 / 当前结果节点”分叉，而不是直接在已完成父节点上继续改
+- 这样 Git 历史和 Canvas 里的父子关系才会保持一致
+
+## 12. 事件流与 ACP 兼容
+
+daemon 的实时刷新依赖：
+
+- `GET /api/quests/<id>/events`
+
+该端点可以返回：
+
+- `format=raw`：原生事件
+- `format=acp`：ACP 兼容 envelope（给 Web/TUI/connector 做统一渲染）
+
+重要原则：
+
+- 文件与 artifacts 是持久化真相
+- events 是实时操作流
+- ACP 只是兼容包装层

package/docs/zh/07_MEMORY_AND_MCP.md

@@ -0,0 +1,235 @@
+# 07 Memory 与 MCP：内建 MCP 和记忆协议
+
+本文定义 DeepScientist Core 内建的 3 个 MCP namespace 的含义与使用纪律：
+
+- `memory`
+- `artifact`
+- `bash_exec`
+
+目标很简单：
+
+- `artifact` 驱动 quest 的“研究状态与结构化产物”
+- `memory` 降低重复发现成本（可复用知识）
+- `bash_exec` 运行可审计的持久 shell 工作
+
+## 1. 什么时候用哪个 MCP
+
+当输出是“以后还会复用、需要记住”的内容时，用 `memory`：
+
+- 论文阅读笔记（可复用）
+- 失败模式与排错经验
+- 选择/否决某个 idea 的稳定理由
+- 评测/指标的稳定注意事项（metric caveat）
+
+对 ideation 的要求（非常重要）：
+
+- 在提出新 idea 前，先回看相关的 idea cards
+- 在扩大检索前，先回看实验结果与失败模式
+- 不要把历史上某行内容当作当前 active idea，除非它被明确再次选中
+
+当输出会改变/汇报 quest 状态时，用 `artifact`：
+
+- idea 的创建/修订
+- 分支/工作树切换记录
+- 主实验记录
+- analysis campaign 记录
+- 进度/里程碑推送
+- 决策与 approval
+- connector 侧需要看到的交互状态
+
+当需要运行“可持续跟踪、可回放”的命令时，用 `bash_exec`：
+
+- 训练/评测
+- 长时间脚本
+- 需要后续 `read/list/kill` 的命令
+
+## 2. Memory 工具语义（建议用法）
+
+### `memory.list_recent(...)`
+
+用途：
+
+- 快速恢复本地上下文
+- pause/restart 后重建状态
+
+建议在：
+
+- turn 开始
+- 恢复 stopped quest 后
+- 在决定“要读哪几张卡”之前
+
+示例：
+
+```text
+memory.list_recent(scope="quest", limit=5, kind="knowledge")
+```
+
+### `memory.search(...)`
+
+用途：
+
+- 在重复劳动之前做定向检索
+
+建议在：
+
+- 做大范围文献检索之前
+- 反复失败前先查是否已有排错记录
+- 选择/修订 idea 之前
+- 问用户前先查是否已经有稳定答案
+
+常见 kind：
+
+- `papers`：论文与引用
+- `decisions`：路线选择理由
+- `episodes`：故障与排错
+- `knowledge`：稳定规则
+
+示例：
+
+```text
+memory.search(query="official validation split", scope="both", kind="papers", limit=6)
+memory.search(query="metric wiring mismatch", scope="quest", kind="episodes", limit=5)
+memory.search(query="baseline novelty constraints", scope="both", kind="ideas", limit=6)
+```
+
+### `memory.read(...)`
+
+用途：
+
+- 读一张“确定相关”的卡
+
+建议：
+
+- 先 `search/list_recent` 找到少量候选，再 `read` 其中 1~3 张
+- 不要一口气读几十张
+
+示例：
+
+```text
+memory.read(path="~/DeepScientist/quests/q-xxxx/memory/knowledge/metric-contract.md")
+```
+
+### `memory.write(...)`
+
+用途：
+
+- 写入可复用的持久化发现
+
+适合写在：
+
+- 有价值的论文阅读总结之后
+- 非平凡的 debug episode 之后
+- 稳定的评测规则确认之后
+- 选中/否决某个 idea（有理由与证据）之后
+
+不适合写在：
+
+- 泛泛的聊天总结
+- 临时的进度 ping（那应该用 artifact）
+- 已经在 artifact 中更好记录的信息
+
+Memory 卡片格式：**Markdown + 顶部 YAML**。建议包含：
+
+1. context
+2. action/observation
+3. outcome
+4. interpretation
+5. boundaries
+6. evidence paths
+7. retrieval hints
+
+示例：
+
+```md
+---
+id: knowledge-1234abcd
+type: knowledge
+title: 指标对比只有在官方验证划分下才成立
+quest_id: q-xxxx
+scope: quest
+tags:
+  - stage:baseline
+  - topic:metric-contract
+stage: baseline
+confidence: high
+evidence_paths:
+  - artifacts/baselines/verification_report.md
+retrieval_hints:
+  - baseline comparison
+  - metric contract
+updated_at: 2026-03-11T18:00:00+00:00
+---
+
+背景：在官方 benchmark 设置下验证 baseline。
+
+观察：只有使用官方 validation split 时数值才一致。
+
+解释：若使用自定义 split，与该 baseline 的对比将不成立。
+
+边界：该规则是 benchmark-specific 的；除非在多个 quest 中复现，否则不建议提升为 global。
+```
+
+### `memory.promote_to_global(...)`
+
+用途：
+
+- 将已证明可复用的 quest-local 经验提升到 global memory
+
+仅在以下情况下使用：
+
+- 不是项目噪声
+- 已足够稳定
+- 其他 quest 很可能受益
+
+## 3. Artifact vs Memory 的边界
+
+两者都写的前提是“职责不同”：
+
+- 实验完成：
+  - `artifact.record_*` 记录官方实验与证据
+  - `memory.write`（可选）只记录可复用规则/教训
+
+不要用 memory 代替实验 artifact。
+不要用 artifact 代替可复用知识卡。
+
+## 4. Bash exec 的基本用法
+
+用于可监控命令：
+
+```text
+bash_exec.bash_exec(command="python train.py --config configs/main.yaml", mode="detach", workdir="<quest workspace>")
+```
+
+随后检查：
+
+```text
+bash_exec.bash_exec(mode="list", status="running")
+bash_exec.bash_exec(mode="read", id="<bash_id>")
+```
+
+只有在确实需要停止时才使用 `kill`。
+
+## 5. Prompt 级纪律（建议）
+
+通常推荐遵循：
+
+1. turn 开始/恢复时先 `memory.list_recent(...)`
+2. 重复劳动前 `memory.search(...)`
+3. 只 `memory.read(...)` 少量关键卡片
+4. quest 状态变化用 `artifact`
+5. 长任务 shell 用 `bash_exec`
+6. 有真正的可复用发现才 `memory.write(...)`
+
+## 6. UI 期望
+
+在 `/projects/{id}` 的 Studio trace 中：
+
+- `memory.*` 应渲染为结构化卡片，而不是 raw JSON
+- 卡片应显示：
+  - 操作类型
+  - scope / kind
+  - title 或 query
+  - 命中条目或写入摘要
+
+如果 agent 完全不调用 memory：优先看 prompt/skill 行为是否偏离。
+如果 agent 调用 memory 但 UI 只显示 raw logs：优先修 UI 的渲染层。

package/docs/zh/08_FIGURE_STYLE_GUIDE.md

@@ -0,0 +1,97 @@
+# 08 图表风格指南：实验图与论文图规范
+
+本文档定义 DeepScientist 默认的实验图、分析图和论文图风格规范。
+
+## 核心原则
+
+优先使用克制、证据优先的图。
+
+- 面向 connector 的里程碑图，目标是快速传达结论
+- 面向论文的图，目标是干净、稳定、适合 PDF 导出与审稿阅读
+- 两者都统一使用 prompt / stage skills 中固定的莫兰迪色系
+
+## 固定莫兰迪配色
+
+- `mist-stone`: `#F3EEE8`, `#D8D1C7`, `#8A9199`
+- `sage-clay`: `#E7E1D6`, `#B7A99A`, `#7F8F84`
+- `dust-rose`: `#F2E9E6`, `#D8C3BC`, `#B88C8C`
+- `fog-blue`: `#DCE5E8`, `#A9BCC4`, `#6F8894`
+- `olive-paper`: `#E6E1D3`, `#B8B095`, `#7C7A5C`
+- `lavender-ash`: `#E8E3EA`, `#B9AFC2`, `#7D7486`
+
+推荐搭配：
+
+- 主方法 vs baseline：`sage-clay` + `mist-stone`
+- 多个 ablation：`mist-stone` + `fog-blue` + `dust-rose`
+- uncertainty / sensitivity：`mist-stone` + `olive-paper`
+- appendix / supplementary：`mist-stone` + `lavender-ash`
+
+## 图表类型选择
+
+图表类型应由研究问题决定：
+
+- 折线图：epoch、step、budget、scale 或有序条件上的趋势
+- 柱状图：少量类别的并列比较，且共享零基线
+- 点图 / point-range：更强调精确值和置信区间时
+- 箱线图 / 小提琴图 / 直方图：真正的分布问题
+- 热力图：只有当矩阵结构本身就是结果时才使用
+
+不要为了“看起来丰富”而做成拥挤的 dashboard。
+
+## 颜色语义
+
+- 有序幅值 -> 使用顺序型、低饱和配色
+- 围绕 0 或某个参考值的正负偏移 -> 使用带中性中心的发散型低饱和配色
+- 类别比较 -> 使用离散配色，不要拿连续色带冒充类别
+
+避免使用 rainbow / jet / HSV 这类会扭曲排序感知的配色。
+
+## 导出规则
+
+- connector 里程碑图：通常导出 `png`
+- 论文图：导出 `pdf` 或 `svg`，同时保留一份 `png` 预览
+- 如果可以导出矢量格式，就不要把线稿和文字栅格化
+- 背景保持白色或近白色
+- 网格线保持轻量
+- 图例尽量简洁，能直标就直标
+- 确保缩放到论文版面后文字仍然可读
+- 默认优先接近常见论文版式：
+  - 单栏宽度约 `89 mm`
+  - 双栏宽度约 `183 mm`
+
+## 强制复检流程
+
+不要在第一次渲染后就把重要图片标记为完成。
+
+对于里程碑图、论文图、附录图，默认流程应当是：
+
+1. 先生成第一版
+2. 打开导出的实际图片进行查看
+3. 如果发现留白、标签、图例、颜色层级或可读性问题，就立即修图
+4. 再导出最终版本
+
+最低完成条件应当是“已经实际看过图，并做过必要修正”，而不是“代码看起来没问题”。
+
+## 最小检查清单
+
+把图当作完成之前，至少确认：
+
+- 可视编码与研究问题一致
+- 标签、单位、基线明确
+- 同一组图里的颜色语义一致
+- 源数据路径明确
+- 生成脚本路径明确
+- 图可以从 durable 文件重新生成
+- 缩小到真实论文版面后仍然可读
+- 用户快速扫一眼就能看出主结论
+- 图例不会挡住数据
+
+## 参考依据
+
+本规范主要参考以下公开资料进行约束抽象：
+
+- PLOS Computational Biology《Ten Simple Rules for Better Figures》：`https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003833`
+- Graphics Principles：`https://graphicsprinciples.github.io/`
+- Nature 作者格式说明：`https://www.nature.com/nature/for-authors/formatting-guide`
+- Matplotlib colormap 指南：`https://matplotlib.org/stable/users/explain/colors/colormaps.html`
+- Datawrapper 可访问性图表规范：`https://academy.datawrapper.de/article/206-how-we-make-sure-our-charts-maps-and-tables-are-accessible`