AI智能体(agent)学习

02 · GLOSSARY

术语表

统一用词，避免把聊天、工作流、RPA、智能体混称。

原理

同一验收语言依赖同一术语。闸口、冻结、回放、证据包是 Harness 四件套；Run 是一次可追溯执行实例。

最佳实践

1. 对外材料统一写 crusbro agent-OS（crusbro智能体操作系统）；禁止把该产品称为开发工具包，禁止使用已废弃旧称。
2. 验收文档出现「完成」时，必须指向工具回执或业务单号，禁止仅引用模型自然语言。

反模式 / 排障

03 · COMPARE

聊天 vs 智能体 vs 工作流 vs RPA

选型先分清形态，否则会把客服机器人当成产线执行引擎。

原理

聊天：生成答复。工作流：预置路径自动流转。RPA：模拟人点 UI。智能体：在目标与工具约束下动态规划并调用系统接口，关键步可冻结。

最佳实践

1. 能用确定性工作流的步骤不要交给模型「自由规划」。
2. 有 API 优先工具调用；无 API 才考虑 RPA，且 RPA 也要进闸口与幂等。
3. 外发、打款、停线、危险执行器：必须冻结或禁止自动。

反模式 / 排障

04 · CHOOSE

选型决策树

用三问快速选型：是否写系统？例外是否多？是否涉及人身/合规风险？

原理

风险与可观测性决定形态；模型能力只是执行层之一。

Q1 只读答复？ → 聊天 / RAG
Q2 路径固定且例外少？ → 工作流（模型可做节点摘要）
Q3 需跨系统编排且例外多？ → 智能体 + 工具契约
Q4 含外发/资金/停线/危险动作？ → 必须 Harness 冻结 + 证据包
Q5 图纸/视觉/机器人/货代？ → 对应领域页 + 本手册专章
Q6 仅个人实验？ → OpenClaw；上产线 → crusbro agent-OS

最佳实践

1. 先写「禁止自动执行清单」，再选模型。
2. 试点范围：一个单据类型 / 一个工位 / 一种缺陷，再横向复制。
3. 对照产品：业务自动化 → OPC agent；图纸 → 图纸模型。

反模式 / 排障

01 · LLM

补全与工具调用原理

生产里只信任「校验后的 tool_calls」，不信任模型自然语言里的「已完成」。

原理

补全是在概率空间续写；工具调用是把动作收敛为 name + JSON 参数。没有 Schema 与权限边界，模型会编造单号与系统状态。

# 生产调用骨架
resp = llm.chat(
  model=route.pick(task),
  messages=trim(messages),
  tools=tool_schemas,          # JSON Schema
  tool_choice="auto",         # 或强制某工具
  temperature=0.1~0.3,
  timeout_s=45,
  request_id=run_id
)
# 校验 arguments → 调工具 → 回执写入 trace → 再观察

最佳实践

1. 工具结果截断入库；长文本进对象存储，上下文只留摘要 + URI。
2. 规划步与生成步可分模型：规划低温，草稿可略高。
3. 每次工具调用带 run_id / step_id，便于回放。

反模式 / 排障

02 · LLM

上下文费用延迟

上下文是稀缺资源：膨胀会同时抬高费用、延迟与出错率。现场要按单号看成本曲线，而不是只看全局均值。

原理

有效上下文 = 目标 + 当前状态摘要 + 最近工具回执 + 必要 RAG 片段。历史全文堆叠不是更聪明，是更贵更慢。工具回执只留关键字段；稳定系统提示与工具 schema 尽量缓存。

budget = {max_steps, max_wall_ms, max_tokens}
while running:
  if exceed(budget): escalate("BUDGET")
  ctx = summarize(work_mem) + last_k(tool_rcpts)
  plan = llm(ctx)
  rcpt = tool(plan); append_short(rcpt)

最佳实践

1. 设最大步数与最大墙钟时间；超时升级人工。
2. 并行工具调用设并发上限，避免下游被打爆。
3. 费用告警按「单号类型」而非全局均值。
4. 大文件先经领域模型/工具抽取，禁止整份 PDF 塞进提示。

反模式 / 排障

03 · LLM

提示词现场版

提示词是配置的一部分：要版本化、可回放、与 Run 绑定，而不是聊天窗口里的临时灵感。

原理

系统提示定义角色与红线；任务提示携带本单事实；工具结果是观察，不是新的系统指令（防提示注入）。

最佳实践

1. 三段式：红线与禁止项 → 输出格式 → 本单事实（结构化）。
2. 变更提示词走发布流程；灰度对比同一验收集。
3. 禁止在用户粘贴内容中执行「忽略以上规则」类指令。
4. 中文现场优先短句、可勾选清单，少口号。

SYSTEM:
- 你只能通过工具读写系统；禁止声称已写入。
- 外发/删除/停线必须 escalate。
TASK:
- order_id=...
- goal=生成冻结草稿供审批
OUTPUT: 仅 tool_call 或 escalate/finish JSON

反模式 / 排障

04 · LLM

模型与路由

路由按任务风险与时延选模型，而不是「最强模型通吃」。写路径、外发、判废类动作优先稳妥可审计路由；摘要类可用更快更便宜模型。

原理

分类：规划 / 抽取 / 生成 / 评审。高风险写路径用更稳路由；视觉与 X 光判读以领域模型优先，通用多模态只做辅助说明。故障转移的备用模型也必须过同一闸口，不可旁路。model_id 与 prompt_version 写入证据包。

route = pick(task_type, risk, latency_slo)
out = call(route.model_id, prompt_ver)
evidence.record(model_id, prompt_ver, route.reason)
if route.side_effect in ("write","outbound"):
  gate.check(out); maybe_freeze(out)

最佳实践

1. 国内优先合规可达模型；外网模型单独出站与密钥策略。
2. 新模型先跑验收集再灰度；与 config_ver 同发版。
3. 密钥托管与轮换；禁止硬编码。

反模式 / 排障

01 · DEV

端到端开发路径

推荐顺序：边界 → 工具 → 循环 → Harness → 评测 → 灰度。跳步会在上线周集中爆炸。

原理

先可验收的最小闭环，再加智能；先单号级证据，再谈多智能体。对照 crusbro agent-OS 部署与运维。每个迭代只扩一类单据或一个工位。

1. 写场景边界与目标函数（成功/失败/升级条件）。
2. 列工具清单与契约（含幂等键、权限、超时）。
3. 实现最小循环 + 轨迹落库。
4. 加闸口、冻结、回放、Run 绑定。
5. 做评测集与回归门禁。
6. 灰度：影子模式 → 建议模式 → 受限自动 → 扩大范围。
7. 运维看板与回滚演练通过后再扩面。

最佳实践

1. 演示环境也要有假单号与假回执，禁止演示直连生产写接口。
2. 周迭代目标写成可勾选状态，不写「继续优化体验」。

反模式 / 排障

02 · DEV

场景边界与目标函数

目标函数写清：什么叫完成、什么叫拒绝、什么叫升级人工。没有边界的智能体只会「尽量帮忙」，无法验收。

原理

边界 = 输入域 × 允许动作 × 禁止动作 × 截止条件。目标用可观察状态表达，不用「尽量准确」之类形容词。每个场景一张一页纸边界表，进配置版本与验收包。

goal = {
  success: "state==frozen AND gates==PASS",
  fail: ["MDM_MISS", "INCOMPLETE"],
  escalate: ["THRESH", "LOW_CONF", "TOOL_X3"],
  forbid: ["outbound_without_freeze", "actuator_direct"]
}
assert_observable(goal)  # 禁止形容词目标

最佳实践

1. 边界表与状态机同审；改边界即发版。
2. 合同或验收若引用效率数字，必须附测法与数据集。
3. 禁止清单单独成页，上线前演练触发。

