Back to Details

evolve-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Self-Evolving Context Protocol

可自我演进的上下文协议

Basics

基础说明

Activation

激活模式

  • 'POST_TASK' (default) — execute post-task protocol when task warrants it
  • 'ALWAYS_ON' (opt-in) — monitor every interaction; use only when explicitly requested
  • 'ON_REQUEST' — full context lifecycle audit when user asks
  • 'POST_TASK'（默认模式）——当任务有需要时执行任务后协议
  • 'ALWAYS_ON'（可选开启）——监控每一次交互；仅在明确请求时使用
  • 'ON_REQUEST'——当用户发起请求时，执行完整的上下文生命周期审计

Paths

路径说明

  • '
    SKILL_DIR
    ' — the directory containing this 
    SKILL.md
    file (resolved by the agent at runtime)
  • 'Scripts': 
    ${SKILL_DIR}/scripts/
    — skill automation scripts
  • 'Detailed docs': 
    ${SKILL_DIR}/docs/protocols.md
     — full protocol specifications
  • '
    SKILL_DIR
    '——包含此
    SKILL.md
    文件的目录（由Agent在运行时解析）
  • 'Scripts'：
    ${SKILL_DIR}/scripts/
    ——技能自动化脚本目录
  • '详细文档'：
    ${SKILL_DIR}/docs/protocols.md
    ——完整的协议规范

Managed Targets

管理目标

  • 'Root README': 
    README.md
    — human entry point
  • 'Index File': One of 
    AGENTS.md
    | 
    CLAUDE.md
    | 
    CODEX.md
    | 
    GEMINI.md
    | 
    CONTEXT.md
  • 'Docs Index': 
    /docs/README.md
    — living index of 
    /docs
  • 'Project Docs': 
    /docs/'
    — documentation files
  • '根目录README'：
    README.md
    ——面向人类的入口文件
  • '索引文件'：以下文件之一 
    AGENTS.md
    | 
    CLAUDE.md
    | 
    CODEX.md
    | 
    GEMINI.md
    | 
    CONTEXT.md
  • '文档索引'：
    /docs/README.md
    ——
    /docs
    目录的动态索引
  • '项目文档'：
    /docs/
    ——所有文档文件

Purpose

核心目标

Maintain a living knowledge system that captures insights, prevents repeated mistakes, and evolves project documentation through structured feedback loops.
'Target format': GitHub-Flavored Markdown. 'Sweet spot': Projects with extensive documentation. 'Core guarantee': No insight is lost. No mistake is repeated. No documentation goes stale.
维护一个动态的知识系统，通过结构化反馈循环捕获洞见、避免重复犯错，并持续演进项目文档。
'目标格式'：GitHub风格Markdown。 '适用场景'：拥有大量文档的项目。 '核心保障'：不丢失任何洞见。不重复任何错误。不让任何文档过时。

Axioms

基本原则

A1: Reflexive Integrity

A1：自反完整性

The protocol applies its own rules to itself. Process context (index file) ≠ project docs (
/docs
).
协议将自身规则应用于自身。流程上下文（索引文件）≠ 项目文档（
/docs
）。

A2: Constraint-Driven Evolution

A2：约束驱动演进

Complexity is earned through discovered constraints, not invented upfront.
复杂度是通过发现的约束逐步积累的，而非预先设计。

A3: Single Source of Truth

A3：单一事实来源

Every piece of knowledge lives in exactly one place. Navigate via hierarchy, never duplicate.
每一条知识仅存于唯一位置。通过层级结构导航，绝不重复存储。

Three-Layer Architecture

三层架构

Layer 0: README.md            ← "what is this & where to go"
Layer 1: AGENTS.md (index)    ← "how we work" (conventions, insights, mistakes)
Layer 2: /docs/README.md      ← "what docs exist"
Layer 3: /docs/'             ← "what we build"
Layer 0: README.md            ← "这是什么 & 去哪里找"
Layer 1: AGENTS.md (index)    ← "我们如何协作"（约定、洞见、错误）
Layer 2: /docs/README.md      ← "现有哪些文档"
Layer 3: /docs/'             ← "我们构建了什么"

Routing Decision Tree

路由决策树

About how we work?         → Layer 1 (index file)
About what we build?       → Layer 3 (/docs), then update Layer 2
About project identity?    → Layer 0 (README.md)
关于协作方式？         → 第1层（索引文件）
关于构建内容？       → 第3层（/docs），然后更新第2层
关于项目定位？    → 第0层（README.md）

Connectivity Invariant

连通性不变规则

README.md → /docs/README.md → /docs/'. README.md → AGENTS.md. Every doc reachable within 2 clicks from root. No dead ends.
README.md → /docs/README.md → /docs/'. README.md → AGENTS.md. 所有文档都能从根目录通过2次点击访问到。无死链接。

Activation Modes

激活模式详情

Mode 1: POST_TASK (Default)

模式1：POST_TASK（默认）

'Trigger decision tree':
Task touched any *.md file? → YES → run POST_TASK
                              NO  → Changed public APIs/architecture? → YES → run POST_TASK
                                                                        NO  → skip
'Farmville guard': Before writing any update, ask: "Does this prevent a future mistake or capture a non-obvious constraint?" If no → skip. Silence is a valid output. Measuring documentation activity instead of prevented errors is the Farmville trap.
'Light post-task' (default — ≤3 files changed, no architectural impact):
  1. EVALUATE — anything worth capturing? If no → skip
  2. ROUTE & WRITE — update appropriate layer
  3. SYNC — ensure /docs/README.md is current
