FinEvidence · 金融证据工作台

打开在线工作台 · 量化验证与首轮失败 · 完整本地运行／模型配置 · 深圳／香港企业调研与两轮设计检查

选择公司与年度 → 检索证据／复核财务指标 → 打开原文核对 → 导出审查记录／可读简报／复算交接包 → 接收者重新核验。在线版本直接在浏览器工作；本地版本使用共享 Python 逻辑并可调用真实模型选择受限工具。

git clone https://github.com/leon1111-wgl/finevidence.git
cd finevidence
python3 -m finevidence.server
# 本地模型版：python3 scripts/start_model.py（终端隐藏输入密钥）

打开 http://127.0.0.1:8765。仅需 Python 3.12，macOS/Linux；核心运行无第三方 Python 包。公开语料为四份明确标识的虚构报告；模型接入成功也不意味着真实财报质量已验证。

可实际体验	交付边界
官方资料目录与本机文件版本识别	两份金蝶历史业绩公告；hash/字节一致不等于事实、人审或许可核验
本机 PDF 预检、物理页文字、指纹与待核验记录导出	5 MiB/120 页；不上传、无 OCR，提取不等于真实事实核验
可选本机审核意见、持久记录与撤回	独立本机凭据、100 条上限；非组织身份认证或财务事实准入
PDF 金额草稿、原页对照、来源绑定导出与接收恢复	最多 20 条待核验记录；非自动抽取、非已审核事实，不用于正式计算
待审草稿缺项／声明冲突检查、原位修订、检查清单导出	精确声明分组；无提示也不代表已核验，来源许可和人审身份仍待完成
原文检索、公司／年度筛选、来源指纹	英文 BM25，合成页
毛利率、收入同比、百分点变化及逐项输入	Python Decimal；浏览器 BigInt 对照，非模型口算
本机模型选工具、调用轨迹、失败拒绝	晨涧云 DeepSeek 首轮 7/8 合成任务通过；密钥只在后端进程
原文核对、备注、刷新恢复、JSON 导出	浏览器个人记录，非认证审批签名
可读 HTML 证据简报、原文跳转与打印样式	同一核查快照；合成资料、未经认证，非复算包或真实 PDF 草稿
复算交接包、选入文件核验、具体字段差异与报告下载	18/18 合成单点差异识别，10/10 正常控制；不认证作者／审批
GitHub Pages 和完整本地界面	公网页不包含模型密钥；本地 API 不开放公网

新增：本机审核留存与撤回 · 草稿检查与修订 · 官方资料入口与版本识别 · PDF 财务草稿工作流 · PDF 预检边界与复跑 · 金融证据交接的两轮竞品取舍 · 复算协议、实际数据流与量化复跑。

企业工程是验收方向。本项目未宣称银行生产使用、真实报告准确率、组织级访问控制或服务 SLA。具体已运行证据和未完成边界见 STATUS。

---

Python CLI 与既有能力

An enterprise-oriented financial evidence application: trace source passages, review facts and build bounded AI workflows. Currently implemented: source-checked offline retrieval, synthetic gross margin, annual revenue growth and margin percentage-point change, with optional read-only SQLite facts. The workbench and bounded model-selected tools are available as described above. Real-report ingestion and authenticated human fact review remain tracked work.

Run the current version

Python 3.12 on Linux/macOS; the Python CLI has no third-party runtime dependencies. The browser PDF preflight vendors pinned PDF.js under its Apache-2.0 license. Imports require the POSIX locking backend; unsupported platforms fail closed rather than importing without a lock.

git clone https://github.com/leon1111-wgl/finevidence.git
cd finevidence
python3 -m venv --without-pip .venv
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m finevidence import aurora_2024.json harbor_2024.json
.venv/bin/python -m finevidence query "revenue" --company "Aurora Orchard" --year 2024 --top-k 1 --json
.venv/bin/python -m finevidence calculate gross-margin --company "Aurora Orchard" --year 2024 --json
.venv/bin/python -m finevidence import aurora_2023.json harbor_2023.json
.venv/bin/python -m finevidence calculate revenue-growth --company "Aurora Orchard" --year 2024 --json
.venv/bin/python -m finevidence calculate gross-margin-change --company "Aurora Orchard" --year 2024 --json

