如何用手工继续这个项目How to continue this project by hand

这一页是给新人的操作手册：机器、数据、代码、命令、规则，以及一份编号的下一步计划。目标是你不需要任何 AI 助手就能接着做。每一条命令都在本机实际跑过（输出见页内），每个输入路径都先确认存在。This page is the operator's manual for a newcomer: machines, data, code, commands, rules, and a numbered plan for what comes next. The goal is that you can continue without any AI assistant. Every command here was actually run on this machine (the output is shown), and every input path was checked to exist first.

1. 机器与分工1. Machines and their roles

来源：agent-memory/environment.md（lang 主机资源规则一节，2026-10-16/17）与 docs/lang-server.qmd。Source: agent-memory/environment.md (the lang host resource rule, 2026-10-16/17) and docs/lang-server.qmd.

2. 数据、代码与结果在哪里2. Where the data, code and results live

来源：AGENTS.md（存储规则）、agent-memory/environment.md（各数据根）、cognition-os/08_RUNNING.md（在飞任务的输入路径）。路径存在性本页写入时已用 ls 核对。Source: AGENTS.md (storage rules), agent-memory/environment.md (the data roots), cognition-os/08_RUNNING.md (the input paths of in-flight tasks). The existence of every path was checked with ls when this page was written.

3. 可直接复制的命令3. Copy-paste commands

3.1 Python 环境（SAS 与 Sherpa 分离）The Python environment (SAS and Sherpa separated)

SAS 与 Sherpa 必须在不同进程里运行：它们需要的 HEADAS 环境互不兼容。项目用 scripts/lang-python.sh 启动一个干净的 CIAO/Sherpa Python，并把本仓库的 src/ 加到 PYTHONPATH。SAS 阶段由管线内部另起子进程初始化。SAS and Sherpa must run in separate processes: they need incompatible HEADAS environments. The project uses scripts/lang-python.sh to start a clean CIAO/Sherpa Python and puts this repository's src/ on PYTHONPATH. The SAS stage is initialized in a separate child process by the pipeline itself.

单线程运行（遵守整机 60 % 规则），把线程数一次性导出，后续命令都继承：Run single-threaded (to respect the whole-machine 60 % rule). Export the thread counts once; later commands inherit them:

cd /u/Lang3/program/S2Fitting
# keep one BLAS thread: the launcher forwards these when the caller sets them
export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1
# read-only: print the CLI help
bash scripts/lang-python.sh -m s2fitting --help

实际输出（2026-10-19）：usage: s2fit [-h] {grid,plan,contract,init,preflight,prepare,extract,responses,fit,run,validate} ...。scripts/lang-python.sh 的 --help 不存在（它不是 argparse 程序），因此这里演示的是它转发的 CLI。Actual output (2026-10-19): usage: s2fit [-h] {grid,plan,contract,init,preflight,prepare,extract,responses,fit,run,validate} .... scripts/lang-python.sh has no --help of its own (it is not an argparse program), so what is shown is the CLI it forwards to.

3.2 查看契约与几何（不需要 SAS 或 Sherpa）Inspect the contract and geometry (no SAS or Sherpa needed)

cd /u/Lang3/program/S2Fitting
bash scripts/lang-python.sh -m s2fitting contract
bash scripts/lang-python.sh -m s2fitting contract --format json
bash scripts/lang-python.sh -m s2fitting plan \
  --config configs/local-lang/fresh-20261001T160304Z/n132d-0210681301-3x3-template.toml

plan 的真实输出（2026-10-19，本机执行）：Actual output of plan (2026-10-19, run on this machine):

Target: N132D (0210681301, R1S032)
Source coordinates: radec
Grid: 3 DISP x 3 XDSP = 9 cells
Cell: 0.75' DISP x 0.75' XDSP
Products: 3 beta spectra, 9 RSPMAT, 3x3 result matrix
Background: template (3 spectrum/spectra)
Fit candidates: 3T
Warnings:
- The VAPEC template is a starting hypothesis and must be reviewed for the target.
- XDSP rows are fitted as separate beta spectra with same-row responses; cross-row
  response mixing and covariance are not modeled.
- Absolute RGS DISP/XDSP coordinates are resolved by SAS during prepare.

来源：docs/architecture.md 命令契约一节。--format {text,json} 与 --config CONFIG 两个 flag 由 s2fit plan --help 列出。Source: docs/architecture.md, the command contract. Both flags, --format {text,json} and --config CONFIG, are listed by s2fit plan --help.

