pracht dev-mcp

@pracht/cli

用于开发、构建、验证和搭建 pracht 应用的命令行工具。

安装

npm install @pracht/cli

命令

pracht dev

启动支持 SSR 和 HMR 的本地开发服务器。

pracht dev
pracht dev --port 4000
pracht dev --cache-dir /tmp/pracht-vite-cache

--cache-dir 可覆盖 Vite 的 node_modules/.vite 缓存。针对同一项目检出目录运行多个开发服务器时，请为它们指定不同的目录。

pracht build

创建包含客户端/服务端输出以及 SSG/ISG 预渲染的生产构建。

pracht build
pracht build --analyze          # per-route client JS report (gzip + raw)
pracht build --json             # same report as JSON (agent-friendly)
pracht build --no-budget-fail   # report exceeded budgets without failing

--analyze 会按路由（模式 + 渲染模式）列出其加载的传递性客户端代码块及其原始大小和 gzip 大小，并显示总计行以及单独列出的共享入口代码块。输出遵循 NO_COLOR。

当 pracht 插件配置声明了 budgets（例如 budgets: { "*": "120kb", "/dashboard": "200kb" }）时，每次构建都会评估各路由的 gzip 客户端 JS 上限，写入 dist/server/budget-report.json，并在超出预算时以非零状态码退出，除非传入 --no-budget-fail。请参阅 docs/PERFORMANCE.md。

对于 Node.js 目标，请使用以下命令运行构建后的服务端：

node dist/server/server.js

pracht preview

在本地提供生产构建。会先运行 pracht build（使用 --skip-build 可跳过），然后为配置的适配器提供构建输出：

• Node：在 --port 指定的端口（或 $PORT，默认值为 3000）运行 dist/server/server.js。
• Cloudflare：针对构建后的 worker 委托给 wrangler dev；要求 node_modules 中或 PATH 上有 wrangler，并且配置了 wrangler。
• Vercel：没有忠实还原生产环境的本地运行时 — 此命令会引导你改用 vercel build / vercel dev。

pracht preview
pracht preview --port 4000
pracht preview --skip-build

pracht verify

运行快速且感知框架的验证检查，无需耗费时间进行完整构建或测试循环。使用 --changed 可专注于清单管理的变更文件，使用 --json 可生成机器可读的输出。当 dist/server/budget-report.json 存在时（在配置了预算的情况下由 pracht build 写入），会将上次构建的客户端 JS 预算结果作为检查项显示。

当应用声明了 defineApp({ constraints }) 或提交了 .pracht/app-graph.json 快照时，验证还会解析实时应用图、强制执行所有约束，并在快照过期时失败（使用 pracht plan --write 修复）。

pracht verify
pracht verify --changed
pracht verify --json

对于公开 WebMCP 页面工具的路由，请使用基于浏览器的子命令：

pracht verify webmcp --url http://localhost:3000
pracht verify webmcp --start "pracht preview" --json

它会启动已安装的 Chrome 150+ 版本，并启用 WebMCP 测试，比较原生路由范围工具注册表与解析后的应用图，并验证导航清理。框架自有的 pracht_* 开发工具不会参与应用图一致性检查。Pracht 绝不会下载未固定版本的浏览器；在 CI 中请传入 --browser /path/to/chrome。当需要将调用/取消证明纳入报告时，--scenario 接受显式的安全 WebMCP eval 文件。

pracht eval

通过 HTTP（默认）、远程 MCP （"transport": "mcp"）或原生 WebMCP（"transport": "webmcp" 加上 "webmcpRoute"）运行脚本化功能场景。WebMCP 步骤可以设置 cancelAfterMs，以证明主机取消操作会传递到分发路径。

pracht eval --start "pracht preview"
pracht eval evals/notes-webmcp.eval.json --browser /path/to/chrome --json

pracht plan

针对基准 git ref 进行语义化应用图差异比较。读取基准 ref 中提交的 .pracht/app-graph.json 快照（路由图锁文件），解析实时应用图，并打印新增、移除或变更的路由、API 端点和约束 — 为审阅者提供意图层面的变更日志。当上次构建写入了预算报告时，还会标注各路由的 gzip 大小。

