PowerToys 模块开发文档体系：全模块文档索引、组织结构与新增文档规范

本篇以 PowerToys 官方开发文档的模块文档索引（doc/devdocs/modules/readme.md）为核心，完整梳理仓库中 27 份 PowerToy 模块开发文档的覆盖范围与检索路径，并结合核心架构文档与「新建 PowerToy」指南，讲解模块文档的目录组织方式、典型文档结构以及为模块补充开发文档时的规范步骤，帮助贡献者快速定位任一模块的实现细节、调试工具与文档撰写入口。

1. 模块文档定位：PowerToys 开发文档的核心索引

PowerToys 是 Microsoft 面向 Windows 的一系列生产力与个性化增强工具集合。整个仓库的开发者文档集中在 doc/devdocs/ 目录下，其中 doc/devdocs/modules/ 子目录专门收录各 PowerToy 模块的开发向文档，内容涵盖：

• 模块架构（architecture）；
• 实现细节（implementation details）；
• 配套调试工具（debugging tools）。

需要区分两类文档：

1. 开发文档：位于 doc/devdocs/modules/，面向开发者，说明模块架构、关键文件、测试方式与调试技巧。按照 新建 PowerToy 指南 的要求，提交新模块时这类文档是必需项；
2. 用户文档：发布时由团队同步到 Microsoft Learn 站点的公开文档，供终端用户了解模块用法，开发者一般无需承担这部分工作。

模块开发文档与以下核心文档构成完整知识网，建议配合阅读：

文档	相对路径	作用
核心架构说明	doc/devdocs/core/architecture.md	模块接口（Module Interface）总览、模块分类、公共依赖
Runner 说明	doc/devdocs/core/runner.md	PowerToys.exe 如何加载模块、传递事件、桥接设置界面
新建 PowerToy 端到端指南	doc/devdocs/development/new-powertoy.md	从模块接口、设置集成、WiX 打包到测试验证的完整流程
模块文档索引（本文主体）	doc/devdocs/modules/readme.md	所有模块开发文档的入口

2. 可用模块文档总览（Available Modules）

索引文档以表格形式列出了当前仓库已覆盖全部开发文档的模块。下表完整继承原文档的模块清单，链接已转换为以仓库根目录起点的相对路径：

模块	开发文档	功能描述
Advanced Paste	advancedpaste.md	增强剪贴板粘贴，支持多种格式选项
Always on Top	alwaysontop.md	将窗口置顶固定在其他窗口之上
Awake	awake.md	在不修改电源设置的前提下保持电脑不休眠
Color Picker	colorpicker.md	从屏幕任意位置拾取并管理颜色
Command Not Found	commandnotfound.md	当命令缺失时提示可安装的软件包
Crop and Lock	cropandlock.md	将应用窗口裁剪为更小的窗口或缩略图
Environment Variables	environmentvariables.md	管理用户与系统环境变量
FancyZones	fancyzones.md（调试工具：fancyzones-tools.md）	自定义窗口布局的窗口管理工具
File Explorer add-ons	fileexploreraddons.md	增强 Windows 资源管理器的扩展
File Locksmith	filelocksmith.md	查找锁定某文件的进程
Hosts File Editor	hostsfileeditor.md	管理系统 hosts 文件
Image Resizer	imageresizer.md	在资源管理器中快速批量调整图片尺寸
Keyboard Manager	keyboardmanager/README.md	重新映射按键与快捷键
Mouse Utilities	mouseutils/readme.md	增强鼠标与光标功能的一组工具
Mouse Without Borders	mousewithoutborders.md	用一套键鼠控制多台电脑
NewPlus	newplus.md	资源管理器右键扩展，快速新建文件
Peek	peek/readme.md	快速查看文件内容的预览工具
Power Rename	powerrename.md	支持查找替换的批量重命名工具
PowerToys Run	launcher/readme.md	快速应用启动与搜索工具（原索引文档标注为「即将弃用」）
Quick Accent	quickaccent.md	快速插入带重音字符与特殊符号
Registry Preview	registrypreview.md	可视化查看与编辑注册表文件
Screen Ruler	screenruler.md	在屏幕上测量像素距离与颜色边界
Shortcut Guide	shortcut_guide.md	按住 Windows 键时展示键盘快捷键指南
Text Extractor	textextractor.md	从图片或截图中提取文本
Workspaces	workspaces.md	保存并恢复不同项目的窗口布局
ZoomIt	zoomit.md	屏幕缩放与标注工具

对照源码目录 src/modules/ 可以看到，每份文档都对应一个真实的模块工程目录（如 src/modules/colorPicker/、src/modules/fancyzones/、src/modules/keyboardmanager/、src/modules/launcher/ 等），文档与代码一一对应，便于边读文档边查源码。

3. 文档组织结构：扁平文件与模块子目录并存

浏览 doc/devdocs/modules/ 目录可以发现，文档组织上存在两种形态，各自对应不同复杂度的模块：

3.1 单文件文档（扁平 .md）

绝大多数模块使用单个 Markdown 文件承载全部开发文档，例如 colorpicker.md、awake.md、fancyzones.md。这类文档通常遵循相近的章节结构，以 Color Picker 为例，其内容脉络为：

