# 客户项目 KB 建设指引

> **适用对象**：SC 顾问 / 项目团队——在 SC Base KB 之上，为某个具体客户项目构建专属知识层，**并建立可操作的售后支持 Agent**。
> **配套**：`SC_Base_KB_使用说明书_v2.0.md`（分层架构）、`KB_建设方法论_指导书_v1.0.md`（项目 KB 通则）。
> **版本**：v1.1 | 2026-07-01（v1.1 新增 §九~§十：Agent 操作规则 + 评估框架）

---

## 一、定位：在 Base 之上，只叠加客户专属

客户项目 KB 不是另起炉灶，而是 **SC Base KB 的上层增强**：

```
SC Base KB（官方怎么配/怎么跑，永远在）
   └ 客户项目 KB（本客户的真实值 / 特例 / 决策 / 已知问题）← 你建的这层
```

**一句话原则：Base 装"标准官方 how"，客户 KB 只装"本客户和标准不一样、或标准没有的那部分"。**

> ⚠️ 最大的坑：把 Base 已有的官方步骤在客户 KB 里再抄一遍。重复内容维护必漂移。**Base 有的，一律引用，不重写。**

---

## 二、两种形态（都合法，走同一套规则）

| 形态 | 是什么 | 何时用 |
|------|--------|--------|
| **临时投喂** | 会议纪要、客户配置清单、一份主数据 Excel、说明邮件——当场拖给 AI | 即用即走，不必先成文 |
| **沉淀成形** | 反复用到的客户决策/特例，整理成正式 `KB_客户_*.md` 文件 | 长期、多人复用 |

两者在分层模型里占同一格，适用同样的优先级（见 §五）。**临时文档是未经核验的客户输入**，AI 用它取真实值/决策，但不拿它推翻官方步骤正确性。

---

## 三、客户项目 KB 装什么 / 不装什么

**装（Base 没有的客户专属）：**
- 客户**真实组织结构**（公司码/销售组织/工厂/库存地点的实际编码）
- 客户**真实主数据约定**（编号规则、关键客户/物料/供应商）
- **配置选择与决策**（"本客户选集中采购""不上 EWM""BD9 用专属定价 ZXXX"）
- **客户特有操作路径**（标准步骤之外的客户化操作）
- **范围界定**（哪些 Scope Item 在/不在本项目范围）
- **已知问题 / 上线踩坑**（本客户环境特有的报错与解法）
- **集成约定**（与第三方系统的接口）
- **定制开发 / RICEFW 规格**（客户自建系统、报表/接口/增强/表单/银企直联等——这层装"指向开发文档 + 与标准流程的触点"，标准底座仍引用 Base）
- **未决问题清单**（带状态）

**不装（指向别处）：**
- 官方操作步骤 / 配置方法 → 引用 Base KB
- 功能"2602 支不支持 / 选哪个 Scope Item" → 指向 SA KB
- 顾问的推测 / 通用 SAP 常识 → 不是事实，不放

---

## 四、文件结构与命名

建议每客户一个目录，包含两部分：**KB 文件**（知识层）+ **AGENTS.md**（Agent 行为规则）。

### 4.1 KB 文件（知识层）

按"决策类 / 操作特例类 / 问题类"组织：

```
客户项目KB_[客户名]/
├── KB_00_[客户名]_Navigation_Map.md   三层路由、冲突裁决、回答红线（ALWAYS 加载）
├── KB_01_项目概况.md            客户信息、实施范围、组织结构、问答边界
├── KB_02_组织与主数据_真实值.md  客户真实组织编码、主数据约定（覆盖 Base 占位值）
├── KB_03_蓝图决策记录.md         每条：决策 + 原因 + 日期 + 负责人 + 依据
├── KB_04_操作特例_[模块].md      本客户与标准不同的操作（引用对应 Base 文件）
├── KB_05_集成约定.md             系统集成触点、接口清单、状态
├── KB_06_上线问题记录.md         报错 + 解法（hypercare 沉淀）
├── KB_07_未决问题清单.md         带状态（未决/已决/已关闭）
├── KB_08_运行质量与证据治理.md   证据等级、长文件加载策略、复审节奏（可选）
├── KB_99_来源索引.md             归档证据线索（可选）
└── KB_MANIFEST.json              机器可读路由、加载策略（可选）
```

### 4.2 AGENTS.md（Agent 行为规则）

**必须采用"轻外壳 + 外链 Prompt + 操作铁律"结构**，禁止将 SA/SC Prompt 全文内嵌：

