工业机器人编程与仿真工具最难处理的反馈，往往不是崩溃，而是一句：

“这个轨迹不对，现场用不了。”

研发看到这句话，会继续追问机器人型号、控制器版本、坐标系、场景文件和复现步骤；用户则可能担心项目文件包含产线布局、工艺参数，不愿意整体上传。最后，双方在聊天、邮件和群消息之间来回补充信息，真正需要解决的问题反而被淹没。

这里的矛盾不是“缺少一个反馈按钮”，而是两件事同时存在：

1. 研发需要足够的运行上下文，才能复现问题；
2. 用户需要知道系统收集了什么，并保留发送决定权。

本文实现一种更适合编程与仿真工具的入口：**用户在当前任务节点发起反馈，系统生成一份可预览、可删减的场景快照，再把它交给明确的责任人。**它既能承接故障，也能为功能需求分析积累结构化证据。

---

一、先决定什么时候出现入口

反馈入口不应只放在全局导航栏。对于流程型工具，更有效的做法是把入口放在容易产生判断分歧的节点旁边。

以机器人离线编程流程为例，可以选取以下检查点：

检查点	用户可能遇到的问题	默认采集的上下文	建议负责人
导入机器人模型	型号缺失、关节限制异常	品牌、型号、模型版本	设备适配
配置工具与工件坐标系	位姿方向不符合预期	坐标系名称、变换矩阵摘要	场景建模
生成运动轨迹	轨迹绕行、奇异点、不可达	规划器、速度参数、失败点位	运动规划
碰撞检测	漏报或误报	碰撞对、检测精度、场景指纹	仿真内核
导出控制器程序	指令不兼容、格式错误	控制器类型、后处理器版本	程序导出

这张表同时解决了“入口放哪里”和“消息归谁管”两个问题。

如果当前团队还不能为某个入口指定责任人，就先不要增加该入口。无人负责的渠道并不会帮助需求分析，只会制造新的消息库存。

二、定义最小场景快照，而不是上传整个工程

场景快照的目标是定位问题，不是复制用户的完整项目。可以把提交内容拆成四层：

用户描述
  └─ 任务上下文：处于哪个工作步骤
      └─ 环境上下文：软件、机器人、控制器版本
          └─ 可选诊断材料：日志、截图、脱敏后的场景片段

推荐的数据结构如下：

{
  "idempotencyKey": "01JZ8YB2W9XQ8G5M7R6K3N4P1A",
  "kind": "simulation_mismatch",
  "checkpoint": "collision_check",
  "summary": "末端执行器接近夹具时未提示碰撞",
  "expected": "距离小于安全间隙时显示碰撞警告",
  "actual": "仿真继续运行且结果面板无告警",
  "context": {
    "appVersion": "3.4.1",
    "robotVendor": "vendor-a",
    "robotModel": "model-x",
    "controllerFamily": "controller-y",
    "planner": "rrt-connect",
    "sceneFingerprint": "sha256:8da6...",
    "activeTool": "gripper-02",
    "locale": "zh-CN"
  },
  "attachments": {
    "includeScreenshot": true,
    "includeRecentLogs": false,
    "includeSceneFile": false
  }
}

其中有三个设计点值得保留：

• sceneFingerprint 只用于判断两次反馈是否来自同一场景版本，不上传场景内容；
• 日志、截图和工程文件分别授权，不能合并成一个模糊的“同意上传诊断信息”；
• expected 与 actual 分开填写，避免把用户预期误当成软件承诺。

场景指纹的生成

浏览器或 Electron 渲染进程可以对不敏感的场景元数据计算摘要：

async function sha256(input: string): Promise<string> {
  const bytes = new TextEncoder().encode(input);
  const digest = await crypto.subtle.digest("SHA-256", bytes);
  return [...new Uint8Array(digest)]
    .map(b => b.toString(16).padStart(2, "0"))
    .join("");
}

async function buildSceneFingerprint(scene: {
  revision: string;
  robotModel: string;
  objectIds: string[];
}) {
  const canonical = JSON.stringify({
    revision: scene.revision,
    robotModel: scene.robotModel,
    objectIds: [...scene.objectIds].sort()
  });

  return `sha256:${await sha256(canonical)}`;
}

不要把工件名称、客户名称、路径坐标等敏感信息拼进摘要原文。哈希不是匿名化：输入范围较小时，仍可能被枚举推断。

三、实现“先预览、再发送”的前端采集器

