# TeamSpeak chat-command permission control — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Gate a fixed set of "admin" TeamSpeak chat commands (`stop`, `clear`, `remove`, `move`, `vol`, `mode`) behind configured TS server-group IDs, opt-in and backward-compatible, configurable from the WebUI and `config.json`.

**Architecture:** A pure helper `canRunCommand(name, invokerGroups, adminGroups)` decides allow/deny. The chat handler `handleTextMessage` (NOT the WebUI-shared `executeCommand`) consults it before executing, performs a best-effort group lookup when the sender's groups weren't delivered with the event, fails closed, and replies on deny. The privileged groups live in the already-declared `config.adminGroups`, surfaced through the existing `GET/POST /api/bot/settings` endpoints and an admin-only Settings.vue section.

**Tech Stack:** Node 20, TypeScript (ESM), Express 5, Vitest + supertest (backend), Vue 3 + `vue-tsc` (frontend), `@honeybbq/teamspeak-client`.

## Global Constraints

- **ESM import specifiers:** every relative import ends in `.js` even in `.ts` files (e.g. `import { canRunCommand } from "./commands.js"`).
- **Admin command set (exact, single source of truth):** `stop`, `clear`, `remove`, `move`, `vol`, `mode`. Everything else is public. (Note: `follow` is intentionally NOT admin — it becomes public.)
- **Enforcement is opt-in / backward-compatible:** `config.adminGroups === []` (the default) ⇒ no enforcement; admin commands stay open to everyone exactly as today.
- **Fail closed:** an admin command, with enforcement on, whose sender groups cannot be determined (even after fallback) is **denied**.
- **Group-id normalization:** `invokerGroups` are strings, `adminGroups` are numbers — compare as the same type so `"6"` matches `6`.
- **Denial reply text (exact):** `⛔ 需要管理员权限（该命令仅限管理员服务器组）`.
- **`adminGroups` validation:** array of non-negative integers; filter out everything else; ignore a non-array value entirely.
- **Live config:** `BotInstance` shares the same `config` object the router mutates; the gate reads `this.config.adminGroups` live (no restart, no propagation call).
- **Per-task tests:** run `npx vitest run <file>` (targets `.ts` directly). Before any full `npm test`, run `rm -rf dist` first — a stale untracked `dist/` makes vitest double-run compiled `.test.js` copies (known environment quirk). The repo path contains spaces (`/c/Users/saopig1/Music/teamspeak music bot`) — quote it.
- **Frontend type-check:** `cd web && npx vue-tsc --noEmit` (must be clean).
- **TDD + frequent commits:** every task is red→green→commit. Keep project `tsc`/`vitest` green after each task.

---

### Task 1: `canRunCommand` helper + admin-set as single source of truth

**Files:**
- Modify: `src/bot/commands.ts` (lines 8-16 sets; line 59-61 `isAdminCommand`)
- Test: `src/bot/commands.test.ts` (append a new `describe` block)

**Interfaces:**
- Consumes: nothing from other tasks.
- Produces:
  - `export const ADMIN_COMMANDS: Set<string>` = `{stop, clear, remove, move, vol, mode}`
  - `export function isAdminCommand(commandName: string): boolean` (unchanged signature)
  - `export function canRunCommand(commandName: string, invokerGroups: readonly (string | number)[], adminGroups: readonly number[]): boolean` — consumed by Task 3.

- [ ] **Step 1: Write the failing tests**

Append to `src/bot/commands.test.ts`:

```ts
import { canRunCommand, isAdminCommand } from "./commands.js";

describe("isAdminCommand classification", () => {
  it("treats stop/clear/remove/move/vol/mode as admin", () => {
    for (const c of ["stop", "clear", "remove", "move", "vol", "mode"]) {
      expect(isAdminCommand(c)).toBe(true);
    }
  });
  it("treats follow and play as NOT admin", () => {
    expect(isAdminCommand("follow")).toBe(false);
    expect(isAdminCommand("play")).toBe(false);
  });
});

describe("canRunCommand", () => {
  it("allows any public command regardless of groups", () => {
    expect(canRunCommand("play", [], [6])).toBe(true);
    expect(canRunCommand("follow", [], [6])).toBe(true);
  });
  it("allows admin command when enforcement is off (empty adminGroups)", () => {
    expect(canRunCommand("stop", [], [])).toBe(true);
  });
  it("allows admin command when an invoker group matches (string vs number)", () => {
    expect(canRunCommand("stop", ["6"], [6])).toBe(true);
    expect(canRunCommand("stop", [6], [6])).toBe(true);
    expect(canRunCommand("vol", ["8", "6"], [6])).toBe(true);
  });
  it("denies admin command when no invoker group matches", () => {
    expect(canRunCommand("stop", ["8"], [6])).toBe(false);
  });
  it("denies admin command when invoker has no groups and enforcement is on", () => {
    expect(canRunCommand("clear", [], [6])).toBe(false);
  });
});
```

