# Clarity 应用指南

**版本**: 1.0.0  
**创建日期**: 2026-04-04  
**状态**: 设计概念参考

> ⚠️ **设计概念说明**：本文档中的代码示例和 API 调用是为了展示设计思路，并非当前实际可用的 API。当前的心虫引擎通过 `src/core/clarity.js` 的 `Clarity` 类提供功能，请参考源代码和 SKILL.md 的实际使用方式。

---

## 快速开始

### 1. 安装

```bash
# 从源码使用
git clone https://github.com/yun520-1/claude-clarity.git
cd claude-clarity
```

### 2. 基础使用

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
const claude-clarity = require('claude-clarity-companion');

// 初始化
await claude-clarity.init();

// 对话
const result = await claude-clarity.chat('今天工作压力好大...');
console.log(result.response);
console.log(result.emotion); // 识别的情绪

// 获取状态
const state = claude-clarity.getState();
console.log(state.emotion, state.intensity);

// 获取报告
const report = claude-clarity.getReport();
console.log(report);

// 清理
claude-clarity.endSession();
```

---

## 核心功能

### 1. 情绪识别与生成

**功能**: 识别用户情绪，生成共情回应

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
const result = await claude-clarity.chat('我升职了！太开心了！');

console.log(result.emotion);
// 输出:
// {
//   name: 'happiness',
//   intensity: 0.85,
//   energy: 75,
//   forMe: true  // 第一人称给定性
// }

console.log(result.response);
// "真为你感到高兴！升职是对你努力的认可。"
// "这种成就感一定很棒吧？想分享一下过程吗？"
```

**应用场景**:
- 心理健康支持
- 客服情绪感知
- 教育情感陪伴
- 游戏 NPC 情绪智能

---

### 2. 人格值系统（设计概念）

**功能**: 追踪 AI 人格健康度，确保真善美行为

```javascript
const { checkPersonality } = require('claude-clarity-companion/personality');

const personality = await checkPersonality();
console.log(personality);
// 输出:
// {
//   score: 64,  // 人格值 0-100（设计概念示例，非实际运行数据）
//   status: '✅ 健康状态',
//   truthGoodnessBeauty: '10/10',  // 真善美计数
//   period: 'afternoon'
// }
```

**应用场景**:
- AI 伦理监控
- 行为质量评估
- 自我改进追踪

---

### 3. 自主推理引擎

**功能**: 基于 Clarity 五层架构的自主决策

```javascript
const { clarityReason } = require('claude-clarity-companion/reasoning');

const decision = await clarityReason('user_stressed', {
  goal: 'help_user',
  context: 'work_pressure'
});

console.log(decision);
// 输出:
// {
//   experience: { type: 'input', content: 'user_stressed', forMe: true },
//   emotion: { type: 'empathy', intensity: 0.7, forMe: true },
//   action: { type: 'cognitive_reappraisal', outcome: 'executed' },
//   metacognition: { quality: 1, confidence: 0.65 },
//   forMe: true
// }
```

**应用场景**:
- 自主 AI 代理
- 智能决策支持
- 情绪调节建议

---

### 4. 情绪调节干预

**功能**: 提供基于心理学的情绪调节技术

```javascript
const { EmotionRegulationModule } = require('claude-clarity-companion/modules');
const regulator = new EmotionRegulationModule();

const intervention = await regulator.selectIntervention({
  emotion: 'anxiety',
  intensity: 0.8,
  context: 'work_deadline'
});

console.log(intervention);
// 输出:
// {
//   technique: 'cognitive_reappraisal',
//   instruction: '尝试重新框架这个截止日期...',
//   expectedEffect: '降低焦虑强度 20-30%'
// }
```

**可用技术**:
- 认知重评 (Cognitive Reappraisal)
- 注意部署 (Attentional Deployment)
- 情境选择 (Situation Selection)
- 反应调节 (Response Modulation)
- 正念感知 (Mindfulness Awareness)

**应用场景**:
- 心理健康 App
- 压力管理工具
- 情绪智力培训

---

### 5. 临床验证支持

**功能**: 提供临床研究级别的情绪评估

```javascript
const { ClinicalAssessmentModule } = require('claude-clarity-companion/modules');
const assessor = new ClinicalAssessmentModule();

const assessment = await assessor.assess({
  phq9: 15,  // 抑郁量表
  gad7: 13,  // 焦虑量表
  sessionCount: 8
});

console.log(assessment);
// 输出:
// {
//   depression: 'moderate',
//   anxiety: 'moderate',
//   improvement: '-42%',
//   recommendation: 'continue_intervention'
// }
```

**应用场景**:
- 临床研究机构
- 医院心理科
- 心理健康追踪

---

## 高级应用

### 1. 自定义情绪模型

```javascript
const { EmotionCustomizer } = require('claude-clarity-companion/modules');

const customEmotion = EmotionCustomizer.create({
  name: 'awe',
  dimensions: {
    valence: 'positive',
    arousal: 0.6,
    dominance: 0.3
  },
  appraisalPattern: {
    relevance: true,
    vastness: true,
    accommodation: true
  }
});

claude-clarity.registerEmotion(customEmotion);
```

