made-bridge 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibe Coding Agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+电脑侧桥接器。设备 API 在 `8788`，工作台在 `127.0.0.1:8787`。
+
+## 启动方式
+
+```sh
+npx made-bridge        # 任何机器一条命令（npm 包，Node >= 22）
+```
+
+- 首次运行会在 `~/.made-bridge/config.local.json` 生成配置（含示例项目），编辑 `projects` 指向你自己的代码仓库后重启。
+- 配置、状态、工作区都在 `~/.made-bridge/`，与代码分离——npm 包目录视为只读，缓存被清也不丢数据。
+- 环境变量：`VIBE_CONFIG` / `VIBE_STATE_DIR` / `VIBE_DATA_DIR` 可把三个位置各自指到别处；`VIBE_USB_PORT`、`MADE_HOME` 等见 `npm run doctor` 输出。
+
+```sh
+npm start              # 源码仓库运行（本目录）；沿用仓库里的 config.local.json
+npm run doctor         # 自检：运行环境、依赖命令、接入方式、已装插件
+```
+
+编程助手 CLI（codex / cursor / qoder 等）需要已安装在 PATH 上；刷机用仓库根的 `npm run flash`，不随 npm 包分发。
+
+## 目录结构
+
+内部仍是桥接器自己的运行结构：
+
+- `src/`：服务、设备接口与内置 agent
+- `public/`：工作台
+- `builtin/`：随代码发布的内置插件与主题（`builtin/plugins/`、`builtin/themes/`），升级代码即升级内置包
+- `examples/`：示例
+- `tools/`：开发工具
+- `test/`：测试
+
+## 插件与主题的目录
+
+用户包不在本目录，而是在固定的用户目录里：
+
+- `~/made/plugins/` —— 管控插件与助手插件
+- `~/made/themes/` —— 主题包
+
+桥接器每次启动扫描这两个目录，市场装到这里即可生效，不需要跟配置文件放在一起。路径可用 `MADE_HOME` 环境变量或 `config.local.json` 里的 `madeHome` 改成别处。
+
+查找顺序是「内置在前、用户目录在后」，**同名时用户目录覆盖内置**。所以 `bridge/builtin/` 里的内置包是只读的：工作台可以启用、停用，但不能移除；想覆盖就在 `~/made/` 放同名目录。
+
+插件市场和专家市场只负责发包，不放在这里。包安装进 `~/made/` 之后，桥接器才会加载。配置文件：源码仓库运行用本目录的 `config.local.json`；`npx made-bridge` 运行用 `~/.made-bridge/config.local.json`。
+
+在仓库根目录执行 `npm start` 或 `npm test` 会转到这里。

package/builtin/plugins/README.md

@@ -0,0 +1,22 @@
+# 内置插件目录
+
+跟代码一起发布的内置插件，`bridge/builtin/plugins/<名字>/` 一个目录一个包（`plugin.mjs` + `plugin.json` + `settings.json`）。
+
+## 与用户目录的关系
+
+桥接器按下面的顺序扫描，**同名时后者覆盖前者**：
+
+1. `bridge/builtin/plugins/` —— 本目录，随代码升级
+2. `~/made/plugins/` —— 用户目录，市场安装的插件都在这里
+
+所以这里是只读的内置包：工作台「插件」页可以启用和停用，但**不能移除**——移除只作用于 `~/made/plugins/`。
+想在本地覆盖某个内置插件，就在 `~/made/plugins/` 放一个同名目录。
+
+用户目录可用 `MADE_HOME` 环境变量或配置里的 `madeHome` 改成别的路径。
+
+## 加载规则
+
+- 一个插件目录必须有 `plugin.mjs`（或 `plugin.js`）与 `plugin.json`
+- 单文件 `.mjs` / `.js` 也会被加载
+
+插件接口见 `bridge/src/plugins/contracts.d.ts`，示例在 `bridge/examples/plugins/`，配置规范见 `docs/PLUGINS.md`。

package/builtin/themes/README.md

