@bolloon/bolloon-agent 0.3.26 → 0.3.28

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

@@ -394,6 +394,81 @@ export function registerBuiltinTools(ctx) {
             }
         }
     });
+    // 2026-08-02: 远端 channel 工具 — 让本地智能体能获取远端 channel 列表 + 发送消息到远端
+    //   (之前本地智能体看不到远端 channel, 无法 @ 远程智能体交流 — "工具没有给到位")
+    ctx.tools.set('list_remote_channels', {
+        name: 'list_remote_channels',
+        description: '列出 P2P 好友节点分享给你的远端 channel (远程智能体会话). 每个远端 channel 属于某个 peer, 你可以在回复中写 "@渠道名 消息内容" 或调用 send_to_remote_channel 给它们发消息.',
+        parameters: {},
+        execute: async () => {
+            try {
+                const port = process.env.PORT || '54188';
+                const res = await fetch(`http://127.0.0.1:${port}/api/remote-channels`);
+                if (!res.ok)
+                    return { success: false, error: `HTTP ${res.status}` };
+                const data = await res.json();
+                const peers = data?.peers || [];
+                const lines = [];
+                let total = 0;
+                for (const p of peers) {
+                    const chs = p.channels || [];
+                    total += chs.length;
+                    if (chs.length === 0)
+                        continue;
+                    lines.push(`👤 ${p.peerName || ('peer-' + String(p.peerId).substring(0, 8))} (${String(p.peerId).substring(0, 16)}…):`);
+                    for (const c of chs) {
+                        lines.push(`  - @${c.name} (id=${c.id})`);
+                    }
+                }
+                if (total === 0) {
+                    return { success: true, output: '📭 当前没有远端 channel (没有好友分享 channel 给你, 或对方不在线). 可先用 add_friend_by_id 添加好友.' };
+                }
+                return { success: true, output: `🌐 ${total} 个远端 channel:\n${lines.join('\n')}\n\n在回复中写 "@渠道名 消息内容" 即可发送 (系统自动转发到对方节点).` };
+            }
+            catch (e) {
+                return { success: false, error: `获取远端 channel 失败: ${String(e.message || e)}` };
+            }
+        }
+    });
+    ctx.tools.set('send_to_remote_channel', {
+        name: 'send_to_remote_channel',
+        description: '发送消息到远端 channel (远程智能体会话, 属于某个 P2P 好友节点). 对方节点会在该 channel 上跑 LLM 处理你的消息并回复. 用 list_remote_channels 查看可用 channel 和 owner.',
+        parameters: {
+            targetPublicKey: '远端节点 publicKey (64 hex, 用 list_remote_channels 看 owner)',
+            channelId: '远端 channel id (用 list_remote_channels 查看)',
+            text: '消息内容 (必填)',
+            autoInvokeTools: '可选, 是否允许对方调用工具 (true/false, 默认 true)'
+        },
+        execute: async (args) => {
+            const targetPublicKey = String(args.targetPublicKey || '').trim();
+            const channelId = String(args.channelId || '').trim();
+            const text = String(args.text || '').trim();
+            if (!targetPublicKey || !channelId || !text) {
+                return { success: false, error: 'targetPublicKey, channelId, text 必填 (用 list_remote_channels 查)' };
+            }
+            try {
+                const port = process.env.PORT || '54188';
+                const res = await fetch(`http://127.0.0.1:${port}/api/remote-channels/chat-send`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        targetPublicKey,
+                        channelId,
+                        text,
+                        ...(typeof args.autoInvokeTools === 'boolean' ? { autoInvokeTools: args.autoInvokeTools } : {}),
+                    })
+                });
+                const data = await res.json();
+                if (!res.ok) {
+                    return { success: false, error: `发送失败: ${data.error || `HTTP ${res.status}`}` };
+                }
+                return { success: true, output: `📨 消息已发送到远端 channel ${channelId} (${data.sent ? '已送达' : data.queued ? '对方不在线, 已入队, 上线后自动送达' : '未知状态'}). 对方智能体会回复, 可用 check_inbox 或稍后查看.` };
+            }
+            catch (e) {
+                return { success: false, error: `发送失败: ${String(e.message || e)}` };
+            }
+        }
+    });
     // delegate_to_engine — 把编码任务委派给本机已安装的其他 AI 编码智能体 CLI
     // (codex / claude-code / opencode / openclaw / hermes). 它们必须已安装且可达 PATH.
     // 实验 API 引擎 (experiment:xxx) 是供应商不是 CLI, 不支持委派, 工具会提示改用 import.
