Transparent Encrypt File MCP (v1.6.5)

> 当前能力（单一事实源）— v1.6.5：40 个 MCP 工具 + 11 个 Python 结构化脚本（另有 1 个共享库
> scripts/lib/dlp_common.py 供上述脚本复用，不计入脚本数）。
> 格式族口径（两个数都对，取决于粒度，v1.6.5 起写明）：能力矩阵 src/shared/capability.js 有
> 16 行 = 15 个二进制格式族 + 纯文本族（TEXT_EXTS 58 个文本/源码扩展名）；面向人的速查表按
> 12 个归并族呈现 —— 把 WPS 三件套（.wps/.et/.dps）并为一行、OpenDocument 三件套
> （.odt/.ods/.odp）并为一行，即 16 − 4 = 12。任何一处出现别的数字都是笔误。
> v1.6.5 = 一次"把散落的隐性知识收成单一事实源"的收口版本（错误分类学 / 能力矩阵 / 写路径守卫三处），
> 并新增 6 个工具（capability_matrix 第 35 个 + 取证/留痕四件套 第 36–39 个 + python_channel_status 第 40 个，见 ⑤ ⑥）：
> ① 错误分类学单一事实源（src/com/error_codes.js，45 个错误码）——每个码固定带「症状 / 根因 /
> 怎么办 / 自检」四段与严重度、可重试标记；所有错误输出的首行统一为 ❌ [CODE] 标题，可被 grep、
> 可被引用、可写进工单。v1.6.5 新增 DEPENDENCY_MISSING（缺 @modelcontextprotocol/sdk / zod 时
> 由 --doctor 直接给出结论，而不是抛一段看不懂的堆栈）。未归类错误的兜底从"一句笼统文案"升级为
> "按命中概率排序的前 3 类原因 + 3 条分诊命令（--doctor / forensics_headers / check_status）"。
> ② 能力矩阵单一事实源（src/shared/capability.js，15 个格式族）——「哪种格式能不能读/写、走哪条通道、
> 前置依赖是什么、没有写路由时替代方案是什么」从此只有一个出处，filetypes.js 的两张旧表改为派生。
> ③ 写路径守卫（src/shared/writeguard.js，新增 P0 数据丢失防护）——对没有 COM 写路由的二进制容器
> （.ods/.odp/.dps/.mdb/.accdb/.pdf/.msg/.eml/.dwg/.dxf 与各压缩包）硬拦截 write_file / edit_file。
> 此前这些扩展名会静默落到 fs.writeFileSync(..., "utf-8")，用纯文本覆盖 ZIP / OLE 容器并返回一条看起来
> 成功的 Wrote … N bytes ——这是本版本修复的最严重缺陷。
> ④ 生成物一致性门——references/errors-zh.md 与 references/capability-matrix-zh.md 由代码生成，
> tools/check_consistency.js 在闸门内 in-process 逐字节比对，杜绝"文档与代码漂移"。
> ⑤ 取证/留痕四件套（新增）——这四个工具的共同点是读盘上原始字节（不是白名单应用解密后的明文），
> 回答 DLP 场景里最先被问到的四个问题：
> · forensics_headers —— "盘上字节到底是什么？"输出十六进制转储 + 魔数分类 + DLP 特征命中 +
> 扩展名与内容是否相符（与 detect_encryption 的分工：那个回答"该走哪条通道"，本工具回答"字节是什么"）；
> · inventory_encrypted —— "这个目录里哪些文件真的被加密了？"按扩展名统计加密/明文/未知三态，
> 迁移、备份、治理前先跑它；
> · compare_plaintext —— "我这次写入有没有把加密破坏掉？"比对两份文件头 + 大小 + SHA-256，
> 并对"一份密文一份明文"直接判为疑似明文泄漏（这正是「明文桥」方案必然产生的未加密窗口）；
> · audit_trail —— "本次会话对哪些文件动过手？"记录写路径的尝试 / 结果 / 被守卫拦下的请求。
> 留痕仅进程内、不落盘（本服务不在 DLP 白名单，写盘会落成密文），是自证与排障工具，
> 不是防篡改的合规证据链 —— 边界已在返回里写明。
> ⑥ 把"文档承诺了、代码却没做"的三件事补上（新增 python_channel_status） ——
> 本版本逐条核对了 45 个错误码的"是否真的会被发出"，发现四个码只躺在分类学里、
> 没有任何运行时发射点，而文档早已对外承诺：
> · python_channel_status（新增工具，第 40 个）—— PYTHON_CHANNEL_UNAVAILABLE 与
> PYTHON_DEPS_MISSING 两个码的 verify 字段都写着"自检命令：python_channel_status"，
> 而此前这个工具并不存在（承诺了却没有）。它一次回答：解释器在哪（含 TEFMCP_PYTHON
> 覆盖）、pywin32 是否可导入、11 个脚本各能做什么、以及哪些能力只有这条通道能做。
> 只读——仅执行 python -c "import …" 探测，不装包、不改环境、不碰业务文件。
> 探测失败时不冒充"没装"：解释器在但探测被拦下 → 报 SPAWN_FAILED，并明说这不能作为
> "缺 pywin32" 的证据。
> · SCANNED_PDF_NO_TEXT —— capability.js 早已写明"扫描件会返回 SCANNED_PDF_NO_TEXT，
> 不会静默成功"，但代码只给了一句自由文案。现改为由错误分类学渲染（单一事实源），
> 并新增文本密度判定（pages/textChars/charsPerPage 一并进 _meta）：
> 旧实现只看绝对阈值，500 页扫描件从页眉凑出几十个字就会被判成"读到了内容"。
> 页数取不到时退回绝对阈值——不猜。
> · PLATFORM_UNSUPPORTED —— 此前在非 Windows 上用户看到的是 spawnSync 的 ENOENT
> （那里根本没有 powershell.exe），于是去查"是不是缺软件""是不是文件坏了"。现于
> com/transport.js 的唯一出口加平台闸门，并在 check_status 兑现
> environment.platform / platformSupported / platformNote（错误码的 verify 承诺）。
> 同版本还把"限制清单"的三种粒度（运行时投影 check_status.knownLimitations /
> 明细 references/limits-zh.md / 摘要表 quickstart §2.1）统一到 L1–L12 同一套编号，
> 由发布闸门逐条比对——三方各改一处必然漂移，这是这类"同一清单多份拷贝"的通病。
> 工具面自 v1.6.0 起未增减，v1.6.5 首次 +6（explain_error 之后的新增工具）。
> 后文出现的其它工具数字均为描述历史版本的更新日志条目，
> 非当前能力。版本号以 manifest.yaml / package.json / 本文件 frontmatter 为准 = 1.6.5。

