企业官网建设流程全解析

第7节 原语可移植性：同一个循环跑遍Claude Code/Codex/TRAE

一句话总结：“一旦发现形状相同，就别再争论用哪个工具”——五大原语在三大工具的映射总表；TRAE等国产工具的原语对照；设计可移植循环的抽象原则。

本文导航

• 一、问题：工具锁定
• 二、五大原语映射总表
• 三、逐项详细对照
• 四、为什么形状相同：抽象层在起作用
• 五、设计可移植循环的原则
• 六、工程实现：一份配置生成三端
• 七、踩坑实录
• 小结
• 下节预告

第5章前六节把五大原语挨个拆完：Automations（心跳）、Worktrees（隔离）、Skills（能力）、Connectors（工具）、Sub-agents（编排），外加Hooks（守护）。这一节收网，回答一个越来越现实的问题：这些原语是你的，还是某个工具的？

答案决定了你被锁定的深度。

一、问题：工具锁定

场景

你用Claude Code开发了完整的循环系统： - Automations定时任务 - Worktrees并行隔离 - Skills技能包 - MCP工具集成 - Sub-agents编排 现在老板说： "我们改用Codex了" 或 "国内要用TRAE" 结果： 所有配置都要重写 所有Skills都要迁移 成本巨大

我的一次全员迁移

这个场景我亲身经历过。2025年中，我们组从Claude Code切到Codex做试点（原因不是工具本身，是公司的API配额调整）。当时我手上有一套跑了三个月的循环资产：7个定时任务、4个Skill、2个子智能体定义、1个MCP接入。切工具的周会上我拍胸脯说"两周迁完"，实际花了三天——因为我早就把配置的"源"和"产物"分开了（下一节细讲）。

同组的另一位同事没这么幸运：他的prompt、调度规则、技能全写在Claude Code的会话历史和本地配置里，迁移等于把三个月的积累推倒重来。最后他花了三周，还有两个定时任务的逻辑再也对不上原样。

同一批人、同一次迁移，两倍以上的成本差距，差别只在一件事：循环资产有没有以可移植的形式存在。

这场迁移还教育了我另一件事：可移植性不只是"少疼一次"，它还是谈判筹码。第二年上半年公司评估要不要切回来，因为迁移成本已经被压到三天，决策完全聚焦在工具本身的优劣上——工具好不好用成了唯一变量。如果迁移要三周，决策就会掺进"沉没成本"：明明有更好的选项，但"迁起来太贵"会把整个团队焊死在次优解上。锁定最贵的代价，是你失去了选择权本身。

核心洞察

五大原语（Automations/Worktrees/Skills/Connectors/Sub-agents） 在不同工具中"形状相同" 只是配置格式不同 只是命名约定不同 核心概念是一样的

二、五大原语映射总表

先上全表，这是本节的干货核心：

注意Connectors那一行：三大工具完全一致，没有差异。这不是巧合——因为MCP是协议层标准（第4节讲过），不是工具层功能。这一行给了一个重要启示：协议层的可移植性 > 功能层的可移植性 > 配置层的可移植性。MCP排在最稳的一层，所以第4节说"MCP优先"是可移植性设计的第一原则。

三、逐项详细对照

1. Automations（定时任务）

Claude Code

// .claude/scheduled_tasks.json{"tasks":[{"name":"daily_triage","schedule":"0 9 * * *","prompt":"检查新Issue并分诊"}]}

Codex

# codex.yamlautomations:-name:daily_triageschedule:"0 9 * * *"prompt:"检查新Issue并分诊"

TRAE

// .trae/automations.json{"tasks":[{"name":"daily_triage","cron":"0 9 * * *","instruction":"检查新Issue并分诊"}]}

共同点：cron表达式 + 提示词/指令
差异：配置格式（JSON/YAML）+ 字段名（schedule/cron）

2. Worktrees（并行隔离）

Claude Code

