polaris-python-ai 0.0.1.dev2__tar.gz

polaris_python_ai-0.0.1.dev2/LICENSE

@@ -0,0 +1,27 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Tencent
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

polaris_python_ai-0.0.1.dev2/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md README-zh.md
+recursive-include docs *.md
+recursive-include examples *.py *.yaml *.md
+recursive-include tests *.py

polaris_python_ai-0.0.1.dev2/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: polaris-python-ai
+Version: 0.0.1.dev2
+Summary: Polaris integrations for Python AI frameworks.
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/polaris-contrib/polaris-python-ai
+Project-URL: Repository, https://github.com/polaris-contrib/polaris-python-ai
+Project-URL: Issues, https://github.com/polaris-contrib/polaris-python-ai/issues
+Project-URL: Documentation, https://github.com/polaris-contrib/polaris-python-ai#readme
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: polaris-python<0.1,>=0.0.1.dev0
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk<2,>=1.2.3; extra == "a2a"
+Provides-Extra: agentscope
+Requires-Dist: a2a-sdk<2,>=1.2.3; extra == "agentscope"
+Requires-Dist: agentscope<3,>=2.0.10; extra == "agentscope"
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=1.0; extra == "langgraph"
+Provides-Extra: mcp
+Requires-Dist: a2a-sdk<2,>=1.2.3; extra == "mcp"
+Requires-Dist: agentscope<3,>=2.0.10; extra == "mcp"
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: a2a-sdk<2,>=1.2.3; extra == "all"
+Requires-Dist: agentscope<3,>=2.0.10; extra == "all"
+Requires-Dist: langgraph<2,>=1.0; extra == "all"
+Requires-Dist: mcp<3,>=2; extra == "all"
+Dynamic: license-file
+
+# polaris-python-ai
+
+Polaris integrations for Python AI frameworks. The repository publishes one
+distribution, `polaris-python-ai`, with optional A2A, AgentScope, MCP, and
+LangGraph extras under the `polaris_ai` import namespace.
+
+## Development Installation
+
+Use Python 3.12 or newer. Run from this project's root directory:
+
+```bash
+uv sync --all-extras
+uv run python -m pytest
+```
+
+The sibling `polaris-python` checkout is selected through `[tool.uv.sources]`;
+published wheel metadata contains only version ranges.
+
+Install framework adapters through package extras:
+
+```bash
+pip install "polaris-python-ai[a2a]"
+pip install "polaris-python-ai[agentscope]"
+pip install "polaris-python-ai[langgraph]"
+pip install "polaris-python-ai[mcp]"
+```
+
+See [docs/version-release.md](docs/version-release.md) for the single version file,
+Snapshot format, and release tag.
+
+See [docs/configuration.md](docs/configuration.md) for the complete feature and
+configuration guide, including Core SDK, Skill, A2A, MCP and AI logging settings.
+
+AgentScope, A2A, and LangGraph are optional. Base-package imports do not load
+their SDKs. The integration targets AgentScope 2.0.10, A2A SDK 1.2.3, and
+LangGraph 1.x. Legacy Java AgentCard JSON is decoded through the official A2A
+compatibility parser.
+
+## Shared AgentScope Context
+
+```python
+from polaris_ai.agentscope import PolarisAgentContext
+
+with PolarisAgentContext.from_address("127.0.0.1:8091", "default") as polaris:
+    provider = polaris.provider
+    consumer = polaris.consumer
+    skill = polaris.skill
+```
+
+The factory owns and closes only the context it creates. It disables stat
+reporting and the provider lossless lifecycle, writes the connector token, and
+maps every discovery host to the Skill endpoint on port 8094 unless
+`skill_address` is explicit. A context passed through `sdk_context` is borrowed
+unchanged and is never destroyed by the factory.
+
+Applications that prefer environment-driven assembly can use:
+
+```python
+from polaris_ai.agentscope import PolarisAgentConfig, PolarisAgentRuntime
+
+config = PolarisAgentConfig.from_env(agent_name="weather-agent")
+async with PolarisAgentRuntime(config) as runtime:
+    loader = runtime.skill_loader
+    resolver = runtime.resolver
+    registrar = runtime.registrar
+```
+
+`POLARIS_AI_*` variables take precedence. `POLARIS_SERVER_ADDRESS`,
+`POLARIS_TOKEN`, `POLARIS_SERVICE_TOKEN`, and
+`POLARIS_SKILL_SERVER_ADDRESS` are accepted as fallbacks. Connector and service
+tokens remain separate. Passing an explicit `sdk_context` borrows it and never
+changes its configuration or ownership.
+When `skill.attach_to_agent` is true, `runtime.skill_toolkit` builds a native
+Toolkit containing the Polaris loader, and `runtime.create_agent()` attaches that
+Toolkit plus the dynamic refresh middleware.
+
+## AI Logging
+
+AI extension logging is optional and disabled for managed files by default. Set
+`ai_log_options` on the runtime to enable Polaris-managed category logs:
+
+```python
+from polaris_ai import PolarisAILogOptions
+
+runtime = PolarisAgentRuntime(
+    config,
+    log_options=core_sdk_log_options,
+    ai_log_options=PolarisAILogOptions(
+        level="info",
+        log_dir="./polaris/log/ai",
+        max_bytes=50 * 1024 * 1024,
+        backup_count=5,
+        max_age_days=30,
+        warning_throttle_seconds=30,
+    ),
+)
+```
+
+Managed logs are separated from Core SDK logs under `./polaris/log/ai` by
+default. Categories are `base`, `agentscope`, `skill`, `a2a`, `mcp`,
+`langgraph`, and `metrics`. Each active runtime writes files such as
+`base/polaris-ai-base-<clientId>.log`; files are created on first use. Category
+files rotate at 50MB, keep five backups, retain backups for 30 days, and use
+exclusive file locks.
+
+`POLARIS_AI_LOG_LEVEL` and `POLARIS_AI_LOG_PATH` are used when the corresponding
+options are not assigned. `POLARIS_AI_LOG_CAPTURE_AGENTSCOPE=true` optionally
+adds an AgentScope `"as"` logger handler for the runtime lifetime. The extension
+does not call `agentscope.setup_logger()` or replace existing AgentScope handlers.
+Because `"as"` is process-global, only one active runtime can capture it at a time.
+
+The detail policy avoids flooding high-frequency paths:
+
+- `INFO`: runtime lifecycle, Skill reference changes, A2A instance failover and MCP pool changes.
+- `DEBUG`: per-page listing, cache hits, candidate filtering, selected endpoints and retries.
+- `WARNING`: recoverable failures, deduplicated by key. The default interval is 30 seconds;
+  the next emitted warning includes the number of suppressed occurrences.
+
+## AgentScope Skill Loader
+
+```python
+import asyncio
+from agentscope.tool import Toolkit
+from polaris.api.config import init_context_by_file
+from polaris_ai.agentscope import PolarisSkillLoader
+
+async def main():
+    context = init_context_by_file("polaris.yaml")
+    try:
+        async with PolarisSkillLoader(context, namespace="default") as loader:
+            toolkit = Toolkit(skills_or_loaders=[loader])
+            print(await toolkit.get_skill_instructions())
+    finally:
+        await asyncio.to_thread(context.destroy)
+
+asyncio.run(main())
+```
+
+Published loading uses 50-item pages, at most 100 skills, and a 30-second list
+cache. `names=["weather"]` skips listing. `service_name="weather-agent"` loads
+only that service's mounted skills. Mount identities are `namespace:skillName`,
+split at the first colon; other namespaces are skipped. Version precedence is
+mounted version, configured `version`, then the server's active version.
+
+ZIPs include `SKILL.md` and assets. Both flat archives and a single skill folder
+are accepted; traversal, absolute paths, links, conflicting entries and multiple
+skill roots are rejected. Maximum archive/expanded size is 64 MiB and the entry
+limit is 2048. Skills live in temporary directories until the loader closes.
+Successful loads with an explicit version are cached by name/version. A blank
+version is an active-version alias: it is revalidated and materialized under
+the server-returned version. Middleware instances sharing one loader also
+share one Toolkit snapshot, so agents created from the same runtime see the
+latest successful refresh.
+Persistent offline fallback is provided by the SDK, not a second adapter cache.
+Published list errors propagate; an individual failed download is logged and
+skipped. Empty mount tables are re-read on the next call.
+`async_list_skill_names()` refreshes references without downloading ZIPs, and
+mounted `async_skill_exists()` checks only the mount table. A `400202` response
+raises `PolarisSkillNotFoundError`. The loader exposes `source`, `location`,
+`get_repository_info()`, and its read-only identity.
+
+`list_skills()` follows AgentScope's asynchronous interface. Explicit single-skill
+loading is `async_get_skill()`. `close()` and `async_close()` remove temporary assets.
+
+## A2A
+
+```python
+from polaris_ai.agentscope import A2ATransport, PolarisA2ARegistrar, PolarisA2AResolver
+from agentscope.agent import A2AAgent
+
+# card is the native a2a.types.AgentCard for an already listening server.
+async with PolarisA2ARegistrar(context, service_token="service-token") as registrar:
+    await registrar.async_register(card, [A2ATransport("10.0.0.1", 8080)])
+    async with PolarisA2AResolver(context) as resolver:
+        remote_card = await resolver.async_resolve(card.name)
+        async with A2AAgent(remote_card) as agent:
+            reply = await agent.reply(message)
+```
+
+Each transport becomes a Polaris instance. Metadata includes `ai-agent-name`,
+`a2a.agent.card`, `a2a.transport` and `a2a.path`; TLS selects `http` or `https`.
+Automatic heartbeat and re-registration use the SDK's `register_instance` with a
+5-second TTL. `service_token` is used for registration, heartbeats and
+deregistration, is distinct from the connector token, and may be empty when the
+server permits unauthenticated registration. The SDK's `bindIP` is not a business
+host.
+
+Partial registration failure rolls back only that call's created instances.
+Failed deregistrations stay in `registrar.registered`, so another `close()` can
+retry. Cancelled registration waits for in-flight SDK work and rolls back its
+successes. A closed registrar accepts further cleanup, but no new registrations.
+`PolarisA2AServerRegistration` waits for `server_ready` before registration and
+deregisters on normal or exceptional exit, replacing the Java Server / Spring
+lifecycle assembly.
+
+The resolver refreshes discovery on every lookup and stays on the selected
+healthy `host:port`. It sees card updates in place and switches when that instance
+is unhealthy, isolated, absent or has invalid metadata. Successful empty results
+raise `AgentCardNotFoundError`; SDK discovery errors reuse a previously decoded
+card. The card's advertised URLs are preserved. Configure each server's card
+with its externally reachable endpoints.
+
+`PolarisA2AAgent` wraps the native AgentScope `A2AAgent`. It resolves once,
+reuses the client for later turns, and rebuilds it after an explicit
+`invalidate()` or a network failure that occurs before any response event is
+delivered. Business errors are propagated without switching instances. Streaming
+does not retry after an event has already been emitted.
+
+Long-lived Skill-backed Agents can add `PolarisDynamicSkillMiddleware(loader)`.
+It refreshes the loader before each reply, honors the loader's refresh interval,
+and continues with the last successful state when Polaris is unavailable.
+
+## MCP
+
+```python
+from polaris_ai.agentscope import PolarisMCPClientPool, PolarisMCPResolver
+
+resolver = PolarisMCPResolver(context, "default")
+client = await resolver.async_create_client("search-mcp")
+
+async with PolarisMCPClientPool(resolver, "search-mcp") as pool:
+    selected = pool.choose_client()
+```
+
+The resolver reads standard MCP instance metadata, validates the protocol, builds
+an AgentScope `HttpMCPConfig`, and maps disabled contract Tools to
+`MCPClient.disable_tools`. Streamable HTTP is stateless; SSE is connected as a
+stateful client. The pool watches Polaris changes and reconciles clients.
+MCP Tool calls automatically report the original Tool name as method and
+`instance_type="mcp"`. A2A replies report `message/send` with
+`instance_type="a2a"`; native A2A timeout errors are reported as timeouts.
+
+`build_agent_card()` and `PolarisAgentCardTemplate` construct native A2A cards
+with protocol, Skills, streaming capability, and input/output modes.
+
+MCP-aware applications can enable the resolver with `POLARIS_AI_MCP_ENABLED=true`
+and use `POLARIS_AI_MCP_PROTOCOL_VERSION`, `POLARIS_AI_MCP_SCHEME`,
+`POLARIS_AI_MCP_TIMEOUT`, `POLARIS_AI_MCP_HEADERS`,
+`POLARIS_AI_MCP_FILTER_CONTRACT`, `POLARIS_AI_MCP_CALLER_SERVICE`, and
+`POLARIS_AI_MCP_LABELS`.
+
+Ordinary A2A method names are synchronous; `async_` names are asynchronous.
+Skill and A2A adapters borrow `SDKContext`; `PolarisAgentContext` is the only
+component that can own one. Close adapters before destroying a shared context.
+Configuration remains in `polaris.yaml` or SDK `Configuration` objects; framework
+settings are code options.
+
+## LangGraph
+
+```python
+from polaris_ai.langgraph import (
+    LangGraphTransport,
+    PolarisLangGraphContext,
+    PolarisLangGraphRegistrar,
+    PolarisLangGraphResolver,
+    PolarisRemoteGraph,
+)
+
+with PolarisLangGraphContext.from_address(
+    "127.0.0.1:8091",
+    "production",
+) as polaris, PolarisLangGraphRegistrar(
+    polaris.context,
+    "production",
+) as registrar, PolarisLangGraphResolver(
+    polaris.context,
+    "production",
+) as resolver:
+    registrar.register(
+        "review-service",
+        [LangGraphTransport("10.0.0.8", 8123, "/api", graph_id="review-graph")],
+    )
+    with PolarisRemoteGraph(
+        resolver,
+        "review-graph",
+        service="review-service",
+    ) as graph:
+        result = graph.invoke(
+            {"messages": []},
+            {"configurable": {"thread_id": "thread-1"}},
+        )
+```
+
+The registrar writes `langgraph.graph-id`, `langgraph.path`, and
+`langgraph.protocol` metadata to an ordinary Polaris instance. The resolver
+selects a healthy, non-isolated instance for the requested graph, prefers the
+previous `host:port`, and reuses the last endpoint when discovery temporarily
+fails.
+
+`PolarisRemoteGraph` exposes `invoke`, `ainvoke`, `stream`, and `astream`.
+Each call refreshes discovery and reports `instance_type="langgraph"` to Polaris
+without changing LangGraph's result or exception. The native `RemoteGraph`
+client is reused until the selected URL changes.
+
+`PolarisLangGraphConfig.from_env()` reads `POLARIS_AI_LANGGRAPH_*` first and
+accepts `POLARIS_SERVER_ADDRESS`, `POLARIS_TOKEN`,
+`POLARIS_SERVICE_TOKEN`, and `POLARIS_NAMESPACE` as fallbacks.
+
+## Validation
+
+```bash
+uv run python -m pytest
+uv build
+./examples/verify.sh
+./examples/verify.sh --only agentscope/a2a/skill
+./examples/verify.sh --only agentscope/mcp
+./examples/verify_e2e.sh --only agentscope/a2a
+```
+
+Tests use real AgentScope Toolkit and A2A types, public Polaris API wrappers and
+a deterministic SDK engine. The A2A transport test exercises the official server
+routes, JSON-RPC/SSE and `A2AAgent` through an in-process HTTP transport. These
+tests do not constitute a commercial Polaris server integration test.
+
+Offline example verification uses real SDK contexts and AgentScope, replacing
+only Polaris RPC calls. Real-registry verification is explicitly enabled through
+`verify_e2e.sh`. See [examples/test.md](examples/test.md) for prerequisites,
+per-run logs, assertions and cleanup, and [AgentScope examples](examples/agentscope/README.md)
+for manual commands. Real MCP Server E2E, remote controller governance, and
+Skill write operations remain outside the current example coverage.

