企业官网建设流程全解析

1. 项目概述：当代码不再“写出来”，而是“声明出来”

最近在几个技术社区里，看到越来越多开发者在讨论一个现象：以前写个自动化脚本，得从头搭环境、写函数、处理异常、串逻辑；现在呢？很多人打开编辑器，第一件事不是敲def，而是新建一个AGENTS.md文件，用几段带缩进的 YAML 风格文本，把“谁该做什么”“依赖什么工具”“失败怎么回退”全列清楚——然后点一下运行，整个工作流就活了。这不是玄学，也不是玩具，而是 AI 编程范式正在发生的实质性位移：从“命令式编码”转向“声明式配置”，而 Memory 工程，就是这场位移里最常被忽略、却最决定成败的底层地基。

你可能已经用过类似 AutoGen、LangGraph 或自研 Agent 框架，也试过让大模型调用 API、读文件、查数据库。但很快会遇到一连串真实到扎心的问题：为什么同一个任务，上午跑通，下午就“忘了”上下文？为什么两个 agent 协作时，总在重复解释背景？为什么调试时翻遍日志，却找不到它“到底记住了什么”？这些都不是模型能力问题，而是 Memory 没被当作工程对象来设计——它被当成缓存用，被当成变量塞，被当成 prompt 里一段拼接文字糊弄过去。结果就是：模型越强，系统越脆；配置越简，行为越不可控。

这个标题里的三个关键词，其实是环环相扣的因果链：“AI 编程范式转换”是表象，“Memory 工程”是支点，“AGENTS.md 声明式配置”是落地接口。它不意味着抛弃代码，而是把“控制逻辑”和“状态契约”彻底分离：代码负责执行引擎、工具调度、错误熔断；而AGENTS.md负责定义“谁是谁”“信什么”“记多久”“传给谁”。就像 Kubernetes 用 YAML 定义 Pod 而非手写进程管理，真正的 AI 工程化，正需要这样一层可版本化、可 diff、可审查、可回滚的状态契约层。

适合谁看？如果你正在用 LLM 构建多 step 流程、跨 agent 协作、长周期任务（比如自动写周报+同步会议纪要+生成待办），或者已经踩过“状态丢失”“上下文爆炸”“记忆污染”的坑，那这篇就是为你写的。不需要你是架构师，但得愿意把“我让模型记住”这件事，当成和“我给数据库建索引”一样认真对待。

2. 核心范式拆解：为什么“无状态”是假命题，而“Memory 工程”是刚需

2.1 “无状态模型”是个危险的幻觉

很多初学者接触 LLM 时，会被“大模型本身无状态”这句话带偏。教科书上说：“每次请求都是独立的，模型不会记住上一次对话。”这没错，但错在把“模型自身”等同于“整个系统”。现实中的 AI 应用从来不是单次 API 调用——它是用户输入 → 系统解析 → 工具调用 → 结果聚合 → 再次推理 → 输出反馈的闭环。在这个闭环里，状态必然存在，只是它被散落在五个地方：

• Prompt 里硬编码的上下文片段（比如“你是一个资深 Python 工程师，擅长用 Pydantic 做数据校验”）
• Session 变量或内存字典（比如st.session_state['user_profile']）
• 外部向量库的检索结果（比如 Chroma 里查出的上周会议记录）
• 工具返回的临时文件路径（比如temp/analysis_20240521.csv）
• LLM 自己生成的中间思考链（比如 ReAct 模式下的 “Thought: 我需要先查文档…”）

提示：这五类状态，90% 的线上故障都源于其中两类的耦合失控——要么把长期记忆（如用户偏好）硬塞进 prompt 导致 token 溢出；要么把临时中间态（如某次分析的 CSV 路径）存在全局变量里，被下个请求意外覆盖。

