Feature Spec Builder

把"只言片语"变成"研发级特性需求"。

核心不是写文档，而是系统性地把一句话里没说清楚的东西挖出来、补完整。一句"我需要 XX 功能"通常缺失 80% 的研发必需信息：角色、场景、边界、能力归属、接口、依赖、验收。本技能用"固定维度扫描 + 交互式逐问澄清"的方式补齐这些缺口，最终产出一份过得了研发评审的特性需求。

本技能产出止于特性需求——包含接口契约草案和验收标准，但不做任务拆分和实现计划，任务拆分交给研发团队。

配置区（首次使用前请填写）

本技能依赖一套产品自有坐标系与团队约定做归类与协同。请把占位符替换成你团队的真实定义；按主题分组，未用到的组可留默认。

A. 能力坐标系

L1 = <例如 原子能力 / 底层运动与感知接口>
L2 = <例如 组合能力 / 应用级开发包>
L3 = <例如 完整方案 / 场景交付>
五域：域1=<…> 域2=<…> 域3=<…> 域4=<…> 域5=<…>

B. 接口约定

API 预算 = <例如 300 个方法上限>   语言/绑定约定 = <例如 C++ core + pybind11>

C. 集成商与形态

集成商分级 = <例如 Associate / Professional / Expert>   形态 = <仿真 / 真机 / 两者>
产出输出目录 = <默认 feature-specs/；产出写到 <此目录>/<特性名>/<特性名>.md>

D. 产品原则（决定产出前自检 gate 的尺子）

采用内置默认原则：是 / 否（默认=是，全文见 references/product-principles.md）
团队自定义/补充原则：<可留空；填了则与内置默认合并，冲突以团队为准>
冲突优先级：<两条硬约束不可覆盖：安全默认、向后兼容均为红线，二者相撞必须升级人工拍板；其余原则的相对优先序请在此填，留空则相撞时一律抛回用户拍板，不自动排序>
破坏性变更签字人：<判定为 break 时需谁签字，例如 平台架构负责人>

E. 实现层 × 部门映射（第 4 步跨层分解指派 owner 用；与 L-Tier 正交——L-Tier 管对外抽象多高，实现层管对内动哪些技术栈、几个部门）

实现层 → 负责部门/角色 owner → 跨层签字人
  运行时层：
    二开 SDK 层            → <填，如 SDK/平台组>   → <签字人>
    底层软件(固件·中间件)  → <填，如 嵌入式/固件组> → <签字人>
    算法服务(感知·算法)    → <填，如 算法组>       → <签字人>
    硬件(机械·电子)        → <填，如 硬件/电子组>   → <签字人>
  非运行时层（生态/集成/文档类特性会落这里，别硬塞给固件/算法/硬件组）：
    文档门户层      → <填，如 DevRel/文档/站点前端> → <签字人>
    构建/分发基建层        → <填，如 SDK 构建/DevOps>      → <签字人>
  跨部门升级路径 = <例如 层 owner → 部门负责人 → 跨部门架构评审会 → CTO>

配置区未填怎么办： 至少补齐 A 组（能力层级 + 五域），这两项直接决定归类准确度。其余各组的降级处理——

A/B/C 未填：归类（自动归类步）时显式声明「以下 L 层级/域/预算/绑定为我的推断」并给依据；正文凡用到这套坐标系的字段（层级、能力域、API 预算、绑定约定，分布在《能力定位》《影响评估·兼容·发布策略》《接口契约草案》各节）一律打 [待确认]，绝不把推断值当已确认写；把「配置区真实值待补」写进《遗留待确认》节。

D 未填：默认套用 references/product-principles.md 的内置默认 10 条，并在《产品原则自检》节注明「本次采用内置默认产品原则」。产品原则自检 gate 任何情况下都要跑，绝不因配置区空着就略过。

E 未填：第 4 步跨层分解里的 owner/部门/签字人一律打 [待确认·需指派]，提示用户补，绝不臆造部门名——把推断的部门责任误派给错误的团队是最危险的失败。

F. 组织与流程（本地私有配置，公司级协作用）

各公司的"谁负责什么、过哪些流程 gate、版本怎么排"不同且私有，不写进本 skill。用于公司级协作时，把 references/org-process-config.md 的模板复制成本地 org-process.local.md（或跑 scripts/init-org-config.sh 生成），按你公司填角色地图 / 交付 gate / 版本节奏与管道容量。本地私有、勿提交（已在 .gitignore）。

有此配置：产出时按角色地图把 owner 落到真实责任人、在《影响评估·兼容·发布策略》列出必过 gate 与交付件、标注目标版本与工作量(人天)vs 管道容量、需求锁定后变更提示走 CCB（细则见 references/org-process-config.md）。

无此配置：用通用角色占位（如 [产品经理·待指派]），并提示用户可生成一份本地配置。任何情况下都不要把真实人名/内部流程写进 skill 或产出到要公开传阅的文档里。

工作流

收到一段零散需求后，严格按这条主链路推进：

接收片段 → 需求分流(识别隐含多特性) → 自动归类 → 跨层分解与路由(识别各层改动·owner·依赖序) → 第一层澄清(定位·粗) → 第二层澄清(功能细节·细) → 产出文档(过原则自检 gate)

第 1 步：接收与复述

读入用户给的片段。先用一句话复述你的理解（"我理解你要的是……，对吗？"），让用户确认或纠正。这一步防止从一开始就跑偏。

第 2 步：需求分流（识别是否隐含多特性）

一段零散诉求里常常裹着不止一个需求——尤其是从群聊/邮件原文粘来的片段，主诉求最显眼，但旁边还散落着别的诉求、被对话带偏的提问、或由目标反推出的隐含能力。别一头扎进最显眼的那个就开做，先做一次分流扫描：

