AI4SCI Workflow

AI4SCI Workflow 是一个面向科研选题、文献调研、问题定义、实验验证和论文写作的项目级 agent workflow。仓库重点维护本项目的 skills、共享工具、标准产物结构和测试资产。

完整工作流文档见 attachments/docs/workflow.md。

Quick Start

方式一：npm 全局安装（推荐）

npm install -g ai4sci-workflow
ai4sci init --title "Your Research Topic" --slug your_topic --topic "Your Topic"

初始化时选择编码工具（默认 Claude Code）：

ai4sci init --title "Your Topic" --slug your_topic --topic "Your Topic" --tools claude,codex

方式二：从源码运行

python .\.codex\skills\ai4sci-init\scripts\ai4sci_init.py init \
  --title "Your Research Topic" \
  --slug your_research_topic \
  --topic "Your Research Topic"

配置密钥

编辑工作区内的 .ai4sci/secrets.env，填写 API key：

OPENAI_CHAT_BASE_URL=https://...
OPENAI_CHAT_API_KEY=sk-...
OPENAI_CHAT_MODEL=...

启动工作流

3. 从 Step 1 开始方向探索：

• 新想法：使用 ai4sci-brainstorming
• 已有聊天记录或研究笔记：使用 ai4sci-direction-extractor

4. 只有 Step 1 产出研究者确认的 selected_direction.md 和 search_handoff.md 后，才进入 Step 2 文献获取。

CLI 命令

| 命令 | 说明 | | ------ | ------ | | ai4sci init | 初始化研究工作区 | | ai4sci check-env | 检测本地环境和 API key 状态 | | ai4sci setup-guide | 生成本地依赖安装指引 |

Repository Layout

.ai4sci/skills/     SKILL.md 源文件（中性位置，不偏向任何编码工具）
bin/                npm CLI 入口 (ai4sci 命令)
attachments/        Shared docs, schemas, templates, scripts, and eval assets
tools/              共享 Python 工具模块和 CLI
.claude/skills/     Junction → .ai4sci/skills/ (Claude Code 发现技能)
.codex/skills/      Junction → .ai4sci/skills/ (Codex CLI 发现技能)
test/               pytest 和 smoke-test 脄本

Standard Research Workspace

Each research topic should use its own workspace:

<workspace_root>/
├── project_manifest.json
├── .ai4sci/
│   ├── config.json
│   ├── secrets.env         (本地密钥，gitignored)
│   ├── secrets.example.env (可提交的模板)
│   └── skills/             Junction 目标（由 ai4sci init 创建）
├── 01_direction_exploration/
├── 02_literature_review/
├── 03_problem_definition/
├── 04_experiment_and_paper/
└── 05_submission_and_promotion/

Standard path rules are documented in attachments/docs/standard-workspace.md.

Main Skills

| Skill | Step | Purpose | | --- | --- | --- | | ai4sci-init | Init | Create workspace, manifest, local config, key templates, and setup guidance | | ai4sci-direction-explorer | Step 1 | Direction exploration — brainstorm (1a) + direction extraction (1b) | | ai4sci-brainstorming | Step 1a | Guide structured direction exploration and preserve raw conversation logs | | ai4sci-direction-extractor | Step 1b | Extract candidate directions from existing notes or chats | | ai4sci-lit-search | Step 2a | Search and merge literature pools | | ai4sci-lit-filter | Step 2b | Prepare/apply semantic relevance filtering, with optional auto-llm | | ai4sci-lit-download | Step 2c | Download legally accessible PDFs and reconcile manual downloads | | ai4sci-lit-analysis | Step 3 | Convert PDFs, initialize/fill per-paper analysis, build evidence and summary outputs | | ai4sci-zotero-handoff | Step 3c optional | Generate Zotero import metadata and linked PDF/Markdown manifests without copying source files | | ai4sci-lit-synthesis | Step 4a | Build paper matrix, evidence bank, cross analysis, gap map, and candidate questions | | ai4sci-survey-writing | Step 4b | Draft a complete evidence-grounded survey manuscript | | ai4sci-direction-proposal | Step 5 | Propose and evaluate candidate research directions | | ai4sci-deep-analysis | Step 6 | Directed validation planning for selected research direction | | ai4sci-experiment-design | Step 7 | Generate experiment design, baseline, metrics, ablation, and risk plan |

Skill registry: .ai4sci/skills/registry.md

Skill Discovery Architecture

SKILL.md 源文件统一放在 .ai4sci/skills/（中性位置）。各编码工具通过 junction/symlink 发现技能：

.ai4sci/skills/ ←──── SKILL.md 源文件（唯一真相源）
    ↑
    ├── .claude/skills/ → junction → .ai4sci/skills/
    ├── .codex/skills/  → junction → .ai4sci/skills/
    └── .trae/skills/   → junction → .ai4sci/skills/

Core Contracts

• literature_pool.json follows attachments/schemas/literature_pool.schema.json.
• project_manifest.json follows attachments/schemas/project_manifest.template.json.
• Step 3 writes human-readable per_paper_analysis/*.md and structured _state/per_paper_summary.json/jsonl.
• Step 4b survey claims must be traceable to original evidence using % evidence: ... markers and tables/claim_evidence_audit.md.
• Reports and logs go to _logs/; machine state goes to _state/; regenerable exports go to _exports/; raw per-round outputs go to _rounds/.

Testing

Run the tracked pytest suite:

python -m pytest test\scripts -q

Run the npm CLI wrapper tests:

python -m pytest test\test_npm_cli.py -v

Test policy:

• Track test/cases/, test/fixtures/, and test/scripts/.
• Keep generated outputs under test/output/; they are ignored except .gitkeep.
• Do not commit downloaded PDFs, converted Markdown outputs, large logs, or run state.

Development

Development conventions are documented in CONTRIBUTING.md.

Before handing off changes, run:

python -m py_compile attachments\scripts\literature_pool_schema.py `
  .codex\skills\ai4sci-lit-filter\scripts\lit_filter.py `
  .codex\skills\ai4sci-lit-download\scripts\pdf_recovery.py `
  .codex\skills\ai4sci-lit-analysis\scripts\lit_analysis.py `
  .codex\skills\ai4sci-lit-synthesis\scripts\lit_synthesis.py `
  .codex\skills\ai4sci-survey-writing\scripts\survey_writing.py

python -m pytest test\ -q