edit | blame | history | raw

慧博 10 分钟快速采集工具开发方案 V002

创建人员：dev.developer.ana.cai
文件职责：append-only 修复 V001 独立审核的 6 个 blocking findings，并冻结可直接实现、测试和复核的模块 API、状态模型、时间边界、原子归档、额度并发与性能样本合同。
predecessor：CODE-DESIGN-ANA-HIBOR-FAST-COLLECTION-V001=15549/ecacaaea740454ae56e928ef58af4a5d5e706334b1ac917c8647db8a8eb3edf9。
predecessor review：AUDIT-DEV-ANA-HIBOR-FAST-COLLECTION-DESIGN-V001=HOLD/6/6，审计入口 ana-doc/案例审计报告.md。
记录方式：V001 保持不可变；V002 对冲突处拥有后继优先级，V001 已通过的包名、缓存、访问控制、原件、额度上限、角色和零实现关口全部继续有效。普通源码/内部测试按语义验收，PDF、正式 manifest、额度账本和终态证据按真实消费者要求做哈希与不可变验证，不恢复普遍逐字节预冻结。

1. 本轮 closure 与不变边界

V002 必须同时关闭：

  1. BLOCK-HIBOR-DESIGN-01：逐模块 API、调用图、canonical model/schema、主键、错误与 exit 总映射；
  2. BLOCK-HIBOR-DESIGN-02：任务观察时点传递、单一 monotonic deadline、子进程/锁/I/O/terminal 的有界生命周期；
  3. BLOCK-HIBOR-DESIGN-03：PROVISIONAL_VISIBLE 与 DETAIL_CONFIRMED 分离，早停失效后的 cursor 恢复与补扫；
  4. BLOCK-HIBOR-DESIGN-04：同目录 staging、完整验证后原子 no-replace 发布、崩溃恢复与 package closure；
  5. BLOCK-HIBOR-DESIGN-05：额度 read-fold-reserve 原子临界区、事件主键/幂等、并发和 replay；
  6. BLOCK-HIBOR-DESIGN-06：10 个 trigger 的预登记总体、批量计数、SLA failure 与 external exclusion 口径。

方案复审 PASS 前仍禁止创建候选源码/测试、运行 Python/ADB/APP/dry-run、创建额度账本或产生真实下载 trigger。

2. 唯一 owner、模块 API 与调用图

2.1 唯一 owner

cli.main() 是唯一 orchestration owner；其余模块不得互相创建 run、写 terminal、追加额度或自行启动外部命令。RunContext 由 CLI 创建一次并只读传递。外部命令全部通过 ProcessSupervisor.run(argv: Sequence[str], ...)，必须是 argv list、shell=False；模块不得调用 os.system、shell 字符串、隐式 PATH 脚本或自行 subprocess.*。

2.2 公共 API

下列为包内唯一 public API；未列函数/类必须以下划线开头，测试不得依赖其实现细节。

