keyshot-mcp 0.13.1 → 0.13.5

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to KeyShot MCP are documented in this file.
 
 ## [Unreleased]
 
+## [0.13.5] - 2026-10-20
+
+### Installation and Diagnostics / 安装与诊断
+
+- Isolate each bridge request in a private temporary subdirectory, clean it after execution, and return structured failures for local filesystem errors. Preserve completed diagnostic checks when startup throws; check temporary storage before launching KeyShot.
+- 每次桥接请求使用独立临时子目录并在执行后清理；本地文件系统出错时返回结构化结果。启动抛异常时保留已完成的诊断，并在启动 KeyShot 前检查临时目录。
+
+- Store bridge request/result files in the system temporary directory instead of the installed package, avoiding Windows path-length failures in nested installations.
+- 将桥接请求与结果文件移到系统临时目录，避免 Windows 嵌套安装路径过长导致 KeyShot 无法写回结果。
+
+### Publication Privacy / 发布隐私
+
+- Add a redacted public-content check to CI and publication, including credential
+  patterns, private paths, file names and PNG metadata. Reject unreviewed binary
+  assets; extend ignore rules for local environment, credential, scene and license files.
+- 为 CI 与发布流程增加脱敏的公开内容检查，覆盖疑似凭据、私人路径、文件名及 PNG 元数据；
+  拦截未经复核的二进制素材，补全本地环境、凭据、场景和许可证文件忽略规则。
+- Bound preview file reads before allocation and while reading, reject special-file
+  output destinations, and check case variants and malformed PNG metadata containers.
+- 预览读取在分配内存前和读取过程中均限制大小，拒绝特殊文件输出目标，并补查文件名
+  大小写变体及损坏的 PNG 元数据容器。
+
+### Output Safety / 输出安全
+
+- Apply default no-overwrite protection to single renders, queued jobs, imports,
+  scene edits and saves. Add optional `overwrite` to low-level writing tools without
+  renaming tools or removing inputs. Declared input files and linked aliases remain
+  protected even with overwrite enabled; scene and image outputs must be distinct.
+- 将默认不覆盖保护统一到单张渲染、队列、导入、场景编辑与保存。底层写入工具增加可选
+  `overwrite`，不改工具名称或删除参数；即使允许覆盖，也不能替换本次声明的输入文件及其
+  链接别名，场景与图片不能写入同一文件。
+- Recheck every generated camera output inside the bridge, protect every queue input,
+  disambiguate selected-camera filenames and avoid deleting rejected preview outputs.
+- bridge 在逐相机写入前重新检查路径，保护整个队列的输入场景，为清理后同名的指定相机
+  生成不同文件名，并避免误删被拒绝的预览输出。
+
+### Documentation / 文档
+
+- Clarify the roles of the MCP client's Agent, client configuration and model provider in privacy notices; distinguish client-managed transmission from the local KeyShot MCP service.
+- 明确隐私提示中 MCP 客户端 Agent、客户端配置与模型服务的职责，区分客户端处理的数据传输与本机 KeyShot MCP 服务。
+
 ## [0.13.1] - 2026-10-15
 
 ### Release Safety / 发布安全
@@ -143,7 +184,8 @@ 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.13.1...HEAD
+[Unreleased]: https://github.com/truman-t3/keyshot-mcp/compare/v0.13.5...HEAD
+[0.13.5]: https://github.com/truman-t3/keyshot-mcp/compare/v0.13.1...v0.13.5
 [0.13.1]: https://github.com/truman-t3/keyshot-mcp/compare/v0.13.0...v0.13.1
 [0.13.0]: https://github.com/truman-t3/keyshot-mcp/compare/v0.12.1...v0.13.0
 [0.12.1]: https://github.com/truman-t3/keyshot-mcp/compare/v0.12.0...v0.12.1

package/CONTRIBUTING.md

