zero-agent-core 0.2.0__py3-none-any.whl

agent_core/workflow/state_machine.py

@@ -0,0 +1,427 @@
+"""手写状态机调度器。
+
+核心概念：
+- State: 字典，存储所有运行时状态
+- Node: 可调用函数，接受 state，返回更新字典
+- Edge: 节点间的转移规则（固定边 / 条件边）
+- Execution: 从 START 开始，按边的规则依次执行节点，直到 END
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+from copy import deepcopy
+from dataclasses import dataclass
+from inspect import isawaitable
+from typing import Any
+
+from agent_core.errors import StateMachineError
+
+logger = logging.getLogger(__name__)
+
+# 特殊节点名称
+START = "__start__"
+END = "__end__"
+
+# 节点函数签名
+NodeFunc = Callable[[dict[str, Any]], dict[str, Any] | Awaitable[dict[str, Any]]]
+# 条件路由函数签名：返回下一个节点名称
+ConditionalRouteFunc = Callable[[dict[str, Any]], str | Awaitable[str]]
+StepCallback = Callable[
+    [str, str, dict[str, Any], int],
+    Awaitable[None] | None,
+]
+NodeStartCallback = Callable[["NodeExecutionContext", dict[str, Any]], Awaitable[None] | None]
+IdempotencyKeyFactory = Callable[[str, int], str]
+
+
+@dataclass(frozen=True)
+class NodeExecutionPolicy:
+    """单个工作流节点的超时和重试策略。"""
+
+    timeout_seconds: float | None = None
+    max_attempts: int = 1
+    backoff_initial_seconds: float = 0.0
+    backoff_multiplier: float = 2.0
+    backoff_max_seconds: float = 30.0
+    retry_exceptions: tuple[type[Exception], ...] = (Exception,)
+    idempotent: bool = False
+
+    def __post_init__(self) -> None:
+        if self.timeout_seconds is not None and self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds 必须大于 0")
+        if self.max_attempts <= 0:
+            raise ValueError("max_attempts 必须大于 0")
+        if self.max_attempts > 1 and not self.idempotent:
+            raise ValueError("开启节点重试前必须声明 idempotent=True")
+        if self.backoff_initial_seconds < 0 or self.backoff_max_seconds < 0:
+            raise ValueError("退避时间不能小于 0")
+        if self.backoff_multiplier < 1:
+            raise ValueError("backoff_multiplier 不能小于 1")
+
+
+@dataclass(frozen=True)
+class NodeExecutionContext:
+    """当前节点调用可读取的执行上下文。"""
+
+    node_name: str
+    attempt: int
+    idempotency_key: str
+
+
+_CURRENT_NODE_EXECUTION: ContextVar[NodeExecutionContext | None] = ContextVar(
+    "agent_core_node_execution",
+    default=None,
+)
+
+
+def current_node_execution() -> NodeExecutionContext | None:
+    """返回当前节点执行上下文，供外部副作用传递幂等键。"""
+
+    return _CURRENT_NODE_EXECUTION.get()
+
+
+class WorkflowPause(Exception):
+    """节点主动暂停工作流，等待外部条件满足后恢复。"""
+
+    def __init__(self, reason: str, data: dict[str, Any] | None = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.data = dict(data or {})
+
+
+class StateMachine:
+    """手写状态机调度器。
+
+    功能：
+    1. 注册节点（node）和边（edge）
+    2. 从 START 开始执行，按照边的规则转移
+    3. 每执行一个节点，将返回值合并到 state
+    4. 条件边根据当前 state 动态决定下一个节点
+    5. 到达 END 或超过最大步数时停止
+    """
+
+    def __init__(self, *, max_steps: int = 50) -> None:
+        """
+        Args:
+            max_steps: 最大执行步数，防止死循环。
+        """
+        self._nodes: dict[str, NodeFunc] = {}
+        self._node_policies: dict[str, NodeExecutionPolicy] = {}
+        # 固定边：node_name -> next_node_name
+        self._edges: dict[str, str] = {}
+        # 条件边：node_name -> route_func
+        self._conditional_edges: dict[str, ConditionalRouteFunc] = {}
+        self._conditional_targets: dict[str, tuple[str, ...]] = {}
+        self._max_steps = max_steps
+
+    def add_node(
+        self,
+        name: str,
+        func: NodeFunc,
+        *,
+        policy: NodeExecutionPolicy | None = None,
+    ) -> None:
+        """注册一个节点。
+
+        Args:
+            name: 节点名称（全局唯一）。
+            func: 节点函数，接受 state，返回更新字典。
+        """
+        if name in self._nodes:
+            raise StateMachineError(f"Node {name!r} already registered.")
+        if name in (START, END):
+            raise StateMachineError(f"Cannot register reserved node name {name!r}.")
+        self._nodes[name] = func
+        self._node_policies[name] = policy or NodeExecutionPolicy()
+
+    def add_edge(self, from_node: str, to_node: str) -> None:
+        """注册一条固定边：from_node 执行完毕后自动转移到 to_node。
+
+        Args:
+            from_node: 源节点名称。
+            to_node: 目标节点名称。
+        """
+        if from_node in self._conditional_edges:
+            raise StateMachineError(f"Node {from_node!r} already has a conditional edge.")
+        self._edges[from_node] = to_node
+
+    def add_conditional_edges(
+        self,
+        from_node: str,
+        route_func: ConditionalRouteFunc,
+        *,
+        possible_targets: list[str] | tuple[str, ...] | None = None,
+    ) -> None:
+        """注册一条条件边：from_node 执行完毕后，调用 route_func(state) 决定下一个节点。
+
+        Args:
+            from_node: 源节点名称。
+            route_func: 路由函数，接受 state，返回下一个节点名称。
+        """
+        if from_node in self._edges:
+            raise StateMachineError(f"Node {from_node!r} already has a fixed edge.")
+        self._conditional_edges[from_node] = route_func
+        self._conditional_targets[from_node] = tuple(possible_targets or ())
+
+    async def ainvoke(self, initial_state: dict[str, Any]) -> dict[str, Any]:
+        """异步执行状态机。
+
+        Args:
+            initial_state: 初始状态字典。
+
+        Returns:
+            执行完毕后的最终状态。
+
+        Raises:
+            StateMachineError: 节点不存在、超过最大步数等错误。
+        """
+        return await self.ainvoke_from(initial_state, start_node=START)
+
+    async def ainvoke_from(
+        self,
+        initial_state: dict[str, Any],
+        *,
+        start_node: str = START,
+        on_step: StepCallback | None = None,
+        on_node_start: NodeStartCallback | None = None,
+        idempotency_key_factory: IdempotencyKeyFactory | None = None,
+    ) -> dict[str, Any]:
+        """从指定节点执行，并在每个节点完成后发布可持久化快照。"""
+        if start_node != START and start_node != END and start_node not in self._nodes:
+            raise StateMachineError(f"Node {start_node!r} not found.")
+        state = deepcopy(initial_state)
+        current_node = start_node
+        steps = 0
+        completed_nodes = 0
+
+        logger.info("StateMachine: starting execution from %s", current_node)
+
+        while current_node != END:
+            steps += 1
+            if steps > self._max_steps:
+                raise StateMachineError(
+                    f"StateMachine exceeded max steps ({self._max_steps}). Last node: {current_node!r}."
+                )
+
+            # 执行当前节点（START 和 END 是虚拟节点，不执行）
+            if current_node != START:
+                node_func = self._nodes.get(current_node)
+                if node_func is None:
+                    raise StateMachineError(f"Node {current_node!r} not found.")
+
+                logger.debug("StateMachine: executing node %r (step %d)", current_node, steps)
+                try:
+                    idempotency_key = (
+                        idempotency_key_factory(current_node, completed_nodes)
+                        if idempotency_key_factory is not None
+                        else f"{current_node}:{completed_nodes + 1}"
+                    )
+                    updates = await self._execute_node(
+                        current_node,
+                        node_func,
+                        state,
+                        idempotency_key=idempotency_key,
+                        on_node_start=on_node_start,
+                    )
+                    if updates:
+                        state.update(updates)
+                    completed_nodes += 1
+                except WorkflowPause:
+                    raise
+                except Exception as exc:
+                    raise StateMachineError(f"Node {current_node!r} raised exception: {exc}") from exc
+
+            # 决定下一个节点
+            next_node = await self._get_next_node(current_node, state)
+            if on_step is not None:
+                checkpoint = on_step(current_node, next_node, deepcopy(state), completed_nodes)
+                if isawaitable(checkpoint):
+                    await checkpoint
+            logger.debug("StateMachine: %r -> %r", current_node, next_node)
+            current_node = next_node
+
+        logger.info("StateMachine: execution completed in %d steps", steps)
+        return state
+
+    @property
+    def node_count(self) -> int:
+        """返回已注册的实际节点数量。"""
+        return len(self._nodes)
+
+    async def _execute_node(
+        self,
+        node_name: str,
+        node_func: NodeFunc,
+        state: dict[str, Any],
+        *,
+        idempotency_key: str,
+        on_node_start: NodeStartCallback | None,
+    ) -> dict[str, Any]:
+        policy = self._node_policies[node_name]
+        delay = policy.backoff_initial_seconds
+        for attempt in range(1, policy.max_attempts + 1):
+            context = NodeExecutionContext(
+                node_name=node_name,
+                attempt=attempt,
+                idempotency_key=idempotency_key,
+            )
+            if on_node_start is not None:
+                pending = on_node_start(context, deepcopy(state))
+                if isawaitable(pending):
+                    await pending
+            token = _CURRENT_NODE_EXECUTION.set(context)
+            try:
+                result = node_func(state)
+                if isawaitable(result):
+                    if policy.timeout_seconds is None:
+                        result = await result
+                    else:
+                        result = await asyncio.wait_for(result, timeout=policy.timeout_seconds)
+                return result
+            except WorkflowPause:
+                raise
+            except policy.retry_exceptions:
+                if attempt >= policy.max_attempts:
+                    raise
+                if delay > 0:
+                    await asyncio.sleep(delay)
+                    delay = min(
+                        policy.backoff_max_seconds,
+                        max(delay, 0.001) * policy.backoff_multiplier,
+                    )
+            finally:
+                _CURRENT_NODE_EXECUTION.reset(token)
+        raise StateMachineError(f"Node {node_name!r} exhausted retry policy.")
+
+    def describe(self) -> dict[str, Any]:
+        """返回可序列化的状态机结构，用于调试和可视化。"""
+
+        return {
+            "nodes": [
+                {
+                    "name": name,
+                    "policy": {
+                        "timeout_seconds": policy.timeout_seconds,
+                        "max_attempts": policy.max_attempts,
+                        "idempotent": policy.idempotent,
+                    },
+                }
+                for name, policy in self._node_policies.items()
+            ],
+            "edges": [
+                {"from": source, "to": target, "kind": "fixed"} for source, target in self._edges.items()
+            ],
+            "conditional_edges": [
+                {
+                    "from": source,
+                    "targets": list(self._conditional_targets.get(source, ())),
+                    "kind": "conditional",
+                }
+                for source in self._conditional_edges
+            ],
+            "max_steps": self._max_steps,
+        }
+
+    def to_mermaid(self, *, direction: str = "TD") -> str:
+        """把状态机导出为 Mermaid flowchart。"""
+
+        normalized_direction = direction.upper()
+        if normalized_direction not in {"TD", "TB", "BT", "LR", "RL"}:
+            raise ValueError(f"不支持的 Mermaid 方向：{direction}")
+        names = [START, *self._nodes, END]
+        node_ids = {name: f"N{index}" for index, name in enumerate(names)}
+
+        def label(value: str) -> str:
+            return value.replace("\\", "\\\\").replace('"', "&quot;")
+
+        lines = [f"flowchart {normalized_direction}"]
+        lines.append(f'    {node_ids[START]}(["START"])')
+        for name in self._nodes:
+            lines.append(f'    {node_ids[name]}["{label(name)}"]')
+        lines.append(f'    {node_ids[END]}(["END"])')
+        for source, target in self._edges.items():
+            if source in node_ids and target in node_ids:
+                lines.append(f"    {node_ids[source]} --> {node_ids[target]}")
+        for index, source in enumerate(self._conditional_edges):
+            targets = self._conditional_targets.get(source, ())
+            if targets:
+                for target in targets:
+                    if target in node_ids:
+                        lines.append(f'    {node_ids[source]} -. "条件" .-> {node_ids[target]}')
+            else:
+                dynamic_id = f"D{index}"
+                lines.append(f'    {dynamic_id}{{"动态路由"}}')
+                lines.append(f'    {node_ids[source]} -. "条件" .-> {dynamic_id}')
+        return "\n".join(lines)
+
+    async def _get_next_node(self, current_node: str, state: dict[str, Any]) -> str:
+        """根据边的规则决定下一个节点。
+
+        优先级：
+        1. 条件边（如果存在）
+        2. 固定边（如果存在）
+        3. 默认：END（终止执行）
+        """
+        # 条件边
+        if current_node in self._conditional_edges:
+            route_func = self._conditional_edges[current_node]
+            try:
+                next_node = route_func(state)
+                return await next_node if isawaitable(next_node) else next_node
+            except Exception as exc:
+                raise StateMachineError(
+                    f"Conditional route from {current_node!r} raised exception: {exc}"
+                ) from exc
+
+        # 固定边
+        if current_node in self._edges:
+            return self._edges[current_node]
+
+        # 默认终止
+        return END
+
+
+class StateMachineBuilder:
+    """状态机构建器（类似 StateGraph 的接口风格）。"""
+
+    def __init__(self, *, max_steps: int = 50) -> None:
+        self._machine = StateMachine(max_steps=max_steps)
+
+    def add_node(
+        self,
+        name: str,
+        func: NodeFunc,
+        *,
+        policy: NodeExecutionPolicy | None = None,
+    ) -> StateMachineBuilder:
+        """添加节点（链式调用）。"""
+        self._machine.add_node(name, func, policy=policy)
+        return self
+
+    def add_edge(self, from_node: str, to_node: str) -> StateMachineBuilder:
+        """添加固定边（链式调用）。"""
+        self._machine.add_edge(from_node, to_node)
+        return self
+
+    def add_conditional_edges(
+        self,
+        from_node: str,
+        route_func: ConditionalRouteFunc,
+        *,
+        possible_targets: list[str] | tuple[str, ...] | None = None,
+    ) -> StateMachineBuilder:
+        """添加条件边（链式调用）。"""
+        self._machine.add_conditional_edges(
+            from_node,
+            route_func,
+            possible_targets=possible_targets,
+        )
+        return self
+
+    def build(self) -> StateMachine:
+        """构建并返回状态机实例。"""
+        return self._machine

zero_agent_core-0.2.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.5
+Name: zero-agent-core
+Version: 0.2.0
+Summary: 零外部平台绑定的 Python Agent 运行时内核
+Project-URL: Homepage, https://github.com/qiuzixu/agent-core
+Project-URL: Documentation, https://github.com/qiuzixu/agent-core/tree/main/docs
+Project-URL: Repository, https://github.com/qiuzixu/agent-core
+Project-URL: Issues, https://github.com/qiuzixu/agent-core/issues
+Author: qiuzixu
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: acp,agent,function-calling,llm,mcp,react
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.13
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1,>=0.40; extra == 'anthropic'
+Provides-Extra: chroma
+Requires-Dist: chromadb<2,>=1.0; extra == 'chroma'
+Provides-Extra: dev
+Requires-Dist: mkdocs-material<10,>=9.7; extra == 'dev'
+Requires-Dist: mypy<2,>=1.18; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
+Requires-Dist: pytest<10,>=9; extra == 'dev'
+Requires-Dist: ruff<1,>=0.14; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai<2,>=1.0; extra == 'gemini'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
+Provides-Extra: models
+Requires-Dist: anthropic<1,>=0.40; extra == 'models'
+Requires-Dist: dashscope<2,>=1.27; extra == 'models'
+Requires-Dist: google-genai<2,>=1.0; extra == 'models'
+Requires-Dist: httpx<1,>=0.28; extra == 'models'
+Requires-Dist: openai<3,>=1.0; extra == 'models'
+Provides-Extra: openai
+Requires-Dist: httpx<1,>=0.28; extra == 'openai'
+Requires-Dist: openai<3,>=1.0; extra == 'openai'
+Provides-Extra: pgvector
+Requires-Dist: asyncpg<1,>=0.30; extra == 'pgvector'
+Provides-Extra: production
+Requires-Dist: asyncpg<1,>=0.30; extra == 'production'
+Provides-Extra: qwen
+Requires-Dist: dashscope<2,>=1.27; extra == 'qwen'
+Description-Content-Type: text/markdown
+
+# Handwritten Agent Core
+
+<!-- PyPI 徽章（发布到 PyPI 后取消此行注释即生效）：
+[![PyPI version](https://img.shields.io/pypi/v/zero-agent-core)](https://pypi.org/project/zero-agent-core/)
+[![Python versions](https://img.shields.io/pypi/pyversions/zero-agent-core)](https://pypi.org/project/zero-agent-core/)
+-->
+[![Core CI](https://github.com/qiuzixu/agent-core/actions/workflows/ci.yml/badge.svg)](https://github.com/qiuzixu/agent-core/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+[![Python 3.13](https://img.shields.io/badge/Python-3.13-blue.svg)](https://www.python.org/)
+
+一个零外部平台绑定的 Python Agent 运行时内核。项目从头实现 Agent Loop、
+工具调用、MCP、Skill、上下文压缩、持久化恢复、工作流、HITL、多模型适配和 ACP 协议。
+
+> 当前版本为 `0.2.0` Alpha，要求 Python 3.13。公开 API 在 `0.x` 阶段仍可能调整。
+
+## 主要能力
+
+- 普通和流式 ReAct Agent Loop，本轮多个工具并发执行；
+- Function Calling、MCP stdio 客户端和声明式 Skill；
+- OpenAI、Anthropic、Gemini、Ollama，以及自定义模型 Provider；
+- JSON Schema 结构化输出，以及模型限流、并发、超时、熔断和 fallback；
+- Middleware、Guardrails、HITL、调用统计和可选 OpenTelemetry；
+- 生命周期 Callback、统一 RunEvent 和流式增量事件；
+- Document/Blob、文本加载与切分、Embedding/Retriever/VectorStore 协议；
+- 可选 `zero-agent-core-mineru` 扩展包解析 PDF、扫描件和复杂版面；
+- 可选 `zero-agent-core-embeddings` 扩展包接入 OpenAI、Gemini 和 Ollama；
+- 可选 `zero-agent-core-multi-agent` 扩展包编排多个独立 Agent；
+- 内存、Chroma、pgvector 向量存储，关键词检索以及用户/租户/namespace 隔离；
+- 带类型白名单、Schema 版本和迁移函数的安全 JSON 序列化；
+- 安全文本/聊天 Prompt 模板、消息占位符、partial 和版本管理；
+- 基于模型上下文用量的摘要压缩、工具结果瘦身和 spill；
+- Run、事件、幂等键、Worker 租约、心跳、重启恢复和取消；
+- Checkpoint 历史、回滚、节点重试/幂等/pending write 和 Mermaid 状态机导出；
+- 会话、长期上下文、审批、模型选择的内存、SQLite、PostgreSQL 存储；
+- 跨会话长期记忆、TTL、版本冲突、关键词检索和访问隔离；
+- 用户、租户和管理员访问上下文；
+- ACP JSON-RPC/stdio 服务端适配。
+
+完整边界见[已实现能力](docs/CAPABILITIES.md)，模块和应用调用关系见
+[系统架构](docs/ARCHITECTURE.md)。
+
+## 快速开始
+
+从 PyPI 安装（导入名是 `agent_core`，不受发行名更名影响）：
+
+```bash
+pip install zero-agent-core
+```
+
+推荐使用 [uv](https://docs.astral.sh/uv/)（与仓库其它项目一致，自动创建 `.venv`）：
+
+```bash
+cd agent-core
+uv sync --all-extras
+uv run python examples/starter/starter_agent.py   # 五分钟上手：单文件最小完整示例
+uv run python examples/basic_agent.py             # 更小的最小示例
+```
+
+`uv sync` 默认安装项目本体与 `dev` 依赖组；按需追加 extra：
+
+```bash
+uv sync --extra openai            # 单个 extra
+uv sync --extra models,mcp,production
+uv sync --all-extras              # 全部可选依赖
+```
+
+不用 uv 时也可以用标准 venv + pip：
+
+```bash
+cd agent-core
+python -m venv .venv
+python -m pip install -e ".[dev]"
+python examples/starter/starter_agent.py
+```
+
+`examples/starter/starter_agent.py` 与 `examples/basic_agent.py` 都使用离线演示模型，
+不需要 API Key 或外部服务。五分钟上手路径（安装 → 运行 → 换真实模型 → 加工具 →
+加工作流）见 [examples/starter/README.md](examples/starter/README.md)。
+
+真实模型按需安装（uv 用户把 `pip install` 换成 `uv pip install`，或用上面的
+`uv sync --extra ...`）：
+
+```bash
+pip install "zero-agent-core[openai]"
+pip install "zero-agent-core[anthropic]"
+pip install "zero-agent-core[gemini]"
+pip install "zero-agent-core[models,mcp,production]"
+pip install "zero-agent-core[chroma]"    # 本地持久化向量存储
+pip install "zero-agent-core[pgvector]"  # PostgreSQL 向量存储
+pip install zero-agent-core-mineru       # 独立 MinerU 文档解析扩展包
+pip install "zero-agent-core-embeddings[openai]"
+pip install "zero-agent-core-embeddings[gemini]"
+pip install "zero-agent-core-embeddings[ollama]"
+pip install zero-agent-core-multi-agent  # 独立多 Agent 编排扩展包
+```
+
+最小组装方式：
+
+```python
+from agent_core import ReActAgent, ToolExecutor, ToolRegistry, create_model_provider
+
+model = create_model_provider(settings)
+
+tools = ToolRegistry()
+tools.register("lookup", lookup, "查询数据")
+
+agent = ReActAgent(
+    llm=model,
+    tool_executor=ToolExecutor(tools),
+    system_prompt="你是一个助手。",
+    tool_definitions=tools.build_tool_definitions(),
+)
+
+answer = await agent.run("查询数据")
+```
+
+应用可以通过路径依赖使用尚未发布的 Core。**uv 0.11 起 path 源默认非 editable**，
+不加 `editable = true` 时 site-packages 里是同步时刻的快照，Core 源码更新后应用
+会用到旧代码（症状是新符号 ImportError）：
+
+```toml
+[project]
+dependencies = ["zero-agent-core"]
+
+[tool.uv.sources]
+zero-agent-core = { path = "../agent-core", editable = true }
+```
+
+随后在应用目录执行 `uv sync`（多包仓库在 workspace 根执行
+`uv sync --all-packages --all-extras`）完成安装。
+
+## 文档站
+
+文档源文件位于 `docs/`，使用 Material for MkDocs：
+
+```bash
+python -m pip install mkdocs-material
+python -m mkdocs serve       # 本地预览 http://127.0.0.1:8000
+python -m mkdocs build       # 构建到 site/
+```
+
+子路径部署时设置 `DOCS_BASE`，例如 `/zero-agent-core/`。文档入口为
+[docs/index.md](docs/index.md)，包含快速开始、核心概念、模型、工具、MCP、Skill、存储、
+工作流、ACP 和公共 API 参考。
+
+## 项目边界
+
+Core 只提供框架通用能力（Agent Loop、模型适配、工具执行、会话与存储等），
+不包含任何特定业务。应用侧仍负责：
+
+- HTTP、WebSocket 或 SSE 等 API 接入；
+- 身份认证、业务授权和密钥读取；
+- 业务提示词、业务工具和业务数据模型；
+- 前端通信与外部系统集成；
+- 部署编排、监控后端和数据库运维。
+
+新 Agent 直接依赖 `agent_core`。Core 不感知、也不依赖任何具体业务域。
+
+## 开发
+
+```bash
+uv run ruff check src tests examples
+uv run pytest
+uv run mkdocs build
+uv build
+```
+
+不使用 uv 时：
+
+```bash
+python -m pip install build
+ruff check src tests examples
+pytest
+python -m mkdocs build
+python -m build
+```
+
+贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
+安全问题按 [SECURITY.md](SECURITY.md) 私密报告。首次发布前的外部配置和决策记录在
+[OPEN_SOURCE_CHECKLIST.md](OPEN_SOURCE_CHECKLIST.md)。
+
+## 许可证
+
+项目按 [Apache License 2.0](LICENSE) 发布。
+
+
+<!-- 嵌入式 Agent 内核 这个名字备选 -->