wecom-cli深度技术解析：企业微信开放平台命令行工具的架构与实现原理

{
  "name": "@wecom/cli",
  "bin": { "wecom-cli": "./bin/wecom.js" },
  "optionalDependencies": {
    "@wecom/cli-darwin-arm64": "0.1.1",
    "@wecom/cli-darwin-x64": "0.1.1",
    "@wecom/cli-linux-x64": "0.1.1",
    "@wecom/cli-win32-x64": "0.1.1"
  }
}

// 1. 平台检测：os.platform() + os.arch() → 包名映射
function getPlatformPackage() {
  const platform = os.platform();  // darwin | linux | win32
  const arch = os.arch();          // arm64 | x64
  // 映射到 @wecom/cli-{platform}-{arch}
}

// 2. 二进制路径解析：require.resolve 查找预编译包
function getBinaryPath() {
  const pkgPath = require.resolve(`${pkg}/package.json`);
  const binName = process.platform === 'win32' ? 'wecom-cli.exe' : 'wecom-cli';
  return path.join(path.dirname(pkgPath), binName);
}

// 3. 透传执行：execFileSync 调用 Rust 二进制
execFileSync(binaryPath, process.argv.slice(2), { stdio: 'inherit' });

#[tokio::main]
async fn main() -> Result<()> {
    // 1. 加载 .env 环境变量
    dotenvy::dotenv().ok();

    // 2. 初始化日志
    logging::init_logging();

    // 3. 从 config.rs 获取业务品类，动态生成子命令
    let categories = config::get_categories();

    // 4. 构建 CLI 应用
    let app = Command::new("wecom-cli")
        .subcommand(Command::new("init")...);  // 内置 init 命令

    // 动态添加品类命令
    for cat in &categories {
        app = app.subcommand(Command::new(cat.name).about(cat.description)...);
    }

    // 5. 命令分发
    match matches.subcommand() {
        Some(("init", m))      => cmd::init::handle_init_cmd(m).await,
        Some((category, m))    => cmd::call::handle_call_cmd(category, m).await,
        _ => anyhow::bail!("未知命令"),
    }
}

#[derive(Debug, Clone)]
pub struct CategoryInfo {
    pub name: &'static str,
    pub description: &'static str,
}

pub fn get_categories() -> Vec<CategoryInfo> {
    vec![
        CategoryInfo { name: "contact",  description: "通讯录 — 成员查询和搜索" },
        CategoryInfo { name: "doc",      description: "文档 — 文档/智能表格创建和管理" },
        CategoryInfo { name: "meeting",  description: "会议 — 创建/管理/查询视频会议" },
        CategoryInfo { name: "msg",      description: "消息 — 聊天列表、发送/接收消息" },
        CategoryInfo { name: "schedule", description: "日程 — 日程增删改查和可用性查询" },
        CategoryInfo { name: "todo",     description: "待办事项 — 创建/查询/编辑待办项" },
    ]
}

pub async fn handle_call_cmd(category_name: &str, matches: &ArgMatches) -> Result<()> {
    // 1. 参数解析：method + args + help
    let args = CallArgs::from_arg_matches(matches)?;

    // 2. 校验品类有效性
    if !config::get_categories().iter().any(|c| c.name == category_name) {
        anyhow::bail!("未知的命令品类: {}", category_name);
    }

    // 3. 交互式引导：缺少参数时自动显示帮助
    if args.help || args.method.is_none() {
        help::show_category_tools(category_name).await?;
        return Ok(());
    }

    // 4. 构建 JSON-RPC 请求
    let method = args.method.unwrap();
    let params = serde_json::from_str(&args.args.unwrap_or("{}".into()))?;

    // 5. 特殊超时处理：媒体下载设置 120s
    let timeout = if method == "get_msg_media" { Some(120_000) } else { None };

    // 6. 发送 JSON-RPC 请求
    let response = json_rpc::send(category_name, "tools/call",
        Some(json!({ "name": method, "arguments": params })),
        timeout
    ).await?;

    // 7. 媒体拦截：对 get_msg_media 进行特殊处理
    let response = if method == "get_msg_media" {
        media::intercept_media_response(response).await?
    } else {
        response
    };

    // 8. 输出结果
    println!("{}", response["result"]);
    Ok(())
}

