功能代码编写帮助

一、功能是什么

后台「功能管理」里的一项 = 一个功能。一个功能可以同时用两种方式触发，也可以只用其中一种：

两种触发方式可以同时配置（双触发）：一个功能既是菜单按钮、又是文本指令，共用同一段功能代码。 只做文本指令、不想占用菜单位置时，取消勾选「在菜单中显示」（show_in_menu: false）， 这样不必填 data，功能仍可用指令触发。

每个功能还可以写一段 Python 代码（code 字段），触发时执行。触发后的查找顺序：

1. 若该功能有代码且勾选了「覆盖内置功能」（override: true） → 执行代码并结束， 内置按钮 / 内置指令都不再执行；
2. 否则先看这次触发是否命中内置逻辑：按钮 data 命中 @pm.button、 指令名命中 @pm.command → 用内置逻辑；
3. 没有命中内置逻辑时，该功能有代码就执行这段代码；
4. 都没有：按钮只记一条 debug 日志；指令不产生动作。

也就是说：不勾选「覆盖内置功能」时，功能代码不会覆盖内置按钮/指令；要接管 menu:home、menu:sign、内置「绑定」指令这类已有功能，勾上 「覆盖内置功能」即可，不用改 plugins/ 源码。适合做「几行代码就能搞定」的小功能： 回一句提示、发张卡片、调你自己的服务器接口、记录点击次数，或者替换某个内置功能的行为。 代码存在 data/menu.json 的菜单项里，保存即生效。

两个典型场景

场景 A：接管内置功能（勾选「覆盖内置功能」） —— 把「签到」换成自己服务器的签到：

async def run(ctx, bot):
    result = await bot.api_client.call(bot.api_path("sign", "/api/sign"), method="POST")
    await ctx.reply(ServerAPI.to_text(result))

场景 B：给新功能写代码（不勾选） —— 新增一个按钮 my:hello（或文本指令 hello），因为没有同名内置逻辑，不勾选也会走这段代码：

async def run(ctx, bot):
    await ctx.reply("你好，这是自定义功能回复")

内置功能的 data 与指令名对照表

下面这些 data / 指令名在 plugins/ 里有内置逻辑。 不勾选「覆盖内置功能」时，按钮点击与指令都一律走内置逻辑；勾选后才能用功能代码接管。 「内置指令名」为空表示该功能只有按钮、没有注册文本指令（可在功能里另填 command 给它加一个）。

另有不带按钮的内置指令：菜单（别名 menu、帮助菜单）、 解绑。后台功能管理页会在 data 输入框旁显示「内置：签到」这类小标签，提示这个 data 有内置逻辑。

二、代码契约

必须定义一个名为 run 的入口函数，必须是 async 函数，参数固定两个 （名字可以改，但顺序不能变）：

async def run(ctx, bot):
    await ctx.reply("你好，这是自定义功能回复")

触发方式不同，参数来源也不同：

• 菜单按钮触发：ctx.args 为空（按钮没有参数）。建议用 getattr(ctx, "args", "") 兜底，同一段代码两种触发都能用。
• 文本指令触发：用户发「指令名 参数」时，指令名之后的剩余文本（去掉首尾空白） 放在 ctx.args 里。例如用户在聊天框发「天气 北京」，ctx.args 就是 "北京"；只发「天气」则是空字符串。指令名参数（中间不加空格）也能匹配。

功能项上的可选字段：label（显示文字）、desc（描述）、data （按钮回调 key）、link（链接项，必须 https）、command / aliases （文本指令名与别名）、show_in_menu（布尔，为 false 时不在菜单卡片显示，仍可用指令触发）、 code（这段代码）与 override（布尔，对应「覆盖内置功能」， 仅在同时有 code 时有效）。command 与 aliases 合计的指令名 在同一份功能里不能与其它功能重复（后台保存时会报错指出重复的名字）。

• ctx —— 本次触发的上下文，类型是 bot/context.py 的 Context （群里的按钮点击拿到的是它的子类 InteractionContext）。发消息、判断群聊/私聊、 取用户 openid、读指令参数都靠它。
• bot —— 机器人实例（bot/core.py 的 QQBot）， 可以调服务器接口、读写 data 数据、看配置。

除这两个参数外，代码里还能直接用下面这些名字（已经预置好，不用 import）：

bind 可用函数（绑定功能组）

菜单按钮、文本指令和功能代码共用同一份绑定实现，不用自己拼流程：

mailer 可用成员

ctx 的常用成员

bot 的常用成员

三、完整示例

示例 1：回复一段文本

async def run(ctx, bot):
    await ctx.reply("你好，这是自定义功能回复")

示例 2：回复带按钮的卡片

async def run(ctx, bot):
    card = Card("自定义功能卡片\r点下面的按钮可以返回主菜单")
    card.add_row(Button("返回主菜单", "menu:home"))
    await ctx.reply_card(card)

卡片限制：整张卡片最多 5 行按钮，每行最多 5 个。行数超了会报错， 用户会收到「功能执行失败」。

示例 3：调用服务器接口并把返回发给用户

async def run(ctx, bot):
    # 接口名/路径来自 config.yaml 的 server_api.endpoints（可在「基本配置」里维护）
    result = await bot.api_client.call(bot.api_path("online", "/api/online"))
    card = Card(ServerAPI.to_text(result))
    card.add_row(Button("返回主菜单", "menu:home"))
    await ctx.reply_card(card)

ServerAPI.to_text() 会优先取返回 JSON 里的 text/msg/message/content 字段， 取不到就把 JSON 格式化成代码块；接口没返回时给一句「服务器接口暂时无法访问」。

示例 4：读取/写入 data 里的自定义数据

