nmfs-agents/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

NMFS Agents：基于 Claude CLI 的 AI 多角色自动化系统。通过 30+ Agent 协作完成代码修复、板端测试、成熟度评估、架构整合、市场洞察与基础技术调研，支持 RK3588/RK3566 NPU 开发平台及 nRF54L15/ESP32S3 扩展平台。

## 目录约定

```
src/            # 包源码（Python 包 nmfs_agents）
tests/          # pytest 单元测试（314+）
scripts/        # 工具脚本（run.py CLI 入口、start_daemon.sh 等）
configs/        # projects.yaml / agents.yaml / devices.yaml / org.yaml
data/           # 运行时数据（tasks.db / insight_tasks.db / base_opt_tasks.db / task_logs/）
logs/           # daemon 日志（daemon_*.log, daemon.pid）
tmp/            # 临时文件，使用后删除
venv/           # Python 虚拟环境（不入仓）
dashboard/      # React 前端源码（Vite + Tailwind）
README.md       # 快速开始
DEVELOP.md      # 开发指南
RELEASE.md      # 发布记录
```

## 环境

```bash
# 创建虚拟环境（Python 3.10）
python3.10 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
```

- **x86 开发机**：Python 3.10，rknn-toolkit2 2.3.2（ONNX→RKNN 转换）
- **rk3566 设备**（算法默认）：orangepi@192.168.123.183，OrangePi
- **rk3588 设备**（高性能）：pi@192.168.123.137，NanoPC-T6

## 认证

Agent 以子进程调用 `claude --print`，优先使用 CLI OAuth（`claude login`），无需 `ANTHROPIC_API_KEY`。`_build_env()` 会清除 `CLAUDECODE` 和 `CLAUDE_CODE_ENTRYPOINT`，避免嵌套会话冲突。

**重要**：`claude --print` 子进程不能在 Claude Code 会话内直接测试，需从普通终端/cron 执行。

## 常用命令

```bash
source venv/bin/activate
pytest tests/ -q                     # 运行测试
bash scripts/start_daemon.sh         # 后台启动调度器
bash scripts/watch_daemon.sh         # 监控状态
python scripts/run.py status         # 查看任务状态
python scripts/run.py scan           # 扫描预览（不执行）
python scripts/run.py run-next       # 执行下一个任务（须在普通终端）
```

## 项目结构