claude--worktree"修复bug"

Codex

# .codex/agents/worker.toml [agent] isolation = "worktree"

TRAE

// .trae/config.json{"isolation":"worktree"}

共同点：都支持worktree隔离
差异：命令行参数 vs 配置文件

3. Skills（技能包）

Claude Code

<!-- .claude/skills/code-review/SKILL.md --> --- name: code-review description: 审查代码 --- # 代码审查技能 ...

Codex

<!-- .codex/skills/code-review/SKILL.md --> --- name: code-review description: 审查代码 --- # 代码审查技能 ...

TRAE

<!-- .trae/skills/code-review/skill.md --> --- name: code-review description: 审查代码 --- # 代码审查技能 ...

共同点：SKILL.md格式几乎相同
差异：目录位置（.claude/.codex/.trae）

Skills是五个原语里迁移成本最低的——正文完全不用改，换个目录就行。这也说明第3节讲的SKILL.md三段结构（frontmatter+正文+脚本资产）事实上已经是跨工具的事实标准。

4. Connectors（MCP）

三者都支持MCP协议 配置格式相同

通用配置

// .mcp.json (通用){"servers":{"github":{"command":"mcp-server-github","args":["--token","$GITHUB_TOKEN"]}}}

共同点：完全相同
差异：无

5. Sub-agents（子智能体）

Claude Code

<!-- .claude/agents/maker.md --> --- name: maker description: 写代码 --- # Maker Agent ...

Codex

# .codex/agents/maker.toml [agent] name = "maker" description = "写代码"

TRAE

// .trae/agents/maker.json{"name":"maker","description":"写代码","prompt":"..."}

共同点：name + description + prompt
差异：格式（Markdown/TOML/JSON）

把差异汇总成一张"迁移成本表"：

看出来了吧：贵的从来不是原语本身，是"把配置当源码"的习惯。

怎么自己验证"形状相同"

表是我总结的，你不用信我——新工具到手时，花二十分钟做三件事，自己验证一遍：

第一，找心跳。搜索文档里有没有定时/计划任务能力，看它的调度表达式是不是cron五段式。是，Automations原语存在。

第二，找隔离。看并行任务或多会话怎么处理文件冲突，搜"worktree"或者"隔离"。有worktree或等价物，Worktrees原语存在。

第三，找技能文件。看有没有"往某个目录扔一个markdown文件就能注入能力"的机制，文件里是不是frontmatter+正文的结构。是，Skills原语存在。

Connectors和Sub-agents的验证更直接：MCP搜配置格式（有没有.mcp.json），Sub-agents搜有没有多智能体/子智能体的定义目录。五项里有四项对得上，这个工具就可以放心把你的循环迁过去；对不上的是少数派原语，单独写适配层就行。这套验证动作本身也可移植——它不依赖任何一家文档的写法。

四、为什么形状相同：抽象层在起作用

为什么三大工具的原语长一个样？两个原因。

第一，问题空间是同一个。并行循环一定要隔离（不然互相覆盖），可复用知识一定要文件化（不然每次从零开始），工具接入一定要标准化（不然N×M爆炸），质量把关一定要分离角色（不然自评偏差）。这些是循环工程的结构性问题，不管哪家工具来做，解都收敛到同一组原语。问题决定形状。

第二，行业在快速对齐。MCP成了协议标准，SKILL.md格式被普遍采纳，cron是几十年的老标准。后来的工具（包括各家国产工具）没有理由另起炉灶——兼容生态的收益远大于差异化的收益。你看TRAE的定时任务字段名虽然叫cron，值还是那个五段式表达式。

所以那句"一旦发现形状相同，就别再争论用哪个工具"的真实含义是：原语层没有护城河，争论工具优劣是在比较保温杯的颜色，比的不是保温能力。真正该较劲的是：循环的目标设计、验证器质量、技能积累——这些才是你的资产，而且它们天生可移植。

反面对照：不可移植的循环长什么样

