VCD_README_PRODUCT_FIRST.md

VCD

Vibe Coding Design

Understand what was built. Regain control. Prepare it for the real world.

面向 Vibe Coding 与陌生代码项目的本地项目理解、证据分析与接管平台。

为什么选择 VCD · 核心能力 · 部署与商业化 · 下载与启动 · 社区讨论 · 报告问题

VCD（Vibe Coding Design） 是一个以项目全局和可核验证据为核心的代码理解系统。

它最初为 Vibe Coding 创作者而设计。现在已经有很多人可以借助 AI 做出网站、小程序或应用，但一个“能在自己电脑上运行”的作品，距离真正可以交付、上线和获利，通常仍有很长一段路：

• 页面存在，不代表业务逻辑已经完成；
• 按钮可点击，不代表数据真的被保存；
• 本地能运行，不代表具备生产环境配置；
• AI 能继续修改，不代表用户知道修改会影响哪里；
• 有一个产品想法，不代表当前代码已经具备收费条件。

VCD 希望帮助用户从：

“我用 AI 做出了一个能运行的原型。”

走向：

“我真正理解、控制并准备好发布这个产品。”

VCD 从 Vibe Coding 的问题出发，但并不局限于 Vibe Coding。它也适用于任何需要快速理解、评估、接手或交付陌生代码项目的场景。

VCD transforms unfamiliar, complex, or AI-generated codebases into understandable, traceable, and actionable project context.

ChatGPT、Codex、Claude、Cursor 等工具非常擅长回答问题和修改代码。

但通用 AI 的答案通常从用户提供的描述和当前对话上下文开始。

例如：

“我做了一个饮食管理网站，应该怎样部署和赚钱？”

AI 可以快速建议订阅、广告、企业合作或云服务器。但它未必真正知道：

• 项目是否存在真实的用户系统；
• 登录是否只是一个静态页面；
• 数据是否写入数据库；
• 后端接口是否真实存在；
• 是否仍在使用模拟数据；
• 环境变量和生产配置是否完整；
• 当前架构能否支持多个真实用户；
• 哪些问题会直接阻止上线；
• 项目当前是否已经具备收费所需的账户、权限、支付或额度能力。

General AI begins with the context you provide.
VCD first builds context from the project itself.

VCD 先扫描用户上传项目的文件、目录、配置、路由、代码符号、接口、数据和部署线索，建立结构化的事实层与 Evidence Index；随后 AI 才在这些证据和报告基础上生成项目理解、接管资料、上线检查、部署路线与收费建议。

VCD 不是把“整个项目”当作一段模糊 Prompt，而是把它整理为一个可以持续保存、核验和交接的项目上下文。

VCD 不试图取代通用 AI。

VCD：理解、组织、保存并证明项目事实
其他 AI：基于这些事实继续修改和开发

文件 / ZIP / 本地目录
          ↓
浏览器本地读取与确定性扫描
          ↓
文件树、代码符号、路由、API、数据与 Evidence Index
          ↓
代码事实 / 文档事实 / AI 推测 / 无法确认
          ↓
AI 项目理解报告
          ↓
项目接管文件
          ↓
上线准备检查
          ↓
部署路线与收费建议

VCD 会登记项目中的全部可见文件。支持读取的文本文件会进入结构分析；超大文本文件和二进制文件只登记路径、类型与大小。

它不会执行用户上传项目中的代码或脚本。

VCD 不只告诉用户“项目用了 React、有多少个文件”，还会尝试恢复：

• 项目用途与产品目标；
• 目标用户；
• 已实现、疑似部分实现和无法确认的功能；
• 页面、路由与核心使用流程；
• API、数据库与外部服务；
• 技术栈、部署线索和完成程度。

VCD 将分析结果分为：

重要结论会尽可能绑定文件路径、组件、函数、路由、配置项、Evidence ID 和相关代码位置。

“没有发现证据”不会被写成“确定不存在”。

VCD 尝试以产品功能为中心整理：

