简介模型是无状态的推理函数Harness 是有状态的编排器人要做的是写规范、验结果AGENTS.md 这类 Memory 文件用声明式配置让 Agent 读懂项目并在上下文压缩后持续生效范式转换从写代码到写规范简介Software 3.0 时代编程不再等于写代码80% 时间想清楚要什么20% 时间验证 AI 做得对不对Software 三代演进阶段做法典型Software 1.0手写每一行代码if-else、for 循环Software 2.0用数据训练模型替代手写规则ML / Deep LearningSoftware 3.0用自然语言描述意图AI 生成实现LLM Agent范式转换的本质你不再是代码的生产者而是意图的传达者和质量的把关者时间分配的变化编码时间压缩到 20%规划和测试时间翻倍新比例约为 Planning 40%、Coding 20%、Testing 40%启示需要更强的架构设计能力和验证能力设计反转Design Inversion传统人写代码AI 辅助新范式人写规范AI 写代码80% 时间想清楚要什么写规范20% 时间验证 AI 做得对不对实现力高原Implementation PlateauAI 写代码的能力已进入高原期SWE-bench 的代际提升只有个位数百分比不是不进步而是够用了十个人用同样的模型、同样的额度产出差异可以有十倍区别在规范瓶颈不在模型在你能不能把需求说清楚核心观点编程 ≠ 写代码编程 设计意图 × 精确表达 × 验证产出循环是 Design、Prompt、Validate、Iterate底层架构规范、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工具类型开源国产模型MemoryAgent 编排OpenCode终端 AgentMIT 开源原生支持AGENTS.md原生支持Claude Code终端 Agent闭源不支持CLAUDE.md原生支持CursorIDE 插件闭源部分支持.cursorrulesComposerWindsurfIDE 插件闭源部分支持RulesCascadeCopilotIDE 插件闭源不支持.github/copilot有限TraeIDE 插件闭源原生支持RulesBuilder工程化能力六维对比能力维度OpenCodeClaude CodeCursor说明Memory 记忆AGENTS.mdCLAUDE.md.cursorrules持久化项目上下文Sub-Agents 委派原生支持原生支持Composer任务分解与委派Skills 技能原生支持原生支持自定义命令可复用能力封装Hooks 事件原生支持原生支持有限事件驱动自动化MCP 协议原生支持原生支持部分支持外部工具集成Headless CI/CD原生支持原生支持不支持无人值守运行OpenCode 与 Claude Code 概念映射概念OpenCodeClaude Code本质项目记忆AGENTS.mdCLAUDE.md持久化上下文注入子 AgentSub-Agent 原语SubAgent 原语隔离上下文的任务委派技能包Skill 文件SKILL.md声明式能力封装快捷命令Slash CommandSlash Command用户触发的预定义流程事件钩子Hook 配置Hook 配置工具执行前后的自动化外部工具MCP ServerMCP Server标准化外部能力接入无人值守Headless 模式Headless 模式CI/CD 集成编程 SDKAPI / SDKAgent SDK程序化调用 Agent为什么以 OpenCode 为主线MIT 开源代码完全公开可学习架构设计、可二次开发100K Stars社区活跃问题有人答国产模型原生支持DeepSeek / Qwen / GLM / Kimi 零成本接入概念映射完整与 Claude Code 六大能力一一对应安装遇到问题时Cursor、通义灵码、Trae、Claude Code、Cline 等任意工具都能替代AI 辅助开发的道理相通工程思想无状态推理 有状态编排简介模型是极其强大但完全被动的推理函数编排器给它加上循环、记忆和行动才变成一个系统模型的本质无状态函数大语言模型 f(input) → output每次调用都独立没有记忆、没有状态三个关键约束约束含义无记忆上一轮说了什么模型完全不知道除非重新喂给它无决策模型不会主动决定下一步做什么只回答当前问题无行动不能读文件、不能调 API、不能执行任何操作编排器的本质有状态系统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 编排importos, json, urllib.requestAPI_KEYos.environ.get(DEEPSEEK_API_KEY,)API_URLhttps://api.deepseek.com/chat/completionsdefcall_api(prompt:str)-str:datajson.dumps({model:deepseek-chat,messages: [{role:user,content: prompt}],max_tokens:1000,}).encode(utf-8)requrllib.request.Request(API_URL, datadata, headers{Content-Type:application/json,Authorization:fBearer{API_KEY},})withurllib.request.urlopen(req)asresp:returnjson.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 编码自动化人驱动对话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首次对话成功即可安装# macOSbrewinstall nodenode--version# 需要 18npminstall-gopencode-ailatest# 或 curl -fsSL https://opencode.ai/install | bashopencode--version国产模型 API Key方案入口特点DeepSeek推荐platform.deepseek.com约 ¥1 / 百万 tokens最便宜的高质量模型充 ¥5~10 可用很久智谱 GLMopen.bigmodel.cn新用户有免费额度零成本试用阿里云 Qwenbailian.console.aliyun.com开通百炼服务后获取 DashScope API Keyechoexport DEEPSEEK_API_KEYsk-你的key~/.zshrc# bash 用 ~/.bashrcsource~/.zshrcecho$DEEPSEEK_API_KEYmkdir~/opencode-testcd~/opencode-testopencode# 输入“你好请回复 OK 确认连通”注意点API Key 只显示一次创建后立即复制保存自查清单Node 18、opencode --version有输出、Key 已获取、环境变量已配置、首次启动成功、对话回复 OKMemory 工程让 Agent 拥有持久记忆简介Memory 是一个纯文本配置文件每次会话自动加载进提示词相当于新员工入职读的项目开发手册两种记忆类型说明会话记忆短期当前对话的上下文关闭即丢失项目记忆长期写在文件里的规则和知识跨会话持久存在Memory 不是数据库是声明式的意图描述文件没有 Memory vs 有 Memory维度没有 Memory 的 Agent有 Memory 的 Agent身份每次会话都是新员工每次会话都是老员工项目认知不知道用什么框架清楚技术栈和架构编码规范不清楚规范和命名习惯遵循团队编码规范代码风格可能不符合团队风格生成的代码风格一致提醒成本需要反复提醒同样的信息自动遵守约定产出质量不稳定依赖提示词稳定可预期各工具的 Memory 文件工具Memory 文件位置格式Claude CodeCLAUDE.md项目根目录MarkdownOpenCodeAGENTS.md项目根目录MarkdownCursor.cursorrules项目根目录纯文本 / MarkdownWindsurf.windsurfrules项目根目录纯文本 / MarkdownGitHub Copilotcopilot-instructions.md.github/MarkdownCline.clinerules项目根目录纯文本 / MarkdownClaude 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 的每一步行为defconfigure_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-所有函数必须有 docstringGoogle 风格-禁止裸 print()使用 logging 或写入文件-禁止 import *文件编码统一 UTF-8## 项目结构ai-knowledge-base/├── AGENTS.md — 项目规范本文件├── .opencode/│ ├── agents/ — Agent 角色定义文件│ └── skills/ — 可复用技能包├── knowledge/│ ├── raw/ — 原始采集数据JSON│ └── articles/ — 结构化知识条目JSON├── pipeline/ — 自动化流水线└── workflows/ — LangGraph 工作流## 内容规范-摘要中文、不超过 100 字技术术语保留英文原文-评分 1-109-10 改变格局7-8 直接有帮助5-6 值得了解## 知识条目格式必填字段id, title, source_url, summary, tags, statusstatus 可选值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 *-禁止在循环中进行数据库查询 (N1 问题)-禁止硬编码密钥或密码上下文管理策略策略做法分层配置根目录AGENTS.md放通用规则子目录放特定规则保持精简控制在 500 行以内太长反而稀释关键信息优先级明确最重要的规则放最前面Agent 注意力有衰减定期维护随项目演进更新过期规则及时清理团队共建Memory 文件纳入 Code Review 流程效果演示同一条指令的产出差异检查项无 Memory自由发挥有 Memory遵守规范框架猜错用了 Flask正确使用 FastAPI Pydantic命名camelCasesnake_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 和直接发一段话让 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里的模糊点npxskillslatest add mattpocock/skills/grill-me-aopencode# Claude Code 用 -a claude-codels~/.opencode/skills/grill-me/SKILL.md# 装完重启 CLIskill 靠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 个发现盲点03~4 个走偏概率高低改需求成本全重写改 spec 一条即可两周后记得难易spec 在 git 里多花的 25 分钟不是额外开销是把调试 2000 行代码的成本提前投入在澄清需求阶段A 路输在没想到的就漏了例如规范里根本没写行宽同事抱怨时才发现grill-me 的价值不是直接帮你写是帮你发现你没想到的面试/考试记忆点编程 设计意图 × 精确表达 × 验证产出80% 想清楚要什么20% 让 AI 实现三层架构你写的 SDD 规范、Harness 运行时、无状态模型上层加载下层调用模型是无状态函数三个约束是无记忆、无决策、无行动Harness 编排器 规范化补上循环、记忆、行动三个能力while True: 观察 → 思考 → 行动 → 更新状态Harness 比模型更重要同一模型换 Harness 的差距远大于换模型规范一直有效的原因是 Harness 在每次上下文压缩后重新注入AGENTS.mdMemory 不是数据库是声明式的意图描述文件相当于项目入职手册声明式写 What 不写 How可审计、可版本控制、可协作、可迁移、可组合、低耦合AGENTS.md六个部分项目概述、技术栈、编码规范、项目结构、工作流程、特殊约束控制在 500 行内重要规则放前面SDD 三阶段 Specify、Clarify、Implementspec 里故意留?给 AI 追问