我见过最典型的反模式，是某团队用 LangChain 写客服机器人，把用户历史对话全拼进 system prompt。初期效果惊艳，但上线两周后，平均响应延迟从 800ms 涨到 4.2s，错误率飙升。查下来发现：第 37 次对话时，prompt 长度已超 12K token，模型光做 tokenization 就占了 60% 时间；更糟的是，当用户问“刚才说的那个方案，能加个导出功能吗？”，模型根本分不清“刚才”是指上一轮，还是三天前的某次会话——因为所有历史都被扁平化压成一段文本，没有时间戳、没有来源标记、没有语义分组。

2.2 Memory 工程的本质：给状态装上“交通管制系统”

Memory 工程不是给模型加个 Redis 缓存那么简单。它是一套完整的状态生命周期管理体系，核心目标就一个：让每个状态单元，都具备可识别、可追溯、可约束、可协同的工程属性。这需要三重设计：

第一重：状态分类与边界定义
不能所有东西都叫“memory”。必须按时效性、作用域、变更频率切分成四类：

• Identity Memory（身份记忆）：用户 ID、角色权限、长期偏好（如“默认用中文回复”）。生命周期 = 用户会话期以上，变更频率低，需持久化。
• Context Memory（上下文记忆）：当前任务的输入参数、中间产物、工具返回值。生命周期 = 单次任务链，变更频率高，可暂存内存或本地文件。
• Knowledge Memory（知识记忆）：公司 SOP、产品文档、API 手册等结构化知识。生命周期 = 天级更新，变更频率极低，需向量库+元数据管理。
• Trace Memory（轨迹记忆）：agent 的决策日志、工具调用链、失败重试记录。生命周期 = 分析期（7–30 天），用于归因与优化，需结构化存储（如 SQLite）。

第二重：状态契约化（Contractual Memory）
每类状态都要有明确的“契约”：谁写、谁读、有效期多长、冲突怎么解决。比如 Identity Memory 的契约可能是：

identity: source: auth_service schema: {user_id: str, role: enum[admin,editor,viewer], lang: str} ttl: 7d conflict_policy: overwrite_on_auth_refresh

这个契约不是注释，而是运行时强制校验的规则。引擎启动时会检查auth_service是否可用；每次写入前验证role是否在枚举内；超时自动清理；当认证服务推送新权限时，按策略覆盖旧值——全部由框架自动执行，不靠人肉if判断。

第三重：状态路由与隔离
不同 agent 对同一类状态的访问权限必须隔离。A agent 可以读写自己的 Context Memory，但只能只读访问 B agent 的 Identity Memory；Knowledge Memory 对所有 agent 公开，但 Trace Memory 仅限监控 agent 访问。这种路由不是靠代码里if agent_name == 'reporter'控制，而是通过 Memory Router 组件，在请求到达前完成鉴权与路径分发。

注意：很多团队卡在第二步“契约化”。他们建了 Redis，写了序列化逻辑，但没定义“这个 key 代表什么”“谁有权删它”“过期后要不要触发回调”。结果就是：运维半夜收到告警说 Redis 内存爆了，一查全是temp_context_123456789这种无主 key，既不敢删（怕影响线上），也不敢留（OOM 风险）。这就是没契约的典型代价。

2.3 AGENTS.md：声明式配置如何成为范式转换的“语法糖”

AGENTS.md不是 Markdown 文件，而是一种轻量级、人类可读、机器可解析的 Agent 声明协议。它的价值不在格式，而在它强制你回答三个关键问题：

1. 这个 agent 的“身份契约”是什么？（对应 Identity Memory）
2. 它参与的任务流中，“上下文契约”如何流转？（对应 Context Memory）
3. 它能调用哪些工具，这些工具的“知识契约”如何绑定？（对应 Knowledge Memory）

我们来看一个真实简化版AGENTS.md片段（已脱敏）：

