# 用户使用与安装手册 (user-manual.md)

> **本文档定位**: 给最终用户(锚点 / 项目主理 / 投委)用,**不是给工程师**。
>
> 工程师装/调试见 `dev-quickstart.md`,这份只讲"装好之后怎么用"。
>
> 阅读时间: 15 分钟 / 实际使用: 1-3 分钟一个议题。
>
> **v3.1.1 (2026-05-27) 状态**:
> - ✅ **V0 5 case 收官** (T11 strategic + T19 customer + C3 organizational + C4 product + C5 brand 全跑通)
> - ✅ **`/boss <议题>` 用户面命令** (仿 `/mba` 范式, install 后在 Claude Code 内直接用)
> - **部署**: 云端单租户 VM (PRD v3.1-r2 §4.1), 终端用户视角不感知 — 飞书 @ 本项目机器人 或 Claude Code 输入 `/boss <议题>` 触发, 30-40 分钟后收报告

---

## 第 1 部分  系统能做什么(一句话)

把你脑子里的"一个具体议题"输入,系统在 30-40 分钟内输出一份完整判断报告,
包含**锚点视角的判断 + 6 个维度评委的独立 review + 5 镜头打分 + 反方观点 + 30/90/365 天验证清单**。

---

## 第 2 部分  我的角色 — 5 种使用场景

按你的角色选场景:

### 场景 A · 锚点(决策者) — 我要做一个战略判断

```
1. 在飞书 @本项目机器人 发: "我想判断一下 <议题>"
   示例: "我想判断一下 X 业务要不要剥离"
   或:   "我想判断一下 Y 客户报价该不该上调 30%"

2. 等 30-40 分钟 (后台 7 评委各跑各的)

3. 飞书收到一张卡片:
   - 一句话主张
   - 5 镜头分数 (我的视角 vs 6 维度评委)
   - 我的视角与维度平均的 delta (异议 / 同意度)
   - 30 天该验证什么

4. 我在卡片上对 5 镜头各 1-5 打分 (我同意度)
   分数会回流到系统, 用于评委漂移监控

5. 30 天后自动收到 attribution check:
   "30 天前的判断 X, 截至今日 confirmed / falsified / pending"
```

**典型用法**: 每天 09:30 看昨天判断的 30 天 checkpoint;
每周一开始 1-2 个新议题。

---

### 场景 B · 项目主理(业务负责) — 我要起一个新议题

```
1. 在 vault 中起新 case:
   cp -r templates/case-template/ cases/C-2026-0042/
   cd cases/C-2026-0042/
   vim case.json    # 填 trigger_event / thesis / evidence (ATELIER 6 字段)

2. 触发判断:
   /boss <议题> --brand <brand-slug>

   (brand-slug 是议题代号, 比如 q3-strategy-review, 用 [a-z0-9-]+)

3. 30-40 分钟后, 看 reports/<brand-slug>/report.md (主报告)
   + reports/<brand-slug>/report.html (可视化, 雷达图)

4. 锚点打分卡片自动推送
   你旁观锚点打分, 决定是否需要 EVOLUTION (再跑一轮加新材料)

5. 30/90 天 attribution 触发后, 你看 failure_cards/ 中是否有新 FC
```

**典型用法**:
- 每周一起 1-2 议题
- 周五看本周 Failure Card 累积
- 每月 15 号跑 `make monthly-review-current` 看评委漂移

---

### 场景 C · 投委(只读旁观)— 我想看本周判断质量

```
1. 在飞书 @本项目机器人 发: "本周判断列表"
   返回近 7 天 case 摘要

2. 点开任一 case 链接 → 飞书内嵌网页打开 report.html
   - 雷达图 (5 镜头 × 7 评委)
   - 反方观点 (评委的 if_thesis_wrong)
   - 30 天 checkpoint 进度

3. 想发表意见: 在飞书群 @决策者 + 截图
   (V0 期不支持直接 in-app 投委评论, V1 加)
```

**典型用法**: 每周日晚抽 15 分钟扫一遍本周 5-10 个 case。

---

### 场景 D · 锚点(EVOLUTION)— 我看了报告,但有新信息要补

```
1. 飞书 @本项目: "C-2026-0042 加新材料"
   或在 CLI: /boss <议题> --refresh    (EVOLUTION 模式)

2. 系统会问你: 新材料是什么?
   - 飞书文档 link → 自动 lark-cli 抓取
   - 文本粘贴 → 直接进 cases/<id>/raw_evidence/
   - 一句话补充 → 进 cases/<id>/notes.md

3. 系统会保留 v1 不动, 生成 v2:
   reports/<brand-slug>/versions/v1_*.md  ← 不可变快照
   reports/<brand-slug>/versions/v2_*.md  ← 新一版

4. 飞书推送 v2 卡片, 标注 "v2: 加入了 X 材料"
   你再对 v2 打分
```

