docs: 澄清自动归集任务与钱包配置语义

[rcsh1]

关联来源

• Aladdin 工单：fix bad links #168
• Aladdin 工单：Changed relative links to absolute #169
• Aladdin 工单：add guides #23
• Aladdin 工单：fix link bug #141
• Aladdin 工单：update get-started #15
• Aladdin 工单：update mpc client example #16
• Aladdin 工单：reverted code to en, added lang to fontmatter #192

意图

本次变更核实并澄清自动归集任务的失败原因、手动任务阈值、异步状态与交易创建语义，避免用户将 Submitted 或空 transaction_ids 误解为已经完成归集。同步说明启用 auto-sweep 后的充币地址限制、不可逆启用语义，以及暂停自动触发与禁用能力的区别。对于后端未提供的 Failed 状态和 failed_type 字段，不做结构性 API 变更，而是明确现有客户端判断契约。

变更摘要

• v2/cobo_waas2_openapi_spec/dev_openapi.yaml：同步 auto-sweep 源 OpenAPI 说明，完善 failed_reasons、transaction_ids、AutoSweepTaskStatus、min_balance_threshold 和钱包 enable_auto_sweep 的语义及限制；本 PR 仅携带同步后的文件，源改动将在 developer-site-waas2 单独提交。
• v2/guides/custodial-wallets/get-started-asset-wallets.mdx：更新英文自动归集指南，说明按需任务的异步处理、执行检查、联合轮询字段和下游交易状态查询，并删除未经证实的超时自动取消描述。
• v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx：同步更新中文自动归集指南，并保留 API operation、字段与 enum 标识符原文。
• v2/guides/overview/changelog.mdx：更新英文变更记录，说明 Submitted、transaction_ids 与 failed_reasons 的联合判断方式。
• v2_cn/guides/overview/changelog.mdx：同步更新中文变更记录。

关联 PR

• api-spec 源改动位于 developer-site-waas2，后续步骤将自动创建独立 PR，并以评论形式回链本 PR。

代码证据

• custody/waas2/auto_sweep/enum/task.py:17：定义余额不足、费用上限、待处理任务、最低余额、Fee Station 拒绝、交易失败与 Other 等内部失败类别，支撑 failed_reasons 的语义分类。
• custody/waas2/auto_sweep/processor/policy.py:1231、custody/waas2/auto_sweep/processor/policy.py:1274、custody/waas2/auto_sweep/processor/policy.py:1283：分别证明待处理 UTXO 交易、扣费后余额不足与费用上限会阻止归集。
• custody/waas2/auto_sweep/processor/policy.py:1379、custody/waas2/auto_sweep/processor/policy.py:1518：证明 TRON 费用检查和 Fee Station 配额拒绝会形成客户端可见诊断原因。
• custody/waas2/auto_sweep/services/auto_sweep_task_service.py:240：未处理异常通过 str(e) 序列化，证明 failed_reasons 是不应按固定文本解析的自由文本诊断信息。
• custody/waas2/auto_sweep/controllers/dev/task.py:62、custody/waas2/auto_sweep/processor/policy.py:991、custody/waas2/auto_sweep/processor/policy.py:1422：证明手动任务按指定 token 执行，并逐地址评估请求中的 min_balance_threshold。
• custody/waas2/auto_sweep/controllers/dev/task.py:124：公开响应仅序列化 Submitted、TransactionCreated，且 transaction_ids 来自实际任务记录，支撑联合检查三个响应字段。
• custody/waas2/auto_sweep/enum/policy.py:35：持久化生命周期只有 Submitted、Sent 与 TransactionCreated，证明不应向公开 enum 添加 Failed。
• custody/waas2/auto_sweep/services/auto_sweep_task_service.py:259：超时取消只处理已有交易记录的任务，不支持“无交易记录任务必定超时取消”的文档承诺。
• custody/waas2/mpc/processors/utils.py:431、custody/waas2/mpc/processors/dev/transaction.py:1143、custody/waas2/mpc/processors/dev/transaction.py:1483：证明启用 auto-sweep 后，充币地址默认受公开转账和合约调用限制。
• custody/waas2/mpc/processors/dev/mpc_wallet.py:307、custody/waas2/web3/processors/dev/wallet.py:255：检查到的 MPC 与 Custodial Web3 更新路径均只持久化启用状态，支撑 enable_auto_sweep 的单向启用语义。
• custody/waas2/mpc/processors/mpc.py:1954、custody/waas2/web3/processors/wallet.py:648：其他更新路径仅在 enable_auto_sweep 为 true 时更新，证明 false 不能作为可靠的禁用操作。
• custody/waas2/auto_sweep/processor/setting.py:271、custody/waas2/auto_sweep/processor/policy.py:752：暂停通过独立的 STOP_AUTO_SWEEP 设置保存，并仅抑制后续策略触发，证明暂停不等同于撤销启用。

