IntelliSource

AI-powered intelligent information aggregation and distribution platform.

快速上手（新用户）

零基础把系统跑起来（先装 Docker Desktop 与 uv）：

# 1. 安装依赖并注册 intellisource 命令
uv sync

# 2. 交互式初始化（生成 docker/.env、播种配置模板、写入起始信源）
uv run intellisource init

# 3. 一键启动全栈（db / redis / 迁移 / api / worker / beat）
uv run intellisource up

# 4. 自检配置（含运行中 API 健康检查）
uv run intellisource doctor --check-api

# 5a. 想快速看到效果 → 用内置主题包（init 已引导过此路径）
uv run intellisource topic list
uv run intellisource topic enable <topic-id> --channel wework

# 5b. 想精确控制信源 → 手动加载订阅并触发第一次采集
uv run intellisource subscriptions reload
uv run intellisource source list             # 找到 source id
uv run intellisource task trigger <source-id>

两条路径殊途同归：topic enable 是"信源导入 + 订阅创建"的打包版，最终都落到 subscription 配置好 + 触发一次采集。

Windows PowerShell / macOS / Linux 命令完全一致——intellisource up/down/migrate/logs/ps 跨平台封装 docker compose，无需安装 make。装了 make（Linux/macOS）也可用等价的 make up / make bootstrap。

核心概念（理解这 4 个即可上手）：

概念	含义	配置位置
source 信源	内容从哪来（RSS / API / 网页）	config/sources/
subscription 订阅	把匹配内容推给谁、走哪个渠道	config/subscriptions/
channel 渠道	推送目的地（企业微信 / 公众号 / 邮件）凭据	docker/.env
pipeline 流水线	采集 → 处理 → 分发的自动编排	config/pipelines/

完整链路需要 source + subscription + channel 三者都配置好才会有推送。

intellisource init 在宿主机运行（容器以只读挂载 config，容器内无法写）。任何"配置不生效"先跑 uv run intellisource doctor 自检。本地直接 uv run uvicorn/celery 时，进程会自动加载 docker/.env 中的 IS_* 与 LLM provider key。

配置管理（查看 / 修改 / 回滚）

📍 配置全貌（哪类配置在哪、谁改、怎么改）见 config/README.md——新手先看这张地图。

配置是 YAML 为准（SSOT）+ 运行时 DB 双层模型：编辑 config/**/*.yaml 后 reload 生效并记录版本快照；API/CLI 的热编辑是临时态，下次 reload 会被 YAML 覆盖。

操作	命令
查看单条详情	intellisource subscriptions show <id> / intellisource source show <id>
改订阅（含 digest 模板/渲染模式）	intellisource subscriptions patch <id> --render-mode llm-freeform
改信源	intellisource source update <id> --url … --schedule-interval …
reload 前预览改动	intellisource subscriptions diff / intellisource source diff
一览两域漂移 + 最新版本	intellisource config status
列出版本快照	intellisource subscriptions versions / intellisource source versions
回滚到某版本	intellisource subscriptions rollback <version>

diff / config status 的 reload 预览会区分两种语义：subscriptions reload 是全量同步（YAML 删掉的订阅被 PAUSE）；sources reload 是加法 upsert（YAML 没有的 DB 信源 PRESERVE 保留）。subscriptions show 额外标注 digest 的 configured render_mode 与"协作者缺失时降级 code"提示。

订阅匹配规则（match_rules 语义）

订阅的 match_rules 决定"哪些内容会推给这条订阅"。只识别下面 5 个键，其它键名（含拼写错误）在 reload 时记 WARN 并被静默忽略——看到 WARN 先核对键名。可运行示例见 config/examples/subscriptions.example.yaml。

键	类型	作用	命中语义
keywords	list[str]	标题+正文关键词	见下方操作符表（混合 AND / OR）
tags	list[str]	内容标签	OR：命中任一即正向匹配
discipline_tags	list[str]	学科标签（与 tags 独立的维度）	OR：命中任一即正向匹配
source_names	list[str]	信源名白名单	强约束：设置后内容信源必须在列表内，否则整条丢弃
min_score	float	相关性阈值	通过其它维度后，分数 < 阈值再过滤掉（0 = 不过滤）

keywords 操作符（按 token 前缀）：

写法	含义	语义
word	普通词	OR 正向信号；大小写不敏感
+word	必含	AND 强约束；缺失则整条丢弃；大小写不敏感
!word	必不含	AND 强约束；出现则整条丢弃；大小写不敏感
/pattern/	正则	命中即正向信号；大小写敏感，带 1s ReDoS 超时保护（超时按未命中处理）

