woodenfish-bot

开发检查

• npm run typecheck：检查全部源码和测试文件的 TypeScript 类型，无需本地测试凭据。
• npm run lint:check：检查 ESLint；npm run lint 自动修复现有 JS/TS 文件可修复的问题。
• npm test -- --runInBand：运行离线单元测试，覆盖 v1/v2 客户端、群管理、消息、公共工具及 WebSocket，不调用真实 QQ 接口。
• npm run build：生成 lib/index.js、es/index.js 和 typings/index.d.ts。
• npm run test:coverage -- --runInBand：额外生成覆盖率报告，沿用现有 100% 覆盖率门槛。

旧 v1 接口测试通过 npm run test:integration 单独运行。它们会调用真实 QQ 接口，包含发送消息、修改权限以及创建和删除频道等操作。运行前，将 test/api-config.example.ts 复制到 test-config/api-config.ts，填写专用测试机器人的凭据和测试目标 ID。test-config 已被 Git 忽略，缺少配置或凭据时集成测试会明确报错。

QQ 群管理接口

通过 createOpenAPIV2(config).groupApi 调用，返回 RestyResponse<T>，业务结果位于 response.data。

• 群信息：getGroupInfo、getGroupBotState。
• 入群申请：getGroupJoinRequests、approveGroupJoinRequest。
• 群禁言：getGroupRestrictChatSetting、setGroupRestrictChatSetting。
• 入群自动审批策略：getGroupJoinApprovalStrategies、createGroupJoinApprovalStrategy、updateGroupJoinApprovalStrategy、deleteGroupJoinApprovalStrategy、executeGroupJoinApprovalStrategy、updateGroupJoinApprovalStrategyWhitelist。
• 群成员管理：getGroupMembers、getGroupMember、batchRemoveGroupMembers、getGroupMemberBlacklist、updateGroupMemberBlacklist。

import { createOpenAPIV2 } from 'woodenfish-bot';

const { groupApi } = createOpenAPIV2({ appID: '你的 AppID', clientSecret: '你的 AppSecret' });
const groupOpenid = '群 OpenID';
const memberOpenid = '成员 OpenID';

// 成员列表每页最多 30 人，仅支持 cursor；next_cursor 为空表示末页。
const firstPage = await groupApi.getGroupMembers(groupOpenid);
if (firstPage.data.next_cursor) {
  const nextPage = await groupApi.getGroupMembers(groupOpenid, { cursor: firstPage.data.next_cursor });
}
const member = await groupApi.getGroupMember(groupOpenid, memberOpenid);

// 单次最多移除 20 人；可选择同时拉黑，需检查拉黑失败列表。
const removed = await groupApi.batchRemoveGroupMembers(groupOpenid, {
  member_openids: [memberOpenid],
  add_to_member_blacklist: true,
});
console.log(removed.data.add_to_member_blacklist_fail_openids);

// 黑名单查询默认每页 20 人，limit 最大 100。
const blacklist = await groupApi.getGroupMemberBlacklist(groupOpenid, { limit: 100 });

// op 可为 add 或 del，单次最多 20 人；add 时目标用户必须已不在群中。
const updated = await groupApi.updateGroupMemberBlacklist(groupOpenid, {
  op: 'del',
  member_openids: [memberOpenid],
});
console.log(updated.data.fail_openids);

上述方法均支持最后一个可选参数 { timeout: 5000 }，单位为毫秒。列表方法省略分页时，可传 undefined 占位，例如 getGroupMembers(groupOpenid, undefined, { timeout: 5000 })。

群成员管理能力在官方文档中标注为内邀接入，仅白名单机器人可用，未获权限会返回 11253。SDK 保留平台错误和部分失败列表，不会自动重试批量操作或拆分请求。