fix: 任务定位

2026-07-16 15:44:58 +08:00
parent be46cf49c5
commit 1d12732646
65 changed files with 11693 additions and 18 deletions
--- a/.agents/skills/using-superpowers/SKILL.md
+++ b/.agents/skills/using-superpowers/SKILL.md
@@ -0,0 +1,143 @@
+---
+name: using-superpowers
+description: 在开始任何对话时使用——确立如何查找和使用技能，要求在任何响应（包括澄清性问题）之前调用 Skill 工具
+version: "1.0.0"
+license: MIT
+metadata:
+  hermes:
+    tags: [meta, getting-started]
+---
+
+<SUBAGENT-STOP>
+如果你是作为子智能体被分派来执行特定任务的，跳过此技能。
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+如果你认为哪怕只有 1% 的可能性某个技能适用于你正在做的事情，你绝对必须调用该技能。
+
+如果一个技能适用于你的任务，你没有选择。你必须使用它。
+
+这不可协商。这不是可选的。你不能通过合理化来逃避。
+</EXTREMELY-IMPORTANT>
+
+## 指令优先级
+
+Superpowers 技能覆盖默认系统提示行为，但**用户指令始终具有最高优先级**：
+
+1. **用户的明确指令**（AGENTS.md、GEMINI.md、AGENTS.md、直接请求）——最高优先级
+2. **Superpowers 技能** ——在冲突处覆盖默认系统行为
+3. **默认系统提示** ——最低优先级
+
+如果 AGENTS.md、GEMINI.md 或 AGENTS.md 说"不要使用 TDD"，而某个技能说"始终使用 TDD"，遵循用户的指令。用户拥有控制权。
+
+## 如何访问技能
+
+**在 Codex 中：** 使用 `Skill` 工具。当你调用一个技能时，其内容会被加载并呈现给你——直接遵循即可。绝不要用 Read 工具读取技能文件。
+
+**在 Copilot CLI 中：** 使用 `skill` 工具。技能从已安装的插件中自动发现。`skill` 工具的工作方式与 Codex 的 `Skill` 工具相同。
+
+**在 Hermes Agent 中：** 使用 `skill_view` 工具加载技能。Hermes 支持三级渐进式加载：`skills_list` 浏览 → `skill_view(name)` 加载完整内容 → `skill_view(name, path)` 查看引用文件。
+
+**在 Gemini CLI 中：** 技能通过 `activate_skill` 工具激活。Gemini 在会话开始时加载技能元数据，并按需激活完整内容。
+
+**在其他环境中：** 查看你的平台文档了解技能的加载方式。
+
+## 平台适配
+
+技能使用 Codex 的工具名称。非 CC 平台：查看 `references/copilot-tools.md`（Copilot CLI）、`references/hermes-tools.md`（Hermes Agent）、`references/codex-tools.md`（Codex）、`references/qoder-tools.md`（Qoder）了解工具对应关系。Gemini CLI 用户通过 GEMINI.md 自动获得工具映射。
+
+# 使用技能
+
+## 规则
+
+**在任何响应或操作之前调用相关或被请求的技能。** 哪怕只有 1% 的可能性某个技能适用，你都应该调用该技能来检查。如果调用后发现技能不适合当前情况，你不需要使用它。
+
+```dot
+digraph skill_flow {
+    "收到用户消息" [shape=doublecircle];
+    "即将进入 EnterPlanMode？" [shape=doublecircle];
+    "已经头脑风暴过？" [shape=diamond];
+    "调用头脑风暴技能" [shape=box];
+    "可能有技能适用？" [shape=diamond];
+    "调用 Skill 工具" [shape=box];
+    "宣布：'使用 [技能] 来 [目的]'" [shape=box];
+    "有检查清单？" [shape=diamond];
+    "为每个条目创建 TodoWrite 待办" [shape=box];
+    "严格遵循技能" [shape=box];
+    "响应（包括澄清）" [shape=doublecircle];
+
+    "即将进入 EnterPlanMode？" -> "已经头脑风暴过？";
+    "已经头脑风暴过？" -> "调用头脑风暴技能" [label="否"];
+    "已经头脑风暴过？" -> "可能有技能适用？" [label="是"];
+    "调用头脑风暴技能" -> "可能有技能适用？";
+
+    "收到用户消息" -> "可能有技能适用？";
+    "可能有技能适用？" -> "调用 Skill 工具" [label="是，哪怕只有 1%"];
+    "可能有技能适用？" -> "响应（包括澄清）" [label="确定不适用"];
+    "调用 Skill 工具" -> "宣布：'使用 [技能] 来 [目的]'";
+    "宣布：'使用 [技能] 来 [目的]'" -> "有检查清单？";
+    "有检查清单？" -> "为每个条目创建 TodoWrite 待办" [label="是"];
+    "有检查清单？" -> "严格遵循技能" [label="否"];
+    "为每个条目创建 TodoWrite 待办" -> "严格遵循技能";
+}
+```
+
+## 红线
+
+这些想法意味着停下——你在合理化：
+
+| 想法 | 现实 |
+|------|------|
+| "这只是一个简单的问题" | 问题就是任务。检查技能。 |
+| "我需要先了解更多上下文" | 技能检查在澄清性问题之前。 |
+| "让我先探索一下代码库" | 技能告诉你如何探索。先检查。 |
+| "我可以快速查一下 git/文件" | 文件缺少对话上下文。检查技能。 |
+| "让我先收集信息" | 技能告诉你如何收集信息。 |
+| "这不需要正式的技能" | 如果技能存在，就使用它。 |
+| "我记得这个技能" | 技能会迭代更新。阅读当前版本。 |
+| "这不算一个任务" | 行动 = 任务。检查技能。 |
+| "技能太小题大做了" | 简单的事会变复杂。使用它。 |
+| "让我先做这一件事" | 在做任何事之前先检查。 |
+| "这样做感觉很高效" | 无纪律的行动浪费时间。技能防止这一点。 |
+| "我知道那是什么意思" | 知道概念 ≠ 使用技能。调用它。 |
+
+## 技能优先级
+
+当多个技能可能适用时，使用此顺序：
+
+1. **流程技能优先**（头脑风暴、调试）- 这些决定如何处理任务
+2. **实现技能其次**（前端设计、mcp-builder）- 这些指导执行
+
+"让我们构建 X" → 先头脑风暴，再使用实现技能。
+"修复这个 bug" → 先调试，再使用领域特定技能。
+
+## 中国特色技能路由
+
+当检测到以下场景时，**必须**优先调用对应的中国特色技能：
+
+| 场景 | 调用技能 |
+|------|---------|
+| 代码审查且团队使用中文沟通 | **superpowers:chinese-code-review** |
+| 使用 Gitee/Coding/极狐 GitLab | **superpowers:chinese-git-workflow** |
+| 编写中文技术文档或 README | **superpowers:chinese-documentation** |
+| 编写 git commit message（中文项目） | **superpowers:chinese-commit-conventions** |
+| 构建 MCP 服务器/工具 | **superpowers:mcp-builder** |
+
+**判断依据：**
+- 项目中有中文注释、中文 README、或 .gitee 目录 → 启用中文系列技能
+- commit 历史中有中文 → 使用中文提交规范
+- 用户用中文交流 → 所有输出使用中文，优先考虑中国特色技能
+
+中国特色技能与翻译技能**叠加使用**，不互斥。例如：做代码审查时，同时使用 requesting-code-review（流程）+ chinese-code-review（风格）。
+
+## 技能类型
+
+**刚性的**（TDD、调试）：严格遵循。不要偏离纪律。
+
+**灵活的**（模式）：根据上下文调整原则。
+
+技能本身会告诉你它属于哪种。
+
+## 用户指令
+
+指令说明做什么，而非怎么做。"添加 X"或"修复 Y"不意味着跳过工作流。
--- a/.agents/skills/using-superpowers/references/codex-tools.md
+++ b/.agents/skills/using-superpowers/references/codex-tools.md
@@ -0,0 +1,25 @@
+# Codex 工具映射
+
+Skills 使用 Claude Code 的工具名称。在 Codex 中遇到这些名称时，请使用对应的平台等价工具：
+
+| Skill 中的引用 | Codex 等价工具 |
+|---------------|---------------|
+| `Task` 工具（派遣子 agent） | `spawn_agent` |
+| 多个 `Task` 调用（并行） | 多个 `spawn_agent` 调用 |
+| Task 返回结果 | `wait` |
+| Task 自动完成 | `close_agent` 释放槽位 |
+| `TodoWrite`（任务跟踪） | `update_plan` |
+| `Skill` 工具（调用 skill） | Skills 原生加载——直接按说明操作 |
+| `Read`、`Write`、`Edit`（文件） | 使用原生文件工具 |
+| `Bash`（执行命令） | 使用原生 shell 工具 |
+
+## 子 Agent 派遣需要多 Agent 支持
+
+在 Codex 配置文件（`~/.codex/config.toml`）中添加：
+
+```toml
+[features]
+multi_agent = true
+```
+
+启用后可使用 `spawn_agent`、`wait` 和 `close_agent`，支持 `dispatching-parallel-agents` 和 `subagent-driven-development` 等 skills。
--- a/.agents/skills/using-superpowers/references/copilot-tools.md
+++ b/.agents/skills/using-superpowers/references/copilot-tools.md
@@ -0,0 +1,52 @@
+# Copilot CLI 工具映射
+
+技能使用 Claude Code 的工具名称。当你在技能中遇到这些工具时，使用你平台的等价工具：
+
+| 技能中引用的工具 | Copilot CLI 等价工具 |
+|-----------------|----------------------|
+| `Read`（读取文件） | `view` |
+| `Write`（创建文件） | `create` |
+| `Edit`（编辑文件） | `edit` |
+| `Bash`（运行命令） | `bash` |
+| `Grep`（搜索文件内容） | `grep` |
+| `Glob`（按名称搜索文件） | `glob` |
+| `Skill` 工具（调用技能） | `skill` |
+| `WebFetch` | `web_fetch` |
+| `Task` 工具（分派子智能体） | `task`（参见[智能体类型](#智能体类型)） |
+| 多个 `Task` 调用（并行） | 多个 `task` 调用 |
+| Task 状态/输出 | `read_agent`、`list_agents` |
+| `TodoWrite`（任务跟踪） | `sql` 配合内置 `todos` 表 |
+| `WebSearch` | 无等价工具 — 使用 `web_fetch` 配合搜索引擎 URL |
+| `EnterPlanMode` / `ExitPlanMode` | 无等价工具 — 留在主会话中 |
+
+## 智能体类型
+
+Copilot CLI 的 `task` 工具接受 `agent_type` 参数：
+
+| Claude Code 智能体 | Copilot CLI 等价 |
+|-------------------|----------------------|
+| `general-purpose` | `"general-purpose"` |
+| `Explore` | `"explore"` |
+| 命名的插件智能体（如 `superpowers:code-reviewer`） | 从已安装的插件中自动发现 |
+
+## 异步 Shell 会话
+
+Copilot CLI 支持持久化的异步 shell 会话，这在 Claude Code 中没有直接等价物：
+
+| 工具 | 用途 |
+|------|---------|
+| `bash` 配合 `async: true` | 在后台启动长时间运行的命令 |
+| `write_bash` | 向运行中的异步会话发送输入 |
+| `read_bash` | 读取异步会话的输出 |
+| `stop_bash` | 终止异步会话 |
+| `list_bash` | 列出所有活跃的 shell 会话 |
+
+## 额外的 Copilot CLI 工具
+
+| 工具 | 用途 |
+|------|---------|
+| `store_memory` | 持久化代码库相关事实供未来会话使用 |
+| `report_intent` | 更新 UI 状态行显示当前意图 |
+| `sql` | 查询会话的 SQLite 数据库（待办、元数据） |
+| `fetch_copilot_cli_documentation` | 查阅 Copilot CLI 文档 |
+| GitHub MCP 工具（`github-mcp-server-*`） | 原生 GitHub API 访问（issue、PR、代码搜索） |
--- a/.agents/skills/using-superpowers/references/gemini-tools.md
+++ b/.agents/skills/using-superpowers/references/gemini-tools.md
@@ -0,0 +1,33 @@
+# Gemini CLI 工具映射
+
+Skills 使用 Claude Code 的工具名称。在 Gemini CLI 中遇到这些名称时，请使用对应的平台等价工具：
+
+| Skill 中的引用 | Gemini CLI 等价工具 |
+|---------------|-------------------|
+| `Read`（读取文件） | `read_file` |
+| `Write`（创建文件） | `write_file` |
+| `Edit`（编辑文件） | `replace` |
+| `Bash`（执行命令） | `run_shell_command` |
+| `Grep`（搜索文件内容） | `grep_search` |
+| `Glob`（按名称搜索文件） | `glob` |
+| `TodoWrite`（任务跟踪） | `write_todos` |
+| `Skill` 工具（调用 skill） | `activate_skill` |
+| `WebSearch` | `google_web_search` |
+| `WebFetch` | `web_fetch` |
+| `Task` 工具（派遣子 agent） | 无等价工具——Gemini CLI 不支持子 agent |
+
+## 不支持子 Agent
+
+Gemini CLI 没有 Claude Code `Task` 工具的等价物。依赖子 agent 派遣的 skills（`subagent-driven-development`、`dispatching-parallel-agents`）将退化为通过 `executing-plans` 进行单会话执行。
+
+## Gemini CLI 额外工具
+
+以下工具在 Gemini CLI 中可用，但 Claude Code 中没有对应工具：
+
+| 工具 | 用途 |
+|------|------|
+| `list_directory` | 列出文件和子目录 |
+| `save_memory` | 将信息持久化到 GEMINI.md，跨会话保留 |
+| `ask_user` | 向用户请求结构化输入 |
+| `tracker_create_task` | 丰富的任务管理（创建、更新、列表、可视化） |
+| `enter_plan_mode` / `exit_plan_mode` | 切换到只读研究模式，在修改前先调研 |
--- a/.agents/skills/using-superpowers/references/hermes-tools.md
+++ b/.agents/skills/using-superpowers/references/hermes-tools.md
@@ -0,0 +1,44 @@
+# Hermes Agent 工具映射
+
+技能使用 Claude Code 的工具名称。当你在技能中遇到这些工具时，使用你平台的等价工具：
+
+| 技能中引用的工具 | Hermes Agent 等价工具 |
+|-----------------|----------------------|
+| `Read`（读取文件） | `read_file` |
+| `Write`（创建文件） | `write_file` |
+| `Edit`（编辑文件） | `patch` |
+| `Bash`（运行命令） | `terminal` |
+| `Grep`（搜索文件内容） | `search_files` |
+| `Glob`（按名称搜索文件） | `search_files` |
+| `Skill` 工具（调用技能） | `skill_view` |
+| `WebFetch` | `web_extract` |
+| `WebSearch` | `web_search` |
+| `Task` 工具（分派子智能体） | `delegate_task` |
+| 多个 `Task` 调用（并行） | 多个 `delegate_task` 调用 |
+| `TodoWrite`（任务跟踪） | `todo` |
+| `EnterPlanMode` / `ExitPlanMode` | 无等价工具 — 留在主会话中 |
+
+## 技能管理
+
+Hermes Agent 使用三级渐进式技能加载：
+
+| 操作 | 工具 |
+|------|------|
+| 列出所有可用技能 | `skills_list` |
+| 查看技能完整内容 | `skill_view(name)` |
+| 查看技能的引用文件 | `skill_view(name, path)` |
+| 管理技能（安装/更新） | `skill_manage` |
+
+## 额外的 Hermes Agent 工具
+
+| 工具 | 用途 |
+|------|---------|
+| `memory` | 持久化知识供未来会话使用 |
+| `session_search` | 搜索历史会话记录 |
+| `execute_code` | 在沙箱中执行代码 |
+| `process` | 后台进程管理 |
+| `vision_analyze` | 图像分析 |
+| `image_generate` | 图像生成 |
+| `clarify` | 向用户提出澄清性问题 |
+| `browser_*` | 浏览器自动化工具集 |
+| `mixture_of_agents` | 多智能体高级推理 |
--- a/.agents/skills/using-superpowers/references/pi-tools.md
+++ b/.agents/skills/using-superpowers/references/pi-tools.md
@@ -0,0 +1,28 @@
+# Pi Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below.
+
+| Action skills request | Pi equivalent |
+| --- | --- |
+| Invoke a skill | Pi native skills: load the relevant `SKILL.md` with `read`, or let the human use `/skill:name` |
+| Read a file | `read` |
+| Create a file | `write` |
+| Edit a file | `edit` |
+| Run a shell command | `bash` |
+| Search file contents | `grep` when active; otherwise `bash` with `rg`/`grep` |
+| Find files by name | `find` or `bash` with shell globs |
+| List files and subdirectories | `ls` when active; otherwise `bash` with `ls` |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | Use an installed subagent tool such as `subagent` from `pi-subagents` if available |
+| Task tracking ("create a todo", "mark complete") | Use an installed todo/task tool if available, otherwise track tasks in the plan or `TODO.md` |
+
+## Skills
+
+Pi discovers skills from configured skill directories and installed Pi packages. A Superpowers Pi package should expose `skills/` through its `pi.skills` manifest entry. Pi does not expose Claude Code's `Skill` tool, but the agent should still follow the Superpowers rule: when a skill applies, load and follow it before responding.
+
+## Subagents
+
+Pi core does not ship a standard subagent tool. The `pi-subagents` package is a strong optional companion and provides a `subagent` tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate `Task` calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.
+
+## Task lists
+
+Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Superpowers plan files, checklists in Markdown, or a repo-local `TODO.md` for task tracking. Older Superpowers docs may refer to `TodoWrite`; treat that as the task-tracking action above.
--- a/.agents/skills/using-superpowers/references/qoder-tools.md
+++ b/.agents/skills/using-superpowers/references/qoder-tools.md
@@ -0,0 +1,43 @@
+# Qoder 工具映射
+
+Skills 使用 Claude Code 的工具名称。Qoder（阿里 AI IDE）大部分工具与 Claude Code **同名**，只有少数差异：
+
+| Skill 中的引用 | Qoder 等价工具 |
+|---------------|---------------|
+| `Read` / `Write` / `Edit` | 同名（`Read` / `Write` / `Edit`） |
+| `Bash` | 同名 |
+| `Grep` / `Glob` | 同名 |
+| `Task`（派遣子 agent） | 同名（`Task`） |
+| `WebFetch` / `WebSearch` | 同名 |
+| `AskUserQuestion` | 同名 |
+| `Skill` | 同名 |
+| `TodoWrite` | 同名 |
+| `EnterPlanMode` / `ExitPlanMode` | **`EnterSpecMode` / `ExitSpecMode`**（Qoder 把"计划模式"称为"Spec 模式"）|
+
+## Task 子 Agent 类型
+
+| Claude Code Agent | Qoder 等价 |
+|------------------|-----------|
+| `general-purpose` | `general-purpose` |
+| `Explore` | `explore-agent` |
+| `Plan` | `plan-agent` |
+| `claude-code-guide` | `qoder-guide` |
+
+Qoder 额外有 `browser-agent`、`code-reviewer`、`design-agent` 等专用 agent，依任务匹配选用。
+
+## Quest MCP 工具（Qoder 原生）
+
+Qoder 内置 Quest 系统提供以下工具，Claude Code 没有等价物，可在 skill 流程中直接调用：
+
+| 工具 | 用途 |
+|------|------|
+| `mcp__quest__search_codebase` | 语义化代码搜索（按意图找代码） |
+| `mcp__quest__search_symbol` | 按符号名搜索代码及关系 |
+| `mcp__quest__get_problems` | 获取文件编译/语法错误 |
+| `mcp__quest__run_preview` | 启动本地 Web 服务器预览 |
+| `mcp__quest__search_memory` / `update_memory` | 跨会话记忆管理 |
+| `mcp__quest__fetch_rules` | 查询规则文件 |
+
+## 加载方式
+
+Qoder 在每个会话自动加载 `.qoder/rules/superpowers-zh.md`（`trigger: always_on`），里面包含 skill 索引。`.qoder/skills/<name>/SKILL.md` 由模型按 description 自主调用，也可输入 `/<skill-name>` 手动触发。