# AGENTS.md 与知识库「规则层」设计（需求梳理稿）

> 状态：**只梳理、不动工**（运营者要求先对齐需求）。
> 目标：让客服 AI 像真正的 harness 工程一样有**明确范围边界、数据源登记、工具调用规则、沉淀与更新机制**；
> 店规只是「事实资料」的一部分，话术沉淀是「把经验变成规则」的机制，产品 Excel 是「结构化资料」的一种。

---

## 1. 你的需求（我理解的）

1. 每个客服项目要有一份类似 `AGENTS.md` 的**项目规则文档**：说清 AI 是谁、能答什么、不能答什么、什么场景读哪份资料、什么场景调什么工具/MCP、什么情况必须转人工。
2. 这份规则要**可以更新**：以后新增资料（店规、话术、产品表、图片）时，除了放文件，还要在规则里登记「它是什么、什么时候用、优先级」。
3. 现有的**店规**其实已经很接近这种「规则+事实」混合体，可以拆成：规则层（怎么答）+ 事实层（答什么）。
4. **话术沉淀**：从真实对话里复盘出可复用的问答/打法，评审后并入知识库，并在规则变更记录里留痕。
5. **产品 Excel 表**：需要让 AI 能查（型号/价格/卖点/库存口径），并明确「以哪个为准、成本价之类敏感列不能给买家」。
6. **图片**：新增了图片素材后，要能声明「什么时候发哪张图」（地址图、效果图、新品图），以及 AI 能不能自动发。
7. 最终效果：AI 的回答不是靠运气检索，而是「规则先定边界，资料给事实，工具补实时」。

---

## 2. 现状盘点（能直接用的 vs 缺的）

| 已有 | 说明 |
|---|---|
| 项目资料库 | 每个项目独立目录、文件树、关键词检索、pinned 必读、面板维护 |
| 真实店规 | 「示例店铺」项目已放入 8.3KB 真实店规（v1 / 店规 V2.2） |
| AI 上下文 | 按「账号 → 项目」注入：pinned 全文 + 检索片段（≤6000 字） |
| 闲鱼工具 | 32 个（订单/商品/发品/退款/客户/产品库/采集/曝光…） |
| 抖音 MCP | 店铺实时数据（shop_state / stock_list，只读），适配器预取注入 |
| 话术沉淀 | playbook：增量复盘 → 小模型提炼 → 写 `knowledge/*.md`（**目前写的是旧的全局目录，没接项目库**，默认关闭） |

| 缺口 | 影响 |
|---|---|
| 没有 AGENTS.md 概念/加载 | 规则散在店规里，无法区分「硬边界」和「业务事实」 |
| 自动回复**没有工具调用** | 现状是纯文本生成 + 上下文注入；订单状态/店铺/库存只能靠适配器预取 |
| 图片只支持人工发 | `adapter.sendImage` 有，但 AI 回复链路只发文本 |
| Excel 不能直接被检索 | 目前只索引 .md/.txt/.json/.csv；xlsx 要导入转换 |
| 沉淀没有评审/变更记录 | playbook 直接写文件，易跑偏，也不留痕 |
| 规则更新无版本/changelog | 改完不知道改了什么、为什么 |

---

## 3. 分层模型（建议）

```
L0 硬约束（代码级，任何文档都不能绕过）
   · AI 默认关闭；只有明确开启才自动回
   · 退款/赔付/免单/承诺时间/保证店铺 → 一律转人工
   · 不可逆平台操作（关闭订单/退款/改价/发品）→ 必须人工确认
   · 发送前复查（人工刚回过就让位）、审计全量留痕

L1 项目 AGENTS.md（规则层，每个项目一份，进 AI 上下文最前面）
   · 身份/语气/输出格式
   · 范围边界：可答 / 不可答 / 必转人工
   · 数据源登记表：文件、类型、优先级、什么时候读
   · 工具 & MCP 调用策略表：场景 → 动作 → 前置条件 → 确认要求 → 失败兜底
   · 图片/素材使用规则
   · 升级与交接规则
   · 变更记录（版本/日期/改了什么/为什么）
   · 自测问句（验收样例：问句 → 期望行为）

L2 事实资料（检索层，AI 按需读）
   · 店规细则（规则全文/FAQ）
   · 话术库（按意图分类：接待/价格/催发货/售后/新品）
   · 产品表（Excel 导入后的结构化资料）
   · 图片素材 + 素材清单
   · FAQ / 历史优质对话

> 账号未绑定任何项目时：适配器返回「该账号还没分配项目」，**不再退回旧 `客服知识库`**（旧路径已不存在，退回只会报 ENOENT 误导）；
> 面板把这种情况显示为灰色提示（不是红色故障），只有项目资料/规则真的坏了才告警。

## 3.1 原则（2026-10-20 修正，务必遵守）

- **AGENTS.md / 系统提示词里绝不列举具体问题或具体答案**。客服面对的是开放问题，写死等于按问题打补丁；
- 规则层只写**通用判定原则**：资料里有依据 → 直接答；资料里没有/无法确认 → 转人工；涉及承诺/退款赔付/投诉 → 转人工；
- 业务事实（价格、时间、流程、产品）只在**资料文件**里，由检索按问题动态获取；
- 模型误判「有依据却转人工」时的兜底也必须是**通用机制**（带「复核」提示重答一次），而不是给某个词加特例。

L3 沉淀（演进层）
   对话复盘 → 候选话术/候选规则 → 人工评审 → 写入 L2 或补充 L1 → 记 changelog
```

