Imported from Jack-Liang/ABAP-Render-Kit (
AGENTS.md). Install upstream withnpx skills add Jack-Liang/ABAP-Render-Kit. Copyright stays with the author.
ARK 开发准则（所有开发者与 AI 会话必须遵循）
北极星目标（2026-09-06 由项目所有者确立，长期有效）
ABAP 端尽量少写 HTML。 应用代码只提供"数据和参数"（类型化 state / 声明式 API），框架负责把它们 渲染成 HTML 页面。未来所有开发决策以这条目标为最高准则。
由此推导的开发规则
-
新能力 = 扩展声明层，不是教用户写 HTML。
- 新的展示形态：先考虑给
zif_ark_gui_state加 section 类型 / 字段， 在zcl_ark_state_page实现渲染； - 新的 JS 库/前端能力：走
zif_ark_js_widget（get_assets+render）zcl_ark_js_library注册器，组件内部自含 HTML，业务侧零 HTML；
- 只有逃生舱口（
zcl_ark_html原样 API、set_option_override）可以 暴露原始 HTML/JSON，且必须在文档标注"脚本注入"警告。
- 新的展示形态：先考虑给
-
渲染层纪律。 框架内拼接 HTML 的代码：动态值一律过
zcl_ark_convert=>escape_html（属性/文本）或escape_js（脚本字面量）； 样式进zcl_ark_theme的.ark-*类与 design token，渲染器不写内联颜色。 -
动作路由走约定。 页面动作 =
on_action_<动作名>方法（基类自动分发）， 新示例/文档不得再示范 on_event 里写 CASE 分发（框架内部保留 CASE 除外）。 -
新示例必须是声明式示范。
src/examples的页面要么继承zcl_ark_state_page填 state，要么是组件 API 演示；手写 HTML 字符串的 示例页面不允许新增（发现即迭代掉）。 -
内核基线。 Windows WebView2/Edge 为全功能基线；JavaFX WebView（Java GUI， WebGL 能力因 JavaFX 版本而异——2026-09-06 用户真机实测可渲染 three.js， 勿再断言"无 WebGL"）与 IE 只要求优雅降级并给出可读提示（参考
zcl_ark_three_view， 先尝试创建 WebGL 上下文、失败才降级）。任何新功能不得静默依赖 Edge 独有 API。 -
质量门禁（每次推送前必做）。
npx --yes @abaplint/cli必须 0 issues；- 见
docs/js-extensions.md与根目录abaplint.json； - 历史陷阱清单见项目记忆与 [[ark-abap-template-pitfalls]]：字符串模板
{ expr }空格、接口方法不得用复合名声明、TYPES ... VALUE不上 string 组件、测试助手整体放 testclasses、带 testclasses 的类 XML 必须有WITH_UNIT_TESTS、gui_download 只收绝对路径。
-
破坏性变更允许（项目处于 alpha），但必须：同步更新 MANIFEST.md、 README、
docs/，并在提交信息里写明破坏点与迁移方式。
技术债与降期决策（2026-09-07 框架盘点）
以下事项已评估、明确降期，做与不做以本节为准：
- UI5 路线深化（
zcl_ark_ui5_shell/ui5_page的表格排序/筛选/CSV 映射、 真机验证）：面积为剩余最大，但使用面窄（仅 Edge 内核 + 需要 UI5 运行时的 场景）。降期为实验特性：不再投入常规迭代，仅在破坏性变更时保持可激活； 真机验证并入用户 Windows 环境可用时统一做。 - framework→components 依赖倒置（
zcl_ark_state_page/ui5_shell直接引用zcl_ark_echarts）：monorepo 阶段无害，是未来拆仓库的前置条件而非当前 缺陷。触发条件：拆分 examples/assets 出库时一并处理（接口注入或事件回调）。 - 已完成项（2026-09-07）：导航栈独立类+单测、嵌入式 JS 语法门禁 （tools/js_regress.mjs）、框架文本 i18n（zcl_ark_texts）、忙指示遮罩、 chart_section 多系列、保留动作常量类（zcl_ark_actions）、sparkline 色值 令牌化、viewer~back 死代码清理。
其他长期约定
- 用户通过
git pull（abapGit）安装：修复要当轮 commit+push，不留本地。 - 用户真机环境：SAP GUI for Java（macOS，JavaFX WebView——WebGL 实测可用）+ ABAP Platform 2023 (7.57)。语法保持 7.57 保守。
- 纯前端模板迭代用
demo/*.html（不开 SAP 即可在浏览器验证）。