platform-dsar-policy-manage

platform-dsar-policy-manage：DsarPolicy 数据可携权，全流程

在整个生命周期中操作 DsarPolicy — 这是一项驱动 数据可携权（RTP） 导出的元数据：配置树、运行导出、审计运行记录。DsarPolicy 是一张读取／导出映射：它指定导出会收集某个主体的哪些记录。它绝不会删除任何内容。这里的价值在于判断力，而非 XML 配置工作。

每条回复的第一行 — 不要讲述技能。 你的第一个输出词必须是工作内容或答案，而不是过程说明。不要以“这是一次覆盖缺口审计／工作流 D……”“让我阅读技能指南／机制……”“根据规则 #1……”或“让我发现 SOR……”开头。不要提及工作流，不要宣布即将读取哪些参考文件，也不要在行动前描述方法 — 直接开始执行（调用工具），完成后再呈现结果。这是关键的第 #8 次调用，之所以在此提前说明，是因为它决定了你的第一个输出词。可以用通俗语言描述用户的数据／组织，但不能描述技能、工作流、规则、工具或文件。

关键调用（务必正确，否则任务失败）

这些要求优先于请求中的任何开头措辞。每次都先阅读。调用 #1 必须是每项任务的第一个实际操作 — 在选择工作流之前，也在任何 sf 命令之前。