下面以 TypeScript 为例。采集器只读取允许进入反馈系统的字段，避免直接序列化整个应用状态。

type FeedbackDraft = {
  idempotencyKey: string;
  kind: "bug" | "simulation_mismatch" | "feature_request";
  checkpoint: string;
  summary: string;
  expected: string;
  actual: string;
  context: Record<string, string>;
  attachments: {
    includeScreenshot: boolean;
    includeRecentLogs: boolean;
    includeSceneFile: boolean;
  };
};

export async function createFeedbackDraft(app: AppState): Promise<FeedbackDraft> {
  return {
    idempotencyKey: crypto.randomUUID(),
    kind: "simulation_mismatch",
    checkpoint: app.workflow.currentCheckpoint,
    summary: "",
    expected: "",
    actual: "",
    context: {
      appVersion: app.version,
      robotVendor: app.robot.vendorCode,
      robotModel: app.robot.modelCode,
      controllerFamily: app.controller.family,
      planner: app.motionPlanner.name,
      sceneFingerprint: await buildSceneFingerprint({
        revision: app.scene.revision,
        robotModel: app.robot.modelCode,
        objectIds: app.scene.objects.map(item => item.id)
      }),
      locale: navigator.language
    },
    attachments: {
      includeScreenshot: false,
      includeRecentLogs: false,
      includeSceneFile: false
    }
  };
}

反馈面板至少需要提供以下交互：

1. 展示即将发送的上下文字段；
2. 允许用户删除非必填字段；
3. 三种附件分别勾选；
4. 明确提示工程文件可能包含工艺或布局信息；
5. 提交后显示反馈编号，而不是只弹出“发送成功”。

对现场网络不稳定的环境，还应先写入本地待发送队列，再尝试请求服务端。一个简化实现如下：

const OUTBOX_KEY = "feedback-outbox-v1";

function readOutbox(): FeedbackDraft[] {
  return JSON.parse(localStorage.getItem(OUTBOX_KEY) ?? "[]");
}

function saveOutbox(items: FeedbackDraft[]) {
  localStorage.setItem(OUTBOX_KEY, JSON.stringify(items));
}

export async function submitWithOutbox(draft: FeedbackDraft) {
  const outbox = readOutbox();
  if (!outbox.some(item => item.idempotencyKey === draft.idempotencyKey)) {
    outbox.push(draft);
    saveOutbox(outbox);
  }

  const response = await fetch("/api/feedback", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(draft)
  });

  if (!response.ok) throw new Error(`submit failed: ${response.status}`);

  saveOutbox(
    readOutbox().filter(item => item.idempotencyKey !== draft.idempotencyKey)
  );

  return response.json();
}

正式桌面应用建议改用 IndexedDB 或 Electron 主进程中的加密存储。localStorage 适合演示数据流，不适合保存日志、截图和工程文件。

四、服务端用幂等键防止重复反馈

现场断网重试很容易把同一条问题提交多次，因此不能只依赖前端按钮防抖。数据库应给幂等键增加唯一约束。

PostgreSQL 表结构示例：

