AI 编程范式转换与 Memory 工程：从无状态模型到 AGENTS.md 声明式配置简介：模型是无状态的推理函数，H

简介：模型是无状态的推理函数，Harness 是有状态的编排器，人要做的是写规范、验结果；AGENTS.md 这类 Memory 文件用声明式配置让 Agent 读懂项目，并在上下文压缩后持续生效

范式转换：从写代码到写规范

简介：Software 3.0 时代编程不再等于写代码，80% 时间想清楚要什么，20% 时间验证 AI 做得对不对

Software 三代演进

阶段	做法	典型
Software 1.0	手写每一行代码	if-else、for 循环
Software 2.0	用数据训练模型替代手写规则	ML / Deep Learning
Software 3.0	用自然语言描述意图，AI 生成实现	LLM + Agent

范式转换的本质：你不再是代码的生产者，而是意图的传达者和质量的把关者
时间分配的变化

AI 辅助开发时间分配

编码时间压缩到 20%，规划和测试时间翻倍，新比例约为 Planning 40%、Coding 20%、Testing 40%
启示：需要更强的架构设计能力和验证能力
设计反转（Design Inversion）
- 传统：人写代码，AI 辅助
- 新范式：人写规范，AI 写代码
- 80% 时间想清楚要什么（写规范），20% 时间验证 AI 做得对不对
实现力高原（Implementation Plateau）
- AI 写代码的能力已进入高原期，SWE-bench 的代际提升只有个位数百分比，不是不进步，而是够用了
- 十个人用同样的模型、同样的额度，产出差异可以有十倍，区别在规范
- 瓶颈不在模型，在你能不能把需求说清楚
核心观点
- 编程 ≠ 写代码
- 编程 = 设计意图 × 精确表达 × 验证产出，循环是 Design、Prompt、Validate、Iterate

底层架构：规范、Harness、模型三层

简介：你写的三层规范被 Harness 加载，Harness 再调用无状态模型，三层各司其职

规范、Harness、模型三层架构

层	组成	职责
SDD 三层规范（你写的）	`AGENTS.md` 项目规范、`agents/.md` 角色规范、`skills//SKILL.md` 能力规范	描述要什么
Harness（运行时容器）	OpenCode / Claude Code / Cursor	循环、记忆、行动、权限控制
模型（推理引擎）	DeepSeek / Qwen / Claude / GPT	无状态、纯推理，`f(input) → output`

关键点
- 代码两年就淘汰，设计思想用一辈子，跑通固然可喜，理解架构才是核心收获
- 学概念、学思想，不绑定任何一个工具

AI Coder 工具全景与概念映射

简介：主流 AI 编程工具都实现了 Harness，六大工程化能力一一对应，差别在开源程度和国产模型支持

工具全景（2025~2026）

工具	类型	开源	国产模型	Memory	Agent 编排
OpenCode	终端 Agent	MIT 开源	原生支持	`AGENTS.md`	原生支持
Claude Code	终端 Agent	闭源	不支持	`CLAUDE.md`	原生支持
Cursor	IDE 插件	闭源	部分支持	`.cursorrules`	Composer
Windsurf	IDE 插件	闭源	部分支持	Rules	Cascade
Copilot	IDE 插件	闭源	不支持	`.github/copilot`	有限
Trae	IDE 插件	闭源	原生支持	Rules	Builder

工程化能力六维对比

能力维度	OpenCode	Claude Code	Cursor	说明
Memory 记忆	`AGENTS.md`	`CLAUDE.md`	`.cursorrules`	持久化项目上下文
Sub-Agents 委派	原生支持	原生支持	Composer	任务分解与委派
Skills 技能	原生支持	原生支持	自定义命令	可复用能力封装
Hooks 事件	原生支持	原生支持	有限	事件驱动自动化
MCP 协议	原生支持	原生支持	部分支持	外部工具集成
Headless CI/CD	原生支持	原生支持	不支持	无人值守运行

OpenCode 与 Claude Code 概念映射

