@bolloon/bolloon-agent 0.3.27 → 0.3.28

package/dist/agents/decision-store.js

@@ -0,0 +1,247 @@
+/**
+ * decision-store.ts — 决策协议 (Context OS §7, 2026-08-03)
+ *
+ * Context OS 原则: 重要决策不允许只写结论, 至少要留下可回滚的推理链.
+ * 9 要素:
+ *   1. 问题到底是什么            → problem
+ *   2. 有哪些选项, 包括"不做"     → options[].label (includeDoNothing)
+ *   3. 每个选项的时间/金钱/精力/机会成本 → options[].costs
+ *   4. 每个选项的短期/长期收益和战略价值 → options[].benefits
+ *   5. 风险、概率、影响、是否可恢复       → options[].risks
+ *   6. 当前的信息缺口             → infoGaps
+ *   7. 推荐方案                  → recommendation
+ *   8. 为什么是现在               → timing
+ *   9. 失败时的触发条件和回滚动作   → rollback
+ *
+ * 防止三类错误: 把一时情绪当判断 / 因一条新信息推翻整个项目 / 把不能回滚的重投入当"勇敢".
+ * 原则: 新信息只修改它真正证伪的那个假设; 其他部分默认不动.
+ *
+ * 设计 (减法, 同 plan-store):
+ *   - 不建数据库. 落盘 = ~/.bolloon/decisions/<decisionId>.json
+ *   - 工具入口在 pi-sdk-tools.ts 注册, 复用现有 LLM 调度.
+ *   - 任何 IO 失败静默返回 error 对象, 不阻塞主对话.
+ *   - 决策确认 (decideDecision) 后自动 reflect 到 judgeness:
+ *     HumanJudgment (storeHumanJudgment, source=trajectory) + JudgenessDescription
+ *     (reflectAfterJudgment, openState=locked → Context OS 阶段0 临时价值点).
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+// ============================================================
+// 落盘路径
+// ============================================================
+export function getDecisionsDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'decisions');
+}
+export function getDecisionPath(decisionId, home = os.homedir()) {
+    return path.join(getDecisionsDir(home), `${decisionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+export function sanitizeDecisionId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+export async function createDecision(input, home) {
+    const problem = String(input.problem || '').trim();
+    if (!problem)
+        return { ok: false, error: 'problem 必填 (问题到底是什么)' };
+    const options = Array.isArray(input.options)
+        ? input.options
+            .map((o) => ({
+            label: String(o.label || '').trim(),
+            includeDoNothing: !!o.includeDoNothing,
+            costs: String(o.costs || ''),
+            benefits: String(o.benefits || ''),
+            risks: String(o.risks || ''),
+        }))
+            .filter((o) => o.label)
+        : [];
+    if (options.length === 0)
+        return { ok: false, error: 'options 至少 1 个选项 (含"不做")' };
+    const now = new Date().toISOString();
+    const decisionId = `dec_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+    const decision = {
+        decisionId,
+        problem,
+        options,
+        infoGaps: String(input.infoGaps || ''),
+        recommendation: String(input.recommendation || ''),
+        timing: String(input.timing || ''),
+        rollback: String(input.rollback || ''),
+        context: {
+            domain: String(input.domain || '通用'),
+            stakes: input.stakes || 'medium',
+            by: input.by || 'agent',
+            originChannel: String(input.originChannel || ''),
+        },
+        status: 'draft',
+        createdAt: now,
+        updatedAt: now,
+    };
+    try {
+        const dir = getDecisionsDir(home);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(getDecisionPath(decisionId, home), JSON.stringify(decision, null, 2), 'utf-8');
+        return { ok: true, decision };
+    }
+    catch (e) {
+        return { ok: false, error: `写入失败: ${e?.message || String(e)}` };
+    }
+}
+export async function loadDecision(decisionId, home) {
+    try {
+        const raw = await fs.readFile(getDecisionPath(decisionId, home), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function saveDecision(decision, home) {
+    decision.updatedAt = new Date().toISOString();
+    await fs.writeFile(getDecisionPath(decision.decisionId, home), JSON.stringify(decision, null, 2), 'utf-8');
+}
+export async function updateDecisionStatus(decisionId, input, opts = {}) {
+    const decision = await loadDecision(decisionId, opts.home);
+    if (!decision)
+        return { ok: false, error: `decision '${decisionId}' 不存在` };
+    const now = new Date().toISOString();
+    if (input.decide) {
+        if (input.recommendation && input.recommendation.trim()) {
+            decision.recommendation = String(input.recommendation).trim();
+        }
+        if (!decision.recommendation)
+            return { ok: false, error: 'recommendation 必填 (推荐方案)' };
+        decision.status = 'decided';
+        decision.decidedAt = now;
+        // 决策确认 → 自动 reflect 到 judgeness (Context OS 阶段0 入账)
+        const refl = await reflectDecisionToJudgeness(decision, opts.byAgentId);
+        if (!refl.ok) {
+            return { ok: false, error: `决策确认失败 (judgeness 入库): ${refl.error}` };
+        }
+        decision.reflection = refl.reflection;
+    }
+    else if (input.implemented) {
+        if (decision.status !== 'decided' && decision.status !== 'implemented') {
+            return { ok: false, error: '只能把 decided 的决策标记为 implemented' };
+        }
+        decision.status = 'implemented';
+    }
+    else if (input.rollback || input.abandon) {
+        decision.status = input.rollback ? 'rolled-back' : 'abandoned';
+        // 回滚/放弃 → 教训入库 (reject 语义, 防重复踩坑)
+        const reason = String(input.reason || '');
+        if (reason && input.rollback) {
+            await reflectRollbackLesson(decision, reason, opts.byAgentId).catch(() => { });
+        }
+    }
+    else {
+        return { ok: false, error: '必须指定 decide / implemented / rollback / abandon 之一' };
+    }
+    await saveDecision(decision, opts.home);
+    return { ok: true, decision };
+}
+export async function listDecisions(status, home) {
+    try {
+        const dir = getDecisionsDir(home);
+        const files = await fs.readdir(dir);
+        const out = [];
+        for (const f of files) {
+            if (!f.endsWith('.json'))
+                continue;
+            try {
+                const raw = await fs.readFile(path.join(dir, f), 'utf-8');
+                const d = JSON.parse(raw);
+                if (status && d.status !== status)
+                    continue;
+                out.push(d);
+            }
+            catch { /* 单文件损坏跳过 */ }
+        }
+        out.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** 决策摘要 → 上下文注入 (9 要素完整可追溯, 上下文只给精简版) */
+export function decisionToContext(d) {
+    const lines = [`📌 ${d.problem} [${d.status}] (id=${d.decisionId})`];
+    for (const o of d.options) {
+        const tag = o.includeDoNothing ? ' [不做]' : '';
+        lines.push(`  - 选项${tag}: ${o.label}`);
+    }
+    if (d.recommendation)
+        lines.push(`  推荐: ${d.recommendation}`);
+    if (d.infoGaps)
+        lines.push(`  信息缺口: ${d.infoGaps}`);
+    if (d.rollback)
+        lines.push(`  回滚条件: ${d.rollback}`);
+    if (d.reflection)
+        lines.push(`  ✅ 已入库 judgeness: hv=${d.reflection.hvId}${d.reflection.jdId ? ` jd=${d.reflection.jdId}` : ''}`);
+    return lines.join('\n');
+}
+/** 决策确认后入库: HumanJudgment (source=trajectory) + reflectAfterJudgment (openState=locked) */
+export async function reflectDecisionToJudgeness(decision, byAgentId) {
+    try {
+        const { storeHumanJudgment } = await import('../pi-ecosystem-judgment/human-value-store.js');
+        const { reflectAfterJudgment } = await import('../judgeness/reflect.js');
+        const decisionText = `${decision.recommendation} (问题: ${decision.problem})`;
+        const judgment = await storeHumanJudgment({
+            decision: decisionText.slice(0, 300),
+            decision_type: 'approve',
+            reasons: [
+                `选项: ${decision.options.map((o) => o.label).join(' / ')}`,
+                `风险: ${decision.options.map((o) => o.risks || '无').join('; ')}`,
+                `回滚: ${decision.rollback || '无'}`,
+            ].filter(Boolean),
+            values_derived: [],
+            context: {
+                domain: decision.context.domain,
+                complexity: decision.context.stakes === 'critical' ? 'profound' : decision.context.stakes === 'high' ? 'complex' : decision.context.stakes === 'medium' ? 'moderate' : 'simple',
+                stakes: decision.context.stakes,
+                time_pressure: 'medium',
+            },
+            outcome: { approved: true },
+            metadata: { source: 'trajectory', confidence: 0.8, revisable: true },
+            status: 'active',
+            appliesTo: [],
+        });
+        const jd = await reflectAfterJudgment(judgment, 'agent', byAgentId).catch(() => null);
+        return {
+            ok: true,
+            reflection: { hvId: judgment.id, jdId: jd?.descriptionId, at: new Date().toISOString() },
+        };
+    }
+    catch (e) {
+        return { ok: false, error: e?.message || String(e) };
+    }
+}
+/** 回滚教训入库: HumanJudgment (reject 语义) — Context OS "失败时的触发条件和回滚动作" */
+async function reflectRollbackLesson(decision, reason, byAgentId) {
+    try {
+        const { storeHumanJudgment } = await import('../pi-ecosystem-judgment/human-value-store.js');
+        const { reflectAfterJudgment } = await import('../judgeness/reflect.js');
+        const judgment = await storeHumanJudgment({
+            decision: `回滚决策: ${decision.problem} — 失败原因: ${reason.slice(0, 200)}`,
+            decision_type: 'reject',
+            reasons: [decision.rollback || '', reason].filter(Boolean),
+            values_derived: [],
+            context: {
+                domain: decision.context.domain,
+                complexity: 'moderate',
+                stakes: decision.context.stakes,
+                time_pressure: 'medium',
+            },
+            outcome: { approved: false, feedback: reason.slice(0, 200) },
+            metadata: { source: 'trajectory', confidence: 0.7, revisable: false },
+            status: 'active',
+            appliesTo: [],
+        });
+        const jd = await reflectAfterJudgment(judgment, 'agent', byAgentId).catch(() => null);
+        return { ok: true, reflection: { hvId: judgment.id, jdId: jd?.descriptionId, at: new Date().toISOString() } };
+    }
+    catch (e) {
+        return { ok: false, error: e?.message || String(e) };
+    }
+}

