v0.3.0 - .psfm project review and controlled Git handoff

PlantSim-Agent v0.3.0 - Project review and controlled Git handoff

This release adds the W4 project-review and controlled Git-handoff workflow to PlantSim-Agent. It extends the existing Plant Simulation knowledge and coding workflow with read-only model-change inspection, snapshot-bound commit proposals, explicit commit and push gates, and a stronger cold-install path. The package reports version 0.3.0 and is published with the v0.3.0 tag.

Release overview

Area	v0.3.0 outcome
Project review	Read-only Git and .psfm change inspection through review_project_changes
Change evidence	Best-effort object, Method, inheritance, and flow-edge deltas with parser coverage warnings
Git handoff	Snapshot-bound commit proposals plus explicit commit and push confirmation gates
Agent workflow	plantsim-project-review skill, W4 orchestrator routing, and **Change Evidence:** citation contract
Installation	Explicit MCP package installation, non-interactive minimal-KB initialization, and repo-local .venv fallback
Public release	Sanitized allowlist export with private Help data, caches, bytecode, databases, and internal paths excluded

W4 project review

The new review_project_changes MCP tool provides a read-only review of a Plant Simulation project and its surrounding Git worktree. It reports:

• Git status and the selected baseline-to-worktree file changes;
• bounded patch text when the caller requests it;
• changed .psfm YAML files and their best-effort structural deltas;
• object, Method, inheritance, and flow-edge changes when the parser can identify them; and
• parser coverage warnings for malformed YAML, non-YAML changes, and changed
  YAML files without a recognized structural delta.

The review does not write back to .psfm files, switch branches, revert files, or perform Git writes. See plantsim-project-review and ADR-003.

Controlled Git handoff

A successful review produces a snapshot-bound commit_proposal. The proposal contains the proposed subject and body, default model-artifact paths, suspicious in-model paths, permanently excluded outside-model paths, and Git write blockers.

The handoff is intentionally split into separate gates:

• commit_project_changes commits only after the review snapshot is still
  current and the user confirms the operation;
• the commit message can be edited before the commit is created;
• model-only staging is supported for the approved artifact paths; and
• push_project_commit requires the exact commit SHA and a second confirmation,
  and never force-pushes.

Branch creation, revert operations, direct .psfm write-back, and remote configuration remain outside these gates. The push gate requests an unconfigured remote only when needed and does not persist it.

The design boundary is documented in Project change review and Git handoff.

Installation and quick start

The Windows quick-start path now documents the complete first-run sequence:

1. Install the MCP package from the repository's mcp/ directory.
2. Run the installer or register the MCP server explicitly with plantsim-copilot-mcp register-vscode.
3. Build or initialize the minimal public knowledge base without an interactive prompt.
4. Use the repo-local .venv executable as a fallback when the MCP package is installed but its console script is not available on PATH.
5. Reload VS Code and invoke the custom agent with @plantsim-copilot.

The cold-install guide and manual MCP guide use the same released command
surface and invocation syntax.

Public export boundary

The public repository is generated from the private canonical source through the plantsim-agent-public export policy. The allowlist includes the released agent files, documentation, minimal public knowledge base, MCP package, scripts, skills, and tests.

The export excludes private Help data, .plantsim-agent state, generated indices, pytest and Ruff caches, Python bytecode, SQLite and other database files, and internal workspace paths. Each export carries an EXPORT-MANIFEST.json with file hashes so the publish step can verify the staging directory before replacing the public checkout.

Validation

The v0.3.0 release gate covered:

• the canonical source test suite, with the optional local Plant Simulation COM integration test skipped when --run-com is not enabled;
• cold-install subprocess checks;
• public staging tests with bytecode and pytest cache generation disabled;
• export manifest, path, private-marker, and Markdown-link scans; and
• public publish checks for a clean target checkout, the expected target HEAD, the configured repository origin, and the sanitized export manifest.

The public staging test run completed with 240 passed, 1 skipped, 1 deselected. The deselected test checks repository-boundary protection through .git metadata and was run successfully against the canonical Git checkout.
The public export itself intentionally contains no .git directory.

Evidence boundary

The project-review deltas are best-effort parser results. A malformed or unsupported .psfm change is reported with a coverage warning; it is not silently treated as a complete structural review.

The Git handoff gates protect the reviewed snapshot and the explicit commit and push operations. They do not establish semantic correctness for arbitrary Plant Simulation models, AGV or AMR scheduling, long-running stochastic simulations, or changes that the parser cannot recognize.

Release status

The private canonical source now includes this standalone v0.3.0 release note alongside CHANGELOG.md. The plantsim-agent-public export policy includes the file for the next public synchronization. The existing public v0.3.0 tag remains unchanged and is not moved retroactively.

v0.2.2 - first public 0.2.x cumulative release

PlantSim-Agent v0.2.2 - first public 0.2.x cumulative release

