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 很明确地写了“不应该做什么”。比如：

避免 更好的做法
一上来就做多 Agent 编排 先用单 Agent，只有上下文真的不够时再拆
启动时加载整个 workspace 先读索引，再按需深入
所有东西直接写进 wiki 先进入 inbox，让知识自然沉淀
把根 CLAUDE.md 写得很长 根文件做 router，细节下沉
把 TODO.md 当成绝对命令队列 执行前验证 TODO 是否过期
核心流程依赖 MCP 文件协议做核心，MCP 按需添加

这说明项目不是从白板上画出来的，而是从真实使用中长出来的。这里的反模式基本都是日常运行多项目 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

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