Upsonic 开发指南CLAUDE.md 如何为 AI 编码助手装配一套可执行的仓库工作协议【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistantCLAUDE.md 是 Upsonic 仓库一个面向生产环境的 Python AI Agent 框架PyPI 包名upsonic的AI 操作总纲它规定了 AI 编码助手在修改本仓库代码前必须查阅哪些流程文档、如何保持子系统文档与代码契约同步、框架的核心架构与入口、开发命令、20 模型提供商的配置方式以及四层测试结构。读完本文你既能掌握 Upsonic 仓库的实际工程组织方式也能学到一套可以直接迁移到自己项目中的AI 助手协作协议 文档-代码同步实践方法。1. CLAUDE.md 是什么一个 always-apply 的仓库级 AI 指南仓库根目录下的 CLAUDE.md 在文件头部带有 YAML frontmatter--- description: alwaysApply: true ---alwaysApply: true表明该文件对 Claude Code 会话始终生效仓库根目录下也存在.claude/配置目录。文件开篇一句话点明用途This file provides guidance to Claude Code when working with code in this repository.也就是说它不是面向终端用户的 API 文档那是README.md与官方文档站而是面向在本仓库中干活的 AI的操作手册。全文由六个板块构成AI Operational Guides操作指南索引→ Core Architecture核心架构→ Development Commands开发命令→ Model Providers and Configuration模型提供商与配置→ Key Features / Testing Structure关键特性与测试结构→ Environment Variables / File Organization环境变量与文件组织。下面按原文脉络逐节展开并用仓库源码、配置佐证每一处断言。2. AI Operational Guides十份流程文档的分工与触发条件CLAUDE.md 的核心主张是Consult the relevant guide before doing the work — these are operational, not optional.动手之前先查对应指南这些是强制性操作规范不是可选项。documents/ai/guides/目录下的 10 份指南各自绑定一个工作场景原文档给出的完整分工如下指南文档触发场景定义的核心流程四阶段 硬门禁feature.md新增功能或非平凡增强新公共 API、新 providerVector/Model/Storage/Tool/Embedding/OCR/Loader、新 agent 类型、safety_engine/新策略、新 RAG 组件、既有类的新公共方法/配置项Understand → Design → Implement → Verify附 8 项横切检查清单与反模式refactor.md不改变可观察行为的内部结构调整重命名、抽取、拆分超大模块、删除死代码、机械迁移Motivate Scope → Characterize → Transform → Verify Behaviour Preservedbug-fix.md修复已报告的 bug、失败测试、traceback、与契约矛盾的行为Reproduce → Diagnose → Fix → Verify强调根因纪律、回归测试、最小 difftesting.md为任何功能/重构/修复推导、编写、评审或锁定测试Derive Scenarios → Generate RED Tests → Manual Review → Lock Iterate via Codecoding-standards.md常开always-on命名、类型标注、结构、格式、测试与评审的纯 Python 编码标准—serena.md常开何时/如何用 Serena MCP 做符号与引用查找源码只读约束可选的 Serena 记忆层—memory.md常开Claude Code 自动记忆机制——存放位置、自动加载 vs 懒加载、何时查阅、工作流结束时必须保存反思—subagents.md常开何时派发子代理重度读取、可分离的调查、长任务、规划/评审、何时不派发—new_prebuilt_agent_adding.md在src/upsonic/prebuilt/your_agent/下发布新的预置自主 agent定义 runtime/agent 类/template 三层结构、AGENT_REPO/AGENT_FOLDER与PrebuiltAutonomousAgentBase的接线、new_X(...)高层 API 约定—commit.md任何git commit、git push或历史重写命令之前硬规则未经用户明确批准绝不提交这些指南不是空泛的流程描述而是有真实内容的操作协议。例如 testing.md 明确写出测试纪律的四个阶段Phase 1 先由用户提供场景种子并锁定场景清单Scenario list locked. No additions / removals without approval.Phase 2 要求 RED First——先写测试、确认其对当前代码库全部失败Phase 3 是不可跳过的人工评审硬门禁列出五类必须打回的测试无生产改动也能通过的测试、名不副实的边界测试、依赖执行顺序的测试、mock 掉框架自身边界的测试、断言实现细节而非契约的测试Phase 4 锁定测试文件后行为变更只能走src/永不修改已锁定的测试。feature.md 则给出范围判据新增公共 API、src/upsonic/下的 provider、agent 类型、safety_engine/策略等属于 in-scopebug 修复、纯重构、typo、依赖升级属于 out-of-scope拿不准时默认走流程。commit.md 规定提交信息格式type(scope): subjecttype 取feat/fix/refactor/test/docs/chore/perf/style/build/ci主体行 ≤72 字符、祈使句、小写、无尾点。2.1 Default Pre-Work Consultation动手前的统一前置查阅CLAUDE.md 要求在任何非平凡任务之前常开指南合并成一次前置查阅动作——Claude Code 记忆 Serena 代码查找若激活则再加 Serena 记忆并在回复开头一并呈现发现例如From memory: prior feedback dont mock the DB. From Serena: existing similar handler atsrc/upsonic/X.py:42.琐碎工作单行 typo、注释编辑跳过此流程但必须显式声明Skipping memory / Serena lookup — single-line cosmetic edit.静默跳过是被禁止的。这套约定在两份常开指南中有完整展开。serena.md 规定三个 Serena MCP 工具的分工——find_symbol按名定位符号、find_referencing_symbols反向引用追踪、get_symbols_overview模块符号概览——并给出硬规则符号查询优先于grep避免误匹配文档/注释/字符串、Serena 对本仓库只读、查到什么必须展示什么。memory.md 规定自动记忆的加载模型MEMORY.md前 200 行或 25 KB在会话开始时自动加载主题文件feedback_*.md、project_*.md按需懒加载必须保存记忆的情形包括用户给出可泛化的纠正规则用户确认了一个非显而易见的选择发现代码里看不出的约定功能/重构/修复/测试流程结束时的强制反思——若没有值得保存的教训也要显式输出No memory-worthy learning from this task.值得注意的是memory.md 还专门澄清了 Anthropic API 的memory_20250818记忆工具与 Claude Code 自动记忆是两回事本仓库不使用前者serena.md 则说明.serena/memories/当前为空且被根.gitignore忽略Serena 记忆层currently unused。2.2 让documents/ai/explanation/与代码保持同步CLAUDE.md 中篇幅最大、也最具迁移价值的一节是 explanation 文档同步协议。它把documents/ai/explanation/subsystem/subsystem.md定位为各子系统行为契约的权威描述只要代码变更动摇了某个 explanation 文档断言的可观察契约就必须在同一 commit或紧随其后的docs: sync explanation/…commit里重新同步。对照当前仓库documents/ai/explanation/下正好为 38 个子系统各备一份文档agent、chat、models、storage、safety_engine、tools、team、ocr、ralph、skills等每个目录一个subsystem.md与src/upsonic/的子系统划分一一对应。而documents/ai/guides/是过程性文档只在流程变化时才改。几乎必然触发文档更新的六类改动原文清单公共方法/构造函数签名变化增删参数、新默认值、新的 keyword-only 要求副作用被新增、移除或变为有条件原文举例Chat.__init__不再无条件覆盖agent.memoryToolConfig/dataclass 默认值翻转或某个子类覆盖了泛型默认值异常路径改为优雅回退或反之既往文档化的不变量X always Y现在变成了有条件的新增了调用方可能观察到的公共发射UserWarning、日志行、事件。执行方法原文四步定位被触及的src/upsonic/模块grep -rln class or symbol documents/ai/explanation/找到文档及已过期的具体行外科手术式修改——只改断言失效的句子/表格不重写周边文字文档修改与代码变更放在同一逻辑变更块内若代码 commit 已推送在 PR 评审前补docs: sync explanation/…commit。纯内部改动私有 helper、注释修剪、保持全部可观察契约的重构可跳过但同样要声明发现例如TouchedChat.__init__storage wiring → resyncingdocuments/ai/explanation/chat/chat.mdlines 257–280.从源码结构看这套每个子系统一份契约文档 触发式同步机制实际上是把文档腐化问题从 CI 层面提前到了每次 PR 的自检清单层面。3. Core Architecture框架核心组件与主要入口CLAUDE.md 把 Upsonic 定位为a reliability-focused AI agent framework——一个以可靠性为核心卖点、面向生产级 AI agent 与数字员工的框架提供高级可靠性特性、MCP 集成并支持 20 AI 提供商。它列出的关键组件与仓库源码目录逐一可对应组件位置说明Agent Systemsrc/upsonic/agent/核心 agent 实现Direct类为主 agent 接口Agent/Direct主类位于 agent.py另有autonomous_agent/、deepagent/、pipeline/、context_managers/子模块Task Managementsrc/upsonic/tasks/任务定义与执行逻辑入口 tasks.pyTools MCPsrc/upsonic/tools/工具处理与外部工具管理含common_tools/、custom_tools/、mcp.py、registry.py 等Reliability Layersrc/upsonic/reliability_layer/verifier agent、editor agent 与迭代质量改进轮次Safety Enginesrc/upsonic/safety_engine/基于策略的内容过滤与强制policies/下有 17 个策略文件敏感内容、成人内容、加密资产、社媒等Storagesrc/upsonic/storage/多 provider 存储In-Memory、JSON、SQLite、Redis、PostgreSQL、MongoDB、mem0 等后端统一接口 base.pyTeam/Multi-Agentsrc/upsonic/team/团队协调与任务委派入口 team.pyKnowledge Base RAGsrc/upsonic/knowledge_base/KB 接口 knowledge_base.pyRAG 组件拆分在vectordb/向量库、embeddings/嵌入器、loaders/文档加载器、text_splitter/分块器、ocr/摄取用 OCRPrebuilt Autonomous Agentssrc/upsonic/prebuilt/agent/template/就绪即用的 agent打包 system prompt、first-message 模板与 skills共享基类 prebuilt_agent_base.py主要入口点原文四条Task任务定义与执行tasks.pyAgent/Direct主 agent 类agent.pyTeam多 agent 协调team.pyKnowledgeBaseRAG 与文档管理knowledge_base.py从 src/upsonic/init.py 的实现可以印证两个工程细节其一包内使用_lazy_import惰性导入机制把重依赖推迟到实际使用时加载保证最小安装保持最小这与 coding-standards.md可选重依赖必须函数内惰性导入的规则一致其二包初始化时会从当前工作目录加载.envoverrideFalse找不到时再回退向上搜索——这解释了 CLAUDE.md 环境变量一节的实用性用户只需在运行脚本的目录放一个.env即可注入 API key。4. Development Commands基于 uv 的环境、测试与工具链CLAUDE.md 给出的开发命令全部围绕uv包管理器pyproject.toml 中[tool.uv]要求required-version 0.10.0并默认启用dev依赖组。以下命令按原文完整保留4.1 环境安装# Install dependencies with uv uv sync # Install with optional dependency groups (umbrella groups: vectordb, storage, # models, embeddings, loaders, tools, ocr — per-provider groups also exist; # see [project.optional-dependencies] in pyproject.toml for the full list) uv sync --extra vectordb --extra storage --extra embeddings对照 pyproject.toml 的[project.optional-dependencies]这些伞形组确实存在且是组合语义storage组内部声明为upsonic[sqlite-storage]、upsonic[redis-storage]、upsonic[postgres-storage]、upsonic[mongo-storage]、upsonic[mem0-storage]五个 per-provider 组的聚合vectordb组聚合了 chromadb、faiss-cpu、pinecone、psycopg、pymilvus、qdrant-client、weaviate-client、pgvector、supermemory 等客户端。此外还有models、embeddings、loaders含 pdf/docx/html/csv/json/markdown/xml/yaml/docling 等 per-format 组、tools、ocr、mcp、safety-engine、otel、langfuse等组覆盖了 CLAUDE.md 提到的per-provider groups also exist。4.2 测试运行# Run all tests uv run pytest # Run a specific tier or subsystem (tiers: unit_tests, smoke_tests, integration_tests, doc_examples) uv run pytest tests/unit_tests/ # Run tests with coverage uv run pytest --covsrc/upsonic测试配置在 pytest.ini 中得到印证testpaths tests、asyncio_mode strict配合pytest-asyncio、python_files test_*.py并注册了integrationmarker可用-m not integration排除。CLAUDE.md 明确要求Use pytest with async support enabled与dev依赖组中的pytest-asyncio0.25.1、pytest-timeout2.3.1相对应。4.3 开发工具# Type checking uv run mypy src/ # Pre-commit hooks (runs automatically on commit) pre-commit run --all-files # Lock dependencies uv lock从仓库当前的 .pre-commit-config.yaml 看实际挂载的钩子为uv-pre-commit的uv-lock与uv-sync提交时自动更新并同步锁文件以及一个 local 钩子pytest执行uv run --all-extras pytest tests/unit_tests/——即提交前自动跑全量单测。而 coding-standards.md 描述的完整工具链还包括ruff format行宽 120、ruff check启用E/F/W/I/B/UP/SIM/PL规则、mypy --strict允许 narrowly-scoped 的# type: ignore[code]禁止裸 ignore。4.4 常见问题ModuleNotFoundErrorCLAUDE.md 专门给出一条排障路径# 若出现 ModuleNotFoundError: No module named upsonic重新安装并同步 uv pip uninstall upsonic uv sync然后重跑原命令。原文还以uv run test.py作为运行示例的示例命令需要说明的是当前仓库快照的根目录中并没有test.pyexamples/目录亦为空占位该命令应理解为运行你自己的示例脚本的占位写法实际可参考 tests/doc_examples/ 下的公开 API 用法示例。5. Model Providers and Configuration20 提供商的统一provider/model寻址CLAUDE.md 指出框架通过统一接口支持 20 AI 提供商具体实现位于src/upsonic/models/元数据集中在 model_registry.py。对照源码目录models/下确实按提供商一一成文件openai.py、anthropic.py、google.py、azure.py、bedrock.py、cohere.py、mistral.py、groq.py、cerebras.py、xai.py、together.py、openrouter.py、nvidia.py、sambanova.py、huggingface.py、moonshotai.py、github.py、grok.py、litellm.py、outlines.py、vllm.py、ollama.py、lmstudio.py、vercel.py、heroku.py等外加model_selector.py、settings.py、wrapper.py、instrumented.py等支撑文件每个 provider 的源文件里写明了确切的 env-var 名。原文列出的主要提供商与凭据约定OpenAI—OPENAI_API_KEYAnthropic—ANTHROPIC_API_KEYGoogleGemini、Azure OpenAIAzure 专属凭据、AWS Bedrock标准 AWS 凭据Cohere、Mistral、Groq、Cerebras、xAI / Grok、Together、OpenRouter、NVIDIA、SambaNova、HuggingFace、Ollama本地、VLLM本地、LMStudio本地等模型寻址格式为provider/model原文给出的示例是openai/gpt-4o、anthropic/claude-sonnet-4-6、anthropic/claude-opus-4-7。这一格式与 README.md 中的示例Agent(modelanthropic/claude-sonnet-4-5, ...)相互印证用户只需在构造Agent/AutonomousAgent/Task时传入该字符串无需单独实例化 provider 客户端。6. Key Features可靠性层、MCP、安全引擎与存储抽象CLAUDE.md 用四个小节概述了框架的差异化能力均可在源码中找到落点Reliability Layersrc/upsonic/reliability_layer/reliability_layer.py提供 verifier agent、editor agent 与迭代质量改进轮次目标是production-ready outputs。MCP Integration内置 Model Context Protocol 工具支持tools/mcp.py可对接生态中大量现有 MCP serverpyproject.toml中mcpextra 依赖mcp[cli]1.26.0与fastmcp2.14.5。Safety Engine基于策略的内容过滤与强制safety_engine/policies/ 下 17 个策略模块覆盖敏感内容、成人内容、加密资产、社媒等规则safety-engineextra 引入detoxify。Storage Abstraction统一存储接口storage/base.py支撑会话管理、记忆持久化与用户画像后端覆盖 In-Memory、JSON、SQLite、Redis、PostgreSQL、MongoDB另见 mem0 后端与 §4.1 的 storage extra 组对应。7. Testing Structure四层测试与 Docker 支撑的 smoke 层CLAUDE.md 规定测试按四层组织且放置规则与 feature.md §4.5 对齐——tests/目录结构与之一致tests/unit_tests/subsystem/— 无需网络、磁盘或运行中服务即可执行的纯逻辑测试当前含 agent、chat、culture、graph、rag、ralph、safety_engine、skills、task、team、tools、usage_registry 等子目录。tests/smoke_tests/subsystem/— 触碰外部服务、数据库、API 或文件系统的功能测试通过make smoke_tests运行Docker 支撑的真实服务。tests/integration_tests/— 跨子系统行为例如 agent storage tools 组合接线。tests/doc_examples/— 针对新公共 API 面的公开用法示例演练。tests/conftest.py存放共享 fixtures。从 Makefile 看smoke 层的运行机制很具体smoke_teststarget 先依赖deps_smoke执行uv sync --extra storage --extra faiss与docker_up在tests/smoke_tests/目录拉起 docker-compose 服务并轮询等待 healthy再执行uv run pytest tests/smoke_tests -v显式忽略 HITL 相关的两个手动用例另有docker_down、docker_restart、test_storage_only只跑tests/smoke_tests/memory等 target。compose 文件位于 tests/smoke_tests/docker-compose.yml配套说明在 tests/smoke_tests/DOCKER_SETUP.md。CLAUDE.md 还指明测试纪律工作流场景推导 → 先 RED → 人工评审 → 锁定详见 testing.md——即 §2 所述的锁定测试后行为只能从src/变更的闭环。8. Environment Variables 与 File Organization关键环境变量原文清单OPENAI_API_KEY、ANTHROPIC_API_KEY— AI 提供商凭据其余提供商见各自 provider 源文件中的 env-var 名UPSONIC_TELEMETRYFalse— 关闭遥测采集存储提供商的数据库连接串Redis、PostgreSQL 等文件组织原文清单与仓库实际布局一致源码src/upsonic/测试tests/四层结构见 §7AI 操作指南documents/ai/guides/过程协议见 §2其他文档README.md、行内 Google-style docstrings配置pyproject.toml、.pre-commit-config.yaml、pytest.ini依赖由uv管理锁定于uv.lock9. 这套模式对工程团队的借鉴价值把 CLAUDE.md 作为独立对象审视它实际上演示了三层可复用的实践为 AI 助手编写操作型而非描述型文档每份指南绑定明确触发场景何时用/何时不用、四阶段流程、硬门禁与反模式并大量使用 RFC 2119 语义的 MUST/SHOULD 措辞使AI 是否走流程成为可检验的合规问题而非风格偏好文档-代码契约的双向同步协议documents/ai/explanation/subsystem/subsystem.md作为子系统行为契约的权威描述配合六类触发器清单与四步手术式更新法把文档何时过期变成了确定性判定可追溯的知识回路memory/Serena 前置查阅必须把发现说出口、流程结束必须显式反思是否保存记忆、提交必须显式批准——这些规则的共同点是把AI 的静默行为全部强制显性化用户因此可以在每次回复开头审查 AI 的依据。以上全部结论均出自当前仓库的 CLAUDE.md、documents/ai/guides/ 十份指南、pyproject.toml、pytest.ini、Makefile、.pre-commit-config.yaml 与src/upsonic/源码结构适用于本仓库当前快照upsonic版本 0.77.3Python ≥ 3.10。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考