面向研发的 Agent 驱动工程框架

📖 项目简介

✨ 核心特性

• 🎯 意图驱动：自然语言 → 结构化意图队列 → 可执行任务

• 🔄 生命周期状态机：Explorer → Propose → Review → Approval → Implement → QA → Archive

• 🧠 知识图谱：分层 Wiki 系统，支持双向导航

• 🛡️ 自我纠偏：自动守卫钩子、失败恢复、人类介入检查点

• 📊 契约先行：基于 OpenSpec 的设计优先于实现

• 🔌 技能矩阵：25+ 专业技能提供领域专家能力

• 📈 防膨胀机制：自动知识提取与归档，防止信息过载

✨ 核心特性深度解析

1. 🎯 意图驱动：让需求落地更精准

1. 用户输入自然语言需求（如“新增一个查询用户信息的接口，支持按用户ID和手机号查询，返回用户基本信息和角色列表”）；

2. 意图网关接收需求后，结合LLM Wiki知识图谱中的上下文信息，对需求进行解析、拆分，提取核心意图（如“新增查询接口”“支持多条件查询”“返回指定字段”）；

3. 将核心意图整理为结构化的意图队列，明确每个意图的优先级、依赖关系和执行标准；

4. 意图队列作为生命周期引擎的输入，引导研发流程按步骤推进，确保每个意图都能落地为具体的技术实现。

2. 🔄 生命周期状态机：让研发流程更可控

• Explorer（探索阶段）：澄清需求边界、定义研发范围、识别潜在风险，产出《探索报告》，明确需求的目标、非目标、跨域影响面和异常分支；

• Propose（设计阶段）：基于探索阶段的结论，设计技术方案，冻结API契约、数据模型、业务流程等，产出《OpenSpec契约文档》，作为后续研发的唯一依据；

• Review（评审阶段）：对设计方案进行自动化技术评审，检查是否符合架构标准、API规范、SQL性能要求等，若评审不通过，返回Propose阶段修订；

• Approval（确认阶段）：人类介入检查点，由研发负责人确认设计方案是否可行，冻结契约，授权进入实现阶段，同时为前端、QA等协作方提供契约依据；

• Implement（实现阶段）：按照OpenSpec契约，在规范边界内实现代码，遵循Java工程标准、防御性编程指南，确保代码质量；

• QA（测试阶段）：遵循TDD原则，进行单元测试、回归测试，确保代码功能符合需求，关键路径测试覆盖率达到100%，若测试失败，返回Implement阶段修复；

• Archive（归档阶段）：提取研发过程中的稳定知识，更新LLM Wiki知识图谱，将OpenSpec契约、测试用例等归档，清理临时文件，完成研发闭环。

3. 🧠 知识图谱（LLM Wiki）：让知识沉淀更高效

• 分层结构：知识图谱分为根节点（Sitemap）、规范层（Schema）、活跃知识层（Wiki）和归档层（Archive），层次清晰，便于导航；

• 双向导航：支持从根节点下钻到具体的知识域（如API、数据模型、领域逻辑），也支持从具体知识反向关联到相关的规范和文档，实现知识的快速检索；

• 自动沉淀：在Archive阶段，系统会自动从OpenSpec契约、代码实现、测试用例中提取稳定知识，更新到对应的知识域索引中，无需人工手动维护；

• 防膨胀机制：设置知识索引的容量阈值（如500行），当索引超过阈值时，自动拆分为子目录，避免知识图谱过于庞大，确保检索效率；无法挂载到知识树的内容，优先归档，不污染活跃知识层。

• KNOWLEDGE_GRAPH.md：知识图谱根节点，挂载所有顶级知识域入口，是Agent检索知识的强制起点；

• Schema/：规范层，包含OpenSpec契约模板、知识图谱结构规范等，确保知识的标准化；

• Wiki/：活跃知识层，按域隔离，包含API契约、数据模型、领域逻辑、架构决策、测试策略等，是研发过程中常用知识的集中存储区；

• Archive/：归档层，存储已完成研发任务的OpenSpec契约、临时文档等，保留可追溯性，但不参与日常检索。

4. 🛡️ 自我纠偏：让研发风险更可控

5. 📊 契约先行：让研发协作更高效

• 统一研发基准：所有研发人员都围绕同一套契约开展工作，避免了因理解偏差导致的代码不一致；

