@liangjie559567/ultrapower 5.6.6 → 5.6.8

package/docs/reviews/AGENTS.md

@@ -4,17 +4,19 @@
 # docs/reviews/
 
 ## Purpose
+
 代码审查文档目录。存放代码审查报告和审查结果，记录各功能模块的审查意见和改进建议。
 
 ## Subdirectories
 
 | Directory | Purpose |
-|-----------|---------|
+| ----------- | --------- |
 | `ultrapower-standards/` | Ultrapower 规范体系审查报告 |
 
 ## For AI Agents
 
 ### 修改此目录时
-- 审查报告是历史记录，通常不修改
+
+* 审查报告是历史记录，通常不修改
 
 <!-- MANUAL: -->

package/docs/reviews/documentation-system/review_critic.md

@@ -10,61 +10,85 @@
 ## 1. Security Audit (安全审计 - ⚠️ Conditional Pass)
 
 ### 🔴 [P0-CRITICAL] 示例代码泄露敏感信息风险
+
 **问题描述**:
 PRD 要求 "71 skills × 1 示例 = 71 个代码片段"，但未明确禁止在示例中包含：
-- API keys / tokens（如 MCP 配置示例中的 `OPENAI_API_KEY`）
-- 内部路径（如 `C:\Users\ljyih\Desktop\ultrapower`）
-- 真实用户数据（如 session IDs、worktree 路径）
+
+* API keys / tokens（如 MCP 配置示例中的 `OPENAI_API_KEY`）
+
+* 内部路径（如 `C:\Users\ljyih\Desktop\ultrapower`）
+
+* 真实用户数据（如 session IDs、worktree 路径）
 
 **潜在影响**:
-- 用户复制粘贴示例时可能泄露凭证
-- 文档被索引后敏感路径暴露在搜索引擎
+
+* 用户复制粘贴示例时可能泄露凭证
+
+* 文档被索引后敏感路径暴露在搜索引擎
 
 **修复建议**:
 在 **§6.2 文档格式规范** 中新增：
 ```markdown
+
 ### 6.2.4 示例代码安全规范
-- 所有 API keys 使用占位符：`YOUR_API_KEY_HERE`
-- 所有路径使用通用占位符：`/path/to/project`
-- 所有用户数据使用虚构值：`session-abc123`
-- CI 门禁：使用正则表达式扫描常见泄露模式
+
+* 所有 API keys 使用占位符：`YOUR_API_KEY_HERE`
+
+* 所有路径使用通用占位符：`/path/to/project`
+
+* 所有用户数据使用虚构值：`session-abc123`
+
+* CI 门禁：使用正则表达式扫描常见泄露模式
 ```
 
 ---
 
 ### 🟡 [P1-HIGH] 文档权限控制缺失
+
 **问题描述**:
 PRD 未说明文档的访问控制策略：
-- 是否所有文档都公开？
-- 架构设计文档（`architecture/`）是否包含内部实现细节？
-- 是否需要对敏感章节（如安全审查流程）设置访问限制？
+
+* 是否所有文档都公开？
+
+* 架构设计文档（`architecture/`）是否包含内部实现细节？
+
+* 是否需要对敏感章节（如安全审查流程）设置访问限制？
 
 **建议**:
 在 **§6 技术约束** 中新增：
 ```markdown
+
 ### 6.4 访问控制策略
-- 所有文档默认公开（MIT 许可证）
-- 架构文档仅描述公开 API 契约，不暴露内部实现
-- 安全相关文档（如漏洞修复流程）在发布前经过安全团队审查
+
+* 所有文档默认公开（MIT 许可证）
+
+* 架构文档仅描述公开 API 契约，不暴露内部实现
+
+* 安全相关文档（如漏洞修复流程）在发布前经过安全团队审查
 ```
 
 ---
 
 ### ✅ [P2-MEDIUM] 外部链接安全（已部分覆盖）
