目标：从 股票代码 或 “原始披露材料（EDGAR filings / PDF 财报）”加工成一份可追溯的公司全貌梳理 Markdown，并最终一键导出成 HTML / PDF / Word。

两套写作工具：

1. 网页版（GUIDE 手写）：按 GUIDE.md 逐章写作 → 用 render 导出 HTML/PDF/Word。
2. Codex CLI 自动写作：准备 filings 或 PDF（可选用 Marker/MinerU 处理成 LLM ready）→ 自动写作 → 用 render 导出 HTML/PDF/Word。

Markdown（.md文件）可以用Chrome（需安装Markdown Viewer扩展程序）打开查看，然后用打印成PDF，render脚本可不用。

也可不用准备材料，给TICKER就能写作。

• 获取材料（可选）（任选其一）

  • 美股/SEC：下载 filings

  python utils/fetch_sec_edgar.py --ticker AAPL --form 10-K 10-Q --start 2015 --end 2025

  • PDF（财报、公告、电话会议）
    可自己从公司IR网站下载PDF。

• 按 GUIDE.md 逐章写作

• 用 render 导出 HTML/PDF/Word

python utils/render.py Reports/<TICKER>/<公司名>全貌梳理.md

也可不下载任何资料直接用TICKER开始写作，但是速度理论上比下载好材料写作慢

• 美股/SEC：下载 filings

python utils/fetch_sec_edgar.py --ticker AAPL --form 10-K 10-Q --start 2015 --end 2025

• PDF：可直接用原 PDF，也可用 Marker/MinerU 处理成 LLM ready，建议处理。

从GUIDE.md 生成prompts：

python utils/sync_codex_from_guide.py

用TICKER自动写作：

python utils/run_qual_report_codex.py --ticker <TICKER>

用本机材料自动写作：

python utils/run_qual_report_codex.py --base filings/<TICKER>

python utils/render.py Reports/<TICKER>/<公司名>全貌梳理.md

• filings/：SEC EDGAR 下载的原始 filing（iXBRL HTML + XBRL 实例与 taxonomy）。
• output/：各类脚本的输出目录（渲染后的 HTML/PDF/Word、marker 输出、媒体资源等）。
• render/：Pandoc 渲染模板资源（CSS、before/after 片段、Lua filter）。
• Reports/：你写作/自动化生成的最终产物（建议用股票代码做目录名：Reports/<TICKER>/...）。

可选两类材料来源：

• 美股/SEC：下载 filings（见【脚本参数说明】fetch_sec_edgar）
• PDF：可直接用原 PDF 作为材料

写作流程与“对话协议”在 GUIDE.md。推荐顺序：

1. 新对话中粘贴 GUIDE.md 的“开场必发：协议注入 + 全局硬约束”。
2. 上传《定性分析模板.md》与材料。
3. 用 #WRITE 从“公司介绍与沿革”开始线性推进；跳章用 #JUMP。
4. 中间章节写完后再 #FIX；最后 #FILL 回填“投资要点概览”和“来源清单”。
5. 用 #CHECK 做一致性检查。

Markdown（.md文件）可以用Chrome（需安装Markdown Viewer扩展程序）打开查看，然后用打印成PDF，render脚本可不用。

python utils/render.py Reports/<TICKER>/<公司名>全貌梳理.md

python utils/run_qual_report_codex.py --ticker <TICKER>

也可获取材料到本机后用材料写作，理论上速度会更快。

可选两类材料来源：

• 美股/SEC：下载 filings（见【脚本参数说明】 fetch_sec_edgar）
• PDF：可直接用原 PDF，或先处理成 LLM ready，建议处理。

适合：PDF 规模大、结构复杂、需要更稳定的章节检索与引用。

输入：PDF
输出：LLM ready的材料库
示例（MinerU）：

python utils/mineru_extract.py --base /path/to/pdfs --output output/<base目录名>

当材料库规模很大（例如上千文件）时，建议构建索引并按章拼包。 输入：LLM ready的材料库
输出：材料库 索引
示例（MinerU）：

python utils/build_mineru_manifest.py --base output/<base目录名>

从GUIDE.md 生成prompts：

python utils/sync_codex_from_guide.py

直接从filings或PDF开始写作：

python utils/run_qual_report_codex.py --base filings/<TICKER> --ticker <TICKER>

从材料库开始写作：

如果未显式传 --materials-index，脚本会自动检查 --base/index 是否存在索引并使用它。

python utils/run_qual_report_codex.py --base output/<base目录名>

从材料库 + 索引开始写作：

python utils/run_qual_report_codex.py --base output/<base目录名> --materials-index output/<base目录名>/index

当章节审计失败触发重试时，脚本会自动扩大该章材料包（提高 top_k 与 max_total_chars）并重写。

产物与日志：

• 报告：Reports/<TICKER>/<公司名>全貌梳理.md
• 章节：Reports/<TICKER>/chapters/
• 日志：Reports/<TICKER>/_codex_logs/

python utils/render.py Reports/<TICKER>/<公司名>全貌梳理.md

脚本：utils/fetch_sec_edgar.py

常用参数：

