架构

TL;DR — AI-Native Workspace 是一个开源框架，用来把 AI coding agent 真正接入长期运行的研究或工程工作区。它的核心思路很简单：把 Model、Agent、Protocol、Application 四层拆开，让 Claude、DeepSeek、Codex、Cursor、MCP 服务、项目文档和知识管理流程可以独立替换，而不是绑死在同一个生态里。 大多数 AI coding 工作流一开始都像一堆有用但松散的碎片：一个 CLAUDE.md，几段 prompt，几个 shell 脚本，也许还有 .cursorrules，再加一句“记得更新 TODO”。 单项目时这能跑。等工作区长到五六个项目、三四个模型供应商、一个 wiki、一个 inbox、几组本地服务和几个月的历史决策时，它就开始变形。 AI-Native Workspace 是我们把这堆经验整理成架构的尝试。 它不是另一个 dotfiles dump。它的出发点是：把 workspace 本身看成操作系统；model 提供推理能力，agent 像进程一样运行，protocol 是系统调用，application layer 才是真正的工作产物。 这个比喻听起来有点抽象，但它解决的是一个很实际的问题：当模型、agent 和工具每几个月就变化一次时，怎样让一个 AI 工作区保持可迁移？ 问题：大多数 Agent 工作流耦合太重 现在很多 “AI workflow” 配置都绑定在一个单一生态里： 一个模型供应商， 一个 coding agent， 一种配置格式， 一套项目结构， 一组工具集成。 这能让你很快开始，但后续成本会慢慢出现。模型涨价了，脚本要改。agent 换了配置格式，规则要改。加第二个项目后，根目录说明开始变成垃圾桶。聊天记录断了，agent 就失去了过去决策的原因。 AI-Native Workspace 从相反的假设出发： workspace 应该比任何单个模型、agent、供应商或工具活得更久。 所以它把整个系统拆成四层。 四层架构 1 2 3 4 5 6 7 8 9 10 11 12 13 ┌─────────────────────────────────────────────────────────┐ │ Application │ │ Projects · Inbox · Wiki · workflows │ ├─────────────────────────────────────────────────────────┤ │ Protocol │ │ CLAUDE.md conventions · CLI tools · MCP servers │ ├─────────────────────────────────────────────────────────┤ │ Agent │ │ Claude Code · Codex · Cursor · markdown-aware agents │ ├─────────────────────────────────────────────────────────┤ │ Model │ │ DeepSeek · Claude · Qwen · OpenAI · local models │ └─────────────────────────────────────────────────────────┘ 每层只负责一件事。更重要的是，每层都可以替换，而不强迫其他层一起重写。 ...

一句话 — n8n 和 Dify 在自托管 AI 评测里经常并列出现，但它们想占据栈里完全不同的层。对照一套自建 AI 系统认真评估之后，我们吸收了 n8n，跳过了 Dify。决策归到同一个问题——“它想占据哪一层，而我是不是已经拥有那一层？"——两个平台的答案正好相反。这篇把决策框架完整摊开，你可以对着自己的栈跑一遍同样的评估。 为什么这个对比在 2026 年还值得写 半年前问"哪个 OSS AI 平台应该自己跑”，认真的答案大概只有三个。今天有几十个，而且彼此功能严重重叠。Dify 和 n8n 在评估清单里几乎总是并列出现——都用 TypeScript 写、都能 Docker 自托管、都有可视化编辑器、都能调 LLM。 这种表面的相似很有误导性。它们想占据的栈层完全不同。 把它们当替代品评估是一个范畴错误，代价就是一周的部署+返工。 对照已有的自托管栈认真评估后，我们得到的结论是： Dify 想当 orchestrator。如果你已经有一个 orchestrator，Dify 一无是处。 n8n 想当执行层（execution layer）。如果你还没有执行层，n8n 是市面上最好的开箱选项之一。 Dify 是什么 Dify 是开源 LLM 应用开发平台（Apache 2.0，GitHub 55k+ ⭐）。它的卖点： 可视化工作流编辑器 — 拖节点构建 AI 流水线 内置 RAG — 上传文档，得到一个可查询的知识库 Agent 构建器 — 预打包的 prompt 模板 + tool calling 模型网关 — 在 OpenAI / Anthropic / DeepSeek / 本地模型之上抽象一层 可观测性 dashboard — 请求日志、延迟、成本 2025–2026 年 Dify 用自研的 “Beehive Runtime” 替换了底层 LangChain，工程实现确实扎实。这个产品本身是认真做的。 ...

TL;DR — 我们逆向了 Claude Code 的 TypeScript 源码，搞清楚了它的 Agent 架构如何处理安全、复杂任务和工具权限。然后把这些模式用到了一个开源项目上——让玩家在泰拉瑞亚游戏里跟 AI 聊天，AI 还能给道具、改天气、传送玩家。以下是我们的发现、实现过程和踩坑总结。 为什么要拆 Claude Code 的源码 Claude Code 不只是个编程助手。底层它是一个 Agent 运行时——会 spawn 子 Agent、管理文件权限、跑 bash 命令、判断什么时候该问用户什么时候该直接做。我们想搞清楚它的内部机制，然后把这些想法用到一个完全不同的场景：泰拉瑞亚游戏服务器。 我们的项目 terra_llm_bridge 把泰拉瑞亚 TShock 服务器接到了一个 LLM 上。玩家在聊天框打 @ai 就能跟 AI 对话——但 AI 不止能聊天，还能做事：给道具、改天气、传送玩家，甚至能切换困难模式。最后那条就是我们翻车的地方。 第一次有玩家让 AI 设成雨天，LLM 自作主张调了 terra_world_hardmode(confirm=True)——把整个服务器的世界不可逆地切成了困难模式。没人要求它这么做。模型自己觉得该做就做了。 我们需要一个真正的权限系统。于是去翻 Claude Code 的源码。 Claude Code 的 7 层权限架构 通读 src/utils/permissions/permissions.ts 的约 1500 行代码，加上 Agent 工具的基础设施（约 3800 行），一套清晰的架构浮现出来。Claude Code 不是靠单点检查做安全——它有七层： Layer 1a: 拒绝规则 → "永远不允许 Bash(git push --force)" Layer 1b: 询问规则 → "Bash(curl *) 总是弹窗确认" Layer 1c: 工具自检 → 每个工具 checkPermissions() 自己的逻辑 Layer 1d: 工具自拒 → Read 工具白名单特定路径 Layer 1f: 内容规则 → "就算 bypass 模式，npm publish 也要弹窗" Layer 1g: 安全检查 → ".git/、.claude/ 永远不能绕过用户确认" Layer 2: 模式旁路 → bypassPermissions / auto / acceptEdits / dontAsk Layer 3: YOLO 分类器 → AI 读全文 transcript，判断是否安全 最有意思的是 YOLO 分类器——一个独立的小模型，读取完整对话记录，把每次工具调用分类为安全或危险。两阶段系统：快速分类器处理明显 case，深度思考分类器处理边界情况。 ...