DevMesh Studio

DevMesh Studio 是一个本地优先的开发运维一体化产品平台，面向需要在图形界面中完成项目配置、自动测试、持续集成、制品治理、发布、观测与回滚的团队和教学实验环境。

核心目标

平台不把开源工具简单串成脚本集合，而是围绕三个自有领域能力建立产品闭环：

Change-to-Evidence Graph：把提交、测试、扫描、制品、部署和健康检查组织为可追溯证据图。
Project Twin：保存代码、依赖、镜像、环境配置和运行状态的快照，并检测环境漂移。
Risk-Adaptive Pipeline：按变更影响范围和历史风险解释性地选择测试，同时以不可绕过的策略门禁保证发布质量。

当前阶段

已完成平台核心可运行垂直切片并继续扩展到真实 Docker 交付链路：NestJS 控制平面、PostgreSQL/内存事件存储、Gitea Webhook/Diff 适配、证据图与风险策略、Docker Runtime Controller、Java 17 测试任务、BuildKit/OCI digest、Project Twin 漂移与收敛、Release 审批/健康检查/回滚、React 控制台和 Electron 桌面壳均已落地。

登录与认证：当 DEVMESH_AUTH_REQUIRED=true 时，Web 会先显示 Access Token 登录页，不会渲染出一个无法操作的空工作区。Token 默认保存在当前会话的 sessionStorage，勾选“记住此设备”后才写入 localStorage；登录成功后 API 请求和 SSE 均携带 Bearer Token，Settings 页面显示主体、角色和认证方式，退出登录会清除 Token。当前后端使用预配置 Token（DEVMESH_AUTH_TOKENS、DEVMESH_DEV_TOKEN 等），不是用户名/密码登录；开发模拟模式会明确显示 dev-bypass/development auth。

npm run build:all
npm run desktop:dev

已生成 unpacked Electron 目录后，可用 npm run test:desktop 启动打包的 DevMesh Studio.exe 并通过 /api/health 做启动探针；该探针验证打包 API 能启动，不替代桌面窗口视觉级 E2E。

如果 npm run desktop:dev 报出 Electron failed to install correctly，通常是 Electron npm 包的 postinstall 没有完成，缺少 node_modules/electron/path.txt 和 node_modules/electron/dist/electron.exe。在项目目录执行 npm rebuild electron --foreground-scripts 重新生成 Electron 二进制即可；随后可用 node_modules/.bin/electron --version 验证。当前 Node.js 20.17.0 已满足 Electron 34.5.8 的运行要求。

桌面壳默认以 Docker Runtime 模式启动；仅做 API/UI 开发时可将 DEVMESH_RUNTIME_MODE 设置为 development，此时运行时中心使用开发模拟执行，不会启动本地容器。Playwright GUI 测试会显式使用 development simulation，并在页面中诚实显示模拟边界。

API 垂直切片包括：

GET  /api/health
GET  /api/runtime
POST /api/runtime/start
POST /api/runtime/stop
POST /api/projects
POST /api/projects/:id/changes
POST /api/projects/:id/runs
GET  /api/runs/:id/evidence
POST /api/runs/:id/release-evaluation

演示项目位于 sample-project/petclinic-devops-demo/，与平台业务代码保持独立。

apps/                 应用层：desktop/web/api/worker
packages/             领域模型、证据图、适配器和 UI 组件
infra/                本地运行依赖与策略样例
sample-project/       独立演示服务的契约和配置
scripts/              文档、代码规模和冒烟校验脚本
docs/                 设计与演示文档

开发原则

用户不需要在终端中操作平台；启动、停止和项目发布均由桌面 UI 完成。
平台自有代码负责领域模型、状态机、证据图、策略解释和产品体验；底层构建、扫描、存储和观测复用成熟开源实现。
所有长流程都必须可恢复、可审计、可观测。
所有发布都必须绑定不可变制品摘要、SBOM、签名和回滚点。

本地基础设施与 ObjectStore

先复制环境模板并填写仅用于本机的凭据；infra/docker-compose.yml 不再保存密码：

cp .env.example .env
npm run infra:up
# 查看解析后的 compose 配置
npm run infra:config
# 停止并移除本地容器（保留命名卷）
npm run infra:down