• --ticker：股票代码（与 --cik 互斥，二选一）
• --cik：CIK 数字（与 --ticker 互斥，二选一）
• --form：表单类型（必填，可多填，如 10-K 10-Q）
• --start：起始日期（必填；支持 YYYY / YYYY-MM / YYYY-MM-DD）
• --end：结束日期（可选；支持 YYYY / YYYY-MM / YYYY-MM-DD；默认今天）
• --output：输出目录（可选，默认 ./filings）
• --user-agent：覆盖 SEC User-Agent（优先级高于 SEC_USER_AGENT 环境变量）
• --sleep：请求间隔秒数（默认 0.2）
• --overwrite：强制覆盖已有文件（默认关闭）
• --no-xbrl：不探测/下载 XBRL 实例与 taxonomy（仅保留主 HTML）

重要说明：

• SEC 要求 User-Agent 标识身份，请在环境变量中设置：

   export SEC_USER_AGENT="Your Name [email protected]"

• 输出目录结构形如：filings/<TICKER>/<FORM>_<DATE>_report_<REPORT_DATE>_<ACCESSION>/。

脚本：utils/mineru_extract.py

参数：

• --filing：单个 PDF 文件路径（与 --base 互斥）
• --base：PDF 目录（递归扫描 .pdf，与 --filing 互斥）
• --output：输出目录（默认 ./output）
• --ocr：启用 OCR（默认关闭）
• --html：导出 HTML（extra_formats=["html"]）
• --sleep：轮询间隔秒数（默认 30）
• --timeout：轮询超时秒数（默认 1200；实际总超时 = timeout * 文件数）

重要说明：

• MinerU 要求申请API Key，请在环境变量中设置：

   export MINERU_TOKEN="xxxxxxxxxxxx"

脚本：utils/marker_extract.py

参数：

• --filing：单个 PDF 文件路径（与 --base 互斥）
• --base：PDF 目录（仅当前目录下 .pdf）
• --output：输出目录（默认 ./output）
• --ollama：启用本地 Ollama
• --model：Ollama 模型名（默认 deepseek-r1:8b）

脚本：utils/build_mineru_manifest.py

用途：把 MinerU 输出目录（大量文件）构建成可检索的 manifest.jsonl/manifest.tsv，供后续按章节选 Top-K chunks。

参数：

• --base：MinerU 输出根目录（例如 output/0883）
• --output：索引输出目录（可选；默认 <base>/index）

• --chunk-chars：chunk 大小（字符数；默认取环境变量 MINERU_CHUNK_CHARS，否则 1800）
• --include-doc-records：在 manifest.jsonl 中额外写入 doc 级记录（可选）
• --max-docs：仅处理前 N 份文档（调试用；0 表示不限制）
• --write-toc：生成一个 toc.md 骨架（默认开启；仅当 toc.md 不存在时写入）
• --no-write-toc：关闭 toc.md 生成

脚本：utils/build_marker_manifest.py

用途：把 Marker 输出目录（大量 JSON）构建成可检索的 manifest.jsonl/manifest.tsv，供后续按章节选 Top-K chunks。

参数：

• --base：Marker 输出根目录（例如 output/0300）
• --output：索引输出目录（可选；默认 <base>/index）

• --chunk-chars：chunk 大小（字符数；默认取环境变量 MARKER_CHUNK_CHARS，否则 2200）
• --include-doc-records：在 manifest.jsonl 中额外写入 doc 级记录（可选）
• --max-docs：仅处理前 N 份文档（调试用；0 表示不限制）
• --write-toc：生成一个 toc.md 骨架（默认开启；仅当 toc.md 不存在时写入）
• --no-write-toc：关闭 toc.md 生成

脚本：utils/run_qual_report_codex.py

参数：

• --base：材料目录（单一公司；可选，不提供则表示不使用本地材料）
• --ticker：股票代码（可选但推荐；用于默认 base 与校验）
• --company：公司名（可选，覆盖自动识别）
• --materials-index：材料索引目录（包含 manifest.jsonl + toc.md，可选，默认检索<base>/index目录）
• --manifest-max-items：材料清单最多列出多少项（默认 6）
• --profile：执行档位（fast/balanced/high/deep，默认balanced）
• --max-attempts：每章最大尝试次数（默认 2，1即关闭稿件审计）
• --only-chapters：只写指定章节（可重复或逗号分隔）
• --protocol-restate-after：累计审计失败 N 次后重申硬约束（默认 10）
• --write-blocked-max：#WRITE写作失败（非审计失败）的最大次数（默认 10），超出即中断写作
• --check/--no-check：是否执行最终一致性检查（默认开启）

• --verbose：打印 Codex 最终输出
• --dry-run：只打印计划不执行
• --dump-prompts：仅生成 prompts（不调用 Codex）
• --dump-prompts-dir：--dump-prompts 输出目录

• --pack-top-k：覆盖 toc 中 top_k（0=按 toc）
• --pack-neighbor-window：覆盖 toc 中 neighbor_window（-1=按 toc）
• --pack-max-total-chars：构建材料包时的最大字符数（默认 220000）
• --identity-index-top-n：身份推断时使用的清单/索引条数（默认 12）

脚本：utils/render.py

参数：

• <input_markdown>：输入 Markdown（必填）
• [output_path]：输出路径（可选；扩展名决定格式：html/pdf/docx）

运行时依赖：

• pandoc（带 Lua filter 支持）
• python3（用于 HTML 后处理：CSS 内联、图片宽度限制）
• Google Chrome（PDF 导出时 headless 打印）

macOS 通常需要配置：

export PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"