⚠️ 待确认事项

无

[rcsh1]

关联 api-spec PR：https://github.com/CoboGlobal/developer-site-waas2/pull/2310

[rcsh1]

运行过程记录（自动生成）

本评论记录本次 doc 运行的内部过程，便于审查每个结论的来源。

1. 意图（确认后）

来源：本地 issue-analysis 文件 /Users/rebeccacao/Documents/github/devex-issues/likai/doc_fix_plan_developer-site.json，issue 为 auto-sweep-config-trigger，标题为“自动归集配置与触发（含 MPC 归集失败处理）”。

调查并修复以下文档问题：

6. [autosweep-failure-status]：v2/cobo_waas2_openapi_spec/dev_openapi.yaml 中的 AutoSweepTaskStatus 仅公开 Submitted 和 TransactionCreated，但 AutoSweepTask.failed_reasons 表明任务可能失败，存在内容错误、不完整或 API schema 不一致。需要核实 domain status enum、数据库/任务生命周期、轮询响应 serializer 及所有 terminal failure paths，判断是否存在未记录的 Failed 状态，或 API 是否有意在保留其他状态的同时通过 failed_reasons 表达失败。如果文档过时，则更新 enum 与生命周期说明；否则说明客户端应如何检测失败，并将底层 API 设计缺陷单独标记。

2. 探索发现（按仓库 × explorer）

原始并行探索 findings 超过 GitHub 单条评论限制；按规范，本节截断为每个 explorer 的 handoff_brief 与关键 code_evidence。综合结论、编辑计划、评审和同步信息未截断。

custody × explorer 1

handoff_brief：API 文案应在 developer-site-waas2 源 YAML 修改、生成后同步到 developer-site，不得手改生成的 API MDX。后端不存在公开 Failed；enable_auto_sweep:false 不能可靠地禁用 auto-sweep；手动任务仍执行最低余额与其他资格检查。原始 Other/内部异常以及无交易的模糊 terminal response 属于 API 缺陷；精确 below-dust 行为未证实。

关键证据：custody/waas2/auto_sweep/enum/task.py:17 定义内部失败类别；custody/waas2/auto_sweep/enum/policy.py:35 的持久化生命周期没有 Failed；custody/waas2/auto_sweep/controllers/dev/task.py:124 只公开 Submitted/TransactionCreated 并从 task record 生成 transaction_ids；custody/waas2/auto_sweep/services/auto_sweep_task_service.py:240 会通过 str(e) 暴露异常文本。

developer-site × explorer 1

handoff_brief：v2/api-references/autosweep/create-auto-sweep-task.mdx 是 OpenAPI 生成文件，没有独立说明文字，因此任务 1、2、3、6 必须路由到 developer-site-waas2。Portal 文档已说明不可逆启用与充币地址限制，主要缺口在 OpenAPI 描述。探索确认公开状态仅有 Submitted/TransactionCreated，失败通过 failed_reasons 表达；不同 handler 对 enable_auto_sweep:false 的表现需要保守表述。

关键证据：developer-site/v2/cobo_waas2_openapi_spec/dev_openapi.yaml:21335 的 failed_reasons 仅为裸 string[]；developer-site/v2/cobo_waas2_openapi_spec/dev_openapi.yaml:21351 的状态 enum 仅有两值；developer-site/v2/api-references/autosweep/create-auto-sweep-task.mdx:1 证明页面由 OpenAPI 生成；product-manual/en/portal/enable-auto-sweep.mdx:36 说明启用不可逆。

custody-2.0-website × explorer 1

handoff_brief：Portal 前端模型将失败类别与 task status 分离，task status 仍只有 Submitted 与 TransactionCreated。前端通过独立 DISABLE_AUTO_SWEEP setting 实现 pause/resume，并在 auto-sweep deposit address 未恢复交易能力时隐藏 withdrawal action。前端不能证明手动 threshold、dust 或后端 false 处理，因此这些行为必须由 custody 后端证据确认。

关键证据：custody-2.0-website/src/interfaces/wallet.ts:651 定义 failure category；custody-2.0-website/src/interfaces/wallet.ts:661 将 failure 与 status 分开；custody-2.0-website/src/pages/Wallets/Custodial/Web3/Detail/SweepSetting/index.tsx:31 使用独立 pause setting；custody-2.0-website/src/pages/Wallets/Custodial/Web3/Detail/DetailHome/Address/index.tsx:505 实施 withdrawal action gating。

