diff --git a/cross-client-setup-and-runbook.md b/cross-client-setup-and-runbook.md new file mode 100644 index 0000000..fae54bf --- /dev/null +++ b/cross-client-setup-and-runbook.md @@ -0,0 +1,516 @@ +# Cross-Client Setup and Runbook + +This document records how to reproduce the current scholarly-writing workflow on: + +- Codex +- Claude Code +- other MCP-compatible clients such as OpenClaw + +The goal is to make the same review-writing workflow reusable across clients, with the smallest possible amount of client-specific logic. + +--- + +## 1. Scope + +This workflow is designed for: + +- Chinese review writing +- Zotero-backed literature management +- PDF parsing with Docling +- local hybrid retrieval with QMD +- Word `.docx` editing with `word-mcp` +- browser-assisted manual downloading with `chrome-devtools` +- multi-agent task decomposition when the client supports it + +Current repository: + +- `scholarly-writing-workbench` + +Current workbench directory: + +- `D:\phd\presentation\汇总-文献汇报PPT` + +Core workflow documents: + +- `README.md` +- `multi-agent-review-workflow-template.md` +- `codex-multi-agent-setup-notes.md` +- `review-outline.md` +- `pending-calibration-tasks.md` + +--- + +## 2. Important compatibility rule + +Not every client supports the same feature set. + +### 2.1 What is Codex-specific + +The following part is currently Codex-specific: + +- `Deep-Research-skills` skill installation and direct skill invocation +- Codex `agents/*.toml` role definitions +- Codex-native multi-agent configuration in `~/.codex/config.toml` + +### 2.2 What is reusable across Codex, Claude Code, and OpenClaw + +The following parts are generally reusable across MCP-compatible clients: + +- `word-mcp` +- `zotero` +- `docling` +- `qmd` +- `chrome-devtools` +- the review workflow template +- the outline file +- the paper-to-GitHub mapping table +- the citation-evidence workflow + +### 2.3 Practical consequence + +If you want the same task to work in Claude Code or OpenClaw: + +- reuse the MCP servers +- reuse the markdown workflow documents +- reuse the repository layout +- do not assume those clients understand Codex skills directly + +Instead, treat the workflow template as the portable “instruction layer”. + +--- + +## 3. Files and directories to keep stable + +To maximize portability, keep these filenames stable: + +- `README.md` +- `multi-agent-review-workflow-template.md` +- `codex-multi-agent-setup-notes.md` +- `review-outline.md` +- `pending-calibration-tasks.md` +- `macrolide-review-draft.docx` + +Recommended stable analysis artifacts: + +- `paper_github_repo_map.csv` +- `citation-evidence/` + +Recommended stable RAG layout: + +```text +zotero-rag/ + pdf/ + parsed-md/ + parsed-json/ + github-sources/ + github-md/ + qmd-workspace/ + scripts/ +``` + +--- + +## 4. Required local software + +Install these first: + +- Git +- Python 3.10+ +- Node.js 22+ +- `uv` +- `pixi` +- Zotero +- Microsoft Word +- Codex CLI if using Codex +- Claude Code if using Claude Code +- OpenClaw or another MCP-capable client if using that route + +Recommended checks: + +```powershell +git --version +python --version +node --version +uv --version +pixi --version +``` + +--- + +## 5. Required MCP servers + +These MCP servers form the portable core of the workflow. + +### 5.1 `word-mcp` + +Purpose: + +- edit `.docx` +- back up files before edits +- support paragraph-level Word revision workflows + +Recommended installation: + +```powershell +git clone C:\Users\\Documents\project\word-mcp +``` + +Codex example: + +```powershell +codex mcp add word-mcp -- pixi run --manifest-path C:/Users//Documents/project/word-mcp start +``` + +Claude Code example: + +Use the equivalent `claude mcp add ...` command or add the same command/args pair to Claude Code MCP settings. + +OpenClaw: + +Use the same underlying command if OpenClaw supports stdio MCP servers. + +### 5.2 `zotero` + +Purpose: + +- manage Zotero items +- add papers by DOI +- import PDFs +- inspect metadata +- support citation workflows + +Required environment variables: + +- `ZOTERO_API_KEY` +- `ZOTERO_USER_ID` +- `UNPAYWALL_EMAIL` + +Recommended installation: + +```powershell +git clone C:\Users\\Documents\project\mcp-zotero +``` + +Codex example: + +```powershell +codex mcp add zotero ` + --env ZOTERO_API_KEY=YOUR_KEY ` + --env ZOTERO_USER_ID=YOUR_USER_ID ` + --env UNPAYWALL_EMAIL=YOUR_EMAIL ` + -- pixi run --manifest-path C:/Users//Documents/project/mcp-zotero start +``` + +Claude Code / OpenClaw: + +Reuse the same server command and environment variables through the client's MCP config. + +### 5.3 `docling` + +Purpose: + +- parse PDFs into structured markdown and JSON + +Recommended installation: + +```powershell +git clone https://github.com/docling-project/docling-mcp.git C:\Users\\Documents\project\docling-mcp +cd C:\Users\\Documents\project\docling-mcp +uv sync +``` + +Codex example: + +```powershell +codex mcp add docling -- uv run --directory C:/Users//Documents/project/docling-mcp docling-mcp-server --transport stdio +``` + +Claude Code / OpenClaw: + +Reuse the same stdio command. + +### 5.4 `qmd` + +Purpose: + +- local hybrid retrieval across parsed papers, GitHub docs, and notes + +Requirements: + +- Node.js >= 22 + +Recommended installation: + +```powershell +git clone https://github.com/tobi/qmd C:\Users\\Documents\project\qmd +cd C:\Users\\Documents\project\qmd +npm install +npm run build +``` + +Codex example: + +```powershell +codex mcp add qmd -- node C:/Users//Documents/project/qmd/dist/qmd.js mcp +``` + +Claude Code / OpenClaw: + +Reuse the same MCP entry if the client supports stdio MCP. + +### 5.5 `chrome-devtools` + +Purpose: + +- open paper pages +- open GitHub pages +- support manual downloads + +Codex example: + +```powershell +codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest +``` + +Windows often needs: + +- `SystemRoot` +- `PROGRAMFILES` +- `startup_timeout_ms` + +For Claude Code / OpenClaw: + +Use the same underlying command, but match the MCP config format required by the client. + +--- + +## 6. Codex-specific setup + +### 6.1 Install Deep-Research-skills + +Codex currently supports local skills under: + +- Windows: + - `C:\Users\\.codex\skills` +- macOS: + - `/Users//.codex/skills` +- Linux: + - `/home//.codex/skills` + +Install at least: + +- `research` +- `research-add-fields` +- `research-add-items` +- `research-deep` +- `research-report` + +### 6.2 Enable Codex multi-agent + +Edit: + +- `~/.codex/config.toml` + +Minimum: + +```toml +[features] +multi_agent = true +``` + +Recommended: + +```toml +[agents] +max_threads = 6 +max_depth = 1 +``` + +### 6.3 Add review-specific agent roles + +Recommended roles: + +- `deep_researcher` +- `zotero_locator` +- `qmd_retriever` +- `github_mapper` +- `writer` +- `citation_checker` +- `citation_archivist` +- `web_researcher` + +See: + +- `codex-multi-agent-setup-notes.md` + +--- + +## 7. Claude Code setup + +Claude Code does not rely on Codex skills. To reproduce the same workflow: + +1. configure the same MCP servers +2. reuse the same repository and markdown instructions +3. treat `multi-agent-review-workflow-template.md` as the primary portable workflow spec + +Recommended sequence: + +1. add `word-mcp` +2. add `zotero` +3. add `docling` +4. add `qmd` +5. add `chrome-devtools` +6. open the repository +7. explicitly tell Claude Code to follow: + - `README.md` + - `multi-agent-review-workflow-template.md` + - `review-outline.md` + - `pending-calibration-tasks.md` + +Important limitation: + +- Codex skills are not automatically portable to Claude Code as “skills” +- the equivalent behavior should be driven by the workflow template and MCP tools + +--- + +## 8. OpenClaw setup + +The same general rule applies to OpenClaw: + +- if OpenClaw supports MCP stdio servers, reuse the same MCP commands +- if OpenClaw supports multi-agent behavior, map the same role structure conceptually +- if OpenClaw does not support Codex-style skills, use the markdown workflow template as the instruction layer + +Minimum expectation for OpenClaw: + +1. it can call MCP servers +2. it can read local markdown files +3. it can follow a structured review workflow from prompt + docs + +If those three conditions hold, the workflow can be reproduced at the process level even without Codex-native skills. + +--- + +## 9. Recommended repository bootstrapping on a new machine + +Clone the repository: + +```powershell +git clone ssh://git@gitea.jmsu.top:2222/lingyuzeng/scholarly-writing-workbench.git +cd scholarly-writing-workbench +``` + +Then verify: + +- `README.md` +- `multi-agent-review-workflow-template.md` +- `review-outline.md` +- `macrolide-review-draft.docx` + +--- + +## 10. Recommended startup procedure for any client + +Before starting a real task: + +1. open the repository root +2. read: + - `README.md` + - `multi-agent-review-workflow-template.md` + - `review-outline.md` + - `pending-calibration-tasks.md` +3. confirm that the MCP servers are available +4. confirm whether QMD has already indexed the parsed corpus +5. confirm whether Zotero has the needed papers and PDFs + +Do not start with Word editing. + +Start with: + +- literature gap discovery +- evidence retrieval +- citation planning + +Only then move to: + +- Word revision +- citation evidence files +- manual Zotero citation insertion + +--- + +## 11. Recommended review task sequence + +Standard order: + +1. identify the chapter and subsection from `review-outline.md` +2. check Zotero and local files +3. if missing, open pages and download manually +4. parse PDFs with Docling +5. index and query with QMD +6. align paper and GitHub traces +7. revise the Word draft +8. archive citation evidence +9. insert citations manually in Word + +--- + +## 12. First test plan on a new client + +Run a small pilot before trusting the full workflow. + +Recommended pilot: + +### Round 0 + +- confirm MCP availability +- confirm agent role plan +- do not edit Word + +### Round 1 + +- choose one subsection +- collect evidence only +- do not edit Word + +### Round 2 + +- edit one or two paragraphs only +- back up before editing + +### Round 3 + +- create citation evidence files +- do not insert citations automatically yet + +### Round 4 + +- test paper-to-GitHub reasoning for a tool-oriented section + +--- + +## 13. Current known limitations + +The following items still require iterative calibration: + +- QMD thresholds and candidate counts +- Docling JSON field whitelist for citation evidence +- depth of GitHub evidence inspection +- whether Zotero auto-insertion should ever be tested on Word copies +- whether Word recovery should be fully scripted + +These are tracked in: + +- `pending-calibration-tasks.md` + +--- + +## 14. Key portability principle + +To make this workflow usable across Codex, Claude Code, and OpenClaw: + +- keep filenames in English +- keep workflow instructions in stable markdown files +- keep MCP servers client-agnostic where possible +- treat Codex skills as optional acceleration for Codex, not as the only source of workflow logic