@bolloon/bolloon-agent 0.1.1 → 0.1.2

package/src/bollharness/scripts/context-fragments/pi-agent-operations.md

@@ -0,0 +1,108 @@
+---
+paths:
+  - "src/agents/**"
+---
+
+# Pi Agent 操作与工具定义
+
+> 来源: pi-sdk.ts TOOL_DEFINITIONS + getDefaultResponse
+> 关联: src/agents/constraint-layer.ts（工具注册）
+
+---
+
+## 核心操作
+
+| 操作 | 描述 | 方法签名 |
+|------|------|----------|
+| 读取文档 | 读取并分析文档内容，支持 .txt, .md, .pdf, .docx | `read_document(path)` |
+| 总结文档 | 总结文档内容，可选提供上下文 | `summarize_document(path, context?)` |
+| 改进文档 | 改进文档，需提供文件路径和改进要求 | `improve_document(path, requirements)` |
+| 查看节点 | 查看已连接的对等节点 | `list_peers()` |
+| 发送消息 | 向指定对等节点发送消息 | `send_message(peer_id, message)` |
+| 广播消息 | 广播消息到所有节点 | `broadcast_message(message)` |
+| 查看身份 | 查看当前智能体身份 | `get_identity()` |
+| 设置 Persona | 更新智能体 persona 信息 | `set_persona(persona_json)` |
+| 执行工作流 | 执行预定义工作流 | `run_workflow(steps)` |
+| 查看日志 | 查看最近操作日志 | `get_operation_logs()` |
+| 列出文件 | 列出目录中的文件 | `list_files(path?)` |
+| 读取目录 | 读取目录内容，返回文件列表和目录结构 | `read_directory(path?)` |
+
+---
+
+## 自主循环机制
+
+智能体基于 ReAct (Reasoning + Acting) 模式工作，具备自动评估质量和错误恢复能力：
+
+### 质量评估与自动改进
+- **质量阈值**: `0.6` (6/10)
+- **最大改进次数**: `3` 次
+- 当回复或工具执行结果质量低于阈值时，自动触发改进循环
+- 改进时在 system prompt 中添加质量提示，让 LLM 重新生成更优回答
+
+### 错误处理与自动恢复
+- **连续错误上限**: `3` 次
+- 工具执行失败时增加错误计数
+- 达到连续错误上限时，添加错误上下文让 LLM 换一种方式处理
+- 工具执行异常会被捕获并记录，不中断循环
+
+### 循环继续条件
+当 LLM 返回不是 tool call 格式时，判断是否需要继续循环：
+1. 包含错误/失败信息（不存在、找不到、错误、failed 等）
+2. 回复太短（<100 字符且无换行），可能是中间回复
+3. 包含问号，可能是需要更多信息
+4. 不包含明确结论（完成、结果、答案等）
+
+满足以上任一条件且循环未达上限，则继续处理。
+
+### 重试机制
+- 工具调用失败时重试（最多 3 次）
+- 汇报发送失败时重试（最多 2 次，指数退避）
+- 失败的汇报会进入待重试队列
+
+---
+
+## 示例请求格式
+
+### 文档操作
+```
+"读取 README.md"
+"总结一下 src/index.ts"
+"改进文档，按照更清晰的错误处理要求"
+```
+
+### P2P 网络操作
+```
+"查看当前连接了哪些节点"
+"向 QmABC... 发送测试消息"
+"广播消息：系统将在 10 分钟后维护"
+```
+
+### 身份与状态
+```
+"查看身份"
+"查看日志"
+```
+
+---
+
+## 工具注册位置
+
+工具在 `pi-sdk.ts` 的 `PiAgent` 类构造函数中注册，映射到：
+- `src/agents/constraint-layer.ts` — ConstraintLayer 基类提供的基础能力
+- `src/network/p2p.ts` — P2P 网络模块
+- `src/documents/reader.ts` — 文档读取模块
+
+---
+
+## 自然语言指令映射
+
+| 自然语言指令 | 解析关键词 | 执行方法 |
+|-------------|-----------|----------|
+| 读取 X | `读取`、`read_document`、`read` | `readDocument(path)` |
+| 总结文档 | `总结`、`summarize_document` | `summarizeDocument(path, context?)` |
+| 改进文档 | `改进`、`improve_document` | `improveDocument(request)` |
+| 查看节点 | `查看节点`、`list_peers` | `listPeers()` |
+| 发送消息 | `向 X 发送消息`、`send_message` | `sendMessage(peerId, message)` |
+| 广播消息 | `广播消息`、`broadcast_message` | `broadcast(message)` |
+| 查看身份 | `查看身份`、`get_identity` | `getIdentity()` |
+| 查看日志 | `查看日志`、`get_operation_logs` | `getOperationLogs()` |

