@mycodemap/mycodemap 0.1.1 → 0.3.4

package/docs/rules/engineering-with-codex-openai.md

@@ -0,0 +1,202 @@
+# 基于 Codex 的工程落地规则
+
+> 目标：把 OpenAI《Engineering with Codex》里的高信号原则，转成当前 CodeMap 仓库可执行的开发与交付规则。
+> 适用范围：本仓库内使用 Codex / Claude / 其他 agent 进行分析、修改、验证、提交流程。
+
+## 1. 先说边界
+
+- 本项目当前主要交付形态是 npm 包与 CLI，不是长期运行的 Web 服务。
+- 因此这里强调的是 `CLI` / `CI` 护栏，而不是 preview 环境或部署沙箱。
+- 涉及长期稳定知识时，优先写入仓库文档与生成物；不要把关键约束留在聊天记录、口头约定或临时笔记里。
+
+## 2. 核心原则
+
+- 人类掌舵，agent 执行：人类负责定义目标、限制、DoD、依赖和验收；agent 负责检索、实现、验证和补文档。
+- 地图优于手册：入口文档保持短小，只做路由；细节下沉到 `ARCHITECTURE.md`、`docs/rules/`、`docs/design-docs/`、`docs/exec-plans/`。
+- 仓库是记录系统：规则、设计权衡、执行计划、生成产物、失败复盘都应进入版本控制。
+- 检索优先于记忆：优先使用 `node dist/cli/index.js query|analyze|deps|impact` 获取事实，再回退到 `rg`、`find`、直接读文件。
+- 规则优先编码：重复出现的评审意见、输出约束、结构边界，优先落为 CLI 子命令、hook、CI 检查或生成契约，而不是停留在 prose。
+
+## 3. 渐进式上下文披露（Harness 规范）
+
+**原则**：不向 AI 提供超过当前任务决策所需的信息，避免注意力稀释。
+
+**上下文层级**（AI 按优先级读取）：
+
+1. **T0-地图层**（始终提供）：架构说明、类型定义、关键约束文件
+   - `AGENTS.md`（仓库级强约束）
+   - `CLAUDE.md`（执行手册）
+   - `src/types/index.ts`（核心类型）
+
+2. **T1-任务相关层**（动态检索）：通过 CodeMap CLI 或文件路径匹配提供
+   - 当前修改文件的依赖图谱（直接上下游）
+   - 相关测试文件（同名 `.test.ts` 或 `.spec.ts`）
+   - 接口定义（如果实现类，提供接口）
+
+3. **T2-按需获取层**（工具调用）：AI 明确请求时才提供
+   - 具体业务逻辑实现细节
+   - 历史提交记录
+   - 第三方库文档
+
+**禁止行为**：不要将整个 `node_modules` 目录或上千行无关代码粘贴给 AI。
+
+## 4. 当前项目的 CLI 护栏
+
+- 仓库内调试与验证优先使用 `node dist/cli/index.js <command>`，因为当前真实 CLI 入口是 `dist/cli/index.js`。
+- 需求澄清、影响分析、引用定位优先走 `query`、`analyze`、`deps`、`impact`，不要直接全仓漫游。
+- 修改 `analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
+  - `--help` 输出与文档示例一致；
+  - 受影响的真实子命令可以在当前仓库运行；
+  - 若涉及机器输出，`--output-mode machine --json` 仍保持纯 JSON 契约。
+- 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
+- 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`。
+- 涉及发布边界时，再补 `npm run build` 与 `npm run validate-pack`；不要把本地临时产物当成发布事实。
+
+## 5. 当前项目的 CI 护栏
+
+- 本地护栏：
+  - `.githooks/pre-commit` 会执行变更相关测试、文件头检查，并尝试生成 AI feed。
+  - 当变更涉及 README、`docs/`、CLI 入口、测试配置或 CI 配置时，`.githooks/pre-commit` 还会执行 `npm run docs:check`。
+  - `.githooks/commit-msg` 会校验 `[TAG] scope: message` 格式与单次 commit 文件数量。
+- 服务端护栏：
+  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，然后再通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
+  - `.github/workflows/publish.yml` 会在发布前执行 `npm test` 与 `npm run build`。
+- 仓库协议仍然禁止通过 `--no-verify`、关闭 hook、放宽阈值、删除检查项来"修复"问题。
+
+## 6. 代码生成红线详细规范（Harness 规范）
+
+AI 生成代码时，以下模式触发**硬性阻断**：
+
+| 红线规则 | 检测方式 | 阻断标准 | 修复策略 |
+|---------|---------|---------|---------|
+| **敏感信息硬编码** | 正则检测 `"password"`, `"secret"`, `"api_key"`, `"token"` 字面量 | 生产代码中出现明文凭证 | 替换为 `process.env.XXX` 读取 + env 类型声明 |
+| **`any` 类型使用** | `tsc --noImplicitAny` + ESLint `@typescript-eslint/no-explicit-any` | 非边界文件使用 `any` | 推导具体类型或使用 `unknown` + 类型守卫 |
+| **函数超过 50 行** | 代码行数统计（不含空行和注释） | 单函数 >50 行 | 拆分为子函数，保持单一职责 |
+| **未处理 Promise** | ESLint `@typescript-eslint/no-floating-promises` | 异步调用无 `await` 或错误处理 | 添加 `await` 或 `.catch()` 处理 |
+| **`console.log` 遗留** | ESLint `no-console` | 非调试代码包含 `console.log` | 使用 `src/cli/runtime-logger.ts` 替代 |
+| **未使用 import** | ESLint `@typescript-eslint/no-unused-vars` | 存在未引用 import | 自动删除或标记为使用 |
+| **缺少文件头** | `.githooks/pre-commit` 检查 | TS 源文件缺少 `[META]` 或 `[WHY]` | 添加标准文件头注释 |
+
+## 7. 依赖流向规则（Harness 规范）
+
+**第一性原理**：业务逻辑必须与实现细节解耦，确保可测试性和技术栈可替换性。
+
+当前项目采用 **MVP3 分层架构**（从上至下依赖）：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                            │
+│  src/cli/ - 命令行接口，注册命令、参数解析、用户交互          │
+├─────────────────────────────────────────────────────────────┤
+│                      Server Layer                           │
+│  src/server/ - HTTP API 服务器，RESTful 端点，Handler 处理    │
+├─────────────────────────────────────────────────────────────┤
+│                       Domain Layer                          │
+│  src/domain/ - 核心业务逻辑，领域实体与服务                   │
+│  - entities/: Project, Module, Symbol, Dependency, CodeGraph │
+│  - services/: CodeGraphBuilder                              │
+│  - events/: DomainEvent                                     │
+│  - repositories/: 仓库接口                                  │
+├─────────────────────────────────────────────────────────────┤
+│                   Infrastructure Layer                      │
+│  src/infrastructure/ - 技术实现细节                          │
+│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage, Neo4jStorage
+│  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
+│  - repositories/: CodeGraphRepositoryImpl                   │
+├─────────────────────────────────────────────────────────────┤
+│                     Interface Layer                         │
+│  src/interface/ - 类型定义与契约，跨层共享的接口              │
+│  - types/: 核心类型定义                                     │
+│  - config/: 配置接口                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**分层依赖规则**（严格自上而下）：
+- CLI → Server → Domain → Infrastructure → Interface
+- **禁止跨层依赖**（如 Domain 层不得导入 CLI 模块）
+- 同层内可以相互依赖
+
+**Enforcement 规则**：
+1. **Domain 层禁止导入**：CLI、Server 层模块
+2. **Infrastructure 层禁止导入**：CLI、Server、Domain 中的具体实现
+3. **Server 层禁止导入**：CLI 层模块
+4. **跨层调用必须通过接口**，依赖 Interface 层契约
+
+**历史架构说明**：
+- MVP3 之前的旧架构（cli→orchestrator→core→parser→generator）已完成迁移
+- 原有 `src/orchestrator/` 部分功能已整合到 Server 层和 CLI 层
+- 原有 `src/core/`、`src/parser/`、`src/generator/` 已迁移到 Domain/Infrastructure 层
+
+**违规检测**：使用 `dependency-cruiser` 或 CodeMap 自身的 `deps` 命令检查跨层依赖。
+
+**违规示例**：
+```typescript
+// ❌ 违规：Domain 层直接依赖 Infrastructure 具体实现
+// src/domain/services/CodeGraphBuilder.ts
+import { FileSystemStorage } from '../infrastructure/storage/FileSystemStorage'; // 错误！
+
+// ✅ 合规：通过 Interface 层契约依赖
+// src/domain/services/CodeGraphBuilder.ts
+import type { IStorage } from '../interface/types/storage'; // 正确：只依赖接口
+```
+
+## 8. 文档与知识落点
+
+- 规则变化：写入 `docs/rules/`
+- 设计权衡：写入 `docs/design-docs/`
+- 执行计划、复盘、技术债：写入 `docs/exec-plans/`
+- 生成物、快照、报告：写入 `docs/generated/`
+- 外部资料摘要：写入 `docs/references/`
+
+如果一次任务无法在 1 天内稳定完成，先拆成更小的执行单元；复杂任务的过程信息不要只留在对话里。
+
+## 9. 失败预演
+
+至少预演一个失败模式，而不是只验证 happy path。当前仓库已经出现过两类高信号风险：
+
+- 文档漂移：例如测试规则曾与真实 `vitest.config.ts` 不一致，导致 agent 按旧规则执行错误命令。
+- 文档检索盲区：当 `analyze documentation` 无法命中文档时，agent 需要立即回退到 `rg` / 直接读文件，并在适用时记录 CodeMap 缺陷，而不是假装"没问题"。
+
+## 10. 最小交付清单（更新版 - Harness 规范）
+
+### 10.1 交付内容
+
+每次 agent 交付至少要说明：
+
+1. **改了什么**：文件清单 + 变更摘要
+2. **为什么改**：需求背景 + 设计决策
+3. **按什么护栏验证**：执行的检查命令和结果
+4. **失败场景或风险模式**：至少一个预演的失败场景
+5. **可信度自评**（见 AGENTS.md 5.1 格式）：确定/推测/需验证/风险
+6. **文档同步说明**：是否更新了相关文档及原因
+
+### 10.2 必须同步文档的触发条件
+
+以下情况**必须**更新对应文档：
+
+| 你的改动 | 必须更新的文档 |
+|---------|--------------|
+| 新增/修改 CLI 命令或参数 | `CLAUDE.md`、`docs/rules/engineering-with-codex-openai.md` |
+| 新增/修改配置项或 Schema | `README.md`、相关配置示例 |
+| 修改类型定义/公共接口 | 接口注释、`docs/rules/` 中相关文档 |
+| 修改 CI/CD 流程 | `docs/rules/validation.md`、`.github/workflows/` |
+| 修改 Git Hooks | `docs/rules/validation.md` |
+| 修改测试规则/覆盖率要求 | `docs/rules/testing.md` |
+| 修改架构分层或依赖规则 | `ARCHITECTURE.md`、`docs/rules/architecture-guardrails.md` |
+| 新增代码质量红线 | `docs/rules/code-quality-redlines.md` |
+| 修改提交格式规范 | `AGENTS.md` |
+| 发现文档与代码不符 | 立即修复对应文档 |
+
+**原则**：若改动会影响其他开发者或 AI 的行为，就必须更新文档。
+
+## 11. 参考来源
+
+- OpenAI Engineering: https://openai.com/engineering/codex/
+- Harness Engineering 方法论：`docs/references/tmp.md`
+- 仓库入口协议：`AGENTS.md`
+- 最小执行手册：`CLAUDE.md`
+- 架构地图：`ARCHITECTURE.md`
+- 当前验证规则：`docs/rules/validation.md`
+- 当前发布规则：`docs/rules/deployment.md`
+- 代码质量红线：`docs/rules/code-quality-redlines.md`
+- 架构护栏：`docs/rules/architecture-guardrails.md`