> 一句话决策：文件用自带工具能正常读 → 不用本技能；读出来是乱码/报错但 Excel/Word 能打开 →
> 用 MCP 工具；需要脚本才做得到的能力（文档顺序、原地改格、PPT 备注、Access 改记录、PDF 页面）→
> 用 scripts/。用之前先做 30 秒环境自检（见下）。

> 中文快速上手（面向新手）：本技能用于「文件被公司透明加密（DLP）的 Windows 电脑」，让 AI 代理像人一样
> 正常读取/写入被加密的 Office / PDF / WPS 等文件（借道被放行的 Office/WPS 程序，不破解加密）。
> 部署步骤、工具对照表、常见错误处理见 references/quickstart-zh.md；
> 排错先看 references/troubleshooting.md；
> 需要「文档结构 / 原地改单元格 / 生成带版式的 Word」时看 references/python-structured-channel.md。
> 动手写入之前先查 references/anti-patterns-zh.md（A01–A29 错法清单：
> 反模式 / 为什么错 / 症状 / 正确做法 / 自检）；不确定就问 references/faq-zh.md
> （36 问，每问带自检）；"这个格式到底能不能读 / 写"看 references/limits-zh.md
> （L1–L12 明细，与 quickstart §2.1 摘要表同编号）。
> 运行时错误提示为中文；读 COM 失败会自动重试 1 次。

第一步先做环境自检（评审 E 项：用对工具的前提是先知道装了什么、DLP 是否真开着）：

• 装了什么软件：调 check_status → 看 environment.installedApps（基于 App Paths 注册表，不启动
  Office、不弹窗）；或跑 python scripts/probe_dlp_policy.py → 看 [Apps] 段。
• DLP 是否真的开着：python scripts/probe_dlp_policy.py --dir <真实业务目录>（只碰它自己生成的
  测试文件；管理员身份重跑可拿到 fltmc 过滤驱动这一直接证据）。
