ai-berkshire (Agent Skills)

# AI Berkshire Codex Guide

This repository contains investment research workflows, reports, and shared
validation tools. Keep compatibility with both Claude Code and Codex users.

## Project Layout

- `skills/*.md`: Claude Code slash-command source files.
- `codex-skills/*/SKILL.md`: Codex skill packages. Most are generated from
  `skills/*.md`; Codex-only hand-written packages are allowed when clearly
  marked and no same-named `skills/*.md` source exists.
- `codex-prompts/*.md`: generated Codex custom prompts for slash-command
  style entry points. These are a compatibility layer; skills remain preferred.
- `tools/*.py`: shared financial validation and data tools used by both systems.
- `reports/`: research outputs. Do not rewrite unrelated reports while changing
  tooling or skills.
- `scripts/sync-codex-skills.py`: regenerates Codex skills from `skills/*.md`.
- `scripts/install-codex-skills.sh` / `scripts/install-codex-skills.bat`:
  installs Codex skills locally.
- `scripts/install-codex-prompts.sh` / `scripts/install-codex-prompts.bat`:
  installs generated Codex slash prompts locally.
- `scripts/install-claude-commands.sh` / `scripts/install-claude-commands.bat`:
  installs Claude Code commands locally.

## Compatibility Rules

- Treat `skills/*.md` as the canonical workflow source.
- After changing any file in `skills/`, run:
  `python3 scripts/sync-codex-skills.py`
- If slash prompt compatibility is needed, also run:
  `python3 scripts/sync-codex-prompts.py`
- Do not manually edit generated `codex-skills/*/SKILL.md` unless also updating
  the corresponding source in `skills/`.
- For Codex-only hand-written packages under `codex-skills/`, keep them clearly
  marked as Codex-only and do not create a same-named `skills/*.md` file unless
  intentionally adopting the workflow for Claude Code too.
- Keep tool paths compatible with the documented checkout path:
  `~/ai-berkshire/tools/...`
- Keep `CLAUDE.md` for Claude Code behavior and this `AGENTS.md` for Codex
  behavior.

## Research Quality Rules

- Before starting any research, run the `date` command to confirm today's
  date. Treat that date as the baseline for "latest" data (prices, market cap,
  most recent filings), and state the data cutoff date in the report header.
  Never assume the current date from training data.
- Financial data must come from at least two independent sources when the skill
  requires verification.
- Use exact arithmetic tools for market cap, valuation, cross-source checks, and
  scenario analysis:
  `python3 tools/financial_rigor.py ...`
- Use report audit tooling before treating generated research as publishable:
  `python3 tools/report_audit.py ...`
- Clearly label low-confidence conclusions, incomplete data, and source gaps.
- This project is for learning and research, not investment advice.

## Editing Rules

- Preserve existing report files unless the task specifically asks to change
  them.
- Keep changes scoped to the requested skill, tool, script, or documentation.
- Before finishing a skill/tool change, run the relevant syntax or generation
  check. For compatibility changes, run:
  `python3 scripts/sync-codex-skills.py`
- To verify generated Codex artifacts are current without rewriting files, run:
  `python3 scripts/sync-codex-skills.py --check`
  and, when slash prompts are relevant:
  `python3 scripts/sync-codex-prompts.py --check`

# AI Berkshire — 项目指令

## 项目概述

基于 Claude Code 的价值投资研究 Skill 合集。四大师框架：巴菲特、芒格、段永平、李录。
GitHub: xbtlin/ai-berkshire

## 项目结构

```
skills/          — 投研 Skill 定义（.md），复制到 ~/.claude/commands/ 使用
tools/           — 辅助工具（financial_rigor.py 精确计算、twstock_data.py 台股FinMind取数）
reports/         — 投资研究报告输出
assets/          — 图片等静态资源
```

## 报告目录结构

所有报告按**公司名**建文件夹，公司相关的所有报告放在对应文件夹内：

```
reports/
├── AI产业研究/              — AI产业链全景研究（置顶）
│   ├── AI五层蛋糕-产业全景研究-20260605.md
│   └── AI五层蛋糕-公众号-20260605.md
├── 腾讯/                    — 腾讯所有研究报告
│   ├── 腾讯-research-20260408.md
│   ├── 腾讯-earnings-2025Q4.md
│   ├── 腾讯-management-20260409.md
│   └── 腾讯-thesis.md
├── 拼多多/                  — 拼多多所有研究报告
├── 泡泡玛特/                — 泡泡玛特所有研究报告
├── 核电-industry-20260409.md — 行业报告放根目录
├── AI算力-funnel-20260509.md  — 漏斗筛选报告放根目录
├── AI-轮动判断-20260509.md    — 主题级综合判断报告放根目录
├── portfolio-latest.md       — 组合报告放根目录
└── 多公司对比-checklist-20260408.md — 多公司报告放根目录
```

