airlabs-manage/AirLabs AI 能力需求文档.md

AirLabs · AI 能力需求文档

V2 功能模块 | 更新日期：2026-02-13

---

1. 功能概述

为 AirLabs 项目管理系统接入 AI 能力，实现：

1. 自动报告生成 — 系统定时汇总项目、产出、成本数据，由 AI 大模型生成自然语言总结
2. 飞书私聊推送 — 通过飞书自建应用将报告以卡片消息形式私聊推送给指定管理人员
3. 项目风险预警 — 基于规则引擎 + AI 分析，识别项目风险并在仪表盘展示

本版本不包含：

• 前端 AI 聊天助手页面
• 自然语言数据问答
• 按权限分级推送（所有接收人看到相同完整报告）

以上功能列入后续迭代计划。

---

2. AI 模型选型

项目	选型
模型	豆包（Doubao）— 字节跳动旗下大语言模型
平台	火山引擎 ARK
模型版本	doubao-seed-1-8-251228
API 协议	OpenAI 兼容（使用 openai Python SDK）
API 地址	https://ark.cn-beijing.volces.com/api/v3

调用方式

from openai import OpenAI

client = OpenAI(
    api_key="<ARK_API_KEY>",
    base_url="https://ark.cn-beijing.volces.com/api/v3"
)

response = client.chat.completions.create(
    model="doubao-seed-1-8-251228",
    messages=[
        {"role": "system", "content": "你是 AirLabs 项目管理助手..."},
        {"role": "user", "content": "<数据上下文>"}
    ]
)

降级策略

• API Key 未配置 → 报告仅包含数据模板，不含 AI 摘要
• API 调用失败 → 自动降级为纯数据报告，记录错误日志
• 超时设置：单次调用 30 秒超时

---

3. 自动报告功能

3.1 报告类型与推送时间

报告类型	推送时间	数据范围
日报	每天 20:00	当天数据
周报	每周五 20:00	本周一至周五
月报	每月1日 10:00	上月完整数据

时区：Asia/Shanghai（北京时间）

3.2 日报内容

📊 AirLabs 日报 — 2026-02-13

【今日概览】
• 进行中项目：X 个
• 今日提交：X 人次，总产出 Xm Xs
• 今日未提交：张三、李四

【各项目进展】
• 项目A：进度 XX%，今日产出 Xs
• 项目B：进度 XX%，今日产出 Xs

【风险提醒】
⚠️ 项目C：距截止仅剩 X 天，进度仅 XX%

【AI 点评】
（豆包生成的自然语言总结）

3.3 周报内容

📋 AirLabs 周报 — 第X周（MM/DD - MM/DD）

【项目进展】
• 项目A：周初 XX% → 周末 XX%，本周产出 Xs
• 项目B：周初 XX% → 周末 XX%，本周产出 Xs

【团队产出】
• 本周总产出：Xm Xs
• 人均日产出：Xs
• 效率最高：XXX（日均 Xs）

【成本概览】
• 本周人力成本：¥X
• 本周 AI 工具支出：¥X
• 本周外包支出：¥X

【损耗排行】
• 项目A：损耗率 XX%
• 项目B：损耗率 XX%

【AI 分析与建议】
（豆包生成的深度分析）

3.4 月报内容

📈 AirLabs 月报 — 2026年X月

【月度总览】
• 进行中项目：X 个
• 本月完成项目：X 个
• 月度总产出：Xm Xs
• 月度总成本：¥X

【各项目成本明细】
| 项目 | 人力 | AI工具 | 外包 | 固定开支 | 总成本 |
| ... |

【盈亏概览】（仅客户正式项目）
• 项目A：回款 ¥X，成本 ¥X，利润 ¥X
• 总利润率：XX%

【月度损耗】
• 总损耗：Xs（损耗率 XX%）
• 测试损耗：Xs
• 超产损耗：Xs

【人均产出统计】
• 月度人均产出：Xs
• 较上月变化：+XX% / -XX%

【AI 深度分析】
（豆包生成的月度总结、趋势分析、改进建议）

---

4. 飞书推送机制

4.1 接入方式

• 类型：飞书自建应用（非 Webhook 群机器人）
• 能力：私聊发送消息给指定个人
• 消息格式：飞书交互式卡片（Interactive Card）

4.2 所需权限

权限	权限标识	用途
以应用身份发消息	im:message:send_as_bot	发送私聊消息
通过手机号获取用户ID	contact:user.id:readonly	查找接收人

4.3 接收人配置

通过 .env 文件配置接收人手机号，逗号分隔：

REPORT_RECEIVERS=18002277047,13811803069,13636518028,13811126887

