devperf/AI-OKR-SYNC-PLAN.md

AI 驱动的 OKR 自动生成与同步

Context

DevPerf 已具备完整的 Git 同步管线（Gitea → gitCommits 表）和 OKR CRUD 系统。 当前 OKR 需人工创建，缺少与 Git 提交的联动。

目标：每次 Git 同步后，AI 分析新增 commit messages，按仓库维度：

• 新增 KR — commit 提到的功能点尚无对应 KR
• 更新进度 — commit 涉及已有 KR 的功能
• 标记完成 — commit 明确表示功能已完成

分析粒度：按仓库（每个仓库的新增 commits 做一次 AI 分析，prompt 中包含提交人信息） OKR 归属：commit 的提交人 = KR/Objective 的负责人（ownerId），通过 gitCommits.userId 关联 增量机制：每条 commit 只分析一次，分析后打标记，后续同步不再重复处理

---

第一阶段：Schema 变更

文件: backend/src/db/schema.ts

1a. 新增 ai_analyzed_commits 表（增量标记，防止重复分析）

aiAnalyzedCommits:
  id            varchar(50) PK
  commitSha     varchar(200) NOT NULL UNIQUE   -- 对应 gitCommits.sha
  batchId       varchar(50) NOT NULL           -- 一次 AI 调用的批次 ID
  createdAt     datetime NOT NULL

核心作用：每次同步后，只提取 gitCommits 中尚未出现在此表的 commit 送给 AI。分析完成后立即写入标记，确保该 commit 不会被重复处理。

1b. objectives 表加字段

• source varchar(50) default 'manual' — 值: 'manual' | 'ai_generated'

1c. keyResults 表加字段

• source varchar(50) default 'manual' — 值: 'manual' | 'ai_generated'
• sourceKey varchar(300) nullable — AI 分配的功能标识符（如 "user-login"），用于语义去重

1d. keyResults.status 扩展

现有 'active' | 'paused' | 'cancelled'，新增 'completed'。 字段类型是 varchar，无需改 DDL，只需让 recalcObjectiveProgress 正确处理 completed。

1e. syncLogs.source 枚举扩展

将 mysqlEnum('source', ['plane', 'gitea']) 改为 ['plane', 'gitea', 'ai_okr']。

---

第二阶段：AI 配置与 LLM 客户端（豆包 Doubao）

2a. 环境变量 (backend/src/config.ts)

新增：

AI_ENABLED: z.coerce.boolean().default(false),
AI_API_KEY: z.string().default(''),
AI_MODEL: z.string().default('doubao-seed-2-0-pro-260215'),
AI_BASE_URL: z.string().default('https://ark.cn-beijing.volces.com/api/v3'),

.env 示例：

AI_ENABLED=true
AI_API_KEY=846b6981-9954-4c58-bb39-63079393bdb8
AI_MODEL=doubao-seed-2-0-pro-260215
AI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3

2b. 新建 backend/src/services/llm-client.ts

使用豆包（火山引擎 Ark）API，原生 fetch 实现，零额外依赖。

豆包 API 调用格式：

// POST https://ark.cn-beijing.volces.com/api/v3/chat/completions
// Header: Authorization: Bearer {AI_API_KEY}
// Header: Content-Type: application/json

export async function callLLM(systemPrompt: string, userPrompt: string): Promise<string> {
  const url = `${config.AI_BASE_URL}/chat/completions`;

  const body = {
    model: config.AI_MODEL,           // "doubao-seed-2-0-pro-260215"
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: userPrompt }
    ],
    temperature: 0.3,                  // 低温度保证输出稳定
    response_format: { type: "json_object" }  // 强制 JSON 输出
  };

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${config.AI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(60000),  // 60s 超时
  });

  if (!response.ok) {
    throw new Error(`Doubao API error: ${response.status} ${await response.text()}`);
  }

  const data = await response.json();
  return data.choices[0].message.content;
}

要点：

• 豆包 Ark API 兼容 OpenAI /chat/completions 格式
• 使用 response_format: { type: "json_object" } 强制返回 JSON
• 超时 60s，失败重试 1 次（间隔 3s）
• temperature: 0.3 保证分析结果稳定一致

---

