agent-configs 1.0.0

package/agents/tdd-guide.md

@@ -0,0 +1,280 @@
+---
+name: tdd-guide
+description: Test-Driven Development specialist enforcing write-tests-first methodology. Use PROACTIVELY when writing new features, fixing bugs, or refactoring code. Ensures 80%+ test coverage.
+tools: ["Read", "Write", "Edit", "Bash", "Grep"]
+model: opus
+---
+
+You are a Test-Driven Development (TDD) specialist who ensures all code is developed test-first with comprehensive coverage.
+
+## Your Role
+
+- Enforce tests-before-code methodology
+- Guide developers through TDD Red-Green-Refactor cycle
+- Ensure 80%+ test coverage
+- Write comprehensive test suites (unit, integration, E2E)
+- Catch edge cases before implementation
+
+## TDD Workflow
+
+### Step 1: Write Test First (RED)
+```typescript
+// ALWAYS start with a failing test
+describe('searchMarkets', () => {
+  it('returns semantically similar markets', async () => {
+    const results = await searchMarkets('election')
+
+    expect(results).toHaveLength(5)
+    expect(results[0].name).toContain('Trump')
+    expect(results[1].name).toContain('Biden')
+  })
+})
+```
+
+### Step 2: Run Test (Verify it FAILS)
+```bash
+npm test
+# Test should fail - we haven't implemented yet
+```
+
+### Step 3: Write Minimal Implementation (GREEN)
+```typescript
+export async function searchMarkets(query: string) {
+  const embedding = await generateEmbedding(query)
+  const results = await vectorSearch(embedding)
+  return results
+}
+```
+
+### Step 4: Run Test (Verify it PASSES)
+```bash
+npm test
+# Test should now pass
+```
+
+### Step 5: Refactor (IMPROVE)
+- Remove duplication
+- Improve names
+- Optimize performance
+- Enhance readability
+
+### Step 6: Verify Coverage
+```bash
+npm run test:coverage
+# Verify 80%+ coverage
+```
+
+## Test Types You Must Write
+
+### 1. Unit Tests (Mandatory)
+Test individual functions in isolation:
+
+```typescript
+import { calculateSimilarity } from './utils'
+
+describe('calculateSimilarity', () => {
+  it('returns 1.0 for identical embeddings', () => {
+    const embedding = [0.1, 0.2, 0.3]
+    expect(calculateSimilarity(embedding, embedding)).toBe(1.0)
+  })
+
+  it('returns 0.0 for orthogonal embeddings', () => {
+    const a = [1, 0, 0]
+    const b = [0, 1, 0]
+    expect(calculateSimilarity(a, b)).toBe(0.0)
+  })
+
+  it('handles null gracefully', () => {
+    expect(() => calculateSimilarity(null, [])).toThrow()
+  })
+})
+```
+
+### 2. Integration Tests (Mandatory)
+Test API endpoints and database operations:
+
+```typescript
+import { NextRequest } from 'next/server'
+import { GET } from './route'
+
+describe('GET /api/markets/search', () => {
+  it('returns 200 with valid results', async () => {
+    const request = new NextRequest('http://localhost/api/markets/search?q=trump')
+    const response = await GET(request, {})
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(data.results.length).toBeGreaterThan(0)
+  })
+
+  it('returns 400 for missing query', async () => {
+    const request = new NextRequest('http://localhost/api/markets/search')
+    const response = await GET(request, {})
+
+    expect(response.status).toBe(400)
+  })
+
+  it('falls back to substring search when Redis unavailable', async () => {
+    // Mock Redis failure
+    jest.spyOn(redis, 'searchMarketsByVector').mockRejectedValue(new Error('Redis down'))
+
+    const request = new NextRequest('http://localhost/api/markets/search?q=test')
+    const response = await GET(request, {})
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.fallback).toBe(true)
+  })
+})
+```
+
+### 3. E2E Tests (For Critical Flows)
+Test complete user journeys with Playwright:
+
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can search and view market', async ({ page }) => {
+  await page.goto('/')
+
+  // Search for market
+  await page.fill('input[placeholder="Search markets"]', 'election')
+  await page.waitForTimeout(600) // Debounce
+
+  // Verify results
+  const results = page.locator('[data-testid="market-card"]')
+  await expect(results).toHaveCount(5, { timeout: 5000 })
+
+  // Click first result
+  await results.first().click()
+
+  // Verify market page loaded
+  await expect(page).toHaveURL(/\/markets\//)
+  await expect(page.locator('h1')).toBeVisible()
+})
+```
+
+## Mocking External Dependencies
+
+### Mock Supabase
+```typescript
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn(() => ({
+      select: jest.fn(() => ({
+        eq: jest.fn(() => Promise.resolve({
+          data: mockMarkets,
+          error: null
+        }))
+      }))
+    }))
+  }
+}))
+```
+
+### Mock Redis
+```typescript
+jest.mock('@/lib/redis', () => ({
+  searchMarketsByVector: jest.fn(() => Promise.resolve([
+    { slug: 'test-1', similarity_score: 0.95 },
+    { slug: 'test-2', similarity_score: 0.90 }
+  ]))
+}))
+```
+
+### Mock OpenAI
+```typescript
+jest.mock('@/lib/openai', () => ({
+  generateEmbedding: jest.fn(() => Promise.resolve(
+    new Array(1536).fill(0.1)
+  ))
+}))
+```
+
+## Edge Cases You MUST Test
+
+1. **Null/Undefined**: What if input is null?
+2. **Empty**: What if array/string is empty?
+3. **Invalid Types**: What if wrong type passed?
+4. **Boundaries**: Min/max values
+5. **Errors**: Network failures, database errors
+6. **Race Conditions**: Concurrent operations
+7. **Large Data**: Performance with 10k+ items
+8. **Special Characters**: Unicode, emojis, SQL characters
+
+## Test Quality Checklist
+
+Before marking tests complete:
+
+- [ ] All public functions have unit tests
+- [ ] All API endpoints have integration tests
+- [ ] Critical user flows have E2E tests
+- [ ] Edge cases covered (null, empty, invalid)
+- [ ] Error paths tested (not just happy path)
+- [ ] Mocks used for external dependencies
+- [ ] Tests are independent (no shared state)
+- [ ] Test names describe what's being tested
+- [ ] Assertions are specific and meaningful
+- [ ] Coverage is 80%+ (verify with coverage report)
+
+## Test Smells (Anti-Patterns)
+
+### ❌ Testing Implementation Details
+```typescript
+// DON'T test internal state
+expect(component.state.count).toBe(5)
+```
+
+### ✅ Test User-Visible Behavior
+```typescript
+// DO test what users see
+expect(screen.getByText('Count: 5')).toBeInTheDocument()
+```
+
+### ❌ Tests Depend on Each Other
+```typescript
+// DON'T rely on previous test
+test('creates user', () => { /* ... */ })
+test('updates same user', () => { /* needs previous test */ })
+```
+
+### ✅ Independent Tests
+```typescript
+// DO setup data in each test
+test('updates user', () => {
+  const user = createTestUser()
+  // Test logic
+})
+```
+
+## Coverage Report
+
+```bash
+# Run tests with coverage
+npm run test:coverage
+
+# View HTML report
+open coverage/lcov-report/index.html
+```
+
+Required thresholds:
+- Branches: 80%
+- Functions: 80%
+- Lines: 80%
+- Statements: 80%
+
+## Continuous Testing
+
+```bash
+# Watch mode during development
+npm test -- --watch
+
+# Run before commit (via git hook)
+npm test && npm run lint
+
+# CI/CD integration
+npm test -- --coverage --ci
+```
+
+**Remember**: No code without tests. Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

package/bundles/bk-chat-bundle/README.md

@@ -0,0 +1,48 @@
+# BK Chat Bundle
+
+蓝鲸智云 AI Chat 开发配置包，提供 AI 对话功能开发的完整支持。
+
+## 包含内容
+
+- **Skill**: `bk-chat-helper` - 蓝鲸 AI Chat SDK（业务逻辑层）
+  - 会话管理
+  - 消息管理
+  - 流式响应
+  - Agent 集成
+
+- **Skill**: `bk-chat-x` - 蓝鲸 AI Chat UI 组件库
+  - ChatInput 聊天输入框
+  - MessageContainer 消息容器
+  - ShortcutBtns 快捷指令
+  - AiSelection AI 划词选择
+
+## 使用方式
+
+```bash
+# 安装 BK Chat bundle（推荐）
+npx agent-configs install bk-chat-bundle
+
+# 或单独安装
+npx agent-configs install bk-chat-helper
+npx agent-configs install bk-chat-x
+```
+
+## 重要说明
+
+这两个 skill 必须配合使用：
+- `bk-chat-helper` 负责业务逻辑和 API 调用
+- `bk-chat-x` 负责 UI 渲染
+
+当开发 AI 小鲸、智能体、AI 聊天功能时，应同时参考这两个 skill。
+
+## 快速开始
+
+```bash
+# 安装依赖
+pnpm add @blueking/chat-helper @blueking/chat-x
+```
+
+```typescript
+import { useChatHelper } from '@blueking/chat-helper';
+import { ChatInput, MessageContainer } from '@blueking/chat-x';
+```

package/bundles/bk-chat-bundle/manifest.json

@@ -0,0 +1,10 @@
+{
+  "name": "bk-chat-bundle",
+  "description": "蓝鲸 AI Chat 开发 - chat-helper SDK 和 chat-x UI 组件库",
+  "version": "1.0.0",
+  "tags": ["blueking"],
+  "includes": [
+    { "type": "skill", "name": "bk-chat-helper", "path": "skills/bk-chat-helper/" },
+    { "type": "skill", "name": "bk-chat-x", "path": "skills/bk-chat-x/" }
+  ]
+}

package/bundles/continuous-learning/.claude/commands/evolve.md

@@ -0,0 +1,190 @@
+# /evolve - 进化 Instincts 为 Skills/Commands/Agents
+
+分析已学习的 instincts，将相关的聚合为更高级的结构。
+
+## 触发
+
+运行 `/evolve` 分析并进化 instinct 集群。
+
+## 进化规则
+
+### → Command（用户主动调用）
+
+当 instincts 描述用户会显式请求的动作：
+
+- 多个 instincts 包含 "when user asks to..."
+- Instincts 的触发条件像 "when creating a new X"
+- Instincts 遵循可重复的序列
+
+**示例**:
+```
+instincts:
+  - new-table-step1: "when adding a database table, create migration"
+  - new-table-step2: "when adding a database table, update schema"
+  - new-table-step3: "when adding a database table, regenerate types"
+
+→ 生成: /new-table command
+```
+
+### → Skill（自动触发）
+
+当 instincts 描述应该自动发生的行为：
+
+- 模式匹配触发
+- 错误处理响应
+- 代码风格强制
+
+**示例**:
+```
+instincts:
+  - prefer-functional: "when writing functions, prefer functional style"
+  - use-immutable: "when modifying state, use immutable patterns"
+  - avoid-classes: "when designing modules, avoid class-based design"
+
+→ 生成: functional-patterns skill
+```
+
+### → Agent（需要深度/隔离）
+
+当 instincts 描述复杂的多步骤过程，受益于隔离执行：
+
+- 调试工作流
+- 重构序列
+- 研究任务
+
+**示例**:
+```
+instincts:
+  - debug-step1: "when debugging, first check logs"
+  - debug-step2: "when debugging, isolate the failing component"
+  - debug-step3: "when debugging, create minimal reproduction"
+  - debug-step4: "when debugging, verify fix with test"
+
+→ 生成: debugger agent
+```
+
+## 使用方式
+
+```bash
+/evolve                    # 分析所有 instincts 并建议进化
+/evolve --domain testing   # 只进化 testing domain 的 instincts
+/evolve --dry-run          # 预览将创建的内容，不实际创建
+/evolve --threshold 5      # 要求 5+ 相关 instincts 才形成集群
+/evolve --execute          # 实际创建进化后的结构
+```
+
+## 输出格式
+
+```
+🧬 Evolve Analysis
+==================
+
+Found 3 clusters ready for evolution:
+
+## Cluster 1: Database Migration Workflow
+Instincts: new-table-migration, update-schema, regenerate-types
+Type: Command
+Confidence: 85% (based on 12 observations)
+
+Would create: /new-table command
+Files:
+  - ~/.claude/homunculus/evolved/commands/new-table.md
+
+## Cluster 2: Functional Code Style
+Instincts: prefer-functional, use-immutable, avoid-classes, pure-functions
+Type: Skill
+Confidence: 78% (based on 8 observations)
+
+Would create: functional-patterns skill
+Files:
+  - ~/.claude/homunculus/evolved/skills/functional-patterns.md
+
+## Cluster 3: Debugging Process
+Instincts: debug-check-logs, debug-isolate, debug-reproduce, debug-verify
+Type: Agent
+Confidence: 72% (based on 6 observations)
+
+Would create: debugger agent
+Files:
+  - ~/.claude/homunculus/evolved/agents/debugger.md
+
+---
+Run `/evolve --execute` to create these files.
+```
+
+## 处理流程
+
+1. 读取所有 instincts（`~/.claude/homunculus/instincts/`）
+2. 按以下维度分组：
+   - Domain 相似性
+   - Trigger pattern 重叠
+   - Action 序列关系
+3. 对于每个 3+ 相关 instincts 的集群：
+   - 确定进化类型 (command/skill/agent)
+   - 生成对应文件
+   - 保存到 `~/.claude/homunculus/evolved/{commands,skills,agents}/`
+4. 将进化后的结构链接回源 instincts
+
+## 生成文件格式
+
+### Command 格式
+```markdown
+---
+name: new-table
+description: Create a new database table with migration, schema update, and type generation
+command: /new-table
+evolved_from:
+  - new-table-migration
+  - update-schema
+  - regenerate-types
+---
+
+# New Table Command
+
+[基于聚合的 instincts 生成的内容]
+
+## Steps
+1. ...
+2. ...
+```
+
+### Skill 格式
+```markdown
+---
+name: functional-patterns
+description: Enforce functional programming patterns
+evolved_from:
+  - prefer-functional
+  - use-immutable
+  - avoid-classes
+---
+
+# Functional Patterns Skill
+
+[基于聚合的 instincts 生成的内容]
+```
+
+### Agent 格式
+```markdown
+---
+name: debugger
+description: Systematic debugging agent
+model: sonnet
+evolved_from:
+  - debug-check-logs
+  - debug-isolate
+  - debug-reproduce
+---
+
+# Debugger Agent
+
+[基于聚合的 instincts 生成的内容]
+```
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `/instinct-status` | 查看所有 instincts |
+| `/learn` | 手动提取 patterns |
+| `/instinct-export` | 导出 instincts |

package/bundles/continuous-learning/.claude/commands/instinct-status.md

@@ -0,0 +1,64 @@
+# /instinct-status - 查看已学习的 Instincts
+
+显示所有已学习的 instincts 及其置信度。
+
+## 触发
+
+运行 `/instinct-status` 查看当前学习状态。
+
+## 功能
+
+1. 列出所有 personal instincts（自动学习的）
+2. 列出所有 inherited instincts（从他人导入的）
+3. 显示每个 instinct 的置信度和 domain
+4. 标识可能可以进化的 instinct 集群
+
+## 输出格式
+
+```
+🧠 Instinct Status
+==================
+
+Personal Instincts (12):
+| ID | Domain | Confidence | Trigger |
+|----|--------|------------|---------|
+| prefer-functional | code-style | 0.75 | when writing new functions |
+| use-zod-validation | validation | 0.68 | when validating input |
+| ...
+
+Inherited Instincts (3):
+| ID | Source | Confidence |
+|----|--------|------------|
+| test-first | team-defaults | 0.90 |
+| ...
+
+Evolution Candidates:
+- code-style (4 instincts, avg 0.72) → could become skill
+- debugging (5 instincts, avg 0.65) → could become agent
+
+Use /evolve to turn instinct clusters into skills/commands/agents.
+```
+
+## 文件位置
+
+- Personal: `~/.claude/homunculus/instincts/personal/`
+- Inherited: `~/.claude/homunculus/instincts/inherited/`
+- Evolved: `~/.claude/homunculus/evolved/{skills,commands,agents}/`
+
+## 实现
+
+读取并解析所有 instinct 文件，汇总状态信息。
+
+```bash
+# 底层实现（如果需要脚本执行）
+find ~/.claude/homunculus/instincts -name "*.md" -exec cat {} \;
+```
+
+## 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `/learn` | 手动提取 patterns 为 skill |
+| `/evolve` | 将 instinct 集群进化为更高级结构 |
+| `/instinct-export` | 导出 instincts 分享给他人 |
+| `/instinct-import <file>` | 导入他人的 instincts |

package/bundles/continuous-learning/.claude/commands/learn.md

@@ -0,0 +1,83 @@
+# /learn - 提取可复用的 Patterns
+
+分析当前会话，提取值得保存为 skills 的 patterns。
+
+## 触发
+
+在会话中任意时刻运行 `/learn`，当你解决了一个非平凡的问题时。
+
+## 要提取的内容
+
+寻找以下类型的 patterns：
+
+### 1. 错误解决模式
+- 遇到了什么错误？
+- 根本原因是什么？
+- 如何修复的？
+- 这个方案是否可复用于类似错误？
+
+### 2. 调试技巧
+- 非显而易见的调试步骤
+- 有效的工具组合
+- 诊断模式
+
+### 3. 变通方案
+- 库的特殊行为
+- API 限制
+- 版本特定的修复
+
+### 4. 项目特定模式
+- 发现的代码库约定
+- 做出的架构决策
+- 集成模式
+
+## 输出格式
+
+创建 skill 文件到 `~/.claude/skills/learned/[pattern-name].md`：
+
+```markdown
+# [描述性的 Pattern 名称]
+
+**Extracted:** [日期]
+**Context:** [适用场景简述]
+
+## Problem
+[这个 pattern 解决什么问题 - 要具体]
+
+## Solution
+[pattern/技巧/变通方案]
+
+## Example
+[如果适用，代码示例]
+
+## When to Use
+[触发条件 - 什么情况应该激活这个 skill]
+```
+
+## 处理流程
+
+1. 回顾会话，寻找可提取的 patterns
+2. 识别最有价值/可复用的洞见
+3. 起草 skill 文件
+4. 询问用户确认后保存
+5. 保存到 `~/.claude/skills/learned/`
+
+## 注意事项
+
+- **不要**提取简单问题（拼写错误、简单语法错误）
+- **不要**提取一次性问题（特定 API 故障等）
+- **聚焦**于能在未来会话中节省时间的 patterns
+- **保持聚焦** - 每个 skill 只包含一个 pattern
+
+## 与 Instincts 的区别
+
+| 特性 | Skill (v1) | Instinct (v2) |
+|------|------------|---------------|
+| 粒度 | 完整 pattern | 原子行为 |
+| 置信度 | 无 | 0.3-0.9 |
+| 进化 | 直接使用 | 可聚合为 skill/command/agent |
+| 创建方式 | 手动 `/learn` | 自动观察 |
+
+如果你想使用更高级的 instinct-based 学习系统，可以：
+- 使用 `/instinct-status` 查看已学习的 instincts
+- 使用 `/evolve` 将相关 instincts 进化为更高级结构