Nexent 智能体集成（五大方向）

配套平台版本：2.4.0（接口/字段/端口均以该版本为准；跨版本使用请先以各服务 /openapi.json 实测校准）。

整合华为开源 ModelEngine Nexent 智能体平台的全部对接经验，分为五大方向：

| 方向 | 内容 | 参考文档 | |---|---|---| | 方向一：北向接口调用 | 从外部 Web 系统调用智能体：agent 发现、POST /nb/v1/chat/run、SSE 流式、Bearer 鉴权、conversation_id 追问、附件/文件上传（/nb/v1/chat/attachments/upload + 知识库文件上传） | references/01-northbound-api.md | | 方向二：流式输出经验 | SSE 事件协议本质（thinking 增量/final_answer 一次性）、conversation_id 响应头、协议层踩坑（空请求体 422/conversation_id 误渲染）、提示词契约；前端呈现（三层架构/滚动三态/图表 init/弹窗解耦/真实浏览器验证）详见 ui-browser-testing 技能 streaming-ui.md | references/02-streaming-guide.md + ui-browser-testing/streaming-ui.md | | 方向三：远程操控提示词与发布 | 管理 API（登录 session 鉴权、agent_id 查询、search_info/update、技能管理 API（/api/skills 创建/上传/更新/scan_skill/nl2skill + 脚本型技能 run_skill_script 执行机制）、版本 publish 递增与命名规则） | references/03-admin-api.md + scripts/nexent_agent.py | | 方向四：MCP 工具接入与联调 | API 转 MCP（/tool/openapi_service）、工具扫描/绑定、MCP 仓库注册（/api/mcp/add）、接入已有远程 MCP 服务器（healthcheck/tools/refresh-tools）、config_json 补配置、SSE 协议探测、OpenAPI 对接与裁剪、端口速查 | references/04-mcp.md | | 方向五：加载与调用原理 | 提示词草稿/发布两态、技能渐进式加载（read_skill_md 命中后读全文）、工具绑定与 thinking 可见调用、技能命中验证方法论、技能使用规则 prompt 模板 | references/05-prompt-skill-tool-loading.md |

🔎 接口探查方法论（铁律：文档优先 → 源码兜底）

遇到接口问题，先查官方 API 文档，调试不通再解析源码——不要一上来就翻 GitHub。

位置速查：源码仓库 https://github.com/ModelEngine-Group/nexent（main）；运行环境 API 文档 = 各服务端口 /openapi.json（示例部署 3000/5010/5013，端口由部署决定，勿假设默认）；前端端点常量 frontend/services/api.ts（API_ENDPOINTS）+ frontend/const/*.ts；后端路由 backend/apps/*.py、模型 backend/consts/model.py、实现 backend/services/*.py。