概念	OpenCode	Claude Code	本质
项目记忆	`AGENTS.md`	`CLAUDE.md`	持久化上下文注入
子 Agent	Sub-Agent 原语	SubAgent 原语	隔离上下文的任务委派
技能包	Skill 文件	`SKILL.md`	声明式能力封装
快捷命令	Slash Command	Slash Command	用户触发的预定义流程
事件钩子	Hook 配置	Hook 配置	工具执行前后的自动化
外部工具	MCP Server	MCP Server	标准化外部能力接入
无人值守	Headless 模式	Headless 模式	CI/CD 集成
编程 SDK	API / SDK	Agent SDK	程序化调用 Agent

为什么以 OpenCode 为主线
- MIT 开源，代码完全公开，可学习架构设计、可二次开发
- 100K+ Stars，社区活跃，问题有人答
- 国产模型原生支持，DeepSeek / Qwen / GLM / Kimi 零成本接入
- 概念映射完整，与 Claude Code 六大能力一一对应
- 安装遇到问题时，Cursor、通义灵码、Trae、Claude Code、Cline 等任意工具都能替代，AI 辅助开发的道理相通

工程思想：无状态推理 + 有状态编排

简介：模型是极其强大但完全被动的推理函数，编排器给它加上循环、记忆和行动，才变成一个系统

模型的本质：无状态函数
- 大语言模型 = f(input) → output，每次调用都独立，没有记忆、没有状态
- 三个关键约束

约束	含义
无记忆	上一轮说了什么，模型完全不知道，除非重新喂给它
无决策	模型不会主动决定下一步做什么，只回答当前问题
无行动	不能读文件、不能调 API、不能执行任何操作

编排器的本质：有状态系统（Harness）

Harness 编排循环

红色节点是模型唯一参与的一步，其余都由 Harness 完成，绿色是退出条件
编排器 = while True: 观察 → 思考 → 行动 → 更新状态
Harness 本意是马具，马有力气但没有马具拉不动车，Harness 改变的是力量的传导方式
Harness = 编排器 + 规范化，包含 Tools、Knowledge、Observation、Action Interfaces、Permissions
三个模型没有的核心能力

能力	说明
循环	持续运行，直到任务完成或用户中断
记忆	维护对话历史、项目上下文、工具调用结果
行动	读写文件、执行命令、调用 API、与外部系统交互

OpenCode / Claude Code / Cursor 本质都是编排器，负责管理状态、调度模型、执行工具、维护上下文，并提供权限系统保证运行时安全

无状态模型与有状态编排器

被低估的关键能力：上下文管理

上下文压缩与重注入

红色节点是规范持久生效的秘密
模型上下文窗口有限，真实任务很快撑满，Harness 的解法是自动压缩 + 重注入
不是模型记住了规范，是 Harness 在每次压缩后都重新塞给模型
一个重要命题
- Harness 比模型更重要：同一个模型在不同 Harness 中的表现差距，远大于不同模型在同一个 Harness 中的差距
- 调教 Harness 的能力 = 真正的杠杆点
实战验证：裸 API 调用 vs OpenCode 编排

import os, json, urllib.request

API_KEY = os.environ.get("DEEPSEEK_API_KEY", "")
API_URL = "https://api.deepseek.com/chat/completions"

def call_api(prompt: str) -> str:
    data = json.dumps({
        "model": "deepseek-chat",
        "messages": [{"role": "user", "content": prompt}],
        "max_tokens": 1000,
    }).encode("utf-8")
    req = urllib.request.Request(API_URL, data=data, headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    })
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode())["choices"][0]["message"]["content"]

# 让它分析当前项目：裸 API 只会回答“请提供代码”或“我无法访问文件”
print(call_api("请分析当前项目的目录结构和代码质量，给出改进建议。"))

同一个问题在 OpenCode 里问，它会用 Glob / Read 扫描目录、读取文件内容，基于真实文件给出具体建议

维度	裸 API 调用	OpenCode 编排
本质	无状态推理	有状态编排
项目背景	不知道	自动注入 `AGENTS.md` 上下文
看文件	不能	能
执行命令	不能	能
交互方式	一问一答，做完就忘	多轮交互，持续迭代
类比	打电话问路	开着导航走
结论	只有推理，没有系统	推理 + 记忆 + 行动 = 系统