#[derive(Debug, Clone, Serialize)]
struct JsonRpcRequest {
    jsonrpc: &'static str,  // 固定 "2.0"
    id: String,              // 唯一请求标识
    method: String,          // RPC 方法名 (tools/list | tools/call)
    params: Option<Value>,   // 可选参数
}

pub async fn send(
    category: &str,
    method: &str,
    params: Option<Value>,
    timeout_ms: Option<i32>,
) -> Result<Value> {
    // 1. 获取该品类对应的 MCP URL
    let url = mcp::get_mcp_url(category).await?;

    // 2. 构建请求
    let req = JsonRpcRequest {
        jsonrpc: "2.0",
        id: mcp::gen_req_id("mcp_rpc"),  // 格式: mcp_rpc_{timestamp}_{hex}
        method: method.to_string(),
        params,
    };

    // 3. 发送 HTTP POST (默认30s超时)
    let timeout = Duration::from_millis(timeout_ms.unwrap_or(30_000) as u64);
    let resp = reqwest::Client::new()
        .post(&url)
        .json(&req)
        .timeout(timeout)
        .send()
        .await?;

    // 4. 解析响应
    let text = resp.text().await?;
    Ok(serde_json::from_str(&text)?)
}

pub fn gen_req_id(prefix: &str) -> String {
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_millis();
    let random_hex = generate_random_hex(4);  // 8位十六进制
    format!("{prefix}_{timestamp}_{random_hex}")
}
// 示例: mcp_rpc_1711814400000_a3f2b1c9

pub async fn get_mcp_url(category: &str) -> Result<String> {
    let configs = config::get_mcp_config().await?;
    for item in &configs {
        if item.biz_type == category {
            return Ok(item.url.clone());
        }
    }
    anyhow::bail!("当前企业暂不支持 {} 命令", category);
}

// cipher.rs - 加密
pub fn encrypt(key: &[u8; 32], plaintext: &[u8]) -> Result<Vec<u8>> {
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);  // 随机96位nonce
    let ciphertext = cipher.encrypt(&nonce, plaintext)?;
    // 输出格式: nonce(12B) || ciphertext || tag(16B)
    let mut out = nonce.to_vec();
    out.extend(ciphertext);
    Ok(out)
}

// cipher.rs - 解密
pub fn decrypt(key: &[u8; 32], data: &[u8]) -> Result<Vec<u8>> {
    // 最小长度校验: nonce(12) + tag(16) = 28
    if data.len() < NONCE_SIZE + TAG_SIZE { bail!("数据损坏"); }
    let (nonce_bytes, ciphertext) = data.split_at(NONCE_SIZE);
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
    cipher.decrypt(nonce_bytes.into(), ciphertext)
}

// keystore.rs
pub fn save_key(key: &[u8; 32]) -> Result<()> {
    // 优先尝试 OS Keyring (macOS Keychain / Linux Secret Service)
    if keyring::Entry::new("wecom-cli", "master-key")?
        .set_secret(key).is_ok() {
        return Ok(());
    }
    // 回退：写入文件 ~/.config/wecom/key (权限 0o600)
    fs_util::atomic_write(&key_path, key, Some(0o600))
}

// fs_util.rs
pub fn atomic_write(path: &Path, data: &[u8], mode: Option<u32>) -> Result<()> {
    // 1. 在同目录创建临时文件（确保同一文件系统）
    let mut tmp = NamedTempFile::new_in(parent)?;

    // 2. 先设置权限（避免权限窗口期）
    #[cfg(unix)]
    if let Some(m) = mode {
        tmp.as_file().set_permissions(Permissions::from_mode(m))?;
    }

    // 3. 写入 + flush + sync
    tmp.write_all(data)?;
    tmp.as_file().flush()?;
    tmp.as_file().sync_all()?;

    // 4. 原子重命名到目标路径
    tmp.persist(path)?;
    Ok(())
}