- [ ] **Step 2: Run the tests to verify they fail**

Run: `npx vitest run "src/bot/commands.test.ts"`
Expected: FAIL — `canRunCommand` is not exported / not a function.

- [ ] **Step 3: Implement the helper and tighten the admin set**

In `src/bot/commands.ts`, delete the dead `PUBLIC_COMMANDS` export (nothing imports it; the admin set is the sole source of truth), set `ADMIN_COMMANDS` to the exact spec set (drop `follow`), and add `canRunCommand`. The file becomes:

```ts
export interface ParsedCommand {
  name: string;
  args: string;
  rawArgs: string[];
  flags: Set<string>;
}

/**
 * The fixed set of "admin" chat commands. This is the SINGLE source of truth
 * for which commands the permission gate restricts; reclassifying a command is
 * a one-line edit here. Everything not in this set is public.
 */
export const ADMIN_COMMANDS = new Set([
  "stop", "clear", "remove", "move", "vol", "mode",
]);

export function parseCommand(
  message: string,
  prefix: string,
  aliases: Record<string, string> = {},
): ParsedCommand | null {
  const trimmed = message.trim();
  if (!trimmed.startsWith(prefix)) return null;

  const withoutPrefix = trimmed.slice(prefix.length);
  if (!withoutPrefix) return null;

  const parts = withoutPrefix.split(/\s+/);
  let name = parts[0].toLowerCase();

  if (aliases[name]) {
    name = aliases[name];
  }

  const flags = new Set<string>();
  const argParts: string[] = [];

  for (let i = 1; i < parts.length; i++) {
    if (
      parts[i].startsWith("-") &&
      parts[i].length === 2 &&
      /[a-zA-Z]/.test(parts[i][1])
    ) {
      flags.add(parts[i][1].toLowerCase());
    } else {
      argParts.push(parts[i]);
    }
  }

  return {
    name,
    args: argParts.join(" "),
    rawArgs: argParts,
    flags,
  };
}

export function isAdminCommand(commandName: string): boolean {
  return ADMIN_COMMANDS.has(commandName);
}

/**
 * Decide whether a chat command may run, given the invoker's TS server groups
 * and the configured admin groups. Pure + synchronous so it is trivially unit
 * tested and reused by the async gate in BotInstance.
 *
 * Allowed iff: (1) it is a public command, OR (2) enforcement is off
 * (adminGroups empty), OR (3) some invoker group is in adminGroups.
 * invokerGroups (strings from TS) and adminGroups (numbers) are normalized to
 * strings before comparison so "6" matches 6.
 */
export function canRunCommand(
  commandName: string,
  invokerGroups: readonly (string | number)[],
  adminGroups: readonly number[],
): boolean {
  if (!isAdminCommand(commandName)) return true;
  if (adminGroups.length === 0) return true;
  const admin = new Set(adminGroups.map((g) => String(g)));
  return invokerGroups.some((g) => admin.has(String(g)));
}
```

- [ ] **Step 4: Run the tests to verify they pass**

Run: `npx vitest run "src/bot/commands.test.ts"`
Expected: PASS (parser tests + the new classification/canRunCommand tests).

- [ ] **Step 5: Verify nothing else imported the deleted symbol**

Run: `grep -rn "PUBLIC_COMMANDS" src/`
Expected: no matches (confirms the deletion is safe).

- [ ] **Step 6: Commit**

```bash
git add "src/bot/commands.ts" "src/bot/commands.test.ts"
git commit -m "feat(commands): add canRunCommand gate helper + admin-set source of truth"
```

