Srujan-Amaragatti05/project-brain

# 🧠 project-brain       [](https://project-brain-i2fdcj9qr-srujan-amaragatti05s-projects.vercel.app/)  ## 🚀 什么是 project-brain？ `project-brain` 是一款 CLI 优先的开发者智能工具，专为分析代码库、在函数级别跟踪 Git 变更、为 AI 系统生成结构化导出以及使用可选的 LLM 集成解释代码变更而构建。 与在原始行差异上运行的传统 Git 工具不同，project-brain 使用基于 AST 的解析来理解代码结构，并生成对开发者友好的洞察。 该项目围绕**本地优先**、**注重隐私**和 **AI 可选**的工作流进行设计。 # 🎯 为什么存在 project-brain 现代开发工作流面临以下几个问题： ### Git diffs 噪音过多 传统的 diff 显示的是行变更，而不是语义。 一次小重构可能会产生大量 diff，同时隐藏了实际的行为影响。 ### 代码库变得难以理解 庞大的代码库通常包含： * 深度嵌套的模块 * 重复的逻辑 * 不清晰的所有权 * 隐藏的依赖关系 手动理解它们非常耗时。 ### AI 工具需要结构化上下文 大多数 AI 系统在接收原始代码库时表现不佳。 project-brain 会创建： * 结构化的导出 * 聚焦的变更集 * 函数级别的智能信息 * 对 AI 友好的上下文 ### 本地优先工具很重要 许多开发者不希望： * 自动上传代码 * 依赖云服务 * 供应商锁定 project-brain 在以下情况完全离线工作： ``` llm: provider: none ``` # ✨ 功能特性 ## 已实现 * 🔍 递归代码库扫描 * 🧠 基于 AST 的 Python 分析 * 🧩 函数提取 * 🏛️ 类提取 * 🔄 Git diff 解析 * 📌 函数级别变更追踪 * 📦 对 AI 友好的代码导出系统 * 🤖 可选的 LLM 解释 * 💾 解释缓存 * 🌐 HTML diff 报告 * ⚠️ 配置校验 * 🩺 环境诊断 * 🪵 持久化日志 * 🚫 跳过二进制文件 * 🛡️ 无效 Python 文件的安全处理 * ⚡ 深度目录遍历 # 🏗️ 架构概览 project-brain 由独立的模块结构组成。 ``` CLI Layer │ ├── Analyzer ├── Diff Engine ├── Explain Engine ├── Export Engine ├── Doctor / Diagnostics ├── Config Validation ├── Logging System └── LLM Provider Layer ``` ## 🔍 分析器 负责： * 文件系统遍历 * AST 解析 * 元数据提取 * 文件哈希 * 提取函数/类 使用 Python `ast` 模块进行语义分析。 ## 🔄 Diff 引擎 负责： * Git diff 解析 * 追踪修改的文件 * 函数级别变更检测 * 比较提取出的函数 AST 主体 支持： * 新增文件 * 修改文件 * 删除文件 ## 🧠 Explain 引擎 负责： * 生成语义解释 * 生成结构化摘要 * LLM provider 集成 * 缓存解释结果 * AI 禁用时的回退行为 ## 📦 导出引擎 负责： * 导出整个代码库 * 仅导出变更代码 * 生成对 AI 友好的代码包 * 结构化文件聚合 ## 🤖 LLM Provider 层 支持： * OpenAI * Ollama * Gemini * HuggingFace Provider 抽象层包括： * 超时处理 * 模型列表 * 响应标准化 * 错误处理 ## 💾 缓存系统 解释结果缓存在： ``` .brain/cache/ ``` 这避免了对未更改的函数 diff 重复调用 LLM。 # ⚙️ 安装说明 ## 前置条件 * Python >= 3.10 * Git 已安装 * 可选： * Ollama * OpenAI API 访问权限 * Gemini API 访问权限 * HuggingFace API 访问权限 ## 从 PyPI 安装 ``` pip install project-brain-cli ``` ## 验证安装 ``` brain --version ``` ## 升级 ``` pip install --upgrade project-brain-cli ``` ## CLI 别名 以下两个命令均可使用： ``` brain ``` ``` project-brain ``` # ⚡ 快速开始 (30 秒) ## 1. 初始化 project-brain ``` brain project init ``` 创建： ``` .brain/ brain.yaml ``` ## 2. 分析代码库 ``` brain project analyze . ``` 执行： * 递归扫描 * AST 解析 * 元数据生成 将结果存储在： ``` .brain/data.json ``` ## 3. 检查 Git 变更 ``` brain diff show ``` 默认行为： ``` HEAD~1 → HEAD ``` 显示： * 修改的文件 * 新增的文件 * 删除的文件 * 函数级别的变更 ## 4. 导出 AI 友好的上下文 ``` brain export full_code ``` 创建： ``` .brain/exports/full_code.txt ``` ## 5. 访问社区资源 ``` brain community ``` 直接打开反馈/讨论页面： ``` brain --feedback ``` # 🧠 命令参考 # 📁 项目命令 ## `brain project init` 初始化 project-brain。 ### 语法 ``` brain project init ``` ### 作用 创建： * `.brain/` * `.brain/cache/` * `.brain/data.json` * `.brain/index.json` * `brain.yaml` ### 注意事项 * 现有文件将被保留 * 重复运行是安全的 ## `brain project analyze` 分析代码库结构。 ### 语法 ``` brain project analyze [path] ``` ### 参数 | 参数 | 默认值 | 描述 | | -------- | ------- | -------------- | | path | `.` | 根目录 | ### 内部行为 * 递归遍历目录 * 跳过忽略的路径 * 跳过二进制文件 * 可选跳过测试 * 提取： * 函数 * 类 * 哈希值 * 元数据 ### 输出 ``` .brain/data.json ``` ### 示例 ``` brain project analyze . ``` ### 边缘情况 * 无效的 Python 文件会被安全跳过 * 无法读取的文件不会导致分析崩溃 ## `brain project summary` 生成代码库摘要。 ### 语法 ``` brain project summary ``` ### 显示内容 * 文件总数 * 函数总数 * 类总数 * 按函数数量排名靠前的文件 * 检测到的架构提示 ### 输出模式 使用以下方式配置： ``` output: format: text ``` 支持： * text * json * markdown ## `brain project doctor` 运行全面的环境和代码库诊断。 ### 语法 ``` brain project doctor ``` ### 检查内容 #### 环境 * Python 安装/版本 * 操作系统信息 * 虚拟环境检测 * Git 安装情况 #### 代码库 * Git 仓库检测 * 当前分支 * 最新提交 * 仓库大小 #### 分析 * `.brain/` 初始化 * 分析数据库是否存在 * 已分析的文件数量 * 分析的新鲜度/陈旧度检测 #### 导出 * 导出目录可用性 * 完整代码导出是否存在 * 代码变更导出是否存在 #### LLM * 已配置的 provider * provider 状态 * 离线模式检测 ### 示例输出 ``` 🩺 Project Brain Diagnostics Environment ✔ Python 3.14 ✔ Virtual environment active ✔ Git installed Repository ✔ Git repository detected ✔ Branch: dev Analysis ✔ data.json exists ⚠ Analysis may be stale Exports ✔ Full code export available LLM ℹ Provider: none ℹ LLM disabled ``` ### 最终状态 | 状态 | 含义 | | --------- | ----------------------------------- | | READY | 代码库已完全配置 | | PARTIAL | 配置不完整，但可用 | | NOT READY | 缺少关键设置 | ### 注意事项 当出现以下情况时，会出现新鲜度警告： * 代码库变更可能与当前分析不匹配 * `data.json` 似乎已过时 建议刷新： ``` brain project analyze . ``` ### 备注 doctor 系统旨在： * 尽早检测出损坏的设置 * 验证开发者环境 * 减少 CLI/运行时故障 * 提高操作可靠性 # 🔄 Diff 命令 ## `brain diff show` 显示代码库变更。 ### 语法 ``` brain diff show [from_ref] [to_ref] ``` ### 默认行为 如果未提供引用： ``` brain diff show ``` 相当于： ``` brain diff show HEAD~1 HEAD ``` ### Git 引用说明 | 引用 | 含义 | | ------ | --------------------- | | HEAD | 当前提交 | | HEAD~1 | 上一次提交 | | HEAD~5 | HEAD 之前的 5 次提交 | ### 内部工作流 project-brain： 1. 验证 git refs 2. 运行 git diff 逻辑 3. 计算变更的文件 4. 提取 Python 函数 5. 比较函数体 ### 输出示例 ``` Files Changed: 2 Modified: * src/api.py Added: * src/utils.py Deleted: * src/legacy.py ``` ### 函数级别输出 ``` Functions Added: * validate_user Functions Modified: * create_user ``` ### 边缘情况 * 非 Python 文件仅接收文件级别的 diff * 无效的 git refs 会安全失败 * 非 Git 代码库将被拒绝 ## `brain diff review` 生成语义 diff 解释。 ### 语法 ``` brain diff review [from_ref] [to_ref] ``` ### 作用 * 计算 git diff * 提取变更的函数 * 构建 prompt * 调用 LLM provider * 缓存结果 * 生成报告 ### 输出 ``` .brain/reports/diff_.json .brain/reports/diff_.html ``` ### HTML 报告 交互式 HTML 报告包括： * 分组的文件 * 风险标签 * 语义摘要 * 影响描述 ### LLM 禁用模式 如果： ``` provider: none ``` project-brain 会生成基于启发式的回退摘要。 ## `brain diff explain` 解释文件或函数。 ### 语法 ``` brain diff explain ``` ### 文件示例 ``` brain diff explain src/api.py ``` ### 函数示例 ``` brain diff explain src/api.py:create_user ``` ### 行为 未使用 LLM 时： * 仅生成结构化摘要 使用 LLM 时： * 语义解释 * 风险评估 * 逻辑概述 # 📦 导出命令 ## `brain export full_code` 导出整个代码库。 ### 语法 ``` brain export full_code ``` ### 输出 ``` .brain/exports/full_code.txt ``` ### 导出格式 ``` === FILE: src/api.py === ``` ### 行为 * 递归扫描文件 * 遵循忽略规则 * 遵循文件大小限制 * 可选跳过测试 ## `brain export file` 手动导出单个文件。 ### 语法 ``` brain export file ``` ### 示例 ``` brain export file src/api.py ``` ## `brain export dir` 手动导出目录。 ### 语法 ``` brain export dir ``` ### 示例 ``` brain export dir src/ ``` ## `brain export code_changes` 导出两个引用之间的变更代码。 ### 语法 ``` brain export code_changes ``` ### 示例 ``` brain export code_changes HEAD~3 HEAD ``` ### 输出 ``` === FILE: src/api.py === --- FUNCTION: create_user (UPDATED) --- OLD: ... NEW: ... ``` # 🧪 LLM 命令 ## `brain testllm test` 测试 provider 连通性。 ### 语法 ``` brain testllm test ``` ### 作用 * 加载 provider 配置 * 发送测试 prompt * 验证响应 * 可选获取模型列表 ### 禁用模式 如果： ``` provider: none ``` 输出： ``` LLM disabled ``` # ⚙️ 配置 配置文件： ``` brain.yaml ``` # 示例配置 ``` version: "1.1.0" llm: provider: none model: "" timeout_sec: 60 analysis: depth: fast include_tests: false ignore: - .brain/ - .git/ - node_modules/ - venv/ - .venv/ - __pycache__/ - env/ - .env/ - project_brain_cli.egg-info/ - tests/ - test/ diff: mode: function export: full_code: include_tests: false max_file_size_kb: 200 manual_add: allow_duplicates: true changes: mode: function include_context: true output_path: .brain/exports/code_changes.txt ignore: - .brain/ - .git/ - node_modules/ - venv/ - .venv/ - __pycache__/ - env/ - .env/ - project_brain_cli.egg-info/ - tests/ - test/ explain: level: detailed include_risks: true output: format: text ``` # 🔑 API 密钥设置 密钥绝不应存储在 `brain.yaml` 中。 ## Windows CMD ``` setx OPENAI_API_KEY "your_key" ``` ``` setx GEMINI_API_KEY "your_key" ``` ``` setx HUGGINGFACE_API_KEY "your_key" ``` ## PowerShell ``` [Environment]::SetEnvironmentVariable("OPENAI_API_KEY","your_key","User") ``` ## Linux/macOS ``` export OPENAI_API_KEY="your_key" ``` # 📴 离线模式 project-brain 完全支持离线工作流。 使用： ``` llm: provider: none ``` 行为： * 无 API 调用 * 不依赖云服务 * 仅限本地分析 * 启用回退解释 # 📄 示例输出 ## 分析 ``` 🔍 Analyzing: . 📋 File Paths: src/api.py src/utils.py ✅ Analysis complete ``` ## Diff 审查 ``` Function: create_user Change: Added validation layer Impact: Improves input integrity Risk: medium ``` # 📁 项目结构 ``` project-brain/ │ ├── src/ │ └── project_brain/ │ ├── cli.py │ ├── core/ │ ├── llm/ │ ├── storage/ │ └── config/ │ ├── tests/ ├── brain.yaml ├── pyproject.toml └── README.md ``` # 🪵 日志系统 日志存储在： ``` .brain/logs.txt ``` 跟踪： * 警告 * provider 故障 * 解析错误 * 导出失败 * 缓存问题 日志失败永远不会导致 CLI 崩溃。 # 🛠️ 故障排除## ❌ 不是 Git 仓库 初始化 git： ``` git init ``` ## ❌ 无效的 Git 引用 检查引用： ``` git log --oneline ``` ## ❌ 空导出 可能的原因： * 路径被忽略 * 文件大小限制 * 测试被排除 ## ❌ Provider 故障 检查： * API 密钥 * 网络连接 * provider 模型名称 ## ❌ 缺少 API 密钥 验证环境变量： ``` echo %OPENAI_API_KEY% ``` # 🧪 测试与 QA 当前 QA 状态： * 18 个自动化测试通过 * 导出验证 * 函数 diff 验证 * 配置验证 * 边缘情况处理 * provider 回退测试 # 🌍 社区与反馈 project-brain 包含内置的社区工作流，以简化反馈和贡献者互动。 ## 打开反馈页面 ``` brain --feedback ``` 行为： * 打开 GitHub Discussions 页面 * 如果浏览器启动失败，回退打印 URL ## 社区资源 ``` brain community ``` 显示： * GitHub 仓库 * PyPI 包 * Discussions * Issues * 文档链接 ## GitHub Discussions 使用 Discussions 进行： * 功能想法 * 工作流讨论 * 故障排除 * 集成 * 反馈 仓库： [project-brain GitHub 仓库](https://github.com/Srujan-Amaragatti05/project-brain?utm_source=chatgpt.com) Discussions： [project-brain Discussions](https://github.com/Srujan-Amaragatti05/project-brain/discussions?utm_source=chatgpt.com) PyPI： [PyPI 上的 project-brain-cli](https://pypi.org/project/project-brain-cli/?utm_source=chatgpt.com) # 🔮 路线图 ## 近期计划 * 语义 diff 智能分析 * 集成测试 * 增量分析 * 性能提升 * 重命名检测 ## 中期计划 * 多语言解析 * 插件架构 * 依赖关系图 * 更丰富的语义索引 # 🔐 安全与隐私 project-brain 采用本地优先的理念设计。 核心原则： * 无自动代码上传 * 支持离线工作流 * API 密钥仅通过环境变量提供 * 代码库数据本地存储 LLM 的使用完全是可选的。 # 🤝 贡献 欢迎贡献。 推荐工作流： ``` git checkout -b feature/my-feature ``` 准则： * 保持 PR 聚焦 * 保持 CLI 一致性 * 为新逻辑添加测试 * 避免不必要的依赖 # 📜 许可证 MIT License # 🧠 最终定位

标签：AI辅助开发, AI风险缓解, C2, DLL 劫持, Git, LLM集成, odt, Python, SOC Prime, 上下文提取, 云安全监控, 代码仓库管理, 代码分析, 代码审查, 代码理解, 代码结构化, 凭证管理, 大语言模型, 工程效率, 差异对比, 开发工具, 开发效率, 开发者智能, 开源, 抽象语法树, 数据管道, 文档生成, 文档结构分析, 无后门, 本地优先, 网络可观测性, 网络安全, 网络安全研究, 网络调试, 自动化, 自动化payload嵌入, 软件工程, 逆向工具, 重构分析, 隐私保护, 静态分析