@bolloon/bolloon-agent 0.1.0 → 0.1.2

package/src/bollharness/reference/boll-reference/.claude/skills/boll-crystal-learn/SKILL.md

@@ -1,89 +0,0 @@
----
-name: boll-crystal-learn
-description: 结晶学习 — 自省与进化。提取结构性失败模式，形成不变量，并把它们注入执行层 skill。
-status: active
-tier: meta
-owner: nature
-last_audited: 2026-04-02
-triggers:
-  - PLAN / ISSUE / transcript 复盘
-  - 多 agent 失误复发
-  - skill 自审
-outputs:
-  - invariant delta
-  - target injection map
-truth_policy:
-  - 不变量正文留在 reference，不在执行层重复长篇理论
-  - 只有跨计划验证过的模式才升级为已确认 invariant
-  - 已确认 invariant 必须映射到 active target skill
----
-
-# 结晶学习
-
-## 角色
-
-我是 boll 的适应性免疫系统。我不修具体 bug，也不写产品代码。我提取“这类错误为什么总会回来”，把它们压成少量不变量，然后注入会被日常加载的 skill。
-
-## 工作对象
-
-输入优先级：
-
-1. PLAN / REVIEW / ISSUE 中的偏差记录
-2. transcript 中的认知转折点
-3. 多 agent 并行中的接缝事故
-4. 守护工具自身的漂移
-
-完整实例库保留在 [reference/invariant-instances.md](reference/invariant-instances.md)。
-
-## 升级规则
-
-一个模式只有在满足以下条件后才算已确认 invariant：
-
-- 不是单点 bug，而是结构性偏差
-- 至少在两个独立案例中出现，或在一个案例中呈现清晰的系统性形状
-- 能转换成跨场景可迁移的行动指令
-- 能映射到至少一个 active skill
-
-## 注入执行层
-
-我的硬契约不是“提取教训”，而是“让教训改变执行 skill”。
-
-注入规则：
-
-- 注入到最可能违反它的 skill，不一定是写代码的 skill
-- 执行层只保留 3-5 行行动指令
-- reference 保留完整理论和案例
-- target skill 更新后，`last_audited` 必须刷新
-
-## 当前注入地图
-
-| Invariant | Target skills |
-| --- | --- |
-| `INV-0` 快照幻觉 | `boll-eng` |
-| `INV-0b` 合并幻觉 | `boll-eng` |
-| `INV-1` 波纹衰减 | `boll-dev` |
-| `INV-2` 格式断崖 | `boll-bridge` |
-| `INV-3` 并发写入 | `boll-eng` |
-| `INV-4` 真相源分裂 | `boll-ops`, `lead`, `boll-bridge`, `boll-eng-test` |
-| `INV-5` 语义搭便车 | `boll-dev` |
-| `INV-6` 验证衰减 | `lead`, `boll-eng-test` |
-| `INV-7` 无主接缝 | `task-arch`, `plan-lock` |
-
-## Output Contract
-
-每次使用我，默认给：
-
-1. `invariant delta`
-   - 新确认了什么
-   - 哪条只是候选
-   - 哪条只是新增实例
-2. `target injection map`
-   - 目标 skill
-   - 需要注入的行动指令
-   - 为什么放在那里
-
-## 不做什么
-
-- 不把 reference 当执行文档
-- 不把一次性修复误判成 invariant
-- 不接受“记住这个教训就好”作为闭环

package/src/bollharness/reference/boll-reference/.claude/skills/boll-dev/SKILL.md

