星桥三联：StarBridge Creative Software MCP

Current Capability Matrix

Photoshop, Illustrator, Blender, and CapCut write flows are experimental or planned unless a reviewed local run proves otherwise.

GitHub description 建议： Codex Computer Use + StarBridge MCP + Safety Verification Layer for local creative software, with GUI inspection, structured tools, redacted checks, and CI validation.

项目状态：v0.1-alpha

这个仓库当前是 v0.1-alpha 工程原型，不是完整多软件生产平台。定位是 Windows-first、local-first 的 MCP stdio server + tool registry + safety verification layer，用于让 Codex / Cursor / Claude Code 以可验证方式接入本机创意软件。StarBridge 不替代 ComfyUI、Photoshop、Illustrator、AutoCAD、Blender、剪映/CapCut 或 GUI Computer Use；它只把已经能测试的本地能力收敛成结构化工具，并把实验能力和计划能力明确分开。StarBridge v0.2 的重点是 EvidenceManifest + JobStatus，而不是继续扩张软件数量。

当前真实能力分层：

v0.1-alpha 已有且可以验证：

• MCP stdio server：python -m starbridge_mcp.mcp_server
• 工具注册表：npm.cmd run starbridge:tools:safe
• 总状态与安全状态：npm.cmd run bridge:status:safe
• ComfyUI：offline-safe probe、workflow JSON validate；真实生成任务仍依赖本机 ComfyUI 和显式 checkpoint。
• AutoCAD/DXF：自然语言/JSON plan、validate_cad_plan、dry-run、confirm_write 受控写入 examples/cad/output、manifest/report。
• Adobe / Blender / CapCut：已有部分 probe/demo 入口，但生产级写入闭环仍是 experimental 或 planned。

关键文档：

• docs/CAPABILITY_MATRIX.md：逐桥能力矩阵，区分 reads/writes/dry-run/真实软件依赖。
• docs/RELEASE_V0_1_ALPHA.md：v0.1-alpha 只承诺当前真实可运行能力。
• docs/comfyui-agent-workflow-protocol.md：ComfyUI 智能体自动搭建、修复、运行 workflow 的可视化协议。
• docs/client-compatibility.md：Claude Desktop / Cursor / Codex / mock stdio 兼容状态。
• docs/windows-install.md：Windows 本地开发安装说明。
• SECURITY.md：公开仓库安全边界。

最短运行路径：

python -m pytest
npm.cmd test
npm.cmd run preflight
npm.cmd run bridge:status:safe
npm.cmd run starbridge:tools:safe
python scripts\security_check.py
python scripts\collect_bridge_status.py --json
python scripts\bridge_capability_matrix.py --check
python scripts\starbridge_preflight.py --markdown
python scripts\starbridge_preflight.py --write-report --soft-exit
python examples\bridge_status.py --json --redact-paths --soft-exit
python examples\cad\generate_dxf_plan.py

CI 候选检查使用下面这些命令：

python -m compileall .
python -m unittest discover -s tests
python scripts/security_check.py
python scripts/collect_bridge_status.py --json
python examples/bridge_status.py --json --redact-paths --soft-exit
python -m starbridge_mcp.server tools --json --safe-only
python -m starbridge_mcp.server evidence --init --json
python -m starbridge_mcp.server evidence --validate --json
python -m starbridge_mcp.server job-status --json

See docs/demo-illustrator.md and docs/demo-photoshop.md. Real outputs go to examples/output/ and are ignored by Git.

Release Readiness

• Visual evidence: docs/adobe-demo-gallery.md
• Local smoke test: docs/adobe-demo-smoke-test.md
• Draft release notes: RELEASE_NOTES_DRAFT.md
• Computer Use architecture: docs/starbridge.md
• GitHub comparison notes: docs/github-comparison.md

English quick summary: StarBridge is a Windows-first, local-first MCP stdio server and safety bridge for connecting AI coding agents to creative desktop software: ComfyUI, Blender, AutoCAD / DXF, Photoshop, Illustrator, and CapCut / Jianying. It focuses on safe probes, workflow validation, redacted status reports, and guarded automation examples instead of uploading private assets or replacing the creative tools.

Search keywords: MCP, Model Context Protocol, Codex, AI agent, creative software automation, ComfyUI workflow, Blender automation, AutoCAD DXF, Photoshop COM, Illustrator scripting, CapCut Jianying, local-first AI tools.

这个仓库整理 Codex 接入本机创作软件 的公开方案。新定位不是“用 StarBridge 替代 Computer Use”，而是把两者分工清楚：Computer Use 看真实 GUI、点击和复现问题；StarBridge MCP 把稳定动作做成参数化工具；Safety layer 在两者外侧做路径脱敏、权限边界、只读检查和发布前体检。成熟的只读检查、workflow 校验和受保护 DXF 能力继续通过 MCP stdio tools 交给 Codex / Cursor / Claude Code 调用。

公开仓库只保存说明、协议、示例脚本、workflow、MCP stdio server、工具注册表和安全检查。不保存个人路径、账号、模型、素材、生成图、客户图纸、授权信息或本机缓存。

