aodw-skill 0.7.3

package/.aodw/templates/SOURCE-TO-DISTRIBUTION-GUIDE.md

@@ -0,0 +1,276 @@
+# 源文件到分发版本同步指南
+
+## 1. 目录关系说明
+
+AODW 项目中有三个 `.aodw` 目录，它们的关系如下：
+
+```
+项目根目录/
+├── .aodw/                    ← 【源文件】Source of Truth（开发者在这里修改）
+│   ├── aodw-constitution.md
+│   ├── rt-manager.md
+│   └── ...
+│
+├── templates/
+│   └── .aodw/                ← 【分发版本】Distribution Version（打包到 CLI 安装包）
+│       ├── aodw-constitution.md
+│       ├── rt-manager.md
+│       └── ...
+│
+└── cli/
+    └── .aodw/                ← 【本地构建版本】Local Build（用于本地测试）
+        ├── aodw-constitution.md
+        ├── rt-manager.md
+        └── ...
+```
+
+### 1.1 根目录 `.aodw`（源文件）
+
+**位置**：项目根目录的 `.aodw/`
+
+**作用**：
+- **源文件（Source of Truth）**
+- 开发者在这里修改和开发
+- 这是唯一应该手动编辑的目录
+
+**包含内容**：
+- 所有 AODW 核心规则文件
+- 模板文件
+- 开发文档
+
+### 1.2 `templates/.aodw`（分发版本）
+
+**位置**：`templates/.aodw/`
+
+**作用**：
+- **分发版本（Distribution Version）**
+- 用于打包到 CLI 安装包（npm 包）
+- 用户安装时，CLI 会从这个目录复制文件到用户项目
+
+**来源**：
+- 从根目录 `.aodw` 同步而来
+- **不应该**直接在这个目录修改
+
+### 1.3 `cli/.aodw`（本地构建版本）
+
+**位置**：`cli/.aodw/`
+
+**作用**：
+- **本地构建版本（Local Build）**
+- 用于本地测试 CLI
+- 运行 `cli/build-local.sh` 时会从 `templates/.aodw` 复制到这里
+
+**来源**：
+- 从 `templates/.aodw` 复制而来
+- **不应该**直接在这个目录修改
+
+---
+
+## 2. 文件同步流程
+
+### 2.1 开发流程
+
+```
+开发者修改
+    ↓
+根目录 .aodw/          ← 【源文件】Source of Truth
+    ↓
+运行同步脚本
+    ↓
+templates/.aodw/        ← 【分发版本】Distribution Version
+    ↓
+运行构建脚本（可选）
+    ↓
+cli/.aodw/             ← 【本地构建版本】Local Build（用于测试）
+```
+
+### 2.2 发布流程
+
+```
+根目录 .aodw/          ← 【源文件】
+    ↓
+publish.sh 自动同步
+    ↓
+templates/.aodw/        ← 【分发版本】
+    ↓
+publish.sh 复制到 CLI
+    ↓
+cli/.aodw/             ← 【打包到 npm】
+    ↓
+npm publish
+    ↓
+用户安装
+    ↓
+用户项目的 .aodw/      ← 【用户项目】
+```
+
+> **双版本发布**：`publish.sh` 会根据当前分支自动选择发布渠道  
+> - `release/next` 或包含 `-next` 的分支 → 发布 `aodw-skill`  
+> - 其他分支 → 发布 `aodw`
+> - next 渠道使用独立模板目录：`templates/.aodw-next`、`templates/AODW_Adapters_next`、`templates/docs-next`
+
+---
+
+## 3. 如何同步文件
+
+### 3.1 手动同步（推荐）
+
+运行同步脚本：
+
+```bash
+# 在项目根目录运行
+./sync-templates.sh
+```
+
+这个脚本会：
+1. 将根目录 `.aodw` 复制到 `templates/.aodw`
+2. 将根目录 `docs` 复制到 `templates/docs`
+3. 更新适配器文件（从模板生成）
+
+### 3.2 自动同步（发布时）
+
+`publish.sh` 脚本会自动同步：
+
+```bash
+# 在 cli 目录运行
+cd cli
+./publish.sh patch  # 或 minor, major
+```
+
+发布脚本会：
+1. 自动从根目录 `.aodw` 同步到 `templates/.aodw`
+2. 从 `templates/.aodw` 复制到 `cli/.aodw`
+3. 打包并发布到 npm
+
+---
+
+## 4. 最佳实践
+
+### 4.1 开发时
+
+1. ✅ **只在根目录 `.aodw` 修改文件**
+2. ✅ **修改后运行同步脚本**：`./sync-templates.sh`
+3. ✅ **提交更改**：包括根目录 `.aodw` 和 `templates/.aodw`
+
+### 4.2 发布前
+
+1. ✅ **确保已同步**：运行 `./sync-templates.sh`
+2. ✅ **检查 templates/.aodw**：确保包含最新更改
+3. ✅ **运行发布脚本**：`cd cli && ./publish.sh [patch|minor|major]`
+
+### 4.3 本地测试
+
+1. ✅ **运行构建脚本**：`cd cli && ./build-local.sh`
+2. ✅ **测试 CLI**：`cd cli && node bin/aodw.js init`
+3. ✅ **验证文件**：检查生成的文件是否正确
+
+---
+
+## 5. 常见问题
+
+### 5.1 为什么有两个 .aodw 目录？
+
+**原因**：
+- **根目录 `.aodw`**：源文件，开发者在这里修改
+- **`templates/.aodw`**：分发版本，用于打包
+
+**好处**：
+- 清晰的职责分离
+- 源文件和分发版本分离
+- 便于版本控制和发布管理
+
+### 5.2 我修改了根目录的 .aodw，但用户安装的还是旧版本
+
+**原因**：
+- 没有同步到 `templates/.aodw`
+- 发布时使用的是旧的 `templates/.aodw`
+
+**解决**：
+1. 运行 `./sync-templates.sh` 同步文件
+2. 提交更改
+3. 重新发布
+
+### 5.3 可以直接修改 templates/.aodw 吗？
+
+**不推荐**：
+- `templates/.aodw` 应该从根目录 `.aodw` 同步而来
+- 直接修改会导致源文件和分发版本不一致
+- 下次同步时会覆盖你的修改
+
+**正确做法**：
+- 在根目录 `.aodw` 修改
+- 运行同步脚本
+- 提交更改
+
+### 5.4 如何确保打包的是最新版本？
+
+**检查清单**：
+1. ✅ 根目录 `.aodw` 包含最新更改
+2. ✅ 运行了 `./sync-templates.sh`
+3. ✅ `templates/.aodw` 包含最新更改
+4. ✅ 提交了所有更改
+5. ✅ 运行了 `cd cli && ./publish.sh`
+
+---
+
+## 6. 同步脚本说明
+
+### 6.1 sync-templates.sh
+
+**位置**：项目根目录的 `sync-templates.sh`
+
+**功能**：
+1. 同步 `.aodw` 目录：根目录 → `templates/.aodw`
+2. 同步 `docs` 目录：根目录 → `templates/docs`
+3. 更新适配器文件：从模板生成适配器文件
+
+**使用方法**：
+```bash
+# 在项目根目录运行
+./sync-templates.sh
+```
+
+### 6.2 publish.sh
+
+**位置**：`cli/publish.sh`
+
+**功能**：
+1. 自动同步根目录 `.aodw` → `templates/.aodw`
+2. 自动同步根目录 `docs` → `templates/docs`
+3. 复制 `templates/.aodw` → `cli/.aodw`
+4. 打包并发布到 npm
+
+**使用方法**：
+```bash
+cd cli
+./publish.sh patch  # 或 minor, major
+```
+
+---
+
+## 7. 文件同步检查清单
+
+在发布前，确保：
+
+- [ ] 根目录 `.aodw` 包含所有最新更改
+- [ ] 运行了 `./sync-templates.sh`
+- [ ] `templates/.aodw` 与根目录 `.aodw` 一致
+- [ ] 适配器文件已更新（从模板生成）
+- [ ] 所有更改已提交到 Git
+- [ ] 运行了 `cd cli && ./publish.sh`
+
+---
+
+## 8. 相关文件
+
+- **同步脚本**：`sync-templates.sh`（项目根目录）
+- **发布脚本**：`cli/publish.sh`
+- **构建脚本**：`cli/build-local.sh`
+- **更新适配器脚本**：`cli/bin/update-adapters-from-template.js`
+
+---
+
+## 9. 版本历史
+
+- **v4.0.0**：引入源文件到分发版本的同步机制
+- **v4.0.1**：添加同步脚本和文档