姓名	手机号
沈海川	18002277047
李海	13811803069
曾恺	13636518028
黄雪婷	13811126887

4.4 推送流程

定时触发 / 手动触发
    ↓
report_service 汇总数据库数据
    ↓
ai_service 调用豆包生成摘要
    ↓
组装飞书卡片 markdown
    ↓
feishu_service 获取 tenant_access_token
    ↓
通过手机号查询每个接收人的 user_id
    ↓
逐个发送私聊卡片消息

---

5. 项目风险预警

5.1 风险评估维度

维度	规则	风险等级
进度风险	实际进度 < 预期进度（按时间线性估算）	中/高
超期风险	距截止不足 7 天且进度 < 80%	高
损耗风险	损耗率 > 50%	中；> 80% 高
产出停滞	近 7 天无提交或产出骤降 > 50%	高

5.2 展示位置

• 仪表盘：新增风险预警卡片区域，展示所有中/高风险项目
• 日报：风险提醒段落
• 周报/月报：风险汇总段落

5.3 AI 增强

对标记为中/高风险的项目，调用豆包生成：

• 风险原因分析
• 改进建议
• 预估影响

---

6. 技术架构

┌──────────────────────────────────────────────────┐
│  FastAPI 后端                                     │
│                                                  │
│  ┌─────────────┐   ┌────────────────────┐        │
│  │ APScheduler  │──→│ report_service.py  │        │
│  │ 定时调度      │   │  数据汇总          │        │
│  │ • 日报 20:00  │   │  ↓                │        │
│  │ • 周报 五20:00│   │  ai_service.py    │        │
│  │ • 月报 1日10  │   │  调用豆包 AI       │        │
│  └─────────────┘   │  ↓                │        │
│                    │  feishu_service.py │        │
│  ┌─────────────┐   │  飞书私聊推送       │        │
│  │ reports.py   │──→│                   │        │
│  │ 手动触发 API  │   └────────────────────┘        │
│  └─────────────┘                                 │
│                                                  │
│  ┌─────────────┐   ┌────────────────────┐        │
│  │ dashboard.py │──→│ ai_service.py      │        │
│  │ 仪表盘 API   │   │ 风险预警分析        │        │
│  └─────────────┘   └────────────────────┘        │
└──────────────────────────────────────────────────┘
         │                        │
         ▼                        ▼
┌──────────────┐         ┌──────────────┐
│  SQLite 数据库 │         │  豆包 AI API  │
│  airlabs.db   │         │  ARK 平台     │
└──────────────┘         └──────────────┘
                                │
                                ▼
                        ┌──────────────┐
                        │  飞书开放平台  │
                        │  私聊消息推送  │
                        └──────────────┘

新增依赖

包名	用途
openai	调用豆包 AI（OpenAI 兼容协议）
httpx	异步 HTTP 请求（飞书 API）
apscheduler	定时任务调度
python-dotenv	读取 .env 配置

---

7. 新增文件说明

文件路径	用途
backend/.env	环境变量：API Key、飞书凭证、接收人
backend/services/init.py	services 包初始化
backend/services/ai_service.py	豆包模型调用封装
backend/services/report_service.py	报告数据汇总 + AI 摘要
backend/services/feishu_service.py	飞书应用消息推送
backend/services/scheduler_service.py	APScheduler 定时任务
backend/routers/reports.py	手动触发报告 API

---

8. API 接口

方法	路径	说明	权限
POST	/api/reports/daily	手动触发日报	超级管理员
POST	/api/reports/weekly	手动触发周报	超级管理员
POST	/api/reports/monthly	手动触发月报	超级管理员

---

9. 后续迭代计划

优先级	功能	说明
P0	AI 智能问答助手	前端聊天页面，自然语言查询系统数据
P1	按权限分级推送	不同角色收到不同内容的报告
P1	报告历史存储	保存历史报告，支持回看
P2	飞书交互式操作	在飞书卡片上直接查看详情、跳转系统
P2	团队效率 AI 分析	AI 深度分析成员效率趋势和分配建议

---

10. 配置清单

已获取

配置项	值
豆包 API Key	846b6981-9954-4c58-bb39-63079393bdb8
豆包模型	doubao-seed-1-8-251228
飞书 App ID	cli_a90478156bf85bd7
飞书 App Secret	87N2nnx6Yv56TPjl2GraLdKOjFiGOSGp
接收人	沈海川、李海、曾恺、黄雪婷

飞书应用已开通权限

• im:message:send_as_bot — 以应用身份发消息
• contact:user.id:readonly — 通过手机号获取用户 ID

---

本文档为 AirLabs V2 AI 能力的完整需求说明，配合主 PRD 使用。