made-market 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jobop
+
+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,70 @@
-# Temporary Holding Version
+# made-market · 码得公开插件市场
 
-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.
+码得的公开插件市场。**只做包管理**：登记和分发三类包，本身不执行插件、不连接码得、不保存配对令牌或 hook 密钥。
+
+包装进固定的用户目录 `~/made`（可用 `MADE_HOME` 覆盖）之后才生效：桥接器每次启动扫描 `~/made/plugins` 与 `~/made/themes`，不需要登记，也不需要和配置文件放在一起。
+
+| 类别 | 管什么 | 安装到 |
+| --- | --- | --- |
+| **主题** | 码得的外观：调色板、锁屏图、提示音 | `~/made/themes/<dir>/` |
+| **管控** | 接收板侧事件、把命令放进设备队列、调外部 hook | `~/made/plugins/<dir>/` |
+| **agent 运行时** | 接上一种助手的执行方式：会话、模型、进度、取消 | `~/made/plugins/<dir>/` |
+
+桥接器里另有一份随代码发布的内置包 `bridge/builtin/`；查找顺序是「内置在前、用户目录在后」，同名时 `~/made` 覆盖内置。
+
+技能不在本仓库建广场，沿用现成技能广场；人格归专家市场。边界与归类见码得仓库的 `docs/MARKETS.md`。
+
+## 安装一个包
+
+```sh
+npx made-market install sunset        # 主题
+npx made-market install alarm-clock   # 管控插件
+npx made-market list                  # 看看有什么
+```
+
+包从哪里下载？索引解析顺序是 `--registry` > 环境变量 `MADE_MARKET_REGISTRY`（指向 OSS 上的公开索引）> npm 包内自带的索引快照。**权威分发源是 OSS**，日常安装走它；远端不可达时自动回落到包内快照，离线也能装。发布流程见 [docs/PUBLISH.md](docs/PUBLISH.md)。
+
+## 目录
+
+```
+bin/             npx 入口（made-market）
+packages/        包源：themes/ control/ agents/，每包一个目录
+registry/        公开索引 index.json（生成物，是分发的唯一入口）
+site/            公开站点（静态，直接托管 site/ 即可）+ 归档 site/packages/
+tools/           校验、构建、打包、安装、发布（OSS / 上传服务）、脚手架
+server/          上传分发服务（用户上传 → 服务端校验 → 动态索引）
+docs/            包规范、安装说明、提交说明、后端部署
+test/            校验/打包/安装/上传服务的测试
+```
+
+## 维护者命令
+
+```sh
+node tools/validate.mjs     # 校验全部包
+node tools/build.mjs        # 生成索引与下载归档
+node tools/serve.mjs        # 本地预览站点 http://127.0.0.1:8899
+node tools/install.mjs alarm-clock --home ~/made   # 不经 npx 直接装
+npm test                    # 跑测试
+```
+
+## 文档
+
+- [包规范 v1](docs/SPEC.md) — 目录结构、`market.json`、三类包的桥接器文件
+- [安装说明](docs/INSTALL.md) — 一条命令或手动解包，卸载与安全边界
+- [提交说明](docs/PUBLISH.md) — 从脚手架到发布（含 OSS）
+- [上传服务](docs/BACKEND.md) — 自建后端：用户上传、服务端校验、动态索引、部署
+
+## 用户上传
+
+开放上传靠自建的上传分发服务（`server/`，无依赖 Node 服务）：作者
+`npx made-market publish <包目录>` 上传，服务端用与 `validate.mjs` 相同的规则
+校验（"CI 过审即上架"），版本不可变，索引动态重建，归档与元数据存阿里云 OSS。
+部署与 token 管理见 [docs/BACKEND.md](docs/BACKEND.md)。
+
+## 安全
+
+插件是本机 JavaScript，拥有桥接器进程的权限。只安装你信任的代码。市场能提供的是源码公开、静态校验和逐文件校验和；运行时的权限边界由桥接器决定。
+
+## 许可
+
+MIT