为了加深体感，我画两个对照的结构。一个可移植的循环，资产分层清晰：

可移植循环： 目标定义（GoalSpec，纯YAML/JSON） 验证器（标准Python + pytest） Skills（标准SKILL.md） 工具接入（MCP标准） 三端配置（脚本生成，随时可再生）

一个被锁死的循环，所有东西糊在一起：

锁定循环： 目标写在某工具的会话历史里 验证逻辑调用了宿主专有接口 提示词嵌在工具的专属命令格式里 工具接入用了厂商私有API 配置手写、从未版本化

第二种不是夸张，是我同事的真实状况，也是大多数人的默认状态——锁定不是选择的结果，是不设计的结果。你不需要"决定要不要可移植"，只需要在每次新增资产时问一句：“这东西换个工具还活着吗？”

五、设计可移植循环的原则

原则1：抽象优先

❌ 错误：直接写工具特定配置 ✅ 正确：先写抽象定义，再转换为各工具配置

原则2：统一配置源

loop_config.yaml（统一源） ↓ 转换脚本 .claude/...（Claude Code配置） .codex/...（Codex配置） .trae/...（TRAE配置）

原则3：MCP优先

MCP是通用标准 能用MCP解决的，不用工具特定API

三条原则展开讲讲第二条，因为它是操作性最强的。统一配置源的本质是"单一事实来源"（Single Source of Truth）：循环资产只维护一份（loop_config.yaml），三端配置全部由脚本生成，且生成物进.gitignore——手改生成物等于制造分叉，下次生成就被冲掉。我那次三天完成的迁移，实际动作只有：跑一遍转换脚本，提交，收工。

验证逻辑也要可移植。除了配置，循环里还有一部分是代码（验证器、Hook、工具脚本）。我的做法：验证器全部用标准Python（pytest/ruff/subprocess），不调用任何宿主的专有API；宿主相关的胶水（怎么把pytest结果喂回模型）薄到几十行，换工具时重写这层就行。厚的部分写标准，薄的部分写适配——跟后端系统的端口适配器模式一个道理。

可移植性检查清单

原则要落到检查上。每次给循环加新资产，过一遍这份清单（我在团队里把它做成PR模板的一部分）：

## 可移植性检查清单 ### 配置层 - [ ] 新配置写在loop_config.yaml，而不是直接改某端目录？ - [ ] 生成物在.gitignore里，没有手改痕迹？ - [ ] cron表达式和时区显式声明？ ### 代码层 - [ ] 验证器只用标准Python/pytest，无宿主API？ - [ ] Hook脚本独立可运行、可测试？ - [ ] 与宿主的胶水代码是否足够薄（<100行）？ ### 资产层 - [ ] Skill正文没有宿主专有语法？ - [ ] 工具接入走MCP而非私有API？ - [ ] 提示词资产以纯文本形式进了git？ ### 行为层 - [ ] 迁移后每个定时任务手动触发验证过？ - [ ] 子智能体的工具权限在新端等价配置？

十二个格子，一分钟勾完。它的作用不是形式主义，而是把"我记得要可移植"变成"每次提交都被问一遍"——记忆会松懈，清单不会。

六、工程实现：一份配置生成三端

按本课程统一工程规范（Python 3.12 + uv、pydantic校验、logging控制台+文件双输出按月分割保留12个月），把转换脚本写成生产版：

