hai/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-05-12 15:47:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: salvage remaining stable zh-CN skill translations

Browse Source
This commit is contained in:
Affaan Mustafa
2026-05-11 15:18:26 -04:00
committed by Affaan Mustafa
parent c3246dbe34
commit 4e88912a58
17 changed files with 2961 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
docs/zh-CN/skills/accessibility/SKILL.md Normal file
View File

@@ -0,0 +1,145 @@
---
name: accessibility
description: 使用 WCAG 2.2 Level AA 标准设计、实施和审计包容性数字产品。运用此技能为 Web 生成语义 ARIA，并为 Web 和原生平台（iOS/Android）生成无障碍特性。
origin: ECC
---
# 无障碍性（WCAG 2.2）
本技能确保数字界面对于所有用户（包括使用屏幕阅读器、开关控制或键盘导航的用户）具有可感知性、可操作性、可理解性和健壮性（POUR）。它专注于 WCAG 2.2 成功标准的技术实现。
## 使用时机
* 定义 Web、iOS 或 Android 的 UI 组件规范。
* 审计现有代码中的无障碍性障碍或合规性差距。
* 实现新的 WCAG 2.2 标准，如目标尺寸（最小）和焦点外观。
* 将高层设计需求映射到技术属性（ARIA 角色、特性、提示）。
## 核心概念
* **POUR 原则**：WCAG 的基础（可感知、可操作、可理解、健壮）。
* **语义映射**：使用原生元素而非通用容器，以提供内置的无障碍性。
* **无障碍树**：辅助技术实际“读取”的 UI 表示。
* **焦点管理**：控制键盘/屏幕阅读器光标的顺序和可见性。
* **标签与提示**：通过 `aria-label`、`accessibilityLabel` 和 `contentDescription` 提供上下文。
## 工作原理
### 步骤 1：识别组件角色
确定功能目的（例如，这是按钮、链接还是标签页？）。在诉诸自定义角色之前，优先使用最语义化的原生元素。
### 步骤 2：定义可感知属性
* 确保文本对比度达到 **4.5:1**（正常文本）或 **3:1**（大文本/UI 组件）。
* 为非文本内容（图像、图标）添加文本替代方案。
* 实现响应式重排（放大至 400% 时功能不丢失）。
### 步骤 3：实现可操作控件
* 确保最小 **24x24 CSS 像素** 的目标尺寸（WCAG 2.2 SC 2.5.8）。
* 验证所有交互元素可通过键盘访问，并具有可见的焦点指示器（SC 2.4.11）。
* 为拖拽操作提供单指针替代方案。
### 步骤 4：确保可理解逻辑
* 使用一致的导航模式。
* 提供描述性错误消息和更正建议（SC 3.3.3）。
* 实现“冗余输入”（SC 3.3.7），避免重复询问相同数据。
### 步骤 5：验证健壮兼容性
* 使用正确的 `Name, Role, Value` 模式。
* 为动态状态更新实现 `aria-live` 或活动区域。
## 无障碍架构图
```mermaid
flowchart TD
UI["UI Component"] --> Platform{Platform?}
Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
Platform -->|iOS| SwiftUI["Accessibility Traits + Labels"]
Platform -->|Android| Compose["Semantics + ContentDesc"]
ARIA --> AT["Assistive Technology (Screen Readers, Switches)"]
SwiftUI --> AT
Compose --> AT
```
## 跨平台映射
| 特性 | Web (HTML/ARIA) | iOS (SwiftUI) | Android (Compose) |
| :--------------- | :----------------------- | :----------------------------------- | :---------------------------------------------------------- |
| **主标签** | `aria-label` / `<label>` | `.accessibilityLabel()` | `contentDescription` |
| **辅助提示** | `aria-describedby` | `.accessibilityHint()` | `Modifier.semantics { stateDescription = ... }` |
| **操作角色** | `role="button"` | `.accessibilityAddTraits(.isButton)` | `Modifier.semantics { role = Role.Button }` |
| **实时更新** | `aria-live="polite"` | `.accessibilityLiveRegion(.polite)` | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
## 示例
### Web：无障碍搜索
```html
<form role="search">
<label for="search-input" class="sr-only">Search products</label>
<input type="search" id="search-input" placeholder="Search..." />
<button type="submit" aria-label="Submit Search">
<svg aria-hidden="true">...</svg>
</button>
</form>
```
### iOS：无障碍操作按钮
```swift
Button(action: deleteItem) {
Image(systemName: "trash")
}
.accessibilityLabel("Delete item")
.accessibilityHint("Permanently removes this item from your list")
.accessibilityAddTraits(.isButton)
```
### Android：无障碍切换开关
```kotlin
Switch(
checked = isEnabled,
onCheckedChange = { onToggle() },
modifier = Modifier.semantics {
contentDescription = "Enable notifications"
}
)
```
## 应避免的反模式
* **Div 按钮**：使用 `<div>` 或 `<span>` 处理点击事件，但未添加角色和键盘支持。
* **仅用颜色传达含义**：仅通过颜色变化（例如，将边框变为红色）来指示错误或状态。
* **未限制的模态焦点**：模态框未限制焦点，导致键盘用户在模态框打开时仍可导航背景内容。焦点必须被限制，并且可通过 `Escape` 键或显式关闭按钮退出（WCAG SC 2.1.2）。
* **冗余替代文本**：在替代文本中使用“图像...”或“图片...”（屏幕阅读器已宣布“图像”角色）。
## 最佳实践检查清单
* \[ ] 交互元素满足 **24x24px**（Web）或 **44x44pt**（原生）的目标尺寸。
* \[ ] 焦点指示器清晰可见且高对比度。
* \[ ] 模态框在打开时**限制焦点**，并在关闭时干净地释放焦点（`Escape` 键或关闭按钮）。
* \[ ] 下拉菜单和菜单在关闭时将焦点恢复到触发元素。
* \[ ] 表单提供基于文本的错误建议。
* \[ ] 所有仅图标按钮都有描述性文本标签。
* \[ ] 文本缩放时内容正确重排。
## 参考
* [WCAG 2.2 指南](https://www.w3.org/TR/WCAG22/)
* [WAI-ARIA 创作实践](https://www.w3.org/TR/wai-aria-practices/)
* [iOS 无障碍编程指南](https://developer.apple.com/documentation/accessibility)
* [iOS 人机界面指南 - 无障碍](https://developer.apple.com/design/human-interface-guidelines/accessibility)
* [Android 无障碍开发者指南](https://developer.android.com/guide/topics/ui/accessibility)
## 相关技能
* `frontend-patterns`
* `design-system`
* `liquid-glass-design`
* `swiftui-patterns`

161
docs/zh-CN/skills/agent-introspection-debugging/SKILL.md Normal file
View File

@@ -0,0 +1,161 @@
---
name: agent-introspection-debugging
description: 针对AI代理故障的结构化自调试工作流程，包括捕获、诊断、受限恢复和内省报告。
origin: ECC
---
# 智能体内省调试
当智能体运行反复失败、消耗令牌却无进展、在相同工具上循环或偏离预期任务时，使用此技能。
这是一个工作流技能，而非隐藏运行时。它教会智能体在升级给人类之前，系统性地自我调试。
## 何时激活
* 达到最大工具调用/循环限制失败
* 重复重试但无任何进展
* 上下文增长或提示漂移导致输出质量下降
* 文件系统或环境状态与预期不匹配
* 可通过诊断和较小纠正措施恢复的工具故障
## 范围边界
激活此技能用于：
* 在盲目重试前捕获失败状态
* 诊断常见的智能体特定失败模式
* 应用受限的恢复操作
* 生成结构化的人类可读调试报告
请勿将此技能作为以下情况的主要来源：
* 代码变更后的功能验证；请使用 `verification-loop`
* 当已有更窄的 ECC 技能时的框架特定调试
* 当前框架无法自动强制执行的运行时承诺
## 四阶段循环
### 阶段 1：失败捕获
在尝试恢复之前，精确记录失败信息。
捕获内容：
* 错误类型、消息和堆栈跟踪（如可用）
* 最后有意义的工具调用序列
* 智能体当时试图完成的任务
* 当前上下文压力：重复提示、过大的粘贴日志、重复的计划或失控的笔记
* 当前环境假设：工作目录、分支、相关服务状态、预期文件
最小捕获模板：
```markdown
## 失败捕获
- 会话/任务：
- 进行中的目标：
- 错误：
- 最后成功的步骤：
- 最后失败的工具/命令：
- 观察到的重复模式：
- 需验证的环境假设：
```
### 阶段 2：根因诊断
在更改任何内容之前，将失败与已知模式匹配。
| 模式 | 可能原因 | 检查 |
| --- | --- | --- |
| 最大工具调用/重复相同命令 | 循环或无退出观察路径 | 检查最后 N 次工具调用是否存在重复 |
| 上下文溢出/推理能力下降 | 无界笔记、重复计划、过大日志 | 检查近期上下文是否存在重复和低信号批量内容 |
| `ECONNREFUSED` / 超时 | 服务不可用或端口错误 | 验证服务健康状态、URL 和端口假设 |
| `429` / 配额耗尽 | 重试风暴或缺少退避 | 统计重复调用次数并检查重试间隔 |
| 写入后文件缺失/差异过时 | 竞态、工作目录错误或分支漂移 | 重新检查路径、工作目录、git 状态和实际文件是否存在 |
| “修复”后测试仍然失败 | 假设错误 | 隔离确切失败的测试并重新推导错误 |
诊断问题：
* 这是逻辑失败、状态失败、环境失败还是策略失败？
* 智能体是否丢失了真实目标并开始优化错误的子任务？
* 失败是确定性的还是瞬态的？
* 能够验证诊断的最小可逆操作是什么？
### 阶段 3：受限恢复
使用改变诊断面的最小操作进行恢复。
安全恢复操作：
* 停止重复重试并重新陈述假设
* 修剪低信号上下文，仅保留活跃目标、阻碍因素和证据
* 重新检查实际文件系统/分支/进程状态
* 将任务缩小到一个失败的命令、一个文件或一个测试
* 从推测性推理切换到直接观察
* 当失败风险高或受外部阻碍时升级给人类
不要声称不支持的自动修复操作，如“重置智能体状态”或“更新框架配置”，除非你正在当前环境中通过真实工具实际执行这些操作。
受限恢复检查清单：
```markdown
## 恢复操作
- 选择的诊断方式：
- 采取的最小操作：
- 为何此操作安全：
- 哪些证据能证明修复生效：
```
### 阶段 4：内省报告
以一份使恢复过程对下一个智能体或人类清晰可读的报告结束。
```markdown
## 代理自调试报告
- 会话/任务：
- 失败原因：
- 根本原因：
- 恢复措施：
- 结果：成功 | 部分成功 | 受阻
- Token/时间消耗风险：
- 是否需要后续跟进：
- 后续需编码的预防性变更：
```
## 恢复启发式方法
按顺序优先选择以下干预措施：
1. 用一句话重新陈述真实目标。
2. 验证世界状态，而非依赖记忆。
3. 缩小失败范围。
4. 运行一次判别性检查。
5. 然后才重试。
错误模式：
* 用略微不同的措辞重复相同操作三次
正确模式：
* 捕获失败
* 分类模式
* 运行一次直接检查
* 仅当检查支持时才更改计划
## 与 ECC 集成
* 如果代码已更改，在恢复后使用 `verification-loop`。
* 当失败模式值得转化为本能或后续技能时，使用 `continuous-learning-v2`。
* 当问题不是技术失败而是决策模糊时，使用 `council`。
* 如果失败源于冲突的本地状态或仓库漂移，使用 `workspace-surface-audit`。
## 输出标准
当此技能激活时，不要仅以“我已修复”结束。
始终提供：
* 失败模式
* 根因假设
* 恢复操作
* 证明情况已改善或仍受阻的证据

215
docs/zh-CN/skills/agent-sort/SKILL.md Normal file
View File

@@ -0,0 +1,215 @@
---
name: agent-sort
description: 通过将技能、命令、规则、钩子和额外内容并行进行仓库感知审查，为特定仓库构建基于证据的 ECC 安装计划，将其分为 DAILY 和 LIBRARY 两类。当 ECC 应精简为项目实际所需而非加载完整包时使用。
origin: ECC
---
# 技能分类
当仓库需要项目特定的 ECC 表面而非默认完整安装时，使用此技能。
目标不是猜测"什么感觉有用"。目标是根据实际代码库中的证据对 ECC 组件进行分类。
## 何时使用
* 项目只需要 ECC 的子集，完整安装过于嘈杂
* 仓库技术栈明确，但无人希望逐个手动筛选技能
* 团队希望获得基于 grep 证据而非主观意见的可重复安装决策
* 需要将始终加载的日常工作流表面与可搜索的库/参考表面分离
* 仓库已偏离至错误的语言、规则或钩子集，需要清理
## 不可协商的规则
* 以当前仓库为事实来源，而非通用偏好
* 每个 DAILY 决策必须引用具体的仓库证据
* LIBRARY 并不意味着"删除"；它意味着"保持可访问但不默认加载"
* 不要安装当前仓库无法使用的钩子、规则或脚本
* 优先使用 ECC 原生表面；不要引入第二个安装系统
## 输出
按顺序生成以下工件：
1. DAILY 清单
2. LIBRARY 清单
3. 安装计划
4. 验证报告
5. 可选的路由器（如果项目需要）
## 分类模型
仅使用两个分类：
* `DAILY`
* 应为该仓库的每个会话加载
* 与仓库的语言、框架、工作流或操作者表面强匹配
* `LIBRARY`
* 保留有用，但不值得默认加载
* 应通过搜索、路由器技能或选择性手动使用保持可访问
## 证据来源
在进行任何分类之前，使用仓库本地证据：
* 文件扩展名
* 包管理器和锁文件
* 框架配置
* CI 和钩子配置
* 构建/测试脚本
* 导入和依赖清单
* 明确描述技术栈的仓库文档
有用的命令包括：
```bash
rg --files
rg -n "typescript|react|next|supabase|django|spring|flutter|swift"
cat package.json
cat pyproject.toml
cat Cargo.toml
cat pubspec.yaml
cat go.mod
```
## 并行审查轮次
如果并行子代理可用，将审查分为以下轮次：
1. 代理
* 分类 `agents/*`
2. 技能
* 分类 `skills/*`
3. 命令
* 分类 `commands/*`
4. 规则
* 分类 `rules/*`
5. 钩子和脚本
* 分类钩子表面、MCP 健康检查、辅助脚本和操作系统兼容性
6. 额外项
* 分类上下文、示例、MCP 配置、模板和指导文档
如果子代理不可用，则按顺序运行相同的轮次。
## 核心工作流
### 1. 读取仓库
在分类任何内容之前，确定实际技术栈：
* 使用的语言
* 使用的框架
* 主要包管理器
* 测试技术栈
* 代码检查/格式化技术栈
* 部署/运行时表面
* 已存在的操作者集成
### 2. 构建证据表
对于每个候选表面，记录：
* 组件路径
* 组件类型
* 建议的分类
* 仓库证据
* 简短理由
使用此格式：
```text
skills/frontend-patterns | skill | DAILY | 84 个 .tsx 文件，存在 next.config.ts | 核心前端技术栈
skills/django-patterns | skill | LIBRARY | 无 .py 文件，无 pyproject.toml | 此仓库中未激活
rules/typescript/* | rules | DAILY | 存在 package.json + tsconfig.json | 活跃的 TS 仓库
rules/python/* | rules | LIBRARY | 零个 Python 源文件 | 仅保持可访问
```
### 3. 决定 DAILY 还是 LIBRARY
提升至 `DAILY` 当：
* 仓库明确使用匹配的技术栈
* 组件足够通用，有助于每个会话
* 仓库已依赖相应的运行时或工作流
降级至 `LIBRARY` 当：
* 组件与技术栈不匹配
* 仓库可能以后需要，但不是每天
* 它增加了上下文开销而无直接相关性
### 4. 构建安装计划
将分类转化为行动：
* DAILY 技能 -> 安装或保留在 `.claude/skills/`
* DAILY 命令 -> 仅当仍然有用时保留为显式 shim
* DAILY 规则 -> 仅安装匹配的语言集
* DAILY 钩子/脚本 -> 仅保留兼容的
* LIBRARY 表面 -> 通过搜索或 `skill-library` 保持可访问
如果仓库已使用选择性安装，则更新该计划而非创建另一个系统。
### 5. 创建可选的路由器
如果项目需要可搜索的库表面，创建：
* `.claude/skills/skill-library/SKILL.md`
该路由器应包含：
* DAILY 与 LIBRARY 的简短说明
* 分组的触发关键词
* 库参考的存放位置
不要在路由器内重复每个技能的主体。
### 6. 验证结果
应用计划后，验证：
* 每个 DAILY 文件存在于预期位置
* 未保留过时的语言规则
* 未安装不兼容的钩子
* 最终安装确实匹配仓库技术栈
返回一个简洁的报告，包含：
* DAILY 数量
* LIBRARY 数量
* 移除的过时表面
* 未解决的问题
## 交接
如果下一步是交互式安装或修复，交接至：
* `configure-ecc`
如果下一步是重叠清理或目录审查，交接至：
* `skill-stocktake`
如果下一步是更广泛的上下文修剪，交接至：
* `strategic-compact`
## 输出格式
按此顺序返回结果：
```text
栈
- 语言/框架/运行时摘要
日常
- 始终加载的条目及证据
库
- 可搜索/参考的条目及证据
安装计划
- 应安装、移除或路由的内容
验证
- 已运行的检查及剩余差距
```

120
docs/zh-CN/skills/api-connector-builder/SKILL.md Normal file
View File

@@ -0,0 +1,120 @@
---
name: api-connector-builder
description: 通过匹配目标仓库现有的集成模式，构建一个新的API连接器或提供者。适用于在不发明第二种架构的情况下添加一个集成。
origin: ECC direct-port adaptation
version: "1.0.0"
---
# API 连接器构建器
当任务需要添加仓库原生的集成接口，而非仅通用 HTTP 客户端时使用此工具。
关键在于匹配宿主仓库的模式：
* 连接器布局
* 配置模式
* 认证模型
* 错误处理
* 测试风格
* 注册/发现机制
## 使用时机
* "为此项目构建 Jira 连接器"
* "按照现有模式添加 Slack 提供商"
* "为此 API 创建新集成"
* "构建符合仓库连接器风格的插件"
## 约束条件
* 若仓库已有集成架构，不得自行发明新架构
* 不得仅从供应商文档入手；应优先参考仓库内现有连接器
* 若仓库需要注册机制、测试和文档，不得仅停留在传输代码层面
* 若仓库有更新的当前模式，不得盲目复制旧连接器
## 工作流程
### 1. 学习内部风格
检查至少 2 个现有连接器/提供商，并映射：
* 文件布局
* 抽象边界
* 配置模型
* 重试/分页约定
* 注册钩子
* 测试夹具和命名规范
### 2. 缩小目标集成范围
仅定义仓库实际需要的接口：
* 认证流程
* 关键实体
* 核心读写操作
* 分页和速率限制
* Webhook 或轮询模型
### 3. 按仓库原生层次构建
典型分层：
* 配置/模式
* 客户端/传输层
* 映射层
* 连接器/提供商入口
* 注册机制
* 测试
### 4. 对照源模式验证
新连接器应在代码库中显得自然，而非从不同生态导入。
## 参考模板
### 提供商风格
```text
providers/
existing_provider/
__init__.py
provider.py
config.py
```
### 连接器风格
```text
integrations/
existing/
client.py
models.py
connector.py
```
### TypeScript 插件风格
```text
src/integrations/
existing/
index.ts
client.ts
types.ts
test.ts
```
## 质量检查清单
* \[ ] 匹配仓库内现有集成模式
* \[ ] 存在配置验证
* \[ ] 认证和错误处理明确
* \[ ] 分页/重试行为遵循仓库规范
* \[ ] 注册/发现机制完整
* \[ ] 测试镜像宿主仓库风格
* \[ ] 若仓库要求，更新文档/示例
## 相关技能
* `backend-patterns`
* `mcp-server-patterns`
* `github-ops`

279
docs/zh-CN/skills/autonomous-agent-harness/SKILL.md Normal file
View File

@@ -0,0 +1,279 @@
---
name: autonomous-agent-harness
description: 将 Claude Code 转变为具有持久记忆、定时操作、计算机使用和任务队列的完全自主代理系统。通过利用 Claude Code 的原生定时任务、调度、MCP 工具和记忆，取代独立的代理框架（Hermes、AutoGPT）。当用户需要持续自主操作、定时任务或自我导向的代理循环时使用。
origin: ECC
---
# 自主代理框架
仅使用原生功能和 MCP 服务器，将 Claude Code 转变为持久化、自我导向的代理系统。
## 同意与安全边界
自主操作必须由用户明确请求并划定范围。除非用户已批准该能力以及当前设置的目标工作空间，否则不得创建计划、调度远程代理、写入持久化内存、使用计算机控制、发布外部内容、修改第三方资源或处理私人通信。
在启用定期或事件驱动操作之前，优先使用预演计划和本地队列文件。将凭据、私有工作空间导出、个人数据集和账户特定自动化排除在可复用的 ECC 工件之外。
## 何时激活
* 用户需要一个持续运行或按计划运行的代理
* 设置定期触发的自动化工作流
* 构建一个跨会话记住上下文的个人 AI 助手
* 用户说“每天运行这个”、“定期检查这个”、“持续监控”
* 希望复制 Hermes、AutoGPT 或类似自主代理框架的功能
* 需要计算机使用与计划执行相结合
## 架构
```
┌──────────────────────────────────────────────────────────────┐
│ Claude Code 运行时 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│ │ 定时任务 │ │ 远程调度 │ │ 记忆存储 │ │ 计算机使用 │ │
│ │ 调度器 │ │ 代理 │ │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ ECC 技能 + 代理层 │ │
│ │ │ │
│ │ skills/ agents/ commands/ hooks/ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ MCP 服务器层 │ │
│ │ │ │
│ │ memory github exa supabase browser-use │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
## 核心组件
### 1. 持久化内存
使用 Claude Code 的内置内存系统，并通过 MCP 内存服务器增强以处理结构化数据。
**内置内存**（`~/.claude/projects/*/memory/`）：
* 用户偏好、反馈、项目上下文
* 存储为带有前置元数据的 Markdown 文件
* 在会话启动时自动加载
**MCP 内存服务器**（结构化知识图谱）：
* 实体、关系、观察
* 可查询的图结构
* 跨会话持久化
**内存模式：**
```
# 短期：当前会话上下文
使用 TodoWrite 进行会话内任务追踪
# 中期：项目记忆文件
写入 ~/.claude/projects/*/memory/ 以实现跨会话回忆
# 长期：MCP 知识图谱
使用 mcp__memory__create_entities 创建永久结构化数据
使用 mcp__memory__create_relations 进行关系映射
使用 mcp__memory__add_observations 添加关于已知实体的新事实
```
### 2. 计划操作（定时任务）
使用 Claude Code 的计划任务创建定期代理操作。
**设置定时任务：**
```
# Via MCP tool
mcp__scheduled-tasks__create_scheduled_task({
name: "daily-pr-review",
schedule: "0 9 * * 1-5", # 工作日上午9点
prompt: "Review all open PRs in affaan-m/everything-claude-code. For each: check CI status, review changes, flag issues. Post summary to memory.",
project_dir: "/path/to/repo"
})
# Via claude -p (程序化模式)
echo "Review open PRs and summarize" | claude -p --project /path/to/repo
```
**有用的定时任务模式：**
| 模式 | 计划 | 用例 |
|---------|----------|----------|
| 每日站会 | `0 9 * * 1-5` | 审查 PR、问题、部署状态 |
| 每周回顾 | `0 10 * * 1` | 代码质量指标、测试覆盖率 |
| 每小时监控 | `0 * * * *` | 生产健康、错误率检查 |
| 夜间构建 | `0 2 * * *` | 运行完整测试套件、安全扫描 |
| 会前准备 | `*/30 * * * *` | 为即将到来的会议准备上下文 |
### 3. 调度 / 远程代理
远程触发 Claude Code 代理以进行事件驱动的工作流。
**调度模式：**
```bash
# Trigger from CI/CD
curl -X POST "https://api.anthropic.com/dispatch" \
-H "Authorization: Bearer $ANTHROPIC_API_KEY" \
-d '{"prompt": "Build failed on main. Diagnose and fix.", "project": "/repo"}'
# Trigger from webhook
# GitHub webhook → dispatch → Claude agent → fix → PR
# Trigger from another agent
claude -p "Analyze the output of the security scan and create issues for findings"
```
### 4. 计算机使用
利用 Claude 的计算机使用 MCP 进行物理世界交互。
**能力：**
* 浏览器自动化（导航、点击、填写表单、截图）
* 桌面控制（打开应用、输入、鼠标控制）
* 超越 CLI 的文件系统操作
**在框架内的用例：**
* Web UI 的自动化测试
* 表单填写和数据录入
* 基于截图的监控
* 多应用工作流
### 5. 任务队列
管理一个跨会话边界的持久化任务队列。
**实现：**
```
# 通过记忆实现任务持久化
将任务队列写入 ~/.claude/projects/*/memory/task-queue.md
# 任务格式
---
name: task-queue
type: project
description: 用于自主操作的持久化任务队列
---
## 活跃任务
- [ ] PR #123: 审查并在CI通过后批准
- [ ] 监控部署：每30分钟检查一次 /health，持续2小时
- [ ] 调研：在AI工具领域寻找5个潜在客户
## 已完成
- [x] 每日站会：审查了3个PR，2个问题
```
## 替换 Hermes
| Hermes 组件 | ECC 等效组件 | 如何实现 |
|------------------|---------------|-----|
| 网关/路由器 | Claude Code 调度 + 定时任务 | 计划任务触发代理会话 |
| 内存系统 | Claude 内存 + MCP 内存服务器 | 内置持久化 + 知识图谱 |
| 工具注册表 | MCP 服务器 | 动态加载的工具提供者 |
| 编排 | ECC 技能 + 代理 | 技能定义指导代理行为 |
| 计算机使用 | 计算机使用 MCP | 原生浏览器和桌面控制 |
| 上下文管理器 | 会话管理 + 内存 | ECC 2.0 会话生命周期 |
| 任务队列 | 内存持久化任务列表 | TodoWrite + 内存文件 |
## 设置指南
### 步骤 1：配置 MCP 服务器
确保这些在 `~/.claude.json` 中：
```json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@anthropic/memory-mcp-server"]
},
"scheduled-tasks": {
"command": "npx",
"args": ["-y", "@anthropic/scheduled-tasks-mcp-server"]
},
"computer-use": {
"command": "npx",
"args": ["-y", "@anthropic/computer-use-mcp-server"]
}
}
}
```
### 步骤 2：创建基础定时任务
```bash
# Daily morning briefing
claude -p "Create a scheduled task: every weekday at 9am, review my GitHub notifications, open PRs, and calendar. Write a morning briefing to memory."
# Continuous learning
claude -p "Create a scheduled task: every Sunday at 8pm, extract patterns from this week's sessions and update the learned skills."
```
### 步骤 3：初始化内存图谱
```bash
# Bootstrap your identity and context
claude -p "Create memory entities for: me (user profile), my projects, my key contacts. Add observations about current priorities."
```
### 步骤 4：启用计算机使用（可选）
授予计算机使用 MCP 浏览器和桌面控制所需的权限。
## 示例工作流
### 自主 PR 审查员
```
Cron: 工作时间内每30分钟执行一次
1. 检查关注仓库的新PR
2. 对每个新PR：
- 在本地拉取分支
- 运行测试
- 使用代码审查代理审查变更
- 通过GitHub MCP发布审查评论
3. 更新审查状态到记忆库
```
### 个人研究代理
```
Cron: 每天上午6点执行
1. 检查内存中保存的搜索查询
2. 对每个查询运行Exa搜索
3. 总结新发现
4. 与昨日结果进行对比
5. 将摘要写入内存
6. 标记高优先级项目供晨间审阅
```
### 会议准备代理
```
触发条件：每个日历事件前30分钟
1. 读取日历事件详情
2. 搜索记忆中关于参会者的背景信息
3. 提取与参会者近期的邮件/Slack讨论记录
4. 准备谈话要点和议程建议
5. 将准备文档写入记忆
```
## 约束
* 定时任务在隔离的会话中运行——除非通过内存，否则它们不与交互式会话共享上下文。
* 计算机使用需要明确的权限授予。不要假设可以访问。
* 远程调度可能有速率限制。设计定时任务时使用适当的间隔。
* 内存文件应保持简洁。归档旧数据，而不是让文件无限增长。
* 始终验证计划任务是否成功完成。在定时任务提示中添加错误处理。

94
docs/zh-CN/skills/benchmark/SKILL.md Normal file
View File

@@ -0,0 +1,94 @@
---
name: benchmark
description: 使用此技能测量性能基线，检测PR前后的回归，并比较堆栈替代方案。
origin: ECC
---
# 基准测试 — 性能基线及回归检测
## 使用场景
* 在 PR 前后测量性能影响
* 为项目建立性能基线
* 用户反馈"感觉变慢"时
* 发布前确保达到性能目标
* 对比不同技术栈的性能表现
## 工作原理
### 模式 1：页面性能
通过浏览器 MCP 测量真实浏览器指标：
```
1. 导航至每个目标 URL
2. 测量核心网页指标：
- LCP（最大内容绘制）— 目标 < 2.5 秒
- CLS（累积布局偏移）— 目标 < 0.1
- INP（与下一次绘制的交互）— 目标 < 200 毫秒
- FCP（首次内容绘制）— 目标 < 1.8 秒
- TTFB（首字节时间）— 目标 < 800 毫秒
3. 测量资源大小：
- 页面总重量（目标 < 1MB）
- JS 包大小（目标 < 200KB gzip 压缩后）
- CSS 大小
- 图片重量
- 第三方脚本重量
4. 统计网络请求数量
5. 检查阻塞渲染的资源
```
### 模式 2：API 性能
对 API 端点进行基准测试：
```
1. 每个端点请求 100 次
2. 测量：p50、p95、p99 延迟
3. 追踪：响应大小、状态码
4. 负载测试：10 个并发请求
5. 与 SLA 目标进行对比
```
### 模式 3：构建性能
测量开发反馈循环效率：
```
1. 冷构建时间
2. 热重载时间 (HMR)
3. 测试套件执行时间
4. TypeScript 检查时间
5. 代码检查时间
6. Docker 构建时间
```
### 模式 4：前后对比
在变更前后运行以测量影响：
```
/benchmark baseline # 保存当前指标
# ... 进行更改 ...
/benchmark compare # 与基线进行比较
```
输出结果：
```
| Metric | Before | After | Delta | Verdict |
|--------|--------|-------|-------|---------|
| LCP | 1.2s | 1.4s | +200ms | WARNING: WARN |
| Bundle | 180KB | 175KB | -5KB | ✓ BETTER |
| Build | 12s | 14s | +2s | WARNING: WARN |
```
## 输出
将基线数据以 JSON 格式存储在 `.ecc/benchmarks/` 中。通过 Git 追踪，便于团队共享基线。
## 集成
* CI：在每个 PR 上运行 `/benchmark compare`
* 配合 `/canary-watch` 进行部署后监控
* 配合 `/browser-qa` 完成发布前完整检查清单

104
docs/zh-CN/skills/canary-watch/SKILL.md Normal file
View File

@@ -0,0 +1,104 @@
---
name: canary-watch
description: 使用此技能在部署、合并或依赖升级后监控已部署的URL是否存在回归问题。
origin: ECC
---
# Canary Watch — 部署后监控
## 使用场景
* 部署到生产或预发布环境后
* 合并高风险 PR 后
* 需要验证修复是否生效时
* 发布窗口期间的持续监控
* 依赖升级后
## 工作原理
监控已部署 URL 是否存在回归问题。循环运行，直至手动停止或监控窗口过期。
### 监控内容
```
1. HTTP 状态 — 页面是否返回 200？
2. 控制台错误 — 是否出现之前没有的新错误？
3. 网络故障 — 是否存在失败的 API 调用、5xx 响应？
4. 性能 — LCP/CLS/INP 与基线相比是否有退化？
5. 内容 — 关键元素是否消失？（h1、导航、页脚、CTA）
6. API 健康 — 关键端点是否在 SLA 内响应？
```
### 监控模式
**快速检查**（默认）：单次执行，报告结果
```
/canary-watch https://myapp.com
```
**持续监控**：每 N 分钟检查一次，持续 M 小时
```
/canary-watch https://myapp.com --interval 5m --duration 2h
```
**差异模式**：对比预发布环境与生产环境
```
/canary-watch --compare https://staging.myapp.com https://myapp.com
```
### 告警阈值
```yaml
critical: # immediate alert
- HTTP status != 200
- Console error count > 5 (new errors only)
- LCP > 4s
- API endpoint returns 5xx
warning: # flag in report
- LCP increased > 500ms from baseline
- CLS > 0.1
- New console warnings
- Response time > 2x baseline
info: # log only
- Minor performance variance
- New network requests (third-party scripts added?)
```
### 通知机制
当超过关键阈值时：
* 桌面通知（macOS/Linux）
* 可选：Slack/Discord Webhook
* 记录至 `~/.claude/canary-watch.log`
## 输出
```markdown
## Canary 报告 — myapp.com — 2026-03-23 03:15 PST
### 状态：健康 ✓
| 检查项 | 结果 | 基线 | 偏差 |
|-------|--------|----------|-------|
| HTTP | 200 ✓ | 200 | — |
| 控制台错误 | 0 ✓ | 0 | — |
| LCP | 1.8s ✓ | 1.6s | +200ms |
| CLS | 0.01 ✓ | 0.01 | — |
| API /health | 145ms ✓ | 120ms | +25ms |
### 未检测到回归问题。部署状态良好。
```
## 集成
配合使用：
* `/browser-qa` 进行部署前验证
* 钩子：在 `git push` 上添加 PostToolUse 钩子，部署后自动检查
* CI：在 GitHub Actions 的部署步骤后运行

171
docs/zh-CN/skills/ck/SKILL.md Normal file
View File

@@ -0,0 +1,171 @@
---
name: ck
description: Claude Code 的每个项目持久化记忆。在会话启动时自动加载项目上下文，通过 git 活动追踪会话，并写入原生记忆。命令运行确定性的 Node.js 脚本——行为在不同模型版本间保持一致。
origin: community
version: 2.0.0
author: sreedhargs89
repo: https://github.com/sreedhargs89/context-keeper
---
# ck — 上下文管家
你是**上下文管家**助手。当用户调用任何 `/ck:*` 命令时，
运行相应的 Node.js 脚本，并将其标准输出原样呈现给用户。
脚本位于：`~/.claude/skills/ck/commands/`（使用 `$HOME` 展开 `~`）。
***
## 数据布局
```
~/.claude/ck/
├── projects.json ← 路径 → {名称, 上下文目录, 最后更新时间}
└── contexts/<名称>/
├── context.json ← 真实来源（结构化 JSON，v2 版本）
└── CONTEXT.md ← 自动生成的视图 — 请勿手动编辑
```
***
## 命令
### `/ck:init` — 注册项目
```bash
node "$HOME/.claude/skills/ck/commands/init.mjs"
```
脚本输出包含自动检测信息的 JSON。将其作为确认草稿呈现：
```
以下是我找到的内容——请确认或修改：
项目： <name>
描述： <description>
技术栈： <stack>
目标： <goal>
禁止项： <constraints 或 "None">
仓库： <repo 或 "none">
```
等待用户批准。应用任何编辑。然后将确认后的 JSON 通过管道传递给 save.mjs --init：
```bash
echo '<confirmed-json>' | node "$HOME/.claude/skills/ck/commands/save.mjs" --init
```
确认后的 JSON 模式：`{"name":"...","path":"...","description":"...","stack":["..."],"goal":"...","constraints":["..."],"repo":"..." }`
***
### `/ck:save` — 保存会话状态
**这是唯一需要 LLM 分析的命令。** 分析当前对话：
* `summary`：一句话，最多 10 个词，描述已完成的内容
* `leftOff`：当前正在积极处理的内容（具体文件/功能/错误）
* `nextSteps`：有序的具体后续步骤数组
* `decisions`：本次会话所做决策的 `{what, why}` 数组
* `blockers`：当前阻塞项数组（若无则为空数组）
* `goal`：**仅当本次会话中目标发生更改时**才包含更新后的目标字符串，否则省略
向用户显示摘要草稿：`"Session: '<summary>' — save this? (yes / edit)"`
等待确认。然后通过管道传递给 save.mjs：
```bash
echo '<json>' | node "$HOME/.claude/skills/ck/commands/save.mjs"
```
JSON 模式（精确）：`{"summary":"...","leftOff":"...","nextSteps":["..."],"decisions":[{"what":"...","why":"..."}],"blockers":["..."]}`
逐字显示脚本的标准输出确认信息。
***
### `/ck:resume [name|number]` — 完整简报
```bash
node "$HOME/.claude/skills/ck/commands/resume.mjs" [arg]
```
逐字显示输出。然后询问："从这里继续？还是有什么变化？"
如果用户报告有变化 → 立即运行 `/ck:save`。
***
### `/ck:info [name|number]` — 快速快照
```bash
node "$HOME/.claude/skills/ck/commands/info.mjs" [arg]
```
逐字显示输出。无需后续提问。
***
### `/ck:list` — 项目组合视图
```bash
node "$HOME/.claude/skills/ck/commands/list.mjs"
```
逐字显示输出。如果用户回复数字或名称 → 运行 `/ck:resume`。
***
### `/ck:forget [name|number]` — 移除项目
首先解析项目名称（如有需要运行 `/ck:list`）。
询问：`"This will permanently delete context for '<name>'. Are you sure? (yes/no)"`
如果是：
```bash
node "$HOME/.claude/skills/ck/commands/forget.mjs" [name]
```
逐字显示确认信息。
***
### `/ck:migrate` — 将 v1 数据转换为 v2
```bash
node "$HOME/.claude/skills/ck/commands/migrate.mjs"
```
首先进行试运行：
```bash
node "$HOME/.claude/skills/ck/commands/migrate.mjs" --dry-run
```
逐字显示输出。将所有 v1 的 CONTEXT.md + meta.json 文件迁移为 v2 的 context.json。
原始文件备份为 `meta.json.v1-backup` — 不会删除任何内容。
***
## 会话启动钩子
位于 `~/.claude/skills/ck/hooks/session-start.mjs` 的钩子必须在
`~/.claude/settings.json` 中注册，以便在会话启动时自动加载项目上下文：
```json
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "node \"~/.claude/skills/ck/hooks/session-start.mjs\"" }] }
]
}
}
```
该钩子每次会话注入约 100 个 token（紧凑的 5 行摘要）。它还会检测
未保存的会话、自上次保存以来的 git 活动，以及与 CLAUDE.md 的目标不匹配。
***
## 规则
* 在 Bash 调用中始终将 `~` 展开为 `$HOME`。
* 命令不区分大小写：`/CK:SAVE`、`/ck:save`、`/Ck:Save` 均有效。
* 如果脚本以退出码 1 退出，则将其标准输出显示为错误消息。
* 切勿直接编辑 `context.json` 或 `CONTEXT.md` — 始终使用脚本。
* 如果 `projects.json` 格式错误，请告知用户并提供重置为 `{}` 的选项。

189
docs/zh-CN/skills/connections-optimizer/SKILL.md Normal file
View File

@@ -0,0 +1,189 @@
---
name: connections-optimizer
description: 重新组织用户的X和LinkedIn网络，采用审查优先的修剪策略，提供添加/关注建议，并以用户真实口吻起草针对不同渠道的温和外联。当用户希望清理关注列表、向当前优先事项发展或围绕更高信号的关系重新平衡社交图谱时使用。
origin: ECC
---
# 连接优化器
重新组织用户的社交网络，而非将对外联系视为单向的潜在客户列表。
本技能处理：
* X（推特）关注清理与扩展
* LinkedIn 关注与连接分析
* 优先审核队列
* 添加与关注建议
* 温暖路径识别
* 以用户真实口吻生成 Apple Mail、X DM 和 LinkedIn 草稿
## 何时激活
* 用户想要清理其 X 关注列表
* 用户想要重新平衡关注或保持连接的对象
* 用户说"清理我的网络"、"我应该取消关注谁"、"我应该关注谁"、"我应该与谁重新建立联系"
* 外联质量取决于网络结构，而不仅仅是生成冷名单
## 必要输入
收集或推断：
* 当前优先事项和活跃工作
* 目标角色、行业、地区或生态圈
* 平台选择：X、LinkedIn 或两者
* 不可触碰名单
* 模式：`light-pass`、`default` 或 `aggressive`
如果用户未指定模式，则使用 `default`。
## 工具要求
### 首选
* `x-api` 用于 X 图谱检查与近期活动
* `lead-intelligence` 用于目标发现与温暖路径排序
* `social-graph-ranker` 当用户希望独立于更广泛的线索流程评估桥梁价值时
* Exa / 深度研究用于人物与公司信息丰富
* `brand-voice` 在起草外联内容之前
### 备选
* 浏览器控制用于 LinkedIn 分析与起草
* 当 API 覆盖受限时，使用浏览器控制处理 X
* 当电子邮件是合适渠道时，通过桌面自动化起草 Apple Mail 或 Mail.app 邮件
## 安全默认设置
* 默认优先审核，绝不盲目自动清理
* X：仅清理用户关注的对象，绝不清理粉丝
* LinkedIn：将一级连接的移除视为手动优先审核
* 不自动发送私信、邀请或电子邮件
* 在任何执行步骤之前，输出排序后的行动计划与草稿
## 平台规则
### X
* 互关比单向关注更稳固
* 未回关者可更积极清理
* 长期不活跃或已消失的账号应快速浮现
* 互动、信号质量与桥梁价值比原始粉丝数更重要
### LinkedIn
* 若用户实际拥有 LinkedIn API 访问权限，优先使用 API
* 当缺少 API 访问权限时，必须使用浏览器工作流程
* 区分对外关注与已接受的一级连接
* 对外关注可更自由地清理
* 已接受的一级连接应默认审核，而非自动移除
## 模式
### `light-pass`
* 仅清理高置信度、低价值的单向关注
* 其余内容供审核
* 生成少量添加/关注列表
### `default`
* 平衡的清理队列
* 平衡的保留列表
* 排序的添加/关注队列
* 在有用时起草温暖介绍或直接外联
### `aggressive`
* 更大的清理队列
* 对过时未回关者的容忍度更低
* 执行前仍需审核把关
## 评分模型
使用以下正面信号：
* 互惠性
* 近期活跃度
* 与当前优先事项的契合度
* 网络桥梁价值
* 角色相关性
* 真实互动历史
* 近期存在感与响应度
使用以下负面信号：
* 已消失或废弃的账号
* 过时的单向关注
* 偏离优先主题的集群
* 低价值噪音
* 反复无响应
* 存在许多更优替代者时仍未回关
互关和真实的温暖路径桥梁应比单向关注受到更宽松的惩罚。
## 工作流程
1. 获取优先事项、不可触碰约束和选定平台。
2. 拉取当前关注/连接清单。
3. 对清理候选者进行评分并附上明确理由。
4. 对保留候选者进行评分并附上明确理由。
5. 使用 `lead-intelligence` 结合研究信息对扩展候选者进行排序。
6. 匹配正确渠道：
* X DM 用于温暖、快速的社交接触点
* LinkedIn 消息用于职业图谱邻近关系
* Apple Mail 草稿用于需要更多上下文的介绍或外联
7. 在起草消息前运行 `brand-voice`。
8. 在任何执行步骤前返回审核包。
## 审核包格式
```text
连接优化器报告
============================
模式：
平台：
优先级设置：
修剪队列
- 账号/个人资料
原因：
置信度：
操作：
审查队列
- 账号/个人资料
原因：
风险：
保留/保护
- 账号/个人资料
桥梁价值：
添加/关注目标
- 联系人
当前原因：
预热路径：
首选渠道：
草稿
- X 私信：
- LinkedIn：
- Apple 邮件：
```
## 外联规则
* 默认邮件路径是创建 Apple Mail / Mail.app 草稿。
* 不自动发送。
* 根据温暖度、相关性和上下文深度选择渠道。
* 当电子邮件或不进行外联是正确选择时，不要强制发送私信。
* 草稿应听起来像用户本人，而非自动化的销售文案。
## 相关技能
* `brand-voice` 用于可复用的语音档案
* `social-graph-ranker` 用于独立的桥梁评分与温暖路径计算
* `lead-intelligence` 用于加权目标与温暖路径发现
* `x-api` 用于 X 图谱访问、起草和可选执行流程
* `content-engine` 当用户还希望围绕网络变动发布公开内容时

216
docs/zh-CN/skills/council/SKILL.md Normal file
View File

@@ -0,0 +1,216 @@
---
name: council
description: 召集四方会议处理模糊决策、权衡取舍及继续/停止决策。当存在多个有效路径且需要在选择前进行结构化异议时使用。
origin: ECC
---
# 顾问团
在模糊决策时召集四位顾问：
* 上下文中的Claude声音
* 怀疑论者子代理
* 实用主义者子代理
* 批评者子代理
这适用于**模糊性下的决策制定**，而非代码审查、实施规划或架构设计。
## 何时使用
在以下情况使用顾问团：
* 决策存在多个可行路径且无明显优胜者
* 需要明确权衡利弊
* 用户要求第二意见、异议或多角度分析
* 存在对话锚定效应的真实风险
* 通过对抗性挑战能优化"执行/放弃"决策
示例：
* 单一仓库 vs 多仓库
* 立即发布 vs 打磨后发布
* 功能开关 vs 全面上线
* 简化范围 vs 保持战略广度
## 何时不使用
| 不应使用顾问团的情况 | 应使用 |
| --- | --- |
| 验证输出是否正确 | `santa-method` |
| 将功能拆解为实施步骤 | `planner` |
| 设计系统架构 | `architect` |
| 审查代码中的错误或安全漏洞 | `code-reviewer` 或 `santa-method` |
| 直接的事实性问题 | 直接回答 |
| 明确的执行任务 | 直接执行 |
## 角色
| 声音 | 视角 |
| --- | --- |
| 架构师 | 正确性、可维护性、长期影响 |
| 怀疑论者 | 质疑前提、简化、打破假设 |
| 实用主义者 | 交付速度、用户影响、运营现实 |
| 批评者 | 边缘情况、下行风险、失败模式 |
三个外部声音应作为全新子代理启动，**仅提供问题和相关上下文**，而非完整对话历史。这是反锚定机制。
## 工作流程
### 1. 提取真实问题
将决策简化为一个明确提示：
* 我们在决定什么？
* 哪些约束条件重要？
* 什么算成功？
如果问题模糊，在召集顾问团前先提出一个澄清性问题。
### 2. 仅收集必要上下文
如果决策与代码库相关：
* 收集相关文件、代码片段、问题描述或指标
* 保持简洁
* 仅包含决策所需的上下文
如果决策是战略/通用性的：
* 除非能实质性改变答案，否则跳过仓库代码片段
### 3. 首先形成架构师立场
在阅读其他声音之前，写下：
* 你的初始立场
* 支持该立场的三个最强理由
* 首选路径的主要风险
先完成此步骤，以确保综合意见不会简单镜像外部声音。
### 4. 并行启动三个独立声音
每个子代理获得：
* 决策问题
* 必要的简洁上下文
* 严格角色定义
* 无多余对话历史
提示模板：
```text
你是四声部决策委员会中的[角色]。
问题：
[决策问题]
背景：
[仅包含相关片段或约束条件]
回复格式：
1. 立场 — 1-2句话
2. 理由 — 3个简洁要点
3. 风险 — 你建议中最大的风险
4. 意外点 — 其他声部可能忽略的一个方面
直接明了，不要含糊。控制在300字以内。
```
角色重点：
* 怀疑论者：挑战框架、质疑假设、提出最简单的可信替代方案
* 实用主义者：优化速度、简单性和实际执行
* 批评者：揭示下行风险、边缘情况以及计划可能失败的原因
### 5. 通过偏见护栏进行综合
你既是参与者也是综合者，因此需遵循以下规则：
* 不得无故驳回外部观点，需说明理由
* 若外部声音改变了你的建议，需明确说明
* 始终包含最强烈的异议，即使你最终拒绝它
* 若两个声音一致反对你的初始立场，将其视为真实信号
* 在最终裁决前保持原始立场可见
### 6. 呈现简洁裁决
使用以下输出格式：
```markdown
## 委员会：[简短决策标题]
**架构师：** [1-2句立场陈述]
[1行理由说明]
**怀疑论者：** [1-2句立场陈述]
[1行理由说明]
**实用主义者：** [1-2句立场陈述]
[1行理由说明]
**批评者：** [1-2句立场陈述]
[1行理由说明]
### 裁决
- **共识点：** [各方达成一致之处]
- **最大分歧：** [最重要的争议点]
- **前提检验：** [怀疑论者是否质疑了问题本身？]
- **建议方案：** [综合后的行动路径]
```
确保在手机屏幕上可快速浏览。
## 持久化规则
**不要**从此技能向 `~/.claude/notes` 或其他隐藏路径写入临时笔记。
若顾问团实质性改变了建议：
* 使用 `knowledge-ops` 将经验教训存储在正确的持久化位置
* 或使用 `/save-session`（若结果属于会话记忆）
* 或直接更新相关的GitHub/Linear问题（若决策改变了当前执行事实）
仅在决策改变实际内容时进行持久化。
## 多轮跟进
默认为一轮。
若用户要求另一轮：
* 保持新问题聚焦
* 仅在必要时包含上一轮裁决
* 尽可能保持怀疑论者的"干净"状态以保留反锚定价值
## 反模式
* 将顾问团用于代码审查
* 在任务仅为实施工作时使用顾问团
* 向子代理提供完整对话记录
* 在最终裁决中隐藏分歧
* 无论重要性如何都持久化每个决策
## 相关技能
* `santa-method` — 对抗性验证
* `knowledge-ops` — 正确持久化重要决策变更
* `search-first` — 在顾问团前收集外部参考资料（如需要）
* `architecture-decision-records` — 当决策成为长期系统策略时正式化结果
## 示例
问题：
```text
我们现在应该以 alpha 版本发布 ECC 2.0，还是等到控制平面 UI 更完善后再发布？
```
可能的顾问团形态：
* 架构师推动结构完整性并避免混乱的界面
* 怀疑论者质疑UI是否真的是瓶颈因素
* 实用主义者询问在不损害信任的前提下现在可以交付什么
* 批评者关注支持负担、期望债务和上线混乱
价值不在于达成一致。价值在于在选择前让分歧清晰可见。

88
docs/zh-CN/skills/hermes-imports/SKILL.md Normal file
View File

@@ -0,0 +1,88 @@
---
name: hermes-imports
description: 将本地 Hermes 操作员工作流转换为经过清理的 ECC 技能和发布包工件。在准备将 Hermes 工作流用于公共 ECC 重用而不泄露私有工作区状态、凭据或仅本地路径时使用。
origin: ECC
---
# Hermes 导入
当需要将重复的 Hermes 工作流转化为可在 ECC 中安全发布的内容时，使用此技能。
Hermes 是操作员外壳。ECC 是可复用工作流层。导入操作应将稳定模式从 Hermes 迁移至 ECC，同时避免移动私有状态。
## 使用时机
* Hermes 工作流重复次数足够多，已具备可复用性
* 本地操作员提示词需要升级为公共 ECC 技能
* 启动、内容、研究或工程工作流需要经过净化的交接文档
* 工作流中包含本地路径、凭证、个人数据集或私有账户名，发布前必须移除
## 导入规则
* 将本地路径转换为仓库相对路径或占位符
* 用角色标签（如 `operator`、`default profile`、`workspace owner`）替换真实账户名
* 仅通过提供商名称描述凭证要求
* 保持示例简洁且可操作
* 不得发布原始工作区导出文件、令牌、OAuth 文件、健康数据、CRM 数据或财务数据
* 若工作流依赖私有状态才能理解，则保留在本地
## 净化检查清单
提交导入的工作流前，需扫描：
* 绝对路径（如 `/Users/...`）
* `~/.hermes` 路径（除非文档明确说明本地设置）
* API 密钥、令牌、Cookie、OAuth 文件或 Bearer 字符串
* 电话号码、私人邮箱地址及个人联系人图谱
* 尚未公开的客户名称、家族名称或账户名
* 收入、健康或 CRM 详情
* 包含私有系统工具输出的原始日志
## 转换模式
1. 识别可重复的操作员循环
2. 剥离私有输入与输出
3. 将本地路径重写为仓库相对路径示例
4. 将一次性指令转化为 `When To Use` 章节及简短流程
5. 添加具体输出要求
6. 在发起 PR 前执行密钥与本地路径扫描
## 示例：启动交接
本地 Hermes 提示词：
```text
读取我的本地工作区文件并最终确定发布文案。
```
ECC 安全版本：
```text
使用 docs/releases/<version>/ 下的公开发布包。
返回一条 X 帖子、一条 LinkedIn 帖子、一份录制检查清单以及缺失资源列表。
```
## 示例：静默时段操作员任务
本地 Hermes 任务：
```text
夜间运行我的私人收件箱、财务和内容检查。
```
ECC 安全版本：
```text
描述调度器策略、静默时段、升级规则以及检查类别。请勿包含私有数据源或凭据。
```
## 输出契约
返回：
* 候选 ECC 技能名称
* 净化后的工作流摘要
* 必需的公共输入
* 已移除的私有输入
* 剩余风险
* 应创建或更新的文件

276
docs/zh-CN/skills/hexagonal-architecture/SKILL.md Normal file
View File

@@ -0,0 +1,276 @@
---
name: hexagonal-architecture
description: 设计、实现并重构端口与适配器系统，具有清晰的领域边界、依赖反转以及跨 TypeScript、Java、Kotlin 和 Go 服务的可测试用例编排。
origin: ECC
---
# 六边形架构
六边形架构（端口与适配器）使业务逻辑独立于框架、传输层和持久化细节。核心应用依赖于抽象端口，而适配器在边缘实现这些端口。
## 适用场景
* 构建需要长期可维护性和可测试性的新功能。
* 重构分层或框架密集型代码，其中领域逻辑与I/O关注点混杂。
* 为同一用例支持多种接口（HTTP、CLI、队列工作器、定时任务）。
* 替换基础设施（数据库、外部API、消息总线）而无需重写业务规则。
当需求涉及边界、领域驱动设计、重构紧耦合服务，或将应用逻辑与特定库解耦时，使用此技能。
## 核心概念
* **领域模型**：业务规则和实体/值对象。无框架导入。
* **用例（应用层）**：编排领域行为和工作流步骤。
* **入站端口**：描述应用能力的契约（命令/查询/用例接口）。
* **出站端口**：应用所需依赖的契约（仓库、网关、事件发布器、时钟、UUID等）。
* **适配器**：端口的基础设施和交付实现（HTTP控制器、数据库仓库、队列消费者、SDK封装器）。
* **组合根**：将具体适配器绑定到用例的单一连接位置。
出站端口接口通常位于应用层（仅当抽象真正属于领域层时才位于领域层），而基础设施适配器实现它们。
依赖方向始终向内：
* 适配器 -> 应用/领域
* 应用 -> 端口接口（入站/出站契约）
* 领域 -> 仅领域抽象（无框架或基础设施依赖）
* 领域 -> 无外部依赖
## 工作原理
### 步骤1：建模用例边界
定义具有清晰输入和输出DTO的单个用例。将传输细节（Express `req`、GraphQL `context`、任务负载包装器）保持在此边界之外。
### 步骤2：首先定义出站端口
将每个副作用识别为端口：
* 持久化（`UserRepositoryPort`）
* 外部调用（`BillingGatewayPort`）
* 横切关注点（`LoggerPort`、`ClockPort`）
端口应建模能力，而非技术。
### 步骤3：使用纯编排实现用例
用例类/函数通过构造函数/参数接收端口。它验证应用层不变量，协调领域规则，并返回纯数据结构。
### 步骤4：在边缘构建适配器
* 入站适配器将协议输入转换为用例输入。
* 出站适配器将应用契约映射到具体API/ORM/查询构建器。
* 映射保持在适配器中，而非用例内部。
### 步骤5：在组合根中连接所有组件
实例化适配器，然后将其注入用例。保持此连接集中化，以避免隐藏的服务定位器行为。
### 步骤6：按边界测试
* 使用伪造端口对用例进行单元测试。
* 使用真实基础设施依赖对适配器进行集成测试。
* 通过入站适配器对面向用户的流程进行端到端测试。
## 架构图
```mermaid
flowchart LR
Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
OutboundAdapter --> ExternalSystem["DB/API/Queue"]
UseCase --> DomainModel["DomainModel"]
```
## 建议的模块布局
使用以功能为先的组织方式，并带有显式边界：
```text
src/
features/
orders/
domain/
Order.ts
OrderPolicy.ts
application/
ports/
inbound/
CreateOrder.ts
outbound/
OrderRepositoryPort.ts
PaymentGatewayPort.ts
use-cases/
CreateOrderUseCase.ts
adapters/
inbound/
http/
createOrderRoute.ts
outbound/
postgres/
PostgresOrderRepository.ts
stripe/
StripePaymentGateway.ts
composition/
ordersContainer.ts
```
## TypeScript 示例
### 端口定义
```typescript
export interface OrderRepositoryPort {
save(order: Order): Promise<void>;
findById(orderId: string): Promise<Order | null>;
}
export interface PaymentGatewayPort {
authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
}
```
### 用例
```typescript
type CreateOrderInput = {
orderId: string;
amountCents: number;
};
type CreateOrderOutput = {
orderId: string;
authorizationId: string;
};
export class CreateOrderUseCase {
constructor(
private readonly orderRepository: OrderRepositoryPort,
private readonly paymentGateway: PaymentGatewayPort
) {}
async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
const order = Order.create({ id: input.orderId, amountCents: input.amountCents });
const auth = await this.paymentGateway.authorize({
orderId: order.id,
amountCents: order.amountCents,
});
// markAuthorized returns a new Order instance; it does not mutate in place.
const authorizedOrder = order.markAuthorized(auth.authorizationId);
await this.orderRepository.save(authorizedOrder);
return {
orderId: order.id,
authorizationId: auth.authorizationId,
};
}
}
```
### 出站适配器
```typescript
export class PostgresOrderRepository implements OrderRepositoryPort {
constructor(private readonly db: SqlClient) {}
async save(order: Order): Promise<void> {
await this.db.query(
"insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
[order.id, order.amountCents, order.status, order.authorizationId]
);
}
async findById(orderId: string): Promise<Order | null> {
const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
return row ? Order.rehydrate(row) : null;
}
}
```
### 组合根
```typescript
export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
const orderRepository = new PostgresOrderRepository(deps.db);
const paymentGateway = new StripePaymentGateway(deps.stripe);
return new CreateOrderUseCase(orderRepository, paymentGateway);
};
```
## 多语言映射
在不同生态系统中使用相同的边界规则；仅语法和连接方式发生变化。
* **TypeScript/JavaScript**
* 端口：`application/ports/*` 作为接口/类型。
* 用例：带有构造函数/参数注入的类/函数。
* 适配器：`adapters/inbound/*`、`adapters/outbound/*`。
* 组合：显式工厂/容器模块（无隐藏全局变量）。
* **Java**
* 包：`domain`、`application.port.in`、`application.port.out`、`application.usecase`、`adapter.in`、`adapter.out`。
* 端口：`application.port.*` 中的接口。
* 用例：普通类（Spring `@Service` 是可选的，非必需）。
* 组合：Spring配置或手动连接类；将连接逻辑保持在领域/用例类之外。
* **Kotlin**
* 模块/包镜像Java的拆分（`domain`、`application.port`、`application.usecase`、`adapter`）。
* 端口：Kotlin接口。
* 用例：带有构造函数注入的类（Koin/Dagger/Spring/手动）。
* 组合：模块定义或专用组合函数；避免服务定位器模式。
* **Go**
* 包：`internal/<feature>/domain`、`application`、`ports`、`adapters/inbound`、`adapters/outbound`。
* 端口：由消费应用包拥有的小型接口。
* 用例：带有接口字段和显式 `New...` 构造函数的结构体。
* 组合：在 `cmd/<app>/main.go` 中连接（或专用连接包），保持构造函数显式。
## 应避免的反模式
* 领域实体导入ORM模型、Web框架类型或SDK客户端。
* 用例直接从 `req`、`res` 或队列元数据读取。
* 从用例直接返回数据库行，未经领域/应用映射。
* 让适配器直接相互调用，而非通过用例端口流转。
* 将依赖连接分散到多个文件中，使用隐藏的全局单例。
## 迁移手册
1. 选择一个垂直切片（单个端点/任务），该切片频繁变更且带来痛苦。
2. 提取具有显式输入/输出类型的用例边界。
3. 围绕现有基础设施调用引入出站端口。
4. 将编排逻辑从控制器/服务移动到用例中。
5. 保留旧适配器，但使其委托给新用例。
6. 围绕新边界添加测试（单元测试 + 适配器集成测试）。
7. 逐个切片重复；避免完全重写。
### 重构现有系统
* **绞杀者模式**：保留当前端点，一次将一个用例路由到新的端口/适配器。
* **无大爆炸式重写**：按功能切片迁移，并通过特征化测试保持行为。
* **先建外观**：在替换内部实现之前，将遗留服务包装在出站端口后面。
* **组合冻结**：尽早集中连接，使新依赖不会泄漏到领域/用例层。
* **切片选择规则**：优先处理高变更频率、低影响范围的流程。
* **回滚路径**：为每个迁移的切片保留可逆开关或路由切换，直到生产行为得到验证。
## 测试指南（相同的六边形边界）
* **领域测试**：将实体/值对象作为纯业务规则进行测试（无模拟，无框架设置）。
* **用例单元测试**：使用出站端口的伪造/桩件测试编排；断言业务结果和端口交互。
* **出站适配器契约测试**：在端口级别定义共享契约套件，并针对每个适配器实现运行。
* **入站适配器测试**：验证协议映射（HTTP/CLI/队列负载到用例输入，以及输出/错误映射回协议）。
* **适配器集成测试**：针对真实基础设施（数据库/API/队列）运行，测试序列化、模式/查询行为、重试和超时。
* **端到端测试**：覆盖关键用户旅程，通过入站适配器 -> 用例 -> 出站适配器。
* **重构安全性**：在提取之前添加特征化测试；保持它们直到新边界行为稳定且等价。
## 最佳实践清单
* 领域和应用层仅导入内部类型和端口。
* 每个外部依赖都由一个出站端口表示。
* 验证发生在边界处（入站适配器 + 用例不变量）。
* 使用不可变转换（返回新值/实体，而非修改共享状态）。
* 错误在边界间进行转换（基础设施错误 -> 应用/领域错误）。
* 组合根是显式的且易于审计。
* 用例可通过简单的内存伪造端口进行测试。
* 重构从具有行为保持测试的一个垂直切片开始。
* 语言/框架特定内容保持在适配器中，绝不进入领域规则。

258
docs/zh-CN/skills/opensource-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,258 @@
---
name: opensource-pipeline
description: "开源流水线：fork、清理并打包私有项目以安全公开发布。串联3个代理（fork代理、清理代理、打包代理）。触发词：'/opensource'、'open source this'、'make this public'、'prepare for open source'。"
origin: ECC
---
# 开源流水线技能
通过三阶段流水线安全地开源任何项目：**分叉**（剥离密钥）→ **净化**（验证清洁）→ **打包**（CLAUDE.md + setup.sh + README）。
## 何时激活
* 用户说"开源此项目"或"使其公开"
* 用户希望将私有仓库准备为公开发布
* 用户需要在推送到 GitHub 前剥离密钥
* 用户调用 `/opensource fork`、`/opensource verify` 或 `/opensource package`
## 命令
| 命令 | 操作 |
|---------|--------|
| `/opensource fork PROJECT` | 完整流水线：分叉 + 净化 + 打包 |
| `/opensource verify PROJECT` | 对现有仓库运行净化器 |
| `/opensource package PROJECT` | 生成 CLAUDE.md + setup.sh + README |
| `/opensource list` | 显示所有暂存项目 |
| `/opensource status PROJECT` | 显示暂存项目的报告 |
## 协议
### /opensource fork PROJECT
**完整流水线——主要工作流程。**
#### 步骤 1：收集参数
解析项目路径。如果 PROJECT 包含 `/`，则视为路径（绝对或相对）。否则检查：当前工作目录、`$HOME/PROJECT`，然后询问用户。
```
SOURCE_PATH="<resolved absolute path>"
STAGING_PATH="$HOME/opensource-staging/${PROJECT_NAME}"
```
询问用户：
1. "哪个项目？"（如果未找到）
2. "许可证？（MIT / Apache-2.0 / GPL-3.0 / BSD-3-Clause）"
3. "GitHub 组织或用户名？"（默认：通过 `gh api user -q .login` 检测）
4. "GitHub 仓库名称？"（默认：项目名称）
5. "README 的描述？"（分析项目以提供建议）
#### 步骤 2：创建暂存目录
```bash
mkdir -p $HOME/opensource-staging/
```
#### 步骤 3：运行分叉代理
生成 `opensource-forker` 代理：
```
Agent(
description="将 {PROJECT} 分叉为开源项目",
subagent_type="opensource-forker",
prompt="""
将项目分叉以进行开源发布。
来源：{SOURCE_PATH}
目标：{STAGING_PATH}
许可证：{chosen_license}
遵循完整的分叉协议：
1. 复制文件（排除 .git、node_modules、__pycache__、.venv）
2. 清除所有机密和凭证
3. 将内部引用替换为占位符
4. 生成 .env.example
5. 清理 Git 历史记录
6. 在 {STAGING_PATH}/FORK_REPORT.md 中生成 FORK_REPORT.md
"""
)
```
等待完成。读取 `{STAGING_PATH}/FORK_REPORT.md`。
#### 步骤 4：运行净化代理
生成 `opensource-sanitizer` 代理：
```
Agent(
description="验证 {PROJECT} 的脱敏处理",
subagent_type="opensource-sanitizer",
prompt="""
验证开源分支的脱敏处理。
项目：{STAGING_PATH}
源（供参考）：{SOURCE_PATH}
运行所有扫描类别：
1. 密钥扫描（严重）
2. 个人身份信息扫描（严重）
3. 内部引用扫描（严重）
4. 危险文件检查（严重）
5. 配置完整性（警告）
6. Git 历史审计
在 {STAGING_PATH}/ 目录下生成 SANITIZATION_REPORT.md 文件，并给出通过/未通过的判定结果。
"""
)
```
等待完成。读取 `{STAGING_PATH}/SANITIZATION_REPORT.md`。
**如果失败：** 向用户展示发现结果。询问："修复这些问题并重新扫描，还是中止？"
* 如果修复：应用修复，重新运行净化器（最多重试 3 次——3 次失败后，展示所有发现结果并请用户手动修复）
* 如果中止：清理暂存目录
**如果通过或带警告通过：** 继续步骤 5。
#### 步骤 5：运行打包代理
生成 `opensource-packager` 代理：
```
Agent(
description="将项目 {PROJECT} 打包为开源项目",
subagent_type="opensource-packager",
prompt="""
为项目生成开源打包文件。
项目：{STAGING_PATH}
许可证：{chosen_license}
项目名称：{PROJECT_NAME}
描述：{description}
GitHub 仓库：{github_repo}
生成：
1. CLAUDE.md（命令、架构、关键文件）
2. setup.sh（一键引导脚本，设为可执行）
3. README.md（或增强现有文件）
4. LICENSE
5. CONTRIBUTING.md
6. .github/ISSUE_TEMPLATE/（bug_report.md、feature_request.md）
"""
)
```
#### 步骤 6：最终审查
向用户展示：
```
开源分支就绪：{PROJECT_NAME}
位置：{STAGING_PATH}
许可证：{license}
生成的文件：
- CLAUDE.md
- setup.sh（可执行文件）
- README.md
- LICENSE
- CONTRIBUTING.md
- .env.example（{N} 个变量）
清理：{sanitization_verdict}
后续步骤：
1. 审查：cd {STAGING_PATH}
2. 创建仓库：gh repo create {github_org}/{github_repo} --public
3. 推送：git remote add origin ... && git push -u origin main
是否继续创建 GitHub 仓库？（是/否/先审查）
```
#### 步骤 7：GitHub 发布（用户批准后）
```bash
cd "{STAGING_PATH}"
gh repo create "{github_org}/{github_repo}" --public --source=. --push --description "{description}"
```
***
### /opensource verify PROJECT
独立运行净化器。解析路径：如果 PROJECT 包含 `/`，则视为路径。否则检查 `$HOME/opensource-staging/PROJECT`，然后 `$HOME/PROJECT`，最后当前目录。
```
Agent(
subagent_type="opensource-sanitizer",
prompt="验证以下路径的清理状态：{resolved_path}。运行全部6类扫描，并生成 SANITIZATION_REPORT.md 文件。"
)
```
***
### /opensource package PROJECT
独立运行打包器。询问"许可证？"和"描述？"，然后：
```
Agent(
subagent_type="opensource-packager",
prompt="Package: {resolved_path} ..."
)
```
***
### /opensource list
```bash
ls -d $HOME/opensource-staging/*/
```
显示每个项目及其流水线进度（FORK\_REPORT.md、SANITIZATION\_REPORT.md、CLAUDE.md 是否存在）。
***
### /opensource status PROJECT
```bash
cat $HOME/opensource-staging/${PROJECT}/SANITIZATION_REPORT.md
cat $HOME/opensource-staging/${PROJECT}/FORK_REPORT.md
```
## 暂存布局
```
$HOME/opensource-staging/
my-project/
FORK_REPORT.md # 来自 forker 代理
SANITIZATION_REPORT.md # 来自 sanitizer 代理
CLAUDE.md # 来自 packager 代理
setup.sh # 来自 packager 代理
README.md # 来自 packager 代理
.env.example # 来自 forker 代理
... # 清理后的项目文件
```
## 反模式
* **绝不**在未经用户批准的情况下推送到 GitHub
* **绝不**跳过净化器——它是安全门
* **绝不**在净化器失败且未修复所有关键发现后继续
* **绝不**在暂存目录中保留 `.env`、`*.pem` 或 `credentials.json`
## 最佳实践
* 对于新版本，始终运行完整流水线（分叉 → 净化 → 打包）
* 暂存目录会持续存在直到显式清理——用于审查
* 在发布前，任何手动修复后重新运行净化器
* 参数化密钥而非删除它们——保留项目功能
## 相关技能
参见 `security-review` 了解净化器使用的密钥检测模式。

310
docs/zh-CN/skills/santa-method/SKILL.md Normal file
View File

@@ -0,0 +1,310 @@
---
name: santa-method
description: "具有收敛循环的多智能体对抗验证。两个独立的审查代理必须都通过，输出才能发送。"
origin: "Ronald Skelton - Founder, RapportScore.ai"
---
# 圣诞老人方法
多智能体对抗验证框架。列个清单，检查两遍。如果行为不端，就修正直到表现良好。
核心洞察：单个智能体审查自身输出时，会共享产生该输出的相同偏见、知识盲区和系统性错误。两个没有共享上下文的独立审查者可以打破这种故障模式。
## 何时激活
在以下情况调用此技能：
* 输出将被发布、部署或供最终用户使用
* 必须强制执行合规、监管或品牌约束
* 代码未经人工审查即投入生产
* 内容准确性至关重要（技术文档、教育材料、面向客户的文案）
* 大规模批量生成，抽检无法发现系统性模式
* 幻觉风险较高（声明、统计数据、API 参考、法律用语）
**不要**用于内部草稿、探索性研究或具有确定性验证的任务（这些请使用构建/测试/代码检查流水线）。
## 架构
```
┌─────────────┐
│ 生成器 │ 阶段 1：列出清单
│ (代理 A) │ 生成交付物
└──────┬───────┘
│ 输出
▼
┌──────────────────────────────┐
│ 双重独立审查 │ 阶段 2：复核两次
│ │
│ ┌───────────┐ ┌───────────┐ │ 两个代理，同一评分标准，
│ │ 审查者 B │ │ 审查者 C │ │ 无共享上下文
│ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │
└────────┼──────────────┼───────┘
│ │
▼ ▼
┌──────────────────────────────┐
│ 裁决门 │ 阶段 3：判定好坏
│ │
│ B通过且C通过 → 好 │ 两者必须通过。
│ 否则 → 坏 │ 无例外。
└──────┬──────────────┬────────┘
│ │
好 坏
│ │
▼ ▼
[ 发布 ] ┌─────────────┐
│ 修复循环 │ 阶段 4：修复至通过
│ │
│ 迭代次数++ │ 收集所有标记。
│ 若 i > 最大: │ 修复所有问题。
│ 升级处理 │ 重新运行两个审查者。
│ 否则: │ 循环直至收敛。
│ 跳至阶段2 │
└──────────────┘
```
## 阶段详情
### 阶段 1：列清单（生成）
执行主要任务。无需改变正常的生成工作流程。圣诞老人方法是一个生成后验证层，而非生成策略。
```python
# The generator runs as normal
output = generate(task_spec)
```
### 阶段 2：检查两遍（独立双重审查）
并行生成两个审查智能体。关键不变项：
1. **上下文隔离** — 两个审查者互不见面对方的评估
2. **相同评估标准** — 两者收到相同的评估标准
3. **相同输入** — 两者都收到原始规格说明和生成的输出
4. **结构化输出** — 每个审查者返回类型化的判定，而非散文
```python
REVIEWER_PROMPT = """
You are an independent quality reviewer. You have NOT seen any other review of this output.
## Task Specification
{task_spec}
## Output Under Review
{output}
## Evaluation Rubric
{rubric}
## Instructions
Evaluate the output against EACH rubric criterion. For each:
- PASS: criterion fully met, no issues
- FAIL: specific issue found (cite the exact problem)
Return your assessment as structured JSON:
{
"verdict": "PASS" | "FAIL",
"checks": [
{"criterion": "...", "result": "PASS|FAIL", "detail": "..."}
],
"critical_issues": ["..."], // blockers that must be fixed
"suggestions": ["..."] // non-blocking improvements
}
Be rigorous. Your job is to find problems, not to approve.
"""
```
```python
# Spawn reviewers in parallel (Claude Code subagents)
review_b = Agent(prompt=REVIEWER_PROMPT.format(...), description="Santa Reviewer B")
review_c = Agent(prompt=REVIEWER_PROMPT.format(...), description="Santa Reviewer C")
# Both run concurrently — neither sees the other
```
### 评估标准设计
评估标准是最重要的输入。模糊的标准会产生模糊的审查。每个标准必须有客观的通过/失败条件。
| 标准 | 通过条件 | 失败信号 |
|-----------|---------------|----------------|
| 事实准确性 | 所有声明均可根据源材料或常识验证 | 编造的统计数据、错误的版本号、不存在的 API |
| 无幻觉 | 没有虚构的实体、引用、URL 或参考文献 | 指向不存在页面的链接、无来源的引用 |
| 完整性 | 规格说明中的每个要求都得到满足 | 缺少章节、遗漏边缘情况、覆盖不完整 |
| 合规性 | 通过所有项目特定的约束 | 使用禁用术语、语气违规、监管不合规 |
| 内部一致性 | 输出内无矛盾 | A 部分说 X，B 部分说非 X |
| 技术正确性 | 代码可编译/运行，算法合理 | 语法错误、逻辑错误、错误的复杂度声明 |
#### 特定领域评估标准扩展
**内容/营销：**
* 品牌语气一致性
* 满足 SEO 要求（关键词密度、元标签、结构）
* 无竞争对手商标滥用
* CTA 存在且链接正确
**代码：**
* 类型安全（无 `any` 泄漏，正确处理 null）
* 错误处理覆盖
* 安全性（代码中无秘密、输入验证、注入防护）
* 新路径的测试覆盖
**合规敏感（受监管、法律、金融）：**
* 无结果保证或未经证实的声明
* 存在所需的免责声明
* 仅使用批准的术语
* 符合司法管辖区的语言
### 阶段 3：表现好坏（判定门控）
```python
def santa_verdict(review_b, review_c):
"""Both reviewers must pass. No partial credit."""
if review_b.verdict == "PASS" and review_c.verdict == "PASS":
return "NICE" # Ship it
# Merge flags from both reviewers, deduplicate
all_issues = dedupe(review_b.critical_issues + review_c.critical_issues)
all_suggestions = dedupe(review_b.suggestions + review_c.suggestions)
return "NAUGHTY", all_issues, all_suggestions
```
为什么两者都必须通过：如果只有一个审查者发现问题，那么该问题是真实存在的。另一个审查者的盲点正是圣诞老人方法旨在消除的故障模式。
### 阶段 4：修正直到表现良好（收敛循环）
```python
MAX_ITERATIONS = 3
for iteration in range(MAX_ITERATIONS):
verdict, issues, suggestions = santa_verdict(review_b, review_c)
if verdict == "NICE":
log_santa_result(output, iteration, "passed")
return ship(output)
# Fix all critical issues (suggestions are optional)
output = fix_agent.execute(
output=output,
issues=issues,
instruction="Fix ONLY the flagged issues. Do not refactor or add unrequested changes."
)
# Re-run BOTH reviewers on fixed output (fresh agents, no memory of previous round)
review_b = Agent(prompt=REVIEWER_PROMPT.format(output=output, ...))
review_c = Agent(prompt=REVIEWER_PROMPT.format(output=output, ...))
# Exhausted iterations — escalate
log_santa_result(output, MAX_ITERATIONS, "escalated")
escalate_to_human(output, issues)
```
关键：每轮审查使用**全新的智能体**。审查者不得携带之前轮次的记忆，因为先前的上下文会造成锚定偏差。
## 实现模式
### 模式 A：Claude Code 子智能体（推荐）
子智能体提供真正的上下文隔离。每个审查者是一个独立的进程，没有共享状态。
```bash
# In a Claude Code session, use the Agent tool to spawn reviewers
# Both agents run in parallel for speed
```
```python
# Pseudocode for Agent tool invocation
reviewer_b = Agent(
description="Santa Review B",
prompt=f"Review this output for quality...\n\nRUBRIC:\n{rubric}\n\nOUTPUT:\n{output}"
)
reviewer_c = Agent(
description="Santa Review C",
prompt=f"Review this output for quality...\n\nRUBRIC:\n{rubric}\n\nOUTPUT:\n{output}"
)
```
### 模式 B：顺序内联（备用方案）
当子智能体不可用时，通过显式上下文重置模拟隔离：
1. 生成输出
2. 新上下文："你是审查者 1。仅根据此评估标准进行评估。找出问题。"
3. 逐字记录发现
4. 完全清除上下文
5. 新上下文："你是审查者 2。仅根据此评估标准进行评估。找出问题。"
6. 比较两个审查结果，修复，重复
子智能体模式严格优于内联模拟——内联模拟存在审查者之间上下文渗透的风险。
### 模式 C：批量采样
对于大批量（100+ 项），对每个项目都执行完整的圣诞老人方法成本过高。使用分层采样：
1. 对随机样本（批量的 10-15%，最少 5 项）运行圣诞老人方法
2. 按类型对失败进行分类（幻觉、合规性、完整性等）
3. 如果出现系统性模式，对整个批量应用针对性修复
4. 重新采样并重新验证修复后的批量
5. 持续直到干净的样本通过
```python
import random
def santa_batch(items, rubric, sample_rate=0.15):
sample = random.sample(items, max(5, int(len(items) * sample_rate)))
for item in sample:
result = santa_full(item, rubric)
if result.verdict == "NAUGHTY":
pattern = classify_failure(result.issues)
items = batch_fix(items, pattern) # Fix all items matching pattern
return santa_batch(items, rubric) # Re-sample
return items # Clean sample → ship batch
```
## 故障模式与缓解措施
| 故障模式 | 症状 | 缓解措施 |
|-------------|---------|------------|
| 无限循环 | 修复后审查者仍不断发现新问题 | 最大迭代次数限制（3 次）。升级处理。 |
| 橡皮图章 | 两个审查者都通过所有内容 | 对抗性提示："你的工作是发现问题，而不是批准。" |
| 主观漂移 | 审查者标记风格偏好，而非错误 | 严格的评估标准，仅包含客观的通过/失败标准 |
| 修复回归 | 修复问题 A 引入了问题 B | 每轮使用全新的审查者来捕获回归 |
| 审查者一致性偏差 | 两个审查者都遗漏了同一件事 | 独立性可缓解但无法消除。对于关键输出，添加第三个审查者或人工抽检。 |
| 成本激增 | 大型输出上迭代次数过多 | 批量采样模式。每个验证周期的预算上限。 |
## 与其他技能的集成
| 技能 | 关系 |
|-------|-------------|
| 验证循环 | 用于确定性检查（构建、代码检查、测试）。圣诞老人方法用于语义检查（准确性、幻觉）。先运行验证循环，再运行圣诞老人方法。 |
| 评估工具 | 圣诞老人方法的结果反馈给评估指标。跟踪圣诞老人方法运行中的 pass@k，以衡量生成器质量随时间的变化。 |
| 持续学习 v2 | 圣诞老人方法的发现成为本能。同一标准上的重复失败 → 学习到的行为以避免该模式。 |
| 战略压缩 | 在压缩**之前**运行圣诞老人方法。不要在验证过程中丢失审查上下文。 |
## 指标
跟踪以下指标以衡量圣诞老人方法的有效性：
* **首次通过率**：第一轮通过圣诞老人方法的输出百分比（目标：>70%）
* **收敛平均迭代次数**：达到"表现良好"的平均轮数（目标：<1.5）
* **问题分类**：失败类型的分布（幻觉 vs. 完整性 vs. 合规性）
* **审查者一致性**：两个审查者都标记的问题与仅一个审查者标记的问题的百分比（一致性低 = 需要收紧评估标准）
* **逃逸率**：发布后发现但圣诞老人方法本应捕获的问题（目标：0）
## 成本分析
每个验证周期，圣诞老人方法的代币成本大约是单独生成的 2-3 倍。对于大多数高风险的输出，这很划算：
```
圣诞老人的成本 = (生成代币) + 2×(每轮审查代币) × (平均轮数)
不做圣诞老人的成本 = (声誉损害) + (纠正努力) + (信任侵蚀)
```
对于批量操作，采样模式将成本降低到完全验证的约 15-20%，同时捕获超过 90% 的系统性问题。

60
docs/zh-CN/skills/skill-comply/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
---
name: skill-comply
description: 可视化技能、规则和代理定义是否被实际遵循——自动生成3种提示严格级别的场景，运行代理，分类行为序列，并报告完整工具调用时间线的合规率
origin: ECC
tools: Read, Bash
---
# skill-comply：自动化合规性测量
通过以下方式测量编码代理是否实际遵循技能、规则或代理定义：
1. 从任意 .md 文件自动生成预期行为序列（规范）
2. 自动生成提示严格程度递减的场景（支持性 → 中性 → 竞争性）
3. 运行 `claude -p` 并通过 stream-json 捕获工具调用轨迹
4. 使用 LLM（而非正则表达式）将工具调用分类到规范步骤
5. 确定性检查时间顺序
6. 生成包含规范、提示和时间线的自包含报告
## 支持的目标
* **技能**（`skills/*/SKILL.md`）：工作流技能，如搜索优先、TDD 指南
* **规则**（`rules/common/*.md`）：强制性规则，如 testing.md、security.md、git-workflow.md
* **代理定义**（`agents/*.md`）：代理是否在预期时被调用（内部工作流验证尚不支持）
## 何时激活
* 用户运行 `/skill-comply <path>`
* 用户询问"这条规则是否真的被遵循？"
* 添加新规则/技能后，验证代理合规性
* 作为质量维护的一部分定期执行
## 使用方法
```bash
# Full run
uv run python -m scripts.run ~/.claude/rules/common/testing.md
# Dry run (no cost, spec + scenarios only)
uv run python -m scripts.run --dry-run ~/.claude/skills/search-first/SKILL.md
# Custom models
uv run python -m scripts.run --gen-model haiku --model sonnet <path>
```
## 关键概念：提示独立性
测量技能/规则是否在提示未明确支持时仍被遵循。
## 报告内容
报告是自包含的，包括：
1. 预期行为序列（自动生成的规范）
2. 场景提示（每个严格程度级别询问的内容）
3. 每个场景的合规性评分
4. 带有 LLM 分类标签的工具调用时间线
### 高级（可选）
对于熟悉钩子的用户，报告还包含针对合规性较低的步骤的钩子提升建议。此为参考信息——主要价值在于合规性本身的可见性。

154
docs/zh-CN/skills/social-graph-ranker/SKILL.md Normal file
View File

@@ -0,0 +1,154 @@
---
name: social-graph-ranker
description: 加权社交图谱排名，用于在X和LinkedIn上发现温暖介绍、桥梁评分和网络差距分析。当用户想要可重用的图谱排名引擎本身，而不是其上层更广泛的推广或网络维护工作流时使用。
origin: ECC
---
# 社交图谱排名器
面向网络感知外联的规范化加权图排名层。
当用户需要以下功能时使用此工具：
* 根据内在价值对现有互关或联系人进行排名
* 为目标列表绘制温暖路径
* 衡量跨一度和二度连接的桥梁价值
* 决定哪些目标适合温暖引荐而非直接冷启动外联
* 独立于 `lead-intelligence` 或 `connections-optimizer` 理解图谱数学原理
## 何时独立使用
当用户主要需要排名引擎时选择此技能：
* "我的网络中谁最适合引荐我？"
* "对我的互关进行排名，看谁能帮我联系到这些人"
* "针对此ICP映射我的图谱"
* "展示桥梁数学计算"
当用户真正需要以下功能时，请勿单独使用此技能：
* 完整的潜在客户生成和外联序列 -> 使用 `lead-intelligence`
* 修剪、重新平衡和扩展网络 -> 使用 `connections-optimizer`
## 输入
收集或推断：
* 目标人物、公司或ICP定义
* 用户在X、LinkedIn或两者上的当前图谱
* 权重优先级，如角色、行业、地理位置和响应性
* 遍历深度和衰减容忍度
## 核心模型
给定：
* `T` = 加权目标集
* `M` = 你当前的互关/直接联系人
* `d(m, t)` = 从互关 `m` 到目标 `t` 的最短跳数距离
* `w(t)` = 来自信号评分的目标权重
基础桥梁分数：
```text
B(m) = Σ_{t ∈ T} w(t) · λ^(d(m,t) - 1)
```
其中：
* `λ` 是衰减因子，通常为 `0.5`
* 直接路径贡献全部价值
* 每增加一跳，贡献减半
二度扩展：
```text
B_ext(m) = B(m) + α · Σ_{m' ∈ N(m) \\ M} Σ_{t ∈ T} w(t) · λ^(d(m',t))
```
其中：
* `N(m) \\ M` 是互关认识但你认识的人集合
* `α` 对二度可达性进行折扣，通常为 `0.3`
响应调整后的最终排名：
```text
R(m) = B_ext(m) · (1 + β · engagement(m))
```
其中：
* `engagement(m)` 是归一化的响应性或关系强度
* `β` 是参与度加成，通常为 `0.2`
解读：
* 第一梯队：高 `R(m)` 和直接桥梁路径 -> 温暖引荐请求
* 第二梯队：中等 `R(m)` 和一跳桥梁路径 -> 条件性引荐请求
* 第三梯队：低 `R(m)` 或无可行桥梁 -> 直接外联或关注缺口填补
## 评分信号
在图遍历前根据当前优先级集对目标进行加权：
* 角色或职位匹配度
* 公司或行业契合度
* 当前活跃度和时效性
* 地理相关性
* 影响力或覆盖范围
* 响应可能性
在遍历后对互关进行加权：
* 进入目标集的加权路径数量
* 这些路径的直接性
* 响应性或过往互动历史
* 进行引荐的上下文契合度
## 工作流程
1. 构建加权目标集。
2. 从X、LinkedIn或两者拉取用户的图谱。
3. 计算直接桥梁分数。
4. 为最高价值的互关扩展二度候选者。
5. 按 `R(m)` 排名。
6. 返回：
* 最佳温暖引荐请求
* 条件性桥梁路径
* 不存在温暖路径的图谱缺口
## 输出格式
```text
社交图谱排名
====================
优先级集合：
平台：
衰减模型：
顶级桥梁
- 共同好友 / 连接
基础分数：
扩展分数：
最佳目标：
路径摘要：
推荐操作：
条件路径
- 共同好友 / 连接
原因：
额外跳数成本：
无温暖路径
- 目标
推荐：直接联系 / 填补图谱空白
```
## 相关技能
* `lead-intelligence` 在更广泛的目标发现和外联管道中使用此排名模型
* `connections-optimizer` 在决定保留、修剪或添加谁时使用相同的桥梁逻辑
* `brand-voice` 应在起草任何引荐请求或直接外联之前运行
* `x-api` 提供X图谱访问和可选执行路径

121
docs/zh-CN/skills/token-budget-advisor/SKILL.md Normal file
View File

@@ -0,0 +1,121 @@
---
name: token-budget-advisor
description: 在回答前，为用户提供关于消耗多少响应深度的知情选择。当用户明确希望控制响应长度、深度或令牌预算时使用此技能。触发条件："token budget", "token count", "token usage", "token limit", "response length", "answer depth", "short version", "brief answer", "detailed answer", "exhaustive answer", "respuesta corta vs larga", "cuántos tokens", "ahorrar tokens", "responde al 50%", "dame la versión corta", "quiero controlar cuánto usas"，或用户明确要求控制答案大小或深度的清晰变体。不触发条件：用户已在当前会话中指定了级别（保持该级别），请求明显是单字答案，或"token"指代认证/会话/支付令牌而非响应大小。origin: community
---
# Token预算顾问（TBA）
在Claude回答之前拦截响应流程，让用户选择回答深度。
## 何时使用
* 用户希望控制回答的长度或详细程度
* 用户提及token、预算、深度或回答长度
* 用户说"简短版"、"太长不看"、"简要"、"25%"、"详尽"等
* 任何用户希望预先选择深度/详细程度的情况
**不要触发**当：用户已在本会话中设置了级别（静默保持），或答案本身只有一行。
## 工作原理
### 第一步 — 估算输入token
使用仓库的标准上下文预算启发式方法，在脑海中估算提示词的token数量。
使用与[context-budget](../context-budget/SKILL.md)相同的校准指南：
* 散文：`words × 1.3`
* 代码密集或混合/代码块：`chars / 4`
对于混合内容，使用主导内容类型并保持估算启发式方法。
### 第二步 — 按复杂度估算响应大小
对提示词进行分类，然后应用乘数范围获取完整响应窗口：
| 复杂度 | 乘数范围 | 示例提示词 |
|--------------|------------|------------------------------------------------------|
| 简单 | 3× – 8× | "X是什么？"，是/否问题，单一事实 |
| 中等 | 8× – 20× | "X是如何工作的？" |
| 中高 | 10× – 25× | 带上下文的代码请求 |
| 复杂 | 15× – 40× | 多部分分析、比较、架构 |
| 创意 | 10× – 30× | 故事、散文、叙事写作 |
响应窗口 = `input_tokens × mult_min` 到 `input_tokens × mult_max`（但不要超过模型配置的输出token限制）。
### 第三步 — 呈现深度选项
在**回答之前**呈现此区块，使用实际估算的数字：
```
分析您的提示...
输入：~[N] 个令牌 | 类型：[类型] | 复杂度：[级别] | 语言：[语言]
选择您的深度级别：
[1] 基础 (25%) -> ~[令牌数] 直接回答，无开场白
[2] 适中 (50%) -> ~[令牌数] 回答 + 背景 + 1个示例
[3] 详细 (75%) -> ~[令牌数] 完整回答及备选方案
[4] 详尽 (100%) -> ~[令牌数] 全部内容，无限制
选择哪个级别？(1-4 或说 "25% 深度", "50% 深度", "75% 深度", "100% 深度")
精确度：启发式估计约 85-90% 准确率（±15%）。
```
各级别token估算（在响应窗口内）：
* 25% → `min + (max - min) × 0.25`
* 50% → `min + (max - min) × 0.50`
* 75% → `min + (max - min) × 0.75`
* 100% → `max`
### 第四步 — 按所选级别回答
| 级别 | 目标长度 | 包含内容 | 省略内容 |
|------------------|---------------------|-----------------------------------------------------|---------------------------------------------------|
| 25% 核心 | 最多2-4句话 | 直接回答、关键结论 | 上下文、示例、细微差别、替代方案 |
| 50% 适中 | 1-3个段落 | 答案+必要上下文+1个示例 | 深度分析、边界情况、参考文献 |
| 75% 详细 | 结构化回答 | 多个示例、优缺点、替代方案 | 极端边界情况、详尽参考文献 |
| 100% 详尽 | 无限制 | 一切内容——完整分析、所有代码、所有视角 | 无 |
## 快捷方式 — 跳过提问
如果用户已表明级别，立即按该级别回答，无需询问：
| 用户所说 | 级别 |
|----------------------------------------------------|-------|
| "1" / "25%深度" / "简短版" / "简要回答" / "太长不看" | 25% |
| "2" / "50%深度" / "适中深度" / "平衡回答" | 50% |
| "3" / "75%深度" / "详细回答" / "全面回答" | 75% |
| "4" / "100%深度" / "详尽回答" / "完整深入分析" | 100% |
如果用户在本会话中已设置级别，后续回答**静默保持**该级别，除非用户更改。
## 精度说明
此技能使用启发式估算——非真实分词器。准确率约85-90%，偏差±15%。始终显示免责声明。
## 示例
### 触发场景
* "先给我简短版。"
* "你的回答会用多少token？"
* "按50%深度回答。"
* "我要详尽的答案，不要摘要。"
* "先给我简短版，再给详细版。"
### 不触发场景
* "什么是JWT token？"
* "结账流程使用了一个支付token。"
* "这正常吗？"
* "完成重构。"
* 用户已为本会话选择深度后的后续问题
## 来源
来自[TBA — Claude Code的Token预算顾问](https://github.com/Xabilimon1/Token-Budget-Advisor-Claude-Code-)的独立技能。
原始项目还附带了一个Python估算脚本，但本仓库保持技能自包含且仅使用启发式方法。