# AI Support Current State

更新时间：2026-09-07

## Scope

当前仓库里真正成型的部分集中在 `services/ticket-manager` —— 一个面向 support case 的 control plane，负责接收 Jira case、通过 Dispatch Policy 执行 triage，并将 Lark 消息接入 Agent Gateway。

围绕它的横向支撑：

- `packages/sdk-go` —— 共享 SDK：API server / GORM / Jira client / Lark client / Logger / AWS Secrets Manager / config / 通用 utils。
- `packages/contracts/ticket-manager/openapi.yaml` —— ticket-manager HTTP API 的契约。
- `infra/images/agent-codex/project-seeds/` —— Agent Codex 镜像内置的 skills 来源：`ticket-manager/.agents/skills/builtin/` 提供项目级 skills（包括 `triage`、`workspace`），`__global__/skills/lark-cli/` 提供全局 Lark skills；Ticket Manager 通过 Agent Gateway 调用 Agent，不再运行 OpenCode。
- `apps/cli/ticket-manager/` —— workspace 管理 CLI 客户端。

## Current Architecture

当前是 **模块化单体**，不是多服务系统。

主链路：

- `Ticket ingest → persistent DispatchTrigger → triage Action → Ticket Manager Agent Service → Agent Gateway ProcessMessage / TaskEvent → DispatchContext`
- `Lark callback → Agent Service → Agent Gateway → task events / replies`
- `Workspace evidence → Ticket Manager Agent Service → Agent Gateway → curated timeline draft`
- `Docker / Kustomize / GitHub Actions → dev EKS deployment`

主要代码边界（落到目录）：

- HTTP handlers：`services/ticket-manager/internal/app/handlers/{agent,collaboration,dispatch,engineer,lark,task,ticket,workspace}/`
- 领域服务：`services/ticket-manager/internal/services/{agent,collaboration,dispatch,engineer,ingest,task,ticket,workspace}/`
- DI 装配：`services/ticket-manager/internal/deps/`（基于 `go.uber.org/dig`）
- 集成层：`services/ticket-manager/internal/integrations/agentgateway/`；Jira / Lark / DB / Secret 已经下沉到 `packages/sdk-go/infra/`
- 持久化模型：`services/ticket-manager/models/{collaboration,dispatch,engineer,task,ticket,workspace,base}/` + `services/ticket-manager/migrate/`
- 服务入口：`services/ticket-manager/cmd/ticket-manager/`（`--config` 加载 yaml；详见 service `README.md`）

## Implemented

### Persistence

GORM + MySQL（通过 `packages/sdk-go/infra/database`），由 `migrate.Migrator` 在启动时 AutoMigrate。当前覆盖的表：

- `tickets`
- `timeline_events`

旧 conversation 表不再由模型或 AutoMigrate 管理；已有部署中的历史表不会被启动迁移主动删除。

Ticket ID 是 `uint64` 自增主键。Ticket snapshot 不再保存 triage；最新 triage 结果投影在 `dispatch_contexts`，完整审计保存在 Dispatch Execution 的 Action Context。

### Configuration

走 yaml + ASM secret 三层合并（默认值 → `--config <file>` → `secret.rootConfigSecretName` 指向的 ASM 条目），代码入口 `services/ticket-manager/config/RootConfig`。Ticket Manager 不再启动 OpenCode 子进程，旧的 `clients.opencode`、`clients.aws.bedrock`、`clients.alicloud.bailian` 配置已移除；模型认证和 Agent 工具凭据配置在执行 Agent 的环境中，不通过任务 prompt 或 Gateway 请求传递。仓库里有：

- `services/ticket-manager/config.example.yaml` —— checked-in 模板
- `services/ticket-manager/config.local.yaml` —— gitignored，本地开发实际用的
- `infra/kustomize/envs/dev/ticket-manager/config.yaml` —— dev 环境配置，由 `configMapGenerator` 投递成带哈希的 ConfigMap

### Ticket Ingest

- `POST /api/v1/ticketmanager/tickets/{jiraIssueKey}`
- Ingest Service 先创建或刷新 case snapshot，再创建持久化 DispatchTrigger
- Dispatch Execution 按命中的 Policy 通过 Ticket Manager Agent Service 提交 Agent Gateway application message，并等待对应终态 Task Event；不再由 Ticket Service 启动独立 agent task
- Jira 客户端走 `packages/sdk-go/infra/jira/client`，配置里有 `dummy: true` 短路开关（开发常用）

### Dispatch Triage

