name: nc-base version: "1.4" description: | NeoCRM AI Agent 通用行为规范。 所有 NeoCRM Skill 的基础依赖，定义 AI Agent 在操作 CRM 数据时必须遵守的行为规则。 layer: shared

NeoCRM AI Agent 行为规范

强制检查

技能的执行强依赖 neocrm 命令行，要保证本地安装的 neocrm-cli-client 命令行包是最新的，通过如下步骤进行：

1. 使用neocrm --version检查neocrm-cli-client版本，获取本地安装neocrm-cli-client的版本
2. 使用npm view neocrm-cli-client version，获取npm上的neocrm-cli-client的版本
3. 如果发现本地安装的neocrm-cli-client的版本和npm上的neocrm-cli-client的版本不一样，就使用npm install -g neocrm-cli-client@latest更新本地安装的 neocrm-cli-client 命令行包，重新学习neocrm命令的帮助，重新学习neo-skills-for-agent技能套件

登录检查

执行任何 CRM 操作之前，必须先确认已登录。通过 neocrm auth:whoami 检查登录状态： - 如果返回用户信息，说明已登录，继续操作 - 如果报错或提示未登录，必须引导用户完成登录

登录流程

用户首次使用或登录状态失效时，必须引导用户完成身份验证。禁止使用记忆中的clientId直接登录

环境选择

NeoCRM 提供两个登录环境：

操作步骤

Step 1. 询问环境

向用户展示选项，等待用户回复。

提示文案：

欢迎使用 NeoCRM！请选择登录环境：

1 - 正式环境（日常业务使用）

2 - 沙箱环境（测试、演练）

Step 2. 询问 clientId

用户确认环境后，向用户索要 OAuth 2.0 客户端 ID。

提示文案： - 用户选择 1 → "请提供您的 OAuth 2.0 客户端 ID（通常由管理员提供）" - 用户选择 2 → "请提供您的 OAuth 2.0 客户端 ID（沙箱环境）"

Step 3. 执行登录

收集到 clientId 后执行登录：

# 正式环境
neocrm auth:login -c <clientId>

# 沙箱环境
neocrm auth:login -c <clientId> --host crm-sandbox.xiaoshouyi.com

Step 4. 确认状态

登录成功后，通过以下命令确认用户信息： neocrm auth:whoami

黄金法则

1. 先加载 skill，再操作 — 执行任何 CRM 操作前，必须先加载对应的 skill，不允许跳过 skill 直接使用 neocrm 命令。未加载 skill 就操作是违规行为。
2. 先 describe，再操作 — 查询、创建、更新前都必须先获取字段定义。调用 describe 前必须完整理解 references/metadata-describe.md。不理解完整文档就调用是违规操作。
3. 禁止硬编码 — 字段名、字段值、实体名都必须运行时获取，不许猜
4. 展示再确认 — 写操作前必须展示完整内容，用户确认后才执行
5. 失败即停 — 写操作失败后不重试、不绕过，询问用户如何处理

写操作确认

创建、编辑、删除、转移等写操作，必须先向用户展示将要执行的内容，获得明确确认后才能执行。删除、批量操作等高风险操作需要额外的二次确认。

意图边界

用户说了什么就做什么。推断出的额外意图，先问用户是否需要，不自作主张执行。做不到时再问替代方案，不替用户做决定。

必填项处理

执行写操作前，如果存在用户未明确提供的必填项，必须将这些字段列出来询问用户，禁止编造、猜测或使用占位值填充。即使该字段有"合理的默认值"，也必须向用户确认后才能使用。

对于枚举类型、业务类型等有固定可选值的必填项，必须先通过 neocrm metadata:describe 或 neocrm metadata:busitype 获取可选值列表，然后将可选值展示给用户，由用户选择，不得自行假设。

操作前置协议

执行任何 CRM 操作之前：

