Feature/pi research orchestrator

CHANGELOG.md

@@ -6,10 +6,120 @@ All notable changes to this project are documented in this file. The format is b
 
 ## [Unreleased]
 
+## [0.4.6] - 2026-09-06
+
+### Fixed
+
+- Online-only research now performs one bounded, cross-provider broadening round when the first set of
+  source-specific queries yields no admissible evidence.
+- Broadening removes overly restrictive model and workflow terms while retaining the scientific objects,
+  then fans the query out to Crossref, OpenAlex, arXiv, and PubMed.
+- Each discovery provider has an independent timeout so an unavailable source returns a diagnostic status
+  before the complete research tool call times out.
+- A genuinely empty online run now returns the attempted queries, source failures, and actionable next
+  steps instead of a one-sentence empty response.
+
+## [0.4.5] - 2026-09-06
+
+### Fixed
+
+- Model-selected search actions now remove byte-equivalent duplicate calls before execution, avoiding
+  duplicate retrieval work and tool-budget consumption.
+- Runtime query diagnostics preserve one specification per remaining tool call, including the same query
+  intentionally sent to distinct online sources.
+- Search result cardinality mismatches are recorded as diagnostic events and the matched subset continues
+  instead of terminating the complete research run with a raw `zip()` exception.
+
+## [0.4.4] - 2026-09-06
+
+### Fixed
+
+- Markdown-aware claim extraction now preserves heading, list, table, recommendation, hypothesis, and
+  evidence-gap semantics instead of flattening an entire report into malformed factual sentences.
+- Drafts with some valid citations but uncited factual claims receive citation binding before Reviewer.
+- Final review removes unsupported claim-sized content while preserving Markdown structure and no longer
+  leaves dangling headings or list fragments.
+- A report completeness gate rebuilds excessively shortened output as a structured, cited evidence report
+  with a literature table, coverage gaps, focused searches, proposed next steps, and explicit limitations.
+- Repetitive final-review errors are summarized instead of attaching dozens of near-duplicate limitations.
+- Research trace text, section headings, metrics, line spacing, and long-list scrolling are enlarged for
+  legible use on Windows high-density displays.
+
+## [0.4.3] - 2026-09-05
+
+### Fixed
+
+- Common model citation variants such as `【W5】`, `(W5)`, and lowercase evidence IDs are normalized to the
+  canonical inline form before validation.
+- A draft that declares valid evidence but omits inline markers receives one citation-only repair turn using
+  the existing screened evidence; unknown evidence IDs remain a hard integrity error.
+- If citation repair is unavailable or still invalid, the run now returns a cited screened-evidence catalog
+  with an explicit limitation instead of failing after successful retrieval.
+- The desktop research trace reports citation repair and degraded-output states.
+
+## [0.4.2] - 2026-09-05
+
+### Fixed
+
+- Research tool batches are truncated to the remaining call budget instead of failing the entire run.
+- Exhausted retrieval budgets now stop further local or online search and continue to a bounded synthesis
+  from already screened evidence, with a visible limitation and research-trace event.
+- Full-text expansion reads one highest-ranked document per query, scouts preserve capacity for the main
+  loop, and deterministic single-choice actions no longer consume model steps needed for synthesis/review.
+- Concurrent tool batches reserve their hard-budget capacity atomically.
+
+## [0.4.1] - 2026-09-05
+
+### Fixed
+
+- Broad but actionable research questions no longer stop because optional application scope, report length,
+  or granularity was left unspecified; these preferences are recorded as explicit assumptions instead.
+- Truly underspecified questions now expose a dedicated same-run clarification control, and a timed-out
+  clarification produces a visible Chinese request instead of an English failed-run error.
+- Clarification waits have their own bounded budget and remain subject to the overall research-run timeout.
+
+## [0.4.0] - 2026-09-04
+
 ### Added
 
