mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-09-05 16:13:53 +08:00

Files

Yige a8361009b9 feat(dingtalk-workspace): add USAGE.md and wire feature docs into skill references (#113 )

## 背景 / Background

`agents/dingtalk-workspace` 条目把 13 篇使用文档放在 `docs/` 目录，但**两侧都读不到**：

- 市场详情页只渲染 `agent.json` 的元数据字段，不扫描条目目录下的 `docs/`
- Agent 自身的上下文只挂载 `persona.md` / `principles.md` / `memory/` /
`skills/`，`docs/` 不在其中

The listing kept 13 usage documents under `docs/`, but nothing consumed
them: the
market detail page only projects `agent.json` metadata, and the agent's
own context
mounts `persona.md` / `principles.md` / `memory/` / `skills/` only.

## 变更 / Changes

配合 DesireCore 主仓库的 `USAGE.md` 平台约定（ADR-143）与既有技能 `references` 机制，分别解决两侧。
Pairs with the new `USAGE.md` platform convention (ADR-143) in the
DesireCore repo.

| 变更 / Change | 说明 / Detail |
| --- | --- |
| 新增 `USAGE.md` | 安装前该知道的内容：第三方 CLI 依赖声明、5
步快速开始、六种审批模式取舍、安全与已知边界。**刻意不含图片**——详情页的 markdown 渲染器会移除普通 `img src` |
| 新增私有技能 `dingtalk-guide` | 只做索引，正文用 `${SKILL_DIR}/references/` 绝对路径指向
13 篇文档，Agent 按需 `Read`。单产品问题（如「钉盘同步怎么用」）可触发查文档再作答，不占每轮上下文 |
| `docs/` → `dingtalk-guide/references/` | 整体移入并拍平。原 12
篇无交叉链接、无图片，移动无需改写正文 |
| `docs/README.md` 拆分 | 安装部分 → `USAGE.md`；界面与审批部分连同两张截图 →
`references/界面与审批.md` |
| `README.md` | 补 `USAGE.md` 约定说明与目录树条目 |
| `manifest.json` | 1.5.0 → 1.5.1（条目内容新增；计数不变，经校验器实跑确认） |

**单一真相源 / Single source of truth**：每篇文档只有一份，归 `dingtalk-guide` 技能所有；
不存在 `docs/` 与 `references/` 两份副本。`dingtalk-onboarding` 与
`dingtalk-workflows`
两个既有技能不变。

## 校验 / Validation

README 记录的 7 条 CI 校验命令全部实跑通过（改动前后各一轮）：

```
scripts/i18n/test_validate_i18n.py                              exit=0
scripts/catalog/test_validate_catalog_metadata.py               exit=0
scripts/catalog/test_collection_generator.py                    exit=0
scripts/catalog/validate_catalog_metadata.py --require-complete  exit=0
scripts/i18n/validate-i18n.py                                   exit=0
scripts/i18n/translate.py --check                               exit=0
scripts/gen-collection-children.py --check                      exit=0
```

`manifest.json#stats` 由 `validate_catalog_metadata` 输出实跑确认（agents=3,
teams=1,
publishableSkills=69），非算术推导，故不变。

## 公开信息边界 / Public information boundary

全树扫描零命中：改动文件、新增路径名、分支名、commit 主题与正文、本 PR 文本均不含
租户/客户/伙伴/个人身份。两张截图已逐张目视复核——仅含 DesireCore 自身界面、Agent 名称与
通用 `dws` 命令，返回结果为空列表，不含组织名或任何组织形态。

Full-tree scan returned zero results. Both screenshots were reviewed
individually:
they show only DesireCore's own UI, the agent name, and generic `dws`
commands.

## 依赖 / Dependency

`USAGE.md` 的详情页渲染依赖 DesireCore 主仓库的配套 PR。在其发布前，本条目的
`USAGE.md` 仍是仓库内可读的普通文件，不影响现有行为。

Detail-page rendering depends on the companion PR in the DesireCore
repository.
Until it ships, `USAGE.md` is simply a readable file in the listing and
changes nothing.

2026-09-04 00:08:53 -04:00

6.1 KiB

Raw Permalink Blame History

使用说明

把自然语言意图翻译成钉钉官方 CLI（dws）的正确调用，并对结果负责。覆盖通讯录、群聊消息、日程会议、待办、审批、考勤、日志、文档、表格、AI 多维表、钉盘、知识库、邮件、AI 听记、DING、实时事件等钉钉产品域。

它不是钉钉命令的说明书。 命令目录由钉钉官方技能与 dws schema 提供，随二进制升级而更新。本 Agent 做的是官方技能不覆盖的四件事：

增量	说明
接入	钉钉官方 CLI 的 Agent 分发列表里没有 DesireCore，装到 DesireCore 的路径无人覆盖
纪律	钉钉 CLI 有 339 个「自己不拦」的写操作（占全部写操作 56%），由本 Agent 把关
编排	跨产品工作流；官方 SKILL.md 明写「定时调度由外层工作流负责」
降级	没装 / 没授权 / 没权限 / 没开通时如实停下，绝不编造成功

装之前必须知道

本 Agent 依赖一个由第三方独立分发的命令行程序。DesireCore 不打包、不分发、不授权、不安装、不代付、不运营该程序及其背后的钉钉产品。凭据与费用由你与钉钉之间的服务条款约束。

装完本 Agent 还不能直接用，必须自行完成下面 5 步。

快速开始

1. 安装钉钉官方 CLI

npm i -g dingtalk-workspace-cli

⚠️ 这一步会顺带往你机器上其它 AI 编程工具的技能目录写入钉钉技能（~/.claude/skills/、~/.cursor/skills/ 等，共 80+ 个框架）。这是上游 dws 的 postinstall 行为，不是 DesireCore 做的。

2. 把官方产品技能装进 DesireCore

装完 CLI 后技能已解包在 ~/.dws/skills/multi/，拷进 DesireCore 全局技能目录：

DC_ROOT="${DESIRECORE_TEST_ROOT:-${DESIRECORE_HOME:-$HOME/.desirecore}}"
mkdir -p "$DC_ROOT/skills"
cp -R ~/.dws/skills/multi/dingtalk-* "$DC_ROOT/skills/"

共 14 个：aisearch aitable calendar chat contact doc drive event mail minutes misc shared todo wiki。

为什么不走市场安装：市场里有 dingtalk-cli 条目，但钉钉官方仓库未公开（HTTP 404），客户端按 git 源拉不到内容。该条目的作用是让你在市场里发现这个能力并看到装法，不是分发通道。

代价：这样装的技能没有 provenance 记录，市场同步视为孤儿——既不自动更新也不自动卸载。 每次 dws upgrade 后要重跑一次上面的拷贝。

3. 授权

dws auth login              # 本机有浏览器
dws auth login --device     # 无浏览器 / SSH / 容器，出设备码

⚠️ 钉钉不支持账号密码登录，也不支持手机验证码、纯应用凭证。只有 OAuth 回环、设备流、 --token、自有应用 OAuth 四种。

授权成功后 access token 约 2 小时、refresh token 约 30 天自动刷新，之后无需再打扰。

4. 把 `dws` 加进命令白名单（强烈建议）

实测每条 dws 命令都会被判高风险并弹审批卡片——18 个测试用例里 34 次 Bash 调用触发了 41 次审批。不加白名单的话你要不停点确认。

点输入框左下角的审批模式胶囊即可切换。六种模式的取舍：

模式	行为	适合
AI 审批（默认）	前台保留 30 秒真人抢先窗口，AI 建议到达即收敛	日常，但需要配好审批 chat 模型
完全 AI 审批	AI 建议到达立即决策	无人值守
仅 AI 建议	AI 只提供参考，永不自动决策，无截止时间等待真人	高风险场景
每次确认	每次执行命令都要你审批	最保守
白名单	仅白名单中的命令可自动执行	推荐：把 `dws` 加进去
外部工具审批	交给外部系统裁决	有审批中台时

⚠️ 默认的「AI 审批」需要一个可用的审批 chat 模型。 没配的话所有命令会被 fail-closed 拦掉，报「AI 审批后端不可用，命令未执行」——连本 Agent 自己写计划文件都会被拦。要么去资源管理面板 → 算力配一个 chat 模型，要么换成「白名单」或「每次确认」。

5. 自检

dws doctor

四项：登录状态 / 钥匙串 / 网络连通性 / 版本更新。

安全边界

本 Agent 继承钉钉官方的执行契约，并补了 DesireCore 侧的一层：

只走 dws，不用 curl、不自拼 HTTP
不编造标识符——userId / docId / baseId 一律从命令返回中提取
写操作先确认，判据是 effect == destructive || risk == high || confirmation == user_required 三元组兜底（不能只看 confirmation 字段：1256 个工具里有 339 个是 dws 自己不拦的 silent-write）
单次批量 ≤ 30 条
多候选禁止默认取第一个；多组织时解析、读取、执行必须用同一个 profile
退出码不等于成功——只有 data.complete=true 才能说「全部」，响应里缺少集合不能当空结果
禁止轮询消息历史或审批列表，实时需求走长连接

已知边界

限制	说明
视频会议	CLI 无入口。会前（排日程订会议室）与会后（纪要/逐字稿/行动项）可用，会中控制需在钉钉客户端操作
消息搜索	需要消息搜索权益，未开通时返回 `SearchRightsDenied`。其余 chat 能力（发消息、群管理、机器人）不受影响
组织权限	能力覆盖取决于 OAuth 授权范围与你所在组织开通的产品，本 Agent 会在受限时如实说明

更详细的功能文档

按产品域的能力覆盖、边界与权益门槛，随 Agent 一起安装在私有技能 dingtalk-guide 的 references/ 目录下（通讯录、群聊、日程、待办审批、文档表格、钉盘知识库、邮件、AI 听记、考勤日志、实时事件、跨产品工作流、界面与审批、故障排查共 13 篇）。装好后直接问本 Agent「钉盘同步怎么用」这类问题即可，它会自己去读对应文档再回答。

6.1 KiB Raw Permalink Blame History Unescape Escape