The offline TLS fault tests also require the system openssl command to create temporary loopback certificates; no model API key or external provider is used. See provider deadlines.

For a human-readable result, omit --json. A repeat import skips identical files. Filtered searches never fall back to other companies or years.

.venv/bin/python -m finevidence query "lamps" --company "Aurora Orchard" --json

The second query returns NO_MATCH, an empty citations list and answer: null.

What is implemented

• Four clearly marked SYNTHETIC documents: two fictional companies across 2023/2024, eight synthetic pages, sixteen paragraphs when all are imported.
• Bounded JSON ingestion, path containment, regular-file checks, duplicate/conflict detection and atomic snapshot writes protected by a full-operation import lock.
• Page-preserving paragraph chunks, source IDs and import-time source SHA256.
• English BM25 retrieval with exact company/year metadata filters; source/snapshot equality checked before filtering and deterministic ranking.
• A shared workflow and JSON response contract with request ID, status, original excerpts, citations and limitations.
• Eight typed synthetic facts, explicit units/period/currency/basis/scope, original-source rechecks and deterministic Decimal gross margin, revenue growth and margin percentage-point change.
• An explicit synthetic SQLite snapshot builder and parameterized, read-only lookup used by all three calculations; JSON remains the reference backend.
• Source-linked regression tests; GitHub Actions records results for each commit on Linux and macOS with Python 3.12.

All companies, amounts and statements in the sample corpus are fictional. page_kind=synthetic is not a PDF physical page. Engineering tests do not establish real financial question-answering quality.

Response contract

schema_version, trace_id, mode, status, answer, claims, citations, calculations, limitations.

Each citation contains its document/chunk identity, filename, source SHA256, company/year, page kind and exact excerpt; retrieval citations also contain a score. Retrieval-only mode leaves answer null and both claims and calculations empty. BM25 scores are ranking signals, not confidence probabilities. Citation structure does not prove semantic support.

--json provides structured runtime errors, including missing/invalid index, invalid query and filter values. Invalid command syntax (unknown flags or non-integer argparse arguments) uses the standard CLI usage error on stderr. Successful retrieval and no-match return exit code 0; invalid input or source/index failure returns 2.

Synthetic financial calculation

The calculate gross-margin command requires imported source documents and an exact company/calendar-year selection. Aurora Orchard gives 36 million / 120 million = 0.3, displayed as 30.00%; Harbor Lantern gives 25.00%. Omit --json to see the inputs, formula and original paragraph in the terminal.

calculate revenue-growth --company "Aurora Orchard" --year 2024 compares 2024 to 2023. Both reports must be imported. The formula is (current_revenue - prior_revenue) / prior_revenue: Aurora gives (120 - 100) / 100 = 20.00%; Harbor gives (80 - 100) / 100 = -20.00%. The result contains both facts, both source citations, normalized inputs and the absolute currency change. Growth needs revenue facts only, not gross profit.

The JSON mode is synthetic_calculation. It includes typed facts, exact string-encoded normalized values, a deterministic calc_id, input fact IDs, formula, explicit ratio or percentage-point unit, rounding policy, citations and a templated synthetic answer. This is a fixed workflow, not model inference. Replaying identical facts and policy retains the calculation ID and gets a new request ID; no history is persisted.

Values must be bounded fixed-point decimal strings, not floats, exponent notation, null or NaN. Explicit scales of 1, thousand, million or billion are normalized before division. For gross margin, company, dates, report type, currency, accounting basis and consolidation scope must agree. Zero revenue returns ZERO_DENOMINATOR; negative revenue is outside the current policy and returns NEGATIVE_REVENUE; negative gross profit is allowed. Gross-margin and revenue-growth division uses an isolated 50-significant-digit Decimal context; only display percentages are quantized to two decimals using half-even rounding. Recurring decimals are precision-limited, not claimed exact.

Facts are authored test fixtures (verification_status=synthetic_fixture, verified_by=null), not human-verified financial facts. The loader checks the original bytes against the imported snapshot and fact hash, report year/company, and exact page paragraph. The version-controlled manifest is trusted for numeric transcription; these checks do not independently establish semantic correctness or authenticate a coordinated edit of all files. Real/human-verified statuses are refused until a review workflow exists.

