代理线束
- 作者仓库星标 5,841
- 作者仓库 lightdash
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @lightdash · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Node.js · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:发现您的代理 ID
您的代理 ID 决定您的所有端口和资源。通过检查生成的环境文件找到它:这将显示类似 `.env.agent.1` 的内容 — 该数字是您的代理 ID。替代方案:检查哪些 PM2 进程正在运行:
第 2 步:了解您的端口
获得代理 ID 后,您的端口就确定了: 服务 · 公式 · 代理 1 · 代理 2 · 代理 3 前端(Vite) · 3000 + (ID × 10) · 3010 · 3020 · 3030 后端 API · 8000 + (ID × 10) · 8010 · 8020 · 8030 节点调试器 · 9200 + (ID × 10)·9210·9220·9230
第 3 步:使用 CLI
所有堆栈管理都经过`agent-cli.sh`:
第 4 步:验证工作流程
每次代码更改后运行验证:输出为 JSON 到 stdout:阶段按顺序运行,在第一次失败时停止: typecheck — 用于通用、后端、前端(并行)的 TypeScript lint — 用于通用、后端、前端(并行)的 ESLint
# Agent Harness Quick Start
You are running in an isolated Lightdash development environment managed by the agent-harness. This guide helps you discover your environment and get productive immediately.
## Step 1: Discover Your Agent ID
Your agent ID determines all your ports and resources. Find it by checking for the generated environment file:
```bash
ls -la .env.agent.* 2>/dev/null | head -1
```
This will show something like `.env.agent.1` — the number is your agent ID.
**Alternative**: Check which PM2 processes are running:
```bash
pnpm exec pm2 jlist 2>/dev/null | node -e "
const data = JSON.parse(require('fs').readFileSync(0, 'utf8'));
const agents = [...new Set(data.map(p => p.name.match(/^agent-(\d+)-/)?.[1]).filter(Boolean))];
if (agents.length === 1) console.log('AGENT_ID=' + agents[0]);
else if (agents.length > 1) console.log('Multiple agents running: ' + agents.join(', '));
else console.log('No agent processes found');
"
```
## Step 2: Know Your Ports
Once you have your agent ID, your ports are deterministic:
| Service | Formula | Agent 1 | Agent 2 | Agent 3 |
|---------|---------|---------|---------|---------|
| Frontend (Vite) | 3000 + (ID × 10) | 3010 | 3020 | 3030 |
| Backend API | 8000 + (ID × 10) | 8010 | 8020 | 8030 |
| Node Debugger | 9200 + (ID × 10) | 9210 | 9220 | 9230 |
**Shared infrastructure** (same for all agents):
- PostgreSQL: `localhost:15432`
- MinIO S3: `localhost:19000`
- Headless Browser: `localhost:13001`
- Mailpit SMTP: `localhost:11025`
- Mailpit Web UI: `localhost:18025`
Get your URLs with:
```bash
./agent-harness/agent-cli.sh <AGENT_ID> url
```
## Step 3: Use the CLI
All stack management goes through `agent-cli.sh`:
```bash
# Replace <ID> with your agent ID (1-5)
# Check process status (uptime, restarts, memory)
./agent-harness/agent-cli.sh <ID> status
# View logs (services: api, frontend, common-watch, warehouses-watch)
./agent-harness/agent-cli.sh <ID> logs api
./agent-harness/agent-cli.sh <ID> logs frontend
# Check API health
./agent-harness/agent-cli.sh <ID> health
# Restart services after code changes
./agent-harness/agent-cli.sh <ID> restart api
./agent-harness/agent-cli.sh <ID> restart frontend
# Run SQL queries against your database
./agent-harness/agent-cli.sh <ID> psql "SELECT * FROM users LIMIT 5;"
# View slow queries (useful for debugging)
./agent-harness/agent-cli.sh <ID> slow-queries
# Run arbitrary command with your agent's environment loaded
./agent-harness/agent-cli.sh <ID> exec pnpm -F backend test:dev:nowatch
```
## Step 4: Verification Workflow
**Run verification after every code change:**
```bash
# Quick verification (typecheck + lint + unit tests for changed files)
./agent-harness/verify.sh <ID>
# Full verification (complete test suite + smoke test)
./agent-harness/verify.sh <ID> --full
```
Output is JSON to stdout:
```json
{
"status": "pass",
"stages": [
{"name": "typecheck", "status": "pass", "duration_ms": 3200},
{"name": "lint", "status": "pass", "duration_ms": 1800},
{"name": "test-unit", "status": "pass", "duration_ms": 4500}
],
"total_duration_ms": 9500
}
```
Stages run in order, stopping on first failure:
1. **typecheck** — TypeScript for common, backend, frontend (parallel)
2. **lint** — ESLint for common, backend, frontend (parallel)
3. **test-unit** — Unit tests for changed files
4. **test-full** (--full only) — Complete test suite
5. **smoke** (--full only) — API health check
## Step 5: Test Login Credentials
```
Email: demo@lightdash.com
Password: demo_password!
```
## Common Workflows
### Making code changes
1. Edit files as needed
2. If you changed `packages/common/`, the TypeScript watcher auto-rebuilds
3. If you changed `packages/backend/`, restart the API:
```bash
./agent-harness/agent-cli.sh <ID> restart api
```
4. Run verification:
```bash
./agent-harness/verify.sh <ID>
```
### Debugging API issues
```bash
# Check health
./agent-harness/agent-cli.sh <ID> health
# View recent API logs
./agent-harness/agent-cli.sh <ID> logs api
# Check for errors using Spotlight MCP
mcp__spotlight__search_errors with filters: {"timeWindow": 300}
# Get trace details
mcp__spotlight__get_traces with traceId: "<8-char-prefix-from-logs>"
```
### Debugging frontend issues
```bash
# View Vite server logs
./agent-harness/agent-cli.sh <ID> logs frontend
# Use Chrome DevTools MCP for browser automation
# (Your frontend URL is http://localhost:<3000 + ID*10>)
```
### Database queries
```bash
# View schema
./agent-harness/agent-cli.sh <ID> psql "\d tablename"
# Run queries
./agent-harness/agent-cli.sh <ID> psql "SELECT * FROM projects LIMIT 5;"
# Check slow queries
./agent-harness/agent-cli.sh <ID> slow-queries
```
## Definition of Done
Your task is complete when ALL are true:
- `./agent-harness/verify.sh <ID> --full` returns `"status": "pass"`
- Feature/fix works in browser at your frontend URL
- Tests cover the change
- No TypeScript errors or lint warnings
- Changes are committed
## What NOT to Do
- **Do NOT** modify shared infrastructure (PostgreSQL, MinIO containers)
- **Do NOT** hardcode ports — always derive from your agent ID
- **Do NOT** run `docker compose` commands — use `agent-cli.sh`
- **Do NOT** touch other agents' databases or processes
- **Do NOT** manually edit `.env.agent.<ID>` or `ecosystem.agent.<ID>.config.cjs`
- **Do NOT** disable tests to make verification pass
## Tmux Session Management
If you were launched with `--claude`, you're running inside a named tmux session `agent-<ID>`.
**For human supervisors** to attach to your session:
```bash
# Attach to a specific agent's tmux session
./agent-harness/attach.sh <ID>
# Or directly with tmux
tmux attach -t agent-<ID>
# List all agent sessions
tmux list-sessions | grep "^agent-"
```
**Useful tmux commands** (prefix is `Ctrl-a` on cloud servers, `Ctrl-b` locally):
- `prefix + d` — Detach from session (leaves Claude running)
- `prefix + [` — Enter scroll mode (q to exit)
- `prefix + c` — Create new window
- `prefix + n/p` — Next/previous window
## Quick Reference Card
```bash
# Status & Health
./agent-harness/agent-cli.sh <ID> status
./agent-harness/agent-cli.sh <ID> health
./agent-harness/agent-cli.sh <ID> url
# Logs
./agent-harness/agent-cli.sh <ID> logs api
./agent-harness/agent-cli.sh <ID> logs frontend
# Restart
./agent-harness/agent-cli.sh <ID> restart api
./agent-harness/agent-cli.sh <ID> restart frontend
# Database
./agent-harness/agent-cli.sh <ID> psql "<SQL>"
./agent-harness/agent-cli.sh <ID> slow-queries
# Verification
./agent-harness/verify.sh <ID> # Quick
./agent-harness/verify.sh <ID> --full # Complete
# Package commands (use your agent's env)
pnpm -F common typecheck
pnpm -F backend typecheck
pnpm -F frontend typecheck
pnpm -F backend lint
pnpm -F common test
pnpm generate-api # After TSOA controller changes
```
章节与文件索引
按说明文件中的顺序排列。
第 1 步:发现您的代理 ID
第 2 步:了解您的端口
第 3 步:使用 CLI
第 4 步:验证工作流程
更改代码
文件/命令 -> .env.agent.1 · localhost:15432 · localhost:19000 · localhost:13001 · localhost:11025 · localhost:18025 · agent-cli.sh · packages/common/
内容校验值 -> c2538f1ec27f
当前原文的自动摘译,尚未人工审校。
更改代码
根据需要编辑文件 如果您更改了
packages/common/,TypeScript 观察器会自动重建 如果您更改了packages/backend/,请重新启动 API: 运行验证: