AutoEquityPenetrator

精简重写版 macOS 天眼查辅助采集与股权穿透工具。

目标

• 面向非专业用户，保留必要能力，减少配置绕路和 UI 噪音。
• 只保留 Chrome + Playwright 浏览器自动化采集路径，不再保留 MCP 采集。
• 股权穿透只保留 crawl 与 build 两段式工作流。
• XLSX 输出必须兼容旧版格式；旧版写入器会作为格式基线迁移并加回归验证。

当前状态

仓库已建立新的 Swift Package 骨架：

• AutoEquityCore：核心模型、命名规则、终止规则、穿透图算法。
• AutoEquityApp：SwiftUI macOS 应用入口和精简导航雏形。
• AutoEquityCoreTests：核心规则与穿透算法的第一组回归测试。
• AutoEquityImportTool：临时工程闭环工具，可用于内部验证导入旧 SQLite、从新 SQLite build XLSX、导出 HTML 穿透报告；最终 App 不暴露旧库迁移入口。
• “数据资产”页已接入本地 SQLite 列表、状态/质量/规则标记筛选；最终 App 专注新版数据库的查看与维护。
• “条目详情”页已接入本地条目加载、基本信息/股东预览，并提供 HTML 与 XLSX 穿透 build 导出；可配置最大层级、终止条件和实际持股阈值。
• “输出”页已接入 Reports 目录索引，可快速定位最近生成的 HTML、XLSX 与审计 JSON。
• “工作台”页已接入 Chrome + Playwright 采集环境预检；核心层已建立浏览器采集运行器边界和打包脚本资源。
• “设置”页已分成默认说明和高级配置：普通用户无需改动，高级用户可自定义 SQLite、输出目录、运行目录、Chrome Profile、Chrome 可执行文件、截图和精确匹配。
• “设置”页还提供数据库同步包导入/导出，用于和其他用户交换本地 SQLite 数据。
• crawl 调度已进入核心层：从目标公司开始采集，反复计算缺口企业 frontier，并按批次调用 Chrome + Playwright 写入 SQLite。
• 批量基本信息工作流已进入核心层、CLI 和工作台：优先复用本地缓存，自动补采缺失或不完整条目，并按输入顺序导出 Markdown。

后续会继续扩展真实天眼查页面验证、XLSX 金样本覆盖和干净 Mac 验收。

当前工程命令

swift test
npm run test:crawler
swift run AutoEquityImportTool build-xlsx <autoequity.sqlite> <company-name> <output.xlsx> [max-depth] [minimum-actual-holding-percent] [sorted-sheet-minimum-actual-holding-percent]
swift run AutoEquityImportTool compare-xlsx <legacy.xlsx> <candidate.xlsx>
swift run AutoEquityImportTool build-html <autoequity.sqlite> <company-name> <output.html> [sorted-sheet-minimum-actual-holding-percent]
swift run AutoEquityImportTool preflight-browser
swift run AutoEquityImportTool crawl <autoequity.sqlite> <run-directory> <company-name>
swift run AutoEquityImportTool crawl-batch <autoequity.sqlite> <run-directory> <company-name> [company-name...]
swift run AutoEquityImportTool basic-info <autoequity.sqlite> <run-directory> <output.md> <company-name> [company-name...]
swift run AutoEquityImportTool basic-info-file <autoequity.sqlite> <run-directory> <output.md> <input.txt>
swift run AutoEquityImportTool export-basic-info-md <autoequity.sqlite> <output.md> <company-name> [company-name...]

开发环境运行 preflight-browser 需要仓库根目录存在 node_modules/playwright-core；打包后的 App 会使用 Contents/Resources/runtime 中随包携带的 Node 与 playwright-core，目标机器只需要安装 Google Chrome。

打包

构建机需要能安装一次 playwright-core 并安装 Google Chrome，以便打包时做真实 Chrome 启动验收；目标 Mac 不需要安装 Node、npm、Python、Playwright 或 Homebrew，只需要安装 Google Chrome。

npm install --omit=dev
Scripts/build_app.sh