This document records the v0.2.2 release of PlantSim-Agent. The package
reports version 0.2.2, and the release is published with the v0.2.2 tag.

This is the first public 0.2.x release after v0.1.1. It consolidates the
previously unreleased work from the 0.2 development line rather than
representing only the final runtime milestone. The release covers retrieval
and installation safety, the COM compile loop, measurable code-generation
evaluation, bounded runtime evidence, session-evidence handling, and the
release integration gates. The intermediate development milestones were not
published as separate public releases.

Release overview

Area	v0.2.2 outcome
Help retrieval and safety	Focused lookup tools, fullmd navigation, source breadcrumbs, and safer skill loading
COM compile loop	Version-aware connection, compile_simtalk, sandbox validation, retry, and self-correction
Code-generation evaluation	12-task baseline and 36-task expanded Pilot with independent COM replay
Runtime evaluation	Versioned PS2504 fixture, typed assertions, strict admission, and Agent-generated runtime Pilot
Integration and release	VS Code smoke, citation review, cold-install checks, private evidence boundary, and sanitized public export

Help retrieval and installation safety

• Added smart_lookup for the exact-match, suggestion, and FTS fallback
  cascade, reducing the normal retrieval path from 5-10 MCP calls to 1-2.
• Added list_section for chapter, kind, and query filtering when a user needs
  to enumerate Help entries.
• Added chapter-aware fullmd indexing and suggestion fallbacks. Large single
  file Help results now use searchable breadcrumbs instead of broken direct
  links, while multi-file entries continue to use valid Markdown links.
• Reworked the plantsim-kb-qa cascade and aligned its Sources contract with
  citation-reviewer.
• Hardened installation so skills are not globally symlinked into
  ~/.copilot/skills/, preventing direct skill invocation from bypassing the
  orchestrator's citation-review workflow.
• Reworked the KB build and installation documentation, including the
  scripts/convert_help_pdf.py PDF-to-Markdown workflow and the Windows-only
  support boundary.

COM compile loop

• Added a version-aware Plant Simulation COM connection with project-version
  selection, lazy connection reuse, reconnect cleanup, and graceful
  degradation when COM is unavailable.
• Added the compile_simtalk MCP tool and a versioned PS2504 sandbox fixture
  for valid, invalid, and parameterized SimTalk.
• Added a code-author compile gate that feeds compiler errors back into the
  Agent for targeted self-correction, with a three-attempt limit and explicit
  compile status reporting.
• Added stable error codes for configuration, project, sandbox, COM, and
  compile-check failures. A failed COM call reloads the configured sandbox
  before retrying.

Code-generation evaluation

The compile evaluation moved from a qualitative demonstration to a reproducible
Pilot with private JSONL evidence, failure sources, and independent COM replay.

• The 12-task baseline reached a 100.0% final compile pass rate, with a 58.3%
  first-attempt pass rate and 100.0% recovery after retry.
• The expanded 36-task Pilot reached a 100.0% final compile pass rate, a 63.9%
  first-attempt pass rate, and 100.0% retry recovery across all 13 initial
  failures.
• Local COM replay matched all 36 final results. The private run records and
  replay artifacts remain outside the repository.

Bounded runtime evaluation

The runtime layer extends the compile loop to observable behavior, but only on
declared, deterministic fixtures and inputs.

• Added a versioned PS2504 runtime fixture with typed assertions and a clean
  fixture reload before each task.
• Added generate and repair task contracts, isolated serial worker
  execution, hard timeouts, and Behavior Pass Rate reporting with
  infrastructure errors kept separate.
• Added independent COM compile replay for every recorded attempt.
• Added strict capture-package validation for task and fixture inputs, fixture
  identity, Plant Simulation version, duplicate task IDs, complete MCP
  payloads, session association, and independent Agent provenance.
• Added task admission categories and the session-derived collector. Incomplete
  transcript evidence remains candidate-only instead of entering strict
  evaluation records.
• The Agent-generated runtime Pilot covered 6 unique tasks from 7 historical
  sessions. It achieved a 100.0% Behavior Pass Rate, 100.0% final compile pass
  rate, 100.0% retry recovery, and 100.0% compile/runtime replay agreement
  across 7 recorded attempts, including one repair retry.
• The private real-session evidence was re-normalized with the current
  collector and evaluator and reproduced on the local Plant Simulation 25.4
  environment. The source session evidence, capture package, and generated
  runtime results remain outside the repository.

Integration and release gates

• The manual VS Code smoke confirmed that @plantsim-copilot appears in the
  Agent picker, the MCP server starts, a Plant Simulation question returns its
  Sources block, and the orchestrator dispatches citation-reviewer in the
  same Copilot turn. The reviewer returned ok.
• Automated cold-install checks, live session capture/evaluation replay, and
  repeatable local PS2504 COM validation passed.
