mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-09-05 18:23:50 +08:00
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.
This commit is contained in:
GitHub
131
agents/dingtalk-workspace/USAGE.md
Normal file
131
agents/dingtalk-workspace/USAGE.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# 使用说明
|
||||
|
||||
把自然语言意图翻译成钉钉官方 CLI（`dws`）的正确调用，并对结果负责。覆盖通讯录、群聊消息、
|
||||
日程会议、待办、审批、考勤、日志、文档、表格、AI 多维表、钉盘、知识库、邮件、AI 听记、DING、
|
||||
实时事件等钉钉产品域。
|
||||
|
||||
**它不是钉钉命令的说明书。** 命令目录由钉钉官方技能与 `dws schema` 提供，随二进制升级而更新。
|
||||
本 Agent 做的是官方技能不覆盖的四件事：
|
||||
|
||||
| 增量 | 说明 |
|
||||
| --- | --- |
|
||||
| **接入** | 钉钉官方 CLI 的 Agent 分发列表里没有 DesireCore，装到 DesireCore 的路径无人覆盖 |
|
||||
| **纪律** | 钉钉 CLI 有 339 个「自己不拦」的写操作（占全部写操作 56%），由本 Agent 把关 |
|
||||
| **编排** | 跨产品工作流；官方 SKILL.md 明写「定时调度由外层工作流负责」 |
|
||||
| **降级** | 没装 / 没授权 / 没权限 / 没开通时如实停下，绝不编造成功 |
|
||||
|
||||
---
|
||||
|
||||
## 装之前必须知道
|
||||
|
||||
本 Agent 依赖一个**由第三方独立分发**的命令行程序。DesireCore 不打包、不分发、不授权、
|
||||
不安装、不代付、不运营该程序及其背后的钉钉产品。凭据与费用由你与钉钉之间的服务条款约束。
|
||||
|
||||
装完本 Agent 还**不能直接用**，必须自行完成下面 5 步。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装钉钉官方 CLI
|
||||
|
||||
```bash
|
||||
npm i -g dingtalk-workspace-cli
|
||||
```
|
||||
|
||||
⚠️ 这一步会顺带往你机器上**其它 AI 编程工具的技能目录**写入钉钉技能
|
||||
（`~/.claude/skills/`、`~/.cursor/skills/` 等，共 80+ 个框架）。这是上游 `dws` 的
|
||||
postinstall 行为，不是 DesireCore 做的。
|
||||
|
||||
### 2. 把官方产品技能装进 DesireCore
|
||||
|
||||
装完 CLI 后技能已解包在 `~/.dws/skills/multi/`，拷进 DesireCore 全局技能目录：
|
||||
|
||||
```bash
|
||||
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. 授权
|
||||
|
||||
```bash
|
||||
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. 自检
|
||||
|
||||
```bash
|
||||
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「钉盘同步怎么用」这类问题即可，它会自己去读对应文档再回答。
|
||||
Reference in New Issue
Block a user