qiuruiandClaude Opus 4.6
bbea70dc9c
文档刷新： - CLAUDE.md/README.md/DEVELOP.md/RELEASE.md 同步 org v2 架构 （Boss/GroupLeader/SeniorDev/Ops 组织层、EventBus/DailyReport/OpsHub/ AgentScorer/VersionPipeline 工具层、nrf-dev/esp32-dev/market-* 新角色） - 清除所有 /data/rockchip 路径引用 → /data/company（源码+测试+前端） - 保留 "Rockchip" 芯片厂商名作为技术描述（hw_engineer/algo_vision 等） - docs/plans/ 历史文档保持原样（反映当时路径状态） Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
226 lines
11 KiB
Markdown
226 lines
11 KiB
Markdown
# 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/` 并确认后删除
|