AI Native 研发实战：一个类 Notion 笔记的创业团队的 Harness 工程与知识复利

┌─────────────────────────────────────────────────────────┐
│ Notion 类产品核心技术栈 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Block Model │ │ CRDT │ │ Permission │ │
│ │ (块模型) │◄──►│ (协作引擎) │◄──►│ (权限系统) │ │
│ │ │ │ │ │ │ │
│ │ - 扁平化存储 │ │ - Yjs/Automerge│ │ - RBAC + │ │
│ │ - 类型注册表 │ │ - 冲突解决 │ │ 继承链 │ │
│ │ - 拖拽排序 │ │ - 离线同步 │ │ - 分享链接 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ 跨域耦合（高爆炸半径） │ │
│ │ 改块模型 → 影响协作 │ │
│ │ 改权限 → 影响同步 │ │
│ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ Hugo (Architect / TL) │
│ 不写业务代码 │
│ 职责： │
│ 1. 定义"什么叫好"（SOP、判据、验收标准） │
│ 2. 集成 Triage（分析 Agent 失败 → 沉淀知识） │
│ 3. 知识治理（成熟度评审、衰减、冲突解决） │
│ 4. Agent 名册管理（权限边界、监督者） │
└────────────┬──────────────────────────┬──────────────┘
 │ │
 ┌─────────▼─────────┐ ┌──────────▼──────────┐
 │ Domain Cell A │ │ Domain Cell B │
 │ (Alice + Charlie)│ │ (Bob + Dave) │
 │ Own: 编辑器/块模型│ │ Own: 协作/权限/同步 │
 │ + UX/前端渲染 │ │ + 后端 API/存储 │
 └─────────┬─────────┘ └──────────┬──────────┘
 │ │
 └──────────┬───────────────┘
 │
 ┌─────────▼─────────┐
 │ Agent Platform │
 │ (共享基础设施) │
 │ - Runtime 标准 │
 │ - 权限拦截器 │
 │ - 日志/可观测 │
 │ - 评估 Harness │
 └───────────────────┘

team-knowledge.git/
├── knowledge-catalog.md # Agent 查询入口
├── .knowledge-config.yaml # 团队配置
│
├── team-conventions/ # Layer 0-T（团队宪法）
│ ├── commit-style.md
│ ├── pr-review-rules.md
│ └── agent-onboarding-checklist.md
│
├── tech-wiki/ # Layer 1（跨项目技术）
│ ├── flat-vs-nested-storage.md # [decision] [proven]
│ ├── crdt-conflict-strategies.md # [process] [verified]
│ └── postgres-jsonb-indexing.md # [pitfall] [proven]
│
├── biz-wiki/ # Layer 2（Notion 业务领域）
│ ├── block-model/
│ │ ├── architecture.md # [decision] [proven]
│ │ ├── type-registry.md # [model] [proven]
│ │ └── drag-drop-sorting.md # [process] [verified]
│ ├── collaboration/
│ │ ├── yjs-integration.md # [process] [verified]
│ │ └── offline-sync.md # [guideline] [draft]
│ └── permission/
│ ├── rbac-model.md # [model] [proven]
│ └── share-link-security.md # [pitfall] [verified]
│
├── project-profiles/ # Layer 3（项目级）
│ └── notion-clone/
│ ├── tech-stack.md
│ ├── known-debt.md
│ └── agent-roster.md
│
└── contributions/ # 暂存区
 └── conflicts/

---
id: km-0042
type: decision
maturity: proven
domain: block-model
contributors: [hugo, alice]
validated_in: [notion-clone, mobile-app]
last_used: 2026-05-10
---

# Block Model Architecture Decision

## Context
Notion 类产品核心是块模型。需支持嵌套、拖拽、30+ 类型扩展、多人协作。

## Decision
采用 **扁平化存储 + parent_id 树形重建**，而非嵌套 JSON。

## Rationale
1. **嵌套 JSON 的致命缺陷**：
 - 局部更新需重写整棵树（CRDT 冲突率 12%）
 - 无法增量同步（离线场景灾难）
 - 数据库索引失效（JSONB 深层查询慢 10x）
