科研工作流协调服务，统一管理 FastRead、FastWrite、FastNews 等模块的工作流程。
前端根地址默认进入 /intro 宣传页；研究工作台位于 /workspace。
- 个人密钥工作区: 为每个成员分配独立密钥，管理阅读脉络、关注作者、研究标签
- FastInsight 收件箱: 接收每日论文推送、研究信号，支持标记已读
- SSO 单点登录: 集成 FastCAS 统一身份，一次登录访问所有模块
- 工作流引擎: 管理跨模块的研究流水线，顺序执行各环节任务
- FastTask 集成: 接收 FastTask 发布的任务流水线，自动追踪完成进度
- Node.js 22.13+（使用内置 SQLite 模块）
- npm 或 pnpm
# 克隆仓库
git clone <repo-url>
cd FastResearch
# 安装依赖
npm install
# 配置环境变量（可选）
cp .env.example .env
# 启动服务
npm run server
# 开发模式（前端 + 后端）
npm run dev在 .env 或 .env.local 中配置：
首次启动建立 SQLite 账号库；已有 data/access.json 将经过校验和备份后迁移。参见 账号迁移与回滚。默认管理员账号为 admin，默认密码为 admin123456。生产环境请通过 ADMIN_USERNAME、ADMIN_PASSWORD 和 FASTINSIGHT_INGEST_KEY 环境变量设置凭证。
# 服务端口
PORT=8787
# 数据目录
FASTRESEARCH_DATA_DIR=data
# FastInsight 自动分发名册
FASTINSIGHT_ROSTER=../fastinsight/assets/colleagues.yaml
# 公共访问地址
FASTRESEARCH_PUBLIC_URL=http://127.0.0.1:8787
# FastCAS 单点登录
FASTCAS_ISSUER=https://fastcas.example.com
FASTCAS_CLIENT_ID=fastresearch
FASTCAS_CLIENT_SECRET=your-client-secret
# 模块地址
FASTREAD_URL=http://127.0.0.1:3015
FASTNEWS_URL=http://127.0.0.1:4173
# Cookie 配置
# 成员登录态保存在 data/accounts.sqlite，由 HttpOnly Cookie 引用。
# 部署在 fastrd.io 时建议设为 .fastrd.io，保证裸域和 www 共用登录态；
# 留空时服务会按请求 Host 自动推断（www.fastrd.io -> .fastrd.io）。
FASTRESEARCH_COOKIE_NAME=fr_session
FASTRESEARCH_COOKIE_DOMAIN=
FASTRESEARCH_COOKIE_SAMESITE=Lax
# CORS 额外来源（逗号分隔）
FASTRESEARCH_CORS_ORIGINS=GET /api/admin/fastinsight/roster- 管理员读取colleagues.yaml、版本号与文件名PUT /api/admin/fastinsight/roster- 校验并原子保存研究领域、关键词、分发人物和默认负责人；提交旧版本号会返回409
POST /api/auth/login-key- 个人密钥登录GET /api/fastcas/authorize- 启动 FastCAS SSO 登录GET /api/fastcas/callback- FastCAS 回调处理POST /api/auth/logout- 登出
GET /api/member- 获取成员信息（关注作者、研究标签、收件箱）POST /api/inbox- 标记收件箱已读PUT /api/authors- 更新关注作者PUT /api/tags- 更新研究标签PUT /api/impression- 更新研究印象
GET /api/workflow- 获取当前工作流POST /api/workflow- 创建/更新工作流POST /api/workflow/complete- 完成当前工序GET /api/workflow/team- 团队工作流视图
POST /api/workflow/publish- 接收工作流发布（支持新旧协议）GET /api/workflows- 查询流水线列表（活跃、待开始、已完成）GET /api/workflows/{id}- 获取流水线详情POST /api/workflows/{id}/start- 启动流水线POST /api/workflows/{id}/stages/{stage_id}/complete- 完成工序
GET /api/admin/stats- 系统统计信息POST /api/admin/migrate-key- 密钥迁移POST /api/admin/rotate-key- 密钥轮换
FastTask 可使用 FASTTASK_INGEST_KEY 配置专用 X-FastTask-Key 发布凭证；该凭证只用于工作流发布，不影响 FastInsight 的 FASTINSIGHT_INGEST_KEY。
FastResearch 回传工序完成证据时使用 FASTTASK_URL + FASTTASK_API_KEY，请求 FastTask 的 /api/v1/integrations/fastresearch/progress，并通过 X-API-Key 认证。FastTask 对应配置为 FASTTASK_FASTRESEARCH_INGEST_KEY；同一工序事件使用稳定 event_id 幂等，服务重启后会继续重试待同步事件。
POST /api/content/reading/publish- FastRead 推送阅读记录POST /api/insight/publish- FastInsight 推送研究信号POST /api/fastinsight/case- FastInsight 一键到达：发布论文名称与论文地址
详细 API 文档见 docs/api.md
FastResearch 实现了与 FastTask 的任务流水线集成，支持接收 FastTask 发布的研究任务，追踪工序完成进度，并回传完成事件。
FastTask FastResearch 各业务模块
│ │ │
│ 发布任务流水线 │ │
├──────────────────────────────> │
│ (dispatch payload) │ │
│ │ │
│ 返回接收回执 │ │
<──────────────────────────────┤ │
│ │ │
│ │ 用户启动流水线 │
│ ├─────────────────────────>│
│ │ │
│ │ 用户完成工序 │
│ <─────────────────────────┤
│ │ │
│ 接收完成事件 │ │
<──────────────────────────────┤ │
│ (stage completion) │ │
FastTask 使用 fasttask-dispatch-v1 协议版本发布任务：
{
"schema_version": "fasttask-dispatch-v1",
"dispatch_id": "dispatch-001",
"dispatch_revision": 1,
"receiver_ref": "account-123",
"title": "研究任务标题",
"description": "任务描述",
"task_id": "task-001",
"task_revision": 1,
"stages": [
{
"stage_id": "stage-1",
"module": "fast-read",
"title": "阅读论文",
"description": "阅读相关文献",
"success_criteria": "完成精读并标注",
"completion_target": "record_progress"
}
]
}fast-read- FastRead 阅读与检索fast-write- FastWrite 写作工作区fast-news- FastNews 资讯跟踪
个人 Key 是 FastResearch 与 FastTask 之间唯一的用户凭证。已登录成员点击页面上的「打开 FastTask」会经 /api/fasttask/login 跳转到 FastTask 登录入口；FastTask 校验 state 后把浏览器送回 FastResearch，FastResearch 再出一次性票据（audience=fast-task）并 302 到 FastTask 回调。FastTask 服务端用共享密钥兑换票据，按稳定的 accountId 创建或复用本模块用户，原始个人 Key 不会离开 FastResearch。
需要在两边配置：
| 变量 | 配置位置 | 说明 |
|---|---|---|
FASTTASK_PUBLIC_URL |
FastResearch | 浏览器访问 FastTask 的公开地址 |
FASTRESEARCH_FASTTASK_SSO_SECRET |
FastResearch | 至少 32 字符，与 FastTask 侧一致 |
FASTTASK_FASTRESEARCH_LOGIN_ENABLED |
FastTask | 设为 true 启用 Key 登录 |
FASTTASK_FASTRESEARCH_URL |
FastTask | FastTask 服务端访问 FastResearch 的地址 |
FASTTASK_FASTRESEARCH_PUBLIC_URL |
FastTask | 浏览器访问 FastResearch 的公开地址 |
FASTTASK_FASTRESEARCH_SSO_SECRET |
FastTask | 与 FastResearch 侧一致 |
FastResearch 工作台通过 GET /api/fasttask/today 展示当前成员在 FastTask 的当天任务，GET /api/workflow/team 同时返回每位成员当天的 FastTask 任务进度。FastResearch 服务端使用 FASTTASK_URL + FASTTASK_API_KEY 调用 FastTask 的 /api/v1/integrations/fastresearch/today；FastTask 侧对应配置为 FASTTASK_FASTRESEARCH_INGEST_KEY，两边的 Key 必须一致。没有收到任务时，工作台显示「未接受到任务」。
本机以 FASTTASK_ENV=production 运行且公开地址为回环 HTTP 时，FastTask 还需设置 FASTTASK_FASTRESEARCH_LOOPBACK_HTTP=true。完整接口与安全规则见 docs/key-login.md。
详细集成说明和示例代码见：
- FastTask 集成方案 - 完整设计文档
- 集成使用示例 - API 调用示例
data/accounts.sqlite- 账号、身份链接、FastCAS 会话data/workflows.sqlite- 工作流、工序、完成记录、待回传事件
data/access.json- 个人密钥、关注作者、研究标签、收件箱（旧格式，兼容保留）
FastResearch/
├── server/ # 服务端代码
│ ├── index.mjs # 主服务器
│ ├── account-store.mjs # 账号存储
│ ├── workflow-store.mjs # 工作流存储
│ ├── fasttask-dispatch.mjs # FastTask 集成逻辑
│ ├── fastcas-http.mjs # FastCAS 认证
│ └── service-ingest.mjs # 服务接收校验
├── src/ # 前端代码
│ ├── App2.tsx # 主应用组件
│ ├── index.css # 样式
│ └── i18n.ts # 国际化
├── docs/ # 文档
│ ├── api.md # API 文档
│ ├── sso.md # SSO 集成说明
│ ├── fasttask-integration.md # FastTask 集成方案
│ └── fasttask-integration-example.md # 使用示例
└── package.json
# 运行所有测试
npm test
# 运行 FastTask 集成测试
npm run test:fasttask- 使用 ESM 模块
- 服务端使用 Node.js 内置模块优先
- 前端使用 React + TypeScript
- 遵循项目现有代码风格
# 构建前端
npm run build
# 启动生产服务
npm run server本仓库 main 推送后由 GitHub Actions 工作流 CD FastResearch 构建前端；若仓库 Secrets 配好了 SSH，会自动在服务器执行 scripts/deploy-local.sh。
服务器本机也有 systemd 定时拉取 origin/main 并热更新，不依赖 GitHub Secrets。
生产进程：
npm run build
npm start # node --env-file=.env.production server/index.mjsserver/index.mjs 会同时提供 /api/* 与 dist/ 静态资源。监听地址由 HOST/PORT 控制，默认 127.0.0.1:8787，前面用 nginx 反代 80 端口。
需要的 GitHub Secrets：DEPLOY_HOST、DEPLOY_USER、DEPLOY_SSH_KEY，可选 DEPLOY_KNOWN_HOSTS。
# 构建镜像
docker build -t fastresearch .
# 运行容器
docker run -d \
-p 8787:8787 \
-v $(pwd)/data:/app/data \
-e FASTCAS_ISSUER=https://fastcas.example.com \
fastresearch前端可以单独部署到 Vercel：
npm run build
vercel deploy后端需要部署到支持 Node.js 的服务器。