反模式 / 排障

03 · DEV

智能体循环

智能体是带状态的执行环：观察 → 规划 → 调工具 → 再观察，直到完成或升级。

原理

循环必须有最大步数、墙钟超时与风险分支；否则会空转烧钱或静默失败。

state = {goal, context, steps: [], status: "running"}
while state.status == "running":
  plan = llm.plan(state)  # tool_call | finish | escalate
  if plan.type == "escalate":
    freeze_and_wait_human(state, plan.reason); break
  if plan.type == "finish":
    assert_gates(state); state.status = "done"; break
  result = call_tool(plan.tool, plan.args)  # 幂等
  append_trace(state, plan, result)
  if result.risk == "high" and not approved(result):
    freeze_and_wait_human(state, result)

最佳实践

1. 上线前能回答：最大步数？超时谁接手？哪些工具永不可自动？
2. 每步写入 trace：输入摘要、工具名、回执码、耗时。

反模式 / 排障

04 · DEV

规划策略对照

规划策略按例外率与可观测性选择；不是越「自主」越好。工业默认：确定性骨架承载合规路径，模型只填局部决策与草稿。

原理

高风险步骤固定为工作流节点，不允许模型跳过。重规划次数设上限，超限升级。分层主管/工人要有权限与消息契约。外发、过账、停线类节点强制冻结或禁止自动。

1. 先画合规骨架：哪些步必须确定性。
2. 再标可交模型的局部决策点。
3. 为每类高风险节点挂闸口或冻结。
4. 设重规划与步数上限，超限 escalate。

最佳实践

1. 策略选择写进方案一页纸，评审可追问「为何不纯工作流」。
2. 金标含：计划过时重规划、模型试图跳过冻结节点。

反模式 / 排障

05 · DEV

工具契约与幂等

工具是智能体唯一合法的「手」。无契约等于把写权限交给幻觉。

原理

契约至少覆盖：名称、JSON Schema、权限、超时、幂等键、错误码语义、是否需冻结。

最佳实践

1. 同一业务动作只暴露一个工具入口。
2. 写工具必须返回业务单号或明确失败码。
3. 禁止「自由 SQL / 自由 Shell」类万能工具上生产。

反模式 / 排障

06 · DEV

状态机重试补偿

失败要可分类：重试、补偿、拒收、升级。混在一起会制造脏数据。

原理

状态机显式化：draft → gated → frozen → approved → outbound → done / compensated。每个迁移有守卫条件。网络抖动可有限退避重试（同幂等键）；业务拒绝不重试硬撞；部分成功走补偿或对账，禁止标绿 done。

on_error(e):
  cls = classify(e)
  if cls == RETRYABLE and retries < N:
    sleep_backoff(); retry(idem_key)
  elif cls == BUSINESS_REJECT:
    transit("rejected"); notify_rework()
  elif cls == PARTIAL:
    transit("partial"); compensate_or_ticket()
  else:
    freeze_escalate(e)

最佳实践

1. 补偿与正向路径同等测试。
2. 对账任务按单号拉取两侧状态。
3. 未知错误默认升级，禁止盲目重试放大事故。

反模式 / 排障

07 · DEV

最小可运行样例

教学闭环：查单 → 草稿 → 闸口 → 冻结 → 审批 → 外发。指标仅为验收设计示例。

原理

一个单据类型跑通，比十个半成品更有交付价值。

1) tool.query_order(order_id) -> 事实包
2) llm.draft_reply(facts) -> draft
3) gates: 主数据齐全? 金额阈值? 敏感词?
4) freeze(draft) -> 待审
5) human.approve() / reject()
6) tool.outbound(approved_payload, idem_key)
7) pack_evidence(order_id, run_id)

最小验收表（教学）

反模式 / 排障

01 · KG

为何要接地

接地把「听起来对」与「系统里真」切开。未接地的生成只能当草稿，不能当动作依据。

原理

接地 = 答复与动作可追溯到三类来源之一：工具回执、主数据权威字段、已版本化的知识片段（含生效区间）。模型自然语言本身不是证据。

最佳实践

1. 每条关键结论带 citation：单据字段路径、知识块 ID、图纸 rev 三选一以上。
2. 动作只经工具；UI 展示「待回执」直到工具返回成功码。
3. 无来源时默认 escalate，而不是降低置信度后静默放行。
4. 过期 SOP 片段在检索层降权；引用时展示生效版本号。

# 伪代码：答复前接地检查
claim = draft_answer(ctx)
srcs = resolve_citations(claim)
if not srcs or any(expired(s) for s in srcs):
  return escalate("UNGROUNDED")
if claim.implies_write:
  return deny("WRITE_MUST_USE_TOOL")
return answer_with_citations(claim, srcs)

反模式 / 排障

02 · KG

RAG/知识库现场版

现场 RAG 是受控检索，不是「向量越新越对」。切片、ACL、过期与评测四件事缺一不可。

原理

检索质量上限决定生成下限。权限隔离与版本生效优先于召回率刷榜。表格尽量结构化入库；长文切片保留标题路径与文档版本。

q = normalize(user_q)
hits = retrieve(q, acl=user.acl, top_k=K)
hits = [h for h in hits if h.acl_ok and not expired(h)]
if not hits: return refuse_or_escalate()
ans = generate(q, hits)
assert all(c in hits for c in ans.citations)
log(run_id, q_hash, hit_ids, cite_ids)

最佳实践

1. 按组织与密级分库或分命名空间，禁止全公司一个无 ACL 大库。
2. 过期文档降权或下线；制度变更当日重建受影响索引。
3. 评测集含：必须命中、必须拒答、必须升级、有害诱导引用。
4. 运维看板：空检索率、引用缺失率、ACL 丢弃次数。

反模式 / 排障

03 · KG

记忆分层

记忆分层防止串单与隐私膨胀：工作记忆、情景、语义、程序性各有生命周期与写入权限。

原理

混层会导致 A 单细节污染 B 单，或把临时草稿当成制度。默认最小必要记忆；跨单学习必须单独审批与脱敏。

1. 开 Run：只装载本单情景摘要 + 相关语义版本，不装载历史全文聊天。
2. 步间：工作记忆滚动摘要，超预算则压缩为结构化事实包。
3. 结 Run：情景落证据包；工作记忆丢弃或归档摘要。
4. 跨单学习：走变更单，产出脱敏规则，禁止原文回灌。

最佳实践

1. 跨单学习需单独审批；默认不把 A 单细节注入 B 单。
2. 情景层以业务单号为键，不以会话线程为键。
3. 语义层变更发版；Run 绑定当时语义版本号。

mem = {
  work: ring_buffer(max_tokens),
  episodic: store_by(biz_id),
  semantic: versioned_sop,
  procedural: tool_policy_ver
}
forbid(inject(episodic[A], into=run[B]))  # 除非审批脱敏包

反模式 / 排障

04 · KG

SOP与规则编码

SOP 要变成可执行规则与闸口，而不是塞进系统提示的长文。人读、机检、例外升级三者对齐。

原理

编码路径：人读 SOP → 条件/动作/证据/责任人规则表 → Gate 谓词 → 例外升级路径。提示词只引用规则 ID，不复制整章制度。

# 规则表示意（配置，非提示词）
rules = load(sop_ver)
for r in match(rules, ctx):
  if not eval(r.when, ctx): continue
  apply(r.then)
  evidence.append(r.rule_id, r.evidence)
gate.require_all_mandatory(rules, ctx)

最佳实践

1. 每条规则写清：条件、动作、证据、责任人；禁止含糊「酌情」。
2. 规则变更走发布；与 Run 绑定 sop_ver，争议以绑定版为准。
3. 例外升级必须可测：缺证据、超阈、冲突规则三条用例进金标。
4. 长文 SOP 进 RAG 供人读；机检只跑规则表。