2. **扁平化优势**：
 - 每个块独立文档（CRDT 友好，冲突率降至 0.3%）
 - 增量同步（只传变更块）
 - 树形重建在客户端完成（<5ms for 1000 blocks）

## Pitfalls（已知陷阱）
- ⚠️ **循环引用**：parent_id 必须写入层拦截（见 postgres-jsonb-indexing.md）
- ⚠️ **子树移动**：批量更新 parent_id 需事务保证一致性
- ⚠️ **孤儿块**：删除父块时需级联处理（软删除 + 定时清理）

## Evidence
- 2026-03: 嵌套方案导致协作冲突率 12% → 扁平化后降至 0.3%
- 2026-04: mobile-app 复用此决策，零适配成本
- 2026-05: Agent 生成代码时，查询此条目后一次通过率从 30% → 85%

draft（新，单来源）
 ↓ （在 1 个工作流中成功引用）
verified（单项目验证）
 ↓ （在 ≥2 个不同项目验证）
proven（成熟/可信）

衰减规则：
- proven 12 个月未使用 → verified
- verified 6 个月未使用 → draft
- draft 未使用 + Lint 标记 → 归档

INIT (Pull) → Execution (Consume) → ARCHIVE (Extract & Promote)

# .github/workflows/agent-init.yaml
name: Agent Session Init
on:
 workflow_dispatch:
 inputs:
 task_type: {type: choice, options: [feature, bugfix, refactor]}
 domain: {type: string}

