跨 AI 助手项目上下文管理系统 — 让不同 Agent 无缝切换项目
Cross-AI-Agent Project Context Management — Seamless handoffs between AI assistants
中文：当你使用多个 AI 助手（DeepSeek、Kimi、GLM、Claude 等）交替开发同一个项目时，每次切换都要重新解释项目背景——浪费时间且容易遗漏。project-brain 用一套结构化的 Markdown 文件系统，让每个 AI 助手进入项目时自动读取上下文，离开时留下清晰的交接记录。
English: When you switch between multiple AI assistants (DeepSeek, Kimi, GLM, Claude, etc.) on the same project, you waste time re-explaining context every time. project-brain uses structured Markdown files so each AI assistant automatically reads project context when entering and leaves clear handoff notes when leaving.
| 特性 Feature | 中文说明 | English Description |
|---|---|---|
| 🏗️ 三层渐进式入口 | Layer 1 速览（20行）→ Layer 2 开发环境 → Layer 3 深度参考。渐进披露，防止上下文膨胀 | Three-Layer Entry File: Layer 1 summary → Layer 2 dev env → Layer 3 deep ref. Prevents context bloat |
| 📋 结构化交接清单 | ✅可继续 / |
Structured Handoff Checklist: next agent instantly knows project status |
| 🔍 提案审查 8 项规则 | 含自我反驳、外部依赖风险、回滚复杂度、隐性耦合——阻止 AI 拍脑袋决策 | 8-Item Proposal Review: self-rebuttals, dependency risk, rollback, coupling analysis |
| 🛡️ 推翻保护 | 冷却期 + PoC 门槛 + 量化对比——防止 Agent 之间反复横跳 | Decision Override Protection: cooling period + PoC threshold + quantified comparison |
| 📝 问题追踪 | 记录每个 Bug 的状态、尝试方案、结果——避免后人踩坑 | Issue Tracking Table: status, attempts, results per bug |
| 🔌 零依赖 | 纯 Markdown 文件，不需要服务器、数据库、API Key | Zero-Dependency: pure Markdown — no server, no DB, no API keys |
| 🔒 隐私优先 | 三道防线：初始化 .gitignore → 结束会话扫描 → 推送前检查，防止密钥/路径泄露 | Privacy-first: 3 defense lines — auto .gitignore at init, sensitive-file scan at end-session, pre-push check |
| 🌐 跨平台 | 适配任意支持 Agent Skills 标准的平台 | Cross-Platform: any platform supporting the Agent Skills standard |
| 维度 | CLAUDE.md | project-brain |
|---|---|---|
| 结构 Structure | 单层扁平 | 三层渐进披露 |
| 交接 Handoff | 一个 Agent 写，同一个 Agent 读 | 跨 Agent 交接清单 (✅ |
| 跨模型 Cross-model | ❌ 绑定单一生态 | ✅ 任意 LLM |
| 问题追踪 Issue tracking | ❌ 临时散落 | ✅ 结构化表格（状态+方案+结果） |
| 决策治理 Decision governance | ❌ 无审查规则 | ✅ 8 项提案审查 + 推翻保护 |
| 触发方式 Triggers | ❌ 手动编辑 | ✅ 关键词触发（"结束会话""记录问题"等） |
| 依赖 Dependencies | 无 | 无（和 CLAUDE.md 一样，纯 Markdown） |
CLAUDE.md 是个人笔记。project-brain 是团队记忆。
CLAUDE.md is personal memory. project-brain is team memory.
AI 助手会自动生成含密钥/路径的配置文件。project-brain 在三个节点保护你：
| ③ 三道防线 | 时机 | 做什么 |
|---|---|---|
| ① 初始化 | 开始新项目 | 自动询问"要开源吗？" → 生成含 7 类 AI 敏感文件的 .gitignore |
| ② 收工 | 结束会话 | 扫描 git diff 发现敏感文件 → 高亮警告 |
| ③ 推送 | 公开前 | git ls-files 扫描 → 匹配到敏感文件立即阻止 |
💡 可选 pre-commit 钩子：任何
git commit自动扫描，发现.claude/或.mcp.json直接拒绝提交。
详细敏感文件清单和清理指南
# AI agent config
CLAUDE.md .claude/ .mcp.json .codex/ .cursor/ .clinerules/
# Agent memory
memory/
# Dev credentials
.env .env.local credentials.json *.pem .npmrc .pypirc已提交过敏感文件？git filter-repo 或 BFG Repo-Cleaner 清理历史。
完整使用说明书（14 章 + 7 附录，含模板全文、GLM5 审查详情、FAQ 等）：📖 docs/
Full documentation (14 chapters + 7 appendices) available in 📖 docs/.
方式 A：一行命令（推荐）
npx skills add HuaKaiBuChangWu/project-brain -g -y全局安装到 Claude Code、Codex、Cursor、OpenCode 等 49+ Agent。
One-command install for Claude Code, Codex, Cursor, OpenCode, and 49+ other agents.
方式 B：手动安装（所有平台通用）
git clone https://github.com/HuaKaiBuChangWu/project-brain.git
# 复制到 Skills 目录:
# CherryStudio Windows: %APPDATA%/CherryStudio/Data/Skills/project-brain/
# CherryStudio macOS: ~/Library/Application Support/CherryStudio/Data/Skills/project-brain/
# CherryStudio Linux: ~/.config/CherryStudio/Data/Skills/project-brain/
# Claude Code: ~/.claude/skills/project-brain/
# Codex: ~/.codex/skills/project-brain/告诉 AI 助手你的公共工作空间路径，并复制模板：
我的公共工作空间在
~/public_workspace
cp templates/*.md ~/public_workspace/_system/Tell your AI assistant: "My shared workspace is at ~/public_workspace"
| 你想做什么 | 说什么 | Say this (EN) |
|---|---|---|
| 开始新项目 | "开始新项目" | "Start new project" |
| 继续已有项目 | "查看项目" | "View project" |
| 结束当天工作 | "结束会话" | "End session" |
| 记录一个 Bug | "记录问题" | "Record issue" |
| 更新项目状态 | "更新项目状态" | "Update project status" |
- 新项目 →
开始新项目→ 8 轮问答 → 自动生成入口文件 - 每天开工 →
查看项目→ Agent 自动读上下文，无需解释背景 - 收工 →
结束会话→ 生成交接清单 ✅⚠️ 🔒📌，下一个 Agent 秒懂 - 换 Agent → 重复步骤 2，无缝继续
New →
Start project→ 8 Q&A → auto-gen entry file. Resume →View project→ context auto-loaded. Done →End session→ handoff checklist. Switch agents → repeat.
<workspace>/
├── _tools/ ← Shared utility scripts
├── _patterns/ ← Reusable code patterns
├── _system/ 或 _系统/ ← 全局记录（目录名自行决定，告知 Agent 即可）
│ └── 会话日志.md ← 所有项目会话日志
├── <项目A>/
│ ├── 项目入口.md ← 3层渐进式入口文件
│ └── 问题追踪.md ← Bug 追踪表
└── <项目B>/
└── ...
| 平台 | 自动触发 Skill | 说明 |
|---|---|---|
| Claude Code | ✅ | 原生支持，description 关键词自动匹配 |
| CherryStudio + Claude | ✅ | CherryStudio 调用 Claude Code CLI，skill 自动注入 |
| CherryStudio + 其他模型 | 需检查模型设置中是否开启了该 Skill。非 Claude 模型走 API 直连，skill 不会自动注入到系统提示词 | |
| OpenAI Codex CLI | ✅ | 支持 Agent Skills 标准 |
| Cursor | ✅ | 支持 Agent Skills 标准 |
| OpenCode | ✅ | 支持 Agent Skills 标准 |
⚠️ CherryStudio 用户注意：如果换了非 Claude 的模型后发现 skill 没触发，去 CherryStudio 该模型的「能力/Capabilities」设置里确认 skill 开关已打开。
⚠️ CherryStudio users: If you switch to a non-Claude model and the skill doesn't trigger, check that the skill is enabled in that model's Capabilities settings.
Q: 会话记录会自动保存吗？ / Auto-save?
中文：不会。你必须手动说"结束会话"。AI 无法自动检测你何时结束工作。
ENG: No. You must say "End session" to trigger logging. AI cannot detect when you're done.
Q: 换了 AI 模型，新助手能看懂吗？ / Cross-model readable?
中文：能。所有记录都是标准 Markdown 文件，任何 AI 模型都能读取。
ENG: Yes. All records are standard Markdown files — any AI model can read them.
Q: 需要联网吗？ / Internet required?
中文：不需要。纯本地文件操作，完全离线可用。
ENG: No. Pure local file operations — fully offline.
Q: 两个 AI 能同时操作同一项目吗？ / Concurrent agents?
中文：不推荐。没有文件锁机制。建议一个时段只用一个助手，结束会话后再切换。
ENG: Not recommended. Use one assistant at a time, end session, then switch.
Q: 能自定义模板吗？ / Customizable?
中文：当然可以。模板在 templates/ 目录下，随意修改或让 Agent 按你的团队风格适配。
ENG: Absolutely. Edit templates/ freely or let an agent adapt them to your team.
Q: 和 CLAUDE.md / AGENTS.md 有什么不同？
中文：CLAUDE.md 是静态的——一个 Agent 写，同一个 Agent 读。project-brain 增加了分层结构、跨 Agent 交接清单、问题追踪、决策治理，适配任意 LLM。简单说：CLAUDE.md 是个人笔记本，project-brain 是团队看板。
ENG: CLAUDE.md is static — one agent writes, that agent reads. project-brain adds structured layers, cross-agent handoff checklists, issue tracking, and decision governance that work across any LLM. Think of it as CLAUDE.md with team scaffolding.
Q: 我说了触发词但 Agent 没反应？ / Skill not triggering?
中文：Skill 的自动触发依赖平台支持。Claude Code 原生支持 description 关键词匹配；CherryStudio 里如果换了非 Claude 模型（如 GLM、Kimi），需要在模型设置里手动开启该 Skill。如果还是没反应，直接说"请按 project-brain 的流程操作"。
ENG: Auto-trigger depends on platform support. Claude Code matches description keywords natively. In CherryStudio with non-Claude models (GLM, Kimi), enable the skill in model settings. Fallback: say "Follow project-brain workflow."
欢迎提 Issue 和 PR！觉得有用请 ⭐ Star。
- 发现 Bug 或有新想法？提交 Issue
- 想改进模板或添加翻译？PR 随时欢迎
- 用 project-brain 做了什么？分享出来，我们乐意展示社区项目
Issues and PRs welcome! If you find this useful, please ⭐ Star this repo. Found a bug? Open an issue. PRs always welcome.
MIT © 2026 HuaKaiBuChangWu