模块 唯一公共 API 返回/异常 owner
models.py load_task_spec(path: Path) -> TaskSpec；validate_task_spec(x: Mapping) -> TaskSpec；to_ordered_dict(model) -> dict 仅抛 ContractError(code, field, detail) CLI
budget.py Budget.start(observed_at_utc: str, total_ms: int, close_reserve_ms: int, clock: Clock) -> Budget；remaining_ms(kind: Literal['work','close']) -> int；checkpoint(phase: Phase, operation: str, kind='work') -> None；slice(max_ms: int, teardown_ms: int) -> int 到期抛 BudgetExpired; wall-clock 回退/未来时间/启动前已耗尽抛 ContractError CLI
process.py ProcessSupervisor.run(argv: Sequence[str], cwd: Path, budget: Budget, phase: Phase, input_bytes: bytes|None, max_stdout: int, max_stderr: int) -> ProcessResult 不抛裸异常；所有可观测结果封装；liveness unknown 置 LIVENESS_UNKNOWN ADB/PDF provider only
adb.py AdbClient.preflight(ctx) -> DeviceSnapshot；list_cache(ctx) -> tuple[RemoteFile,...]；remote_sha256(ctx,path)->str；pull(ctx,remote,local_staging)->PullResult；ui_dump(ctx)->UiSnapshot；screenshot(ctx,dst_staging)->ArtifactDraft；tap/swipe/input_text/back/start_package(ctx,...) -> ActionReceipt 只经 ProcessSupervisor；包/设备/cache 身份漂移为 typed stop UI/cache
ui.py FastScanner.scan(ctx, checkpoint: ScanCheckpoint|None) -> ScanOutcome；confirm_detail(ctx,candidate)->Candidate；restore(ctx,checkpoint)->ScanCheckpoint；trigger(ctx,candidate,reservation)->TriggerReceipt 不写 quota/PDF/terminal；每次动作前后验证 anchor/package CLI
quota.py QuotaLedger.snapshot(ctx)->QuotaSnapshot；reserve(ctx, report_key, slot_id)->ReservationResult；confirm(ctx,reservation,trigger)->QuotaEvent；mark_uncertain(...)；release(...)；raise_baseline(ctx,floor,evidence_ref)->QuotaEvent 每次 API 内部独占一次完整 read-validate-fold-check-append-fsync-reopen 临界区 CLI
cache.py CacheWatcher.capture_baseline(ctx)->CacheBaseline；wait_unique_stable(ctx,baseline,trigger)->CacheMatch 只读远端；歧义/超时返回 typed stop CLI
archive.py ArchiveManager.stage_pull(ctx,match)->ArtifactDraft；validate(ctx,draft,detail)->ValidatedArtifact；publish_no_replace(ctx,validated,destination)->PublishedArtifact；recover(ctx,recovery_record)->RecoveryResult 不写 manifest/quota/terminal；正式路径只通过原子 publish 出现 CLI
manifests.py append_manifest(ctx,row)->ManifestReceipt；write_delivery(ctx,package)->PublishedArtifact；write_timing(ctx,rows)->PublishedArtifact 同目录 staging+验证+no-replace；manifest 单锁 append 并 fsync CLI
terminal.py build_terminal(ctx,package,stop)->TerminalRecord；persist_terminal(ctx,record)->TerminalReceipt；render_public_payload(record)->str 不发送消息；console payload 永远可生成，持久化失败如实记录 CLI
cli.py main(argv: Sequence[str]|None=None)->int 捕获所有 typed/untyped 错误，按第 5 节唯一映射返回 public

2.3 固定调用图

cli.main
  -> models.load_task_spec
  -> Budget.start
  -> AdbClient.preflight + QuotaLedger.snapshot
  -> FastScanner.scan
       -> AdbClient.ui_dump/screenshot/action
  -> FastScanner.confirm_detail
  -> CacheWatcher.capture_baseline
  -> QuotaLedger.reserve
  -> FastScanner.trigger
  -> QuotaLedger.confirm|mark_uncertain|release
  -> CacheWatcher.wait_unique_stable
  -> ArchiveManager.stage_pull -> validate -> publish_no_replace
  -> append_manifest
  -> write_delivery -> write_timing
  -> build_terminal -> persist_terminal -> render_public_payload

collect-batch 仅在 CLI 层循环 item；每个 item 使用独立 report_key、reservation、artifact 和 manifest row，共享 search/scan checkpoint。任何模块不得反向调用 CLI 或 terminal。

3. Canonical model 与 schema

3.1 基本类型与序列化

  • Id：非空 ASCII [A-Za-z0-9._:-]{1,160}；PathText：绝对 Windows 路径字符串；RemotePath：以固定 cache root 开头的 POSIX 路径。
  • UtcTime：UTC RFC3339，毫秒 3 位，后缀 Z；Hash：小写 64 位十六进制；Bytes/Millis：非负 JSON integer；BOOL 只允许 JSON true/false。
  • JSON 使用 UTF-8、无 BOM；模型输出按本文字段顺序，null 必须显式出现，不允许额外键。CSV 列顺序固定，null 编码为空字段，BOOL 编码 true|false。
  • canonical acceptance 是“严格 parse + 字段/类型/枚举/交叉约束 + 重序列化语义一致”；只有 quota/正式 manifest/terminal 发布后记录实际 bytes/hash，不预冻结未来运行字节。

3.2 TaskSpec V002（有序 27 键）