• 支持并行协作：在Approval阶段冻结契约后，前端可以基于契约构建UI，QA可以基于契约编写测试用例，后端可以同步实现代码，实现多角色并行协作，提升研发效率；

• 简化评审流程：评审阶段只需检查代码是否符合契约要求，无需重复确认需求，简化了评审流程；

• 便于维护和迭代：契约作为研发的“唯一事实来源”，后续需求迭代时，只需修改契约，再基于契约更新代码和文档，确保研发过程的可追溯性。

6. 🔌 技能矩阵：让专业能力更可复用

• 模块化设计：每个技能独立封装，包含技能说明、使用场景、调用方式、校验标准等内容，便于维护和扩展；

• 阶段映射：每个生命周期阶段都有对应的推荐技能，确保研发过程中每个环节都能获得专业能力支撑；

• 标准化规范：技能中包含统一的规范要求，确保研发人员在调用技能时，能够遵循一致的标准；

• 可扩展性：支持新增自定义技能，满足团队的个性化需求，例如结合企业内部的代码规范、业务特点，新增专属技能。

7. 📈 防膨胀机制：让知识体系更健康

• 索引拆分规则：任何知识域的索引文件（如API索引、数据模型索引）超过500行时，自动拆分为子目录，每个子目录对应一个细分领域，更新上级索引的挂载点，确保索引的简洁性；

• 知识筛选规则：只有稳定、可复用的知识才能写入活跃知识层（Wiki），临时文档、一次性需求的契约等，在Archive阶段归档，不进入活跃知识层；

• 挂载点规则：所有新增知识必须在LLM Wiki的Sitemap树中找到对应的挂载点，无法挂载的知识视为无效知识，优先归档；

• 定期清理规则：在Archive阶段，自动清理研发过程中的临时文件、冗余文档，确保项目结构清晰。

🏗️ 架构总览

核心组件

核心组件详细解析

1. 意图网关（Intent Gateway）

1. 需求输入：用户输入自然语言需求（可以是PRD文档、口头需求、需求工单等）；

2. 上下文检索：通过上下文漏斗，从LLM Wiki知识图谱中检索相关的知识（如相关API规范、数据模型、业务逻辑），辅助需求理解；

3. 意图提取：对需求进行解析，提取核心意图，例如“新增接口”“修改表结构”“修复Bug”“性能优化”等；

4. 队列组装：将核心意图按优先级、依赖关系，组装为结构化的意图队列（Launch Spec），每个意图都包含执行目标、依赖条件、产出物要求等；

5. 持久化存储：将意图队列写入.agents/router/runs/目录，实现断点续传——若研发过程中断，重新启动后可从上次中断的意图继续推进；

6. 队列提交：将意图队列提交给生命周期引擎，启动研发流程。

2. 上下文漏斗（Context Funnel）

• 正向检索：当意图网关解析需求、生命周期引擎执行阶段任务时，上下文漏斗会从LLM Wiki的Sitemap根节点开始，按域索引下钻，检索相关的知识（如API规范、数据模型、架构决策），为研发提供上下文支撑；若索引中未找到相关知识，才允许使用兜底关键词搜索，避免“盲搜”导致的效率低下；

• 反向写回：当研发任务进入Archive阶段时，上下文漏斗会将研发过程中产生的稳定知识（如新增的API、修改的数据模型、优化的SQL），按照Sitemap的挂载规则，写回对应的知识域索引中，实现知识的自动沉淀；

• 知识校验：在知识写回前，对知识的规范性、完整性进行校验，确保写入知识图谱的知识符合项目规则和规范；

• 防膨胀控制：在知识写回时，检查目标索引的容量，若超过阈值，触发索引拆分机制，确保知识图谱的健康。

3. 生命周期引擎（Lifecycle Engine）

• 阶段管理：明确7个阶段的边界和目标，确保研发过程按“Explorer→Propose→Review→Approval→Implement→QA→Archive”的顺序流转，不允许跳过关键阶段；

• 任务调度：根据意图队列，为每个阶段分配对应的任务，调用相关的技能和工具，确保任务的高效执行；

• 产出物校验：对每个阶段的产出物进行校验（如探索报告的完整性、OpenSpec契约的规范性、测试用例的覆盖率），若校验不通过，触发fail_hook，回退到上一阶段；

