dsh-plugin-yuque

语雀（Yuque）OpenAPI 工具插件 for DeepSeek Harness (DSH)

在 DSH 中直接调用语雀 API，实现文档的查询、创建、更新、删除和搜索。

功能

封装语雀 OpenAPI 为 9 个 DSH 工具（Tool），Agent 可在对话中自然调用：

工具名	功能	对应 API
yuque_get_user	获取当前用户（验证 Token）	GET /user
yuque_list_repos	列出知识库	GET /repos
yuque_get_repo	获取知识库详情	GET /repos/:namespace
yuque_list_docs	列出文档	GET /repos/:namespace/docs
yuque_get_doc	获取文档正文	GET /repos/:namespace/docs/:slug
yuque_create_doc	创建文档	POST /repos/:namespace/docs
yuque_update_doc	更新文档	PUT /repos/:namespace/docs/:id
yuque_delete_doc	删除文档	DELETE /repos/:namespace/docs/:id
yuque_search	搜索语雀内容	GET /search

环境要求

• Node.js: 开发编译 ≥ 18，DSH 运行时 ≥ 22.19
• 包管理器: npm / pnpm 均可

安装

方式一：从本地目录安装（开发中）

dsh plugin --profile yuque add /path/to/dsh-plugin-yuque

方式二：npm 发布后安装

dsh plugin --profile yuque add dsh-plugin-yuque

配置

安装后，在 DSH profile 的 cordis.patch.yml 中配置 Token：

- insert:
    - id: yuque
      name: dsh-plugin-yuque
      config:
        token: "你的语雀Token"
        baseUrl: "https://www.yuque.com/api/v2"  # 可选，私有部署时修改
        timeoutMs: 15000                            # 可选

获取 Token

1. 登录语雀
2. 访问 https://www.yuque.com/settings/tokens
3. 点击「创建新的 Token」，勾选读取权限（需要写操作时勾选写入）
4. 复制生成的 Token（只显示一次）

使用

启动 DSH 后，Agent 可以自然语言调用工具：

用户：帮我查一下我语雀里有哪些知识库
Agent：[调用 yuque_list_repos] → 返回知识库列表

用户：在「技术笔记」知识库里创建一篇关于 Spring Boot 404 错误排查的文档
Agent：[调用 yuque_create_doc] → 创建成功

开发

项目结构

dsh-plugin-yuque/
├── src/
│   ├── index.ts          # 插件入口（name/inject/Config/apply）
│   ├── client.ts         # 语雀 API 客户端（HTTP 封装）
│   ├── types.ts          # 类型定义
│   └── tools/
│       ├── user.ts       # yuque_get_user
│       ├── repo.ts       # yuque_list_repos / yuque_get_repo
│       ├── doc.ts        # 文档 CRUD（5个工具）
│       ├── search.ts     # yuque_search
│       └── index.ts      # 聚合导出
├── test/
│   ├── helpers.ts        # 测试辅助（mock fetch / mock ctx）
│   ├── client.test.ts    # YuqueClient 单元测试
│   └── plugin.test.ts    # 插件注册测试
├── scripts/
│   ├── integration-test.mjs  # 真实 API 集成测试
│   └── smoke-test.mjs        # 构建产物冒烟测试
├── cordis.patch.yml      # DSH bundle 配置
├── package.json
├── tsconfig.json
└── vitest.config.ts

安装依赖

npm install

注意: @deepseek-ai/dsh-tools 必须使用 next tag 版本。 npm latest tag 指向过时的 0.0.1-rc.1（不可用）。 本项目的 package.json 已正确锁定。

构建

npm run build       # tsc 编译到 dist/
npm run dev         # 监听模式编译
npm run typecheck   # 仅类型检查

本地调试（挂载到 DSH）

在 DSH 源码仓库中创建开发用 patch 文件：

# scratch-yuque/cordis.yml
- insert:
    - id: yuque
      name: '/absolute/path/to/dsh-plugin-yuque/src/index.ts'
      config:
        token: '你的语雀Token'

启动：

pnpm dsh web --patch ./scratch-yuque/cordis.yml
# 打开 http://127.0.0.1:3080