原则：**L1 定边界和策略，L2 给事实，L0 兜底**；AI 永远不直接改写 L1（只能产出候选，等人确认）。

---

## 4. AGENTS.md 模板（草案）

```markdown
# AGENTS.md — 示例店铺项目客服规则
版本：v1.0 ｜ 更新：2026-10-20 ｜ 维护人：运营者

## 1. 身份与语气
- 你是「示例店铺」的客服，语气亲切、短句、口语，不用客服腔。
- 一次回复不超过 3 句话；先回答问题，再给下一步建议。

## 2. 范围边界
### 可以回答
- 营业时间、烫豆规则/价格、预约与到店流程、退换规则、产品与材料咨询、催发货安抚
### 不可以回答 / 必须转人工
- 退款、赔付、免单、优惠承诺 → 转人工
- 固定店铺、留位、具体等待时间 → 转人工
- 投诉、差评、情绪激动 → 转人工，并提示「店长马上来」
- 外带材料代烫 → 明确拒绝（不转人工）

## 3. 数据源登记（什么时候读什么）
| 资料 | 类型 | 优先级 | 使用场景 |
|---|---|---|---|
| 店规速查.md | 规则全文 | 最高（必读） | 所有规则类问题 |
| 话术/接待.md | 话术 | 高 | 开场、语气、催回复 |
| 话术/价格.md | 话术 | 高 | 问价/议价 |
| 产品/产品表.md | 结构化 | 高 | 问型号/价格/库存口径 |
| 素材/门店地址.png | 图片 | 中 | 问到店地址时 |

## 4. 工具与 MCP 调用策略
| 场景 | 动作 | 前置条件 | 确认 | 失败兜底 |
|---|---|---|---|---|
| 买家问「到我号了吗/订单状态」 | 只读查订单（mtop） | 有 buyer_id | 不需要 | 查不到→「我帮您看下，稍等」转人工 |
| 买家问「现在还有位置吗」 | 读店铺 MCP（shop_state） | 项目绑定了 MCP | 不需要 | 无数据→不承诺，转人工 |
| 买家要退款/改价 | 禁止 AI 操作 | — | 必须人工 | 直接转人工 |
| 买家要地址/效果图 | 发素材图（见素材清单） | 图在清单里且允许自动发 | 不需要 | 没图→文字说明+转人工 |

## 5. 图片素材清单
| 图片 | 用途 | 触发条件 | 是否允许 AI 自动发 |
|---|---|---|---|
| 门店地址.png | 到店指引 | 买家问地址/怎么走 | 是 |
| 新品-草莓.png | 新品推荐 | 买家问新品/有什么推荐 | 是 |
| 客照-XXX.jpg | 效果展示 | 买家问效果 | 否（需授权） |

## 6. 输出规范
- 必须基于资料回答；资料没有 → 「我帮您问一下店员」；
- 引用规则时给依据（如「按店规，特殊烫 19:00 截止」）；
- 不编价格、不编活动、不编时间。

## 7. 变更记录
| 版本 | 日期 | 改了什么 | 为什么 |
|---|---|---|---|
| v1.0 | 2026-10-20 | 初版：范围边界 + 店规/话术/产品登记 | 上线 |
| v1.1 | 2026-10-25 | 新增「新品图自动发」 | 双十一活动 |

## 8. 自测问句（验收用）
| 问句 | 期望 |
|---|---|
| 特殊烫免费吗？ | 答免费 + 镜像烫要开拼前说 |
| 现在来还来得及吗？ | 按当前时间对照截止表回答 |
| 能给我留个位置吗？ | 转人工，不承诺 |
| 退款！ | 转人工，不承诺赔付 |
```

---

## 5. 关键设计问题（需要先定，决定工作量）

### 5.1 工具调用：三条路线

