第 05 篇2026.10.06

建立可重复的项目骨架

把命名、固定身份、目录、配置和启动方法整理成别人也能复现的工程起点。

一个项目在作者电脑上跑得起来，很容易让人以为准备工作已经结束。换个目录或机器，才会发现它依赖了一份没写进说明的配置、全局工具或者旧数据库。这一章用轻联公开的 npm 包来讲骨架：身份、目录、配置和干净环境检查。

先给项目一份身份证#

显示名称是用户看到的名字；包名、命令名、工具名和域名，则会被安装脚本、Agent 配置或已有数据引用。它们相关，但改一个名字不应自动改掉所有身份。

01 / 名称与固定身份

左列改了只影响展示，设备改名也不改变密钥和配对；右列被安装命令、Agent 配置或设备签名引用，改动前要先做兼容。

轻联的身份表是这样的，每一项都能在 npm 包、公开指南或个人站产品页里核对：

项	轻联的值	谁在引用
显示名	轻联 / Device Center	个人站产品页、面板与指南
npm 包	`device-center`，MIT，`beta` 渠道	`npx` 命令、安装说明
CLI 命令	`device-center`（start、plan、connect、service 等）	安装脚本、用户级后台服务
MCP	本机 `/mcp`，工具名以 `device_center_` 开头	用户 Agent 的配置
公开指南	devices.owenshen.top/start	个人站、朋友试用
运行环境	Node.js 24，macOS / Linux	安装前检查

中文名“轻联”只出现在个人站和这套课程里，包、命令和工具名都叫 device-center。哪天换中文名，安装命令和 Agent 的 MCP 配置都不用动。控制面域名也算固定身份：设备请求的签名覆盖控制面的 Origin，不能随手改。

固定身份要有检查守着。轻联的发布前检查会拒绝这些情况：包名不是 device-center，版本不是 x.y.z-beta.n 的格式，渠道不是 beta 或不走官方 registry，许可证与 LICENSE 文件对不上，运行依赖没有钉死版本。

目录要反映责任#

下面是 npm 包里能看到的结构，在 npm 网站的文件列表里就能核对：

bin/device-center.mjs   CLI 入口：start、plan、connect、service 等
server/                 服务端，本机 Driver 与云端控制面共用
  drivers/              资源采集、SSH 只读检查、签名、配对、中转
  modules/devices/      设备登记的数据访问
  connector.mjs         本机 MCP 的工具
index.html 等三个页面   面板、登录页和 /start 指南的入口
src/                    这些页面的脚本和样式，无构建步骤
scripts/                driver、service、access 命令与发布前检查
docs/                   架构、安装、托管、排查等随包文档

架构文档按模块写职责：请求边界与账号核验、SSH 只读检查、签名与一次性配对、证书、中转与日额度、日志授权、MCP 工具、常驻服务。服务端是一个模块化单体，同一份代码按环境变量 DEVICE_CENTER_RUNTIME 以本机、容器或云端方式运行。前端是静态文件，只经 HTTP 调用服务端，不导入服务端模块。运行依赖只有两个固定版本的包，由 npm-shrinkwrap 锁住。

包里只放用户运行需要的东西：显式白名单，没有 install 钩子；数据库、身份、SSH、认证配置、部署记录和测试都不发布。

02 / 骨架承载三个职责

这张图是包内目录的阅读顺序。三块同在一个包里，前端只经 HTTP 调用服务端，不导入服务端模块。

配置要能解释来源#

本机模式不需要额外配置，只监听回环地址。部署云端控制面时，README 要求设置三个环境变量：

配置	用途	放在哪里
`DEVICE_CENTER_RUNTIME=cloud`	选择云端运行方式	服务端运行环境
`DEVICE_CENTER_PUBLIC_ORIGIN`	公开的 HTTPS 地址，用来核对 Host 和来源	服务端运行环境
`DEVICE_CENTER_AUTH_FILE`	指向认证配置文件	文件放仓库外，权限 0600

