| name | ficc-pricing |
| description | DolphinDB FICC 定价技能。用于构造 FICC Instrument、MarketData、曲线/曲面、调用专用 pricer 或 instrumentPricer，并校验债券、利率、外汇、商品期货期权、权益期权等资产定价脚本。 |
| license | MIT |
| metadata | {"author":"ddb-user","version":"2.1.0"} |
ficc_pricing
本 skill 是 DolphinDB FICC 定价的通用中文规范。它服务于三个目标：准确构造 parseInstrument 入参、准确构造 parseMktData 或 builder 入参、准确选择 pricer 并解释结果。平台 API、前端 session、REST endpoint、业务数据库名、页面状态同步等内容不属于本 skill；这些内容应放在平台集成 skill 中。
一、适用范围
使用本 skill 处理以下任务：
- 根据条款构造单只或一组 FICC instrument。
- 根据市场数据构造利率曲线、股息曲线、资产价格曲线、外汇即期、波动率曲面。
- 调用 DolphinDB 专用定价函数，例如
bondPricer、fxForwardPricer、eqEuropeanOptionPricer。
- 调用
instrumentPricer(instrument, pricingDate, marketData) 做批量或自动匹配定价。
- 校验
.dos 示例脚本、定位字段错误、补充可审计输出。
不在本 skill 中硬编码平台函数前缀、平台库表路径、HTTP 路由、会话字段、UI 状态或一次性任务说明。
二、通用工作流
1. 确认条款
先确认资产类型、交易方向、本金、币种、起息日、到期日、行权价、票息、浮动指数、曲线名称、参考日期等真实输入。缺少关键市场数据时，应说明缺口或使用明确给出的替代假设；不要凭空补曲线、票息、波动率、股息率、样本券或即期汇率。
2. 构造 Instrument
统一使用 dict(STRING, ANY)：
instDict = dict(STRING, ANY)
instDict["productType"] = "Cash"
instDict["assetType"] = "Bond"
// ...继续填字段
inst = parseInstrument(instDict)
字段以各资产目录下的 instruments/*/fields.md 为准。字段名要使用 DolphinDB 实际枚举和字段名，例如债券用 start，不是 issueDate；权益期权用 payoffType，不是 callPut；NDF 用 direction，不是 buySell。
3. 构造 MarketData
市场数据也统一使用 dict(STRING, ANY) 后 parseMktData，或使用对应 builder。利率和波动率输入均使用小数，0.02 表示 2%，不能写成 2。
常见对象：
| 类型 | 用途 | 文档 |
|---|
IrYieldCurve | 债券、存款、IRS、FX、期权贴现曲线 | market_data/ir_yield_curve/fields.md |
AssetPriceCurve | IRS fixing、商品期货曲面构建的期货价格曲线 | market_data/asset_price_curve/fields.md |
FxSpotRate | instrumentPricer 自动匹配外汇即期 | market_data/fx_spot/fields.md |
FxVolatilitySurface | 外汇期权波动率曲面 | market_data/fx_vol_surface/fields.md |
VolatilitySurface | 商品期货期权、权益期权波动率曲面 | market_data/vol_surface/fields.md |
DividendCurve | 权益期权股息率曲线 | market_data/dividend_curve/fields.md |
专用 FX pricer（fxForwardPricer / fxSwapPricer / fxEuropeanOptionPricer 等）的 spot 参数要 DOUBLE 标量；若手头是存量 FxSpotRate MKTDATA 对象，取其 value 字段得标量再传，例如 spot = extractMktData(obj)["value"]。FxSpotRate 对象本身只用于 instrumentPricer 自动匹配。
4. 选择定价入口
单资产优先使用专用 pricer；多资产组合、需要自动匹配市场数据时使用 instrumentPricer。已验证环境中 instrumentPricer 签名为三参数：
instrumentPricer(instrument, pricingDate, marketData)
不要给已验证服务器传第四个参数或 platform wrapper 专用参数。
5. 输出可审计结果
示例脚本最后应返回标量、dict 或小表，避免最后一行只是赋值或注释。推荐返回 table(...)，至少包含 pricingDate、核心输入、NPV/price、曲线名称、关键风险指标或状态字段。
6. 执行与验收
使用 execute-dlang/scripts/ddb_runner/execute.py 运行 .dos。当前 runner 已修正：DolphinDB 服务端报错会返回非 0 退出码；脚本成功但最后返回 None 仍视为成功。批量验收时仍建议同时检查退出码和输出中的 [Error]、Code Execution Failed、Server Response，以兼容旧 runner 或 server 模式。
三、资产覆盖矩阵
| # | 资产 | Instrument 文档 | 专用 pricer | 主要市场数据 | 输出语义 |
|---|
| 1 | 债券 | instruments/01_bond/fields.md | bondPricer(instrument, pricingDate, discountCurve, [spreadCurve], [setting]) | IrYieldCurve，可选 spread curve | 曲线折现得到的全价/现值；净价需另减应计利息 |
| 2 | 国债期货 | instruments/02_bond_futures/fields.md | bondFuturesPricer(instrument, pricingDate, discountCurve) | 可交割债券融资/贴现曲线 | 理论期货价格 |
| 3 | 存款 | instruments/03_deposit/fields.md | irDepositPricer(instrument, pricingDate, discountCurve) | IrYieldCurve | 标量 NPV |
| 4 | 利率互换 | instruments/04_irs/fields.md | irFixedFloatingSwapPricer(instrument, pricingDate, discountCurve, forwardCurve, assetPriceCurve, [setting]) | 贴现曲线、远期曲线、fixing 曲线 | 标量 NPV 或含明细的 dict |
| 5 | 外汇远期 | instruments/05_fx_forward/fields.md | fxForwardPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve) | spot 标量、两条利率曲线 | 标量 NPV |
| 6 | 外汇掉期 | instruments/06_fx_swap/fields.md | fxSwapPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve) | spot 标量、两条利率曲线 | 近端+远端合计 NPV |
| 7 | 外汇欧式期权 | instruments/07_fx_option/fields.md | fxEuropeanOptionPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve, volSurface, [setting]) | spot、两条曲线、FxVolatilitySurface | 标量 NPV 或 Greeks dict |
| 8 | 商品期货欧式期权 | instruments/08_cm_fut_european_option/fields.md | cmFutEuropeanOptionPricer(instrument, pricingDate, futPrice, discountCurve, volSurf, [setting], [model], [method]) | 期货价标量、贴现曲线、VolatilitySurface | 标量 NPV 或 Greeks dict |
| 9 | 商品期货美式期权 | instruments/09_cm_fut_american_option/fields.md | cmFutAmericanOptionPricer(instrument, pricingDate, futPrice, discountCurve, volSurf, [setting], [model], [method]) | 期货价标量、贴现曲线、VolatilitySurface | 含提前行权价值的 NPV |
| 10 | 外汇 NDF | instruments/10_fx_ndf/fields.md | fxForwardPricer(instrument, pricingDate, spot, domesticCurve, foreignCurve) | spot、两条曲线 | NDF 差额结算 NPV |
| 11 | 权益欧式期权 | instruments/11_eq_european_option/fields.md | eqEuropeanOptionPricer(instrument, pricingDate, spotPx, discountCurve, dividendYieldCurve, volSurface, [setting]) | spot、贴现曲线、股息曲线、波动率曲面 | 标量 NPV 或 Greeks dict |
| 12 | 权益美式期权 | instruments/12_eq_american_option/fields.md | eqAmericanOptionPricer(instrument, pricingDate, spotPx, discountCurve, dividendYieldCurve, volSurface, [setting], [model], [method]) | spot、贴现曲线、股息曲线、波动率曲面 | 含提前行权价值的 NPV |
| 13 | 外汇奇异期权 | instruments/13_fx_exotic_option/fields.md | fxDigitalOptionPricer、fxRangeAccrualOptionPricer | spot、两条曲线、FxVolatilitySurface | v3.00.5 已验证数字期权和区间累计 |
四、债券工作流示例
债券是本 skill 中最容易出错的资产。不能只看 Bond，必须同时识别 bondType 和 subType。
1. bondType 决定现金流结构
bondType | 适用场景 | 构造要点 |
|---|
FixedRateBond | 固定票息、规则付息 | 必填 coupon、frequency；仅当规则付息债被误录成 Once 时才归一为 Annual。真正单笔现金流的超短期票据（SCP 超短融/短融、部分 ADBC/NCD 贴现券）Once 是正确的，不要归一；本质零息/贴现债同理。临近到期的单现金流票据 bondInstrumentCalculator 的净价/应计/YTM 拆分可能返回 NULL/None（已知限制）。 |
ZeroCouponBond | 无期间票息，到期一次兑付 | 不要硬建成普通固定票息债 |
DiscountBond | 折价发行，到期按面值兑付 | 重点字段是 issuePrice，通常不需要 coupon/frequency |
OptionBond | 含赎回、回售、调息等特殊条款 | 需补充期权标志、行权日/价格/票息路径；行权收益率用 priceType="YTE" |
FloatingRateBond | 票息随指数重置 | 需要浮动指数、spread、reset/fixing 信息；不能默认当固定利率债 |
AmortizingBond | 本金分期偿还 | 需要本金摊还计划；普通 bullet 假设会显著偏差 |
PerpetuityBond | 永续债或展期特征主导 | 需要赎回/延期/利差跳升假设 |
2. subType 决定曲线族和样本券
| 类别 | subType |
|---|
| 利率债 | TREASURY_BOND、CDB_BOND、ADBC_BOND、EIBC_BOND、LOCAL_GOV_BOND |
| 信用债 | SHORT_FIN_BOND、PPN、CORP_BOND、ABS、COMM_BANK_FIN_BOND |
不要使用过期或自造枚举，例如 LOC_GOV_BOND、CORPORATE_BOND 或中文标签。
subType → 标准 discountCurve 名 映射（信用债无评级时默认 AAA 曲线）
subType | discountCurve | | subType | discountCurve |
|---|
TREASURY_BOND | CNY_TREASURY_BOND | | NCD | CNY_NCD_AAA |
CENTRAL_BANK_BILL | CNY_CENTRAL_BANK_BILL | | MTN | CNY_MTN_AAA |
CDB_BOND | CNY_CDB_BOND | | SHORT_FIN_BOND | CNY_MTN_AAA |
EIBC_BOND | CNY_EIBC_BOND | | CORP_BOND / PPN / ABS | CNY_OTHER_BOND_AAA |
ADBC_BOND | CNY_ADBC_BOND | | URBAN_INVEST_BOND | CNY_URBAN_INVEST_BOND_AAA |
LOCAL_GOV_BOND | CNY_LOCAL_GOV_BOND_AAA | | BANK_BOND / COMM_BANK_FIN_BOND | CNY_BANK_BOND_AAA |
RAILWAY_BOND | CNY_RAILWAY_BOND | | SECURITIES_BOND | CNY_OTHER_BOND_AAA |
有评级时把 _AAA 换成实际评级后缀（如 _AA+）。instrument 的 discountCurve 字段应据此填写；instrumentPricer 即按该字段自动匹配同名曲线。信用债不得静默套用国债曲线。
3. 债券曲线选择顺序
- 用户明确提供曲线且币种、日期、风险类别匹配时，直接使用。
- instrument 的
discountCurve 指向可信标准曲线时，优先按该曲线族取数。
- 有同
subType、同参考日或可接受参考日的存量曲线时使用。
- 无存量曲线时，用同
subType 样本券和真实 YTM 报价通过 bondYieldCurveBuilder 构造。
- 样本券少于两个有效期限或报价不可信时，回退到 instrument 标准曲线或停止并补数据。
信用债、PPN、短融、ABS、商业银行金融债不能因为缺曲线就静默套国债曲线。国债曲线只能用于国债或明确的无风险基准比较。
4. 样本券选择规则
- 样本券必须与目标券同
subType，且 maturity > pricingDate。
- YTM 报价必须是真实市场报价，并转换为小数。
- 按目标期限匹配剩余期限，优先流动性更好的券。
- 对续发、柜台、重复期限或同一月到期的样本做去重。
Bootstrap 至少需要 2 个有效期限；NS 至少建议 4 个；NSS 至少建议 6 个。
5. 债券结果解释
bondPricer 返回的是给定曲线下的现值/全价含义，不自动拆分净价、全价、应计利息和收益率。需要交易报价口径时使用：
dirtyPrice = bondPricer(bond, pricingDate, discountCurve)
accrued = bondAccrInt(start, maturity, issuePrice, coupon, frequency, dayCountConvention, bondType, pricingDate)
cleanPrice = dirtyPrice - accrued
risk = bondInstrumentCalculator(bond, pricingDate, cleanPrice, "CleanPrice", calcRisk=true)
含权债若按行权路径估值，使用 bondInstrumentCalculator(..., priceType="YTE")；YTM 是到期收益率路径。
五、文件组织
| 路径 | 用途 |
|---|
instruments/*/fields.md | parseInstrument 字段、枚举、必填项、条款含义 |
instruments/*/demo.dos | 最小可运行 instrument 构造示例 |
market_data/*/fields.md | parseMktData 字段、曲线/曲面格式、适用资产 |
market_data/builders/* | 曲线和曲面 builder 参数、输入形状、demo |
pricers/*/fields.md | 专用 pricer 签名、参数、市场数据映射、输出语义、常见错误 |
pricers/*/demo.dos | 单资产定价 demo |
pricers/instrument_pricer.md | 批量自动匹配定价入口 |