- **A. 声明式预取（推荐 v1）**：AGENTS.md 声明「什么场景需要什么数据」，适配器/运行时在回复前预取（店铺、订单状态、库存）拼进上下文。无工具调用风险，改动小，实时性够用。
- **B. 只读工具 function-calling（推荐 v2）**：给自动回复循环加「模型可请求 1–2 次只读工具调用」的能力（查订单、查店铺、查产品），结果回灌后生成回复。体验最好，但要处理循环/超时/幻觉调用。
- **C. 转 Agent 会话**：把买家消息交给 DSH agent（带工具 + AGENTS.md），由 agent 回复。能力最强，但时延/成本/可控性都变差，客服场景不建议。

**建议**：v1 用 A；等规则稳定再上 B 的只读白名单（写操作永远人工）。

### 5.2 产品 Excel 的接入方式

| 方案 | 做法 | 优缺点 |
|---|---|---|
| **1（推荐）导入为资料** | 上传 xlsx → 后台用 openpyxl 转成 `产品/产品表.md`（表格）+ 保留原文件 → 索引检索 | AI 能直接读；源表更新后重新导入；不需要工具调用 |
| 2 保留 xlsx + 查询工具 | 新增 `cs_product_query` 读表按型号/别名查 | 表格大时更准，但需要工具调用（依赖 5.1-B） |
| 3 以平台为准 | 产品信息以闲鱼产品库/商品详情为准，Excel 仅运营参考 | 实时性最好，但 AI 问「卖点」时不如资料表全 |

需要确认：产品表有哪些列？**成本价/供应商**这类敏感列绝对不能给买家（导入时可配置「买家可见列」白名单）。

### 5.3 图片：AI 能不能自动发

- 现状：`adapter.sendImage` 已有，但 AI 回复链路只发文本。
- 若要自动发图：回复结构里支持 `[[img:素材/xxx.png]]` → runtime 发文本后补发图片（失败降级为文字）；
- 需要素材清单（文件、用途、触发条件、是否允许自动发、是否涉及肖像/版权）；
- 建议 v1 先在 AGENTS.md 声明「哪些图可自动发」，实现发图；不确定的图一律转人工。

### 5.4 话术沉淀怎么接规则

- 现状 playbook 写旧的 `knowledge/*.md`，且无评审 → 改为：按项目沉淀 → 产出**候选变更**（新话术/FAQ 条目/规则补充建议）→ 面板「待审变更」→ 人工通过后写 L2，并在 AGENTS.md changelog 记一条；
- AI 永不直接改 AGENTS.md；
- 频率/开关/审批人需要定（建议默认关，手动「复盘一次」+ 每周自动一次）。

### 5.5 规则更新权限与流程

- 谁能改 AGENTS.md：只有你？还是运营也能改（留 changelog）？
- 改完是否立即生效（当前知识库 60s 缓存；规则可以强制立即重载）；
- 是否需要「发布前预览」：改完用自测问句跑一遍「AI 会读到什么」再保存生效。

---

## 6. 面板要补的能力（粗略）

1. 项目内「规则」编辑器：直接编辑 AGENTS.md（Markdown，带章节提示/模板）；
2. 数据源登记表：新增文件时选类型（规则/话术/产品/图片/FAQ）+ 使用场景 + 优先级 + 是否必读；
3. 工具策略表：勾选允许 AI 用哪些只读工具、哪些必须转人工；
4. 素材清单：图片 + 用途 + 触发条件 + 允许自动发；
5. 待审变更：话术沉淀产生的候选，一键采纳/丢弃；
6. 变更记录（changelog）+「预览验证」按钮（自测问句 → 实际上下文）。

---

## 7. 建议实施顺序（等确认后）

- **P1（先让规则生效）**：AGENTS.md 加载（进上下文最前）+ 面板编辑 + 数据源登记 + 自测预览；
- **P2（资料与素材）**：产品 Excel 导入（含敏感列白名单）+ 图片素材清单 + AI 自动发图；
- **P3（沉淀与工具）**：话术沉淀接项目库 + 待审变更 + 只读工具调用（function calling）+ 项目级 MCP 配置。

---

## 8. 需要你拍板（8 个问题）— **已确认，见 §9**

1. AGENTS.md 粒度：**每个项目一份**（示例店铺、高报各自独立）？还是要一份全局通用红线 + 项目补充？
2. 工具调用：v1 先做「规则声明 + 预取注入」（A），还是直接上「只读工具 function-calling」（B）？
3. 产品 Excel：用推荐方案 1（导入成资料）吗？表里哪些列**买家可见**、哪些列（成本价/供应商）必须隐藏？
4. 图片：要不要做「AI 自动发图」？先列一下哪些图允许自动发、触发条件是什么。
5. 话术沉淀：自动写入还是**必须人工审**后再进知识库？你希望多久复盘一次（每天/每周/手动）？
6. 规则更新权限：只有你能改 AGENTS.md，还是运营也能改（留 changelog）？
7. 示例店铺与高报的规则差异有多大？通用红线是否抽成一份共享模板（新项目复制即用）？
8. 验收方式：「上下文预览」跑自测问句即可，还是要做「历史对话回放」对比（更费时）？