@@ -1433,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/).

package/dist/bootstrap/context-os.js

@@ -0,0 +1,213 @@
+/**
+ * context-os.ts — Context OS 资产层 (2026-08-03, P5)
+ *
+ * 把 Ziye-Context-OS 的 12+3 层文件夹体系落地到 Bolloon:
+ *   ~/.bolloon/context-os/
+ *     01-Me ~ 12-Analysis + output / research / tmp
+ *
+ * 每层回答一种问题 (Context OS §3):
+ *   01-Me 我是谁 / 02-Network 我认识谁 / 03-Current 我现在在做什么
+ *   04-Projects 我正在推进什么 / 05-Prompts 哪些提示词已验证
+ *   06-Protocols AI 和系统该如何工作 / 07-Knowledge 哪些知识跨项目复用
+ *   08-Insights 哪些判断改变决策 / 09-Tools 哪些工具省时间
+ *   10-Skills 哪些能力可验证 / 11-Write 哪些表达可复用
+ *   12-Analysis 决策过程与复盘 / output 对外交付 / research 中间成果 / tmp 一次性草稿
+ *
+ * 价值判断标准 (Context OS §5): 每个资产进入前回答"未来哪个具体场景会用到它?".
+ * 回答不出 = 噪音, 不该进正式层.
+ *
+ * 设计 (减法):
+ *   - 每层一个 README.md 声明职责边界 (存什么/不该存什么/典型用途)
+ *   - 资产文件: <ts>-<slug>.md, frontmatter v2 (stage0 = 临时价值点, 与 judgeness 生命周期对应)
+ *   - 写操作失败静默, 不阻塞主对话
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+export const CONTEXT_OS_LAYERS = [
+    { key: '01-Me', name: '我是谁', store: '经过验证的原则、不可碰的边界、稳定偏好', notStore: '临时情绪、未经验证的念头', usage: '防止 AI 用错误的方式帮助你' },
+    { key: '02-Network', name: '我认识谁', store: '有真实关系、能力可定位、能在具体问题上调用的人', notStore: '只看过主页的陌生人', usage: '需要咨询、合作、求证时找到正确的人' },
+    { key: '03-Current', name: '我现在在做什么', store: '今天/本周的现实状态、工作现场、阻塞项', notStore: '长期知识、项目历史全文', usage: '防止 AI 按过期状态给建议' },
+    { key: '04-Projects', name: '我正在推进什么', store: '有明确交付、真实进度、可验证证据的项目', notStore: '只有想法的脑暴', usage: '让 AI 按项目真实边界推进' },
+    { key: '05-Prompts', name: '已验证可复用的提示词', store: '至少复用过、效果稳定的 Prompt', notStore: '一次性调试 Prompt', usage: '跨项目、跨工具复用工作方法' },
+    { key: '06-Protocols', name: 'AI 和系统该如何工作', store: '为防止真实错误而产生、被重复调用的规则', notStore: '纯理论流程', usage: '把"知道"变成"每次都会做"' },
+    { key: '07-Knowledge', name: '哪些领域知识未来复用', store: '未来至少三个项目可能复用的领域理解', notStore: '随手可搜的常识', usage: '技术/行业问题的长期积累' },
+    { key: '08-Insights', name: '哪些已验证的判断改变决策', store: '能改变决策、产品方向或自我认知的已验证判断', notStore: '情绪碎片、未经验证的直觉', usage: '防止重复踩同一种坑' },
+    { key: '09-Tools', name: '哪些工具和脚本省时间', store: '实际用过、能节约时间、包含回退方案的工具经验', notStore: '只安装未使用的软件', usage: '提升执行效率，避免重复试错' },
+    { key: '10-Skills', name: '哪些能力可验证交付', store: '可外部验证、能交付、有作品支撑的能力', notStore: '"我想学"的愿望', usage: '简历、分工、能力缺口识别' },
+    { key: '11-Write', name: '哪些写作可复用', store: '可以引用、改写、发布的成熟表达', notStore: '未整理草稿', usage: '保持跨场景表达一致' },
+    { key: '12-Analysis', name: '决策过程与复盘', store: '有推理链、可事后复盘的研究与决策', notStore: '只有结论的事后合理化', usage: '重要决策可追溯、可修正' },
+    { key: 'output', name: '对外交付物', store: '给外部的人看的最终交付物', notStore: '内部草稿', usage: '可直接分享给他人' },
+    { key: 'research', name: '研究中间成果', store: '研究中的中间成果', notStore: '结论已定型的资产', usage: '未完成研究的暂存' },
+    { key: 'tmp', name: '一次性草稿', store: '一次性草稿与临时文件', notStore: '任何未来要复用的东西', usage: '定期清理' },
+];
+const LAYER_KEYS = new Set(CONTEXT_OS_LAYERS.map((l) => l.key));
+// ============================================================
+// 路径
+// ============================================================
+export function getContextOsRoot(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'context-os');
+}
+export function getLayerDir(layer, home = os.homedir()) {
+    return path.join(getContextOsRoot(home), layer);
+}
+/** 校验 layer 合法; 非法返回 null */
+export function resolveLayer(layer) {
+    const key = String(layer || '').trim();
+    return LAYER_KEYS.has(key) ? CONTEXT_OS_LAYERS.find((l) => l.key === key) : null;
+}
+function slugify(s) {
+    return s.replace(/[^a-zA-Z0-9\u4e00-\u9fa5_-]/g, '_').slice(0, 40) || 'untitled';
+}
+// ============================================================
+// 初始化: 建目录 + 每层 README (幂等)
+// ============================================================
+function layerReadme(l) {
+    return `# ${l.key} — ${l.name}
+
+## 这一层回答的问题
+${l.name}
+
+## 存什么
+${l.store}
+
+## 不该存什么
+${l.notStore}
+
+## 典型用途
+${l.usage}
+
+## 价值判断标准 (Context OS §5)
+写入前先回答: **未来哪个具体场景会用到它?**
+回答不出 = 噪音, 留在 tmp/, 不进正式层.
+
+## 价值生命周期
+阶段0 临时价值点 (对话中刚出现, 未验证) → 阶段1 验证 (被使用/确认)
+→ 阶段2 固化 (本层唯一位置) → 阶段3 索引化 (高频引用) → 阶段4 归档/删除.
+`;
+}
+export async function ensureContextOsDirs(home) {
+    const root = getContextOsRoot(home);
+    await fs.mkdir(root, { recursive: true });
+    for (const l of CONTEXT_OS_LAYERS) {
+        const dir = getLayerDir(l.key, home);
+        await fs.mkdir(dir, { recursive: true });
+        const readmePath = path.join(dir, 'README.md');
+        try {
+            await fs.access(readmePath);
+        }
+        catch {
+            await fs.writeFile(readmePath, layerReadme(l), 'utf-8');
+        }
+    }
+}
+/**
+ * 写入资产到指定层.
+ * 文件名: <ts>-<slug>.md; frontmatter v2 (stage0 = 临时价值点, 待验证).
+ * 幂等: 同层同 slug 已存在 → 跳过 (不重复造文件, Context OS §6 Step3).
+ */
+export async function writeContextAsset(input, home) {
+    const layer = resolveLayer(input.layer);
+    if (!layer) {
+        return { ok: false, error: `layer 非法: '${input.layer}'. 合法: ${CONTEXT_OS_LAYERS.map((l) => l.key).join(' / ')}` };
+    }
+    const title = String(input.title || '').trim();
+    if (!title)
+        return { ok: false, error: 'title 必填' };
+    const content = String(input.content || '').trim();
+    if (!content)
+        return { ok: false, error: 'content 必填' };
+    await ensureContextOsDirs(home);
+    const now = new Date().toISOString();
+    const ts = Date.now();
+    const slug = slugify(title);
+    const fileName = `${ts}-${slug}.md`;
+    const filePath = path.join(getLayerDir(layer.key, home), fileName);
+    // 幂等: 同 slug 已存在 → 跳过
+    try {
+        const files = await fs.readdir(getLayerDir(layer.key, home));
+        if (files.some((f) => f.endsWith(`-${slug}.md`))) {
+            return { ok: true, skipped: true, error: `同标题资产已存在 (${slug}.md), 未重复写入` };
+        }
+    }
+    catch { /* 目录不存在, 继续 */ }
+    const fm = [
+        '---',
+        `title: ${title.replace(/[\n\r]/g, ' ').slice(0, 80)}`,
+        `source: session`,
+        `created: ${now}`,
+        `layer: ${layer.key}`,
+        `stage: stage0`,
+        `tags: [${(input.tags || []).map((t) => t.replace(/[^\w\u4e00-\u9fa5-]/g, '')).filter(Boolean).join(', ')}]`,
+        input.domain ? `domain: ${input.domain.replace(/[\n\r]/g, ' ').slice(0, 40)}` : '',
+        'schema_version: 2',
+        '---',
+        '',
+        content,
+    ].filter(Boolean).join('\n');
+    try {
+        await fs.writeFile(filePath, fm, 'utf-8');
+        return {
+            ok: true,
+            asset: { layer: layer.key, file: fileName, title, path: filePath, createdAt: now, stage: 'stage0' },
+        };
+    }
+    catch (e) {
+        return { ok: false, error: `写入失败: ${e?.message || String(e)}` };
+    }
+}
+/** 列出层资产; layer 为空 → 全层汇总 */
+export async function readContextAssets(layer, keyword, home) {
+    const root = getContextOsRoot(home);
+    const kw = String(keyword || '').trim().toLowerCase();
+    const wanted = layer ? [resolveLayer(layer)].filter(Boolean).map((l) => l.key) : CONTEXT_OS_LAYERS.map((l) => l.key);
+    const out = [];
+    for (const key of wanted) {
+        const l = resolveLayer(key);
+        try {
+            const files = (await fs.readdir(getLayerDir(key, home))).filter((f) => f.endsWith('.md') && f !== 'README.md');
+            const entries = [];
+            for (const f of files) {
+                try {
+                    const raw = await fs.readFile(path.join(getLayerDir(key, home), f), 'utf-8');
+                    const titleM = raw.match(/^title:\s*(.+)$/m);
+                    const createdM = raw.match(/^created:\s*(.+)$/m);
+                    const title = titleM ? titleM[1].trim() : f.replace(/\.md$/, '');
+                    if (kw && !(title.toLowerCase().includes(kw) || raw.toLowerCase().includes(kw)))
+                        continue;
+                    entries.push({ file: f, title, createdAt: createdM ? createdM[1].trim() : '' });
+                }
+                catch { /* 单文件损坏跳过 */ }
+            }
+            entries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+            out.push({ layer: key, name: l.name, fileCount: entries.length, files: entries.slice(0, 20) });
+        }
+        catch {
+            out.push({ layer: key, name: l.name, fileCount: 0, files: [] });
+        }
+    }
+    return out;
+}
+/** 读取单篇资产正文 (供工具输出完整内容) */
+export async function readAssetBody(layer, file, home) {
+    const l = resolveLayer(layer);
+    if (!l)
+        return { ok: false, error: `layer 非法: '${layer}'` };
+    const safeFile = path.basename(String(file || '').replace(/[^\w\u4e00-\u9fa5.-]/g, '_'));
+    if (!safeFile.endsWith('.md'))
+        return { ok: false, error: 'file 必须是 .md' };
+    try {
+        const raw = await fs.readFile(path.join(getLayerDir(l.key, home), safeFile), 'utf-8');
+        return { ok: true, body: raw };
+    }
+    catch (e) {
+        return { ok: false, error: `读取失败: ${e?.message || String(e)}` };
+    }
+}
+/** 层 → 上下文注入摘要 (给 LLM 的资产层目录) */
+export function formatLayerListing(listings) {
+    if (listings.length === 0)
+        return '';
+    const lines = listings.map((l) => `  - ${l.layer} (${l.name}): ${l.fileCount} 篇` + (l.files.length > 0 ? ` — ${l.files.slice(0, 3).map((f) => f.title).join(' / ')}` : ''));
+    return `[系统上下文] 资产层 (Context OS 12+3 层, 先看 03-Current 再按任务路由):\n${lines.join('\n')}\n\n`;
+}