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       │
└─────────────────────────────────────────────────────────┘

每层只负责一件事。更重要的是，每层都可以替换，而不强迫其他层一起重写。

第一层：Model

Model layer 是提供推理能力的 LLM：Claude、DeepSeek、Qwen、OpenAI、Gemini，通过 Ollama 或 vLLM 跑的本地模型，或者第三方 relay。

AI-Native Workspace 把模型视为最容易替换的一层。这是刻意设计的。模型质量和价格一直在变。一个只能在单一供应商上工作的流程很脆弱。

实际使用中，框架倾向于通过环境配置切换 provider。日常编辑可以用便宜模型，深度架构任务再切强推理模型。workspace 本身不需要知道当前跑的是哪一个。

第二层：Agent

Agent layer 是读取指令、理解任务并调用工具的软件。今天可能是 Claude Code，明天可能是 Codex CLI、Cursor、Aider、Continue，或者一个自定义 LangGraph agent。

这里的关键设计是：工作区指令用普通 markdown 写。文件名可以叫 CLAUDE.md，但内容并不天然只属于 Claude。任何能读 markdown 的 agent 都能理解这套约定。

这让 CLAUDE.md 变成 agent 的运行时配置，而不只是 README。它告诉 agent：有哪些项目，状态放在哪里，如何结束一次会话，如何恢复工作，哪些文档是权威来源。

第三层：Protocol

Protocol layer 定义 agent 如何跟外部世界交互。

这里分三档：

1. File protocol — CLAUDE.md、inbox/TODO.md、wiki/MANIFEST.md 这类 markdown 约定。
2. CLI tools — git、curl、docker、Python、Node、Hugo，或者任何本地命令行工具。
3. MCP servers — 可选扩展，用来接搜索、数据库、API、游戏服务器、内部系统等。

重点是：MCP 不是前提。最低可用协议是一份能读的文件。哪怕没有任何 MCP server，只要 agent 能读 markdown，它仍然可以运行这个 workspace 的核心流程。

这是项目里最实用的约束之一：file protocol 是地板，MCP 是天花板。

第四层：Application

Application layer 才是真正的工作区：项目、inbox、wiki、work log 和累积下来的知识。

一个最小工作区大概长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

workspace/
├── CLAUDE.md              # workspace-level cognitive config
├── inbox/                 # low-friction capture buffer
│   ├── README.md
│   └── TODO.md
├── projects/              # concrete work
│   ├── project-a/
│   │   └── CLAUDE.md
│   └── project-b/
│       └── CLAUDE.md
└── wiki/                  # matured knowledge base
    └── MANIFEST.md        # progressive-loading index

这一层让 AI-Native Workspace 不只是 agent 配置模板，而是一套实际的知识生命周期。

亮点一：先 Inbox，后 Wiki

这个项目里最有价值的想法可能也是最简单的：不要要求每条记录一开始就进入结构化知识库。

inbox/ 是草稿缓冲区。会话总结、临时笔记、半成型想法、TODO、会议碎片都可以先放进去。第一天不需要完美分类。

只有当某个信息反复变得有用时，它才应该沉淀进 wiki/。

这比“永远保持一个干净知识库”的想法更适合真实 AI-agent 工作流。Agent 会产生大量中间状态，人类也会在跨会话时忘掉细节。Inbox 给双方一个低成本的上下文缓冲区，先保存，再判断哪些东西值得长期存在。

亮点二：渐进式上下文加载

AI agent 经常不是因为上下文太少失败，而是因为加载了太多无关上下文而失焦。一个有几百篇笔记的 workspace 不可能每次都塞进 prompt。

AI-Native Workspace 用 wiki/MANIFEST.md 做轻量索引。Agent 先读 manifest，看每个文件的一行摘要，再只加载真正相关的文件。

这跟数据库索引是同一个思想：

• 先扫便宜的 index，
• 选出少数相关条目，
• 需要细节时再读取正文。

结果是，workspace 可以扩展，而不会把每次会话都变成 context dump。

亮点三：分层 CLAUDE.md

框架在多个层级使用 CLAUDE.md：

1
2
3

~/.claude/CLAUDE.md              # global preferences
<workspace>/CLAUDE.md            # workspace map and shared workflows
<workspace>/<project>/CLAUDE.md  # project-specific instructions

这避免根目录文件变成 500 行的杂物间。

根 CLAUDE.md 应该是 router：告诉 agent 有什么、去哪看、哪些规则全局适用。项目级细节留在各项目自己的文档里。稳定知识进入项目文档或 wiki。临时状态留在 inbox。

这个分离很朴素，但非常重要。它让一个用了几个月的 workspace 仍然可读。

亮点四：面向 Agent 优化，但人类也能接手

AI-Native Workspace 是为 agent 设计的，但没有把系统藏在人类看不懂的自动化后面。

这很重要，因为人类是 fallback operator。API 会挂，模型会退化，工具会坏，agent 有时也会迷路。这时，人类应该能读同一组文件，理解当前状态，并继续推进工作。

所以框架尽量避免魔法。普通 markdown，普通目录，普通 CLI 工具，显式协议。