---

### Task 2: Surface `invokerGroups` on `TS3TextMessage`

**Files:**
- Modify: `src/ts-protocol/client.ts` (interface lines 58-64; mapping lines 205-214)
- Test: `src/ts-protocol/text-message.test.ts` (new)

**Interfaces:**
- Consumes: nothing from other tasks.
- Produces:
  - `TS3TextMessage` gains `invokerGroups: string[]`.
  - `export function toTS3TextMessage(msg: TextMessage): TS3TextMessage` — a pure mapper, used by the `textMessage` event handler and unit-testable. Consumed (the field) by Task 3.

- [ ] **Step 1: Write the failing test**

Create `src/ts-protocol/text-message.test.ts`:

```ts
import { describe, it, expect } from "vitest";
import { toTS3TextMessage } from "./client.js";
import type { TextMessage } from "@honeybbq/teamspeak-client";

function makeMsg(over: Partial<TextMessage> = {}): TextMessage {
  return {
    invokerName: "Alice",
    invokerUID: "uid-abc",
    message: "!stop",
    invokerGroups: ["6", "8"],
    targetMode: 2,
    targetID: 0n,
    invokerID: 5,
    ...over,
  };
}

describe("toTS3TextMessage", () => {
  it("maps core fields and stringifies invokerID", () => {
    const r = toTS3TextMessage(makeMsg());
    expect(r.invokerName).toBe("Alice");
    expect(r.invokerId).toBe("5");
    expect(r.invokerUid).toBe("uid-abc");
    expect(r.message).toBe("!stop");
    expect(r.targetMode).toBe(2);
  });

  it("preserves the sender's server groups", () => {
    expect(toTS3TextMessage(makeMsg({ invokerGroups: ["6"] })).invokerGroups).toEqual(["6"]);
  });

  it("defaults missing invokerGroups to an empty array", () => {
    const partial = {
      invokerName: "Bob",
      invokerUID: "u",
      message: "!stop",
      targetMode: 1,
      targetID: 0n,
      invokerID: 7,
    } as unknown as TextMessage;
    expect(toTS3TextMessage(partial).invokerGroups).toEqual([]);
  });
});
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `npx vitest run "src/ts-protocol/text-message.test.ts"`
Expected: FAIL — `toTS3TextMessage` is not exported.

- [ ] **Step 3: Add the field and the pure mapper, and use it in the handler**

In `src/ts-protocol/client.ts`, extend the interface (add `invokerGroups`):

```ts
export interface TS3TextMessage {
  invokerName: string;
  invokerId: string;
  invokerUid: string;
  message: string;
  targetMode: number; // 1=private, 2=channel, 3=server
  invokerGroups: string[]; // sender's TS server-group ids; [] when not in view cache
}
```

Add the pure mapper just below the interface (still above the `TS3Client` class):

```ts
/**
 * Map the library's TextMessage to our wrapper. Preserves invokerGroups (the
 * sender's TS server groups), which the library populates only when the sender
 * is in the bot's client-view cache; otherwise it is []. Used by the chat
 * command permission gate.
 */
export function toTS3TextMessage(msg: TextMessage): TS3TextMessage {
  return {
    invokerName: msg.invokerName,
    invokerId: String(msg.invokerID),
    invokerUid: msg.invokerUID,
    message: msg.message,
    targetMode: msg.targetMode,
    invokerGroups: msg.invokerGroups ?? [],
  };
}
```

Replace the inline mapping inside `this.client.on("textMessage", ...)` (currently lines 205-214) with a call to the mapper:

```ts
    this.client.on("textMessage", (msg: TextMessage) => {
      this.emit("textMessage", toTS3TextMessage(msg));
    });
