feat: add knowledge-driven joint design studio

2026-08-14 13:53:51 +08:00
parent 7d12459a32
commit 281afdfd9e
57 changed files with 269659 additions and 1152 deletions
@@ -0,0 +1,53 @@
+# Mechanical Transmission Knowledge Base
+
+This directory is the detached, read-only knowledge source for future
+knowledge-assisted generation. It does not participate in the current CLI,
+solver, CAD, validation, or joint-module execution paths.
+
+## Safety boundary
+
+- `knowledge_enabled` is conceptually `false` until an explicit integration
+  layer is added later.
+- Existing code under `src/` must not import this directory.
+- Knowledge entries describe facts and bind stable capability IDs to existing
+  implementations; they do not execute Python code.
+- A mechanism is not considered supported merely because it has a topology
+  entry. Its `maturity` and capability bindings define how far it can run.
+- Generated experiments must eventually use `output/experiments/`, never the
+  existing `output/runs/` production path.
+
+## Layers
+
+```text
+schemas/       machine-readable contracts for every entry kind
+ontology/      common vocabulary: ports, relations, units, maturity
+components/    reusable parts and virtual references
+relations/     local physical and kinematic connections
+mechanisms/    executable mechanism units/topologies
+compositions/  legal ways to connect mechanism units
+capabilities/  bindings to solvers, layouts, CAD, and validators
+evidence/      regression baselines and validation provenance
+tools/         read-only consistency checks
+```
+
+The initial catalog only records capabilities already present in the project:
+
+- `simple_2k_h`
+- `simple_2k_h_cascade`
+- `ferguson_wolfrom`
+- the six currently registered topology relations
+
+No new transmission structure is claimed to be executable in this first
+version.
+
+## Validate
+
+From `backend/`:
+
+```bash
+python3 knowledge/tools/validate_knowledge.py
+```
+
+The validator uses the Python standard library. It checks entry identity,
+cross-references, mechanism graph integrity, capability source locations, and
+the hashes of the three legacy topology templates.