# FeedWatch MCP

**RSS/Atom 变更监控 API + MCP Server**
**当前阶段**：验证期准备（判定线：8 周内 5 个真实付费用户）

🌐 **English version**: [README.en.md](./README.en.md) · 中文在下方

---

## 从这里开始

| 你想了解 | 看这份 |
|---|---|
| **⭐ 现在什么状态、下一步做什么** | [📋 **工作计划与进展**](docs/工作计划与进展.md) |
| **整个项目长什么样** | [📐 项目蓝图](docs/架构/项目蓝图.md) |
| 开发要做什么 | [💻 软件开发需求说明书](docs/需求/软件开发需求说明书.md) |
| 客户怎么用它 | [📖 用户说明书](docs/需求/用户说明书.md) |
| **买服务器 + 部署** | [🖥️ 服务器采购与部署手册](docs/运营手册/服务器采购与部署手册.md) |
| **注册海外公司** | [🏢 海外公司注册与维护手册](docs/运营手册/海外公司注册与维护手册.md) |
| **给客户签发API Key** | [🔑 **API Key 管理与配额**](docs/运营手册/API Key管理与配额.md) |
| **自己先试用一遍** | [🧪 **内部测试指南**](docs/运营手册/内部测试指南.md) |
| **发布到MCP 生态** | [🔌 MCP生态发布指南](docs/运营手册/MCP生态发布指南.md) |
| **收款开通（Payoneer）** | [💳 Payoneer 收款链接操作手册](docs/运营手册/Payoneer收款链接操作手册.md) |
| 收款怎么配（通用） | [💰 收款与运营手册](docs/运营手册/收款与运营手册.md) |
| 为什么这么选 | [📋 决策记录-收款与主体](docs/决策/决策记录-收款与主体.md) |
| **改完代码要跑什么** | [🧪 **回归测试要求点清单**](docs/复盘/回归测试要求点清单.md) |
| **提交前自查（4 问 + 12 项检查）** | [✅ **提交前自查清单**](docs/复盘/提交前自查清单.md) |
| 踩过什么坑 | [🔍 调试复盘](docs/复盘/调试复盘.md) |
| 上线要查什么 | [✅ 上线检查清单](docs/复盘/上线检查清单.md) |
| 状态字段什么意思 | [🔢 状态字段语义](docs/复盘/状态字段语义.md) |

> ⚠️ **改代码前先看「回归测试要求点清单」** —— 里面有 89 项离线测试的覆盖现状、
> 19 项已知缺口、以及**已证伪的 4 处错误「已验证」**。
> **不要只看测试名声称覆盖了什么，要看它实际断言了什么。**

---

## 一句话说明

客户把 RSS/Atom/JSON Feed 的网址交给我们，我们替他们盯着；**内容变了就主动推送**，
并精确告诉他**哪个字段、从什么变成什么**。

**核心差异**：竞品多数只能报"新增条目"，我们能**检测已有条目被修改**并给出字段级 diff——
新闻更正错字、竞品悄悄改价格，这些都不产生新条目，但恰恰是客户最需要知道的。

---

## 文档体系（四层结构）

