内容
# 知情流
> *文档一直是知识层。知情流使之成为人工智能可以真正触及的知识层。*
**知情流** 是一个由信息架构师构建的 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，他厌倦了在四个工具之间切换上下文以回答一个问题：*用户没有找到什么？*
它连接您的文档主体、GA4 搜索分析、Jenkins CI 管道和 RAGAS 风格的评估层到 Claude — 在一次对话中。
```
Claude Desktop / Claude Code
│
│ JSON-RPC over stdio
▼
知情流
│
├── 搜索文档 → TF-IDF 主体搜索（可升级到 pgvector / ChromaDB）
├── 获取主题 → 按 ID 获取完整主题内容
├── 列出主题 → 主体索引，带有产品和类型过滤器
├── 获取内容空白 → GA4 零结果查询 → 排名内容空白列表
├── 获取构建状态 → Jenkins 发布管道状态
└── 评估管道 → RAGAS 风格评估：相关性 · 真实性 · 召回率
```
---
## 我们为什么要构建它
每个文档团队都会问同样的问题：*我们接下来应该写什么？*
答案曾经存在于三个或四个独立的地方 — GA4 中的搜索分析、文档站点中的现有内容、电子表格中的主题层次结构、Jenkins 中的构建状态。从“用户没有找到什么？”到“这里有一个草拟的主题”曾经需要数小时的上下文切换。
知情流将这些功能合并成一个对话。
```
获取内容空白 "47 名用户搜索了 X 但未找到任何结果"
↓
搜索文档 "最近的现有主题：rpm-upgrade-8.0"
↓
获取主题 "这里是完整的上下文内容"
↓
Claude 草拟 缺失部分，耗时不到两分钟
↓
评估管道 "真实性：0.91 · 相关性：0.87 · 召回率：0.74"
↓
信息架构师审查 → 发布 → 差距关闭 → 循环重复
```
变化最大的部分不是速度，而是信号。
您现在可以在支持票告诉您之前知道要写什么。
---
## 连接后您可以向 Claude 提问
> *"过去 30 天内返回结果为零的前十个搜索查询是什么？*
> *"运行 evaluate_pipeline 并使用 report_format markdown — 显示哪些查询表现不佳以及原因。*
> *"在主体中查找所有提及 Tableau 连接器的主题。今天文档构建是否通过？*
> *"用户搜索了 'silent RPM install' 47 次但未找到任何结果。查找最近的现有主题并草拟缺失部分。*
> *"哪些主题超过 90 天没有被审查？将它们标记为潜在真实性风险。*
---
## 快速入门
### 1. 克隆并安装
```bash
git clone https://github.com/Bipin-24/knowflow.git
cd knowflow
npm install
npm run build
```
### 2. 连接到 Claude Desktop
打开您的 Claude Desktop 配置：
| 操作系统 | 路径 |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
添加此块：
```json
{
"mcpServers": {
"知情流": {
"command": "node",
"args": ["/绝对路径/到知情流/dist/index.js"]
}
}
}
```
重启 Claude Desktop。您应该会在工具列表中看到 `知情流`。
### 3. 连接到 Claude Code
在项目根目录中添加 `.mcp.json`：
```json
{
"mcpServers": {
"知情流": {
"command": "node",
"args": ["../知情流/dist/index.js"]
}
}
}
```
---
## 工具
### `搜索文档`
文档主体中的语义搜索。
```
查询 字符串 必需 自然语言搜索查询
产品 字符串 可选 analytics-engine | ingres | actian-client | all
版本 字符串 可选 例如 "8.0", "11.x"
限制 数字 可选 1–10，默认 5
```
### `获取主题`
按 ID 检索主题的完整 Markdown 内容。
```
主题 ID 字符串 必需 来自 search_docs 结果的主题 ID
```
### `列出主题`
浏览主体索引并带有可选过滤器。
```
产品 字符串 可选 analytics-engine | ingres | actian-client | all
主题类型 字符串 可选 concept | task | reference | troubleshooting | all
```
### `获取内容空白`
显示返回零或少数结果的搜索查询 — 用户需要但尚不存在的内容。
```
天数 数字 可选 回顾窗口，默认 30
限制 数字 可选 最大差距数，默认 20
最小搜索量 数字 可选 最小搜索量，默认 2
```
每个空白返回 `空白类型`（缺失内容 | 低可发现性）、最近的现有主题、搜索量和推荐操作。
### `获取构建状态`
检查 Jenkins CI/CD 发布管道状态。
```
作业 字符串 可选 Jenkins 作业名称，默认 "actian-docs-publish"
```
### `评估管道`
在管道上运行 RAGAS 风格的评估。
```
查询 字符串[] 可选 测试查询。如果省略，则使用默认的 10 个查询。
报告格式 字符串 可选 summary | detailed | markdown （默认：summary）
```
| 指标 | 测量内容 |
|--------|-----------------|
| 答案相关性 | 检索的内容是否回答了查询？ |
| 真实性 | 声明是否有源主体支持？ |
| 上下文召回率 | 检索是否提供了最有用的内容？ |
---
## 架构
### 搜索
自带轻量级 TF-IDF 引擎 — 无外部依赖或 API 密钥。要升级到基于嵌入的语义搜索：
1. 在 `package.json` 中添加 `chromadb` 或 `pgvector`
2. 运行 `scripts/index_corpus.py` 嵌入主体
3. 在 `src/lib/search.ts` 中用向量相似性查询替换 `scoreTopics()`
### 评估
`src/lib/evaluator.ts` 使用确定性启发式方法作为 RAGAS 近似值 — 无需 LLM API 调用即可运行。使用 LLM 评估器替换为 [RAGAS Python 库](https://docs.ragas.io)。
### 实时数据
自带模拟 GA4 和 Jenkins 的真实数据。要连接实时源：
```bash
cp .env.example .env
# 填写 BIGQUERY_PROJECT_ID, JENKINS_URL, JENKINS_TOKEN
```
用于 GA4 站点搜索导出的 BigQuery SQL 在 `scripts/ga4_export.sql` 中。
---
## 项目结构
```
知情流/
├── src/
│ ├── index.ts # MCP 服务器 — 工具注册和路由器
│ ├── tools/
│ │ ├── searchDocs.ts
│ │ ├── getTopic.ts
│ │ ├── listTopics.ts
│ │ ├── getContentGaps.ts
│ │ ├── getBuildStatus.ts
│ │ └── evaluatePipeline.ts # RAGAS 风格评估
│ ├── data/
│ │ └── corpus.ts # 示例文档主题
│ └── lib/
│ ├── search.ts # TF-IDF 搜索引擎
│ └── evaluator.ts # 评估引擎
├── scripts/
│ └── ga4_export.sql # BigQuery 查询，用于实时 GA4 导出
├── .env.example
├── package.json
└── tsconfig.json
```
---
## 升级到实时数据
| 内容 | 状态 | 如何升级 |
|------|--------|----------------|
| 搜索 | TF-IDF（内置） | 换成 ChromaDB / pgvector |
| 内容空白 | 模拟 GA4 数据 | 连接 BigQuery — 见 `scripts/ga4_export.sql` |
| 构建状态 | 模拟 Jenkins 数据 | 在 `.env` 中添加 `JENKINS_URL` + `JENKINS_TOKEN` |
| 评估 | 确定性启发式方法 | 替换为 RAGAS Python 库 |
---
## 技术栈
- **运行时：** Node.js 18+ / TypeScript
- **协议：** `@modelcontextprotocol/sdk`
- **搜索：** TF-IDF → pgvector / ChromaDB
- **评估：** 确定性 RAGAS 近似值 → RAGAS Python
- **分析：** 模拟 GA4 → BigQuery
- **CI：** 模拟 Jenkins → Jenkins REST API
---
## 相关项目
- [`Documentation-AI-Assistant`](https://github.com/Bipin-24/Documentation-AI-Assistant) — RAG 管道和文档主体上的聊天界面
- [IA Playbook](https://information-architecture-playbook.vercel.app) — 用于 RAG 就绪文档的 AI 内容治理框架
---
## 作者
**Bipin Pandey** — 首席信息架构师
构建人类和 AI 系统都依赖的知识层。
[作品集](https://bipin-24.github.io) · [LinkedIn](https://www.linkedin.com/in/bipin-pandey24/) · [GitHub](https://github.com/Bipin-24)
