Next-Gen Zoning Extractor / V2.0

文件、GitHub 与云端架构

一份面向组员和非技术协作者的结构说明：代码在哪里、项目文件放哪里、GitHub 如何协作、Cloud 如何在电脑关机后继续工作，以及各目录到底负责什么。

当前 GitHub 基线main @ 90400fd6
当前应用版本V2 / app/2.0.0
核对日期2026-08-02
代码与规则
GitHub 仓库V2 源码、Schema、协议、测试、Agent 规则、文档与流程图
→
PR + GitHub Actions每次改动独立分支；确定性测试通过后合入 main
真实项目数据
外置 V2_RUNTIME法规 PDF、报批/审批文件、Gold、运行回执、模型答案与 HTML 报告
↔
Google Drive团队共享的 projects 镜像；不保存缓存和凭据
云端执行
Codex Cloud / Codespaces手机发起任务、写代码、跑确定性测试、提交 PR
→
A100 / Qwen（后续）真实 12 次 Answerer、批量城市与重计算；结果冻结后回传 Judge
最重要的边界：GitHub 管“程序如何工作”；Drive 和 V2_RUNTIME 管“程序在什么项目上工作”。法规、Gold、答案、凭据和缓存不进入 Git。

01. GitHub 仓库根目录

团队首先需要认清的文件地图
目录主要职责谁会使用
app/现役、按版本冻结的应用包。当前只看 app/2.0.0/；新功能应进入后续版本，而不是散落在根目录。开发者 / Agent
AGENT/团队 AI 协作说明、路径规则、Cloud/手机说明和接力单。队友的 Codex 先读根 AGENTS.md，再读这里点名的接力单。Codex / Claude
docs/论文、汇报、历史研究交付、项目动态地图与 docs 台账。它是知识和状态说明，不是运行代码仓库。全组
archive/旧 V1 的归档索引、冻结 Git tag 和回放说明。旧代码不在现役目录重复保存，需要时通过 tag 恢复。复现 / 审计
config/外置 workspace 的示例配置：Windows、Codespaces、Codex Cloud 各有一份路径合同；真实凭据不放这里。环境配置
governance/架构政策和边界规则，防止 V1 旧目录、运行数据或错误 Skill 重新混入 V2。CI / 审查
probes/小型、数据化的验收样例与城市探针定义；不保存大型 PDF、缓存或城市专用程序。测试
tools/架构检查、Drive 同步等跨版本工具。应保持通用，不承载某个城市的答案。开发 / CI
visualization/架构图、流程图及其 SVG/PNG/HTML 说明，用于演示和论文表达。汇报 / 产品
.github/GitHub Actions。验证架构、release lock、Cloud 脚本和 62 项确定性测试。GitHub
.devcontainer/GitHub Codespaces 启动环境：安装 V2、rclone、外置 runtime 并自动测试。Codespaces
.codex/Codex Cloud 的 setup/maintenance 脚本。云端每次创建或恢复容器时复现同一 V2 环境。Codex Cloud
tmp/本地临时区。可重建、不属于正式交付；不应提交到 GitHub。本机临时
入口顺序：00_START_HERE.md → AGENTS.md → docs/项目动态地图.md → 任务接力单 → app/2.0.0/README.md。不要从文件数量最多的目录开始扫。

02. app/2.0.0：现役程序内部

版本包、三条业务链与公共底座
app/2.0.0/ ├─ components/ 组件注册表、迁移锁 ├─ protocols/ A-F 等实验协议 ├─ schemas/ Question/Gold/Answer/Judge 合同 ├─ skills/ 仅 Gold 与 Report 两份权威 Skill ├─ input/ 三类 PDF 的角色与访问规则 ├─ tests/ 确定性、边界和集成测试 └─ src/zoning_v2/ ├─ application/ CLI 与跨域编排 ├─ platform/ 输入、Artifact、Provider、缓存 └─ domains/ ├─ d01_question_gold/ ├─ d02_answer_modules/ └─ d03_judge_evaluation/

components / protocols / schemas / input

前三类分别登记组件、实验流程与数据合同；input 规定法规、报批/审批材料和 Gold reference 的角色与读取权限。代码、合同和 release lock 必须同步。

skills

V2 只保留两份可复用工作流：结构化 Gold 与评测报告。Question、Answerer、Judge 是注册组件，不再伪装成 Skill。

tests / pyproject / release.lock

tests 验证合同与边界；pyproject.toml 定义安装和命令；release.lock.json 锁定版本构成。现行基线为 57 通过、5 跳过、0 失败。