亮点五：把反模式当成一等设计对象

这个 repo 很明确地写了“不应该做什么”。比如：

这说明项目不是从白板上画出来的，而是从真实使用中长出来的。这里的反模式基本都是日常运行多项目 AI workspace 后留下的伤疤。

谁适合用？

AI-Native Workspace 适合这些人：

• 每天都用 AI coding agent，
• 同时推进多个项目，
• 在意跨会话连续性，
• 希望在不同模型供应商之间切换而不重写 workflow，
• 工作会在几个月内持续积累知识。

如果你只有一个短期项目，它可能有点重。那种情况下，一个简单的 CLAUDE.md 就够了。

Bootstrap 文件就是产品的一部分

这个 repo 里有一个很有意思的文件：BOOTSTRAP.md。它不是写给人看的，而是写给 AI agent 看的。

预期用法很直接：

1. 创建一个空 workspace 目录。
2. 打开 Claude Code、Codex、Cursor 或其他 agent。
3. 把 BOOTSTRAP.md 作为第一条 prompt 粘进去。
4. 让 agent 自己生成初始结构。

这让项目有点“自举”的味道：框架把自己解释给那个将要搭建它的 agent。

最后

AI-Native Workspace 不想做一个重型平台。它的赌注几乎相反：AI-native 工作流里真正耐用的部分，应该是简单文件、明确约定和清晰边界。

模型会变，agent 会变，MCP server 会增减。但一个结构良好的 workspace 可以穿过这些变化。

核心洞察是：

不要把 workflow 建在某个模型上。把它建在一个能替换模型的 workspace 架构上。

如果你想把 AI coding agent 变成一个长期运行的研究或工程伙伴，这个区别很关键。

项目链接：RedDragonHQ/ai-native-workspace

如果你有任何疑虑，或者想进一步了解这套架构如何在真实工作区里运行，欢迎随时联系：contact@aibrew.ai。

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，深度思考分类器处理边界情况。

但对我们最有用的不是 AI 分类器。而是 Claude Code 如何在结构上防止某些工具在错误的上下文中被调用——通过工具白名单、黑名单和子 Agent 特化。

Agent 模式：不是多 Agent 协作，而是专项 Worker

Claude Code 用的不是"Agent 之间协商谈判"的多 Agent 协作。它是一个主协调器 + 专项 Worker：

主 Agent（Tool Calling，全部工具）
  │
  ├─ 简单: "读文件 X" → Read 工具
  │
  └─ 复杂: "审计这个分支" → Agent("Explore")
                              │
                              ├─ 工具: [Read, Grep, Glob]  ← 白名单
                              ├─ 禁止: [Edit, Write]        ← 黑名单
                              ├─ 系统提示: "你是文件搜索专家"
                              └─ 返回结果 → 主 Agent 行动

每个子 Agent 类型由三要素定义：

1. 工具权限（白名单 + 黑名单）——能碰什么
2. 系统提示——角色专属指令
3. 模型——Explore Agent 用 Haiku（便宜），Plan Agent 用 Sonnet（推理强）

核心洞察：主 Agent 不会变更复杂。它保持简单，只有一个 Agent 工具让它把复杂任务委派出去。子 Agent 就是另一个 Tool Calling 循环，只是工具受限 + 提示词不同。

这套架构的可组合性是关键：每个零件简单，但组合起来能处理单个 prompt 消化不了的复杂度。

我们怎么把这个模式用到 terra_llm_bridge

我们的泰拉瑞亚桥接比 Claude Code 简单——46 个工具而非几百个，“安全问题"是"别在玩家问天气时切 hardmode"而不是"别让 AI rm -rf /"。但模式是直接可以搬的。

问题

改之前：LLM 同时看到所有 46 个工具。当玩家问"给我最强套装”，LLM 会并行调 wiki_search 查资料 + give_item 给东西——一边查 wiki 一边已经预判了 Solar Flare 套装。有时候猜对，有时候给召唤师玩家塞了一套战士装备。

解决方案：两阶段工具开放

我们没有加子 Agent——46 个工具不需要。但我们在 graph 层面用了工具限制模式：

route → llm(研究)  ⇄  tool      →  escalate  →  llm(行动)  ⇄  authorize  ⇄  tool  →  output
        17 个只读工具                          46 全工具      关键词 gate
        wiki、lookup、状态                       give、kick、spawn

图有两个阶段：

研究阶段——LLM 只拿到 17 个只读工具（wiki_search、item_lookup、player_list、world_info 等）。它不能调 give_item、kick、spawn 或任何破坏性工具。先查资料。

升级（escalate）——当 LLM 输出文本（没有更多 tool_call），图自动切到行动模式，注入提示：“你现在可以访问全部工具了。”

行动阶段——LLM 拿到全部 46 个工具，可以对研究发现做出行动。

这是结构层面强制执行的，不是 prompt 建议。LLM 在研究阶段根本调不了 give_item，因为这个工具没绑定。

权限 Gate

在两阶段拆分之前，我们还加了 authorize_node——LLM 和 ToolNode 之间的硬拦截，检查玩家聊天最近的消息是否包含该工具领域的关键词：