3.3 运行一个完整管线（会调用 SAS 与 Sherpa）Run a full pipeline (this calls SAS and Sherpa)

先 preflight，通过后 run。永远用新的 run-id，绝不复用已发布的 run-id；已存在的 run 目录默认不可变。Run preflight first, then run. Always use a new run-id and never reuse a published one; existing run directories are immutable by default.

cd /u/Lang3/program/S2Fitting
export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1
CFG=configs/local-lang/fresh-20261001T160304Z/n132d-0210681301-3x3-template.toml

bash scripts/lang-python.sh -m s2fitting preflight --config "$CFG"
bash scripts/lang-python.sh -m s2fitting run --config "$CFG" \
  --run-id <NEW-IMMUTABLE-RUN-ID>

flag 依据：s2fit run --help 列出 --config CONFIG 与 --run-id RUN_ID（本页写入时已核对）。run 依次执行 prepare、extract、responses、fit、validate；各阶段也可单独调用（docs/architecture.md 命令契约）。Flag evidence: s2fit run --help lists --config CONFIG and --run-id RUN_ID (checked when this page was written). run executes prepare, extract, responses, fit and validate in order; each stage can also be invoked on its own (docs/architecture.md, the command contract).

3.4 校验 cognition-os 与运行测试套件Validate cognition-os and run the test suite

cd /u/Lang3/program/S2Fitting
python3 scripts/validate-cognition-os.py
python3 scripts/validate-cognition-os.py --audit-products
bash scripts/lang-python.sh -m unittest discover -s tests -q

实际输出（2026-10-19，本机执行）：Actual output (2026-10-19, run on this machine):

{
  "status": "PASS",
  "scope": "cognition links, trust, receipt consistency and pinned evidence",
  "documents": 85,
  "artifacts": 57,
  "experiments": 20,
  "evidence_files": 295,
  "products_audited": false,
  "science_scope": "reference-observation fixed-DISP probes only"
}

----------------------------------------------------------------------
Ran 256 tests in 16.721s

OK

来源：agent-memory/procedures.md 研究认知维护一节。--audit-products 会重算 21 个 RMF、冻结代码与全部输入/校准 pin，较慢，按需使用。Source: agent-memory/procedures.md, research cognition maintenance. --audit-products rehashes 21 RMFs, frozen code and every input/calibration pin; it is slower, so use it on demand.

3.5 生成 handbook 图片Generate the handbook figures

cd /u/Lang3/program/S2Fitting
export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1
bash scripts/lang-python.sh handbook/scripts/make_figures.py

该脚本只读冻结的输入包，输出 PNG 到 handbook/site/assets/，不跑任何科学拟合。实际输出（2026-10-19）：6 个 PNG，最大 134 KiB。This script only reads the frozen input packs and writes PNGs to handbook/site/assets/; it runs no science fit. Actual output (2026-10-19): 6 PNGs, the largest 134 KiB.

4. 必须遵守的规则4. Rules you must keep

4.1 来自 AGENTS.md 的硬规则Hard rules from AGENTS.md

1. 本地 Git 仓库是唯一真源；不要只在远端服务器上改代码。The local Git repository is the source of truth; never edit code only on a remote server.
2. 绝不把 ODF 文件、FITS 产品、日志、Sherpa 会话或完整 run 目录提交进 Git。Never commit ODF files, FITS products, logs, Sherpa sessions or complete run directories to Git.
3. /data/jyz/RGS-tutorial 是只读输入，不要修改。/data/jyz/RGS-tutorial is a read-only input; do not modify it.
4. 不要改动共享的 SAS、HEASoft、CIAO 或 CCF 安装。Do not change the shared SAS, HEASoft, CIAO or CCF installations.
5. SAS 与 Sherpa 在不同进程里运行（见 3.1）。Run SAS and Sherpa in separate processes (see 3.1).
6. USER 源索引要从 SRCLIST 里查出来，绝不假设是 1 或 3。Discover USER source indices from the SRCLIST; never assume source index 1 or 3.
7. 一个完成的 run 必须有 manifest，并通过 s2fit validate。A completed run must contain a manifest and pass s2fit validate.

4.2 科学解释的界限（最容易犯错的地方）Limits on scientific interpretation (the easiest mistakes)