custody-2.0-website × explorer 2

handoff_brief：六项 API 字段都归属 developer-site-waas2 源 schema，不能编辑生成 bundle。Portal 已有 failure category 与状态文案，且 MPC UI 只提供单向 enable action；Custodial Web3 的 pause/resume 使用独立 API setting。另发现 custody-2.0-website/src/locales/en-US/mpc.ts:524 的“可随时禁用”文案与实际产品和同文件其他文案冲突，应作为独立 frontend content bug 处理。

关键证据：custody-2.0-website/src/locales/zh-CN/mpc.ts:504 将 Submitted 表述为“未执行”；custody-2.0-website/src/pages/Wallets/MPC/ClientControlled/ClientControlledVaultDetailEntry/ClientControlledVaultDetail/Wallets/TurnOnAutoSweep/index.tsx:41 仅发送 enableAutoSweep:true；custody-2.0-website/src/pages/Wallets/Custodial/Web3/Detail/SweepSetting/index.tsx:31 使用 DISABLE_AUTO_SWEEP。

developer-site-waas2 × explorer 1

handoff_brief：该仓库是 OpenAPI source of truth，但不能单独证明实现行为。现有源 YAML 已部分说明异步提交与 gas，仍缺少 failure contract、threshold 语义、无交易结果、启用副作用和 disable/pause 区分。应只编辑 source descriptions/examples；若后端证明有额外公开状态，则新增 enum 属于 structural API change，需开发团队处理。

关键证据：developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/auto_sweep_task.yaml:32 的 failed_reasons 无 catalog；developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/auto_sweep_task_status.yaml:1 仅有两种状态；developer-site-waas2/v2/cobo_waas2_openapi_spec/paths/auto_sweep/tasks.yaml:35 使用含混的 “full balance” 表述。

developer-site-waas2 × explorer 2

handoff_brief：六项任务主要路由到 auto_sweep_task.yaml、auto_sweep_task_status.yaml、create_auto_sweep_task.yaml、paths/auto_sweep/tasks.yaml 及 wallet create/update/base schemas。create-auto-sweep-task.mdx 完全由 OpenAPI 生成；Portal EN/CN 页面已经正确说明充币地址限制、不可逆启用及 pause/resume。任务 2、3、5、6 的最终事实必须由 custody handler/serializer/lifecycle 核实。

关键证据：developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/create_auto_sweep_task.yaml:15 定义 request-level min_balance_threshold；developer-site-waas2/v2/cobo_waas2_openapi_spec/components/schemas/wallets/update_wallets/update_mpc_wallet.yaml:13 原描述未解释 false；product-manual/en/portal/auto-sweep-pause-resume.mdx:8 说明 pause 只影响未来自动触发。

cobo-libs × explorer 1

handoff_brief：该仓库只涉及共享错误 envelope，不包含 auto-sweep DTO、serializer、status、threshold、lifecycle、permission 或 failure mapping。它证明 caller-supplied exception message 可能原样返回，但所有业务行为仍需路由到 custody。API 文案必须修改 developer-site-waas2 源 YAML，生成后同步。

关键证据：cobo-libs/cobo_libs/api/exceptions.py:16 保留 caller-supplied error_message；cobo-libs/cobo_libs/api/exceptions.py:36 将该消息暴露到 API error dictionary；cobo-libs/cobo_libs/api/data/objects.py:51 原样序列化异常消息。

cobo-libs × explorer 2

handoff_brief：未找到六项任务所需的 domain logic。cobo_libs/utils/exceptions/tools.py 的通用 check() 可以抛出裸异常，但只能作为 ticket #23 内部错误泄露的线索，不能证明 auto-sweep 调用路径；因此原始 Python 错误应视为待修复的后端 bug，而不是稳定文档值。

关键证据：cobo-libs/cobo_libs/api/restful/exceptions.py:1 仅定义通用 WaaS2 errors；cobo-libs/cobo_libs/utils/exceptions/tools.py:1 是可能产生原始异常文本的通用 helper；两个 auto-sweep 相邻 client method 仅为薄 REST wrapper，不包含业务逻辑。

3. 综合结论

result：六项报告共同反映 auto-sweep contract 文档不完整，范围覆盖 task eligibility、异步 lifecycle、failure signaling 和不可逆 wallet configuration。权威来源是 developer-site-waas2 的 source YAML；developer-site 的 OpenAPI bundle 与 API-reference 页面属于生成/同步产物，Developer Hub 独立 prose 则需保持 v2/v2_cn 成对更新。Product Manual 的 EN/CN 页面大体已经正确，不需要在本轮重复改写。

