flutter-mcp-toolkit-repo-maintainer

flutter-mcp-toolkit 仓库维护者

此仓库（而非面向终端用户的 Flutter 应用）的推荐流程。优先在 main 上使用 release-please；只有 Release PR 流程受阻时，才使用手动步骤。

适用场景

• 发布版本，或在 CHANGELOG.md 中推进 ## [Unreleased]
• 添加或编辑贡献者文档、AI Agent 安装文档或插件技能
• 合并前验证版本同步情况或技能资源是否存在差异
• 排查 release-please、release.yml 二进制文件或 install.sh 版本固定问题

版本关联项（必须与根目录的 VERSION 一致）

File	Field
VERSION	repo pin
plugin/EXPECTED_SERVER_VERSION	installer pin
packages/core/lib/src/runtime_version.dart	kFlutterMcpVersion (x-release-please-version)
packages/server_capability_core/lib/src/fmt_capability.dart	version getter
mcp_server_dart/pubspec.yaml	version:
mcp_toolkit/pubspec.yaml	version:
packages/core/pubspec.yaml	version:
packages/server_capability_kernel/pubspec.yaml	version: + same-train dependency constraints
packages/server_capability_core/pubspec.yaml	version: + same-train dependency constraints
plugin/.cursor-plugin/plugin.json	version
plugin/.codex-plugin/plugin.json	version
plugin/.claude-plugin/plugin.json	version
.claude-plugin/marketplace.json	plugins[0].version
.release-please-manifest.json	"." key
mcp_server_dart/lib/src/skill_assets.g.dart	generated — embeds plugin/.cursor-plugin/plugin.json, plugin/.codex-plugin/plugin.json, plugin/mcp.json, and all plugin/skills/*/SKILL.md

每次提升版本后：依次运行 make sync-version、make sync-skills，然后运行 make check-contracts（包括 check_version_sync.sh 和 check_skill_assets_drift.sh）。tool/release/sync_version.sh 会从根目录的 VERSION 推导所有版本触点。

Video（独立仓库）：flutter_mcp_video——不在此插件目录树中维护。外部的 flutter_harness 仓库已退役（ADR-0017）；其场景层从未迁移。

更新日志工作流

1. 在 CHANGELOG.md 的 ## [Unreleased] 下添加面向用户的说明（Keep a Changelog 分区：Added、Changed、Fixed、Documentation）。
2. 在 main 上使用约定式提交标题（feat:、fix:、docs:），以便 release-please 汇总变更。
3. 不要编辑 .cursor/plans/ 中的计划文件。

Markdown lint（MD052）

Keep a Changelog 要求使用 ## [3.0.1] 这样的版本标题。Lint 工具会将 [3.0.1] 视为未定义的引用链接（MD052：“No link definition found”）。

• 不要删除 CHANGELOG.md 文件顶部的 ``（release-please 在前置新分区时必须保留它）。
• 在项目符号文本中，代码标识符使用反引号：`AgentCallEntry`，不要使用 [AgentCallEntry]。
• 合并前运行：bash tool/contracts/check_changelog_markdown.sh（也包含在 make check-contracts 中）。

自动发布（推荐）

flowchart LR
  main[merge_to_main] --> rp[release-please.yml]
  rp --> pr[Release_PR]
  pr --> sync[release_pr_sync_versions.yml]
  pr --> assets[release_pr_sync_skills.yml]
  pr --> tag[vX_Y_Z_tag]
  tag --> rel[release.yml_binaries]
  tag --> pub[pub_publish.yml_pubdev]

1. 使用约定式提交将 PR 合并到 main。
2. 等待 release-please.yml 创建 Release PR。
3. 版本同步：release_pr_sync_versions.yml 会在 Release PR 上运行 tool/release/sync_version.sh，并提交与根目录 VERSION 不一致的变更。
4. **技能资源：**检测到差异时，release_pr_sync_skills.yml 会在 Release PR 上自动提交 skill_assets.g.dart；PR 创建时会发布检查清单评论。如果 skill-assets-drift 仍然失败，请在本地运行 make sync-skills 并推送。
5. 在该 PR 中检查 VERSION、CHANGELOG、pubspecs 和插件固定版本，然后合并。
6. release-please 会创建 vX.Y.Z 和 GitHub 发布说明。
7. release.yml 会验证标签是否等于 VERSION，然后附加 flutter_mcp_* 压缩包（不会覆盖发布正文）。
8. pub_publish.yml 会通过 OIDC 按依赖顺序发布 pub.dev 软件包：flutter_mcp_toolkit_core → flutter_mcp_toolkit_capability_kernel → flutter_mcp_toolkit_capability_core → mcp_toolkit。

在启用自动发布到 pub.dev 之前，每个软件包都必须先手动发布一次，并且 pub.dev 管理员必须为此仓库启用 GitHub Actions 发布，标签模式设为 v{{version}}。使用设有必需审核者的 GitHub 环境 pub.dev。

配置：release-please-config.json。

手动发布（备用方案）

在 release-please 不可用或必须从分支发布时使用：

1. 将 ## [Unreleased] 下的条目移至 ## [X.Y.Z]（添加日期），并保留空的 ## [Unreleased]。
2. 将 VERSION 更新为 X.Y.Z。
3. 运行 make sync-version，以生成所有版本相关位置和 .release-please-manifest.json。
4. 运行 make sync-skills（每当插件清单或技能发生变更时都必须运行）。
5. 运行 make check-contracts
6. 提交：chore: release X.Y.Z
7. 可选的 pub.dev 发布前检查：make publish-pub-dry-run。
8. 打标签：git tag vX.Y.Z 并推送标签（触发二进制文件和 pub.dev 工作流）。

在本地构建制品：make release-artifacts 或 bash tool/release/build_release_artifacts.sh --version X.Y.Z。 仅在备用情况下于本地发布 pub.dev 软件包：make publish-pub。

文档索引（单一事实来源）

主题	规范文档
终端用户 Agent 安装	docs/ai_agents/overview.mdx
npx skills + 锁定文件	概览 § 通过 npx skills 安装；.skills.json.example
贡献者 / 发布	docs/contributing/contribution_guide.mdx
插件布局	plugin/README.md
市场文案单一事实来源	docs/ai_agents/marketplace_copy.yaml
分发 / 商店	docs/ai_agents/marketplace_distribution.mdx
商店提交操作手册	docs/contributing/marketplace_submission_runbook.mdx
技能正文	plugin/skills/<id>/SKILL.md → make sync-skills

避免在 README 中重复安装表格——请链接到概览。

技能维护

• 规范技能：plugin/skills/（仓库根目录下的 skills/ → 供 npx skills 使用的符号链接）。
• 添加新的捆绑技能：创建 plugin/skills/<id>/SKILL.md，将 id 添加到 build_skill_assets.dart 中的 expectedSkillIds，然后运行 make sync-skills。
• 本地 Cursor 副本：.cursor/skills/<id>/ 可链接到 plugin/skills/<id>/。
• 平台自用技能：flutter-mcp-toolkit-maintain-web、flutter-mcp-toolkit-maintain-macos、flutter-mcp-toolkit-dogfood-iterations。

HyperFrames 宣传内容（flutter_mcp_video 仓库）

视频技能和项目位于 flutter_mcp_video（skills/hyperframes-video/、projects/video-projects/<id>/）。它们不会通过工具包的 make sync-skills 捆绑。

在该仓库发布宣传内容时：编辑视频仓库；合并前在该仓库运行 bash tool/check_doc_paths.sh。工具包仓库仅在 plugin/assets/ 下托管共享品牌资源（v7-weaver 的符号链接目标）。

IntentCall 消费方维护者门禁

更改 mcp_flutter 中的 IntentCall 消费方集成时：

1. 如果 expectedSkillIds 中尚未包含 flutter-mcp-toolkit-intentcall-migration，请将其追加到 build_skill_assets.dart 中。
2. 运行 make sync-skills——有技能内容修改时，请提交 skill_assets.g.dart。
3. 运行 bash tool/contracts/check_intentcall_skills_grep.sh——迁移技能之外不得存在旧版调用入口符号。
4. 运行 cd mcp_server_dart && dart test test/contract/
5. 运行 flutter-mcp-toolkit migrate agent-entries --check showcase/flutter_test_app/lib（预期退出码为 0）
6. 将规范的 IntentCall 设计链接指向 IntentCall 仓库；本仓库应专注于托管依赖和回归证明。

合并前检查清单

• make check-contracts
• 如果 plugin/skills/ 或 plugin/*-plugin/plugin.json 有更改，则运行 make sync-skills
• 面向用户的更改已更新到 CHANGELOG [Unreleased]
• 已提交的配置中不包含机密信息