维护台湾上市公司股票研究数据库、供应链映射与主题选股时，用…

适用于需要批量管理台湾 TWSE/OTC 股票研究报告、按主题发现供应链公司并生成投资筛选/网络图的场景。

适用场景

解决思路

1. 安装：执行 git clone https://github.com/Timeverse/My-TW-Coverage，然后 cd My-TW-Coverage，再执行 pip install yfinance pandas tabulate。
2. 按目录组织数据：Pilot_Reports/ 放置按 99 个行业文件夹分类的 1,735 个 ticker 报告；scripts/ 放置工具脚本；WIKILINKS.md 为自动生成可浏览索引；network/index.html 为 D3.js 网络图；themes/ 为主题投资筛选页；task.md 为批次定义和进度跟踪。
3. 按路径格式创建报告：Pilot_Reports/<Sector>/<TICKER>_<Name>.md。
4. 按报告模板维护内容：包含 業務簡介、板塊、產業、市值、企業價值、供應鏈位置（上游/中游/下游）、主要客戶及供應商、財務概況（估值指标表、年度 3 年财务表、季度 4 季度财务表），实体使用 [[wikilink]]。
5. 添加新 ticker：python scripts/add_ticker.py 2330 台積電；指定行业时用 python scripts/add_ticker.py 2330 台積電 --sector Semiconductors。
6. 更新单个/多个财务数据：python scripts/update_financials.py 2330；python scripts/update_financials.py 2330 2454 3034。
7. 按批次、行业或全部更新财务数据：python scripts/update_financials.py --batch 101；python scripts/update_financials.py --sector Semiconductors；python scripts/update_financials.py。
8. 仅更新估值：python scripts/update_valuation.py 2330；python scripts/update_valuation.py --batch 101；python scripts/update_valuation.py --sector Semiconductors；python scripts/update_valuation.py。只刷新 P/E、Forward P/E、P/S、P/B、EV/EBITDA 和股价，跳过完整财报重取，约快 3 倍。
9. 按关键词发现相关公司：python scripts/discover.py "液冷散熱"；用 --smart 自动检测相关行业并跳过银行/保险/房地产；用 --apply 给匹配报告加 [[wikilinks]]；用 --apply --rebuild 同时重建 themes 和网络图；用 --sector Semiconductors 限定行业。
10. 使用常见关键词示例："CoWoS"、"HBM"、"電動車"、"AI 伺服器"（148 家公司）、"光阻液"、"碳化矽"。
11. 批量更新 enrichment：准备 JSON 后执行 python scripts/update_enrichment.py --data enrichment.json 2330；python scripts/update_enrichment.py --data enrichment.json --batch 101；python scripts/update_enrichment.py --data enrichment.json --sector Semiconductors。
12. 编写 enrichment JSON：顶层 key 为 ticker 字符串；每个条目包含 desc、supply_chain、cust；实体使用 [[wikilink]]；内容用 Traditional Chinese，专有名词可英文；保存为 UTF-8 且 ensure_ascii=False。
13. 审计报告质量：python scripts/audit_batch.py 101 -v；python scripts/audit_batch.py --all -v。
14. 审计时检查：每份报告至少 8 个 wikilinks；括号中无通用词如 [[公司]]、[[產品]]；无占位文本；中文段无英文；元数据完整（板塊、產業、市值、企業價值）；章节完整（業務簡介、供應鏈位置、主要客戶及供應商、財務概況）。
15. 重建 wikilink 索引：python scripts/build_wikilink_index.py，重新生成 WIKILINKS.md，将 4,900+ wikilinks 分类为 Technologies、Materials、Applications、Companies。
16. 生成主题投资筛选：python scripts/build_themes.py 生成全部 20 个主题；python scripts/build_themes.py "CoWoS" 生成单个主题；python scripts/build_themes.py --list 列出可用主题；输出到 themes/，每页按上游/中游/下游分组公司。
17. 生成交互式网络图：python scripts/build_network.py 默认最少 5 次共现；python scripts/build_network.py --min-weight 10 减少边；python scripts/build_network.py --top 200 只显示前 200 节点；用浏览器打开 network/index.html。节点颜色：红色=台湾公司，蓝色=国际公司，绿色=技术，橙色=材料，紫色=应用。
18. 用 wikilink 图搜索实体：每个 [[entity]] 产生知识图谱边；搜索 [[Apple]] 得 207 家公司，[[NVIDIA]] 得 277 家，[[台積電]] 得 469 家，[[CoWoS]] 得 39 家，[[AI 伺服器]] 得 148 家，[[PCB]] 得 263 家，[[電動車]] 得 223 家；浏览 WIKILINKS.md 查看完整分类索引。
19. 读取并解析报告：用 Path.rglob 在 Pilot_Reports 下查找 <ticker>_*.md；读取 UTF-8 内容；用正则提取 [[...]] wikilinks；用 re.search 提取 產業 和 板塊；返回 ticker、file、sector、board、wikilinks、wikilink_count、content。
20. 构建自定义 wikilink 索引：遍历 Pilot_Reports 下所有 .md；从文件 stem 的 split("_")[0] 取 ticker；提取每份报告的 wikilinks；用 defaultdict(list) 建立 entity 到 ticker 列表的索引；按提及公司数量降序排序。
21. 查找两个实体的供应链重叠：构建 wikilink 索引；取 set(index.get(entity_a, [])) 与 set(index.get(entity_b, [])) 的交集；例如 supply_chain_overlap("NVIDIA", "Apple")、supply_chain_overlap("AI 伺服器", "電動車")。
22. 按行业批量更新并处理错误：根据 valuation_only 选择 update_valuation.py 或 update_financials.py；用 subprocess.run([sys.executable, f"scripts/{script}", "--sector", sector], capture_output=True, text=True) 调用；检查 returncode，打印 stderr 或 stdout。
23. 准备 enrichment JSON 条目：定义 build_enrichment_entry；把 upstream、downstream、customers、suppliers 列表包装为 - [[item]]；生成含 **上游:**、**中游:**、**下游:** 的 supply_chain 字符串；生成含 ### 主要客戶、### 主要供應商 的 cust 字符串；用 json.dump(..., ensure_ascii=False, indent=2) 保存。
24. 程序化审计批次：运行 python scripts/audit_batch.py <batch_id> -v；用 subprocess.run capture_output；统计输出中 ✓ 和 ✗ 数量；计算 pass_rate。
25. 工作流 1 研究新投资主题：python scripts/discover.py "液冷散熱" --smart；python scripts/discover.py "液冷散熱" --apply；python scripts/build_themes.py "液冷散熱"；python scripts/build_wikilink_index.py；python scripts/build_network.py；打开 themes/液冷散熱.md 和 network/index.html。
26. 工作流 2 上线新 ticker：python scripts/add_ticker.py 6669 緯穎 --sector Computer Hardware；python scripts/update_financials.py 6669；准备 enrichment.json；python scripts/update_enrichment.py --data enrichment.json 6669；python scripts/audit_batch.py --all -v；python scripts/build_wikilink_index.py。
27. 工作流 3 财报季刷新估值：python scripts/update_valuation.py --sector Semiconductors；python scripts/update_valuation.py --sector Electronic Components；python scripts/update_valuation.py --sector Computer Hardware；或 python scripts/update_valuation.py 全量刷新（慢，过夜）。
28. 工作流 4 映射供应链：遍历 Pilot_Reports 下 .md；若内容含 [[technology]] 则继续；按 **上游:**、**中游:**、**下游:** 分段判断公司位置；输出 upstream、midstream、downstream 列表。
29. 按 Token 成本选择操作：Update financials、Update valuation、Discover（有结果）、Audit、Build themes/network/index 均为 Free（yfinance）；/add-ticker 为 Medium；/update-enrichment 为 Medium，每 ticker 做 3–5 次 web searches；/discover（无结果）为 Low–High，AI 在线研究。
30. 遵循成本规则：批量数据操作用 Python scripts；只有需要 AI 研究特定 ticker 时才用 Claude Code slash commands。
31. 故障排除 yfinance 无数据：台湾 ticker 需要 .TW 后缀（TWSE）或 .TWO（OTC）；例如 yf.Ticker("2330.TW").info.get("marketCap")。
32. 故障排除报告找不到：文件名必须匹配 {TICKER}_{CompanyName}.md；必须位于 Pilot_Reports/ 的子文件夹；用 python scripts/utils.py 测试文件发现。
33. 故障排除审计失败 too few wikilinks：每份报告至少需要 8 个唯一 [[wikilinks]]；用 update_enrichment.py 添加更丰富内容；运行 discover.py --apply 自动打相关 wikilinks。
34. 故障排除 build_network.py 空图：先运行 python scripts/build_wikilink_index.py，确认 WIKILINKS.md 有条目；再运行 python scripts/build_network.py --min-weight 2 降低阈值。
35. 故障排除 enrichment JSON 被拒：确保文件为 UTF-8 且 ensure_ascii=False；key 必须是 ticker 字符串如 "2330"，不是数字 2330；每个条目必须包含 desc、supply_chain、cust；内容必须为 Traditional Chinese，英文只用于专有名词。
36. 查找批次号：查看 task.md 获取批次定义以及每个批次包含哪些 tickers；批次用于增量处理 1,735 个 tickers。

适用边界 · 注意事项

• 不适用于非台湾上市股票、全球市场覆盖或需要实时交易信号/高频数据的场景；该库只覆盖 TWSE + OTC 的 1,735 家台湾公司。
• 没有 My-TW-Coverage 仓库、其 scripts/ 脚本、yfinance 或相应 Python 环境时不能直接套用。
• 批量全量更新财务/估值很慢，且 yfinance 数据可能有延迟；不适合对时点准确性要求极高的生产交易系统。