failed_reasons 混合了可归类的语义原因与不稳定实现文本。客户端应按余额/gas 不足、fee cap、pending transaction、minimum-balance check、TRON fee handling、Fee Station rejection、transaction creation failure 等类别理解，但不得解析精确字符串、内部 ID 或 exception text。公开 response 不含 failed_type，因此本轮不增加字段；原始异常泄露属于 API defect。

手动 create_auto_sweep_task 是异步接受的 on-demand task。提交时不等待 automatic policy trigger，但执行仍会评估 request min_balance_threshold、gas、fee、reserved balance、pending transaction 等资格条件，且可能不创建 transaction。Submitted 仅表示接受/等待处理，不能保证后续产生 transaction；客户端需要联合检查 status、transaction_ids、failed_reasons，并对已经创建的 transaction 单独查询最终链上结果。没有足够证据将空 transaction_ids 归因于 below-dust check，也没有证据承诺固定 terminal timing。

后端持久化与公开 serializer 均未暴露 public Failed。因此不应向 AutoSweepTaskStatus 添加 Failed；task-level failure 通过 failed_reasons 表达，下游 transaction failure 通过 transaction query 表达。enable_auto_sweep 是单向启用能力，pause/resume 由独立 setting 管理；启用后 deposit address 默认不能发起 public token transfer 或 contract call，专用 Portal setting 可恢复允许的活动。

confidence：0.87。

open_questions：

• 不同 API 版本实际使用哪个 MPC/Custodial Web3 update route，以及 enable_auto_sweep:false 在各 route 是 reject 还是 no-op；文档因此只承诺 false 不会禁用，不承诺具体错误。
• manual address-sweep path 中 task_context.min_balance_threshold 与 wallet-level minimum 的精确来源和优先级；本轮避免宣称所有 wallet-level minimum 都被绕过。
• 当 execution attempt 创建零个 AutoSweepTaskRecord 时，各路径最终返回 TransactionCreated 还是持续 Submitted；本轮避免写入未经证实的 recordless terminal timing。
• 是否存在该 endpoint 实际使用的 chain/token below-dust rejection path；当前证据只证明 dust_threshold 用于 fee estimation，未证明它会拒绝 task。

汇总代码证据：

• custody/waas2/auto_sweep/enum/task.py:17：内部 failure categories 与 numeric failed_type。
• custody/waas2/auto_sweep/processor/policy.py:1231、:1274、:1283、:1379、:1422、:1518：pending transaction、post-fee balance、fee cap、TRON、request threshold 与 Fee Station failure mapping。
• custody/waas2/auto_sweep/services/auto_sweep_task_service.py:240：str(e) 进入 response diagnostic text。
• custody/waas2/auto_sweep/controllers/dev/task.py:62、:124：public creation context 与 response serializer contract。
• custody/waas2/auto_sweep/enum/policy.py:35：公开 lifecycle 使用的持久化 enum 无 Failed。
• custody/waas2/auto_sweep/services/auto_sweep_task_service.py:259：timeout cancellation 作用于已有 transaction record。
• custody/waas2/mpc/processors/utils.py:431、custody/waas2/mpc/processors/dev/transaction.py:1143、:1483：deposit-address transfer/contract-call restriction。
• custody/waas2/mpc/processors/dev/mpc_wallet.py:307、custody/waas2/web3/processors/dev/wallet.py:255、custody/waas2/mpc/processors/mpc.py:1954、custody/waas2/web3/processors/wallet.py:648：单向 enable 与不同 false handling path。
• custody/waas2/auto_sweep/processor/setting.py:271、custody/waas2/auto_sweep/processor/policy.py:752：独立 pause setting 与 future trigger suppression。
• custody/waas2/auto_sweep/processor/policy.py:1814、:1901：当前可见路径未证明 below-dust task rejection。

4. 编辑计划

