4 · 快速开始

目标：在本地把 KTH 基座 + 一个业务插件跑起来，打开 http://localhost:3080/bus-yyjz-agents/，看到「业务前台」与「配置后台」两个页面。

前置

请先完成 3 · 环境准备（Node ≥ 22.19、pnpm、GitLab 可访问）。本页命令以 Windows / PowerShell 为例，Linux/macOS 把 $env:X = "v" 换成 export X=v 即可。

步骤总览#

建立工作目录：基座与插件放在同一父目录，patch 相对路径才成立。
拉取 KTH 基座：kth.git（DSH 运行时）。
拉取业务插件模板：bus-yyjz-agents.git。
构建基座：pnpm install + pnpm run build。
构建业务插件：同样两条命令（产出 lib/）。
准备 patch：用 kth-deploys 的本地覆盖层，或按第 6 章建最小版。
启动宿主：pnpm dsh web --patch ... --no-open。
访问与登录：打开平台首页与插件页面。

1. 建立工作目录#

建议结构（插件库与基座平级）：

text目录约定

kth/
├── kth/                    # KTH 基座（DSH 运行时，克隆自 kth.git）
├── bus-yyjz-agents/        # 业务插件（模板，克隆自 global-plugins/bus-yyjz-agents.git）
├── infra-configmanagement/ # 配置中心（按需，见第 5 章）
├── infra-database-postgresql/
├── base-permission/
└── kth-deploys/            # 部署与本地覆盖层（含 local-dev/dev-plugins.patch.yml）

2. 拉取基座与模板插件#

bashclone

mkdir -p ~/kth && cd ~/kth

# KTH 基座（DSH 运行时）
git clone http://123.60.59.128:8888/kunlun/harnessagentvm/kth.git

# 业务插件模板（永盈子智能体平台：业务前台 + 配置后台）
git clone http://123.60.59.128:8888/kunlun/harnessagentvm/global-plugins/bus-yyjz-agents.git

# 部署与本地覆盖层（提供 local-dev/dev-plugins.patch.yml）
git clone http://123.60.59.128:8888/kunlun/harnessagentvm/kth-deploys.git

注意

若拉取受网络限制，请在 GitLab 地址前加内网/代理设置；不要把明文口令写进任何入库文件（见第 9 章）。

3. 构建（每个仓库各跑一次）#

宿主加载的是各插件的 lib/（构建产物），所以改完源码必须重新构建。

bash安装依赖并构建

# ① 基座
cd ~/kth/kth
pnpm install
pnpm run build

# ② 业务插件模板
cd ~/kth/bus-yyjz-agents
pnpm install
pnpm run build          # 产出 lib/index.js 与 lib/web/**

仓库	命令	产物
基座 `kth`	`pnpm install` → `pnpm run build`	DSH 运行时与 `dsh` CLI
业务插件	`pnpm install` → `pnpm run build`	`lib/index.js`、`lib/web/**`

4. 准备 patch 装配文件#

宿主通过 patch 覆盖层把插件按序注入，不改动 profile。仓库已自带一份可直接用的：

textkth-deploys/local-dev/dev-plugins.patch.yml

kth-deploys/local-dev/dev-plugins.patch.yml

它依次注入：配置中心 → 数据库 → 认证 → base-permission → 业务插件 → MCP 连接器。如果你只做单页面开发，只需保留「自己的项目 + 配置中心 + 数据存储」三行，见 6 · 最小 patch 与访问。

凭据放哪里

patch 里的数据库口令、SM4 密钥等敏感值，属于本地覆盖层；示例中一律用占位符。真实值从你的本地 dev-plugins.patch.yml 或平台管理员处获取，不要提交到 Git。

5. 启动宿主#

--patch 是启动器参数，必须写在 --no-open 这类 app 参数之前。

powershellWindows / PowerShell

$env:DSH_HOME = "$HOME\kth\.dsh-home"
cd $HOME\kth\kth
pnpm dsh web --patch "$HOME\kth\kth-deploys\local-dev\dev-plugins.patch.yml" --no-open

bashLinux / macOS

export DSH_HOME="$HOME/kth/.dsh-home"
cd ~/kth/kth
pnpm dsh web --patch ~/kth/kth-deploys/local-dev/dev-plugins.patch.yml --no-open

6. 访问与登录#

地址	说明
http://localhost:3080/	平台首页
http://localhost:3080/bus-yyjz-agents/	插件「业务前台」（本模板）
http://localhost:3080/bus-yyjz-agents/admin/	插件「配置后台」

路径从哪来

URL 由插件在 src/index.ts 里注册（本插件注册 /bus-yyjz-agents/），不是 patch 行的 id。id（如 kth-bus-yyjz-agents）只是装配标识。详见第 6 章。

常见启动问题#

现象	原因 / 处理
报 `unknown option '--patch'`	参数顺序错：`--patch` 必须写在 `--no-open` 之前。
页面 404 / 白屏	插件未构建：在插件目录重跑 `pnpm run build` 后重启宿主（宿主加载 `lib/`）。
`pnpm: command not found`	pnpm 未装或不在 PATH，见第 3 章。
端口 3080 被占用	关掉上一个宿主进程，或改端口启动。
配置中心相关报错	把配置中心也拉下来并构建（第 5 章），台账登记库连接。

下一步

需要数据库 / 权限 / 配置中心？看 5 · 按需拉取插件。要开始写自己的业务？看 7 · 业务插件开发（模板）。