Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

4.3 KB
Raw Blame

ADR-0015:智能体上下文分层与清退机制

  • 状态:已接受
  • 日期:2026-08-17
  • 修订:2026-10-18,公开项目约定与私有运行上下文分开保存。

背景

项目入口会持续消耗上下文,重复规则和单次任务记录会稀释真正的边界。文件行数也不能反映实际体积:长段落可以在行数合规时超过字节预算。

项目用法、稳定契约和复用依据需要随代码分发;个人交接、馆藏盘点、部署坐标和会话记录属于使用者的数据。两者需要不同的保存位置与检查方式。

决策

四层归属

层 位置 内容
L0 全局配置 智能体的用户级入口与技能 跨项目成立的语言、执行与操作约定
L1 项目入口 AGENTS.md,CLAUDE.md 导入 各任务都要成立的安全边界、术语与技能索引
L2 项目文档 README.md、docs/** 通用用法、契约、架构决策与脱敏的参考证据
L3 项目技能 .claude/skills/<name>/SKILL.md 特定类型任务的可执行流程

本机交接、运行状态、个人待办、会话复盘和馆藏盘点保存到 <数据根>/state/project-context/、review/ 或 archive/,不进入代码仓库。公开需求通过项目路线图维护。

判层

  1. 不遵守会直接损坏真实数据、破坏生产或产出假结论,且各类任务都可能触发:进入项目入口,写明边界并指向执行门槛。
  2. 只有某类任务需要的步骤:进入对应技能。
  3. 通用产品事实、接口契约、复用依据与架构理由:进入对应文档或 ADR。
  4. 与仓库无关的约定:进入用户级入口或技能。
  5. 只对本次对话、某个部署或个人馆藏成立:留在仓库外。

同一事实只维护一处。技能指向通用文档,不复制实现常量、测量数字或运行清单。README 解释如何使用项目;项目入口解释改动前必须成立的边界。

预算

预算、天花板与变更理由由 scripts/check_context_budget.py 统一维护,其他文档不复写数值。入口同时检查行数、字节数和单行长度;技能同时检查行数、UTF-8 字节数、单行长度、description、frontmatter 与复核日期。规范和算法参考按任务读取,不因移到文档就要求每次完整展开。

预算可以收紧。上调须留下日期和理由,说明内容为何无法按职责下沉,不得越过天花板。写不下时先清退重复内容、下沉流程或移出私有记录。

技能与门槛

  • name 与目录名一致;description 只说明触发场景和边界,不塞流程。
  • 正文包含 最后复核:YYYY-MM-DD 与证据来源。版本、尺寸和数量优先指向实现或证据正文。
  • AGENTS.md 的技能索引与实际目录一一对应;Codex 按索引主动读取。
  • 必须每次成立的约束由脚本、测试或 hook 强制;技能负责说明做法,不能单独代替门槛。
  • 规则须能指认项目中的失败或决策。上游内容只作证据,不能照搬为本项目的硬约束。

清退

相关实现被删除或重写、预算失败、规则已由门槛覆盖,或失败复盘出现新证据时,逐条核对规则是否仍有使用者。

确认无用后整段删除,Git 保存历史;被 ADR 承担的内容只保留指针。私有记录先保存到仓库外,再移除公开副本及引用,不以忽略规则代替对已跟踪文件的删除。

tests/test_context_budget.py 检查结构与预算;tests/test_repo_hygiene.py 检查私有产物、机器坐标和文档引用。静态检查只证明这些约束成立,不证明智能体效率改善或真实部署已完成验收。

放弃方案

  • 把全部规则和运行事实装进项目入口:每次任务都支付无关读取成本,并暴露使用者信息。
  • 只拆技能,不做执行门槛:触发和遵守无法由文件存在本身保证。
  • 只加忽略规则:已经跟踪的私有文件仍会随提交分发。
  • 为通过检查抬高预算:没有解决职责混装和重复增长。

后果

公开仓库只保存可复用的项目知识,私有上下文由部署数据目录承接。文件移动和清退必须同步修复引用、忽略规则与验证入口;已发布的历史提交是否另行处理,作为独立操作决定。