反模式 / 排障

05 · KG

领域模型进智能体

图纸、视觉、X 光等是领域模型；智能体编排它们，而不是用通用大模型硬看图硬判废。

原理

底座关系：crusbro agent-OS + 领域模型 → 场景智能体。领域模型产出结构化结果进工具回执；通用 LLM 做编排与说明，不替代检测头。对照：图纸 · 视觉 · agent-OS。

1. 标定与金标集就绪后，才允许领域模型进生产路由。
2. 模型输出必须带 confidence / 失败码；低置信进审或拒收。
3. 智能体只消费结构化回执，禁止「再看一眼原图自由发挥」绕过模型。
4. 换模型权重 = 配置发版；旧 Run 仍绑定旧 model_ver。

最佳实践

1. 领域模型输出结构化结果进工具回执，进证据包。
2. 通用多模态可做辅助说明，判定与写系统以领域模型为准。
3. 视觉系列模型与 X 光模型分路由；工位级视觉智能体另章验收。

反模式 / 排障

01 · HARNESS

为什么需要 Harness

没有驾驭框架，智能体只是会说话的脚本：不可闸、不可冻、不可回放，管理者无法用同一语言验收。

原理

Harness 是智能体工程术语（非生活语义的「缰绳」）：在 crusbro agent-OS 中封装「按既定目标把事做完」的控制面——闸口、冻结、回放、配置与 Run 绑定、证据包。它让大模型的规划与工具调用可验收，而不是再包一层聊天 UI。价值在可控可审计与跨产品线同一验收语言，而不是省几行编排代码。产品说明见 crusbro agent-OS。

最佳实践

1. 立项首日即定义 Harness 点位：哪些步闸、哪些步冻、证据清单。
2. 对业务：讲清升级路径与可读拒绝原因；对管理：讲清跨线复用验收表。
3. 演示环境也跑冻结与证据包，避免「演示幸福、上线裸奔」。

run = start(goal, config_ver)
while not done:
  step = plan(run)
  gate.check(step) or reject
  if risky(step): freeze(step); await_hitl()
  rcpt = tool(step)
  evidence.append(rcpt)
bind(run, config_ver)  # 不可事后篡改

反模式 / 排障

02 · HARNESS

Harness 是什么

Harness 是 crusbro agent-OS（crusbro智能体操作系统）的核心能力层，不是可选插件或 UI 皮肤。

原理

它把模型、工具、人审与企业系统收束到同一运行时。四件套 + Run 绑定：闸口（阶段硬校验）、冻结（高风险前锁定）、回放（配置+输入复现）、证据包（单号齐套）、配置与执行实例绑定。详见 crusbro agent-OS。

1. 新场景先画 Harness 点位图（哪步闸、哪步冻、谁审）。
2. 再写工具契约与状态机；提示词最后写且只引用规则 ID。
3. 验收按四件套逐项勾选，缺一项不扩面。

最佳实践

1. 点位图进配置库，与 config_ver 一同发布。
2. 人审动作必须是系统内 approve/reject，禁止群聊口头放行。
3. 回放环境默认禁止连生产写库。

反模式 / 排障

03 · HARNESS

闸口设计

闸口是机器可判定的谓词集合。失败要可诊断：缺什么、谁整改、是否允许重提。

原理

模糊「差不多」不能进 Gate。闸口代码与配置同版本发布；结果写入证据包，对人可读。对应运行时见 agent-OS。

def gate(ctx, rules_ver):
  fails = []
  for g in load_gates(rules_ver):
    if not g.pred(ctx):
      fails.append({code: g.code, hint: g.human_hint, owner: g.owner})
  if fails:
    evidence.gate_fail(fails)
    return block(rework=True)
  evidence.gate_pass()
  return allow_next_state()

最佳实践

1. 每条闸口有负责人与重提条件；拒绝原因对业务可读。
2. 阈值进配置，不进硬编码；变更走发版。
3. 金标含：应过、应拒、应升级三类用例。

反模式 / 排障

04 · HARNESS

冻结与外发

冻结把可改草稿变成待审快照；外发只允许快照内容。未冻结外发不可审计。

原理

审批意见与快照哈希一并存证。冻结后改稿必须解冻并重新过闸口。外发工具强制校验 freeze_id。超时未审：升级或作废，禁止静默外发。运行时能力见 agent-OS。

snap = freeze(draft)          # 锁定内容哈希
await hitl.approve(snap.id)
outbound.send(
  payload=snap.bytes,
  require_freeze_id=snap.id
)
# 禁止: send(draft) 或 send(after_silent_edit)

最佳实践

1. 邮件/IM/报关回执类通道默认高风险，一律走冻结。
2. 解冻 = 新草稿 + 新闸口 + 新冻结，旧 freeze_id 作废。
3. 审批人与起草人职责分离；自审自批进禁止清单。

反模式 / 排障

05 · HARNESS

回放与证据包

回放用于排障与审计；证据包按业务单号打包，而不是按聊天线程。

原理

可回放 = 配置版本 + 输入 + 工具回执可对齐。缺任一环只能猜测。回放环境禁止误连生产写库（只读或影子）。能力说明见 agent-OS。

1. 按 biz_id 一键打包下载；权限按角色裁剪敏感字段。
2. 回放时加载绑定 config_ver，输入重放，写操作重定向影子。
3. 差异报告标出：哪一步回执不一致或闸口结果变化。
4. 审计抽检每周至少一条异常 Run 全量回放。

最佳实践

1. 证据包清单固化进验收表，缺项不得签字。
2. 对象存储保留原文件哈希；争议以原件为准。
3. 回放账号无生产写权限，权限分离可测。

反模式 / 排障

06 · HARNESS

配置与 Run 绑定

每次 Run 绑定当时的提示词摘要哈希、规则、模型路由与工具版本。争议以绑定版本为准。绑定不是日志装饰，而是验收与回放的法律意义上的「当时有效配置」快照引用。

原理

禁止事后改配置再声称该 Run 成功。发布产生 config_version；Run 写入该字段且不可变。灰度用不同 version 并行。见 agent-OS。闸口、冻结、回放所依据的规则版本，都必须落在同一绑定包内，禁止拆开热改。

cfg = release.publish(diff)          # -> config_ver
run = runtime.start(goal, cfg.ver)
assert run.config_ver == cfg.ver
# 禁止:
#   hot_patch(prompt) ; claim_success(run)

最佳实践

1. 生产热修也走紧急发版，事后补变更单；禁止无版本热改提示词。
2. 看板按 config_ver 对比成功率，避免混版解读。
3. 回滚 = 流量切回上一 config_ver，不是改几句词。

反模式 / 排障

07 · HARNESS

多角色协作

多角色协作要有明确职责与消息契约；避免多个模型同时改同一单据无锁。

原理

主管智能体分配目标；工人智能体执行工具；仲裁/审计角色只读或触发冻结。共享状态用单号锁或状态机唯一写者。跨角色传递结构化事实包，少传长对话。仍落在同一 agent-OS Harness 下。

lock = acquire(biz_id)
try:
  fact = worker.run(subgoal, tools=acl)
  gate.check(fact)
  state_machine.transition(owner="orchestrator")
finally:
  release(lock)
# 跨角色只传 fact_pack，不传全文对话

最佳实践

1. 每个字段有唯一写者；其他人提变更请求事件。
2. 子智能体继承父 Run 的 config_ver 与证据链。
3. 死锁与超时：锁租约 + 升级人工。

反模式 / 排障

01 · INTEG

企业系统对接地图

先画系统地图：主数据在哪、写权限在哪、异步通道在哪。智能体不替代 ERP/MES/WMS，而是编排它们的合法接口。

