任务写入范围与变更归属
范围授权决定原生文件工具和受控扩展可操作的路径,归属记录区分任务改动与已有外部内容。父会话 Shell 不提供写入预检,见下文运行边界。
适用范围
Pi 负责写入授权、本地观测和完成门禁。智能体在交互式方案批准时一次性提出任务相关范围;仓库不实现范围脚本,也不维护独立允许列表。领域技能/规则说明任务需要哪些文件和检查。运行时不依赖前端框架或 test-tool 包。
这是本地审计和工作流门禁,不是操作系统沙箱。原生写入/编辑路径在执行前检查;任意 Shell 或扩展命令的真实写入集合无法从参数推断。批准范围内的已观测改动可自动继续;仅为实施补充路径且说明原因时可复用已批准方案。已有外部内容和已知冲突需要人工决定。这些命令可能影响观测边界之外的被忽略文件或外部系统。观测记录不证明改动作者,领域验证仍然适用。
工具与接口
wenext_approve({ writePaths?, includePaths?, excludePaths?, reason?,
acknowledgeInterruption?, acknowledgeHistory? })
wenext_scope({ action: "status" | "approve", writePaths?, includePaths?,
excludePaths?, reason?, acknowledgeInterruption?, acknowledgeHistory? })人工批准的方案未变时,wenext_scope approve 可携带具体 reason 和新增 writePaths,将路径合并到已有范围,无需再次调用审查器或打开界面。若目标、公共契约或质量要求发生变化(包括降低质量要求),模型必须先更新方案。这是工作流契约,不是对任意 JSON 编辑的自动语义证明。已有未提交内容、归属决定、历史冲突、审查证据缺失/撤销或方案摘要变化,不能使用这条路径。
实施范围修订在范围证据中持久化 kind=implementation_scope 和 planReviewApproval。任务的 approvedAt/approvedBy 及原始审查证据保持不变,不虚构人工或智能体判定。经校验的修订必须匹配任务、项目根、方案、writePaths 和精确的原批准。范围修订仍会使质量指纹失效。提交后的 Git 历史或归属确认若未改变方案与已批准范围,复用现有实施范围修订及原评审绑定;预览页展示实际扩展范围,不要求删掉已批准的测试/helper 路径。仍需确认历史变化,迟到确认、未授权扩权、损坏或撤销的评审证据继续拒绝。
其它新决定使用真实终端界面或 RPC 确认。若 wenext_scope approve 的路径未变,纳入/排除决定也已解决,则直接成功,不打开界面,不更新批准时间、修订号或证据。需要确认时,若没有界面、用户取消,或确认期间任务绑定、方案、范围证据、观测内容变化,都会拒绝。方案变化需要重新执行 wenext_approve;wenext_scope 只调整已批准方案的范围,不批准新的方案文本。
内部服务如下,不构成已发布的外部 SDK:
WriteScopeService.propose(directory, taskId, planDigest, decisions): ScopeProposal
WriteScopeService.commit(proposal, synchronousTaskValidation, implementationReview?): T
WriteScopeService.begin(directory, taskId, planDigest, sessionId, toolCallId, toolName, input): void
WriteScopeService.complete(sessionId, toolCallId, isError): void
WriteScopeService.inspect(directory): WriteScopeState | undefined
verifyWriteScope(root, directory, taskId, planDigest, required?): void行为约定
| 字段 | 含义 |
|---|---|
writePaths | 最多 64 个字面量项目相对文件/目录路径;不允许通配符、路径越界或符号链接。. 明确授权快照限制内的整个项目。首次批准时省略表示不允许项目写入,修订时省略则保留已有路径。 |
includePaths | 批准范围内最多 10000 个精确文件,由人工明确纳入其当前内容,包括预存或归属不明确的改动。必须说明原因。 |
excludePaths | 保留为任务外部内容的精确已改文件;后续原生写入持续阻断,直到纳入。必须说明原因。 |
reason | 纳入/排除、中断/历史确认的非空说明。 |
acknowledgeInterruption | 解决涉及待决范围或冲突的中断,不将其标为成功。普通范围内恢复无需人工确认。 |
acknowledgeHistory | 确认 Git HEAD 或可用性变化;已改文件仍需纳入/排除。 |
以下为智能体调用示例,随后进行一次人工确认:
{ "writePaths": ["packages/example/src", ".agents/rules/example.md"] }在批准范围内实施无需重复询问。原生 write 内容及 SDK 精确、互不重叠的 edit.edits[] 结果会与请求比较,包括 BOM 和换行符。成功且匹配的差异标为 native_write,证明的是已观测操作的结果,不是整个文件的作者归属。批准路径内的模糊编辑、工具失败后的部分改动、Shell 和未知工具改动记为 scope_observed,表示受既有授权覆盖,不证明作者或工具成功。人工纳入标为 human_confirmed,不能冒充原生写入。
若旧 unobserved_change、opaque_tool_change、failed_tool_change、interrupted_tool 待决项位于批准路径内、不属于外部内容且 Git 历史未变,观测会协调这些记录。范围修订号和任务批准保持不变,新的观测证据会改变质量指纹。未知待决原因和已知冲突继续保留。
首次方案批准会纳入 writePaths 内已有未提交文件,除非显式排除。后续批准保留排除决定,不会静默重新接管外部文件。原生结果/哈希不匹配,或原生工具已知目标之外的变化,标为 concurrent_write_conflict,后续观测不能抹去此原因。操作之间未观测到的编辑无法确认作者:授权覆盖的是范围内已观测工作,不是持续并发检测。
Git 快照包含声明的已跟踪/未跟踪文件、所有 Git 可见的未提交文件及之前观测过的文件。精确文件路径可纳入被忽略文件。非 Git 快照只覆盖声明路径,不透明扩展写入在这种情况下会被阻断。Shell 命令不经过此预检,因此只能观测声明快照内的改动。无版本控制时,不推断已有内容在任务开始前的作者归属。
扫描与写入分别校验。只读快照记录普通文件内容、缺失路径、符号链接位置及其链接文本,不跟随链接读取目标;历史子路径的父目录变成链接时也遵循同一规则。链接内容变化仍使证据变化,Git HEAD 变化仍需历史确认。无关链接可以用 excludePaths 排除,不再使整个状态扫描报写入越界;不能把链接自动纳入任务或使用 includePaths 获得穿透写权限。
维护规则与技能
.agents 不是禁止修改的目录。用户可以要求更新 .agents/rules、.agents/skills 等仓库源文件,将实际路径纳入方案和 writePaths,执行对应配置或技能契约检查。修改质量规则本身可以是合法任务;普通业务修复中擅自降低必需检查仍不允许。
若 .agents/skills/example 是链接,写入诊断会显示链接位置、目标及恢复方式。目标在仓内时,改用真实源路径并纳入写入范围;目标仍有链接时继续解析,直至普通源文件。目标在仓外时,应在所属项目中另行维护。不要通过 Shell 绕过范围约束。状态扫描能观察链接,不等于授权修改其目标。
依赖目录(node_modules、.git)及旧版生成的任务/工作区/运行时状态被排除。快照预算为 10000 个路径和五秒,每次 Git 探测超时为十秒。超预算会明确失败,智能体必须缩小范围。这不是持续文件系统监控,观测之间写入后又恢复的临时变化可能被遗漏。
私有状态仍位于仓库外的任务目录:
write-scope/state.json:模式版本 1,包含规范化项目根/任务/方案摘要、修订号、批准路径、哈希、外部/已归属/待决文件、中断/历史标记和可选进行中操作。write-scope/events/<uuid>.json:只追加的操作/批准证据,带有前序引用。当前状态根据其引用事件的哈希校验;这不是防范同用户篡改的签名账本。记录不保存源码内容或原始 Shell 命令。- 项目租约使协作 Pi 宿主的托管原生/扩展写入串行化,直到结果观测完成;Shell 不获取此租约。嵌套/并行托管写入按忙碌拒绝,只读子智能体独立继续。恢复从不重放写入。已退出的持有者或中断操作保留在观测证据中;范围内的部分输出允许在既有批准下继续编码。智能体必须检查部分输出,是否完成仍由质量检查决定。
范围状态返回路径、待决原因、标记、planCurrent 和观测覆盖情况,不将完整文件哈希快照放入模型上下文。
质量请求模式版本 1 的 scope 新增可选 writeScope,包含 schemaVersion、revision、writePaths、attributedPaths、confirmedPaths、observedPaths、externalPaths、pendingPaths、digest。其中 observedPaths 将 scope_observed 文件与原生/人工归属区分。这些事实参与 inputFingerprint。
既有 attribution: "unattributed" 仍描述原始 Git 观测,complete 保留原有 Git 覆盖含义。范围批准/审查不会使检查自动通过,消费方必须容忍新增字段。无需新增环境变量或仓库配置。
结果与错误处理
| 条件 | 结果 |
|---|---|
| 没有范围、路径为空或原生目标在范围外 | 阻断写入,应提出目标路径 |
| 已有 Git 未提交文件未明确纳入 | 阻断原生写入,保留用户工作 |
| 范围内 Shell/模糊编辑/失败/不透明工具改动 | 记录观测并继续,保留工具失败证据 |
| 范围外改动、外部内容变化或已知并发冲突 | 等待决定,不静默接管 |
| 纳入/排除使用目录或缺少证据 | 人工界面前拒绝,要求精确文件路径 |
| 重复提交已解决的范围请求 | 无操作,不弹窗,不更新批准/证据 |
| 方案变化 | 重新批准当前方案产物 |
| 对话框打开期间文件/范围/任务变化 | 拒绝迟到确认,重新审视当前事实 |
| 存在活动项目写入租约 | 拒绝另一项修改操作,不按时间将活动进程判为过期 |
| 写入中断 | 保留持久证据、恢复租约、允许范围内继续;不重放或声称成功 |
| 引用证据缺失/变化 | 拒绝,不静默重置为空范围 |
| 新式批准的范围目录被删除 | 任务标记 writeScopeRequired 阻止回退到旧行为 |
| 最终钩子或其它进程改变已观测文件 | 阻断完成,包括直接完成接口 |
| 受信任的规范准备超出范围 | 写入前阻断 |
| 规范准备改变已检查输入 | 保留准备结果,拒绝旧质量证据;显式重试检查新内容 |
重试时,相同的受信任规范准备不做操作,避免证据无限失效。完成流程在同步最终校验、状态更新和归档期间持有项目租约。质量命令仍在此之前执行;检查造成的源码变化会被观测并阻止完成。
父会话的 bash 和 powershell 使用独立的 shell 分类。无论是否有 Git,在所有阶段都绕过命令文本、方案、beforeWrite 和 begin 预检。不设通用命令允许列表或特殊 mkdir 权限;活动任务中常见 git add/git commit 调用会被引导到受控提交工具。这个提示性拦截不是完整 Shell 解析或任意脚本沙箱。执行器负责命令校验和失败;通用任务状态损坏处理保持不变。
原生文件工具已有的控制面/研究限制仍保留。Shell 没有等价的路径限制,任务状态仍必须通过受信任工作流工具修改。后续 inspect、托管写入和最终复核会观测快照差异,但不将作者归属分配给 Shell。由于没有 Shell 进行中记录,中断不会被识别为某次具体托管写入;范围内观测无需额外批准。声明范围外的被忽略路径、非 Git 未跟踪路径和外部副作用不在覆盖内。
没有范围的旧程序化任务仍可读取,完成时同样校验质量证据和任务未提交改动;旧批准本身不授予原生宿主写入权限。
授权复用
首次批准在一次决定中接管草稿。重复提交未变的已批准方案/范围/审查时返回 reused: true,不打开界面。业务 .agents/rules 文件可在批准范围内编辑,任务/运行时状态仍使用宿主工具。解决归属后提供有效 observedPaths 并清除预存歧义;rawGit 保留原始观测。外部依赖输入仍影响证据哈希。
当前检查范围与历史归属
历史 attributedPaths 不等于当前有改动的文件。buildChangeScope 在归属已解决时选择当前 Git 变化、任务基线以来的提交差异及被接管的初始草稿。从干净基线修改后恢复原样的路径不再选包,但归属历史保留。被接管的预存草稿及其删除仍保留任务基线语义,external 排除保持。无法确认归属或历史时继续保守返回不完整范围。
文件系统路径身份
resolveWritePaths(root, paths, field?, limit?) 在字面量路径校验后,使用实际文件系统规范化已存在的路径组成部分。路由、人工审查绑定、范围提案、快照和原生写入目标使用同一种拼写;尚不存在的输出部分保留请求名称。大小写敏感文件系统区分 README.md 与 readme.md;大小写不敏感文件系统将二者解析为同一文件。不能全局小写化路径或改变共享 realpath 辅助函数的语义。
规范化项目根下每个已存在的路径组成部分都使用 lstat 检查。真实符号链接(包括悬空链接和缺失输出的符号链接父目录)仍被阻断,路径越界和 .git 目标也一样。仅凭路径拼写不能认定它是符号链接。
受控提交在项目写入租约内更新 Git HEAD 与范围快照,记录 git_committed 事件,不把这次已确认提交当作未知历史变化。外部手动提交仍按原规则核验历史。写入范围授权不等于 Git 提交授权;已接管的预存草稿也不能由工具自动整文件提交。