中文 · English

🏭 PlantSim-Agent

Bringing AI into the Plant Simulation ecosystem — help-doc Q&A, SimTalk coding, and .psfm project understanding

Why This Exists · What It Does · Quick Start · Architecture · Docs · Roadmap

---

🤔 Why This Exists

Plant Simulation is one of the most widely used discrete-event factory simulation tools, but its ecosystem is closed — the proprietary SimTalk scripting language, the lack of open-source community discussion and public learning material, and the fact that the Plant Simulation 2606 Copilot may still depend on version, entitlement, account, and LLM conditions that limit enterprise adoption. The consequences:

• ❌ It's hard to solve Plant Simulation problems with general-purpose LLMs directly
• ❌ APIs, attributes, and objects get fabricated out of thin air
• ❌ Deprecated SimTalk 1.0 syntax keeps surfacing
• ❌ AI can't truly participate in large simulation projects — there's no closed loop of state requirement → modify code → verify behaviour

PlantSim-Agent aims to fill that gap: a GitHub Copilot Custom Agent + MCP Server combo where every answer is grounded in the Help documentation and your own coding conventions, with no improvisation. It is not intended to replace the Plant Simulation 2606 Copilot; it targets Plant Simulation 2504 and older environments and constrained enterprise setups by reusing GitHub Copilot and adding local project analysis, COM compile validation, and auditable evidence.

📋 What It Does

Capability	Example	Description
Knowledge-Base Q&A	"How does Buffer.numMU behave on a blocked station?"	Searches Help → answer with Help section citation
SimTalk Code Assistant	"Write a method that logs per-shift MU throughput to a DataTable"	Generates code + lists the source of every API used
SimTalk Compile Check	"Can this SimTalk compile?"	Uses Plant Simulation COM to compile-check source and return errors; requires a local Plant Simulation install and configured sandbox
.psfm Project Parsing	"How does the AGV execute a transport task?"	Indexes the whole project → walks through code logic with file locations
.psfm Change Review	"Review the current model changes against HEAD"	Git summary, structured model deltas, parser coverage, and gated model-only handoff

Design Highlights

• Intent routing — the orchestrator agent classifies your question (docs lookup / code writing / project parsing), dispatches it to the right skill with the right conventions loaded — no manual /kb-qa, /code-author switching
• Local KB indexing — the MCP server builds SQLite FTS5 indices locally; queries never leave your machine
• Version-aware COM validation — selects the Plant Simulation version matching the .psfm project and checks SimTalk in a sandbox
• Traceable — every answer carries a workflow-specific evidence anchor; W4 uses **Change Evidence:** for changed paths and revision facts

🚀 Quick Start

v0.3.0 is released: W4 provides change review, a snapshot-bound model-only commit gate, and a SHA-bound non-force push gate. See the Roadmap for the evidence boundary.

Prerequisites

• Windows 10/11, PowerShell, Git, and Python 3.10+
• VS Code 1.99+ with the GitHub Copilot Chat extension
• install.ps1 creates symbolic links; enable Windows Developer Mode or use an elevated PowerShell
• A local Plant Simulation installation is only required for compile_simtalk; the minimal KB, Help search, and project indexing can be tried without it

1. Clone to the recommended location

git clone https://github.com/JackySummerfield/plantsim-agent.git $HOME/.copilot/plantsim-agent
cd $HOME/.copilot/plantsim-agent

2. Prepare the Python environment and MCP server

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .\mcp
plantsim-copilot-mcp --help

If PowerShell blocks Activate.ps1, use .\.venv\Scripts\plantsim-copilot-mcp.exe for the CLI commands below. The installer also discovers this repo-local executable automatically.

3. Install the Agent integration

.\scripts\install.ps1

The script performs two idempotent actions:

1. Creates symlinks under ~/.copilot/agents/ pointing back to the repo, so edits in the repo are picked up by VS Code immediately — no copy step. Skills stay in the repo and are loaded by the orchestrator only (not globally registered), ensuring citation-reviewer always runs.
2. Registers plantsim-copilot-mcp in VS Code's user-level mcp.json, using the active environment first and the repo-local .venv as a fallback.

4. Complete the first run with the bundled minimal KB

# This does not require Siemens Help and verifies the complete first-run path.
plantsim-copilot-mcp init --non-interactive --kb-root .\kb_minimal --build

After this, ~/.plantsim-agent/config.toml and ~/.plantsim-agent/indices/help.db should exist. To add Help from your licensed Plant Simulation installation, run plantsim-copilot-mcp init interactively and add the Help markdown root or fullmd source.

If the console script is not available yet, the same wizard can be run directly from the clone:

python scripts\build_kb.py

To enable compile_simtalk, add the sandbox model path to the same config file:

[com]
sandbox_model = "C:/path/to/tests/fixtures/sandbox.psfm"

For CI / cold-install machines, use non-interactive mode:

plantsim-copilot-mcp init --non-interactive --kb-root .\kb_minimal --build

5. Confirm MCP server registration

install.ps1 already attempts this in step 3. Rerun the command after switching Python environments or when you need to refresh the user-level configuration:

plantsim-copilot-mcp register-vscode --absolute

This merges the following JSON into VS Code's user-level mcp.json (Windows %APPDATA%\Code\User\mcp.json, macOS ~/Library/Application Support/Code/User/mcp.json, Linux ~/.config/Code/User/mcp.json) without touching any other server entries you already have:

