Files
knowledge-governance/docs/DINGTALK_DWS_FETCHER.md
T
姚章浩 f4e1ecc5f1 feat(artifact): 钉钉取件优先走 dws(DingTalk Workspace CLI),老路径保留为回退
- artifact_fetch.py: 新增 dingtalk dws 取件器(adoc→doc export、axls→sheet 转换、其余→drive 直下),
  ARTIFACT_DINGTALK_FETCHER=dws|auto|legacy 三级开关,auto 仅对可重试错误回落老路径;
  平台侧判定(pick_suffix/SLIDES/magic/大小上限/sha256/spool/空壳检查)全部保留;
  结果 JSON 字段不变(Go runner 用 DisallowUnknownFields 解析 stdout),取件器来源只写 stderr。
- axls_to_xlsx.py: 纯标准库 axls→xlsx(文本写入 sharedStrings 以通过空壳判定)。
- dws_error_map.py: dws 错误→平台 {ok,code,retryable,missing};未分类错误默认不重试。
- Dockerfile: alpine 增加 gcompat/libc6-compat;dws v1.0.63 固定版本+sha256 校验;构建期 dws version 自检。
- compose.yaml: worker 增加 dws 环境与凭据挂载(DWS_HOME 方案,XDG_DATA_HOME 不被 dws 识别)。
- 测试: artifact_fetch_test 新增 11 项(路由/回落语义/契约字段锁定);dws_error_map 17 断言。
- 实测: 真容器(--read-only --tmpfs --user 1000:1000) 端到端 adoc/axls/pdf 3/3 成功,docx sha 与平台基准一致。
2026-10-09 10:57:11 +08:00

5.0 KiB
Raw Blame History

DingTalk 取件走 dws(DingTalk Workspace CLI)

默认优先使用 dws 取钉钉知识库字节,老路径(本地镜像树 + 浏览器 a-token 实况导出)作为回退保留。

1. 开关

环境变量 取值 含义
ARTIFACT_DINGTALK_FETCHER auto(默认) 先 dws;仅当 dws 返回可重试错误(429/5xx/超时/连接层/dws 二进制缺失)时回落到老路径
dws 只用 dws,失败即失败(灰度验证/压测用)
legacy 完全绕过 dws,走原逻辑(回退开关)
DWS_BIN 默认 /usr/local/bin/dws dws 可执行文件
DWS_CONFIG_DIR 容器内 /data/dws dws 配置目录(profiles/identity)
DWS_HOME 容器内 /data/home dws 子进程专用 HOME:文件型 keychain 必须位于 $HOME/.local/share/dws-cli(XDG_DATA_HOME 不被识别),只给 dws 子进程换 HOME,不动 worker 全局 HOME
DWS_DISABLE_KEYCHAIN 1 无系统 keychain 的环境用 file-DEK 模式

2. 路由

按已解析文件名后缀路由(与老路径判定一致;manifest 无 declared_type,缺失时依次退回 declared_type → dws drive +inspect):

后缀 取件方式 产物
adoc dws doc export --export-format docx docx
axls dws sheet list + sheet range read → scripts/axls_to_xlsx.py 落盘 xlsx
其余可入库类型 dws drive +download 原后缀
dlink / hlink 直接 missing(链接节点 fileSize=0) —
amind / appt unsupported_format(CLI 无内容导出入口,与老路径等价) —

平台侧判定一律保留:pick_suffix、SLIDES(PPT 必须 PDF 双胞胎)、magic 校验、大小上限、sha256、spool 原子写、exported_doc_is_blank() 空壳检查。dws 只负责“取字节”。

3. 错误映射

scripts/dws_error_map.py 把 dws 的错误体(严格版 ok/error 包裹、普通子命令 error 对象、本地错误、TLS/网络文本)统一映射为平台语义 {ok, code, retryable, missing}。要点:

  • 只有明确瞬时信号(429/5xx/超时/连接层失败/dws 二进制缺失)为 retryable=true;
  • 未分类错误 code=unknown 且不重试——避免被无限重试掩盖真因;
  • workspace node not found → missing=true(走 missing 分支而非 failed);
  • TLS 缺 CA(x509: certificate signed by unknown authority)→ tls_ca,终态(重试无意义,需补 CA)。

覆盖样本与断言见 scripts/test_dws_error_map.py(17 个断言,样本为实测捕获的真实错误体)。

4. 镜像与部署

  • 镜像:alpine:3.22 + gcompat libc6-compat ca-certificates(官方 dws 是动态链接 glibc 的二进制,靠 gcompat 在 musl 上运行;已验证端到端字节一致);dws 版本与 sha256 固定在 Dockerfile 的 DWS_VERSION/DWS_SHA256,禁用 dws upgrade。
  • 凭据:与宿主共享同一份 state(refresh token 是轮换制,两个副本会互相顶掉):
    • ~/.dws → /data/dws(DWS_CONFIG_DIR)
    • ~/.local/share/dws-cli → /data/home/.local/share/dws-cli(DWS_HOME)
  • 容器必须 --user <宿主 uid>:<gid>(worker 已是 1000:1000),否则 state 被写成 root 所有。

5. 续期 Runbook(refresh token 30 天)

# 到期前 7 天(阈值告警)在目标机执行,本人完成浏览器授权
dws auth login --device
# 验证必须真实调用,而不是只看 authenticated 字段
dws wiki +space-list --limit 1 -f json     # 期望 ok:true
docker exec <worker> dws auth status --readonly -f json

出现 code=credentials 时立即停批(不要重试风暴),重新授权后 --retry-failed 续跑。健康面板建议展示 refresh_expires_at:<7 天黄、<3 天红。

6. 回退演练(上线前必做)

docker compose exec worker env ARTIFACT_DINGTALK_FETCHER=legacy ...   # 或改 compose 环境变量后重建 worker
# 取同一批节点 → 断言 spool_ref/sha256 契约不变、无新增 code=* → 再切回 auto

保留 dingtalk-login sidecar 与 63GB 镜像树至少 2 周(镜像树可降级为只读热备)。

7. 验证证据(2026-10-09)

项 结果
影子比对(真实 worker 容器 vs 宿主 dws) adoc 24/24 等价(正文相似度 1.0、media 逐项相等、11/24 字节完全相同);普通文件 5/5 sha256 一致;axls 归一化后值覆盖 100%/100%
容器端到端(本改动 + 真容器约束 --read-only --tmpfs /tmp --user 1000:1000) adoc/docx 305,078B(sha 77b393c3…,与平台基准一致)、axls/xlsx 3,330B、pdf 27,140B → 3/3 成功;结果 JSON 字段与改动前完全一致
单元测试 scripts/artifact_fetch_test.py 14 项、scripts/artifact_fetch_blank_doc_test.py 5 项、scripts/test_dws_error_map.py 17 断言 —— 全绿
大表能力 平台老路径失败的 220MB/15 表/3,658 行 axls,dws + 转换器 18s 产出 128KB 有效 xlsx