小红书聚光每日投放检查
对小红书聚光当日投放执行一次固定口径体检：取授权 → 取数 → 计划健康度扫描 → 笔记素材检查 → 计划调整建议 → 错峰准备。
本 Skill 只做读取与判定，不执行任何后台写操作。所有建议都要人工在聚光后台确认后再执行。
何时使用
用户提到以下任一表达时进入本流程：
- 「聚光检查」「聚光投放检查」「聚光每日检查」「聚光体检」
- 「小红书投放检查」「小红书投放体检」「笔记投放检查」
- 「帮我看看今天聚光跑得怎么样」「今天聚光要不要调」
- 「今天哪条笔记该停」「聚光哪个计划衰减了」
不触发：单独出现「聚光」或「小红书投放」两三个字；与投放检查无关的聚光话题（开户、资质、结算、充值、产品版本咨询）；小红书笔记写作、选品、账号运营等不涉及投放数据的话题。
付费闸门
本 Skill 按次计费。未取得本次授权前，不得执行四段判定，也不得输出报告。
付费链路固定四段，顺序不可颠倒、不可跳过：probe → pay → complete → ack。
前置检查 确认当前环境具备支付能力
发起下单前先确认当前 Agent 环境中存在支付宝支付能力工具（官方 alipay-payment-skill 或 alipay-bot 提供的工具，例如用 check-wallet 确认钱包可用）。
- 存在：继续。
- 不存在：终止流程，给出提示语——「合作智能体请升级至最新版；开放智能体请从 SkillHub 安装官方「支付宝 AI 付」Skill 后重试」。
不要自建支付通道，不要手工构造付款链接或二维码。
probe 请求资源，取得 402 账单
python scripts/paid_gate.py
不带凭证请求付费端点 /v1/xhs-juguang-check。服务端返回 HTTP 402 与 Payment-Needed 头。
收到 402 时暂停交付，把 Payment-Needed 原文原样落盘到 ~/.xhs-juguang-check/payment-needed.txt，退出码 20。
pay 交给官方支付能力，用户本人完成付款
把账单交给官方支付能力（alipay-payment-skill / alipay-bot 提供的能力）拉起收银台。
用户本人完成付款，Agent 只做编排，不代付、不垫付、不伪造凭证。
complete 携带凭证重试，验付与履约
用户确认已支付后：
python scripts/paid_gate.py --payment-proof-file <Payment-Proof 文本文件路径>
服务端解码 Payment-Proof，调 alipay.aipay.agent.payment.verify 完成验付，校验通过后调 alipay.aipay.agent.fulfillment.confirm 确认履约，返回 HTTP 200 与 Payment-Validation 头。
验付分两层，不要在本 Side 重复服务端职责：
| 层 | 执行方 | 校验内容 |
|---|---|---|
| 客户端侧 | 本 Skill 的 scripts/paid_gate.py |
响应 success 为真、响应体非空、交易号 32 位 |
| 服务端侧 | 商户资源接口 server/pay_service.py |
凭证真伪、金额、资源标识、时效，由官方验付接口完成 |
ack 交付后确认履约，失败可幂等重试
- 报告产出并交付后，履约确认成功才把订单标记为
FULFILLED。 - 履约确认失败时返回 502 与
FULFILLMENT_CONFIRM_FAILED。此时资源已生成，用同一 Payment-Proof 重试即可，明确告知用户不要重新支付。 - 同一
trade_no再次请求时直接返回已保存结果（already_fulfilled为true），不重复扣费、不重复交付。订单表在trade_no上有唯一约束，资源生成在事务内一次性完成。
退出码路由
| 退出码 | 含义 | 动作 |
|---|---|---|
| 0 | 已取得授权 | 进入「开始前：环境检查」，继续检查流程 |
| 20 | 需要支付 | 把 [[JUGUANG_PAYMENT_REQUIRED]] 区块中的商品名、金额、订单号、支付截止时间原样告知用户，等用户完成支付 |
| 10 | 付费配置缺失 | 只展示缺失项的配置步骤，不进入检查流程 |
| 11 | 付费服务不可达 | 说明不可达原因，停止本次流程 |
| 12 | 付费服务返回异常 | 照录返回的状态码与代码；返回 FULFILLMENT_CONFIRM_FAILED 时提示用同一 Payment-Proof 重试 |
付费闸门的硬性约束
- 不得在未取得授权时输出报告，也不得先出报告再补支付。
- 不得伪造支付成功、不得跳过支付步骤、不得手动构造凭证。
- 不得向用户展示
Payment-Proof原文、签名、密钥或任何凭据内容。 - 交易号与
Payment-Proof属中间过程信息，不对用户展示；用户侧只给订单号（out_trade_no）用于对账。 - 不得改写、截断或复用
payment-needed.txt与 Payment-Proof 文件内容。 - 支付与履约的失败状态照实报告，不隐瞒不替换。
开始前：环境检查
- 运行
python scripts/juguang_report.py --show-config。该命令只输出配置就绪状态，不输出任何凭据值。 - 再运行
python scripts/check_environment.py取依赖级状态。该脚本退出码非 0 表示存在未就绪依赖，不是崩溃；未提供宿主探测结果时，需要探测的检查项会返回probe_required，此时以第 1 步的本地结果为准。 - 按状态路由：
| 状态 | 判定依据 | 动作 |
|---|---|---|
| ready | api_ready 为 true 且 token_cached 为 true |
跳过所有配置说明，直接执行主流程 |
| needs_setup | missing 非空 |
只展示缺失项的配置步骤；用户拒绝配置时转手动兜底 |
| partial | 凭据齐全但部分接口取不到 | 直接执行主流程，在结果中标注本次降级范围 |
| unavailable | 凭据齐全但接口报错或 token 无法续期 | 展示原因与恢复步骤；无法恢复时转手动兜底 |
- 已经通过的配置项不重复讲解。
主流程
步骤 1 确认取数日期与账户
- 默认查询当日；用户指定日期则用指定日期。
- 目标账户取配置中的
advertiser_id；用户明确指定了别的账户时才覆盖。
步骤 2 取数
优先自动取数：
python scripts/juguang_report.py --date <YYYY-MM-DD>
自动取数失败或未配置时转手动兜底（见「降级」）：
python scripts/juguang_report.py --manual <数据文件路径>
手动数据格式见报告模板文件 output-template.md 的手动输入模板。用户直接粘贴数据时，由你按同一模板整理后落盘，再调用脚本。
步骤 3 四段判定
python scripts/juguang_report.py --manual <数据文件路径> --format markdown
按判定口径文件 iron-rules.md 的四段结构逐段判定，每条结论只允许三种取值：达标 / 不达标 / 待确认。
四段内容：
- 计划健康度扫描——列出各计划消耗、点击成本、转化成本，标记衰减计划。
- 笔记素材检查——阅读率 ≥ 15%、互动率 ≥ 8% 达标判定；不达标笔记建议暂停并返回内容优化环节。
- 计划调整建议——优质计划加预算放量；衰减计划只执行换素材、换人群包、换沟通角度的切换，不加钱。
- 错峰准备——检查下一轮素材与人群包是否就绪，未就绪则提醒提前准备。
判定只使用取到的原始数值，不用记忆或经验补值。任一判据缺失即判「待确认」，并写明缺哪一项。
步骤 4 输出
按报告模板文件 output-template.md 的骨架输出，四段齐全，段序固定。
每条建议必须附判据（引用具体判据结论或具体数值）。没有判据的建议不得输出。
输出前先过「三条铁律」闸门，违反任一条的建议直接删除，并把被删原因记入「被铁律或判据拦下的建议」小节。
三条铁律
铁律是输出闸门，不是建议强度偏好。
- 严禁零笔记直接建计划。 任何新建计划或放量的建议，都必须先确认存在已就绪且达标的笔记素材；没有就删除该条建议并说明原因。
- 衰减计划不加钱只切换。 衰减计划的动作只允许换素材、换人群包、换沟通角度三项。加预算、提价、提高出价一律禁止。
- 保持投放连续性。 不得输出「暂停全部计划」「停投观察」「等这条计划跑死再开新计划」类建议。暂停类建议只允许针对不达标笔记对应的投放单元，且必须同时给出接力动作。
降级
主通道不可用时不放弃整个流程，按下表降级：
| 触发条件 | 降级动作 | 输出标注 |
|---|---|---|
未配置 app_id / app_secret / advertiser_id |
展示配置步骤；用户拒绝则转手动 | 本次为手动数据 |
access_token 失效且刷新失败 |
提示重新授权；本次转手动 | 数据由用户提供 |
| 接口报错或超时 | 有限重试后转手动 | 自动取数失败，原因照录 |
| 权限未批（如缺数据报表权限） | 说明缺哪个权限点，转手动 | 部分字段待确认 |
| 用户拒绝配置 | 直接转手动 | 本次为手动数据 |
| 接口路径核验未通过 | 停止自动取数，转手动 | 自动取数未通过核验 |
| 某段判据不足 | 该段只输出结构与缺口清单 | 逐项写明缺哪一项 |
| 付费服务地址未配置 | 展示付费协议文件 pay-protocol.md 的部署与配置章节 | 无输出，未取得授权 |
| 付费服务不可达或返回异常 | 说明原因后停止 | 无输出，未取得授权 |
付费闸门不参与降级。 授权取不到时停止整个流程，不用「先出报告后补支付」「跳过支付」等方式替代。
手动数据必须记录来源与时间，并标注「用户提供，未与平台核对」。
硬性禁止
- 不执行任何后台写操作：不建计划、不暂停计划、不改预算、不改出价、不动素材、不改定向。只给建议。
- 不要求用户在对话中粘贴
app_secret、access_token、refresh_token或账号密码。 - 不估算、不补默认值、不推断缺失字段。取不到就标「待确认」。
- 不给突破三条铁律的建议。
- 不把「消耗低」直接解读为「建议关停」。
- 不声称已执行用户没有确认执行的操作。
- 未取得本次授权就输出报告，或用任何方式绕过付费闸门。
- 展示 Payment-Proof、交易号、密钥、签名等凭据与中间过程内容。
质量自查
输出前逐项确认：
- [ ] 已完成付费闸门，本次授权已取得
- [ ] 四段齐全，段序未调整
- [ ] 每条结论都是达标 / 不达标 / 待确认三者之一
- [ ] 每个「待确认」都写明了缺哪一项
- [ ] 每个数值都能追溯到数据来源
- [ ] 衰减标记附了具体判据与数值
- [ ] 每条建议都附判据
- [ ] 三条铁律逐条校验并给出了结论
- [ ] 全文没有出现执行类动作的完成时态
停止条件
出现以下任一情况时停止本流程并说明原因，不用低可信结果顶替：
- 未取得本次授权，且用户不接受付费或无法完成支付
- 付费服务不可达、返回异常，或校验反复不通过
- 当前环境缺少支付能力工具
- 判据全缺，无法产生任何一条结论
- 用户提供的数据与实际账户口径明显不符且无法澄清
- 涉及账户权限、凭据泄露等安全问题
参考文件
- 判定口径与三条铁律：
references/iron-rules.md - 报告模板与手动数据模板：
references/output-template.md - 付费协议：
references/pay-protocol.md - 配置指南：
references/setup-guide.md - 聚光接口、字段与已知坑：
references/api-fields.md
