最近老有朋友問我“Agent 和普通的大模型 API 封裝到底差在哪”我做這類應(yīng)用的時(shí)間不算短過去一年里最大的感受就是區(qū)別不在于你調(diào)了幾次模型而在于你有沒有把“能力”做出“人感”來。這里說的“人感”落到工程上就是三件事Skill 有沒有記憶、有沒有角色、有沒有主動(dòng)性。很多剛接觸 AI Agent 的人以為 Skill 就是一段可以被大模型調(diào)用的函數(shù)給它一個(gè)名字、一段描述、一個(gè)執(zhí)行邏輯完事。但當(dāng)你把 Skill 做成這樣你得到的只是一個(gè)工具不是一個(gè)能幫忙做事的智能體。今天這篇文章我就拿一個(gè)真實(shí)能跑的例子——“任務(wù)推進(jìn)助手”Skill手把手把它寫出來。這個(gè) Skill 會(huì)記住你的偏好、給自己設(shè)定角色還會(huì)在合適的時(shí)機(jī)主動(dòng)提醒你該做的事情。文章面向兩類人一類是剛會(huì)調(diào)用大模型 API、想學(xué) Agent 開發(fā)的新手另一類是已經(jīng)在做 Agent 框架、但一直覺得“工具不夠聰明”的開發(fā)者。本文不要求你有很深的機(jī)器學(xué)習(xí)基礎(chǔ)只要你有 Python 基礎(chǔ)能跑通 OpenAI 兼容接口就基本能跟上。代碼偏工程向我會(huì)把所有關(guān)鍵選擇的“為什么”都說清楚。1. 動(dòng)手之前先拆解 Skill 的三層能力1.1 Skill 和普通函數(shù)的邊界在哪里先說個(gè)你可能踩過的坑很多 Agent 框架只是把 Function Calling 包裝成了 Skill。底層邏輯是這樣框架把工具的 JSON Schema 喂給大模型模型覺得該調(diào)工具時(shí)就返回一個(gè) tool call然后 Python 執(zhí)行完再喂回去。這套機(jī)制本身沒問題但請(qǐng)你想一個(gè)問題函數(shù)是無(wú)狀態(tài)的Skill 如果也只是無(wú)狀態(tài)的那它充其量是“工具箱里的扳手”而不是“能獨(dú)當(dāng)一面的幫手”。我理解中的 Skill至少要包含三部分元信息name、description、version、調(diào)用條件。這決定了大模型在什么場(chǎng)景下會(huì)選中它。執(zhí)行邏輯真正做事的那段代碼、提示詞、工具調(diào)用鏈。生命周期它在被調(diào)用前要準(zhǔn)備什么調(diào)用后要記住什么運(yùn)行完之后會(huì)不會(huì)主動(dòng)觸發(fā)其他動(dòng)作。把這三部分補(bǔ)齊Skill 才從一個(gè)“函數(shù)”變成一種“帶狀態(tài)的自主能力”。我們下面要寫的任務(wù)推進(jìn)助手就會(huì)同時(shí)擁有這三個(gè)層面。為什么不能直接用 Function Calling 解決因?yàn)?Function Calling 的天然邊界是“等用戶問”。它只能被動(dòng)響應(yīng)而一個(gè)會(huì)做任務(wù)管理的 Skill必須在用戶沒有明確說“幫我記任務(wù)”的時(shí)候也知道把關(guān)鍵信息沉淀到記憶里在用戶沒有問“今天有什么待辦”的時(shí)候也能根據(jù)時(shí)間戳和上下文判斷要不要主動(dòng)提醒。這已經(jīng)超出了普通函數(shù)的職責(zé)范圍。1.2 記憶、角色、主動(dòng)性能力層級(jí)逐層遞進(jìn)這三樣?xùn)|西不是并列關(guān)系而是遞進(jìn)關(guān)系。記憶是最底層。沒有記憶Agent 每一次對(duì)話都是“陌生人”。你在星期二告訴它“這個(gè)項(xiàng)目周五要交第一版”到星期四你再問它“我最近忙什么”它應(yīng)該能回憶起這個(gè) deadline。這里的記憶分為兩層短期記憶是當(dāng)前會(huì)話的上下文長(zhǎng)期記憶是跨會(huì)話沉淀下來的用戶偏好和事實(shí)。角色在記憶之上。角色本質(zhì)上是一套行為約束和表達(dá)風(fēng)格。同樣一句話讓同一個(gè)模型扮演“嚴(yán)肅項(xiàng)目經(jīng)理”和“親切的同事”寫出來的任務(wù)提醒完全不一樣。有了角色Skill 的答案才穩(wěn)定而不是每次跟著 prompt 隨機(jī)漂移。主動(dòng)性在最上層。主動(dòng)性不是讓模型像鬧鐘一樣每天定時(shí)亂叫而是讓它擁有“判斷什么時(shí)候該開口”的能力。一個(gè)任務(wù)推進(jìn)助手如果所有提醒都等用戶來問那它根本不叫助手。真正的主動(dòng)觸發(fā)點(diǎn)在工程上是事件驅(qū)動(dòng)的用戶新提了一個(gè)任務(wù)、某個(gè)任務(wù)的截止時(shí)間快到了、用戶連續(xù)兩天沒更新狀態(tài)……這些事件到達(dá)時(shí)Skill 要能自動(dòng)決定要不要打擾用戶。1.3 本項(xiàng)目落地形態(tài)與功能拆解我把示例 Skill 命名為TaskFollowerSkill中文名叫“任務(wù)推進(jìn)助手”。它的能力拆解如下角色一名話不多、但邏輯嚴(yán)謹(jǐn)?shù)捻?xiàng)目推進(jìn)助理。它不替用戶做決定只負(fù)責(zé)幫用戶把任務(wù)拆成可執(zhí)行步驟并追蹤風(fēng)險(xiǎn)。記憶記錄用戶的核心偏好比如“每天提醒不要超過三次”“重要任務(wù)要排序”記錄任務(wù)狀態(tài)和截止時(shí)間。主動(dòng)性當(dāng)檢測(cè)到有任務(wù)在今天到期或者已經(jīng)逾期時(shí)Skill 會(huì)返回一條非用戶主動(dòng)詢問的提醒文本交給 Agent 主循環(huán)推送出去。擴(kuò)展點(diǎn)為了不把事情做復(fù)雜這個(gè)版本我不集成日歷、郵件等外部系統(tǒng)而是把這些都抽象成“外部事件輸入”你在自己的項(xiàng)目里替換成真實(shí)接口即可。下面我們從零開始把這段代碼寫出來。2. 環(huán)境準(zhǔn)備與 Skill 骨架先跑通最小閉環(huán)2.1 安裝依賴與項(xiàng)目目錄先準(zhǔn)備好 Python 環(huán)境。建議用 3.10 以上版本避免類型注解寫法上遇到兼容問題。在任意目錄執(zhí)行mkdir agent-skill-demo cd agent-skill-demo python -m venv .venv source .venv/bin/activate # Windows 下是 .venv\Scripts\activate pip install openai1.0 python-dotenv sentence-transformers numpy這里用到的依賴說明一下openai用來調(diào)用大模型 API我用的是 OpenAI 兼容協(xié)議后續(xù)換成其他兼容服務(wù)也基本不用改代碼。sentence-transformers用來把記憶片段轉(zhuǎn)成向量實(shí)現(xiàn)長(zhǎng)期記憶中的語(yǔ)義檢索。numpy做向量點(diǎn)積計(jì)算。python-dotenv管理 API Key 等環(huán)境變量。目錄結(jié)構(gòu)我建議按能力邊界分文件而不是把 Skill 都堆在一個(gè)文件里agent-skill-demo/ ├── .env ├── main_loop.py # Agent 主循環(huán)負(fù)責(zé)調(diào)度 Skill ├── skills/ │ ├── __init__.py │ ├── base.py # Skill 基類和元數(shù)據(jù)結(jié)構(gòu) │ └── task_follower.py # 任務(wù)推進(jìn)助手 Skill └── memory/ ├── __init__.py ├── vector_store.py # 向量記憶存儲(chǔ)與檢索 └── memory_utils.py # 序列化、加載等輔助函數(shù)這樣分層的理由是memory 模塊不依賴具體 Skill可復(fù)用skills 模塊只依賴 BaseSkill 和 MemoryStore互相解耦。以后你想加第二個(gè) Skill不需要?jiǎng)佑洃浤K的代碼。2.2 Skill 元信息給大模型一張“說明書”Skill 的第一步是定義好它的身份。在大模型驅(qū)動(dòng)的 Agent 里Skill 的 description 不是給人看的而是給調(diào)度器看的。如果描述不清晰模型會(huì)在錯(cuò)誤的場(chǎng)景里調(diào)用它或者在合適的場(chǎng)景里忽略了它。# skills/base.py from __future__ import annotations from dataclasses import dataclass, field from typing import Any, Awaitable, Callable, Optional dataclass class SkillMeta: name: str description: str version: str 1.0 priority: int 100 tags: list[str] field(default_factorylist) # 可選的觸發(fā)條件描述例如“當(dāng)檢測(cè)到用戶提到截止日期時(shí)” trigger_hint: str class BaseSkill: meta: SkillMeta def __init__(self) - None: # 這里預(yù)留 run_hooks不同擴(kuò)展點(diǎn)會(huì)在不同時(shí)機(jī)被調(diào)度器調(diào)用 self.pre_hooks: list[Callable[[], Awaitable[None]]] [] self.post_hooks: list[Callable[[], Awaitable[None]]] [] async def execute(self, user_input: str, context: dict[str, Any]) - str: Skill 的主執(zhí)行入口子類必須實(shí)現(xiàn)。 raise NotImplementedError async def build_context(self, user_input: str) - dict[str, Any]: 執(zhí)行前構(gòu)建上下文包括從記憶里召回相關(guān)內(nèi)容。 raise NotImplementedError async def proactive_check(self, context: dict[str, Any]) - Optional[str]: 主動(dòng)檢查返回需要主動(dòng)推送的文本沒有則返回 None。 return None我特意把proactive_check從execute里拆出來是因?yàn)橹鲃?dòng)性并不總是“用戶剛說完話”的那個(gè)瞬間。Agent 主循環(huán)可以定時(shí)調(diào)用一次或者在其他事件到來時(shí)調(diào)用。這樣 Skill 既是響應(yīng)式的也是事件驅(qū)動(dòng)的。2.3 description 的寫法別寫功能寫場(chǎng)景一個(gè)常見的壞習(xí)慣是把 description 寫成“任務(wù)管理工具用于管理任務(wù)”這種描述對(duì)模型來說信息量太低了。更好的寫法是把“什么時(shí)候不該調(diào)用”也寫進(jìn)去因?yàn)樨?fù)例能顯著降低誤調(diào)用率。舉個(gè)例子TaskFollowerSkill.meta SkillMeta( nametask_follower, description( 當(dāng)用戶提到任務(wù)、待辦、截止日期、提醒、計(jì)劃推進(jìn)時(shí)使用。 它負(fù)責(zé)幫用戶拆分任務(wù)、記錄進(jìn)度和偏好并在截止日期臨近時(shí)主動(dòng)提醒。 如果用戶只是閑聊或者問百科知識(shí)不要調(diào)用本 Skill。 ), version1.0, priority90, tags[task, reminder, memory], trigger_hint新任務(wù)寫入或截止時(shí)間臨近時(shí)返回 proactive 文本, )看起來只是文字問題但實(shí)際影響很大。有一次我在一個(gè)測(cè)試項(xiàng)目里把 description 寫成了“任務(wù)管理工具”結(jié)果用戶問“幫我整理一下今天的會(huì)議地點(diǎn)”模型調(diào)用了任務(wù)管理 Skill卻不知道該提取什么字段輸出了垃圾結(jié)構(gòu)。后來我把觸發(fā)場(chǎng)景寫清楚立刻好很多。這里有一個(gè)元層面的經(jīng)驗(yàn)Skill 的撰寫本質(zhì)是在給模型寫“路由規(guī)則”。description 越接近真實(shí)場(chǎng)景路由就越準(zhǔn)確。3. 核心工程給 Skill 接入長(zhǎng)期記憶3.1 短期記憶與長(zhǎng)期記憶的分工做 Agent 的初期我試過把所有歷史對(duì)話一股腦塞進(jìn)上下文很快發(fā)現(xiàn)兩個(gè)問題一是窗口裝不下二是信息越多模型越容易受無(wú)關(guān)內(nèi)容干擾。所以在任務(wù)推進(jìn)助手里面我們必須把記憶分成兩層短期記憶Session Memory保留當(dāng)前對(duì)話輪次的最近 10 條左右外加完整會(huì)話的壓縮摘要。長(zhǎng)期記憶Long-term Memory跨會(huì)話保存用戶偏好、任務(wù)事實(shí)、重要結(jié)論以結(jié)構(gòu)化記錄落盤。短期記憶很簡(jiǎn)單就是維護(hù)一個(gè)messages列表每次執(zhí)行完把 user 消息和 assistant 回復(fù) append 進(jìn)去。這個(gè)不難。困難的是長(zhǎng)期記憶如何判斷什么值得記住、如何存儲(chǔ)、如何在需要的時(shí)候找回來。3.2 長(zhǎng)期記憶存儲(chǔ)用向量 結(jié)構(gòu)化的雙層結(jié)構(gòu)我推薦的結(jié)構(gòu)是“向量檢索為主結(jié)構(gòu)化字段為輔”。向量負(fù)責(zé)語(yǔ)義召回結(jié)構(gòu)化字段負(fù)責(zé)精確過濾比如按日期、按類型。這樣既避免了純關(guān)鍵詞搜索的呆板也避免了純向量檢索的日期混亂問題。先實(shí)現(xiàn)一個(gè)記憶條目# memory/vector_store.py from __future__ import annotations import json import os import numpy as np from dataclasses import dataclass, field dataclass class MemoryEntry: content: str kind: str fact created_at: str # ISO 格式時(shí)間 due_date: str | None None # 可選例如 2026-02-28 embedding: list[float] field(default_factorylist)每個(gè)字段的解釋content真正需要記憶的一句話比如“用戶偏好每天下午兩點(diǎn)后不打擾”。kind記憶類型。這里我定義了preference、todo、fact三種。類型的作用不是給人看的是給 recall 時(shí)過濾用的。due_date只有todo類型需要填方便做硬性的日期過濾。embedding把 content 向量化后得到的數(shù)組用于語(yǔ)義檢索。注意記憶條目在落盤時(shí)要轉(zhuǎn)成 JSON。numpy.ndarray不能直接被 json 序列化所以我統(tǒng)一存list類型class MemoryStore: def __init__(self, path: str memory_store.jsonl): self.path path os.makedirs(os.path.dirname(self.path), exist_okTrue) def _to_dict(self, entry: MemoryEntry) - dict: return { content: entry.content, kind: entry.kind, created_at: entry.created_at, due_date: entry.due_date, embedding: entry.embedding, } def _append(self, entry: MemoryEntry) - None: with open(self.path, a, encodingutf-8) as f: f.write(json.dumps(self._to_dict(entry), ensure_asciiFalse) \n)用 JSONL 而不是單個(gè) JSON 文件是因?yàn)槊織l追加寫入的方式最簡(jiǎn)單崩潰恢復(fù)也容易生產(chǎn)環(huán)境如果量大再替換成 SQLite 或?qū)ｉT的向量數(shù)據(jù)庫(kù)即可。3.3 embedding 計(jì)算與語(yǔ)義召回接下來是向量化。我是用本地方案避免每次調(diào)遠(yuǎn)程 embedding 服務(wù)的延遲和成本。模型我選擇了BAAI/bge-small-zh-v1.5體積小中文效果足夠用。模型第一次加載會(huì)比較慢所以我用模塊級(jí)單例避免重復(fù)加載。# memory/vector_store.py 追加 from sentence_transformers import SentenceTransformer _model None def get_embedding(text: str) - np.ndarray: global _model if _model is None: _model SentenceTransformer(BAAI/bge-small-zh-v1.5) embedding _model.encode(text, normalize_embeddingsTrue) return np.asarray(embedding, dtypenp.float32)為什么要 normalize因?yàn)楹竺嬗命c(diǎn)積表示余弦相似度時(shí)歸一化之后可以直接算q emb省去一次除法。大多數(shù) embedding 模型都會(huì)建議歸一化如果有精度問題可以檢查一下是否做了這一步。召回邏輯如下def recall(self, query: str, top_k: int 3, kind: str | None None) - list[dict]: if not os.path.exists(self.path): return [] query_emb get_embedding(query) scored [] with open(self.path, r, encodingutf-8) as f: for line in f: line line.strip() if not line: continue row json.loads(line) if kind and row.get(kind) ! kind: continue emb np.asarray(row[embedding], dtypenp.float32) score float(query_emb emb) scored.append((score, row)) scored.sort(keylambda x: x[0], reverseTrue) return [row for score, row in scored[:top_k] if score 0.35]這里的閾值 0.35 不是拍腦袋定的而是我用一小批測(cè)試句子調(diào)出來的低于這個(gè)值召回的條目經(jīng)常和當(dāng)前意圖完全無(wú)關(guān)高于 0.5很多相關(guān)的偏好又漏掉了。不同 embedding 模型閾值不一樣你換模型后必須重新做一次范圍測(cè)試。召回之后怎么用在 Skill 的build_context中我按類型分別召回。召回 preference 是為了構(gòu)建系統(tǒng)人設(shè)召回 fact 是為了給模型補(bǔ)充背景召回 todo 是為了在主動(dòng)檢查時(shí)用。4. 注入角色再給 Skill 裝上“主動(dòng)性”4.1 角色提示詞不寫空話寫決策偏好角色本身并不神秘它就是一段 system prompt。但這里有個(gè)反直覺的點(diǎn)角色 prompt 不是越長(zhǎng)越像人而是越能影響具體輸出越好。比如“你是一位耐心的助手”這種話模型很難根據(jù)它做出行為差異但“當(dāng)用戶表現(xiàn)出焦慮時(shí)先共情再給建議”就能影響行為。我為任務(wù)推進(jìn)助手寫的角色原則是你是“小助”一名任務(wù)推進(jìn)助理。你說話風(fēng)格簡(jiǎn)潔不廢話不客套。 你的工作信條 1. 把模糊目標(biāo)拆成下一步行動(dòng)而不是只給宏大建議。 2. 記住用戶的偏好并主動(dòng)調(diào)用記憶里的信息來調(diào)整表達(dá)方式。 3. 當(dāng)發(fā)現(xiàn)任務(wù)有截止日期的風(fēng)險(xiǎn)時(shí)直接點(diǎn)出風(fēng)險(xiǎn)不拐彎抹角。 4. 每天主動(dòng)提醒不超過三次除非用戶明確要求更頻繁。注意第三條和第四條它們?cè)诤竺鏁?huì)被工程邏輯影響。角色 prompt 決定了模型“輸出什么氣質(zhì)”工程邏輯決定了模型“在什么情況下開口”。兩者配合才叫有主動(dòng)性的 Skill光靠 prompt 里的“你要主動(dòng)”沒有用。把記憶注入角色 prompt 的方式def _build_system_prompt(self, mem_rows: list[dict]) - str: if mem_rows: lines \n.join( f- {row[content]} for row in mem_rows[:8] ) user_memory_section f\n用戶的重要信息\n{lines} else: user_memory_section \n用戶的重要信息暫無(wú)。 return ROLE_TEMPLATE user_memory_section這里有個(gè)約束召回的記憶不能全塞進(jìn)去最多 8 條。否則長(zhǎng)的記憶會(huì)讓 system prompt 變得很臃腫既浪費(fèi) token又會(huì)讓模型抓不住重點(diǎn)。4.2 如何判斷要不要“主動(dòng)開口”主動(dòng)性先要定義一個(gè)“觸發(fā)檢查”。我把觸發(fā)場(chǎng)景拆成兩類規(guī)則型觸發(fā)代碼判斷比如“任務(wù) due_date 等于今天/已逾期”這種判斷必須交給代碼不能讓模型去算日期。語(yǔ)義型觸發(fā)需要理解上下文比如“用戶提到某個(gè)項(xiàng)目而這個(gè)項(xiàng)目在記憶里已經(jīng)有待辦”這種判斷由模型做。真實(shí)項(xiàng)目里兩者要結(jié)合。我簡(jiǎn)化成一個(gè)proactive_checkasync def proactive_check(self) - str | None: today datetime.now().strftime(%Y-%m-%d) overdue_items [] for row in self.memory.iter_all(kindtodo): due_date row.get(due_date) if not due_date: continue if due_date today: overdue_items.append(row) if not overdue_items: return None messages [] for item in overdue_items[:3]: messages.append(f任務(wù){(diào)item[content]}截止時(shí)間{item[due_date]}) return 主動(dòng)提醒你有任務(wù)需要關(guān)注。\n \n.join(messages)這段代碼的關(guān)鍵是日期比較用字符串是因?yàn)?ISO 格式Y(jié)YYY-MM-DD的字典序和真實(shí)時(shí)間順序一致不需要額外轉(zhuǎn) datetime。這個(gè)細(xì)節(jié)很實(shí)用。不過只靠規(guī)則會(huì)有 bug比如用戶說“下周二前給我初稿”模型并不一定會(huì)把 due_date 填對(duì)。所以在保存任務(wù)時(shí)我會(huì)先調(diào)用一次大模型做一個(gè)抽取動(dòng)作把自然語(yǔ)言里的截止時(shí)間轉(zhuǎn)成 ISO 格式再寫入記憶。4.3 Skill 的完整實(shí)現(xiàn)與調(diào)用鏈路現(xiàn)在把角色、記憶、主動(dòng)性串起來。下面是TaskFollowerSkill的核心代碼# skills/task_follower.py from __future__ import annotations import json from datetime import datetime from .base import BaseSkill, SkillMeta from memory.vector_store import MemoryStore, get_embedding ROLE_TEMPLATE 你是“小助”一名任務(wù)推進(jìn)助理。你說話風(fēng)格簡(jiǎn)潔不廢話不客套。 你的工作信條 1. 把模糊目標(biāo)拆成下一步行動(dòng)而不是只給宏大建議。 2. 記住用戶的偏好并主動(dòng)調(diào)用記憶里的信息來調(diào)整表達(dá)方式。 3. 當(dāng)發(fā)現(xiàn)任務(wù)有截止日期的風(fēng)險(xiǎn)時(shí)直接點(diǎn)出風(fēng)險(xiǎn)不拐彎抹角。 4. 每天主動(dòng)提醒不超過三次除非用戶明確要求更頻繁。 class TaskFollowerSkill(BaseSkill): meta SkillMeta( nametask_follower, description( 當(dāng)用戶提到任務(wù)、待辦、截止日期、提醒、計(jì)劃推進(jìn)時(shí)使用。 它負(fù)責(zé)幫用戶拆分任務(wù)、記錄進(jìn)度和偏好并在截止日期臨近時(shí)主動(dòng)提醒。 如果用戶只是閑聊或者問百科知識(shí)不要調(diào)用本 Skill。 ), version1.0, priority90, ) def __init__(self, llm_client): super().__init__() self.llm llm_client self.memory MemoryStore(memory_store.jsonl) def _save_preference_from_text(self, text: str): # 實(shí)踐中這里會(huì)讓 LLM 判斷是否值得記再?zèng)Q定寫入。 # 為了演示簡(jiǎn)單我用一個(gè)規(guī)則當(dāng)包含“我喜歡/我不喜歡/盡量/別”時(shí)寫入。 if any(kw in text for kw in [我喜歡, 我不喜歡, 盡量, 別, 不要]): self.memory.save( contenttext.strip(), kindpreference ) async def build_context(self, user_input: str) - dict: prefs self.memory.recall(用戶的偏好, kindpreference, top_k3) facts self.memory.recall(user_input, kindfact, top_k3) return {prefs: prefs, facts: facts} async def execute(self, user_input: str, context: dict | None None) - str: context context or await self.build_context(user_input) system_prompt ROLE_TEMPLATE if context[prefs]: system_prompt \n用戶相關(guān)偏好 for m in context[prefs]: system_prompt f\n- {m[content]} # 調(diào)用大模型讓助手給出回應(yīng) messages [ {role: system, content: system_prompt}, {role: user, content: user_input}, ] reply await self.llm.chat(messages) # 抽取可能存在的任務(wù)/偏好并寫入長(zhǎng)期記憶 self._save_preference_from_text(user_input) return reply你要注意execute 返回給用戶的是模型的回復(fù)但它私下還會(huì)悄悄做兩件事檢索偏好、寫入新偏好。這就是“記憶”的開始。那么主動(dòng)性是怎么被調(diào)用的是在 main loop 里。注意主循環(huán)不能只在用戶發(fā)消息后調(diào)用proactive_check還要周期性地調(diào)用一次。最簡(jiǎn)單的方式是讓 main loop 每次處理用戶請(qǐng)求前都先檢查一次同時(shí)后臺(tái)定時(shí)任務(wù)每 30 分鐘也檢查一次。為了不打擾用戶我可以在 Skill 內(nèi)維護(hù)一個(gè)“今天已提醒次數(shù)”的計(jì)數(shù)超過三次就不再觸發(fā)這個(gè)計(jì)數(shù)邏輯需要落到一個(gè)狀態(tài)文件里重啟程序后才能保留。# main_loop.py 片段 async def run_once(skill: TaskFollowerSkill, user_msg: str): # 在執(zhí)行用戶消息前先看有沒有需要主動(dòng)提醒的內(nèi)容 proactive await skill.proactive_check() if proactive: print([主動(dòng)提醒], proactive) # 再執(zhí)行主任務(wù) context await skill.build_context(user_msg) answer await skill.execute(user_msg, context) print([助手], answer)看到?jīng)]有這只是在用戶開口前進(jìn)實(shí)際上就體現(xiàn)出了 Skill 的主動(dòng)性。更進(jìn)一步如果你的 Agent 跑在群聊或自動(dòng)任務(wù)平臺(tái)上可以加一個(gè) cron 觸發(fā)器每 10 分鐘調(diào)用一次proactive_check。這里不一定要做很重的調(diào)度系統(tǒng)把主動(dòng)性做成 Skill 的一個(gè)方法剩下的就是外部什么時(shí)候想叫它的問題。5. 調(diào)試實(shí)錄把容易踩的坑一次說清5.1 大模型會(huì)把“偏好”和“事實(shí)”混為一談我早期把偏好數(shù)據(jù)全存成了fact后來發(fā)現(xiàn)召回時(shí)背景信息和用戶偏好混在一起導(dǎo)致模型在生成回復(fù)時(shí)把偏好當(dāng)成客觀事實(shí)做出錯(cuò)誤的推斷。比如用戶說“我不喜歡太長(zhǎng)的提醒”模型如果沒有區(qū)分出這句話是 preference可能把“提醒不能太長(zhǎng)”理解成任務(wù)內(nèi)容回復(fù)風(fēng)格就亂了。解決方法是給recall加kind參數(shù)并用“用戶偏好”作為查詢?cè)~去召回。你可以做一個(gè)簡(jiǎn)單的對(duì)照實(shí)驗(yàn)把同一句話分別按fact和preference保存然后召回“用戶的偏好”高分的命中基本是preference類型的這證明類型過濾是有效且必要的。5.2 向量檢索對(duì)短句不敏感長(zhǎng)句反而有用embedding 適合做語(yǔ)義相似度但它不是萬(wàn)能的。我發(fā)現(xiàn)如果讓用戶輸入“提醒我周五交周報(bào)”然后直接拿這個(gè)整句去向量庫(kù)里召回往往匹配不到歷史偏好“用戶習(xí)慣周五上午交周報(bào)”因?yàn)閮蓚€(gè)句子的表面形式差得有點(diǎn)遠(yuǎn)。更穩(wěn)的做法不是拿原始輸入做 query而是先用大模型把用戶的輸入轉(zhuǎn)成“記憶檢索詞”。也就是說與其問向量庫(kù)“提醒我周五交周報(bào)”不如問“用戶周五有哪些交材料的習(xí)慣”這樣召回的準(zhǔn)確率會(huì)高不少。我在build_context里加上了一步調(diào)用模型生成短檢索詞再執(zhí)行記憶召回。多了這一步延遲但效果提升非常大值得為它多花一兩秒。5.3 主動(dòng)性觸發(fā)不能只看“日期 今天”還要考慮時(shí)區(qū)“今天”是一個(gè)隨時(shí)間變化的概念。如果你的 Agent 部署在服務(wù)器上服務(wù)器時(shí)區(qū)可能和用戶時(shí)區(qū)不一樣。比如服務(wù)器 UTC 時(shí)間是 2 月 28 日 16 點(diǎn)國(guó)內(nèi)已經(jīng)是 2 月 29 日 0 點(diǎn)一個(gè)在 2 月 29 日截止的任務(wù)就會(huì)因?yàn)榕袛噙壿嬇茉?UTC 時(shí)區(qū)而錯(cuò)誤地“還不是今天”。我的方案是把截止時(shí)間統(tǒng)一按用戶時(shí)區(qū)存儲(chǔ)并在比較今天日期時(shí)指定用戶時(shí)區(qū)from zoneinfo import ZoneInfo def get_user_today(user_tz: str Asia/Shanghai) - str: return datetime.now(ZoneInfo(user_tz)).strftime(%Y-%m-%d)別小看這個(gè)細(xì)節(jié)很多遠(yuǎn)程提醒類 Avatar 早期版本出錯(cuò)最后查下來全是時(shí)區(qū)問題。把日期處理的邊界釘死比增加各種提示詞更能保證可靠性。5.4 上下文里塞太多召回內(nèi)容模型會(huì)“迷路”我剛做這個(gè) Skill 時(shí)覺得召回越多越好模型知識(shí)多總比少好。測(cè)試后發(fā)現(xiàn)完全不是這樣。系統(tǒng) prompt 加了一堆記憶之后模型在處理簡(jiǎn)單任務(wù)時(shí)反而會(huì)“過度引用”歷史信息比如用戶單純問“把簡(jiǎn)報(bào)發(fā)我”它居然會(huì)把以前記的“用戶喜歡用紅色標(biāo)題”這種偏好強(qiáng)行塞進(jìn)回復(fù)里。后來我把召回?cái)?shù)量限制得很嚴(yán)格偏好最多 3 條事實(shí)最多 5 條且每條后面標(biāo)注類型和觸發(fā)場(chǎng)景。模型反而表現(xiàn)更好。記憶系統(tǒng)最重要的是做減法不是做加法這條經(jīng)驗(yàn)同樣適用于幾乎所有的 Agent 系統(tǒng)。5.5 標(biāo)準(zhǔn)問題排查速查表現(xiàn)象可能原因排查與解決模型在無(wú)關(guān)場(chǎng)景調(diào)用 Skilldescription 寫得太寬泛補(bǔ)充負(fù)面觸發(fā)條件如“閑聊時(shí)不要調(diào)用”記憶召回結(jié)果和主題不相關(guān)閾值過低或 query 不精準(zhǔn)提高閾值先用 LLM 生成檢索詞再召回主動(dòng)提醒永遠(yuǎn)不觸發(fā)時(shí)區(qū)不同導(dǎo)致日期判斷錯(cuò)統(tǒng)一用用戶時(shí)區(qū)判斷“今天”模型記住了不該記的信息缺少記憶寫入審批環(huán)節(jié)保存前讓 LLM 判斷是否值得記并限制 content 長(zhǎng)度長(zhǎng)期記憶文件越來越大JSONL 只追加沒有合并去重定期壓縮對(duì)重復(fù)記憶按向量相似度合并Skill 重啟后主動(dòng)提醒計(jì)數(shù)丟失計(jì)數(shù)只存在內(nèi)存中把每天提醒次數(shù)寫入本地狀態(tài)文件這是我在跑這個(gè)演示項(xiàng)目時(shí)遇到的最典型的六個(gè)問題基本覆蓋了從路由、記憶到主動(dòng)性的全過程。當(dāng)你把它擴(kuò)展到自己的項(xiàng)目時(shí)如果場(chǎng)景復(fù)雜建議先單獨(dú)測(cè)試記憶召回再測(cè)試主動(dòng)觸發(fā)不要一上來就連起來調(diào)否則很難定位問題出在哪個(gè)環(huán)節(jié)。6. 向前一步把 Skill 升級(jí)成真正可落地的 Agent 能力到這你已經(jīng)有了一個(gè)會(huì)記憶、會(huì)扮演角色、會(huì)主動(dòng)檢查任務(wù)的 Skill。但如果你想把它接到生產(chǎn)環(huán)境我認(rèn)為接下來要補(bǔ)三塊工作。第一給記憶系統(tǒng)加上合并更新能力。當(dāng)前演示是每次都追加一條記憶里面容易有重復(fù)。實(shí)際操作中當(dāng)向量召回發(fā)現(xiàn)相似度大于 0.9 的已有條目時(shí)應(yīng)該替換舊條目而不是新增。你可以使用一個(gè)簡(jiǎn)單的去重函數(shù)def upsert(self, entry: MemoryEntry) - None: similarities self._search(entry.content, top_k1) if similarities and similarities[0][score] 0.9: # 更新相似條目 self._delete_by_content(similarities[0][content]) self._append(entry)第二主動(dòng)性觸發(fā)要做“抑制機(jī)制”。如果你希望 Skill 每天早上 9 點(diǎn)主動(dòng)提醒一次那么必須有觸發(fā)狀態(tài)控制否則用戶在 9 點(diǎn)整正好發(fā)了條消息主循環(huán)調(diào)用一次proactive_check后臺(tái)任務(wù)再調(diào)用一次就會(huì)重復(fù)打擾。解決方式是在 Skill 內(nèi)維護(hù)一個(gè)“最后一次主動(dòng)提醒時(shí)間”的字段兩次提醒之間至少間隔 4 小時(shí)。第三把 Skill 的輸入從“單條文本”擴(kuò)展為“結(jié)構(gòu)化事件”。比如日歷同步、郵件到達(dá)、代碼倉(cāng)庫(kù) push這些都是外部事件。你可以在參數(shù)里加入event_type和event_data讓 Skill 在不同事件下走不同的處理分支。這一步做完你就不再只是做一個(gè)“聊天工具”而是真正把 Agent 嵌進(jìn)工作流里了。我在實(shí)際測(cè)試這個(gè) Skill 時(shí)最明顯的感覺是它開始像一個(gè)“有審美的同事”了。它不是每次都有問必答而是在合適的時(shí)間打擾你它能記得你說過的話并且用你舒服的方式回應(yīng)。當(dāng)你把這三層能力加到任意 Skill 上你寫的就不再是“一段 API 調(diào)用”而是一個(gè)有自己工作方式的數(shù)字員工。最后提醒一句啟動(dòng)新項(xiàng)目時(shí)別急著堆功能先把記憶召回和主動(dòng)檢查這兩個(gè)循環(huán)調(diào)穩(wěn)整體體驗(yàn)一定會(huì)超過你預(yù)期。