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 进行脱敏。文本由您组织的脱敏智能体处理,工具会返回脱敏后的文本以及它识别出的实体列表。您还可以选择将结果限定为特定的实体类型。
输入
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
text | string | 是 | 要脱敏的文本(不能为空)。 |
types | string[] | 否 | 仅对这些 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_id | string | 是 | 文件的 UUID。 |
override_redacted | boolean | 否 | 重新分析已脱敏的文档。不传此参数时,已脱敏的文件会被拒绝。 |
输出
{ 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_id | string | 是 | 文件的 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 中一样。