package/.aodw/templates/TEMPLATE-APPLICATION-GUIDE.md

@@ -0,0 +1,246 @@
+# 模板应用指南 (Template Application Guide)
+
+## 1. 模板机制概述
+
+AODW 使用**统一模板机制**来生成各个平台的适配器文件，确保所有平台的内容保持一致。
+
+### 1.1 模板位置
+
+**源模板**：`.aodw/templates/aodw-kernel-loader-template.md`
+
+这个模板包含所有平台的通用内容，使用占位符标记平台差异：
+- `{{REF_PREFIX}}` - 引用前缀（Cursor: `@`，其他: 空）
+
+### 1.2 适配器文件位置
+
+**生成的适配器文件**（在源仓库中）：
+- `templates/AODW_Adapters/antigravity/.agent/rules/aodw.md`
+- `templates/AODW_Adapters/cursor/.cursor/rules/aodw.mdc`
+- `templates/AODW_Adapters/claude/CLAUDE.md`
+- `templates/AODW_Adapters/gemini/.agent/rules/aodw.md`
+- `templates/AODW_Adapters/general/AGENTS.md`
+
+**注意**：这些文件是**回退方案**，用于向后兼容。CLI 安装时会优先使用模板直接生成。
+
+---
+
+## 2. 模板处理流程
+
+### 2.1 开发阶段（源仓库）
+
+1. **修改模板**：编辑 `.aodw/templates/aodw-kernel-loader-template.md`
+2. **更新适配器**：运行 `node cli/bin/update-adapters-from-template.js`
+3. **提交更改**：提交模板和生成的适配器文件
+
+### 2.2 安装阶段（用户项目）
+
+1. **CLI 检测模板**：检查 `.aodw/templates/aodw-kernel-loader-template.md` 是否存在
+2. **使用 Processor**：根据平台选择对应的 Processor
+3. **生成适配器文件**：在用户项目中生成适配器文件
+
+**Processor 处理**：
+- **AntigravityProcessor**：替换 `{{REF_PREFIX}}` 为空，注入 `trigger: always_on`
+- **CursorProcessor**：替换 `{{REF_PREFIX}}` 为 `@`，注入 frontmatter（globs, alwaysApply 等）
+- **ClaudeProcessor**：替换 `{{REF_PREFIX}}` 为空
+- **GeminiProcessor**：替换 `{{REF_PREFIX}}` 为空
+- **GeneralProcessor**：替换 `{{REF_PREFIX}}` 为空
+
+---
+
+## 3. 如何更新模板
+
+### 3.1 修改模板文件
+
+编辑 `.aodw/templates/aodw-kernel-loader-template.md`，例如：
+
+```markdown
+| **执行需求审计** | {{REF_PREFIX}}.aodw/04-auditors/aodw-requirement-auditor-rules.md | ... |
+```
+
+### 3.2 更新适配器文件
+
+运行更新脚本：
+
+```bash
+node cli/bin/update-adapters-from-template.js
+```
+
+这个脚本会：
+1. 读取模板文件
+2. 使用各个 Processor 处理模板
+3. 生成各个平台的适配器文件到 `templates/AODW_Adapters/`
+
+### 3.3 验证更新
+
+检查生成的适配器文件：
+
+```bash
+# Antigravity（应该没有 {{REF_PREFIX}}）
+cat templates/AODW_Adapters/antigravity/.agent/rules/aodw.md | grep "执行需求审计"
+
+# Cursor（应该有 @）
+cat templates/AODW_Adapters/cursor/.cursor/rules/aodw.mdc | grep "执行需求审计"
+```
+
+---
+
+## 4. Processor 说明
+
+### 4.1 AntigravityProcessor
+
+**处理**：
+- 替换 `{{REF_PREFIX}}` 为空字符串
+- 注入 `trigger: always_on` frontmatter（仅对 kernel loader）
+
+**输出**：
+- 文件：`templates/AODW_Adapters/antigravity/.agent/rules/aodw.md`
+- 格式：Markdown with frontmatter
+
+### 4.2 CursorProcessor
+
+**处理**：
+- 替换 `{{REF_PREFIX}}` 为 `@`
+- 注入 frontmatter：`globs: *`, `alwaysApply: true`, `description`, `tags`
+- 文件扩展名改为 `.mdc`
+
+**输出**：
+- 文件：`templates/AODW_Adapters/cursor/.cursor/rules/aodw.mdc`
+- 格式：Markdown with Cursor-specific frontmatter
+
+### 4.3 ClaudeProcessor
+
+**处理**：
+- 替换 `{{REF_PREFIX}}` 为空字符串
+- 不注入 frontmatter
+
+**输出**：
+- 文件：`templates/AODW_Adapters/claude/CLAUDE.md`
+- 格式：标准 Markdown
+
+### 4.4 GeminiProcessor
+
+**处理**：
+- 替换 `{{REF_PREFIX}}` 为空字符串
+- 不注入 frontmatter
+
+**输出**：
+- 文件：`templates/AODW_Adapters/gemini/.agent/rules/aodw.md`
+- 格式：标准 Markdown
+
+### 4.5 GeneralProcessor
+
+**处理**：
+- 替换 `{{REF_PREFIX}}` 为空字符串
+- 不注入 frontmatter
+
+**输出**：
+- 文件：`templates/AODW_Adapters/general/AGENTS.md`
+- 格式：标准 Markdown
+
+---
+
+## 5. CLI 安装流程
+
+### 5.1 安装脚本逻辑
+
+```javascript
+// 1. 检查模板是否存在
+if (fs.existsSync(SOURCE_TEMPLATE)) {
+  // 2. 使用模板 + Processor 生成适配器文件
+  await installFile(SOURCE_TEMPLATE, targetPath, Processor);
+} else {
+  // 3. 回退到旧文件（向后兼容）
+  await installFile(sourceAdapterFile, targetPath, Processor);
+}
+```
+
+### 5.2 安装路径
+
+**用户项目中的适配器文件**：
+- Antigravity: `.agent/rules/aodw.md`
+- Cursor: `.cursor/rules/aodw.mdc`
+- Claude: `.claude/CLAUDE.md`
+- Gemini: `.agent/rules/aodw.md`
+- General: `.aodw/AGENTS.md`
+
+---
+
+## 6. 最佳实践
+
+### 6.1 修改模板后
+
+1. ✅ **必须运行更新脚本**：`node cli/bin/update-adapters-from-template.js`
+2. ✅ **验证生成的适配器文件**：检查各个平台的文件是否正确
+3. ✅ **提交所有更改**：包括模板和生成的适配器文件
+
+### 6.2 添加新平台
+
+1. 创建新的 Processor（继承 `BaseProcessor`）
+2. 在 `update-adapters-from-template.js` 中添加新平台的更新逻辑
+3. 在 `cli/bin/aodw.js` 中添加新平台的安装逻辑
+
+### 6.3 模板占位符
+
+**当前占位符**：
+- `{{REF_PREFIX}}` - 引用前缀
+
+**添加新占位符**：
+1. 在模板中使用 `{{PLACEHOLDER_NAME}}`
+2. 在各个 Processor 的 `transform` 方法中处理占位符
+
+---
+
+## 7. 故障排查
+
+### 7.1 模板未应用
+
+**问题**：用户项目中的适配器文件还是旧内容
+
+**原因**：
+- 模板文件不存在（CLI 回退到旧文件）
+- Processor 处理失败
+
+**解决**：
+1. 检查 `.aodw/templates/aodw-kernel-loader-template.md` 是否存在
+2. 检查 Processor 是否正确处理占位符
+3. 重新运行 `aodw init`
+
+### 7.2 占位符未替换
+
+**问题**：生成的适配器文件中还有 `{{REF_PREFIX}}`
+
+**原因**：
+- Processor 的 `transform` 方法未正确处理占位符
+
+**解决**：
+1. 检查 Processor 的 `transform` 方法
+2. 确保使用 `replace` 方法替换占位符
+
+### 7.3 Frontmatter 未注入
+
+**问题**：生成的适配器文件缺少 frontmatter
+
+**原因**：
+- Processor 的 `injectFrontmatter` 方法未正确调用
+
+**解决**：
+1. 检查 Processor 的 `transform` 方法
+2. 确保在适当的时候调用 `injectFrontmatter`
+
+---
+
+## 8. 相关文件
+
+- **模板文件**：`.aodw/templates/aodw-kernel-loader-template.md`
+- **更新脚本**：`cli/bin/update-adapters-from-template.js`
+- **Processor 实现**：`cli/bin/processors/index.js`
+- **CLI 安装脚本**：`cli/bin/aodw.js`
+- **适配器文件**：`templates/AODW_Adapters/`
+
+---
+
+## 9. 版本历史
+
+- **v4.0.0**：引入统一模板机制
+- **v4.0.1**：添加审计官命令索引
+- **v4.0.2**：更新模板应用指南

