# 开发 Quickstart — Day 0 (SuperIntern 拿到 vault 后 30 分钟内完成)

> **本文档目标**: SuperIntern 第一次拿到 vault 后, 跟随本文档逐步操作,
> 30 分钟内完成本地环境部署 + 烟雾测试通过 + 能跑第一个 Skill。
>
> 如果某步卡住超过 5 分钟, 看本文末尾 § 常见问题 或问 CTO。
>
> **v3.1.1 (2026-05-27) 状态**: V0 5 case 收官 + `/boss` 用户面命令就位.
> 装完即可在 Claude Code 内 `/boss list` 验证。

---

## 0. 前提

你已有:
- macOS 或 Ubuntu 24 开发机
- 公司 GitLab 账号 + SSH key
- 1Password 账号 (用于密钥)
- 飞书账号 (用于接收测试卡片)

---

## Step 1. 拉代码 (2 min)

```bash
git clone git@${GITLAB_HOST}:judgement/boss-vault.git ~/boss-vault
cd ~/boss-vault
git log --oneline -5     # 应看到 v3.4 锁定 commit
```

---

## Step 2. 安装系统依赖 (5 min)

**macOS:**
```bash
brew install python@3.11 git curl jq
```

**Ubuntu 24:**
```bash
sudo apt update
sudo apt install -y python3.11 python3-pip git curl jq
```

验证:
```bash
python3 --version    # 应 ≥ 3.11
git --version
jq --version
```

---

## Step 3. 跑 install.sh (开发模式) (3 min)

```bash
bash scripts/install.sh --skip-systemd --skip-1password
```

输出末尾应看到:
```
✅ 安装完成
```

如果某步骤报错, 看 § 常见问题。

---

## Step 4. 跑 smoke test (1 min)

```bash
make smoke
```

应输出:
```
=== Skill lint ===
✅ skill_lint PASSED — 无 issue

=== Redact check fixtures ===
17 passed, 0 failed

=== Laotian filter status ===
{...}

✅ smoke test 完成
```

> v2 后 fixture 增至 17 (新增 3 条锚点真名变体, 详见本地 `tests/unit/test_redact_check.py`)。

接着跑端到端 smoke (T10):

```bash
make smoke-e2e
```

应输出 11 项契约 check 全 ✅ + `e2e smoke PASSED`。

✓ 如果到这里全 PASS, 你的本地环境已经能写代码。

### 更多 make targets (v2.7 新)

```bash
make test                  # pytest tests/ · 应 119 passed, 1 skipped
make attribution-due       # 30/90/365 调度器: 列今天到期 checkpoint
make attribution-check     # 跑 attribution_check.py --dry-run (V0 stub)
make cloud-sync-dry        # cloud_sync.sh laotian target print-only
make cloud-sync-vault-dry  # cloud_sync.sh vault target print-only
make help                  # 全 target 列表
```

---

## Step 5. 阅读 (你最好在 Day 0 当天读完, 不一定 30 分钟内)

按优先级:
1. **CLAUDE.md** (550+ 行) — vault 的工程纪律全文, 必读
2. **v3.1 系统设计与开发方案.docx** (37 页) — 系统为什么这么设计
3. **v3.1 开发实施手册.docx** (59 页) — 你要做什么, 按时间
4. **v3.3 锚点 raw 材料过滤层补丁.docx** (18 页) — laotian 集成的最新设计
5. **panels/default.yaml** + **skills/tian-judgement-orchestrator/SKILL.md** — V0 期主入口的具体实现

---

## Step 6. 探索 vault 结构 (5 min)

```bash
# 看 11 个 Skill
ls skills/

# 看主 orchestrator
cat skills/tian-judgement-orchestrator/SKILL.md | head -30

# 看锚点 raw 材料过滤层 (v3.3 新增)
cat skills/laotian-adapter/SKILL.md | head -50
cat scripts/laotian_filter.py | head -50
cat config/laotian_filter_rules.yaml

# 看 sage-wiki 配置
cat config.yaml
```

---

## Step 7. 配置 1Password (Day 1 再做, 不阻塞 Day 0) (10 min)

```bash
# 装 1Password CLI
curl -sSL https://app-updates.agilebits.com/cli/v2/op_install.sh | bash

# 登录
op signin

# 创建 vault
op vault create boss-vault-prod

# 在 1Password GUI 中添加 4 个 item 到此 vault:
#   - anthropic (字段: credential)
#   - lark (字段: app_id, app_secret)
#   - marsdata (字段: credential)

# 验证可以读出
op read "op://boss-vault-prod/anthropic/credential" > /dev/null && echo "✓"
```

---

## Step 8. 装 Hermes (Day 1, 仅 CTO 或 SuperIntern 在生产机器上做)

