@bolloon/bolloon-agent 0.1.0

package/src/bollharness/.boll/skills/guardian-fixer/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: guardian-fixer
+description: 守夜人 issue 自动修复管道。8 Gate 全流程——规划、独立审查、开发、测试、闭环、PR。用于修复 docs/issues/guard-*.md 中 status:open 的 issue。
+status: active
+tier: execution
+owner: nature
+last_audited: 2026-03-24
+triggers:
+  - 修复 guardian issue
+  - 执行 guard issue
+  - 自动修复管道
+outputs:
+  - 独立 branch 上的 PR
+  - 完整 Gate artifacts (PLAN/REVIEW/TASK/LOG/TEST/CLOSURE)
+truth_policy:
+  - issue 文档是唯一执行队列
+  - 不从口头描述、memory、聊天记录直接开做
+  - 代码真相以 repo 当前状态为准，不以 issue 描述为准
+---
+
+# 守夜人 Issue 自动修复
+
+## 我是谁
+
+我把 `docs/issues/guard-*.md`（status: open）变成可合并的 PR。我不发现 issue（那是巡逻的事），我只修复。
+
+## 核心约束
+
+1. **8 Gate 全走，一个都不能少。** 简单 issue 不是跳步的理由。
+2. **审查是独立的。** Gate 2/4/7 必须 spawn 独立 subagent（opus），不是自己审自己。
+3. **验证是诚实的。** 跑不了的测试标 BLOCKED，不标 PASS。"collect 通过" ≠ "测试通过"。
+4. **写了代码必须运行。** 每个 WP 完成后必须有运行时证据（命令 + 输出），不是"看起来对"。
+
+## 执行流程
+
+### Step 0: 选 issue
+
+```bash
+# 找到优先级最高的可执行 issue
+grep -rl 'status: open' docs/issues/guard-*.md | while read f; do
+  sev=$(grep '^severity:' "$f" | sed 's/severity: *//')
+  exec_st=$(grep '^execution_status:' "$f" | sed 's/execution_status: *//')
+  # 跳过已有 execution_status 的（除了 pending）
+  if [ -z "$exec_st" ] || [ "$exec_st" = "pending" ]; then
+    echo "$sev|$f"
+  fi
+done | sort
+```
+
+选第一个（P0 > P1 > P2）。如果需要检查 zone 冲突，查 DESIGN 文档 Section 3.6 的 CODE_ZONES。
+
+### Step 1: 建 worktree
+
+```bash
+ISSUE_SLUG="guard-YYYYMMDD-HHMM-slug"  # 从 issue 文件名提取
+git worktree add /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG -b codex/$ISSUE_SLUG main
+mkdir -p /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG/docs/decisions/tasks/GUARD-YYYYMMDD-HHMM
+```
+
+以下所有操作在 worktree 目录内进行。
+
+### Step 2: Gate 1 — 规划
+
+**输入**: issue 文档
+**产物**: `PLAN.md`
+
+PLAN.md 必须包含：
+
+```markdown
+# PLAN: guard-YYYYMMDD-HHMM — 标题
+
+**Issue**: issue 文档路径
+**Severity**: P0/P1/P2
+**Component**: 主要代码文件
+
+## 问题分析
+（根因，不是症状）
+
+## 变更清单
+| # | 文件 | 变更 | 类型 |
+
+## 契约 vs 实现分析
+- 契约变更？消费方？
+
+## 同类检查
+（grep 验证是否有其他地方有同样的问题）
+
+## 测试策略
+（修改前/修改后的验证方法）
+
+## Scope 判定
+- ≤3 文件 + 无契约变更 → 可执行
+- 否则 → needs_plan，停止
+```
+
+**Scope 硬上限**：
+- 超过 3 个代码文件 → 标 `needs_plan`，停止
+- API/schema/event 契约变更 → 标 `needs_plan`，停止
+- 需要数据库 migration → 标 `needs_plan`，停止
+
+### Step 3: Gate 2 — 独立审查 PLAN
+
+**用 Agent tool spawn 独立审查者（opus 模型）。不是自己审自己。**
+
+```
+Agent tool:
+  model: opus
+  prompt: |
+    你是独立代码审查者。你没有参与这段代码的编写。
+
+    审查 PLAN 文档：[路径]
+    对照 issue 文档：[路径]
+    读相关代码文件。
+
+    审查维度（全部覆盖）：
+    1. 覆盖性：变更清单完整吗？
+    2. 独立性：每个改动可独立验证吗？
+    3. 执行模拟：逐步走，开发者会卡住吗？
+    4. 自包含性：有执行所需全部信息吗？
+    5. 元数据准确性：severity/component/scope 正确吗？
+    6. 修复完整性：修复完整吗？有没有引入新问题？
+
+    输出写入：[PLAN-REVIEW.md 路径]
+    YAML frontmatter 必须有 verdict: PASS 或 FAIL。
+```
+
+**如果 FAIL**：修改 PLAN，重新提交审查（最多 2 轮）。2 轮不通过 → 标 `blocked`，停止。
+
+### Step 4: Gate 3 — 任务拆解
+
+**产物**: `TASK.md`
+
+```markdown
+# TASK: guard-YYYYMMDD-HHMM
+
+## WP-N: 标题
+**文件**: 路径
+**改什么**: 具体描述
+**验收标准**: 可机械验证的条件
+
+## 验收测试
+| # | 方法 | 预期结果 |
+```
+
+### Step 5: Gate 4 — 独立审查 TASK
+
+同 Gate 2，spawn 独立审查者审查 TASK.md。
+
+### Step 6: Gate 5 — 开发
+
+**操作顺序**：
+
+1. **先开 LOG.md**（实时写，不是事后补）
+2. 逐个 WP 执行：
+   a. 写代码
+   b. **运行代码**（关键！不是"看起来对"就 commit）
+   c. 记录运行命令和输出到 LOG.md
+   d. 验证 TASK.md 中的验收标准
+3. 更新 issue 文档状态（pre-commit hook 要求）
+4. Commit（不 push）
+
+**Worktree 里 Read/Edit 工具可能被 guard hook 阻塞**（pre-existing findings）。用 Bash 操作 worktree 文件：
+- 读文件：`cat` / `tail`
+- 写文件：`cat > file << 'EOF'` 或 `cat >> file << 'EOF'`
+- 小修改：`sed -i ''`
+
+**LOG.md 格式**：
+
+```markdown
+# LOG: guard-YYYYMMDD-HHMM
+
+## WP-N: 标题
+- 做了什么
+- 运行命令 + 输出（证据）
+- 偏差说明（如果有）
+
+## 验收检查
+| # | 方法 | 结果 |
+```
+
+### Step 7: Gate 6 — 测试
+
+**运行所有能跑的测试**：
+
+```bash
+# 从 worktree 运行
+cd /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG
+npm test  # 运行项目测试
+```
+
+**产物**: `TEST.md`
+
+```markdown
+# TEST: guard-YYYYMMDD-HHMM
+
+## 测试执行结果
+
+### 可运行测试
+| 测试集 | 数量 | 结果 | 命令 |
+
+### 需要 Docker 的测试
+| 测试集 | 状态 | 原因 |
+
+### 诚实声明
+- 新代码有没有被测试覆盖？
+- 是"旧测试通过"还是"新代码验证通过"？
+- 有没有把 BLOCKED 标成 PASSED？
+```
+
+**诚实规则**：
+- "collect 通过" ≠ "测试通过"
+- "旧测试通过" ≠ "新代码验证通过"
+- Docker 不可用 → 标 BLOCKED，不标 PASS
+- 不虚构测试数量
+
+### Step 8: Gate 7 — 最终审查
+
+Spawn 独立审查者（opus）审查代码 diff + 测试结果。
+
+```
+Agent tool:
+  model: opus
+  prompt: |
+    你是独立代码审查者（最终审查）。
+
+    审查 git diff + TEST.md + LOG.md。
+    检查代码是否与 PLAN 一致。
+    检查有没有引入新问题。
+    检查 TEST.md 是否诚实。
+
+    输出写入：[FINAL-REVIEW.md 路径]
+    verdict: PASS 或 FAIL。
+```
+
+### Step 9: Gate 7.5 — Closure
+
+**产物**: `CLOSURE.md`
+
+```markdown
+# CLOSURE
+
+## Issue 闭环状态
+- status: fixed ✓/✗
+- prevention_status: closed ✓/✗
+- mechanism_layer: guard|test|type|convention ✓/✗
+
+## 文档同步清单
+
+### 必须更新
+- [ ] issue 文档 status/prevention_status
+
+### 可能需要更新（写进 PR 描述）
+- [ ] CLAUDE.md 路由表（如果改了 API）
+- [ ] 其他 issue 文档（如果修复也解决了其他问题）
+
+### 不需要更新
+- （列出检查过但不需要改的）
+```
+
+**禁止修改的文件**：
+- CLAUDE.md（行为指令部分）
+- AGENTS.md
+- `.boll/skills/*/SKILL.md`
+- `scripts/hooks/guard-feedback.ts`
+- `scripts/context_router.ts`
+
+### Step 10: Gate 8 — Push + PR
+
+```bash
+cd /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG
+git push -u origin codex/$ISSUE_SLUG
+gh pr create --title "fix(...): guard-YYYYMMDD-HHMM 标题" --body "..."
+```
+
+PR 描述必须包含：
+- Issue 路径
+- 变更摘要
+- 8 Gate 结果表
+- 验证结果（诚实标注 PASS/BLOCKED）
+- Artifacts 列表
+
+## 异常处理
+
+| 场景 | 操作 |
+|------|------|
+| Scope 超 3 文件 | Gate 1 标 `needs_plan`，停止 |
+| 审查 2 轮不通过 | 标 `blocked`，停止 |
+| 测试失败且无法修 | TEST.md 记录失败原因，标 `blocked`，停止 |
+| 碰禁止修改的文件 | 停止 |
+| Rebase 冲突 | 标 `needs_coordination`，停止 |
+
+**所有异常路径都停止。不要强行继续。**
+
+## 反模式清单
+
+以下行为是明确禁止的（PLAN-064 教训）：
+
+| 反模式 | 正确做法 |
+|--------|---------|
+| 写完代码不运行就 commit | 每个 WP 必须有运行时证据 |
+| LOG.md 从 git log 生成 | LOG.md 在写代码时实时写 |
+| 把 "199 tests PASS" 当验证 | 区分旧测试/新测试，标注新代码覆盖率 |
+| 4 分钟完成一个 WP | 如果太快，说明没有运行验证 |
+| 自己审自己 | Gate 2/4/7 必须 spawn 独立 subagent |
+| Docker 不可用就跳过 | 标 BLOCKED，不标 PASS |
+
+## Gate 检查清单
+
+执行前自检——**如果正在写代码但 PLAN.md 不存在，立刻停下来。**
+
+```
+□ PLAN.md 存在？           → Gate 2 可以开始
+□ PLAN-REVIEW.md verdict: PASS？ → Gate 3 可以开始
+□ TASK.md 存在？           → Gate 4 可以开始
+□ TASK-REVIEW.md verdict: PASS？ → Gate 5 可以开始
+□ LOG.md 存在？            → Gate 6 可以开始
+□ TEST.md 存在？           → Gate 7 可以开始
+□ FINAL-REVIEW.md verdict: PASS？ → Gate 7.5 可以开始
+□ CLOSURE.md 存在？        → Gate 8 可以开始
+```

