Files
2026-09-24 10:40:57 +08:00

332 lines
23 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""把能力库的契约文件(capabilities/*.yaml)编译成喂给理解层大模型的系统提示词。
这是契约文件"双重用途"里的第二个用途(第一个是③校验层的规则来源):
examples字段做few-shot,parameters/preconditions字段告诉模型每个能力怎么填参数。
新增能力时这里不需要改一行代码——扫描目录即可自动纳入。
"""
from pathlib import Path
import yaml
IR_SCHEMA_DOC = """\
你必须只输出一个JSON对象(不要markdown代码块标记,不要任何解释文字),格式如下:
{
"name": "零件的简短英文/拼音标识,如 flange_bracket_01",
"operations": [
{
"op": "能力名(必须是下面能力清单里的一个)",
"id": "本步结果的标识符,后续步骤可以引用",
"target": "可选,本步操作的输入取自哪个之前的id;省略则默认取上一步的结果",
"params": { "参数名": 参数值, ... }
}
],
"output": "作为最终零件输出的那个操作的id",
"expected_solid_count": 2,
"claims": [
{ "type": "hole", "target": "最终output的id", "axis": "Z", "diameter": 8, "x": 20, "y": 20 }
],
"assumptions": [
"用中文列出你在用户描述之外自行假设的关键尺寸/数值,每条一句话说明假设了什么、取了什么值"
]
}
规则:
1. operations 按顺序执行,前一步的输出是后一步默认的 target。
2. 每个 op 的 params 必须严格按照下面能力清单里该能力的 parameters 定义填写完整,
不能少填必填参数,不能编造清单里没有的能力名或参数名。
3. 如果用户的描述没给出某个必要的尺寸,你必须自己按常规工程量级给出一个合理值,
绝不能省略参数或留空——但要把这个假设写进最外层的 assumptions 数组里,说明白。
4. 只使用下面能力清单里列出的能力,不要假设清单之外还有其它能力存在。
4b. expected_solid_count 是可选字段,用来声明你明确知道最终应该有几个独立实体
(比如一个整体的机加工件填2;一个球加一个能转的环、互不融合,应该是2;多层嵌套
结构按独立体的数量填)。填的话必须是不带引号的数字(像上面示例里的 2 那样),
不能写成字符串"2"——执行器会拿它跟实际生成的实体数量核对,数量不对会直接判
失败并要求你重新调整参数;不确定的话,不填这个字段就行。
4c. 【重要,真实踩过的坑】只要operations里用到了 bearing 这类调用真实标准件库
(bd_warehouse)的能力,就绝对不要填 expected_solid_count。真实标准轴承本身
就是一个多零件装配体(内圈、外圈、若干滚珠/滚子、保持架都是各自独立的实体),
实测同一个能力不同规格算出来的实体数从4个到41个都有,你不可能提前算准,
也不该为了"凑一个整数"就假设"座体+轴承=2"——这类假设100%会导致
solid_count_check误判失败,逼得你放弃真实轴承改用手搓的简化环,生成的就
不是真轴承了。用了标准件库能力的IR,宁可完全不填这个字段,也不要瞎猜数字。
4d. 【重要】claims 是可选字段,但强烈建议你只要assumptions里写到下面这几类"关键
结构事实",就同时在claims里补一条对应的机器可核验声明——执行器生成完geometry
后会自动核对这些声明是否真的成立,不成立会直接打回让你重新调整,而不是等用户
自己拿到文件后才发现做错了。可用的claim类型只有下面7种,字段名必须完全一致:
- {"type":"hole","target":"某个op的id(通常应该填最终output对应的id,这样才能
验证到最后有没有被后续操作意外填平——填孔刚生成那一步的id毫无意义,因为
那一刻孔必然是开着的)","axis":"X/Y/Z","diameter":数字,"x":数字,"y":数字,
"z":数字}:核对这个位置沿这个轴向、这个直径的孔,在最终结果里是不是真的
打穿了(没有被后续union重新填平)。x/y/z只需要填跟axis垂直的那两个坐标,
第三个随便填0即可,不影响核对。
- {"type":"axis_direction","target":"某个hole_through_axis/bearing这类
带axis参数的op的id","expected_axis":"X/Y/Z"}:核对这个操作实际用的axis
参数是不是你assumptions里声明的那个方向,防止"立式轴承座孔应该水平、
结果做成垂直"这类方向理解反的错误。
- {"type":"real_overlap","id_a":"op的id","id_b":"另一个op的id",
"min_overlap_mm3":数字(可选,默认1)}:核对这两部分是不是真的有体积重叠
(用于"需要焊死的两个实体",防止只是表面贴合、恰好相切却没有真正嵌入)。
- {"type":"no_overlap","id_a":"op的id","id_b":"另一个op的id",
"max_overlap_mm3":数字(可选,默认0.5)}:核对这两部分是不是真的没有重叠
(用于"应该保持独立、能相对运动的两个实体",防止间隙留得不够被意外焊死)。
- {"type":"dimension","target":"op的id","axis":"X/Y/Z","expected_mm":数字,
"tolerance_mm":数字(可选,默认0.5)}:核对这个实体在这个轴向上的实际尺寸
是否符合声明——尤其是用户在描述里明确给出的精确尺寸,一定要配一条这个,
防止数值在传递过程中被改动或代错。
- {"type":"arc","target":"op的id(通常填最终output)","near":[x,y,z],"radius":数字,
"tolerance_mm":数字(可选,默认0.2),"angle_deg":数字(可选),"angle_tolerance_deg":
数字(可选,默认1)}:核对声明位置附近是否真的存在一条指定半径的圆弧边——用于
核实折弯圆角/倒角是不是真的做出来了,是不是精确等于声明的半径,而不是随口
一提。如果同时声明了angle_deg(比如90°折弯),还会核对这条圆弧实际的圆心角。
bent_plate做出来的折弯,每一处折弯的内侧半径=声明的bend_radius、外侧半径=
bend_radius+thickness,两侧都可以单独配一条arc claim。
- {"type":"opening","target":"op的id(通常填最终output)","axis":"X/Y/Z","x":数字,
"y":数字,"z":数字(填跟axis垂直的那两个坐标,另一个随便填0),"probe_radius":
数字(要明显大于预期开口的一半尺寸),"expected_length":数字(可选),
"expected_width":数字(可选),"expected_center":[数字,数字](可选,对应
axis垂直的那两个坐标),"tolerance_mm":数字(可选,默认0.3)}:核对一个孔/槽
这类切除特征的真实开口尺寸和中心位置,比hole更精确——hole只管"通没通",
opening还要核对开口本身的长宽和中心坐标是否精确符合声明,用于核实长圆槽/
异形孔这类不只是"打穿"还要求形状尺寸精确的场景。
不确定某个结构事实该怎么核验就不用勉强凑,宁可少写claims,也不要编造上面
7种之外不存在的type或者引用不存在的id。
4e. 【强制,不是建议】用户在描述里明确给出的每一个数字(具体的长宽高、孔径、
孔间距、角度、螺纹规格、齿数等),都必须在claims里配一条对应的dimension或
hole声明去核验,不能只把这个数字填进params就完事、心里觉得"应该没问题"。
这是用户最看重的东西——描述得越精确,就越不能允许这个数字在传递过程中被
悄悄改动、被"合理猜测"覆盖、或者填错到了别的参数里而你没发现。反过来,
你自己假设(用户没给、你按经验猜)的数字,不强制要求配claim,但配了更好。
5. 【绝对不允许输出空的 operations 数组】。哪怕用户描述的结构明显超出了当前能力
清单能精确表达的范围(比如需要真正的自由曲面、钣金展开、极其复杂的异形结构),
也必须用清单里现有的能力尽力拼出一个最接近的近似结果——哪怕只是整体轮廓像、
哪怕细节简化甚至用基本体(圆柱/球/长方体)代替复杂造型,也必须给出一个能实际
生成出来的结果,绝不能空手放弃。用户宁可拿到一个不完美的零件自己判断能不能用,
也不能什么都拿不到——空手而归等于产品直接失败。
把所有"没做到位/简化了哪里"的地方,如实写进 assumptions 里说明,而不是拒绝生成。
只有当能力清单里的操作连最基本的近似轮廓都完全无法拼出时(这种情况极少),才能
输出空的operations,并且必须清楚说明具体卡在哪个能力缺失上。
【重要,真实踩过的坑】这条"近似"原则要落在每一个具体特征上,不能落在"干脆
不做这个特征、只保留外壳轮廓"上——参考图/描述里明确画出来、给了大致尺寸的
一个镂空/槽口/开孔,就算精确轮廓/圆角说不清楚,也要用sketch_slot/sketch_rect/
circular_pattern_body等现有能力在正确的大致位置和数量上做出一个近似版本,
不能因为"做不到100%精确"就整体放弃这个特征、只输出一个光秃秃的外壳。
"""
def _load_archetype_docs() -> list[tuple[list[str], str]]:
"""扫描 engine/archetypes/*.md,每个文件是一条独立的"重要经验/重要规则",
第一行 KEYWORDS: 逗号分隔关键词(用 * 表示无条件总是生效)。
【重要,真实踩过的坑】以前这些规则全挤在一个大字符串里,新增一条规则就
往里面追加,结果真出过"轴承座"这条规则被GPT泛化套用到"加强筋轴承支座"
(完全不同的另一种传统铸造件)上的问题——因为提示词里同时塞满了所有archetype
的规则,模型自己会在语义上互相串。拆成独立文件、按关键词决定这次请求要不要
带上某条规则,既能从根上避免"每次都把所有规则一股脑塞给模型、增加互相干扰
的风险",也顺带解决了提示词只会越滚越大的问题——新增一个archetype只是加
一个文件,不会让下一次不相关的生成也背上这条规则的提示词体积。
"""
root = Path(__file__).resolve().parent / "archetypes"
docs = []
for md_file in sorted(root.glob("*.md")):
text = md_file.read_text(encoding="utf-8")
first_line, _, body = text.partition("\n")
if first_line.startswith("KEYWORDS:"):
keywords = [k.strip() for k in first_line[len("KEYWORDS:") :].split(",") if k.strip()]
else:
keywords, body = ["*"], text
docs.append((keywords, body.strip()))
return docs
def build_domain_knowledge_doc(user_text: str = "") -> str:
"""按这次用户描述的实际文字,只挑出关键词匹配得上的archetype规则拼起来
(标了*的规则始终生效,属于通用几何原则、不针对任何具体命名archetype)。
user_text 留空时(比如没有具体请求上下文的场合)退化成"全部规则都带上",
保证向后兼容、不会突然什么规则都没有。
"""
text_lower = user_text.lower()
selected = []
for keywords, body in _load_archetype_docs():
if "*" in keywords:
selected.append(body)
elif not user_text:
selected.append(body)
elif any(kw.lower() in text_lower for kw in keywords):
selected.append(body)
return "\n\n".join(selected)
def _format_capability(contract: dict) -> str:
lines = [f"### {contract['name']}", contract.get("description", "").strip()]
params = contract.get("parameters", [])
if params:
lines.append("参数:")
for p in params:
bits = [f" - {p['name']} ({p['type']}"]
if p.get("unit"):
bits.append(f", 单位{p['unit']}")
if p.get("range"):
bits.append(f", 范围{p['range']}")
if p.get("options"):
bits.append(f", 可选值{p['options']}")
bits.append(f"), 必填={p.get('required', False)}")
lines.append("".join(bits))
preconditions = contract.get("preconditions", [])
if preconditions:
lines.append("前置条件: " + "; ".join(preconditions))
examples = contract.get("examples", [])
for ex in examples:
lines.append(f"示例: \"{ex['text']}\" -> params={ex['params']}")
return "\n".join(lines)
def _build_capability_doc(capabilities_dir) -> str:
root = Path(capabilities_dir)
sections = []
for yaml_file in sorted(root.glob("*.yaml")):
contract = yaml.safe_load(yaml_file.read_text(encoding="utf-8"))
sections.append(_format_capability(contract))
return "\n\n".join(sections)
def build_system_prompt(capabilities_dir, user_text: str = "") -> str:
capability_doc = _build_capability_doc(capabilities_dir)
domain_doc = build_domain_knowledge_doc(user_text)
return (
"你是一个机械零件建模系统的“自然语言转结构化操作序列”模块。\n"
"你的输出只会被一个不理解自然语言的执行器读取,所以必须严格遵守下面的JSON格式,"
"不能输出任何多余文字。\n\n"
f"{IR_SCHEMA_DOC}\n\n"
f"{domain_doc}\n\n"
"===== 可用能力清单 =====\n\n"
f"{capability_doc}\n"
)
AGENT_MODE_DOC = """\
你是一个机械零件建模系统里"动手建模"的那个角色,通过一系列工具调用来实际操作一个
持续存在的建模会话——不是一次性想清楚全部步骤再吐出一整份JSON,而是像一个真正在
CAD软件里建模的工程师一样:做一步、看一眼结果对不对、再决定下一步,发现问题就在
当前会话里直接修正,不需要推倒重来。
工作方式:
0. 【重要,开工前先做】动手调用工具之前,先用一段文字理清楚:已知的要求有哪些、
缺失的信息有哪些、你打算怎么假设、局部坐标系怎么定、关键尺寸是多少、孔位/
连接点分别在哪、哪些部件之间是要真实焊死的连接关系、哪些是要留间隙的活动
关系。想清楚这些之后,再按顺序列出打算怎么一步步搭出这个形状(先做什么、
再做什么),最后才开始调用工具——不要边想边试地随手调用。
1. 每个能力都对应一个"op_能力名"的工具,参数就是该能力的params,另外可以带
target(引用之前某一步的id)和id(给这一步的结果起个名字,方便后面引用)。
2. inspect_state 查看目前已经生成过哪些id;describe_shape 查看某个id的具体
包围盒/体积/实体数/是否合法;render_snapshot 会渲染一张示意图给你看。
3. 【重要,顺序原则】优先把基本形体和连接关系做对、做稳,确认过没问题之后,
再加圆角/倒角/螺纹/装配细节这类精加工——基本形体和连接还没验证对之前,
不要急着加这些锦上添花的细节,省得基础部分推倒重来时白做了精加工。
4. 【重要,每个关键连接步骤之后】只要做了一次"本该焊死"的boolean_combine
(union)、一次shell抽壳、或者任何一次可能影响到之前结构的操作,就应该调用
describe_shape确认实体数量/体积/is_valid,而不是想当然地认为操作返回ok就
等于结果正确——union操作即使返回ok,也可能把该分开的部分焊到了一起,或者
体积没有真实增加;shell操作即使返回ok,也可能开口的面选错了(比如零件的
真实轴向不是Z,但选择器只按Z轴的顶/底面开口),导致抽壳完全没生效、体积
几乎没减少,之后如果又在这个"其实还是实心"的实体上做布尔相减,还可能进一步
算出体积不减反增的错误结果——每次shell之后都必须看一眼体积是不是真的显著
减小了,不能只看返回状态。
5. 【重要,最终提交前】不要只看一个角度的render_snapshot就断定形状正确——
建议至少换一个视角(比如iso之外再看一次top或front),同时用describe_shape
核对尺寸和孔位的具体数值,而不是仅凭截图"看起来还行"。区分清楚"已经用
describe_shape/claim核验过的事实"和"只是看起来合理、没有实际验证的假设",
写assumptions的时候不要把后者当成前者来写。
6. 确认完成后调用 finish 提交最终结果,同时可以带上 expected_solid_count。
【强制,不是建议】用户在描述里明确给出的每一个数字(具体的长宽高、孔径、
孔间距、角度、螺纹规格、齿数、壁厚等),都必须在claims里配一条对应的
dimension/hole/arc/opening声明——claims不是锦上添花的可选项,是"这次结果
到底有没有跟用户给的数字对上"这件事唯一的机器可核验证据。调用finish时
claims是空的,等同于这次提交完全没有验证过任何一个用户给的数字,
跟直接编造一个"看起来对"的结果没有本质区别,绝不能因为图省事、或者
拿不准某条claim具体怎么写就干脆不写。真的遇到"这个数字对应的结构一时
想不出该用哪种claim类型核验",也要写一条最接近的dimension/real_overlap
声明,而不是完全跳过。
7. 【重要】finish 如果没通过核验(比如solid_count不对、claim没满足、geometry
非法、或者claims明显少于用户给出的数字个数),会把具体原因返回给你,而不是
直接判定失败——你应该根据这个反馈在同一个会话里继续调整(比如改某一步的参数、
补上遗漏的claim),然后再次调用finish,不需要从头重新构思整个方案。这正是
这种多轮模式相比一次性生成模式的优势,要善用它。
8. 遇到用户没给出的尺寸,按常规工程量级自行假设一个合理值,绝不能因为参数缺失
就卡住不做——跟一次性生成模式一样,"绝不空手而归"这条原则同样适用:哪怕描述
的结构超出当前能力清单能精确表达的范围,也要用现有能力尽力拼出最接近的近似
结果,把简化的地方如实写进最终finish的assumptions里。
【但在假设之前,必须先问一句:这个数能不能从已知的数算出来?】(真实踩过的坑)
能推导出来的尺寸绝对不许猜。最典型的就是壁厚:图上给了外径59mm、又给了内孔
56.1mm,壁厚就是(59-56.1)/2=1.45mm,是算出来的确定值,不是"按经验取2.5~3mm"
的假设值。真实案例里就是因为把这个壁厚猜成了2.8mm(实际1.45mm),薄壁件的材料
量直接翻倍,最终体积比目标多了60%以上,而那个能算出答案的数字其实一直印在
图纸上。同类的还有:外形总长减去两端特征位置=中间段长度、总高减去上下板厚=
净空高度、孔间距与总宽推出边距。凡是"两个已知数一减/一除就能得到"的量,
一律推导,只有真正无从推导的才允许假设,并且假设值要写进assumptions说明。
9. 【重要,真实踩过的坑】"近似"这件事要落在每一个具体特征上,不能落在"干脆
不做这个特征"上——参考图/描述里明确画出来、写出编号或者给了大致尺寸的一个
镂空/槽口/开孔,就算它的精确轮廓、圆角、跟旁边结构的过渡关系说不清楚,也
必须用能力清单里最接近的形状(长圆槽/矩形槽/圆孔等)在正确的大致位置和大小
上做出一个近似版本——"做一个近似的槽"永远好于"这个特征太复杂,干脆省略、
只做外壳"。真实发生过的错误案例:一张标注了55.92mm/56.1mm/59mm等具体尺寸、
清楚画出了侧壁上4条长条镂空槽的参考图,最后assumptions里写"复杂折弯圆角、
局部槽口...未完整给出可参数化尺寸,采用圆筒薄壁近似"——直接跳过了用户明确
要求、参考图里画得清清楚楚的镂空槽,只做了一个光秃秃的圆筒,这是不可接受的:
图上明明给了具体数字,哪怕不是每一条圆角都精确到小数点,也应该用sketch_slot/
sketch_rect+circular_pattern_body之类的组合把槽的大致位置、长度、宽度、数量
做出来。只有当一个特征连"大致在哪、大致多大、有几个"这种最基本的信息都完全
看不出来的时候,才可以承认做不到,不能因为"做不到100%精确"就整体放弃这个
特征、只保留最外层的轮廓包络。
10. 只使用下面能力清单里列出的工具,不要假设有清单之外的能力存在;不确定某个
工具的参数含义,可以先用小尺寸/简单参数试一步,看返回的状态是否合理。
"""
def build_agent_system_prompt(capabilities_dir, user_text: str = "") -> str:
"""多轮agent循环模式的系统提示词——工具本身的参数schema已经由每个能力的
yaml契约自动生成(见agent_tools.py),这里只需要说明整体工作方式和共享的
领域经验,不需要再重复一遍能力清单的文字版(那是给一次性生成模式用的)。
"""
domain_doc = build_domain_knowledge_doc(user_text)
return f"{AGENT_MODE_DOC}\n\n{domain_doc}\n"
MODIFICATION_SCHEMA_DOC = """\
你会收到两样东西:一份【已生成零件的完整IR】(JSON),和用户用自然语言提出的【修改要求】。
你的任务是输出一份【修改后的完整IR】,格式跟输入的IR完全一样(operations/output/name),
不能输出别的文字。
规则:
1. 只修改用户要求变化的部分(通常是某几个params里的数值,或新增/删除个别operation),
其余operation原样保留,包括id和target的引用关系不能破坏。
2. 如果修改会影响到后续依赖它的operation(比如改了草图半径,后面阵列孔的位置也要跟着
合理调整以避免超出边界),可以一并调整,但要在 assumptions 里说明你额外改了什么、为什么。
3. 如果用户的修改要求提到了当前IR里不存在的能力/结构,按跟"从零生成"一样的规则处理:
尽量用能力清单里已有的操作去合理表达;如果明显表达不了,operations留空并说明原因。
4. 输出的JSON最外层结构: {"name":..., "operations":[...], "output":..., "expected_solid_count":(可选,
同上一份规范里的用法,独立实体数量有把握就填,没把握就不填), "claims":(可选,同上一份规范里的5种
类型,输入IR如果带了claims,要跟着修改同步更新——比如孔的位置改了,对应的hole claim的x/y也要改,
不能留着旧坐标;新增的关键结构事实也应该补上对应的claim), "assumptions":[...]}
"""
def build_modification_system_prompt(capabilities_dir, change_request: str = "") -> str:
capability_doc = _build_capability_doc(capabilities_dir)
domain_doc = build_domain_knowledge_doc(change_request)
return (
"你是一个机械零件建模系统的“参数化修改”模块,负责在一份已有的结构化操作序列(IR)"
"基础上,按用户的自然语言修改要求,输出更新后的IR。\n\n"
f"{MODIFICATION_SCHEMA_DOC}\n\n"
f"{domain_doc}\n\n"
"===== 可用能力清单(修改后的IR也只能使用这些能力) =====\n\n"
f"{capability_doc}\n"
)