name: settings-management description: 查看和修改Thoth配置设置。当用户想要更改API密钥、路径、搜索设置或其他配置选项时使用。 tools:

view_settings
update_settings
validate_settings
reset_settings
migrate_settings

设置管理

管理Thoth配置，包括API凭证、文件路径、搜索参数和系统行为。设置存储在thoth.settings.json中，并在会话间持久化。

概述

设置系统提供：

集中化配置 - 所有设置集中一处
验证 - 基于模式的验证防止错误
分区 - 按功能区域组织
持久化 - 更改自动保存到文件

核心工具

工具	用途	使用时机
`view_settings`	显示当前配置	检查当前值
`update_settings`	修改设置	更改配置
`validate_settings`	检查设置有效性	更改后或故障排除时
`reset_settings`	恢复默认值	修复损坏的配置
`migrate_settings`	从环境变量导入	首次设置时

设置分区

API配置 (`api`)

{
  "api": {
    "openai_api_key": "sk-...",
    "anthropic_api_key": "sk-ant-...",
    "semantic_scholar_api_key": "...",
    "openalex_email": "user@example.com"
  }
}

文件路径 (`paths`)

{
  "paths": {
    "vault_path": "/path/to/obsidian/vault",
    "pdf_directory": "thoth/papers/pdfs",
    "data_directory": "thoth/data",
    "backup_directory": "thoth/backups"
  }
}

RAG设置 (`rag`)

{
  "rag": {
    "embedding_model": "text-embedding-3-small",
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "collection_name": "thoth_articles"
  }
}

搜索设置 (`search`)

{
  "search": {
    "default_limit": 10,
    "min_relevance": 0.7,
    "hybrid_search": true,
    "sources": ["semantic_scholar", "openalex", "arxiv"]
  }
}

发现设置 (`discovery`)

{
  "discovery": {
    "default_max_papers": 50,
    "default_relevance_threshold": 0.7,
    "auto_discovery_enabled": false,
    "discovery_interval_hours": 24
  }
}

数据库设置 (`database`)

{
  "database": {
    "connection_string": "postgresql://...",
    "pool_size": 5
  }
}

查看设置

查看所有设置

view_settings()
→ 返回完整的设置对象

查看特定分区

view_settings(section="api")
→ 仅返回API配置

view_settings(section="paths")
→ 仅返回路径配置

查看单个设置

view_settings(section="rag", key="embedding_model")
→ 返回: "text-embedding-3-small"

更新设置

更新单个值

update_settings(
  section="search",
  updates={"default_limit": 20}
)

更新多个值

update_settings(
  section="rag",
  updates={
    "chunk_size": 1200,
    "chunk_overlap": 300
  }
)

重要注意事项

更改在保存前会进行验证
某些更改需要重启服务
某些更改需要重新索引（参见RAG管理技能）

验证

检查设置有效性

validate_settings()
→ 返回验证结果

示例输出：
{
  "valid": true,
  "warnings": [
    "semantic_scholar_api_key 未设置 - 将应用速率限制"
  ],
  "errors": []
}

常见验证问题

问题	解决方案
缺少必填字段	使用update_settings设置字段
无效路径	检查路径是否存在且可访问
无效API密钥格式	验证密钥是否正确复制
无效值类型	检查模式中的预期类型

重置设置

重置单个分区

reset_settings(section="search")
→ 将搜索设置恢复为默认值

重置所有设置

reset_settings(all=true)
→ 将整个配置恢复为默认值

警告：重置将覆盖当前值。建议先备份。

从环境变量迁移

首次设置或从.env文件迁移时：

migrate_settings()
→ 从环境变量导入设置

迁移：
- OPENAI_API_KEY → api.openai_api_key
- VAULT_PATH → paths.vault_path
- POSTGRES_URL → database.connection_string
...

工作流示例

示例1：更改知识库路径

用户：“我将Obsidian知识库移动到了新位置”

1. 查看当前路径
   view_settings(section="paths", key="vault_path")
   → /old/path/to/vault

