[xiaoland]

目的与范围

交付完整的原生 Mac Peer：用户可以采集选区、粘贴材料、框选截图与想法，将本地目录持续收入 info-base，并保存和切换多个连接。Mac 通过 PostgresNIO 直接使用 PostgreSQL；应用 Host、通用 PeerCore、Capture 与本地文件 first-party 扩展各自负责自己的生命周期和业务。

本 PR 整体承接并取代已关闭的 #1，直接以 main 为基底；包含原生采集实现及后续本地文件、多连接和 Logo 接入。

• 以普通主窗口、原生设置、全局快捷键和辅助面板承载采集；SwiftUI／AppKit 共用一份草稿，图片支持 Quick Look，截图仅收入明确确认的区域。

• Capture 使用 SQLite 保存草稿与冻结待办，凭据保存在 Keychain。图、原图与共享摘要回执在一个数据库事务内保存；恢复复用原 UUID、材料和目标，核对回执后才清理本机材料。

• inkcre/local-files 经原生 PostgreSQL 保存正文和位置引用，不需要 Python Peer 执行写入。

• 支持 PDF 文字层、DOCX 主文档、Markdown、Org、HTML 和纯文本；FSEvents 变化、重启核对及手动 Source Job 共用对账流程。

• 文件修改更新原资料；可证明的重命名保持 ID；删除原件保留正文；提取失败和目录不可访问不会清空旧内容。

• 原件留在磁盘，以 inkcre-peer-file://<peer-id>/<机器绝对路径> 引用。目录绑定原信息库，切换连接不改投。

• Host 拥有主窗口、导航和连接管理；Capture 与本地文件独立启停。删除 Capture 旧连接页及重复轮询，实际提交时办理首次准入。

• 列表与扫描只读取元数据，选中文件才读取正文；未变化文件跳过写事务；Capture 减少全量读取和无变化刷新。

• 本机先停用再尝试同步共享意图；后台 Keychain 读取静默失败，避免反复系统授权提示。

• 本机保存命名连接列表与当前选择，重新打开恢复上次选择；旧单连接保留身份与 Keychain 引用。设置和 Peer 页可添加、编辑并切换连接。

• 切换立即清空前台目录选择，等待旧刷新收束后读取当前库。Capture 冻结待办和已有目录监视继续使用原目标，不因切换而改投。

验证

• 2026-10-26 整体承接原 feat(mac): 原生 PostgreSQL Peer 与 Capture first-party 扩展 #1 并对齐 main 后，最终 bash scripts/check.sh 通过：许可证打包回归检查 1 项通过；Swift 套件报告 61 tests / 10 suites，3 个真实数据库 opt-in 用例跳过。此前数据库验证的适用范围见下文。

• 最终签名 universal app／DMG 构建通过，包含实际 SwiftPM UI 资源 bundle、品牌来源与使用说明、第三方完整许可；codesign --verify --strict 通过。修复了新增 UI 依赖导致完整打包失败的问题，未知来源或缺失品牌来源文件仍使检查失败。

• swift test：58 项、9 个 suite 通过，同时启用一次性 PostgreSQL 的 Capture 与本地文件检查。

• 数据库主流程涵盖首次准入、重复提交／重启回执恢复、六格式收入、修改与重命名、失败／删除保留及来源移除。

• 隐藏 AppKit 窗口跑通选择正文、快速切换、暂停／恢复与重启，实际查看正文、失败保留、空状态和 Host 页面渲染图。仅图片尺寸断言归为渲染冒烟检查。

• 此前用合成内容完成系统目录选择、打开原件、移除取消／确认的前台验证；精简后没有重新操作前台或重验屏幕录制权限。

• bash scripts/build-app.sh：授权 Apple Development 身份签署的 universal 0.1.0（build 17） app/dmg 构建和签名验证通过；本次多连接包未替换已安装应用。

• 多连接增量：Swift 完整套件报告 61 tests（3 个数据库 opt-in 用例跳过）；2026-10-25 重跑连接持久化与 Host 界面定向 5 项通过。包含 A/B/A、重载恢复、名称编辑、旧单连接保留及无效选择不覆盖。

