人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载openJiuwen agent-core 是一套覆盖 AI Agent 开发、运行、调优与演进全链路的 Python SDK代码规模庞大core、agent_teams、harness、agent_evolving 等数十个子包。为了保证多模块协同开发时代码可读、可维护、可静态检查仓库在 .claude/rules/code-style.md 中沉淀了一套硬性代码风格规范并在 pyproject.toml 与 Makefile 中固化为可执行的工具链。本文将逐条拆解这套规范并结合仓库源码说明其底层实现与落地方式读完你既能理解 openJiuwen 的编码约定也能将其直接复用到自己的 Python 项目中。语言与格式化基线Python 3.11 与 Ruff规范的第一层约束是运行环境与工具链基线Python 3.11 是硬性要求仓库在 pyproject.toml 中声明requires-python 3.11,3.14并在[tool.ruff]中设置target-version py311同时 mypy 也以python_version 3.11做类型检查基线三者保持一致。Ruff 行宽 120 字符[tool.ruff] line-length 120pylint 的max-line-length 120同步对齐保证 formatter、linter 与代码审查的标准完全统一。Ruff 是主力的 formatter/lintermake fix一键自动修复内部等价于ruff check --fixruff format两个阶段。引入新模式前先匹配周边模块风格优先沿用同目录既有写法避免同一模块内风格割裂。新公共 API 必须带类型注解docstring 与所在模块保持一致mypy 配置中check_untyped_defs true即未标注的函数也会被检查返回类型一致性。工具链层面的细节值得展开。Ruff 的 lint 规则集在[tool.ruff.lint]中显式声明为select [E, F, I, ASYNC]覆盖规则族含义典型作用Epycodestyle 错误行宽、空白等格式问题Fpyflakes 错误未使用导入/变量、未定义名称Iisort导入顺序与分组ASYNCflake8-async异步代码正确性如asyncio.sleep、阻塞调用同时extend-ignore [E203]并附有详细注释说明Ruff formatterBlack 风格会在含复杂表达式的切片中:前插入空格因此需要关闭 E203 以避免 formatter 与 linter 互相打架。[tool.ruff.format]还规定quote-style double、skip-magic-trailing-comma false尊重魔法尾逗号作为“强制多行”的显式信号、docstring-code-format truedocstring 内的代码块也参与格式化。用 Makefile 固化格式检查与自动修复流程规范中提到的make fix在 Makefile 中有完整定义。该 Makefile 是跨平台设计同时兼容 cmd.exe / PowerShell / Git Bash核心目标与等价命令如下Make 目标等价命令作用make fixmake fix-lintmake fix-format一键自动修复先ruff check --fix自动修复可安全修复的 lint 问题再ruff format格式化make formatruff check --select Iruff format --check只检查不修改导入顺序 格式make lintruff check --show-fixeslint 检查并展示可修复项make pylintpylint files更全面的静态分析含设计约束make spellingcodespell files拼写检查make type-checkmypy files类型检查make checkformat → spelling → lint → pylint提交前全量检查值得注意的两个机制只检查变更文件所有检查目标都依赖has-staged-changes通过git diff --name-only默认检查已暂存改动设置COMMITSN则检查最近 N 次提交过滤出.py/.pyi文件后再执行检查避免每次全库扫描拖慢迭代。uv 自动探测UV ? $(strip $(shell uv --version ...))环境存在 uv 时用uv run执行否则回退到python -m保证不同开发环境的命令一致性。pylint 还附带设计层面的约束[tool.pylint.DESIGN]限制max-args 10、max-locals 15、max-branches 25、max-return 5并加载pylint.extensions.bad_builtin插件将print列为坏内建函数——这与下面的日志规范遥相呼应。异步安全库代码的第一优先级规范对异步安全的要求非常明确库代码必须异步安全除非该模块已刻意如此否则禁止在 async 路径中做阻塞调用。Ruff 的ASYNC规则族是这条约束的静态检查抓手。异步文件 I/O 优先用aiofiles或asyncio.to_thread()禁止直接同步open()。仓库在 pyproject.toml 的依赖中声明了aiofiles25.1.0同时filelock、portalocker等文件锁库也均为多线程/多进程场景设计说明异步并发是该 SDK 的基础运行模式。这一约定在整个日志子系统中体现得最为彻底。在 openjiuwen/core/common/logging/CLAUDE.md 中明确写着“异步安全是第一优先级”上下文传播使用contextvars.ContextVarset_session_id/set_member_id并明文禁止threading.local()——因为它在asyncio.Task之间会泄漏状态LogManager刻意不设 threading lock整个设计面向 asyncio GIL 的并发模型loguru后端通过enqueueTrue走进程内队列保证 sink 并发安全。这些都属于规范中“避免阻塞调用、保持 async-safe”原则在真实模块中的落地。日志规范禁用 print()统一命名 logger规范中日志部分的硬性要求是库代码禁止使用print()。注意 pyproject.toml 中[tool.pylint.DEPRECATED BUILTINS] bad-functions [print]从静态检查层面直接封杀。必须从openjiuwen.core.common.logging导入命名 logger如agent_logger、workflow_logger、llm_logger等。完整规则见 .claude/rules/logging.md。这些命名 logger 在 openjiuwen/core/common/logging/init.py 中统一定义全部是LazyLogger实例# 模块级懒加载 loggerimport 零副作用首次访问方法时才绑定真实 logger agent_logger LazyLogger(lambda: LogManager.get_logger(agent)) workflow_logger LazyLogger(lambda: LogManager.get_logger(workflow)) llm_logger LazyLogger(lambda: LogManager.get_logger(llm)) tool_logger LazyLogger(lambda: LogManager.get_logger(tool)) memory_logger LazyLogger(lambda: LogManager.get_logger(memory)) retrieval_logger LazyLogger(lambda: LogManager.get_logger(retrieval)) team_logger LazyLogger(lambda: LogManager.get_logger(team))LazyLogger的设计见同文件第 59~98 行保证了两个关键语义模块 import 时不触发LogManager.initialize()这是整个启动路径的性能约束配置变更后LogManager.reset()会回调reset_lazy_loggers()清空所有缓存使 logger 在下次使用时重新绑定到新配置。因此规范禁止在库代码中直接logging.getLogger(__name__)或裸用 loguru logger——这两种方式都会绕过配置层与 backend 切换机制。对应的日志书写规范见 .claude/rules/logging.md还包括使用懒占位符而非 f-stringlogger.debug(got %s items, count)因为 f-string 无条件求值、异常路径用logger.exception(msg)、结构化事件通过create_log_event发射且新字段必须先加到events.py的 dataclass 白名单。命名规范Card、Config/Manager/Runner 的固定模式命名部分要求遵循 PEP 8 Ruff 默认值并给出两类非常具体的类型命名约定Card 类型身份/元数据AgentCard、ToolCard、WorkflowCard、SysOperationCard这些命名与仓库源码一一对应AgentCard定义于 openjiuwen/core/single_agent/schema/agent_card.pyToolCard在 openjiuwen/core/foundation/tool/base.pyWorkflowCard在 openjiuwen/core/workflow/base.pySysOperationCard在 openjiuwen/core/sys_operation/sys_operation.py。它们构成 Agent 生态中各实体的统一“身份证”是 schema 层的核心类型。配置/管理/运行时类型FeatureConfig、FeatureManager、FeatureRunner。这在日志子系统中同样能找到例证——LogConfig配置快照与LogManager运行时持有 backend 类与实例缓存就是“配置是纯数据、Manager 是运行时”的命名分层典范见 openjiuwen/core/common/logging/CLAUDE.md 第 53~55 行。另外类型别名与 schema 类放在schema/或types/子目录这一约定在整个仓库目录结构中随处可见如single_agent/schema/、harness_protocol/下的models.py、types.py。导入规范绝对导入、禁用通配符、三组分类导入部分的规则简洁但明确openjiuwen包内一律使用绝对导入。这与仓库pythonpath [jiuwen]的 pytest 配置以及 setuptools 的包发现方式include [openjiuwen*]相配合保证包内引用路径清晰、可重定位。库代码禁用通配符导入from module import *。这也是 RuffF规则族pyflakes自动捕获的问题。导入按 stdlib → 第三方 → 本地/相对分组由 Ruff 自动处理I规则族isort。make fix-format中的ruff check --select I --fix正是为此服务的。文件组织一模块一公共类__init__.py最小化最后是文件组织约定每个模块优先只放一个公共类小型的相关工具函数可以共用模块。这保证了模块命名即类名、检索成本最低也是 openJiuwen 各子包普遍呈现的组织形态。私有实现细节以_或__开头将公共 API 面与非公共实现清晰隔离。__init__.py只导出公共面保持最小化。openjiuwen/core/common/logging/init.py 是这一约定的直接示范模块内部还有manager.py、log_config.py、base_impl.py、default/、loguru/等大量实现文件但__init__.py只 re-export 公开符号LoggerProtocol、LogManager、各命名 logger、事件类型与工具函数并通过__all__明确定义公共边界外部代码只能从这里引用。总结一条可落地的 Python 工程化规范闭环openJiuwen agent-core 的代码风格规范并非停留在文档层面的口号而是形成了一条完整闭环规范文档code-style.md / logging.md→ 工具配置pyproject.toml 的 ruff/pylint/mypy→ 一键命令Makefile 的 fix/check→ 源码落地LazyLogger、Card 类型、日志子系统。对于希望规范自身 Python 项目的开发者可以按以下清单快速落地在 pyproject.toml 配置 Ruffline-length 120、target-version py311、select[E, F, I, ASYNC]、ignoreE203用 Makefile 封装fixruff check --fixruff format与checkformat/spelling/lint/pylint目标并只检查 git 变更文件建立统一日志入口如LazyLogger 命名空间 logger在 pylint 中把print列为 bad-builtin约定类型命名模式*Card/*Config/*Manager/*Runner并让__init__.py只暴露公共面。这套规范与 openJiuwen 的日志架构、schema 设计、异步运行时等核心机制深度耦合是理解该项目代码组织方式的第一把钥匙。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐Dependabot Core代码格式化统一风格的代码规范Dependabot Core代码格式化统一风格的代码规范 痛点多语言依赖管理中的代码一致性挑战 作为GitHub官方的自动化依赖更新工具Dependab开发工具后端安全供应链安全1BRC代码风格统一代码风格与格式化规范1BRC代码风格统一代码风格与格式化规范 概述 在十亿行挑战1BRC这个高性能计算项目中代码风格的一致性对于项目维护和性能优化至关重要。本文深入探讨1B性能测试大数据M9A 代码格式化规范prettier 与 ruff 双引擎统一仓库代码与资源风格M9A 代码格式化规范prettier 与 ruff 双引擎统一仓库代码与资源风格 M9A重返未来1999 小助手是一个同时包含 Python 自动化逻GUI 自动化AI 应用上一篇Context Hub 文档精讲用 aws-sdk/client-bedrock-runtime 在 Node.js 中调用 Amazon Bedrock 推理 API下一篇解密AMD显卡驱动精简革命Radeon Software Slimmer如何重塑你的游戏体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考