完善 Python 侧可视化公共接口与交互式浏览器对比视图

.github/workflows/test.yml

@@ -440,6 +440,32 @@ jobs:
         shell: bash
         run: |
           make DIAGRAM_REFERENCE="$DIAGRAM_REFERENCE" diagram_assets_verify
+      - name: Provision Chromium for the browser export gate
+        if: ${{ matrix.python-version == '3.11' }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Only the official Chrome package is accepted here. The runner's
+          # /usr/bin/chromium is the snap wrapper, which cannot open a
+          # DevTools endpoint under Actions confinement.
+          for candidate in google-chrome google-chrome-stable; do
+            if command -v "$candidate" >/dev/null 2>&1; then
+              echo "CHROME_BIN=$(command -v "$candidate")" >> "$GITHUB_ENV"
+              exit 0
+            fi
+          done
+          curl -fsSL -o "$RUNNER_TEMP/google-chrome.deb" \
+            https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+          sudo apt-get install -y "$RUNNER_TEMP/google-chrome.deb"
+          command -v google-chrome >/dev/null
+          echo "CHROME_BIN=$(command -v google-chrome)" >> "$GITHUB_ENV"
+      - name: Run standalone browser export gate
+        if: ${{ matrix.python-version == '3.11' }}
+        env:
+          CI: 'true'
+        shell: bash
+        run: |
+          make diagram_browser_check
 
   template_suite_gate:
     name: template-suite-gate
@@ -1412,3 +1438,51 @@ jobs:
           flags: jsfcstm
           name: codecov-jsfcstm
           fail_ci_if_error: false
+
+  lint:
+    # ``ruff`` and the generated API RST were gates that existed only as lines
+    # in a plan for a human to run, which is how a gate stops being one: the
+    # generated RST turned out to be current only because someone regenerated
+    # it by hand to find out. Both are seconds of work, so they run on every
+    # push and name the commit that introduced the drift.
+    #
+    # The paths are narrow on purpose. ``ruff check`` over the whole package
+    # reports 941 pre-existing findings and ``ruff format`` would rewrite 66
+    # files, so a repository-wide gate could only be added by first paying off
+    # that debt. Widen these lists when a tree is cleaned up, rather than
+    # relaxing the rules to fit one.
+    name: Lint and generated RST
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3.3.0
+        with:
+          fetch-depth: 20
+          submodules: 'recursive'
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: Install lint and runtime dependencies
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          # Read the pin out of requirements-dev.txt so the ruff version
+          # contract keeps living in exactly one place. The rest of that file
+          # is LLM/image tooling this job has no use for.
+          python -m pip install "$(grep -E '^ruff' requirements-dev.txt)"
+          python -m pip install -r requirements.txt
+      - name: Lint the diagram surface
+        shell: bash
+        run: |
+          ruff check pyfcstm/diagram pyfcstm/model/model.py \
+            pyfcstm/model/imports.py pyfcstm/bmc/domain.py test/diagram
+          ruff format --check pyfcstm/diagram test/diagram
+      - name: Check the generated API RST is current
+        shell: bash
+        run: |
+          make rst_auto
+          # ``rst_auto`` is generation, so a clean tree afterwards is the whole
+          # assertion: a public signature that moved without its RST being
+          # regenerated shows up here as a diff.
+          git diff --exit-code

CLAUDE.md

@@ -74,6 +74,59 @@ Applies to all code in [pyfcstm/](pyfcstm/), [editors/jsfcstm/src/](editors/jsfc
 [editors/jsfcstm/src/dsl/grammar/](editors/jsfcstm/src/dsl/grammar/))
 are exempt — they are produced by ANTLR.
 
+## Code Review Scope (findings must be reachable through the public surface)
+
+A code-review finding about this repository's behaviour must describe a failure a
+real user can reach through a documented entry point, used the way the
+documentation says to use it. Anything else is not a finding, however true it is
+about the internals.
+
+**In scope.** The public Python API and the CLI, called normally:
+
+- `StateMachine.diagram()`, `Diagram.to_dict` / `to_json` / `to_html` / `save` /
+  `show` / `with_options` / `with_view_state`, and the equivalents on other
+  modules' public surfaces.
+- `pyfcstm generate` / `simulate` / `bmc` / `plantuml` / `inspect` / `diagram`
+  with the argument combinations their `--help` documents.
+- Ordinary environmental failures a user actually meets on those paths: Ctrl-C
+  part-way through, a destination directory that does not exist or is not
+  writable, a full disk, a missing optional dependency, a common umask, a shared
+  temporary directory, a second user on the same machine, a supported Python
+  version, a supported platform.
+
+**Out of scope.** A defect that exists only in a path constructed for the purpose
+is not reported:
+
+- Calling a private helper directly to reach a state the public API cannot
+  produce.
+- Patching production internals to create a state the public API cannot produce.
+- Injecting a failure into an internal call site — a `logging.Handler` that
+  raises, a broken `sys.stderr`, an argument whose `__str__` raises, a forced
+  `os.fstat` / `os.fchmod` / `unlink` error, a synthesised `EDQUOT`.
+- Faking a platform constant, or forcing a branch that does not exist on the
+  platform under test.
+- Races that need preemption between adjacent bytecodes, or a hard link or
+  symlink swapped in at a freshly generated random name.
+- Branches that need two or more independent failures at once.
+
+**Instruments are not findings.** The exclusions above are about what may be
+*reported*, not about how a property may be *tested*. A test may drive a private
+helper, inject an interrupt at every line, or fake an identity, provided the
+property it pins is one the public surface exposes: `save()` being interrupted is
+an ordinary user event, so a line-granularity probe over the private writer is a
+legitimate way to gate it.
+
+**The question to answer before reporting.** "A user who only reads the public
+documentation and runs the documented commands — how do they arrive here?" If that
+has no answer, the finding is not one. Reporting "nothing found on normal paths,
+and here is what I checked" is the correct outcome in that case, and is more useful
+than a list of unreachable branches.
+
+This section governs correctness reviews of this repository's own code. It does
+not narrow security review of untrusted *input* — a malicious `.fcstm` source, a
+hostile template, or a crafted `.fbmcq` query arrives through a public entry point
+and is therefore in scope by the rule above, not excluded by it.
+
 ## Conversation Language
 
 Reply in whatever language the user wrote their most recent message in. Do not default to English on your own. If the user writes in Chinese, reply in Chinese; if the user writes in English, reply in English; if the user mixes languages, mirror their dominant language and keep technical terms in their original form. When the user switches languages mid-conversation, switch with them on the very next turn — do not keep using the previous language.
@@ -303,6 +356,9 @@ pyfcstm simulate -i input.fcstm -e "cycle; cycle Start; current"     # Batch mod
 pyfcstm simulate -i input.fcstm -e "init System.Active counter=10; cycle 5"  # Hot start batch
 pyfcstm bmc -i input.fcstm -q property.fbmcq                       # Human BMC report
 pyfcstm bmc -i input.fcstm -q property.fbmcq --json -o result.json # Stable JSON result
+pyfcstm diagram -i input.fcstm                                     # Portable JSON on stdout
+pyfcstm diagram -i input.fcstm -o viewer.html                      # Self-contained HTML viewer
+pyfcstm diagram -i input.fcstm --open                              # Viewer in an app window
 
 # Interactive hot start:
 # > init System.Active counter=10 flag=1
@@ -493,10 +549,29 @@ Mandatory completion rule for built-in template work:
 - Requires every SAT model to decode into a public macro-step trace and pass `SimulationRuntime` replay before the CLI reports a trusted verdict
 - Keeps bounded conclusions explicit: SAT/UNSAT describe the solver objective, while `property_satisfied` / `outcome` describe whether the user property holds within the requested bound
 
+**Diagram Views** ([pyfcstm/diagram/](pyfcstm/diagram/))
+
+- `StateMachine.diagram()` returns a `Diagram`: an immutable snapshot detached from the model, so later edits to the
+  model cannot change what a saved view shows
+- `to_dict()` / `to_json()` give portable data; `to_html()` gives a self-contained ~29 MB viewer with the jsfcstm
+  renderer, ELK layout, resvg WASM rasteriser and CJK fonts embedded, under a strict inline CSP and no network access
+- `with_options()` / `with_view_state()` return new snapshots rather than mutating; `show()` opens the viewer in a
+  Chromium-family app window
+- Runtime assets under [pyfcstm/diagram/assets/](pyfcstm/diagram/assets/) are build products, not tracked sources.
+  `make build_assets` produces them and `make unittest` depends on it, in the same way `make tpl` produces the packaged
+  template assets
+- The gates are `make diagram_assets_check`, `diagram_csp_check`, `diagram_contract_check`, `diagram_browser_check`
+  and `diagram_docstring_check`; each one must be able to fail, so mutation-test a gate before trusting it
+- A reST cross-reference must name the module that `docs/source/api_doc` documents the object under, which is the
+  implementation module: `pyfcstm.diagram.api.Diagram`, not `pyfcstm.diagram.Diagram`. A wrong one renders as plain
+  text without any complaint from an ordinary Sphinx build. There is no automated gate for this; a build with `-n`
+  reports it, along with some 1700 pre-existing warnings elsewhere in the tree
+
 **Entry Points** ([pyfcstm/entry/](pyfcstm/entry/))
 
 - [cli.py](pyfcstm/entry/cli.py): Click-based CLI; `pyfcstmcli()` registered as console script
 - [plantuml.py](pyfcstm/entry/plantuml.py): PlantUML diagram generation from state machine models
+- [diagram.py](pyfcstm/entry/diagram.py): `pyfcstm diagram` — portable JSON or a self-contained HTML viewer
 - [generate.py](pyfcstm/entry/generate.py): Orchestrates parsing DSL, building model, and rendering with either `--template-dir` or built-in `--template`
 - [dispatch.py](pyfcstm/entry/dispatch.py): Command dispatching logic for CLI subcommands
 - [simulate/](pyfcstm/entry/simulate/): Interactive simulation REPL (sub-package) with

MANIFEST.in

@@ -7,10 +7,11 @@ recursive-include pyfcstm/template *.zip *.json
 recursive-include pyfcstm/dsl *.g4 *.interp *.tokens
 recursive-include pyfcstm/bmc/grammar *.g4 *.interp *.tokens
 recursive-include pyfcstm/llm *.md *.sha256
-recursive-include pyfcstm/diagram/assets *.md *.js *.wasm *.json *.txt *.ttf *.otf
+recursive-include pyfcstm/diagram/assets *.md *.js *.css *.wasm *.json *.txt *.ttf *.otf
 prune pyfcstm/assets
 prune pyfcstm/diagram_runtime
 include pyfcstm/diagram/assets/NOTICE.txt
 include pyfcstm/diagram/assets/LICENSE-MPL-2.0.txt
 include pyfcstm/diagram/assets/LICENSE-EPL-2.0.txt
 include pyfcstm/diagram/assets/LICENSE-OFL-1.1.txt
+include pyfcstm/diagram/assets/LICENSE-MIT.txt

Makefile

@@ -1,4 +1,4 @@
-.PHONY: docs docs_en docs_zh docs_pdf docs_pdf_en docs_pdf_zh test unittest template_unittest resource antlr antlr_build fcstm_antlr_build fbmcq_antlr_build build build_info build_info_cli package clean build_assets build_assets_clean diagram_assets_check diagram_rendering_check diagram_parity_check diagram_reference_check diagram_engine_floor diagram_provenance_check diagram_assets_verify diagram_package_check diagram_corpus docs_auto todos_auto tests_auto rst_auto sha256 jsfcstm jsfcstm_clean vscode vscode_clean vscode_install vscode_uninstall logos logos_clean app_icons app_icons_clean help tpl tpl_clean templates_package template_packaging_check template_source_install_check docs_terminology_check test_boundary_check
+.PHONY: docs docs_en docs_zh docs_pdf docs_pdf_en docs_pdf_zh test unittest template_unittest resource antlr antlr_build fcstm_antlr_build fbmcq_antlr_build build build_info build_info_cli package clean build_assets build_assets_clean diagram_assets_check diagram_rendering_check diagram_browser_check diagram_contract_check diagram_data_check diagram_options_check diagram_csp_check diagram_parity_check diagram_reference_check diagram_engine_floor diagram_provenance_check diagram_assets_verify diagram_package_check diagram_corpus docs_auto todos_auto tests_auto rst_auto sha256 jsfcstm jsfcstm_clean vscode vscode_clean vscode_install vscode_uninstall logos logos_clean app_icons app_icons_clean help tpl tpl_clean templates_package template_packaging_check template_source_install_check docs_terminology_check test_boundary_check
 
 PYTHON := $(shell which python)
 
@@ -93,7 +93,12 @@ help:
 	@echo "  make build_info   - Generate build identity for a package or CLI build"
 	@echo "  make build_assets - Build ignored Python diagram JS/WASM/font assets"
 	@echo "  make diagram_assets_check - Build and validate diagram assets and ignore rules"
-	@echo "  make diagram_assets_verify - Run provenance, runtime, and visual asset gates"
+	@echo "  make diagram_browser_check - Run representative offline Chrome export gate"
+	@echo "  make diagram_contract_check - Verify the public snapshot and portable data contract"
+	@echo "  make diagram_data_check - Verify parsed, imported and programmatic data parity"
+	@echo "  make diagram_options_check - Verify option and view-state mapping parity"
+	@echo "  make diagram_csp_check - Verify the standalone HTML policy and embedded resources"
+	@echo "  make diagram_assets_verify - Run provenance, runtime, contract, and visual asset gates"
 	@echo "  make diagram_parity_check DIAGRAM_REFERENCE=/abs/path/reference.json"
 	@echo "  make diagram_reference_check - Verify reference archive retry behavior"
 	@echo "  make diagram_corpus - Rebuild checked-in DiagramData rendering oracles"
@@ -244,6 +249,37 @@ diagram_assets_check: build_assets
 	$(PYTHON) tools/build_diagram_assets.py --check
 	$(PYTHON) tools/check_diagram_assets.py
 
+diagram_browser_check: build_assets
+	@if test -n "$(DIAGRAM_HTML)"; then \
+		node tools/diagram_assets/check_viewer_browser.js "$(DIAGRAM_HTML)" "$(DIAGRAM_SCREENSHOT)"; \
+	else \
+		$(PYTHON) tools/check_diagram_browser_exports.py --all-cases --formats svg,png,pdf --pdf-require-zero-images --pdf-page-size-match --pdf-rerender; \
+	fi
+
+diagram_contract_check: build_assets
+	$(PYTHON) tools/check_diagram_contract.py
+
+diagram_data_check: build_assets
+	$(PYTHON) tools/check_diagram_data_parity.py
+
+diagram_options_check: build_assets
+	$(PYTHON) tools/check_diagram_options_parity.py
+
+diagram_csp_check: build_assets
+	$(PYTHON) tools/check_diagram_csp.py --check
+	$(PYTHON) tools/check_diagram_csp.py \
+		--require-default-none --require-connect-none --require-worker-none \
+		--require-script-hashes --require-style-hashes --require-style-nonce \
+		--require-wasm-unsafe-eval --forbid-unsafe-eval \
+		--require-no-fallback-directives \
+		--require-font-data --require-img-data-blob \
+		--forbid-eval --forbid-new-function --zero-network \
+		--require-embedded-fonts 5 --require-fonts-ready
+
+diagram_docstring_check: build_assets
+	$(PYTHON) tools/check_diagram_docstring_examples.py --check
+	$(PYTHON) tools/check_diagram_docstring_examples.py
+
 diagram_rendering_check: build_assets
 	$(PYTHON) tools/check_diagram_rendering.py --check
 	$(PYTHON) tools/check_diagram_rendering.py \
@@ -278,7 +314,7 @@ diagram_provenance_check:
 diagram_reference_check:
 	$(PYTHON) tools/fetch_diagram_reference.py --check
 
-diagram_assets_verify: diagram_assets_check diagram_rendering_check diagram_parity_check diagram_engine_floor diagram_provenance_check diagram_reference_check
+diagram_assets_verify: diagram_assets_check diagram_docstring_check diagram_rendering_check diagram_contract_check diagram_data_check diagram_options_check diagram_csp_check diagram_parity_check diagram_engine_floor diagram_provenance_check diagram_reference_check
 
 diagram_package_check: package
 

docs/source/api_doc/diagram/api.rst

@@ -0,0 +1,40 @@
+pyfcstm.diagram.api
+========================================================
+
+.. currentmodule:: pyfcstm.diagram.api
+
+.. automodule:: pyfcstm.diagram.api
+
+
+\_\_all\_\_
+-----------------------------------------------------
+
+.. autodata:: __all__
+
+
+DiagramOptions
+-----------------------------------------------------
+
+.. autoclass:: DiagramOptions
+    :members: __post_init__,to_dict,detail_level,direction,palette,mode,cjk_locale
+
+
+DiagramViewState
+-----------------------------------------------------
+
+.. autoclass:: DiagramViewState
+    :members: __post_init__,to_dict,mode,collapsed_state_ids,zoom,pan_x,pan_y
+
+
+DiagramData
+-----------------------------------------------------
+
+.. autoclass:: DiagramData
+    :members: __post_init__,__eq__,__hash__,to_dict,to_json,value
+
+
+Diagram
+-----------------------------------------------------
+
+.. autoclass:: Diagram
+    :members: __init__,__setattr__,__delattr__,to_dict,to_json,with_options,with_view_state,to_svg,to_png,to_pdf,to_html,save,show

docs/source/api_doc/diagram/engine.rst

@@ -6,6 +6,18 @@ pyfcstm.diagram.engine
 .. automodule:: pyfcstm.diagram.engine
 
 
+DiagramError
+-----------------------------------------------------
+
+.. autoclass:: DiagramError
+
+
+DiagramUnavailableError
+-----------------------------------------------------
+
+.. autoclass:: DiagramUnavailableError
+
+
 DiagramAssetError
 -----------------------------------------------------
 
@@ -30,6 +42,12 @@ DiagramEngineConflictError
 .. autoclass:: DiagramEngineConflictError
 
 
+DiagramEngineLoadError
+-----------------------------------------------------
+
+.. autoclass:: DiagramEngineLoadError
+
+
 DiagramAssetEngine
 -----------------------------------------------------
 

docs/source/api_doc/diagram/index.rst

@@ -9,6 +9,7 @@ pyfcstm.diagram
 .. toctree::
     :maxdepth: 3
 
+    api
     assets/index
     engine
 

docs/source/api_doc/entry/diagram.rst

@@ -0,0 +1,18 @@
+pyfcstm.entry.diagram
+========================================================
+
+.. currentmodule:: pyfcstm.entry.diagram
+
+.. automodule:: pyfcstm.entry.diagram
+
+
+\_\_all\_\_
+-----------------------------------------------------
+
+.. autodata:: __all__
+
+
+diagram\_command
+-----------------------------------------------------
+
+.. autofunction:: diagram_command

docs/source/api_doc/entry/index.rst

@@ -12,6 +12,7 @@ pyfcstm.entry
     base
     bmc
     cli
+    diagram
     dispatch
     generate
     inspect