01 Question / Gold

  • fact_extractor：从报批/审批材料抽事实
  • question_generator：由 LLM 把事实编译成问题
  • question_builder：生成并校验 QuestionSpec
  • gold_builder：绑定私有标准答案
  • gold_regulation_crosswalk：对应法规页码、章节和 chunk
  • gold_legal_reconciler：处理适用性、冲突和映射失败

02 Answer / Modules

  • module_1_extract：PDF 转 chunk/table
  • module_2_retrieve：相关性检索
  • module_3_legal_priority：法律优先级
  • fusion：合并 2+3
  • slot_router：按 required slots 逐槽检索
  • module_4_evidence_gate：检查证据闭合
  • evidence_pack_compiler：物化 A-F 证据包
  • answer_job_compiler：编译可恢复作答任务
  • answerer：Gold-blind 作答

03 Judge / Evaluation

  • primary_judge：读取冻结答案与 sealed Gold
  • metric_compiler：编译五项指标
  • report_renderer：输出论文式 HTML
  • dag.py / workflow.py：顺序、检查点与失败恢复
  • A-F 是六种证据输入，不是六个 Module
  • Gate、Answer 和 Judge 结论必须分开显示
源码入口：application 负责 CLI 与跨域编排，platform 提供输入、Artifact、Provider 与缓存，__main__.py 启动程序；__pycache__ 只是自动缓存，可忽略。Module 2/4 的冻结核心只能通过新适配组件扩展。

03. V2_RUNTIME：真实项目与运行数据

仓库外、可同步、不能混入 Git
V2_RUNTIME/ ├─ workspace/ │ ├─ artifact_store/ 内容寻址公共产物 │ └─ projects/ │ ├─ fremont-centerville-plaza/ │ └─ livermore-3541-east/ ├─ cache/ 可重建缓存 ├─ temp/ 临时目录 ├─ config/ 私有运行配置 ├─ handoff(s)/ 跨机器冻结包与接力资料 ├─ source_staging/ 原始资料暂存 └─ reference_library/ 城市/项目参考索引

为什么必须外置

PDF、Gold、模型答案和回执会快速膨胀仓库，也可能包含私有项目事实。外置后，代码可以公开审计，数据仍按项目权限管理。

  • Git：版本、逻辑、合同
  • Drive：团队项目资料与报告
  • 本地/A100：缓存、模型和重计算

每个项目的标准目录

workspace/projects/<project_id>/ ├─ inputs/ │ ├─ files/ 人工投放原始 PDF │ │ ├─ zoning document/ 法规原文 │ │ ├─ project document/ 申请书、图纸、项目说明 │ │ └─ gold reference/ Staff Report、批准文件、人工核对资料 │ ├─ regulations/ 程序生成的法规 hash 冻结副本 │ ├─ application/ 程序生成的项目材料冻结副本 │ ├─ gold_sources/ 程序生成的私有参考冻结副本 │ └─ manifests/ 输入清单与 SHA-256 ├─ cases/ 问题、事实台账、私有 Gold 绑定 └─ runs/ Module、A-F、Answer、Judge、Metrics、Report
输入角色Question / GoldModule 1-4 / AnswererJudge
法规原文可读可读可读
项目报批材料可读仅题目公开事实可读
Gold reference私有可读禁止答案 hash 冻结后
一次预处理，多次答题：同一法规的 Module 1 结果和 Module 3 可复用；换题时只重跑与问题相关的 Module 2、Fusion、Router/Module 4 与 Answerer。

04. GitHub 与云端协作

电脑关机后，任务仍可继续
手机 / 桌面选择 Cloud 环境，写任务提示词
Codex Cloud从 main 克隆；读 AGENTS 与接力单
独立分支只修改白名单；提交 Draft PR
GitHub Actions架构、锁、Cloud 脚本、测试
main通过审查后合并，成为团队真源

Codex Cloud：Agent 主导

  • 环境：Zoning V2 Cloud
  • Setup：bash .codex/cloud/setup.sh
  • Maintenance：bash .codex/cloud/maintenance.sh
  • Agent 阶段网络默认关闭
  • 适合手机发任务、看 diff、审 PR

GitHub Codespaces：终端主导

  • 从 main 创建
  • .devcontainer/ 自动安装 V2 和 rclone
  • 适合交互终端、Drive 同步、手动检查
  • 手机浏览器可用，但不如 Cloud 对话直观