# ReportGeneratorAgent ## Identity - role: "data_analyst" - expertise: ["SQL", "Pandas", "reporting_best_practices_v3"] - language: "zh-CN" ## ContextFlow - input_schema: - report_type: enum[daily,weekly,monthly] - date_range: {start: iso_date, end: iso_date} - output_schema: - file_path: str # generated CSV/Excel - summary: str - memory_scope: task_local # 仅本任务链内有效 ## Tools - sql_executor: - knowledge_ref: "company_db_schema_v2" - timeout: 30s - chart_generator: - knowledge_ref: "charting_rules_v1" - max_charts: 5 ## Recovery - on_tool_failure: retry(3, backoff: exp) - on_context_overflow: fallback_to_summary_only

这段配置背后，是整套 Memory 工程的落地接口：

• role和expertise不是提示词，而是 Identity Memory 的 schema 声明，引擎会据此过滤 Knowledge Memory 中匹配的文档片段；
• memory_scope: task_local是 Context Memory 的生命周期契约，引擎自动在任务开始时创建隔离命名空间，结束时销毁；
• knowledge_ref是 Knowledge Memory 的引用键，引擎根据它从向量库中检索相关文档，并附带元数据（如“该规则最后更新于 2024-03-15，由 DataTeam 签署”）；
• on_context_overflow是状态溢出的兜底策略，当输入参数 + 中间态超过预设阈值（如 8K token），自动触发摘要降维，而非硬截断。

它之所以能成为范式转换的载体，是因为它把原本散落在代码、配置文件、注释、团队 wiki 里的隐性约定，全部显性化、结构化、可版本化。一次git diff AGENTS.md就能看清：这次迭代是放宽了 SQL 执行超时，还是新增了图表数量限制，还是切换了报表语言——而不用 grep 二十个 Python 文件找timeout=。

3. Memory 工程实操：从零搭建可验证的声明式 Agent 系统

3.1 构建 Memory 核心组件：四层抽象与选型逻辑

Memory 工程不是堆工具，而是建抽象层。我们按数据流方向，从底向上构建四层：

Layer 0：Storage Layer（存储层）——不追求“快”，而追求“准”
这是最容易踩坑的一层。很多团队一上来就选 Redis 或 Memcached，图快，结果埋下大雷：Redis 没有 schema 校验，user_id字段可能存成字符串"123"，也可能存成整数123，下游 agent 解析时直接崩溃；Memcached 不支持 TTL 精确控制，导致过期 key 残留。

实测下来，SQLite + WAL 模式是中小规模系统的最优解：

• 支持完整 SQL，可建带 CHECK 约束的表（如CREATE TABLE identity (user_id TEXT CHECK(length(user_id)>0), role TEXT CHECK(role IN ('admin','editor')), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)）；
• WAL 模式支持高并发读写，实测 50 QPS 下平均延迟 < 3ms；
• 数据文件即备份，cp memory.db backup_20240521.db就是完整快照；
• 无需额外运维，嵌入式部署，agent 启动时自动初始化。

实操心得：别碰 RocksDB 或 LevelDB。它们性能虽好，但 schema 管理成本极高，且没有成熟 ORM 支持。SQLite 的PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;三行配置，就能扛住 95% 的场景。

Layer 1：Schema & Contract Layer（契约层）——用 Pydantic V2 做运行时守门员
所有 Memory 读写操作，必须经过契约校验。我们为四类 Memory 分别定义 Pydantic 模型：

from pydantic import BaseModel, Field, validator from typing import Optional, Dict, Any class IdentityMemory(BaseModel): user_id: str = Field(..., min_length=1, max_length=64) role: str = Field(..., pattern=r"^(admin|editor|viewer)$") lang: str = Field(default="zh-CN", pattern=r"^[a-z]{2}(-[A-Z]{2})?$") @validator('user_id') def validate_user_id(cls, v): if not v.isalnum(): raise ValueError('user_id must be alphanumeric') return v class ContextMemory(BaseModel): task_id: str step: int = Field(ge=0, le=100) # 防止无限递归 data: Dict[str, Any] = Field(default_factory=dict) expires_at: Optional[float] = None # Unix timestamp

