feat(plugin): 迁移 setup helper 到 Commands

.github/workflows/plugin-api-v3.yml

@@ -0,0 +1,51 @@
+name: plugin-api-v3
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: akashic-plugins/plugin-contracts
+          ref: 4dd69dd621e029e51e99aa428443fa3a4ec1f6cf
+          path: .plugin-contracts
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Check Plugin API v3
+        env:
+          PYTHONPATH: .plugin-contracts
+        run: python -m akashic_plugin_contracts check plugin.py
+
+  composition-parity:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: kachofugetsu09/akashic-agent
+          ref: 8c45ab7873aac8c9eebcd22e9d6ae123f8dcf616
+          path: .akashic-core
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: .akashic-core/requirements.txt
+      - name: Install pinned Core dependencies
+        run: python -m pip install -r .akashic-core/requirements.txt pytest pytest-asyncio
+      - name: Compare v2 and v3 command receipts
+        env:
+          AKASHIC_AGENT_ROOT: .akashic-core
+          PYTHONPATH: .akashic-core
+        run: python -m pytest -q tests/

plugin.py

@@ -2,18 +2,67 @@
 
 import os
 from pathlib import Path
-from typing import cast
+from typing import Protocol, cast
 
 from pydantic import BaseModel
 
 from agent.lifecycle.types import BeforeTurnCtx, TurnState
+from agent.plugin_composition import (
+    COMMANDS,
+    CommandDefinition,
+    CommandInvocation,
+    CommandResult,
+    Context,
+)
 from agent.plugins import Plugin
 
 
 class SetupHelperConfig(BaseModel):
     qqbot_data_dir: str = ""
 
 
+api_version = 3
+name = "setup_helper"
+version = "1.0.0"
+desc = "快速查询当前会话 chat_id，用于配置 proactive"
+Config = SetupHelperConfig
+inject = (COMMANDS,)
+
+
+class _BeforeTurnFrame(Protocol):
+    input: TurnState
+    slots: dict[str, object]
+
+
+async def apply(ctx: Context, config: SetupHelperConfig) -> None:
+    """Register the chat identity command against the Core command seam."""
+
+    # 1. Resolve plugin-owned presentation configuration once per generation.
+    qqbot_config_path = _qqbot_config_path(config)
+
+    # 2. Core owns admission; this plugin owns the command behavior and text.
+    async def handle(invocation: CommandInvocation) -> CommandResult:
+        chat_id = invocation.chat_id or "（未知）"
+        return CommandResult(
+            "success",
+            _format_reply(
+                chat_id,
+                channel=invocation.channel,
+                qqbot_config_path=qqbot_config_path,
+            ),
+        )
+
+    await ctx.require(COMMANDS).register(
+        ctx,
+        CommandDefinition(
+            name="chatid",
+            description="查看我的 chat_id（配置 proactive 用）",
+            aliases=("myid",),
+            handler=handle,
+        ),
+    )
+
+
 class ChatIdCommandModule:
     slot = "setup_helper.chatid"
     requires = ("before_turn.acquire_session", "session:session")
@@ -23,9 +72,10 @@ def __init__(self, qqbot_config_path: Path | None) -> None:
         self._qqbot_config_path = qqbot_config_path
 
     async def run(self, frame: object) -> object:
-        if "session:ctx" in frame.slots:  # type: ignore[attr-defined]
+        typed_frame = cast(_BeforeTurnFrame, frame)
+        if "session:ctx" in typed_frame.slots:
             return frame
-        state: TurnState = frame.input  # type: ignore[attr-defined]
+        state = typed_frame.input
         if _normalize_command(state.msg.content) not in {"/chatid", "/myid"}:
             return frame
         chat_id = state.msg.chat_id or "（未知）"
@@ -34,7 +84,7 @@ async def run(self, frame: object) -> object:
             channel=state.msg.channel,
             qqbot_config_path=self._qqbot_config_path,
         )
-        frame.slots["session:ctx"] = _abort_ctx(state, reply)  # type: ignore[attr-defined]
+        typed_frame.slots["session:ctx"] = _abort_ctx(state, reply)
         return frame