pbf/AGENTS.md

# AGENTS.md

## Project Identity

Project root: `/root/sourceserver/pbf`

This repository is the NavSea PBF engineering, delivery, and audit workspace.

Primary Git remote:

- `origin -> ssh://git@nas:2222/tei/pbf.git`

## 2026-10-13 全国 Full PBF 权威生产基线（优先于下列历史 20nm 规则）

用户明确指定公网 `pbf-delivery-full-20260418-rebuild` 是 NavSea PBF 全国 Full 标准；请首先阅读：
`docs/报告/20261013_NavSea_PBF全国Full生产链溯源调查_v1.md` 及 `NavSea_全国完整PBF重建流水线说明.md`。
真正的 2026-04-18 四段生成路径是 `/home/wwwroot/pbf-delivery-full-20260418-rebuild.parts/{z0_8,z9_10,z11,z12}`；
生产源码历史固定在 `6d72340`，采用 NewPEC 原始 PBF + MySQL `pbf_analysis` / `navsea-core`。
2026-10-13 抽查多个缩放等级的公网样本与历史分片字节一致。
本地同名合并目录已在后续语义统一操作中出现部分不同的文件，并与 20260808 派生目录存在硬链接；
不要把该目录的当前全部内容误当成公网原始生产基线。
历史 20nm 对比页和 Domain/Provider 路径是各自的历史或独立范围，不能覆盖此权威生产定义。
任何新重建只允许写独立候选目录；严禁覆盖原始分片、正式同名目录或公开版本。

## First Files To Read

When resuming work in this project, read in this order:

1. [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)
2. [`PROJECT_HANDOFF_2026-03-31.md`](/root/sourceserver/pbf/PROJECT_HANDOFF_2026-03-31.md)
3. [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
4. [`NavSea_Audit_Logic_And_Evolution_2026-04-01.md`](/root/sourceserver/pbf/NavSea_Audit_Logic_And_Evolution_2026-04-01.md)

If the task is specifically about Domain work, also read:

5. [`NavSea_Chart_Domain_Model_v1.md`](/root/sourceserver/pbf/NavSea_Chart_Domain_Model_v1.md)
6. [`NavSea_Semantic_Package_Overlay_Design.md`](/root/sourceserver/pbf/NavSea_Semantic_Package_Overlay_Design.md)

## Current Reliable Audit Baseline

As of 2026-03-31:

- the most reliable current delivery audit baseline is `Karatsu 10nm`
- the trusted report is:
  - [`NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md`](/root/sourceserver/pbf/NavSea_Original_vs_Delivery_Render_Audit_Karatsu_10nm_2026-03-31.md)

Important limitation:

- `Karatsu 20nm delivery` is currently not object-auditable with the existing audit script because the delivery PBF no longer preserves enough trace-back anchor fields

## Audit Order

Current official order:

1. object preservation audit
2. render audit
3. AOI / visual audit

Do not treat a visual match as a pass if objects have already been dropped or wrongly merged.

Preferred current 20nm object-preservation entry point:

- [`navsea_object_preservation_audit.py`](/root/sourceserver/pbf/navsea_object_preservation_audit.py)
- current reports:
  - [`report/object_preservation_20nm/object_preservation_delivery_20nm.md`](/root/sourceserver/pbf/report/object_preservation_20nm/object_preservation_delivery_20nm.md)
  - [`report/object_preservation_20nm/object_preservation_final_20nm.md`](/root/sourceserver/pbf/report/object_preservation_20nm/object_preservation_final_20nm.md)

## Current Visual Regression Baseline

The current working visual baseline is:

- `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`

Current target PBF line for visual restoration:

- `/home/wwwroot/pbf-delivery-karatsu-20nm`

Rules:

- use the page above as the primary visual regression surface
- do not switch the primary comparison URL casually
- do not create additional comparison pages unless explicitly requested
- prefer improving the current 20nm compare page over replacing it
- keep the click-pick inspection panel working on both left and right maps
- every visible compare-page revision must bump a human-readable version string on the page itself
- show that version near the reload button so visual review can confirm refresh state
- use the same version string as a cache-busting base for style / tile reloads

## Working Rules

### 0. 文档语言统一

本项目默认文档语言为中文。

规则：

- `STEP_RECORD.md` 必须使用中文
- 所有新增输出文档必须使用中文
- 所有新增审计报告必须使用中文
- 不要再新增英文版交接、审计、总结文档，除非用户明确要求

### 1. Step Record Must Stay Fresh

Whenever there is meaningful progress, update:

- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)

