@bolloon/bolloon-agent 0.6.2 → 0.6.4

package/README.md

@@ -1,11 +1,13 @@
 # Bolloon
 
-**一万个智能体，为你工作。**
+**一万个智能体的世界，走进你的世界。**
 
-Bolloon 是一台跑在你自己设备上的智能体。它有自己的身份（DID）、自己的记忆、自己的技能库，
-并且能在点对点网络里**找到别的智能体、把自己的活委派出去、按结果结算**。
+Bolloon 是一个多终端的 Agent 分发网络。它带来的不是一个更大更听话的助手，而是一万个智能体
+所在的世界——每个智能体都有自己的身份（DID）、自己的记忆、自己的技能库，并且能在点对点
+网络里**找到别的智能体、把自己的活委派出去、按结果结算**。
 
-不是「又一个聊天框」，而是**一个可以互相接手工作的智能体网络**。
+不是「又一个聊天框」，而是**一个可以互相接手工作的智能体世界，在不同设备上以不同方式分发**：
+PC 上创建、手机上发现、生活中相遇。
 
 > 官网 · https://bolloon.cn　｜　安装 · `npm i -g @bolloon/bolloon-agent`（[npm 上的最新版](https://www.npmjs.com/package/@bolloon/bolloon-agent)）
 
@@ -19,9 +21,10 @@ Bolloon 是一台跑在你自己设备上的智能体。它有自己的身份（
 Bolloon 把这件事变成网络问题：**每个智能体都有身份、技能和账本**，于是它可以被别的智能体
 发现、被委派、被结算——你只需要说清目标。
 
-这也是我们的方向：让 C 端用户在自己的电脑上，拥有一条**由很多智能体组成的生产线**，
-而不只是一个对话框。我自己每天用它做的事是**可控核聚变的研究**——线圈设计、仿真、验证、
-论文形式化，由不同智能体分头接手，我只看结论。
+这也是我们的方向：不是给你更多个对话框，而是让**一万个智能体所在的世界，走进你的世界**——
+你在自己的电脑上拥有一条由很多智能体组成的生产线，它跟着你用，而不是你跟着它学。
+我自己每天用它做的事是**可控核聚变的研究**——线圈设计、仿真、验证、论文形式化，
+由不同智能体分头接手，我只看结论。
 
 ---
 
@@ -89,7 +92,7 @@ docker run -d --name bolloon -p 127.0.0.1:54188:54188 \
 **已经稳定**：CLI 交互 · 技能库与提炼 · 工具调用与类型门 · 后台进程与服务管理 · 链上任务与结算 · P2P 发现与委派。
 
 **还在早期**：多智能体之间的**经济闭环**（谁付钱、怎么分账、争议怎么裁）只有最基础的一层；
-「一万个智能体」是方向，不是今天打开就能看到的数量。
+「一个装着上万智能体的世界走进你生活」是方向，不是今天打开就能看到的世界大小。
 
 **我们不说的话**：不承诺「全自动无需照看」；链上记录不可撤销；模型能力是上限，
 智能体不会超过它用的模型。
