Waafir
本页面为机器翻译,尚待人工审核,可能存在错误。

waafir-redact 参考

waafir-redact 服务器以两种形式向已连接的 AI 客户端提供 Waafir 的脱敏功能:

  • redact_text — 一段文本,以内联方式脱敏并立即返回。
  • redact_file / redact_file_status — 数据室中的整个文档,经过 PII 分析并准备好供人工审核。

将脱敏应用到文档上的操作被有意设计为不通过 MCP 提供。应用脱敏会改变其他所有参与方打开文件时看到的内容,因此必须由人在 AI 脱敏审核界面中批准。此服务器上没有任何工具会改变任何读者所看到的内容。

连接:https://app.waafir.io/api/mcp/waafir,或领域服务器 https://app.waafir.io/api/mcp/waafir-redact;两者上的工具名称相同,请参阅设置。redact_text 只需要 read 权限范围(或更高)的 PAT:它不涉及任何数据室,因此无需通过逐文件或逐数据室的检查(但与所有运行模型的工具一样,它仍需要付费套餐并启用 AI)。

两个文档工具都仅限交易团队使用。 redact_file 需要 write 权限范围以及该数据室的交易团队成员身份;redact_file_status 也是如此,尽管它只是读取:read 权限范围的 PAT 是必要条件但不是充分条件,因为脱敏作业的存在本身就是关于该文档的一项事实。交易团队之外的调用者会收到 FORBIDDEN,无论令牌具有何种权限范围。令牌权限范围是令牌的上限;交易团队成员身份是人的上限,两者都必须满足。

redact_text

对一段文本中的 PII 进行脱敏。文本由您组织的脱敏智能体处理,工具会返回脱敏后的文本以及它识别出的实体列表。您还可以选择将结果限定为特定的实体类型。

输入

字段类型必填说明
textstring是要脱敏的文本(不能为空)。
typesstring[]否仅对这些 PII 类型进行脱敏。省略则对检测到的所有内容进行脱敏。

输出

{ redacted_text, entities, truncated, processed_chars, total_chars, max_chars,
  filtered_out_count, unclassified_redacted_count, unclassified_types,
  filter_exact }
  • redacted_text — 经过分析、敏感片段已被涂黑的文本。
  • entities — 被移除的 PII。type 是脱敏模型使用的标签;canonical_type 是它所对应的标准类型,如果无法归类则为 null。
  • truncated / processed_chars / total_chars / max_chars — 请参阅大小限制。
  • filtered_out_count / unclassified_redacted_count / unclassified_types / filter_exact — 请参阅按类型筛选。

脱敏依据的是您组织自己的脱敏配置,因此结果与产品所使用的智能体一致。与此接口上的所有操作一样,该调用以令牌所有者的身份执行,并限定于该组织。

大小限制

只会分析前 80,000 个字符。一直以来都是如此;现在结果会明确告诉您这一点。当 truncated 为 true 时,processed_chars 之后的文本从未被检查过,请不要将该响应视为对整个输入的脱敏。请在后续调用中发送剩余部分。

按类型筛选

types 仅接受以下值:

name, email, phone, ssn, account, address, financial, confidential, url, username

⚠️ 破坏性变更(2026 年 8 月)。 types 以前接受任何字符串。现在它只接受上述值,其他任何值("emails"、"PII"、"credit-card",或大小写不同的写法如 "EMAIL")都会返回校验错误。

这是用显式失败取代了静默失败。以前,无法识别的值不会匹配任何内容,因此工具什么都不脱敏,并在一个成功的响应中将您的原始文本作为 redacted_text 返回。如果您传入 types,请将您的值映射到上面的列表。省略 types 的调用不受影响。

有一种实体类型即使您没有要求也会被脱敏。 如果脱敏模型为某个内容打上了我们无法识别的类型标签,该实体仍会被脱敏,而不是被丢弃:我们无法证明它不在您要求的范围之内,而在文本中留下 PII 是更严重的错误。发生这种情况时:

  • filter_exact 为 false(只要筛选被精确应用,它就为 true),
  • unclassified_redacted_count 表示受影响的实体数量,并且
  • unclassified_types 列出所涉及的标签。

您有意筛除的实体会单独计入 filtered_out_count。

要求:付费套餐,且您组织的 AI 功能已启用(默认开启;组织管理员可以在 设置 → AI 与集成 中将其关闭)。当您的组织达到每日 AI 用量上限,或 Waafir 暂停了该功能时,调用也会被拒绝;错误消息会说明是哪种情况。

redact_file

分析数据室中整个文档的 PII。此操作仅进行分析:文档不会被更改,任何人看到的内容也不会改变。分析是异步的;请轮询 redact_file_status。

输入