```

(`TextMessage` is already imported at the top of the file.)

- [ ] **Step 4: Run the test to verify it passes**

Run: `npx vitest run "src/ts-protocol/text-message.test.ts"`
Expected: PASS (3 tests).

- [ ] **Step 5: Commit**

```bash
git add "src/ts-protocol/client.ts" "src/ts-protocol/text-message.test.ts"
git commit -m "feat(ts-protocol): surface invokerGroups on TS3TextMessage via pure mapper"
```

---

### Task 3: Permission gate in `handleTextMessage` (fallback lookup + fail-closed + denial reply)

**Files:**
- Modify: `src/bot/instance.ts` (imports lines 10-14; add a module constant; `handleTextMessage` lines 317-349; add two private methods)
- Test: `src/bot/instance.test.ts` (append a new `describe` block)

**Interfaces:**
- Consumes:
  - `canRunCommand(commandName, invokerGroups, adminGroups)` from `./commands.js` (Task 1).
  - `TS3TextMessage.invokerGroups: string[]` (Task 2).
  - Existing `this.tsClient.getClientsInChannel(): Promise<ClientInfo[]>` where each `ClientInfo` has `id: number` and `serverGroups: string[]` (library already parses these).
  - Existing `this.tsClient.sendTextMessage(message: string, targetMode?: number): Promise<void>`.
- Produces:
  - `export const COMMAND_DENIED_MESSAGE: string` (exported so the test can assert it).
  - Private `isCommandAllowed(commandName, msg)` and `lookupInvokerGroups(invokerId)` (exercised via prototype in the test).

- [ ] **Step 1: Write the failing tests**

Append to `src/bot/instance.test.ts`:

```ts
import { vi } from "vitest";
import { COMMAND_DENIED_MESSAGE } from "./instance.js";
import type { TS3TextMessage } from "../ts-protocol/client.js";

/** Minimal `this` carrying only what handleTextMessage's gate path touches.
 *  The gate methods live on the prototype and are attached here so calls like
 *  `this.isCommandAllowed(...)` resolve against this same object. */
function makeGateCtx(opts: {
  adminGroups?: number[];
  clients?: Array<{ id: number; serverGroups: string[] }>;
}) {
  const ctx: any = {
    config: { commandPrefix: "!", commandAliases: {}, adminGroups: opts.adminGroups ?? [] },
    logger: { info: vi.fn(), error: vi.fn() },
    tsClient: {
      sendTextMessage: vi.fn(async () => {}),
      getClientsInChannel: vi.fn(async () => opts.clients ?? []),
    },
    executeCommand: vi.fn(async () => null),
    isCommandAllowed: (BotInstance.prototype as any).isCommandAllowed,
    lookupInvokerGroups: (BotInstance.prototype as any).lookupInvokerGroups,
  };
  return ctx;
}

function makeMsg(message: string, invokerGroups: string[] = [], invokerId = "5"): TS3TextMessage {
  return { invokerName: "Tester", invokerId, invokerUid: "uid", message, targetMode: 2, invokerGroups };
}

const handleTextMessage = (BotInstance.prototype as any).handleTextMessage as (
  this: unknown,
  msg: TS3TextMessage,
) => Promise<void>;