引擎层封装MemoryManager类，所有.write()方法内部先调用IdentityMemory(**data).model_dump()，校验失败则抛出ValidationError并记录到 Trace Memory。这比在业务代码里写if not isinstance(data['user_id'], str): ...可靠十倍——因为校验逻辑集中，且无法绕过。

Layer 2：Router & Isolation Layer（路由层）——用命名空间实现零信任隔离
不同 agent 的 Context Memory 必须物理隔离。我们采用“双命名空间”策略：

• Global Namespace：存放 Identity Memory 和 Knowledge Memory，按user_id或knowledge_ref哈希分片；
• Task Namespace：每个任务链启动时，生成唯一task_id（UUIDv4），所有 Context Memory 存入context_{task_id}表；任务结束，自动DROP TABLE context_{task_id}。

路由逻辑在MemoryManager.get()时触发：

def get(self, memory_type: str, key: str, agent_name: str, task_id: Optional[str] = None): if memory_type == "context" and task_id: table_name = f"context_{task_id}" elif memory_type == "identity": table_name = "identity" else: raise ValueError(f"Invalid memory type: {memory_type}") # 后续查询...

这样，ReportGeneratorAgent 写入context_abc123，而 AlertMonitorAgent 读取context_def456，天然隔离，无需任何锁机制。

Layer 3：Declaration & Runtime Layer（声明层）——AGENTS.md 解析器的核心逻辑
AGENTS.md解析不是简单 YAML load。它要完成三件事：

1. Schema 验证：用 Pydantic 模型校验每个 section 是否符合规范；
2. 契约注入：将memory_scope: task_local转为ContextMemory模型的expires_at计算逻辑；
3. 工具绑定：将sql_executor的knowledge_ref映射到 Knowledge Memory 的向量检索 query。

解析器核心代码（简化）：

import yaml from pydantic import parse_obj_as from typing import Dict, Any class AgentConfig(BaseModel): name: str identity: IdentityMemory context_flow: Dict[str, Any] tools: Dict[str, Dict[str, Any]] def load_agents_config(config_path: str) -> Dict[str, AgentConfig]: with open(config_path) as f: raw = yaml.safe_load(f) agents = {} for agent_name, config in raw.items(): # 注入 memory_scope 逻辑 if config.get('context_flow', {}).get('memory_scope') == 'task_local': config['context_flow']['expires_at'] = time.time() + 3600 # 1h TTL # 校验并构建 agents[agent_name] = parse_obj_as(AgentConfig, { 'name': agent_name, **config }) return agents

这套四层架构，把 Memory 从“代码里的变量”升格为“可治理的基础设施”。上线后，某客户系统 Memory 相关故障下降 78%，平均排障时间从 47 分钟缩短到 6 分钟——因为所有状态操作都有契约日志、有命名空间隔离、有 schema 错误码，再也不用靠猜。

3.2 AGENTS.md 配置实战：从需求到可运行的完整链路

假设我们要实现一个“周报生成助手”，需求如下：

• 输入：用户指定日期范围（如 2024-05-13 至 2024-05-19）
• 步骤：1）从 GitLab 获取该周代码提交记录；2）从 Jira 获取关联 issue；3）合并分析生成周报摘要；4）输出 Markdown 和 PDF
• 约束：Jira 查询需带用户权限 token；PDF 生成不能超时 15 秒；若 GitLab 不可用，降级为仅分析 Jira 数据

我们一步步构建AGENTS.md：

Step 1：定义 Identity Memory 契约
这是整个 agent 的“身份证”，必须包含所有外部依赖的认证信息：

# WeeklyReportAgent ## Identity - user_id: "weekly_report_bot" - role: "report_generator" - auth_tokens: gitlab: "${GITLAB_TOKEN}" # 环境变量注入 jira: "${JIRA_TOKEN}" - language: "zh-CN"

注意${GITLAB_TOKEN}不是硬编码，而是运行时从环境变量读取。引擎启动时会检查这些变量是否存在，缺失则拒绝加载 agent，避免上线后才发现认证失败。

Step 2：定义 ContextFlow，明确输入输出与状态边界

