zero-agent-core 0.2.0__tar.gz

zero_agent_core-0.2.0/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[{*.json,*.yml,*.yaml,*.ts,*.css}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

zero_agent_core-0.2.0/.gitattributes

@@ -0,0 +1,11 @@
+* text=auto
+
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.json text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.ts text eol=lf
+*.css text eol=lf
+*.svg text eol=lf

zero_agent_core-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: 缺陷报告
+description: 报告可以稳定复现的框架问题
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: 安全漏洞请按 SECURITY.md 私密报告，不要在这里公开。
+  - type: input
+    id: version
+    attributes:
+      label: Agent Core 版本
+      placeholder: 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: 运行环境
+      placeholder: Python 3.13、Windows 11 / Ubuntu 24.04
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 最小复现
+      description: 请提供已经去除密钥和业务数据的代码、配置和步骤。
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 预期行为
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: 实际行为和完整错误栈
+    validations:
+      required: true

zero_agent_core-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 安全问题
+    url: https://github.com/qiuzixu/agent-core/blob/main/SECURITY.md
+    about: 请按安全策略使用私密渠道报告漏洞

zero_agent_core-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: 功能建议
+description: 建议一个可复用的框架能力
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: 使用场景和问题
+      description: 请说明为什么这是多个 Agent 都需要的通用能力。
+    validations:
+      required: true
+  - type: textarea
+    id: api
+    attributes:
+      label: 期望行为或 API
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 已考虑的替代方案

zero_agent_core-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## 问题与结果
+
+<!-- 说明具体触发条件，以及修改前后的行为。 -->
+
+## 兼容性
+
+<!-- 说明公共 API、持久化数据、恢复中的 Run/Workflow 和依赖是否受影响。 -->
+
+## 验证
+
+- [ ] `ruff check src tests examples`
+- [ ] `pytest`
+- [ ] `python -m mkdocs build`
+- [ ] 已按需更新 `docs/ARCHITECTURE.md` 和 `docs/CAPABILITIES.md`

zero_agent_core-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: Core CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Install project
+        run: >-
+          python -m pip install -e ".[dev]"
+          -e "./packages/mineru"
+          -e "./packages/embeddings"
+          -e "./packages/multi-agent"
+          build
+      - name: Lint
+        run: >-
+          ruff check src tests examples
+          packages/mineru/src packages/mineru/tests
+          packages/embeddings/src packages/embeddings/tests
+          packages/multi-agent/src packages/multi-agent/tests
+      - name: Type check
+        run: |
+          mypy src
+          mypy --config-file packages/mineru/pyproject.toml packages/mineru/src
+          mypy --config-file packages/embeddings/pyproject.toml packages/embeddings/src
+          mypy --config-file packages/multi-agent/pyproject.toml packages/multi-agent/src
+      - name: Test
+        run: |
+          pytest
+          pytest packages/mineru/tests
+          pytest packages/embeddings/tests
+          pytest packages/multi-agent/tests
+      - name: Build package
+        run: |
+          python -m build
+          python -m build packages/mineru
+          python -m build packages/embeddings
+          python -m build packages/multi-agent

zero_agent_core-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,27 @@
+name: Docs
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Install dependencies
+        run: python -m pip install -e ".[dev]" mkdocs-material
+      - name: Build docs
+        run: python -m mkdocs build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: mkdocs-site
+          path: site

zero_agent_core-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: Publish
+
+# 首次发布前置条件（PyPI 侧一次性配置，见 docs/reference 或发布指南）：
+# 在 PyPI 项目尚未存在时使用 "Pending Publisher" 预绑定 Trusted Publisher：
+#   owner = qiuzixu, repository = agent-core, workflow = publish.yml,
+#   environment = pypi（PyPI 侧可留空，GitHub 侧如使用 environment 需一致）。
+# 发布：打 tag（如 v0.2.0）推送到 GitHub，或手动触发 workflow_dispatch。
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build tool
+        run: python -m pip install build twine
+      - name: Build four distributions
+        run: |
+          python -m build
+          python -m build packages/mineru
+          python -m build packages/embeddings
+          python -m build packages/multi-agent
+      - name: Twine check
+        run: python -m twine check dist/* packages/mineru/dist/* packages/embeddings/dist/* packages/multi-agent/dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: |
+            dist/*
+            packages/mineru/dist/*
+            packages/embeddings/dist/*
+            packages/multi-agent/dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted Publisher 要求 id-token: write，不上传任何 PyPI 令牌。
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist
+      - name: Consolidate wheels and sdists
+        run: |
+          mkdir -p upload
+          find dist -name "*.whl" -exec mv {} upload/ \;
+          find dist -name "*.tar.gz" -exec mv {} upload/ \;
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: upload

zero_agent_core-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+site/
+*.db
+*.sqlite
+*.sqlite3
+.venv/*

zero_agent_core-0.2.0/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent Core 维护约束
+
+修改 `agent-core` 时必须遵守以下规则：
+
+1. 修改 `src/agent_core/**` 后，必须在同一提交中检查 `docs/ARCHITECTURE.md`。
+2. 模块边界、公共接口、依赖方向、运行时调用链、存储对象、协议或应用 Agent 接入关系发生变化时，
+   必须同步修改对应 Mermaid 架构图。
+3. 如果代码变化不影响图形关系，也必须在 `docs/ARCHITECTURE.md` 的“同步记录”中增加一条检查记录，
+   说明无需修改图形的原因。
+4. 新增公共能力时，同时更新 `docs/CAPABILITIES.md`；不能把规划中的能力写成已经实现。
+5. 架构图和代码注释优先使用中文，公共类型名和协议名保留代码中的英文名称。

zero_agent_core-0.2.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# 变更日志
+
+本项目遵循[语义化版本](https://semver.org/lang/zh-CN/)，变更按
+[Keep a Changelog](https://keepachangelog.com/zh-CN/) 的结构记录。
+
+## [Unreleased]
+
+### Changed
+
+- 发行名由 `handwritten-agent-core` 更名为 `zero-agent-core`（PyPI 发行名与三个扩展包
+  `zero-agent-core-mineru` / `zero-agent-core-embeddings` / `zero-agent-core-multi-agent` 同步更名）。
+  导入名 `agent_core`、`agent_core_mineru`、`agent_core_embeddings`、`agent_core_multi_agent`
+  保持不变，升级后无需修改任何 import 语句；安装命令改为
+  `pip install "zero-agent-core[models,mcp]"` 等对应形式。
+
+## [0.2.0] - 2026-10-11
+
+### Added
+
+- `AgentRuntime` 支持可选 `run_executor`（`RunExecutor` 协议）：应用可接管 Agent 调用，
+  Runtime 统一收口运行状态、事件、持久化与租约。
+- 访问校验抽取为 `agent_core.access.enforce_access`：严格模式要求、资源归属完整性与
+  身份校验三类判定共享同一实现。
+- `TimeTravelCheckpointer` 新增 `max_versions_per_thread` 版本容量上限（默认 100）：
+  追加超过上限时淘汰最旧版本并同步收缩持久化文件，当前指针语义保持不变。
+- 基于 Material for MkDocs 的中文文档站、使用指南和公共 API 参考。
+- 开源许可证、贡献指南、社区准则、安全策略、支持说明和发布检查清单。
+- 最小 Agent、自定义模型和持久化工作流示例。
+- Core 检查与文档构建的 CI 配置。
+- JSON Schema 结构化输出、decoder 和校验失败重试。
+- 模型请求/输入 Token 限流、按 scope 并发、超时、熔断和 fallback。
+- 工作流节点级重试、超时、退避、幂等键、pending write 和 Mermaid 导出。
+- 跨会话长期记忆端口及内存、SQLite、PostgreSQL 实现。
+- 安全 Prompt 文本/聊天模板、消息占位符、partial 和默认变量。
+- 生命周期 CallbackManager、增强 RunEvent 和流式增量事件。
+- 文档加载/切分、Embedding/Retriever/VectorStore 协议及轻量内存实现。
+- 独立 `handwritten-agent-core-mineru` 扩展包，支持自托管 `/file_parse`、区块、页码和来源追踪。
+- 独立 `handwritten-agent-core-embeddings` 扩展包，支持 OpenAI、Gemini、Ollama 和统一工厂。
+- 独立 `handwritten-agent-core-multi-agent` 扩展包，支持 Agent 注册、路由、handoff、父子 Run、
+  预算、恢复、租约和顺序/并行协调。
+- Chroma 本地持久化、PostgreSQL pgvector 生产适配器及统一向量存储工厂。
+- 带类型白名单、Schema 版本和迁移函数的安全 JSON 序列化。
+
+### Fixed
+
+- 直接 API 以 checkpoint 恢复 Agent 时回填 RunContext.checkpoint 基底，修复恢复批次进度快照丢失迭代/预算/最终回答的问题。
+- 时间旅行接口 `get_checkpoint_history`/`rollback_to` 增加显式 `thread_id` 参数，避免读到构造时默认会话的版本。
+- Middleware `MODIFY` 聚合与 ctx 写入对账，按注释契约只写回 ctx 的自定义中间件不再被 data 旧值覆盖。
+- 并发工具批次末尾不再重复保存与主循环相同的 phase=model 快照。
+- 幂等唯一索引升级前预检归一化后重复行，SQLite/PostgreSQL 初始化给出可操作的错误而不是建索引失败。
+- HITL 幻影请求（存储记录缺失）等待超时按 TIMEOUT 收口；进程内缓存与 `list_pending` 补齐过期检查。
+- 取消运行时记录任务的业务异常日志，不再无声吞掉。
+- 模型治理在全部候选熔断时直接失败且不消耗限流配额，熔断状态容量可配置并自动淘汰。
+- `TimeTravelCheckpointer` 持久化失败回滚按身份移除版本，避免并发保存时弹掉其他调用者的版本。
+- 文件与时间旅行 Checkpointer 的 thread 文件名改为白名单严格清洗（单射可逆）：
+  含 `/`、`\`、`:` 等 Windows 非法字符的会话不再互相覆盖，`list_threads` 反向映射同步还原。
+
+### Changed
+
+- `ReActAgent` 的 `run`/`stream` 双循环抽取为共享内核 `_iterate`：消息构造、checkpoint 恢复、
+  中间件 before/after、工具预算守卫、工具执行与快照保存只实现一次；非流式/流式一轮模型调用的
+  差异（`llm.chat` vs `stream_chat` 增量归并、文案与日志标识）集中到 `_LoopMode` 策略对象。
+  对外签名、事件序列、checkpoint 状态字段与错误文案逐字保持不变，并有 run/stream checkpoint
+  一致性契约测试守护。
+- `AgentRuntime` 与 `DurableWorkflowRunner` 的 `_check_access` 改为委托共享的
+  `agent_core.access.enforce_access`，判定顺序与错误文案保持不变。
+- 7 个 SQLite 存储（session/runtime/lease/memory/workflow/context/model_selection）的
+  async 方法统一经 `asyncio.to_thread` 在线程池执行，构造期 DDL/PRAGMA 初始化同样入线程；
+  新增共享连接规范 `storage/_sqlite_utils.py`（`timeout=30.0` + WAL），SQLite 锁等待
+  不再冻结事件循环，方法签名与返回值保持不变。
+- 补齐 compaction 子系统核心单测（region 边界切割、pruner 瘦身与 spill 标记、summarizer 结构
+  校验失败、中间件阈值触发与 prune-only 降级）、OpenAI/Anthropic/Gemini 流式 `finish_reason`
+  契约测试，以及"恢复时只重放未完成工具"回归断言。
+- 修复 Runtime/Workflow 并发覆盖和匿名作用域幂等索引，PostgreSQL Workflow JSONB 恢复兼容字符串返回。
+- HITL 持久化审批 deadline，并以条件状态转换避免超时覆盖批准或拒绝。
+- 文件与时间旅行 Checkpoint 改为原子替换，ReAct 并发工具按完成进度保存可恢复快照。
+- 模型治理按逻辑请求执行限流和并发控制，增加默认调用超时与按 scope 隔离的熔断状态。
+- 统一模型工具参数错误、结构化输出校验、MCP 文本结果回退和工具失败观测语义。
+- 收紧 Context/Prompt/ACP 的归属、损坏文件和审批选项处理，并限制进程内观测记录容量。
+- `ObservabilityMiddleware` 按异步上下文隔离模型/工具计时，并从当前调用元数据读取 `thread_id`。
+- `DurableWorkflowRunner` 增加 `raise_on_failure`，应用可以读取已持久化的失败执行实例。
+- `TimeTravelCheckpointer` 持久化 rollback 当前版本指针，并实现整条 thread 历史删除协议。
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- 手写 ReAct Agent Loop，支持普通执行、真正的流式输出、并发工具调用和运行恢复。
+- Function Calling、MCP 客户端、Skill 清单加载与工具绑定。
+- 模型协议、模型目录、运行时模型选择，以及 OpenAI、Anthropic、Gemini、Ollama 适配器。
+- Middleware、HITL、Guardrails、可观测性和上下文压缩。
+- Checkpoint、状态机、持久化工作流、运行租约和 ACP stdio 服务端。
+- 内存、SQLite 和 PostgreSQL 的会话、上下文、运行、审批、工作流与模型选择存储。
+- 用户、租户和管理员访问上下文。

zero_agent_core-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# 社区行为准则
+
+## 我们的承诺
+
+我们承诺为所有参与者提供友好、安全、无骚扰的协作环境，不因年龄、身体状况、
+民族、性别认同与表达、经验水平、国籍、外貌、种族、宗教、性取向或其他身份而区别对待。
+
+## 期望行为
+
+- 使用尊重、包容且具体的语言。
+- 接受建设性的技术反馈，并围绕事实讨论。
+- 尊重他人的时间、隐私、署名和知识产权。
+- 发生分歧时优先澄清目标、约束和可验证证据。
+- 发现不当行为时及时向维护者报告。
+
+## 不可接受的行为
+
+- 侮辱、威胁、骚扰、跟踪或公开他人隐私信息。
+- 带有歧视或性暗示的言论、图片和行为。
+- 持续打断讨论、蓄意制造敌意或对个人进行攻击。
+- 未经许可使用他人的身份、作品、密钥或私有数据。
+- 维护者认定不适合专业协作环境的其他行为。
+
+## 执行
+
+维护者负责解释和执行本准则，并可删除不当内容、限制参与、临时或永久禁止参与者。
+执行时会尽量保护报告者和相关人员的隐私。
+
+请通过 [安全策略](SECURITY.md) 中的私密渠道报告行为准则问题。维护者会根据影响范围、
+是否重复发生和当事人的配合程度采取一致、相称的处理措施。
+
+本准则适用于项目仓库、Issue、合并请求、评审、社区活动以及代表项目参与的其他公共空间。

zero_agent_core-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# 贡献指南
+
+感谢你参与 Handwritten Agent Core。提交改动前，请先确认问题属于框架通用能力，
+还是某个应用 Agent 的业务能力。业务工具、HTTP 路由和产品页面应留在应用项目中。
+
+## 开始开发
+
+项目要求 Python 3.13。推荐使用 `uv`：
+
+```bash
+uv sync --extra dev --extra models --extra mcp --extra production
+uv pip install build twine
+python -m pip install mkdocs-material
+```
+
+也可以使用标准 `venv` 和 `pip`：
+
+```bash
+python -m venv .venv
+python -m pip install -e ".[dev,models,mcp,production]"
+python -m pip install -e "./packages/mineru"
+python -m pip install -e "./packages/embeddings"
+python -m pip install -e "./packages/multi-agent"
+python -m pip install build twine mkdocs-material
+```
+
+运行检查：
+
+```bash
+ruff check src tests examples
+pytest
+mypy src
+mypy --config-file packages/mineru/pyproject.toml packages/mineru/src
+pytest packages/mineru/tests
+mypy --config-file packages/embeddings/pyproject.toml packages/embeddings/src
+pytest packages/embeddings/tests
+mypy --config-file packages/multi-agent/pyproject.toml packages/multi-agent/src
+pytest packages/multi-agent/tests
+python -m mkdocs build
+python -m build
+python -m build packages/mineru
+python -m build packages/embeddings
+python -m build packages/multi-agent
+```
+
+Core 和扩展包都执行 strict mypy，类型错误会阻止 CI 合并。
+
+## 修改约束
+
+- 公共 API 优先从 `agent_core` 顶层导出，并为行为变化补充测试。
+- 第三方平台适配优先放在 `packages/` 独立发行包中，通过 Core Protocol 和值对象接入。
+- 修改 `src/agent_core/**` 后，检查并更新 `docs/ARCHITECTURE.md` 的架构图或同步记录。
+- 新增公共能力时，同步更新 `docs/CAPABILITIES.md` 和对应使用指南。
+- 注释和架构说明优先使用中文；公共类型名、协议名与行业术语保留英文。
+- 不在提交中包含密钥、真实业务数据、数据库文件或构建产物。
+- 兼容性破坏需要在变更说明中给出迁移方式，并按语义化版本提升主版本或次版本。
+
+## 提交和合并请求
+
+提交信息推荐使用 Conventional Commits，例如：
+
+```text
+feat: 增加自定义模型适配器注册能力
+fix: 恢复中断运行时释放租约
+docs: 补充 MCP 接入示例
+```
+
+合并请求应说明问题、最终行为、兼容性影响和验证命令。一个合并请求尽量只解决一个主题。
+安全问题不要创建公开 Issue，请按 [安全策略](SECURITY.md) 报告。
+
+提交贡献即表示你有权提交这些内容，并同意按项目的 Apache-2.0 许可证发布。