## 报告命名规范

| Skill | 文件命名格式 | 示例 |
|------|---------|------|
| /investment-team | `{公司名}/` 目录内含4个视角+最终报告 | `reports/拼多多/最终报告.md` |
| /investment-research | `{公司名}-research-{YYYYMMDD}.md` | `reports/腾讯/腾讯-research-20260408.md` |
| /investment-checklist | `{公司名}-checklist-{YYYYMMDD}.md` | `reports/腾讯/腾讯-checklist-20260408.md` |
| /industry-research | `{行业名}-industry-{YYYYMMDD}.md`（根目录） | `reports/核电-industry-20260409.md` |
| /industry-funnel | `{行业名}-funnel-{YYYYMMDD}.md`（根目录） | `reports/AI算力-funnel-20260509.md` |
| /private-company-research | `{公司名}-private-{YYYYMMDD}.md` | `reports/字节跳动/字节跳动-private-20260408.md` |
| /earnings-review | `{公司名}-earnings-{期间}.md` | `reports/腾讯/腾讯-earnings-2025Q4.md` |
| /earnings-team | `{公司名}/` 目录内含4个大师视角+研究底稿+公众号文章+读者评审 | `reports/腾讯/腾讯-earnings-2025Q4.md`（公众号定稿） |
| /thesis-tracker | `{公司名}-thesis.md`（长期维护） | `reports/腾讯/腾讯-thesis.md` |
| /portfolio-review | `portfolio-latest.md`（根目录，持续更新） | `reports/portfolio-latest.md` |
| /management-deep-dive | `{公司名}-management-{YYYYMMDD}.md` | `reports/腾讯/腾讯-management-20260409.md` |

## /investment-team 文件结构

```
reports/{公司名}/
├── README.md                         — 研究框架概览+核心结论
├── 01-商业模式分析-段永平视角.md
├── 02-财务估值分析-巴菲特视角.md
├── 03-行业竞争分析-芒格视角.md
├── 04-风险管理层评估-李录视角.md
└── 最终报告.md                       — Team Lead 综合报告
```

## 投研分析核心原则（最高优先级）

- **客观、客观、客观**——所有投研分析必须基于事实和数据，严禁主观臆断
- 严格区分"事实"与"观点"：事实用数据支撑，观点必须明确标注为"观点"或"推测"
- **不预设立场**：不预设看多或看空，先摆数据、再推逻辑、最后得结论。结论必须从数据中自然推出
- 禁止使用"我认为"、"我觉得"、"显然"等主观表述，改用"数据显示"、"证据表明"、"根据XX来源"
- **呈现正反两面**：每个核心判断都必须附带反面论据（"但另一方面..."），让读者自己权衡
- 对不确定的事情诚实说"不确定"或"数据不足"，不要用推测填充确定性
- 所有skill（investment-team、investment-research、earnings-review等）在执行时都必须遵守以上原则

## 报告语言与风格

- 所有报告使用**中文**
- 风格：直接、犀利、不说废话
- 数据必须标注来源，关键数据至少2个来源交叉验证
- 估计值必须注明"估计"
- 评分使用★符号（★1-5），不含半星
- 穿插巴菲特/芒格/段永平/李录的语录点评

## GitHub 操作

- 本地克隆路径：`~/ai-berkshire/`
- 远程仓库：`https://github.com/xbtlin/ai-berkshire.git`
- 推送前先 `git pull --rebase origin main`（远程经常有新提交）
- commit message 用中文，描述清楚改了什么
- 不要推送中间过程文件（如 data_collection.md），只推最终报告

## 常用命令

```bash
# 推送报告到GitHub
cd ~/ai-berkshire
git add reports/xxx.md
git commit -m "添加xxx报告"
git pull --rebase origin main
git push origin main
```

## 注意事项

- 市值必须手算校验：股价 × 总股本，与报告市值对比
- 货币单位要明确（港币/人民币/美元/新台币），防止混淆
- PE/ROE等指标用 tools/financial_rigor.py 精确计算
- 台股数据用 tools/twstock_data.py（FinMind）获取，并按 skills/financial-data.md 台股章节交叉验证
- 报告写完后主动询问是否推送到GitHub

# 财报精读：一手资料深度解读

对 $ARGUMENTS 进行财报精读分析。

**支持输入格式**：`公司名 季度`，例如：`腾讯 2025Q4`、`PDD 2025年报`、`美团 最新`（默认读取最近一期）

