Kingscript 专家

作为 AI Agent 处理 Kingscript 二开任务的入口 skill 使用。

目录结构

./
├── SKILL.md                                    ← 本文件（通用 skill 入口）
├── README.md                                   ← 使用说明
├── references/                                 ← 共享知识库
│   ├── language/                                ← 语法规范
│   ├── sdk/                                     ← SDK 索引与声明
│   │   ├── indexes/
│   │   ├── classes/
│   │   ├── packages/
│   │   ├── plugins/
│   │   ├── microservices/
│   │   └── manifests/
│   ├── gotchas/                                 ← 公共注意事项与经验
│   │   ├── bigdecimal.md
│   │   ├── bigint.md
│   │   ├── date.md
│   │   ├── dynamicobject.md
│   │   └── README.md
│   ├── docs/                                    ← 各开发类型专属指南
│   │   ├── 脚本控制器开发指南.md
│   │   ├── 业务扩展点开发指南.md
│   │   └── 插件开发指南.md
│   ├── templates/                               ← 各开发类型模板
│   │   ├── kwc-controller-template.md
│   │   ├── extpoint-template.md
│   │   ├── form-plugin-template.md
│   │   ├── bill-plugin-template.md
│   │   ├── ... (其余插件模板)
│   └── examples/                                ← 示例
│       ├── plugins/
│       └── community/
├── install.ps1                                 ← Windows 安装脚本
├── install.sh                                  ← macOS/Linux 安装脚本
├── sdks.zip                                    ← 外部 SDK 扩展包
└── ../bos-plugin-sample-7.0.jar               ← Java 样例 jar（可选，与 skill 同级）

外部可选资源（与 skill 安装目录同级）：

• ../bos-plugin-sample-7.0.jar — Java 样例 jar，用于反编译查找 Java 源码
• ../bos-docs/ — 外部知识盘，仅在仓库内 references/ 不足时使用

固定入口

examples

• references/examples/README.md
• references/examples/plugins/README.md
• references/examples/plugins/插件示例/

gotchas

• references/gotchas/README.md
• references/gotchas/bigdecimal.md
• references/gotchas/bigint.md
• references/gotchas/date.md
• references/gotchas/dynamicobject.md
• references/gotchas/serialization.md

docs

• references/docs/README.md
• references/docs/脚本控制器开发指南.md
• references/docs/业务扩展点开发指南.md
• references/docs/插件开发指南.md

templates

• references/templates/README.md
• references/templates/kwc-controller-template.md
• references/templates/extpoint-template.md

sdk

• references/sdk/README.md
• references/sdk/strategy.md
• references/sdk/indexes/class-index.md
• references/sdk/indexes/method-index.md
• references/sdk/indexes/methods-by-name.md
• references/sdk/indexes/scenario-index.md
• references/sdk/indexes/keyword-index.md

language

• references/language/README.md

优先阅读

1. 先确认 references/ 目录结构完整
2. 再找 references/examples/ 中最接近的示例
3. 如果用户提到 KWC、脚本控制器、controller、REST API、Web API，先读 references/docs/脚本控制器开发指南.md 和 references/templates/kwc-controller-template.md
4. 如果用户提到 扩展点、extension、extpoint、业务扩展，先读 references/docs/业务扩展点开发指南.md 和 references/templates/extpoint-template.md
5. 如果用户提到 插件、plugin、表单插件、单据插件、列表插件、操作插件，先读 references/docs/插件开发指南.md
6. 如果需要插件骨架或占位代码，读 references/templates/README.md
7. 如果涉及 SDK，先读 references/sdk/README.md、strategy.md 和 indexes/
8. 如果涉及语法、关键字或语言限制，读 references/language/README.md
9. 编码/诊断/审查类任务的 gotchas 加载规则见下一节「约束加载策略」，纯概念问答、SDK 符号查询等非编码任务不必加载 gotchas

约束加载策略

所有运行时约束统一收敛到 references/gotchas/，上层 docs/ 指南与 templates/ 模板通过引用使用。gotchas 只在真正需要约束检查的编码类任务中加载，且一次性加载常驻上下文，避免重复 I/O 和上下文污染。

触发条件（按需加载，非无差别加载）