关键洞察：模型是同一个模型，差别在于编排器赋予了它感知和行动的能力

实战项目：AI 知识库助手系统

简介：一个人加一个 AI Agent 团队，搭出一个从采集到分发的知识管理系统，分四个版本渐进演进

四大核心能力

能力	内容
定制化知识采集	GitHub / Hacker News / 技术博客 / RSS 自动采集
AI 深度分析解读	摘要、技术亮点、架构分析、趋势研判
结构化知识存储	标签体系、全文检索、知识图谱
多渠道智能分发	公众号 / 飞书 / Telegram / 邮件

技术栈：OpenCode 编排 + 国产模型推理 + MCP 工具集成
V1 到 V4 渐进演进

V1 到 V4 演进路线

版本	目标	内容	工程思想
V1 编码自动化	人驱动对话，AI 写码	Memory 配置、第一批结构化知识	无状态 vs 有状态
V2 采集自动化	自动化流水线	Hooks 触发、Skills 标准化、自动采集 + 分析	事件驱动架构
V3 质量自动化	多 Agent 协作	Agent 编排、协作协议定义、自动审核 + 分发	分布式协作
V4 服务自动化	全平台上线	MCP 集成、CI/CD 部署、监控 + 运维	系统可靠性

V1 的四个主题

主题	核心内容	工程思想
AI 编程范式转换	工具选型 + 概念映射	无状态推理 + 有状态编排
Memory 工程	`AGENTS.md` 设计与分层	上下文工程原理
Sub-Agent 委派	任务分解与角色定义	关注点分离原则
Skill 封装	可复用能力包设计	声明式 vs 命令式

环境搭建：OpenCode + 国产模型

简介：Node.js 18+ 装 OpenCode，配一个国产模型的 API Key，首次对话成功即可

安装

# macOS
brew install node && node --version      # 需要 18+
npm install -g opencode-ai@latest        # 或 curl -fsSL https://opencode.ai/install | bash
opencode --version

国产模型 API Key

方案	入口	特点
DeepSeek（推荐）	platform.deepseek.com	约 ¥1 / 百万 tokens，最便宜的高质量模型，充 ¥5~10 可用很久
智谱 GLM	open.bigmodel.cn	新用户有免费额度，零成本试用
阿里云 Qwen	bailian.console.aliyun.com	开通百炼服务后获取 DashScope API Key

echo 'export DEEPSEEK_API_KEY="sk-你的key"' >> ~/.zshrc   # bash 用 ~/.bashrc
source ~/.zshrc && echo $DEEPSEEK_API_KEY
mkdir ~/opencode-test && cd ~/opencode-test && opencode   # 输入“你好，请回复 OK 确认连通”

注意点
- API Key 只显示一次，创建后立即复制保存
- 自查清单：Node 18+、opencode --version 有输出、Key 已获取、环境变量已配置、首次启动成功、对话回复 OK

Memory 工程：让 Agent 拥有持久记忆

简介：Memory 是一个纯文本配置文件，每次会话自动加载进提示词，相当于新员工入职读的项目开发手册

两种记忆

类型	说明
会话记忆（短期）	当前对话的上下文，关闭即丢失
项目记忆（长期）	写在文件里的规则和知识，跨会话持久存在

Memory 不是数据库，是声明式的意图描述文件
没有 Memory vs 有 Memory

维度	没有 Memory 的 Agent	有 Memory 的 Agent
身份	每次会话都是新员工	每次会话都是老员工
项目认知	不知道用什么框架	清楚技术栈和架构
编码规范	不清楚规范和命名习惯	遵循团队编码规范
代码风格	可能不符合团队风格	生成的代码风格一致
提醒成本	需要反复提醒同样的信息	自动遵守约定
产出质量	不稳定，依赖提示词	稳定可预期

各工具的 Memory 文件