1. 同条带振幅不是去 PSF 的空间图：响应里没有跨行混合时，相邻行的振幅只是“表观”条带亮度（docs/architecture.md、B002）。Same-row amplitudes are not a PSF-deconvolved map: without cross-row mixing in the response, neighbouring-row amplitudes are only apparent strip brightness (docs/architecture.md, B002).
2. 有效宽度（effective sigma）混合了空间、仪器与模型误差，不能直接当作速度（I004）。The effective width (effective sigma) mixes spatial, instrument and model error and cannot be read as a velocity directly (I004).
3. 一个量一句话里只放一个估计量，并说出估计量的名字（“One estimator per sentence”）。One estimator per sentence, and name the estimator.
4. 任何“更好/更差”的比较都要带配对区间；区间含 0 时写“持平”。Every better/worse comparison carries its paired interval; if the interval contains 0, write "no significant difference".
5. 结果还没出来就写“待定”，绝不猜。Write "Pending" for results that do not exist yet; never guess them.

来源：AGENTS.md 工作规则一节、docs/architecture.md（同条带拓扑的解释限制）、cognition-os/03_TRUST_TABLE.md B002 与 I004 行。Source: AGENTS.md working rules, docs/architecture.md (the interpretation limit of the same-row topology), cognition-os/03_TRUST_TABLE.md rows B002 and I004.

5. 下一步：编号计划5. Next steps: the numbered plan

1. 核查 E018c（O VII 第 2 阶段）的报告Triage the E018c (O VII stage 2) report

   目标：确认细网格响应与分界自由的双成分速度分布的拟合结果。输入：/u/Lang3/program/S2Fitting/.agent/jobs/2026-10-19-e018c-ovii-stage2/REPORT.{opus,codexnim}.md 与 /u/Lang2/ai_tmp/{opus,codexnim}/s2fitting-e018c-ovii-stage2-20261019/。方法：按简报里的验收标准复算关键拟合（check A 节点一致性 \(10^{-10}\)；check B Asimov 恢复；锚点 L/D0 C_total 2067.0802）。成功标准：两臂一致、所有 gate 通过；失败标准：任何一个 gate 不过则保留 I029 原状并开 B-record。预计时间：半天到一天。先读：.agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md。Goal: confirm the fine-grid-response, free-boundary two-component velocity fit. Inputs: /u/Lang3/program/S2Fitting/.agent/jobs/2026-10-19-e018c-ovii-stage2/REPORT.{opus,codexnim}.md and /u/Lang2/ai_tmp/{opus,codexnim}/s2fitting-e018c-ovii-stage2-20261019/. Method: replay the decisive fits per the brief's acceptance (check A node agreement \(10^{-10}\); check B Asimov recovery; the anchor L/D0 C_total 2067.0802). Success: both arms agree and every gate passes. Failure: any gate failing keeps I029 unchanged and opens a B-record. Time: half a day to one day. Read first: .agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md.

2. 核查 E020（O VIII 输入包）与 E021（档案普查）Triage E020 (the O VIII input pack) and E021 (the archive census)

   目标：冻结 O VIII 拟合的输入与谱线清单。输入：.agent/jobs/2026-10-19-e020-oviii-pack/REPORT.luna.md、.agent/jobs/2026-10-19-e021-archive-lines/REPORT.sonnet.md。方法：按各自简报的自检 A–D 复算（O VII 波段响应复现 \(10^{-3}\)；计数与背景标度精确；CCD 缺口列出；census 覆盖三个在用观测、AtomDB 交叉核对 10 %）。成功：A–C 全过并冻结；失败：O VIII 拟合不开工（fail-closed）。预计时间：半天。先读：两个 BRIEF.md。Goal: freeze the inputs and the line inventory for the O VIII fits. Inputs: .agent/jobs/2026-10-19-e020-oviii-pack/REPORT.luna.md, .agent/jobs/2026-10-19-e021-archive-lines/REPORT.sonnet.md. Method: replay the self-checks A-D of each brief (the O VII-band response reproduced to \(10^{-3}\); counts and background scaling exact; CCD gaps listed; the census covers the three observations in use, AtomDB cross-checked to 10 %). Success: A-C pass and the packs freeze. Failure: no O VIII fit starts (fail-closed). Time: half a day. Read first: the two BRIEF.md files.

