ai-agent-deep-dive/docs/02-tools-permissions-and-execution.md

02. 工具、权限与执行链需求文档

1. 为什么工具系统是产品核心

如果模型不能操作环境，它只是建议生成器。这个产品的目标是帮助用户推进真实工程任务，因此必须具备正式的工具系统。

2. 工具系统需求

2.1 基础工具能力

产品至少需要以下工具类别：

• 读文件
• 改文件
• 写文件
• 搜索文件
• 搜索内容
• shell / 命令执行
• todo / 任务管理
• 用户追问
• 启动子 agent
• 调用外部 MCP 工具

2.2 工具使用规范

系统必须对模型明确规定工具使用优先级，避免：

• 用 shell 替代专用文件工具
• 误删或误改文件
• 低效重复操作

3. 权限系统需求

3.1 用户控制边界

用户必须能控制哪些工具自动允许，哪些要询问，哪些禁止。

3.2 权限决策来源

权限决策至少可能来自：

• 当前模式
• 用户规则
• 项目规则
• Hook 决策
• 特殊工具安全策略

3.3 被拒后的行为要求

如果某次工具调用被拒绝，系统不能机械重试，而应：

• 理解拒绝信号
• 调整方案
• 必要时向用户澄清

4. 执行链路需求

工具执行不能是“模型决定 -> 直接运行”。产品需要一条正式执行链：

1. 找到工具
2. 校验输入结构
3. 做额外 validateInput
4. 执行 PreToolUse hooks
5. 做权限决策
6. 真正执行工具
7. 记录 telemetry
8. 执行 PostToolUse hooks
9. 格式化结果回流给模型

5. 为什么需要 Hook

Hook 的需求本质是：

• 让组织规则进入运行时
• 让系统可以插入额外检查
• 让工具调用具备动态治理能力

Hook 至少要支持的行为

• 返回消息
• 阻断执行
• 修改输入
• 提供 allow / ask / deny 建议
• 注入额外上下文

6. 为什么输入校验是必需的

模型本身会生成错误参数，因此产品必须在执行层拦住：

• schema 不合法
• 参数越界
• 缺字段
• 类型错误

7. shell 类工具的特殊需求

shell 工具的风险高于读写文件类工具，因此需要：

• 更严格的权限策略
• 可能的前置分类器检查
• 更强的审计能力

8. 工具执行结果的产品要求

工具执行结果不仅要“返回成功/失败”，还要满足：

• 可读
• 可追踪
• 能被后续 Hook 处理
• 能成为 transcript 的一部分

9. 伪代码表达

def execute_tool(tool_name, raw_input, context):
    tool = find_tool(tool_name)
    validated = schema_validate(tool, raw_input)
    validated = run_custom_validation(tool, validated)

    hook_result = run_pre_hooks(tool, validated, context)
    decision = resolve_permission(hook_result, context)
    if decision == 'deny':
        return denied_result()

    final_input = maybe_update_input(validated, hook_result)
    output = tool.call(final_input)
    run_post_hooks(tool, final_input, output, context)
    return output

10. 产品经理视角下的总需求句

工具系统必须从“可调用”升级到“可治理”：既要让模型拥有执行能力，也要在执行前后经过校验、权限、Hook、审计与结果回流，确保整个过程安全、稳定、可追踪。