quickstart

name	quickstart
description	评审/上手引导：自动完成 装依赖 → 配置密钥 → 跑测试 → 启动 UI → 演示走查。当用户说「上手」「跑起来」「怎么跑」「启动」「运行这个项目」「demo」「quickstart」「run this」「帮我评审」或刚 clone 完想看效果时使用。

App Review Insights · 一键上手

目标：让评审在 5 分钟内跑通「App Store 链接 + 自然语言目标 → 清洗 → 动态主题 → Dashboard → PRD → 测试用例 → 追溯校验」的完整流水线。按下面顺序执行，每步验证通过再进下一步。

第 0 步：判断有没有模型密钥

先问用户一个问题：「你有 DeepSeek 或 Qwen(DashScope) 的 API key 吗？」

• 没有 key → 走「离线评审路径」（本文末尾），无需网络与密钥，可看到一次真实运行的全部产物并跑通全部默认测试。
• 有 key → 继续第 1 步。

第 1 步：安装依赖

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Python ≥ 3.10。若用户环境已有可用的 python/依赖，直接复用即可，不强求 venv。

第 2 步：配置密钥（Claude 不经手 key 本身）

cp agent_main/.env.example agent_main/.env

然后请用户自己编辑 agent_main/.env，把 key 填到 DEEPSEEK_API_KEY=（默认 Provider）或 DASHSCOPE_API_KEY=（同时把 LLM_PROVIDER 改为 qwen）。.env 已被 .gitignore 排除，绝不会被提交。不要替用户把明文 key 写进任何文件或命令。

配好后验证连通（一次最小调用，几乎零成本）：

python -c "
import sys; sys.path.insert(0,'agent_main')
from pydantic import BaseModel
import llm
class Ping(BaseModel): ok: bool
print(llm.complete(Ping, system='Reply ok=true', user='ping', temperature=0.0, timeout=30))"

第 3 步：跑默认测试（零成本、零网络）

pytest -m "not integration" -q

预期：115 passed。这套测试覆盖数据契约、清洗、五项证据 Gate、追溯链、失败降级，全部不调模型。

第 4 步：启动 UI 并走查

streamlit run app.py          # 端口被占时: streamlit run app.py --server.port 8502

浏览器打开后按这条演示路径走（约 3–5 分钟，实拉 RSS + 真实模型调用）：

1. 数据来源选 App Store URL，默认链接已填（Workout for Women）；分析目标输入自然语言，例如：「看用户的痛点，我们需要做什么改进，我们有哪些做的比较好？」（也可换任意美区 App 链接、上传 JSON/CSV、或勾选缓存样例——格式见 docs/IMPORT_FORMAT.md）。
2. 点「开始分析」→ 确认点 1：核对模型解析出的 Scope（评分/版本/日期过滤 + 语义焦点），可修改，点「确认开始」。
3. 等待主题发现与归类 → 确认点 2：审阅 Dashboard（评分分布、主题正负情绪、趋势、归类覆盖率），勾选要进 PRD 的主题，可写一句自己的产品判断（无证据的会标为 assumption），点「生成 PRD」。
4. 查看 tabs：Plan（findings 分优点/问题/需求，各带 confidence + support）→ Validation（五项代码 Gate + 语义校验的诚实结果，失败不隐藏）→ Trace（Review→Finding→Requirement→Test 追溯矩阵）→ Events（降级/错误审计日志）。每个产物均可下载。

第 5 步（可选）：LLM 集成测试与 gold benchmark

pytest -m integration -q                      # 需要 key，少量真实调用
python tests/bench_selection_analysis.py --help   # 分析车道 24 gold case（Candidate/Judge 隔离）
python tests/bench_selection_plan.py --help       # 计划车道 9 gold case

离线评审路径（无 key / 无外网）

• 一次真实运行的完整产物：sample_run/（14 个阶段产物 + events 日志，均标记为缓存）。
• 截图对应那次运行的 UI 下载件：docs/demo_run/（prd.md / product_plan.json / validation_report.json / traceability.json），截图走查见 README「截图与 PRD」。
• 默认测试：pytest -m "not integration" -q → 115 passed，零网络零费用。
• 独立产物检查器（零依赖黑盒复核追溯链与禁止字段）：

python scripts/verify_lean_prd.py sample_run/lean_prd

• UI 也可无 key 起动看界面：数据来源选「缓存样例 real_full_500」可跑通 获取→清洗→Dashboard（阶段 3 起需要 key）。

常见问题

现象	处理
RSS 拉不到（无外网/被限流）	UI 会自动降级并提示；改用「缓存样例」或上传 JSON/CSV
DeepSeek 报 tool_choice 400	已内置规避（LLM_MODE=JSON），不需要处理
8501 端口被占	--server.port 8502
想理解设计取舍	docs/ARCHITECTURE.md（架构与不做清单）、docs/DEVLOG.md（D1–D7 决策）、docs/PROMPTS.md（5 个 Prompt 合同）、docs/MODEL_SELECTION_*.md（模型选型实测）