+- A schema-validated `AgentAction` controller that selects bounded local and online tool calls before
+  synthesis, review, and completion.
+- Persisted phase checkpoints containing the research plan, evidence ledger, coverage matrix, tool-result
+  context, counters, draft, and review state for exact run recovery.
+- Tool-using subagent loops whose observations are fed back into the next model turn.
+- Structured research intent, bilingual source-specific queries, claim-level review, comparison matrices,
+  follow-up queues, session branching, steering, cancellation, and context compaction.
 - Open-source repository metadata, community files, CI, security policy, and contributor documentation.
 
+### Changed
+
+- Resumed runs skip completed intake, planning, and retrieval work when a safe evidence checkpoint exists.
+- Desktop browser checks now cover current research-run APIs, settings scrolling, mobile overflow, library
+  state controls, and Markdown/citation rendering against deterministic API fixtures.
+
+## [0.3.1] - 2026-09-02
+
+### Added
+
+- A same-topic evidence admission gate that labels retrieved candidates as relevant, adjacent, or irrelevant
+  before coverage assessment, synthesis, and DOI acquisition.
+- A visible research trace for subquestions, search queries, evidence exclusions, scout activity, and reviewer
+  findings.
+- A validated read-only research tool registry with call budgets, lifecycle events, parallel execution, and
+  normalized tool failures.
+- Conservative abstention and cross-topic regression coverage for cases such as multibeam sonar results being
+  retrieved for spherical harmonic analysis.
+
+### Changed
+
+- DeepSeek structured roles now receive the exact Pydantic JSON Schema instead of relying on generic JSON mode.
+- Planner fallback decomposes broad requests into focused queries, and assessor fallback no longer assigns the
+  first three retrieval results as evidence.
+- Reviewer checks receive evidence excerpts and explicitly block cross-domain citations; parallel scouts are
+  enabled by default with reserved model budget for synthesis and review.
+- Planner output now defines an explicit bilingual topic contract. Deterministic admission and final-answer
+  guards enforce that contract even when the relevance model or synthesizer makes a cross-topic error.
+
 ## [0.3.0] - 2026-09-02
 
 ### Added

CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use this software in research, please cite the software release."
 title: "ResearchBrain"
 type: software
-version: 0.1.8
-date-released: 2026-08-17
+version: 0.4.6
+date-released: 2026-09-06
 license: AGPL-3.0-only
 authors:
   - name: "ResearchBrain contributors"

README.en.md

@@ -19,7 +19,7 @@ Metadata, PDFs, parsed artifacts, vector indexes, and conversations remain on th
 Only the requests needed for enabled online discovery or configured MiniMax and DeepSeek calls leave the
 device. The Windows 11 application runs without WSL, gbrain, Docker, or PostgreSQL.
 
-> Status: `0.3.0 alpha`. The core research loop works, but this is not a full Zotero replacement.
+> Status: `0.4.6 alpha`. The core research loop works, but this is not a full Zotero replacement.
 
 ![ResearchBrain desktop library](docs/images/researchbrain-library.png)
 
@@ -91,15 +91,17 @@ The default data directory is `%LOCALAPPDATA%\ResearchBrain`.
 
 Evidence Chat uses persisted research runs by default: `planning → local_search → gap_assessment →
 online_search → synthesis → verification`. Complex questions can use up to three local retrieval rounds and
-one revision. Optional read-only scouts split subquestions in parallel and remain disabled by default until
-their quality and cost benefit is measured.
+one revision. Read-only scouts split subquestions in parallel and are enabled by default with a configuration
+switch for controlled comparisons. Read-only search tools run through a validated registry with a
+call budget, lifecycle events, parallel execution, and normalized errors. A topic contract blocks cross-domain
+material at evidence admission, citation review, and final-answer output.
 
 ```powershell
 $env:RESEARCHBRAIN_RESEARCH_LOOP_V2 = "1"  # enabled by default
-$env:RESEARCHBRAIN_PARALLEL_SCOUTS = "1"   # optional experiment
+$env:RESEARCHBRAIN_PARALLEL_SCOUTS = "1"   # enabled by default; use 0 to disable
 ```
 
