6.9 从源码运行与调试

日常开发推荐 本机 Teloa / Harness + Docker PostgreSQL。这样可以直接调试本机文件、程序、PATH 与工具权限，也与 npm 原生安装使用相同的执行方式。当前需要本机操作的用户也可按本页从源码运行；不同安装方式见安装指南。

全容器 Compose 可用于隔离集成测试与部署回归；本机程序和系统权限仍需在原生环境验证，详见测试环境分工。

环境与启动

需要已取得源码、Node ^22.19.0 || >=24.0.0、pnpm 11.7.0 和可连接的本机 Docker。

pnpm install
pnpm setup:database
pnpm setup:dsh
pnpm dev:dsh

启动器会先构建，并输出当前认证地址。使用完整地址进入。不要把令牌提交到仓库或错误报告。

这组命令在本机运行应用，只把数据库放入 Docker。setup:database 默认需要可用的本机 Docker。已发行的 npm 安装器也可接入已有本机专用数据库，配置要求见安装指南；此选项不用于连接任意远程数据库。

默认工作目录为 .runtime/teloa/workspace。可通过 TELOA_WORKSPACE_ROOT 显式指定自己的工作目录，但不能使用 Teloa 程序目录、其上级目录或程序目录中运行目录以外的位置。切换工作目录不会自动搬迁原有文件。

Harness 从工作目录调用获授权的工具。程序是否可用取决于工具接入、启动环境的 PATH 和操作系统权限；原生运行不等于开放整台电脑。修改 PATH 后应重启服务并实测。浏览器、桌面和办公软件操作还需要对应工具，不能用“安装完成”作为已具备这些能力的证据。

pnpm check:dsh
pnpm test:contract
pnpm test:bindings

按修改范围补跑后端、Harness 或浏览器测试。插件配置与界面构建通常需要重新构建并重启宿主，不能依赖浏览器刷新自动加载新代码。

使用仓库提供的 pnpm dev:dsh:acceptance 验收启动器，按其提示创建独立 profile、端口、工作目录和数据库范围。不要只改一个端口就复用正式工作数据。

默认 3100 是日常宿主。结束验收时只操作自己启动的进程，不按模糊关键词批量终止。

先看启动命令的错误，再看 .runtime/teloa/harness.log 和相应执行记录。分享前删除令牌、Cookie、密钥、数据库连接和私人内容。构建输出、模型错误和业务状态错误应分别记录。