intent: "项目文档和使用指南（中文版）" role: documentation when_to_load: "初次安装或查阅使用说明"

Code Frontmatter (CFM)

代码文件的“身份证”。 让 AI 仅用 < 5% 的 Token 成本就能理解你的整个代码库。

Code Frontmatter (CFM) 是一个开放标准和 MCP (Model Context Protocol) 服务器，用于管理源代码文件中的结构化元数据。

通过在文件顶部添加轻量级的 YAML 头部，你可以将代码库从普通的“文本文件集合”升级为一张“语义图谱”，让 AI 助手（如 Cursor、Windsurf、Claude）能够即时、准确地导航。

🚀 为什么要用 CFM?

AI 编程助手在处理大型代码库时常面临以下问题：

1. 上下文溢出：读取所有文件以理解架构会消耗巨大的上下文窗口（且昂贵）。
2. 幻觉：AI 需猜测文件用途，容易导致 Bug。
3. 盲区：Agent 不知道去哪里寻找特定的逻辑。

CFM 通过暴露高层意图、架构角色和依赖关系图，解决了这些问题，且无需 AI 读取代码正文。

| 指标 | 不使用 CFM | 使用 CFM | | :--- | :--- | :--- | | 上下文成本 | 100% (全源码) | ~3-5% (仅头部) | | 检索速度 | 慢 (Grep/Read) | 即时 (语义索引) | | 准确性 | 概率性猜测 | 确定性 |

📦 安装

本项目设计为 Model Context Protocol (MCP) 服务器。

1. 适用于 Cursor

将以下内容添加到你的 ~/.cursor/mcp.json（或者通过 Cursor 设置界面添加）：

{
  "mcpServers": {
    "code-frontmatter": {
      "command": "npx",
      "args": ["-y", "code-frontmatter"]
    }
  }
}

2. 适用于 Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "code-frontmatter": {
      "command": "npx",
      "args": ["-y", "code-frontmatter"]
    }
  }
}

🤖 AI Agent 指引 (关键步骤)

为了充分利用 CFM，你必须明确指示你的 AI 助手使用它。 AI 模型通常比较“懒”，除非明确告知，否则它们倾向于猜测而不是调用工具。

请将以下内容复制并粘贴到你的项目规则 (.cursorrules / .windsurfrules) 或自定义指令中：

# Code Frontmatter Protocol (CFM)

本项目使用 Code Frontmatter (CFM) 管理文件元数据。
你必须严格遵守以下规则：

1.  **搜索优先**：当查找特定功能（例如“认证逻辑”）时，在读取文件内容之前，先使用 `cfm_search` 精准定位相关文件。
2.  **先读表头再读全文**：在读取任何文件全文之前，先调用 `cfm_read` 传入文件路径查看表头。根据 `intent` 和 `exports` 判断是否真的需要阅读全文。
3.  **维护头部**：
    - 创建新文件时，必须生成有效的 CFM 头部（intent, role, exports）。
    - 修改代码时，必须使用 `cfm_write` 更新头部中的 `exports` 和 `ai_notes`。
    - 保持 `ai_notes` 简练。只存储永久性的架构约束，不要记录变更日志。

📐 格式标准（无需安装任何工具）

CFM 真正的竞争力是文件头格式本身，而非 MCP 工具。即使不安装 CFM，手动在文件顶部添加 /*--- ---*/ YAML 头部，任何 AI 助手都能立即理解。

就像 JSDoc 一样 —— 你不需要安装任何工具就能从中受益。

⚡ 30 秒上手

只需在任何文件顶部添加 3 行：

/*---
intent: "处理用户登录和 Session 管理"
role: service
---*/

// 你的代码...

完成。任何 AI 读到这个文件时，无需阅读代码正文就能理解它的用途。

🔧 MCP 工具的附加价值

| 手动添加表头 | CFM MCP 工具 | | :--- | :--- | | ✅ AI 可以读取你的表头 | ✅ AI 可以搜索所有表头 | | ✅ 无需任何安装 | ✅ 自动化表头的创建和更新 | | ❌ 需要手动维护 | ✅ 检测表头与代码之间的漂移 |

总结：格式本身就是标准。MCP 工具只是自动化维护的手段。

🛠 使用方法 & 语法

头部格式

CFM 在你所用语言的标准注释语法中使用 YAML 块。

TypeScript / JavaScript / Java / C#:

/*---
intent: "处理 JWT 令牌验证和轮换"
role: service
exports:
  - "verifyToken: 检查签名"
  - "refreshToken: 发发新访问令牌"
depends_on: ["config.ts", "db-client.ts"]
ai_notes: "不要修改密钥派生逻辑。"
---*/

export function verifyToken(token) { ... }

Python / Ruby / Shell / YAML:

#---
# intent: "用户数据模型定义"
# role: model
# domain: "identity"
# mutates_state: false
#---

class User(BaseModel): ...

可用工具

作为 MCP 服务器安装后，你的 AI 将获得以下超能力：

• cfm_search({ directory, keyword, role, domain }):
  • 对头部进行语义搜索。这是定位文件的首选入口。
  • 适用场景：“查找哪处理用户计费”。先搜索，再决定要读什么。
• cfm_read({ path }):
  • 读取 CFM 表头。传入文件路径读取单个表头，传入目录路径扫描所有文件。
  • 适用场景：在读取文件全文之前，先查看它的“身份证”。
• cfm_write({ file, intent, ... }):
  • 写入或更新头部。
  • 适用场景：创建新文件或更新文档。
• cfm_register_language({ name, extensions, ... }):
  • 教服务器如何解析自定义文件类型的头部。

🤝 贡献代码

我们希望将其打造为 AI-Code 交互的行业标准。

1. Fork 本仓库。
2. 创建一个特性分支。
3. 提交 PR。

关注领域：

• 更多语言的解析器 (Rust, Go, Swift)。
• IDE 扩展 (VS Code, JetBrains)。
• 分析工具。

📄 许可证

MIT © 2026 coobi7