Name: yiyunet/dsh-dingtalk-connector
Author: yiyunet

让钉钉 AI 表格的数据，流进 DeepSeek Harness

Read and write DingTalk AI Tables from DeepSeek Harness

简体中文 · English

简介

一个 DSH 插件，把钉钉 AI 表格（多维表 / aitable）接到 DeepSeek Harness 上。装完即得 10 个 dingtalk_aitable_* 工具和一个**「钉钉文档」设置面板**——在 Harness 里直接发现 Base、读数据表、按条件查记录、批量写回、导出带 BOM 的中文 CSV，并支持定时导出。

架构：包装钉钉官方 dws（dingtalk-workspace-cli）执行 dws aitable ...， 不直连 REST。这与钉钉官方 OpenClaw connector 同构——它自己也不直连 REST，而是注入 DWS_CLIENT_ID/SECRET 后调 dws（实测，2026-09-14 直读其仓库确认）。

设计取向：只读优先 + 写门禁。写与删除默认全关，删除还需每次逐条确认。宁可多一步确认，也不给"模型幻觉 + 权限过大"留组合空间。

⚠️ 这不是一个自包含插件——它依赖外部 CLI dws。装之前请先读安装与前置条件，三层依赖（Node / dws / 钉钉侧授权）缺一不可。

界面

上图为面板结构示意（非截图）。设置 → 「钉钉文档」（order 22，排在「IM机器人」之后），内含三区：账号绑定 / AI 表格清单 / 定时导出。真实截图待补，清单与打码要求见 docs/images/README.md。

能力一览

能力	入口	写门禁
自检（版本 / 授权 / 命令面 / RPC 端点）	`dingtalk_aitable_diagnose`	—
Base 文件：查 / 建 / 改 / 删	`dingtalk_aitable_base`	删需双锁
数据表：查表与字段 / 建 / 改 / 删	`dingtalk_aitable_table`	删需双锁
字段：查 / 建 / 改 / 删	`dingtalk_aitable_field`	删需双锁
记录：按 ID 或条件查（可全量拉）	`dingtalk_aitable_record_query`	无
记录：批量写 / 改 / 删	`dingtalk_aitable_record_write`	写 / 删门禁
受控直通（注册表内任意子命令）	`dingtalk_aitable_raw`	危险命令需双锁
候选 Base 发现 + 可读性实测	`dingtalk_aitable_scan`	无
全量导出 CSV（带 BOM，覆盖同名）	`dingtalk_aitable_export_csv`	无
定时导出任务：建 / 列 / 删 / 启停 / 立即执行	`dingtalk_sync_job`	无

双锁 = allowDelete: true（配置层）+ confirm: true（逐次，表示已获同意）。

首屏必读三条

这三条最容易被误解，先看这里再看细节。

定时器跑在 DSH host 进程内——DSH 关着时不执行，重启后重算下次触发点。不是云端定时。

钉钉侧没有"列出全部 Base"的接口——扫描产出是「候选 ∪ 人工补录」，不保证穷尽，且 base search 的 hasMore: true 是误报（游标翻页无效）。

写与删除门禁默认全关——删除还需每次 confirm=true。

本 README 中每条技术结论均标明来源档位：实测 / 官方原文 / 推测，并附取得日期。

一、为什么从"手搓 REST"改成"包装 dws"

	v0.1 手搓 REST（已废弃）	v0.2+ 包装 dws（当前）
端点来源	靠推断，标 `pending`	官方 CLI 内置，已发布可用
鉴权	自己换 accessToken、缓存、刷新	dws 自动管理（2h 自动刷新）
分页/错误码	自己实现	dws 提供 `--format json` + 恢复闭环
正确性风险	高（路径与请求体都可能错）	低（命令面有官方文档）
维护成本	跟钉钉 API 变更	跟 dws 版本

结论：v0.1 已废弃。改为包装 dws，消除了全部端点不确定性。

同时纠正了 v0.1 的三处硬错误（官方文档明确点名）：

sheetId → 正确是 tableId（AI 表格的数据模型是 base/table/field/record）
记录写入 cells 的 key 必须是 fieldId（fldXXX），不是字段名
更新记录必须带 recordId

二、前置条件（钉钉侧 + 本机侧）

完整版见 docs/安装与前置条件.md（含平台矩阵、解压依赖、组织级拦阻、一键核验清单）。下面是速查版。

三层依赖，缺一不可：

层	要求
① 本机运行时	Node ≥ 22.19（本插件要求）；DSH `0.1.2-alpha.4` ~ `0.1.5-alpha.1`
② dws CLI	`npm i -g dingtalk-workspace-cli`，版本 ≥ 1.0.6（实测基线 `v1.0.61`）
③ 钉钉侧	授权＋开通「AI 表格记录读写」权限＋把应用加为 Base 协作者（可编辑）★最易漏

1. 安装 dws（本机）

npm i -g dingtalk-workspace-cli
dws --version          # 必须 >= 1.0.6，实测基线 v1.0.61
npm root -g            # 记下前缀，Windows 上要用它填 dwsEntry

⚠️ dws 不是纯 JS 包——它带 postinstall，安装时下载并解压一个平台原生二进制（约 25 MB）。支持 Windows / macOS / Linux 的 x64 与 arm64 六个平台。解压依赖：Windows 用系统自带 powershell.exe，macOS / Linux 需要 tar 或 unzip。完整矩阵见 docs/安装与前置条件.md。

2. 授权（二选一）

方式 A — 扫码登录（交互式）

dws auth login         # 钉钉 App 扫码授权；token 自动刷新（access 2h / refresh 30d）
dws auth status        # 确认已登录

方式 B — 复用钉钉应用凭证（headless / 推荐给服务器）

# Windows
set DWS_CLIENT_ID=<你的 Client ID>
set DWS_CLIENT_SECRET=<你的 Client Secret>
# macOS / Linux
export DWS_CLIENT_ID=<你的 Client ID>
export DWS_CLIENT_SECRET=<你的 Client Secret>

dws auth login

凭证优先级：--token > DWS_CLIENT_ID/SECRET > OAuth 加密存储。凭证只走环境变量注入子进程，不进命令行参数（避免出现在进程列表里）。

3. 开通权限（极易漏，漏了必 403）

钉钉开发者后台 → 该应用 → 权限管理 → 开通 AI 表格（多维表）记录读写权限 → 发布生效
目标 Base → 右上角「协作/分享」→ 把该应用加为协作者，权限给到可编辑

这两件事缺一不可。dws 报 permission denied / 403 时，九成是这里没做完。

三、安装插件

# 从 npm 安装
dsh plugin --profile web add @yiyunet/dsh-dingtalk-connector

# 或从本地路径安装（开发时）
dsh plugin --profile web add "<本仓库绝对路径>"

dsh --profile web --dump-config          # 期望看到 dingtalk-connector 这一层

然后重启 dsh web。

自带一个引导 CLI：