• 功能状态；
• 相关文件；
• 组件、函数与代码符号；
• 静态健康程度；
• 复杂度和修改风险；
• 对应证据。

用户可以从产品结论回到源代码，并针对文件或符号生成面向非技术用户的解释。

分析结果保存在当前浏览器的 IndexedDB 中，可以：

• 保存独立分析；
• 创建项目文件夹；
• 将同一产品保存为 V1、V2、V3 等版本；
• 保留旧版本报告、接管文件和部署方案；
• 上传新版本后继续分析；
• 清除单个项目或全部本地记录。

完成项目理解报告后，VCD 可以生成 Markdown 接管资料，用于交给：

• ChatGPT；
• Claude；
• Cursor；
• Codex；
• 新的开发者或技术合作者。

接管文件继承原报告中的完成状态、证据路径和“无法确认”边界，不会在第二阶段重新推断一套相互矛盾的项目结论。

部署与商业化是 VCD 的核心差异之一，但它们不是脱离代码的点子生成器。

VCD 会先建立项目理解报告，检查：

• 当前真实实现的功能；
• 页面、路由和业务流程；
• API、数据库与数据操作；
• 环境变量和外部服务；
• 构建、启动与部署配置；
• 上线阻断项和高风险问题；
• 当前真正可以交付给用户的能力。

只有在项目理解和上线准备检查完成后，VCD 才会基于现有报告生成完整部署与收费方案。

当前实现中，如果报告发现 阻止上线 的问题，部署与收费方案入口会被阻止，提示用户先修复并重新上传检查，而不是跳过风险直接给出一份看似完整的上线方案。

VCD 将问题分为：

• 阻止上线
• 高风险
• 建议优化
• 暂不处理

这样用户既不会因为追求完美架构无限延期，也不会把真正影响上线的问题当成普通优化。

• 当前是否具备上线基础；
• 推荐的部署形态与替代方案；
• 前端、后端、数据库和文件存储安排；
• 环境变量、域名、HTTPS 与 CORS；
• 可能需要修改的文件和模块；
• 上线实施顺序；
• 验证、备份和回滚；
• 维护难度与主要成本来源。

• 最可能付费的用户是谁；
• 用户真正购买的结果是什么；
• 免费能力与收费能力如何划分；
• 按次、订阅或服务制的适配程度；
• 套餐和使用限制的初步思路；
• AI、服务器和存储等成本来源；
• 可能影响毛利的风险；
• 首批真实用户的验证方式；
• 当前阶段不值得过早开发的复杂能力。

VCD 给出的不是：

“你做了一个某类网站，这里有十个赚钱方法。”

而是：

“根据你上传项目当前真实具备的功能、技术结构、证据和缺失部分，下面是更符合这个项目实际状态的部署路径与商业化方向。”

部署和商业化输出属于分析建议，不代表部署已经完成，也不保证任何收益。平台价格、法律合规、税务和商业决策仍需要用户自行核验。

Vibe Coding 是 VCD 最核心的起点，但项目理解与接管也适用于：

• 日常办公中快速了解突然收到的代码项目；
• 接手同事或离职员工留下的项目；
• 新成员熟悉团队代码库；
• 产品经理核对功能是否真实完成；
• 开发人员理解遗留项目；
• 检查外包团队实际交付了什么；
• 修改前了解相关文件和潜在影响；
• 在合作、继续开发或技术评估前建立项目概览；
• 上线前整理风险、缺失项和部署条件；
• 将陌生项目整理成可交给其他 AI 或开发者继续工作的资料。

• 单个文件；
• 多个文件；
• ZIP 项目；
• 本地项目目录；
• 浏览器拖拽文件或目录。

VCD 会自动跳过 .git、.idea、node_modules、dist、build、缓存目录和识别到的 Python 虚拟环境目录。

如果上面的产品能力和使用场景符合你的需求，可以按照下面的步骤在自己的电脑上运行 VCD。

VCD 当前是一个 Local-first 本地运行项目。下载后，所有程序都会运行在用户自己的电脑上。

