# Deployment Guide · 三种部署形态

> v0.2.1 起 boss-vault 支持三种部署形态。**任选其一**, 不互斥。三种判断质量一致 (同一 boss-skills + 5 镜头 + adversarial_view + anchor_delta + 30/90/365 attribution)。
>
> 见 [ADR-003 · Deployment as optional](adr/ADR-003-deployment-as-optional.md) 的决策背景。

---

## 部署形态对比

| 形态 | 别名 | 适合 | always-on | 30/90/365 attribution | 飞书 push | infra 成本 | 装机时间 |
|---|---|---|---|---|---|---|---|
| **D1** | Local Claude Code | 个人 / 小团队 / V0 期 | ❌ 终端在线时 | launchd cron 本地 | ❌ CLI 调用 | $0 | 5 min |
| **D2** | Self-host Hermes | 内部团队 / always-on 需求 | ✅ | Hermes scheduler 自动 | ✅ 飞书 webhook | $10-30/月 | 1-2 小时 |
| **D3** | GitHub Actions | 开源用户 / 无本地 / 无云 | ⚠️ schedule 触发 | GitHub cron (5 min granularity) | ❌ | $0 (公开 repo) | 15 min |

**推荐**:
- 个人首次用 → D1
- 内部团队 ≥ 3 人 / 需要飞书 push → D2
- 把 boss-vault 当作开源产品自己用 → D1 + 可选 D3 (attribution 自动化)

---

## D1 · Local Claude Code (推荐 default)

最轻量。装完 5 分钟可用。

### 安装

```bash
# 1. clone
git clone https://github.com/zhanglunet/boss-vault.git ~/boss-vault
cd ~/boss-vault

# 2. 装依赖 (Python 3.10+)
pip install -r requirements.txt

# 3. 装 /boss skill (symlink 到 ~/.claude/skills/)
bash scripts/install_tian_skill.sh

# 4. 配 .env
cp .env.example .env
# 编辑填 ANTHROPIC_API_KEY
```

### 使用

在 Claude Code 内:

```
/boss list                          # 验证安装
/boss "评估某战略议题" --quick     # 跑一次判断 (~ 18 分钟)
/boss panels                        # 列出可用 panel
```

### 30/90/365 attribution (本地 launchd, macOS)

attribution-checker 每天 09:00 扫所有 case, 把到期 checkpoint 拉数据更新。本地用 launchd plist:

```bash
# 1. 复制模板 (推迟到 v0.3.0 提供)
cp templates/com.boss-vault.attribution.plist.example ~/Library/LaunchAgents/com.boss-vault.attribution.plist

# 2. 编辑路径
sed -i '' "s|VAULT_ROOT|$HOME/boss-vault|g" ~/Library/LaunchAgents/com.boss-vault.attribution.plist

# 3. 加载
launchctl load ~/Library/LaunchAgents/com.boss-vault.attribution.plist

# 4. 验证
launchctl list | grep boss-vault
```

**已知限制**: 本地终端 sleep / 关机时 cron 漏触发, 重启后下次 09:00 才补跑。如果痛点严重, 升级到 D2 或 D3。

### Linux 替代 (crontab)

```bash
# crontab -e 加入:
0 9 * * * cd $HOME/boss-vault && python3 scripts/attribution_check.py >> $HOME/.boss-vault-attribution.log 2>&1
```

---

## D2 · Self-host Hermes (云 VM, 内部团队)

适合内部团队 always-on 用法。需要云 VM + 简单运维。

### 适用信号 (来自 ADR-003 §2.3)

- 锚点明确表示需要从飞书 always-on 触发 (非 ad-hoc CLI 调用)
- D1 launchd 大量漏 cron (本地终端常 sleep)
- 团队 ≥ 3 人跨位置协作

### 推荐云配置

| 项 | 推荐 |
|---|---|
| 云厂商 | 腾讯云轻量 / 阿里云 ECS / Hetzner CX22 |
| 规格 | 4C8G · 80GB SSD |
| OS | Ubuntu 22.04 LTS |
| 月费 | ~80-200 元/月 (腾讯云轻量 CN-1) / €5-15 (Hetzner) |

### 部署步骤

```bash
# 1. SSH 到云 VM, 装基础环境
ssh boss@<vm-ip>
sudo apt update && sudo apt install -y python3-pip git nginx

# 2. clone vault
git clone https://github.com/zhanglunet/boss-vault.git ~/boss-vault
cd ~/boss-vault
pip install -r requirements.txt

# 3. 装 Hermes (always-on Agent runtime)
# 详见 Hermes 自己的 install 文档
# 简化: 它会读 .hermes/scheduler.yaml 里的 cron 调度

# 4. 配 systemd service
sudo cp templates/boss-hermes.service.example /etc/systemd/system/boss-hermes.service
sudo systemctl daemon-reload
sudo systemctl enable boss-hermes
sudo systemctl start boss-hermes

# 5. (可选) nginx + 飞书 webhook
sudo cp templates/nginx-boss-hermes.conf.example /etc/nginx/sites-available/boss-hermes
sudo ln -sfn /etc/nginx/sites-available/boss-hermes /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

详见 [`docs/installation.md`](installation.md) (CTO 完整部署指南)。

### 飞书 webhook (D2 独有)

飞书 @ 机器人触发 /boss → Hermes 接收 webhook → 派发 Phase 0-5 → 完成后推送飞书卡片回群。需要:

- 飞书应用 (lark.feishu.cn) 配置 webhook URL → `https://<vm-domain>/feishu/event`
- nginx 转发 → Hermes
- `.env` 填 `LARK_APP_ID` / `LARK_APP_SECRET`