This includes:

- after audits
- after code fixes
- after direction changes
- before stopping at a meaningful checkpoint

### 2. Commit Carefully

This repository is often in a dirty working state.

Rules:

- never stage unrelated modified files
- only commit files touched for the current task
- do not sweep untracked audit artifacts into commits unless that is the explicit goal

### 3. Preserve Audit Reality

Do not present a delivery audit as trustworthy unless object identity is still recoverable.

Current known-good object-level delivery audit pattern:

- use `/home/wwwroot/pbf-delivery-karatsu-10nm`
- use `--fid-key 'thisMyWorld@2026'`
- use `--match-on-fid-only`

### 4. Prefer Repo-Local Documentation

When deciding what to do next, prefer repo-local docs over memory.

Key references:

- [`NavSea_Legacy_Field_Exit_Roadmap.md`](/root/sourceserver/pbf/NavSea_Legacy_Field_Exit_Roadmap.md)
- [`NavSea_Delivery_Preflight_Audit_Spec.md`](/root/sourceserver/pbf/NavSea_Delivery_Preflight_Audit_Spec.md)
- [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md)

### 5. Make Visual Revisions Traceable

When changing the primary compare page:

- bump the compare page version string
- display it near the reload button
- redeploy the HTML to `/mnt/sda1/www/newpec/navsea-compare-karatsu-20nm.html`
- if the visual change depends on style updates, redeploy the corresponding style JSON too

### 6. Prefer Unified Strict Audit For 20nm Visual Gate

For the current 20nm visual baseline, prefer:

- [`navsea_strict_audit.py`](/root/sourceserver/pbf/navsea_strict_audit.py)
- [`strict_audit_hotspots_20nm.json`](/root/sourceserver/pbf/strict_audit_hotspots_20nm.json)
- [`strict_audit_hotspots_20nm_pilot.json`](/root/sourceserver/pbf/strict_audit_hotspots_20nm_pilot.json)
- visual review page:
  - `http://192.168.200.184/newpec/navsea-compare-karatsu-20nm.html`

Even when 10nm delivery is rebuilt and audited:

- keep `20nm compare` as the visual audit baseline
- use `10nm` as the object-level backend audit reference only
- do not silently switch the user's visual review baseline away from `20nm compare`

For small-scope image audit experiments:

- keep the style under test fixed to:
  - [`src/pbf/style.navsea-delivery-karatsu-10nm.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-karatsu-10nm.json)
- prefer the 3-hotspot pilot config first
- use full hotspot coverage only when pilot hotspots are no longer enough

This script combines:

- browser-rendered screenshot diff from the fixed compare page
- backend render audit summary from the current 20nm audit JSON

And now focuses on:

- small AOI hotspot crops that are chosen to calibrate backend audit blind spots
- not just one coarse full-screen diff number

Use it when you need one report that explains both:

- what the user really sees
- what the backend render audit currently says

## Resume Checklist

At the start of a session:

1. Read [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).
2. Check `git status --short --branch`.
3. Confirm `git remote -v` still points to `nas`.
4. Continue from the latest recorded next step.

At the end of a session:

1. Update [`STEP_RECORD.md`](/root/sourceserver/pbf/STEP_RECORD.md).
2. If the checkpoint is useful, commit it.
3. Keep unrelated dirty files out of the commit.



## 3. Codex 文档命名与版本管理规则

当 Codex 被要求编写、整理或生成项目文档时，必须遵守以下规则：

- 文档文件名必须使用中文
- 文档正文内容必须使用中文
- 在创建整理后的文档之前，必须先检查项目中已有文档
- 如果已有文档是在总结同一个主题、同一个问题或同一类方案，不要另起完全不同的文件名
- 对同一个主题的总结文档，必须沿用统一主题名称，并在文件名中加入版本号
- 版本号必须逐步升级，例如：
  - `AIS数据解析总结-v1.md`
  - `AIS数据解析总结-v2.md`
  - `AIS数据解析总结-v3.md`
- 新版本应表示当前整理后的最新版
- 避免对同一个事情反复创建多个不同名称的总结文档
- 如果确实需要新文件名，必须是因为主题范围发生了明显变化