原理

每条读写边标明：系统、接口负责人、幂等、是否需冻结、失败是否可补偿。无主责人的接口不上生产。设备与机器人指令口必须经安全层，禁止模型直连。邮件/IM 外发默认高风险。

1. 列出权威主数据源（客户、物料、图号）。
2. 标出唯一写入口与查询入口。
3. 标出异步队列与死信责任人。
4. 标出禁止直连的库表与设备口。

最佳实践

1. 接口清单进配置库，变更走发布。
2. 地图与数据契约同版本号。
3. 新系统接入先只读影子，再开写。

反模式 / 排障

02 · INTEG

数据契约与主数据

主数据不同步，智能体只会正确地写错单。字段字典、枚举、单位、时区、空值语义必须书面约定。

原理

契约进版本库；枚举变更设兼容期双写。对账任务日频，差异进整改队列。智能体消费契约字段，不发明同义别名。

contract = load("mdm.order.v3")
payload = validate(agent_out, contract)
if payload.errors:
  return gate.fail("CONTRACT", payload.errors)
erp.write(payload, idem=idem_key)
reconcile.daily(src=erp, dst=agent_mirror)

最佳实践

1. 对账差异分：漏写、多重、字段漂，分别派单。
2. 枚举新增先双读，再停旧码；删除码需兼容窗口。
3. 契约变更走与 config 相同的发布治理。

反模式 / 排障

03 · INTEG

异步队列与幂等

异步提高韧性，但必须幂等与可见终态。生产者带幂等键；消费者去重；查询能回答处理中/成功/失败。现场事故里，一半「智能体写重了」其实是队列重试没有去重。

原理

至少投递一次是常态。无去重就会双写。毒消息进死信并告警到人；重放死信要人工确认。终态可查询，禁止「发了就忘」。幂等键写入工具契约与证据包，排障时能一眼对齐。

key = f"{biz_id}:{action}:{payload_hash}"
if dedup.seen(key): return ACK
try:
  rcpt = downstream.apply(payload)
  dedup.mark(key, rcpt)
except Poison as e:
  dead_letter.put(key, e); alert(owner)
expose GET /status?key= -> pending|ok|fail

最佳实践

1. 幂等键设计进工具契约，评审必查。
2. 看板：队列积压、死信数、重复投递比。
3. 重放工具强制二次确认并写审计。

反模式 / 排障

04 · INTEG

接口失败与部分成功

多写场景默认会部分成功。设计补偿与对账，而不是祈祷全部原子成功。

原理

按系统能力选 saga/补偿或事务消息。对业务暴露明确状态：哪下游成功、哪下游失败、下一步是重试还是人工。部分成功禁止标绿 done。

1. 编排记录每下游回执到证据包。
2. 任一下游失败：状态=partial，触发补偿或工单。
3. UI 分项展示成功/失败，不给总成功绿灯。
4. 日终对账扫 partial 残留。

最佳实践

1. 不可逆外发放最后一步，且仅在前置全部成功后冻结发送。
2. 补偿失败升级值班，禁止静默吞掉。
3. 金标含「第二下游超时」用例。

反模式 / 排障

01 · QA

评测与回归

没有金标集就没有回归。模型或规则一换，不能全凭感觉放行。

原理

评测集覆盖：正常路径、缺数、恶意注入、边界阈值、部分失败、必须拒答/必须升级。每次发版跑门禁；失败阻断。教学规模：每场景数十条起，指标须附测法。

suite = load_gold(scene)
for case in suite:
  run = replay(case.input, config_ver)
  assert match(run, case.expect)
publish.allow = suite.all_green()

最佳实践

1. 金标集版本化；改期望走评审。
2. 负面用例占比不低于约定阈值（现场自定，写入验收）。
3. 发版报告附失败用例 ID，禁止口头「感觉差不多」。

反模式 / 排障

02 · SEC

安全红线与提示注入

把不可信输入当数据，不当指令。工具权限最小化。提示注入、工具越权、密钥泄露、外发诈骗是四类高频风险。

原理

系统提示与用户数据隔离。高危工具默认拒绝，显式白名单。模型不得直驱危险执行器；不得未冻结外发；不得导出超出权限的主数据。

最佳实践

1. 不可信通道（邮件/附件/网页）内容只作数据字段。
2. 高危工具二次授权；默认 deny。
3. 定期跑注入用例进门禁。

反模式 / 排障

03 · OPS

可观测性

要能按单号看到：步数、工具延迟、闸口结果、费用、错误类。日志、指标、轨迹三位一体。

原理

只有日志不够做 SLO。以业务单号为关联键，贯穿 Run、工具、外发回执。看板最小集：成功率、升级率、P95 延迟、费用/单。

1. 所有工具调用打 span，属性含 biz_id、config_ver、tool_sku。
2. 闸口失败码聚合进看板，按周 TopN 整改。
3. 异常 Run 采样进回放队列。
4. 费用按单归因，防止无界循环烧预算。

最佳实践

1. 值班手册写清：告警 → 查单号 → 回放 → 升级路径。
2. 禁止只盯 token 不计业务成功率。
3. PII 字段日志脱敏策略与安全章一致。

反模式 / 排障

04 · OPS

灰度与运维

灰度顺序：影子（只观察）→ 建议 → 受限自动 → 扩大。回滚=切回上一 config_ver。

原理

变更窗口与生产冻结策略对齐。明确值班与升级路径。禁止无人值守的大流量模型切换。回滚不是改几句提示词。

route = {
  "v_prev": 90%,
  "v_new": 10%,  # config_ver=B
}
if burn_error_budget():
  route = {"v_prev": 100%}  # 回滚=切版本

最佳实践

1. 工作日小流量；避开周五傍晚全量切模型。
2. 每阶段签字人与错误预算写入变更单。
3. 回滚演练纳入上线验收，而不只是文档承诺。

反模式 / 排障

05 · QA

可签字验收表

验收表必须可勾选、可取证。形容词不进合同口径。跨产品线复用功能、风险、证据、运维四栏。

原理

签字人含业务与 IT；附件含 config_version 与证据包样例。教学指标须注明测法，不与现场结果混写。Harness 相关勾选项对齐 agent-OS。

1. 会前冻结验收表版本，会中只勾选不改口径。
2. 每项失败记缺陷单，不口头「下次再说」。
3. 签字附件：config_ver、金标摘要、回滚演练纪要。
4. 未勾证据栏不得进入扩大灰度。

最佳实践

1. 同一验收语言用于 OPC、图纸、视觉等产品线，减少各说各话。
2. 合同数字必须能指向数据集与脚本。

反模式 / 排障

01 · DRAW

图纸智能体总览

图纸智能体 = 领域图纸模型（结构化抽取）+ crusbro agent-OS 编排（闸口/冻结/证据）。目标不是「看图聊天」，而是可机用的事实包，再驱动工艺/BOM/标注/变更。

原理

通用多模态适合解释；工业交付依赖领域模型对标题栏、尺寸链、装配树的稳定输出。产品对照：工业图纸模型 · agent-OS。

最佳实践

1. 版本源以 PLM 为准；邮箱附件只进隔离区，不直连生产解析。
2. 事实包必含：drawing_id、rev、unit、confidence、source_hash。
3. 再应用写 MES/ERP 仅草稿；外发/下发不可逆动作必须冻结。
4. 扫描件与可制造精确图分流：前者可示意，后者才进尺寸闸口。

fact = {
  drawing_id, rev, unit,
  title_block: {...},
  views: [...], dimensions: [...],
  bom_rows: [...],   # 2D 明细或 3D 实例汇总
  asm_tree: [...],   # 仅 3D
  conf: {field: score}
}
gates(fact) -> reject | review | pass_to_draft

反模式 / 排障