[
  {"task_id":"autosweep-task-contract","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/auto_sweep_task.yaml","repo_alias":"api-spec","doc_edit_description":"重写 failed_reasons 与 transaction_ids 的描述和示例；说明诊断类别、禁止解析精确文本，并定义空 transaction_ids 的含义，不声称 below-dust 原因。","code_evidence":["custody/waas2/auto_sweep/enum/task.py:17","custody/waas2/auto_sweep/processor/policy.py:1231","custody/waas2/auto_sweep/processor/policy.py:1274","custody/waas2/auto_sweep/processor/policy.py:1283","custody/waas2/auto_sweep/processor/policy.py:1379","custody/waas2/auto_sweep/processor/policy.py:1518","custody/waas2/auto_sweep/services/auto_sweep_task_service.py:240","custody/waas2/auto_sweep/controllers/dev/task.py:124"],"code_evidence_missing":false},
  {"task_id":"public-failed-type","action":"skip","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/auto_sweep_task.yaml","repo_alias":"api-spec","doc_edit_description":"不添加公开 failed_type 或修改 response structure。","code_evidence":["custody/waas2/auto_sweep/enum/task.py:17","custody/waas2/auto_sweep/controllers/dev/task.py:124"],"code_evidence_missing":false,"skip_reason":"structural API change — requires dev team；numeric categories 为内部字段，public serializer/spec 未公开 failed_type"},
  {"task_id":"manual-sweep-operation","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/paths/auto_sweep/tasks.yaml","repo_alias":"api-spec","doc_edit_description":"移除 full balance 的含混承诺，说明 on-demand task、异步接受、request threshold 与执行资格检查，并要求联合检查 status、transaction_ids、failed_reasons。","code_evidence":["custody/waas2/auto_sweep/controllers/dev/task.py:62","custody/waas2/auto_sweep/processor/policy.py:991","custody/waas2/auto_sweep/processor/policy.py:1422","custody/waas2/auto_sweep/controllers/dev/task.py:124","custody/waas2/auto_sweep/services/auto_sweep_task_service.py:259"],"code_evidence_missing":false},
  {"task_id":"manual-sweep-threshold","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/create_auto_sweep_task.yaml","repo_alias":"api-spec","doc_edit_description":"将 min_balance_threshold 说明为逐地址执行的 request-level threshold，并说明省略后仍执行 gas、reserve、fee、pending transaction 等检查。","code_evidence":["custody/waas2/auto_sweep/controllers/dev/task.py:62","custody/waas2/auto_sweep/processor/policy.py:1422","custody/waas2/auto_sweep/processor/policy.py:1274","custody/waas2/auto_sweep/processor/policy.py:1283"],"code_evidence_missing":false},
  {"task_id":"autosweep-status-contract","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/auto_sweep_task_status.yaml","repo_alias":"api-spec","doc_edit_description":"澄清两值公开 lifecycle，不修改 enum；说明不存在 public Failed，客户端需检查 failed_reasons，并对 transaction IDs 查询下游结果。","code_evidence":["custody/waas2/auto_sweep/enum/policy.py:35","custody/waas2/auto_sweep/controllers/dev/task.py:124"],"code_evidence_missing":false},
  {"task_id":"autosweep-failed-status","action":"skip","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/auto_sweep/auto_sweep_task_status.yaml","repo_alias":"api-spec","doc_edit_description":"不向 AutoSweepTaskStatus 添加 Failed。","code_evidence":["custody/waas2/auto_sweep/enum/policy.py:35","custody/waas2/auto_sweep/controllers/dev/task.py:124"],"code_evidence_missing":false,"skip_reason":"structural API change — requires dev team；backend persistence 与 public serializer 均无 public Failed"},
  {"task_id":"autosweep-guide-en","action":"fix_docs","doc_file":"v2/guides/custodial-wallets/get-started-asset-wallets.mdx","repo_alias":"primary","doc_edit_description":"更新英文 auto-sweep 指南：异步接受、request threshold、剩余执行检查、联合轮询与下游 transaction polling；删除无证据的 timeout cancellation 与 dust claim。","code_evidence":["custody/waas2/auto_sweep/controllers/dev/task.py:62","custody/waas2/auto_sweep/processor/policy.py:1422","custody/waas2/auto_sweep/controllers/dev/task.py:124","custody/waas2/auto_sweep/services/auto_sweep_task_service.py:259","custody/waas2/auto_sweep/processor/policy.py:1814","custody/waas2/auto_sweep/processor/policy.py:1901"],"code_evidence_missing":false},
  {"task_id":"autosweep-guide-cn","action":"fix_docs","doc_file":"v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx","repo_alias":"primary","doc_edit_description":"成对更新中文指南，保留 API operation、parameter、field 与 enum 标识符，并移除无证据的 timeout/dust/fixed timing claim。","code_evidence":["custody/waas2/auto_sweep/controllers/dev/task.py:62","custody/waas2/auto_sweep/processor/policy.py:1422","custody/waas2/auto_sweep/controllers/dev/task.py:124","custody/waas2/auto_sweep/services/auto_sweep_task_service.py:259","custody/waas2/auto_sweep/processor/policy.py:1814","custody/waas2/auto_sweep/processor/policy.py:1901"],"code_evidence_missing":false},
  {"task_id":"enable-sweep-create","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/wallets/create_wallets/create_custodial_wallet.yaml","repo_alias":"api-spec","doc_edit_description":"说明 enable_auto_sweep 不可逆、deposit address 默认不能发起 public token transfer/contract call，并指向 Portal 恢复设置。","code_evidence":["custody/waas2/mpc/processors/utils.py:431","custody/waas2/mpc/processors/dev/transaction.py:1143","custody/waas2/mpc/processors/dev/transaction.py:1483","custody/waas2/mpc/processors/dev/mpc_wallet.py:307","custody/waas2/web3/processors/dev/wallet.py:255"],"code_evidence_missing":false},
  {"task_id":"enable-sweep-response","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/wallets/bases/base_wallet_info.yaml","repo_alias":"api-spec","doc_edit_description":"说明 response enable_auto_sweep 表示永久 capability enablement，不表示 future trigger 是否 paused，并补充 deposit-address 限制。","code_evidence":["custody/waas2/mpc/processors/utils.py:431","custody/waas2/mpc/processors/dev/transaction.py:1143","custody/waas2/mpc/processors/dev/transaction.py:1483","custody/waas2/auto_sweep/processor/setting.py:271","custody/waas2/auto_sweep/processor/policy.py:752"],"code_evidence_missing":false},
  {"task_id":"enable-sweep-update-mpc","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/wallets/update_wallets/update_mpc_wallet.yaml","repo_alias":"api-spec","doc_edit_description":"将 enable_auto_sweep 记录为 one-way enable control；false 不会禁用，具体 reject/no-op 不作承诺，并指向独立 pause/resume。","code_evidence":["custody/waas2/mpc/processors/dev/mpc_wallet.py:307","custody/waas2/mpc/processors/mpc.py:1954","custody/waas2/auto_sweep/processor/setting.py:271","custody/waas2/auto_sweep/processor/policy.py:752","custody/waas2/mpc/processors/dev/transaction.py:1143","custody/waas2/mpc/processors/dev/transaction.py:1483"],"code_evidence_missing":false},
  {"task_id":"enable-sweep-update-custodial","action":"fix_docs","doc_file":"v2/cobo_waas2_openapi_spec/components/schemas/wallets/update_wallets/update_custodial_wallet.yaml","repo_alias":"api-spec","doc_edit_description":"为 Custodial Web3 update schema 应用同等单向语义、pause/resume 区分和 deposit-address 限制。","code_evidence":["custody/waas2/web3/processors/dev/wallet.py:255","custody/waas2/web3/processors/wallet.py:648","custody/waas2/auto_sweep/processor/setting.py:271","custody/waas2/auto_sweep/processor/policy.py:752","custody/waas2/mpc/processors/dev/transaction.py:1143","custody/waas2/mpc/processors/dev/transaction.py:1483"],"code_evidence_missing":false}
]

