# FFD MCP + Skill 一键快速接入

把本页交给正在使用的 AI Agent，它会按当前客户端和电脑环境完成接入或更新。API Key 只在本机终端输入，已接入用户继续使用本机保存的 Key。

## 已接入用户：更新 FFD

**新版支持自动更新。完成本次更新并保持自动更新开启后，重启智能体即可检查并更新 MCP 与当前客户端已安装的 Skill 文件。** Skill 若未刷新，按客户端提示重新加载或新建会话。

旧版首次升级、手动安装或关闭自动更新的用户，把下面这段话复制给 Agent，立即更新：

```text
阅读 https://ffd.findesk.cn/downloads/ffd-agent-kit/quick-connect.md，请按官方流程立即更新当前客户端的 FFD MCP 和 ffd-finflow-data Skill，保留现有 API Key 和配置。完成后用 ffd_health 确认版本；需要重启或新建会话时请说明，不执行付费查询。
```

[短提示词下载](fixed-update-prompt.txt)；原 `fixed-update-prompt-v1.1.txt` 地址继续可用。

## 手动立即更新命令

也可以直接运行官方命令。将示例的 `openclaw` 换为正在使用的客户端：`codex`、`claude-code`、`claude-desktop`、`cursor`、`cline`、`trae`、`reasonix` 或 `generic`。

macOS / Linux：

```bash
curl -fsSL https://ffd.findesk.cn/downloads/ffd-agent-kit/install.sh | bash -s -- --client openclaw
```

Windows PowerShell：

```powershell
& ([scriptblock]::Create((irm https://ffd.findesk.cn/downloads/ffd-agent-kit/install.ps1))) -Client 'openclaw'
```

更新后按 Agent 指引重新加载连接；需要新会话读取 Skill 时，Agent 会说明具体操作。

<details>
<summary>给 Agent 的安装、更新与验收步骤</summary>

## 新版统一自动更新（MCP 0.8.10）

- 官方安装器仍使用上方命令，统一更新器下载并校验 MCP Server、`SKILL.md`、更新器和 `ffd_launcher.py`。默认安装到 `~/.ffd/`，以本次读取的 `latest.json` 及其中 SHA-256 为目标；一致文件跳过改写。
- 新版统一启动器 `~/.ffd/ffd_launcher.py` 在启动时先完成校验和文件更新，再在同一次启动中运行新版 MCP。自动检查失败时继续使用现有文件，并简要说明情况；不会通过付费查询验证升级。
- 自动更新处理 FFD 共用文件及当前选定客户端已经存在的 Skill 副本，不创建其他客户端的 Skill 目录。手动 `--client` 安装或更新仍按选定客户端完成用户级 Skill 安装。项目或工作区的同名 Skill 只报告差异，不扩散覆盖。
- `FFD_AUTO_UPDATE=0`（或 `false`、`no`、`off`）关闭启动时自动更新。选定客户端由启动器 `--client`、`FFD_CLIENT` 或安装器保存的客户端标记确定；未知客户端不猜测其他客户端目录。
- 文件更新与 Skill 会话加载分开判断。启动器可以在同一次调用运行新版 MCP；已经开启的会话仍可能缓存旧 Skill，须按宿主客户端的发现方式重新加载或新建会话后核对实际选中的内容。

### 旧版升级兼容

旧版用户先运行一次上方手动提示词或更新命令。统一更新器会将可识别的 FFD Python 公共 Server 直连启动配置迁移到启动器，保留 Key、环境变量及其他 MCP 配置；自定义 wrapper 保持原启动方式，由新版 Server 兼容入口衔接统一更新。未知格式或外部托管启动方式由 Agent 明确报告所需操作，不覆盖猜测的配置。

旧版 Server 原有自动下载机制可能在第一次启动时只更新磁盘文件，需要再次重新加载才能运行新版；因此不能向尚未迁移的旧版用户承诺只重启一次即完成本次升级。旧发布清单未提供可校验的启动器时维持兼容安装，不使用未经校验的文件，也不迁移启动配置。

## 安全约束

- 不要让用户在聊天、截图或群聊中发送 FFD API Key。新用户只在本机安装器提示处输入 Key；老用户复用已保存的 Key，不回显、记录或上传凭据。
- 先读取本次 `latest.json`，固定目标发布版本及文件 SHA-256；更新程序与 MCP Server、`SKILL.md`、统一启动器都须先通过相应校验，再写入安装目标。校验失败停止更新；已有文件 SHA-256 与目标一致时跳过改写。
- 保留现有 Key、环境变量和其他 MCP 服务。仅可识别的 FFD 直连启动配置按上述规则迁移到统一启动器；未知格式由 Agent 按实际客户端格式确认并合并 FFD 条目，不能整文件替换。
- 默认只更新 FFD 共用文件和显式选择客户端的用户级 `ffd-finflow-data` Skill。改写前生成受保护的本地备份；不修改其他 Skill，也不扩散到其他客户端或工作区。