pracht plan                       # diff against origin/main
pracht plan --base main
pracht plan --markdown            # fenced diff for PR comments
pracht plan --json                # full structured payload
pracht plan --write               # refresh .pracht/app-graph.json (commit it)

pracht report

根据机器生成的事实汇总适用于 PR 的 Markdown 报告：pracht plan 差异、pracht verify 结果，以及上次构建的客户端 JS 预算表。可将其作为 PR 描述中基于事实的部分。

pracht report
pracht report --base main --out pr-report.md

pracht llms

输出供编码 Agent 使用的内嵌 pracht 编写指南（项目布局、 约定、verify → plan → report 循环）。--write 会将其保存为应用根目录中的 llms.txt，以便 Agent 自动读取。

pracht llms
pracht llms --write

pracht docs

阅读此软件包内附带的 pracht 文档，确保内容与已安装版本一致，并支持离线使用。不指定主题时会列出页面；指定主题时会以 Markdown 格式输出对应页面（slug#section 会输出一个章节）；--search 可搜索章节。 这些文件也位于 node_modules/@pracht/cli/docs/ 中。

pracht docs
pracht docs routing
pracht docs --search "loader revalidate"

pracht generate route

创建新的路由模块。在清单应用中，此命令也会更新 src/routes.ts。 当应用已配置 Playwright（playwright.config.* 或 e2e/ 目录）时，还会在 e2e/<route-id>.spec.ts 中生成冒烟测试—— --no-test 可跳过测试，--test 可强制生成测试。生成的测试会导入 @playwright/test；如果缺少此依赖，命令会提示后续安装步骤（例如，pnpm add -D @playwright/test）。

pracht generate route --path /dashboard --render ssr --shell app --middleware auth
pracht generate route --path /blog/:slug --render ssg --no-test

pracht generate shell

创建 shell 模块并在应用清单中注册。

pracht generate shell --name app

pracht generate middleware

创建中间件模块并在应用清单中注册。

pracht generate middleware --name auth

pracht generate api

在 src/api/ 下创建 API 路由。

pracht generate api --path /health --methods GET,POST

pracht inspect

检查解析后的应用图。使用 --json 供 Agent/工具读取。

pracht inspect --json
pracht inspect routes --json
pracht inspect api --json
pracht inspect capabilities --json
pracht inspect agents --json
pracht inspect build --json

pracht inspect agents 会汇总已配置的 Agent 接口：Web Bot Auth 策略和密钥、破坏性操作确认模式、远程 MCP 端点、是否生成 llms.txt，以及哪些能力通过哪些传输方式公开。llms.txt 状态取自解析后的生产服务器构建配置，包括仅适用于构建或生产环境的选项。如果较旧的已安装 @pracht/vite-plugin 无法提供该状态，JSON 会报告 null，文本会报告 unknown，而不会将缺少元数据视为已禁用。JSON 报告还包含 mcpEndpoint、mcpDestructive、mcpRuntimeStatus 和 mcpUnavailableReasons；如果检查无法确认工具是否可访问，文本会将其声明标记为 mcp(unserved) 或 mcp(unverified)。

pracht typegen

根据解析后的路由图生成 src/pracht.d.ts 和 src/pracht-routes.ts，为 <Link>、路由对象形式的 useNavigate() 和 href() 辅助函数提供类型支持，并为 apiFetch() 提供带类型的 API 路由注册信息。生成期间不会执行 API 模块。在 CI 中使用 --check，当生成文件过期时使命令失败。首次生成后，pracht dev 会持续更新默认输出；在此之前，开发横幅会显示一条单行设置提示。

pracht typegen
pracht typegen --check

pracht doctor

验证整个项目中的本地应用配置。使用 --json 获取机器可读的输出。

pracht doctor
pracht doctor --json

pracht dev-mcp

通过 stdio 启动 Model Context Protocol 服务，将 inspect、doctor、verify、plan、report、generate、编写指南和内置文档（get_docs、list_docs、search_docs）作为原生工具提供给编码 Agent。客户端注册和工具参考请参阅 docs/MCP.md。

pracht dev-mcp