submit: yai-agent-core

submissions/mcp-hackathon/yai-agent-core/RIGHTS.md

@@ -0,0 +1,56 @@
+# RIGHTS · 权利与授权声明
+
+## 1. 提交人
+
+- 提交团队：**YAI**（单人团队）
+- 提交人 / 版权人：**Gi-Tuu**（https://github.com/Gi-Tuu）
+- 项目仓库：https://github.com/Gi-Tuu/yai-agent-core
+- 提交人声明：本项目全部代码、文档、示例均由本人原创编写，对代码、服务、依赖与数据拥有提交所需的全部权利；不存在未披露的第三方代码抄袭、虚假部署或身份操纵。
+
+## 2. 项目许可证
+
+本项目以 **MIT License** 开源，许可证全文见 `source/LICENSE`：
+
+> Copyright (c) 2026 Gi-Tuu
+
+任何人（含 X-Agent 评审与后续 MCP 标准化流程）可在 MIT 条款下使用、复制、修改、合并、发布、再许可与分发。
+
+## 3. 第三方依赖许可证
+
+内核本体（`src/yai_core/` 的核心部分）**零第三方运行时依赖**，仅使用 Python 标准库。
+下列依赖全部为可选 extras（按需安装、模块内懒加载），均为 MIT / BSD / Apache 类宽松许可证，完整版本锁定见 `source/uv.lock`，各依赖的许可证原文随其分发包提供：
+
+| 依赖（extras） | 用途 | 许可证 |
+|---|---|---|
+| openai（llm） | OpenAI 兼容模型客户端（线上接 DeepSeek） | Apache-2.0 |
+| fastapi（server） | HTTP API 框架 | MIT |
+| uvicorn[standard]（server） | ASGI 服务器 | BSD-3-Clause |
+| pydantic（server） | 请求模型与数据校验 | MIT |
+| starlette（fastapi 传递依赖） | ASGI 工具集 | BSD-3-Clause |
+| mcp（mcp） | 官方 Model Context Protocol Python SDK v2 | MIT |
+| anyio / httpx / httpcore（传递依赖） | 异步与 HTTP 运行时 | MIT / BSD-3-Clause |
+| pydantic-core / typing-extensions / sniffio / h11 / idna 等 | 运行时支撑库 | MIT / BSD / PSF 类宽松许可 |
+
+开发期工具（pytest、ruff、python-docx 等）仅用于测试与文档构建，**不进入运行时镜像与服务**。
+如评审需要逐包许可证清单，可在隔离环境执行 `uv tree` / 查看 `uv.lock` 完整复现。
+
+## 4. 数据与外部服务
+
+- 线上服务不采集、不存储、不转发任何用户个人数据；内置示例数据（3 条演示笔记、演示天气文案）均为虚构。
+- 运行时唯一的外部出站请求是发往模型 API（线上为 DeepSeek，https://api.deepseek.com）的任务推理请求，遵循该服务方的公开服务条款；提交人对发送内容负责，不包含任何第三方隐私数据。
+- 不使用任何未授权的付费资源、私有数据集或抓取数据。
+
+## 5. 提交与存档授权
+
+提交人授权 X-Agent 官方及评审流程：
+
+1. 在隔离评审环境中拉取、构建、运行本提交的 `source/` 与在线服务，进行硬门槛校验、源码评审、安全与数据审查；
+2. 在通过评审后，将与评审基线 commit 一致的完整源码复制到官方存档 ref、生成不可变的验收 release；
+3. 对入选项目按公开规则进行 MCP 标准化适配（适配器与提交包由 X-Agent 侧拥有，底层能力的真实性、运行与维护责任由提交人承担）。
+
+提交人理解：通过评审不构成 OKX 收录、上架、流量或收益的承诺；撤回未合并 PR 即视为退赛；已验收/获奖的源码将保留在官方存档中。
+
+## 6. 商标与署名
+
+- "YAI Agent Core" 与 "AMBRACE（拥爱）"为提交人自有项目名称；
+- DeepSeek、OKX、X-Agent、Render、GitHub 等名称归各自权利人所有，本项目仅作技术兼容性描述，不暗示任何背书或关联关系。

submissions/mcp-hackathon/yai-agent-core/SUBMISSION.md