npx @yiyunet/dsh-dingtalk-connector install [--profile web]   # 安装 + 核对配置层
npx @yiyunet/dsh-dingtalk-connector doctor                    # 体检：dsh / dws / Node / 授权状态

四、配置（`cordis.patch.yml`）

配置项	默认	说明
`dwsCommand`	`dws`	PATH 上的命令名
`dwsEntry`	无	Windows 建议设：dws 的 JS 入口绝对路径。设了就用 node 直接 spawn，完全不走 shell，记录文本里的引号/`&`/`\|` 才安全
`timeoutMs`	60000	单条命令超时
`clientIdEnv` / `clientSecretEnv`	`DWS_CLIENT_ID` / `DWS_CLIENT_SECRET`	凭证环境变量名
`allowWrite`	false	开关：create / update
`allowDelete`	false	开关：delete（独立，且每次还要 `confirm=true`）
`maxBatch`	30	单次批量上限（官方 connector skill 规定 ≤30）
`exportRoot`	无	可选：把导出落盘限制在指定目录内
`defaultExportDir`	无	可选：面板「选表后自动填充」的目录；不设则只填文件名
`scanConcurrency`	4	扫描可读性实测的并发数（防限流）

关于 `dwsEntry`（Windows 上的安全要点）

Windows 上 .cmd 必须经 shell 启动，而 shell 会解释参数里的元字符——记录文本含引号或 &/| 时可能被注入。插件对此硬拒绝（返回 ARG_UNSAFE 并给出指引）。

要彻底解决：把 dwsEntry 指向 dws 的 JS 入口，例如

dwsEntry: '<npm root -g>/dingtalk-workspace-cli/bin/dws.js'

先用 npm root -g 确认你本机的实际前缀（Windows 上分隔符用 \）。

五、十个工具

工具	作用	门禁
`dingtalk_aitable_diagnose`	自检：dws 版本 / 授权状态 / 已注册命令	无
`dingtalk_aitable_base`	Base 文件：list / search / get / create / update / delete	delete 需双锁
`dingtalk_aitable_table`	数据表：get（必传 `tableIds` 才返回字段）/ create / update / delete	delete 需双锁
`dingtalk_aitable_field`	字段：get / create / update / delete	delete 需双锁
`dingtalk_aitable_record_query`	读记录（按 ID 或条件查；`all=true` 可全量拉）	无
`dingtalk_aitable_record_write`	写记录：create / update / delete	write / delete 门禁
`dingtalk_aitable_raw`	受控直通：注册表内任意子命令	危险命令需双锁
`dingtalk_aitable_scan`	候选 Base 发现 + 可读性实测	无
`dingtalk_aitable_export_csv`	全量导出 CSV（带 BOM，表头用字段中文名，覆盖同名）	无（受 `exportRoot` 可选约束）
`dingtalk_sync_job`	定时导出任务 create / list / remove / enable / disable / run-now	无

双锁 = allowDelete: true（配置）+ confirm: true（逐次，表示已获同意）。

五之二、设置面板「钉钉文档」

在设置里出现一级项 「钉钉文档」（order 22，排在「IM机器人」之后）。

面板做三件事

区	内容
账号绑定	显示 CLI 版本、企业名 / 用户名、access token 到期、凭证来源、写门禁状态；含扫码绑定会话（二维码 / 深链 / 原始输出 / 组织拦阻提示）
AI 表格清单	输入关键词 → 扫描（候选发现 + 可读性实测）→ 每个 Base 标「可读/不可读」→ 展开看数据表 → 单选一张表 → 复制 Base ID / Table ID
定时导出	选中的表 + 输出路径 + 每天/每周 + 时间 → 新建任务；任务表显示下次/上次结果，支持立即执行 / 启停 / 删除

工程形态

lib/client.js 是 npm run build 的构建产物：esbuild 把 plugin-src/client/impl.mjs 打成 IIFE，再把手写的装载器 wrapper plugin-src/client/index.mjs 接在其后，产出官方客户端模块系统同形的结构：

window.__ModuleLoader__.load({
  id: '@yiyunet/dsh-dingtalk-connector',
  factory: (require) => { /* ... */ return module.exports },   // 契约：{ name, inject, apply }
})

平台冻结模块表提供 require('react')；打包时 react / react-dom 标记为 external（运行时解析）
客户端 → 宿主：ctx.connection.rpc.call('/api', 'dsh-dingtalk-connector', { method, payload }, signal)
宿主端点：ctx.connection.fetch.register({ path: '/api/dsh-dingtalk-connector', methods:['POST'], ... })（见 plugin-src/host/rpc.mjs）

⚠️ 关键架构约束：`connection` 必须走 scoped 注入，绝不能写进 `inject`

connection 服务只存在于 web 平面（由 packages/bundle/web-app 挂载 @deepseek-ai/dsh-client-connection）。

如果把它写进本插件的顶层声明 inject = ['tools', 'connection']，那么：

在 headless / tui 等没有 web 连接的 profile 里，整个插件会永远停在 inactive —— 连那 10 个 dingtalk_aitable_* 工具会一起消失。

因为本插件结构上分两半：工具注册（宿主平面，任何 profile 都该有）与 面板 RPC 端点（天然 web-only）。正确写法是把后者放进子 fiber：

export const inject = ['tools']                    // ← 保持不动，只声明真正必需的

ctx.inject(['connection'], (rpcCtx) => {           // ← 可选依赖：就绪才执行，无此服务则静默不执行
  const disposeRpc = registerConnectorRpc(rpcCtx, { ... })
  rpcCtx.effect(function* () { yield () => disposeRpc?.() }, '…rpc endpoint')
})

面板可用性自证：dingtalk_aitable_diagnose 的返回里带 rpcEndpoint 字段， registered: true 才说明 /api/dsh-dingtalk-connector 端点挂上了。

RPC 方法（面板可调）

status / accounts / unbind / loginStart / loginStatus / loginCancel / scan / tables / exportNow / jobsList / jobCreate / jobRemove / jobToggle / jobRunNow —— 全部只读或本地文件操作，不触碰钉钉写接口。

多账号：扫码绑定 / 移除接入（已实现）

能力	命令	说明
列出已绑定账号	`dws profile list --format json`	一个 profile = 一个 `corpId + userId`；可同时绑多个账号
移除接入	`dws auth logout --profile <corpId:userId>`	精确选择器只退一个账号（不传则退全部）；面板做二次确认
扫码绑定	`dws auth login --device --recommend --format json`	面板「扫码绑定」按钮；输出实时回显，成功后自动刷新账号列表

⚠️ 两点必须知道的事实（实测，避免误判）

① dws 的设备流不输出二维码。 它只给：

link: https://login.dingtalk.com/oauth2/device/verify.htm
authorization code: QMQK-PTMB
Or open the following link:
  https://login.dingtalk.com/oauth2/device/verify.htm?user_code=QMQK-PTMB