字段类型必填说明
file_idstring是文件的 UUID。
override_redactedboolean否重新分析已脱敏的文档。不传此参数时,已脱敏的文件会被拒绝。

输出

{ file_id, job_id, status: "analysis_started", applied: false,
  review_required: true, review_with, apply_via }

按照设计,没有 auto_apply 选项,请参阅本页顶部的说明。不支持图像文件。

要求:write 权限范围的 PAT、该数据室的交易团队成员身份、付费套餐,以及您组织的 AI 功能已启用(默认开启;组织管理员可以在 设置 → AI 与集成 中将其关闭)。

仍在检查中的文件。 如果该文件是 Waafir 尚未检查完毕的新上传文件或新版本,redact_file 和 redact_apply 会返回 UNAVAILABLE,附带 error.reason: "ACTIVATION_PENDING" 和消息 This file is still being checked. Try again shortly. 不会进行任何分析或应用;请稍等片刻后再次调用。

redact_file_status

检查文档脱敏分析的状态。

输入

字段类型必填说明
file_idstring是文件的 UUID。

输出

{ file_id, status, entity_count?, applied: false, apply_via }
  • status — idle、analyzing、applying、review_ready、completed、failed、error 之一。applying 和 completed 表示有人正在 Waafir 界面中应用脱敏:您无法通过 MCP 进入这些状态,但如果在您轮询期间有人批准了审核,您会看到它们。
  • entity_count — 审核就绪后,分析建议脱敏的 PII 实体数量。
  • applied 始终为 false:批准和应用脱敏在 Waafir 界面中进行。

将无法识别的 status 视为“继续轮询”,而不是错误。 终止状态只会短暂保留,随后作业标记就会被清理,因此迟到的轮询方会看到 idle(或重建的 review_ready),而不是它所等待的状态;并且 idle 表示“没有正在进行的作业”,而不是“什么都没发生过”。请设定截止时间,轮询您想要的状态,而不是断言该值属于某个固定列表。

redact_history

文件最近一次脱敏分析的结果,以按实体类型统计的数量呈现。永远不会返回脱敏文本本身。

  • 权限范围:read。交易团队成员,针对其可以读取内容的文件。
  • 输入:file_id(必填)。
  • 输出:{ file_id, analysis }。analysis 为 { history_id, analysed_at, entities: { total, by_type } },如果该文件从未被分析过则为 null。

redact_list_terms

数据室的脱敏词条:始终脱敏的短语(always)和从不脱敏的短语(never)。

  • 权限范围:read。交易团队成员。
  • 输入:dataroom_id(必填)。
  • 输出:{ terms },每项为 { id, term, kind, created_at }。

redact_add_term

向数据室添加一个词条。它适用于该数据室中文件的下一次脱敏,当下不会更改任何文件。

  • 权限范围:write。交易团队成员,需付费套餐。
  • 输入:dataroom_id、term(均为必填);kind(always 或 never,默认为 always)。
  • 输出:{ term }。

redact_remove_term

从数据室中移除一个词条。当下不会更改任何文件;重新添加该词条即可撤消。

  • 权限范围:write。交易团队成员。
  • 输入:dataroom_id、term_id(均为必填)。
  • 输出:{ removed, term_id }。

redact_revert

取消文件的脱敏。所有读者(包括投资者)都会立即重新看到原始文档。脱敏版本会被保留,因此可以重新应用。

  • 权限范围:write。交易团队成员,针对其可以编辑的文件。
  • 输入:file_id(必填);confirm_token。
  • 分两步。不传 confirm_token 时不会做任何更改,您会得到一个预览和一个令牌。使用相同的参数和该令牌再次调用即可执行恢复。
  • 未脱敏的文件会被拒绝(409)。正在进行分析或涂黑处理的文件也会被拒绝(409):您会在预览时得知这一点,因此不会为无法执行的恢复签发令牌,并且在您确认时会再次执行该检查。

redact_apply

应用文件最近一次来自 redact_file 的分析结果,减去您排除的实体类型,再加上该数据室的始终脱敏词条。之后所有读者(包括投资者)看到的都是脱敏后的文档。redact_revert 可以撤消此操作。

  • 权限范围:write。交易团队成员,需付费套餐,针对其可以读取内容的文件。
  • 输入:file_id(必填);exclude_types;confirm_token。
  • 分两步。不传 confirm_token 时不会做任何更改,您会得到一个预览(按类型统计的目标数量,绝不包含文本)和一个令牌。使用相同的参数和该令牌再次调用即可开始涂黑处理。如果在此期间分析结果、文件、数据室的词条或目标发生了变化,调用会被拒绝,您需要重新预览。
  • 如果您的组织关闭了 AI,则只能应用该数据室已保存的始终脱敏词条,与在 Waafir 中一样。