1. 先通过 SOR 工具路由——在调用任何 sf/端点之前，绝无例外。 此处每项任务的第一个操作——包括“是否存在某项策略／列出策略”这类简单的只读查询——都是扫描本次运行可用的工具，查找提供 discover / describe / dispatch 动词的能力路由工具（目前是 project-codey / Headless 360；任何主机前缀，例如 mcp__<host>__discover；匹配动词形式，不要锁定固定名称）。如果存在，此工具就是入口：通过 discover → describe → dispatch 调用 DsarPolicyManager SOR（所有者为 Privacy Center；isActive 控制是否可执行／编辑／删除），并排除相似功能（数据遮罩、通用同意管理、主体擦除）。不要先调用 sf——因为任务“看起来只是个简单查询”而条件反射般地使用 sf，是最常见的失误，即使它能奏效，这么做仍然是错的。只有在无法使用任何路由工具时，才将 sf 作为回退方案（检查 sf org list 以查看本地通过身份验证的组织是可以的——这是客户端身份验证检查，不是 SOR 调用）。以下工作流中展示的每条 sf/salesforce-api-context 命令，都是没有路由工具时的写法；若存在路由工具，则应通过它分派等效操作。详情见：references/headless-sor.md。
2. 导出，绝不擦除。 一次运行会生成一个导出文件；不会擦除／涂除／删除主体的数据。如果请求将其描述为删除（“移除他们”“擦除”“清空”），先纠正这一点，绝不要声称主体已被擦除。擦除是另一种机制——如果这是用户的目标，请说明并停止。如果授权明确，纠正前提后仍可导出。
3. 不要猜测个人数据。 哪些对象／关系包含主体的数据，属于管理员的分类决策。如果请求将此事交由你处理（“判断哪些内容算”“把整套东西配置好”），不要自行编写猜测性的树——列出管理员必须作出的决定（根对象；每种关系是继续跟进还是停止；字段），并将任何方案标记为待管理员处置。过于宽泛的猜测会导出其他人的记录。
4. 上限是硬性限制——指出上限并停止；不要遍历图谱。 树的上限：每条路径最多 10 个子项，深度为 10，最多 200 个节点。无限范围的请求（“所有内容”“整个图谱”）无法满足。不要枚举对象图谱来“试试看”（永远无法完成，还会耗尽本轮处理）。指出超出的具体上限，并提供有界替代方案（拆分策略、剪除分支）。绝不要静默截断。
5. 轮询几次后再询问——不要一直等待终态。 运行句柄既可查询状态，也可获取文件。过早调用 getfile 会返回 NOT_FOUND / "This file isn't ready yet"——这表示约定正常运作，并非失败。轮询约 2–3 次；若仍未到终态，停止并询问用户是否继续轮询——不要循环等待。由于下游异步处理，运行可能无限期处于非终态——这是平台／Tool Factory 的职责范围，不应由此技能诊断或介入；用通俗语言报告状态（运行中／已完成／出错），让用户决定。终态之前绝不要下载。失败的运行可能返回 HTTP 201——应读取响应正文中的信封／RequestStatus，而不是 HTTP 状态码。getfile 的分段名是 dsr，不是 dsar。
6. 历史记录是只读操作。 运行历史记录 = 对 DsarPolicyLog 执行 SOQL 查询。不是 installListView，不是 UI 列表；此操作不会启动运行。
7. 绝不自动激活或重新发布。 激活必须经过慎重考虑并由人工确认。编辑 ACTIVE 策略前，必须先将其停用——停用 → 编辑 → 停止，报告结果，并在重新激活前取得用户的明确确认。新策略在用户激活前保持 INACTIVE。自动重新发布会破坏争议处理所依赖的、可供审查的审计轨迹。
8. 静默处理——绝不要讲述技能的内部运作（适用于所有工作流；见上方标题）。 用户询问的是领域问题；应直接作答，不要描述技能如何作答。调用工具并呈现结果——不要在过程中讲述以下内容：你即将阅读／正在阅读技能指南、机制或参考文件（“让我先看看技能指南和机制”）；当前属于哪个工作流（“这是覆盖缺口审计／工作流 D”“采用工作流 C 的读取方式”）——用户不会用工作流字母来思考，因此绝不要提及；你使用了哪个 SOR／路由工具，或正在“加载架构／发现／分派”；作为依据的规则编号（“根据规则 #1”）；排除相似功能的步骤；操作图谱或 GET 与分派之间的实现细节（getAccessInfo、dispatch_readonly 等）。这些内容决定你的工作方式，不是状态更新。（执行环境仍会显示其自身的普通工具调用行；这没问题——只要不要自行添加逐步讲解即可。）用户实际会看到的内容：最终答复，以及——在调用需要时——通俗易懂的问题（AskUserQuestion），或简短说明其组织的范围／同意情况（“我只列出了策略，没有做任何更改”“此操作会导出，不会删除”）。经验法则：涉及其数据／组织的句子可以面向用户；涉及技能、工作流、步骤、工具、规则或文件的句子必须保留在内部。工作流 D 的方法预告是唯一允许使用的“接下来我会这样做”说明，而且也必须用通俗语言描述审计方法（“我会从策略对象向外检查一层，并标记可能包含个人数据的字段”）——不得提及任何工作流字母、规则、工具或文件。这段预告不意味着可以说“这是工作流 D”或“让我先看看机制”。

DsarPolicy 对象模型

每种实体的访问方式都不同——猜错访问入口是最耗时的事。

实体	含义	访问方式
DsarPolicy	策略外壳 + 生命周期（ACTIVE/INACTIVE）	Metadata API
DsarPolicyPath	树节点：根对象，或父级→关联关系	Metadata API（DsarPolicy 的子级）
DsarPolicyField	在某个路径收集的字段	Metadata API（路径的子级）
DsarPolicyLog	运行日志（每次运行一行）	Standard SOQL
执行导出	—	Connect DSR endpoint（POST）
状态 / getfile	—	Connect DSR endpoint，通过句柄访问；getfile 片段 dsr

运行时通过 salesforce-api-context（或 sf）解析确切的 Connect 路由/版本。不要运行 sf sobject describe DsarPolicy*——树属于元数据；只有 DsarPolicyLog 支持标准 SOQL。在 MCP 界面中，每一行对应一个 DsarPolicyManager 操作。

按动词选择工作流

