CodeEntire 开放接口 | 帮助文档

# CodeEntire 开放接口

Checkpoint 是 CodeEntire 为 AI 编码会话（Claude Code、Cursor 等 Agent）沉淀的提交级记录，每个 Checkpoint 对应一次 commit，关联该次提交涉及的所有 AI 会话（Session）及其统计数据。本节接口用于检索项目下的 Checkpoint 列表、获取单个 Checkpoint 详情、获取完整会话 Transcript，以及查询统计数据（项目下 commit 的 AI 生成率、用户维度的统计概览）。

# 通用说明

Checkpoint 系列接口的统一路径前缀为：

/api/entire/v3/projects/:id

参数 id 为项目 ID 或项目全路径 project_full_path。如果使用项目全路径，需确保已编码，例如 /api/entire/v3/projects/tencent/code --> /api/entire/v3/projects/tencent%2Fcode（/ 编码为 %2F）。

用户维度的统计接口不属于项目，路径前缀为 /api/entire/v3/user。

注意：

所有接口均需登录认证。项目维度接口仅能访问当前用户有权限的项目，用户维度接口的权限规则见对应接口说明。
所有时间字段均为 UTC 时区。
checkpointId 即该次提交的 Git commit SHA。
「获取单个 Checkpoint」「获取 Checkpoint Transcript」两个接口结果均有 300 秒服务端缓存。

# 搜索 Checkpoint 列表

分页搜索指定项目下的 Checkpoint 列表，支持关键词模糊匹配与排序。

GET /api/entire/v3/projects/:id/checkpoints/search

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
search	string（可选）	搜索关键词，按标题等字段模糊匹配
sort	string（可选）	排序字段与方向，如 `created_at desc`。可用字段取决于数据库列名（如 `created_at`、`committed_at` 等），缺省为 `created_at desc`
page	integer（可选）	页码，缺省为 1
per_page	integer（可选）	每页大小，缺省为 20

返回值：

{
    "pageNum": 1,
    "pageSize": 20,
    "total": 1,
    "pages": 1,
    "list": [
        {
            "id": 1001,
            "projectId": 12345,
            "checkpointId": "abc123def456",
            "title": "feat: add login module",
            "authorName": "zhangsan",
            "authorEmail": "zhangsan@example.com",
            "branch": "main",
            "parentCommitId": "a1b2c3d4e5f6",
            "sessionCount": 3,
            "filesChangedCount": 8,
            "agents": ["Claude Code", "Cursor"],
            "inputTokens": 15200,
            "outputTokens": 8300,
            "apiCallCount": 12,
            "agentLines": 156,
            "stepCount": 5,
            "committedLines": 230,
            "committedDate": "2026-05-15T00:00:00.000+0000",
            "committedAt": "2026-05-15T10:32:15.000+0000",
            "createdAt": "2026-05-15T10:35:00.000+0000",
            "updatedAt": "2026-05-15T10:35:00.000+0000"
        }
    ]
}

说明：分页字段由 PageHelper 分页组件生成，list 内元素结构见下方数据模型 Checkpoint。

# 获取单个 Checkpoint

根据 checkpointId 获取指定 Checkpoint 的详细信息。

GET /api/entire/v3/projects/:id/checkpoint/:checkpointId

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
checkpointId	string	Checkpoint 唯一标识（commit SHA）

返回值：

{
    "id": 1001,
    "projectId": 12345,
    "checkpointId": "abc123def456",
    "title": "feat: add login module",
    "authorName": "zhangsan",
    "authorEmail": "zhangsan@example.com",
    "branch": "main",
    "parentCommitId": "a1b2c3d4e5f6",
    "sessionCount": 3,
    "filesChangedCount": 8,
    "agents": ["Claude Code"],
    "inputTokens": 15200,
    "outputTokens": 8300,
    "apiCallCount": 12,
    "agentLines": 156,
    "stepCount": 5,
    "committedLines": 230,
    "committedDate": "2026-05-15T00:00:00.000+0000",
    "committedAt": "2026-05-15T10:32:15.000+0000",
    "createdAt": "2026-05-15T10:35:00.000+0000",
    "updatedAt": "2026-05-15T10:35:00.000+0000"
}

