docs: 修复中文文档 GBK 双重编码乱码 + 清理失效文档引用（C3） - #5
Merged
Merged
Conversation
enterprise.zh-CN.md、TUTORIAL.zh-CN.md、RELEASE_NOTES_v0.2.0.md 在仓库中即为乱码（UTF-8 字节被当 GBK 解码后又存为 UTF-8）；确认 HEAD 与本地一致，非本地环境问题，对应 plan 里的 C3 待复核项。 修复方式为往返还原（当前文本 → GBK 字节 → UTF-8 解码），保持 UTF-8 无 BOM 与 CRLF 不变。已知残留：原损坏过程把部分全角标点等替换成 '?'，属不可逆损失。
审查者指南本 PR 仅修复 3 个中文 Markdown 文档因 GBK→UTF-8 双重编码造成的乱码，通过字节级往返还原恢复可读文本，并验证乱码特征归零且保持原有 BOM 与换行格式；部分损坏过程中已不可逆丢失的字符仍以问号保留。 文件级变更
提示和命令与 Sourcery 交互
自定义使用体验访问你的控制面板以：
获取帮助Original review guide in EnglishReviewer's Guide本 PR 仅修复 3 个中文 Markdown 文档因 GBK→UTF-8 双重编码造成的乱码，通过字节级往返还原恢复可读文本，并验证乱码特征归零且保持原有 BOM 与换行格式；部分损坏过程中已不可逆丢失的字符仍以问号保留。 File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
你好——我发现了 2 个问题
AI 代理提示
请处理本次代码审查中的评论：
## 单独评论
### 评论 1
<location path="docs/guides/TUTORIAL.zh-CN.md" line_range="5" />
<code_context>
+英文主教程（推荐优先阅读）：[TUTORIAL.md](./TUTORIAL.md)
-> 璇存槑锛氭湰椤垫槸涓枃杈呭姪鐗堬紝缁撴瀯涓庤嫳鏂囦富鏁欑▼瀵归綈锛屼絾鍐呭鏇寸簿绠€銆?
+> 说明：本页是中文辅助版，结构与英文主教程对齐，但内容更精简�?
-## 1. 鍑嗗鏉′欢
</code_context>
<issue_to_address>
**细节问题：** 修复后的文档仍然包含字面量 Unicode 替换字符（`�`）和截断文本，因此所声称的可读中文修复并不完整。诸如 `中文辅助版，结构与英文主教程对齐，但内容更精简�?` 和 `企业版预览（单租户私有化�?` 这样的标题和句子，对读者来说仍然明显损坏。
**触发场景：** 用户阅读修复后的中文文档时。
**建议修复：** 将每个 `�`/截断片段替换为预期的中文标点或措辞；或者明确报告这些剩余的替换字符属于尚未解决的损坏，而不是声称已经完成完整修复。
</issue_to_address>
### 评论 2
<location path="docs/guides/TUTORIAL.zh-CN.md" line_range="15" />
<code_context>
+ - 远程：OpenAI-compatible endpoint + API key�?
-## 2. 棣栨閰嶇疆锛堟闈㈢増锛?
+## 2. 首次配置（桌面版�?
-1. 鎵撳紑璁剧疆锛堝彸涓婅榻胯疆锛夈€?
</code_context>
<issue_to_address>
**细节问题：** 新近恢复的几个标题仍然格式错误，并不是有效的中文标题：`首次配置（桌面版�?`、`## 运行时收口模�?`、`## 私有化部署资�?`、`# Memory OS Lite 企业价�?` 和 `### 性能与索�?` 的末尾都包含替换/截断痕迹。尽管周围的正文已经完成转换，但这使文档结构和术语仍不完整。
**触发场景：** 读者按章节标题浏览或搜索中文 Markdown 文档时。
**建议修复：** 恢复各标题中缺失的标点和字符，例如补上右括号，以及 `模型`、`资产`、`价值` 和 `索引` 中缺失的文字。
</issue_to_address>Sourcery 评估
已批准。
Original comment in English
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="docs/guides/TUTORIAL.zh-CN.md" line_range="5" />
<code_context>
+英文主教程（推荐优先阅读）：[TUTORIAL.md](./TUTORIAL.md)
-> 璇存槑锛氭湰椤垫槸涓枃杈呭姪鐗堬紝缁撴瀯涓庤嫳鏂囦富鏁欑▼瀵归綈锛屼絾鍐呭鏇寸簿绠€銆?
+> 说明：本页是中文辅助版，结构与英文主教程对齐，但内容更精简�?
-## 1. 鍑嗗鏉′欢
</code_context>
<issue_to_address>
**nitpick:** The repaired documents still contain literal Unicode replacement characters (`�`) and truncated text, so the claimed readable Chinese restoration is incomplete. Headings and sentences such as `中文辅助版，结构与英文主教程对齐，但内容更精简�?` and `企业版预览（单租户私有化�?` remain visibly corrupted to readers.
**Triggers:** When a user reads the repaired Chinese documentation.
**Suggested fix:** Replace each `�`/truncated fragment with the intended Chinese punctuation or wording, or explicitly report these remaining replacement characters as unresolved corruption rather than claiming a complete repair.
</issue_to_address>
### Comment 2
<location path="docs/guides/TUTORIAL.zh-CN.md" line_range="15" />
<code_context>
+ - 远程：OpenAI-compatible endpoint + API key�?
-## 2. 棣栨閰嶇疆锛堟闈㈢増锛?
+## 2. 首次配置（桌面版�?
-1. 鎵撳紑璁剧疆锛堝彸涓婅榻胯疆锛夈€?
</code_context>
<issue_to_address>
**nitpick:** Several newly restored headings are still malformed rather than valid Chinese headings: `首次配置（桌面版�?`, `## 运行时收口模�?`, `## 私有化部署资�?`, `# Memory OS Lite 企业价�?`, and `### 性能与索�?` end with replacement/truncation artifacts. This makes the document structure and terminology incomplete even though the surrounding prose was converted.
**Triggers:** When readers navigate or search the Chinese Markdown documents by section heading.
**Suggested fix:** Restore the missing punctuation and characters in each heading, such as the closing parenthesis and the missing words in `模型`, `资产`, `价值`, and `索引`.
</issue_to_address>Sourcery assessment
Approved.
Owner
|
方向是对的，恢复质量也不错（ 先说清楚性质：不是这个 PR 弄坏的我核过三个文件修复前后的情况：
乍看像是修复引入了 191 个乱码，其实不是：原始损坏本身就是不可逆的。这些文件是 UTF-8 被当 GBK 读， 换句话说：从"完全不可读"变成"基本可读 + 191 个洞"，净收益很大。但这 191 个洞得补上才能合。 需要处理的两件事1. 191 处
|
评审 FPSZ#5：U+FFFD 紧跟字面 ? 的空洞共 191 处。本提交按评审建议批量处理行尾空洞（绝大多数原本是全角句号），并把因换行被吃掉的并行列表项拆回独立行（?- 模式）。行中空洞（丢的是实义字）需逐句判断，留待下一批。
三个中文文档在仓库里是“UTF-8 字节被按 GBK 二次解码”写坏的，恢复后还剩 行中空洞；上一批批量补句号时也有一批位置补错了。这一批全部按字节证据逐处修正。 方法：空洞处丢的是当时 GBK 解不出来的那 1~2 个字节，而空洞前面仍残留同一字符的 UTF-8 前缀。把前缀补 0x80~0xBF 枚举出候选字符，再结合上下文与英文主文档定原文。 - 补齐剩余行中空洞：如“远端 runtime”“展示”“同一套”“最终”“每行一个”等 - 纠正误补成句号的位置 45 处：标题（发版前检查/可选烟测脚本/认证与会话/运行时收口模型/ 私有化部署资产/性能与索引/企业价值）、未闭合括号 14 处、列表引导语改冒号 31 处 - 修正上一批猜字与字节证据不符的 11 处（远程→远端、与→和/或、为→是、在→为 等） - 去掉拆行时多出的一个空格 5 处 验证：三份文档 U+FFFD 归零；全部 191 处空洞的填入字符都落在字节前缀允许的候选集内 （190 处逐一比对通过，2 处为 URL 里的真问号与已正确处）；行尾保持 CRLF、无 BOM。
用 CommonMark 渲染器（markdown-it-py）检查三份中文文档，发现 4 处渲染问题。 这些都是原文档自带的排版问题（乱码不会改变 # 和空行），按要求一并修好： - 教程末尾 “Memory OS Lite 使用提示” 由一级标题降为二级，并补空行 - 企业文档末尾 “Memory OS Lite 企业价值” 同样降为二级，前后补空行 - 企业文档末尾说明段与“企业侧应重点强调：”之间补空行，不再被渲染成同一段 - 企业文档末尾补上换行符（其余行本就是 CRLF，末尾不再是裸 LF） 验证：渲染结构检查三份文档问题数 0；行尾全 CRLF 无混合；U+FFFD 仍为 0； 空洞字节审计结果不变（190 处通过 / 0 处不符 / 2 处已解释）。
docs/guides/ 下的相对路径要多退一层：../deploy/README.md 会解析到不存在的 docs/deploy/README.md，而 deploy 目录在仓库根。中英两份指南同一处都写错了， 一起修正为 ../../deploy/README.md。 验证：按 GitHub 的相对路径语义解析，两处都能指到仓库根的 deploy/README.md； 三份中文文档的链接检查、渲染检查、字节证据审计仍全部通过。
全仓库相对链接普查发现 5 处失效，本提交修掉 README/索引这 3 处（另 2 处 deploy 链接已在上一提交修正）： - README.md / README.en.md：教程链接少了 guides/ 一层，改指 docs/guides/ - docs/README.md：删掉指向 docs/planning/PLAN_CHANGELOG.md 的索引项，因为该文件 在上游 a94bb41 已被删除，main/dev/collab 等所有分支上都不存在 验证：全仓库相对链接普查 0 处失效（47 条相对链接全部可解析）。
上游删掉或改名的文档，仓库里还留着"让读者去读 / 去更新"的索引，逐处清理： - docs/planning/plan.md：Change Log 一节原写"变更日志已迁移至 docs/planning/PLAN_CHANGELOG.md"，该文件在上游 a94bb41 已删除（main/dev/collab 都没有），改成说明不再单独维护、历史变更查 git 提交记录 - CONTRIBUTING.md / CONTRIBUTING.en.md： * README.zh-CN.md → README.en.md、CONTRIBUTING.zh-CN.md → CONTRIBUTING.en.md * 去掉指向已删除的 AI.md（4bd8556 删除）与 UI.md（fc455ca 删除）的条目 - docs/architecture/STRUCTURE.md：文档分工与建议阅读顺序里去掉已删除的 docs/AI.md （并重排编号），plan.md 的描述同步去掉"变更日志" 验证：全仓库相对链接普查 0 失效；三份中文文档五层审计 0 问题；改动文件行尾统一 CRLF、末尾有换行、无 U+FFFD（plan.md 的 BOM 是上游既有，未改动）。
wjs480
pushed a commit
to wjs480/Memori-Vault
that referenced
this pull request
Sep 15, 2026
评审 FPSZ#5：U+FFFD 紧跟字面 ? 的空洞共 191 处。本提交按评审建议批量处理行尾空洞（绝大多数原本是全角句号），并把因换行被吃掉的并行列表项拆回独立行（?- 模式）。行中空洞（丢的是实义字）需逐句判断，留待下一批。
Author
|
按提交分层说明一下，方便评审按需取舍。 一、乱码修复（ec18772 / 20733b3 / 2ce9b6c）这三份中文文档是「UTF-8 字节被按 GBK 二次解码」写坏的。恢复过程有字节级依据，不是猜：空洞处丢的是当时 GBK 解不出来的那 1–2 个字节，但空洞前面仍残留同一字符的 UTF-8 前缀；把前缀补
举个能说明「为什么不是猜」的例子： 验证：三份文档 U+FFFD 归零；192 处空洞逐一比对，190 处填入字符落在字节前缀允许的候选集内；剩下 2 处分别是 URL 里的真问号（ 二、渲染修复（67e8f27）用 CommonMark 解析器检查，发现 4 处渲染问题：两处正文中间夹着一级标题、两段被渲染成同一段、企业文档末尾缺换行符。修完后渲染问题数为 0。 三、文档卫生（265f99b / a5c3d77 / 887c664，可按需拆分）
如果希望本 PR 只聚焦中文文档修复，前 4 个提交（ec18772 / 20733b3 / 2ce9b6c / 67e8f27）已完整可用，第 5–7 个我可以另开一个 PR，说一声即可。 总验证：三份中文文档的「编码 / 结构 / 链接 / 渲染 / 字节证据」五层检查 0 问题；全仓库相对链接普查 0 失效。 |
Owner
|
复审通过，可以合了。上一轮提的两件事都做完了，而且做得比要求的更彻底。 核实结果1. 191 处空洞已清零
残留的唯一一个字面 补字抽查下来都对，而且读着自然： （有几处原字节已不可考， 2. 列表并行已拆开 之前 3. 顺带做的链接修复 我把这个 PR 改到的全部 md 文件做了一遍本地链接检查：38 条本地链接，失效 0 条。 一个小建议（不影响合并）PR 标题还是「修复 3 个中文文档的 GBK 双重编码乱码（C3）」，但现在实际改了 11 个文件，多出来的是 这些改动本身没问题（我都验过），只是建议把标题和描述更新一下，比如「修复中文文档 GBK 双重编码乱码 + 清理失效文档引用（C3）」，免得以后翻 git log 的人按标题找不到链接修复那部分。 这三份文档坏了很久，能按字节证据一点点捞回来、连列表结构都还原了，这活干得漂亮。 |
FPSZ
added a commit
to wjs480/Memori-Vault
that referenced
this pull request
Sep 16, 2026
合并 FPSZ#2/FPSZ#3/FPSZ#5 后的 collab，三处冲突均为双方各自新增内容，保留双方： - README.md「已实现但仍在优化」：50k 压测条目 + OCR 条目 - docs/qa/RETRIEVAL_BASELINE_V2.md：作答层 LLM-judge 基线 + OCR 接入与边界 - memori-server/src/dto.rs：AppSettings 的 index_filter 与 ocr_tesseract_path 两个字段 同时启用 pdf_with_indirect_resources_is_extracted（原 #[ignore]）： 手工构造 lopdf::Stream 用结构体字面量会绕过 /Length 写入（lopdf object.rs:602 的 Stream::new 才会 dict.set("Length", ...)），存盘后流长度为 0、load 回来 content 为空，解码拿不到像素，测试因此假失败——与 get_pages() 无关（实测 get_pages()=1、get_page_resources 也正确返回 inherited）。改用 Stream::new 后 测试通过，可作为间接 /Resources + 间接 /XObject 的回归锁。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
wjs480
changed the title
Author
|
@FPSZ 已按建议更新：
合并提交与 diff 未受影响（ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
核对文档时发现仓库里有 3 个中文文档是乱码（UTF-8 字节被当作 GBK 解码后又存成 UTF-8 的「双重编码」）：
docs/guides/enterprise.zh-CN.mddocs/guides/TUTORIAL.zh-CN.mddocs/release/RELEASE_NOTES_v0.2.0.md已确认
HEAD与本地一致、且本地对这些文件无改动 → 是仓库本身的问题，不是本地环境造成。这正对应plan.md里的待复核项 C3「Windows GBK→UTF-8 乱码复核」。全库扫描（md / rs / ts / tsx / json / yaml / toml / ps1 / html）确认只有这 3 个文件受影响，代码、字符串字面量与配置均未被破坏。改了什么（11 个文件 / 7 个提交 / +217 −218）
一、乱码修复（核心）
往返还原：
当前文本 → 按 GBK 还原字节 → 按 UTF-8 解码，保持 UTF-8 无 BOM 与 CRLF，不引入换行噪声。按字节证据补回空洞：双重编码过程把一部分字节写成了
?。这些空洞丢的是当时 GBK 解不出来的那 1–2 个字节，但空洞前面仍残留同一字符的 UTF-8 前缀——把前缀补0x80–0xBF枚举出候选字符，再结合上下文与英文主文档确定原文。例如
应用不会自动启动本地 llama.cpp 或远<?>runtime这一处，候选集里只有「端」没有「程」，所以原文是远端；最终 runtime candidate、每行一个 JSON 事件、向量检索、SQLite 持久化、UI 语言与 AI 回答语言分离等同理。结构还原：把因换行被吃掉而挤在一行的 5 个 bullet 拆回独立列表项；三个文件最长行分别是 147 / 128 / 86 字符。
二、渲染修复
用 CommonMark 解析器检查出 4 处渲染问题并修好：两处正文中间夹着一级标题、两处段落被渲染成同一段、企业文档末尾缺换行符。修完后渲染问题数为 0。
三、失效文档引用清理（顺带）
enterprise.md/enterprise.zh-CN.md：../deploy/README.md少退一层 →../../deploy/README.mdREADME.md/README.en.md：教程链接缺guides/一层docs/README.md：去掉指向已被删除的PLAN_CHANGELOG.md的索引项CONTRIBUTING.md/CONTRIBUTING.en.md/STRUCTURE.md/plan.md：清理对已删除文档（AI.md= 4bd8556 删除、UI.md= fc455ca 删除、PLAN_CHANGELOG.md= a94bb41 删除）与已改名文档（README.zh-CN.md、CONTRIBUTING.zh-CN.md）的过期引用验证
?是GET /api/admin/audit?page=1&page_size=50里的 query stringgit diff --check干净