# Echobot Development

> Work on this EchoBot repository when the task changes repository code or runtime behavior: agent loop, skill runtime, tool registry, session flow, routing, roleplay, commands, channels, gateway delivery, FastAPI API, browser UI, scheduling, memory, attachments, images, ASR, TTS, or tests. Use for requests like "修改 EchoBot 逻辑", "排查 route / 会话 / skill / 定时任务问题", "补测试", "重构这个仓库", or "review this EchoBot change".

- Skill: `kdaip/echobot-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kdaip/echobot-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kdaip/echobot-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kdaip (https://skillmd.com/u/kdaip)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kdaip/echobot-development

---


# EchoBot Development

Work inside the current repository layout. Keep changes small, readable, and shared across CLI, gateway, and app entrypoints.

## Start here

- Read `AGENTS.md` before non-trivial changes.
- Keep Python 3.11+ code beginner-friendly. Prefer `pathlib`. Keep one clear responsibility per function or class.
- Do not block the event loop. Move blocking file, network, or CPU-heavy work to `asyncio.to_thread(...)` or an executor.
- Find the real entrypoint first: `echobot/cli/main.py`, `echobot/cli/chat.py`, `echobot/cli/gateway.py`, `echobot/cli/app.py`, or `echobot/app/create_app.py`.
- Reuse the shared runtime assembly in `echobot/runtime/bootstrap.py`. If a feature should exist in chat, gateway, and app, wire it there once.

## Choose the right layer

- Change `echobot/orchestration/decision.py` or `echobot/orchestration/route_modes.py` for route selection only.
- Change `echobot/orchestration/roleplay.py` for visible persona replies, delegated acknowledgements, and final presentation only.
- Change `echobot/agent.py`, `echobot/runtime/session_runner.py`, or `echobot/runtime/turns.py` for background agent behavior, tools, skills, memory, and scheduling.
- Change `echobot/tools/` or `echobot/skill_support/` instead of duplicating tool or skill wiring in one entrypoint.
- Change `echobot/commands/` and `echobot/cli/session_commands.py` for `/route`, `/runtime`, `/role`, and session command behavior.
- Change `echobot/app/routers/`, `echobot/app/services/`, and `echobot/app/web/` for HTTP or browser UI behavior.

## Practical workflow

1. Locate the entrypoint and the owning layer.
2. Trace shared wiring through `build_runtime_context(...)`, `ConversationCoordinator`, and `SessionAgentRunner`.
3. Make the smallest coherent change.
4. Add or update focused tests under `tests/`.
5. Run the narrowest useful test group first, then expand if the change crosses subsystem boundaries.

## Shared runtime rules

- Keep one source of truth for sessions, tools, skills, route modes, runtime settings, and scheduling.
- Extend `create_basic_tool_registry(...)` or the tool-registry factory instead of hand-building tool lists for one surface.
- Keep skill behavior inside `echobot/skill_support/` and repository-local skills under `skills/`.
- Preserve the separation between user-facing roleplay context and background agent execution context.
- Use `json.dumps(..., ensure_ascii=False)` for JSON output.
- When changing a project skill, validate it with `python -X utf8 echobot/skills/skill-creator/scripts/quick_validate.py skills/<skill-name>`.

## Focused tests

- Skills or skill runtime: `python -m unittest tests.test_skill_support tests.test_chat_agent -v`
- Agent loop, tools, or traces: `python -m unittest tests.test_agent tests.test_tools tests.test_agent_traces -v`
- Routing, coordinator, or roleplay: `python -m unittest tests.test_decision tests.test_coordinator tests.test_roleplay tests.test_roles -v`
- Commands, gateway, or API: `python -m unittest tests.test_commands tests.test_gateway tests.test_app_api -v`
- Sessions, settings, or scheduler: `python -m unittest tests.test_sessions tests.test_config tests.test_scheduler -v`
- Images, attachments, or TTS: `python -m unittest tests.test_images tests.test_channel_images tests.test_tts -v`

Read `references/architecture.md` before changing more than one subsystem or any shared runtime path.