keyshot-mcp 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to KeyShot MCP are documented in this file.
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-01
+
+### Added
+
+- Structured bug and feature request forms, a pull request checklist, support
+  guidance, code ownership, and a bilingual community code of conduct.
+- Weekly Dependabot updates for npm and monthly updates for GitHub Actions.
+- CodeQL analysis for JavaScript and TypeScript changes and a weekly scheduled scan.
+
+### Changed
+
+- Contribution guidance now describes the complete validation suite, real KeyShot
+  testing expectations, compatibility rules, and confidential-asset restrictions.
+- Security guidance now links directly to GitHub private vulnerability reporting.
+- Release validation now checks that required community health files remain present.
+
+## [0.11.0] - 2026-08-12
+
+### Added
+
+- `keyshot_sync_saved_scene`, which detects the newest saved `.bip`, copies it to
+  a collision-safe output, returns a content fingerprint, and optionally embeds a
+  preview.
+- Machine-readable interaction-mode diagnostics so Agents can explain that stable
+  tools work on saved scenes rather than an unsaved GUI session.
+- An original KeyShot MCP project mark and a clearer README introduction,
+  navigation, highlights, and bilingual positioning for easier recognition.
+
+### Changed
+
+- README, Agent Skill, and MCP workflow guidance now explain the tested KeyShot
+  Script Runner limitation and recommend the saved-scene synchronization workflow.
+
 ## [0.10.0] - 2026-08-11
 
 ### Added
@@ -22,5 +55,7 @@ All notable changes to KeyShot MCP are documented in this file.
 
 - Documented that scene metadata and preview images may be sent by an MCP client to its configured model provider.
 
