Frankie08180914/vcd

## VCD 是什么 VCD（Vibe Coding Decoder）是一套面向 Vibe Coding 创作者的本地项目理解系统。 当一个项目经历多轮 AI 生成和修改后，创作者往往只知道“它现在能运行”，却很难继续回答： - 这个项目实际上由哪些页面、功能、路由和数据组成？ - 某个功能由哪些文件、组件、函数或代码符号共同实现？ - 修改一处代码可能影响哪些产品能力？ - 哪些结论能够被代码证明，哪些只是文档描述或 AI 推测？ - 项目距离上线还缺少什么？ - 怎样把项目完整交给另一个 AI 或开发者继续维护？ VCD 会先在浏览器中完成确定性扫描，建立文件、符号、路由、依赖和配置证据；用户主动调用 AI 后，再基于这些证据生成项目理解报告、代码解释、接管文件及部署建议。 ## 核心能力 ### 1. 多种项目输入方式 - 单个文件 - 多个文件 - ZIP 项目 - 本地项目目录 - 浏览器拖拽文件或目录 VCD 会登记全部可见文件；可读取的文本文件进入结构分析，二进制文件、未知文件和超大文本文件保留路径、类型与大小等元数据。 ### 2. 浏览器本地确定性扫描 不依赖 AI 即可生成： - 项目文件树 - 文件类型与语言统计 - 依赖和构建配置 - 函数、类、React 组件与代码符号 - 页面、路由与导航关系 - API、数据库和部署相关线索 - 导入关系与结构证据 - 疑似未完成内容和静态风险提示 VCD **不会执行上传项目中的脚本**。 ### 3. Evidence Index VCD 会把项目中的重要线索整理为可引用的证据索引，包括： - 文件证据 - 代码符号证据 - 路由和页面证据 - 数据库证据 - 部署与环境变量证据 - 文档证据 - 疑似未完成证据 AI 生成的重要结论会引用 Evidence ID。点击证据可以回到对应文件和代码位置，而不是只得到一段无法核验的总结。 ### 4. AI 项目理解报告 在完成本地扫描后，可选择 OpenAI、Claude 或 DeepSeek 生成结构化报告，包括： - 项目是做什么的 - 产品目标 - 目标用户 - 当前完成程度 - 已实现、疑似实现和无法确认的功能 - 产品使用流程 - 数据库与数据操作 - 部署方式与环境配置 - 上线准备检查 - 功能相关代码一览 - 仍然无法确认的问题 上线准备检查会把问题划分为： - 阻止上线 - 高风险 - 建议优化 - 暂不处理 静态检查不会被描述成真实运行测试。 ### 5. 功能到代码的导航 VCD 不只按文件解释代码，也会尝试以产品功能为中心整理： - 实现状态 - 静态健康程度 - 复杂度 - 修改风险 - 相关文件 - 相关组件、函数与代码符号 用户可以从功能结论跳回源代码，再针对文件或代码符号生成面向非技术创作者的 AI 解释。 ### 6. 项目工作区与版本记忆 分析结果保存在当前浏览器的 IndexedDB 中。 - 独立保存单次分析 - 创建项目文件夹 - 将同一产品保存为 V1、V2、V3 等版本 - 保留旧版本报告、接管文件和部署方案 - 上传新版本后继续比较和迭代 - 清除单个项目或全部本地记录 ### 7. AI 项目接管文件 完成项目理解报告后，可以生成 Markdown 接管资料，用于交给： - ChatGPT - Claude - Cursor - 新的技术合作者或开发者 接管文件会继承已有报告中的事实边界、完成状态和证据路径，而不是重新生成一套互相冲突的项目判断。 ### 8. 部署与收费方案 当上线准备检查不存在阻止项时，可以基于当前报告生成： - 推荐部署形态 - 实施步骤 - 环境变量和配置 - 上线验证 - 备份与回滚 - 免费与收费边界 - 收费方式建议 - 首批用户验证路径 该功能生成的是基于代码证据的建议，不会替代实际部署、合规检查或商业决策。 ### 9. 微信小程序专项分析 当项目中识别到足够的微信小程序结构时，可启用专项分析，重新组织： - `app.json` 与全局配置 - 页面和配套文件 - WXML / WXSS / WXS - 页面导航关系 - `wx.*` 平台能力 - 云函数、网络请求与后端线索 - 权限与隐私能力 - 小程序专项风险与缺口 ## 工作流程 上传文件 / ZIP / 本地目录 ↓ 浏览器本地读取与确定性扫描 ↓ 建立文件树、代码符号和 Evidence Index ↓ 保存为独立报告或项目版本 ↓ 可选：调用 OpenAI / Claude / DeepSeek ↓ 项目理解报告 → 代码解释 → 接管文件 → 部署与收费方案 ## 技术架构 | 层级 | 实现 | | --- | --- | | 前端 | React 19、React Router、Vite | | 代码与结构解析 | `@babel/parser`、自定义静态分析器 | | ZIP 处理 | JSZip | | 本地数据 | Browser IndexedDB | | 本地 AI 网关 | Node.js HTTP Server | | AI 接入 | OpenAI Responses API、Anthropic Messages API、DeepSeek Chat Completions API | | 动效与视觉 | GSAP、OGL、Lucide React | ## 项目结构 VCD/ ├─ public/ # 图标等静态资源 ├─ scripts/ │ └─ dev.mjs # 同时启动 Vite 与本地 AI 服务 ├─ server/ │ ├─ index.mjs # 本地 AI HTTP 服务 │ ├─ providerRouter.mjs # OpenAI / Claude / DeepSeek 适配 │ ├─ prompts.mjs # 报告、接管、部署等提示约束 │ ├─ schemas.mjs # 结构化输出 Schema │ ├─ validation.mjs # Evidence 引用校验 │ └─ httpClient.mjs # API 请求与代理处理 ├─ src/ │ ├─ components/ # UI、报告与 AI 组件 │ ├─ context/ # 全局 UI 状态 │ ├─ pages/ # 首页、工作区、版本与报告页面 │ ├─ services/ # AI 服务与 IndexedDB 项目存储 │ ├─ styles/ # 全局样式 │ └─ utils/ # 上传、文件识别、项目分析与证据构建 ├─ .env.example # AI 配置模板，不包含真实 Key ├─ package.json ├─ package-lock.json └─ vite.config.js ## 本地运行 ### 环境要求 - 推荐 Node.js 22.12 或更高版本 - npm - Edge 或 Chrome 等现代浏览器 ### 1. 安装依赖 npm ci ### 2. 创建本地 AI 配置 Windows PowerShell： Copy-Item .env.example .env macOS / Linux： cp .env.example .env ### 3. 配置至少一个 AI 提供商 编辑根目录的 `.env`： # OpenAI OPENAI_API_KEY= OPENAI_MODEL=gpt-5.6-terra # Anthropic Claude ANTHROPIC_API_KEY= ANTHROPIC_MODEL=claude-sonnet-5 # DeepSeek DEEPSEEK_API_KEY= DEEPSEEK_MODEL=deepseek-v4-flash AI_SERVER_PORT=8787 只需要填写你准备使用的提供商。其他 Key 可以保持为空。 模型名称可以根据你的 API 账户权限进行替换。不要把真实 `.env`、API Key、Token 或密钥截图提交到 Git。 ### 4. 启动 VCD npm run dev 该命令会同时启动： - VCD 页面：`http://127.0.0.1:5173/` - 本地 AI 服务：`http://127.0.0.1:8787/` 没有配置 API Key 时，VCD 仍可完成本地确定性扫描和项目存储；AI 报告、AI 代码解释、接管文件与部署方案不可用。 ## 可用命令 | 命令 | 作用 | | --- | --- | | `npm run dev` | 同时启动前端与本地 AI 服务 | | `npm run dev:web` | 只启动 Vite 前端 | | `npm run server` | 只启动本地 AI 服务 | | `npm run build` | 构建生产前端资源 | | `npm run preview` | 本地预览构建结果 | ## 当前处理限制 | 项目 | 当前上限 | | --- | --- | | 单次输入总大小 | 20 MB | | ZIP 解压后总大小 | 80 MB | | 项目文件数量 | 5,000 个 | | 单个文本文件读取 | 2 MB；超过后只登记元数据 | | 本地 AI 请求体 | 2 MB | VCD 会自动跳过 `.git`、`.idea`、`node_modules`、`dist`、`build`、缓存目录及识别到的 Python 虚拟环境目录。 ## 隐私与安全 - 基础结构扫描在浏览器本地完成。 - VCD 不执行上传项目中的代码或脚本。 - 本地 AI 服务仅监听 `127.0.0.1`。 - API Key 由本地 Node.js 服务读取，不会写入浏览器前端。 - 分析项目、可读取源码和生成结果会保存在当前浏览器的 IndexedDB 中。 - 只有用户主动生成 AI 报告、代码解释、接管文件或部署方案时，相关的结构化证据和代码片段才会发送给所选择的 AI 提供商。 - 调用第三方 AI API 可能产生费用，费用由对应 API 账户承担。 ## 当前边界 - VCD 的扫描结果来自静态文件与语法分析，不等同于真实运行、集成测试或渗透测试。 - AI 报告依赖当前上传范围、证据质量、模型能力和 API 可用性。 - “未发现证据”不等于“功能确定不存在”。 - VCD 当前是 Local-first 工具，不是带账户、团队协作和云端托管能力的 SaaS。 - VCD 不会自动修复项目，也不会自动完成部署。 ## License status VCD 自有代码尚未选择最终的项目级许可证。除仓库内第三方代码和依赖各自适用的许可证外，当前未通过 `LICENSE` 文件授予额外的复制、修改、分发或商业使用权限。 在正式选择许可证前，本仓库应被理解为 **公开展示源代码，而不是已经完成标准开源授权**。

标签：MITM代理, React, SOC Prime, Syscalls, Vibe Coding, 云安全监控, 代码地图, 代码理解, 开发工具, 自定义脚本, 静态分析