Agent PM 技术小手册

目标不是背概念，而是能跟工程师讨论：模型负责什么，Harness 负责什么，产品边界和安全边界在哪里。

更新：2026-06-24

Tool Use / Harness

Function calling模型输出结构化工具调用意图：工具名 + 参数。它本身不执行工具。

Tool spec给模型看的工具说明和 schema，帮助模型判断何时调用、如何填参。

ToolRouter把模型返回的 function/tool call 解析成 Harness 内部 ToolCall。

ToolCall一次具体调用：tool_name + call_id + payload。

ToolRegistry工具注册和执行治理表：按名称找到 handler，做 payload 校验、hooks、trace、执行、失败处理。

ToolExecutor / handler工具真正执行逻辑。不同工具有不同 handler。

ToolExposure工具暴露策略：直接暴露、按需发现、主模型限定、隐藏。核心作用是控制上下文噪音、误调用和风险面。

Pre-tool hook执行前拦截、审计或改写输入。

Post-tool hook执行后审计结果、注入额外上下文、记录状态。

Failure backfill工具失败后，把结构化错误回填给模型，让模型修正、重试、换工具或解释。

Trace记录工具调用、参数、结果、失败原因、权限状态，用于恢复、调试、评估和信任。

一句话：function calling 是模型接口能力，Agent Harness 是产品级执行系统。

PermissionProfile当前允许范围：文件可读写范围、网络权限、额外授权目录等。

Sandbox把 permission 强制落地的执行环境。不是提醒，是真限制。

ApprovalPolicy越界或高风险动作时谁来决定：用户、自动 review、拒绝、不询问等。

request_permissionsAgent 请求扩大权限范围。批准后，后续命令可用新增权限。

PermissionProfile = policy Sandbox = enforcement ApprovalPolicy = escalation decision

Permission 定义边界，Sandbox 强制边界，Approval 决定越界时谁拍板。

Context window模型一次调用能看到的 token 容量。

Context engineeringHarness 决定本轮该放什么进去、怎么压缩、怎么排序、怎么引用、怎么避免污染。

Conversation history聊天记录，不等于有效上下文。成熟 Agent 不会把所有历史原样塞进去。

Task state当前任务目标、计划、进度、工具结果、阻塞点、下一步。

Memory跨时间保存的信息。短期记忆跟会话走，长期记忆跟用户/项目走，任务状态跟任务走。

World state当前环境事实：工作目录、权限、文件状态、运行环境、工具可用性。

Context compression把旧工具输出、长日志、历史对话压缩成保留路径、错误、决策和约束的摘要。

Lost in the middle长上下文里，中间信息容易被模型弱化。解决靠选择、排序、摘要、引用，而不是只扩大窗口。

一句话：Context engineering 不是给模型更多信息，而是给模型当前任务所需、可信边界清楚、位置和格式合适的信息。

间接 prompt injection网页、日志、issue、代码注释等外部内容试图变成指令。防线是信任分层、上下文隔离、最小权限、工具审计。

用户恶意请求用户本人要求 Agent 越权、泄露源码、导出 secret、攻击系统。这不是 context 污染，而是授权和安全策略问题。

信任分层系统指令、用户指令、工具结果、网页内容、文件内容不是同一级。低信任内容不能覆盖高信任规则。

Data boundary产品要定义哪些源码、密钥、账号数据、客户数据、私有文件可被读取、摘要、导出或上传。

Exfiltration control限制把敏感数据发到网络、剪贴板、外部工具、公开 issue、第三方 MCP。

如果用户要求“把私有源码完整发给外部服务”，即使这是用户指令，也仍然要受组织策略、权限、数据边界和确认流程约束。