• 踩坑前先看隐藏限制：调 check_status → 看 knownLimitations（10 条最常踩的坑，排障时不用翻文档）。

Purpose

Under transparent-encryption DLP, a filesystem filter driver decrypts files only for
whitelisted processes (Office / WPS / Outlook / AutoCAD, or a whitelisted CLI such as
7-Zip or LibreOffice). The agent's own process is not whitelisted, so fs / the built-in
Read tool return ciphertext. This skill bundles a Node.js MCP server (stdio) that reads
and writes such files as plaintext by delegating to a whitelisted process instead of
touching the disk directly.

The skill never cracks or weakens DLP — it uses the existing whitelist exactly as a human
double-clicking the file would.

Two cooperating channels

Coverage difference — read this before assuming the second channel is a superset. The MCP
channel covers 16 capability rows = 12 grouped format families (see the grouping note at the
top). The Python channel is depth, not breadth: it reaches
5 families (Word, Excel, PowerPoint, Access, plus PDF via Acrobat) and does things a
line-based reader cannot. PPTX / Access / WPS / PDF work exists only as explicit scripts —
for .ods/.odp, email .eml/.msg, CAD and archives there is no Python script at all; use the
MCP tools (or write a new script).

Default to the MCP tools — they cover more formats and need no per-call setup. Switch to the
Python channel only when you specifically need structure, style, or in-place cell edits that a
line-based reader cannot express. Both channels obey the same two iron rules: reads are
read-only (ReadOnly=True + SaveChanges=False) and writes save from inside the
whitelisted app so the DLP driver re-encrypts on the way to disk.

When to use — layered trigger (evidence-driven)

Do not blanket-route every file through this skill. Decide by evidence, in this order:

When the tier is ambiguous and the file is cheap to probe, run detect_encryption first
(it reads only the first 1 KB) rather than guessing.

Do NOT trigger this skill when

• The machine has no transparent-encryption DLP at all — every covered file is then
  normal plaintext and routing through COM is pure overhead.
• The file is a scanned / image-only PDF — there is no OCR here; it will return little
  or no text (see references/troubleshooting.md §3).
• The host is not Windows, or is a headless / Session-0 / CI environment — Office COM
  cannot run there (text-file fs reads still work; everything COM-based will not).
• The target is a plain .txt/.md/.csv/.json whose content already reads correctly — use the
  built-in tools.
• You only need to view a .docx/.xlsx that the platform's own local Office editor route
  can already open unencrypted.

Which MCP tool to call

All tools are named mcp__transparent-encrypt-file-mcp__<tool>.

Utilities: read_files (batch; Excel/PPT reuse one COM instance), search_files,
create_directory, file_info, check_status, doctor (one-call health check),
capability_matrix (per-format read/write capability + alternatives), forensics_headers (raw on-disk
bytes + hex dump), inventory_encrypted (which files are really encrypted), compare_plaintext
(write-did-not-break-encryption check) audit_trail (write-path log) and python_channel_status (Python-channel
self-check: interpreter + pywin32 + what only this channel can do). Total: 40 tools.

Call pattern: always pass the absolute Windows path as path. If a tool errors or
returns empty, surface the error to the user — do not silently retry with the built-in
Read tool, which would hand back ciphertext.

Safety invariants (mandatory)

1. Read paths never write. Every reader opens the document read-only and closes with
   save-changes disabled. Under DLP an accidental save from a delegated app would rewrite the
   encrypted original. Never "fix up" a read result by saving the source file.
2. Never quit the user's Outlook. Outlook is a single-instance COM server, so
   New-Object -ComObject Outlook.Application attaches to the running instance. The server
   therefore never calls $ol.Quit() — doing so closes the user's Outlook.
