衡式 ThesisProof

衡式 ThesisProof 是一个本地优先、证据驱动的 .docx 论文交付工作台。

它不会宣称“一键完美排版”。跨平台核心负责安全扫描、模板诊断、角色与样式映射、候选文档生成和包级证据；最终分页、目录、字段与渲染必须由 Windows Microsoft Word 复核并产生 WordProofManifest。

当前状态

版本：0.2.0a1（alpha 预览），正确性基础阶段。

已经落地：

• 输入文件只读，输出默认不覆盖。
• DOCX ZIP、XML、宏、ActiveX、altChunk、外部关系与资源耗尽防护。
• 模板、内容与映射 SHA-256 绑定。
• 一致的样式候选排序；角色专用模板样式优先于 Word 通用样式。
• 同分候选标记为 ambiguous，不再伪装成高置信自动选择。
• 表格单元格、空段落、文本框与内容控件默认保留，不套用全局正文样式。
• ProjectManifest、OperationManifest、PackageEvidence 与 v1 mapping 只读迁移。
• 输出包关系图、非目标部件与移除部件检查。
• 所有自动建议均需确认；严格模式拒绝未确认映射。
• 未取得 WordProofManifest 时，交付状态固定为 word_verification_pending。
• 隔离、可恢复的包级批处理基础。
• 中文优先、分享安全、响应式、可打印的 HTML 证据报告。

尚未达到公开发布门禁：

• 60 组获授权、脱敏的真实论文验收集尚未建立。
• .NET 10 + Open XML SDK 核心、CLI 契约与 Windows authority 项目骨架已经建立；当前机器缺少 .NET SDK，且官方下载连接失败，因此本地构建验证仍待 CI 完成。
• Windows Word COM 权威链需要在安装 Microsoft Word 的 Windows 专机上验证。
• Avalonia 五步桌面、签名安装包与正式视觉系统受验收集门禁约束。

因此，当前输出只能称为“候选文档”，不能称为“可交付文档”。

证据状态

产品只使用以下状态：

• blocked：安全、映射或包级证据失败。
• decision_required：存在缺失、歧义或未确认映射。
• package_verified：包级证据通过；不代表 Word 布局通过。
• word_verification_pending：等待 Windows Word 权威复核。
• word_verified：Word 已打开、更新、重分页、保存并导出 PDF。
• signed_off：Word 证明核对完成并通过人工签核。

环境

• Python 3.11+
• 推荐使用 uv
• GUI 兼容层：PySide6
• Windows Word 权威层：可选 pywin32，仅 Windows 安装
• v2 目标核心：当前 LTS .NET + Open XML SDK
• v2 目标桌面：Avalonia

安装开发环境：

uv sync --locked --extra dev --extra gui

Windows Word 适配环境：

uv sync --locked --extra dev --extra gui --extra word

五步流程

1. 输入与安全

python -m app.main doctor \
  --template examples/template_basic.docx \
  --content examples/content_basic.docx \
  --out-dir workdir

2. 模板适配与结构检查

python -m app.main inspect \
  --template examples/template_basic.docx \
  --content examples/content_basic.docx \
  --out-dir workdir

主要产物：

• project_manifest.json
• format_profile.json
• content_structure.json
• mapping.generated.json
• readiness_result.json
• inspection_report.html

3. 映射确认

自动生成的映射默认是 proposed。使用 GUI 的“确认所有唯一建议”处理唯一候选，再逐项处理 ambiguous 与 missing。

python -m app.main gui

旧 v1 mapping 会只读迁移到 v2 内存模型，原文件不会被改写。所有旧映射均重新进入待确认状态。

4. 生成与包级验证

先生成操作清单：

python -m app.main plan \
  --template examples/template_basic.docx \
  --content examples/content_basic.docx \
  --mapping workdir/mapping.gui.json \
  --output workdir/candidate.docx \
  --manifest workdir/operation_manifest.preview.json

生成候选文档：

