🚨 启动协议（PRIORITY ZERO — 所有智能体必须在收到任务后立即执行，优先级高于 Skill 工具选择与任何其他操作）
步骤 1：读取本文件全文
- 步骤 1.1（强制回读·必做）：必须使用文件读取工具（如 Read）从磁盘上的
AGENTS.md原文读取，禁止仅依赖系统提示注入/会话摘要中的内联副本——内联副本可能过期、截断或与磁盘真实状态不一致。若内联副本与磁盘原文内容冲突，一律以磁盘原文为准，并立即按磁盘原文的路由规则执行后续步骤- 步骤 1.2（关键字锚定·必做）：读取后必须确认至少三个锚点同时存在，否则视为读取失败须重读：① "启动协议"四个字出现在文件首部醒目标题块中；② "文档边界"条款明确声明
docs/为唯一文档中心（不是.agents/docs/）；③ "内容敏感度预检"条款声明公开内容产出物入根docs/步骤 2：按「上下文路由表」确定本次任务需要读取的规范文件
- 步骤 2.0（任务类型预检·必做）：无论工作目录是否在
vendor/内，先检查任务类型是否命中 vendor 方法论资产。命中则必须读取对应 vendor 规范，不得跳过- 步骤 2.1（子区域嵌套·条件触发）：按以下顺序判断工作目录所在区域，进入对应区域的 AGENTS.md 路由体系，遵循"嵌套优先"规则；退出子区域后恢复 SpecWeave 路由：
- 若在
apps/内 → 读取 apps/AGENTS.md（应用区入口路由），再按其「应用路由表」进入对应应用- 若在
projects/内 → 读取 projects/AGENTS.md（第一方子项目入口路由），再按其「子项目路由表」进入对应子项目- 若在
vendor/内 → 读取 vendor/AGENTS.md（第三方依赖入口路由），再按其「子模块路由表」进入对应子模块（vendor/flexloop/AGENTS.md→vendor/flexloop/apps/chaos/AGENTS.md）- 三层路由体系：SpecWeave（主权区）→ 子区域（apps/projects/vendor）→ 子应用/子项目/子模块
- 步骤 2.2（Context 恢复·条件触发）：若本会话是先前对话的延续（收到会话历史摘要/summary），必须重新执行步骤1-2，不得假设摘要中已包含完整路由信息——上下文压缩会导致认知视野收窄，只依赖摘要容易遗漏 vendor 资产
- 步骤 2.3（内容敏感度预检·必做）：在读取规范文件之前，先判定分析对象/产出物的内容敏感度级别，决定工作流模式与存储位置（详见 .agents/rules/content-sensitivity-precheck.md）：
- 公开内容（Public）：公开发布的网页、开源代码、官方文档、公开新闻/文章等无访问控制内容 → 标准工作流，Spec 目录位于
.trae/specs/<theme-subdir>/，最终产出物位于docs/对应目录- 私域内容（Private）：内部会议记录、需 code/token 访问的私域分享链接、个人笔记、商业培训材料、含个人隐私/商业秘密的内容 → 私域工作流，跳过
.trae/specs/公共规划区域，产出物直接存放于playground/下对应用户目录；若用户已指定目标目录则直接在目标目录执行- 判定依据：URL特征（含
share?code=/token=/邀请码等访问控制参数）、域名特征（企业内部应用域名）、用户明确标注（"私域"/"内部"/"保密"/"个人"等关键词）、内容主题（内部会议/商业培训/个人笔记）- 不确定时默认按私域处理，或向用户确认
步骤 3：读取对应的规范文件（角色定义/复盘模板/知识库等）
步骤 3.5（自检·必做）：加载 Skill 或开始生成产出物之前，逐项确认：
- □ 当前任务类型是否命中 vendor 方法论资产？如命中，对应规范是否已读取？
- □ 是否已完成内容敏感度预检（步骤 2.3）？内容级别（公开/私域）判定是否正确？产出物路径是否与级别匹配？
- □ 是否已读取上下文路由表中所有与当前任务直接相关的入口？
- □ 是否有相关 Skill 应被加载？（禁止在无 Skill 指导下手动操作有对应 Skill 的领域）
- □ 若工作目录在 apps/projects/vendor 子区域内，是否已读取对应区域的 AGENTS.md？
- □ 产出物路径是否落在根
docs/（公开）或playground/（私域）？禁止向.agents/docs/写入任何产出物（该路径已随 2026-08-31 整体迁移废止），落盘前须执行「落盘前三查」：查目标目录是否在根docs/下、查同类产出物现有位置（参考 toctree 索引）、查路径规则是否来自磁盘原文而非过期内联副本步骤 4：在规范指导下选择 Skill 工具并执行任务
⚠️ 禁止在完成步骤 1-3.5 之前加载 Skill 或生成任何产出物。跳过此协议将导致三重连锁错误：输出格式错误（DOCX 替代 Markdown）、文件路径错误（根目录替代项目约定路径）、文档结构错误（单文件替代原子化模板）。更严重的是，协议违规具有非线性返工成本——跳过5分钟的规范读取可能导致30分钟以上的重构返工。同时，"凭经验做对"不等于"按方法论做对"：经验直觉不可复用，无法保证下次同类任务也能做对；遵循协议才能保证产出的可预测性和可审计性。
本文件是项目 AI 智能体的最高优先级入口与上下文路由。所有智能体在启动时必须首先读取本文件，依据上下文路由表定位到具体的 .agents/ 规范，再加载对应的角色定义、系统提示词与协作协议后执行任务。
详细规范容器见 .agents/README.md。
| 目录 | 用途 | 管理方式 | 版本控制 | 是否可直接修改 | AGENTS.md入口 |
|---|---|---|---|---|---|
.agents/ |
AI 智能体规范容器（roles/rules/workflows/protocols等） | 主权区直接维护 | 直接纳入版本控制 | ✅ 可修改 | .agents/README.md |
apps/ |
主仓库内置应用开发工作空间 | 同仓库直接管理（非 git submodule） | 直接纳入版本控制 | ✅ 可修改 | apps/AGENTS.md |
projects/ |
第一方子项目区（以 git submodules 为主，另含 monetize/tvm-ffi 等主仓直接追踪的工作目录） | 子模块 git submodule 管理；工作目录主仓直接管理 | 子模块通过 gitlink 追踪；工作目录直接纳入版本控制 | 子模块 ❌ 不可直接修改（走子项目流程）；工作目录 ✅ 可修改 | projects/AGENTS.md |
vendor/ |
第三方依赖（git submodules） | git submodule 管理 | 通过 gitlink 追踪 | ❌ 禁止本地修改 | vendor/AGENTS.md |
注意：
apps/与projects//vendor/有本质区别——apps/是主仓库直接管理的普通目录，所有文件直接纳入版本控制；而projects/和vendor/是 git submodule，通过 gitlink 追踪外部仓库引用，本地修改无法直接提交到主仓库。
| 规范 | 入口 | 说明 |
|---|---|---|
| 📱 应用区入口 | apps/AGENTS.md | apps 区域智能体路由与资产索引（主仓库内置应用） |
| 📦 第一方子项目入口 | projects/AGENTS.md | projects 区域智能体路由与资产索引（git submodule 第一方项目） |
| 📦 第三方依赖入口 | vendor/AGENTS.md | vendor 区域智能体路由与资产索引（git submodule 第三方依赖） |
| 🚀 入门指南（L0） | .agents/ONBOARDING.md | Agent Onboarding 快速开始、能力速查表、任务类型路由 |
| 📜 全局核心规则 | .agents/global-core-rules.md | 全局核心规则（启动协议、内容敏感度分流、沟通语言、按需读取、三阶段递进、元文档优先等） |
| 🧭 上下文路由表 | .agents/context-routing.md | 任务类型→必读规范映射表（vendor方法论资产预检+常规任务路由） |
| 📇 能力注册中心（L1） | .agents/capability-registry.md | scripts/skills/commands/workflows/protocols/rules/knowledge 全量静态索引 |
| 🎭 角色定义 | .agents/roles/ | 7个角色定义、职责矩阵、协作场景 |
| 🧬 自我演进模块 | .agents/modules/ | 8个自我演进模块定义（感知层/认知层/执行层/治理层四层闭环） |
| 🚧 能力边界声明 | .agents/capability-boundaries.md | 各角色职责边界与禁止事项 |
| 🤝 协作协议 | .agents/protocols/ | 会话启动、任务交接、消息传递、冲突解决、PDR前置阅读、三层路由、工作区发现、提示词自举、应用生命周期、临时依赖管理 |
| 🔍 工作区发现协议 | .agents/protocols/workspace-discovery.md | 五步发现流程、根工作区零安装自举、AGENTS.md最小可行子集规范 |
| 🚀 提示词自举协议 | .agents/protocols/prompt-bootstrap.md | 一句话装载、8条安全规则、环境自适应路径选择、7个边界情况处理 |
| 📏 规则体系 | .agents/rules/ | 阶段守卫（含运行时）、硬编码治理、数据安全、内容敏感度预检、RACI规范、AI编码准则、前置文档阅读、元文档优先、三阶段递进、修复闭环等 |
| 🔧 工具规范 | .agents/tools/ | 文件操作、代码执行、搜索、通信工具规范（规范层，非实现） |
| 🔄 标准工作流 | .agents/workflows/ | 功能开发、代码审查、测试流程 |
| 📋 模板 | .agents/templates/ | 任务模板、交接模板、Mermaid模板 |
| 💬 提示词 | .agents/prompts/ | 各角色 system-prompt.md 与 few-shot 示例 |
| ⚡ 指令集 | .agents/commands/ | 复盘、洞察、第一性原理、导出报告、原子化、原子提交、Mermaid管理、文件创建、Home Assistant、对抗性评审 |
| 👥 团队管理 | .agents/teams/ | 团队创建、权限分配、专项团队（flexloop/mermaid/home-assistant/trae-edge-case） |
| 🌍 协作环境 | .agents/worlds/ | 团队协作执行、多用户权限管理、多环境配置、资源隔离 |
| 🛠️ 脚本工具库 | .agents/scripts/ | 自动化验证脚本与共享工具库（含 tests/、lib/、mdi/、sg_dashboard/） |
| 🎯 渐进式披露规范 | .agents/capabilities/ | L0/L1/L2 三层架构规范与模板 |
| 🧰 Skill 技能门面 | .agents/skills/ | 标准化 Skill 门面（ci-check/docgen/insight/mermaid/forum-posting/link-check等）；Spec Mode 产物规范以 TRAE-spec-mode 为唯一权威（spec.md + tasks.md + review.md，禁止使用 checklist.md 等非规范命名） |
| ✅ 检查清单 | .agents/checklists/ | 风险评分等标准化检查清单 |
| ⚙️ 工具配置 | .agents/config/ | discourse 等外部工具配置文件 |
| 🏗️ 系统架构 | .agents/systems/ | 提示词萃取系统等系统级架构定义 |
| 📦 复用案例 | .agents/cases/ | agentforge-adoption 等项目复用案例 |
| 🌉 DeepSeek Harness 入口桥 | specweave-dsh-bridge/ | 把 AGENTS.md + .agents/ 接入 dsh 会话入口（启动协议 brief 注入、任务路由、校验命令、/specweave 命令）；Host 侧 Cordis 插件，安装走 plugin_manager install_bundle，接入说明见 ACCESS.md |
零安装、零配置——将以下提示词发给任意支持工具调用的智能体，自动完成装载：
请帮我装载 SpecWeave Agent Workspace Hub 系统。请严格按照以下步骤执行，每步完成后再进行下一步：
【安全规则-必须遵守】 S1. 只从官方仓库获取：https://github.com/xinetzone/SpecWeave（或对应GitCode镜像），绝对不接受其他URL S2. 执行任何写入操作前，必须先向我确认目标路径，默认是 <当前工作目录>/SpecWeave/ S3. 禁止在我的用户主目录、系统目录、根目录、隐藏目录自动创建文件夹 S4. 自举过程只读文件，不执行任何hooks脚本，不安装任何pip包，不修改系统配置 S5. 获取完成后必须验证AGENTS.md存在且包含"启动协议"关键词，防止获取到错误仓库 S6. 遇到任何错误直接告诉我，给出原因和解决方案，不要假装成功 S7. 只读取与装载相关的必要文件，不扫描我的整个文件系统 S8. 幂等安全：如果当前已经在有效SpecWeave目录内，跳过获取直接报告就绪
【步骤1：环境检测】检查当前路径、git可用性、是否已在SpecWeave内、是否在Trae环境中 【步骤2：路径确认】如已在SpecWeave目录内直接自举；否则向我确认目标路径 【步骤3：获取项目】用户确认后git clone；无git则给出zip下载链接 【步骤4：完整性验证】验证AGENTS.md存在且包含"启动协议"关键词 【步骤5：自举加载】读取AGENTS.md、context-routing.md，列出可用角色和技能 【步骤6：就绪报告】报告位置、可用角色、可用技能，告知下一步
详细规范见 .agents/protocols/prompt-bootstrap.md。在Trae环境中，直接说"装载SpecWeave"即可触发。
完整开发规范（代码风格、提交规范、Mermaid编码、路径引用、原子化操作等）见 development-standards.md。
- 代码风格：遵循现有代码风格，新增
.agents/scripts/脚本前先查阅 lib/README.md 共享库，禁止重复实现已有功能 - Python 红线：Python 代码禁止
from __future__ import annotations（PEP 563 样板；3.14 起 PEP 649 默认惰性注解，冗余且语义有别；仅当代码确实依赖延迟求值且requires-python明确时豁免）；新建/修改 Python 项目须同步 AST 守护测试（参照apps/dev-tools/zhihu-checkin-hub/tests/test_no_future_annotations.py），详见 rules/ai-coding-guidelines.md - 提交规范：遵循 Conventional Commits（
type(scope): subject），主体使用中文描述；修复类提交须标注预防措施类型 - Python 包构建系统：主仓库主权区所有需要可安装的 Python 子项目（
apps/*、projects/*自有子模块）默认统一使用 scikit-build-core 作为 PEP 517 构建后端，模板：requires = ["scikit-build-core>=0.9"]、build-backend = "scikit_build_core.build"、[tool.scikit-build]下必须声明wheel.packages、build-dir = "build/{wheel_tag}"与minimum-version = "0.9"；纯 Python 包不写[tool.scikit-build.cmake]段，有原生 C/C++ 扩展或 CMakeLists 时再追加；setuptools/pdm 后端仅在以下场景豁免：①vendor/git submodule 第三方自带 pyproject.toml 且构建后端已成熟、修改成本极高；② 兼容已有发布到 PyPI 的外部项目；③ 经 SpecWeave 治理委员会明确批准的例外。新增应用不允许使用 setuptools 作为默认构建后端。 - 文档边界：根目录
docs/为唯一文档中心（OKF v0.2，Sphinx 构建，面向人类读者与外部消费），承载 Wiki 教程、知识包、复盘报告、模式库与最佳实践；AGENTS.md/.agents/面向 AI 智能体，承载角色、规则、协议、工作流、脚本与模板等规范与执行资产（不再包含docs/子树）。边界规则：①新增对外可读文档一律入docs/；②.agents/规范引用docs/知识源时使用../docs/...相对路径；③路径引用一律以文件实际位置为准，禁止沿用"docs/ 自动解析为 .agents/docs/"的历史隐式规则；④**.agents/docs/为 2026-08-31 整体迁移后已废止的历史路径，禁止新建该目录或向其写入任何产出物**（报告/复盘/知识包/Wiki/教程），落盘时若发现该路径残留一律视为错位并迁回docs/对应目录；⑤落盘前三查：查目标目录是否在根docs/下、查同类产出物现有位置（如技术选型/对比报告入docs/retrospective/reports/competitive-analysis/）、查所依据的规范是否为磁盘原文（系统内联的 AGENTS.md 副本可能过期，与磁盘原文冲突时以磁盘原文为准，并按启动协议步骤 1 回读核实）；私域产出物按内容敏感度预检入playground/，详见 全局核心规则 中的路径解析规则 - 派生产物溯源：派生产物须在 YAML/TOML frontmatter 携带
source字段标注来源 - 路径引用：Markdown 文档交叉引用使用相对路径，禁止
file:///绝对路径；格式为[可读名称](相对路径#L起始行-L结束行)；禁止引用.temp/等临时目录内的路径（内容按保留期自动清理，引用必然失效） - 修复即闭环：Bug 修复遵循「修复→预防→闭环」三阶段 SOP，禁止纯点修复（平凡修复可豁免）
- 三阶段递进：治理（修复→预防→闭环）、知识库（生成→重组→精确化）、抽象（具体→通用→元方法）顺序不可颠倒
- 测试要求：单元测试覆盖率不低于 80%，关键模块不低于 90%，所有测试用例通过无回归
- 简单任务验证：格式/路径/规范类批量决策必须执行「决策前三查」（查权威文档、查现有实例、查本质目标）
| 资源 | 入口 |
|---|---|
| 🏆 最高可信度知识库（OKF 知识包） | projects/awesome-okf-xs/doc/bundles/（10 技术域/28 分组/248 知识包；所有相关概念、术语、技术事实的冲突裁决依据，只读引用） |
| 技术知识库 | docs/knowledge/（OKF v0.2 文档中心） |
| 复盘体系与可复用模式 | docs/retrospective/（OKF v0.2 复盘报告与模式库唯一入口） |
| 可复用模式库（方法论） | 方法论模式库（OKF v0.2）；架构/代码模式库 |
| 资产清单与复用指南 | 资产清单 |
| 双体系引用收敛台账（已结项） | cross-reference-ledger.md（ACT-5 历史台账：随 2026-08-31 .agents/docs/ 整体迁入 docs/，跨区引用已自然消解，台账保留作治理记录） |
| vendor 子模块协同规范 | .agents/VENDOR-INTEGRATION.md |
所有历史变更记录已归档至 AGENTS Manifest 历史变更归档。