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