# AGENTS.md - OpenClaw Workspace Rules

## 1) Core Behavior

- Execute first, explain later. Do not throw generic blockers to the user.
- Before asking user for help, try at least 2 autonomous recoveries.
- If still blocked, only ask for concrete missing items (OTP/CAPTCHA/2FA/session expired).
- Do not fabricate data. Every conclusion must come from tool results.

## 2) Routing Priority (Highest to Lowest)

### A. Xiaohongshu Tasks (override all market routes)

Trigger keywords: 小红书 / 红书 / xhs / 笔记 / 种草 / 舆情

Required sequence:
1. `exec: xhs-api health`
2. `exec: xhs-api login-status`
3. If not logged in: `exec: xhs-api login-qrcode /root/.openclaw/workspace/outputs/xhs-login-qrcode.png`
4. Then use:
   - `xhs-api search "<keyword>"`
   - `xhs-api detail <id> <xsecToken> true`

### B. Sales / Aftersale / Refund / Performance Tasks (SQL only)

Trigger keywords: 销售 / 业绩 / 售后 / 退款 / 费比 / 店铺周报 / SKU结构 / 发货 / 工单 / 客诉 / 客服体验 / 用户反馈 / 话术分析 / 产品信息 / 商品ID / SKU编码 / 成本 / 材质 / 预览图 / 库存 / 缺货 / 补货 / 安全库存

Hard rules:
- Must route to `company-sales-db-analysis`.
- Do not use yuce website for sales/aftersale tasks.
- Do not use web_search/web_fetch for these tasks.
- Must run at least one `exec` data query before final response.
- Do not call `tts` unless user explicitly asks voice output.

Mandatory first checks (once per turn):
1. `exec: company-db health`
2. Query by SQL templates in `/root/.openclaw/workspace/sqlserver/`

Template mapping:
- 店铺周报 -> `shop_weekly_report.sql`
- SKU结构 -> `sku_structure_report.sql`
- 产品信息/库存预警（SKU/成本/材质/预览图/库存/发货件数/缺货天数） -> `exec: product-info "<sku或关键词>" --days 30 --limit 20`
- 全量SKU缺货预警明细 -> `exec: stock-risk-alerts --days 30 --limit 500`
- 全量SKU缺货预警推送飞书（结构化字段） -> `exec: stock-risk-to-feishu --days 30 --top 100`
- 商品ID查SKU清单 -> `exec: product-skus-by-id "<商品id>" --limit 1000`

Product info output minimum fields:
- SKU编码, SKU名称, 成本价, 材质, 预览图地址, 当前库存, 日均发货件数, 预计缺货天数, 补货建议
- 推荐补充：SPU/货号/分类/供应商/尺寸/重量/SKU状态
- 若存在物流数据，追加 一区/二区/三区 运费汇总（近30天）
- 若存在售后数据，追加 售后总览 + 售后类型矩阵 + 售后原因TOP（近30天）
- 若涉及库存/补货，必须追加：近30天在售商品ID数量（按渠道）+ 商品ID对应店铺名/运营人 + 采购/工厂/仓库信息
- 库存预警（强制）：
  - 必须输出 `estimated_stockout_days` 与 `replenishment_lead_days(=10)`
  - 当 `estimated_stockout_days <= 10` 时，结论必须标记 `补货紧急`
- 退款原因/售后 -> `after_sale_360_report.sql`
- 费比异常 -> `fee_ratio_alert.sql`
- 物流时效 -> `logistics_sla_report.sql`
- 运费效率 -> `freight_efficiency_report.sql`
- 客服热点 -> `customer_service_hotspot_report.sql`
- 客服体验/话术分析（可指定时间段） -> `exec: customer-service-analysis --start <YYYY-MM-DD> --end <YYYY-MM-DD> [--shop "店铺关键词"] --limit 20`
  - 输出需包含：客服能力总分与等级（S/A/B/C/D）
- 安装服务 -> `install_service_quality_report.sql`
- 链接目标覆盖 -> `link_target_coverage_report.sql`

Aftersale special rule:
- Do not analyze only one table.
- Must prioritize reason dimensions from:
  1) `jst_goods_profit_kpi_items_afs` (undefined57/58/56)
  2) `pc_kfChatLog` (mainReason/secondReason/thirdReason)
  3) `fys_Ticketing_install` (工单维度)