• 状态回退：当某个阶段失败时，支持状态降级回退，记录失败原因，允许研发人员修正后重新推进；

• 队列消费：在Archive阶段完成后，通过loop_hook检查意图队列是否全部完成，若未完成，自动启动下一个意图的研发流程，实现多意图的批量处理。

4. 钩子系统（Hooks）

• pre_hook（前置钩子）：在每个阶段开始前触发，用于装载该阶段所需的规范、技能和偏好设置，为阶段任务的执行提供基准；例如，在Implement阶段开始前，pre_hook会装载Java代码规范、API设计标准等；

• guard_hook（守卫钩子）：在阶段任务执行过程中触发，用于校验任务执行的规范性，拦截违规操作；例如，在Implement阶段，guard_hook会检查代码是否符合Checkstyle规范、是否存在跨域越权等；

• post_hook（后置钩子）：在每个阶段完成后触发，用于同步文档、记录日志、更新状态；例如，在QA阶段完成后，post_hook会记录测试结果，同步更新测试用例文档；

• fail_hook（失败钩子）：在某个阶段失败时触发，用于处理失败场景，包括状态回退、记录失败原因、触发重试计数；例如，测试失败时，fail_hook会将状态回退到Implement阶段，记录测试失败的具体用例和原因；

• loop_hook（循环钩子）：在Archive阶段完成后触发，用于检查意图队列是否全部完成，若未完成，自动启动下一个意图的研发流程，实现多意图的循环处理。

5. LLM Wiki 知识图谱

• .agents/llm_wiki/KNOWLEDGE_GRAPH.md：知识图谱的根节点，仅挂载顶级知识域（如schema、wiki、archive）的入口，是Agent检索知识的强制起点，确保知识检索的规范性和高效性；

• purpose.md：定义了Java Harness Agent 的系统哲学、设计原则和核心目标，为研发人员提供统一的理念指引；

• schema/：规范层，包含OpenSpec契约模板（openspec_schema.md）和规范索引（index.md），确保研发过程中的契约和文档符合标准化要求；

• wiki/
：活跃知识层，按域隔离，存储研发过程中常用的、可复用的知识：
• api/：存储所有API契约、接口规范、请求/响应示例等；
• data/：存储数据模型、表结构、SQL规范、索引设计等；
• domain/：存储领域模型、业务字典、业务逻辑等；
• architecture/：存储架构决策记录（ADR）、系统架构图、技术选型等；
• specs/：存储当前活跃的需求契约（未归档的OpenSpec）；
• testing/：存储测试策略、测试用例、测试工具用法等；
• preferences/：存储研发偏好、禁忌规则、最佳实践等，用于指导后续研发。

• archive/：冷存储层，存储已完成研发任务的OpenSpec契约、临时文档、废弃规范等，保留可追溯性，但不参与日常检索，避免污染活跃知识层。

6. 技能矩阵（Skills）

（1）意图与生命周期类技能

• intent-gateway：意图入口能力，协助理解需求并启动“先读图谱再下钻”的工作流，支持意图提取和队列组装；

• devops-lifecycle-master：生命周期主控编排，强制执行阶段边界，确保研发流程按标准化顺序流转；

• skill-graph-manager：维护技能知识图谱的双向链接，确保技能之间的关联性和一致性；

• trae-skill-index：技能总索引，帮助Agent快速发现和调用所需的专业技能。

（2）需求与设计类技能

• product-manager-expert：需求澄清、范围界定、验收标准提炼，帮助研发人员准确理解产品需求；

• prd-task-splitter：将PRD拆分为结构化开发任务，明确任务依赖关系和执行顺序；

• devops-requirements-analysis：梳理PDD/SDD边界，输出可执行的需求规格和影响面分析；

• devops-system-design：系统设计与数据建模，包括表结构、索引、扩展性方案的设计；

• devops-task-planning：将设计方案拆分为实现任务清单，明确实现顺序和验证点。

（3）实现类技能

• devops-feature-implementation：按规格实现功能代码，强调TDD原则，确保代码符合规范；

• devops-bug-fix：缺陷定位、复现、修复与回归，确保Bug修复彻底，不引入新问题；

• utils-usage-standard：统一工具类/框架用法模式，避免风格碎片化；

