字段试验方法论 — 目的、阶段与终点
本文档说明字段试验（FT）循环为何存在、其目的如何随时间演变，以及何为"完成"。关于操作流程（节奏、报告模板、DX 审查角色）请参阅 CLAUDE.md §12 以及 docs/templates/field-trial-report.md。
FT 循环存在的原因
字段试验在独立沙箱（/home/xi/docker/nene2-python-FT/ftNNN-*/）中基于 nene2-python 实现真实工作负载，运行完整的检查套件，并记录实现者实际遇到的摩擦点。其目标是让文档和设计从观察而非推测中成长：
- 验证框架 API 在多样领域中稳定且符合人体工程学；
- 以可修复的具体观察记录摩擦点（
F-1、F-2、……）； - 通过安全诊断和渗透测试积累安全知识；
- 通过记录决策保持框架AI 可读。
每个 FT 的持久输出是其在 docs/field-trials/ 中的报告 — 沙箱本身是可丢弃的（.venv 可通过 uv sync 再生，旧沙箱可用 ft-status.sh --clean-sandbox 定期清理）。
阶段（目的随时间演变）
FT 循环并非单一活动，其目的经历了演变，#540 的存在正是因为这一演变从未被写下来。
阶段 0 — 框架反馈循环（FT1–FT6）
真实示例应用（lunchlog、bookshelf、tasklist、wallet、weather……）对框架特性进行了验证：身份验证（Bearer/ApiKey）、middleware 栈、MCP 服务器/客户端、事务、AsyncUseCaseProtocol。目标是强化框架自身的 API。发现的问题直接反馈至 nene2.*。
阶段 1 — 系统化标准库验证（FT7–~FT202）
核心 API 稳定后，循环转向每次 FT 包裹一个标准库模块，套上轻薄的 nene2 HTTP 层。每个 FT 回答：「框架的解析 → UseCase → 响应模式对这个领域是否符合人体工程学，以及这个模块的安全使用注意事项是什么？」此阶段产出了 FT 索引 和 how-to 文档库的主体。
阶段 2 — 深化安全（FT203+）
从约 FT203 起，循环越来越聚焦于安全原语和"危险原语规避"系列：secrets/hashlib/hmac（密码学）、pickle/marshal/ast.literal_eval/eval（反序列化）、subprocess（命令注入）、urllib.parse/ipaddress（SSRF）、re（ReDoS）、zipfile/tarfile/zlib/gzip/lzma（Zip 穿越与解压炸弹）、string.Formatter/string.Template（格式字符串/SSTI）。这些 FT 具有最高的持续价值，因为它们同时充当审计清单。
节奏
- 安全诊断（🔒）每当
FT % 3 == 0时执行。 - 攻击者渗透测试（🔍）每当
FT % 4 == 0时执行。 - 6 角色 DX 审查在每个 FT 中执行。
终点 — 何为"完成"
穷尽式的标准库扫描从未打算永无止境。到阶段 2，与安全相关的标准库接入面已覆盖（序列化、压缩/归档、解析/标记语言、密码学/认证、子进程、文件系统路径、网络输入、正则表达式、数值输入强化）。继续包裹纯计算性模块（colorsys、cmath、calendar、math……）相对于最初目的而言收益递减。
因此，FT 循环被认定为穷尽扫描已完成，转入维护 + 按需模式。只有当以下触发条件之一发生时，才需要新的 FT：
- 新框架能力需要验证（回归阶段 0 式反馈）。
- 新依赖（标准库或第三方）被引入框架或示例 — 在依赖它之前先验证。
- 发现未覆盖的安全类别（例如新的注入类型）。
- 维护者的明确请求。
维护模式下的周期性义务是每月的 uv lock --upgrade → pip-audit → 测试 → PR 循环（CLAUDE.md §5），而非新的 FT。
如何决定停止还是继续
- 如果候选 FT 不符合上述四个触发条件之一，优先选择不执行 — 结束循环，将精力用于解决未关闭的 issue 或框架特性上。
- "完成"是一个有记录的决定，而非数字。当循环暂停时，在
docs/todo/current.md中记录该决定（并更新 FT 索引 的页脚）。
摩擦分类与决策分类
当按需 FT 执行时，记录每个摩擦点（F-1、F-2……）时需标注类型和决策，使发现在各试验间保持一致且可分析，而非自由格式的叙述。
摩擦类型
| 类型 | 含义 |
|---|---|
docs-gap | 框架行为正确，但文档/示例未使其易于发现。 |
feature-gap | 实现者预期但实际缺失的功能。 |
design-trade-off | 摩擦是某个刻意设计选择的可接受后果。 |
process-gap | 工具/工作流摩擦（CI、检查、脚手架），而非 API 本身。 |
python-idiomatic-trade-off | Python 特有摩擦（Pydantic v2 强制转换、async/await、uv lock、mypy strict），没有单一"正确"答案。 |
最后一种类型替换了 NeNe 翻新专用的 legacy-preserved，该类型不适用于全新的 Python 框架。
决策类型 — 每个摩擦点恰好对应其中一种：
| 决策 | 行动 |
|---|---|
fix-in-framework | 在同一 FT PR 中修改框架/示例代码。 |
document | 行为正确；补充或澄清文档/CLAUDE.md。 |
keep | 接受现状并记录理由。 |
defer | 追踪为后续 Issue 并说明原因 — 这是 Issue 能够在 FT PR 之后存活的唯一情形（CLAUDE.md §12）。 |
此分类法从姊妹仓库治理提案（#545）中提炼而来。该提案的其余部分（引导脚本、专用 ADR、独立 FT README）已由 CLAUDE.md §12、现有报告模板和本文档覆盖，或因循环已达终点而价值不大。
总结
| 阶段 | 范围 | 目的 | 状态 |
|---|---|---|---|
| 0 — 框架反馈 | FT1–FT6 | 强化 nene2 API | ✅ 完成 |
| 1 — 标准库验证 | FT7–~FT202 | 确认人体工程学 + 积累文档 | ✅ 已扫描 |
| 2 — 深化安全 | FT203+ | 安全原语作为审计清单 | ✅ 接入面已覆盖 |
| 维护 + 按需 | — | 仅在 4 个触发条件时执行 FT；每月依赖更新 | 🔄 当前模式 |