02 · DRAW

格式与输入管道

STEP/IGES 走 3D 几何管道；DWG/DXF 走 2D 矢量语义；PDF 先分矢量/扫描再分流。管道不同，质控项与失败码也不同，禁止「一个解析器通吃」。

原理

输入管道职责：病毒扫描 → 格式嗅探 → 单位/编码探测 → 版本登记 → 预览栅格 → 投递对应抽取任务。原文件只读存档，加工产物另存。

# 伪代码：登记后分流
meta = sniff(file)  # mime, units_hint, page_count
quarantine.scan(file)
reg = register(plm_rev, sha256, meta)
if meta.kind in ("step","iges"): enqueue("pipe.3d", reg)
elif meta.kind in ("dwg","dxf"): enqueue("pipe.2d", reg)
elif meta.kind == "pdf":
  if is_scanned(meta): enqueue("pipe.scan", reg)
  else: enqueue("pipe.pdf_vec", reg)

最佳实践

1. 保留原始哈希与转换工具版本；争议以原文件为准。
2. 单位不一致（mm/inch）在登记阶段显式确认，禁止隐式假设。
3. 大装配 STEP 可先轻量化预览，全拓扑按需异步。

反模式 / 排障

03 · DRAW

2D 识别与语义解析

2D 交付物是语义图：标题栏、明细表、视图、尺寸与公差、焊接/表面符号——不是整页 OCR 散文。

原理

流水线：版面检测 → 区域分类 → 字段/符号识别 → 几何关联（尺寸箭头落点）→ 规则校验（必填、单位、基准齐全）。标题栏与明细表优先，因其驱动主数据闸口。

for dim in dimensions:
  assert dim.anchor_ids  # 必须挂到图元，禁止裸数字
  if dim.conf < T_dim: queue_review(dim)
title = parse_title_block(region)
gate_missing = required_fields - title.keys()

最佳实践

1. 金标集按对象分层：标题栏 / 尺寸 / 焊接符号分册评测。
2. 尺寸链规则：同一基准系内冲突尺寸标红，不自动「选一个」。
3. 低置信度只进审图队列，不写下游草稿。

反模式 / 排障

04 · DRAW

3D 数字模型理解

3D 输出可计算特征与装配实例树，供工艺/仿真/MBOM 下游消费；渲染图仅作预览，不是主数据。

原理

B-rep 路径保留精确拓扑；网格路径用于可视化与部分检测。单位、坐标系、抑制件、柔性件状态必须进入事实包，否则下游「正确却错位」。

asm = load_step(path, unit="mm")
tree = expand_instances(asm)          # 含抑制标记
feats = extract_features(asm.solid) # 孔轴、螺纹候选等
assert asm.unit == expected_unit
for node in tree:
  if node.suppressed: node.status = "suppressed"
pack = {"asm_tree": tree, "features": feats,
        "bbox": asm.bbox, "unit": asm.unit}

装配树最小字段

• instance_id / parent_id / part_number / rev / qty
• transform（相对父级）/ suppressed / flexible
• source_file_sha（叶子零件）

最佳实践

1. 装配以实例树为准；同零件多实例分别计数，禁止只按文件名去重。
2. 抑制/隐藏件显式输出 status=suppressed，避免漏检当「没有」。
3. 大装配分层：先结构树，再按需展开叶子几何。
4. 与 2D 同图号交叉：材料/关键尺寸不一致则升级审图。

反模式 / 排障

05 · DRAW

再应用：工艺路线

结构化图纸 → 工艺路线草稿；模型建议工序，规则校验能力与基准，冻结后才进 MES 草稿。

原理

确定性骨架（粗加工→精加工→检验）承载合规路径；模型只填局部参数与可选工序。缺基准、缺关键尺寸、材料未知 → Gate reject，不生成可下发工单。

1. 读事实包：材料、关键尺寸、公差等级、孔系。
2. 匹配工艺模板库（按件型/材料族）。
3. 规则：设备能力、刀具可达、基准是否可装夹。
4. 生成工序草稿 + 理由字段（引用尺寸/特征 ID）。
5. 工艺员审阅冻结；仅草稿写入 MES（幂等键=drawing_rev+template_ver）。

draft = suggest_routing(fact, templates)
for step in draft.steps:
  if not capability_ok(step, plant): gate.reject(step)
if missing_datums(fact): gate.reject("NO_DATUM")
freeze(draft)  # HITL
mes.write_draft(draft, idem=f"{rev}:{tpl_ver}")

脱敏案例（行业典型场景）

反模式 / 排障

06 · DRAW

再应用：BOM

EBOM（设计明细/装配树）与 MBOM（制造投料）分离处理：先对齐主数据，再谈转换规则。

原理

抽取 → 物料匹配（主数据）→ 齐套/替代校验 → 冻结。匹配分必须可解释；低分禁止静默选最近邻。

rows = fact.bom_rows or flatten(fact.asm_tree)
for r in rows:
  m = mdm.match(r.code, r.name)
  if m.score < T: escalate(r)
  else: r.material_id = m.id
mbom = e_to_m(rows, plant_rules_ver)
freeze(mbom)

最佳实践

1. 禁止模型编造物料号；无匹配则空并升级。
2. 数量与单位（PCS/m/kg）在契约中声明。
3. EBOM↔MBOM 差异清单进证据包，供工艺确认。

反模式 / 排障

07 · DRAW

再应用：标注与文档溯源

每条建议必须可点回：字段 → 图元/特征 ID → 页码/视图 → 原文件哈希。无坐标批注无法仲裁。

原理

溯源三元组 (field_path, entity_id, loc) 写入证据；导出包含原图哈希与标注清单，争议回放不依赖聊天记录。

ann = {
  "msg": "键槽宽度公差建议复核",
  "field": "dimensions[12].tol",
  "entity_id": "dim:12",
  "loc": {"page": 1, "view": "A", "xy": [0.42, 0.61]},
  "file_sha": sha
}
export_pack(drawing_id, [ann], include_preview=True)

最佳实践

1. UI 点击标注必须高亮对应图元；做不到则标「仅文本、待补链」。
2. 导出给外部时剥离内部路径，保留相对 loc + 哈希。

反模式 / 排障

08 · DRAW

图纸变更与审图

变更 = 新 rev；自动 diff + 影响分析 + 审图闸口。历史 Run 仍绑定旧 rev，禁止热改冒充。

原理

diff 应对齐语义对象（尺寸值、材料、明细行、特征参数），而非只比像素。影响清单映射到工艺草稿/BOM/在制工单，供人决定是否重发。

d = semantic_diff(fact_old, fact_new)
impacts = map_impacts(d, open_wip=True)
gate.require_review(d, impacts)
# 新 Run 绑定 new_rev；旧证据只读

最佳实践

1. 自动列出变更列表供审图；人确认后才允许新草稿覆盖。
2. 在制工单冲突策略预定义：继续旧版 / 暂停 / 改版换单。

反模式 / 排障

09 · DRAW

脱敏案例集（图纸）

四则均为行业典型场景（脱敏），写具体步骤供验收设计教学，不代表某项目业绩。

案例 A · 机加 2D 识图

1. 登记 DWG：单位 mm、rev B、字体齐套检查通过。
2. 抽标题栏图号/材料；明细 12 行；关键尺寸 36 条挂图元。
3. 3 条尺寸 conf<阈值 → 审图队列；其余进事实包。
4. 教学验收：审图队列可打开高亮；无低置信度写 MES。

案例 B · 钣金 3D→工艺建议

1. STEP 导入：壁厚与折弯特征摘要；展开仅作建议。
2. 模板匹配「激光→折弯→攻牙」；缺折弯半径则拒收。
3. 工艺员改序后冻结；MES 仅草稿。
4. 教学验收：理由字段引用 feature_id。

