aiagent/docs/虚拟公司模块-功能与使用文档.md

虚拟公司模块 · 完整功能与使用文档

适用平台：天工 AI Agent 平台（后端 FastAPI :8037，前端 Vue3 :3001） 模块定位：在「虚拟团队」之上再叠一层 3 级组织（公司 → 部门 → 成员），用一句业务目标驱动一整支 AI 团队自动完成「CEO 规划 → 部门并行执行 → CEO 评审打分 → 多轮返工」的闭环，并提供白盒控制室做全程可观测 + 可干预。

---

目录

1. 核心概念与数据模型
2. 三阶段编排流程
3. 功能特性全览
4. 前端使用指南（3 个页面）
5. 白盒控制室：实时控制能力
6. 学习闭环与知识沉淀
7. 报告导出、洞察、调度、模板市场、项目监管
8. API 参考
9. 配置项
10. 典型端到端使用流程
11. 设计取舍与注意事项

---

1. 核心概念与数据模型

概念	底层实体	说明
公司 Company	companies	3 级组织的顶层。含 name/description/industry/ceo_agent_id/status。
部门 Department	复用 teams（parent_company_id 指向公司，department_type 标类型）	一个部门 = 一支虚拟团队，运行时由 TeamOrchestrator 驱动。config JSON 存 model_override 等。
成员 Member	team_members → agents	部门内的 AI 角色（pm/dev-backend/qa/ceo/cto…），每个成员是一个 Agent。
项目 Project	company_projects	一次公司执行任务。含 description/status/ceo_plan/review_scores/round_count/成本时长等。
事件 Event	company_project_events	执行全过程的时间线，按 per-run 单调 seq 落库，是白盒可观测与回放的数据源。
知识 Knowledge	company_knowledge	公司记忆：项目沉淀出的 ceo_plan/dept_output/review/insight 4 类知识，回喂给 CEO 规划。
调度 Schedule	company_schedules	定时触发项目（cron 或固定间隔）。

部门类型（department_type）：executive(战略) / product(产品) / engineering(交付/工程) / operations(运营) / marketing / sales / finance / hr。

事件信封（envelope）：CompanyProjectEvent.to_envelope() → { seq, pid, type, payload, ts }，业务数据统一嵌在 payload 下。

---

2. 三阶段编排流程

CompanyOrchestrator（复用 TeamOrchestrator）执行一个项目分三阶段，外层可多轮返工：

Phase 1 · CEO 规划
  └─ CEO Agent 读业务目标 + 各部门可用角色 (+ 注入历史经验) → 产出 JSON 计划
      { analysis, departments:[ {department_name, goal, deliverables, dependencies} ] }

Phase 2 · 部门并行执行（按依赖分波次）
  └─ 无依赖部门先跑；下游部门等上游 dept_done 后启动
  └─ 上游交付物按 dependencies 精准注入下游部门 context（部门间交接）
  └─ 每波并行度 ≤ MAX_CONCURRENT_DEPARTMENTS

Phase 3 · CEO 评审打分
  └─ 逐部门 0–10 打分 + pass/feedback/improvement_areas + overall_score

（可选）多轮返工 round 2..N
  └─ 失败部门带「CEO 评审反馈 + 改进方向 (+ 人工意见)」重跑，直到全过或达 max_rounds

关键点：

• CEO 计划可预览（/plan）后再执行，也可直接把审定后的 ceo_plan 传给 /execute/async 跳过规划。
• 返工不是「盲目重跑」：默认就会把 CEO 打分反馈注入失败部门；开返工审批门后还能注入人工意见。
• 评审是直连单次 LLM（非 ReAct），解析失败会显式 parse_failed 并中断，不再静默 auto-pass。

---

3. 功能特性全览

3.1 组织搭建

• 6 套预置模板一键建公司（自动建部门 + Agent + 填成员）：

  preset_type	名称	角色数
  tech-software	软件科技公司	9（CEO/CTO 顾问、产品、UI、前后端、测试、运维、文档）
  ecommerce-retail	电商零售公司	8
  consulting-service	咨询服务公司	8
  manufacturing	制造企业	8
  media-marketing	媒体营销公司	8
  entertainment-media	娱乐传媒公司	7