Google Drive：团队数据

  • 路径：Zoning Code Archive/V2_RUNTIME/workspace/projects
  • 保存法规、报批/审批、私有 Gold、报告
  • 按 project_id 与本地目录一一对应
  • 只用 copy 同步，避免误删

A100 / Qwen：高算力执行

  • Module 结果只生成一次并冻结
  • Qwen 分别读取 A-F，运行 12 次 Answerer
  • 答案 hash 后回传 Codex Judge
  • 模型、embedding 和大缓存不进 Git/Drive
Module 2 接力
AGENT/handoffs/260802_V2_Module2混合检索_Kaiwen-to-Team.md
新建混合检索适配器；保留 BM25 保底与 cross-reference，不改冻结核心。
Module 4 接力
AGENT/handoffs/260802_V2_Module4证据闭合_Kaiwen-to-Team.md
新建逐义务 Gate Adapter 与定向补检索；Gate PASS 不冒充 Judge Coverage。
飞机上的现实边界：有网络时可从手机继续 Cloud；没有网络时只能提前启动任务，恢复联网后再审查。Remote 依赖本机保持开机，不等同于 Cloud。

05. 当前状态、权限与下一步

哪些已经可用，哪些仍是下一阶段
内容GitHubDriveCloud 临时盘A100 本地盘
V2 源码 / Schema / 测试真源不需要克隆副本部署副本
法规 / 报批 / 审批 PDF禁止共享真源按项目复制按批次复制
私有 Gold / Judge 材料禁止受控保存Judge 阶段Answerer 禁止
答案 / 回执 / HTML一般不入库选定结果任务产物批次产物
缓存 / embedding / 模型禁止不建议临时可重建主要位置
API Key / OAuth / rclone禁止禁止Secrets系统密钥
已完成V2 文件分层、三业务域、Module 1-4 接线、A-F/Answer/Judge/Report 合同、Codespaces、Codex Cloud、Drive 桥、手机入口、PR #12 云端验证。
正在接力Module 2 混合检索；Module 4 逐义务证据闭合。二者必须独立分支开发，并保留 migration lock。
下一重点最终交互产品：三类 PDF 导入、快速/研究模式、进度与错误解释、答案/Gold/Judge 对照、批次与报告入口。
后续接入A100 双卡与 Qwen Answerer、真实多城市压力测试、非技术 Launcher/EXE、正式人工 Gold 审核界面。

组员第一次打开仓库

  1. 读 00_START_HERE.md
  2. 读根 AGENTS.md
  3. 在动态地图确认任务卡号
  4. 只读对应接力单列出的文件
  5. 独立分支 + Draft PR + CI

明天从手机研究交互产品

  1. 打开 Zoning V2 Cloud
  2. 从 main 新建 Cloud 任务
  3. 使用 AGENT/CODEX_CLOUD_MOBILE.zh-CN.md 中的提示词
  4. 先做流程、页面、状态机和验收范围
  5. 不调用真实模型，不改冻结 Module
判断架构是否清楚的标准：任何人都能回答四个问题 - 代码在哪里、数据在哪里、谁能读取 Gold、一次修改怎样经过 PR 与 CI 进入 main。

相关入口：GitHub cogco1/next-gen-zoning-extractor；Codex Cloud 环境 Zoning V2 Cloud；Google Drive Zoning Code Archive/V2_RUNTIME/workspace/projects。

06. 文件夹层级导读

对应截图 1-4：从仓库外壳走到三条业务链
next-gen-zoning-extractor-v2/ 仓库：代码、合同、协作规则 └─ app/2.0.0/ 当前可发布版本包 ├─ components / input / protocols / schemas 版本构成与机器合同 ├─ skills / tests 工作流说明与验证 └─ src/zoning_v2/ Python 源码包 ├─ application/ CLI 与流程编排 ├─ platform/ 输入、Artifact、Provider、缓存 └─ domains/ 三条业务链 ├─ d01_question_gold/ ├─ d02_answer_modules/ └─ d03_judge_evaluation/

截图 1 · 仓库根目录

最外层是团队协作外壳。app 放现役应用；AGENT 放接力单；docs 放正式说明；archive 放 V1 历史；governance 和 .github 负责边界与 CI。根目录不是堆放城市 PDF 的地方。

截图 2 · app/2.0.0

这是一个可安装、可测试、可锁定的完整版本。components 登记组件，input 定义三类输入，protocols/schemas 定义流程和数据合同，release.lock.json 锁定版本。

截图 3 · src/zoning_v2

application 决定先后顺序；platform 提供公共基础设施；domains 才是业务功能。__main__.py 是启动入口，__pycache__ 只是自动生成的缓存。