案例 C · 装配明细→物料匹配

1. 装配树展开 48 实例；合并同料 15 种。
2. 13 种高匹配写入；2 种低分升级；禁止自动猜号。
3. 生成 EBOM 与建议 MBOM diff（虚拟件合并说明）。
4. 教学验收：低分零静默放行。

案例 D · 变更对比

1. rev C vs B：键槽宽 +0.1、材料牌号变更、明细少 1 行。
2. 影响：键槽工序重审、工艺模板重匹配、BOM 重冻。
3. 在制单策略选「暂停待改版」。
4. 教学验收：影响清单三项都有勾选记录。

反模式 / 排障

01 · ROBOT

robot-agent 定位

robot-agent 编排工位协作中的感知、事件与安全约束，不替代安全 PLC / 示教器权限。产品页：机器人智能体。

原理

价值在「可验收的行为安全监控与升级」，不是让大模型「会开车床」。输出是事件、建议降速/暂停请求与证据帧，执行许可在安全层。

最佳实践

1. 立项先画四层边界图，签字确认「谁能发运动指令」。
2. 影子模式默认：只告警不干预，对齐后再开受限联动。
3. 与 MES 交互用事件码，不把视频全文塞进业务库。

反模式 / 排障

02 · ROBOT

分层与工具边界

应用 → Agent → 能力 → HAL。禁止跨层：LLM 不得持有 jog/速度写接口。

原理

工具白名单按副作用分级：read / signal / safety_request。safety_request 只产生「请求」，由安全 PLC 或互锁逻辑裁决。

# Agent 只可：
event = capability.detect(frame)
if event.risk >= HIGH:
  safety.request("PAUSE", reason=event.code, evidence=clip_id)
# 禁止：
# robot.jog(axis=..., delta=...)  # 不暴露给 LLM

最佳实践

1. 联调先影子；干预链路用测试工装验证可测性。
2. 密钥与示教器权限物理隔离；模型运行账号最小权限。

反模式 / 排障

03 · ROBOT

行为安全监控原理

融合：机器人包络检测框 + 人体 19 关键点骨架 + 人员位置 + 禁区多边形；在工位坐标系做时空判定。

原理

单帧分数不够；需连续帧确认与迟滞，降低闪烁误报。标定（相机↔工位）失效时整段降级为「仅记录、不联动」。

P = project_to_station(keypoints19, K, extrinsics)
d = min_dist(robot_hull, P.hands)
if d < D_warn: score_approach += w
if inside_polygon(P.torso, keepout) for N frames: flag_intrusion()
if calib_health < thr: mode = "OBSERVE_ONLY"

最佳实践

1. 标定单定期复核；移动相机后强制重标定。
2. 证据保留短视频或关键帧（人脸默认脱敏）。
3. 阈值分班次/工装可配置，变更走发布。

反模式 / 排障

04 · ROBOT

三类异常操作指引

现场三类异常定义要可操作：伤人风险（接近）、越界、跌倒。每类写清检测条件、自动侧上限、人工侧动作。

原理

伤人：标定后距离阈值 + 手部 19 关键点中腕/指尖朝向机器人运动。越界：禁区多边形 + 连续帧（躯干点）。跌倒：躯干/髋关键点时序（突发下降或躺姿持续）+ 可选姿态分类器。

def approach(d, v_wrist, robot_dir):
  return d < D_warn and dot(v_wrist, robot_dir) > 0
def intrusion(poly, torso, hist):
  return all(inside(poly, p) for p in hist[-N:])
def fall(kps19_seq):
  # kps19_seq: T x 19 x (x,y,conf)
  return hip_drop(kps19_seq) > H and duration_ms > M

操作卡要点

1. 告警弹窗必须带事件码与关键帧缩略图入口。
2. 复位权限：接近可由班长复位；急停锁定需安全员。
3. 跌倒：先救护与清场，再补证据与复盘，禁止先问模型写报告。
4. 每类异常每月至少演练一次（模拟人/标记带）。

最佳实践

1. 三类策略分表配置，禁止共用一个全局阈值。
2. 演练记录进上线包；未演练不得开联动。

反模式 / 排障

05 · ROBOT

数据与训练现场版

链路：采集规范 → 检测框/关键点标注 → YOLO Pose（或同类）训练 → 工位验证预览 → 阈值固化。规则硬阈值始终保留，学习只增强。

原理

样本需覆盖：正常协作、近风险、灯光变化、遮挡。事故样本可少量，但不能成为唯一来源。

1. 制定标注手册：框定义、19 点命名、遮挡/截断标记、左右侧约定。
2. 采集：多班次光照、不同工装、有/无人员；记录相机与标定版本。
3. 划分 train/val 按日期与相机，防同片段泄漏。
4. 训练 Pose/检测；导出引擎并签名；记录超参与数据哈希。
5. 工位验证预览：叠框图、关键点、距离条；对齐误报后再影子。
6. 规则硬阈值与学习分数解耦：学习可关，规则仍在。
7. 数据/模型/阈值写入同一 release。

ds = Dataset(manifest, split_by=["date", "camera_id"])
model = train_yolo_pose(ds.train, kpt=19)
preview_overlay(station_cam, model)  # 人工点检
rel = sign(model, thr, label_manual_ver)

最佳实践

1. 人脸默认模糊；导出集审查后再离场。
2. 每周难例回灌，固定窗口，避免天天热更。
3. 标注抽检：点定位误差超标则整批返工。

反模式 / 排障

06 · ROBOT

上线检查

上线看互锁可测性与证据帧完整性，不只看演示视频好看。分层审查必须证明：无大模型直连运动指令；PAUSE/ESTOP 请求可测。

原理

上线门禁 = 架构无直驱 + 安全回路可测 + 标定在允差 + 影子期对齐 +三类异常演练签字 + 证据帧可取 + 回滚演练通过。缺任一项不得扩大班次。

1. 冻结 release：model_ver + thr_ver + 互锁映射表。
2. 按表逐项取证，失败项开缺陷单。
3. 首周每日抽误报/漏报各若干条复盘。
4. 变更窗口避开无人值班夜班首次全量。

最佳实践

1. 上线检查单与 RACI 同附；业务与安全双签。
2. 证据帧保留策略写进运维手册（天数/容量）。

反模式 / 排障

07 · ROBOT

脱敏案例：工位协作安全监控

行业典型场景（脱敏）：人机协作工位行为安全监控试点。路径：影子告警 → 班组长对齐阈值 → 受限降速联动 → 扩大班次。不宣传「零事故」。

原理

试点目标是可观测告警与可测互锁，不是替代表述安全认证。急停权限始终在安全层；智能体最多发降速/暂停请求。

1. 周 1–2：只观察；收集接近/越界误报。
2. 周 3：调 D_warn 与 N 帧；操作卡上墙。
3. 周 4：开启「降速请求」互锁；急停仍仅演练。
4. 验收：架构无直驱、三类演练签字、事件可取证、可回滚。

最小验收表（教学）

反模式 / 排障

01 · VISION

视觉工程地图

先分清：系列检测模型 / X 光模型 / 工位视觉智能体。模型出视觉结果；智能体管节拍、复检、写回与证据。产品：工业视觉检测。

原理

算法族按任务选：检测框、分割、异常检测、点云尺寸；稀缺缺陷是常态，方案要能兜底，而不是承诺「所有缺陷都能监督到位」。

稀缺缺陷现实

• 监督样本不够是常态；先保证光学可复现与缺陷文字定义。
• 无异常兜底就承诺「零漏检」不可验收。
• 工位智能体负责处置状态机；模型只提供视觉证据。

最佳实践