通读片段，列出其中每一个可独立成立的诉求（一个动作／一个能力 = 一个候选特性）。特别留意四类常被漏掉的：① 被追问带偏的"最初那个提问"；② 与主诉求无关、只是同段对话顺带提到的独立诉求；③ 研发已回"暂不支持／自己实现"的点（往往是被埋掉的隐藏需求）；④ 由客户终极目标反推、但当前没明说的组合能力。
异构交付物启发式： 当一句诉求里同时出现不同交付物形态（可运行代码/接口契约/文档内容/站点结构/分发包）时，优先怀疑是多特性——不同交付物形态往往对应不同 owner、不同验收方式、不同维护周期，混写会让一份 md 里评审对象和验收标准打架（如"给个 ROS 示例 + 官网加个板块"= 代码特性 + 文档特性，owner 与验收根本不同）。
共享真相源的关联特性簇： 拆出的多个特性若共享单一真相源（如文档 tutorial = 示例仓代码 = 主特性契约的对外投影），仍各自独立成文，但须在每份《依赖与前置》/关联特性里显式钉死真相源归属（哪份文档/仓库拥有定义权，其余为投影/引用），并给一张簇内依赖图——复用《层间交接契约》的"定义权归属"范式，避免多份文档各写一版对不上。
若确实只有一个诉求，记一句"已确认单一特性"，直接进归类。
若有多个，画一张需求分流表（候选特性｜来源原话｜性质｜现状｜与主诉求的关系/依赖），然后让用户拍板本轮细化哪些——这是范围取舍，绝不自作主张替他圈定。未选中的，在《遗留待确认》节留"关联特性占位"，便于后续单独立项。
多特性一起做时，每个特性各自产出一份独立的特性需求文档，绝不把多个需求混写进同一份——逐个走完后续步骤，彼此只用「关联特性」互相指向、标清依赖（如 D 依赖 A+B）。（注意：一个特性哪怕跨层，也只出一份 md、内部分阅读对象成节，不拆成多个文件；这是"同一特性内部分层/分阅读对象"，与"多特性各自独立成文"不冲突。）

这一步是整条链路里最容易被跳过、却最影响交付正确性的一环：跳过它，研发拿到的需求可能只覆盖了客户诉求的一部分，或把几个本该独立的特性糊成一个。

第 3 步：自动归类

把需求钉到坐标系上：它落在 L1/L2/L3 哪一层、属于五域中的哪一域、是否跨域。归类本身就会暴露第一批隐含问题——如果你无法干净地归类，说明片段在某个维度上信息不足，这正是后面要澄清的缺口。把归类不确定的地方记下来。

注意：归类钉的是对外抽象层级（L-Tier）和能力域，不回答"这事对内要动哪些实现层、归哪个部门"——那是下一步第 4 步的事。一个 L1 接口可能只动二开层，也可能一路动到固件/算法/硬件。

L-Tier 对非运行时特性的 N/A 出口： 若特性本质是既有能力的交付/分发/安装/文档形态（非新运行时能力、不暴露 API、不占 API 预算，如离线安装包/示例仓/官网板块——原型 H/I），L-Tier 显式标 N/A（非能力特性，仅落实现层轴）、五域可标 N/A，不硬塞一个 L 值。判定信号：交付物是"分发包/文档/站点结构"而非"运行时 API/行为"；其重心转到构建/分发基建层或文档门户层 + 外部依赖轴（第 4 步）。

第 4 步：跨层分解与路由（跨层特性必做）

归类只回答"落在 L 几、哪个域"；本步进一步回答**"这个需求要动哪些实现层、各层归谁、谁先谁后、是不是光靠二开就能独立交付"**。很多客户需求看似落在二开 SDK 层，实则强依赖更底层——固件/中间件、算法服务、甚至硬件——而这些层往往归不同部门。

按 references/cross-layer-routing.md 的判定问题做五件事：

逐层判定要不要动：对二开 SDK 层 / 底层软件(固件·中间件) / 算法服务层 / 硬件层四个运行时层，逐层问"这一层需要改什么"。另外必问两类非运行时层（生态/集成/文档类特性重心常在这里）：文档门户层（官网板块、示例仓、文档 IA——owner 是 DevRel/文档/站点，不是研发）与构建/分发基建层（打包、多环境 CI、ABI/预编译——owner 是 SDK 构建/DevOps）。⚠ 交付物是示例/打包/安装/分发/文档时（原型 H/I），即使技术触底=纯二开，也不要默认派给二开 SDK 组——按配置区 E 组路由到对应 owner（硬塞给固件/算法/硬件组、或默认丢给二开组，都是高危错派）。能干净答"只动二开层、无门户/基建改动"的，记"单层特性（二开 SDK）"，直接进第 5 步。
定最底改动层（硬 gate）+ 可行性证伪：找出需要改动的最底层。一旦某层答"不支持/不确定"，沿二开→固件→算法→硬件逐层下探，直到触底（找到能支持的层或判定物理不可行）。给出层级触底结论(三选一)：A 纯二开可交付 / B 跨层可交付 / C 当前层级不可交付(下层未排期或物理限制)。若最底改动层不是二开 SDK 层，本特性就不是二开层能独立交付的——在文档显著位置打标：⚠ 非二开层可独立交付：本特性最底改动落在 <层>，需 <owner 部门> 先交付 <能力>，二开层才能封装，并写进《能力定位》节与 DoR。触到硬件/物理限制时，立即停止在二开层细化接口签名——继续写一个做不出来的契约草案是评审拒稿高频原因。
画跨层分解表 + 排依赖序 + 定层间交接契约：列出每层要改什么、owner 部门、是否阻塞上层；排出自底向上的依赖链；为每条跨层依赖钉一份「下层向上层暴露什么」的交接契约（含定义权归属——避免两部门各写一版对不上）。
识别 owner 与跨部门待确认项（每项必须带归属三元组）：哪些层的"要不要动/能不能支持"是你判断不了、必须找对应部门确认的（如"固件到底支不支持波束成形"），列成跨部门待确认项。本技能的使用者(通常是产品/SDK 侧)在会话里拿不到下层部门的真实答复，所以不能只打 [待确认] 丢进清单了事——每一项必须带三元组：验证 owner（谁去对接该部门）｜需在哪个评审节点前有答案｜未及时答复的默认假设/降级方案（与阈值类 [待确认] 的「定责人+定法+期限」同一范式）。它们往往是整个需求的关键路径阻塞点。
结论 B/C 必做：把真实可交付物回写主叙述（堵死「假就绪」）：一旦层级触底结论=B 或 C，必须回改《一句话定义》与 P1 故事，使其只描述本轮真实可交付物（如"本轮交付 SDK 桩+签名，波束实际能力依赖固件 Q4"），绝不按客户原始诉求的完整能力写 P1——否则研发/客户读到的就绪文档和实际能交付的对不上，正是最危险的假就绪。下层「不支持且未排期」时，必须在《跨层实现与跨部门协同》节给降级/分期方案（mock 桩 / 有限档位 / 仿真先行），不能只挂待确认。