工具	Memory 文件	位置	格式
Claude Code	`CLAUDE.md`	项目根目录	Markdown
OpenCode	`AGENTS.md`	项目根目录	Markdown
Cursor	`.cursorrules`	项目根目录	纯文本 / Markdown
Windsurf	`.windsurfrules`	项目根目录	纯文本 / Markdown
GitHub Copilot	`copilot-instructions.md`	`.github/`	Markdown
Cline	`.clinerules`	项目根目录	纯文本 / Markdown

Claude Code 用户把文件命名为 CLAUDE.md，效果相同

工程思想：声明式配置优先

简介：告诉系统要什么而不是怎么做，规则放进文件，可审计、可版本控制、可协作

命令式 vs 声明式

维度	命令式（Imperative）	声明式（Declarative）
告诉系统	怎么做（HOW）	要什么（WHAT）
描述内容	执行步骤和流程	期望的最终状态
执行顺序	很重要	由系统决定
例子	先建表，再插数据，再加索引；Shell 脚本部署服务器	我需要一个有索引的用户表；Kubernetes YAML 声明服务
关注点	过程（Process）	结果（Outcome）

为什么声明式更适合 AI Agent

特性	说明
可审计（Auditable）	打开 `AGENTS.md` 就能看到所有规则
可版本控制（Versionable）	用 Git 管理，每次改动有记录、可回滚
可协作（Collaborative）	团队成员可以 Review、讨论、共同维护
可迁移（Portable）	换工具换模型，Memory 文件直接复用
可组合（Composable）	子目录可以有自己的 `AGENTS.md`，覆盖或扩展父级规则
低耦合（Decoupled）	规则与 Agent 实现分离，互不依赖

两种写法对比

# 命令式：用代码控制 Agent 的每一步行为
def configure_agent(agent):
    agent.set_language("python")
    agent.set_style("google")
    agent.add_rule("always_add_docstring", True)
    agent.add_rule("max_function_length", 50)
    agent.set_naming_convention("snake_case")
    agent.add_forbidden_pattern("print()")
    # 问题：规则散落在代码里；改规则要改代码重新运行；非程序员无法参与；换框架要重写

# AGENTS.md — 声明式：描述要什么
## 技术栈
- 语言: Python 3.12
- 框架: FastAPI + Uvicorn
## 编码规范
- 遵循 Google Python Style Guide
- 所有函数必须有 docstring
- 函数不超过 50 行，使用 type hints
- 变量命名: snake_case
- 禁止裸 print()，使用 logging 模块

核心价值
- 描述要什么而非怎么做，让 Agent 自己决定最优执行路径
- 可审计、可版本控制、可协作，三位一体的工程化保障

AGENTS.md 实战：六个组成部分与上下文管理

简介：AGENTS.md 是 SDD 三层规范的第一层，按六个部分写，控制篇幅，重要规则放前面

从 Memory 到规范驱动开发（SDD）

层级	文件	作用
项目规范	`AGENTS.md`	项目的技术栈、编码规范、架构约束
角色规范	`agents/*.md`	每个 Agent 的身份、权限、职责
能力规范	`skills/*/SKILL.md`	每个可复用技能的步骤和输入输出

六个组成部分

部分	内容	目的
项目概述	一句话说清项目是什么、做什么	让 Agent 建立全局认知
技术栈	语言、框架、数据库、测试工具	防止 Agent 推荐错误的技术
编码规范	命名规则、代码风格、禁止项	统一团队代码风格
项目结构	目录布局和职责	让 Agent 知道代码该放哪里
工作流程	提交规范、分支策略、CI/CD	与团队流程对齐
特殊约束	安全、性能、合规要求	守住底线红线

知识库项目的 AGENTS.md（参考实现）

# AGENTS.md — AI 知识库助手项目规范

## 项目概述
个人 AI 知识库助手系统。自动从 GitHub Trending、Hacker News 采集内容，
AI 分析后结构化存储，支持多渠道分发。

## 技术栈
- 语言: Python 3.12
- AI 编排: OpenCode + 国产大模型（DeepSeek/Qwen/GLM/Kimi）
- 工作流: LangGraph
- 部署: OpenClaw
- 依赖管理: pip + requirements.txt
- 版本控制: Git

