CLAUDE.md · diff
git:20260812.e1e0545 to git:20261102.a11d179
76 added, 86 removed. Audit A to A.
# Project Agent Guide / 项目 Agent 指南
- This file is the project-specific source of truth for AI agents working in this repository.
-
- 这是本仓库的项目级 AI 协作规则源文件。
-
- ## 项目定位
+ 本文件是仓库内 AI 协作规则的事实来源，面向 Claude Code、Codex 等 Agent。
- `xxsj-fs-ob` 是一套运行在用户自己电脑上的信息收集系统，同时提供 Codex Skill 集成。
+ ## 范围
- 当前正式实现：抖音视频采集 → 飞书多维表格任务队列 → 本地 Worker → Qwen-ASR → Faster-Whisper Large-v3 fallback → DeepSeek 摘要/分类 → Markdown → Obsidian → Base 回写。
+ - 项目根目录：本仓库根目录。
+ - 运行时：Windows + TypeScript/Node.js + Playwright + Vitest。
+ - 主命令：`tsx scripts/run-auto-worker.ts`（轮询飞书多维表格队列）。
+ - 检查命令：`pnpm typecheck`、`pnpm test`。
+ - 用户文档：`README.md`、`docs/`。
- ## Scope / 范围
+ ## 安全
- - Project root: this repository root.
- - Runtime: TypeScript Node.js CLI, Vitest, pnpm.
- - Checks: `pnpm test` and `pnpm typecheck`.
- - 主命令：Worker 通过 `scripts/start-worker.ps1` 或 `start-xxsj-fs-ob-worker.cmd` 启动。
+ - 不要打印或提交 `.env`、飞书 Token、LLM API Key、浏览器 Cookie、Playwright 用户目录内容。
+ - `.env`、`.browser/`、`data/`、`logs/`、`cookies/` 是本地运行状态，必须留在 git 外。
+ - `.env.example` 只能放占位符。
+ - 除非用户明确要求本地调试，不要在日志里输出完整正文。
- ## 当前正式支持 (v1.0.1)
+ ## 飞书字段契约（当前 16 个字段）
- - 抖音视频链接采集和处理
- - 飞书多维表格任务队列
- - Qwen-ASR 主转写
- - Faster-Whisper Large-v3 备用转写
- - DeepSeek 摘要、分类和值得保存的信息
- - Obsidian Markdown 原子写入
- - 去重、幂等、断点恢复、锁和冲突保护
- - bot identity 无人值守 Base 读写
+ Worker 只写入以下 4 个字段：
- ## 尚未正式实现
+ ```text
+ 处理状态
+ 知识库路径
+ 处理时间
+ 最近错误
+ ```
- - 公众号
- - B站
- - YouTube
- - 推特 / X
- - 小红书
+ 其余字段由上游（Hermes/人工）维护，Worker 只读：
- 目录中存在不等于功能已实现。遇到未支持平台，Worker 会明确拒绝。
+ ```text
+ 收录日期
+ 作品发布日期
+ 原文链接
+ 标题
+ 备注
+ 概述
+ 二级标签
+ 作者
+ 去重ID
+ 来源平台
+ 三级标签
+ 一级标签
+ ```
- ## 平台 adapter 扩展原则
+ - 字段白名单在 `src/worker/autoWorker.ts` 的 `BASE_FIELD_NAMES`；表结构变化时必须同步。
+ - `处理状态` 取值：`pending` / `processing` / `draft_ready` / `done` / `failed`。
+ - `来源平台` 仅支持：`抖音`、`B站`、`微信公众号`（别名 `公众号`）、`X`（别名 `Twitter`/`推特`）、`YouTube`（别名 `Youtube`/`油管`）。留空按 `抖音` 处理。
+ - 重试次数保存在本地 `data/tasks/<recordId>/stage.json` 的 `retryCount`，不写飞书。
- 当需要添加新平台时：
- 1. 创建新平台目录（如 `src/platform/bilibili/`）
- 2. 实现平台 adapter 接口
- 3. 在 Worker 中注册新平台
- 4. 仅通过配置启用，不影响已有平台处理链
+ ## 平台能力
- ## 目录结构
+ | 平台 | 能力 |
+ |---|---|
+ | 抖音 | 视频、图文（`/note/`）；文章（`/article/`）代码支持但无真实样本；不支持 v.douyin.com 短链 |
+ | B站 | BV/av 链接、b23.tv 短链、视频下载 + ASR |
+ | 微信公众号 | `/s/` 参数型与路径型文章；图片归档 |
+ | X（推特） | status 链接、t.co 短链、纯数字 ID；图片、视频 |
+ | YouTube | `watch?v=`、`youtu.be`；官方字幕优先，无字幕转音频 ASR |
- ```
- xxsj-fs-ob/
- ├── src/ # TypeScript 源代码
- │ ├── analysis/ # 内容分析（DeepSeek）
- │ ├── asr/ # ASR 转写编排（Qwen + Whisper fallback）
- │ ├── base/ # 飞书多维表格适配器
- │ ├── media/ # 抖音媒体捕获
- │ ├── obsidian/ # Obsidian 写入
- │ ├── pipeline/ # 处理管道
- │ ├── summary/ # DeepSeek 摘要与分类
- │ ├── video/ # 视频深度处理
- │ ├── worker/ # 自动 Worker
- │ └── config.ts # 配置管理
- ├── scripts/ # PowerShell 和 Python 脚本
- ├── tests/ # Vitest 测试 (27 文件, 251 tests)
- ├── docs/ # 文档
- ├── config/ # 配置模板
- ├── references/ # 架构参考
- └── SKILL.md # Codex Skill 定义
- ```
+ 小红书未实现。
- ## Safety / 安全
+ ## 转写
- - 不要打印或提交 `.env`、飞书 token、LLM API Key、浏览器 Cookie、Playwright 用户目录内容。
- - `.env`、`.browser/`、`data/`、`logs/` 是本地运行状态，必须留在 git 外。
- - `.env.example` 只能保留空白密钥占位。
- - 除非用户明确要求本地调试输出，不要在日志里输出完整私信正文。
+ - 主编排：`src/asr/asrOrchestrator.ts`。
+ - 优先 Qwen-ASR（`DASHSCOPE_API_KEY`），失败回退本地 faster-whisper large-v3。
+ - 本地脚本：`scripts/transcribe-faster-whisper.py`。
+ - 相关配置：`ASR_MODE`、`WHISPER_MODEL`、`WHISPER_DEVICE`、`WHISPER_COMPUTE_TYPE`、`TRANSCRIBE_PYTHON_PATH`。
+ - 无 GPU 时把 `WHISPER_DEVICE=cpu`、`WHISPER_COMPUTE_TYPE=int8`（未实测，需自行验证）。
- ## 测试命令
+ ## Obsidian
- ```bash
- pnpm test # 27 测试文件, 251 tests
- pnpm test:watch # watch 模式
- pnpm typecheck # TypeScript 类型检查
- ```
+ - vault 路径来自 `.env` 的 `OBSIDIAN_VAULT_PATH`，未配置时 Worker 启动即退出。
+ - 收件箱目录来自 `OBSIDIAN_INBOX_DIR`，默认 `000-Inbox\001-信息中心`。
+ - 平台子目录由 `OBSIDIAN_PLATFORM_DIR_MAP` 映射。
+ - 原子写入，SHA-256 相同则跳过；用户修改过内容则不覆盖。
+ - 图片归档到 `<平台>/_assets/<sha256(dedupeKey) 前 16 位>/`。
- ## 安全规则
+ ## 抖音采集规则
- - 不读取真实 `.env`
- - 不使用真实 Base 数据作 fixture
- - 测试使用合成数据
- - 不调用真实飞书、Qwen、DeepSeek、Whisper
- - 不下载大型模型
- - 不写入真实 Obsidian
+ - 登录态由 `scripts/manual-login.ts` 保存到 `BROWSER_USER_DATA_DIR`（默认 `.browser/douyin`）。
+ - 媒体捕获在 `src/media/douyinMediaCapture.ts`；不得打印签名媒体直链、请求头、Cookie。
+ - 必须使用精确匹配的详情响应，失败时直接报错，不用页面媒体兜底。
+ - 限流：`src/media/douyinRateLimiter.ts`，120 次/小时，超限延后到下一轮。
+ - 下载后必须校验存在音轨。
- ## 当前抖音正式支持范围
+ ## 代理
- - 飞书机器人接收抖音链接 → Base pending
- - Worker 领任务：解析作品 ID → 下载视频 → Qwen-ASR 转写
- - ASR 失败自动切 Faster-Whisper Large-v3
- - DeepSeek 生成摘要、分类、值得保存的信息
- - 生成 Markdown → 写入 Obsidian
- - Base 状态回写 done
- - 去重（Record ID + 平台作品 ID）
- - 幂等（已下载不重复下载、已转写不重复转写）
- - 断点恢复
- - Obsidian 原子写入（冲突保护、用户修改检测）
+ - 启动脚本依次读取：进程环境 → `.env` 的 `XXSJ_HTTPS_PROXY`/`XXSJ_HTTP_PROXY` → `.env` 的 `HTTPS_PROXY`/`HTTP_PROXY`。
+ - 都为空表示不设代理。
+ - 抖音、公众号、B站、飞书一般不需要代理；X、YouTube 通常需要。
- ## 公众号是下一优先级
+ ## 验证
- 公众号内容采集与 Markdown 化是 v1.x 路线的下一个平台目标。
+ ```powershell
+ pnpm typecheck
+ pnpm test
+ .\scripts\doctor.ps1
+ ```