bumaren-agent-workflow 0.1.6__tar.gz

bumaren_agent_workflow-0.1.6/.github/workflows/publish-pypi.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: python -m pip install --upgrade build && python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bumaren-agent-workflow
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

bumaren_agent_workflow-0.1.6/.gitignore

@@ -0,0 +1,4 @@
+__pycache__
+.venv
+.claude
+.vscode

bumaren_agent_workflow-0.1.6/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 更新日志
+
+本项目的版本记录遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [未发布]
+
+## [0.1.1] - 2026-08-20
+
+### 修复
+- 同步 `pyproject.toml` 中的包版本到 `0.1.1`，使 PyPI 发布工作流的标签校验与发布标签一致。
+
+## [0.1.0] - 2026-08-06
+
+### 新增
+- 框架层：`engine`（工作流引擎）、`agent`（能力挂载层）、`state`（共享状态）、
+  `llm`（LLM 抽象层）、`tools`（工具系统）。
+- 控制流原语：`Sequence`、`Loop`、`ForEach`、`Checkpoint`、`Breaker`（提前终止）、
+  `Continuer`（驱动 Loop 重开下一轮）。
+- 场景层挂载点 `scenarios/`，含 `scenarios/example/`（测试用例设计工作流）示例场景。
+- 场景开发指南 [`scenarios/development-guide.md`](scenarios/development-guide.md)。
+- 开源合规文件：`LICENSE`（MIT）、`CONTRIBUTING.md`、`CODE_OF_CONDUCT.md`。
+
+[未发布]: https://github.com/BuMaRen/miniagent/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/BuMaRen/miniagent/releases/tag/v0.1.1
+[0.1.0]: https://github.com/BuMaRen/miniagent/releases/tag/v0.1.0

bumaren_agent_workflow-0.1.6/CODE_OF_CONDUCT.md

