CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

AI LiaoWang Web App — 基于 Flask 的爬虫管理与数据采集系统，支持脚本爬虫和通用配置爬虫，集成 AI 对话与深度采集功能。

常用命令

# 激活虚拟环境
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 初始化数据库（首次运行必须执行）
python init_db.py

# 启动开发服务器
python run.py
# 访问 http://localhost:5000

默认管理员账号：admin / admin

项目结构

ai-LiaoWangweb-app/
├── run.py                  # 入口：create_app() + 启动服务
├── init_db.py              # 数据库初始化脚本（创建 admin + 默认爬虫源）
├── requirements.txt        # Python 依赖
├── app/
│   ├── __init__.py         # Flask 应用工厂，注册所有 Blueprint
│   ├── config.py           # 配置（SQLite + SECRET_KEY）
│   ├── models.py           # SQLAlchemy 数据模型
│   ├── routes/             # 路由蓝图
│   │   ├── main_routes.py      # 首页、登录
│   │   ├── source_routes.py    # 爬虫源 CRUD
│   │   ├── collection_routes.py # 采集任务管理
│   │   ├── data_routes.py      # 数据查看/导出
│   │   ├── deep_routes.py      # 深度采集
│   │   └── ai_routes.py        # AI 模型管理 & 对话
│   ├── spider/             # 爬虫核心
│   │   ├── engine.py           # 通用爬虫引擎（GenericSpiderEngine）
│   │   ├── baidusearch.py      # 百度搜索脚本（search 函数入口）
│   │   └── config.json         # 爬虫配置
│   ├── templates/          # HTML 模板（含 partials/ 局部）
│   └── static/             # 静态资源（CSS/JS/ECharts/FontAwesome）
└── app/app.db              # SQLite 数据库（运行后生成）

架构要点

Flask 应用工厂模式：create_app() 在 app/__init__.py 中创建实例，初始化 db、login_manager，注册 6 个 Blueprint。
数据模型（app/models.py）：
- User — 用户认证
- SpiderSource — 爬虫源（支持 script 脚本型和 generic 配置型）
- SpiderTask（别名 CollectionTask）— 采集任务
- SpiderResult — 采集结果
- DeepCollection — 深度采集内容
- AIModel / TokenUsageLog / AIConversation / AIMessage — AI 相关
爬虫引擎（app/spider/engine.py）：GenericSpiderEngine 通过 URL + selectors 配置实现无代码爬虫，基于 requests + BeautifulSoup。
脚本爬虫约定：在 app/spider/ 下新建 .py 文件，实现 search(keyword, limit) 函数，即可在爬虫源管理中选择"自定义脚本"类型。
数据库：SQLite，URI 在 app/config.py 中配置，db.create_all() 在应用启动时自动建表。

你是我的结对工程师。我们要在这个仓库里做一次小迭代。

规则： 1) 先用 3-5 句话复述你理解的问题/目标，并列出不确定点提问 2) 给出一个小方案（含文件位置/边界/验证方式），等我确认 3) 拆成 2-5 分钟可完成的小任务清单（每项含“如何验证”） 4) 实现时优先 TDD：先写失败测试，再修复到通过，再重构 5) 每完成一个小任务就准备一条可 review 的 commit（我会决定是否提交）

Claude Code 配置：superpowers + gstack

主干由两个插件组成：

superpowers —— 思考与流程层（plan/brainstorm/debug/TDD/review/verify）
gstack —— 执行与外部世界层（browser/QA/ship/deploy/canary/护栏）

类比：superpowers 是大脑，gstack 是手脚。

核心原则

流程归 superpowers：所有 plan、brainstorm、debug、TDD、verify、 code review 默认走 superpowers。
执行归 gstack：所有浏览器操作、QA 测试、ship、deploy、canary、 retro 走 gstack。
独立 reviewer 通道：作者和审查者绝不在同一上下文里互评。
证据优先：声明完成前必须收集可验证的证据。
遇到歧义先 brainstorm。

浏览器规则

/browse 是唯一的浏览器入口。禁止使用 mcpclaude-in-chrome* 和 mcpcomputer-use* 来操作浏览器。

不要重复造轮子

下列能力只走 superpowers：

plan / brainstorm / writing-plans / executing-plans
TDD / debugging / verification
code review（请求和接收）
subagent / parallel dispatch
worktrees

下列能力只走 gstack：

浏览器、QA、ship、deploy、canary、retro、护栏

默认 skill 路由表

下面这张表是日常工作的"地图"。任何任务先查表，知道默认走哪个 skill。

任务	默认 skill	备选/补强
想清楚要做什么	`superpowers:brainstorming`	—
写实施计划	`superpowers:writing-plans`	多视角审查 → `gstack:/plan-*-review`
执行计划	`superpowers:executing-plans` + worktrees	并行 → `dispatching-parallel-agents`
写代码	`superpowers:test-driven-development`	—
调试 bug	`superpowers:systematic-debugging`	看真实页面 → `gstack:/browse`
跑前端看效果	`gstack:/browse`	—
端到端 QA（带修 bug）	`gstack:/qa`	—
完成前自检	`superpowers:verification-before-completion`	—
请求代码审查	`superpowers:requesting-code-review`	二次意见 → `gstack:/review`
收尾分支	`superpowers:finishing-a-development-branch`	—
Ship 发布	`gstack:/ship` → `/land-and-deploy`	—
上线后监控	`gstack:/canary` / `/benchmark`	—
写发布文档	`gstack:/document-release`	—
周回顾	`gstack:/retro`	—
危险命令护栏	`gstack:/careful` 或 `/guard`	—

CLAUDE.md 6.7 KB تاريخچه خام