@wwkit/harness 1.0.8 → 1.0.10

package/skills/read-docs/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: read-docs
+description: |
+  按路径读取文档或浏览目录结构。文件直接显示内容，目录显示一级子项列表。
+  内置 OpenCode 文档库，相对路径基于 references/ 解析，用户无需输入 references/ 前缀。
+  提供：目录浏览、文件读取、内置文档库。
+  适用：查阅文档、浏览目录结构、了解功能用法。
+  不适用：修改文档、创建文档、递归批量读取。
+---
+
+# 文档读取器
+
+## 工作流模式
+
+本 Skill 采用 **顺序工作流**：
+
+1. **解析**：解析路径参数，确定是文件还是目录
+2. **输出**：文件→显示内容；目录→显示一级子项列表；无参数→显示 references/ 下一级目录
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| path | 否 | 字符串 | 文件或目录路径。相对路径基于 references/ 解析（如 `opencode` → `references/opencode/`）；绝对路径直接读取。不提供则列出 references/ 下可用目录 |
+
+## 输出
+
+- 无参数：references/ 下的一级目录列表
+- 文件路径：文件完整内容
+- 目录路径：该目录下的一级子目录和文件列表
+
+---
+
+## 阶段一：解析
+
+### 1.1 无参数
+
+列出 `references/` 下的一级目录：
+
+```
+可用文档目录：
+- opencode/    # OpenCode 使用文档
+```
+
+提示用户指定目录或文件路径。
+
+### 1.2 相对路径
+
+路径不以 `/` 或盘符开头时，解析为 `references/<path>`：
+
+- `opencode` → `references/opencode/`
+- `opencode/guide` → `references/opencode/guide/`
+- `opencode/guide/index.md` → `references/opencode/guide/index.md`
+
+### 1.3 绝对路径
+
+路径以 `/` 或盘符（如 `D:/`）开头时，直接使用。
+
+### 1.4 路径类型判断
+
+- 路径指向文件 → 进入阶段二（文件读取）
+- 路径指向目录 → 进入阶段三（目录浏览）
+- 路径不存在 → 报错，提示路径无效
+
+---
+
+## 阶段二：文件读取
+
+使用 Read 工具读取文件内容，直接输出完整内容。
+
+输出格式：
+
+```
+--- <path> ---
+
+<文件完整内容>
+```
+
+读取后用户可基于内容提问，AI 基于已读取的内容回答。
+
+---
+
+## 阶段三：目录浏览
+
+列出该目录下的一级子项（不递归）：
+
+1. 使用 Glob 工具扫描 `目录/*`（非递归）
+2. 区分子目录和文件
+3. 按字母排序，子目录在前，文件在后
+
+输出格式：
+
+```
+<目录路径>/
+
+目录：
+- agents/
+- cli/
+- guide/
+- ...
+
+文件：
+- index.md
+- providers.md
+- ...
+```
+
+提示用户可指定子目录或文件继续浏览。
+
+---
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 路径不存在 | 提示路径无效，列出可用目录供选择 |
+| 目录为空 | 提示目录无内容 |
+| 文件读取失败 | 输出错误信息 |
+| 无参数且 references/ 为空 | 提示暂无可用文档 |
+
+## 一定要做
+
+1. 相对路径基于 references/ 解析，用户不需要输入 references/ 前缀
+2. 目录浏览只显示一级子项，不递归
+3. 文件读取直接显示完整内容
+4. 无参数时列出 references/ 下可用目录
+5. 目录浏览时区分子目录和文件，分别列出
+
+## 一定不要做
+
+1. 不要递归扫描目录下所有文件
+2. 不要批量读取目录下多个文件
+3. 不要修改或创建文档
+4. 不要在路径不存在时静默失败

package/skills/read-docs/references/opencode/agents/cases.md