## 1. 识别本机环境

先确认本机有 Python 3.10 或更高版本。macOS / Linux 安装器会选择合格的解释器；如需指定已安装的解释器，可设置 `FFD_PYTHON` 为其绝对路径。

```bash
python3 --version
```

Windows PowerShell：

```powershell
python --version
```

没有合格的解释器时先安装，再运行更新流程。版本不满足或现有配置无效时，保留原文件并报告原因。

## 2. 运行官方安装或更新流程

`--client` 可选 `openclaw`、`codex`、`claude-code`、`cursor`、`cline`、`claude-desktop`、`trae`、`reasonix`、`generic`。Agent 必须选择当前实际客户端；以下示例为 OpenClaw，其他客户端替换对应值。

macOS / Linux 终端：

```bash
curl -fsSL https://ffd.findesk.cn/downloads/ffd-agent-kit/install.sh | bash -s -- --client openclaw
```

Windows PowerShell：

```powershell
& ([scriptblock]::Create((irm https://ffd.findesk.cn/downloads/ffd-agent-kit/install.ps1))) -Client 'openclaw'
```

也可显式设置环境变量 `FFD_CLIENT` 选择客户端；命令参数优先于环境变量。未指定两者时默认 `generic`，仅处理 FFD 共用文件、通用 MCP 配置和权威 Skill 副本，不检测并批量写入其他客户端。

安装入口读取本次发布清单，校验官方更新程序后调用它；更新程序下载、校验目标 MCP Server、大写 `SKILL.md` 和统一启动器后再写入，已有同 SHA 文件跳过。这一步是文件安装或更新，不证明客户端已经加载新内容。

已有客户端配置按上述兼容规则保留或迁移。新客户端如需自动创建 FFD 配置，须明确使用 `--configure-client`；否则 Agent 从本机 `~/.ffd/mcp-config.json` 的 `mcpServers.ffd` 读取 FFD 服务定义，按当前客户端实际 registry 格式映射并合并，保留其他 MCP 服务和已有启动方式；不能将通用顶层 `mcpServers` 结构原样写入所有客户端。配置格式或路径未明确时先报告缺口，不覆盖未知结构。

## 3. 确认文件和 Skill 加载路径

- 核对更新回执中的目标版本、文件 SHA-256 和实际写入或跳过路径。
- FFD 权威 Skill 副本位于 `~/.ffd/skills/ffd-finflow-data/SKILL.md`；显式选择的客户端只处理当前用户级 Skill 目录，不修改其他客户端。
- OpenClaw 使用 `~/.agents/skills/ffd-finflow-data/SKILL.md` 和 `~/.openclaw/skills/ffd-finflow-data/SKILL.md`。发现工作区中的同名旧副本时，仅报告路径和内容差异，不自动覆盖；Agent 须确认当前客户端实际选中的副本与目标一致。
- 安装路径、SHA-256、跳过状态及备份位置记录在 `~/.ffd/skill-install.json`，回执不包含 API Key。Skill 没有独立版本字段时，以内容 SHA-256 和实际路径识别，不编造版本号。
- 确认当前客户端的 Skill 列表可发现 `ffd-finflow-data`；不支持自动发现时，让 Agent 直接读取上述权威副本，并说明实际使用路径。

FFD 能力和工具调用规范的公开源文件：

<https://ffd.findesk.cn/downloads/ffd-agent-kit/SKILL.md>

## 4. 重新加载并验证当前客户端

1. 按当前客户端真实运行方式重新加载 MCP 与 Skill：由客户端管理的 MCP 服务重启该服务；需要完全退出或新建会话才能刷新时，明确给出操作。更新磁盘文件不能证明已运行的进程或已加载的 Skill 已更新。
2. 确认当前客户端实际选中的 Skill 路径及内容 SHA-256 与本次目标一致，且可被发现或明确读取。
3. 通过当前客户端调用 `ffd_health`，核对运行版本与本次读取的 `latest.json.version` 一致；不用其他终端新进程的健康结果替代当前客户端验收。此检查不需要付费数据查询。
4. 只有上述运行与 Skill 验证通过，才报告“更新并验收完成”。如需用户手动重新加载，报告“文件更新完成，运行验收待完成”，列出具体操作；不能把文件写入成功表述为运行完成。
5. 报告 MCP 更新前后运行版本、Skill SHA-256 与实际加载路径、验收结果及待办；没有取得更新前运行版本时如实注明。本次更新验收不执行行情或其他付费数据查询。


</details>

<details>
<summary>版本更新与能力合同说明</summary>

## 日期与机器合同补充修复（0.8.09）