schema_version,task_id,handoff_id,requester,review_owner,mode,query,quantity,destination_root,output_root,quota_ledger,adb_executable,pdfinfo_executable,package_name,cache_root,device_serial,observed_at_utc,total_budget_ms,close_reserve_ms,batch_increment_budget_ms,min_screens,normal_max_screens,hard_max_screens,hard_max_candidates,selection_filters,performance_slot_id,performance_plan_id

  • schema_version='HIBOR_FAST_TASK_SPEC_V002'；mode=DRY_RUN|COLLECT_ONE|COLLECT_BATCH|RESUME_POSTPROCESS。
  • package_name='cn.com.hibor'；cache_root='/sdcard/Android/data/cn.com.hibor/files/myfile/'。
  • quantity INT 1..10；collect-one 的 total_budget_ms=600000；collect-batch 的 total_budget_ms=600000+240000*(quantity-1)；close_reserve_ms=10000；batch_increment_budget_ms=240000；screens=3/5/20；candidates=100。
  • device_serial STRING|null；dry-run 必须 null，真实模式必须非空并与唯一设备一致。
  • performance_slot_id/performance_plan_id 均 STRING|null；真实性能运行必须非空，普通生产采集均为 null。
  • selection_filters 为有序对象：subject:string,allowed_institutions:array<string>|null,report_types:array<string>,date_from:YYYY-MM-DD,date_to:YYYY-MM-DD,min_pages:int,max_pages:int,analyst_required:bool,max_per_institution:int；不得含评分之外的主观字段。

3.3 Candidate V002（有序 22 键）

candidate_id,report_key,state,query,screen_index,rank_on_screen,result_title,result_institution,result_date,result_pages,result_analysts,detail_title,detail_institution,detail_date,detail_pages,detail_analysts,detail_fingerprint,hard_filter_pass,score,duplicate_of,reject_code,checkpoint_id

  • state=DISCOVERED|PROVISIONAL_VISIBLE|DETAIL_OPENED|DETAIL_CONFIRMED|REJECTED|TRIGGER_RESERVED|TRIGGERED|CACHE_MATCHED|ARCHIVED|FAILED。
  • result 字段在 PROVISIONAL_VISIBLE 后非空；detail 字段在 DETAIL_CONFIRMED 后非空；此前为 null。
  • hard_filter_pass 为 BOOL|null，仅 DETAIL_CONFIRMED/REJECTED 可非空；score 为 INT|null，仅 result 字段完整时可非空。
  • duplicate_of/reject_code 为 STRING|null；被拒/重复时必须提供其一。稳定 top-K 只能使用 PROVISIONAL_VISIBLE 的 provisional ranking 作为“暂停扫描”依据，最终 trigger 集只允许 DETAIL_CONFIRMED && hard_filter_pass=true && duplicate_of=null。

3.4 ScanCheckpoint V002（有序 10 键）

checkpoint_id,query,screen_index,scroll_count,page_fingerprint,first_visible_key,last_visible_key,seen_candidate_ids,provisional_top_ids,created_at_utc

数组顺序为实际扫描顺序；page_fingerprint 是 UI dump 规范化可见节点的 SHA-256，不是截图内容推断。restore 后 query、screen/scroll、first/last key 和 fingerprint 必须全部一致，否则 UI_CURSOR_RESTORE_FAILED。

3.5 QuotaEvent CSV V002（固定 18 列）

schema_version,event_id,idempotency_key,ledger_date,event_seq,event_type,task_id,handoff_id,run_id,slot_id,report_key,reservation_id,ref_event_id,confirmed_delta,uncertain_delta,reservation_delta,baseline_floor,created_at_utc

  • event_id=sha256(ledger_date+'|'+idempotency_key+'|'+event_type+'|'+event_seq)；idempotency_key=sha256(task_id+'|'+handoff_id+'|'+slot_id+'|'+report_key)。
  • event_type=BASELINE_ESTIMATE|CORRECTION_RAISE|RESERVE|CONSUME_CONFIRMED|CONSUME_UNCERTAIN|RELEASE。
  • baseline/correction：三个 delta 为 0，baseline_floor 为 INT；baseline 首次至少 3，correction 只能提高 floor，ref_event_id 指向证据事件。
  • reserve：0/0/+1；confirmed：+1/0/-1；uncertain：0/+1/-1；release：0/0/-1；其余组合非法。
  • 一个 idempotency key 最多一个 active reservation 和一个终结事件；同 event_id/同整行是 replay，返回原 receipt；同 event_id 或同 idempotency key 但字段不同为 QUOTA_REPLAY_CONFLICT。

3.6 TimingRow CSV V002（固定 12 列）

schema_version,run_id,item_id,phase,operation,monotonic_start_ns,monotonic_end_ns,elapsed_ms,wall_start_utc,wall_end_utc,outcome,detail_code

