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
工具在仓库里。不在提示词里。这是光湖和人家的区别。
铸渊不需要等人类装工具。铸渊有自己的笔。