Spark Framework Engine

SPARK框架引擎

通用 MCP 发动机 SPARK代码框架（SCF）. 显示任何 SCF 兼容项目的代理、技能、指令和提示符 以代理模式访问GitHub Copilot上的资源和工具。

引擎读取 .github/ 动态活跃的项目- 不包含域数据，适用于任何项目。

当前版本 ： 3.3.0 (09 maggio 2026).对于迁移笔记 咨询 更改日志.md.

______________________________________________________________________

要求

• Python 3.11或更高级
• VS Code 与 GitHub Copilot 扩展
• Dipendenza运行时间： mcp （包括FastMCP）

______________________________________________________________________

安装和首次启动

完整的安装、首次启动和操作指南 工作空间配置，请参阅：

→ docs/getting-started.md

______________________________________________________________________

如何运作

引擎读取文件夹 .github/ VS Code 中的活动工作区 并按需向AI模型（在代理模式下）提供所有发现的SCF内容。

______________________________________________________________________

可用资源 （19）

agents://list             agents://{name}
skills://list             skills://{name}
instructions://list       instructions://{name}
prompts://list            prompts://{name}
engine-skills://list      engine-skills://{name}       (alias deprecato → skills://)
engine-instructions://list engine-instructions://{name} (alias deprecato → instructions://)
scf://global-instructions
scf://project-profile
scf://model-policy
scf://agents-index
scf://framework-version
scf://workspace-info
scf://runtime-state

计数 19 指的是静态记录的引擎侧资源。 实际运行时间数量较高，因为安装的软件包记录 额外的资源启动通过 _v3_repopulate_registry().

可用的工具 （50）

scf_list_overrides(resource_type=None)
scf_read_resource(uri, source="auto")
scf_get_skill_resource(name)
scf_get_instruction_resource(name)
scf_get_agent_resource(name)
scf_get_prompt_resource(name)
scf_override_resource(uri, content)
scf_drop_override(uri)
scf_list_agents           scf_get_agent(name)
scf_list_skills           scf_get_skill(name)
scf_list_instructions     scf_get_instruction(name)
scf_list_prompts          scf_get_prompt(name)
scf_get_project_profile   scf_get_global_instructions
scf_get_model_policy      scf_get_framework_version (restituisce `engine_version` e le versioni dei pacchetti installati)
scf_get_workspace_info
scf_verify_workspace()
scf_verify_system()
scf_get_runtime_state()
scf_update_runtime_state(patch)
scf_get_update_policy()
scf_set_update_policy(auto_update, default_mode=None, mode_per_package=None, mode_per_file_role=None)
scf_bootstrap_workspace(install_base=False, conflict_mode="abort", update_mode="", migrate_copilot_instructions=False, force=False, dry_run=False)
scf_migrate_workspace(dry_run=True, force=False)
scf_list_available_packages()
scf_get_package_info(package_id)
scf_list_installed_packages()
scf_install_package(package_id)
scf_plan_install(package_id)
scf_check_updates()
scf_update_package(package_id, conflict_mode, update_mode="")
scf_update_packages()
scf_apply_updates(package_id | None)
scf_remove_package(package_id)
scf_get_package_changelog(package_id)
scf_finalize_update(session_id)
scf_resolve_conflict_ai(session_id, conflict_id)
scf_approve_conflict(session_id, conflict_id)
scf_reject_conflict(session_id, conflict_id)
scf_plugin_install(pkg_id)
scf_plugin_remove(pkg_id)
scf_plugin_update(pkg_id)
scf_plugin_list()
scf_list_plugins()
scf_install_plugin(package_id, version="latest", workspace_root="", overwrite=False)

Nota sui工具遗产

I工具 scf_list_plugins() e scf_install_plugin() 声音 弃用 赞成 的 scf_plugin_list() e scf_plugin_install() （在v3.0中引入） 它们仍然可用于向后兼容，但在有效负载中进行报告 deprecated: true e removal_target_version: "3.4.0" （由于轻微释放dopo 3.2.0）。营地 migrate_to return block指定工具 明确替代。客户应该转向新的工具。 下一个版本。

