怪兽密码助手

一个面向 Windows 11 的个人密码保存助手。它支持手动录入、区域截图或粘贴图片识别、浏览器 CSV 导入、分类分页搜索、Windows Hello / PIN 便捷解锁和加密备份。

#安装

#使用安装程序

1. 从项目的 GitHub Releases 下载 PasswordAssistant-0.3.0-win-x64-setup.exe；自行构建时，安装包位于 artifacts/installer。
2. 安装器没有商业代码签名。Windows SmartScreen 首次可能显示“Windows 已保护你的电脑”，确认文件来自本项目后，可选择“更多信息”再选择“仍要运行”。
3. 按安装向导继续。默认安装到 %LOCALAPPDATA%\Programs\PasswordAssistant，不需要管理员权限，也不需要单独安装 .NET 运行时。
4. 如需桌面快捷方式，在安装向导的“附加任务”中勾选“创建桌面快捷方式”。
5. 安装完成后勾选“启动怪兽密码助手”，或从开始菜单打开“怪兽密码助手”。

#免安装运行

artifacts/publish/PasswordAssistant.exe 是自包含版本，可以直接运行。移动它不会移动保险库，个人数据仍默认保存在 %LOCALAPPDATA%\PasswordAssistant。

#更新与卸载

• 安装新版本前先退出系统托盘中的旧实例，再运行新版安装程序覆盖安装。
• 可在 Windows 11 的“设置 → 应用 → 已安装的应用”中卸载“怪兽密码助手”。
• 卸载程序不会删除 %LOCALAPPDATA%\PasswordAssistant 中的保险库。需要彻底清除数据时，请先确认备份可用，再手动删除该目录。

#首次使用

1. 第一次启动会显示“创建本机保险库”。输入至少 12 个字符的主密码并再次确认。
2. 需要核对输入时勾选“显示主密码”。
3. 点击“创建保险库”进入主界面。主密码无法找回，忘记后无法解锁现有数据和备份。
4. 后续启动只需输入主密码并点击“解锁”。

如已在 Windows“设置 → 账户 → 登录选项”中配置 PIN 或 Windows Hello，可在应用设置中启用便捷解锁。启用时仍需输入一次当前主密码并完成系统验证。

#保存凭据

#手动新增

1. 点击左侧“手动新增”。
2. 根据需要填写名称、类型、网址或应用、账号、密码、标签和备注。
3. 密码右侧的眼睛按钮可以切换明文和隐藏状态。
4. 至少填写一个字段即可保存，缺少名称、账号或密码不会阻止保存。

#配置 AI 识别

首次进行截图或图片识别前，点击左侧“AI 与应用设置”，填写：

• 完整接口地址：OpenAI 兼容的 /v1/chat/completions 完整地址。远程接口必须使用 HTTPS，本机回环地址可以使用 HTTP。
• 模型：必须同时支持图片输入和 JSON 输出的视觉模型。
• API Key：服务商提供的 Bearer API Key，可用右侧眼睛按钮查看输入。
• 备用模型：可选。填写备用接口地址、模型和 API Key 后，主模型遇到网络或 HTTP 错误、超时、无效 JSON 时会自动尝试备用模型一次；主动取消不会触发切换。
• 超时：单次识别最长等待秒数。
• 隐私确认：勾选“我了解原始截图会发送给所配置的 AI 服务”。

点击“测试连接”时，应用只发送自动生成的虚拟账号图片，不会发送保险库中的真实数据。测试成功后点击“保存 AI 设置”。

#截图识别

1. 在网站或应用中打开需要保存的信息。只有截图里直接显示的文字可以被识别，圆点、星号或模糊遮挡的密码不会被猜测。
2. 按 Ctrl+Alt+S，或点击左侧“截图识别”。
3. 在多显示器桌面上拖动选择要识别的区域，松开鼠标后开始识别；按 Esc 可以取消。
4. 在“确认识别结果”窗口中核对截图预览和所有字段。AI 没有识别到的字段会保持为空，不会导致整次识别失败。
5. 备注、标签和警告要求模型使用简体中文输出。仍应人工核对，可直接修改后再点击“确认保存”。
6. 如果名称或应用和账号与已有记录相同，应用会提示更新现有记录或另存一条，不会静默覆盖。

