yai-agent-core 0.8.0__tar.gz

yai_agent_core-0.8.0/.gitignore

@@ -0,0 +1,52 @@
+# 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/
+.preview/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# 由 scripts/build_walkthrough_docx.py 生成的讲义产物（需要时本地构建）
+docs/exports/
+
+# 杭州参赛材料截图（含个人信息，永不入库；目录由用户录材料时本地创建）
+docs/competitions/hangzhou/evidence/
+
+# host_e 销售 CRM 演示数据（运行时生成，不入库）
+examples/host_e_sales_crm/crm_data.json
+examples/host_e_sales_crm/route_learning.json
+
+# 路由自校准 benchmark 生成物（脚本一键复现，不入库；定稿图见 docs/assets/）
+benchmark_out/
+
+# 本地 bge-m3 向量模型（约 560MB，不入库；下载说明见 models/README.md）
+models/*
+!models/README.md

yai_agent_core-0.8.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与语义化版本。
+**内核本体始终保持零第三方硬依赖**（`pyproject.toml` 的 `dependencies = []`），真实模型、Web 服务、MCP、OpenAPI 等能力全部走可选 extras 与 SPI 契约懒加载。
+
+详细的版本说明源稿见 [`docs/releases/`](docs/releases/)。版本号与 GitHub Release / tag 由维护者拍板后发布。
+
+## [Unreleased]
+
+## [v0.8.0] - 2026-10-10
+
+### Added
+
+- **代码工具仓库管理（灵动岛「工具」入口）**：内核 `CodeToolManager` 新增 `set_permanent(name, on)`（可逆开关，值未变不落盘）与 `remove(name)`（立即删除任意指定工具，区别于只批量回收过期项的 `expire_stale`），`make_permanent` 改为委托，`records()` 每项带上 `description`。薄壳侧 `shell/desktop/tool_vault.py` 用**不接模型、不接沙箱**的轻量 manager 直接读写持久化文件（复用内核同一份格式、原子写与过期判定）；工作台的 `openCodeVault / setCodeToolPermanent / removeCodeTool` 把读写**派发到常驻 worker loop**，与运行中的 Core 同线程串行，杜绝"面板改了、Core 又用旧内存态覆盖"的竞态，结果经 `codeVaultUpdated` 回 GUI。面板因此**空闲时也能打开**（Core 是每任务临时的，不能依赖当前实例）；任务执行中只可查看，写操作置灰并提示"下次任务生效"。新增 `tests/test_tool_vault.py`（4 项，按文件路径加载、不依赖 Qt）与 3 项内核回归、2 项工作台冒烟。（一个灵动岛管多个专员）**：`WorkbenchRuntime` 持有唯一一条后台 asyncio 循环，下挂多个 `SpecialistRuntime`（销售 / 仓库 / 笔记 / 陪伴），每专员**独立 busy、挂起决策、权限挡位、未读、时间线**；QML 只连工作台的聚合 Property（`activeBusy / activePendingKind / activePermissionMode / …`）与统一信号 `specialistEvent(sid, type, payload)`。定位钉死：**灵动岛是前台/交换机，专员的大脑长在应用里**——不聚合工具、不做意图自动分发。`SpecialistListModel` 供切换条显示字形/状态点/未读角标，切换后旧行一并刷新（避免双高亮）。新增 `tests/test_desktop_workbench.py` 5 项隔离测试（忙隔离、挂起隔离、事件带 id、未读、收尾唯一 loop）。
+- **三态交互形态机**：待命是**圆球**（56×56，中央动态波形，执行中起伏），指针驻留 110ms **向右展开成胶囊**（340×52，状态文本 + 呼吸点），点击**向下展开成面板**（420×620）；指针离开窗口回到球，但**有授权/澄清挂起时拒绝收回**（离开判定留 320ms 宽限，避免跨子项抖动）。左上角锚定，整岛移动交给 `Window.startSystemMove()`（位移超 4px 判拖动，否则算点击），不再手算 DPI/多屏位移。
+- **面板改为"对话优先"**：主体只有"你说"与"它答"两种气泡，思考链与调用链折叠成一条 `› 过程 · N 步`，点击才展开明细；壳层改为不透明（半透明在开着其他软件的桌面上会让对话看起来是空的）。列表数据按专员各存一份 ListModel，切走再切回历史不丢。
+- **离线演示的授权卡改为真挂起**：`shell/demo_script.py` 走到 `permission_asked` / `clarify_requested` 时不再伪造事件，而是真的 `await channel.confirm/ask` 等待界面点击——无 Key 演示里的允许/拒绝走完整权限链路，拒绝会按"用户拒绝，未执行"收尾；并补齐仓库 / 笔记 / 陪伴三段主题脚本。
+- **原生桌面端 `shell/desktop/`（PySide6 + QML）**：屏幕顶部居中的灵动岛胶囊（340×52）与员工面板（420×620）之间是**真窗口形变动画**，配系统托盘；内核与界面**同进程**（`ShellRuntime` 在专用 asyncio 线程跑 `AgentCore`，事件经 Qt 信号跨线程投递，授权/澄清由 `QtChannel` 挂起等待界面决策），不再需要本地 HTTP 端口与 SSE。动效逐条绑定真实内核事件（`strategy_selected` 涟漪、`capability_missing` 琥珀描边脉冲、`tool_discovered` 新能力飞入、`permission_asked` 自动展开授权卡、`delegate` 子员工出芽），只做小面积属性动画，不开全窗 alpha 模糊。新增 `[desktop]` 可选依赖，`python -m shell.desktop`（默认离线演示、`--live` 接真实模型）；`tests/test_desktop_runtime.py` 8 项离线测试覆盖投递/挂起兑现/忙拒绝/取消/非法挡位，未装 extra 时整体跳过、CI 四矩阵不受影响。新增讲义第 22 篇。
+- **语言中立能力清单（manifest）序列化**：`ToolSpec.to_manifest_dict()` / `from_manifest_dict()` 与 `tools/manifest.py`（批量打包 + JSON 文件读写）。composite 工作流（steps）与 code 工具（code，需宿主沙箱）作为"数据即能力"可跨进程 / 跨语言完整移植并执行；native/openapi/mcp 的 handler 不可移植，只导出能力声明。内核不另造调用通道（避免做成简化版 MCP），跨语言实际调用统一走 MCP / OpenAPI。新增 `tests/test_manifest.py`（含移植后组合工具端到端执行验证）与讲义第 21 篇。
+- **工程文档**：`docs/deployment-scaling.md`（部署 / 水平扩展 / 多租户）、`docs/multilang-interop.md`（多语言接入设计与 conformance 愿景）。
+- **PyPI 发布就绪**：补全 classifiers / project URLs、PEP 561 `py.typed` 标记，sdist 改为显式白名单（只含库源码、测试与核心文档，排除 inbox 与过程稿）；新增 OIDC Trusted Publishing 工作流 `publish.yml`（推 `v*` tag 触发、免 API token）。
+
+### Changed
+
+- **CI 工程门禁**：GitHub Actions 新增 mypy 类型检查（`src/yai_core` 零错误，66 文件）与覆盖率门禁（`--cov-fail-under=90`，实测 92.58%、474 passed）；`checkout` / `setup-uv` 钉完整 commit SHA。
+- **Windows CI 转绿**：真机 Docker 沙箱用例改按 `docker info` 的 OSType 判定，OSType 非 linux / 无 daemon 时 skip，修复 windows-latest（Server 2025）默认 Windows 容器模式导致的失败。
+
+### Security
+
+- 新增 `SECURITY.md`（支持版本表、公网部署必须配置 `YAI_API_KEY`、Subprocess/Docker 沙箱边界、发现不等于授权、私密报告渠道）与 `.github/dependabot.yml`（pip + Actions 每周更新、open-pull-requests-limit 3）。
+
+## [v0.7.0] - 2026-09-22
+
+### Added
+
+- **随包发布零依赖确定性模型 `ScriptedModel`**（`yai_core.llm`）：`pip install` 后无需 API Key、不联网即可在 30 秒内验证内核已正确嵌入并跑通工具调用；README 新增"路线 A：零 Key 验证嵌入"，并有 `tests/test_quickstart.py` 作为可执行回归。
+- **多模型兜底 `FallbackModelProvider`**：主模型 429 / 5xx / 超时 / 空响应时按序降级，带断路器冷却；只配置单个模型时默认休眠，运行时行为不变。
+- **数字员工宿主 E 网页工作台成品化**：原生 CRM 界面（客户/订单/跟进/待办/日报五视图）+ 可收起的 AI 数字员工抽屉；内置按需能力目录（拜访天气、含税报价），演示"缺口感知 → 发现 → 授权 → 本轮可用"闭环。
+- **数字员工宿主 E 产品化增强**：原生 CRM 扩为客户 / 订单 / 商机 / 跟进 / 待办 / 日报六个视图，内省自动发现 18 个业务工具（10 读 8 写）；新增客户搜索与等级/状态筛选、客户资料编辑、订单录入、商机看板（新建 + 阶段推进）等读写功能，全部不依赖 Core 即可使用，应用内开关一键对比有无 Core。
+- **ToolDiscovery 最小闭环（第 5 个 SPI）**：模型报出 `missing_capability` 后，内核向发现源（内置 `StaticCatalog`）要候选、去重注册、发 `tool_discovered` 事件，新工具本轮 ReAct 即可调用；发现源异常不致命，"能被发现不等于被授权执行"。新增宿主 F 离线演示。
+- **能力缺口感知**：LLM 路由输出 `missing_capability`，内核据此发 `capability_missing` 事件（规则路径、澄清、无工具部署不发）。
+- **`llm_router="auto"`**：按模型后端 `yai_live_router` 标记自动决定是否启用 LLM 分类，真实模型开启、离线脚本模型走规则。
+- **开源治理资产**：`ROADMAP.md`、`docs/comparison.md`（与主流框架的诚实对比）、Issue/PR 模板、CONTRIBUTING"新人 30 分钟跑通"、CI 四矩阵（Ubuntu 3.11/3.12/3.13 + Windows 3.13）。
+- **自校准路由（第 8 个 SPI `learning`）**：`ContextualBanditSelector` 按 9 维任务特征在线学习路由策略选择，宿主 E 持久化反馈、网页学习面板可查看；离线 benchmark 随反馈累积末段准确率较纯规则约 +16pp；无反馈取规则先验，冷启动确定、模型不可用不影响。
+- **双通道语义工具发现**：新增 `EmbeddingProvider` SPI 与 `SemanticCatalog`，词法相关度与语义向量相似度融合，支持同义改写/跨语言召回；本地 `bge-m3` ONNX 离线后端与 OpenAI 兼容云端后端可选，无 embedder 或出错时自动降级纯词法。
+- **两层工具目录与执行中动态发现**：系统提示只放工具摘要目录，LLM 选定后再注入完整 Schema；ReAct 循环执行中可触发发现源、注册新工具并在本轮使用。
+- **组合工具 composer 与权限三档**：模型可把已注册工具编排成新工具（只引用已注册工具、每步仍授权，能力不越界）；权限支持全部审批 / 读放行写授权 / 无需审批三档 + 白名单，运行时可切换。
+- **代码工具注册 / TTL / 授权闸与子进程教学沙箱**：`ToolSandbox` 契约 + 宿主侧 `SubprocessSandbox`（白名单内置、超时杀循环、输出截断、Unix 内存上限、授权后执行、TTL 到期回收），新增 host_g 教学沙箱宿主。
+
+### Changed
+
+- 系统提示词由"你只能通过工具操作"改为"你可以使用工具；能力不足时请明确指出缺失能力"，同时保留"不要编造工具不存在的数据"防幻觉护栏。
+
+### Fixed
+
+- 澄清循环死锁：意图不清时追问最多两轮、上下文累积合并、空回答体面收尾，重置会先终止卡住的任务。
+- 无 `[local-embed]` 环境下 `LocalBgeEmbedder` 缺模型时先抛 `ModuleNotFoundError: numpy` 而非设计的 `RuntimeError("bge-m3…")`：调整为先 `_load()` 完成模型/依赖检查再 `import numpy`，并用 `sys.modules['numpy']=None` 加回归测试锁定顺序，修复 CI 四矩阵失败。
+
+## [v0.5.0-hangzhou]
+
+- 2026 AI 杭州·码动未来"超级智能体"赛道提交版本（tag 指向该比赛快照）：MCP Client、LLM 路由器（规则兜底）、SQLite 持久化记忆（opt-in）、OpenAPI 发现、FastAPI 在线 API、多宿主 demo、容器化与 PaaS 部署。
+
+## [v0.1]
+
+- 函数内省、规则路由、Agent Loop、五个 SPI 默认实现、FastAPI Battery、三宿主 demo、容器化与 PaaS 部署。

yai_agent_core-0.8.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# 参与贡献 YAI Agent Core
+
+感谢你对 YAI Agent Core 的兴趣。本项目是一个**进程内嵌入式、自适应的 Agent 内核**：宿主软件只声明普通业务函数，Core 自动把函数变成工具、自适应选择执行策略并把全过程以事件流"喊"出来。在动手之前，请先读 [README.md](README.md) 的定位章节——我们不做又一个需要开发者自己拼装的 Agent 框架。
+
+本文档同时是维护者本人的标准操作手册：环境怎么装、代码往哪放、提交前必须过哪些检查。
+
+## 0. 新人 30 分钟跑通
+
+不需要任何 API Key，按顺序执行即可：
+
+```bash
+# 前置：Python 3.11+、uv（https://docs.astral.sh/uv/）、git
+git clone https://github.com/Gi-Tuu/yai-agent-core.git
+cd yai-agent-core
+uv venv
+uv sync --extra dev --extra llm --extra server --extra mcp --extra openapi   # 一次装齐
+uv run pytest                                   # ① 全量 197 项离线测试，应全绿
+uv run python scripts/smoke_test.py             # ② 同一内核冒烟跑通三个宿主
+uv run python examples/host_e_sales_crm/standalone_cli.py   # ③ 不带 AI 的原生 CRM 菜单（看"软件本来的样子"）
+```
+
+跑通后按这个顺序读三份文档：
+
+1. `README.md`——定位（嵌入式内核 vs 平台/框架）与 30 秒示例；
+2. `docs/reading-guide.md`——代码学习路线；
+3. `docs/walkthrough/00-index.md`——每个源码文件的逐行讲解（从 00 开始，不用跳读）。
+
+想体验真实模型：复制 `.env.example` 为 `.env` 填 Key，再跑 `examples/host_a_notes/run.py`。
+想参与贡献：看完下面的"架构红线"（§2），再从带 `good first issue` 标签的 Issue 开始。
+
+## 1. 开发环境
+
+要求 Python 3.11+（开发与 CI 以 3.13 为准），包管理使用 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+# 1. 创建并激活虚拟环境
+uv venv
+.venv\Scripts\activate            # Windows PowerShell；Linux/macOS 用 source .venv/bin/activate
+
+# 2. 安装：可编辑模式 + 开发/真实模型/在线API 可选依赖（接入 MCP/OpenAPI 再加对应 extra）
+uv pip install -e ".[dev,llm,server]"
+uv pip install -e ".[mcp]"          # 仅在开发/运行 MCP Client 集成时需要
+uv pip install -e ".[openapi]"      # 仅在开发/运行 OpenAPI 发现时需要（httpx + pyyaml）
+# 一次装齐（全量 197 项测试）：uv sync --extra dev --extra llm --extra server --extra mcp --extra openapi
+
+# 3. 验证：离线测试与冒烟，全程不需要 API Key（激活 venv 后可直接用 pytest；未激活用 uv run pytest）
+uv run pytest                       # 197 passed，离线（extras 组合与 CI 一致时无 skip）
+uv run python scripts/smoke_test.py
+```
+
+需要跑通真实模型（DeepSeek 等 OpenAI 兼容端点）时，复制 `.env.example` 为 `.env` 并填入 Key：
+
+```bash
+cp .env.example .env              # Windows: copy .env.example .env
+```
+
+`.env` 已在 `.gitignore` 中，**永远不要把 API Key 提交进仓库**。
+
+## 2. 架构红线（改动前必读）
+
+1. **内核本体零第三方硬依赖**。`pyproject.toml` 的 `dependencies` 必须保持为空；openai、fastapi、mcp 等只能出现在可选依赖（`llm` / `server` / `mcp`）里，并在对应模块内**懒加载**（`integrations/mcp/` 顶层禁止 import mcp，有 AST 测试守这条线）。
+2. **一切外部能力走 SPI 契约**（`src/yai_core/spi/`）：模型、通道、记忆、权限、发现五个插槽必须可替换，Core 只依赖 `Protocol`，不依赖具体实现。
+3. **事件流只有一条出口**：工具执行等过程事件由执行方收集、统一由 `AgentLoop` yield、`AgentCore.astream` 是唯一对外 emit 点，不允许出现第二条事件路径。
+4. **每个自适应决策必须可观测**：新增任何"Core 自己做决定"的分支，都要通过 `AgentEvent` 发出对应事件，不允许静默决策。
+5. **v0.1 不做**：MCP Server、Multi-Agent、自进化写工具、向量记忆、内置 UI、coding agent。相关讨论先进 Issue。
+
+## 3. 代码规范
+
+- Linter / import 排序：[Ruff](https://docs.astral.sh/ruff/)，规则集见 `pyproject.toml`（`E,F,I,UP,B`），行宽 100。
+- 提交前必须本地通过：
+
+  ```bash
+  ruff check src tests examples scripts
+  pytest
+  ```
+
+- 类型注解为硬性要求：公开 API 必须带参数与返回值注解；数据结构优先用 `@dataclass`，枚举用 `StrEnum`。
+- 每个模块开头写模块 docstring，说明它在全景图中的位置；面向学习者，复杂逻辑块配行内注释。
+- **改了源码就要同步改逐行讲解**：`docs/walkthrough/` 与代码逐块对应，行为变化时同 PR 更新对应篇目。
+
+## 4. 测试约定
+
+- 测试**不允许依赖网络、API Key 或外部服务**。真实协议用假模块/假端点验证，参考 `tests/test_openai_compat.py`（注入假 `openai` 模块）、`tests/test_loop.py`（ScriptedModel）与 `tests/test_mcp_bridge.py`（内存 MCPServer 实例直连，不起子进程、不触网；文件首行 `pytest.importorskip` 保证最小环境可跳过）。
+- 新功能必须带测试：新策略、新工具来源、新 SPI 实现至少各一条端到端用例。
+- 修 Bug 先写一个能复现该 Bug 的失败测试，再修代码让它通过。
+
+## 5. 常见开发任务怎么做
+
+| 想做的事 | 动哪里 | 参考 |
+|---|---|---|
+| 让一个新软件被 Core 适配 | 新建 `examples/host_x/`，只写普通函数 + run 脚本 | `examples/host_a_notes/` |
+| 支持一家新模型厂商 | 实现 `ModelProvider` 契约（OpenAI 兼容优先复用现有 provider） | `src/yai_core/llm/`、`spi/model.py` |
+| 增加一种工具来源（MCP/OpenAPI） | 产出统一 `ToolSpec` 注册进 `ToolRegistry`，执行侧不改；MCP 范式见 `integrations/mcp/` | `integrations/mcp/client.py`、`discovery/introspect.py` |
+| 增加一种"按需发现"来源 | 实现 `ToolDiscovery` 契约（`discover(need, *, task, available) -> list[ToolSpec]`），通过 `AgentCore(..., discovery=)` 注入；只交候选，注册/去重/权限归内核；最小实现见 `discovery/catalog.py` | `spi/discovery.py`、`discovery/catalog.py`、`tests/test_discovery_catalog.py` |
+| 增加一种执行策略 | 先在 `AdaptiveRouter` 加确定性规则并补测试，LLM 分类是 v0.2 的事 | `kernel/router.py` |
+| 换记忆/权限/输入输出 | 实现对应 SPI，通过 `AgentCore(..., memory=/policy=/channel=)` 注入 | `src/yai_core/spi/` |
+
+## 6. 提交与 PR 流程
+
+- 分支命名：`feat/xxx`、`fix/xxx`、`docs/xxx`、`test/xxx`、`chore/xxx`。
+- Commit message 使用 Conventional Commits：`feat: host_a 接入 DeepSeek 真实工具调用`、`fix: provider 直接消费 Context 产出的线格式消息`、`docs: 补 06 loop 逐行讲解`。
+- 一个 PR 只解决一件事；保持小步提交，不要把重构和功能混在一起。
+- PR 描述需说明：改了什么、为什么、怎么验证的（贴命令与结果）、是否改动了公开 API 或 walkthrough。
+- 合并前 checklist：`ruff check` 通过、`pytest` 全绿、新行为有测试、文档同步、无 Key/隐私泄露。
+
+## 7. Issue 与讨论
+
+- Bug 报告请附：系统与 Python 版本、复现命令、期望与实际结果、完整报错堆栈；模型相关问题注明厂商、模型名、是否离线测试可通过。
+- 功能建议先描述**宿主场景与痛点**（哪个软件、原本要写什么 Agent 代码），再谈方案；与"嵌入式自适应内核"定位不符的需求可能会被建议放到 Battery 或独立仓库。
+
+## 8. 许可证
+
+本项目采用 MIT 许可证，提交 PR 即表示你同意你的贡献以 MIT 许可发布。

yai_agent_core-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gi-Tuu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yai_agent_core-0.8.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.5
+Name: yai-agent-core
+Version: 0.8.0
+Summary: YAI Agent Core — an embeddable, self-adaptive agent kernel for host applications
+Project-URL: Homepage, https://github.com/Gi-Tuu/yai-agent-core
+Project-URL: Repository, https://github.com/Gi-Tuu/yai-agent-core
+Project-URL: Issues, https://github.com/Gi-Tuu/yai-agent-core/issues
+Project-URL: Changelog, https://github.com/Gi-Tuu/yai-agent-core/blob/main/CHANGELOG.md
+Author: Gi-Tuu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,embedded,kernel,llm,mcp,runtime,tool-calling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: desktop
+Requires-Dist: pyside6>=6.6; extra == 'desktop'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: python-docx>=1.1; extra == 'docs'
+Provides-Extra: llm
+Requires-Dist: openai>=1.40; extra == 'llm'
+Provides-Extra: local-embed
+Requires-Dist: numpy>=1.26; extra == 'local-embed'
+Requires-Dist: onnxruntime>=1.17; extra == 'local-embed'
+Requires-Dist: tokenizers>=0.15; extra == 'local-embed'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Provides-Extra: openapi
+Requires-Dist: httpx>=0.27; extra == 'openapi'
+Requires-Dist: pyyaml>=6.0; extra == 'openapi'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: pydantic>=2.7; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'server'
+Description-Content-Type: text/markdown
+
+# YAI Agent Core
+
+[![CI](https://github.com/Gi-Tuu/yai-agent-core/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Gi-Tuu/yai-agent-core/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Version](https://img.shields.io/badge/version-v0.7.0-blue.svg)](CHANGELOG.md)
+[![Kernel](https://img.shields.io/badge/kernel-0%20third%20party%20deps-c0392b)](pyproject.toml)
+
+<p align="center"><b>给每个软件，一颗会思考的心脏。</b></p>
+
+> 进程内嵌入式、**自适应**的 Agent 内核 —— **Agent 世界的 SQLite**。
+> 不必部署一个智能体平台，也不必写 Agent Loop / Planner / 工具选择代码：把内核 `import`
+> 进你**已有的软件**，宿主只声明“我有什么能力”，Core 自动发现能力、选策略、调工具、完成任务。
+
+<p align="center">
+  <img src="docs/assets/desktop-panel.png" alt="YAI 灵动岛员工面板：对话为主体，思考链与调用链折叠成过程步，含税任务从发现工具到归档完整闭环" width="520">
+</p>
+
+<p align="center"><b>一个浮窗，就是一个数字员工。</b> 对话为主体，思考链与工具调用折叠成“过程 · N 步”；
+路由、能力缺口、新工具飞入、授权卡全部由真实内核事件驱动。截图数据均为虚构。</p>
+
+## 这是什么
+
+YAI 不是又一个聊天机器人，也不是让你照着教程拼装的 Agent 框架。它是一个**跑在你软件进程里的内核**：
+
+- 你把软件里**本来就存在的普通函数**交给它（或接入 MCP / OpenAPI）；
+- 它内省这些能力、自动生成工具规格，在收到任务时**自适应**地决定直接回答、调用工具、分步规划，还是向你澄清；
+- 能力不足时能**感知缺口、按需发现新工具**，高危操作默认**先请求授权**——每一步都以事件对外可见。
+
+## 适合谁 / 不适合谁
+
+| ✅ 适合你，如果…… | ⛔ 不适合你，如果…… |
+|---|---|
+| 已有一个能跑的软件，想**低成本加上 Agent 能力**，且不被平台锁定 | 想在网页上**拖拽搭 Agent**、完全不写代码（用 Dify / Coze） |
+| 想让 AI 调用你软件的**真实功能**，而不是通用闲聊 | 想要开箱即用的**云端托管 / 团队 SaaS** 智能体 |
+| 需要可**自托管、可内嵌**、各部件可替换的 Agent 运行时 | 想要无人值守、全自动的 **coding agent**（YAI 刻意默认要授权） |
+| 想边做边学 Agent 内部原理（每个决策可审计、有逐行讲义） | 期望零配置的通用助手——YAI 的价值恰恰在**绑定宿主能力** |
+
+## 和你听过的东西有何不同
+
+|  | 平台<br>Dify / Coze | 框架<br>LangGraph · CrewAI · Agents SDK | **嵌入式内核 · YAI** |
+|---|---|---|---|
+| 形态 | 注册账号，在平台里搭 | 自己定义 Agent / 工具 / 编排 | **`import` 进现有软件** |
+| 要写的 Agent 代码 | — | 多 | **无** |
+| 部署方式 | 平台托管 | 自己起一个服务 | **随宿主进程，无独立服务** |
+| 绑定宿主能力 | 弱、需手动接 | 手动接 | **自动内省发现** |
+| 内核第三方硬依赖 | — | 通常较多 | **0**（全部可选、懒加载） |
+
+> 数据库类比：平台是云数据库控制台，框架是 ORM，**YAI 是 SQLite** —— 不抢主角，安静地嵌进你的程序。
+
+## 30 秒跑起来
+
+**路线 A · 只装库、零 Key 验证嵌入**（不必克隆、不必申请模型）。内核本体零第三方硬依赖：
+
+```bash
+pip install "yai-agent-core @ git+https://github.com/Gi-Tuu/yai-agent-core.git"
+```
+
+```python
+import asyncio
+from yai_core import AgentCore, ScriptedModel, ModelResponse, ToolCallRequest, build_spec
+
+def search_notes(keyword: str) -> list[str]:
+    """搜索宿主笔记库。"""                # 你自己的普通业务函数，没有任何 Agent 代码
+    return {"周报": ["Core 骨架", "工具调用"]}.get(keyword, [])
+
+# 离线确定性模型（真实上线整体换成 OpenAICompatProvider）：先调工具，再给结论
+model = ScriptedModel([
+    ModelResponse(content="", tool_calls=[ToolCallRequest(id="c1", name="search_notes",
+                 arguments={"keyword": "周报"})]),
+    ModelResponse(content="本周周报 2 条。"),
+])
+core = AgentCore(model)
+core.register_tools([build_spec(search_notes)])      # 内省 type hints / docstring 生成工具
+print(asyncio.run(core.run("搜索周报并总结")).final_text)   # 本周周报 2 条。
+```
+
+接真实模型只需换一行（`[llm]` extra，OpenAI 兼容 DeepSeek / 通义 / OpenAI / Agnes）：
+
+```python
+from yai_core import OpenAICompatProvider
+model = OpenAICompatProvider()      # 读 OPENAI_API_KEY / OPENAI_BASE_URL / LLM_MODEL
+```
+
+**路线 B · 克隆仓库，跑全部宿主与测试**（离线，无需 Key）：
+
+```bash
+uv venv
+uv pip install -e ".[dev,llm,server]"
+uv run python scripts/smoke_test.py   # 同一 Core 自适应多个不同宿主
+uv run pytest                         # 全量测试，不需要 API Key
+```
+
+第一次读代码：[`docs/reading-guide.md`](docs/reading-guide.md) 是学习路线，[`docs/walkthrough/00-index.md`](docs/walkthrough/00-index.md) 是逐行讲解。
+
+## 核心能力
+
+| 能力 | 一句话 |
+|---|---|
+| **能力自发现** | Python 函数 type hints + docstring 自动生成 JSON Schema；外部 **MCP** 工具经 MCP Client、**OpenAPI** REST 操作经规范解析，同构接入注册表 |
+| **自适应路由** | 任务路由到 `direct / react / plan / clarify`；LLM 分类异常自动回退规则，工具不足时发出 `capability_missing`，决策全程可审计 |
+| **自校准学习** | 上下文 bandit 从成败中学习路由，Thompson Sampling 选策略；离线 benchmark 末段 **89.6% vs 规则 73.3%（约 +16pp）** |
+| **按需发现闭环** | 缺口 → 向发现源要候选 → 注册 → **本轮即可调用**；支持词法 + 本地 bge-m3 / 云端 embedding 双通道语义召回 |
+| **长上下文压缩** | 超预算时把旧轮压成摘要、最近完整轮原样保留，模型失败回退硬裁剪——长对话不丢早期目标与事实 |
+| **安全边界** | 权限三档（全部 / 部分 / 无需审批）；组合工具只编排已注册工具、不执行生成代码；代码生成仅定义 `ToolSandbox` 契约、沙箱由宿主提供 |
+| **全程可观测** | 每次策略选择、能力缺口、工具发现 / 组合 / 调用、权限确认都通过统一事件流对外发出 |
+
+<details>
+<summary>展开：八个可替换 SPI 契约</summary>
+
+`Model · Channel · Memory · Policy · Discovery · Sandbox · RouteSelector · Embedding`
+——宿主可替换任意一个，Core 提供零配置默认实现。内核本体始终零第三方硬依赖。
+
+</details>
+
+## 两种用法
+
+### 1）作为库嵌入（三步）
+
+```python
+from yai_core import AgentCore, OpenAICompatProvider
+import my_app_capabilities as cap                       # 宿主自己的普通业务函数
+
+core = AgentCore.auto(cap, OpenAICompatProvider())      # ① 内省能力，自动注册工具
+result = await core.run("搜索本周记录并整理成报告")        # ② 自适应 direct/react/plan/clarify
+print(result.final_text)                                # ③ 可交付结果 + 全程事件
+```
+
+### 2）灵动岛员工薄壳（`shell/desktop`）
+
+需要一张“脸”的宿主**不必自己写交互窗口**：官方薄壳提供一个常驻浮窗，Qt Quick 真原生渲染、
+与各应用内置的 Core 跑在**同一进程**（无本地端口）。
+
+<p align="left">
+  <img src="docs/assets/desktop-ball.png" alt="灵动岛引导球：圆形球加紫色呼吸环，球内点我提示" width="180">
+</p>
+
+- **三态形变**：圆形球（56）→ 悬停向右展开胶囊（340×52）→ 点击向下展开员工面板（470×620），全程可拖动；
+- **位置记忆**：拖动后关闭重开，浮窗回到原处；
+- **首次引导**：球内“点我” + 紫色呼吸环，引导一次后不再出现；
+- **全局快捷键**：在任意软件按 `Ctrl+Alt+Y` 立刻呼出并展开；
+- **离线 / 真实双入口**：桌面快捷方式分别启动离线演示与接真实模型的员工；
+- **多专员切换**：一座岛管理销售 / 仓库 / 笔记 / 陪伴多个**彼此隔离**的专员，时间线不丢 ——
+  灵动岛只做前台 / 交换机，**不做超级 Agent**。
+
+```bash
+uv sync --extra desktop
+.\.venv\Scripts\python.exe -m shell.desktop            # 离线演示：无 Key 看全部动效
+.\.venv\Scripts\python.exe -m shell.desktop --live     # 接真实模型
+```
+
+薄壳只做呈现与编排；`shell/employee` 把子员工实现为“收窄工具 + 收窄权限 + 独立上下文 + 预算”的
+一次 sub-run（并行 ≤ 5、嵌套 ≤ 2、结果只回流根），**内核不感知界面、也不做多 Agent 框架**。
+
+## 截图墙
+
+<p align="center">
+  <img src="docs/assets/hoste-native.png" alt="销售 CRM 原生六视图，不依赖 Core 完整可用" width="45%">
+&nbsp;&nbsp;
+  <img src="docs/assets/hoste-discovery.png" alt="CRM 嵌入 Core，能力不足时自动发现天气工具并请求授权" width="45%">
+</p>
+
+<p align="center"><b>左：</b>软件本来的样子（六个原生视图，无 Core 也完整可用）；
+<b>右：</b>嵌入 Core 后，能力不足时自动发现工具、首次调用仍弹授权卡（发现 ≠ 授权）。</p>
+
+<p align="center">
+  <img src="docs/assets/router-learning-curve.svg" alt="自校准路由学习曲线：bandit 从规则基线爬升到约 90%" width="60%">
+</p>
+
+## 示例（由浅入深）
+
+| # | 宿主 | 看什么 |
+|---|---|---|
+| 1 | `host_a_notes` | 最小接入：普通函数自动变工具 |
+| 2 | `host_c_companion` | 换领域即换岗位（AMBRACE 预演） |
+| 3 | `host_d_mcp` | 作为 Client 接入外部 MCP Server |
+| 4 | `host_f_discovery` | 能力缺口 → 发现 → 本轮可用（静态 / 语义） |
+| 5 | `host_g_sandbox` | 教学沙箱：现场造代码工具并执行 |
+| 6 | `host_e_sales_crm` | 旗舰：独立 CRM，一个开关嵌入 Core（终端 + 网页，端口 8200） |
+| 7 | `host_i_mealie` | 适配真实第三方高 star 开源项目（Mealie） |
+
+> 目录名保留历史编号（a/c/d/e/f/g/i），不随学习顺序重排，以便与各版材料、讲义路径一致。
+
+## 在线 HTTP API
+
+线上实例：**https://yai-agent-core.onrender.com**（免费层冷启动约 30–90s）
+
+```bash
+GET  /health                  # {"status":"ok", ...}
+GET  /v1/tools                # 当前宿主自动发现的工具清单
+POST /v1/agent/run            # {"task": "..."} -> 事件流 + 最终结果
+```
+
+可选环境变量（持久化记忆、历史裁剪 / TTL、限流等）见 [`.env.example`](.env.example) 与 [`docs/architecture.md`](docs/architecture.md)。
+
+## 版本路线
+
+- **v0.1 – v0.3（已完成）**：函数内省、规则 / LLM 路由、Agent Loop、SPI 默认实现、MCP Client、SQLite 持久化、OpenAPI 发现、历史裁剪与限流、容器化部署
+- **v0.4 – v0.6（已完成）**：能力缺口感知与 ToolDiscovery 闭环、host_e CRM 零改造嵌入、权限三档、组合工具、双通道语义发现、执行中动态发现
+- **v0.7（已完成，本版）**：自校准路由 contextual bandit（离线 +16pp）、代码工具注册 / TTL / 授权闸、子进程教学沙箱、灵动岛员工薄壳
+- **v1.0（规划中）**：作为 AI Companion 项目 [AMBRACE](https://github.com/Gi-Tuu/AMBRACE) 的 Agent 内核回流嵌入
+
+## 许可证
+
+MIT · [Gi-Tuu](https://github.com/Gi-Tuu)