Growth requires adjacent complete calendar years with matching company, currency, basis and scope. Leap years are supported; non-calendar fiscal years, quarters and nonadjacent years are refused. A zero prior revenue returns ZERO_DENOMINATOR, a negative prior returns NEGATIVE_BASE, and negative current revenue returns NEGATIVE_REVENUE. Zero current revenue with a positive prior is a valid -100% change. A percentage-point margin change is a separate operation described below.

calculate gross-margin-change --company "Aurora Orchard" --year 2024 compares the two margins: (36 / 120 - 25 / 100) * 100 = 5.00 pp. This means five percentage points, not 5% relative growth; Harbor gives -5.00 pp. The result includes four input facts, two source citations, both component margins and unit=percentage_points. Both revenues must be positive, while negative profits remain valid. Current/prior years must be adjacent complete calendar years with matching company, currency, basis and scope. No missing operand is inferred.

Margin change uses normalized cross-products in an isolated 100-digit Decimal context, then rounds only the final display to two decimals. It does not subtract the two rounded percentage displays or the 50-digit component ratios. This preserves small differences between nearly equal margins. Its policy and all four fact records determine the calculation ID; recurring results remain precision-limited.

Missing operands return FACTS_NOT_FOUND rather than falling back to another company/year. Invalid manifests, incompatible facts, unverified facts and source drift have separate error codes and return no answer/calculation (exit 2). Read-only SQLite lookup is available through the explicit backend below. See the calculation contract.

Read-only SQLite fact snapshot

After importing all four sources, build a new snapshot and select it explicitly:

.venv/bin/python -m finevidence build-facts --json
.venv/bin/python -m finevidence calculate gross-margin-change --company "Aurora Orchard" --year 2024 --fact-store sqlite --json

The default is --fact-store manifest. Both backends preserve facts, source checks, Decimal results and calculation IDs; the response identifies which backend was used. SQLite lookup uses bound values and a read-only connection. Database failure never falls back to JSON. The build validates every synthetic fact/source and refuses to overwrite an existing data/facts.sqlite; preserve and move an old snapshot before explicitly rebuilding. A later manifest edit does not silently update the snapshot.

Build JSON responses retain mode=synthetic_store_build and fact_store=sqlite_snapshot on both success and runtime failure. For example, repeating the build returns FACT_STORE_EXISTS with exit 2 and no financial result; it is still a build operation. mode identifies the operation, while status identifies its outcome.

This is a small local snapshot (1 MiB / 32 facts), not human fact review, a SQL Agent or a live multi-user database. Missing/corrupt snapshots, unsupported schemas, lock contention and source drift fail explicitly. See snapshot lifecycle, failure contract and tests.

Code map

File	Responsibility
finevidence/cli.py	CLI parsing and presentation
finevidence/workflow.py	Shared query workflow, filters and response contract
finevidence/documents.py	Source validation, snapshot and page-preserving chunks
finevidence/retrieval.py	Tokenization and BM25 scoring
finevidence/facts.py	Typed fixture validation, selection and original-source checks
finevidence/fact_store.py	Checked snapshot publication and parameterized read-only fact lookup
finevidence/finance.py	Comparable-input validation and Decimal financial operations
tests/test_cli.py	Real CLI integration and boundary tests
tests/test_fact_store.py	Snapshot lifecycle, read-only boundaries, failures and backend parity
tests/test_finance*.py	Literal arithmetic oracles and source-linked calculation boundaries
tests/test_margin_change*.py	Percentage-point arithmetic, comparability, four-fact and two-source CLI lineage
tests/test_growth*.py	Annual-comparison arithmetic, policy boundaries and two-source CLI lineage
tests/test_import_concurrency.py	Real-process contention, retry, crash-boundary and lock-input tests
tests/test_retrieval_integrity.py	Source/snapshot drift, including false empty results from altered metadata

The generated data/index.json and stable data/index.json.lock are ignored by Git. It is an import snapshot; source edits do not silently replace existing records. To intentionally rebuild, back up the index and re-import the sources. Queries do not write history.

The offline JSON index has a 1 MiB (1,048,576-byte) UTF-8 storage limit, including formatting and its final newline. Both reading and writing enforce this limit: oversized input or a batch that would exceed it returns INDEX_LIMIT without replacing the existing index. Nonregular index files and broken index links return INDEX_INVALID; a genuinely absent index retains INDEX_MISSING for queries and can be created by import. On POSIX, nonblocking open followed by descriptor type validation rejects a FIFO without waiting for a writer.