```
AGENTS.md（~400 行）
├── System Prompt 加载顺序表       ← 3 行，外链 project/SA/SC prompt 文件
├── KB 三层架构图                  ← 5 行，优先级：项目 KB > SC > SA
├── 项目 KB 文件索引               ← 16 行，快速路由表
├── Issue Ledger 路径              ← 5 行，问题清单目录
├── 不在范围清单                   ← 1 行，明确列出不在实施范围的功能
└── Agent 工作铁律（15 条）         ← ~350 行，完整售后操作规则
```

> ⚠️ **反模式**：将 SA Prompt (~600 行) + SC Prompt (~300 行) 全文内嵌到 AGENTS.md = 每次对话浪费 ~700 行上下文且无操作规则。这是"重外壳 + 无规则"的典型错误。

---

## 五、引用 Base 与优先级（铁律）

**引用规范**：指向 Base 一律用**完整文件名 + 章节**，禁止抄内容、禁止缩写。
- 正确：`本客户 BD9 定价用 ZXXX，其余步骤同 KB_SD_BD9_Sell-from-Stock.md §操作步骤`
- 错误：把 BD9 的步骤复制进客户 KB；或写"参见 BD9"

**冲突优先级**：`客户项目 KB ＞ 蓝图 ＞ SC Base KB ＞ SA KB`
**但官方事实锚点不变**：客户 KB 只能覆盖"客户特例/真实值/范围"；若客户 KB 与 Base 的**官方步骤正确性**矛盾，AI 应**标出冲突让顾问判断**，不默默照改。

---

## 六、质量红线（项目 KB 专用）

- 每条决策必须注明 **日期 + 负责人 + 依据**（会议纪要号/邮件/客户签字）。
- 未决问题必须有状态；已决的及时更新。
- 不含产品功能判断（"这个功能 2602 支不支持"→ 指向 SA KB）。
- 不重写 Base 官方步骤；只写差异，用完整文件名引用。
- 真实值覆盖 Base 占位值时，明确标注"客户真实值"。

---

## 七、Owner 与生命周期

| 项 | 规则 |
|----|------|
| Owner | 项目经理（无 Owner 不正式上线） |
| 更新触发 | 蓝图决策变更、配置选择更改、里程碑完成、上线问题 |
| 更新频率 | 周级（跟项目里程碑） |
| 退役 | 项目收尾归档，整理成"项目交接手册"；不再更新 |

---

## 八、与 Base KB 的协作校验

客户 KB 上线前自检：
- [ ] 没有抄 Base 已有的官方步骤（只写差异）
- [ ] 所有对 Base 的引用是完整文件名 + 章节
- [ ] 每条决策有日期/负责人/依据
- [ ] 真实值已覆盖并标注 Base 占位值
- [ ] 未含产品选型/功能判断（那是 SA KB）
- [ ] 与 Base 官方步骤的冲突点已显式标注、由人确认

---

## 九、Agent 操作规则建设（铁律体系）

> **为什么需要**：KB 解决"AI 知道什么"，铁律解决"AI 怎么做"。KB 97 分 + Agent 0 分 = 综合 75，照样不能干活。**没有铁律的 Agent 只是 KB 注册表，不是售后支持工具。**

### 9.1 为什么需要铁律

| 场景 | 没有铁律 | 有铁律 |
|------|---------|--------|
| 顾问说"客户反映一个问题" | Agent 直接给技术分析，不知道要区分给客户/给顾问的内容 | 铁律一A 确认场景 → 铁律十一 双输出格式 |
| 顾问说"这个单据报错了" | Agent 直接猜原因，不查已有记录 | 铁律四 四步诊断：上线问题→未决→操作特例→升级 |
| 顾问要查配置值 | Agent 可能用训练记忆回答 | 铁律二 查来源再开口：先输出 KB 引用 |
| Agent 要在 P 系统操作 | 直接执行，不确认 | 铁律三 生产系统二次确认 |
| 问 OA/MES 内部怎么实现 | Agent 推断外部系统逻辑 | 铁律六 集成问题只答触点 |

### 9.2 铁律体系（15 条）

每条铁律在 AGENTS.md 中以独立章节呈现，格式统一：触发条件 → 执行步骤 → 输出格式。