架构 — 内部软件包与 Workspace 插件

发动机显示两个 大学 不同的组件：

• Universo A（仅限MCP）： 包裹 spark-base, spark-ops,

scf-master-codecrafter e scf-pycode-crafter 仅通过存储引擎的MCP提供服务 集中。不会在用户工作区中生成文件。通过访问 资源URI agents://, skills://, instructions://, prompts://. spark-base copre引导/入职/工作流程工具； spark-ops 共同 E2E编排，框架文档和发布协调。

• Universo B（插件工作区）：i插件esterni（类别“插件”）e i

包含 delivery_mode: "file" 可以安装物理文件到 用户 workspace scf_plugin_install() 哦 scf_install_package(). 文件编辑直接在VS Code文件系统中进行。

有关操作流程的详细信息和与 MCP 相关的工具列表 每个宇宙，咨询代理 spark-assistant： 部分 “架构 — 内部软件包与工作空间插件”是规范来源 对于这个话题。

从 Workspace Pre-Ownership 迁移

如果工作区是使用早期版本的所有权感知系统初始化，则引擎将进入受控迁移模式。

• 缺失 .github/user-prefs.json第一个 scf_update_package(...) 哦 scf_bootstrap_workspace(...) 返回 action_required: configure_update_policy 并提供策略的初始配置。
• 来自没有元数据的旧软件包的文件 scf_* 以向后兼容的方式处理，如 scf_merge_strategy: replace.
• 硒 .github/copilot-instructions.md 不存在完整的SCF标记，发动机不会自动注入标记：返回 action_required: migrate_copilot_instructions 等待明确确认。
• 文件迁移始终需要有效的写入权限 .github/.
• 标记之外的用户文本 SCF:BEGIN/END 在显式迁移期间保存。

快速常见问题解答：

• 我的自定义文件会发生什么？

用户已经修改的文件将保留在流中 integrative e conservative.In replace 首先创建一个备份 .github/runtime/backups/.

• 发动机自行修改 copilot-instructions.md 遗产？

不。只有当呼叫者在工具流中明确确认时，文件才会被迁移。

scf_get_update_policy() 返回工作空间的策略更新，使用 source (file, default_missing, default_corrupt）有效配置。

scf_set_update_policy(auto_update, default_mode=None, mode_per_package=None, mode_per_file_role=None) 更新 .github/user-prefs.json 不触摸软件包文件和 准备扩展的安装、更新和引导行为。

scf_bootstrap_workspace(install_base=False, conflict_mode="abort", update_mode="", migrate_copilot_instructions=False, force=False, dry_run=False) 将 bootstrap 基本集复制到用户工作区： i 13提示 scf-*.prompt.md，代理人 spark-assistant.agent.md e spark-guide.agent.md，e l’指令 spark-assistant-guide.instructions.md. 如果工作区已经是 bootstrap-duct，但缺少一些基本资产，工具将复制 只有缺少的文件。

Bootstrap 不会复制组装文件 .github/copilot-instructions.md 从发动机。 该文件只能通过安装或更新软件包进入工作区 SCF贡献的部分 merge_sections内部块； spark-framework-engine 它被限制在引擎的存储库中。

骗局 scf_bootstrap_workspace(install_base=True, conflict_mode=..., update_mode=...) 发动机可以 也安装 spark-base 使用正常的 registry 和 manifest preflight。 硒 spark-base 并且已经安装，该步骤在没有重新安装的情况下跳过。 当......的时候 install_base=True，il conflict_mode 被转发到 scf_install_package 因此，bootstrap可以选择是否保存，替换或合并现有文件。 如果工作区已经有明确的策略，或者调用者通过 update_mode，il引导 扩展也构建 diff_summary 的 spark-base， 检查 github_write_authorized 在 .github/runtime/orchestrator-state.json 可以先申请许可或 政策的初始配置。

硒 install_base=True创建或更新 .github/copilot-instructions.md 在软件包安装流程中，通过合并由软件包分发的部分进行， 不是通过复制引擎组装文件。

Nota有效载荷： 返回字典在所有运行分支之间并不统一。 每个分支的保证字段是： success, status, files_written, preserved e workspace. 扩展字段（action_required, authorization_required, github_write_authorized, diff_summary, phase6_assets, base_install, policy_created（只有存在） 在相关分支（权限流，扩展引导，基本安装）。

scf_get_package_info(package_id) 它还展示了该领域 package-manifest.json 模式 2.0包括 min_engine_version, dependencies, conflicts, file_ownership_policy e changelog_path连同一个部分的 计算在活动工作空间上的兼容性。

scf_install_package(package_id, conflict_mode="abort", update_mode="") 执行 preflight 在写文件之前：检查引擎兼容性，声明的依赖关系， 包冲突，运行时清单中已经绘制的路径的所有权和 与文件冲突 .github/ 存在但没有追踪。该 conflict_mode 检查冲突时的行为：

• abort （default）：阻止未解决的冲突。
• replace显式覆盖冲突文件。
• manual打开一个交互式会话以单独解决每个冲突。
• auto引擎尝试确定性最佳努力分辨率并降低到 manual 如果案件不确定。
• assisted打开带有磁盘标记的会话，并允许单个冲突的批准/拒绝。

参数 update_mode 而是在新系统中管理包级策略 所有权意识：

• integrative尝试将兼容的文件与合并或共享分区进行整合。
• replace强制替换路径并自动备份受影响的文件。
• conservative保留本地修改过的文件。
• selective指示工作区在继续之前需要明确选择。
• 空字符串： 使用工作空间策略 （mode_per_package → mode_per_file_role → default_mode).

