minimal-designer

# FormaSpec FormaSpec 是一款自主托管、以 AI 为主的产品和 UI 设计工作空间。**FormaSpec** 是产品和主要代理面对的身份：产品经理可以向 Codex 描述网页、手机或平板电脑体验，审查渲染的预览，并继续在浏览器中编辑同一个结构化文档。 支持的代理身份是 `[@FormaSpec](plugin://formaspec@formaspec)`。升级会在 FormaSpec 0.4.0 安装并验证后删除安装程序拥有的旧身份。 该应用程序不嵌入 OpenAI API，也不要求 OpenAI API 密钥。Codex 通过本地 FormaSpec MCP 桥接器连接。您的 Codex 订阅或 API 使用情况保持独立。 > **当前发布状态：** 企业升级正在积极开发中。核心设计、持久性、MCP、产品规格、规划和 Codex 连接基础存在，但仓库 **尚未准备好投入生产**。请参阅 [实施状态](docs/IMPLEMENTATION_STATUS.md) 以获取已验证的空白和发布阻止因素。 ## 安装和启动 从仓库根目录运行一个安装程序命令。它会检查操作系统和要求，准备选定的运行时，启动 FormaSpec 和循环桥，并在检测到 Codex 后配置无令牌的 `formaspec` MCP 服务器和托管的 FormaSpec 0.4.0 插件。 Docker 是最简单的源安装方式： ```bash ./designer --yes install docker ``` 对于本地 Node.js 安装： ```bash ./designer --yes install local ``` Docker 安装程序和容器本地安全模式已实现。当前的 schema-16 本地检查点使用镜像 `sha256:620d231484044701403ff688493492ff5f8d12d7b09db3de6f00be83cbc658a1`。它在无需回退的情况下达到渲染器准备就绪，渲染相同的真实 PNG，在 API 重启前后，并拒绝渲染器 DNS、直接 TCP 和外部接口出口。相同的镜像通过 Firefox/WebKit 对齐 12/12 和相同机器复制的 bundle 恢复到独立的干净 Compose 项目中。证据保留在 `artifacts/ci/docker-schema11/summary.json`、`artifacts/ci/cross-browser-docker/summary.json` 和 `artifacts/ci/offhost-restore-simulation/NO-GO-SUMMARY.json` 中；兼容性目录名称 `docker-schema11` 故意保持不变。这些是本地未提交源的 `NO-GO` 检查点，而不是托管出处、真正的远程主机/TLS 恢复练习或生产资格。 兼容性 `designer` 启动器保留现有的 `.designer` 状态，并将支持的命令委托给 `formaspecctl`。删除 `--yes` 如果您希望在设置和 Codex 配置之前有一个明确的授权提示。 启动后，打开： - FormaSpec：[http://127.0.0.1:4310](http://127.0.0.1:4310) - 本地 MCP 桥：[http://127.0.0.1:4312/mcp](http://127.0.0.1:4312/mcp) 对于已安装依赖项的源代码开发： ```bash pnpm dev ``` 开发使用 Vite 编辑器，地址为 [http://127.0.0.1:4311](http://127.0.0.1:4311)，API 在端口 4310，本地桥在端口 4312。 ## 从 Codex 使用 FormaSpec 安装程序通常会自动执行此连接。要连接或修复它，请运行： ```bash ./designer --yes agent connect codex ``` 然后使用以下任意一个启动新的 Codex 任务： ```text 使用 FormaSpec 设计此产品流程。 使用 FormaSpec 设计此产品。 使用 FormaSpec 完善此选择。 [@FormaSpec](plugin://formaspec@formaspec) 创建专业的移动注册流程。 ``` FormaSpec 0.4.0 是唯一受管理的插件。安装或升级后启动新的 Codex 任务，因为已经打开的任务保留其原始插件库存。 连接在 Codex 配置中故意无令牌。Codex 与循环桥通信；桥在 macOS 钥匙串、Linux 秘密服务或 Windows 当前用户 DPAPI blob 中持有短期作用域授予。安装程序仅在受信任的本地 `[mcp_servers.formaspec]` 条目上设置自动工具批准，因此 Codex 不会对每个 FormaSpec 工具调用都提示。`doctor` 和 `status` 验证此条目仍然指向确切的活动凭证免费循环桥，然后报告它受信任。全局 Codex 批准和沙盒设置保持不变。 Windows 代码级 DPAPI 测试通过；发布前仍需要真正的打包 Windows 生命周期测试。 FormaSpec 的 MCP 服务器名为 `formaspec`。 网站不会创建代理任务。从 Codex 或 CLI 启动工作；确认确切的产品、设计、基准版本和选择后，FormaSpec 创建持久的 MCP 任务。Codex 声称它，读取其授权上下文，创建确切的预览，检查其 PNG，运行 linting，并将其转换为 `awaiting_approval` 状态，带有 `previewId`。代理不得提交预览或完成任务。人类审查确切的预览在 FormaSpec 中，并选择 **Commit** 或 **Discard**。 对于直接的非任务请求，代理首先创建一个任务，并使用相同的人类批准边界： 1. 读取项目、产品规格、版本和编辑器选择上下文。 2. 读取产品、规范产品规格、有效设计系统版本、可重用组件、令牌和连接的存储库映射。 3. 在不更改历史记录的情况下创建有界预览。 4. 检查确切的渲染 PNG、lint 诊断、辅助功能、RTL、响应式变体、交互状态和工程可行性。 5. 将任务发布为 `awaiting_approval` 状态；只有网站的 **Commit** 按钮才能保存确切的预览。 6. 返回确切的渲染 PNG 和无秘密的审查链接以供人类批准。 存档操作使用其自己的破坏性预览和提交工具。`VERSION_CONFLICT` 需要重新读取和预览；V1 永远不会自动合并。请参阅 [Codex 配置](docs/codex-config.toml.example) 以获取手动回退。 ## 当前控制命令 在开发过程中，通过 pnpm 运行 CLI： ```bash pnpm formaspecctl -- help pnpm formaspecctl -- doctor auto pnpm formaspecctl -- ensure-running --json pnpm formaspecctl -- status pnpm formaspecctl -- start docker pnpm formaspecctl -- stop pnpm formaspecctl -- restart pnpm formaspecctl -- migrate status pnpm formaspecctl -- backup create pnpm formaspecctl -- backup list pnpm formaspecctl -- backup schedule show pnpm formaspecctl -- backup schedule enable --at 02:00 pnpm formaspecctl -- backup schedule run pnpm formaspecctl -- backup prune preview pnpm formaspecctl -- backup verify /path/to/formaspec-backup.tar pnpm formaspecctl -- backup restore /path/to/formaspec-backup.tar --yes pnpm formaspecctl -- backup restore --backup-id backup_<id> --yes pnpm formaspecctl -- backup restore offline /safe/path/formaspec-backup.tar --yes pnpm formaspecctl -- backup restore status pnpm formaspecctl -- backup restore resume --yes pnpm formaspecctl -- backup restore resume --offline-bundle /safe/path/formaspec-backup.tar --yes pnpm formaspecctl -- backup restore rollback --yes pnpm formaspecctl -- backup restore abort --yes pnpm formaspecctl -- backup restore clear-stale-lock --yes pnpm formaspecctl -- agent config generic --format json pnpm formaspecctl -- support-bundle preview ``` 当前实现的 `formaspecctl` 工作流程如下： | 命令 | 当前行为 | | --- | --- | | `install local\|docker` | 检查/准备源运行时，启动 FormaSpec 和桥，并提供支持的 Codex 设置。 | | `doctor auto\|local\|docker\|server` | 诊断选定的运行时、渲染器、数据存储标识、桥对齐和身份验证的 FormaSpec MCP 连接。 | | `ensure-running` | 仅恢复记录的运行时和数据存储，验证桥，并使用 `--json` 返回结构化的阻止详细信息；它永远不会猜测或静默切换运行时模式。 | | `start`、`stop`、`restart`、`status` | 将应用程序生命周期委托给兼容性启动器并管理桥。 | | `migrate status` | 报告源模式数据库的编号迁移账本。 | | `backup create` | 请求正在运行的循环 FormaSpec API 创建并立即验证托管备份。 | | `backup list` | 列出不公开服务器文件系统路径的不透明托管备份记录。 | | `backup schedule show\|enable\|disable\|run` | 配置一个 UTC 每日窗口，并提供在固定 7/4/12 保留期内相同的窗口 ID 不变性执行。 | | `backup prune preview\|execute` | 生成确切的过期计划，永久豁免手动备份，并需要计划哈希加上明确的 `--yes` 才能重新验证删除。 | | `backup verify` | 独立验证现有的有界 `formaspec-backup` 包。 | | `backup restore <bundle>` | 使用明确的 `--yes` 验证并原子性恢复本地源 `./data`，创建停止服务的安全副本，在健康失败时回滚，并在 Docker/server 模式下拒绝。 | | `backup restore --backup-id <id>` | 外部监督 `HEALTHY_PLANNED_RESTORE_ONLY` 操作的启动器记录本地 Docker/server 运行时，通过其固定的运行时绑定、维护围栏、共享工作线程锁、验证的托管安全备份、渲染/数据库检查、凭证吊销和就绪门控重启。 | | `backup restore offline <bundle>` | 使用明确的 `--yes` 验证操作员选择的包，然后进行突变，固定相同的常规文件，通过身份/哈希/大小进行容量门控，流式传输 stdin 进入网络禁用的恢复工作线程，应用法医预复制容量检查，创建并验证现有 `/data` 字节的精确快照，即使 SQLite 已损坏，然后使用标准验证的切换、模式/渲染检查、审计/出站对账、凭证吊销和就绪门控重启。 | | `backup restore status\|resume\|rollback\|abort\|clear-stale-lock` | 检查或安全恢复确切的持久 Docker 恢复操作。 | | `agent connect codex` | 启动或刷新桥，配置无令牌的 MCP 和服务器作用域的自动工具批准，安装和验证单个托管的 FormaSpec 0.4.0 插件，删除仅安装程序拥有的旧身份，并在不更改全局 Codex 批准或沙盒策略的情况下验证连接。 | | `agent config generic` | 打印验证的无令牌循环 JSON/TOML 和验证指南，而不读取或修改未知客户端。 | | `support-bundle preview\|create` | 预览或显式创建具有积极的删减和无数据库、资产、备份、环境值、源或凭证的确定性有界诊断存档。 | 自动监督安装/警报、原生软件包安装、自动启动和完整的升级/卸载工作流程还不是完整的 CLI 功能。启动器固定的 Docker/server 恢复现在有两个单独授权的路径：`HEALTHY_PLANNED_RESTORE_ONLY` 通过托管备份 ID，和从显式选择的验证包进行的离线恢复。离线路径不依赖于健康的当前 API/数据库，但仍然缺少保留的真实 Docker/server 损坏数据库的生命周期练习。备份创建/列出/计划/修剪仍然需要本地循环服务，而包验证、本地源恢复和支持包创建保持单独。 ## 已实现的功能 - 具有稳定 ID、类型化操作、令牌、资产、原型链接、不可变修订、PNG 渲染和 JSON 交互的结构化 V1 设计文档。 - 内容寻址的 Brotli 快照、SHA-256 修订链、持久的确切预览、幂等原子提交、存档专用破坏路径和可重放的组织作用域 SSE。 - 组织、主体、角色、项目所有权、过期作用域代理授予、审计记录和服务层项目授权基础。 - 共享的 `ViewportTransform`、未转换的交互叠加层、凝聚的 `Moveable` 几何刷新、记忆化的节点视图、选择规范化和自动化的 Chrome DPR/缩放/平移/LTR/RTL 对齐基础。 - 严格的 V2 模式和确定性的 V1 到 V2 迁移实用程序，以及 FormaSpec 基础系统模型。 - 产品规格预览/提交、22 节规划模型、代理任务/连接和修订固定的检查。检查 API/视图保持请求的修订与当前头部分离，并公开完整性、解析的令牌、资产、组件、规则、验收标准、映射、稳定 ID 和 JSON 路径。 - 校验和验证的便携式导出、只读验证和管理授权的突变导入，具有幂等保留 ID 的冲突失败或确定性克隆重映射、隔离的栅格规范化、本地版本重基线和不可变的迁移-10 源。 - 在 `formaspec` 身份和 `formaspec://` 资源方案下提供可流式传输的 HTTP MCP 工具/资源。 - Docker 中一个单独的有界 Unix 套接字 Playwright 渲染器服务，具有非 root 用户、无网络、只读 root、丢弃的权限、确定性上下文、资源限制和关闭健康检查。 - 模式 11 持久的渲染作业记录，用于渲染和栅格规范化。API 拥有数据库生命周期（`queued` → `running` → 终端），使用所有者租约和心跳进行滚动进程恢复，仅保留有界哈希/版本/维度/警告/安全错误，并执行允许门控的 30 天终端记录保留。渲染器工作线程保持无数据库，输出图像字节不存储在作业行中。 - PNG/JPEG/WebP 解码和确定性的规范化，具有字节/像素限制、生成的内容寻址文件、完整性验证和旧 BLOB 回退。 - 具有显式过期/可撤销的存储库授予的只读工作区桥基础、秘密/符号链接/生成的文件排除、支持的平台检测、有界库存和无路径上传映射。 - 自动托管的 Codex 授予协调：授权启动器重用存储的凭证，仅当其确切的作用域和项目限制与当前组织策略匹配时，否则它会通过一次性配对轮换。Codex 配置保持无令牌。 - 批准门控的选定工作区 Codex 启动。授予绑定到确切的中央库存，交互必须携带确切的不可变 `approved` → `implementing` `start_implementation` 转换，Codex 启动时将选定的存储库作为其确切的工作目录，一个无秘密的任务参数、`shell: false` 和最小环境。POSIX 进程组监视在吊销、过期、策略撤回、交互关闭或库存更改后终止启动；包装的 Windows 后代保留需要作业对象或等效。 - 持久的组织设计系统，具有追加令牌/组件版本、不可变的发布、项目固定、确切的升级预览、REST/MCP 接口和初始管理 UI。 - 中央无路径存储库库存、不可变的 设计/源映射固定到确切的修订和库存哈希，以及修订固定的工程交接带有审查的映射 UI、人类批准/实施门控、可重放事件，并且没有中央文件系统路径输入。 - 具有独立范围的持久七阶段重新设计工作室、不可变的阶段历史、设计版本 CAS、仅限规划的一键式入口、REST/MCP 和专用的浏览器工作区。未来状态入口需要当前的存储库库存和验证的确切修订映射证据。 - 确定性的 1,000 节点核心/服务性能比较基准。 - 具有监督运行的 UTC 调度、预览优先的再验证修剪和永久手动备份豁免的固定 7 天/4 周/12 个月托管备份规划。 - 组织管理员审计保留确切的过期预览、30 天最低执行、有界 2,000 行/8 MiB 每种类型批次、受保护的原子删除、间隙重放和不可变的 SHA-256 链接运行证据。 - 具有模式 `0600` 确切运行时绑定、关闭维护、共享的非过期工作线程锁、崩溃可恢复的日记状态、验证的安全备份、数据库/渲染检查、`O_NOFOLLOW` 在 `/backups` 上的源固定、提交的日记保留在清理失败时、恢复的凭证吊销和显式恢复命令的外部监督启动器本地 Docker 恢复。 - 具有只读预览、相邻本地清单、删减日志/配置密钥库存和显式创建批准的有界确定性支持包。 ## 当前的重要限制 - 命名为 Windows 渲染器的命名管道、本地生命周期证明和持续出口/故障/负载证明在验证的 Docker 网络拒绝的工作器之外仍未完成。渲染和光栅归一化作业持续保留有界的仅哈希、所有者租赁的生命周期，保留时间恰好为 30 天，但组织可配置的保留仪表板和打包的负载证据仍未开放。 - 当前的 schema-16 本地证据在编辑器/管理 5/5、发布 E2E 1/1、预览集成 2/2、Chromium 对齐 12/12、Firefox/WebKit 对齐 12/12、视觉回归 7/7 和所有 1,000 节点浏览器预算方面均通过。Docker 重启/出口和复制包恢复门控也在本地通过。托管的支持 OS 重复、当前安全/SBOM/镜像扫描、签名本地生命周期证据和真正的远程主机/TLS 恢复仍未完成。 - 五个存储库本地最小特权工作流程现已涵盖冻结源门控、浏览器对齐/视觉/性能/发布套件、历史 Docker 烟雾测试、确定性 SBOM/许可证证据、未签名的 Linux 包和非安装 macOS 提取运行时门控。本地证据帮助程序通过工作流程合约 8/8、跨浏览器运行器测试 2/2、主机外模拟测试 7/7、发布证据测试 8/8、macOS 包证据测试 12/12 和 macOS 运行时烟雾合约测试 11/11；但尚未保留任何 GitHub 主机运行或真正的 Ubuntu DEB/RPM 工件。 - 完整的组件/发布授权和升级审查 UI、框架感知的工作区桥映射/上传/实现启动以及完整的 Redesign Studio 工件/E2E 覆盖率仍未完成。可移植导入现在将多部分上传流式传输到私有模式-`0700`暂存目录，通过哈希/大小固定存档，从有界读取中验证其中心/本地标头，并将每个条目膨胀为 16 KiB 块的私有文件。它不再保留多部分正文或所有提取的条目在内存中。单个 JSON/光栅条目在解析或归一化时仍在每个条目上限 64 MiB 下读取；更广泛的并发/对抗性和打包证据仍在进行中。 - 验证的备份创建/列出/验证/下载和可移植验证/导入在 `/administration` 中公开；源本地恢复、主管可调用的计划/修剪、启动器固定的计划恢复和显式授权的离线包路径存在。已安装的监督/警报、签名出处、隔离的端到端 `formaspecctl` 离线生命周期和更广泛的故障恢复证据仍未完成。一个真正的唯一项目 `formaspecctl` 烟雾测试现在通过验证的持久化 Compose 身份锻炼离线工作器/控制路径。服务器模式代理生命周期、打包运行时、真正的远程主机/网络/TLS/异地恢复和更广泛的证明仍在进行中。一个单独的相同机器复制包烟雾测试现在针对独立的干净目标通过，而无需声明这些远程保证。 ## 数据和兼容性 源/本机数据默认为 `./data`。启动器状态、日志和生成的运行时配置保留在被忽略的 `.designer/` 目录下。Docker 在其 Compose 卷中持久化 `/data`。 迁移账本在原地升级现有数据库，并保持 V1 文档/历史模型可读。V2 转换实用程序保留项目、页面、框架、节点、令牌、资产和原型 ID，但自动 V2 头迁移未作为一般操作员工作流启用。 在升级或恢复之前，请遵循 [备份和恢复](docs/BACKUP_AND_RESTORE.md)。 ## 开发验证 当前的 schema-16 源验证通过七包套件 842/842（核心 59、服务器 467、网页 91、CLI 96、本地桥 20、工作区桥 37、安装程序 72）、启动器 225/225 和所有工作区类型检查/构建。当前的本地证据还在编辑器/管理 5/5、发布 E2E 1/1、预览集成 2/2、Chromium 和 Firefox/WebKit 对齐 12/12 每个、视觉回归 7/7、macOS 运行时合约 11/11 和 1,000 节点浏览器预算方面通过。Schema-16 Docker 重启/出口、精确图像跨浏览器和干净项目复制包恢复检查点保留在 `artifacts/ci/` 下；精确的 schema-13 SBOM/许可证结果仍为历史记录。 ```bash pnpm test:run pnpm typecheck pnpm build pnpm test:launcher pnpm test:e2e:alignment pnpm test:e2e:alignment:cross-browser pnpm test:e2e:editor pnpm test:e2e:visual pnpm test:e2e:performance pnpm test:e2e:release pnpm test:performance pnpm test:release-evidence pnpm test:macos-pkg-evidence pnpm test:macos-pkg-runtime-smoke pnpm release:evidence:macos:verify pnpm package:linux:deb pnpm package:linux:rpm docker compose config --quiet ``` `pnpm ci:release-evidence` 是严格的源工作区生产依赖门控。历史链接的 0.45.2 schema-13 源证据在删除 Sharp/libvips 后，以 342 个第三方组件和零个策略违规通过；当前的 schema-16 源工作区和目标工件证据必须重新生成。保留的 `schema12-current` 未签名 PKG 通过其冻结的包/工作区完整性检查和非安装的提取运行时烟雾测试，但当前的验证器现在记录了预期的源漂移，它仍然是一个工程检查点：外部 PKG 即使在同一主机上也不可字节到字节复制，并且法律批准、签名、标记、漏洞扫描和特权本地生命周期证明仍在进行中。保留的 `schema11-current` 和 `schema10-current` 候选者是历史性的；容器、Windows 和 Linux 工件仍需要它们自己的目标特定证据。 仅通过单元/构建检查并不确立生产准备就绪。浏览器、安全、性能、备份/恢复、安装程序和发布证据门控在 [实现状态](docs/IMPLEMENTATION_STATUS.md) 中仍是权威的。 更多详情： - [快速入门](docs/GETTING_STARTED.md) - [视觉回归测试](docs/VISUAL_REGRESSION_TESTING.md) - [本地安装](docs/LOCAL_INSTALLATION.md) - [架构](docs/architecture.md) - [文档模式](docs/DOCUMENT_SCHEMA.md) - [设计系统](docs/DESIGN_SYSTEM.md) - [产品规格](docs/PRODUCT_SPECIFICATION.md) - [保留的 CI 和发布证据](docs/CI_RELEASE_EVIDENCE.md) - [MCP](docs/MCP.md) - [代理连接](docs/AGENT_CONNECTIONS.md) - [工作区桥](docs/WORKSPACE_BRIDGE.md) - [Redesign Studio](docs/REDESIGN_STUDIO.md) - [操作](docs/OPERATIONS.md) - [服务器部署](docs/deployment.md) - [安全](docs/SECURITY.md) - [威胁模型](docs/THREAT_MODEL.md) - [故障排除](docs/TROUBLESHOOTING.md) - [支持包](docs/SUPPORT_BUNDLES.md) - [升级](docs/UPGRADING.md) - [许可](docs/LICENSING.md) - [发布检查清单](docs/RELEASE_CHECKLIST.md) - [企业实施报告](docs/FINAL_IMPLEMENTATION_REPORT.md)