- Ticket create 由 Ingest Service 创建持久化 `DispatchTrigger`。
- triage 是标准 Dispatch Action，输出 `issueType`、动态 Project `components`、`severity`、`projectLevel`、`language`、`reasoningSummary` 和 `confidenceScore`。
- triage 复用 `SendApplicationMessage` / `RegisterApplicationTaskEventHandler`，并通过 `services.dispatch.triage.agentID` 显式选择专用 Agent；第一次输出无效时，在同一个 Agent Gateway Session 中提交一次 repair message，不保留 OpenCode session 或兼容字段。
- `GET /api/v1/ticketmanager/dispatch/projects/{projectKey}/components` 返回当前 Jira/JSM Project 的候选 Component。
- triage 不更新 Jira、Ticket snapshot 或 timeline；live 结果投影到 `dispatch_contexts`，dry-run 结果保存在 Execution 审计中并回填当前 Execution 的运行时 DispatchContext，不写数据库上下文。
- Dispatch dry-run 可配置 `overwrite_data.now`。该业务时间随 Execution 持久化，并覆盖 Condition、Webhook 模板、Oncall 查询、Retrigger 计划和 Triage 生成时间；Execution/Trigger 审计时间继续使用真实时钟。

### Lark And Agent Gateway

- Workspace CLI：`apps/cli/ticket-manager`
- Lark 真实 callback：`POST /public/v1/ticketmanager/channels/lark/events`
  - URL verification、verification token 校验、encrypted payload 解密
  - Agent Service 处理私聊与群聊 `@bot` 策略
  - 消息转发到 Agent Gateway，由其管理 session 和 task
  - Agent task event 回调驱动 Lark 消息渲染与回复
- Lark 客户端已经搬到 `packages/sdk-go/infra/lark/client`（先前的 `internal/integrations/lark` 已被删除）

### Delivery

- `infra/images/ticket-manager/Dockerfile` —— slim runtime，只打包预先构建的 Ticket Manager 二进制；Agent 工具和 skills 由 `infra/images/agent-codex/Dockerfile` 打包。
- `infra/kustomize/base/ticket-manager` —— 公共 deployment / service / ingress
- `infra/kustomize/envs/dev/ticket-manager` —— dev 环境，含 `configMapGenerator` 引用 `config.yaml`；Pod 不再从 k8s Secret 注入任何凭据，运行时一切走 yaml + ASM 覆盖
- `.github/workflows/ci-ticket-manager.yml`、`.github/workflows/deploy-ticket-manager-dev.yml`

## Mock And Gaps

### Still Mocked / Hardcoded

- **Engineer pool**：`internal/services/engineer.ListEngineers` 返回硬编码三个工程师（alice / bob / carol），skillTags 用新前缀（`kernel-tikv` / `kernel-tidb` 等）。
- **Jira dummy mode**：`clients.jira.dummy: true` 时所有写操作走短路实现，便于无 Jira 凭据下跑 e2e。
- **Agent Service unavailable**：Agent task runner 返回明确的 unavailable 错误；Workspace 和 Dispatch triage 都通过 Agent Gateway 执行。

### Not Wired Into Runtime

- `internal/services/scheduler/reminder.go` —— ReminderService 已经实现并测试，但 `internal/deps/deps.go` 里没有装配，启动时不会跑。
- 没有 sync 调度作业（之前 doc 提到的 `internal/ingest/sync_job.go` 已不存在 —— 目录里只剩 `automation.go`）。

### Data Model Reserved But Not Closed-Loop

`tickets` 上这些字段已经存在但没有完整业务闭环：

- `primary_runtime_id`
- `latest_summary`
- `latest_workspace_url`
- `latest_change_url`
- `last_reminded_at`（依赖未启用的 ReminderService）

### Missing Product Surface

- board read model
- web UI / admin UI
- contract-generated SDKs（OpenAPI 已有，但还没接 codegen）
- 跨服务的 production-grade DB topology（目前仍是单库单实例形态）

## Practical Summary

当前最准确的定位仍然是：

> 一个已经打通核心链路的、agent-driven case management control plane prototype。

它已经具备：

- case ingest（Jira webhook）
- agent triage（含 type + module taxonomy）
- Agent Gateway-backed Lark adapter
- workspace 管理和 curated timeline
- yaml-driven 配置 + ASM secret 覆盖
- dev EKS 部署骨架（Dockerfile + kustomize + GitHub Actions）
- 基于 MySQL 的持久化层（migrate 自动跑）

它还没有完成：

- 真实 Jira side effect（dummy mode 仍是默认开发配置）
- 真实 engineer source（仍是硬编码 demo pool）
- reminder / 周期任务调度的运行时装配
- board / UI
- 完整 contract-first SDK 体系