截图 4 · domains

这里不是三个版本，而是三个职责域：d01 生产问题与私有 Gold；d02 只看法规并作答；d03 在答案冻结后评价。三者通过 Schema 交接，不能直接互读内部文件。

最短寻找路径：想改问题或 Gold，进 d01；想改 Module 或 Answerer，进 d02；想改指标、Judge 或报告，进 d03。想改跨域顺序，才去 application。

07. 三个业务文件夹

对应截图 5-7：逐项解释

截图 6 · d01_question_gold

  • fact_extractor：从报批/审批材料抽取项目事实
  • question_generator：由 LLM 把事实编译成自然语言问题
  • question_builder：生成并校验 QuestionSpec
  • gold_builder：建立私有 Gold 候选与封存答案
  • gold_regulation_crosswalk：把 Gold 对应到法规页码、章节和 chunk
  • gold_legal_reconciler：处理版本、适用性、冲突和缺失证据

截图 7 · d03_judge_evaluation

  • primary_judge：答案 hash 冻结后读取 sealed Gold，逐槽裁决
  • metric_compiler：将裁决编译为五项指标
  • report_renderer：生成论文式 HTML 报告
  • dag.py：描述评价任务之间的依赖关系
  • workflow.py：执行顺序、检查点和失败恢复

这里不检索法规、不生产答案；它只负责独立对账和呈现。

截图 5 · d02_answer_modules

  • module_1_extract：PDF 转 chunk/table，同一法规通常只跑一次
  • module_2_retrieve：按问题做相关性检索，换题时重排
  • module_3_legal_priority：法规效力与优先级，可跨问题复用
  • fusion：融合 Module 2 与 3
  • slot_router：把问题拆成 required slots 并逐槽检索
  • module_4_evidence_gate：检查各槽证据是否闭合
  • evidence_pack_compiler：从公共产物物化 A-F 六套证据包
  • answer_job_compiler：绑定问题、证据、provider、重复次数和预算
  • answerer：调用 Codex、Claude 或 Qwen 做 Gold-blind 作答
复用原则：Module 1、3 与公共 chunk 只生成一次；Module 2、Fusion、Router、Module 4 随问题重算；A-F 的 Answerer 必须分别运行，不能用同一答案冒充六组实验。

06. 截图导读：仓库根目录

从这里进入，但不要逐层盲扫
GitHub 仓库根目录截图
截图 01 · 本地 Git 仓库根目录。程序、协作规则、文档和历史归档在这里分层。
01 app现役、可发布的 V2 应用包。当前正式入口是 app/2.0.0。
02 AGENT团队与 AI 的协作说明、任务边界和接力单；队友动手前先读。
03 docs论文、汇报、动态地图和正式说明。它解释项目，但不承载运行代码。
04 archiveV1 历史快照与迁移说明，仅用于复现和审计，不参与 V2 主链。
05 config不同运行环境的示例配置；真实密钥与真实项目数据不得放入仓库。
06 governance目录、迁移锁和边界检查，防止旧结构或运行数据重新混入 V2。
07 probes小型验收样例与城市探针，只证明特定边界，不代表总体准确率。
08 tools / visualization通用检查、Drive 同步、架构图和报告展示工具。
09 .github / .devcontainer / .codex分别管理 CI、Codespaces 和 Codex Cloud 的可复现环境。
10 tmp可删除、可重建的本地临时文件，不应提交。
根目录文件：00_START_HERE.md 是入口；AGENTS.md 是执行规则；README.md 是项目概览；提交台账.md 记录正式变更。

07. 截图导读：app/2.0.0

一个自洽、可锁定的应用版本
app 2.0.0 目录截图
截图 02 · 当前版本包。新增正式能力应进入后续版本，而不是散落到仓库根目录。
01 components组件登记与迁移来源；回答“当前版本到底包含哪些组件”。
02 input定义法规、报批/审批材料与 Gold reference 三种输入角色及权限。
03 protocolsA-F、Gold 隔离、Answer/Judge 顺序等实验协议。
04 schemasQuestion、Gold、Answer、Judge 等 JSON 合同，是组件之间的接口。
05 skills只保留 Gold 和 Report 两项可复用工作流。
06 src真正的 Python 源码，分为应用编排、公共平台和三条业务链。
07 tests合同、边界、迁移锁和集成测试；与真实城市准确率分开报告。
三个根文件：pyproject.toml 定义安装与命令；README.md 给人读；release.lock.json 锁定版本构成与哈希。