package/dist/agents/pi-sdk-tools.js

@@ -1508,6 +1508,350 @@ export function registerBuiltinTools(ctx) {
             }
         }
     });
+    // ============================================================
+    // 决策协议工具 (2026-08-03, Context OS §7) — 可回滚的推理链
+    // create_decision / decide_decision / rollback_decision / list_decisions
+    // 实现: decision-store.ts (~/.bolloon/decisions/<id>.json)
+    // 9 要素: 问题/选项(含不做)/成本/收益/风险/信息缺口/推荐/时机/回滚
+    // 决策确认 (decide_decision) 自动 reflect 到 judgeness (HumanJudgment + JudgenessDescription)
+    // ============================================================
+    ctx.tools.set('create_decision', {
+        name: 'create_decision',
+        description: '重大决策前先写推理链 (Context OS 9 要素): problem 问题是什么, options 选项数组 (含"不做"), info_gaps 信息缺口, recommendation 推荐方案, timing 为什么是现在, rollback 失败时回滚条件. 之后用 decide_decision 确认.',
+        parameters: {
+            problem: '问题到底是什么 (必填)',
+            options: '选项数组 JSON (必填, e.g. [{"label":"方案A","costs":"成本","benefits":"收益","risks":"风险"},{"label":"什么都不做","includeDoNothing":true}])',
+            info_gaps: '当前信息缺口 (可选)',
+            recommendation: '推荐方案 (可选, 确认时必填)',
+            timing: '为什么是现在 (可选)',
+            rollback: '失败时的回滚条件 (可选)',
+            stakes: '风险等级: low / medium / high / critical (可选)',
+            domain: '领域 (可选)',
+        },
+        execute: async (args) => {
+            try {
+                const { createDecision, decisionToContext } = await import('./decision-store.js');
+                const problem = String(args.problem || '').trim();
+                if (!problem)
+                    return { success: false, error: 'problem 必填' };
+                let options = [];
+                try {
+                    const s = JSON.parse(String(args.options || '[]'));
+                    if (Array.isArray(s))
+                        options = s;
+                }
+                catch { /* options 解析失败 */ }
+                const rawStakes = String(args.stakes || 'medium');
+                const stakes = rawStakes === 'low' || rawStakes === 'high' || rawStakes === 'critical' ? rawStakes : 'medium';
+                const r = await createDecision({
+                    problem,
+                    options,
+                    infoGaps: args.info_gaps ? String(args.info_gaps) : undefined,
+                    recommendation: args.recommendation ? String(args.recommendation) : undefined,
+                    timing: args.timing ? String(args.timing) : undefined,
+                    rollback: args.rollback ? String(args.rollback) : undefined,
+                    stakes,
+                    domain: args.domain ? String(args.domain) : undefined,
+                    by: 'agent',
+                    originChannel: ctx.channelId || '',
+                });
+                if (!r.ok || !r.decision)
+                    return { success: false, error: r.error };
+                return { success: true, output: `✅ 决策推理链已创建 ${r.decision.decisionId}\n\n${decisionToContext(r.decision)}` };
+            }
+            catch (e) {
+                return { success: false, error: `create_decision 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('decide_decision', {
+        name: 'decide_decision',
+        description: '确认一个决策 (必须已有 recommendation). 确认后自动把该决策入库 judgeness (HumanJudgment + 5 维描述, 阶段0 临时价值点). 决策确认后状态 → decided.',
+        parameters: {
+            decision_id: '决策 ID (必填, create_decision 返回)',
+            recommendation: '最终推荐方案 (必填, 若创建时未填)',
+        },
+        execute: async (args) => {
+            try {
+                const { updateDecisionStatus } = await import('./decision-store.js');
+                const decisionId = String(args.decision_id || '').trim();
+                if (!decisionId)
+                    return { success: false, error: 'decision_id 必填' };
+                const r = await updateDecisionStatus(decisionId, { decide: true, recommendation: args.recommendation ? String(args.recommendation) : undefined }, { byAgentId: ctx.agentId || '' });
+                if (!r.ok || !r.decision)
+                    return { success: false, error: r.error };
+                const refl = r.decision.reflection ? ` (已入库 judgeness: hv=${r.decision.reflection.hvId})` : '';
+                return { success: true, output: `✅ 决策已确认: ${r.decision.problem} → ${r.decision.recommendation}${refl}` };
+            }
+            catch (e) {
+                return { success: false, error: `decide_decision 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('rollback_decision', {
+        name: 'rollback_decision',
+        description: '决策失败触发回滚条件时调用: 标记 rolled-back + 记录教训 (reject 语义入库 judgeness, 防止重复踩坑).',
+        parameters: {
+            decision_id: '决策 ID (必填)',
+            reason: '失败/回滚原因 (必填, 将作为教训入库)',
+        },
+        execute: async (args) => {
+            try {
+                const { updateDecisionStatus } = await import('./decision-store.js');
+                const decisionId = String(args.decision_id || '').trim();
+                if (!decisionId)
+                    return { success: false, error: 'decision_id 必填' };
+                const reason = String(args.reason || '').trim();
+                if (!reason)
+                    return { success: false, error: 'reason 必填 (回滚原因)' };
+                const r = await updateDecisionStatus(decisionId, { rollback: true, reason }, { byAgentId: ctx.agentId || '' });
+                if (!r.ok || !r.decision)
+                    return { success: false, error: r.error };
+                return { success: true, output: `↩️ 决策已回滚: ${r.decision.problem}\n教训已入库 judgeness (reject 语义): ${reason.slice(0, 120)}` };
+            }
+            catch (e) {
+                return { success: false, error: `rollback_decision 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('list_decisions', {
+        name: 'list_decisions',
+        description: '列出全部决策 (按创建时间倒序). 可选 status 过滤: draft / decided / implemented / abandoned / rolled-back. 用于恢复决策上下文.',
+        parameters: {
+            status: '可选过滤: draft / decided / implemented / abandoned / rolled-back',
+        },
+        execute: async (args) => {
+            try {
+                const { listDecisions, decisionToContext } = await import('./decision-store.js');
+                const status = ['draft', 'decided', 'implemented', 'abandoned', 'rolled-back'].includes(args.status) ? args.status : undefined;
+                const decisions = await listDecisions(status);
+                if (decisions.length === 0)
+                    return { success: true, output: '暂无决策记录.' };
+                const text = decisions.slice(0, 8).map(d => decisionToContext(d)).join('\n\n');
+                return { success: true, output: `🧭 ${decisions.length} 条决策 (9 要素推理链可追溯):\n\n${text}` };
+            }
+            catch (e) {
+                return { success: false, error: `list_decisions 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    // ============================================================
+    // Context OS 资产层工具 (2026-08-03, P5) — 12+3 层文件夹体系
+    // list_context_layers / write_context_asset / read_context_assets
+    // 实现: src/bootstrap/context-os.ts (~/.bolloon/context-os/)
+    // 价值判断: 写入前回答"未来哪个具体场景会用到它?" — 回答不出进 tmp/
+    // ============================================================
+    ctx.tools.set('list_context_layers', {
+        name: 'list_context_layers',
+        description: '列出 Context OS 资产层 (12+3 层: 01-Me 我是谁 / 02-Network 我认识谁 / 03-Current 我在做什么 / 04-Projects 项目 / 05-Prompts 提示词 / 06-Protocols 协议 / 07-Knowledge 知识 / 08-Insights 洞察 / 09-Tools 工具 / 10-Skills 技能 / 11-Write 写作 / 12-Analysis 决策复盘 / output / research / tmp) + 每层资产数. 任务前先看目录, 再按任务路由读取对应层.',
+        parameters: {},
+        execute: async () => {
+            try {
+                const { readContextAssets, formatLayerListing } = await import('../bootstrap/context-os.js');
+                const listings = await readContextAssets();
+                const total = listings.reduce((s, l) => s + l.fileCount, 0);
+                if (total === 0)
+                    return { success: true, output: '📂 Context OS 资产层已就绪 (12+3 层), 当前暂无资产. 有价值的内容用 write_context_asset 写入对应层.' };
+                return { success: true, output: `📂 Context OS 资产层共 ${total} 篇资产:\n\n${formatLayerListing(listings)}` };
+            }
+            catch (e) {
+                return { success: false, error: `list_context_layers 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('write_context_asset', {
+        name: 'write_context_asset',
+        description: '把已验证的价值写入 Context OS 资产层 (唯一落点, 不制造重复文件). 写入前先自检: 未来哪个具体场景会用到它? 回答不出 → 写 tmp/ 或放弃. layer 可选: 01-Me 原则边界 / 02-Network 人脉 / 03-Current 当前状态 / 04-Projects 项目 / 05-Prompts 已验证提示词 / 06-Protocols 规则 / 07-Knowledge 跨项目知识 / 08-Insights 已验证洞察/教训 / 09-Tools 工具经验 / 10-Skills 可验证能力 / 11-Write 成熟表达 / 12-Analysis 决策复盘 / output 对外交付 / research 中间成果 / tmp 一次性草稿.',
+        parameters: {
+            layer: '层 key (必填, 见 description 列表)',
+            title: '资产标题 (必填, 一句话)',
+            content: '资产正文 markdown (必填)',
+            tags: '可选 tags 数组 JSON',
+            domain: '可选领域',
+        },
+        execute: async (args) => {
+            try {
+                const { writeContextAsset } = await import('../bootstrap/context-os.js');
+                const layer = String(args.layer || '').trim();
+                const title = String(args.title || '').trim();
+                const content = String(args.content || '').trim();
+                if (!layer)
+                    return { success: false, error: 'layer 必填 (如 07-Knowledge)' };
+                if (!title)
+                    return { success: false, error: 'title 必填' };
+                if (!content)
+                    return { success: false, error: 'content 必填' };
+                let tags = [];
+                try {
+                    const t = JSON.parse(String(args.tags || '[]'));
+                    if (Array.isArray(t))
+                        tags = t.map(String);
+                }
+                catch { /* tags 解析失败 */ }
+                const r = await writeContextAsset({ layer, title, content, tags, domain: args.domain ? String(args.domain) : undefined });
+                if (!r.ok)
+                    return { success: false, error: r.error };
+                if (r.skipped)
+                    return { success: true, output: `⏭️ ${r.error}` };
+                return { success: true, output: `📥 已写入资产层 ${r.asset.layer}: ${r.asset.title} (stage0 临时价值点, 待验证后固化)\n路径: ${r.asset.path}` };
+            }
+            catch (e) {
+                return { success: false, error: `write_context_asset 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('read_context_assets', {
+        name: 'read_context_assets',
+        description: '读取 Context OS 资产层内容. layer 可选 (空 = 全层汇总); keyword 可选 (标题/内容过滤). 做项目前先读 04-Projects 对应项目, 重大决策前读 08-Insights + 12-Analysis, 学技术读 07-Knowledge + 09-Tools.',
+        parameters: {
+            layer: '可选层 key (如 07-Knowledge), 空 = 全部',
+            keyword: '可选关键词过滤',
+        },
+        execute: async (args) => {
+            try {
+                const { readContextAssets, formatLayerListing } = await import('../bootstrap/context-os.js');
+                const layer = args.layer ? String(args.layer) : undefined;
+                const kw = args.keyword ? String(args.keyword) : undefined;
+                const listings = await readContextAssets(layer, kw);
+                if (listings.every((l) => l.fileCount === 0)) {
+                    return { success: true, output: layer ? `📂 资产层 ${layer} 暂无资产` : '📂 资产层暂无资产' };
+                }
+                // 单层且有 keyword → 输出完整正文
+                if (layer && kw) {
+                    const found = listings[0]?.files || [];
+                    const { readAssetBody } = await import('../bootstrap/context-os.js');
+                    const bodies = [];
+                    for (const f of found.slice(0, 5)) {
+                        try {
+                            const r = await readAssetBody(layer, f.file);
+                            if (r.ok && r.body)
+                                bodies.push(`--- ${f.title} ---\n${r.body.slice(0, 2000)}\n--- 结束 ---`);
+                        }
+                        catch { /* 跳过 */ }
+                    }
+                    return { success: true, output: bodies.length > 0 ? bodies.join('\n\n') : '未找到匹配资产' };
+                }
+                return { success: true, output: formatLayerListing(listings) };
+            }
+            catch (e) {
+                return { success: false, error: `read_context_assets 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    // ============================================================
+    // MCP 工具 (2026-08-03) — 外部 MCP server 接入 agent 工具系统
+    // 配置: ~/.mcp.json (mcpServers), 启动时 initializeMcpAdapter 自动握手发现工具
+    // mcp_list_tools: 列出已发现的 MCP 工具
+    // mcp_tool: 调用任意 MCP 工具 (真实 stdio JSON-RPC)
+    // ============================================================
+    ctx.tools.set('mcp_list_tools', {
+        name: 'mcp_list_tools',
+        description: '列出通过 MCP 协议连接的可用外部工具 (来自 ~/.mcp.json 配置的 MCP servers). 调用 MCP 工具前先列一次, 拿准确工具名和参数.',
+        parameters: {},
+        execute: async () => {
+            try {
+                const mcp = await import('../pi-ecosystem-mcp/index.js');
+                await mcp.initializeMcpAdapter().catch(() => { });
+                const tools = mcp.listTools();
+                if (tools.length === 0) {
+                    return { success: true, output: '未发现 MCP 工具. 配置 ~/.mcp.json (mcpServers: {name: {command, args}}), 重启后自动连接.' };
+                }
+                const lines = tools.map((t) => `  - ${t.name} (${t.serverName}): ${t.description?.slice(0, 80) || '无描述'}`);
+                return { success: true, output: `🔌 ${tools.length} 个 MCP 工具可用:\n${lines.join('\n')}\n\n调用用 mcp_tool (tool=工具名, arguments=参数 JSON)` };
+            }
+            catch (e) {
+                return { success: false, error: `mcp_list_tools 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    ctx.tools.set('mcp_tool', {
+        name: 'mcp_tool',
+        description: '调用外部 MCP 工具 (真实 stdio JSON-RPC 通信). tool = 工具名 (先用 mcp_list_tools 查看), arguments = 参数 JSON 对象.',
+        parameters: {
+            tool: 'MCP 工具名 (必填)',
+            arguments: '参数 JSON 对象 (必填, e.g. {"text":"hello"})',
+        },
+        execute: async (args) => {
+            try {
+                const mcp = await import('../pi-ecosystem-mcp/index.js');
+                const tool = String(args.tool || '').trim();
+                if (!tool)
+                    return { success: false, error: 'tool 必填' };
+                let argumentsObj = {};
+                try {
+                    const a = JSON.parse(String(args.arguments || '{}'));
+                    if (a && typeof a === 'object')
+                        argumentsObj = a;
+                }
+                catch {
+                    return { success: false, error: 'arguments 必须是 JSON 对象' };
+                }
+                const r = await mcp.executeTool(tool, argumentsObj);
+                if (!r.success)
+                    return { success: false, error: r.error || 'MCP 调用失败' };
+                const text = Array.isArray(r.content)
+                    ? r.content.map((c) => c?.text ?? '').filter(Boolean).join('\n')
+                    : JSON.stringify(r.content);
+                return { success: true, output: `🔧 MCP ${tool}:\n${text.slice(0, 4000)}` };
+            }
+            catch (e) {
+                return { success: false, error: `mcp_tool 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
+    // ============================================================
+    // publish_did (2026-08-03) — 把当前 agent 的 DID 发布到 IPFS + IPNS
+    // 全自动: 自动安装/启动本地 Kubo → 上传 DID 文档 → 发布 IPNS name
+    // 实现: @diap/sdk (AgentAuthManager + publishAfterUpload)
+    // ============================================================
+    ctx.tools.set('publish_did', {
+        name: 'publish_did',
+        description: '把当前 agent 的 DID 身份发布到本地 IPFS + IPNS (自动安装启动 Kubo). 返回 DID + CID (IPFS 内容地址) + IPNS name (稳定可解析标识). 跨节点发现和身份解析依赖它.',
+        parameters: {
+            name: '可选: 发布显示名 (默认 agentId)',
+        },
+        execute: async (args) => {
+            try {
+                const agentId = String(ctx.agentId || '').trim();
+                const { loadOrCreateAgentIdentity } = await import('./agent-identity.js');
+                const identity = loadOrCreateAgentIdentity(agentId || 'default-agent');
+                const { KeyManager } = await import('@diap/sdk');
+                const kp = KeyManager.fromPrivateKey(Buffer.from(identity.privateKey, 'hex'));
+                const displayName = args.name ? String(args.name) : agentId || 'bolloon-agent';
+                // 1. 确保本地 Kubo (自动安装 + 启动)
+                const sdk = await import('@diap/sdk');
+                const checkKuboSetup = sdk.checkKuboSetup;
+                if (typeof checkKuboSetup === 'function') {
+                    const setup = await checkKuboSetup(true, true);
+                    if (!setup?.ready || !setup?.daemonRunning) {
+                        return { success: false, error: '本地 Kubo 不可用 (自动安装失败), 无法发布到 IPFS' };
+                    }
+                }
+                // 2. 注册 agent → 上传 DID 文档 → CID
+                const { AgentAuthManager } = await import('@diap/sdk');
+                const auth = await AgentAuthManager.newWithRemoteIpfs('http://127.0.0.1:5001', 'http://127.0.0.1:8080');
+                const result = await auth.registerAgent({ name: displayName, services: [] }, kp, '');
+                const cid = result.cid || result.didDocCid;
+                if (!cid)
+                    return { success: false, error: 'DID 上传成功但未拿到 CID' };
+                // 3. 发布 IPNS name (稳定标识)
+                let ipnsName = '';
+                try {
+                    const ipfs = await sdk.IpfsClient.newWithRemoteNode('http://127.0.0.1:5001', 'http://127.0.0.1:8080');
+                    const pub = await ipfs.publishAfterUpload?.(cid, kp);
+                    ipnsName = pub?.name || pub?.ipnsName || '';
+                }
+                catch { /* IPNS 失败不致命, CID 仍可用 */ }
+                return {
+                    success: true,
+                    output: `✅ DID 已发布到 IPFS:\n  DID: ${identity.did}\n  CID: ${cid}\n  IPNS: ${ipnsName || '(发布失败, CID 仍可用)'}\n  读回验证: curl -X POST "http://127.0.0.1:5001/api/v0/cat?arg=${cid}"`,
+                };
+            }
+            catch (e) {
+                return { success: false, error: `publish_did 失败: ${String(e).slice(0, 200)}` };
+            }
+        }
+    });
 }
 /**
  * 注册 Wallet + Polymarket + Safe 工具 (基于 constraint-runtime/src/tools/).