判定顺序：① 若 keywords/tags/discipline_tags/source_names 全空 → 永不匹配（reload 时 WARN）；② source_names 强约束先过；③ keywords 的 +/! 强约束先过；④ 再要求至少命中一个正向维度（keywords 普通词/正则、tags、discipline_tags、或已通过的 source_names），否则丢弃；⑤ 最后按 min_score 过滤。一句话：+/!/source_names 是 AND 硬门槛，普通 keywords/tags/discipline_tags 是 OR 正向信号。

对话检索（chat）

对已采集的资料库做基于检索的对话（RAG）。CLI 与 Web 两个入口对接同一组 /search/chat 端点：

CLI — intellisource chat：

# 单次问答（打印回答 + 引用来源；--json 输出原始响应）
uv run intellisource chat "最近有哪些关于 LLM 的进展？"

# 交互式会话（自动保持上下文 session_id；空行 / exit / Ctrl-D 退出）
uv run intellisource chat

Web — 浏览器访问 http://localhost:8000/chat：

一个最简前端（HTML + SSE），用 fetch 流式消费 /api/v1/search/chat/stream，逐 token 渲染回答并列出引用来源。页面本身公开可加载；若配置了 IS_API_KEY，在右上角输入框填入即可（只存于本地浏览器，随每次请求以 X-API-Key 头发送）。

API 文档 / 轻量管理面

http://localhost:8000/docs 已公开可访问（Swagger UI）。右上角点 Authorize，填入 X-API-Key（同 IS_API_KEY）后即可直接调用全部管理 API——source / subscription 的增删改查、reload、rollback 等——当作一个轻量管理面使用，无需额外装工具。

开发环境

以下步骤仅用于本地裸进程（非 Docker）开发；Docker 路径 intellisource up 已在容器内自动完成迁移，无需手动执行 alembic upgrade head。

uv sync
uv run alembic upgrade head

测试运行

单元测试

单元测试无外部依赖，可直接在本地运行：

uv run pytest tests/unit/ -q --tb=short

集成测试

集成测试分为两类：

不依赖 Docker 的集成测试（本地可直接运行）：

uv run pytest tests/integration/test_celery_worker_wiring.py -q --tb=short

依赖 Docker 的集成测试（pg_container / pg_session / pg_truncate fixtures）：

这类测试需要本地 Docker daemon 运行，使用 pgvector/pgvector:pg16 镜像启动临时 PostgreSQL 容器。Docker 不可用时，pytest 会自动跳过相关测试（通过 pytest_collection_modifyitems hook），并输出跳过原因：

SKIPPED — Docker daemon not available locally — integration tests skipped;
GREEN verification deferred to CI (ubuntu-latest with built-in Docker)

启动 Docker 后即可本地运行全部集成测试：

uv run pytest tests/integration/ -q --tb=short

CI 验证

GitHub Actions 使用 ubuntu-latest（内置 Docker），所有集成测试在 CI 中完整运行。详见 .github/workflows/ci.yml。

全量测试

uv run pytest -q --tb=short

质量门禁

本项目用 ruff / mypy / pytest / import-linter / deptry / vulture / pydeps 七件套覆盖风格、类型、功能、架构、依赖、死代码、可视化。本地一键跑全套：

make check         # arch + deps + deadcode + ruff + mypy + pytest

命令	工具	目的
make arch	uv run lint-imports	架构契约（分层 / 禁止依赖 / 独立模块），配置见 pyproject.toml [tool.importlinter]
make deps	uv run deptry src	依赖卫生（未声明 / 未使用 / transitive 直 import）
make deadcode	uv run vulture	死代码（参数 / 变量 / 方法），allowlist 在 .vulture_whitelist.py
make deps-graph	uv run pydeps ...	渲染依赖图 SVG（需本机装 Graphviz dot）
make lint-fix	ruff format + ruff check --fix	自动修复风格问题

Windows 用户没 make 时直接跑 uv run <tool>：

uv run lint-imports --no-cache
uv run deptry src
uv run vulture
uv run pydeps src/intellisource --max-bacon=2 --cluster --noshow -o docs/arch/deps-graph.svg

CI 集成

• 每个 PR：lint job 跑 ruff + mypy + import-linter + deptry + vulture，架构治理三工具当前为 observation 模式 (continue-on-error: true)，等基线条目（见 BACKLOG B-020 ~ B-028）清零后切为强制门禁
• 每日 02:00 UTC：arch-graph job 自动渲染 docs/arch/deps-graph.svg 并 upload 为 artifact
• 手动触发：gh workflow run CI

新增违规不会被 observation 模式静默 — 会在 CI 日志显式打印，方便 PR 作者在新代码上即时发现。

治理基线快照

最新一次扫描见 docs/reviews/code/CODE-SCAN-arch-20260524-r1.md。