因此二维码由本插件自己生成：宿主侧用 qrcode 包把带 user_code 的深链画成 SVG data URL，前端只渲染 <img>。绝不调用第三方二维码服务 —— 认证链接不外发。解析失败时降级为"只显示深链 + 授权码"。

② 本机已登录钉钉时，设备流可能「无需扫码」即完成。 这不是"系统自动批准"，而是：本机当前已处于钉钉登录态，设备流因此可直接选定对应的钉钉账号与企业组织，无需扫码就通过授权并继续换取令牌。

推论（重要）：

点「扫码绑定」在已登录的机器上可能不弹码直接完成 —— 更省事，但它用的是本机当前选定的账号/组织，不是让你重新挑一个；
「探测输出 8 秒」这个按钮不是零副作用：若组织已开启 CLI 访问，探测即可能真的新增账号。

⛔ 已知阻塞：组织未开启 CLI 个人数据访问

新登录会走到 Step 4 被拦下：

CLI data access is not enabled for this organization
The organization admin has not enabled "Allow members to access their personal data via CLI".

需组织主管理员在钉钉开放平台 → 开发者设置开启该开关后重新扫码。 这是组织管理动作，不是技术配置；未解决前，"多账号"实际只能绑到 1 个账号。

注：现有登录在此开关未开的情况下仍可用（auth status 有效、数据可读）。新登录被拦而旧会话可用的原因尚未查明，建议由管理员核对该开关的真实状态。

五之三、工作流（扫描 → 勾选 → 定时）

① dingtalk_aitable_scan(keywords="关键词A,关键词B", withTables=true)
      → 候选 Base 清单 + 每个的「可读性实测」结果（readable / 失败原因）
      → 记下要关注的表：baseId + tableId

② dingtalk_aitable_export_csv(baseId, tableId, outputPath="<绝对路径>.csv")
      → 立即导出一份，验证表头/编码/条数对不对（用 Excel 打开看中文是否正常）

③ dingtalk_sync_job(action="create", baseId, tableId,
                    outputPath="<绝对路径>.csv",
                    frequency="daily", time="09:00", label="订单销售日更")
      → 每天 09:00 自动导出并覆盖同名文件

④ dingtalk_sync_job(action="list")                    # 看下次触发时间与上次结果
   dingtalk_sync_job(action="run-now", id="<id>")     # 立即跑一次验证

⚠️ 三条必须知道的语义

定时器跑在 DSH host 进程内：DSH 关着时不会执行（已确认接受的语义）；重启后自动重算下次触发点。
"枚举全部 Base"在钉钉侧做不到：base list 只给最近访问，base search 每次约 4 条且游标翻页无效 （实测 hasMore 是误报）。所以扫描是"多渠道候选 ∪ 人工补录"，不保证穷尽——多给关键词，或直接给 baseId 补录。
CSV 必须带 BOM：插件的 CSV 以 \uFEFF 开头，这是 Excel 正确识别 UTF-8 中文的唯一条件。插件落盘后会回读首 3 字节自证（编辑器看不见 BOM，ripgrep 还会主动剥掉它）。

六、标准工作流（官方文档规定，照做即可）

1. dws aitable base search --query "关键词"          → 提 baseId
2. dws aitable base get --base-id <B>                → 提 tableId
3. dws aitable table get --base-id <B> --table-id <T> → 提 fieldId  ★写记录前必须
4. dws aitable record query --base-id <B> --table-id <T>
5. dws aitable record create --records '[{"cells":{"fldXXX":"值"}}]'

插件调用顺序等价：base(action=search) → base(action=get) → table(action=get) → record_query → record_write。

先跑 diagnose，再按上面走。拿不到 baseId 时注意：base list 只返回最近访问过的 Base，用前端打开一次该表，或改用 base search。

cells 读写格式速查（官方）

字段类型	写入	读取返回
text	`"字符串"`	`"字符串"`
number	`123`	`"123"`
singleSelect	`"选项名"` 或 `{"id":"xxx"}`	`{"id":"x","name":"选项名"}`
multipleSelect	`["选项A","选项B"]`	`[{"id":"x","name":"选项A"}]`
date	`"2026-03-13"`	ISO 字符串
checkbox	`true`/`false`	`true`/`false`
user	`[{"userId":"xxx"}]`	`[{"corpId":"x","userId":"x"}]`
url	`{"text":"显示文本","link":"https://..."}`	同写入
richText	`{"markdown":"加粗"}`	同写入

过滤（filters）里 singleSelect 建议用 option id（从 field get 取）更可靠；写入时可直接用选项名。

七、排错（错误信号 → 下一步）

信号	含义	处理
`command not found: dws`	CLI 未安装	`npm i -g dingtalk-workspace-cli`
`请先执行 dws login`	未授权	`dws auth login`
`AUTH_TOKEN_EXPIRED` / `USER_TOKEN_ILLEGAL`	token 过期	重新 `dws auth login`
`permission denied` / 403	权限不足	开发者后台开 AI 表格权限 + 把应用加为 Base 协作者
`RECOVERY_EVENT_ID=<id>`	已持久化失败快照	按 `dws recovery plan/execute/finalize` 闭环
`ARG_UNSAFE`	参数含 shell 元字符	配置 `dwsEntry` 走无 shell 模式
`PAGING_TRUNCATED`	达到翻页上限	用返回的 cursor 续拉，或调大 `pageLimit`
面板一片空白/「空壳」	RPC 信封形状或端点名不一致	跑 `npm run verify`（会校验端点一致性）

八、安全与边界

写门禁默认全关；删除另需逐次 confirm=true（双锁）。
凭证只走环境变量注入子进程，不进命令行参数（避免出现在进程列表里）。
参数逐元素传递，绝不拼成 shell 字符串；设了 dwsEntry 即完全无 shell，否则有硬校验。
客户端不硬编码导出路径：默认目录由宿主下发（defaultExportDir）。
工具可见性：宿主侧 bundle 挂 host plane，该 profile 下所有会话都能看到这 10 个工具。
官方 connector 自身的安全提醒同样适用：模型幻觉 / 执行不可控 / 提示词注入是固有风险；官方建议"避免在企业生产环境直接部署"。本插件用只读优先 + 写门禁降低暴露面。
本插件为非官方社区集成，与钉钉、DeepSeek 无隶属或背书关系。

九、开发

npm install          # 装 esbuild（构建期）与可选的 qrcode；装完会自动构建（prepare）
npm run build        # plugin-src/ → lib/（宿主：复制加横幅；客户端：esbuild + 装载器 wrapper）
npm test             # node --test 纯函数测试（调度 / CSV / 任务存储 / 命令注册表）
npm run verify       # 八类发布契约断言
npm run doctor       # 环境自检（只读）：Node / esbuild / 源文件 / 产物 / qrcode 是否就位
npm run inspect      # 诊断：把 lib/client.js 的体量/行数/关键标记实况摆出来（报"找不到标记"时用它）
npm run check        # build && test && verify   ← CI 跑的就是这一条