// mcp/config.rs
fn sign(secret: &str, bot_id: &str, time: &str, nonce: &str) -> String {
    sha256_hex(&format!("{secret}{bot_id}{time}{nonce}"))
}

// 请求结构
struct GetMcpConfigRequest {
    bot_id: String,
    time: String,      // Unix 时间戳
    nonce: String,      // 随机数
    signature: String,  // sha256(secret + bot_id + time + nonce)
}

// cmd/init.rs
pub async fn handle_init_cmd(matches: &ArgMatches) -> Result<()> {
    let args = InitArgs::from_arg_matches(matches)?;

    // 快速刷新模式
    if args.refresh {
        mcp::config::fetch_mcp_config().await?;
        println!("MCP 配置已刷新");
        return Ok(());
    }

    // 交互式输入（使用 cliclack 库）
    let bot_id = if let Some(id) = args.bot_id {
        id
    } else {
        cliclack::input("请输入 Bot ID").interact()?
    };
    let secret = cliclack::password("请输入 Bot Secret").interact()?;

    // 创建 Bot 对象并持久化
    let bot = auth::Bot::new(bot_id, secret);
    auth::set_bot_info(&bot)?;

    // 验证凭证有效性
    let spinner = cliclack::spinner();
    spinner.start("正在验证凭证...");

    match mcp::config::fetch_mcp_config().await {
        Ok(_) => {
            spinner.stop("凭证验证成功");
            cliclack::outro("初始化完成 ✅")?;
        }
        Err(e) => {
            spinner.stop("凭证验证失败");
            // 回滚：清除已存储的凭证和配置
            auth::clear_bot_info();
            mcp::config::clear_mcp_config();
            cliclack::outro("初始化失败 ❌")?;
            return Err(e);
        }
    }
    Ok(())
}

// mcp/config.rs
pub async fn get_mcp_config() -> Result<Vec<McpConfigItem>> {
    // 优先从本地加密缓存加载
    if let Ok(cached) = load_mcp_config() {
        return Ok(cached);
    }
    // 缓存未命中，从服务器拉取
    fetch_mcp_config().await
}

pub async fn fetch_mcp_config() -> Result<Vec<McpConfigItem>> {
    let resp = fetch_mcp_config_from_server().await?;
    // 加密并缓存到本地
    save_mcp_config(&resp)?;
    Ok(resp)
}

pub async fn intercept_media_response(res: Value) -> Result<Value> {
    // 1. 提取 MCP 响应中的 content[].text 字段
    let biz_data: Value = serde_json::from_str(text)?;

    // 2. 校验业务响应 (errcode == 0)
    if biz_data["errcode"].as_i64() != Some(0) { return Ok(res); }

    // 3. 解码 base64 数据
    let buffer = base64::STANDARD.decode(base64_data)?;

    // 4. 大小校验 (最大 20MB)
    if buffer.len() > 20 * 1024 * 1024 { bail!("媒体文件过大"); }

    // 5. 检测 MIME 类型
    let content_type = utils::detect_mime(media_name, &buffer);

    // 6. 原子保存到本地 (带去重)
    let file_path = utils::save_media(media_name, media_id, &content_type, &buffer).await?;

    // 7. 构建精简响应：移除 base64_data，添加 local_path
    Ok(json!({
        "result": { "content": [{ "type": "text", "text": json!({
            "errcode": 0, "errmsg": "ok",
            "media_item": {
                "local_path": file_path,
                "size": buffer.len(),
                "content_type": content_type
            }
        })}]}
    }))
}