如果发生写入错误，该工具将尝试回滚刚触摸的文件 不要部分更新 manifest。

当策略流处于活动状态时，有效负载还包括：

• resolved_update_mode e update_mode_source
• diff_summary 没有文件 unchanged
• authorization_required / github_write_authorized
• backup_path 对于路线 replace

每i包清单架构 3.1安装明确区分 在payload v3中有三个类别：

• mcp_services_activated包激活的 MCP URI （agents://,

skills://, instructions://, prompts://)

• workspace_files_written：文件编辑器绑定dichiarati workspace_files
• plugin_files_installed声明的物理文件 plugin_files安装

在工作空间中使用相同的保存门 workspace_files

钥匙 installed 保留为写入的物理文件的过时别名 与现有客户端兼容。

scf_plan_install(package_id) 返回结果的只读预览 安装： 可写文件， 要保存的文件， 冲突需要 一个明确的决定，对于合并模式，合并计划的预览。

scf_check_updates() 只返回已安装的包 与注册表相比可更新，具有安装版本和可用版本。

scf_update_package(package_id, conflict_mode, update_mode="") 更新单个软件包 安装，保存用户修改的文件。支持相同的 conflict_mode 的 scf_install_package: abort, replace, manual, auto, assisted并使用相同的 update_mode 安装流程的 package-level。

scf_update_packages() 它不再局限于报告版本三角洲：它构建 更新计划的有序预览，包括包之间的依赖关系， 操作块和预期的应用顺序。

scf_apply_updates(package_id | None, conflict_mode="abort") 使用相同的 dependency-aware 计划 按拓扑顺序更新包。在写作之前，执行预飞 在批中的所有目标上，如果检测到未解决的冲突，则停止，返回 锁定的包的详细信息。该 conflict_mode 然后转发给每个 batch 安装，所以更新可以使用 replace 要覆盖 哦 manual / auto / assisted 合并已修改的用户文件。

scf_finalize_update(session_id) 结束一个打开的合并会话 manual 哦 assisted将确认的决策应用于工作区文件，并且 更新manifest。

scf_resolve_conflict_ai(session_id, conflict_id) 自动提出一个 保守的解决单个公开的冲突，验证它之前 让它可接受。