+
 **现状**:
 PRD 提到 "所有内部链接有效（通过 CI 校验）"，但未提及外部链接的安全性。
 
 **建议**:
 在 CI 门禁中新增外部链接检查：
-- 禁止链接到已知恶意域名
-- 对第三方文档链接添加 `rel="noopener noreferrer"`
-- 定期检查外部链接可用性（避免 404）
+
+* 禁止链接到已知恶意域名
+
+* 对第三方文档链接添加 `rel="noopener noreferrer"`
+
+* 定期检查外部链接可用性（避免 404）
 
 ---
 
 ## 2. Edge Case Analysis (边缘场景分析)
 
 ### 🔴 [P0-CRITICAL] 文档过时检测机制不足
+
 **场景**: 代码重构导致 agent 名称变更（如 `researcher` -> `document-specialist`）
 
 **当前方案的漏洞**:
@@ -75,21 +99,29 @@ PRD 提到 "自定义脚本校验 agent/skill 名称"，但未说明：
 
 **修复建议**:
 ```markdown
+
 ### 5.3.1 名称一致性校验规则
-- 扫描范围：Markdown 正文 + 代码块 + Mermaid 图表
-- 允许废弃别名，但必须标注 `[DEPRECATED]` 并提供替代方案
-- 代码注释中的名称不强制校验（避免误报）
-- 校验脚本：`scripts/validate-doc-names.ts`
+
+* 扫描范围：Markdown 正文 + 代码块 + Mermaid 图表
+
+* 允许废弃别名，但必须标注 `[DEPRECATED]` 并提供替代方案
+
+* 代码注释中的名称不强制校验（避免误报）
+
+* 校验脚本：`scripts/validate-doc-names.ts`
 ```
 
 ---
 
 ### 🟡 [P1-HIGH] 示例代码版本兼容性
+
 **场景**: 用户使用 v5.5.14 运行 v5.5.15 文档中的示例
 
 **潜在问题**:
-- 新版本引入的 API 在旧版本中不存在
-- 示例代码依赖特定的 MCP 服务器配置
+
+* 新版本引入的 API 在旧版本中不存在
+
+* 示例代码依赖特定的 MCP 服务器配置
 
 **建议**:
 在每个示例顶部标注最低版本要求：
@@ -101,6 +133,7 @@ PRD 提到 "自定义脚本校验 agent/skill 名称"，但未说明：
 ---
 
 ### 🟢 [P2-LOW] 多语言环境下的路径问题
+
 **场景**: Windows 用户复制 Unix 风格路径（`/path/to/project`）
 
 **当前方案**: PRD 未明确说明路径示例的跨平台兼容性
@@ -120,45 +153,58 @@ const projectPath = '/Users/user/.omc/state';
 ## 3. Logical Consistency (逻辑一致性)
 
 ### 🔴 [P0-CRITICAL] 目标与验收标准不对齐
+
 **矛盾点 1**: 目标 vs 验收标准的时间承诺
 
 | 维度 | 目标 (§2.1) | 验收标准 (§5.2) | 冲突 |
-|------|------------|----------------|------|
+| ------ | ------------ | ---------------- | ------ |
 | 新用户上手 | "15 分钟跑通第一个示例" | "≤ 15 分钟" | ✅ 一致 |
 | 信息可达性 | "3 次点击内可达任何信息" | "≤ 3 次点击可达" | ✅ 一致 |
 | 示例可用性 | "每个功能模块都有完整示例" | "所有代码示例可直接复制运行（无需修改）" | ⚠️ **不一致** |
 
 **问题**:
 "完整示例" 不等于 "可直接运行"。例如：