• 自定义建公司：空壳公司 + 手动增删部门（从已有 Team 挂载 / 卸载）。
• 按部门配模型（四档-③）：给某部门指定 provider/model，该部门全体成员统一走该模型，做成本/质量分层（如交付层用便宜模型、战略层用强模型）。留空即回归成员 Agent 自身模型。

3.2 执行与规划

• 计划预览 /plan：只跑 CEO 规划、不执行，供人工审阅（覆盖 300s 超时）。
• 三种执行入口：/execute（同步阻塞）、/execute/stream（SSE 流式）、/execute/async（异步 + 白盒控制室，推荐）。
• 部门间交接（四档-①）：上游部门交付物按声明的 dependencies 精准注入下游 context（逐项 ≤2000 字、合计 ≤6000 字），下游在上游产物基础上衔接，不重复劳动。

3.3 白盒控制室（实时可观测 + 可干预）

详见 第 5 节。含：事件流实时推送、停止/暂停/继续/跳过部门、单部门取消/返工、人在环审批（计划门 + 返工门，可注入反馈）、预算熔断、超时熔断。

3.4 可信度量

• 真实 token + 成本（¥）：无条件累计每次 LLM 的真实 usage，逐部门 cost_yuan/tokens_used、公司级 total_cost_yuan，与各部门之和精确相等。控制室顶栏实时显示成本。

3.5 学习闭环

• 项目终态自动沉淀知识 → CEO 规划回喂历史经验。详见 第 6 节。

3.6 规模与健壮性（三档-a/b）

• 事件批量落库：攒批写（默认 25 条 / 0.7s 触发一次），大幅降低对远程 MySQL 的写放大；终态事件立即 force-flush 保证 finale 不被截断。
• 项目并发上限 + 真实排队：MAX_CONCURRENT_COMPANY_PROJECTS（默认 3）个并行，超出者进队列（有 queued 事件 + 心跳防僵尸误杀），排队期不占 DB 连接。
• 每波部门并发上限：MAX_CONCURRENT_DEPARTMENTS（默认 4），总并发部门 ≤ 项目×部门，不打爆连接池。

---

4. 前端使用指南（3 个页面）

路由	页面	作用
/company-presets	预置模板	选模板一键建公司
/companies	公司构建器 CompanyBuilder	公司/部门管理、按部门配模型、计划预览、启动项目
/companies/:companyId/projects/:projectId/monitor	白盒控制室 CompanyControlRoom	实时观测 + 全部运行时控制 + 导出报告

4.1 建公司

• 走 /company-presets 选一套模板（如「软件科技公司」），可自定义公司名 → 一键生成完整班底。
• 或在 /companies 新建空公司再手动挂部门。

4.2 配置部门模型（可选）

在 CompanyBuilder 的部门卡片头，点「默认模型 / xxx」标签 → 弹窗选 provider（deepseek/openai/anthropic/siliconflow）+ 填 model → 保存 / 清除。

4.3 启动项目

1. 在 CompanyBuilder 输入业务目标 → 预览计划（看 CEO 会怎么拆部门）。
2. 设置运行选项（最大轮次、成本上限 ¥、超时上限、是否开启计划/返工审批门）。
3. 确认并执行 → 走 /execute/async → 自动跳转白盒控制室。

---

5. 白盒控制室：实时控制能力

控制室通过 WebSocket /api/v1/ws/company-projects/{projectId}?token=&since_seq= 实时接收事件（断线重连自带全量回放），并提供以下控制（M2 十项能力）：

能力	端点	语义
停止	POST …/stop	硬取消整个项目 → company_terminated + status=stopped
暂停 / 继续	POST …/pause …/resume	暂停=不开新波次（在飞部门跑完）；继续=恢复调度
跳过部门	POST …/skip {department_name}	仅跳过「未开始」的部门，下游照常推进
单部门取消	POST …/departments/{name}/cancel	硬取消运行中的某部门，仍发 dept_done{cancelled} 让波次推进
单部门返工	POST …/departments/{name}/rework	对已跑完的部门 on-demand 重跑（seq 续写）
人在环审批	POST …/approve {decision, gate?, feedback?}	计划门 / 返工门；返工门可带 feedback 注入人工意见
预算熔断	执行参数 max_cost_yuan	累计成本超阈 → budget_tripped + 优雅停（不打断在飞 LLM）
超时熔断	执行参数 max_duration_min	超时 → timeout_tripped + 停