基金历史净值每个所请字段附带精确证券、日期区间和指标合同；原生返回相邻日期、错误证券或字段时，在客户出账前拒绝并自动退回预扣，客户端停止后续分字段调用，不转未经验证的Hub。成功日期为净值观察日，不证明交易日历或完整历史覆盖。历史分钟已公开机器合同的函数与作用域标识保持稳定，源时间字段元数据保留；其他文本和凭据脱敏维持。详见[专项合同](pk-special-repair-contract.md)。

## 真实取数复核修补（0.8.08）

高级筛选在全部源行的日期、字段、身份和排序通过校验后，可从单一已排序结果交付前N行，同时留存完整来源档案和哈希；不会先截断以掩盖尾部错误。财务THS_BD原生回执未返回报告期时，只声明已验证的原生报告期参数绑定，标记PASS_WITH_WARNINGS，source_report_period为空，不用缓存日期冒充源回显。合同失败不可原样重试。详见[专项合同](pk-special-repair-contract.md)。

## 专项修复（0.8.07）

高级筛选保留日期、排序及字段并校验原始回执；营业收入/归母净利润只取对应金额，基金显式字段不再增加额外指标。来源定义、覆盖分母和精确快照缺口分别披露。分钟端点、原生单位、全市场同步快照及PIT未知仍保留。详见[专项合同](pk-special-repair-contract.md)。

## A股历史数据合同（0.8.06）

历史快照按证券×字段×时刻验覆盖，支持原生200只自动分批，以及exact/last_before与明确陈旧上限。部分返回净扣点0，strict有缺口失败。历史证券目录新增ffd_query的stock_list/historical_security_master子模式，按精确as_of分页并保留历史代码、名称及知识时间缺口。日级涨跌停价和交易状态与秒级快照分开。

分钟时间标签、左右端点、集合竞价归属、原生绝对单位和上游revision time分别读取minute_contract；未验证字段保持unknown/null。SDK0.3.9保留原始字典，默认DataFrame.attrs保留合同。正常历史源回执留存用于复用，持久接收不等于正式全市场/PIT发布。详见[完整合同](ashare-data-infrastructure-contract.md)。

## 指数分钟覆盖说明（0.8.05）

原生数据、代码覆盖、时间覆盖与模型准入分别判断。MCP 的 `minute_contract` 以服务端顶层 `coverage` 为权威；`complete=false`、`time_coverage_complete=null` 和 `status=unknown/unverified` 不会因返回48根或代码齐全被提升为完整。未知柱边界、最终性和数据定义保持未知；原始标签与价格不改写。

结构化 `ffd_intraday_quote` 使用 `params`，其客户端实际出站为 `POST /api/query`、`function=THS_HF`；通用 `ffd_query(function="intraday")` 使用 `options` 时保留公开 `intraday` 名称。以下是2026-10-06对58正式指数逐代码真实MCP请求使用的参数，代表代码000985.CSI本轮交付48根OHLC；不证明全58代码、全历史或模型已通过。

```json
{
  "symbols": "000985.CSI", "indicators": "open;high;low;close",
  "data_mode": "highfreq", "interval": 5,
  "start_date": "2026-09-30 09:30:00", "end_date": "2026-09-30 15:00:00",
  "params": "Fill:Original,Interval:5,CPS:1", "format": "json"
}
```

2026-10-06使用当前公开MCP 0.8.04、上述 `CPS:1` 参数完成58个正式指数逐项真实请求：49项各48根OHLC，9项仍由覆盖门禁关闭。本轮49项中，47项服务端时间覆盖为unknown、complete=false、time_coverage_complete=null；000918.SH及899050.BJ两项顶层coverage显式complete。MCP 0.8.05只修正这些响应的格式化优先级，保留原始交付和边界；完整性、计费、同日日线与模型分别验收，不以48根推断覆盖完整。