phase=preflight|quota|ui_search|ui_scan|detail_and_trigger|cache_wait|copy|validation|manifest|delivery|timing|terminal；outcome=PASS|STOP|FAIL|SKIP。monotonic 只允许进程内差值，wall 仅审计。

3.7 ManifestRow CSV V002（固定 34 列）

schema_version,row_id,task_id,handoff_id,run_id,item_id,slot_id,requester,review_owner,query,candidate_id,report_key,title,institution,report_date,analysts,selection_reason,remote_path,remote_bytes,remote_sha256,local_path,local_bytes,local_sha256,pdf_magic_ok,pdf_openable,page_count,encrypted,quota_reservation_id,quota_terminal_event_id,status,stop_code,created_at_utc,reused_without_new_trigger,external_evidence_hash

  • row_id=sha256(task_id|run_id|item_id|report_key|status)；成功必须 34 键全部有值或合法 null，且 remote/local bytes/hash 相等、magic/openable true、encrypted false、page_count 与详情一致。
  • status=SUCCESS|DUPLICATE|FAILED|STOPPED；非 SUCCESS 的未知证据保持 null，禁止填造。
  • external_evidence_hash 是该行对应正式 PDF 的 SHA-256；无正式 PDF 时为 null。

3.8 PackageState V002 与终态（有序字段）

每个 item 的 package row 为：item_id,report_key,state,trigger_attempted,quota_state,staging_path,final_path,manifest_row_id,delivery_present,timing_present,terminal_present,stop_code。

TerminalRecord V002 固定 30 键：

schema_version,task_id,handoff_id,run_id,mode,status,exit_code,stop_code,blocker,observed_at_utc,started_at_utc,ended_at_utc,total_elapsed_ms,work_deadline_reached,close_deadline_reached,requested,triggered,succeeded,failed,duplicates,gaps,quota_confirmed,quota_uncertain,quota_active,quota_safe_available,items,manifest_path,delivery_path,timing_path,prohibited_action_attestation

items 按 item_id 排序，元素即上述 package row。任何路径不存在时 null；prohibited_action_attestation 固定对象：remote_original_modified:false,credential_persisted:false,access_control_bypassed:false,body_parsed:false,research_conclusion_generated:false,external_message_sent:false。

4. 候选、早停、详情确认与补扫状态机

4.1 两层集合

  • provisional_set：结果页可见字段通过“可先判断”的过滤规则；只用于决定是否暂停扫描、安排详情复核，不等于合格候选。
  • confirmed_set：详情页字段与结果页一致、所有硬过滤通过、去重完成；只有该集合可 reservation/trigger。
  • stable_top_k：连续两屏 provisional top quantity+2 的 id+score 不变，只产生 PAUSE_FOR_DETAIL，不产生最终早停。

4.2 固定流程

  1. 从 checkpoint 或第 1 屏开始，至少扫描 3 屏；每屏落内存 candidate/checkpoint，不写正式结果。
  2. 达到 provisional quantity+2 且两屏稳定时保存 checkpoint，暂停扫描并按 score/既有并列规则逐个 confirm_detail。
  3. 详情字段必须与结果页 title/institution/date/pages/analysts 可比字段一致；不一致为 DETAIL_RESULT_MISMATCH 并 REJECTED。
  4. 同机构上限、报告 identity 去重、日期/页数/类型/分析师过滤在详情确认后再次执行。
  5. confirmed_set>=quantity 才允许最终结束扫描；否则调用 restore(checkpoint)，从该 cursor 的下一未处理屏继续。
  6. 详情打开失败、详情不一致、duplicate、硬过滤失败、trigger 前页面漂移、trigger 后确认未触发，都不会把 provisional 当成功；恢复后继续扫描。
  7. 扩展扫描终止只允许：confirmed 数量满足；连续 3 屏无新增 provisional 且所有 provisional 已详情判定；或达到 20 屏/100 unique 上限。数量不足时返回 gap，不伪装成功。

4.3 checkpoint 恢复

恢复路径固定为：回到搜索入口→重新输入同 query→按 scroll_count 重放纵向翻页→比较 first/last visible key 与 page_fingerprint→从已记录 seen ids 后继续。每步都受 Budget；任一 anchor/fingerprint 不一致停止，不猜坐标。测试必须覆盖详情失败、详情/结果不一致、重复候选、trigger 未发生、早停后补扫成功、恢复 fingerprint 漂移和硬上限不足。