#!/usr/bin/env python3# uv init loop-porter && uv add pydantic pyyaml"""loop-porter：统一配置 → 三端配置，带校验和日志"""importjsonimportloggingfromlogging.handlersimportTimedRotatingFileHandlerfrompathlibimportPathimportyamlfrompydanticimportBaseModel,Field log=logging.getLogger("porter")log.setLevel(logging.INFO)_fmt=logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")_c=logging.StreamHandler();_c.setFormatter(_fmt);log.addHandler(_c)_f=TimedRotatingFileHandler("logs/porter.log",when="midnight",interval=30,backupCount=12,encoding="utf-8")_f.setFormatter(_fmt);log.addHandler(_f)classAutomation(BaseModel):name:strschedule:str=Field(pattern=r"^[\d*/,-]+\s")# 必须是合法cronprompt:str=Field(min_length=4)timezone:str="Asia/Shanghai"# 第1节的教训：时区必须显式classAgentDef(BaseModel):name:strdescription:strprompt:strclassSkillDef(BaseModel):name:strdescription:str=Field(min_length=6)# 第3节的教训：短描述必然触发不准prompt:strclassLoopConfig(BaseModel):"""统一配置源模型：脏配置在转换前就被拦下"""automations:list[Automation]=Field(default_factory=list)agents:list[AgentDef]=Field(default_factory=list)skills:list[SkillDef]=Field(default_factory=list)defload_config(path:str="loop_config.yaml")->LoopConfig:cfg=LoopConfig.model_validate(yaml.safe_load(Path(path).read_text(encoding="utf-8")))log.info("配置校验通过 定时任务%d个 智能体%d个 技能%d个",len(cfg.automations),len(cfg.agents),len(cfg.skills))returncfgdefgenerate_claude(cfg:LoopConfig):tasks=[{"name":a.name,"schedule":a.schedule,"prompt":a.prompt}foraincfg.automations]Path(".claude").mkdir(exist_ok=True)Path(".claude/scheduled_tasks.json").write_text(json.dumps({"tasks":tasks},ensure_ascii=False,indent=2),encoding="utf-8")foragincfg.agents:Path(f".claude/agents/{ag.name}.md").parent.mkdir(parents=True,exist_ok=True)Path(f".claude/agents/{ag.name}.md").write_text(f"---\nname:{ag.name}\ndescription:{ag.description}\n---\n{ag.prompt}\n",encoding="utf-8")defgenerate_codex(cfg:LoopConfig):Path(".codex/agents").mkdir(parents=True,exist_ok=True)foragincfg.agents:Path(f".codex/agents/{ag.name}.toml").write_text(f'[agent]\nname = "{ag.name}"\ndescription = "{ag.description}"\n',encoding="utf-8")defgenerate_trae(cfg:LoopConfig):Path(".trae").mkdir(exist_ok=True)tasks=[{"name":a.name,"cron":a.schedule,"instruction":a.prompt}foraincfg.automations]Path(".trae/automations.json").write_text(json.dumps({"tasks":tasks},ensure_ascii=False,indent=2),encoding="utf-8")if__name__=="__main__":cfg=load_config()generate_claude(cfg);generate_codex(cfg);generate_trae(cfg)log.info("三端配置生成完成")

控制台输出：

$ uv run loop_porter.py 2026-07-08 16:40:02 | INFO | 配置校验通过 定时任务2个 智能体2个 技能1个 2026-07-08 16:40:02 | INFO | 三端配置生成完成

注意pydantic在这里干的两件事：Automation.schedule用正则强制校验cron格式（写错定时表达式这种事故在转换阶段就拦下），timezone字段给默认值Asia/Shanghai（把第1节踩过的时区坑固化成结构默认）。可移植性的第一道防线，是配置本身的质量。

真要迁移时的五步SOP

最后送一份实操流程，按这个顺序走，迁移基本不会翻车：

第五步最容易被省，也最不该被省。迁移最大的风险从来不是"配置没生成"，而是"行为悄悄变了"——某个字段的默认值不同、某端的最小调度粒度不同。并行观察期就是给这些差异留暴露窗口。我那位同事三周才迁完的教训，一半就栽在跳过了第2步和第5步。

统一配置示例

# loop_config.yamlautomations:-name:daily_triageschedule:"0 9 * * *"prompt:"检查新Issue并分诊"skills:-name:code-reviewdescription:审查代码质量prompt:|## 代码审查技能 审查代码时检查以下方面...agents:-name:makerdescription:写代码的工人prompt:|你是一个Python开发者...-name:checkerdescription:审查代码的检查者prompt:|你是一个严格的代码审查者...

