04 — 可复用 Harness 框架 (Cross-Vertical)

A 股是第一个垂直，但框架要能复用到其他行业

目标 (Goal)

把 03 里的 5 层架构抽象成 vertical-agnostic 的脚手架，A 股是第一个 instance；后续可以是医疗、法律、能源、跨境贸易研究等任何"信息密集型 + 需要可信引用"的领域。

为什么要做 Harness

如果 A 股做得好但不能复用，下一个垂直要从零再来一遍：

• 数据接入再重写
• Skill 框架再重写
• Citation 协议再重写
• 文档再重写

→ 时间和心智成本都大。所以必须第一天就把可复用的边界划清楚。

关键决策点 (Open Questions)

Q1. 抽象什么、不抽象什么

应该抽象 (vertical-agnostic)：

• 5 层架构骨架 (L1-L5)
• Citation / Provenance 协议
• Skill / Tool 注册机制
• Data Access 接口规范（不是具体 schema）
• 评估框架 (eval harness)
• 可观测性 (logging, tracing, replay)
• 文档脚手架

不应该抽象 (vertical-specific)：

• 具体的 schema (财报、研报)
• 具体的数据源 adapter
• 具体的 domain prompts
• 具体的 metric 计算

Q2. 抽象的形态

• A) Library / SDK：用户写代码继承基类、注册 adapter
• B) Framework / Convention：目录结构 + 配置文件，"看到 verticals/astock/ 就知道是 A 股"
• C) Mono-repo with plugins：核心 + plugins，A 股是一个 plugin

→ 建议 B + C 混合：约定式目录 + plugin 注册。例：

harness/
├── core/                    # vertical-agnostic
│   ├── orchestrator/
│   ├── citation/
│   ├── skill_registry/
│   └── eval/
├── verticals/
│   ├── astock/              # A 股 instance
│   │   ├── data_adapters/
│   │   ├── skills/
│   │   └── prompts/
│   └── (future) healthcare/
└── docs/

Q3. 验证可复用性的"第二个垂直"

只做 A 股的话，抽象很容易过拟合。建议：

• 至少在脑子里走查一个第二垂直（比如"美股研究"或"加密货币研究"）
• 看 5 层架构是否需要改动
• 如果改动很大 → 抽象不到位

→ 这步可以推迟到 A 股 MVP 后做，但架构决策时必须考虑。

Q4. Open source vs Closed source

影响很多决策：

• License 选择
• 数据源 adapter 的 commit 策略 (Tushare token 不能写死)
• 文档的公开程度

→ 需要用户决定。

Q5. 命名

"Harness" 是个工程术语，外部不一定理解。是否需要起一个产品名？

与其他层的关系

• 04 是 元层 (meta-layer)：定义 01/02/03 怎么组织
• 不直接产生 A 股的功能；产生的是"让 A 股功能容易写、容易换"的脚手架

风险 (Risks)

1. 过早抽象 (Premature Abstraction) — 只见过 A 股一个例子就抽象，往往抽错
2. 抽象税 (Abstraction Tax) — 每个新功能都要先想"放哪一层"，拖慢一期速度
3. Plugin API 漂移 — 核心 API 一变，所有 vertical 都要改

→ 缓解策略：一期 A 股先直接写，不强求 harness 抽象；等到 A 股 MVP 跑通、第二垂直要开始时再重构抽象出 harness。这是 "Rule of Three" 的应用。

下一步

1. 用户决定 Q4 (open vs closed source)
2. 用户决定一期是 直接写 A 股 还是 先建 harness 再写 A 股
   • 我的强烈建议：直接写 A 股，harness 后置
3. 在 03 Agent 框架的 design 里，预留 harness 抽象点（命名约定、目录结构）