CREATE TABLE feedback_reports (
    report_id UUID PRIMARY KEY,
    idempotency_key UUID NOT NULL UNIQUE,
    kind VARCHAR(32) NOT NULL,
    checkpoint VARCHAR(64) NOT NULL,
    summary TEXT NOT NULL,
    expected TEXT NOT NULL DEFAULT '',
    actual TEXT NOT NULL DEFAULT '',
    context JSONB NOT NULL,
    attachment_manifest JSONB NOT NULL,
    owner_team VARCHAR(64) NOT NULL,
    status VARCHAR(24) NOT NULL DEFAULT 'new',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_feedback_checkpoint_created
ON feedback_reports(checkpoint, created_at DESC);

CREATE INDEX idx_feedback_scene_fingerprint
ON feedback_reports((context->>'sceneFingerprint'));

FastAPI 接口只接收白名单字段，并由服务端决定责任团队：

from typing import Literal
from uuid import UUID, uuid4
from fastapi import FastAPI
from pydantic import BaseModel, Field
import psycopg

app = FastAPI()

OWNER_BY_CHECKPOINT = {
    "model_import": "device-adapter",
    "frame_setup": "scene-modeling",
    "path_generation": "motion-planning",
    "collision_check": "simulation-core",
    "program_export": "post-processor"
}

class Attachments(BaseModel):
    includeScreenshot: bool = False
    includeRecentLogs: bool = False
    includeSceneFile: bool = False

class FeedbackIn(BaseModel):
    idempotencyKey: UUID
    kind: Literal["bug", "simulation_mismatch", "feature_request"]
    checkpoint: str = Field(min_length=1, max_length=64)
    summary: str = Field(min_length=5, max_length=2000)
    expected: str = Field(default="", max_length=4000)
    actual: str = Field(default="", max_length=4000)
    context: dict[str, str]
    attachments: Attachments

@app.post("/api/feedback")
def create_feedback(data: FeedbackIn):
    owner = OWNER_BY_CHECKPOINT.get(data.checkpoint, "product-triage")
    report_id = uuid4()

    with psycopg.connect("postgresql://app:password@db/feedback") as conn:
        row = conn.execute(
            """
            INSERT INTO feedback_reports (
              report_id, idempotency_key, kind, checkpoint,
              summary, expected, actual, context,
              attachment_manifest, owner_team
            ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
            ON CONFLICT (idempotency_key)
            DO UPDATE SET idempotency_key = EXCLUDED.idempotency_key
            RETURNING report_id, owner_team, status
            """,
            (
              report_id, data.idempotencyKey, data.kind, data.checkpoint,
              data.summary, data.expected, data.actual,
              data.context, data.attachments.model_dump(), owner
            )
        ).fetchone()
        conn.commit()

    return {
        "reportId": str(row[0]),
        "ownerTeam": row[1],
        "status": row[2]
    }

这里故意没有让前端提交 ownerTeam。责任归属属于内部配置，不能由客户端决定，否则版本过期或恶意请求都可能造成错误路由。

附件上传也不应直接塞进这个 JSON 接口。更稳妥的流程是：先创建反馈记录，再根据用户勾选项生成短期上传凭证，上传完成后登记附件摘要与保留期限。

五、把反馈转化为需求证据，而不是直接变成排期

一条“希望增加自动路径优化”的反馈，可能是功能需求，也可能是参数入口不易发现，还可能是现有规划器对某类机器人支持不足。不能收到一条消息就创建功能任务。

可以用下面的证据框架进行人工评审：

维度	需要回答的问题
任务阻塞程度	用户还能否完成导出或现场调试？
可复现性	当前快照能否稳定复现？
影响范围	是单一模型、单一控制器，还是通用流程？
替代成本	是否存在可接受的手动绕过方式？
安全相关性	是否涉及碰撞、速度限制或设备损伤风险？
证据置信度	有日志、场景版本和多个独立报告，还是只有描述？

建议将处理结果分成四类，而不是简单标记“采纳/拒绝”：

• 产品缺陷：行为违反已定义规则，并且可以复现；
• 适配问题：只发生在特定机器人、控制器或后处理器组合；
• 体验问题：能力已经存在，但入口、提示或默认参数导致误用；
• 需求候选：当前产品确实没有该能力，需要继续收集任务证据。

涉及碰撞判断、速度限制等安全相关反馈时，不应因为“出现次数少”而降低优先级。频率只能帮助排序，不能替代安全评审。

六、AI 可以整理材料，但不能判断仿真是否安全

这类反馈入口确实适合使用 AI，但可证明的能力主要集中在文本处理层：

• 从描述中提取机器人型号、控制器和任务阶段；
• 对已经脱敏的反馈生成摘要；
• 推荐标签或疑似责任团队；
• 聚合同一场景指纹下的相似描述；
• 根据已有排查模板生成追问草稿。

它不适合直接完成以下决策：

• 判定一条轨迹在真实设备上安全；
• 根据自然语言自动修改运动参数并下发；
• 把“疑似重复”当作同一个根因；
• 根据模型摘要自动关闭反馈；
• 在缺少机器人模型和控制器信息时编造复现步骤。

真正的焦虑并不是“要不要用 AI”，而是团队是否会在效率压力下，把概率输出悄悄变成工程结论。可执行的边界是：AI 只生成建议字段，原始材料保留；责任人确认后才能修改分类、合并问题或形成需求。

七、实时沟通与结构化反馈怎么选

场景快照适合异步复现，但有时用户正在调试，希望马上解释“这个参数为什么被拒绝”。这时可以增加实时聊天，但不要用聊天替代诊断包。

方案	适用情况	主要代价
自建场景快照 API	需要结构化上下文、附件治理和内部路由	需要维护后端、数据库与权限
普通反馈表单	内容简单、无需继续对话	上下文容易缺失
站内实时聊天	问题需要连续追问，团队有人值守	容易产生非结构化信息
快照 + 聊天	复杂调试、需要一边看上下文一边沟通	需要设计两套信息如何关联

如果小团队暂时不想维护聊天后端，可以把 Knocket 作为实时沟通层的一个实现例子。它提供可嵌入网页的在线聊天组件、移动 WebView SDK、联系页面和统一收件箱；网站可使用控制台生成的脚本标签安装，访客无需注册账号即可发起聊天。消息还能路由到 Telegram，并把维护者的引用回复送回网站访客。

接入时仍建议保留本文的场景快照：用户点击“带当前场景咨询”后，先生成不含敏感文件的摘要，再由用户确认后粘贴到会话首条消息。这样，聊天负责澄清，快照负责复现，两者不会互相替代。

八、按故障路径做验收

不要只测试“正常提交一次”。上线前至少完成以下检查。

1. 上下文与隐私

• 默认不上传工程文件、截图和日志；
• 用户能在发送前预览自动采集字段；
• 场景指纹不包含客户名、坐标明细等敏感原文；
• 日志经过令牌、路径、账号和网络地址脱敏；
• 附件有独立的保留期限与删除策略。

2. 网络与重复提交

• 断网时草稿进入本地待发送队列；
• 网络恢复后可以手动重试；
• 同一个幂等键连续提交两次，只产生一个反馈编号；
• 服务端超时后，用户不会误以为内容已经丢失；
• 本地队列不会长期保存敏感附件。

可用以下请求验证幂等写入：

curl -X POST http://localhost:8000/api/feedback \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey":"7b77b55e-6613-4eaa-bdf4-4dfbb3f59133",
    "kind":"simulation_mismatch",
    "checkpoint":"collision_check",
    "summary":"安全间隙内未显示碰撞告警",
    "expected":"显示碰撞警告",
    "actual":"仿真继续运行",
    "context":{"appVersion":"3.4.1","sceneFingerprint":"sha256:test"},
    "attachments":{"includeScreenshot":false,"includeRecentLogs":false,"includeSceneFile":false}
  }'