七、踩坑实录

1. 手改了生成物：同事直接改.claude/下的配置文件，下次跑转换脚本被覆盖，改动丢失。修法：生成物进.gitignore，改动只能改loop_config.yaml再重新生成。
2. 字段名映射漏了一处：schedule→cron的映射只写了automations，漏了某个工具的提醒任务，迁移后那个任务再没跑过。修法：转换脚本跑完自动diff三端任务数，数量对不上就报警。
3. 在Skill正文里用了宿主专有语法：某技能正文里写了Claude Code专属的斜杠命令，迁到Codex后命令静默失效。修法：Skill正文只用通用Markdown和标准命令，宿主专有能力隔离在适配层。
4. 验证器调了宿主API：早期验证器用了Claude Code的会话接口，换工具时验证器跟着重写。修法：验证器只用标准Python+pytest，宿主胶水薄层化。
5. 以为"形状相同"等于"行为相同"：三端的定时任务都有cron，但某端的最小粒度是5分钟，我配的*/2 * * * *被静默取整。修法：迁移后每个任务手动触发一次验证（第1节的老规矩，跨工具也适用）。
6. 配置源本身进了git但没进评审：统一源是唯一事实来源，改它却没走review，一次手滑的cron改动同时影响三端。修法：loop_config.yaml的变更走PR，转换脚本在CI里跑，生成失败直接挡住合并——影响面越大的文件，评审门槛越高。

最后说个心态问题。有人觉得"搞统一配置源是过度设计，我又不换工具"。我以前也这么想，直到发现统一源带来一个意外收益：配置可读了。三端配置格式各异、字段琐碎，直接维护时没人愿意通读；而loop_config.yaml是一份干净的、人话的、单一的清单——新同事接手项目，读这一份文件就理解了整个循环系统的骨架。可移植性解决的是明天的问题，可读性解决的是今天的问题，一份配置同时买到两样，这笔账怎么算都划算。

小结

• 五大原语在三大工具中形状相同：Automations、Worktrees、Skills、Connectors、Sub-agents只是配置格式和字段名不同，核心概念一致；问题空间决定形状，行业对齐加速趋同。
• Connectors零成本迁移：MCP是协议层标准，三端完全一致——协议层>功能层>配置层的可移植性排序，是"MCP优先"原则的根据。
• Skills是第二便宜的资产：正文跨工具通用，换目录即可；SKILL.md事实上已是行业标准。
• 统一配置源是操作核心：loop_config.yaml单一事实来源，三端配置全部脚本生成，生成物不进git；厚的部分（验证器/Hook）写标准Python，薄的部分写适配。
• 可移植性的第一道防线是配置质量：pydantic在转换前校验cron格式、强制时区默认——脏配置连变成生成物的机会都没有。
• 形状相同≠行为相同：迁移后逐任务手动触发验证，别信"应该没问题"。

下节预告

理论部分到此收官：前5章我们讲清了循环的解剖学（第3章）、上下文工程（第4章）、五大原语与生态（第5章）。第6章开始进入实战核心区——《环境搭建与第一个循环》。第6章第1节《开发环境：Python 3.12 + uv + 日志基建》，从uv管理环境开始，把日志双输出、按月分割、保留12个月的基建搭起来——后面每一章的代码都跑在这套地基上。

如果觉得本文对你有帮助，欢迎点赞、收藏、关注三连！
本系列持续更新中，关注不迷路~

文章编号：第5章第7节 | 总进度：37/120 | 预计阅读时间：15分钟

🎉 第5章（循环的五大原语与生态）全部完成！7/7篇，累计37/120篇（30.8%）

课程进度：已完成3/5章的理论部分，即将进入实战核心区（第6-13章）