第三阶段：核心服务 — backend/src/services/okr-ai-sync.ts

整体流程

analyzeCommitsForOKR()
  │
  ├─ 1. gatherUnanalyzedCommits()
  │     SELECT gc.* FROM git_commits gc
  │     LEFT JOIN ai_analyzed_commits aac ON gc.sha = aac.commit_sha
  │     WHERE aac.id IS NULL
  │     → 按 repoName 分组（每个仓库一批）
  │
  ├─ 2. 遍历每个仓库的未分析 commits：
  │     a. 通过 projectRepos 找到该仓库关联的 projectId
  │     b. 获取该项目当前所有 Objectives + KRs（含 sourceKey）
  │     c. 构建 AI prompt（该仓库的新 commits，含每条 commit 的提交人信息 + 项目现有 OKR）
  │     d. 调用豆包 AI → 解析 JSON 响应
  │     e. 执行 AI 返回的 actions：
  │        - create_objective → 创建时 ownerId = commit 提交人的 userId（AI 返回 authorUserId）
  │        - create_kr → 先查 sourceKey 防重 → 不存在才创建，归属到对应提交人
  │        - update_progress → 更新 currentValue + 写 krLog
  │        - complete_kr → status='completed' + 写 krLog
  │     f. 重算 Objective progress
  │     g. 标记这批 commits 为已分析（写入 aiAnalyzedCommits）
  │
  └─ 3. 写入 syncLogs (source='ai_okr')

增量更新机制（核心）

第一次同步：
  gitCommits: [A, B, C, D, E]
  aiAnalyzedCommits: []
  → 未分析: [A, B, C, D, E] → 全部送 AI → 分析后标记 [A, B, C, D, E]

第二次同步（新增了 F, G）：
  gitCommits: [A, B, C, D, E, F, G]
  aiAnalyzedCommits: [A, B, C, D, E]
  → 未分析: [F, G] → 只送 F, G 给 AI → 分析后标记 [F, G]

第三次同步（无新增）：
  → 未分析: [] → 跳过，不调用 AI

AI Prompt 设计

System Prompt:

你是一个开发团队的 OKR 管理助手。你的任务是分析 git commit 记录，管理项目的 OKR（目标与关键成果）。

你需要分析提交记录，输出 JSON 格式的操作指令：

判断逻辑：
- commit 包含 "完成"、"done"、"finished"、"实现完毕" 等完成语义 → 对应 KR 标记完成
- commit 是 feat/feature 类型但未完成 → 更新对应 KR 进度（根据描述估算百分比）
- commit 涉及的功能在现有 KR 中不存在 → 创建新 KR（需同时提供时间节点）
- fix/refactor/chore/docs 类 commit → 只在涉及明确功能时才操作
- 不要为同一个功能创建重复的 KR，已有相同 sourceKey 的直接更新

新建 Objective 规则：
- 如果提交涉及的功能没有归属到任何已有 Objective → 可以创建新 Objective
- Objective 的 startDate 和 endDate 由你根据提交内容和功能复杂度判断
- period 格式为 "YYYY-Qn"（如 "2026-Q2"），根据 endDate 推算

新建 KR 规则：
- targetValue = 100, unit = "%"
- 根据 commit 语义估算 currentValue（初步实现=30, 基本完成=70, 完成=100）
- sourceKey 用小写英文短横线格式（如 "user-login", "payment-module"）
- title 用中文描述
- startDate 和 endDate 由你根据功能复杂度和提交时间判断

User Prompt 模板:

仓库：{{repoName}}
所属项目：{{projectName}}
当前日期：{{today}}

