# Iso：跨平台AI代理工具链，一次编写，处处运行 > Razroo开源的Iso是一套完整的AI代理开发工具链，通过14个协同工作的npm包，解决代理工具碎片化、模型能力差异和运行时可靠性三大问题，实现一套指令在Claude Code、Cursor、Codex、OpenCode等多个平台无缝运行。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-04-26T19:45:04.000Z - 最近活动: 2026-04-26T19:52:13.438Z - 热度: 145.9 - 关键词: AI代理, Claude Code, Cursor, Codex, OpenCode, 跨平台, 提示工程, MCP, 代理工作流, Razroo - 页面链接: https://www.zingnex.cn/forum/thread/iso-ai - Canonical: https://www.zingnex.cn/forum/thread/iso-ai - Markdown 来源: ingested_event --- # Iso：跨平台AI代理工具链，一次编写，处处运行\n\nAI编程助手正在改变软件开发的方式，但一个日益严重的问题是：每个平台都有自己的配置格式和指令系统。Claude Code用`CLAUDE.md`，Cursor用`.cursor/rules/*.mdc`，Codex用`.codex/config.toml`，OpenCode有自己的`opencode.json`和`.opencode/agents/*.md`。如果你想在多个工具之间切换，或者让团队使用不同的AI助手，就必须维护多份几乎相同但格式各异的配置文件。\n\nRazroo开源的Iso项目正是为了解决这个"代理工具碎片化"问题。它提供了一套完整的工具链，让你只需编写一次代理指令，就能自动适配到所有主流AI编程平台。\n\n## 三大碎片化问题\n\nIso的文档开宗明义地指出了当前AI代理工作流的三个核心痛点：\n\n### 1. 工具碎片化（Harness Fragmentation）\n\n每个AI编码助手读取不同的文件布局：\n- Claude Code → `CLAUDE.md`\n- AGENTS.md → 某些工具使用\n- Cursor → `.cursor/rules/*.mdc`\n- OpenCode → `.opencode/agents/*.md`\n- MCP配置 → `.mcp.json` vs `opencode.json` vs `.codex/config.toml`\n\n保持这些文件同步意味着无尽的复制粘贴，而复制粘贴必然导致漂移（drift）——时间久了，不同平台的配置就会不一致。\n\n### 2. 模型碎片化（Model Fragmentation）\n\n为前沿大模型（如GPT-4、Claude 3.5 Sonnet）编写的提示词，在小型模型（如7B本地模型）上可能会失效。软性指令（"should"、"when relevant"）、品味词汇、模糊的交叉引用、非结构化的推理——这些在前沿模型上能很好理解的表达，在小型模型上可能完全失效。\n\n更糟的是，这种失效是静默的——你不会立即发现问题，直到代理在生产环境中行为异常。\n\n### 3. 运行时碎片化（Runtime Fragmentation）\n\n当前的工作流依赖脆弱的提示词散文来控制：\n- 扇出限制（fan-out limits）\n- 上下文加载\n- 产物复用\n- 角色权限\n- 输出格式\n- 重复检查\n- "已经发生了什么"的状态跟踪\n\n这些不变量应该放在确定性的本地包中，而不是在每次请求中重复token化的指令里。\n\n## Iso的解决方案：14个协同工作的包\n\nIso通过14个npm包组成一个完整的流水线，从编写、构建到运行时控制，再到反馈闭环，提供端到端的解决方案：\n\n### 构建时工具（4个包）\n\n**@razroo/agentmd**：结构化的代理提示词方言。规则使用作用域标签（`[H1]`硬限制、`[D1]`默认），并附带`why:`原理说明。提供结构检查（缺失原理、悬空引用、无回退行）和基于fixture的测试工具。\n\n**@razroo/isolint**：检查编译后的提示词散文中弱小型模型无法解析的短语——如"should"、"when relevant"、"one of the usual categories"、品味词汇、长句、未闭合的"etc."列表。`--fix --llm`可以重写违规内容并重新检查。\n\n**@razroo/iso-harness**：一个`iso/`源目录 → 每个编码代理实际读取的文件布局。将指令、子代理、斜杠命令和MCP服务器转译为`CLAUDE.md`、`AGENTS.md`、`.cursor/rules/*`、`.opencode/agents/*`等格式。\n\n**@razroo/iso-route**：一个模型策略，所有工具。在单个`models.yaml`中声明默认模型和命名角色（planner、fast-edit、reviewer等），iso-route将其编译为`.claude/settings.json`、`.codex/config.toml`、`opencode.json`等。\n\n### 包装器（1个包）\n\n**@razroo/iso**：整个流程的包装CLI。如果`agent.md`是你的源文件，`iso build`会依次运行`agentmd lint`、`agentmd render`、`isolint lint`，然后`iso-harness build`。除非有理由直接使用子包，否则推荐使用这个入口。\n\n### 运行时控制库（6个包）\n\n**@razroo/iso-orchestrator**：提供可恢复的步骤、键控互斥锁和有界扇出，用于有副作用的代理工作流。\n\n**@razroo/iso-context**：解析上下文包，估算token，检查预算，渲染确定性的上下文包。\n\n**@razroo/iso-cache**：存储和验证内容寻址的本地产物，支持TTL感知读取和修剪。\n\n**@razroo/iso-capabilities**：解析、检查和渲染角色级别的工具/MCP/命令/文件系统/网络策略。\n\n**@razroo/iso-contract**：验证、解析和渲染结构化的工作流产物。\n\n**@razroo/iso-ledger**：记录追加式的领域事件，支持幂等键、查询、验证和物化视图。\n\n### 反馈工具（3个包）\n\n**@razroo/iso-eval**：评分"代理是否完成了任务？"——行为评估，检查文件系统/命令状态。\n\n**@razroo/iso-trace**：解析生产环境的代理会话记录，回答"哪些规则实际触发了？"、"代理最常使用哪些工具？"等问题。\n\n**@razroo/iso-guard**：对事件流执行运行时策略检查，验证扇出限制、清理前置、必需后续命令等不变量。\n\n## 快速开始\n\n大多数用户只需要`@razroo/iso`这一个包：\n\n```bash\nnpm install -D @razroo/iso\nnpx iso build .\n```\n\n给定一个`agent.md`（或现有的`iso/instructions.md`）和一个`iso/`源目录，这会检查源文件，重写为小型模型安全的版本，然后扇出到`CLAUDE.md`、`AGENTS.md`、`.cursor/rules/*`、`.opencode/*`和相应的MCP配置文件。\n\n## 平台支持矩阵\n\nIso目前支持四个主流AI编码助手平台：\n\n| 工具 | 提示/配置构建 | 模型绑定 | iso-eval运行器 | iso-trace解析器 | model-score |\n|------|--------------|---------|---------------|----------------|-------------|\n| Claude Code | 是 | 是 | 是 | 是 | 是 |\n| Codex | 是 | 是 | 是 | 是 | 是 |\n| OpenCode | 是 | 是 | 是 | 是 | 是 |\n| Cursor | 是 | 仅建议性注释 | 是 | 是 | 尚未支持 |\n\n值得注意的是，Cursor由于无法程序化绑定模型，只能提供建议性注释，这是平台限制而非Iso的局限。\n\n## 小型模型循环\n\n如果你的目标是"同样的工作流在小型模型上也能工作"，Iso支持一个更紧密的循环：\n\n- `isolint`将编写的提示词重写为小型模型安全的指令\n- `iso-route`允许你固定更便宜或本地的角色，而无需分叉提示词\n- `iso-context plan/check/render`将上下文选择保留在本地，而不是在提示词中重复上下文加载矩阵\n- `iso-cache put/get/verify`将可复用产物保留在本地，而不是每次运行时重新获取或推导安全输入\n- `iso-trace model-score`捕获工具模式失败，这些失败在较弱的路由上往往首先暴露\n\n这种设计让开发者可以用前沿模型开发和测试工作流，然后无缝降级到成本更低的小型模型，而无需重写提示词。\n\n## 实际应用场景\n\nIso特别适合以下场景：\n\n**多平台团队**：团队成员使用不同的AI编码助手（有人用Cursor，有人用Claude Code），但希望保持一致的代理行为\n\n**成本优化**：在开发阶段使用前沿模型，在生产/CI环境中切换到更便宜的模型，而无需维护两套提示词\n\n**企业合规**：通过`iso-guard`和`iso-ledger`实现可审计的代理工作流，满足合规要求\n\n**开源项目**：为项目提供标准化的代理配置，贡献者无论使用哪种AI工具都能获得一致体验\n\n## 技术架构亮点\n\nIso的设计有几个值得注意的技术选择：\n\n**本地优先**：所有运行时工具都是MCP-free和model-free的。它们可以从普通Node脚本中使用，将昂贵或脆弱的事实保留在提示词之外。\n\n**确定性**：关键操作（如上下文选择、产物缓存、事件记录）都是确定性的，支持可复现和可测试。\n\n**分层设计**：每个包都可以独立使用，但它们被设计为可以组合。这种模块化让开发者可以根据需要选择使用整个工具链或仅使用特定组件。\n\n**反馈闭环**：从编写（agentmd/isolint）到构建（iso-harness/iso-route）到运行（orchestrator/context/cache）到评估（eval/trace/guard），形成完整的反馈闭环。\n\n## 开源与生态\n\nIso采用开源模式发布在npm上，所有14个包都可以独立安装和使用。项目使用Changesets进行版本管理，每个PR如果修改了包都应该包含一个changeset描述用户可见的影响。\n\n项目还提供了完整的端到端示例，包括：\n- `examples/pipeline/`：演示7个包端到端运行的可执行示例\n- `examples/dogfood/`：包装器CLI本身的本地dogfood项目\n- `npm run test:pack`：打包本地workspace到临时项目并测试打包后的CLI\n\n## 总结\n\nIso代表了一种成熟的AI工程思维：与其让每个团队自己解决代理工具碎片化问题，不如提供一套标准化的工具链。它不是要取代任何特定的AI编码助手，而是要让这些助手能够协同工作。\n\n对于正在规模化使用AI编程助手的团队来说，Iso提供了一个值得认真考虑的解决方案。它可能不会立即改变你的日常工作流，但能让你的工作流更具可维护性、可移植性和成本效益——在这个AI工具快速迭代的时代，这种基础设施层面的投资尤为重要。