#粘贴或拖入图片

• 先从浏览器、聊天软件、截图软件或文件管理器复制 PNG/JPEG 图片，再点击左侧“粘贴图片”。应用兼容常见的 PNG 数据流、WPF/WinForms 位图、图片文件和 HTML data:image 剪贴板格式。
• 也可以把 PNG/JPEG 文件直接拖到主窗口。
• 图片只在内存中处理，不会由怪兽密码助手另存到磁盘。识别和确认步骤与截图识别相同。
• 只有图片成功读取且剪贴板未被其他内容替换时，应用才会清除原图。

#从浏览器导入

1. 在 Chrome、Edge 或 Firefox 的密码管理器中使用“导出密码”，得到 CSV 文件。浏览器通常会要求先进行 Windows 身份验证。
2. 回到怪兽密码助手，点击左侧“浏览器导入”，选择导出的 .csv 文件。
3. 在预览窗口中取消不需要的项目；“显示密码”仅用于导入前核对。
4. 选择重复项的处理方式。默认按规范化网址和账号匹配并更新已有记录；取消勾选后，重复项会另存为新记录。
5. 点击“开始导入”，完成后检查新增和更新数量。

浏览器导出的 CSV 含有明文密码。怪兽密码助手只读取你选择的文件，不会替你删除它；导入并核对成功后，请从下载目录和回收站中删除该 CSV。CSV 解析兼容带引号、逗号、分号或制表符分隔的 Chrome、Edge 和 Firefox 常见格式。

#查找与查看

• 顶部可切换“网站 / 应用 / 其他”三类视图，分类之间不会混排；搜索只在当前分类中匹配名称、网址、应用、账号或标签。清空搜索框时显示该分类最近使用的凭据。
• 每页显示 5 条，使用右下角左右箭头翻页；切换分类或修改搜索条件会回到第一页。
• 网站凭据会在内存中尝试读取该网站自身的 /favicon.ico 并显示为图标。请求失败、图标无效或网址不合法时，会使用内置网站图标，不会调用第三方图标服务。
• 网站行中的网址可点击，会在默认浏览器中打开。没有协议的网址会按 https:// 处理；应用和其他类型保持普通文本。
• 每条凭据右侧依次提供：显示或隐藏密码、复制账号、复制密码、编辑和删除。
• 复制账号或密码后，应用会在 30 秒后尝试清除剪贴板。只有剪贴板仍是本应用复制的内容时才会清除，不会覆盖你后来复制的新内容。
• 默认按 Ctrl+Alt+P 显示主窗口并聚焦搜索框。

#应用设置

在“AI 与应用设置”中还可以调整：

• 快速搜索快捷键和截图识别快捷键，格式例如 Ctrl+Alt+P。两个快捷键不能相同。
• 自动锁定时间，范围为 0 到 120 分钟；0 表示关闭应用内无操作自动锁定。
• 主密码，需要依次输入当前主密码、新主密码和确认密码。“显示主密码”可以同时切换三项输入的显示状态。
• Windows Hello / PIN 解锁：输入当前主密码并点击“启用 PIN 解锁”，再完成 Windows 弹出的系统验证。之后锁定页会显示便捷解锁按钮。应用不会读取或保存 PIN；修改主密码或恢复备份后需要重新启用。

即使关闭了无操作自动锁定，Windows 锁屏、休眠、用户切换或应用退出时仍会锁定保险库。

#备份与恢复

#导出备份

1. 点击左侧“导出备份”。
2. 选择 .pavault 文件的保存位置。
3. 备份本身保持加密，使用导出时的主密码解锁，不会生成明文中间文件。

#恢复备份