> "我从不看卖方研报，只读原始财报。" —— 李录
>
> "我每天读500页。知识就是这样积累的，像复利一样。" —— 巴菲特

## 设计理念

大多数AI投研工具依赖二手信息（新闻、研报摘要、数据网站）。但巴菲特和李录的核心能力是**读一手资料**——年报、季报、电话会纪要。

二手信息的问题：
- 被筛选过——分析师选择性呈现对其观点有利的数据
- 有时滞——等别人消化完，alpha已经没了
- 缺乏语境——"收入增长15%"脱离了管理层对增长质量的讨论

本Skill直接解读一手资料，关注巴菲特和李录真正会看的内容。

## 执行流程

### 前置步骤：资料可得性评级

| 等级 | 特征 | 影响 |
|------|------|------|
| A级 | 获取到完整原文（10-K/年报/电话会纪要） | 正常执行全部步骤 |
| B级 | 仅获取到部分原文或第三方汇总 | 标注"非原始来源"，降低附注分析权重 |
| C级 | 仅有新闻报道和数据网站摘要 | 聚焦核心财务数据变化，跳过附注挖掘，标注"一手资料不足" |

### 第一步：获取一手资料

使用 Task 工具启动多个后台 Agent **并行**获取以下原始材料：

1. **财报原文**：从公司IR页面、SEC EDGAR（美股10-K/10-Q）、港交所披露易（港股）、巨潮资讯网（A股）获取
2. **业绩电话会纪要/录音**：从 Seeking Alpha、公司IR页面、雪球等获取
3. **管理层致股东信**（如有年报）：完整阅读
4. **投资者日/分析师日材料**（如近期有）

如果无法获取完整原文，按 `skills/financial-data.md` 规范使用标准数据源拼凑（美股：macrotrends+stockanalysis；港股：aastocks+macrotrends；A股：东方财富+巨潮资讯；台股：FinMind `tools/twstock_data.py`+Goodinfo），但必须标注"非原始财报，来自第三方汇总"，且关键数据两源误差>1%须标记。

### 第二步：核心财务数据提取与验证

#### 2.1 收入与利润表

| 指标 | 本期 | 上期 | YoY变化 | 管理层指引 | 是否达标 |
|------|------|------|---------|-----------|---------|

必须覆盖：
- 总收入及分业务/分地区收入拆解
- 毛利润、毛利率变化
- 经营利润、经营利润率变化（区分GAAP和Non-GAAP）
- 净利润（注意非经常性损益的影响）
- EPS（基本 vs 稀释）

#### 2.2 现金流表（巴菲特最看重）

| 指标 | 本期 | 上期 | 变化 | 关注点 |
|------|------|------|------|--------|

必须覆盖：
- 经营性现金流 vs 净利润的比率（>100%为佳，<80%需警惕）
- 资本开支及其构成（维护性 vs 扩张性）
- 自由现金流 = 经营现金流 - 资本开支
- 回购金额、分红金额
- 现金及等价物期末余额

#### 2.3 资产负债表健康度

必须覆盖：
- 现金+短期投资 vs 有息负债
- 净现金/净负债变化趋势
- 应收账款周转天数变化（是否在放松信用条件冲收入？）
- 存货周转天数变化（是否在积压？）
- 商誉及无形资产占比（是否有减值风险？）

**数据验证**：使用 `tools/financial_rigor.py` 对关键数据进行校验：

```bash
# 收入和净利润交叉验证（至少2个来源）
python3 tools/financial_rigor.py cross-validate \
  --metric "revenue" --values 108.3e9 107.9e9 --sources "公司财报" "Yahoo Finance"

# 市值校验
python3 tools/financial_rigor.py verify-market-cap \
  --price 101 --shares 1.488e9 --reported 1.44e11 --currency USD

# 估值指标验算
python3 tools/financial_rigor.py verify-valuation \
  --price 101 --eps 9.6 --bvps 26.5 --fcf-per-share 10.2
```

### 第三步：管理层讨论精读（MD&A）

这是巴菲特和李录花最多时间的部分。不是看数字，是**听管理层怎么说**。

#### 3.1 管理层语气分析

逐段阅读管理层讨论/电话会发言，标注以下信号：