@@ -0,0 +1,82 @@
+# 贡献者公约（Contributor Covenant）行为准则
+
+## 我们的承诺
+
+身为社区成员、贡献者与维护者，我们承诺让每个人都能在无骚扰的环境下参与本项目，无论其年龄、体型、
+可见或不可见的残疾、族裔、性别特征、性别认同与表达、经验水平、教育程度、社会经济地位、国籍、
+个人外貌、种族、宗教信仰，或性取向与性认同为何。
+
+我们承诺以有助于建立开放、友善、多元、包容、健康社区的方式行事和互动。
+
+## 我们的准则
+
+有助于营造积极环境的行为包括：
+
+- 展现同理心与善意
+- 尊重不同的观点、立场与经验
+- 给予并优雅地接受建设性反馈
+- 为自己的错误承担责任、向受影响者道歉，并从中学习
+- 关注对社区整体最有利的事，而不仅是个人利益
+
+不可接受的行为包括：
+
+- 使用与性有关的语言或图像，以及任何形式的性骚扰
+- 挑衅、侮辱性或贬损性的言论，以及人身或政治攻击
+- 公开或私下的骚扰
+- 未经明确许可，发布他人的私人信息（如实际地址或电子邮件地址）
+- 在专业场合中可被合理认定为不当的其他行为
+
+## 执行责任
+
+项目维护者负责阐明并执行我们对可接受行为的标准，并会针对任何被认为不当、具威胁性、冒犯性或
+有害的行为采取适当且公正的纠正措施。
+
+维护者有权且有责任移除、编辑或拒绝与本准则不符的评论、提交（commit）、代码、wiki 编辑、
+Issue 及其他贡献，并在适当时说明理由。
+
+## 适用范围
+
+本准则适用于项目所有的空间，也适用于个人在公共场合代表社区时的行为，例如使用官方邮箱、
+通过官方社交媒体账号发帖，或在线上/线下活动中担任指定代表。
+
+## 执行方式
+
+如遇辱骂、骚扰或其他不可接受的行为，可通过 <masha961110@gmail.com> 向项目维护者举报。
+所有投诉都将被及时、公正地审查与调查。
+
+所有维护者都有义务尊重举报人的隐私与安全。
+
+## 执行准则
+
+项目维护者在判定违反本准则的行为后果时，将参考以下社区影响准则：
+
+### 1. 纠正
+
+**社区影响**：使用不当言语或其他被认为不专业或不受欢迎的行为。
+
+**后果**：由维护者私下书面警告，说明违规性质并解释为何该行为不当，可能会要求公开道歉。
+
+### 2. 警告
+
+**社区影响**：单次或多次事件违规。
+
+**后果**：警告并附带后续行为的相应后果。在指定时间内，不得与相关人员互动，包括主动与执行准则者
+互动。违反此条款可能导致临时或永久封禁。
+
+### 3. 临时封禁
+
+**社区影响**：严重违反社区准则，包括持续的不当行为。
+
+**后果**：在指定时间内，暂时禁止与社区进行任何形式的互动或公开交流。违反此条款可能导致永久封禁。
+
+### 4. 永久封禁
+
+**社区影响**：表现出违反社区准则的行为模式，包括持续的不当行为、骚扰个人，或对某类个人的攻击
+或贬低。
+
+**后果**：永久禁止在项目社区内进行任何形式的公开互动。
+
+## 出处
+
+本准则改编自 [Contributor Covenant](https://www.contributor-covenant.org) 2.1 版，
+原文见 <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>。

bumaren_agent_workflow-0.1.6/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# 贡献指南
+
+感谢你对 MiniAgent 感兴趣！在提交 Issue 或 PR 之前，请花几分钟阅读本指南。
+
+## 项目定位
+
+在动手之前，建议先读一遍 [README.md](README.md)，
+理解框架层（`engine`/`agent`/`state`/`llm`/`tools`）与场景层（`scenarios/`）的边界：
+
+- **框架层**的改动应保持场景无关，任何看起来像"为了某个场景而加"的字段/分支，通常说明设计错了地方。
+- **场景层**的改动（新增/扩展场景）不需要动框架结构，只需要拼装既有原语、开发对应 ToolSet。
+
+## 开发环境
+
+```bash
+git clone https://github.com/BuMaRen/miniagent.git
+cd miniagent
+pip install -r requirements.txt
+```
+
+框架层测试仅依赖标准库 `unittest`：
+
+```bash
+python3 -m unittest discover -s tests -t .
+```
+
+## 提交 Issue
+
+- Bug 报告请附上复现步骤、期望行为与实际行为。
+- 功能建议请先说明用例，尤其是"这属于框架层还是场景层"，方便判断是否符合项目定位。
+
+## 提交 Pull Request
+
+1. Fork 仓库，基于 `main` 创建分支（建议命名 `feat/xxx`、`fix/xxx`）。
+2. 改动前先确认涉及范围：框架结构改动请附带设计理由；场景/ToolSet 改动尽量自包含。
+3. 提交前本地跑一遍测试，新增功能请补充对应的单元测试。
+4. Commit message 遵循 [Conventional Commits](https://www.conventionalcommits.org/)，例如：
+
+   ```
+   feat(engine): add retry policy to Loop primitive
+   fix(state): correct patch merge for nested paths
+   docs: update framework design doc section 8
+   ```
+
+5. PR 描述中说明改动动机（why）而不仅是改动内容（what），并关联相关 Issue。
+
+## 代码风格
+
+- Python 代码遵循项目现有风格，无强制 linter 配置时以可读性和与相邻代码一致为准。
+- 避免为假设中的未来需求做设计；框架层的抽象改动请先在 Issue 中讨论。
+
+## 许可
+
+提交贡献即表示你同意你的代码以本项目的 [MIT License](LICENSE) 授权发布。

bumaren_agent_workflow-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BuMaRen
+
+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.

bumaren_agent_workflow-0.1.6/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: bumaren-agent-workflow
+Version: 0.1.6
+Summary: A reusable, scenario-agnostic AI workflow framework.
+Author: BuMaRen
+License: MIT License
+        
+        Copyright (c) 2026 BuMaRen
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/BuMaRen/miniagent
+Project-URL: Repository, https://github.com/BuMaRen/miniagent
+Project-URL: Issues, https://github.com/BuMaRen/miniagent/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai==1.68.2
+Requires-Dist: anthropic==0.120.0
+Requires-Dist: zai-sdk==0.2.3
+Requires-Dist: pyyaml==6.0.3
+Dynamic: license-file
+
+# MiniAgent
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+一个**与场景无关**的可复用 AI 工作流框架:提供 Stage(阶段)、ToolSet(能力挂载)、State Store(共享状态)、Loop(评审-修订循环)、ForEach(遍历子流程)、Checkpoint(人工断点)等通用构件。二次开发一个具体场景,通常只需要"定义 State Schema + 拼装这些原语 + 挂载/开发对应 ToolSet",而不需要重新设计流程结构。
+
+当前已有一个示例场景用于验证这套抽象是否好用,具体内容见 [scenarios/development-guide.md](scenarios/development-guide.md)。二次开发/专业化某个场景时,预期的改动方式是打磨/扩充对应 Stage 上挂载的 ToolSet,而不是改动引擎结构。
+
+## 项目定位
+
+- **框架层**:Stage、ToolSet、State Store、Loop、ForEach、Checkpoint、Breaker、Continuer 等通用构件,不绑定任何具体场景,理论上可复用于代码审查、报告撰写等其他多阶段生成任务。这是二次开发时应该复用、不应该改动结构的部分。
+- **场景层**:`scenarios/example/`(测试用例设计工作流)是当前用来验证这套抽象是否好用的具体实例——用框架原语拼出流程,并挂载场景专属的 ToolSet 与 State Schema。
+
+## 项目结构
+
+框架层(`engine`/`agent`/`state`/`llm`/`tools`)不含任何场景语义,场景层内容全部落在 `scenarios/` 下。
+
+```
+miniagent/
+├── engine/                     # 工作流引擎(框架核心,场景无关)
+│   ├── stage.py                #   Stage:输入→输出契约 + Node 统一协议
+│   ├── context.py              #   RunContext:运行期共享上下文 + 生命周期 hook
+│   ├── workflow.py             #   Workflow:顶层节点编排 + 失败续跑(WorkflowFailure)
+│   └── primitives/             #   控制流原语
+│       ├── sequence.py         #     顺序执行
+│       ├── loop.py             #     迭代:同一份输入反复跑 body,配合 Breaker/Continuer 判定退出/重开(含超限策略)
+│       ├── foreach.py          #     遍历子流程
+│       ├── checkpoint.py       #     人工断点(同步问答)
+│       ├── breaker.py          #     提前终止 Loop/ForEach(相当于 break)
+│       └── continuer.py        #     跳过本轮、从 body 头重开下一轮(仅对 Loop 生效,相当于 continue)
+│
+├── agent/                      # 能力挂载层
+│   ├── agent.py                #   Agent = LLM + 工具 + 工具集 + 记忆(agentic loop)
+│   ├── toolset.py              #   ToolSet:一组 (func, schema)
+│   └── memory.py               #   对话记忆(短期,区别于 State Store)
+│
+├── state/                      # 共享状态
+│   ├── store.py                #   StateStore 抽象:get/patch/append/slice/snapshot
+│   ├── schema.py               #   StateSchema:场景方定义字段与校验
+│   └── backends/               #   内存后端 + JSON 文件后端(断点恢复)
+│
+├── llm/                        # LLM 抽象层
+│   ├── client.py               #   LLMClient 接口 + ChatResponse
+│   ├── message.py              #   Message / ToolCall 标准结构
+│   └── providers/               #   OpenAI / Anthropic / 智谱(zai-sdk)实现
+│
+├── tools/                      # 工具系统
+│   ├── schema.py               #   ToolSchema + schema_from_func(自动生成)
+│   ├── registry.py             #   ToolRegistry
+│   └── executor.py             #   ToolExecutor(安全执行 + 异常回填)
+│
+└── scenarios/                  # 场景层:二次开发挂载点(见 scenarios/development-guide.md)
+```
+
+场景方直接用 Python 组合 `Stage` 与 `engine/primitives/` 下的控制流原语拼出
+`Workflow`(见 `scenarios/example/workflow.py`),
+不存在从 YAML 等声明式定义编译节点这一层——详见 [scenarios/development-guide.md](scenarios/development-guide.md)。
+
+## 关键设计点
+
+1. **Node 统一协议** — Stage 和各控制流原语都实现 `run(ctx, inputs)`,因此能任意嵌套(`ForEach` 的 body 可以是 `Loop`)。这是"用少量原语组合出任意流程"的基础。
+2. **reads/writes 声明式** — Stage 显式声明需要读写的状态切片,既能只向 LLM 注入相关上下文(控制成本),又能做依赖分析(判断哪些 Stage 可并行)。
+3. **Loop 的退出与超限策略** — 是否重开下一轮/提前结束由放进 body 里的普通 Node 决定:`Continuer` 相当于 `continue`(跳过本轮剩余节点,从 body 头重开),`Breaker` 相当于 `break`(终止最近的外层 Loop/ForEach)。判定逻辑放在场景自己的 Node 里,引擎不认识任何业务字段名;超限则有 `accept_last / escalate_to_checkpoint / raise` 三种策略,杜绝死循环。
+4. **两种记忆分离** — `agent/memory.py` 是单次 Agent 运行内的短期对话记忆;`state/` 是跨 Stage 的长期结构化事实。用摘要保证连贯,用结构化状态保证事实一致,职责分开。
+5. **能力通过 ToolSet 挂载,而非改结构** — 换场景/做专业化的预期改动是"换一套 ToolSet + 换一份 State Schema",Stage/Loop/ForEach 的骨架不动。
+
+## 运行测试
+
+框架层的单元测试在 `tests/`(镜像 `engine`/`agent`/`state`/`llm`/`tools` 的目录结构),只用标准库 `unittest`,无需额外依赖即可跑：
+
+```
+python3 -m unittest discover -s tests -t .
+```
+
+`tests/llm/test_openai_provider.py`、`tests/llm/test_anthropic_provider.py`、`tests/llm/test_zhipu_provider.py` 覆盖三个 Provider 的消息格式转换;若未安装对应的 `openai`/`anthropic`/`zai-sdk`(`requirements.txt` 里的三个依赖),对应的文件会自动跳过而非报错。
+
+## 安装
+
+发布到 PyPI 后,在其他项目中安装:
+
+```
+pip install bumaren-agent-workflow
+```
+
+版本由 Git 标签自动生成;发布时推送形如 `v0.1.3` 的新标签即可:
+
+```
+git tag v0.1.3
+git push origin v0.1.3
+```
+
+首次发布前,在 PyPI 的 `Publishing` 页面添加一个 pending Trusted Publisher:
+owner 为 `BuMaRen`, repository 为 `miniagent`, workflow 为 `publish-pypi.yml`, environment
+为 `pypi`。后续发布无需保存 PyPI token 到 GitHub Secrets。
+
+## 二次开发一个新场景
+
+参见 [scenarios/development-guide.md](scenarios/development-guide.md)。典型步骤:
+
+1. 定义 `state_schema.py`(该场景要跨步骤追踪哪些事实,用 `state.schema.StateSchema` 直接构造)。
+2. 开发 `toolsets/`(每个 Stage 需要的工具集,**主要工作量所在**)。
+3. 写 `prompts.py`(每个 Agent 的提示词;共享片段提成模块级常量复用)。
+4. 在 `nodes/` 下按业务分组,每个模块提供 `build_xxx_stage()` 函数:声明节点的 executor / reads / writes / output_schema / tools / prompt。
+5. 在 `workflow.py` 的 `build_workflow()` 里用 `Sequence`/`Loop`/`ForEach`/`Checkpoint` 直接拼出流程。
+6. 在 `run.py` 里组装 LLMClient / StateStore / RunContext 并运行。
+
+参见 `scenarios/example/` 这一个完整范例。
+
+## 文档
+
+- [scenarios/development-guide.md](scenarios/development-guide.md) — **场景开发指南**:动手向导,一步步把框架构件拼成一个新场景
+
+## 状态
+
+v0.1.1:框架层(`tools/` → `llm/` → `state/` → `agent/` → `engine/`)与首个场景 `scenarios/example/`(测试用例设计工作流)均已实现,`tests/` 下有对应单元测试覆盖。

bumaren_agent_workflow-0.1.6/README.md

@@ -0,0 +1,115 @@
+# MiniAgent
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+一个**与场景无关**的可复用 AI 工作流框架:提供 Stage(阶段)、ToolSet(能力挂载)、State Store(共享状态)、Loop(评审-修订循环)、ForEach(遍历子流程)、Checkpoint(人工断点)等通用构件。二次开发一个具体场景,通常只需要"定义 State Schema + 拼装这些原语 + 挂载/开发对应 ToolSet",而不需要重新设计流程结构。
+
+当前已有一个示例场景用于验证这套抽象是否好用,具体内容见 [scenarios/development-guide.md](scenarios/development-guide.md)。二次开发/专业化某个场景时,预期的改动方式是打磨/扩充对应 Stage 上挂载的 ToolSet,而不是改动引擎结构。
+
+## 项目定位
+
+- **框架层**:Stage、ToolSet、State Store、Loop、ForEach、Checkpoint、Breaker、Continuer 等通用构件,不绑定任何具体场景,理论上可复用于代码审查、报告撰写等其他多阶段生成任务。这是二次开发时应该复用、不应该改动结构的部分。
+- **场景层**:`scenarios/example/`(测试用例设计工作流)是当前用来验证这套抽象是否好用的具体实例——用框架原语拼出流程,并挂载场景专属的 ToolSet 与 State Schema。
+
+## 项目结构
+
+框架层(`engine`/`agent`/`state`/`llm`/`tools`)不含任何场景语义,场景层内容全部落在 `scenarios/` 下。
+
+```
+miniagent/
+├── engine/                     # 工作流引擎(框架核心,场景无关)
+│   ├── stage.py                #   Stage:输入→输出契约 + Node 统一协议
+│   ├── context.py              #   RunContext:运行期共享上下文 + 生命周期 hook
+│   ├── workflow.py             #   Workflow:顶层节点编排 + 失败续跑(WorkflowFailure)
+│   └── primitives/             #   控制流原语
+│       ├── sequence.py         #     顺序执行
+│       ├── loop.py             #     迭代:同一份输入反复跑 body,配合 Breaker/Continuer 判定退出/重开(含超限策略)
+│       ├── foreach.py          #     遍历子流程
+│       ├── checkpoint.py       #     人工断点(同步问答)
+│       ├── breaker.py          #     提前终止 Loop/ForEach(相当于 break)
+│       └── continuer.py        #     跳过本轮、从 body 头重开下一轮(仅对 Loop 生效,相当于 continue)
+│
+├── agent/                      # 能力挂载层
+│   ├── agent.py                #   Agent = LLM + 工具 + 工具集 + 记忆(agentic loop)
+│   ├── toolset.py              #   ToolSet:一组 (func, schema)
+│   └── memory.py               #   对话记忆(短期,区别于 State Store)
+│
+├── state/                      # 共享状态
+│   ├── store.py                #   StateStore 抽象:get/patch/append/slice/snapshot
+│   ├── schema.py               #   StateSchema:场景方定义字段与校验
+│   └── backends/               #   内存后端 + JSON 文件后端(断点恢复)
+│
+├── llm/                        # LLM 抽象层
+│   ├── client.py               #   LLMClient 接口 + ChatResponse
+│   ├── message.py              #   Message / ToolCall 标准结构
+│   └── providers/               #   OpenAI / Anthropic / 智谱(zai-sdk)实现
+│
+├── tools/                      # 工具系统
+│   ├── schema.py               #   ToolSchema + schema_from_func(自动生成)
+│   ├── registry.py             #   ToolRegistry
+│   └── executor.py             #   ToolExecutor(安全执行 + 异常回填)
+│
+└── scenarios/                  # 场景层:二次开发挂载点(见 scenarios/development-guide.md)
+```
+
+场景方直接用 Python 组合 `Stage` 与 `engine/primitives/` 下的控制流原语拼出
+`Workflow`(见 `scenarios/example/workflow.py`),
+不存在从 YAML 等声明式定义编译节点这一层——详见 [scenarios/development-guide.md](scenarios/development-guide.md)。
+
+## 关键设计点
+
+1. **Node 统一协议** — Stage 和各控制流原语都实现 `run(ctx, inputs)`,因此能任意嵌套(`ForEach` 的 body 可以是 `Loop`)。这是"用少量原语组合出任意流程"的基础。
+2. **reads/writes 声明式** — Stage 显式声明需要读写的状态切片,既能只向 LLM 注入相关上下文(控制成本),又能做依赖分析(判断哪些 Stage 可并行)。
+3. **Loop 的退出与超限策略** — 是否重开下一轮/提前结束由放进 body 里的普通 Node 决定:`Continuer` 相当于 `continue`(跳过本轮剩余节点,从 body 头重开),`Breaker` 相当于 `break`(终止最近的外层 Loop/ForEach)。判定逻辑放在场景自己的 Node 里,引擎不认识任何业务字段名;超限则有 `accept_last / escalate_to_checkpoint / raise` 三种策略,杜绝死循环。
+4. **两种记忆分离** — `agent/memory.py` 是单次 Agent 运行内的短期对话记忆;`state/` 是跨 Stage 的长期结构化事实。用摘要保证连贯,用结构化状态保证事实一致,职责分开。
+5. **能力通过 ToolSet 挂载,而非改结构** — 换场景/做专业化的预期改动是"换一套 ToolSet + 换一份 State Schema",Stage/Loop/ForEach 的骨架不动。
+
+## 运行测试
+
+框架层的单元测试在 `tests/`(镜像 `engine`/`agent`/`state`/`llm`/`tools` 的目录结构),只用标准库 `unittest`,无需额外依赖即可跑：
+
+```
+python3 -m unittest discover -s tests -t .
+```
+
+`tests/llm/test_openai_provider.py`、`tests/llm/test_anthropic_provider.py`、`tests/llm/test_zhipu_provider.py` 覆盖三个 Provider 的消息格式转换;若未安装对应的 `openai`/`anthropic`/`zai-sdk`(`requirements.txt` 里的三个依赖),对应的文件会自动跳过而非报错。
+
+## 安装
+
+发布到 PyPI 后,在其他项目中安装:
+
+```
+pip install bumaren-agent-workflow
+```
+
+版本由 Git 标签自动生成;发布时推送形如 `v0.1.3` 的新标签即可:
+
+```
+git tag v0.1.3
+git push origin v0.1.3
+```
+
+首次发布前,在 PyPI 的 `Publishing` 页面添加一个 pending Trusted Publisher:
+owner 为 `BuMaRen`, repository 为 `miniagent`, workflow 为 `publish-pypi.yml`, environment
+为 `pypi`。后续发布无需保存 PyPI token 到 GitHub Secrets。
+
+## 二次开发一个新场景
+
+参见 [scenarios/development-guide.md](scenarios/development-guide.md)。典型步骤:
+
+1. 定义 `state_schema.py`(该场景要跨步骤追踪哪些事实,用 `state.schema.StateSchema` 直接构造)。
+2. 开发 `toolsets/`(每个 Stage 需要的工具集,**主要工作量所在**)。
+3. 写 `prompts.py`(每个 Agent 的提示词;共享片段提成模块级常量复用)。
+4. 在 `nodes/` 下按业务分组,每个模块提供 `build_xxx_stage()` 函数:声明节点的 executor / reads / writes / output_schema / tools / prompt。
+5. 在 `workflow.py` 的 `build_workflow()` 里用 `Sequence`/`Loop`/`ForEach`/`Checkpoint` 直接拼出流程。
+6. 在 `run.py` 里组装 LLMClient / StateStore / RunContext 并运行。
+
+参见 `scenarios/example/` 这一个完整范例。
+
+## 文档
+
+- [scenarios/development-guide.md](scenarios/development-guide.md) — **场景开发指南**:动手向导,一步步把框架构件拼成一个新场景
+
+## 状态
+
+v0.1.1:框架层(`tools/` → `llm/` → `state/` → `agent/` → `engine/`)与首个场景 `scenarios/example/`(测试用例设计工作流)均已实现,`tests/` 下有对应单元测试覆盖。

bumaren_agent_workflow-0.1.6/agent/__init__.py

@@ -0,0 +1,20 @@
+"""Agent 与 ToolSet —— 场景能力的挂载点。
+
+Agent = LLM Client + ToolRegistry + ToolSets(工具集) + Memory。
+它是 Stage 的典型执行体(executor)。给同一个抽象 Stage 挂载不同 ToolSet,
+就得到不同场景下的能力——这正是"二次开发只需装 ToolSet"的核心机制。
+
+注意:这里的 ToolSet 是代码装配期显示挂载的一组 (tool_func, schema),
+与 Claude/OpenAI 的 "Skill"(运行时由模型自主发现/渐进式加载的磁盘目录)
+是不同层次的概念,不要混用。
+
+    Agent  —— 执行体:驱动一次 LLM + 工具调用循环完成 Stage
+    ToolSet  —— 一组 (tool_func, schema),可加载进 Agent
+    ConversationMemory —— Agent 的对话记忆
+"""
+
+from agent.agent import Agent
+from agent.toolset import ToolSet
+from agent.memory import ConversationMemory
+
+__all__ = ["Agent", "ToolSet", "ConversationMemory"]