@@ -22,6 +22,7 @@ Requirements: Node.js 20 or newer, pnpm 10, and Python 3.11 or newer.
 ```bash
 pnpm install --frozen-lockfile
 pnpm run check
+pnpm run check:public-safety
 pnpm test
 python -m unittest discover -s tests -p "test_*.py"
 pnpm run format:check
@@ -38,6 +39,10 @@ reinspection, invalid-name rejection and an unsupported Wavefront MTL fixture.
 Optionally pass `--material-file "<native KeyShot MTL>"` to test a trusted local
 single-material file. The native file is read only, never copied into the repository.
 Tests use generated geometry and a new output subfolder, not user scenes.
+Run `pnpm run smoke:keyshot:outputs` to check existing-file rejection, source hashes,
+explicit replacement of a distinct copy and PNG output in a new test subfolder.
+Use a fresh `KEYSHOT_OUTPUT_DIR` when repeating the full smoke test, which uses fixed names.
+`pnpm docs:tools` also synchronizes the platform manifest's input schemas.
 CI on Linux validates the MCP and bridge logic; it does not verify KeyShot itself.
 
 ### Pull requests
@@ -54,6 +59,9 @@ Never include proprietary KeyShot scenes, license data, customer assets, credent
 private paths, or unpublished renders in Issues, Discussions, commits, or pull requests.
 Report vulnerabilities through GitHub's private security reporting form.
 
+Use a GitHub no-reply commit email. Check filenames and image metadata as well as
+visible content; new public images require review in `scripts/check-public-safety.mjs`.
+
 ## 中文
 
 欢迎设计师、开发者、技术美术和测试人员参与。比较有价值的贡献包括：
@@ -74,6 +82,7 @@ Report vulnerabilities through GitHub's private security reporting form.
 ```bash
 pnpm install --frozen-lockfile
 pnpm run check
+pnpm run check:public-safety
 pnpm test
 python -m unittest discover -s tests -p "test_*.py"
 pnpm run format:check
@@ -89,6 +98,9 @@ KeyShot。
 运行 `pnpm run smoke:keyshot:materials` 可验证材质预设、保存后复查、无效名称及不支持的
 Wavefront MTL 拒绝；可选传入 `--material-file "<KeyShot 原生 MTL>"` 检查可信本地单材质文件。
 原生文件只读，不复制进仓库；测试仅使用生成模型和新输出子目录，不覆盖用户场景。
+运行 `pnpm run smoke:keyshot:outputs` 可验证重名拒绝、源文件哈希、明确覆盖另一份副本及
+PNG 输出，文件保存在新测试子目录。完整 smoke 使用固定文件名，重复运行时请设置新的
+`KEYSHOT_OUTPUT_DIR`。`pnpm docs:tools` 同时同步平台清单中的输入 Schema。
 
 ### Pull Request
 
@@ -100,3 +112,6 @@ Wavefront MTL 拒绝；可选传入 `--material-file "<KeyShot 原生 MTL>"` 检
 
 不要在 Issue、Discussion、提交或 PR 中包含专有 KeyShot 场景、许可证数据、客户资产、
 账号凭据、私人路径或未公开渲染图。安全漏洞请通过 GitHub 私密安全报告提交。
+
+提交使用 GitHub no-reply 邮箱；除可见内容外，也检查文件名和图片元数据。
+新增公开图片需要在 `scripts/check-public-safety.mjs` 中完成复核登记。

package/README.md

@@ -44,9 +44,14 @@
 > computer as KeyShot. It does not read unsaved edits or control the open KeyShot window.
 > **处理已保存的场景，不是实时 GUI 控制。** 服务在本机后台运行 KeyShot，不能读取窗口中尚未保存的修改。
 >
-> File processing is local, but your client may send scene metadata and previews
-> to its model provider. Review [privacy and security](SECURITY.md) before confidential work.
-> 文件处理在本机完成，但客户端可能把场景信息和预览发送给模型服务；保密项目请先阅读[隐私与安全说明](SECURITY.md)。
+> **Client Agent and privacy.** The Agent in your MCP client receives scene information
+> and previews returned by tools. Depending on the client's implementation and settings,
+> these results may be sent to its configured model provider. KeyShot MCP itself does
+> not upload them. Review [privacy and security](SECURITY.md) before confidential work.
+>
+> **客户端 Agent 与隐私。** MCP 客户端中的 Agent 会接收工具返回的场景信息和预览；
+> 这些内容可能根据客户端的实现与配置发送给其所选模型服务。KeyShot MCP 本身不主动上传这些内容。
+> 保密项目请先阅读[隐私与安全说明](SECURITY.md)。
 
 ## From a Request to a Render / 一句话到出图
 
@@ -111,11 +116,12 @@ licensed KeyShot edition with headless scripting. **Windows 11 + KeyShot Studio
 2025 / KeyShot 14.1 is tested.** Other systems and KeyShot versions are not verified.
 KeyShot software, licenses and library assets are not included.
 