绝不要直接改 lib/ —— 它是构建产物，会被下次构建覆盖。唯一真源是 plugin-src/。

⚠️ `lib/` 不在版本库里 —— 删了、重置了、重装后都要重建

lib/ 与 node_modules/ 都在 .gitignore 里，但 package.json 的 main 指向 lib/index.mjs。后果是：lib/ 缺失时插件加载不了，而症状只是一句晦涩的模块找不到，不会告诉你"你还没构建"。

因此有两道防护：

防护行为

prepare 钩子 npm install 装完自动跑一次构建。它永不失败（构建失败也只打印指引，不会让 install 整体失败）；别人把它当依赖安装时静默跳过（发布包自带 lib/）。
⚠️ 为什么是 prepare 而不是 postinstall：pnpm 10+ 默认拦截依赖的安装期脚本（供应链防护），postinstall 会让消费者侧直接安装失败（ERR_PNPM_IGNORED_BUILDS）；而 prepare 对 registry 依赖根本不执行，恰好不在拦截范围内

npm run doctor 只读自检，逐项报告「Node / esbuild / 9 个宿主源文件 / lib/ 产物 / qrcode」是否就位，并直接给出该跑什么

症状对照：DSH 起不来、日志说 @yiyunet/dsh-dingtalk-connector 模块找不到或入口缺失 → 九成是 lib/ 不在 → npm run doctor 确认 → npm run build。

`lib/` 的形态（构建产物布局）

产物	来源	说明
`lib/index.mjs`	`plugin-src/host/index.mjs`	插件入口（`package.json` 的 `main`）。宿主侧 9 个 `.mjs` 原样复制，只在文件头加"由构建生成"横幅
`lib/<其余>.mjs`	`plugin-src/host/*.mjs`	同样原样复制 —— 保留 `.mjs` 是因为它们确实是 ESM，这个扩展名比 `.js` 准确
`lib/client.js`	`esbuild(plugin-src/client/impl.mjs)` + `plugin-src/client/index.mjs`	浏览器半侧产物（`dsh.client` 引用）。IIFE 打包体独占一行，装载器 wrapper 接在其后

宿主侧不做转译（源码本来就是 ESM，多一道转译只增加出错面）。

为什么匹配产物时要"解转义"

esbuild 默认把非 ASCII 字符（如中文）输出成 \uXXXX 转义。 所以"源码里写着「钉钉文档」"和 "产物里能 includes('钉钉文档')"是两回事 —— 直接匹配会把一个完全正确的产物判成"契约漂移"。 scripts/bundle-markers.mjs 提供 containsMarker()：原样或解转义后命中都算通过，build 与 verify 共用同一套判断。

发布契约断言（`npm run verify`）

必需文件齐全（源码 + 构建产物 + 对外文档）
任何依赖节与 lock 文件都不得出现 @deepseek-ai/dsh-* —— DSH 运行时包用模块局部 Symbol 做 key，装第二份物理副本会破坏 Host 查找
客户端产物注册了正确的装载器 id
客户端产物注册了正确的设置面板契约（id / order / label / 挂载点）
客户端产物不含 ESM 顶层语法（它是产物，不是源码）
RPC 端点名在宿主源、客户端源、客户端产物三处一致（曾因信封形状不一致导致面板空壳而 RPC 不报错）
全仓不含个人绝对路径与凭证赋值
files 白名单自洽 —— 白名单每条在磁盘上存在；生命周期脚本（如 postinstall）引用的文件其目录已入包；package.json 声明的入口（main / exports / bin）已入包。 为什么必须有这条：本地 link: 装载时 files 字段完全不生效，漏件在开发机上永远看不见，只有 npm publish 之后才会在安装方那里炸成 npm install 失败。

构建/校验报错时的排查顺序

npm run inspect      # ① 产物实况：体量、行数、BOM、含不含转义、六项关键标记逐条命中情况
                     #    → 若"解转义后命中"，那是正常现象，不是故障
                     # ② 若真缺某项：去 plugin-src/client/impl.mjs 里搜该串
                     #    · 源码有、产物无 → 产物过期，重跑 npm run build
                     #    · 源码也无     → 契约漂移，改源码而不是改校验脚本

十、卸载

dsh plugin --profile web remove @yiyunet/dsh-dingtalk-connector

十一、文档索引

根目录的 README 讲怎么用；docs/ 讲为什么这样做、当时验证了什么。

文档	内容
docs/安装与前置条件.md	★ 最先读这篇：Node / dws / 钉钉侧授权三层依赖全解，含平台矩阵与核验清单
docs/发布与版本管理.md	怎么传上 GitHub、加功能后怎么升版本与发布、发布前检查清单
docs/README.md	文档总索引（按问题找文档）
docs/adr/0001-从手搓REST改为包装dws.md	架构决策记录：为什么废弃 v0.1 的手搓 REST
docs/实测/	逐次真机验证留痕（踩到的坑与确认的行为）
CONTEXT.md	术语表与禁用说法——措辞精度在这里是功能，不是文风
CHANGELOG.md	变更记录（含 v0.1 → v0.2 架构反转留痕）
THIRD_PARTY_NOTICES.md	第三方组件与商标声明
README.en.md	English

十二、检查与安装更新

# 查看当前版本
npm view @yiyunet/dsh-dingtalk-connector version

# 升级插件
dsh plugin --profile web add @yiyunet/dsh-dingtalk-connector@latest
dsh plugin --profile web remove @yiyunet/dsh-dingtalk-connector   # 卸载

# 顺带升级本插件的外部依赖 dws（它是独立包，不会随插件一起升）
npm i -g dingtalk-workspace-cli@latest
dws --version

注意：dws 是本插件的外部前置依赖，不由插件管理。插件版本没变但行为异常时，先查 dws --version——很可能是 dws 升级带来了命令面变化。

升级后跑一次自检确认：

dingtalk_aitable_diagnose

十三、联系方式

问题反馈 / 功能建议：优先走 GitHub Issues
安全相关：请勿公开提 issue —— 本插件涉及钉钉凭证与组织数据访问，详见「八、安全与边界」

十四、贡献者 ✨

感谢每一位帮助本项目成长的贡献者！

本项目采用 All Contributors 规范，认可代码、文档、测试、问题反馈、想法和其他形式的贡献。

贡献类型说明： 💻 代码 · 📖 文档 · ⚠️ 测试 · 🚇 基础设施 · 🌍 翻译 · 🤔 想法与规划。

贡献名单由 .all-contributorsrc 管理。

十五、许可与非官方声明

许可：MIT © 2026 yiyunet
非官方：本插件是非官方社区集成，与钉钉（DingTalk）、DeepSeek 无隶属或背书关系。
外部依赖：dws（dingtalk-workspace-cli）为钉钉官方发布，采用 Apache-2.0，版权归其作者所有。详见 THIRD_PARTY_NOTICES.md。

让钉钉 AI 表格的数据，流进 DeepSeek Harness

Read and write DingTalk AI Tables from DeepSeek Harness

