esclak 0.0.5__py3-none-any.whl

clak/__init__.py

@@ -0,0 +1,3 @@
+"""clak：固定流程脚本壳。"""
+
+__version__ = "0.0.5"

clak/__main__.py

@@ -0,0 +1,4 @@
+from clak.cli import main
+
+if __name__ == "__main__":
+    main()

clak/cli.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from clak.runtime.headless import HeadlessError, emit, run_line
+from clak.tui.app import run_tui
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="clak", description="固定流程脚本 TUI")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("tui", help="打开交互 TUI（默认）")
+
+    exec_parser = sub.add_parser("exec", help="无头执行一条 slash 或 prompt")
+    exec_parser.add_argument(
+        "line",
+        help='要执行的行，例如 "/version" 或 "/pack-game-res"',
+    )
+    exec_parser.add_argument(
+        "--set",
+        action="append",
+        default=[],
+        metavar="FIELD=VALUE",
+        help="脚本参数（可重复），如 --set version=1.0 --set targets=base,cn",
+    )
+    exec_parser.add_argument(
+        "--use-defaults",
+        action="store_true",
+        help="未 --set 的 ask 字段使用 AskRequest.default（无交互批量）",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    command = args.command
+
+    if command == "exec":
+        from clak.runtime.params import ScriptInputs
+
+        try:
+            inputs = ScriptInputs.parse_set_flags(
+                args.set,
+                allow_defaults=args.use_defaults or not args.set,
+            )
+            run = run_line(args.line, script_inputs=inputs)
+        except (HeadlessError, ValueError) as error:
+            print(f"clak: {error}", file=sys.stderr)
+            code = error.code if isinstance(error, HeadlessError) else 2
+            raise SystemExit(code) from error
+        raise SystemExit(emit(run))
+
+    if command in (None, "tui"):
+        run_tui()
+        return
+
+    parser.error(f"未知子命令: {command}")

clak/commands/__init__.py

@@ -0,0 +1 @@
+# 各 slash 子命令见同目录模块；聚合在 registry。

clak/commands/_registry.py

@@ -0,0 +1,40 @@
+from clak.commands import (
+    clear,
+    quit,
+    status,
+    version,
+)
+from clak.commands.types import ScriptEntry, SlashCommand, SlashEntry
+from clak.runtime.session import ScriptSession
+from clak.scripts._registry import all_scripts
+
+_BUILTINS: tuple[SlashCommand, ...] = (
+    clear.COMMAND,
+    version.COMMAND,
+    status.COMMAND,
+    quit.COMMAND,
+)
+
+COMMANDS: tuple[SlashEntry, ...] = _BUILTINS + all_scripts()
+
+
+def command_for_token(token: str) -> SlashEntry | None:
+    needle = token.lower()
+    for cmd in COMMANDS:
+        if needle in cmd.all_names():
+            return cmd
+    return None
+
+
+def script_command(script_id: str) -> ScriptEntry | None:
+    for cmd in all_scripts():
+        if cmd.script_id == script_id:
+            return cmd
+    return None
+
+
+def run_script(session: ScriptSession, script_id: str) -> None:
+    cmd = script_command(script_id)
+    if not cmd:
+        raise ValueError(f"未知脚本: {script_id}")
+    cmd.script_run(session)

clak/commands/clear.py

@@ -0,0 +1,21 @@
+from clak.commands.types import (
+    SlashAction,
+    SlashCommand,
+    SlashDispatchResult,
+)
+
+
+def dispatch() -> SlashDispatchResult:
+    return SlashDispatchResult(
+        action=SlashAction.NEW_SESSION,
+        message="已清空 history",
+        status="Session cleared",
+    )
+
+
+COMMAND = SlashCommand(
+    "/clear",
+    ("/new",),
+    "清空 history",
+    handler=dispatch,
+)

clak/commands/quit.py

@@ -0,0 +1,17 @@
+from clak.commands.types import (
+    SlashAction,
+    SlashCommand,
+    SlashDispatchResult,
+)
+
+
+def dispatch() -> SlashDispatchResult:
+    return SlashDispatchResult(action=SlashAction.QUIT, status="再见")
+
+
+COMMAND = SlashCommand(
+    "/quit",
+    ("/exit",),
+    "退出 TUI",
+    handler=dispatch,
+)

clak/commands/status.py

@@ -0,0 +1,21 @@
+from clak.commands.types import (
+    SlashAction,
+    SlashCommand,
+    SlashDispatchResult,
+)
+
+
+def dispatch() -> SlashDispatchResult:
+    return SlashDispatchResult(
+        action=SlashAction.SHOW_STATUS,
+        message="clak 脚本聚合",
+        status="已显示状态",
+    )
+
+
+COMMAND = SlashCommand(
+    "/status",
+    ("/context",),
+    "软件名与定位",
+    handler=dispatch,
+)

clak/commands/types.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum, auto
+
+from clak.runtime.session import ScriptSession
+
+
+class SlashAction(Enum):
+    NONE = auto()
+    NEW_SESSION = auto()
+    SHOW_STATUS = auto()
+    RUN_SCRIPT = auto()
+    QUIT = auto()
+    UNKNOWN = auto()
+
+
+@dataclass(frozen=True)
+class SlashMatch:
+    name: str
+    description: str
+
+
+@dataclass
+class SlashDispatchResult:
+    action: SlashAction
+    message: str | None = None
+    status: str | None = None
+    command: str | None = None
+
+
+class SlashTokenKind(Enum):
+    NOT_SLASH = auto()
+    INCOMPLETE = auto()
+    AVAILABLE = auto()
+    UNKNOWN = auto()
+
+
+SlashHandler = Callable[[], SlashDispatchResult]
+ScriptRunner = Callable[[ScriptSession], None]
+
+
+@dataclass(frozen=True)
+class SlashCommand:
+    """纯 slash 命令：只分发，不跑脚本。"""
+
+    name: str
+    aliases: tuple[str, ...]
+    description: str
+    handler: SlashHandler
+
+    def all_names(self) -> tuple[str, ...]:
+        return (self.name, *self.aliases)
+
+
+@dataclass(frozen=True)
+class ScriptEntry:
+    """脚本入口：slash 名 + 脚本 runner。"""
+
+    name: str
+    aliases: tuple[str, ...]
+    description: str
+    script_id: str
+    script_run: ScriptRunner
+
+    def all_names(self) -> tuple[str, ...]:
+        return (self.name, *self.aliases)
+
+
+SlashEntry = SlashCommand | ScriptEntry

clak/commands/version.py

@@ -0,0 +1,22 @@
+from clak import __version__
+from clak.commands.types import (
+    SlashAction,
+    SlashCommand,
+    SlashDispatchResult,
+)
+
+
+def dispatch() -> SlashDispatchResult:
+    return SlashDispatchResult(
+        action=SlashAction.SHOW_STATUS,
+        message=f"clak {__version__}",
+        status="已显示版本",
+    )
+
+
+COMMAND = SlashCommand(
+    "/version",
+    (),
+    "显示工具版本",
+    handler=dispatch,
+)

clak/runtime/ask/__init__.py

@@ -0,0 +1,12 @@
+"""ask 协议：请求、选项、答案与解析。"""
+
+from clak.runtime.ask.answer import AskAnswer, parse_ask_answer
+from clak.runtime.ask.request import AskChoice, AskMode, AskRequest
+
+__all__ = [
+    "AskAnswer",
+    "AskChoice",
+    "AskMode",
+    "AskRequest",
+    "parse_ask_answer",
+]

clak/runtime/ask/answer.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from clak.runtime.ask.request import AskMode, AskRequest
+
+
+@dataclass(frozen=True)
+class AskAnswer:
+    """脚本侧结构化答案；线协议仅在边界序列化。"""
+
+    field_id: str
+    text: str
+    tokens: frozenset[str]
+
+    @property
+    def primary(self) -> str:
+        return self.text
+
+
+def parse_ask_answer(request: AskRequest, wire: str) -> AskAnswer:
+    raw = wire.strip() or request.default
+    if request.mode == AskMode.MULTI:
+        parts = {p.strip() for p in raw.split(",") if p.strip()}
+        return AskAnswer(
+            field_id=request.field_id,
+            text=",".join(sorted(parts)),
+            tokens=frozenset(parts),
+        )
+    return AskAnswer(
+        field_id=request.field_id,
+        text=raw,
+        tokens=frozenset({raw}),
+    )

clak/runtime/ask/request.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class AskMode(Enum):
+    SINGLE = auto()
+    MULTI = auto()
+    FILTER = auto()
+
+
+@dataclass(frozen=True)
+class AskChoice:
+    label: str
+    value: str | None = None
+
+
+@dataclass(frozen=True)
+class AskRequest:
+    field_id: str
+    prompt: str
+    default: str
+    choices: tuple[AskChoice, ...] = ()
+    mode: AskMode = AskMode.SINGLE

clak/runtime/headless.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+
+from clak.commands._registry import run_script
+from clak.runtime.params import MissingScriptInputError, ScriptInputs
+from clak.runtime.session import ScriptSession
+from clak.runtime.slash import (
+    SlashAction,
+    SlashEngine,
+)
+
+
+class HeadlessError(Exception):
+    def __init__(self, message: str, code: int = 2) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class HeadlessRun:
+    text: str
+    exit_code: int = 0
+    stream: str = "stdout"
+
+
+def run_line(
+    line: str,
+    *,
+    script_inputs: ScriptInputs | None = None,
+) -> HeadlessRun:
+    stripped = line.strip()
+    if not stripped:
+        raise HeadlessError("输入不能为空", code=2)
+    if stripped.startswith("/"):
+        return _run_slash(stripped, script_inputs)
+    return _run_prompt(stripped)
+
+
+def _run_slash(
+    line: str,
+    script_inputs: ScriptInputs | None,
+) -> HeadlessRun:
+    engine = SlashEngine()
+    result = engine.dispatch(line)
+
+    match result.action:
+        case SlashAction.QUIT:
+            return HeadlessRun("", 0)
+        case SlashAction.UNKNOWN:
+            msg = result.message or f"未知命令 {result.command}"
+            return HeadlessRun(msg, 2, stream="stderr")
+        case SlashAction.RUN_SCRIPT:
+            if not result.command:
+                return HeadlessRun("缺少脚本名", 2, stream="stderr")
+            return _run_script_headless(result.command, script_inputs)
+        case SlashAction.SHOW_STATUS | SlashAction.NEW_SESSION | SlashAction.NONE:
+            if result.message:
+                return HeadlessRun(result.message, 0)
+            if result.status:
+                return HeadlessRun(result.status, 0)
+            return HeadlessRun("", 0)
+
+
+def _run_prompt(prompt: str) -> HeadlessRun:
+    body = "请使用 slash 命令，例如 /pack-game-res"
+    return HeadlessRun(body, 0)
+
+
+def _run_script_headless(
+    script_id: str,
+    script_inputs: ScriptInputs | None,
+) -> HeadlessRun:
+    lines: list[str] = []
+    inputs = script_inputs or ScriptInputs(allow_defaults=True)
+    session = ScriptSession(lines.append, inputs=inputs, fail_on_missing=not inputs.allow_defaults)
+    try:
+        run_script(session, script_id)
+    except ValueError as error:
+        return HeadlessRun(str(error), 2, stream="stderr")
+    except MissingScriptInputError as error:
+        return HeadlessRun(str(error), 2, stream="stderr")
+    if session.is_awaiting_input:
+        req = session.pending_request
+        field = req.field_id if req else "?"
+        return HeadlessRun(
+            f"脚本等待输入 [{field}]，请用 --set {field}=... 补齐",
+            2,
+            stream="stderr",
+        )
+    return HeadlessRun("\n".join(lines), 0)
+
+
+def emit(run: HeadlessRun) -> int:
+    if run.text:
+        if run.stream == "stderr":
+            print(run.text, file=sys.stderr)
+        else:
+            print(run.text)
+    return run.exit_code

clak/runtime/params.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+class MissingScriptInputError(ValueError):
+    def __init__(self, field_id: str, prompt: str) -> None:
+        super().__init__(f"缺少脚本输入 [{field_id}]: {prompt}")
+        self.field_id = field_id
+
+
+@dataclass
+class ScriptInputs:
+    """Exec 无交互：只从此读取参数；未补齐则挂起或报错。"""
+
+    values: dict[str, str] = field(default_factory=dict)
+    allow_defaults: bool = False
+
+    def get(self, field_id: str) -> str | None:
+        return self.values.get(field_id)
+
+    def set(self, field_id: str, wire: str) -> None:
+        self.values[field_id] = wire.strip()
+
+    def resolve_wire(self, field_id: str, default: str) -> str | None:
+        wire = self.get(field_id)
+        if wire is not None:
+            return wire
+        if self.allow_defaults and default:
+            return default
+        return None
+
+    @classmethod
+    def from_pairs(cls, pairs: dict[str, str], *, allow_defaults: bool = False) -> ScriptInputs:
+        return cls(values=dict(pairs), allow_defaults=allow_defaults)
+
+    @classmethod
+    def parse_set_flags(cls, flags: list[str], *, allow_defaults: bool = False) -> ScriptInputs:
+        values: dict[str, str] = {}
+        for item in flags:
+            if "=" not in item:
+                raise ValueError(f"无效 --set 格式（需 field=value）: {item}")
+            key, value = item.split("=", 1)
+            key = key.strip()
+            if not key:
+                raise ValueError(f"无效 --set 格式: {item}")
+            values[key] = value.strip()
+        return cls(values=values, allow_defaults=allow_defaults)

clak/runtime/session.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from clak.runtime.step_list import StepList
+from clak.runtime.ask import AskAnswer, AskRequest, parse_ask_answer
+from clak.runtime.params import MissingScriptInputError, ScriptInputs
+
+LogFn = Callable[[str], None]
+AnswerFn = Callable[[AskAnswer], None]
+
+
+class ScriptSession:
+    """Exec 无交互；缺参时挂起 gate，由 provide_input 补齐后继续。"""
+
+    def __init__(
+        self,
+        log: LogFn,
+        *,
+        inputs: ScriptInputs | None = None,
+        fail_on_missing: bool = False,
+    ) -> None:
+        self.log = log
+        self.inputs = inputs or ScriptInputs()
+        self.fail_on_missing = fail_on_missing
+        self.step_list = StepList()
+        self._cancelled = False
+        self._running = False
+        self._on_finished: Callable[[], None] | None = None
+        self._pending_request: AskRequest | None = None
+        self._pending_answer: AnswerFn | None = None
+
+    @property
+    def pending_request(self) -> AskRequest | None:
+        return self._pending_request
+
+    @property
+    def is_awaiting_input(self) -> bool:
+        return self._pending_request is not None and not self._cancelled
+
+    @property
+    def is_running(self) -> bool:
+        return self._running and not self._cancelled
+
+    def on_finished(self, callback: Callable[[], None] | None) -> None:
+        self._on_finished = callback
+
+    def bind_step_end(self) -> None:
+        self.step_list.set_end_callback(self._notify_finished)
+
+    def _notify_finished(self) -> None:
+        if self._cancelled:
+            return
+        self._running = False
+        self._clear_pending()
+        if self._on_finished:
+            self._on_finished()
+
+    def cancel(self) -> None:
+        self._cancelled = True
+        self._running = False
+        self._clear_pending()
+        self.step_list.stop()
+        self.step_list.clear()
+
+    def ask_step(self, request: AskRequest, on_answer: AnswerFn) -> int:
+        if self._cancelled:
+            return 0
+        wire = self.inputs.resolve_wire(request.field_id, request.default)
+        if wire is not None:
+            on_answer(parse_ask_answer(request, wire))
+            return 0
+        if self.fail_on_missing:
+            raise MissingScriptInputError(request.field_id, request.prompt)
+        self._pending_request = request
+        self._pending_answer = on_answer
+        return 1
+
+    def provide_input(self, field_id: str, wire: str) -> bool:
+        if self._cancelled:
+            return False
+        self.inputs.set(field_id, wire)
+        if not self._pending_request or self._pending_request.field_id != field_id:
+            return False
+        request = self._pending_request
+        answer_cb = self._pending_answer
+        self._clear_pending()
+        if not answer_cb:
+            return False
+        answer_cb(parse_ask_answer(request, wire))
+        self.step_list.resume()
+        self._sync_running()
+        return True
+
+    def run(self) -> None:
+        if self._cancelled:
+            return
+        self._running = True
+        self.step_list.execute()
+        self._sync_running()
+
+    def _clear_pending(self) -> None:
+        self._pending_request = None
+        self._pending_answer = None
+
+    def _sync_running(self) -> None:
+        if self._cancelled:
+            self._running = False
+            return
+        if self.is_awaiting_input or self.step_list.is_waiting:
+            return
+        if self.step_list.is_finished:
+            self._running = False

clak/runtime/slash.py

@@ -0,0 +1,72 @@
+"""Slash 命令：实现见 commands/*，引擎在此。"""
+
+from __future__ import annotations
+
+from clak.commands._registry import COMMANDS, command_for_token
+from clak.commands.types import (
+    ScriptEntry,
+    SlashAction,
+    SlashDispatchResult,
+    SlashEntry,
+    SlashMatch,
+    SlashTokenKind,
+)
+
+__all__ = [
+    "SlashAction",
+    "SlashDispatchResult",
+    "SlashEngine",
+    "SlashEntry",
+    "SlashMatch",
+    "SlashTokenKind",
+]
+
+
+class SlashEngine:
+    def filter(self, input_text: str) -> list[SlashMatch]:
+        token = input_text.split()[0] if input_text.split() else input_text
+        if not token.startswith("/"):
+            return []
+        needle = token.lower()
+        matches: list[SlashMatch] = []
+        for cmd in COMMANDS:
+            names = cmd.all_names()
+            if any(name.startswith(needle) or needle.startswith(name) for name in names):
+                matches.append(SlashMatch(cmd.name, cmd.description))
+        if not matches and input_text.startswith("/"):
+            for cmd in COMMANDS:
+                matches.append(SlashMatch(cmd.name, cmd.description))
+        return matches
+
+    def token_kind(self, token: str) -> SlashTokenKind:
+        if not token.startswith("/"):
+            return SlashTokenKind.NOT_SLASH
+        if command_for_token(token):
+            return SlashTokenKind.AVAILABLE
+        if token == "/":
+            return SlashTokenKind.INCOMPLETE
+        return SlashTokenKind.UNKNOWN
+
+    def tab_completion(self, input_text: str, selected: int) -> str | None:
+        matches = self.filter(input_text)
+        if not matches or selected >= len(matches):
+            return None
+        return matches[selected].name
+
+    def dispatch(self, line: str) -> SlashDispatchResult:
+        token = line.split()[0].lower() if line.split() else line.lower()
+        cmd = command_for_token(token)
+        if not cmd:
+            return SlashDispatchResult(
+                action=SlashAction.UNKNOWN,
+                command=token,
+                message=f"未知命令 {token}",
+                status="unknown slash",
+            )
+        if isinstance(cmd, ScriptEntry):
+            return SlashDispatchResult(
+                action=SlashAction.RUN_SCRIPT,
+                command=cmd.script_id,
+                status=cmd.script_id,
+            )
+        return cmd.handler()