```
docs/
├── 架构/         【第 1 层】顶层设计
│   └── 项目蓝图.md                整个项目 + 架构 + 外部资源 + 阶段路线
│
├── 需求/         【第 2 层】做什么
│   ├── 软件开发需求说明书.md功能清单 + 验收标准 + 需求来源
│   └── 用户说明书.md                客户视角的产品说明与使用场景
│
├── 运营手册/     【第 3 层】怎么操作
│   ├── 服务器采购与部署手册.md       选型对比 + Vultr 注册购买 + Linux 部署
│   ├── 海外公司注册与维护手册.md     香港公司注册 + 银行开户 + 后续维护
│   ├── 内部测试指南.md              ⭐ 8 步实测流程（含MCP 与安全验证）
│   ├── API Key管理与配额.md          ⭐ 签发 Key + 各项限流 + 配额口径核对
│   ├── MCP生态发布指南.md            ⭐ 官方注册表 + 5 个目录收录方式
│   ├── Payoneer收款链接操作手册.md   ⭐ 验证期收款开通（注意：非 Checkout）
│   ├── 收款与运营手册.md            付费时机 + 收款配置 + 排障（第三部分已废弃）
│   └── 部署配置与待办-Windows方案.md （已弃用，保留参考）
│
├── 决策/         【第 4 层】为什么这么选
│   └── 决策记录-收款与主体.md       平台选型 + 主体时间线 + 被排除项（含 v2 纠错）
│
└── 复盘/         【第 5 层】经验沉淀
    ├── 回归测试要求点清单.md         ⭐ 89 项测试覆盖现状 + 19 项缺口 + 最小回归集
    ├── 调试复盘.md                 10 个缺陷 + 5 条交付规范 + 失误归因
    ├── 上线检查清单.md             三阶段 checklist + B1–B6
    ├── 状态字段语义.md             三状态正交表 + 错误码判读
    └── 事故复盘/
        └── 2026-10-13-www站点500事故复盘.md
```

### 分层判断标准

| 层 | 回答什么问题 | 变更频率 |
|---|---|---|
| **架构** | 整个项目长什么样 | 很少（季度级） |
| **需求** | 做什么功能、验收标准 | 中（月级） |
| **运营手册** | 怎么一步步做 | 高（跟着平台变化） |
| **决策** | 为什么这么选、为什么排除别的 | 低（决策后很少变） |
| **复盘** | 踩过什么坑、教训是什么 | 追加式 |

⚠️ **常见错误**：把"为什么选 A 不选 B"写进运营手册。
**平台会变（被收购、改费率），手册不会自动更新** —— 一份三个月前正确的手册，今天可能把人导向一个用不了的平台。

---

## 快速开始（开发者）

```bash
npm install
HOST=127.0.0.1 PORT=3001 PUBLIC_URL=https://api.tiici.com \
  FEEDWATCH_BOOTSTRAP_KEY=<至少32位随机> \
  npm start
curl http://127.0.0.1:3001/health
```

> ⚠️ Bind to `127.0.0.1`, never `0.0.0.0`. Put Nginx (or any reverse proxy) in
> front so TLS, access logs and WAF are not bypassed.

### 测试

```bash
npm test              # 87 项离线测试（5 个套件）
npm run test:live     # 28 项真实源测试（需出网）
```

---

## 技术栈

```
运行时      Node.js 22 ESM
依赖        fast-xml-parser（唯一运行时依赖）
HTTP        node:http 原生（零框架）
部署        Linux + Nginx + systemd / Windows + IIS
测试        自建轻量断言框架（无 jest/vitest）
规模        2143 行 / 7 模块
测试规模    87 项离线全绿，全部经「回退法证伪」
```

**为什么零框架依赖**：便于跨环境（Linux/Windows）部署，减少供应链风险。

---

## 目录结构

```
06MCP/
├── web/index.html         对外落地页（部署到 /）
├── docs/
│   ├── 工作计划与进展.md            ⭐ 当前状态 + 每日台账 + 下一步
│   ├── 架构/项目蓝图.md                整体架构 + 外部资源 + 阶段路线
│   ├── 需求/                          功能清单 + 实现状态 + 客户说明
│   ├── 运营手册/                ⭐ 内部测试 / Key 管理 / MCP 发布 / 收款 / 部署
│   ├── 决策/                      收款平台与主体决策（v2 含纠错）
│   └── 复盘/                ⭐ 提交前自查清单 / 回归测试要求点 / 调试复盘 / 上线清单 / 状态语义
├── src/                        7 模块 2242 行
├── scripts/                    ~2100 行 / 7 套件
│   ├── selfcheck-silent.js    ★ 三个高发模式的 12 项自动检查（npm test 第一道）
│   ├── selftest / regression*.js       92 项离线断言
│   ├── e2e.js                 端到端（含回退证伪用例）
│   └── livefeed-test.js       28 项真实源测试（需出网）
├── deploy/                     Linux/Windows/落地页/云防火墙部署脚本
├── server.json                 MCP 官方注册表清单
├── smithery.yaml               Smithery 一键安装配置
├── web/index.html              对外落地页
└── deliverables/gstack/        审查与发布报告（不随仓库公开）
```