中文阅读指南

如果你第一次打开这个仓库，按这三步走就够了：

最短状态检查：

python examples\bridge_status.py
python examples\bridge_status.py --json
python examples\bridge_status.py --json --redact-paths --soft-exit
python examples\bridge_status.py --probe-executables

也可以通过 npm 快捷命令运行：

npm.cmd run bridge:status:json
npm.cmd run bridge:status:safe

如果 PowerShell 拦截 npm.ps1，优先使用 npm.cmd。

For English Readers

Start with this README and docs/local-mcp-setup.md. Most project notes are Chinese-first because the current workstation and software setup are Windows-first, but commands, tool names, environment variables, and MCP APIs are kept in English.

Useful entry points:

这个仓库解决什么

它把本地创作工作站拆成多条清楚的软件桥：

一句话原则：Computer Use 管 GUI 观察和交互复现，StarBridge 管结构化安全边界，MCP 管稳定工具调用，Safety layer 管脱敏验证，专业软件管真实生产，私有资产只留本机。

按目标选择入口

仓库区域标注

运行前配置

真实安装路径不要写进 GitHub。每台电脑用环境变量或本地 .env 管理：

本地输出、报告、图片、DWG、PSD、缓存和日志应放在 output/、scratch/ 或其他本机私有目录，并保持在 Git 提交之外。

常用命令

检查已接入桥

python examples\bridge_status.py
python examples\bridge_status.py --json
python examples\bridge_status.py --json --redact-paths --soft-exit
python examples\bridge_status.py --probe-executables

发布前体检

python scripts\starbridge_preflight.py --markdown
python scripts\starbridge_preflight.py --json
python scripts\starbridge_preflight.py --write-report --soft-exit
python scripts\security_check.py

StarBridge MCP

python -m starbridge_mcp.server --json
python -m starbridge_mcp.server tools --json --safe-only
python -m starbridge_mcp.server evidence --init --json
python -m starbridge_mcp.server evidence --validate --json
python -m starbridge_mcp.server job-status --json
python -m starbridge_mcp.mcp_server
npm.cmd run starbridge:mcp

MCP 客户端可发现首批安全工具：starbridge.status、starbridge.probe、starbridge.tools、starbridge.evidence_init、starbridge.evidence_validate、starbridge.job_status、comfyui.system_probe、comfyui.workflow_validate、blender.environment_probe、cad_autocad.environment_probe、photoshop.session_info、illustrator.document_info、jianying_capcut.draft_probe、autocad_dxf.status、autocad_dxf.validate_cad_plan、autocad_dxf.create_dxf_plan、autocad_dxf.summarize_plan 和 autocad_dxf.write_dxf。

Evidence / Job lifecycle

python -m starbridge_mcp.server evidence --init --json
python -m starbridge_mcp.server evidence --validate --json
python -m starbridge_mcp.server job-status --json

默认 manifest 写入 examples/output/evidence/manifest.latest.json。这里只保留脱敏 JSON 证据和状态摘要，不保存客户素材、模型、PSD、AI、DWG 或真实导出结果。

ComfyUI

python examples\comfy_bridge\comfy_probe.py
python examples\comfy_bridge\validate_workflow.py --json
python examples\comfy_bridge\validate_workflow.py --workflow examples\comfy_bridge\workflows\minimal_api_workflow.json --json
python examples\comfy_bridge\run_txt2img.py --prompt "a quiet futuristic tea house in a garden" --ckpt "<checkpoint-name>"

ComfyUI closed loop demo：先用 npm.cmd run comfy:probe 和 npm.cmd run comfy:workflow:validate 做只读检查；本机 ComfyUI 启动后，再运行 python examples\comfy_bridge\run_txt2img.py --prompt "a quiet futuristic tea house in a garden" --ckpt "<checkpoint-name>" 提交一次 txt2img。脚本会查询 /history/{prompt_id}，在 examples/output/comfyui/demo_manifest.json 写入脱敏 lifecycle 摘要；该 manifest 和真实生成图都被 .gitignore 忽略，不提交到 GitHub。

ComfyUI safe workflow loop

本轮 ComfyUI 闭环只开放安全层能力，不真实调用生成队列：

• comfyui.workflow_validate：只读校验 API-format workflow JSON，检查 node id、class_type、inputs、核心 link、输出节点和 prompt 节点，并返回 valid、errors、warnings、node_count、detected_models、missing_or_suspicious_fields。
• comfyui.workflow_build_plan：为 txt2img、img2img、inpaint、upscale 生成 dry-run plan，包含 task_type、input_requirements、workflow_requirements、safety_notes、expected_outputs、blocked_reasons。
• comfy.workflow_draft：为 txt2img、img2img、inpaint、upscale 生成 API-like workflow JSON 草案，并立即用 workflow_validate 校验。
• comfy.workflow_compose：把安全 placeholder 模块组合成 API-like graph，覆盖 checkpoint、prompt encode、latent、load image、VAE encode、KSampler、decode、save、upscale、inpaint mask 等基础模块。
• img2img、inpaint、upscale 当前支持 draft workflow；不会读取本机图片、模型目录或 ComfyUI output，也不会提交 /prompt。
• 校验输出会经过 StarBridge sanitizer，真实路径、用户名和模型路径会脱敏。