1
2
3
4
5
6

GATED_TOOLS = {
    "terra_world_hardmode": {"hardmode", "hard mode", "肉山", "困难模式"},
    "terra_player_kick":    {"kick", "踢出", "踢了"},
    "terra_server_stop":    {"stop server", "关服", "停服"},
    # ... 还有 8 个
}

如果玩家说"设个雨天试试"而 LLM 想调 world_hardmode，authorize_node 检查：玩家最近的消息里有 hardmode 相关的关键词吗？没有？拦截。 这个工具调用被替换成 BLOCKED 消息，ToolNode 根本看不到。

这是粗过滤器——它检查的是玩家提到了什么，而不是玩家请求了什么。“上次打肉山的时候"会通过关键词检查，尽管玩家没要求开 hardmode。但粗够了：目标是拦截灾难性的跨界调用（天气 → hardmode），不是完美理解意图。

我们选择不做的

没有 YOLO 分类器

Claude Code 的 AI 分类器读完整 transcript，用另一个模型判断工具调用是否安全。我们没做，因为：

• 增加延迟——每次 gated 工具调用前多一次 LLM 请求
• 泰拉瑞亚聊天风险低——给错套装可以补救
• 关键词匹配已经能拦住灾难性 case

没有子 Agent 派生

Claude Code 为复杂任务 spawn 子进程。我们不需要：

• 泰拉瑞亚工具面小（46 个）
• 多轮工具调用已经能处理我们实际面对的场景
• 给游戏聊天机器人 spawn 子进程是过度工程

没有 ReAct 模式

经典的 Thought → Action → Observation 循环会增加 token 消耗，但不改变我们的核心能力。DeepSeek 的 thinking tokens 已经承担了推理，而两阶段工具访问比基于 prompt 的 ReAct 更可靠地强制了"先研究再行动”。

一张图看清架构

┌──────────────────────────────────────────────────────────┐
│  泰拉瑞亚服务器（TShock + C# 插件，24 个游戏 Hook）        │
│  玩家输入 "@ai 给我最好的套装"                             │
└──────────────────────┬───────────────────────────────────┘
                       │ JSON webhook
┌──────────────────────▼───────────────────────────────────┐
│  Python aiohttp 监听器 (:9876)                            │
└──────────────────────┬───────────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────────┐
│  LangGraph StateGraph                                     │
│                                                           │
│  route  →  llm(研究)  ⇄  tool      17 只读工具           │
│               │                                           │
│          escalate  →  llm(行动)  ⇄  authorize  ⇄  tool   │
│                          46 全工具      关键词拦截         │
│               │                                           │
│             output  →  广播到游戏聊天                      │
│                                                           │
│  记忆: AsyncSqliteSaver 按玩家（thread_id）持久化          │
└──────────────────────────────────────────────────────────┘
                       │
         ┌─────────────┴──────────────┐
         ▼                            ▼
   TShock REST API              Terraria Wiki API
   (give / kick / spawn)        (terraria.wiki.gg)

源码分析的启示

读 Claude Code 源码教会我们三件事，适用于任何 Agent 项目：

1. 安全是分层的，不是二元的。 一个 confirm 参数对 LLM 来说只是软建议。真正的安全需要结构性约束——LLM 不该能调用它无权使用的工具，就像 Web 服务器不该让你访问没有权限的端点，不管你怎么礼貌地请求。

2. 工具限制是最便宜也最可靠的安全形式。 Claude Code 的 Explore Agent 之所以"只读"，不是因为 prompt 写了——是因为 Edit 和 Write 不在它的工具列表里。我们的研究阶段之所以"先查资料"，不是 prompt 建议——是因为 give_item 根本没绑定。你不能通过 prompt injection 绕过不存在的工具。

3. 特化胜过复杂化。 Claude Code 的子 Agent 不比主 Agent 更聪明——只是更受约束。更少的工具 + 聚焦的 prompt = 更可靠的行为。我们的两阶段系统同理：先限制，准备就绪再扩展。

关于这个项目

terra_llm_bridge 是一个连接泰拉瑞亚游戏服务器与 LLM 的开源项目。功能包括：

• 24 个游戏 Hook——自研 C# TShock 插件捕获聊天、Boss 击杀、死亡、登录等 24 种事件
• 46 个管理工具——给道具、管玩家、控天气、召 NPC、管区域和权限
• 两阶段 Agent——研究（17 工具）→ 行动（46 工具）
• 硬权限 Gate——基于关键词的 authorize_node 拦截未授权工具调用
• MCP 服务端——同 46 工具暴露给 Claude Code 做服务器管理
• 持久化记忆——通过 LangGraph AsyncSqliteSaver 按玩家保持对话历史

项目目前处于活跃测试阶段，尚未发布到 GitHub。我们在私有泰拉瑞亚服务器上运行，迭代 Agent 架构后再开源。如果对代码感兴趣或想提前体验，欢迎联系。

技术栈：Python 3.14, LangGraph 1.x, DeepSeek（Anthropic 兼容 API）, C# .NET 9, TShock v6.1.0, aiohttp, httpx.