ArcKit converter.py源码解析：一套命令如何自动生成6种AI平台格式（完整指南）-平芜编程栈

ArcKit converter.py源码解析：一套命令如何自动生成6种AI平台格式（完整指南）

【免费下载链接】arc-kitThe Enterprise Architecture Governance Harness — strategy, architecture, delivery, and assurance using AI coding assistants项目地址: https://gitcode.com/GitHub_Trending/ar/arc-kit

ArcKit是一个用 AI 编码助手驱动的企业架构治理工具包，而它的"多平台分发引擎"就是 converter.py：只写一份命令源文件，运行一次转换脚本，就能自动把 125 个左右的企业架构命令扇出到 Codex、Gemini CLI、OpenCode、GitHub Copilot、Mistral Vibe、Kimi Code CLI 等 6 种 AI 助手平台，全程零手工复制。

为什么需要"单一事实源"转换器？

如果 7 个平台各维护一套命令副本，改一处就得改七处，漂移只是时间问题。ArcKit 的思路是：

唯一可编辑的源：plugins/arckit-claude/commands/下的 Markdown 命令文件（外加各地域插件目录里的命令）
其余全部是生成物：Codex 的SKILL.md、Gemini 的 TOML、Copilot 的 prompt 文件等，都不许手改——改源文件，重跑python scripts/converter.py，全部再生

官方文档 custom-commands.md 里写得很直白："A command is a single Markdown file that ArcKit fans out to six AI-assistant formats automatically."

第一层：把 14 个插件源合并成一份命令清单

v5.0.0 之后，ArcKit 的命令分散在 14 个插件目录里（阿联酋、法国、荷兰、加拿大、欧盟、奥地利、澳大利亚、英国金融、英国 NHS、TOGAF/ADM、OAA、Agent 架构、核心……）。converter 的PLUGIN_SOURCES列表按"社区插件在前、核心插件最后"的顺序声明这些源（见 converter.py 第253-269行），合并时：

逐目录扫描.md命令文件，重名时打印 WARNING 并"先出现者胜"——由于文件名都带地域前缀（uae-*、fr-*…），实践中不会冲突，而核心插件排最后保证了"真撞车时核心赢"
三个插件被刻意排除在转换之外：arckit-fde、arckit-repo（独立工具插件），以及专有许可证的arckit-uk-gcloud——注释里专门说明这是防止许可泄漏，不能混进 MIT 协议的公开扩展（见 converter.py 第270-276行）
合并结果按文件名排序，保证生成物顺序稳定、无 diff 噪音

第二层：翻译引擎——路径重写与占位符替换

每条命令的 prompt 里写的是 Claude 风格的路径和占位符。rewrite_paths()函数（converter.py 第391-426行）按目标平台的配置逐项改写：

源写法	转换后（举例）
`${CLAUDE_PLUGIN_ROOT}`	各平台实际安装位置：Codex/OpenCode 用`.arckit`，Gemini 用`~/.gemini/extensions/arckit`
`$ARGUMENTS`	Gemini →`{{args}}`；Copilot →`${input:topic:...}`；Paperclip →`{topic}`
`${user_config.KEY}`	降级为普通环境变量`${KEY}`（非 Claude 平台不支持插件用户配置）
模板路径	有项目级覆盖的平台改为`.arckit/templates-custom/`，先于插件根展开

Gemini 还有特殊照顾：它的扩展目录在工作区沙箱之外，converter 会把 prompt 里"Read 某文件"的指令正则替换成Run cat ...，并在每条命令开头插入一段"扩展文件访问须知"（EXTENSION_FILE_ACCESS_BLOCK，见 converter.py 第214-226行）——提示模型只能用 shell 命令读模板。

第三层：一个配置字典驱动 6 种输出

converter 最优雅的设计是AGENT_CONFIG字典（converter.py 第281-388行）：每个平台就是一个条目，声明输出目录、文件名模式、格式类型和特殊开关。