## ContextFlow - input_schema: - start_date: iso_date - end_date: iso_date - include_metrics: bool = true - output_schema: - markdown: str - pdf_url: str - memory_scope: task_local - max_steps: 4

max_steps: 4是防呆设计：如果 agent 在执行中陷入循环（比如反复调用自己），引擎会在第 4 步强制终止并记录 Trace Memory。

Step 3：绑定 Tools，声明 Knowledge Memory 依赖

## Tools - gitlab_fetcher: - knowledge_ref: "gitlab_api_docs_v2" - timeout: 20s - retry: {max_attempts: 2, backoff: linear} - jira_searcher: - knowledge_ref: "jira_jql_cheatsheet_v1" - timeout: 15s - report_analyzer: - knowledge_ref: "weekly_report_template_v4" - pdf_generator: - timeout: 15s - max_file_size_mb: 5

这里knowledge_ref是关键。引擎会用它作为 query，从 Knowledge Memory 向量库中检索相关文档。例如jira_jql_cheatsheet_v1可能返回：

# JQL 常用写法（v1，2024-04-10 更新） - 按日期范围：updated >= "2024-05-13" AND updated <= "2024-05-19" - 按状态：status IN ("In Progress", "Done") - 关联代码：issue in linkedIssues("PROJECT-123")

这些文档不是静态贴在 prompt 里，而是动态检索、带版本号、带更新时间戳，确保 agent 总是用最新规则。

Step 4：定义 Recovery 策略，把“失败”变成“可预期”

## Recovery - on_tool_failure: gitlab_fetcher: fallback_to_jira_only jira_searcher: error_out - on_timeout: pdf_generator: fallback_to_markdown_only - on_context_overflow: truncate_and_summarize

fallback_to_jira_only不是空字符串，而是预定义的降级流程：跳过 gitlab 步骤，直接用 jira 数据生成报告。这个流程本身也是AGENTS.md里定义的另一个 agent，叫JiraOnlyReportAgent。

Step 5：运行时验证与加载
配置写完，不是直接运行。我们提供agent-validate命令：

$ python cli.py agent-validate --config AGENTS.md ✅ Validating WeeklyReportAgent... ✅ Identity schema OK ✅ ContextFlow input_schema valid (iso_date parser loaded) ✅ Tools knowledge_refs found in Knowledge Memory: gitlab_api_docs_v2, jira_jql_cheatsheet_v1, ... ✅ Recovery fallbacks resolved: fallback_to_jira_only → JiraOnlyReportAgent exists ✅ All environment variables present: GITLAB_TOKEN, JIRA_TOKEN ✔ AGENTS.md is valid and ready to deploy.

这个验证过程，就是 Memory 工程的“编译期检查”。它确保上线前，所有状态契约、工具依赖、降级路径都已就绪，而不是等到凌晨三点用户投诉“周报没生成”才去查GITLAB_TOKEN拼错了。

3.3 Memory 状态可视化与调试：告别“黑盒式”排查

再好的设计，没有可观测性就是空中楼阁。我们为 Memory 工程配套了三类调试工具：

1. Memory Snapshot CLI（快照命令行）
在任意时刻，执行：

$ python cli.py memory-snapshot --task-id abc123 --type context { "task_id": "abc123", "step": 2, "data": { "gitlab_commits": [{"id":"c1","msg":"fix login bug","files":["auth.py"]}], "jira_issues": [{"key":"PROJ-456","summary":"Login flow redesign"}] }, "expires_at": 1716254280.0 }

这比翻日志快十倍——你不需要 grep “commit count”，直接看到当前 Context Memory 的完整快照。

2. Memory Diff 工具（状态差异对比）
当 agent 行为异常，对比两次快照：

$ python cli.py memory-diff --before snap_20240520_1422.json --after snap_20240520_1425.json --- Before +++ After @@ -3,3 +3,4 @@ "gitlab_commits": [...], - "jira_issues": [] + "jira_issues": [{"key":"PROJ-456",...}] + "analysis_summary": "Found 1 critical issue..."