结论 C 且二开层本轮无任何可独立交付物（含桩）的早停出口： 若证伪确认本特性当前实为下层/硬件改动、二开侧连桩都没意义，不要继续走第 5、6 步逐维澄清（那只会产出一份满是 [待确认] 的空壳，浪费交互预算、也违背范围纪律本身）。直接产出一份精简「跨层路由结论」：层级触底结论 + 跨层分解表 + 跨层阻塞与升级路径 + 给客户的口径，并显式标注"本需求当前不是二开层任务，建议转 <部门> 立项"。

产出形态：一个特性 = 一份 md（分阅读对象）。 无论单层还是跨层，一个特性都只产出一份特性需求文档；跨层/跨部门内容不拆成多个文件，而是在这同一份 md 内分阅读对象成节（产品/评审、二开 SDK、固件、算法、硬件），并在文档顶部给一张《阅读指引》把"阅读对象 → 该读哪些节 → 各自负责什么"列清，便于在一份需求文档里全程追踪。分阅读对象的节模板与阅读指引模板见 references/cross-layer-routing.md《九》。

产出填进输出模板的《跨层实现与跨部门协同》节。

本步结论会改写第 5、6 步要问的问题清单：例如客户要 set_microphone_beam_angle 波束接口，本步若核实出固件尚不支持波束成形，第 5 步就要先澄清"是否接受级联到算法/硬件、本轮范围是否仅做 SDK 占位"，而不是直接去问接口签名。

为什么单独成步、且排在定位之前： 一个"其实要动固件"的需求若被当普通二开特性走完，产出的会是一份"看着研发能接手、实则下层没这能力"的假就绪文档——这是最危险的失败模式。把这一步前置，就是在 DoR 之前先堵住"伪二开特性"。

仍遵守《交互式澄清规则》： 跨层分解表里凡 owner、某层是否需改、底层是否已支持属推断的，一律打 [待确认] 并作为澄清问题逐个抛回用户（一次一问、带候选），绝不把推断的部门/owner/依赖当已确认填表——这一步天然诱导你一口气列满 owner 表，那等于替用户拍板「谁是 owner、哪层要改」。

第 5 步：第一层澄清——定位（粗粒度）

拿《第一层 · 定位维度》当清单，逐条对照片段，把没回答的维度列出来，按《交互式澄清规则》逐个问清。这一层定的是特性的形状：它是什么、归哪层哪域、边界在哪、什么形态。一次只问一个问题。

把缺口分成两类：

阻塞性缺口：不补就没法继续归类或定义边界（例如：服务于哪类角色、核心行为是什么）。
非阻塞缺口：影响完整度但不影响主干（例如：某个边缘错误码、文档形式）。

第 6 步：第二层澄清——功能细节（细粒度）

定位清楚后，特性的形状已知，但研发还不能动手——因为还不知道它"具体怎么动"。这一层用《第二层 · 功能细节维度》深挖行为规格：正常流程怎么走、有哪些状态、异常怎么处理、边界场景怎么办、参数取值多少。

第二层的提问要因特性类型而异：导览类要问路径与到点逻辑，感知类要问误检与置信度，数据类要问 schema 与量级。具体的分类型提问库见 references/detail-probes.md——先判断这个特性属于哪个原型，再调对应的探针清单。

第 7 步：产出特性需求文档（含产品原则自检 gate）

阻塞性缺口补齐后，先过产品原则自检 gate，再按《输出模板》产出。

模板选择： 纯二开单层、缺口少的小特性走精简模板（《一句话定义》《来源背景》《能力定位》《范围边界》《故事+MVP》《行为规格》《接口契约》《依赖》《影响评估》《产品原则自检(一行结论)》《决策记录》《遗留待确认》，跳过《跨层实现与跨部门协同》和大部分按需 NFR）；跨实现层或重大特性走完整模板。两者共用同一套必答项与 DoR。

产出前必过：产品原则自检 gate。 取配置区《D. 产品原则》（未填则用 references/product-principles.md 的内置默认 10 条），对照本特性逐条给三态结论：✓符合 / ⚠违背-有取舍 / —不适用。三态判定细则、常见红旗清单、冲突优先级见 references/product-principles.md。任一条 ⚠ 必须在《产品原则自检》节写清取舍，并在《关键决策记录》节落一行（来源标"产品原则冲突取舍"，注明第几条）；全 ✓/— 的轻量特性可把自检压成一行结论，不必铺空表。

gate 不是 skill 自己打勾通过，而是把不达标项转成澄清问题或 [待确认] 抛回用户。 凡涉及取舍（要不要为兼容牺牲某能力、预算超了砍哪个、危险动作要不要加权限门），必须按《交互式澄清规则》一次一问、带候选，抛回用户拍板。

DoR 硬性要求：

