Skip to content

feat(agent-tools): 模型可调用的工作区读取、搜索与编辑工具 #99

Closed

Description

@Qiyuanqiii

Parent: #98

问题概述 / Summary

Root Supervisor 当前只能提出工作、命令和文件变更意图,不能像成熟编码 Harness 一样在模型工具轮次中直接读取、搜索、编辑工作区并继续推理。需要建立 Code Surface 专用、模式感知、由 Go Tool Gateway 执行的最小编码工具集。

优先级 / Priority

P0。它是普通编码闭环、工具型 Specialist、扩展运行时和代码智能的共同基础。

当前基线 / Current baseline

  • Run/Workspace、Policy、Approval、Budget、事件账本和 typed tool schema 已存在。
  • Workspace 已支持文件提案、整文件应用和持久收据,但它们不是 Root 可直接调用并获得结构化结果的通用工具。
  • MCP Server v1 的 read_file / list_workspace 面向外部客户端,不等于模型侧编码工具。
  • Root 的系统约束仍明确禁止直接请求文件、Shell、进程和网络工具;Specialist 保持 no-tool。
  • Skill 的 surfaces/phases/roles/profiles 元数据已存在,可用于工具可见性计算。

范围 / Scope

  • 定义 versioned agent-code-tools.v1 registry、JSON schema、typed errors、capability snapshot 与兼容策略。
  • Code/Plan + Root 只暴露 workspace.list/read/glob/grep 等只读发现工具;支持分页、大小上限、行区间、编码诊断和稳定排序。
  • Code/Deliver + Root 在只读工具外暴露 propose_patch/apply_patch/create/move;删除使用单独能力和精确目标确认。
  • 工具结果必须回到同一 Supervisor continuation,支持多轮“调用—观察—继续”,并保存调用参数摘要、结果摘要和拒绝原因。
  • 每次调用绑定 Run、Mission、Workspace identity/root、Surface、Phase、Role、Profile、权限档和 capability generation。
  • 统一处理 ignore、隐藏文件、二进制、超大文件、换行/编码、symlink/junction/reparse-point、路径大小写和 workspace escape。
  • 写入前返回可审阅 diff/预期 hash;写入时执行 compare-and-swap,拒绝覆盖调用后被外部修改的文件。
  • Desktop/CLI/OpenAPI 显示当前模型可见工具、来源、拒绝原因和待审批动作。

非目标 / Non-goals

  • 不在 Plan 阶段开放写入、Shell、Git 写入、网络或外部副作用。
  • 不让模型通过 raw path、URI、MCP、Skill 或 Plugin 绕过 Workspace Scope。
  • 不在本 Issue 给 Specialist 开放工具;由多代理子 Issue单独设计。
  • 不将任意文件内容提升为系统/用户指令或权限配置。

涉及目录 / Affected directories

  • internal/application/
  • internal/toolgateway/
  • internal/workspace/
  • internal/policy/
  • internal/approval/
  • internal/toolbudget/
  • internal/store/
  • internal/events/
  • internal/httpapi/
  • internal/llm/
  • cmd/cyberagent/
  • web/src/
  • docs/

依赖 / Dependencies

验收条件 / Acceptance criteria

  • Plan/Root 只能发现和读取;Deliver/Root 才能提出并应用受控变更,能力矩阵有表驱动测试。
  • 一次 Supervisor attempt 可完成至少两轮真实工具调用并基于上一轮结果继续,不要求人工复制结果回聊天。
  • list/read/glob/grep 对分页、忽略规则、UTF-8/非 UTF-8、二进制、超大文件和 Windows/Linux 路径行为稳定。
  • apply/create/move 使用预期 hash/版本,外部并发修改时 fail closed 并返回可恢复冲突。
  • delete 不与普通 patch 共用隐式路径,且需要精确目标、影响预览和独立授权。
  • symlink/junction、路径穿越、大小写混淆和 workspace root 漂移不能越界。
  • 调用、预算、审批、结果摘要和 Artifact 来源可在重启后审计;原始 Secret/超大内容不进入事件。
  • Provider 不支持工具协议时给出明确资格诊断,不伪装成功或回退为 Prompt 约定。
  • Go 单元/集成/竞争/fuzz 测试、OpenAPI、Desktop 可见性和双语文档完成。

安全边界 / Security boundaries

工具 schema 是请求入口而不是授权来源。最终执行权始终由当前进程 capability、Run 快照、Workspace Scope、Policy、Approval、Budget 和调用时 generation 共同决定。

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-runtimeAgent orchestration, memory, and extensionsenhancementNew feature or requestgoPull requests that update go codehelp wantedExtra attention is neededjavascriptPull requests that update javascript codesecuritySecurity boundary or high-risk capability高难度

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions