# qimingcode 二进制代码签名问题

**日期**: 2026-03-28
**影响**: macOS 平台

---

## 问题描述

在 macOS 上，当从本地构建复制 qimingcode 二进制到 `~/.qimingclaw/node_modules/qimingcode-darwin-arm64/bin/` 时，运行时会收到 SIGKILL 信号。

### 症状

```log
[2026-03-28 10:29:08.097] [info]  [AcpClient stdin] 📤 {"jsonrpc":"2.0","id":0,"method":"initialize"...}
[2026-03-28 10:29:09.380] [info]  [AcpClient] Process exited { code: null, signal: 'SIGKILL' }
```

直接运行也失败：
```bash
~/.qimingclaw/node_modules/qimingcode-darwin-arm64/bin/qimingcode --version
# Exit code 137 (SIGKILL)
```

---

## 根因分析

macOS 的代码签名验证机制会拒绝未正确签名的二进制文件。

### 验证过程

1. 源二进制有 adhoc 签名：
   ```
   codesign -dv ~/workspace/qimingcode/.../qimingcode
   Signature=adhoc
   ```

2. 复制后文件哈希一致（排除文件损坏）：
   ```
   shasum -a 256 source/qimingcode: 69605cb4...
   shasum -a 256 target/qimingcode: 69605cb4...  # 相同
   ```

3. 但运行时被系统终止

### 原因

macOS 对从网络下载或复制的二进制有额外的安全检查。即使文件有 adhoc 签名，某些情况下仍需要重新签名才能通过验证。

---

## 解决方案

### 临时修复（手动）

```bash
# 重新签名
codesign --force --sign - /path/to/qimingcode

# 验证
/path/to/qimingcode --version
```

### 长期方案

#### 方案 1：CI/CD 构建时签名

在 qimingcode 的构建流程中添加正式签名步骤：

```yaml
# .github/workflows/release.yml
- name: Sign binary (macOS)
  if: runner.os == 'macOS'
  run: |
    codesign --force --sign - ./dist/qimingcode-darwin-arm64/bin/qimingcode
```

#### 方案 2：Electron 端自动签名

在复制二进制后自动签名：

```typescript
// src/main/services/packages/dependencies.ts
import { execSync } from "child_process"

function copyQimingCodeBinary(source: string, target: string) {
  fs.copyFileSync(source, target)

  // macOS 需要重新签名
  if (process.platform === "darwin") {
    try {
      execSync(`codesign --force --sign - "${target}"`, { stdio: "pipe" })
      log.info("Binary re-signed successfully", { target })
    } catch (error) {
      log.warn("Failed to re-sign binary", { error })
    }
  }
}
```

#### 方案 3：使用 adhoc 签名 + 时间戳

```bash
codesign --force --sign - --timestamp none /path/to/qimingcode
```

---

## 最佳实践

1. **开发环境**：复制二进制后始终运行 `codesign --force --sign -`

2. **生产环境**：
   - 使用 Apple Developer 证书正式签名
   - 或在 CI/CD 中使用 adhoc 签名 + 公证

3. **调试技巧**：
   ```bash
   # 检查签名状态
   codesign -dv --verbose=4 /path/to/binary

   # 检查扩展属性
   xattr -l /path/to/binary

   # 清除扩展属性
   xattr -c /path/to/binary
   ```

---

## 相关链接

- qimingcode 性能优化文档：`/Users/apple/workspace/qimingcode/docs/PERF-PLUGIN-INIT-2026-03-28.md`
- Apple Code Signing Guide: https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/