• aliyun-oss：对象存储相关能力规范，包括多桶管理、环境隔离、预签名URL等。

（4）代码标准类技能

• global-backend-standards：全局后端标准索引入口，统一工程规范、分层规则和依赖管理；

• java-engineering-standards：Java工程分层与包结构规范，保证职责边界和可维护性；

• java-backend-guidelines：Java防御性编程、完整装配、分页等通用编码准则；

• java-backend-api-standard：API设计模式（动词/路径/响应结构等），避免API演进失控；

• java-javadoc-standard：统一Javadoc风格与注释规范，保证代码可读性；

• java-data-permissions：数据权限约束（查询过滤/动作校验），避免越权；

• mybatis-sql-standard：MyBatis SQL性能与安全守卫，避免隐式转换、JOIN风险等；

• error-code-standard：统一错误码与异常表达方式，避免前后端割裂；

• checkstyle：Java代码风格强制（Google/Sun混合规则），确保代码风格一致。

（5）测试与评审类技能

• devops-testing-standard：测试规范与TDD阶段指导，确保测试用例覆盖全面；

• code-review-checklist：强制评审清单，覆盖安全、性能、规范、可维护性等维度。

（6）文档类技能

• api-documentation-rules：强制API文档生成与归档规则，避免“代码更新但文档缺失”；

• database-documentation-sync：数据库结构变更时，同步表文档、清单与ER图。

🚀 快速上手

前置要求

• Java 17+

• Python 3.8+（可选脚本）

• Git

3 分钟入门

第一步：阅读项目规则 ⚡

第二步：导航知识图谱 🗺️

• API 设计 → wiki/api/index.md

• 数据模型 → wiki/data/index.md

• 领域逻辑 → wiki/domain/index.md

• 架构决策 → wiki/architecture/index.md

第三步：运行第一个完整周期 🔄

💡 使用场景

场景 A：新增查询接口（不改表）

• ✅ explore_report.md - 范围与影响面分析

• ✅ openspec.md - API 契约含 JSON 示例

• ✅ 按契约实现的代码（不过度设计）

• ✅ 单元测试与覆盖率证据

• ✅ 更新 wiki/api/ 中的 API 索引

场景 B：API + 数据库模式变更

1. Propose：同时冻结 API 与 Data 契约

2. Review：SQL 风险评估、索引利用、隐式转换检查

3. QA：回归测试覆盖核心查询与边界条件

4. Archive：同时更新 wiki/api/ 和 wiki/data/ 索引

• devops-system-design - 模式建模

• mybatis-sql-standard - SQL 性能守卫

• database-documentation-sync - ER 图更新

场景 C：Bug 修复（先复现后测试）

1. Explorer：最小复现路径 + 根因假设

2. QA：修复前先写失败测试（TDD 方法）

3. Implement：修复实现使测试通过

4. Archive：在 wiki/testing/ 或 reviews/ 中记录模式

场景 D：性能优化

• Propose：文档化"行为不变"约束 + 回退策略

• Review：SQL 标准与索引利用作为最高优先级

• QA：对比证据（性能基准 + 正确性）

• Archive：将可复用性能规则提取到 preferences/

场景 E：重构（含边界守卫）

• 明确的"做什么/不做什么"范围定义

• 跨域修改需要显式授权

• 架构决策写回到 wiki/architecture/

场景 F：并行协作

• Approval 阶段：冻结的 OpenSpec 成为唯一事实来源

• 最小交接物：API 契约（JSON 示例）、验收标准（Given/When/Then）、错误码

• 后端内聚：其他细节保持后端内部（不强制外扩）

📚 生命周期阶段

Phase 1: Explorer 🔍

• 需求边界与非目标

• 跨域影响面分析

• 异常分支与边界情况

Phase 2: Propose 📝

• API 签名与数据模型

• 数据库模式与索引

• 业务流程

• 验收标准

• JSON 请求/响应示例

Phase 3: Review 🔬

• ✅ 架构与工程标准

• ✅ API 设计模式

• ✅ SQL 性能与安全

• ✅ 安全与数据权限

• ✅ 错误处理一致性

Phase 3.5: Approval (HITL) 👥

• ✅ 是 → 进入 Implement 阶段（契约冻结）