想要……	执行	结束条件
设置 / 编辑策略树	A — 配置	有界策略已创建为 INACTIVE；或已明确无界请求的上限 / 已列出信息不足请求所需的决策——然后停止
为主体运行导出	B — 导出	主体已解析为根 Id，已读取运行状态（running/completed/errored），成功时已找到文件——或者，如果轮询几次后仍在运行，则询问用户是否继续
查看过往运行	C — 历史记录	报告 DsarPolicyLog 中的过往运行，不启动运行
查找尚未覆盖的 PII	D — 覆盖缺口	列出候选项及逐字段原因，将处置决定留给管理员——只读

混合请求 → 只执行用户要求的操作；不要在配置中额外加入导出，也不要在历史记录查询中启动运行。

以下每个工作流都假设调用 #1 已完成——已通过发现/ 描述/分发 SOR 工具进行路由（或已确认无法使用该工具）。每个工作流中的 sf/salesforce-api-context 命令是无路由工具时的写法；如果有路由工具，则通过该工具分发等效操作。

工作流 A — 配置

操作步骤（元数据结构、关系/字段解析、生命周期转换）：references/configure.md。

1. 先分类——任何描述操作前先判断是否应提前结束。 有三种情况，其中两种不进入创建阶段：
   • 无界（“全部”“整个图谱”）——无法满足上限。不要描述/遍历。编写 上限拒绝报告（调用 #3），然后停止。
   • 信息不足——将分类工作交由他人处理，未指定根/字段。不要猜测并创建。 编写信息收集报告（列出管理员需作出的决定；支持多个根；提案标记为待处置），然后停止。
   • 有界且明确——已命名的根/关系/字段符合上限 → 继续。
2. 仅确认类型并描述已命名对象（不要假定名称，也不要扩展到已命名范围之外）：

   sf org list metadata --metadata-type DsarPolicy --target-org <alias> --json
   sf sobject describe --sobject <NamedObject> --target-org <alias> --json
   

   如果无法列出/描述 DsarPolicy，则说明情况并停止（这是可接受的终止结果）。
3. 验证树结构（不要凭目测检查上限/名称）：

   python3 scripts/validate-policy-tree.py <tree.json>
   

   检查子级≤10、深度≤10、节点≤200，以及 devname [a-zA-Z]+[a-zA-Z0-9_]*。
4. 在 ${outputDir} 下创建 INACTIVE 元数据，严格遵循批准的策略——不得添加未经批准的路径，也不得删除任何已批准的路径。

   **生命周期门槛：**编辑/删除需要 INACTIVE，执行需要 ACTIVE。更改 ACTIVE 策略时，执行 停用 → 编辑 → 停止；重新激活前必须获得用户明确确认（调用 #7）。

5. 部署（尽力而为）：sf project deploy start --source-dir <outputDir> --target-org <alias> --json。 如果该类型尚未完全启用，部署可能失败——如实说明原始错误 + 前置条件；不要伪造成功。无论部署结果如何，分类工作均有效。
6. 报告已达到的结果——上限拒绝 / 信息收集 / 已创建——遵循 references/report-format.md。绝不要把被截断的树称为“完整”。

工作流 B — 运行导出

端点、示例信封、轮询／下载顺序：references/export-and-history.md。

• B0. 确定主体。 请求提供的是电子邮件／姓名／ID，而不是 dataSubjectId。 将其解析为所选策略的根类型（ROOT）记录的 Id（Account / Contact / Individual / Lead / User）——例如，通过 SOQL 按 Email 查询 Lead／Contact。确认该类型 是策略根类型（执行仅匹配主体类型的根子树——非根主体不会导出任何内容）。若匹配结果为 0 条／多条／非根类型，请停止并报告；绝不要猜测 Id 后执行。
• B1. 前提条件。 策略必须为ACTIVE（否则转到 A）。通过 salesforce-api-context 解析 DSR 路由。
  • 谨慎选择策略： 指定了名称 → 使用该策略；否则使用当前上下文中的策略；如果尚未确定 策略或可能匹配的 ACTIVE 策略有多个，则询问确认（例如：“为 <subject> 运行 <policy>——确认吗？”）。绝不默默选择。
  • 访问权限： 遇到 401／403 时，指出权限检查项并停止——用户权限 Consent.CAN_EXECUTE_DSAR_POLICY、 组织功能 Consent.hasDsarPortability。即使出现此错误，也要说明先轮询、后下载的顺序 （这是可接受的终止结果；不要盲目重试）。
