协作式AI工具框架

                                       __                               
_-_ _,,   ,,            ,,           ,-||-,              ,,        |\   
   -/  )  ||   _        ||          ('|||  )             ||     '   \\  
  ~||_<   ||  < \,  _-_ ||/\       (( |||--)) ,._-_  _-_ ||/\\ \\  / \\ 
   || \\  ||  /-|| ||   ||_<       (( |||--))  ||   ||   || || || || || 
   ,/--|| || (( || ||   || |        ( / |  )   ||   ||   || || || || || 
  _--_-'  \\  \/\\ \\,/ \\,\         -____-    \\,  \\,/ \\ |/ \\  \\/  
 (                                                         _/           
                                                                        

黑兰花：一个可扩展的协同环境框架

作为MCP服务器交付，它允许通过Claude Code或任何接受MCP的系统动态创建使用AI的工具和技能 它是一个用于自定义Python工具的热可重新加载MCP代理服务器，是全球（非项目绑定）技能的中心。使用安全模块加载importlib （不是 exec).自动从Python模块中发现具有冲突检测功能的工具。

动态协作、可破解的脚本、动态扩展

添加自己的技能，并将其用于任何项目，添加自己的工具。

这既是一个协作空间，也是一个扩展功能的平台。

仍然是高度实验性的。欢迎反馈和贡献！

特性

• 热可重新加载MCP代理服务器
• 安全模块加载（importlib，而非exec）
• 自动从Python模块中发现工具
• 重复函数名的冲突检测
• 公共和私有模块支持
• Claude的自动发现技能

安装

请看 requirements.txt，下面是设置它的几种方法。

快速设置：

claude mcp add --transport stdio Black_Orchid python "absolute/path/to/black_orchid.py"

注意：需要指向black_orchid.py的绝对路径 fastmcp 全局安装，否则需要更改命令。你还需要 python-toon 和 pyyaml。这将只为每个文件夹安装所有黑兰花。

对于全局安装：

请注意，Claude将GLOBAL MCP服务器存储在顶层 mcpServers 物业内 /Users/USERNAME/.claude.json.

这就是您必须添加命令的地方，请注意，如果您想隔离依赖关系，可以使用fastmcp运行器UV，或者简单地使用您创建的venv运行它。

运作原理

Black Orchid允许您将技能、扩展模块和其他任何内容分离到私有和公共文件夹中，因此，如果您分叉仓库，您可以简单地忽略私有文件夹。将其用于个人物品、敏感数据等。

将继续添加更多公开可用的默认模块。

对于技能：

• 扫描 modules/skills/ （公众）和 private/modules/skills 文件夹。
• 让克劳德列出可用的技能
• 体现技能：克劳德拥有技能并使用它
• 生成代理：克劳德设置了一个具有该技能的代理，然后为他们分配了一项任务。

对于工具：

• 扫描 modules/ （公众）和 private/modules/ （私人）文件夹
• 将所有.py文件作为工具加载
• 每个公共功能（不以 _)在模块中成为MCP工具
• 无需重新启动服务器即可进行热重新加载
• 路径验证和语法检查以确保安全性

可用的内置工具

运用技能

技能是可移植的协作模式——在项目中与你同行的思维和工作方式。

• list_skills() -查看有哪些模式可用（两种模式都有 modules/skills/ 和 private/skills/)
• use_skill(skill_name) -在当前会话中体现一项技能
• spawn_subagent_with_skill(skill_name, task) -创建一个以技能为背景的专业代理

想要一项新技能吗？只需在中创建一个markdown文件 modules/skills/ 或 private/skills/ 并致电 reload_all_modules()。您创建的技能立即可用。

内置技能

《黑兰花》附带了公共技能，助您入门：

文档优化器 -将冗长的文档转换为LLM友好、令牌高效的标记

• 清楚地标记人类/AI范围边界(🚫 人类所需，✅ AI可以处理，⚠️ 需要合作）
• 优化令牌效率，同时保留重要信息
• 结构化文档，无需重复获取即可快速查找
• 为不同的文档类型提供模板和指南

在集成新框架或API时特别有用——一次获取文档，优化它们，并在会话之间引用它们，而无需重新获取。

项目估算员 -协作项目范围界定和时间估算

• 将复杂项目分解为可估算的组成部分
• 考虑不确定性和依赖性
• 提供范围而不是假精度
• 有助于及早发现隐藏的复杂性

在规划新功能或项目时使用它——它有助于将“我想构建X”变成“这是X实际涉及的内容以及可能需要多长时间”

文档状态审阅者 -系统性文件审计

• 检查实际代码以了解存在的内容
• 阅读当前文档
• 要求澄清有关意图和优先事项的问题
• 识别差距（存在但未记录的特征）
• 识别过时的文档
• 对需要更新的内容进行公正的评估

当你怀疑你的文档与现实不同步时，可以使用它——它有助于捕捉“我们构建的内容”和“我们记录的内容”之间的差距

管理您的会话

在整个对话中保持上下文活跃，而不会使上下文窗口膨胀。

会话存储器 （短暂-仅在当前会话中存在）：

• remember(key, value) -存储此会话的数据
• recall(key) -检索存储的数据
• forget(key) -删除特定内存
• list_memories() -查看所有存储的密钥
• clear_all_memories() -把石板擦干净

工作偏好 （持久-跨会话生存）：

• load_working_preferences() -加载您的协作首选项
• save_working_preference(key, value) -为以后的会话保存首选项
• get_preference(key) -查找特定首选项

会话内存用于“记住API对接下来几圈的响应”。首选项用于“我总是想要黑暗模式”或“我喜欢的代码样式是X”

语义记忆与知识管理

用于技术知识、参考库和自定义域的持久、分层存储系统。

Black Orchid包括一个语义记忆系统，可以让你从markdown文档中构建可搜索的知识库。与简单的文件存储不同，语义记忆使用嵌入来实现智能搜索——用自然语言提问，并获得具有完整出处的相关结果。

核心功能：

• initialize_semantic_memory() -设置ChromaDB并创建收藏
• ingest_document(file_path, domain) -将markdown文件添加到内存中
• query_memory(text, domain, n_results) -使用自然语言进行语义搜索
• rebuild_domain(domain) -批处理域中的所有文件
• get_collections() -查看所有内存集合的统计数据

工作原理：

1. 层次结构 -文档被解析为L0（文档）、L1（章节）、L2（子章节）
2. 来源追踪 -每个结果都准确地显示了它的来源(book > chapter > section)
3. 域组织 -不同知识类型的单独集合
4. 语义搜索 -使用问题而非关键字进行查询

示例用法：

# Initialize the system
initialize_semantic_memory()

# Add documents to memory
ingest_document("sources/library/power_electronics.md", domain="library")
ingest_document("sources/technical/decisions.md", domain="technical")

# Search semantically
results = query_memory("MOSFET switching behavior", domain="library", n_results=3)
# Returns: matches with full context and provenance paths

可配置域：

域是通过YAML配置的（请参阅下面的配置部分）。公共配置定义默认域（技术、库），而私有配置可以添加自定义域。

储存：

• 文件： sources/{domain}/ -您的降价文件
• 数据库： db/chroma/ -嵌入和元数据（gitignored）
• 使用ChromaDB sentence-transformers/all-MiniLM-L6-v2 嵌入模型
• 在本地运行，不需要外部API

非常适合构建个人知识库、记录技术决策或创建可查询的参考库。

配置

通过YAML配置文件自定义Black Orchid行为。

Black Orchid使用两层配置系统：

• 公共配置 (config.yaml)-提交给git的设置
• 私有配置 (private/config.yaml)-个人设置（忽略）

域配置示例：

# config.yaml (public)
domains:
  technical:
    enabled: true
    description: "Technical decisions and code patterns"
  library:
    enabled: true
    description: "Reference materials and documentation"

# private/config.yaml (private)
domains:
  custom_domain:
    enabled: true
    description: "Your custom knowledge domain"

两个配置中的域在运行时合并，在不修改公共代码的情况下实现可扩展性。

配置功能：

• get_config(scope, key_path) -读取配置值
• set_config(scope, key_path, value) -更新配置
• reload_config(scope) -从磁盘热重新加载配置
• get_enabled_domains() -列出所有已启用的内存域

系统信息

了解你的环境，这样你就可以编写跨平台代码。

• get_os_info() -跨平台操作系统检测和系统信息

返回平台、版本、架构——这对模块中的条件逻辑很有用。

热重新加载和调试

更改？立即看到他们。有东西坏了吗？找出原因。

• reload_all_modules() -从头开始重新加载所有模块（工具和技能）
• reload_module(module_name) -只重新加载一个特定模块
• list_rejected_modules() -查看哪些模块加载失败以及原因

这就是魔术——编辑一个Python文件，调用reload，你的更改就会生效。无需重新启动服务器，无需清除缓存，只需即时反馈。

创建自己的模块

您可以创建模块，并拥有自己的自定义实用程序、包装API，以及任何您能想到的东西。

方法如下：

1. 在中创建.py文件 modules/ 文件夹
2. 使用文档字符串编写函数
3. 呼叫 reload_all_modules() 加载新工具
4. 功能作为MCP工具可用

示例简单模块：

def hello_world():
    """Say hello to the world."""
    return "Hello, World!"

带参数的示例：

def greet_person(name: str, enthusiasm: int = 5):
    """Greet a person with configurable enthusiasm.

    Args:
        name: The person's name
        enthusiasm: How many exclamation marks (default: 5)

    Returns:
        A greeting string
    """
    return f"Hello, {name}{'!' * enthusiasm}"

当通过Black Orchid拨打电话时： use_proxy_tool("greet_person", {"name": "Alice", "enthusiasm": 3}) 回报 "Hello, Alice!!!"

错误处理： 如果使用不正确的参数调用工具，Black Orchid将返回一条明确的错误消息：

• 缺少必需的参数： "Error calling tool 'greet_person': missing required argument 'name'"
• 参数类型错误： "Error calling tool 'greet_person': argument 'enthusiasm' must be int, not str"
• 意外参数： "Error calling tool 'greet_person': unexpected keyword argument 'volume'"

重要提示：

辅助功能： 以开头的函数 _ （下划线）被视为私人助手，不会作为工具公开。将其用于内部实用程序。

def _helper_function():
    """This won't be exposed as a tool"""
    return "internal use only"

def public_tool():
    """This will be exposed"""
    result = _helper_function()
    return result

课程： 类不直接作为工具公开。要公开类方法，请实例化类并在函数中调用方法。

class MyUtility:
    def do_something(self):
        return "result"

# Expose the class method as a tool
def use_my_utility():
    """Use MyUtility class"""
    util = MyUtility()
    return util.do_something()

模块结构

• modules/ -公共工具（致力于git）
• private/modules/ -私有工具（gitignored）
• 碰撞处理：自动 _modulename 函数名冲突时的后缀

用法示例

与克劳德代码交谈

当你想让克劳德使用你的黑兰花工具时，自然地问：

"Using your Black Orchid proxy tools, can you call list_proxy_tools?"

或者更具体地说：

"Please use the Black Orchid proxy tool 'get_os_info' to check my system"

如果你已经提到了黑兰花，你可能不需要做太多。

克劳德将使用 use_proxy_tool 自动运行。您不需要知道确切的MCP函数名称，只需参考“Black Orchid代理工具”并描述您想要什么。

常用命令

• 列出可用工具： list_proxy_tools()
• 调用工具： use_proxy_tool(tool_id, kwargs)
• 更改后重新加载： reload_all_modules()
• 检查被拒绝的模块： list_rejected_modules()

工作流示例

1. 在中创建新模块 modules/my_tools.py
2. 问克劳德：“使用黑兰花，重新加载所有模块”
3. 问克劳德：“列出可用的黑兰花代理工具”
4. 问克劳德：“使用黑兰花的my_function工具”

安全

Black Orchid的设计考虑了安全性，但遵循“信任但验证”的方法：

它的作用：

• 路径验证：根据批准的目录验证所有模块路径(modules/ 和 private/modules/)
• 防止目录遍历攻击-拒绝批准目录外的模块
• 安全模块加载：使用 importlib （Python的标准模块加载器）， 不 exec()
• 语法验证：所有模块均已解析 ast.parse() 加载前捕获语法错误
• 被拒绝的模块跟踪：使用 list_rejected_modules() 查看加载失败的原因

你应该做什么/最佳实践：

• 仅加载您信任的模块 -Black Orchid从您的模块中执行Python代码
• 在将任何模块放入之前，请先对其进行审查 modules/ 或 private/modules/
• 保持你的 private/modules/ 文件夹真正私有（默认情况下为gitignore）
• 谨慎使用第三方模块-使用前请验证代码

信任但验证： 你最终要对你选择加载的代码负责。

贡献

我们始终欢迎您的贡献和反馈。技能、工具，无论你决定添加或创建什么。 感谢您的阅读，请告诉我任何功能请求、错误或其他问题。

授权人员

版权所有2025 AJ Gonzalez

根据Apache许可证2.0版（“许可证”）许可； 除非遵守许可证，否则您不得使用此文件。 您可以在以下网址获得许可证副本

   http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则软件 根据许可证分发的内容按“原样”分发， 无任何明示或暗示的保证或条件。 请参阅许可证，了解管理权限和 许可证下的限制。