| 编号 | 铁律名称 | 核心规则 | 来源 |
|------|---------|---------|------|
| 零 | 云原生拦截 | Public Cloud 无 SE16N/SPRO/ABAP → 查 KB 替代流程 | SC Prompt §1.4 |
| 一 | 开场先分类 | 每次对话声明 A/B/C/D/E + 模式 + 知识层 | 康诺实践 |
| 一A | 开答前确认场景 | AskUserQuestion 三选一：提出问题/给出方案/内部分析 | 康诺实践 |
| 二 | 查来源再开口 | 回答前先输出 `来源：文件名 §章节` | 方法论原则三 |
| 三 | 生产系统二次确认 | P 系统写操作必须文字确认 | 安全合规 |
| 四 | 诊断走四步不跳步 | 上线问题→未决清单→操作特例→升级判断 | 康诺实践 |
| 五 | 边界判断优先于执行 | 变更请求/开发Bug/SAP Bug/配置修改 → 分类处置 | 康诺实践 |
| 六 | 集成问题只答触点 | 只答触发条件+替代步骤+异常处理，禁止推断外部逻辑 | 康诺实践 |
| 七 | 样例值不进P系统 | SC Base 样例值只用于演示，P 系统取客户真实值替换 | SC Prompt §1.2 |
| 八 | 自查只对照KB | 被追问时验证答案只用 KB 内容，禁止训练记忆推翻 | 康诺实践 |
| 九 | 冲突停下不自决 | 信息冲突或涉合规/数据安全 → 停下等人工确认 | 方法论原则 |
| 十 | 诊断输出标准格式 | C 类诊断必须按固定格式输出（关联Issue/分类/来源/根因/步骤/升级判断） | 康诺实践 |
| 十一 | 双输出格式 | 有客户场景时强制两区：给客户（可直接发）+ 给顾问（内部分析） | 康诺实践 |
| 十二 | 禁止"我无法查询" | 禁止暴露 Agent 限制，用正确替代做法（直接问/直接做） | 康诺实践 |
| 十三 | Session ↔ Ledger 闭环 | C/E 类诊断完成后提炼日志 → 询问确认 → 回写 Issue Ledger | 康诺实践 |

### 9.3 铁律编写规范

每条铁律在 AGENTS.md 中的格式：

```markdown
### 铁律[N]：[名称]

**触发条件**：[什么情况下触发]

**执行步骤**：
1. [步骤1]
2. [步骤2]

**输出格式**：[固定模板]
```

> 铁律不是"建议"，是"强制"。Agent 遇到触发条件必须执行，不得跳过或简化。

---

## 十、Agent 质量评估框架（14 项清单）

Agent 上线前必须逐项检查，0/14 = 不可用，7/14 = 可用但不完善，14/14 = 完整。

| # | 评估项 | 检查标准 | 权重 |
|---|--------|---------|:----:|
| 1 | 请求类型分类 | AGENTS.md 是否定义了 A/B/C/D/E 分类机制 | 10% |
| 2 | 场景确认 | 是否有 AskUserQuestion 工作流区分有无客户 | 10% |
| 3 | 四步诊断法 | C 类问题是否有标准排查路径（上线→未决→特例→升级） | 15% |
| 4 | 双输出格式 | E 类问题是否有给客户+给顾问两个分区的固定模板 | 15% |
| 5 | Issue 闭环 | 是否有 Issue Ledger 路径 + session→ledger 回写规则 | 10% |
| 6 | 生产确认 | P 系统写操作是否有二次确认规则 | 5% |
| 7 | 边界判断 | 是否有变更/Bug/标准/配置的分类处置规则 | 5% |
| 8 | 集成触点 | 外部系统问题是否只答触发条件，禁止推断内部逻辑 | 5% |
| 9 | 样例值管控 | SC Base 样例值是否显式标注不进 P 系统 | 5% |
| 10 | 禁止表述 | 是否有"禁止我无法查询"规则及正确替代做法 | 5% |
| 11 | 查来源再开口 | 回答是否要求先输出 KB 引用来源 | 5% |
| 12 | 自查只对照KB | 是否有禁止训练记忆推翻 KB 的规则 | 5% |
| 13 | 不在范围声明 | AGENTS.md 是否明确列出不在实施范围的功能 | 5% |
| 14 | Issue Ledger 路径 | AGENTS.md 是否声明了问题清单目录和操作入口 | 5% |

**评分标准**：
- 14/14 = **95 分**（完整售后 Agent）
- 10~13/14 = **75~90 分**（可用，个别项待补）
- 7~9/14 = **55~70 分**（勉强可用，缺关键能力）
- 0~6/14 = **42 分以下**（不可用，只是 KB 注册表）

> **与 KB 评估的关系**：KB 质量（方法论 7 条原则）+ Agent 规则（本 14 项）= 综合评分。两者权重建议 60:40。一个 KB 97 分但 Agent 42 分的项目，综合只有 75 分——能回答问题但不能干活。

---

*客户项目 KB 建设指引 v1.1 | 2026-07-01 | 新增 Agent 操作规则 + 评估框架 | v1.0: 2026-06-14*