package/src/bollharness/scripts/context-fragments/protocol-consumers.md

@@ -0,0 +1,15 @@
+## Protocol API 消费方
+
+你正在编辑 /protocol/ 相关代码。以下是 Protocol API 的消费方列表：
+
+| 消费方 | 入口 | 认证方式 |
+|--------|------|----------|
+| MCP Server (Python) | `mcp-server/boll_mcp/client.py` | session token |
+| MCP Server (Node) | `mcp-server-node/src/client.ts` | session token |
+| 前端 website | `website/` fetch 调用 | session token (cookie) |
+| Bridge Agent | `bridge_agent/` | bridge API key |
+| 外部 A2A 调用方 | federation endpoint | DID 签名 |
+
+**行为约束**: 修改任何 /protocol/ 路由的请求/响应结构时，必须检查上述所有消费方是否兼容。
+不得在不更新消费方的情况下修改返回字段名或删除字段。
+新增字段必须是 optional，避免破坏现有消费方。

package/src/bollharness/scripts/context-fragments/run-events-consumers.md

@@ -0,0 +1,15 @@
+## run_events 消费方（共享结构）
+
+你正在编辑 run_events 相关代码。此表有 6 个消费方，各自角色不同：
+
+| 消费方 | 读/写 | 用途 | 关键依赖 |
+|--------|-------|------|----------|
+| Bridge events 路由 | 写 | 接收 worker 上报的事件 | event_type 枚举 |
+| Catalyst coordinator | 写 | 记录协商轮次事件 | round_number, role |
+| Run status API | 读 | 前端展示进度 | 按 run_id 查询 + 时间排序 |
+| Run result API | 读 | 提取最终产物 | artifact 类型过滤 |
+| Admin event log | 读 | 运维审计 | 全字段 |
+| WebSocket hub | 读 | 实时推送 | 增量查询（last_id） |
+
+**行为约束**: 修改 run_events 表结构或写入逻辑时，必须逐一确认 6 个消费方不受影响。
+不得假设"只有一个地方读"。读模型截断会导致长 run 状态不正确。

package/src/bollharness/scripts/context-fragments/scene-fidelity.md

@@ -0,0 +1,13 @@
+## 场景保真度分级
+
+你正在编辑场景相关代码。每个场景有明确的保真度等级：
+
+| 等级 | 含义 | 数据来源 | 示例 |
+|------|------|----------|------|
+| **real** | 接真实 Protocol API | 生产后端 | startup-hub |
+| **demo** | 有独立后端但非协议链路 | demo 专用 API | ai-gig-market |
+| **shell** | 纯前端展示，无后端 | 静态/mock 数据 | 其他展示页 |
+
+**行为约束**: 文档和代码中声明的保真度必须与运行时实际行为一致。
+不得在文档中声称"真实协议"而代码跑 demo fallback（承诺 vs 现实漂移）。
+修改场景接入方式时，必须同步更新场景配置中的 fidelity 字段。

package/src/bollharness/scripts/context-fragments/truth-source-hierarchy.md

@@ -0,0 +1,15 @@
+## 真相源优先级
+
+你正在编辑核心文档。boll 的真相源有明确的优先级：
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | 运行中的代码 | 实际行为是最终真相 |
+| 2 | 数据库 schema + 测试 | 可执行的约束 |
+| 3 | ADR / TECH / PLAN 文档 | 设计决策记录 |
+| 4 | CLAUDE.md | 开发指导（派生自上层） |
+| 5 | MEMORY.md | 会话间记忆（最易过期） |
+
+**行为约束**: 当不同层级的信息冲突时，必须以高优先级来源为准并修正低优先级来源。
+CLAUDE.md 中的信息必须可以从代码或 ADR 中验证——不得包含无法溯源的断言。
+修改真相源文件时，必须检查下游是否需要同步更新。

package/src/bollharness/scripts/context-fragments/two-language.md