关键事件类型：company_start / ceo_plan_start / ceo_plan_done / round_start / dept_waiting / dept_done / dept_skipped / ceo_score_done / round_done / company_done / company_terminated / awaiting_approval / approval_resolved / paused / resumed / budget_tripped / timeout_tripped / rework_start / rework_done / dept_agent_event。

审批门用法：启动时 approve_plan=true → CEO 出计划后停在 awaiting_approval(plan)，控制室弹窗批准/拒绝；approve_rework=true → 每轮评审后若有失败部门，停在 awaiting_approval(rework)，可在弹窗里填反馈再批准。

导出报告：控制室「导出报告」按钮 → GET …/report 下载单项目 Markdown 运行报告（概要/CEO 规划/部门结果/评分/时间轴）。

---

6. 学习闭环与知识沉淀

闭环两半（四档-②）：

1. 沉淀（自动）：项目终态时自动把本次项目抽取为知识（ceo_plan/dept_output/review/insight 4 类），按 project_id 去重，落 company_knowledge。手动触发：POST …/knowledge/generate {project_id}。
2. 回喂（自动）：CEO 规划前，按相关性检索本公司历史知识（领域信号词命中 + tag 命中打分，review/insight 权重更高），取 TopN（默认 5 条 / ≤4000 字）拼成「## 历史项目经验」块注入 CEO system prompt，让 CEO 复用被验证的做法、规避已知低分项。

门控开关见 COMPANY_CEO_MEMORY_ENABLED / COMPANY_AUTO_EXTRACT_KNOWLEDGE，关闭即回归旧行为。

知识管理：GET …/knowledge（可 search/category/limit）、DELETE …/knowledge/{id}。

---

7. 报告导出、洞察、调度、模板市场、项目监管

• 导出：GET …/export（整公司 Markdown）、GET …/projects/{pid}/report（单项目运行报告，文件名走 RFC 5987 支持中文）。
• 统计/洞察：GET …/stats（项目数/成功率/最近活跃）；GET …/insights（部门执行统计、协作对、平均轮次/成本、失败原因、改进建议）。
• 定时调度：…/schedules 增删改查 + …/schedules/{id}/trigger 立即触发（cron 或 interval_minutes）。
• 模板市场：POST …/projects/{pid}/publish / unpublish 发布/下架项目为可复用模板；GET /templates/list 浏览。
• 项目监管（Supervisor）：GET …/supervisor/zombies（僵尸项目）、…/supervisor/in-progress（在途 + 风险预警）、POST …/supervisor/scan（触发扫描）、POST …/projects/{pid}/recover（恢复）。

---

8. API 参考

全部前缀 /api/v1/companies。鉴权：Authorization: Bearer <token>。

公司

方法	路径	说明
GET	``	列出公司
GET	/{id}	公司详情（含部门）
POST	``	新建公司 {name, description?, industry?}
POST	/template/{preset_type}?company_name=	预置模板建公司
PUT	/{id}	更新公司
DELETE	/{id}	删除公司
GET	/{id}/export	导出整公司 Markdown
GET	/{id}/stats	公司统计
GET	/{id}/insights	公司洞察分析

部门

方法	路径	说明
POST	/{cid}/departments	挂载部门 {team_id}
DELETE	/{cid}/departments/{did}	卸载部门
PUT	/{cid}/departments/{did}/model	按部门配模型 {provider?, model?}

执行与规划

方法	路径	说明
POST	/{cid}/plan	预览 CEO 计划（300s）
POST	/{cid}/execute	同步执行
POST	/{cid}/execute/stream	SSE 流式执行
POST	/{cid}/execute/async	异步执行（白盒控制室）→ {project_id, status, ws_url}
GET	/{cid}/projects/{pid}/events?since_seq=&limit=	拉取事件（HTTP 回放）
WS	/api/v1/ws/company-projects/{pid}?token=&since_seq=	实时事件流

/execute/async body：{ project_description, ceo_plan?, max_rounds=1, max_cost_yuan?, max_duration_min?, approve_plan=false, approve_rework=false }

运行时控制

方法	路径
POST	/{cid}/projects/{pid}/stop · /pause · /resume
POST	/{cid}/projects/{pid}/skip {department_name}
POST	/{cid}/projects/{pid}/approve {decision, gate?, feedback?}
POST	/{cid}/projects/{pid}/departments/{name}/cancel · /rework
GET	/{cid}/projects
GET	/{cid}/projects/{pid}/report