-[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.9.1...v0.10.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Community Code of Conduct / 社区行为准则
+
+## Our standards
+
+KeyShot MCP welcomes designers, developers, testers, technical artists, and
+documentation contributors. Participate respectfully, discuss the work rather than
+the person, accept constructive feedback, and make room for different experience
+levels and languages.
+
+Harassment, discrimination, threats, deliberate disruption, and publication of
+another person's private or confidential information are not accepted. Never upload
+customer assets, private scenes, license data, credentials, or unpublished renders
+without clear authorization from their owner.
+
+Maintainers may edit or remove content, close interactions, or restrict participation
+when behavior puts people, projects, or confidential work at risk. Serious platform
+abuse can also be reported through GitHub's reporting tools.
+
+## 中文说明
+
+KeyShot MCP 欢迎设计师、开发者、测试人员、技术美术和文档贡献者参与。请尊重
+他人，只讨论工作本身，接受建设性反馈，并尊重不同经验水平和语言背景。
+
+社区不接受骚扰、歧视、威胁、蓄意干扰或公开他人隐私和保密信息。未经所有者明确
+授权，不得上传客户资产、私人场景、许可证信息、账号凭据或未公开渲染图。
+
+当行为危害参与者、项目或保密工作时，维护者可以编辑或删除内容、结束讨论或限制
+参与。严重的平台滥用行为也可以通过 GitHub 的举报工具报告。

package/CONTRIBUTING.md

@@ -2,44 +2,93 @@
 
 ## English
 
-Contributions are welcome.
+Contributions are welcome from designers, developers, technical artists, and
+testers. Useful contributions include:
 
-Useful areas:
+- Testing a clean installation or another KeyShot release.
+- Reproducing a workflow problem with generated or non-confidential assets.
+- Improving designer-facing instructions and MCP client examples.
+- Adding focused wrappers for documented KeyShot `lux` APIs.
+- Improving tests, diagnostics, security, or release reliability.
 
-- Test with more KeyShot versions.
-- Improve compatibility with macOS and Linux paths.
-- Add examples for Claude Desktop, Codex, and other MCP clients.
-- Add more precise wrappers for KeyShot `lux` APIs.
+Start with a GitHub Discussion for usage questions. Open an Issue before a large
+implementation so the workflow, KeyShot API availability, compatibility, and safety
+expectations can be agreed first.
 
-Before opening a pull request:
+### Development setup
+
+Requirements: Node.js 20 or newer, pnpm 10, and Python 3.11 or newer.
 
 ```bash
-npm install
-npm run build
-npm run status
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm test
+python -m unittest discover -s tests -p "test_*.py"
+pnpm run format:check
+python -m ruff check scripts tests
+pnpm run docs:tools:check
+node scripts/check-release.mjs
+npm pack --dry-run
 ```
 
-Do not include proprietary KeyShot scenes, license data, customer assets, or private render outputs in issues or pull requests.
+Run `pnpm run smoke:keyshot` only on a computer with a supported, licensed KeyShot
+installation. Record the KeyShot version and operating system in the pull request.
+CI on Linux validates the MCP and bridge logic; it does not verify KeyShot itself.
+
+### Pull requests
 
----
+- Keep changes focused and preserve existing tool names and inputs unless a breaking
+  change has been discussed.
+- Update tests, generated tool documentation, README, Skill, and changelog when the
+  public interface changes.
+- Use generated or clearly redistributable test assets.
+- Explain real KeyShot validation when behavior depends on the `lux` API.
+- Follow the pull request checklist and wait for CI to pass.
+
+Never include proprietary KeyShot scenes, license data, customer assets, credentials,
+private paths, or unpublished renders in Issues, Discussions, commits, or pull requests.
+Report vulnerabilities through GitHub's private security reporting form.
 
 ## 中文
 
-欢迎参与贡献。
+欢迎设计师、开发者、技术美术和测试人员参与。比较有价值的贡献包括：
+
+- 在干净环境或其他 KeyShot 版本上测试安装。
+- 使用项目生成或不保密的素材复现工作流问题。
+- 改进面向设计师的说明和 MCP 客户端示例。
+- 为官方文档公开的 KeyShot `lux` API 增加聚焦的工具封装。
+- 改进测试、诊断、安全和发布可靠性。
 
-比较有价值的方向：
+普通使用问题请先在 GitHub Discussions 讨论。准备较大功能前请先创建 Issue，确认
+工作流、KeyShot API 可用性、兼容范围和安全要求。
 
-- 测试更多 KeyShot 版本。
-- 改进 macOS 和 Linux 路径兼容。
-- 增加 Claude Desktop、Codex 和其他 MCP 客户端示例。
-- 为 KeyShot `lux` API 增加更精确的封装。
+### 开发环境
 
-提交修改前建议先运行：
+需要 Node.js 20 或更高版本、pnpm 10，以及 Python 3.11 或更高版本。
 
 ```bash
-npm install
-npm run build
-npm run status
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm test
+python -m unittest discover -s tests -p "test_*.py"
+pnpm run format:check
+python -m ruff check scripts tests
+pnpm run docs:tools:check
+node scripts/check-release.mjs
+npm pack --dry-run
 ```
 
-请不要在 issue 或 pull request 里上传专有 KeyShot 场景、许可证数据、客户资产或私人渲染结果。
+只有在本机已安装并合法授权 KeyShot 时才运行 `pnpm run smoke:keyshot`，并在 PR 中
+注明操作系统和 KeyShot 版本。Linux CI 只验证 MCP 与 Bridge 逻辑，不代表已经实测
+KeyShot。
+
+### Pull Request
+
+- 保持改动聚焦；除非已讨论破坏性变更，否则保留现有工具名称和输入兼容性。
+- 公共接口变化时同步测试、自动生成工具文档、README、Skill 和 Changelog。
+- 只使用项目生成或明确允许再分发的测试素材。
+- 依赖 `lux` 行为的改动需要说明真实 KeyShot 验证结果。
+- 完成 PR 检查项并等待 CI 通过。
+
+不要在 Issue、Discussion、提交或 PR 中包含专有 KeyShot 场景、许可证数据、客户资产、
+账号凭据、私人路径或未公开渲染图。安全漏洞请通过 GitHub 私密安全报告提交。

package/README.md

@@ -1,35 +1,79 @@
-# KeyShot MCP
-
-[![npm version](https://img.shields.io/npm/v/keyshot-mcp.svg)](https://www.npmjs.com/package/keyshot-mcp)
-[![CI](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-
-[English](#english) | [中文](#中文)
-
-> **Useful for your KeyShot workflow? Star the repository to help other designers discover it.**
->
-> **如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。**
+<p align="center">
+  <img src="assets/logo-lockup.png" width="620" alt="KeyShot MCP">
+</p>
+
+<p align="center">
+  <strong>Turn product-rendering requests into safe, repeatable KeyShot workflows.</strong><br>
+  <strong>将产品渲染需求转化为安全、可重复执行的 KeyShot 工作流。</strong>
+</p>
+
+<p align="center">
+  Inspect scenes, prepare product views, adjust materials, cameras and environments,
+  and return Agent-visible renders through local KeyShot headless scripting.<br>
+  检查场景、准备产品视图、调整材质、相机和环境，并通过本地 KeyShot headless 脚本将渲染结果返回给 Agent。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/keyshot-mcp"><img src="https://img.shields.io/npm/v/keyshot-mcp.svg" alt="npm version"></a>
+  <a href="https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml"><img src="https://github.com/truman-t3/keyshot-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+  <img src="https://img.shields.io/badge/tools-19-55E6A5" alt="19 MCP tools">
+  <img src="https://img.shields.io/badge/MCP-Model_Context_Protocol-111827" alt="Model Context Protocol">
+  <img src="https://img.shields.io/badge/KeyShot-14.1_tested-00AEEF" alt="KeyShot 14.1 tested">
+  <img src="https://img.shields.io/badge/Node.js-20%2B-339933" alt="Node.js 20 or newer">
+  <img src="https://img.shields.io/badge/TypeScript-5.9-3178C6" alt="TypeScript 5.9">
+</p>
+
+<p align="center">
+  <a href="#quick-start-for-designers">Quick start</a> ·
+  <a href="#highlights">Highlights</a> ·
+  <a href="#common-workflows">Workflows</a> ·
+  <a href="#tools">Tools</a> ·
+  <a href="#configuration">Configuration</a>
+</p>
+
+<p align="center"><a href="#english">English</a> · <a href="#中文">简体中文</a></p>
+
+<p align="center">
+  <strong>Useful for your KeyShot workflow? Star the repository to help other designers discover it.</strong><br>
+  <strong>如果它改善了你的 KeyShot 工作流，欢迎点一个 Star，让更多设计师发现这个项目。</strong>
+</p>
 
 KeyShot MCP connects an MCP-compatible AI agent to a licensed KeyShot installation
-on the same computer. It can inspect scenes, import models, apply materials, set
-cameras and environments, save scene copies, and render images through KeyShot
-headless scripting. KeyShot file processing stays local; however, an MCP client may
-send tool results, scene metadata, or embedded previews to its configured model
+on the same computer. KeyShot file processing stays local; however, an MCP client
+may send tool results, scene metadata, or embedded previews to its configured model
 provider. See [Security](SECURITY.md) before using confidential work.
 
 ![KeyShot MCP workflow](assets/workflow.svg)
 
 ## English
 
+### Highlights
+
+- **Start with a request, not a render-settings checklist.** Use one product tool
+  for model import, object materials, camera, environment, scene copy, and output.
+- **See before committing.** Bounded PNG previews are returned directly to the
+  Agent for composition, material, and lighting feedback.
+- **Keep source scenes protected.** Editing workflows write controlled copies and
+  reject output paths outside the configured safe directory by default.
+- **Continue from the latest save.** Saved-scene sync detects real file changes,
+  creates a collision-safe copy, and avoids duplicate work with fingerprints.
+- **Use focused controls when needed.** Nineteen documented tools cover inspection,
+  presets, cameras, materials, environments, render queues, and all-camera output.
+
+> [!NOTE]
+> Tested on Windows 11 with KeyShot Studio 2025 / KeyShot 14.1. KeyShot and a valid
+> license are required and are not included with this independent project.
+
 ### Quick start for designers
 
 The easiest setup is to send this prompt to an agent that can edit your MCP
 configuration:
 
 ```text
-Install KeyShot MCP 0.10.0 and configure it in my MCP client.
+Install KeyShot MCP 0.12.0 and configure it in my MCP client.
 
-1. Use: npx -y keyshot-mcp@0.10.0
+1. Use: npx -y keyshot-mcp@0.12.0
 2. Find my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE to its full path.
 3. Keep outputs in the default KeyShot MCP Outputs folder unless I choose another safe folder.
 4. Keep KEYSHOT_ALLOW_EXTERNAL_OUTPUTS disabled.
@@ -55,9 +99,41 @@ from C:\models\speaker.obj.
   they are not currently verified by this project.
 - KeyShot, its license, materials, and environments are not included.
 
+### Why the stable release does not control the open KeyShot window
+
+The stable server works on saved scene files through KeyShot headless scripting;
+it does not control the currently open, unsaved KeyShot GUI session. This is a
+boundary of the public KeyShot scripting execution model, not an omitted MCP
+connection. KeyShot's Script Runner keeps a GUI script active until that script
+returns. In our Live Companion prototype, keeping a bridge alive also kept the
+Script Runner open and blocked normal interaction with the KeyShot window.
+
+Calling `lux.sync()` can flush pending KeyShot operations, but it does not provide
+a documented background service, GUI event callback, or plugin lifecycle that can
+safely host a persistent MCP bridge. Calling `lux` from an arbitrary worker thread
+would also risk unsafe access to the scene. For that reason, the project does not
+present the experimental bridge as production-ready realtime control.
+
+For a reliable workflow, save the scene first. The Agent can inspect or edit a
+safe copy through headless KeyShot, return a preview, and preserve the original
+file. True realtime GUI control can be reconsidered if KeyShot exposes a supported
+non-blocking GUI extension or main-thread callback API.
+
+Use `keyshot_sync_saved_scene` for the closest stable alternative to realtime
+collaboration. Give it a saved `.bip` file or one folder containing `.bip` files.
+It selects the newest saved scene, computes a content fingerprint, copies it to a
+collision-safe output name, and returns an embedded preview by default. Pass the
+returned fingerprint on the next call; if the user has not saved a new change,
+the tool reports `changed: false` without creating another copy or render.
+
+```text
+I saved my KeyShot scene in C:\projects\speaker. Sync the newest .bip from that
+folder, show me a preview, and do not overwrite the original scene.
+```
+
 ### Install
 
-The current release is `0.10.0`.
+The current release is `0.12.0`.
 
 #### Run with npx
 
@@ -68,7 +144,7 @@ No global npm installation is required:
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.10.0"],
+      "args": ["-y", "keyshot-mcp@0.12.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -80,7 +156,7 @@ No global npm installation is required:
 #### Install globally
 
 ```bash
-npm install -g keyshot-mcp@0.10.0
+npm install -g keyshot-mcp@0.12.0
 ```
 
 ```json
@@ -185,6 +261,7 @@ Lower-level render tools preserve their existing behavior when no preset is give
 | `keyshot_status`                | Diagnose local configuration, output access, presets, and KeyShot startup.    |
 | `keyshot_product_render`        | Prepare, save, and render a model or scene in one process.                    |
 | `keyshot_preview_render`        | Return a temporary or saved PNG directly to the Agent for visual review.      |
+| `keyshot_sync_saved_scene`      | Copy the newest saved scene safely, detect changes, and return a preview.     |
 | `keyshot_inspect_scene`         | List scene metadata, objects, cameras, materials, model sets, and references. |
 | `keyshot_list_cameras`          | Return saved camera names before a selected-camera render.                    |
 | `keyshot_render`                | Render one active or named camera.                                            |
@@ -203,7 +280,7 @@ Lower-level render tools preserve their existing behavior when no preset is give
 
 The server also exposes one MCP Prompt for product rendering and one MCP Resource
 describing the KeyShot headless workflow. The complete generated reference for
-all 18 tools is in [`docs/TOOLS.md`](docs/TOOLS.md). The bundled Agent Skill in
+all 19 tools is available in [`docs/TOOLS.md`](docs/TOOLS.md). The bundled Agent Skill in
 [`skills/keyshot-mcp`](skills/keyshot-mcp) teaches compatible agents how to install,
 diagnose, and use the server safely.
 
@@ -257,10 +334,14 @@ directory. A representative result is included below:
 ### Development
 
 ```bash
-pnpm install
-pnpm check
+pnpm install --frozen-lockfile
+pnpm run check
 pnpm test
 python -m unittest discover -s tests -p "test_*.py"
+pnpm run format:check
+python -m ruff check scripts tests
+pnpm run docs:tools:check
+node scripts/check-release.mjs
 npm pack --dry-run
 ```
 
@@ -268,6 +349,21 @@ CI runs on Windows and Ubuntu with Node.js 20 and 24. Linux CI validates the MCP
 server, bridge logic, metadata, and package; it does not claim that KeyShot itself
 was tested on Linux.
 
+### Community and support
+
+- Ask installation and usage questions in
+  [GitHub Discussions](https://github.com/truman-t3/keyshot-mcp/discussions).
+- Use the structured [Bug report](https://github.com/truman-t3/keyshot-mcp/issues/new?template=bug-report.yml)
+  or [Feature request](https://github.com/truman-t3/keyshot-mcp/issues/new?template=feature-request.yml)
+  forms for actionable project work.
+- Report vulnerabilities through
+  [private vulnerability reporting](https://github.com/truman-t3/keyshot-mcp/security/advisories/new).
+- Read [SUPPORT.md](SUPPORT.md), [CONTRIBUTING.md](CONTRIBUTING.md), and
+  [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before sharing diagnostics or contributing.
+
+Never attach customer scenes, proprietary models, license information, credentials,
+or confidential renders to a public post.
+
 ### Roadmap
 
 - Verify additional supported KeyShot releases on real installations.
@@ -293,14 +389,29 @@ bypass licensing or redistribute proprietary KeyShot software or assets.
 KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具结果、场景元数据或
 内嵌预览发送给它所配置的模型服务。处理保密项目之前请先阅读[安全说明](SECURITY.md)。
 
+### 核心特点
+
+- **从设计需求开始，而不是先填写一堆渲染参数。** 一个产品出图工具即可完成模型导入、
+  指定对象材质、相机、环境、场景副本和渲染输出。
+- **正式出图前先看预览。** 预览 PNG 会直接返回给 Agent，用于检查构图、材质和光线。
+- **保护源场景。** 编辑流程默认生成受控副本，并拒绝向安全输出目录之外写入文件。
+- **从最近一次保存继续。** 保存同步会识别真实文件变化、创建不重名副本，并用内容指纹
+  避免重复处理。
+- **需要精细控制时仍然可用。** 19 个工具覆盖场景检查、预设、相机、材质、环境、
+  渲染队列和全部相机出图。
+
+> [!NOTE]
+> 已实测 Windows 11 + KeyShot Studio 2025 / KeyShot 14.1。使用时需要另行安装并合法
+> 授权 KeyShot；本项目是独立开源项目，不包含 KeyShot 软件或许可证。
+
 ### 设计师快速开始
 
 最简单的安装方式，是把下面这段话发给能够修改 MCP 配置的 Agent：
 
 ```text
-请安装 KeyShot MCP 0.10.0，并配置到我的 MCP 客户端。
+请安装 KeyShot MCP 0.12.0，并配置到我的 MCP 客户端。
 
-1. 使用：npx -y keyshot-mcp@0.10.0
+1. 使用：npx -y keyshot-mcp@0.12.0
 2. 查找本机 keyshot_headless.exe，并把完整路径设置为 KEYSHOT_HEADLESS_EXE。
 3. 默认把结果保存在“文档/KeyShot MCP Outputs”，除非我明确选择其他安全目录。
 4. 保持 KEYSHOT_ALLOW_EXTERNAL_OUTPUTS 关闭。
@@ -324,9 +435,36 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 - 暴露相同脚本 API 的其他 KeyShot 版本可能可用，但本项目暂未完成实机验证。
 - 本项目不包含 KeyShot、许可证、官方材质或环境资源。
 
+### 为什么稳定版不能控制当前打开的 KeyShot 窗口
+
+稳定版通过 KeyShot headless 脚本处理已经保存的场景文件，不能直接控制 KeyShot
+窗口中尚未保存的当前会话。这是 KeyShot 现有公开脚本执行方式的边界，并不是 MCP
+连接功能遗漏。
+
+我们已经制作并实机测试过 Live Companion 原型。为了等待 Agent 指令，Bridge 脚本
+必须长期保持运行；但 KeyShot Script Runner 会一直等待脚本结束，导致脚本窗口持续
+占用并阻挡 KeyShot GUI 的正常交互。`lux.sync()` 只能同步待处理操作，公开文档没有
+提供可安全承载常驻 MCP Bridge 的后台服务、GUI 事件回调或插件生命周期。让普通后台
+线程直接调用 `lux` 也可能造成不安全的场景访问。因此，本项目没有把这个实验方案包装成
+可用于正式工作的“实时控制”。
+
+可靠的工作方式是先保存场景，再让 Agent 使用 headless KeyShot 检查或修改安全副本、
+返回预览并保留原文件。如果 KeyShot 后续公开非阻塞 GUI 扩展接口或主线程回调 API，
+本项目可以重新评估真正的实时 GUI 控制。
+
+`keyshot_sync_saved_scene` 是目前最接近实时协作、同时保持稳定的方案。向它提供一个已
+保存的 `.bip` 文件，或只包含当前项目场景的文件夹。工具会选择最近保存的场景、计算
+内容指纹、复制到不会重名的安全输出路径，并默认返回内嵌预览。下一次调用时传入上次的
+指纹；如果用户没有保存新的修改，工具会返回 `changed: false`，不会重复复制或渲染。
+
+```text
+我已经把 KeyShot 场景保存在 C:\projects\speaker。请同步这个文件夹中最新的 .bip，
+给我看预览，而且不要覆盖原场景。
+```
+
 ### 安装
 
-当前正式版本为 `0.10.0`。
+当前正式版本为 `0.12.0`。
 
 #### 使用 npx 免安装运行
 
@@ -335,7 +473,7 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.10.0"],
+      "args": ["-y", "keyshot-mcp@0.12.0"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -347,7 +485,7 @@ KeyShot MCP 在本机处理 KeyShot 文件；但 MCP 客户端可能会把工具
 #### 全局安装
 
 ```bash
-npm install -g keyshot-mcp@0.10.0
+npm install -g keyshot-mcp@0.12.0
 ```
 
 ```json
@@ -446,6 +584,7 @@ pnpm build
 | `keyshot_status`                | 检查本机配置、输出目录、预设和 KeyShot 启动状态。  |
 | `keyshot_product_render`        | 在一个进程中整理、保存并渲染模型或场景。           |
 | `keyshot_preview_render`        | 将临时或保留的 PNG 直接返回给 Agent 进行视觉检查。 |
+| `keyshot_sync_saved_scene`      | 安全同步最近保存的场景、检测变化并返回预览。       |
 | `keyshot_inspect_scene`         | 查看场景、对象、相机、材质、模型集和外部引用。     |
 | `keyshot_list_cameras`          | 返回场景中的相机名称。                             |
 | `keyshot_render`                | 渲染当前或指定相机。                               |
@@ -463,7 +602,7 @@ pnpm build
 | `keyshot_save_scene`            | 将场景保存到受控输出路径。                         |
 
 服务还提供一个产品渲染 MCP Prompt，以及一个说明 headless 工作流程的 MCP Resource。
-完整的 18 个工具参考由代码自动生成在 [`docs/TOOLS.md`](docs/TOOLS.md)。
+完整的 19 个工具参考由代码自动生成在 [`docs/TOOLS.md`](docs/TOOLS.md)。
 [`skills/keyshot-mcp`](skills/keyshot-mcp) 中的 Agent Skill 会指导兼容的 Agent 安装、
 诊断并安全使用这些工具。
 
@@ -511,16 +650,31 @@ npm run smoke:keyshot
 ### 开发与测试
 
 ```bash
-pnpm install
-pnpm check
+pnpm install --frozen-lockfile
+pnpm run check
 pnpm test
 python -m unittest discover -s tests -p "test_*.py"
+pnpm run format:check
+python -m ruff check scripts tests
+pnpm run docs:tools:check
+node scripts/check-release.mjs
 npm pack --dry-run
 ```
 
 CI 在 Windows 和 Ubuntu 上使用 Node.js 20、24。Linux CI 验证 MCP 服务、bridge、
 元数据和 npm 包，不表示 KeyShot 软件已经在 Linux 上通过实机测试。
 
+### 社区与支持
+
+- 安装和使用问题请在 [GitHub Discussions](https://github.com/truman-t3/keyshot-mcp/discussions) 提问。
+- 可以复现的问题使用 [Bug 报告](https://github.com/truman-t3/keyshot-mcp/issues/new?template=bug-report.yml)，
+  工作流建议使用 [功能建议](https://github.com/truman-t3/keyshot-mcp/issues/new?template=feature-request.yml)。
+- 安全漏洞通过 [私密安全报告](https://github.com/truman-t3/keyshot-mcp/security/advisories/new) 提交。
+- 公开诊断信息或参与贡献前，请阅读 [SUPPORT.md](SUPPORT.md)、
+  [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
+
+不要在公开内容中附加客户场景、专有模型、许可证信息、账号凭据或保密渲染图。
+
 ### 路线图
 
 - 在更多受支持的 KeyShot 正式版本上完成实机验证。

package/SECURITY.md

@@ -30,8 +30,10 @@ execution.
 
 ### Reporting issues
 
-Report vulnerabilities through a private GitHub security advisory before posting
-technical details publicly.
+Report vulnerabilities through the repository's
+[private vulnerability form](https://github.com/truman-t3/keyshot-mcp/security/advisories/new)
+before posting technical details publicly. Include the affected version, impact,
+reproduction steps, and a safe proof of concept that contains no private assets.
 
 ---
 
@@ -60,4 +62,7 @@ KeyShot MCP 本身不会上传文件、运行远程服务或收集遥测数据
 
 ### 报告安全问题
 
-请先通过 GitHub 私密安全公告报告漏洞，不要直接公开技术细节。
+请先通过仓库的
+[私密安全报告入口](https://github.com/truman-t3/keyshot-mcp/security/advisories/new)
+报告漏洞，不要直接公开技术细节。请说明受影响版本、影响、复现步骤，并确保验证材料
+不包含私人资产。

package/SUPPORT.md

@@ -0,0 +1,28 @@
+# Support / 支持
+
+## English
+
+Use the channel that matches the request:
+
+- Installation and usage questions: [GitHub Discussions](https://github.com/truman-t3/keyshot-mcp/discussions)
+- Reproducible bugs: [Bug report](https://github.com/truman-t3/keyshot-mcp/issues/new?template=bug-report.yml)
+- Workflow proposals: [Feature request](https://github.com/truman-t3/keyshot-mcp/issues/new?template=feature-request.yml)
+- Vulnerabilities: [Private security report](https://github.com/truman-t3/keyshot-mcp/security/advisories/new)
+
+Before posting, run `keyshot_status` and remove license credentials, tokens,
+customer names, private paths, scene files, models, and confidential renders.
+Support is provided by the community on a best-effort basis. KeyShot product,
+license, or account support must be requested from KeyShot.
+
+## 中文
+
+请根据问题选择对应入口：
+
+- 安装和使用问题：[GitHub Discussions](https://github.com/truman-t3/keyshot-mcp/discussions)
+- 可以复现的 Bug：[Bug 报告](https://github.com/truman-t3/keyshot-mcp/issues/new?template=bug-report.yml)
+- 工作流建议：[功能建议](https://github.com/truman-t3/keyshot-mcp/issues/new?template=feature-request.yml)
+- 安全漏洞：[私密安全报告](https://github.com/truman-t3/keyshot-mcp/security/advisories/new)
+
+提交前请先运行 `keyshot_status`，并删除许可证、Token、客户名称、私人路径、
+场景文件、模型和保密渲染图。社区维护者会尽力提供支持；KeyShot 软件、许可证
+或账号问题需要联系 KeyShot 官方支持。

package/dist/diagnostics.js

@@ -74,6 +74,13 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
             availableFunctionCount: availableFunctions.length,
             capabilities: capabilitySummary(availableFunctions),
             serverVersion: VERSION,
+            interaction: {
+                mode: "saved-scene-headless",
+                realtimeGuiControl: false,
+                requiresSavedScene: true,
+                recommendedSyncTool: "keyshot_sync_saved_scene",
+                reason: "Persistent GUI scripts keep KeyShot Script Runner active and block normal GUI interaction; the documented scripting API does not expose a supported non-blocking bridge lifecycle.",
+            },
             ready,
             config: {
                 keyshotHeadlessExe: config.keyshotHeadlessExe,