lingyuzeng/scholarly-writing-workbench
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
scholarly-writing-workbench/cross-client-setup-and-runbook.md
mm644706215 8189bdb493 Add cross-client setup and runbook
2026-03-10 17:31:24 +08:00

517 lines
10 KiB
Markdown
Raw Permalink Blame History

# 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 <YOUR_WORD_MCP_REPO> C:\Users\<user>\Documents\project\word-mcp
```
Codex example:
```powershell
codex mcp add word-mcp -- pixi run --manifest-path C:/Users/<user>/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 <YOUR_ZOTERO_MCP_REPO> C:\Users\<user>\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/<user>/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\<user>\Documents\project\docling-mcp
cd C:\Users\<user>\Documents\project\docling-mcp
uv sync
```
Codex example:
```powershell
codex mcp add docling -- uv run --directory C:/Users/<user>/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\<user>\Documents\project\qmd
cd C:\Users\<user>\Documents\project\qmd
npm install
npm run build
```
Codex example:
```powershell
codex mcp add qmd -- node C:/Users/<user>/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\<user>\.codex\skills`
- macOS:
- `/Users/<user>/.codex/skills`
- Linux:
- `/home/<user>/.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
Reference in New Issue View Git Blame Copy Permalink