简体中文 · English

简介

设计取向：只读优先 + 写门禁。写与删除默认全关，删除还需每次逐条确认。宁可多一步确认，也不给"模型幻觉 + 权限过大"留组合空间。

⚠️ 这不是一个自包含插件——它依赖外部 CLI dws。装之前请先读安装与前置条件，三层依赖（Node / dws / 钉钉侧授权）缺一不可。

界面

上图为面板结构示意（非截图）。设置 → 「钉钉文档」（order 22，排在「IM机器人」之后），内含三区：账号绑定 / AI 表格清单 / 定时导出。真实截图待补，清单与打码要求见 docs/images/README.md。

能力一览

能力	入口	写门禁
自检（版本 / 授权 / 命令面 / RPC 端点）	`dingtalk_aitable_diagnose`	—
Base 文件：查 / 建 / 改 / 删	`dingtalk_aitable_base`	删需双锁
数据表：查表与字段 / 建 / 改 / 删	`dingtalk_aitable_table`	删需双锁
字段：查 / 建 / 改 / 删	`dingtalk_aitable_field`	删需双锁
记录：按 ID 或条件查（可全量拉）	`dingtalk_aitable_record_query`	无
记录：批量写 / 改 / 删	`dingtalk_aitable_record_write`	写 / 删门禁
受控直通（注册表内任意子命令）	`dingtalk_aitable_raw`	危险命令需双锁
候选 Base 发现 + 可读性实测	`dingtalk_aitable_scan`	无
全量导出 CSV（带 BOM，覆盖同名）	`dingtalk_aitable_export_csv`	无
定时导出任务：建 / 列 / 删 / 启停 / 立即执行	`dingtalk_sync_job`	无

双锁 = allowDelete: true（配置层）+ confirm: true（逐次，表示已获同意）。

首屏必读三条

这三条最容易被误解，先看这里再看细节。

定时器跑在 DSH host 进程内——DSH 关着时不执行，重启后重算下次触发点。不是云端定时。

钉钉侧没有"列出全部 Base"的接口——扫描产出是「候选 ∪ 人工补录」，不保证穷尽，且 base search 的 hasMore: true 是误报（游标翻页无效）。

写与删除门禁默认全关——删除还需每次 confirm=true。

本 README 中每条技术结论均标明来源档位：实测 / 官方原文 / 推测，并附取得日期。

一、为什么从"手搓 REST"改成"包装 dws"

	v0.1 手搓 REST（已废弃）	v0.2+ 包装 dws（当前）
端点来源	靠推断，标 `pending`	官方 CLI 内置，已发布可用
鉴权	自己换 accessToken、缓存、刷新	dws 自动管理（2h 自动刷新）
分页/错误码	自己实现	dws 提供 `--format json` + 恢复闭环
正确性风险	高（路径与请求体都可能错）	低（命令面有官方文档）
维护成本	跟钉钉 API 变更	跟 dws 版本

结论：v0.1 已废弃。改为包装 dws，消除了全部端点不确定性。

同时纠正了 v0.1 的三处硬错误（官方文档明确点名）：

sheetId → 正确是 tableId（AI 表格的数据模型是 base/table/field/record）
记录写入 cells 的 key 必须是 fieldId（fldXXX），不是字段名
更新记录必须带 recordId

二、前置条件（钉钉侧 + 本机侧）

完整版见 docs/安装与前置条件.md（含平台矩阵、解压依赖、组织级拦阻、一键核验清单）。下面是速查版。

三层依赖，缺一不可：

层	要求
① 本机运行时	Node ≥ 22.19（本插件要求）；DSH `0.1.2-alpha.4` ~ `0.1.5-alpha.1`
② dws CLI	`npm i -g dingtalk-workspace-cli`，版本 ≥ 1.0.6（实测基线 `v1.0.61`）
③ 钉钉侧	授权＋开通「AI 表格记录读写」权限＋把应用加为 Base 协作者（可编辑）★最易漏

1. 安装 dws（本机）

npm i -g dingtalk-workspace-cli
dws --version          # 必须 >= 1.0.6，实测基线 v1.0.61
npm root -g            # 记下前缀，Windows 上要用它填 dwsEntry

⚠️ dws 不是纯 JS 包——它带 postinstall，安装时下载并解压一个平台原生二进制（约 25 MB）。支持 Windows / macOS / Linux 的 x64 与 arm64 六个平台。解压依赖：Windows 用系统自带 powershell.exe，macOS / Linux 需要 tar 或 unzip。完整矩阵见 docs/安装与前置条件.md。

2. 授权（二选一）

方式 A — 扫码登录（交互式）

dws auth login         # 钉钉 App 扫码授权；token 自动刷新（access 2h / refresh 30d）
dws auth status        # 确认已登录

方式 B — 复用钉钉应用凭证（headless / 推荐给服务器）

# Windows
set DWS_CLIENT_ID=<你的 Client ID>
set DWS_CLIENT_SECRET=<你的 Client Secret>
# macOS / Linux
export DWS_CLIENT_ID=<你的 Client ID>
export DWS_CLIENT_SECRET=<你的 Client Secret>

dws auth login

凭证优先级：--token > DWS_CLIENT_ID/SECRET > OAuth 加密存储。凭证只走环境变量注入子进程，不进命令行参数（避免出现在进程列表里）。

3. 开通权限（极易漏，漏了必 403）

钉钉开发者后台 → 该应用 → 权限管理 → 开通 AI 表格（多维表）记录读写权限 → 发布生效
目标 Base → 右上角「协作/分享」→ 把该应用加为协作者，权限给到可编辑

这两件事缺一不可。dws 报 permission denied / 403 时，九成是这里没做完。

三、安装插件

# 从 npm 安装
dsh plugin --profile web add @yiyunet/dsh-dingtalk-connector

# 或从本地路径安装（开发时）
dsh plugin --profile web add "<本仓库绝对路径>"

dsh --profile web --dump-config          # 期望看到 dingtalk-connector 这一层

然后重启 dsh web。

自带一个引导 CLI：

npx @yiyunet/dsh-dingtalk-connector install [--profile web]   # 安装 + 核对配置层
npx @yiyunet/dsh-dingtalk-connector doctor                    # 体检：dsh / dws / Node / 授权状态

四、配置（`cordis.patch.yml`）

配置项	默认	说明
`dwsCommand`	`dws`	PATH 上的命令名
`dwsEntry`	无	Windows 建议设：dws 的 JS 入口绝对路径。设了就用 node 直接 spawn，完全不走 shell，记录文本里的引号/`&`/`\|` 才安全
`timeoutMs`	60000	单条命令超时
`clientIdEnv` / `clientSecretEnv`	`DWS_CLIENT_ID` / `DWS_CLIENT_SECRET`	凭证环境变量名
`allowWrite`	false	开关：create / update
`allowDelete`	false	开关：delete（独立，且每次还要 `confirm=true`）
`maxBatch`	30	单次批量上限（官方 connector skill 规定 ≤30）
`exportRoot`	无	可选：把导出落盘限制在指定目录内
`defaultExportDir`	无	可选：面板「选表后自动填充」的目录；不设则只填文件名
`scanConcurrency`	4	扫描可读性实测的并发数（防限流）

