CH 01 · How to Read and Learning Paths
Chapter Goal
This chapter doesn't teach you any operation. It tells you two things: how to read this book, and the rhythm to learn at. Pick a reading path that fits you, then follow the three-day plan. With a clear map, you won't panic.
Three Reading Paths
Take a look at this diagram first, to get a rough sense:
Path One: Beginner Reads Through (Recommended)
Who it's for: first time with dsh, never run an Agent before.
How to read: start from CH 00 and go chapter by chapter. Finish PART 01 (CH 02–07) in one stretch — clear the "get it running" bar first. Then read CH 09 "Core Subsystems and the Flow of One Message", and only after that revisit CH 08 and CH 10. You'll get the "now I get it" feeling.
Why this order: the early chapters are organized around real tasks; each step lands exactly where the next one needs. Skipping gets you stuck, and unsticking later costs more time.
Path Two: Scenario Direct
Who it's for: you know what you want to do, don't want to read from the top.
How to read: jump straight to a chapter via the table below:
| Your goal | Read this |
|---|---|
| Just get it running | CH 03 → 04 → 05 |
| Understand the architecture before touching anything | CH 08 → 10 |
| Plug into the MCP ecosystem | CH 12 |
| Find ready-made plugins and install them | CH 12 → 17 |
| Make the Agent run on a schedule | CH 15 |
| Run it locally | CH 16 |
| Use dsh to make PPTs / reports / videos | CH 25 → 26 |
| Develop your own plugins | CH 18 → 20 → 21 |
| Take it to production | CH 27 → 28 → 29 |
Chapters you skip via "scenario jump" can be revisited if you get stuck — no shame in that. Nobody finishes it in one pass.
Path Three: On-Demand Depth
Who it's for: you can already run dsh and use it as a reference book.
How to read: when a problem appears, scan the table of contents and jump to the matching chapter, paired with the appendices. Appendix A (Glossary), Appendix B (Command Cheatsheet), Appendix C (Official Docs Index) are the daily three. CH 07 (Troubleshooting Cheatsheet) is worth bookmarking on its own.
Characteristic: no need to read in order; when a chapter blocks you, open it.
Three-Day Learning Path
If you want to power through dsh from end to end in a focused block, the three-day plan below can be followed as-is. Each day is sized for "read while you do" — not pure document reading.
Day 1: Get It Running, Build Intuition
Goal: install dsh, get it running, and know what it can do.
Read: CH 00 → CH 07 (PART 00 + PART 01)
Do:
- CH 03: install Node.js and dsh, launch the Web UI
- CH 04: get familiar with the UI — pick a workspace, pick a model, send your first message
- CH 05: run a headless task once, experience "it works while nobody watches"
- CH 06: connect a third-party model (e.g. a local model or another provider's API)
- CH 07: when an error pops up, walk through the troubleshooting flow
By the end you should be able to: open dsh, send messages, run headless, plug in a third-party model, and read basic errors.
Day 2: Understand the Skeleton, Wire Up Capabilities
Goal: understand what "everything is a plugin" really means, and wire up the common capabilities.
Read: CH 08 → CH 16 (PART 02 + PART 03)
Do:
- CH 08–10: understand the plugin tree, message flow, sessions and trajectory — these three are theory; no code, just comprehension
- CH 11: understand the tool call pipeline and permission approvals
- CH 12: connect an MCP server (e.g. Firecrawl) so the Agent can fetch web pages
- CH 13: try a subagent, experience "delegating work to others"
- CH 14: install a Skill (e.g. AIHOT), so the Agent can use ready-made capabilities
- CH 15: set up a scheduled task so the Agent runs automatically every day
- CH 16: connect a local model, experience "use it without paying"
By the end you should be able to: explain dsh's plugin architecture, connect MCP, use subagents, install Skills, configure scheduled tasks, and plug in a local model.
Day 3: Develop Plugins, Go to Production
Goal: write a plugin of your own, and know how to deploy and operate it.
Read: CH 17 → CH 23 (PART 04) + CH 27 → CH 29 (PART 06)
Do:
- CH 17: learn to install and manage plugins
- CH 18–21: write four plugins following along — minimal, service, tool, hook — get each one running
- CH 22: write a UI plugin and add a new tab to the settings page
- CH 23: understand model adapters (optional read; skip if you're not writing plugins)
- CH 27: use Docker to deploy dsh to a server, bind a domain and configure HTTPS
- CH 28: walk through the security checklist, confirm permissions and credentials
- CH 29: learn to read trajectories, manage context, control cost
By the end you should be able to: write a working plugin, deploy it to a server, and manage security and cost.
The Common Starting Point of All Three Paths
No matter which path you take, spend ten minutes on CH 00 first. It's only three intuitions, no operations involved, yet it lays the foundation for everything after: Agent = Model + Harness, everything is a plugin, why now.
What you learned in this chapter
You pass if you can complete the items below:
- [ ] Name the three reading paths, and know which one a first-time dsh reader should take
- [ ] State the goal → chapter mapping for "scenario jump" (at least remember: MCP → CH 12, plugin development → CH 18)
- [ ] Know what to read and what to do each day of the three-day plan
- [ ] Know that no matter the path, you should read CH 00 first to lay the foundation