• ✅ 需要加载：生成/修改 KingScript 代码、排查运行时异常、代码风险审查、检查现有代码是否违反约束
• ❌ 无需加载：解释 SDK 类/方法签名、查询符号所在包、介绍插件/扩展点概念、导航目录结构、讨论语法规则

加载规则

• 命中触发条件时一次性完整读入：进入编码/诊断/审查任务的第一步即完整读取 references/gotchas/README.md，加载后常驻当次任务上下文
• 同一任务内不得重复加载：后续整个任务过程中不得再次 read_file 同一文件，即使多次命中「详见坑 X」引用
• 专题文档同规则：bigdecimal.md / bigint.md / date.md / dynamicobject.md / serialization.md 在首次命中对应场景时一次性完整加载并常驻，不重复读取
• 引用仅作定位锚点：docs/ 指南与 templates/ 模板中出现的「详见坑 X」「详见 gotchas/README.md 坑 Y」「详见 xxx.md」等表述，仅用于在已加载的上下文内快速定位约束条目，不触发新的文件读取
• 禁止约束重复罗列：docs/ 与 templates/ 中不得复制 gotchas 中的约束细节（症状/原因/错写法/正写法），只保留「一句话引用 + 专属要点」；发现重复应收敛回 gotchas
• 单向引用不可逆：引用方向固定为 docs/ → gotchas/、templates/ → gotchas/、docs/ → templates/；反向引用（gotchas → docs/templates）严格禁止

降级查找顺序

当 skill 里只给了目录、没有给具体文件时，必须按下面顺序继续收敛，直到落到具体文件，而不是停在目录名上：

1. 先开该目录下的 README.md
2. 再看该目录下的文件名是否已经能直接定位目标
3. 如果只知道类名、方法名、事件名、插件类型，优先回到 sdk/indexes/
4. 如果只知道"场景"，优先回到 examples/plugins/README.md 和对应"场景拆分"目录的 README.md
5. 如果仍然不够，再在目标目录里做关键字检索
6. 索引和 examples 都不够时，再降级到 sdk/manifests/
7. 仍不足时，再看本地 .d.ts、jar 反编译结果或在线 Javadoc

目录级路径的收敛规则

从 examples 收敛

• 已知是插件案例时，先开 references/examples/plugins/README.md
• 再根据插件类别进入 插件示例/表单插件-场景拆分/README.md、插件示例/字段控件-场景拆分/README.md、插件示例/控件-场景拆分/README.md、插件示例/单据体-场景拆分/README.md、插件示例/报表查询插件-场景拆分/README.md 这类目录 README
• 只有目录名时，必须继续打开该目录里的具体 *.md，不能只回答"去这个目录找"

从 docs 收敛

• 已知是 KWC、脚本控制器、Web API、REST API 开发时，先开 references/docs/README.md
• 再进入 references/docs/脚本控制器开发指南.md
• 如果只需要某一块规则，可继续在该文档中检索 permission、url、request、response、version 等关键字

从 sdk 收敛

• 已知类名：references/sdk/indexes/class-index.md
• 已知方法名：references/sdk/indexes/method-index.md，如果没有，再看 methods-by-name.md
• 已知生命周期或插件类型：references/sdk/indexes/plugin-index.md、methods-lifecycle.md
• 已知业务词或场景词：references/sdk/indexes/scenario-index.md、keyword-index.md
• 找到线索后，继续打开 references/sdk/classes/、packages/、plugins/、microservices/ 下的具体文件

从 language 收敛

• 语法总入口先看 references/language/README.md
• 再按主题进入 类.md、方法.md、变量.md、接口.md、异常处理.md、语法示例.md

本地检索方式

如果目录 README 仍然不够，必须继续做本地检索。优先级如下：

1. 优先 rg --files 或 rg -n
2. 如果 rg 不可用或权限异常，改用 PowerShell：

Get-ChildItem -Path 'references/' -Recurse -Include *.md |
  Select-String -Pattern 'SearchEnterEvent|EntryGridBindDataEvent|AbstractReportFormPlugin' -Encoding UTF8

1. 如果要先看目录里有什么文件，用：

Get-ChildItem -Path 'references/examples/plugins/插件示例/控件-场景拆分'

1. 如果要从 jar 里找 Java 来源，用：

jar tf '<java_sample_jar>' | Select-String 'SearchSample|TreeViewSample|ReportColumnMergePlugin'

任务路由

