@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/knowledge-base/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: knowledge-base
+description: 知识库 + RAG 开发指南
+---
+
+# 知识库 + RAG 开发指南
+
+## 项目结构
+
+```
+WHartTest_Django/knowledge/
+├── models.py           # KnowledgeBase, Document 模型
+├── services.py         # 向量检索服务
+├── serializers.py      # API 序列化
+└── views.py            # 知识库 API
+```
+
+## 核心组件
+
+### Qdrant 向量数据库
+- 容器: `wharttest-qdrant`
+- 端口: 8918 (REST API)
+- 数据卷: `qdrant-data`
+
+### BGE-M3 嵌入模型
+- 容器: `wharttest-bge-m3` (Ollama)
+- 端口: 8917
+- 模型: `bge-m3`
+
+## 知识库服务
+
+```python
+from langchain_qdrant import QdrantVectorStore
+from langchain_community.embeddings import OllamaEmbeddings
+
+# 初始化嵌入模型
+embeddings = OllamaEmbeddings(
+    model="bge-m3",
+    base_url="http://bge-m3:11434"
+)
+
+# 连接向量数据库
+vector_store = QdrantVectorStore.from_existing_collection(
+    embedding=embeddings,
+    collection_name="my_collection",
+    url="http://qdrant:6333"
+)
+
+# 相似度检索
+docs = vector_store.similarity_search(query, k=5)
+```
+
+## 文档处理
+
+```python
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+splitter = RecursiveCharacterTextSplitter(
+    chunk_size=1000,
+    chunk_overlap=200
+)
+chunks = splitter.split_documents(documents)
+```
+
+## RAG 检索增强
+
+```python
+from langchain.chains import RetrievalQA
+
+qa_chain = RetrievalQA.from_chain_type(
+    llm=llm,
+    retriever=vector_store.as_retriever(
+        search_kwargs={"k": 5}
+    ),
+    return_source_documents=True
+)
+
+result = qa_chain.invoke({"query": question})
+```
+
+## 环境变量
+
+```bash
+QDRANT_URL=http://qdrant:6333
+OLLAMA_BASE_URL=http://bge-m3:11434
+```
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/langgraph/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: langgraph
+description: LangGraph + LangChain 开发指南
+---
+
+# LangGraph + LangChain 开发指南
+
+## 项目集成位置
+
+```
+WHartTest_Django/
+├── langgraph_integration/    # LLM 配置管理
+│   ├── models.py             # LLMConfig, ChatSession
+│   └── views.py              # Chat API
+├── orchestrator_integration/ # Agent 编排
+│   ├── agent_loop.py         # Agent 循环逻辑
+│   ├── graph.py              # LangGraph 工作流
+│   └── prompts.py            # 系统提示词
+└── knowledge/                # RAG 知识库
+    └── services.py           # 向量检索服务
+```
+
+## LangGraph 工作流定义
+
+```python
+from langgraph.graph import StateGraph, END
+from typing import TypedDict, Annotated
+from operator import add
+
+class AgentState(TypedDict):
+    messages: Annotated[list, add]
+    next_action: str
+
+def create_graph():
+    workflow = StateGraph(AgentState)
+    
+    workflow.add_node("agent", agent_node)
+    workflow.add_node("tools", tool_node)
+    
+    workflow.set_entry_point("agent")
+    workflow.add_conditional_edges(
+        "agent",
+        should_continue,
+        {"continue": "tools", "end": END}
+    )
+    workflow.add_edge("tools", "agent")
+    
+    return workflow.compile()
+```
+
+## LLM 配置使用
+
+```python
+from langgraph_integration.models import LLMConfig
+from langchain_openai import ChatOpenAI
+
+config = LLMConfig.objects.get(id=config_id)
+llm = ChatOpenAI(
+    model=config.model_name,
+    api_key=config.api_key,
+    base_url=config.api_base_url,
+    temperature=config.temperature
+)
+```
+
+## MCP 工具集成
+
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+async def get_mcp_tools(mcp_configs):
+    client = MultiServerMCPClient(mcp_configs)
+    tools = await client.get_tools()
+    return tools
+```
+
+## 检查点持久化
+
+```python
+from langgraph.checkpoint.postgres import PostgresSaver
+
+checkpointer = PostgresSaver.from_conn_string(
+    os.environ.get('DATABASE_URL')
+)
+graph = workflow.compile(checkpointer=checkpointer)
+```
+
+## 常用模式
+
+### 流式输出
+```python
+async for event in graph.astream(
+    {"messages": [HumanMessage(content=query)]},
+    config={"configurable": {"thread_id": thread_id}}
+):
+    yield event
+```
+
+### 工具调用
+```python
+from langchain_core.tools import tool
+
+@tool
+def my_tool(query: str) -> str:
+    """工具描述"""
+    return f"Result for {query}"
+```
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/learn/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: learn
+description: Workflow skill from learn.md
+---
+
+# /learn - Extract Reusable Patterns
+
+Analyze the current session and extract any patterns worth saving as skills.
+
+## Trigger
+
+Run `/learn` at any point during a session when you've solved a non-trivial problem.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns**
+   - What error occurred?
+   - What was the root cause?
+   - What fixed it?
+   - Is this reusable for similar errors?
+
+2. **Debugging Techniques**
+   - Non-obvious debugging steps
+   - Tool combinations that worked
+   - Diagnostic patterns
+
+3. **Workarounds**
+   - Library quirks
+   - API limitations
+   - Version-specific fixes
+
+4. **Project-Specific Patterns**
+   - Codebase conventions discovered
+   - Architecture decisions made
+   - Integration patterns
+
+## Output Format
+
+Create a skill file at `~/.claude/skills/learned/[pattern-name].md`:
+
+```markdown
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround]
+
+## Example
+[Code example if applicable]
+
+## When to Use
+[Trigger conditions - what should activate this skill]
+```
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+3. Draft the skill file
+4. Ask user to confirm before saving
+5. Save to `~/.claude/skills/learned/`
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused - one pattern per skill

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/log-analysis-optimization/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: log-analysis-optimization
+description: Midscene 日志分析优化指南，识别性能瓶颈、提升测试效率、解决问题的最佳实践
+---
+
+# Midscene 日志分析优化工作流
+
+> 通过系统化分析日志，识别性能瓶颈，优化测试效率，快速定位和解决问题。
+
+---
+
+## 工作流概览
+
+```mermaid
+graph TD
+    A[定位日志目录] --> B[快速健康检查]
+    B --> C{是否有明显问题?}
+    C -->|是| D[问题诊断模块]
+    C -->|否| E[性能瓶颈分析]
+    E --> F[优化建议生成]
+    D --> G[解决方案设计]
+    F --> H[实施优化]
+    G --> H
+    H --> I[效果验证]
+```
+
+---
+
+## 第一步：日志目录定位与文件说明
+
+Midscene 运行产物存储在 `midscene_run/` 目录下：
+
+```text
+midscene_run/<timestamp>/
+├── log/
+│   ├── console.log          # 核心流程日志，优先分析
+│   ├── ai-profile-stats.log # AI 性能统计，含 token 和耗时
+│   ├── ai-call.log          # AI 调用详情，含推理过程
+│   ├── agent.log            # Agent 执行细节
+│   └── cache.log            # 缓存操作日志
+├── report/
+│   └── *.html               # 可视化报告
+└── run-info.json            # 运行元数据
+```
+
+---
+
+## 第二步：快速健康检查
+
+### 2.1 检查测试结果摘要
+
+在 `console.log` 末尾查找测试摘要：
+
+```text
+════════════════════════════════════════════════════════════
+  测试执行摘要 (Test Execution Summary)
+════════════════════════════════════════════════════════════
+  总用例数 (Total):    6
+  通过 (Passed):       6  ✓
+  失败 (Failed):       0  
+  执行时间 (Duration): 10m 56.6s
+════════════════════════════════════════════════════════════
+```
+
+### 2.2 关键指标基准线
+
+| 指标 | 健康值 | 警告值 | 危险值 |
+|:---|:---|:---|:---|
+| 单用例耗时 | < 60s | 60-120s | > 120s |
+| AI 调用耗时 | < 8s | 8-15s | > 15s |
+| 导航节省率 | > 30% | 15-30% | < 15% |
+| 缓存命中率 | > 50% | 20-50% | < 20% |
+
+---
+
+## 第三步：性能瓶颈识别
+
+### 3.1 AI 调用耗时分析
+
+从 `ai-profile-stats.log` 提取性能数据：
+
+```text
+# 格式: timestamp, model, mode, prompt-tokens, completion-tokens, total-tokens, cost-ms
+[时间] model, ep-xxx, mode, doubao-vision, prompt-tokens, 1302, completion-tokens, 714, total-tokens, 2016, cost-ms, 13185
+```
+
+**关注点**：
+- `cost-ms > 15000`：调用过慢，检查网络或模型负载
+- `completion-tokens > 5000`：响应过长，需优化 prompt
+- `prompt-tokens > 3000`：输入过大，考虑精简上下文
+
+### 3.2 高耗时操作识别
+
+搜索 `console.log` 中的 AI 操作日志：
+
+```bash
+# 查找耗时超过 15 秒的操作
+grep -E "duration.*[0-9]{5}" console.log
+```
+
+常见高耗时操作模式：
+
+| 操作类型 | 正常耗时 | 原因分析 |
+|:---|:---|:---|
+| `aiTap` | 5-10s | 元素定位 + 点击确认 |
+| `aiQuery` | 3-8s | 页面分析 |
+| `aiInput` | 10-18s | 键盘输入 + 验证 |
+| `aiWaitFor` | 依赖页面 | 等待条件满足 |
+
+### 3.3 Token 消耗异常检测
+
+```bash
+# 查找异常高的 completion tokens
+grep "completion-tokens" ai-profile-stats.log | awk -F',' '{print $8}' | sort -n | tail -10
+```
+
+**异常阈值**：单次 `completion-tokens > 5000` 应检查：
+- AI 响应是否陷入循环
+- Prompt 是否过于开放
+
+---
+
+## 第四步：效率优化建议
+
+### 4.1 批量验证策略
+
+**现有模式**（已实现）：
+```text
+BatchVerifier: 批量验证完成
+  totalElements: 21, aiCallCount: 3, totalDuration: 18650ms
+```
+
+**优化建议**：
+- 每批元素数控制在 10 个左右
+- 使用 `useFreeze: true` 冻结页面上下文
+- 相似元素合并为一次查询
+
+### 4.2 状态导航优化
+
+**识别重复导航**：
+```text
+[StateNavigator] 当前状态: unknown (置信度: 30%, 尝试 1/2)
+[StateNavigator] 未找到从 unknown 到 main_page 的路径，等待...
+```
+
+**优化建议**：
+- 添加更多状态识别规则
+- 提高 `unknown` 状态的识别覆盖率
+- 使用 `NavigationOptimizer` 跳过已知位置
+
+**效果指标**：
+```text
+NavigationOptimizer: 节省导航=2, 总请求=5, 节省率=40.0%
+```
+
+### 4.3 Prompt 精简建议
+
+**当前模式**（可优化）：
+```json
+{
+  "prompt": "分析当前 APP 页面状态，返回 JSON:\n{\n  \"hasSplashScreen\": ..., \"hasWelcomeGuide\": ..., ... }"
+}
+```
+
+**优化后**：
+- 减少描述性文字，使用简洁的字段名
+- 预定义返回格式，减少 AI 推理负担
+- 使用缓存避免重复检测
+
+---
+
+## 第五步：问题诊断
+
+### 5.1 常见故障模式速查表
+
+| 现象 | 日志关键词 | 可能原因 | 解决方案 |
+|:---|:---|:---|:---|
+| AI 调用超时 | `AI 调用超时`, `timeout` | 网络慢/模型负载高 | 增加超时时间，添加重试 |
+| 状态识别失败 | `unknown`, `置信度: 30%` | 页面状态未覆盖 | 添加新状态规则 |
+| 元素找不到 | `Element Not Found` | Prompt 不准确/页面未加载 | 优化 prompt，增加等待 |
+| SmartWait 失败 | `达到最大重试次数` | 页面状态不稳定 | 增加 stabilityCount |
+| 导航循环 | `超过最大尝试次数` | 状态转换规则缺失 | 添加转换规则 |
+
+### 5.2 错误根因分析流程
+
+```mermaid
+graph TD
+    A[发现错误] --> B{错误类型?}
+    B -->|超时| C[检查网络和模型响应]
+    B -->|元素未找到| D[查看截图确认页面状态]
+    B -->|断言失败| E[检查预期值和实际值]
+    C --> F[调整超时配置]
+    D --> G[优化元素定位 Prompt]
+    E --> H[修正测试数据或断言]
+```
+
+### 5.3 日志关键词速查
+
+```bash
+# 快速定位错误
+grep -E "\[ERROR\]|\[WARN \]" console.log
+
+# 查找超时
+grep -i "timeout" console.log
+
+# 查找状态问题
+grep "unknown" console.log
+
+# 查找重试
+grep -i "retry" console.log
+```
+
+---
+
+## 第六步：最佳实践
+
+### 6.1 日志分析标准流程
+
+1. **快速扫描**：查看测试摘要，确认通过/失败数
+2. **定位问题**：搜索 `[ERROR]`、`[WARN ]` 关键词
+3. **时间分析**：检查各阶段耗时，识别瓶颈
+4. **详细追踪**：结合 HTML 报告查看截图和时间线
+
+### 6.2 性能监控指标
+
+| 指标 | 采集位置 | 监控建议 |
+|:---|:---|:---|
+| 单用例耗时 | 测试摘要 | 趋势监控，超过阈值告警 |
+| AI 调用耗时 | ai-profile-stats.log | P99 不超过 15s |
+| Token 消耗 | ai-profile-stats.log | 单次不超过 5000 |
+| 导航节省率 | console.log | 保持 > 30% |
+| 缓存命中率 | console.log | 目标 > 50% |
+
+### 6.3 持续改进建议
+
+- **定期分析**：每周分析一次日志趋势
+- **基准对比**：建立性能基准，对比历史数据
+- **规则更新**：根据新页面状态更新识别规则
+- **缓存维护**：定期清理无效缓存
+
+---
+
+## 相关 Skills
+
+- `skills/midscene-log-analysis/SKILL.md` - 基础日志分析
+- `skills/midscene-framework/SKILL.md` - 框架开发指南
+- `skills/error-handling/SKILL.md` - 错误处理技巧

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/mcp-builder/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: mcp-builder
+description: Workflow skill from mcp-builder.md
+---
+
+# MCP Server 构建指南
+
+构建高质量的 MCP (Model Context Protocol) 服务器，让 LLM 能够与外部服务交互。
+
+## 核心原则
+
+1. **工具设计**: 每个工具应该做一件事并做好
+2. **错误处理**: 返回有意义的错误信息
+3. **类型安全**: 使用 TypeScript 或 Python 类型提示
+4. **文档**: 每个工具都需要清晰的描述和参数说明
+
+## Python (FastMCP) 示例
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
+@mcp.tool()
+def my_tool(param: str) -> str:
+    """工具描述"""
+    return result
+```
+
+## TypeScript (MCP SDK) 示例
+
+```typescript
+import { Server } from "@modelcontextprotocol/sdk/server";
+
+const server = new Server({
+  name: "my-server",
+  version: "1.0.0"
+});
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [{ name: "my_tool", description: "...", inputSchema: {...} }]
+}));
+```
+
+## 最佳实践
+
+- 使用环境变量存储敏感配置
+- 实现速率限制和超时
+- 记录关键操作日志
+- 提供健康检查端点

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/midscene-fix-review/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: midscene-fix-review
+description: Midscene 失败复盘与最小改动修复流程（日志→根因→修复→验证→复盘）
+---
+
+# Midscene Fix Review
+
+> 定位 midscene_run/... 根因并给出最小改动修复与验证路径，要求自我迭代并通过 Review 标准。
+
+---
+
+## 工作流概览
+
+```mermaid
+graph TD
+    A[收集输入] --> B[定位日志]
+    B --> C[根因归纳]
+    C --> D[最小改动方案]
+    D --> E[落地改动]
+    E --> F[自检与 Review]
+    F -->|通过| G[收尾同步]
+    F -->|不通过| D
+```
+
+---
+
+## 目标与约束
+
+- 聚焦“最小改动、兼容现有策略”的修复路径，优先改动已有模块而非新建文件。
+- 若写代码，必须为新函数添加函数级注释，保持 UTF-8 编码。
+- 需要验证逻辑时：在 `test-temp/` 创建临时测试文件并使用测试框架运行，完成后删除。
+- 每轮对话结束：更新 `README.md` 的任务列表，并记录关键结论到记忆系统。
+- 项目内最佳实践清单：`openspec/specs/skill-governance/spec.md`。
+
+---
+
+## 必备输入
+
+- `midscene_run/<run_id>` 路径
+- 用例名
+- 期望行为
+- 已知结论与可疑模块
+
+---
+
+## 日志定位与证据链
+
+按顺序读取并建立时间线：
+
+1. `log/console.log`（beforeAll/BatchVerifier/aiWaitFor/handlePopups）
+2. `log/ai-call.log`（aiQuery/aiTap/JSON 响应结构）
+3. `log/android-device.log` 与 `log/img.log`（截图通道异常）
+
+---
+
+## 根因归纳（四类）
+
+- **解析层**：aiQuery 返回格式与解析习惯不一致（如缺少 `data` 包裹）。
+- **预操作策略**：缓存跳过 preAction 后未验证目标状态，缺少强制重试。
+- **弹窗策略**：触发时机过宽导致副作用或遗漏关键节点弹窗。
+- **设备通道**：`Screenshot returned no data` 影响识别与定位稳定性。
+
+---
+
+## 最小改动方案模板
+
+输出必须指明：
+- 文件路径
+- 关键函数名
+- 改动点
+- 风险与验证路径
+
+---
+
+## 示例：BatchVerifier 断言为空
+
+**日志证据**：
+```text
+[WARN ] BatchVerifier: 批量查询结果为空，使用默认值
+```
+
+**推断**：
+ai-call.log 返回 JSON 数组，但解析层只读取 `data` 字段，导致结果被丢弃。
+
+**最小修复**：
+- `src/optimization/BatchVerifier.ts` → `buildBatchQueryPrompt` 统一输出 `{ "data": [...] }`
+- 解析失败时禁止默认“通过”，改为显式失败或回退重试
+
+**验证**：
+单跑相关用例，确认 `verify_not_exists` 不再误通过。
+
+---
+
+## 自检与 Review 通过标准
+
+- 结论与证据闭环（日志时间戳、文件路径、关键语句对齐）。
+- 修复方案为最小改动且可验证，有明确验证路径。
+- 若涉及代码改动：函数级注释齐全、无新增任务型文档、测试临时文件已删除。
+- README 任务列表已更新，关键结论已记录到记忆系统。
+- 不通过则回到“最小改动方案模板”重新迭代。
+
+---
+
+## 输出要求（简洁）
+
+- 结论（1-2 句）→ 证据（日志文件+时间戳）→ 影响（失败路径）
+- 最小修复方案 → 验证步骤
+- 若需改动：列出文件路径与关键函数名
+
+---
+
+## 相关 Skills
+
+- #midscene-log-analysis
+- #midscene-framework