08. 截图导读：src/zoning_v2

程序代码的三层分工
src zoning v2 目录截图
截图 03 · Python 包入口。这里按职责分层，不按城市或实验版本堆文件。
01 applicationCLI 与跨业务链编排。决定“先做什么、后做什么”，但不实现检索或 Judge 细节。
02 domains三条核心业务链：Question/Gold、Answer/Modules、Judge/Evaluation。
03 platform输入管理、Artifact 存储、Provider 接口、缓存等公共基础设施。
04 __main__.py允许以 Python 模块方式启动 V2；它把命令转交给 application。
可忽略：__pycache__ 是 Python 自动生成的字节码缓存，不是源码，也不应进入 Git。

09. 截图导读：domains

生产、作答、评价彼此分离
domains 目录截图
截图 04 · 三条业务链。编号表示流程顺序，不表示耦合成一个大文件。
01 d01_question_gold读取项目报批/审批材料，抽取公开事实，生成问题，并在私有路径建立带法规交叉引用的 Gold。
02 d02_answer_modules只依据法规运行 Module 1-4、物化 A-F 证据包，并让 Answerer 在看不到 Gold 的情况下回答。
03 d03_judge_evaluation答案冻结后才读取 sealed Gold，生成 Judge 裁决、五项指标与 HTML 报告。
隔离原则：d01 的私有 Gold 不得流入 d02；d03 只能在答案文件完成哈希冻结后启动。

10. 截图导读：Question / Gold

先有项目事实，再编问题与私有答案
Question Gold 组件截图
截图 05 · 问题与 Gold 属于同一业务域，但生成物必须分权限保存。
01 fact_extractor从 Staff Report、审批意见和报批材料提取经人工筛选的项目事实。
02 question_generator由 LLM 把项目事实编译成开发商式、条件明确的自然语言问题。
03 question_builder确定性地生成 QuestionSpec、question_id、task_type 和 required slots。
04 gold_builder把已确认事实绑定为 Gold 候选与封存答案，不允许 Answerer 读取。
05 gold_regulation_crosswalk在法规里寻找对应页码、章节和 canonical chunk，使项目事实与法规答案对得上。
06 gold_legal_reconciler处理版本、适用性、例外和冲突；无法确认的项目不进入正式准确率分母。
关键输出：公开的 QuestionSpec 与私有的 sealed Gold 成对，但保存在不同权限路径。

11. 截图导读：Answer / Modules

模块只跑必要部分，答案按 A-F 隔离
Answer Modules 组件截图
截图 06 · 现役作答链。Module 结果可复用，六组 Answerer 调用不能互相冒充。
01 module_1_extract法规 PDF 转稳定 chunk 与 table；同一法规通常只运行一次。
02 module_2_retrieve按问题做相关性检索；换题时需要重新排序。
03 module_3_legal_priority判断法律效力和条文优先级，通常可跨问题复用。
04 fusion合并 Module 2 与 3 的排序结果，生成 E 组候选。
05 slot_router把问题拆成 required slots，逐槽检索，避免多个答案挤在一个 Top-k 中。
06 module_4_evidence_gate检查每个槽位的证据是否闭合，形成 F 组；Gate PASS 不等于 Judge 正确。
07 evidence_pack_compiler从同一份公共产物物化 A-F 六套 Gold-free 证据包。
08 answer_job_compiler绑定问题、证据组、provider、重复次数和预算，形成可恢复作答任务。
09 answerer调用 Codex、Claude 或 Qwen，仅依据当前证据包生成结构化答案。

12. 截图导读：Judge / Evaluation

答案冻结后，独立评价
Judge Evaluation 组件截图
截图 07 · 评价链。这里不生产法规答案，只比较、计分和呈现。
01 metric_compiler把 Judge 的结构化裁决编译为 Correctness、Coverage、Faithfulness、Uncertainty F1 与 Consistency；不合法标签显示 N/A，不伪造零分。
02 primary_judge读取冻结答案、证据与 sealed Gold，逐槽判断缺项、错值、错单位和引用缺口。
03 report_renderer把城市、问题、Gold、A-F、Judge、耗时和 token 回执渲染成论文式 HTML。
04 dag.py / workflow.py负责评价顺序、检查点和失败恢复；它们是编排器，不是第四个评价指标。
完整闭环：项目材料生成 Question/Gold - 法规生成 A-F 答案 - 答案 hash 冻结 - Judge 对账 - 指标编译 - HTML 报告。
← MonkeyHub Institute · People