vibe-blueprint

<p align="center"> <img src="docs/assets/vibe-blueprint-hero.png" width="100%" alt="Vibe Blueprint 将项目事实转化为已保存的选择和原因，仅在需要时支持审查。" /> </p> <h1 align="center">Vibe Blueprint</h1> <p align="center"> <strong>Vibe Coding 开工蓝图</strong><br /> 从记住为什么的计划开始构建。 </p> <p align="center"> 获取适用于您的应用形状、数据和登录、部署和项目边界的技术启动计划。<br /> 保存选择和原因。仅在需要时重新审视它们。 </p> <p align="center"> <a href="#快速开始">快速开始</a> · <a href="#开始--记住--重新审视">工作原理</a> · <a href="#技术信任">技术信任</a> · <a href="docs/security.md">安全</a> · <a href="docs/client-configs.md">客户端设置</a> </p> > [!IMPORTANT] > **它规划开始。它不构建您的应用或监视代码。**<br /> > **它只规划怎么开工，不替你生成应用，也不会在后台盯着代码。** > [!NOTE] > 该项目尚未发布到 npm。目前可以从公共源代码仓库安装。 ## 从应用理念开始，而不是技术词汇 您可以以普通语言提问： > 我想构建一个小型费用报销应用。我不了解技术栈。给我一个实用的启动计划，解释重要的选择，并告诉我什么仍然不确定。 Vibe Blueprint 可以返回一个类似这样的计划： | 蓝图部分 | 示例答案 | | --- | --- | | 应用形状 | 从单个 Web 应用程序开始，而不是多个服务。 | | 数据 + 登录 | 在托管的服务器端存储中保存收据和帐户，并使用托管的登录。 | | 部署 | 为首次启动使用一个托管的部署路径。 | | 边界 | 包括员工提交和审批；排除工资和直接资金转移；确认是否需要离线工作。 | | 为什么 | 较少的活动部件使第一个版本更容易构建和维护。 | | 缺点 | 托管平台会创建供应商依赖。 | | 审查触发器 | 如果现场工作人员必须在停机期间继续工作，请重新审视数据方法。 | 这是交付成果的示例，而不是针对每个费用应用的通用建议。 ## 开始 → 记住 → 重新审视 ### 开始 描述您要构建的内容和重要的现实情况。配置的模型会提取事实并提出完整的基线路线。然后，基于代码的门控会拒绝硬约束失败、合并类似选择、删除主导路线、检查所需的最基本防护措施，并选择路线、提出一个实质性问题、提供最多两个真正不同的业务路线、升级或放弃。 结果涵盖了应用形状、数据和登录、部署、包含和排除的功能、重要假设、权衡和应触发另一次审查的条件。 ### 记住 当您批准提案时，Vibe Blueprint 会保存版本控制的、Git 友好的项目状态。后续编码会话可以检索已接受的选择及其原因，而不是从聊天历史中重建它们。 机器可读的真相源是： ```text .project-foundation/foundation.json ``` 可读且有证据的制品包括： ```text PROJECT-FOUNDATION.md .project-foundation/session-brief.md .project-foundation/evidence.json .project-foundation/decisions.jsonl ``` ### 重新审视 仅在您或您的编码代理请求时才会发生审查： - 新需求可以触发对受影响功能的聚焦重新评估； - 按需 Git 扫描可以报告组合的支付、多组织、离线和敏感数据信号以及受影响的功能；并且 - 注册的证据检查可以预览或运行通过命令允许列表。 Git 信号不会无声地重写保存的蓝图，识别具有语义确定性的每个受影响的决策，修复代码，阻止提交或在后台连续运行。 ## 快速开始 ### 要求 - Node.js 20 或更高版本 - npm - Git 用于变更扫描和提交感知证据 - 您自己的 OpenAI Responses 兼容端点的密钥 不包含、共享或从 Codex 身份验证文件读取 API 密钥。 ### 1. 从源代码安装 ```bash git clone https://github.com/SinboBoop/vibe-blueprint.git cd vibe-blueprint npm ci npm run build npm link ``` 这会公开： - `vibe-blueprint-mcp` — stdio MCP 服务器；stdout 保留用于协议消息。 - `vibe-blueprint` — 安全凭证管理和本地诊断。 ### 2. 在本地记录您的密钥 ```bash vibe-blueprint auth set vibe-blueprint auth status ``` `auth set` 不接受密钥参数。它从交互式终端读取而不回显，并将凭证存储在平台用户配置目录中，并使用支持的限制权限。 ### 3. 注册 MCP 服务器 首先，解析可执行文件的绝对路径： ```bash command -v vibe-blueprint-mcp ``` 对于 Codex，请用绝对路径替换可执行文件和项目根目录占位符： ```bash codex mcp add vibe_blueprint \ --env FOUNDATION_ALLOWED_ROOTS=/absolute/path/to/projects \ --env FOUNDATION_CODE_SHARING=none \ -- /absolute/path/to/vibe-blueprint-mcp ``` 长时间模型分析可能需要完整的 [Codex、Claude Code、Cursor 和通用 stdio 配置](docs/client-configs.md) 中显示的客户端超时。 ### 4. 安装薄 Codex 技能 ```bash mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" ln -s "/absolute/path/to/vibe-blueprint/skill/vibe-blueprint" \ "${CODEX_HOME:-$HOME/.codex}/skills/vibe-blueprint" ``` 技能决定何时调用 Vibe Blueprint 并以普通语言呈现结果。决策逻辑保留在 MCP 服务器中。 ### 5. 检查真实模型连接 ```bash vibe-blueprint doctor /absolute/path/to/project --check-model ``` 然后启动新的客户端会话并询问： > 我想构建一个小型 SaaS，代理商可以在其中管理单独的客户端工作区并每月支付费用。在编码之前创建 Vibe Blueprint。 对于现有项目： > 现场工作人员现在必须在停机期间继续编辑。在实施之前重新审视保存的蓝图。 对于不跨越项目基础边界的普通错误、样式更改或隔离功能，请改用普通的编码工作流。 ## 技术信任 ### 模型提出；基于代码的门控检查提案 Vibe Blueprint 不是仅限于提示的堆栈选择器。其配置的模型会创建事实、候选路线、评分、解释和安全声明。确定性代码会根据记录的决策完整性边界验证结构化的提案：硬约束、活动风险规则、路线等价性和优势、稳定排序和最小不变性完整性。 这些检查减少了与所述项目现实相矛盾的听起来不错的选择。它们 **不** 证明一个普遍最佳的堆栈，独立验证供应商，检查是否正确实施了安全措施，或证明生产准备就绪。 ### 保存状态不依赖聊天内存 批准的计划会作为模式版本化的项目状态写入，并带有可读的摘要和追加的决策记录。待处理的 `analysis_id` 值仅存在于运行的 MCP 进程中；在提交之前重启服务器，待处理的分析将被丢弃，而提交的项目文件仍保持持久。 ### 验证受到约束 注册的证据命令在分离的参数、`shell: false`、受控的工作目录、允许列表、超时、输出上限、编辑和包脚本哈希绑定下运行。这比任意命令执行更严格，但通过检查只能证明注册检查实际覆盖的内容。 ### 仓库检查 仓库包括自动化测试、严格的 TypeScript 检查、linting、协议集成、安装形状的 stdio 检查、检查到的已知回归库存和仓库秘密扫描。库存涵盖了维护的故障家族；它不是专家标记的代表性基准、一般准确性评分或优于其他模型的证据。 在本地重现检查： ```bash npm ci npm run lint npm run typecheck npm run build npm test npm run inventory:report npm run test:protocol npm run test:e2e npm run scan:secrets npm run check:skill npm run check:brand npm run check:package ``` 提供者支持的验证是显式的、按需的，并且可能会消耗配额： ```bash npm run verify:live ``` 其净化记录仅限于该运行的范围；它不是 SLA 或生产就绪证书。 ## 八种稳定的 MCP 工具 下面的 `foundation_*` 名称是稳定的协议标识符，为保持兼容性而保留；它们不是第二个公共品牌。 | 工具 | 责任 | | --- | --- | | `foundation_doctor` | 检查配置、凭证存在、允许根、模型连接性、保存状态和保护覆盖。 | | `foundation_analyze_project` | 为内部模型请求事实和候选路线，然后应用活动风险、不变性和路线检查。 | | `foundation_answer_question` | 将用户的答案应用于返回的实质性现实问题，并重新评估建议。 | | `foundation_commit` | 将用户确认的提案原子写入项目基础工件，而不修改应用程序源代码。 | | `foundation_get` | 以 JSON、Markdown 或紧凑的会话简报形式读取保存的状态。 | | `foundation_assess_change` | 将新需求与提交的状态进行比较，并重新分析受影响的功能。 | | `foundation_scan_changes` | 检查 Git 变更、依赖项、迁移、环境名称和结构，以获取组合边界信号。 | | `foundation_verify` | 预览或运行一个明确注册的、允许列表中的证据检查，而无需 shell。 | ## 安全和隐私默认值 - **您的密钥保留在仓库之外。** `vibe-blueprint auth set` 使用用户级凭证文件；CLI 密钥参数被拒绝。 - **默认情况下不提供仓库上下文。** `FOUNDATION_CODE_SHARING=none` 不发送调用者提供的摘要、源代码或 Git 差异。 - **明确的上下文上限。** `summary` 仅接受有界、编辑的结构化文本；仅 `diff` 允许有界、编辑的添加行。 - **有限的文件系统访问。** 每个 `project_root` 都使用 `realpath` 进行规范化，并与 `FOUNDATION_ALLOWED_ROOTS` 进行检查，包括符号链接逃逸。 - **不受信任的仓库文本保持为数据。** 注释、文档、摘要和差异在模型分析之前与指令隔离。 - **没有任意 shell 运行程序。** 证据命令使用允许列表、`shell: false`、超时、输出上限、编辑和包脚本哈希绑定。 - **协议安全的日志记录。** stdio stdout 仅承载 MCP；诊断信息发送到 stderr，并编辑标头、承载令牌和密钥形字符串。 - **没有沉默的模型回退。** 配置的模型 ID 被保留，并在提供者拒绝时报告。 - **没有响应存储请求。** 响应请求发送 `store: false`；端点操作员的基础设施保留在此项目控制之外。 阅读完整的 [安全模型](docs/security.md) 和 [安全报告策略](SECURITY.md)，然后再共享仓库差异或敏感需求。 ## 配置 `FOUNDATION_*` 环境变量和 `.project-foundation/` 状态名称保持稳定的协议和持久性合同。 | 变量 | 默认值 | 目的 | | --- | --- | --- | | `FOUNDATION_LLM_API_KEY` | 无 | 最高优先级凭证；优先在工作站上使用 `vibe-blueprint auth set`。 | | `FOUNDATION_LLM_BASE_URL` | `https://api.inferenvoy.com` | 兼容响应式的基 URL。 | | `FOUNDATION_LLM_RESPONSES_PATH` | 已发现 | 显式路径覆盖；否则为 `/responses`，然后在 404/405 之后为 `/v1/responses`。 | | `FOUNDATION_LLM_MODEL` | `gpt-5.6-sol` | 确切的模型 ID；从不静默替换。 | | `FOUNDATION_LLM_REASONING_EFFORT` | `xhigh` | 响应推理努力。 | | `FOUNDATION_ALLOWED_ROOTS` | 服务器工作目录 | 平台划定的根目录，在此之下可以解析 `project_root`。 | | `FOUNDATION_CODE_SHARING` | `none` | 最大仓库上下文：`none`、`summary` 或 `diff`。 | 端点发现仅在用户配置目录中缓存非机密端点元数据。参见 [.env.example](.env.example) 中的占位符；切勿在跟踪文件中放置真实凭证。 ## 支持的边界 Vibe Blueprint 适用于早期 Web 应用、SaaS 产品、内部工具和跨五个审查的架构模式的 AI Web 项目。 它 **不是**: - 完整的应用程序生成器； - 后台仓库监视器、自动计划更新器、提交阻止器或部署阻止器； - 保证最佳技术栈； - 通用架构、供应商、医疗、金融、法律、隐私、安全或合规顾问； - 证明声明的安全措施存在于源代码中； - 技术证据目录或确切版本新鲜度服务； - 生产就绪、安全或合规证书；或 - 专家标记的一般质量基准。 变更扫描报告保守信号和受影响的功能，而不是整个程序语义证明或替换蓝图。只有单独配置的钩子、CI 检查和受保护的分支可以将选定的发现转换为技术阻止器。 参见 [决策完整性发行说明](docs/releases/decision-integrity.md)，获取确切的兼容性合同。 ## 兼容性注意 在公共重命名之前，本地检查点使用预发布的可执行文件别名 `foundation-guard` 和 `foundation-guard-mcp`，并在 `foundation-guard` 用户配置目录下存储凭证。该软件包暂时保留这些可执行文件别名，并安全地读取该凭证位置，如果新凭证位置不存在，则现有本地用户无需重新输入密钥。新设置应使用 `vibe-blueprint`、`vibe-blueprint-mcp`、`vibe_blueprint` 客户端密钥和 `skill/vibe-blueprint` 路径。 八个 `foundation_*` 工具、`FOUNDATION_*` 设置、`.project-foundation/` 目录、`PROJECT-FOUNDATION.md` 和模式版本 1 有意保持稳定。 ## 升级和删除 使用 `git pull --ff-only`、`npm ci`、`npm run build`、`npm test` 和 `npm link` 升级源代码检查点。在升级共享项目之前查看发行说明，因为决策完整性合同添加了 `abstain` 作为第五种成功的交互模式。 在卸载可执行文件之前，请删除用户凭证和 MCP 注册： ```bash vibe-blueprint auth delete codex mcp remove vibe_blueprint npm unlink --global vibe-blueprint-mcp ``` 卸载不会删除项目中的 `.project-foundation/` 或 `PROJECT-FOUNDATION.md`；这些是项目记录，必须单独审查。 ## 贡献和安全 欢迎提出问题和拉取请求。不要在公共问题中放置密钥、私有源代码、原始差异、漏洞详细信息或未编辑的日志。按照 [SECURITY.md](SECURITY.md) 通过 GitHub 私有报告漏洞。 ## 许可证 [MIT](LICENSE)