@fxri/toolkit 1.12.5 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 方弦工具集
 
+## 1.13.0
+
+> 2026-10-24 发布
+
+### ✨ 新增功能
+
+- `fxri-text-encoding` 技能按「乱码三问」定归属（谁的字节 / 还能救吗 / 错在第几跳），附读取方默认解码对照与按 mojibake 特征串选 `iconv` 方向的反向转码命令
+- 技能给出 `.ps1` / `.psm1` / `.psd1` / `.bat` / `.sh` / `.xml` / `.properties` / C 系与 Java 源文件及 Excel CSV 的 UTF-8、BOM 与行尾基线
+- 技能对照 AI 写入工具与 `powershell.exe` / `pwsh` / .NET / Node / Python / `.editorconfig` / `.gitattributes` 的写盘 BOM 与默认编码行为，含 `-Encoding UTF8` 在两种 shell 下同名不同义、`Export-Csv` 省略 `-Encoding` 写 ASCII、Node 读侧残留 `\uFEFF`
+- 技能提供落盘后首三字节自查与 `git ls-files` 全仓巡检，改完即可验
+- 技能覆盖运行期管线断点——控制台代码页、`$OutputEncoding` 与 `>` 重定向、`Get-Content` 解码、Python locale、容器 CI `LANG=C`、Java `file.encoding`
+- 技能记录 `core.autocrlf` 检出转换与 `eol=lf` 不回溯已提交内容、Windows「Beta: 使用 Unicode UTF-8 提供全球语言支持」造成的同文件异机差异、Excel 另存 CSV 的编码走向、不可见字符、全角标点、`�` 不可逆、二次转码等场景
+
+### 🔧 功能调整
+
+- `docs/ai-rules.md` 代码规范补脚本字节形态铁律（`.ps1` UTF-8 with BOM、`.sh` 无 BOM + LF、`.bat` / `.cmd` 不带 BOM + CRLF），以系统内置的 `powershell.exe` 指代该 shell，指向该技能
+
+## 1.12.6
+
+> 2026-10-19 发布
+
+### ⚡ 优化改进
+
+- `conventions-spec.md` 声明 `.tasks/` 外层骨架以 `task-spec.md` 为真源，避免两份目录树各自演进漂移
+
+### 🐛 问题修复
+
+- `fxri-session-recap` 恢复模式二引用兄弟技能 `conventions-migration.md` 时补包内真源兜底，单独加载该篇也能定位升级链路
+- `fxri-plan-to-task` 的 v2 → v3 升级步骤直接写出 `retired.md` 固定表头，迁移不再需要反向查 `conventions-spec.md`
+- `fxri-session-recap` 恢复模式二的规范核对步骤按相对路径引用兄弟技能 `conventions-migration.md`，与同文件其他引用及技能编写核对项一致
+- 同一处补全载体形态判定「v1 / v2」与按需读清单 `retired.md`，与主文件 R3 及 `docs/guide.md` 口径一致
+
 ## 1.12.5
 
 > 2026-10-19 发布

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright © 2026 唐启云
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright © 2026 唐启云
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -1,9 +1,9 @@
-@fxri/toolkit
-Copyright © 2026 唐启云. All rights reserved.
-
-出品方：方弦研究所（唐启云个人项目品牌，非独立法人实体）
-
-商标声明：
-"方弦®"为第42类注册商标（注册号89648411），核定服务项目：计算机出租、计算机软件设计、为他人研究和开发新产品、计算机软件维护、把有形的数据或文件转换成电子媒体、为他人创建和维护网站、网络服务器出租、提供互联网搜索引擎、托管计算机站（网站）、云计算。
-本开源许可（MIT License）不授予商标使用权。
-详见 TRADEMARK.md 了解完整商标信息。
+@fxri/toolkit
+Copyright © 2026 唐启云. All rights reserved.
+
+出品方：方弦研究所（唐启云个人项目品牌，非独立法人实体）
+
+商标声明：
+"方弦®"为第42类注册商标（注册号89648411），核定服务项目：计算机出租、计算机软件设计、为他人研究和开发新产品、计算机软件维护、把有形的数据或文件转换成电子媒体、为他人创建和维护网站、网络服务器出租、提供互联网搜索引擎、托管计算机站（网站）、云计算。
+本开源许可（MIT License）不授予商标使用权。
+详见 TRADEMARK.md 了解完整商标信息。

package/README.md