-- MCP 工具示例需要用户先配置 API key
-- Team Pipeline 示例需要用户先初始化 git 仓库
+
+* MCP 工具示例需要用户先配置 API key
+
+* Team Pipeline 示例需要用户先初始化 git 仓库
 
 **修复建议**:
 在 §5.2 中明确定义 "可直接运行" 的边界条件：
 ```markdown
+
 ### 5.2.1 示例可运行性定义
-- **Level 1 (无依赖)**: 复制即可运行（如 `/ultrapower:cancel`）
-- **Level 2 (环境依赖)**: 需要完成 getting-started 中的环境配置
-- **Level 3 (外部依赖)**: 需要额外配置（如 MCP API key），文档中必须提供配置步骤链接
+
+* **Level 1 (无依赖)**: 复制即可运行（如 `/ultrapower:cancel`）
+
+* **Level 2 (环境依赖)**: 需要完成 getting-started 中的环境配置
+
+* **Level 3 (外部依赖)**: 需要额外配置（如 MCP API key），文档中必须提供配置步骤链接
 ```
 
 ---
 
 ### 🟡 [P1-HIGH] 里程碑规划与资源投入不匹配
+
 **问题**:
 PRD 规划 4 周完成，但未说明：
-- 谁来编写这 71 个示例？（预计工作量：71 × 30 分钟 = 35.5 小时）
-- 谁来维护 CI 脚本？（预计工作量：链接检查 + 类型检查 + 名称校验 = 16 小时）
-- 谁来审查文档质量？（预计工作量：每个文档 15 分钟审查 = 20 小时）
+
+* 谁来编写这 71 个示例？（预计工作量：71 × 30 分钟 = 35.5 小时）
+
+* 谁来维护 CI 脚本？（预计工作量：链接检查 + 类型检查 + 名称校验 = 16 小时）
+
+* 谁来审查文档质量？（预计工作量：每个文档 15 分钟审查 = 20 小时）
 
 **总工作量估算**: 71.5 小时（约 9 个工作日）
 
 **建议**:
 在 §7 中新增资源分配表：
 ```markdown
+
 ### 7.1 资源分配
+
 | 角色 | 工作量 | 负责模块 |
-|------|--------|---------|
+| ------ | -------- | --------- |
 | Technical Writer | 40h | 编写示例代码 + 场景文档 |
 | DevOps Engineer | 16h | CI 集成 + 自动化脚本 |
 | QA Reviewer | 16h | 文档质量审查 |
@@ -167,6 +213,7 @@ PRD 规划 4 周完成，但未说明：
 ---
 
 ### 🟢 [P2-LOW] 非目标定义不够明确
+
 **问题**:
 "不提供视频教程" 是合理的非目标，但 "不删除 docs/standards/" 不应该是非目标（这是技术约束，不是业务决策）。
 
@@ -178,25 +225,38 @@ PRD 规划 4 周完成，但未说明：
 ## 4. 质量门禁缺陷分析
 
 ### 🟡 [P1-HIGH] CI 门禁覆盖不全
+
 **当前方案** (§5.3):
-- ✅ 链接检查
-- ✅ TypeScript 类型检查
-- ✅ 名称一致性校验
+
+* ✅ 链接检查
+
+* ✅ TypeScript 类型检查
+
+* ✅ 名称一致性校验
 
 **缺失项**:
-- ❌ **Markdown 语法校验**（避免格式错误导致渲染失败）
-- ❌ **代码块语言标注检查**（所有代码块必须标注语言）
-- ❌ **图片 alt 文本检查**（无障碍合规）
-- ❌ **文档长度限制**（单个文档 > 5000 行会影响可读性）
+
+* ❌ **Markdown 语法校验**（避免格式错误导致渲染失败）
+
+* ❌ **代码块语言标注检查**（所有代码块必须标注语言）
+
+* ❌ **图片 alt 文本检查**（无障碍合规）
+
+* ❌ **文档长度限制**（单个文档 > 5000 行会影响可读性）
 
 **建议**:
 在 §6.3 中新增：
 ```markdown
+
 ### 6.3.2 扩展 CI 检查项
