TV Program Preview - 电视节目预告

核心用法

TV Program Preview 是一款调用极速数据（JisuAPI）接口的电视节目预告查询技能，提供两大核心功能：

1. 频道列表查询（channel）：获取所有可用电视频道的 ID、名称及层级信息
2. 节目单查询（query）：根据频道 ID 和指定日期拉取完整节目表，含节目名称与开始时间

使用流程为：先调用 channel 获取目标频道 tvid（如 CCTV-3 对应 435、湖南卫视对应特定 ID），再使用 query 查询具体日期的节目安排。支持自然语言场景如「今晚 CCTV-3 有什么节目」「湖南卫视明天晚间综艺」等。

显著优点

• 数据权威：接入国内专业 API 数据平台极速数据，覆盖央视、卫视及地方频道，节目信息更新及时
• 查询灵活：支持任意日期（格式 YYYY-MM-DD）的精确查询，可横向对比多日节目安排
• 响应结构清晰：返回 JSON 包含频道名称、日期、节目列表（名称+开始时间），便于二次解析与展示
• 集成友好：Python 脚本化调用，易于嵌入对话系统或自动化工作流

潜在缺点与局限性

• 依赖外部 API：需注册极速数据账号并申请「电视节目预告 API」权限，获取 AppKey 后方可使用
• 免费额度受限：极速数据采用会员制，免费套餐存在调用次数限制，高频使用需购买套餐
• 日期范围未明确：文档示例使用 2015 年历史日期，实际可查询日期范围需以 API 返回为准
• 无节目详情：仅返回节目名称和开始时间，不包含节目简介、时长、演员/嘉宾等元信息
• 地区覆盖不均：部分地方台或数字频道可能缺失，以 channel 返回列表为准

适合人群

• 需要快速查询电视节目的普通用户（替代传统 TV Guide）
• 构建智能音箱、客服机器人的开发者（自然语言转节目查询）
• 媒体行业从业者（排期比对、竞品分析）
• 家庭场景自动化（如「今晚 8 点提醒我看综艺」联动设置）

常规风险

• API 密钥泄露风险：JISU_API_KEY 需配置为环境变量，硬编码或日志泄露可能导致账户被盗用
• 服务稳定性依赖：极速数据平台维护、接口停用或网络波动将直接影响功能可用性
• 数据时效性风险：节目临时调整（如突发新闻插播）可能未及时同步至 API
• 错误码需妥善处理：频道 ID 错误（202）、无信息（203）等需前端友好提示，避免 raw error 暴露

核心用法

本技能是一款基于极速数据（JisuAPI）平台的电视节目预告查询工具，通过简洁的命令行接口实现两大核心功能：频道列表获取与节目单查询。用户首先调用 channel 指令获取全量频道信息（含频道ID、名称、层级关系），再通过 query 指令指定频道ID与日期，即可拉取该频道当日的完整节目排期。技能设计遵循"先查ID、再查节目"的两步逻辑，既保证查询精准度，又避免频道名称歧义带来的错误。

显著优点

数据来源权威可靠：极速数据是国内知名的API数据服务平台，覆盖生活常用、交通出行、工具万能等数十类数据接口，服务稳定性与数据准确性经市场验证。API采用HTTPS加密传输，符合现代数据安全标准。

功能场景贴合日常：精准解决"今晚央视综艺有什么节目""湖南卫视明天晚间档安排"等高频生活需求，特别适合家庭用户规划观影时间、粉丝追踪特定节目播出节点。

安全实践规范：代码层面实现零硬编码凭据，API密钥通过环境变量 JISU_API_KEY 安全注入；依赖审计显示仅使用Python标准库与requests，无已知CVE漏洞；输入参数经过非空校验，防御基础注入风险。

部署门槛低：仅需Python 3环境即可运行，无复杂依赖安装流程，个人开发者与企业团队均可快速集成。

潜在缺点与局限性

强依赖外部服务可用性：功能完全耦合于JisuAPI服务状态，若平台维护、API密钥过期或配额耗尽（错误码101-108），技能将直接失效。无本地缓存机制导致频道列表也需重复请求，增加API调用成本。

输入验证委托服务端：当前实现仅做基础非空检查，日期格式合法性、频道ID有效性等校验后置至API层，无效输入可能返回生硬的错误码（如201"频道为空"、202"频道错误"），用户体验有待优化。

数据时效性边界：节目单数据由第三方平台提供更新，极端情况下可能存在与电视台实际排播的延迟或偏差，重要节目建议二次确认。

适合的目标群体

• 家庭日常用户：需要快速了解央视、卫视等主流频道节目安排，规划晚间观影时间
• 综艺/剧集追踪者：关注特定频道（如湖南卫视、CCTV-3综艺）的栏目更新与重播节点
• 智能家居开发者：可将技能集成至语音助手场景，实现"查节目-换频道"联动体验
• 老年用户辅助：通过Agent自然语言交互降低传统EPG（电子节目指南）的操作门槛

使用风险说明

API配额与成本风险：JisuAPI采用商业授权模式，免费额度有限，高频调用可能触发请求次数限制（错误码104）或产生费用，建议关注配额监控与套餐升级。

隐私与数据流转：API密钥及查询参数（频道ID、日期）需传输至第三方服务器，虽经HTTPS加密，但用户需知悉数据离境事实；建议定期轮换密钥并限制IP访问范围。

服务连续性风险：无内置降级方案或备用数据源，建议关键场景预留容错逻辑（如错误码107"接口维护中"时的友好提示）。