D-sudoasd · Oct 22, 2026 · Oct 22, 2026
diff --git a/.agents/skills/diffractscout-agent-pipeline/SKILL.md b/.agents/skills/diffractscout-agent-pipeline/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: diffractscout-agent-pipeline
+description: Execute DiffractScout scientific jobs through its durable CLI, Python or local MCP interface, including planning, candidate discovery, CIF preparation, theoretical diffraction, recovery and verified exports. Use for research execution requests, not general repository coding or experimental-pattern fitting.
+---
+
+# DiffractScout scientific jobs
+
+Use the shared workflow service to turn the user's scientific request into a
+recorded calculation with verified exports. Read the repository's
+[agent pipeline guide](../../../docs/AGENT_PIPELINE.md) for execution and
+recovery, and [scientific contracts](../../../docs/SCIENTIFIC_CONTRACTS.md)
+when interpreting numerical fields. Concrete requests are in
+[examples/agent](../../../examples/agent/README.md).
+
+Obtain `diffractscout agent context` and `diffractscout agent schema request`
+(or their MCP/Python equivalents) for current capabilities and fields. Choose
+the existing workflow for the requested outcome; use `prepare_analyze` when
+starting CIF preparation and subsequent theoretical analysis are both requested.
+Do not build another numerical implementation or add a language model to the
+calculation path.
+
+Preserve the requested composition, local source identity, radiation and scan
+range. Check available inputs before asking for missing information. Synchrotron
+peak positions require an explicit wavelength or energy; ask for it if unavailable.
+Nominal chemistry and prototype cell parameters are starting assumptions. Cited
+lattice/coordinate edits must come from supplied evidence. Do not infer phase
+fractions, invent elastic constants or claim experimental phase identification.
+
+Normalize relative paths from the request file, select a workspace that remains
+stable across sessions, and omit `output_dir` for a unique service-managed output
+or select a fresh target outside the input tree.
+Plan the request and resolve actionable diagnostics before execution. Keep
+Materials Project credentials in the runtime environment (`MP_API_KEY`) or
+runtime API argument, never in the request or outputs. Respect the user's
+database scope and download authorization; do not widen limits to clear a failure.
+
+Use `submit` for work that may outlive the current tool call. Record the returned
+`run_id` and workspace, poll `status`, and consume new event pages using
+`next_cursor`. A successful submission is not completion. Before resubmitting
+after a lost response, inspect existing jobs. Resume an interrupted or blocked
+job only after addressing its diagnostic; preserve checkpoint and source checks.
+Cancellation is cooperative and retains completed evidence. Batch independent
+requests serially unless finite concurrency is explicitly appropriate.
+
+After a completed or partial run, obtain `result` with integrity verification.
+Request table pages only as needed. Report artifact paths, radiation/range,
+source/prototype assumptions, diagnostics and missing values with the result.
+If verification fails or work remains blocked, identify the affected stage and
+required input; do not present an unverified bundle or partial task as complete.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -97,6 +97,25 @@ jobs:
           path: ci_reference_engines
           if-no-files-found: warn
 
+  mcp-stdio:
+    name: MCP stdio / Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install optional official MCP SDK and test tools
+        run: python -m pip install -e ".[mcp,test]"
+      - name: Exercise JSON CLI and real MCP stdio client
+        run: python -m pytest -q tests/test_agent_cli.py tests/test_mcp_server.py
+
   cross-platform-smoke:
     name: Smoke / ${{ matrix.os }}
     runs-on: ${{ matrix.os }}

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,13 @@ All notable changes are recorded here. The project follows semantic versioning a
 
 ### Added
 