1. 点击“恢复备份”；在保险库锁定界面也可以选择“从备份恢复”。
2. 选择 .pavault 文件并输入该备份导出时使用的主密码。
3. 应用会先验证格式、密码和密文完整性，成功后才替换当前保险库。

更改主密码不会修改以前导出的备份。旧备份仍需使用导出时的旧主密码。

#托盘与退出

• 关闭主窗口只会将应用隐藏到系统托盘，不会彻底退出。
• 双击托盘图标或使用托盘菜单可以重新打开主窗口。
• 需要彻底退出时，右键托盘图标并选择“退出”。
• 应用采用单实例模式；重复启动只会唤醒已经运行的实例。

#数据位置

默认数据目录为 %LOCALAPPDATA%\PasswordAssistant，主要文件包括：

• vault.db：加密保险库、加密 AI 设置和记录数据。
• app-settings.json：快捷键、自动锁定时间等非秘密应用设置。
• windows-hello.dat：仅在启用 Windows Hello / PIN 解锁后存在，由 Windows 当前用户的 DPAPI 保护；不能复制到其他电脑或 Windows 账户使用。

不要在应用运行时手动编辑这些文件。迁移或重装前建议优先使用应用内的“导出备份”。

#常见问题

• 启动后没有看到窗口：检查任务栏右下角的系统托盘，应用可能已经在后台运行。
• 快捷键没有反应：快捷键可能被其他程序占用，请到“AI 与应用设置”中更换组合键并保存。
• AI 返回无效 JSON：确认模型支持图片输入和 JSON 模式，并检查接口地址是否是完整的 /v1/chat/completions 地址。
• 部分字段没有识别出来：这是允许的，缺失字段会留空，可在确认页手动补充。
• 主模型识别失败：配置完整的备用模型后会自动尝试一次，结果页会提示已切换；两者都失败时不会保存任何记录。
• 浏览器 CSV 无法读取：请直接使用 Chrome、Edge 或 Firefox 密码管理器的导出功能，不要用表格软件另存；另存可能改写表头、编码或分隔符。
• 没有 PIN 解锁按钮：先在 Windows 登录选项中配置 PIN/Windows Hello，再到应用设置中启用。修改主密码或恢复保险库后，旧绑定会自动关闭。
• 遮挡密码没有识别出来：这是预期行为。需要先在原网站或应用中显示明文密码，再重新截图，或在确认页手动输入。
• 剪贴板没有被清空：如果 30 秒内复制了其他内容，应用会保留新内容，不再清除剪贴板。

#隐私边界

• 保险库记录、备注和 API Key 使用 XChaCha20-Poly1305 加密；主密码通过 Argon2id 派生封装密钥。
• 截图在内存中捕获、裁剪和编码，不调用系统截图工具，也不保存到磁盘。
• 选择截图识别后，原始裁剪图片会发送给用户配置的 AI 服务。应用无法控制服务商的日志、留存和合规政策。
• 圆点、星号、模糊等遮挡密码不会被恢复或猜测。
• 应用没有遥测、云同步、密码找回、浏览器扩展或自动填充。
• Windows Hello / PIN 由 Windows 验证。应用在验证成功后读取由当前 Windows 用户 DPAPI 保护的主密码，因此它是个人设备上的便利功能，不是第二重加密或密码找回机制。

更多边界见 安全设计。

#开发

要求 Windows 11 x64 和 .NET 10 SDK：

dotnet restore PasswordAssistant.slnx
dotnet test PasswordAssistant.slnx
dotnet run --project src/PasswordAssistant.App

测试或调试时可通过 PASSWORD_ASSISTANT_DATA_DIR 指向独立数据目录，避免使用正式保险库。

#发布

生成自包含目录：

.\scripts\build-release.ps1 -SkipInstaller

安装 Inno Setup 6 后生成安装程序：

.\scripts\build-release.ps1

发布文件位于 artifacts/publish，安装器位于 artifacts/installer。

当前个人版安装器未做商业代码签名，Windows SmartScreen 可能在首次运行时显示提示。