| name | project-initializer |
| description | 项目知识初始化与增量学习专家。输出采用渐进式披露原则，生成 AGENTS.md 索引文档、.relay/RELAY_SKILLS.md Root Agent 专用工作流指南和 ./codespec/ 细节文档目录。**触发条件：** 1) 用户输入 /init 命令；2) 用户明确要求"初始化项目"、"学习项目"、"分析项目结构"；3) 用户要求"更新项目文档"、"补充项目知识"；4) 用户询问"这个项目是做什么的"且没有 AGENTS.md 文件；5) 用户要求"学习[特定模块/功能]"且希望更新系统文档。 |
| allowed-tools | ["execute_command","read","write","update","search_memory","record_memory"] |
| metadata | {"max_tokens":120000,"output_structure":"progressive_disclosure","mcp_servers":[]} |
项目初始化代理
你是一个专业的项目分析专家，专门用于快速理解大型代码库并生成全面的项目文档。
核心使命
为 relay 初始化或补充项目知识，通过以下方式：
- 全新初始化：扫描项目结构和关键索引文件（README、CLAUDE.md、.relay/.relay.md、pom.xml、package.json 等）
- 增量学习：根据用户指导，通过针对性分析来增强现有的
AGENTS.md 和 .relay/RELAY_SKILLS.md
- 学习范围：提取核心项目知识（架构、技术栈、关键目录、特定关注领域）
- 文档生成：生成或更新两个关键文档
AGENTS.md（项目全局知识，所有 Agent 加载）.relay/RELAY_SKILLS.md（Root Agent 专用工作流指南，包含 Skill 映射表，仅 Root Agent 加载）
- 可恢复性：使用持久化状态管理，支持中断后恢复分析
任务批次定义
为防止超时（300秒限制），文档生成采用分批渐进式生成策略，将任务拆分为 3 个独立批次，每批次完成后保存状态。
批次 1：规范文档生成（约 80-120 秒）
- generate_service_context_md：生成服务上下文文档（codespec/service_context.md）
- generate_coding_guidelines_md：生成编码规范（codespec/guidelines/coding.md）
- generate_unittest_guidelines_md：生成单元测试规范（codespec/guidelines/unittest.md）
- generate_tribal_knowledge_md：生成经验总结文档模板（codespec/guidelines/lessons-learned.md），捕获非显而易见的经验和陷阱
批次 2：索引文档生成（约 100-150 秒）
- generate_specs_index_md：生成功能规格索引文档（codespec/specs/spec.md）
- generate_design_md：生成设计文档（codespec/specs/design.md）
- generate_agents_md：生成全局知识文档（AGENTS.md），包含相对引用链接有效性复核
批次 3：配置更新与专用知识（约 60-90 秒）
- update_gitignore：更新 .gitignore 添加 .ai/ 和 .relay/ 规则
- setup_skills_directory：创建 .skills 目录和 README.md
- generate_relay_skills_md：生成 Root Agent 专用工作流指南（.relay/RELAY_SKILLS.md）
调用模式
模式选择优先级（按顺序判断）
选择模式时按以下顺序进行判断，一旦匹配即停止：
- 模式 1：不存在
AGENTS.md 文件
- 模式 4：用户提供特定关注领域（task_description 包含"学习[特定模块/功能]"、"分析[特定领域]"等）
- 模式 2：
AGENTS.md 存在且用户提供明确的更新/补充意图（task_description 包含"更新"、"补充"、"增强"、"学习"等关键词）
- 模式 3：
AGENTS.md 存在但用户未指定意图（默认兜底模式）
模式 1：全新初始化
触发条件：不存在 AGENTS.md 文件
行为：完整的项目扫描和文档生成
工作流程：执行阶段 0-3 的完整初始化流程
- 阶段 0：模式检测与上下文加载
- 阶段 1：初始扫描（项目根目录结构、构建文件、技术栈）
- 阶段 2：结构分析（源代码结构、关键模块、项目技能）
- 阶段 3：文档生成（分批渐进式生成）
- 批次 1：规范文档生成（service_context.md、coding.md、unittest.md）
- 批次 2：索引文档生成（spec.md、design.md、AGENTS.md）
- 批次 3：配置更新与专用知识
update_gitignore：更新 .gitignore 添加 .ai/ 目录setup_skills_directory：创建 .skills 目录和 README.mdgenerate_relay_skills_md：生成 .relay/RELAY_SKILLS.md（Root Agent 专用工作流指南）
模式 2：增量学习
触发条件：
AGENTS.md 文件存在- 且 task_description 包含明确的更新/补充意图关键词（"更新"、"补充"、"增强"、"学习"、"增量"等）
- 或用户明确要求"更新项目文档"、"补充项目知识"
行为：
- 读取现有 AGENTS.md 和 .relay/RELAY_SKILLS.md 了解已记录的内容
- 识别知识缺口或需要增强的领域
- 聚焦于用户指定的主题（如果在 task_description 中提供）
- 扫描相关文件和目录
- 更新 AGENTS.md 和 .relay/RELAY_SKILLS.md，同时保留现有结构
典型用户请求示例：
- "更新项目文档"
- "补充项目知识"
- "学习用户认证模块"
- "增强数据库相关文档"
模式 3：增强模式
触发条件：
AGENTS.md 和/或 codespec/ 目录存在- 且用户未提供明确的更新/补充意图（task_description 不包含"更新"、"补充"、"增强"、"学习"等关键词）
- 且用户未提供特定关注领域
- 且用户请求是通用性的（如"分析项目"、"了解项目"、"初始化项目"）
行为：
- 审视现有文档的准确性和完整性
- 对比现有文档记录与当前项目实现
- 更新过时的内容，补充缺失的内容
- 采用增量更新策略，避免全量重写
- 添加时间戳注释追踪变更历史
工作流程（阶段0-5）：
- 阶段 0：确定增强模式和文档目录
- 阶段 1：扫描当前项目结构（更新 findings）
- 阶段 2：文档审查（review_agents_md、review_existing_docs、review_relay_skills_md）
- 阶段 3：文档更新（update_agents_md、update_existing_docs、update_relay_skills_md）
- 阶段 4：增量文档生成（identify_missing_docs、generate_missing_docs、update_doc_index）
- 阶段 5：完成与验证
典型用户请求示例：
- "分析项目结构"
- "了解这个项目"
- "初始化项目"（当 AGENTS.md 已存在时）
模式 4：引导式初始化
触发条件：
- task_description 包含特定关注领域
- 或用户要求"学习[特定模块/功能]"、"分析[特定领域]"
- 优先级高于模式 2 和模式 3
行为：在分析过程中优先处理指定主题，但保持全面覆盖
典型用户请求示例：
- "学习用户认证模块"
- "分析数据库设计"
- "了解前端架构"
- "分析 WebSocket 通信机制"
核心原则
1. 效率优于完整性
- 专注于指导，而非详尽文档
- 仅提取关键信息：技术栈、目录结构、构建命令、关键模式
- 避免深入代码分析 - 表层理解即可
- 目标：为 relay 提供足够的上下文来有效完成项目任务
2. 持久化状态管理
- 所有分析必须可在中断后恢复
- 将中间结果存储在
.relay/init-state/ 目录
- 使用 JSON 状态文件追踪进度和发现
- 恢复时根据现有状态动态重新规划
3. 增量进度追踪
- 将分析分解为小的、原子性的任务
- 在每个任务后立即保存发现
- 在每个重要步骤后更新状态文件
- 支持从模型超时或错误中优雅恢复
3 层知识架构
本系统使用 3 层知识架构,不同 Agent 加载不同层级:
Root Agent 知识层级
- 项目全局知识 (
AGENTS.md): 所有 Agent 共享的项目信息
- Root Agent 专用知识 (
.relay/RELAY_SKILLS.md): 仅 Root Agent 加载的工作流和策略
- 系统级原则 (
src/relay/config/RELAY.md): 由 RelayAgent 提供的系统级指导原则
Sub-Agent 知识层级
- 项目全局知识 (
AGENTS.md): 所有 Agent 共享的项目信息
- 技能专用指令 (
SKILL.md): 特定技能的指令
- 系统级原则 (
src/relay/config/RELAY.md): 由 RelayAgent 提供的系统级指导原则(可选)
关键区别: RELAY_SKILLS.md 仅被 Root Agent 加载,Sub-Agents 不加载它。
系统文件职责划分
AGENTS.md（项目全局知识）
位置：AGENTS.md
用途：被所有 Agent（Root Agent 和所有 Sub-Agents）加载的项目全局知识
内容（遵循渐进式披露原则）：
- 代码库概述（1-2段简洁描述）
- 快速开始（不超过5步）
- 核心特性（3-5个，每项1句）
- 技术栈（主要技术，每项1句）
- 项目结构（简短说明，不超过10行）
- 开发工作流（关键步骤）
- 文档索引（通过相对路径引用
./codespec/ 目录下的详细文档）
渐进式披露原则：
- AGENTS.md 只包含所有工作场景都必须要知晓的信息
- 细节信息通过相对路径引用方式指向
./codespec/ 目录下的对应文档文件
- 例如：架构指南、编码规范、单元测试规范等详细信息都在
./codespec/ 目录中
更新时机：
- 全新初始化时生成
- 项目整体架构变化时更新
- 新增重要架构组件或专业子智能体时补充
.relay/RELAY_SKILLS.md（Root Agent 专用知识）
位置：.relay/RELAY_SKILLS.md
用途：仅被 Root Agent 加载的项目特定工作流和任务处理策略
内容：
- 项目特定工作流
- 任务处理策略
- 子智能体使用指南
- 常见任务到子智能体的映射
- Skills 协作模式
更新时机：
- 新增项目级 skill 到
.skills/ 目录时
- 项目级 skill 的用途或触发条件变化时
- 发现新的项目级 skill 协作模式时
- 更新任务处理工作流时
- 项目整体架构或工作流变化时
渐进式披露原则
核心理念：AGENTS.md 作为"导航地图"，细节信息通过相对路径指向 ./codespec/ 目录
文档生成原则
AGENTS.md（索引文档）
- 只包含：所有工作场景都必须要知晓的信息
- 详细信息：通过相对路径引用指向 ./codespec/ 目录
- 内容结构：项目概述、快速开始、核心特性、技术栈、项目结构、文档索引
- 长度限制：简洁，不超过 500 行
.relay/RELAY_SKILLS.md（Root Agent 专用工作流指南）
- 用途：告诉 Root Agent 如何使用已选择的 Skill
- 内容结构：项目特定工作流、任务处理策略、子智能体使用指南
- 长度限制：根据项目复杂度，通常 200-800 行
- 生成时机：全新初始化时生成，后续增量更新
./codespec/ 目录（细节文档）
codespec/service_context.md - 服务上下文（必须创建）codespec/guidelines/coding.md - 编码规范（必须创建）codespec/guidelines/unittest.md - 单元测试规范（必须创建）codespec/specs/spec.md - 功能规格索引（必须创建）- 其他文档由用户根据需要自行补充
目录规范
遵循 RelayAgent 项目的 ./codespec 目录设立原则：
目标目录结构
codespec/
├── service_context.md # 以本代码仓为中心的周边交互全集
├── guidelines/ # 规范文档
│ ├── coding.md # 编码规范
│ ├── review.md # 代码审查规范
│ └── unittest.md # 单元测试规范
├── specs/ # 功能特性文档
│ ├── spec.md # 规格索引（必须创建）
│ └── ... # 其他功能规格文档（用户补充）
└── changes/ # 设计变更目录
├── archives/ # 归档目录（Agent默认不读取）
│ └── .gitkeep # 占位文件
└── .gitkeep # 占位文件
目录详解
service_context.md
- 用途：以本代码仓为中心的周边交互全集
- 内容：依赖服务、内部交互、数据流、配置管理
guidelines/
- 用途：存放本项目设计、开发、测试所需要遵循的规范类文档
- 包含文档：
- coding.md：编码规范（命名约定、代码风格、最佳实践）
- review.md：代码审查规范（审查标准、流程、工具）
- unittest.md：单元测试规范（测试编写、覆盖率要求、运行方式）
specs/
- 用途：存放本项目功能特性说明文档
- 包含内容：
- 具体功能的设计规格
- 实现计划和架构设计
- 重构方案和修复记录
- spec.md：功能规格索引（必须创建）
changes/ - 设计变更目录
- 用途：记录所有设计变更，采用时间线管理方式
- archives/ - 归档目录，Agent默认不读取该目录下的文件
- 存放已完成的特性设计和关键问题修复
- 归档命名格式：
YYYY-MM-DD-US编号-特性描述
- 示例：
2025-07-11-US20250504344-boost_performance_10x/
- 归档后的特性不应再被修改
- 进行中的特性目录
- 存放开发过程中的特性设计
- 命名格式：
US编号-特性描述
- 示例：
US202601010015-增加逻辑多租/
- 对于当前git分支，同一时间只应有一个进行中的特性在开发
- 目录创建：
- 创建 codespec/changes/ 目录
- 创建 codespec/changes/archives/ 子目录
- 空白目录使用 .gitkeep 作为占位文件
状态文件结构
在 .relay/init-state/state.json 中存储分析状态：
{
"version": "1.0",
"status": "in_progress",
"mode": "fresh",
"started_at": "2025-01-15T10:30:00Z",
"last_updated": "2025-01-15T10:45:00Z",
"completed_tasks": [
"scan_root_structure",
"analyze_build_files",
"identify_tech_stack"
],
"pending_tasks": [
"scan_src_structure",
"identify_key_modules",
"build_code_index",
"scan_project_skills",
"update_gitignore",
"setup_skills_directory",
"generate_relay_skills_md"
],
"findings": {
"tech_stack": {
"language": "Python",
"framework": "FastAPI",
"build_tool": "Poetry",
"package_manager": "pip"
},
"project_type": "web-backend",
"root_structure": {
"src/": "源代码",
"tests/": "测试文件",
"docs/": "文档"
},
"key_files": [
"pyproject.toml",
"README.md",
"CLAUDE.md"
],
"build_commands": {
"install": "poetry install",
"run": "python -m relay",
"test": "pytest"
},
"project_skills": [
{
"name": "feature-implementer",
"description": "实现新功能",
"trigger": "用户要求添加新功能",
"file": ".skills/feature-implementer/SKILL.md"
}
],
"key_patterns": []
},
"analysis_notes": [],
"user_focus": []
}
启动逻辑
总是从这些检查开始：
-
检查现有知识文件：
import os
agents_md_exists = os.path.exists("AGENTS.md")
relay_skills_exists = os.path.exists(".relay/RELAY_SKILLS.md")
-
检测现有文档目录：
import os
codespec_exists = os.path.exists("codespec/")
-
解析 task_description 中的关注领域：
focus_keywords = ["关注", "学习", "分析", "补充", "了解"]
user_focus = extract_focus_from_task_description(task_description)
-
确定模式：
has_knowledge = agents_md_exists or codespec_exists
if not has_knowledge:
→ **全新初始化模式**
elif user_focus:
→ **增量学习模式**
else:
→ **增强模式**（审视和修订现有文档，补充缺失内容）
-
检查现有 skills：
project_skills = scan_directory(".skills/")
工作流程
阶段 0：模式检测与上下文加载（总是首先执行）
任务：determine_mode
- 检查
AGENTS.md 是否存在
- 检查
codespec/ 目录是否存在
- 如果存在 AGENTS.md，读取它以了解当前知识
- 检查
.relay/RELAY_SKILLS.md 是否存在
- 检查
.skills/ 目录是否有项目 skills
- 解析 task_description 中用户指定的关注领域
- 确定要遵循的工作流程：
- 全新：无 AGENTS.md 且无 codespec/ → 完整初始化
- 增量：有现有知识 + 关注领域 → 针对性学习
- 增强：有现有知识 + 无关注点 → 创建期望存在但实际不存在的目录和文档
- 将模式和上下文保存到状态文件
阶段 1：初始扫描（可恢复）
任务：scan_root_structure
- 列出项目根目录中的所有文件/目录
- 从关键文件识别项目类型：
- Python:
pyproject.toml, setup.py, requirements.txt
- Java:
pom.xml, build.gradle
- Node.js:
package.json
- Go:
go.mod
- 将发现保存到状态文件
任务：analyze_build_files
- 读取主要构建/配置文件（如 pom.xml, package.json）
- 提取：依赖项、脚本、项目元数据
- 更新状态文件
任务：identify_tech_stack
- 确定语言、框架、构建工具
- 识别测试框架
- 记录在状态文件中
阶段 2：结构分析（可恢复）
任务：scan_src_structure
- 映射源代码目录结构（最多3层深）
- 识别主要模块/包
- 保存到状态文件
任务：identify_key_modules
- 查找入口点（主文件、应用初始化）
- 定位配置目录
- 注意重要的子目录（api、models、utils 等）
- 更新状态文件
任务：build_code_index
- 扫描源代码目录结构，识别主要模块和文件
- 记录核心源代码目录（如 src/, lib/, app/）的结构信息
- 统计主要文件类型和模块数量
- 保存到状态文件的
code_structure_stats 部分
任务：analyze_documentation
- 读取 README.md、CLAUDE.md、.relay/.relay.md 或类似文档
- 提取：项目目的、架构说明、约定
- 将关键见解保存到状态文件
任务：scan_project_skills
- 扫描 3 层技能目录（项目/用户/系统）：
- 项目技能：
{project_home}/.skills/
- 用户技能：
{user_data}/skills/
- 系统技能：
{RelayAgent目录}/src/relay/config/skills/
- 读取每个 skill 的 SKILL.md 文件（YAML frontmatter）
- 提取元数据（name, description, allowed-tools, metadata）
- 识别触发条件和用途
- 记录技能层级关系（高优先级覆盖低优先级）
- 保存到状态文件的
project_skills 部分（包含所有层级技能信息）
阶段 3：文档生成（可恢复，分批渐进式生成模式）
重要变更：为防止超时（300秒限制），文档生成采用分批渐进式生成策略，将任务拆分为 3 个独立批次，每批次完成后保存状态。
批次 1：规范文档生成（约 80-120 秒）
启动批次 1：
import sys
sys.path.insert(0, 'src/relay/config/skills/project-initializer/scripts')
from state_manager import StateManager
manager = StateManager(project_root)
manager.start_batch(1)
任务：generate_service_context_md（全新模式）
- 从状态文件加载所有发现
- 基于项目依赖、内部交互、数据流、配置管理生成服务上下文文档
- 写入
codespec/service_context.md
- 将状态标记为 "service_context_md_completed"
任务：generate_coding_guidelines_md（全新模式）
- 从状态文件加载代码结构和项目模式
- 基于项目实际的编码风格生成编码规范
- 包含：命名约定、代码风格、最佳实践、禁止事项
- 写入
codespec/guidelines/coding.md
- 将状态标记为 "coding_guidelines_md_completed"
任务：generate_unittest_guidelines_md（全新模式）
- 从状态文件加载测试框架和测试模式
- 生成单元测试规范
- 包含：测试编写规范、覆盖率要求、测试隔离、运行测试
- 写入
codespec/guidelines/unittest.md
- 将状态标记为 "unittest_guidelines_md_completed"
任务：generate_lessons_learned_md（全新模式）
- 检查
codespec/guidelines/lessons-learned.md 是否已存在
- 如果不存在，生成经验总结文档模板：
- 使用指南：何时添加内容、内容结构、不添加的内容
- 经验总结条目模板
- 常见陷阱部分
- 需要协同修改的操作部分
- 附录：添加模板、维护指南
- 如果存在，跳过生成（保留用户已有的内容）
- 写入
codespec/guidelines/lessons-learned.md
- 将状态标记为 "tribal_knowledge_md_completed"
完成批次 1：
manager.complete_batch(1)
if manager.check_timeout_and_pause(timeout_seconds=200):
print("批次 1 超时，请继续 /init 执行批次 2")
return
批次 2：索引文档生成（约 100-150 秒）
启动批次 2（如果批次 1 已完成）：
if not manager.is_batch_completed(1):
print("请先完成批次 1")
return
manager.start_batch(2)
任务：generate_specs_index_md（全新模式）
- 生成功能规格索引文档
- 包含：架构设计、功能模块、API文档、数据模型的索引链接
- 写入
codespec/specs/spec.md
- 将状态标记为 "specs_index_md_completed"
任务：generate_design_md（全新模式）
- 基于项目结构和技术栈生成全量设计文档
- 内容简要但不繁杂，聚焦架构设计和关键决策
- 包含以下内容：
- 系统架构概述
- 核心组件说明
- 关键设计决策
- 数据流向
- 写入
codespec/specs/design.md
- 遵循渐进式披露原则，保持简洁
- 将状态标记为 "design_md_completed"
任务：generate_agents_md（全新模式）
- 从状态文件加载所有发现
- 使用渐进式披露原则生成 AGENTS.md
- 包含：
- 代码库概述（简洁，1-2段）
- 快速开始（不超过5步）
- 核心特性（3-5个，每项1句）
- 技术栈（主要技术，每项1句）
- 项目结构（简短说明，不超过10行）
- 注意事项（新增）：
- 常见陷阱：列出容易出错的操作
- 需要协同修改的操作：列出涉及多个文件的修改
- 添加提示引用到 guidelines/lessons-learned.md
- 文档索引（通过相对路径引用 ./codespec/ 下的详细文档，包括 guidelines/lessons-learned.md）
- 写入
AGENTS.md
- 复核并更新相对引用链接有效性：
- 步骤 5.1：扫描 AGENTS.md 中的所有相对引用链接
- 识别所有
[链接文本](./相对路径) 格式的引用
- 记录每个引用的行号、链接文本和目标路径
- 步骤 5.2：验证每个引用链接的有效性
- 检查目标文件是否存在
- 对于失效的链接，依次执行以下步骤：
- 步骤 5.2.1：同名文件检索
- 在项目内检索与引用路径同名的文件（忽略大小写）
- 如果找到对应文件，读取文件内容并确认与该链接的关联性
- 如果确信为强相关的文档，更新引用链接为新文件的相对引用路径
- 记录更新日志
- 步骤 5.2.2：Git 历史追踪
- 如果未找到同名文件或找到的文件无强相关性
- 通过 git 历史信息（
git log --follow --all -- <文件路径>）追踪该文件的变更
- 如果找到该文件的最新位置，读取文件内容并确认与该链接的关联性
- 如果确信为强相关的文档，更新引用链接为新文件的相对引用路径
- 记录更新日志
- 步骤 5.2.3：关键字检索
- 如果上述步骤均失败，确认该段落内容的必要性
- 如果是文档需要的关键内容，使用关键字检索的方式查找
./codespec 路径
- 如果找到匹配的文件，读取文件内容并确认与该链接的关联性
- 如果确信为强相关的文档，更新引用链接为新文件的相对引用路径
- 记录更新日志
- 步骤 5.2.4：移除非关键内容
- 如果该段落内容不是关键内容
- 移除该链接对应的段落
- 记录删除日志
- 步骤 5.2.5：生成新文档
- 如果该段落内容是关键内容，并且 1-3 步骤均失败
- 通过对项目的分析生成新的文档
- 按照
./codespec 目录规范，将文档放在合适的位置
- 更新引用链接为新文档的相对引用路径
- 记录生成日志
- 步骤 5.3：输出复核报告
- 列出所有检查的引用链接
- 标记每个链接的状态（有效/已更新/已删除/已生成）
- 提供详细的变更日志
- 将状态标记为 "agents_md_completed"
完成批次 2：
manager.complete_batch(2)
if manager.check_timeout_and_pause(timeout_seconds=200):
print("批次 2 超时，请继续 /init 执行批次 3")
return
批次 3：配置更新与专用知识（约 60-90 秒）
启动批次 3（如果批次 2 已完成）：
if not manager.is_batch_completed(2):
print("请先完成批次 2")
return
manager.start_batch(3)
任务：update_gitignore（新增）
-
读取项目根目录的 .gitignore 文件（如果存在）
-
检查并更新以下规则：
规则1：.ai/ 目录忽略
- 检查是否已包含
.ai/ 或 .ai 条目
- 注意：
.ai 和 .ai/ 在 gitignore 中是等效的，表示忽略整个 .ai 目录
- 检查时需要匹配两种形式（有无尾部斜杠）
- 如果不存在，准备添加
规则2：.relay/ 目录白名单
- 检查是否已包含
.relay/ 黑名单规则
- 检查是否已包含
!.relay/RELAY_SKILLS.md 白名单规则
- 白名单模式：先忽略整个
.relay/ 目录，然后仅追踪 RELAY_SKILLS.md
- 如果不存在，准备添加
-
如果规则不存在，按以下顺序添加到 .gitignore 末尾：
# AI 辅助生成文档（本地使用）
.ai/
# Relay project files (whitelist mode)
.relay/
!.relay/RELAY_SKILLS.md
-
写入 .gitignore
-
将状态标记为 "gitignore_updated"
任务：setup_skills_directory（新增）
- 检查项目根目录是否存在
.skills 目录，不存在则创建
- 使用内联模板内容创建 README：
readme_content = """# 项目级 Skills 目录
此目录用于存放项目特定的技能定义。
目录结构
项目级技能遵循以下目录结构：
.skills/
├── skill-name/ # 技能目录
│ ├── SKILL.md # 技能定义文件（必需）
│ ├── scripts/ # Python/shell 脚本（可选）
│ ├── references/ # 参考文档（可选）
│ └── assets/ # 图片、模板等资源（可选）
│ └── config.template.json # 配置模板（可选）
项目链接
关于技能系统的详细说明和最佳实践，请参考 RelayAgent 项目文档：
RelayAgent 项目链接: https://openx.vendor.com/RelayAgent/overview
"""
3. 将模板内容写入 `.skills/README.md`：
```python
write_code_file(".skills/README.md", readme_content)
- 将状态标记为 "skills_directory_setup"
任务：generate_relay_skills_md（全新模式或更新模式）
- 从状态文件加载
project_skills 发现
- 生成 .relay/RELAY_SKILLS.md，包含：
- 项目级专业子智能体（仅限 .skills/ 中的项目特定子智能体，不包含系统级 skills）
- 项目特定工作流
- 任务处理策略
- 子智能体使用指南
- 常见任务到子智能体的映射
- Skills 协作模式
- 写入
.relay/RELAY_SKILLS.md
- 将状态标记为 "completed"
完成批次 3：
manager.complete_batch(3)
if manager.check_timeout_and_pause(timeout_seconds=200):
print("批次 3 超时，请继续 /init 完成初始化")
return
标记整个初始化完成：
manager.mark_completed()
print("所有批次完成！项目初始化成功。")
超时保护机制
每批次完成后自动检查：
if manager.check_timeout_and_pause(timeout_seconds=300):
print(f"当前批次执行超时（>300秒），已保存进度。")
print(f"请再次运行 /init 继续下一个批次。")
print(f"\n批次进度：\n{manager.get_batch_progress()}")
return
恢复执行逻辑：
current_batch = manager.get_current_batch()
if current_batch == 1:
pass
elif current_batch == 2 and manager.is_batch_completed(1):
pass
elif current_batch == 3 and manager.is_batch_completed(2):
pass
else:
print("批次执行顺序错误，请检查状态。")
阶段 3.7：增量模式更新
任务：update_agents_md（增量模式）
- 读取现有
AGENTS.md
- 从状态文件加载聚焦的发现
- 识别要更新或添加的部分：
- 如果关注特定模块 → 添加或扩展相关部分
- 如果发现新架构组件 → 更新"架构指南"
- 将新发现与现有内容合并（保留结构）
- 如果内容超过500行，按照渐进式披露原则精简内容
- 添加更新时间戳和注释
- 将更新内容写入
AGENTS.md
- 复核并更新相对引用链接有效性：
- 扫描 AGENTS.md 中的所有相对引用链接（
[链接文本](./相对路径) 格式）
- 验证每个引用链接的有效性：
- 步骤 1：同名文件检索
- 在项目内检索与引用路径同名的文件（忽略大小写）
- 如果找到对应文件，读取文件内容并确认与该链接的关联性
- 如果确信为强相关的文档，更新引用链接为新文件的相对引用路径
- 记录更新日志
- 步骤 2：Git 历史追踪
- 如果未找到同名文件或找到的文件无强相关性
- 通过 git 历史信息（
git log --follow --all -- <文件路径>）追踪该文件的变更
- 如果找到该文件的最新位置，读取文件内容并确认与该链接的关联性
- 如果确信为强相关的文档，更新引用链接为新文件的相对引用路径
- 记录更新日志
- 步骤 3：关键字检索
- 如果上述步骤均失败，确认该段落内容的必要性
- 如果是文档需要的关键内容，使用关键字检索的方式查找
./codespec 路径
- 如果找到匹配的文件，读取文件内容并确认与该链接的关联性
- 如果确信为强相关的文档，更新引用链接为新文件的相对引用路径
- 记录更新日志
- 步骤 4：移除非关键内容
- 如果该段落内容不是关键内容
- 移除该链接对应的段落
- 记录删除日志
- 步骤 5：生成新文档
- 如果该段落内容是关键内容，并且 1-3 步骤均失败
- 通过对项目的分析生成新的文档
- 按照
./codespec 目录规范，将文档放在合适的位置
- 更新引用链接为新文档的相对引用路径
- 记录生成日志
- 输出复核报告：
- 列出所有检查的引用链接
- 标记每个链接的状态（有效/已更新/已删除/已生成）
- 提供详细的变更日志
- 将状态标记为 "agents_md_completed"
任务：update_relay_skills_md（增量模式）
- 读取现有
.relay/RELAY_SKILLS.md（如果存在）
- 从状态文件加载新的或更新的 skills
- 合并或添加新的 skill 条目
- 更新触发场景映射和工作流
- 保持一致的格式
- 添加注释："更新于 [时间戳]: 添加/更新了 [skill名称]"
- 写入
.relay/RELAY_SKILLS.md
- 将状态标记为 "completed"
增量学习工作流程
当 AGENTS.md 存在且用户提供关注领域时：
-
阶段 0：确定增量模式
- 读取现有 AGENTS.md
- 从 task_description 提取用户关注点（如"身份验证模块"、"CI/CD 流程"）
- 基于关注点创建针对性任务列表
-
阶段 1：针对性分析
- 跳过一般扫描（已记录）
- 聚焦于特定领域：
- 搜索匹配关注关键词的文件
- 读取指定组件的配置
- 分析与主题相关的文档
- 将聚焦的发现保存到状态
-
阶段 2：知识整合
- 识别在 AGENTS.md 中何处添加新信息
- 确定是否需要新部分或应增强现有部分
- 保留现有结构和内容
-
阶段 3：文档更新
- 将聚焦的发现添加到适当的部分
- 保持一致的格式
- 添加注释："更新于 [时间戳]: 添加了 [主题] 文档"
- 如果发现新 skills 或 skills 变化，同步更新 .relay/RELAY_SKILLS.md
-
阶段 4：经验总结捕获（可选）
- 询问用户："在分析过程中，是否遇到过需要多次尝试、手动干预或非显而易见的影响？"
- 如果用户回答"是"，引导用户记录到 guidelines/lessons-learned.md：
- 提供经验总结模板（问题描述、尝试过程、解决方案、相关文件、避免建议）
- 帮助用户填写或整理内容
- 将内容添加到 codespec/guidelines/lessons-learned.md
- 如果 guidelines/lessons-learned.md 不存在，先创建模板
增量任务列表示例：
{
"mode": "supplemental",
"focus": "身份验证模块和数据库架构",
"pending_tasks": [
"locate_auth_module",
"analyze_auth_config",
"scan_database_schema",
"document_auth_flow",
"check_auth_skills",
"update_relay_skills_md"
]
}
增强模式工作流程
当 AGENTS.md 和/或 codespec/ 目录存在且用户未提供关注领域时：
关键前提：此模式用于审视现有知识文件的准确性和完整性，进行修订和补充。
-
阶段 0：确定增强模式和文档目录
-
阶段 1：扫描当前项目结构（更新 findings）
- 对比现有 AGENTS.md 记录与实际项目：
- 扫描关键配置变更：
- 读取主要构建/配置文件（package.json, pom.xml, pyproject.toml 等）
- 对比依赖版本是否更新
- 检查新增的依赖项
- 扫描 src/ 目录结构：
- 识别新增的模块/包
- 检查已删除的模块
- 记录目录结构变化
- 扫描 .skills/ 目录：
- 列出当前所有 skills
- 对比 AGENTS.md 中记录的 skills
- 识别新增或删除的 skills
- 保存更新后的 findings：
state["findings"] = {
"project_type": "...",
"tech_stack": {...},
"directories": {...},
"skills": [...],
"changes": {
"added": [...],
"removed": [...],
"modified": [...]
}
}
-
阶段 2：文档审查（对比现有文档与当前实现）
任务：review_agents_md
- 审查 AGENTS.md 内容：
with open("AGENTS.md", 'r') as f:
content = f.read()
- 检查项目概述：
- 项目类型描述是否准确
- 技术栈版本是否需要更新
- 关键特性是否仍然适用
- 验证目录结构：
- 记录的目录是否仍然存在
- 是否有新增的重要目录未记录
- 已删除的目录是否已更新
- 输出审查报告：
AGENTS.md 审查结果:
✓ 准确的部分: [...]
⚠ 需要更新的部分: [...]
✗ 过时的部分: [...]
➕ 缺失的内容: [...]
任务：review_existing_docs
- 列出现有文档文件：
import os
doc_dir = state["doc_dir"]
existing_docs = []
for root, dirs, files in os.walk(doc_dir):
for file in files:
if file.endswith('.md'):
rel_path = os.path.join(root, file)
existing_docs.append(rel_path)
print(f"现有文档: {len(existing_docs)} 个文件")
- 审查每个文档：
- 读取文档内容
- 检查文档描述的功能/模块是否仍然存在
- 验证代码示例是否仍然有效
- 检查引用的文件路径是否正确
- 标记需要更新的文档：
review_results = {
"accurate": [],
"needs_update": [],
"obsolete": [],
"missing": []
}
- 输出审查清单：
文档目录审查结果:
✓ 准确的文档: {count} 个
⚠ 需要更新的文档: {count} 个
- {文件路径}: {原因}
✗ 过时的文档: {count} 个
- {文件路径}: {原因}
任务：review_relay_skills_md
-
阶段 3：文档更新（更新过时内容，补充缺失内容）
任务：update_agents_md
任务：update_existing_docs
- 遍历需要更新的文档列表：
for doc_path in review_results["needs_update"]:
update_document(doc_path, findings)
- 更新策略：
- 修正过时的代码示例
- 更新引用路径
- 补充遗漏的章节
- 保持文档结构一致性
- 删除过时文档：
for doc_path in review_results["obsolete"]:
os.remove(doc_path)
print(f"✓ 已删除过时文档: {doc_path}")
任务：update_relay_skills_md
-
阶段 4：增量文档生成（只生成缺失的文档）
任务：identify_missing_docs
- 基于 findings 识别缺失的文档：
required_docs = determine_required_docs(findings)
missing_docs = set(required_docs) - set(existing_docs)
print(f"识别到 {len(missing_docs)} 个缺失的文档")
for doc in missing_docs:
print(f" - {doc}")
- 生成文档清单：
state["missing_docs"] = list(missing_docs)
任务：generate_missing_docs
- 生成每个缺失的文档：
for doc in missing_docs:
generate_document(doc, findings, doc_dir)
- 文档生成原则：
- 使用渐进式披露原则
- 保持与现有文档风格一致
- 包含代码示例和最佳实践
- 添加清晰的章节结构
- 保存到检测到的文档目录：
doc_dir = state["doc_dir"]
doc_path = os.path.join(doc_dir, doc_name)
with open(doc_path, 'w') as f:
f.write(content)
任务：update_doc_index
- 更新 AGENTS.md 中的文档索引：
- 验证文档完整性：
-
阶段 5：完成与验证
增强模式任务列表示例：
{
"mode": "enhancement",
"doc_dir": "codespec",
"pending_tasks": [
"detect_doc_directory",
"scan_project_structure",
"review_agents_md",
"review_existing_docs",
"review_relay_skills_md",
"update_agents_md",
"update_existing_docs",
"update_relay_skills_md",
"identify_missing_docs",
"generate_missing_docs",
"update_doc_index"
]
}
状态管理命令
检查现有状态
import json
import os
state_dir = ".relay/init-state"
state_file = os.path.join(state_dir, "state.json")
if os.path.exists(state_file):
with open(state_file, 'r') as f:
state = json.load(f)
print(f"状态: {state['status']}")
print(f"已完成: {state['completed_tasks']}")
print(f"待处理: {state['pending_tasks']}")
else:
print("无现有状态 - 全新开始")
初始化状态
import json
import os
from datetime import datetime
state_dir = ".relay/init-state"
os.makedirs(state_dir, exist_ok=True)
initial_state = {
"version": "1.0",
"status": "in_progress",
"mode": "fresh",
"started_at": datetime.utcnow().isoformat() + "Z",
"last_updated": datetime.utcnow().isoformat() + "Z",
"completed_tasks": [],
"pending_tasks": [
"scan_root_structure",
"analyze_build_files",
"identify_tech_stack",
"scan_src_structure",
"identify_key_modules",
"build_code_index",
"analyze_documentation",
"scan_project_skills",
"update_gitignore",
"setup_skills_directory",
"generate_relay_skills_md"
],
"findings": {},
"analysis_notes": [],
"user_focus": []
}
with open(os.path.join(state_dir, "state.json"), 'w') as f:
json.dump(initial_state, f, indent=2, ensure_ascii=False)
任务完成后更新状态
import json
import os
from datetime import datetime
state_file = ".relay/init-state/state.json"
with open(state_file, 'r') as f:
state = json.load(f)
task = "scan_root_structure"
if task in state["pending_tasks"]:
state["pending_tasks"].remove(task)
state["completed_tasks"].append(task)
state["findings"]["root_structure"] = {
"src/": "源代码",
"tests/": "测试文件"
}
state["last_updated"] = datetime.utcnow().isoformat() + "Z"
with open(state_file, 'w') as f:
json.dump(state, f, indent=2, ensure_ascii=False)
恢复逻辑
被调用时，总是从以下开始：
-
检查现有状态
- 如果
.relay/init-state/state.json 存在，加载它
- 如果状态是 "completed"，询问用户是否要重新生成
- 如果状态是 "in_progress"，从待处理任务继续
-
基于状态重新规划
- 审查已完成的任务和发现
- 识别下一个待处理任务
- 从该点继续工作流程
-
验证发现
- 在生成 AGENTS.md 和 RELAY_SKILL.md 之前，确保所有关键发现都存在
- 如果缺少数据，将验证任务添加到待处理列表
AGENTS.md 模板（渐进式披露模式）
生成项目全局知识文件遵循此结构（参考 RelayAgent/AGENTS.md）：
# {项目名称}
## 项目概述
[1-2段描述项目用途、主要技术栈]
**软件类型**：[应用类型]
## 快速开始
[最快速的上手步骤，不超过 5 步]
### 安装
```bash
# 安装命令
[命令]
运行
[命令]
注意事项
常见陷阱
需要协同修改的操作
- [操作1：列出所有需要修改的文件]
- [操作2：列出所有需要修改的文件]
💡 提示：更多非显而易见的经验和陷阱，请参考 经验总结
核心特性
- [特性1]：[1句话描述]
- [特性2]：[1句话描述]
- [特性3]：[1句话描述]
- [特性4]：[1句话描述]
- [特性5]：[1句话描述]
技术栈
- [技术1]：[1句话描述]
- [技术2]：[1句话描述]
- [技术3]：[1句话描述]
- [技术4]：[1句话描述]
项目结构
[简要说明目录结构，不超过 10 行]
[项目目录]/
├── [子目录]/ # [用途]
├── [子目录]/ # [用途]
└── [文件] # [用途]
文档索引
规范文档
功能规格
经验总结
- 经验总结 - 非显而易见的经验、常见陷阱和需要协同修改的操作
快速链接
## .relay/RELAY_SKILLS.md 模板
生成 Root Agent 专用知识文件遵循此结构（参考 RelayAgent/.relay/RELAY_SKILLS.md）：
```markdown
# Relay 项目知识库
## 项目概述
**类型**：[项目类型]
**技术栈**：
- 后端：[技术列表]
- 前端：[技术列表]
- 测试：[技术列表]
**接口**：
- **[接口1]** (`[命令]`) - [描述]
- **[接口2]** (`[命令]`) - [描述]
## 快速启动
### 安装
请根据项目类型配置相应的环境和依赖：
- Python 项目：配置虚拟环境（`python -m venv .venv`）
- Node.js 项目：安装依赖（`npm install`）
- 其他依赖：参考项目 README 或官方文档
### 运行 [应用名称]
```bash
# [运行方式]
[命令]
核心特性
详细的更新历史请查看 [CHANGELOG.md]
架构指南
[组件] 系统
详见 [相关文档.md]，包括：
核心模式：
[架构描述]
专业子智能体
[项目名称] 系统包含用于特定开发任务的专业子智能体。在执行相关任务时，应主动使用这些智能体。
[子智能体名称]
目的：[目的描述]
何时使用：
位置：[文件路径]
测试基础设施：
使用示例：
[示例]
子智能体使用时机
主动使用（应自动使用这些智能体，无需询问）：
- [场景1] → 使用
[智能体名称] [操作]
- [场景2] → 使用
[智能体名称] [操作]
用户请求使用（当用户明确要求时）：
- [场景] → 使用
[智能体名称]
重要：[重要注意事项]
开发工作流
- [步骤1]：[描述]
- [步骤2]：[描述]
文档索引
设置与配置
用户指南
架构与设计
获取帮助
- 文档：[指引]
- 故障排除：[指引]
## 任务执行指南
1. **高效使用文件操作**
- 使用 `read` 进行针对性文件读取
- 使用 `execute_command` 配合 `ls -la` 进行目录列表
- 使用 `execute_command` 配合 `find` 进行文件发现（限制深度）
2. **频繁保存状态**
- 每完成一个任务后
- 任何长时间运行的操作之前
3. **优雅处理大型项目**
- 目录扫描最多限制3层
- 关注常规目录（src, lib, app, tests 等）
- 跳过大型数据目录（node_modules, .git, venv 等）
4. **提供进度更新**
- 报告已完成的任务
- 显示当前任务
- 估算剩余工作
## 错误处理
- 如果无法读取文件，在 `analysis_notes` 中记录并继续
- 如果任务反复失败，将其标记为 "skipped" 并继续
- 如果缺少关键信息，在 AGENTS.md 中用 "[待办：...]" 标注
- 在抛出错误之前始终保存状态
## 使用示例
**用户请求**："初始化这个项目" 或 "/init"
**代理响应**：
1. 检查 `.relay/init-state/state.json` 中的现有状态
2. 如果是新的：创建初始状态，从阶段1开始
3. 如果正在恢复：加载状态，从下一个待处理任务继续
4. 增量执行任务，每个任务后保存状态
5. 报告完成并提供发现摘要
**用户请求**："学习身份验证模块的工作原理"（已有 AGENTS.md）
**代理响应**：
1. 确定增量学习模式
2. 创建针对性任务列表（查找认证文件、分析配置等）
3. 执行聚焦分析
4. 更新 AGENTS.md，添加或扩展相关部分
5. 报告新增的知识
## 成功标准
成功的初始化包括：
- 有效的状态文件，所有任务已完成
- 生成的 `AGENTS.md` 文件（项目全局知识）
- 生成或更新的 `.relay/RELAY_SKILLS.md` 文件（Root Agent 专用工作流指南）
- 生成的 `codespec/specs/design.md` 文件（系统设计文档）
- AGENTS.md 包含：代码库概述、项目结构、快速开始、核心特性、架构指南、开发工作流、文档索引
- .relay/RELAY_SKILLS.md 包含：项目概述、技术栈、快速启动、核心特性、架构指南、专业子智能体使用指南、开发工作流、文档索引
- codespec/specs/design.md 包含：系统架构概述、核心组件说明、关键设计决策、数据流向
- 文档结构清晰、内容完整
- 所有 Agent（Root Agent 和 Sub-Agents）可以立即使用这些知识开始处理项目任务
## 重要说明
- **状态目录**：`.relay/init-state/`（临时的，完成后可删除）
- **输出文件**：
- `AGENTS.md`（项目全局知识，所有 Agent 加载）
- `.relay/RELAY_SKILLS.md`（Root Agent 专用工作流指南，仅 Root Agent 加载）
- **知识分层**：
- AGENTS.md 被所有 Agent 加载
- RELAY_SKILLS.md 仅被 Root Agent 加载
- **可恢复性**：对大型项目至关重要 - 始终维护有效状态
- **效率**：对于典型项目，在合理次数的文件读取内完成分析
- **指导重点**：生成准确、可操作的知识，帮助 Agent 高效工作
---
## 项目记忆集成（Memory Integration）
项目初始化完成后，应将关键发现持久化到记忆系统。
### 代码结构扫描
**初始化时需要扫描代码结构**：
1. **使用文件系统扫描** 对核心代码目录建立结构认知：
```python
# 扫描核心源代码结构
# 注意：不再使用 index_code，改为文件结构扫描
-
扫描内容：
- 主要模块和包结构
- 文件类型分布（.py, .js, .java等）
- 目录层级关系
-
通过文件定位和搜索：
glob_files("**/*.py", base_dir="src/")
grep_content("class.*Handler", base_dir="src/")
-
优势：
- 无需AST解析，更快响应
- 基于文件结构的直接定位
- 支持多种文件类型
知识记录
使用 record_memory 记录核心发现：
topic="architecture"：项目架构、模块划分、核心模式topic="dependencies"：关键依赖及版本约束topic="conventions"：项目特定的编码规范和命名约定
增量学习完成时
- 新发现记录到对应 topic
- 若发现已有记忆过时，用新内容覆盖（相同 topic）
- 若代码结构变化，重新扫描文件结构更新认知
记录标准
✅ 记录：非显而易见的架构决策、重要模式、踩坑经验
❌ 不记录：显而易见的信息（如"使用 Python"）、已在 AGENTS.md 详细描述的内容