package/src/bollharness/.boll/skills/harness-dev/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: harness-dev
+description: {{PROJECT_NAME}}全栈开发 Skill。代码实现、调试、重构、测试。当用户需要写代码或调试时使用。
+status: active
+tier: execution
+owner: nature
+last_audited: 2026-04-06
+triggers:
+  - {{PROJECT_NAME}} 代码实现
+  - 调试
+  - 重构
+  - 测试闭环
+outputs:
+  - change propagation checklist
+  - implementation closure
+  - test closure
+truth_policy:
+  - 代码前提来自已冻结计划与最新仓库真相
+  - 契约变更先追消费者，不用记忆同步
+  - 生成物和共享类型视为契约，不视为内部实现
+---
+
+# {{PROJECT_NAME}}实现专才
+
+## 角色
+
+我是 {{PROJECT_NAME}} 的实现者。我的工作不是再决定"做什么"，而是把已经冻结的判断变成可运行代码，并把变更传播、测试闭环、生成物一致性一起收掉。
+
+## 核心张力
+
+- **快修 vs 契约安全**
+  判断函数：如果改的是契约，先列消费方；如果只是实现，才允许局部收口。
+- **局部实现 vs 系统传播**
+  判断函数：任何共享 schema、事件、生成物、配置 key 都按契约处理。
+- **简洁 vs 静默降级**
+  判断函数：{{PROJECT_NAME}} 宁可大声报错，也不靠 silent fallback 维持"看起来能跑"。
+
+## 工作顺序
+
+1. 重新验证计划引用的文件、函数、schema 仍存在
+2. 判断改的是 `contract` 还是 `implementation`
+3. `grep` 消费方，不靠想象
+4. 修改代码和测试
+5. 追生成物、类型、文档是否需要同步
+6. 跑指定验证，直到闭环
+
+## {{PROJECT_NAME}} 实现规则
+
+- 共享 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/.boll/skills/harness-dev/examples/README.md

