准备接入 Poppy 时，最先要做的不是写配置，而是把字段先列出来：从公开草案、示例配置、日志里出现过的键名逐条抄成一张表，标清来源、必填性、默认值；凡是找不到公开定义的字段，一律不写进正式配置，改成编号放进单独的 pending 段，默认关闭。代价是多维护一个占位文件，换来的是后续定义明确时只改一处，不必回头翻代码找散落的猜测值。
判断方向：Poppy 公开定义不足时，先出字段清单，再出配置骨架，最后才接真实服务。操作动作：字段逐条标来源与必填性，拿不到定义的统一编号并隔离到 pending 段，enabled 默认 false。验证方式：用缺失、未知、类型不符三类输入跑校验看日志，再用本地桩跑 dry-run 核对字段集合。风险边界：dry-run 只能证明配置可解析、字段集合与清单一致，不能证明远端会接受这些字段。
从 Poppy 草案和公开材料里抽取字段清单
凭印象拼字段最常见的两个坑：把示例里的可选键当成必填，或者把日志里偶发出现的字符串当成字段名。抽取时逐条记来源，来源只认可复核的几类：公开草案中的字段描述或示例、公开 schema、官方示例配置、运行时日志中稳定出现的键、命令行帮助输出。除此之外的印象，先归到未确认。
清单模板建议按下面这几列落地，存成 CSV 或表格都行，重点是每行四个值都要填满，不留空：
字段名,来源,必填性,默认值,未知标记
FIELD_A,草案示例,required,,-
FIELD_B,官方示例配置,optional,DEFAULT_B,-
FIELD_C,日志出现过一次,unknown,unknown,UNKNOWN-001来源写不到具体位置时，必填性只能填 unknown，默认值也只能填 unknown，不要为了让配置看起来完整而推一个默认值出来。UNKNOWN-001 这类编号是给后续替换用的，配置里只出现编号，不出现猜测出来的真实字段名。
用配置文件骨架隔离未知字段
未确认字段不要散落在正常配置层级里，集中放到一个显式的 pending 段，运行时直接跳过。下面是一份通用骨架，字段名与接口名全部是占位符，替换成自己确认过的那一份即可：
poppy:
endpoint: ${POPPY_ENDPOINT}
auth:
mode: AUTH_MODE_PLACEHOLDER
token: ${POPPY_TOKEN}
request:
FIELD_A: VALUE_A
FIELD_B: 0
pending:
- id: UNKNOWN-001
name: FIELD_C
source: draft_seen_definition_unconfirmed
enabled: false
fallback:
on_unknown_field: warn
on_missing_required: reject骨架里两处需要自己判断：enabled 默认给 false，只有拿到明确定义且校验通过后才改 true；on_unknown_field 在联调阶段给 warn 便于观察，进入正式使用前建议改成 reject，避免未知字段被静默发出去。凭据类字段只从环境变量读，不写进文件。整段建议单独放一个文件（例如 poppy.pending.yaml），排查时比混在主配置里清楚。
写一层字段校验和拒绝策略
校验层要分开处理三种输入，不要合并成一条“配置有误”的日志，否则排查时分不清是少字段还是字段名写错。可以先按下面的规则写：
REQUIRED = {'FIELD_A', 'FIELD_B'}
KNOWN = REQUIRED | {'FIELD_C'}
def validate(cfg):
# 1. 缺失
missing = REQUIRED - cfg.keys()
if missing:
log.error('missing_required fields=%s', sorted(missing))
return REJECT
# 2. 未知（含 pending 段里误开的字段）
unknown = cfg.keys() - KNOWN
if unknown:
log.warning('unknown_field fields=%s policy=%s', sorted(unknown), POLICY)
if POLICY == 'reject':
return REJECT
# 3. 类型不符
for k, v in cfg.items():
t = EXPECTED_TYPE.get(k)
if t and not isinstance(v, t):
log.error('type_mismatch field=%s expected=%s got=%s', k, t, type(v).__name__)
return REJECT
return ACCEPT验证方式就是构造三类输入各跑一次：删掉一个必填字段、加一个不在清单里的字段、把某个应当为数字的字段写成字符串。三次都应各产生一条能区分原因的日志，并且拒绝路径不发起任何调用。日志里只打字段名和类型，不要打 token 等凭据值。
用 dry-run 或本地桩验证接入流程
没有真实服务时，把 endpoint 指向本地桩。桩只做两件事：回显收到的字段集合、返回一个固定结构的应答，不模拟任何业务语义：
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
class H(BaseHTTPRequestHandler):
def do_POST(self):
n = int(self.headers.get('Content-Length', 0))
body = json.loads(self.rfile.read(n) or b'{}')
print('STUB_RECV keys=', sorted(body.keys()))
out = json.dumps({'ok': True, 'echo_keys': sorted(body.keys()), 'stub': True}).encode()
self.send_response(200)
self.send_header('Content-Type', 'application/json')
self.end_headers()
self.wfile.write(out)
HTTPServer(('127.0.0.1', 18080), H).serve_forever()日志观察点建议看四处：配置解析阶段是否出现 missing_required、unknown_field、type_mismatch；桩侧 STUB_RECV 的 keys 里是否混进了 pending 段中 enabled 为 false 的字段（不应出现）；数字字段在请求体里是否被序列化成了字符串；日志与桩输出里是否出现凭据明文。dry-run 能证明的是配置可解析、字段集合符合清单，远端是否接受这些字段，仍要等拿到真实定义后确认。
给未定义字段留出回退与变更记录
回退开关至少留两个粒度：整体回退，切回不接 Poppy 的旧路径，用配置项控制而不是改代码分支；字段级回退，把 pending 段里对应字段的 enabled 改回 false。字段定义后来变了的场景（改名、必填性变化、类型变化），改的就是这张表里的一行。
日期 | 字段 | 来源 | 变更前 | 变更后 | 触发原因 | 验证方式 | 回退方式
---- | ---- | ---- | ------ | ------ | -------- | -------- | --------
| UNKNOWN-001 -> FIELD_C | 公开草案对应小节 | enabled:false | enabled:true | 拿到明确定义 | dry-run 加桩日志对比 | 改回 false验证步骤建议固定三步：改字段之前先跑一次 dry-run，把日志存成基线；改完再跑一次，对比字段集合差异应当只包含本次变更的字段；确认无误后才把 enabled 打开，并在变更记录里补上日期与回退方式。后续定义再变化时，这张表就是排查的起点，不必重新推一遍字段。