OMERO 元数据与注解安全导出实战Annotation 类型、有界读取与脱敏清单【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsOMERO 服务器中注解Annotation是承载参与者标识、样本名、未发表结果、自由文本、远端文件名与附件的关键对象也是隐私与合规风险最集中的数据面。本文基于本仓库omero-integration技能SKILL.md的元数据参考文档 metadata.md系统讲解 OMERO 结构化注解模型、十种注解类型与omero.gateway包装器、namespace 语义、Map/Tag/Comment/File 四类常用注解的读写姿势并结合 export_image_metadata.py 与 omero_common.py 的源码实现给出只读最少字段、默认脱敏、硬性限额、解链不等于删除的完整实战方案。读完本文你将能安全地完成 OMERO 注解清单导出、有界下载与受审写入工作流。OMERO 结构化注解模型类型清单与包装器OMERO 的结构化注解模型structured annotation model覆盖十种内置类型TagAnnotation受控标签常用于状态标记如 ReviewedMapAnnotation键值对集合适合结构化元数据如实验版本、状态FileAnnotation附件文件可携带任意类型数据CommentAnnotation自由文本评论通常是最敏感的注解类型BooleanAnnotation/LongAnnotation/DoubleAnnotation数值与布尔标记TimestampAnnotation时间戳TermAnnotation本体术语引用XmlAnnotationXML 结构化内容以及通过注解到注解链接annotation-to-annotation links构成的注解层级当前omero.gateway导出了对应的包装器包括TagAnnotationWrapper、MapAnnotationWrapper、FileAnnotationWrapper和CommentAnnotationWrapper。不要导入历史遗留的BaseAnnotationWrapper当前公开的公共包装器是AnnotationWrapper——这一点在 metadata.md 中被明确强调历史代码迁移时最容易踩坑。注解与对象之间是多对多关系一个注解可以链接到多个对象注解本身的归属ownership与每条链接的归属可能不同。因此删除一条链接与删除整个注解是两个完全不同的操作必须分开对待详见下文解链与删除一节。有界读取listAnnotations()没有分页客户端必须自行截断listAnnotations()支持 namespace 过滤但不提供 page-size 分页参数。任何直接list(image.listAnnotations())的写法都可能把某个对象的所有注解一次性拉回客户端。正确做法是使用itertools.islice在客户端做硬性截断并报告是否发生截断from itertools import islice image conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) max_annotations 100 items list(islice(image.listAnnotations(), max_annotations 1)) truncated len(items) max_annotations for annotation in items[:max_annotations]: print(annotation.getId(), annotation.OMERO_CLASS, annotation.getNs()) print({truncated: truncated})这里的关键技巧是多取一个元素来判断截断islice(..., max_annotations 1)使len(items) max_annotations成为可靠的截断信号。仓库中的共享工具take_bounded()omero_common.py正是这一模式的通用封装def take_bounded(iterable, limit): if limit 0: raise ValueError(limit must be non-negative) items list(islice(iterable, limit 1)) return BoundedResult(itemsitems[:limit], truncatedlen(items) limit)测试用例 test_scripts.py 直接验证了这一语义take_bounded(range(5), 3)返回前 3 项且truncatedTrue。更严格的原则不要触碰未获批的值比打印后隐藏更安全的是根本不取回。文档明确警告当数值超出批准的导出范围时不要调用getValue()——仅仅在检索后避免打印安全性弱于不检索。这是因为数据一旦进入客户端内存就可能出现在日志、traceback 或意外序列化中。仓库测试 RedactionTests 用FakeAnnotation验证了这一点当include_valuesFalse时导出记录中value_redactedTrue且注解的getValue()从未被调用self.assertFalse(annotation.value_read)整个记录序列化后不包含任何敏感字符串。按链接查询当需要基于显式父对象 ID 查询注解链接时可调用getAnnotationLinks()。父 ID 列表与返回的链接数量都必须有界image_ids [101, 102] for link in islice( conn.getAnnotationLinks(Image, parent_idsimage_ids), 200, ): print(link.getParent().getId(), link.getChild().getId())脱敏清单只导出标识符与类型不导出值一个安全的默认导出记录只应包含标识符和类型而非具体值。参考实现def annotation_summary(annotation): details annotation.getDetails() owner details.getOwner() if details is not None else None return { id: annotation.getId(), type: annotation.OMERO_CLASS, namespace: annotation.getNs(), owner_id: owner.getId() if owner is not None else None, value_redacted: True, }以下字段在默认情况下都应单独决策是否包含绝不可打包放行所有者用户名owner names注解值annotation values文件名file names描述descriptions链接所有者用户名link-owner names仓库内置导出器的默认脱敏行为仓库提供了export_image_metadata.py源码这是一个面向显式 Image ID 的只读 JSON 导出器默认全部脱敏且分为 dry-run 与 execute 两阶段python -B scripts/export_image_metadata.py \ --image-id 101 \ --max-annotations-per-image 100 \ --max-rois-per-image 100 \ --output ./image-101-metadata.json # Review, then connect. Add inclusion flags only when approved. python -B scripts/export_image_metadata.py \ --image-id 101 \ --max-annotations-per-image 100 \ --max-rois-per-image 100 \ --execute \ --output ./image-101-metadata.json注意这里的命令需要从仓库根目录执行实际脚本路径为 skills/omero-integration/scripts/export_image_metadata.py。该导出器永不下载 FileAnnotation 的字节内容也永不下载像素数据。导出的脱敏策略由redaction_payload()export_image_metadata.py以 JSON 形式显式声明任何一次导出都会自我标注annotation_values_included默认 Falseowner_names_included默认 Falsefile_names_included默认 Falseroi_labels_included默认 Falsefile_bytes_included恒为 Falsepixel_data_included恒为 Falsemask_bytes_included恒为 Falseannotation_record()export_image_metadata.py完整实现了按需包含逻辑未授权时输出value_redacted: true、name_redacted: true对FileAnnotation则输出original_file_id、size_bytes、mimetype与bytes_downloaded: false并把文件名默认置为脱敏。各限制参数的含义与取值范围导出器通过bounded_int()强制校验所有上限omero_common.py每个参数都有明确的取值范围参数默认值取值范围语义--image-id必填正整数显式 Image ID可重复指定重复值会被拒绝--max-images251–100显式图片数量上限--max-annotations-per-image1001–1000每张图片注解条数上限--max-rois-per-image1001–1000每张图片 ROI 序列化上限--max-shapes-per-roi5001–5000每个 ROI 的形状数量上限--max-string-length51232–4096导出字符串的最大长度--max-value-items1001–1000被包含注解值中的最大元素数--group-id无正整数显式组上下文不支持跨组-1--include-annotation-values关开关包含有界注解值默认脱敏--include-owner-names关开关包含注解所有者用户名默认仅 ID--include-file-names关开关包含 FileAnnotation 文件名默认脱敏--include-roi-labels关开关包含形状文本标签默认脱敏--output必填路径必须以.json结尾位于已存在目录--overwrite关开关仅可替换普通文件绝不可经由符号链接--execute关开关无此标志只输出 dry-run 计划不连接服务器--allow-insecure-transport关开关显式策略审查后才允许OMERO_SECUREfalsedry-run 模式输出server_contacted: false、output_not_written: true、完整的 scope 与 redaction 声明并提示next_step: Review scope/redaction, then add --execute.。连接只在--execute时发生且omero包是惰性导入参数解析之后才导入确保--help无需安装 OMERO 即可工作详见 scripts.md。Namespace为注解赋予语义的命名空间机制Namespace 让工具可以给注解赋予语义并实现按需过滤for annotation in image.listAnnotations(nsorg.example.analysis.v1): print(annotation.getId())使用自定义 namespace 时必须遵守两条纪律使用组织可控的 URI 或反向域名模式并记录其 schema 与版本不要把自定义 namespace 宣称成 OME 标准。客户端 map 注解的标准 namespace 常量位于from omero.constants.metadata import NSCLIENTMAPANNOTATIONOME 的 Python 示例特别警告一个 client map annotation 应该只链接到一个对象。当使用该 namespace 时每个目标对象都要创建独立的 map annotation不可复用同一个实例跨对象链接。Map Annotation键值对的读取与受审写入读取仅在获批后读取键值对并施加多重独立限制from omero.gateway import MapAnnotationWrapper for annotation in image.listAnnotations(nsorg.example.analysis.v1): if isinstance(annotation, MapAnnotationWrapper): pairs annotation.getValue() for key, value in pairs[:50]: print(key, value)限制必须独立施加在四个维度上注解条数、键值对数量、键长度、值长度。特别要警惕键同样可能敏感——一个值已脱敏的导出如果让参与者 ID 留在键里那么它并没有真正脱敏。底层实现中json_safe()omero_common.py为嵌套结构提供了完整的边界保障字符串超长时截断并追加…[truncated]标记集合超长时在末尾追加{truncated_items: N}字节对象输出{bytes_omitted: len}非有限浮点输出{non_finite_float: ...}嵌套深度超过 8 层时输出{omitted: maximum nesting depth exceeded}。测试 BoundTests.test_json_safe_bounds_nested_values 验证了超长字符串与超长集合均会被正确截断并标记。创建与链接一次写入需要前置审批from omero.constants.metadata import NSCLIENTMAPANNOTATION from omero.gateway import MapAnnotationWrapper image conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) pairs [[Analysis version, 2.1], [Status, reviewed]] annotation MapAnnotationWrapper(conn) annotation.setNs(NSCLIENTMAPANNOTATION) annotation.setValue(pairs) annotation.save() image.linkAnnotation(annotation)运行这段代码之前metadata.md 要求逐项确认确认 Image ID 与所属组group确认写入权限与 namespace校验键值对数量与字符串长度决定save 成功但链接创建失败时的回滚策略绝不因为此前查询作用域落在错误的组就重复创建一份本不存在的元数据即先查证再写入避免用写入掩盖查询错误。Tag 与 Comment创建与链接是两次独立写入受控标签Tagfrom omero.gateway import TagAnnotationWrapper tag TagAnnotationWrapper(conn) tag.setValue(Reviewed) tag.setDescription(Reviewed under protocol v2) tag.save() image conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) image.linkAnnotation(tag)标签的创建与链接是两次独立的写入。写之前必须先查询是否已存在受控标签controlled tag并检查组与所有者的语义——不要复用来自意外组的同名标签。同名的标签在不同组中可能是完全不同的实体。评论Comment评论是自由文本往往是最敏感的注解类型。规则明确不要将评论纳入通用清单general inventory绝不把不可信的评论内容传入 shell、HTML、SQL/HQL、文件名或动态代码——自由文本是最经典的注入向量。File Annotation检查元数据而不下载字节只读元数据检查对附件应先看元数据、后决定是否下载from omero.gateway import FileAnnotationWrapper for annotation in image.listAnnotations(): if isinstance(annotation, FileAnnotationWrapper): original annotation.getFile() print( { annotation_id: annotation.getId(), original_file_id: original.getId(), size: original.getSize(), mimetype: original.getMimetype(), name_redacted: True, } )远端文件名是不可信输入绝不能直接拼接到本地输出目录。这一点与 data_access.md 中omero download的路径安全约束一致本地目标路径必须由调用方选择且拒绝符号链接与碰撞。有界下载单文件、字节上限、调用方指定路径只有在一个明确获批的文件上才允许下载且必须同时满足字节上限、路径安全与流式计数三重约束from pathlib import Path max_bytes 50 * 1024 * 1024 destination Path(./approved-result.bin) original file_annotation.getFile() if original.getSize() max_bytes: raise ValueError(File exceeds approved byte limit) if destination.exists() or destination.is_symlink(): raise FileExistsError(destination) written 0 with destination.open(xb) as handle: for chunk in file_annotation.getFileInChunks(): written len(chunk) if written max_bytes: raise ValueError(Received more than approved byte limit) handle.write(chunk)要点解读original.getSize()只做预检流式写入时还要按累计字节数做实时复核防止服务端返回超出声明的大小xb独占创建模式与exists()/is_symlink()双重检查共同防止覆盖与符号链接攻击失败时若策略允许删除本地部分文件不要在未持有显式文件清单时下载 Project/Dataset 下挂载的全部 FileAnnotation。仓库导出器在服务端侧也贯彻同一原则annotation_record()对 FileAnnotation 只序列化original_file_id、size_bytes、mimetype与bytes_downloaded: false且仅在--include-file-names获批时才包含文件名export_image_metadata.py。上传一次变更操作source ./approved-analysis.csv annotation conn.createFileAnnfromLocalFile( source, mimetypetext/csv, nsorg.example.analysis.v1, descReviewed analysis results, ) dataset.linkAnnotation(annotation)执行前必须检查本地文件大小、类型、内容分类、目标 Dataset ID/组以及是否被授权上传。数值与布尔注解值必须结合 schema 解释包装器导入方式from omero.gateway import ( BooleanAnnotationWrapper, DoubleAnnotationWrapper, LongAnnotationWrapper, )数值本身不携带单位与语义必须由 namespace/schema 提供。不要推断DoubleAnnotation的值单位是微米也不要把LongAnnotation当作计数——脱离 schema 解释数值是最常见的元数据误用方式。解链与删除两个必须严格区分的操作解链Unlink删除对象与注解之间的链接但保留注解本身及其与其他对象的链接删除注解Delete annotation删除注解对象可能影响每一个被链接的对象。执行任一操作前metadata.md 给出了六步检查清单检索并显示确切的链接/注解 ID统计其他链接的数量验证所有权与权限获得针对确切操作的明确批准不要用 namespace 级的批量删除绕过 ID 审查等待并检查命令完成状态。此外只读导出工具绝不应包含 delete/unlink 模式——这正是 export_image_metadata.py 等仓库内置导出器被设计为纯只读的原因--execute只是批准一次只读连接而不是扩大范围或允许变更scripts.md 明确说明。Metadata Export 完整检查清单将上述原则收敛为一份可执行的导出前检查单源自 metadata.md显式的对象类型与 ID 列表单一组上下文one group context最大对象数、注解数、链接数、键值对数与字符串长度默认脱敏值values redacted by default文件名与所有者名分别独立授权无附件字节除非单个文件与字节上限均已获批输出路径由调用方选择无远端派生路径原子写入且权限仅所有者可读owner-only permissions连接在finally中关闭最后三条与 omero_common.py 的实现完全对应atomic_write_json()L383-L443通过tempfile.mkstempos.replace实现原子写入以os.fchmod(descriptor, 0o600)和os.chmod(target, 0o600)保证 0600 私有权限并拒绝符号链接目标测试 OutputTests.test_atomic_json_refuses_overwrite_and_uses_private_mode 验证了 0600 模式与覆盖拒绝gateway_session()L207-L255以上下文管理器保证连接即使在部分失败时也会关闭。仓库测试在无真实 OMERO 服务器的条件下运行使用 fake gateway 对象与临时目录因此你可以放心地通过 tests/omero-integration/test_scripts.py 验证全部脱敏与边界语义PYTHONDONTWRITEBYTECODE1 \ python -B -m unittest discover \ -s tests/omero-integration \ -p test_*.py延伸阅读本主题与 OMERO 技能的其他参考文档互为补充推荐按需查阅连接、会话、组与 TLSreferences/connection.md对象层级、分页与传输references/data_access.md本地辅助脚本与 OMERO.server 脚本模型references/scripts.mdROI 模型与形状导出references/rois.md技能总览与操作契约Operating ContractSKILL.md【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OMERO 元数据与注解安全导出实战：Annotation 类型、有界读取与脱敏清单
OMERO 元数据与注解安全导出实战Annotation 类型、有界读取与脱敏清单【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsOMERO 服务器中注解Annotation是承载参与者标识、样本名、未发表结果、自由文本、远端文件名与附件的关键对象也是隐私与合规风险最集中的数据面。本文基于本仓库omero-integration技能SKILL.md的元数据参考文档 metadata.md系统讲解 OMERO 结构化注解模型、十种注解类型与omero.gateway包装器、namespace 语义、Map/Tag/Comment/File 四类常用注解的读写姿势并结合 export_image_metadata.py 与 omero_common.py 的源码实现给出只读最少字段、默认脱敏、硬性限额、解链不等于删除的完整实战方案。读完本文你将能安全地完成 OMERO 注解清单导出、有界下载与受审写入工作流。OMERO 结构化注解模型类型清单与包装器OMERO 的结构化注解模型structured annotation model覆盖十种内置类型TagAnnotation受控标签常用于状态标记如 ReviewedMapAnnotation键值对集合适合结构化元数据如实验版本、状态FileAnnotation附件文件可携带任意类型数据CommentAnnotation自由文本评论通常是最敏感的注解类型BooleanAnnotation/LongAnnotation/DoubleAnnotation数值与布尔标记TimestampAnnotation时间戳TermAnnotation本体术语引用XmlAnnotationXML 结构化内容以及通过注解到注解链接annotation-to-annotation links构成的注解层级当前omero.gateway导出了对应的包装器包括TagAnnotationWrapper、MapAnnotationWrapper、FileAnnotationWrapper和CommentAnnotationWrapper。不要导入历史遗留的BaseAnnotationWrapper当前公开的公共包装器是AnnotationWrapper——这一点在 metadata.md 中被明确强调历史代码迁移时最容易踩坑。注解与对象之间是多对多关系一个注解可以链接到多个对象注解本身的归属ownership与每条链接的归属可能不同。因此删除一条链接与删除整个注解是两个完全不同的操作必须分开对待详见下文解链与删除一节。有界读取listAnnotations()没有分页客户端必须自行截断listAnnotations()支持 namespace 过滤但不提供 page-size 分页参数。任何直接list(image.listAnnotations())的写法都可能把某个对象的所有注解一次性拉回客户端。正确做法是使用itertools.islice在客户端做硬性截断并报告是否发生截断from itertools import islice image conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) max_annotations 100 items list(islice(image.listAnnotations(), max_annotations 1)) truncated len(items) max_annotations for annotation in items[:max_annotations]: print(annotation.getId(), annotation.OMERO_CLASS, annotation.getNs()) print({truncated: truncated})这里的关键技巧是多取一个元素来判断截断islice(..., max_annotations 1)使len(items) max_annotations成为可靠的截断信号。仓库中的共享工具take_bounded()omero_common.py正是这一模式的通用封装def take_bounded(iterable, limit): if limit 0: raise ValueError(limit must be non-negative) items list(islice(iterable, limit 1)) return BoundedResult(itemsitems[:limit], truncatedlen(items) limit)测试用例 test_scripts.py 直接验证了这一语义take_bounded(range(5), 3)返回前 3 项且truncatedTrue。更严格的原则不要触碰未获批的值比打印后隐藏更安全的是根本不取回。文档明确警告当数值超出批准的导出范围时不要调用getValue()——仅仅在检索后避免打印安全性弱于不检索。这是因为数据一旦进入客户端内存就可能出现在日志、traceback 或意外序列化中。仓库测试 RedactionTests 用FakeAnnotation验证了这一点当include_valuesFalse时导出记录中value_redactedTrue且注解的getValue()从未被调用self.assertFalse(annotation.value_read)整个记录序列化后不包含任何敏感字符串。按链接查询当需要基于显式父对象 ID 查询注解链接时可调用getAnnotationLinks()。父 ID 列表与返回的链接数量都必须有界image_ids [101, 102] for link in islice( conn.getAnnotationLinks(Image, parent_idsimage_ids), 200, ): print(link.getParent().getId(), link.getChild().getId())脱敏清单只导出标识符与类型不导出值一个安全的默认导出记录只应包含标识符和类型而非具体值。参考实现def annotation_summary(annotation): details annotation.getDetails() owner details.getOwner() if details is not None else None return { id: annotation.getId(), type: annotation.OMERO_CLASS, namespace: annotation.getNs(), owner_id: owner.getId() if owner is not None else None, value_redacted: True, }以下字段在默认情况下都应单独决策是否包含绝不可打包放行所有者用户名owner names注解值annotation values文件名file names描述descriptions链接所有者用户名link-owner names仓库内置导出器的默认脱敏行为仓库提供了export_image_metadata.py源码这是一个面向显式 Image ID 的只读 JSON 导出器默认全部脱敏且分为 dry-run 与 execute 两阶段python -B scripts/export_image_metadata.py \ --image-id 101 \ --max-annotations-per-image 100 \ --max-rois-per-image 100 \ --output ./image-101-metadata.json # Review, then connect. Add inclusion flags only when approved. python -B scripts/export_image_metadata.py \ --image-id 101 \ --max-annotations-per-image 100 \ --max-rois-per-image 100 \ --execute \ --output ./image-101-metadata.json注意这里的命令需要从仓库根目录执行实际脚本路径为 skills/omero-integration/scripts/export_image_metadata.py。该导出器永不下载 FileAnnotation 的字节内容也永不下载像素数据。导出的脱敏策略由redaction_payload()export_image_metadata.py以 JSON 形式显式声明任何一次导出都会自我标注annotation_values_included默认 Falseowner_names_included默认 Falsefile_names_included默认 Falseroi_labels_included默认 Falsefile_bytes_included恒为 Falsepixel_data_included恒为 Falsemask_bytes_included恒为 Falseannotation_record()export_image_metadata.py完整实现了按需包含逻辑未授权时输出value_redacted: true、name_redacted: true对FileAnnotation则输出original_file_id、size_bytes、mimetype与bytes_downloaded: false并把文件名默认置为脱敏。各限制参数的含义与取值范围导出器通过bounded_int()强制校验所有上限omero_common.py每个参数都有明确的取值范围参数默认值取值范围语义--image-id必填正整数显式 Image ID可重复指定重复值会被拒绝--max-images251–100显式图片数量上限--max-annotations-per-image1001–1000每张图片注解条数上限--max-rois-per-image1001–1000每张图片 ROI 序列化上限--max-shapes-per-roi5001–5000每个 ROI 的形状数量上限--max-string-length51232–4096导出字符串的最大长度--max-value-items1001–1000被包含注解值中的最大元素数--group-id无正整数显式组上下文不支持跨组-1--include-annotation-values关开关包含有界注解值默认脱敏--include-owner-names关开关包含注解所有者用户名默认仅 ID--include-file-names关开关包含 FileAnnotation 文件名默认脱敏--include-roi-labels关开关包含形状文本标签默认脱敏--output必填路径必须以.json结尾位于已存在目录--overwrite关开关仅可替换普通文件绝不可经由符号链接--execute关开关无此标志只输出 dry-run 计划不连接服务器--allow-insecure-transport关开关显式策略审查后才允许OMERO_SECUREfalsedry-run 模式输出server_contacted: false、output_not_written: true、完整的 scope 与 redaction 声明并提示next_step: Review scope/redaction, then add --execute.。连接只在--execute时发生且omero包是惰性导入参数解析之后才导入确保--help无需安装 OMERO 即可工作详见 scripts.md。Namespace为注解赋予语义的命名空间机制Namespace 让工具可以给注解赋予语义并实现按需过滤for annotation in image.listAnnotations(nsorg.example.analysis.v1): print(annotation.getId())使用自定义 namespace 时必须遵守两条纪律使用组织可控的 URI 或反向域名模式并记录其 schema 与版本不要把自定义 namespace 宣称成 OME 标准。客户端 map 注解的标准 namespace 常量位于from omero.constants.metadata import NSCLIENTMAPANNOTATIONOME 的 Python 示例特别警告一个 client map annotation 应该只链接到一个对象。当使用该 namespace 时每个目标对象都要创建独立的 map annotation不可复用同一个实例跨对象链接。Map Annotation键值对的读取与受审写入读取仅在获批后读取键值对并施加多重独立限制from omero.gateway import MapAnnotationWrapper for annotation in image.listAnnotations(nsorg.example.analysis.v1): if isinstance(annotation, MapAnnotationWrapper): pairs annotation.getValue() for key, value in pairs[:50]: print(key, value)限制必须独立施加在四个维度上注解条数、键值对数量、键长度、值长度。特别要警惕键同样可能敏感——一个值已脱敏的导出如果让参与者 ID 留在键里那么它并没有真正脱敏。底层实现中json_safe()omero_common.py为嵌套结构提供了完整的边界保障字符串超长时截断并追加…[truncated]标记集合超长时在末尾追加{truncated_items: N}字节对象输出{bytes_omitted: len}非有限浮点输出{non_finite_float: ...}嵌套深度超过 8 层时输出{omitted: maximum nesting depth exceeded}。测试 BoundTests.test_json_safe_bounds_nested_values 验证了超长字符串与超长集合均会被正确截断并标记。创建与链接一次写入需要前置审批from omero.constants.metadata import NSCLIENTMAPANNOTATION from omero.gateway import MapAnnotationWrapper image conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) pairs [[Analysis version, 2.1], [Status, reviewed]] annotation MapAnnotationWrapper(conn) annotation.setNs(NSCLIENTMAPANNOTATION) annotation.setValue(pairs) annotation.save() image.linkAnnotation(annotation)运行这段代码之前metadata.md 要求逐项确认确认 Image ID 与所属组group确认写入权限与 namespace校验键值对数量与字符串长度决定save 成功但链接创建失败时的回滚策略绝不因为此前查询作用域落在错误的组就重复创建一份本不存在的元数据即先查证再写入避免用写入掩盖查询错误。Tag 与 Comment创建与链接是两次独立写入受控标签Tagfrom omero.gateway import TagAnnotationWrapper tag TagAnnotationWrapper(conn) tag.setValue(Reviewed) tag.setDescription(Reviewed under protocol v2) tag.save() image conn.getObject(Image, image_id) if image is None: raise LookupError(Image unavailable) image.linkAnnotation(tag)标签的创建与链接是两次独立的写入。写之前必须先查询是否已存在受控标签controlled tag并检查组与所有者的语义——不要复用来自意外组的同名标签。同名的标签在不同组中可能是完全不同的实体。评论Comment评论是自由文本往往是最敏感的注解类型。规则明确不要将评论纳入通用清单general inventory绝不把不可信的评论内容传入 shell、HTML、SQL/HQL、文件名或动态代码——自由文本是最经典的注入向量。File Annotation检查元数据而不下载字节只读元数据检查对附件应先看元数据、后决定是否下载from omero.gateway import FileAnnotationWrapper for annotation in image.listAnnotations(): if isinstance(annotation, FileAnnotationWrapper): original annotation.getFile() print( { annotation_id: annotation.getId(), original_file_id: original.getId(), size: original.getSize(), mimetype: original.getMimetype(), name_redacted: True, } )远端文件名是不可信输入绝不能直接拼接到本地输出目录。这一点与 data_access.md 中omero download的路径安全约束一致本地目标路径必须由调用方选择且拒绝符号链接与碰撞。有界下载单文件、字节上限、调用方指定路径只有在一个明确获批的文件上才允许下载且必须同时满足字节上限、路径安全与流式计数三重约束from pathlib import Path max_bytes 50 * 1024 * 1024 destination Path(./approved-result.bin) original file_annotation.getFile() if original.getSize() max_bytes: raise ValueError(File exceeds approved byte limit) if destination.exists() or destination.is_symlink(): raise FileExistsError(destination) written 0 with destination.open(xb) as handle: for chunk in file_annotation.getFileInChunks(): written len(chunk) if written max_bytes: raise ValueError(Received more than approved byte limit) handle.write(chunk)要点解读original.getSize()只做预检流式写入时还要按累计字节数做实时复核防止服务端返回超出声明的大小xb独占创建模式与exists()/is_symlink()双重检查共同防止覆盖与符号链接攻击失败时若策略允许删除本地部分文件不要在未持有显式文件清单时下载 Project/Dataset 下挂载的全部 FileAnnotation。仓库导出器在服务端侧也贯彻同一原则annotation_record()对 FileAnnotation 只序列化original_file_id、size_bytes、mimetype与bytes_downloaded: false且仅在--include-file-names获批时才包含文件名export_image_metadata.py。上传一次变更操作source ./approved-analysis.csv annotation conn.createFileAnnfromLocalFile( source, mimetypetext/csv, nsorg.example.analysis.v1, descReviewed analysis results, ) dataset.linkAnnotation(annotation)执行前必须检查本地文件大小、类型、内容分类、目标 Dataset ID/组以及是否被授权上传。数值与布尔注解值必须结合 schema 解释包装器导入方式from omero.gateway import ( BooleanAnnotationWrapper, DoubleAnnotationWrapper, LongAnnotationWrapper, )数值本身不携带单位与语义必须由 namespace/schema 提供。不要推断DoubleAnnotation的值单位是微米也不要把LongAnnotation当作计数——脱离 schema 解释数值是最常见的元数据误用方式。解链与删除两个必须严格区分的操作解链Unlink删除对象与注解之间的链接但保留注解本身及其与其他对象的链接删除注解Delete annotation删除注解对象可能影响每一个被链接的对象。执行任一操作前metadata.md 给出了六步检查清单检索并显示确切的链接/注解 ID统计其他链接的数量验证所有权与权限获得针对确切操作的明确批准不要用 namespace 级的批量删除绕过 ID 审查等待并检查命令完成状态。此外只读导出工具绝不应包含 delete/unlink 模式——这正是 export_image_metadata.py 等仓库内置导出器被设计为纯只读的原因--execute只是批准一次只读连接而不是扩大范围或允许变更scripts.md 明确说明。Metadata Export 完整检查清单将上述原则收敛为一份可执行的导出前检查单源自 metadata.md显式的对象类型与 ID 列表单一组上下文one group context最大对象数、注解数、链接数、键值对数与字符串长度默认脱敏值values redacted by default文件名与所有者名分别独立授权无附件字节除非单个文件与字节上限均已获批输出路径由调用方选择无远端派生路径原子写入且权限仅所有者可读owner-only permissions连接在finally中关闭最后三条与 omero_common.py 的实现完全对应atomic_write_json()L383-L443通过tempfile.mkstempos.replace实现原子写入以os.fchmod(descriptor, 0o600)和os.chmod(target, 0o600)保证 0600 私有权限并拒绝符号链接目标测试 OutputTests.test_atomic_json_refuses_overwrite_and_uses_private_mode 验证了 0600 模式与覆盖拒绝gateway_session()L207-L255以上下文管理器保证连接即使在部分失败时也会关闭。仓库测试在无真实 OMERO 服务器的条件下运行使用 fake gateway 对象与临时目录因此你可以放心地通过 tests/omero-integration/test_scripts.py 验证全部脱敏与边界语义PYTHONDONTWRITEBYTECODE1 \ python -B -m unittest discover \ -s tests/omero-integration \ -p test_*.py延伸阅读本主题与 OMERO 技能的其他参考文档互为补充推荐按需查阅连接、会话、组与 TLSreferences/connection.md对象层级、分页与传输references/data_access.md本地辅助脚本与 OMERO.server 脚本模型references/scripts.mdROI 模型与形状导出references/rois.md技能总览与操作契约Operating ContractSKILL.md【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考