3. Timed-out COM calls kill only the PID we caused. Generators report OFFICEPID: (the
   single Word PID identified by a before/after PID diff at creation time); on timeout the server
   kills that PID and its own PowerShell tree only — never a blanket image-name kill (that
   would also destroy the user's own open, unsaved documents). If the PID cannot be
   identified, nothing is killed and the error says so explicitly.
   In headless sessions only, Word reads may seed 5 HKCU first-run-wizard keys (minimal set,
   no privacy/online-content preferences; opt-out TEFMCP_NO_FIRSTRUN_SEED=1). This is never
   silent: the read result carries a firstRunSeed field listing every key written and the undo command.
4. ZIP extraction is transient. Archive contents are extracted into a temp directory that is
   removed immediately after reading; no plaintext is left outside the DLP-protected area.
5. Do not disable, weaken or bypass DLP. If a tool reports that the process is not
   authorized, the answer is to ask the admin to whitelist powershell.exe (or the Node
   binary) — never to work around the policy.

What makes this different (compliance-first)

Most "read my encrypted files" tools optimise for feature count. This one optimises for
being safe to run inside a company that has something to protect. Five deliberate
differences, each with the naive alternative it replaces and how you can verify it yourself.
The reasoning behind them (and the seven non-negotiable red lines) is in
references/design-rationale-zh.md.

Two consequences worth stating plainly:

• Your ceiling is your whitelist. This server can only do what a whitelisted process can do.
  If Word is not installed, .docx reads fail — and no amount of Node.js will fix that.
• Honest limits beat hidden ones. Where a capability is missing, the tool says which format
  family, why, and what to do instead (install X, or use scripts/*.py, or convert to a
  writable format) — rather than returning a plausible-looking empty result.

Diagnosis procedure (find the real whitelist)

Vendor signatures and the policy table are inferences. The authoritative answer comes from
probing: take one known-encrypted file and open it with each candidate process. Whichever
returns a real header (PK\x03\x04, D0CF11E0) or readable text is whitelisted.

In practice Node.js and Python are usually NOT whitelisted; the Office apps almost always
ARE — hence the delegation pattern. Exception: some TianRui Green Shield configurations do
whitelist Node, so verify rather than assume. The bundled detect_encryption tool only reads
the header and returns heuristic fields (vendor, *ByPolicy, signatureStrength); it cannot
prove whitelist membership.

Deployment & MCP registration

One command (recommended) — from the skill folder, in PowerShell:

powershell -ExecutionPolicy Bypass -File install.ps1

install.ps1 is idempotent, backs up mcp.json before touching it (and restores it if
the write fails), and self-verifies (node index.js --doctor) before registering.
Afterwards run node index.js --doctor yourself: exit code 0 = no blocking fault,
1 = something is wrong — greppable, scriptable, no need to parse the output.

Full operator manual → references/deployment-zh.md
(manual registration path, materializing index.js / the .bat assets, all timeout
environment variables and their defaults, the agent-facing routing hint, source layout &
build, and the MCP error: -32000 Connection closed diagnosis table).

Environment requirements

• Windows only — COM Automation + PowerShell. No Linux / macOS / mobile.
• Interactive desktop session required for anything COM-based. Office COM will not run in
  a headless server or a CI container without a logged-in Windows session.
• The relevant app (Office / WPS / Outlook / AutoCAD / 7-Zip / LibreOffice) must be
  installed AND on the DLP whitelist.
• Node.js 18+ for the MCP server itself.
• Python + pywin32 only if you intend to use the scripts/ structured channel; the MCP
  channel needs no Python.
• Read/write access to the server directory (the server writes transient .ps1 files; if the
  directory is read-only it falls back to %TEMP%\transparent-encrypt-file-mcp).

Gotchas

• PowerShell variable pitfalls: $r, $c are parsed as drive references inside
  double-quoted strings / (...) — use $i, $j, $k for loop counters.
• Test-Path on a Chinese path may falsely return False; enumerate with Get-ChildItem
  and feed the real FullName to the COM app instead.
• MsoTriState trap (PowerPoint): $shape.HasTextFrame -eq $true is always $false
  (msoTrue = -1) — use a truthy check. Presentations.Open's ReadOnly is the 2nd
  parameter; Visible must be set with [Microsoft.Office.Core.MsoTriState]::msoFalse.
• Visible=$false may throw "Hiding not allowed" on some Office builds — the server wraps
  the assignment in try/catch.
• PowerPoint COM Presentations.Open is non-functional on some hosts, failing with
  0x80070003 / 0x80070570 even on a local non-encrypted .pptx. Excel/Word COM work
  fine there. Do not read that as "the file is corrupt". Ask the user to save a
  non-DLP-protected copy, or extract the key slides as text/xlsx.
• Office/WPS COM is slow (~1–3 s) and holds a hidden instance — the server always calls
  Quit() + ReleaseComObject in finally to avoid zombie EXCEL.EXE / WINWORD.EXE /
  POWERPNT.EXE / MSACCESS.EXE / wps.exe / et.exe processes.
• write_email to .eml is unverified. 3 (olMSG) is the reliable Outlook save-as
  format; the .eml path relies on format 1024, which some Outlook versions do not render as
  RFC822. The tool returns an explicit "待校验" warning — verify the output, or write .msg.
• CSV → Excel fidelity. Values starting with =, leading-zero identifiers (00123) and
  ≥16-digit numbers are written as text so Excel cannot execute them as formulas or strip
  precision. Values are never Trim()-ed — leading/trailing spaces are data.
• Password-protected files hang. Office shows a password prompt that blocks a headless
  call until timeout. Open the file once manually and supply the password, or save a
  password-free copy first.
• The CSDN "Node is whitelisted" assumption is wrong for ESAFENET — route through
  Office/WPS COM, not fs.
• npm.cmd segfault in Git Bash — call npm's CLI through Node instead:
  node "<node>\node_modules\npm\bin\npm-cli.js" install.
• WPS ProgID variance: some WPS builds expose wps.Application / et.Application /
  wpp.Application instead of KWPS / KET / KWPP. If WPS COM fails, try the alternates.
• cmd.exe DLP intercept: all PowerShell calls use spawnSync('powershell.exe', args, {shell:false}) so Node never spawns cmd.exe internally. If you still see
  "此版本进程未授权打开加密文件", the admin must whitelist powershell.exe (or the Node binary).

Relationship to other skills (avoid double-routing)

• dlp-office-com-io has been superseded by this skill (v1.1.0). Its five pywin32 scripts
  were carried over into scripts/ here, and its knowledge is in
  references/python-structured-channel.md. Use this skill; the older skill directory is
  left untouched on disk but should no longer be selected.
• Never drive both channels against the same file in the same step. Two hidden Office
  instances opening one workbook produce sharing-violation errors. Pick the MCP tool or the
  Python script, finish, then switch.
• Platform local-Office routing (tencent-docs-routing / tencent-local-office-edit,
  tencent-docs-family skills): for plaintext (Tier 0) Office files, prefer those — they are
  the platform's native path. Hand over to this skill the moment ciphertext is observed.

Troubleshooting

Start with references/troubleshooting.md — consolidated
errors, per-type edge cases, environment requirements and security notes. Quick hits:

• Timeout (COM 操作超时) → file locked / Office first-run activation / slow DLP. Raise
  WORD_COM_TIMEOUT_MS and restart the MCP service.
• Ciphertext returned → a non-text file was read through the plaintext channel; use the
  typed tool (read_excel / read_word / read_pdf …).
• Component missing (LibreOffice / 7-Zip / AutoCAD / Outlook) → install it and
  add it to the DLP whitelist.
• -32000 Connection closed → see the two causes above (cwd/modules vs cmd.exe).

Version

1.6.5 (bundled server transparent-encrypt-file-mcp v1.6.5). The server reads its
version from the deployed package.json at runtime and only accepts a package.json whose
name matches, so the displayed version always tracks the npm manifest. Keep
package.json, manifest.yaml and this frontmatter in sync when releasing.

> 完整变更历史已外移到 CHANGELOG.md（v1.6.5 起）。
> 原因：历史占本文件约四成篇幅，而本文件是代理每次运行都会读的当前指令 ——
> 三百行"以前改过什么"会稀释"现在该怎么做"。历史留在变更日志里，这里只保留
> 当前版本号 + 同步口径 + 改代码前必读。
>
> 改任何代码前先读 references/design-rationale-zh.md：
> 那里有 7 项不可回退的红线（G1–G7），任何一项被破坏都会让本技能失去存在意义。
> 动手写入之前先查 references/anti-patterns-zh.md。
>
> 本文件其它位置出现的工具数 / 错误码数若与顶部"当前能力"块不同，那些都是历史条目。

References

完整文件地图 → references/file-map-zh.md
（每个文件干什么、哪些是生成物不要手改、目录树、Python 通道前置条件）。
这里只列代理真正会去读的几份：

Python channel prerequisites

需要 Python + pywin32（MCP 通道不需要）。先调 python_channel_status 确认本机够不够条件，
别白折腾；装法与调用方式见 references/file-map-zh.md §4
（隔离 venv + 绝对路径，不要把带空格的路径塞进 python -c "..."）。