Skip to content

Loading and Validation

This content is not available in your language yet.

  • Workspace 配置在首次访问时加载
  • 文件变更通过 mtime 或 hash 触发缓存失效
  • 运行时维护基于 workspace 的内存缓存

.openharness/data/ 是运行时托管资源,不参与能力定义加载:

路径说明
.openharness/data/运行时数据目录
.openharness/data/history.db本地 SQLite 运行时数据文件
  • 首次需要时由 runtime 自动创建
  • 缺失或损坏不影响 workspace 配置加载
场景行为
YAML 语法错误标记该定义加载失败
单个定义失败不影响整个 workspace
Agent 引用不存在的能力该 run 失败并返回明确错误
history.db 不可用不影响配置加载

加载时执行以下校验:

校验项说明
Frontmatter 解析Agent Markdown frontmatter 可解析性
YAML 解析所有 YAML 文件语法正确
JSON Schema按对应 schema 校验结构
引用存在性agent model / model_ref、action、skill、tool 引用目标存在
名称唯一性同层级内名称不重复
工具名冲突暴露名称不冲突

Schema 文件:

类型Schema
settingssettings.schema.json
promptsprompts.schema.json
modelsmodels.schema.json
actionaction.schema.json
MCP toolsmcp-settings.schema.json
hookhook.schema.json

Agent 不使用 JSON Schema 强约束,运行时校验 frontmatter 可解析性、model / model.model_ref 存在性、tools 引用存在性。

Error: Failed to parse .openharness/hooks/block-cmd.yaml: unexpected token

原因:缩进不正确或使用了 tab。用 YAML linter 检查,确保一致使用空格。

Error: Unknown workspace model alias "default" in agent builder model.

检查 .openharness/settings.yaml 的 models 是否声明了对应别名,并确认它解析到存在的 platform/<name> 或 workspace/<name>。

Error: Duplicate skill name "repo-explorer" found in .openharness/skills/

同一 skill 根目录下出现同名目录。重命名其中一个确保唯一。

Warning: MCP server "docs-server" failed to start: ENOENT node ./servers/docs-server/index.js

检查 .openharness/tools/settings.yaml 中 command 路径是否正确,确保文件存在且有执行权限。