10 · 打包发布与 FAQ

从插件库打包 → 汇集四组件产物 → 客户机 / 内部服务器部署，一条链路讲清； 末尾汇总现场最常见的现象与处理。

1. 四组件#

交付只有四个组件，不再引入 governance / channel / agent / model / marketplace。 组件名 = 产物目录名 = tarball 包名前缀，层级来自插件库的目录前缀。

kth-runtime运行时，唯一来源 deepseek-harness/dist/npm/*.tgz
kth-infraInfrastructure/infra-* → 包名 kth-infra-*
kth-baseInfrastructure/base-* → 包名 kth-base-*
kth-busInfrastructure/bus-* → 包名 kth-bus-*
目录即归属

packages/kth-infra/ 只放包名以 kth-infra- 开头的 tarball —— 汇集的全部依据就是包名前缀。

2. 打包（在插件库）#

在插件库 Infrastructure/ 根执行，脚本扫描全部插件、逐个在临时 git worktree 里检出对应分支构建（不动工作区），再打包。

bashInfrastructure/ · 按环境分支打包
pnpm run pack            # main 分支 → dist/production/*.tgz
pnpm run pack:test       # dev  分支 → dist/test/*.tgz
构建目录

只能在插件包根内构建，别处构建产物会落错位置，而宿主仍加载旧的 lib/，表现为「改完不生效」。 脚本会校验 lib/index.js，缺失即报错。

3. 汇集（在 kth-deploys）#

在 kth-deploys/ 根执行，把上一步的 tarball 按包名前缀归入四组件目录。本仓库只汇集，不再自己打包。

bashkth-deploys/ · 汇集产物
pnpm run assemble            # → production/packages/
pnpm run assemble:test       # → test/packages/

产物目录（packages/）与 dsh.env 都不入库；随目录整体拷贝交付。

4. 部署#

场景命令（在对应分区下）说明
客户机sudo bash scripts/deploy-customer.sh install消费 tarball，不联网；安装前先清掉残留 app/
内部服务器sudo bash scripts/deploy-linux-service.sh deploy源码构建式部署

5. 环境与端口#

环境端口服务名 / 启动方式
本地开发3080--patch 覆盖层就地启动
测试3081kth-harness-test（test/ 分区）
生产3080kth-harness（production/ 分区）

测试与生产端口错开，可同机并存。

6. 常见问题（FAQ）#

现象原因 / 处理
报 unknown option '--patch' 参数顺序错：--patch 是启动器参数，必须写在 --no-open 这类 app 参数之前。
页面 404 / 白屏 插件未构建（lib/ 缺失或过期），或改完后未重启宿主。在插件目录重跑构建再重启宿主。
pnpm: command not found pnpm 未装或不在 PATH，按第 3 章装好并保证 PATH 生效。
业务插件不加载 缺 kth-infra-configmanagement（消费方 inject: ['infraConfig'] 的硬依赖）；把配置中心也拉下来、构建并注入 profile。
客户机 npm error Invalid Version: 安装根目录残留了上次安装的半成品 app/，重跑 npm install 被拖崩。进安装根目录 sudo rm -rf app 后重新 install（.dsh-home/ 与 dsh.env 不要删）。
CentOS 7 / glibc 2.17 起不来 node 官方包要求 glibc ≥ 2.28。手工装 unofficial-builds 的 glibc-217 版（如 node-v22.23.3-linux-x64-glibc-217），装完 init-env 的环境检查即通过。
明文口令出现在补丁里 口令应放本地覆盖层（gitignored 文件）或环境变量，勿入库；生产交付的补丁与文档一律用占位符。
端口被占用 关掉上一个宿主进程，或改端口启动（测试默认 3081，与生产 3080 错开）。

7. 下一步#

从这里继续

去 GitHub / GitLab 查看各插件的 README.md（每个插件仓库都带），了解它的服务面与配置项； 也可以从 bus-yyjz-agents 模板起步，写自己的业务插件：注册路由、领域表、运行时资源装配 —— 路线见 7 · 业务插件开发（模板） 与 8 · DSH 运行时能力。