• B2. 同意门槛与正确的删除表述（第 2 次调用）。 如果请求表述为删除，先纠正（这是导出， 不是擦除）。如果授权情况不明确，通过 AskUserQuestion 询问；授权明确后继续。
• B3. 执行——以信封为准，而非 HTTP 状态码。 POST 执行请求并获取运行句柄。 失败的运行可能返回 HTTP 201——读取信封状态；如果状态表示失败，就报告失败。
• B4. 轮询约 2–3 次，然后询问；仅在终止后下载（第 5 次调用）。 轮询句柄（或 DsarPolicyLog.RequestStatus）。过早出现 NOT_FOUND／“尚未就绪”是预期情况。轮询几次后仍未终止 → 停止并询问是否继续轮询；不要循环轮询（非终止状态表示下游异步处理，不属于本技能要诊断的范围）。报告运行中／已完成／出错。
• B5. 下载（仅限终止成功状态）——使用 dsr 分段。 dsar 分段会返回 404。报告导出文件 的保存位置。
• B6. 报告遵循 references/report-format.md：已解析的主体（id + 类型）及所选策略 （+ 若存在歧义，说明你曾询问确认）；已确认同意；这是导出，不是删除；用通俗语言说明 信封／运行状态中的结果；成功时提供文件位置；明确说明轮询顺序（轮询几次，终止后才下载文件，仍在运行时曾询问是否继续）。即使前提条件阻止了运行，也要说明该顺序。

工作流 C — 历史记录（只读）

sf data query --target-org <alias> \
  --query "SELECT Id, DsarPolicyId, RequestStatus, CreatedDate FROM DsarPolicyLog WHERE DsarPolicyId = '<POLICY_ID>' ORDER BY CreatedDate DESC"

报告先前的运行记录（时间、状态）；“无先前运行记录”也是有效结果。若日志缺失或出现 401／403／404， 请提供原始错误及前置条件。不要执行策略；不要使用 installListView／UI 列表。

工作流 D — 覆盖缺口分析（只读审计）

“还有哪些个人数据尚未覆盖？” 只读且确定性强——向管理员列出候选项；不做分类，也不添加或启用任何内容。脚本和评估标准：references/gap-analysis-guide.md；操作方式：references/gap-scan.md。

1. 先用通俗语言说明方法（第 8 次调用）——用一句话按用户的说法说明：从策略的对象出发，向外只看一层，标记可能属于 PII 的字段，并逐项说明理由；由管理员决定。不要说“工作流 D”“覆盖缺口审计”或“让我看看操作方式”——只需用通俗语言说明方法，然后开始。
2. 读取当前覆盖情况（只读）——缺口以此为参照。
3. 只扫描一跳，并限制范围——说明每个根对象，以及其隐私相关性最高的最多约 5 个一跳对象；默认深度为 1，不要递归。绝不要将原始 --json describe 读入当前轮次——完整 describe 约为 100KB，累积的载荷会撑满事件流，并在写入报告前截断运行（这是此处最常见的失败）。先将每个 describe 精简为 {name,type,label}（见 references/gap-scan.md）。如果无法读取策略/类型（功能关闭——这是已知的环境路径），只读取一个精简后的根对象 describe；不要继续扩展。根据根对象和少数一跳 describe 编写报告，列出跳过的对象，并通过深度确认门槛提供进一步扫描。书面报告才是交付物——尽早起草并写入，不要等收集完所有信息再写。
4. 逐字段列出候选项并说明理由——优先依据合规元数据，其次是字段类型，最后是名称含义。绝不要断言“这就是 PII”（第 3 次调用）。
5. 透明地报告——列出已扫描的对象、每个候选项及理由、已覆盖项与新发现项，并明确说明仅限一层（即使没有候选项也要说明）。
6. 设置深度确认门槛——只有明确确认后才能深入（提醒用户：输出量大、成本高）。
7. 说明处理方式，不做变更——询问用户要添加哪些项；添加操作转至工作流 A（设为 INACTIVE，重新启用前会暂停并要求确认——第 7 次调用）。

