Fix&Feat: Template config optimization

[Railgun19457]

Modifications / 改动点

解决的问题

• fix
  • template_list 中 file 类型字段未写 default 时，前端默认值会变成 undefined。
  • AstrBotConfigV4 下复用 TemplateListEditor 时，插件 i18n 和配置路径上下文缺失。
  • 修复模板里添加 file 类型配置项时提示 Config item not found or not file type。
  • 修复 template_list 内文件路径上传/列目录/保存校验路径不一致的问题。
• feat
  • 添加多个同类型模板后，折叠状态下只能看到模板类型，难以区分具体条目。
  • 某些模板 hint 在已添加列表中占空间或重复展示，现在可通过 hide_hint_in_list 隐藏。

更改文件

• dashboard/src/components/shared/TemplateListEditor.vue

  • 支持 file 类型默认值。
  • 新增 display_item，可在折叠列表显示某个 string 字段值。
  • 新增 hide_hint_in_list，可只隐藏已添加条目列表里的模板 hint。
  • 保留添加模板下拉菜单中的 hint 显示。

• dashboard/src/components/shared/AstrBotConfigV4.vue

  • 补齐 pluginName、pluginI18n、pathPrefix 传递。
  • 让 V4 配置项、TemplateListEditor、ConfigItemRenderer 支持插件 i18n 和正确配置路径。

• astrbot/dashboard/routes/util.py

  • get_schema_item() 支持解析 template_list.templates.<template>.items路径。
  • 修复模板内 file 类型字段无法被文件接口识别的问题

• astrbot/dashboard/routes/config.py

  • template_list 保存校验改用模板 schema 路径。
  • 避免模板内 file 上传成功后保存配置时路径校验失败。

• tests/unit/test_dashboard_util.py

  • 新增单元测试覆盖模板内 file 字段、嵌套模板字段、保存路径校验。

• docs/zh/dev/star/guides/plugin-config.md

  • 补充 template_list 的 display_item 和 hide_hint_in_list 中文说明与示例。

• docs/en/dev/star/guides/plugin-config.md

  • 补充 template_list 的 display_item 和 hide_hint_in_list 英文说明与示例。

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

---

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Optimize template-based configuration handling and display in the dashboard, particularly for file-type fields and plugin-driven configs.

New Features:

• Allow template list entries to show a configurable string field value in the collapsed list via the display_item option.
• Support hiding template-level hints from the collapsed template list using the hide_hint_in_list option.
• Propagate plugin name, i18n context, and config path into V4 config items and template lists to enable localized, path-aware rendering.

Bug Fixes:

• Ensure file-type fields in template lists have a proper default value instead of becoming undefined.
• Fix recognition of file-type fields inside templates so file upload APIs and path validation work correctly, including nested templates.
• Align template list save-time path validation with the template schema path to avoid false validation failures for uploaded files.

Enhancements:

• Improve template list entry display styling by highlighting the selected display text field.
• Extend schema lookup utility to resolve template_list templates items paths for more robust config validation and tooling.

Documentation:

• Document the display_item and hide_hint_in_list options for template_list in both English and Chinese plugin config guides, with updated examples.

Tests:

• Add unit tests covering template_list schema resolution for file fields, including nested templates, and validation of file paths based on template schema.

Summary by Sourcery

Optimize template-based configuration handling and display for plugin configs, especially around template_list entries and file-type fields.

New Features:

• Allow templates to specify a display_item string field whose value is shown for each entry in the collapsed template_list.
• Support hide_hint_in_list on templates to hide template hints in the collapsed list while retaining them in the template selector and expanded view.
• Propagate plugin name, i18n context, and config path into V4 config items, TemplateListEditor, and ConfigItemRenderer for localized, path-aware rendering.

Bug Fixes:

• Ensure file-type fields in template_list have a defined default value instead of becoming undefined.
• Fix schema resolution and API recognition for file-type fields inside templates, including nested template_list structures, so file upload and validation work correctly.
• Align template_list save-time path validation with template schema paths to prevent false failures when saving uploaded file paths.

Enhancements:

• Improve collapsed template_list entry display by rendering a highlighted primary display text when configured.
• Extend schema lookup utility to understand template_list.templates..items paths for more robust validation and tooling.

  Documentation:

  • Document the display_item and hide_hint_in_list options for template_list in both English and Chinese plugin configuration guides, with examples.

  Tests:

  • Add unit tests covering template_list schema resolution for file items (including nested templates) and validation of file paths based on template schema.

[gemini-code-assist]

Code Review

This pull request enhances the configuration system by adding support for template_list schema navigation in the backend and improving the WebUI's display of template entries. Key changes include updating get_schema_item to handle nested template paths, introducing display_item and hide_hint_in_list properties for better template entry identification in the UI, and adding unit tests for these new behaviors. Feedback was provided regarding a potential AttributeError in the schema utility when handling malformed templates fields, along with a suggested fix to ensure robust dictionary type checking.

[gemini-code-assist]

The current implementation of get_schema_item is not fully defensive when handling template_list types. If the templates field in the schema exists but is not a dictionary (e.g., it is None or a string due to a malformed schema), meta.get("templates", {}) will return that non-dictionary value, and the subsequent .get() call will raise an AttributeError. It is safer to explicitly verify that templates is a dictionary before attempting to access its keys.

Suggested change

	template_meta = meta.get("templates", {}).get(parts[idx + 2])
	if not isinstance(template_meta, dict):
	return None
	templates = meta.get("templates")
	if not isinstance(templates, dict):
	return None
	template_meta = templates.get(parts[idx + 2])
	if not isinstance(template_meta, dict):
	return None

[sourcery-ai]

Hey - I've left some high level feedback:

• The get_schema_item logic for handling template_list paths is getting fairly complex with index arithmetic and nested branching; consider extracting the template_list-specific traversal into a small helper or restructuring the loop to make the supported path shapes and failure cases easier to read and maintain.
• In TemplateListEditor.vue, both getItemMetaBySelector and getValueBySelector implement their own selector parsing; consolidating this dot-path traversal into a single shared helper would reduce the risk of subtle inconsistencies if the selector semantics evolve.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `get_schema_item` logic for handling `template_list` paths is getting fairly complex with index arithmetic and nested branching; consider extracting the `template_list`-specific traversal into a small helper or restructuring the loop to make the supported path shapes and failure cases easier to read and maintain.
- In `TemplateListEditor.vue`, both `getItemMetaBySelector` and `getValueBySelector` implement their own selector parsing; consolidating this dot-path traversal into a single shared helper would reduce the risk of subtle inconsistencies if the selector semantics evolve.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}