@@ -0,0 +1,111 @@
+# YAI Agent Core · X-Agent MCP Hackathon 提交说明
+
+- **项目名**：YAI Agent Core（yai-agent-core）
+- **提交团队**：YAI（单人开发者 Gi-Tuu，https://github.com/Gi-Tuu）
+- **一句话定位**：进程内嵌入式、自适应的 Agent 内核——已有软件只需声明自己的普通业务函数（或挂载 MCP Server），Core 自动发现能力、自适应选择执行策略并完成任务，**宿主不写一行 Agent Loop / Planner / 工具选择代码**。
+- **在线 API**：https://yai-agent-core.onrender.com
+- **源码仓库**：https://github.com/Gi-Tuu/yai-agent-core（MIT）
+- **评审基线 commit**：以 `submission.json` 的 `reviewCommit`（40 位 SHA）为准，与 `/health`、`/.well-known/xagent-verification.json` 三处一致。
+
+---
+
+## 1. 解决什么真实问题
+
+市面上的 Agent 形态分两类：平台型（Dify/Coze，要把东西搬进别人的云）和框架型（LangGraph/OpenAI Agents SDK，开发者仍要自己定义 Agent、工具、编排）。
+大量已有软件（笔记应用、数据后台、陪伴 App）想要 Agent 能力，但不想重写、不想上云、也不想在业务代码里堆 Agent 胶水代码。
+
+YAI Agent Core 类比"Agent 世界的 SQLite"：以库的形式运行在宿主进程内，范式是 **host-declares-capability / core-adapts**：
+
+1. 宿主只提供普通 Python 函数（type hints + docstring），Core 内省生成工具规格；
+2. 外部 MCP Server 的工具经 MCP Client 同构接入（v0.2 已落地）；
+   Core 同时内置 OpenAPI 发现（可选）：任意 OpenAPI 3 REST API 提供描述即可被自动注册为工具，
+   与 MCP 工具在同一 Tool Bus 上同构调度（read_only 只读模式可用于公网演示）；
+3. Adaptive Router 把任务路由到 `direct / react / plan / clarify` 四种策略：
+   v0.2 起先由模型做一次轻量分类（输出 `{strategy, reason, tier}` JSON），
+   超时/异常/非法输出自动回退确定性规则，**两条路径都返回带来源的决策记录**；
+4. Agent Loop 完成 ReAct 工具循环 / 计划拆解执行（规划轮使用路由建议的模型档位）；
+5. 每一次策略选择（含 `source=llm|rules` 与理由）、工具调用、权限确认都作为事件流出，
+   **过程可审计，不是黑盒**。
+
+它不是又一个需要开发者拼装的 Agent 框架，而是可以"装进软件里"的内核；项目最终将回流嵌入开源 AI Companion 项目 AMBRACE。
+
+## 2. 在线能力（评审可直接调用）
+
+| 端点 | 方法 | 说明 |
+|---|---|---|
+| `/health` | GET | 健康检查，返回 `status` 与本次部署的 40 位 commit |
+| `/.well-known/xagent-verification.json` | GET | 部署证明：`schemaVersion=1` + `slug` + `commit` |
+| `/v1/tools` | GET | 当前宿主注册的全部工具（含 `source: native/mcp/openapi` 来源标注；线上实例同时挂载本地笔记工具与公共 DeepWiki MCP Server 的 3 个远程工具） |
+| `/v1/agent/run` | POST | 入参 `{"task": "..."}`，返回策略、最终结果与**全过程事件流**；任务涉及外部仓库问答时会真实发起 MCP 工具调用 |
+
+可复现的 curl 命令与期望输出见 `verification/README.md`。
+
+> 免费实例 15 分钟无流量会休眠，首次请求冷启动约 30–90 秒，请耐心等待或先请求一次 `/health` 唤醒。
+
+## 3. 工程与架构
+
+```
+src/yai_core/
+├── types.py             # ToolSpec / AgentEvent / Strategy 等核心数据结构（零依赖）
+├── spi/                 # Model / Channel / Memory / Policy 四个可替换契约
+├── discovery/           # 宿主函数内省 → ToolSpec（能力自发现）
+├── tools/               # ToolRegistry（统一花名册）+ ToolExecutor（权限→执行→事件）
+├── kernel/              # AdaptiveRouter（策略路由）+ Context + AgentLoop（主循环）
+├── llm/                 # OpenAI 兼容模型后端（DeepSeek 等，可选依赖、懒加载）
+├── memory/ policy/ channels/   # 默认实现：内存记忆 + SQLite 持久化（opt-in）/ 白名单权限 / CLI·收集通道
+├── integrations/
+│   ├── mcp/             # MCP Client 桥接（可选 [mcp] 依赖、懒加载）
+│   └── openapi/         # OpenAPI 3 发现 → 工具（可选 [openapi] 依赖、懒加载）
+└── batteries/fastapi_server/   # 在线 API Battery（可选 [server] 依赖，含限流中间件；历史保留由宿主按 env 注入）
+```
+
+关键工程原则：
+
+- **内核本体零第三方硬依赖**：`pyproject.toml` 的 `dependencies` 为空；openai / fastapi / mcp / httpx 全部归入可选 extras（llm / server / mcp / openapi）并在模块内懒加载，有 AST 测试防止顶层误引入。
+- **工具同构**：本地函数与外部 MCP 工具在 ToolRegistry 中都是 ToolSpec，Router/Loop/Executor 对工具位置零感知。
+- **错误回灌而非崩溃**：工具（含 MCP 工具）异常被捕获为失败结果回灌模型，事件流照常完整。
+- **可复现**：`uv.lock` 锁定全部依赖；Dockerfile 多阶段构建、`docker compose` 一键起；Render Blueprint（`render.yaml`）即点即部署。
+
+## 4. 测试与可观测
+
+- 离线测试 **125 项**全部通过（截至 v0.3，以 `pytest -q` 实跑为准；不需要网络与 API Key）：用 ScriptedModel 假模型、内存态 MCP Server 假外部服务、`httpx.MockTransport` 假 REST 端点，覆盖路由、ReAct/Plan 循环、权限、MCP/OpenAPI 桥接、记忆保留策略、限流与 API 端点。
+- GitHub Actions CI 矩阵：Ubuntu × Python 3.11/3.12/3.13 + Windows × 3.13。
+- 每次运行返回完整事件序列（strategy_selected / plan_created / tool_call / tool_result / done…），可直接作为评审的"能力证据"。
+- 长期运行的记忆治理：历史支持条数上限与 TTL（opt-in，按对话轮对齐裁剪，不拆散工具调用对），SQLite 存储在写入与启动时自动清理过期历史，裁剪规则为纯函数并有对等测试。
+
+## 5. MCP 产品化准备（对应 15 分评分项）
+
+- 工具边界清晰：每个工具有 name / description / JSON Schema 入参，MCP 工具 schema 经白名单清洗后与本地工具同构；
+- 已实现 MCP Client（官方 Python SDK v2），支持 Streamable HTTP、stdio 子进程、内存直连三种传输；
+- **线上 API 自身即 MCP 消费方**：部署期通过 `MCP_SERVER_URL` 环境变量挂载公共免鉴权 MCP Server（DeepWiki），评审可直接 POST 任务让线上服务真实调用远程 MCP 工具，挂载失败不影响本地工具与验证端点（优雅降级）；
+- 错误语义明确：MCP `is_error` 统一翻译为失败结果并产生 `tool_result(ok=false)` 事件；
+- 权限、副作用边界在 Tool Bus 一层统一收口；超时（规划中）同样收口于此；已实现评审期限流（每 IP 每分钟 30 次、429 + Retry-After，GET 验证端点不受限）；
+- 入选后可直接配合 X-Agent 做工具边界与 I/O schema 标准化，本项目自身不绑定任何特定 MCP Server。
+
+## 6. 安全与数据处理（评审须知）
+
+- 线上服务不提供账号体系、不采集个人信息：仅使用演示宿主自带的 3 条虚构笔记；会话历史按部署配置可落盘（`YAI_DB_PATH`，Render 免费层为临时盘、实例重建即清空），不用于任何训练或分析用途。
+- 出站请求仅发往配置的 LLM 端点（线上为 DeepSeek 官方 API）；代码内无任何遥测/统计 SDK。
+- API Key 仅存在于部署平台 Secret 与本地 `.env`（gitignore），不入库、不入镜像层（`.dockerignore` 排除）。
+- 评审期端点开放调用（满足"可在线调用"要求），已加按 IP 的零依赖限流（每 IP 每分钟 30 次，超限返回 429 与 Retry-After；health/verification/tools 三个验证端点不受限）；不提供登录墙。
+- 依赖与授权清单见 `RIGHTS.md`。
+
+## 7. 本地复现（隔离环境，5–10 分钟）
+
+```bash
+git clone https://github.com/Gi-Tuu/yai-agent-core && cd yai-agent-core
+uv venv && uv sync --extra dev --extra llm --extra server --extra mcp --extra openapi
+uv run pytest                     # 125 passed，离线
+uv run ruff check src tests examples scripts
+uv run python scripts/smoke_test.py  # 同一内核自适应三个不同宿主（离线）
+docker compose up --build         # 容器化（容器内 8000，宿主 127.0.0.1:8001）
+```
+
+接真实模型：复制 `.env.example` 为 `.env` 填入 OpenAI 兼容 Key（DeepSeek 等），运行
+`uv run python examples/host_d_mcp/run.py` 可看到本地工具与 MCP 工具在同一注册表里协同。
+
+## 8. 已知限制（诚实声明）
+
+- 免费层部署会休眠、冷启动约 30–90 秒（波动较大，建议先请求 `/health` 预热）；正式评审期将迁移常驻 VPS（手册见仓库 `docs/competitions/deployment.md`）。
+- 路由为"单次轻量 LLM 分类 + 确定性规则兜底"，不做多层反思/多智能体编排；持久化记忆为 SQLite（opt-in），免费层临时盘随实例重建清空、且不支持多进程共享，长期留存需挂盘或迁移常驻 VPS；限流按 IP 滑动窗口，不防御伪造 XFF，当前无账号体系与鉴权（列入后续版本计划）。
+- 不做 MCP Server、Multi-Agent、自进化写工具、向量记忆、内置 UI、coding agent（明确的 v0.1 红线，避免过度设计）。

