__
_-_ _,, ,, ,, ,-||-, ,, |\
-/ ) || _ || ('||| ) || ' \\
~||_ chapter > section`)
1. **域组织** -不同知识类型的单独集合
1. **语义搜索** -使用问题而非关键字进行查询
**示例用法：**
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/` 文件夹
1. 使用文档字符串编写函数
1. 呼叫 `reload_all_modules()` 加载新工具
1. 功能作为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`
1. 问克劳德：“使用黑兰花，重新加载所有模块”
1. 问克劳德：“列出可用的黑兰花代理工具”
1. 问克劳德：“使用黑兰花的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
除非适用法律要求或书面同意，否则软件
根据许可证分发的内容按“原样”分发，
无任何明示或暗示的保证或条件。
请参阅许可证，了解管理权限和
许可证下的限制。