用途:构建讲解真实系统的解释器,而非单纯调试部件;尽量同时提供面向读者的叙事层,以及用源码链接、运行时轨迹或实时控件佐证解释的交互产物。若用户已有完成的研读指南且只需展示,改用 interactive-study-guide;若只需狭窄调试面板,用 transparent-ui。
主要能力与原则:叙事决定顺序(借鉴文学化编程,按人类理解顺序而非磁盘文件顺序呈现);证据优先于感觉,每个主要论断须有源码位置、轨迹/日志、测试、类型契约或受控实验支撑;先讲稳定概念(参与者、边界、不变量、happy path),再讲边界情况;让读者做小实验;一次只讲一个子系统。默认交付三件:叙事主线、交互式 playground、源码索引。参考 references/guide-blueprint.md、references/literate-programming.md、references/patterns.md、references/trace-adapters.md。
用法流程:1 校准教学对象(子系统、读者、必答问题、边界);2 建立证据台账(入口、测试、架构文档、状态与编排源文件,提取参与者、输入输出、状态转换、不变量、时序、失败路径、文件锚点);3 设计叙事主线;4 应用文学化编程纪律;5 选择产物形态(内嵌开发路由、独立解释页、混合文档+playground);6 最小且诚实地插桩(优先既有测试/日志,仅限开发环境,记录时间戳与因果元数据);7 构建回答具体问题的面板;8 添加读者实验;9 以教学工具标准验证。
脚手架:若仓库尚无解释包,可用 python3 scripts/scaffold.py <repo-root> "<topic>" --shape docs 初始化(--shape hybrid 适用于 Next.js 式开发路由),创建 guide.md、source-index.md、chunk-manifest.md、reader-lab.md 等。
限制:不编造事实;须防止漂亮但无源码支撑的图表、按仓库顺序的穷举文件导览、无叙事故事的运行时插桩、自信却无代码/测试/轨迹支撑的散文、试图一次讲完整个代码库的单体 playground。本文档未提供具体收费、价格、平台或效果信息。