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      # 发布记录

环境

# 创建虚拟环境（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 执行。

常用命令

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/ 并确认后删除