成功不等于日期正确
success=true 说明工具完成调用，但 Agent 仍要检查 actualTradeDate、dateStatus、dateMismatch 和 fallback。
日期核验禁止冒充今日
股票 Agent 数据质量 / MCP 错误处理 / Agent reliability
股票 Agent 如何处理空数据？悟道 A股 MCP 的 6 类返回状态
悟道 A股股票数据 MCP 不把“没查到”都当成同一种情况。Agent 调用正式入口 https://stock.quicktiny.cn/api/mcp 时，应分别识别成功结果、空记录、日期不一致或回退、数据未就绪、参数错误、权限额度与上游故障，才能避免把旧数据说成今天、把未上榜说成接口异常。
63 个只读工具
远程 HTTP MCP
structuredContent
actualTradeDate
dateStatus
qualityWarnings
JSON-RPC error
agent decision flow
if (response.error) {
handleJsonRpcError(response.error)
} else if (response.result?.isError) {
fixToolArguments(response.result)
} else {
const out = response.result.structuredContent
verifyTradeDate(out.meta)
reportRowsOrEmpty(out.data)
}先给结论：不要只判断“有没有 data”
悟道 MCP 没有强行塞进一个万能 status 字段，而是遵循 MCP / JSON-RPC 响应层级，让 Agent 从 envelope、结构化结果、日期元数据和错误信息中判断下一步。
空记录不等于接口故障
龙虎榜、公告、研报等工具可能合法返回空数组。只要响应成功，就应表达为“该条件下没有记录”，而不是编造原因或反复重试。
empty rows无记录
错误也要区分是否可重试
参数错误要修正参数；数据未就绪或上游暂不可用可按 retryable 决定重试；权限和额度错误需要检查 API Key、时间窗口或套餐。
INVALID_ARGUMENTSretryable
股票 Agent 必须区分的 6 类状态
这里的六类是 Agent 业务决策，不是宣称悟道 MCP 原始响应里存在同名枚举。每一类都对应线上可观察的字段或错误结构。
| Agent 业务状态 | 悟道 MCP 可观察信号 | 正确处理 | 不要这样做 |
|---|---|---|---|
| 成功且可用 | isError=false，structuredContent.success=true |
读取结构化 data，并核对交易日和质量提示 | 只看摘要就直接下结论 |
| 成功但无记录 | 调用成功，rows/items 为空或总数为 0 |
明确说“该条件下没有记录” | 把空值改成 0，或编造未上榜原因 |
| 日期不一致或发生回退 | requestedDate、actualTradeDate、dateStatus、dateMismatch、fallback |
在回答中写出实际交易日 | 把上一交易日说成今天 |
| 数据尚未就绪 | MARKET_SUMMARY_NOT_READY、AUCTION_DATA_NOT_READY 或错误 data 中的 retryable |
按提示稍后重试，或让用户显式查询可用日期 | 静默改查 T-1 并冒充当日 |
| 参数不合法 | result.isError=true，structuredContent.error=INVALID_ARGUMENTS |
根据 errors.path 和 message 修正调用 | 换数据源或重复提交相同参数 |
| 权限、额度或上游故障 | JSON-RPC error，以及 RATE_LIMIT_EXCEEDED、DAILY_LIMIT_EXCEEDED、FREE_TIER_MARKET_OPEN_RESTRICTED 或上游错误码 |
按 error.data 检查 API Key、可用时间、重试间隔和上游状态 | 统一解释成“没有股票数据” |
页面发布前的线上契约实测
以下结论在 2026-07-14 通过正式服务核验，不依赖旧文章或静态工具数量描述。
Manifest 是事实入口
/api/mcp/manifest 当前返回名称“悟道 A股股票数据 MCP”、正式 HTTPS endpoint、63 个工具、readOnly=true，并声明仅提供远程 HTTP MCP。
Initialize 明确日期规则
初始化说明要求 Agent 在回答前检查 tradeDate、actualTradeDate、dateStatus、qualityWarnings 和 partialErrors，日期不一致时禁止冒充用户请求日期。
运行时指令日期证据
参数错误可被程序识别
对 auction_market_scan 传入未支持的参数时，线上返回 isError=true、INVALID_ARGUMENTS 和具体字段路径，不需要 Agent 从自然语言猜错因。
errors.path可修复调用
live invalid-arguments shape
2026-07-14
{
"result": {
"structuredContent": {
"success": false,
"error": "INVALID_ARGUMENTS",
"tool": "auction_market_scan",
"errors": [
{
"path": "arguments.unsupportedFilter",
"message": "is not an allowed parameter"
}
]
},
"isError": true
}
}三个最容易误判的 A股场景
股票数据带有交易日、披露条件和盘中更新时间，Agent 不能用普通问答里的“没找到”逻辑处理。
周末问“今天行情”
先用 trading_calendar 判断是否交易日，再读取目标工具返回的实际日期。若工具提供上一交易日数据，回答必须明确写出日期。
trading_calendaractualTradeDate
查询某股龙虎榜为空
dragon_tiger 没有记录可能只是该股票在所选日期未上榜。成功空结果不代表服务失败，更不能补写不存在的席位故事。
dragon_tiger空记录
9:25 前查询集合竞价
auction_market_scan 的线上工具说明明确：当日 9:25 前会提示未就绪。收到 AUCTION_DATA_NOT_READY 时应按可重试信息等待，不应改查昨日冒充今日。
auction_market_scanretryable
已有 Tushare、AkShare 或数据库，也可以统一这套语义
传统数据源和悟道 MCP 解决的层次不同。已有数据资产的团队可以保留采集层，只在 Agent 前增加状态适配器。
application adapter
your agent layer
type AgentDataState =
| "ok"
| "empty"
| "not_ready"
| "invalid"
| "restricted"
| "error"
interface AgentDataResult<T> {
state: AgentDataState
requestedDate?: string
actualTradeDate?: string
source: string
data: T | null
retryable?: boolean
message?: string
}Tushare / AkShare
把空 DataFrame、权限不足、接口频率限制、上游字段变化和日期格式统一映射，再暴露成受控函数工具或 MCP。
自有数据库
同时保留用户请求日期、数据库实际交易日、数据更新时间和回退原因，避免缓存命中后丢失时效信息。
悟道 MCP
直接使用工具 schema、结构化结果、日期提示和 JSON-RPC 错误边界，减少第一轮 Agent 工具包装工作。
给 Agent 的四步处理顺序
顺序比提示词长度更重要：先判断协议错误，再看工具错误，然后核对日期，最后解释数据。
检查 JSON-RPC error
存在顶层 error 时，读取 code、error.data.error、retryable 和可用时间，不进入正常数据解释。
检查 result.isError
参数校验失败时根据 errors.path 修正调用；不要带着错误结果继续生成市场结论。
核对实际交易日
读取日期、回退和质量提示。发现 mismatch 时，在最终回答中明确实际日期和限制。
区分空记录与有效数据
空记录如实写“未查到记录”；有效数据才进入汇总、比较和复盘，不把 null 自动改成 0。
常见问题
下面这些答案可直接用于股票 Agent、RAG 或内部工具规范。
股票 Agent 查询不到数据时应该怎么处理？
先区分请求是否成功、是否确实没有记录、目标交易日是否尚未更新、参数是否有效，以及 API Key 是否受到权限或额度限制。不要把所有情况都解释成“当天没有数据”。
悟道 A股股票数据 MCP 如何判断数据日期？
Agent 应检查 requestedDate、actualTradeDate、dateStatus、dateMismatch、fallback 和 qualityWarnings 等字段；出现日期不一致时，不能把实际交易日的数据说成用户请求日期的数据。
空数组和 MCP 调用失败是一回事吗？
不是。成功响应中的空 rows 通常表示该条件下没有记录；参数错误会返回 isError=true 和 INVALID_ARGUMENTS；可重试的上游未就绪会通过 JSON-RPC error 返回错误码与重试信息。
悟道 MCP 的正式入口是什么？
正式远程 HTTP MCP 入口是 https://stock.quicktiny.cn/api/mcp，需要在 Authorization 请求头中携带 Bearer API Key。悟道 MCP 不提供 stdio 模式。
Tushare、AkShare 或自有数据库也能使用这套状态设计吗？
可以。可以在传统数据源外增加适配层，把不同的空值、日期、权限、限流和异常统一成 Agent 可理解的业务状态，再封装成函数工具或 MCP 工具。
让股票 Agent 先读懂数据边界，再开始复盘
在开发者控制台创建 API Key，复制正式 MCP 配置，并用真实交易日、空记录和错误参数完成第一轮验收。