---

## 当前状态

> 📋 **完整台账见 [`docs/工作计划与进展.md`](docs/工作计划与进展.md)**（每日工作 + 下一步 8 项）

### ✅ 已就绪

```
产品        https://api.tiici.com/ 落地页 + REST API + MCP 端点，全部线上
源码        2242 行 / 7 模块（零 Web 框架）
测试        12 项模式自查+ 92 项断言全绿 + 28 项真实源 = 2000 行 / 7 套件
安全        15 个缺陷全修（每个都做回退证伪）+ 三层防护
              云防火墙 / ufw / Nginx+TLS，3001 公网实测不可达
服务器      Vultr 167.179.112.40（Tokyo / $5/月 / Ubuntu 24.04.5）
运行        feedwatch.service active+enabled，Node v22.23.3，实测 RSS 93 MB
证书        api.tiici.com 已签发（至 2027-01-13，自动续期 dry-run 已验证）
配额        免费层 5 个监控点 / 6h 频率（**申报与实际强制一致**）
分发        GitHub 公开仓库 + tag v0.1.0 + server.json 通过官方 validate
依赖        fast-xml-parser 5.11.2（OSV 漏洞清零）
文档        15 份（含回归测试要求点清单、API Key 管理、内部测试指南）
```

### ⏳ 待办（完整版见工作计划）

| # | 事项 | 负责 | 阻塞什么 |
|---|---|---|---|
| 1 | **Payoneer 个人账户 + 收款链接**（⚠️ 非 Checkout）| 徐总 | 🔴 **收款前置条件** |
| 2 | 提交 MCP 官方注册表 | 徐总 | 分发（`mcp-publisher publish`）|
| 3 | 点 GitHub Release Publish | 徐总 | tag 已推送，只需点一下 |
| 4 | Smithery / mcp.so / mcpservers.org | 徐总 | 各 3-5 分钟 |
| 6 | 咨询税务师（第 3 周）| 徐总 | 后续合规 |
| 7 | TTL 调回 300 | 徐总 | — |

**⏸️暂缓**：海外公司注册 —— 验证期不需要，**确定要接 Checkout 2.0 / Stripe 时再办**

> 📌 **不在本项目范围**：www.tiici.com / game.tiici.com 的证书续签属于
> WordMaster 等其他站点，归各自项目台账管理，本台账不跟进。

---

## 核心判定线

| 指标 | 目标 |
|---|---|
| **真实付费用户** | **≥ 5 个（8 周内）** |
| 推送准确率/漏报率 | < 1% |
| 转化率（免费→付费） | > 5% |

⚠️ **不要用"技术跑通"当判定** —— **要有人掏钱**。技术跑通只是必要条件。

---

## ⚠️ 两条给后续接手者的提醒

**① 不要只看文档里的「已验证」三个字**

本次审查里，团队成员**至少 5 次**写了「已验证」而结论后来被推翻。
**可靠的方式是：临时把修复改回去，看测试会不会红。**

**② 声称「X 会失败」前，先证明 X 在应该成功时确实成功**

只测失败路径无法区分「X 有问题」和「工具有问题」。

---

> **遇到问题先看 `docs/复盘/调试复盘.md`** —— 那里记录了 10 个真实缺陷与它们被发现的经过，
> 避免重复踩坑。
>
> 完整审查报告：`deliverables/gstack/pre-launch-review-feedwatch-2026-10-12.md`