任一原则标 ⚠ 而文档里找不到对应取舍说明 + 决策记录 → 不过 DoR，不得标"研发可接手/待评审"。
第 4 步层级触底结论为 B/C，而《一句话定义》或 P1 仍承诺下层未就绪的完整能力 → 不过 DoR（必须先按第 4 步第 5 小点回写为真实可交付物）。

通过 gate 后按选定模板生成文档，写入标准输出目录 feature-specs/<特性名>/<特性名>.md（不是只贴在对话里；位置约定见《输出模板》）；仍未解决的非阻塞缺口放进《遗留待确认》节，对正文受影响字段标 [待确认]，绝不凭空编造。

两层为什么分两个 pass： 一次会话问太多会让人疲劳（见澄清规则的总量上限）。建议第一层（第 5 步）问完先出一版"定位已定、行为待补"的草案，第二层（第 6 步）作为后续深挖 pass 再把行为规格补全、升级成研发级 v1.0。两层各自遵守总量上限，互不挤占。如果需求很小、缺口不多，也可以一口气两层跑完。

第一层 · 定位维度（粗粒度）

定特性的"形状"。对照片段逐条检查，缺失的就是要澄清的。分两组。

A 组 · 需求本质（What / Why / 边界）

角色与场景：谁在用？在什么场景下触发？（终端用户 / 集成商开发者 / 运维…）
核心行为：这个功能具体做什么动作？输入什么、产生什么结果？
范围边界：包含什么、明确不包含什么（这一条最容易被忽略，也最能防止研发自行脑补范围）。
成功判据：怎样算"做对了"？用什么可观测的指标衡量？

B 组 · SDK 工程定位

能力层级归属：落在 L1 / L2 / L3 哪一层？
五域定位：属于哪个能力域？是否跨域？跨域会牵动谁？
接口影响面：需要新增/修改哪些接口？是否冲击 API 预算上限？
底层依赖：依赖哪些已有能力、哪些尚不存在需要先建？
适用形态：仿真、真机，还是两者都要？两者的验收判据可能不同。
集成商可用性：目标是哪一级集成商能用？对应的封装/文档复杂度不同。
向后兼容：是否会破坏现有接口约定？是否需要版本化或迁移路径？若判定会 break，需顺带问清受影响的存量集成商/版本范围与可接受的弃用周期，不能只记一句"是否 break"。
文档与认证影响：是否需要新的开发者文档？是否进入集成商认证考核范围？
安全与权限（含物理改装）：这个能力对哪一级集成商/角色开放？是否涉及危险或高权限动作？安全风险有两类，都要强制问一次、不得默认放开——
- 危险软件调用：解锁速度/力矩上限、解除急停、直接底盘/关节控制、越过安全围栏 → 问"谁有权调、是否需二次确认/审计/权限门"。
- 危险物理改装（硬件末端/改装类特性，原型 J）：客户把自制硬件接到会运动、会伤人的机器人上 → 问承重/力矩/供电红线与超限后果、禁改区（哪些接口动了会解除急停/安全机制）、改末端后是否需负载重标定、改装授权/资质门槛、保修与责任边界、免责与合规声明、资料开放范围（角色分级/门控）。给错一个物理红线数字 = 人身安全 + 法律责任。

第二层 · 功能细节维度（细粒度）

定特性"具体怎么动"。这是让需求真正达到研发级的关键——下面每一条不定清，研发动手时都得自己拍脑袋。这些是通用维度，对照特性类型从 references/detail-probes.md 取分类型探针来具体提问。

正常流程分步：把核心行为拆成有序步骤，每步的输入、输出、前置条件分别是什么。
状态与生命周期：有哪些状态？状态机怎么转？start / pause / resume / stop / cancel 各自的语义、各状态下允许哪些操作。
触发与前置条件：什么条件下能启动？对系统/资源的前置要求？重复触发、并发触发怎么处理。
异常与失败处理：列出每一步可能的失败点，逐个定对策——重试 / 降级 / 中止 / 上报，以及由谁善后、状态如何收尾。
边界与边缘场景：空输入、极值、中途打断、资源不足（电量/算力）、外部条件突变时的行为。
参数细则：每个可配置项的单位、取值范围、默认值、非法值如何校验。
时序与性能约束：响应时间、超时阈值、吞吐、实时性要求。
并发与可重入：能否并行多实例？调用方多次调用同一接口怎么办？
可观测性：调用方需要哪些状态查询、事件/回调、日志或指标，才能感知特性的运行情况。可观测性分两层都要问——面向调用方（状态查询/事件回调/可定位日志，服务集成商感知运行状态）与面向平台运营（上线后用哪些指标/埋点判断这个特性健康度、被采纳率、失败分布，服务排障与决策），后者常被漏掉。

不必把 9 条全部问完才罢休。判断哪些对这个特性是关键的（异常处理对长时任务几乎总是关键，参数细则对纯查询类可能很轻），抓关键的问，其余合理留默认或打 [待确认]。

三条正交的轴，叠加使用： 上面九维 + detail-probes 的「特性原型 A~J」是按特性类型切的一条轴（H = 生态集成/参考实现/文档类；I = 打包/分发/离线安装/部署类；J = 硬件末端/物理接口规格与改装资料类，对外契约是机械/电气物理接口）；某特性还要不要跨实现层分解（动了二开层以外的层，含"文档门户层 / 构建·分发基建层"两类非运行时层，以及外部依赖/EOL 轴）是第二条轴，见第 4 步与 references/cross-layer-routing.md；有哪些非功能性需求(NFR) 与产品原则要过是第三条轴，见 references/product-principles.md。三者不互相替代，命中即叠加。

交互式澄清规则

这是把"简单"变"完整"的引擎，务必遵守：