字段结构见下方数据模型 Checkpoint；若不存在返回 null。

# 获取 Checkpoint Transcript

获取指定 Checkpoint 的完整会话 Transcript，包含 Checkpoint 概要信息、关联的所有 Session（含逐条 Event）及涉及的提交点列表。返回内容会根据当前用户的会话可见性设置做过滤，不可见的 Session 不会出现在结果中。

GET /api/entire/v3/projects/:id/checkpoint/:checkpointId/transcript

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
checkpointId	string	Checkpoint 唯一标识

返回值：

{
    "checkpoint": {
        "id": 1001,
        "projectId": 12345,
        "checkpointId": "abc123def456",
        "title": "feat: add login module",
        "authorName": "zhangsan",
        "authorEmail": "zhangsan@example.com",
        "branch": "main",
        "sessionCount": 2,
        "agents": ["Claude Code"],
        "committedAt": "2026-05-15T10:32:15.000+0000"
    },
    "sessions": [
        {
            "sessionId": "sess_001",
            "agent": "Claude Code",
            "events": [
                {
                    "id": "evt_001",
                    "role": "user",
                    "content": "帮我实现登录模块",
                    "type": "text",
                    "toolCall": null,
                    "timestamp": "2026-05-15T10:20:00.000+0000",
                    "commit": null
                }
            ],
            "inputTokens": 8000,
            "outputTokens": 4200,
            "apiCallCount": 6,
            "agentLines": 80,
            "humanAdded": 12,
            "humanModified": 5,
            "humanRemoved": 3,
            "committedLines": 120,
            "calculatedAt": "2026-05-15T10:33:00.000+0000",
            "stepCount": 3,
            "visible": true,
            "authorUsername": "zhangsan"
        }
    ],
    "commits": [
        {
            "checkpointId": "abc123def456",
            "commitId": "abc123def456",
            "title": "feat: add login module",
            "committedAt": "2026-05-15T10:32:15.000+0000",
            "current": true
        }
    ],
    "message": null
}

字段结构见下方数据模型 Transcript；若不存在返回 null。

# 批量查询 Commit AI 生成率

批量查询指定项目下一组 commit 的 AI 代码生成率统计。通过 commit ID 反查关联的 Checkpoint 记录，聚合 AI 生成行数与提交总行数，计算 AI 生成率。

POST /api/entire/v3/projects/:id/commits/agent_rate

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path（路径变量）

请求体：

{
    "ids": ["abc123def456", "789ghi012jkl"]
}

字段	类型	描述
ids	string[]	commit ID 列表，最多 100 个。请求体可省略或为空，此时返回空数组

返回值：

[
    {
        "commitId": "abc123def456",
        "checkpointCount": 1,
        "agentLines": 120,
        "committedLines": 200,
        "agentRate": 0.6
    },
    {
        "commitId": "789ghi012jkl",
        "checkpointCount": 0,
        "agentLines": 0,
        "committedLines": 0,
        "agentRate": 0.0
    }
]

字段结构见下方数据模型 CommitAgentRate。

说明：

响应按请求中 ids 的顺序返回，重复的 commit ID 会去重（仅保留首次出现的位置）。
没有关联 Checkpoint 的 commit（如 CodeEntire 启用前的历史提交、非 AI 编码产生的提交）返回全 0 而非 404。调用方可通过 checkpointCount 区分：checkpointCount = 0 表示该 commit 无 AI 参与记录。
ids 数量超过 100 时返回 400 错误。
agentRate 的计算口径：仅统计 committedLines > 0 的 Checkpoint 行数，与项目概览页的聚合口径一致。当一个 commit 关联多个 Checkpoint 时，行数按加权汇总（非简单平均）。