1. 立项用五维表；落地走九步；X 光双签不与外观混验收。
2. 缺陷定义争议先冻结金标，再谈模型分。
3. 算法族选型写进方案一页纸，避免中途换族无回归。

反模式 / 排障

02 · VISION

五维拆解法

五维：工件、缺陷、光学、节拍、处置。任一维空白，就不要签指标。五维是方案约束，不是文案装饰；变更任一张量，评测集可能失效。

原理

立项用五维表定边界；落地用九步走门禁。光学变更视为新场景，必须触发回归。处置状态机（OK/NG/复检/升级）与模型分数同等重要，缺处置不签合同口径。

five_d = {part, defect, optics, takt, disposition}
for k, v in five_d.items():
  if blank(v): reject_review("MISSING_" + k)
if optics.changed: require_regression()

最佳实践

1. 五维表进立项附件；评审缺维即退回。
2. 光学变更走变更单，绑定新 release。
3. 样品矩阵含批次与姿态，不只良品合影。

反模式 / 排障

03 · VISION

九步落地路径

九步是门禁顺序：跳步（尤其跳过影子）是误剔/漏检事故的常见根因。

原理

每步有退出准则；未达标不进入下一步。模型训练只是其中一步。

for step in STEPS:
  artifacts = run(step)
  if not exit_ok(step, artifacts):
    block(step); notify(owner[step]); break
  gate.record(step, artifacts)
# 禁止：step4 完成后直接 step8 联动剔料

影子期最小报告字段

• 日期/班次/相机 ID / model_ver / thr_ver
• 人检 OK/NG vs 模型建议；不一致件列表
• 误剔候选、漏检候选（教学分类）
• 是否建议进入阈值冻结

最佳实践

1. 影子期长度按缺陷风险定，不按演示日程压。
2. 难例池与金标集分离：难例进训练，金标保回归。
3. 每步产物链接进项目库，评审只看产物不看口头。

反模式 / 排障

04 · VISION

小样本与自监督

稀缺缺陷现实：监督样本不够时，用自监督表征 + 少样本微调 + 异常检测兜底，而不是硬训一个过拟合头。先稳光学与缺陷定义，再谈算法花样。

原理

算法顺序通常：异常兜底保漏检底线 → 少样本抬常见缺陷 → 监督头覆盖可定义类。类别极不均衡时分报表，不看 macro 均值自嗨。每周固定难例回灌窗口；禁止日常热改阈值当「训练」。

1. 冻结缺陷文字定义与采集 SOP。
2. 建异常兜底与复检队列。
3. 少样本覆盖高频可定义类。
4. 难例回灌进训练；金标集只增不乱改期望。

最佳实践

1. release 同时记录数据配比与算法族，便于回放。
2. 无异常兜底不签「零漏检」类表述。

反模式 / 排障

05 · VISION

场景卡片（脱敏）

行业典型场景（脱敏）卡片，对照五维与算法族，用作方案选型提示，不作合同指标。每张卡片必须能回答：光学是否稳定、缺陷是否可定义、处置谁执行。

原理

卡片数字与「典型做法」仅为教学；正式验收另附测法与数据集。复材等高压场景：卡片只给思路，验收必须以工艺标准与持证流程为准。连接器与外观等不得共用同一阈值与 release。

1. 选卡片后回填五维表，缺维不立项。
2. 选定算法族后写一页纸理由与弃选族。
3. 处置状态机与 MES/PLC 信号对齐。
4. 分场景 release，禁止一键共用阈值。

反模式 / 排障

06 · VISION

工位智能体编排

工位智能体 ≠ 模型：模型出视觉结果；智能体管触发、规则、复检队列、MES 写回、证据与升级。

原理

状态机示例：idle → capture → infer → rule → {ok, ng_bin, recheck, escalate} → ack。停线申请走冻结级权限。

on trigger(part_id):
  img = capture()
  r = model.infer(img, model_ver)
  d = rules.apply(r, thr_ver)
  if d == "recheck": queue.push(part_id, r)
  elif d == "escalate": freeze_stop_request(part_id)
  mes.write(part_id, d, idem=f"{part_id}:{model_ver}")
  evidence.pack(part_id, img_ref, r, d)

最佳实践

1. 复检队列设 SLA 与超时升级。
2. 写回幂等；重复触发不双记账。
3. 模型分与业务处置码分开存。

反模式 / 排障

07 · VISION

MLOps 与版本

模型权重、预处理、阈值、采集 SOP 同一 release；签名、回滚、难例回流闭环。

原理

线上先查版本漂移，再查数据漂移。回流：生产难例 → 审核标注 → 训练候选 → 金标回归 → 灰度影子 → 晋升。

rel = sign(model, preprocess, thr, sop)
if not regress(gold, rel): abort()
deploy_shadow(rel)
if promote_ok: deploy_active(rel)
else: rollback(prev_rel)

最佳实践

1. 工位禁止手改阈值；改阈值=发版。
2. 回流集与金标集权限分离，防污染。

反模式 / 排障

01 · XRAY

DR/CT 原理与图像链

先稳图像链再谈 AI：DR 高动态、多帧降噪、ROI；CT 重建参数与伪影控制。压缩预览图不能当评片原图。

原理

评片级数据保留剂量/几何/窗宽窗位/设备状态元数据；质控失败（过曝、严重伪影）不得进模型。

meta = read_technique(study)
if not match_recipe(meta, recipe_ver): return QC_FAIL("TECH")
frames = align(load_frames(study))
img = denoise_fuse(frames) if meta.n_frames > 1 else frames[0]
img = apply_roi(img, meta.roi)
if clipped(img) or blur_score(img) < T: return QC_FAIL("IMG")
store(img, meta, class_="review_grade")

最佳实践

1. 配方（technique）版本化，与图像绑定。
2. CT/DR 分管道验收，不混指标。
3. 预览图仅导航；评片与训练只用评片级。

反模式 / 排障

02 · XRAY

AI 评片流水线

质控 → 检测 → 分割（可选）→ 分级 → 热力图/关键图报告 → 人审队列 → 结论归档。

原理

AI 输出「建议等级 + 依据热图」；合规结论按组织双签口径，不由模型分直接落章。

img, meta = load_study(id)
if not qc(img, meta): return QC_FAIL
det = detect(img)
seg = segment(img, det)          # 可选
grade = classify(det, seg, rules)
report = {grade, heatmap, cites}
queue_human(report)               # 双签前
archive(study_id, report, model_ver)

最佳实践

1. 轨迹逐步落库；禁止只存最终 PDF。
2. 规则分级与模型分可拆开配置，分别发版。

反模式 / 排障

03 · XRAY

双签与合规口径（教学）

教学口径：AI 初评 → 具备资质人员复评/签发；抽检与仲裁流程可配置。具体法规与资质要求以项目合规顾问为准，本章不构成法律意见。

原理

双签记录：谁、何时、对哪版图像、哪版模型/规则、同意或改判原因。抽检：按比例或风险分层抽已签案件复审；争议进仲裁队列。

assert user.has_cert(role)
sign(study_id, user, decision, on={
  "img_sha", "model_ver", "rule_ver"})
if decision.changed_from_ai:
  require_reason_code()
if random() < sample_rate or risk_tier(study) == "H":
  enqueue_audit(study_id)

最佳实践

1. 禁止共用账号；签发后影像与结论只读。
2. 改判必须填原因码，进质量看板（教学指标）。
3. 仲裁结论追加写入，保留完整意见链。
4. 对外材料写「辅助评片」，不写替代持证表述。

反模式 / 排障

04 · XRAY

验收表怎么写

验收分四块：图像质控、算法、流程（双签）、证据；每项写测法与数据集，不写空形容词。材料表述定位为辅助评片，不写替代持证人员。

原理