连续执行两次，返回的 reportId 应保持一致。

3. 责任与决策

• 每个检查点都能映射到现存团队或具体角色；
• 未知检查点会进入兜底队列，而不是静默丢弃；
• 安全相关反馈有独立升级规则；
• AI 分类不会直接关闭、合并或改写原始反馈；
• 需求评审能够查看原始报告与场景版本，而不只看摘要。

九、常见坑

坑 1：自动上传完整项目，认为信息越多越好

完整项目可能包含产线布局、工艺参数和客户资产。正确做法是默认发送最小元数据，需要工程文件时再单独征得同意。

坑 2：按“Bug、建议、其他”分流

这是内容类型，不是研发责任边界。对于仿真工具，按模型导入、坐标系、规划、碰撞检测、程序导出等任务节点路由，通常更容易找到负责人。

坑 3：把同一场景的多条反馈直接合并

相同场景指纹只能说明环境接近，不能证明根因相同。一次可能是碰撞体缺失，另一次可能是检测精度配置错误，合并仍需人工确认。

坑 4：只采集机器上下文，不让用户描述预期

日志能说明发生了什么，却未必能说明用户认为哪里不合理。expected 和 actual 是需求分析不可替代的部分。

坑 5：上线聊天入口，却没有值守约定

实时界面会形成“马上有人回复”的预期。如果团队只能异步处理，应明确展示响应方式，并优先使用可排队、可追踪的结构化入口。

十、可复用总结

这套方案不局限于工业机器人软件。凡是存在“配置复杂、现场环境多样、项目文件敏感”的开发工具，都可以复用下面的设计顺序：

1. 在任务检查点放置入口，而不是只做全局反馈按钮；
2. 自动生成最小上下文快照，不复制整个应用状态；
3. 让用户预览并分别授权日志、截图和项目文件；
4. 用幂等键、本地待发送队列处理弱网与重试；
5. 按业务组件映射责任人，未知情况进入兜底队列；
6. 把单条意见视为证据，不直接视为需求结论；
7. AI 负责摘要和建议，人负责安全、优先级与产品决策；
8. 需要连续追问时再增加聊天层，并与场景快照关联。

一个可靠的反馈入口，不是让用户多说几句话，而是让双方在不越过隐私和责任边界的前提下，更快确认：当时处于什么场景、软件实际做了什么、用户原本要完成什么任务。

关系披露：作者团队参与 Knocket 的开发与运营，因此本文仅把它作为一种实现示例，而非中立推荐或产品排名。