一次一个问题。 问完一个，停下，等用户回答，再问下一个。不要一次甩出一串问题。
阻塞优先。 先问阻塞性缺口（角色、核心行为、范围边界、能力归属），再问非阻塞的。
每个问题都带"为什么问"和候选答案。 形如："这个功能主要服务于哪类角色？（这决定了它该封装到哪一层）A. 终端用户直接用 B. 集成商二次开发用 C. 内部测试用"。给候选答案能大幅降低回答成本，用户也可以选"以上都不是"并补充。
控制总量，防止疲劳。 每一层单次会话尽量不超过 7~8 个问题（两层各自计，互不挤占）。如果缺口太多，先补齐阻塞性的，其余打 [待确认] 标记，告诉用户"剩下的我先标记出来，你后续可以再补"。第二层细节问题尤其容易超量，挑对这个特性关键的问。
答完即复述确认。 用户回答后，用一句话复述你的理解再继续，确保没听岔。
绝不替用户拍板。 涉及取舍的问题（做不做某个边界、用哪种形态、谁是 owner、哪层要改）必须问，不能默认。把"还没确认的"显式标成 [待确认]，而不是悄悄填一个看起来合理的值。

写作与可读性（产出必须做到）

需求文档是给人读、要过评审的，不是把想到的点堆上去。产出前对照这三条：

说人话、逻辑连贯。 句子通顺、段落有主线，别"想一块写一块"地堆碎片。第一次出现的术语/缩写，要么就地一句点破，要么收进《名词解释》——别让读者卡在生词上。宁可多一句白话解释，少一句行话。
总背景 + 角色分节 + 术语，三段式。 一份文档 = ① 总背景（所有人先读：这是什么、为什么、给谁、交付什么 =《一句话定义》+《来源与背景》+《名词解释》）＋ ② 角色分节（《阅读指引》把后续各节按阅读对象分开，各角色只读自己那块，别让某个团队淹在跟他无关的细节里）＋ ③ 《名词解释》（术语单独讲清，面向看不懂的人）。
限对外交付形态、放开内部技术细节。 需求钉死"对外交付什么"——接口签名、产品形态、交付物形式、支持的平台/环境、验收标准；但不过度规定"内部怎么实现"——用哪个库、什么架构、哪种打包/编译工具，留给研发。每写一条问自己："这是对外契约，还是内部实现？"是内部实现就改成"由研发定"或降级为"建议（非强制）"，别把需求写成设计方案。
大白话是为了好懂，不是为了含糊——对外契约必须严谨。 行文用大白话，但凡涉及对外输出标准的——接口定义（签名/参数/返回/错误）、消息与数据格式、支持的平台矩阵要逐格列全、交付物形式、验收标准——必须精确、无歧义、可据以验收，该给签名给签名、该逐行列矩阵就列全。通俗归通俗，契约不能松。 按角色分章时，把这些严谨的契约集中在"对外契约"类章节，让研发/测试能照着实现和验证。

输出模板

阻塞性缺口补齐后（且过了第 7 步产品原则自检 gate），严格按此模板产出。模板内置一条 Definition of Ready——只有每一节都填实（或显式标记 [待确认]），这份需求才算"研发能接手"。

约定：

节不再硬编号，统一按节名引用，避免插节后节号错位。
精简模板=去掉《跨层实现与跨部门协同》与按需 NFR 维度后的同一套节，给纯二开单层小特性用；完整模板给跨层或重大特性用。
接口/参数命名全程遵循：全小写下划线（snake_case）、词意完整准确、禁用缩写（如 mic→microphone、cfg→config、num→count），并与同域既有接口保持一致。
一份文档只承载一个特性，且一个特性只出一份 md；多个特性各自独立成文（绝不混写），但一个特性哪怕跨层也不拆成多文件——跨层/跨部门内容在同一份 md 内分阅读对象成节。
产出落盘位置（标准输出目录，必须遵守）：产出写入文件（不是只贴在对话里）——落到输出目录 feature-specs/<特性名>/<特性名>.md（相对当前工作目录/仓库根；默认根 feature-specs/，团队可在配置区改）。一个特性一个子目录（便于放该特性的附图/子产物），文件名 = 特性名。多个特性各自独立子目录；关联特性之间用相对链接互指。
跨层（结论 B/C）特性：在本模板顶部加一张《阅读指引（分阅读对象）》，并在《跨层实现与跨部门协同》节把各层内容按【阅读对象：X组】分节承载（模板见 references/cross-layer-routing.md《九》）——全部在这一份 md 内，不另拆文件。

# 特性需求：[特性名称]

> 状态：草稿 / 待评审 / 已确认　｜　提出方：[客户/合作伙伴]　｜　日期：YYYY-MM-DD　｜　模板：完整 / 精简

## 阅读指引（分阅读对象）
> **怎么读**：先读**总背景**（《一句话定义》《来源与背景》《名词解释》，所有人都读）；其余各节按下表**各读各的**、不必读全篇。跨层/跨部门特性务必填此表；纯单层小特性表可精简，但总背景与《名词解释》仍要有。
| 阅读对象 | 重点读哪些节 | 你负责什么 |
| --- | --- | --- |
| 产品 / 评审 | 一句话定义、来源背景、能力定位、范围边界、故事+验收、影响评估、产品原则自检、决策记录、遗留 | 确认范围/优先级/取舍 |
| 二开 SDK 组 | 接口契约、行为规格、《跨层实现与跨部门协同》·二开节 | 对外封装与接口契约 |
| 固件组 | 《跨层实现与跨部门协同》·固件节、层间交接契约 | 确认/开放下层能力接口 |
| 算法组 | 《跨层实现与跨部门协同》·算法节 | 算法能力就绪/适配 |
| 硬件组 | 《跨层实现与跨部门协同》·硬件节 | 硬件形态/物理边界 |
| 测试 / QA | 验收标准、对外契约（接口/消息/平台矩阵）、待确认 | 照验收标准与契约设计测试、覆盖全平台矩阵 |
（角色**按特性类型选**：运行时特性=各实现层；交付/集成/安装类=打包·DevOps／文档／测试 等。**测试/QA 始终作为一个角色纳入**——它关心验收怎么测、要覆盖哪些平台、对外契约是否可测。不涉及的角色整行删去。**正文尽量按角色分章**，让每个角色能整块读自己那部分。）