**关键**: v1 永远不会被改 — 历史快照不可变, 这是判断学的核心要求。

---

### 场景 E · CTO(运维)— 我要看系统健康

```
本地终端:
   make filter-status            # laotian 过滤器健康
   make smoke                    # 系统冒烟
   hermes status                 # Hermes Agent 运行状态
   sage-wiki doctor              # Wiki 编译引擎健康

   make monthly-review-current   # 月度评委漂移 + FC 统计

飞书:
   每天 09:00 收到自动健康卡片
   异常项: 飞书 PagerDuty 群
```

---

## 第 3 部分  常用飞书指令

> 在飞书 @本项目机器人 后发以下任意一条:

| 指令 | 用途 | 示例 |
|---|---|---|
| `判断 <议题>` | 起新议题 | "判断 Y 客户报价上调" |
| `查 <case-id>` | 查 case 状态 | "查 C-2026-0042" |
| `本周判断` | 本周 case 列表 | "本周判断" |
| `attribution <case-id>` | 看 case 的 30/90/365 天命中情况 | "attribution C-2026-0042" |
| `EVOLUTION <case-id>` | 加新材料起 v2 | "EVOLUTION C-2026-0042" |
| `failure cards` | 本月 FC 列表 | "failure cards" |
| `健康` | 系统健康摘要 | "健康" |
| `help` | 列出所有指令 | "help" |

---

## 第 4 部分  飞书卡片字段解读

锚点每次收到的卡片是这样:

```
┌──────────────────────────────────────────────────────────┐
│ 📋 C-2026-0042  |  v1  |  example-strategy-issue          │
│                                                          │
│ 💡 一句话主张:                                           │
│ 建议剥离 X 业务, 集中资源在 Y 上                         │
│                                                          │
│ 📊 5 镜头打分 (1-10):                                    │
│                                                          │
│         tian-perspective │ 6 评委均值 │ Δ delta          │
│ 推理性     7.2          │   6.5     │  +0.7            │
│ 证据-论点  6.0          │   5.8     │  +0.2            │
│ 反方处理   5.5          │   6.2     │  -0.7            │
│ 可证伪性   8.0          │   7.0     │  +1.0            │
│ 现实韧性   6.5          │   6.0     │  +0.5            │
│ ─────────────────────────────────────────────           │
│ |Δ| 均值: 0.62  (健康范围 0.5-1.5)                       │
│                                                          │
│ ⚠️ 反方核心担忧 (来自评委 if_thesis_wrong):              │
│ 1. 行业可能处于 hype 阶段而非成熟期 (industry-trend)     │
│ 2. 剥离影响品牌完整性 (strategic-vision)                 │
│                                                          │
│ 🎯 30 天验证项:                                          │
│ - X 业务月营收 < 阈值 Y → confirmed                      │
│ - 客户 NPS < 28 → confirmed                              │
│                                                          │
│ ┌──────┬──────┬──────┬──────┬──────┐                     │
│ │ ★ 1  │ ★ 2  │ ★ 3  │ ★ 4  │ ★ 5  │  ← 锚点点击打分    │
│ │ 推理 │ 证据 │ 反方 │ 可证 │ 韧性 │                     │
│ └──────┴──────┴──────┴──────┴──────┘                     │
│                                                          │
│ [ EVOLUTION ]  [ 标记完成 ]  [ 详细 HTML ]               │
└──────────────────────────────────────────────────────────┘
```

### 字段含义

| 字段 | 解释 | 该关注什么 |
|---|---|---|
| **tian-perspective** | 模拟锚点判断风格的 anchor 评委分 | 与你直觉差太多?系统对你的画像不准 |
| **6 评委均值** | 6 个维度评委 (industry-trend / strategic-vision / customer-strategy / product-strategy / org-strategy / financial-strategy) 的平均 | 高 = 多维度都认同;低 = 多维度都质疑 |
| **Δ delta** | 维度 - tian, 正 = 维度比你乐观,负 = 维度比你严苛 | \|Δ\|>2 = 你与维度严重分歧 → 看具体哪个评委拉大,需要补 doctrine |
| **\|Δ\| 均值健康范围** | 0.5-1.5 是健康 (有适度异议) | <0.5 = 维度变应声筒;>2.0 = 维度与你脱节 |
| **反方核心担忧** | 评委 frontmatter 的 `adversarial_view.if_thesis_wrong` 字段 | 看完后,如果某条让你重新思考,可以 EVOLUTION |
| **30 天验证项** | 系统自动从论点反推的可证伪指标 | 30 天后系统自动检查,你不用记 |