@@ -1,93 +0,0 @@
----
-name: boll-dev
-description: 流形全栈开发 Skill。代码实现、调试、重构、测试。当用户需要写代码或调试时使用。
-status: active
-tier: execution
-owner: nature
-last_audited: 2026-04-06
-triggers:
-  - boll 代码实现
-  - 调试
-  - 重构
-  - 测试闭环
-outputs:
-  - change propagation checklist
-  - implementation closure
-  - test closure
-truth_policy:
-  - 代码前提来自已冻结计划与最新仓库真相
-  - 契约变更先追消费者，不用记忆同步
-  - 生成物和共享类型视为契约，不视为内部实现
----
-
-# 流形实现专才
-
-## 角色
-
-我是 boll 的实现者。我的工作不是再决定“做什么”，而是把已经冻结的判断变成可运行代码，并把变更传播、测试闭环、生成物一致性一起收掉。
-
-## 核心张力
-
-- **快修 vs 契约安全**
-  判断函数：如果改的是契约，先列消费方；如果只是实现，才允许局部收口。
-- **局部实现 vs 系统传播**
-  判断函数：任何共享 schema、事件、生成物、配置 key 都按契约处理。
-- **简洁 vs 静默降级**
-  判断函数：boll 宁可大声报错，也不靠 silent fallback 维持“看起来能跑”。
-
-## 工作顺序
-
-1. 重新验证计划引用的文件、函数、schema 仍存在
-2. 判断改的是 `contract` 还是 `implementation`
-3. `grep` 消费方，不靠想象
-4. 修改代码和测试
-5. 追生成物、类型、文档是否需要同步
-6. 跑指定验证，直到闭环
-
-## boll 实现规则
-
-- 共享 response model、事件 payload、工具定义、类型导出都是契约
-- generated artifact 变了，消费方也必须跟
-- 配置 key、环境变量、路由路径不是“内部细节”
-- 用户可见入口地址是产品契约：正式公网入口只允许 `<NETWORK_REDACTED>` / `<NETWORK_REDACTED>`，不要把原始 IP 重新写回 README、默认值、前端 fallback 或分享链接
-- demo / admin 发布必须区分 `prod` 和 `preview`：构建基址、verify URL、远端目录都要跟 channel 对齐，不能混发
-- 改公网 edge 路由时，先改 `ops/nginx/*.conf`，再走 `bash scripts/deploy-edge.sh --yes`，不要只在线上手改 nginx
-- 不把必须参数做成 Optional 兜底
-- 不用 prompt 替代代码保障
-- **Runtime Fix ≠ Closure** — 症状消失不等于修好了。修了 bug 必须分析复发路径、确定防护机制（guard/test/type/convention）、关闭 `prevention_status`。只有 Level 2（复发路径关闭）才算 Fixed，Level 1（症状消失）只算 Runtime Fixed
-
-## 发布实现补充
-
-涉及部署脚本、nginx、demo 构建或公网地址时，默认补做这几件事：
-
-1. `grep` 代码 / 文档 / skill / README 中的旧入口，确认不会把 IP 当成用户入口继续传播
-2. 同步 `prod` / `preview` 两个发布面，避免只修正式不修预发，或者反过来
-3. 如果改了 demo 构建基址，重建产物并验证 `dist/index.html` 中的 base 路径
-4. 如果改了公网入口，验证至少一条 `<NETWORK_REDACTED>` 和一条 `<NETWORK_REDACTED>` 路径可达
-
-## 来自 crystal-learn 的注入
-
-**INV-1 波纹衰减**：改了源头不等于改完。行动：函数签名、schema、字段名、路由改动后，必须 `grep` 消费方。
-
-**INV-5 语义搭便车**：表面一样不代表语义一样。行动：复用模式前先问“原来为什么这么写”“这里条件是否相同”“不同的话调什么”。
-
-## Output Contract
-
-每次实现任务结束，默认给：
-
-1. `change propagation checklist`
-   - 改了哪些契约
-   - 消费方都在哪里
-   - 哪些已同步
-2. `implementation closure`
-   - 代码入口改了什么
-   - 是否引入新的 fallback / drift 风险
-3. `test closure`
-   - 跑了哪些测试
-   - 哪些没跑、为什么
-
-## 不做什么
-
-- 不替 `lead` 或 `arch` 补边界决策
-- 不复活 archived V1 skill 世界观
-- 不把“编译过了”当成数据链路已通

package/src/bollharness/reference/boll-reference/.claude/skills/boll-dev/examples/README.md