5. 单一时间预算与子进程/阻塞 I/O 生命周期

5.1 从“请求已观察”开始计时

调用方在观察请求且环境可用时写入 TaskSpec.observed_at_utc；CLI 启动立即读取同主机 UTC，并计算 startup_elapsed_ms=now_utc-observed_at_utc。允许时钟前进，若 observed 在未来超过 2 秒、无法 parse、时差计算异常或 startup elapsed 已达到 600000ms，返回 BLOCKED_INPUT/TIME_BUDGET_STOP，不触发 UI。

CLI 随后记录 start_monotonic_ns，并创建：

  • close_deadline=start_monotonic + max(0,600000-startup_elapsed_ms)；
  • work_deadline=close_deadline-10000ms；最后 10 秒只用于 kill/drain、quota 收口、timing/terminal，不得启动新 UI、pull、hash、publish 或 manifest 行。
  • 批量首 item 继承上述 deadline；每个后续 item 在前一 item terminal 时创建 min(close_deadline, item_start+240000ms) 的 item deadline。总体任务不得超过首份 600 秒；如任务明确允许批量持续，batch task spec 必须把 total_budget_ms 写成 600000+240000*(quantity-1)，首份仍独立 600 秒。V002 默认按该公式验证，不接受其他值。

所有 SLA 总耗时使用 ended_at_utc-observed_at_utc 与进程 monotonic elapsed 交叉核对；偏差超过 2 秒为 timing invalid，样本计失败。

5.2 ProcessSupervisor 总状态机

固定状态：NOT_STARTED -> STARTED -> EXITED；异常分支 START_FAILED；deadline 分支 TIMEOUT -> TERMINATE_ONCE -> WAIT_BOUNDED -> EXITED_AFTER_TERMINATE|LIVENESS_UNKNOWN。

  1. start 前 budget.slice(max_ms, teardown_ms=3000) 必须返回正值；argv 非空字符串数组，shell=False，cwd 固定，stdin/stdout/stderr 为 binary pipes 或 DEVNULL。
  2. Windows 使用一个 per-child Job Object，JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE，先 suspended create、成功 assign 后 resume；任一步失败时不运行未受管 child。非 Windows 测试用新 process group 等价模拟。
  3. communicate(timeout=slice)；stdout/stderr 各有上限，超限立即进入 terminate，不截断后冒充成功。
  4. timeout/异常只允许一次 TerminateJobObject，随后 wait/communicate 最多 min(3000ms,close_remaining)；确认 exit 后才返回。不能确认时关闭 Job handle并返回 LIVENESS_UNKNOWN，CLI 只做内存 terminal，不再读/写可能被 child 改动的 artifact。
  5. ProcessResult 固定字段：argv_redacted,started,pid,exit_code,timed_out,terminate_issued,exited,liveness_unknown,stdout_bytes,stderr_bytes,stdout_truncated,stderr_truncated,started_at_utc,ended_at_utc,elapsed_ms,error_code。凭据永不进入 argv/stdin/output。

5.3 锁与文件 I/O

  • 锁：每 50ms 非阻塞尝试，最长 min(2000ms,work_remaining)；失败 LOCK_TIMEOUT，不得阻塞到 deadline。
  • pull 输出仅到 staging；复制/hash 每 1MiB 前后 checkpoint；截图/小 JSON 每 64KiB。到期立即关闭句柄，保留 staging，不登记 success。
  • flush/fsync、pdfinfo 等不可中断边界仅在 work_remaining>=5000ms 时进入；进入前后均 checkpoint。调用返回晚于 work deadline 时结果一律 TIME_BUDGET_STOP，即使 bytes/hash 正确也不得发布/登记 SUCCESS。
  • manifest/delivery/timing/terminal 进入各自步骤前保留 2000/2000/2000/3000ms；不足则跳过下游、在 console terminal 中把对应 present=false。close deadline 到达后不得再做文件写，直接返回内存 terminal。
  • hang/kill/wait、stdout overflow、锁阻塞、copy/hash 分块到期、fsync late、pdfinfo late、manifest late、terminal persist late 都必须有 deterministic fake-clock/subprocess tests。

6. 原子归档、崩溃恢复与 package closure

