Skip to content

UPGRADE_GUIDE.md

Latest commit

 

History

History
269 lines (204 loc) · 6.1 KB

UPGRADE_GUIDE.md

File metadata and controls

269 lines (204 loc) · 6.1 KB

CCCP 配置升级指南

本指南指导如何将现有的 CCCP 配置升级到改进版本，获得更好的默认值和配置管理。

📋 改进清单

  • 创建集中的环境变量管理模块 (env-config.js)
  • 改进默认值（MAX_LLM_CALLS, CLI_CONCURRENCY, PREFETCH_MAX_FILES）
  • 添加启动时验证和警告
  • 支持 .env 文件配置
  • 改进模型继承（CONTRACT_MODEL 和 BUNDLE_MODEL 继承 CCCP_MODEL）
  • 提供详细的 .env.example 文档
  • 新增改进的启动脚本

🔧 升级步骤

第一步：添加新文件

  1. 复制 env-config.js

    cp src/env-config.js src/

  2. 复制 .env.example

    cp .env.example ./

  3. 创建 .env 工作文件

    cp .env.example .env
# 编辑 .env，填入实际的 ANTHROPIC_API_KEY
nano .env

第二步：安装 dotenv 依赖

npm install dotenv

第三步：更新现有代码引用

选项 A：逐模块更新（建议）

修改 src/index.js：

// 在文件顶部添加
import { ENV, validateConfig, printConfigSummary } from './env-config.js';

// 在 McpServer 初始化前添加验证
const errors = validateConfig();
if (errors.length > 0) {
  console.error('Configuration errors:', errors);
  process.exit(1);
}

if (process.env.DEBUG === '1') {
  printConfigSummary();
}

修改 src/dual-pool.js：

// 替换现有的环境变量读取
import { ENV } from './env-config.js';

// 然后改用
const API_CONCURRENCY = ENV.API_CONCURRENCY;
const CLI_CONCURRENCY = ENV.CLI_CONCURRENCY;

修改 src/budget-guard.js：

import { ENV } from './env-config.js';

// 替换所有 process.env.CCCP_MAX_* 为 ENV.MAX_*
const CONFIG = {
  MAX_LLM_CALLS: ENV.MAX_LLM_CALLS,
  MAX_REPAIR_CALLS: ENV.MAX_REPAIR_CALLS,
  MAX_FALLBACKS: ENV.MAX_FALLBACKS,
  // ...
};

修改 src/contract-injector.js：

import { ENV } from './env-config.js';

// 现在支持继承了
export const CONTRACT_MODE = ENV.CONTRACT_FIRST;
export const CONTRACT_FAIL_MODE = ENV.CONTRACT_FAIL_MODE;
export const CONTRACT_MODEL = ENV.CONTRACT_MODEL; // 自动继承 CCCP_MODEL

选项 B：全局替换（快速但需小心）

# 在 src 目录下进行全局替换
find src -name "*.js" -not -name "env-config.js" -type f -exec sed -i 's/process\.env\.CCCP_/ENV./g' {} \;

第四步：更新 package.json

添加依赖：

{
  "dependencies": {
    "dotenv": "^16.4.5"
  }
}

更新启动脚本（可选）：

{
  "scripts": {
    "mcp": "node src/index.js",
    "start": "node src/index.js",
    "start:debug": "DEBUG=1 node src/index.js",
    "start:dotenv": "node bin/cccp-improved.js"
  }
}

第五步：测试升级

# 验证环境变量解析
node -e "import('./src/env-config.js').then(m => m.printConfigSummary())"

# 测试完整启动
npm start
# 或
node bin/cccp-improved.js

📊 变更摘要

默认值改进

配置项 旧值 新值 影响
CCCP_MAX_LLM_CALLS 8 12 +50% 预算，更少失败
CCCP_CLI_CONCURRENCY 2 4 +100% CLI 吞吐
CCCP_PREFETCH_MAX_FILES 5 10 +100% 文件预取
CCCP_PREFETCH_MAX_TOTAL_CHARS 20000 50000 +150% 上下文
CCCP_CACHE_TTL_MS 24h 48h 更好的缓存命中

新增功能

功能 说明
模型继承 CONTRACT_MODEL 和 BUNDLE_MODEL 继承 CCCP_MODEL
.env 支持 自动加载 .env 文件
启动验证 自动检查必需配置
配置输出 printConfigSummary() 和 printDetailedConfig()
警告系统 checkConfigWarnings() 提示非理想配置

🚨 常见问题

Q1: 我已经在生产环境中设置了环境变量，需要迁移吗？

A: 不需要立即迁移。新模块完全向后兼容：

  • 如果有 CCCP_MAX_LLM_CALLS 环境变量，会使用它
  • 否则使用新的默认值

建议逐步迁移：

  1. 先升级到新版本（向后兼容）
  2. 观察行为是否符合预期
  3. 如需调整，通过 .env 文件配置

Q2: 如何在 Docker 中使用 .env 文件？

A: 有两种方式：

方式1：挂载 .env 文件

# Dockerfile
COPY .env .env
CMD ["npm", "start"]

方式2：使用环境变量传递

docker run -e CCCP_MAX_LLM_CALLS=20 -e ANTHROPIC_API_KEY=$API_KEY ...

Q3: 生产环境中应该设置哪些环保量？

A: 最小必需集合：

export ANTHROPIC_API_KEY=sk-...
export CCCP_API_CONCURRENCY=8
export CCCP_MAX_LLM_CALLS=20

Q4: 如何在不同环境之间切换配置？

A: 使用配置预设和 CCCP_PROFILE 环境变量：

# 开发环境（平衡）
CCCP_PROFILE=default npm start

# 测试环境（质量优先）
CCCP_PROFILE=quality_max npm start

# 生产环境（速度优先）
CCCP_PROFILE=fast npm start

或者使用多个 .env 文件：

# 创建不同配置
cp .env.example .env.prod
cp .env.example .env.dev

# 加载不同的配置
dotenv -e .env.prod npm start
dotenv -e .env.dev npm start

Q5: 硬限制（HARD LIMITS）如何设置？

A: 硬限制用于保护长时间运行的进程。在 .env 中设置：

# 全局最多 200 次 LLM 调用
CCCP_MAX_LLM_CALLS_HARD=200

# 全局最多 10M 字符
CCCP_MAX_TOTAL_CHARS_HARD=10000000

✅ 验证清单

升级完成后，请验证以下项目：

  • .env 文件已创建并包含 ANTHROPIC_API_KEY
  • npm install dotenv 已执行
  • env-config.js 已添加到 src 目录
  • 主要模块已更新使用 ENV 对象
  • 测试启动：npm start 成功
  • 配置摘要正确显示
  • 所有现有功能仍然正常工作

🔄 回滚步骤

如果需要回滚到旧版本：

# 1. 移除 .env 文件
rm .env

# 2. 移除 env-config.js
rm src/env-config.js

# 3. 恢复代码更改
git checkout src/

# 4. 卸载 dotenv
npm uninstall dotenv

📞 支持

  • 如有问题，查看 ANALYSIS_REPORT.md 的详细分析
  • 查看 .env.example 的配置说明
  • 运行 DEBUG=1 npm start 获取详细日志