inkcre-cli 0.1.0__py3-none-any.whl

inkcre_cli/__init__.py

@@ -0,0 +1 @@
+"""Independent InKCre REST consumer; no Core runtime imports."""

inkcre_cli/command.py

@@ -0,0 +1,187 @@
+"""Small shared Click options and one invocation's resources."""
+
+import sys
+from pathlib import Path
+from typing import Any, Literal
+from urllib.parse import quote
+
+import click
+from pydantic import BaseModel, TypeAdapter
+
+from . import connection
+from .errors import CommandError
+from .http import CoreRESTClient
+from .output import Output
+
+
+class Command(click.Command):
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        original = args.copy()
+        try:
+            return super().parse_args(ctx, args)
+        except click.UsageError:
+            # Click rejects unknown options before eager callbacks run. Its native
+            # tolerant parse can still find presentation options without scanning
+            # raw argv (which would mistake an --input-json value for an option).
+            with self.make_context(
+                ctx.info_name,
+                original,
+                parent=ctx.parent,
+                obj=ctx.obj,
+                resilient_parsing=True,
+                ignore_unknown_options=True,
+            ):
+                pass
+            raise
+
+
+class Group(Command, click.Group):
+    command_class = Command
+    group_class = type
+
+
+class Entity(BaseModel):
+    type: Literal["block", "relation"]
+    id: int
+
+
+def entity(value: str, *, block_only: bool = False) -> Entity:
+    kind, separator, identity = value.partition(":")
+    if not separator:
+        raise click.BadParameter("使用 block:<id> 或 relation:<id>")
+    result = Entity.model_validate({"type": kind, "id": identity})
+    if block_only and result.type != "block":
+        raise click.BadParameter("此操作需要 block:<id>")
+    return result
+
+
+def segment(value: str | int) -> str:
+    return quote(str(value), safe="")
+
+
+def duration(value: str) -> float:
+    suffix = value[-1:] if value[-1:].isalpha() else ""
+    scale = {"": 1, "s": 1, "m": 60, "h": 3600}
+    try:
+        result = float(value[:-1] if suffix else value) * scale[suffix]
+        if not 0 < result < float("inf"):
+            raise ValueError
+        return result
+    except (ValueError, KeyError) as error:
+        raise click.BadParameter("使用正数秒，或 30s / 2m / 1h") from error
+
+
+class Invocation:
+    def __init__(self):
+        self.connection_name: str | None = None
+        self.connections_file: Path | None = None
+        self.output = Output()
+        self._client: CoreRESTClient | None = None
+
+    @property
+    def local_file(self) -> Path:
+        return connection.file_path(self.connections_file)
+
+    @property
+    def client(self) -> CoreRESTClient:
+        if self._client is None:
+            _, selected = connection.select(connection.load(self.local_file), self.connection_name)
+            self._client = CoreRESTClient(selected)
+        return self._client
+
+    def close(self) -> None:
+        if self._client:
+            self._client.close()
+
+    def send(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict | None = None,
+        body: Any = None,
+        strip: tuple[str, ...] = (),
+        selectors: dict[str, str] | None = None,
+    ) -> Any:
+        try:
+            return self.client.request(method, path, params=params, body=body)
+        except CommandError as error:
+            if error.status == 422 and isinstance(error.detail, list):
+                detail = []
+                for item in error.detail:
+                    loc = list(item.get("loc", ()))
+                    if loc[:1] == ["body"]:
+                        loc = loc[1:]
+                        if loc[: len(strip)] == list(strip):
+                            loc = loc[len(strip) :]
+                        if loc and selectors and loc[0] in selectors:
+                            loc[0] = selectors[loc[0]]
+                    detail.append({**item, "loc": loc})
+                raise CommandError(detail, status=error.status) from error
+            raise
+
+    def show(self, value: Any, *, no_content: bool = False, partial_failure: bool = False) -> None:
+        self.output.emit(value, no_content=no_content)
+        if partial_failure:
+            raise CommandError("结果中存在逐项错误；成功项已保留")
+
+
+def _option(ctx: click.Context, parameter: click.Parameter, value: Any) -> Any:
+    invocation = ctx.ensure_object(Invocation)
+    if value is not None:
+        if parameter.name == "json_mode":
+            invocation.output.json_mode = value
+        elif parameter.name == "output_dir":
+            invocation.output.directory = value
+        else:
+            setattr(invocation, parameter.name, value)
+    return value
+
+
+def common(function):
+    options: list[tuple[tuple[str, ...], dict[str, Any]]] = [
+        (("--connection", "connection_name"), {"help": "本次使用的本机连接名"}),
+        (("--connections-file",), {"type": click.Path(path_type=Path), "help": "替换连接配置文件"}),
+        (
+            ("--output-dir",),
+            {"type": click.Path(path_type=Path), "help": "保存完整结果，返回入口文件"},
+        ),
+        (
+            ("--json", "json_mode"),
+            {"is_flag": True, "default": None, "is_eager": True, "help": "完整紧凑 JSON"},
+        ),
+    ]
+    for args, kwargs in options:
+        function = click.option(*args, callback=_option, expose_value=False, **kwargs)(function)
+    return function
+
+
+def input_options(function):
+    function = click.option("--schema", is_flag=True, help="只查询输入 JSON Schema，不执行操作")(
+        function
+    )
+    function = click.option("--input-json", help="直接提供 JSON 对象")(function)
+    return click.option(
+        "--input", "input_file", type=click.Path(path_type=Path), help="JSON 文件，- 表示 stdin"
+    )(function)
+
+
+def paging(function):
+    function = click.option("--cursor", help="前一页返回的 next_cursor；保留相同过滤条件")(function)
+    return click.option(
+        "--limit", type=click.IntRange(min=1), help="本次最多返回多少项；不自动翻页"
+    )(function)
+
+
+def load_input(input_file: Path | None, input_json: str | None) -> dict[str, Any]:
+    if input_file is not None and input_json is not None:
+        raise click.UsageError("--input 与 --input-json 不能同时使用")
+    if input_file is not None:
+        text = (
+            sys.stdin.read() if str(input_file) == "-" else input_file.read_text(encoding="utf-8")
+        )
+    elif input_json is not None:
+        text = input_json
+    else:
+        return {}
+    return TypeAdapter(dict[str, Any]).validate_json(text)