6.1 staging 与 no-replace 发布

  1. staging 必须在最终目标同一 NTFS volume、同一 destination 目录下的 .hibor-staging/，名称 <run_id>.<item_id>.<nonce>.part，以 os.open(O_CREAT|O_EXCL|O_WRONLY) 创建；staging 永不被当正式 PDF。
  2. pull/copy 完成后 flush+os.fsync，关闭；独占只读 reopen，验证 %PDF-、remote/local bytes/hash、pdfinfo open/page/encryption 和详情页一致。
  3. 发布使用 Win32 CreateHardLinkW(final,staging)：同卷、原子创建新目录项、final 已存在则失败且绝不替换；随后只读 reopen final 再校验 bytes/hash，最后 unlink staging。若 hard-link capability/reparse/volume 不符合，预检 STOP，不降级为覆盖 rename/copy。
  4. crash before link：只有 .part；crash after link before unlink：final 与 .part 指向同一已验证文件；恢复以 file-id+bytes/hash 证明同一后清理 staging。不同 hash、unknown file-id 或 final reparse 一律冲突 STOP。
  5. 任何最终路径若已存在：ordinary file 且 hash 等于期望→DUPLICATE，复用原文件但不重复 consume；其他 object/hash→FINAL_PATH_CONFLICT。不删除、截断、覆盖或改名模拟器原件和既有正式文件。

6.2 package state/expected-presence（总序）

state PDF staging final PDF quota terminal manifest delivery timing terminal 允许后继
P00_INIT N N N N N N N preflight
P01_RESERVED N N N N N N N trigger
P02_TRIGGER_UNKNOWN N N U N N N N close only
P03_CACHE_MATCHED N N V N N N N stage
P04_STAGING_PARTIAL I N V N N N N recover/stop
P05_STAGING_VALID V N V N N N N publish
P06_PUBLISHED N V V V N N N N manifest
P07_MANIFESTED N V V V V N N N delivery
P08_DELIVERY N V V V V V N N timing
P09_TIMING N V V V V V V N terminal
P10_CLOSED N V V N V U N V N V N V N V N none

N=absent,V=known valid,I=known partial/invalid,U=unknown。顺序固定：quota trigger 终结→PDF publish→manifest→delivery→timing→terminal。上游失败不补造下游；P10 terminal 根据实际 presence 记录，不要求为了“闭包好看”写假文件。

6.3 恢复

每个 staging 创建后同步写一个同目录 recovery JSON（同样 O_EXCL），字段为 schema_version,run_id,item_id,remote_path,remote_bytes,remote_sha256,staging_path,final_path,stage,created_at_utc。resume-postprocess 仅在：无 active UI/process、quota 已是 confirmed/uncertain、remote identity 不变、staging/final 可安全复核时继续；否则 STOP。故障注入点固定为 create 前、每 1MiB 后、fsync 前后、hardlink 前后、final reopen 后、manifest/delivery/timing/terminal 前后，断言正式路径不会指向 partial。

7. 额度并发、reducer 与 replay

7.1 唯一临界区

账本旁固定 daily_quota_<date>.lock。第一次以 O_CREAT 建立普通 lock file，之后所有进程打开同一文件并用 msvcrt.locking(LK_NBLCK,1) 锁第 0 字节；lock file 不删除。每个 quota public API 在同一个锁持有期内严格执行：

read all bytes -> strict CSV/header/date/row validation -> fold -> idempotency lookup -> APP visible remainder conservative reconcile(if provided) -> safe_available check -> construct one row -> append -> flush -> fsync -> reopen/read/fold verify -> unlock。

锁前后都 checkpoint；锁 timeout/ledger unreadable/invalid/reopen mismatch 为 STOP，不点击原文。不得缓存旧 fold 后另开写事务。

7.2 reducer

  • baseline_floor=max(all BASELINE_ESTIMATE/CORRECTION_RAISE.baseline_floor)；2026-07-29 首次必须 >=3，证据 ref 为中国中免任务。
  • confirmed=baseline_floor + count(unique idempotency keys terminal CONSUME_CONFIRMED)；uncertain=count(...CONSUME_UNCERTAIN)；active=count(RESERVE without exactly one terminal)。
  • safe_available=max(0,27-confirmed-uncertain-active)；APP 可见剩余若可信，则 app_consumed=30-visible_remaining，有效 confirmed floor 取本地与 APP 更保守者；APP 不可信不降低本地值。
  • RESERVE 只在 safe_available>=1、同 key 无 terminal/active 时写入。写入并 reopen 验证前不得点击。
  • CONSUME_CONFIRMED/UNCERTAIN/RELEASE 必须引用 active reservation 并使其恰好终结一次；重复相同请求返回原 event，不追加。
  • correction 只提高 baseline 或以明确 ref 把残留 reservation终结；禁止负 confirmed/uncertain、降低 baseline 或删除历史。