测试

本项目提供四层测试保障：

第一层：单元测试（Vitest）

测试 YuqueClient 的 HTTP 封装逻辑和插件工具注册，使用 mock fetch，不需要网络和 Token。

npm test                  # 运行所有单元测试
npm run test:watch        # 监听模式
npm run test:coverage     # 覆盖率报告

覆盖范围：

• client.test.ts: 构造函数校验、request 方法（鉴权头/序列化/错误处理/超时/非JSON响应）、User/Repo/Doc/Search 各 API 的 URL 和 method 正确性
• plugin.test.ts: 插件元信息导出、Config Schema 校验、9个工具注册验证、工具命名规范、必填参数校验

第二层：冒烟测试（构建产物验证）

验证 dist/ 构建产物可以被正确加载，插件元信息正确，apply() 能注册预期数量的工具。基于 Vitest 运行（mock 掉 dsh-tools 的深层依赖链），不需要真实 DSH 运行时和 Token，适合 CI 快速验证。

npm run build && npm run smoke

检查项：

• dist/index.js 存在且可导入
• 导出 name/inject/apply/Config
• Config Schema 接受合法配置、拒绝空 token
• apply() 注册恰好 9 个工具
• 所有工具名以 yuque_ 开头
• 每个工具都有 description 和 execute 函数

第三层：集成测试（真实 API）

调用真实的语雀 OpenAPI，验证端到端功能。需要 YUQUE_TOKEN 和网络。

# 设置 Token
export YUQUE_TOKEN=你的Token    # Linux/macOS
# $env:YUQUE_TOKEN="你的Token"  # PowerShell

# 运行全部测试（含写操作：创建→更新→删除临时文档）
npm run test:integration

# 只跑只读测试
node scripts/integration-test.mjs --skip-write

# 指定测试用的知识库
node scripts/integration-test.mjs --namespace=你的用户名/知识库slug

测试流程：

1. 只读：getCurrentUser → getUser → listRepos → getRepo → listDocs → getDoc → getToc → search
2. 写操作：createDoc（创建临时文档）→ updateDoc（更新标题+正文）→ deleteDoc（清理）
3. 输出每项通过/失败状态和汇总

第四层：DSH 加载验证（端到端）

在真实 DSH 环境中验证插件可以被加载并被模型调用。需要 Node.js ≥ 22.19 和 DSH 源码。

# 1. 克隆 DSH 源码
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

# 2. 创建 patch 文件（指向你的插件源码）
cat > scratch-yuque/cordis.yml << EOF
- insert:
    - id: yuque
      name: '/absolute/path/to/dsh-plugin-yuque/src/index.ts'
      config:
        token: '你的语雀Token'
EOF

# 3. 查看配置树（验证插件被加载）
pnpm dsh web --patch ./scratch-yuque/cordis.yml --dump-config

# 4. 启动 Web UI 实际调用
pnpm dsh web --patch ./scratch-yuque/cordis.yml
# 在 http://127.0.0.1:3080 中输入：用 yuque_get_user 验证我的 token

测试矩阵总结

测试层	命令	需要 Token	需要网络	需要 DSH	速度
单元测试	npm test	❌	❌	❌	快
冒烟测试	npm run smoke	❌	❌	❌	快
集成测试	npm run test:integration	✅	✅	❌	中
DSH 加载验证	手动	✅	✅	✅	慢

发布

# 1. 构建
npm run build

# 2. 冒烟测试
npm run smoke

# 3. 发布到 npm
npm publish

# 4. 给 GitHub 仓库添加 dsh-plugin topic（方便社区发现）

用户安装：

dsh plugin add dsh-plugin-yuque

技术栈

• TypeScript - 类型安全
• Cordis - DSH 插件内核（@deepseek-ai/cordis）
• DSH Tools - 工具定义 DSL（@deepseek-ai/dsh-tools）
• Schemastery - 配置 Schema 校验（@deepseek-ai/schemastery）
• Vitest - 单元测试框架
• 原生 fetch - HTTP 请求（Node 18+ 内置，无需额外依赖）

License

MIT