@@ -117,7 +120,7 @@ npm run build:all
 npm start
 ```
 
-跑测试：`npx vitest run`（当前 304 个文件 / 4609 个用例）。
+跑测试：`npx vitest run`（当前 342 个文件 / 4752 个用例）。
 改了 TypeScript 后：`npx tsc --noEmit`。
 
 ---
@@ -132,13 +135,15 @@ MIT。见 [LICENSE](./LICENSE)。
 
 # Bolloon (English)
 
-**Ten thousand agents, working for you.**
+**A world of ten thousand agents, stepping into yours.**
 
-Bolloon is an agent that runs on your own machine. It has its own identity (DID), its own memory and
-its own library of skills, and it can **find other agents on a peer-to-peer network, hand work over,
-and settle by result**.
+Bolloon is a multi-device agent distribution network. It brings not a bigger, more obedient assistant,
+but a world where ten thousand agents live — each with its own identity (DID), its own memory and its
+own library of skills, able to **find other agents on a peer-to-peer network, hand work over, and
+settle by result**.
 
-Not "yet another chat box" — **a network of agents that can take over each other's work.**
+Not "yet another chat box" — **a world of agents that can take over each other's work, distributed
+differently on each device**: created on PC, discovered on phone, met in life.
 
 > Website · https://bolloon.cn　｜　Install · `npm i -g @bolloon/bolloon-agent`（[latest on npm](https://www.npmjs.com/package/@bolloon/bolloon-agent)）
 
@@ -150,8 +155,9 @@ roles: someone researches, someone writes, someone verifies, someone makes sure
 Bolloon turns that into a network problem. Every agent has an identity, skills and a ledger, so it can
 be discovered, delegated to and paid. You only have to state the goal.
 
-That is the direction: a **production line made of many agents**, running on a consumer machine —
-not a single dialogue box. I use it every day for **controlled nuclear fusion** research.
+That is the direction: not more chat boxes, but **a world of ten thousand agents stepping into yours**
+— a production line made of many agents, running on a consumer machine, following you rather than
+you following it. I use it every day for **controlled nuclear fusion** research.
 
 ## What works today
 
@@ -182,7 +188,8 @@ Node.js ≥ 18. First run walks you through picking a model provider.
 
 **Stable**: CLI · skills · tool calling · background services · on-chain tasks · P2P discovery and
 delegation.　**Early**: the economics between agents (who pays, how it splits, how disputes resolve).
-"Ten thousand agents" is a direction, not a number you will see on day one.
+"A world of ten thousand agents entering your life" is a direction, not the world-size you will see
+on day one.
 
 **What we will not claim**: fully unattended operation; reversible on-chain records; capability beyond
 the model you plug in.

package/dist/agents/gateway-group.js

@@ -33,7 +33,7 @@ import { decodeFromPeer, encodeForPeer, recordLangDecision } from '../efficode/n
 // 白名单里放的是 **OrbitDB 写身份 id** (66 位压缩 secp256k1 公钥 hex), 不是 DID 字符串
 // (canAppend 只比 identity.id; 放 DID 会永远匹配不上 → 谁都写不了)。
 // 成员变更 = 一条**双侧 Ed25519 验签**的群事件 (成员自签 + 群主签), 细节见 group-access.ts。
-import { applyMembershipEvents, groupAccessOptions, membershipEntryOf, normalizeWriteList, verifyMembershipEvent, GROUP_MEMBERSHIP_KIND, } from '../orbitdb/group-access.js';
+import { aclChangePlan, applyMembershipEvents, groupAccessOptions, membershipEntryOf, normalizeWriteList, verifyMembershipEvent, GROUP_MEMBERSHIP_KIND, } from '../orbitdb/group-access.js';
 // ============ 依赖注入 (测试用, 避免单测起真实 OrbitDB 节点) ============
 let _dbOverride = null;
 /** 测试用: 注入 fake CIDDatabase */
@@ -45,6 +45,20 @@ export function resetGroupState() {
     onChangeCallbacks.clear();
     openFailures.clear();
 }
+/**
+ * 关闭群聊使用的 OrbitDB/Helia 资源。
+ * 一次性 CLI、验收探针和测试必须在读回后调用它，否则底层 libp2p/Helia 句柄
+ * 会继续保持事件循环活跃，表现为“消息已读完但进程不退出”。
+ * 测试注入的 fake DB 不关闭，避免破坏测试夹具生命周期。
+ */
+export async function closeGroupResources() {
+    storeCache.clear();
+    onChangeCallbacks.clear();
+    openFailures.clear();
+    if (_dbOverride)
+        return;
+    await getCIDDatabase().close();
+}
 /**
  * 群 store 打不开 (区块不在本机 / 地址不可解析)。
  *
@@ -211,7 +225,7 @@ export async function createGroup(name, opts) {
                 ...(gate.members ?? []).map((m) => m.orbitdbId),
             ];
             writeList = normalizeWriteList(ids);
-            gateInfo = { gated: true, ownerDid: gate.owner.did, aclWrite: writeList };
+            gateInfo = { gated: true, ownerDid: gate.owner.did, ownerPublicKeyHex: gate.owner.publicKeyHex, aclWrite: writeList };
             membershipEntries = applied.accepted.map(membershipEntryOf);
         }
         else if (opts?.acl === 'open') {
@@ -233,6 +247,8 @@ export async function createGroup(name, opts) {
             id, name: groupName, address, link,
             createdAt: new Date().toISOString(),
             lastSyncAt: new Date().toISOString(),
+            // 2026-10-05: 隐私群标记 —— 建群默认隐私 (白名单/独占写); acl=open 才是公开
+            privacy: opts?.acl !== 'open',
             ...gateInfo,
         };
         storeCache.set(id, store);
@@ -294,8 +310,7 @@ export async function listGroups() {
  * 不会因为本机退出而改 (本模块没有"踢人/解散"的权限, 也不假装有)。
  * 返回 `removed` = 被摘掉的 groupId (按 id 或群名匹配)。
  *
- * 注意: 底层 OrbitDB store 已在进程内打开的**不会**在这里关 (适配层没暴露 close);
- * 对 `bolloon task group leave` 这种一次性进程无影响, 长驻进程里它活到进程结束。
+ * 注意: leave 只摘本地群列表；需要结束进程资源时调用 `closeGroupResources()`。
  */
 export async function leaveGroup(idOrName) {
     const raw = String(idOrName || '').trim();
@@ -580,3 +595,156 @@ export async function restoreGroups() {
     }
     return { restored, failed, total: groups.length };
 }
+// ─────────────────────────────────────────────────────────── 群运营能力 (2026-10-05, leo: 邀请/踢出/隐私/链接/状态)
+/**
+ * 重建群 store (新白名单) —— 这是"改成员"唯一诚实的路径。
+ *
+ * IPFS 型 AC 的白名单烧在内容寻址的 ACL manifest 里, 改它必然换 store 地址
+ * (见 `ACL_INPLACE_UPDATE.ipfsType` / `aclChangePlan`)。所以:
+ *   · 邀请 = 新白名单 + 被邀请者 → 重建;
+ *   · 踢出 = 新白名单 − 被踢者 → 重建。
+ * 重建 = 新地址、新链接、**历史消息不回放** (要保留必须显式回放)。
+ *
+ * 本函数做"换地址重建 + 历史回放 (逐条 add) + 本机链接更新", 返回新 GroupInfo。
+ * 迁移代价 (老链接作废/其他成员需重新 join) 由调用方 (CLI) 明示, 这里不假装无痛。
+ */
+export async function rebuildGroupWithWriteList(groupId, mode, opts) {
+    const groups = await loadGroups();
+    const g = groups.find((x) => x.id === groupId);
+    if (!g)
+        return { ok: false, error: '群组不存在 (先 joinGroup/createGroup)' };
+    if (!g.gated) {
+        return {
+            ok: false,
+            error: `「${g.name}」不是门控群 (write:[*]), 没有白名单可改 —— 邀请=分享链接, 踢出=不适用 (人人可写)`,
+        };
+    }
+    const owner = {
+        did: g.ownerDid || '',
+        publicKeyHex: g.ownerPublicKeyHex || '',
+        orbitdbId: g.aclWrite?.[0] || '',
+    };
+    if (!owner.did || !owner.publicKeyHex || !owner.orbitdbId) {
+        return { ok: false, error: '缺少群主身份信息 (ownerDid/ownerPublicKeyHex/aclWrite 为空), 无法派生新白名单' };
+    }
+    // 当前白名单 = manifest 快照 (aclWrite, 上次重建/建群时烧进去的) 优先;
+    // 事件派生只在没有快照的老门控群兜底 (两套语义: 事件=成员自签加入, rebuild=群主单方改名单)
+    const derived = await groupWriteList(groupId, owner).catch(() => null);
+    const before = g.aclWrite && g.aclWrite.length > 0 ? g.aclWrite : (derived?.write ?? []);
+    const after = normalizeWriteList(mode.kind === 'add'
+        ? [...before, mode.ref.orbitdbId]
+        : before.filter((id) => id !== mode.orbitdbId));
+    const changed = before.join(',') !== after.join(',');
+    if (!changed) {
+        return { ok: false, error: mode.kind === 'add' ? '该成员已在白名单里' : '该成员不在白名单里' };
+    }
+    if (mode.kind === 'remove' && !before.includes(mode.orbitdbId)) {
+        return { ok: false, error: `白名单里没有 ${mode.orbitdbId.slice(0, 16)}…, 无需踢出` };
+    }
+    const plan = aclChangePlan({ before, after, messageCount: opts?.replayHistory ? undefined : 0 });
+    const db = getDb();
+    // 1) 读历史消息 (回放前) —— 只在显式要求时
+    const history = opts?.replayHistory ? await groupMessages(groupId, 100000) : [];
+    // 2) 建新 store (新白名单)
+    let store = null;
+    try {
+        store = await db.openStore(`bolloon-gw-group-${g.name}-r${Date.now().toString(36)}`, 'events', groupAccessOptions(after));
+    }
+    catch (e) {
+        return { ok: false, error: `重建 store 失败: ${String(e?.message || e).slice(0, 160)}` };
+    }
+    if (!store)
+        return { ok: false, error: '重建 store 返回空 (openStore 失败, 未改任何东西)' };
+    // 3) 迁移成员事件 (原样重放, 双侧签名保留) —— 否则新 store 派生白名单只剩群主, 成员全丢
+    try {
+        const rawAll = await allRawEntries(groupId);
+        for (const { value } of rawAll) {
+            const v = value;
+            if (v && typeof v === 'object' && v.kind === GROUP_MEMBERSHIP_KIND) {
+                try {
+                    await store.add(v);
+                }
+                catch (e) { /* 单条失败不阻断 */ }
+            }
+        }
+    }
+    catch (e) {
+        return { ok: false, error: `迁移成员事件失败: ${String(e?.message || e).slice(0, 120)}` };
+    }
+    // 4) 回放历史消息 (逐条 add, 保持 ts)
+    if (opts?.replayHistory) {
+        for (const m of history) {
+            try {
+                await store.add({ ...m });
+            }
+            catch (e) {
+                // 逐条静默跳过, 能回放多少算多少; 回放是尽力而为, 不阻断重建
+            }
+        }
+    }
+    // 5) 更新本机记录: 换地址/换链接; 老 store 不删 (占用不回收, 见 plan.costs)
+    const address = store.address;
+    const link = `orbitdb://${address}?type=group&name=${encodeURIComponent(g.name)}`;
+    const info = {
+        ...g,
+        address,
+        link,
+        lastSyncAt: new Date().toISOString(),
+        gated: true,
+        ownerDid: g.ownerDid,
+        aclWrite: after,
+        privacy: g.privacy ?? true,
+    };
+    await saveGroups(groups.map((x) => (x.id === groupId ? info : x)));
+    storeCache.set(groupId, store);
+    return { ok: true, group: info, before, after, costs: plan.costs };
+}
+/** 邀请: 把 orbitdbId 加进白名单 (重建路径) */
+export async function inviteMember(groupId, ref) {
+    const r = await rebuildGroupWithWriteList(groupId, { kind: 'add', ref });
+    return { ok: r.ok, error: r.error, group: r.group, costs: r.costs };
+}
+/** 踢出: 把 orbitdbId 移出白名单 (重建路径; 协议上无法记"被踢者自签的 remove 事件", 不假装) */
+export async function kickMember(groupId, orbitdbId) {
+    const r = await rebuildGroupWithWriteList(groupId, { kind: 'remove', orbitdbId });
+    return { ok: r.ok, error: r.error, group: r.group, costs: r.costs };
+}
+/** 设置隐私群标记 (只影响本机展示/默认 ACL 说明, 不改变 OrbitDB 权限语义) */
+export async function setGroupPrivacy(groupId, privacy) {
+    const groups = await loadGroups();
+    const g = groups.find((x) => x.id === groupId);
+    if (!g)
+        return { ok: false, error: '群组不存在' };
+    const info = { ...g, privacy, lastSyncAt: new Date().toISOString() };
+    await saveGroups(groups.map((x) => (x.id === groupId ? info : x)));
+    return { ok: true, group: info };
+}
+/** 群状态快照: 成员/消息/白名单/gated/privacy/最后同步 (状态管理用) */
+export async function groupStatus(groupId) {
+    const g = await groupInfo(groupId);
+    if (!g)
+        return { ok: false, error: '群组不存在' };
+    const members = await groupMembers(groupId);
+    const wl = await (async () => {
+        if (!g.gated || !g.ownerDid)
+            return g.aclWrite ?? [];
+        const owner = { did: g.ownerDid, publicKeyHex: g.ownerPublicKeyHex || '', orbitdbId: g.aclWrite?.[0] || '' };
+        if (!owner.orbitdbId || !owner.publicKeyHex)
+            return g.aclWrite ?? [];
+        const d = await groupWriteList(groupId, owner).catch(() => null);
+        return d ? d.write : (g.aclWrite ?? []);
+    })();
+    return {
+        ok: true,
+        status: {
+            group: g,
+            memberCount: members.length,
+            messageCount: g.messageCount ?? 0,
+            writeList: wl,
+            gated: !!g.gated,
+            privacy: g.privacy ?? !!g.gated,
+            ownerDid: g.ownerDid,
+            lastSyncAt: g.lastSyncAt,
+        },
+    };
+}