-<!-- release-version: 0.13.1 -->
+<!-- release-version: 0.13.5 -->
 
-**Version 0.13.1** includes verified material assignments, clearer material-file
-errors and the updated designer workflow documentation. Installation examples
-below target this version. See the [release validation record and 1.0 checklist](docs/RELEASE-READINESS.md).
+**Version 0.13.5.** This maintenance batch
+strengthens output protection, bounded previews, publication privacy, Windows
+installation paths and startup diagnostics. Installation examples below target
+this version. See the [release validation record and 1.0 checklist](docs/RELEASE-READINESS.md).
 See [Changelog](CHANGELOG.md) and [upgrade notes](docs/UPGRADING.md).
 
 #### Ask Your Agent to Install
@@ -123,7 +129,7 @@ See [Changelog](CHANGELOG.md) and [upgrade notes](docs/UPGRADING.md).
 Send this to an Agent that can edit your client's MCP configuration:
 
 ```text
-Install KeyShot MCP 0.13.1 in my MCP client using npx -y keyshot-mcp@0.13.1.
+Install KeyShot MCP 0.13.5 in my MCP client using npx -y keyshot-mcp@0.13.5.
 Find the full path of my local keyshot_headless.exe and set KEYSHOT_HEADLESS_EXE.
 Keep the default Documents/KeyShot MCP Outputs folder and external outputs disabled.
 Use my client's configuration format, restart or reload it, and run keyshot_status.
@@ -142,7 +148,7 @@ and replace the executable path with the actual path on your computer.
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.13.1"],
+      "args": ["-y", "keyshot-mcp@0.13.5"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -157,7 +163,7 @@ the executable, output access, bridge, presets and a minimal KeyShot startup.
 <details>
 <summary>Global npm installation or source build</summary>
 
-**Global:** run `npm install -g keyshot-mcp@0.13.1`, then use `keyshot-mcp` as the
+**Global:** run `npm install -g keyshot-mcp@0.13.5`, then use `keyshot-mcp` as the
 client command with no `npx` arguments. Keep the same environment settings.
 
 **Source:**
@@ -306,15 +312,19 @@ See [material assignment and error guidance](docs/MATERIALS.md).
 
 Inputs can come from any trusted local path. Output traversal and symlink/junction
 escapes are rejected by default. Automatically named product outputs use `-2`,
-`-3`, etc. on collision; explicit paths are not silently renamed. Enable `overwrite`
-only where supported and when replacement is intentional. Prefer scene copies.
+`-3`, etc. on collision; explicit paths are not silently renamed. Writing tools reject
+existing files by default. Set `overwrite: true` only to replace a distinct output
+intentionally; it never permits replacing this request's input scene, model, material
+or environment, including linked aliases. Preview and saved-scene sync never overwrite.
+Keep scene and image destinations separate. Prefer scene copies.
 KeyShot headless tasks run sequentially within each server instance to reduce
 license and file conflicts; this does not coordinate separate MCP server processes.
 
-Processing is local, **but your MCP client may send tool results, scene metadata
-and preview images to its selected model provider**. Review privacy settings
-before confidential work. No license bypass or arbitrary Python execution is
-provided. See [Security](SECURITY.md).
+Processing is local. When an Agent in your MCP client uses these tools, **the client
+may send tool results, scene metadata and preview images to its selected model provider**,
+depending on the client's implementation and settings. KeyShot MCP itself does not
+upload these results. Review privacy settings before confidential work. No license
+bypass or arbitrary Python execution is provided. See [Security](SECURITY.md).
 
 ### Questions and Support
 
@@ -374,8 +384,9 @@ Community conduct is covered by [Code of Conduct](CODE_OF_CONDUCT.md).
 KeyShot**。已实测 **Windows 11 + KeyShot Studio 2025 / KeyShot 14.1**；其他系统和
 KeyShot 版本尚未实机验证。项目不包含 KeyShot、许可证或官方材质库。
 
-**本版为 `0.13.1`：** 包含材质实际赋值校验、更明确的材质文件错误提示及更新后的设计师工作流文档。
-下方安装示例使用此版本。验证记录与正式版准备见[验收清单](docs/RELEASE-READINESS.md)，
+**本版为 `0.13.5`：** 集中加固输出保护、预览大小限制、发布隐私、
+Windows 安装路径和启动诊断。下方安装示例使用此版本。
+验证记录与正式版准备见[验收清单](docs/RELEASE-READINESS.md)，
 版本变更见[更新记录](CHANGELOG.md)和[升级说明](docs/UPGRADING.md)。
 
 #### 把安装交给 Agent
@@ -383,7 +394,7 @@ KeyShot 版本尚未实机验证。项目不包含 KeyShot、许可证或官方
 将下面这段话发给能够修改客户端 MCP 配置的 Agent：
 
 ```text
