README_zh.md

JellyFrame 文档索引

最后更新：2026-08-11；适用版本：0.6.0-dev；兼容基线：0.5.0

本目录保存技术文档：模块行为、支持子集、接口和宿主契约，应尽量贴近代码维护。

每份公开 Markdown 文档顶部都有一行轻量新鲜度信息： 最后更新：YYYY-MM-DD；适用版本：VERSION。代码变化后，可以先看这行判断文档是否需要复审。

按角色查找

角色	先读	接着使用
App 作者	../HOW_TO_START_zh.md、app_author_guide_zh.md	能力速查表、recipes、target preset 和 ../tools/README.md
Render Core 贡献者	engine_architecture_zh.md、../src/render_core/README.md	修改模块旁的 scope 文档和能力矩阵
移植维护者	porting_work_guide_zh.md、embedded_hal_api_zh.md	../ports/<port>/README.md、framebuffer/text 文档和移植侧报告
Runtime/host 维护者	../src/app_runtime/README.md	lifecycle、packaging、services 和授权边界文档
Device Runtime 维护者	device_runtime_zh.md	官方板卡 profile、设备协议和 port 接入
Script/runtime 维护者	../src/script/README.md	scripting scope 和跨任务所有权契约
兼容性或工具维护者	能力矩阵和可搜索 HTML/CSS 全表	../tools/README.md、schemas 和工具回归测试

第一次阅读顺序

1. ../HOW_TO_START_zh.md
2. engine_architecture_zh.md
3. 如果要写 app，读 app_author_guide_zh.md。
4. app_author_recipes_zh.md：可复制的小屏 UI 写法。
5. developer_capability_matrix_zh.md
6. 如果要拆分或消费构建边界，读 component_compatibility_matrix_zh.md。
7. 如果要搜索 HTML 或 CSS 特性支持性，读 html_living_standard_support_table_zh.md 或 csswg_support_table_zh.md。
8. 如果要构建本地 app package，读 app_packaging_zh.md。
9. 根据要使用、移植或检查的模块，继续阅读对应模块文档。

技术文档

核心管线

• engine_architecture_zh.md：类浏览器分层和当前取舍。
• html_tokenizer_scope_zh.md：tokenizer 子集、恢复规则和明确裁剪状态。
• html_tree_builder_scope_zh.md：DOM 构建子集和低性能设备限制。
• html_parser_architecture_zh.md：parser 结构、命名和性能规则。
• css_parser_scope_zh.md：CSS syntax、at-rule 和 selector 子集。
• cssom_scope_zh.md：cascade 和 computed style 策略。
• render_tree_scope_zh.md：render tree 构建和面向 layout 的规则。
• layer_tree_scope_zh.md：成层原因、裁剪和降级策略。
• software_renderer_scope_zh.md：CPU renderer、display commands 和明确裁剪。

交互与运行时

• events_scope_zh.md：hit testing、类 DOM event dispatch 和输入裁剪。
• scripting_scope_zh.md：当前 JerryScript 支持范围和不支持的浏览器 API。
• run_loop_contract_zh.md：宿主运行循环顺序、dirty flags 和 repaint planning。

宿主、嵌入式和文本

• host_abstraction_zh.md：资源、时间、framebuffer、文本和预算的薄宿主边界。
• app_packaging_zh.md：app 包格式、manifest 和资源包工作流。
• app_lifecycle_zh.md：面向 app 作者的安装、启动、挂起、恢复、 service completion 和 recovery 生命周期行为。
• device_runtime_zh.md：官方 developer image、设备部署和工具链的产品边界与交付计划。
• authorized_file_broker_zh.md：面向文件管理器和系统组件的宿主持有授权文件访问边界。
• host_optional_services_zh.md：图片/音频/轻量视频、网络数据和安装式 bundle 的可选宿主服务契约。
• ../tools/vscode-jellyframe/README_zh.md： 面向 App 作者的 JellyFrame VS Code 扩展。
• ../tools/schemas/jellyframe.app.schema.json： jellyframe.app.json 的 JSON Schema。
• embedded_hal_api_zh.md：开发板侧 API checklist。
• embedded_framebuffer_backend_zh.md：调用方持有 framebuffer 的转换和 flush 契约。
• text_backend_zh.md：文本测量/绘制 API 和字体工作流。
• embedded_optimization_notes_zh.md：当前优化选择和基准基线。
• porting_work_guide_zh.md：分阶段开发板移植指导。

面向开发者的功能契约

• app_author_guide_zh.md：给 app 作者的短契约、布局 recipes 和 warning 修法。
• app_author_capability_table_zh.md：app 作者快速判断 HTML/CSS/JS/资源能力能不能用。
• app_author_recipes_zh.md：按钮、卡片、滚动列表和固定底部导航等可复制小屏组件写法。
• developer_capability_matrix_zh.md：最主要的 can-do/cannot-do 契约。
• component_compatibility_matrix_zh.md：Core、Runtime、Device OS 和 package consumer 的兼容性证据。
• html_living_standard_support_table_zh.md：可检索的 HTML Living Standard 全量支持表。
• html_living_standard_support_table.csv：同一张表的机器可读版本，供编辑器/工具集成。
• csswg_support_table_zh.md：可检索的 CSSWG 全量支持表。
• csswg_support_table.csv：CSS 表的机器可读版本，供编辑器/工具集成。
• jelly_ui_design_system_zh.md：胶体/水母质感的控件与动效设计体系。
• versioning_zh.md：版本和发布纪律。

文件命名

英文文档使用原文件名，中文文档使用 _zh 后缀，例如 engine_architecture.md 和 engine_architecture_zh.md。