-- `markdownlint`: 强制执行 Markdown 格式规范
-- `remark-lint`: 检查代码块语言标注
-- `a11y-checker`: 验证图片 alt 文本
-- `doc-length-limit`: 单文件不超过 3000 行
+
+* `markdownlint`: 强制执行 Markdown 格式规范
+
+* `remark-lint`: 检查代码块语言标注
+
+* `a11y-checker`: 验证图片 alt 文本
+
+* `doc-length-limit`: 单文件不超过 3000 行
 ```
 
 ---
@@ -204,21 +264,27 @@ PRD 规划 4 周完成，但未说明：
 ## 5. 文档过时风险缓解评估
 
 ### 🟢 [PASS] 已有缓解措施
+
 PRD 提出的方案：
 1. ✅ CI 门禁强制校验（§5.3）
 2. ✅ 每个文档标注最后更新日期（§5.4）
 3. ✅ 废弃功能标记 `[DEPRECATED]`（§5.4）
 
 ### 🟡 [P1-HIGH] 建议增强
+
 **问题**: 被动检测（CI 失败后才发现）不如主动预防
 
 **建议**:
 在 §6.3 中新增：
 ```markdown
+
 ### 6.3.3 文档同步自动化
-- Git pre-commit hook: 修改 `src/agents/definitions.ts` 时提示更新文档
-- 每月自动生成 "文档健康度报告"（过时文档列表 + 未覆盖功能）
-- 使用 `@deprecated` JSDoc 标签自动同步到文档
+
+* Git pre-commit hook: 修改 `src/agents/definitions.ts` 时提示更新文档
+
+* 每月自动生成 "文档健康度报告"（过时文档列表 + 未覆盖功能）
+
+* 使用 `@deprecated` JSDoc 标签自动同步到文档
 ```
 
 ---
@@ -226,6 +292,7 @@ PRD 提出的方案：
 ## 6. 逻辑漏洞汇总
 
 ### 🔴 [P0] 循环依赖风险
+
 **场景**: `getting-started/concepts.md` 引用 `features/agents.md`，而 `features/agents.md` 又引用 `getting-started/concepts.md`
 
 **当前方案**: PRD 未提及文档间的依赖关系管理
@@ -247,7 +314,7 @@ Layer 4 (高级): advanced/ + architecture/
 ### 评分矩阵
 
 | 维度 | 得分 | 权重 | 加权得分 |
-|------|------|------|---------|
+| ------ | ------ | ------ | --------- |
 | 安全性 | 6/10 | 30% | 1.8 |
 | 质量保障 | 7/10 | 25% | 1.75 |
 | 逻辑一致性 | 7/10 | 20% | 1.4 |
@@ -266,10 +333,14 @@ Layer 4 (高级): advanced/ + architecture/
 3. **[P0-LOGIC-01]** 在 §5.2 中明确定义 "可直接运行" 的三级分类标准
 
 **可选优化** (P1 问题可在 Phase 2-3 中解决):
-- 文档权限控制策略
-- 示例代码版本兼容性标注
-- 里程碑资源分配表
-- 扩展 CI 检查项（Markdown lint + 无障碍检查）
+
+* 文档权限控制策略
+
+* 示例代码版本兼容性标注
+
+* 里程碑资源分配表
+
+* 扩展 CI 检查项（Markdown lint + 无障碍检查）
 
 ---
 
@@ -298,13 +369,13 @@ Layer 4 (高级): advanced/ + architecture/
 3. 定义示例可运行性三级标准（§5.2.1）
 
 **短期优化** (Phase 2-3):
-4. 新增文档访问控制策略（§6.4）
-5. 新增资源分配表（§7.1）
-6. 扩展 CI 检查项（§6.3.2）
+1. 新增文档访问控制策略（§6.4）
+2. 新增资源分配表（§7.1）
+3. 扩展 CI 检查项（§6.3.2）
 
 **长期改进** (v5.6.0):
-7. 实现文档同步自动化（Git hooks + 健康度报告）
-8. 引入文档依赖层级管理（防止循环引用）
+1. 实现文档同步自动化（Git hooks + 健康度报告）
+2. 引入文档依赖层级管理（防止循环引用）
 
 ---