文档优先：① 平台官方文档/帮助 → ② 环境内 /openapi.json（最权威的本环境接口清单）→ ③ 前端 frontend/services/api.ts 的 API_ENDPOINTS（前端真实调用 URL）→ ④ 仓库 docs/
源码兜底（文档缺失/过时/与实际不符时）：backend/apps/*.py 路由（确认真实路径与 prefix）→ backend/consts/model.py（请求/响应模型字段）→ backend/services/*.py（行为实现，如 update 注释 "agent_id is None → create"）→ frontend/services/*.ts（前端怎么调）
GitHub 拉取用 api.github.com trees/contents API（秒级），不下载整包 zip

本技能中标注「源码确认」的结论均为此流程的实战产出，可直接复用。详见 references/03-admin-api.md「接口探查方法论」。

⚠️ 两套鉴权（最易混淆，务必区分）

| 场景 | 鉴权方式 | 用途 | |---|---|---| | 北向接口（方向一） | Authorization: Bearer <北向 API Key> | 调用智能体对话（chat/run、agents 列表） | | 管理接口（方向三） | Authorization: Bearer <登录 session JWT>（北向 API Key 无效！） | 查询/更新提示词、发布版本 |

管理接口的 JWT 获取：POST {BASE}/api/user/signin body {"email","password"}，从响应 Set-Cookie: nexent_access_token=<JWT> 提取。

方向一：北向接口调用（Quick Start）

# 1. 发现智能体(可选)
# ⚠️ 北向 API 与管理门户端口不同：实测环境 管理门户=:3000、北向=:5013（均为示例值，具体端口由你的部署决定）
#    {NEXENT_BASE_URL} 此处应填北向 base(如 http://<host>:5013), 不是管理门户 3000(3000 的 /nb/v1/* 是前端门户会 404/307)
curl -s "{NEXENT_NORTHBOUND_BASE_URL}/nb/v1/agents" -H "Authorization: Bearer <API_KEY>"

# 2. 发起对话(SSE 流式响应)
curl -s -N -X POST "{NEXENT_BASE_URL}/nb/v1/chat/run" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{"agent_name":"<agentName>","query":"<用户问题>"}'

# 3. 追问: 从响应头取 conversation_id, 传回即可延续会话
curl -s -N -X POST "{NEXENT_BASE_URL}/nb/v1/chat/run" \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"agent_name":"<agentName>","conversation_id":"<上轮id>","query":"追问内容"}'

完整协议、端点、错误处理见 references/01-northbound-api.md。

方向二：流式输出经验（要点速记）

thinking 事件：逐字增量 → 前端须累积拼接（不逐帧取末段，否则 1-2 字闪现）
final_answer 事件：一次性完整（非增量）→ 到达后整体处理
conversation_id：在响应头（非 SSE 事件体），只读不渲染进答案
协议层踩坑：空请求体 → 422 → [object Object]（对象展开丢键）；conversation_id 误渲染进答案（重复分支）
前端呈现（三层架构/滚动三态/图表 init 时机/关闭弹窗不中断/真实浏览器验证）详见 ui-browser-testing 技能 streaming-ui.md——本技能只负责协议对不对，渲染对不对由 UI 测试技能覆盖
⚠️ 铁律：前端交付必须真实浏览器渲染验证（JSON 正确 ≠ 渲染正确）
完整协议/契约层踩坑与跨技能索引见 references/02-streaming-guide.md

方向三：远程操控提示词与发布（要点速记）

使用前先向用户追问基础信息（与方向一相同原则，不假设）：① 管理 API base URL（部署方提供的完整地址，端口由部署决定、无固定默认值，实测环境为 http://<host>:3000 但不要假设 3000；同理北向端口实测环境为 5013）；② 登录邮箱/密码（从部署方获取，交互输入或环境变量注入，禁止硬编码）；③ 北向 API Key（形如 nexent-xxx，调用北向接口时用）；④ 当前环境能否直连该管理 API。详见 references/03-admin-api.md 的 Required Values。

⚠️ 铁律：模型/知识库只在【创建】智能体时由用户显式选择；【更新】智能体自动沿用现有配置，不再询问

创建闸门（强制交互）：任何 agent create 调用之前，必须 GET /api/model/list 拉列表 → 用 AskUserQuestion 展示给用户 → 拿到显式选择的 model_id 才能继续。禁止硬编码 model_id、禁止取默认值、禁止"先建完再问"。

更新自动沿用（不询问）：agent update 不询问模型，直接沿用 search_info 返回的 model_ids（如 [7463]）→ update["model_id"] = model_ids[0]、update["model_ids"] = model_ids。创建时的选择是"一次性决策"，后续迭代不重复打扰用户。

写自动化部署脚本也必须遵守：不要把 create 压成无交互单脚本并硬编码 model_ids——Phase 1 先交互收集（模型/知识库/提示词），Phase 2 才执行。本技能自带 nexent_agent.py create 已内置 input("请选择模型 ID...") 闸门，优先用它而非自写硬编码脚本。

反模式：为图快把部署写成 deploy.py 单脚本、硬编码 deepseek-v4-pro，未让用户选模型，事后补救换模型重 publish。根因=软指令被"交付惯性"覆盖、且绕过技能自带交互 CLI。

模型列表：GET /api/model/list（⚠️ 响应含明文 api_key，只取 model_id/display_name/model_type 展示）

知识库列表：GET /api/indices → {"indices": ["<index_name哈希>", ...]}（⚠️ 仅返回索引哈希串，本版本管理 API 无任何端点返回知识库可读名称——名称只存在于平台「知识库管理」UI；RAGFlow/AIDP/iData 为外部代理需单独 api_base+api_key。向用户列候选时必须标注"这是索引哈希、名称请到 UI 核对"，禁止只甩哈希）

挂知识库 = 配置 knowledge_base_search 工具实例的 params 数组中 index_names 元素的 default（⚠️ params 是 param 描述数组非字典；update 后 publish）

MCP 接入硬闸门：任何 POST /api/mcp/add（远程 MCP）/ API 转 MCP / 绑定资源（tool/update）之前，必须先列候选 MCP（名称/用途/传输/是否需隧道）让用户选，或用 AskUserQuestion 确认 server_url 与目标资源——禁止默认挑一个、禁止硬编码 server_url 直接 add。MCP 接入涉及外部网络可达性决策，本质是用户选择点。

破坏性操作确认闸门：任何 DELETE（删智能体 DELETE /api/agent、删技能 DELETE /api/skills/{name}、删会话 DELETE /api/conversation/{id}、删版本 DELETE /api/agent/{id}/versions/{no}）不可逆，执行前必须用 AskUserQuestion 让用户显式确认"删哪个 + 是否确认"——禁止静默/默认删除（即便会话清理有"先建后删+快照对比"规则，删除那步仍需确认）。

# 内置 CLI(自动登录/字段回填/版本递增; 邮箱/密码未提供时交互输入)
# <base_url> 为部署方提供的完整管理 API 地址(端口由部署决定, 示例 3000, 勿假设默认)
python scripts/nexent_agent.py list   <base_url>              # 列全部智能体(name+id)
python scripts/nexent_agent.py show   <base_url> <agent_id>   # 看配置(含提示词)
python scripts/nexent_agent.py create <base_url>              # 新建智能体(★ 先读模型列表让用户选→交互收集提示词→创建→提示publish)
python scripts/nexent_agent.py update <base_url> <agent_id> duty_prompt   # 更新字段(回填其余)
python scripts/nexent_agent.py publish <base_url> <agent_id> [version_name] [release_note] [desc] [--duty=描述智能体如何工作] [--opening=开场白]  # 发布新版本(自动递增); 末尾可同步「展示/描述字段组」
python scripts/nexent_agent.py bind-kb <base_url> <agent_id>  # 挂载知识库(★ 先列 indices 让用户选→更新 knowledge_base_search 实例 index_names→提示publish)

字段职责划分（提示词放对位置！）：

| 字段 | 职责 | |---|---| | duty_prompt | 角色定位、核心任务（不要放输出格式要求） | | constraint_prompt | 工具使用规范 + 输出格式要求 | | few_shots_prompt | 示例（few-shot 示例对话，用户可见"示例"字段） |

update 必须回填全部字段（search_info 拉取 → 排除 tools/sub_agent_id_list/skills/model_names/model_ids → 规范化 model_id=enabled_tool_ids=related_agent_ids → 仅改目标字段），否则清空未传字段。

publish 版本规则（创建时确认，更新自动递增）：

创建时：初始版本命名规则（如 X.Y 格式、起始版本）由用户确认。
更新时（不询问用户）：先读版本列表（version_name + version_no + create_time 一起看）推测规律——update 会自动落一条版本、publish 再落一条（列表末尾可能是"伪最新"），且存在同名重复 → 识别命名规律（[前缀]主.次）后延续（同前缀+同主版本，次版本+1） → POST /api/agent/{id}/publish body {version_name, release_note, publish_as_a2a:false}（version_no 服务端自动递增）；发布后复查去重。禁止只看列表最后一条 / 取全局最大值+1 / 凭记忆硬编码 1. 前缀。

⚠️ 发布前必须同步「展示/描述字段组」（用户报 bug 后扩展）：智能体列表/卡片/对话首屏面向用户的字段，属"展示类字段"，不会随 duty_prompt/技能/MCP 的更新自动变化。每次发布若涉及能力/功能变更（新增技能、绑定工具、提示词新增能力），必须同步刷新整组，否则平台展示的仍是旧功能描述。

字段组（语义映射，实测校准 / 部署 <管理门户 base URL>（示例 :3000），★ 用户二次复核确认）：description=智能体描述 · display_name=展示名 · business_description=描述智能体应该如何工作（★非 duty_prompt，用户实测确认）· duty_prompt=角色设定/系统提示词 · constraint_prompt=使用要求 · greeting_message=开场白（实测真实字段名；opening_remarks/greeting/prologue 在本平台均不存在，勿用）· example_questions=示例问题（list，开场白旁首屏展示）· few_shots_prompt=示例（few-shot 示例对话，其它精心配置的智能体均用此字段）。

一键（全部用 --flag 显式传，杜绝位置参数顺序混淆）：python scripts/nexent_agent.py publish <base> <agent_id> --version-name="1.4" --release-note="说明" --desc="新描述" --business="描述智能体如何工作" --duty="新角色设定" --opening="新开场白" --examples="问题1,问题2" --shots="few-shot示例对话"（脚本发布前先回填其余字段并仅改对应字段，再 publish，不会清空其它字段；只传涉及的字段即可；版本名省略则自动递增）。

或分步：python scripts/nexent_agent.py update <base> <agent_id> <field>（field 取上述任一词，从 stdin 读新值，回填其余字段）→ 再 publish。

新建时也要填：cmd_create 已收集 greeting_message（开场白，可空）等字段，新建即写入，避免后续才补。

举一反三：update 接口"未传字段即清空"——脚本 cmd_update/_update_field 已显式锚定整组（仅当 search_info 返回该字段才写回），避免更新其它字段时漏带清空；但任何"展示类字段"的内容随能力变更须主动 update，平台不会自动派生。

完整协议见 references/03-admin-api.md。

技能管理 API（远程创建/上传/更新，/api/skills，属管理 API 范畴）：

POST /api/skills JSON 创建（body: name/description/content/tool_ids/tags…；tool_names 不支持）
POST /api/skills/upload multipart 上传创建：file=SKILL.md 或 ZIP（frontmatter 需 name/description；ZIP 含 SKILL.md 根或子目录）
⚠️ 脚本型技能（含 scripts/ 的）必须整包 ZIP 上传——只传 SKILL.md 单文件时 scripts/ 不物化，run_skill_script 报 FileNotFound（详见 03）
PUT /api/skills/{name}/upload 文件覆盖更新；GET /api/skills/{name}/files 验证物化；GET /api/skills/scan_skill 扫描本地目录刷新 DB（Skill not found 时修复）
AI 辅助创建：POST /api/skills/creator/create（nl2skill 异步任务）

方向四：MCP 工具接入与联调（要点速记）

把自有 REST API 变成 Nexent 智能体的 MCP 工具——Nexent 有一键「API 转 MCP」能力（FastMCP.from_openapi()）。

端口速查（实测部署示例值，端口由部署决定、无固定默认，勿假设）：3000 管理门户（登录拿 JWT）/ 5010 Config API（转换/工具管理主入口）/ 5011 MCP 服务器（SSE，工具运行于此）/ 5013 北向 API（chat/run）/ 5015 MCP 管理 API（内部）。

两个注册渠道，用途不同（最易混淆）：

| 渠道 | 接口 | 效果 | |---|---|---| | 原生 MCP 代理（首选，Channel ②） | POST {3000}/api/mcp/add body {name, server_url, enabled, authorization_token?, custom_headers?} | 进 MCP 仓库（mcp_record_t）；配合 5010 scan_tool 把远程 MCP 工具扫入 tool_t（source=mcp, usage=服务器名）→ 可绑定智能体；运行时 直连 MCP 服务器（ToolCollection.from_mcp，自动带鉴权头） | | OpenAPI 转换（Channel ①） | POST {5010}/tool/openapi_service body {service_name, server_url, openapi_json, headers_template?, force_update?} | 生成 src:mcp 工具，可绑定智能体；不进 MCP 仓库；工具运行在 Nexent 自己的 5011 MCP 服务器（FastMCP.from_openapi 包装） |

选型：已有原生 MCP 服务器（SSE/streamable-http）时，一律优先 Channel ②——工具由 MCP 服务器自己提供、运行时直连、鉴权头自动注入（mcp_record 的 authorization_token → headers["Authorization"]，custom_headers 合并进 mcp_config["headers"]），这才是"原生 MCP 接入"的正路。Channel ① 只在只有 REST API、没有 MCP 服务器时用（API 转 MCP 中转方案）。 ⚠️ 历史教训：曾因 Channel ② 实测时漏了 5010 /tool/scan_tool 这一步（只 add+refresh-tools，远程 MCP 工具没进 tool_t 表），误判"原生 MCP 无法绑定"而退回 Channel ①——这是错误结论，正路是 Channel ② 补上 scan_tool。

原生 MCP（Channel ②）绑定完整链路：

1. POST {3000}/api/mcp/add   {name, server_url, enabled:true, authorization_token?:"Bearer xxx", custom_headers?}
2. GET  {3000}/api/mcp/list            按 name 取 mcp_id（add 响应无 mcp_id）
3. GET  {3000}/api/mcp/healthcheck?mcp_id=     → status=true（scan_tool 依赖 enabled && status）
4. POST {3000}/api/mcp/refresh-tools?mcp_id=   → 持久化工具名
5. GET  {3000}/api/mcp/tools?mcp_id=           → 实时验证工具可见（可选）
6. GET  {5010}/tool/scan_tool           ★ 关键步骤：把远程 MCP 工具扫入 tool_t（source=mcp, usage=mcp服务器名），生成 tool_id
7. GET  {3000}/api/tool/list            按 origin_name 找 tool_id（source=mcp, usage=服务器名）
8. POST {5010}/tool/update              {tool_id, agent_id, params:{}, enabled:true} → tool_instance 绑定
9. POST {3000}/api/agent/{id}/publish   ★ 必须发布版本才生效

⚠️ 补充坑：改 mcp 记录（PUT /api/mcp/update）必须回填 authorization_token+custom_headers（不带会清空 → healthcheck 401/503 → 工具不可用）；agent 调用 MCP 工具挂起时，用官方 mcp SDK 客户端直连探测二分定位（服务端正常则问题在 Nexent 客户端，实测中换 SSE 端点解决）；自建 SSE 服务器鉴权中间件必须用纯 ASGI（BaseHTTPMiddleware 不支持 SSE 流式），sse_app() 挂 Mount("/") 根路径，mcp SDK sse_client() 返回 2 元组。

配置六步（Channel ①，API 转 MCP；无原生 MCP 服务器时才用）：

1. POST {5010}/tool/openapi_service     注册 OpenAPI 服务（openapi_json 可直接用应用 /openapi.json 或裁剪版）
2. GET  {5010}/tool/scan_tool            扫描 → 工具生成（src:mcp，记录 tool_id）
3. GET  {3000}/api/tool/list             确认工具（tool_id, origin_name）
4. POST {5010}/tool/update               绑定到智能体（每个工具一次）body {tool_id, agent_id, params:{}, enabled:true}
5. POST {3000}/api/agent/{id}/publish    ★ 必须发布版本，绑定才生效！
6. PUT  {3000}/api/mcp/update            补 config_json（OpenAPI JSON，含 "openapi" key）→ 界面 API-MCP 配置可见

MCP SSE 协议探测（验证工具真实可用）：

GET  {host}:5011/sse → event: endpoint / data: /messages/?session_id=xxx
POST {host}:5011/messages/?session_id=xxx → JSON-RPC: initialize → notifications/initialized → tools/list → tools/call
tools/call body: {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<tool_name>","arguments":{...}}}

Python 读 SSE 必须 readline 逐行（逐字节读在 Windows/urllib 下有缓冲问题导致 endpoint 丢失）
工具绑定后必须 publish 智能体版本，否则运行时看不到工具
常见坑：/tool/validate 只查远程 MCP 代理表，不适用于验证 OpenAPI 转换类工具

OpenAPI 对接：FastAPI 天然生成 /openapi.json（OpenAPI 3），可直接作 openapi_json；建议裁剪只留对外端点（内部 /api/* 不泄漏给智能体）。

完整流程、踩坑清单、GitHub 源码获取方式见 references/04-mcp.md。

方向五：提示词/技能/工具的加载与调用原理（要点速记）

核心结论一句话：技能是文件化的（SKILL.md，tenant 隔离），加载靠 read_skill_md("<技能名>") 渐进式读取（动作可见于 thinking）；没有触发 read_skill_md = 技能一定没加载。

提示词：三层（duty_prompt 角色任务 / constraint_prompt 约束+输出格式 / few_shots_prompt 示例）；update 只改草稿、必须 publish 才生效；update 必带 agent_id（漏传=误建新 agent）。

技能：

文件化：skills/{tenant_id}/{skill_name}/SKILL.md；校验 GET /api/skills/{name}/files，缺失可 GET /api/skills/scan_skill 刷新
加载 = read_skill_md("<技能名>")（命中后读全文，thinking 可见）；tool_ids=[] 只是"不可作为函数工具调用"，不代表不能被 read_skill_md 加载
"Skill not found" = 技能文件未就绪/参数错误（排查 files/scan_skill），不是绕开加载的理由
提示词是否要求"每次分析都 read_skill_md 加载"是项目决策，不是平台通用规则：若项目分析依赖技能全文，可要求每次加载（提示词写"每次分析都 read_skill_md 加载" + 兜底"失败忽略但禁止编造技能依据"）；若技能只是可选增强，则不必强制加载，可写"可用时加载"

工具：内置（如 knowledge_base_search）+ API 转 MCP；绑定后必须 publish；模型在 thinking 中以 code block 发起调用，平台执行回填。

会话管理：chat/run 不带 conversation_id = 新建会话；北向无删除接口（405），删除只能走管理 API DELETE /api/conversation/{id}（JWT）；"只保留最近一次"= 应用存管理凭据，新会话成功后再删上一次（先建后删）；只删应用创建且未被续用的会话（update_time 快照对比，被续用保留；应用自身追问也要刷新快照）。

验证方法论：端到端 SSE 抓 thinking → 技能看 read_skill_md 动作、工具看 code block 调用。

完整原理、实测案例、11 条踩坑清单、修正后 prompt 模板见 references/05-prompt-skill-tool-loading.md。

提示词设计建议（配合前端渲染）

固定小节结构（如 ## 核心结论 / ## 处理建议 / ## 分歧分析 / ## 风险提示，业务方可根据场景自定义小节名）便于前端分区卡片渲染
禁止 ### #### 三级标题，段首引导用 **粗体**
表格必须完整（表头 + 分隔行 + 数据行），防止解析失败
每条建议标注依据来源（如规则/技能/知识库）
关键数值用 Markdown 表格；结论前置，简洁专业

Resources

references/01-northbound-api.md — 方向一：北向接口完整 API 文档（agents / chat/run / SSE / 错误处理）
references/02-streaming-guide.md — 方向二：流式输出对接方法论（接口/协议层：SSE 事件本质 / conversation_id 响应头 / 协议层踩坑（空请求体 422、conversation_id 误渲染）/ 提示词契约 / 验证清单；前端呈现（三层架构/滚动三态/图表 init/弹窗解耦/真实浏览器验证）详见 ui-browser-testing 技能 streaming-ui.md，本文件仅留概述 + 跨技能索引）
references/03-admin-api.md — 方向三：管理 API 完整文档（Required Values 追问 / 登录鉴权 / agent CRUD 与创建（update 不带 agent_id）/ 模型与知识库列表（创建时供用户选择，更新自动沿用）/ 技能管理 API（创建/上传/更新/scan_skill/nl2skill + 脚本型技能 run_skill_script 执行机制 + ★ZIP 上传（只传 SKILL.md 脚本不物化）） / search_info / update / publish / 版本命名规则（创建时确认、更新自动递增，多读版本号找规律）/ 接口探查方法论（文档优先→源码兜底）/ 技能"不存在但已加载"排查（已修订指向 05））
references/04-mcp.md — 方向四：MCP 工具接入（原生 MCP 接入（Channel②首选：/api/mcp/add→healthcheck→refresh-tools→5010 scan_tool→tool/update→publish） / API 转 MCP（Channel①，仅无原生 MCP 时用）/ 双渠道机制与选型 / 运行时 mcp_host 直连与鉴权头注入 / MCP 调用挂起排障路径（官方 mcp SDK 直连二分定位） / SSE 服务器自建三坑（纯 ASGI 中间件、sse_app 挂根路径、sse_client 2 元组） / mcp/update 不带 authorization_token 会清空 / MCP SSE 协议探测 / 端口速查）
references/05-prompt-skill-tool-loading.md — 方向五：提示词/技能/工具加载与调用原理（三层提示词草稿/发布 / 技能文件化与 read_skill_md 渐进式加载（无触发=技能一定没加载）/ 工具绑定与 thinking 可见调用 / 会话生命周期与管理（北向无删除、管理 API DELETE、只删应用创建且未被续用的会话） / 11 条踩坑清单 / 修正后技能使用规则 prompt 模板）
references/06-field-mapping.md — 字段映射速查表（实测校准）：用户可见「展示/描述字段组」(description/display_name/business_description=描述智能体应该如何工作(非duty_prompt)/duty_prompt/constraint_prompt/greeting_message/example_questions/few_shots_prompt=示例) + 技术配置字段 + 反模式(opening_remarks/greeting/prologue 不存在) + 版本字段；快速判断 UI↔底层字段映射的方法
references/90-qc-ground-truth.md — 【质控专用，非使用教程】：领域事实清单/复查清单（20 条核心结论 + 已废弃结论 + 已发现问题记录），本技能逻辑复查的领域锚点；质控方法论详见独立技能 skill-qc（L0~L4 五层），质控时加载 skill-qc 执行；正常使用本技能无需阅读，仅在排查/修订/复查时对照使用
scripts/nexent_agent.py — 管理 CLI（list / show / update / publish，自动登录 + 字段回填 + 版本递增）