LocalRedactor / 本地脱敏框

LocalRedactor is a Windows desktop tool for privacy-first legal document processing. It combines a local language model's contextual understanding with deterministic Python document editing: the model identifies sensitive entities and proposes one mapping table, then the application validates that table and applies it once to a new copy.

LocalRedactor 是一款面向法律工作者的 Windows 本地文档脱敏工具。它把本地 AI 的 上下文理解能力与 Python 的确定性文档写回能力结合起来：模型完整阅读材料并生成一次 敏感信息映射表，程序校验映射后只执行一次替换，避免 AI 与正则反复改写造成过度脱敏。

Important

**模型能力说明：**当前版本的识别质量较依赖本地 AI 的语义理解能力。现阶段实测中， 4B 及以下小参数模型对复杂法律文书中的姓名、机构、简称继承、银行网点和账号等信息 容易出现遗漏或映射错误，不建议用于低人工复核场景。本项目不包含小模型规则补偿路线； 无论使用何种模型，脱敏结果仍应经过人工复核。

See 模型能力与使用建议 for details.

Core workflow / 核心机制

Source document
      |
      v
Local AI reads context and creates one mapping table
      |
      v
Python validates required fields, protected values, and file structure
      |
      v
Python applies the approved mapping once
      |
      v
Redacted copy + local report (source remains unchanged)

模型负责“理解和指挥”，程序负责“验证和执行”。这不是让模型重写整份文档，也不是让 正则盲目猜测实体，而是让两者在清晰边界内协作。

模型主导的单次脱敏

模型独立阅读文档并生成一次完整敏感信息映射，程序只校验字段完整性、原文是否存在及保护内容，随后执行一次精确替换。工具不使用程序规则发现实体、补全简称或生成脱敏值；复杂主体关系、同名区分和简称继承完全取决于模型的语义能力，输出仍需人工复核。

补充 Prompt

界面的“补充 Prompt（可选）”可填写本次材料特有的识别要求，例如需要重点识别的主体类型、行业简称或特殊称谓。它只补充本地 AI 的识别与映射判断，不增加第二轮脱敏；模型仍返回完整映射，程序校验后统一写入脱敏副本。金额、日期、时间、诉讼请求、案由和法律依据等保护内容不能被补充 Prompt 覆盖。

Features / 功能

• Drag files or folders directly into the desktop window.
• Word (.docx), Excel (.xlsx) and PowerPoint (.pptx) produce same-format redacted copies while preserving formatting as far as their file structures allow.
• Legacy Word .doc files are supported through locally installed Microsoft Word.
• Native and scanned PDFs, plus supported images, are read and exported as simple redacted .docx text for downstream AI analysis.
• Text files produce redacted text copies.
• Chinese and English processing profiles also switch the entire interface language.
• Connect to LM Studio or another OpenAI-compatible /v1/chat/completions API.

Current support status / 当前支持状态

• Word and text-based PDFs: the most mature workflow at present. Word creates a same-format redacted copy; PDFs with extractable text create a simple redacted Word copy.
• Images and scanned PDFs: require a vision-capable model. The LM Studio vision request path is supported, but visual reading and redaction quality still depends heavily on image quality, page layout, and model capability. This path remains under active improvement.

Privacy model / 隐私边界

Local mode: requests are sent to the endpoint you configure, normally a local LM Studio server. Original files and private mappings remain on the computer.

Online API mode: relevant document content is sent to the configured provider. This mode is not equivalent to fully local processing. Review the provider's data policy and your confidentiality obligations before using confidential documents.

API keys are stored in the local redaction_config.json. The file is excluded from Git. Public builds contain only the non-secret example configuration.

Redaction is an assistive process, not a guarantee. Always review the generated copy before disclosure or upload, especially scanned documents, handwriting, stamps, embedded images, unusual account formats, and ambiguous names.

Quick start / 快速开始

Windows release

1. Download and extract LocalRedactor-Windows-x64.zip from Releases.
2. Start LM Studio, load a text model, and enable its local server.
3. Run LocalRedactor.exe.
4. Open 模型设置 / Model Settings and enter the endpoint and model names.
5. Test the connection, save it, then drag files into 文件脱敏 / File Redaction.
6. Review the _脱敏 copy generated beside the source file.

Default LM Studio endpoint: http://127.0.0.1:1234/v1

The included model name is only an example. Select a model that is actually loaded in your local service. A vision-capable model is required for scanned PDFs and images.

Supported outputs / 输出规则

Input	Output
.docx	same-directory _脱敏.docx
.xlsx	same-directory _脱敏.xlsx
.pptx	same-directory _脱敏.pptx
.doc	Microsoft Word-backed redacted copy
.pdf	same-directory _脱敏.docx
.png, .jpg, .jpeg, .bmp, .tif, .tiff	same-directory _脱敏.docx
.txt	same-directory _脱敏.txt

When a folder is selected, output is organized in a sibling redacted folder. Source files are not intentionally modified.

Redaction responsibilities / 分工

The language model:

• reads the full available document context;
• classifies people, professionals, organizations, aliases, banks, addresses, accounts, identifiers, and other sensitive entities;
• returns exact original -> replacement mappings.

The Python application:

• validates required mapping fields and confirms the original text exists;
• protects dates, times, amounts, calculations, claims, and legal citations;
• applies the mapping once without asking the model to rewrite the document;
• writes a copy and records processing results.

Exact recognition quality depends on the selected model, visual-reading quality, and document structure. The application does not add a second program-detection route.

Build from source / 从源码构建

Requirements:

• Windows 10 or 11;
• Python 3.10-3.13 (3.12 recommended);
• Microsoft Word only when legacy .doc support is required.

git clone <repository-url>
cd LocalRedactor
powershell -ExecutionPolicy Bypass -File .\build_exe.ps1

The script creates .venv, installs missing packages from requirements.txt's equivalent build set, bundles the checked-in Tk runtime, and writes the application to release\LocalRedactor\LocalRedactor.exe.

Run tests:

.\.venv\Scripts\python.exe -m unittest -v test_redactor_core.py test_redactor_failures.py

Known limitations / 已知限制

• Formatting preservation means minimal in-place text replacement inside a copy; text length changes can still alter pagination or cell layout.
• Text embedded in images inside Office files is not currently rewritten in place.
• Visual reading requires a vision-capable model and may miss handwriting, seals, low-resolution scans, rotated pages, or uncommon symbols. Image and scanned-PDF handling is still being improved; review those outputs especially carefully.
• Password-protected, damaged, or unsupported files may fail.
• English support is available but requires further domain-specific testing across jurisdictions and document styles.
• The tool does not replace professional confidentiality review.

Security

See SECURITY.md. Never include original client documents, real API keys, redaction_config.json, or unredacted reports in an issue.

License

LocalRedactor is released under the GNU Affero General Public License v3.0. This choice is required for the open-source distribution because the application uses the AGPL-licensed PyMuPDF library. A proprietary distribution requires an appropriate commercial PyMuPDF/Artifex license and a separate review of all other dependencies. See THIRD_PARTY_NOTICES.md.