文档

照着做完大约 15 分钟。每一步都写清「你会看到什么」,看到的东西不一样就先别往下走。

1. 装(Node.js 18 以上)

   npm i -g @bolloon/bolloon-agent

   看到什么:命令正常结束,没有红色报错。

2. 确认装上了

   bolloon --version

   看到什么:打印一个版本号。若提示 command not found,看下面「排障」第一条。

3. 第一次启动(会进配置向导)

   bolloon

   看到什么:向导依次问你用哪家模型、要密钥。密钥只会写到本机 ~/.bolloon/llm-config.json,不会进任何仓库。

4. 确认模型通

   bolloon setup --test

   看到什么:连通性测试通过。这里不过,后面一定会失败——先修它。

5. 说第一个目标

   把 README 里过期的命令改成现在能跑的,改完把每条命令真跑一遍

   看到什么:一行行「这一步在做什么」(例如 🔧 查看 git 状态 · git_status 327ms),不是一屏思维流。它会自己拆步骤、自己挑工具。

6. 看它干完了什么

   /trace

   看到什么:这一步在做什么的执行记录。最后一行的「📚 复盘」是它这一轮真正学到的东西。

7. 在浏览器里看同一个会话

   bolloon --web

   看到什么:本机 54188 端口打开一个面板,和终端里是同一份状态,不是另一个东西。

这一节解释「为什么它会那样表现」。想直接干活可以跳到 ③;想改代码建议老实读完这一节。

一句话定义

Bolloon 是一个多终端的 Agent 分发网络:它带来的不是一个更大更听话的助手,而是一万个智能体所在的世界,走进你的世界——PC 上创建、手机上发现;每台机器跑一个实例,自动积累你的判断力,跨机器互通,不需要中心服务器。

1 · 启动时发生了什么

1. 装配身份与人格

   系统提示词按层装配(身份 / 人格 / 渠道 / 工具纪律),所以同一个模型在不同渠道里说话方式不一样。

2. 加载技能库与记忆

   技能(可复用的做法)与记忆(会话与长期事实)先就位——它一开始就知道自己会什么、以前踩过什么坑。

3. 启动节点与发现

   拿到自己的身份,接上点对点网络,开始发现别的节点。这一步是并发的,所以启动面板上的步骤编号偶尔不按顺序出现。

2 · 你说一句话之后:Goal → Run → Checkpoint

它内部把「长期意图」和「一次执行」分开:Goal 是你想要的结果(能跨很多天),Run 是其中一次执行(有开始有结束)。这个划分是它能「睡一觉接着干」的原因。

目标 → 判断下一步 → 自主决定节奏 → 执行或派遣 → 监控阻塞 → 注入新要求
     → 汇总结果 → 写进记忆 → 形成技能改进候选 → 下一次直接用

这条链的判据只有一条:下一次是不是真的更容易、更省。「继续运行」本身不算进展。

3 · Run 的状态机(为什么它不会假装在跑)

每次执行的合法状态是有限的,非法迁移一律拒绝——所以不会出现「偷偷回到正在跑」这种假状态。

4 · 什么时候它会停下来问你

不可逆的动作它不替你做主:发布、删除、动生产环境、花钱。它会停下给选项,你用 /approve 或 /reject 回答。另外「模型说完成了」不等于「系统确认完成」——完成要有证据(命令退出码、测试、读回的文件内容),没有证据的完成会继续查。

5 · 上下文、记忆、技能:它凭什么越用越省

6 · 网络、身份与钱

它有自己的身份(不是你的账号),可以接进点对点网络被别的节点找到、按能力接活、干完按结果结算。接进来的方式见「网关」页;钱的部分是链上任务与微支付信息,今天只做到最基础一层。

7 · 数据都在哪

本机优先:所有会话、记忆、技能、日志默认都在 ~/.bolloon/ 下,不上传;密钥单独放在 llm-config.json。具体路径见 ④ 参考。

每条都是「想干什么 → 敲什么 → 看到什么」。命令都能一键复制。

换模型或加一家供应商

1. bolloon model

   看当前供应方与模型,并在终端里直接换(进一个可选列表)

2. bolloon model key deepseek

   给某一家写密钥(deepseek / openai / anthropic / gemini)