```bash
# 在 prod-01 机器上 (不是开发机)
curl -sSL https://hermes-agent.io/install.sh | bash
hermes --version          # 应 ≥ v0.4

# 初始化
hermes init --workdir ~/.hermes
ln -sfn ~/boss-vault/skills ~/.hermes/skills
ln -sfn ~/boss-vault/.mcp.json ~/.hermes/.mcp.json
ln -sfn ~/boss-vault/.hermes/scheduler.yaml ~/.hermes/scheduler.yaml

# 启动 (生产用 systemd, 开发用 daemon)
op run --env-file=op.env -- hermes start --daemon
hermes status
```

---

## Step 9. 跑你第一个 Skill (Day 1) (10 min)

### 推荐路径 · `/boss` slash command (v3.1.1 新)

```bash
# 1. install /boss skill (symlink 模式, 5 秒)
bash scripts/install_tian_skill.sh

# 2. 在 Claude Code 内验证 (新 session)
#    输入: /boss list
#    应看到 5 个已判断议题 (T11+T19+C3+C4+C5)

# 3. 装好就可以跑判断:
#    /boss "我想判断 X 议题"           # FRESH 模式
#    /boss X --refresh                  # EVOLUTION 模式 (已有 brand 时)
#    /boss X --quick                    # 跳过 WebSearch
#    /boss X --no-judges                # 仅 synthesis 不打分
```

### 等价 CLI 路径 (Hermes 上云后, prod 环境)

```bash
# 列所有 Skill
hermes skills list

# 跑 attribution-checker 干跑
hermes skill run attribution-checker --dry-run

# 跑锚点 raw 材料过滤层 (前提: backups/feishu/ 有内容)
make laotian-filter

# 直接跑 Python pipeline (本地等价于 /boss)
python3 scripts/run_pipeline_local.py "议题描述" --brand <slug>
```

---

## Step 10. W1 D-Day 5/26 任务清单

W0 准备期 (5/22-5/25) 结束时, 你应该:
- ✅ 完成 Step 1-7 (本地环境)
- ✅ git tag `v0-prep` 存在
- ✅ 项目主理 + zhanglu 已确认锚点的飞书 `open_id` (B-1 解决, 见 v3.3 补丁 §6.2)
- ✅ zhanglu 已部署 laotian + lark-cli OAuth (B-3 解决)

W1 D-Day (5/26 周一) 开始:
- 阅读 v3.1 开发实施手册 §2.2 (W1 任务分日表)
- 你的首日任务: 填 `cases/C-2026-0001/case.json` (某 B2B 客户战略议题, 项目主理 提供模板)
- + 写 industry-trend doctrine 文件 (`skills/industry-trend-perspective/references/doctrine/01-pest.md` 等)

---

## § 常见问题

### Q1: `pip install -r requirements.txt --break-system-packages` 失败 "externally-managed-environment"

A: 你的 pip 是系统 pip, 加 `--break-system-packages` 即可。或用 venv:
```bash
python3 -m venv ~/.venv-boss
source ~/.venv-boss/bin/activate
pip install -r requirements.txt
```

### Q2: `make smoke` 报 "skill_lint.py: No module named yaml"

A: PyYAML 未装, 跑:
```bash
pip3 install pyyaml --break-system-packages
```

### Q3: pre-commit hook 阻断 commit, 但我确认无敏感数据

A: 看 hook 阻断点:
```bash
git commit ... 2>&1 | tee /tmp/last-commit.log
cat /tmp/boss-redact.log    # 或 /tmp/boss-skill-lint.log
```

如果确实是 false positive, 紧急时可:
```bash
git commit --no-verify   # 但需 CTO 在飞书群说明原因
```

### Q4: laotian_filter.py 报 "backups/feishu/ 不存在"

A: 这是正常的 — W0/W1 期 laotian 还没装, backups 目录是空的。filter 在空目录下也能跑, 只是 `examined: 0`。

### Q5: 我修改 SKILL.md 后, sage-wiki 是否会自动重编译?

A: ❌ 不会。SKILL.md 在 sage-wiki 的 ignore 列表中 (D7 边界)。修改后只影响 MBA 层。
✅ 修改 `raw/clippings/` 或 `anchors/tian/raw/feishu-laotian/docs/` 才会触发重编译。

### Q6: 我想跑某个 Skill 但 Hermes 还没装

A: Hermes 是生产环境必需的, 开发期你可以直接读 `skills/<name>/SKILL.md` 思考 prompt 内容,
然后用 Claude API CLI / Claudian (Obsidian 插件) / Claude Code CLI 任一手段跑。

---

## 联系

- 工程问题: CTO (飞书私聊)
- 业务问题: 项目主理
- laotian 相关: zhanglu (laotian 项目作者)
- 紧急 (生产宕机): PagerDuty 群

参考:
- `docs/troubleshooting.md` — 详细故障排查
- `docs/api-contracts.md` — 关键接口契约
- `v3.1 开发实施手册.docx` — 完整开发指南