pub fn detect_mime(file_name: Option<&str>, buffer: &[u8]) -> String {
    // 策略1：文件扩展名推断
    if let Some(name) = file_name {
        let mime = mime_guess::from_ext(ext).first_or_octet_stream();
        if mime != APPLICATION_OCTET_STREAM { return mime.to_string(); }
    }
    // 策略2：魔术字节检测
    if let Some(kind) = infer::get(buffer) {
        return kind.mime_type().to_string();
    }
    "application/octet-stream".to_string()
}

pub async fn save_media(...) -> Result<PathBuf> {
    // 原子写入临时文件
    let mut tmp = NamedTempFile::new_in(&dir)?;
    tmp.write_all(data)?;
    tmp.as_file().sync_all()?;

    // 首先尝试原始文件名
    let target = dir.join(make_file_name(&stem, None, &ext));
    match tmp.persist_noclobber(&target) {
        Ok(_) => return Ok(target),
        Err(e) if e.error.kind() == AlreadyExists => { /* 继续去重 */ }
    }

    // 文件已存在：尝试 stem.0.ext, stem.1.ext, ..., stem.100.ext
    for idx in 0..100 {
        let target = dir.join(make_file_name(&stem, Some(idx), &ext));
        // persist_noclobber 保证无覆盖的原子操作
    }
}

pub fn init_logging() {
    let stderr_filter = env::var("WECOM_CLI_LOG_LEVEL").ok();
    let log_file_dir = env::var("WECOM_CLI_LOG_FILE").ok();

    // Stderr 层：人类可读格式
    let stderr_layer = stderr_filter.map(|filter| {
        tracing_subscriber::fmt::layer()
            .with_writer(std::io::stderr)
            .compact()                        // 紧凑格式
            .with_filter(EnvFilter::new(filter))
    });

    // 文件层：JSON 行格式 + 按日轮转
    let file_layer = log_file_dir.map(|dir| {
        let file_appender = tracing_appender::rolling::daily(dir, "ww.log");
        tracing_subscriber::fmt::layer()
            .json()                           // JSON 结构化
            .with_writer(non_blocking)        // 非阻塞写入
    });

    // 组合层级
    let subscriber = registry.with(stderr_layer).with(file_layer);
    tracing::subscriber::set_global_default(subscriber).ok();
}

pub async fn show_category_tools(category: &str) -> Result<()> {
    // 通过 tools/list 接口获取该品类的工具列表
    let response = json_rpc::send(category, "tools/list", None, None).await?;

    // 缓存到 thread_local 避免重复请求
    TOOLS_CACHE.with(|cache| {
        cache.borrow_mut().insert(category.to_string(), tools.clone());
    });

    // 打印品类信息和工具列表
    println!("品类: {} - {}", cat.name, cat.description);
    for tool in &tools {
        println!("  {} - {}", tool["name"], tool["description"]);
    }
}

pub async fn show_tool_help(category: &str, tool_name: &str) -> Result<()> {
    // 优先从缓存读取，未命中则远程拉取
    // 打印工具名称、描述、输入参数 Schema
}

---
name: wecomcli-lookup-contact
description: 通讯录成员查询技能，获取当前用户可见范围内的通讯录成员
metadata:
  requires:
    bins: ["wecom-cli"]      # 依赖的二进制
  cliHelp: "wecom-cli contact --help"  # CLI帮助入口
---

# 通讯录成员查询技能

## 操作
### 1. 获取全量通讯录成员
**调用示例：**
wecom-cli contact get_userlist '{}'

**返回格式：**
{ "errcode": 0, "userlist": [{ "userid": "zhangsan", "name": "张三" }] }

### 2. 按姓名/别名搜索人员
- 精确匹配 → 直接使用
- 模糊匹配 → 返回候选列表
- 无结果 → 告知用户

## 注意事项
- ⚠️ 超过10人时接口报错
- userid 是唯一标识

## 典型工作流
### 工作流1：查询人员信息
用户问："帮我查一下 Sam 是谁？"
1. 调用 get_userlist 获取全量成员
2. 本地筛选匹配
3. 展示结果