Files
frontend/Client/docs/requirements-contract.md

6.5 KiB
Raw Permalink Blame History

前台机器人需求解析与匹配 JSON

本阶段在前台测试需求整理,尚未提交业务匹配。用户文字/图片 → 豆包解析 → 服务端共享程序校验 → 可读清单 → 补充确认。规则已独立为 ai-rules/robot-demand-parser-v1/,后续由业务后端运行同一套解析与校验,前台收取结果。详见包内 backend-handoff.md。

发给后端的标准结构

固定五个顶层字段,保持已讨论的字段名:

{
  "userInput": "我要一个双足跑步机器人,整体20自由度,质量不超过10kg,躯干用铝合金,右臂扭矩至少20N·m",
  "requirements": ["双足", "机器人", "跑步"],
  "requiredParts": [
    "TORSO_0",
    "HEAD_0",
    "WAIST_0",
    "ARM_L",
    "ARM_R",
    "HAND_L",
    "HAND_R",
    "LEG_L",
    "LEG_R",
    "FOOT_L",
    "FOOT_R"
  ],
  "robotRequirements": {
    "degreesOfFreedom": 20,
    "functionDescription": "跑步",
    "massKg": 10,
    "operators": { "massKg": "lte" }
  },
  "partRequirements": [
    { "category": "TORSO_0", "material": "铝合金" },
    { "category": "ARM_R", "torqueNm": 20, "operators": { "torqueNm": "gte" } }
  ]
}
  • userInput:全部用户轮次原文按换行合并,保留可追溯输入。整段解析的字段以当前有效需求为准,明确修改覆盖旧值。助手的回复不混入用户原文。
  • requirements:去重的语义关键词/需求短语数组。包括主体、形态、动作、场景、仿生对象、定性偏好、禁止项以及暂无属性字段承载的需求。实际输出可以比示例更多,不能删掉“跑步”“不要飞行”等信息。
  • requiredParts:根据已配置机器人类型展开的候选零件分类数组,不是库存记录、BOM数量或装配关系。
  • robotRequirements:整机要求。允许 componentName、degreesOfFreedom、material、functionDescription、shape、size、torqueNm、massKg、description。
  • partRequirements:指定零件要求,除上述属性外必须带 category。双臂同要求展开为两条,单臂左右不明先澄清。

未明确给出的属性一律省略;不能把未知填成0,明确的0必须保留。数值是JSON number,质量统一kg,扭矩统一N·m,自由度为非负整数。大小保留完整维度和单位文本。比较默认eq,非等值用operators里的lte/gte。严格小于/大于、双边区间、文本排除等现有结构尚不能无损表达的条件保留在解析依据中,并标记待澄清,禁止复制/下载为可提交匹配结果,不能偷偷放宽。

前台规则与约束

规则与目录位于 ai-rules/robot-demand-parser-v1/,仅在服务端加载并完成校验,不进入浏览器打包产物。前台通过通用SSE事件接收阶段进度和经校验的需求结果,不透传供应商协议。

  1. 事实与推断分开:每个关键词标明explicit/inferred、原文证据及简短依据。证据必须是用户某条输入的连续文字。数值验证必须能在对应证据中找到相同单位换算后的值,不能编造参数。
  2. 深度拆分:主体、仿生对象、形态、动作、功能、环境、任务、材料、自由度、质量、扭矩、尺寸,以及载荷、速度、续航、数量、预算等无法由现有字段表达的需求,都要保留。不会擅自补常识数值。
  3. 区分范围:整机质量/整体自由度与单个零件约束分开;两臂总质量不能给两侧各赋同一个值;范围不明先问。
  4. 保留否定和限定:不要、至少、最多、整体、每个、尽量都不能丢。偏好不升级为硬阈值。明确排除的零件从模板剔除;同一零件同时要求和排除则阻止提交。
  5. 兼容候选:“仿生鸟类的机器”保留仿生、鸟类、机器人,并将可能飞行和双足标为推断,可展开双足候选。飞行/鸟形列为待核实能力,不声称双足候选满足飞行。企鹅、鸵鸟或明确不飞行时不推断飞行。推断不能写成硬数值/功能筛选。
  6. 目录边界:当前只有已讨论的双足模板,含11类零件。尾可明确补入。四足、轮式、履带、翅膀等未配置类型不会凭空造分类或套双足模板。后续直接修改配置,类型id由schema枚举限制,模型不能自造。
  7. 程序校验:JSON/schema结构、允许字段、分类、左右、证据、数值单位、后端精度、条件合并与矛盾检测。失败/中断/待澄清结果不变成可提交数据。语义准确性还需用户核对,不能用格式校验宣称所有机械需求必然正确。
  8. 装配边界:解析输出不含坐标、偏移、父子关系或安装点选择。未来拿到后端URDF后,LINK#id_HEAD_0 只识别类型 HEAD_0;定位仍使用机械文件的完整原始变换和明确的跨文件配对规则。名字本身不能证明装配方向正确;多接口/多候选不可凭空选择。

展示与未来匹配

前台显示摘要、可读需求清单、关键词和推断标记、待补充问题、来源与图片识别。只有可确认结果可复制/导出需求清单文本,不提供内部JSON调试或规则下载入口。匹配尚未接入时仍明确区分需求确认和实际装配。

业务后端保留 result.request 五字段,同时必须保存并读取 result.analysis 的详细需求、来源、硬要求/偏好和未覆盖能力,避免只按关键词丢失条件。不能把所有requirements按AND过滤导致只能全命中;完整匹配无结果时,按类型/形态降级找候选属于后端匹配策略,必须返回未满足项并保留原意,不能把部分匹配宣称为完全满足需求。前台不自行筛选库存或伪造匹配结果。若后端需要结构化区分硬/软关键词或支持范围/排除操作,需再明确增加的接口字段;现有五字段不能凭空表达所有高级比较。

验证

npm test 不调用收费模型,覆盖标准示例、鸟类软候选、显式排除、中文数值、单位换算、矛盾、范围、未知分类、证据与数值编造、历史修改、SSE中断、密钥隔离和无联网工具。

node tests/live-analysis.mjs 为显式运行的真实豆包评估,会消耗模型额度;覆盖仿生鸟、企鹅/否定、双臂与多轮改口、无法无损表达的范围。结果保存到 docs/analysis-examples/ 供核对,不作为用户项目数据或库存。

模型结构化输出协议参照方舟结构化输出文档。