## 一句话定义
[What —— 这个特性做什么，一句话讲清。⚠ 若第 4 步层级触底结论为 B/C，这里只写本轮真实可交付物，不写下层未就绪的完整能力]

## 来源与背景（Why）
- 原始诉求：[客户/合作伙伴最初那句话，照原意保留]
- 业务场景：[谁、在什么场景下、要解决什么问题]
- 价值：[为什么值得做]

## 名词解释（术语）
> 文档里会用到、非本领域读者可能看不懂的术语/缩写，一词一句白话讲清（面向不同角色，别默认大家都懂）；没有生词写"无"。
| 术语 | 一句话说明 |
| --- | --- |
| … | … |

## 能力定位
- 层级：L1 / L2 / L3　[配置区 A 组未填则打 [待确认]；**若为交付/分发/安装/文档类非运行时特性则标 `N/A（非能力特性，仅落实现层轴）`**]
- 能力域：[五域之一，或"跨域：X + Y"，或 N/A]
- 跨域影响：[会牵动哪些其他域/团队]
- 跨层结论（第 4 步）：单层特性（二开 SDK） / ⚠ 非二开层可独立交付：最底改动落在 <层>，需 <部门> 先交付 <能力>，二开层才能封装

## 范围边界
- 包含（In Scope）：
  - …
- 明确不做（Out of Scope）：   ← 必填，防止研发误扩范围
  - …
- 关联特性占位（来自需求分流、本轮不做）：
  - …

## 跨层实现与跨部门协同
> 仅当第 4 步判定本特性跨实现层（动了二开 SDK 层以外的层）时必填；纯二开单层写「单层特性（二开 SDK），无跨层协同」并跳过本节（精简模板直接不含本节）。
> **产出形态：** 一个特性只出一份 md；本节承载跨层/跨部门内容，各需改动层按【阅读对象：X组】分节（handoff、待确认、本层验收各归其节），配合文档顶部《阅读指引》即可让各团队在同一份文档里找到并追踪自己那部分，不另拆文件。

### 跨层分解表
| 实现层 | 本层要改什么 | 是否真要动 | owner(部门/角色) | 依赖/被谁阻塞 | 是否本轮范围 |
| --- | --- | --- | --- | --- | --- |
| 二开 SDK | … | 是/否 | [配置区 E 组，推断打[待确认]] | 被『固件/算法』阻塞 | 是/否 |
| 底层软件(固件·中间件) | … | 是/否/[待确认] | … | 阻塞二开层 | … |
| 算法服务层 | … | 是/否/[待确认] | … | 阻塞二开层 | … |
| 硬件 | … | 是/否/[待确认] | … | 阻塞固件层 | … |
- **最底改动层**：[填] ｜ **层级触底结论**：A 纯二开可交付 / B 跨层可交付 / C 当前层级不可交付 ｜ **是否二开可独立交付**：是 / ⚠ 否（需 <部门> 先交付 <能力>）
- **结论 B/C 回写检查**：《一句话定义》与 P1 是否已改为只描述本轮真实可交付物？ 是 / 否（否=不过 DoR）

### 跨层依赖链与顺序
> 自底向上读：下层就绪是上层启动的前置。
- 依赖链：[硬件/固件 X] → [算法 Y] → [二开 Z]
- 可并行启动：[不互相阻塞、各部门可同时推进的项；如对外接口设计/桩可与下层开发并行]
- 关键路径阻塞点：[最可能卡住整体进度的那一环 + 当前确认状态]
- 上层不可启动条件：[下层哪些未就绪前，上层联调/真机验收不可启动]

### 层间交接契约（Handoff，每条跨层依赖一份）
> 把「下层向上层暴露什么」讲死，并钉死**定义权归属**，避免两部门各写一版对不上。
- **[下层 → 上层] <能力名> handoff**
  - 定义方（拥有定义权的层/部门）：[未达成一致则标 `[待确认·需 X 与 Y 对齐]`]
  - 下层暴露：[接口/数据/能力，签名级]
  - 输入：[类型/单位/范围/坐标系/默认值] ｜ 输出：[…] ｜ 非法输入语义：[拒绝/钳制/就近吸附；失败时原值是否保持]
  - 标称范围 vs 实际档位：[对外声明范围与底层真实可达分辨率/档位是否一致；不一致如何映射]
  - 单位/坐标系换算责任在哪层：[上层透传 / 上层转换 / 下层适配]
  - 同步/异步、生效时机、掉电是否保留：[…]

### 协同治理（owner / 签字 / 升级）
> 默认只需这张**轻表**——谁负责、谁签字、卡了找谁，对「产出止于特性需求」的阶段已够用。
| 实现层/事项 | owner(部门/角色) | 跨层签字人 | 升级路径 |
| --- | --- | --- | --- |
| … | … | [配置区 E 组] | [配置区 E 组升级路径] |
> **RACI（可选，仅大型跨四层需求按需展开）：** 若需求确实涉及多部门并行执行、责任易扯皮，再补一张 R(执行)/A(担责签字)/C(被咨询)/I(被知会) 表；否则不强制填，避免大量格子是 [待确认] 的低密度信息。

### 跨层阻塞与降级（有未排期下层依赖时必填）
> 把「已知阻塞」与「信息待确认」分开。每个阻塞独立成行，必须给降级/分期方案，且每个跨部门待确认项必须带「验证 owner｜需在哪个评审节点前有答案｜未答复的默认假设/降级」三元组。
| 阻塞/待确认项 | 验证 owner(谁去对接) | 需在哪个评审节点前有答案 | 对客户的影响 | 降级/分期方案(未答复也按此走) | 升级路径 |
| --- | --- | --- | --- | --- | --- |
| … | … | … | … | ①先交 mock 桩 ②有限档位 ③仿真先行/真机待下层 | … |

