用途：在采用 reST 字段列表（:param:/:returns:/:raises:）和 Sphinx 交叉引用的 Python 项目中编写、编辑、审查 docstring，让同一份文本既能被人阅读（如工具提示），也能被 Sphinx 渲染成带真实链接的 API 文档，表达类型注解无法覆盖的含义、约束、副作用与失败条件。
主要能力：
- 规范字段顺序为 :param: → :returns: → :raises:，字段列表作为一个块放在摘要（及可选正文）之后，用空行分隔。
- 可变参数在字段中不带星号（写 :param args:），签名本身已展示星号。
- 已存在类型注解时省略 :type:/:rtype:，避免注解漂移，autodoc 可合并注解。
- 摘要行紧跟 """ 之后、以句号结尾，其后再空行；采用 PEP 257 祈使语气（如 “Return the first row.”）。
- 交叉引用角色：:mod:、:class:、:meth:、:func:、:attr:、:exc:、:data:、:obj:；目标加 ~ 前缀只渲染末段。短名在当前类、当前模块内解析，跨模块需完全限定。字面值用双反引号。
- :raises: 只记录调用者接口相关异常并写明触发条件；不记录因调用者违反契约而产生的异常；协议接口仅在抛出属于契约必需时才写。
- 统一使用 :param:、:returns:、:raises: 拼写，不使用别名，便于检索与评审。
使用方式：按上述约定撰写或改写 docstring；摘要默认单独成行，仅在有非显然行为、副作用、不变量或“为什么”时补充 1–3 句正文；字段规模与真实 API 面匹配；不重复类型到叙述文字中，描述补充单位、约束、缺省行为；摘要与字段列表之间留空行；行宽约 88 列，摘要须保持单物理行。
适用场景：为函数、方法、类及属性、property、生成器、类型别名、常量、TypedDict、@overload/Protocol 桩等编写契约文档，原则是在调用者接触的层级描述契约。
限制：未提供官方文本、安装命令、收费或平台信息；生成器不用 :yields: 字段，改在 :returns: 中描述迭代器。