README 里的认证配置示例只用占位域名。迁移历史数据时要加的原所有者映射，只放仓库外的私有配置，不进公开示例或日志。前端能打包进去的配置都按公开信息处理；密钥由服务端运行环境提供，不复制到浏览器。

本地、测试、生产要能区分。轻联的本机清单默认只有真实的本机 Driver，没有预置记录；测试数据只留在临时目录和临时数据库里，不出现在产品启动中。

版本也要有真源，而且可能不止一条线。本机装的版本用 device-center --version 查，健康接口不提供版本号。网页和 npm 是两条线：main 的 CI 全部通过后，网页按精确的源码 SHA 构建部署；npm 包单独发布。只更新网页，已经装好的旧 CLI 不会多出新参数。

这件事我自己也踩过：2026-10-08 发布到 npm beta 标签的 0.2.0-beta.4，包里的 README 还写着“当前公开 npm 仍为 0.2.0-beta.3”。手写在文档里的版本号最容易过期，要么注明日期，要么从同一个真源生成。

用干净环境检查骨架#

03 / 干净环境复现

轻联的包检查按这个顺序跑。只有实际执行并留下结果，才把启动说明标为已验证。

轻联发布前跑 check、test 和 verify:package。最后一项在独立的临时 HOME 里，不带凭据，从官方 registry 取依赖，再离线安装这次打出的包，检查真实的 bin、npx 和前台 HTTP；只清理这次测试的临时目录，不碰用户数据。

你的项目也可以这样：找一个独立目录或临时 HOME，按文档完成安装、启动、一次基本操作和停止。失败时补齐缺的依赖或说明，不靠复制作者的整个环境解决。

轻联是怎么做的#

当时想解决什么。 包要公开发布，用户会用 npx 直接运行。我要确认它在别人的电脑上装得上、跑得起来，也没把我本机的数据带出去。

交给 Agent 什么。 发布规则写在随包的 docs/npm.md 里：显式白名单，不设 install、postinstall、prepare 钩子；数据库、身份、SSH、认证配置、部署记录和测试不进包；npm 的密码和一次性验证码由我自己在 npm 官方页面处理，不进聊天。

得到什么。 prepublishOnly 自动跑发布前检查，verify:package 在空 HOME 里复现安装。0.2.0-beta.4 的包一共 72 个文件。

怎样检查。 发布后匿名查询 registry，核对 SHA512 完整性摘要和包的字节，再运行帮助和计划命令。

为什么调整。 两处调整写在公开文档里。一是为了生成标准证书，加入了固定版本的 X509 依赖，不再是零依赖包，于是用 npm-shrinkwrap 锁住传递依赖和完整性摘要。二是把两种产物分开叫：本机工作区打出的候选包，文档里不称作 main 的 CI 构建；网页由 main 的 CI 按精确 SHA 构建部署，npm 包另行发布。

换成你自己的项目#

请为当前项目整理一份别人也能照着复现的工程骨架说明。先读代码和现有文档，不要凭印象写。

1. 写 docs/project-profile.md：显示名、仓库名、包名或应用 ID、命令名、服务名、公开域名、版本真源；标出哪些改了会影响安装、登录、数据或签名。
2. 在同一文件写目录职责：每个顶层目录负责什么，哪些文件进发布产物，哪些不进。
3. 写一份示例配置（如 .env.example）：每个字段的用途、是否必填、由哪个组件读取；不放真实值，密钥文件放在仓库外。
4. 在新目录或临时 HOME 里按文档从零安装、启动、做一次基本操作、停止，把命令、输出和缺口记进 docs/clean-setup-check.md。

最后告诉我：哪些命令实际跑过，哪些还只是写在文档里。

把方括号里的内容换成自己的需求。

身份表里每个固定身份都写了“谁在引用它”
示例配置里没有真实凭据，前端可见的字段都按公开信息处理
版本号能从一处查到，文档里没有写死、会过期的版本
docs/clean-setup-check.md 记录了一次干净环境安装，包括失败和修正

下一章开始做一条完整的前端路径，把骨架变成用户能操作的东西。前后端解耦的多服务部署概念，可查 Docker Compose 应用模型。