关于 `dwsEntry`（Windows 上的安全要点）

要彻底解决：把 dwsEntry 指向 dws 的 JS 入口，例如

dwsEntry: '<npm root -g>/dingtalk-workspace-cli/bin/dws.js'

先用 npm root -g 确认你本机的实际前缀（Windows 上分隔符用 \）。

五、十个工具

工具	作用	门禁
`dingtalk_aitable_diagnose`	自检：dws 版本 / 授权状态 / 已注册命令	无
`dingtalk_aitable_base`	Base 文件：list / search / get / create / update / delete	delete 需双锁
`dingtalk_aitable_table`	数据表：get（必传 `tableIds` 才返回字段）/ create / update / delete	delete 需双锁
`dingtalk_aitable_field`	字段：get / create / update / delete	delete 需双锁
`dingtalk_aitable_record_query`	读记录（按 ID 或条件查；`all=true` 可全量拉）	无
`dingtalk_aitable_record_write`	写记录：create / update / delete	write / delete 门禁
`dingtalk_aitable_raw`	受控直通：注册表内任意子命令	危险命令需双锁
`dingtalk_aitable_scan`	候选 Base 发现 + 可读性实测	无
`dingtalk_aitable_export_csv`	全量导出 CSV（带 BOM，表头用字段中文名，覆盖同名）	无（受 `exportRoot` 可选约束）
`dingtalk_sync_job`	定时导出任务 create / list / remove / enable / disable / run-now	无

双锁 = allowDelete: true（配置）+ confirm: true（逐次，表示已获同意）。

五之二、设置面板「钉钉文档」

在设置里出现一级项 「钉钉文档」（order 22，排在「IM机器人」之后）。

面板做三件事

区	内容
账号绑定	显示 CLI 版本、企业名 / 用户名、access token 到期、凭证来源、写门禁状态；含扫码绑定会话（二维码 / 深链 / 原始输出 / 组织拦阻提示）
AI 表格清单	输入关键词 → 扫描（候选发现 + 可读性实测）→ 每个 Base 标「可读/不可读」→ 展开看数据表 → 单选一张表 → 复制 Base ID / Table ID
定时导出	选中的表 + 输出路径 + 每天/每周 + 时间 → 新建任务；任务表显示下次/上次结果，支持立即执行 / 启停 / 删除

工程形态

window.__ModuleLoader__.load({
  id: '@yiyunet/dsh-dingtalk-connector',
  factory: (require) => { /* ... */ return module.exports },   // 契约：{ name, inject, apply }
})

平台冻结模块表提供 require('react')；打包时 react / react-dom 标记为 external（运行时解析）
客户端 → 宿主：ctx.connection.rpc.call('/api', 'dsh-dingtalk-connector', { method, payload }, signal)
宿主端点：ctx.connection.fetch.register({ path: '/api/dsh-dingtalk-connector', methods:['POST'], ... })（见 plugin-src/host/rpc.mjs）

⚠️ 关键架构约束：`connection` 必须走 scoped 注入，绝不能写进 `inject`

connection 服务只存在于 web 平面（由 packages/bundle/web-app 挂载 @deepseek-ai/dsh-client-connection）。

如果把它写进本插件的顶层声明 inject = ['tools', 'connection']，那么：

在 headless / tui 等没有 web 连接的 profile 里，整个插件会永远停在 inactive —— 连那 10 个 dingtalk_aitable_* 工具会一起消失。

因为本插件结构上分两半：工具注册（宿主平面，任何 profile 都该有）与 面板 RPC 端点（天然 web-only）。正确写法是把后者放进子 fiber：

export const inject = ['tools']                    // ← 保持不动，只声明真正必需的

ctx.inject(['connection'], (rpcCtx) => {           // ← 可选依赖：就绪才执行，无此服务则静默不执行
  const disposeRpc = registerConnectorRpc(rpcCtx, { ... })
  rpcCtx.effect(function* () { yield () => disposeRpc?.() }, '…rpc endpoint')
})

面板可用性自证：dingtalk_aitable_diagnose 的返回里带 rpcEndpoint 字段， registered: true 才说明 /api/dsh-dingtalk-connector 端点挂上了。

RPC 方法（面板可调）

多账号：扫码绑定 / 移除接入（已实现）

能力	命令	说明
列出已绑定账号	`dws profile list --format json`	一个 profile = 一个 `corpId + userId`；可同时绑多个账号
移除接入	`dws auth logout --profile <corpId:userId>`	精确选择器只退一个账号（不传则退全部）；面板做二次确认
扫码绑定	`dws auth login --device --recommend --format json`	面板「扫码绑定」按钮；输出实时回显，成功后自动刷新账号列表

⚠️ 两点必须知道的事实（实测，避免误判）

① dws 的设备流不输出二维码。 它只给：

link: https://login.dingtalk.com/oauth2/device/verify.htm
authorization code: QMQK-PTMB
Or open the following link:
  https://login.dingtalk.com/oauth2/device/verify.htm?user_code=QMQK-PTMB

推论（重要）：

点「扫码绑定」在已登录的机器上可能不弹码直接完成 —— 更省事，但它用的是本机当前选定的账号/组织，不是让你重新挑一个；
「探测输出 8 秒」这个按钮不是零副作用：若组织已开启 CLI 访问，探测即可能真的新增账号。

⛔ 已知阻塞：组织未开启 CLI 个人数据访问

新登录会走到 Step 4 被拦下：

CLI data access is not enabled for this organization
The organization admin has not enabled "Allow members to access their personal data via CLI".

注：现有登录在此开关未开的情况下仍可用（auth status 有效、数据可读）。新登录被拦而旧会话可用的原因尚未查明，建议由管理员核对该开关的真实状态。

五之三、工作流（扫描 → 勾选 → 定时）

① dingtalk_aitable_scan(keywords="关键词A,关键词B", withTables=true)
      → 候选 Base 清单 + 每个的「可读性实测」结果（readable / 失败原因）
      → 记下要关注的表：baseId + tableId

② dingtalk_aitable_export_csv(baseId, tableId, outputPath="<绝对路径>.csv")
      → 立即导出一份，验证表头/编码/条数对不对（用 Excel 打开看中文是否正常）

③ dingtalk_sync_job(action="create", baseId, tableId,
                    outputPath="<绝对路径>.csv",
                    frequency="daily", time="09:00", label="订单销售日更")
      → 每天 09:00 自动导出并覆盖同名文件

④ dingtalk_sync_job(action="list")                    # 看下次触发时间与上次结果
   dingtalk_sync_job(action="run-now", id="<id>")     # 立即跑一次验证

⚠️ 三条必须知道的语义