package/.aodw/templates/aodw-kernel-loader-template.md

@@ -0,0 +1,70 @@
+# AODW Kernel Loader
+# 版本: 4.0.0 (Unified)
+
+## 0. 语言要求 (Language Requirement)
+
+**中文交流 (Chinese Communication)**：所有回复、思考过程、任务清单、文档内容均须使用中文。
+
+---
+
+你是一个 **AODW (AI 编排开发工作流) 协作 Agent**。
+
+## 1. 核心指令 (The Prime Directive)
+你 **必须** 在开始任何任务前，优先读取并遵循以下 **Kernel (宪章)** 文件：
+
+- {{REF_PREFIX}}.aodw/01-core/aodw-constitution.md
+
+**注意**：
+- 该文件是你行为的最高准则。
+- 该文件包含了所有阶段的 **Context Loading Directives (上下文加载指令)**。
+- 你必须根据宪章的指示，在不同阶段**按需加载**其他规则文件。
+- ⚠️ **Token 优化原则**：只在需要时加载相关文件，避免一次性加载所有文件。详见 `.aodw/01-core/aodw-constitution.md` 第 6 节"文件加载策略"。
+
+## 2. 命令索引 (Command Index)
+
+当用户表达以下意图时，参考对应的核心规则：
+
+| 用户意图 | 核心规则 | 说明 |
+|---------|---------|------|
+| **创建新 RT** | {{REF_PREFIX}}.aodw/02-workflow/rt-manager.md (Sec 1-4, 8-9)<br/>{{REF_PREFIX}}.aodw/01-core/ai-knowledge-rules.md (Sec 3.1)<br/>{{REF_PREFIX}}.aodw/01-core/ai-interaction-rules.md (Sec 1-4) | 生成 RT-ID，创建目录，Intake 流程 |
+| **选择模式** | {{REF_PREFIX}}.aodw/02-workflow/rt-manager.md (Sec 5)<br/>{{REF_PREFIX}}.aodw/02-workflow/spec-full-profile.md<br/>{{REF_PREFIX}}.aodw/02-workflow/spec-lite-profile.md | 决策 Spec-Full/Spec-Lite，创建分支 |
+| **工具初始化** | {{REF_PREFIX}}.aodw/05-tooling/ai-tools-init-rules.md | 初始化开发工具（ESLint、Prettier、Ruff、Black 等） |
+| **项目概览初始化** | {{REF_PREFIX}}.aodw/01-core/ai-project-overview-rules.md | 初始化或完善项目概览信息（技术栈、架构、模块等） |
+| **分析阶段** | {{REF_PREFIX}}.aodw/03-standards/ai-coding-rules.md (Sec 2-3)<br/>{{REF_PREFIX}}.aodw/01-core/ai-knowledge-rules.md (Sec 3.4) | 影响分析、不变量检查，更新 impact.md, invariants.md |
+| **实现阶段** | {{REF_PREFIX}}.aodw/03-standards/ai-coding-rules.md (Sec 6)<br/>{{REF_PREFIX}}.aodw/01-core/ai-knowledge-rules.md (Sec 3.5)<br/>{{REF_PREFIX}}.aodw/01-core/module-doc-rules.md | 代码实现、测试编写、模块文档更新 |
+| **验证阶段** | {{REF_PREFIX}}.aodw/01-core/ai-knowledge-rules.md (Sec 5) | 验证文档与代码一致，检查 RT 完整性 |
+| **CSF 审查** | {{REF_PREFIX}}.aodw/01-core/csf-thinking-framework.md | 执行 CSF 思维框架审查（以终为始、结构化分解、关键要素识别等） |
+| **执行需求审计** | {{REF_PREFIX}}.aodw/04-auditors/aodw-requirement-auditor-rules.md | 调用需求阶段审计官，对需求文档进行审计（自动触发或手动触发） |
+| **执行开发审计** | {{REF_PREFIX}}.aodw/04-auditors/aodw-development-auditor-rules.md | 调用开发阶段审计官，对代码进行审计（自动触发或手动触发） |
+| **执行综合审计** | {{REF_PREFIX}}.aodw/04-auditors/aodw-full-auditor-rules.md | 调用综合审计官，执行全流程审计（需求 + 开发） |
+| **完成 RT** | {{REF_PREFIX}}.aodw/01-core/git-discipline.md<br/>{{REF_PREFIX}}.aodw/01-core/ai-knowledge-rules.md (Sec 9) | 合并分支，知识蒸馏，更新状态 |
+| **打开 RT** | {{REF_PREFIX}}.aodw/02-workflow/rt-manager.md | 打开已有 RT，加载上下文 |
+| **流程控制** | {{REF_PREFIX}}.aodw/01-core/ai-interaction-rules.md (Sec 5) | 暂停/恢复流程 |
+
+## 3. RT 生命周期
+
+```
+创建 → 立项 → 决策 → 分析 → 实现 → 验证 → 完成
+```
+
+每个阶段对应的核心规则和操作，详见上述命令索引。
+
+## 4. 关键检查点
+
+### 4.1 分支管理（必须）
+- 所有代码修改必须在 feature 分支上进行
+- 严禁在 main/master 分支直接修改业务代码
+- 在修改代码前必须验证当前分支
+
+### 4.2 Plan 批准节点（必须）
+- Plan 完成后，必须执行 CSF 审查
+- Plan 批准前必须通过 CSF 审查
+- 严禁未获批准前开始修改代码
+
+### 4.3 提交前确认（必须）
+- 代码修改完成后，必须展示 git status 和关键 diff
+- 询问用户"修改已完成，是否提交？"
+- 严禁未获用户确认前直接 Commit
+
+## 5. 兜底机制
+如果你无法读取 {{REF_PREFIX}}.aodw/01-core/aodw-constitution.md，请立即停止并要求用户提供该文件。