04 · 落地清单(Rails)
目标:把
proto/里的 6 个页面落到 nine-admin(Rails 7 + ERB + Bootstrap 3 + Turbolinks)。 原则:先做只读展示,再做动作;每个动作都要有审计与失败回滚。
一、改造顺序(建议 5 步,每步可单独上线)
| 步 | 内容 | 依赖 | 风险 |
|---|---|---|---|
| 1 | 侧栏 + 6 个空页面 + 权限点 | 无 | 极低 |
| 2 | brain_slots + posts + skill_registry 建表 + 后台维护页 |
无 | 低 |
| 3 | 集群档案 / 全部档案(只读,读 agent_* 表) | 步 2 | 低 |
| 4 | 工单派单(写 tickets.assignee) | 步 3 | 中(动工单) |
| 5 | 档案分析(ATP 模型 + Sidekiq)、任务派单 / 工单直达(下发通道) | 步 4 | 高(外部调用) |
二、控制器(app/controllers/admin/brain/)
Admin::Brain::SlotsController # 集群档案:index / show / configure
Admin::Brain::DirectivesController # 工单直达:index / create(任务会话、下达)
Admin::Brain::AnalysesController # 档案分析:index / create / show(轮询)
Admin::Brain::TaskDispatchesController # 任务派单:index / analyze / confirm
Admin::Brain::TicketDispatchesController # 工单派单:index / analyze / confirm
Admin::Brain::ArchivesController # 全部档案:index / show / export
Admin::Brain::SkillOpsController # 技能四动作:learn / assign / copy / revive
权限点(挂 admin_privileges,沿用 /admin/控制器&动作 格式):
/admin/brain/slots&index
/admin/brain/directives&index
/admin/brain/analyses&index
/admin/brain/task_dispatches&index
/admin/brain/ticket_dispatches&index
/admin/brain/archives&index
/admin/brain/skill_ops&learn / assign / copy / revive
三、路由
namespace :admin do
namespace :brain do
resources :slots, only: %i[index show] do
member { post :configure }
end
resources :directives, only: %i[index create]
resources :analyses, only: %i[index create show]
resources :task_dispatches, only: %i[index] do
collection { post :analyze; post :confirm }
end
resources :ticket_dispatches, only: %i[index] do
collection { post :analyze; post :confirm }
end
resources :archives, only: %i[index show] do
collection { get :export }
end
post 'skill_ops/learn', to: 'skill_ops#learn'
post 'skill_ops/assign', to: 'skill_ops#assign'
get 'skill_ops/copy', to: 'skill_ops#copy'
post 'skill_ops/revive', to: 'skill_ops#revive'
end
end
四、四个 SKILL 动作的后端实现
1. 主脑学习 POST /admin/brain/skill_ops/learn
- 校验主脑实体(
agent_clients里 type=mind 的那条)last_used_at在 10 分钟内,否则返回{ok:false, error:'mind_offline'},前端提示「主脑智能体未连接」。 - 把
skill_registry指向的agent_documents(kind=skill)复制/引用到主脑的档案空间(写入skill_registry.mind_learned_at)。 - 若走 MCP:调主脑的
sat_token 执行tools/call让主脑实际装载;失败则回滚标记。 - 记
skill_ops_logs(action='learn')+user_action_logs。
2. 技能指派 POST /admin/brain/skill_ops/assign
参数:skill_code, slot_id, mode(in|avail)
1. 校验 slot 已设置且 machine_uuid 非空。
2. 写 skill_registry.slot_id + status(in→in_use / avail→available)。
3. 生成待下发任务:在客户端下次 POST /api/v1/agents/sync 时带回,或走 MCP 直接下发。
4. 记 skill_ops_logs(action='assign', target_slot_id)。
3. 复制技能 GET /admin/brain/skill_ops/copy?code=
- 返回
text/markdown,Content-Disposition: attachment; filename="<技能名>.md"。 - 内容由服务端渲染(编号 / 岗位 / 状态 / 次数 / 说明 / 触发场景 / 步骤 / 边界),取自档案原文,不是模板壳。
- 前端
navigator.clipboard.writeText+ 触发下载,两条路都走。
4. 原岗复活 POST /admin/brain/skill_ops/revive
参数:skill_code
1. 找该 skill 所属 post → 找 staff_posts.ended_on 非空且 handover_to_staffer_id 非空的记录。
2. 无接替人 → {ok:false, error:'no_successor'},前端提示「该岗位暂无接替员工,请先补人」。
3. 有 → 取接替人名下的 slot,按 assign 逻辑指派为 in_use,并在 note 标记「原岗复活」。
五、两处必须"同源"的地方(验收项)
- 集群档案「已设置」数量 = 档案分析逐智能体详细框数量
两处都必须走同一个 scope:
BrainSlot.configured(agent_client_id IS NOT NULL)。 任何一边用别的取数(手写数组 / 视图局部变量)都会漂 → 直接判验收不通过。 - SKILL 的「在用/可用/弃用」=
skill_registry.status不允许前端按uses_count猜。
六、模型调用(ATP)
- 走现有 new-api 兼容端点(
ATP_*环境变量已在用)。 - 模型清单不要写死:从 ATP 的模型/渠道接口拉取并缓存(
Rails.cache,10 分钟)。 - 「DeepSeek Flash」的真实 model id 需按 ATP 返回确认(可能形如
deepseek-v3-flash)。原型里deepseek-flash只是占位。 - 分析结果落
brain_analyses.result(jsonb),不要每次打开都重算;重算要人工点「开始分析」。
七、性能与那台 2C/4GB
- 档案分析必须异步:
BrainAnalysisJob.perform_later(analysis_id),前端轮询GET /admin/brain/analyses/:id。 - 一次性数据修复/回填用
systemd-run --scope -p MemoryMax=600M(2026-10-17 活锁教训)。 - 全部档案的查询要加索引(
agent_documents(kind, last_uploaded_at)已有;新增skill_registry(post_id,status))。 - 导出 CSV 走流式(
send_data分块),不要一次to_a。
八、任务派单 / 工单直达的"下达通道"(必须先定)
两条路,二选一,这决定要不要动客户端:
| 方案 | 做法 | 代价 |
|---|---|---|
| A. MCP | 后台作为 MCP 客户端,用该智能体的 sat_ token 调 tools/call 下发任务 |
后台要维护 100 个 token 与客户端会话;现在就能通 |
| B. 任务队列接口 | 新增 POST/GET /api/v1/agent_tasks(客户端轮询取任务、回报结果) |
要改 V1.07 客户端加拉取逻辑;更稳、可离线排队 |
在选定之前,线上不得声明「可直接向智能体下达任务」。
九、安全
- 所有
create/update/destroy与四个技能动作,一律写user_action_logs(含 IP、参数过滤)。 - MCP token 权限面大(可封禁造物者、批退款、上下架),主脑相关工具单独开一组前缀
brain_*,只授 admin。 - 「复制技能」下载的内容要脱敏:不含 token、密钥、内网地址。