mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-04-26 00:46:22 +02:00
Structure the tech specs directory (#836)
Tech spec some subdirectories for different languages
This commit is contained in:
cybermaggedon
GitHub
parent
48da6c5f8b
commit
e7efb673ef
423 changed files with 0 additions and 0 deletions
499
docs/tech-specs/zh-cn/tool-group.zh-cn.md
Normal file
499
docs/tech-specs/zh-cn/tool-group.zh-cn.md
Normal file
|
|
@ -0,0 +1,499 @@
|
|||
---
|
||||
layout: default
|
||||
title: "TrustGraph 工具组系统"
|
||||
parent: "Chinese (Beta)"
|
||||
---
|
||||
|
||||
# TrustGraph 工具组系统
|
||||
|
||||
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
|
||||
## 技术规范 v1.0
|
||||
|
||||
### 摘要
|
||||
|
||||
本规范定义了一个用于 TrustGraph 代理的工具分组系统，该系统允许对哪些工具可用于特定请求进行细粒度控制。该系统通过配置和请求级别的指定，引入基于组的工具过滤，从而实现更好的安全边界、资源管理以及代理功能的划分。
|
||||
|
||||
### 1. 概述
|
||||
|
||||
#### 1.1 问题陈述
|
||||
|
||||
目前，TrustGraph 代理可以访问所有配置的工具，而与请求上下文或安全要求无关。这带来了一些挑战：
|
||||
|
||||
**安全风险**: 即使是只读查询，也可能访问到敏感工具（例如，数据修改）。
|
||||
**资源浪费**: 即使简单的查询也不需要，也会加载复杂的工具。
|
||||
**功能混淆**: 代理可能会选择不合适的工具，而存在更简单的替代方案。
|
||||
**多租户隔离**: 不同的用户组需要访问不同的工具集。
|
||||
|
||||
#### 1.2 解决方案概述
|
||||
|
||||
工具分组系统引入了：
|
||||
|
||||
1. **组分类**: 工具在配置时会被标记为所属的组。
|
||||
2. **请求级别过滤**: AgentRequest 指定允许使用的工具组。
|
||||
3. **运行时强制**: 代理只能访问与请求的组匹配的工具。
|
||||
4. **灵活分组**: 工具可以属于多个组，以适应复杂的场景。
|
||||
|
||||
### 2. 模式变更
|
||||
|
||||
#### 2.1 工具配置模式增强
|
||||
|
||||
现有的工具配置通过添加一个 `group` 字段进行增强：
|
||||
|
||||
**之前：**
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph"
|
||||
}
|
||||
```
|
||||
|
||||
**翻译后：**
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph",
|
||||
"group": ["read-only", "knowledge", "basic"]
|
||||
}
|
||||
```
|
||||
|
||||
**组字段规范：**
|
||||
`group`: Array(String) - 此工具所属的组列表
|
||||
**可选：** 没有组字段的工具属于 "默认" 组
|
||||
**多重隶属：** 工具可以属于多个组
|
||||
**区分大小写：** 组名必须是完全匹配的字符串
|
||||
|
||||
#### 2.1.2 工具状态转换增强
|
||||
|
||||
工具可以选择性地指定状态转换和基于状态的可用性：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "knowledge-query",
|
||||
"type": "knowledge-query",
|
||||
"description": "Query the knowledge graph",
|
||||
"group": ["read-only", "knowledge", "basic"],
|
||||
"state": "analysis",
|
||||
"available_in_states": ["undefined", "research"]
|
||||
}
|
||||
```
|
||||
|
||||
**状态字段规范：**
|
||||
`state`: String - **可选** - 成功执行工具后要转换到的状态
|
||||
`available_in_states`: Array(String) - **可选** - 此工具可用的状态
|
||||
**默认行为：** 没有 `available_in_states` 的工具在所有状态下都可用
|
||||
**状态转换：** 仅在成功执行工具后发生
|
||||
|
||||
#### 2.2 AgentRequest 模式增强
|
||||
|
||||
`trustgraph-base/trustgraph/schema/services/agent.py` 中的 `AgentRequest` 模式已增强：
|
||||
|
||||
**当前 AgentRequest：**
|
||||
`question`: String - 用户查询
|
||||
`plan`: String - 执行计划（可以删除）
|
||||
`state`: String - Agent 状态
|
||||
`history`: Array(AgentStep) - 执行历史
|
||||
|
||||
**增强后的 AgentRequest：**
|
||||
`question`: String - 用户查询
|
||||
`state`: String - Agent 执行状态（现在被积极用于工具过滤）
|
||||
`history`: Array(AgentStep) - 执行历史
|
||||
`group`: Array(String) - **新增** - 此请求允许的工具组
|
||||
|
||||
**模式变更：**
|
||||
**已移除：** `plan` 字段不再需要，可以删除（最初用于工具规范）
|
||||
**已添加：** `group` 字段用于工具组规范
|
||||
**已增强：** `state` 字段现在控制执行期间的工具可用性
|
||||
|
||||
**字段行为：**
|
||||
|
||||
**组字段：**
|
||||
**可选：** 如果未指定，默认为 ["default"]
|
||||
**交集：** 只有匹配至少一个指定组的工具才可用
|
||||
**空数组：** 没有可用工具（agent 只能使用内部推理）
|
||||
**通配符：** 特殊组 "*" 授予访问所有工具的权限
|
||||
|
||||
**状态字段：**
|
||||
**可选：** 如果未指定，默认为 "undefined"
|
||||
**基于状态的过滤：** 只有在当前状态下可用的工具才有资格
|
||||
**默认状态：** "undefined" 状态允许所有工具（受组过滤限制）
|
||||
**状态转换：** 成功执行后，工具可以更改状态
|
||||
|
||||
### 3. 自定义组示例
|
||||
|
||||
组织可以定义特定领域的组：
|
||||
|
||||
```json
|
||||
{
|
||||
"financial-tools": ["stock-query", "portfolio-analysis"],
|
||||
"medical-tools": ["diagnosis-assist", "drug-interaction"],
|
||||
"legal-tools": ["contract-analysis", "case-search"]
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 实现细节
|
||||
|
||||
#### 4.1 工具加载和过滤
|
||||
|
||||
**配置阶段：**
|
||||
1. 所有工具从配置文件中加载，并带有其组分配信息。
|
||||
2. 没有明确组分配的工具将被分配到 "默认" 组。
|
||||
3. 组成员关系将被验证并存储在工具注册表中。
|
||||
|
||||
**请求处理阶段：**
|
||||
1. AgentRequest 携带可选的组指定信息。
|
||||
2. Agent 根据组的交集过滤可用的工具。
|
||||
3. 只有匹配的工具才会被传递到 Agent 执行上下文。
|
||||
4. Agent 在整个请求生命周期内都使用过滤后的工具集。
|
||||
|
||||
#### 4.2 工具过滤逻辑
|
||||
|
||||
**组合组和状态过滤：**
|
||||
|
||||
```
|
||||
For each configured tool:
|
||||
tool_groups = tool.group || ["default"]
|
||||
tool_states = tool.available_in_states || ["*"] // Available in all states
|
||||
|
||||
For each request:
|
||||
requested_groups = request.group || ["default"]
|
||||
current_state = request.state || "undefined"
|
||||
|
||||
Tool is available if:
|
||||
// Group filtering
|
||||
(intersection(tool_groups, requested_groups) is not empty OR "*" in requested_groups)
|
||||
AND
|
||||
// State filtering
|
||||
(current_state in tool_states OR "*" in tool_states)
|
||||
```
|
||||
|
||||
**状态转换逻辑：**
|
||||
|
||||
```
|
||||
After successful tool execution:
|
||||
if tool.state is defined:
|
||||
next_request.state = tool.state
|
||||
else:
|
||||
next_request.state = current_request.state // No change
|
||||
```
|
||||
|
||||
#### 4.3 代理集成点
|
||||
|
||||
**ReAct 代理：**
|
||||
工具过滤在 `agent_manager.py` 中在工具注册创建期间发生。
|
||||
可用工具列表在计划生成之前，会根据组和状态进行过滤。
|
||||
状态转换会在工具执行成功后更新 `AgentRequest.state` 字段。
|
||||
下一次迭代使用更新后的状态进行工具过滤。
|
||||
|
||||
**基于置信度的代理：**
|
||||
工具过滤在 `planner.py` 中在计划生成期间发生。
|
||||
`ExecutionStep` 验证确保只使用组+状态符合条件的工具。
|
||||
流程控制器在运行时强制执行工具可用性。
|
||||
状态转换由流程控制器在步骤之间管理。
|
||||
|
||||
### 5. 配置示例
|
||||
|
||||
#### 5.1 带有组和状态的工具配置
|
||||
|
||||
```yaml
|
||||
tool:
|
||||
knowledge-query:
|
||||
type: knowledge-query
|
||||
name: "Knowledge Graph Query"
|
||||
description: "Query the knowledge graph for entities and relationships"
|
||||
group: ["read-only", "knowledge", "basic"]
|
||||
state: "analysis"
|
||||
available_in_states: ["undefined", "research"]
|
||||
|
||||
graph-update:
|
||||
type: graph-update
|
||||
name: "Graph Update"
|
||||
description: "Add or modify entities in the knowledge graph"
|
||||
group: ["write", "knowledge", "admin"]
|
||||
available_in_states: ["analysis", "modification"]
|
||||
|
||||
text-completion:
|
||||
type: text-completion
|
||||
name: "Text Completion"
|
||||
description: "Generate text using language models"
|
||||
group: ["read-only", "text", "basic"]
|
||||
state: "undefined"
|
||||
# No available_in_states = available in all states
|
||||
|
||||
complex-analysis:
|
||||
type: mcp-tool
|
||||
name: "Complex Analysis Tool"
|
||||
description: "Perform complex data analysis"
|
||||
group: ["advanced", "compute", "expensive"]
|
||||
state: "results"
|
||||
available_in_states: ["analysis"]
|
||||
mcp_tool_id: "analysis-server"
|
||||
|
||||
reset-workflow:
|
||||
type: mcp-tool
|
||||
name: "Reset Workflow"
|
||||
description: "Reset to initial state"
|
||||
group: ["admin"]
|
||||
state: "undefined"
|
||||
available_in_states: ["analysis", "results"]
|
||||
```
|
||||
|
||||
#### 5.2 请求示例与状态工作流
|
||||
|
||||
**初始研究请求：**
|
||||
```json
|
||||
{
|
||||
"question": "What entities are connected to Company X?",
|
||||
"group": ["read-only", "knowledge"],
|
||||
"state": "undefined"
|
||||
}
|
||||
```
|
||||
*可用工具：知识查询，文本补全*
|
||||
*知识查询后：状态 → "分析"*
|
||||
|
||||
**分析阶段：**
|
||||
```json
|
||||
{
|
||||
"question": "Continue analysis based on previous results",
|
||||
"group": ["advanced", "compute", "write"],
|
||||
"state": "analysis"
|
||||
}
|
||||
```
|
||||
*可用工具：复杂分析、图更新、重置工作流程*
|
||||
*复杂分析之后：状态 → "结果"*
|
||||
|
||||
**结果阶段：**
|
||||
```json
|
||||
{
|
||||
"question": "What should I do with these results?",
|
||||
"group": ["admin"],
|
||||
"state": "results"
|
||||
}
|
||||
```
|
||||
*可用的工具：仅限 reset-workflow*
|
||||
*reset-workflow 之后：状态 → "undefined"*
|
||||
|
||||
**工作流程示例 - 完整流程：**
|
||||
1. **开始 (undefined)**：使用 knowledge-query → 转换到 "analysis"
|
||||
2. **分析状态：** 使用 complex-analysis → 转换到 "results"
|
||||
3. **结果状态：** 使用 reset-workflow → 转换回 "undefined"
|
||||
4. **返回开始：** 所有初始工具再次可用
|
||||
|
||||
### 6. 安全注意事项
|
||||
|
||||
#### 6.1 访问控制集成
|
||||
|
||||
**网关级别的过滤：**
|
||||
网关可以根据用户权限强制执行组限制
|
||||
防止通过请求修改来提升权限
|
||||
审计跟踪包括请求和授予的工具组
|
||||
|
||||
**示例网关逻辑：**
|
||||
```
|
||||
user_permissions = get_user_permissions(request.user_id)
|
||||
allowed_groups = user_permissions.tool_groups
|
||||
requested_groups = request.group
|
||||
|
||||
# Validate request doesn't exceed permissions
|
||||
if not is_subset(requested_groups, allowed_groups):
|
||||
reject_request("Insufficient permissions for requested tool groups")
|
||||
```
|
||||
|
||||
#### 6.2 审计和监控
|
||||
|
||||
**增强的审计跟踪：**
|
||||
记录每个请求所请求的工具组和初始状态
|
||||
跟踪按组成员划分的状态转换和工具使用情况
|
||||
监控未经授权的组访问尝试和无效的状态转换
|
||||
警报不寻常的组使用模式或可疑的状态工作流程
|
||||
|
||||
### 7. 迁移策略
|
||||
|
||||
#### 7.1 向后兼容性
|
||||
|
||||
**第一阶段：增量更改**
|
||||
向工具配置添加可选的 `group` 字段
|
||||
向 AgentRequest 模式添加可选的 `group` 字段
|
||||
默认行为：所有现有工具都属于 "默认" 组
|
||||
现有请求如果没有组字段，则使用 "默认" 组
|
||||
|
||||
**保留现有行为：**
|
||||
没有组配置的工具继续工作（默认组）
|
||||
没有状态配置的工具在所有状态下都可用
|
||||
没有组指定的请求可以访问所有工具（默认组）
|
||||
没有状态指定的请求使用 "未定义" 状态（所有工具可用）
|
||||
没有对现有部署进行破坏性更改
|
||||
|
||||
### 8. 监控和可观察性
|
||||
|
||||
#### 8.1 新指标
|
||||
|
||||
**工具组使用情况：**
|
||||
`agent_tool_group_requests_total` - 按组划分的请求计数器
|
||||
`agent_tool_group_availability` - 每个组可用的工具计量
|
||||
`agent_filtered_tools_count` - 组+状态过滤后工具计数的直方图
|
||||
|
||||
**状态工作流程指标：**
|
||||
`agent_state_transitions_total` - 按工具划分的状态转换计数器
|
||||
`agent_workflow_duration_seconds` - 每个状态花费时间的直方图
|
||||
`agent_state_availability` - 每个状态可用的工具计量
|
||||
|
||||
**安全指标：**
|
||||
`agent_group_access_denied_total` - 未经授权的组访问计数器
|
||||
`agent_invalid_state_transition_total` - 无效状态转换计数器
|
||||
`agent_privilege_escalation_attempts_total` - 具有可疑请求的计数器
|
||||
|
||||
#### 8.2 日志增强
|
||||
|
||||
**请求日志记录：**
|
||||
```json
|
||||
{
|
||||
"request_id": "req-123",
|
||||
"requested_groups": ["read-only", "knowledge"],
|
||||
"initial_state": "undefined",
|
||||
"state_transitions": [
|
||||
{"tool": "knowledge-query", "from": "undefined", "to": "analysis", "timestamp": "2024-01-01T10:00:01Z"}
|
||||
],
|
||||
"available_tools": ["knowledge-query", "text-completion"],
|
||||
"filtered_by_group": ["graph-update", "admin-tool"],
|
||||
"filtered_by_state": [],
|
||||
"execution_time": "1.2s"
|
||||
}
|
||||
```
|
||||
|
||||
### 9. 测试策略
|
||||
|
||||
#### 9.1 单元测试
|
||||
|
||||
**工具过滤逻辑：**
|
||||
测试组的交集计算
|
||||
测试基于状态的过滤逻辑
|
||||
验证默认组和状态的分配
|
||||
测试通配符组的行为
|
||||
验证空组的处理
|
||||
测试组合的组+状态过滤场景
|
||||
|
||||
**配置验证：**
|
||||
测试使用各种组和状态配置加载工具
|
||||
验证无效的组和状态规范的模式验证
|
||||
测试与现有配置的向后兼容性
|
||||
验证状态转换的定义和循环
|
||||
|
||||
#### 9.2 集成测试
|
||||
|
||||
**代理行为：**
|
||||
验证代理只看到组+状态过滤的工具
|
||||
测试使用各种组组合的请求执行
|
||||
测试代理执行期间的状态转换
|
||||
验证在没有可用工具时错误处理
|
||||
测试通过多个状态的工作流程进度
|
||||
|
||||
**安全测试：**
|
||||
测试特权提升预防
|
||||
验证审计跟踪的准确性
|
||||
测试网关与用户权限的集成
|
||||
|
||||
#### 9.3 完整场景
|
||||
|
||||
**具有状态工作流程的多租户使用：**
|
||||
```
|
||||
Scenario: Different users with different tool access and workflow states
|
||||
Given: User A has "read-only" permissions, state "undefined"
|
||||
And: User B has "write" permissions, state "analysis"
|
||||
When: Both request knowledge operations
|
||||
Then: User A gets read-only tools available in "undefined" state
|
||||
And: User B gets write tools available in "analysis" state
|
||||
And: State transitions are tracked per user session
|
||||
And: All usage and transitions are properly audited
|
||||
```
|
||||
|
||||
**工作流程状态演进：**
|
||||
```
|
||||
Scenario: Complete workflow execution
|
||||
Given: Request with groups ["knowledge", "compute"] and state "undefined"
|
||||
When: Agent executes knowledge-query tool (transitions to "analysis")
|
||||
And: Agent executes complex-analysis tool (transitions to "results")
|
||||
And: Agent executes reset-workflow tool (transitions to "undefined")
|
||||
Then: Each step has correctly filtered available tools
|
||||
And: State transitions are logged with timestamps
|
||||
And: Final state allows initial workflow to repeat
|
||||
```
|
||||
|
||||
### 10. 性能考虑
|
||||
|
||||
#### 10.1 工具加载的影响
|
||||
|
||||
**配置加载：**
|
||||
组和状态元数据在启动时加载一次
|
||||
每个工具的内存开销很小（附加字段）
|
||||
不会影响工具的初始化时间
|
||||
|
||||
**请求处理：**
|
||||
组+状态过滤的组合在每个请求中执行一次
|
||||
复杂度为 O(n)，其中 n = 配置的工具数量
|
||||
状态转换会增加微小的开销（字符串赋值）
|
||||
对于典型的工具数量（< 100），影响可以忽略不计
|
||||
|
||||
#### 10.2 优化策略
|
||||
|
||||
**预计算的工具集：**
|
||||
根据组+状态组合缓存工具集
|
||||
避免重复过滤常见的组/状态模式
|
||||
内存与计算之间的权衡，适用于经常使用的组合
|
||||
|
||||
**延迟加载：**
|
||||
仅在需要时才加载工具实现
|
||||
减少具有许多工具的部署的启动时间
|
||||
基于组需求的动态工具注册
|
||||
|
||||
### 11. 未来增强功能
|
||||
|
||||
#### 11.1 动态组分配
|
||||
|
||||
**基于上下文的组：**
|
||||
根据请求上下文将工具分配到组
|
||||
基于时间的组可用性（仅在工作时间内）
|
||||
基于负载的组限制（在低使用情况下限制昂贵的工具）
|
||||
|
||||
#### 11.2 组层级结构
|
||||
|
||||
**嵌套的组结构：**
|
||||
```json
|
||||
{
|
||||
"knowledge": {
|
||||
"read": ["knowledge-query", "entity-search"],
|
||||
"write": ["graph-update", "entity-create"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 11.3 工具推荐
|
||||
|
||||
**基于组的建议：**
|
||||
针对请求类型，推荐最佳工具组。
|
||||
从使用模式中学习，以改进推荐。
|
||||
在首选工具不可用时，提供备用组。
|
||||
|
||||
### 12. 开放性问题
|
||||
|
||||
1. **组验证：** 请求中无效的组名是否应导致硬性错误或警告？
|
||||
|
||||
2. **组发现：** 系统是否应提供一个 API 来列出可用的组及其工具？
|
||||
|
||||
3. **动态组：** 组是否应在运行时配置，或者仅在启动时配置？
|
||||
|
||||
4. **组继承：** 工具是否应从其父类别或实现继承组？
|
||||
|
||||
5. **性能监控：** 需要哪些额外的指标来有效跟踪基于组的工具使用情况？
|
||||
|
||||
### 13. 结论
|
||||
|
||||
工具组系统提供：
|
||||
|
||||
**安全性：** 对代理功能进行细粒度的访问控制。
|
||||
**性能：** 减少工具加载和选择开销。
|
||||
**灵活性：** 多维工具分类。
|
||||
**兼容性：** 与现有代理架构无缝集成。
|
||||
|
||||
该系统使 TrustGraph 部署能够更好地管理工具访问，提高安全边界，并优化资源利用率，同时与现有的配置和请求完全兼容。
|
||||
Loading…
Add table
Add a link
Reference in a new issue