describe("BotInstance.handleTextMessage — command permission gate", () => {
  it("runs a public command even with enforcement on", async () => {
    const ctx = makeGateCtx({ adminGroups: [6] });
    await handleTextMessage.call(ctx, makeMsg("!play 晴天"));
    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
    expect(ctx.tsClient.sendTextMessage).not.toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
  });

  it("runs an admin command when enforcement is off (empty adminGroups)", async () => {
    const ctx = makeGateCtx({ adminGroups: [] });
    await handleTextMessage.call(ctx, makeMsg("!stop"));
    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
  });

  it("runs an admin command when the event carried a matching group", async () => {
    const ctx = makeGateCtx({ adminGroups: [6] });
    await handleTextMessage.call(ctx, makeMsg("!stop", ["6"]));
    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
    expect(ctx.tsClient.getClientsInChannel).not.toHaveBeenCalled(); // no fallback needed
  });

  it("denies an admin command when known groups do not match (no fallback, with reply)", async () => {
    const ctx = makeGateCtx({ adminGroups: [6] });
    await handleTextMessage.call(ctx, makeMsg("!stop", ["8"]));
    expect(ctx.executeCommand).not.toHaveBeenCalled();
    expect(ctx.tsClient.getClientsInChannel).not.toHaveBeenCalled();
    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
  });

  it("falls back to a group lookup when the event carried no groups, and allows on match", async () => {
    const ctx = makeGateCtx({ adminGroups: [6], clients: [{ id: 5, serverGroups: ["6"] }] });
    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
    expect(ctx.tsClient.getClientsInChannel).toHaveBeenCalledTimes(1);
    expect(ctx.executeCommand).toHaveBeenCalledTimes(1);
  });

  it("fails closed when the fallback finds the client but no matching group", async () => {
    const ctx = makeGateCtx({ adminGroups: [6], clients: [{ id: 5, serverGroups: ["8"] }] });
    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
    expect(ctx.executeCommand).not.toHaveBeenCalled();
    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
  });

  it("fails closed when the fallback cannot find the client at all", async () => {
    const ctx = makeGateCtx({ adminGroups: [6], clients: [] });
    await handleTextMessage.call(ctx, makeMsg("!stop", [], "5"));
    expect(ctx.executeCommand).not.toHaveBeenCalled();
    expect(ctx.tsClient.sendTextMessage).toHaveBeenCalledWith(COMMAND_DENIED_MESSAGE);
  });
});
```

- [ ] **Step 2: Run the tests to verify they fail**

Run: `npx vitest run "src/bot/instance.test.ts"`
Expected: FAIL — `COMMAND_DENIED_MESSAGE` is not exported; `isCommandAllowed`/`lookupInvokerGroups` are undefined.

- [ ] **Step 3: Implement the gate**

In `src/bot/instance.ts`, change the commands import (lines 10-14) from `isAdminCommand` to `canRunCommand`:

```ts
import {
  parseCommand,
  canRunCommand,
  type ParsedCommand,
} from "./commands.js";
```

Add a module-level constant just after the imports (above `export interface BotInstanceOptions`):

```ts
/** Reply sent when a non-admin invokes an admin-only chat command. */
export const COMMAND_DENIED_MESSAGE = "⛔ 需要管理员权限（该命令仅限管理员服务器组）";
```

Replace `handleTextMessage` (lines 317-349) so the dead stub becomes the real gate:

```ts
  private async handleTextMessage(msg: TS3TextMessage): Promise<void> {
    const parsed = parseCommand(
      msg.message,
      this.config.commandPrefix,
      this.config.commandAliases
    );
    if (!parsed) return;

    if (!(await this.isCommandAllowed(parsed.name, msg))) {
      this.logger.info(
        { command: parsed.name, invoker: msg.invokerName },
        "Command denied: invoker not in adminGroups"
      );
      try {
        await this.tsClient.sendTextMessage(COMMAND_DENIED_MESSAGE);
      } catch (sendErr) {
        this.logger.error({ err: sendErr }, "Failed to send permission-denied message to chat");
      }
      return;
    }

    this.logger.info(
      { command: parsed.name, args: parsed.args, invoker: msg.invokerName },
      "Command received"
    );

    try {
      const response = await this.executeCommand(parsed, msg);
      if (response) {
        await this.tsClient.sendTextMessage(response);
      }
    } catch (err) {
      this.logger.error({ err, command: parsed.name }, "Command execution error");
      try {
        await this.tsClient.sendTextMessage(
          `Error: ${(err as Error).message}`
        );
      } catch (sendErr) {
        this.logger.error({ err: sendErr }, "Failed to send error message to chat");
      }
    }
  }

  /**
   * Decide whether a chat command may run for this sender. Reads adminGroups
   * live from this.config (the router mutates the same object). Only performs
   * the async group lookup when the synchronous decision is "deny because the
   * event carried no groups" — i.e. an admin command, enforcement on, and
   * empty invokerGroups. Fails closed if groups remain undeterminable.
   */
  private async isCommandAllowed(commandName: string, msg: TS3TextMessage): Promise<boolean> {
    const adminGroups = this.config.adminGroups;
    if (canRunCommand(commandName, msg.invokerGroups, adminGroups)) return true;
    // Here: admin command, enforcement on, and the provided groups did not match.
    // If the event actually carried groups, this is a genuine deny — no lookup.
    if (msg.invokerGroups.length > 0) return false;
    // Groups unknown (sender not in the view cache): one targeted lookup, then
    // re-decide. canRunCommand([], …) is false ⇒ fail-closed when still unknown.
    const groups = await this.lookupInvokerGroups(msg.invokerId);
    return canRunCommand(commandName, groups, adminGroups);
  }

  /**
   * Best-effort lookup of a sender's server groups by client id, via the
   * channel client list (whose entries already carry parsed serverGroups).
   * Returns [] when the client can't be found or the query fails (→ deny).
   */
  private async lookupInvokerGroups(invokerId: string): Promise<string[]> {
    const clid = Number(invokerId);
    if (!Number.isFinite(clid) || clid <= 0) return [];
    try {
      const clients = await this.tsClient.getClientsInChannel();
      const match = clients.find((c) => c.id === clid);
      return match?.serverGroups ?? [];
    } catch {
      return [];
    }
  }