-The repository includes a fixed 24-case regression set. Start the local API, then run:
+The repository includes a fixed 25-case regression set. Start the local API, then run:
 
 ```powershell
 $env:PYTHONPATH = "src"
@@ -112,6 +114,7 @@ python .\scripts\evaluate_research_answers.py `
 The report records citation-ID validity, subquestion coverage, visible empty results, latency, model steps,
 and tool calls. It uses real provider requests and is therefore not part of normal CI. See the
 [research orchestrator plan](docs/research-orchestrator-plan.md) for architecture and implementation status.
+See [Pi pattern adoption](docs/pi-patterns.md) for the explicit adopted, adapted, and excluded scope.
 
 ## Codex Skills
 

README.md

@@ -21,7 +21,7 @@ CSL-JSON、BibTeX、RIS、DOI 清单或 Markdown，也可通过 MCP 交给 Codex
 MiniMax、DeepSeek 时才会发送相应请求。应用可在 Windows 11 上独立运行，不依赖 WSL、gbrain、
 Docker 或 PostgreSQL。
 
-> 当前为 `0.3.0 alpha`。核心研究闭环可运行，但还不是 Zotero 的完整替代品。
+> 当前为 `0.4.6 alpha`。核心研究闭环可运行，但还不是 Zotero 的完整替代品。
 
 ![ResearchBrain 桌面界面](docs/images/researchbrain-library.png)
 
@@ -118,15 +118,16 @@ npm run dev
 ## 多轮研究编排
 
 “证据对话”默认使用持久化研究运行：`planning → local_search → gap_assessment → online_search →
-synthesis → verification`。复杂问题可以进行最多三轮本地补检索和一次修订；可选只读 scout 会并行
-处理不同子问题，但默认关闭，便于先比较成本与质量。
+synthesis → verification`。复杂问题可以进行最多三轮本地补检索和一次修订；只读 scout 默认并行
+处理不同子问题。检索工具通过受控注册表执行，具备参数校验、调用预算、生命周期事件和统一错误回传；
+主题契约会在证据进入、引用审查和最终成文三个位置阻断跨领域材料。
 
 ```powershell
 $env:RESEARCHBRAIN_RESEARCH_LOOP_V2 = "1"  # 默认启用
-$env:RESEARCHBRAIN_PARALLEL_SCOUTS = "1"   # 可选实验能力
+$env:RESEARCHBRAIN_PARALLEL_SCOUTS = "1"   # 默认启用；设为 0 可关闭
 ```
 
-运行固定的 24 项质量集时，先启动本地 API，再传入普通文库和可选空文库 ID：
+运行固定的 25 项质量集时，先启动本地 API，再传入普通文库和可选空文库 ID：
 
 ```powershell
 $env:PYTHONPATH = "src"