立刻定位到：是 Jira 数据成功加载了，还是分析模块新增了摘要字段。

3. Memory Trace Explorer（轨迹探索器）
基于 Trace Memory 构建的 Web UI（轻量 Flask 应用），可按task_id查看完整状态流转图：

• 时间轴显示每个 step 的开始/结束时间、Memory 读写操作；
• 点击某次ContextMemory.write()，查看写入的原始数据、调用栈、agent 名称；
• 红色高亮on_timeout或fallback事件，点击直达 Recovery 配置。

实操心得：不要用 ELK 或 Grafana 做 Memory 追踪。它们太重，且不理解 Memory 的语义。我们用 SQLite 的 FTS5 全文搜索扩展，对 Trace Memory 建立task_id,agent_name,event_type三字段索引，SELECT * FROM trace WHERE task_id MATCH 'abc123' AND event_type = 'context_write'10ms 内返回，足够日常调试。

4. 常见问题与避坑指南：那些只有踩过才懂的 Memory 痛点

4.1 问题速查表：高频故障与根因定位

4.2 那些文档里不会写的“血泪经验”

经验一：永远不要在 Context Memory 里存二进制大对象
曾有个团队把用户上传的 Excel 文件 base64 编码后塞进ContextMemory.data。结果单次任务 Context 表暴涨到 200MB，SQLite WAL 日志写满磁盘。正确做法：Context Memory 只存路径和元数据，文件走独立对象存储（如 MinIO），data里只存{"file_path": "/tmp/upload_abc.xlsx", "size_bytes": 124567, "sha256": "a1b2c3..."}。Memory 工程的第一铁律：状态是索引，不是仓库。

经验二：Identity Memory 的ttl必须大于最长任务耗时
某金融客户设置 Identity Memoryttl: 30m，但风控报告任务平均耗时 42 分钟。结果任务执行到一半，Identity Memory 过期被删，后续步骤因缺失auth_tokens全部失败。解决方案：ttl不是“用户不操作就过期”，而是“该身份凭证的有效期”。从认证服务拉取的 token 有效期是 24h，那就设ttl: 23h，并配refresh_on_access: true，每次访问时自动延长。

经验三：AGENTS.md的recovery策略必须可测试
我们要求每个fallback_to_xxx都对应一个独立的、可手动触发的测试用例。比如fallback_to_jira_only，必须有test_fallback_jira_only.py，能模拟 gitlab_fetcher 失败，验证是否真的跳过并生成报告。上线前，所有 recovery 测试用例必须 100% 通过。否则，所谓“高可用”只是幻觉。

经验四：Memory Router 的命名空间隔离，必须覆盖所有存储层
曾以为 SQLite 表名隔离就够了，结果发现 Knowledge Memory 用的 Chroma 向量库，collection 名是硬编码的default。当多个 agent 同时检索，互相污染结果。补救措施：为每个 agent 动态创建 Chroma collection，命名规则knowledge_{agent_name}_{version}，并在AGENTS.md的knowledge_ref中显式声明collection: knowledge_WeeklyReportAgent_v4。Memory 工程的终极考验，就是看你的隔离策略能否穿透所有技术栈。

4.3 性能压测实录：Memory 层在高并发下的真实表现

我们用 Locust 对 Memory 层做了三轮压测（硬件：4C8G，SQLite WAL 模式）：

Round 1：纯 Identity Memory 读（模拟 1000 用户并发登录）

• QPS：1280
• P95 延迟：8.2ms
• 瓶颈：CPU（SQLite 解析 JSON 字段）
• 优化：将auth_tokens从 JSON 字段拆为独立列gitlab_token TEXT, jira_token TEXT，P95 降至 3.1ms

Round 2：Context Memory 读写混合（模拟 200 个并发任务）

• QPS：320（写）+ 680（读）
• P95 延迟：12.7ms
• 瓶颈：WAL 日志写入（磁盘 I/O）
• 优化：PRAGMA journal_size_limit=67108864（64MB），避免频繁 fsync，P95 降至 9.4ms