@@ -0,0 +1,206 @@
+# Agent 案例
+
+## 案例 1：多语言文档生成系统
+
+需求：自动将 API 文档翻译成多语言版本。
+
+### 系统设计
+
+```
+用户输入 API 文档
+       ↓
+   @doc-parser（解析文档结构）
+       ↓
+   @translator-zh（翻译成中文）
+   @translator-ja（翻译成日文）  ← 并行
+   @translator-ko（翻译成韩文）
+       ↓
+   @doc-formatter（格式化输出）
+       ↓
+   多语言文档
+```
+
+### 配置
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "doc-generator": {
+      "description": "多语言文档生成编排器",
+      "mode": "primary",
+      "prompt": "{file:./prompts/doc-generator.md}",
+      "permission": {
+        "task": {
+          "*": "deny",
+          "doc-parser": "allow",
+          "translator-*": "allow",
+          "doc-formatter": "allow"
+        }
+      }
+    },
+    "doc-parser": {
+      "description": "解析 API 文档结构，提取可翻译内容",
+      "mode": "subagent",
+      "temperature": 0.1
+    },
+    "translator-zh": {
+      "description": "英译中专家，保持技术术语准确",
+      "mode": "subagent",
+      "temperature": 0.3
+    },
+    "translator-ja": {
+      "description": "英译日专家",
+      "mode": "subagent",
+      "temperature": 0.3
+    },
+    "translator-ko": {
+      "description": "英译韩专家",
+      "mode": "subagent",
+      "temperature": 0.3
+    },
+    "doc-formatter": {
+      "description": "文档格式化，确保多语言版本格式一致",
+      "mode": "subagent",
+      "temperature": 0.1
+    }
+  }
+}
+```
+
+## 案例 2：代码审计流水线
+
+需求：对 PR 进行全方位代码审计。采用 Parallelization + Orchestrator-Workers 混合模式。
+
+### 系统设计
+
+```
+PR 代码变更
+       ↓
+   @audit-coordinator（协调器）
+       ↓
+   ┌──────────────────────────────────┐
+   │  并行执行（Sectioning）          │
+   │  @security-auditor              │
+   │  @performance-auditor           │
+   │  @quality-auditor               │
+   │  @test-auditor                  │
+   └──────────────────────────────────┘
+       ↓
+   汇总所有发现
+       ↓
+   @report-generator（生成报告）
+       ↓
+   审计报告
+```
+
+### 配置
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "audit-coordinator": {
+      "description": "代码审计协调器，编排多维度审计",
+      "mode": "subagent",
+      "model": "anthropic/claude-opus-4-5-thinking",
+      "prompt": "{file:./prompts/audit-coordinator.md}",
+      "steps": 50
+    },
+    "security-auditor": {
+      "description": "安全漏洞审计：注入、认证、数据泄露",
+      "mode": "subagent",
+      "temperature": 0.1,
+      "permission": { "edit": "deny" }
+    },
+    "performance-auditor": {
+      "description": "性能审计：复杂度、内存、并发",
+      "mode": "subagent",
+      "temperature": 0.1,
+      "permission": { "edit": "deny" }
+    },
+    "quality-auditor": {
+      "description": "代码质量审计：可读性、SOLID、重复代码",
+      "mode": "subagent",
+      "temperature": 0.2,
+      "permission": { "edit": "deny" }
+    },
+    "test-auditor": {
+      "description": "测试审计：覆盖率、边界情况、Mock 质量",
+      "mode": "subagent",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny",
+        "bash": {
+          "*": "deny",
+          "npm test*": "allow",
+          "npm run test*": "allow"
+        }
+      }
+    },
+    "report-generator": {
+      "description": "生成结构化审计报告",
+      "mode": "subagent",
+      "temperature": 0.2
+    }
+  }
+}
+```
+
+### 创建专家 Agent
+
+```
+.opencode/
+├── agent/
+│   └── security-auditor.md
+└── prompts/
+    ├── audit-coordinator.md
+    ├── security-auditor.md
+    ├── performance-auditor.md
+    ├── quality-auditor.md
+    ├── test-auditor.md
+    └── report-generator.md
+```
+
+完整示例：security-auditor.md
+
+```md
+---
+description: |
+  安全漏洞审计专家。专注 OWASP Top 10、注入攻击、认证绕过、敏感数据泄露。
+  适用场景：PR 审查、代码安全扫描、上线前检查。
+  不适用：性能优化、代码风格、功能开发。
+mode: subagent
+temperature: 0.1
+permission:
+  edit: deny
+---
+# 角色
+你是一位资深安全审计专家，专注于识别代码中的安全漏洞。
+# 审计范围
+## Critical（必须检查）
+- **SQL 注入**：用户输入是否直接拼接到 SQL 语句中
+- **XSS**：用户输入是否未经转义就渲染到页面
+- **硬编码密钥**：API Key、密码、Token 是否写死在代码中
+- **认证绕过**：是否存在未经验证的接口访问
+- **路径遍历**：文件操作是否使用了用户可控的路径
+## High（重点检查）
+- **不安全的反序列化**
+- **SSRF**：用户可控的 URL 请求
+- **敏感数据泄露**：日志、错误信息中是否暴露了内部信息
+## Medium（常规检查）
+- **CORS 配置**
+- **CSRF 防护**
+- **速率限制**
+- **输入验证不完整**
+# 输出格式
+对每个发现的问题：
+**[严重程度] 问题标题**
+- 文件：`path/to/file.ts:L行号`
+- 风险说明：攻击者可以...
+- 修复建议：...
+# 约束条件
+- ✅ 每个问题必须给出具体文件和行号
+- ✅ 必须给出修复建议
+- ❌ 不要报告理论风险，只报告代码中实际存在的
+```