inkcre_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Ordinary command groups, not an Extension command registry."""

inkcre_cli/commands/agent.py

@@ -0,0 +1,121 @@
+"""Agent definitions and read-only AI/profile discovery."""
+
+import click
+
+from ..command import Group, Invocation, common, input_options, load_input, paging, segment
+from ..schema import request_schema
+
+
+@click.group(cls=Group)
+def agent():
+    """管理 Agent definition；不启动对话或本机 Agent runtime。"""
+
+
+@agent.command("list")
+@paging
+@common
+@click.pass_obj
+def list_agents(inv: Invocation, limit, cursor):
+    """列出 Agent definition。"""
+    inv.show(inv.send("GET", "/agents", params={"limit": limit, "cursor": cursor}))
+
+
+@agent.command()
+@click.argument("agent_id", type=int)
+@common
+@click.pass_obj
+def get(inv: Invocation, agent_id):
+    """读取一个 Agent definition。"""
+    inv.show(inv.send("GET", f"/agents/{agent_id}"))
+
+
+@agent.command()
+@input_options
+@common
+@click.pass_obj
+def create(inv: Invocation, schema, input_file, input_json):
+    """创建 Agent definition；模型用 ai models、工具用 agent tools 发现。"""
+    if schema:
+        return inv.show(request_schema(inv.client, "/agents", "POST"))
+    inv.show(inv.send("POST", "/agents", body=load_input(input_file, input_json)))
+
+
+@agent.command()
+@click.argument("agent_id", type=int)
+@input_options
+@common
+@click.pass_obj
+def update(inv: Invocation, agent_id, schema, input_file, input_json):
+    """修改提交的 Agent definition 字段。"""
+    if schema:
+        return inv.show(request_schema(inv.client, "/agents/{agent_id}", "PATCH"))
+    inv.show(inv.send("PATCH", f"/agents/{agent_id}", body=load_input(input_file, input_json)))
+
+
+@agent.command()
+@click.argument("agent_id", type=int)
+@common
+@click.pass_obj
+def delete(inv: Invocation, agent_id):
+    """删除 Agent definition。"""
+    inv.show(inv.send("DELETE", f"/agents/{agent_id}"), no_content=True)
+
+
+@agent.command()
+@click.argument("tool_id", required=False)
+@paging
+@common
+@click.pass_obj
+def tools(inv: Invocation, tool_id, limit, cursor):
+    """列出本机已注册 Agent Tool；给定 ID 时取得完整合同，不执行工具。"""
+    inv.show(
+        inv.send(
+            "GET",
+            "/agent-tools" + ("/" + segment(tool_id) if tool_id else ""),
+            params={"limit": limit, "cursor": cursor},
+        )
+    )
+
+
+@click.group(cls=Group)
+def ai():
+    """发现 AI 模型，不混入 Agent definition 的管理范围。"""
+
+
+@ai.command()
+@click.argument("model_id", type=int, required=False)
+@paging
+@common
+@click.pass_obj
+def models(inv: Invocation, model_id, limit, cursor):
+    """列出 AIModel，或读取指定 ID；不返回 Provider 的 secret config。"""
+    inv.show(
+        inv.send(
+            "GET",
+            "/ai/models" + (f"/{model_id}" if model_id is not None else ""),
+            params={"limit": limit, "cursor": cursor},
+        )
+    )
+
+
+@click.group("embedding-profile", cls=Group)
+def embedding_profile():
+    """只读发现语义检索可选的 embedding profile。"""
+
+
+@embedding_profile.command("list")
+@paging
+@common
+@click.pass_obj
+def list_profiles(inv: Invocation, limit, cursor):
+    """列出 EmbeddingProfile。"""
+    inv.show(inv.send("GET", "/embedding-profiles", params={"limit": limit, "cursor": cursor}))
+
+
+@embedding_profile.command("get")
+@click.argument("profile_id", type=int)
+@common
+@click.pass_obj
+def get_profile(inv: Invocation, profile_id):
+    """读取 EmbeddingProfile。"""
+    inv.show(inv.send("GET", f"/embedding-profiles/{profile_id}"))

inkcre_cli/commands/config.py

@@ -0,0 +1,95 @@
+"""Deployment config values and their runtime-owned input schemas."""
+
+import click
+
+from ..command import Group, Invocation, common, input_options, load_input, paging, segment
+from ..schema import partial
+
+
+@click.group(cls=Group)
+def config():
+    """远端 deployment 配置，与本机 connection 文件分开。"""
+
+
+@config.command("list")
+@paging
+@common
+@click.pass_obj
+def list_configs(inv: Invocation, limit, cursor):
+    """列出保存的 deployment config，不要求 schema 已加载。"""
+    inv.show(inv.send("GET", "/configs", params={"limit": limit, "cursor": cursor}))
+
+
+@config.command()
+@click.argument("key")
+@common
+@click.pass_obj
+def get(inv: Invocation, key):
+    """读取配置的实际 schema/value。"""
+    inv.show(inv.send("GET", "/configs/" + segment(key)))
+
+
+@config.command()
+@click.argument("schema_id", required=False)
+@paging
+@common
+@click.pass_obj
+def schemas(inv: Invocation, schema_id, limit, cursor):
+    """发现接入 Peer 已加载的 schema；给出 ID 时读取输入合同。"""
+    inv.show(
+        inv.send(
+            "GET",
+            "/config-schemas" + ("/" + segment(schema_id) if schema_id else ""),
+            params={"limit": limit, "cursor": cursor},
+        )
+    )
+
+
+@config.command()
+@click.argument("key")
+@click.option("--schema-id", required=True)
+@input_options
+@common
+@click.pass_obj
+def replace(inv: Invocation, key, schema_id, schema, input_file, input_json):
+    """创建或完整替换；JSON 是 value 本身，不再包装 value。"""
+    if schema:
+        return inv.show(inv.send("GET", "/config-schemas/" + segment(schema_id))["input_schema"])
+    inv.show(
+        inv.send(
+            "PUT",
+            "/configs/" + segment(key),
+            body={
+                "schema": schema_id,
+                "value": load_input(input_file, input_json),
+            },
+            strip=("value",),
+            selectors={"schema": "--schema-id"},
+        )
+    )
+
+
+@config.command()
+@click.argument("key")
+@input_options
+@common
+@click.pass_obj
+def update(inv: Invocation, key, schema, input_file, input_json):
+    """更新 value 的提交字段；嵌套值按 owner 合同处理。"""
+    if schema:
+        existing = inv.send("GET", "/configs/" + segment(key))
+        return inv.show(
+            partial(
+                inv.send("GET", "/config-schemas/" + segment(existing["schema"]))["input_schema"]
+            )
+        )
+    inv.show(inv.send("PATCH", "/configs/" + segment(key), body=load_input(input_file, input_json)))
+
+
+@config.command()
+@click.argument("key")
+@common
+@click.pass_obj
+def delete(inv: Invocation, key):
+    """删除保存的配置值。"""
+    inv.show(inv.send("DELETE", "/configs/" + segment(key)), no_content=True)

inkcre_cli/commands/connection.py

@@ -0,0 +1,109 @@
+"""Offline connection editing and explicit connectivity observation."""
+
+from typing import Any
+
+import click
+import httpx
+
+from .. import connection as store
+from ..command import Group, Invocation, common, input_options, load_input
+from ..errors import CommandError
+
+
+@click.group(cls=Group)
+def connection():
+    """本机命名连接，不是远端 deployment config 或 Peer 注册。"""
+
+
+@connection.command("list")
+@common
+@click.pass_obj
+def list_connections(inv: Invocation):
+    """离线列出名称、地址与保存的默认名。"""
+    data = store.load(inv.local_file)
+    inv.show(
+        {
+            "default": data.default,
+            "connections": {
+                name: {"base_url": str(value.base_url)} for name, value in data.connections.items()
+            },
+        }
+    )
+
+
+@connection.command()
+@click.argument("name")
+@common
+@click.pass_obj
+def get(inv: Invocation, name):
+    """离线读取指定连接，包括保存的 JWT secret。"""
+    _, value = store.select(store.load(inv.local_file), name)
+    inv.show(value.model_dump(mode="json"))
+
+
+@connection.command("set")
+@click.argument("name")
+@input_options
+@common
+@click.pass_obj
+def set_connection(inv: Invocation, name, schema, input_file, input_json):
+    """创建或完整替换命名连接；输入 base_url 与 jwt_secret。"""
+    if schema:
+        return inv.show(store.Connection.model_json_schema())
+    value = store.Connection.model_validate(load_input(input_file, input_json))
+    data = store.load(inv.local_file)
+    data.connections[name] = value
+    if data.default is None:
+        data.default = name
+    store.save(inv.local_file, data)
+    inv.show({"name": name, "base_url": str(value.base_url), "default": data.default})
+
+
+@connection.command()
+@click.argument("name")
+@common
+@click.pass_obj
+def use(inv: Invocation, name):
+    """修改本机默认连接。"""
+    data = store.load(inv.local_file)
+    store.select(data, name)
+    data.default = name
+    store.save(inv.local_file, data)
+    inv.show({"default": name})
+
+
+@connection.command()
+@click.argument("name")
+@common
+@click.pass_obj
+def delete(inv: Invocation, name):
+    """删除本机连接；不操作远端部署。"""
+    data = store.load(inv.local_file)
+    store.select(data, name)
+    del data.connections[name]
+    if data.default == name:
+        data.default = None
+    store.save(inv.local_file, data)
+    inv.show(None, no_content=True)
+
+
+@connection.command()
+@common
+@click.pass_obj
+def check(inv: Invocation):
+    """分别检查公共 readyz 与受保护读取，不把就绪误当成认证成功。"""
+    result: dict[str, Any] = {"endpoint": inv.client.base_url}
+    failed = False
+    for key, path, authenticated in (
+        ("readyz", "/readyz", False),
+        ("authenticated_read", "/peers/self", True),
+    ):
+        try:
+            result[key] = inv.client.request("GET", path, authenticated=authenticated)
+        except CommandError as error:
+            result[key] = {"error": error.as_dict()}
+            failed = True
+        except httpx.RequestError as error:
+            result[key] = {"error": {"detail": str(error)}}
+            failed = True
+    inv.show(result, partial_failure=failed)

inkcre_cli/commands/extension.py

@@ -0,0 +1,125 @@
+"""Extension Host REST management; no CLI-specific Extension adapters."""
+
+import click
+
+from ..command import Group, Invocation, common, input_options, load_input, paging, segment
+from ..errors import CommandError
+from ..schema import partial
+
+
+def route(coordinate: str) -> str:
+    namespace, separator, name = coordinate.partition("/")
+    if not separator or not namespace or not name or "/" in name:
+        raise click.BadParameter("Extension 使用 namespace/name coordinate")
+    return "/extensions/" + segment(namespace) + "/" + segment(name)
+
+
+@click.group(cls=Group)
+def extension():
+    """安装、配置和启停 Extension；发布仍由 Extension 的交付流程负责。"""
+
+
+@extension.command("list")
+@paging
+@common
+@click.pass_obj
+def list_extensions(inv: Invocation, limit, cursor):
+    """列出 Extension 的安装、启用意图与运行状态。"""
+    inv.show(inv.send("GET", "/extensions", params={"limit": limit, "cursor": cursor}))
+
+
+@extension.command()
+@click.argument("coordinate")
+@common
+@click.pass_obj
+def get(inv: Invocation, coordinate):
+    """读取一个已安装 Extension。"""
+    inv.show(inv.send("GET", route(coordinate)))
+
+
+@extension.command()
+@click.argument("coordinate")
+@click.option("--version", required=True, help="准确的已发布版本，不解析 latest")
+@common
+@click.pass_obj
+def install(inv: Invocation, coordinate, version):
+    """安装准确版本；不隐式启用。"""
+    inv.show(inv.send("POST", route(coordinate), params={"version": version}))
+
+
+@extension.command()
+@click.argument("coordinate")
+@common
+@click.pass_obj
+def uninstall(inv: Invocation, coordinate):
+    """卸载 Extension。"""
+    inv.show(inv.send("DELETE", route(coordinate)), no_content=True)
+
+
+@extension.command()
+@click.argument("coordinate")
+@click.option("--peer", help="启用意图的目标 Peer；省略时为接入 Peer")
+@common
+@click.pass_obj
+def enable(inv: Invocation, coordinate, peer):
+    """在指定或当前 Peer 启用 Extension。"""
+    inv.show(inv.send("POST", route(coordinate) + "/enable", params={"route_to_peer": peer}))
+
+
+@extension.command()
+@click.argument("coordinate")
+@click.option("--peer", help="禁用意图的目标 Peer；省略时为接入 Peer")
+@common
+@click.pass_obj
+def disable(inv: Invocation, coordinate, peer):
+    """在指定或当前 Peer 禁用 Extension。"""
+    inv.show(inv.send("POST", route(coordinate) + "/disable", params={"route_to_peer": peer}))
+
+
+@extension.group()
+def config():
+    """读写 Extension 的持久配置，不要求先启用。"""
+
+
+@config.command("get")
+@click.argument("coordinate")
+@common
+@click.pass_obj
+def get_config(inv: Invocation, coordinate):
+    """从安装记录读取 config；不调用业务 schema 验证。"""
+    inv.show(inv.send("GET", route(coordinate))["config"])
+
+
+def config_schema(inv: Invocation, coordinate: str) -> dict:
+    contract = inv.send("GET", route(coordinate))["config_schema"]
+    if contract is None:
+        raise CommandError("该 Extension 尚未发布配置 schema；可在启用后重新发现")
+    return contract
+
+
+@config.command("replace")
+@click.argument("coordinate")
+@input_options
+@common
+@click.pass_obj
+def replace_config(inv: Invocation, coordinate, schema, input_file, input_json):
+    """完整替换 Extension config。"""
+    if schema:
+        return inv.show(config_schema(inv, coordinate))
+    inv.show(
+        inv.send("PUT", route(coordinate) + "/config", body=load_input(input_file, input_json))
+    )
+
+
+@config.command("update")
+@click.argument("coordinate")
+@input_options
+@common
+@click.pass_obj
+def update_config(inv: Invocation, coordinate, schema, input_file, input_json):
+    """更新提交的 config 字段。"""
+    if schema:
+        return inv.show(partial(config_schema(inv, coordinate)))
+    inv.show(
+        inv.send("PATCH", route(coordinate) + "/config", body=load_input(input_file, input_json))
+    )