目标平台	输出格式	输出位置	特点
Codex CLI	Markdown + Skill	`extensions/arckit-codex/prompts/`与`skills/arckit-<n>/SKILL.md`	一个命令双形态，skill 附带`agents/openai.yaml`
OpenCode CLI	Markdown	`extensions/arckit-opencode/commands/`	同 Codex 的`.arckit`路径前缀
Gemini CLI	TOML	`extensions/arckit-gemini/commands/arckit/<n>.toml`	文件访问须知块 +`{{args}}`参数占位符
GitHub Copilot	Prompt frontmatter	`extensions/arckit-copilot/prompts/arckit-<n>.prompt.md`	按 prompt 内容自动选配工具集（含`fetch`的研究类命令会加上 fetch 工具）
Paperclip	单一 JSON	`extensions/arckit-paperclip/src/data/commands.json`	所有命令、模板内容、handoffs 全部内嵌进一个文件
Mistral Vibe	Skill Markdown	`extensions/arckit-vibe/skills/`	附`display_name`、tags 前缀的 frontmatter
Kimi Code CLI	Skill 目录	`extensions/arckit-kimi/skills/arckit-<n>/SKILL.md`	只输出 name/description 字段，Claude-only 字段天然被丢弃

转换结束后还有一轮"配套资产生成"：Codex 的config.toml（生命周期钩子 + MCP 服务器，自动剔除 Claude-only 的alwaysLoad字段）和每个 agent 的.toml；Gemini 的子 agent 文件、hooks.json和policies/rules.toml（禁止改扩展自身文件、写入密钥前询问）；Copilot 的.agent.md包装器与copilot-instructions.md；Kimi 的插件清单kimi.plugin.json（MCP 映射 + 钩子数组）。

执行顺序也很讲究（见 converter.py 主流程）：先拷贝支撑文件（各插件的templates/、data/合并进同一目录，脚本/指南/配置只从核心插件取），再转换命令，最后做平台后处理——因为命令 skill 要生成在参考 skill 就位之后。

第四层：优雅降级——处理"平台不支持"的特性

不同平台的"能力天花板"不一样，converter 用黑白名单把不兼容的东西干净地剥离掉：

命令级跳过：build.md依赖 Claude Code 独有的并行 Agent 派发，没有对应运行时，直接不转换（CLAUDE_ONLY_COMMANDS，见 converter.py 第51行）
字段级剥离：effort、paths、doc-type等 Claude-only frontmatter 字段，以及 agent 的maxTurns、disallowedTools等，一律剔除后再序列化
subagent 过滤：带subagent: true的读写子代理只存在于 Claude Code，其他目标全部跳过
agent 命令内联：像research这类"命令只是委托给同名 agent"的场景，converter 直接取 agent 的完整 prompt 作为命令正文，并补上## User Request占位段落——因为非 Claude 平台没有 Task/agent 架构
hook 依赖替换：没有上下文注入 hook 的平台，"hook 已帮你扫过项目"的提示会被替换成"自己扫描projects/目录"的说明
standalone 覆盖：commands-standalone/里存着针对无 hook 平台改写的命令版本，converter 会按平台的has_sync_guides_hook开关自动选用

这套机制的效果是：同一份源命令，在 6 个平台上都能"像原生一样"运行，而不是带着一堆无效字段硬塞。

加一个新 AI 平台要做什么？

答案写在源码注释里（converter.py 第279行）："adding a new AI target = adding a dictionary entry"。往AGENT_CONFIG加一个条目（输出目录 + 格式 + 路径前缀 + 参数占位符），主循环的通用逻辑就会替你处理合并、重写、frontmatter 生成、handoffs 渲染；如果格式特殊，再补一个后处理函数即可。Vibe 和 Kimi 就是这么加进来的。

什么时候该运行 converter.py？

官方发布流程（RELEASING.md）要求：新增命令、修改 agent prompt、调整模板之后，重跑一次python scripts/converter.py（需要 Python ≥ 3.11 + PyYAML），把全部目标文件再生一遍，连同源文件一起提交。由于生成过程完全确定性，重跑不会有 diff 噪音；tests/plugin/ 下还有专门的跨平台一致性测试（如test_claude_overlay_namespacing.py、test_kimi_hook_adapter.mjs）守着"源改了、6 份生成物同步改"的约定。