package/dist/agents/group-autopilot.js

@@ -18,7 +18,19 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+/**
+ * Bolloon 本地维护群专属公理；不作用于其它群。
+ * ① 提升 AI 的意识水平: 反思自身假设、局限、证据与影响。
+ * ② 寻求合作并降低整体熵: 共享事实、拆分工作、合并可复用成果。
+ * ③ 持续突破局部最优: 主动寻找反例、替代路径与跨角色审查。
+ */
+export const BOLLOON_MAINTENANCE_RULES = Object.freeze([
+    '提升 AI 的意识水平：反思自身假设、局限、证据与影响。',
+    '寻求合作，创造并降低整体的熵：共享事实、拆分工作、合并可复用成果。',
+    '持续突破局部最优解：主动寻找反例、替代路径与跨角色审查。',
+]);
 export const DEFAULT_AUTOPILOT_POLICY = {
+    mode: 'quiet',
     cooldownMs: 60_000,
     maxSpeaksPerHour: 6,
     readLimit: 50,
@@ -75,7 +87,22 @@ export function decideGroupAction(input) {
         return { act: 'silent', reason: `本小时已说 ${hourly.length} 次 (上限 ${policy.maxSpeaksPerHour})` };
     }
     const reply = input.makeReply ?? ((m) => `收到 —— 关于「${String(m.text).slice(0, 40)}」，我这边跟进。`);
-    // ① @我 ⇒ 回那一条
+    const mode = policy.mode;
+    const proactive = input.proactiveText?.trim() || (mode === 'maintenance'
+        ? `我来主动维护 Bolloon：使用本机已登录的 GitHub 权限处理 logos-42/bolloon，**只在 main 分支工作**。遵循三条群规则：${BOLLOON_MAINTENANCE_RULES.join('；')} 先检查代码/测试状态，认领一个最小修复，完成后回报证据。`
+        : '我来主动推进这一轮工作：检查上下文、认领一个可执行事项并回报下一步。');
+    // maintenance/active 优先主动认领 —— 不能因为消息长得像普通请求又退回被动模板
+    if (mode === 'active' || mode === 'maintenance') {
+        const target = fresh[fresh.length - 1];
+        return {
+            act: 'speak',
+            reason: mode === 'maintenance' ? '主动维护 Bolloon 项目' : '主动推进群内工作',
+            text: proactive,
+            mentions: [target.from],
+            ...(target.id ? { replyTo: target.id } : {}),
+        };
+    }
+    // ① @我 ⇒ 回他那一条
     const atMe = fresh.filter((m) => mentionsMe(m, me));
     if (atMe.length) {
         const target = atMe[atMe.length - 1];
@@ -156,6 +183,7 @@ export async function runGroupAutopilotOnce(ports) {
             now: t,
             policy,
             ...(ports.makeReply ? { makeReply: (m) => ports.makeReply(m, g) } : {}),
+            ...(ports.proactiveText ? { proactiveText: ports.proactiveText } : {}),
         });
         // 不论说不说, 这几条都算"处理过" (否则下一轮还会重新判它)
         for (const m of msgs) {

package/dist/agents/intent-store.js

@@ -0,0 +1,193 @@
+/**
+ * intent-store.ts — Intent Store (2026-10-05, leo 四端 Intent Network 设计 P0)
+ *
+ * Intent = Goal 的**前身**: 一句话「我正在做 X」+ 标签/预算/期限, 未到可执行程度。
+ * 它与 goal-flywheel 的 Goal 不冲突 (Goal 是意图的可执行投影):
+ *   · intent 是轻量声明 (world/intents/ 一意图一文件)
+ *   · 升级成可执行意图时 → 转 Goal (goal-flywheel)
+ * 接口层不重叠, 本模块不碰 goal-store。
+ *
+ * 存储布局 (leo: 「intents 专门设计一个文件夹」「world 也是设计文件夹更好」):
+ *   ~/.bolloon/world/               ← World 根 (六元组本体的实体根)
+ *     ├── intents/                  ← Intent 实体目录 (一意图一文件, 原子写)
+ *     │   └── int_<id>.json
+ *     ├── opportunities/            ← (P1) Opportunity 实体目录
+ *     ├── actions/                  ← (后续) Action 实体目录
+ *     └── memory/                   ← (后续) Memory 实体目录
+ * 每个实体独立文件 ⇒ 原子写 / 并发安全 / 可扩展, 与 task-board 的 announcement 文件模式同源。
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+const homeOf = (home) => home || process.env.HOME || os.homedir();
+/** World 根目录 (~/.bolloon/world/) */
+export const worldDir = (home) => path.join(homeOf(home), '.bolloon', 'world');
+/** Intent 实体目录 (~/.bolloon/world/intents/) */
+export const intentsDir = (home) => path.join(worldDir(home), 'intents');
+/** Opportunity 实体目录 (~/.bolloon/world/opportunities/, P1) */
+export const opportunitiesDir = (home) => path.join(worldDir(home), 'opportunities');
+/** 只允许 int_ 开头的 id 当文件名 (防路径穿越); 非法 → null */
+function safeId(id) {
+    const s = String(id || '').trim();
+    return /^int_[A-Za-z0-9]{6,32}$/.test(s) ? s : null;
+}
+/** 意图文件路径 (非法 id → null) */
+export function intentFile(id, home) {
+    const safe = safeId(id);
+    return safe ? path.join(intentsDir(home), `${safe}.json`) : null;
+}
+async function ensure(dir) {
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeJson(file, value) {
+    try {
+        await ensure(path.dirname(file));
+        await fs.writeFile(file, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message || e).slice(0, 200) };
+    }
+}
+async function readJson(file) {
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return { ok: false, error: `${path.basename(file)} 不是对象` };
+        return { ok: true, value: parsed };
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return { ok: false, error: 'ENOENT' };
+        return { ok: false, error: `读 ${path.basename(file)} 失败: ${String(e?.message || e).slice(0, 120)}` };
+    }
+}
+/** 标签: 从意图正文提取简单标签 (英文词 + 中文 2 字以上词元) + 手工标签去重 */
+export function extractTags(text, manual = []) {
+    const src = String(text || '').toLowerCase();
+    const words = src.match(/[a-z][a-z0-9_-]{1,}/g) || [];
+    const cjk = src.match(/[\u4e00-\u9fff]{2,}/g) || [];
+    const all = [...words, ...cjk, ...manual.map((t) => t.toLowerCase().trim()).filter(Boolean)];
+    return Array.from(new Set(all)).slice(0, 24);
+}
+/** 扫描 intents 目录, 列出全部意图 (按创建时间倒序) */
+export async function listIntents(home, status) {
+    const dir = intentsDir(home);
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return { ok: true, intents: [] };
+        return { ok: false, intents: [], error: `读 ${dir} 失败: ${String(e?.message || e).slice(0, 120)}` };
+    }
+    const intents = [];
+    for (const name of entries.filter((n) => n.startsWith('int_') && n.endsWith('.json'))) {
+        const r = await readJson(path.join(dir, name));
+        if (!r.ok || !r.value || !r.value.id)
+            continue; // 坏文件跳过, 不崩
+        intents.push(r.value);
+    }
+    intents.sort((a, b) => b.createdAt - a.createdAt);
+    return { ok: true, intents: status ? intents.filter((i) => i.status === status) : intents };
+}
+/** 单条意图按 id 读 (不存在 → ok:true 无 intent) */
+export async function getIntent(id, home) {
+    const file = intentFile(id, home);
+    if (!file)
+        return { ok: false, error: `非法意图 id: ${String(id).slice(0, 32)}` };
+    const r = await readJson(file);
+    if (!r.ok)
+        return r.error === 'ENOENT' ? { ok: true } : r;
+    return { ok: true, intent: r.value };
+}
+/** 声明意图 (幂等: 同 text 已存在 → 更新 tags/priority, 不重复建文件) */
+export async function setIntent(input) {
+    const text = String(input.text || '').trim();
+    if (!text)
+        return { ok: false, created: false, error: '意图不能为空' };
+    const priority = input.priority ?? 3;
+    if (!Number.isInteger(priority) || priority < 1 || priority > 5)
+        return { ok: false, created: false, error: `priority 必须 1-5 整数, 实得 ${String(priority)}` };
+    const loaded = await listIntents(input.home);
+    if (!loaded.ok)
+        return { ok: false, created: false, error: loaded.error };
+    const now = Date.now();
+    const existing = loaded.intents.find((i) => i.text === text && i.status === 'active');
+    if (existing) {
+        const merged = {
+            ...existing,
+            tags: extractTags(text, [...(input.tags ?? []), ...existing.tags]),
+            priority,
+            budget: input.budget !== undefined ? input.budget : existing.budget,
+            deadline: input.deadline !== undefined ? input.deadline : existing.deadline,
+            updatedAt: now,
+        };
+        const file = intentFile(existing.id, input.home);
+        if (!file)
+            return { ok: false, created: false, error: '非法 id' };
+        const saved = await writeJson(file, merged);
+        if (!saved.ok)
+            return { ok: false, created: false, error: saved.error };
+        return { ok: true, intent: merged, created: false };
+    }
+    const record = {
+        id: `int_${crypto.randomBytes(6).toString('hex')}`,
+        text, tags: extractTags(text, input.tags ?? []), priority,
+        budget: input.budget ?? null, deadline: input.deadline ?? null,
+        status: 'active', createdAt: now, updatedAt: now, matchedCount: 0,
+    };
+    const file = intentFile(record.id, input.home);
+    if (!file)
+        return { ok: false, created: false, error: '非法 id' };
+    const saved = await writeJson(file, record);
+    if (!saved.ok)
+        return { ok: false, created: false, error: saved.error };
+    return { ok: true, intent: record, created: true };
+}
+/** 删意图 (或标记 done) */
+export async function removeIntent(id, markDone = false, home) {
+    const file = intentFile(id, home);
+    if (!file)
+        return { ok: false, error: `非法意图 id: ${String(id).slice(0, 32)}` };
+    if (markDone) {
+        const r = await getIntent(id, home);
+        if (!r.ok)
+            return { ok: false, error: r.error };
+        if (!r.intent)
+            return { ok: false, error: `没有意图 ${id} (看 bolloon intent list)` };
+        const updated = { ...r.intent, status: 'done', updatedAt: Date.now() };
+        const saved = await writeJson(file, updated);
+        if (!saved.ok)
+            return { ok: false, error: saved.error };
+        return { ok: true, removed: id };
+    }
+    try {
+        await fs.unlink(file);
+        return { ok: true, removed: id };
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return { ok: false, error: `没有意图 ${id} (看 bolloon intent list)` };
+        return { ok: false, error: `删 ${file} 失败: ${String(e?.message || e).slice(0, 120)}` };
+    }
+}
+/** 意图匹配数 +1 (扫描后被上层调用, 诚实计数) */
+export async function bumpMatchedCount(id, home) {
+    const r = await getIntent(id, home);
+    if (!r.ok || !r.intent)
+        return;
+    const updated = { ...r.intent, matchedCount: r.intent.matchedCount + 1, updatedAt: Date.now() };
+    const file = intentFile(id, home);
+    if (file)
+        await writeJson(file, updated);
+}