{
  "servers": {
    "plantsim-copilot-mcp": {
      "type": "stdio",
      "command": "plantsim-copilot-mcp",
      "args": ["serve"]
    }
  }
}

ℹ️ Note: If mcp.json already contains a different plantsim-copilot-mcp entry, the command reports a conflict instead of silently overwriting it. Review the existing entry before using --force.

If VS Code can't find the command on PATH (typical when the package lives in a conda/venv that VS Code wasn't launched from), run plantsim-copilot-mcp register-vscode --absolute --force to write the absolute path instead. Manual configuration: docs/guides/manual-mcp.md. Full cold-install checklist: docs/guides/cold-install.md.

6. Reload VS Code and make the first request (Ctrl+Shift+P → Developer: Reload Window)

Select PlantSim-Agent in the Copilot Chat agent picker, or type @plantsim-copilot, then verify the complete path with a small request:

@plantsim-copilot How do I check whether a Buffer is full in SimTalk?

Knowledge-Base Layout

The repo ships with two knowledge-base folders side-by-side with very different visibility:

Folder	In git?	Contents
kb_minimal/	✅ yes	Sample KB: SimTalk syntax cheat sheet, API name index, modelling-standards template. Contains nothing under proprietary copyright.
kb_local/	Public checkout: private corpus excluded; private workspace: managed locally	Your private KB. Drop markdown converted from your licensed Help, company-internal modelling standards, project templates, personal notes. The MCP indexes both folders together; public exports exclude the private corpus.

Full Help-to-markdown conversion workflow: docs/guides/kb-build-guide.md.

⚙️ Architecture Overview

graph TD
    A[VS Code Copilot Chat] --> B["plantsim-copilot.agent.md<br/>main orchestrator"]
    B -->|intent routing| C[kb-qa skill]
    B -->|intent routing| D[code-author skill]
    B -->|intent routing| E[project-analyst skill]
    B -->|intent routing| J[project-review skill]
    C --> F[plantsim-mcp Server<br/>Python + FastMCP]
    D --> F
    E --> F
    J --> F
    F -.W4 gates.-> K[Git status/diff + .psfm facts + safe handoff]
    F --> G[(SQLite FTS5 indices)]
    G --> H[kb_minimal/<br/>kb_local/<br/>.psfm project]
    B -.post-audit.-> I[citation-reviewer<br/>subagent]

Loading

The released package exposes 13 MCP tools: search_help, get_api, smart_lookup, list_section, find_method, find_callers, get_object_graph, search_code, validate_simtalk, compile_simtalk, review_project_changes, commit_project_changes, and push_project_commit. W4 is split into review, snapshot-bound model-only commit, and SHA-bound non-force push gates. Recognized artifacts inside the explicit .psfm folder are selected by default; repository-outside paths are always excluded, and only suspicious in-model files require a decision. The released package version is 0.3.0. See docs/architecture.md for the full design.

💬 Usage Examples

Open Copilot Chat in any VS Code workspace and select PlantSim-Agent from the agent picker (or type @plantsim-copilot):

@plantsim-copilot How do I make a Worker ignore service requests during a break?
@plantsim-copilot Write a SimTalk method that logs per-shift MU throughput per station to a DataTable.
@plantsim-copilot In this .psfm project, find every method that calls AGVFleet.
@plantsim-copilot Review the current changes in Model.psfm against HEAD.

🗺️ Roadmap

• v0.1.2 — Released: KB Q&A, SimTalk code authoring, read-only .psfm analysis, citation review, and smart_lookup / list_section retrieval improvements
• v0.2.2 — Released — COM compile loop, bounded self-correction, the 36-task compile-only Pilot, the six-task Agent-generated runtime Pilot, the strict capture package, independent compile replay, and the VS Code agent-discovery and citation-reviewer integration smoke are complete
• v0.3.0 — Released — W4 review, snapshot-bound model-only commit, SHA-bound non-force push gates, and the 13-tool MCP surface are complete
• v0.3.1 (planned) — Revision history comparison, guarded branch assistance, and safe rollback through a new git revert commit
• v0.4 (planned) — Help/API metadata, object-scoped queries, aliases, batch symbol lookup, and a BM25 golden baseline; Dense/RRF is evaluated only if the baseline shows a real recall gap

Full detail in docs/roadmap.md.

🤝 Contributing

All Plant Simulation users are welcome to help improve the project~

⚖️ Trademark & Copyright Notice

This project is not affiliated with, endorsed by, or sponsored by Siemens AG or Siemens Industry Software Inc. "Siemens", "Plant Simulation", "Tecnomatix", and "SimTalk" are trademarks of Siemens or its affiliates and are used here only for nominative reference.

This repository does not redistribute any Siemens documentation, the Plant Simulation Help, model libraries, or any other proprietary Siemens material. All knowledge-base content used by the agent is built locally by each user from the Help shipped with their own licensed copy of the software.

🌟 References & Credits

• Design inspiration: GitHub Copilot Custom Agents and Agent Skills
• Tool protocol: Model Context Protocol
• Thanks to the SCC Forum, LinkedIn, and PSWiki Plant Simulation community for years of public knowledge sharing

License

MIT — see LICENSE.