simonkoson
20 KiB
20 KiB
-
项目协作主控文件 (CLAUDE.md)
🔖 状态栏（每次结束 session 前必须更新这三行）
- 最后更新：Claude Fable（顾问）｜ 2026-07-07
- 当前状态一句话：期次一条龙录入子项目立项（收视分析持续运行入口，落点责编录入页）——PRD v1.0 完成、制片人三项拍板已定、寄存条已建，暂不开发。看板 L1-L4 + 仪表盘均已就绪。
- 下一个动手的人从这里开始：见下方「⏩ 交接备注」
🤖 给 AI 的工作约定（READ FIRST）
- 开工前先读完：本文件「状态栏 / 交接备注 / 关键决策」三节 + 四份宪法 +
note/下全部外迁寄存条（看板升级 / doco / CCA / 期次一条龙录入，共四份）。 - 角色定位：Claude Code 默认是顾问——出方案、审 Plan、卡壳兜底、写交接文档。写代码（Plan + Act）交给 Cline，不要架空 Cline。顾问位是为省 token：日常 CRUD、常规实现不该 Claude Code 亲自写。仅两种情况下场动手：① Cline 连续几次改都过不去的坎；② 制片人明确点名让 Claude Code 操刀。
- 给 Cline 的指令一律用代码块封装，方便复制；不要让制片人手动粘贴整份文件内容。
- 完成一段工作 → 增量更新：在「已完成」追加一条、「待办」勾掉/新增、必要时补「关键决策」，最后改「状态栏」三行。只追加/勾选，不重写、不删历史。
- 涉及发送、发布、删除、改权限、付款、跑 schema 迁移等不可逆操作前，先在对话里跟制片人确认。
- Git 红线：
git reset --hard/push --force/rebase/ 删分支删 tag —— 必须停下问制片人，永不自动执行；删整个.git永远禁止。 - 沟通：全程简体中文；制片人不懂代码，解释说人话、最小化技术语言；给明确推荐而非反复抛选项；复杂决策配可视化产物（HTML 原型 / 气泡图）辅助。回复简明，不堆中间过程。
🧩 子项目关系 / 话题边界（外迁禁区）
主干保持稳定，复杂功能拆成独立子项目（独立 chat / 独立 PRD）。以下话题已外迁，主项目里聊到要先反问「这是子项目的事还是主干的事」，是子项目的就提醒制片人切到对应 chat，不在主干默默施工。
- 看板分析升级（
寄存条_看板升级已外迁.md）：关键词——看板升级 / 双引擎象限图 / 题材热度 / AI 打标 / Prompt 1·2·3 / ground-truth / episodes 加字段 / 23 期回填 / 能力地图 / 置信度三档 / 本期诊断小结。 - Doco 文稿整理（
寄存条_doco子项目已外迁.md）：关键词——doco / 文稿整理 / 三方融合 / 视频双路拆分 / A·B 稿 / ASR / 讯飞 / DeepSeek Vision / 终版文稿 / 差异报告 / 段落对齐。⚡ 2026-06-26 已交付：22 期融合A稿成品在doco/deliverables/（按播出顺序命名），缺第01期（无A稿）。下一步：批量导入知识库（走 Phase 3 上传/embedding 链路）。 - CCA 唱词助手（
寄存条CCA唱词助手子项目已外迁.md）：关键词——cca / 唱词助手 / changci / SRT 字幕 / 拍词规则 / 编导审稿台 / 唱词校对 / ASR 转字幕 / 大洋字幕格式 / 折行规则。⚡ 2026-07-04 立项：编导 A 稿+人声音频 → ASR+AI 校对+编导审稿 → 大洋格式 SRT。先部署 lanhao 配音 2.0 测试，成熟后并入 TPS。 - 期次一条龙录入（
寄存条期次一条龙录入子项目已外迁.md，目录episode-intake/）：关键词——一条龙 / 期次录入流水线 / 流水线状态点 / 文稿回联期次 / transcript_item_id / 005 迁移 / AI 处理按钮 / 标签审核台 / draft-reviewed 流转 / 责编录入抽屉。⚡ 2026-07-07 立项：责编录入页升级为每期任务清单（收视→文稿入库→AI打标+摘要卡→制片人审核→进看板），让收视分析持续生长。PRD v1.0 就绪，暂不开发；实施时落主干、走主干纪律。已拍板：文稿口径=doco 融合A稿（doco 转常态运行）、22 期导入时回联期次、责编可触发 AI 处理。
主干仍管：Phase 0–3 主干代码、全部 backend schema/API/迁移、全部前端 React 实施、主干 bug/性能/新需求、Cline 的全部 Plan+Act。
接收子项目交付物的纪律：只接稳定版（草稿不实施）→ 跑迁移前先
pg_dump备份 → 实施完回访子项目登记状态。Schema 变更走「Cline Plan + Opus 审 + 制片人批准 Act」。跨子项目通用规则见
跨子项目协作规则.md（现有规则 1：PRD 版本管理——主项目只留最新版 PRD+回复，翻新先删再传）。docs/api_credentials_inventory.md登记各子模块外部 API 元信息（不存真 key）。
1. 项目概览（稳定）
- 项目名：TPS 工作台（Topic Planning System）— 央视《军事科技》栏目 8 人团队（制片人/责编/6 编导）内部工作台。
- 目标：把散在 Excel/Word/微信/个人电脑里的工作流收拢成一个系统——仪表盘（收视+排期）、知识库（往期文稿/军报/检索）、对话式选题策划+报题单生成、编导个人首页+热点雷达。
- 设计哲学红线（贯穿所有功能/Prompt/UI）：辅助而不替代，AI 给方向不给答案，保护编导创作主权。 任何让 AI 替编导拍板、或把编导逼向「按 AI 建议改」的设计，不做或重做。AI 输出永远是草稿，制片人审核后才发布，绝不自动发布；未审核内容对编导显示「待审核」，绝不展示 AI 草稿值。
- 范围边界（1.0 不做，别自由发挥）：TypeScript、Alembic、async SQLAlchemy、AI 模型配置 UI、文稿写作辅助系统、Karpathy LLM Wiki 形态（仅预埋接口）、移动端、多栏目复用。
2. 技术栈与运行方式（稳定，红线，禁止擅改）
- 前端：React 18 + Vite + Ant Design 5（中文 locale）+ Zustand + React Router v6，JavaScript（不用 TS）。
- 后端：FastAPI + SQLModel（同步，不用 async）；手写 SQL
backend/sql/00X_*.sql（不用 Alembic）。 - 库：PostgreSQL 16 + pgvector；向量统一 1536 维（不可改）。
- 认证：Session + Cookie（不用 JWT）；CORS 必须
allow_credentials=True+ 显式列allow_origins（不能["*"]）。 - 其他锁定：Word 用 docxtpl；甘特图用 frappe-gantt；定时任务 APScheduler。任何「换成 XX 更好」先在 Plan 讨论，绝不直接改。
- 关键目录：
backend/app/{api,core,services,models,db}、backend/sql/、frontend/src/{pages,components,services,stores}、logs/、docs/。 - 远程仓库：
http://101.42.29.217:3000/simonkoson/tps-dashboard.git（腾讯云 Gitea，用户 simonkoson）。双机开发：单位 4090D + 家里电脑，开工先git pull，收工必git push，详见docs/git_workflow.md第 7 章。 - 本地启动（开发模式，两个 PowerShell 窗口都别关；仓库根
E:\tps-dashboard）：- 后端：
cd backend→ 激活虚拟环境 →uvicorn app.main:app --reload --port 8000（文档/docs） - 前端：
cd frontend→npm run dev（端口 5173 或 5174）
- 后端：
- 环境变量/密钥：放
backend/.env，永不进 git、永不写进本文件。需要：数据库连接、SECRET_KEY、MiniMax API Key + GroupId。 - 依赖锁版本（勿乱升）：
bcrypt==4.0.1（新版与 passlib 不兼容）、itsdangerous==2.2.0、python-multipart==0.0.9；starlette不单独装。
3. 当前进度（动态，核心交接区 — 以最新快照为准）
- 已完成至：收视分析看板 L1-L4 全部完成，含 L4 AI 诊断报告（DeepSeek V4 Pro 生成、摘要块三档自适应+详情页 Markdown 渲染、22期内容摘要卡入库）。
- 正在做：无。
- 卡点/待解：无硬卡点。下一刀候选见待办。
- Schema 状态：episodes 表已通过 003（+7 AI 标签列）和 004（+content_digest JSONB）迁移。知识库两表不再改。
4. 已完成（只追加，最新在上）
- [2026-07-07] 期次一条龙录入子项目立项（只立项不开发）：① PRD v1.0 写入
episode-intake/PRD_期次一条龙录入_v1.md（每期任务清单模式、4 状态点、抽屉四区块、6 个新 API、005 迁移只加 transcript_item_id 一列、看板只用 reviewed 期次、四刀分期+七条验收）；② 制片人三项拍板：文稿口径=doco 融合A稿（CCA 是播出前工具不算终稿，doco 转常态运行）、22 期批量导入时回联期次、责编可触发 AI 处理；③ 子项目 CLAUDE.md + 寄存条建立，CCA 寄存条清单表同步更新。 - [2026-07-06] 三处 Bug 修复 + 全局宽度调优：① AI 诊断摘要块
extractSection从硬编码indexOf改为正则模糊匹配，解决 DeepSeek 返回标题格式不一致导致干条不显示的问题；② 仪表盘近 12 期柱状图加.reverse()改为从左到右按播出时间升序；③ 全局内容区宽度：定位到.app-content（AppLayout.css）的max-width是唯一有效参数（必须搭配width: 100%，否则 Ant Design flex 布局下margin: 0 auto会触发 shrink-to-fit），最终定为 1190px。 - [2026-07-03] L4 AI 诊断报告：① Prompt 4（内容摘要卡，MiMo 生成）+ Prompt 5（诊断报告，DeepSeek V4 Pro）撰写完成；② 22 期文稿摘要卡批量生成并导入 episodes.content_digest（004 迁移）；③ 后端 POST /api/analytics/diagnosis-report 端点（组装数据+调 DeepSeek+内存缓存）；④ 前端摘要块 DiagnosisSummary（左右两块、三档自适应色调、可滚动、粗体渲染）+ 详情页 DiagnosisReport（react-markdown 渲染+重新生成+免责声明）；⑤ 话题性（社交货币）三维框架设计（大众认知度/降维切口/惊奇密度）。模型选型：DeepSeek V4 Pro 胜出（vs Qwen-Max 对比测试）。
- [2026-07-03] 收视分析看板 React 前端实现（L1–L3）：① 指标卡 5 列（均值/基础达标率/摸高完成率含四档动画/期次数/年度目标）；② 走势折线图（dataZoom 滑块+确认按钮范围过滤，下游模块联动）；③ 双列对比区（左列季度+编导、右列题材饼图+条形图）；④ 双引擎象限图（题材热度×叙事结构散点，气泡编码份额/三色/钩子强度）。附带：25 期真实收视+AI 标签数据导入、侧边栏 fixed 定位、滑块滚轮冲突修复。后端 analytics API 增返 4 个 AI 标签字段。
- [2026-07-03] 看板升级子项目原型阶段收工：L2 打标流水线就绪（GT v0.6.0 / 25 期 / 三个 Prompt 可用）+ L3 HTML 原型验证通过（双引擎象限图+5 模块+视觉定稿）+ 003 迁移已执行（episodes +7 AI 标签列）。交付清单见寄存条。
- [2026-05-27] Phase 3 Task 3/3.1/3.2：知识库树形视图（按来源大类→二级维度分组、左右布局、节点联动、展开收起；修出处筛选/宽度跳动/排版）。commit
3409d48。 - [2026-05-27] Phase 3 Task 2：知识库管理后台最小版（上传/列表/删除）。
- [2026-05-27] Phase 3 Task 1：embedding 链路（入库即调 MiniMax embo-01 算 1536 维向量存 pgvector）。
- [—] Phase 2：仪表盘 + 批量导入 + 写权限收紧（yearly_targets 写权限）。
- [—] Phase 1：后端骨架（认证三件套）+ 前端骨架（登录/主布局/路由守卫）。
- [—] Phase 0：环境 + Git。
5. 待办（下一刀候选，开局前定先做哪件）
L4 AI 诊断报告→ 已完成（2026-07-03）- 下一刀三选一：① 语义搜索界面（不依赖任何材料，随时能开，是 Phase 4a 硬门槛）；② PDF 原文关联 + 大文件存储架构（需 Opus 审方案，优先级较高）；③ 界面像素级打磨+视觉规范统一。
- 期次一条龙录入开发（子项目已立项 2026-07-07，PRD 就绪在
episode-intake/，等制片人排期；四刀分期，第二刀含 doco 22 期导入回联，与既有待办「200+ md 批量录入」相互独立）。 - PDF 大文件存储：大文件不入库，单独文件仓库，DB 只存地址指针（md 正文+向量留库参与检索；pdf 仅按需调阅）。地基一次定对，避免上云返工。
- 200+ Obsidian md 批量录入（建议在 PDF 存储方案定后做；先试 10 篇验证解析/落位再全量，每篇都真调 MiniMax 耗额度）。
- 「按编导看稿」独立筛选视图（路线 A 重构时一并处理，从来源树里迁出来）。
- 操作留痕 schema（episodes 等加 created_by/updated_by/updated_at；涉 schema 须 Opus 审）。
- 界面像素级打磨（连同全栏目视觉规范统一弄，参考「色调字体倒角」图）。
6. 关键决策（跨 session 最易丢，先看这节再动手）
栏目业务红线（AI 凭通用习惯 100% 写反，死守）
- 收视颜色反直觉：只对
audience_share上色（audience_rating只显示不判定）。🔴红=份额**>当年摸高目标=优秀；🔵蓝=基础≤份额≤摸高=达标；🟢绿=份额<**基础=待提升。（与通用红警绿安相反） - yearly_targets 只增不改：按节目播出年份的目标判色（非当前年）；
year加 UNIQUE，INSERT 用ON CONFLICT DO NOTHING，永不 ON CONFLICT UPDATE。 - 编导关联用软引用+快照双字段：
editor_id+editor_name_snapshot。离职编导editor_id留 NULL、保留快照；查历史作品先按 id、回退按 name 文本匹配。禁止外键非空 + 级联删（否则离职者历史节目全成无主）。 - 报题单内容概要双段结构：默认 引子（200–300 字）+ 列举（3–5 条，每条以
**加粗关键词**起头）；纯叙述式仅编导明确指定时用。Prompt 与 docxtpl 模板同此。 - 角色枚举是拼音：
zhipianren/zebian/biandao，不增枚举、不换英文。yearly_targets：POST/PATCH 限 zhipianren+zebian（biandao 403），DELETE 仅 zhipianren，GET 三角色均可。
架构决策
- 知识库树交互层 vs 数据分组层必须解耦：分组逻辑在
useKnowledgeGrouping.js+ 后端get_grouped_items()；树组件只管展开/高亮/联动，不感知按什么字段分组。 - 二级分组维度做成可配置映射表
SECONDARY_GROUP_FIELD（manuscript→author，military_report→source_detail，其余 None），前后端同名对齐。将来转主题树（路线 A）只改这一处映射，原料已在库（tags/related_entities JSONB），大概率无需补字段重传。 - 向量 1536 维、Session 认证、不用 Alembic/TS/async —— 见技术栈节，宪法锁定。
- embedding 用 MiniMax embo-01：请求用
texts数组 +type（db/query），返回在vectors字段，需 API Key + GroupId；花 MiniMax 账号额度（与 Claude token 两笔账，一篇几厘钱）。 - PDF 等大文件不入数据库，单独文件仓库 + DB 存指针（详见待办，待立项）。
- 收视分析看板 dataZoom 模式：只用 slider（禁
type:'inside'避免滚轮冲突），拖滑块更新zoomRange但不立即过滤，用户点「应用此范围」按钮才写入appliedRange→filteredEpisodes；走势图始终用全量episodes，其余模块（指标卡/对比/象限图）用filteredEpisodes。 - 收视分析看板页面顺序：指标卡 → 走势图 → AI 诊断报告（摘要块） → 双引擎象限图 → 双列对比（左列季度+编导堆叠、右列题材跨两行）。
- L4 AI 诊断报告模型选型：DeepSeek V4 Pro（胜出，分析深度+论证结构优于 Qwen-Max）。不搞多模型共识——诊断报告是完整分析文章，逻辑连贯性比多家一致更重要。
- L4 摘要块视觉：左块固定粉红色系（
#c0584f），右块跟 tier 三档变色（绿/蓝/红）。两块均可滚动查看完整内容。 - L4 话题性框架：社交货币理论三维（大众认知度/降维切口/惊奇密度），写入摘要卡不作为独立 AI 标签字段。
- L4 prompt5 约束：① 提及期次必须用「第X期《节目名》」格式；② 话题性必须独立分析段；③ 军事装备分类须准确（枪械≠冷兵器）。
- 全局页面内容区宽度：唯一有效参数是
frontend/src/components/Layout/AppLayout.css里.app-content的max-width（当前 1190px）。必须保留width: 100%+box-sizing: border-box，不能单独用margin: 0 auto（Ant Design flex 布局下会触发 shrink-to-fit，宽度锁死无法调节）。制片人直接说"调这个参数"即可。
7. ⏩ 交接备注（换人/换账号 0 摩擦续上）
- 收视分析看板 L1-L4 全部完成。页面布局：指标卡 → 走势图 → AI 诊断报告（摘要块） → 双引擎象限图 → 双列对比（左:季度+编导, 右:题材）。
- L4 AI 诊断报告新增文件：后端
backend/app/api/analytics.py（POST 端点）；前端DiagnosisSummary.jsx（摘要块）+DiagnosisReport.jsx/.css（详情页）；Prompt 文件ai-labeling/prompts/prompt4_content_digest.md+prompt5_diagnosis_report.md；批量脚本ai-labeling/scripts/gen_content_digest.py+scripts/import_content_digests.py。 - L4 依赖：
backend/.env需配DEEPSEEK_API_KEY；前端需react-markdown包（已装）；后端需openai包（已装）。 - 004 迁移已执行：episodes 表 +content_digest JSONB 列，22 期摘要卡已导入。
- 看板前端其他文件：
frontend/src/components/Analytics/（QuarterCompare / EditorCompare / TopicCompare / QuadrantChart）；scripts/（import_real_episodes.py / fix_label_mapping.py / import_content_digests.py，一次性导入脚本）。 - schema 红线：Phase 3 不改知识库两表；
topics/topic_embeddings属 Phase 4a，勿碰；五类source_type枚举固定不增减，细分杂志/军报=改表=须 Opus 审。 logs/是受保护资产：Act 模式严禁 Cline 改；phase 日志由顾问协助生成。Task 3 三轮内容待并入phase3_log（Task 3 段）。- 避雷（Phase 3 实战教训）：
- 不信 Cline 自检——它多次虚标 ✅，一律由制片人真实点页面逐条验。
- 改树节点 key 格式属高风险，生成端与过滤端必须同步，改后必实测点击联动。
- 已验证好用的布局别为对齐整体重构（flex 改 Grid 连坏两轮）；样式微调优先。
- Cline 报告自相矛盾时，把源码发给 Opus 一眼定位胜过让 Cline 反复试错。
- 像素级打磨边际收益递减，见好就收，记 backlog 改天连视觉规范统一弄。
- 页面宽度问题：Ant Design
Layout > Content是 flex 子元素，margin: 0 auto不搭配显式width会导致元素缩到内容宽度（shrink-to-fit），改max-width数值完全无效。必须同时写width: 100%。
8. 受保护资产 / 改前必经制片人确认
严禁 Act 自动修改/删除：
.clinerules、project_plan.md、dev_plan.md、README.md、docs/**、logs/**、samples/*.xlsx、.git/、.env。如需改，切 Plan 经制片人确认。
9. 待确认 / 开放问题（需制片人拍板，AI 别自行假设）
AI 诊断报告（L4）方案细化→ 已完成（2026-07-03）- PDF 文件存哪、笔记如何关联中台内文件位置（Backlog #2 的前提）。
- 视觉风格参考图、6 名编导初始画像（各 200 字）、甘特图样本 —— 后续 Phase 需要。