### 各层各自的验收
> 跨层特性不能只有对外整体验收，每层要有可独立验证的判据，否则无法定位卡在哪层。
- 硬件层：… ｜ 固件层：… ｜ 算法层：… ｜ 二开层（对外）：…

## 开发者/集成商故事（按 P1/P2/P3 优先级，每条可独立交付）
- **[P1]** 作为 <角色>，我希望 <能力>，以便 <目的>
  - 验收标准（可衡量、技术无关；**至少含一条 DX 验收**：命名/参数风格与同域既有接口一致、零配置默认行为安全、失败返回信息可让开发者自行定位根因）：
  - 优先级依据：[客户硬需求/合规必须 vs 增强项，来源]
  - 仿真判据：[测试数据/样本量 ｜ 前置环境/场景前提 ｜ 判定方法与工具(谁判/用什么量) ｜ 通过阈值及来源]
  - 真机判据：[同上四子字段]
- **[P2]** …
> ⚠ 若第 4 步层级触底结论为 B/C，P1 只能写本轮真实可交付物（如 SDK 桩+签名），不得把下层未就绪能力写成 P1。对客户呈现口径（标称范围 vs 实际档位）不一致时，验收按"实际能力边界"写，不得按标称范围写。阈值类 `[待确认]` 必须带「定责人 ｜ 定法(基准/实验/标定) ｜ 期限」闭环，否则该验收视为不可执行。

### MVP 最小切分
- 本轮最小可交付集(MVP) = [构成最小可用闭环的 P1 条目]
- 砍到 MVP 后是否仍对客户成立：[是/否 + 理由]
- 明确推迟到下一迭代：[哪些 P2/P3，为什么可以等]

## 行为规格（Behavioral Spec —— 第二层澄清的产出）
> 这一节决定研发能否真正动手；按第二层澄清到的细节填实。
- 正常流程：[核心行为的有序步骤]
- 状态与生命周期：[状态机；start/pause/resume/stop/cancel 语义]
- 异常与失败处理：[失败点 → 对策（重试/降级/中止/上报）]
- 边界与边缘场景：[空输入、极值、中途打断、资源不足等的行为]
- 参数细则：[每个可配置项的单位、范围、默认值、校验]
- 时序与性能约束：[响应/超时/吞吐/实时性]
- 并发与可重入：[多实例/重复调用的行为]
- 可观测性：面向调用方[状态查询/事件回调/可定位日志] ｜ 面向平台运营[指标/埋点/采纳率/失败分布]

## 非功能性需求(NFR) 与上线就绪
> 维度清单见 references/product-principles.md。**安全与权限、数据与隐私、运营可观测、MVP 切分为每个特性必答**（确实不涉及的可一行带过写「不涉及/本特性不采集敏感数据」，但不得留空）；其余按命中填或打 [待确认]。精简模板保留这四项必答，跳过下面的[按需]维度。
- 安全与权限：访问控制(对哪级集成商开放) ｜ 危险/高权限动作 → 权限门/二次确认/审计 ｜ 鉴权失败时安全态(必须安全侧失败)
- 数据与隐私/合规：采集的数据项与敏感级别 ｜ 存哪/留多久/是否出域/加密脱敏 ｜ 合规(个保法/GDPR/行业)与同意流程 ｜ 数据主体删除响应（不采集敏感数据则一行写「本特性不采集个人/敏感数据」）
- 运营可观测：上线后用哪些指标/埋点看健康度与采纳率 ｜ 关键告警阈值 ｜ 出问题如何复现采集现场
- 性能与容量[按需]：关键路径目标时延/吞吐/启动 + 测量条件 + 不达标对策 ｜ 资源占用(CPU/内存/算力/带宽/电量) ｜ 硬件/固件/平台依赖与可移植

## 接口契约草案（不写实现）
> **接口契约有两类，看特性而定**：
> - **软件接口**（多数特性）：名称 ｜ 输入 ｜ 输出 ｜ 错误码 ｜ 同步/异步；签名级、精确。
>   - 命名与绑定约定：**接口/参数全小写下划线（snake_case）、词意完整准确、禁用缩写**（如 `mic`→`microphone`、`cfg`→`config`），与同域既有接口一致；按 [配置区 B 组 语言/绑定约定，如 C++ core / pybind11]。
> - **物理接口**（硬件末端/改装类特性，原型 J）：契约是**机械 + 电气接口**，不套软件字段——
>   - 机械：安装法兰/接口标准 ｜ 螺栓孔位阵列与螺纹 ｜ 定位销 ｜ 尺寸与**公差带** ｜ **最大承重（静/动态）** ｜ **各轴力矩上限** ｜ 质心/惯量 ｜ 安装姿态。
>   - 电气：连接器**厂商料号+配对件** ｜ **pinout 逐针脚（编号↔信号↔电平）** ｜ 线序 ｜ **供电电压/电流/功率包络（含峰值）** ｜ 通信协议 ｜ 接地/屏蔽。
>   - 按**型号 × 硬件版本/批次**锁矩阵；标适用硬件版本/序列号区间/固件依赖；数据源头（工程图纸/PCB/BOM）与背书人写清。探针见 detail-probes 原型 J。
> 无论软硬件，接口契约都是**对外输出标准**，必须精确、无歧义、可据以实现或加工验收（见《写作与可读性》）。

## 依赖与前置条件
- 依赖的已有底层能力：
- 需先建的能力：
- 硬件 / 仿真前提：
- 外部依赖：