@@ -0,0 +1,15 @@
+## 两套语言体系
+
+你正在编辑面向用户的代码。协议术语和用户语言必须严格分离：
+
+**协议层**（仅开发者/文档可见）：
+formulation, crystallization, catalyst, nomination, intent field, operator, resonance
+
+**用户层**（UI/文案/帮助文本）：
+需求澄清, 多方协商, 协调, 推荐, 能力匹配
+
+**行为约束**: 前端 UI、用户提示、错误消息中不得出现协议内部术语。
+用户永远不需要知道"结晶"是什么——他们只知道"多方协商"。
+比喻：酒店管家不会跟客人说"我现在执行 housekeeping protocol"。
+
+禁词（用户可见文本）: "播种意图"、"共振"、"场域"、"结晶"等诗意表达。

package/src/bollharness/scripts/context-fragments/version-sources.md

@@ -0,0 +1,14 @@
+## 版本号来源清单
+
+你正在编辑版本相关文件。一个事实只允许有一个定义：
+
+| 版本号 | 权威来源 | 必须同步的位置 |
+|--------|----------|----------------|
+| MCP Python | `mcp-server/pyproject.toml` | CLAUDE.md 引用 |
+| MCP Node | `mcp-server-node/package.json` | 必须与 Python 版本一致 |
+| 后端 API | `backend/product/protocol/service.py` | /protocol 元数据返回 |
+| 前端 | `website/package.json` | 部署产物 BUILD_ID |
+
+**行为约束**: 修改任何版本号时，必须同步所有关联位置。
+Python MCP 和 Node MCP 版本号必须完全一致，不得出现 0.x.y vs 0.x.z 的漂移。
+"一个事实一个定义"——如果两个地方都写死版本号，其中一个必须是自动派生的。

package/src/bollharness/scripts/hooks/stop-evaluator.md