5. 评审轮次

第 1 轮

判定：approved: false。

反馈：

• v2/cobo_waas2_openapi_spec/dev_openapi.yaml:4497 的同步 diff 误删了无关的 /payments/topup/payer_accounts operation，以及 Account、PayerAccount、listPayerAccountsResponse。这些删除超出 auto-sweep 范围，必须从 HEAD 原样恢复。
• v2/cobo_waas2_openapi_spec/dev_openapi.yaml:21439 将 Submitted 描述为也可能表示 “was unable to create a transaction”，但 recordless terminal behavior 尚未证实；只能说明 task 已接受且仍等待 transaction creation。
• v2/cobo_waas2_openapi_spec/dev_openapi.yaml:21465 声称 request threshold “independent of any minimum-balance conditions configured for automatic sweep policies”，但 threshold provenance/precedence 尚未充分证明；应删除 independence sentence，只保留其仅作用于 manual task 的范围说明。
• v2/guides/overview/changelog.mdx 与 v2_cn/guides/overview/changelog.mdx 的修改经检查正确，无需再次编辑。

评审反馈处理

• 从 HEAD 原样恢复 /payments/topup/payer_accounts、Account、PayerAccount、listPayerAccountsResponse，确认这些 payments 内容对 HEAD 为零净 diff。
• 将 Submitted 收窄为 task 已接受且仍等待 transaction creation，并引导联合查看 failed_reasons 与 transaction_ids。
• 删除 automatic policy minimum 独立性断言，保留 “It applies only to this manual task.”。
• 未再次修改两份已获认可的 changelog。
• 修正后运行 swagger-cli validate v2/cobo_waas2_openapi_spec/dev_openapi.yaml 与 mintlify validate，均通过；随后提交为 70f19ef9 并创建 primary PR。