package/bin/made-market.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * 码得插件市场的命令行入口 —— 供 `npx made-market` 直接使用。
+ *
+ * 市场只做包管理：列出、查询、下载、校验和落盘到一个固定目录，从不执行包代码。
+ * 包装到 <home>/plugins 或 <home>/themes（默认 ~/made），桥接器启动时自己扫。
+ *
+ *   npx made-market list
+ *   npx made-market info sunset
+ *   npx made-market install sunset alarm-clock
+ *   npx made-market install demo-echo --home /tmp/home --dry-run
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { ROOT } from '../tools/lib/market.mjs';
+import { install, loadRegistry, resolveHome, resolveRegistry } from '../tools/install.mjs';
+import { publish } from '../tools/publish.mjs';
+import { login, logout, register, resolvePassword, whoami } from '../tools/account.mjs';
+
+const KIND_LABELS = { theme: '主题', control: '管控', agent: 'agent 运行时' };
+const KIND_ORDER = ['theme', 'control', 'agent'];
+
+const USAGE = `码得 · 插件市场  (made-market)
+
+用法
+  npx made-market <命令> [参数] [选项]
+
+命令
+  list                        列出索引里的全部包
+  search <关键词>              在包名、简介和标签里搜索
+  info <包 ID>                 看一个包的详情：文件、校验和、安装位置、创建人
+  install <包 ID…>             装到包目录，重启桥接器后生效（匿名，无需登录）
+  publish <包目录>             把一个包目录上传到市场服务（需先登录）
+  register <用户名>            注册账号并登录（凭证存 <home>/credentials.json）
+  login <用户名>               登录市场服务（发布的前提；90 天会话）
+  whoami                      看当前登录的账号
+  logout                      退出登录（吊销服务端会话并删除本地凭证）
+  rebuild-from-store           管理命令：从存储 manifests 全量重建 PG 索引
+
+选项
+  --home <目录>                包目录根，默认 $MADE_HOME 或 ~/made
+  --registry <路径|URL>        索引来源。默认优先 $MADE_MARKET_REGISTRY（如市场服务的索引），
+                               不可用或未设置时回落到本包自带的索引（离线可用）
+  --server <URL>              市场服务地址（register/login/publish；默认 $MADE_MARKET_SERVER，
+                               已登录时也可从凭证读取）
+  --token <t>                 发布 token（publish；默认 $MADE_MARKET_TOKEN 或登录凭证）
+  --password <pw>             密码（register/login；缺省在 TTY 下不回显输入）
+  --kind theme|control|agent   只列某一类（list / search）
+  --json                       以 JSON 输出
+  --force                      目标目录已存在时覆盖
+  --dry-run                    只校验并列出将要写入的文件
+  -h, --help                   显示帮助
+  -v, --version                显示版本
+
+装好的包在：
+  <home>/plugins/   管控插件与 agent 运行时
+  <home>/themes/    主题包
+
+桥接器每次启动扫描这两个目录，不需要登记，也不需要和配置文件放在一起。`;
+
+function parse(argv) {
+  const options = { command: '', args: [], home: '', registry: '', server: '', token: '', password: '', kind: '', json: false, force: false, dryRun: false, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--home') options.home = argv[++i] || '';
+    else if (arg === '--registry') options.registry = argv[++i] || '';
+    else if (arg === '--server') options.server = argv[++i] || '';
+    else if (arg === '--token') options.token = argv[++i] || '';
+    else if (arg === '--password') options.password = argv[++i] || '';
+    else if (arg === '--kind') options.kind = argv[++i] || '';
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--version' || arg === '-v') options.version = true;
+    else if (arg.startsWith('-')) throw new Error(`未知参数 ${arg}`);
+    else if (!options.command) options.command = arg;
+    else options.args.push(arg);
+  }
+  return options;
+}
+
+const semverGreater = (a, b) => {
+  const left = String(a).split('.').map(Number);
+  const right = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((left[i] || 0) !== (right[i] || 0)) return (left[i] || 0) > (right[i] || 0);
+  }
+  return false;
+};
+
+/**
+ * API 模式安装：按包直查市场服务的 /api/packages/<id>，不下载全量索引。
+ * 大市场（索引几十 MB）时用这个，归档地址改写成服务上的绝对地址。
+ */
+async function resolveViaApi(ids, server) {
+  const base = String(server).replace(/\/+$/, '');
+  const packages = [];
+  for (const id of ids) {
+    const response = await fetch(`${base}/api/packages/${encodeURIComponent(id)}`, { signal: AbortSignal.timeout(15000) });
+    if (!response.ok) throw new Error(`查询 ${id} 失败：HTTP ${response.status}`);
+    const versions = await response.json();
+    const latest = versions.reduce((best, item) => (!best || semverGreater(item.version, best.version) ? item : best), null);
+    if (!latest) throw new Error(`服务上没有包 ${id}`);
+    packages.push({ ...latest, download: latest.download.startsWith('http') ? latest.download : `${base}/${latest.download}` });
+  }
+  return { packages, base };
+}
+
+const human = (bytes) => (bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1048576).toFixed(2)} MB`);
+const homeOf = (options) => resolveHome(options.home);
+
+function installCommand(entry) {
+  return `npx made-market install ${entry.id}`;
+}
+
+function describe(entry) {
+  return {
+    id: entry.id,
+    kind: entry.kind,
+    version: entry.version,
+    name: entry.name,
+    summary: entry.summary,
+    author: entry.author,
+    license: entry.license,
+    tags: entry.tags,
+    target: entry.target,
+    dir: entry.dir,
+    createdBy: entry.createdBy || '',
+    publishedBy: entry.publishedBy || '',
+    sha256: entry.sha256,
+    archiveBytes: entry.archiveBytes,
+    files: entry.files,
+    install: installCommand(entry),
+  };
+}
+
+function listRows(index, options) {
+  const rows = options.kind ? index.packages.filter((entry) => entry.kind === options.kind) : index.packages;
+  const ordered = KIND_ORDER.flatMap((kind) => rows.filter((entry) => entry.kind === kind));
+  return ordered.length ? ordered : rows;
+}
+
+function printTable(rows) {
+  if (!rows.length) {
+    console.log('没有匹配的包。');
+    return;
+  }
+  const width = Math.max(...rows.map((entry) => entry.id.length), 2);
+  for (const entry of rows) {
+    console.log(`${entry.kind.padEnd(8)} ${entry.id.padEnd(width)}  v${entry.version.padEnd(7)} ${human(entry.archiveBytes).padStart(9)}  ${entry.name}`);
+  }
+  console.log(`\n共 ${rows.length} 个包。安装：npx made-market install <包 ID>`);
+}
+
+async function main() {
+  let options;
+  try {
+    options = parse(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    console.error(`\n${USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.version) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+    console.log(pkg.version);
+    return;
+  }
+  if (options.help || !options.command) {
+    console.log(USAGE);
+    return;
+  }
+
+  // 索引来源按需加载：--registry > $MADE_MARKET_REGISTRY > 包内自带（远端失败自动回落，离线可用）。
+  // rebuild-from-store 与 install --server（API 模式）不依赖全量索引。
+  const loadIndex = () => loadRegistry(resolveRegistry(options.registry));
+
+  if (options.command === 'list') {
+    const rows = listRows((await loadIndex()).index, options);
+    if (options.json) console.log(JSON.stringify(rows.map(describe), null, 2));
+    else printTable(rows);
+    return;
+  }
+
+  if (options.command === 'search') {
+    const query = options.args.join(' ').trim().toLowerCase();
+    if (!query) throw new Error('search 需要一个关键词');
+    const rows = listRows((await loadIndex()).index, options).filter((entry) => [
+      entry.id, entry.name, entry.nameEn, entry.summary, entry.summaryEn, ...(entry.tags || []), ...(entry.highlights || []),
+    ].filter(Boolean).some((field) => String(field).toLowerCase().includes(query)));
+    if (options.json) console.log(JSON.stringify(rows.map(describe), null, 2));
+    else printTable(rows);
+    return;
+  }
+
+  if (options.command === 'info') {
+    const id = options.args[0];
+    if (!id) throw new Error('info 需要一个包 ID');
+    const entry = (await loadIndex()).index.packages.find((item) => item.id === id);
+    if (!entry) throw new Error(`索引里没有包 ${id}`);
+    if (options.json) {
+      console.log(JSON.stringify(describe(entry), null, 2));
+      return;
+    }
+    console.log(`${entry.name}  ·  ${entry.id} v${entry.version}  ·  ${KIND_LABELS[entry.kind] || entry.kind}`);
+    console.log(`${entry.summary}`);
+    if (entry.description) console.log(`\n${entry.description}`);
+    console.log('\n信息');
+    console.log(`  作者      ${entry.author}`);
+    console.log(`  许可      ${entry.license}`);
+    console.log(`  创建人    ${entry.createdBy || '—'}`);
+    console.log(`  最近发布  ${entry.publishedBy || '—'}${entry.publishedAt ? ` · ${entry.publishedAt}` : ''}`);
+    console.log(`  标签      ${(entry.tags || []).join('、') || '—'}`);
+    console.log(`  安装到    ${homeOf(options)}/${entry.target}/${entry.dir}/`);
+    console.log(`  归档      ${human(entry.archiveBytes)}  sha256 ${entry.sha256}`);
+    console.log('\n文件与校验和');
+    for (const file of entry.files || []) console.log(`  ${file.path.padEnd(14)} ${human(file.size).padStart(9)}  ${file.sha256.slice(0, 16)}`);
+    if (entry.highlights?.length) {
+      console.log('\n要点');
+      for (const item of entry.highlights) console.log(`  · ${item}`);
+    }
+    console.log(`\n安装：${installCommand(entry)}`);
+    return;
+  }
+
+  if (options.command === 'install') {
+    if (!options.args.length) throw new Error('install 需要至少一个包 ID');
+    // 配了 --server / $MADE_MARKET_SERVER：按包直查 API，不拉全量索引（大市场友好）。
+    if (options.server || process.env.MADE_MARKET_SERVER) {
+      const { packages, base } = await resolveViaApi(options.args, options.server || process.env.MADE_MARKET_SERVER);
+      await install(options.args, { home: options.home, registry: base, index: { packages }, force: options.force, dryRun: options.dryRun });
+      return;
+    }
+    // 归档从索引所在的位置取：远端索引配远端归档，自带索引配包内归档，可离线。
+    const { source, index } = await loadIndex();
+    await install(options.args, { home: options.home, registry: source, index, force: options.force, dryRun: options.dryRun });
+    return;
+  }
+
+  if (options.command === 'publish') {
+    const dir = options.args[0];
+    if (!dir) throw new Error('publish 需要一个包目录');
+    await publish(dir, { server: options.server, token: options.token, home: options.home });
+    return;
+  }
+
+  if (options.command === 'register' || options.command === 'login') {
+    const name = options.args[0];
+    if (!name) throw new Error(`${options.command} 需要一个用户名`);
+    const server = options.server || process.env.MADE_MARKET_SERVER;
+    const password = await resolvePassword({ ...options, name });
+    const run = options.command === 'register' ? register : login;
+    const result = await run({ server, name, password, home: options.home });
+    const who = result.user || { name };
+    console.log(`${options.command === 'register' ? '注册' : '登录'}成功：${who.name}${who.displayName && who.displayName !== who.name ? `（${who.displayName}）` : ''}`);
+    console.log(`  服务 ${server}`);
+    console.log(`  凭证已存 ${resolveHome(options.home)}/credentials.json（0600），publish 直接可用`);
+    return;
+  }
+
+  if (options.command === 'whoami') {
+    const result = await whoami({ server: options.server, home: options.home, token: options.token });
+    console.log(`已登录：${result.user}${result.server ? ` @ ${result.server}` : ''}`);
+    return;
+  }
+
+  if (options.command === 'logout') {
+    await logout({ home: options.home, token: options.token });
+    console.log('已退出登录（服务端会话已吊销，本地凭证已删除）。');
+    return;
+  }
+
+  if (options.command === 'rebuild-from-store') {
+    const { createPool, initSchema, rebuildFromStore } = await import('../server/db.mjs');
+    const { createStore } = await import('../server/store.mjs');
+    if (!process.env.DATABASE_URL) throw new Error('rebuild-from-store 需要 DATABASE_URL 指向 PG 索引库');
+    const db = createPool(process.env.DATABASE_URL);
+    try {
+      await initSchema(db);
+      const count = await rebuildFromStore(db, createStore(), { log: (key) => console.log(`  同步 ${key}`) });
+      console.log(`索引重建完成：${count} 条版本事实。`);
+    } finally {
+      await db.close();
+    }
+    return;
+  }
+
+  throw new Error(`未知命令 ${options.command}\n\n${USAGE}`);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/docs/BACKEND.md