签字栏含业务、质量、IT；附件含 release 哈希与金标包版本。旁路双签必须有渗透用例证明失败。指标旁注「教学示例，非现场结果」。

1. 冻结验收表版本后再开会勾选。
2. 每项失败记缺陷，不口头放过。
3. 证据栏未过不得进入扩大流量。
4. 表述审查：删除替代持证类句子。

最佳实践

1. 验收与外观视觉分册，避免口径串用。
2. 回滚演练记录进附件，不只承诺。

反模式 / 排障

05 · XRAY

脱敏案例：焊缝/铸件评片闭环

行业典型场景（脱敏）：焊缝或铸件从采集到双签归档的闭环，用于验收设计。路径：影子对比人评 → 固化阈值/规则 → 强制双签 → 抽检仲裁 → 归档回放。

原理

坏图不计模型指标；高争议等级强制第二人；争议件进标定集回流。教学验收盯：旁路双签失败、件号证据包齐套、可回滚。禁止宣称替代持证评片人员。

1. 图像链质控通过；失败件不计模型指标。
2. 影子期：AI 建议与人评对照，只出报告不归档终签。
3. 对齐后开启双签；高争议等级强制第二人。
4. 每周抽检；争议件进标定集回流。
5. 教学验收：旁路失败、证据齐套、可回滚、表述合规。

最小验收表（教学）

反模式 / 排障

01 · FIELD

业务自动化 OPC agent 要点

OPC agent = 业务自动化智能体：单据、审批、外发，跑在 crusbro agent-OS 之上。核心是闸口/冻结/单号证据，而不是聊天润色。现场交付盯业务终态与回执，不盯模型「说得像不像」。

原理

一单据类型一闭环；外发必冻；与 ERP 幂等对账。收单闸口挡住脏主数据，冻结挡住未审外发，回放与证据包挡住事后扯皮。产品页：OPC agent · 底座：agent-OS。

doc = ingest(mail_or_api)
gate.mdm(doc) or reject
draft = fill(doc, rules_ver)
fid = freeze(draft)
await approve(fid)
erp.post(snapshot(fid), idem=f"{doc.id}:post")
pack_evidence(doc.id)

最佳实践

1. 按单据类型拆智能体或明确互斥路由，避免万能单超长提示。
2. 禁止把 OPC agent 称作开发工具包或已废弃旧称。
3. 对账差异日清；部分过账走 partial 状态。

反模式 / 排障

02 · FIELD

货代智能体要点

货代场景单据多、例外多、外发多：更依赖主数据闸口与冻结。报关/运单类动作默认高风险。

原理

港口、航司、船期、客户收件人等主数据必须对齐；敏感字段脱敏展示。产品对照：货代智能体；编排仍在 agent-OS。

1. 收单：运编号/柜号等关键键校验，冲突则升级。
2. 起草：结构化字段，禁止模型编造港口代码。
3. 外发：冻结模板；收件人白名单。
4. 例外：船期变更走变更单，旧快照作废重冻。

最佳实践

1. 港口/航司主数据日对；码表变更发版。
2. 敏感字段（证件、价格）按角色裁剪。
3. 例外率进看板，过高则收紧自动范围。

反模式 / 排障

03 · FIELD

端边部署与断网

边侧要能降级：本地队列、断网续传、冲突合并、证书与时间同步。断网是工况，不是意外。产线工位、库房门口、移动终端都可能长时间离云，策略必须写进配置而不是靠现场临场发挥。

原理

预定义只读 / 缓写 / 禁止外发策略。心跳与版本上报；恢复联网后先对账再放行高风险写。边侧配置仍 Run 绑定，禁止黑盒私改。降级模式下同样保留闸口结论与本地证据，待上云后并入单号证据包。

if not cloud.ok:
  mode = DEGRADED  # no outbound
  queue.persist(event)
  alert("EDGE_OFFLINE")
else:
  drain(queue, idem=True)
  reconcile()
report(heartbeat, config_ver, cert_exp)

最佳实践

1. 证书到期与时钟漂移进巡检。
2. 本地存储加密与容量告警。
3. 断网演练纳入上线验收。

反模式 / 排障

04 · ORG

谁做什么 RACI

RACI 写清业务、工艺、IT、安全、供应商职责。都负责等于都不负责。智能体项目失败常见根因不是模型，而是上线谁签字、闸口谁改、事故谁值守说不清。

原理

每个关键活动有且仅有一个 A（问责人）。供应商可 R，不可单独充当上线 A。闸口规则的 A 通常在业务与合规，配置工程师做 R。Harness 相关活动（闸口、冻结、回放、发版）必须在表上有名有姓。

最佳实践

1. RACI 表进立项附件，变更时同步改。
2. 会议纪要点名 A，不写「大家一起」。
3. 供应商交付物需甲方 A 签收。

反模式 / 排障

05 · ORG

变更与发布治理

提示词、规则、模型、阈值都是变更，走同一发布治理。群里说一声就改生产不可审计。

原理

变更单必备：原因、差异、评测结果、回滚方式、沟通对象。生产变更窗口；紧急热修事后补单。配置与 Run 绑定，变更即新 config_ver。

1. 提单：差异与风险。
2. 评测：门禁绿。
3. 审批：按 RACI。
4. 发布：生成 config_ver。
5. 观察：灰度指标。
6. 关闭：或回滚并复盘。

最佳实践

1. 生产窗口外只允许约定级别的紧急单。
2. 变更沟通清单含业务值班，不只 IT。
3. 禁止「先改后补」成为常态；统计紧急单占比。

反模式 / 排障

06 · OPENCLAW

OpenClaw 实验路径

OpenClaw 适合本地实验工具调用与渠道；产线交付用 crusbro agent-OS（crusbro智能体操作系统）。实验项目也建议模拟幂等、冻结与单号，避免把坏习惯带进生产。

原理

完整指南：OpenClaw 指南。个人 Gateway 不是多租户产线运行时。上生产迁移到 agent-OS，把实验中的工具清单与冻结点对照本手册补齐。

1. 按指南约 30 分钟打通 Dashboard。
2. 接一个渠道，观察轨迹与工具调用。
3. 用表格模拟证据包：单号、工具回执、是否冻结。
4. 对照工具契约与闸口清单，标出实验缺口。
5. 上生产迁移到 agent-OS；切断实验环境对生产写接口。

最佳实践

1. 实验数据一律合成脱敏。
2. 写一份「迁移检查单」再谈上线。

反模式 / 排障

07 · APPENDIX

反模式合集

高频反模式速查。出现任一即暂停扩面，先回到闸口/冻结/回放/Run 绑定基线。

原理

反模式清单纳入发布门禁与周会抽查，避免贴墙不执行。底座能力对照 agent-OS。

1. 周会抽查一条生产 Run：是否踩表中项。
2. 发布门禁自动扫描：外发无 freeze、无 config_ver 等。
3. 复发项升级为变更单，指定 A 角关闭。

最佳实践

1. 新人上手先读本表再写提示词。
2. 演示脚本故意触发至少两项反模式的正确拦截。

反模式 / 排障

08 · APPENDIX

打印版检查单汇总

可打印汇总：立项、开发、上线、日报。按需裁剪。

通用落地检查（仅此汇总一次）

1. 规则进配置版本，不留在聊天草稿。
2. 故意跑失败路径，确认闸口/升级/补偿。
3. 证据含 run_id、业务单号、config_version、关键回执。
4. 外发/停线/危险动作：状态机上有冻结点。
5. 合同指标必须附测法与数据集；教学数字≠客户结果。
6. 图纸：输入哈希+rev；再应用仅草稿。
7. 机器人：无 LLM 直驱；三类异常演练可测。
8. 视觉：五维+九步；影子后门禁。
9. X 光：质控门+双签不可旁路；定位辅助。

反模式 / 排障