polaris_python_ai-0.0.1.dev2/README-zh.md

@@ -0,0 +1,286 @@
+# polaris-python-ai
+
+面向 Python AI 框架的北极星扩展。本仓库只发布一个 distribution
+`polaris-python-ai`，通过可选 extras 提供 A2A、AgentScope、MCP 和 LangGraph
+适配，公开导入名统一为 `polaris_ai`，底层调用 `polaris-python` 公开 API。
+
+## 安装
+
+使用 Python 3.12 或更高版本，在本项目根目录执行：
+
+```bash
+uv sync --all-extras
+uv run python -m pytest
+```
+
+相邻 `polaris-python` 通过 `[tool.uv.sources]` 参与本地解析；发布 wheel
+只声明版本范围。
+
+通过 extras 安装对应适配器：
+
+```bash
+pip install "polaris-python-ai[a2a]"
+pip install "polaris-python-ai[agentscope]"
+pip install "polaris-python-ai[langgraph]"
+pip install "polaris-python-ai[mcp]"
+```
+
+单版本文件、Snapshot 和 Release tag 见 [docs/version-release.md](docs/version-release.md)。
+
+完整功能与配置见 [docs/configuration.md](docs/configuration.md)，包含 Core SDK、
+Skill、A2A、MCP 和 AI 日志配置。
+
+AgentScope、A2A 和 LangGraph 为可选依赖，基础包导入不会加载它们。当前验证组合为
+AgentScope 2.0.10、A2A SDK 1.2.3 和 LangGraph 1.x，A2A 使用官方兼容解析器读取
+Java 卡片 JSON。
+
+## 共享 AgentScope Context
+
+```python
+from polaris_ai.agentscope import PolarisAgentContext
+
+with PolarisAgentContext.from_address("127.0.0.1:8091", "default") as polaris:
+    provider = polaris.provider
+    consumer = polaris.consumer
+    skill = polaris.skill
+```
+
+工厂只拥有并关闭自己创建的 context。它会关闭 stat 上报、写入 connector token，
+并关闭 provider 无损上下线，然后把每个发现地址的 host 映射到 8094 端口的 Skill
+地址；显式 `skill_address` 优先。通过 `sdk_context` 传入的 context 保持原配置，
+且不会被工厂销毁。
+
+应用侧也可以使用环境变量装配：
+
+```python
+from polaris_ai.agentscope import PolarisAgentConfig, PolarisAgentRuntime
+
+config = PolarisAgentConfig.from_env(agent_name="weather-agent")
+async with PolarisAgentRuntime(config) as runtime:
+    loader = runtime.skill_loader
+    resolver = runtime.resolver
+    registrar = runtime.registrar
+```
+
+`POLARIS_AI_*` 变量优先；`POLARIS_SERVER_ADDRESS`、`POLARIS_TOKEN`、
+`POLARIS_SERVICE_TOKEN` 和 `POLARIS_SKILL_SERVER_ADDRESS` 作为回退。connector
+token 与 service token 保持分离。显式传入 `sdk_context` 时只借用，不改配置、
+不接管生命周期。
+`skill.attach_to_agent` 为 true 时，`runtime.skill_toolkit` 会创建包含 Polaris
+loader 的原生 Toolkit；`runtime.create_agent()` 会同时接入 Toolkit 和动态刷新
+Middleware。
+
+## AI 日志
+
+AI 扩展默认不创建 Polaris 管理的日志文件。需要由 Runtime 管理分类日志时，
+传入独立的 `ai_log_options`：
+
+```python
+from polaris_ai import PolarisAILogOptions
+
+runtime = PolarisAgentRuntime(
+    config,
+    log_options=core_sdk_log_options,
+    ai_log_options=PolarisAILogOptions(
+        level="info",
+        log_dir="./polaris/log/ai",
+        max_bytes=50 * 1024 * 1024,
+        backup_count=5,
+        max_age_days=30,
+        warning_throttle_seconds=30,
+    ),
+)
+```
+
+默认与 Core SDK 日志分开存放在 `./polaris/log/ai`。分类为 `base`、
+`agentscope`、`skill`、`a2a`、`mcp`、`langgraph` 和 `metrics`，文件按首次使用创建，例如
+`base/polaris-ai-base-<clientId>.log`。每类默认 50MB 滚动、保留 5 份和 30 天，
+并使用跨进程独占文件锁。
+
+代码未显式赋值的 level 和 path 会读取 `POLARIS_AI_LOG_LEVEL`、
+`POLARIS_AI_LOG_PATH`。`POLARIS_AI_LOG_CAPTURE_AGENTSCOPE=true` 可以在 Runtime
+生命周期内桥接 AgentScope `"as"` logger，但不会调用 `agentscope.setup_logger()`
+或替换 AgentScope 原有 handler。由于 `"as"` 是进程级 logger，同一进程同一时刻只能
+有一个活动 Runtime 捕获它。
+
+详细程度策略：
+
+- `INFO`：Runtime 生命周期、Skill 引用变化、A2A 实例切换和 MCP 池成员变化。
+- `DEBUG`：分页、缓存命中、候选过滤、选中地址和重试等高频细节。
+- `WARNING`：可恢复错误按 key 聚合，默认 30 秒内只输出一次；下一次输出会带上被抑制次数。
+
+## Skill 加载
+
+```python
+import asyncio
+from agentscope.tool import Toolkit
+from polaris.api.config import init_context_by_file
+from polaris_ai.agentscope import PolarisSkillLoader
+
+async def main():
+    context = init_context_by_file("polaris.yaml")
+    try:
+        async with PolarisSkillLoader(context, namespace="default") as loader:
+            toolkit = Toolkit(skills_or_loaders=[loader])
+            print(await toolkit.get_skill_instructions())
+    finally:
+        await asyncio.to_thread(context.destroy)
+
+asyncio.run(main())
+```
+
+默认每页 50 条，最多加载 100 个，列表缓存 30 秒。指定 `names=["weather"]`
+直接下载，跳过列表；指定 `service_name="weather-agent"` 只加载该服务挂载的 Skill。
+挂载名称 `namespace:skillName` 按第一个冒号切分，其他命名空间跳过，重复名称保留第一条。
+版本优先级为挂载版本、构造时指定的 `version`、服务端 active 版本。
+
+显式版本下载成功后按名称和版本缓存；空版本表示服务端 active 版本，会重新验证，并按服务端
+返回的实际版本物化缓存。共享同一个 loader 的多个动态刷新中间件共享一份 Toolkit 快照，
+同一 Runtime 创建的多个 Agent 都会看到最新成功刷新。
+失败不会缓存。列表失败直接抛错，单个下载失败会记录日志并跳过，下次重试。空的已发布列表缓存
+30 秒，空挂载表下次重新查询。
+`async_list_skill_names()` 只刷新引用列表，不下载 ZIP；挂载模式的
+`async_skill_exists()` 只检查挂载表。服务端返回 `400202` 时抛
+`PolarisSkillNotFoundError`。loader 暴露 `source`、`location`、
+`get_repository_info()` 和只读标识。
+
+下载 ZIP 中的 `SKILL.md` 和资源解压到临时目录，支持平铺或单一顶层 Skill 目录。
+拒绝越界 / 绝对路径、链接、冲突文件和多 Skill 根目录，压缩与解压大小上限 64 MiB，
+最多 2048 项。`close()` / `async_close()` 清理临时资源；持久化和网络故障降级由 SDK 负责。
+`list_skills()` 遵循 AgentScope 原生异步接口，单个 Skill 使用 `async_get_skill()`。
+
+## A2A 注册与发现
+
+```python
+from agentscope.agent import A2AAgent
+from polaris_ai.agentscope import A2ATransport, PolarisA2ARegistrar, PolarisA2AResolver
+
+# card 为已启动服务的 a2a.types.AgentCard；message 为 AgentScope 消息。
+async with PolarisA2ARegistrar(context, service_token="service-token") as registrar:
+    await registrar.async_register(card, [A2ATransport("10.0.0.1", 8080)])
+    async with PolarisA2AResolver(context) as resolver:
+        remote_card = await resolver.async_resolve(card.name)
+        async with A2AAgent(remote_card) as agent:
+            reply = await agent.reply(message)
+```
+
+每个 transport 注册一个普通实例，写入 `ai-agent-name`、`a2a.agent.card`、
+`a2a.transport` 和 `a2a.path`。自动心跳和实例不存在重注册复用 SDK，TTL 默认 5 秒。
+`service_token` 用于注册、心跳和反注册，它与 connector token 是两个配置；可为空，
+由服务端决定是否接受无鉴权注册。
+业务实例地址由 `A2ATransport.host` 指定，SDK `bindIP` 不作为业务实例 host。
+
+部分注册失败回滚本次成功实例；反注册失败记录保留在 `registered`，可再次 `close()` 重试。
+取消注册会等待在途请求完成并回滚，关闭后禁止新注册。
+`PolarisA2AServerRegistration` 可等待 `server_ready` 事件后再注册，退出或异常时
+统一反注册，用于替代 Java Server / Spring 的生命周期装配。
+
+每次解析重新发现，按健康 `host:port` 保持粘性并读取最新卡片；实例移除、不健康、隔离或
+卡片失效后切换。SDK 查询异常时复用此前成功卡片；成功空结果抛 `AgentCardNotFoundError`。
+保留卡片声明的 URL，服务端需提供真实可访问的地址。
+
+A2A 普通名称为同步接口，`async_` 前缀为异步接口；通用 A2A 入口也可从 `polaris_ai.a2a`
+导入。Skill 与 A2A 适配器借用 `SDKContext`，只有 `PolarisAgentContext` 可以拥有
+context。关闭时只释放自身资源，应用统一销毁共享 context。
+SDK 配置继续使用 `polaris.yaml` 或 `Configuration`，框架参数通过代码指定。
+
+`PolarisA2AAgent` 包装原生 AgentScope `A2AAgent`：首次调用解析卡片，后续轮次复用
+客户端；显式 `invalidate()` 或尚未输出任何事件的网络错误会重新解析并重建客户端。
+业务错误直接抛出，不切换实例；流式调用已经输出事件后不会重试。
+
+长生命周期 Skill Agent 可加入 `PolarisDynamicSkillMiddleware(loader)`。它会在每轮
+回复前刷新 loader，遵循刷新间隔；Polaris 不可用时记录警告并继续使用最近一次成功状态。
+
+## MCP
+
+```python
+from polaris_ai.agentscope import PolarisMCPClientPool, PolarisMCPResolver
+
+resolver = PolarisMCPResolver(context, "default")
+client = await resolver.async_create_client("search-mcp")
+
+async with PolarisMCPClientPool(resolver, "search-mcp") as pool:
+    selected = pool.choose_client()
+```
+
+Resolver 读取标准 MCP 实例 metadata、校验协议、构造 AgentScope `HttpMCPConfig`，
+并把契约中禁用的 Tool 写入 `MCPClient.disable_tools`。Streamable HTTP 使用无状态
+客户端，SSE 使用有状态连接。连接池通过 watch 感知实例增删并同步重建客户端。
+MCP Tool 调用自动以原 Tool 名作为 method、`instance_type="mcp"` 上报；A2A 回复自动以
+`message/send` 和 `instance_type="a2a"` 上报，官方 A2A 超时异常会按 timeout 上报。
+
+`build_agent_card()` 与 `PolarisAgentCardTemplate` 可构造原生 A2A 卡片，支持协议、
+Skill、流式能力和输入输出模式。
+
+MCP 应用可通过 `POLARIS_AI_MCP_ENABLED=true` 启用 resolver，并配置
+`POLARIS_AI_MCP_PROTOCOL_VERSION`、`POLARIS_AI_MCP_SCHEME`、
+`POLARIS_AI_MCP_TIMEOUT`、`POLARIS_AI_MCP_HEADERS`、
+`POLARIS_AI_MCP_FILTER_CONTRACT`、`POLARIS_AI_MCP_CALLER_SERVICE` 和
+`POLARIS_AI_MCP_LABELS`。
+
+## LangGraph
+
+```python
+from polaris_ai.langgraph import (
+    LangGraphTransport,
+    PolarisLangGraphContext,
+    PolarisLangGraphRegistrar,
+    PolarisLangGraphResolver,
+    PolarisRemoteGraph,
+)
+
+with PolarisLangGraphContext.from_address(
+    "127.0.0.1:8091",
+    "production",
+) as polaris, PolarisLangGraphRegistrar(
+    polaris.context,
+    "production",
+) as registrar, PolarisLangGraphResolver(
+    polaris.context,
+    "production",
+) as resolver:
+    registrar.register(
+        "review-service",
+        [LangGraphTransport("10.0.0.8", 8123, "/api", graph_id="review-graph")],
+    )
+    with PolarisRemoteGraph(
+        resolver,
+        "review-graph",
+        service="review-service",
+    ) as graph:
+        result = graph.invoke(
+            {"messages": []},
+            {"configurable": {"thread_id": "thread-1"}},
+        )
+```
+
+注册器把 `langgraph.graph-id`、`langgraph.path` 和 `langgraph.protocol` 写入普通
+Polaris 实例。Resolver 只选择对应 graph 的健康、未隔离实例，优先复用上次
+`host:port`；发现临时失败时复用最近一次成功端点。
+
+`PolarisRemoteGraph` 提供 `invoke`、`ainvoke`、`stream` 和 `astream`。每次调用都会
+刷新发现，并以 `instance_type="langgraph"` 上报结果，不改变 LangGraph 的返回值或
+异常。原生 `RemoteGraph` 客户端在 URL 不变时复用，切换实例后重建。
+
+`PolarisLangGraphConfig.from_env()` 优先读取 `POLARIS_AI_LANGGRAPH_*`，并接受
+`POLARIS_SERVER_ADDRESS`、`POLARIS_TOKEN`、`POLARIS_SERVICE_TOKEN` 和
+`POLARIS_NAMESPACE` 作为回退。
+
+## 验证
+
+```bash
+uv run python -m pytest
+uv build
+./examples/verify.sh
+./examples/verify.sh --only agentscope/a2a/skill
+./examples/verify.sh --only agentscope/mcp
+./examples/verify_e2e.sh --only agentscope/a2a
+```
+
+已验证原生 Toolkit、官方 A2A 类型、公开 SDK 包装器，以及本地 JSON-RPC/SSE 调用。
+单元测试使用确定性 SDK 替身。examples 离线集成测试使用真实 SDK 和 AgentScope，
+仅替换 Polaris gRPC 边界；真实注册中心验证由 verify_e2e.sh 显式运行。
+运行参数、前置资源、日志和清理见 [examples/test.md](examples/test.md)。
+可运行的已发布 Skill、挂载 Skill、A2A provider / consumer 和 Skill 驱动 A2A 示例见
+[examples/agentscope](examples/agentscope/README.md)，A2A Echo 示例无需模型密钥。
+真实 MCP Server E2E、远端 Controller 治理和 Skill 写操作暂不在当前范围。