@@ -1,112 +1,113 @@
-<p align="center">
-  <img src="./docs/public/logo.png" width="128" alt="方弦工具集">
-</p>
-
-# 方弦工具集
-
-[![CI](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@fxri/toolkit)](https://www.npmjs.com/package/@fxri/toolkit)
-[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](./docs/getting-started.md#安装)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-
-> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/toolkit)（与 GitHub 同源同步，仓库/文档/issues/skills 全渠道可用）；问题反馈走 [GitHub Issues](https://github.com/fxri-net/toolkit/issues) 或 [Gitee Issues](https://gitee.com/fxri/toolkit/issues)。
-
-专为**多人 + AI 跨项目协作**打造：任务管理 + 多语言 CHANGELOG。
-
-AI 参与开发后，方案与决策散落在对话记录里，会话一关什么都不剩；任务记录零散，谁在做、做到哪，无从查起；发版 CHANGELOG 还要人肉维护多语言。本工具把这条链路沉淀为**仓库内可检索、可校验、可归档的文件**——人离开会话，记忆留在仓库里。
-
-- **零依赖 AI 技能包（skills）**：方案落盘、发版 CHANGELOG 两套工作流沉淀为 Agent Skills，不绑定任何 AI 工具；skills 可以独立工作，CLI 是可选加速——推荐都装，体验最完整（[什么关系？](./docs/faq.md#工具和-skills-都得装吗)）
-- **不懂 AI 也能用**：任务管理与 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语-先说人话)）
-
-## 🚀 30 秒上手
-
-```bash
-# 1. 项目内安装（推荐，团队共享版本）
-pnpm add -D @fxri/toolkit
-
-# 2. 初始化任务区（生成 .tasks/ 骨架、conventions/ 规范载体与技能入口壳；含本地依赖时写入 prepare 刷新钩子）
-pnpm exec toolkit init
-
-# 3. 查看任务总览
-pnpm exec toolkit tasks
-```
-
-之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。多任务 / 多仓方案先出纯展示计划表，再逐仓逐任务建档、按序逐个交付提交。完整步骤见 [新手指南](./docs/getting-started.md)。
-
-## ✨ 能力矩阵
-
-| 能力 | 适用场景 | 文档 |
-| --- | --- | --- |
-| 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](./docs/cli.md) · [任务文件规范](./docs/guide.md#任务文件规范) |
-| 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](./docs/cli.md#changelog) |
-| 协作规范载体（conventions） | 把任务里提炼的规范收进 `.tasks/conventions/`，成为可检索、可校验的项目规范源；支持结构升级、表格形态归一与只读体检 | [CLI 参考](./docs/cli.md) · [完整攻略](./docs/guide.md#conventions-规范沉淀地) |
-| Node API | 把上述能力嵌进脚本或平台 | [API 参考](./docs/api.md) |
-| 隐私脱敏 | 落盘前自动掩码邮箱、手机号、密钥等 | [配置参考](./docs/config.md) |
-| AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活；装了可一键分发技能（`--scope project` 随仓库入库、队友 clone 即用） | [完整攻略](./docs/guide.md#ai-技能包-skills) · [FAQ](./docs/faq.md#工具和-skills-都得装吗) |
-| 配置文件 | 三层（全局 / 项目 / 本地）定制脱敏、告警、导入列映射、语言表；`toolkit config status` 只读查看生效情况与来源 | [CLI 参考](./docs/cli.md#config-1-11-2-新增) · [配置参考](./docs/config.md) |
-
-## 📚 文档
-
-| 文档 | 适合谁 |
-| --- | --- |
-| [新手指南](./docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
-| [操作手册](./docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
-| [完整攻略](./docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
-| [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
-| [API 参考](./docs/api.md) | 作为库引入 Node 项目 |
-| [配置参考](./docs/config.md) | 查配置文件字段（全局 / 项目 / 本地三层） |
-| [更新日志](./docs/changelog.md) | 查各版本变更内容 |
-| [FAQ](./docs/faq.md) | 遇到问题先来这里找 |
-| [推荐 AI 全局规则](./docs/ai-rules.md) | 想让 AI 助手按本工具的最佳实践协作 |
-| [推荐提交信息规则](./docs/commit-rules.md) | 想让 AI 按统一格式写 git 提交信息 |
-| [完整文档站](https://fxri-net.github.io/toolkit/) | 在线阅读体验 |
-
-## 🧩 AI 技能包（skills）
-
-```bash
-pnpm add -g @fxri/toolkit && toolkit skills install   # 装了 CLI 一键分发（npm 用户：npm i -g @fxri/toolkit）
-toolkit skills install --scope project                # 项目面分发：真源与入口薄壳随仓库入库、队友 clone 即用
-pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器（npm 用户：npx skills add fxri-net/toolkit）
-```
-
-技能随包分发（真源为包内 `skills/`），与 CLI 同一发布批次（技能内容版本独立编号）；`toolkit skills install` 默认软链，链接创建失败自动降级副本，`toolkit skills status` 查现场，`toolkit skills remove` 卸载。`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐。
-
-- [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（任务分解与纯展示计划表、逐仓逐任务建档、check、归档 + 任务级规范沉淀为强制终点）
-- [fxri-release-changelog](./skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
-- [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
-
-skills 与工具的关系、只在公司项目激活等说明见 [FAQ](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。
-
-## 📦 安装
-
-```bash
-pnpm add -D @fxri/toolkit        # 项目 devDependency（团队项目推荐，版本随仓库锁定）
-pnpm i -g @fxri/toolkit          # 全局（个人多项目推荐；pnpm 不受 nvm 切版本影响）
-pnpm dlx @fxri/toolkit tasks     # 不安装临时执行
-```
-
-npm / yarn / bun 用户与各方式对比见 [新手指南 · 安装](./docs/getting-started.md#安装)。
-
-## 🔒 隐私脱敏
-
-落盘记录默认脱敏敏感信息：内置邮箱、手机号、身份证、IPv4、内网 URL、JWT、AWS / GitHub / OpenAI / Slack 密钥等 13 类规则，支持自定义规则与禁用。开关三档（CLI 参数 > 环境变量 > 配置文件），详见 [配置参考](./docs/config.md)。
-
-## ⚙️ 环境要求
-
-- Node.js >= 20.19.0（更低版本可安装，changesets 相关子命令不可用，见 [FAQ](./docs/faq.md#node-18-能用吗)）
-
-## 📄 版权信息
-
-作者：唐启云 <tqy@fxri.net>
-
-出品：方弦研究所
-
-版权：Copyright © 2026 唐启云. All rights reserved.
-
-网站：[方弦研究信息网](https://fxri.net:444/)
-
-协议：[MIT License](./LICENSE)
-
-商标："方弦®"为第42类注册商标（注册号89648411），本开源许可不授予商标使用权，详见 [TRADEMARK.md](./TRADEMARK.md)
-
-> 方弦研究所为唐启云个人项目品牌与出品方，非独立法人实体；本软件著作权归唐启云所有。
+<p align="center">
+  <img src="./docs/public/logo.png" width="128" alt="方弦工具集">
+</p>
+
+# 方弦工具集
+
+[![CI](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@fxri/toolkit)](https://www.npmjs.com/package/@fxri/toolkit)
+[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](./docs/getting-started.md#安装)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/toolkit)（与 GitHub 同源同步，仓库/文档/issues/skills 全渠道可用）；问题反馈走 [GitHub Issues](https://github.com/fxri-net/toolkit/issues) 或 [Gitee Issues](https://gitee.com/fxri/toolkit/issues)。
+
+专为**多人 + AI 跨项目协作**打造：任务管理 + 多语言 CHANGELOG。
+
+AI 参与开发后，方案与决策散落在对话记录里，会话一关什么都不剩；任务记录零散，谁在做、做到哪，无从查起；发版 CHANGELOG 还要人肉维护多语言。本工具把这条链路沉淀为**仓库内可检索、可校验、可归档的文件**——人离开会话，记忆留在仓库里。
+
+- **零依赖 AI 技能包（skills）**：方案落盘、发版 CHANGELOG 两套工作流沉淀为 Agent Skills，不绑定任何 AI 工具；skills 可以独立工作，CLI 是可选加速——推荐都装，体验最完整（[什么关系？](./docs/faq.md#工具和-skills-都得装吗)）
+- **不懂 AI 也能用**：任务管理与 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语-先说人话)）
+
+## 🚀 30 秒上手
+
+```bash
+# 1. 项目内安装（推荐，团队共享版本）
+pnpm add -D @fxri/toolkit
+
+# 2. 初始化任务区（生成 .tasks/ 骨架、conventions/ 规范载体与技能入口壳；含本地依赖时写入 prepare 刷新钩子）
+pnpm exec toolkit init
+
+# 3. 查看任务总览
+pnpm exec toolkit tasks
+```
+
+之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。多任务 / 多仓方案先出纯展示计划表，再逐仓逐任务建档、按序逐个交付提交。完整步骤见 [新手指南](./docs/getting-started.md)。
+
+## ✨ 能力矩阵
+
+| 能力 | 适用场景 | 文档 |
+| --- | --- | --- |
+| 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](./docs/cli.md) · [任务文件规范](./docs/guide.md#任务文件规范) |
+| 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](./docs/cli.md#changelog) |
+| 协作规范载体（conventions） | 把任务里提炼的规范收进 `.tasks/conventions/`，成为可检索、可校验的项目规范源；支持结构升级、表格形态归一与只读体检 | [CLI 参考](./docs/cli.md) · [完整攻略](./docs/guide.md#conventions-规范沉淀地) |
+| Node API | 把上述能力嵌进脚本或平台 | [API 参考](./docs/api.md) |
+| 隐私脱敏 | 落盘前自动掩码邮箱、手机号、密钥等 | [配置参考](./docs/config.md) |
+| AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活；装了可一键分发技能（`--scope project` 随仓库入库、队友 clone 即用） | [完整攻略](./docs/guide.md#ai-技能包-skills) · [FAQ](./docs/faq.md#工具和-skills-都得装吗) |
+| 配置文件 | 三层（全局 / 项目 / 本地）定制脱敏、告警、导入列映射、语言表；`toolkit config status` 只读查看生效情况与来源 | [CLI 参考](./docs/cli.md#config-1-11-2-新增) · [配置参考](./docs/config.md) |
+
+## 📚 文档
+
+| 文档 | 适合谁 |
+| --- | --- |
+| [新手指南](./docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
+| [操作手册](./docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
+| [完整攻略](./docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
+| [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
+| [API 参考](./docs/api.md) | 作为库引入 Node 项目 |
+| [配置参考](./docs/config.md) | 查配置文件字段（全局 / 项目 / 本地三层） |
+| [更新日志](./docs/changelog.md) | 查各版本变更内容 |
+| [FAQ](./docs/faq.md) | 遇到问题先来这里找 |
+| [推荐 AI 全局规则](./docs/ai-rules.md) | 想让 AI 助手按本工具的最佳实践协作 |
+| [推荐提交信息规则](./docs/commit-rules.md) | 想让 AI 按统一格式写 git 提交信息 |
+| [完整文档站](https://fxri-net.github.io/toolkit/) | 在线阅读体验 |
+
+## 🧩 AI 技能包（skills）
+
+```bash
+pnpm add -g @fxri/toolkit && toolkit skills install   # 装了 CLI 一键分发（npm 用户：npm i -g @fxri/toolkit）
+toolkit skills install --scope project                # 项目面分发：真源与入口薄壳随仓库入库、队友 clone 即用
+pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器（npm 用户：npx skills add fxri-net/toolkit）
+```
+
+技能随包分发（真源为包内 `skills/`），与 CLI 同一发布批次（技能内容版本独立编号）；`toolkit skills install` 默认软链，链接创建失败自动降级副本，`toolkit skills status` 查现场，`toolkit skills remove` 卸载。`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐。
+
+- [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（任务分解与纯展示计划表、逐仓逐任务建档、check、归档 + 任务级规范沉淀为强制终点）
+- [fxri-release-changelog](./skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
+- [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
+- [fxri-text-encoding](./skills/fxri-text-encoding/SKILL.md)：文本文件的 UTF-8 / BOM / 行尾基线，脚本中文乱码、终端与重定向输出乱码、首行报错的定位与修复
+
+skills 与工具的关系、只在公司项目激活等说明见 [FAQ](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。
+
+## 📦 安装
+
+```bash
+pnpm add -D @fxri/toolkit        # 项目 devDependency（团队项目推荐，版本随仓库锁定）
+pnpm i -g @fxri/toolkit          # 全局（个人多项目推荐；pnpm 不受 nvm 切版本影响）
+pnpm dlx @fxri/toolkit tasks     # 不安装临时执行
+```
+
+npm / yarn / bun 用户与各方式对比见 [新手指南 · 安装](./docs/getting-started.md#安装)。
+
+## 🔒 隐私脱敏
+
+落盘记录默认脱敏敏感信息：内置邮箱、手机号、身份证、IPv4、内网 URL、JWT、AWS / GitHub / OpenAI / Slack 密钥等 13 类规则，支持自定义规则与禁用。开关三档（CLI 参数 > 环境变量 > 配置文件），详见 [配置参考](./docs/config.md)。
+
+## ⚙️ 环境要求
+
+- Node.js >= 20.19.0（更低版本可安装，changesets 相关子命令不可用，见 [FAQ](./docs/faq.md#node-18-能用吗)）
+
+## 📄 版权信息
+
+作者：唐启云 <tqy@fxri.net>
+
+出品：方弦研究所
+
+版权：Copyright © 2026 唐启云. All rights reserved.
+
+网站：[方弦研究信息网](https://fxri.net:444/)
+
+协议：[MIT License](./LICENSE)
+
+商标："方弦®"为第42类注册商标（注册号89648411），本开源许可不授予商标使用权，详见 [TRADEMARK.md](./TRADEMARK.md)
+
+> 方弦研究所为唐启云个人项目品牌与出品方，非独立法人实体；本软件著作权归唐启云所有。

package/TRADEMARK.md

@@ -1,41 +1,41 @@
-# 商标声明
-
-## 基本信息
-
-| 项目 | 内容 |
-|---|---|
-| 商标名称 | 方弦® |
-| 商标类型 | 文字商标 |
-| 商标说明 | 商标由文字"方弦"组成 |
-| 商标类别 | 第42类（共10项） |
-| 注册号 | 89648411 |
-| 申请人 | 唐启云 |
-| 递交商标局 | 2026-01-12 |
-| 版本 | 基础版 |
-
-## 第42类服务项目
-
-计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
-
-## 权利状态
-
-"方弦®"商标（注册号89648411）已获中国国家知识产权局商标局核准注册，核定使用于第42类上述服务项目，现为注册商标。
-
-## 授权范围
-
-本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
-
-任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
-
-## 使用规范
-
-- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦®"指代本项目名称
-- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
-
-## 获取授权
-
-如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
-
-## 侵权处理
-
-如发现未经授权使用"方弦®"商标的行为，请通过上述联系方式举报。
+# 商标声明
+
+## 基本信息
+
+| 项目 | 内容 |
+|---|---|
+| 商标名称 | 方弦® |
+| 商标类型 | 文字商标 |
+| 商标说明 | 商标由文字"方弦"组成 |
+| 商标类别 | 第42类（共10项） |
+| 注册号 | 89648411 |
+| 申请人 | 唐启云 |
+| 递交商标局 | 2026-01-12 |
+| 版本 | 基础版 |
+
+## 第42类服务项目
+
+计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
+
+## 权利状态
+
+"方弦®"商标（注册号89648411）已获中国国家知识产权局商标局核准注册，核定使用于第42类上述服务项目，现为注册商标。
+
+## 授权范围
+
+本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
+
+任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
+
+## 使用规范
+
+- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦®"指代本项目名称
+- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
+
+## 获取授权
+
+如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
+
+## 侵权处理
+
+如发现未经授权使用"方弦®"商标的行为，请通过上述联系方式举报。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fxri/toolkit",
-  "version": "1.12.5",
+  "version": "1.13.0",
   "description": "专为多人 + AI 跨项目协作打造：任务管理 + 多语言 CHANGELOG。",
   "license": "MIT",
   "author": {

package/skills/README.md

@@ -8,9 +8,10 @@
 
 | 技能 | 版本 | 用途 |
 | --- | --- | --- |
-| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.9.3 | 方案落盘：任务分解与纯展示计划表 → 逐仓逐任务建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
+| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.9.4 | 方案落盘：任务分解与纯展示计划表 → 逐仓逐任务建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
 | [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.2.1 | changesets 发版与多语言 CHANGELOG 维护 |
-| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.6.0 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
+| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.6.2 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
+| [fxri-text-encoding](./fxri-text-encoding/SKILL.md) | 1.0.0 | 文本编码：按「生产者 × 消费者」定文件字节与进程管道编码，处置脚本乱码、终端与重定向输出乱码、乱码反查与不可见字符、首行报错 |
 
 版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致。
 

package/skills/fxri-plan-to-task/SKILL.md

@@ -3,14 +3,14 @@ name: fxri-plan-to-task
 description: 将已确认的实施方案分解为可独立交付的任务并给出计划表，再落盘为标准任务文件并跟踪至归档：建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查、任务级规范沉淀与归档。方案确认后表达「开始落地/登记记录」的意图，或即将改仓库文件时使用——含任务分解、建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录、v1 / v2 升 v3）等说法及口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
 license: MIT
 metadata:
-  version: "1.9.3"
+  version: "1.9.4"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 方案落盘：任务建档与归档
 
-> 本技能版本 1.9.3（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.9.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 

package/skills/fxri-plan-to-task/assets/active-task-template.md

@@ -1,13 +1,13 @@
----
-owner: <负责人 git 用户名>
-status: 待办
-created: <创建日 YYYYMMDD>
-updated: <创建日 YYYYMMDD，随每次修改同步>
-completed: ''
-depends_on: []
-scope: <影响范围>
----
-
-# 任务标题
-
-（方案正文：背景、实施方案、影响范围、验证方式）
+---
+owner: <负责人 git 用户名>
+status: 待办
+created: <创建日 YYYYMMDD>
+updated: <创建日 YYYYMMDD，随每次修改同步>
+completed: ''
+depends_on: []
+scope: <影响范围>
+---
+
+# 任务标题
+
+（方案正文：背景、实施方案、影响范围、验证方式）

package/skills/fxri-plan-to-task/references/conventions-migration.md

@@ -45,7 +45,7 @@
 
 1. **索引表删两列**：删「状态」「确立来源任务」两列
 2. **`history.md` 表头归一**：v2 存量 `history.md` 沿用「规则 ID / 名称」旧表头，首格归一为稳定 ID `ID`（与索引表首列同归一）
-3. **退休条目迁出**：把原状态为 `已废弃` 的行迁入 `retired.md`（首部补 `# 规范退休记录`、元规则与 7 列表头），并从 Z1 索引表删除；同步删除 Z2 分册内对应小节（三层清理的索引 + 分册两层）
+3. **退休条目迁出**：把原状态为 `已废弃` 的行迁入 `retired.md`（首部补 `# 规范退休记录`、元规则与固定表头 `ID | 规则 | 退休时语义（冻结） | 归属 | 后继 | 退休来源任务 | 条文去向`），并从 Z1 索引表删除；同步删除 Z2 分册内对应小节（三层清理的索引 + 分册两层）
 4. **`retired.md` 按需建**：无退休条目则不创建该文件
 5. **来源 / ID 补录报告**：`history.md` 中 ID 列仍用规则名者、来源列含多任务者，输出人工复核报告——**不做全自动改写**（历史行只追加不改旧的元规则下，改写须人工确认）
 6. **用法说明 / 写入纪律复核**：`index.md` 表外的自由文本（用法说明、写入纪律）若仍残留 v2 措辞（如「填『确立来源任务』」「把『状态』改为『已废弃』」），输出人工复核报告——升级只机械归一索引表列结构，不改写描述该表的自由文本

package/skills/fxri-plan-to-task/references/conventions-spec.md

@@ -4,6 +4,8 @@
 
 ## 1. 载体结构
 
+> `.tasks/` 外层骨架（`active/` / `archive/` / `conventions/` 三目录与命名）以 `task-spec.md` §1 为真源；本节只展开 `conventions/` 内部结构。
+
 ```
 .tasks/
 ├── active/                    # 进行中的任务

package/skills/fxri-session-recap/SKILL.md

@@ -3,14 +3,14 @@ name: fxri-session-recap
 description: 会话收尾的工作记忆沉淀 + 新会话开场恢复 + 历史任务时间修正：收尾时把整场会话的全部任务完整建档归档，按四级时间源还原真实完成时间，沉淀规范进 conventions 载体；新会话开场按三层恢复（全量索引 + active 精读 + 近窗归档）重建现场并核对规范；也可批量修正历史归档时间。用户表达会话收尾意图（今天先到这、收个尾、归档本次会话、把结论记下来）、接续意图（恢复上下文、继续上次、上次做到哪）或修正历史任务时间时使用。不用于会话中途的常规方案建档（那是 fxri-plan-to-task 的职责）、与工作交接无关的代码技术总结。
 license: MIT
 metadata:
-  version: "1.6.0"
+  version: "1.6.2"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 会话归档、上下文恢复与历史修正
 
-> 本技能版本 1.6.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.6.2（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 

package/skills/fxri-session-recap/references/mode-2-recovery.md

@@ -8,6 +8,6 @@
 2. **L1 工作层精读**：逐文件读 `.tasks/active/` 全部任务（决策、进展、阻塞）。⚠️ **搁置识别**：active 任务 `updated` 距今 >1 年时标注「疑似搁置（距今 X 年）」，建议用户确认收尾或放弃，不当「进行中」呈现
 3. **L2 近窗精读**：读最近归档。**近窗按时间连续性判定，不按数量**：先定位最新归档块的完成时间，只精读从该时刻向前连续活跃的归档（归档月份 ≤ 6 个月或归档块 ≤ 200 条时精读全文）；**被 ≥1 年空洞隔断的旧归档一律只入 L0 索引，不精读、不列为「最近完成」**；超阈值降级为统计（按月/负责人汇总 + 近期明细），防止历史膨胀撑爆上下文
 4. **按需拉取**：更早历史（含空洞隔断的旧归档）不主动展开，在 L0 索引可见；用户点名、或 AI 判断相关时用 `--owner`/`--date` 过滤检索；用户明确说「全部恢复」才全量列出
-5. **规范核对与提炼**：读 conventions 载体（存在时）纳入现场——常驻只读 `index.md`（`history.md` 与各分册按需读），再按任务 `scope` 命中加载 `common.md` 与端分册；载体为 v1 或 `check` / `toolkit conventions status` 报形态告警时提示用户可升级（升级链路见 `../../fxri-plan-to-task/references/conventions-migration.md`）；对照近期任务按主文件「规范提炼子流程」提议增改——⚠️ 恢复主体只读，写载体是用户确认后的独立动作
+5. **规范核对与提炼**：读 conventions 载体（存在时）纳入现场——常驻只读 `index.md`（`history.md` / `retired.md` 与各分册按需读），再按任务 `scope` 命中加载 `common.md` 与端分册；载体为 v1 / v2 或 `check` / `toolkit conventions status` 报形态告警时提示用户可升级（升级链路见 `../../fxri-plan-to-task/references/conventions-migration.md`；该兄弟路径不存在时改读包内真源——`toolkit skills status` 打印的「技能源」目录下同名文件）；对照近期任务按主文件「规范提炼子流程」提议增改——⚠️ 恢复主体只读，写载体是用户确认后的独立动作
 6. **输出**：全部任务索引摘要 → 进行中/阻塞任务（含搁置标注）→ 最近完成（连续活跃期内，不含空洞旧档）→ 未完事项 → **多任务执行顺序**（会话留有展示型计划表则按表；无表时按各 active 任务正文的「批次 / 计划位置 / 前置」行重建）→ 规范现场 → **建议的下一步**
 7. 全程不写任务区文件；对存疑内容向用户确认后再动

package/skills/fxri-text-encoding/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: fxri-text-encoding
+description: 新建、改写、生成、转码 `.ps1`、`.bat`、`.cmd`、`.sh`、`.properties`、给 Excel 的 `.csv` 等文本文件之前，先按读取方定字符集、BOM 与行尾；AI 自己用文件写入 / 编辑工具落盘后立即自查首三字节（这类工具默认不写 BOM）。也用于乱码归属：终端或命令输出中文变问号、重定向出的文件后续解析失败、`Get-Content` 读 UTF-8 文件乱码、管道传给原生命令变 `?`、编译报看不见的非法字符——含编码、字符集、BOM、乱码、转码、换行、CRLF、LF、UTF-8 BOM、chcp、locale、stdout 编码等说法及口语近义表达（中文变问号、打开是乱码）。事后定位同样适用：PowerShell 报 Missing closing、脚本首行命令报错、JSON 带 BOM 解析失败、跨平台分发脚本打不开。不用于 Base64 / URL 编码、排序与字符计数、文件名规范化、CSV 语法、路径分隔符、时区，也不用于 git 提交信息、任务建档或代码风格。
+license: MIT
+metadata:
+  version: "1.0.0"
+  author: fxri
+  source: https://github.com/fxri-net/toolkit
+---
+
+# 文本编码与字节形态
+
+> 本技能版本 1.0.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+
+## 何时使用
+
+写之前先定字符集、BOM、行尾三件套；AI 写入工具落盘后立刻判首三字节（见「写盘」）；出错先走乱码三问，文件侧查速查表，运行期查「跑起来乱码」。
+
+## 先分归属（乱码三问）
+
+故障是「写入方字节」×「读取方默认解码」，与操作系统无关；看到乱码先走三问，别凭感觉改文件：
+
+1. **是谁的字节？** 重定向到文件看首字节：字节对但显示乱 → 终端或管线解码错；字节本身错 → 生产者编码错
+2. **还能救吗？** 出现 `�`（U+FFFD）说明解码已失败、原字节丢失，**不可逆**；无 `�` 的多为 mojibake，可反向转码
+3. **错在第几跳？** `涓枃` = UTF-8 被当 GBK 读；`ä¸æ–‡` = UTF-8 被当 Latin-1 读；`ÖÐÎÄ` = GBK 被当 Latin-1 读。只修认出的那一跳，别整条链重来
+
+第 1 问的判据——读取方无 BOM 时按什么解码：
+
+| 读取方 | 默认解码 |
+| --- | --- |
+| `powershell.exe`、Excel、`cmd` 与多数 Windows 老工具 | 系统 ANSI 或 OEM 代码页（简体中文均为 936） |
+| 记事本 | Win10 1903 起先试 UTF-8、失败回落 ANSI，「打开正常」不能当编码证据 |
+| `pwsh`、Node、Python 3、Go、Rust | UTF-8 |
+| bash / sh / 各语言 `open()` | 按 locale，`LANG=C` 时为 ASCII |
+
+第 2、3 问的处置——按特征串选反向转码（先备份原件，转完核对本意）：
+
+- `涓枃` 类 `iconv -f GBK -t UTF-8`；`ä¸æ–‡` 类 `-f ISO-8859-1`
+- 无 iconv 时：`[Text.Encoding]::UTF8.GetString([Text.Encoding]::GetEncoding(936).GetBytes($s))`，Latin-1 把 936 换 28591
+
+## 基线决策（按文件类型）
+
+| 文件类型 | 字符集 | BOM | 行尾 | 理由 |
+| --- | --- | --- | --- | --- |
+| `.ps1` / `.psm1` / `.psd1` | UTF-8 | 有 | 均可 | `powershell.exe` 无 BOM 即按 ANSI 解码，中文必炸 |
+| `.bat` / `.cmd` | ASCII 优先；必须中文时用系统 ANSI | 无 | CRLF | BOM 会让首条命令报错 |
+| `.sh` / `Makefile` / 带 shebang 的脚本 | UTF-8 | 无 | LF | BOM 会污染 shebang |
+| `.md` / `.ts` / `.js` / `.json` / `.yml` / `.toml` / `.xml` | UTF-8 | 无 | LF | 工具链默认；JSON 带 BOM 多解析失败，XML 改字节而非只改声明 |
+| `.properties` | Latin-1 + `\uXXXX`，或 `load(Reader)` 显式 UTF-8 | 无 | LF | `load(InputStream)` 固定按 ISO-8859-1 读 |
+| C / C++ / Java 源文件 | UTF-8 | 有；或加 `/utf-8` / `-encoding UTF-8` | LF | MSVC 按系统代码页读源文件，无 BOM 中文报 C4819 |
+| 交给 Excel 的 `.csv` | UTF-8 | 有 | 遵循目标平台 | 无 BOM 时 Excel 按 ANSI 解码 |
+
+即便只在 `pwsh` 下跑也统一带 BOM——脚本常在别人机器上跑；`.psm1` / `.psd1` 同理。
+
+## 写盘：谁在悄悄改字节
+
+| 写法 | 实际行为 |
+| --- | --- |
+| AI 文件写入 / 编辑工具；编辑器「保存为 UTF-8」 | 不写 BOM，须写完补或写入时前置 `\uFEFF` |
+| `powershell.exe` `Set-Content` / `Add-Content` | 省略 `-Encoding` 按系统 ANSI 写，UTF-8 中文落盘即坏；`-Encoding UTF8` 写 BOM |
+| `powershell.exe` `Export-Csv` 省略 `-Encoding` | 写 ASCII，中文直接变 `?`；加 `-Append` 时编码又与新建不同 |
+| `pwsh` `Set-Content` / `Out-File` / `>` | 默认 `utf8NoBOM`，要 BOM 显式 `utf8BOM` |
+| .NET `[IO.File]::WriteAllText` / Node `fs.writeFileSync` | 均不写 BOM，须分别传 `[Text.UTF8Encoding]::new($true)`、前置 `"\uFEFF"` |
+| Python `open(p, "w", encoding="utf-8-sig")` | 写 BOM；`"utf-8"` 不写；省略 `encoding` 走 locale |
+| `.editorconfig` `charset` / git `.gitattributes` | 前者只在编辑器保存时生效；后者 `eol=` 管行尾、`working-tree-encoding=` 管编码，**都不补 BOM** |
+
+⚠️ 两者同名不同义：要在两种 shell 下都跑，用 `[Text.UTF8Encoding]::new($true)` 显式指定；`utf8BOM` 只有 `pwsh` 认。
+
+写完立刻自查（AI 写入工具默认无 BOM，是本类故障最常见来源）：
+
+1. 新建或改写 `.ps1` 后判首三字节，不是 `EF BB BF` 当场补，别等运行时报错
+2. 批量生成、打包、格式化钩子跑完后抽查产物，并回跑一次生成脚本——只补产物不修产线，下次还会丢
+3. 纯内联 `-Command` 不落盘的没有文件侧问题，运行期另查下一节
+
+判工具：`powershell.exe` `[IO.File]::ReadAllBytes($p)[0..2] -join ','`（`239,187,191` 即有 BOM）、Node `fs.readFileSync(p).subarray(0,3).toString("hex")`（`efbbbf`）、bash `head -c 3 f | xxd -p`；行尾 `file f` 报 `with CRLF, LF line terminators` 即混用；末尾缺换行 `tail -c 1 f | xxd -p` 非 `0a` 即缺。
+
+Node `readFileSync(p, "utf8")` 会保留 `\uFEFF`，解析前 `s.replace(/^\uFEFF/, "")`；补 BOM（内容已是 UTF-8）用 `[IO.File]::WriteAllText($p, [IO.File]::ReadAllText($p), [Text.UTF8Encoding]::new($true))`，Node 读回后前置 `"\uFEFF"`。
+
+全仓巡检：`git ls-files '*.ps1' '*.sh' '*.csv' '*.bat'` 列出目标后逐个判首三字节；行尾混用一次性捞全 `git ls-files -z | xargs -0 file | grep CRLF`。人眼抽查只用于验证产线，别当门禁。
+
+## 组合速查：文件字节类
+
+| 现象 | 根因 | 处置 |
+| --- | --- | --- |
+| `powershell.exe` 报 `Missing closing '}'` / `Unexpected token`，文件看着没问题 | `.ps1` 无 BOM，中文被按 ANSI 解码 | 转 UTF-8 with BOM，逻辑不变 |
+| `.bat` / `.cmd` 首行就报命令不存在 | 文件带 BOM | 去 BOM，中文改由 `.ps1` 承担 |
+| Linux 侧 `.sh` 报 `$'\r': command not found` | CRLF | 转 LF，`.gitattributes` 用 `eol=lf` 固化 |
+| 仓库里是 LF，检出后 `.sh` 变 CRLF；已配 `eol=lf` 但 CI 仍报 `$'\r'` | `core.autocrlf=true` 在检出时转换；属性只约束后续写入，不回溯已提交内容 | `.gitattributes` 写 `eol=lf` 覆盖本机设置；存量执行 `git add --renormalize .` 后提交 |
+| Excel 打开 CSV 乱码，或另存出的 CSV 进程序后乱码 | 打开侧无 BOM 按 ANSI 解码；另存侧 Excel 按系统 ANSI 写 | 打开侧加 BOM（Python 写用 `utf-8-sig`）；导出选「CSV UTF-8（逗号分隔）」或入库前转 UTF-8 |
+| `JSON.parse` 报 `Unexpected token` 但内容正常 | 首字节 `EF BB BF` | 去 BOM |
+| XML 报声明与实际编码不符 | `encoding=` 写 GBK 而实际 UTF-8 | 统一实际字节为 UTF-8，别只改声明 |
+| 同一文件同事机器正常、本机乱码 | 那台机器开了「Beta: 使用 Unicode UTF-8 提供全球语言支持」，系统 ANSI 已变 UTF-8 | 别依赖该设置，仍按基线写 BOM |
+
+## 组合速查：内容类
+
+| 现象 | 根因 | 处置 |
+| --- | --- | --- |
+| 编译报「非法字符 / unexpected character」但该行看不见异常 | 不可见字符：NBSP `U+00A0`、全角空格 `U+3000`、零宽空格 `U+200B`、中段 BOM `U+FEFF`、双向控制 `U+200E/200F` | 定位后替换，见下方命令 |
+| 代码报语法错，字符看着像英文标点 | 全角标点 `“”（）：，；－` | 全文替换为半角，检查输入法全角态 |
+| Python 输出 `\u4e2d\u6587`、git 把中文路径显示成 `\346\226\207` | `json.dump` 默认 `ensure_ascii=True`；`core.quotepath` 默认开启 | 分别传 `ensure_ascii=False`、`git -c core.quotepath=false`，都不是乱码 |
+
+定位不可见字符：GNU grep `grep -nP '[\x{00A0}\x{200B}\x{3000}\x{FEFF}\x{200E}\x{200F}]' f`；`powershell.exe` `Select-String -Path f -Pattern '[\u00A0\u200B\u3000\uFEFF\u200E\u200F]'`。
+
+## 跑起来乱码（不落盘）
+
+命令执行中乱码多为管线问题，源文件可能正常：先按第 1 问判归属，再查下表。
+
+| 断点 | 现象 | 处置 |
+| --- | --- | --- |
+| 控制台代码页（简体默认 936） | 原生命令输出 UTF-8 中文显示乱码 | `chcp 65001` + `[Console]::OutputEncoding = [Text.UTF8Encoding]::new()` |
+| `powershell.exe` `$OutputEncoding` 默认 ASCII | PS 管道把中文传给原生命令后变 `?` | 先设 `$OutputEncoding = [Text.UTF8Encoding]::new()` |
+| `powershell.exe` `>` / `Out-File` 默认 UTF-16LE | 重定向出的 `.json` / `.csv` 后续解析失败 | 改 `-Encoding utf8` 或 `[IO.File]::WriteAllText`；`pwsh` 默认 UTF-8 无 BOM |
+| `powershell.exe` `Get-Content` 对无 BOM 文件按 ANSI | 读 UTF-8 文件得乱码，误判文件损坏 | 显式 `-Encoding utf8`；`pwsh` 默认 UTF-8 |
+| Node 输出被 `powershell.exe` 读 | 控制台 UTF-16 显示正常，落文件是 UTF-8，再读就乱 | 读侧显式编码，别改 Node 侧 |
+| Python 用 locale 编码 | 非 ASCII 报 `UnicodeEncodeError` 或输出 `?` | `PYTHONUTF8=1` 或 `PYTHONIOENCODING=utf-8` |
+| 容器 / CI `LANG=C`、`LC_ALL=C` | 本地正常，线上同上报错 | 设 `LANG=C.UTF-8`，或注入 `PYTHONIOENCODING=utf-8` |
+| Java 运行期 `file.encoding` | JDK 18 前在 Windows 默认 GBK，读写出乱码 | `-Dfile.encoding=UTF-8` |
+
+⚠️ 别因 stdout 乱码就回头改源文件；`file -i` 与 chardet 对短文本误判率高，只作参考。
+
+## 修复纪律
+
+1. **消灭组合条件并固化**：能不带 BOM 的格式就别带；必须带的统一基线，写进 `.gitattributes`（`eol` / `working-tree-encoding`）、`.editorconfig`（`charset`）与项目文档
+2. **机器校验**：生成后或 CI 断言首三字节与行尾，不靠人眼
+3. **只转一次、不只补产物**：转码前确认原始编码（`�` 不可逆，回源重取）；BOM 反复丢失一定有一处在重写文件，先定位那次写入再补