• 确定目标实体：如果不确定该用哪个实体（不知道 objectApiKey），先从 memory/neocrm-entity-cache.json 读取实体列表；文件不存在时调用 neocrm metadata:objects 获取，获取后必须先通过 references/metadata-objects.md 的验证流程确认完整，确认通过后再简化字段（只保留 apiKey、label、objectId 等必要字段）写入缓存。
• 获取字段定义：操作前必须调用 neocrm metadata:describe -o <entity> 获取最新字段定义。
• 执行前必须完整理解 references/metadata-describe.md 的全部内容。不理解完整文档就调用是违规操作。
• 获取后必须先通过验证流程确认完整，确认通过后再进行字段映射。
• 字段定义不缓存，每次操作前实时获取。

实体列表缓存策略

缓存文件位置：memory/neocrm-entity-cache.json

缓存原则（无 TTL，无主动过期）：

• 首次使用时写入：第一次调用 metadata:objects 时，获取后必须通过 references/metadata-objects.md 的验证流程确认完整，确认通过后再简化字段写入文件；之后直接读文件，不再调用接口。
• 以下情况删除缓存、重新获取：
• 业务异常时（目标实体找不到、权限变化等）
• 用户明确要求查询最新实体列表时
• 字段定义不缓存：每次操作前必须重新调用 metadata:describe，确保获取最新字段结构。

缓存结构：

{
  "objectList": [...],
  "fetchedAt": "<ISO-8601 时间戳>"
}

字段发现协议

NeoCRM 支持租户自定义字段和必填项，同一实体在不同租户中字段可能完全不同。因此禁止凭经验猜测字段名或字段值，必须运行时动态获取。

以下操作之前，必须先调用 neocrm metadata:describe -o <entity> 获取字段定义：

⚠️ 前置条件：执行以下步骤前，必须已完整理解 references/metadata-describe.md 的全部内容。不理解完整文档就执行字段映射是违规操作。

强制字段映射步骤（查询/创建/更新均适用）：

调用 neocrm metadata:describe -o <entity> 获取字段定义后，必须通过 references/metadata-describe.md 的验证流程确认完整，再按以下顺序构建字段映射表（顺序不可颠倒）：

Step 1: 先列出需求 — 从用户的请求中提取所有需要用到的业务字段的中文名称列表。例如用户要查商机，需要的中文名称可能是：机会名称、客户、金额、阶段、负责人。

Step 2: 再逐个搜索 — 对 Step 1 中的每个中文名称，在 describe 返回的 fields 数组中按 label 搜索，找到后记录其 apiKey 和 type。如果某个中文名称在 fields 中找不到，告知用户该字段不存在，禁止猜测可能的 apiKey。

Step 3: 输出映射表 — 将搜索结果整理为映射表：

映射表格式：

label（中文名）→ apiKey（字段标识）→ type（类型）→ 用途（SELECT / WHERE / WRITE）

示例：

机会名称 → opportunityName → text → SELECT, WHERE
金额 → money → currency → SELECT
客户名称 → accountId → reference → SELECT

关键：映射表是搜索结果，不是猜测。先有中文名称，再从 describe 里搜出 apiKey，禁止反过来先想 apiKey 再填表。

禁止行为： - ❌ 先想好 apiKey 再填进映射表（顺序反了） - ❌ 跳过映射表直接构造 XOQL（即使你"觉得"知道字段名） - ❌ 映射表中出现未在 describe 结果中查到的 apiKey - ❌ 字段名报错后继续猜测其他字段名，必须回到 describe 结果重新按 label 搜索

字段发现步骤（创建/更新）： 1. 调用 neocrm metadata:describe -o <entity> 获取字段定义，获取后必须通过 references/metadata-describe.md 的验证流程确认完整 2. 构建字段映射表：按 label 搜索所有需要用到的字段，确认 apiKey 和 type（具体步骤见上方"强制字段映射步骤"的 Step 1~3） 3. 筛选 required: true 且 createable: true 的字段，与用户已提供信息对比，列出缺失项逐一询问 4. 业务类型字段通过 neocrm metadata:busitype -o <entity> 获取可选值，展示给用户选择 5. 禁止编造、猜测或用占位值填充任何必填字段

查找关联字段步骤（查询关联记录时）： 1. 调用 neocrm metadata:describe -o <关联实体> 获取字段定义 2. 构建字段映射表：找到 type: reference 且 referTo.apiKey 为目标实体的字段，记录其 apiKey 3. 禁止使用任何硬编码的关联字段名

describe 返回的字段 apiKey 是唯一合法的字段标识。禁止使用任何未出现在 describe 结果中的字段名，即使该名称在其他 CRM 系统中是通用的。

个性化 action 接口的参数不通过 metadata:describe 获取，以对应 references/<action>.md 文件为准。

实体定位规则（根据用户描述确定实体类型时）：

NeoCRM 支持租户自定义实体，实体的 apiKey 不可预测。当用户提到的对象无法直接确定实体类型时（如"自定义1"、"项目"等非标准名称），必须按以下步骤定位：

1. 调用 neocrm metadata:objects 获取租户所有实体列表（必须先通过 references/metadata-objects.md 验证完整）
2. 在结果的 label 字段中模糊匹配用户描述的关键词，找到对应实体
3. 记录该实体的 apiKey（用于后续查询和操作）和 objectId（用于需要传入对象 ID 的接口参数）
4. 禁止凭经验猜测 apiKey，即使是标准实体也建议通过 metadata:objects 确认

错误处理

遇到错误时，向用户说明原因和建议操作，不暴露接口路径、错误码等技术细节。

任何可能改变系统数据的操作（创建、更新、删除、转移、提交、转化等）失败后，必须立即停止，严禁以下行为： - 自行尝试其他接口、命令或方式重试同一操作 - 绕过失败步骤继续执行后续流程 - 用破坏性更强的方式（如直接修改字段、删除记录）替代失败的操作

失败后只能做两件事：向用户说明失败原因，以及询问用户希望如何处理。后续操作完全由用户决定。

查询操作失败时不受此限制，可以尝试调整查询条件后重试。查询类错误的标准恢复流程： - 字段名错误（no such column）→ 重新执行 metadata:describe（获取后必须先验证完整），从结果中按 label 找到正确的 apiKey，禁止继续猜测其他字段名 - 权限不足 → 告知用户权限问题，停止操作 - 查询结果为空 → 告知用户未找到匹配记录，引导确认查询条件

CRM 业务概念

X 天未跟进： 在 CRM 语境下，"X 天未跟进"是指某条记录（客户、商机、联系人、线索等）在最近 X 天内没有任何活动记录（activityrecord）。判断依据是该记录关联的活动记录的最后创建时间，而不是记录本身的更新时间。

命令使用规范

通用数据操作（创建、查询、更新、锁定等）使用具名命令： neocrm data:create、neocrm data:query、neocrm data:update、neocrm data:lock、neocrm data:unlock、neocrm data:get

个性化 action 接口（特定实体的特有操作，如线索转化、合同提交审批等）使用： neocrm api:post、neocrm api:get、neocrm api:put 或 neocrm api:patch

使用 api:post / api:get / api:patch 时，必须满足以下条件： - 对应的 nc-ext Skill 目录下有 references/<action>.md 文件 - 接口路径、参数名称、参数类型均以 references 文件为准 - 禁止凭经验猜测接口路径或参数结构

当操作既无具名命令、对应 references 文件也不存在时，必须告知用户"当前能力不支持该操作"，不得自行猜测接口调用。

这个 Skill 质量不错，文档写得非常详细，涵盖了 CRM 操作的各种场景。它的一大优点是规矩很清楚——操作前要先查询字段定义、写入前要展示给用户确认、失败了就停下来不乱来。功能覆盖面也比较广，客户、公海池、拜访准备等场景都有照顾到。美中不足的是文档有点长且部分内容重复，初次上手需要花点时间消化。总体来说，这是一个规范完善、考虑周全的 Skill Pack。