```

- [ ] **Step 4: Run the gate tests to verify they pass**

Run: `npx vitest run "src/bot/instance.test.ts"`
Expected: PASS (existing `runExclusive` tests + the 7 new gate tests).

- [ ] **Step 5: Confirm the live-config invariant**

Confirm `BotInstance` reads `adminGroups` from the shared, mutable config — not a copy. The constructor stores `this.config = options.config` (line 91 region) and the router (`src/web/api/bot.ts`) mutates that same object; no propagation call is needed. Quick check:

Run: `grep -n "this.config = options.config\|this.config.adminGroups" "src/bot/instance.ts"`
Expected: shows the assignment and the gate read (proves the gate uses the live reference).

- [ ] **Step 6: Commit**

```bash
git add "src/bot/instance.ts" "src/bot/instance.test.ts"
git commit -m "feat(bot): gate admin chat commands on adminGroups with fallback + deny reply"
```

---

### Task 4: Read/write `adminGroups` in the settings endpoints

**Files:**
- Modify: `src/web/api/bot.ts` (GET `/settings` lines 35-41; POST `/settings` lines 45-97)
- Test: `src/web/api/bot.test.ts` (append `it` cases to the first `describe("bot router /settings", …)` block)

**Interfaces:**
- Consumes: existing `config.adminGroups: number[]` (already declared in `src/data/config.ts`, default `[]`).
- Produces: `GET /api/bot/settings` returns `adminGroups: number[]`; `POST /api/bot/settings` accepts, validates, persists, and echoes `adminGroups`.

- [ ] **Step 1: Write the failing tests**

Append these `it` cases inside the existing first `describe("bot router /settings", …)` block in `src/web/api/bot.test.ts` (it already wires `app`, `config`, and an admin `cookie`):

```ts
  it("GET /settings includes adminGroups reflecting config", async () => {
    config.adminGroups = [6, 8];
    const res = await request(app).get("/api/bot/settings").set("Cookie", cookie);
    expect(res.status).toBe(200);
    expect(res.body.adminGroups).toEqual([6, 8]);
  });

  it("POST /settings persists a validated adminGroups and GET returns it", async () => {
    const res = await request(app)
      .post("/api/bot/settings")
      .set("Cookie", cookie)
      .send({ adminGroups: [6, 8] });
    expect(res.status).toBe(200);
    expect(res.body.adminGroups).toEqual([6, 8]);
    expect(config.adminGroups).toEqual([6, 8]);
    const followUp = await request(app).get("/api/bot/settings").set("Cookie", cookie);
    expect(followUp.body.adminGroups).toEqual([6, 8]);
  });

  it("POST /settings filters invalid adminGroups entries (negative, non-integer, non-number)", async () => {
    const res = await request(app)
      .post("/api/bot/settings")
      .set("Cookie", cookie)
      .send({ adminGroups: [6, -1, 2.5, "x", 8] });
    expect(res.status).toBe(200);
    expect(config.adminGroups).toEqual([6, 8]);
  });

  it("POST /settings ignores a non-array adminGroups (leaves config unchanged)", async () => {
    config.adminGroups = [6];
    const res = await request(app)
      .post("/api/bot/settings")
      .set("Cookie", cookie)
      .send({ adminGroups: "6" });
    expect(res.status).toBe(200);
    expect(config.adminGroups).toEqual([6]);
  });
