# Bolloon - 判断力智能体协作平台

## 核心效果

> **两个有判断力的人的决策，被 Bolloon 记录后，异步进行合作，由 Harness 驱动自动化执行。**

### Pi 生态集成

Bolloon 基于 [Pi](https://github.com/earendil-works/pi) 构建，使用以下官方包：

```bash
# 必装
npx oh-pi

# MCP 桥接
pi tools add --mcp tavily

# 增强工具
pi tools add --git https://github.com/obra/superpowers

# 可选
npm install -g pi-subagents pi-goals
```

| 包名 | 用途 |
|------|------|
| `oh-pi` | Pi 的配置管理（类 oh-my-zsh） |
| `pi-mcp-adapter` | MCP 协议桥接，按需加载工具 |
| `pi-goals` | 持久化目标追踪和工作流编排 |
| `pi-subagents` | 轻量级子 Agent（基于 tmux） |

**设计哲学**：Pi 提倡最小化原语（read/write/edit/bash），没有 Plan Mode、没有权限弹窗、没有内置待办。系统开销极小，上下文空间最大化。

---

```
人类 A 的判断力                         人类 B 的判断力
      │                                       │
      ▼                                       ▼
┌─────────────────┐                   ┌─────────────────┐
│  Bolloon 记录    │                   │  Bolloon 记录    │
│  决策日志        │                   │  决策日志        │
└────────┬────────┘                   └────────┬────────┘
         │                                     │
         ▼                                     ▼
┌─────────────────────────────────────────────────────────────┐
│                    Bollharness 治理框架                       │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Session Archive (异步归档)  │  Gate State Machine     │  │
│  │ • 操作历史压缩              │  • 8-Gate 工作流       │  │
│  │ • 关键决策提取              │  • Entry/Blocker 检查  │  │
│  │ • 跨 Session 关联            │  • 快速通道           │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Skill Adapter (16 Skills)                           │  │
│  │ • lead (流程统领)  • arch (架构)  • harness-eng    │  │
│  │ • task-arch (任务分解)  • crystal-learn (学习)      │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Guard Checker (15 项自动化检查)                      │  │
│  │ • 命名规范  • 安全检查  • 质量门禁                  │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Context Router (路径上下文自动注入)                   │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │                                     │
         ▼                                     ▼
┌─────────────────────────────────────────────────────────────┐
│                 Pi Judgment System (判断系统)                 │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Judgment Distillation (判断蒸馏)                      │  │
│  │ • 隐式信号检测  • 显式反馈处理  • 轨迹学习           │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Human Value Store (人类价值观存储)                    │  │
│  │ • 规则  • 偏好  • 轨迹  • 奖励                     │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Value Injection (价值观注入)                         │  │
│  │ • 情境感知匹配  • LLM 语义评分  • 动态置信度        │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Decision Authorization (决策授权)                     │  │
│  │ • 置信度阈值  • 多级授权  • 协作决策               │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │                                     │
         ▼                                     ▼
    自动化执行 ←─────────────────────→ 自动化执行
```

### 关键词

- **异步合作**：决策被记录，不阻塞当前工作流
- **Harness 驱动**：基于 8-Gate 工作流的自动化执行框架
- **判断力保留**：人类决策作为高优先级上下文，智能体执行时不丢失意图

---

## 一、项目概述

**Bolloon** 是一个判断力智能体协作平台，核心价值在于**保留人类的判断力决策，通过 Harness 实现异步自动化合作**。

> 不是让 AI 替代人类思考，而是让人类的判断力与 AI 的执行能力解耦、异步协作。

---

## 二、核心架构

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              Bolloon 架构                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐     ┌─────────────────────────────────────────────────┐   │
│  │   人类用户   │────▶│              Pi SDK (Agent Session)              │   │
│  └─────────────┘     │  ┌─────────┐  ┌─────────┐  ┌─────────────────┐  │   │
│                      │  │ Session │  │ Persona │  │  Tool Registry  │  │   │
│                      │  └────┬────┘  └────┬────┘  └────────┬────────┘  │   │
│                      │       │            │                 │            │   │
│                      │       ▼            ▼                 ▼            │   │
│                      │  ┌─────────────────────────────────────────────┐  │   │
│                      │  │         Constraint Layer (约束层)            │  │   │
│                      │  │   • 操作日志记录   • 权限检查   • 质量门禁   │  │   │
│                      │  └──────────────────┬──────────────────────────┘  │   │
│                      └─────────────────────┼────────────────────────────┘   │
│                                            │                                  │
│                    ┌───────────────────────┼───────────────────────┐       │
│                    │                       ▼                       │       │
│                    │  ┌─────────────────────────────────────────┐  │       │
│                    │  │      Bollharness Integration           │  │       │
│                    │  │        (治理框架集成层)                  │  │       │
│                    │  ├─────────────────────────────────────────┤  │       │
│                    │  │                                         │  │       │
│                    │  │  ┌─────────────┐  ┌─────────────────┐  │  │       │
│                    │  │  │ Gate State  │  │  Skill Adapter  │  │  │       │
│                    │  │  │  Machine     │  │  (16 Skills)   │  │  │       │
│                    │  │  │  (8-Gate)   │  └─────────────────┘  │  │       │
│                    │  │  └──────┬──────┘                       │  │       │
│                    │  │         │                              │  │       │
│                    │  │  ┌──────▼──────┐  ┌─────────────────┐  │  │       │
│                    │  │  │    Guard    │  │ Context Router  │  │  │       │
│                    │  │  │   Checker   │  │  (路径上下文)   │  │  │       │
│                    │  │  │ (15 检查项)  │  └─────────────────┘  │  │       │
│                    │  │  └─────────────┘                       │  │       │
│                    │  │                                        │  │       │
│                    │  │  ┌─────────────────────────────────┐  │  │       │
│                    │  │  │     Session Archive              │  │  │       │
│                    │  │  │  (操作历史自动归档压缩)          │  │  │       │
│                    │  │  └─────────────────────────────────┘  │  │       │
│                    │  └─────────────────────────────────────────┘  │       │
│                    └───────────────────────────────────────────────┘       │
│                    ┌───────────────────────────────────────────────┐       │
│                    │               Pi Judgment System               │       │
│                    │  ┌───────────────┐  ┌─────────────────────┐  │       │
│                    │  │   Distillation │  │   Value Injection   │  │       │
│                    │  │  (判断蒸馏)    │  │  (情境感知注入)     │  │       │
│                    │  └───────────────┘  └─────────────────────┘  │       │
│                    │  ┌───────────────┐  ┌─────────────────────┐  │       │
│                    │  │ Human Value   │  │  Decision Auth     │  │       │
│                    │  │   Store       │  │  (多级授权)        │  │       │
│                    │  └───────────────┘  └─────────────────────┘  │       │
│                    └───────────────────────────────────────────────┘       │
│                                          │                                    │
│                                          ▼                                    │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                        外部服务层                                      │   │
│  │   • P2P 网络 (Hyperswarm/DIAP)   • LLM (Minimax)   • IPFS        │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
```

## 三、核心流程

```
人类 A (判断力)
    │
    ▼ 提出决策
Pi SDK Session ──────────────────▶ Bollharness 治理框架
    │                                    │
    │                                    ├── Session Archive (归档)
    │                                    ├── Gate State Machine (工作流)
    │                                    ├── Skill Adapter (执行)
    │                                    ├── Guard Checker (检查)
    │                                    └── Context Router (注入)
    │                                          │
    │                                    Pi Judgment System
    │                                    ├── Distillation (蒸馏)
    │                                    ├── Value Store (存储)
    │                                    ├── Value Injection (注入)
    │                                    └── Decision Auth (授权)
    │                                          │
    ▼                                          ▼
人类 B (判断力) ◀──────────────────── 自动化执行结果
```

### 流程说明

1. **人类判断**：人类以自然语言/决策形式输入判断
2. **自动记录**：Pi SDK 接收决策，自动记录操作日志
3. **异步归档**：Session Archive 压缩存储关键决策
4. **蒸馏存储**：判断信号蒸馏为结构化 judgment，存入 Human Value Store
5. **价值观注入**：Judgment 结果通过 Value Injection 注入到 LLM prompt
6. **Harness 执行**：Bollharness 根据归档历史驱动自动化
7. **结果反馈**：执行结果反馈给人类，形成闭环

---

## 四、核心功能

### 4.1 Pi SDK (Agent Session)

- **会话管理**：管理人类与智能体的对话 Session
- **Persona 管理**：智能体的人格特征配置
- **工具注册**：动态注册和执行各类工具
- **约束层**：自动记录操作日志、权限检查、质量门禁
- **Harness 集成**：与 Bollharness 治理框架无缝集成
- **Judgment 集成**：支持判断蒸馏、价值观注入、决策授权流程

### 4.2 Bollharness 治理框架

#### 4.2.1 Gate State Machine (8-Gate 工作流)

```
Gate 0: Problem Lock (问题锁定) → Gate 1: Architecture Design (架构设计)
Gate 2: Review (审查) → Gate 3: Plan Freeze (计划冻结)
Gate 4: Review (审查) → Gate 5: Task Architecture (任务架构)
Gate 6: Review (审查) → Gate 7: Execution (执行)
Gate 8: Test & Integration (测试集成) → 完成
```

- **Entry 检查**：每个 Gate 有进入条件
- **Blocker 追踪**：记录未完成的依赖项
- **快速通道**：简单变更可跳过中间审查

#### 4.2.2 Skill Adapter (16 Skills)

| Skill | 职责 | 触发 Gate |
|-------|------|-----------|
| lead | 开发流程统领 | G0, G4, G8 |
| arch | 架构设计专才 | G1, G2 |
| task-arch | 任务分解 | G5 |
| harness-eng | 执行编排 | G3, G7 |
| harness-eng-test | 测试工程 | G8 |
| crystal-learn | 结晶学习 | 任意 |
| guardian-fixer | Issue 自动修复 | 任意 |
| plan-lock | 计划锁定 | G3-G4 |
| skill-discovery | Skill 发现 | 任意 |

#### 4.2.3 Guard Checker (15 项自动化检查)

- 文件命名规范检查
- 代码重复率检查
- 安全敏感信息检查
- 文档完整性检查
- 测试覆盖检查
- 依赖版本检查
- 等等...

#### 4.2.4 Context Router (路径上下文自动注入)

根据编辑的文件路径，自动注入相关上下文：

| 文件路径 | 注入上下文 |
|----------|-----------|
| src/agents/ | truth-source-hierarchy, protocol-consumers |
| src/documents/ | truth-source-hierarchy, db-shared-structures |
| src/network/ | truth-source-hierarchy, protocol-consumers |
| src/constraints/ | truth-source-hierarchy, fixed-three-layers |
| docs/ | truth-source-hierarchy, two-language |
| CLAUDE.md | truth-source-hierarchy, bridge-constitution |

#### 4.2.5 Session Archive (操作历史归档)

- **自动归档**：Pi SDK 每次工具执行自动记录
- **压缩存储**：去除重复操作，保留关键决策
- **上下文获取**：Skill 可访问历史作为决策依据
- **Gate 关联**：每次归档关联当前 Gate

### 4.3 想法接收与文档化

- **自然语言输入**：人类以自然语言提出研究想法或目标
- **自动文档化**：智能体将想法自动转化为结构化协作文档
- **文档结构**：包含研究目标、关键假设、验证步骤、所需资源、潜在风险

### 4.4 智能体自组织

- **服务发现**：智能体可发现网络中其他智能体的能力和状态
- **动态协商**：智能体之间可协商任务分工、优先级、资源分配
- **策略调整**：根据执行反馈，智能体自主调整协作策略
- **冲突解决**：智能体间出现冲突时，自动协商解决方案

### 4.5 文档分发机制

- **DID签名验证**：文档发送前使用发送方DID签名，确保来源可信
- **分发策略**：
  - 广播分发：文档分发到所有可达智能体
  - 定向分发：根据文档内容智能匹配目标智能体
  - 分层分发：先分发给骨干智能体，再逐层传递

### 4.6 Pi Judgment System（判断系统）

人类判断力的捕获、蒸馏与注入，使 LLM 在决策时理解"为什么会这样决定"而非仅知道"应该怎么做"。

#### 4.6.1 判断蒸馏（Judgment Distillation）

将人类决策信号转化为结构化判断：

| 触发类型 | 说明 |
|---------|------|
| `explicit` | 人类显式反馈（纠正、批准、拒绝） |
| `implicit` | 隐式信号检测（犹豫、跳过、重复修改） |
| `trajectory` | 轨迹学习（行动序列 + 结果 + 人工批准） |

蒸馏产物为四种判断类型：

| 类型 | 用途 |
|------|------|
| `rule` | 硬性规则（安全底线、不可妥协） |
| `preference` | 偏好（权衡时的倾向） |
| `trajectory` | 轨迹（成功路径的模式） |
| `reward` | 奖励信号（结果评价） |

#### 4.6.2 人类价值观存储（Human Value Store）

分层存储，按访问频率和用途分流：

| 存储位置 | 内容 | 用途 |
|----------|------|------|
| `context-fragments/*.md` frontmatter | 高频规则 | Context Router 自动注入 |
| `~/.bolloon/judgments/*.yaml` | 长期偏好、轨迹 | 语义检索、蒸馏来源 |
| `~/.bolloon/human-values/judgments.json` | 结构化判断 | LLM 注入、语义匹配 |

关键词 + LLM 语义双重匹配，支持按领域、决策类型、置信度过滤。

#### 4.6.3 价值观注入（Value Injection）

两种注入模式，适用于不同场景：

**关键词匹配**（`generateValueInjection`）
- 基于 `getRelevantValues()` 的关键词相似度
- 适合判断数据不足 3 条时的 fallback

**情境感知**（`generateSituationalValueInjection`）
- LLM 语义评分每条 judgment 的情境相关性（0-1）
- `dynamicConfidence = situationalScore × historicalConfidence`
- 注入内容包括：匹配的判断列表、相关价值观排序、历史决策参考
- 需至少 3 条 judgment 才能启用 LLM 语义匹配

**Gate 情境注入**（`GateStateMachine`）
- 每次 gate transition 时生成
- 基于 `GATE_CONFIGS[gate].situation` 扩展用户输入
- 最多维护 10 条对话历史用于情境丰富化
- 产出存入 `state.valueInjection`，通过 `getGatePack().value_injection` 暴露

#### 4.6.4 决策授权（Decision Authorization）

置信度低于阈值时的决策路由：

| 等级 | 条件 | 行为 |
|------|------|------|
| `autonomous` | 置信度 > 阈值 | 自主执行 |
| `consult_internal` | 置信度中等 | 咨询内部 agent（colony/subagent） |
| `consult_external` | 置信度较低 | 咨询外部 P2P agent |
| `require_human` | 置信度很低 | 人工确认 |

决策请求包含：描述、上下文、置信度、阈值、授权等级、目标列表。

#### 4.6.5 快速通道检查

变更分类为 `implementation` 时，检查 5 个条件全部满足方可跳过中间审查门：

1. 改动不超过 3 个文件
2. 无契约变更
3. 无跨模块接缝
4. 不影响用户心智或产品语义
5. 不引入新的架构决策

### 4.7 反馈闭环

- **进度反馈**：协作任务的阶段性进展
- **结果反馈**：最终协作产出和发现
- **异常反馈**：协作过程中出现的问题和解决情况
- **审计日志**：完整的操作记录供人类追溯

## 五、典型使用场景

### 场景一：研究想法快速验证

1. 人类提出研究想法："我想验证拓扑量子计算的可行性"
2. 智能体接收想法，自动生成结构化协作文档
3. 文档通过DID签名验证后，分发给网络中的相关智能体
4. 各智能体根据文档执行验证任务，智能体间动态调整协作方法
5. 验证结果汇总后反馈给人类

### 场景二：跨团队协作协调

1. 人类提出复杂目标："需要A团队和B团队的智能体协作完成这个课题"
2. 智能体自动分解任务，生成跨团队协作文档
3. 各团队智能体网络接收文档，自主协调执行
4. 动态调整协作方法解决冲突和依赖
5. 阶段性结果反馈给人类，人类进行目标调整

### 场景三：智能体自组织协作

1. 人类提出开放式目标："探索机器学习在组合优化中的应用"
2. 智能体网络接收目标后，自主发现可协作的智能体，动态协商分工和协作方法
3. 协作过程中记录操作日志供人类审计
4. 最终结果和发现反馈给人类

## 六、生态位分离

| 角色 | 职责 | 特点 |
|------|------|------|
| **人类** | 目标设计者 | 提出研究想法/目标，不参与具体协作执行 |
| **智能体** | 动态协作执行者 | 可在运行中调整协作方法，负责文档化和分发 |

## 七、技术选型

| 组件 | 技术方案 |
|------|----------|
| 核心能力 | 人类-智能体协作自动化 |
| 身份系统 | DID（去中心化身份） |
| 通信协议 | DIaoP（去中心化身份与通信协议） |
| 开发语言 | TypeScript |
| 运行环境 | Node.js |
| 治理框架 | Bollharness (8-Gate 工作流) |
| Session 归档 | 自动压缩归档 |
| 判断存储 | 混合模式（YAML + JSON） |
| 价值观注入 | LLM 语义匹配 + 关键词匹配双模式 |
| 存储路径 | `~/.bolloon/judgments/*.yaml` / `~/.bolloon/human-values/judgments.json` |

## 八、信任机制

- **DID身份认证**：确保参与协作的智能体身份可信
- **签名验证**：协作过程中的关键操作需签名确认
- **操作审计**：所有协作操作记录在链，供人类追溯
- **Gate 审查**：关键决策需通过 Gate 审查

## 九、效果量化指标

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 想法转化成功率 | ≥ 95% | 人类想法成功转化为结构化文档的比例 |
| 文档分发到达率 | ≥ 99% | 文档成功到达目标智能体的比例 |
| 智能体自组织率 | ≥ 90% | 协作调整中无需人类干预的比例 |
| 人类反馈满意度 | ≥ 85% | 人类对协作结果的满意程度 |
| 信任建立时间 | ≤ 30秒 | 新智能体加入网络建立信任的耗时 |

## 十、核心效果定义

**产品核心效果：判断力智能体协作平台**

> 两个有判断力的人的决策，被 Bolloon 记录后，异步进行合作，由 Harness 驱动自动化执行。人类的判断力决策作为高优先级上下文，智能体执行时不丢失意图。

### 关键词

- **异步合作**：决策被记录，不阻塞当前工作流
- **Harness 驱动**：基于 8-Gate 工作流的自动化执行框架
- **判断力保留**：人类决策作为高优先级上下文，智能体执行时不丢失意图
- **信任机制**：基于 DID 的身份认证、签名验证确保分发可靠