此前2026-10-05实测也沿用 `CPS:1`，49项各48根、9项未交付；保留原请求。当前 [官方高频输出设置](https://quantapi.10jqka.com.cn/gwstatic/static/ds_web/quantapi-web/help-center/manual.html) 将 `no` 定义为不复权，`Fill:Original` 为不处理非交易间隔；没有把数字 `1` 列为当前 CPS 值。本轮没有将 `CPS:no` 作为已实测可用参数，不将 `CPS:1` 结果改写成 `CPS:no` 的成功证明，也不据文档差异断言原始数据有错。两种取值的真实执行语义须另行验收。

指数 OHLC 单位为点位，scale=1；本地目标标签是北京时间09:35—11:30、13:05—15:00共48根。这是标签验收范围，不能据此推断每柱起止语义。48×4=192是有效数值单元数，不代表上游消费、实际扣费或持久化证明。此前49项与同日日线均有OHLC差异；原始交付、同口径日线对照与客户模型初始化仍分别验收。

## 美股分钟行情时间与覆盖合同（0.8.04）

`POST /api/query` 的 `function=highfreq_series` 和对应 MCP 分钟查询必须分别判断证券覆盖、输入时区、返回时区与时间覆盖。只有服务端返回已验证的 `time_contract` 时才采用其中的时区；美股或其他尚未验证市场的 `input_timezone`、`output_timezone` 和 `market_time_coverage` 保持 `unknown`，客户端保留原始时间，不自动换算。

大陆既有分钟例子仍按 `Asia/Shanghai` 使用。证券后缀 `.O` 不能单独证明当前账号权限、分钟数据覆盖或返回时间为纽约时间。`timeformat:LocalTime` 的官方说明是返回时间标签，不能据此推定输入时间会自动转换。代码覆盖与时间覆盖分别读取；旧响应 `coverage.complete=true` 不足以证明美股时间覆盖完整。

字段使用 `open;high;low;close;volume`。美股具体代码、时间、options 与成功回执尚须逐证券真实验收；空结果不作成功或完整覆盖依据，也不以其他市场成功替代美股验收。

完整说明与明确标记的未实测请求构造例子见 [us-minute-time-contract.md](us-minute-time-contract.md)。

## 分钟行情默认调用规则（MCP 0.7.102）

历史分钟行情使用 `ffd_intraday_quote` 的标准分钟接口。不要把扩展高频接口作为默认入口、重试目标或容量不足时的替代路径。

- 结构化 `data_mode="highfreq"` 必须同时提供 `start_date` 和 `end_date`；不能只填写代码和周期。
- 缺少时间范围时在客户端本地返回参数错误，不发起数据请求、不扣点。
- 标准分钟请求失败时保留原错误、可重试性和计费状态，不自动改走扩展通道，不以实时快照或日线代替历史分钟。
- 普通 OHLCV 示例使用 `open,high,low,close,volume,amount`。其他字段必须先确认该接口的字段合同，不能因名称相似而替换。
- `real_time` 仍表示实时快照，不是历史分钟；原有明确调用旧 REST 接口的兼容性不变。
- 已安装旧版 MCP 的客户端应按本次读取的 `latest.json` 更新并重新加载 MCP 进程；运行版本须通过当前客户端的 `ffd_health` 核对。

```text
ffd_intraday_quote(symbols="600519.SH", indicators="open,high,low,close,volume,amount", data_mode="highfreq", interval=5, start_date="2026-09-22 09:35:00", end_date="2026-09-22 10:00:00", format="json")
```

示例为沪深 A 股，时间按北京时间传入；实际覆盖以回执为准。本规则不承诺全部证券、日期或特殊字段均可用，也不改变套餐权益和计费规则。

## 0.8.02 原生映射修复与调用验收

指定报告期的基金持仓查询接受有效季末日期（YYYY-MM-DD 或 YYYYMMDD），并兼容 YYYY 年度写法。该查询取得完整报告，scope=top10 仅控制展示前十条，客户计费仍按完整 HTTP 报告；选择 output_mode=raw 或 both 可在同一次调用取得完整原始报告和计费、资产回执，无需再次查询。份额继承、有效组合代码与部分返回状态按实际响应明确展示。

精确宏观序列由 `/ffd-macro-series-dictionary.json` 发现；返回 `series_contract` 中的频率、单位、观察期和完整性边界，不把观察值日期当成首次发布日期。

专题字段以该 report_id / variant_id 的原生字典为准；`NAME` 等同名字段不会翻译为股票基础字段。分类模板提供独立验证范围及可执行示例，原生空值、上游服务错误和完整业务交付分别列示。

REST逐端点参数、可选响应字段、分页、覆盖和计费合同见 `/ffd-rest-endpoint-contracts.json`。静态结构字段与实际观察字段分开说明，不代表所有请求都会返回全部字段。公开目录支持文档列示的API Key认证。

原生日历的23种市场及偏移边界见 `/ffd-calendar-native-contracts.json`；现有公开入口的市场范围保持各自合同。上游用量未确认不伪记为0，不改变管理员权重或已购权益。指定基金持仓报告的原始记录与所选字段分别保存，入库完成不代表历史覆盖已完整验证。完整专题映射、专项数据和持续订阅的剩余依赖仍按公开边界显示。


以下按版本保留的数据示例不作为当前安装版本要求；当前客户端的目标版本始终以本次 `latest.json` 为准。

### 0.7.69 FFD 统一能力目录快速核验

- 当前客户端运行版本须与本次 `latest.json.version` 一致；`tools/list` 应保留 0.7.67 全部工具，并新增 `ffd_sector_data`，不得出现独立的供应商工具目录。
- 板块自身指标：`ffd_sector_data(query="半导体板块行情、估值和技术指标", format="json")`；板块成分仍使用 `ffd_industry_stocks`。
- 公司事件：`ffd_company_events(stock_code="600519.SH", event_type="equity_incentive", format="json")`；IPO、再融资、并购重组、治理变更、股权激励和员工持股均在同一 FFD 工具中。
- 基金缺口分别使用现有 `ffd_fund_ownership`（申购/赎回/份额变动）、`ffd_fund_financials`（分红金额/次数/预案）、`ffd_fund_company_info`（公司财务、组合和公司级 Alpha/Beta）。
- 标准历史分钟：`ffd_intraday_quote(symbols="600519.SH", indicators="open,high,low,close,volume,amount", data_mode="highfreq", interval=5, start_date="2026-09-22 09:35:00", end_date="2026-09-22 10:00:00", format="json")`；不自动转扩展通道。
- 指数高频：`ffd_global_index_data(symbols="000001.SH", indicators="领先指标,上涨家数,下跌家数", data_mode="real_time", interval=1, format="json")`。
- 0.7.69 已完成官方高频字段词汇转换与二维表格返回解析；中英文公开别名不应再因适配层误差返回通道 502。
- 扩展字段按市场、证券、日期和当前覆盖返回；缺失不得用其他频率、其他证券或推导值冒充。失败和空结果不得净扣点。

### 0.7.67 国际商品现货快速核验

- 当前客户端运行版本须与本次 `latest.json.version` 一致。
- 调用 `ffd_commodity_spot(query="伦敦金和LME铜最新日频现货价", latest=true, format="json")`，应返回 `XAU_LONDON_CLOSE` 和 `LME_COPPER_CASH`，每行包含 `definition_id`、`frequency=daily`、`unit` 和精确 `price_type`。
- 伦敦铂/钯必须标记为上午现货价，LME基本金属必须标记为现货结算价；全部国际商品序列当前均为日频，不得表述成实时行情。
- 计费为每个实际返回的日期×价格观测 1 个 market 点；元数据不重复扣点，空结果和失败不扣点。

### 0.7.66 历史估值覆盖合同快速核验

- 当前客户端运行版本须与本次 `latest.json.version` 一致；不一致时核对该客户端实际使用的文件路径，并按其真实运行方式重新加载后再调用 `ffd_health`。
- 历史估值分位：`ffd_financial_metrics(codes="600519.SH,300750.SZ", metrics="PE;PB;估值历史分位", as_of_dates=["2024-01-09","2024-10-08"], valuation_windows_years=[1,3,5], coverage_policy="return_available", coverage_only=true, format="json")`。单批最多 300 个股票×日期组合，`coverage_only` 不扣点并逐组合返回缺失原因。
- 严格报告期财务：`ffd_financial_metrics(codes="...", metrics="ROE;营收同比;净利润同比", report_date="2024-12-31", as_of_date="2025-04-30", format="json")`；单批最多 300 只，公告日不得晚于信号日。
- 公司事件：`ffd_company_events(stock_codes="600519.SH,300750.SZ", start_date="2023-01-03", end_date="2026-08-28", format="json")`；检查 `first_published_at` 和 `meta.stock_filter_coverage`，无匹配不能解读为已证明监控完整。
- 常规并发 2–3；仅对 429 或明确 `retryable=true` 的瞬时错误指数退避。`retryable=false`、`failure_scope=dataset_coverage` 表示指定日缺观测、样本数不足或历史窗口不足，应立即停止原样重试。

### 0.7.55 历史行情覆盖交付快速核验

- 当前客户端运行版本须与本次 `latest.json.version` 一致；升级后不一致时，按实际运行方式重新加载，不能仅凭刷新对话确认更新。
- 多代码 `ffd_quote_history` 默认使用 `coverage_policy="complete_rows"`，结果应返回完整的证券×交易日行，并在 `coverage` 中披露当日待发布或历史缺口。
- `return_available_cells` 可以保留已验证单元和 null；`strict` 遇到任一缺口应失败关闭且客户净扣点为 0。
- 同一个父请求可以对应多个物理上游租约，但客户只有一次结算；计费点数必须等于实际交付的非空请求单元数。MCP 不得对已披露缺口继续拆单或自动重试。
- 完整片段进入资产链路时必须使用独立 fragment 身份，不能让不完整批次命中为原始完整缓存。

### 0.7.54 个股历史点时估值快速核验

- 当前客户端运行版本须与本次 `latest.json.version` 一致；升级后不一致时，按实际运行方式重新加载，不能仅凭刷新对话确认更新。
- 调用 `ffd_financial_metrics(query="600519.SH 2024-01-09 PE PB", codes="600519.SH", metrics="PE;PB", as_of_date="2024-01-09", format="json")`，应返回请求日的 PE/PB，并携带 `point_in_time=true`、`future_data_allowed=false`、`ttm_report_basis=report_announcement_date`。
- 仅请求 PE/PB 时不得因 PS/PCF 缺失而失败；股票代码与 PE 同时出现时不得进入商品/化工现货路由。
- `dataset.as_of_date` 必须等于请求日期；基础数据返回观察日期时会再做一致性校验，未返回日期列时则以精确请求参数和隔离缓存身份绑定该日期。任一所请字段缺失或数据暂不可用时，应失败关闭且不返回当前值/相邻日值。
- 0.7.53 的以下路由合同继续有效：
- 仅传 `code="AAPL.O"` 调用 `ffd_us_finance_data`，或仅传 `code="00700.HK"` 调用 `ffd_hk_finance_data`，默认应请求 profile / quotes / financials / events 全量分区。
- `ffd_hk_finance_data(code="00700.HK", trade_date="2025-09-26", datasets=["quotes"])` 的市值/PE/PB 请求应走统一标准估值快照，不应被旧补充分区容量拦截。
- `ffd_market_microstructure(task="call_auction", trade_date="2026-08-28", date_mode="exact", rank_by="amount", limit=50)` 可不传 symbol，返回完整终态资产派生的全市场开盘竞价 TopN；显式日期不回退。若省略日期，默认 `date_mode="latest_completed"`，周末或其他非交易日会解析到最近一个已完成 09:25 最终撮合的交易日；查北京时间当日使用 `date_mode="current_trading_day"`。响应须核对 `requested_date`、`resolved_trade_date`、`actual_data_date`、`requested_trade_date`、`actual_trade_date`、`actual_data_time`、`date_status`、`fallback_reason`、`asset_as_of` 和 `snapshot_final`。日期解析及本地已验证终态资产读取合同已发布；尾盘与委托额榜单仍不开放，交易日当日本地缺失补取仍须以后端正向验收为准。
- `ffd_topic_report` 不传参数时应返回免费模板目录；这不是数据请求，不扣点。
- `ffd_technical_indicators` 的结果行应直接包含 MA5/10/20/60 和布林带上中下轨，同时保留嵌套 `indicators`。
- 真实 ESG、股东或全球快照来源缺口仍应明确失败关闭或返回 null，不能把缺失字段补成 0。
- L2 权益、字段、实时即用即抛和不沉淀规则没有变化。

## 常见恢复

- 工具列表没有 FFD：核对当前客户端实际配置和启动路径，按真实运行方式重新加载。
- Skill 列表没有 `ffd-finflow-data`：查看 `~/.ffd/skill-install.json` 的实际目标和 SHA-256，检查同名工作区副本是否被优先选中，再按当前客户端的发现或重新加载方式处理；不自动覆盖工作区。
- 鉴权失败：重新运行官方安装器，只在本机终端提示处粘贴完整 FFD API Key。
- 安装器提示配置 JSON 无效：保留原文件，先修复 JSON 语法，不要覆盖用户现有配置。


## Truthfulness contract: 2026-09-08 / MCP 0.7.77

- 历史表现支持明确起止日期和 A 股单日期前后各 N 个交易日；无法精确解析时停止，不改查最近行情。交易日以正式交易日历为准。
- 宏观多项需求用分号分开，每项保留指标、频率、单位、请求日期和实际观测范围；未识别项逐项报错，不静默丢弃。`format=json, output_mode=raw` 返回完整数据，不把预览长度当覆盖长度。
- 估值分位默认 `return_available`，1/3/5 年窗口各自报告可用性；未指定日期按本地最新实际观察日解析，指定日期严格绑定。`strict` 缺口关闭；`coverage_only` 仅预检。
- 主力连续合约与具体月份合约不等价。未验证连续代码和换月规则时返回 `FUTURES_CONTINUOUS_CONTRACT_UNRESOLVED`；可另行查询明确的 `RB2610.SHF` 等合约，但不得声称替代主力连续序列。
- 可转债转股数据与实际返回的行情交易日对齐。转股价生效日没有证据时保持 null，不用查询日期充当生效日期。
- 指数估值失败不再用当前成分股或实时行情替代。成分市值聚合口径不是官方指数 PE/PB，也不是估值历史分位。
- 日频异动只对实际样本评分，并列同分、缺失因子不制造排名；披露样本覆盖，不能当成全市场完整榜单或直接成交信号。
- 最新财报未携带报告期时 `report_date=null`，明确 `report_period_status=unresolved`。普通财报查询不是公告时点 PIT；严格回测使用 PIT 接口和逐项覆盖证明。
- 宏观和商品的实际观测序列不自动构成完整交易日历覆盖，也不等于历史初值/修订版本。缺失值不填零、不前向填充、不用未来数据填过去。
- 美股期权、ESG 返回结构不合格、请求级上游用量证据不足分别报告真实边界；不得统一解释为境外网络不稳定。审计门禁不绕过。
- 权益快照短缓存 30 秒；瞬态失败最多提供 300 秒内的明确 stale 历史快照，不作为数据请求授权。401/403 不回退缓存。
- 重型调用包括完整财报、综合摘要、股东、板块资金与指数聚合。推荐串行，并将 MCP 客户端超时设为至少 180 秒。请求超时结果可能已在服务端完成，禁止自动原样重复 POST；先查看调用记录。
- `ffd_adjustment_factor_events.codes` 同时接受代码数组和分隔字符串。`ffd_capabilities(detail_level=compact)` 用于渐进发现，`full` 保留完整地图。
- 新闻分类先调用 `ffd_news_search(mode=sectors)` 取得实时字典。`no_sector_match` 是无匹配结果且不收费，不代表整个新闻服务不可用。
- Markdown 是预览，不是数据交付全集；被省略或截断的字段必须明示。机器分析以 JSON raw 和服务端覆盖合同为准。


### REST and MCP scope

MCP 场景工具不等于 Python SDK 的同名方法。SDK 与 REST 仍以各自已发布合同为准。

历史估值分位批量 REST：`POST /api/mcp-hub/valuation-percentiles/batch`，沿用 API Key 鉴权和现有权益门禁。

```json
{"codes":["600519.SH"],"as_of_dates":["2026-09-07"],"date_policy":"exact","metrics":["pe_ttm","pb_mrq"],"windows_years":[1,3,5],"coverage_policy":"return_available","coverage_only":false}
```

显式日期不可替换。仅在没有 `as_of_dates` 时可传 `date_policy=latest_available`，服务端返回实际解析出的观察日。
`return_available` 按窗口披露缺口；`strict` 任一缺口失败且不扣点；`coverage_only=true` 不返回数值且不扣点。
复权事件 REST 继续使用代码数组；MCP `ffd_adjustment_factor_events` 可接收代码字符串并转换为数组。
权益 MCP 响应的 `snapshot_status` 区分 fresh、cached、stale；历史快照不作为实际数据访问授权。


## 0.7.79 增量修复

0.7.79 同步发布已验收修复：财务默认报告期、加密资产来源凭据与 UTC 自然日、伦敦金源窗口及子区间计数、港美股名称币种、Request ID 和完整性错误协议。股东新替代路径关闭，ESG 仅修复容量语义，均不宣称数据恢复。保留 93 项工具及既有计费规则。

详细边界及示例见 [0.7.79 修复合同](residual_repair_contract.md)。


## Optional A-share Financial PIT Auditable Delivery v1

This separately configured extension adds immutable CSV/Parquet exports, coverage/provenance manifests, explicit customer billing and resumable downloads. It does not replace the 94-tool core MCP server or the finflowdata Python SDK.

Existing observations are not full historical PIT proof. Decision mode fails closed on missing official evidence or conflicting revision branches. No upstream collection or paused backfill is started by this extension.

[Contract and usage](https://ffd.findesk.cn/downloads/ffd-agent-kit/pit-delivery-v1/README.md) | [Python client/CLI](https://ffd.findesk.cn/downloads/ffd-agent-kit/pit-delivery-v1/ffd_pit.py) | [Optional stdio MCP](https://ffd.findesk.cn/downloads/ffd-agent-kit/pit-delivery-v1/ffd_pit_mcp.py)


## PIT evidence readiness and frozen field lineage

The accepted REST endpoints and manual dashboard expose registered evidence gaps and immutable field lineage. Full historical financial PIT and private-object signed delivery are not claimed complete. Existing MCP tools, Python SDK and billing rules are unchanged.

[Evidence governance, accepted scope and remaining gaps](https://ffd.findesk.cn/downloads/ffd-agent-kit/pit-delivery-v1/governance.md) | [Readiness dashboard](https://ffd.findesk.cn/api/v1/pit/delivery/readiness/dashboard)


## 0.7.88 指数分钟行情合同

- 指数价格单位为 `points`，不再沿用股票的 `CNY/share`。
- 大陆既有指数分钟标签声明 `Asia/Shanghai`；尚未核验的市场时区、bar 端点与最终性明确为 unknown。
- `ffd_global_index_data(data_mode="highfreq")` 支持成对的单日历史范围并回显生效区间。
- 详细合同：[index-minute-contract.md](index-minute-contract.md)。

- 已验收的原生实时快照：`ffd_intraday_quote(symbols="600519.SH", indicators="latest;volume", data_mode="real_time", format="json")`。按行情有效字段单元计费；以 `data.time` 判断源观察时间，休市日不保证当日新行情。其他实时字段当前不自动降级或猜值。


## 0.7.101 日历计量与正式事件池交付

# 日历计量与历史事件池交付合同

版本：2026-09-30.1。对应 MCP 0.7.101；历史数据覆盖没有因客户端版本升级而自动扩展。

## 交易日历

REST `POST /api/query`，`function=trade_calendar`；MCP `ffd_trade_calendar`。

客户计量基数是唯一交付的交易所与日期。同一日期在 `rows`、`dates` 等容器重复出现只计一次；`complete`、`row_count`、请求范围等元数据不计点。空日期序列为 0 个日期观察值。客户倍率若适用，仍按原规则执行。

`billing.contract_version=calendar-unique-observation-20260930.1` 回显计量口径和观察数；`charged_points` 是本次扣点。原始缓存不改写，但缓存交付也按本版本重新计量。

`balance_remaining_scope=legacy_aggregate_not_charged_pool_balance` 表示旧式汇总余额，不代表本次基本面额度池余额。按池余额与请求账本分别核对。

## 涨跌停事件池

REST `POST /api/query`，`function=ffd_limit_pool`；MCP `ffd_limit_pool`。`all` 仍为涨停加炸板，`all_events` 为涨停加炸板加跌停。

MCP 使用一次正式 REST 调用，不再以多个普通筛选请求拼装历史完整事件池。MCP 请求终态交付；未形成精确日期终态资产时，服务端在成功计费前拒绝，保留原始错误码和请求 ID。HTTP 成功后的意外合同错误仍如实携带已收到的计费回执，不伪报为已退款。

完整明细首次成功交付为 2 个事件任务单位，基础明细为 1 个；同用户、日期、池类型、明细层级和资产版本按既有幂等交付规则执行。三个池的完整组合不是三次各扣 2 点。失败未交付为 0 点。

`complete_scope=pool_membership` 不代表所有字段非空。首次时间、末次时间、开板次数按 `field_coverage` 判断；新增返回已有资产的 `amount`、`float_market_cap`，空值不补零，金额单位未完成独立鉴真时标为 `unverified`，不得视为已确认的标准货币金额。

REST `summary.columns` 列出实际字段，不再限制为 20 列。新增字段不删除原日期前缀字段，也不增加事件任务扣点。

## 历史边界

2020-2025 不构成连续完整历史覆盖。2026 清单存在不证明不存在漏成员，也不保证盘中字段齐全。2026-01-12 已有成员不一致线索，尚未完成精确修订，不应作为通过完整市场复核的样本使用。

没有声明免费覆盖查询端点、完整多年补采或固定补齐 SLA；没有修改客户旧账本、停用 Key 或自动退款。`observed_at` 不等于历史首次公开时间，版本标识不替代完整的历史修订链。


</details>


### 0.8.23 分钟周期及余额修复

REST intraday/THS_HF 顶层 interval 已接入原生周期，兼容 freq/period/bar 分钟别名；与 params/options 周期冲突时扣费前拒绝。查询余额按 data_point 分池合计，与权益接口同口径；分池不可互相挪用。保留原生分钟时间与覆盖边界，不将行数乘字段数替代实际非空指标单元。
详见 https://ffd.findesk.cn/downloads/ffd-agent-kit/intraday-interval-balance.md 。


### 商品期货与期权（0.8.24）

0.8.24：修复郑商所期货YYMM/YMM代码兼容、大商所分钟接口笼统预检及广期所GFE境内分类；期权日线保留实际终态错误并统一大商所原生合约格式。通道覆盖不足不等于客户套餐不足；失败不扣点，不建议反复重试或升级套餐。单合约实测不代表全交易所、全历史已开通；合约链仍按当前通道状态处理。 详情见 [调用合同](commodity-options-contract.md)。


### 0.8.24 期权字段与计费

期权日线逐项验证请求字段，缺失字段拒绝成功交付且净扣0；日线和快照只计有效行情字段，合约、日期、布尔状态等元数据不收费。客户角色实测日线2字段2点、缺持仓量净0、快照默认5字段5点。 对已确认的历史误扣按原请求回补，不要求升级套餐。通道尚不支持的合约或字段仍明确说明，不能以其他字段、其他日期替代。


# 商品期货与期权日线（0.8.25）

大商所、广期所期货日线使用标准历史行情入口（`ffd_quote_history` 或 `POST /api/query`、`function=THS_HD`）；单合约期权日线使用 `ffd_options` / `POST /api/market-data/options`，`market=cn, operation=history`。

明确请求 `open,high,low,close,volume,open_interest` 中所需字段。商品持仓量适配已修正；广期所期权公共代码如 `SI2701C8000.GFE` 会转换为通道要求的格式。期权不要混入普通期货日线接口。单次一个合约、最长31个日历日；具体历史与字段以原生真实返回为准，不以本地缺失断言不可获取。

成功交付只按有效行情指标单元计费，合约、时间和状态元数据不收费；例如单合约单日六字段为6点。缺字段、错误日期或错误合约拒绝交付，净扣费0。缓存命中按正常交付价格计费，不产生新的上游取数；不同日期、代码和字段分别识别，不能相互充数。

这次日线验证不证明大商所、广期所的分钟或快照已开通。Choice的分钟与快照入口存在，但当前FFD原生路由、权限和计量链尚未完成验证；尚未派发到上游的请求不能被解释为Choice账号拒权。不要建议客户升级套餐来解决服务侧通道问题，不要将日线当分钟或将收盘值当实时快照。

现有iFinD分钟与快照按原各自覆盖合同运行；本次没有以Choice日线代替这些模式。期权Greeks、完整合约链、全市场和全部历史均没有在这次样本中认证。

客户端请更新并重启MCP或重新加载Skill。REST后端修复独立生效，既有Key不需要更换。