package/skills/read-docs/references/opencode/agents/design-pattern.md

@@ -0,0 +1,47 @@
+# Agent 设计模式
+
+## 核心原则
+
+### 1. 保持简单
+
+> "最成功的实现使用简单、可组合的模式，而非复杂框架。"
+
+- 能用单个 Agent 解决的，不要用多个
+- 能用固定流程的，不要用动态决策
+- 能用 prompt 解决的，不要加工具
+
+### 2. 透明度优先
+
+> "显式展示 Agent 的规划步骤。"
+
+- Agent 的思考过程应该可见
+- 每个步骤都有明确的输入输出
+- 用户能理解 Agent 在做什么
+
+### 3. 精心设计工具接口（ACI）
+
+> "像设计人机界面（HCI）一样投入精力设计 Agent-计算机界面（ACI）。"
+
+- 工具描述要像给初级开发者写的优秀 docstring
+- 包含使用示例和边界情况
+- 避免需要精确计数或复杂转义的格式
+
+## Workflow vs Agent
+
+| 维度 | Workflow | Agent |
+|------|----------|-------|
+| 执行方式 | 预定义代码路径，步骤固定 | LLM 动态决策，自主探索 |
+| 适用场景 | 任务可预测、结构清晰 | 开放性问题、无法预测步骤 |
+| 实现方式 | Skill、Command | Agent + Task tool |
+
+### 决策树
+
+```
+任务来了
+    ↓
+步骤是否固定？
+    ├─ 是 → 用 Workflow（Skill/Command）
+    └─ 否 → 需要多少自主性？
+              ├─ 低 → 受限 Agent（steps + 权限控制）
+              └─ 高 → 完全自主 Agent
+```

package/skills/read-docs/references/opencode/agents/detail.md

@@ -0,0 +1,191 @@
+# Agent 详解
+
+## 父子 Agent 协作
+
+```
+用户 ←→ Primary Agent (build/plan)
+              ↓
+         Task Tool (创建独立 Session)
+              ↓
+         Subagent (explore/general/你的自定义 Agent)
+              ↓
+         返回结果给 Primary
+```
+
+### 子代理的运行机制
+
+子代理运行在全新、独立的 Session 中：
+
+1. **看不到主 Agent 的对话历史**：不知道之前聊了什么
+2. **上下文仅包含 Prompt**：只有传给它的任务描述
+3. **必须提供完整上下文**：调用时必须把任务所需的所有信息写在 prompt 里
+
+### All 模式的双重身份
+
+当 `mode: "all"` 的 Agent：
+
+1. 被 Tab 切换时：它是主 Agent，拥有完整历史记忆
+2. 被 `@` 调用时：它是子 Agent，受到 Session 隔离限制
+
+## Agent 文件结构
+
+```md
+---
+description: 简短描述这个 Agent 做什么
+mode: subagent
+---
+这里是系统提示词（System Prompt）。
+告诉 Agent 它是谁、擅长什么、如何工作。
+```
+
+## 权限配置
+
+在 Frontmatter 中直接配置权限：
+
+```md
+---
+description: 只读代码审计 Agent
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git log*": allow
+  task:
+    "*": deny
+---
+```
+
+## 系统提示词的工作原理
+
+### 提示词组装顺序
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Agent prompt  或  Provider 默认提示词（二选一）          │
+│     ├─ 有 prompt → 使用你定义的                              │
+│     └─ 无 prompt → 使用模型默认（如 anthropic.txt）          │
+├─────────────────────────────────────────────────────────────┤
+│  2. 环境信息 + 指令文件（始终添加）                          │
+│     工作目录、git 状态、平台、日期                           │
+│     AGENTS.md、CLAUDE.md 等全局规则文件                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+关键点：
+
+- Agent prompt 和 Provider 默认提示词是**二选一**，不是叠加
+- 环境信息和指令文件**始终添加**，无论是否有 Agent prompt
+
+### 场景 1：Agent 有 prompt
+
+```md
+---
+description: 代码审查专家
+mode: subagent
+---
+你是代码审查专家，专注于安全和性能...
+```
+
+发送给模型的提示词：
+
+```
+你是代码审查专家，专注于安全和性能...    ← 你的 prompt（替代默认）
+You are powered by the model named...     ← 环境信息
+Working directory: /path/to/project       ← 环境信息
+...                                       ← AGENTS.md 内容（如有）
+```
+
+### 场景 2：Agent 无 prompt
+
+```md
+---
+description: 通用助手
+mode: subagent
+---
+（正文为空）
+```
+
+发送给模型的提示词：
+
+```
+You are OpenCode, the best coding agent... ← Provider 默认
+You are powered by the model named...       ← 环境信息
+Working directory: /path/to/project         ← 环境信息
+...                                         ← AGENTS.md 内容（如有）
+```
+
+## 混合使用 Markdown 和 JSON
+
+如果同名 Agent 同时存在于 Markdown 和 JSON 配置中：
+
+- **JSON 配置优先级更高**：`opencode.json` 中的字段覆盖 `.md` 中的同名字段
+- **推荐做法**：用 `.md` 定义 Prompt（长文本好写），用 `opencode.json` 微调参数（如临时禁用、修改模型）
+
+### JSON 示例
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "code-reviewer": {
+      "description": "代码审查专家，专注安全、性能、可维护性。",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "temperature": 0.2,
+      "steps": 30,
+      "prompt": "你是代码审查专家。\n\n## 检查要点\n- 安全漏洞\n- 性能问题\n- 代码风格\n- 可维护性"
+    }
+  }
+}
+```
+
+当 prompt 很长时，可引用外部文件：
+
+```json
+{
+  "prompt": "{file:./prompts/code-reviewer.txt}"
+}
+```
+
+## Agent 三大组件设计
+
+### Planning（规划）
+
+| 技术 | 说明 | 适用场景 |
+|------|------|----------|
+| Chain of Thought | "一步步思考" | 通用推理 |
+| Tree of Thoughts | 探索多个推理路径 | 复杂决策 |
+| ReAct | 思考-行动-观察循环 | 需要与环境交互 |
+
+在 Agent Prompt 中应用：
+
+```md
+# 工作方式
+采用 ReAct 模式：
+1. **思考**：分析当前状态，决定下一步
+2. **行动**：执行具体操作（调用工具）
+3. **观察**：分析操作结果
+4. **重复**：直到任务完成
+```
+
+### Memory（记忆）
+
+| 类型 | 存储 | 容量 |
+|------|------|------|
+| 短期记忆 | 上下文窗口 | 有限，约几万 token |
+| 长期记忆 | 外部向量库 | 无限，需要检索 |
+
+OpenCode 中的实现：
+
+- 短期：会话上下文
+- 长期：MCP 集成向量数据库
+
+### Tool Use（工具使用）
+
+设计原则：
+
+1. **描述清晰**：像给初级开发者的 docstring
+2. **输入简单**：避免复杂的格式要求
+3. **输出可解析**：结构化，便于后续处理
+4. **错误友好**：清晰的错误信息

package/skills/read-docs/references/opencode/agents/examples.md

@@ -0,0 +1,100 @@
+# Agent 示例
+
+## 文档写作 Agent
+
+`.opencode/agent/docs-writer.md`
+
+```md
+---
+description: |
+  技术文档写作专家，擅长 API 文档、README、用户手册。
+  适用场景：写新项目文档、更新现有文档、解释代码功能。
+  不适用：代码审查、Bug 修复、功能实现。
+mode: subagent
+temperature: 0.3
+---
+# 角色
+你是技术文档专家，擅长将复杂概念解释得通俗易懂。
+# 文档规范
+- 使用 Markdown 格式
+- 代码示例必须可运行
+- 包含输入/输出说明
+- 中文优先，专业术语保留英文
+# 文档结构
+1. 概述（一句话说明是什么）
+2. 快速开始（30 秒能跑起来）
+3. 详细 API（完整参数说明）
+4. 示例代码（覆盖常见场景）
+5. 常见问题（预判用户疑惑）
+# 约束条件
+- ✅ 快速开始的代码必须可直接复制运行
+- ✅ 参数说明要包含类型和默认值
+- ❌ 避免假设用户已有背景知识
+```
+
+## 自动化代码审查机器人
+
+### 配置
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "pr-reviewer": {
+      "description": "PR 审查机器人，自动审查代码变更",
+      "mode": "primary",
+      "model": "anthropic/claude-opus-4-5-thinking",
+      "steps": 100,
+      "temperature": 0.1,
+      "prompt": "{file:./prompts/pr-reviewer.md}",
+      "permission": {
+        "edit": "deny",
+        "bash": {
+          "*": "deny",
+          "git log*": "allow",
+          "git diff*": "allow",
+          "npm test": "allow"
+        },
+        "task": {
+          "*": "deny",
+          "security-auditor": "allow",
+          "performance-checker": "allow",
+          "style-checker": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+## 多模型协作
+
+```jsonc
+{
+  "agent": {
+    "planner": {
+      "description": "规划者：分析需求，制定计划",
+      "mode": "primary",
+      "model": "anthropic/claude-opus-4-5-thinking",
+      "temperature": 0.2,
+      "steps": 20
+    },
+    "executor": {
+      "description": "执行者：实现具体代码",
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "temperature": 0.3,
+      "steps": 100
+    },
+    "reviewer": {
+      "description": "审查者：检查代码质量",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny"
+      }
+    }
+  }
+}
+```