nmfs-agents/DEVELOP.md

NMFS Agents 开发指南

环境搭建

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 刷新

常用命令

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                      # 全量测试

调试

查看任务队列

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;"

手动入队

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 添加：

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

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

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

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（防饥饿）