package/docs/rules/pre-release-checklist.md

@@ -0,0 +1,426 @@
+# 发布前检查清单 (Pre-Release Checklist)
+
+> 本文档定义了每次发布前必须通过的强制护栏规则。
+> 
+> **自动执行**: `npm run docs:check:pre-release`
+> **CI 集成**: 发布工作流会自动运行此检查
+
+---
+
+## 🚨 关键原则
+
+**任何发布都必须满足以下原则：**
+
+1. **AI友好文档完整性** - 所有AI文档必须存在且符合标准
+2. **版本一致性** - 所有文件中的版本号必须一致
+3. **llms.txt 标准** - 必须符合 llmstxt.org 规范
+4. **交叉引用有效性** - 所有内部链接必须有效
+5. **CHANGELOG 同步** - 必须包含当前版本的更新记录
+6. **OIDC 配置** - 使用 Trusted Publishing 方式发布
+
+---
+
+## 📋 检查项详情 (共10项)
+
+### 1. AI 文档完整性检查
+
+**目标**: 确保所有必需的AI文档存在且大小在合理范围内
+
+**检查文件**:
+| 文件 | 必需 | 最小大小 | 最大大小 |
+|------|------|---------|---------|
+| `llms.txt` | ✅ | 100B | 10KB |
+| `AI_GUIDE.md` | ✅ | 1KB | 50KB |
+| `AI_DISCOVERY.md` | ✅ | 1KB | 50KB |
+| `ai-document-index.yaml` | ✅ | 500B | 50KB |
+| `docs/ai-guide/README.md` | ✅ | 500B | 30KB |
+| `docs/ai-guide/QUICKSTART.md` | ✅ | 1KB | 50KB |
+| `docs/ai-guide/COMMANDS.md` | ✅ | 2KB | 100KB |
+| `docs/ai-guide/OUTPUT.md` | ✅ | 2KB | 100KB |
+| `docs/ai-guide/PATTERNS.md` | ✅ | 2KB | 100KB |
+| `docs/ai-guide/PROMPTS.md` | ✅ | 2KB | 100KB |
+| `docs/ai-guide/INTEGRATION.md` | ✅ | 2KB | 150KB |
+
+**限制**:
+- 单个文件最大 150KB
+- 所有AI文档总计最大 500KB
+
+### 2. llms.txt 标准格式检查
+
+**目标**: 确保符合 [llmstxt.org](https://llmstxt.org/) 标准
+
+**必需元素**:
+- [ ] H1 标题 (`# CodeMap`)
+- [ ] 摘要引用 (`> CodeMap 是...`)
+- [ ] 文档章节 (`## 文档` 或 `## Docs`)
+- [ ] 链接格式 (`[Title](./path.md)`)
+
+**推荐元素**:
+- [ ] 快速开始章节
+- [ ] 完整文档章节
+- [ ] 可选章节
+
+**Token 效率**:
+- llms.txt 估算 token 数必须 < 5,000
+
+### 3. 版本一致性检查
+
+**目标**: 确保所有文件中的版本号一致
+
+**检查文件**:
+- `package.json` - `version` 字段
+- `llms.txt` - 文中版本号
+- `ai-document-index.yaml` - `project.version`
+- `AI_GUIDE.md` - 文中版本号
+- `AI_DISCOVERY.md` - 文中版本号 (可选)
+
+**要求**:
+- 所有文件版本号必须完全一致
+- 必须符合语义化版本规范 (`x.x.x`)
+- 预发布版本可包含后缀 (`0.2.0-beta.1`)
+
+**版本同步清单**:
+
+更新版本号时必须同步以下文件:
+- [ ] `package.json` - 主版本号
+- [ ] `llms.txt` - 文中版本声明
+- [ ] `ai-document-index.yaml` - `project.version`
+- [ ] `AI_GUIDE.md` - 页眉版本信息
+- [ ] `AI_DISCOVERY.md` - 页眉版本信息
+- [ ] `CHANGELOG.md` - 版本条目
+
+### 4. 交叉引用有效性检查
+
+**目标**: 确保文档间的引用关系完整
+
+**必需引用**:
+| 源文件 | 必须引用 |
+|--------|---------|
+| `llms.txt` | `AI_GUIDE.md`, `ai-document-index.yaml` |
+| `AI_GUIDE.md` | `AI_DISCOVERY.md`, `ai-document-index.yaml`, `docs/ai-guide/` |
+| `README.md` | `AI_GUIDE.md` |
+| `AGENTS.md` | AI 友好文档规范 |
+| `CLAUDE.md` | `AI_GUIDE.md`, `docs/ai-guide/` |
+
+**链接验证**:
+- 所有内部链接必须指向存在的文件
+- 锚点链接 (`#section`) 会被忽略
+
+### 5. AI 友好性检查
+
+**目标**: 确保 AI_GUIDE.md 符合 AI 阅读最佳实践
+
+**检查项**:
+- [ ] 层级标题 (`##`, `###`)
+- [ ] 表格 (速查表)
+- [ ] 代码块 (bash/typescript/json)
+- [ ] TypeScript 接口定义
+- [ ] 决策树/流程图
+- [ ] 提示词模板
+
+### 6. CHANGELOG 同步检查
+
+**目标**: 确保 CHANGELOG 包含当前版本的更新记录
+
+**要求**:
+- 必须包含当前版本号的条目
+- 推荐包含 AI 文档相关更新记录
+
+**格式示例**:
+```markdown
+## [0.2.0] - 2026-03-17 - MVP3 Architecture Release
+
+### 🐛 Bug Fixes
+- ...
+
+### 📚 Documentation
+- ...
+```
+
+### 7. 发布必需文件检查
+
+**目标**: 确保发布到 NPM/GitHub 所需的文件都存在
+
+**必需文件**:
+| 文件 | 用途 | 状态 |
+|------|------|------|
+| `CHANGELOG.md` | GitHub Release 引用 | 必需 |
+| `LICENSE` | NPM 包许可证 | 必需 |
+| `README.md` | NPM 包主页展示 | 必需 |
+
+### 8. Git Tag 一致性检查
+
+**目标**: 确保版本号与 git tag 一致
+
+**检查项**:
+- [ ] 本地 tag `v{x.x.x}` 是否存在
+- [ ] Tag 是否指向当前 commit
+- [ ] 远程 tag 是否已推送
+- [ ] 当前分支是否为 main/master
+
+**发布流程**:
+
+```bash
+# 方式1: 使用发布脚本（推荐）
+./scripts/release.sh patch   # patch/minor/major
+
+# 方式2: 手动发布
+# 1. 更新版本号
+npm version patch  # 自动创建 tag
+
+# 2. 推送 tag
+git push origin main --tags
+
+# 3. GitHub Actions 自动完成:
+#    - 构建项目
+#    - 运行测试
+#    - 发布到 NPM (通过 OIDC)
+#    - 创建 GitHub Release
+```
+
+**Tag 命名规范**:
+- 格式: `v{x.x.x}` (例如: `v0.2.0`)
+- 必须带有 `v` 前缀
+- 必须符合语义化版本规范
+
+**GitHub Release**:
+- 由 GitHub Actions 自动创建
+- 基于 CHANGELOG.md 生成 release notes
+- 包含预发布版本检测 (版本号包含 `-`)
+
+### 9. OIDC 发布配置检查
+
+**目标**: 确保使用 OIDC Trusted Publishing 方式发布
+
+**配置要求**:
+
+1. **NPM 端配置**:
+   - 访问 `https://www.npmjs.com/package/@mycodemap/mycodemap/access`
+   - 添加 GitHub Actions 作为 Trusted Publisher:
+     - GitHub Organization: `yuanyuanyuan`
+     - GitHub Repository: `mycodemap`
+     - Workflow Name: `publish.yml`
+
+2. **GitHub Secrets 检查**:
+   - [ ] **不应设置** `NPM_TOKEN` secret
+   - [ ] 如果需要 Token 方式，使用 `NPM_TOKEN` 并确保是 **Automation** 类型
+
+3. **Workflow 权限配置**:
+   ```yaml
+   permissions:
+     contents: write  # 用于创建 GitHub Release
+     id-token: write  # 用于 OIDC trusted publishing (必需)
+   ```
+
+4. **发布命令**:
+   ```yaml
+   # 正确：使用 OIDC
+   - name: Publish to NPM
+     run: npm publish --access public --provenance
+   
+   # 错误：设置 NODE_AUTH_TOKEN 会干扰 OIDC
+   # env:
+   #   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+   ```
+
+**验证命令**:
+```bash
+# 检查是否设置了 NPM_TOKEN（OIDC 方式应该为空）
+gh secret list | grep NPM_TOKEN
+
+# 如果存在，删除它
+gh secret remove NPM_TOKEN
+```
+
+### 10. YAML 索引有效性检查
+
+**目标**: 确保 `ai-document-index.yaml` 结构完整
+
+**必需字段**:
+- [ ] `project` 根字段
+- [ ] `project.version` 版本号
+- [ ] `documentation` 文档配置
+- [ ] `documentation.ai_documents` AI文档列表
+- [ ] `cli_commands` 命令索引
+- [ ] `navigation` 导航配置
+
+**引用验证**:
+- YAML 中引用的所有文件路径必须存在
+
+### 11. AGENTS.md 文档规范检查
+
+**目标**: 确保 AGENTS.md 包含 AI 友好文档的强制要求
+
+**必需章节**:
+- [ ] AI 友好文档规范
+- [ ] 结构清晰要求
+- [ ] 决策树要求
+- [ ] 速查表要求
+- [ ] 代码可复现要求
+- [ ] 类型定义要求
+- [ ] 提示词模板要求
+
+---
+
+## 🔧 使用方法
+
+### 本地检查
+
+```bash
+# 运行完整的发布前检查
+npm run docs:check:pre-release
+
+# 查看详细输出
+npm run docs:check:pre-release 2>&1 | less
+```
+
+### CI/CD 集成
+
+发布工作流 (`.github/workflows/publish.yml`) 已自动集成此检查:
+
+```yaml
+- name: Run pre-release AI documentation check
+  run: npm run docs:check:pre-release
+```
+
+### 发布前准备
+
+**推荐方式: 使用发布脚本（一键完成）**
+
+```bash
+# 使用发布脚本（自动处理版本、tag、推送）
+./scripts/release.sh patch    # patch 版本 (0.2.0 -> 0.2.1)
+./scripts/release.sh minor    # minor 版本 (0.2.0 -> 0.3.0)
+./scripts/release.sh major    # major 版本 (0.2.0 -> 1.0.0)
+./scripts/release.sh 0.3.0    # 指定具体版本
+
+# 脚本会自动:
+# 1. 运行 npm run check:all
+# 2. 更新 package.json 版本
+# 3. 创建 git commit
+# 4. 创建 git tag
+# 5. 推送到远程仓库
+# 6. 触发 GitHub Actions 发布 (OIDC)
+```
+
+**手动方式（需要更多控制时）**
+
+```bash
+# 1. 确保工作区干净
+git status
+
+# 2. 运行发布前检查
+npm run docs:check:pre-release
+
+# 3. 构建和测试
+npm run check:all
+
+# 4. 更新版本号（会自动创建 tag）
+npm version patch|minor|major
+
+# 5. 推送代码和 tag
+git push origin main
+git push origin --tags
+
+# 6. GitHub Actions 自动完成发布
+```
+
+---
+
+## ❌ 常见问题
+
+### OIDC 发布失败
+
+**问题**: GitHub Actions 发布失败，提示 403 Forbidden
+
+**解决**:
+1. 检查 NPM 端是否配置了 Trusted Publisher:
+   - 访问 `https://www.npmjs.com/package/@mycodemap/mycodemap/access`
+   - 确认已添加 GitHub Actions 作为 Trusted Publisher
+2. 检查 workflow 权限:
+   - 确保有 `id-token: write`
+3. 检查是否意外设置了 `NPM_TOKEN`:
+   ```bash
+   gh secret list | grep NPM_TOKEN
+   # 如果存在，删除：gh secret remove NPM_TOKEN
+   ```
+4. 检查 workflow 中是否设置了 `NODE_AUTH_TOKEN` 环境变量（不应该设置）
+
+### 版本不一致
+
+**问题**: 多个文件中的版本号不一致
+
+**解决**:
+```bash
+# 统一更新所有文件中的版本号
+VERSION="0.3.0"
+
+# 更新 package.json
+npm version $VERSION --no-git-tag-version
+
+# 手动更新其他文件中的版本号
+# - llms.txt
+# - AI_GUIDE.md
+# - AI_DISCOVERY.md
+# - ai-document-index.yaml
+```
+
+### llms.txt 格式错误
+
+**问题**: llms.txt 不符合标准格式
+
+**解决**:
+参考 [llmstxt.org](https://llmstxt.org/) 规范，确保包含:
+- H1 标题
+- 摘要引用 (blockquote)
+- 文档章节
+
+### CHANGELOG 缺少条目
+
+**问题**: CHANGELOG 缺少当前版本的条目
+
+**解决**:
+```bash
+# 在 CHANGELOG.md 顶部添加条目
+## [x.x.x] - $(date +%Y-%m-%d) - 简短描述
+
+### 🐛 Bug Fixes
+- ...
+
+### ✨ Features
+- ...
+
+### 📚 Documentation
+- ...
+```
+
+---
+
+## 📊 检查脚本架构
+
+```
+scripts/pre-release-check.js
+├── checkRequiredFiles()      # 检查文件存在性和大小
+├── checkLlmsTxtStandards()   # llms.txt 标准格式
+├── checkVersionConsistency() # 版本一致性
+├── checkCrossReferences()    # 交叉引用有效性
+├── checkAIFriendliness()     # AI 友好性
+├── checkChangelogSync()      # CHANGELOG 同步
+├── checkYamlIndex()          # YAML 索引有效性
+├── checkDocumentationStandards() # AGENTS.md 规范
+├── checkReleaseFiles()       # 发布必需文件
+└── checkGitTag()             # Git Tag 一致性
+```
+
+---
+
+## 📝 变更历史
+
+| 日期 | 版本 | 变更 |
+|------|------|------|
+| 2026-03-23 | 0.2.0 | 添加 OIDC Trusted Publishing 配置说明 |
+| 2026-03-22 | 0.2.0 | 初始发布，基于 AI_FRIENDLINESS_AUDIT.md |
+
+---
+
+*此文档是发布流程的强制要求，任何变更都需要同步更新检查脚本。*

package/docs/rules/testing.md

@@ -0,0 +1,73 @@
+# 测试规则
+
+> 测试框架、覆盖率要求、基准测试
+
+---
+
+## 测试框架
+
+| 项目 | 配置 |
+|------|------|
+| 框架 | Vitest |
+| 覆盖率工具 | @vitest/coverage-v8 |
+| 目标覆盖率 | >= 80% |
+
+## 测试文件位置
+
+| 类型 | 路径 |
+|------|------|
+| 常规测试 | `src/**/*.test.ts` |
+| 集成测试 | `tests/` 目录（如存在单独集成测试编排） |
+| 基准测试 | `refer/benchmark-quality.test.ts` |
+
+## 测试配置
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+    exclude: ['node_modules', 'dist', 'refer/**/*.test.ts'],
+    testTimeout: 10000,
+    hookTimeout: 10000,
+    pool: 'threads'
+  }
+});
+```
+
+## 测试要求
+
+- 所有新功能必须附带测试
+- 测试文件命名：`* .test.ts`
+- 使用 `describe` 和 `it` 组织测试用例
+- 使用 `beforeEach`/`afterEach` 管理测试状态
+
+## 基准测试
+
+- 基准查询集：`refer/benchmark-quality.ts`（30 条预定义查询）
+- 基准测试配置：`vitest.benchmark.config.ts`
+- 关键指标：
+  - Token 消耗降低 >= 40%
+  - Hit@8 >= 90%
+
+## 常用命令
+
+```bash
+# 运行所有测试
+npm test
+npx vitest run
+
+# 运行特定测试文件
+npx vitest run src/orchestrator/__tests__/confidence.test.ts
+
+# 运行与变更相关的测试
+npx vitest run --changed
+
+# 运行覆盖率
+npx vitest run --coverage
+
+# 监视模式
+npx vitest watch
+```