aiagent/docs/虚拟公司迭代计划.md

虚拟公司模块迭代计划

制定日期：2026-07-27 | 基于 K3 分析报告 33 问题 + 23 建议 | 单 worker 自用场景

总览

V2.1 ─ 安全还债（2天）      ← 当前起点
V2.2 ─ 验证闭环（5-7天）    ← 最大价值增量
V2.25 ─ 智能化提升（4-5天） ← 六张牌：自验/验收标准/画像/批判/交接/检索
V2.3 ─ 模板化复用（3天）    ← 低成本高回报
V2.4 ─ 质量加固（3天）      ← 收口清理
V3.0 ─ 运行时上线（2-3天）  ← Redis 解耦 + 多 worker 就绪

---

V2.1 — 安全还债（2 天）

目标：上线阻断级问题清零，删掉旧执行链路

2.1.1 鉴权修复（半天）

为以下端点补 _assert_company_owner 或 Depends：

• GET/DELETE /knowledge/{id} — 任何登录用户可删他人知识
• POST/PUT/DELETE /schedules/* — 任何登录用户可改他人调度
• POST /supervisor/* — 未做归属校验
• GET /projects (list_projects) — 未过滤 workspace
• DELETE /{company_id} — 确认 admin 权限

做法：把 _assert_company_owner 改为 FastAPI Depends（像 require_workspace_admin 那样），从机制上防止遗漏。

2.1.2 XSS 治理（半天）

CompanyBuilder.vue 4 处 v-html 输出走 DOMPurify.sanitize()：

• L453: CEO 评审 summary
• L488: 部门交付物
• L508: 知识条目内容
• L615: 洞察分析文本

做法：统一 renderMarkdown 内部末尾调 DOMPurify.sanitize()，不改调用方。

2.1.3 执行入口收敛（半天）

• POST /{company_id}/execute/stream (SSE) → 下线，前端改为跳控制室
• POST /{company_id}/execute (非流式) → 标记 deprecated，内部改为调 execute_stream 并缓冲事件
• Builder 的 "停止" 按钮 → 改调后端 POST /{project_id}/stop
• approve 决策归一化 → .lower().strip() 后白名单匹配

保留：POST /{company_id}/execute/async + WS 作为唯一执行入口。

2.1.4 P0 后端修复（半天）

修复	位置	做法
_parse_ceo_json 返回 {} 时直接报错	orchestrator.py:131	if not plan or not plan.get("departments"): raise ValueError(...)
Kimi K3 temperature 归一化	orchestrator.py:379/1572	在 _LLMClient 或 AgentLLMConfig 层统一 provider=="moonshot" → temperature=1
_run_department 标记废弃	orchestrator.py:440	改内部调 _run_department_stream + 缓冲

---

V2.2 — 验证闭环（5-7 天）

目标：评审从"印象分"变"证据分"，一次通过率有数据可衡量

2.2.1 验证器框架（2 天）

新增 app/services/deliverable_validator.py：

class DeliverableValidator:
    """按交付物类型自动选择验证器，产出机器验证报告"""
    
    async def validate(project_path: Path, dept_results: List[Dict]) -> ValidationReport:
        """遍历各部门产出文件，匹配验证器，生成结构化报告"""

三类验证器（从简到深）：

类型	检测逻辑	证据输出
文档/报告	字数 ≥ 200、必含章节关键字（背景/分析/建议/结论 中 2 个）	{pass, word_count, found_sections, missing_sections}
HTML/网页	起 http.server → http_request 冒烟（1 次 GET，断言 200 且 body 非空）	{pass, status_code, body_size, syntax_errors}
Python/JS 代码	Python ast.parse() / JS esprima（或正则基础检查：括号匹配、import 可解析）	{pass, syntax_ok, importable, error_msg}

不做：沙箱执行、完整单测（太重，V2.2 范围外）。验证器仅做自动化冒烟检查。

2.2.2 评审引擎改造（1.5 天）

改 _ceo_review_with_scoring（orchestrator.py:1477-1620）：

评审 prompt 从：

Output: {deliverable[:800]}

改为结构化的验证报告注入：

## 机器验证报告（客观证据）

### 部门「技术研发」
- 交付物类型: HTML 网页
- 文件数: 12
- 验证项1: 语法检查 → ✅ 通过
- 验证项2: 页面冒烟 → ✅ 通过 (HTTP 200, body 8421 bytes)
- 验证项3: 内容完整性 → ✅ 通过 (含关键词: 产品介绍/技术架构/价格方案)

### 部门「市场策略」
- 交付物类型: 文档/报告
- 验证项1: 基本完整性 → ⚠️ 未通过 (缺"数据分析"章节)
- 验证项2: 字数检查 → ✅ 通过 (1560 字)
- 总体: ⚠️ 1/2 项通过

## 部门 LLM 交付物摘要
{原 deliverable 文本 800 字}

请基于以上**机器证据**评审并打分，打分必须引用具体验证结果。

评分规则增加约束：

• 机器验证全部通过 → pass 默认为 true（除非内容明显糊弄）
• 机器验证有失败项 → pass 可以为 true 但必须写理由说明"为什么失败项不影响整体"
• score 与验证通过率相关但不强制等比例（保留 LLM 判断空间）

2.2.3 返工接验证证据（1 天）

改 execute_stream 多轮迭代的返工注入逻辑（orchestrator.py:1170-1184）：

返工 feedback 从：

p["rework_feedback"] = "CEO 评审反馈：" + feedback + "\n改进方向：" + areas

改为：

p["rework_feedback"] = (
    f"## 机器验证结果\n{validation_report[dept_name]}\n\n"
    f"## CEO 评审反馈\n{feedback}\n\n"
    f"## 改进方向\n{areas}"
)

这样部门返工时看到的不只是"质量不够好"，而是"index.html 语法检查发现 3 个错误：第 43 行缺少闭合标签"。

2.2.4 数据采集（0.5 天）

在 company_projects 表加两个字段（或存在 review_scores JSON 里）：

• validation_report JSON — 机器验证完整报告
• validation_pass_rate float — 首轮验证通过率

加一个简单的对比查询供 V2.4 做趋势图：

SELECT DATE(created_at), AVG(validation_pass_rate), COUNT(*)
FROM company_projects
GROUP BY DATE(created_at)

2.2.5 冒烟验证（0.5 天）

用 3 个历史项目（1 文档类 + 1 网页类 + 1 失败类）回归跑，确认：

• 机器验证不会误杀（false negative）
• 评审 prompt 注入证据后，打分与之前对比有无显著偏移
• 返工 feedback 包含具体错误信息而非泛泛"不够好"

---

V2.25 — 智能化提升（4-5 天）

目标：在 V2.2 验证管道上，把产出质量从"靠 LLM 自己"拉到"有约束、有自检、有历史经验"

前提：V2.2 的验证器框架 + 证据注入评审已就位，本阶段所有改动都是"已有管道上改 prompt 结构 + 查库统计"，不引入新基础设施。

2.25.1 验证器前移：部门交付前自验（1.5 天）★ 最高优先级

现在验证发生在部门交付之后（CEO 评审时）。前移到部门内部：

部门产出 → 跑验证器+验收标准 → 自验
  ├─ 通过 → 准交付
  └─ 不过 → 部门自己修（max 2 次内部返工）→ 过了才准交付

做法：TeamOrchestrator 里加一个 _pre_delivery_gate()，在部门标记 done 之前：

1. 对产出文件跑 DeliverableValidator.validate()（复用 V2.2 验证器）
2. 若本部门交付物有验收标准（见 2.25.2），逐项核对
3. 未通过 → 注入修正 feedback 给 Agent，最多 2 轮自修
4. 通过 → 正常交付

效果：垃圾不出部门门——"研发部交了个打不开的网页，CEO 打回，整轮返工"变成"研发部内部修好了才交"。一次通过率提升是最直接的智能化度量。

2.25.2 验收标准驱动（1 天）

现在 CEO 规划的 deliverables 只是名词列表（"线框图""API 规约"），验证器只能做通用冒烟。

改 CEO 规划 prompt（orchestrator.py Phase1），每个交付物必须带验收标准：

{
  "department_name": "技术研发",
  "deliverables": [
    {
      "name": "产品落地页",
      "type": "html",
      "acceptance": [
        "首屏含产品名 + slogan",
        "有价格表区块且含 3 个以上套餐",
        "移动端视口不横向滚动",
        "JS 无语法错误",
        "所有链接可点击且不 404"
      ]
    }
  ]
}

验证器侧改动（DeliverableValidator）：

• 机器可查的（JS 语法、文件存在、字数）→ 机器逐项判 ✅/❌
• 机器不能查的（"首屏含产品名"）→ 标记为 requires_llm_judgment，传给评审 LLM 逐项判

评审 prompt 改动（_ceo_review_with_scoring）：

## 验收标准逐项核对

### 交付物「产品落地页」
| 验收标准 | 机器验证 | LLM 判定 |
|----------|----------|----------|
| JS 无语法错误 | ✅ 通过 | — |
| 首屏含产品名+slogan | — | ✅ 通过 (h1 标签含"AI客服系统·让服务更智能") |
| 有价格表区块且含3+套餐 | — | ❌ 未通过 (价格表仅2个套餐) |
| 移动端不横向滚动 | — | ⚠️ 无法判定 (无移动端截图) |

通过率: 2/4, 待定: 1/4

这直接把评审从"整体印象分"变成"逐项验收"——评分可信度质变。

2.25.3 Agent 能力画像（1 天）

review_scores 已积累每个部门的历史得分——从未被用于决策。

新增 app/services/agent_profiler.py：

class AgentProfiler:
    """基于历史 review_scores 构建 Agent 能力画像"""
    
    async def get_profile(agent_id: str) -> AgentProfile:
        """返回: {强项任务类型及均分, 弱项类型及均分, 总项目数, 趋势}"""
    
    async def get_department_profile(dept_name: str, task_type: str) -> DeptProfile:
        """返回: 该部门在同类任务上的历史均分/通过率/样本数"""

数据来源：company_projects.review_scores JSON → dept_scores[dept_name].score

注入位置：

1. CEO 规划时（orchestrator.py Phase1 prompt）：注入画像摘要

   ## Agent 历史能力画像
   - 技术研发部：网页类均分 8.7/10（12 次），数据分析类均分 5.2/10（3 次）
   - 市场策略部：文案类均分 8.1/10（9 次），定价策略类均分 6.8/10（4 次）
   → 本次「网页+文案」类项目，当前部门配置匹配度高
   

2. 任务分配优化：强项 → 可用更便宜的小模型（下一步），弱项 → 自动路由强模型

纯统计 + prompt 注入，无新基础设施。数据全在库里。

2.25.4 规划自我批判（0.5 天）

CEO 规划是单次出 JSON。加一轮 critique：

CEO 出计划 v1
  → 第二个 LLM 调用扮演"挑刺者"（检查：依赖环？漏环节？标准不可验？粒度太粗？）
  → 挑刺结果注入
  → CEO 修订出 v2（最终版）

挑刺 prompt 要点：

• 依赖图有无环？有无缺失的前置环节？
• 每个交付物验收标准是否可验证？（"做得好"不可验，"JS 无语法错误"可验）
• 交付物粒度是否合理？（一个部门 10 个交付物 → 太碎；一个部门 1 个"完成所有工作" → 太粗）
• 部门间交接是否有明确的输入/输出契约？

成本：一次额外 LLM 调用（¥0.05 级），规划质量显著上移。复杂项目尤其明显——单次规划最常见的病就是依赖关系错和验收标准虚。

2.25.5 交接结构化（0.5 天）

现在交接是"上游 deliverable 截断 2000 字"塞给下游——粗糙。

改 _build_handoff_context（orchestrator.py），改为结构化交接包：

## 上游「技术研发」交付物交接

### 契约摘要
- 数据接口: POST /api/product/{id} → {name, price, features}
- 页面路由: /, /pricing, /about
- 样式规范: Tailwind CSS, 主色 #2563eb

### 文件清单
- /outputs/技术研发/index.html (12KB)
- /outputs/技术研发/style.css (4KB)
- /outputs/技术研发/api-spec.yaml (2KB)

### 关键决策
1. 价格方案选三档（免费/Pro/企业）而非五档——CEO 评审倾向简洁
2. 移动端用响应式而非独立 m. 子域——维护成本低

### 给下游的注意事项
- 市场策略部写文案时，feature 列表以 api-spec.yaml 为准
- 首页 hero 区 slogan 留空，由市场策略部填充

效果：下游部门拿到的是"接口文档"而非"上游的工作总结小作文"。对代码类项目提升巨大——后端写的 API 前端真能对上。

2.25.6 知识检索升级（0.5 天）

学习闭环现在是关键词匹配（company_knowledge_extractor.py 20 个硬编码中文词做 tag 提取 + _select_relevant_knowledge 靠关键词命中次数加权）。基础设施（vector_memory_enabled）早就有了。

做法：

1. 知识条目入库时，调 embedding 模型存向量（复用 vector_memory 的 embedding 管线）
2. _select_relevant_knowledge 改为 embedding 相似度匹配 + 关键词匹配加权融合
3. 保留关键词匹配作为 fallback（向量库不可用时降级）

效果："AI 客服"和"智能问答机器人"这种同义不同词的能被真正想起来。学习闭环从"碰巧命中关键词"变成"语义理解"。

---

优先级与依赖

2.25.1 自验前移 ──→ 2.25.2 验收标准 ──→ 2.25.3 能力画像
                                           │
2.25.4 规划批判 ────────────────────────────┤（并行）
                                           │
                              2.25.5 交接结构化（跟 V2.3 模板化顺手做）
                              2.25.6 知识检索升级（跟 V2.3 模板化顺手做）

• 前四个（自验 → 验收标准 → 画像 → 批判）一周内落地，合计能把一次通过率拉出肉眼可见的变化
• 后两个（交接 + 检索）跟 V2.3 模板化并行推进，改动面有重叠

诚实的天花板

这六张牌全打完，智能化大约 7.8-8.2。再往上：

分数	手段	代价
8.5+	部门内 writer-critic 双角色互搏、多方案生成择优 (self-consistency)	成本翻倍
9+	真实执行环境（headless 浏览器点击冒烟、pytest 沙箱真跑）+ 更强基座模型	已不是平台智能化，是 LLM 供应商的智能化

---

V2.3 — 模板化复用（3 天）

目标：成功项目变成可复用的模板，同类项目从"每次掷骰子"变"站在上次肩膀上"

2.3.1 项目存为模板（1 天）

新增 API：POST /api/v1/companies/{company_id}/projects/{project_id}/save-template

把成功项目的元结构存为模板（存 CompanyKnowledge 表或新建 CompanyProjectTemplate 表）：

{
  "template_name": "产品落地页生成",
  "source_project_id": "xxx",
  "company_config": {
    "departments": [
      {"name": "产品设计", "type": "product", "roles": ["产品经理", "UI设计师"]},
      {"name": "技术开发", "type": "engineering", "roles": ["前端开发", "后端开发"]},
      {"name": "市场策略", "type": "marketing", "roles": ["文案策划"]}
    ]
  },
  "ceo_plan_skeleton": {
    "analysis": "{{PRODUCT_NAME}} 的落地页项目...",
    "departments": [
      {"department_name": "产品设计", "goal": "设计 {{PRODUCT_NAME}} 落地页信息架构...", "deliverables": ["线框图", "设计稿说明"], "priority": 1, "dependencies": []},
      ...
    ]
  },
  "validation_checklist": {
    "产品设计": ["文档字数 ≥ 200", "含线框图描述"],
    "技术开发": ["HTML 冒烟通过", "JS 语法检查通过"],
    "市场策略": ["含目标用户画像", "含投放渠道建议"]
  }
}

前端：项目详情页加 "保存为模板" 按钮。

2.3.2 从模板创建项目（1 天）

新增 API：POST /api/v1/companies/{company_id}/execute/from-template

输入：template_id + variables（如 {"PRODUCT_NAME": "AI 客服系统"}）

流程：

1. 加载模板，用 variables 做模板变量替换
2. 预填 CEO 计划（跳过规划阶段，直接入参 ceo_plan——v2.1 入口收敛后已有此能力）
3. 调用 execute/async 进入正常执行流

前端：创建项目对话框加 "从模板" Tab，列出已有模板，选模板后填变量。

2.3.3 模板列表与管理（1 天）

API：GET /api/v1/companies/{company_id}/templates — 列表 + 分类 前端：CompanyBuilder 加 "模板市场" Tab（当前公司内），展示模板卡片：名称、来源项目、成功轮次、验证通过率、使用次数

---

V2.4 — 质量加固（3 天）

目标：代码债务收口 + 用户体验补齐

2.4.1 后端债务（1 天）

事项	做法
per-dept Session 隔离	orchestrator commit/update 改为临时 SessionLocal（与 _heartbeat 同模式）
__import__("time") 收口	文件顶部 import time as _time，全文替换
round_count 迁移	alembic: String(10) → Integer，默认 1
循环依赖加提示	触发时给各 dept 注入 "上游依赖未完成，基于假设数据工作"
_safe_name 加固	加 Windows 保留名过滤 (CON/PRN/NUL) + 超长截断

2.4.2 前端体验补齐（1.5 天）

事项	做法
项目对比真实化	对比抽屉：并排展示状态/轮次/成本/token/评分/交付物文件列表
时间轴回放	控制室加 scrubber，基于 rawEvents (seq 有序) 步进回放
重新执行按钮	项目卡片加 "以原目标重跑"，调 execute/async
列表分页	公司卡片列表 / 项目表 / 知识列表 统一分页

2.4.3 洞察升级（0.5 天）

insight_analyzer.py 加：

• 项目级时间序列（按日统计项目数/通过率/平均成本）
• 部门协作对排名（哪个部门-部门组合通过率最高）

---

V3.0 — 运行时上线（2-3 天）

目标：解除单 worker 锁死，为云端多项目并行执行铺路 前提：已验证闭环稳定运行 10+ 项目，确认方向后再投入

3.0.1 进程内 → Redis（1.5 天）

当前	改为
_RUNNING: Dict[str, Task]	Redis key company:task:{project_id} → JSON {pid, status, started_at}；task 句柄仍是进程内，但跨 worker 可知道"谁在跑"
_CONTROL: Dict[str, ProjectControl]	Redis pub/sub channel company:control:{project_id}，pause/cancel/approve 事件跨 worker 广播
_PROJECT_SEM	保留（仅控制本 worker 并发上限，不跨 worker）

关键设计：不在 Redis 里存 task 句柄（asyncio task 不能序列化）。Redis 只做控制信号通道。每个 worker 有自己的 _RUNNING dict 和信号量，通过 Redis pub/sub 接收跨 worker 的控制指令。

3.0.2 多 worker 安全机制（0.5 天）

• 启动时注册 worker_id 到 Redis
• 项目分配：execute/async 先 SETNX company:task:{pid} 抢锁，抢到才在本 worker spawn
• worker 宕机：company:task:{pid} 设 TTL 60s，task 内周期性刷新 TTL；TTL 过期 → 其他 worker 可接管（但需配合 project status 脏检测）
• 同一个 project 不会两个 worker 同时执行

3.0.3 告警与监控（0.5-1 天）

• 僵尸项目：ProjectSupervisor 加通知（webhook/飞书/邮件，复用现有调度模块的通知能力）
• worker 健康检查：/api/v1/health 加 worker 状态信息

---

优先级矩阵

                    高影响
                      │
        V2.2 验证闭环  │  V2.25 智能化提升
        V2.1 安全还债  │  V2.3 模板化
                      │
    ──────────────────┼──────────────────
                      │
        V2.4 质量加固  │  V3.0 运行时上线
                      │
                    低影响

        低投入 ←──────────→ 高投入

V2.1+V2.25 是"低投入高影响"象限（前四张牌一周内落地），V2.2 是高投入但也是后续一切的基础。V3.0 等到云端多项目并行成了瓶颈再投入。

---

里程碑与度量

版本	完成标志	度量指标
V2.1	所有 API 鉴权覆盖、XSS 治理、旧链路下线	0 个未鉴权端点、0 处裸 v-html
V2.2	机器验证报告注入评审 + 返工	首轮评分通过率（对比上线前基线）、平均返工轮次
V2.25	自验 gate + 验收标准 + 能力画像 + 规划批判	一次通过率提升幅度、验收标准覆盖率、自验拦截率
V2.3	模板存取 API + 前端入口	模板数、从模板创建的项目占比
V2.4	项目对比/回放可用、代码 debt 清零	重复代码行数、inline import 数
V3.0	多 worker 并行执行不互锁	单机 2 worker 各跑 1 项目无竞态

智能化得分演进

5.0 ─ V2.2 验证闭环 ──→ 6.5 ─ V2.25.1 自验前移 ──→ 7.2
                                  V2.25.2 验收标准  ──→ 7.5
                                  V2.25.3 能力画像  ──→ 7.6
                                  V2.25.4 规划批判  ──→ 7.8
                                  V2.25.5 交接结构  ──→ 7.9
                                  V2.25.6 检索升级  ──→ 8.0
                                                    （天花板 ~8.2，再往上需真实执行环境+更强模型）