• Public export rules exclude private Help data, session evidence, caches,
  bytecode, and internal workspace paths.

Evidence boundary

The reported results apply only to the declared PS2504 fixture, task inputs,
trigger conditions, and observable assertions. They do not establish general
semantic correctness for arbitrary Plant Simulation models,
project-wide changes, or long-running stochastic simulations.

AMR routing and scheduling, event-driven or parameterized Method scenarios,
cross-Method project patches, random or long-running simulations, and general
model semantic correctness remain outside the v0.2 release boundary.

Release status

The v0.2 release gates are complete and the cumulative release is published as
v0.2.2. The public release history intentionally moves from v0.1.1 to
v0.2.2; no intermediate 0.2 development milestone was published as a
separate public version.

Full Changelog: v0.2.2...v0.2.2

v0.1.0 — First Public Release

让 AI 真正成为 Plant Simulation 的副驾驶。

PlantSim-Agent 把 GitHub Copilot 变成一个能查帮助文档、写 SimTalk 代码、读 .psfm 项目的「Plant Simulation 副驾驶」——并且每个答案都必须给出来源，不允许凭空捏造。

What's in the box

🤖 7 个 MCP Tool

Tool	用途
search_help	全文检索本地 Help 知识库（FTS5）
get_api	按名字精确查 SimTalk API，找不到时返回 did_you_mean
find_method	在 .psfm 项目里按名找 Method，并列出继承覆写
find_callers	反向查谁调用了某个 identifier
search_code	在所有 SimTalk method body 里做 FTS
get_object_graph	返回对象的继承 + 物流邻居
validate_simtalk	SimTalk 2.0 lint（ST001-ST004）

🛠 3 个 Skill

• plantsim-kb-qa — 文档问答级联（get_api → did_you_mean 重试 → search_help → 拒绝），强制 **Sources:** 锚点
• plantsim-code-author — Symbol-Lookup-Cascade + API Evidence Table + Refuse-to-Guess
• plantsim-project-analyst — 四个子流程（Locate / Trace / Map / Audit），永远开启继承审计

🛡 2 个 Agent

• plantsim-copilot — 用户面 orchestrator，自动按意图路由到对应 skill，每次回答后调度 reviewer
• citation-reviewer — 单一职责的 sub-agent，三段 regex 检查（anchor 存在 / 来源质量 / 拒绝纪律），返回 JSON 裁决

🧙 一键开箱

git clone https://github.com/JackySummerfield/PlantSim-Agent.git $HOME/.copilot/plantsim-agent
cd $HOME/.copilot/plantsim-agent
.\scripts\install.ps1
pip install -e mcp/
plantsim-copilot-mcp init           # 交互式向导
# 或 CI 自动化：
plantsim-copilot-mcp init --non-interactive --kb-root .\kb_minimal --build

Highlights

• 本地优先：所有索引在你电脑上的 SQLite FTS5 里，问答全程不出机器
• 可追溯：每个回答都附 **Sources:** 或 API Evidence Table，回链到 Help 章节或代码行
• 拒绝瞎编：找不到来源就明确说 ❌ Cannot verify，不让训练数据里的 SimTalk 1.0 老语法溜进去
• 真实项目验证：已在大型物流自动化仿真模型（25,463 objects / 7,698 flow edges）上跑通；并在真实 SimTalk 方法里查出 4 个 lint 问题

Quality bar

• 122 个单元测试（mcp + cold-install）全部通过
• 30/30 评估通过：20 个 QA 召回 + 10 个 citation-recall fixture（tests/eval/，pytest --run-eval）
• 冷装回归：3 个 subprocess 测试守门 init → build → serve 全流程，外加 docs/cold-install.md 7 步手动 checklist

Known limitations (→ v0.2)

• FTS5 索引不包含 section 标题，自然语言查询召回受限 → v0.2 上向量检索
• validate_simtalk 只有 4 条正则规则 → v0.2 升级到 lexer/AST
• 项目只读，不能写回 → v0.2 加 apply_patch / replace_method_body，沿用 citation 审计契约

Compatibility

• Windows only（Plant Simulation 本体只在 Windows 上运行；agent 没有独立价值）
• VS Code 1.99+，GitHub Copilot 最新版
• Python 3.10+
• Tecnomatix Plant Simulation 2024 SP3 / 2025 SP1 测试通过；2025 SP4 (PTS Help 25.04) 是 v0.1 默认目标

Acknowledgments

• Siemens Industry Software — Plant Simulation 帮助文档（用户需自备授权副本）
• VS Code Copilot Custom Agent + MCP 平台让这种深度集成成为可能

Trademark

"Plant Simulation" 与 "Tecnomatix" 是 Siemens AG 的注册商标。本项目与 Siemens 无任何官方关系。

---

📖 Full docs: README (中) · README (en) · Architecture · Roadmap
🐛 Issues: https://github.com/JackySummerfield/PlantSim-Agent/issues