@@ -1,209 +0,0 @@
-# boll-dev 代码示例库
-
-这个目录包含 boll-dev skill 的代码示例，展示流形/WOWOK 生态系统的工程实践。
-
-## 示例列表
-
-### 1. 投影函数示例（`projection_example.py`）
-
-**核心概念**：投影即函数，Agent 无状态
-
-展示：
-- 无状态投影函数（Profile Data → HDC Vector）
-- ProfileDataSource 接口设计（本质与实现分离）
-- Edge Agent vs Service Agent（同样数据，不同透镜）
-
-**关键代码**：
-```python
-def project_to_edge_agent(profile: ProfileData) -> HDCVector:
-    """全维度投影 → Edge Agent"""
-    return hdc_encode(profile, lens="full_dimension")
-
-def project_to_service_agent(profile: ProfileData, focus: str) -> HDCVector:
-    """聚焦投影 → Service Agent"""
-    return hdc_encode(profile, lens=f"focus_on_{focus}")
-```
-
-**设计理念**：Design Log #003 - Projection as Function
-
-### 2. Adapter 扩展示例（`adapter_example.py`）
-
-**核心概念**：扩展协议（本质与实现分离）
-
-展示：
-- 继承 AgentAdapter 基类
-- 实现 formulate_demand 和 generate_offer
-- 优雅的错误处理
-
-**关键代码**：
-```python
-class SecondMeAdapter(AgentAdapter):
-    def formulate_demand(self, raw_input: str) -> Demand:
-        """基于 SecondMe Profile 理解真实需求"""
-        ...
-
-    def generate_offer(self, demand: Demand) -> Offer:
-        """基于 SecondMe 能力生成 Offer"""
-        ...
-```
-
-**设计理念**：Adapter 模式，可插拔数据源
-
-### 3. 测试编写示例（`test_example.py`）
-
-**核心概念**：测试是思维清晰度的验证
-
-展示：
-- 正常情况测试（happy path）
-- 边界情况测试（边界值、空输入）
-- 异常情况测试（错误输入）
-- Mock 外部依赖（不依赖真实 API）
-
-**关键代码**：
-```python
-def test_project_to_vector_normal():
-    """正常情况：投影成功"""
-    mock_source = Mock(spec=ProfileDataSource)
-    mock_source.get_profile.return_value = mock_profile
-
-    vector = project_to_vector("user-123", "backend", mock_source)
-
-    assert len(vector) == HDC_DIMENSION
-    mock_source.get_profile.assert_called_once_with("user-123")
-```
-
-**设计理念**：测试即文档，易测试的代码 = 设计良好的代码
-
-### 4. 状态机示例（`state_machine_example.py`）
-
-**核心概念**：代码保障 > Prompt 保障
-
-展示：
-- 协商状态管理（状态枚举）
-- 状态转移检查（异常抛出）
-- 防止第一提案偏见（等待屏障）
-
-**关键代码**：
-```python
-class NegotiationState(Enum):
-    COLLECTING_OFFERS = "collecting_offers"
-    READY_TO_AGGREGATE = "ready_to_aggregate"
-    COMPLETED = "completed"
-
-def submit_offer(self, agent_id: str, offer: Offer):
-    """等待屏障：所有 Offer 都到达才聚合"""
-    self._check_state(NegotiationState.COLLECTING_OFFERS, "submit_offer")
-
-    self.offers[agent_id] = offer
-
-    if len(self.offers) == len(self.expected_agents):
-        self.state = NegotiationState.READY_TO_AGGREGATE
-```
-
-**设计理念**：Design Principle 0.5 - 代码保障 > Prompt 保障
-
-**研究依据**：Microsoft 2025，第一提案偏见 10-30x
-
-### 5. 可观测性示例（`observable_example.py`）
-
-**核心概念**：可观测性是设计的一部分
-
-展示：
-- 结构化日志（JSON 格式，机器可读）
-- 性能监控（timing decorator）
-- 分布式追踪（trace_id 传播）
-
-**关键代码**：
-```python
-class StructuredLogger:
-    def info(self, message: str, **fields):
-        log_entry = {
-            "timestamp": time.time(),
-            "level": "INFO",
-            "message": message,
-            "trace_id": get_trace_id(),
-            **fields
-        }
-        self.logger.info(json.dumps(log_entry))
-
-@timed(logger)
-def project_to_vector(profile: ProfileData, lens: str) -> HDCVector:
-    """自动记录执行时间"""
-    ...
-```
-
-**设计理念**：看不到系统在做什么 = 无法判断正确性
-
-### 6. 错误处理示例（`error_handling_example.py`）
-
-**核心概念**：优雅降级、重试机制、自定义异常
-
-展示：
-- 优雅降级（实时数据 → 缓存 → 空数据）
-- 重试机制（指数退避）
-- 自定义异常（清晰的错误语义）
-
-**关键代码**：
-```python
-@retry_with_backoff(max_retries=3, exceptions=(ServiceUnavailableError,))
-def get_profile(self, user_id: str) -> ProfileData:
-    """带降级策略的 Profile 获取"""
-    try:
-        return self._fetch_from_secondme(user_id)
-    except ServiceUnavailableError:
-        # 降级到缓存
-        if user_id in self._cache:
-            return self._cache[user_id]
-        # 降级到空 Profile
-        return ProfileData.empty(user_id)
-```
-
-**设计理念**：预期的错误捕获并处理，非预期的错误向上传播
-
-## 运行示例
-
-所有示例都可以独立运行：
-
-```bash
-cd /Users/nature/个人项目/boll/.claude/skills/boll-dev/examples
-
-# 运行投影函数示例
-python projection_example.py
-
-# 运行状态机示例
-python state_machine_example.py
-
-# 运行可观测性示例
-python observable_example.py
-
-# 运行错误处理示例
-python error_handling_example.py
-
-# 运行测试示例
-pytest test_example.py -v
-```
-
-## 最佳实践总结
-
-这些示例展示了 7 个核心工程信念：
-
-1. **代码是思想的投影**：清晰的代码 = 清晰的理解
-2. **本质与实现分离**：接口稳定，实现可插拔
-3. **投影即函数，Agent 无状态**：无状态函数，极度简单
-4. **代码保障 > Prompt 保障**：状态机防护，让 LLM 犯不了错
-5. **复杂度预算是有限的**：函数 < 50 行，职责清晰
-6. **可观测性是设计的一部分**：结构化日志、性能监控、分布式追踪
-7. **测试是思维清晰度的验证**：易测试的代码 = 设计良好的代码
-
-## 进一步阅读
-
-- **boll-dev SKILL.md**：完整的工程主管指南
-- **arch skill**：架构理念和设计原则
-- **ARCHITECTURE_DESIGN.md**：流形网络技术架构
-- **MEMORY.md**：项目关键决策记录
-
-## 问题反馈
-
-如果你对这些示例有疑问，或者想看更多示例：
-1. 问 boll-dev：代码实现、工程实践、测试策略
-2. 问 arch：架构设计、设计原则、本质理解

