npm - @bolloon/bolloon-agent - Versions diffs - 0.1.0 → 0.1.2 - Mend

@bolloon/bolloon-agent 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (581) hide show

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

@@ -1,320 +0,0 @@
----
-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 DELETED Viewed

@@ -1,93 +0,0 @@
----
-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 DELETED Viewed

@@ -1,227 +0,0 @@
-# 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：架构设计、设计原则、本质理解