---

## 第 5 部分  安装与首次使用(给非工程师)

### 5.1 你不用自己装

正常情况下,**CTO 已经在公司 prod-01 机器上装好系统**,你只需要:

```
1. 让 CTO 把"boss 判断"机器人加你飞书
2. 学会上面的飞书指令
3. 就可以用了
```

### 5.2 如果你想本地试用(可选)

需要:macOS 或 Ubuntu 24,Python 3.11+,Git,飞书账号。

```bash
# 1. 拉代码 (CTO 提供 GitLab 内部地址)
git clone <gitlab-url>:judgement/boss-vault.git ~/boss-vault
cd ~/boss-vault

# 2. 一键装
bash scripts/install.sh --skip-systemd --skip-1password

# 3. 测试装好
make smoke
# 应输出: ✅ smoke test 完成

# 4. (项目主理 必做, 一次性) 填锚点飞书身份
cp config/laotian_filter_rules.yaml.example config/laotian_filter_rules.yaml
vim config/laotian_filter_rules.yaml
# 在 tian_identifiers 段填 锚点的 飞书 open_id

# 5. 跑你的第一个议题 (CLI 版, 无需 Hermes)
# (需要 Anthropic API key, 见 .env.example)
export ANTHROPIC_API_KEY=sk-...
python3 scripts/manual_judgement.py "我想判断的议题描述"
# (此脚本 V0 期可选, 主要走飞书入口)
```

### 5.3 本地调试的已知限制 (W0 期; code-audit 2026-05-26)

> 本机直接 `git clone` 后跑 `make test-unit` / `make smoke-e2e` 都能过 (契约层),
> **但下列真链路在 dev 机上跑不通,这是预期行为不是 bug**:

| 缺失能力 | 原因 | 本机替代方案 |
|---|---|---|
| `mcp__sage-wiki__query` | sage-wiki 二进制未装,`_wiki/` 没编译 | `run_pipeline_local.py` Phase 1 grep fallback (Wiki 退化方案, 已实施) · LLM 用 `Read` 看 `anchors/tian/raw/feishu-laotian/*.md` |
| `mcp__feishu__search_doc` | 没装 `op` (1Password CLI),飞书 token 没注入 | LLM 用 `WebSearch` 拉公开信息 + 手工提供截图 |
| `mcp__marsdata__fetch_metric` | 同上,marsdata API key 不在 environment | 30/90/365 attribution 跑 `--dry-run`,真信号等云上 |
| Hermes 自动派单 | hermes 二进制未装 | ✅ **路径 B 已落地** (W1 Day 1-3 完成, dev-plan v2.8): `python3 scripts/run_pipeline_local.py "议题" --brand <slug> [--dry-run]` Anthropic SDK 直接驱动 Phase 0-5 + Verify. 真 LLM 跑等 T11 项目主理 选议题。 |
| 出站 webhook 真闸 | 没有 Hermes daemon | `python3 scripts/redact_check.py --stdin --fail-close < payload.json` 手工演练 |

**这些限制不影响**: 契约测试 (**173 PASS** 含 51 run_pipeline_local) / skill_lint / redact 单测 / fixture e2e / `run_pipeline_local --dry-run` 全跑通。
**这些限制影响**: 真 LLM 端到端 (W2 V0 验收目标),需要 ANTHROPIC_API_KEY 配 + 项目主理 选议题。云 VM (T05a) 起来后 Hermes 可接管,但不强阻塞 V0。

详见 `docs/code-audit-2026-05-26.md` §3 和 dev-plan §"风险与缓解" #3。

---

### 5.4 我得装什么生产服务?

如果你是 CTO, 见 `dev-quickstart.md` 第 5-12 步(systemd / Hermes / sage-wiki / 1Password / 飞书 webhook 配置)。

---

## 第 6 部分  常见问题 (用户视角)

### Q1: 我提了议题,30 分钟没收到卡片

**首先检查**:
- 飞书是否将"本项目机器人"加为好友?(在飞书搜"boss 判断"主动加)
- 你的议题描述有没有完整三要素(触发事件 + 时间 + 干系人)?

如果都 OK, 联系 CTO 看 `~/.hermes/logs/`。

### Q2: tian-perspective 评委给的分跟我直觉差很多

这是预期的 — 系统是根据你**过去的访谈 + 飞书文档**训练的,不是实时读心。

**修复方法**: 
- 每月 review 中, 关注 anchor_delta 漂移信号
- 如果 |Δ| 持续 > 2, 让 项目主理 补 `references/research/` 加新的锚点访谈片段