@@ -139,6 +140,9 @@ python .\scripts\evaluate_research_answers.py `
 评测记录引用 ID 有效率、子问题覆盖率、可见空结果、耗时、模型步骤和工具调用。真实模型评测会
 产生 API 请求和费用，不会在普通 CI 中自动运行。完整设计与实施状态见
 [多轮研究编排器方案](docs/research-orchestrator-plan.md)。
+与 Pi Agent Harness 的逐项对应关系见 [Pi 模式采用说明](docs/pi-patterns.md)。
+后续增强项的真实完成状态和验收条件，以
+[研究 Agent 实施清单](docs/research-agent-implementation-checklist.md)为准。
 
 ## 首次配置
 

desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "researchbrain-desktop",
   "private": true,
-  "version": "0.3.0",
+  "version": "0.4.6",
   "license": "AGPL-3.0-only",
   "description": "Local-first literature library and evidence-grounded research desktop app",
   "type": "module",

desktop/scripts/chat_render_check.cjs

@@ -108,23 +108,72 @@ const assistantMessage = {
         ) {
             const events = [
                 {
-                    type: "phase_started",
+                    type: "plan_ready",
                     run_id: "test-run",
                     sequence: 1,
+                    subquestions: [
+                        {
+                            id: "Q1",
+                            question: "核对球谐分析的数据与方法",
+                            required_level: "fulltext_section",
+                        },
+                    ],
+                    queries: ["spherical harmonic analysis methods"],
+                    topic_terms: ["球谐", "spherical harmonic"],
+                    excluded_terms: ["多波束", "multibeam sonar"],
+                },
+                {
+                    type: "phase_started",
+                    run_id: "test-run",
+                    sequence: 2,
                     phase: "local_search",
                     label: "正在检索本地文库",
                 },
+                {
+                    type: "evidence_screened",
+                    run_id: "test-run",
+                    sequence: 3,
+                    counts: { relevant: 4, adjacent: 1, irrelevant: 1 },
+                    judgments: [
+                        {
+                            evidence_id: "E5",
+                            relevance: "irrelevant",
+                            reason: "多波束声呐与球谐分析不是同一研究主题",
+                        },
+                    ],
+                },
+                {
+                    type: "tool_execution_start",
+                    run_id: "test-run",
+                    sequence: 31,
+                    call_id: "call-1",
+                    tool: "search_library",
+                },
+                {
+                    type: "tool_execution_end",
+                    run_id: "test-run",
+                    sequence: 32,
+                    call_id: "call-1",
+                    tool: "search_library",
+                    status: "completed",
+                },
                 {
                     type: "evidence_updated",
                     run_id: "test-run",
-                    sequence: 2,
+                    sequence: 4,
                     count: 6,
                     levels: { fulltext_page: 4, structured_abstract: 2 },
                 },
+                {
+                    type: "scouts_started",
+                    run_id: "test-run",
+                    sequence: 5,
+                    count: 1,
+                },
                 {
                     type: "coverage_updated",
                     run_id: "test-run",
-                    sequence: 3,
+                    sequence: 6,
                     counts: {
                         covered: 2,
                         partial: 1,
@@ -134,7 +183,7 @@ const assistantMessage = {
                 {
                     type: "approval_available",
                     run_id: "test-run",
-                    sequence: 4,
+                    sequence: 7,
                     approval: {
                         id: "approval-1",
                         action: "import_dois",
@@ -146,13 +195,20 @@ const assistantMessage = {
                 {
                     type: "answer_delta",
                     run_id: "test-run",
-                    sequence: 5,
+                    sequence: 8,
                     delta: assistantMessage.content,
                 },
+                {
+                    type: "review_ready",
+                    run_id: "test-run",
+                    sequence: 9,
+                    blocking: 0,
+                    warnings: 0,
+                },
                 {
                     type: "run_completed",
                     run_id: "test-run",
-                    sequence: 6,
+                    sequence: 10,
                     message_id: "assistant-message",
                 },
             ];
@@ -212,6 +268,30 @@ const assistantMessage = {
     await page.locator(".message.assistant").waitFor();
     await page.getByText("发现 1 篇可导入文献").waitFor();
 
+    const trace = page.locator(".research-trace");
+    await trace.waitFor();
+    if (!(await trace.getAttribute("open"))) {
+        await trace.locator("summary").click();
+    }
+    const traceText = await trace.innerText();
+    for (const expected of [
+        "核对球谐分析的数据与方法",
+        "spherical harmonic analysis methods",
+        "必须相关：球谐 · spherical harmonic",
+        "跨域排除：多波束 · multibeam sonar",
+        "受控工具循环",
+        "search_library",
+        "调用 1",
+        "排除 1",
+        "多波束声呐与球谐分析不是同一研究主题",
+        "证据侦察 1 个子问题",
+        "审查：阻断 0，警告 0",
+    ]) {
+        if (!traceText.includes(expected)) {
+            throw new Error(`Research trace is missing: ${expected}`);
+        }
+    }
+
     const answer = page.locator(".message.assistant");
     if ((await answer.locator("strong").first().textContent()) !== "主要结论") {
         throw new Error("Markdown bold text was not rendered");