2. 更新路径
   update_settings(
     section="paths",
     updates={"vault_path": "/new/path/to/vault"}
   )

3. 验证
   validate_settings()
   → valid: true

4. 响应：
   "已将您的知识库路径更新为 /new/path/to/vault。
   更改已保存并立即生效。"

示例2：配置API密钥

用户：“我需要设置我的Semantic Scholar API密钥”

1. 获取当前状态
   view_settings(section="api")
   → 显示当前API密钥（已屏蔽）

2. 更新密钥
   update_settings(
     section="api",
     updates={"semantic_scholar_api_key": "用户提供的密钥"}
   )

3. 验证
   validate_settings()
   → 检查警告/错误

4. 响应：
   "Semantic Scholar API密钥已配置。
   您现在将拥有更高的论文发现速率限制。"

示例3：优化搜索配置

用户：“我的搜索返回的结果太少了”

1. 检查当前搜索设置
   view_settings(section="search")
   → default_limit: 10, min_relevance: 0.8

2. 调整设置
   update_settings(
     section="search",
     updates={
       "default_limit": 25,
       "min_relevance": 0.6,
       "hybrid_search": true
     }
   )

3. 响应：
   "搜索设置已更新：
   - 结果限制：10 → 25
   - 相关性阈值：0.8 → 0.6（更具包容性）
   - 混合搜索：已启用（结合语义+关键词）

   请再次尝试搜索 - 您应该能看到更多结果。"

示例4：首次设置

用户：“我刚安装了Thoth，帮我配置一下”

1. 尝试从环境变量迁移
   migrate_settings()
   → 从环境变量导入了5个设置

2. 检查缺少的必需设置
   validate_settings()
   → warnings: ["vault_path 未设置"]

3. 设置必需路径
   update_settings(
     section="paths",
     updates={
       "vault_path": "/path/to/obsidian/vault",
       "pdf_directory": "thoth/papers/pdfs"
     }
   )

4. 验证API密钥
   view_settings(section="api")
   → 检查哪些密钥已配置

5. 响应：
   "初始配置完成！

   已配置：
   ✓ OpenAI API密钥
   ✓ 知识库路径
   ✓ PDF目录

   可选（未配置）：
   - Semantic Scholar API密钥（更高速率限制）
   - Anthropic API密钥（替代LLM）

   您现在可以开始使用Thoth。您希望我：
   - 运行测试搜索以验证一切正常？
   - 帮助您导入现有PDF？"

设置参考

必需设置

设置	分区	用途
`openai_api_key`	api	LLM和嵌入
`vault_path`	paths	Obsidian知识库位置

可选设置

设置	分区	用途
`semantic_scholar_api_key`	api	更高速率限制
`anthropic_api_key`	api	替代LLM
`auto_discovery_enabled`	discovery	后台搜索

最佳实践

安全性

切勿在聊天中共享API密钥
在共享配置中对敏感值使用环境变量
API密钥在view_settings输出中被屏蔽

配置更改

更改后始终验证
某些RAG更改需要重新索引（使用RAG管理技能）
重大配置更改后进行测试

备份

设置位于thoth.settings.json中
重大更改前备份
谨慎使用reset_settings

故障排除

设置未生效

1. 验证设置：validate_settings()
2. 检查验证输出中的错误
3. 如果需要，重启服务
4. 对于RAG更改，运行重新索引

无效设置文件

1. 尝试validate_settings()获取具体错误
2. 重置特定分区：reset_settings(section="broken_section")
3. 最后手段：reset_settings(all=true)

更新后缺少设置

1. 检查是否运行了迁移：migrate_settings()
2. 验证设置文件的文件权限
3. 检查分区/键名中的拼写错误

设置	分区	默认值	用途
`pdf_directory`	paths	thoth/papers/pdfs	PDF存储
`chunk_size`	rag	1000	RAG分块大小
`min_relevance`	search	0.7	搜索阈值