Files
2026-11-12 20:40:21 +08:00

6.2 KiB

接口、维护与后续扩展

运行方式

使用 Python 3.10+,推荐在本目录建立虚拟环境并执行 python3 -m pip install -e .。这是源目录分发方式,数据文件位于同一目录的 references/ 与 schemas/。本期不提供脱离源目录的数据包 wheel。

CLI 可在本目录运行 python3 -m cad_knowledge,可编辑安装后也可使用 cad-knowledge。从其他目录使用时传 --root /Users/lk/Projects/vibemake相关项目/community/knowledge/cad-parts。不需要模型 Key、模型 SDK、向量数据库或网络连接。

Python 接口

离线短规程读取使用 kb.build_generation_context(family_ids, engine_build=None, experimental=False):仅加载符合准入状态及正文哈希要求的纯 Markdown,返回 manifest、skipped、text。没有合格条目时 text 为空,不能回退到旧长文。experimental=True 只用于明确记录的隔离试验。engine_build 为可选诊断标签,不检查部署版本,也不读取历史 compatible_builds 作为门槛。此离线接口不检查网页规程的具体变体条件,不能替代正式路由。准入依据见生成文本规则。下面的 build_context 是保留的离线资料接口及旧实验复现接口。

from cad_knowledge import KnowledgeBase
kb = KnowledgeBase('/Users/lk/Projects/vibemake相关项目/community/knowledge/cad-parts')
candidates = kb.search('制作带筋轴承座')
context = kb.build_context(['ribbed-bearing-housing'], include_examples=True)
example = kb.documents['example-ribbed-bearing-housing']['meta']['params']
validation = kb.validate_params('ribbed-bearing-housing', example)

search(query) 返回 candidates、category_hits、flags、needs_semantic_review、selected_family_id。selected_family_id 始终为 null;匹配依据是登记的名称或别名,不是模型概率。中文做短语包含匹配,英文使用词边界;统一 Unicode NFKC、大小写和连续空白,不做模糊拼写与参数抽取。

目录命中返回 catalog_only 或 related_family_available;后者只表示存在有关联的细分/部件知识,不表示整个目录节点已覆盖。否定、多个族或显式选择词分别标记 negation、multi_family、ambiguous。标记仅是语义层提示,不能完全解析自然语言否定范围。

build_context(family_ids, feature_ids=None, include_examples=False) 返回 manifest 和 text。每份文档只加载一次,清单包含 ID、kind、版本、相对路径。默认包含选中族登记的相关特征,显式 features 只可补入这些族允许的特征;不能注入无关族或任意路径。单独请求特征时 Python 接口可传空族列表。示例默认不读。

上下文保留 YAML 属性定义与示例参数,避免只读正文而丢失关键参数。顺序为通用约定、族、相关特征、可选示例。requires 仅在共享特征上登记,可引用通用约定或其他共享特征;不能隐式加载其他零件族或示例。使用前检查断链与循环。

validate_params(family_id, params) 接收完整结构化对象,返回 valid、missing、conflicts、unsupported、derived、checks 和 geometry_validated=false。missing 是缺少必需属性,conflicts 是类型/尺寸或解析关系错误,unsupported 是未知字段或超出声明的固定变体。派生值在关系冲突时可能仍返回,仅用于诊断;调用方必须先判断 valid。

没有自由文本参数抽取、单位自动换算、自动补默认或 CAD 执行。修改请求由上层整理成完整新对象再校验,接口本身不保存会话。

CLI 命令

python3 -m cad_knowledge search '不要六角头螺栓,只要安装板'
python3 -m cad_knowledge context involute-spur-gear --examples --format markdown
python3 -m cad_knowledge generation-context involute-spur-gear --engine-build 5707e4ae25621c4a32c40108
python3 -m cad_knowledge validate covered-thin-wall-enclosure --example
python3 -m cad_knowledge validate mounting-plate --params request.json
python3 -m cad_knowledge build
python3 -m cad_knowledge check
python3 -m cad_knowledge evaluate --report reports/acceptance.json
python3 -m unittest discover -s tests -v

退出码:0 为命令成功/校验通过,1 为校验或评测不通过,2 为参数、文件或知识库格式错误。search 返回候选不意味着参数已通过。除 build 和显式 --report 外,命令不写知识文件。

编辑和版本流程

先修改主文档元数据、正文和示例;确定是否应复用共享特征。改变参数含义或表示边界时更新 knowledge_version 并记录兼容影响;结构字段发生不兼容变化再升级 schema_version。

新增族:确认边界与分类映射 → 填完整模板 → 定义/复用特征 → 完整示例 → 登记校验器和至少六个评测 → build → check/测试/评测 → 更新覆盖状态和报告。新族需要扩展 Python 解析关系校验,不依赖一个不受控的公式解释器自动执行任意 YAML。

原始 MCB 图谱与项目扩展保持分开。来源编号稳定;译名更正保留理由。新知识在内部复核前标 draft,复核后 reviewed;对应检索与参数评测通过后再标 retrieval_verified。不要添加几何已验证的状态冒充 CAD 证据。

网页接入与收益评估

CAD 网页助手已实现单一 knowledge_lookup 与原工具循环接线,Python 长文接口不作为网页生成入口。运行配置、API、Maven 打包校验、上下文去重及扩展流程统一见项目维护入口。默认关闭,pilot 允许满足条件的实验规程,enabled 只允许已准入规程;前后端和引擎构建号均不影响加载。

首轮模型端到端 A/B 已完成,题目、截图、原生设计、版本指纹和复核见齿轮集成实测。同题 20 齿 A 未生成实体,B 完整结构及组合中的齿轮通过几何复核;这是有限样例的收益证据,规程仍为实验状态。后续继续固定模型、思考程度、需求、工具和引擎,对比不加载知识与按需加载短规程,衡量真实齿形、结构/尺寸、实体、修改、返工及耗时;代码和检索测试不能证明生成收益,不估算提升百分比。