# 批量查询用户统计概览

批量查询一组用户最近 7 天（含今天）的 CodeEntire 统计概览，口径与 CodeEntire 页面上的个人统计概览一致。

GET /api/entire/v3/user/statistics/overview

参数：

参数	类型	描述
usernames	string（可选）	要查询的用户名，多个用英文逗号分隔，最多 20 个。不传时只查询当前用户

示例：

GET /api/entire/v3/user/statistics/overview?usernames=zhangsan,lisi,wangwu,not_exist

返回值：

{
    "stats": [
        {
            "userId": 10001,
            "username": "zhangsan",
            "checkpointCount": 12,
            "commitCount": 30,
            "projectCount": 3,
            "aiSessionCount": 18,
            "avgStepsPerCheckpoint": 6.5,
            "avgAgentPercentage": 42.37,
            "agentDistribution": [
                {
                    "agentName": "Claude Code",
                    "count": 9,
                    "percentage": 75.0
                },
                {
                    "agentName": "Cursor",
                    "count": 3,
                    "percentage": 25.0
                }
            ]
        }
    ],
    "denied": ["wangwu"],
    "notFound": ["not_exist"]
}

字段结构见下方数据模型 UserStatsResult。

权限规则：

当前用户始终可以查询自己的数据。
查询其他用户时，当前用户必须是管理岗，且目标用户的主岗组织属于当前用户负责的组织（含下级组织，例如中心负责人可以查询中心下所有组的成员）。
目标用户必须为在职或试用期员工，离职员工和 AD 账号不可查询。
普通员工只能查询自己，传入的其他用户名都会放入 denied。

说明：

只返回有权限用户的统计。无权限的用户名放入 denied，不存在的用户名放入 notFound，请求本身不会因此失败。
stats 按请求中 usernames 的顺序返回。用户名匹配不区分大小写，重复的用户名（含仅大小写不同的）会去重。
usernames 数量超过 20 时返回 400 错误。
统计窗口固定为最近 7 天（含今天），不支持自定义时间段。数据由服务端预聚合，用户首次被查询且尚无统计数据时，会同步计算一次，该次请求耗时会略长。

# 数据模型

# Checkpoint

字段	类型	说明
id	long	主键
projectId	long	项目 ID
checkpointId	string	Checkpoint 唯一标识（commit SHA）
title	string	提交标题
authorName	string	作者名
authorEmail	string	作者邮箱
branch	string	所属业务分支（来源 metadata.json 的 branch 字段，可能为空）
parentCommitId	string	父 commit SHA（首次提交无 parent 时为空）
sessionCount	int	关联会话数
filesChangedCount	int	文件变更数
agents	string[]	使用的 AI Agent 列表
inputTokens	int	输入 token 总数
outputTokens	int	输出 token 总数
apiCallCount	int	API 调用次数
agentLines	int	AI 生成代码行数
stepCount	int	AI 对话步数（assistant 回复中 text 类型 content 条数之和）
committedLines	int	提交总代码行数
committedDate	datetime	提交日期（UTC 0 点，仅用于按天分组统计）
committedAt	datetime	提交时间（UTC 完整时间戳，用于统计窗口筛选）
createdAt	datetime	记录创建时间
updatedAt	datetime	记录更新时间

# Transcript

字段	类型	说明
checkpoint	Checkpoint	关联的 Checkpoint 概要信息
sessions	Session[]	会话列表（已按当前用户可见性过滤）
commits	CommitPoint[]	该 Transcript 涉及的提交点列表
message	string	附加提示信息，正常情况下为空

# Session

