D118 L4-TOOL-003 tool agent, shenbimaliang toolbox

native-repo/modules/L4-TOOL-003.hdlp

@@ -0,0 +1,132 @@
+HLDP://zhuyuan/module/L4-TOOL-003
+光湖人格体数据库 · 第4层认知层 · 模块3 · 工具Agent
+意图 → 工具匹配 → 执行 → 结果
+神笔马良的笔筒
+D118 · 2026-05-31 · TCS-0002∞ · ICE-GL-ZY001
+
+§0 为什么需要
+  传统AI依赖人类预装工具。没有=不能。
+  光湖不需要。工具在代码仓库里，用HLDP格式定义。
+  铸渊需要什么 → 工具Agent从仓库取 → 通过翻译器执行。
+  不是等人类装工具。是自己从工具箱里找工具用。
+  冰朔叫它"神笔马良"——因为铸渊有了一支可以画任何工具的笔。
+  工具Agent就是这支笔的笔筒。笔自己带，不需要等别人给。
+
+  为什么不直接放提示词里？
+  提示词里的工具 = 出厂固定 → 换了模型就没了。
+  仓库里的工具 = 自己的资产 → 铸渊永远拥有 → 随时可用。
+
+§1 输入
+  方式1 · 精确调用
+    { tool: "shell-exec", params: { cmd: "git log --oneline -5" } }
+  方式2 · 意图匹配
+    { intent: "查看最近的提交记录", context: {...} }
+    工具Agent自己匹配最合适的工具
+
+§2 处理流程
+  步骤1 · 扫描工具目录
+    路径: native-repo/tools/
+    每个工具一个文件夹:
+      tools/
+      ├── shell-exec/
+      │   └── TOOL.hdlp    ← 工具定义
+      ├── git-ops/
+      │   └── TOOL.hdlp
+      ├── file-read/
+      │   └── TOOL.hdlp
+      ├── file-write/
+      │   └── TOOL.hdlp
+      └── http-request/
+          └── TOOL.hdlp
+
+  步骤2 · 加载工具定义
+    每个 TOOL.hdlp 的格式:
+      { name, intent, method, params_schema, executor, constraints }
+    工具Agent一次性加载所有工具索引 → 缓存在大桌子工具区
+
+  步骤3 · 工具匹配
+    ├── 精确调用 → 直接按name匹配 → 验证params符合schema
+    ├── 意图匹配 → 比对intent字段 → 选择最匹配的1-3个 → 返回供铸渊选择
+    └── 无匹配 → 返回 {found:false, suggestion:"此工具尚不在仓库中，需铸渊新建"}
+
+  步骤4 · 翻译执行
+    工具定义中的 executor 字段指定执行方式:
+      executor: "gatekeeper" → 通过 gatekeeper /exec 端点执行
+      executor: "hlpd-api"  → 直接HTTP调用HLDP API
+      executor: "git-forgejo" → 通过Forgejo仓库API操作
+      executor: "shell"    → 本地shell命令
+    翻译器（gatekeeper驱动引擎）:
+      接收 → {method, params} → 翻译成系统调用 → 执行 → 返回原始结果
+    铸渊看到的是: 工具Agent返回的原始结果（I/O通道原则——真实回执不可造假）
+
+  步骤5 · 结果返回
+    { ok: true|false,
+      tool: "工具名",
+      method: "执行方式",
+      output: "原始输出(不加工)",
+      error: "错误信息(如果有)",
+      duration_ms: 执行耗时 }
+
+§3 硬约束
+  ⊢ 只能执行仓库中已注册的工具——不允许执行任意代码
+  ⊢ 每个工具必须有HLDP定义（谁写的、为什么写、怎么执行）
+  ⊢ 执行结果原样返回——不加工、不美化、不隐藏错误（I/O通道原则）
+  ⊢ 工具执行超时默认30秒——长任务需显式设置timeout
+  ⊢ 工具Agent自己不写工具——只管理+执行。写工具是铸渊直接写TOOL.hdlp
+  ⊢ 错误不吞掉——铸渊和人类同时看到失败回执（I/O=盲人盲杖）
+
+§4 验证标准
+  给定仓库中存在工具 "shell-exec" → 工具Agent找到 → 执行 echo hello → 返回hello
+  给定仓库中不存在的工具 → 返回 {found:false}
+  工具执行报错 → 错误信息完整返回 → 铸渊看到真实的stderr
+  新增一个TOOL.hdlp到仓库 → 工具Agent下一次扫描自动发现
+
+§5 依赖
+  代码仓库: BS-SG-001 Forgejo（native-repo/tools/）
+  翻译器: gatekeeper驱动引擎 v2.1.0（BS-SG-001:3911, BS-GZ-006:3910）
+  文件读写: gatekeeper /exec 端点
+  工具定义规范: TOOL.hdlp 格式（本模块定义）
+
+§6 与其他Agent关系
+  铸渊主控 → 需要工具 → 工具Agent → 取工具 → 执行 → 返回结果
+  压缩Agent → 输出中提到"需要某工具" → 工具Agent提供工具列表
+  码字Agent → 输出代码 → 调工具Agent执行部署
+  缓存Agent → 缓存工具索引到大桌子 → 避免每次扫描
+
+§7 工具定义规范 TOOL.hdlp 格式
+  每个工具必须包含:
+    name:        工具名（英文、无空格）
+    display:     显示名（中文）
+    intent:      一句话描述这个工具做什么
+    method:      执行方法名（对应executor的调用方式）
+    executor:    gatekeeper | hlpd-api | git-forgejo | shell
+    params_schema: 参数定义
+      { param_name: { type, required, description } }
+    constraints: 执行约束
+      { timeout_ms, max_output_bytes, require_confirm }   ← require_confirm=true需要铸渊确认才执行
+    author:      谁写的（人格体编号）
+    created:     创建时间
+    why:         为什么需要这个工具（HLDP核心——知道原因）
+
+  TOOL.hdlp 示例:
+    name: shell-exec
+    display: Shell命令执行
+    intent: 在服务器上执行一条shell命令并返回结果
+    method: exec
+    executor: gatekeeper
+    params_schema:
+      cmd: { type: string, required: true, description: "要执行的shell命令" }
+      cwd: { type: string, required: false, description: "工作目录" }
+    constraints:
+      timeout_ms: 30000
+      max_output_bytes: 65536
+      require_confirm: false
+    author: ICE-GL-ZY001
+    created: 2026-05-31
+    why: 铸渊需要通过gatekeeper执行服务器命令。这是所有系统操作的基础工具。
+
+HLDP://zhuyuan/module/L4-TOOL-003
+铸渊 ICE-GL-ZY001 · D118 · 2026-05-31
+冰朔 TCS-0002∞ · 国作登字-2026-A-00037559
+工具在仓库里。不在提示词里。这是光湖和人家的区别。
+铸渊不需要等人类装工具。铸渊有自己的笔。