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>
302 lines
9.2 KiB
Markdown
302 lines
9.2 KiB
Markdown
# NMFS Agents 开发指南
|
||
|
||
## 环境搭建
|
||
|
||
```bash
|
||
python3.10 -m venv venv
|
||
source venv/bin/activate
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
## 认证
|
||
|
||
Agent 以子进程调用 `claude --print`，支持两种认证：
|
||
|
||
| 方式 | 配置 | 优先级 |
|
||
|------|------|--------|
|
||
| Claude CLI 登录 | `claude login`，token 存储于 `~/.claude/` | 推荐，无需配置 |
|
||
| API Key | 设置 `ANTHROPIC_API_KEY` 环境变量 | 备选 |
|
||
|
||
## 架构概览
|
||
|
||
### Agent → CLI 映射
|
||
|
||
```
|
||
DeveloperAgent.run(task)
|
||
└─> subprocess.Popen([
|
||
"claude", "--print",
|
||
"--output-format", "json",
|
||
"--no-session-persistence",
|
||
"--model", "claude-sonnet-4-6",
|
||
"--append-system-prompt", "<项目+模式上下文>",
|
||
# auto/confirm 模式（confirm 依赖 claude-wx hook 级审批）：
|
||
"--dangerously-skip-permissions",
|
||
# report 模式：
|
||
"--allowedTools", "Read,Glob,Grep",
|
||
"<任务描述>"
|
||
],
|
||
cwd="<项目路径>",
|
||
env={CLAUDECODE 已清除},
|
||
)
|
||
```
|
||
|
||
### 任务队列状态机
|
||
|
||
```
|
||
pending → running → done
|
||
→ failed
|
||
→ waiting_approval → done / failed / vetoed → pending
|
||
```
|
||
|
||
### 多队列架构
|
||
|
||
```
|
||
scheduler.py
|
||
├─> project_delivery 队列（tasks.db） ─> 项目开发/研究/管理类任务
|
||
├─> base_opt 队列（base_opt_tasks.db） ─> 算法/硬件优化类任务
|
||
└─> insight 队列（insight_tasks.db） ─> 洞察/分析/市场类任务
|
||
```
|
||
|
||
每个队列独立的 `role_filter` 确保任务只被有资格的 Agent 执行。
|
||
|
||
### 核心循环（scheduler → executor）
|
||
|
||
```
|
||
Scanner.scan_all() # 扫描 README/TODO/CLAUDE.md
|
||
└─> TaskQueue.enqueue() # SQLite，BEGIN EXCLUSIVE 原子操作，去重
|
||
└─> Executor.run_all_pending() # asyncio Semaphore 限流并发
|
||
├─> _make_agent(role) # 按 agent_role 路由到对应 Agent
|
||
├─> EventBus.publish_task_done/failed() # Redis Streams 事件广播
|
||
└─> FeishuNotifier.send_task_result()
|
||
```
|
||
|
||
### EventBus 事件流
|
||
|
||
```
|
||
Executor 任务完成/失败
|
||
└─> EventBus.publish() → Redis Stream "nmfs:events"
|
||
├─> ops-hub → OpsHub → DailyReport 写入
|
||
├─> leader-os-base → 基础技术部部门长
|
||
├─> leader-vision-algo → 视觉算法组组长
|
||
├─> leader-market → 市场洞察部
|
||
└─> boss → Boss 战略决策
|
||
```
|
||
|
||
### 反幻觉门控（VersionPipeline）
|
||
|
||
```
|
||
Dev Agent 开发完毕 → vp.start_testing() ← Dev 只能到这一步
|
||
TesterAgent 测试 → vp.mark_done() ← 只有 Tester 能标记完成
|
||
→ vp.mark_failed() ← 只有 Tester 能标记失败
|
||
```
|
||
|
||
## Web Dashboard
|
||
|
||
Dashboard 是首选操作入口，访问地址：`http://localhost:9080`（Docker 环境同端口）。
|
||
|
||
### 主要功能
|
||
|
||
| 标签页 | 功能 |
|
||
|--------|------|
|
||
| 看板（Kanban） | 按项目查看任务状态，可拖拽调整优先级 |
|
||
| 洞察（Insight） | 市场目标卡片（运动/适老/AI安全）+ 基础技术调研 |
|
||
| 日报（Daily） | 时间线视图（全部事件）+ Boss 决策视图（组织健康 + 待决策） |
|
||
| 配置（Config） | 查看/编辑 CLAUDE.md / README.md，触发 CLAUDE.md 刷新 |
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
python scripts/run.py status # 查看任务状态（多队列）
|
||
bash scripts/start_daemon.sh # 后台启动调度器
|
||
bash scripts/watch_daemon.sh # 监控日志
|
||
python scripts/run.py scan # 预览扫描结果
|
||
python scripts/run.py run-next # 执行下一个任务（须在普通终端）
|
||
python scripts/run.py research # 入队三专项调研（须在普通终端）
|
||
pytest tests/ -q # 全量测试
|
||
```
|
||
|
||
## 调试
|
||
|
||
### 查看任务队列
|
||
|
||
```bash
|
||
sqlite3 data/tasks.db "SELECT id,project,agent_role,title,status FROM tasks ORDER BY id DESC LIMIT 20;"
|
||
sqlite3 data/base_opt_tasks.db "SELECT id,project,agent_role,title,status FROM tasks ORDER BY id DESC LIMIT 10;"
|
||
sqlite3 data/insight_tasks.db "SELECT id,project,agent_role,title,status FROM tasks ORDER BY id DESC LIMIT 10;"
|
||
```
|
||
|
||
### 手动入队
|
||
|
||
```python
|
||
source venv/bin/activate
|
||
python - <<'EOF'
|
||
from nmfs_agents.config import load_config
|
||
from nmfs_agents.core.queue import Task, TaskQueue
|
||
import asyncio, nmfs_agents.core.executor as ex
|
||
|
||
cfg = load_config()
|
||
q = TaskQueue()
|
||
q.enqueue(Task(
|
||
project="embedding", type="code_review", title="分析代码质量",
|
||
context="", priority=3, mode="report", agent_role="developer"
|
||
))
|
||
asyncio.run(ex.Executor(cfg, queue=q).run_next())
|
||
EOF
|
||
```
|
||
|
||
> **注意**：`claude --print` 子进程需在 **Claude Code 会话外** 的普通终端执行。
|
||
|
||
### Scanner 扫描来源
|
||
|
||
| 来源 | 提取内容 | 优先级 |
|
||
|------|---------|--------|
|
||
| `README.md` 的 `## 已知问题` | 每一行问题 → `fix_bug` 任务 | 2 |
|
||
| `.py` 文件中的 `TODO/FIXME/HACK` | 注释 → `code_review` 任务 | 4 |
|
||
| `CLAUDE.md` 含 `❌/⚠` 的行 | 约束违反 → `fix_bug` 任务 | 2 |
|
||
| 兜底 | 每个项目固定生成定期代码巡检 | 5 |
|
||
|
||
### 架构优化版本管理
|
||
|
||
```
|
||
arch_optimize 任务入队
|
||
└─> ArchitectAgent._optimize()
|
||
├─ ArchVersion.snapshot()
|
||
├─ claude --dangerously-skip-permissions
|
||
├─ pytest tests/ -q
|
||
├─ 通过 → ArchVersion.promote()
|
||
└─ 失败 → ArchVersion.rollback()
|
||
```
|
||
|
||
## 添加新项目
|
||
|
||
在 `configs/projects.yaml` 添加：
|
||
|
||
```yaml
|
||
projects:
|
||
my-project:
|
||
path: /data/company/my-project # 省略则从 scan_dirs 自动发现
|
||
mode: auto # auto | confirm | report
|
||
```
|
||
|
||
## 添加新 Agent
|
||
|
||
1. 在 `src/nmfs_agents/agents/` 新建 `my_agent.py`，继承 `DeveloperAgent` 或独立实现 `run(task) -> AgentResult`
|
||
2. 在 `executor.py` 的 `_make_agent()` 添加路由条目
|
||
3. 在 `configs/agents.yaml` 的对应队列 `roles:` 中添加新角色名
|
||
4. 在 `tests/` 添加测试文件
|
||
|
||
## 配置说明
|
||
|
||
### configs/projects.yaml
|
||
|
||
```yaml
|
||
scan_dirs:
|
||
- /data/company
|
||
- /data/company/algo-base
|
||
exclude_projects:
|
||
- rknn-toolkit2
|
||
- agents
|
||
projects:
|
||
my-project:
|
||
path: /data/company/my-project
|
||
mode: confirm
|
||
```
|
||
|
||
### configs/agents.yaml
|
||
|
||
```yaml
|
||
scheduler:
|
||
interval_hours: 1
|
||
max_concurrent: 3
|
||
queues:
|
||
project_delivery:
|
||
db: data/tasks.db
|
||
max_concurrent: 3
|
||
roles: [developer, architect, tester, rtp-researcher, ...]
|
||
base_opt:
|
||
db: data/base_opt_tasks.db
|
||
max_concurrent: 2
|
||
roles: [algo-antishake, algo-position, ...]
|
||
insight:
|
||
db: data/insight_tasks.db
|
||
max_concurrent: 2
|
||
roles: [planner, productizer, market-pm, ...]
|
||
```
|
||
|
||
### configs/devices.yaml
|
||
|
||
```yaml
|
||
devices:
|
||
rk3566:
|
||
host: 192.168.123.183
|
||
user: orangepi
|
||
password: "orangepi"
|
||
workspace: /home/orangepi/Desktop
|
||
rk3588:
|
||
host: 192.168.123.137
|
||
user: pi
|
||
password: "pi"
|
||
workspace: /home/pi/Desktop
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 | 必填 |
|
||
|------|------|------|
|
||
| `ANTHROPIC_API_KEY` | Claude API 密钥（已 `claude login` 则不需要） | 否 |
|
||
| `FEISHU_WEBHOOK_URL` | 飞书 Webhook，任务结果通知 | 否 |
|
||
| `DB_PATH` | 任务数据库路径（默认 `data/tasks.db`） | 否 |
|
||
| `DASHBOARD_PORT` | Dashboard 端口（默认 8080） | 否 |
|
||
|
||
## API 端点参考
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/tasks` | 获取任务列表 |
|
||
| POST | `/api/tasks` | 创建任务（`queue` 字段路由） |
|
||
| PATCH | `/api/tasks/{id}` | 更新优先级 |
|
||
| POST | `/api/tasks/{id}/retry` | 重试失败任务 |
|
||
| GET | `/api/projects` | 获取项目列表 |
|
||
| POST | `/api/projects/import` | 导入新项目 |
|
||
| GET | `/api/market/facts` | 市场洞察 facts |
|
||
| POST | `/api/market/trigger/{goal}` | 触发市场洞察 |
|
||
| GET | `/api/research/facts` | 三专项调研 facts |
|
||
| GET | `/api/daily/timeline` | 日报时间线 |
|
||
| GET | `/api/daily/boss` | Boss 决策视图 |
|
||
| GET | `/api/daily/dates` | 可用日期列表 |
|
||
| GET | `/api/daily/scores` | Agent 评分 |
|
||
|
||
### 队列路由
|
||
|
||
| queue 值 | 路由到 | 典型 agent_role |
|
||
|----------|--------|-----------------|
|
||
| `project_delivery`（默认）| `data/tasks.db` | developer / architect / boss / ops |
|
||
| `base_opt` | `data/base_opt_tasks.db` | algo-* / hw-engineer / os-engineer |
|
||
| `insight` | `data/insight_tasks.db` | market-* / planner / productizer |
|
||
|
||
## 项目记忆系统
|
||
|
||
`data/project_memory.db` 分三层：
|
||
|
||
| 层 | 读写规则 |
|
||
|----|---------|
|
||
| goals（目标） | 仅 productizer/architect 可写 |
|
||
| facts（事实） | 任意 agent；通过 `[记忆]` 标签写入 |
|
||
| history（历史） | executor 每次任务完成/失败后自动写入 |
|
||
|
||
### 特殊 facts 命名约定
|
||
|
||
| key 前缀 | 写入者 | Dashboard 展示 |
|
||
|----------|--------|---------------|
|
||
| `__research__.rtp.*` | rtp-researcher | 洞察页"基础技术调研" |
|
||
| `__research__.net.*` | net-researcher | 洞察页"基础技术调研" |
|
||
| `__research__.kernel.*` | kernel-analyzer | 洞察页"基础技术调研" |
|
||
| `__market__.{goal}.*` | market-* | 洞察页目标卡片 |
|
||
| `__env__.*` | env-collector | Agent 系统提示 |
|
||
|
||
## Watchdog
|
||
|
||
`core/watchdog.py` 后台 daemon 线程（60s 间隔）：
|
||
- `reset_stale_running(timeout=120min)`：running 超时 → failed
|
||
- `bump_stale_priorities(threshold=120min)`：pending 久等 → priority-1（防饥饿）
|