## 编码规范
- 遵循 PEP 8，变量 snake_case，类名 PascalCase
- 所有函数必须有 docstring（Google 风格）
- 禁止裸 print()，使用 logging 或写入文件
- 禁止 import *，文件编码统一 UTF-8

## 项目结构
ai-knowledge-base/
├── AGENTS.md                  — 项目规范（本文件）
├── .opencode/
│   ├── agents/                — Agent 角色定义文件
│   └── skills/                — 可复用技能包
├── knowledge/
│   ├── raw/                   — 原始采集数据（JSON）
│   └── articles/              — 结构化知识条目（JSON）
├── pipeline/                  — 自动化流水线
└── workflows/                 — LangGraph 工作流

## 内容规范
- 摘要中文、不超过 100 字，技术术语保留英文原文
- 评分 1-10：9-10 改变格局，7-8 直接有帮助，5-6 值得了解

## 知识条目格式
必填字段：id, title, source_url, summary, tags, status
status 可选值：draft / reviewed / published

## Agent 角色概览
| 角色 | 文件 | 职责 |
|------|------|------|
| 采集 Agent | .opencode/agents/collector.md | 从外部源采集技术动态 |
| 分析 Agent | .opencode/agents/analyzer.md | 深度分析和价值评估 |
| 整理 Agent | .opencode/agents/organizer.md | 去重、格式化、归档 |

## 红线（绝对禁止）
- 不编造不存在的项目或数据
- 不在日志中输出 API Key 或敏感信息
- 不执行 rm -rf 等危险命令
- 不修改 AGENTS.md 本身（除非明确要求）

{
  "id": "2026-03-01-github-openclaw",
  "title": "OpenClaw: 开源 AI Agent 运行时",
  "source": "github-trending",
  "source_url": "https://github.com/example/project",
  "collected_at": "2026-03-01T10:00:00Z",
  "summary": "一句话中文摘要（不超过 100 字）",
  "analysis": {"tech_highlights": ["多 Agent 路由", "50+ 平台支持"], "relevance_score": 9},
  "tags": ["agent", "runtime", "open-source"],
  "status": "draft"
}

红线部分守住底线，知识条目格式让所有 Agent 的产出可以互相读懂，这也是 AGENTS.md 和普通 README 的区别
编码规范注入（详细版）

## 编码规范 (详细版)
### 命名规则
- 文件名: kebab-case (如 user-service.py)
- 类名: PascalCase (如 UserService)
- 函数/变量: snake_case (如 get_user_by_id)
- 常量: UPPER_SNAKE_CASE (如 MAX_RETRY_COUNT)
- 私有方法: 前缀下划线 (如 _validate_input)
### 必须遵守
- 每个函数不超过 30 行，每个文件不超过 300 行
- 所有公开函数必须有 docstring (Google 风格)
- 所有 API 返回统一格式: {"code": 0, "data": ..., "msg": ""}
### 禁止事项
- 禁止 print() 调试，使用 logging
- 禁止 import *
- 禁止在循环中进行数据库查询 (N+1 问题)
- 禁止硬编码密钥或密码

上下文管理策略

策略	做法
分层配置	根目录 `AGENTS.md` 放通用规则，子目录放特定规则
保持精简	控制在 500 行以内，太长反而稀释关键信息
优先级明确	最重要的规则放最前面，Agent 注意力有衰减
定期维护	随项目演进更新，过期规则及时清理
团队共建	Memory 文件纳入 Code Review 流程

效果演示：同一条指令的产出差异

检查项	无 Memory（自由发挥）	有 Memory（遵守规范）
框架	猜错，用了 Flask	正确使用 FastAPI + Pydantic
命名	camelCase	snake_case
日志	`print()`	`logging` 模块
类型与文档	没有 type hints	完整的 type hints 和 docstring
返回格式	不统一	统一 `{"code": 0, "data": ...}`
文件位置	放在根目录	放在 `backend/api/` 下

