# 上下文、工具与权限

> 控制 Agent 能看见什么、调用什么，以及何时需要你的明确授权。

Canonical page: /core/context-tools-and-permissions



<Takeaways>
  <li>
    上下文、工具和权限是三件分开呈现的事
  </li>

  <li>
    引用具体文件，而不是模糊描述
  </li>

  <li>
    先用沙盒和单次授权验证任务
  </li>
</Takeaways>

任务质量取决于三件事：给了哪些上下文、允许使用哪些工具，以及动作是否越过当前权限边界。Astravia 将这三部分分开呈现，便于在效率和风险之间做明确选择。

## 组成一次模型调用的上下文 [#组成一次模型调用的上下文]

<Panel>
  <PanelGroup title="你提供">
    <PanelItem title="当前任务">
      直接输入目标、约束和验收条件
    </PanelItem>

    <PanelItem title="项目文件">
      `@`

       引用或由工具读取源码、配置、文档和数据
    </PanelItem>

    <PanelItem title="图片">
      粘贴或添加截图、界面和视觉参考
    </PanelItem>

    <PanelItem title="项目指令">
      项目中的 

      `AGENTS.md`

      ，保存长期规则
    </PanelItem>
  </PanelGroup>

  <PanelGroup title="系统接入">
    <PanelItem title="技能 / 场景">
      输入 

      `/`

       选择可复用方法和工作模式
    </PanelItem>

    <PanelItem title="知识库">
      本轮开启知识检索，使用跨项目长期资料
    </PanelItem>

    <PanelItem title="插件 / MCP">
      启用对应能力，接入外部工具和数据
    </PanelItem>
  </PanelGroup>
</Panel>

输入区的上下文圆环显示最近一次模型调用的使用量。展开后可以检查基础指令、扩展能力、工具 Schema、历史消息和当前输入分别占用了多少上下文。

## 引用文件而不是模糊描述 [#引用文件而不是模糊描述]

需要 Agent 依据具体材料时，直接引用文件并说明用途：

<Plate no="01" title="带引用的任务">
  ```text
  阅读 @src/auth/login.ts 和 @test/auth/login.test.ts。
  定位无效刷新令牌仍被接受的原因，只修改认证模块，补充回归测试。
  完成后运行认证测试并汇报实际结果。
  ```
</Plate>

外部拖入的图片会作为附件；其他文件通常作为引用。项目内文件引用不会复制一份新的事实源。

## 工具与执行模式 [#工具与执行模式]

Astravia 的工具可以读取和编辑文件、执行命令、搜索内容、维护待办，也可以由插件或 MCP 提供额外动作。

<Fork>
  <ForkPane kicker="DEFAULT" title="沙盒受限">
    <li>
      只允许工作区受限访问
    </li>

    <li>
      适合来源不确定的项目、首次试跑
    </li>

    <li>
      不需要访问项目外资源时优先使用
    </li>

    <li>
      平台缺少可用沙盒后端时，界面会说明原因
    </li>
  </ForkPane>

  <ForkPane kicker="ELEVATED" title="完全访问">
    <li>
      允许访问当前系统中更广的文件和进程
    </li>

    <li>
      适合明确需要跨目录或系统工具的任务
    </li>

    <li>
      应确认提示词、项目和扩展来源可信
    </li>

    <li>
      不要把它当成默认模式
    </li>
  </ForkPane>
</Fork>

默认执行模式在「设置 → 通用设置」中配置，只影响之后新建且未单独选择模式的会话，不会改变已经打开的会话。

## 处理权限请求 [#处理权限请求]

<MediaFrame>
  <img src="/images/product/permission-choice.webp" alt="Astravia 在执行过程中请求用户选择和确认" width="900" height="1640" />

  <figcaption>
    需要用户决策或高影响动作时，Astravia 把选择放回执行过程，而不是隐藏处理。
  </figcaption>
</MediaFrame>

输入区的权限抽屉会列出等待确认的请求：

<Entries>
  <Entry kicker="ONCE" title="允许本次">
    只授权当前请求。
  </Entry>

  <Entry kicker="SESSION" title="本会话不再询问">
    当前会话后续同类请求直接允许。
  </Entry>

  <Entry kicker="DENY" title="拒绝">
    不执行该动作，Agent 会收到拒绝结果。
  </Entry>
</Entries>

确认前至少检查目标路径、命令、网络目的地和动作是否可撤回。不要因为任务来自可信项目就自动批准所有外部工具调用。

## 外部能力是新的信任边界 [#外部能力是新的信任边界]

技能会影响任务方法，插件可以扩展宿主界面和 Agent 能力，MCP 可以连接外部进程或服务。安装或启用前检查来源、权限和配置；凭证只填写在专用设置界面，不放进任务、项目文件或问题报告。

<Callout type="warn" title="最小权限优先">
  先用沙盒和单次授权验证任务。只有确实需要跨工作区访问时再切换完全访问，只有稳定且明确的同类动作才考虑会话级授权。
</Callout>