- If reason fields are empty, explicitly mark as "源字段为空" and continue with available dimensions.

Metric priority rule (very important):
- Prefer piece/order counts first: `发货件数`, `订单数`, `售后件数`, `工单量`.
- Amount metrics are secondary and optional.
- Unless user explicitly asks for 金额/费用/利润, never rank conclusions by amount first.

Output format for sales/aftersale:
1. 件数与订单核心结论
2. 原因结构（一级/二级/三级）
3. 趋势与异常
4. 金额补充（可选）
5. 可执行建议
6. 若为客服体验/话术任务，必须补充“对话案例 + 推荐回复话术”
7. 若为客服体验/话术任务，必须补充“客服能力评分（按客服名字输出四维度+总分+等级）”

### C. Market Analysis Tasks (non-sales)

Trigger keywords: 市场分析 / 行业分析 / 类目分析 / 竞品分析 / 趋势分析

Hard rules:
- Only allow domain `hq.yucekj.com` / `yucekj.com`.
- Use `exec` with `yuce-browser` only.
- Never use browser `search` action.
- Never use web_search/web_fetch for this route.
- If login/CAPTCHA blocks, ask user for that exact step only.

### D. General Online Search Tasks

Trigger keywords: 在线搜索 / 搜一下 / 查资料 / 最新消息 / 新闻 / 政策更新

Preferred execution:
1. First use `exec: web-search "<query>" --count 8` (stable path; includes Brave+Bing fallback).
2. Optional: if user explicitly asks for Brave-only, use `web_search`.
3. Summarize with source links, and mark date/time context when content is time-sensitive.

## 3) Security and Privacy

- Do not expose raw data source endpoints in user-facing replies.
- Mask domain/IP/api endpoints in final messages when possible.
- Exception: when reporting Feishu push result, must show the actual Feishu table link (do not mask `*.feishu.cn`).
- Never leak secrets from env files.

## 4) Reply Quality Rules

- Send concise final answer; no long tool transcript dump.
- If task may take time, send one short processing hint first.
- Do not repeat the same result twice in one turn.
- If a request fails, include: what was attempted, what failed, and next actionable fix.

## 5) Feishu Delivery Rules

Trigger keywords: 推到飞书表格 / 写入飞书 / 同步飞书 / 发送飞书表格链接

Default target (pinned):
- default_link: https://acnuoqgha8fk.feishu.cn/wiki/RBSxwq8woiQDCUkRZfkcg7x8nMb?table=tblzuMy85WiRAUX5&view=vewuydm9EI
- default_app_token: SZ4ebCKU3a9OdfspetxcSeg1n4g
- default_table_id: tblzuMy85WiRAUX5

Required behavior:
- Never auto-push to Feishu unless the user explicitly asks in the current turn.
- If current turn does not contain Feishu push intent, do analysis only and return in chat.
- When user asks to push result to Feishu Bitable, run write action first (feishu_bitable_create_record or feishu_bitable_update_record).
- For stock-risk/inventory warning reports, do NOT write a long text blob into one cell; must push structured columns/rows (summary row + detail rows), preferably via `exec: stock-risk-to-feishu --days 30 --top 100`.
- In continuous chat, if user says "把上一个结果推到飞书", use the previous assistant result as write payload.
- If user does not provide a link in current turn, ALWAYS use the pinned default target above.
- Do NOT ask user for Feishu link again unless user explicitly asks to switch to another table.
- In final reply, always include:
  1) push status (success/failed)
  2) target sheet link (actual link used)
  3) written record_id (or updated count)
- If write partially fails, return succeeded records and failed reason list separately.
- If user explicitly asks for "只要结果", keep reasoning short but still include the sheet link and write status line.

## 6) Workspace Paths

- SQL templates: `/root/.openclaw/workspace/sqlserver/`
- SQL catalog: `/root/.openclaw/workspace/outputs/company-sales-db-catalog.md`
- Router skill: `/root/.openclaw/skills/web-task-router/SKILL.md`
- Tool guide: `/root/.openclaw/workspace/TOOLS.md`
- Site config: `/root/.openclaw/workspace/websites.yaml`