1. 从一次营销系统重构说起五大实体为什么必须统一建模做全域智能营销系统最怕的不是模型不够强而是数据各管各的。我见过太多团队用户表在 CRM 里叫customer在企微侧叫external_contact在会话服务里又变成visitor_id等到要做跨渠道触达时发现根本对不上号。Agent 想记住用户偏好结果每次对话都像第一次见面想复用一套技能结果每个渠道各写一份 prompt。这套系统的核心检索词就是 User、Session、Memory、Skill、Task 五大实体。User 负责身份统一Session 负责对话生命周期Memory 负责跨会话记忆Skill 负责可复用能力Task 负责执行追踪。它们能做什么简单说就是让营销 Agent 在多工具协作场景下做到身份可打通、状态可恢复、记忆可检索、技能可进化、任务可审计。适合谁适合正在从单点脚本走向平台化 Agent 的工程团队尤其是需要同时对接飞书、钉钉、企微、Telegram 这类多渠道的营销中台。这篇不讲空泛架构直接给可落地的数据模型、可复制的 TaoToken 配置骨架以及连通性验证动作。你跟着做至少能把五大实体的数据流转链路跑通并且每一步都能追踪到具体是哪个实体、哪个字段在起作用。2. TaoToken 前置统一 Key 与 API 通道的配置骨架在写实体代码之前先把模型调用通道统一。多工具协作场景下最乱的就是每个服务各自配一套 Key出了问题不知道是谁在调。TaoToken 的作用就是提供一个统一的 API 通道让 User、Session、Memory、Skill、Task 五个模块共用同一套鉴权配置。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不加 UTM 参数直接用于代码里的 base_url。你需要先拿到 Key。进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制保存。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例。配置分两处settings.json用于应用层读取config.toml用于本地开发或 CLI 工具。两者保持同一个 Key 和同一个 base_url避免出现“测试环境能跑、生产环境 401”的经典问题。3. 可复制配置settings.json 与 config.toml 双份骨架3.1 settings.json 配置这个文件放在项目根目录或配置中心五个实体模块统一读取taotoken节点。{ taotoken: { api_key: sk-你的TaoTokenKey, base_url: https://taotoken.net/api, default_model: claude-sonnet-4-20250514, timeout_seconds: 60, max_retries: 3 }, entities: { user: { oneid_field: unified_user_id, channel_mapping: [feishu, dingtalk, wecom, telegram] }, session: { state_machine: [INIT, ACTIVE, PAUSED, CLOSED, ERROR], idle_pause_minutes: 30 }, memory: { layers: [redis, mysql, object_storage], embedding_dim: 1536, top_k: 10 }, skill: { standard: agentskills.io, sources: [manual, auto_generated, community] }, task: { max_parallel_subtasks: 3, tree_enabled: true } } }关键点api_key和base_url只在这里出现一次其他模块通过配置读取器获取不要在每个实体服务里硬编码。3.2 config.toml 配置如果你用 CLI 工具或本地调试config.toml更顺手。[taotoken] api_key sk-你的TaoTokenKey base_url https://taotoken.net/api default_model claude-sonnet-4-20250514 timeout_seconds 60 max_retries 3 [taotoken.headers] X-Entity-Source uni-mdp X-Trace-Enabled true [entities.user] oneid_field unified_user_id channels [feishu, dingtalk, wecom, telegram] [entities.session] states [INIT, ACTIVE, PAUSED, CLOSED, ERROR] idle_pause_minutes 30 [entities.memory] layers [redis, mysql, object_storage] embedding_dim 1536 top_k 10 [entities.skill] standard agentskills.io sources [manual, auto_generated, community] [entities.task] max_parallel_subtasks 3 tree_enabled trueX-Entity-Source和X-Trace-Enabled这两个 header 是我建议加的后面排查问题时能直接看出请求来自哪个实体模块省去翻日志的时间。3.3 五大实体与配置项的对应关系实体核心字段配置节点作用Userunified_user_id, multi_platform_idsentities.userOneID 打通多渠道身份映射Sessionsession_id, status, contextentities.session状态机驱动对话生命周期Memorymemory_id, memory_type, embeddingentities.memory三层存储与混合检索Skillskill_id, trigger_conditions, action_rulesentities.skill可复用能力定义与进化Tasktask_id, parent_task_id, statusentities.task树形结构追踪与 Subagent 编排这张表建议直接放进你的设计文档后面每加一个字段先问它属于哪个实体、对应哪个配置节点。4. 验证请求确认五大实体数据流转可追踪配置写完后不要急着写业务逻辑先做连通性验证。目标是确认三件事Key 有效、base_url 可达、实体标识能透传。4.1 用 curl 做最小验证curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoTokenKey \ -H X-Entity-Source: user \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回里有正常的content字段说明通道没问题。注意X-Entity-Source这里填user你可以依次换成session、memory、skill、task确认五个实体标识都能正常透传。4.2 Python 验证脚本import json import requests with open(settings.json, r, encodingutf-8) as f: cfg json.load(f)[taotoken] def verify_entity(entity_name: str): resp requests.post( f{cfg[base_url]}/v1/messages, headers{ Content-Type: application/json, x-api-key: cfg[api_key], X-Entity-Source: entity_name, }, json{ model: cfg[default_model], max_tokens: 32, messages: [{role: user, content: ping}], }, timeoutcfg[timeout_seconds], ) print(entity_name, resp.status_code, resp.json().get(content, )[:40]) for e in [user, session, memory, skill, task]: verify_entity(e)跑完这个脚本你会看到五行输出每行对应一个实体的请求状态。如果某个实体返回 401说明 Key 没读到如果返回 404检查 base_url 是不是多写了斜杠。4.3 成功结果长什么样正常输出类似user 200 [{type: text, text: OK}] session 200 [{type: text, text: OK}] memory 200 [{type: text, text: OK}] skill 200 [{type: text, text: OK}] task 200 [{type: text, text: OK}]五个实体全部 200说明统一 Key 和 API 通道已经打通。接下来你在 User 表里插入一条记录在 Session 表里关联 user_id在 Memory 表里写入一条 fact在 Skill 表里注册一个技能在 Task 表里创建一个根任务整条链路的数据流转就有了可追踪的基础。5. 本篇常见错排查5.1 401 Unauthorized最常见的原因是 Key 没读到。检查settings.json里的api_key字段名是不是写成了apiKey或key代码里读取的路径要和文件结构完全一致。另一个原因是 Key 复制时带了空格建议用strip()处理一下。5.2 404 Not Foundbase_url 写成https://taotoken.net/api/末尾带斜杠再拼接/v1/messages就会变成双斜杠。统一用https://taotoken.net/api拼接时用rstrip(/)处理。5.3 实体标识丢失如果你在网关层做了转发X-Entity-Source可能被过滤掉。检查网关的 header 白名单把自定义 header 加进去。这个字段丢了不影响请求成功但后面排查问题时你会不知道请求来自哪个实体。5.4 超时设置过短营销场景下 Memory 检索和 Skill 加载可能耗时较长timeout_seconds建议不低于 60。如果经常超时先看是不是 Memory 的 embedding 计算拖慢了整体链路而不是盲目加大超时。5.5 配置双份不一致settings.json和config.toml里的 Key 或 base_url 不一致导致本地能跑、容器里跑不通。建议把这两个文件放在同一个配置仓库用 CI 检查关键字段是否一致。6. 下一步把配置骨架接进实体代码配置和验证做完后你可以按这个顺序接入先写 User 的 OneID 解析再写 Session 的状态机然后接 Memory 的三层存储接着注册第一个 Skill最后用 Task 把整个链路串起来。每一步都用上面那个验证脚本确认实体标识能透传。如果你要长期跑编码类 Agent 或做多任务编排可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有按任务量分档的配置建议。需要直接对话验证模型效果的走模型对话入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。Key 管理和接入文档分别在这里API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。我自己的习惯是每加一个实体字段就回头跑一次五实体验证脚本。看起来笨但能保证数据模型在扩展时不会悄悄断掉某条链路。