```

- [ ] **Step 2: Run the tests to verify they fail**

Run: `npx vitest run "src/web/api/bot.test.ts"`
Expected: FAIL — `res.body.adminGroups` is `undefined`; the POST does not persist `adminGroups`.

- [ ] **Step 3: Extend the GET handler**

In `src/web/api/bot.ts`, add `adminGroups` to the GET `/settings` response (the handler at lines 35-41):

```ts
  router.get("/settings", requireNotGuest, (_req, res) => {
    res.json({
      idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
      autoPauseOnEmpty: config.autoPauseOnEmpty,
      adminGroups: config.adminGroups ?? [],
      guestMode: config.guestMode,
    });
  });
```

- [ ] **Step 4: Extend the POST handler**

In the POST `/settings` handler: (a) pull `adminGroups` out of `req.body`; (b) validate + assign before `saveConfig`; (c) echo it in the response. Change the destructuring line (46):

```ts
    const { idleTimeoutMinutes, autoPauseOnEmpty, guestMode, adminGroups } = req.body;
```

Add this block just before `saveConfig(configPath, config);` (line 77):

```ts
    if (Array.isArray(adminGroups)) {
      config.adminGroups = adminGroups.filter(
        (g: unknown): g is number =>
          typeof g === "number" && Number.isInteger(g) && g >= 0,
      );
    }
```

Add `adminGroups` to BOTH `res.json({ … })` bodies in this handler (the success response near line 92, and — if present — keep them consistent):

```ts
    res.json({
      idleTimeoutMinutes: config.idleTimeoutMinutes ?? 0,
      autoPauseOnEmpty: config.autoPauseOnEmpty,
      adminGroups: config.adminGroups ?? [],
      guestMode: config.guestMode,
    });
```

- [ ] **Step 5: Run the tests to verify they pass**

Run: `npx vitest run "src/web/api/bot.test.ts"`
Expected: PASS (existing settings/guest-mode tests + the 4 new adminGroups tests).

- [ ] **Step 6: Commit**

```bash
git add "src/web/api/bot.ts" "src/web/api/bot.test.ts"
git commit -m "feat(api): read/write adminGroups in bot settings endpoints"
```

---

### Task 5: Admin-only "命令权限" section in Settings.vue

**Files:**
- Modify: `web/src/views/Settings.vue` (template: add a section after the Guest Mode section, before the Bot Profile section ~line 506; script: add state + handlers near the guest-mode block ~line 1093; hydrate in `loadIdleTimeout` ~line 1024)

**Interfaces:**
- Consumes: `GET /api/bot/settings` → `adminGroups: number[]`; `POST /api/bot/settings` with `{ adminGroups: number[] }` (Task 4). Existing `session.isAdmin.value`.
- Produces: UI only.

- [ ] **Step 1: Add the template section**

In `web/src/views/Settings.vue`, insert this `<section>` immediately AFTER the closing `</section>` of the Guest Mode block (the one whose title is `游客模式`, ends ~line 505) and BEFORE the `<!-- Bot Profile … -->` section:

```html
    <!-- Command Permissions (admin only) -->
    <section v-if="session.isAdmin.value" class="settings-section">
      <h2 class="section-title">命令权限</h2>
      <p class="profile-section-hint">
        限制谁能在 TeamSpeak 聊天里运行管理类命令（stop / clear / remove / move / vol / mode）。
        填写允许的服务器组 ID（逗号分隔）。留空 = 不限制，所有人可用。如何查看服务器组 ID 见 README。
      </p>
      <div class="setting-row">
        <div class="prefix-input-wrap">
          <input v-model="adminGroupsText" class="input input-sm" placeholder="如 6, 8" />
          <button class="btn-primary" :disabled="adminGroupsSaving" @click="saveAdminGroups">
            {{ adminGroupsSaving ? '保存中…' : '保存' }}
          </button>
        </div>
      </div>
    </section>
```

- [ ] **Step 2: Add the script state + handlers**

In the `<script setup>` block, add this just after the guest-mode block (after `saveGuestMode` closes, ~line 1093):

```ts
// --- Command permissions (admin only) ---
const adminGroupsText = ref('');
const adminGroupsSaving = ref(false);

function applyAdminGroupsFromServer(groups: unknown) {
  if (Array.isArray(groups)) {
    adminGroupsText.value = groups.filter((g) => typeof g === 'number').join(', ');
  }
}

function parseAdminGroups(text: string): number[] {
  return text
    .split(',')
    .map((s) => s.trim())
    .filter((s) => s.length > 0)
    .map((s) => Number(s))
    .filter((n) => Number.isInteger(n) && n >= 0);
}

