示例运行指南
这份指南专门讲“如何运行仓库自带示例”，并解释每一步为什么要做。
如果你只想最快看到结果，先执行“最短路径”；如果你希望理解输出含义和常见报错，再看后面的讲解与排查。
最短路径（推荐）
bash
pnpm install
pnpm build
pnpm --filter @colony-harness/example-basic-agent dev
pnpm --filter @colony-harness/example-memory-agent dev
pnpm --filter @colony-harness/example-queen-agent-via-sdk dev说明：
pnpm install：安装 monorepo 全部依赖pnpm build：先构建 workspace 包（示例依赖这些包的dist类型与产物）--filter ... dev：只运行目标示例
前置条件
- Node.js
>=18.18.0 - pnpm
>=10.33.0
可用下面命令确认：
bash
node -v
pnpm -v示例一：basic-agent
运行：
bash
pnpm --filter @colony-harness/example-basic-agent dev你会看到：
Colony Trace日志（loop、tool 调用、token 统计）Final output: { output: 'The result is 6.', tools: [ 'calculator' ] }
这说明主链路已经打通：
HarnessBuilder完成运行时装配- Agent Loop 触发模型调用（示例中是 mock provider）
calculator工具被调用- 工具结果回注，输出最终答案
示例二：memory-agent（默认内存后端）
运行：
bash
pnpm --filter @colony-harness/example-memory-agent dev你会看到类似输出：
backend=memorymemories: [ 'colony-harness has layered memory architecture' ]
这表示语义记忆已写入并成功召回。
示例三：queen-agent-via-sdk（adapter 接入路径）
运行：
bash
pnpm --filter @colony-harness/example-queen-agent-via-sdk dev你会看到：
Result from queen-agent-via-sdk example:- 包含
echo与taskId的结果对象
该示例演示：
- Harness runtime 通过
controlplane-runtime桥接到控制面端口 - 使用
controlplane-sdk-adapter组合 BeeAgent 接入层 - 不改变业务 task handler 的写法
memory-agent 的 SQLite 持久化模式
先创建数据目录，再运行：
bash
mkdir -p examples/memory-agent/data
MEMORY_BACKEND=sqlite pnpm --filter @colony-harness/example-memory-agent dev看到 backend=sqlite 即表示切换成功。数据库文件会写到：
examples/memory-agent/data/memory.sqlite
常见报错排查（示例运行相关）
1) Cannot find module 'colony-harness' 或 @colony-harness/trace-console
原因：workspace 包还没先构建。
解决：
bash
pnpm build
pnpm --filter @colony-harness/example-basic-agent dev2) ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY
常见于非交互式终端里首次安装。
解决：
bash
CI=true pnpm install3) Could not locate the bindings file ... node_sqlite3.node
原因：sqlite3 原生模块没有正确下载/编译。
建议顺序：
bash
pnpm rebuild sqlite3若仍失败，可进入 sqlite3 目录手动执行安装脚本（会触发下载或本地编译）：
bash
pnpm --dir node_modules/.pnpm/sqlite3@5.1.7/node_modules/sqlite3 run install如果你的版本不是
5.1.7，把路径中的版本号替换成当前实际版本。
4) SQLITE_CANTOPEN: unable to open database file
原因通常是 SQLite 文件目录不存在。
解决：
bash
mkdir -p examples/memory-agent/data
MEMORY_BACKEND=sqlite pnpm --filter @colony-harness/example-memory-agent dev如何修改示例并快速验证
- 改
examples/basic-agent/src/index.ts：可以替换工具逻辑或输入表达式 - 改
examples/memory-agent/src/index.ts：可以调整remember:/recall:逻辑 - 修改后执行：
bash
pnpm --filter @colony-harness/example-basic-agent dev
# 或
pnpm --filter @colony-harness/example-memory-agent dev