用户不需要使用项目作者的 API Key。需要 AI 功能时，应在自己电脑的 .env 文件中填写自己的 OpenAI、Claude 或 DeepSeek API Key。

VCD 不提供共享 API Key。AI API 的调用费用由用户自己的提供商账户承担。

• Node.js ^20.19.0 或 >=22.12.0
• npm
• Edge、Chrome 或其他现代浏览器

建议使用 Node.js 22。

在终端中检查：

node -v
npm -v

如果系统提示找不到 node 或 npm，请先安装 Node.js，完成后关闭并重新打开终端。

在 GitHub 仓库页面点击：

Code → Download ZIP

解压下载的 ZIP，然后进入解压后的项目文件夹。

请确认当前文件夹中可以直接看到：

package.json
package-lock.json
src/
server/
public/
.env.example

不要在 ZIP 压缩包内部直接运行，也不要停留在多套一层的外部文件夹。

Windows：

打开项目文件夹，在空白处右键，选择“在终端中打开”或“在 PowerShell 中打开”。

macOS / Linux：

在 Terminal 中使用 cd 进入项目根目录。

判断是否进入正确位置：

dir

Windows 也可以使用：

Get-ChildItem

macOS / Linux 使用：

ls

列表中应当存在 package.json。

npm ci

首次安装需要下载依赖，耗时取决于网络环境。

已经安装 Git 的用户可以运行：

git clone https://github.com/Frankie08180914/vcd.git
cd vcd
npm ci

然后继续执行下面的 .env 配置和启动步骤。

VCD 仓库只包含安全模板：

.env.example

用户需要在本地复制一份并命名为：

.env

Copy-Item .env.example .env

copy .env.example .env

cp .env.example .env

.env 只保存在用户自己的电脑中，已经被 .gitignore 忽略。不要把它上传到 GitHub，不要公开截图，也不要发送给其他人。

如果使用 Windows 记事本手动创建文件，请确认文件名不是：

.env.txt

推荐直接使用上面的复制命令，避免扩展名错误。

用 VS Code、PyCharm、记事本或其他文本编辑器打开根目录中的 .env。

初始内容类似：

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.6-terra

ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=claude-sonnet-5

DEEPSEEK_API_KEY=
DEEPSEEK_MODEL=deepseek-v4-flash

AI_SERVER_PORT=8787

用户只需要配置准备使用的一个或多个提供商。

OPENAI_API_KEY=在这里填写你自己的_OpenAI_API_Key
OPENAI_MODEL=gpt-5.6-terra

ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=claude-sonnet-5

DEEPSEEK_API_KEY=
DEEPSEEK_MODEL=deepseek-v4-flash

AI_SERVER_PORT=8787

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.6-terra

ANTHROPIC_API_KEY=在这里填写你自己的_Anthropic_API_Key
ANTHROPIC_MODEL=claude-sonnet-5

DEEPSEEK_API_KEY=
DEEPSEEK_MODEL=deepseek-v4-flash

AI_SERVER_PORT=8787

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.6-terra

ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=claude-sonnet-5

DEEPSEEK_API_KEY=在这里填写你自己的_DeepSeek_API_Key
DEEPSEEK_MODEL=deepseek-v4-flash

AI_SERVER_PORT=8787

注意：

• API Key 来自用户自己的 AI 提供商账户；
• 通常不需要在 Key 外面添加引号；
• 不要在等号前后添加多余空格；
• 不使用的提供商保持空值即可；
• 模型名称需要与用户 API 账户实际可用的模型一致；
• API 请求可能产生费用，请查看对应提供商账户的计费和额度；
• 修改 .env 后，如果 VCD 已经运行，请停止并重新启动。

在项目根目录执行：

npm run dev

该命令会同时启动：

• VCD 前端：http://127.0.0.1:5173/
• 本地 AI 服务：http://127.0.0.1:8787/

如果浏览器没有自动打开，请手动访问：

http://127.0.0.1:5173/

终端需要在 VCD 使用期间保持打开。

停止 VCD：

Ctrl + C

