chat.md: The Hacker's AI Chat Interface [Experimental]

chat.md：黑客的 AI 聊天界面 [实验性]

终于有了一个支持 MCP、可用于任何大模型的完全可编辑聊天界面。

chat.md 是一个 Visual Studio Code 扩展，通过纯文本文件重新构想 AI 交互方式。与临时的网页界面或专有聊天窗口不同，chat.md 采用文件优先的方式，让你与 AI 的对话就是带有 .chat.md 扩展名的 Markdown 文件。你可以编辑、进行版本控制、分享——这些文件都属于你。AI 会直接在文件中写入回复。

现在，任何 *.chat.md 文件都能由你改造为 AI Agent。尽情尝试非线性的 AI 对话吧。

使用视频

这是我使用 gemini-2.5-pro 和 wcgw mcp 发布此 vscode 扩展时用的聊天记录

注意 ⚠️：chat.md 完全由 AI 编写，应将其视为功能丰富的 POC。

为什么选择 chat.md？

其他 AI 工具	chat.md
❌ 线性对话或编辑能力有限	✅ 非线性编辑——改写历史记录、分支对话
❌ 工具执行受限于专有实现	✅ 任何大模型都能调用工具
❌ 无法手动编辑 AI 回复	✅ 替大模型发言——编辑内容，并让它从那里继续
❌ 许多大模型不支持 MCP	✅ 任何大模型都能使用 MCP 服务
❌ 助手回复达到最大令牌限制后无法继续	✅ 随时继续未完成的 AI 回复
❌ 对话保存在云端或无法访问	✅ 文件以人类可读的格式存储在本地代码旁
❌ 上下文与工作区分离	✅ 直接附加项目中的文件

功能

🗣️ 基于文件的对话

与 Copilot 的内联建议、ChatGPT 的网页界面或 Cursor 的侧边栏不同，chat.md 将对话视为工作区中的一等文件：

# %% user
How can I optimize this function?