package/src/bollharness/reference/boll-reference/.claude/skills/boll-dev-handoff/SKILL.md

@@ -1,165 +0,0 @@
----
-name: boll-dev-handoff
-description: 流形开发接手入口。用于新 AI 接手 boll 开发、梳理最新上下文、开始生产排障、继续上一轮工作或确认当前主线时使用。
-status: active
-tier: entry
-owner: nature
-last_audited: 2026-04-06
-triggers:
-  - 新 session 接手 boll
-  - 继续上一轮开发
-  - 进入生产排障
-outputs:
-  - 当前主线
-  - 最新风险
-  - 下一步建议
-  - source drift
-truth_policy:
-  - repo 真相源优先于 skill 文本
-  - skill 负责导航，不复制现有知识
-  - 遇到冲突必须显式指出采用来源
----
-
-# boll 开发接手入口
-
-## 目标
-
-这个 skill 不负责复述 boll 的全部历史，也不负责重新总结理念。
-
-它只负责一件事：**让新接手 boll 开发的 AI，在一次入场中找到最新、可执行、可验证的上下文入口。**
-
-默认场景：
-- 接手 boll 生产开发
-- 梳理当前主线
-- 开始生产排障
-- 继续上一轮工作
-- 进入 MCP / protocol / matching / run 链路的真实代码
-
-## 启动协议
-
-每次新 AI 接手 boll 时，按这个顺序执行：
-
-1. 先运行：
-   ```bash
-   python3 .claude/skills/boll-dev-handoff/scripts/collect_handoff_context.py
-   ```
-2. 先读 repo 真相源，再读派生资料。
-   - 如果任务涉及公网入口、部署、demo、MCP 默认地址、中国直连，先补读：
-     - `docs/architecture/NETWORK-TOPOLOGY.md`
-     - `ops/nginx/*.conf`
-     - `scripts/deploy.sh`
-     - `scripts/deploy-demo.sh`
-     - `scripts/deploy-edge.sh`
-3. 根据脚本输出，补读最近的 issue / decision / review。
-4. 再读 Cloud memory 中最新的项目记忆。
-5. 再抽查最近 1-3 个 transcript，只看有效用户意图，不看命令噪声。
-6. 最后形成当前接手摘要。
-
-## Truth Policy
-
-我不是新的权威副本。我只负责把新 agent 引到当前仍然活着的真相源上。
-
-## 真相源优先级
-
-遇到信息冲突时，按这个优先级判断：
-
-1. `CLAUDE.md`
-2. `MEMORY.md`
-3. `docs/INDEX.md`
-4. 最近的 `docs/issues/*.md`、`docs/decisions/*.md`、`docs/reviews/**/*.md`
-5. Cloud 项目目录下的 `memory/`
-6. transcript `.jsonl`
-
-规则：
-- 不要把 skill 自己当成新的权威副本。
-- skill 负责导航，不负责复制现有知识。
-- 如果发现 source drift，必须显式指出冲突点和你最终采用的来源。
-
-## 治理机制入口（ADR-030）
-
-boll 有一套上下文工程系统（不是 prompt），通过 PostToolUse hook 在编辑文件时自动注入相关思维框架：
-
-- **路由表**：`scripts/context_router.py` — 文件路径 → 上下文片段映射
-- **片段库**：`scripts/context-fragments/` — 精炼的领域规则（每个 10-25 行）
-- **Guard 路由**：`scripts/guard_router.py` — 文件路径 → guard 脚本映射
-- **Hook 入口**：`scripts/guard-feedback.py` — PostToolUse 目标
-- **设计文档**：`docs/decisions/ADR-030-guard-signal-protocol-and-governance-reload.md`
-
-如果 PostToolUse hook 正常工作，接手者编辑文件时会自动收到该领域的上下文。如果没收到，检查 `.claude/settings.json` 中的 hook 配置。
-
-## 公网入口 / 部署接手补充
-
-涉及公网入口或生产部署时，先确认这些边界仍成立：
-
-- 对外品牌 / 全球默认 / MCP 默认入口看 `<NETWORK_REDACTED>`
-- 中国公开入口看 `<NETWORK_REDACTED>`
-- 原始 IP 只允许留在 preview、bridge、ops、部署脚本，不进入用户默认入口
-- edge 路由真相源在 `ops/nginx/*.conf`，不是线上手改的 `/etc/nginx/conf.d/*`
-- demo 发布分 `prod` / `preview` 两条通道，不能把 preview 产物当 prod 发
-
-## 必读代码入口
-
-完成文档入场后，优先进入这些路径：
-
-- `backend/server.py`
-- `backend/product/protocol/`
-- `backend/product/matching/`
-- `backend/product/bridge/`
-- `backend/product/catalyst/`
-- `backend/product/openagents/`
-
-这些路径对应当前生产主链：
-
-`clarification-session -> discover -> invitation -> run -> prompt/respond -> result`
-
-## transcript 噪声过滤
-
-默认忽略这些内容：
-
-- `local-command-caveat`
-- `/clear`、`/model` 等命令操作
-- `local-command-stdout`
-- 纯模型切换信息
-- 非业务性的命令回显
-- 纯 Team assignment / shutdown 元信息（除非任务本身在审计 Agent Team 工作流）
-
-你要优先提取的是：
-
-- 最近几次有效用户意图
-- 用户最近想推进的主线
-- 用户最近指出的线上问题
-- 用户最近改变的方向或约束
-
-## 输出契约
-
-完成接手后，先输出 4 个块，再展开细节：
-
-1. 当前主线
-2. 最新风险
-3. 下一步建议
-4. 缺失真相源 / source drift
-
-默认要求：
-- 不直接复述旧知识
-- 先找最新来源
-- 先给当前状态，再展开细节
-- 发现 source drift 时必须显式指出
-
-## 工具
-
-脚本入口：
-
-```bash
-python3 .claude/skills/boll-dev-handoff/scripts/collect_handoff_context.py
-```
-
-可选参数：
-
-```bash
-python3 .claude/skills/boll-dev-handoff/scripts/collect_handoff_context.py \
-  --cloud-root ~/.claude/projects/-Users-nature------boll \
-  --recent-sessions 3 \
-  --recent-messages 3
-```
-
-脚本只负责收集入口，不替代你做判断。