submissions/mcp-hackathon/yai-agent-core/source/.dockerignore

@@ -0,0 +1,29 @@
+# 本地环境与密钥（绝不进镜像）
+.env
+.venv/
+venv/
+
+# 本地 SQLite 数据（容器内如需持久化走挂载卷，不进镜像）
+data/
+*.db
+*.db-wal
+*.db-shm
+
+# 版本控制与缓存
+.git/
+.github/
+.pytest_cache/
+.ruff_cache/
+**/__pycache__/
+*.pyc
+
+# 文档与生成产物（镜像只跑服务，不需要讲义）
+docs/
+*.docx
+*.pdf
+
+# 编辑器/系统
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

submissions/mcp-hackathon/yai-agent-core/source/.env.example

@@ -0,0 +1,46 @@
+# 复制为 .env 后填写；.env 已被 .gitignore 排除，不会进仓库
+#
+# DeepSeek 接入步骤：
+#   1. 打开 https://platform.deepseek.com/ 注册并登录
+#   2. 左侧「API keys」→ 创建并复制 sk- 开头的 Key
+#   3. 填到下面 OPENAI_API_KEY= 后面（等号两边不要加空格、不要加引号）
+# 通义千问 / OpenAI / 本地 vLLM 等任何 OpenAI 兼容端点同理，改 BASE_URL 与模型名即可。
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://api.deepseek.com
+LLM_MODEL=deepseek-chat
+# 复杂/规划任务使用的强模型（可选，缺省与 LLM_MODEL 相同）
+LLM_STRONG_MODEL=deepseek-chat
+
+# X-Agent 部署验证（batteries/fastapi_server 读取）
+YAI_PROJECT_SLUG=yai-agent-core
+
+# 持久化记忆（可选；不设置则用进程内内存，重启即失）
+# YAI_DB_PATH=data/yai.db    # 容器内路径；Render 免费层磁盘为临时存储，重启/redeploy 会丢
+
+# 历史保留策略（可选；不设置则永不裁剪，行为与旧版一致）
+# YAI_HISTORY_MAX_MESSAGES=200    # 保留最近 N 条消息（按轮对齐、整轮删除，至少留最后一轮）
+# YAI_HISTORY_TTL_SECONDS=604800  # 历史存活秒数（7 天）；过期历史在写入与启动时清理，全部过期则清空
+
+# 评审期限流（可选；默认开启，防公网误刷与失控循环）
+# YAI_RATE_LIMIT_ENABLED=1        # 0/false 关闭（本地开发可关）
+# YAI_RATE_LIMIT_PER_MINUTE=30    # 每 IP 每窗口允许的 POST /v1/agent/run 次数
+# YAI_RATE_LIMIT_WINDOW_SECONDS=60
+
+# 外部 MCP Server（可选；不设置时 serve_example 只提供本地 native 工具，
+# host_d_mcp 示例则回落到自带的本地 stdio 演示 Server）
+# Streamable HTTP 形态（线上默认接公共免鉴权的 DeepWiki）：
+# MCP_SERVER_URL=https://mcp.deepwiki.com/mcp
+# stdio 子进程形态（二选一）：
+# MCP_SERVER_COMMAND=python examples/host_d_mcp/demo_mcp_server.py
+
+# OpenAPI 发现（可选；不设置则不挂载任何 REST API）
+# OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json   # 在线描述（JSON/YAML）
+# OPENAPI_SPEC_PATH=                                                # 本地描述文件路径，与 URL 二选一
+# OPENAPI_AUTH_TOKEN=                                               # bearer / apiKey 共用的令牌
+# OPENAPI_BASE_URL=                                                 # 覆盖 spec servers[0].url
+# OPENAPI_READ_ONLY=1                                               # 1/true/yes 时只注册 GET/HEAD
+# YAI_GIT_COMMIT 保持注释状态：
+#   - 本地直接跑 uvicorn 时，留空会自动读取当前 git HEAD；
+#   - Docker 部署时由构建参数 --build-arg YAI_GIT_COMMIT=<40位commit> 固化；
+#   不要在 .env 里写 YAI_GIT_COMMIT=（空值会在运行时覆盖镜像内固化的 commit）。
+# YAI_GIT_COMMIT=