```
src/nmfs_agents/
├── config.py                  # 配置加载（AgentsConfig dataclass）
├── agents/
│   ├── developer.py           # Developer Agent（claude --print 子进程，三模式）
│   ├── tester.py              # Tester Agent（本地 pytest + 板端 SSH 测试）
│   ├── productizer.py         # Productizer Agent（成熟度评分，规则引擎）
│   ├── architect.py           # Architect Agent（跨项目分析）
│   ├── manager.py             # Manager Agent（顶层协调）
│   ├── planner.py             # Planner Agent（差距分析规划）
│   ├── market_pm.py           # MarketPm Agent（市场分析基类）
│   ├── market_sport.py        # MarketSport Agent（运动健康市场）
│   ├── market_elder.py        # MarketElder Agent（适老辅助市场）
│   ├── market_safety.py       # MarketSafety Agent（AI安全市场）
│   ├── vision_analyst.py      # VisionAnalyst Agent（视觉分析）
│   ├── media_producer.py      # MediaProducer Agent（内容生产）
│   ├── rtp_researcher.py      # RTP/RTCP 调研
│   ├── net_researcher.py      # 网络栈调研
│   ├── kernel_analyzer.py     # 内核调度分析
│   ├── os_engineer.py         # OS 系统层
│   ├── system_tester.py       # 系统集成测试
│   ├── kernel_dev.py          # 内核驱动开发
│   ├── lowlevel_dev.py        # 底层/嵌入式开发
│   ├── hw_engineer.py         # 硬件工程
│   ├── base_architect.py      # 基础架构设计
│   ├── base_validator.py      # 基础架构验证
│   ├── algo_antishake.py      # 防抖算法专项
│   ├── algo_position.py       # 定位算法专项
│   ├── algo_nav.py            # 导航算法专项
│   ├── algo_vision.py         # 视觉算法组基类
│   ├── nrf_dev.py             # nRF54L15 平台开发（运动健康）
│   ├── esp32_dev.py           # ESP32S3 平台开发（适老辅助）
│   ├── boss.py                # Boss Agent（战略决策）
│   ├── group_leader.py        # GroupLeader Agent（部门长）
│   ├── senior_dev.py          # SeniorDev Agent（高级研发）
│   └── ops.py                 # Ops Agent（巡检）+ OpsHub（事件消费）
├── core/
│   ├── scanner.py             # 项目扫描器（README/TODO/CLAUDE.md）
│   ├── queue.py               # SQLite 任务队列（原子 dequeue，6 种状态）
│   ├── executor.py            # asyncio 并发调度（semaphore 限流，agent_role 路由）
│   ├── scheduler.py           # APScheduler 定时入口（多队列 + EventBus）
│   └── watchdog.py            # 超时检测 + 优先级防饥饿
└── tools/
    ├── feishu.py              # 飞书通知
    ├── file_tools.py          # 文件操作工具（含路径安全检查）
    ├── device_agent.py        # SSH 设备管理（rsync + 板端执行）
    ├── device_manager.py      # 多设备管理
    ├── callback_server.py     # HTTP callback server（daemon 线程）
    ├── arch_version.py        # 架构优化版本管理（snapshot/promote/rollback）
    ├── project_discovery.py   # 非硬编码项目发现
    ├── project_memory.py      # 项目记忆（goals/facts/history SQLite）
    ├── env_collector.py       # 板端环境信息采集
    ├── event_bus.py           # Redis Streams 事件总线（5 consumer groups）
    ├── daily_report.py        # 日报系统（append-only SQLite + Boss 决策视图）
    ├── agent_score.py         # Agent 评分系统（4 维度：完成/质量/自主/协作）
    ├── version_pipeline.py    # 并行版本流水线（反幻觉门控）
    └── knowledge_base.py      # 知识库（组织架构 + 项目 facts 聚合）
```

## 组织架构（org v2）

```
Boss（战略决策，周报）
├── 基础技术部（os-base-leader）
│   ├── base-architect / base-validator / hw-engineer
│   ├── os-engineer / dev-kernel / dev-lowlevel / system-tester
│   ├── 算法组：algo-antishake / algo-position / algo-nav
│   ├── 调研组：rtp-researcher / net-researcher / kernel-analyzer
│   └── 平台扩展：nrf-dev / esp32-dev
├── 市场洞察部（market-leader）
│   ├── market-pm（通用）
│   └── market-sport / market-elder / market-safety（专项）
├── 项目交付部
│   ├── architect / developer / tester
│   └── planner / productizer / vision-analyst / media-producer
└── Ops（独立运营，星形枢纽）
    ├── OpsAgent：每日巡检（AI 推理）
    └── OpsHub：事件消费 → 日报写入（纯逻辑，快）
```

## Agent 角色路由

任务队列中 `agent_role` 字段决定使用哪个 Agent（executor.py `_make_agent()`）：

### 基础技术组（base_opt 队列）

| agent_role | Agent 类 | goals | facts | 用途 |
|-----------|---------|:---:|:---:|------|
| `base-architect` | BaseArchitectAgent | W | W | 平台架构整合，技术决策 |
| `base-validator` | BaseValidatorAgent | R | W | 基准测试，架构方案验证 |
| `hw-engineer` | HwEngineerAgent | R | W | 硬件选型，功耗/算力权衡 |
| `os-engineer` | OsEngineerAgent | R | W | 内核参数调优，驱动框架 |
| `dev-kernel` | KernelDevAgent | R | W | 内核驱动开发，DTS/BSP |
| `dev-lowlevel` | LowlevelDevAgent | R | W | 嵌入式固件，硬件 bring-up |
| `system-tester` | SystemTesterAgent | R | W | 系统集成测试 |
| `algo-antishake` | AlgoAntishakeAgent | R | W | 防抖算法专项 |
| `algo-position` | AlgoPositionAgent | R | W | 定位算法专项 |
| `algo-nav` | AlgoNavAgent | R | W | 导航算法专项 |