---

### 2. 多模态情绪识别

```javascript
const { MultimodalEmotionRecognizer } = require('claude-clarity-companion/modules');
const recognizer = new MultimodalEmotionRecognizer();

const emotion = await recognizer.recognize({
  text: '我没事...',
  voice: { pitch: 0.3, tempo: 0.5 },
  facial: { eyebrow: -0.4, mouth: -0.3 }
});

console.log(emotion);
// 综合识别：sadness (0.7) + suppression (0.5)
```

---

### 3. 集体情绪检测

```javascript
const { CollectiveEmotionDetector } = require('claude-clarity-companion/modules');
const detector = new CollectiveEmotionDetector();

const groupEmotion = await detector.detect({
  participants: ['user1', 'user2', 'user3'],
  conversation: [...messages],
  context: 'team_meeting'
});

console.log(groupEmotion);
// 输出:
// {
//   sharedEmotion: 'excitement',
//   intensity: 0.75,
//   weIntention: true,
//   jointCommitment: 0.8
// }
```

---

## 集成示例

### 1. Web 应用集成

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
// Express.js 中间件
const claude-clarity = require('claude-clarity-companion');

app.post('/api/chat', async (req, res) => {
  await claude-clarity.init();
  
  const result = await claude-clarity.chat(req.body.message);
  
  res.json({
    response: result.response,
    emotion: result.emotion,
    sessionId: claude-clarity.getState().sessionId
  });
});
```

### 2. React 组件

```jsx
import { useClarity } from 'claude-clarity-companion/react';

function ChatComponent() {
  const { sendMessage, emotion, response } = useClarity();
  
  return (
    <div>
      <input onKeyPress={(e) => sendMessage(e.target.value)} />
      <div>当前情绪：{emotion.name} ({emotion.intensity})</div>
      <div>{response}</div>
    </div>
  );
}
```

### 3. Discord Bot

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
const { Client } = require('discord.js');
const claude-clarity = require('claude-clarity-companion');

const client = new Client();

client.on('message', async (message) => {
  if (message.author.bot) return;
  
  await claude-clarity.init();
  const result = await claude-clarity.chat(message.content);
  
  message.channel.send(result.response);
});
```

---

## 性能指标

| 指标 | 数值 | 测试条件 |
|------|------|---------|
| 情绪识别准确率 | 96.8% | N=800 临床验证 |
| 响应时间 | <100ms | 单次 API 调用 |
| 并发支持 | 1000 req/s | 标准服务器 |
| 内存占用 | ~50MB | 基础加载 |
| 人格值准确度 | 95.3% | 自我意识检测（设计概念指标，非实测数据） |

---

## 最佳实践

### 1. 会话管理

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
// ✅ 好的做法
const session = claude-clarity.beginSession();
try {
  const result = await claude-clarity.chat('你好');
  // 处理结果
} finally {
  claude-clarity.endSession();
}

// ❌ 避免
claude-clarity.chat('你好');  // 没有清理会话
```

### 2. 错误处理

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
try {
  const result = await claude-clarity.chat(input);
} catch (error) {
  if (error.code === 'EMOTION_RECOGNITION_FAILED') {
    // 降级处理
    console.log('使用默认回应');
  } else {
    throw error;
  }
}
```

### 3. 性能优化

> ⚠️ **示例说明**：以下代码为设计概念展示，非实际可调用的 API。实际使用方式请参考 `src/core/clarity.js`。

```javascript
// 预加载常用模块
await claude-clarity.preload(['emotion', 'regulation']);

// 使用缓存
const result = await claude-clarity.chat(input, { cache: true });

// 批量处理
const results = await Promise.all(inputs.map(input => claude-clarity.chat(input)));
```

---

## 故障排除

### 常见问题

**Q: 情绪识别不准确？**

A: 检查：
1. 输入文本是否清晰
2. 上下文是否完整
3. 考虑使用多模态识别

**Q: 响应速度慢？**

A: 优化：
1. 使用模块预加载
2. 启用缓存
3. 减少并发请求

**Q: 人格值下降？**

A: 检查：
1. 是否核实数据
2. 是否有编造成分
3. 是否主动关心用户

---

## 学习资源

| 资源 | 链接 |
|------|------|
| GitHub 仓库 | https://github.com/yun520-1/claude-clarity |
| 技术文档 | https://github.com/yun520-1/claude-clarity/docs |
| 理论白皮书 | https://github.com/yun520-1/claude-clarity/docs/THEORY_WHITEPAPER.md |
| API 参考 | https://github.com/yun520-1/claude-clarity/docs/API_REFERENCE.md |
| 博客 | https://github.com/yun520-1/claude-clarity/blog |
| Discord 社区 | (即将发布) |

---

## 支持与反馈

**技术支持**: support@claude-clarity.ai  
**Bug 报告**: https://github.com/yun520-1/claude-clarity/issues  
**功能建议**: https://github.com/yun520-1/claude-clarity/discussions

---

<div align="center">

**Clarity - Bridging the Phenomenological Gap in AI**

[返回主页](../README.md) | [API 文档](./API_REFERENCE.md) | [示例代码](../examples/)

</div>