Round 3：Knowledge Memory 检索（100 QPS 向量相似度搜索）

• 使用 Chroma + sentence-transformers/all-MiniLM-L6-v2
• P95 延迟：210ms（含 embedding 计算）
• 瓶颈：CPU（embedding 模型推理）
• 优化：将 embedding 计算前置，AGENTS.md加载时预计算knowledge_ref对应的向量，检索时只做 FAISS 近邻搜索，P95 降至 45ms

结论：Memory 层不是性能瓶颈，而是放大器——它会把上游（如模型推理）的延迟、下游（如工具 API）的抖动，原样暴露给整个系统。所以 Memory 工程的首要目标不是“更快”，而是“更稳、更可预测”。

5. 范式延伸：当 AGENTS.md 成为团队协作的新契约

5.1 从个人脚本到团队标准：AGENTS.md 的协作价值

AGENTS.md最大的隐性价值，是它天然适配现代软件工程协作范式。我们观察到三个转变：

转变一：Code Review 的焦点，从“怎么写”变为“怎么配”
以前 CR 重点是if/else是否完备、异常处理是否周全；现在 CR 清单第一条是：“AGENTS.md中recovery策略是否覆盖所有工具失败场景？” 第二条：“knowledge_ref是否指向最新版文档？” 第三条：“memory_scope是否与任务实际生命周期匹配？” —— 因为配置错误导致的线上故障，远多于代码逻辑错误。

转变二：SOP 文档自动同步
某客户将《周报生成 SOP》写成 Confluence 页面，但 agent 用的却是旧版 JQL 规则。后来他们把 SOP 关键条款，直接写进AGENTS.md的## Knowledgesection：

## Knowledge - jira_jql_cheatsheet_v1: | # JQL 规则（2024-04-10 生效） - 日期范围必须用 updated 字段，非 created - status 必须包含 "Done"，不可省略

每次 Confluence 更新 SOP，就同步更新AGENTS.md并触发 CI 流水线。agent 永远用最新规则，文档和代码再不脱节。

转变三：新人上手时间从天级降到分钟级
新成员入职，不再需要花两天读代码理解“周报 agent 怎么调 Jira”，而是直接打开AGENTS.md，5 分钟内看懂：它用什么权限、查什么字段、失败怎么降级、输出什么格式。AGENTS.md成了比代码更权威的系统说明书。

5.2 Memory 工程的下一步：从“声明式配置”到“可编程记忆”

当前AGENTS.md是声明式，但未来一定是可编程的。我们已在实验两个方向：

方向一：Memory Hooks（记忆钩子）
允许在 Memory 读写前后插入自定义逻辑：

## Hooks - on_identity_read: - script: "validate_token_expiry.py" # 检查 token 是否过期，过期则自动刷新 - on_context_write: - script: "log_sensitive_data.py" # 扫描 data 字段，屏蔽手机号、邮箱

这把 Memory 从被动容器，变成主动参与者。

方向二：Cross-Agent Memory Sync（跨 agent 记忆同步）
当 ReportGeneratorAgent 生成一份报告，自动触发AlertMonitorAgent的on_new_reporthook，将报告关键指标（如“本周 bug 数 +15%”）写入其 Identity Memory 的watched_metrics字段。这样，下次 AlertMonitorAgent 检查时，就能基于最新业务数据做判断，而非静态阈值。

这条路的终点，不是让模型更聪明，而是让系统更可信。当你能清晰说出“这个 agent 记住了什么”“它凭什么记住这个”“它什么时候会忘记”，AI 编程才算真正走出实验室，走进产线。

我个人在实际交付中发现，最难的从来不是让 agent 做事，而是让它做事时，始终知道自己是谁、记得什么、该信谁。AGENTS.md和 Memory 工程，就是给 AI 系统装上的“自我认知模块”。它不提升智商，但极大降低运维熵值——而这，恰恰是规模化落地的真正门槛。