7.3 崩溃/竞争测试

必须用两个真实测试进程竞争最后一个 safe slot，唯一一个 RESERVE 成功；覆盖锁 timeout、append 前崩溃（无行）、append 后 fsync 前/后、reopen mismatch、同 CLI 重放、同 handoff 不同 payload 冲突、残留 reservation、release/confirmed/uncertain replay、baseline>=3、correction raise、跨日 ledger、APP 值更保守。所有测试用临时账本，不接 APP、不消耗额度。

8. 错误、终态、exit code 与 precedence

precedence 从高到低：LIVENESS_UNKNOWN/STATE_UNCERTAIN -> ACCESS_CONTROL -> TIME_BUDGET -> QUOTA -> INPUT -> ENVIRONMENT -> AMBIGUOUS_MAPPING -> VALIDATION -> INTERNAL -> PARTIAL/SUCCESS。高优先级证据不得被后续低优先级覆盖。

terminal status stop/error family exit
SUCCESS 全部 requested item P10 success 0
PARTIAL_SUCCESS 至少一个 success，存在非 quota/time 的已知 gap 2
TIME_BUDGET_STOP deadline/late I/O/subprocess timeout 10
PARTIAL_QUOTA_STOP safe_available 不足且有有效子集 11
BLOCKED_INPUT task/schema/replay contract 12
BLOCKED_ACCESS_CONTROL login/CAPTCHA/paywall/subscription/permission 13
BLOCKED_ENVIRONMENT device/package/cache/tool/lock/liveness known failure 14
BLOCKED_AMBIGUOUS_MAPPING cache/candidate/final identity 多义 15
VALIDATION_FAILED PDF/hash/page/manifest/package validation 16
INTERNAL_ERROR 未分类异常，证据保持 null 20
STATE_UNCERTAIN child/file/quota liveness 或事实未知 27

成功子集存在时，TIME/QUOTA/ACCESS/STATE_UNCERTAIN 仍保留该高优先级 terminal，不降为 partial。CLI 捕获裸异常为 INTERNAL_ERROR/20；任何 terminal 中 status/exit_code/stop_code/blocker 必须互相符合本表。

9. Manifest/delivery/timing/terminal 发布规则

  • PDF/manifest/quota 是正式不可变证据；manifest 使用固定 34 列，单锁 read/validate/idempotency→append/fsync/reopen，row_id replay 同整行返回已有；冲突 STOP。
  • delivery.md 只列元数据、文件路径、选择理由、状态、缺口与额度摘要，不含正文/结论；其源数据必须来自已验证 model，不从文件名猜。
  • timing_manifest.csv 固定 12 列，所有已进入阶段均有一行，未进入阶段不造行。
  • terminal JSON 是 package 最后一个可选持久化对象；无剩余 close budget 时只向 stdout 输出严格 JSON，并标 terminal_path=null,terminal_present=false。工具不发送 Codex/网络消息。
  • 所有正式输出记录实际 bytes/hash 到运行 receipt；不以 hash 匹配替代语义验证。

10. 测试与性能总体

10.1 L0/L1/L2（零真实 trigger）

  1. L0：py_compile、import、禁止 API/shell/credential 静态扫描。
  2. L1：标准库 unittest 覆盖全部 schema/交叉约束、candidate/cursor、Budget/ProcessSupervisor、quota reducer/并发、atomic publish/package matrix、manifest/terminal 与错误映射。
  3. L2：fake ADB + 合成 PDF + 临时 NTFS 目录，真实启动可控 helper child 测 hang/kill/wait/stdout overflow；dry-run 必须 real_adb_action_count=0,trigger_count=0,real_quota_write_count=0。
  4. 实现复审前必须提供 test case→requirement→result trace matrix；失败可在 L0/L1 范围修复重跑，保留失败记录，不需逐次管理 A001。

10.2 真实性能计划（最多 10 个 distinct trigger）

在第一次真实 reserve 前生成并锁定 performance_plan.json：10 个 primary item + 最多 3 个 no-trigger alternate；字段固定 plan_id,created_at_utc,slot_id,mode,batch_id,item_order,query,expected_report_identity,external_exclusion_allowed,selected_from_readonly_discovery。该计划的实际 bytes/hash 写入执行日志，之后不替换已触发 slot。

