feat(报告): 完成 V4 可信研究链路

.env.example

@@ -0,0 +1,181 @@
+# ====================================
+# 写作 LLM 与备用端点
+# ====================================
+
+# OpenAI-compatible 写作端点；必须包含 /v1。单 key 用 LLM_API_KEY，多 key 用 LLM_API_KEYS。
+LLM_BASE_URL=https://your-primary-compatible-endpoint/v1
+LLM_API_KEY=primary_key
+# LLM_API_KEYS=primary_key_1,primary_key_2
+
+# 可选：Gemini-compatible 备用端点。主链多次失败/超时后会继续尝试 Gemini fallback 模型。
+LLM_BASE_URL_BACKUP=https://your-gemini-compatible-endpoint/v1
+LLM_API_KEY_BACKUP=gemini_backup_key
+# LLM_API_KEYS_BACKUP=gemini_backup_key_1,gemini_backup_key_2
+
+# 深度报告可能较慢，生产建议给足超时时间。
+LLM_REQUEST_TIMEOUT_MS=600000
+
+# 当前写作链示例：DeepSeek/GLM 优先；代码会自动追加 Gemini-compatible 默认链作为末级 fallback。
+LLM_MODELS_STANDARD=deepseek-v4-flash,glm-5.2
+LLM_MODELS_DEEP=deepseek-v4-flash,glm-5.2
+LLM_MODELS_EXPAND=deepseek-v4-flash,glm-5.2
+
+# ====================================
+# 搜索 LLM 与 Tavily
+# ====================================
+
+# Grok 搜索建议使用独立端点/key，避免受写作端点额度影响。
+SEARCH_LLM_BASE_URL=https://your-search-compatible-endpoint/v1
+SEARCH_LLM_API_KEY=search_key
+# SEARCH_LLM_API_KEYS=search_key_1,search_key_2
+LLM_MODELS_SEARCH=grok-4.20-multi-agent-console,grok-4.20-multi-agent-high
+
+TAVILY_API_KEY=
+TAVILY_SEARCH_ENABLED=true
+TAVILY_SEARCH_DEPTH=basic
+TAVILY_MAX_RESULTS=6
+
+# ====================================
+# 访问控制与限流
+# ====================================
+
+# 生产环境会自动启用访问控制。生产部署必须配置非空 token，否则受保护端点会 fail closed。
+APP_ACCESS_TOKEN=
+
+# 本地或预发布环境也可显式开启访问控制；只要 APP_ACCESS_TOKEN 非空也会自动开启。
+ACCESS_CONTROL_ENABLED=false
+
+# 访问令牌 cookie 有效期；可通过 Authorization: Bearer、X-App-Token、Cookie 或 access_token query 提供。
+ACCESS_COOKIE_MAX_AGE_SECONDS=86400
+
+# 受保护端点的内存限流：/api/*（除 /api/health）、/reports/*、质量看板。
+ACCESS_RATE_LIMIT_ENABLED=true
+ACCESS_RATE_LIMIT_WINDOW_MS=60000
+ACCESS_RATE_LIMIT_MAX_REQUESTS=120
+
+# 高成本写入口预算：POST /api/tasks、/api/reports、/api/channel-tasks、/api/reports/merge、/api/uploads。
+# 默认按客户端 IP 计分；deep 任务 4 分、standard/quick 任务 1 分、merge 2 分、upload 1 分。
+COST_GUARD_ENABLED=true
+COST_GUARD_WINDOW_MS=86400000
+COST_GUARD_MAX_COST_UNITS=24
+
+# 质量模块开关
+# 是否启用来源黑名单检查；启用后会识别并拦截命中黑名单的来源。
+QUALITY_BLACKLIST_ENABLED=true
+
+# 是否启用质量门禁；启用后会根据质量规则决定是否阻断或告警。
+QUALITY_GATE_ENABLED=true
+
+# 是否启用推测性内容检查；启用后会统计和标记缺少来源支撑的推测表达。
+QUALITY_SPECULATION_ENABLED=true
+
+# 是否启用完整度检查；启用后会根据报告覆盖程度计算完整度评分。
+QUALITY_COMPLETENESS_ENABLED=true
+
+# 是否启用一手来源层级检查；启用后会统计 Tier 1 来源数量和占比。
+QUALITY_TIER_ENABLED=true
+
+# 阈值配置
+# 报告完整度最低分数阈值；低于该值时触发完整度告警或门禁。
+QUALITY_COMPLETENESS_THRESHOLD=60
+
+# Tier 1 一手来源的最低数量要求；少于该数量时触发来源层级告警。
+QUALITY_TIER1_MIN_COUNT=3
+
+# Tier 1 一手来源的最低占比要求；取值范围为 0 到 1，例如 0.2 表示 20%。
+QUALITY_TIER1_MIN_RATIO=0.2
+
+# 推测性内容的最高允许占比；取值范围为 0 到 1，例如 0.4 表示 40%。
+QUALITY_SPECULATION_MAX_RATIO=0.4
+
+# 行为配置
+# 是否在发现严重质量问题时阻断报告生成或发布流程。
+QUALITY_BLOCK_ON_CRITICAL=true
+
+# 是否在质量分数偏低时输出告警，但不一定阻断流程。
+QUALITY_WARN_ON_LOW=true
+
+# 是否记录被质量规则阻断的来源，便于后续审计和排查。
+QUALITY_LOG_BLOCKED_SOURCES=true
+
+# 推测性内容的标记符号；用于在报告中提示该内容需要谨慎解读。
+QUALITY_SPECULATION_MARKER=⚠️
+
+# 是否为推测性内容追加文字标签，便于用户识别非确定性结论。
+QUALITY_SPECULATION_ADD_LABEL=true
+
+# 是否在完整度低于阈值时输出告警。
+QUALITY_WARN_COMPLETENESS=true
+
+# 是否在 Tier 1 一手来源数量或占比不足时输出告警。
+QUALITY_WARN_TIER1=true
+
+# ====================================
+# 多源交叉验证配置
+# ====================================
+
+# 是否启用多源交叉验证；启用后会对关键数据断言进行多来源交叉验证。
+QUALITY_VERIFICATION_ENABLED=true
+
+# 验证可信度最低阈值（0-1）；低于此值会触发警告。
+QUALITY_VERIFICATION_MIN_CONFIDENCE=0.6
+
+# 每份报告最多验证的断言数量；控制验证成本。
+QUALITY_VERIFICATION_MAX_CLAIMS=10
+
+# 是否在验证可信度低于阈值时发出警告。
+QUALITY_WARN_VERIFICATION=true
+
+# ====================================
+# 搜索 Provider 与 URL 校验配置
+# ====================================
+
+# 搜索顺序：grok-first 表示先跑 Grok 模型链、Tavily 兜底；tavily-first 保留旧行为。
+SEARCH_PROVIDER_ORDER=grok-first
+
+# 是否对 Grok 返回的来源 URL 做可达性校验；Tavily 来源不重复校验。
+SEARCH_URL_CHECK_ENABLED=true
+
+# Grok 来源 URL HEAD/GET 校验超时。
+SEARCH_URL_CHECK_TIMEOUT_MS=5000
+
+# Grok 来源 URL 校验并发上限。
+SEARCH_URL_CHECK_MAX_CONCURRENT=5
+
+# ====================================
+# 方法论框架配置
+# ====================================
+
+# 默认分析框架：auto | none | swot | porter-5forces | mckinsey-7s | pestel | timeline
+DEFAULT_FRAMEWORK=auto
+
+# 是否允许多轮深化研究。开启后，深度报告可追加证据缺口识别和二次搜索。
+DEEP_DIVE_ENABLED=false
+
+# 是否默认启用多轮深化研究；建议保持 false，由请求显式开启。
+DEEP_DIVE_DEFAULT=false
+
+# 每份 deep dive 报告最多追加的证据缺口搜索问题数。
+DEEP_DIVE_MAX_GAP_QUESTIONS=4
+
+# 每份 deep dive 报告最多执行的证据缺口搜索轮次；默认 2，避免无界搜索成本。
+DEEP_DIVE_MAX_ROUNDS=2
+
+# ====================================
+# 报告排版配置
+# ====================================
+
+# 是否在 HTML/PDF 渲染中自动生成目录。
+PDF_ENABLE_TOC=true
+
+# 是否在 Chromium PDF 中启用页眉页脚。
+PDF_ENABLE_HEADER_FOOTER=true
+
+# 预留主题配置：professional | minimal | academic
+HTML_THEME=professional
+
+# ====================================
+# 已废弃：图片/封面生成
+# ====================================
+
+# 当前报告流程不调用图片模型。不要再配置 IMAGE_*；历史本地 .env 或平台环境如果残留这些变量，当前代码会忽略。

.gitignore

@@ -9,7 +9,17 @@ dist/
 .env.local
 
 # Runtime data
+.planning/
+.wrangler/
 data/reports/*/
+data/model-comparison/
+data/*.sqlite
+data/*.sqlite-*
+data/search-cache.json
+data/search-audit.jsonl
+data/quality-history.jsonl
+data/tasks.json
+data/uploads/*/
 
 # Logs
 *.log
@@ -28,3 +38,4 @@ Thumbs.db
 # Temporary files
 *.tmp
 .cache/
+screenshots/