本地调试使用独立的 cxclaw-dev 插件。tenant-panel-dev 始终由该插件声明,不会注册成全局独立 MCP,也不会替换或修改已安装的稳定版 cxclaw。
在仓库根目录运行:
bun install --frozen-lockfile
bun run dev:plugin该命令会:
- 构建本地
dist/cli.js和dist/mcp-apps/中的 MCP App 产物。 - 在
_tmp_/codex-plugin-dev/生成本地 marketplace 和开发插件。 - 将开发插件同步到仓库根目录下的
./playground/,并写入项目级 marketplace、配置和AGENTS.md。 - 清理全局
cxclaw-dev注册,确保开发插件只在该目录中启用。 - 让开发插件直接执行当前仓库的
dist/cli.js,不经过 npm。
首次使用前,在仓库根目录创建 playground 目录:
mkdir playground这些目录由 .gitignore 忽略,不会提交到 Git。
首次安装完成后重启一次 ChatGPT desktop app。登录并选择租户后,使用当前会话的 contextId 调用 tenant.current,右侧显示标题为 CXClaw Dev 当前租户 的开发版租户面板。
启动持续构建:
bun run dev:plugin:watch保存代码后,Node.js 端由 tsup 更新,MCP App 前端由 Vite 更新。刷新方式取决于修改内容:
- 修改
mcp-apps/:等待 Vite 生成新产物,完全退出并重新打开 ChatGPT desktop app,使 MCP server 用新内容 hash 注册 tool 和 resource,再重新调用入口 tool。 - 修改
src/mcp/server.ts、tool metadata 或其他 MCP server 逻辑:完全退出并重新打开 ChatGPT desktop app,让插件 MCP 进程重新加载dist/cli.js。
插件内置 MCP 当前没有独立的 Restart 按钮。无需 npm 发版、Git Marketplace 更新或重新安装稳定插件。
修改 skills、manifest 或 MCP 配置后,运行一次:
bun run dev:plugin它会重新生成并同步本地开发插件。修改 skills、manifest 或 MCP 配置后,完全退出并重新打开 ChatGPT desktop app,让宿主重新发现插件结构。
所有新增和重构的 MCP App 必须使用:
- Vite:浏览器端构建和 watch。
- React:组件、状态和生命周期。
- Radix UI:无样式交互原语和可访问性行为。
- Tailwind CSS:布局、排版、响应式和视觉样式。
@modelcontextprotocol/ext-apps:MCP Apps bridge 和宿主上下文。
前端源码统一放在:
mcp-apps/
├── vite.config.ts
├── src/shared/
├── src/<app-name>/main.tsx
└── tests/
MCP server 端只负责 tool、resource、业务逻辑和 Vite 产物加载。React 组件不得放入 src/mcp/。
所有 App 共享一份 Vite 配置、Tailwind 入口、host theme provider、MCP bridge hooks 和基础 UI 组件。每个 App 使用独立 main.tsx entry,并通过统一构建脚本逐 App 生成自包含 ES module,禁止产生跨 App 共享 chunk。
- Dialog、Popover、Tooltip、Tabs、Progress、ScrollArea 等交互组件优先使用 Radix UI primitive。
- Radix UI 负责交互语义、键盘操作、focus 管理和 ARIA;Tailwind CSS 负责全部视觉样式。
- 公共组件放在
mcp-apps/src/shared/ui/,业务组件保留在各 App 目录。 - 组件输入必须来自经过 Zod 校验的
structuredContent,不能直接信任 tool result。 - 权威业务状态保存在 MCP server;React state 和
widgetState只保存界面状态。 - 所有 tool call 通过
App.callServerTool()发起,卡片不直接访问 Solvea API。 - 所有 bundle、CSS 和静态资源随插件本地发布,不从运行时 CDN 加载。
所有 MCP App 必须跟随宿主主题,不维护独立主题开关。
初始化和宿主主题变化时统一执行:
import {
applyDocumentTheme,
applyHostStyleVariables,
} from "@modelcontextprotocol/ext-apps";
const applyHostTheme = () => {
const context = app.getHostContext();
if (context?.theme) applyDocumentTheme(context.theme);
if (context?.styles?.variables) {
applyHostStyleVariables(context.styles.variables);
}
};
applyHostTheme();
app.addEventListener("hostcontextchanged", applyHostTheme);Tailwind dark variant 绑定 document.documentElement[data-theme]:
@import "tailwindcss";
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));宿主 CSS variables 映射为项目语义 token:
@theme inline {
--color-app-background: var(--color-background-primary, Canvas);
--color-app-surface: var(--color-background-secondary, ButtonFace);
--color-app-foreground: var(--color-text-primary, CanvasText);
--color-app-muted: var(--color-text-secondary, GrayText);
--color-app-border: var(--color-border-secondary, ButtonBorder);
--color-app-ring: var(--color-ring-primary, Highlight);
--color-app-danger: var(--color-text-danger, LinkText);
--font-app-sans: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
--font-app-mono: var(--font-mono, ui-monospace, monospace);
}组件只使用语义 class,例如 bg-app-background、bg-app-surface、text-app-foreground、text-app-muted、border-app-border。业务状态色使用宿主提供的 info、success、warning、danger variables。
主题验收必须覆盖:
- light 首次渲染。
- dark 首次渲染。
- 卡片挂载期间从 light 切换到 dark。
- 卡片挂载期间从 dark 切换到 light。
- Radix UI portal 内容跟随当前主题。
- focus ring、disabled、error、loading 状态在两种主题下均清晰可见。
- Node.js CLI 和 MCP server 使用
tsup。 - MCP App 浏览器代码使用 Vite,不在
tsup.config.ts中增加 browser entry。 - Vite 输出统一写入
dist/mcp-apps/。 - 每个 App 的 Vite manifest 是对应 MCP resource 加载构建产物的唯一索引。
- 每个 App 必须独立生成自包含 bundle,不能引用其他 App 的输出文件或跨 App 共享 chunk。
- resource HTML 使用
<script type="module">加载内联 bundle。 - UI resource MIME 固定为
text/html;profile=mcp-app。 - UI resource URI 固定使用
ui://cxclaw/<app-name>/<content-hash>.html,例如ui://cxclaw/live-test/4a16d8c390ef.html。 content-hash取最终内联 HTML 的 SHA-256 前 12 位,覆盖 Vite 生成的 JavaScript、CSS 和 resource HTML 包装逻辑。- 构建内容变化时必须生成新的
content-hash;内容不变时 URI 必须保持稳定。禁止使用v2、日期或手工递增数字代替内容 hash。 - tool metadata、resource 注册 URI 和 resource contents URI 必须引用同一个带 hash URI。
- URI 由 MCP server 根据
dist/mcp-apps/<app-name>/自动计算,开发者不得手工维护 hash。 - 生产构建不得依赖 Vite dev server。
bun run typecheck
bun test
bun run build
bun run test:package前端变更必须同时通过 React 组件测试、light/dark 主题测试和打包产物测试。
查看插件和 marketplace 状态:
bun run dev:plugin:status移除开发版,不影响稳定版:
bun run dev:plugin:remove本地开发产物都在 _tmp_/codex-plugin-dev/,不会提交到 Git。
- 已迁移业务命令统一使用
cxclawctl <resource> <action>,例如analytics messages、agent list。 resource和action只能使用小写 kebab-case(单词用-连接),不得使用驼峰、下划线或通配符。- 新能力直接在资源 handler 中实现;不得新增
api analytics-messages、api chat-report-*一类扁平别名再转发。 api <command>只保留给尚未迁移的兼容能力。已经进入资源注册表的命令会拒绝从api入口调用。- 禁止用
startsWith()将一组未知命令兜底到同一个实现;每个公开 action 必须显式注册并有请求级测试。