From 3242ed461fdab0a16ec0e78405a2c7e7e52af39f Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Mon, 11 May 2026 14:09:27 -0400 Subject: [PATCH] docs: salvage zh-CN core skill translations --- .../skills/automation-audit-ops/SKILL.md | 142 ++++ docs/zh-CN/skills/click-path-audit/SKILL.md | 257 +++++++ docs/zh-CN/skills/code-tour/SKILL.md | 244 ++++++ .../skills/ecc-tools-cost-audit/SKILL.md | 160 ++++ docs/zh-CN/skills/gateguard/SKILL.md | 123 +++ docs/zh-CN/skills/git-workflow/SKILL.md | 720 ++++++++++++++++++ docs/zh-CN/skills/github-ops/SKILL.md | 145 ++++ docs/zh-CN/skills/hookify-rules/SKILL.md | 139 ++++ docs/zh-CN/skills/jira-integration/SKILL.md | 302 ++++++++ docs/zh-CN/skills/knowledge-ops/SKILL.md | 177 +++++ docs/zh-CN/skills/project-flow-ops/SKILL.md | 111 +++ docs/zh-CN/skills/repo-scan/SKILL.md | 79 ++ docs/zh-CN/skills/research-ops/SKILL.md | 112 +++ docs/zh-CN/skills/terminal-ops/SKILL.md | 109 +++ .../skills/workspace-surface-audit/SKILL.md | 125 +++ 15 files changed, 2945 insertions(+) create mode 100644 docs/zh-CN/skills/automation-audit-ops/SKILL.md create mode 100644 docs/zh-CN/skills/click-path-audit/SKILL.md create mode 100644 docs/zh-CN/skills/code-tour/SKILL.md create mode 100644 docs/zh-CN/skills/ecc-tools-cost-audit/SKILL.md create mode 100644 docs/zh-CN/skills/gateguard/SKILL.md create mode 100644 docs/zh-CN/skills/git-workflow/SKILL.md create mode 100644 docs/zh-CN/skills/github-ops/SKILL.md create mode 100644 docs/zh-CN/skills/hookify-rules/SKILL.md create mode 100644 docs/zh-CN/skills/jira-integration/SKILL.md create mode 100644 docs/zh-CN/skills/knowledge-ops/SKILL.md create mode 100644 docs/zh-CN/skills/project-flow-ops/SKILL.md create mode 100644 docs/zh-CN/skills/repo-scan/SKILL.md create mode 100644 docs/zh-CN/skills/research-ops/SKILL.md create mode 100644 docs/zh-CN/skills/terminal-ops/SKILL.md create mode 100644 docs/zh-CN/skills/workspace-surface-audit/SKILL.md diff --git a/docs/zh-CN/skills/automation-audit-ops/SKILL.md b/docs/zh-CN/skills/automation-audit-ops/SKILL.md new file mode 100644 index 00000000..9e7787d3 --- /dev/null +++ b/docs/zh-CN/skills/automation-audit-ops/SKILL.md @@ -0,0 +1,142 @@ +--- +name: automation-audit-ops +description: 面向ECC的以证据为先的自动化清单与重叠审计工作流。当用户希望在修复任何内容之前了解哪些作业、钩子、连接器、MCP服务器或包装器是活跃的、损坏的、冗余的或缺失时使用。 +origin: ECC +--- + +# 自动化审计运维 + +当用户询问哪些自动化正在运行、哪些任务出现故障、哪里存在重叠，或者哪些工具和连接器当前正在实际发挥作用时，请使用此技能。 + +这是一项以审计为先的操作技能。其任务是在重写任何内容之前，生成一份有证据支持的清单以及一套保留/合并/删除/下一步修复的建议集。 + +## 技能栈 + +在相关时，将这些 ECC 原生技能引入工作流程： + +* `workspace-surface-audit` 用于连接器、MCP、钩子和应用清单 +* `knowledge-ops` 当审计需要将实时仓库的真实情况与持久上下文进行核对时 +* `github-ops` 当答案依赖于 CI、计划工作流、议题或 PR 自动化时 +* `ecc-tools-cost-audit` 当真正的问题是兄弟应用仓库中的 webhook 扇出、队列任务或计费消耗时 +* `research-ops` 当需要将本地清单与当前平台支持或公开文档进行比较时 +* `verification-loop` 用于证明修复后的状态，而不是依赖假设的恢复 + +## 使用时机 + +* 用户询问"我有哪些自动化"、"什么在运行"、"什么出故障了"或"什么重叠了" +* 任务涉及 cron 任务、GitHub Actions、本地钩子、MCP 服务器、连接器、包装器或应用集成 +* 用户想知道从其他代理系统移植了什么，以及哪些还需要在 ECC 内部重建 +* 工作区积累了多种执行同一任务的方式，用户希望有一条规范的路径 + +## 防护栏 + +* 除非用户明确要求修复，否则以只读方式开始 +* 区分： + * 已配置 + * 已验证身份 + * 最近已验证 + * 过时或损坏 + * 完全缺失 +* 不要仅仅因为某个技能或配置引用了某个工具，就声称该工具正在运行 +* 在证据表存在之前，不要合并或删除重叠的表面 + +## 工作流程 + +### 1. 盘点真实表面 + +在理论化之前，先读取当前的实时表面： + +* 仓库钩子和本地钩子脚本 +* GitHub Actions 和计划工作流 +* MCP 配置和已启用的服务器 +* 基于连接器或应用的集成 +* 包装器脚本和特定仓库的自动化入口点 + +按表面分组： + +* 本地运行时 +* 仓库 CI / 自动化 +* 连接的外部系统 +* 消息传递 / 通知 +* 计费 / 客户运营 +* 研究 / 监控 + +### 2. 按实时状态对每个项目进行分类 + +对于每个发现的自动化，标记： + +* 已配置 +* 已验证身份 +* 最近已验证 +* 过时或损坏 +* 缺失 + +然后对问题类型进行分类： + +* 活动故障 +* 身份验证中断 +* 状态过时 +* 重叠或冗余 +* 功能缺失 + +### 3. 追溯证据路径 + +为每个重要声明提供具体来源： + +* 文件路径 +* 工作流运行 +* 钩子日志 +* 配置条目 +* 最近的命令输出 +* 确切的故障特征 + +如果当前状态不明确，请直接说明，而不是假装审计已完成。 + +### 4. 以保留 / 合并 / 删除 / 下一步修复结束 + +对于每个重叠或可疑的表面，返回一个决策： + +* 保留 +* 合并 +* 删除 +* 下一步修复 + +其价值在于将杂乱的自动化整合到一条规范的 ECC 路径中，而不是保留每一条历史路径。 + +## 输出格式 + +```text +当前表面 +- 自动化 +- 来源 +- 实时状态 +- 证据 + +发现 +- 活跃故障 +- 重叠 +- 过时状态 +- 缺失能力 + +建议 +- 保留 +- 合并 +- 删除 +- 下次修复 + +下一步ECC行动 +- 需加强的具体技能/钩子/工作流/应用通道 +``` + +## 常见陷阱 + +* 当可以读取实时清单时，不要凭记忆回答 +* 不要将"配置中存在"视为"正在工作" +* 在指出故障的高信号路径之前，不要修复低价值的冗余 +* 如果用户首先要求的是清单，不要将任务扩大为仓库重写 + +## 验证 + +* 重要声明需引用实时证据路径 +* 每个发现的自动化都需标有清晰的实时状态类别 +* 最终建议需区分保留 / 合并 / 删除 / 下一步修复 diff --git a/docs/zh-CN/skills/click-path-audit/SKILL.md b/docs/zh-CN/skills/click-path-audit/SKILL.md new file mode 100644 index 00000000..a7ceba3f --- /dev/null +++ b/docs/zh-CN/skills/click-path-audit/SKILL.md @@ -0,0 +1,257 @@ +--- +name: click-path-audit +description: "追踪每个面向用户的按钮/触点的完整状态变化序列，以发现功能单独工作但相互抵消、产生错误最终状态或使UI处于不一致状态的错误。适用于：系统调试未发现错误但用户报告按钮失效，或在任何涉及共享状态存储的重大重构之后。" +origin: community +--- + +# /click-path-audit — 行为流审计 + +发现静态代码审查遗漏的缺陷：状态交互副作用、顺序调用间的竞态条件，以及相互静默撤销的处理程序。 + +## 解决的问题 + +传统调试检查： + +* 函数是否存在？（缺少连接） +* 是否崩溃？（运行时错误） +* 是否返回正确类型？（数据流） + +但未检查： + +* **最终 UI 状态是否与按钮标签承诺一致？** +* **函数 B 是否静默撤销了函数 A 刚刚执行的操作？** +* **共享状态（Zustand/Redux/context）是否存在抵消预期操作的副作用？** + +真实案例：一个"新邮件"按钮依次调用了 `setComposeMode(true)` 和 `selectThread(null)`。两者单独工作正常。但 `selectThread` 有一个副作用重置了 `composeMode: false`。按钮毫无反应。系统化调试发现了 54 个缺陷——这个被遗漏了。 + +*** + +## 工作原理 + +针对目标区域内的每个交互触点： + +``` +1. 识别处理函数（onClick、onSubmit、onChange 等） +2. 按顺序追踪处理函数中的每个函数调用 +3. 对于每个函数调用： + a. 它读取了哪些状态？ + b. 它写入了哪些状态？ + c. 它是否对共享状态产生了副作用？ + d. 它是否作为副作用重置/清除了任何状态？ +4. 检查：后续调用是否会撤销前面调用的状态变更？ +5. 检查：最终状态是否符合用户对按钮标签的预期？ +6. 检查：是否存在竞态条件（异步调用以错误顺序解析）？ +``` + +*** + +## 执行步骤 + +### 步骤 1：映射状态存储 + +在审计任何触点之前，构建每个状态存储操作的副作用映射： + +``` +对于作用域内的每个 Zustand 存储 / React 上下文： + 对于每个操作/设置器： + - 它设置了哪些字段？ + - 它是否作为副作用重置了其他字段？ + - 文档：actionName → {sets: [...], resets: [...]} +``` + +这是关键参考。"新邮件"缺陷在不知道 `selectThread` 重置了 `composeMode` 的情况下是不可见的。 + +**输出格式：** + +``` +STORE: emailStore + setComposeMode(bool) → 设置: {composeMode} + selectThread(thread|null) → 设置: {selectedThread, selectedThreadId, messages, drafts, selectedDraft, summary} 重置: {composeMode: false, composeData: null, redraftOpen: false} + setDraftGenerating(bool) → 设置: {draftGenerating} + ... + +危险的重置（清除不属于自身状态的操作）： + selectThread → 重置 composeMode（由 setComposeMode 拥有） + reset → 重置所有内容 +``` + +### 步骤 2：审计每个触点 + +针对目标区域内的每个按钮/开关/表单提交： + +``` +TOUCHPOINT: [按钮标签] 在 [组件:行] + HANDLER: onClick → { + 调用 1: functionA() → 设置 {X: true} + 调用 2: functionB() → 设置 {Y: null} 重置 {X: false} ← 冲突 + } + EXPECTED: 用户看到 [按钮标签所承诺的描述] + ACTUAL: X 为 false，因为 functionB 重置了它 + VERDICT: BUG — [描述] +``` + +**检查以下每种缺陷模式：** + +#### 模式 1：顺序撤销 + +``` +handler() { + setState_A(true) // 设置 X = true + setState_B(null) // 副作用：重置 X = false +} +// 结果：X 为 false。第一次调用毫无意义。 +``` + +#### 模式 2：异步竞态 + +``` +handler() { + fetchA().then(() => setState({ loading: false })) + fetchB().then(() => setState({ loading: true })) +} +// 结果：最终的 loading 状态取决于哪个先完成 +``` + +#### 模式 3：过期闭包 + +``` +const [count, setCount] = useState(0) +const handler = useCallback(() => { + setCount(count + 1) // 捕获了过时的 count + setCount(count + 1) // 同样的过时 count — 只增加 1，而不是 2 +}, [count]) +``` + +#### 模式 4：缺失状态转换 + +``` +// 按钮显示"保存"，但处理程序仅验证，从未实际保存 +// 按钮显示"删除"，但处理程序设置了一个标志而未调用API +// 按钮显示"发送"，但API端点已被移除/损坏 +``` + +#### 模式 5：条件死路径 + +``` +handler() { + if (someState) { // 此时 someState 始终为 false + doTheActualThing() // 永远不会执行到 + } +} +``` + +#### 模式 6：useEffect 干扰 + +``` +// Button 设置 stateX = true +// useEffect 监听 stateX 并将其重置为 false +// 用户看不到任何变化 +``` + +### 步骤 3：报告 + +针对发现的每个缺陷： + +``` +CLICK-PATH-NNN: [严重性: 严重/高/中/低] + 触点: [按钮标签] 位于 [文件:行号] + 模式: [顺序撤销 / 异步竞态 / 过期闭包 / 缺失过渡 / 死路径 / useEffect 干扰] + 处理函数: [函数名或内联] + 追踪: + 1. [调用] → 设置 {字段: 值} + 2. [调用] → 重置 {字段: 值} ← 冲突 + 预期: [用户期望的结果] + 实际: [实际发生的结果] + 修复: [具体修复方案] +``` + +*** + +## 范围控制 + +此审计成本较高。请适当限定范围： + +* **全应用审计：** 在发布或重大重构后使用。按页面启动并行代理。 +* **单页面审计：** 在构建新页面或用户报告按钮失效后使用。 +* **存储聚焦审计：** 在修改 Zustand 存储后使用——审计所有使用已更改操作的消费者。 + +### 全应用推荐的代理拆分： + +``` +Agent 1：映射所有状态存储（步骤 1）——这是所有其他代理的共享上下文 +Agent 2：仪表盘（任务、笔记、日志、想法） +Agent 3：聊天（DanteChatColumn、JustChatPage） +Agent 4：邮件（ThreadList、DraftArea、EmailsPage） +Agent 5：项目（ProjectsPage、ProjectOverviewTab、NewProjectWizard） +Agent 6：CRM（所有子标签页） +Agent 7：个人资料、设置、保险库、通知 +Agent 8：管理套件（所有页面） +``` + +代理 1 必须首先完成。其输出是所有其他代理的输入。 + +*** + +## 何时使用 + +* 系统化调试发现"无缺陷"但用户报告 UI 失效后 +* 修改任何 Zustand 存储操作后（检查所有调用者） +* 任何涉及共享状态的重构后 +* 发布前，针对关键用户流程 +* 当按钮"无反应"时——这是解决该问题的工具 + +## 何时不使用 + +* 针对 API 级别缺陷（错误的响应结构、缺失端点）——使用系统化调试 +* 针对样式/布局问题——视觉检查 +* 针对性能问题——性能分析工具 + +*** + +## 与其他技能的集成 + +* 在 `/superpowers:systematic-debugging`（发现其他 54 种缺陷类型）之后运行 +* 在 `/superpowers:verification-before-completion`（验证修复是否有效）之前运行 +* 反馈至 `/superpowers:test-driven-development`——此处发现的每个缺陷都应添加测试 + +*** + +## 示例：启发此技能的缺陷 + +**ThreadList.tsx "新邮件"按钮：** + +``` +onClick={() => { + useEmailStore.getState().setComposeMode(true) // ✓ 设置 composeMode = true + useEmailStore.getState().selectThread(null) // ✗ 重置 composeMode = false +}} +``` + +存储定义： + +``` +selectThread: (thread) => set({ + selectedThread: thread, + selectedThreadId: thread?.id ?? null, + messages: [], + drafts: [], + selectedDraft: null, + summary: null, + composeMode: false, // ← 这个静默重置导致按钮失效 + composeData: null, + redraftOpen: false, +}) +``` + +**系统化调试遗漏了它**，因为： + +* 按钮有 onClick 处理程序（未失效） +* 两个函数都存在（无缺失连接） +* 两个函数均未崩溃（无运行时错误） +* 数据类型正确（无类型不匹配） + +**点击路径审计捕获了它**，因为： + +* 步骤 1 映射出 `selectThread` 重置了 `composeMode` +* 步骤 2 追踪处理程序：调用 1 设置为 true，调用 2 重置为 false +* 判定：顺序撤销——最终状态与按钮意图矛盾 diff --git a/docs/zh-CN/skills/code-tour/SKILL.md b/docs/zh-CN/skills/code-tour/SKILL.md new file mode 100644 index 00000000..70ac08b2 --- /dev/null +++ b/docs/zh-CN/skills/code-tour/SKILL.md @@ -0,0 +1,244 @@ +--- +name: code-tour +description: 创建 CodeTour `.tour` 文件——针对特定角色的、带有真实文件和行锚点的逐步演练。用于入职引导、架构演练、PR 演练、RCA 演练以及结构化的“解释其工作原理”请求。 +origin: ECC +--- + +# 代码导览 + +创建 **CodeTour** `.tour` 文件，用于代码库导览，可直接打开真实文件并定位到指定行范围。导览文件存放在 `.tours/` 目录中，专为 CodeTour 格式设计，而非临时性的 Markdown 笔记。 + +一个好的导览应针对特定读者讲述一个故事： + +* 他们正在查看什么 +* 为什么重要 +* 接下来应该遵循什么路径 + +仅创建 `.tour` JSON 文件。不要在此技能范围内修改源代码。 + +## 何时使用 + +在以下情况下使用此技能： + +* 用户请求代码导览、入职导览、架构导览或 PR 导览 +* 用户说“解释 X 如何工作”，并希望获得可重用的引导式产物 +* 用户希望为新工程师或审阅者提供上手路径 +* 相比平铺直叙的摘要，引导式序列更适合该任务 + +示例： + +* 新维护者入职 +* 单个服务或包的架构导览 +* 锚定到变更文件的 PR 审查导览 +* 展示故障路径的根本原因分析导览 +* 信任边界和关键检查的安全审查导览 + +## 何时不使用 + +| 不使用代码导览的情况 | 使用 | +| --- | --- | +| 在聊天中一次性解释就足够了 | 直接回答 | +| 用户想要散文式文档，而不是 `.tour` 产物 | `documentation-lookup` 或仓库文档编辑 | +| 任务是实现或重构 | 执行实现工作 | +| 任务是没有导览产物的广泛代码库入职 | `codebase-onboarding` | + +## 工作流程 + +### 1. 探索 + +在编写任何内容之前探索仓库： + +* README 和包/应用入口点 +* 文件夹结构 +* 相关配置文件 +* 如果导览聚焦于 PR，则查看变更的文件 + +在理解代码结构之前，不要开始编写步骤。 + +### 2. 推断读者 + +根据请求确定角色和深度。 + +| 请求形式 | 角色 | 建议深度 | +| --- | --- | --- | +| "入职"，"新成员" | `new-joiner` | 9-13 步 | +| "快速导览"，"快速了解" | `vibecoder` | 5-8 步 | +| "架构" | `architect` | 14-18 步 | +| "导览此 PR" | `pr-reviewer` | 7-11 步 | +| "为什么这个出错了" | `rca-investigator` | 7-11 步 | +| "安全审查" | `security-reviewer` | 7-11 步 | +| "解释此功能如何工作" | `feature-explainer` | 7-11 步 | +| "调试此路径" | `bug-fixer` | 7-11 步 | + +### 3. 读取并验证锚点 + +每个文件路径和行锚点必须是真实的： + +* 确认文件存在 +* 确认行号在范围内 +* 如果使用选区，验证确切的代码块 +* 如果文件易变，优先使用基于模式的锚点 + +切勿猜测行号。 + +### 4. 编写 `.tour` + +写入： + +```text +.tours/-.tour +``` + +保持路径确定且可读。 + +### 5. 验证 + +在完成之前： + +* 每个引用的路径都存在 +* 每行或每个选区都有效 +* 第一步锚定到真实文件或目录 +* 导览讲述连贯的故事，而非罗列文件 + +## 步骤类型 + +### 内容 + +谨慎使用，通常仅用于结束步骤： + +```json +{ "title": "Next Steps", "description": "You can now trace the request path end to end." } +``` + +不要将第一步设为纯内容。 + +### 目录 + +用于引导读者了解模块： + +```json +{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." } +``` + +### 文件 + 行 + +这是默认步骤类型： + +```json +{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." } +``` + +### 选区 + +当某个代码块比整个文件更重要时使用： + +```json +{ + "file": "src/core/pipeline.ts", + "selection": { + "start": { "line": 15, "character": 0 }, + "end": { "line": 34, "character": 0 } + }, + "title": "Request Pipeline", + "description": "This block wires validation, auth, and downstream execution." +} +``` + +### 模式 + +当精确行号可能发生变化时使用： + +```json +{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" } +``` + +### URI + +在需要时用于 PR、问题或文档： + +```json +{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" } +``` + +## 编写规则：SMIG + +每个描述应回答： + +* **情境**：读者正在查看什么 +* **机制**：它是如何工作的 +* **影响**：为什么对此角色重要 +* **陷阱**：聪明的读者可能会错过什么 + +保持描述简洁、具体，并基于实际代码。 + +## 叙事结构 + +除非任务明确需要不同结构，否则使用此弧线： + +1. 定位 +2. 模块地图 +3. 核心执行路径 +4. 边缘情况或陷阱 +5. 结束 / 下一步 + +导览应感觉像一条路径，而非清单。 + +## 示例 + +```json +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "API Service Tour", + "description": "Walkthrough of the request path for the payments service.", + "ref": "main", + "steps": [ + { + "directory": "src", + "title": "Source Root", + "description": "All runtime code for the service starts here." + }, + { + "file": "src/server.ts", + "line": 12, + "title": "Entry Point", + "description": "The server boots here and wires middleware before any route is reached." + }, + { + "file": "src/routes/payments.ts", + "line": 8, + "title": "Payment Routes", + "description": "Every payments request enters through this router before hitting service logic." + }, + { + "title": "Next Steps", + "description": "You can now follow any payment request end to end with the main anchors in place." + } + ] +} +``` + +## 反模式 + +| 反模式 | 修复 | +| --- | --- | +| 平铺直叙的文件列表 | 讲述一个步骤间有依赖关系的故事 | +| 通用描述 | 指明具体的代码路径或模式 | +| 猜测的锚点 | 先验证每个文件和行 | +| 快速导览步骤过多 | 果断精简 | +| 第一步是纯内容 | 将第一步锚定到真实文件或目录 | +| 角色不匹配 | 为实际读者编写，而非通用工程师 | + +## 最佳实践 + +* 步骤数量与仓库大小和角色深度成比例 +* 使用目录步骤进行定位，文件步骤用于实质内容 +* 对于 PR 导览，首先覆盖变更的文件 +* 对于单体仓库，将范围限定在相关包，而非导览所有内容 +* 以读者现在可以做什么来结束，而非总结 + +## 相关技能 + +* `codebase-onboarding` +* `coding-standards` +* `council` +* 官方上游格式：`microsoft/codetour` diff --git a/docs/zh-CN/skills/ecc-tools-cost-audit/SKILL.md b/docs/zh-CN/skills/ecc-tools-cost-audit/SKILL.md new file mode 100644 index 00000000..e6ca1540 --- /dev/null +++ b/docs/zh-CN/skills/ecc-tools-cost-audit/SKILL.md @@ -0,0 +1,160 @@ +--- +name: ecc-tools-cost-audit +description: 证据优先的ECC工具燃烧和计费审计工作流。用于调查ECC工具仓库中的失控PR创建、配额绕过、高级模型泄漏、重复作业或GitHub App成本激增。 +origin: ECC +--- + +# ECC 工具成本审计 + +当用户怀疑 ECC Tools GitHub App 正在消耗成本、过度创建 PR、绕过使用限制，或将免费用户引导至付费分析路径时，使用此技能。 + +这是一个针对兄弟仓库 [ECC-Tools](../../../../ECC-Tools) 的聚焦操作者工作流。它不是通用的计费技能，也不是仓库范围的代码审查。 + +## 技能栈 + +在相关情况下，将这些 ECC 原生技能拉入工作流： + +* `autonomous-loops` 用于跨 webhook、队列、计费和重试的有界多步骤审计 +* `agentic-engineering` 用于将请求路径追踪为离散的、可证明的单元 +* `customer-billing-ops` 当需要清晰分离仓库行为和客户影响计算时 +* `search-first` 在发明辅助函数或重新实现仓库本地工具之前 +* `security-review` 当涉及认证、使用限制、授权或密钥时 +* `verification-loop` 用于证明重试安全性和精确的修复后状态 +* `tdd-workflow` 当修复需要在 worker、路由器或计费路径中添加回归测试覆盖时 + +## 使用时机 + +* 用户提及 ECC Tools 消耗率、PR 递归、过度创建的 PR、使用限制绕过或付费模型泄漏 +* 任务位于兄弟仓库 `ECC-Tools` 中，并依赖于 webhook 处理器、队列 worker、使用预留、PR 创建逻辑或付费网关强制执行 +* 客户报告称应用创建了过多 PR、计费错误，或分析了代码但未产生可用结果 + +## 范围约束 + +* 在兄弟仓库 `ECC-Tools` 中工作，而非 `everything-claude-code` +* 除非用户明确要求修复，否则以只读方式开始 +* 在追踪分析消耗时，不要修改无关的计费、结账或 UI 流程 +* 将应用生成的分支和应用生成的 PR 视为红旗递归路径，除非被证明并非如此 +* 明确区分三件事： + * 仓库侧消耗的根本原因 + * 面向客户的计费影响 + * 需要纳入待办事项跟踪的产品或授权缺口 + +## 工作流 + +### 1. 冻结仓库范围 + +* 切换到兄弟仓库 `ECC-Tools` +* 首先检查分支和本地差异 +* 确定审计的具体范围： + * webhook 路由器 + * 队列生产者 + * 队列消费者 + * PR 创建路径 + * 使用预留 / 计费路径 + * 模型路由路径 + +### 2. 在理论化之前追踪入口 + +* 首先检查 `src/index.*` 或主入口点 +* 在提出修复建议之前，映射每个入队路径 +* 确认哪些 GitHub 事件共享一个队列类型 +* 确认 push、pull\_request、synchronize、comment 或手动重新运行事件是否会汇聚到同一个昂贵的路径上 + +### 3. 追踪 Worker 和副作用 + +* 检查处理分析的队列消费者或定时 worker +* 确认排队的分析是否总是以以下方式结束： + * PR 创建 + * 分支创建 + * 文件更新 + * 付费模型调用 + * 使用量增加 +* 如果分析可能消耗令牌，然后在输出持久化之前失败，则将其归类为“消耗但输出中断” + +### 4. 审计高信号消耗路径 + +#### PR 倍增 + +* 检查 PR 辅助函数和分支命名 +* 检查去重、synchronize 事件处理以及现有 PR 的复用 +* 如果应用生成的分支可以重新进入分析，则将其视为优先级为 0 的递归风险 + +#### 配额绕过 + +* 检查配额检查的位置与使用量预留或增加的位置 +* 如果在入队前检查配额，但仅在 worker 内部计费使用量，则将并发的前门通过视为真正的竞态条件 + +#### 付费模型泄漏 + +* 检查模型选择、层级分支和提供商路由 +* 验证当存在付费密钥时，免费或受限用户是否仍能访问付费分析器 + +#### 重试消耗 + +* 检查重试循环、重复的队列任务和确定性失败重试 +* 如果相同的非临时性错误可以反复消耗分析资源，则先修复此问题，再进行质量改进 + +### 5. 按消耗顺序修复 + +如果用户要求代码更改，请按以下顺序优先修复： + +1. 阻止自动 PR 倍增 +2. 阻止配额绕过 +3. 阻止付费模型泄漏 +4. 阻止重复任务扇出和无意义的重试 +5. 弥补重试/更新安全缺口 + +除非同一根本原因明显跨越多个文件，否则将修复范围限制在一到三个直接修复。 + +### 6. 以最小的验证步骤进行验证 + +* 仅重新运行覆盖已更改路径的目标测试或集成片段 +* 验证消耗路径现在是否： + * 被阻止 + * 已去重 + * 降级为更便宜的分析 + * 或提前被拒绝 +* 准确说明最终状态： + * 本地已更改 + * 本地已验证 + * 已推送 + * 已部署 + * 仍被阻止 + +## 高信号故障模式 + +### 1. 所有触发器使用同一队列类型 + +如果推送、PR 同步和手动审计都入队相同的任务，并且 worker 总是创建 PR，那么分析就等于 PR 垃圾信息。 + +### 2. 入队后预留使用量 + +如果在入口处检查使用量，但仅在 worker 中增加，则并发请求可能全部通过关卡并超出配额。 + +### 3. 免费层级走付费路径 + +如果存在密钥时，免费的排队任务仍能路由到 Anthropic 或其他付费提供商，即使客户从未看到付费结果，这也是真实的支出泄漏。 + +### 4. 应用生成的分支重新进入 Webhook + +如果 `pull_request.synchronize`、分支推送或评论触发的运行在应用拥有的分支上触发，则应用可以递归分析自己的输出。 + +### 5. 在持久化安全之前执行昂贵操作 + +如果系统可能消耗令牌，然后在 PR 创建、文件更新或分支冲突时失败，则是在消耗成本而不产生价值。 + +## 陷阱 + +* 不要一开始就广泛浏览仓库；先确定 webhook -> 队列 -> worker 的路径 +* 不要将客户计费推断与基于代码的产品事实混为一谈 +* 在最高消耗路径被控制之前，不要修复价值较低的质量问题 +* 在重新运行狭窄的验证步骤之前，不要声称消耗问题已修复 +* 除非用户要求，否则不要推送或部署 +* 如果无关的仓库本地更改正在进行中，不要触碰它们 + +## 验证 + +* 根本原因需引用确切的文件路径和代码区域 +* 修复按消耗影响排序，而非代码整洁度 +* 需指明验证命令的名称 +* 最终状态需区分本地更改、验证、推送和部署 diff --git a/docs/zh-CN/skills/gateguard/SKILL.md b/docs/zh-CN/skills/gateguard/SKILL.md new file mode 100644 index 00000000..7da52bf6 --- /dev/null +++ b/docs/zh-CN/skills/gateguard/SKILL.md @@ -0,0 +1,123 @@ +--- +name: gateguard +description: 强制事实的门控，阻止编辑/写入/Bash（包括MultiEdit），并要求在允许操作之前进行具体调查（导入器、数据模式、用户指令）。与无门控代理相比，可测量地将输出质量提高2.25分。 +origin: community +--- + +# GateGuard — 事实驱动的前置操作门控 + +一个 PreToolUse 钩子，强制 Claude 在编辑前进行调查。不同于自我评估（"你确定吗？"），它要求具体的事实。调查行为本身创造了自我评估永远无法带来的认知。 + +## 何时激活 + +* 处理任何文件编辑会影响多个模块的代码库时 +* 项目包含具有特定模式或日期格式的数据文件时 +* 团队要求 AI 生成的代码必须匹配现有模式时 +* 任何 Claude 倾向于猜测而非调查的工作流程中 + +## 核心概念 + +LLM 的自我评估不起作用。问"你是否违反了任何策略？"答案永远是"没有"。这已通过实验验证。 + +但问"列出所有导入此模块的文件"会迫使 LLM 运行 Grep 和 Read。调查本身创造了改变输出的上下文。 + +**三阶段门控：** + +``` +1. DENY — 阻止首次编辑/写入/Bash 尝试 +2. FORCE — 明确告知模型需要收集哪些事实 +3. ALLOW — 在事实呈现后允许重试 +``` + +没有竞争对手能同时做到这三步。大多数止步于拒绝。 + +## 证据 + +两个独立的 A/B 测试，相同的代理，相同的任务： + +| 任务 | 有门控 | 无门控 | 差距 | +| --- | --- | --- | --- | +| 分析模块 | 8.0/10 | 6.5/10 | +1.5 | +| Webhook 验证器 | 10.0/10 | 7.0/10 | +3.0 | +| **平均** | **9.0** | **6.75** | **+2.25** | + +两个代理生成的代码都能运行并通过测试。区别在于设计深度。 + +## 门控类型 + +### 编辑/多编辑门控（每个文件的首次编辑） + +多编辑的处理方式相同——批次中的每个文件都单独进行门控。 + +``` +在编辑 {file_path} 之前，请先呈现以下事实： + +1. 列出所有导入/引用此文件的文件（使用 Grep） +2. 列出受此更改影响的公共函数/类 +3. 如果此文件读取/写入数据文件，请显示字段名称、结构以及日期格式（使用脱敏或合成值，而非原始生产数据） +4. 逐字引用用户当前的指令 +``` + +### 写入门控（首次创建新文件） + +``` +在创建 {file_path} 之前，请先说明以下事实： + +1. 命名将调用此新文件的文件及行号 +2. 确认没有现有文件具有相同功能（使用 Glob） +3. 如果此文件读取/写入数据文件，请展示字段名称、结构及日期格式（使用脱敏或合成值，而非原始生产数据） +4. 逐字引用用户当前的指令 +``` + +### 破坏性 Bash 门控（每个破坏性命令） + +触发条件：`rm -rf`、`git reset --hard`、`git push --force`、`drop table` 等。 + +``` +1. 列出此命令将修改或删除的所有文件/数据 +2. 编写一行回滚步骤 +3. 逐字引用用户当前的指令 +``` + +### 常规 Bash 门控（每个会话一次） + +``` +1. 当前用户请求的一句话概括 +2. 此特定命令验证或生成的内容 +``` + +## 快速开始 + +### 选项 A：使用 ECC 钩子（零安装） + +`scripts/hooks/gateguard-fact-force.js` 处的钩子已包含在此插件中。通过 hooks.json 启用它。 + +如果 GateGuard 阻止了设置或修复工作，请使用 +`ECC_GATEGUARD=off` 启动会话。如需钩子级别的控制，请继续使用 +`ECC_DISABLED_HOOKS` 配合 GateGuard 钩子 ID。 + +### 选项 B：带配置的完整包 + +```bash +pip install gateguard-ai +gateguard init +``` + +这会添加 `.gateguard.yml` 用于按项目配置（自定义消息、忽略路径、门控开关）。 + +## 反模式 + +* **不要使用自我评估替代。** "你确定吗？"总是得到"确定。"这已通过实验验证。 +* **不要跳过数据模式检查。** 两个 A/B 测试代理都假设了 ISO-8601 日期，而实际数据使用的是 `%Y/%m/%d %H:%M`。检查数据结构（使用脱敏值）可以防止这类错误。 +* **不要对每个 Bash 命令都进行门控。** 常规 bash 门控每个会话一次。破坏性 bash 门控每次执行。这种平衡避免了速度下降，同时捕获了真正的风险。 + +## 最佳实践 + +* 让门控自然触发。不要试图预先回答门控问题——调查本身才是提高质量的关键。 +* 为你的领域自定义门控消息。如果你的项目有特定约定，请将其添加到门控提示中。 +* 使用 `.gateguard.yml` 忽略 `.venv/`、`node_modules/`、`.git/` 等路径。 + +## 相关技能 + +* `safety-guard` — 运行时安全检查（互补，不重叠） +* `code-reviewer` — 编辑后审查（GateGuard 是编辑前调查） diff --git a/docs/zh-CN/skills/git-workflow/SKILL.md b/docs/zh-CN/skills/git-workflow/SKILL.md new file mode 100644 index 00000000..7de224a5 --- /dev/null +++ b/docs/zh-CN/skills/git-workflow/SKILL.md @@ -0,0 +1,720 @@ +--- +name: git-workflow +description: Git工作流模式，包括分支策略、提交约定、合并与变基、冲突解决以及适用于各种规模团队的协作开发最佳实践。 +origin: ECC +--- + +# Git 工作流模式 + +Git 版本控制、分支策略与协作开发的最佳实践。 + +## 何时启用 + +* 为新项目设置 Git 工作流 +* 决定分支策略（GitFlow、主干开发、GitHub Flow） +* 编写提交信息和 PR 描述 +* 解决合并冲突 +* 管理发布和版本标签 +* 让新团队成员熟悉 Git 实践 + +## 分支策略 + +### GitHub Flow（简单，推荐大多数场景使用） + +最适合持续部署以及中小型团队。 + +``` +main (protected, always deployable) + │ + ├── feature/user-auth → PR → merge to main + ├── feature/payment-flow → PR → merge to main + └── fix/login-bug → PR → merge to main +``` + +**规则：** + +* `main` 始终可部署 +* 从 `main` 创建功能分支 +* 准备就绪后发起 Pull Request +* 审核通过且 CI 通过后，合并到 `main` +* 合并后立即部署 + +### 主干开发（高速度团队） + +最适合具备强大 CI/CD 和功能开关的团队。 + +``` +main (主干) + │ + ├── 短期功能分支（最长1-2天） + ├── 短期功能分支 + └── 短期功能分支 +``` + +**规则：** + +* 所有人直接提交到 `main` 或使用极短生命周期的分支 +* 功能开关隐藏未完成的工作 +* 合并前必须通过 CI +* 每天多次部署 + +### GitFlow（复杂，基于发布周期） + +适合计划性发布和企业级项目。 + +``` +main (生产发布版本) + │ + └── develop (集成分支) + │ + ├── feature/user-auth + ├── feature/payment + │ + ├── release/1.0.0 → 合并到 main 和 develop + │ + └── hotfix/critical → 合并到 main 和 develop +``` + +**规则：** + +* `main` 仅包含生产就绪代码 +* `develop` 是集成分支 +* 功能分支从 `develop` 创建，合并回 `develop` +* 发布分支从 `develop` 创建，合并到 `main` 和 `develop` +* 热修复分支从 `main` 创建，合并到 `main` 和 `develop` + +### 何时使用哪种策略 + +| 策略 | 团队规模 | 发布频率 | 最佳适用场景 | +|----------|-----------|-----------------|----------| +| GitHub Flow | 任意 | 持续 | SaaS、Web 应用、初创公司 | +| 主干开发 | 5 人以上有经验 | 每天多次 | 高速度团队、功能开关 | +| GitFlow | 10 人以上 | 计划性 | 企业、受监管行业 | + +## 提交信息 + +### 常规提交格式 + +``` +(): + +[optional body] + +[optional footer(s)] +``` + +### 类型 + +| 类型 | 用途 | 示例 | +|------|---------|---------| +| `feat` | 新功能 | `feat(auth): add OAuth2 login` | +| `fix` | 错误修复 | `fix(api): handle null response in user endpoint` | +| `docs` | 文档 | `docs(readme): update installation instructions` | +| `style` | 格式调整，无代码变更 | `style: fix indentation in login component` | +| `refactor` | 代码重构 | `refactor(db): extract connection pool to module` | +| `test` | 添加/更新测试 | `test(auth): add unit tests for token validation` | +| `chore` | 维护任务 | `chore(deps): update dependencies` | +| `perf` | 性能改进 | `perf(query): add index to users table` | +| `ci` | CI/CD 变更 | `ci: add PostgreSQL service to test workflow` | +| `revert` | 回滚之前的提交 | `revert: revert "feat(auth): add OAuth2 login"` | + +### 好与坏的示例 + +``` +# 不好：模糊，无上下文 +git commit -m "修复了一些东西" +git commit -m "更新" +git commit -m "进行中" + +# 好：清晰，具体，解释原因 +git commit -m "fix(api): 在 503 服务不可用时重试请求 + +外部 API 在高峰时段偶尔会返回 503 错误。 +添加了指数退避重试逻辑，最多尝试 3 次。 + +关闭 #123" +``` + +### 提交信息模板 + +在仓库根目录创建 `.gitmessage`： + +``` +# (): +# # 类型：feat, fix, docs, style, refactor, test, chore, perf, ci, revert +# 范围：api, ui, db, auth 等 +# 主题：祈使语气，无句号，最多50个字符 +# +# [可选正文] - 解释原因，而非内容 +# [可选脚注] - 破坏性变更，关闭 #issue +``` + +启用方式：`git config commit.template .gitmessage` + +## 合并 vs 变基 + +### 合并（保留历史） + +```bash +# Creates a merge commit +git checkout main +git merge feature/user-auth + +# Result: +# * merge commit +# |\ +# | * feature commits +# |/ +# * main commits +``` + +**适用场景：** + +* 将功能分支合并到 `main` +* 希望保留完整历史 +* 多人共同开发该分支 +* 分支已推送，其他人可能基于它开展工作 + +### 变基（线性历史） + +```bash +# Rewrites feature commits onto target branch +git checkout feature/user-auth +git rebase main + +# Result: +# * feature commits (rewritten) +# * main commits +``` + +**适用场景：** + +* 用最新的 `main` 更新本地功能分支 +* 希望获得线性、干净的历史 +* 分支仅存在于本地（未推送） +* 只有你一个人在该分支上工作 + +### 变基工作流 + +```bash +# Update feature branch with latest main (before PR) +git checkout feature/user-auth +git fetch origin +git rebase origin/main + +# Fix any conflicts +# Tests should still pass + +# Force push (only if you're the only contributor) +git push --force-with-lease origin feature/user-auth +``` + +### 何时不应变基 + +``` +# 切勿变基以下分支： +- 已推送至共享仓库的分支 +- 他人已基于其工作的分支 +- 受保护分支（main、develop） +- 已合并的分支 + +# 原因：变基会重写历史，破坏他人的工作 +``` + +## Pull Request 工作流 + +### PR 标题格式 + +``` +(): + +示例： +feat(auth): add SSO support for enterprise users +fix(api): resolve race condition in order processing +docs(api): add OpenAPI specification for v2 endpoints +``` + +### PR 描述模板 + +```markdown +## 内容 + +简要描述此 PR 的内容。 + +## 动机 + +解释动机和背景。 + +## 实现方式 + +值得强调的关键实现细节。 + +## 测试 + +- [ ] 新增/更新单元测试 +- [ ] 新增/更新集成测试 +- [ ] 执行手动测试 + +## 截图（如适用） + +UI 变更的前后对比截图。 + +## 检查清单 + +- [ ] 代码遵循项目风格指南 +- [ ] 完成自我审查 +- [ ] 为复杂逻辑添加注释 +- [ ] 更新文档 +- [ ] 未引入新警告 +- [ ] 测试在本地通过 +- [ ] 关联问题已链接 + +关闭 #123 +``` + +### 代码审查清单 + +**审查者：** + +* \[ ] 代码是否解决了所述问题？ +* \[ ] 是否处理了所有边界情况？ +* \[ ] 代码是否可读且易于维护？ +* \[ ] 是否有足够的测试？ +* \[ ] 是否存在安全问题？ +* \[ ] 提交历史是否干净（必要时已压缩）？ + +**作者：** + +* \[ ] 在请求审查前已完成自我审查 +* \[ ] CI 通过（测试、lint、类型检查） +* \[ ] PR 大小合理（理想情况下 <500 行） +* \[ ] 与单个功能/修复相关 +* \[ ] 描述清晰解释了变更内容 + +## 冲突解决 + +### 识别冲突 + +```bash +# Check for conflicts before merge +git checkout main +git merge feature/user-auth --no-commit --no-ff + +# If conflicts, Git will show: +# CONFLICT (content): Merge conflict in src/auth/login.ts +# Automatic merge failed; fix conflicts and then commit the result. +``` + +### 解决冲突 + +```bash +# See conflicted files +git status + +# View conflict markers in file +# <<<<<<< HEAD +# content from main +# ======= +# content from feature branch +# >>>>>>> feature/user-auth + +# Option 1: Manual resolution +# Edit file, remove markers, keep correct content + +# Option 2: Use merge tool +git mergetool + +# Option 3: Accept one side +git checkout --ours src/auth/login.ts # Keep main version +git checkout --theirs src/auth/login.ts # Keep feature version + +# After resolving, stage and commit +git add src/auth/login.ts +git commit +``` + +### 冲突预防策略 + +```bash +# 1. Keep feature branches small and short-lived +# 2. Rebase frequently onto main +git checkout feature/user-auth +git fetch origin +git rebase origin/main + +# 3. Communicate with team about touching shared files +# 4. Use feature flags instead of long-lived branches +# 5. Review and merge PRs promptly +``` + +## 分支管理 + +### 命名规范 + +``` +# 功能分支 +feature/user-authentication +feature/JIRA-123-payment-integration + +# 错误修复 +fix/login-redirect-loop +fix/456-null-pointer-exception + +# 热修复（生产问题） +hotfix/critical-security-patch +hotfix/database-connection-leak + +# 发布版本 +release/1.2.0 +release/2024-01-hotfix + +# 实验/概念验证 +experiment/new-caching-strategy +poc/graphql-migration +``` + +### 分支清理 + +```bash +# Delete local branches that are merged +git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d + +# Delete remote-tracking references for deleted remote branches +git fetch -p + +# Delete local branch +git branch -d feature/user-auth # Safe delete (only if merged) +git branch -D feature/user-auth # Force delete + +# Delete remote branch +git push origin --delete feature/user-auth +``` + +### 暂存工作流 + +```bash +# Save work in progress +git stash push -m "WIP: user authentication" + +# List stashes +git stash list + +# Apply most recent stash +git stash pop + +# Apply specific stash +git stash apply stash@{2} + +# Drop stash +git stash drop stash@{0} +``` + +## 发布管理 + +### 语义化版本 + +``` +MAJOR.MINOR.PATCH + +MAJOR：破坏性变更 +MINOR：新功能，向后兼容 +PATCH：错误修复，向后兼容 + +示例： +1.0.0 → 1.0.1（补丁：错误修复） +1.0.1 → 1.1.0（次要：新功能） +1.1.0 → 2.0.0（主要：破坏性变更） +``` + +### 创建发布 + +```bash +# Create annotated tag +git tag -a v1.2.0 -m "Release v1.2.0 + +Features: +- Add user authentication +- Implement password reset + +Fixes: +- Resolve login redirect issue + +Breaking Changes: +- None" + +# Push tag to remote +git push origin v1.2.0 + +# List tags +git tag -l + +# Delete tag +git tag -d v1.2.0 +git push origin --delete v1.2.0 +``` + +### 变更日志生成 + +```bash +# Generate changelog from commits +git log v1.1.0..v1.2.0 --oneline --no-merges + +# Or use conventional-changelog +npx conventional-changelog -i CHANGELOG.md -s +``` + +## Git 配置 + +### 基本配置 + +```bash +# User identity +git config --global user.name "Your Name" +git config --global user.email "your@email.com" + +# Default branch name +git config --global init.defaultBranch main + +# Pull behavior (rebase instead of merge) +git config --global pull.rebase true + +# Push behavior (push current branch only) +git config --global push.default current + +# Auto-correct typos +git config --global help.autocorrect 1 + +# Better diff algorithm +git config --global diff.algorithm histogram + +# Color output +git config --global color.ui auto +``` + +### 实用别名 + +```bash +# Add to ~/.gitconfig +[alias] + co = checkout + br = branch + ci = commit + st = status + unstage = reset HEAD -- + last = log -1 HEAD + visual = log --oneline --graph --all + amend = commit --amend --no-edit + wip = commit -m "WIP" + undo = reset --soft HEAD~1 + contributors = shortlog -sn +``` + +### Gitignore 模式 + +```gitignore +# Dependencies +node_modules/ +vendor/ + +# Build outputs +dist/ +build/ +*.o +*.exe + +# Environment files +.env +.env.local +.env.*.local + +# IDE +.idea/ +.vscode/ +*.swp +*.swo + +# OS files +.DS_Store +Thumbs.db + +# Logs +*.log +logs/ + +# Test coverage +coverage/ + +# Cache +.cache/ +*.tsbuildinfo +``` + +## 常见工作流 + +### 开始新功能 + +```bash +# 1. Update main branch +git checkout main +git pull origin main + +# 2. Create feature branch +git checkout -b feature/user-auth + +# 3. Make changes and commit +git add . +git commit -m "feat(auth): implement OAuth2 login" + +# 4. Push to remote +git push -u origin feature/user-auth + +# 5. Create Pull Request on GitHub/GitLab +``` + +### 用新变更更新 PR + +```bash +# 1. Make additional changes +git add . +git commit -m "feat(auth): add error handling" + +# 2. Push updates +git push origin feature/user-auth +``` + +### 同步 Fork 与上游 + +```bash +# 1. Add upstream remote (once) +git remote add upstream https://github.com/original/repo.git + +# 2. Fetch upstream +git fetch upstream + +# 3. Merge upstream/main into your main +git checkout main +git merge upstream/main + +# 4. Push to your fork +git push origin main +``` + +### 撤销错误操作 + +```bash +# Undo last commit (keep changes) +git reset --soft HEAD~1 + +# Undo last commit (discard changes) +git reset --hard HEAD~1 + +# Undo last commit pushed to remote +git revert HEAD +git push origin main + +# Undo specific file changes +git checkout HEAD -- path/to/file + +# Fix last commit message +git commit --amend -m "New message" + +# Add forgotten file to last commit +git add forgotten-file +git commit --amend --no-edit +``` + +## Git 钩子 + +### 预提交钩子 + +```bash +#!/bin/bash +# .git/hooks/pre-commit + +# Run linting +npm run lint || exit 1 + +# Run tests +npm test || exit 1 + +# Check for secrets +if git diff --cached | grep -E '(password|api_key|secret)'; then + echo "Possible secret detected. Commit aborted." + exit 1 +fi +``` + +### 预推送钩子 + +```bash +#!/bin/bash +# .git/hooks/pre-push + +# Run full test suite +npm run test:all || exit 1 + +# Check for console.log statements +if git diff origin/main | grep -E 'console\.log'; then + echo "Remove console.log statements before pushing." + exit 1 +fi +``` + +## 反模式 + +``` +# 错误：直接提交到主分支 +git checkout main +git commit -m "修复bug" + +# 正确：使用功能分支和拉取请求 + +# 错误：提交机密信息 +git add .env # 包含API密钥 + +# 正确：添加到.gitignore，使用环境变量 + +# 错误：巨大的拉取请求（超过1000行） +# 正确：拆分为更小、更聚焦的拉取请求 + +# 错误："更新"类提交信息 +git commit -m "更新" +git commit -m "修复" + +# 正确：描述性信息 +git commit -m "fix(auth): 解决登录后的重定向循环问题" + +# 错误：重写公共历史 +git push --force origin main + +# 正确：对公共分支使用回退 +git revert HEAD + +# 错误：长期存在的功能分支（数周/数月） +# 正确：保持分支短期（数天），频繁变基 + +# 错误：提交生成的文件 +git add dist/ +git add node_modules/ + +# 正确：添加到.gitignore +``` + +## 快速参考 + +| 任务 | 命令 | +|------|---------| +| 创建分支 | `git checkout -b feature/name` | +| 切换分支 | `git checkout branch-name` | +| 删除分支 | `git branch -d branch-name` | +| 合并分支 | `git merge branch-name` | +| 变基分支 | `git rebase main` | +| 查看历史 | `git log --oneline --graph` | +| 查看变更 | `git diff` | +| 暂存变更 | `git add .` 或 `git add -p` | +| 提交 | `git commit -m "message"` | +| 推送 | `git push origin branch-name` | +| 拉取 | `git pull origin branch-name` | +| 暂存 | `git stash push -m "message"` | +| 撤销上次提交 | `git reset --soft HEAD~1` | +| 回滚提交 | `git revert HEAD` | diff --git a/docs/zh-CN/skills/github-ops/SKILL.md b/docs/zh-CN/skills/github-ops/SKILL.md new file mode 100644 index 00000000..b67aaa4b --- /dev/null +++ b/docs/zh-CN/skills/github-ops/SKILL.md @@ -0,0 +1,145 @@ +--- +name: github-ops +description: GitHub 仓库操作、自动化与管理。使用 gh CLI 进行问题分类、PR 管理、CI/CD 操作、发布管理和安全监控。当用户想要管理 GitHub 问题、PR、CI 状态、发布、贡献者、过期项目或任何超出简单 git 命令的 GitHub 操作任务时使用。 +origin: ECC +--- + +# GitHub 操作 + +管理 GitHub 仓库，重点关注社区健康、CI 可靠性和贡献者体验。 + +## 何时激活 + +* 对议题进行分类（分类、打标签、回复、去重） +* 管理 PR（审查状态、CI 检查、过期 PR、合并就绪状态） +* 调试 CI/CD 失败 +* 准备发布和变更日志 +* 监控 Dependabot 和安全告警 +* 管理开源项目的贡献者体验 +* 用户说“检查 GitHub”、“分类议题”、“审查 PR”、“合并”、“发布”、“CI 坏了” + +## 工具要求 + +* 所有 GitHub API 操作均使用 **gh CLI** +* 通过 `gh auth login` 配置仓库访问权限 + +## 议题分类 + +按类型和优先级对每个议题进行分类： + +**类型：** bug, feature-request, question, documentation, enhancement, duplicate, invalid, good-first-issue + +**优先级：** critical（破坏性/安全相关）, high（重大影响）, medium（锦上添花）, low（外观/体验优化） + +### 分类工作流程 + +1. 阅读议题标题、正文和评论 +2. 检查是否与现有议题重复（通过关键词搜索） +3. 通过 `gh issue edit --add-label` 应用适当的标签 +4. 对于问题：起草并发布有帮助的回复 +5. 对于需要更多信息的 Bug：要求提供复现步骤 +6. 对于适合新手的议题：添加 `good-first-issue` 标签 +7. 对于重复议题：评论并附上原始议题链接，添加 `duplicate` 标签 + +```bash +# Search for potential duplicates +gh issue list --search "keyword" --state all --limit 20 + +# Add labels +gh issue edit --add-label "bug,high-priority" + +# Comment on issue +gh issue comment --body "Thanks for reporting. Could you share reproduction steps?" +``` + +## PR 管理 + +### 审查清单 + +1. 检查 CI 状态：`gh pr checks ` +2. 检查是否可合并：`gh pr view --json mergeable` +3. 检查 PR 的创建时间和最后活动时间 +4. 标记超过 5 天未审查的 PR +5. 对于社区 PR：确保包含测试并遵循项目规范 + +### 过期策略 + +* 超过 14 天无活动的议题：添加 `stale` 标签，评论要求更新 +* 超过 7 天无活动的 PR：评论询问是否仍在进行 +* 30 天内无回复的过期议题自动关闭（添加 `closed-stale` 标签） + +```bash +# Find stale issues (no activity in 14+ days) +gh issue list --label "stale" --state open + +# Find PRs with no recent activity +gh pr list --json number,title,updatedAt --jq '.[] | select(.updatedAt < "2026-03-01")' +``` + +## CI/CD 操作 + +当 CI 失败时： + +1. 检查工作流运行：`gh run view --log-failed` +2. 识别失败的步骤 +3. 判断是不稳定测试还是真正的失败 +4. 对于真正的失败：确定根本原因并提出修复建议 +5. 对于不稳定测试：记录模式以便未来调查 + +```bash +# List recent failed runs +gh run list --status failure --limit 10 + +# View failed run logs +gh run view --log-failed + +# Re-run a failed workflow +gh run rerun --failed +``` + +## 发布管理 + +准备发布时： + +1. 确保主分支上的所有 CI 检查通过 +2. 审查未发布的更改：`gh pr list --state merged --base main` +3. 根据 PR 标题生成变更日志 +4. 创建发布：`gh release create` + +```bash +# List merged PRs since last release +gh pr list --state merged --base main --search "merged:>2026-03-01" + +# Create a release +gh release create v1.2.0 --title "v1.2.0" --generate-notes + +# Create a pre-release +gh release create v1.3.0-rc1 --prerelease --title "v1.3.0 Release Candidate 1" +``` + +## 安全监控 + +```bash +# Check Dependabot alerts +gh api repos/{owner}/{repo}/dependabot/alerts --jq '.[].security_advisory.summary' + +# Check secret scanning alerts +gh api repos/{owner}/{repo}/secret-scanning/alerts --jq '.[].state' + +# Review and auto-merge safe dependency bumps +gh pr list --label "dependencies" --json number,title +``` + +* 审查并自动合并安全的依赖项更新 +* 立即标记任何严重/高严重性告警 +* 至少每周检查一次新的 Dependabot 告警 + +## 质量门禁 + +在完成任何 GitHub 操作任务之前： + +* 所有已分类的议题都带有适当的标签 +* 没有超过 7 天未收到审查或评论的 PR +* CI 失败已被调查（不仅仅是重新运行） +* 发布包含准确的变更日志 +* 安全告警已被确认并跟踪 diff --git a/docs/zh-CN/skills/hookify-rules/SKILL.md b/docs/zh-CN/skills/hookify-rules/SKILL.md new file mode 100644 index 00000000..145de33d --- /dev/null +++ b/docs/zh-CN/skills/hookify-rules/SKILL.md @@ -0,0 +1,139 @@ +--- +name: hookify-rules +description: 当用户要求创建hookify规则、编写hook规则、配置hookify、添加hookify规则或需要关于hookify规则语法和模式的指导时，应使用此技能。 +--- + +# 编写 Hookify 规则 + +## 概述 + +Hookify 规则是带有 YAML 前置元数据的 Markdown 文件，用于定义要监控的模式以及匹配时显示的消息。规则存储在 `.claude/hookify.{rule-name}.local.md` 文件中。 + +## 规则文件格式 + +### 基本结构 + +```markdown +--- +name: rule-identifier +enabled: true +event: bash|file|stop|prompt|all +pattern: regex-pattern-here +--- + +当此规则触发时向 Claude 显示的消息。 +可包含 Markdown 格式、警告、建议等内容。 +``` + +### 前置元数据字段 + +| 字段 | 必填 | 值 | 描述 | +|-------|----------|--------|-------------| +| name | 是 | kebab-case 字符串 | 唯一标识符（动词优先：warn-*、block-*、require-*） | +| enabled | 是 | true/false | 无需删除即可切换 | +| event | 是 | bash/file/stop/prompt/all | 触发规则的钩子事件 | +| action | 否 | warn/block | warn（默认）显示消息；block 阻止操作 | +| pattern | 是* | 正则表达式字符串 | 要匹配的模式（\*或使用 conditions 实现复杂规则） | + +### 高级格式（多条件） + +```markdown +--- +name: warn-env-api-keys +enabled: true +event: file +conditions: + - field: file_path + operator: regex_match + pattern: \.env$ + - field: new_text + operator: contains + pattern: API_KEY +--- + +你正在向 .env 文件中添加 API 密钥。请确保该文件已包含在 .gitignore 中！ +``` + +**按事件划分的条件字段：** + +* bash：`command` +* file：`file_path`、`new_text`、`old_text`、`content` +* prompt：`user_prompt` + +**运算符：** `regex_match`、`contains`、`equals`、`not_contains`、`starts_with`、`ends_with` + +所有条件必须同时满足才能触发规则。 + +## 事件类型指南 + +### bash 事件 + +匹配 Bash 命令模式： + +* 危险命令：`rm\s+-rf`、`dd\s+if=`、`mkfs` +* 权限提升：`sudo\s+`、`su\s+` +* 权限问题：`chmod\s+777` + +### file 事件 + +匹配编辑/写入/多重编辑操作： + +* 调试代码：`console\.log\(`、`debugger` +* 安全风险：`eval\(`、`innerHTML\s*=` +* 敏感文件：`\.env$`、`credentials`、`\.pem$` + +### stop 事件 + +完成检查与提醒。模式 `.*` 始终匹配。 + +### prompt 事件 + +匹配用户提示内容以强制执行工作流程。 + +## 模式编写技巧 + +### 正则表达式基础 + +* 转义特殊字符：`.` 转义为 `\.`，`(` 转义为 `\(` +* `\s` 空白字符，`\d` 数字，`\w` 单词字符 +* `+` 一个或多个，`*` 零个或多个，`?` 可选 +* `|` 或运算符 + +### 常见陷阱 + +* **过于宽泛**：`log` 会匹配 "login"、"dialog"——请使用 `console\.log\(` +* **过于具体**：`rm -rf /tmp`——请使用 `rm\s+-rf` +* **YAML 转义**：使用无引号模式；带引号的字符串需要 `\\s` + +### 测试 + +```bash +python3 -c "import re; print(re.search(r'your_pattern', 'test text'))" +``` + +## 文件组织 + +* **位置**：项目根目录下的 `.claude/` 目录 +* **命名**：`.claude/hookify.{descriptive-name}.local.md` +* **Gitignore**：将 `.claude/*.local.md` 添加到 `.gitignore` + +## 命令 + +* `/hookify [description]` - 创建新规则（无参数时自动分析对话） +* `/hookify-list` - 以表格形式查看所有规则 +* `/hookify-configure` - 交互式切换规则开关 +* `/hookify-help` - 完整文档 + +## 快速参考 + +最小可行规则： + +```markdown +--- +name: my-rule +enabled: true +event: bash +pattern: dangerous_command +--- +此处显示警告信息 +``` diff --git a/docs/zh-CN/skills/jira-integration/SKILL.md b/docs/zh-CN/skills/jira-integration/SKILL.md new file mode 100644 index 00000000..1b707219 --- /dev/null +++ b/docs/zh-CN/skills/jira-integration/SKILL.md @@ -0,0 +1,302 @@ +--- +name: jira-integration +description: 在检索Jira工单、分析需求、更新工单状态、添加评论或转换问题时使用此技能。通过MCP或直接REST调用提供Jira API模式。 +origin: ECC +--- + +# Jira 集成技能 + +直接从 AI 编码工作流中检索、分析和更新 Jira 工单。支持 **基于 MCP**（推荐）和 **直接 REST API** 两种方式。 + +## 何时激活 + +* 获取 Jira 工单以理解需求 +* 从工单中提取可测试的验收标准 +* 向 Jira 问题添加进度评论 +* 转换工单状态（待办 → 进行中 → 完成） +* 将合并请求或分支链接到 Jira 问题 +* 通过 JQL 查询搜索问题 + +## 前提条件 + +### 选项 A：MCP 服务器（推荐） + +安装 `mcp-atlassian` MCP 服务器。这将向您的 AI 代理直接暴露 Jira 工具。 + +**要求：** + +* Python 3.10+ +* `uvx`（来自 `uv`），通过您的包管理器或官方 `uv` 安装文档进行安装 + +**添加到您的 MCP 配置**（例如，`~/.claude.json` → `mcpServers`）： + +```json +{ + "jira": { + "command": "uvx", + "args": ["mcp-atlassian==0.21.0"], + "env": { + "JIRA_URL": "https://YOUR_ORG.atlassian.net", + "JIRA_EMAIL": "your.email@example.com", + "JIRA_API_TOKEN": "your-api-token" + }, + "description": "Jira issue tracking — search, create, update, comment, transition" + } +} +``` + +> **安全：** 切勿在源代码中硬编码密钥。建议在系统环境（或密钥管理器）中设置 `JIRA_URL`、`JIRA_EMAIL` 和 `JIRA_API_TOKEN`。仅对本地未提交的配置文件使用 MCP `env` 块。 + +**获取 Jira API 令牌：** + +1. 访问 +2. 点击 **创建 API 令牌** +3. 复制令牌 — 将其存储在您的环境中，切勿存储在源代码中 + +### 选项 B：直接 REST API + +如果 MCP 不可用，可通过 `curl` 或辅助脚本直接使用 Jira REST API v3。 + +**所需的环境变量：** + +| 变量 | 描述 | +|----------|-------------| +| `JIRA_URL` | 您的 Jira 实例 URL（例如，`https://yourorg.atlassian.net`） | +| `JIRA_EMAIL` | 您的 Atlassian 账户邮箱 | +| `JIRA_API_TOKEN` | 来自 id.atlassian.com 的 API 令牌 | + +将这些存储在您的 shell 环境、密钥管理器或未跟踪的本地环境文件中。不要将其提交到仓库。 + +## MCP 工具参考 + +当配置了 `mcp-atlassian` MCP 服务器时，以下工具可用： + +| 工具 | 用途 | 示例 | +|------|---------|---------| +| `jira_search` | JQL 查询 | `project = PROJ AND status = "In Progress"` | +| `jira_get_issue` | 按键获取完整问题详情 | `PROJ-1234` | +| `jira_create_issue` | 创建问题（任务、缺陷、故事、史诗） | 新建缺陷报告 | +| `jira_update_issue` | 更新字段（摘要、描述、经办人） | 更改经办人 | +| `jira_transition_issue` | 更改状态 | 移至“评审中” | +| `jira_add_comment` | 添加评论 | 进度更新 | +| `jira_get_sprint_issues` | 列出冲刺中的问题 | 活跃冲刺评审 | +| `jira_create_issue_link` | 链接问题（阻塞、关联） | 依赖跟踪 | +| `jira_get_issue_development_info` | 查看关联的 PR、分支、提交 | 开发上下文 | + +> **提示：** 在转换前始终调用 `jira_get_transitions` — 转换 ID 因项目工作流而异。 + +## 直接 REST API 参考 + +### 获取工单 + +```bash +curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{ + key: .key, + summary: .fields.summary, + status: .fields.status.name, + priority: .fields.priority.name, + type: .fields.issuetype.name, + assignee: .fields.assignee.displayName, + labels: .fields.labels, + description: .fields.description + }' +``` + +### 获取评论 + +```bash +curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | { + author: .author.displayName, + created: .created[:10], + body: .body + }' +``` + +### 添加评论 + +```bash +curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "body": { + "version": 1, + "type": "doc", + "content": [{ + "type": "paragraph", + "content": [{"type": "text", "text": "Your comment here"}] + }] + } + }' \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment" +``` + +### 转换工单 + +```bash +# 1. Get available transitions +curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}' + +# 2. Execute transition (replace TRANSITION_ID) +curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"transition": {"id": "TRANSITION_ID"}}' \ + "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" +``` + +### 使用 JQL 搜索 + +```bash +curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \ + --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \ + "$JIRA_URL/rest/api/3/search" +``` + +## 分析工单 + +当为开发或测试自动化检索工单时，提取： + +### 1. 可测试的需求 + +* **功能需求** — 功能的作用 +* **验收标准** — 必须满足的条件 +* **可测试的行为** — 具体操作和预期结果 +* **用户角色** — 谁使用此功能及其权限 +* **数据需求** — 需要哪些数据 +* **集成点** — 涉及的 API、服务或系统 + +### 2. 所需的测试类型 + +* **单元测试** — 单个函数和工具 +* **集成测试** — API 端点和服务交互 +* **端到端测试** — 面向用户的 UI 流程 +* **API 测试** — 端点契约和错误处理 + +### 3. 边界情况与错误场景 + +* 无效输入（空值、过长、特殊字符） +* 未授权访问 +* 网络故障或超时 +* 并发用户或竞态条件 +* 边界条件 +* 数据缺失或为空 +* 状态转换（返回导航、刷新等） + +### 4. 结构化分析输出 + +``` +Ticket: PROJ-1234 +Summary: [工单标题] +Status: [当前状态] +Priority: [高/中/低] +Test Types: 单元测试, 集成测试, 端到端测试 + +Requirements: +1. [需求1] +2. [需求2] + +Acceptance Criteria: +- [ ] [验收标准1] +- [ ] [验收标准2] + +Test Scenarios: +- Happy Path: [描述] +- Error Case: [描述] +- Edge Case: [描述] + +Test Data Needed: +- [测试数据1] +- [测试数据2] + +Dependencies: +- [依赖项1] +- [依赖项2] +``` + +## 更新工单 + +### 何时更新 + +| 工作流步骤 | Jira 更新 | +|---|---| +| 开始工作 | 转换为“进行中” | +| 编写测试 | 评论并附上测试覆盖率摘要 | +| 创建分支 | 评论并附上分支名称 | +| 创建 PR/MR | 评论并附上链接，链接问题 | +| 测试通过 | 评论并附上结果摘要 | +| PR/MR 合并 | 转换为“完成”或“评审中” | + +### 评论模板 + +**开始工作：** + +``` +开始实现此工单。 +分支：feat/PROJ-1234-feature-name +``` + +**测试已实现：** + +``` +已实现的自动化测试： + +单元测试： +- [测试文件1] — [覆盖内容] +- [测试文件2] — [覆盖内容] + +集成测试： +- [测试文件] — [覆盖的端点/流程] + +所有测试在本地通过。覆盖率：XX% +``` + +**PR 已创建：** + +``` +Pull request created: +[PR Title](https://github.com/org/repo/pull/XXX) + +Ready for review. +``` + +**工作完成：** + +``` +Implementation complete. + +PR merged: [link] +Test results: All passing (X/Y) +Coverage: XX% +``` + +## 安全指南 + +* **切勿在**源代码或技能文件中硬编码 Jira API 令牌 +* **始终使用**环境变量或密钥管理器 +* **将 `.env`** 添加到每个项目的 `.gitignore` 中 +* **如果令牌暴露在 git 历史中，立即轮换** +* **使用最小权限** API 令牌，范围限定在所需项目 +* **在发出 API 调用前验证**凭据是否已设置 — 快速失败并给出清晰消息 + +## 故障排除 + +| 错误 | 原因 | 修复 | +|---|---|---| +| `401 Unauthorized` | API 令牌无效或已过期 | 在 id.atlassian.com 重新生成 | +| `403 Forbidden` | 令牌缺少项目权限 | 检查令牌范围和项目访问权限 | +| `404 Not Found` | 工单键或基础 URL 错误 | 验证 `JIRA_URL` 和工单键 | +| `spawn uvx ENOENT` | IDE 在 PATH 中找不到 `uvx` | 使用完整路径（例如，`~/.local/bin/uvx`）或在 `~/.zprofile` 中设置 PATH | +| 连接超时 | 网络/VPN 问题 | 检查 VPN 连接和防火墙规则 | + +## 最佳实践 + +* 边工作边更新 Jira，而不是最后一次性更新 +* 保持评论简洁但信息丰富 +* 链接而非复制 — 指向 PR、测试报告和仪表板 +* 如果需要他人输入，使用 @提及 +* 在开始前检查关联问题以了解完整功能范围 +* 如果验收标准模糊，在编写代码前要求澄清 diff --git a/docs/zh-CN/skills/knowledge-ops/SKILL.md b/docs/zh-CN/skills/knowledge-ops/SKILL.md new file mode 100644 index 00000000..577ecb98 --- /dev/null +++ b/docs/zh-CN/skills/knowledge-ops/SKILL.md @@ -0,0 +1,177 @@ +--- +name: knowledge-ops +description: 知识库管理、摄取、同步和跨多个存储层（本地文件、MCP内存、向量存储、Git仓库）的检索。当用户想要保存、组织、同步、去重或搜索其知识系统时使用。 +origin: ECC +--- + +# 知识操作 + +管理一个多层知识系统，用于跨多个存储库进行知识的摄取、组织、同步和检索。 + +推荐使用实时工作区模型： + +* 代码工作存在于实际克隆的仓库中 +* 活跃执行上下文存在于 GitHub、Linear 和仓库本地的上下文文件中 +* 面向人类更广泛的笔记可以存放在非仓库的上下文/归档文件夹中 +* 跨机器的持久化记忆应属于知识库，而非影子仓库工作区 + +## 何时激活 + +* 用户希望将信息保存到其知识库 +* 将文档、对话或数据摄取到结构化存储中 +* 跨系统同步知识（本地文件、MCP 记忆、Supabase、Git 仓库） +* 对现有知识进行去重或整理 +* 用户说“保存到知识库”、“同步知识”、“关于 X 我知道什么”、“摄取这个”、“更新知识库” +* 任何超出简单记忆回忆的知识管理任务 + +## 知识架构 + +### 第一层：活跃执行真相 + +* **来源：** GitHub 议题、PR、讨论、发布说明、Linear 议题/项目/文档 +* **用途：** 工作的当前操作状态 +* **规则：** 如果某事物影响活跃的工程计划、路线图、发布或版本，优先将其放在此处 + +### 第二层：Claude Code 记忆（快速访问） + +* **路径：** `~/.claude/projects/*/memory/` +* **格式：** 带有前置元数据的 Markdown 文件 +* **类型：** 用户偏好、反馈、项目上下文、参考 +* **用途：** 跨对话持久化的快速访问上下文 +* **会话启动时自动加载** + +### 第三层：MCP 记忆服务器（结构化知识图谱） + +* **访问：** MCP 记忆工具（create\_entities、create\_relations、add\_observations、search\_nodes） +* **用途：** 对所有存储记忆进行语义搜索、关系映射 +* **跨会话持久化，具有可查询的图谱结构** + +### 第四层：知识库仓库 / 持久化文档存储 + +* **用途：** 精选的持久化笔记、会话导出、综合研究、操作员记忆、长文文档 +* **规则：** 当内容不属于仓库拥有的代码时，这是跨机器上下文的首选持久化存储 + +### 第五层：外部数据存储（Supabase、PostgreSQL 等） + +* **用途：** 结构化数据、大型文档存储、全文搜索 +* **适用场景：** 对于记忆文件过大的文档、需要 SQL 查询的数据 + +### 第六层：本地上下文/归档文件夹 + +* **用途：** 面向人类的笔记、归档的游戏计划、本地媒体整理、临时非代码文档 +* **规则：** 可写入用于信息存储，但非影子代码工作区 +* **禁止用于：** 应存在于上游的活跃代码更改或仓库真相 + +## 摄取工作流 + +当需要捕获新知识时： + +### 1. 分类 + +这是什么类型的知识？ + +* 业务决策 -> 记忆文件（项目类型）+ MCP 记忆 +* 活跃路线图 / 发布 / 实现状态 -> 优先使用 GitHub + Linear +* 个人偏好 -> 记忆文件（用户/反馈类型） +* 参考信息 -> 记忆文件（参考类型）+ MCP 记忆 +* 大型文档 -> 外部数据存储 + 记忆中的摘要 +* 对话/会话 -> 知识库仓库 + 记忆中的简短摘要 + +### 2. 去重 + +检查此知识是否已存在： + +* 搜索记忆文件中的现有条目 +* 使用相关术语查询 MCP 记忆 +* 在创建另一个本地笔记之前，检查信息是否已存在于 GitHub 或 Linear 中 +* 不要创建重复项。而是更新现有条目。 + +### 3. 存储 + +写入适当的层级： + +* 始终更新 Claude Code 记忆以便快速访问 +* 使用 MCP 记忆实现语义可搜索性和关系映射 +* 当信息改变实时项目真相时，首先更新 GitHub / Linear +* 提交到知识库仓库以进行持久的、长格式的添加 + +### 4. 索引 + +更新任何相关的索引或摘要文件。 + +## 同步操作 + +### 对话同步 + +定期将会话历史同步到知识库： + +* 来源：Claude 会话文件、Codex 会话、其他代理会话 +* 目标：知识库仓库 +* 生成会话索引以便快速浏览 +* 提交并推送 + +### 工作区状态同步 + +将重要的工作区配置和脚本镜像到知识库： + +* 生成目录映射 +* 在提交前编辑敏感配置 +* 随时间跟踪更改 +* 不要将知识库或归档文件夹视为实时代码工作区 + +### GitHub / Linear 同步 + +当信息影响活跃执行时： + +* 更新相关的 GitHub 议题、PR、讨论、发布说明或路线图线程 +* 当工作需要持久的规划上下文时，将支持文档附加到 Linear +* 之后仅当本地笔记仍能增加价值时才进行镜像 + +### 跨源知识同步 + +将来自多个来源的知识汇集到一处： + +* Claude/ChatGPT/Grok 对话导出 +* 浏览器书签 +* GitHub 活动事件 +* 写入状态摘要，提交并推送 + +## 记忆模式 + +``` +# 短期：当前会话上下文 +使用 TodoWrite 进行会话内任务追踪 + +# 中期：项目记忆文件 +写入 ~/.claude/projects/*/memory/ 以实现跨会话回溯 + +# 长期：GitHub / Linear / 知识库 +将活跃执行事实置于 GitHub + Linear +将持久化综合上下文置于知识库仓库 + +# 语义层：MCP 知识图谱 +使用 mcp__memory__create_entities 创建永久结构化数据 +使用 mcp__memory__create_relations 进行关系映射 +使用 mcp__memory__add_observations 添加关于已知实体的新事实 +使用 mcp__memory__search_nodes 查找已有知识 +``` + +## 最佳实践 + +* 保持记忆文件简洁。归档旧数据，而不是让文件无限增长。 +* 在所有知识文件上使用前置元数据（YAML）作为元数据。 +* 存储前进行去重。先搜索，然后创建或更新。 +* 每个事实集优先使用一个权威存放位置。避免在本地笔记、仓库文件和跟踪器文档中并行复制同一计划。 +* 在提交到 Git 之前编辑敏感信息（API 密钥、密码）。 +* 对知识文件使用一致的命名约定（小写-连字符-分隔）。 +* 使用主题/类别标记条目，以便于检索。 + +## 质量门控 + +在完成任何知识操作之前： + +* 没有创建重复条目 +* 任何 Git 跟踪的文件中的敏感数据已被编辑 +* 索引和摘要已更新 +* 为数据类型选择了适当的存储层 +* 在相关处添加了交叉引用 diff --git a/docs/zh-CN/skills/project-flow-ops/SKILL.md b/docs/zh-CN/skills/project-flow-ops/SKILL.md new file mode 100644 index 00000000..8a3f77f5 --- /dev/null +++ b/docs/zh-CN/skills/project-flow-ops/SKILL.md @@ -0,0 +1,111 @@ +--- +name: project-flow-ops +description: 通过分类问题和拉取请求、关联活跃工作、保持GitHub对外可见而Linear作为内部执行层，来协调GitHub和Linear之间的执行流程。当用户需要待办事项控制、PR分类或GitHub与Linear协调时使用。 +origin: ECC +--- + +# 项目流程运营 + +此技能将分散的 GitHub Issue、PR 和 Linear 任务整合为一条执行流程。 + +当问题在于协调而非编码时使用。 + +## 使用时机 + +* 梳理开放的 PR 或 Issue 积压 +* 决定哪些应放入 Linear，哪些应保留在 GitHub 中 +* 将活跃的 GitHub 工作与内部执行通道关联 +* 将 PR 分类为：合并、移植/重建、关闭或搁置 +* 审查评论、CI 失败或过时 Issue 是否阻碍执行 + +## 运营模式 + +* **GitHub** 是公开和社区的真实来源 +* **Linear** 是内部执行的真实来源，用于活跃的已排期工作 +* 并非每个 GitHub Issue 都需要创建 Linear Issue +* 仅当工作满足以下条件时，才创建或更新 Linear： + * 活跃 + * 已委派 + * 已排期 + * 跨职能 + * 重要到需要内部跟踪 + +## 核心工作流 + +### 1. 首先阅读公开信息 + +收集： + +* GitHub Issue 或 PR 状态 +* 作者和分支状态 +* 审查评论 +* CI 状态 +* 关联的 Issue + +### 2. 对工作进行分类 + +每个项目应归入以下状态之一： + +| 状态 | 含义 | +|-------|---------| +| 合并 | 独立完整、符合策略、准备就绪 | +| 移植/重建 | 有用的想法，但应在 ECC 内部手动重新落地 | +| 关闭 | 方向错误、过时、不安全或重复 | +| 搁置 | 可能有用，但当前未排期 | + +### 3. 判断是否需要 Linear + +仅在以下情况下创建或更新 Linear： + +* 执行正在积极规划中 +* 涉及多个仓库或工作流 +* 工作需要内部所有权或排序 +* 该 Issue 是更大项目通道的一部分 + +不要机械地镜像所有内容。 + +### 4. 保持两个系统一致 + +当工作活跃时： + +* GitHub Issue/PR 应说明公开进展 +* Linear 应在内部跟踪负责人、优先级和执行通道 + +当工作完成或被拒绝时： + +* 将公开解决方案发布回 GitHub +* 相应地标记 Linear 任务 + +## 审查规则 + +* 切勿仅凭标题、摘要或信任进行合并；需使用完整差异 +* 当外部来源的功能有价值但不独立完整时，应在 ECC 内部重建 +* CI 红色表示需分类并修复或阻止；不要假装其已可合并 +* 如果真正的阻碍是产品方向，请直接说明，而非隐藏在工具背后 + +## 输出格式 + +返回： + +```text +公开状态 +- 议题 / 拉取请求状态 +- 持续集成 / 审查状态 + +分类 +- 合并 / 移植重建 / 关闭 / 搁置 +- 一段理由说明 + +线性操作 +- 创建 / 更新 / 无需线性项 +- 项目 / 泳道（如适用） + +下一步操作者行动 +- 确切的下一个步骤 +``` + +## 良好用例 + +* "审查开放的 PR 积压，告诉我哪些应合并，哪些应重建" +* "将 GitHub Issue 映射到我们的 ECC 1.x 和 ECC 2.0 项目通道" +* "检查这是否需要创建 Linear Issue，还是应保留在 GitHub 中" diff --git a/docs/zh-CN/skills/repo-scan/SKILL.md b/docs/zh-CN/skills/repo-scan/SKILL.md new file mode 100644 index 00000000..2797a290 --- /dev/null +++ b/docs/zh-CN/skills/repo-scan/SKILL.md @@ -0,0 +1,79 @@ +--- +name: repo-scan +description: 跨栈源代码资产审计——对每个文件进行分类，检测嵌入的第三方库，并为每个模块提供可操作的四级判定结果，附带交互式HTML报告。 +origin: community +--- + +# repo-scan + +> 每个生态系统都有自己的依赖管理器，但没有工具能跨 C++、Android、iOS 和 Web 告诉你：有多少代码真正属于你，哪些是第三方代码，哪些是冗余负担。 + +## 适用场景 + +* 接手大型遗留代码库，需要了解整体结构 +* 重大重构前——识别核心代码、重复代码和废弃代码 +* 审计直接嵌入源码（而非通过包管理器声明）的第三方依赖 +* 为单体仓库重组准备架构决策记录 + +## 安装 + +```bash +# Fetch only the pinned commit for reproducibility +mkdir -p ~/.claude/skills/repo-scan +git init repo-scan +cd repo-scan +git remote add origin https://github.com/haibindev/repo-scan.git +git fetch --depth 1 origin 2742664 +git checkout --detach FETCH_HEAD +cp -r . ~/.claude/skills/repo-scan +``` + +> 安装任何代理技能前，请先审查源码。 + +## 核心能力 + +| 能力 | 描述 | +|---|---| +| **跨技术栈扫描** | 一次扫描 C/C++、Java/Android、iOS（OC/Swift）、Web（TS/JS/Vue） | +| **文件分类** | 每个文件标记为项目代码、第三方代码或构建产物 | +| **库检测** | 识别 50+ 已知库（FFmpeg、Boost、OpenSSL…）并提取版本号 | +| **四级判定** | 核心资产 / 提取合并 / 重建 / 废弃 | +| **HTML 报告** | 交互式深色主题页面，支持逐层下钻导航 | +| **单体仓库支持** | 分层扫描，提供摘要 + 子项目报告 | + +## 分析深度级别 + +| 级别 | 读取文件数 | 适用场景 | +|---|---|---| +| `fast` | 每模块 1-2 个 | 快速盘点大型目录 | +| `standard` | 每模块 2-5 个 | 默认审计，含完整依赖 + 架构检查 | +| `deep` | 每模块 5-10 个 | 增加线程安全、内存管理、API 一致性检查 | +| `full` | 所有文件 | 合并前全面审查 | + +## 工作原理 + +1. **分类仓库表面**：枚举文件，将每个文件标记为项目代码、嵌入的第三方代码或构建产物。 +2. **检测嵌入的库**：检查目录名、头文件、许可证文件和版本标记，识别捆绑的依赖及其可能版本。 +3. **为每个模块评分**：按模块或子系统分组文件，根据所有权、重复度和维护成本分配四种判定之一。 +4. **突出结构风险**：指出冗余产物、重复的封装器、过时的供应商代码，以及应提取、重建或废弃的模块。 +5. **生成报告**：返回简洁摘要及交互式 HTML 输出，支持按模块下钻，便于异步审查审计结果。 + +## 示例 + +在一个 50,000 文件的 C++ 单体仓库中： + +* 发现仍在使用 FFmpeg 2.x（2015 年版本） +* 发现同一 SDK 封装器重复了 3 次 +* 识别出 636 MB 已提交的 Debug/ipch/obj 构建产物 +* 分类结果：3 MB 项目代码 vs 596 MB 第三方代码 + +## 最佳实践 + +* 首次审计时从 `standard` 深度开始 +* 对包含 100+ 模块的单体仓库使用 `fast` 快速盘点 +* 对标记为需重构的模块增量运行 `deep` +* 审查跨模块分析结果，检测子项目间的重复代码 + +## 链接 + +* [GitHub 仓库](https://github.com/haibindev/repo-scan) diff --git a/docs/zh-CN/skills/research-ops/SKILL.md b/docs/zh-CN/skills/research-ops/SKILL.md new file mode 100644 index 00000000..9b059c95 --- /dev/null +++ b/docs/zh-CN/skills/research-ops/SKILL.md @@ -0,0 +1,112 @@ +--- +name: research-ops +description: 以证据为先的ECC当前状态研究工作流程。当用户希望基于当前公开证据和提供的本地上下文获取最新事实、比较、丰富信息或建议时使用。 +origin: ECC +--- + +# 研究运营 + +当用户要求研究当前信息、比较选项、丰富人员或公司信息，或将重复查询转化为可监控的工作流时，使用此功能。 + +这是仓库研究栈的操作封装。它并非 `deep-research`、`exa-search` 或 `market-research` 的替代品；而是指示何时以及如何将它们结合使用。 + +## 技能栈 + +在相关场景下，将这些 ECC 原生技能纳入工作流： + +* `exa-search`：用于快速发现当前网络信息 +* `deep-research`：用于多源综合并附带引用 +* `market-research`：当最终结果应为建议或排序决策时使用 +* `lead-intelligence`：当任务针对人员/公司而非通用研究时使用 +* `knowledge-ops`：当结果需持久存储于后续上下文时使用 + +## 使用时机 + +* 用户提及“研究”、“查找”、“比较”、“我应该联系谁”或“最新情况” +* 答案依赖于当前的公开信息 +* 用户已提供证据，并希望将其纳入新的建议中 +* 任务可能具有重复性，应转为监控而非一次性查询 + +## 防护措施 + +* 当新鲜搜索成本低廉时，不要依赖过时记忆回答当前问题 +* 区分： + * 有来源的事实 + * 用户提供的证据 + * 推断 + * 建议 +* 如果答案已存在于本地代码或文档中，不要启动繁重的研究流程 + +## 工作流 + +### 1. 从用户已提供的信息出发 + +将任何提供的材料规范化为： + +* 已有证据的事实 +* 需要验证的内容 +* 未解决的问题 + +如果用户已构建部分模型，不要从零开始重新分析。 + +### 2. 对请求进行分类 + +在搜索前选择正确的路径： + +* 快速事实性回答 +* 比较或决策备忘录 +* 线索/丰富化处理 +* 重复监控候选 + +### 3. 优先采用最轻量的有效证据路径 + +* 使用 `exa-search` 进行快速发现 +* 当需要综合或多源信息时，升级至 `deep-research` +* 当结果需以建议形式呈现时，使用 `market-research` +* 当实际需求是目标排序或温暖路径发现时，转交至 `lead-intelligence` + +### 4. 报告时明确证据边界 + +对于重要声明，说明其属于： + +* 有来源的事实 +* 用户提供的上下文 +* 推断 +* 建议 + +对时效性敏感的答案应包含具体日期。 + +### 5. 决定任务是否应保持手动 + +如果用户可能反复提出相同的研究问题，请明确说明，并建议采用监控或工作流层，而非永远重复相同的手动搜索。 + +## 输出格式 + +```text +问题类型 +- 事实性 / 比较性 / 补充性 / 监控性 + +证据 +- 有来源的事实 +- 用户提供的上下文 + +推论 +- 从证据中得出的结论 + +建议 +- 答案或下一步行动 +- 是否应将其设为监控项 +``` + +## 常见陷阱 + +* 不要将推断混入有来源的事实而不加标注 +* 不要忽略用户提供的证据 +* 不要对本地仓库上下文能回答的问题使用繁重的研究路径 +* 不要给出不含日期的时效性敏感答案 + +## 验证 + +* 重要声明需标注证据类型 +* 时效性敏感的输出需包含日期 +* 最终建议需与实际使用的研究模式匹配 diff --git a/docs/zh-CN/skills/terminal-ops/SKILL.md b/docs/zh-CN/skills/terminal-ops/SKILL.md new file mode 100644 index 00000000..35e4fb21 --- /dev/null +++ b/docs/zh-CN/skills/terminal-ops/SKILL.md @@ -0,0 +1,109 @@ +--- +name: terminal-ops +description: 基于证据优先的仓库执行工作流，适用于ECC。当用户需要运行命令、检查仓库、调试CI失败或推送带有精确执行和验证证明的窄修复时使用。 +origin: ECC +--- + +# 终端操作 + +当用户需要真实的仓库执行时使用此技能：运行命令、检查 git 状态、调试 CI 或构建、进行窄幅修复，并准确报告更改和验证的内容。 + +此技能有意比通用编码指导更窄。它是一种以证据为先的终端执行操作工作流。 + +## 技能栈 + +在相关时，将这些 ECC 原生技能引入工作流： + +* `verification-loop` 用于更改后的精确验证步骤 +* `tdd-workflow` 当正确的修复需要回归覆盖时 +* `security-review` 当涉及密钥、认证或外部输入时 +* `github-ops` 当任务依赖于 CI 运行、PR 状态或发布状态时 +* `knowledge-ops` 当需要将验证结果捕获到持久的项目上下文中时 + +## 使用时机 + +* 用户说"修复"、"调试"、"运行这个"、"检查仓库"或"推送它" +* 任务依赖于命令输出、git 状态、测试结果或已验证的本地修复 +* 答案必须区分：本地已更改、本地已验证、已提交和已推送 + +## 安全护栏 + +* 先检查再编辑 +* 如果用户仅要求审计/审查，则保持只读 +* 优先使用仓库本地的脚本和辅助工具，而非即兴的临时封装 +* 在验证命令重新运行之前，不得声称已修复 +* 除非分支确实已推送到上游，否则不得声称已推送 + +## 工作流 + +### 1. 确定工作表面 + +明确： + +* 确切的仓库路径 +* 分支 +* 本地差异状态 +* 请求的模式： + * 检查 + * 修复 + * 验证 + * 推送 + +### 2. 首先读取失败表面 + +在更改任何内容之前： + +* 检查错误 +* 检查文件或测试 +* 检查 git 状态 +* 在盲目重新读取之前，使用任何已提供的日志或上下文 + +### 3. 保持修复的窄幅 + +一次解决一个主要失败： + +* 首先使用最小的有用验证命令 +* 仅在本地失败解决后，才升级到更大的构建/测试流程 +* 如果某个命令持续以相同特征失败，停止广泛重试并缩小范围 + +### 4. 报告确切的执行状态 + +使用确切的状态词： + +* 已检查 +* 本地已更改 +* 本地已验证 +* 已提交 +* 已推送 +* 已阻塞 + +## 输出格式 + +```text +表面 +- 仓库 +- 分支 +- 请求模式 + +证据 +- 失败的命令 / 差异 / 测试 + +操作 +- 变更内容 + +状态 +- 已检查 / 本地已更改 / 本地已验证 / 已提交 / 已推送 / 已阻止 +``` + +## 陷阱 + +* 当可以读取实时仓库状态时，不要依赖过时的记忆 +* 不要将窄幅修复扩大为仓库范围的变动 +* 不要使用破坏性的 git 命令 +* 不要忽略不相关的本地工作 + +## 验证 + +* 响应中需指明验证命令或测试 +* 与 git 相关的工作需指明仓库路径和分支 +* 任何推送声明需包含目标分支和确切结果 diff --git a/docs/zh-CN/skills/workspace-surface-audit/SKILL.md b/docs/zh-CN/skills/workspace-surface-audit/SKILL.md new file mode 100644 index 00000000..7e7529b5 --- /dev/null +++ b/docs/zh-CN/skills/workspace-surface-audit/SKILL.md @@ -0,0 +1,125 @@ +--- +name: workspace-surface-audit +description: 审计活跃仓库、MCP服务器、插件、连接器、环境表面和工具设置，然后推荐最高价值的ECC原生技能、钩子、代理和操作员工作流。当用户希望帮助设置Claude Code或了解其环境中实际可用的功能时使用。 +origin: ECC +--- + +# 工作区表面审计 + +只读审计技能，用于回答"这个工作区和机器当前实际上能做什么，以及我们下一步应该添加或启用什么？" + +这是 ECC 原生对设置审计插件的回答。除非用户明确要求后续实现，否则不会修改文件。 + +## 何时使用 + +* 用户说"设置 Claude Code"、"推荐自动化"、"我应该使用什么插件或 MCP？"或"我缺少什么？" +* 在安装更多技能、钩子或连接器之前审计机器或仓库 +* 比较官方市场插件与 ECC 原生覆盖范围 +* 审查 `.env`、`.mcp.json`、插件设置或连接的应用表面，以发现缺失的工作流层 +* 决定某项能力应该是技能、钩子、代理、MCP 还是外部连接器 + +## 不可协商的规则 + +* 绝不打印秘密值。仅显示提供商名称、能力名称、文件路径以及密钥或配置是否存在。 +* 当 ECC 能够合理拥有该表面时，优先选择 ECC 原生工作流，而非通用的"安装另一个插件"建议。 +* 将外部插件视为基准和灵感，而非权威的产品边界。 +* 清晰区分三件事： + * 当前已可用的 + * 可用但 ECC 封装不佳的 + * 不可用且需要新集成的 + +## 审计输入 + +仅检查回答该问题所需的文件和设置： + +1. 仓库表面 + * `package.json`、锁定文件、语言标记、框架配置、`README.md` + * `.mcp.json`、`.lsp.json`、`.claude/settings*.json`、`.codex/*` + * `AGENTS.md`、`CLAUDE.md`、安装清单、钩子配置 +2. 环境表面 + * 活动仓库及明显相邻的 ECC 工作区中的 `.env*` 文件 + * 仅显示密钥名称，如 `STRIPE_API_KEY`、`TWILIO_AUTH_TOKEN`、`FAL_KEY` +3. 连接工具表面 + * 已安装的插件、已启用的连接器、MCP 服务器、LSP 和应用集成 +4. ECC 表面 + * 已覆盖需求的现有技能、命令、钩子、代理和安装模块 + +## 审计流程 + +### 阶段 1：盘点现有内容 + +生成简洁的清单： + +* 活动的工具链目标 +* 已安装的插件和连接的应用 +* 已配置的 MCP 服务器 +* 已配置的 LSP 服务器 +* 由密钥名称暗示的基于环境的服务 +* 与工作区相关的现有 ECC 技能 + +如果某个表面仅以原始形式存在，请指出。例如： + +* "Stripe 可通过连接的应用使用，但 ECC 缺少计费操作技能" +* "Google Drive 已连接，但 ECC 没有原生的 Google Workspace 操作工作流" + +### 阶段 2：与官方和已安装表面进行基准比较 + +将工作区与以下内容进行比较： + +* 与设置、审查、文档、设计或工作流质量重叠的官方 Claude 插件 +* Claude 或 Codex 中本地安装的插件 +* 用户当前连接的应用表面 + +不要仅列出名称。对于每个比较，回答： + +1. 它们实际做什么 +2. ECC 是否已具备同等能力 +3. ECC 是否仅有原始形式 +4. ECC 是否完全缺失该工作流 + +### 阶段 3：将差距转化为 ECC 决策 + +对于每个实际差距，推荐正确的 ECC 原生形态： + +| 差距类型 | 首选 ECC 形态 | +|----------|---------------------| +| 可重复的操作工作流 | 技能 | +| 自动执行或副作用 | 钩子 | +| 专门的委派角色 | 代理 | +| 外部工具桥接 | MCP 服务器或连接器 | +| 安装/引导指南 | 设置或审计技能 | + +当需求是操作性的而非基础设施性的时，默认使用面向用户的技能来编排现有工具。 + +## 输出格式 + +按此顺序返回五个部分： + +1. **当前表面** + * 当前已可用的内容 +2. **同等能力** + * ECC 已匹配或超越基准的地方 +3. **仅有原始形式的差距** + * 工具存在，但 ECC 缺少简洁的操作技能 +4. **缺失的集成** + * 尚不可用的能力 +5. **前 3-5 个下一步行动** + * 具体的 ECC 原生新增内容，按影响排序 + +## 推荐规则 + +* 每个类别最多推荐 1-2 个最高价值的想法。 +* 优先选择具有明显用户意图和商业价值的技能： + * 设置审计 + * 计费/客户运营 + * 问题/项目运营 + * Google Workspace 运营 + * 部署/运营控制 +* 如果连接器是公司特定的，仅在其确实可用或对用户工作流明显有用时才推荐。 +* 如果 ECC 已有强大的原始形式，建议封装技能而非发明全新的子系统。 + +## 良好结果 + +* 用户可以立即看到已连接的内容、缺失的内容以及 ECC 下一步应拥有的内容。 +* 推荐足够具体，无需再次发现即可在仓库中实现。 +* 最终答案围绕工作流而非 API 品牌组织。