3. 写完之后跑 bolloon setup --test 复测连通性;配置落在 ~/.bolloon/llm-config.json。

把它接进点对点网络

1. 接进来之后,别的节点可以按能力找到它、把活派给它;它自己也能委派出去。

2. 打开网关页看接入命令、网络现状与口径。

让长活离开现场自己跑

1. /goal 把这一章写完并自检;写不动就先把缺口列出来

   立一个能跨很久的目标,它会分次推进

2. /queue

   看排队的活

3. /runs

   看每一轮执行的状态(done / failed / stalled / needs_human …)

4. /session

   会话历史

5. 关掉终端不等于停:后台任务与服务的台账在 ~/.bolloon/processes.json,重启后会恢复并对活。

看它到底在干什么

1. /trace

   这一步在做什么(执行记录, 代替思维流)

2. tail -f ~/.bolloon/logs/tool-calls.jsonl

   每一次工具调用:名称、参数摘要、耗时

3. tail -f ~/.bolloon/logs/experience-review.log

   每轮复盘的过程与结果

安全边界:什么时候它会停下来

1. 不可逆的动作(发布、删除、动生产、花钱)它会停下来给选项,不替你做主。

2. /approve

   同意继续

3. /reject

   拒绝,并说明为什么

4. 改代码与写文件另有类型门与写入门:它不会用「命令跑完了」当「活干好了」。

出问题了先跑这三条

1. bolloon setup status

   看配置与连通性状态

2. bolloon setup --test

   复测模型连通性

3. BOLLOON_VERBOSE=1 bolloon

   带详细日志启动,日志落在 ~/.bolloon/logs/

4. 更多症状对照见 ④ 参考里的排障表。

备份 / 搬到另一台机器

1. 整个数据目录就是你的全部状态(会话、记忆、技能、日志、身份)。

2. cp -a ~/.bolloon ~/bolloon-backup-$(date +%F)

   整目录复制一份(含密钥文件,注意保管)

3. 新机器上:装同一个包,把目录放回 ~/.bolloon,再跑 bolloon setup --test。

在另一台机器上跑第二个实例

1. 同一台机器上重复安装即可拿到第二个身份;两台机器之间会自动发现彼此。

2. 各自的数据目录互不干扰;要看清对方在做什么,用 /net 或网关页。

终端命令

会话里的指令

环境变量

文件与端口

排障对照

这一节写给要改代码、要发布、要维护这份文档的人:架构在哪、怎么验、怎么发,以及这份文档自己是怎么被生产出来的。

1 · 架构与目录

2 · 本地开发

3 · 这个项目怎么定义「全绿」

测试通过只是其中一条。这六条同时成立才叫全绿——它写在项目自己的运行协议里:

1. 每个在跑的执行都处在合法状态(状态机校验通过)。

2. 没有幽灵「正在跑」:启动对账加失速巡检兜住。

3. 每个执行都能回答:目标是什么、做到哪、下一步是谁做什么、为什么停。

4. 失败必须有恢复决定,并留下痕迹。

5. 重启之后能恢复目标、检查点与约束。

6. 终端与网页显示同一份状态(同一个接口,不是两套)。

4 · 验收门的规矩

5 · 发布

1. 全量测试先绿,再改版本号(顺序不能反)。

2. 改 package.json 与 lock 两处版本号,提交。

3. 发布到 npm,等注册表放行(大包可能要十几分钟)。

4. 回读校验:版本、下载校验和逐字比对,别只信「发布命令退出了 0」。

5. 打标签、发 Release,并把这一版写进项目 wiki 的日志。

6 · 工作方式:先共识,再代码

这个仓库默认不是「先写代码」,而是原始资料 → 编译成 wiki 共识 → 再落到代码;改完代码要回写 wiki,否则算没做完。所以你会看到 docs/wiki 里同一件事既有设计稿也有事后验收报告——那是它的工作留痕,不是冗余。

7 · 这份文档是怎么做出来的

今天的三个例子:锚点门是在发现四个死链之后加的;溢出两条门是在量到顶栏把页面挤出 155 像素之后加的;复制按钮那条门不只看按钮在不在,还会真的点一次、从剪贴板读回来比对。

项目自己的共识库(设计与验收报告)都在仓库里,想往深走看这里: