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 時間戳>"
}

欄位發現協議

小蔥技能站7w4.net發現了升級外掛。

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。