## 影响评估 · 兼容 · 发布策略
- API 预算影响：新增约 N 个方法（上限 [配置区数值]，占用后约 X%）
  - 是否考虑过复用/重载/合并现有接口：[是/否 —— 结论或为何无法复用]
  - 这几个新方法值得占永久预算的理由：[…]
- 向后兼容：[纯新增 / 破坏性变更]
  - 若 break：迁移路径 [...] ｜ 弃用窗口 [...] ｜ 受影响存量版本/集成商范围 [...] ｜ 兼容垫片/迁移成本 [...] ｜ 需签字人：[配置区 D 组 破坏性变更签字人]
- 发布策略[按需]：是否灰度(按集成商/场景/版本) ｜ 特性开关(默认开/关、谁控制) ｜ 回滚方案(如何一键回退、有无状态残留) ｜ 降级行为(依赖不满足时优雅降级到什么程度，对齐异常处理)
- 文档与认证影响：[需新增文档？是否进认证考核]
- 版本与流程协同[有本地 org-process 配置时填，见 references/org-process-config.md]：目标版本 ｜ 工作量估分(人天) vs 管道容量 ｜ 必过流程 gate 与交付件(需求锁定/设计评审/自测报告=提测入口/需求验收/发版评审…) ｜ 需求锁定后变更是否需走 CCB ｜ owner 按角色地图落到真实责任人(无配置留 [角色·待指派])

## 产品原则自检（Product Principles Gate）
> 产出前对照《产品原则》逐条核对的结论。本次依据：团队自有原则 / 内置默认 10 条（二选一注明）。
> **轻量特性（全 ✓/—）写一行即可：** 「本特性已逐条过 N 条原则，无 ⚠。」 **只有出现 ⚠ 时才展开下表**（⚠ 项必须在「说明」列写清取舍，并在《关键决策记录》节有对应行）。
| 原则 | 结论(✓/⚠/—) | 说明（⚠ 必填：违背什么·为何·取舍） |
| --- | --- | --- |
| 1 分层完整性 | | |
| 2 单一职责 | | |
| 3 API 预算纪律 | | |
| 4 向后兼容 | | |
| 5 最小惊讶/DX | | |
| 6 安全默认/最小权限 | | |
| 7 可观测且可度量 | | |
| 8 范围纪律/MVP | | |
| 9 可演进性 | | |
| 10 决策可溯源 | | |

## 关键决策记录
| 决策点 | 结论 | 依据 / 来源 | 涉及原则 |
| --- | --- | --- | --- |
| … | … | （客户提出 / 澄清确认 / 团队约定 / 产品原则冲突取舍） | （如适用，注明第几条） |

## 遗留待确认
- [ ] …

关键决策记录规则（简化版溯源）

不逐字保存所有原话，只记关键决策：凡是在澄清过程中做出取舍、定边界、定优先级的地方，记一行进《关键决策记录》节，写清"决策点 / 结论 / 依据"。依据里简要点明来源，方便后续评审追溯"这条为什么这么定"，但不做逐字档案。

溯源来源分四类：客户提出 / 澄清中确认 / 团队约定 / 产品原则（注明第几条）。第四类——「因为单一职责所以拆开」「因为预算纪律所以复用」这类不是客户要求、也非临时澄清、而是「平台原则本就这么定」的决策，归此类，避免被误读为拍脑袋。因原则冲突而做的让步，注明让位关系（哪条让位于哪条）。

双语处理

默认输出中文全文。如果用户标明这份需求要给海外合作伙伴（partner-facing），额外在文档顶部生成一段英文摘要（覆盖《一句话定义》《范围边界》《开发者/集成商故事》三节的要点：定义、范围边界、核心验收标准），正文保持中文。用户也可要求全文英文。

续接已有需求

如果用户给的是一份已有的特性需求文档 + 一段新补充，则进入续接模式：在已有文档基础上做缺口扫描和交互澄清，把新内容并入对应章节，保持术语/编号/优先级一致，并在《关键决策记录》节追加新的决策记录。不要重写已确认的部分。

一个简短示例

用户输入： "客户说想要个迎宾导览功能。"

第 1 步复述： "我理解是：机器人在入口接待来访者，并带领他们到目的地。对吗？"

第 2 步分流： 通读后只有"迎宾导览"一个可独立成立的诉求，记一句"已确认单一特性"，直接进归类。（若片段里还夹着"顺便也要个充电桩对接"之类，这一步就要拆成分流表让用户挑本轮做哪个。）

第 3 步归类（暴露缺口）： "迎宾导览"既可能是 L2 应用包，也可能是 L3 完整方案——取决于客户要的是一个可二次开发的能力组件，还是开箱即用的交付。这是第一个阻塞性缺口。

第 4 步跨层分解： "迎宾导览"主要落在二开 SDK 层（组合导航与交互的应用包），不级联固件/算法/硬件改动，记一句"单层特性（二开 SDK）"，跳过《跨层实现与跨部门协同》节，直接进第 5 步定位澄清。（若它依赖一个尚不存在的底层能力——如某种新传感器——这一步就会把它打成跨层、转 references/cross-layer-routing.md。）

第 5 步逐问（一次一个）： "客户要的是一个集成商能拿去二次开发的能力包，还是一个开箱即用的成品方案？（这决定它归 L2 还是 L3）A. 能力包，集成商自己搭场景 B. 成品方案，直接部署 C. 还不确定，需要我帮你分析两种的差异"

……（逐个补齐角色、场景、边界、形态、接口……进入第 6 步深挖行为规格）

第 7 步： 先过产品原则自检 gate，再按（精简）模板产出特性需求文档。

完整的端到端示例见 references/example.md（单层，原型无）、references/example-ros-integration.md（原型 H）、references/example-offline-install.md（原型 I）、references/example-hardware-mod.md（原型 J），以及 references/cross-layer-routing.md《八》节 set_microphone_beam_angle 端到端示例（跨层）。

Auromix/feature-spec-builder

Ask in your favorite AI

Dokumentation