验证 Memory 是否加载
- 启动 OpenCode 后问“请告诉我这个项目的技术栈和编码规范”，检查回答是否包含 Python 3.12、PEP 8、snake_case、禁止裸 print()、目录结构
- 对比实验：把 AGENTS.md 临时改名为 AGENTS.md.bak，用完全相同的提示词再生成一次，比较命名、docstring、日志、错误处理、文件位置
注意点
- 对比实验后务必把 AGENTS.md 改回来，后续实操都依赖它
- 做无 Memory 对比时要同时删掉上一轮生成的文件，否则会相互影响，足够聪明的 AI Coder 也可能去参考备份文件
- 发现 Agent 产出不符合期望，先想 AGENTS.md 缺了哪条规则，补上去

SDD 强化：手写第一份 spec 与 grill-me 追问

简介：SDD 不需要装任何工具，核心是 Specify、Clarify、Implement 三阶段闭环，缺的不是模板而是一个会追问你的对手

三阶段闭环

SDD 三阶段闭环

红色节点是 SDD 和直接发一段话让 AI 干活的本质区别，绿色是让两周后还记得的关键
Clarify 阶段 AI 的每个追问都给推荐答案，可以接受、改成自己的，或说“你决定”放权
spec 模板：四个 H2

# AI 知识库 · 项目愿景 v0.1

## 要做什么
- 每天抓取 GitHub Trending（? 多少条 · 只 AI 相关？）
- 用 Agent 分析内容（? 分析什么 · 输出啥）
- 输出知识条目（? JSON 还是 Markdown · 字段有哪些）

## 不做什么

## 边界 & 验收

## 怎么验证

留下的 ? 是下一阶段给 AI 质询的靶子
这份愿景 spec 最终变成 AGENTS.md 的项目定义段，编码规范 spec 变成 AGENTS.md 的编码规范段
grill-me：让 AI 变成面试官
- 来自 Matt Pocock 的开源技能集，6 行 Markdown，装完 AI 会一条条拷问 AGENTS.md 里的模糊点

npx skills@latest add mattpocock/skills/grill-me -a opencode   # Claude Code 用 -a claude-code
ls ~/.opencode/skills/grill-me/SKILL.md                         # 装完重启 CLI

skill 靠 SKILL.md 里的 description 字段自动触发，不需要 /skill 前缀，直接说 “grill me on my AGENTS.md”
用法：先在 specs/coding-standards.md 写粗糙版（black 格式化、strict mode、覆盖率 ≥ 80%、不允许 TODO 进 main），再让 grill-me 追问，最后把结论写进 AGENTS.md
直接聊（A 路）vs SDD 闭环（B 路）

维度	A 路：直接发一段话	B 路：SDD 闭环
时间	5 分钟	25~30 分钟
产出	一份 200 字散文 / 15 行规范	spec + `AGENTS.md` + 验证报告
覆盖维度	约 5 个	约 15 个
发现盲点	0	3~4 个
走偏概率	高	低
改需求成本	全重写	改 spec 一条即可
两周后记得	难	易，spec 在 git 里

多花的 25 分钟不是额外开销，是把调试 2000 行代码的成本提前投入在澄清需求阶段
A 路输在没想到的就漏了，例如规范里根本没写行宽，同事抱怨时才发现
grill-me 的价值不是直接帮你写，是帮你发现你没想到的

面试/考试记忆点

编程 = 设计意图 × 精确表达 × 验证产出，80% 想清楚要什么，20% 让 AI 实现
三层架构：你写的 SDD 规范、Harness 运行时、无状态模型，上层加载下层调用
模型是无状态函数，三个约束是无记忆、无决策、无行动
Harness = 编排器 + 规范化，补上循环、记忆、行动三个能力，while True: 观察 → 思考 → 行动 → 更新状态
Harness 比模型更重要，同一模型换 Harness 的差距远大于换模型
规范一直有效的原因是 Harness 在每次上下文压缩后重新注入 AGENTS.md
Memory 不是数据库，是声明式的意图描述文件，相当于项目入职手册
声明式写 What 不写 How，可审计、可版本控制、可协作、可迁移、可组合、低耦合
AGENTS.md 六个部分：项目概述、技术栈、编码规范、项目结构、工作流程、特殊约束，控制在 500 行内，重要规则放前面
SDD 三阶段 Specify、Clarify、Implement，spec 里故意留 ? 给 AI 追问