'Full post-task' (>3 files changed OR architectural impact detected): 1–7. Full protocol steps (see protocols.md) 8. VALIDATE — 
bash "${SKILL_DIR}/scripts/validate-context"
'触发决策树'：
任务是否修改了任何*.md文件？ → 是 → 运行POST_TASK
                              否  → 是否修改了公共API/架构？ → 是 → 运行POST_TASK
                                                                        否  → 跳过
'Farmville 防护机制'：在撰写任何更新前，先自问：“这是否能避免未来的错误，或是捕获非显性约束？”如果不能，则跳过。无更新也是一种有效结果。只衡量文档更新次数而非避免的错误数量，就是所谓的“Farmville 陷阱”。
'轻量任务后流程'（默认——修改文件≤3个，无架构影响）：
  1. 评估——是否有值得记录的内容？如果没有 → 跳过
  2. 路由与撰写——更新对应层级的内容
  3. 同步——确保/docs/README.md是最新的
'完整任务后流程'（修改文件>3个 或 检测到架构影响）： 1–7. 完整协议步骤（参见protocols.md） 8. 验证——执行 
bash "${SKILL_DIR}/scripts/validate-context"

Mode 2: ALWAYS_ON (Opt-in)

模式2：ALWAYS_ON（可选开启）

Only when explicitly requested by the user. Silently track during any task: surprises, wrong assumptions, recurring patterns, stale/missing/duplicated docs. Flag for post-task capture.
Cost: agent attention on every turn. Use only when task density justifies it.
仅在用户明确请求时启用。在任何任务中静默跟踪：意外情况、错误假设、重复模式、过时/缺失/重复的文档。标记需要在任务后捕获的内容。
成本：Agent需要关注每一次交互。仅当任务密度足够高时使用。

Mode 3: ON_REQUEST (Explicit)

模式3：ON_REQUEST（主动请求）

Full context lifecycle audit + validation. See protocols.md.
完整的上下文生命周期审计+验证。详情参见protocols.md。

Pre-Task Protocol

任务前协议

1. READ index file — scan for relevant conventions and insights
2. READ /docs/README.md — understand documentation landscape
3. CHECK if similar task was done before → review past decisions
4. SCAN relevant /docs/' files
5. PROCEED with task execution
1. 阅读索引文件——扫描相关约定与洞见
2. 阅读/docs/README.md——了解文档体系
3. 检查是否有类似任务已完成→回顾过往决策
4. 扫描相关/docs/文件
5. 开始执行任务

Entry Templates

条目模板

Defaults for new files. If a file already has a format — match THAT format. Full templates: 
docs/templates.md
新文件的默认模板。如果文件已有格式——匹配现有格式。 完整模板：
docs/templates.md

Quick Reference

快速参考

'Index file entry':
markdown
- '[label]': [description] | Trigger: [cause] | Action: [what to do]
'Change History entry':
markdown
- `[Current]` [Task]. Impact: [what changed]. Insight: [lesson learned].
'Change History rotation': 
[Current]
→ 
[Previous]
→ 
[Legacy-0]
→ 
[Legacy-1]
→ 
[Legacy-2]
→ CHANGELOG.md
'索引文件条目'：
markdown
- '[标签]': [描述] | 触发条件: [原因] | 操作: [执行内容]
'变更历史条目'：
markdown
- `[Current]` [任务]. 影响: [变更内容]. 洞见: [经验总结].
'变更历史轮转规则'：
[Current]
→ 
[Previous]
→ 
[Legacy-0]
→ 
[Legacy-1]
→ 
[Legacy-2]
→ CHANGELOG.md

Tooling: 
validate-context

工具：
validate-context

Automated documentation health checker. Detects index file, validates links (skipping code blocks), analyzes bloat heuristically, checks docs index coverage.
  • 'Design': 
    docs/validation-design.md
  • 'Usage': 
    bash "${SKILL_DIR}/scripts/validate-context"
    from project working directory
  • 'Override root': 
    VALIDATE_CONTEXT_ROOT=/path/to/project bash ...
  • 'Exit 0' = passed, 'Exit 1' = errors found
自动化文档健康检查工具。检测索引文件、验证链接（跳过代码块）、启发式分析冗余、检查文档索引覆盖率。
  • '设计文档'：
    docs/validation-design.md
  • '使用方法'：在项目工作目录中执行 
    bash "${SKILL_DIR}/scripts/validate-context"
  • '覆盖根目录'：
    VALIDATE_CONTEXT_ROOT=/path/to/project bash ...
  • '退出码0' = 检查通过，'退出码1' = 发现错误

Lifecycle & Maintenance

生命周期与维护

  • 'Growth control': Discovery → Active → Consolidation → Strategic Pattern → Archive
  • 'GC triggers': 3+ bloat signals from validator → mandatory garbage collection
  • 'Change History': Max 5 entries, rotate older to 
    CHANGELOG.md
  • 'Mistake escalation': Insight → Convention → Hard rule → Structural change
  • 'Details': protocols.md
  • '增长管控'：发现→活跃→整合→战略模式→归档
  • 'GC触发条件'：验证工具发出3个以上冗余信号→强制执行垃圾回收
  • '变更历史'：最多保留5条条目，旧条目轮转至
    CHANGELOG.md
  • '错误升级流程'：洞见→约定→硬性规则→结构变更
  • '详细说明'：protocols.md