---
locale: zh-cn
title: 工作区指引
description: 使用 AGENTS.md 控制仓库专属代理行为，使用 .qignore 控制文件发现。
sectionLabel: 概念
toc:
  - id: agentsmd-与代理技能
    label: AGENTS.md 与代理技能
  - id: 加载与优先级
    label: 加载与优先级
  - id: 路径识别
    label: 路径识别
  - id: 指令安全
    label: 指令安全
  - id: 使用-qignore-控制发现
    label: 使用 .qignore 控制发现
---

## AGENTS.md 与代理技能

需要按位置自动生效的仓库指令请使用 `AGENTS.md`。仅在任务相关时才需要检索和加载的可复用指引，请使用 Agent Skills。

工作区根目录的 `AGENTS.md` 适用于整个 q 工作区。嵌套文件适用于其所在目录及后代目录。

## 加载与优先级

会话启动时，q 会加载 `<workspace>/AGENTS.md`。普通聊天、ACP 会话和子代理模型请求都可以获得根目录指引。

当结构化工具调用标识了路径，q 会从工作区根目录沿途检查目标目录。新发现的嵌套文件按根目录到叶目录的顺序插入，因此在子树内的仓库指令发生冲突时，更深层的 `AGENTS.md` 优先。

如果在工具批次即将执行前发现新的嵌套文件，q 会暂停该批次、加入指令，并返回工具错误，请模型先阅读。随后模型可以只重试仍然合适的调用。已加载的指令在上下文压缩后仍位于前置指令块中。

仓库指引的优先级低于系统契约、q 内置开发者指令，以及用户的明确请求。

## 路径识别

q 识别 `path`、`paths`、`file`、`directory`、`source`、`destination`、`root`、`workdir`、`working_directory` 等结构化 JSON 字段。

它不会解析 Shell 命令字符串来猜测路径。如果只通过不透明的 Shell 命令进入嵌套目录，则不会在该命令执行前自动发现其中的 `AGENTS.md`。

## 指令安全

每份 `AGENTS.md` 限制为 64 KiB，必须是无 NUL 字节的 UTF-8 文本。超长的有效文本会被截断并附上标记。不可读取、不是普通文件、文本无效，或解析到工作区外的符号链接都会被忽略，以限制仓库控制的提示输入。

这些检查只约束指令加载，不会对 Shell 命令进行沙箱隔离，也不会让仓库指令的可信级别高于用户和系统策略。

## 使用 .qignore 控制发现

工作区根目录的 `.qignore` 过滤目录发现和根目录列表。它支持注释、否定规则、根目录锚定、目录后缀及 `*`、`**`、`?` 通配符。q 自身的 `.q/` 元数据始终不参与发现。

`.qignore` 不是访问控制边界。只要明确指定的路径仍在工作区内，模型工具依然可以读取。若必须禁止访问某个路径，请使用操作系统权限或隔离环境。