定时器跑在 DSH host 进程内：DSH 关着时不会执行（已确认接受的语义）；重启后自动重算下次触发点。
"枚举全部 Base"在钉钉侧做不到：base list 只给最近访问，base search 每次约 4 条且游标翻页无效 （实测 hasMore 是误报）。所以扫描是"多渠道候选 ∪ 人工补录"，不保证穷尽——多给关键词，或直接给 baseId 补录。
CSV 必须带 BOM：插件的 CSV 以 \uFEFF 开头，这是 Excel 正确识别 UTF-8 中文的唯一条件。插件落盘后会回读首 3 字节自证（编辑器看不见 BOM，ripgrep 还会主动剥掉它）。

六、标准工作流（官方文档规定，照做即可）

1. dws aitable base search --query "关键词"          → 提 baseId
2. dws aitable base get --base-id <B>                → 提 tableId
3. dws aitable table get --base-id <B> --table-id <T> → 提 fieldId  ★写记录前必须
4. dws aitable record query --base-id <B> --table-id <T>
5. dws aitable record create --records '[{"cells":{"fldXXX":"值"}}]'

插件调用顺序等价：base(action=search) → base(action=get) → table(action=get) → record_query → record_write。

先跑 diagnose，再按上面走。拿不到 baseId 时注意：base list 只返回最近访问过的 Base，用前端打开一次该表，或改用 base search。

cells 读写格式速查（官方）

字段类型	写入	读取返回
text	`"字符串"`	`"字符串"`
number	`123`	`"123"`
singleSelect	`"选项名"` 或 `{"id":"xxx"}`	`{"id":"x","name":"选项名"}`
multipleSelect	`["选项A","选项B"]`	`[{"id":"x","name":"选项A"}]`
date	`"2026-03-13"`	ISO 字符串
checkbox	`true`/`false`	`true`/`false`
user	`[{"userId":"xxx"}]`	`[{"corpId":"x","userId":"x"}]`
url	`{"text":"显示文本","link":"https://..."}`	同写入
richText	`{"markdown":"加粗"}`	同写入

过滤（filters）里 singleSelect 建议用 option id（从 field get 取）更可靠；写入时可直接用选项名。

七、排错（错误信号 → 下一步）

信号	含义	处理
`command not found: dws`	CLI 未安装	`npm i -g dingtalk-workspace-cli`
`请先执行 dws login`	未授权	`dws auth login`
`AUTH_TOKEN_EXPIRED` / `USER_TOKEN_ILLEGAL`	token 过期	重新 `dws auth login`
`permission denied` / 403	权限不足	开发者后台开 AI 表格权限 + 把应用加为 Base 协作者
`RECOVERY_EVENT_ID=<id>`	已持久化失败快照	按 `dws recovery plan/execute/finalize` 闭环
`ARG_UNSAFE`	参数含 shell 元字符	配置 `dwsEntry` 走无 shell 模式
`PAGING_TRUNCATED`	达到翻页上限	用返回的 cursor 续拉，或调大 `pageLimit`
面板一片空白/「空壳」	RPC 信封形状或端点名不一致	跑 `npm run verify`（会校验端点一致性）

八、安全与边界

写门禁默认全关；删除另需逐次 confirm=true（双锁）。
凭证只走环境变量注入子进程，不进命令行参数（避免出现在进程列表里）。
参数逐元素传递，绝不拼成 shell 字符串；设了 dwsEntry 即完全无 shell，否则有硬校验。
客户端不硬编码导出路径：默认目录由宿主下发（defaultExportDir）。
工具可见性：宿主侧 bundle 挂 host plane，该 profile 下所有会话都能看到这 10 个工具。
官方 connector 自身的安全提醒同样适用：模型幻觉 / 执行不可控 / 提示词注入是固有风险；官方建议"避免在企业生产环境直接部署"。本插件用只读优先 + 写门禁降低暴露面。
本插件为非官方社区集成，与钉钉、DeepSeek 无隶属或背书关系。

九、开发

npm install          # 装 esbuild（构建期）与可选的 qrcode；装完会自动构建（prepare）
npm run build        # plugin-src/ → lib/（宿主：复制加横幅；客户端：esbuild + 装载器 wrapper）
npm test             # node --test 纯函数测试（调度 / CSV / 任务存储 / 命令注册表）
npm run verify       # 八类发布契约断言
npm run doctor       # 环境自检（只读）：Node / esbuild / 源文件 / 产物 / qrcode 是否就位
npm run inspect      # 诊断：把 lib/client.js 的体量/行数/关键标记实况摆出来（报"找不到标记"时用它）
npm run check        # build && test && verify   ← CI 跑的就是这一条

绝不要直接改 lib/ —— 它是构建产物，会被下次构建覆盖。唯一真源是 plugin-src/。

⚠️ `lib/` 不在版本库里 —— 删了、重置了、重装后都要重建

因此有两道防护：

防护行为

npm run doctor 只读自检，逐项报告「Node / esbuild / 9 个宿主源文件 / lib/ 产物 / qrcode」是否就位，并直接给出该跑什么

症状对照：DSH 起不来、日志说 @yiyunet/dsh-dingtalk-connector 模块找不到或入口缺失 → 九成是 lib/ 不在 → npm run doctor 确认 → npm run build。

`lib/` 的形态（构建产物布局）

产物	来源	说明
`lib/index.mjs`	`plugin-src/host/index.mjs`	插件入口（`package.json` 的 `main`）。宿主侧 9 个 `.mjs` 原样复制，只在文件头加"由构建生成"横幅
`lib/<其余>.mjs`	`plugin-src/host/*.mjs`	同样原样复制 —— 保留 `.mjs` 是因为它们确实是 ESM，这个扩展名比 `.js` 准确
`lib/client.js`	`esbuild(plugin-src/client/impl.mjs)` + `plugin-src/client/index.mjs`	浏览器半侧产物（`dsh.client` 引用）。IIFE 打包体独占一行，装载器 wrapper 接在其后

宿主侧不做转译（源码本来就是 ESM，多一道转译只增加出错面）。

为什么匹配产物时要"解转义"

发布契约断言（`npm run verify`）

必需文件齐全（源码 + 构建产物 + 对外文档）
任何依赖节与 lock 文件都不得出现 @deepseek-ai/dsh-* —— DSH 运行时包用模块局部 Symbol 做 key，装第二份物理副本会破坏 Host 查找
客户端产物注册了正确的装载器 id
客户端产物注册了正确的设置面板契约（id / order / label / 挂载点）
客户端产物不含 ESM 顶层语法（它是产物，不是源码）
RPC 端点名在宿主源、客户端源、客户端产物三处一致（曾因信封形状不一致导致面板空壳而 RPC 不报错）
全仓不含个人绝对路径与凭证赋值
files 白名单自洽 —— 白名单每条在磁盘上存在；生命周期脚本（如 postinstall）引用的文件其目录已入包；package.json 声明的入口（main / exports / bin）已入包。 为什么必须有这条：本地 link: 装载时 files 字段完全不生效，漏件在开发机上永远看不见，只有 npm publish 之后才会在安装方那里炸成 npm install 失败。

构建/校验报错时的排查顺序

npm run inspect      # ① 产物实况：体量、行数、BOM、含不含转义、六项关键标记逐条命中情况
                     #    → 若"解转义后命中"，那是正常现象，不是故障
                     # ② 若真缺某项：去 plugin-src/client/impl.mjs 里搜该串
                     #    · 源码有、产物无 → 产物过期，重跑 npm run build
                     #    · 源码也无     → 契约漂移，改源码而不是改校验脚本

十、卸载

dsh plugin --profile web remove @yiyunet/dsh-dingtalk-connector

十一、文档索引

根目录的 README 讲怎么用；docs/ 讲为什么这样做、当时验证了什么。

文档	内容
docs/安装与前置条件.md	★ 最先读这篇：Node / dws / 钉钉侧授权三层依赖全解，含平台矩阵与核验清单
docs/发布与版本管理.md	怎么传上 GitHub、加功能后怎么升版本与发布、发布前检查清单
docs/README.md	文档总索引（按问题找文档）
docs/adr/0001-从手搓REST改为包装dws.md	架构决策记录：为什么废弃 v0.1 的手搓 REST
docs/实测/	逐次真机验证留痕（踩到的坑与确认的行为）
CONTEXT.md	术语表与禁用说法——措辞精度在这里是功能，不是文风
CHANGELOG.md	变更记录（含 v0.1 → v0.2 架构反转留痕）
THIRD_PARTY_NOTICES.md	第三方组件与商标声明
README.en.md	English

十二、检查与安装更新

# 查看当前版本
npm view @yiyunet/dsh-dingtalk-connector version

# 升级插件
dsh plugin --profile web add @yiyunet/dsh-dingtalk-connector@latest
dsh plugin --profile web remove @yiyunet/dsh-dingtalk-connector   # 卸载

# 顺带升级本插件的外部依赖 dws（它是独立包，不会随插件一起升）
npm i -g dingtalk-workspace-cli@latest
dws --version

注意：dws 是本插件的外部前置依赖，不由插件管理。插件版本没变但行为异常时，先查 dws --version——很可能是 dws 升级带来了命令面变化。

升级后跑一次自检确认：

dingtalk_aitable_diagnose

十三、联系方式

问题反馈 / 功能建议：优先走 GitHub Issues
安全相关：请勿公开提 issue —— 本插件涉及钉钉凭证与组织数据访问，详见「八、安全与边界」

十四、贡献者 ✨

感谢每一位帮助本项目成长的贡献者！

本项目采用 All Contributors 规范，认可代码、文档、测试、问题反馈、想法和其他形式的贡献。

贡献类型说明： 💻 代码 · 📖 文档 · ⚠️ 测试 · 🚇 基础设施 · 🌍 翻译 · 🤔 想法与规划。

贡献名单由 .all-contributorsrc 管理。

十五、许可与非官方声明

非官方：本插件是非官方社区集成，与钉钉（DingTalk）、DeepSeek 无隶属或背书关系。
外部依赖：dws（dingtalk-workspace-cli）为钉钉官方发布，采用 Apache-2.0，版权归其作者所有。详见 THIRD_PARTY_NOTICES.md。

yiyunet/dsh-dingtalk-connector

简介

界面

能力一览

首屏必读三条

一、为什么从"手搓 REST"改成"包装 dws"

二、前置条件（钉钉侧 + 本机侧）

1. 安装 dws（本机）

2. 授权（二选一）

3. 开通权限（极易漏，漏了必 403）

三、安装插件

四、配置（cordis.patch.yml）

关于 dwsEntry（Windows 上的安全要点）

五、十个工具

五之二、设置面板「钉钉文档」

面板做三件事

工程形态

⚠️ 关键架构约束：connection 必须走 scoped 注入，绝不能写进 inject

RPC 方法（面板可调）

多账号：扫码绑定 / 移除接入（已实现）

⚠️ 两点必须知道的事实（实测，避免误判）

⛔ 已知阻塞：组织未开启 CLI 个人数据访问

五之三、工作流（扫描 → 勾选 → 定时）

六、标准工作流（官方文档规定，照做即可）

cells 读写格式速查（官方）

七、排错（错误信号 → 下一步）

八、安全与边界

九、开发

⚠️ lib/ 不在版本库里 —— 删了、重置了、重装后都要重建

lib/ 的形态（构建产物布局）

为什么匹配产物时要"解转义"

发布契约断言（npm run verify）

构建/校验报错时的排查顺序

十、卸载

十一、文档索引

十二、检查与安装更新

十三、联系方式

十四、贡献者 ✨

十五、许可与非官方声明

Community comments

yiyunet/dsh-dingtalk-connector

简介

界面

能力一览

首屏必读三条

一、为什么从"手搓 REST"改成"包装 dws"

二、前置条件（钉钉侧 + 本机侧）

1. 安装 dws（本机）

2. 授权（二选一）

3. 开通权限（极易漏，漏了必 403）

三、安装插件

四、配置（cordis.patch.yml）

关于 dwsEntry（Windows 上的安全要点）

五、十个工具

五之二、设置面板「钉钉文档」

面板做三件事

工程形态

⚠️ 关键架构约束：connection 必须走 scoped 注入，绝不能写进 inject

RPC 方法（面板可调）

多账号：扫码绑定 / 移除接入（已实现）

⚠️ 两点必须知道的事实（实测，避免误判）

⛔ 已知阻塞：组织未开启 CLI 个人数据访问

五之三、工作流（扫描 → 勾选 → 定时）

六、标准工作流（官方文档规定，照做即可）

cells 读写格式速查（官方）

七、排错（错误信号 → 下一步）

八、安全与边界

九、开发

⚠️ lib/ 不在版本库里 —— 删了、重置了、重装后都要重建

lib/ 的形态（构建产物布局）

为什么匹配产物时要"解转义"

发布契约断言（npm run verify）

构建/校验报错时的排查顺序

十、卸载

十一、文档索引

十二、检查与安装更新

十三、联系方式

十四、贡献者 ✨

十五、许可与非官方声明

Community comments

四、配置（`cordis.patch.yml`）

关于 `dwsEntry`（Windows 上的安全要点）

⚠️ 关键架构约束：`connection` 必须走 scoped 注入，绝不能写进 `inject`

⚠️ `lib/` 不在版本库里 —— 删了、重置了、重装后都要重建

`lib/` 的形态（构建产物布局）

发布契约断言（`npm run verify`）

四、配置（`cordis.patch.yml`）

关于 `dwsEntry`（Windows 上的安全要点）

⚠️ 关键架构约束：`connection` 必须走 scoped 注入，绝不能写进 `inject`

⚠️ `lib/` 不在版本库里 —— 删了、重置了、重装后都要重建

`lib/` 的形态（构建产物布局）

发布契约断言（`npm run verify`）