知识 / 调度 / 模板 / 监管

方法	路径	说明
GET/POST/DELETE	/{cid}/knowledge …	知识列表 / generate {project_id} / 删除
GET/POST/PUT/DELETE	/{cid}/schedules …, /schedules/{id}	调度增删改查
POST	/schedules/{id}/trigger	立即触发调度
GET	/templates/list?search=	模板市场列表
POST	/{cid}/projects/{pid}/publish · /unpublish	发布/下架模板
GET	/supervisor/zombies · /supervisor/in-progress	项目监管
POST	/supervisor/scan · /{cid}/projects/{pid}/recover	扫描 / 恢复

---

9. 配置项

app/core/config.py（可用同名环境变量覆盖；放宽默认值即回归旧行为）：

配置	默认	含义
MAX_CONCURRENT_COMPANY_PROJECTS	3	同时运行的项目上限，超出排队
MAX_CONCURRENT_DEPARTMENTS	4	每波并行部门上限
COMPANY_EVENT_FLUSH_MAX_EVENTS	25	事件攒批条数（=1 即逐条 commit）
COMPANY_EVENT_FLUSH_INTERVAL_SEC	0.7	事件攒批时间阈（WS 可见延迟 ≤ ~1.5s）
COMPANY_QUEUE_HEARTBEAT_SEC	60	排队期刷新 updated_at 防僵尸误杀
COMPANY_CEO_MEMORY_ENABLED	True	是否回喂历史知识给 CEO
COMPANY_CEO_MEMORY_MAX_ENTRIES	5	回喂知识最大条数
COMPANY_CEO_MEMORY_MAX_CHARS	4000	回喂知识最大字数
COMPANY_AUTO_EXTRACT_KNOWLEDGE	True	项目终态是否自动沉淀知识

---

10. 典型端到端使用流程

1. /company-presets 选「软件科技公司」→ 建公司「XX 科技」
2. （可选）CompanyBuilder 给交付层配便宜模型、战略层配强模型
3. 输入业务目标（例：开发一个「家庭泡饮」制作助手，能展示图片和制作方法）
4. 预览计划 → 确认 CEO 把任务拆成 产品层/交付层/运营层/战略层
5. 设运行选项（max_rounds=1、max_cost_yuan=50 护栏）→ 确认并执行
6. 自动进白盒控制室：实时看各部门 ReAct 步骤、成本累加
   - 中途可暂停/跳过/单部门重跑；开审批门可人工把关计划与返工
7. company_done → 看综合评分 + 总成本；「导出报告」下载 Markdown
8. 产物落在 team_projects/{department_team_id}/… （HTML/CSS/JS + 图片等）
9. 本次项目自动沉淀为知识 → 下个项目 CEO 规划自动复用经验

产物目录约定：各部门产物写到 D:\workspace\aiagent\team_projects\{部门 team_id}\<context 目录>\；公司级项目记录在 backend\company_projects\{company_id}\<项目名>\。

---

11. 设计取舍与注意事项

• 复用而非重造：部门 = Team、CompanyOrchestrator 复用 TeamOrchestrator，Department.config 复用 Team 的 JSON 字段存 model_override（避免破坏性 alembic 迁移）。
• 单 worker 运行时状态：_RUNNING/_CONTROL 注册表在进程内，事件投递（WS/HTTP）已是 DB 轮询天然跨进程安全；多副本横向扩展（Redis 分布式控制 + Celery）为后续规划，当前单副本。
• 终态原子性：终态事件永远 force-flush，崩溃至多丢缓冲窗内的「非终态闲聊事件」；status/review_scores 由编排器自身 session 独立提交，正确性不受批量写影响。
• 返工语义：交接产物累加器每轮重置，返工轮只重跑失败部门 → 下游返工可能拿不到未重跑上游的最新交付物（首轮全量交接是核心价值）。
• 评审健壮：评审直连单次 LLM + 一次纠正重试；解析失败显式 parse_failed=False→pass、中断当轮，绝不静默 auto-pass 污染打分/熔断。
• 模型覆盖范围：model_override 只改 provider/model，不动 temperature/tools/prompt。

文档版本：2026-07-12。对应虚拟公司 M1（白盒控制室）+ 一档~三档 + 四档①②③④ 全部已实施。