@bolloon/bolloon-agent 0.1.35 → 0.1.37

package/dist/llm/tool-manifest/places.js

@@ -0,0 +1,83 @@
+export const places_search = {
+    id: 'places_search',
+    name: 'places_search',
+    oneLine: '使用 Google Places 搜索地点/商户/餐厅/景点 (多查询).',
+    description: '单次调用支持多个查询. 多个查询可用于: 高效的行程规划, 拆解广泛或抽象的请求. 包含更广泛的区域以避免同名地点冲突.',
+    whenToUse: [
+        '用户问某地有什么 (餐厅/景点/酒店)',
+        '行程规划 (多地点)',
+        '需要 place_id 以便后续在地图展示',
+    ],
+    whenNotToUse: [
+        '需要地点坐标 (问 GPS)',
+        '只问天气 (用 weather_fetch)',
+    ],
+    parameters: [
+        { name: 'queries', type: 'array', required: true, description: '1-10 个查询', minItems: 1, maxItems: 10, items: {
+                name: 'q', type: 'object', required: true, description: '单查询', properties: [
+                    { name: 'query', type: 'string', required: true, description: '自然语言搜索' },
+                    { name: 'max_results', type: 'integer', required: false, description: '1-10, 默认 5', minimum: 1, maximum: 10, default: 5 }
+                ],
+            } },
+        { name: 'location_bias_lat', type: 'number', required: false, description: '可选纬度' },
+        { name: 'location_bias_lng', type: 'number', required: false, description: '可选经度' },
+        { name: 'location_bias_radius', type: 'number', required: false, description: '米 (默认 5000)', default: 5000 }
+    ],
+    callExample: `[TOOL:places_search]
+[P:queries]${'${'}JSON.stringify([{"query":"ramen restaurants Tokyo"}])[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};
+export const places_map_display_v0 = {
+    id: 'places_map_display_v0',
+    name: 'places_map_display_v0',
+    oneLine: '在地图上展示地点, 附上你的推荐和内行小贴士.',
+    description: '工作流: 先用 places_search 获取 place_id, 然后用 place_id 引用调用本工具. 两种模式: 简单标记 (locations) 或行程 (days).',
+    whenToUse: [
+        '用户需要看地点在地图上',
+        '行程规划, 需要可视化',
+    ],
+    whenNotToUse: [
+        '只问地点信息 (用 places_search 文字回答)',
+    ],
+    parameters: [
+        { name: 'locations', type: 'array', required: false, description: '简单标记模式', minItems: 1, maxItems: 50, items: {
+                name: 'loc', type: 'object', required: true, description: '地点', properties: [
+                    { name: 'name', type: 'string', required: true, description: '地点名' },
+                    { name: 'latitude', type: 'number', required: true, description: '纬度' },
+                    { name: 'longitude', type: 'number', required: true, description: '经度' },
+                    { name: 'place_id', type: 'string', required: false, description: '从 places_search 复制' },
+                    { name: 'notes', type: 'string', required: false, description: '你的小贴士' },
+                    { name: 'address', type: 'string', required: false, description: '自定义地点的地址 (没有 place_id 时用)' },
+                    { name: 'arrival_time', type: 'string', required: false, description: '到达时间 (用于行程, e.g. "8:00 AM")' },
+                    { name: 'duration_minutes', type: 'integer', required: false, description: '停留时长 (分钟)' },
+                ],
+            } },
+        { name: 'days', type: 'array', required: false, description: '行程模式', minItems: 1, maxItems: 30, items: {
+                name: 'day', type: 'object', required: true, description: '单日', properties: [
+                    { name: 'day_number', type: 'integer', required: true, description: '天数 (从 1 开始)', minimum: 1 },
+                    { name: 'title', type: 'string', required: false, description: '日期标题' },
+                    { name: 'narrative', type: 'string', required: false, description: '该日叙述' },
+                    { name: 'locations', type: 'array', required: true, description: '该日地点', minItems: 1, maxItems: 50, items: {
+                            name: 'loc', type: 'object', required: true, description: '地点', properties: [
+                                { name: 'name', type: 'string', required: true, description: '地点名' },
+                                { name: 'latitude', type: 'number', required: true, description: '纬度' },
+                                { name: 'longitude', type: 'number', required: true, description: '经度' },
+                                { name: 'place_id', type: 'string', required: false, description: '从 places_search 复制' },
+                                { name: 'notes', type: 'string', required: false, description: '你的小贴士' },
+                                { name: 'address', type: 'string', required: false, description: '自定义地点地址' },
+                                { name: 'arrival_time', type: 'string', required: false, description: '到达时间' },
+                                { name: 'duration_minutes', type: 'integer', required: false, description: '停留时长 (分钟)' },
+                            ],
+                        } },
+                ],
+            } },
+        { name: 'mode', type: 'enum', required: false, description: 'markers | itinerary', enumValues: ['markers', 'itinerary'] },
+        { name: 'travel_mode', type: 'enum', required: false, description: 'driving | walking | transit | bicycling', enumValues: ['driving', 'walking', 'transit', 'bicycling'] },
+        { name: 'show_route', type: 'boolean', required: false, description: '是否显示路线' },
+        { name: 'title', type: 'string', required: false, description: '行程标题' },
+        { name: 'narrative', type: 'string', required: false, description: '行程叙述' },
+    ],
+    callExample: `[TOOL:places_map_display_v0]
+[P:locations]${'${'}JSON.stringify([{"name":"Senso-ji","latitude":35.7148,"longitude":139.7967,"place_id":"ChIJ..."}])[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/present_files.js

@@ -0,0 +1,21 @@
+export const present_files = {
+    id: 'present_files',
+    name: 'present_files',
+    oneLine: '让文件对用户可见, 客户端界面中查看和渲染.',
+    description: '接收来自容器文件系统的文件路径数组, 返回客户端可访问文件的输出路径. 输出路径按与输入路径相同的顺序返回. 多个文件可在单次调用中高效呈现. 如果文件不在输出目录中, 会自动复制到该目录.',
+    whenToUse: [
+        '让用户可以查看、下载或与文件交互',
+        '一次展示多个相关文件',
+        '创建了应向用户展示的文件之后',
+    ],
+    whenNotToUse: [
+        '只是为了自己的处理而需要读取文件内容',
+        '临时或中间文件',
+    ],
+    parameters: [
+        { name: 'filepaths', type: 'array', required: true, description: '至少 1 个文件路径', minItems: 1, items: { name: 'path', type: 'string', required: true, description: '容器内路径' } },
+    ],
+    callExample: `[TOOL:present_files]
+[P:filepaths]${'${'}JSON.stringify(["/home/bolloon/report.md"])[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/recipe.js

@@ -0,0 +1,40 @@
+export const recipe_display_v0 = {
+    id: 'recipe_display_v0',
+    name: 'recipe_display_v0',
+    oneLine: '显示带可调整份量的交互式食谱.',
+    description: '用户要求食谱、烹饪说明或食物准备指南时使用. 该组件允许用户通过调整份量控件按比例缩放所有食材的用量.',
+    whenToUse: [
+        '用户问食谱',
+        '需要比例缩放 (份量调整)',
+    ],
+    whenNotToUse: [
+        '用户只要食材列表 (用文字)',
+        '用户问餐厅推荐 (用 places_search)',
+    ],
+    parameters: [
+        { name: 'title', type: 'string', required: true, description: '食谱名称' },
+        { name: 'base_servings', type: 'integer', required: false, description: '基础份数 (默认 4)' },
+        { name: 'description', type: 'string', required: false, description: '简短描述' },
+        { name: 'ingredients', type: 'array', required: true, description: '食材', items: {
+                name: 'ing', type: 'object', required: true, description: '食材', properties: [
+                    { name: 'id', type: 'string', required: true, description: '唯一 ID' },
+                    { name: 'amount', type: 'number', required: true, description: '数量', minimum: 0 },
+                    { name: 'unit', type: 'enum', required: false, description: 'g/kg/ml/l/tsp/tbsp/cup/fl_oz/oz/lb/pinch', enumValues: ['g', 'kg', 'ml', 'l', 'tsp', 'tbsp', 'cup', 'fl_oz', 'oz', 'lb', 'pinch'] },
+                    { name: 'name', type: 'string', required: true, description: '显示名 (整体可数项, 把 counting noun 放在这里)' },
+                ],
+            } },
+        { name: 'steps', type: 'array', required: true, description: '步骤', items: {
+                name: 's', type: 'object', required: true, description: '步骤', properties: [
+                    { name: 'id', type: 'string', required: true, description: '唯一 ID' },
+                    { name: 'title', type: 'string', required: true, description: '步骤摘要' },
+                    { name: 'content', type: 'string', required: true, description: '完整指令 (用 {id} 引用食材)' },
+                    { name: 'timer_seconds', type: 'integer', required: false, description: '等待/烹饪计时秒数', minimum: 0 }
+                ],
+            } },
+        { name: 'notes', type: 'string', required: false, description: '附加说明' },
+    ],
+    callExample: `[TOOL:recipe_display_v0]
+[P:title]Pasta
+[P:ingredients]${'${'}JSON.stringify([{"id":"a1","amount":500,"name":"pasta"}])[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/recommend_apps.js

@@ -0,0 +1,23 @@
+export const recommend_bolloon_apps = {
+    id: 'recommend_bolloon_apps',
+    name: 'recommend_bolloon_apps',
+    oneLine: '推荐 1-3 个 Bolloon 应用或扩展.',
+    description: '当用户正在处理的事情可能更适合用 Bolloon 聊天以外的应用来完成时, 展示此建议. 仅推荐与用户当前用例相关的应用, 并按相关性排序.',
+    whenToUse: [
+        '编码任务 (Bolloon Code)',
+        '知识工作 (Cowork)',
+        '处理电子表格 (Excel) 或幻灯片 (PowerPoint)',
+        '浏览器自动化 (Chrome)',
+    ],
+    whenNotToUse: [
+        '用户已明确不想离开对话',
+        '没有相关应用',
+    ],
+    parameters: [
+        { name: 'app_ids', type: 'array', required: true, description: '应用 ID 数组', items: {
+                name: 'id', type: 'string', required: true, description: '应用 ID (如 desktop/ios/android/code_terminal/code_vscode/code_jetbrains/code_slack/excel/powerpoint/chrome)',
+            } },
+    ],
+    callExample: '[TOOL:recommend_bolloon_apps] [P:app_ids] ["code_vscode","excel"] [ENDTOOL]',
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/str_replace.js

@@ -0,0 +1,27 @@
+export const str_replace = {
+    id: 'str_replace',
+    name: 'str_replace',
+    oneLine: '将文件中的唯一字符串替换为另一个.',
+    description: 'old_str 必须与原始文件内容完全匹配且只出现一次. 从 view 输出复制时, 不要包含行号前缀(空格 + 行号 + 制表符). 在编辑前立即查看文件; 任何成功的 str_replace 之后, 该文件之前的 view 输出已失效 — 在对同一文件进行进一步编辑之前请重新查看. /mnt/* 路径只读, 需先复制到可写位置.',
+    whenToUse: [
+        '编辑已有文件的小改动',
+        '精确替换单段文本',
+    ],
+    whenNotToUse: [
+        '创建新文件 (用 create_file)',
+        '完全重写文件 (用 create_file + 删除)',
+    ],
+    parameters: [
+        { name: 'description', type: 'string', required: true, description: '为什么我要做这个编辑' },
+        { name: 'old_str', type: 'string', required: true, description: '要被替换的字符串 (必须唯一)' },
+        { name: 'new_str', type: 'string', required: true, description: '新字符串 (空字符串 = 删除)', default: '' },
+        { name: 'path', type: 'string', required: true, description: '文件路径' },
+    ],
+    callExample: `[TOOL:str_replace]
+[P:description]修复 typo
+[P:old_str]recieve
+[P:new_str]receive
+[P:path]/home/bolloon/main.py
+[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/types.js

@@ -0,0 +1,7 @@
+/**
+ * tool-manifest/types.ts — 工具清单的类型
+ *
+ * 设计原则: schema 在代码侧(结构化数据), description/when-to-use 在代码侧,
+ * prompt 里只嵌"调用格式 + 名字 + 一句话描述" — 节省 LLM 注意力.
+ */
+export {};

package/dist/llm/tool-manifest/view.js

@@ -0,0 +1,24 @@
+export const view = {
+    id: 'view',
+    name: 'view',
+    oneLine: '查看文本、图像和目录列表.',
+    description: '支持的路径类型: 目录 (列出文件和目录, 最多 2 层深度, 忽略隐藏项和 node_modules); 图像文件 (.jpg, .jpeg, .png, .gif, .webp) 以可视方式显示; 文本文件显示带行号的内容 (前缀仅用于显示 — 不要在 str_replace 的 old_str 中包含它). 可以指定 view_range 来查看特定行.',
+    whenToUse: [
+        '读取已有文件的内容',
+        '看图像文件',
+        '列目录',
+    ],
+    whenNotToUse: [
+        '创建新文件 (用 create_file)',
+    ],
+    parameters: [
+        { name: 'description', type: 'string', required: true, description: '为什么我要查看' },
+        { name: 'path', type: 'string', required: true, description: '绝对路径' },
+        { name: 'view_range', type: 'array', required: false, description: '[start, end] 1-indexed, end=-1 表示到末尾', minItems: 2, maxItems: 2, items: { name: 'r', type: 'integer', required: true, description: '行号' } }
+    ],
+    callExample: `[TOOL:view]
+[P:description]读 README
+[P:path]/home/bolloon/README.md
+[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/weather.js

@@ -0,0 +1,27 @@
+export const weather_fetch = {
+    id: 'weather_fetch',
+    name: 'weather_fetch',
+    oneLine: '显示天气信息 (用用户家庭位置确定温度单位).',
+    description: '使用用户的家庭位置来确定温度单位: 美国用户使用华氏度, 其他用户使用摄氏度.',
+    whenToUse: [
+        '用户询问特定地点的天气',
+        '用户询问"我该带雨伞/外套吗"',
+        '用户在规划户外活动',
+        '用户询问"[城市]怎么样"(天气语境)',
+    ],
+    whenNotToUse: [
+        '气候或历史天气问题',
+        '闲聊天气但未指定地点',
+    ],
+    parameters: [
+        { name: 'location_name', type: 'string', required: true, description: '人类可读地点名' },
+        { name: 'latitude', type: 'number', required: true, description: '纬度' },
+        { name: 'longitude', type: 'number', required: true, description: '经度' },
+    ],
+    callExample: `[TOOL:weather_fetch]
+[P:location_name]San Francisco, CA
+[P:latitude]37.78
+[P:longitude]-122.41
+[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/llm/tool-manifest/web.js

@@ -0,0 +1,51 @@
+export const web_search = {
+    id: 'web_search',
+    name: 'web_search',
+    oneLine: '搜索 Web (返回前 10 条结果).',
+    description: '当需要当前信息或信息可能自知识截止以来已发生变化时使用. 1-6 词查询最佳. 默认改写; 引用应是个罕见的例外.',
+    whenToUse: [
+        '当前状态 (谁担任某职位、什么政策生效)',
+        '时效性信息 (股价、新闻)',
+        '不识别的实体 (默认搜索)',
+    ],
+    whenNotToUse: [
+        '永恒信息/成熟技术事实 (直接答)',
+        '已故人物 (不会变)',
+    ],
+    parameters: [
+        { name: 'query', type: 'string', required: true, description: '搜索查询 (1-6 词最佳)' },
+    ],
+    callExample: `[TOOL:web_search]
+[P:query]S&P 500 current price
+[ENDTOOL]`,
+    layerId: 'tool.web_search',
+};
+export const web_fetch = {
+    id: 'web_fetch',
+    name: 'web_fetch',
+    oneLine: '获取指定 URL 网页的内容.',
+    description: '此函数只能获取用户直接提供的或由 web_search 和 web_fetch 工具的结果中返回的 EXACT URL. 此工具无法访问需要身份验证的内容, 例如私有 Google Docs 或登录墙后的页面. URL 必须包含协议.',
+    whenToUse: [
+        'web_search 摘要不够, 需要读完整文章',
+        '用户提供 URL 让你读',
+    ],
+    whenNotToUse: [
+        '需要身份验证的页面',
+        'web_search 已经足够时',
+    ],
+    parameters: [
+        { name: 'url', type: 'string', required: true, description: '完整 URL (含协议, https://...)', format: 'uri' },
+        { name: 'allowed_domains', type: 'array', required: false, description: '仅允许的域名白名单 (如 ["example.com","*.github.com"])', items: { name: 'd', type: 'string', required: true, description: '域名' } },
+        { name: 'blocked_domains', type: 'array', required: false, description: '黑名单域名', items: { name: 'd', type: 'string', required: true, description: '域名' } },
+        { name: 'html_extraction_method', type: 'string', required: false, description: 'HTML 提取方法 (e.g. "text"/"markdown")' },
+        { name: 'is_zdr', type: 'boolean', required: false, description: '是否 Zero Data Retention 请求 (true 时不记录 URL)' },
+        { name: 'text_content_token_limit', type: 'integer', required: false, description: 'token 限制', minimum: 0 },
+        { name: 'web_fetch_pdf_extract_text', type: 'boolean', required: false, description: '是否提取 PDF 文本' },
+        { name: 'web_fetch_rate_limit_key', type: 'string', required: false, description: '速率限制键' },
+        { name: 'web_fetch_rate_limit_dark_launch', type: 'boolean', required: false, description: '速率限制暗启动模式' },
+    ],
+    callExample: `[TOOL:web_fetch]
+[P:url]https://example.com/article
+[ENDTOOL]`,
+    layerId: 'tool.manifest',
+};

package/dist/network/p2p-direct.js

@@ -64,6 +64,29 @@ export class P2PDirect extends EventEmitter {
             conn.on('data', (chunk) => {
                 const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
                 console.log(`[P2PDirect:${this.name}] 收到数据 from ${remotePubKeyHex.substring(0, 12)}... (${buf.length} bytes)`);
+                // P-Action 3: untrusted-input scanner (默认 silence-on-fail + log-only)
+                // 包装层 跨机器 @-mention 代发 (已 WORKING) 不能 block-on-suspicion
+                try {
+                    // 动态 import 避免循环依赖 + 启动时加载
+                    // (lazy require to keep cold-start fast)
+                    // eslint-disable-next-line @typescript-eslint/no-var-requires
+                    const { scanInput, writeScanAudit, shouldHardBlock } = require('../security/input-scanner.js');
+                    const result = scanInput(buf, { source: 'p2p' });
+                    if (shouldHardBlock(result)) {
+                        console.warn(`[P2PDirect:${this.name}] 阻断恶意消息 from ${remotePubKeyHex.substring(0, 12)}... (verdict=${result.verdict}, threats=${result.threats.length})`);
+                        writeScanAudit(result, { fromPublicKey: remotePubKeyHex, blocked: true }).catch(() => { });
+                        return; // 不 emit('data'), 跨机中转不传播
+                    }
+                    if (result.verdict !== 'pass') {
+                        // log-only: 仍然 emit('data'), 但写 audit 留痕
+                        writeScanAudit(result, { fromPublicKey: remotePubKeyHex, blocked: false }).catch(() => { });
+                        console.log(`[P2PDirect:${this.name}] 输入扫描 verdict=${result.verdict} (${result.threats.length} threats) from ${remotePubKeyHex.substring(0, 12)}... (audit-only)`);
+                    }
+                }
+                catch (err) {
+                    // scanner 自身挂掉 → 静默, 不阻断
+                    console.warn(`[P2PDirect:${this.name}] input scanner failed (silent, fail-safe):`, err);
+                }
                 this.emit('data', {
                     data: buf,
                     fromPublicKey: remotePubKeyHex,

package/dist/network/source-intent-broadcaster.js

@@ -0,0 +1,203 @@
+/**
+ * source-intent-broadcaster.ts — 包装 P2PDirect, 收发 SourceIntentMsg
+ *
+ * 用法:
+ *   const p2p = new P2PDirect({ name: 'bolloon', role: 'source-agent' });
+ *   await p2p.start();
+ *   const sb = new SourceIntentBroadcaster(p2p, { agent: 'agent-A@mac1' });
+ *   await sb.start();
+ *
+ *   // 我方要改 src/foo.ts 行 42-50
+ *   const conflict = await sb.reserve({ taskId, file: 'src/foo.ts', lines: [42, 50] });
+ *   if (conflict) {
+ *     // 对方已 reserve, 选: 让出 / 改别的 / 强制
+ *   } else {
+ *     sb.writeFileAndCommit(...);
+ *     await sb.broadcastCommitIntent({ taskId, file, lines, sha, diffHash });
+ *   }
+ *
+ * 主题: 复用现有 'bolloon-agent-harness' topic (P2PDirect 已 join),
+ *       上层加 'source-intent:' 前缀避免和别的协议混.
+ */
+import { EventEmitter } from 'events';
+import { ReserveLock, } from './source-intent.js';
+export class SourceIntentBroadcaster extends EventEmitter {
+    p2p;
+    agent;
+    topic;
+    waitMs;
+    lock = new ReserveLock();
+    started = false;
+    dataHandler = null;
+    constructor(p2p, opts) {
+        super();
+        this.p2p = p2p;
+        this.agent = opts.agent;
+        this.topic = opts.topic || 'bolloon-agent-harness';
+        this.waitMs = opts.waitMs ?? 200;
+    }
+    async start() {
+        if (this.started)
+            return;
+        // 确保 p2p 已 join topic
+        await this.p2p.joinTopic(this.topic);
+        this.dataHandler = (data, from) => {
+            try {
+                const text = data.toString('utf8');
+                // 协议前缀 'source-intent:'
+                if (!text.startsWith('source-intent:'))
+                    return;
+                const json = text.slice('source-intent:'.length);
+                const msg = JSON.parse(json);
+                this.onMessage(msg, from);
+            }
+            catch (err) {
+                // 静默忽略非本协议消息
+            }
+        };
+        this.p2p.on('data', this.dataHandler);
+        this.started = true;
+    }
+    stop() {
+        if (!this.started)
+            return;
+        if (this.dataHandler)
+            this.p2p.off('data', this.dataHandler);
+        this.started = false;
+    }
+    /**
+     * 申请 reserve (file, lines).
+     * 返回 {ok:true} → 成功 (没有重叠)
+     * 返回 {ok:false, existing} → 本地 lock 已有重叠, LLM 决定让出 / 改方向 / 强制
+     */
+    async reserve(args) {
+        const now = Date.now();
+        const msg = {
+            type: 'reserve',
+            taskId: args.taskId,
+            agent: this.agent,
+            file: args.file,
+            lines: args.lines,
+            expiresAt: now + ReserveLock.TTL_MS,
+            ts: now,
+        };
+        // 1. 先查本地 lock: 本端/远端任何 reserve 重叠都立即冲突 (避免 [5,15] 漏检 [1,10])
+        const existing = this.lock.isReserved(args.file, args.lines);
+        if (existing) {
+            return { ok: false, existing: { agent: existing.agent, lines: existing.lines } };
+        }
+        // 2. 写本地 lock
+        this.lock.add({
+            taskId: msg.taskId,
+            agent: msg.agent,
+            file: msg.file,
+            lines: msg.lines,
+            expiresAt: msg.expiresAt,
+            ts: msg.ts,
+        });
+        // 3. 广播
+        this.broadcastMsg(msg);
+        // 4. 等待 waitMs 看远端是否 ack 同一区间
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.off('remoteConflict', onRemote);
+                resolve({ ok: true });
+            }, this.waitMs);
+            const onRemote = (existing) => {
+                clearTimeout(timer);
+                resolve({ ok: false, existing });
+            };
+            this.once('remoteConflict', onRemote);
+        });
+    }
+    /** 释放我方 reserve */
+    release(args) {
+        const msg = {
+            type: 'release',
+            taskId: args.taskId,
+            agent: this.agent,
+            file: args.file,
+            lines: args.lines,
+            ts: Date.now(),
+        };
+        this.lock.release(args.file, args.lines);
+        this.broadcastMsg(msg);
+    }
+    /** commit 后广播, 供对方做轻量审计 (diffHash 验真伪) */
+    async broadcastCommitIntent(args) {
+        const msg = {
+            type: 'commit-intent',
+            taskId: args.taskId,
+            agent: this.agent,
+            file: args.file,
+            lines: args.lines,
+            sha: args.sha,
+            diffHash: args.diffHash,
+            ts: Date.now(),
+        };
+        this.broadcastMsg(msg);
+    }
+    /** 取所有 live reserves (给 pi-ai 注入到 LLM 系统 prompt) */
+    liveReserves() {
+        return this.lock.live();
+    }
+    // ---- 内部 ----
+    broadcastMsg(msg) {
+        const text = 'source-intent:' + JSON.stringify(msg);
+        this.p2p.broadcast(Buffer.from(text, 'utf8'));
+    }
+    onMessage(msg, from) {
+        // 忽略自己发出的消息 (P2PDirect 自身会发到自己的 loopback)
+        if (msg.agent === this.agent)
+            return;
+        switch (msg.type) {
+            case 'reserve': {
+                // 检查本地是否已 reserve 重叠区间
+                const existing = this.lock.isReserved(msg.file, msg.lines);
+                if (existing) {
+                    // 我方有重叠, 对方也 reserve → 触发 conflict
+                    this.emit('remoteConflict', { agent: msg.agent, lines: msg.lines });
+                    // 自己也回一个 ack 让对方知道我方已 reserve
+                    const ack = {
+                        type: 'ack',
+                        taskId: existing.taskId,
+                        agent: this.agent,
+                        file: existing.file,
+                        lines: existing.lines,
+                        ts: Date.now(),
+                    };
+                    this.broadcastMsg(ack);
+                }
+                // 记入 lock (远端的 reserve 我方也要避开, LLM 看 prompt 知道)
+                this.lock.add({
+                    taskId: msg.taskId,
+                    agent: msg.agent,
+                    file: msg.file,
+                    lines: msg.lines,
+                    expiresAt: msg.expiresAt,
+                    ts: msg.ts,
+                });
+                this.emit('remoteReserve', msg);
+                break;
+            }
+            case 'ack': {
+                // 远端 ack 我方已 reserve 同一区间 → 立即触发 conflict
+                const local = this.lock.isReserved(msg.file, msg.lines);
+                if (local) {
+                    this.emit('remoteConflict', { agent: msg.agent, lines: msg.lines });
+                }
+                break;
+            }
+            case 'release': {
+                this.lock.release(msg.file, msg.lines);
+                this.emit('remoteRelease', msg);
+                break;
+            }
+            case 'commit-intent': {
+                this.lock.release(msg.file, msg.lines);
+                this.emit('remoteCommit', msg);
+                break;
+            }
+        }
+    }
+}

package/dist/network/source-intent.js

@@ -0,0 +1,100 @@
+/**
+ * source-intent.ts — 行级 P2P 协作: 类型 + reserve.lock
+ *
+ * 为什么: 两台机上的智能体要协作维护同一份源码仓库, 粗粒度 task 协调不够
+ * (同一文件不同行会冲突). 用行级 reserve 让 LLM 在改前先广播"我要改 X 行",
+ * 对方看到重叠可让出/改方向/强制 merge.
+ *
+ * 数据流 (P2P RPC 消息, 走现有 P2PDirect.broadcast):
+ *   reserve  →  我方申请改 file:[start,end]
+ *   ack      →  对方也在这区间, 互相知道, 等 commit-intent 时看谁先到
+ *   release  →  我方放弃 (LLM 决定改别的行)
+ *   commit-intent → 我方 commit 后广播, 附 diffHash, 对方用 diffHash 验真伪
+ *
+ * 兜底:
+ *   - TTL 5min, reserve 不 release 就过期
+ *   - 200ms 等待 + 检冲突, 极端 race 双方都收到 conflict, LLM 自己重选
+ *   - diffHash 不去判语义, 行级 merge 后 lefthook 失败 → revert
+ */
+import { EventEmitter } from 'events';
+/**
+ * 检测两个 LineRange 是否重叠.
+ * 规则: 任一区间的一端落在对方区间内 → 重叠.
+ * 不重叠示例: [1,5] vs [6,10] (边界相邻不算重叠).
+ */
+export function rangesOverlap(a, b) {
+    return a[0] <= b[1] && b[0] <= a[1];
+}
+/**
+ * ReserveLock — 本地内存表, 记录"我方 + 远端"所有 live reserves.
+ *
+ * 事件:
+ *   'added'    新增 reserve (我方或远端)
+ *   'removed'  reserve 被释放 / 过期
+ *   'conflict' 检测到重叠 (a,b)
+ */
+export class ReserveLock extends EventEmitter {
+    /** key = `${file}:${start}-${end}` */
+    byKey = new Map();
+    /** TTL: 5 min, 兜底防止对方死掉/网络断后 reserve 永远不释放 */
+    static TTL_MS = 5 * 60 * 1000;
+    /** 清理过期 reserve, 触发 'removed' 事件 */
+    sweep(now = Date.now()) {
+        for (const [k, r] of this.byKey) {
+            if (r.expiresAt <= now) {
+                this.byKey.delete(k);
+                this.emit('removed', r);
+            }
+        }
+    }
+    /** 我方/远端 reserve, 仅清自己区间后写入 (不清全表, 避免过期 reserve 干扰 add 测试) */
+    add(r) {
+        const key = keyOf(r.file, r.lines);
+        const prev = this.byKey.get(key);
+        this.byKey.set(key, r);
+        if (prev) {
+            // 同一区间已被对方 reserve, 我方再 reserve → 触发冲突
+            this.emit('conflict', { a: prev, b: r });
+        }
+        else {
+            this.emit('added', r);
+        }
+    }
+    /** 释放指定 reserve (我方 LLM 决定让出时调用) */
+    release(file, lines) {
+        const key = keyOf(file, lines);
+        const r = this.byKey.get(key);
+        if (!r)
+            return null;
+        this.byKey.delete(key);
+        this.emit('removed', r);
+        return r;
+    }
+    /** 查询某 (file, lines) 是否已被 reserve (含我方) */
+    isReserved(file, lines, now = Date.now()) {
+        this.sweep(now);
+        for (const r of this.byKey.values()) {
+            if (r.file === file && rangesOverlap(r.lines, lines)) {
+                return r;
+            }
+        }
+        return null;
+    }
+    /** 取所有 live reserves (给 pi-ai 注入到系统 prompt) */
+    live(now = Date.now()) {
+        this.sweep(now);
+        return [...this.byKey.values()];
+    }
+    /** 调试: dump 全部 */
+    dump() {
+        return [...this.byKey.values()];
+    }
+}
+function keyOf(file, lines) {
+    return `${file}:${lines[0]}-${lines[1]}`;
+}
+/** 算 diffHash (git diff 的 sha256 前 16 字符) */
+export function diffHashOf(diffText) {
+    const crypto = require('crypto');
+    return crypto.createHash('sha256').update(diffText, 'utf8').digest('hex').slice(0, 16);
+}