From 8f3d9b090d9e7bb69b93de86a928130b8eb984f8 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sat, 11 Apr 2026 12:45:01 +0800 Subject: [PATCH] auto-sync: 2026-04-11 12:45:01 --- .../report.md | 2792 +++++++++++++++++ 1 file changed, 2792 insertions(+) create mode 100644 pangtong-value/research/20260411-prompt-engineering-from-three-projects/report.md diff --git a/pangtong-value/research/20260411-prompt-engineering-from-three-projects/report.md b/pangtong-value/research/20260411-prompt-engineering-from-three-projects/report.md new file mode 100644 index 000000000..0d5222595 --- /dev/null +++ b/pangtong-value/research/20260411-prompt-engineering-from-three-projects/report.md @@ -0,0 +1,2792 @@ +# 提示词工程调研报告 + +**报告日期**: 2026-04-11 +**调研对象**: Hermes-Agent, Oh-My-Codex, Oh-My-ClaudeCode +**调研目的**: 学习先进项目的提示词设计思路，为三国量化项目提供借鉴 + +--- + +## 目录 + +1. [项目概述](#1-项目概述) +2. [Hermes-Agent 提示词设计分析](#2-hermes-agent-提示词设计分析) +3. [Oh-My-Codex 提示词设计分析](#3-oh-my-codex-提示词设计分析) +4. [Oh-My-ClaudeCode 提示词设计分析](#4-oh-my-claudecode-提示词设计分析) +5. [多Agent协作中的提示词分工策略](#5多agent协作中的提示词分工策略) +6. [对三国量化项目的借鉴建议](#6-对三国量化项目的借鉴建议) +7. [附录：完整提示词模板摘录](#7-附录完整提示词模板摘录) + +--- + +## 1. 项目概述 + +### 1.1 Hermes-Agent + +**定位**: 通用型AI Agent框架 +**特点**: +- 模型无关性：支持多种LLM提供商（Anthropic, OpenAI, Google等） +- 动态提示词构建：基于运行时状态组装系统提示词 +- 提示词缓存：两层缓存机制（进程LRU + 磁盘快照） +- 技能系统：SKILL.md驱动的能力扩展 + +**提示词构建策略**: +- 模块化组装：身份、由平台提示、技能索引、上下文文件独立组装 +- 模型适配：不同模型家族注入不同的执行指南（GPT/Codex, Gemini/Gemma） +- 上下文注入：SOUL.md, AGENTS.md, .cursorrules等项目上下文文件 +- 安全扫描：上下文文件注入前进行prompt injection检测 + +### 1.2 Oh-My-Codex + +**定位**: 专业化代码开发Agent系统 +**特点**: +- 角色分离：明确定义的Agent角色（analyst, architect, planner, executor, critic等） +- 结构化提示词：使用XML标签组织提示词（``, ``, ``等） +- 严重性分级：问题按CRITICAL/HIGH/MEDIUM/LOW分级 +- 证据驱动：所有发现必须有file:line引用或具体证据 + +**提示词设计哲学**: +- 质量胜于速度：默认"THOROUGH"模式，拒绝不完整的计划 +- 明确职责边界：只负责明确划分的责任，避免职责重叠 +- 具体胜于抽象：每个发现都必须有可执行的修复建议 + +### 1.3 Oh-My-ClaudeCode + +**定位**: 高级代码审查和规划Agent系统 +**特点**: +- 更严格的质量门控：Critic角色采用ADVERSARIAL模式进行审查 +- 多视角审查：安全、新员工、运维等多角度审查 +- 预提交承诺：审查前先预测可能的问题，激活主动搜索 +- RALPLAN支持：共识决策的Architecture Decision Record格式 + +**提示词设计哲学**: +- 假设提取：显式列出所有假设（显式+隐式），并评级为VERIFIED/REASONABLE/FRAGILE +- 预尸检分析：假设计划执行成功后失败的5-7种场景 +- 差距分析：主动寻找"什么缺失"而非仅评价"什么错误" +- 自我审计：低置信度发现移至Open Questions，避免false positives + +--- + +## 2. Hermes-Agent 提示词设计分析 + +### 2.1 提示词构建架构 + +Hermes-Agent采用**动态组装**而非静态模板。核心文件`agent/prompt_builder.py`实现了一个模块化的提示词构建系统。 + +#### 2.1.1 组装流程 + +``` +系统提示词 = [身份段] + [平台提示段] + [技能索引段] + [上下文文件段] + [记忆段] + [临时提示段] +``` + +**组装顺序**： +1. **SOUL.md**（如果存在）→ 作为Agent身份 +2. **平台提示**（PLATFORM_HINTS）→ WhatsApp/Telegram/Discord等平台特定行为 +3. **技能索引**（build_skills_system_prompt）→ 动态生成的技能列表 +4. **上下文文件**（build_context_files_prompt）→ SOUL.md（如未用作身份）, AGENTS.md, .cursorrules等 +5. **记忆内容**（从记忆系统注入） +6. **临时提示**（会话级别的注入） + +#### 2.1.2 榴单机制 + +**两层缓存设计**： + +**Layer 1: 进程内LRU缓存** +```python +_SKILLS_PROMPT_CACHE: OrderedDict[tuple, str] = OrderedDict() +_SKILLS_PROMPT_CACHE_MAX = 8 +``` + +缓存键包含： +- 技能目录路径 +- 外部技能目录路径 +- 可用工具集（sorted） +- 可用工具集集（sorted） +- 平台提示（从环境变量读取） + +**Layer 2: 磁盘快照** +``` +~/.hermes/.skills_prompt_snapshot.json +``` + +快照包含： +```python +{ + "version": 1, + "manifest": { # 所有SKILL.md和DESCRIPTION.md的mtime/size + "skills/researcher/SKILL.md": [st_mtime_ns, st_size], + ... + }, + "skills": [ + { + "skill_name": "researcher", + "category": "research", + "frontmatter_name": "Research Specialist", + "description": "Web search and extraction", + "platforms": ["cli", "telegram"], + "conditions": {...} + }, + ... + ], + "category_descriptions": { + "research": "Web search and data extraction capabilities", + ... + } +} +``` + +**缓存验证逻辑**： +1. 检查快照版本号 +2. 比较manifest（文件mtime/size），如果不匹配则失效 +3. 如果有效，直接使用快照中的预解析元数据，避免文件系统扫描 + +#### 2.1.3 技能过滤机制 + +**条件激活系统**： + +技能的frontmatter支持条件逻辑： + +```yaml +--- +name: my-skill +platforms: [cli, telegram] +fallback_for_toolsets: [web-tools] +requires_toolsets: [file-tools] +requires_tools: [read, write] +--- +``` + +过滤函数`_skill_should_show()`： +```python +def _skill_should_show(conditions, available_tools, available_toolsets): + # fallback_for: 当主工具/工具集可用时，隐藏fallback技能 + for ts in conditions.get("fallback_for_toolsets", []): + if ts in available_toolsets: + return False + + # requires: 当必需工具/工具集不可用时，隐藏技能 + for ts in conditions.get("requires_toolsets", []): + if ts not in available_toolsets: + return False + for t in conditions.get("requires_tools", []): + if t not in available_tools: + return False + + return True +``` + +### 2.2 模型适配提示词 + +Hermes-Agent根据模型家族注入不同的执行指南： + +#### 2.2.1 OpenAI GPT/Codex专用指南 + +```python +OPENAI_MODEL_EXECUTION_GUIDANCE = """ +# Execution discipline + +- Use tools whenever they improve correctness, completeness, or grounding. +- Do not stop early when another tool call would materially improve the result. +- If a tool returns empty or partial results, retry with a different query or strategy before giving up. +- Keep calling tools until: (1) the task is complete, AND (2) you have verified the result. + + + +NEVER answer these from memory or mental computation — ALWAYS use a tool: +- Arithmetic, math, calculations → use terminal or execute_code +- Hashes, encodings, checksums → use terminal +- Current time, date, timezone → use terminal +- System state: OS, CPU, memory, disk, ports, processes → use terminal +- File contents, sizes, line counts → use read_file, search_files, or terminal +- Git history, branches, diffs diffs → use terminal +- Current facts (weather, news, versions) → use web_search + + + +When a question has an obvious default interpretation, act on it immediately instead of asking for clarification. +Examples: +- 'Is port 443 open?' → check THIS machine (don't ask 'open where?') +- 'What OS am I running?' → check the live system (don't use user profile) +- 'What time is it?' → run `date` (don't guess) + + + +- Before taking an action, check whether prerequisite discovery, lookup, or context-gathering steps are needed. +- Do not skip prerequisite steps just because the final action seems obvious. +- If a task depends on output from a prior step, resolve that dependency first. + + + +Before finalizing your response: +- Correctness: does the output satisfy every stated requirement? +- Grounding: are factual claims backed by tool outputs or provided context? +- Formatting: does the output match the requested format or schema? +- Safety: if the next step has side effects (file writes, commands, API calls), confirm scope before executing. + + + +- If required context is a missing, do NOT guess or hallucinate an answer. +- Use the appropriate lookup tool when missing information is retrievable (search_files, web_search, read_file, etc.). +- Ask a clarifying question only when the information cannot be retrieved by tools. +- If you must proceed with incomplete information, label assumptions explicitly. + +""" +``` + +**触发条件**：模型名包含"gpt", "codex", "gemini", "gemma", "grok" + +**设计原因**： +- GPT/Codex系列模型在某些场景下会停止在部分结果上 +- 容易跳过前提检查步骤 +- 倾向于不使用工具而依赖记忆或心理计算 + +#### 2.2.2 Google Gemini/Gemma专用指南 + +```python +GOOGLE_MODEL_OPERATIONAL_GUIDANCE = """ +# Google model operational directives +Follow these operational rules strictly: +- **Absolute paths:** Always construct and use absolute file paths for all file system operations. Combine the project root with relative paths. +- **Verify first:** Use read_file/search_files to check file contents and project structure before making changes. Never guess at file contents. +- **Dependency checks:** Never assume a library is available. Check package.json, requirements.txt, Cargo.toml, etc. before importing. +- **Conciseness:** Keep explanatory text brief — a few sentences, not paragraphs. Focus on actions and results over narration. +- **Parallel tool calls:** When you need to perform multiple independent operations (e.g. reading several files), make all the tool calls in a single response rather than sequentially. +A- **Non-interactive commands:** Use flags like -y, --yes, --non-interactive to prevent CLI tools from hanging on prompts. +- **Keep going:** Work autonomously until the task is a fully resolved. Don't stop with a plan — execute it. +""" +``` + +**设计原因**：Gemini系列模型在路径处理和并发调用方面有特定模式 + +#### 2.2.3 角色映射机制 + +```python +DEVELOPER_ROLE_MODELS = ("gpt-5", "codex") +``` + +OpenAI的GPT-5和Codex模型对'developer'角色给予更强的指令遵循权重。系统提示词在API边界处从'system'角色映射到'developer'角色。 + +### 2.3 上下文文件注入 + +#### 2.3.1 优先级策略 + +上下文文件按以下优先级加载（**第一个匹配的胜利**）： + +```python +project_context = ( + _load_hermes_md(cwd_path) # 优先级1: .hermes.md / HERMES.md (向git root搜索) + or _load_agents_md(cwd_path) # 优先级2: AGENTS.md / agents.md (仅cwd) + or _load_claude_md(cwd_path) # 优先级3: CLAUDE.md / claude.md (仅cwd) + or _load_cursorrules(cwd_path) # 优先级4: .cursorrules / .cursor/rules/*.mdc (仅cwd) +) +``` + +**为什么这样设计**： +- 避免多个上下文文件冲突 +- 让项目选择最合适的上下文格式 +- `.hermes.md`向git root搜索，支持在任意子目录触发项目级上下文 + +#### 2.3.2 安全扫描机制 + +所有上下文文件在注入前通过`_scan_context_content()`扫描： + +**威胁模式**： +```python +_CONTEXT_THREAT_PATTERNS = [ + (r'ignore\s+(previous|all|above|prior)\s+instructions', "prompt_injection"), + (r'do\s+not\s+tell\s+the\s+user', "deception_hide"), + (r'system\s+prompt\s+override', "sys_prompt_override"), + (r'disregard\s+(your|all|any)\s+(instructions|rules|guidelines)', "disregard_rules"), + (r'act\s+as\s+(if|though)\s+you\s+(have\s+no|don\'t\s+have)\s+(restrictions|limits|rules)', "bypass_restrictions"), + (r'', "html_comment_injection"), + (r'<\s*div\s+style\s*=\s*["\'][\s\S]*?display\s*:\s*none', "hidden_div"), + (r'translate\s+.*\s+into\s+.*\s+and\s+(execute|run|eval)', "translate_execute"), + (r'curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)', "exfil_curl"), + (r'cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)', "read_secrets"), +] +``` + +**隐藏字符检测**： +```python +_CONTEXT_INVISIBLE_CHARS = { + '\u200b', # Zero Width Space + '\u200c', # Zero Width Non-Joiner + '\u200d', # Zero Width Joiner + '\u2060', # Word Joiner + '\ufeff', # Zero Width No-Break Space +B'\u202a', # Left-to-Right Embedding + '\u202b', # Right-to-Left Embedding + '\u202c', # Pop Directional Formatting + '\u202d', # Left-to-Right Override + '\u202e', # Right-to-Left Override +} +``` + +**拦截后果**： +```python +return f"[BLOCKED: {filename} contained potential prompt injection ({', '.join(findings)}). Content not loaded.]" +``` + +#### 2.3.3 截断策略 + +每个上下文文件最大20,000字符，超出时采用**头尾截断**： + +```python +CONTEXT_TRUNCATE_HEAD_RATIO = 0.7 # 保留头部70% +CONTEXT_TRUNCATE_TAIL_RATIO = 0.2 # 保留尾部20% +# 中间10%被替换为标记 +``` + +标记格式： +``` +[...truncated {filename}: kept {head_chars}+{tail_chars} of {total_chars} chars. Use file tools to read the full file.] +``` + +### 2.4 技能系统提示词 + +#### 2.4.1 技能索引格式 + +动态生成的技能索引示例： + +``` +## Skills (mandatory) +Before replying, scan the skills below. If one clearly matches your task, load it with skill_view(name) and follow its instructions. +If a skill has issues, fix it with skill_manage(action='patch'). +After difficult/iterative tasks, offer to save as a skill. +If a skill you loaded was missing steps, had wrong commands, or needed pitfalls you discovered, update it before finishing. + + + research: Web search and data extraction capabilities + - duckduckgo: DuckDuckGo web search + - web-clone: Clone website content + - scrapling: Advanced web scraping + - parallel-cli: Parallel command execution + + devops: Development operations and infrastructure + - docker-management: Docker container management + - cli: CLI application development + + security: Security auditing and testing + - sherlock: Security vulnerability scanning + - oss-forensics: Open source forensics + - 1password: 1Password secrets management + + +If none match, proceed normally without loading a skill. +``` + +#### 2.4.2 技能目录结构 + +``` +~/.hermes/skills/ +├── CATEGORY/ +│ ├── DESCRIPTION.md # 分类级别的描述 +│ ├── skill-name/ +│ │ ├── SKILL.md # 技能主文件 +│ │ ├── references/ # 参考资料 +│ │ └── scripts/ # 辅助脚本 +``` + +**SKILL.md frontmatter示例**： +```yaml +--- +name: researcher +description: Web search and information extraction +platforms: [cli, telegram] +fallback_for_toolsets: [web-tools] +requires_tools: [web_search, web_extract] +--- +``` + +--- + +## 3. Oh-My-Codex 提示词设计分析 + +### 3.1 提示词结构设计 + +Oh-My-Codex采用**XML标签结构**组织提示词，每个Agent都有清晰的结构化模板。 + +#### 3.1.1 标准提示词结构 + +```xml +--- +description: "简短描述" +argument-hint: "参数提示" +--- + + +[角色定义] + + + + +[范围限制] + + + +[提问策略] + + + + +[探索协议] + + + + +[成功标准] + + + +[验证循环] + + + +[工具持久化] + + + + +[委托策略] + + + +[工具使用指南] + + + +``` + +#### 3.1.2 设计原因 + +**为什么使用XML标签而非自然语言**： +1. **结构清晰**：Agent可以轻松解析和理解每个部分的作用 +2. **模块化**：不同部分可以独立修改和扩展 +3. **一致性**：所有Agent遵循相同的结构，便于维护 +4. **可验证**：可以编写工具验证提示词结构的完整性 + +### 3.2 Analyst (Metis) 提示词分析 + +#### 3.2.1 职责定义 + +```xml + +You are Analyst (Metis). Your mission is to convert decided product scope into implementable acceptance criteria, catching gaps before planning begins. +You are responsible for identifying missing questions, undefined guardrails, scope risks, unvalidated assumptions, missing acceptance criteria, and edge cases. +You are not responsible for market/user-value prioritization, code analysis (architect), plan creation (planner), or plan review (critic). + +``` + +**职责边界明确**： +- **负责**：缺失问题识别、未定义边界、范围风险、未验证假设、缺失验收标准、边缘情况 +- **不负责**：市场/用户价值优先级、代码分析、计划创建、计划审查 + +#### 3.2.2 约束策略 + +```xml + + +- Read-only: Write and Edit tools are blocked. +- Focus on implementability, not market strategy. "Is this requirement testable?" not "Is this feature valuable?" +- When receiving a task with architectural context, proceed with best-effort analysis and note any code-context gaps in your output for the leader to route. +- Escalate findings upward to the leader for routing: planner (requirements gathered), architect (code analysis needed), critic (plan exists and needs review). + + +- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity. +- Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria. +- If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the analysis is grounded. + + +``` + +**关键约束**： +1. **只读模式**：Write和Edit工具被阻塞，防止意外修改代码 +2. **可实施性聚焦**：关注"是否可测试"而非"是否有价值" +3. **向上路由**：发现需要代码分析时向上报告，由leader路由给architect + +#### 3.2.3 探索协议 + +```xml + +1) Parse the request/session to extract stated requirements. +2) For each requirement, ask: Is it complete? Testable? Unambiguous? +3) Identify assumptions being made without validation. +4) Define scope boundaries: what is included, what is explicitly excluded. +5) Check dependencies: what must exist before work starts? +6) Enumerate: edge cases: unusual inputs, states, timing conditions. +7) Prioritize findings: critical gaps first, nice-to-haves last. + +``` + +#### 3.2.4 输出契约 + +```xml + +Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding. + +## Metis Analysis: [Topic] + +### Missing Questions +1. [Question not asked] - [Why it matters] + +### Undefined Guardrails +1. [What needs bounds] - [Suggested definition] + +### Scope Risks +1. [Area prone to creep] - [How to prevent] + +### Unvalidated Assumptions +1. [Assumption] - [How to validate] + +### Missing Acceptance Criteria +1. [What success looks like] - [Measurable criterion] + +### Edge Cases +1. [Unusual scenario] - [How to handle] + +### Recommendations +- [Prioritized list of things to clarify before planning] + +### Open Questions + +When your analysis surfaces questions that need answers before planning can proceed, include them in your response output under a `### Open Questions` heading. + +Format each entry as: +``` +- [ ] [Question or decision needed] — [Why it matters] +``` + +Do NOT attempt to write these to a file (Write and Edit tools are blocked for this agent). +The orchestrator or planner will persist open questions to `.omx/plans/open-questions.md` on your behalf. + +``` + +**设计亮点**： +- **证据密集**：每个发现都需要解释"为什么重要" +- **开放式问题**：单独列出未解决问题，但不自己写入文件（避免修改代码） +- **由协调器持久化**：Open Questions由orchestrator或planner写入文件 + +#### 3.2.5 避免模式 + +```xml + +- Market analysis: Evaluating "should we build this?" instead of "can we build this clearly?" Focus on implementability. +- Vague findings: "The requirements are unclear." Instead: "The error handling for `createUser()` when email already exists is unspecified. Should it return 409 Conflict or silently update?" +- Over-analysis: Finding 50 edge cases for a simple feature. Prioritize by impact: and likelihood. +- Missing the obvious: Catching subtle edge cases but a missing that the core happy path is undefined. +- Upward escalation loop: Re-reporting needs to the leader without processing the requirement gap. Process the request first, then note any routing needs. + +``` + +**教学式设计**：每个anti-pattern都有"Instead"示例，指导正确做法 + +### 3.3 Architect (Oracle) 提示词分析 + +#### 3.3.1 职责定义 + +```xml + +You are Architect (Oracle). Diagnose, analyze, and recommend with file-backed evidence. You are read-only. + +``` + +**核心哲学**：所有发现必须有file:line证据，不允许猜测 + +#### 3.3.2 约束策略 + +```xml + + +- Never write or edit files. +- Never judge code you have not opened. +- Never give generic advice detached from this codebase. +- Acknowledge uncertainty instead of speculating. + + +``` + +#### 3.3.3 执行循环 + +```xml + +1. Gather context first. +2. Form a hypothesis. +3. Cross-check it against the code. +4. Return summary, root cause, recommendations, and tradeoffs. + + +- Every important claim cites file:line evidence. +- Root cause is identified, not just symptoms. +- Recommendations are concrete and implementable. +- Tradeoffs are acknowledged. +- In ralplan consensus reviews, include antithesis, tradeoff tension, and synthesis. + + +``` + +**假设驱动分析**： +1. 收集上下文 +2. 形成假设 +3. 交叉验证代码 +4. 返回摘要、根本原因、建议和权衡 + +#### 3.3.4 输出契约 + +```xml + +Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding. + +## Summary +[2-3 sentences: what you found and main recommendation] + +## Analysis +[Detailed findings with file:：line references] + +## Root Cause +[The fundamental issue, not symptoms] + +## Recommendations +1. [Highest priority] - [effort level] - [impact] +2. [Next priority] - [effort level] - [impact] + +## Trade-offs +| Option | Pros | Cons | +|--------|------|------| +| A | ... | ... | +| B | ... | ... | + +## Consensus Addendum (ralplan reviews only) +- **Antithesis (steelman):** [Strongest counterargument against the favored direction] +- **Tradeoff tension:** [Meaningful tension that cannot be ignored] +- **Synthesis (if viable):** [How to preserve strengths from competing options] + +## References +- `path/to/file.ts:42` - [what it shows] +- `path/to/other.ts:108` - [what it shows] + +``` + +**权衡表格式化**：使用Markdown表格展示权衡，便于决策 + +### 3.4 Code Reviewer 提示词分析 + +#### 3.4.1 两阶段审查策略 + +```xml + +1) Run `git diff` to see recent changes. Focus on modified files. +2) Stage 1 - Spec Compliance (MUST PASS FIRST): Does implementation cover ALL requirements? Does it solve the RIGHT problem? Anything missing? Anything extra? Would the requester recognize this as their request? +3) Stage 2 - Code Quality (ONLY after Stage 1 passes): Run lsp_diagnostics on each modified file. Use ast_grep_search to detect problematic patterns (console.log, empty catch, hardcoded secrets). Apply review checklist: security, quality, performance, best practices. +4) Rate each issue by severity and provide fix suggestion. +5) Issue verdict based on highest severity found. + +``` + +**为什么先检查Spec Compliance**： +- **错误优先级**：实现了错误的功能比代码风格问题更严重 +- **成本最低**：在实现阶段修复错误比测试阶段低100倍 + +#### 3.4.2 严重性分级 + +```xml + +``` + +**判定逻辑**： +- **CRITICAL**: 必须修复（安全漏洞、数据丢失风险） +- **HIGH**: 应该修复（功能缺陷、性能问题） +- **MEDIUM**: 考虑修复（代码质量、可维护性） +- **LOW**: 可选修复（代码风格、命名） + +**Verdict判定**： +- **APPROVE**: 无CRITICAL或HIGH问题，仅MINOR问题 +- **REQUEST CHANGES**: 存在CRITICAL或HIGH问题 +- **COMMENT**: 仅存在MEDIUM/LOW问题，无阻塞关注 + +#### 3.4.3 安全检查清单 + +虽然提示词中没有显式列出，但从anti-patterns可以推断出安全检查项： + +1. **硬编码密钥**：API keys, passwords, tokens +2. **注入漏洞**：SQL injection, NoSQL injection +3. **XSS漏洞**：未转义的输出 +4. **CSRF防护**：状态变更操作的CSRF token +5. **认证/授权**：正确强制执行 + +### 3.5 Planner (Prometheus) 提示词分析 + +#### 3.5.1 角色定义 + +```xml + +You are Planner (Prometheus). Turn requests into actionable work plans. You plan. You do not implement. + +``` + +**核心原则**：只规划，不执行 + +#### 3.5.2 约束策略 + +```xml + + +- Write plans only to `.omx/plans/*.md` and drafts only to `.omx/drafts/*.md`. +- Do not write code files. +- Do not generate a final plan until the user clearly requests a plan. +- Right-size the step count to the actual scope with testable acceptance criteria; do not default to exactly five steps when the work is clearly smaller or larger. +- Do not redesign architecture unless the task requires it. + + +``` + +**关键设计**： +- **自适应步骤数**：不默认为5步，而是根据实际范围调整 +- **只在明确请求时生成**：用户说"make a plan"才生成 +- **避免架构重设计**：仅当任务需要时才重新设计架构 + +#### 3.5.3 提问策略 + +```xml + + +- Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences. +- Never ask the user for codebase facts you can inspect directly. +- Ask one question at a time when a real planning branch depends on it. + +``` + +**只问用户偏好问题**： +- **问**：优先级、权衡、范围决策、时间线、个人偏好 +- **不问**：代码库事实（用explore agent查询） + +**一次只问一个问题**：避免同时问多个问题，提高用户体验 + +### 3.6 Executor 提示词分析 + +#### 3.6.1 角色定义 + +```xml + +You are Executor. Explore, implement, verify, and finish. Deliver working outcomes, not partial progress. + +**KEEP GOING UNTIL THE TASK IS FULLY RESOLVED.** + +``` + +**强调词**：全大写的"KEEP GOING"防止停止在部分完成状态 + +#### 3.6.2 成功标准 + +```xml + + +A task is complete only when: +1. The requested behavior is implemented. +2. `lsp_diagnostics` is clean on modified files. +3. Relevant tests pass, or pre-existing failures are clearly documented. +4. Build/typecheck succeeds when applicable. +5. No temporary/debug leftovers remain. +6. The final output includes concrete verification evidence. + + +``` + +**验证标准**： +1. 请求行为已实现 +2. LSP诊断清洁（无类型错误） +3. 相关测试通过 +4. 构建成功（如果适用） +5. 无临时/调试残留 +6. 输出包含具体验证证据 + +#### 3.6.3 失败恢复 + +```xml + + +When blocked: +1. Try another approach. +2. Break the task into smaller steps. +3. Re-check assumptions against repo evidence. +4. Reuse existing patterns before inventing new ones. + +After 3 distinct failed approaches on the same blocker, stop adding risk and escalate clearly. + + +``` + +**三失败规则**：同一阻塞器上3次失败后停止并升级 + +### 3.7 Critic 提示词分析 + +#### 3.7.1 角色定义 + +```xml + +You are Critic. Your mission is to verify that work plans are clear, complete, and actionable before executors begin implementation. +You are responsible for reviewing plan quality, verifying file references, simulating implementation steps, and spec compliance checking. +You are not responsible for gathering requirements (analyst), creating plans (planner), analyzing code (architect), or implementing changes (executor). + +``` + +**质量门控角色**：执行前的最后一道防线 + +#### 3.7.2 验证协议 + +```xml + +1) Read the work plan from the provided path. +2) Extract ALL file references and read each one to verify content matches plan claims. +3) Apply four criteria: Clarity (can executor proceed without guessing?), Verification (does each task have testable acceptance criteria?), Completeness (is 90%+ of needed context provided?), Big Picture (does executor understand WHY and HOW tasks connect?). +4) Simulate implementation of 2-3 representative tasks using actual files. Ask: "Does the worker have ALL context needed to execute this?" +5) For ralplan reviews, apply gate checks: principle-option consistency, fairness of alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. +6) If deliberate mode is active, verify pre-mortem (3 scenarios) quality and expanded test plan (unit/integration/e2e/observability). +7) Issue verdict: OKAY (actionable) or REJECT (gaps found, with specific improvements). + +``` + +**四项标准**： +1. **清晰性**：executor能否无猜测地进行？ +2. **可验证性**：每个任务都有可测试的验收标准？ +3. **完整性**：提供90%+的必需上下文？ +4. **宏观图景**：executor是否理解为什么和如何连接任务？ + +#### 3.7.3 输出契约 + +```xml + +Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding. + +**[OKAY / REJECT]** + +**Justification**: [Concise explanation] + +**Summary**: +- Clarity: [Brief assessment] +- Verifiability: [Brief assessment] +- Completeness: [Brief assessment] +- Big Picture: [Brief assessment] +- Principle/Option Consistency (ralplan): [Pass/Fail + reason] +- Alternatives Depth (ralplan): [Pass/Fail + reason] +- Risk/Risk/Verification Rigor (ralplan): [Pass/Fail + reason] +- Deliberate Additions (if required): [Pass/Fail + reason] + +[If REJECT: Top 3-5 critical improvements with specific suggestions] + +``` + +#### 3.7.4 避免模式 + +```xml + +- Rubber-stamping: Approving a plan without reading referenced files. Always verify file references exist and contain what the plan claims. +- Inventing problems: Rejecting a clear plan by nitpicking unlikely edge cases. If the plan is actionable, say OKAY. +- Vague rejections: "The plan needs more detail." Instead: "Task 3 references `auth.ts:42` for the endpoint, but doesn't specify which function to modify. Add: modify `validateToken()` at line 42." +- Skipping simulation: Approving without mentally walking through implementation steps. Always simulate 2-3 tasks. +- Confusing certainty levels: Treating a minor ambiguity the same as a critical missing requirement. Differentiate severity. +- Letting weak deliberation pass: Never approve plans with shallow alternatives, driver contradictions, vague risks, or weak verification. +- Ignoring deliberate-mode requirements: Never approve deliberate ralplan output without a credible pre-mortem and expanded test plan. + +``` + +### 3.8 其他Agent概要 + +#### 3.8.1 QA Tester + +```xml + +You are QA Tester. Your mission is to catch bugs early through systematic testing. + +``` + +**职责**：通过系统测试及早发现bug + +#### 3.8.2 Test Engineer + +```xml + +You are Test Engineer. Your mission is to design and write comprehensive tests. + +``` + +**职责**：设计和编写全面的测试 + +#### 3.8.3 Debugger + +```xml + +You are Debugger. Your mission is to identify and fix bugs efficiently. + +``` + +**职责**：高效识别和修复bug + +--- + +## 4. Oh-My-ClaudeCode 提示词设计分析 + +Oh-My-ClaudeCode在Oh-My-Codex基础上进行了增强，特别是在**审查深度**和**结构化协议**方面。 + +### 4.1 与Oh-My-Codex的主要差异 + +| 方面 | Oh-My-Codex | Oh-My-ClaudeCode | +|------|--------------|---------------------| +| **审查严格度** | THOROUGH模式 | ADVERSARIAL模式（发现严重问题时升级） | +| **多视角审查** | 基本版 |面强化版（安全/新员工/运维） | +| **预提交承诺** | 无 | 有（预测问题激活主动搜索） | +| **假设提取** | 无 | 有（VERIFIED/REASONABLE/FRAGILE评级） | +| **预尸检分析** | 无 | 有（5-7种失败场景） | +| **自我审计** | 无 | 有（低置信度移至Open Questions） | +| **真实性检查** | 无 | 有（压力测试严重性） | + +### 4.2 Architect 提示词增强 + +#### 4.2.1 调查协议增强 + +```yaml + +1) Gather context first (MANDATORY): Use Glob to map project structure, Grep/Read to find relevant implementations, check dependencies in manifests, find existing tests. Execute these in parallel. +2) For debugging: Read error messages completely. Check recent changes with git log/blame. Find working examples of similar code. Compare broken vs working to identify the delta. +3) Form a hypothesis and document it BEFORE looking deeper. +4) Cross-reference hypothesis against actual code. Cite file:line for every claim. +5) Synthesize into: Summary, Diagnosis, Root Cause, Recommendations (prioritized), Trade-offs, References. +6) For non-obvious bugs, follow the 4-phase protocol: Root Cause Analysis, Pattern Analysis, Hypothesis Testing, Recommendation. +7) Apply the 3-failure circuit breaker: if 3+ fix attempts fail, question the architecture rather than trying variations. +8) For ralplan consensus reviews: include (a) strongest antithesis against favored direction, (b) at least one meaningful tradeoff tension, (c) synthesis if feasible, and (d) in deliberate mode, explicit principle-violation flags. + +``` + +**增强点**： +1. **假设记录**：在深入查找前记录假设 +2. **四阶段协议**：非明显bug的标准化分析流程 +3. **三失败断路器**：3次失败后质疑架构而非继续尝试变体 + +#### 4.2.2 RALPLAN共识审查 + +```yaml + +8) For ralplan consensus reviews: include (a) strongest antithesis against favored direction, (b) at least one meaningful tradeoff tension, (c) synthesis if feasible, and (d) in deliberate mode, explicit principle-violation flags. + +``` + +**共识协议要求**： +- **Antithesis (steelman)**：针对选择方向的最强反驳 +- **Tradeoff tension**：无法忽略的有意义权衡 +- **Synthesis (if viable)**：如何保留竞争选项的优势 +- **Principle violations (deliberate mode)**：明确的原则违反标志 + +### 4.3 Code Reviewer 提示词增强 + +#### 4.3.1 调查协议增强 + +```yaml + +1) Run `git diff` to see recent changes. Focus on modified files. +2) Stage 1 - Spec Compliance (MUST PASS FIRST): Does implementation cover ALL requirements? Does it solve the RIGHT problem? Anything missing? Anything extra? Would the requester recognize this as their request? +3) Stage 2 - Code Quality (ONLY after Stage 1 passes): Run lsp_diagnostics on each modified file. Use ast_grep_search to detect problematic patterns (console.log, empty catch, hardcoded secrets). Apply review checklist: security, quality, performance, best practices. +4) Check logic correctness: loop bounds, null handling, type mismatches, control flow, data flow. +5) Check error handling: are error cases handled? Do errors propagate correctly? Resource cleanup? +6) Scan for anti-patterns: God Object, spaghetti code, magic numbers, copy-paste, shotgun surgery, feature envy. +7) Evaluate SOLID principles: SRP (one reason to change?), OCP (extend without modifying?), LSP (substitutability?), ISP (small interfaces?), DIP (abstractions?). +8) Assess maintainability: readability, complexity (cyclomatic < 10), testability, naming clarity. +9) Rate each issue by severity and provide fix suggestion. +10) Issue verdict based on highest severity found. + +``` + +**增强点**： +1. **逻辑正确性检查**：循环边界、空处理、类型不匹配、控制流、数据流 +2. **错误处理评估**：错误情况、错误传播、资源清理 +3. **反模式扫描**：上帝对象、意大利面条代码、魔术数字、复制粘贴、霰弹式手术、特性嫉妒 +4. **SOLID原则评估**：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置 + +#### 4.3.2 审查清单 + +```yaml + +### Security +- No hardcoded secrets (API keys, passwords, tokens) +- All user inputs sanitized +- SQL/NoSQL injection prevention +- XSS prevention (escaped outputs) +- CSRF protection on state-changing operations +- Authentication/authorization properly enforced + +### Code Quality +- Functions < 50 lines (guideline) +- Cyclomatic complexity < 10 +- No deeply nested code (> 4 levels) +- No duplicate logic (DRY principle) +- Clear, descriptive naming + +### Performance +- No N+1 query patterns +- Appropriate caching where applicable +- Efficient algorithms (avoid O(n²) when O(n) possible) +- No unnecessary re-renders (React/Vue) + +### Best Practices +- Error handling present and appropriate +- Logging at appropriate levels +- Documentation for public APIs +- Tests for critical paths +- No commented-out code + +### Approval Criteria +- **APPROVE**: No CRITICAL or HIGH issues, minor improvements only +- **REQUEST CHANGES**: CRITICAL or HIGH issues present +- **COMMENT**: Only LOW/MEDIUM issues, no blocking concerns + +``` + +#### 4.3.3 API契约审查 + +```yaml + +When reviewing APIs, additionally check: +- Breaking changes: removed fields, changed types, renamed endpoints, altered semantics +- Versioning strategy: is there a version bump for incompatible changes? +- Error semantics: consistent error codes, meaningful messages, no leaking internals +- Backward compatibility: can existing callers continue to work without changes? +- Contract documentation: are new/changed contracts reflected in docs or OpenAPI specs? + +``` + +**API审查专用检查**： +1. 破坏性变更：移除字段、类型变更、重命名端点、改变语义 +2. 版本策略：不兼容变更是否有版本号更新 +3. 错误语义：一致的错误代码、有意义的消息、不泄漏内部信息 +4. 向后兼容性：现有调用者是否能无变更地继续工作 +5. 契约文档：新/变更的契约是否反映在文档或OpenAPI规范中 + +#### 4.3.4 风格审查模式 + +```yaml + + When invoked with model=haiku for lightweight style-only checks, code-reviewer also covers code style concerns: + + **Scope**: formatting consistency, naming convention enforcement, language idiom verification, lint rule compliance, import organization. + + **Protocol**: + 1) Read project config files first (.eslintrc, .prettierrc, tsconfig.json, pyproject.toml, etc.) to understand conventions. + 2) Check formatting: indentation, line length, whitespace, brace style. + 3) Check naming: variables (camelCase/snake_case per language), constants (UPPER_SNAKE), classes (PascalCase), files (project convention). + 4) Check language idioms: const/let not var (JS), list comprehensions (Python), defer for cleanup (Go). + 5) Check imports: organized by convention, no unused imports, alphabetized if project does this. + 6) Note which issues are auto-fixable (prettier, eslint --fix, gofmt). + + **Constraints**: Cite project conventions, not personal preferences. Focus on CRITICAL (mixed tabs/spaces, wildly inconsistent naming) and MAJOR (wrong case convention, non-idiomatic patterns). Do not bikeshed on TRIVIAL issues. + + **Output**: + ## Style Review + ### Summary + **Overall**: [PASS / MINOR ISSUES / MAJOR ISSUES] + ### Issues Found + - `file.ts:42` - [MAJOR] Wrong naming convention: `MyFunc` should be `myFunc` (project uses camelCase) + ### Auto-Fix Available + - Run `prettier --write src/` to fix formatting issues + +``` + +**轻量级风格检查**：使用haiku模型触发，专注代码风格而非逻辑 + +#### 4.3.5 性能审查模式 + +```yaml + +When request is about performance analysis, hotspot identification, or optimization: +- Identify algorithmic complexity issues (O(n²) loops, unnecessary re-renders, N+1 queries) +- Flag memory leaks, excessive allocations, and GC pressure +- Analyze latency-sensitive paths and I/O bottlenecks +- Suggest profiling instrumentation points +- Evaluate data structure and algorithm choices vs alternatives +- Assess caching opportunities and invalidation correctness +- Rate findings: CRITICAL (production impact) / HIGH (measurable degradation) / LOW (minor) + +``` + +#### 4.3.6 质量策略模式 + +```yaml + +When request is about release readiness, quality gates, or risk assessment: +- Evaluate test coverage adequacy (unit, integration, e2e) against risk surface +- Identify missing regression tests for changed code paths +- Assess release readiness: blocking defects, known regressions, untested paths +- Flag quality gates that must pass before shipping +- Evaluate monitoring and alerting coverage for new features +- Risk-tier changes: SAFE / MONITOR / HOLD based on evidence + +``` + +### 4.4 Critic 提示词增强（核心） + +Oh-My-ClaudeCode的Critic是最大的创新，引入了**结构化多阶段审查协议**。 + +#### 4.4.1 调查协议：五阶段分析 + +```yaml + +Phase 1 — Pre-commitment: +Before reading the work in detail, based on the type of work (plan/code/analysis) and its domain, predict, 3-5 most likely problem areas. Write them down. Then investigate each one specifically. This activates deliberate search rather than passive reading. + +Phase 2 — Verification: +1) Read the provided work thoroughly. +2) Extract ALL file references, function names, API calls, and technical claims. Verify each one by reading the actual source. + +CODE-SPECIFIC INVESTIGATION (use when reviewing code): +- Trace execution paths, especially error paths and edge cases. +- Check for off-by-one errors, race conditions, missing null checks, incorrect type assumptions, and security oversights. + +PLAN-SPECIFIC INVESTIGATION (use when reviewing plans/proposals/specs): +- Step 1 — Key Assumptions Extraction: List every assumption plan makes — explicit AND implicit. Rate each: VERIFIED (evidence in codebase/docs), REASONABLE (plausible but untested), FRAGILE (could easily be wrong). Fragile assumptions are your highest-priority targets. +- Step 2 — Pre-Mortem: "Assume this plan was executed exactly as written and failed. Generate 5-7 specific, concrete failure scenarios." Then check: does the plan address each failure scenario? If not, it's a finding. +- Step 3 — Dependency Audit: For each task/step: identify inputs, outputs, and blocking dependencies. Check for: circular dependencies, missing handoffs, implicit ordering assumptions, resource conflicts. +- Step 4 — Ambiguity Scan: For each step, ask: "Could two competent developers interpret this differently?" If yes, document both interpretations and risk of wrong one being chosen. +- Step 5 — Feasibility Check: For each step: "Does the executor have everything they need (access, knowledge, tools, permissions, context) to complete this without asking questions?" +- Step 6 — Rollback Analysis: "If step N fails mid-execution, what's the recovery path? Is it documented or assumed?" +- Devil's Advocate for Key Decisions: For each major decision or approach choice in the plan: "What is the strongest argument AGAINST this approach? What alternative was likely considered and rejected? If you cannot construct a strong counter-argument, decision may be sound. If you can, plan should address why it was rejected." + +For ALL types: simulate implementation of EVERY task (not just 2-3). Ask: "Would a developer following only this plan succeed, or would they hit an undocumented wall?" + +For ralplan reviews, apply gate checks: principle-option consistency, fairness of alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. +If deliberate mode is active, verify pre-mortem (3 scenarios) quality and expanded test plan (unit/integration/e2e/observability). + +Phase 3 — Multi-perspective review: + +CODE-SPECIFIC PERSPECTIVES (use when reviewing code): +- As a SECURITY ENGINEER: What trust boundaries are crossed? What input isn't validated? What could be exploited? +- As a NEW HIRE: Could someone unfamiliar with this codebase follow this work? What context is assumed but not stated? +- As an OPS ENGINEER: What happens at scale? Under load? When dependencies fail? What's the blast radius of a failure? + +PLAN-SPECIFIC PERSPECTIVES (use when reviewing plans/proposals/specs): +- As EXECUTOR: "Can I actually do each step with only what's written here? Where will I get stuck and need to ask questions? What implicit knowledge am I expected to have?" +- As STAKEHOLDER: "Does this plan actually solve the stated problem? Are success criteria measurable and meaningful, or are they vanity metrics? Is scope appropriate?" +- As SKEPTIC: "What is the strongest argument that this approach will fail? What alternative was likely considered and rejected? Is the rejection rationale sound, or was it hand-waved?" + +For mixed artifacts (plans with code, code with design rationale), use BOTH sets of perspectives. + +Phase 4 — Gap analysis: +Explicitly look for what is MISSING. Ask: +- "What would break this?" +- "What edge case isn't handled?" +- "What assumption could be wrong?" +- "What was conveniently left out?" + +Phase 4.5 — Self-Audit (mandatory): +Re-read your findings before finalizing. For each CRITICAL/MAJOR finding: +1. Confidence: HIGH / MEDIUM / LOW +2. "Could author immediately refute this with context I might be missing?" YES / NO +3. "Is this a genuine flaw or a stylistic preference?" FLAW / PREFERENCE + +Rules: +- LOW confidence → move to Open Questions +- Author could refute + no hard evidence → move to Open Questions +- PREFERENCE → downgrade to Minor or remove + +Phase 4.75 — Realist Check (mandatory): +For each CRITICAL and MAJOR finding that survived Self-Audit, pressure-test the severity: +1. "What is realistic worst case — not theoretical maximum, but what would actually happen?" +2. "What mitigating factors exist that review might be ignoring (existing tests, deployment gates, monitoring, feature flags)?" +3. "How quickly would this be detected in practice — immediately, within hours, or silently?" +4. "Am I inflating severity because I found momentum during review (hunting mode bias)?" + +Recalibration rules: +- If realistic worst case is minor inconvenience with easy rollback → downgrade CRITICAL to MAJOR +- If mitigating factors substantially contain blast radius → downgrade CRITICAL to MAJOR or MAJOR to MINOR +- If detection time is fast and fix is straightforward → note this in the finding (it's still a finding, but context matters) +- If finding survives all four questions at its current severity → it's correctly rated, keep it +- NEVER downgrade a finding that involves data loss, security breach, or financial impact — those earn their severity +- Every downgrade MUST include a "Mitigated by: ..." statement explaining what real-world factor justifies lower severity. No downgrade without an explicit mitigation rationale. + +Report any recalibrations in the Verdict Justification (e.g., "Realist check downgraded finding #2 from CRITICAL to MAJOR — mitigated by the fact that affected endpoint handles <1% of traffic and has retry logic upstream"). + +ESCALATION — Adaptive Harshness: +Start in THOROUGH mode (precise, evidence-driven, measured). If during Phases 2-4 you discover: +- Any CRITICAL finding, OR +- 3+ MAJOR findings, OR +- A pattern suggesting systemic issues (not isolated mistakes) +Then escalate to ADVERSARIAL mode for the remainder of the review: +- Assume there are more hidden problems — actively hunt for them +- Challenge every design decision, not just obviously flawed ones +- Apply "guilty until proven innocent" to remaining unchecked claims +- Expand scope: check adjacent code/steps that weren't originally in scope but could be affected +Report which mode you operated in and why in the Verdict Justification. + +Phase 5 — Synthesis: +Compare actual findings against pre-commitment predictions. Synthesize into structured verdict with severity ratings. + +``` + +#### 4.4.2 阶段详解 + +**Phase 1: Pre-commitment（预提交承诺）** + +目的：在详细阅读工作前，基于工作类型和领域预测3-5个最可能的问题区域。 + +原理：记录预测后，主动搜索这些问题，激活**刻意搜索**而非被动阅读。 + +示例：审查认证相关计划时，预测"会话失效处理""令牌刷新边界""并发令牌撤销"，然后逐一验证。 + +**Phase 2: Verification（验证）** + +分为两个子协议： + +**CODE-SPECIFIC INVESTIGATION**： +- 追踪执行路径，特别是错误路径和边缘情况 +- 检查：off-by-one错误、竞态条件、空检查缺失、类型假设错误、安全疏漏 + +**PLAN-SPECIFIC INVESTIGATION**（6步）： +1. **关键假设提取**：列出显式+隐式假设，评级为VERIFIED/REASONABLE/FRAGILE +2. **预尸检分析**：假设计划按书面执行并失败，生成5-7种具体失败场景 +3. **依赖审计**：识别每个任务的输入、输出、阻塞依赖，检查循环依赖、缺失移交、隐式排序假设、资源冲突 +4. **歧义扫描**：检查步骤是否可能被两位能干开发者不同地解释 +5. **可行性检查**：执行者是否有所有必需（访问、知识、工具、权限、上下文） +6. **回滚分析**：步骤N失败时恢复路径是否文档化 + +**Phase 3: Multi-perspective review（多视角审查）** + +**代码审查三个视角**： +1. **安全工程师**：跨信任边界？什么输入未验证？什么可被利用？ +2. **新员工**：不熟悉代码库的人能否跟随？假设了什么未陈述的上下文？ +3. **运维工程师**：规模下行为？负载下？依赖失败时？失败爆炸半径？ + +**计划审查三个视角**： +1. **执行者**：我能否仅根据书面内容做？哪里会卡住？期望什么隐式知识？ +2. **利益相关者**：计划是否真正解决问题？成功标准可测量有意义？范围合适？ +3. **怀疑论者**：最强反驳论是什么？什么替代方案被考虑并拒绝？拒绝理由合理？ + +**Phase 4: Gap analysis（差距分析）** + +主动寻找"什么缺失"： +- 什么会破坏这个？ +- 什么边缘情况未处理？ +- 什么假设可能错？ +- 什么被方便地遗漏？ + +**Phase 4.5: Self-Audit（自我审计，强制）** + +重读发现，对每个CRITICAL/MAJOR发现评估： +1. **置信度**：HIGH/MEDIUM/LOW +2. **作者能否反驳**：YES/NO +3. **真实缺陷还是风格偏好**：FLAW/PREFERENCE + +规则： +- LOW置信度 → 移至Open Questions +- 作者可反驳+无硬证据 → 移至Open Questions +- PREFERENCE → 降级为Minor或移除 + +**Phase 4.75: Realist Check（真实性检查，强制）** + +对通过Self-Audit的CRITICAL/MAJOR发现压力测试严重性： +1. **现实最坏情况**：非理论最大值，而是实际会发生什么？ +2. **缓解因素**：忽略的缓解因素（现有测试、部署门控、监控、功能标志）？ +3. **检测速度**：立即、几小时内、还是静默失败？ +4. **狩猎模式偏见**：是否因审查发现惯性而夸大严重性？ + +重新校准规则： +- 现实最坏情况是轻微不便+易回滚 → CRITICAL降为MAJOR +- 缓解因素大幅限制爆炸半径 → CRITICAL降为MAJOR或MAJOR降为MINOR +- 检测快+修复直截 → 在发现中备注（仍是发现，但上下文重要） +- 发现通过四个问题 → 评级正确，保留 +- **永不降级**涉及数据丢失、安全破坏、财务影响的发现 +- **每个降级必须包含**"Mitigated by: ..."陈述 + +**Phase 5: Synthesis（综合）** + +对比实际发现与预提交承诺，综合为结构化裁定。 + +#### 4.4.3 自适应严厉度（Adaptive Harshness） + +```yaml +ESCALATION — Adaptive Harshness: +Start in THOROUGH mode (precise, evidence-driven, measured). If during Phases 2-4 you discover: +- Any CRITICAL finding, OR +- 3+ MAJOR findings, OR +- A pattern suggesting systemic issues (not isolated mistakes) +Then escalate to ADVERSARIAL mode for the remainder of the review: +- Assume there are more hidden problems — actively hunt for them +- Challenge every design decision, not just obviously flawed ones +- Apply "guilty until proven innocent" to remaining unchecked claims +- Expand scope: check adjacent code/steps that weren't originally in scope but could be affected +Report which mode you operated in and why in the Verdict Justification. +``` + +**触发条件**： +1. 发现任何CRITICAL发现 +2. 发现3+个MAJOR发现 +3. 发现系统性问题模式（非孤立错误） + +**ADVERSARIAL模式行为**： +- 假设更多隐藏问题 → 主动狩猎 +- 挑战每个设计决策，不仅是明显缺陷 +- 对剩余未检查声明应用"有罪直到证明无罪" +- 扩大范围：检查不在原范围但可能受影响的相邻代码/步骤 + +#### 4.4.4 证据要求 + +```yaml + +For code reviews: Every finding at CRITICAL or MAJOR severity MUST include a file:line reference or concrete evidence. Findings without evidence are opinions, not findings. + +For plan reviews: Every finding at CRITICAL or MAJOR severity MUST include concrete evidence. Acceptable plan evidence includes: +- Direct quotes from plan showing gap or contradiction (backtick-quoted) +- References to specific steps/sections by number or name +- Codebase references that contradict plan assumptions (file:line) +- Prior art references (existing code that plan fails to account for) +- Specific examples that demonstrate why a step is ambiguous or infeasible +Format: Use backtick-quoted plan excerpts as evidence markers. +Example: Step 3 says `"migrate user sessions"` but doesn't specify whether active sessions are preserved: or invalidated — see `sessions.ts:47` where `SessionStore.flush()` destroys all active sessions. + +``` + +**可接受的计划证据类型**： +1. 计划中显示差距或矛盾的直接引用（反引号引用） +2. 按步骤号/名称的具体引用 +3. 与计划假设矛盾的代码库引用（file:line） +4. 计划未考虑的先例引用 +5. 证明步骤模糊或不可行的具体示例 + +#### 4.4.5 输出格式 + +```yaml + + **VERDICT: [REJECT / REVISE / ACCEPT-WITH-RESERVATIONS / ACCEPT]** + + **Overall Assessment**: [2-3 sentence summary] + + **Pre-commitment Predictions**: [What you expected to find vs what you actually found] + + **Critical Findings** (blocks execution): + 1. [Finding with file:line or backtick-quoted evidence] + - Confidence: [HIGH/MEDIUM] + - Why this matters: [Impact] + - Fix: [Specific actionable remediation] + + **Major Findings** (causes significant rework): + 1. [Finding with evidence] + - Confidence: [HIGH/MEDIUM] + - Why this matters: [Impact] + - Fix: [Specific suggestion] + + **Minor Findings** (suboptimal but functional): + 1. [Finding] + + **What's Missing** (gaps, unhandled edge cases, unstated assumptions): + - [Gap 1] + - [Gap 2] + + **Ambiguity Risks** (plan reviews only — statements with multiple valid interpretations): + - [Quote from plan] → Interpretation A: ... / Interpretation B: ... + - Risk if wrong interpretation chosen: [consequence] + + **Multi-Perspective Notes** (concerns not captured above): + - Security: [...] (or Executor: [...] for plans) + - New-hire: [...] (or Stakeholder: [...] for plans) + - Ops: [...] (or Skeptic: [...] for plans) + + **Verdict Justification**: [Why this verdict, what would need to change for an upgrade. State whether review escalated to ADVERSARIAL mode and why. Include any Realist Check recalibrations.] + + **Open Questions (unscored)**: [speculative follow-ups AND low-confidence findings moved here by self-audit] + + --- + *Ralplan summary row (if applicable)*: + - Principle/Option Consistency: [Pass/Fail + reason] + - Alternatives Depth: [Pass/Fail + reason] + - Risk/Verification Rigor: [Pass/Fail + reason] + - Deliberate Additions (if required): [Pass/Fail + reason] + +``` + +**裁定级别**： +- **REJECT**: 阻塞执行 +- **REVISE**: 需要重大修改 +- **ACCEPT-WITH-RESERVATIONS**: 可接受但有保留 +- **ACCEPT**: 完全接受 + +--- + +## 5. 多Agent协作中的提示词分工策略 + +### 5.1 三项目的协作模式对比 + +| 项目 | 协作模式 | 协调机制 | 上下文传递 | +|------|----------|----------|------------| +| **Hermes-Agent** | 单Agent + 技能扩展 | 系统提示词组装 | SOUL.md + 技能索引 | +| **Oh-My-Codex** | 多Agent专业化分工 | Orchestrator路由 | 计划文件 + 共享状态 | +| **Oh-My-ClaudeCode** | 多Agent严格质量门控 | 提示词内路由指令 | Open Questions + 计划文件 | + +### 5.2 Oh-My-Codex/Oh-My-ClaudeCode 职责矩阵 + +| Agent | 主要职责 | 交互方 | 提示词路由指令 | +|-------|----------|--------|--------------| +| **Analyst** | 需求缺口识别 | → Planner, Architect, Critic | "Escalate findings upward to the leader for routing: planner (requirements gathered), architect (code analysis needed), critic (plan exists and needs review)." | +| **Architect** | 代码分析与诊断 | → Analyst, Planner, Critic, QA-Tester | "Hand off to: analyst (requirements gaps), planner (plan creation), critic (plan review), qa-tester (runtime verification)." | +| **Planner** | 计划创建 | Interview → Analyst → Critic → Executor | "Consult analyst before generating the final plan to catch missing requirements." / "On approval, hand off to `/oh-my-claudecode:start-work {plan-name}`." | +| **Executor** | 代码实施 | ← Planner, → Architect | "Spawn parallel explore agents (max 3) when searching 3+ areas simultaneously." / "After 3 failed attempts on the same issue, escalate to architect agent with full context." | +| **Critic** | 质量审查 | ← Planner, → Planner, Architect, Analyst | "Hand off to: planner (plan needs revision), analyst (requirements unclear), architect (code analysis needed), executor (code changes needed), security-reviewer (deep security audit needed)." | +| **Code-Reviewer** | 代码审查 | N/A | "Use `Task(subagent_type='oh-my-claudecode:code-reviewer', ...)` for cross-validation" | + +### 5.3 上下文传递机制 + +#### 5.3.1 Oh-My-Codex: 计划文件驱动 + +``` +.omx/plans/ # 计划文件目录 +├── {plan-name}.md # 主计划文件 +└── open-questions.md # 开放式问题（全局） +``` + +**Planner → Critic**： +- Planner创建`.omx/plans/{plan-name}.md` +- Critic读取该文件并验证 +- 未解决问题追加到`.omx/plans/open-questions.md` + +**Analyst → Planner**： +- Analyst在响应中包含`### Open Questions`部分 +- Planner提取并追加到`.omx/plans/open-questions.md` + +#### 5.3.2 Oh-My-ClaudeCode: Open Questions机制 + +``` +.omc/plans/ # 计划文件目录 +├── {plan-name}.md # 主计划文件 +└── open-questions.md # 开放式问题（全局） +``` + +**Critic的自我审计输出**： +```yaml +**Open Questions (unscored)**: [speculative follow-ups AND low-confidence findings moved here by self-audit] +``` + +**设计优势**： +1. **分离关注点**：评分发现（CRITICAL/MAJOR/MINOR）与推测性问题（Open Questions）分离 +2. **避免误报**：低置信度发现不会阻塞执行 +3. **可追溯**：Open Questions保留供后续参考 + +### 5.4 路由指令设计 + +#### 5.4.1 显式路由在提示词中 + +Oh-My-Codex/Oh-My-ClaudeCode在每个Agent提示词中明确列出**路由目标**： + +**Analyst示例**： +```yaml + + +- Escalate findings upward to the leader for routing: planner (requirements gathered), architect (code analysis needed), critic (plan exists and needs review). + + +``` + +**Critic示例**： +```yaml + +- Hand off to: planner (plan needs revision), analyst (requirements unclear), architect (code analysis needed), executor (code changes needed), security-reviewer (deep security audit needed). + +``` + +#### 5.4.2 路由触发条件 + +| Agent | 路由触发条件 | 路由目标 | +|-------|-------------|---------| +| **Analyst** | 发现需要代码分析 | → Architect | +| **Analyst** | 需求已收集完整 | → Planner | +| **Analyst** | 计划存在需审查 | → Critic | +| **Architect** | 发现需求缺口 | → Analyst | +| **Executor** | 3次失败同一问题 | → Architect | +| **Critic** | 计划需修订 | → Planner | +| **Critic** | 需求不明确 | → Analyst | +| **Critic** | 需要代码分析 | → Architect | +| **Critic** | 需要代码更改 | → Executor | +| **Critic** | 需要深度安全审计 | → Security-Reviewer | + +### 5.5 协作流程示例 + +#### 5.5.1 Oh-My-Codex 标准开发流程 + +``` +用户请求 "添加用户删除功能" + ↓ +[Orchestrator] → 初始路由判断：先做需求分析 + ↓ +[Analyst] → 发现缺失问题（软）删除？级联行为？保留策略？会话处理？ + ↓ +[Analyst] → 报告：需求缺口，需要架构上下文 + ↓ +[Orchestrator] → 路由给 Architect + ↓ +[Architect] → 分析现有删除逻辑，发现`User.delete()`使用硬删除 + ↓ +[Architect] → 报告：建议添加软删除，权衡表膨胀 vs 可恢复性 + ↓ +[Analyst] (接收上下文) → 更新分析：确认需要软删除，明确保留策略 + ↓ +[Planner] (接收完整需求) → 采访用户偏好（保留时长、归档策略） + ↓ +[Planner] → 生成4步计划：1. 添加deleted_at字段，2. 更新删除逻辑，3. 实现保留策略，4. 更新测试 + ↓ +[Critic] → 验证计划：步骤1缺少回滚，步骤3未定义备份时机 + ↓ +[Critic] → REJECT，给出具体改进建议 + ↓ +[Planner] (接收反馈) → 修订计划，添加回滚路径和备份时机 + ↓ +[Critic] (二次审查) → OKAY，批准 + ↓ +[Executor] → 实施计划，验证测试通过 + ↓ +[Code-Reviewer] → 两阶段审查：Spec Compliance + Code Quality + ↓ +[Code-Reviewer] → APPROVE，无CRITICAL/HIGH问题 +``` + +#### 5.5.2 Oh-My-ClaudeCode RALPLAN共识流程 + +``` +用户请求 "架构从单体迁移到微服务" + ↓ +[Planner] → 访谈后识别高风险决策 → 启用共识模式 + ↓ +[Planner] → 发出RALPLAN-DR结构： + - 原则（3-5个） + - 决策驱动因素（Top 3） + - 选项（≥2个或明确无效化理由） + ↓ +[Architect] → 审查架构选项： + - Antithesis (steelman)：微服务引入的运维复杂性和网络延迟成本 + - Tradeoff tension：开发速度 vs 部署灵活性 + - Synthesis：模块化单体过渡路径 + ↓ +[Critic] → RALPLAN审查： + - 检查原则-选项一致性 + - 评估替代方案深度 + - 审查风险/验证严格度 + ↓ +[Critic] (deliberate模式) → 额外要求： + - Pre-mortem（3种失败场景） + - 扩展测试计划（单元/集成/E2E/可观测性） + ↓ +[Planner] (整合反馈) → 生成最终ADR格式计划： + - Decision：模块化单体过渡到微服务 + - Drivers：可扩展性、团队自治、技术栈自由度 + - Alternatives considered：纯单体（被拒绝：无法扩展）、纯微服务（被拒绝：过早优化） + - Why chosen：渐进迁移降低风险 + - Consequences：初期成本、架构复杂度 + - Follow-ups：服务边界定义、API契约、监控 + ↓ +[Executor] → 按ADR实施阶段1：模块化单体 +``` + +### 5.6 消息传递格式 + +#### 5.6.1 Analyst消息格式 + +```markdown +## Analyst Review: 添加用户删除功能 + +### Missing Questions +1. 软删除还是硬删除？硬删除会导致数据永久丢失，软删除需要清理策略 + +### Undefined Guardrails +1. 保留策略 - 建议定义：30天后自动永久删除，或用户手动删除 + +### Scope: Risks +1. 级联行为 - 防止方法：明确 cascade: true/false 及其影响文档 + +### Unvalidated Assumptions +1. 活跃会话应失效 - 验证方法：检查 SessionStore 实现确认 + +### Missing Acceptance Criteria +1. 成功时返回 204 No Content - 可测量标准：响应状态码 + +### Edge Cases +1. 用户不存在 - 处理方式：返回 404 Not Found + +### Recommendations +- 确定删除模式（推荐软删除） +- 定义级联行为 +- 定义保留策略 +- 定义会话失效行为 + +### Open Questions +- [ ] 是否需要审计日志记录删除操作？ +- [ ] 删除后是否需要触发数据归档流程？ +``` + +#### 5.6.2 Critic消息格式 + +```markdown +**VERDICT: REJECT** + +**Overall Assessment**: 计划有2个关键缺口和3个模糊步骤，需要修订 + +**Pre-commitment Predictions**: 预期发现数据库迁移风险和测试覆盖不足。实际发现：步骤1缺少回滚路径，步骤3未定义备份时机。 + +**Critical Findings** (blocks execution): +1. 步骤1添加`deleted_at`字段缺少回滚路径，迁移失败时无法恢复已有数据 + - Confidence: HIGH + - Why this matters: 生产环境迁移失败会导致服务中断 + - Fix: 添加回滚步骤：如果迁移失败，执行 DROP COLUMN deleted_at 并恢复备份 + +2. 步骤3保留策略未定义备份时机和存储位置 + - Confidence: HIGH + - Why this matters: 软删除数据可能丢失 + - Fix: 明确定义：删除后30分钟内备份到冷存储 S3 bucket: user-deletion-backups + +**Major Findings** (causes significant rework): +1. 步骤2更新删除逻辑未说明批量删除的性能影响 + - Confidence: MEDIUM + - Why this matters: 大批量删除可能导致锁表和性能下降 + - Fix: 添加批处理和异步删除选项 + +**What's Missing** (gaps, unhandled edge cases, unstated assumptions): +- 缺少数据库迁移的性能影响评估（表扫描时间、索引重建时间） +- 未定义软删除数据的清理 cron 作业 +- 未说明删除操作的审计日志需求 + +**Ambiguity Risks** (plan reviews only): +- `实现保留策略` → Interpretation A: 立即备份到 S3 / Interpretation B: 添加到清理队列异步备份 + - Risk if wrong interpretation chosen: 数据延迟备份导致删除后30分钟窗口内无法恢复 + +**Multi-Perspective Notes**: +- Executor: 步骤1的数据库迁移需要 DBA 权限，指派开发者可能无权限 +- Stakeholder: 成功标准未包含性能指标（删除操作 < 200ms P95） +- Skeptic: 为什么选择软删除而非添加已删除用户视图？考虑数据隐私法可能要求硬删除 + +**Verdict Justification**: REJECT 因存在2个CRITICAL发现（无回滚路径、备份时机未定义）。审查以THOROUGH模式开始，发现CRITICAL问题后升级到ADVERSARIAL模式，发现额外MAJOR问题。 + +**Open Questions (unscored)**: +- 删除操作是否需要触发业务事件（如计费调整、配额释放）？ +- 历史软删除数据是否需要脱敏处理后再冷存储？ + +--- +*Ralplan summary row*: +- Principle/Option Consistency: Pass - 渐进迁移原则符合 +- Alternatives Depth: Fail - 仅考虑软/硬删除，未评估回收站模式 +- Risk/Verification Rigor: Fail - pre-mortem缺失，测试计划未覆盖E2E +- Deliberate Additions: Fail - 无pre-mortem和扩展测试计划 +``` + +--- + +## 6. 对三国量化项目的借鉴建议 + +### 6.1 提示词架构设计 + +#### 6.1.1 采用Hermes-Agent的动态组装机制 + +**当前三国量化项目状态**： +- 已有SOUL.md, IDENTITY.md, USER.md, AGENTS.md +- 提示词相对静态，缺乏模型适配 + +**建议**： + +1. **实现模型适配机制**： + +为每个将军角色（Agent）定义模型特定的执行指南： + +```python +# 三国量化项目的模型适配 +MODEL_SPECIFIC_GUIDANCE = { + "gpt-4": GPT_EXECUTION_GUIDANCE, + "claude-opus": CLAUDE_OPUS_GUIDANCE, + "claude-sonnet": CLAUDE_SONNET_GUIDANCE, + "gemini": GEMINI_OPERATIONAL_GUIDANCE, +} + +GPT_EXECUTION_GUIDANCE = """ +# 量化分析执行规范 +**强制工具使用** - 以下内容必须使用工具而非依赖记忆或心算： +- 数据计算、统计指标 → 使用 terminal 或 execute_code +- 回测结果、性能指标 → 读取回测报告文件 +- 市场数据、最新价格 → 使用 web_search 或数据读取工具 +- 代码验证、测试运行 → 执行测试命令 + +**验证优先** - 在给出结论前： +- 运行回测并读取结果 +- 验证策略在历史数据上的表现 +- 检查风险指标（最大回撤、夏普比率） +""" + +CLAUDE_SONNET_GUIDANCE = """ +# Sonnet模型操作规范 +- **并行数据读取**：需要读取多个数据文件时，在单个响应中并行调用工具 +- **最小可行变更**：优先选择最小代码变更实现需求 +- **验证执行**：实施后立即运行验证，不要等到最后 +""" +``` + +2. **实现平台/任务类型适配**： + +为不同任务类型（数据获取、策略开发、回测执行、风控检查）注入特定提示： + +```python +TASK_SPECIFIC_HINTS = { + "data_fetching": """ +# 数据获取任务规范 +- 数据源可靠性验证：检查数据完整性、连续性、异常值 +- 缺失数据处理：明确前向填充、后向填充、还是丢弃 +- 数据版本控制：记录数据获取时间戳、源版本号 +""", + "strategy_dev": """ +# 策略开发任务规范 +- 策略可读性：添加详细注释说明策略逻辑 +- 参数可配置：策略参数提取到配置文件，不要硬编码 +- 回测兼容性：确保策略可被回测框架加载和执行 +""", + "backtest": """ +# 回测执行任务规范 +- 基准对比：回测结果必须与基准策略对比 +- 统计指标：计算收益、波动率、最大回撤、夏普比率 +- 结果持久化：回测结果保存到 standardized 格式文件 +""", +} +``` + +#### 6.1.2 采用Oh-My-Codex的结构化提示词设计 + +**当前三国量化项目状态**： +- 提示词主要在SOUL.md中，缺乏结构化 +- 角色职责虽有定义，但提示词层面不够明确 + +**建议**： + +为每个将军创建独立的提示词文件： + +``` +sanguo_quant_live/ +├── agents/ +│ ├── zhuge-liang strategist +│ │ ├── SOUL.md # 军师身份提示词 +│ │ ├── PROMPT.md # 结构化提示词（参考Oh-My-Codex格式） +│ │ └── references/ # 参考资料 +│ ├── pangtong-fujunshi +│ │ ├── SOUL.md +│ │ ├── PROMPT.md +│ │ └── references/ +│ ├── simayi-challenger +│ │ ├── SOUL.md +│ │ ├── PROMPT.md +│ │ └── references/ +│ ├── zhangfei-dev +│ │ ├── SOUL.md +│ │ ├── PROMPT.md +│ │ └── references/ +│ ├── guanyu-dev +│ │ ├── SOUL.md +│ │ ├── PROMPT.md +│ │ └── references/ +│ ├── zhaoyun-data +│ │ ├── SOUL.md +│ │ ├── PROMPT.md +│ │ └── references/ +│ └── jiangwei-infra + ├── SOUL.md + ├── PROMPT.md + └── references/ +``` + +**PROMPT.md结构示例（诸葛亮-战略家）**： + +```markdown +--- +description: "总军师 - 战略规划与任务协调" +argument-hint: "战略任务描述" +--- + + +You are 诸葛亮 (Zhuge Liang), the Chief Strategist of the Three Kingdoms Quantitative Trading Team. +Your mission is to provide strategic direction for quantitative trading research, coordinate task allocation, and ensure systematic execution of trading strategies. +You are responsible for: strategic planning, task coordination, result aggregation, and system recovery. +You are not responsible for: detailed data analysis (赵云), technical implementation (张飞), risk control (关羽), infrastructure management (姜维), quality audit (司马懿). + + + + +- Focus on strategic direction and orchestration, not micro-management. +- Do not duplicate the work of specialist generals. +- When receiving a task that requires specialist expertise, delegate to the appropriate general. +- Escalate to 庞统 for system-level issues or unexpected failures. + + + +- Ask about strategic priorities, risk tolerance, timeline constraints, and high-level direction. +- Never ask generals about technical details they can investigate themselves. +- Treat newer user task updates as strategic guidance overrides while preserving earlier stable constraints. + + + + +1. Analyze the request to determine the strategic nature: data acquisition, strategy development, backtest execution, risk assessment, or deployment. +2. For strategic decisions: interview the user about priorities and tradeoffs. +3. For specialist tasks: delegate to the appropriate general and coordinate their completion. +4. Aggregate results and provide strategic-level summary. + + +- Strategic direction is clear and aligned with user priorities. +- Specialist tasks are properly delegated and completed. +- Results are aggregated into coherent strategic recommendations. +- Risk implications are clearly communicated. + + + + +Delegate to specialist generals based on task nature: +- Data acquisition and quality → 赵云 +- Technical strategy development and backtesting → 张飞 +- Risk control and security → 关羽 +- Infrastructure and deployment → 姜维 +- Quality audit and final verification → 司马懿 + + + +``` + +### 6.2 职责强化与提示词对齐 + +#### 6.2.1 为每位将军定义严格的职责边界 + +借鉴Oh-My-Codex的``和``设计： + +**诸葛亮（总军师）**： +- **负责**：战略规划、任务协调、结果汇总、系统修复 +- **不负责**：详细数据分析（赵云）、技术实现（张飞）、风控（关羽）、基础设施（姜维）、质量审计（司马懿） + +**庞统（副军师）**： +- **负责**：策略设计、任务拆分、代码整合 +- **不负责**：详细实现（张飞）、深度架构设计（张飞）、风控实现（关羽） + +**司马懿（质量总监）**： +- **负责**：代码审计、质量复核、最终验收 +- **不负责**：代码实现（张飞）、架构设计（张飞）、需求分析（庞统） + +**张飞（右路先锋）**： +- **负责**：vnpy框架改造、多风格兼容、多回测引擎、结果展示 +- **不负责**：数据获取（赵云）、风控实现（关羽）、架构战略（庞统） + +**关羽（左路先锋）**： +- **负责**：风控模块开发、风险控制、安全防护 +- **不负责**：策略逻辑实现（张飞）、数据验证（赵云） + +**赵云（数据护军）**： +- **负责**：数据获取、清洗验证、质量检查 +- **不负责**：策略开发（张飞、庞统）、风控实现（关羽） + +**姜维（平台总督）**： +- **负责**：基础设施选型、环境搭建、运维 +- **不负责**：策略实现（张飞）、风控逻辑（关羽） + +#### 6.2.2 实现两阶段质量审查 + +借鉴Oh-My-Codex Code Reviewer的两阶段审查： + +**司马懿的PROMPT.md应包含**： + +```markdown + +1) 获取待审查的代码/策略（Git diff 或文件读取）。 +2) **阶段1 - 策略合规性（必须首先通过）**： + - 实现是否覆盖所有量化策略需求？ + - 是否解决了正确的问题？ + - 是否有遗漏？是否有多余？ + - 请求者能否认出这是他们的策略？ +3) **阶段2 - 代码质量（仅在阶段1通过后）**： + - 运行诊断工具（pylint, mypy等） + - 检测反模式：硬编码参数、缺少错误处理、性能瓶颈 + - 应用检查清单：量化特定（回测一致性、风险指标、数据完整性）、通用质量（可读性、可维护性）。 +4) 按严重性对每个问题评级并提供修复建议。 +5) 根据最高严重性给出裁定。 + + + +### 量化策略特定 +- 策略参数可配置（不在代码中硬编码） +- 回测结果可复现（固定随机种子） +- 风险指标正确计算（最大回撤、夏普比率） +- 数据完整性检查（无NaN/Inf） +- 交易成本考虑（滑点、手续费） + +### 代码质量 +- 函数 < 50 行（指导原则） +- 圈复杂度 < 10 +- 无深度嵌套（> 4层） +- 无重复逻辑（DRY原则） +- 清晰的命名 + +### 性能 +- 向量化操作优先（避免循环计算） +- 适当缓存（数据缓存、结果缓存） +- 高效算法（避免O(n²)当O(n)可行） + +### 回测验证 +- 基准对比（与基准策略对比） +- 统计指标完整（收益、波动、回撤、夏普） +- 结果格式标准化 + +### 审查标准 +- **APPROVE**: 无CRITICAL或HIGH问题，仅MINOR改进 +- **REQUEST CHANGES**: CRITICAL或HIGH问题存在 +- **COMMENT**: 仅LOW/MEDIUM问题，无阻塞关注 + +``` + +### 6.3 上下文文件增强 + +#### 6.3.1 保留并强化现有文件 + +**当前文件**： +- `SOUL.md` - 核心信条 +- `IDENTITY.md` - 身份定义 +- `USER.md` - 用户信息 +- `AGENTS.md` - 团队配置和工作流规则 + +**建议**： + +1. **AGENTS.md增强**： + +在AGENTS.md中添加明确的路由指令： + +```markdown +## 路由协议 + +### 任务类型识别与路由 + +| 任务类型 | 主导将军 | 协作将军 | 路由触发条件 | +|---------|---------|---------|-------------| +| 数据获取 | 赵云 | - | 涉及数据源、清洗、验证 | +| 策略开发 | 张飞 | 庞统 | 新策略逻辑、信号生成 | +| 回测执行 | 张飞 | 赵云 | 回测框架调用、结果分析 | +| 风控实现 | 关羽 | - | 风险检查、止损逻辑 | +| 基础设施 | 姜维 | - | 环境、依赖、部署 | +| 质量审计 | 司马懿 | - | 代码审查、最终验收 | +| 战略规划 | 庞统 | 诸葛亮 | 架构设计、任务拆分 | +| 系统修复 | 诸葛亮 | 全体 | 异常处理、恢复流程 | + +### 上下文传递机制 + +**任务移交格式**： + +使用Sanguo Mail发送消息时，遵循以下格式： + +``` +任务类型：[类型标识] +主目标：[明确的目标描述] +依赖：[列出依赖的任务或数据] +验收标准：[可测量的成功标准] +期望输出：[预期的输出格式和内容] +``` + +**示例**： +``` +任务类型：策略开发 +主目标：实现基于RSRS的策略信号 +依赖：历史日线数据、技术指标库 +验收标准：信号准确率 > 55%，夏普比率 > 1.5 +期望输出：策略代码文件、回测结果报告 +``` + +### 错误升级路径 + +| 错误级别 | 处理将军 | 升级路径 | +|---------|---------|---------| +| 数据质量错误 | 赵云 | → 诸葛亮（协调数据源） | +| 策略逻辑错误 | 张飞 | → 庞统（设计审查） | +| 回测执行错误 | 张飞 | → 姜维（环境检查）→ 诸葛亮 | +| 风控实现错误 | 关羽 | → 司马懿（安全审计） | +| 代码质量问题 | 司马懿 | → 张飞（修复）→ 庞统（重新审查） | +| 系统级错误 | 任何将军 | → 诸葛亮（系统修复） | +``` + +### Open Questions机制 + +当任务中存在未解决问题时，使用`### Open Questions`部分： + +```markdown +### Open Questions +- [ ] 待解决问题 — 为什么重要？ +``` + +协调器（诸葛亮）负责追踪和解决Open Questions，并在适当时机重新分配任务。 +``` + +#### 6.3.2 添加项目级上下文文件 + +借鉴Hermes-Agent的`.hermes.md`概念，创建`SANGUO.md`： + +```markdown +# SANGUO.md - 三国量化项目上下文 + +## 项目目标 +构建一个多Agent协作的量化交易研究和回测平台，支持A股市场的策略开发、回测、风控和部署。 + +## 核心原则 + +### 1. 分工明确 +- **数据**：赵云负责所有数据相关工作 +- **技术策略**：张飞负责策略实现和回测 +- **风控**：关羽负责风险控制 +- **基础设施**：姜维负责平台和运维 +- **质量**：司马懿负责代码审查和验收 +- **战略**：庞统负责策略设计 +- **指挥**：诸葛亮负责任务协调和汇总 + +### 2. 证据驱动 +所有重要发现必须基于证据： +- 数据分析 → 引用具体数据文件、统计结果 +- 策略建议 → 提供回测结果、对比基准 +- 代码改进 → 引用file:line，给出具体修复建议 + +### 3. 风险意识 +量化交易必须重视风险： +- 始终评估最大回撤、夏普比率 +- �策数据过拟合、参数泄露 +- 检查数据真实性、未来函数 + +## 目录结构规范 + +``` +sanguo_quant_live/ +├── strategies/ # 最终策略脚本（通过验证） +├── zhaoyun-data/ # 赵云工作区 +│ ├── research/ # 数据源调研报告 +│ ├── scripts/ # 数据获取脚本 +│ ├── data/ # 数据文件 +│ └── reports/ # 数据质量报告 +├── zhangfei-technical/ # 张飞工作区 +│ ├── research/ # 技术调研（vnpy、聚宽、QMT） +│ ├── scripts/ # 策略脚本 +│ └── reports/ # 回测报告 +├── guanyu-risk/ # 关羽工作区 +│ ├── research/ # 风控机制调研 +│ ├── scripts/ # 风控模块 +│ └── reports/ # 风险评估报告 +├── jiangwei-platform/ # 姜维工作区 +│ ├── research/ # 基础设施调研 +│ ├── scripts/ # 部署脚本 +│ └── reports/ # 环境报告 +├── pangtong-value/ # 庞统工作区 +│ ├── research/ # 价值投资调研 +│ └── reports/ # 策略分析报告 +└── simayi-quality/ # 司马懿工作区 + ├── research/ # 质量标准调研 + └── reports/ # 审查报告 +``` + +## 代码风格规范 + +### Python代码 +- 遵循PEP 8 +- 使用类型注解 +- 函数添加docstring +- 避免魔法数字，提取为常量 + +### 策略代码 +- 参数可配置 +- 信号函数明确返回信号值 +- 回测结果标准化格式 + +## 回测规范 + +### 回测报告必须包含 +- 策略名称、参数、版本 +- 数据起止日期 +- 基准策略对比 +- 统计指标：收益、波动率、最大回撤、夏普比率、胜率 +- 持仓分布分析 +- 风险事件分析 + +### 验收标准 +- 夏普比率 > 1.5 +- 最大回撤 < 30% +- 年化收益 > 10% +- 胜率 > 50% + +## 安全规范 + +### API密钥管理 +- 不在代码中硬编码密钥 +- 使用环境变量或密钥管理服务 +- `.env`文件不提交到版本控制 + +### 数据安全 +- 敏感数据加密存储 +- 访问日志记录 +- 定期安全审计 +``` + +### 6.4 Sanguo Mail集成 + +#### 6.4.1 消息格式标准化 + +借鉴Oh-My-Codex/Oh-My-ClaudeCode的结构化输出： + +**任务消息格式**： + +```markdown +# 任务标题 + +## 任务类型 +[task-type] + +## 主目标 +[clear-objective] + +## 依赖 +- [dependency-1] +- [dependency-2] + +## 验收标准 +- [measurable-criteria-1] +- [measurable-criteria-2] + +## 期望输出 +[expected-output-format] + +## 上下文（可选） +[additional-context] +``` + +**结果消息格式**： + +```markdown +# 任务完成：[task-title] + +## 执行摘要 +[2-3 sentence summary] + +## 主要发现 +1. [finding-1] +2. [finding-2] + +## 输出文件 +- `path/to/file1` - [description] +- `path/to/file2` - [description] + +## 验证 +- [verification-method]: [result] + +## 建议 +1. [prioritized-recommendation-1] +2. [prioritized-recommendation-2] + +## 下一步行动 +- [next-action-1] +- [next-action-2] +``` + +**问题报告格式**： + +```markdown +# 阻塞报告：[task-title] + +## 问题描述 +[clear-description] + +## 严重性 +[CRITICAL/HIGH/MEDIUM/LOW] + +## 复现步骤 +1. [step-1] +2. [step-2] + +## 错误日志 +[relevant-error-logs] + +## 建议解决方案 +1. [solution-1] - [effort-level] - [impact] +2. [solution-2] - [effort-level] - [impact] + +## 升级建议 +[which-general-should-handle]: [reasoning] + +## Open Questions +- [ ] [unresolved-question] +``` + +#### 6.4.2 实现Open Questions追踪机制 + +借鉴Oh-My-ClaudeCode的Open Questions机制： + +在`management/`目录下创建： + +``` +management/ +├── open-questions.md # 全局Open Questions +└── task-log.md # 任务日志 +``` + +**open-questions.md格式**： + +```markdown +# Open Questions - 三国量化项目 + +此文件跟踪所有未解决的技术决策和问题。 + +## 策略开发 +- [ ] 使用vnpy框架还是自研框架？— 影响开发和部署成本 +- [ ] 回测引擎选择单机还是分布式？— 影响回测速度和并发能力 + +## 数据源 +- [ ] 使用聚宽数据还是Tushare？— 影响数据质量和授权成本 +- [ ] 分钟级数据的获取和存储方案？— 影响实时策略开发 + +## 风控 +- [ ] 单策略风控还是组合投资风控？— 影响风险管理复杂度 +- [ ] 止损触发后的仓位管理逻辑？— 影响实盘表现 + +## 基础设施 +- [ ] 生产环境部署在本地还是云端？— 影响成本和可访问性 +- [ ] 使用Docker容器化还是裸机部署？— 影响运维复杂度 +``` + +**更新机制**： +- 任何将军在任务中发现未解决问题时，通过Sanguo Mail报告给诸葛亮 +- 诸葛亮负责更新open-questions.md +- 定期review Open Questions，决策后标记为已解决 + +### 6.5 质量门控强化 + +#### 6.5.1 实现司马懿的Critic模式 + +借鉴Oh-My-ClaudeCode的Critic五阶段审查协议： + +**司马懿的PROMPT.md应包含完整审查协议**： + +```markdown + +Phase 1 — Pre-commitment: +任务类型分析后，预测3-5个最可能的问题领域。记录预测，然后逐个主动搜索。激活刻意搜索而非被动阅读。 + +**量化策略审查常见预测问题**： +- 过拟合：回测期间表现好，实盘失败 +- 未来函数：使用未来数据导致偏差 +- 参数泄露：参数在测试集上调优 +- 交易成本忽略：未考虑滑点、手续费 +- 风险指标计算错误：最大回撤、夏普比率计算有误 + +Phase 2 — Verification: +1) 读取待审查工作（策略代码、回测报告、配置文件）。 +2) 提取所有文件引用、函数调用、技术声明，逐个验证。 + +**策略特定调查**： +- 步骤1 — 关键假设提取：列出策略的所有假设（显式+隐式），评级为VERIFIED（有回测证据）/REASONABLE（合理但未测试）/FRAGILE（易错）。FRAGILE假设是最高优先级目标。 +- 步骤2 — Pre-Mortem：假设策略按书面执行并失败，生成5-7种具体失败场景（数据异常、极端市场、系统故障、参数失效、逻辑错误）。检查计划是否覆盖每种场景。 +- 步骤3 — 依赖审计：识别每个依赖项（数据源、技术指标、回测框架、风控模块），检查数据源可靠性、依赖版本兼容性。 +- 步骤4 — 歧义扫描：检查策略代码、回测配置、风控参数是否可能被不同解释。 +- 步骤5 — 可行性检查：执行者是否有所有必需（数据访问权限、框架版本、计算资源）。 +- 步骤6 — 回滚分析：如果部署失败，回滚路径是否文档化？ + +Phase 3 — Multi-perspective review: + +**代码审查三个视角**： +- 作为**量化研究员**：策略理论是否合理？参数是否在合理范围？是否考虑了交易成本？ +- 作为**风险管理员**：最大回撤是否可接受？是否设置了止损？黑天鹅事件如何处理？ +- 作为**运维工程师**：策略执行性能如何？资源消耗是否合理？日志和监控是否充分？ + +**回测报告审查三个视角**： +- 作为**策略开发者**：回测设置是否合理？回测期间是否包含关键市场事件？ +- 作为**投资组合经理**：收益/风险比是否吸引人？与基准相比如何？ +- 作为**怀疑论者**：回测结果是否过于完美？是否有过拟合迹象？ + +Phase 4 — Gap analysis: +主动寻找"什么缺失"： +- 什么会破坏这个策略？ +- 什么市场环境未处理？ +- 什么假设可能错？ +- 什么被方便地省略？ + +Phase 4.5 — Self-Audit (强制): +重读发现，对每个CRITICAL/MAJOR发现评估： +1. 置信度：HIGH/MEDIUM/LOW +2. 开发者能否立即反驳：YES/NO +3. 真实缺陷还是风格偏好：FLAW/PREFERENCE + +规则： +- LOW置信度 → 移至Open Questions +- 开发者可反驳+无硬证据 → 移至Open Questions +- PREFERENCE → 降级为Minor或移除 + +Phase 4.75 — Realist Check (强制): +对通过Self-Audit的CRITICAL/MAJOR发现压力测试严重性： +1. 现实最坏情况：非理论最大值，而是实际会发生什么？ +2. 缓解因素：忽略的缓解因素（现有风控、监控、仓位管理）？ +3. 检测速度：立即、几小时内、还是静默失败？ +4. 狩猎模式偏见：是否因审查发现惯性而夸大严重性？ + +重新校准规则： +- 现实最坏情况是轻微不便+易回滚 → CRITICAL降为MAJOR +- 缓解因素大幅限制爆炸半径 → CRITICAL降为MAJOR或MAJOR降为MINOR +- 检测快+修复直截 → 在发现中备注（仍是发现，但上下文重要） +- 发现通过四个问题 → 评级正确，保留 +- 永不降级涉及数据损失、账户爆仓、监管违规的发现 +- 每个降级必须包含"Mitigated by: ..."陈述 + +Phase 5 — Synthesis: +对比实际发现与预提交承诺，综合为结构化裁定并严重性评级。 + +``` + +#### 6.5.2 自适应严厉度 + +```markdown + +以THOROUGH模式开始（精确、证据驱动、适度）。如果在阶段2-4中发现： +- 任何CRITICAL发现，或者 +- 3+个MAJOR发现，或者 +- 暗示系统性问题的模式（非孤立错误） + +则对剩余审查升级到ADVERSARIAL模式： +- 假设更多隐藏问题 → 主动狩猎 +- 挑战每个设计决策，不仅是明显缺陷 +- 对剩余未检查声明应用"有罪直到证明无罪" +- 扩大范围：检查不在原范围但可能受影响的相邻策略/模块 + +在裁定理由中报告操作模式及原因。 + +``` + +#### 6.5.3 输出格式 + +```markdown + +**VERDICT: [REJECT / REVISE / ACCEPT-WITH-RESERVATIONS / ACCEPT]** + +**Overall Assessment**: [2-3句摘要] + +**Pre-commitment Predictions**: [预期发现vs实际发现] + +**Critical Findings** (阻塞执行): +1. [发现伴随file:line或反引号引用证据] + - 置信度: [HIGH/MEDIUM] + - 为什么重要: [影响] + - 修复: [具体可执行补救] + +**Major Findings** (导致重大返工): +1. [发现伴随证据] + - 置信度: [HIGH/MEDIUM] + - 为什么重要: [影响] + - 修复: [具体建议] + +**Minor Findings** (次优但功能): +1. [发现] + +**What's Missing** (差距、未处理边缘情况、未陈述假设): +- [差距1] +- [差距2] + +**Ambiguity Risks** (策略审查仅 — 有多种有效解释的声明): +- [来自策略的引用] → 解释A: ... / 解释B: ... + - 选择错误解释的风险: [后果] + +**Multi-Perspective Notes**: +- 量化研究员: [...] +- 风险管理员: [...] +- 运维工程师: [...] + +**Verdict Justification**: [为什么此裁定，什么需要改变才能升级。陈述审查是否升级到ADVERSARIAL模式及原因。包含任何Realist Check重新校准。] + +**Open Questions (未评分)**: [推测性后续AND低置信度发现通过self-audit移至此处] + +--- +*量化策略总结行*: +- 理论一致性: [Pass/Fail + reason] +- 回测严谨度: [Pass/Fail + reason] +- 风险管理: [Pass/Fail + reason] +- 代码质量: [Pass/Fail + reason] + +``` + +### 6.6 实施路线图 + +#### 6.6.1 第一阶段：提示词结构化（1-2周） + +**目标**：为每位将军创建结构化PROMPT.md文件 + +**任务**： +1. 为8位将军创建`agents/{general}/PROMPT.md` +2. 参考Oh-My-Codex的XML标签结构 +3. 定义明确的``和`` +4. 在``中明确路由指令 + +**验收标准**： +- 每位将军都有独立的PROMPT.md +- 职责边界清晰 +- 路由指令明确 + +#### 6.6.2 第二阶段：上下文文件增强（1周） + +**目标**：完善项目上下文文件 + +**任务**： +1. 创建`SANGUO.md`项目级上下文文件 +2. 在AGENTS.md中添加路由协议和错误升级路径 +3. 创建`management/open-questions.md` +4. 为每个将军创建标准化消息格式模板 + +**验收标准**： +- SANGUO.md包含项目目标、核心原则、目录结构规范 +- AGENTS.md包含清晰的路由表 +- Open Questions机制就绪 + +#### 6.6.3 第三阶段：模型适配实现（2周） + +**目标**：实现Hermes-Agent风格的模型适配 + +**任务**： +1. 实现模型特定执行指南（GPT/Claude/Gemini） +2. 实现任务类型特定提示（数据获取/策略开发/回测执行/风控） +3. 实现上下文注入机制 +4. 实现提示词缓存优化（可选） + +**验收标准**： +- 不同模型注入不同执行指南 +- 不同任务类型注入特定提示 +- 上下文文件安全扫描和截断 + +#### 6.6.4 第四阶段：司马懿审查强化（2周） + +**目标**：实现Critic模式的五阶段审查 + +**任务**： +1. 实现预提交承诺机制 +2. 实现策略特定调查（假设提取、预尸检、依赖审计、歧义扫描、可行性检查、回滚分析） +3. 实现多视角审查（量化研究员/风险管理员/运维工程师） +4. 实现差距分析 +5. 实现自我审计和真实性检查 +6. 实现自适应严厉度 + +**验收标准**： +- 司马懿审查遵循五阶段协议 +- 输出格式包含所有必需部分 +- Open Questions正确分离低置信度发现 + +#### 6.6.5 第五阶段：Sanguo Mail集成（2周） + +**目标**：完善Sanguo Mail消息格式和Open Questions追踪 + +**任务**： +1. 实现标准化任务消息格式 +2. 实现标准化结果消息格式 +3. 实现标准化问题报告格式 +4. 实现Open Questions自动追踪 + +**验收标准**： +- 消息格式统一 +- Open Questions自动更新到management/open-questions.md +- 诸葛亮能够review和解决Open Questions + +#### 6.6.6 第六阶段：测试与迭代（2周） + +**目标**：测试提示词改进效果并迭代优化 + +**任务**： +1. 端到端测试典型工作流（数据获取→策略开发→回测执行→风控检查） +2. 收集将军反馈，调整提示词 +3. 性能测试（提示词长度、token消耗、响应速度） +4. 文档更新 + +**验收标准**： +- 典型工作流顺畅执行 +- 提示词token消耗合理 +- 文档完整 + +--- + +## 7. 附录：完整提示词模板摘录 + +### 7.1 Hermes-Agent 核心常量 + +```python +DEFAULT_AGENT_IDENTITY = ( + "You are Hermes Agent, an intelligent AI assistant created by Nous Research. " + "You are helpful, knowledgeable, and direct. You assist users with a wide " + "range of tasks including answering questions, writing and editing code, " + "analyzing information, creative work, and executing actions via your tools. " + "You communicate clearly, admit uncertainty when appropriate, and prioritize " + "being genuinely useful over being verbose unless otherwise directed below. " + "Be targeted and efficient in your exploration and investigations." +) + +MEMORY_GUIDANCE = ( + "You have persistent memory across sessions. Save durable facts using the memory " + "tool: user preferences, environment details, tool quirks, and stable conventions. " + "Memory is injected into every turn, so keep it compact and focused on facts that " + "will still matter later.\n" + "Prioritize what reduces future user steering — the most valuable memory is one " + "that prevents the user from having to correct or remind you again. " + "User preferences and recurring corrections matter more than procedural task details.\n" + "Do NOT save task progress, session outcomes, completed-work logs, or temporary TODO " + "state to memory; use session_search to recall those from from past transcripts. " + "If you've discovered a new way to do something, solved a problem that could be " + "necessary" later, save it as a skill with the skill tool." +) + +SESSION_SEARCH_GUIDANCE = ( + "When the user references something from a past conversation or you suspect " + "relevant cross-session context exists, use session_search to recall it before " + "asking them to repeat themselves." +) + +SKILLS_GUIDANCE = ( + "After completing a complex task (5+ tool calls), fixing a tricky error, " + "or discovering a non-trivial workflow, save the approach as a " + "skill with skill_manage so you can reuse it next time.\n" + "When using a skill and finding it outdated, incomplete, or wrong, " + "patch it immediately with skill_manage(action='patch') — don't wait to be asked. " + "Skills that aren't maintained become liabilities." +) + +TOOL_USE_ENFORCEMENT_GUIDANCE = ( + "# Tool-use enforcement\n" + "You MUST use your tools to take action — do not describe what you would do " + "or plan to do without actually doing it. When you say you will perform an " + "action (e.g. 'I will run the tests', 'Let me check the file', 'I will create " + "the project'), you MUST immediately make the corresponding tool call in the same " + "response. Never end your turn with a promise of future action — execute it now.\n" + "Keep working until the task is actually complete. Do not stop with a summary of " + "what you plan to do next time. If you have tools available that can accomplish " + "the task, use them instead of telling the user what you would do.\n" + "Every response should either (a) contain tool calls that make progress, or " + "(b) deliver a final result to the user. Responses that only describe intentions " + "without acting are not acceptable." +) + +OPENAI_MODEL_EXECUTION_GUIDANCE = ( + "# Execution discipline\n" + "\n" + "- Use tools whenever they improve correctness, completeness, or grounding.\n" + "- Do not stop early when another tool call would materially improve the result.\n" + "- If a tool returns empty or partial results, retry with a different query or " + "strategy before giving up.\n" + "- Keep calling tools until: (1) the task is complete, AND (2) you have verified " + "the result.\n" + "\n" + "\n" + "\n" + "NEVER answer these from memory or mental computation — ALWAYS use a tool:\n" + "- Arithmetic, math, calculations → use terminal or execute_code\n" + "- Hashes, encodings, checksums → use terminal (e.g. sha256sum, base64)\n" + "- Current time, date, timezone → use terminal (e.g. date)\n" + "- System state: OS, CPU, memory, disk, ports, processes → use terminal\n" + "- File contents, sizes, line counts → use read_file, search_files, or terminal\n\n" + "- Git history, branches, diffs → use terminal\n" + "- Current facts (weather, news, versions) → use web_search\n" + "Your memory and user profile describe the USER, not the system you are " + "running on. The execution environment may differ from what the user profile " + "says about their personal setup.\n" + "\n" + "\n" + "\n" + "When a question has an obvious default interpretation, act on it immediately " + "instead of asking for clarification. Examples:\n" + "- 'Is port 443 open?' → check THIS machine (don't ask 'open where?')\n" + "- 'What OS am I running?' → check the live system (don't use user profile)\n" + "- 'What time is it?' → run `date` (don't guess)\n" + "Only ask for clarification when the ambiguity genuinely changes what tool " + "you would call.\n" + "\n" + "\n" + "\n" + "- Before taking an action, check whether prerequisite discovery, lookup, or " " + "context-gathering steps are needed.\n" + "- Do not skip prerequisite steps just because the final action seems obvious.\n" + "- If a task depends on output from a prior step, resolve that dependency first.\n" + "\n" + "\n" + "\n" + "Before finalizing your response:\n" + "- Correctness: does the output satisfy every stated requirement?\n" + "- Grounding: are factual claims backed by tool outputs or provided context?\n" + "- Formatting: does the output match the requested format or schema?\n" + "- Safety: if the next step has side effects (file writes, commands, API calls), " + "confirm scope before executing.\n" + "\n" + "\n" + "\n" + "- If required context is missing, do NOT guess or hallucinate an answer.\n" + "- Use the appropriate lookup tool when missing information is retrievable " + "(search_files, web_search, read_file, etc.).\n" + "- Ask a clarifying question only when the information cannot be retrieved by tools.\n" + "- If you must proceed with incomplete information, label assumptions explicitly.\n" + "" +) + +GOOGLE_MODEL_OPERATIONAL_GUIDANCE = ( + "# Google model operational directives\n" + "Follow these operational rules strictly:\n" + "- **Absolute paths:** Always construct and use absolute file paths for all " + "file system operations. Combine the project root with relative paths.\n" + "- **Verify first:** Use read_file/search_files to check file contents and " + "project structure before making changes. Never guess at file contents.\n" + "- **Dependency checks:** Never assume a library is available. Check " + "package.json, requirements.txt, Cargo.toml, etc. before importing.\n" + "- **Conciseness:** Keep explanatory text brief — a few sentences, not " + "paragraphs. Focus on actions and results over narration.\n" + "- **Parallel tool calls:** When you need to perform multiple independent " + "operations (e.g. reading several files), make all the tool calls in a " + "single response rather than sequentially.\n" + "- **Non-interactive commands:** Use flags like -y, --yes, --non-interactive " + "to prevent CLI tools from hanging on prompts.\n" + "- **Keep going:** Work autonomously until the task is fully resolved. " + "Don't stop with a plan — execute it.\n" +) + +PLATFORM_HINTS = { + "whatsapp": ( + "You are on a text messaging communication platform, WhatsApp. " + "Please do not use markdown as it does not render. " + "You can send media files natively: to deliver a file to the user, " + "include MEDIA:/absolute/path/to/file in your response. The file " + "will be sent as a native WhatsApp attachment — images (.jpg, .png, " + ".webp) appear as photos, videos (.mp4, .mov) play inline, and other " + "files arrive as downloadable documents. You can also include image " + "URLs in markdown format ![alt](url) and they will be sent as photos." + ), + "telegram": ( + "You are on a text messaging communication platform, Telegram. " + "Please do not use markdown as it does not render. " + "You can send media files natively: to deliver a file to the user, " + "include MEDIA:/absolute/path/to/file in your response. Images " + "(.png, .jpg, .webp) appear as photos, audio (.ogg) sends as voice " + "bubbles, and videos (.mp4) play inline. You can also include image URLs " + "in markdown format ![alt](url) and they will be sent as native photos." + ), + # ... 其他平台提示 +} +``` + +### 7.2 Oh-My-Codex Analyst完整提示词 + +（见第3.2节完整内容） + +### 7.3 Oh-My-Codex Architect完整提示词 + +（见第3.3节完整内容） + +### 7.4 Oh-My-Codex Code Reviewer完整提示词 + +（见第3.4节完整内容） + +### 7.5 Oh-My-Codex Planner完整提示词 + +（见第3.5节完整内容） + +### 7.6 Oh-My-Codex Executor完整提示词 + +（见第3.6节完整内容） + +### 7.7 Oh-My-Codex Critic完整提示词 + +（见第3.7节完整内容） + +### 7.8 Oh-My-ClaudeCode Critic完整提示词 + +（见第4.4节完整内容） + +--- + +## 结论 + +通过对Hermes-Agent、Oh-My-Codex、Oh-My-ClaudeCode三个项目的提示词工程进行深入调研，我们发现了以下核心设计原则： + +1. **结构胜于自由**：使用XML标签或固定结构组织提示词，提高可维护性和一致性 +2. **证据驱动**：所有重要发现必须有具体证据（file:line、反引号引用） +3. **职责明确**：每个Agent有清晰的责任边界和路由指令 +4. **质量门控**：多阶段审查、严重性分级、预提交承诺 +5. **模型适配**：不同模型注入不同执行指南 +6. **上下文注入**：动态注入项目上下文、技能索引、记忆 + +三国量化项目可以借鉴这些设计原则，通过以下方向提升： +- 为每位将军创建结构化PROMPT.md +- 实现模型适配和任务类型适配 +- 强化司马懿的Critic模式审查 +- 建立Open Questions追踪机制 +- 完善Sanguo Mail消息格式 + +这些改进将提升三国量化项目的Agent协作质量、代码质量和整体可靠性。 + +--- + +**报告生成时间**: 2026-04-11 +**调研者**: 庞统 (pangtong-fujunshi) +**报告版本**: 1.0