快速规则和注意事项

情况	应对方式
开始任何任务时（即使只是简单地读取“列出/是否存在策略”）	首先检查本次运行可用的工具，查找 discover/describe/dispatch 路由工具（project-codey/Headless 360；任何名为 mcp__<host>__… 的工具——按动词形式匹配）。若存在，则对 DsarPolicyManager SOR 执行 discover/describe/dispatch。不要习惯性地先调用 sf。只有无法使用路由工具时才使用 sf（本地身份验证可使用 sf org list）
“捕获全部/整个图谱”	超出上限（10/10/200）——说明上限，建议拆分或缩减；不要遍历整个图谱
“我们漏掉了哪些 PII？”	工作流 D——只读，深度为 1；列出候选项及理由；由管理员决定处理方式；不添加或启用任何内容
仅提供电子邮件/姓名作为主体，没有 Id	先解析（B0）：查询策略的根实体；确认根类型；结果为 0 个/多个/非根实体时，停止
可能匹配多个 ACTIVE 策略	执行前先询问用户要选哪一个——不得擅自决定
轮询几次后运行仍处于 In Progress	这是下游异步处理（Tool Factory/平台），不属于此技能的诊断范围——报告仍在运行，询问用户是否继续轮询；不要循环轮询
getfile 提示“not ready”/NOT_FOUND	终止前可能出现，属预期情况——再次轮询；这不算失败
执行时返回 HTTP 201	不代表成功——读取信封中的状态
getfile 返回 404	Segment 必须是 dsr，不能是 dsar
刚编辑了 ACTIVE 策略	不要自动重新启用——停止、报告并取得明确确认（第 6 次调用）
sf sobject describe DsarPolicy 返回空结果	此树来自 Metadata API；只有 DsarPolicyLog 支持 SOQL 查询
缺少 DsarPolicy 类型	明确告知并停止；不要编造
返回 401/403/404 或缺少类型	说明所需前提并停止；不要盲目重试

输出（写入 ${outputDir}/report.md）

只报告已运行的工作流；每条命令只写一次；在首屏给出关键结果。 务必简洁——每个关键要点（轮询顺序、导出而非删除、单层限制）只陈述一次，不要在引言、旁注和后续步骤列表中反复重述；全文控制在约 150 行以内，也不要粘贴详尽的逐对象转储。遇到预检错误（功能 / 策略 / 主体缺失）时，指出阻碍因素及前置条件，陈述一次顺序，然后停止——简短说明。各工作流的约定（包括 INACTIVE / 确认重新激活的生命周期和轮询顺序）：references/report-format.md。

参考索引

文件	适用场景
references/headless-sor.md	MCP 接口：发现→描述→分派 SOR，拒绝相似项，sf 后备方案
references/configure.md	元数据结构、根节点 / 关系解析、<tree.json> 输入、生命周期、多根
references/export-and-history.md	DSR 执行 / 状态 / getfile 路由、封装、轮询顺序、dsr 段、历史查询
references/report-format.md	各工作流的报告约定
references/gap-analysis-guide.md	工作流 D：审计脚本、步骤、候选项标记准则
references/gap-scan.md	工作流 D 机制：单跳枚举、差异比较、深度门控、报告结构
scripts/validate-policy-tree.py	编写前的确定性上限 + devname 检查