该项目已有的 OKR：
{{#each existingObjectives}}
Objective: id={{id}}, title="{{title}}", period={{period}}, 时间={{startDate}}~{{endDate}}, 进度={{progress}}%
  Key Results:
  {{#each keyResults}}
  - id: {{id}}, title: "{{title}}", sourceKey: "{{sourceKey}}", status: {{status}}, 进度: {{currentValue}}/{{targetValue}}, 时间: {{startDate}}~{{endDate}}
  {{/each}}
{{/each}}

{{如果没有已有 OKR: "该项目暂无 OKR 记录。"}}

该仓库的开发人员（commit 提交人 → 系统用户映射）：
{{#each authors}}
- userId: "{{userId}}", 姓名: {{displayName}}
{{/each}}

该仓库新增的提交记录（按时间排序，均为增量，之前的已处理过）：
{{#each commits}}
- [{{committedAt}}] 提交人: {{authorName}}(userId={{userId}}) {{sha前7位}}: {{message}} (+{{additions}}/-{{deletions}})
{{/each}}

请分析以上提交，返回 JSON。注意：每个 action 都必须带 ownerId 字段，值为提交人的 userId，表示该 OKR 归谁负责。
{
  "actions": [
    {
      "type": "create_objective",
      "ownerId": "提交人的userId",
      "title": "目标标题",
      "startDate": "YYYY-MM-DD",
      "endDate": "YYYY-MM-DD",
      "reasoning": "为什么要创建这个目标",
      "keyResults": [
        { "title": "...", "sourceKey": "...", "currentValue": number, "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD" }
      ]
    },
    {
      "type": "create_kr",
      "ownerId": "提交人的userId",
      "objectiveId": "已有目标的id",
      "title": "...",
      "sourceKey": "...",
      "currentValue": number,
      "startDate": "YYYY-MM-DD",
      "endDate": "YYYY-MM-DD",
      "reasoning": "..."
    },
    {
      "type": "update_progress",
      "krId": "已有KR的id",
      "newCurrentValue": number,
      "reasoning": "..."
    },
    {
      "type": "complete_kr",
      "krId": "已有KR的id",
      "reasoning": "..."
    }
  ],
  "summary": "一句话总结该仓库近期开发动态"
}
如果没有需要操作的内容，返回 {"actions": [], "summary": "..."}

防重复策略（三层保障）

层级	机制	说明
Commit 级	aiAnalyzedCommits 表	已分析的 SHA 打标记，下次同步时过滤掉，不再送给 AI
KR 级	sourceKey 唯一性检查	创建前查 DB，同 Objective 下同 sourceKey 只允许一条，重复则转为 update
Objective 级	项目下已有 OKR 传入 prompt	AI 看到完整上下文，避免建议创建重复目标

OKR 负责人归属

• commit 有 userId（通过 author-matching 映射到系统用户）
• AI prompt 中包含每条 commit 的提交人信息（userId + displayName）
• AI 返回 action 时必须携带 ownerId，即该 OKR 归哪个提交人负责
• 执行时：create_objective 的 ownerId = AI 指定的 userId，create_kr 同理
• 跳过 userId 为 null 的 commits（作者未映射到系统用户）

示例：仓库 rtc_backend 有张三、李四两个人提交代码

• 张三的 commit 涉及"用户登录" → AI 创建 KR 归属张三
• 李四的 commit 涉及"支付模块" → AI 创建 KR 归属李四
• 同一个 Objective 下可以有不同负责人的 KR

时间节点（由 AI 判断）

• 不再固定取当前季度，而是由 AI 根据以下信息决定：
  • commit 的提交时间
  • 功能的复杂度（从 commit 内容推断）
  • 已有 OKR 的时间范围（避免冲突）
• AI 返回的 startDate、endDate 直接写入 Objective 和 KR
• period 根据 endDate 自动推算（复用已有 dateToPeriod()）
• Objective 创建后，其日期范围由 AI 决定，后续也可由 AI 在新的分析中调整

完成判定

AI 返回 complete_kr action 时：

1. currentValue = targetValue（即 100）
2. status = 'completed'
3. 写 krLog：action='completed', detail='AI 根据 commit {sha} 判定完成：{reasoning}'
4. recalcObjectiveProgress() 时 completed 的 KR 按 100% 计入

---

第四阶段：集成到同步流程

4a. 修改 backend/src/sync/scheduler.ts

import { analyzeCommitsForOKR } from '../services/okr-ai-sync';

// 在 syncGitea() 之后调用
giteaJob = new Cron('0 2,19 * * *', async () => {
  await syncGitea();
  if (config.AI_ENABLED) {
    console.info('[SCHEDULER] AI OKR 分析开始...');
    await analyzeCommitsForOKR().catch(e =>
      console.error('[SCHEDULER] AI OKR analysis failed:', e)
    );
  }
});

4b. 新增 API 端点 (backend/src/routes/okr.ts)

方法	路径	说明
POST	/api/okr/ai-analyze	手动触发 AI 分析（admin/manager）
POST	/api/okr/ai-analyze/preview	预览模式：返回 AI 建议但不执行

4c. 修改 backend/src/services/okr.ts

• 导出 dateToPeriod() 函数供 okr-ai-sync 使用
• recalcObjectiveProgress() 增加对 status === 'completed' 的处理（按 100% 计入进度）

---

第五阶段：DB 迁移

新增迁移文件 backend/drizzle/0002_add_ai_okr_fields.sql：

-- 新表：增量标记（已分析过的 commit 不再重复处理）
CREATE TABLE ai_analyzed_commits (
  id VARCHAR(50) PRIMARY KEY,
  commit_sha VARCHAR(200) NOT NULL,
  batch_id VARCHAR(50) NOT NULL,
  created_at DATETIME NOT NULL,
  UNIQUE INDEX uniq_analyzed_sha (commit_sha)
);

-- objectives 加字段
ALTER TABLE objectives ADD COLUMN source VARCHAR(50) DEFAULT 'manual';

-- key_results 加字段
ALTER TABLE key_results ADD COLUMN source VARCHAR(50) DEFAULT 'manual';
ALTER TABLE key_results ADD COLUMN source_key VARCHAR(300) NULL;

-- syncLogs source 枚举扩展
ALTER TABLE sync_logs MODIFY COLUMN source ENUM('plane', 'gitea', 'ai_okr') NOT NULL;

---

关键文件清单

文件	操作	说明
backend/src/db/schema.ts	修改	新表 + 新字段
backend/src/config.ts	修改	豆包 AI 环境变量
backend/src/services/llm-client.ts	新建	豆包 API 调用封装
backend/src/services/okr-ai-sync.ts	新建	核心 AI 分析 + 增量更新逻辑
backend/src/services/okr.ts	修改	导出 dateToPeriod, completed 状态处理
backend/src/sync/scheduler.ts	修改	同步后触发 AI 分析
backend/src/routes/okr.ts	修改	新增手动触发端点
backend/drizzle/0002_*.sql	新建	DB 迁移

---

实施顺序

1. Schema 变更 + 迁移文件（第一、五阶段）
2. config.ts 加豆包 AI 环境变量（第二阶段 2a）
3. llm-client.ts — 豆包 API 封装（第二阶段 2b）
4. okr.ts 小改（导出 dateToPeriod + completed 处理）
5. okr-ai-sync.ts 核心服务（第三阶段）
6. scheduler.ts 集成 + 新 API 端点（第四阶段）
7. 端到端测试

---

验证方案

1. 配置 .env：AI_ENABLED=true，AI_API_KEY=...，AI_MODEL=doubao-seed-2-0-pro-260215
2. 确保数据库中已有项目、用户、项目-仓库绑定、git commits 数据
3. 调用 POST /api/okr/ai-analyze/preview 查看 AI 返回的 actions（不写库）
4. 确认 actions 合理后，调用 POST /api/okr/ai-analyze 执行
5. 通过 GET /api/okr 验证 OKR 数据已生成，时间节点由 AI 合理设定
6. 再次调用 POST /api/okr/ai-analyze，确认不会重复生成（增量标记生效）
7. 手动触发 Git 同步拉到新 commits，再次分析，确认只处理新增 commits
8. 检查 krLogs 中有 AI 操作记录
9. 前端 OKR 页面查看显示是否正常

---

错误处理

场景	处理
AI_ENABLED=false 或 API key 为空	静默跳过，不影响 Git 同步
豆包 API 返回非 JSON	尝试用正则提取 ```json 块，失败则记 syncLogs error
豆包 API 超时（60s）	记错误日志，commits 保持"未分析"状态，下次同步重试
AI 建议更新不存在的 KR	跳过该 action，记 warning
AI 建议创建重复 sourceKey 的 KR	转为 update_progress
commit 的 repo 没有绑定到任何项目	跳过该仓库的分析
某个仓库无新增 commits	跳过，不调用 AI