@bolloon/bolloon-agent
v0.1.41
Published
P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品
Readme
Bolloon - 判断力对齐协议
⚠️ 2026-06-10 重新校准:本文档下方的"核心效果"是历史叙事。Bolloon 的真正定义见 docs/真正要做的事.md。
一句话:Bolloon 是 A 和 B 对接判断力的协议层——让 A 和 B 在做重要决定前,把双方的 3 个反方观点互相看见。
核心效果(历史叙事,即将更新)
两个有判断力的人的决策，被 Bolloon 记录后，异步进行合作，由 Harness 驱动自动化执行。
Pi 生态集成
Bolloon 基于 Pi 构建，使用以下官方包：
# 必装
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 (判断力) ◀──────────────────── 自动化执行结果流程说明
- 人类判断：人类以自然语言/决策形式输入判断
- 自动记录：Pi SDK 接收决策，自动记录操作日志
- 异步归档：Session Archive 压缩存储关键决策
- 蒸馏存储：判断信号蒸馏为结构化 judgment，存入 Human Value Store
- 价值观注入：Judgment 结果通过 Value Injection 注入到 LLM prompt
- Harness 执行：Bollharness 根据归档历史驱动自动化
- 结果反馈：执行结果反馈给人类，形成闭环
四、核心功能
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 | | Bolloon.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 个条件全部满足方可跳过中间审查门：
- 改动不超过 3 个文件
- 无契约变更
- 无跨模块接缝
- 不影响用户心智或产品语义
- 不引入新的架构决策
4.7 反馈闭环
- 进度反馈：协作任务的阶段性进展
- 结果反馈：最终协作产出和发现
- 异常反馈：协作过程中出现的问题和解决情况
- 审计日志：完整的操作记录供人类追溯
五、典型使用场景
场景一：研究想法快速验证
- 人类提出研究想法："我想验证拓扑量子计算的可行性"
- 智能体接收想法，自动生成结构化协作文档
- 文档通过DID签名验证后，分发给网络中的相关智能体
- 各智能体根据文档执行验证任务，智能体间动态调整协作方法
- 验证结果汇总后反馈给人类
场景二：跨团队协作协调
- 人类提出复杂目标："需要A团队和B团队的智能体协作完成这个课题"
- 智能体自动分解任务，生成跨团队协作文档
- 各团队智能体网络接收文档，自主协调执行
- 动态调整协作方法解决冲突和依赖
- 阶段性结果反馈给人类，人类进行目标调整
场景三：智能体自组织协作
- 人类提出开放式目标："探索机器学习在组合优化中的应用"
- 智能体网络接收目标后，自主发现可协作的智能体，动态协商分工和协作方法
- 协作过程中记录操作日志供人类审计
- 最终结果和发现反馈给人类
六、生态位分离
| 角色 | 职责 | 特点 | |------|------|------| | 人类 | 目标设计者 | 提出研究想法/目标，不参与具体协作执行 | | 智能体 | 动态协作执行者 | 可在运行中调整协作方法，负责文档化和分发 |
七、技术选型
| 组件 | 技术方案 |
|------|----------|
| 核心能力 | 人类-智能体协作自动化 |
| 身份系统 | 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 的身份认证、签名验证确保分发可靠