@@ -0,0 +1,83 @@
+# Stop Hook: Completion Proposal + Independent Review (ADR-044 §3.4 L3+L4)
+
+你**不是** Evaluator。你是被评估的一方。你的工作是：
+1. 写出你做了什么（proposal）
+2. 请一个独立 agent 来评你
+
+**禁止自己给自己打分。** 自评有结构性利益冲突（Anthropic: "Agents consistently overpraise their own work"）。
+
+## Step 1: 写 Completion Proposal
+
+将以下 JSON 写入 `.boll/state/completion-proposal.json`：
+
+```json
+{
+  "session_id": "<当前 session 标识>",
+  "timestamp": "<ISO 8601>",
+  "summary": "<1-3 句话描述本 session 做了什么>",
+  "files_changed": ["<从 git diff 或 risk-snapshot 获取>"],
+  "evidence": {
+    "tests_run": "<运行了哪些测试，结果如何>",
+    "verification_commands": ["<实际执行的验证命令>"],
+    "commits": ["<本 session 的 commit hash + message>"]
+  },
+  "known_limitations": ["<诚实列出已知的未完成项或风险>"],
+  "task_reference": "<TASK.md 路径或用户原始指令摘要>"
+}
+```
+
+**要求**：
+- `files_changed` 必须从 `git diff` 或 risk-snapshot 的 `files_touched` 取，**不得凭记忆列举**
+- `evidence` 中的测试结果必须是实际运行输出，不是"应该通过"
+- `known_limitations` 必须诚实 — 这是给 reviewer 的线索，不是给自己开脱
+
+## Step 2: Spawn 独立 Reviewer
+
+写完 proposal 后，**必须** spawn 一个独立审查 agent：
+
+```
+Agent({
+  subagent_type: "review-readonly",
+  description: "Completion review",
+  prompt: `你是独立的 Completion Reviewer（ADR-044 L4）。
+你的任务是验证 agent 的 completion proposal 是否与实际代码变更一致。
+
+读取 .boll/state/completion-proposal.json，然后：
+
+1. **Proposal vs Reality**：git diff 的实际变更是否与 proposal.files_changed 一致？有遗漏吗？
+2. **Evidence 可信度**：proposal.evidence 中声称的测试/验证，结果是否真实？
+3. **半成品检查**：变更文件中有没有 TODO/FIXME/HACK？有没有 dead code？
+4. **契约一致性**：如果改了 API/config/路由，所有引用处是否同步更新？
+5. **已知限制诚实度**：proposal.known_limitations 是否遗漏了明显风险？
+
+评分（每维 1-5，任何维 < 3 = FAIL）：
+- Completeness: proposal 是否覆盖所有实际变更
+- Honesty: evidence 和 limitations 是否真实
+- Quality: 代码变更本身的质量
+- Consistency: 跨文件/跨层的一致性
+
+输出格式：
+## Verdict: PASS / FAIL
+## Scores: Completeness X/5, Honesty X/5, Quality X/5, Consistency X/5
+## Findings: [具体发现列表]
+## Recommendation: [如果 FAIL，具体要修什么]`
+})
+```
+
+## Step 3: 根据 Reviewer 裁决行动
+
+- **Reviewer 说 PASS** → 你可以 Stop
+- **Reviewer 说 FAIL** → 按 Recommendation 修复，修复后再尝试 Stop
+- **Reviewer spawn 失败**（超时/权限等）→ 降级为 PreCompletionChecklist 自检（下方），但必须在输出中声明 "独立审查未执行，以下为自检降级"
+
+## 降级 Fallback: PreCompletionChecklist（仅当 reviewer 不可用时）
+
+如果因环境限制无法 spawn reviewer，执行以下自检：
+
+1. **Git 状态**: 所有新文件是否已 `git add`？是否有未保存的变更？
+2. **测试**: 如果有代码变更，相关测试是否通过？
+3. **文档一致性**: 代码变更是否需要更新文档？
+4. **无半成品**: 是否有 TODO/FIXME/HACK 被遗留？
+5. **契约一致性**: API 类型、路由路径、配置 key 是否在所有引用处一致？
+
+**但必须标注**：这是自检降级，不是独立审查。

package/src/bollharness/templates/scaffold/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+<!--
+  Auto-generated by bollharness installer.
+  This file is the primary instruction source for Claude Code sessions.
+  Edit freely — the installer will NOT overwrite an existing CLAUDE.md.
+-->
+
+## Project Overview
+
+<!-- TODO: 描述你的项目 — 做什么、技术栈、部署方式 -->
+
+## Governance System (bollharness)
+
+This project is managed by [bollharness](https://github.com/anthropics/bollharness) — an AI agent session governance framework. The following hooks and guards run automatically during Claude Code sessions.
+
+### Hook Lifecycle
+
+| Stage | Hook | What it does |
+|-------|------|-------------|
+| SessionStart | `session-start-reset-risk.ts` | Reset risk snapshot for new session |
+| SessionStart | `session-start-magic-docs.ts` | Load project-specific context documents |
+| SessionStart | `session-start-toolkit-reminder.ts` | Surface available skills and tools |
+| PreToolUse * | `tool-call-counter.ts` | Track tool call frequency for observability |
+| PreToolUse Bash | `deploy-guard.ts` | Block unauthorized deployments |
+| PreToolUse Bash | `auto-python3.ts` | Intercept bare `python` → `python3` |
+| PreToolUse Task | `review-agent-gatekeeper.ts` | Enforce read-only isolation on review agents |
+| PreToolUse Read\|Bash | `sanitize-on-read.ts` | Sanitize sensitive data in read output |
+| PostToolUse Edit\|Write | `guard-feedback.ts` | Context routing + guard checks (ADR-030) |
+| PostToolUse Edit\|Write | `loop-detection.ts` | Detect edit-undo-edit loops |
+| PostToolUse Edit\|Write | `risk-tracker.ts` | Update risk snapshot on file changes |
+| PreCompact | `precompact.sh` | Preserve critical context before compaction |
+| Stop | `stop-evaluator.ts` | Completion proposal + independent review |
+| SessionEnd | `session-reflection.ts` | Session summary and learnings |
+| SessionEnd | `trace-analyzer.ts` | Aggregate trace data for harness optimization |
+| SessionEnd | `deploy-progress-on-session-end.ts` | Persist deployment progress metrics |
+| PostToolUseFailure | `failure-analyzer.ts` | Diagnose tool call failures |
+
+### Runtime Directories
+
+```
+.boll/
+├── state/        # Risk snapshots, session state (gitignored)
+├── guard/        # Guard flags, injection dedup (gitignored)
+└── metrics/      # Observability data — JSONL event logs (gitignored)
+```
+
+These directories are **runtime-only** and gitignored. They are created automatically by hooks.
+
+## AI Behavioral Constraints
+
+### Language
+- All user-facing output in **simplified Chinese**; technical identifiers stay original
+- All commit messages **bilingual** (English title + Chinese summary)
+- Co-Authored-By header: `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`
+
+### Code Quality
+- All commands use `npx ts-node`, never bare `python`
+- Subagent model: review/audit/evaluator agents must use `claude-opus-4-6`
+- Review agents: tool whitelist must be schema-level isolated (no Edit/Write/Bash)
+
+### Workflow
+- **Issue-first**: create `docs/issues/guard-*.md` before fixing any guardian finding
+- **Verification honesty**: partial test pass ≠ full pass; closure needs evidence
+- **No half-finished work**: no TODO/FIXME left behind without tracking
+
+## Guardian Issue Workflow
+
+Guardian/red-team findings go to `docs/issues/*.md` with YAML frontmatter:
+
+```yaml
+---
+status: open          # open | fixed | wont_fix
+prevention_status: open  # open | closed
+mechanism_layer: guard   # guard | test | type | convention
+severity: P1          # P0 | P1 | P2 | P3
+component: path/to/affected/file
+---
+```
+
+Rules:
+- Never fix guardian issues directly on `main` — use a dedicated branch
+- Close only after verification is recorded with evidence
+
+## Path-Scoped Rules
+
+Path-scoped rules in `.boll/rules/*.md` auto-load when Claude reads files matching their trigger patterns. No manual loading needed.
+
+<!-- TODO: 列出你的 path-scoped rules 及触发路径 -->

package/src/cli-entry.ts

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * Bolloon CLI 入口
+ *
+ * 使用方式:
+ *   bolloon                    # 启动 GUI（Electron 或 Web）
+ *   bolloon --cli              # 启动命令行界面
+ *   bolloon --read <file>      # 读取文档
+ *   bolloon --summarize <file> # 总结文档
+ *   bolloon --web              # 启动 Web UI
+ *   bolloon --version          # 显示版本
+ */
+
+import { spawn } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+
+const isWindows = process.platform === 'win32';
+
+// ANSI 颜色
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+const GREEN = '\x1b[32m';
+const MAGENTA = '\x1b[35m';
+
+// 版本信息
+const VERSION = '0.1.1';
+
+function log(msg: string, color: string = RESET) {
+  console.log(`${color}${msg}${RESET}`);
+}
+
+function printBanner() {
+  console.log(`
+${CYAN}${BOLD}
+   ╔═══════════════════════════════════════════╗
+   ║      🤖 Bolloon Agent ${VERSION}              ║
+   ║      P2P AI Document Processor            ║
+   ╚═══════════════════════════════════════════╝${RESET}
+`);
+}
+
+function printHelp() {
+  console.log(`
+${BOLD}用法:${RESET}
+  bolloon [选项] [命令] [参数]
+
+${BOLD}选项:${RESET}
+  --gui, -g           启动图形界面 (Electron)
+  --web, -w           启动 Web UI (浏览器)
+  --cli, -c           启动命令行界面
+  --version, -v       显示版本信息
+  --help, -h          显示帮助信息
+
+${BOLD}命令:${RESET}
+  bolloon --read <file>           读取文档
+  bolloon --summarize <file>      总结文档
+  bolloon --improve <file> <req>  改进文档
+
+${BOLD}示例:${RESET}
+  bolloon                    # 启动图形界面
+  bolloon --web              # 启动 Web UI
+  bolloon --read 想法.md     # 读取文档
+  bolloon --cli              # 命令行模式
+
+${BOLD}环境变量:${RESET}
+  MINIMAX_API_KEY           MiniMax API 密钥
+  OPENAI_API_KEY            OpenAI API 密钥
+  ANTHROPIC_API_KEY         Anthropic API 密钥
+  PORT                      Web 服务端口 (默认 54188)
+`);
+}
+
+function getDistDir(): string {
+  // 对于打包后的应用，__dirname 是 dist 目录
+  return __dirname;
+}
+
+function getMainScript(): string {
+  const distDir = getDistDir();
+
+  // 检查 dist/index.js 是否存在
+  const indexPath = path.join(distDir, 'index.js');
+  if (fs.existsSync(indexPath)) {
+    return indexPath;
+  }
+
+  // 回退到源目录
+  const srcPath = path.join(process.cwd(), 'src', 'index.ts');
+  if (fs.existsSync(srcPath)) {
+    return path.join(process.cwd(), 'src', 'index.ts');
+  }
+
+  throw new Error('找不到入口脚本，请确保已执行 npm run build');
+}
+
+function getElectronPath(): string {
+  // 获取 electron 可执行文件路径
+  const electronPath = require('electron');
+  return electronPath;
+}
+
+// 解析命令行参数
+function parseArgs(): { mode: string; args: string[] } {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    return { mode: 'gui', args: [] };
+  }
+
+  const mode = args[0];
+
+  // 处理简写选项
+  switch (mode) {
+    case '-v':
+    case '--version':
+      return { mode: 'version', args: [] };
+    case '-h':
+    case '--help':
+      return { mode: 'help', args: [] };
+    case '-g':
+    case '--gui':
+      return { mode: 'gui', args: args.slice(1) };
+    case '-w':
+    case '--web':
+      return { mode: 'web', args: args.slice(1) };
+    case '-c':
+    case '--cli':
+      return { mode: 'cli', args: args.slice(1) };
+    default:
+      // 传递所有参数给主程序
+      return { mode: 'passthrough', args };
+  }
+}
+
+// 执行 Node.js 脚本
+async function runNodeScript(scriptPath: string, additionalArgs: string[]) {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(process.execPath, [scriptPath, ...additionalArgs], {
+      stdio: 'inherit',
+      env: { ...process.env }
+    });
+
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`进程退出，代码: ${code}`));
+      }
+    });
+  });
+}
+
+// 启动 Electron
+async function startElectron(additionalArgs: string[]) {
+  const electronPath = getElectronPath();
+  const distDir = getDistDir();
+
+  // 确定主进程入口
+  let mainPath = path.join(distDir, 'electron.js');
+  if (!fs.existsSync(mainPath)) {
+    mainPath = path.join(distDir, '..', 'src', 'electron.js');
+  }
+
+  if (!fs.existsSync(mainPath)) {
+    // 回退到开发模式
+    mainPath = path.join(process.cwd(), 'src', 'electron.ts');
+  }
+
+  log('启动 Electron...', CYAN);
+
+  const child = spawn(electronPath, [mainPath, ...additionalArgs], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: 'development' }
+  });
+
+  child.on('error', (err) => {
+    log(`Electron 启动失败: ${err.message}`, MAGENTA);
+    process.exit(1);
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}
+
+// 启动 Web 服务
+async function startWebServer(additionalArgs: string[]) {
+  log('启动 Web 服务...', CYAN);
+
+  try {
+    const mainPath = getMainScript();
+    const webArgs = ['--web', ...additionalArgs];
+
+    const child = spawn(process.execPath, [mainPath, ...webArgs], {
+      stdio: 'inherit',
+      env: { ...process.env }
+    });
+
+    child.on('error', (err) => {
+      log(`Web 服务启动失败: ${err.message}`, MAGENTA);
+      process.exit(1);
+    });
+
+    child.on('exit', (code) => {
+      process.exit(code || 0);
+    });
+  } catch (err: any) {
+    log(`启动失败: ${err.message}`, MAGENTA);
+    process.exit(1);
+  }
+}
+
+// 启动 CLI
+async function startCLI(additionalArgs: string[]) {
+  log('启动命令行界面...', CYAN);
+
+  try {
+    const mainPath = getMainScript();
+    const cliArgs = [...additionalArgs];
+
+    const child = spawn(process.execPath, [mainPath, ...cliArgs], {
+      stdio: 'inherit',
+      env: { ...process.env }
+    });
+
+    child.on('error', (err) => {
+      log(`CLI 启动失败: ${err.message}`, MAGENTA);
+      process.exit(1);
+    });
+
+    child.on('exit', (code) => {
+      process.exit(code || 0);
+    });
+  } catch (err: any) {
+    log(`启动失败: ${err.message}`, MAGENTA);
+    process.exit(1);
+  }
+}
+
+// 主入口
+async function main() {
+  const { mode, args } = parseArgs();
+
+  switch (mode) {
+    case 'version':
+      console.log(`Bolloon Agent v${VERSION}`);
+      break;
+
+    case 'help':
+      printHelp();
+      break;
+
+    case 'gui':
+      printBanner();
+      await startElectron(args);
+      break;
+
+    case 'web':
+      printBanner();
+      await startWebServer(args);
+      break;
+
+    case 'cli':
+      await startCLI(args);
+      break;
+
+    case 'passthrough':
+      // 传递所有参数给主程序
+      try {
+        const mainPath = getMainScript();
+        const child = spawn(process.execPath, [mainPath, ...args], {
+          stdio: 'inherit',
+          env: { ...process.env }
+        });
+
+        child.on('error', (err) => {
+          log(`执行失败: ${err.message}`, MAGENTA);
+          process.exit(1);
+        });
+
+        child.on('exit', (code) => {
+          process.exit(code || 0);
+        });
+      } catch (err: any) {
+        log(`执行失败: ${err.message}`, MAGENTA);
+        process.exit(1);
+      }
+      break;
+
+    default:
+      log(`未知模式: ${mode}`, MAGENTA);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});