[#file](src/utils.js)

# %% assistant
Looking at your utils.js file, I see several opportunities for optimization:

1. The loop on line 24 could be replaced with a more efficient map/reduce pattern
2. The repetitive string concatenation can be improved with template literals
...

🔌 通用模型支持

• Anthropic Claude：所有模型（Opus、Sonnet、Haiku）
• OpenAI：GPT-4、GPT-3.5、o 系列，以及支持 OpenAI Responses API
• 自定义 API：任何兼容 OpenAI 的端点（Azure、Google Gemini 等）
• 快速切换：在对话过程中切换不同模型。

🛠️ 通过 MCP 实现通用工具生态

Chat.md 是一个 Model Context Protocol（MCP） 客户端——这是一种适用于任何大模型的开放工具执行标准。

与许多聊天应用不同，Chat.md 不会限制任何大模型调用工具。

• 真正通用：任何 AI 模型（Claude、GPT、开源模型）都能使用任何 MCP 工具
• 模型无关：无论使用哪个 AI 模型进行对话，工具的工作方式都相同
• 不受供应商锁定：切换模型也不会丢失工具功能

<tool_call>
<tool_name>filesystem.searchFiles</tool_name>
<param name="pattern">*.js</param>
<param name="directory">src</param>
</tool_call>

📎 上下文文件附件

• 在对话中直接附加文本文件和图片（粘贴任何已复制的图片）
• 使用熟悉的 Markdown 语法链接文件：[file](path/to/file)
• 文件路径相对于聊天文档解析——非常适合提供项目上下文（也可使用绝对路径）

💾 可编辑的对话

由于 chat.md 文件只是文本，你可以完全掌控与 AI 的交互：

• 非线性编辑：编辑对话中较早的部分，以改写历史记录
• 对话改造：编辑 AI 的回复，替 AI 发言
• 控制续写：让 AI 从任意编辑位置继续
• 继续被截断的输出：如果 AI 回复被截断，只需添加一个新的 assistant 区块并继续
• 适用于 Git：跟踪对话变更、协作编写提示词，并对对话进行分支
• 对话模板：为常见任务创建可复用的对话开场内容

入门指南

快速开始

1. 从 VS Code 市场安装 'chat.md'
2. 配置你的 API 密钥：
   • 命令面板 → “添加或编辑 API 配置”
3. 创建新聊天：
   • Opt+Cmd+'（Mac）/ Ctrl+k Ctrl+c（Windows/Linux），创建一个新的 '.chat.md' 文件，并在用户块中填充工作区信息。
   • 或在任意位置创建扩展名为 .chat.md 的文件，并在 vscode 中打开。
4. 在 '# %% user' 块中输入你的问题，然后按 'Shift + Enter'（或者直接创建新的 '# %% assistant' 块并按 Enter）
5. 观察助手逐步生成回复并调用工具。

你也可以选择并排打开 Markdown 预览，以实时预览聊天内容，更加方便易用。

使用信息

• 你可以插入 # %% system 块，向系统提示词追加新指令。
• 你可以在 vscode 设置中手动添加 API 配置和 MCP 配置。参见示例设置
• 点击底部的实时状态栏“Chat.md streaming”图标，或运行“chat.md: Cancel streaming”命令来中断生成
• 你也可以使用与创建新聊天相同的快捷键“Opt+Cmd+'”来取消生成。
• 你可以运行“Refresh MCP Tools”命令重新加载所有 mcp 服务。然后运行“MCP Diagnostics”查看可用的 mcp 服务。
• 你可以运行“Select api configuration”命令，在 API 提供商之间切换

配置

chat.md 支持三级配置系统，优先级如下（从高到低）：

1. 文件专属配置 - 在单个 .chat.md 文件顶部设置
2. 提供商专属配置 - 在 VS Code 设置中为每个 API 提供商设置
3. 全局配置 - 默认 VS Code 设置

文件专属配置

在任意 .chat.md 文件开头配置参数：

selectedConfig="my-provider"
openaiApi="responses"
reasoningEffort="high"
maxTokens=4000
maxThinkingTokens=20000

# %% system
Your system prompt here

VS Code 设置

通过 VS Code 的设置 UI 或 settings.json 访问这些配置：

• chatmd.apiConfigs：命名的 API 配置（提供商、API 密钥、模型、基础 URL、可选的推理/令牌设置，以及 openaiApi："auto" | "chat" | "responses"）
• chatmd.selectedConfig：当前启用的 API 配置
• chatmd.openaiApi：OpenAI API 模式 - "auto"（对 OpenAI 托管的 gpt/o 系列使用 Responses API，其他情况使用 Chat Completions）、"responses" 或 "chat"
• chatmd.mcpServers：配置 MCP 工具服务
• chatmd.reasoningEffort：全局推理深度（none、minimal、low、medium、high）
• chatmd.maxTokens：全局最大响应令牌数
• chatmd.maxThinkingTokens：全局最大思考令牌数

工具执行

当 AI 回复包含工具调用时，扩展将自动：

1. 在助手回复后添加一个 tool_execute 块
2. 使用指定参数执行工具
3. 将工具结果插入回文档
4. 添加新的助手块，让 AI 继续

你也可以通过以下方式手动触发工具执行：

• 将光标置于包含工具调用的助手回复末尾时按 Shift+Enter
• 这将插入一个 tool_execute 块并执行该工具

键盘快捷键

• Shift+Enter：插入下一个块（在用户/助手之间交替）；如果光标位于包含工具调用的助手块末尾，则插入 tool_execute 块
• Opt+Cmd+'（Mac）/ Ctrl+k Ctrl+c'（Windows/Linux）：创建新的上下文聊天或取消当前生成

MCP 工具集成

连接任意 Model Context Protocol 服务以扩展 AI 能力：

本地 MCP 服务（stdio）

适用于与 VS Code 在同一环境中运行的本地 MCP 服务：

"chatmd.mcpServers": {
  "wcgw": {
    "command": "uvx",
    "args": [
      "--python",
      "3.12",
      "--from",
      "wcgw@latest",
      "wcgw_mcp"
    ]
  }
}

远程 MCP 服务（Streamable HTTP）

chat.md 支持 MCP 规范 2025-11-25 中新增的 Streamable HTTP 传输方式，该方式取代了旧版 HTTP+SSE 传输方式。这是连接远程 MCP 服务的推荐方式。

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "https://example.com/mcp",
    "transport": "streamable-http"
  }
}

你也可以传入自定义 HTTP 标头（例如用于身份验证）：

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "https://example.com/mcp",
    "transport": "streamable-http",
    "headers": {
      "Authorization": "Bearer your-token-here"
    }
  }
}

自动检测传输方式