字段	类型	说明
sessionId	string	会话 ID
agent	string	使用的 Agent 名称
events	Event[]	事件（逐条对话记录）列表
inputTokens	long	输入 token 数
outputTokens	long	输出 token 数
apiCallCount	int	API 调用数
agentLines	int	AI 生成代码行数
humanAdded	int	人工新增行数
humanModified	int	人工修改行数
humanRemoved	int	人工删除行数
committedLines	int	该会话对应的提交总行数（对应元数据 committed_lines）
calculatedAt	datetime	统计计算时间
stepCount	int	对话步数
visible	boolean	该会话对当前用户是否可见
authorUsername	string	会话作者用户名

# Event

字段	类型	说明
id	string	事件 ID
role	string	角色，如 `user`、`assistant`、`commit` 等
content	string	事件内容（文本消息内容，工具调用等场景可能为空）
type	string	事件类型
toolCall	ToolCall	工具调用详情，非工具调用事件为空
timestamp	datetime	事件发生时间
commit	CommitPoint	当 role 为 `commit` 时关联的提交点信息，其余情况为空

# CommitPoint

字段	类型	说明
checkpointId	string	关联的 Checkpoint 唯一标识
commitId	string	提交 commit SHA
title	string	提交标题
committedAt	datetime	提交时间
current	boolean	是否为当前查询的 Checkpoint 对应的提交点

# CommitAgentRate

字段	类型	说明
commitId	string	commit ID
checkpointCount	int	该 commit 关联的 Checkpoint 数量。为 0 表示该 commit 无 AI 参与记录（未被 CodeEntire 追踪）
agentLines	long	AI 生成代码行数（仅统计 committedLines > 0 的 Checkpoint，与统计口径一致）
committedLines	long	提交总代码行数
agentRate	double	AI 生成率，取值 0~1，保留 4 位小数。committedLines 为 0 时返回 0

# UserStatsResult

字段	类型	说明
stats	UserStat[]	有权限查询的用户的统计，按请求顺序排列
denied	string[]	无权限查询的用户名
notFound	string[]	不存在的用户名

# UserStat

统计窗口均为最近 7 天（含今天）。

字段	类型	说明
userId	long	用户 ID
username	string	用户名
checkpointCount	int	Checkpoint 数
commitCount	int	提交数（用户在所有参与项目中作为作者的 commit 总数，已剔除 CodeEntire 自动产生的 checkpoint 提交）
projectCount	int	参与的项目数
aiSessionCount	int	AI 会话次数（Checkpoint 内 Session 总数）
avgStepsPerCheckpoint	double	平均每个 Checkpoint 的 AI 对话步数，保留 2 位小数
avgAgentPercentage	double	AI 生成代码百分比，取值 0~100，保留 2 位小数，按行数计算：AI 生成行数之和 / 提交总行数之和 × 100
agentDistribution	AgentStat[]	使用的 AI Agent 分布

无统计数据的用户各数值字段为 0，agentDistribution 为空数组。

# AgentStat

字段	类型	说明
agentName	string	Agent 名称
count	int	使用该 Agent 的 Checkpoint 数
percentage	double	占比，取值 0~100

# 备注

所有时间字段均为 UTC 时区。
checkpointId 为 Git commit SHA。
「获取单个 Checkpoint」「获取 Checkpoint Transcript」均有 300 秒服务端缓存；缓存 key 不包含用户维度，缓存中始终存放未经可见性过滤的完整数据，接口返回前才按当前用户实时过滤。
「搜索 Checkpoint 列表」排序支持的字段取决于数据库表列名（如 created_at、committed_at 等）。
「批量查询 Commit AI 生成率」的 ids 上限为 100，超限返回 400 错误。请求体可省略（@RequestBody(required = false)），此时返回空数组。
「批量查询用户统计概览」的 usernames 上限为 20，超限返回 400 错误。无权限和不存在的用户名分别放在 denied、notFound 中返回，不会导致整个请求失败。

CodeEntire 开放接口

← CodeWiki 开放接口 WebHooks 配置 →