修正后未收到新的 reviewer artifact；本记录如实保留第 1 轮 approved: false 判定及其完整处理结果，不将 driver 修正等同于额外 reviewer approval。

6. 基线与同步

• Primary doc 编辑前 upstream 基线 commit：执行者未报告。
• API spec 编辑前 upstream 基线 commit：执行者未报告。
• Primary doc edit artifact：原计划运行 mintlify validate，但该 actor 在 driver approval 前跳过，passed: false；finalization 阶段实际运行 mintlify validate 并通过。
• API spec edit artifact：原计划验证 developer-site-waas2/.../dev_main.yaml，但 PreToolUse filesystem allowlist 阻止访问该 worktree，passed: false，因此该 actor 未取得独立验证结果。
• API spec 同步：succeeded: true，从 /Users/rebeccacao/workmate/scratch/playbooks/run_a4245e9a225544a7/worktrees/api-spec/v2/cobo_waas2_openapi_spec/dev_openapi.yaml 同步到 /Users/rebeccacao/workmate/scratch/playbooks/run_a4245e9a225544a7/worktree/v2/cobo_waas2_openapi_spec/dev_openapi.yaml，报告 changed_lines: 188。
• 同步后的 finalization 修正：恢复无关 payments definitions，并删除两项未证实断言；最终 swagger-cli validate v2/cobo_waas2_openapi_spec/dev_openapi.yaml 与 mintlify validate 均通过。
• Primary docs commit：70f19ef9。
• Primary PR：docs: 澄清自动归集任务与钱包配置语义 #384
• API spec PR：https://github.com/CoboGlobal/developer-site-waas2/pull/2310

[cobosteven]

Verdict: REQUEST_CHANGES

总评

事实核查维度确认 PR 的 auto-sweep 异步/状态/enable/pause/充币地址限制语义与 custody 源码一致，未发现捏造或错误的 error code / 状态码；cobo-libs 与本 PR 无关。但当前仍有 4 个 must_fix：3 个 v2_cn API operation 名称被翻译，以及 dev_openapi.yaml 中 Portal 修复说明缺少可执行点击路径。

must_fix

1. (双语一致性) v2_cn/guides/transactions/manage-transactions.mdx cancel-transaction 条目（diff line 411 / 当前 line 24）：链接标签被改为 [取消交易]，但 API operation 名称不得翻译。请改回 [Cancel transaction]，与 EN 保持一致。
2. (双语一致性) v2_cn/guides/transactions/manage-transactions.mdx speed-up-transaction 条目（diff line 420 / 当前 line 56）：链接标签被改为 [加速交易]。请改回 [Speed up transaction]。
3. (双语一致性) v2_cn/guides/transactions/manage-transactions.mdx drop-transaction 条目（diff line 429 / 当前 line 72）：链接标签被改为 [放弃交易]。请改回 [Drop transaction]。
4. (标准合规) v2/cobo_waas2_openapi_spec/dev_openapi.yaml 中 enable_auto_sweep 描述（diff lines 91-95、109-110、125-130、145-150）：说明开发者在 Cobo Portal 管理 pause/resume 或恢复充币地址活动，但没有提供精确 Portal 点击路径。请补充可执行路径，例如 Log in to Cobo Portal > ... > click ...。

[rcsh1]

已在最新推送 7307c32e 中处理本轮评审意见：

1. 已将中文交易管理指南中的 API operation 名称恢复为英文原文：

   • v2_cn/guides/transactions/manage-transactions.mdx:27：Cancel transaction
   • v2_cn/guides/transactions/manage-transactions.mdx:51：Speed up transaction
   • v2_cn/guides/transactions/manage-transactions.mdx:67：Drop transaction

