docs: map existing codebase

2026-03-13 14:55:43 +08:00
parent 1d7957aab4
commit a8669ec0a3
5 changed files with 790 additions and 0 deletions
@@ -0,0 +1,162 @@
+# External Integrations
+
+**Analysis Date:** 2026-03-13
+
+## APIs & External Services
+
+**AI Providers:**
+- **智谱 AI (Zhipu)** - 主要 AI 分析服务
+  - SDK: `requests` HTTP 客户端
+  - Auth: `AI_API_KEY` 环境变量
+  - Base URL: `https://open.bigmodel.cn/api/paas/v4`
+  - 模型: `glm-5`, `glm-4`
+
+- **MiniMax** - AI 备选服务
+  - SDK: `requests` HTTP 客户端
+  - Auth: `AI_API_KEY` 环境变量
+  - Base URL: `https://api.minimaxi.com/anthropic/v1/messages`
+
+- **OpenAI** - AI 备选服务
+  - SDK: `requests` HTTP 客户端
+  - Auth: `AI_API_KEY` 环境变量
+
+- **阿里云通义千问 (Alibaba/Qwen)** - AI 备选服务
+  - SDK: `requests` HTTP 客户端
+  - Auth: `AI_API_KEY` 环境变量
+
+**视频平台 API:**
+- **Bilibili** - 视频/专栏元数据提取
+  - SDK: `httpx`, `playwright`
+  - Auth: `BILIBILI_COOKIE` 环境变量 (SESSDATA, bili_jct)
+  - 文件: `kb-bilibili-metadata/bilibili_extractor.py`
+
+- **知乎** - 问答/专栏/视频内容
+  - SDK: `yt-dlp`, `playwright`
+  - Auth: `ZHIHU_COOKIE` 环境变量
+  - 文件: `kb-zhihu-metadata/zhihu_metadata.py`, `kb-zhihu-content/zhihu_content.py`
+
+- **YouTube** - 视频内容（通过链接解析）
+  - SDK: `yt-dlp`
+  - 文件: `kb-link-parser/link-parser.py`
+
+- **小红书** - 笔记内容
+  - 短链接: `xhslink.com`
+  - 文件: `kb-link-parser/link-parser.py`
+
+## Data Storage
+
+**Databases:**
+- 无数据库 - 所有数据以文件形式存储
+
+**File Storage:**
+- 本地文件系统
+  - 工作目录: `~/work/knowledge-base/`
+  - 结构:
+    - `pending/` - 待处理链接
+    - `metadata/` - 元数据 JSON
+    - `content/downloads/` - 下载的媒体文件
+    - `analyzed/` - AI 分析报告
+
+**归档存储:**
+- 路径: `~/work/zq/30.资源/AI分析/`
+- 按日期组织: `YYYY-MM-DD/`
+
+**Caching:**
+- 模型缓存: `~/.cache/modelscope/hub/` - FunASR 模型
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Cookie-based 认证
+  - Bilibili: `BILIBILI_COOKIE`
+  - 知乎: `ZHIHU_COOKIE`
+
+**AI API 认证:**
+- API Key 认证
+  - `AI_API_KEY` - AI 服务密钥
+  - `HF_TOKEN` - HuggingFace Token (说话者分离)
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- 无外部监控服务
+
+**Logs:**
+- 控制台输出 - 所有技能通过 `print()` 输出日志
+- 建议使用 `python3 -u` 禁用缓冲以实时查看输出
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Self-hosted (本地服务器)
+- 技能部署位置: `/home/starmen1265/.openclaw/skills/`
+
+**CI Pipeline:**
+- Gitea Actions (self-hosted runner)
+  - 配置文件: `.gitea/workflows/deploy.yml`
+  - 触发: push to main
+  - 使用 `rsync` 同步技能目录
+
+## Environment Configuration
+
+**必须的环境变量:**
+```bash
+AI_API_KEY="your-api-key"       # AI 服务密钥
+AI_PROVIDER="zhipu"             # 或 openai, minimax, alibaba
+AI_MODEL="glm-5"                # 模型名称
+AI_BASE_URL="https://..."       # API 地址
+```
+
+**可选的环境变量:**
+```bash
+BILIBILI_COOKIE="SESSDATA=xxx; bili_jct=xxx"  # B站登录态
+ZHIHU_COOKIE="..."                            # 知乎登录态
+HF_TOKEN="hf_xxx"                             # HuggingFace Token
+KB_GIT_USER="Your Name"                       # Git 提交用户名
+KB_GIT_EMAIL="your@email.com"                 # Git 提交邮箱
+KB_ARCHIVE_PATH="~/work/zq/30.资源/AI分析"      # 归档目录
+KB_GIT_ROOT="~/work/zq"                       # Git 仓库根目录
+KB_BASE_PATH="~/work/knowledge-base"          # 知识库基础路径
+WHISPER_CPP_PATH="~/whisper.cpp"              # Whisper.cpp 路径
+```
+
+**配置文件位置:**
+- `~/.kb_env` - 知识库专用配置（推荐）
+- `kb-workflow/.env.example` - 示例配置
+
+**Secrets location:**
+- 环境变量（明文存储在 `~/.kb_env`）
+- 无加密/secrets 管理
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- 无 Webhook 端点
+
+**Outgoing:**
+- 无主动 Webhook 调用
+
+## External Tools
+
+**音视频处理:**
+- `ffmpeg` / `ffprobe` - 音视频格式转换和元数据提取
+- `yt-dlp` - 视频下载（知乎视频）
+
+**语音识别:**
+- `whisper.cpp` - 本地 Whisper 推理
+- `funasr` / `modelscope` - 阿里 FunASR
+
+**浏览器自动化:**
+- `playwright` - 无头浏览器
+- `undetected_playwright` - 反检测浏览器
+
+**OCR:**
+- `tesseract` - OCR 引擎
+- `easyocr` - 深度学习 OCR
+
+**会话管理:**
+- `tmux` - 终端会话管理（gsd-openclaw）
+
+---
+
+*Integration audit: 2026-03-13*