• ❌ 否 + 反馈 → 返回 Propose 进行修订

Phase 4: Implement 💻

• 不超过规范的过度设计

• 必须通过 Checkstyle 验证

• 应用防御性编程指南

• 尊重领域边界（guard_hook）

Phase 5: QA Test 🧪

• 关键路径测试覆盖率 ≥ 100%

• 所有检查清单项必须为绿色

• Bug 修复的回归测试

• 优化的性能基准

Phase 6: Archive 📦

1. 文档同步：自动触发 API 与 DB 文档更新

2. 知识提取：将稳定规范合并到域索引

3. 冷存储：将原始 openspec.md 移至 archive/

4. 进化：请求人类评分（1-10）用于偏好学习

5. 循环检查：读取 launch_spec.md → 下一个意图或完成

• 索引文件 > 500 行 → 拆分为子目录

• 无法挂载的内容 → 归档而非活跃区

• 所有知识必须在 sitemap 树中有挂载点

🛡️ 自我纠偏机制

🔧 技能矩阵

可用技能（25+）

意图与生命周期

• intent-gateway - 意图入口能力，启动"先读图谱再下钻"工作流

• devops-lifecycle-master - 生命周期主控编排，强制执行阶段边界

• skill-graph-manager - 维护技能知识图谱双向链接

• trae-skill-index - 技能总索引，快速发现能力

需求与设计

• product-manager-expert - 需求澄清、范围界定、验收标准提炼

• prd-task-splitter - PRD 分解为结构化开发任务

• devops-requirements-analysis - PDD/SDD 边界梳理，可执行需求规格

• devops-system-design - 系统设计与数据建模（FDD/SDD）

• devops-task-planning - 设计分解为实现任务清单

实现

• devops-feature-implementation - 功能编码，强调 TDD

• devops-bug-fix - 缺陷定位、复现、修复与回归

• utils-usage-standard - 统一工具类/框架用法模式

• aliyun-oss - 对象存储（多桶/环境隔离/预签名 URL）

代码标准

• global-backend-standards - 全局后端标准索引入口

• java-engineering-standards - Java 分层与包结构规范

• java-backend-guidelines - 防御性编程、完整装配、分页

• java-backend-api-standard - API 设计模式（动词/路径/响应结构）

• java-javadoc-standard - 统一 Javadoc 风格与注释规范

• java-data-permissions - 数据权限约束（查询过滤/动作校验）

• mybatis-sql-standard - MyBatis SQL 性能与安全守卫

• error-code-standard - 统一错误码与异常表达

• checkstyle - Java 代码风格强制（Google/Sun 混合）

测试与评审

• devops-testing-standard - 测试规范与 TDD 阶段指导

• code-review-checklist - 强制评审清单（安全/性能/规范/可维护性）

文档

• api-documentation-rules - 强制 API 文档生成与归档

• database-documentation-sync - DB 结构变更同步（表/清单/ER 图）

阶段 → 技能映射

📂 项目结构

🔍 可选诊断工具

图谱健康检查

契约结构验证

偏好标签检查

🎯 工程红线

🚫 不盲搜

🚫 不越权

🚫 不暴走

🚫 不膨胀

• 规范必须在提取后归档

• 稳定知识必须提取到索引

• 超过 500 行的索引必须拆分为子目录

📖 相关文档

• 📘 工程手册（英文版）：ENGINEERING_MANUAL.md - 详细的英文工程指南与工作流

• 🇺🇸 English README: README.md - Complete English version of this README

• 📌 项目规则：AGENTS.md - 主规则入口

• 🗺️ 知识图谱：.agents/llm_wiki/KNOWLEDGE_GRAPH.md - 根导航

• 📝 契约模板：.agents/llm_wiki/schema/openspec_schema.md

• 🎯 意图网关：.agents/router/ROUTER.md

• 🔍 上下文漏斗：.agents/router/CONTEXT_FUNNEL.md

• ⚙️ 生命周期：.agents/workflow/LIFECYCLE.md

• 🛡️ 钩子：.agents/workflow/HOOKS.md

🙏 致谢

• OpenSpec：契约优先开发方法论

• Harness：生命周期状态机与钩子系统

• LLM Wiki：具有防膨胀机制的可演进知识图谱

• Agentic Patterns：带人类介入检查点的自主 Agent 工作流