async function saveAdminGroups() {
  adminGroupsSaving.value = true;
  try {
    const res = await axios.post('/api/bot/settings', { adminGroups: parseAdminGroups(adminGroupsText.value) });
    applyAdminGroupsFromServer(res.data?.adminGroups);
  } catch { /* ignore */ } finally {
    adminGroupsSaving.value = false;
  }
}
```

- [ ] **Step 3: Hydrate on load**

In `loadIdleTimeout` (the existing function ~lines 1024-1031), add the hydrate call alongside `applyGuestModeFromServer`:

```ts
async function loadIdleTimeout() {
  try {
    const res = await axios.get('/api/bot/settings');
    idleTimeout.value = res.data.idleTimeoutMinutes ?? 0;
    autoPauseOnEmpty.value = res.data.autoPauseOnEmpty ?? false;
    applyGuestModeFromServer(res.data.guestMode);
    applyAdminGroupsFromServer(res.data.adminGroups);
  } catch { /* ignore */ }
}
```

- [ ] **Step 4: Type-check the frontend**

Run: `cd "web" && npx vue-tsc --noEmit`
Expected: no errors.

- [ ] **Step 5: Commit**

```bash
git add "web/src/views/Settings.vue"
git commit -m "feat(web): admin-only command-permission (adminGroups) settings section"
```

---

### Task 6: Document the feature in the README

**Files:**
- Modify: `README.md`

**Interfaces:**
- Consumes: nothing (docs).
- Produces: user-facing documentation of the feature + how to find TS server-group IDs.

- [ ] **Step 1: Locate the insertion point**

Run: `grep -n "游客模式\|Guest\|权限\|adminGroups" "README.md"`
Expected: shows the guest-mode / permissions area. Insert the new subsection immediately after the guest-mode documentation block (or, if there is a dedicated permissions/features section, at its end).

- [ ] **Step 2: Add the documentation block**

Insert this markdown at the chosen point:

```markdown
### TeamSpeak 命令权限（管理类命令限制）

默认情况下，频道里任何人都能运行所有聊天命令。你可以把一组「管理类」命令限制为只有特定 TeamSpeak 服务器组的成员才能运行：

- 受限命令：`stop`、`clear`、`remove`、`move`、`vol`、`mode`
- 其余命令（点歌、队列、跳过、歌词等）始终对所有人开放
- **默认不限制**：管理服务器组列表为空时，所有命令对所有人开放（向后兼容）

**配置方式**

- 网页端：设置 → 命令权限，填写允许的服务器组 ID（逗号分隔），保存即时生效。
- 或编辑 `config.json` 的 `adminGroups`（数字数组），例如 `"adminGroups": [6, 8]`。

填入任意服务器组 ID 后，限制立即开启：只有属于这些组之一的用户才能运行受限命令，其他人会收到「⛔ 需要管理员权限」的提示。

> 提示（fail-closed）：当受限命令来自一个机器人当前看不到其服务器组的发送者（例如不在机器人所在频道的私聊），机器人会尝试查询其分组；若仍无法确定，则拒绝执行。

**如何查看服务器组 ID**

在 TeamSpeak 客户端中打开「权限 → 服务器组」（Permissions → Server Groups）对话框，选中某个组后，其 ID 会显示在标题栏/状态栏；或在服务器组管理界面中查看每个组对应的数字 ID。把需要授权的组 ID 填入上面的设置即可。
```

- [ ] **Step 3: Sanity-check the docs render**

Run: `grep -n "命令权限\|adminGroups" "README.md"`
Expected: shows the newly added section.

- [ ] **Step 4: Commit**

```bash
git add "README.md"
git commit -m "docs: document TeamSpeak chat-command permission control"
```

---

## Final verification (after all tasks)

- [ ] Remove stale compiled output, then run the full suite:

```bash
rm -rf dist
npm test
```
Expected: all tests pass (the new `canRunCommand`, `toTS3TextMessage`, gate, and `adminGroups` settings tests included).

- [ ] Full build (backend `tsc` + frontend `vue-tsc` + vite):

```bash
npm run build
```
Expected: SUCCESS (no type errors).