@@ -0,0 +1,189 @@
+# 上传分发服务
+
+用户自己上传包的后端。**"CI 过审即上架"的那道 CI 就是这个服务**：归档在服务端解包、
+复用与 `tools/validate.mjs` 完全相同的规则校验，过不了就永远进不了索引。
+
+## 形态
+
+一个**无依赖的 Node HTTP 服务**（`node:http`，无 npm 依赖，连 PG 客户端都是自带的）：
+
+```
+server/
+├── server.mjs     HTTP 路由：上传 / 索引 / 归档下载 / 版本查询 / 搜索
+├── service.mjs    发布流水线：校验 → 入库 → 同步索引（核心逻辑，测试直接驱动）
+├── store.mjs      存储驱动：local（开发/测试）| oss（生产，阿里云）—— 事实源
+└── db.mjs         Postgres 派生索引：零依赖线协议客户端（SCRAM-SHA-256）+ 表结构 + 查询
+```
+
+事实源与索引的分工：
+
+- **存储（local/oss）里的 manifests 是唯一事实源**，每条事实一个不可变对象，随时可以从它全量重建任何派生数据；
+- **Postgres 是派生索引**：发布时同步一行版本事实，搜索/查询/统计走 SQL。索引库没配、断了、报错，服务都自动回落到存储路径照常工作，修好后用 `rebuild-from-store` 补数据。
+
+## 接口
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| `POST` | `/api/register` | 注册账号 `{name, password, displayName?}` → `{token}`，注册即登录 |
+| `POST` | `/api/login` | 登录 `{name, password}` → `{token}`（90 天会话） |
+| `GET` | `/api/me` | 当前登录的账号（Bearer 会话 token） |
+| `POST` | `/api/logout` | 吊销当前会话 |
+| `POST` | `/api/packages` | 发布一个包。Bearer = **登录会话**（或服务令牌），body = tar.gz（**带** market.json） |
+| `GET` | `/registry/index.json` | 公开索引（有 PG 从索引库拼装，没有则从 manifests 重建），与 CLI/站点约定完全一致 |
+| `GET` | `/packages/<归档名>` | 归档下载。oss 存储 302 跳公共读直链（客户端直连 OSS，服务不经手流量）；local 存储由服务读文件返回 |
+| `GET` | `/api/packages/<id>` | 一个包的全部版本（install API 模式按这个直查，不拉全量索引） |
+| `GET` | `/api/search?q=&kind=&limit=` | 搜索：包名/英文名/简介/标签/创建人 ILIKE，kind 过滤 |
+| `GET` | `/` | 状态（含索引层 postgres/store） |
+
+**鉴权边界一句话：发布要登录，下载永远匿名。** 索引、搜索、版本查询、归档下载
+都不需要任何凭证；只有 `POST /api/packages` 检查 Bearer。
+
+## 发布流水线（服务端，上传方无法绕过）
+
+1. 归档 ≤ 10 MB，gunzip + 解 tar，条目路径检查（拒绝 `..` / 绝对路径）；
+2. 读 `market.json`：id / kind / version 合法性；
+3. **服务端校验**：`validatePackage` —— 与 `npm run validate` 同一套规则，
+   含 plugin.json 逐字段规范、主题资产存在性与尺寸、WAV 格式、indexed4 图标；
+4. **版本不可变**：同 id + version 已存在即 409，只能提升版本重新发布；
+5. 服务端**重新打包**（剥离 market.json），sha256 以服务端算的为准，不信任上传方；
+6. 写入 `packages/<id>-<version>.tar.gz` 与 `manifests/<id>/<version>.json`，同步 PG 索引，刷新存储索引。
+
+每次发布记录两个人：**`createdBy` = 该包首个版本的发布者（创建人，跨版本固定）**、
+`publishedBy` = 本版本的发布者。两者都进 manifest、公开索引、PG 搜索结果，可追溯。
+
+## 存储是事实源，PG 是派生索引
+
+存储（local/oss）里的对象布局不变：
+
+```
+packages/<id>-<version>.tar.gz     归档本体（分发，不含 market.json）
+manifests/<id>/<version>.json      版本清单 = 索引条目 + createdBy/publishedBy/publishedAt（事实）
+registry/index.json                兼容用的公开索引快照（发布时刷新）
+users/<名>.json                    账号：scrypt 加盐口令散列，不含明文
+sessions/<token>.json              登录会话：user + expiresAt（吊销 = 覆盖为 revoked 记录）
+access/tokens.json                 服务令牌（CI/管理员兜底通道，可选，也可用环境变量）
+```
+
+配了 `DATABASE_URL` 时，PG 里有两张表：
+
+```
+packages            每包一行：kind/name/summary/tags + latest_version/total_versions（搜索摘要）
+versions            每版本一行：entry = 整条 manifest（jsonb），version_key = 可数值排序的 bigint
+```
+
+- `versions.entry` 与存储里的 manifest 一字不差——**PG 丢了可以从 manifests 全量重建，存储坏了以 PG 为准读，两条腿互为备份**；
+- 发布只写受影响的行，不再全量扫描，10 万包规模下发布仍是 O(1)；
+- 搜索/未来登录、审核流、下载统计都在这层做，OSS 只管存放。
+
+规模化路径：几千包以内不配 `DATABASE_URL` 也完全够用；包量上万或要上账号体系时加一行环境变量即可，客户端接口不变。
+
+## PG 客户端为什么是自带的
+
+延续仓库零 npm 依赖的原则，`db.mjs` 内置了最小 Postgres 线协议实现：
+协议 3.0 握手、SCRAM-SHA-256（RFC 7677，测试含密钥推导交叉验证）、md5/明文/信任兜底、
+简单查询协议、带断线重连的小连接池。**无 TLS**：仅限内网/同机部署，公网请套反向代理。
+
+## 账号与登录
+
+发布必须先登录；账号直接存进存储驱动（与 manifests 同一套事实源，local/OSS 通用，
+不依赖 PG），口令用 scrypt 加盐散列，会话 90 天有效。
+
+```sh
+npx made-market register alice --server https://market.example.com
+#   或：login（已有账号）。凭证存 <home>/credentials.json（0600）
+npx made-market publish ./my-theme --server https://market.example.com
+#   登录过就不再需要 --token
+npx made-market whoami    # 看当前账号
+npx made-market logout    # 吊销服务端会话并删除本地凭证
+```
+
+会话 token 只用于**上传**；下载和索引是公开的。
+
+## 服务令牌（CI / 管理员兜底）
+
+自动化通道可以不走账号，用预签的服务令牌，两个来源（可并用）：
+
+- 环境变量 `MADE_MARKET_TOKENS=name:token,name:token`（重启生效）；
+- 存储里的 `access/tokens.json`：`[{"name":"alice","token":"…"}]`（写入即生效）。
+
+服务令牌发布的包，创建人/发布者记录为令牌名（如 `ci-bot`）。生成一个随机令牌：
+
+```sh
+openssl rand -hex 24
+```
+
+## 部署
+
+配置全部走环境变量：
+
+```sh
+PORT=8787                                   # 监听端口
+MADE_MARKET_STORE=oss                       # local | oss
+MADE_MARKET_PUBLIC_URL=https://market.example.com   # 对外基地址（写进索引 registryUrl）
+MADE_MARKET_TOKENS=alice:…,bob:…            # 发布 token
+DATABASE_URL=postgres://made:…@pg:5432/made_market  # 可选：PG 派生索引
+OSS_REGION=oss-cn-hangzhou                  # 以下为 oss 驱动所需
+OSS_BUCKET=made-market
+OSS_ACCESS_KEY_ID=…
+OSS_ACCESS_KEY_SECRET=…
+OSS_PREFIX=                                 # 可选，key 前缀
+```
+
+直接跑（Node ≥ 22，无依赖）：
+
+```sh
+node server/server.mjs
+```
+
+或 Docker（PG 一起起：`docker compose up -d`，见 `docker-compose.yml`）：
+
+```sh
+docker build -t made-market-server .
+docker run -d -p 8787:8787 --env-file server.env made-market-server
+```
+
+**安全提示**：OSS AccessKey 与数据库口令只放在服务端环境变量里，绝不进前端代码、仓库或
+`site/`——静态站点托管（GitHub Pages / OSS 静态托管）上的任何文件都是公开的。
+
+## 索引自愈
+
+```sh
+# 从存储 manifests 全量重建 PG 索引（换库、丢库、补数据都走这里）
+DATABASE_URL=postgres://… npx made-market rebuild-from-store
+```
+
+## 客户端怎么接
+
+服务上线后，它就是一个普通的索引来源，三种接法任选：
+
+```sh
+# 单次安装（拉全量索引）
+npx made-market install alarm-clock --registry https://market.example.com/registry/index.json
+
+# 大市场推荐：按包直查 API，不拉全量索引
+npx made-market install alarm-clock --server https://market.example.com
+
+# 设为默认下载源（服务优先，断网回落包内快照）
+export MADE_MARKET_REGISTRY=https://market.example.com/registry/index.json
+
+# 上传（作者侧）：先注册/登录一次，之后 publish 不再需要凭证参数
+npx made-market register me --server https://market.example.com
+npx made-market publish ./my-theme --server https://market.example.com
+```
+
+## 本地开发
+
+```sh
+docker compose up -d                       # 起 PG
+DATABASE_URL=postgres://made:made@127.0.0.1:5432/made_market \
+  node server/server.mjs &
+npx made-market register me --server http://127.0.0.1:8787 --password dev123
+npx made-market publish packages/themes/sunset --server http://127.0.0.1:8787
+curl -s 'http://127.0.0.1:8787/api/search?q=日落'
+```
+
+`local` 驱动的数据落在 `./data/`（已 gitignore）。测试覆盖：SCRAM/协议单元测试、
+口令散列与会话生命周期、发布鉴权（未登录 401 / 登录可发 / 创建人跨版本固定 / 下载匿名）、
+CLI 账号链路（register → publish 免 token → whoami → logout）、真实 PG 集成测试
+（设 `DATABASE_URL` 启用，未设自动跳过）、无 PG 时服务全链路、索引库故障自动回落存储、
+rebuild-from-store CLI 端到端。