build_app.sh 会自动做两件事：

• 裁剪 bundled playwright-core 的非运行时文件，并对 app 主二进制做 strip，尽量减小分发体积；Node 保留官方可再发行二进制以避免破坏运行时。
• 运行 packaged preflight，确认 .app 使用 bundled Node、bundled playwright-core、打包内 tyc_batch.js，并能用临时 Chrome Profile 启动目标 Chrome。
• 运行空 frontier 的 crawler smoke，确认随包 Node 可以执行天眼查采集脚本并写出 tyc/results.json。
• 生成可直接拖到干净 Mac 上使用的 .app 和 .zip，目标机只需要安装 Google Chrome。

常用变量：

• APP_VERSION 和 APP_BUILD：写入 Info.plist，用于版本号管理。
• NODE_VERSION：bundled Node runtime 版本。
• SKIP_RUNTIME_PRUNE=1：保留完整 playwright-core，仅用于排查问题，不建议正式分发使用。
• CHROME_BIN：构建验收使用的 Chrome 可执行文件路径；默认查找 /Applications/Google Chrome.app 和 ~/Applications/Google Chrome.app。
• --skip-chrome-smoke：跳过额外的 crawler smoke，仅用于没有 GUI/Chrome 的 CI；正式分发前不建议使用。
• --skip-codesign：不使用外部签名身份，但仍会做 ad-hoc bundle seal，避免 macOS 报“App 已被修改或者已损坏”。

脚本会生成：

• dist/AutoEquityPenetrator.app
• dist/AutoEquityPenetrator-macos-arm64.zip

最近一次打包验证：体积会随 Node 版本和 strip 结果略有变化；packaged preflight 会持续确认使用 bundled runtime、bundled playwright-core 和 tyc_batch.js，并真实启动 Chrome；crawler smoke 会持续确认天眼查采集脚本入口可以运行且不会依赖目标机的 Node/npm/Playwright。

面向外部分发时应使用 Developer ID 签名和公证；ad-hoc 签名只适合本机/内部验证。若用户从网络下载未公证 zip，macOS Gatekeeper 可能阻止首次打开，这不是 Node/Playwright 依赖问题。

内部验证时可用用户本机旧库生成迁移基线；这不属于最终 App 功能，只保留在 CLI 工具里：

swift run AutoEquityImportTool import-legacy "/Users/zachary/Library/Application Support/AutoEquityPenetratorNative/autoequity.sqlite" /private/tmp/autoequity-user-library-import.sqlite

开发工具

import-legacy 只用于把旧库清洗进新库，属于开发/验证工具，不会出现在最终 App 界面里。

版本 Tag

建议按 vMAJOR.MINOR.PATCH 打 tag，例如 v0.1.0。

• 代码或打包配置有变化时先更新 APP_VERSION / APP_BUILD。
• 提交前先跑 swift test、npm run test:crawler 和 Scripts/build_app.sh --skip-codesign。
• 打包验收通过后再创建 release tag，避免把未验证产物挂到版本号上。

最近一次验证结果：导入 2803 个企业页面、7090 个股东、跳过 0 条；新库汇总为 2803 个企业页面、2719 条基本信息、2605 条已匹配、248 条需关注。

XLSX 兼容性

当前已建立旧版/新版金样本对比：新华联合冶金控股集团有限公司 在同一份迁移数据下，除 docProps/core.xml 的生成时间戳外，XLSX 包内 XML 已达到字节级一致。第二张“间接持股排序表”已同步旧版新规则：输出所有实际持股比例大于等于“排序表最小实际持股”的节点路径，默认阈值 0.01%，不再仅限终止节点。compare-xlsx 命令可复用同一套包内 XML 比较逻辑，后续还需要继续扩展到更大、更深、覆盖更多终止标记的样本。

性能方向

穿透 build 和 HTML 报告现在会先把 SQLite 载入 CompanyGraphSnapshot，再进行股东树遍历，避免递归过程中反复查询 SQLite。当前权威迁移库快照规模验证为 2803 个企业页面、7090 个股东。