Yandex Direct 广告审计与管理技能（API v5 / v501），版本 2.0.1。提供 Yandex Direct 全周期管理：账户审计、广告系列增删改查、关键词管理、报表、优化和预算分析。
【命令与用途】
- /direct audit：全账户审计（所有广告系列），评分 0-100。运行 yd-audit.sh 收集全部对象（按 10 个广告系列分块、分页）及最近 30 天基于各系列优先目标的 4 份报表，再按 references/yandex-audit.md 的 55 项检查与 references/scoring-system.md 评分，输出俄语报告：等级（A–F）、发现、快速见效项、按优先级的行动计划。
- /direct campaigns：列出广告系列类型、状态、搜索/网络策略、每周限额（WeeklySpendLimit/1 000 000）、目标；通过 yd-report.sh 获取分网络消费与转化。
- /direct create：创建统一效果广告系列（UnifiedCampaign，v501），包括图片上传获取哈希、广告系列设置、广告组与地区、关键词与自动定向、附加链接与说明扩展、组合广告（ResponsiveAd：标题、文案、Href、图片哈希等），最后由用户审阅后再提交审核。
- /direct keywords：按广告组或不超过 10 个广告系列查询关键词，含投放状态与自动定向设置；支持添加、暂停、恢复、删除、出价（手动策略下 keywordbids.set）及自动定向类别管理；效果通过 yd-report.sh criteria 获取。
- /direct report：按预设（account、campaign、adgroup、ad、criteria、search_query、placement、custom）生成报表；须传入 --goals 优先目标，统一系列加 --by-network 区分搜索与 YAN；支持日期区间与 LAST_7_DAYS 等周期，离线报表自动轮询。
- /direct optimize：基于 30 天报表找高消耗无转化条件与搜索词、需排除的 YAN 投放位置、同一系列内搜索与网络 CPA 差距、RARELY_SERVED 广告组、被拒广告元素；先与账户自身中位数比较再对照基准，按影响排序给出建议，执行 3× Kill Rule（CPA 超过目标 3 倍即标记暂停），学习期内不改策略、限额类型或付费模式。
- /direct budget：读取每周限额（或按档期 CustomPeriodBudget），按日消费计算运行率与每周预测；标记周内提前撞限额、消费低于限额 70%、按转化付费预算低于 10×CPA、周预算低于 300 ₽ 等情况；自 2026-07-06 起 CPC 系列未花完预算最多 30% 可结转。
- /direct negative：管理系列与组级否定关键词及共享否定词集；基于 search_query 报表找出有花费无转化的不相关查询，提出否定词（系列级或共享集），经批准后应用。
【API 配置】凭据位于 ~/.secrets/yandex-direct.json（chmod 600），含 client_id、client_secret、oauth_token、可选 client_login；端点为 https://api.direct.yandex.com/json/v5/<service>，统一广告系列结构（UnifiedCampaign、UnifiedAdGroup、ShoppingAd、ListingAd）的增改走 /json/v501/，脚本自动路由；认证用 Bearer 令牌，代理访问用 Client-Login；支持 YD_SANDBOX=1 及 YD_TOKEN、YD_CLIENT_LOGIN、YD_API_VERSION、YD_SECRETS 环境变量覆盖；金额单位为百万分之一，报表以卢布返回（returnMoneyInMicros: false）。
【重要变更】2023-11 至 2024 年统一效果广告系列（ЕПК）取代文字图片、动态和智能横幅系列，搜索与 YAN 在同一系列需按 AdNetworkType 拆分统计；2024-07-01 起 YAN 禁用手动出价，手动策略仅限搜索；2025-06、2025-09 新增 AVERAGE_CPA_MULTIPLE_GOALS、PAY_FOR_CONVERSION_MULTIPLE_GOALS、MAX_PROFIT 策略；2025-11-13 移除 bidmodifiers.toggle，改用 set（100 为关闭）或 delete；2026-03-20 组合广告（RESPONSIVE_AD）支持最多 7 标题、3 文案、5 图、6 视频，需请求 ResponsiveAdFieldNames，否则按 TextAd 仅返回首项；2026-06-30/07-14 ЕПК 中文字图片广告仅可编辑，新增 TextAd 会创建 RESPONSIVE_AD，Title2 合并入标题（≤56 字符）或丢失；2026-06-22/07-06 手动出价系列与共享账户启用周预算，未花完最多 30% 结转，应分析 WeeklySpendLimit；2026-03-01 起俄罗斯消费者信息语言规则，广告中无俄语对应词的外来词需标记。
【API 限制与排障】adgroups.get、keywords.get、ads.get、bidmodifiers.get 每次 CampaignIds ≤ 10、AdGroupIds ≤ 1000；每次 get 最多 1 万对象，用 Page.Offset = LimitedBy 续取；negativekeywordsharedsets.get 的 Ids ≤ 30，省略 SelectionCriteria 可取全部，sitelinks.get 同理；ads.get 的 TextAdFieldNames 用 AdExtensions 而非 AdExtensionIds；报表 Goals ≤ 10，归因模型仅 AUTO、LSCCD、FCCD、LC，离线报表队列 ≤ 5；keywords.get 的 Productivity 恒为 null，AutotargetingCategories 已弃用，改用 AutotargetingSettings。所有请求返回空 HTTP 204（即使令牌错误）通常表示 Yandex 侧关闭了 Direct API（如 2026 年 10 月数据中心事件后的特殊模式），非令牌、IP 或脚本问题；审计脚本提示找不到系列时可能全部已归档，可用 --include-archived 重跑。
【安全与质量要求】任何写操作（add、update、delete、suspend、resume、archive、moderate、bids、set）都须用户对具体变更明确批准，先展示请求 JSON 或可读差异再执行；审计、报表、优化为只读。转化分析只用优先目标，不用全部目标合计；3× Kill Rule 标记 CPA 超目标 3 倍的关键词/组/位置；策略学习期目标每周 ≥ 10 次转化，前 2–3 周不改策略、限额类型或付费模式，暂停超过 7 天会重启学习；周预算 ≥ 300 ₽，按转化付费 ≥ 10×CPA；优化前检查广告及组合广告各元素的审核状态；开启 ADD_METRICA_TAG，并通过 TrackingParams 或 Href 设置 UTM。
【参考文档与脚本】参考文件按需加载而非启动时加载：yandex-audit.md（55 项检查 YD01-YD55 及数据来源）、scoring-system.md（0-100 加权评分 A-F）、benchmarks.md（指标比较方法与俄罗斯市场粗略参考）、bidding-strategies.md（ЕПК 策略与 API 对应、周预算、学习、出价修正）、compliance.md（审核规则、广告标记、俄语规则）、image-specs.md（组合广告图片与视频规格）。脚本：yd-api.sh（通用 API 调用封装，v5/v501 路由、Client-Login、条目级错误检测）、yd-report.sh（报表封装，预设、目标、归因、离线轮询）、yd-audit.sh（自动化审计数据收集，全部对象加 4 份报表）；依赖 bash、curl、jq。另含审计子代理 agents/audit-yandex.md 用于并行系列分析。