公开示例：

ComfyUI workflow draft builder

comfy.workflow_draft 是只读草案生成器，用于把基础参数转成可审查的 ComfyUI API-like workflow JSON。它接受 task_type、prompt、negative_prompt、width、height、seed、steps、cfg、sampler、scheduler、denoise、scale_by 等参数。

返回结构包含：

• valid：草案是否通过本仓库 workflow_validate。
• workflow：API-like workflow JSON 草案。
• validation_report：完整校验报告。
• warnings、safety_notes、next_steps：说明草案边界和后续人工确认步骤。

所有 draft 都带 StarBridgeDraftMetadata 节点，标记 production_ready=false、queue_submission=disabled、model_policy=placeholder_only。模型、源图、mask、upscale model 都使用 placeholder，不使用真实模型路径、真实图片路径或真实输出目录。

ComfyUI workflow graph composer

comfy.workflow_compose 是只读 graph composer，用固定安全模块组合 ComfyUI API-like workflow：

• checkpoint_loader_placeholder
• positive_prompt_encode
• negative_prompt_encode
• empty_latent_image
• load_image_placeholder
• vae_encode_placeholder
• ksampler
• vae_decode
• save_image_placeholder
• upscale_placeholder
• inpaint_mask_placeholder

返回结构包含 valid、workflow、validation_report、warnings、safety_notes、next_steps。所有 composed workflow 都带 StarBridgeDraftMetadata，其中 draft=true、safe_placeholder=true、queue_submission=disabled。Composer 不读取文件系统、不联网、不提交队列，只生成可审查 JSON。

ComfyUI workflow template registry

workflow_template_registry 在 graph composer 之上增加一层公开模板索引，目前注册：

Registry 文件位于 examples/comfy_bridge/templates/workflow_template_registry.json。每个模板只声明 template_id、version、task_type、composer modules、required inputs、placeholder policy、validation status、safety level 和 notes；不引用真实模型、真实图片或真实输出目录。

新增 MCP safe read-only tools：

• comfy.workflow_template_list：列出模板和 lint 状态。
• comfy.workflow_template_get：按 template_id 返回单个模板。
• comfy.workflow_from_template：用模板调用安全 graph composer，返回 placeholder-only workflow。

这三个 tool 不读取用户文件路径、不联网、不提交 ComfyUI queue；输出 workflow 仍带 StarBridgeDraftMetadata、safe_placeholder=true、production_ready=false、queue_submission=disabled。

CAD / AutoCAD

python scripts\test_autocad_mcp.py
python scripts\draw_connection_plate_from_spec.py
python scripts\draw_reference_mechanical_part.py

Photoshop

先手动打开已授权的 Photoshop，再按需要运行：

powershell -ExecutionPolicy Bypass -File examples\photoshop_bridge\scripts\diagnose_local.ps1
powershell -ExecutionPolicy Bypass -File examples\photoshop_bridge\scripts\document_info.ps1
powershell -ExecutionPolicy Bypass -File examples\photoshop_bridge\scripts\run_local_practice.ps1
python examples\photoshop_bridge\write_practice_report.py

单独运行 COM 探针：

powershell -ExecutionPolicy Bypass -File examples\photoshop_bridge\scripts\com_probe.ps1 -OutputPath "$env:TEMP\codex_photoshop_probe.png"

单独运行主体抠图：

powershell -ExecutionPolicy Bypass -File examples\photoshop_bridge\scripts\extract_subject_to_png.ps1 -InputPath "<source-image>" -OutputPath "$env:TEMP\subject.png"

测试

npm.cmd test
npm.cmd run preflight

或直接运行：

python -m unittest discover -s tests
python scripts\starbridge_preflight.py --markdown

不发布内容

以下内容只留本机，不进入 GitHub：

• 账号、密码、验证码、Cookie、token、OAuth 缓存、浏览器资料和支付信息。
• ComfyUI 模型、LoRA、VAE、ControlNet、生成图片和输出目录。
• Blender 私有 .blend、贴图、资产库、渲染缓存和本机插件缓存。
• CAD 客户图纸、商业 DWG、授权文件和真实项目输出。
• Photoshop 安装路径、Creative Cloud 缓存、PSD、商业字体、笔刷、购买素材、源图和导出结果。
• Illustrator 安装路径、Creative Cloud 缓存、AI 私有工程、商业字体、商业画笔、购买素材、源图和导出结果。
• 剪映/CapCut 草稿、缓存、导出视频、账号信息、会员状态、客户素材和字幕原稿。
• output/、scratch/、临时文件、日志、报告产物和本机缓存。

下一步

完整路线图见 ROADMAP.md。

协作原则

1. 公开仓库只放可复用、可审查、可安全分享的内容。
2. 本机软件、账号授权、商业素材和客户资产由用户手动管理。
3. 示例脚本要能单独运行，失败时给出清楚的中文提示。
4. 新增能力先补文档和状态检查，再扩展自动化脚本。