• Overview：模块定位（如 Color Picker 是一个系统级取色工具，可从屏幕任意位置取色并按可配置格式复制到剪贴板）；
• Implementation Details：核心实现原理与关键代码片段。例如 Color Picker 的取色流程为「获取鼠标坐标 → 构造 1×1 矩形 → 创建 Bitmap 与 Graphics 对象 → 通过 CopyFromScreen 捕获指定位置的像素信息」，并给出了 GetPixelColor 函数的完整 C# 实现；
• Features / User Experience：功能清单与交互体验说明；
• Command Line Support（部分模块）：面向自动化场景的命令行能力说明。

3.2 多页子目录文档（复杂模块）

文档量较大的模块采用独立子目录，将内容拆分为多个专题页：

子目录	文档构成
keyboardmanager/	README 总览 + 主模块实现（keyboardmanager.md）、公共库（keyboardmanagercommon.md）、UI 层（keyboardmanagerui.md）、按键事件处理（keyboardeventhandlers.md）、调试指南（debug.md）
mouseutils/	readme 总览 + 各子工具分篇：Mouse Jump（mousejump.md）、Mouse Pointer（mousepointer.md）、Mouse Highlighter（mousehighlighter.md）、Find My Mouse（findmymouse.md）
launcher/	readme 总览 + 架构（architecture.md）、调试（debugging.md）、项目结构（project_structure.md）、遥测（telemetry.md）、新插件开发清单（new-plugin-checklist.md），以及 plugins/ 子目录下 16 个插件的独立文档（如 calculator.md、shell.md、windowssettings.md 等）
peek/	单页 readme 承载 Peek 预览工具文档

此外，索引中还体现了「调试工具独立成篇」的惯例：FancyZones 在模块主文档之外，单独提供了调试工具文档 fancyzones-tools.md，与 tools/ 目录下的配套调试工程（如 FancyZone_HitTest、FancyZones_DrawLayoutTest）相互印证。

3.3 文档中的模块分类视角

阅读各模块文档前，可以参考 核心架构文档 对模块类型的划分，快速建立预期：

1. Simple Modules（简单模块）：逻辑完全内聚于模块接口 DLL 中，无独立外部应用，例如 Mouse Pointer Crosshairs；
2. External Application Launchers（外部应用启动器）：热键触发时启动独立应用（如 Color Picker 的 WPF 应用），通过命名管道等 IPC 机制通信；
3. Context Handler Modules（上下文处理模块）：以 Shell 扩展形式在资源管理器中注册右键菜单项（如 Power Rename）；
4. Registry-based Modules（注册表模块）：在启用/禁用时注册预览处理器、缩略图提供程序并操作注册表（如 Power Preview）。

这种分类帮助读者判断一份模块文档会侧重讲解接口逻辑、IPC 通信、Shell 扩展注册还是注册表操作。

4. 为模块新增/补充开发文档的规范

索引文档末尾定义了「Adding New Module Documentation」的四步规范，是贡献文档时必须遵循的流程：

1. 创建模块专属 Markdown 文件：命名为 modulename.md，与模块名对应；
2. 视需要拆分调试工具文档：如果模块带有专用调试工具，考虑单独创建 modulename-tools.md（参照 FancyZones 的 fancyzones-tools.md 先例）；
3. 更新本索引：在 doc/devdocs/modules/readme.md 的 Available Modules 表格中补充指向新文档的链接；
4. 遵循既有文档结构：参照同目录下现有文档的章节编排，保持全站文档风格一致。

结合 新建 PowerToy 指南 中「Documentation」一节的补充要求，完整的新模块文档标准还应包括：

• 文档必须存放在 doc/devdocs/modules/ 下（即本文所在目录）；
• 内容应当告诉开发者「如何在这个模块上工作」，具体需要覆盖：模块架构、关键文件、测试方式，以及必要时的调试技巧；
• 用户向的 Microsoft Learn 文档由团队在模块合入后另行编写，开发者在 PR 中保持关注、按需补充信息即可。

5. 结合文档索引的实战导航路径

基于上述索引，推荐的查阅顺序如下：

1. 定位模块：从 模块文档索引 的表格中找到目标模块的文档链接；
2. 理解全局机制：先读 core/architecture.md 了解模块接口（模块接口 DLL 定义了热键结构、名称与键值、配置管理、启用/禁用、遥测与 GPO 配置等标准交互面），再读 core/runner.md 理解 Runner 如何加载模块并将注册事件分发给模块；
3. 深入模块实现：阅读目标模块文档中的 Implementation Details 章节，并对照 src/modules/<ModuleName>/ 下对应源码；
4. 调试与验证：参考模块文档中的调试章节（如 keyboardmanager/debug.md、launcher/debugging.md），配合 development/debugging.md 的通用调试步骤，日志位于 %LOCALAPPDATA%\Microsoft\PowerToys\RunnerLogs 与 %LOCALAPPDATA%\Microsoft\PowerToys\Module\Service\<version>；
5. 新增模块时：按 new-powertoy.md 的端到端流程实现模块，并使用 tools/project_template/ 模板生成模块接口起步代码，最后按第 4 节的四步规范补齐文档并更新索引表格。

6. 小结

doc/devdocs/modules/readme.md 作为 PowerToys 全部模块开发文档的总入口，其价值在于：以一张 27 项模块清单提供了「模块功能 → 开发文档 → 源码目录」的完整映射，并以四条明确规则约束了新文档的命名、拆分与索引维护方式。对于维护者而言，该索引是查找模块架构与调试工具的第一跳；对于贡献者而言，遵循其文档规范（modulename.md 命名、可选 -tools.md 拆分、更新索引表格、保持结构一致）是文档合入的前置条件。