submissions/mcp-hackathon/yai-agent-core/source/.gitattributes

@@ -0,0 +1,11 @@
+# 默认让 Git 以 LF 归一化文本文件，工作区按平台检出
+* text=auto eol=lf
+
+# 二进制产物不做换行符与文本转换
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.pdf binary
+*.docx binary
+*.zip binary

submissions/mcp-hackathon/yai-agent-core/source/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: lint & test (${{ matrix.os }} / py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    env:
+      # 用矩阵解释器覆盖仓库里的 .python-version(3.13)，保证 uv sync/run 不擅自换版本
+      UV_PYTHON: ${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python-version: "3.13"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install project (dev + llm + server + mcp + openapi extras)
+        run: uv sync --extra dev --extra llm --extra server --extra mcp --extra openapi
+
+      - name: Ruff lint
+        run: uv run ruff check src tests examples scripts
+
+      - name: Pytest
+        run: uv run pytest

submissions/mcp-hackathon/yai-agent-core/source/.github/workflows/keepwarm.yml

@@ -0,0 +1,20 @@
+# 评审期保活：X-Agent 自动门槛对 GET /health 的超时是 10 秒，而 Render 免费层
+# 15 分钟无流量会休眠（冷启动 30–90 秒）。评审窗口（2026-09-20 ~ 10-04）内每 10 分钟
+# 轻量唤醒一次；只打 GET /health（返回体 <200B，不触达模型、不花额度、不受限流影响）。
+# 评审结束后（10-04 之后）请手动停用本工作流（GitHub Actions 页 disable 即可）。
+name: keepwarm
+
+on:
+  schedule:
+    - cron: "*/10 * * * *"
+  workflow_dispatch:
+
+jobs:
+  ping-health:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Wake review instance via GET /health
+        run: |
+          curl -sS --fail --max-time 90 https://yai-agent-core.onrender.com/health

submissions/mcp-hackathon/yai-agent-core/source/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Env / secrets
+.env
+*.local
+
+# 本地 SQLite 记忆库与 WAL 旁车文件（含用户对话，绝不入库）
+data/
+*.db
+*.db-wal
+*.db-shm
+
+# 本地 AI 协作者约定，只留本机、不推远端
+AGENTS.md
+
+# Test / tool caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# 由 scripts/build_walkthrough_docx.py 生成的讲义产物（需要时本地构建）
+docs/exports/
+
+# 杭州参赛材料截图（含个人信息，永不入库；目录由用户录材料时本地创建）
+docs/competitions/hangzhou/evidence/

submissions/mcp-hackathon/yai-agent-core/source/.python-version

@@ -0,0 +1 @@
+3.13