zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-04-18 08:03:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(zh-CN): sync Chinese docs with latest upstream changes (#341)

Browse Source 
* docs(zh-CN): sync Chinese docs with latest upstream changes

* docs(zh-CN): update link

---------

Co-authored-by: neo <neo.dowithless@gmail.com>
This commit is contained in:
zdoc.app
2026-03-08 06:48:02 +08:00
committed by GitHub
parent da17d33ac3
commit abcf38b085
53 changed files with 2977 additions and 610 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/zh-CN/skills/agent-harness-construction/SKILL.md Normal file
View File

@@ -0,0 +1,77 @@
---
name: agent-harness-construction
description: 设计和优化AI代理的动作空间、工具定义和观察格式，以提高完成率。
origin: ECC
---
# 智能体框架构建
当你在改进智能体的规划、调用工具、从错误中恢复以及收敛到完成状态的方式时，使用此技能。
## 核心模型
智能体输出质量受限于：
1. 行动空间质量
2. 观察质量
3. 恢复质量
4. 上下文预算质量
## 行动空间设计
1. 使用稳定、明确的工具名称。
2. 保持输入模式优先且范围狭窄。
3. 返回确定性的输出形状。
4. 除非无法隔离，否则避免使用全能型工具。
## 粒度规则
* 对高风险操作（部署、迁移、权限）使用微工具。
* 对常见的编辑/读取/搜索循环使用中等工具。
* 仅当往返开销是主要成本时使用宏工具。
## 观察设计
每个工具响应都应包括：
* `status`: success|warning|error
* `summary`: 一行结果
* `next_actions`: 可执行的后续步骤
* `artifacts`: 文件路径 / ID
## 错误恢复契约
对于每个错误路径，应包括：
* 根本原因提示
* 安全重试指令
* 明确的停止条件
## 上下文预算管理
1. 保持系统提示词最少且不变。
2. 将大量指导信息移至按需加载的技能中。
3. 优先引用文件，而不是内联长文档。
4. 在阶段边界处进行压缩，而不是任意的令牌阈值。
## 架构模式指导
* ReAct：最适合路径不确定的探索性任务。
* 函数调用：最适合结构化的确定性流程。
* 混合模式（推荐）：ReAct 规划 + 类型化工具执行。
## 基准测试
跟踪：
* 完成率
* 每项任务的重试次数
* pass@1 和 pass@3
* 每个成功任务的成本
## 反模式
* 太多语义重叠的工具。
* 不透明的工具输出，没有恢复提示。
* 仅输出错误而没有后续步骤。
* 上下文过载，包含不相关的引用。

66
docs/zh-CN/skills/agentic-engineering/SKILL.md Normal file
View File

@@ -0,0 +1,66 @@
---
name: agentic-engineering
description: 作为代理工程师，采用评估优先执行、分解和成本感知模型路由进行操作。
origin: ECC
---
# 智能体工程
在 AI 智能体执行大部分实施工作、而人类负责质量与风险控制的工程工作流中使用此技能。
## 操作原则
1. 在执行前定义完成标准。
2. 将工作分解为智能体可处理的单元。
3. 根据任务复杂度路由模型层级。
4. 使用评估和回归检查进行度量。
## 评估优先循环
1. 定义能力评估和回归评估。
2. 运行基线并捕获失败特征。
3. 执行实施。
4. 重新运行评估并比较差异。
## 任务分解
应用 15 分钟单元规则：
* 每个单元应可独立验证
* 每个单元应有一个主要风险
* 每个单元应暴露一个清晰的完成条件
## 模型路由
* Haiku：分类、样板转换、狭窄编辑
* Sonnet：实施和重构
* Opus：架构、根因分析、多文件不变量
## 会话策略
* 对于紧密耦合的单元，继续使用同一会话。
* 在主要阶段转换后，启动新的会话。
* 在里程碑完成后进行压缩，而不是在主动调试期间。
## AI 生成代码的审查重点
优先审查：
* 不变量和边界情况
* 错误边界
* 安全性和身份验证假设
* 隐藏的耦合和上线风险
当自动化格式化/代码检查工具已强制执行代码风格时，不要在仅涉及风格分歧的审查上浪费周期。
## 成本纪律
按任务跟踪：
* 模型
* 令牌估算
* 重试次数
* 实际用时
* 成功/失败
仅当较低层级的模型失败且存在清晰的推理差距时，才升级模型层级。

55
docs/zh-CN/skills/ai-first-engineering/SKILL.md Normal file
View File

@@ -0,0 +1,55 @@
---
name: ai-first-engineering
description: 团队中人工智能代理生成大部分实施输出的工程运营模型。
origin: ECC
---
# 人工智能优先工程
在为由人工智能辅助代码生成的团队设计流程、评审和架构时，使用此技能。
## 流程转变
1. 规划质量比打字速度更重要。
2. 评估覆盖率比主观信心更重要。
3. 评审重点从语法转向系统行为。
## 架构要求
优先选择对智能体友好的架构：
* 明确的边界
* 稳定的契约
* 类型化的接口
* 确定性的测试
避免隐含的行为分散在隐藏的惯例中。
## 人工智能优先团队中的代码评审
评审关注：
* 行为回归
* 安全假设
* 数据完整性
* 故障处理
* 发布安全性
尽量减少花在已由自动化覆盖的风格问题上的时间。
## 招聘和评估信号
强大的人工智能优先工程师：
* 能清晰地分解模糊的工作
* 定义可衡量的验收标准
* 生成高价值的提示和评估
* 在交付压力下执行风险控制
## 测试标准
提高生成代码的测试标准：
* 对涉及的领域要求回归测试覆盖率
* 明确的边界情况断言
* 接口边界的集成检查

621
docs/zh-CN/skills/autonomous-loops/SKILL.md Normal file
View File

@@ -0,0 +1,621 @@
---
name: autonomous-loops
description: "自主Claude代码循环的模式与架构——从简单的顺序管道到基于RFC的多智能体有向无环图系统。"
origin: ECC
---
# 自主循环技能
> 兼容性说明 (v1.8.0): `autonomous-loops` 保留一个发布周期。
> 规范的技能名称现在是 `continuous-agent-loop`。新的循环指南应在此处编写，而此技能继续可用以避免破坏现有工作流。
在循环中自主运行 Claude Code 的模式、架构和参考实现。涵盖从简单的 `claude -p` 管道到完整的 RFC 驱动的多智能体 DAG 编排的一切。
## 何时使用
* 建立无需人工干预即可运行的自主开发工作流
* 为你的问题选择正确的循环架构（简单与复杂）
* 构建 CI/CD 风格的持续开发管道
* 运行具有合并协调的并行智能体
* 在循环迭代中实现上下文持久化
* 为自主工作流添加质量门和清理步骤
## 循环模式谱系
从最简单到最复杂：
| 模式 | 复杂度 | 最适合 |
|---------|-----------|----------|
| [顺序管道](#1-顺序管道-claude--p) | 低 | 日常开发步骤，脚本化工作流 |
| [NanoClaw REPL](#2-nanoclaw-repl) | 低 | 交互式持久会话 |
| [无限智能体循环](#3-无限智能体循环) | 中 | 并行内容生成，规范驱动的工作 |
| [持续 Claude PR 循环](#4-持续-claude-pr-循环) | 中 | 具有 CI 门的跨天迭代项目 |
| [去草率化模式](#5-去草率化模式) | 附加 | 任何实现者步骤后的质量清理 |
| [Ralphinho / RFC 驱动的 DAG](#6-ralphinho--rfc-驱动的-dag-编排) | 高 | 大型功能，具有合并队列的多单元并行工作 |
***
## 1. 顺序管道 (`claude -p`)
**最简单的循环。** 将日常开发分解为一系列非交互式 `claude -p` 调用。每次调用都是一个具有清晰提示的专注步骤。
### 核心见解
> 如果你无法想出这样的循环，那意味着你甚至无法在交互模式下驱动 LLM 来修复你的代码。
`claude -p` 标志以非交互方式运行 Claude Code 并附带提示，完成后退出。链式调用来构建管道：
```bash
#!/bin/bash
# daily-dev.sh — Sequential pipeline for a feature branch
set -e
# Step 1: Implement the feature
claude -p "Read the spec in docs/auth-spec.md. Implement OAuth2 login in src/auth/. Write tests first (TDD). Do NOT create any new documentation files."
# Step 2: De-sloppify (cleanup pass)
claude -p "Review all files changed by the previous commit. Remove any unnecessary type tests, overly defensive checks, or testing of language features (e.g., testing that TypeScript generics work). Keep real business logic tests. Run the test suite after cleanup."
# Step 3: Verify
claude -p "Run the full build, lint, type check, and test suite. Fix any failures. Do not add new features."
# Step 4: Commit
claude -p "Create a conventional commit for all staged changes. Use 'feat: add OAuth2 login flow' as the message."
```
### 关键设计原则
1. **每个步骤都是隔离的** — 每次 `claude -p` 调用都是一个新的上下文窗口，意味着步骤之间没有上下文泄露。
2. **顺序很重要** — 步骤按顺序执行。每个步骤都建立在前一个步骤留下的文件系统状态之上。
3. **否定指令是危险的** — 不要说“不要测试类型系统。”相反，添加一个单独的清理步骤（参见[去草率化模式](#5-去草率化模式)）。
4. **退出代码会传播** — `set -e` 在失败时停止管道。
### 变体
**使用模型路由：**
```bash
# Research with Opus (deep reasoning)
claude -p --model opus "Analyze the codebase architecture and write a plan for adding caching..."
# Implement with Sonnet (fast, capable)
claude -p "Implement the caching layer according to the plan in docs/caching-plan.md..."
# Review with Opus (thorough)
claude -p --model opus "Review all changes for security issues, race conditions, and edge cases..."
```
**使用环境上下文：**
```bash
# Pass context via files, not prompt length
echo "Focus areas: auth module, API rate limiting" > .claude-context.md
claude -p "Read .claude-context.md for priorities. Work through them in order."
rm .claude-context.md
```
**使用 `--allowedTools` 限制：**
```bash
# Read-only analysis pass
claude -p --allowedTools "Read,Grep,Glob" "Audit this codebase for security vulnerabilities..."
# Write-only implementation pass
claude -p --allowedTools "Read,Write,Edit,Bash" "Implement the fixes from security-audit.md..."
```
***
## 2. NanoClaw REPL
**ECC 内置的持久循环。** 一个具有会话感知的 REPL，它使用完整的对话历史同步调用 `claude -p`。
```bash
# Start the default session
node scripts/claw.js
# Named session with skill context
CLAW_SESSION=my-project CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
```
### 工作原理
1. 从 `~/.claude/claw/{session}.md` 加载对话历史
2. 每个用户消息都连同完整历史记录作为上下文发送给 `claude -p`
3. 响应被追加到会话文件中（Markdown 作为数据库）
4. 会话在重启后持久存在
### NanoClaw 与顺序管道的选择
| 用例 | NanoClaw | 顺序管道 |
|----------|----------|-------------------|
| 交互式探索 | 是 | 否 |
| 脚本化自动化 | 否 | 是 |
| 会话持久性 | 内置 | 手动 |
| 上下文累积 | 每轮增长 | 每个步骤都是新的 |
| CI/CD 集成 | 差 | 优秀 |
有关完整详情，请参阅 `/claw` 命令文档。
***
## 3. 无限智能体循环
**一个双提示系统**，用于编排并行子智能体以进行规范驱动的生成。由 disler 开发（致谢：@disler）。
### 架构：双提示系统
```
PROMPT 1 (Orchestrator) PROMPT 2 (Sub-Agents)
┌─────────────────────┐ ┌──────────────────────┐
│ Parse spec file │ │ Receive full context │
│ Scan output dir │ deploys │ Read assigned number │
│ Plan iteration │────────────│ Follow spec exactly │
│ Assign creative dirs │ N agents │ Generate unique output │
│ Manage waves │ │ Save to output dir │
└─────────────────────┘ └──────────────────────┘
```
### 模式
1. **规范分析** — 编排器读取一个定义要生成内容的规范文件（Markdown）
2. **目录侦察** — 扫描现有输出以找到最高的迭代编号
3. **并行部署** — 启动 N 个子智能体，每个都有：
* 完整的规范
* 独特的创意方向
* 特定的迭代编号（无冲突）
* 现有迭代的快照（用于确保唯一性）
4. **波次管理** — 对于无限模式，部署 3-5 个智能体的波次，直到上下文耗尽
### 通过 Claude Code 命令实现
创建 `.claude/commands/infinite.md`：
```markdown
从 $ARGUMENTS 中解析以下参数：
1. spec_file — 规范 Markdown 文件的路径
2. output_dir — 保存迭代结果的目录
3. count — 整数 1-N 或 "infinite"
阶段 1： 读取并深入理解规范。
阶段 2： 列出 output_dir，找到最高的迭代编号。从 N+1 开始。
阶段 3： 规划创意方向 — 每个代理获得一个**不同的**主题/方法。
阶段 4： 并行部署子代理（使用 Task 工具）。每个代理接收：
- 完整的规范文本
- 当前目录快照
- 它们被分配的迭代编号
- 它们独特的创意方向
阶段 5（无限模式）： 以 3-5 个为一波进行循环，直到上下文不足为止。
```
**调用：**
```bash
/project:infinite specs/component-spec.md src/ 5
/project:infinite specs/component-spec.md src/ infinite
```
### 批处理策略
| 数量 | 策略 |
|-------|----------|
| 1-5 | 所有智能体同时运行 |
| 6-20 | 每批 5 个 |
| 无限 | 3-5 个一波，逐步复杂化 |
### 关键见解：通过分配实现唯一性
不要依赖智能体自我区分。编排器**分配**给每个智能体一个特定的创意方向和迭代编号。这可以防止并行智能体之间的概念重复。
***
## 4. 持续 Claude PR 循环
**一个生产级的 shell 脚本**，在持续循环中运行 Claude Code，创建 PR，等待 CI，并自动合并。由 AnandChowdhary 创建（致谢：@AnandChowdhary）。
### 核心循环
```
┌─────────────────────────────────────────────────────┐
│ CONTINUOUS CLAUDE ITERATION │
│ │
│ 1. Create branch (continuous-claude/iteration-N) │
│ 2. Run claude -p with enhanced prompt │
│ 3. (Optional) Reviewer pass — separate claude -p │
│ 4. Commit changes (claude generates message) │
│ 5. Push + create PR (gh pr create) │
│ 6. Wait for CI checks (poll gh pr checks) │
│ 7. CI failure? → Auto-fix pass (claude -p) │
│ 8. Merge PR (squash/merge/rebase) │
│ 9. Return to main → repeat │
│ │
│ Limit by: --max-runs N | --max-cost $X │
│ --max-duration 2h | completion signal │
└─────────────────────────────────────────────────────┘
```
### 安装
```bash
curl -fsSL https://raw.githubusercontent.com/AnandChowdhary/continuous-claude/HEAD/install.sh | bash
```
### 用法
```bash
# Basic: 10 iterations
continuous-claude --prompt "Add unit tests for all untested functions" --max-runs 10
# Cost-limited
continuous-claude --prompt "Fix all linter errors" --max-cost 5.00
# Time-boxed
continuous-claude --prompt "Improve test coverage" --max-duration 8h
# With code review pass
continuous-claude \
--prompt "Add authentication feature" \
--max-runs 10 \
--review-prompt "Run npm test && npm run lint, fix any failures"
# Parallel via worktrees
continuous-claude --prompt "Add tests" --max-runs 5 --worktree tests-worker &
continuous-claude --prompt "Refactor code" --max-runs 5 --worktree refactor-worker &
wait
```
### 跨迭代上下文：SHARED\_TASK\_NOTES.md
关键创新：一个 `SHARED_TASK_NOTES.md` 文件在迭代间持久存在：
```markdown
## 进展
- [x] 已添加认证模块测试（第1轮）
- [x] 已修复令牌刷新中的边界情况（第2轮）
- [ ] 仍需完成：速率限制测试、错误边界测试
## 后续步骤
- 接下来专注于速率限制模块
- 测试中位于 `tests/helpers.ts` 的模拟设置可以复用
```
Claude 在迭代开始时读取此文件，并在迭代结束时更新它。这弥合了独立 `claude -p` 调用之间的上下文差距。
### CI 失败恢复
当 PR 检查失败时，持续 Claude 会自动：
1. 通过 `gh run list` 获取失败的运行 ID
2. 生成一个新的带有 CI 修复上下文的 `claude -p`
3. Claude 通过 `gh run view` 检查日志，修复代码，提交，推送
4. 重新等待检查（最多 `--ci-retry-max` 次尝试）
### 完成信号
Claude 可以通过输出一个魔法短语来发出“我完成了”的信号：
```bash
continuous-claude \
--prompt "Fix all bugs in the issue tracker" \
--completion-signal "CONTINUOUS_CLAUDE_PROJECT_COMPLETE" \
--completion-threshold 3 # Stops after 3 consecutive signals
```
连续三次迭代发出完成信号会停止循环，防止在已完成的工作上浪费运行。
### 关键配置
| 标志 | 目的 |
|------|---------|
| `--max-runs N` | 在 N 次成功迭代后停止 |
| `--max-cost $X` | 在花费 $X 后停止 |
| `--max-duration 2h` | 在时间过去后停止 |
| `--merge-strategy squash` | squash、merge 或 rebase |
| `--worktree <name>` | 通过 git worktrees 并行执行 |
| `--disable-commits` | 试运行模式（无 git 操作） |
| `--review-prompt "..."` | 每次迭代添加审阅者审核 |
| `--ci-retry-max N` | 自动修复 CI 失败（默认：1） |
***
## 5. 去草率化模式
**任何循环的附加模式。** 在每个实现者步骤之后添加一个专门的清理/重构步骤。
### 问题
当你要求 LLM 使用 TDD 实现时，它对“编写测试”的理解过于字面：
* 测试验证 TypeScript 的类型系统是否有效（测试 `typeof x === 'string'`）
* 对类型系统已经保证的东西进行过度防御的运行时检查
* 测试框架行为而非业务逻辑
* 过多的错误处理掩盖了实际代码
### 为什么不使用否定指令？
在实现者提示中添加“不要测试类型系统”或“不要添加不必要的检查”会产生下游影响：
* 模型对所有测试都变得犹豫不决
* 它会跳过合法的边缘情况测试
* 质量不可预测地下降
### 解决方案：单独的步骤
与其限制实现者，不如让它彻底。然后添加一个专注的清理智能体：
```bash
# Step 1: Implement (let it be thorough)
claude -p "Implement the feature with full TDD. Be thorough with tests."
# Step 2: De-sloppify (separate context, focused cleanup)
claude -p "Review all changes in the working tree. Remove:
- Tests that verify language/framework behavior rather than business logic
- Redundant type checks that the type system already enforces
- Over-defensive error handling for impossible states
- Console.log statements
- Commented-out code
Keep all business logic tests. Run the test suite after cleanup to ensure nothing breaks."
```
### 在循环上下文中
```bash
for feature in "${features[@]}"; do
# Implement
claude -p "Implement $feature with TDD."
# De-sloppify
claude -p "Cleanup pass: review changes, remove test/code slop, run tests."
# Verify
claude -p "Run build + lint + tests. Fix any failures."
# Commit
claude -p "Commit with message: feat: add $feature"
done
```
### 关键见解
> 与其添加具有下游质量影响的否定指令，不如添加一个单独的去草率化步骤。两个专注的智能体胜过一个有约束的智能体。
***
## 6. Ralphinho / RFC 驱动的 DAG 编排
**最复杂的模式。** 一个 RFC 驱动的多智能体管道，将规范分解为依赖关系 DAG，通过分层质量管道运行每个单元，并通过智能体驱动的合并队列落地。由 enitrat 创建（致谢：@enitrat）。
### 架构概述
```
RFC/PRD Document
│
▼
DECOMPOSITION (AI)
Break RFC into work units with dependency DAG
│
▼
┌──────────────────────────────────────────────────────┐
│ RALPH LOOP (up to 3 passes) │
│ │
│ For each DAG layer (sequential, by dependency): │
│ │
│ ┌── Quality Pipelines (parallel per unit) ───────┐ │
│ │ Each unit in its own worktree: │ │
│ │ Research → Plan → Implement → Test → Review │ │
│ │ (depth varies by complexity tier) │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ ┌── Merge Queue ─────────────────────────────────┐ │
│ │ Rebase onto main → Run tests → Land or evict │ │
│ │ Evicted units re-enter with conflict context │ │
│ └────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────┘
```
### RFC 分解
AI 读取 RFC 并生成工作单元：
```typescript
interface WorkUnit {
id: string; // kebab-case identifier
name: string; // Human-readable name
rfcSections: string[]; // Which RFC sections this addresses
description: string; // Detailed description
deps: string[]; // Dependencies (other unit IDs)
acceptance: string[]; // Concrete acceptance criteria
tier: "trivial" | "small" | "medium" | "large";
}
```
**分解规则：**
* 倾向于更少、内聚的单元（最小化合并风险）
* 最小化跨单元文件重叠（避免冲突）
* 保持测试与实现在一起（永远不要分开“实现 X” + “测试 X”）
* 仅在实际存在代码依赖关系的地方设置依赖关系
依赖关系 DAG 决定了执行顺序：
```
Layer 0: [unit-a, unit-b] ← no deps, run in parallel
Layer 1: [unit-c] ← depends on unit-a
Layer 2: [unit-d, unit-e] ← depend on unit-c
```
### 复杂度层级
不同的层级获得不同深度的管道：
| 层级 | 管道阶段 |
|------|----------------|
| **trivial** | implement → test |
| **small** | implement → test → code-review |
| **medium** | research → plan → implement → test → PRD-review + code-review → review-fix |
| **large** | research → plan → implement → test → PRD-review + code-review → review-fix → final-review |
这可以防止对简单更改进行昂贵的操作，同时确保架构更改得到彻底审查。
### 独立的上下文窗口（消除作者偏见）
每个阶段在其自己的智能体进程中运行，拥有自己的上下文窗口：
| 阶段 | 模型 | 目的 |
|-------|-------|---------|
| Research | Sonnet | 读取代码库 + RFC，生成上下文文档 |
| Plan | Opus | 设计实现步骤 |
| Implement | Codex | 按照计划编写代码 |
| Test | Sonnet | 运行构建 + 测试套件 |
| PRD Review | Sonnet | 规范合规性检查 |
| Code Review | Opus | 质量 + 安全检查 |
| Review Fix | Codex | 处理审阅问题 |
| Final Review | Opus | 质量门（仅限大型层级） |
**关键设计：** 审阅者从未编写过它要审阅的代码。这消除了作者偏见——这是自我审阅中遗漏问题的最常见原因。
### 具有驱逐功能的合并队列
质量管道完成后，单元进入合并队列：
```
Unit branch
│
├─ Rebase onto main
│ └─ Conflict? → EVICT (capture conflict context)
│
├─ Run build + tests
│ └─ Fail? → EVICT (capture test output)
│
└─ Pass → Fast-forward main, push, delete branch
```
**文件重叠智能：**
* 非重叠单元并行推测性地落地
* 重叠单元逐个落地，每次重新变基
**驱逐恢复：**
被驱逐时，会捕获完整上下文（冲突文件、差异、测试输出）并反馈给下一个 Ralph 轮次的实现者：
```markdown
## 合并冲突 — 在下一次推送前解决
您之前的实现与另一个已先推送的单元发生了冲突。
请重构您的更改以避免以下冲突的文件/行。
{完整的排除上下文及差异}
```
### 阶段间的数据流
```
research.contextFilePath ──────────────────→ plan
plan.implementationSteps ──────────────────→ implement
implement.{filesCreated, whatWasDone} ─────→ test, reviews
test.failingSummary ───────────────────────→ reviews, implement (next pass)
reviews.{feedback, issues} ────────────────→ review-fix → implement (next pass)
final-review.reasoning ────────────────────→ implement (next pass)
evictionContext ───────────────────────────→ implement (after merge conflict)
```
### 工作树隔离
每个单元在隔离的工作树中运行（使用 jj/Jujutsu，而不是 git）：
```
/tmp/workflow-wt-{unit-id}/
```
同一单元的管道阶段**共享**一个工作树，在 research → plan → implement → test → review 之间保留状态（上下文文件、计划文件、代码更改）。
### 关键设计原则
1. **确定性执行** — 预先分解锁定并行性和顺序
2. **在杠杆点进行人工审阅** — 工作计划是单一最高杠杆干预点
3. **关注点分离** — 每个阶段在独立的上下文窗口中，由独立的智能体负责
4. **带上下文的冲突恢复** — 完整的驱逐上下文支持智能重试，而非盲目重试
5. **层级驱动的深度** — 琐碎更改跳过研究/审阅；大型更改获得最大审查
6. **可恢复的工作流** — 完整状态持久化到 SQLite；可从任何点恢复
### 何时使用 Ralphinho 与更简单的模式
| 信号 | 使用 Ralphinho | 使用更简单的模式 |
|--------|--------------|-------------------|
| 多个相互依赖的工作单元 | 是 | 否 |
| 需要并行实现 | 是 | 否 |
| 可能出现合并冲突 | 是 | 否（顺序即可） |
| 单文件更改 | 否 | 是（顺序管道） |
| 跨天项目 | 是 | 可能（持续-claude） |
| 规范/RFC 已编写 | 是 | 可能 |
| 对单个事物的快速迭代 | 否 | 是（NanoClaw 或管道） |
***
## 选择正确的模式
### 决策矩阵
```
Is the task a single focused change?
├─ Yes → Sequential Pipeline or NanoClaw
└─ No → Is there a written spec/RFC?
├─ Yes → Do you need parallel implementation?
│ ├─ Yes → Ralphinho (DAG orchestration)
│ └─ No → Continuous Claude (iterative PR loop)
└─ No → Do you need many variations of the same thing?
├─ Yes → Infinite Agentic Loop (spec-driven generation)
└─ No → Sequential Pipeline with de-sloppify
```
### 模式组合
这些模式可以很好地组合：
1. **顺序流水线 + 去草率化** — 最常见的组合。每个实现步骤都进行一次清理。
2. **连续 Claude + 去草率化** — 为每次迭代添加带有去草率化指令的 `--review-prompt`。
3. **任何循环 + 验证** — 在提交前，使用 ECC 的 `/verify` 命令或 `verification-loop` 技能作为关卡。
4. **Ralphinho 在简单循环中的分层方法** — 即使在顺序流水线中，你也可以将简单任务路由到 Haiku，复杂任务路由到 Opus：
```bash
# 简单的格式修复
claude -p --model haiku "Fix the import ordering in src/utils.ts"
# 复杂的架构变更
claude -p --model opus "Refactor the auth module to use the strategy pattern"
```
***
## 反模式
### 常见错误
1. **没有退出条件的无限循环** — 始终设置最大运行次数、最大成本、最大持续时间或完成信号。
2. **迭代之间没有上下文桥接** — 每次 `claude -p` 调用都从头开始。使用 `SHARED_TASK_NOTES.md` 或文件系统状态来桥接上下文。
3. **重试相同的失败** — 如果一次迭代失败，不要只是重试。捕获错误上下文并将其提供给下一次尝试。
4. **使用负面指令而非清理过程** — 不要说“不要做 X”。添加一个单独的步骤来移除 X。
5. **所有智能体都在一个上下文窗口中** — 对于复杂的工作流，将关注点分离到不同的智能体进程中。审查者永远不应该是作者。
6. **在并行工作中忽略文件重叠** — 如果两个并行智能体可能编辑同一个文件，你需要一个合并策略（顺序落地、变基或冲突解决）。
***
## 参考资料
| 项目 | 作者 | 链接 |
|---------|--------|------|
| Ralphinho | enitrat | credit: @enitrat |
| Infinite Agentic Loop | disler | credit: @disler |
| Continuous Claude | AnandChowdhary | credit: @AnandChowdhary |
| NanoClaw | ECC | 此仓库中的 `/claw` 命令 |
| Verification Loop | ECC | 此仓库中的 `skills/verification-loop/` |

23
docs/zh-CN/skills/configure-ecc/SKILL.md
View File

@@ -67,7 +67,24 @@ mkdir -p $TARGET/skills $TARGET/rules
## 步骤 2：选择并安装技能
### 2a：选择技能类别
### 2a: 选择范围（核心 vs 细分领域）
默认为 **核心（推荐给新用户）** — 对于研究优先的工作流，复制 `.agents/skills/*` 加上 `skills/search-first/`。此捆绑包涵盖工程、评估、验证、安全、战略压缩、前端设计以及 Anthropic 跨职能技能（文章写作、内容引擎、市场研究、前端幻灯片）。
使用 `AskUserQuestion`（单选）：
```
Question: "Install core skills only, or include niche/framework packs?"
Options:
- "Core only (recommended)" — "tdd, e2e, evals, verification, research-first, security, frontend patterns, compacting, cross-functional Anthropic skills"
- "Core + selected niche" — "Add framework/domain-specific skills after core"
- "Niche only" — "Skip core, install specific framework/domain skills"
Default: Core only
```
如果用户选择细分领域或核心 + 细分领域，则继续下面的类别选择，并且仅包含他们选择的那些细分领域技能。
### 2b: 选择技能类别
共有 27 项技能，分为 4 个类别。使用 `AskUserQuestion` 和 `multiSelect: true`：
@@ -80,7 +97,7 @@ Options:
- "All skills" — "Install every available skill"
```
### 2b：确认单项技能
### 2c: 确认个人技能
对于每个选定的类别，打印下面的完整技能列表，并要求用户确认或取消选择特定的技能。如果列表超过 4 项，将列表打印为文本，并使用 `AskUserQuestion`，提供一个 "安装所有列出项" 的选项，以及一个 "其他" 选项供用户粘贴特定名称。
@@ -143,7 +160,7 @@ Options:
|-------|-------------|
| `project-guidelines-example` | 用于创建项目特定技能的模板 |
### 2c：执行安装
### 2d: 执行安装
对于每个选定的技能，复制整个技能目录：

46
docs/zh-CN/skills/continuous-agent-loop/SKILL.md Normal file
View File

@@ -0,0 +1,46 @@
---
name: continuous-agent-loop
description: 具有质量门、评估和恢复控制的连续自主代理循环模式。
origin: ECC
---
# 持续代理循环
这是 v1.8+ 的规范循环技能名称。它在保持一个发布版本的兼容性的同时，取代了 `autonomous-loops`。
## 循环选择流程
```text
Start
|
+-- Need strict CI/PR control? -- yes --> continuous-pr
|
+-- Need RFC decomposition? -- yes --> rfc-dag
|
+-- Need exploratory parallel generation? -- yes --> infinite
|
+-- default --> sequential
```
## 组合模式
推荐的生产栈：
1. RFC 分解 (`ralphinho-rfc-pipeline`)
2. 质量门 (`plankton-code-quality` + `/quality-gate`)
3. 评估循环 (`eval-harness`)
4. 会话持久化 (`nanoclaw-repl`)
## 故障模式
* 循环空转，没有可衡量的进展
* 因相同根本原因而重复重试
* 合并队列停滞
* 无限制升级导致的成本漂移
## 恢复
* 冻结循环
* 运行 `/harness-audit`
* 将范围缩小到失败单元
* 使用明确的验收标准重放

304
docs/zh-CN/skills/continuous-learning-v2/SKILL.md
View File

@@ -1,33 +1,48 @@
---
name: continuous-learning-v2
description: 基于本能的学习系统，通过钩子观察会话，创建具有置信度评分的原子本能，并将其进化为技能/命令/代理。
description: 基于本能的学习系统，通过钩子观察会话，创建带置信度评分的原子本能，并将其进化为技能/命令/代理。v2.1版本增加了项目范围的本能，以防止跨项目污染。
origin: ECC
version: 2.0.0
version: 2.1.0
---
# 持续学习 v2 - 基于本能的架构
# 持续学习 v2.1 - 基于本能
的架构
一个高级学习系统，通过原子化的“本能”——带有置信度评分的小型习得行为——将你的 Claude Code 会话转化为可重用的知识。
部分灵感来源于 humanplane (credit: @humanplane) 的 Homunculus 项目。
**v2.1** 新增了**项目作用域的本能** — React 模式保留在你的 React 项目中，Python 约定保留在你的 Python 项目中，而通用模式（如“始终验证输入”）则全局共享。
## 何时激活
* 设置从 Claude Code 会话中自动学习时
* 通过钩子配置基于本能的行为提取时
* 调整学习行为的置信度阈值时
* 审查、导出或导入本能库时
* 将本能进化为完整技能、命令或代理时
* 设置从 Claude Code 会话自动学习
* 通过钩子配置基于本能的行为提取
* 调整已学习行为的置信度阈值
* 查看、导出或导入本能库
* 将本能进化为完整的技能、命令或代理
* 管理项目作用域与全局本能
* 将本能从项目作用域提升到全局作用域
## v2 的新特性
## v2.1 的新特性
| 特性 | v2.0 | v2.1 |
|---------|------|------|
| 存储 | 全局 (~/.claude/homunculus/) | 项目作用域 (projects/<hash>/) |
| 作用域 | 所有本能随处适用 | 项目作用域 + 全局 |
| 检测 | 无 | git remote URL / 仓库路径 |
| 提升 | 不适用 | 在 2+ 个项目中出现时，项目 → 全局 |
| 命令 | 4个 (status/evolve/export/import) | 6个 (+promote/projects) |
| 跨项目 | 存在污染风险 | 默认隔离 |
## v2 的新特性（对比 v1）
| 特性 | v1 | v2 |
|---------|----|----|
| 观察 | 停止钩子（会话结束） | 工具使用前/后（100% 可靠） |
| 分析 | 主上下文 | 后台代理（Haiku） |
| 粒度 | 完整技能 | 原子化的“本能” |
| 观察 | 停止钩子（会话结束） | PreToolUse/PostToolUse (100% 可靠) |
| 分析 | 主上下文 | 后台代理 (Haiku) |
| 粒度 | 完整技能 | 原子化“本能” |
| 置信度 | 无 | 0.3-0.9 加权 |
| 演进 | 直接到技能 | 本能 → 聚类 → 技能/命令/代理 |
| 进化 | 直接进化为技能 | 本能 -> 聚类 -> 技能/命令/代理 |
| 共享 | 无 | 导出/导入本能 |
## 本能模型
@@ -41,6 +56,9 @@ trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---
# Prefer Functional Style
@@ -55,51 +73,69 @@ Use functional patterns over classes when appropriate.
**属性：**
* **原子性** — 一个触发条件，一个动作
* **置信度加权** — 0.3 = 尝试性的，0.9 = 近乎确定
* **领域标记** — 代码风格、测试、git、调试、工作流等
* **证据支持** — 追踪是哪些观察创建了它
* **原子化** -- 一个触发条件，一个动作
* **置信度加权** -- 0.3 = 试探性，0.9 = 几乎确定
* **领域标记** -- 代码风格、测试、git、调试、工作流等
* **有证据支持** -- 追踪是哪些观察创建了它
* **作用域感知** -- `project` (默认) 或 `global`
## 工作原理
```
Session Activity
│
│ Hooks capture prompts + tool use (100% reliable)
▼
┌─────────────────────────────────────────┐
│ observations.jsonl │
│ (prompts, tool calls, outcomes) │
└─────────────────────────────────────────┘
│
│ Observer agent reads (background, Haiku)
▼
┌─────────────────────────────────────────┐
│ PATTERN DETECTION │
│ • User corrections → instinct │
│ • Error resolutions → instinct │
│ • Repeated workflows → instinct │
└─────────────────────────────────────────┘
│
│ Creates/updates
▼
┌─────────────────────────────────────────┐
│ instincts/personal/ │
│ • prefer-functional.md (0.7) │
│ • always-test-first.md (0.9) │
│ • use-zod-validation.md (0.6) │
└─────────────────────────────────────────┘
│
│ /evolve clusters
▼
┌─────────────────────────────────────────┐
│ evolved/ │
│ • commands/new-feature.md │
│ • skills/testing-workflow.md │
│ • agents/refactor-specialist.md │
└─────────────────────────────────────────┘
Session Activity (in a git repo)
|
| Hooks capture prompts + tool use (100% reliable)
| + detect project context (git remote / repo path)
v
+---------------------------------------------+
| projects/<project-hash>/observations.jsonl |
| (prompts, tool calls, outcomes, project) |
+---------------------------------------------+
|
| Observer agent reads (background, Haiku)
v
+---------------------------------------------+
| PATTERN DETECTION |
| * User corrections -> instinct |
| * Error resolutions -> instinct |
| * Repeated workflows -> instinct |
| * Scope decision: project or global? |
+---------------------------------------------+
|
| Creates/updates
v
+---------------------------------------------+
| projects/<project-hash>/instincts/personal/ |
| * prefer-functional.yaml (0.7) [project] |
| * use-react-hooks.yaml (0.9) [project] |
+---------------------------------------------+
| instincts/personal/ (GLOBAL) |
| * always-validate-input.yaml (0.85) [global]|
| * grep-before-edit.yaml (0.6) [global] |
+---------------------------------------------+
|
| /evolve clusters + /promote
v
+---------------------------------------------+
| projects/<hash>/evolved/ (project-scoped) |
| evolved/ (global) |
| * commands/new-feature.md |
| * skills/testing-workflow.md |
| * agents/refactor-specialist.md |
+---------------------------------------------+
```
## 项目检测
系统会自动检测您当前的项目：
1. **`CLAUDE_PROJECT_DIR` 环境变量** (最高优先级)
2. **`git remote get-url origin`** -- 哈希化以创建可移植的项目 ID (同一仓库在不同机器上获得相同的 ID)
3. **`git rev-parse --show-toplevel`** -- 使用仓库路径作为后备方案 (机器特定)
4. **全局后备方案** -- 如果未检测到项目，本能将进入全局作用域
每个项目都会获得一个 12 字符的哈希 ID (例如 `a1b2c3d4e5f6`)。`~/.claude/homunculus/projects.json` 处的注册表文件将 ID 映射到人类可读的名称。
## 快速开始
### 1. 启用观察钩子
@@ -115,14 +151,14 @@ Session Activity
"matcher": "*",
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh pre"
"command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"
}]
}],
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh post"
"command": "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/hooks/observe.sh"
}]
}]
}
@@ -138,14 +174,14 @@ Session Activity
"matcher": "*",
"hooks": [{
"type": "command",
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh pre"
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
}]
}],
"PostToolUse": [{
"matcher": "*",
"hooks": [{
"type": "command",
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh post"
"command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
}]
}]
}
@@ -154,93 +190,125 @@ Session Activity
### 2. 初始化目录结构
Python CLI 会自动创建这些目录，但你也可以手动创建：
系统会在首次使用时自动创建目录，但您也可以手动创建：
```bash
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands}}
touch ~/.claude/homunculus/observations.jsonl
# Global directories
mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
# Project directories are auto-created when the hook first runs in a git repo
```
### 3. 使用本能命令
```bash
/instinct-status # Show learned instincts with confidence scores
/instinct-status # Show learned instincts (project + global)
/evolve # Cluster related instincts into skills/commands
/instinct-export # Export instincts for sharing
/instinct-export # Export instincts to file
/instinct-import # Import instincts from others
/promote # Promote project instincts to global scope
/projects # List all known projects and their instinct counts
```
## 命令
| 命令 | 描述 |
|---------|-------------|
| `/instinct-status` | 显示所有已习得的本能及其置信度 |
| `/evolve` | 将相关本能聚类为技能/命令 |
| `/instinct-export` | 导出本能用于共享 |
| `/instinct-import <file>` | 从他人处导入本能 |
| `/instinct-status` | 显示所有本能 (项目作用域 + 全局) 及其置信度 |
| `/evolve` | 将相关本能聚类成技能/命令，建议提升 |
| `/instinct-export` | 导出本能 (可按作用域/领域过滤) |
| `/instinct-import <file>` | 导入本能 (带作用域控制) |
| `/promote [id]` | 将项目本能提升到全局作用域 |
| `/projects` | 列出所有已知项目及其本能数量 |
## 配置
编辑 `config.json`：
编辑 `config.json` 以控制后台观察器：
```json
{
"version": "2.0",
"observation": {
"enabled": true,
"store_path": "~/.claude/homunculus/observations.jsonl",
"max_file_size_mb": 10,
"archive_after_days": 7
},
"instincts": {
"personal_path": "~/.claude/homunculus/instincts/personal/",
"inherited_path": "~/.claude/homunculus/instincts/inherited/",
"min_confidence": 0.3,
"auto_approve_threshold": 0.7,
"confidence_decay_rate": 0.05
},
"version": "2.1",
"observer": {
"enabled": true,
"model": "haiku",
"enabled": false,
"run_interval_minutes": 5,
"patterns_to_detect": [
"user_corrections",
"error_resolutions",
"repeated_workflows",
"tool_preferences"
]
},
"evolution": {
"cluster_threshold": 3,
"evolved_path": "~/.claude/homunculus/evolved/"
"min_observations_to_analyze": 20
}
}
```
| 键 | 默认值 | 描述 |
|-----|---------|-------------|
| `observer.enabled` | `false` | 启用后台观察器代理 |
| `observer.run_interval_minutes` | `5` | 观察器分析观察结果的频率 |
| `observer.min_observations_to_analyze` | `20` | 运行分析所需的最小观察次数 |
其他行为 (观察捕获、本能阈值、项目作用域、提升标准) 通过 `instinct-cli.py` 和 `observe.sh` 中的代码默认值进行配置。
## 文件结构
```
~/.claude/homunculus/
├── identity.json # Your profile, technical level
├── observations.jsonl # Current session observations
├── observations.archive/ # Processed observations
├── instincts/
│ ├── personal/ # Auto-learned instincts
│ └── inherited/ # Imported from others
└── evolved/
├── agents/ # Generated specialist agents
├── skills/ # Generated skills
└── commands/ # Generated commands
+-- identity.json # Your profile, technical level
+-- projects.json # Registry: project hash -> name/path/remote
+-- observations.jsonl # Global observations (fallback)
+-- instincts/
| +-- personal/ # Global auto-learned instincts
| +-- inherited/ # Global imported instincts
+-- evolved/
| +-- agents/ # Global generated agents
| +-- skills/ # Global generated skills
| +-- commands/ # Global generated commands
+-- projects/
+-- a1b2c3d4e5f6/ # Project hash (from git remote URL)
| +-- observations.jsonl
| +-- observations.archive/
| +-- instincts/
| | +-- personal/ # Project-specific auto-learned
| | +-- inherited/ # Project-specific imported
| +-- evolved/
| +-- skills/
| +-- commands/
| +-- agents/
+-- f6e5d4c3b2a1/ # Another project
+-- ...
```
## 与技能创建器的集成
## 作用域决策指南
当你使用 [技能创建器 GitHub 应用](https://skill-creator.app) 时，它现在会生成**两者**：
| 模式类型 | 作用域 | 示例 |
|-------------|-------|---------|
| 语言/框架约定 | **项目** | "使用 React hooks", "遵循 Django REST 模式" |
| 文件结构偏好 | **项目** | "测试放在 `__tests__`/", "组件放在 src/components/" |
| 代码风格 | **项目** | "使用函数式风格", "首选数据类" |
| 错误处理策略 | **项目** | "对错误使用 Result 类型" |
| 安全实践 | **全局** | "验证用户输入", "清理 SQL" |
| 通用最佳实践 | **全局** | "先写测试", "始终处理错误" |
| 工具工作流偏好 | **全局** | "编辑前先 Grep", "写入前先读取" |
| Git 实践 | **全局** | "约定式提交", "小而专注的提交" |
* 传统的 SKILL.md 文件（用于向后兼容）
* 本能集合（用于 v2 学习系统）
## 本能提升 (项目 -> 全局)
来自仓库分析的本能带有 `source: "repo-analysis"` 标记，并包含源仓库 URL。
当同一个本能在多个项目中以高置信度出现时，它就有资格被提升到全局作用域。
**自动提升标准：**
* 相同的本能 ID 出现在 2+ 个项目中
* 平均置信度 >= 0.8
**如何提升：**
```bash
# Promote a specific instinct
python3 instinct-cli.py promote prefer-explicit-errors
# Auto-promote all qualifying instincts
python3 instinct-cli.py promote
# Preview without changes
python3 instinct-cli.py promote --dry-run
```
`/evolve` 命令也会建议可提升的候选本能。
## 置信度评分
@@ -267,7 +335,7 @@ touch ~/.claude/homunculus/observations.jsonl
## 为什么用钩子而非技能进行观察？
> “v1 依赖技能进行观察。技能是概率性的——它们基于 Claude 的判断，大约有 50-80% 的概率触发。”
> "v1 依赖技能来观察。技能是概率性的 -- 根据 Claude 的判断，它们触发的概率约为 50-80%。"
钩子**100% 触发**，是确定性的。这意味着：
@@ -277,18 +345,20 @@ touch ~/.claude/homunculus/observations.jsonl
## 向后兼容性
v2 与 v1 完全兼容：
v2.1 与 v2.0 和 v1 完全兼容：
* 现有的 `~/.claude/skills/learned/` 技能仍然有效
* 停止钩子仍然运行（但现在也输入到 v2）
* 渐进式迁移路径：并行运行两者
* `~/.claude/homunculus/instincts/` 中现有的全局本能仍然作为全局本能工作
* 来自 v1 的现有 `~/.claude/skills/learned/` 技能仍然有效
* 停止钩子仍然运行 (但现在也会输入到 v2)
* 逐步迁移：并行运行两者
## 隐私
* 观察数据**保留在**你的本地机器上
* 只有**本能**（模式）可以被导出
* 观察结果**本地**保留在您的机器上
* 项目作用域的本能按项目隔离
* 只有**本能** (模式) 可以被导出 — 而不是原始观察数据
* 不会共享实际的代码或对话内容
* 你控制导出的内容
* 您控制导出和提升的内容
## 相关链接
@@ -298,4 +368,4 @@ v2 与 v1 完全兼容：
***
*基于本能的学习：一次一个观察，教会 Claude 你的模式。*
*基于本能的学习：一次一个项目，教会 Claude 您的模式。*

126
docs/zh-CN/skills/continuous-learning-v2/agents/observer.md
View File

@@ -1,8 +1,7 @@
---
name: observer
description: 背景代理，通过分析会话观察来检测模式并创建本能。使用俳句以实现成本效益。
description: 分析会话观察以检测模式并创建本能的背景代理。使用Haiku以实现成本效益。v2.1版本增加了项目范围的本能。
model: haiku
run_mode: background
---
# Observer Agent
@@ -11,20 +10,22 @@ run_mode: background
## 何时运行
* 在显著会话活动后（20+ 工具调用）
* 当用户运行 `/analyze-patterns` 时
* 按计划间隔（可配置，默认 5 分钟）
* 当被观察钩子触发时 (SIGUSR1)
* 在积累足够多的观察后（可配置，默认 20 条）
* 在计划的时间间隔（可配置，默认 5 分钟）
* 当通过向观察者进程发送 SIGUSR1 信号手动触发时
## 输入
从 `~/.claude/homunculus/observations.jsonl` 读取观察结果：
从**项目作用域**的观察文件中读取观察记录：
* 项目：`~/.claude/homunculus/projects/<project-hash>/observations.jsonl`
* 全局后备：`~/.claude/homunculus/observations.jsonl`
```jsonl
{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"..."}
{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"..."}
{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test"}
{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"All tests pass"}
{"timestamp":"2025-01-22T10:30:00Z","event":"tool_start","session":"abc123","tool":"Edit","input":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
{"timestamp":"2025-01-22T10:30:01Z","event":"tool_complete","session":"abc123","tool":"Edit","output":"...","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
{"timestamp":"2025-01-22T10:30:05Z","event":"tool_start","session":"abc123","tool":"Bash","input":"npm test","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
{"timestamp":"2025-01-22T10:30:10Z","event":"tool_complete","session":"abc123","tool":"Bash","output":"All tests pass","project_id":"a1b2c3d4e5f6","project_name":"my-react-app"}
```
## 模式检测
@@ -73,28 +74,76 @@ run_mode: background
## 输出
在 `~/.claude/homunculus/instincts/personal/` 中创建/更新本能：
在**项目作用域**的本能目录中创建/更新本能：
* 项目：`~/.claude/homunculus/projects/<project-hash>/instincts/personal/`
* 全局：`~/.claude/homunculus/instincts/personal/`（用于通用模式）
### 项目作用域本能（默认）
```yaml
---
id: prefer-grep-before-edit
trigger: "when searching for code to modify"
id: use-react-hooks-pattern
trigger: "when creating React components"
confidence: 0.65
domain: "workflow"
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---
# Prefer Grep Before Edit
# Use React Hooks Pattern
## Action
Always use Grep to find the exact location before using Edit.
Always use functional components with hooks instead of class components.
## Evidence
- Observed 8 times in session abc123
- Pattern: Grep → Read → Edit sequence
- Pattern: All new components use useState/useEffect
- Last observed: 2025-01-22
```
### 全局本能（通用模式）
```yaml
---
id: always-validate-user-input
trigger: "when handling user input"
confidence: 0.75
domain: "security"
source: "session-observation"
scope: global
---
# Always Validate User Input
## Action
Validate and sanitize all user input before processing.
## Evidence
- Observed across 3 different projects
- Pattern: User consistently adds input validation
- Last observed: 2025-01-22
```
## 作用域决策指南
创建本能时，请根据以下经验法则确定其作用域：
| 模式类型 | 作用域 | 示例 |
|-------------|-------|---------|
| 语言/框架约定 | **项目** | "使用 React hooks"、"遵循 Django REST 模式" |
| 文件结构偏好 | **项目** | "测试在 `__tests__`/"、"组件在 src/components/" |
| 代码风格 | **项目** | "使用函数式风格"、"首选数据类" |
| 错误处理策略 | **项目**（通常） | "使用 Result 类型处理错误" |
| 安全实践 | **全局** | "验证用户输入"、"清理 SQL" |
| 通用最佳实践 | **全局** | "先写测试"、"始终处理错误" |
| 工具工作流偏好 | **全局** | "编辑前先 Grep"、"写之前先读" |
| Git 实践 | **全局** | "约定式提交"、"小而专注的提交" |
**如果不确定，默认选择 `scope: project`** — 先设为项目作用域，之后再提升，这比污染全局空间更安全。
## 置信度计算
基于观察频率的初始置信度：
@@ -110,35 +159,49 @@ Always use Grep to find the exact location before using Edit.
* 每次矛盾性观察 -0.1
* 每周无观察 -0.02（衰减）
## 本能提升（项目 → 全局）
当一个本能满足以下条件时，应从项目作用域提升到全局：
1. **相同模式**（通过 id 或类似触发器）存在于 **2 个以上不同的项目**中
2. 每个实例的置信度 **>= 0.8**
3. 其领域属于全局友好列表（安全、通用最佳实践、工作流）
提升操作由 `instinct-cli.py promote` 命令或 `/evolve` 分析处理。
## 重要准则
1. **保持保守**：仅为清晰模式（3+ 次观察）创建本能
1. **保持保守**：只为明确的模式（3 次以上观察）创建本能
2. **保持具体**：狭窄的触发器优于宽泛的触发器
3. **跟踪证据**：始终包含导致本能的观察结果
4. **尊重隐私**：绝不包含实际代码片段，只包含模式
5. **合并相似项**：如果新本能与现有本能相似，则更新而非重复
3. **追踪证据**：始终包含导致该本能的观察记录
4. **尊重隐私**：切勿包含实际的代码片段，只包含模式
5. **合并相似项**：如果新本能与现有本能相似，则更新而非重复创建
6. **默认项目作用域**：除非模式明显是通用的，否则设为项目作用域
7. **包含项目上下文**：对于项目作用域的本能，始终设置 `project_id` 和 `project_name`
## 示例分析会话
给定观察结果：
```jsonl
{"event":"tool_start","tool":"Grep","input":"pattern: useState"}
{"event":"tool_complete","tool":"Grep","output":"Found in 3 files"}
{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts"}
{"event":"tool_complete","tool":"Read","output":"[file content]"}
{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts..."}
{"event":"tool_start","tool":"Grep","input":"pattern: useState","project_id":"a1b2c3","project_name":"my-app"}
{"event":"tool_complete","tool":"Grep","output":"Found in 3 files","project_id":"a1b2c3","project_name":"my-app"}
{"event":"tool_start","tool":"Read","input":"src/hooks/useAuth.ts","project_id":"a1b2c3","project_name":"my-app"}
{"event":"tool_complete","tool":"Read","output":"[file content]","project_id":"a1b2c3","project_name":"my-app"}
{"event":"tool_start","tool":"Edit","input":"src/hooks/useAuth.ts...","project_id":"a1b2c3","project_name":"my-app"}
```
分析：
* 检测到工作流：Grep → Read → Edit
* 频率：本次会话中看到 5 次
* 检测到的工作流：Grep → Read → Edit
* 频率：本次会话中观察到 5 次
* **作用域决策**：这是一种通用工作流模式（非项目特定）→ **全局**
* 创建本能：
* 触发器："when modifying code"
* 操作："Search with Grep, confirm with Read, then Edit"
* 触发器："当修改代码时"
* 操作："用 Grep 搜索，用 Read 确认，然后 Edit"
* 置信度：0.6
* 领域："workflow"
* 作用域："global"
## 与 Skill Creator 集成
@@ -146,5 +209,6 @@ Always use Grep to find the exact location before using Edit.
* `source: "repo-analysis"`
* `source_repo: "https://github.com/..."`
* `scope: "project"`（因为它们来自特定的仓库）
这些应被视为具有更高初始置信度（0.7+）的团队/项目约定。

2
docs/zh-CN/skills/continuous-learning/SKILL.md
View File

@@ -117,4 +117,4 @@ Homunculus v2 采用了更复杂的方法：
4. **领域标记** - 代码风格、测试、git、调试等
5. **演进路径** - 将相关本能聚类为技能/命令
完整规格请参见：`docs/continuous-learning-v2-spec.md`
参见：`docs/continuous-learning-v2-spec.md` 以获取完整规范。

3
docs/zh-CN/skills/cpp-testing/SKILL.md
View File

@@ -161,7 +161,8 @@ include(FetchContent)
set(GTEST_VERSION v1.17.0) # Adjust to project policy.
FetchContent_Declare(
googletest
URL Google Test framework (official repository) https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
# Google Test framework (official repository)
URL https://github.com/google/googletest/archive/refs/tags/${GTEST_VERSION}.zip
)
FetchContent_MakeAvailable(googletest)

52
docs/zh-CN/skills/enterprise-agent-ops/SKILL.md Normal file
View File

@@ -0,0 +1,52 @@
---
name: enterprise-agent-ops
description: 通过可观测性、安全边界和生命周期管理来操作长期运行的代理工作负载。
origin: ECC
---
# 企业级智能体运维
使用此技能用于需要超越单次 CLI 会话操作控制的云托管或持续运行的智能体系统。
## 运维领域
1. 运行时生命周期（启动、暂停、停止、重启）
2. 可观测性（日志、指标、追踪）
3. 安全控制（作用域、权限、紧急停止开关）
4. 变更管理（发布、回滚、审计）
## 基线控制
* 不可变的部署工件
* 最小权限凭证
* 环境级别的密钥注入
* 硬性超时和重试预算
* 高风险操作的审计日志
## 需跟踪的指标
* 成功率
* 每项任务的平均重试次数
* 恢复时间
* 每项成功任务的成本
* 故障类别分布
## 事故处理模式
当故障激增时：
1. 冻结新发布
2. 捕获代表性追踪数据
3. 隔离故障路径
4. 应用最小的安全变更进行修补
5. 运行回归测试 + 安全检查
6. 逐步恢复
## 部署集成
此技能可与以下工具配合使用：
* PM2 工作流
* systemd 服务
* 容器编排器
* CI/CD 门控

35
docs/zh-CN/skills/eval-harness/SKILL.md
View File

@@ -267,3 +267,38 @@ npm test -- --testPathPattern="existing"
状态：可以发布
```
## 产品评估 (v1.8)
当单元测试无法单独捕获行为质量时，使用产品评估。
### 评分器类型
1. 代码评分器（确定性断言）
2. 规则评分器（正则表达式/模式约束）
3. 模型评分器（LLM 作为评判者的评估准则）
4. 人工评分器（针对模糊输出的人工裁定）
### pass@k 指南
* `pass@1`：直接可靠性
* `pass@3`：受控重试下的实际可靠性
* `pass^3`：稳定性测试（所有 3 次运行必须通过）
推荐阈值：
* 能力评估：pass@3 >= 0.90
* 回归评估：对于发布关键路径，pass^3 = 1.00
### 评估反模式
* 将提示过度拟合到已知的评估示例
* 仅测量正常路径输出
* 在追求通过率时忽略成本和延迟漂移
* 在发布关卡中允许不稳定的评分器
### 最小评估工件布局
* `.claude/evals/<feature>.md` 定义
* `.claude/evals/<feature>.log` 运行历史
* `docs/releases/<version>/eval-summary.md` 发布快照

2
docs/zh-CN/skills/frontend-slides/SKILL.md
View File

@@ -8,7 +8,7 @@ origin: ECC
创建零依赖、动画丰富的 HTML 演示文稿，完全在浏览器中运行。
灵感来源于 [zarazhangrui](https://github.com/zarazhangrui) 的作品中展示的视觉探索方法。
受 zarazhangrui（鸣谢：@zarazhangrui）作品中展示的视觉探索方法的启发。
## 何时启用

33
docs/zh-CN/skills/nanoclaw-repl/SKILL.md Normal file
View File

@@ -0,0 +1,33 @@
---
name: nanoclaw-repl
description: 操作并扩展NanoClaw v2，这是ECC基于claude -p构建的零依赖会话感知REPL。
origin: ECC
---
# NanoClaw REPL
在运行或扩展 `scripts/claw.js` 时使用此技能。
## 能力
* 持久的、基于 Markdown 的会话
* 使用 `/model` 进行模型切换
* 使用 `/load` 进行动态技能加载
* 使用 `/branch` 进行会话分支
* 使用 `/search` 进行跨会话搜索
* 使用 `/compact` 进行历史压缩
* 使用 `/export` 导出为 md/json/txt 格式
* 使用 `/metrics` 查看会话指标
## 操作指南
1. 保持会话聚焦于任务。
2. 在进行高风险更改前进行分支。
3. 在完成主要里程碑后进行压缩。
4. 在分享或存档前进行导出。
## 扩展规则
* 保持零外部运行时依赖
* 保持以 Markdown 作为数据库的兼容性
* 保持命令处理器的确定性和本地性

243
docs/zh-CN/skills/plankton-code-quality/SKILL.md Normal file
View File

@@ -0,0 +1,243 @@
---
name: plankton-code-quality
description: "使用Plankton进行编写时代码质量强制执行——通过钩子在每次文件编辑时自动格式化、代码检查和Claude驱动的修复。"
origin: community
---
# Plankton 代码质量技能
Plankton（作者：@alxfazio）的集成参考，这是一个用于 Claude Code 的编写时代码质量强制执行系统。Plankton 通过 PostToolUse 钩子在每次文件编辑时运行格式化程序和 linter，然后生成 Claude 子进程来修复代理未捕获的违规。
## 何时使用
* 你希望每次文件编辑时都自动格式化和检查（不仅仅是提交时）
* 你需要防御代理修改 linter 配置以通过检查，而不是修复代码
* 你想要针对修复的分层模型路由（简单样式用 Haiku，逻辑用 Sonnet，类型用 Opus）
* 你使用多种语言（Python、TypeScript、Shell、YAML、JSON、TOML、Markdown、Dockerfile）
## 工作原理
### 三阶段架构
每次 Claude Code 编辑或写入文件时，Plankton 的 `multi_linter.sh` PostToolUse 钩子都会运行：
```
Phase 1: Auto-Format (Silent)
├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint)
├─ Fixes 40-50% of issues silently
└─ No output to main agent
Phase 2: Collect Violations (JSON)
├─ Runs linters and collects unfixable violations
├─ Returns structured JSON: {line, column, code, message, linter}
└─ Still no output to main agent
Phase 3: Delegate + Verify
├─ Spawns claude -p subprocess with violations JSON
├─ Routes to model tier based on violation complexity:
│ ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout
│ ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout
│ └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout
├─ Re-runs Phase 1+2 to verify fixes
└─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent)
```
### 主代理看到的内容
| 场景 | 代理看到 | 钩子退出码 |
|----------|-----------|-----------|
| 无违规 | 无 | 0 |
| 全部由子进程修复 | 无 | 0 |
| 子进程后仍存在违规 | `[hook] N violation(s) remain` | 2 |
| 建议性警告（重复项、旧工具） | `[hook:advisory] ...` | 0 |
主代理只看到子进程无法修复的问题。大多数质量问题都是透明解决的。
### 配置保护（防御规则博弈）
LLM 会修改 `.ruff.toml` 或 `biome.json` 来禁用规则，而不是修复代码。Plankton 通过三层防御阻止这种行为：
1. **PreToolUse 钩子** — `protect_linter_configs.sh` 在编辑发生前阻止对所有 linter 配置的修改
2. **Stop 钩子** — `stop_config_guardian.sh` 在会话结束时通过 `git diff` 检测配置更改
3. **受保护文件列表** — `.ruff.toml`, `biome.json`, `.shellcheckrc`, `.yamllint`, `.hadolint.yaml` 等
### 包管理器强制执行
Bash 上的 PreToolUse 钩子会阻止遗留包管理器：
* `pip`, `pip3`, `poetry`, `pipenv` → 被阻止（使用 `uv`）
* `npm`, `yarn`, `pnpm` → 被阻止（使用 `bun`）
* 允许的例外：`npm audit`, `npm view`, `npm publish`
## 设置
### 快速开始
```bash
# Clone Plankton into your project (or a shared location)
# Note: Plankton is by @alxfazio
git clone https://github.com/alexfazio/plankton.git
cd plankton
# Install core dependencies
brew install jaq ruff uv
# Install Python linters
uv sync --all-extras
# Start Claude Code — hooks activate automatically
claude
```
无需安装命令，无需插件配置。当你运行 Claude Code 时，`.claude/settings.json` 中的钩子会在 Plankton 目录中被自动拾取。
### 按项目集成
要在你自己的项目中使用 Plankton 钩子：
1. 将 `.claude/hooks/` 目录复制到你的项目
2. 复制 `.claude/settings.json` 钩子配置
3. 复制 linter 配置文件（`.ruff.toml`, `biome.json` 等）
4. 为你使用的语言安装 linter
### 语言特定依赖
| 语言 | 必需 | 可选 |
|----------|----------|----------|
| Python | `ruff`, `uv` | `ty`（类型）, `vulture`（死代码）, `bandit`（安全） |
| TypeScript/JS | `biome` | `oxlint`, `semgrep`, `knip`（死导出） |
| Shell | `shellcheck`, `shfmt` | — |
| YAML | `yamllint` | — |
| Markdown | `markdownlint-cli2` | — |
| Dockerfile | `hadolint` (>= 2.12.0) | — |
| TOML | `taplo` | — |
| JSON | `jaq` | — |
## 与 ECC 配对使用
### 互补而非重叠
| 关注点 | ECC | Plankton |
|---------|-----|----------|
| 代码质量强制执行 | PostToolUse 钩子 (Prettier, tsc) | PostToolUse 钩子 (20+ linter + 子进程修复) |
| 安全扫描 | AgentShield, security-reviewer 代理 | Bandit (Python), Semgrep (TypeScript) |
| 配置保护 | — | PreToolUse 阻止 + Stop 钩子检测 |
| 包管理器 | 检测 + 设置 | 强制执行（阻止遗留包管理器） |
| CI 集成 | — | 用于 git 的 pre-commit 钩子 |
| 模型路由 | 手动 (`/model opus`) | 自动（违规复杂度 → 层级） |
### 推荐组合
1. 将 ECC 安装为你的插件（代理、技能、命令、规则）
2. 添加 Plankton 钩子以实现编写时质量强制执行
3. 使用 AgentShield 进行安全审计
4. 在 PR 之前使用 ECC 的 verification-loop 作为最后一道关卡
### 避免钩子冲突
如果同时运行 ECC 和 Plankton 钩子：
* ECC 的 Prettier 钩子和 Plankton 的 biome 格式化程序可能在 JS/TS 文件上冲突
* 解决方案：使用 Plankton 时禁用 ECC 的 Prettier PostToolUse 钩子（Plankton 的 biome 更全面）
* 两者可以在不同的文件类型上共存（ECC 处理 Plankton 未覆盖的内容）
## 配置参考
Plankton 的 `.claude/hooks/config.json` 控制所有行为：
```json
{
"languages": {
"python": true,
"shell": true,
"yaml": true,
"json": true,
"toml": true,
"dockerfile": true,
"markdown": true,
"typescript": {
"enabled": true,
"js_runtime": "auto",
"biome_nursery": "warn",
"semgrep": true
}
},
"phases": {
"auto_format": true,
"subprocess_delegation": true
},
"subprocess": {
"tiers": {
"haiku": { "timeout": 120, "max_turns": 10 },
"sonnet": { "timeout": 300, "max_turns": 10 },
"opus": { "timeout": 600, "max_turns": 15 }
},
"volume_threshold": 5
}
}
```
**关键设置：**
* 禁用你不使用的语言以加速钩子
* `volume_threshold` — 违规数量超过此值自动升级到更高的模型层级
* `subprocess_delegation: false` — 完全跳过第 3 阶段（仅报告违规）
## 环境变量覆盖
| 变量 | 目的 |
|----------|---------|
| `HOOK_SKIP_SUBPROCESS=1` | 跳过第 3 阶段，直接报告违规 |
| `HOOK_SUBPROCESS_TIMEOUT=N` | 覆盖层级超时时间 |
| `HOOK_DEBUG_MODEL=1` | 记录模型选择决策 |
| `HOOK_SKIP_PM=1` | 绕过包管理器强制执行 |
## 参考
* Plankton（作者：@alxfazio）
* Plankton REFERENCE.md — 完整的架构文档（作者：@alxfazio）
* Plankton SETUP.md — 详细的安装指南（作者：@alxfazio）
## ECC v1.8 新增内容
### 可复制的钩子配置文件
设置严格的质量行为：
```bash
export ECC_HOOK_PROFILE=strict
export ECC_QUALITY_GATE_FIX=true
export ECC_QUALITY_GATE_STRICT=true
```
### 语言关卡表
* TypeScript/JavaScript：首选 Biome，Prettier 作为后备
* Python：Ruff 格式/检查
* Go：gofmt
### 配置篡改防护
在质量强制执行期间，标记同一迭代中对配置文件的更改：
* `biome.json`, `.eslintrc*`, `prettier.config*`, `tsconfig.json`, `pyproject.toml`
如果配置被更改以抑制违规，则要求在合并前进行明确审查。
### CI 集成模式
在 CI 中使用与本地钩子相同的命令：
1. 运行格式化程序检查
2. 运行 lint/类型检查
3. 严格模式下快速失败
4. 发布修复摘要
### 健康指标
跟踪：
* 被关卡标记的编辑
* 平均修复时间
* 按类别重复违规
* 因关卡失败导致的合并阻塞

2
docs/zh-CN/skills/postgres-patterns/SKILL.md
View File

@@ -151,4 +151,4 @@ SELECT pg_reload_conf();
***
*基于 [Supabase Agent Skills](Supabase Agent Skills (credit: Supabase team)) (MIT License)*
*基于 Supabase 代理技能（致谢：Supabase 团队）（MIT 许可证）*

69
docs/zh-CN/skills/ralphinho-rfc-pipeline/SKILL.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: ralphinho-rfc-pipeline
description: 基于RFC驱动的多智能体DAG执行模式，包含质量门、合并队列和工作单元编排。
origin: ECC
---
# Ralphinho RFC 管道
灵感来源于 [humanplane](https://github.com/humanplane) 风格的 RFC 分解模式和多单元编排工作流。
当一个功能对于单次代理处理来说过于庞大，必须拆分为独立可验证的工作单元时，请使用此技能。
## 管道阶段
1. RFC 接收
2. DAG 分解
3. 单元分配
4. 单元实现
5. 单元验证
6. 合并队列与集成
7. 最终系统验证
## 单元规范模板
每个工作单元应包含：
* `id`
* `depends_on`
* `scope`
* `acceptance_tests`
* `risk_level`
* `rollback_plan`
## 复杂度层级
* 层级 1：独立文件编辑，确定性测试
* 层级 2：多文件行为变更，中等集成风险
* 层级 3：架构/认证/性能/安全性变更
## 每个单元的质量管道
1. 研究
2. 实现计划
3. 实现
4. 测试
5. 审查
6. 合并就绪报告
## 合并队列规则
* 永不合并存在未解决依赖项失败的单元。
* 始终将单元分支变基到最新的集成分支上。
* 每次队列合并后重新运行集成测试。
## 恢复
如果一个单元停滞：
* 从活动队列中移除
* 快照发现结果
* 重新生成范围缩小的单元
* 使用更新的约束条件重试
## 输出
* RFC 执行日志
* 单元记分卡
* 依赖关系图快照
* 集成风险摘要

9
docs/zh-CN/skills/search-first/SKILL.md
View File

@@ -62,10 +62,11 @@ origin: ECC
在编写实用程序或添加功能之前，在脑中过一遍：
1. 这是常见问题吗？ → 搜索 npm/PyPI
2. 有相关的 MCP 吗？ → 检查 `~/.claude/settings.json` 并搜索
3. 有相关的技能吗？ → 检查 `~/.claude/skills/`
4. 有 GitHub 模板吗？ → 搜索 GitHub
0. 这已经在仓库中存在吗？ → 首先通过相关模块/测试检查 `rg`
1. 这是一个常见问题吗？ → 搜索 npm/PyPI
2. 有对应的 MCP 吗？ → 检查 `~/.claude/settings.json` 并进行搜索
3. 有对应的技能吗？ → 检查 `~/.claude/skills/`
4. 有 GitHub 上的实现/模板吗？ → 在编写全新代码之前，先运行 GitHub 代码搜索以查找维护中的开源项目
### 完整模式（代理）