1. 启动 VCD；
2. 点击“上传内容”；
3. 上传一个安全的项目 ZIP 或选择本地目录；
4. 查看文件树、技术栈、代码符号、路由、API 线索和 Evidence Index；
5. 将结果保存到项目工作区。

1. 完成本地扫描；
2. 在报告页面选择已经配置的 AI 提供商；
3. 生成 AI 项目理解报告；
4. 查看代码事实、文档事实、AI 推测和无法确认；
5. 在完整报告基础上生成项目接管文件；
6. 通过上线准备检查后，再生成部署与收费方案。

Node.js 尚未安装，或安装后终端没有重新打开。安装符合版本要求的 Node.js 后重新打开终端。

确认：

• .env 位于包含 package.json 的项目根目录；
• 文件名确实是 .env，不是 .env.txt；
• Key 填写在对应提供商变量后；
• 修改后已经重新运行 npm run dev。

先关闭其他正在运行的 VCD、Vite 或 Node 进程，再重新执行：

npm run dev

检查：

• API Key 是否有效；
• API 账户是否有可用额度；
• 当前模型名称是否在账户中可用；
• 网络或代理是否允许访问对应 AI 服务；
• 终端中的具体错误信息。

不必须。第一次体验建议使用不含密钥、私人数据和真实用户信息的测试项目。

VCD/
├─ public/                  # 静态资源
├─ docs/media/              # README 产品截图
├─ scripts/dev.mjs          # 同时启动前端和本地 AI 服务
├─ server/                  # AI 网关、Prompt、Schema 与引用校验
├─ src/components/          # UI、报告与 AI 组件
├─ src/pages/               # 首页、工作区、版本和报告页面
├─ src/services/            # AI 服务与 IndexedDB 项目存储
├─ src/utils/               # 上传、文件识别、项目分析与证据构建
├─ .env.example
├─ package.json
└─ vite.config.js

• 基础结构扫描在浏览器本地完成；
• VCD 不执行上传项目中的代码或脚本；
• 本地 AI 服务仅监听 127.0.0.1；
• API Key 由本地 Node.js 服务读取，不会写入浏览器前端；
• 分析项目、可读取源码和生成结果会保存在当前浏览器的 IndexedDB 中；
• 只有用户主动调用 AI 功能时，相关结构化证据和代码片段才会发送给所选择的 AI 提供商；
• 第三方 AI API 费用由对应 API 账户承担。

安全提醒： 分析真实项目之前，请先移除或替换 .env、私钥、Token、证书、云服务凭据和真实用户数据。当前版本不能保证自动识别并脱敏所有秘密信息。

• 扫描结果来自静态文件和语法分析，不等同于真实运行测试、集成测试、性能测试或渗透测试；
• AI 报告依赖上传范围、证据质量、模型能力和 API 可用性；
• “当前未发现证据”不等于“功能确定不存在”；
• 当前是 Local-first 工具，不是带账户、团队协作和云端托管能力的 SaaS；
• VCD 不会自动修复项目，也不会自动完成部署；
• 更完整的修改前影响包、修改前后差异对比和跨版本健康变化仍属于后续方向。

VCD 自有代码尚未选择最终的项目级许可证。

除仓库内第三方代码和依赖各自适用的许可证外，当前未通过 LICENSE 文件授予额外的复制、修改、分发或商业使用权限。

当前仓库应被理解为：

公开展示源代码，而不是已经完成标准开源授权。

如果 VCD 帮助你理解、接管或重新评估了一份代码项目，欢迎为仓库点一个 Star，以便关注后续版本。

• 在 Discussions 分享使用体验、想法和项目场景；
• 在 Issues 报告可以复现的错误和明确的功能需求。

欢迎反馈：

• 你分析了什么类型的项目；
• VCD 是否正确理解了项目；
• 哪些结论最有价值或不够准确；
• 安装、启动或 API 配置中遇到的问题；
• 项目从原型走向上线时遇到的真实阻碍；
• 你希望 VCD 下一步支持的能力。

发布截图或日志前，请删除 API Key、.env、私人代码、个人路径和真实用户数据。