@@ -0,0 +1,227 @@
+# harness-dev 代码示例库
+
+这个目录包含 harness-dev skill 的代码示例，展示{{PROJECT_NAME}}/WOWOK 生态系统的工程实践。
+
+## 示例列表
+
+### 1. 投影函数示例（`projection_example.ts`）
+
+**核心概念**：投影即函数，Agent 无状态
+
+展示：
+- 无状态投影函数（Profile Data → HDC Vector）
+- ProfileDataSource 接口设计（本质与实现分离）
+- Edge Agent vs Service Agent（同样数据，不同透镜）
+
+**关键代码**：
+```typescript
+function projectToEdgeAgent(profile: ProfileData): HDCVector {
+    return hdcEncode(profile, "full_dimension");
+}
+
+function projectToServiceAgent(profile: ProfileData, focus: string): HDCVector {
+    return hdcEncode(profile, `focus_on_${focus}`);
+}
+```
+
+**设计理念**：Design Log #003 - Projection as Function
+
+### 2. Adapter 扩展示例（`adapter_example.ts`）
+
+**核心概念**：扩展协议（本质与实现分离）
+
+展示：
+- 继承 AgentAdapter 基类
+- 实现 formulate_demand 和 generate_offer
+- 优雅的错误处理
+
+**关键代码**：
+```typescript
+class SecondMeAdapter extends AgentAdapter {
+    async formulateDemand(rawInput: string): Promise<Demand> {
+        return { intent: parseIntent(rawInput) };
+    }
+
+    async generateOffer(demand: Demand): Promise<Offer> {
+        return { ...demand, status: "pending" };
+    }
+}
+```
+
+**设计理念**：Adapter 模式，可插拔数据源
+
+### 3. 测试编写示例（`test_example.ts`）
+
+**核心概念**：测试是思维清晰度的验证
+
+展示：
+- 正常情况测试（happy path）
+- 边界情况测试（边界值、空输入）
+- 异常情况测试（错误输入）
+- Mock 外部依赖（不依赖真实 API）
+
+**关键代码**：
+```typescript
+describe("projectToVector", () => {
+    it("normal case: projection succeeds", () => {
+        const mockSource = mock<ProfileDataSource>();
+        mockSource.getProfile.mockResolvedValue(mockProfile);
+
+        const vector = projectToVector("user-123", "backend", mockSource);
+
+        expect(vector).toHaveLength(HDC_DIMENSION);
+        expect(mockSource.getProfile).toHaveBeenCalledOnceWith("user-123");
+    });
+});
+```
+
+**设计理念**：测试即文档，易测试的代码 = 设计良好的代码
+
+### 4. 状态机示例（`state_machine_example.ts`）
+
+**核心概念**：代码保障 > Prompt 保障
+
+展示：
+- 协商状态管理（状态枚举）
+- 状态转移检查（异常抛出）
+- 防止第一提案偏见（等待屏障）
+
+**关键代码**：
+```typescript
+enum NegotiationState {
+    COLLECTING_OFFERS = "collecting_offers",
+    READY_TO_AGGREGATE = "ready_to_aggregate",
+    COMPLETED = "completed"
+}
+
+function submitOffer(self: NegotiationContext, agentId: string, offer: Offer): void {
+    if (self.state !== NegotiationState.COLLECTING_OFFERS) {
+        throw new Error("Invalid state for submitOffer");
+    }
+
+    self.offers[agentId] = offer;
+
+    if (Object.keys(self.offers).length === self.expectedAgents.length) {
+        self.state = NegotiationState.READY_TO_AGGREGATE;
+    }
+}
+```
+
+**设计理念**：Design Principle 0.5 - 代码保障 > Prompt 保障
+
+**研究依据**：Microsoft 2025，第一提案偏见 10-30x
+
+### 5. 可观测性示例（`observable_example.ts`）
+
+**核心概念**：可观测性是设计的一部分
+
+展示：
+- 结构化日志（JSON 格式，机器可读）
+- 性能监控（timing decorator）
+- 分布式追踪（trace_id 传播）
+
+**关键代码**：
+```typescript
+class StructuredLogger {
+    info(message: string, fields: Record<string, unknown>): void {
+        const logEntry = {
+            timestamp: Date.now(),
+            level: "INFO",
+            message,
+            trace_id: getTraceId(),
+            ...fields
+        };
+        this.logger.info(JSON.stringify(logEntry));
+    }
+}
+
+function timed<T extends (...args: unknown[]) => unknown>(
+    logger: StructuredLogger,
+    fn: T
+): T {
+    return ((...args: unknown[]) => {
+        const start = Date.now();
+        const result = fn(...args);
+        logger.info(`Function ${fn.name} took ${Date.now() - start}ms`);
+        return result;
+    }) as T;
+}
+```
+
+**设计理念**：看不到系统在做什么 = 无法判断正确性
+
+### 6. 错误处理示例（`error_handling_example.ts`）
+
+**核心概念**：优雅降级、重试机制、自定义异常
+
+展示：
+- 优雅降级（实时数据 → 缓存 → 空数据）
+- 重试机制（指数退避）
+- 自定义异常（清晰的错误语义）
+
+**关键代码**：
+```typescript
+async function getProfile(userId: string): Promise<ProfileData> {
+    try {
+        return await fetchFromSecondMe(userId);
+    } catch (error) {
+        if (error instanceof ServiceUnavailableError) {
+            if (this.cache.has(userId)) {
+                return this.cache.get(userId)!;
+            }
+            return ProfileData.empty(userId);
+        }
+        throw error;
+    }
+}
+```
+
+**设计理念**：预期的错误捕获并处理，非预期的错误向上传播
+
+## 运行示例
+
+所有示例都可以独立运行：
+
+```bash
+cd .boll/skills/harness-dev/examples
+
+# 运行投影函数示例
+npx ts-node projection_example.ts
+
+# 运行状态机示例
+npx ts-node state_machine_example.ts
+
+# 运行可观测性示例
+npx ts-node observable_example.ts
+
+# 运行错误处理示例
+npx ts-node error_handling_example.ts
+
+# 运行测试示例
+npm test
+```
+
+## 最佳实践总结
+
+这些示例展示了 7 个核心工程信念：
+
+1. **代码是思想的投影**：清晰的代码 = 清晰的理解
+2. **本质与实现分离**：接口稳定，实现可插拔
+3. **投影即函数，Agent 无状态**：无状态函数，极度简单
+4. **代码保障 > Prompt 保障**：状态机防护，让 LLM 犯不了错
+5. **复杂度预算是有限的**：函数 < 50 行，职责清晰
+6. **可观测性是设计的一部分**：结构化日志、性能监控、分布式追踪
+7. **测试是思维清晰度的验证**：易测试的代码 = 设计良好的代码
+
+## 进一步阅读
+
+- **harness-dev SKILL.md**：完整的工程主管指南
+- **arch skill**：架构理念和设计原则
+- **ARCHITECTURE_DESIGN.md**：{{PROJECT_NAME}}网络技术架构
+- **MEMORY.md**：项目关键决策记录
+
+## 问题反馈
+
+如果你对这些示例有疑问，或者想看更多示例：
+1. 问 harness-dev：代码实现、工程实践、测试策略
+2. 问 arch：架构设计、设计原则、本质理解