npcpy 智能体开发框架
用统一的 Python 框架构建多模型智能体、团队与知识图谱。
README 明示 Agent 默认带有 sh、python、edit_file、web_search 等高影响工具，CodingAgent 还会自动执行模型生成的代码，MCP 工具也可自动授予团队；材料未展示最小权限、逐次确认、沙箱、作用域限制或执行前预览，因此 least_privilege 与 user_confirmation 为 0。数据会流向本地或云端模型、远程 MCP、HuggingFace 等外部服务，但没有完整说明发送内容、保留策略或边界，故透明度仅 1。发布流程通过 GitHub secret 传递 PyPI 令牌且工作流权限为 contents: read，但没有面向用户的密钥管理、日志脱敏或隐私说明，敏感数据处理为 1。发布 action 固定到提交且 CI 会构建检查，但依赖普遍未锁定，Ollama 通过 curl 管道安装，lint 和多组测试允许失败，故依赖安全仅 1。文件写入、shell、网络、模型下载、训练和包发布等外部效果可从示例识别，但没有统一控制措施，外部效果为 1；没有撤销或恢复机制，rollback 为 0。仓库、项目名、组织版权、文档和 PyPI 指向清晰，故来源归属为 2；未验证的发布者身份仅视为未知，没有据此作额外负面推断。
README、测试文件和 CI 大体指向同一套 NPC、Agent、Team、工具及多提供商能力，但部分所谓测试只是顶层调用并打印结果，服务端、Windows、网络和集成测试多处 continue-on-error 或“|| true”，lint 也不阻断，因此自洽性仅 1。支持 Python 3.10–3.12、本地与多种云提供商，并有 lite 安装和构建检查，依赖可获得性为 2；但大量模型、服务和可选生态依赖外部下载或凭据，未达到全面水平。失败信息主要是 pytest 输出和 CI 汇总，未见统一的用户级错误分类、恢复建议或提供商故障处理，所以为 1。
材料覆盖研究、代码、图像、知识图谱、多智能体、服务端和结构化输出等多种场景，并提供多种模型与提供商配置，因此受众场景和环境适配各为 2。另一方面，能力范围极宽，缺少明确的不适用场景、安全边界、资源上限和支持矩阵，capability_boundaries 仅 1。角色指令、工具描述和 jinx 描述可辅助触发，但默认工具集与自然语言编排缺少确定的授权或触发规则，因此 trigger_precision 为 1。
README 采用分节、折叠示例和项目树，信息较丰富但在所给截断材料中缺少完整导航、API 参考和运维结构，信息架构为 2。安装仅给出 pip install 和部分 CI 依赖步骤，未完整说明可选 extras、系统依赖、凭据与提供商配置，install_notes 为 1。NPC、Agent、ToolAgent、CodingAgent、Team、NPCArray、jinx 等名称总体稳定，但入口导入方式存在变化且概念数量较多，命名稳定性为 2。示例覆盖面和具体程度很高，examples_and_faq 为 3。没有明确的已知限制章节，故为 0。独立 MIT LICENSE 与 README 徽章一致，license 为 3。仅能看到 PyPI 徽章、发布触发和自动发布流程，没有 changelog、兼容策略或迁移说明，版本记录为 1。组织版权和自动发布路径可见，但缺少明确维护者、支持渠道和安全报告责任，maintenance_responsibility 为 1。
框架展示了普通文本、流式、JSON、Pydantic、多智能体集合及服务端输出，结果通常可直接消费，因此 output_usability 为 2；不过示例输出没有静态验证契约或错误模式。它把多提供商调用、角色、工具、知识图谱和团队编排整合到一个库中，具有明确的边际价值，评为 2；但材料不足以证明相对于成熟替代方案的独特收益达到全面水平。对模型下载、云 API、网络搜索、70B 模型、图像生成及 50 轮训练的时间、费用和硬件代价几乎没有说明，cost_benefit 仅 1。
若干能力有对应 README 示例、测试名称和 CI 步骤，可追溯到具体接口，但“通过软件确保合规”等强主张没有给出机制、策略或测试证据，claim_traceability 为 1。README、测试和工作流对核心导入、文档示例、服务端、SQL、工具及构建形成一定交叉印证，因此 cross_source_corroboration 为 2；不过不少检查允许失败，且本次没有执行。生成式示例输出和营销性能力陈述没有持续区分演示、事实与已验证保证，示例中的模型回答也未附核验，因此 fact_inference_separation 为 1。
- CodingAgent 会自动执行模型生成的代码，而普通 Agent 默认包含 shell、Python、文件编辑和网络搜索工具；在隔离环境外使用前应自行加入逐次确认、工具白名单、路径限制和沙箱。
- 远程模型、MCP 服务、Web 搜索、数据集和媒体提供商可能接收提示、文件或上下文；材料没有给出完整的数据流、保留、隐私或密钥处理说明。
- 多项 CI、集成、服务端、Windows、Web 和 lint 检查允许失败，因此工作流存在并不等于这些路径被强制验证。
- 依赖未展示锁定或漏洞扫描，且 CI 使用网络安装脚本；部署前应独立审计依赖、固定版本并核验供应链。
- README 中“通过软件确保合规”的主张缺少所给源码中的可追溯机制或验证证据，不应视为合规保证。
这个 Agent 能做什么，适合哪些场景？
npcpy 是一个面向多模态语言模型、智能体系统和知识图谱研发的 Python 库。它提供 NPC、Agent、ToolAgent、CodingAgent、Team 与 NPCArray 等组件，覆盖角色定义、工具调用、代码执行、多智能体编排和并行推理。模型层既可连接 Ollama、llama.cpp、LM Studio 等本地运行方式，也支持 OpenAI、Anthropic、Gemini、DeepSeek、MiniMax 等云端提供方。其 Context-Agent-Tool 数据层可结合 .npc、.jinx、team.ctx、Markdown 智能体定义和 MCP 服务组织上下文与权限边界。结果可通过普通响应、流式文本、JSON 或 Pydantic 结构返回，并能借助 Flask REST API 部署团队。项目还包含知识图谱生命周期、图像音频视频生成、SFT、DPO、扩散模型训练及其他实验性机器学习能力，因此更像研究与工程工具箱，而非开箱即用的托管产品。
开发者先通过 NPC 或 Markdown/.npc 文件定义名称、primary_directive、模型和提供方，再用 Agent 的默认工具、ToolAgent 的自定义函数与 MCP 工具，或 CodingAgent 的代码块自动执行能力处理任务。Team.orchestrate() 由 forenpc 协调多个角色，NPCArray 则对多个模型或 NPC 执行并行 infer、jinx、chain 与 consensus 操作。Jinx 使用 YAML、Jinja 模板以及 natural 或 Python 等步骤构建多阶段工作流，并可读取 team.ctx 中的上下文变量。库能调用本地或云端模型，处理消息历史与流式分块，生成结构化 JSON/Pydantic 结果，并提供图像、语音和视频生成接口。知识图谱模块可以从文本提取事实与概念，执行增量演化、睡眠整合、梦境式推测连接和混合检索；SememolutionPopulation 还可维护并选择多个图谱变体。团队既能通过 npcsh 使用，也能由 start_flask_server 暴露为 REST API；npc-claude、npc-codex、npc-gemini 等命令可把外部编码工具作为团队中的 NPC 启动。
- 需要在 Ollama 本地模型与多个云端 API 之间切换的 Python 团队，可用同一套 get_llm_response、NPC 和 Team 接口开发原型。
- 研究多智能体辩论或模型群体行为的实验人员，可用 NPCArray 并行收集回答、进行多轮互评并生成共识。
- 需要让智能体操作文件、运行 shell 或 Python、搜索网络及调用内部服务的工程师，可基于 Agent、ToolAgent 和 MCP 组合工具。
- 要从文档持续构建可检索记忆的研究项目，可使用知识图谱的初始化、增量吸收、睡眠整合、梦境连接与混合搜索流程。
- 希望以可审阅文件管理角色和工作流的团队，可将 persona 写入 .npc 或 Markdown，将多步骤流程写入 .jinx，并以 team.ctx 集中配置。
- 探索智能体微调或多模态生成的研发人员，可试用项目提供的 SFT、DPO、扩散训练以及图像、音频和视频接口。
这个 Agent 有哪些优点和局限？
- 同时支持本地模型与多家云端提供方，核心 NPC、Team 和响应接口不绑定单一模型厂商。
- 从单智能体、定制工具到协调式 Team 和向量化 NPCArray 都有明确组件，可覆盖原型、批量实验与多智能体协作。
- .npc、.jinx、team.ctx、Markdown 智能体和 MCP 服务形成可组合的文件式配置与工作流体系。
- 除文本调用外，还提供流式输出、JSON/Pydantic 结构化结果、多模态生成、知识图谱与微调模块。
- 既可作为 Python 库使用，也可通过 npcsh、可执行工作流文件或 Flask REST 服务交付。
- 功能面很广，采用者需要同时理解角色、团队、Jinx、上下文文件、MCP 和不同智能体子类，学习与治理成本较高。
- 完整功能涉及 Ollama、模型权重、ffmpeg、音频库、diffusers、transformers 或外部 API 等可选依赖，环境配置可能较重。
- 云端模型、远程 MCP、网页搜索和部分多模态功能需要网络及相应凭据；本地运行则需要自行承担模型下载和计算资源。
- CodingAgent 会自动执行模型响应中的代码块，Agent 也带有 shell、Python 和文件编辑工具，生产使用前必须建立权限隔离与审计策略。
- 知识图谱的梦境连接、群体演化和训练功能具有明显研究属性；来源未提供其准确率、稳定性、资源消耗或生产规模基准。
如何安装或部署这个 Agent？
需要 Python 环境。基础安装：
pip install npcpy可按范围安装额外依赖：
pip install npcpy[lite] # API 提供方库
pip install npcpy[local] # Ollama、diffusers、transformers、airllm
pip install npcpy[yap] # TTS/STTpip install npcpy[all] # 全部功能
使用云端提供方时，在环境中设置相应密钥，例如 OPENAI_API_KEY、ANTHROPIC_API_KEY 或 GEMINI_API_KEY。使用本地 Ollama 时还需安装 Ollama，并执行：
ollama pull qwen3.5:2bLinux 上涉及语音、视频或图形功能时，文档列出的系统包包括 espeak、portaudio19-dev、python3-pyaudio、ffmpeg、libcairo2-dev 和 libgirepository1.0-dev；macOS 对应 portaudio、ffmpeg、pygobject3 与 ollama。
如何使用这个 Agent？
最小本地调用：
from npcpy import get_llm_response
response = get_llm_response("Explain quantum entanglement.",
model="qwen3.5:2b",
provider="ollama")
print(response["response"])创建带默认工具的智能体：
from npcpy import Agent
agent = Agent(name="File Operator", model="qwen3.5:2b", provider="ollama")
print(agent.run("Find all Python files over 500 lines in this repo and list them"))运行代码定义的团队：
from npcpy import NPC, Team
coordinator = NPC(name="lead", primary_directive="Coordinate the team. Delegate to @analyst.")
analyst = NPC(name="analyst", primary_directive="Analyze data and report trends.", model="gemini-2.5-flash", provider="gemini")
team = Team(npcs=[coordinator, analyst], forenpc="lead")
print(team.orchestrate("Analyze renewable energy adoption trends")["output"])文件式团队可通过 npcsh 交互运行；也可以执行 .npc/.jinx 文件。若需 REST 服务，调用 start_flask_server，并明确设置端口、CORS、历史数据库路径和团队目录。
这个 Agent 与同类方案有什么区别？
与只调用单一云端 API 的实现相比，npcpy 提供统一的本地/云端模型入口、多智能体团队、工具与知识图谱层，但也引入更多配置和运行依赖。项目内部可按执行风险选择 NPC、Agent、ToolAgent 或 CodingAgent：NPC 侧重角色与模型交互，Agent 带默认工具，ToolAgent 接受自定义工具和 MCP，CodingAgent 会自动执行模型输出的代码块。对于团队执行，Team 偏向由 forenpc 协调角色，NPCArray 偏向对多个模型或角色进行并行、链式和共识计算。