@cniot/mdd-ai-bridge

MDD editor local AI bridge.

Changelog

0.1.8

• feat: 支持 MDD 编辑器自动发现 L4:<code> 关联页面，并递归拉取子 L4 页面一起下发到本地工作区。
• feat: 父页面工作区会生成 linked-pages.json，并在 README.md、AGENTS.md、PROMPT.md 中记录关联页面名称、code、父子层级、引用位置和本地目录，方便 AI 同时分析父子页面联动。
• feat: 下发结果会展示直接子 L4 数量、递归关联总数、已同步页面和需用户处理页面；如关联页本地已有未同步修改，会跳过覆盖并提示用户先同步保存或放弃本地改动后重新下发。
• chore: pull 仍只回写当前页面，不做关联页面批量自动回写，避免误覆盖线上页面。

0.1.7

• feat: pull 返回结构化 diffFiles，支持编辑器以左右对照方式展示 mdd.schema.json、mdd.script.jsx、mdd.style.less 的本地改动。
• chore: 保留 diffText 字段，兼容旧版编辑器的文本 diff 展示。

It starts a localhost service and syncs browser editor pages into:

~/.mdd-ai-workspace

When the service starts, it creates a global MDD context pack:

~/.mdd-ai-workspace/context/mdd-context/
  AGENTS.md
  api-cheatsheet.md
  engine-runtime.md
  schema-dsl.md
  hooks-cookbook.md
  types/mdd-runtime.d.ts
  examples/
  source/libs/

When a page is pushed from the browser, page files are written under pages/{code}, plus a page-level AGENTS.md that points AI tools back to the global context pack.

If the pushed page references other L4 pages with L4:<code>, the editor will request /l4/api/v1/console/get-by-code?code=<code>, recursively discover nested L4 references, and send all discovered pages to the bridge. The parent page workspace records the relationship in linked-pages.json and in generated AI prompt files. If a linked page already has unsynced local changes, the bridge skips overwriting that workspace and reports it back to the editor for the user to decide.

Usage

For most users, install it globally once:

npm i -g @cniot/mdd-ai-bridge

Then start the local bridge from any directory:

mdd-ai-bridge

Alternatively, run it without installing:

npx @cniot/mdd-ai-bridge

If your team prefers project-local scripts, install it in a business project:

npm i -D @cniot/mdd-ai-bridge

{
  "scripts": {
    "mdd:ai-bridge": "mdd-ai-bridge"
  }
}

Then run:

npm run mdd:ai-bridge

Source Context

The npm package is designed to include source-libs at publish time. When users run mdd-ai-bridge, the bridge defaults to MDD_AI_CONTEXT_SOURCE=copy, so the packaged MDD source context is copied into:

~/.mdd-ai-workspace/context/mdd-context/source/libs

This lets Cursor, Qoder, Codex CLI and other local AI tools read MDD runtime context even when the user does not have access to the MDD development repository.

Useful environment variables:

MDD_AI_BRIDGE_PORT=17678
MDD_AI_WORKSPACE=~/.mdd-ai-workspace
MDD_AI_CONTEXT_REFRESH=1
MDD_AI_CONTEXT_SOURCE=copy
MDD_AI_SOURCE_LIBS=/path/to/mdd/src/libs

Publish

This package is published from the package directory, not from the repository root.

cd /Users/caoruiqi/Documents/code/owtb/mdd/src/libs/mdd-ai-bridge

Before publishing, generate the packaged MDD source context and check what will be included:

npm run prepare-source
npm pack --dry-run

The dry-run output should include:

bin/mdd-ai-bridge.js
lib/mdd-ai-bridge.js
scripts/prepare-source-libs.js
source-libs/...
README.md
package.json

To test the package locally before publishing:

npm pack
npm i -g ./cniot-mdd-ai-bridge-0.1.8.tgz
mdd-ai-bridge

The bridge should start on:

http://127.0.0.1:17678

CORS And Private Network Access

The editor page may run on an online domain such as:

http://vnp-rc-test.cainiao.com

and call the local bridge:

http://127.0.0.1:17678

Modern Chrome treats this as a Private Network Access request and sends an extra preflight check. The bridge responds with normal CORS headers and:

Access-Control-Allow-Private-Network: true

If users see a browser CORS error when clicking "发送到本地 AI", make sure they are running a bridge version that includes this header, then restart mdd-ai-bridge and refresh the editor page.

If the browser reports The request client is not a secure context and the resource is in more-private address space loopback, CORS headers alone are not enough. In that case, mdd-editor will open:

http://127.0.0.1:17678/relay

The online page sends data to this local relay window with postMessage, and the relay window calls the bridge from the local origin. Users need to allow the popup window when the browser asks.

For the first publish, log in to npm or your company npm registry:

npm login
npm whoami

If publishing to the public npm registry:

npm publish --access public

Scoped packages such as @cniot/mdd-ai-bridge must be published with public access on the public npm registry. Otherwise npm may report E402 Payment Required - You must sign up for private packages. This package also sets publishConfig.access to public in package.json to avoid publishing as a private package by mistake.

If publishing to a company registry, confirm the registry first:

npm config get registry

Then publish with the company registry if needed:

npm publish --registry=https://your-company-npm-registry

After publishing, users can install and start it with:

npm i -g @cniot/mdd-ai-bridge
mdd-ai-bridge

Release Updates

When this package changes, update the version before publishing again.

For a normal bugfix or small improvement:

cd /Users/caoruiqi/Documents/code/owtb/mdd/src/libs/mdd-ai-bridge
npm version patch
npm run prepare-source
npm pack --dry-run
npm publish

For a larger compatible feature:

npm version minor
npm run prepare-source
npm pack --dry-run
npm publish

For a breaking change:

npm version major
npm run prepare-source
npm pack --dry-run
npm publish

If using a company registry, add the registry parameter to the publish command:

npm publish --registry=https://your-company-npm-registry

npm publish automatically runs the prepack script, which regenerates source-libs. Running npm run prepare-source manually before publishing is still recommended because it lets you inspect the packaged source context earlier.