Development Guide

简体中文

---

1. Environment

cd Paper_Atlas1.5
python launcher.py --prepare-only
python launcher.py --reinstall

--prepare-only creates .venv and installs dependencies without starting the server.

Manual:

python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

Use the manual verification checklist in section 3 before a release.

---

2. Run

.venv/bin/python app.py --host 127.0.0.1 --port 8765

or:

.venv/bin/python launcher.py --no-open

The server creates data/ automatically. For development, use a disposable copy of the data folder so real papers and notes are not touched.

---

3. Manual verification

Before publishing, at minimum:

python launcher.py --check

Start the app and verify:

1. login page and access code;
2. dashboard counters and project list;
3. arXiv search with plain keywords (avoid a real AI call);
4. create a project and link a paper;
5. PDF reader: canvas, text layer, paging, zoom, outline;
6. AI analysis panel (existing analysis) and evidence navigation;
7. text selection, highlight creation and note saving;
8. settings save/reload;
9. close and reopen the reader to confirm reading-state restore.

For a release build:

./dist/PaperAtlas --check

---

4. Data scripts

python scripts/backup_data.py          # DB/config/library/analysis
python scripts/verify_data.py          # read-only integrity checks
python scripts/migrate_schema.py       # migrations with automatic backup
python scripts/migrate_schema.py --dry-run
python scripts/migrate_schema.py --restore-on-failure

All scripts support --help.

---

5. Database changes

Schema lives in atlas/db/schema.py.

Rules:

1. Add a new migration entry; never edit a released migration.
2. Prefer additive changes (CREATE TABLE, CREATE INDEX, ALTER TABLE ADD COLUMN).
3. Check PRAGMA table_info before ALTER TABLE so retries are safe.
4. Record the version in schema_migration.
5. Update repositories and API schemas.
6. Back up and migrate a copy of a real database before applying.
7. Never delete user tables or columns in a migration.

V4_COLUMNS = (("annotation", "my_field", "TEXT NOT NULL DEFAULT ''"),)

def _apply_v4(conn):
    for table, column, ddl in V4_COLUMNS:
        existing = {row[1] for row in conn.execute(f"PRAGMA table_info({table})")}
        if column not in existing:
            conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {ddl}")

MIGRATIONS = (
    ...,
    (4, "my_change", _apply_v4),
)

---

6. Code conventions

• Python 3.10+, type hints on public functions, from __future__ import annotations.
• Keep domain logic out of HTTP routers and the browser.
• Use atlas.core.errors; new endpoints return the unified error envelope.
• Use LLMClient for every model call; never create a second OpenAI client.
• Use atlas.core.files for atomic writes/path checks.
• Do not read data/config.json directly; use the settings facade.
• Write user data under data/ only.
• Frontend: textContent only (never innerHTML for user/model data), no CDN, no framework.
• Reader: keep PDF rendering and analysis data separate; do not call a model to render.

---

7. Structure notes

• app.py is the composition root for arXiv/system routes; feature routers live in atlas/api/.
• review/ is the journal acquisition and analysis engine, reused by the reader.
• atlas/services/reader.py reads analysis results; it must not trigger a second analysis.
• static/vendor/pdfjs/ is third-party code; update it as a whole and keep LICENSE.

---

8. Build

python build.py --check
./build.sh --clean --zip       # Linux/macOS
build.bat --clean --zip        # Windows

PyInstaller bundles:

• Python + runtime dependencies
• templates/ and static/ (including PDF.js)
• atlas and review

Build on the target OS family. Output is in dist/.

---

9. CI

.github/workflows/build.yml runs on Windows and Ubuntu:

1. install dependencies;
2. compile-check Python sources;
3. build with PyInstaller;
4. smoke-test --check;
5. upload the zip artifact.

CI does not call real AI or publisher APIs.