feat：飞书文档补全

.gitignore

@@ -30,3 +30,7 @@ venv/
 Thumbs.db
 Desktop.ini
 .DS_Store
+
+# 下载的 CLI 工具（通过 setup_dws.py 自动下载）
+tools/
+

README.md

@@ -38,7 +38,17 @@
 ### 环境要求
 
 - Python 3.10+
-- 悟空 CLI（dws）已认证登录
+- dws CLI（钉钉官方开源工具，可从 GitHub 自动下载）
+
+### 快速安装
+
+```bash
+# 自动从 GitHub 下载 dws CLI（约 5MB）
+python scripts/setup_dws.py
+
+# 首次使用需认证（钉钉扫码登录）
+tools/dws auth
+```
 
 ### 使用方式
 
@@ -70,6 +80,14 @@ python scripts/write_report.py
 python scripts/daily_feishu_collector.py
 ```
 
+### 配置说明
+
+dws 路径自动查找顺序：
+1. 环境变量 `DWS_PATH`
+2. 项目 `tools/dws.exe`（由 `setup_dws.py` 下载）
+3. 悟空内置路径（向后兼容）
+4. 系统 PATH
+
 ## 核心发现
 
 ### 《我的花园世界》研究
@@ -95,7 +113,8 @@ python scripts/daily_feishu_collector.py
 
 ## 技术栈
 
-- **悟空 CLI（dws）**：钉钉消息拉取、文件下载
+- **dws CLI**：钉钉消息拉取、文件下载（[GitHub 开源](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli)，可从 GitHub 自动下载，无需安装悟空）
 - **Python**：数据处理、知识图谱构建
 - **BeautifulSoup**：HTML 解析
 - **Obsidian**：知识库管理
+

_pending_download.json

@@ -0,0 +1,5 @@
+{
+  "new_links": [],
+  "new_files": [],
+  "kimi_links": []
+}

fetch_tb.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""TeamBition 数据拉取入口 - 隐秘之潮项目"""
+
+import sys
+import os
+import json
+from datetime import datetime
+
+# Add project root to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from tb.tb_config import TBConfig
+from tb.teambition_api import TeambitionAPI
+from tb.task_analyzer import TaskAnalyzer
+from tb.task_manager import TaskManager
+
+
+def fetch_tb_data(send_to_dingtalk=False, mode="daily"):
+    """拉取 TeamBition 任务数据并分析"""
+    config = TBConfig()
+    api = TeambitionAPI(config)
+    analyzer = TaskAnalyzer(config)
+    task_manager = TaskManager(
+        os.path.join(os.path.dirname(__file__), "data", "tb", "task_state.json")
+    )
+
+    project_id = config.get("teambition.project_id", "unknown")
+    print(f"\n{'='*60}")
+    print(f"拉取 TeamBition 任务数据 - 项目: {project_id}")
+    print(f"{'='*60}\n")
+
+    # 1. Export tasks via TeamBition API
+    csv_content = api.fetch_tasks()
+
+    if not csv_content:
+        print("获取任务数据失败")
+        return None
+
+    # 2. Save CSV
+    output_dir = os.path.join(os.path.dirname(__file__), "data", "tb")
+    os.makedirs(output_dir, exist_ok=True)
+    csv_path = api.save_csv(csv_content, output_dir=output_dir)
+
+    if not csv_path:
+        print("保存 CSV 失败")
+        return None
+
+    # 3. Analyze
+    df = analyzer.load_csv(csv_path)
+    if df.empty:
+        print("CSV 数据为空")
+        return None
+
+    # 4. Fetch task activities for contribution tracking
+    id_col = next(
+        (c for c in ["任务 ObjectId", "_id", "id", "taskId", "任务ID"] if c in df.columns),
+        None,
+    )
+    activities = []
+    if id_col:
+        task_ids = [t for t in df[id_col].dropna().astype(str).tolist() if t and t != "nan"]
+        if task_ids:
+            print(f"获取 {len(task_ids)} 个任务的动态...")
+            try:
+                activities = api.fetch_tasks_activities(task_ids)
+            except Exception as e:
+                print(f"[Warning] 获取动态失败: {e}")
+
+    # 5. Generate summary
+    summary = analyzer.analyze_tasks(df, activities)
+    summary_path = os.path.join(output_dir, "summary.json")
+    analyzer.save_summary(summary)
+
+    # 6. Detect changes
+    current_tasks = analyzer.get_task_dict(df)
+    old_state = task_manager.load_state()
+    prev_tasks = old_state.get("tasks", {})
+    changes = task_manager.detect_changes(prev_tasks, current_tasks)
+
+    if changes:
+        print("\n[变动检测]")
+        for c in changes:
+            print(f"  {c}")
+    else:
+        print("\n[变动检测] 无变动")
+
+    task_manager.save_state(current_tasks)
+
+    # 7. Optionally send to DingTalk
+    if send_to_dingtalk:
+        from tb.dingtalk_sender import DingTalkSender
+
+        dingtalk_config = config.get("dingtalk", {})
+        if dingtalk_config.get("enabled"):
+            robots = dingtalk_config.get("robots", {})
+            user_roles = config.get("user_roles", {})
+            user_mobiles = config.get("user_mobiles", {})
+            switches = dingtalk_config.get("switches", {})
+
+            temp_sender = DingTalkSender("")
+            report, at_mobiles = temp_sender.format_task_report(
+                summary, user_roles, user_mobiles,
+                dashboard_url=config.get("dashboard_url"),
+                switches=switches,
+            )
+
+            if switches.get("daily_diff", True):
+                report = temp_sender.format_diff_report(changes, report)
+
+            for name, bot_cfg in robots.items():
+                webhook = bot_cfg.get("webhook")
+                secret = bot_cfg.get("secret")
+                if webhook:
+                    sender = DingTalkSender(webhook)
+                    sender.send_markdown("Teambition 任务日报", report, secret=secret, at_mobiles=at_mobiles)
+                    print(f"已发送到钉钉机器人: {name}")
+
+    # 8. Cleanup CSV
+    if csv_path and os.path.exists(csv_path):
+        os.remove(csv_path)
+
+    print(f"\n完成! 共 {summary.get('total_tasks', 0)} 个任务")
+    return summary
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="TeamBition 数据拉取")
+    parser.add_argument("--dingtalk", action="store_true", help="发送到钉钉群")
+    parser.add_argument("--mode", default="daily", choices=["daily", "interval"])
+    args = parser.parse_args()
+
+    fetch_tb_data(send_to_dingtalk=args.dingtalk, mode=args.mode)

output/downloaded-files/html-md/数据口径入门教程.md

@@ -0,0 +1,170 @@
+# 数据口径入门教程
+> 目的：让你**看懂手里这些数到底是什么意思**，而不是看结论。
+> 全文用 `data/` 里真实存在的列名和真实数字举例，所有数字均经 Python 核验。
+> 文件日期：2026-06-05
+
+---
+
+## 0. 先建立三个最基本的概念（看懂一切的前提）
+
+读这些表之前，脑子里先装三把"尺子"。后面所有指标都是这三把尺子的组合。
+
+### ① 漏斗：钱 → 人 → 留 → 付
+一个游戏的生命，就是一条漏斗，每一层都有专门的数衡量它：
+
+```
+花钱买量(消耗) → 买来多少人(新增/DNU) → 人留下多少(留存) → 留下的人付多少钱(付费/流水)
+   消耗            DNU、激活            次留/7留/30留         内购、广告、付费留存
+```
+
+**关键认知**：前两层（消耗、买人）是"前端"，市面上谁都能买到、人人都在卷；后两层（留存、付费）是"后端"，是真正决定生死的地方，也是好数据稀缺的地方。你手里这批数据值钱，就值在它有**后端的真实留存**。
+
+### ② 留存：「第N天还回来的人 ÷ 当初进来的人」
+- 今天来了 100 个新人。
+- 明天（第2天）还有 8 个人回来打开 → **次留 = 8%**
+- 第7天还有 2 个 → **7留 = 2%**
+- 第30天还有不到 1 个 → **30留 < 1%**
+
+留存是**百分比**，且**一定随天数递减**（次留 > 7留 > 30留）。它衡量"这游戏黏不黏人"。
+
+> 真实基线（你的留存表 1246 款有效产品）：
+> **免费次留中位 8.2% → 7留 2.3% → 30留 0.66%**。
+> 也就是说，一个典型抖小产品，**买来100个人，一个月后只剩不到1个还在玩**。这就是这个市场的残酷底色。
+
+### ③ 免费 vs 付费：两种人，必须分开看
+同一个指标（比如30留），几乎每张表都拆成**两列**：
+- **「新增XX留」= 免费口径**：所有新进来的人（绝大多数不花钱）的留存。衡量**大盘黏性 / 能不能留住普通人**。
+- **「付费新增XX留」= 付费口径**：只看那些付过钱的人的留存。花了钱的人当然更愿意回来，所以**付费留存永远远高于免费留存**。
+
+**这是新手最容易搞混、也最致命的一点**：看到"30留 6%"先问一句——**是免费的还是付费的？** 免费30留 6% 是百里挑一的神作，付费30留 6% 只是市场中位（见下表）。
+
+---
+
+## 1. 你手里有哪几张表，分别管漏斗的哪一层
+
+| 文件 | 管漏斗哪层 | 一句话 |
+|---|---|---|
+| `2026Q2抖小TOP付留留存产品.xlsx` | **留存层（核心资产）** | 1707款产品的免费/付费 次→180天 全留存曲线 |
+| `抖小 2025 全年 单价Top700 数据.xlsx` | **消耗+买人+变现层** | 707款的消耗、买来多少人、CPA、内购/广告流水 |
+| `抖小 Top800产品DAU-次_7留.xlsx` | **规模层** | 800款的DAU（日活），外加次留/7留 |
+| `Q4.xlsx` / `to nan2.xlsx` | **时间序列（微信）** | 26-27款微信产品 × 6个月的投放后台流水，能算"放量后会怎样" |
+| `抖小 2025 全半年微小 TOP产品数据.xlsx` | 补充 | 上半年微信小游戏Top |
+| `IAA中度小游戏排名数据20241212.xlsx` | 补充 | 纯广告变现(IAA)中度游戏排名 |
+
+**入门只需吃透前三张**，后面三张是进阶/特例。
+
+---
+
+## 2. 逐列拆解：每个列名到底是什么意思
+
+### 表A — 留存表 `2026Q2抖小TOP付留留存产品.xlsx`（最重要）
+
+| 列名 | 口径 | 怎么读 |
+|---|---|---|
+| `小游戏名称` | — | 产品名 |
+| `DAU` | 规模 | 日活跃用户数，越大盘子越大 |
+| `新增次留` | **免费**·第2天 | 普通新人第二天回来比例。基线≈8% |
+| `新增7留` | **免费**·第7天 | 基线≈2.3% |
+| `新增30留` | **免费**·第30天 | **最关键的一列**。基线仅 **0.66%**，超过2%就是金矿 |
+| `新增60/90/120/180留` | **免费**·更长期 | 看超长期黏性，多数产品到这里已≈0 |
+| `付费新增次留` | **付费**·第2天 | 付过钱的人的次留，远高于免费 |
+| `付费新增30留` | **付费**·第30天 | 基线≈5.35%（是免费30留的8倍多） |
+| `付费新增60~180留` | **付费**·更长期 | 鲸鱼用户的长期黏性 |
+
+> ⚠️ 列名里**带"付费"二字 = 付费口径，不带 = 免费口径**。这是唯一区分方式，记死它。
+
+### 表B — Top700 `抖小 2025 全年 单价Top700 数据.xlsx`（注意表头在第2行）
+
+| 列名 | 口径 | 怎么读 |
+|---|---|---|
+| `小游戏名称` | — | 产品名 |
+| `新一级品类` / `新二级品类` / `玩法运营品类次级分类` | 分类 | 三级越来越细。如：模拟策略 > 角色扮演 > 卡牌RPG |
+| `买量消耗(元)` | 消耗 | 全年砸了多少钱买量。台球王者≈1647万 |
+| `DNU（年新增去重）` | 买人 | 全年买来多少**去重**新用户。台球王者≈2974万 |
+| `年总CPA` | 单价 | = 消耗 ÷ 买人 = **买一个用户多少钱**。台球王者≈0.55元；全市场中位 **6.67元** |
+| `cpa的日均` | 单价 | CPA的日度均值（部分缺失，官方说算崩了） |
+| `当日内购流水，元` | 变现·IAP | 用户充值的钱（内部购买） |
+| `当日广告流水，元` | 变现·IAA | 看广告产生的钱 |
+
+> ⚠️ **流水列是带"万/亿"后缀的文本**（如 `"1,686万"`），不是纯数字。用 Python 读时要先把"万"=×10000、"亿"=×1e8 转换，否则会变成 nan。
+
+> **CPA 直觉**：CPA 越低 = 买量越便宜。台球王者 0.55 元（休闲，人人能玩，便宜）vs SLG动辄一二十元（盘子窄，贵）。**低CPA = 便宜的扩量壳**，这是好题材的硬指标之一。
+
+### 表C — DAU表 `抖小 Top800产品DAU-次_7留.xlsx`
+
+| 列名 | 口径 | 怎么读 |
+|---|---|---|
+| `小游戏名称` | — | 产品名 |
+| `dau` | 规模 | 日活。注意是**小写dau**，且是带小数的估算值 |
+| `新增次留` / `新增7留` | **免费** | 同留存表口径，用于和留存表交叉验证 |
+| `取数日期：10.1-3.26` | 元信息 | 这列基本是空的，只是标注取数区间 |
+| `2-7保留率` | 衍生 | 第2天到第7天之间的留存保持率（7留÷次留的近似），看"早期流失斜率" |
+
+---
+
+## 3. 四个必须会算的衍生指标（这才是分析的入口）
+
+光看单列没用，真正的洞察来自**列与列相除**。记住这四个：
+
+### ① CPA = 消耗 ÷ DNU
+**买一个用户多少钱**。已在表B直接给出。低=便宜扩量，高=盘子窄。
+
+### ② 裂口 = 付费30留 ÷ 免费30留（"X光机"）
+**判断高留存是真是假**的核心工具。
+- 裂口小（≤4倍）= **宽盘**：普通人和付费人都留得住，健康。
+- 裂口大（>8倍）= **鲸鱼窄盘**：只有少数大R留着，普通人全跑了，虚胖。
+- 全市场裂口中位 **7.3倍**。
+> 例：狱国争霸 免费30留7.69% / 付费30留31.71% → 裂口仅 **4.1倍** = 罕见的真·宽盘。
+> 反例：很多4X产品付费30留10%但免费30留0.4% → 裂口25倍 = 鲸鱼窄盘，免费量全留不住。
+
+### ③ 内购占比 = 内购流水 ÷ (内购+广告流水)
+**这游戏靠充值还是靠看广告赚钱**。高内购占比=深度付费品类（如模拟经营86%），低=纯广告变现的休闲。
+
+### ④ DAU × 免费30留 四象限
+把"盘子大不大"和"留不留人"交叉，得到四类产品：
+
+```
+              免费30留 高              免费30留 低
+  DAU 高    ① 头部赢家(又大又黏)    ③ 烧钱黑洞(大但留不住)
+  DAU 低    ② 金矿池(小而极黏)      ④ 弱/将死
+```
+- **②金矿池**是最值得研究的——小众但黏性极强，往往藏着可复用的留存机制。
+
+---
+
+## 4. 看一个数时，必须连环追问的 4 句话
+
+拿到任何一个留存/CPA数字，按顺序问自己：
+
+1. **这是免费口径还是付费口径？**（列名带不带"付费"）— 不分清，结论全错。
+2. **和基线比是高是低？**（免费30留比0.66%、CPA比6.67元、裂口比7.3倍）— 没有基线就没有"高低"。
+3. **裂口多大？**（付费30留÷免费30留）— 防止把鲸鱼窄盘误判成神作。
+4. **这是个例还是类目普遍现象？**（同玩法分类里其他产品也这样吗）— 防止把孤例当规律。
+   > 真实教训：狱国免费30留7.69%，但同为"策略-SLG"的另外16款中位仅0.76%、最高1.59%。**狱国是孤例，不是"SLG都这样"。** 不追问第4句，就会得出"做SLG就能留人"的错误结论。
+
+---
+
+## 5. 三个新手最容易踩的坑（已在本项目踩过）
+
+| 坑 | 后果 | 怎么避 |
+|---|---|---|
+| 免费/付费留存混着比 | 把市场中位当成神作 | 一次比较只用一把尺子；扩量用免费、变现深度用付费 |
+| 看绝对值不看裂口 | 把鲸鱼窄盘当宽盘 | 任何高留存先算裂口 |
+| 单窗口留存就下结论 | ~32%假阳性 | 至少用两个时间窗口/两张表交叉验证 |
+| 流水列直接当数字 | 全变nan | 先把"万/亿"后缀转成数值 |
+
+---
+
+## 6. 一句话总结这套口径的世界观
+
+> **前端（消耗、CPA、吸量）人人能买、人人在卷；后端（免费留存、裂口）稀缺、决定生死。**
+> 你手里这批数据的价值，全在于它给了你**真实的后端留存**——这正是市面上花钱也买不到的那一半（第三方平台如DataEye只能给买量推导的前端）。
+> 所以读数的功夫，要花在第3、4节那些"相除"和"追问"上，而不是盯着某一列的绝对值。
+
+---
+
+## 附：快速自测（看懂了就能答）
+1. 某产品"30留 9%"，你第一句该问什么？ → *是免费还是付费？*
+2. 免费30留 0.4%、付费30留 12%，裂口多少？健康吗？ → *30倍，鲸鱼窄盘，免费量留不住，不健康。*
+3. CPA 0.5元 和 CPA 20元，哪个是"便宜扩量壳"？ → *0.5元。*
+4. 一个产品免费30留3%，能直接说"它所在品类都很黏"吗？ → *不能，得看同类其他产品（追问第4句）。*