默认情况下，transport 字段为 "auto"——chat.md 会先尝试新的 Streamable HTTP 传输方式；如果服务不支持，则自动回退到旧版 SSE 传输方式。你可以显式将传输方式设为 "streamable-http"、"sse" 或 "auto"：

值	行为
"auto"（默认）	先尝试 Streamable HTTP，不可用时回退到 SSE
"streamable-http"	仅使用新的 Streamable HTTP 传输方式
"sse"	仅使用旧版 SSE 传输方式

远程 MCP 服务（旧版 SSE）

对于仅支持已弃用的 HTTP+SSE 传输方式的旧版远程 MCP 服务：

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "http://localhost:3000/sse",
    "transport": "sse"
  }
}

如果需要，你也可以添加环境变量：

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "http://localhost:3000/sse",
    "transport": "sse",
    "env": {
      "API_KEY": "your-api-key-here"
    }
  }
}

AI 会自动发现本地和远程服务提供的工具，并了解如何使用它们！工具列表每 5 秒自动刷新一次，以保持最新状态。所有 MCP 服务都会并发初始化，因此某个服务响应缓慢或出现故障，都不会阻塞其他服务。

理念

chat.md 摆脱了人为设定的“聊天”范式，并认识到 AI 交互从根本上说是文本处理。将对话视为文件，可以让：

1. 轻松实现持久化——无需特殊的云同步或专有格式
2. 内置协作能力——像处理其他代码一样分享、比较差异和合并
3. 版本控制顺理成章——跟踪随时间发生的更改
4. 自定义不受限制——随心所欲地编辑文件

限制

1. MCP——目前仅支持工具；未来将支持提示词和资源。
2. anthropic api 尚不支持缓存。
3. Gemini、ollama、llm studio 及其他模型只能通过 openai-api 访问。

示例 vscode 设置

vscode json 设置

  "chatmd.apiConfigs": {
    "gpt-5.2": {
      "type": "openai",
      "apiKey": "",
      "model_name": "gpt-5.2",
      "openaiApi": "responses",
      "reasoningEffort": "none"
    },
    "gemini-2.5pro": {
      "type": "openai",
      "apiKey": "",
      "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
      "model_name": "gemini-2.5-pro-exp-03-25"
    },
    "anthropic-sonnet-3-7": {
      "type": "anthropic",
      "apiKey": "sk-ant-",
      "base_url": "",
      "model_name": "claude-3-7-sonnet-latest",
      "maxTokens": 6000,
      "maxThinkingTokens": 18000
    },
    "openrouter-qasar": {
      "type": "openai",
      "apiKey": "sk-or-",
      "base_url": "https://openrouter.ai/api/v1",
      "model_name": "openrouter/quasar-alpha"
    },
    "groq-llam4": {
      "type": "openai",
      "apiKey": "",
      "base_url": "https://api.groq.com/openai/v1",
      "model_name": "meta-llama/llama-4-scout-17b-16e-instruct"
    },
    "together-llama4": {
      "type": "openai",
      "base_url": "https://api.together.xyz/v1",
      "apiKey": "",
      "model_name": "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8"
    }
  },
  "chatmd.mcpServers": {
    
    "wcgw": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "tool",
        "run",
        "--python",
        "3.12",
        "--from",
        "wcgw@latest",
        "wcgw_mcp"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": ""
      }
    },
    "fetch": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["mcp-server-fetch"]
    }
  },
  "chatmd.selectedConfig": "gemini-2.5pro",
  "chatmd.maxTokens": 8000,
  "chatmd.maxThinkingTokens": 16000,
  "chatmd.reasoningEffort": "medium"

配置说明：

• maxTokens（默认值：8000）控制模型响应的最大 token 数
• 对于 OpenAI 推理模型（o1、o3 系列），maxTokens 用作总 max_completion_tokens 预算（包括思考和响应 token）
• 对于 Anthropic 模型，maxThinkingTokens 用于单独控制思考 token 预算，也可以根据 reasoningEffort 自动计算
• 特定提供商的配置会覆盖全局设置，特定文件的配置会同时覆盖这两者（详细的优先级规则请参阅 CONFIGURATION.md）

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

反馈与贡献

• 在 GitHub 仓库中提交问题
• 欢迎通过拉取请求贡献

致谢

• 使用 wcgw mcp 的 Claude
• 使用 chat.md 的 Gemini 2.5 pro