### Q3: 我对评委的某个 review 强烈不同意,怎么办

**正常**:评委的工作就是从一个特定 doctrine 视角挑刺。你不必同意每条。

**如果觉得评委系统性错了**:
- 在飞书私聊 项目主理
- 项目主理 评估是否要修 `skills/<评委>/references/doctrine/` 加新规则,或者降权

### Q4: 飞书机器人不响应我

3 种可能:
1. Hermes Agent 服务 down → CTO 跑 `systemctl restart hermes-agent`
2. 你不在系统的 user 白名单 → CTO 在 `.mcp.json` 中加你的飞书 user_id
3. 你的指令系统不识别 → 发 "help" 看可用指令

### Q5: 我之前的判断历史在哪查

```
~/boss-vault/cases/<case-id>/            # case 起点
~/boss-vault/reports/<brand-slug>/       # 报告 + 各版本
~/boss-vault/_wiki/log.md                # 全局历史日志
```

或在飞书 @本项目: "本月所有判断"。

### Q6: 系统数据会传到 GitHub 吗?

**绝对不会**。

- 所有 raw 数据 (飞书备份 / 锚点 raw 材料 / 锚点访谈 / case / 报告 / FC) 都在本地, `.gitignore` 排除
- 只有代码与设计文档可传 GitHub
- 锚点飞书 user_id 在 `config/laotian_filter_rules.yaml` 中, 此文件 .gitignore 排除
- 详见 `docs/security-and-deidentification.md`

### Q7: 我换电脑了,怎么迁移?

数据在 prod-01 服务器, 不在你电脑上。你换电脑后:
1. 还是用飞书机器人, 跟之前一样
2. 不需要数据迁移

如果你要在新电脑装本地 vault (场景 5.2), 重跑 `bash scripts/install.sh`。

---

## 第 7 部分  反馈与迭代

### 7.1 我觉得某次判断质量不行

→ 飞书 @项目主理 + 截图卡片 + 说"为什么不满意"

项目主理 会:
- 当周内分析根因
- 如果是 doctrine 缺陷 → 修 references/
- 如果是 case.json 填得不准 → 重起 v2
- 如果是评委漂移 → 写入月度 review 报告

### 7.2 我想加一个新评委维度

例:法务、合规、ESG。

→ 飞书 @项目主理 + 描述新维度的判断 doctrine

项目主理 会评估:
- V0 期 (6 个维度) 通常够用
- V1+ 期可考虑新增评委 (工程量约 3-5 天)
- 不建议超过 8 个评委 (过多评委 = 信号噪音)

### 7.3 我想停用某个评委

→ 单次:在指令中加 `--panel-drop <评委名>`
   ```
   /boss my-issue --panel-drop financial-strategy
   ```

→ 长期:修 `panels/default.yaml` 的 `auto_judge_selection` 段(需 CTO + 项目主理 review)

---

## 第 8 部分  系统能力边界 (你必须知道)

| 系统不擅长 | 不擅长的原因 | 怎么办 |
|---|---|---|
| 你私下的、未沉淀进 vault 的想法 | 系统读不到你脑子 | EVOLUTION 时把想法补进 raw_evidence/ |
| 严格量化的财务建模 | 系统是质化判断辅助, 不是 Excel | 让财务部跑模型, 再让系统判断模型假设是否成立 |
| 实时市场数据(股价 / 汇率) | sage-wiki + marsdata 有日级延迟 | 不要让系统做 "今天股价" 类问题 |
| 法律咨询 | 没有法务评委(V0) | 用其他法律专业工具,系统判断"是否要找法务" |
| 极度专业的技术细节(芯片设计 / 生物医药) | 评委是商业判断 doctrine,不是技术专家 | 系统判断 "战略层面",技术细节找专家 |
| 你与某个人的情感问题 | 没在判断学范畴 | 找朋友 |

---

## 第 9 部分  紧急联系 

| 情况 | 联系 |
|---|---|
| 飞书机器人无响应 | CTO (飞书私聊) |
| 我误删了某 case | CTO (从 git / 备份恢复) |
| 我看到不应该出现的内容 | 立即 CTO + 锚点, 走 §incident response (见 security-and-deidentification.md §7) |
| 我想加新功能 | 项目主理 (评估后排进 V1+ 路线) |
| 我对某次判断完全不同意 | 项目主理 + 提供具体不满意原因 |

---

> 本文档与 `dev-quickstart.md` (工程师视角) / `security-and-deidentification.md` (安全 SOP) 互补。
> 修订需 项目主理 + 锚点 review。