infra:up 使用 Docker Compose 的 --wait，只在 PostgreSQL、Redis、MinIO 和 Gitea 的固定健康检查通过后返回。当前仓库没有可独立启动的 worker HTTP 进程，因此统一启动脚本负责基础设施；Worker 的 pipeline adapter 由应用进程加载，避免在 compose 中伪造一个空服务。

Gitea 开启内置 Packages/OCI Registry 作为制品 Registry 边界，不再额外启动 registry:2。镜像发布和 digest 验证应使用 Gitea 的 Registry 地址；MinIO 仅用于报告、证据和扫描附件。

ObjectStore 适配器位于 packages/adapters/src/object-store.ts，不新增 SDK 依赖：

ObjectStorePort 提供 put/get/head/getObject/delete，正文使用 Uint8Array，并通过 contentType、metadata 和 sha256: digest 返回可审计元数据。
S3ObjectStore/MinioObjectStore 使用原生 fetch 和 AWS Signature V4，支持 MinIO 与 S3；默认 path-style 便于本地 MinIO，凭据从环境变量读取。
FilesystemObjectStore 用于离线和桌面开发模式，采用临时文件加 rename，拒绝路径穿越。
putReportAttachment 将内容保存到 reports/attachments/sha256/<hex>，重复内容复用同一对象；getReportAttachment 会重新计算 digest 并拒绝损坏内容。

应用侧可按环境创建实现：

import { createObjectStoreFromEnv } from '@devmesh/adapters';
const objectStore = createObjectStoreFromEnv(process.env);

主机进程连接 compose 中的 MinIO 时，.env 至少应提供 OBJECT_STORE_DRIVER=minio、OBJECT_STORE_ENDPOINT=http://127.0.0.1:59000、OBJECT_STORE_BUCKET、AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY。若不需要 MinIO，可设置 OBJECT_STORE_DRIVER=filesystem 与 OBJECT_STORE_ROOT_DIR。

真实供应链工具

当前验收环境已安装固定版本：

Gitleaks 8.30.1
Semgrep 1.134.0
Trivy 0.74.0
Syft 1.51.0
Cosign 2.4.1

执行独立工具验收：

npm run check:supply-chain

如果工具不在 PATH，可以设置以下变量指向固定二进制或虚拟环境：

DEVMESH_GITLEAKS_COMMAND
DEVMESH_SEMGREP_COMMAND
DEVMESH_TRIVY_COMMAND
DEVMESH_SYFT_COMMAND
DEVMESH_COSIGN_COMMAND
DEVMESH_COSIGN_PUBLIC_KEY

完整验收要求 SUPPLY_CHAIN_TARGET 指向项目 workspace，SUPPLY_CHAIN_IMAGE 指向 immutable image@sha256:<digest>。Cosign 本地测试使用 COSIGN_KEY、COSIGN_PUBLIC_KEY 和 DEVMESH_COSIGN_TLOG_UPLOAD=false；正式环境应替换为 KMS/keyless 密钥并启用 transparency log。供应链工具返回空报告、摘要不匹配或高危漏洞时，平台会真实阻断发布。

Clean deployment from source

This directory is a distributable source release. It intentionally excludes .env, Git history, node_modules, dist, reports, local Docker data, signing keys and tool binaries. On a new Windows computer, follow 部署与演示手册.md from the beginning rather than copying runtime artifacts from another machine.

The default infrastructure path is:

Docker Desktop → infra/docker-compose.yml → PostgreSQL/Redis/MinIO/Gitea
host API → Webhook/real pipeline
Vite Web or Electron → API/UI

After copying .env.example to .env, configure a PostgreSQL DATABASE_URL, Gitea GITEA_BASE_URL/PAT/Webhook secret, authentication token, registry credentials and external tool paths before using real execution. Gitea’s built-in OCI Registry at localhost:3000 is the supported registry; the old standalone registry:2 path is not required.

The complete Windows prerequisites, dependency installation, environment setup, Gitea/Webhook configuration, Node/Petclinic demonstrations, verification commands and real-versus-simulation boundaries are documented in 部署与演示手册.md.

详见 docs/DevMesh-Studio-设计与演示说明.docx。文档同时说明总体架构、创新点、部件选型、数据模型、演示项目、GUI 配置字段、自动测试/持续集成/发布流程和验收标准。

真实运行限制、工具可用性、Docker/Registry 摘要、GUI 报告和 Electron 打包边界见 docs/validation.md。