Isolated Unicode surrogate characters in source text, stored document metadata and financial fact text are rejected; valid non-BMP characters are preserved. Financial text validation returns INVALID_FACT before calculation or serialization. Invalid source filenames retain INVALID_PATH, as do source link cycles. These input checks preserve the original text rather than dropping bad characters. See input boundaries and regression evidence.

Query text and optional company filters must also contain valid Unicode scalar values. The shared retrieval entry rejects invalid text before reading sources, with INVALID_QUERY or INVALID_COMPANY; direct search calls validate query text too. This prevents malformed POSIX argument bytes from producing invalid UTF-8 JSON or a serialization crash. Error messages do not echo the rejected value. Valid text is preserved, including non-BMP symbols; English lexical-query rules and exact company matching still apply.

Queries now re-read every indexed original before applying company/year filters. They compare complete documents, including metadata, pages and byte hash, and use those same validated objects for retrieval. Changing only snapshot text, year, company, page order or hash returns SOURCE_MISMATCH, even if the changed metadata would otherwise hide all hits. Missing/nonregular sources return SOURCE_ERROR; escaping source links return INVALID_PATH. No stale-answer fallback or automatic index repair occurs. See retrieval integrity.

The original 2024 source bytes are unchanged by this increment. Import the two additional 2023 files to enable comparison. If an older source/index predates the explicit financial-period wording, preserve the old index outside the checkout and re-import; do not patch hashes to bypass checks.

Concurrent import and retry

The import lock covers reading the index, validation, merging and atomic replacement. A second overlapping import returns INDEX_BUSY (exit 2) without writing; retry the same command after the active import finishes. The retry re-reads the committed index, so different documents are retained, identical imports are skipped, and conflicting versions still return IMPORT_CONFLICT. There is no automatic waiting or retry loop.

The empty data/index.json.lock file normally remains. Its presence does not mean a live process holds the lock; do not delete or replace it while writers might run. It is a separate stable file because index.json itself is replaced during publication. Malformed lock objects and lock acquisition errors fail closed. Queries still read complete committed snapshots without taking the writer lock.

Actual process-kill tests cover before and after publication. A kill can leave index.*.tmp; those files are ignored as uncommitted data and are not automatically deleted. A commit may survive even if its process dies before printing success; retry is idempotent. These are process-interruption checks, not power-loss durability or distributed recovery. See import concurrency and recovery limits.

Engineering direction and limits

The business goal is to help analysts review document evidence and reproducible financial calculations. The design favors a modular Python application, deterministic tools and a bounded single Agent. See architecture, roadmap, status, review queue and hiring-requirement mapping.

This is not a production banking system, investment recommendation engine or trading system. There are no live users, uptime promises, real-report accuracy claims or production compliance claims. The default workflow and CI make no paid model calls; the earlier explicitly authorized live run is recorded in EVALUATION. Company/year filters are not authorization. The request ID is not full persistent tracing. Cooperating imports on a supported local filesystem now reject contention with INDEX_BUSY and support explicit retry. Distributed writers, cryptographic snapshot authenticity and multilingual/semantic retrieval are not supported.

The final interface pass targets a restrained enterprise research workspace: clear typography, neutral colors, readable tables, source review and understandable failures. It will be evaluated in a real browser after the underlying workflow is complete.

Contribution transparency

Implementation and documentation have been assisted by Codex. Automated tests show observed program behavior, not the author's independent mastery. See contributions. Personal build/interview notes are maintained separately from this public code repository.

PDF准备流程支持本机原页版面对照：选择物理页、放大核对表格、回到待核验草稿；不上传文件或自动批准财务事实。

已导出的待核验草稿可在重新选择同一 PDF 后接收并恢复到列表：先核对指纹、页码、摘录和金额，再显式替换；错误不覆盖旧草稿。同一文件改名可接收，所有记录仍待审核，不进入正式计算。

For a stopped private review store with a hot rollback journal, use the copy-only recovery procedure. The original database/journal stay intact; recovery produces a separate checked directory for explicit selection. This is not automatic failover or financial approval.