统一目录实体创建与修改¶

CLI 和 MCP 均可调用 owl.catalog.entity_create、owl.catalog.entity_modify。先升级配套 CLI、Registry 和提供目录写入接口的 AIAPI / Backend，再同步目录。实际可用能力与权限以目标站点为准；写操作前核对目标与拟变更内容。

准备类型、团队和实体¶

owl sync
owl exec owl.catalog.entity_type_query -p '{"page_size":20,"page_index":1}'
owl exec owl.workspace.member.group_list -p '{"search":"Platform"}'
owl exec owl.catalog.entity_query -p '{"entity_type":"service","name":"checkout-api"}'

读取所选类型的 schemaDefine 和 customProperties，补齐类型的必填属性；顶层 name 不能代替类型要求的独立属性。动态属性和关系由后端校验。

entity_query 必须提供 entity_type。name 精确匹配，search 模糊搜索名称、展示名或 URN，两者互斥；urn 和 filters 可进一步筛选。filters 使用目录字段语法，不是 SQL/DQL；同时传入 name 和 filters.name 时，两者必须一致。

团队工具返回 group_uuid、name 和 member_count，无分页；owl.member.group_list 是兼容别名。所属团队 attributes.owner 使用返回的团队名称，而非 UUID 或个人姓名，值的形态由类型定义决定。免费版空间不提供团队查询。

创建与局部修改¶

创建必填 request_id（UUID）、entity_type、name；可选 display_name、attributes、relation_modes。name 最长 1024 字符，非空 display_name 最长 256 字符，省略时使用 name。重复身份或同类型同名实体不会被覆盖。

修改必填 request_id 和查询返回的完整 urn；只提交明确要修改的 display_name、attributes、relation_modes。不能重命名 name、改变类型或跨空间写入，也不要把查询 item 整体回写。展示名使用顶层 display_name。

未提交字段保留；对象递归合并，普通数组整体替换，空对象不表示清空，null 不是删除指令。手工写入可能改变 provider 和生命周期。

仅提交类型实际声明的关系字段。修改 depends_on、component_of 或 components 时，每个提交字段均需指定 relation_modes：add 追加去重，replace 整体替换，replace 配合空数组清空；创建默认 replace。关系目标必须是当前空间的真实 URN，不能引用自身；components 不是所有实体类型的通用属性。

写入结果与待确认¶

为每次新操作生成一个 UUID，并持久保存工具、完整参数与身份/空间上下文。不要保存凭据。CLI 使用 -f json 查看完整业务结果；进程退出码 0、HTTP 200 或外层 success 本身不证明写入成功。

成功结果须包含 data.write_state=confirmed、对应的 request_id 和实体 URN。changed=false 可表示成功的无变化操作；replayed=true 不表示再次写入。confirmed 说明实体回读及审计任务投递完成，不代表审计最终入库。

仅在返回 can_retry_write=true 时，后续调用才可能重发业务写入；遵守 retry_after_ms（最多 30000 毫秒）及最多 6 次总提交，仍复用原 UUID 和参数。其他 pending 仅做确认。audit_unknown 不应自动重试。

后端状态按工作空间、实际账号与 request_id 保留 7 天。超过保留期、状态丢失或身份/空间改变后，先查询核对，不把旧 UUID 当作永久防重保证。单次 Owl 调用不会自动轮询或重发业务写入。