### 调研专项（project_delivery 队列，`__research__.*` 记忆域）

| agent_role | Agent 类 | 记忆域 | 用途 |
|-----------|---------|------|------|
| `rtp-researcher` | RtpResearcherAgent | `__research__.rtp.*` | RTP/RTCP 协议调研 |
| `net-researcher` | NetResearcherAgent | `__research__.net.*` | 网络栈优化调研 |
| `kernel-analyzer` | KernelAnalyzerAgent | `__research__.kernel.*` | 内核调度分析 |

### 平台扩展（project_delivery 队列）

| agent_role | Agent 类 | 用途 |
|-----------|---------|------|
| `nrf-dev` | NrfDevAgent | nRF54L15 / BLE 5.4 / Zephyr（运动健康） |
| `esp32-dev` | Esp32DevAgent | ESP32S3 / mmWave（适老辅助） |

### 项目交付组（project_delivery 队列）

| agent_role | Agent 类 | goals | facts | 用途 |
|-----------|---------|:---:|:---:|------|
| `architect` | ArchitectAgent | W | W | 跨项目架构分析 |
| `developer` | DeveloperAgent | R | R | 代码修复/重构（默认） |
| `tester` | TesterAgent | R | R | 本地+板端测试 |

### 产品洞察组（insight 队列）

| agent_role | Agent 类 | 用途 |
|-----------|---------|------|
| `planner` | PlannerAgent | 差距分析，洞察任务规划 |
| `productizer` | ProductizerAgent | 成熟度评估（100分制） |
| `vision-analyst` | VisionAnalystAgent | 视觉效果分析 |
| `media-producer` | MediaProducerAgent | 技术内容生产 |

### 市场专项（insight 队列）

| agent_role | Agent 类 | 记忆域 | 用途 |
|-----------|---------|------|------|
| `market-pm` | MarketPmAgent | `__market__.*` | 市场分析（通用） |
| `market-sport` | MarketSportAgent | `__market__.sport.*` | 运动健康市场 |
| `market-elder` | MarketElderAgent | `__market__.elder.*` | 适老辅助市场 |
| `market-safety` | MarketSafetyAgent | `__market__.safety.*` | AI 安全市场 |

### 组织管理层

| agent_role | Agent 类 | 用途 |
|-----------|---------|------|
| `boss` | BossAgent | 战略决策，周报 |
| `os-base-leader` | GroupLeaderAgent | 基础技术部部门长 |
| `vision-algo-leader` | GroupLeaderAgent | 视觉算法组组长 |
| `senior-dev` | SeniorDevAgent | 高级研发（跨组支援） |
| `ops` | OpsAgent | 项目健康巡检 + 文档维护 |

> W=可写 R=只读 | goals/facts 写权限受 `WRITE_ROLES` 常量约束（project_memory.py）

## 事件总线与日报

- **EventBus**（`tools/event_bus.py`）：Redis Streams，executor 任务完成/失败自动发布事件
- **Consumer Groups**：ops-hub / leader-os-base / leader-vision-algo / leader-market / boss
- **OpsHub**（`agents/ops.py`）：消费事件 → 写入 DailyReport，重大事件广播 leader
- **DailyReport**（`tools/daily_report.py`）：append-only SQLite，时间线 + Boss 决策视图
- **AgentScorer**（`tools/agent_score.py`）：4 维评分（完成度 40% + 质量 30% + 自主性 20% + 协作 10%）
- **VersionPipeline**（`tools/version_pipeline.py`）：反幻觉门控，dev agent 只能 start_testing，tester 才能 mark_done/mark_failed

## 编码规范

- `from __future__ import annotations`（保持跨版本兼容）
- 完整类型注解；路径使用 `pathlib.Path`
- 日志使用 `logging` 模块，不使用 `print`
- 命名：类 `PascalCase`，函数/变量 `snake_case`，常量 `UPPER_CASE`
- 测试放 `tests/`，调试 demo 放 `tmp/` 并确认后删除