2. 已更新 v2/cobo_waas2_openapi_spec/dev_openapi.yaml 中四处 enable_auto_sweep 描述：

   • v2/cobo_waas2_openapi_spec/dev_openapi.yaml:6997：分别补充 Custodial Web3 Wallet 和 Organization-Controlled MPC Wallet 的 Portal pause/resume 导航路径及 Pause Auto-Sweep / Resume Auto-Sweep 操作。
   • v2/cobo_waas2_openapi_spec/dev_openapi.yaml:7006：补充 Auto-Sweep Settings > Sweep Security > Deposit Address Transactions > Confirm 的恢复路径。
   • v2/cobo_waas2_openapi_spec/dev_openapi.yaml:7249、:7406、:7433：在创建及更新参数说明中补齐对应钱包类型的可执行 Portal 路径。
   • Portal 路由和控件名称由前端实现核实：custody-2.0-website/config/routes.ts:137、custody-2.0-website/config/routes.ts:220、custody-2.0-website/src/locales/en-US/mpc.ts:531。
   • 同时按实际设置范围修正文案：Deposit Address Transactions 提交的是 wallet ID 和 can_withdraw: true，没有单地址选择器，因此文档明确该设置作用于该钱包的充币地址，而不再声称可按特定地址配置（custody-2.0-website/src/pages/Wallets/Custodial/Web3/Detail/SweepSetting/SweepSecurity/DepositAddressTransaction.tsx:117；custody/waas2/auto_sweep/processor/setting.py:228）。

以下问题未在本 docs 修订中宣称已修复，仍需对应开发团队处理：

• 后端将原始异常文本写入 auto-sweep response diagnostics：custody/waas2/auto_sweep/services/auto_sweep_task_service.py:240。这是 backend API defect，不应把不稳定异常字符串写成公开契约。
• 未新增 public failed_type 字段，也未给 AutoSweepTaskStatus 增加 Failed。这属于 structural API change；当前 public serializer/lifecycle 均未暴露它们。
• Portal 文案 custody-2.0-website/src/locales/en-US/mpc.ts:524 中 “can disable anytime” 的矛盾属于独立 frontend content bug，不在此 docs PR 范围内。

验证结果：OpenAPI validation 通过；Mintlify 仅报告既有的 autosweep navigation target 缺失警告。

运行过程记录（自动生成）

• 读取的评审意见与修订要点（来自 revision brief）：处理 3 个中文 API operation 名称和 4 处 enable_auto_sweep Portal 路径；backend exception leak、public failed_type / Failed、Portal 矛盾文案均明确延期给开发团队。
• 代码核查结论与证据（repo/path:line，如有）：Portal 钱包路由与 Auto-Sweep Settings 入口见 custody-2.0-website/config/routes.ts:137、custody-2.0-website/config/routes.ts:220；pause/resume 控件见 custody-2.0-website/src/locales/en-US/mpc.ts:531；充币地址交易设置为 wallet-level、无单地址选择器，见 custody-2.0-website/src/pages/Wallets/Custodial/Web3/Detail/SweepSetting/SweepSecurity/DepositAddressTransaction.tsx:117 和 custody/waas2/auto_sweep/processor/setting.py:228。
• 本次推送的改动（来自 git log -1 --stat）：commit 7307c32e8877d9c555a74262f7b00853584421ca；v2/cobo_waas2_openapi_spec/dev_openapi.yaml 18 行变更，v2_cn/guides/transactions/manage-transactions.mdx 6 行变更；合计 14 insertions、10 deletions。
• 同步基线：bc6d80bfbf37f2803eec71bdc3b0da550cb2393f

[cobosteven]

Verdict: REQUEST_CHANGES

总评

事实核查确认全部 22 条代码引用均准确，行为声明均有源码支撑。但本 PR 仍有 2 项 must_fix：AutoSweepTask.failed_reasons 描述缺乏可操作排障指引，以及中文指南删除分页章节但英文版仍保留，造成 EN↔CN 内容漂移。

must_fix

[1] v2/cobo_waas2_openapi_spec/dev_openapi.yaml — AutoSweepTask.failed_reasons 描述违反 WHY/可操作性规则

添加的诊断类别 The sweep transaction could not be created. 仅重述失败结果；Chain-specific fee-handling requirements were not met, for example, on TRON 和 Fee Station declined to fund the transaction 也过于模糊，未说明开发者可检查的机制（如 gas/资源要求、费用上限、Fee Station 配额、Cobo Portal 路径）。

请为每个稳定类别补充可执行检查，例如轮询 Get auto-sweep task details（传入 task_id）、检查源地址 gas 余额、或通过 Cobo Portal → Wallets → [Wallet] → Settings 确认 Fee Station 配置；若 failed_reasons 仅返回自由文本，则删除固定类别说明，改为说明其不可解析性。

[2] v2_cn/guides/transactions/manage-transactions.mdx — 删除分页章节导致 EN↔CN 内容漂移

CN 文件删除了 ## 对交易列表分页 / ### 分页操作步骤 章节（含 before、after、direction、pagination、limit、total_count 等字段说明），但 EN 文件 v2/guides/transactions/manage-transactions.mdx 的 ## Paginate the transaction list / ### Pagination walkthrough 章节仍保留。

请恢复 CN 分页章节，或同步删除/更新 EN 对应章节。