---

## D3 · GitHub Actions (开源用户, 零 infra)

把 attribution-checker 跑在 GitHub Actions 上。适合:

- 没有本地 always-on 机器
- 没有云 VM 预算
- 公开使用 boss-vault, 数据非 confidential

### workflow 示例

`.github/workflows/attribution.yml` (v0.3.0 待添加, 设计如下):

```yaml
name: boss attribution checker

on:
  schedule:
    - cron: '0 9 * * *'        # UTC 09:00 每天 (CN 17:00)
  workflow_dispatch:           # 手动触发

jobs:
  attribution:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install -r requirements.txt
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          WEBSEARCH_API_KEY: ${{ secrets.WEBSEARCH_API_KEY }}
        run: python3 scripts/attribution_check.py --commit-results
      - name: Commit updated attribution
        run: |
          git config user.name "boss-attribution-bot"
          git config user.email "noreply@boss-vault"
          git add reports/ cases/ failure_cards/
          git diff --staged --quiet || git commit -m "chore: attribution checkpoint $(date -I)"
          git push
```

### 适用场景

- attribution_check 不需要 confidential 数据 (用 metric URL + WebSearch)
- 公开 repo 的 GitHub Actions 是 unlimited free
- 私有 repo 也免费 2000 min/月

### 局限

- GitHub Actions 调度精度: 至少 5 min 间隔, 高峰期有延迟
- 不能跑超过 6 小时单次 job
- 触发飞书 push 需要 webhook secret (用 `secrets.LARK_*`)

---

## 跨形态可移植性

`anchors/<slug>/` + `panels/*.yaml` + `cases/<case-id>/` + `reports/<brand>/` 在三种形态下结构完全一致, 可任意迁移:

```bash
# D1 ↔ D2 迁移 (例)
# 在 D1 (本地 Mac) 跑了几个判断 → 想换到 D2 (云 VM)
rsync -av ~/boss-vault/{cases,reports,anchors}/  boss@vm:~/boss-vault/

# 反向 (从 D2 拉回本地)
rsync -av boss@vm:~/boss-vault/{cases,reports,anchors}/  ~/boss-vault/
```

`versions/v{n}_*.md` 永久不可变, 跨形态读出来内容 identical。

---

## 安全 / 脱敏 (跨三种形态相同)

- 所有 deployment 形态前 → 都过 `scripts/redact_check.py` fail-close 出站闸 (CLAUDE.md §9)
- D3 (GitHub Actions) 提交回 repo 前自动 redact_check, fail → 阻断 commit
- D2 (Hermes) 推飞书卡片前 redact_check, fail → 写 `failure_cards/blocked-publish.log`
- D1 (Local) pre-commit hook 自动 redact_check

**confidential 数据** (anchors/<slug>/raw/, cases/, reports/) 默认 gitignored, 三种形态下都不入 git。

---

## 推荐路径

| 你的场景 | 推荐起步 | 何时升级 |
|---|---|---|
| 个人首次试用 | D1 | 痛点出现再升 |
| 内部团队 V0 期 | D1 | 锚点要求飞书 push 时升 D2 |
| 开源外部使用 | D1 (+ D3 自动 attribution) | 永远不必升 D2 |
| 多个锚点 (multi-anchor) | D1 | anchors/<slug>/ 数据多到本地 SSD 紧张时升 D2 |

**反共识** (来自 ADR-003): hosting choice 是 commercial decision, 不是 product capability。不投资 D2 不代表系统不成熟。boss-vault 跨三种形态都是同一套 boss-skills + multi-anchor 数据。

---

## 相关文档

- [ADR-001 · Multi-anchor 架构](adr/ADR-001-multi-anchor-architecture.md)
- [ADR-002 · B 档实施](adr/ADR-002-b-tier-implementation.md)
- [ADR-003 · Deployment as optional](adr/ADR-003-deployment-as-optional.md)
- [`docs/installation.md`](installation.md) (CTO 完整部署 · 偏 D2)
- [`docs/dev-quickstart.md`](dev-quickstart.md) (SuperIntern Day 0 · 偏 D1)
- [`docs/troubleshooting.md`](troubleshooting.md) (常见故障)

---

*v1.0 · 2026-05-28 · 见 ADR-003*