package/docs/INSTALL.md

@@ -0,0 +1,95 @@
+# 安装市场包
+
+市场只发包，安装就是下载、校验、落盘到**一个固定目录**。桥接器每次启动自己扫这个目录，所以不需要登记，也不需要把包和配置文件放在一起。
+
+## 一条命令
+
+```sh
+npx made-market install <包 ID>
+```
+
+装到 `~/made`：
+
+- 主题包 → `~/made/themes/<dir>/`
+- 管控包、agent 包 → `~/made/plugins/<dir>/`
+
+装完重启桥接器即可生效。也可以一次装多个：
+
+```sh
+npx made-market install sunset alarm-clock demo-echo
+```
+
+常用命令与参数：
+
+```sh
+npx made-market list                 # 列出全部包
+npx made-market search 主题           # 搜索
+npx made-market info sunset          # 看详情：文件、校验和、安装位置
+npx made-market install sunset --dry-run   # 只校验，不落盘
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `--home <目录>` | 包目录根。默认 `$MADE_HOME`，再默认 `~/made` |
+| `--registry <路径或 URL>` | 指定索引来源。默认优先 `$MADE_MARKET_REGISTRY`（OSS 公开索引），不可达时自动回落到包内自带索引（离线可用） |
+| `--kind theme\|control\|agent` | 只列某一类（配合 `list` / `search`） |
+| `--json` | 以 JSON 输出，便于脚本消费 |
+| `--force` | 目标目录已存在时覆盖 |
+| `--dry-run` | 只校验和展示将要写入的文件，不落盘 |
+
+**包从哪里下载**：索引解析顺序是 `--registry` > `$MADE_MARKET_REGISTRY` > 包内自带快照，归档永远从索引进驻的同一位置按约定取（`<根>/registry/index.json` ↔ `<根>/packages/`）。权威分发源是 OSS，设一次环境变量即可：
+
+```sh
+export MADE_MARKET_REGISTRY=https://<bucket>.<region>.aliyuncs.com/registry/index.json
+```
+
+每个归档的 `sha256` 都记录在索引里，安装前逐字节核对，改过一个字节都会拒绝。
+
+安装工具**不执行**任何插件代码，也不写入任何密钥。
+
+## 包目录在哪
+
+固定的用户目录，桥接器启动时扫描 `<home>/plugins` 与 `<home>/themes`：
+
+| 优先级 | 目录 | 谁写 |
+| --- | --- | --- |
+| 1（被覆盖） | `bridge/builtin/plugins/`、`bridge/builtin/themes/` | 随桥接器代码发布，只读 |
+| 2（覆盖上面） | `~/made/plugins/`、`~/made/themes/` | 市场安装，以及你自己放进去的包 |
+
+**同名时 `~/made` 覆盖内置**。所以在 `~/made/plugins/` 放一个和内置同名的目录，就能本地顶掉内置那版。
+
+改根目录的两种办法，优先级从高到低：命令行 `--home`、环境变量 `MADE_HOME`、桥接器 `config.local.json` 里的 `madeHome`、默认 `~/made`。
+
+## 不用 npx 的两种装法
+
+仓库内直接跑（开发时用）：
+
+```sh
+node tools/install.mjs alarm-clock --home ~/made
+```
+
+手动解包：从站点下载 `<id>-<version>.tar.gz`，解开覆盖到目标目录即可。
+
+```sh
+mkdir -p ~/made/themes/sunset
+tar -xzf sunset-1.0.0.tar.gz -C ~/made/themes/sunset
+```
+
+归档里只有桥接器需要的文件，没有 `market.json`，可以直接解开覆盖。
+
+## 卸载
+
+在桥接器工作台的「插件」页点移除，或直接删掉目录：
+
+```sh
+rm -rf ~/made/themes/sunset
+rm -rf ~/made/plugins/alarm-clock
+```
+
+内置包不能从工作台移除——它跟代码走。要停用就在工作台点停用，要覆盖就放同名目录到 `~/made`。
+
+桥接器重启后生效。已下发的主题需要码得重新拉取才会回退。
+
+## 安全
+
+插件是本机 JavaScript，拥有桥接器进程的权限。**只安装你信任的代码。**市场侧能做的是：静态校验、公开源码、逐文件校验和（归档 sha256 + 每个文件的 sha256）。管控插件调用外部 hook 用的地址与密钥应当留在桥接器本机配置里，不要写进包。