docs(ai-copilot): 把 skills.mdx 六个技能的读/写/输出行按 src/skills 写实，whats-new 技能数 5→6 (#891)

[yinlianghui]

Fixes #891

content/docs/ai-copilot/skills.mdx 是另外两页（sales-copilot / service-copilot）当作「完整技能规格」去引用的那一页，而它每张技能表里的读取 / 写入 / 输出行描述的是 src/skills/*.skill.ts 并不具备的能力。本 PR 以 skill 源码为唯一事实来源，把六个技能逐行写实，并把 whats-new 的技能数从 5 改为 6。三语同改，不动 src/**。

基线：origin/main @ c94a35c7（即 #892 落地之后），行号已重定位。

一、前提复核（issue 断言逐条重核）

issue 的断言	复核结果	证据
crm_case 上没有 category、没有 queue	✅ 成立	src/objects/case.object.ts 全部 29 个字段里无此二名；grep -n "category|queue" 只命中 priority_rank 上下的注释文字
「工单类型的真实字段是 case_type」	⚠️ 措辞略有出入：字段键是 type，label 才是 Case Type	case.object.ts:137 type: Field.select({ label: 'Case Type', options: question/problem/feature_request/bug })。改文按字段实况写 Case Type（zh：类型），与 #861 在 service-copilot 页的落地口径一致
分流没有任何写工具	✅ 成立	case-triage.skill.ts:49 tools: ['describe_object', 'get_record']；case.actions.ts:13-39 两个 Action 均无 ai 块
allSkills 注册 6 个（含 LiveDataSkill）	✅ 成立	src/skills/index.ts:20-27
skills.mdx 自己写 six	✅ 成立	skills.mdx:21 "HotCRM ships with six core skills"
线索资格判定走 action_convert_lead / action_schedule_followup	✅ 成立，且动作语义已复测	lead-qualification.skill.ts:34-37,41-47；两个 Action 都带 ai: { exposed: true }（lead.actions.ts:35-39, 72-76）
Customer 360 instructions 只枚举四个对象	✅ 成立	customer-360.skill.ts:38-52

二、逐技能「源码依据 → 改文」对照

🚦 工单分流（case-triage.skill.ts）

行	源码依据	改文要点
读取	:49 tools 只有两个；:30-37 只 describe/get 当前工单，评判权重是客户分层 + 合同金额	只读当前工单 + 客户上下文；过往工单够不着（无检索工具）；没有产品可读（crm_case 无产品字段、无指向 crm_product 的 lookup）
输出	:38-47 优先级 + 一条理由 + 升级/关闭指引 + 回复交给 email_drafting	优先级（低/中/高/紧急）+ 那一条理由 + 指向 Escalate Case / Close Case；没有分类、没有团队、没有文章清单、没有致谢草稿
写入	:49 + case.actions.ts:13-39（无 ai 块）；case.object.ts 无 category/queue	从「更新 priority、category、queue」改为 什么都不写；并写明被删的两个名字在 crm_case 上根本不存在（工单自己的分类字段是 Case Type），落地动作是坐席点按钮

🎯 线索资格判定（lead-qualification.skill.ts）

行	源码依据	改文要点
读取	:23-25 describe + get + query 相关活动历史	线索本身 + 相关活动历史；不读营销活动参与、不读匹配的客户历史（指令里没有这两步）
输出	:31-33 评分 + 每维度一行理由 + 唯一下一步 + 引用 ID	0–100 BANT 评分；不返回热门/温热/冷淡评级，也不返回建议状态（lead.object.ts:200 的 rating 是 1–5 星 线索评分，不是三档评级）
写入	:34-37,41-47；lead.actions.ts:13-40,58-77；lead-conversion.flow.ts:235-246；schedule-followup.flow.ts:73-101	技能自己不写：≥70 调 Convert Lead（流程建客户/联系人/可选商机，并把线索标记 is_converted + status: converted），否则调 Schedule Follow-up（建 crm_task + 回填 next_followup_date）；rating 两者都不写

✍️ 邮件撰写（email-drafting.skill.ts）

行	源码依据	改文要点
输入 / 读取	:23-26,39 只 get 联系人（+请求点名时的客户或商机），query 取近期往来	按指令写实
输出	:32-33 两个主题行备选 + 推荐哪一个	补上原来漏掉的「第二个主题行备选 + 推荐」
写入	:34-37 + contact.actions.ts:45 send_email 无 ai 块	从「不自动写入」改为 根本没有发送工具可调；只摆草稿 + 指向 Send Email

📈 收入预测（revenue-forecasting.skill.ts）

行	源码依据	改文要点
输入 / 读取	:19-31,41 describe + aggregate 按阶段 + query 捞风险交易；opportunity.object.ts:208 days_in_stage	周期默认本季度；指令里没有读字段历史这一步
输出	:25-37 按阶段汇总 + 加权价值 + 风险交易 + 区间（仅承诺口径 ↔ 完整加权管道）+ 可选出图	原文的 Closed / Commit / Best Case / Pipeline 四桶不是这项技能的输出：它们是 opportunity.object.ts:233 的 forecast_category 字段与 forecast-snapshot.flow.ts:241-290 写进 crm_forecast 的那几个金额——已写明去向，未静默删名
摘要表同格	同上	摘要表原来也写「Rolls up pipeline into commit / best-case / pipeline buckets」，同错同改

🔭 Customer 360°（customer-360.skill.ts）

行	源码依据	改文要点
读取	:38-52,61 只枚举 crm_account / crm_contact / crm_case / crm_opportunity / crm_knowledge_article + aggregate_data	去掉合同/近期活动/营销活动成员，并按 #861 口径写明「够得着但没被要求读」
输出	:53-59 固定三段 + 内联引用 ID + 空段如实说明	从「销售/服务/合同/参与四部分」改为 Account Snapshot · Active Work · Risks & Notes；zh 沿用 #861 的「英文小标题 + 中文注释」写法

🔄 实时数据（live-data.skill.ts）

四行（输入/读取/输出/写入）与 :19-42 逐条核对全部对得上，未改动——如实记录，不为凑改动而改。

直接相关散文

• 「技能如何协同」：原文两条「工单分流/邮件撰写可以调用 Customer 360」在任何 instructions 里都没有出处；case-triage.skill.ts:46-47 里唯一真实的移交是把客户回复交给 email_drafting，而且它是给用户的指引（下一问再问）。整段重写为「技能之间不互相调用 + 唯一的那条移交 + 两条不存在的调用点名说清」。
• 「每项技能都遵循什么」的确认条：原文「任何写入的技能在提交前都需要明确的用户确认」与源码不符——schedule_followup 是 ai.exposed 但没有审批闸门（lead.actions.ts:70-76 注释原文：additive and reversible, so no approval gate），而 convert_lead 因 confirmText 会走人工审批（:29-39）。改为按两个动作分别写实。这条是直接支配「写入」行的散文，故一并写实。

三、whats-new 数词证据

content/docs/whats-new.mdx:99（zh-Hans/zh-Hant :81）位于 ## v5.0 — Latest release → ### AI Copilot 段内，写「Five built-in skills」，缺 Live Data。src/skills/index.ts:20-27 的 allSkills 注册 6 个：LeadQualification / EmailDrafting / RevenueForecasting / CaseTriage / Customer360 / LiveData；skills.mdx:21 自己也写 six。三语同改为「六项」并把 live data 补进列举。

未动：whats-new.mdx:56（zh :39）「Sales Copilot with 5 skills」在 ### What's in v1.0 段内，是历史版本条目，不在本单裁定面。

四、与 #892 的衔接

基线取 #892 合并后的 c94a35c7，行号重定位：

• docs(ai-copilot,service): 把「内置四个 AI 知识库」整套说法按元数据写实 (#808) #892 落地的六行**「知识库」单元格与摘要表 Case Triage 一格里的措辞逐字保留、零回退**（diff 中这些行不出现）。
• 新写实与其衔接：Customer 360 的「读取」行新增 crm_knowledge_article，与 docs(ai-copilot,service): 把「内置四个 AI 知识库」整套说法按元数据写实 (#808) #892 那行「唯一会读文章的技能」一致；工单分流的「读取/输出」行说「够不着文章」，与 docs(ai-copilot,service): 把「内置四个 AI 知识库」整套说法按元数据写实 (#808) #892 的知识库行同因（无检索工具）；邮件撰写的「读取」行不再重复讲文章，交由 docs(ai-copilot,service): 把「内置四个 AI 知识库」整套说法按元数据写实 (#808) #892 那行承担。

五、验证输出

步骤	退出码	关键行
pnpm validate	0	✓ Validation passed (1302ms)
pnpm typecheck	0	tsc --noEmit 无输出
pnpm build	0	Artifact: dist/objectstack.json (1921.4 KB)
pnpm test --maxWorkers=2	0	Test Files 66 passed (66) / Tests 1587 passed | 1 skipped (1588)
pnpm lint	0	13 warning(s), 14 suggestion(s)（均为既有的 approval/field-group 提示）
pnpm hygiene	0	✓ no raw control bytes in first-party files / ✓ source hygiene clean

test 输出里的 ✗ source hygiene: scanned director(y|ies) missing: .changeset 是 source-hygiene-scan-surface 元测试的预期 stderr（本 PR 新增了 .changeset/skills-table-write-real.md），测试整体仍为 0。

改动文件另做控制字节自扫：grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 六个 mdx + changeset 零命中。

六、changeset

.changeset/skills-table-write-real.md（'hotcrm': patch），站内路径用反引号。

---

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 5:24am