+- Durable scientific jobs shared by the JSON `agent` CLI, Python workflow
+  service, optional local stdio MCP tools and bilingual desktop Tasks page.
+  Supports existing discovery, CIF preparation/adaptation, diffraction,
+  elasticity and exports with planning, progress events, bounded batches,
+  source/checkpoint integrity checks, recovery and cooperative cancellation.
+  Includes offline request examples and a project scientific-workflow skill.
+
 - Contextual help throughout the main desktop, initial CIF preparation,
   results and retained workbenches. Delayed hover, keyboard focus and F1
   explain actions, drop-down choices, units and table headings in plain

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 
 **Turn local CIF structures or a chemical-system query into theoretical diffraction references with verifiable provenance.**
 
-[Install and GUI](#graphical-interface) · [CLI guide](docs/CLI.md) · [Scientific contracts](docs/SCIENTIFIC_CONTRACTS.md) · [中文说明](README.zh-CN.md)
+[Install and GUI](#graphical-interface) · [CLI guide](docs/CLI.md) · [External agents](docs/AGENT_PIPELINE.md) · [Scientific contracts](docs/SCIENTIFIC_CONTRACTS.md) · [中文说明](README.zh-CN.md)
 
 [![CI](https://github.com/D-sudoasd/DiffractScout/actions/workflows/ci.yml/badge.svg)](https://github.com/D-sudoasd/DiffractScout/actions/workflows/ci.yml) [![MIT](https://img.shields.io/badge/License-MIT-455A64)](LICENSE) [![Python 3.10–3.13](https://img.shields.io/badge/Python-3.10--3.13-3776AB)](pyproject.toml)
 
@@ -96,6 +96,30 @@ illustrative and may show English even when a fresh launch starts in Chinese.
 
 On Windows, double-click `启动DiffractScout.bat` after an editable install, or drag CIF files onto `quick_export_diffractscout.bat` for a one-shot lab export. Both repository launchers are source-checkout convenience entry points: they run the checkout source through `scripts/diffractscout_entry.py` and prefer the repository `.venv\Scripts\python.exe`, then the current/active `python`, then `py -3`. The quick-export launcher also uses an installed `diffractscout-quick-export` command when `.venv` is absent. Installed `diffractscout-gui` / `diffractscout gui` / `diffractscout-quick-export` do not require the repository launchers.
 
+## External-agent workflows
+
+The JSON CLI, Python workflow service and optional local stdio MCP adapter share
+durable jobs with the desktop **Tasks / 任务** page. An external agent can plan
+existing discovery, CIF preparation/adaptation, theoretical diffraction,
+elasticity and export workflows, submit long work, inspect progress, resume
+interrupted items and read verified results.
+
+```bash
+diffractscout agent context
+diffractscout agent plan examples/agent/analyze-local.json
+diffractscout agent run examples/agent/analyze-local.json
+diffractscout agent list
+```
+
+These examples work offline after the base installation. For a long job, use
+`submit` and follow its `run_id` with `status`, `events` and `result`. See the
+[agent pipeline guide](docs/AGENT_PIPELINE.md),
+[runnable requests](examples/agent/README.md) and
+[project workflow skill](.agents/skills/diffractscout-agent-pipeline/SKILL.md).
+Install `.[mcp]` only when connecting an MCP client. Database credentials remain
+runtime inputs; the service does not contain an internal LLM or experimental
+pattern-fitting engine.
+
 ## CIF2Peaks parity features
 
 DiffractScout reimplements the CIF2Peaks desktop workflow inside a provenance-first package (Gemmi engine; not bit-identical intensities). Practical parity includes:
@@ -250,6 +274,7 @@ in the [CLI guide](docs/CLI.md).
 |---|---|---|
 | base | `python -m pip install -e .` | Offline local CIF analysis, CLI/API, synthetic demo and verification |
 | `mp` | `python -m pip install -e ".[mp]"` | Materials Project discovery/download and optional provider metadata; requires your own API key |
+| `mcp` | `python -m pip install -e ".[mcp]"` | Optional local stdio MCP tools for the shared durable scientific workflow service |
 | `figures` | `python -m pip install -e ".[figures]"` | Optional matplotlib rendering path and paper-figure tooling |
 | `gui-dnd` | `python -m pip install -e ".[gui-dnd]"` | Optional `tkinterdnd2` file/folder drag-and-drop; button-based GUI use remains available without it |
 | `test` | `python -m pip install -e ".[test]"` | Pytest, coverage, Ruff, YAML support, and development checks |

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -6,7 +6,7 @@
 
 **从本地 CIF 或化学体系检索出发，生成带来源、诊断和校验清单的理论衍射参考。**
 
-[图形界面与安装](#图形界面) · [CLI](docs/CLI.md) · [科研约定](docs/SCIENTIFIC_CONTRACTS.md) · [英文主页](README.md)
+[图形界面与安装](#图形界面) · [CLI](docs/CLI.md) · [外部 agent](docs/AGENT_PIPELINE.md) · [科研约定](docs/SCIENTIFIC_CONTRACTS.md) · [英文主页](README.md)
 
 [![CI](https://github.com/D-sudoasd/DiffractScout/actions/workflows/ci.yml/badge.svg)](https://github.com/D-sudoasd/DiffractScout/actions/workflows/ci.yml) [![MIT](https://img.shields.io/badge/License-MIT-455A64)](LICENSE) [![Python 3.10–3.13](https://img.shields.io/badge/Python-3.10--3.13-3776AB)](pyproject.toml)
 
@@ -51,6 +51,27 @@ macOS 桌面不作为支持目标。命令行输出统一为 UTF-8，重定向
 
 [查看完整示意图 / View full-size schematic](assets/readme/principle.png)
 
+## 外部 agent 科研工作流
+
+JSON CLI、Python 工作流服务和可选的本地 stdio MCP 共用持久任务记录，
+桌面“任务”页可查看同一工作区。外部 agent 提供科研参数后，可规划已有的候选
+检索、CIF 准备与显式修改、理论衍射、弹性和导出流程，再提交长任务、查看进度、
+恢复中断项目并读取经过完整性校验的结果。
+
+```bash
+diffractscout agent context
+diffractscout agent plan examples/agent/analyze-local.json
+diffractscout agent run examples/agent/analyze-local.json
+diffractscout agent list
+```
+
+基础安装即可离线运行以上示例。长任务使用 `submit`，保留返回的 `run_id`，再用
+`status`、`events` 和 `result` 查看状态与结果。参见
+[完整说明](docs/AGENT_PIPELINE.md)、[可运行请求](examples/agent/README.md) 和
+[项目工作流技能](.agents/skills/diffractscout-agent-pipeline/SKILL.md)。需要连接 MCP
+客户端时安装 `.[mcp]`；数据库密钥只在运行时提供。此入口不包含内部大模型或实验
+谱线拟合；理论计算和原型起始模型的科研边界沿用现有约定。
+
 ## 主要工作流
 
 使用与开发入口：[文档索引](docs/README.md) · [贡献指南](CONTRIBUTING.md) ·
@@ -192,6 +213,7 @@ Remove-Item Env:MP_API_KEY
 |---|---|---|
 | base | `python -m pip install -e .` | 离线本地 CIF、CLI/API、合成演示和校验 |
 | `mp` | `python -m pip install -e ".[mp]"` | Materials Project 检索/下载和可选 provider 元数据；需要自己的 API 密钥 |
+| `mcp` | `python -m pip install -e ".[mcp]"` | 通过本地 stdio MCP 连接共用的持久科研任务服务 |
 | `figures` | `python -m pip install -e ".[figures]"` | 可选 matplotlib 渲染路径和论文制图工具 |
 | `gui-dnd` | `python -m pip install -e ".[gui-dnd]"` | 可选 `tkinterdnd2` 文件/文件夹拖放；没有它仍可使用按钮式 GUI |
 | `test` | `python -m pip install -e ".[test]"` | pytest、覆盖率、Ruff、YAML 支持和开发检查 |