jobs:
 init:
 runs-on: ubuntu-latest
 steps:
 - name: Pull knowledge repo
 run: |
 git clone ${{ secrets.KNOWLEDGE_REPO }} /tmp/knowledge
 cd /tmp/knowledge && git pull origin main

 - name: Inject block-model knowledge
 if: inputs.domain == 'block-model'
 run: |
 # 只注入 block-model 相关知识，而非全量知识库
 cat /tmp/knowledge/biz-wiki/block-model/*.md >> $GITHUB_STEP_SUMMARY
 cat /tmp/knowledge/tech-wiki/flat-vs-nested-storage.md >> $GITHUB_STEP_SUMMARY

 - name: Load Agent roster & permissions
 run: |
 cat /tmp/knowledge/project-profiles/notion-clone/agent-roster.md
 # 输出：@editor-agent 可读写 src/editor/，禁止修改权限模型

from pathlib import Path
from dataclasses import dataclass
from typing import Optional
from datetime import datetime


@dataclass
class KnowledgeEntry:
 """知识库条目"""
 id: str
 type: str # model | decision | guideline | pitfall | process
 maturity: str # draft | verified | proven
 decision: str
 pitfalls: list[str]
 last_used: datetime


class KnowledgeQuerier:
 """Agent 在决策点按需查询知识库（Notion 场景）"""

 def __init__(self, knowledge_dir: Path, budget: int = 3):
 self.knowledge_dir = knowledge_dir
 self.budget = budget
 self.queries_used = 0

 def query(self, decision_point: str, context: str) -> Optional[dict]:
 """
 Notion 场景决策点查询：
 - "新增 block 类型" → 查询 block-model/architecture.md
 → 获取：扁平化方案 + 循环引用陷阱
 - "实现拖拽排序" → 查询 block-model/drag-drop-sorting.md
 → 获取：分数索引算法 + 边界条件
 - "修改权限" → 查询 permission/rbac-model.md
 → 获取：继承链规则 + 分享链接安全红线
 """
 if self.queries_used >= self.budget:
 return None # 预算耗尽，Agent 自行判断（或请求人类介入）

 self.queries_used += 1

 # 1. 查 catalog 定位文件
 catalog = self._load_catalog()
 target_file = catalog.match(decision_point, context)

 if not target_file:
 return None

 # 2. 加载知识条目
 entry = self._load_entry(target_file)

 # 3. 返回结构化知识（非全文）
 confidence = self._calc_confidence(entry)
 
 # 低置信度强制人工确认
 if confidence < 0.5:
 return {
 "decision": entry.decision,
 "pitfalls": entry.pitfalls,
 "maturity": entry.maturity,
 "confidence": confidence,
 "action": "HUMAN_DRI_CONFIRM_REQUIRED", # Harness 拦截
 }
 
 return {
 "decision": entry.decision,
 "pitfalls": entry.pitfalls,
 "maturity": entry.maturity,
 "confidence": confidence,
 }

 def _calc_confidence(self, entry: KnowledgeEntry) -> float:
 """基于成熟度 + 最近使用计算置信度"""
 base = {"draft": 0.3, "verified": 0.6, "proven": 0.9}
 days = (datetime.now() - entry.last_used).days
 
 # 时间衰减因子
 if days < 30:
 decay = 1.0
 elif days < 90:
 decay = 0.8
 elif days < 180:
 decay = 0.6
 else:
 decay = 0.3
 
 return base[entry.maturity] * decay

# generated by hugo AI

# .github/workflows/agent-archive.yaml
name: Knowledge Archive & Promotion
on:
 pull_request:
 types: [closed]
 branches: [main]

jobs:
 archive:
 if: github.event.pull_request.merged == true
 runs-on: ubuntu-latest
 steps:
 - name: Extract knowledge from PR
 uses: ai/archiver-action@v1
 with:
 pr_number: ${{ github.event.pull_request.number }}
 knowledge_repo: ${{ secrets.KNOWLEDGE_REPO }}
 # Archiver 自动执行：
 # 1. 分析 PR diff：发现新增了"行号渲染逻辑"
 # 2. 提取 guideline："代码块行号需考虑折叠状态"
 # 3. 提取 pitfall："语法高亮 Web Worker 需防抖，否则主线程卡顿"
 # 4. 标记为 draft，写入 contributions/

 - name: Run promotion logic
 run: |
 # 自动提升判断
 # Q1: 是否 Notion 特有？ → 是，留在 biz-wiki/block-model/
 # Q2: 是否通用技术？ → Web Worker 防抖是通用 → 提升到 tech-wiki/
 python scripts/promotion_check.py

 - name: Auto-decay check
 run: |
 # 检查成熟度衰减
 python scripts/decay_check.py

# generated by hugo AI

---
# Agent 名册 - Notion Clone
updated: 2026-05-14
---

| Agent ID | 职责 | 权限边界 | 监督者 | 状态 |
|:---|:---|:---|:---|:---|
| `@editor-agent` | 块操作、类型注册、渲染 | 读写 `src/editor/`，**禁止** 修改 `src/permission/` | alice | active |
| `@collab-agent` | CRDT 同步、冲突解决 | 读写 `src/collab/`，只读 `src/permission/` | bob | active |
| `@permission-agent` | 权限校验、分享链接 | 读写 `src/permission/`，**禁止** 修改块模型 | dave | active |
| `@test-agent` | E2E 测试、回归 | 读写 `tests/`，只读业务代码 | hugo | active |
| `@archiver` | 知识提取、PR 分析 | 只读 PR，写 knowledge repo | hugo | active |

## 权限纪律
1. 越界自动拦截：`@editor-agent` 修改 `src/permission/` → CI 直接 fail
2. 梯度自治：生产环境写入需人类 DRI 审批
3. 失败可观测：Agent 错误日志聚合到 Grafana，异常模式告警

传统 Notion 团队：
 CRDT 经验 → Bob 脑中 → Bob 休假 → 团队停滞
 新人 → 重新踩循环引用的坑 → 线性增长

Harness Notion 团队：
 CRDT 经验 → crdt-conflict-strategies.md [proven]
 每次迭代 → 沉淀 pitfall/guideline → Agent 命中率↑
 新人 → 注入知识库 → 2 天独立提交 → 指数加速

速度(t) = 基础速度 × (1 + 知识命中率) ^ t
6个月后：1.78^6 ≈ 32x（理论上限）
实际：8-12x（考虑衰减、新场景、模型限制）