为 dsh 的重要文档写的中文导读：它讲什么、为什么重要、怎么读。导读不是翻译，读完请一定点原文。
第一次接触 dsh，从这里开始（建议按顺序读）。
理解 dsh 的设计、数据模型与运行时。
dsh 的灵魂文档：Cordis 插件树、profile/bundle 组合机制、核心包与事件分类。
docs/architecture.md
读 dsh 任何源码前的前置知识：插件、context、依赖注入、类型化事件、可逆 effect。
docs/cordis-primer.md
一次对话回合内部发生了什么：收件箱、pre-step 瀑布、持久事实与活体状态的双轨设计。
docs/agent-lifecycle.md
从模型吐出 tool-call 到结果落账，dsh 如何用 pre/execute/post 三段瀑布插入策略、沙箱与审批。
docs/tool-execution-pipeline.md
一张生成图看懂服务声明方、实现方、消费方的关系——「换实现」在 dsh 里意味着什么。
docs/capability-seams.md
dsh README 引用的论文：把「效果」（effect）与「余效果」（coeffect）两个经典概念搬进运行时，给插件系统一个形式化地基。
A Programming Paradigm for Spatiotemporal Composability (arXiv:2608.25512)
一次 agent 对话在 dsh 内部长什么样：只增事件日志、工具定义的完整契约、消息与流式词汇表。
docs/subsystems/session.md · tools.md · llm-streaming.md
dsh 全部事件的「派发方 × 监听方」矩阵——挂 hook 前必查，也是理解插件如何解耦的说明书。
docs/event-producer-consumer.md
值得抄走的开发流程与治理机制。
dsh 最独特的机制：每个非平凡变更强制附决策笔记，生命周期与分类全部路径编码，含中英双语。
.agents/notes/README.md
从零到 typecheck 通过：工具链版本、hooks、仓库目录结构的官方口径。
docs/development.md
dsh 的开发规范入口：不是给人看的 README，而是写给 AI 协作者的岗位说明书。
AGENTS.md
一个开源 agent 框架把故障复盘写成公开文档：三份代表性复盘的故事与共性教训。
docs/postmortem/
跑起来、写插件、程序化接入。
215k star 的仓库不开 PR？官方口径：代码不是唯一的贡献方式，生态才是。
CONTRIBUTING.md
官方安全声明：未经审计、沙箱不保证隔离、风险自担。读完全文再决定给它什么权限。
SAFETY.md
给 dsh 写插件的推荐路径：先跑通教程，再按 cookbook 的契约清单写生产级工具。
docs/cookbook/adding-a-tool.md · docs/user/develop/ · docs/cordis-tutorial/
从 npx 启动到跑通第一个任务：配模型、选工作区、发任务的三步上手指南。
docs/user/guide/index.md
不写 TypeScript 也能用 dsh：Python SDK 怎么包装 dsh、以及官方基准的跑法。
docs/user/guide/python-sdk.md · BENCHMARK.md · python/