@@ -0,0 +1,64 @@
+# 内置主题目录
+
+跟代码一起发布的内置主题，每个子目录 = 一个主题。码得在「设置 → 主题设置」打开时会实时列出，点选即应用（通过当前连接拉取数据，重启生效）。
+
+## 与用户目录的关系
+
+桥接器按下面的顺序扫描，**同名时后者覆盖前者**：
+
+1. `bridge/builtin/themes/` —— 本目录，随代码升级
+2. `~/made/themes/` —— 用户目录，主题市场装的主题都在这里
+
+所以内置主题不能从工作台删除（删除只作用于 `~/made/themes/`）。想覆盖某个内置主题，就在 `~/made/themes/` 放一个同名目录，它的 `theme.json` 与资产会顶掉内置的那份。
+
+用户目录可用 `MADE_HOME` 环境变量或配置里的 `madeHome` 改成别的路径。
+
+## 主题包结构
+
+```
+themes/<名字>/
+├── theme.json   必需：标题、调色板、可选资产声明
+├── chime.wav    可选：提示音（新消息铃声）
+├── icon.bin     可选：锁屏图标，raw RGB565 小端
+└── bg.bin       可选：锁屏背景图，raw RGB565 小端
+```
+
+## theme.json 完整示例
+
+```json
+{
+  "title": "日落",
+  "colors": {
+    "accent": "E07840",
+    "btn_normal": "5C3328",
+    "btn_cancel": "6B4A38",
+    "border": "E0A080",
+    "text_primary": "FFF3E8",
+    "text_secondary": "E8C4A8",
+    "text_hint": "C09070",
+    "text_accent": "FFC088",
+    "title": "FFE8D0",
+    "bg_page": "1F1210",
+    "bg_panel": "2A1714",
+    "bg_row": "3A201B",
+    "danger": "A84040",
+    "lock_bg": "1A0F0C"
+  },
+  "sound": { "file": "chime.wav" },
+  "lock": {
+    "icon": "icon.bin", "icon_w": 112, "icon_h": 112,
+    "bg": "bg.bin", "bg_w": 240, "bg_h": 320
+  }
+}
+```
+
+## 资产格式说明
+
+- **提示音**：WAV（无压缩 PCM 16bit），采样率 8k~48k，单/双声道均可，
+  播放时按文件头自适应；≤256KB（约 8 秒 16k 单声道）
+- **图标/背景**：无头的 raw RGB565 小端像素数组（宽×高×2 字节），
+  尺寸在 theme.json 里声明；bg 建议与屏幕设计分辨率一致
+- **PNG 转 RGB565**：`python3 -c "from PIL import Image; import sys; im = Image.open(sys.argv[1]).convert('RGB'); open(sys.argv[2],'wb').write(b''.join(bytes(((r>>3)<<11)|((g>>2)<<5)|(b>>3)) for r,g,b in im.getdata()))" in.png out.bin`
+- 颜色缺省时回落到内置默认；恢复默认主题 = 清空全部主题缓存
+- **主题显示名（title）请使用常用汉字或英文**：设备内置中文字库覆盖
+  GB2312 常用字，生僻字（如「啵」）会显示为方框

package/builtin/themes/sunset/theme.json

@@ -0,0 +1,19 @@
+{
+  "title": "日落",
+  "colors": {
+    "accent": "E07840",
+    "btn_normal": "5C3328",
+    "btn_cancel": "6B4A38",
+    "border": "E0A080",
+    "text_primary": "FFF3E8",
+    "text_secondary": "E8C4A8",
+    "text_hint": "C09070",
+    "text_accent": "FFC088",
+    "title": "FFE8D0",
+    "bg_page": "1F1210",
+    "bg_panel": "2A1714",
+    "bg_row": "3A201B",
+    "danger": "A84040",
+    "lock_bg": "1A0F0C"
+  }
+}

package/config.example.json

@@ -0,0 +1,20 @@
+{
+  "port": 8787,
+  "devicePort": 8788,
+  "defaultProject": "demo",
+  "defaultProvider": "codex",
+  "codexModel": "gpt-6-astra",
+  "projects": [
+    {
+      "id": "demo",
+      "label": "演示项目",
+      "path": "./demo-project"
+    }
+  ],
+  "workbuddy": {
+    "allowUnscopedDispatch": false
+  },
+  "plugins": [],
+  "disabledPlugins": [],
+  "pluginSettings": {}
+}

package/demo-project/README.md

@@ -0,0 +1,5 @@
+# 演示项目
+
+这是「码得」桥接器附带的试用项目，供连接实体板或用电脑工作台试跑任务使用。
+
+改这里的文件不会影响其他代码，可以放心让编程助手动手。

package/demo-project/index.mjs

@@ -0,0 +1,14 @@
+// 演示用的小工具函数，编程助手会在这里尝试修改代码。
+
+export function greet(name) {
+  return `你好，${name}！`;
+}
+
+export function add(a, b) {
+  return a + b;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  console.log(greet('码得'));
+  console.log('1 + 1 =', add(1, 1));
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "made-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "码得（made）独立语音编程设备的电脑侧桥接器：工作台 API、设备接口、任务调度与插件运行时。一条命令启动，配合 ESP32 固件使用，源码在 github.com/jobop/made。",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "made-bridge": "src/server.mjs"
+  },
+  "files": [
+    "src/",
+    "public/",
+    "builtin/",
+    "config.example.json",
+    "demo-project/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jobop/made.git",
+    "directory": "bridge"
+  },
+  "homepage": "https://github.com/jobop/made/tree/main/bridge#readme",
+  "bugs": {
+    "url": "https://github.com/jobop/made/issues"
+  },
+  "keywords": [
+    "made",
+    "码得",
+    "esp32",
+    "bridge",
+    "voice-coding",
+    "agent",
+    "codex",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "start": "node src/server.mjs",
+    "doctor": "node src/server.mjs --doctor",
+    "test": "node --test --experimental-test-isolation=none --test-concurrency=1"
+  }
+}