PromptX/docs/dacp-config-management.md

DACP配置管理指南

版本: 1.0.0
更新日期: 2025-01-19
作者: Sean

---

概述

DACP配置管理系统支持分层配置策略，实现了项目级配置优先、用户级配置回退的灵活配置管理机制。这允许团队在项目中共享配置，同时保持个人配置的独立性。

配置优先级

项目级配置 (.promptx/dacp/) > 用户级配置 (~/.promptx/dacp/)

优先级说明

1. 项目级配置 - 位于当前项目的 .promptx/dacp/ 目录

   • 优先级最高
   • 适合团队共享的项目配置
   • 可以版本控制管理

2. 用户级配置 - 位于用户主目录的 ~/.promptx/dacp/ 目录

   • 作为回退选择
   • 个人私有配置
   • 跨项目通用配置

配置文件结构

邮件服务配置示例 (send_email.json)

{
  "provider": "gmail",
  "smtp": {
    "user": "your-email@gmail.com",
    "password": "your-app-password"
  },
  "sender": {
    "name": "Your Name",
    "email": "your-email@gmail.com"
  }
}

支持的邮件服务商

• Gmail: smtp.gmail.com:587
• Outlook: smtp-mail.outlook.com:587
• QQ邮箱: smtp.qq.com:465
• 163邮箱: smtp.163.com:465
• 126邮箱: smtp.126.com:465

使用方式

1. 项目级配置（推荐）

创建项目级配置文件：

# 创建配置目录
mkdir -p .promptx/dacp

# 创建邮件配置文件
cat > .promptx/dacp/send_email.json << 'EOF'
{
  "provider": "gmail",
  "smtp": {
    "user": "project-team@gmail.com",
    "password": "project-app-password"
  },
  "sender": {
    "name": "Project Team",
    "email": "project-team@gmail.com"
  }
}
EOF

2. 用户级配置（个人回退）

创建用户级配置文件：

# 创建用户配置目录
mkdir -p ~/.promptx/dacp

# 创建个人邮件配置
cat > ~/.promptx/dacp/send_email.json << 'EOF'
{
  "provider": "gmail",
  "smtp": {
    "user": "personal@gmail.com",
    "password": "personal-app-password"
  },
  "sender": {
    "name": "Personal Name",
    "email": "personal@gmail.com"
  }
}
EOF

Gmail配置特别说明

应用专用密码设置

Gmail用户需要使用应用专用密码：

1. 进入 Google 账户设置
2. 启用两步验证
3. 生成应用专用密码
4. 在配置文件中使用生成的密码

配置示例

{
  "provider": "gmail",
  "smtp": {
    "user": "yourname@gmail.com",
    "password": "abcd efgh ijkl mnop"  // 应用专用密码（16位，含空格）
  },
  "sender": {
    "name": "Your Name",
    "email": "yourname@gmail.com"
  }
}

配置管理命令

检查配置状态

const DACPConfigManager = require('./src/lib/utils/DACPConfigManager')
const configManager = new DACPConfigManager()

// 检查是否有配置（任意级别）
const hasConfig = await configManager.hasActionConfig('send_email')

// 检查项目级配置
const hasProjectConfig = await configManager.hasProjectActionConfig('send_email')

// 检查用户级配置  
const hasUserConfig = await configManager.hasUserActionConfig('send_email')

读取配置

// 读取配置（自动优先级选择）
const config = await configManager.readActionConfig('send_email')

// 明确读取项目级配置
const projectConfig = await configManager.readProjectActionConfig('send_email')

// 明确读取用户级配置
const userConfig = await configManager.readUserActionConfig('send_email')

写入配置

const emailConfig = {
  provider: "gmail",
  smtp: {
    user: "example@gmail.com",
    password: "app-password"
  },
  sender: {
    name: "Example User",
    email: "example@gmail.com"
  }
}

// 写入项目级配置
await configManager.writeProjectActionConfig('send_email', emailConfig)

// 写入用户级配置
await configManager.writeUserActionConfig('send_email', emailConfig)

最佳实践

1. 团队协作

• 项目配置: 使用通用的项目配置，可以提交到版本控制
• 敏感信息: 个人敏感信息（如密码）使用用户级配置
• 配置模板: 在项目中提供配置模板，团队成员复制后修改

2. 安全性

• 不要提交密码: 项目级配置可以包含结构，但不应包含真实密码
• 使用应用密码: Gmail等服务使用应用专用密码
• 权限控制: 确保配置文件权限设置合理

3. 配置继承

当前版本支持完全覆盖模式：

• 如果存在项目级配置，完全使用项目级配置
• 如果不存在项目级配置，回退到用户级配置
• 未来版本可能支持配置合并模式

错误处理

常见错误和解决方案

1. 配置文件不存在

   解决方案: 按照上述步骤创建配置文件
   

2. 项目目录无法获取

   解决方案: 确保在PromptX项目目录中运行，或使用用户级配置
   

3. SMTP认证失败

   解决方案: 检查用户名、密码和服务器配置
   

4. Gmail应用密码问题

   解决方案: 重新生成应用专用密码，确保格式正确
   

版本兼容性

• 向后兼容: 现有用户级配置继续工作
• API兼容: 原有API方法保持不变
• 渐进升级: 可以逐步迁移到项目级配置

扩展功能

未来规划

1. 配置合并模式: 支持项目级和用户级配置的智能合并
2. 配置验证: 增强的配置验证和错误提示
3. 配置模板: 内置常用配置模板
4. 环境变量支持: 支持通过环境变量覆盖配置
5. 配置加密: 敏感信息的加密存储

---

参考资料

• DACP白皮书
• MCP集成指南
• PromptX架构原理