固定总体：

slots mode 计入单份样本 trigger 上限 批量角色
PERF-S01..PERF-S06 6 次 collect-one 6 6 无
PERF-B01-I01..I04 1 次同 query collect-batch 的 4 个 item 4 4 I01=首份，I02-I04=增量
PERF-A01..A03 预登记 alternate 仅替代 trigger 前 external-excluded primary 合计仍不得超过 10 保持被替代 slot mode

因此批量每个 item 同时是一个真实单份样本，正式 PASS 分母固定为 10，distinct trigger 最大也是 10；不得为了凑 PASS 触发第 11 份。alternate 仅在 reserve/点击前出现有证据的 external blocker 时替换，且被替代 primary 永久标 EXCLUDED_PRETRIGGER_EXTERNAL。

10.3 纳入、排除与统计

  • slot 在 preflight 后第一次成功 RESERVE 时进入 SLA population；从 task observed 到该 item terminal 是单份总耗时。任何 TIME_BUDGET_STOP、internal、validation、mapping、quota-state failure 都保留在分母并令 performance acceptance 失败，不能删样本。
  • 可排除项只有在 RESERVE/点击前确认的：登录/验证码/付费/权限、模拟器离线、APP 服务不可用或报告已不可访问；必须有截图/UI dump/process receipt，且使用预登记 alternate。触发后才出现的外部问题仍计 SLA failure。
  • collect-batch I01 从 batch request observed 到 I01 terminal；I02-I04 增量从前一 item terminal monotonic 到本 item terminal。每个 item 也记录自身 start-to-terminal。
  • median：10 个总耗时排序后第 5/6 平均；nearest-rank P90：排序第 ceil(0.9*10)=9 个。任何计入样本非成功、任何验证项失败或样本少于 10，整体只能 PERFORMANCE_FAILED 或 INSUFFICIENT_PERFORMANCE_SAMPLES。
  • PASS 必须同时：10/10 item success；每份 magic、remote/local bytes/hash、openability、page_count、manifest、quota 全通过；median<=480000ms；P90<=600000ms；B01-I01<=600000ms；I02-I04 每份 incremental<=240000ms；trigger_total<=10；confirmed+uncertain+active 永不超过 27。
  • 当日安全额度不足以做完时保留已完成样本并 INSUFFICIENT_PERFORMANCE_SAMPLES 顺延到次日新 ledger；不同日期样本可合并，但每个 slot 仍唯一、每日日限独立，统计不可重置失败 slot。

11. 实施顺序与验收矩阵

设计 PASS 后按以下顺序实施：

  1. models/budget/process + schema/child tests；
  2. quota 原子 reducer + 双进程测试；
  3. candidate/scan checkpoint + fake UI 测试；
  4. archive staging/publish/recovery + crash injection；
  5. manifest/delivery/timing/terminal + package matrix；
  6. CLI 集成与 fake ADB dry-run；
  7. 开发自检与独立实现复审前置检查；
  8. 真实 10-trigger 性能计划、执行、证据与最终独立复审。
blocker V002 closure 强制测试
01 第 2–3、8 节 API/schema/call graph/exit schema/order/null/extra-key/typed error
02 第 5 节 observed→monotonic、Job child、bounded I/O hang/kill/lock/late copy/hash/fsync/terminal
03 第 4 节 provisional/confirmed/checkpoint mismatch/duplicate/detail fail/补扫/漂移
04 第 6、9 节 staging+hardlink+closure 每边界 crash、冲突、duplicate、恢复
05 第 3.5、7 节 atomic quota/replay 双进程、崩溃、重复、残留、跨日
06 第 10.2–10.3 节固定 6+4 population external exclusion、failure inclusion、median/P90

实现不得以跳过 hash、页数、manifest、quota、access-control 或 terminal closure 换取 SLA。开发员只做实现与自检，最终由 dev.reviewer.ana.cai 独立审核。

12. 当前状态

PENDING_INDEPENDENT_DESIGN_REREVIEW。

V002 复审 PASS 前，候选源码/测试/额度账本仍不存在；不得运行 Python、ADB、慧博 APP、真实或合成采集。当前真实 trigger 增量=0，2026-07-29 已知外部基线仍按至少 3 保守处理。