• 已查看多连接设置的隐藏窗口渲染。隔离调度探针确认任务内清理修复了连接切换漏刷新竞态；未将其作为真实多库数据库证据。

• 本次没有重跑真实多信息库端到端与前台原生鼠标交互；上述原本地文件数据库证据仅适用于未改动部分。

风险与回退

正文不包含 OCR、DOCX 脚注／批注；应用离线期间出现又消失且从未收入的文件无法恢复。原件没有备份或跨 Peer 传输。回退开发应用包会停止本地文件执行能力，已收入图及现有应用数据保留；不执行数据清理。多连接保存后，旧版应用不能直接读取新的连接列表格式；若需回退，应先备份本机 connection.json，再恢复旧格式的活动连接，Keychain 和本机材料不清理。

交付影响

本仓库合并不执行数据库迁移、软件包发布、公证或应用安装。Mac 运行依赖 impl-py#151 的原生参与与 Capture 回执 schema；当前正式数据库尚不能据此合并推断为兼容。本轮不连带合并或部署该数据库候选。

第三方依赖固定版本；Cida、BetterShot、PostgresNIO、SwiftSoup 的完整许可与署名随应用交付。版本仍为 0.1.0，17 仅为构建号。

依赖关系

• 父 PR：无；本 PR 直接以 main 为基底。原 feat(mac): 原生 PostgreSQL Peer 与 Capture first-party 扩展 #1 已由本 PR 整体承接后关闭。
• 后续子 PR：无。

跨仓配套

• 多连接用户手册与产品约定 docs#43：补齐 Mac 与其他入口的操作，明确多连接通常推荐给直接与用户交互的 Peer；固定服务一个信息库的 impl-py 服务器可继续使用单一部署配置。切换不改投已绑定的 Capture 待办和目录监视。该文档 PR 已合并并完成生产部署。

• Web／浏览器扩展多连接：独立实现，无合并顺序依赖。

• 共享合同

• Python 读取分发

• Web 读取分发

Logo 资产 SwiftPM 接入

采集面板与菜单栏标识通过 InKCreLogoAssets product 消费已发布的 InKCre UI 2.6.0，SwiftPM 使用 exact 2.6.0 约束。应用的 Package.resolved 锁定发行提交 e5858e1092617eb5acf6588460e597fbc43c662a。

移除三张本地 PNG 副本，沿用浅色／深色 24pt @2x 与菜单 20pt @2x 的原资源、逻辑尺寸和 template 设置。自组装 .app 显式嵌入 InKCreUI_InKCreLogoAssets.bundle，运行时只从 Contents/Resources 定位；缺少资源直接报错。AppIcon SVG、iconset、生成流程和 ICNS 绑定保持原样，由原生消费者维护。

• swift package -j 2 resolve 与 swift build -j 2 --target CaptureMac --disable-automatic-resolution 通过；锁文件将 UI pin 更新为正式 2.6.0 和上述发行提交，其他依赖 pin 未变。
• swift test -j 2 --disable-automatic-resolution --filter 'captureSurfacesRenderOffscreen|iconsetHasTransparentMacMarginsAtEveryScale'：两项相关测试通过。
• 无窗口的最小 .app 探针直接编译当前 BrandAssets.swift，链接正式版本的资源模块；将应用放在构建目录之外，并临时移走整个 .build 后执行。实际从 .app/Contents/Resources 解码了三张 PNG，明暗标识为 24pt／48px，菜单为 20pt／40px 且 template 开启，字节与此前视觉验证一致；随后恢复 .build。
• 保留远端的品牌来源打包修复；许可收集单测和实际 notices 生成通过，包含锁定 UI 2.6.0 的资源说明、原始来源与使用边界。
• 正式版本升级复用原 PNG 的前台显示证据；最终提交 e13a177 的 CI 通过，并重新构建签名 universal app／DMG，codesign --verify --strict 与 DMG 校验通过。没有启动 GUI、公证或安装日常应用。