docs(ai-copilot,service): 把「内置四个 AI 知识库」整套说法按元数据写实 (#808)

[yinlianghui]

Fixes #808

按 PM 在 #808 的定调裁定走方向 1（文档跟元数据）：「HotCRM 内置四个 AI 知识库」整套说法收敛到真实存在的 crm_knowledge_article + 其 7 个 category。方向 2（真把这四个库建成元数据）是产品扩展，本 PR 不预判——见文末声明。

前提复核（基线 origin/main @ 0d3f3216）

issue 正文的两个前提逐一复测，全部成立：

• src/ 里四个名字零命中。全仓 grep 只有三处，全是无关命中：knowledge_article.object.ts:9 的一行注释（Support Knowledge Base）、product.object.ts:31 与 translations/en.ts:835 的产品字段组标签 Product Information（是 fieldGroup label，不是知识库）。没有任何元数据声明知识库，src/skills/ 里没有任何知识库绑定。
• crm_knowledge_article.category 的取值确认为 7 个：Getting Started / How-To / Troubleshooting / Billing & Pricing / API & Integrations / Release Notes / Policy。四个知识库名一个也不在其中。

全量落点清点

grep -rn "Sales Knowledge\|Product Information\|Support Knowledge\|Competitive Intel" content/ 加中文译名全量清点，实得 12 个页族（本单正文记 3 处、追评补第 4 处，其余 8 处为本次清点新增）：

#	页面（×3 语言）	本单是否已记	处置
1	content/docs/service/knowledge-base	✅ 正文	整段重写
2	content/docs/administration/setup（Day 5 清单 + 产品目录一条）	✅ 正文（Day 5）	重写；:82 为新增落点
3	content/docs/ai-copilot/knowledge-bases	✅ 正文	整页重写
4	content/docs/ai-copilot/sales-copilot（Email Drafting 输入列）	✅ 追评	重写
5	content/docs/ai-copilot/skills（每个技能的「知识库」行 ×5 + 摘要表一格）	➕ 新增	逐行写实
6	content/docs/ai-copilot/index（三大组成部分之二）	➕ 新增	一行改写
7	content/docs/ai-copilot/service-copilot（Support Knowledge articles / Support Knowledge index）	➕ 新增	纯名字修正
8	content/docs/getting-started/introduction（能力清单一条）	➕ 新增	一行改写
9	content/docs/whats-new（Four built-in knowledge bases）	➕ 新增	一行改写
10	content/docs/revenue/products（规格表被知识库读取）	➕ 新增	段落改写
11	content/docs/service/cases:156、content/docs/service/index:48	➕ 新增	不在本 PR，见「留给别单」
12	content/docs/service/sla-and-escalation:105	➕ 新增	不在本 PR，见「留给别单」

误报一处，不动：content/docs/revenue/products:16 的 | **Product Information** | 是产品对象 fieldGroups.basic 的标签，与知识库无关。

逐处改文

1. service/knowledge-base ×3 — 「Support Knowledge 索引涵盖四种内容类型」+ 四库表整套拿掉，改为：知识库就是一个知识文章对象，7 个真实分类各自该放什么；标签 / 状态 / 受众 / 语言 / 文章编号；四个列表页签（全部 · 已发布 · 我的草稿 · 复核队列）；对象声明的检索字段是标题/摘要/文章编号。「Service Copilot 如何使用它」按 skill 源码重写：只有 customer_360 读文章，分流无检索工具、邮件撰写不取知识来源。/knowledge/support/ 目录、嵌入刷新、「可以新增知识库并接入特定技能」三条虚构机制随之写实。

2. administration/setup ×3 — Day 5 三条 seed 步骤改成真实可执行动作（按分类写文章 → 设置受众 → 发布 → 复核分类标签），并直说没有叫 Sales Knowledge / Product Information / Competitive Intel 的东西可 seed、也没有可供对战卡挂靠的竞争对手对象。:82 的「上传数据表（馈送产品信息知识库）」改为写实。

3. ai-copilot/knowledge-bases ×3 — 整页重写，保持文件名、slug、meta.json 位置与页面标题不变（导航稳定）。骨架换成：四个旧名字逐一给出实际落点 → 一篇文章是什么 → Copilot 如何取到文章（分类/标签过滤查询，不是语义检索）→ 哪些技能会读文章（6 个技能逐一，含理由）→ 为什么没有语义检索（知识来源只能声明在 agent 上，技能应用无处声明）→ 不存在的东西（文档摄取、/knowledge/... 目录、嵌入分块与检索阈值、夜间/手动重索引、Confluence 等连接器、按技能绑定知识库）。

4. ai-copilot/sales-copilot ×3（追评第五处） — 该页刚被 #848 / #861 改过，已重定位行号（英文 :79-80，zh :74-75），零回退。两个独立事实一并写实：(a) 两个知识库不存在；(b) email-drafting.skill.ts:21-37 的五步 instructions 从不取任何知识来源，技能虽带 query_records 够得着 crm_knowledge_article 但从未被要求去读。与 PR #865 在 service 页落的「草稿不引用知识文章」完全同口径——两页暂不一致自此消除。

5-10. 其余六页按同一裁定口径写实：skills 每个技能的「知识库」行改为该技能是否真读文章（含 Customer 360° 反向纠偏：原写「无——纯粹由数据驱动」，实际它是唯一会读文章的技能）；index / introduction / whats-new 的「四个知识库」列举改为一个知识文章库；service-copilot 两处只改虚构库名，不动任何能力表述；products 的规格表段落写实（文件字段真实存在，但没有任何东西读它的内容）。

边界遵守

• Docs drift (round 2 leftovers): ~39 product pages still name "Sales/Service Copilot" as a persona; config comment and RELEASE_STRATEGY.md still stale #612 边界：Copilot 称谓/人格用语一律未动，只改知识库实体相关句子。新写段落沿用各页原有称谓（service-copilot / index 用「助手」，introduction 用「Copilot」）。
• 不加守卫：issue 建议的「文档知识库名必须解析到元数据取值」断言面，在方向 1 落地后已不存在（文档里不再有需要解析的知识库名），故按裁定不加。
• 未触碰 src/**、content/docs/releases/；未升级 @objectstack/*；三语同步；zh 术语按语言包（zh-CN.ts 的分类/标签/状态/受众译名逐一对齐，zh-Hant 按本仓既有繁体用词：物件 / 欄位 / 佇列 / 整合 / 匯入 / 效能 / 單一登入）。

方向 2 留给维护者

「元数据跟文档」——真的把 Sales Knowledge / Product Information / Support Knowledge / Competitive Intelligence 建成元数据（扩 category 取值，或引入 skills 侧的知识源绑定）——是产品扩展，本 PR 按裁定不预判。若要做，另立实现单；文档届时随实现再更新，本 PR 的写实文本正是那时的对照基线。附一条本次量到的约束供决策参考：AIKnowledgeSchema 只挂在 AgentSchema.knowledge 上，纯 skills 应用没有声明知识源的位置（src/skills/customer-360.skill.ts:13-28 有完整推导），所以方向 2 不只是加几个 category 取值那么简单。

与 #865 / #861 的衔接

• docs(ai-copilot): 按 skill 源码写实 service-copilot 其余段落的能力残留 (#860) #865 在 service-copilot.mdx 落的「草稿不引用知识文章」是本 PR 第 4 处的同一事实，措辞与之对齐（「草稿的依据是这个技能读到的记录……需要援引文章时从 Customer 360° 拿」）。
• docs(ai-copilot): 按 case_triage 与 customer_360 源码写实两页能力清单 (#847) #861 在 sales-copilot.mdx / service-copilot.mdx 落的 Customer 360° 段落（按分类/标签匹配已发布文章、按 KA-0007 引用）是本 PR 新知识库页的事实来源，两处说法一致。

验证输出

全部在共享锁 flock /tmp/os-heavy-verify.lock + NODE_OPTIONS=--max-old-space-size=4096 下依次执行：

命令	退出码	关键行
pnpm validate	0	仅既有 approval/field-group 警告，无新增
pnpm typecheck	0	tsc --noEmit 无输出
pnpm build	0	Artifact: dist/objectstack.json (1921.4 KB)；17 Objects / 24 Flows
pnpm test -- --maxWorkers=2	0	Test Files 66 passed (66) · Tests 1587 passed | 1 skipped (1588)（其中 source-hygiene 元测试的「✗」stderr 为预期）
pnpm lint	0	13 warning(s), 14 suggestion(s)，与 main 同
pnpm hygiene	0	✓ no raw control bytes in first-party files · ✓ source hygiene clean

补充自查：

• 控制字节：grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 扫全部 31 个改动文件，零命中（pnpm hygiene 的 403 个 content/.changeset 文件扫描亦通过）。
• callout 三语配平（docs-drift.test.ts 的等量规则）：本地按该测试同款算法全仓复算，132 个 locale 页 0 处不匹配；本 PR 未增删任何 > 块。
• 锚点：knowledge-bases# / administration/setup# 全仓零引用，故重写页内标题与把 setup 的「### 13. 知识库」改名为「### 13. 知识文章」不产生悬空锚点（content/docs 还剩 17 处悬空锚点（全仓实测），三类新成因：emoji 标题、标题后来加了后缀、zh 页沿用英文锚点 #866 / 守卫能力：给 content/docs 的站内链接加「锚点存在性 + 语言前缀一致性」检查（#749 / #764 / #866 各自的成因都能被它抓住） #867 族）。

顺手发现（已另立单，不在本 PR 修）

• service 三页仍写「建议一个解决方案」会检索知识库并起草回复 / Copilot 用知识库对相似历史工单做模式匹配——两个技能都做不到 #890 — service/cases:156、service/index:48、service/sla-and-escalation:105 三页仍写「建议一个解决方案」会检索知识库并起草回复、Copilot 用知识库对相似历史工单做模式匹配。主语是技能能力（service-copilot.mdx 还剩四处与 skill/对象源码不符：幽灵「产品」字段，以及三段仍在复述「分流会匹配知识库文章」的提示语 #860 / PR docs(ai-copilot): 按 skill 源码写实 service-copilot 其余段落的能力残留 (#860) #865 那一族），不是知识库实体，故不在本单裁定面内；这三处的链接标签 Support Knowledge Base 同时是本单的虚构库名，建议随整句重写一并处理。
• skills.mdx 的「读取 / 写入 / 输出」三行与 src/skills 全面对不上（分流写入两个不存在的字段），whats-new 还把技能数写成 5 个 #891 — skills.mdx 各技能表的「读取 / 写入 / 输出」行与 src/skills 全面对不上（分流的「写入 category、queue」两个字段在 crm_case 上都不存在），外加 whats-new 把技能数写成 5（allSkills 注册 6 个）。本 PR 只改了该页的「知识库」行。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 4:00am

[yinlianghui]

第二次提交（45aeda86）：清点表第 6 行的补正

自查 content/docs/ai-copilot/index 时发现该页开头还有一句同源遗留，第一次提交漏掉：

The six skills read from the same objects you see in the UI, and they know your
products, knowledge bases, and process rules.

同一页第 2 项已经写实成「一个知识文章库……没有独立的产品、销售或竞争情报库」，开头这句的复数 knowledge bases 与之自相矛盾，故三语一并收敛为 knowledge articles / 知识文章 / 知識文章。PR body 清点表第 6 行的「一行改写」应读作两行（第 19 行 + 第 29 行）。

改动后重跑：pnpm hygiene 退出码 0（✓ no raw control bytes in first-party files · ✓ source hygiene clean）、pnpm test -- --maxWorkers=2 退出码 0（Test Files 66 passed (66) · Tests 1587 passed | 1 skipped (1588)）；三个改动文件控制字节自扫零命中。

---

Generated by Claude Code