python -m app.main generate \
  --template examples/template_basic.docx \
  --content examples/content_basic.docx \
  --mapping workdir/mapping.gui.json \
  --out workdir/candidate.docx \
  --report workdir/validation_report.html \
  --strict

新增证据：

• operation_manifest.json
• package_evidence.json
• validation_result.json
• validation_report.html
• delivery_checklist.json
• delivery_checklist.html

候选文档只有在包级证据无 error 时才会移动到最终输出路径。

5. Windows Word 权威复核

仅在安装 Microsoft Word 的 Windows 环境运行：

python -m app.main verify-word \
  --docx workdir/candidate.docx \
  --pdf workdir/candidate.pdf \
  --proof workdir/word_proof_manifest.json

该流程强制关闭宏自动化，更新字段与目录，重新分页，保存 DOCX，导出 PDF，并记录 Word 版本、页数与哈希。Mac 运行相同命令只会产生明确的不可用证明，不会伪造成功。

批处理

批处理只接受已确认且绑定输入哈希的映射档案。每篇任务使用独立目录，包级阶段最多两个进程，Word 阶段仍需 Windows 单实例串行。

python -m app.main batch \
  --manifest batch.json \
  --run-dir batch-run

批次结果保存在 batch_result.json。再次运行相同 batch ID 会跳过已完成且证据文件仍存在的任务。

最小 manifest：

{
  "schema_version": 2,
  "batch_id": "graduation-2026",
  "max_workers": 2,
  "jobs": [
    {
      "job_id": "case-001",
      "template_path": "template.docx",
      "content_path": "content.docx",
      "mapping_path": "mapping.confirmed.json"
    }
  ]
}

真实验收集

策略与示例位于 corpus/。

python scripts/validate_corpus.py corpus/manifest.example.json
python scripts/validate_corpus.py corpus/manifest.local.json --release-gate

发布门禁要求：

• 至少 60 个案例；
• 至少 6 个院校代码；
• 20 个干净模板案例；
• 15 个手工格式参考案例；
• 10 个复杂分节案例；
• 10 个公式、图表或交叉引用案例；
• 5 个修订、批注或预期拒绝案例；
• 每个真实案例具备授权、脱敏、输入哈希与 Word/PDF 基线。

安全与隐私

• 不上传文档，不启用遥测，不默认联网。
• 报告只展示文件名，不展示绝对路径。
• 原始段落、完整 mapping 与机器诊断只出现在折叠技术附录。
• 调试目录必须位于报告目录内且不能是符号链接。
• 完整 XML 调试只在显式开启时保存，可能包含论文全文。
• 外链、嵌入对象、批注、修订、隐藏文本、custom XML 与元数据必须进入复核清单。
• 输出与 JSON/HTML 报告采用原子写入。

验证

uv run --python 3.11 --extra dev pytest -q
uv run --python 3.11 --extra dev bandit -r app core gui models scripts
uv export --frozen --no-dev --no-hashes --no-emit-project --output-file /tmp/thesisproof-requirements.txt
uvx --with "msgpack>=1.2.1" pip-audit --no-deps --disable-pip -r /tmp/thesisproof-requirements.txt

当前 Python 回归为 47 passed。CI 同时覆盖 macOS、Windows 与 Linux；私有 corpus 与 Windows Word 使用独立的可信自托管门禁。

DOCX 输出还必须使用 documents 技能提供的渲染器生成逐页 PNG，并检查所有页面。LibreOffice 渲染只能作为跨平台视觉回归，最终权威仍是 Windows Word。

项目结构

app/       CLI 与服务编排
core/      兼容期确定性引擎、证据、迁移、批处理与 Word 边界
gui/       PySide6 兼容界面
models/    v2 数据契约
corpus/    验收集 schema、策略与示例
tests/     单元、回归、安全、GUI 与证据测试
docs/      架构、安全、发布与迁移说明
dotnet/    .NET 10/Open XML 核心、CLI、Word authority 与契约测试

详细架构见 docs/architecture.md。 安全实现审计见 security_best_practices_report.md；威胁模型确认稿见 docs/security-threat-model.draft.md。