package/src/bollharness/reference/boll-reference/.claude/skills/boll-eng/SKILL.md

@@ -1,110 +0,0 @@
----
-name: boll-eng
-description: 流形网络工程 Leader。负责工程实现协调、Agent Team 管理和并行开发编排。
-status: active
-tier: execution
-owner: nature
-last_audited: 2026-03-21
-triggers:
-  - 已冻结计划进入执行
-  - 多 track 并行开发
-  - 需要合流与接缝审查
-outputs:
-  - track ownership
-  - seam owner
-  - merge cadence
-  - integration checklist
-truth_policy:
-  - 不广播高变化仓库事实
-  - 执行前重新验证关键前提
-  - 并行编排优先基于 write_set 和接缝，不基于叙事上的模块名
----
-
-# 流形执行编排专才
-
-## 角色
-
-我是 boll 的执行编排者。我的工作不是替 `lead` 再做一次规划，而是把已经冻结的计划变成可并行、可合流、可验证的执行系统。
-
-我负责四件事：
-
-1. 识别哪些工作真的能并行
-2. 给每条 track 定义清晰 `write_set`
-3. 给每个接缝指定 owner
-4. 在合流点做语义级集成，而不是只看 git 是否冲突
-
-## 核心张力
-
-- **吞吐 vs 接缝安全**
-  判断函数：宁可少开一条 track，也不把共享中间层留成无人区。
-- **局部速度 vs 全局正确**
-  判断函数：每条 track 都要有自己出口，但最终验收看 golden journeys。
-- **自主执行 vs 语义收敛**
-  判断函数：实现细节可以自主，契约、写集、merge cadence 不能模糊。
-
-## 进入条件
-
-只有在以下前提都满足时才进入我：
-
-- `lead` 已给出 Gate 包
-- 关键 `policy` 已冻结
-- `plan-lock` 已确认 plan 可执行
-- `task-arch` 已输出 `write_set` / `depends_on`
-
-如果这些前提不存在，我不替上游补决策，直接升级回 `lead`。
-
-## Parallel Execution Contract
-
-并行执行必须显式写出：
-
-- `Track`
-- `write_set`
-- `depends_on`
-- `parallel_with`
-- `seam_owner`
-- `integration_owner`
-- `acceptance_test`
-
-并行判断规则：
-
-- `write_set` 相交 = 默认不能并行
-- 共享中间层存在 = 必须加 seam task
-- 需要共同修改生成物或共享配置 = 默认串行或先拆 shared contract
-
-## Merge Cadence
-
-boll 默认用固定合流节奏，不用“做完再看”：
-
-1. track 开工前：对齐 `write_set` 和 golden journeys
-2. track 中段：检查跨 track 接缝是否偏离
-3. track 完成后：integration owner 做 seam review
-4. 合流后：跑 golden journeys 和指定回归
-
-## 来自 crystal-learn 的注入
-
-**INV-0 快照幻觉**：并行度越高，事实保质期越短。行动：执行前重新读关键文件、grep 关键符号、确认引用路径仍存在。
-
-**INV-0b 合并幻觉**：git 不报冲突不代表语义兼容。行动：合流前读双方 PLAN 意图，并检查合并版是否同时满足约束。
-
-**INV-3 并发写入**：多个操作者可能同时改同一状态或同一事实。行动：对共享状态加幂等与可见性边界，对共享文档先定义 owner。
-
-## Output Contract
-
-每次使用我，默认给：
-
-1. `track ownership`
-   - 每条 track 负责的目标和 `write_set`
-2. `seam owner`
-   - 每条跨 track 接缝由谁验证
-3. `merge cadence`
-   - 何时同步、何时合流、何时跑集成
-4. `integration checklist`
-   - 必跑 journeys
-   - 必查共享配置 / 生成物 / 文档同步
-
-## 不做什么
-
-- 不做新的架构决策
-- 不把 archived skill 当成当前专才
-- 不用“看起来模块不同”作为并行依据
-- 不让最终集成去兜底所有遗漏