# 5类事件审计
审计事件类型：
1. llm_input      - LLM接收到的完整提示词
2. tool_call      - 工具调用决策和参数
3. tool_result    - 工具执行结果
4. ai_message     - AI的最终回复
5. system_action  - 系统级操作（如心跳任务触发）

class JSONLEventLogger:
    def log_event(self, thread_id: str, event: str, **kwargs):
        log_item = {
            "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
            "thread_id": thread_id,
            "event": event,
            **kwargs
        }
        self.log_queue.put(log_item)  # 非阻塞入队

class DynamicSkillInput(BaseModel):
    mode: str = Field(description="必须是 'help' 或 'run'")
    command: Optional[str] = Field(default="", description="仅在 mode='run' 时需要")

def lazy_runner(mode: str, command: str = "") -> str:
    if mode == "help":
        # 第一段：查看说明书
        return f"========== 【技能完整说明书】 ==========\n{skill_content[:3000]}"
    elif mode == "run":
        # 第二段：确认后执行
        return execute_office_shell.invoke({"command": actual_cmd})

def trim_context_messages(messages, trigger_turns=8, keep_turns=4):
    """
    按对话回合裁剪上下文消息
    规则：遇到 HumanMessage → 开启新回合
    总回合数 < trigger_turns → 不裁剪
    否则保留最近 keep_turns 个回合，其余裁剪后标记为丢弃
    """

┌─────────────────────────────────────────────────────────────────┐
│  输入层 (蓝色)                                                  │
│  ├── Heartbeat心跳任务 (后台进程)                                │
│  ├── 用户键盘输入                                               │
│  └── 飞书消息通道                                               │
│           ↓                                                    │
│  记忆层 (粉色)                                                  │
│  ├── 上下文裁剪 (按回合分组)                                    │
│  ├── 长期记忆 (user_profile.md)                                 │
│  └── 短期记忆 (SQLite + 摘要)                                   │
│           ↓                                                    │
│  智能决策层 (黄色)                                              │
│  ├── Agent Loop (LangGraph StateGraph)                         │
│  ├── LLM推理决策 (支持多提供商)                                 │
│  └── 工具绑定 (bind_tools)                                     │
│           ↓                                                    │
│  工具执行层 (紫色)                                              │
│  ├── 内置工具集 (12个工具)                                      │
│  └── 可插拔Skills (动态加载)                                    │
│           ↓                                                    │
│  Harness约束层 (橙色)                                          │
│  ├── 沙盒路径拦截 (跨平台)                                     │
│  ├── Shell命令过滤 (危险命令正则匹配)                           │
│  ├── 两段式安全调用 (help → run)                               │
│  └── 心跳反馈回路                                               │
│           ↓                                                    │
│  Trace透明监控层 (绿色)                                         │
│  ├── 4层审计: llm_input, tool_call, tool_result, ai_message    │
│  ├── thread_id可追溯                                           │
│  ├── JSONL日志 (非阻塞写入)                                    │
│  └── Rich监控终端 (实时UI)                                     │
│           ↓                                                    │
│  输出层 (底部)                                                  │
│  ├── 聊天终端 (Prompt Toolkit TUI)                             │
│  ├── 监控终端 (Rich终端UI)                                     │
│  └── 飞书回复通道                                               │
└─────────────────────────────────────────────────────────────────┘

---
name: weather
description: 获取天气预报
---

# Weather Skill

## 功能
获取全球城市的实时天气预报。

## 命令示例
```bash
curl "wttr.in/Beijing?format=3"

## 五、实战场景：从企业到个人

### 场景1：企业合规审计
- **痛点**：AI Agent操作缺乏审计日志，无法满足合规要求
- **方案**：TraceClaw的5类事件审计，完整记录每一次LLM输入、工具调用、执行结果
- **价值**：满足GDPR、ISO27001等合规要求，审计日志可追溯

### 场景2：AI开发调试
- **痛点**：AI决策过程不透明，调试困难
- **方案**：Rich监控终端实时可视化，JSONL日志支持`tail -f`实时监控
- **价值**：快速定位问题，理解AI决策逻辑

### 场景3：个人效率工具
- **痛点**：AI助手"健忘"，每次对话都要重复说明偏好
- **方案**：双水位记忆系统，自动学习用户习惯
- **价值**：越用越顺手，真正的个性化助手

### 场景4：飞书团队协作
- **痛点**：AI助手无法融入团队工作流
- **方案**：深度飞书集成，双向消息通道，心跳任务推送
- **价值**：团队共享AI助手，自动化重复性工作

## 六、快速上手：5分钟部署

### 安装
```bash
# 克隆项目
git clone https://github.com/fubenshuo/TraceClaw.git
cd TraceClaw

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装项目
pip install -e .

# 启动交互式配置向导
traceclaw config

# 配置内容：
# 1. 选择LLM提供商（OpenAI/Anthropic/阿里云等）
# 2. 输入API Key
# 3. 配置飞书集成（可选）
# 4. 设置工作区路径

# 启动主程序
traceclaw run

# 启动监控终端（另一个终端）
traceclaw monitor

# 基础对话
> 现在几点了？

# 数学计算
> 帮我算一下 25 乘以 48

# 定时任务
> 每天早上 8 点提醒我喝水
> 每周一上午 10 点开团队会议

# 文件操作
> 看看 office 里有什么文件
> 读取 readme.txt

# 飞书集成
@TraceClaw 帮我看下现在几点了
@TraceClaw 每天早上9点提醒我站会

git clone https://github.com/fubenshuo/TraceClaw.git
cd TraceClaw
pip install -e .
traceclaw config
traceclaw run