-请用 npx -y keyshot-mcp@0.13.1 将 KeyShot MCP 安装到我的 MCP 客户端。
+请用 npx -y keyshot-mcp@0.13.5 将 KeyShot MCP 安装到我的 MCP 客户端。
 找到本机 keyshot_headless.exe 的完整路径，设置 KEYSHOT_HEADLESS_EXE。
 保留默认“文档/KeyShot MCP Outputs”输出目录，关闭外部输出。
 按这个客户端实际支持的格式配置，重启或重新加载后运行 keyshot_status。
@@ -402,7 +413,7 @@ KeyShot 版本尚未实机验证。项目不包含 KeyShot、许可证或官方
   "mcpServers": {
     "keyshot": {
       "command": "npx",
-      "args": ["-y", "keyshot-mcp@0.13.1"],
+      "args": ["-y", "keyshot-mcp@0.13.5"],
       "env": {
         "KEYSHOT_HEADLESS_EXE": "C:/Program Files/KeyShot Studio/bin/keyshot_headless.exe"
       }
@@ -417,7 +428,7 @@ KeyShot 版本尚未实机验证。项目不包含 KeyShot、许可证或官方
 <details>
 <summary>全局 npm 安装或源码运行</summary>
 
-**全局安装：** 运行 `npm install -g keyshot-mcp@0.13.1`，客户端命令改成 `keyshot-mcp`，
+**全局安装：** 运行 `npm install -g keyshot-mcp@0.13.5`，客户端命令改成 `keyshot-mcp`，
 不再填写 `npx` 参数；环境变量保持一致。
 
 **源码运行：**
@@ -549,12 +560,15 @@ pnpm run build
 
 输入可以来自任意可信本地路径。默认拒绝越界路径及软链接/目录联接逃逸。
 产品工具自动命名的输出重名时使用 `-2`、`-3` 等编号，显式路径不被静默改名。
-仅在工具支持且确实要替换文件时开启 `overwrite`，平时使用场景副本。
+写入工具默认拒绝覆盖已有文件。只有确实要替换另一个输出文件时才设置
+`overwrite: true`；即使开启，也不能覆盖本次调用的输入场景、模型、材质或环境文件，
+包括指向它们的链接。预览与保存同步始终不覆盖。场景和图片必须使用不同路径，平时使用场景副本。
 同一个服务实例内的 KeyShot 后台任务按顺序执行，以减少许可证和文件冲突；
 多个独立 MCP 服务进程之间不共享这一排队机制。
 
-处理在本机完成，**但 MCP 客户端可能把工具结果、场景元数据和预览图发送给所选模型
-服务**。保密项目请先核对隐私设置。项目不提供许可证绕过或任意 Python 执行。
+处理在本机完成。**MCP 客户端中的 Agent 使用工具时，返回的工具结果、场景元数据和
+预览图可能根据客户端的实现与配置发送给所选模型服务。** KeyShot MCP 本身不主动上传
+这些内容。保密项目请先核对隐私设置。项目不提供许可证绕过或任意 Python 执行。
 更多说明见 [SECURITY.md](SECURITY.md)。
 
 ### 常见问题与支持

package/SECURITY.md

@@ -7,11 +7,12 @@ model, material, and environment files and can write rendered images or scene co
 
 ### Model-provider data flow
 
-MCP clients normally send tool inputs and results to the model service selected by
-the user. Scene metadata returned by inspection tools and images returned by
-`keyshot_preview_render` may therefore leave the local computer through that MCP
-client. Review the client and model provider's privacy settings before using private
-or customer work.
+The Agent in an MCP client receives tool results, including scene metadata and
+images returned by `keyshot_preview_render`. Depending on the client's implementation
+and settings, those results may be sent to the user's selected model service.
+The MCP client controls this data transmission; it is not an upload initiated by
+KeyShot MCP. Review the client and model provider's privacy settings before using
+private or customer work.
 
 KeyShot MCP itself does not upload files, run a remote service, or collect telemetry.
 It never requires license keys in prompts and does not expose arbitrary Python
@@ -28,6 +29,37 @@ execution.
   explicitly required and trusted.
 - Review a preview before approving edits or final renders, and preserve source scenes.
 
+### Output protection
+
+Writing tools reject existing files unless `overwrite: true` is explicitly supported
+and requested. Input files declared in the call (including material assignments) and
+all scene inputs in a render queue remain protected even when overwrite is enabled.
+Path comparisons resolve links and detect hard-linked input aliases. Image and scene
+outputs must not share the same file. Preview and saved-scene sync never overwrite.
+
+Paths are checked before headless startup and again in the bridge immediately before
+each save or render, including camera-generated names. These checks are not a filesystem
+sandbox or a cross-process lock: do not run unrelated writers against the same output
+files or modify their links while a task runs. Use a separate output folder per process.
+
+Existing low-level workflows that previously replaced a file implicitly now need a new
+destination or explicit `overwrite: true`; overwriting a declared input is not supported.
+
+### Publication checks
+
+Maintainers run `pnpm run check:public-safety` before a pull request or release.
+CI rejects credential-like values, personal home paths, unreviewed image filenames,
+scene/license files and suspicious PNG metadata in the tracked publication source.
+Public example paths must be generic. New images require explicit review before being
+added to the reviewed-image list; retain third-party credits and licenses.
+
+The check is a rule-based guard, not proof that an asset is non-confidential. It does
+not remove old commits, cached packages, uploaded release artifacts or public issue
+attachments. Review Git history separately, use a GitHub no-reply commit email and
+sanitize diagnostics before sharing: local file paths, scene names and KeyShot output
+can identify a project even without a credential. If a real credential is exposed,
+revoke it first; deleting a file from the latest commit is not sufficient.
+
 ### Reporting issues
 
 Report vulnerabilities through the repository's
@@ -44,9 +76,10 @@ KeyShot MCP 在本机运行 KeyShot headless。它可以读取本地场景、模
 
 ### 模型服务的数据流
 
-MCP 客户端通常会把工具输入和结果发送给用户选择的模型服务。因此，场景检查工具
-返回的元数据，以及 `keyshot_preview_render` 返回的预览图片，可能通过 MCP 客户端
-离开本机。处理私有项目或客户项目之前，请先确认 MCP 客户端和模型服务商的隐私设置。
+MCP 客户端中的 Agent 会接收工具结果，包括场景检查返回的元数据和
+`keyshot_preview_render` 返回的预览图片。这些内容可能根据客户端的实现与配置发送给
+用户选择的模型服务。数据传输由 MCP 客户端处理，不是 KeyShot MCP 主动上传。
+处理私有项目或客户项目之前，请先确认 MCP 客户端和模型服务商的隐私设置。
 
 KeyShot MCP 本身不会上传文件、运行远程服务或收集遥测数据。它不会要求用户在提示词
 中提供许可证密钥，也不开放任意 Python 执行。
@@ -60,6 +93,31 @@ KeyShot MCP 本身不会上传文件、运行远程服务或收集遥测数据
 - 除非明确需要并信任外部位置，否则保持 `KEYSHOT_ALLOW_EXTERNAL_OUTPUTS` 关闭。
 - 批准修改或最终渲染前先检查预览，并保留原始场景。
 
+### 输出保护
+
+写入工具默认拒绝覆盖已有文件，仅在工具支持且明确设置 `overwrite: true` 时允许替换。
+本次调用声明的输入文件（包括材质赋值中的文件）和渲染队列中所有任务的输入场景，
+即使开启覆盖也仍受保护。路径比较会解析链接，并识别输入文件的硬链接别名。
+场景与图片不能写入同一文件；预览与保存同步始终不覆盖。
+
+服务在启动后台进程前检查路径，bridge 在每次保存、渲染前再次检查，包括按相机名生成的路径。
+这些检查不是文件系统沙箱或跨进程锁：任务运行期间不要让其他程序写同一输出文件，
+也不要修改相关链接。多个进程应使用不同输出文件夹。
+
+以前依赖底层工具隐式替换文件的流程，需要改用新路径或显式 `overwrite: true`；
+覆盖本次声明的输入文件不受支持。
+
+### 发布前检查
+
+维护者在 PR 或发布前运行 `pnpm run check:public-safety`。CI 检查疑似凭据、个人用户目录、
+未经复核的图片文件名、场景或许可证文件及 PNG 元数据。公开示例只用通用占位路径。
+新图片经明确复核后才能加入已审核图片清单；保留第三方作者与许可说明。
+
+规则扫描不能证明素材一定不保密，也不会删除旧提交、缓存发布包、Release 附件或公开
+Issue 附件。Git 历史需要单独审查；提交使用 GitHub no-reply 邮箱。分享诊断前先脱敏，
+本机路径、场景名和 KeyShot 输出即使不含密钥，也可能识别项目。真实凭据一旦公开，
+应先撤销，仅从最新提交删除文件是不够的。
+
 ### 报告安全问题
 
 请先通过仓库的

package/dist/config.js

@@ -13,7 +13,7 @@ export function getConfig() {
         keyshotAllowExternalOutputs: parseBoolean(process.env.KEYSHOT_ALLOW_EXTERNAL_OUTPUTS),
         keyshotLicenseArgs: splitWindowsArgs(process.env.KEYSHOT_LICENSE_ARGS ?? ""),
         keyshotTimeoutMs: parsePositiveInt(process.env.KEYSHOT_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
-        tmpDir: path.join(projectRoot, "work", "tmp"),
+        tmpDir: path.join(os.tmpdir(), "keyshot-mcp"),
         bridgeScriptPath: path.join(projectRoot, "scripts", "keyshot_bridge.py"),
         materialPresetsPath: path.resolve(process.env.KEYSHOT_MATERIAL_PRESETS ??
             path.join(projectRoot, "presets", "materials.json")),

package/dist/diagnostics.js

@@ -5,6 +5,7 @@ import { loadCameraPresets } from "./camera-presets.js";
 import { loadMaterialPresets } from "./presets.js";
 import { runKeyShotSerialized } from "./runner.js";
 import { VERSION } from "./version.js";
+import { localFailure } from "./result.js";
 export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerialized) {
     const checks = [];
     const resolvedExecutable = await resolveExecutable(config.keyshotHeadlessExe);
@@ -22,12 +23,24 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
     });
     checks.push(await fileCheck("bridge-script", "KeyShot bridge script", config.bridgeScriptPath, "Reinstall keyshot-mcp so scripts/keyshot_bridge.py is included."));
     checks.push(await outputWriteCheck(config.keyshotOutputDir));
+    checks.push(await outputWriteCheck(config.tmpDir, "temporary-directory", "Temporary directory", "Check that your system temporary directory is writable, then restart the MCP client. 请检查系统临时目录写入权限，然后重启 MCP 客户端。"));
     checks.push(await presetCheck("camera-presets", "Camera presets", () => loadCameraPresets(config), config.cameraPresetsPath));
     checks.push(await presetCheck("material-presets", "Material presets", () => loadMaterialPresets(config), config.materialPresetsPath));
     let keyshotResult;
     if (resolvedExecutable &&
-        checks.find((check) => check.id === "bridge-script")?.ok) {
-        keyshotResult = await runStatus(config, { operation: "status" });
+        checks.every((check) => check.severity !== "error" || check.ok)) {
+        try {
+            keyshotResult = await runStatus(config, { operation: "status" });
+        }
+        catch (error) {
+            keyshotResult = localFailure(errorMessage(error), {
+                errorCode: "KEYSHOT_STARTUP_FAILED",
+                suggestions: [
+                    "Check local folder permissions and KeyShot startup, then retry keyshot_status.",
+                    "请检查本地目录权限及 KeyShot 能否启动，然后重试 keyshot_status。",
+                ],
+            });
+        }
     }
     else {
         keyshotResult = {
@@ -36,7 +49,7 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
             outputFiles: [],
             warnings: [],
             keyshotStdoutTail: "",
-            error: "KeyShot startup was skipped because a required local file was not available.",
+            error: "KeyShot startup was skipped because a required local check failed.",
             errorCode: "DIAGNOSTIC_PREREQUISITE_FAILED",
             suggestions: [],
         };
@@ -88,6 +101,7 @@ export async function runKeyShotDiagnostics(config, runStatus = runKeyShotSerial
                 outputDir: config.keyshotOutputDir,
                 allowExternalOutputs: config.keyshotAllowExternalOutputs,
                 timeoutMs: config.keyshotTimeoutMs,
+                temporaryDir: config.tmpDir,
                 licenseArgsConfigured: config.keyshotLicenseArgs.length > 0,
                 bridgeScriptPath: config.bridgeScriptPath,
                 cameraPresetsPath: config.cameraPresetsPath,
@@ -150,29 +164,29 @@ async function fileCheck(id, label, filePath, suggestion) {
         suggestion: ok ? undefined : suggestion,
     };
 }
-async function outputWriteCheck(outputDir) {
+async function outputWriteCheck(outputDir, id = "output-directory", label = "Output directory", suggestion = "Set KEYSHOT_OUTPUT_DIR to a local folder where the current user can create files.") {
     const probe = path.join(outputDir, `.keyshot-mcp-write-test-${randomUUID()}`);
     try {
         await fs.mkdir(outputDir, { recursive: true });
         await fs.writeFile(probe, "ok", "utf8");
         await fs.rm(probe, { force: true });
         return {
-            id: "output-directory",
-            label: "Output directory",
+            id,
+            label,
             ok: true,
             severity: "error",
-            message: `Output directory is writable: ${outputDir}`,
+            message: `${label} is writable: ${outputDir}`,
         };
     }
     catch (error) {
         await fs.rm(probe, { force: true }).catch(() => undefined);
         return {
-            id: "output-directory",
-            label: "Output directory",
+            id,
+            label,
             ok: false,
             severity: "error",
-            message: `Output directory is not writable: ${outputDir} (${errorMessage(error)})`,
-            suggestion: "Set KEYSHOT_OUTPUT_DIR to a local folder where the current user can create files.",
+            message: `${label} is not writable: ${outputDir} (${errorMessage(error)})`,
+            suggestion,
         };
     }
 }

package/dist/output-paths.js

@@ -1,6 +1,79 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 const OUTPUT_FIELDS = ["outputPath", "outputDir", "outputScenePath"];
+const INPUT_FIELDS = new Set([
+    "scenePath",
+    "sourcePath",
+    "modelPath",
+    "baseScenePath",
+    "materialPath",
+    "environmentPath",
+]);
+export function inputFilePaths(value) {
+    if (Array.isArray(value))
+        return value.flatMap(inputFilePaths);
+    if (!value || typeof value !== "object")
+        return [];
+    return Object.entries(value).flatMap(([key, entry]) => {
+        if (INPUT_FIELDS.has(key) && typeof entry === "string")
+            return [entry];
+        if (key === "_protectedInputPaths" && Array.isArray(entry))
+            return entry.filter((item) => typeof item === "string");
+        return inputFilePaths(entry);
+    });
+}
+export async function assertOutputFilesSafe(request) {
+    const inputs = inputFilePaths(request);
+    const outputs = [request.outputScenePath, request.outputPath].filter((value) => typeof value === "string");
+    for (let index = 0; index < outputs.length; index += 1) {
+        const output = outputs[index];
+        for (const input of inputs) {
+            if (await sameFile(output, input))
+                throw new Error(`Output must not replace an input file: ${output}`);
+        }
+        for (const previous of outputs.slice(0, index)) {
+            if (await sameFile(output, previous))
+                throw new Error(`Output paths must refer to different files: ${output}`);
+        }
+        try {
+            const stat = await fs.lstat(output);
+            let target = stat;
+            if (stat.isSymbolicLink()) {
+                try {
+                    target = await fs.stat(output);
+                }
+                catch {
+                    throw new Error(`Output file path must be a regular file: ${output}`);
+                }
+            }
+            if (target.isDirectory())
+                throw new Error(`Output file path is a directory: ${output}`);
+            if (!target.isFile())
+                throw new Error(`Output file path must be a regular file: ${output}`);
+            if (request.overwrite !== true)
+                throw new Error(`Output already exists and overwrite is false: ${output}`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+async function sameFile(first, second) {
+    if (normalizeCase(await realpathWithMissingTail(first)) ===
+        normalizeCase(await realpathWithMissingTail(second)))
+        return true;
+    try {
+        const a = await fs.stat(first, { bigint: true });
+        const b = await fs.stat(second, { bigint: true });
+        return a.ino !== 0n && a.dev === b.dev && a.ino === b.ino;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
 export async function normalizeOutputPaths(config, request) {
     await fs.mkdir(config.keyshotOutputDir, { recursive: true });
     const normalized = { ...request };