生成或修改代码

• 如果目标是 KWC 脚本控制器，先读 references/docs/脚本控制器开发指南.md 与 references/templates/kwc-controller-template.md
• 如果目标是业务扩展点，先读 references/docs/业务扩展点开发指南.md 与 references/templates/extpoint-template.md
• 如果目标是插件开发，先读 references/docs/插件开发指南.md，再根据插件类型选 references/templates/ 下对应模板
• 如果涉及金额/数值字段，补读 references/gotchas/bigdecimal.md
• 如果涉及日期过滤或 QFilter 日期入参，补读 references/gotchas/date.md
• 如果涉及 QueryServiceHelper.query 或 DynamicObject 字段读取，补读 references/gotchas/dynamicobject.md
• 如果涉及大整数/Long 类型 ID，补读 references/gotchas/bigint.md
• 先读 references/templates/
• 再读 references/examples/ 中最相关的示例
• 生成代码时优先复用已有插件模板和事件写法
• 生成代码前，先确认每个外部类、助手类、事件类、枚举和工具类的真实 import 路径；不能只看到示例里用过就省略 import
• 最终输出代码前，必须逐个自检非全局符号是否已显式 import；不能依赖 IDE、编辑器或运行环境自动补 import
• 如果某个符号不需要 import，必须能明确说明它是运行时全局、当前文件局部定义，或由框架自动注入
• 页面提示、通知、消息框相关方法，必须回到 IFormView 或本地声明层确认，不把示例里出现过的方法名直接当成可用 API
• 调用 obj.method() 前，必须确认 method 属于 obj 当前类型或其声明继承链；不能只因为别的事件参数或上下文对象上有同名方法就直接套用
• 不允许按"近似名字"猜方法；例如声明里是 addItemClickListeners(...)，就不能擅自写成 addItemClickService(...)
• 生成代码时不得把事件参数写成 any；如果当前版本声明只给出 BizDataEventArgs 或 $.java.util.EventObject，也必须按声明原样写

解释 SDK 或 Java 映射

• 先读 references/sdk/README.md
• 再读 references/sdk/strategy.md
• 已知类名时优先读 references/sdk/indexes\class-index.md
• 已知方法名时优先读 references/sdk/indexes\method-index.md；未命中时补读 methods-by-name.md
• 只知道场景时优先读 references/sdk/indexes\scenario-index.md
• 只知道关键词时优先读 references/sdk/indexes\keyword-index.md
• 找到入口后，再读 references/sdk/classes\、packages\、plugins\、microservices\ 下的具体文件
• 索引不足时，再降级到 references/sdk/manifests\
• 如果维护者本地额外挂载了外部知识盘，再按 strategy.md 进入外部扩展层
• 如果 local-paths.json 中配置了 bosdocspath，把它视为外部知识盘主入口；只有仓库内资料不足时才进入
• 命中外部 -description.md 时，先读描述卡；只有需要真实写法、坑点或运行时边界时，再继续读配套 -example.md
• 仍不足时，再读取本地最相关的 .d.ts 或在线 Javadoc

诊断问题或做风险审查

• 按开发类型先读对应指南：KWC → references/docs/脚本控制器开发指南.md；扩展点 → references/docs/业务扩展点开发指南.md；插件 → references/docs/插件开发指南.md
• 运行时报错或类型异常 → references/gotchas/README.md 按症状查坑
• 找同类场景的 references/examples/
• 核对 references/sdk/ 中的类、方法和生命周期说明
• 最后核对 references/language/README.md 及相关语法条目

输出约定

默认采用结构化回答，包含：

1. 场景
2. 假设
3. 代码或方案
4. 风险
5. 待确认问题

不可违背的规则

• 不得编造 Kingscript API、事件名或上下文对象结构
• 不得假设 TypeScript 声明保证运行时可用
• 不得忽略权限、租户隔离或生命周期时序
• 不得定义 static 方法或 static 变量（含类静态字段、static readonly）
• 如果信息缺失，提供有边界的假设方案，而不是虚假的确定答案
• 当用户指出示例、模板或生成代码存在错误时，不能只修当前片段；必须继续判断这个问题是否应沉淀成可复用约束，并按影响范围回写到 SKILL.md、references/sdk/strategy.md、对应知识卡、索引、模板或示例入口，避免同类问题重复生成