TextVeil 是一款把「秘密消息」隐藏在「看起来完全正常的文字」中的开源工具。你可以把一段普通的聊天记录、会议纪要或文章作为载体文本（Cover Text），TextVeil 会通过零宽字符、同形字替换、全半角切换、行尾空白、近义词改写等方式，把加密后的密文悄无声息地编织进去——肉眼阅读毫无异样，复制粘贴、跨 App 转发后密文依然存在；持有密码的接收方可以一键还原。
- 📵 元数据与内容同样敏感：普通聊天工具里发送一串明显的密文，本身就会引起注意；TextVeil 的密文外观就是一段自然文字。
- 🔌 不信任在线服务：同类方案往往依赖大模型在线生成、或需要上传文本到第三方。TextVeil 100% 本地运行，不联网、不留痕。
- 🧰 想要可编程、可审计的实现：纯 Python 标准库实现，核心代码量小、算法透明，可直接作为库嵌入自己的程序。
| 对比维度 | 常见 LLM 隐写方案 | TextVeil |
|---|---|---|
| 运行依赖 | 下载/调用本地或云端大模型 | 零第三方依赖，仅用 Python 标准库 |
| 生成速度 | 秒级~分钟级，受模型影响 | 毫秒级，确定性算法 |
| 载体文本 | AI 生成，措辞本身可能就是破绽 | 用户自带真实文本，自然度无可挑剔 |
| 算法数量 | 单一 | 5 种算法，覆盖字符/字形/排版/词汇四个维度 |
| 中文支持 | 普遍薄弱 | 原生支持中文载体（全半角、中文近义词） |
| 安全强度 | 取决于模型 | PBKDF2 密钥拉伸 + 流加密 + 先加密后认证（HMAC） |
| 反检测能力 | 无 | 自带 detect 取证检测命令，知己知彼 |
💡 灵感来源：GitHub 上近期走热的 LLM 对话隐写项目证明了「把对话本身变成加密信道」的价值，但其依赖本地大模型、体积庞大、英文单一且生成文本反而容易被识别。TextVeil 只借鉴这一产品思路，全部算法与代码均为独立自研，未复制任何原项目代码。
⚖️ 合规声明：TextVeil 面向隐私保护研究、数字水印、CTF 教学、记者/法务等正当的保密通信场景。请勿用于规避法定义务或掩盖违法行为，使用者自行承担一切责任。
- 👻 五种隐写算法，各有适用场景
zero-width：用不可见零宽字符承载比特，容量无上限，载体可见文本一字不改homoglyph：把拉丁字母替换为西里尔/希腊语同形字，肉眼几乎不可分辨fullwidth：ASCII 字符在半角/全角间切换，在中文排版中毫不突兀whitespace：用每行行尾的空格/Tab 编码，编辑器默认不可见synonym：近义词替换（内置英文 + 中文词对），语法完全通顺，属于经典语言隐写
- 🔐 密码保护开箱即用：PBKDF2-HMAC-SHA256（20 万轮）派生密钥，HMAC 计数器模式密钥流加密，Encrypt-then-MAC 防篡改；密码错误立即被识别
- 🔍 内置取证检测：
detect输出零宽字符、混排同形字、全角字符、行尾空白、近义词密度等指纹与 0–100 可疑度评分 - 📏 容量规划器：写入前先用
capacity计算载体最多能藏多少字节，告别盲试 - 🧩 库 + CLI 双形态：既能命令行直接用，也能
import textveil嵌入自动化流程 - 🧪 37 个单元测试：每种算法都有中英文往返、错误密码、篡改检测、CLI 端到端用例
- 📦 跨平台单文件打包：一条命令产出
textveil.pyz，Windows / macOS / Linux 任意装有 Python 3.8+ 的机器双击级运行 - 📤 输出友好：支持文件 / 标准输入输出管道 / JSON 机器可读输出，方便脚本编排
- 🌍 三语文档：简体中文、繁體中文、English 同步维护
- Python 3.8 及以上（Windows / macOS / Linux 均可）
- 无任何第三方运行时依赖，无需联网
git clone https://github.com/gitstq/textveil.git
cd textveil
# 查看支持的隐写方法
PYTHONPATH=src python3 -m textveil methods
# 查看版本
PYTHONPATH=src python3 -m textveil --version# 安装后即可全局使用 textveil 命令
pip install .
textveil --version在 Releases / 本地构建 获得 textveil.pyz 后：
python3 textveil.pyz methods# 1) 准备一段普通载体文本 cover.txt
# 2) 写入秘密（会交互式提示输入密码，输入内容不回显）
textveil hide -m zero-width --carrier cover.txt -s "今晚九点老地方见" -o stego.txt -p mypass
# 3) 把 stego.txt 通过任何聊天/邮件工具发出去——看起来就是一段普通文字
# 4) 接收方用同样的方法和密码还原
textveil reveal -m zero-width -i stego.txt -p mypass
# 输出：今晚九点老地方见| 命令 | 作用 |
|---|---|
textveil methods |
列出全部隐写方法及说明 |
textveil hide |
把秘密写入载体 |
textveil reveal |
从文本中提取并解密秘密 |
textveil detect |
取证扫描一段文本是否含隐写指纹 |
textveil capacity |
计算载体对指定方法的容量 |
全局参数 --json 可让输出变为机器可读 JSON；-i - 表示从标准输入读取，-o 省略时输出到标准输出，因此可以用管道串联。
| 方法 | 容量 | 隐蔽性 | 载体要求 | 典型场景 |
|---|---|---|---|---|
zero-width |
无上限 | 对人眼完美；专业检测器可查 | 任意 | 通用首选、长消息 |
homoglyph |
取决于拉丁字母数量 | 高（字形几乎一致） | 含英文字母 | 英文文档、代码注释 |
fullwidth |
取决于 ASCII 字符数量 | 中文语境下很高 | 含字母/数字 | 中文混排文本 |
whitespace |
等于行数 | 多数编辑器不可见 | 多行文本 | 源码、配置、邮件草稿 |
synonym |
取决于内置词对命中数 | 最高（没有任何异常字符） | 含常见近义词汇 | 要求最自然的成段文章 |
容量不够时 TextVeil 会直接报错并告诉你「需要多少比特、载体提供多少比特」，换用更长的载体或
zero-width即可。
零宽字符在屏幕上完全不可见，TextVeil 默认把密文插入第一个句读标点之后（没有标点则追加到文末）：
textveil hide -m zero-width --carrier article.txt \
--secret-file secret.txt -o marked.txt -p "$PW"
textveil reveal -m zero-width -i marked.txt -p "$PW"部分拉丁字母与西里尔/希腊字母字形几乎相同（如 a / а、o / о、C / С），保持原形记 0、替换为同形字记 1：
textveil hide -m homoglyph --carrier english.txt -s "Bob knows." --no-password -o out.txt
textveil reveal -m homoglyph -i out.txt --no-password在中文文章里出现全角字母数字非常自然，半角记 0、全角记 1：
textveil capacity -m fullwidth -i mixed_zh.txt # 先看容量
textveil hide -m fullwidth --carrier mixed_zh.txt -s "OK" -p pw -o out.txt每行末尾的一个空格表示 0、一个 Tab 表示 1，未使用的行保持干净：
printf 'first line\nsecond line\nthird line\n' > lines.txt
textveil hide -m whitespace --carrier lines.txt -s hi --no-password内置 47 对英文、42 对中文可互换近义词，保留原词记 0、换成近义词记 1，全文不出现任何异常字符，隐蔽性最高：
textveil hide -m synonym --carrier report.txt -s "buy at 21:00" -p pw -o r2.txt
textveil reveal -m synonym -i r2.txt -p pw怀疑一段文字被动过手脚？让 TextVeil 站在对手视角扫描：
textveil detect -i suspicious.txt
# 或输出结构化结果
textveil --json detect -i suspicious.txt报告包含：不可见字符清单与位置、混排同形字样本、全角字符数、带行尾空白的行号、近义词命中数、综合评分与 clean / suspicious / likely-payload 三级结论。
import textveil
cover = open("cover.txt", encoding="utf-8").read()
# 写入（返回对象同时给出占用字节/比特数，便于审计）
result = textveil.hide("zero-width", cover, "Meet at 9pm.", password="pw")
send(result.text)
# 还原
secret = textveil.reveal("zero-width", result.text, password="pw")
# 取证 & 容量规划
report = textveil.detect(result.text)
print(report.score, report.level, report.findings)
print(textveil.capacity("synonym", cover, encrypted=True))更多可运行示例见 examples/demo.py（make demo 一键演示）。
# 载体从标准输入读入，结果继续通过管道交给接收方
cat cover.txt \
| textveil hide -m zero-width --carrier - -s "hi" --no-password \
| textveil reveal -m zero-width --no-password -i -演示动图 / 终端截图将随首个 Release 补充，可先执行
make demo查看完整实时流程。
Q：不用密码可以吗？
A：可以，加 --no-password 即可，但此时只做完整性校验、不做保密，任何拿到文本的人都能还原，仅建议用于水印/演示场景。
Q：隐写后的文本经过微信/Slack/邮件转发会失效吗？
A：zero-width 在主流聊天与邮件客户端中均可存活；个别富文本编辑器会主动过滤零宽字符，此时建议改用 synonym 或 whitespace。发送前可用自己的渠道做一次往返测试。
Q：忘记密码能找回吗？ A：不能，这是刻意设计。HMAC 校验失败只会得到「密码错误或载体被篡改」，不存在后门。
Q：如何扩展新的隐写算法？
A：实现 StegMethod 接口（available_bits / encode / extract_bits）并在 src/textveil/methods/__init__.py 注册即可，详见 CONTRIBUTING.md。
- 载体与密文分离：用户提供真实文本作为载体，避免「AI 生成文本」本身成为异常信号。
- 统一的比特槽抽象：每种方法本质上都是「在载体上寻找能表达 1 个比特的槽位」，因此五种算法共享同一套成帧、加密与容量逻辑，新增算法成本极低。
- 自描述帧结构：
魔数 | 标志位 | 盐/随机数 | 密文 | HMAC，并以 32 位长度前缀自定界，载体尾部多余槽位不影响解码。 - 安全默认值：默认要求密码；PBKDF2 20 万轮；加密与认证密钥分离；先加密后认证（Encrypt-then-MAC），用恒定时间比较防时序攻击。
- 零依赖即可审计：只用标准库，每一行加密与编码代码都可被独立审阅，也便于在隔离/内网环境落地。
- 语言：Python 3.8+——跨平台、标准库自带 PBKDF2/HMAC/argparse/zipapp，无需编译。
- 打包：标准库
zipapp生成单文件.pyz，不依赖 PyInstaller 等重型工具。 - 测试：标准库
unittest，CI 在 Python 3.8 / 3.10 / 3.12 三版本矩阵运行。
- v1.1：新增「标点同形」与「Unicode 标签字符」两种方法；近义词表扩充与外置自定义词表
- v1.2：交互式 TUI 向导（载体诊断 → 算法推荐 → 写入 → 自检）
- v1.3：批量模式（整个目录的文件隐写/扫描）与 HTML/Markdown 感知的槽位选择
- v1.4：检测能力增强（统计检验、零宽字符分类热力图、与已知隐写工具的指纹比对）
- v2.0：可选的密钥交换辅助（基于口令的会话指纹校验），并提供 WASM 浏览器在线演示页（纯前端、依然离线）
欢迎在 Issues 中提出你想要的算法与场景。社区贡献方向：扩充高质量多语言近义词对、补充富文本渠道兼容性测试矩阵、改进检测评分模型。
TextVeil 属于工具库 / CLI 类项目，无需服务端部署。
make build # 等价于：
python3 scripts/build_pyz.py
# 产物：dist/textveil.pyz（约 50KB，压缩格式）Windows PowerShell 用户执行 scripts/build.ps1；macOS / Linux 用户也可执行 scripts/build.sh。产物在任何安装了 Python 3.8+ 的系统上直接运行：
python3 dist/textveil.pyz methodspython3 -m pip install build
python3 -m build # 产出 wheel 与 tar.gzmake test # 37 个单元测试
make lint-smoke # 全量字节码编译检查
make demo # 端到端库 API 演示| 环境 | 支持情况 |
|---|---|
| Windows 10/11、macOS 11+、主流 Linux 发行版 | ✅ 完全支持 |
| Python 3.8 – 3.12 | ✅ CI 矩阵覆盖 |
| 无网络 / 内网 / 离线主机 | ✅ 安装与运行均不需要联网 |
| 无 Python 的主机 | 请先安装 Python，或使用系统包管理器分发 .pyz 包装器 |
我们欢迎 Issue、Pull Request 与算法建议！开始之前请阅读 CONTRIBUTING.md，核心约定：
- 提交信息遵循 Angular 规范：
feat:/fix:/docs:/refactor:/test:/chore: - 不新增第三方运行时依赖（如确有必要请先开 Issue 讨论）
- 新功能必须附带测试，提交前确保
make test全绿、三语文档同步更新 - Issue 请附上命令、预期/实际结果、Python 版本与操作系统；安全敏感问题可通过 GitHub Security Advisory 私下报告
本项目基于 MIT License 开源，允许自由使用、修改、分发与商用，保留版权与许可声明即可。
如果 TextVeil 对你有帮助，欢迎 ⭐ Star 支持，并把它分享给同样关注隐私与信息安全的朋友。