3. 红队 RT22 与 RT23 的分诊Triage red teams RT22 and RT23

   目标：单一模板假设与 \(\delta X_o\) 的读法是否成立。输入：.agent/jobs/2026-10-19-redteam-rt22-template-lines/REPORT.hermes.md、.agent/jobs/2026-10-19-redteam-rt23-dx-astrometry/REPORT.codexnim.md。方法：按 free-redteam 规则，至少复算每条 material 反驳中的一个检查；主 agent 复核后才改信任状态。成功：反驳被复现并按 OS_MAINTENANCE 改信任；失败：反驳不成立则记录并关闭。预计时间：每队半天。先读：cognition-os/REDTEAM_QUEUE.md 的 RT22/RT23 行。Goal: does the single-template assumption and the reading of \(\delta X_o\) hold? Inputs: .agent/jobs/2026-10-19-redteam-rt22-template-lines/REPORT.hermes.md, .agent/jobs/2026-10-19-redteam-rt23-dx-astrometry/REPORT.codexnim.md. Method: per the free-redteam rules, replay at least one check of every material objection; only the main agent changes trust after the replay. Success: objections reproduced and trust updated per OS_MAINTENANCE. Failure: an objection does not reproduce, and it is recorded and closed. Time: half a day each. Read first: the RT22/RT23 rows of cognition-os/REDTEAM_QUEUE.md.

4. O VII 第 3 阶段：全谱线清单进模型O VII stage 3: the full line list into the model

   目标：检验新增谱线是否改变 \(\sigma_v\) 与分裂。输入：E021 的线表 + E018c 的细网格包。方法：在 E018c 的模型里按固定静止波长加入额外谱线（简报已留了钩子），重跑 L 与 L2f。成功：\(\Delta C\) 与参数变化有明确读法；失败：线表不全则先补线表。预计时间：一到两天。先读：.agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md 的“Line content”一节。Goal: test whether the extra lines change \(\sigma_v\) and the split. Inputs: the E021 line table plus the E018c fine-grid packs. Method: add the extra lines at fixed rest wavelengths to the E018c model (the brief leaves a hook) and rerun L and L2f. Success: a clear reading of the \(\Delta C\) and parameter changes. Failure: an incomplete line table is completed first. Time: one to two days. Read first: the "Line content" section of .agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md.

5. O VIII 拟合The O VIII fits

   目标：O VIII 速度场与 O VII/O VIII 对比。输入：E020 冻结的输入包。方法：与 E018c 同一模型族。成功：速度参数与 GOF 报告齐全；失败：输入包自检不过则不开工。预计时间：一到两天。先读：E020 的 BRIEF.md。Goal: the O VIII velocity field and the O VII/O VIII comparison. Inputs: the frozen E020 pack. Method: the same model family as E018c. Success: velocity parameters and goodness of fit reported. Failure: the pack's self-checks fail, so no fit starts. Time: one to two days. Read first: the E020 BRIEF.md.

6. 下载并约简更多观测（D29 默认获准）Download and reduce more observations (allowed by default under D29)

   目标：更多 roll 角约束空间分布。输入：E021 普查结果。方法：XSA 下载到 /u/Lang3/Data/N132D/，然后 cifbuild、odfingest、preflight。成功：preflight 通过；失败：磁盘不足则先清理。预计时间：每个观测约半小时加约简。先读：docs/portable-workflow.md。注意：整机 CPU 与内存保持在 \(60\,\%\) 以内，第二个拟合只在低于该值时启动。Goal: more roll angles to constrain the spatial distribution. Inputs: the E021 census. Method: download from the XSA to /u/Lang3/Data/N132D/, then cifbuild, odfingest, preflight. Success: preflight passes. Failure: if disk is short, clean up first. Time: about half an hour per observation plus reduction. Read first: docs/portable-workflow.md. Note: keep whole-machine CPU and memory within \(60\,\%\); start a second fit only below that.

来源：cognition-os/08_RUNNING.md 第 3、7 节（在飞任务与验收标准）、cognition-os/04_DECISION_LOG.md D29、.agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md。第 6 条是 CoPI 的建议方向，尚未派发。Source: cognition-os/08_RUNNING.md sections 3 and 7 (in-flight tasks and acceptance criteria), cognition-os/04_DECISION_LOG.md D29, .agent/jobs/2026-10-19-e018c-ovii-stage2/BRIEF.md. Item 6 is a CoPI proposal, not yet dispatched.