| 信号类型 | 具体表现 | 示例 |
|---------|---------|------|
| 🟢 **坦诚信号** | 主动承认问题、给出具体原因 | "本季度利润率下降主要因为我们在X领域的投入超出预期" |
| 🟢 **清晰信号** | 战略表述具体、有量化目标 | "我们计划在未来12个月将X业务的市场份额从15%提升到20%" |
| 🔴 **模糊信号** | 大量使用"我们相信"、"长期来看"等没有实质内容的话 | "我们对未来充满信心" |
| 🔴 **转移信号** | 回避直接问题、用其他话题带过 | 被问利润率时转谈收入增速 |
| 🔴 **归因外部化** | 把问题全归咎于宏观/行业/竞争对手 | "由于宏观环境影响..." |

#### 3.2 承诺追踪

从上一期财报/电话会中提取管理层的具体承诺，与本期实际情况对比：

| 上期承诺 | 本期兑现情况 | 评价 |
|---------|------------|------|
| "下半年利润率将恢复到X%" | 实际Y% | ✅达标 / ❌未达标 / ⚠️部分达标 |

**段永平**："看一个管理层靠不靠谱，最简单的方法就是看他以前说的话做到了没有。"

#### 3.3 关键问题识别

从电话会Q&A环节提取分析师最尖锐的问题，以及管理层的回答质量：

| 分析师问题 | 管理层回答 | 回答质量(1-5) | 是否回避 |
|-----------|-----------|:------------:|:-------:|

### 第四步：附注与隐藏信息挖掘

财报附注里藏着管理层不想让你轻易看到的信息：

#### 4.1 必查附注项

- [ ] **关联交易**：与大股东/关联方的交易条款是否公允？
- [ ] **股权激励**：期权/RSU的稀释效应有多大？行权价是多少？
- [ ] **或有负债**：诉讼、担保、承诺等表外风险
- [ ] **会计政策变更**：是否改变了收入确认方式、折旧年限等？
- [ ] **分部信息**：不同业务的利润率差异，是否有"好业务补贴坏业务"
- [ ] **客户/供应商集中度**：前五大客户/供应商占比

#### 4.2 异常信号检测

- [ ] 应收账款增速 > 收入增速（可能在塞渠道）
- [ ] 存货增速 > 收入增速（可能在积压）
- [ ] 经营现金流 < 净利润且差距扩大（利润质量存疑）
- [ ] 资本化开支突然增加（可能在美化利润）
- [ ] 非经常性收益占比突然上升

### 第五步：与历史数据对比

#### 5.1 趋势分析

将本期关键指标放入至少4个季度（或3年年报）的时间序列中：

| 指标 | Q-4 | Q-3 | Q-2 | Q-1 | 本期 | 趋势判断 |
|------|-----|-----|-----|-----|------|---------|

重点关注：
- 利润率是在改善还是恶化？
- 收入增速是在加速还是减速？
- 现金流质量是在提升还是下降？
- 资本开支强度是在增加还是减少？

#### 5.2 与管理层指引对比

| 指标 | 管理层此前指引 | 实际结果 | 偏差 | 解读 |
|------|--------------|---------|------|------|

### 第六步：输出精读报告

#### 报告结构

```
一、核心数据速览（一页表格）
二、本期最重要的3个变化（不超过500字）
三、管理层语气与承诺追踪
四、附注中的隐藏信息
五、关键问题（电话会Q&A精选）
六、与投资论文的关系（如有持仓）
七、结论：这份财报改变了什么？
```

#### 结论必须明确回答

1. **这份财报是超预期、符合预期、还是低于预期？**（不能说"基本符合"然后列一堆两面话）
2. **对投资论文的影响**：强化 / 无影响 / 削弱 / 破裂
3. **需要关注的下一个催化剂是什么？**
4. **如果你已持有，该加仓/持有/减仓？**

### 第七步：保存报告

将报告写入 `reports/{公司名}-earnings-{期间}.md`，例如 `reports/腾讯-earnings-2025Q4.md`

### 第八步：数据抽检（准出流程）

报告写入后，执行数据抽检，通过方可发布：

```bash
# Step 1 — 提取抽检清单
python3 tools/report_audit.py extract \
  --report reports/{公司名}-earnings-{期间}.md

# Step 2 — 对清单每项从可靠信源取数（参见 skills/financial-data.md）

# Step 3 — 输出准出/打回判决
python3 tools/report_audit.py verdict \
  --results '<填好的JSON>' \
  --report {报告文件名}
```

**【准出】** 全部通过 → 发布；**【打回】** 有不通过 → 修正后重审。

## 关键原则

- **读原文，不读摘要**：尽一切可能获取一手资料
- **看变化，不看绝对值**：趋势比数字本身重要
- **听语气，不只听内容**：管理层怎么说和说了什么一样重要
- **查附注，不只看正文**：魔鬼藏在细节里
- **给结论，不做汇总**：精读的目的是形成判断，不是复述财报