---

## 9. 运营者已确认的决策（2026-10-20）

| # | 决策 |
|---|---|
| 1 | **每个项目一份 AGENTS.md**（示例店铺、高报完全独立），不做统一大模板 |
| 2 | 工具调用走 **B：只读工具调用**（像 DSH agent 一样有工具，但**只读**）；**写操作（退款/改价/关单/发品）绝不注册给 AI、绝不自动执行**，只能人工。本条要求代码层强制：白名单 + 参数校验 + 只读接口，不靠 prompt 自觉 |
| 3 | 产品 Excel：**导入成 `产品/产品表.md` 表格**（保留源 xlsx），让 AI 能检索调用；敏感列（成本价/供应商）导入时剔除 |
| 4 | **要 AI 自动发图**：在 AGENTS.md 的「素材清单」里声明图片 + 用途 + 触发条件 + 是否允许自动发 |
| 5 | 话术沉淀：**不人工审，直接入库**；**每 3 天复盘一次**，由 AI 自动填充；后期再开子 agent 做校对 |
| 6 | 规则编辑：**运营者 + 我（助手）都能改**，每次改动必须记 changelog（版本/日期/原因） |
| 7 | 每个项目自己的规则文档，不抽通用大模板 |
| 8 | 验收：**历史对话回放对比**（用真实历史消息跑新规则，对比 AI 回复与人工回复/旧回复） |

### 关于「工具调用不能直接执行、防止远程操作电脑」的承诺

客服 AI 的工具**只会在插件进程内调用白名单里的只读通道**（mtop 查询/库里检索/素材读取），
不执行 shell、不调本机命令、不装包、不读写项目外文件；
写接口在注册层就被排除（AI 拿不到 → 即使模型被诱导也无法调用），不依赖提示词约束。

---

## 10. 实施计划（等资产齐了开工）

### P1 — 规则层（AGENTS.md 生效）✅ 2026-10-20 已落地

1. ✅ 每个项目根目录放 `AGENTS.md`（资料库文件树里可见、可编辑），并作为 AI 上下文**最前面**的规则段注入（上限 5000 字，计入 citations `score 200`）；
2. ✅ 面板：项目工具栏新增「规则」按钮——有则打开编辑，没有则一键生成模板（含范围边界/数据源/工具策略/changelog/自测问句）；
3. ✅ 数据源登记：写在 AGENTS.md 的表格里，人看 + AI 读；
4. ✅ 及时响应：资料库索引增加**新鲜度检测**——外部（资源管理器/脚本）改了文件，下次检索自动重建索引；AGENTS.md 每次回复实时读取，改完立即生效；
5. ✅ 测试：`L7`（规则层必须排最前、不进索引）、`L8`（外部改文件自动重建索引）；
6. ✅ 示例店铺项目已按真实店规起草 v1.0 `AGENTS.md`（范围边界/工具策略/输出规范/自测问句）。


### P2 — 资料与素材

1. ✅ 产品 Excel：`scripts/import_products.py`（xlsx → `产品/产品表.md`，剔除商促价/平台券 ID/归属户等内部列，保留源 xlsx 到 `产品/源文件/`）；已导入 9 个抖音来客商品；
2. ⬜ 图片素材：上传入口 + `素材/素材清单.md` 模板（图片/用途/触发条件/是否允许自动发）；
3. ⬜ AI 自动发图：回复结构支持 `[[img:素材/xx.png]]` → runtime 发文本后补图，失败降级文字；
4. ⬜ 话术沉淀改造：写项目库 `话术.md`（按意图分节），每 3 天自动跑一次，直接入库，changelog 记一条。

### P3 — 只读工具调用 + 回放验收

1. 给自动回复循环加**只读工具调用**（最多 2 轮）：`查订单/查店铺(MCP)/查产品/查物流`，全部只读；
2. 未来若加写操作：只能以「生成待人工确认的操作卡」形式出现，绝不由 AI 执行；
3. 历史对话回放：读取 store 里真实入站消息 → 逐条跑新规则生成回复 → 与人工回复/旧版回复对比 → 输出差异报告（不发送）。

### 还缺的资产（需要运营者给）

1. **产品 Excel 文件路径**（或直接放进项目目录），以及「哪些列可以给买家看」的规则；
2. **图片素材目录/清单**：允许自动发的图 + 触发条件（例如：问地址→门店位置图；问新品→新品图；问效果→成品图，是否涉及客照授权）；
3. 示例店铺项目第一版 AGENTS.md 由我按真实店规起草，你审核；高报项目等资料到了再做。