scf_approve_conflict(session_id, conflict_id) 通过提议的决议 对于会话中的冲突，将其标记为已解决。

scf_reject_conflict(session_id, conflict_id) 拒绝提议的决议， 将文件留在带有冲突标记的手动备份中。

Gestione更新工作区

新的所有权和更新策略系统使用以下运行时文件：

• .github/user-prefs.json --策略更新del工作区
• .github/runtime/orchestrator-state.json — 对受保护脚本的会话授权
• {engine_root}/runtime/{hash[:12]}/ — 用于快照、合并会话和备份的 engine-local 目录（路径由 resolve_runtime_dir 在 spark/boot/validation.py可被环境变量覆盖 SPARK_RUNTIME_DIR)

6步流程

1. 读取策略工作区，默认值安全备份。
2. 建设 diff_summary 目标文件，不包括 unchanged.
3. 授权验证 .github 通过 github_write_authorized.
4. 决议 update_mode 实际选择或明确选择。
5. 路径前自动备份 replace.
6. 用 file-level 写入 replace三向合并或 _scf_section_merge() 共享的文件。

更新模式

对于新的或迁移的工作区， scf_bootstrap_workspace(..., update_mode=...) 您可以创建初始策略， 而 scf_set_update_policy(...) 允许您稍后更新，而无需重新安装软件包。

______________________________________________________________________

3路合并系统

从版本开始 2.0.0引擎支持每个文件3路合并 在安装和更新软件包时进行 markdown。

合并结合了三个版本： 基础 （安装时保存的快照） 上一篇） 。 用户版本 （本地修改）和 新版本 包裹 （注册表内容更新）。

可用模式

手动/辅助会话流程

scf_install_package / scf_update_package (conflict_mode="manual")
  → sessione aperta → session_id restituito

scf_approve_conflict(session_id, conflict_id)   ← accetta ogni conflitto
scf_reject_conflict(session_id, conflict_id)    ← rifiuta e mantieni versione utente
scf_resolve_conflict_ai(session_id, conflict_id) ← delega all'AI integrata

scf_finalize_update(session_id)  ← applica le decisioni e chiude la sessione

每次合并 auto发动机只会自动关闭 保守启发式和验证器；模糊的情况降级为一个 活跃的手动会话。

Lo脚本独立版 spark-init.py 美国 package-manifest.json 的 spark-base 作为第一次初始化的用户面向真理来源。资源 可选操作由 spark-ops如果找到已经存在的文件，但 不跟踪，询问用户是否愿意 replace, preserve 或者整合 尽最大努力 integrate 在触摸工作空间之前。

______________________________________________________________________

SCF 架构

该引擎是SPARK代码框架生态系统的第一级。 有关该项目的完整文档，请参阅 SCF-项目设计.md （原始设计文件，存档）。

Livello 1 — spark-framework-engine   ← questo repo (motore universale)
Livello 2 — scf-pack-*               (pacchetti dominio, repo separati)
Livello 3 — scf-registry             (indice centralizzato dei pacchetti)

文件所有权 .github/ 发动机

我档案 .github/ 此仓库的所有权模式与引擎应用于用户工作区的所有权模式相同：

• 文件自然引擎特定引擎的代理，技能，指令和提示有 scf_owner: "spark-framework-engine".
• 软件包阴影文件：我提示 scf-*.prompt.md 和 代理 spark-guide.agent.md 属于 spark-base 并且重新调整到源软件包的内容 scf_owner: "spark-base".
• 共享文件: .github/copilot-instructions.md 是一个文件 merge_sections 有部分 SCF:BEGIN/END 适用于所有已安装的软件包，并作为标准格式的参考实现。

______________________________________________________________________

贡献者

重命名 SCF 代理、添加/删除 MCP 工具和管理程序 共享的 pytest 固件记录在：

→ 贡献.md

______________________________________________________________________

相关项目

• SCF-项目设计.md 原始设计文件（存档）
• scf-registry — 正在开发中
• scf-pack-gamedev — 正在开发中