async def run(ctx, bot):
    key = "clicks:" + (ctx.user_openid or "")

    def _apply(data):
        data[key] = int(data.get(key, 0)) + 1
        return data[key]

    # storage.update 在文件锁内"重新读盘-改-写"，跨进程安全
    count = bot.storage.update(_apply)
    await ctx.reply("本功能你已点击 " + str(count) + " 次")

数据存在 data/store.json 的顶层。放管理员列表/群设置以外的自定义键没问题； 不要在 update() 之外直接改 bot.storage.data 后 save()， 那会用旧快照整份覆盖机器人刚写入的数据。

示例 5：改「绑定」按钮的回复文案

内置的绑定说明卡刻意只有一句话（BIND_PROMPT，见 plugins/account.py）。 想自定义回复内容，用功能代码接管绑定功能（勾选「覆盖内置功能」）：

async def run(ctx, bot):
    bind.open_bind_lock(bot, ctx.user_openid)   # 必须先开锁，否则用户直接发账号不会被受理
    card = Card("绑定遇简助手\r请直接发送你的遇简APP账号（QQ号或邮箱）")
    card.add_row(Button("返回主菜单", "menu:home"))
    await ctx.reply_card(card)

    # 想在卡片之外再补一句提示，直接回消息：
    # await ctx.reply("绑定后即可签到、查询订单")

texts.save() 只接受已注册的 key：menu_title、 welcome_bot、welcome_member。

示例 6：改绑定流程代码（用 bind.* 组合）

下面是一个「发码」新指令：跳过开锁，直接把验证码发到用户指定的邮箱。数据 + 指令配置如下， 功能代码只用了 bind.send_code：

async def run(ctx, bot):
    # 文本指令触发时 ctx.args 是指令名之后的文本；按钮触发时为空
    email = (getattr(ctx, "args", "") or "").strip()
    if not email:
        await ctx.reply("用法：发码 你的邮箱")
        return
    # bind.send_code 会校验邮箱、发验证码并开验证锁，用户随后直接发验证码即可
    await bind.send_code(bot, ctx, email)

其它常见组合（伪代码，按需取用）：

# 查看绑定状态后再决定下一步
if bind.is_bound(bot, ctx.user_openid):
    email = bind.bound_email(bot, ctx.user_openid)
    await ctx.reply("你已绑定：" + str(email))
else:
    await bind.start_bind(bot, ctx)

# 绑定锁 / 验证锁内收到消息时，交给绑定流程处理（读 ctx.content）
await bind.handle_account(bot, ctx)   # 当账号处理
await bind.handle_code(bot, ctx)      # 当验证码处理

# 把「验证 验证码」的语义拿来用（code 缺省取 ctx.args）
ok = await bind.verify_code(bot, ctx)

示例 6 的菜单项建议：不勾选「在菜单中显示」（只做指令）、command 填 发码、aliases 填 sendcode, 重新发码（逗号或空格分隔）。

示例 7：文本指令 + 按钮双触发的完整功能

功能配置：显示文字「天气」、data my:weather、 command 天气、aliases tq, 查天气， 勾选「在菜单中显示」。

async def run(ctx, bot):
    # 菜单按钮点击：ctx.args 为空 → 用默认城市；文本指令「天气 北京」：ctx.args 为 "北京"
    city = (getattr(ctx, "args", "") or "").strip() or "北京"
    result = await bot.api_client.call(bot.api_path("weather", "/api/weather"),
                                       params={"city": city})
    card = Card(f"{city} 天气\r{ServerAPI.to_text(result)}")
    card.add_row(Button("返回主菜单", "menu:home"))
    await ctx.reply_card(card)

这样用户既能点菜单里的「天气」按钮，也能直接发「天气 上海」查指定城市， 两种触发共用同一段代码。

示例 8：接管内置按钮或内置指令（勾选「覆盖内置功能」）

async def run(ctx, bot):
    # 把内置的「签到」换成走自己服务器的签到（按钮 menu:sign 与指令「签到」都会走这里）。
    # 必须勾选「覆盖内置功能」，否则点击/发指令仍走内置签到逻辑。
    result = await bot.api_client.call(bot.api_path("sign", "/api/sign"), method="POST")
    await ctx.reply(ServerAPI.to_text(result))

四、常见错误与排查

错误码对照

日志在哪看

• 后台「状态日志」标签页：直接看机器人运行日志（botpy.log）， 功能代码里的 log.info(...) 和出错的完整堆栈都在这里。
• 服务器上：项目目录的 botpy.log（会按天轮转成 botpy.log.日期）， 或 journalctl -u qqbot-webadmin（后台自身日志）。

五、安全与限制

• 15 秒超时：执行超过 15 秒会被强制中断，用户收到超时提示，机器人不受影响。
• 不要阻塞事件循环：机器人是单事件循环，代码里写 time.sleep()、 同步网络请求、大循环会卡住所有群的消息。要等待用 await asyncio.sleep(...)， 要请求接口用 await bot.api_client.call(...)。
• 异常不回显给用户：出错只写日志，用户只看到固定的 E2001/E2002/E2003 文案， 避免把接口地址、参数泄露到群里。
• 不要在这里写常驻任务（while True、定时轮询）：触发是一次性的， 常驻逻辑应该写成 plugins/ 里的插件。
• 改动即时生效：每次触发都会读取当前 data/menu.json 里的代码， 不存在「启动时缓存」；保存功能后触发一次就是新逻辑。
• 接管内置功能有风险：勾选「覆盖内置功能」后原来 plugins/ 里的逻辑 彻底不执行（例如接管 menu:home 会让「返回主菜单」失效）。 改坏了删掉代码或取消勾选即可恢复。
• 保存前自动备份：上一版菜单会覆盖式备份到 data/menu.json.bak。

六、相关接口与文件