CodeWiki 开放接口 | 帮助文档

# CodeWiki 开放接口

CodeWiki 是工蜂基于 AI 对项目代码进行深度分析后，自动生成的结构化代码知识文档，包含「代码摘要」与「项目 Wiki」两部分。本节接口用于通过开放 API 开通/更新 Wiki、检索 Wiki 内容、查询生成任务、管理模块与自动追踪配置。

# 通用说明

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

/api/codewiki/v3/projects/:id

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

注意：

CodeWiki 数据来源于离线的代码分析任务，生成接口为异步接口，调用后立即返回任务标识，需再通过任务列表接口查询进度。
Git 项目与 SVN 项目的参数语义不同：Git 项目以 branch 定位，SVN 项目无分支概念，以 doc_module_id（模块）定位。
doc_module_id 指 CodeWiki 模块 ID，可通过「查询 CodeWiki 模块列表」接口获取。缺省时取项目的仓库级模块。

# 开通 / 手动更新项目 CodeWiki

开通项目 CodeWiki 或触发一次手动更新。该接口为异步接口，返回任务标识后由后台执行分析。

POST /api/codewiki/v3/projects/:id/generate

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
branch	string	分支名。Git 项目必填；SVN 项目会忽略该参数
doc_module_id	integer	CodeWiki 模块 ID。SVN 项目必填；Git 项目可选，缺省取仓库级模块
wiki_update_mode	string（可选）	更新模式，取值 `FULL`（全量重建）、`INCREMENTAL`（增量更新）。缺省由服务端自行判定

返回值：

{
    "task_id": 10086,
    "doc_module_id": 65811,
    "status": "PENDING",
    "message": "任务已提交"
}

# 检索 CodeWiki

检索项目的 CodeWiki 内容，默认在代码摘要与 CodeWiki 文档中全量检索。传入 doc_module_id 可限定在某个模块内检索。

GET /api/codewiki/v3/projects/:id/search

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
query	string	检索关键词或自然语言描述
branch	string	分支名。Git 项目缺省取默认分支；SVN 项目忽略该参数
query_type	string（可选）	检索类型，仅支持 `gongfeng_code`（代码摘要）/ `gongfeng_iwiki`（Wiki 文档），缺省为全量检索
doc_module_id	integer（可选）	限定在指定模块内检索

返回值：

{
    "code": 0,
    "message": "success",
    "trace_id": "f001acd3baddfb1d8cee97ca2d621568",
    "data": [
        {
            "chunk_title": "CodeWikiTest.java",
            "chunk_content": "[CodeWikiTest.java]\nLocation: plugins/busines CodeWikiTest 的类，该类继承自 BaseModel 并实现 Serializable 接口。它作为 AI 工作流规则模板的实体，用于承载规则的元数据，包括模板类型、状态机、字段、Agent 和模型等。该类提供了将模板翻译为规则实例（translate）、判断自动生效条件（isEligible）以及运行时规则实例化（toRuntimeRule）的核心能力。其核心成员包括 id（唯一标识）、code（模板代码）、type（模板类型）、ruleFields（规则字段列表）和 defaultAgentId（默认 Agent ID），共 20 个成员。\n\n ",
            "href": "plugins/business-plugin-test/src/main/java/com/tencent/code/web/model/aiflow/CodeWikiTest.java#",
            "doc_file_path": "plugins/business-plugin-test/src/main/java/com/tencent/code/web/model/aiflow/CodeWikiTest.java#",
            "doc_id": "2369565872",
            "chunk_index": 1,
            "source": "code"
        },
        {
            "chunk_title": "AiFlowEvent",
            "chunk_content": "[CodeWikiTest2]\nLocation: plugins/business-plugin/CodeWikiTest.java#AiFlowEvent\n\nCode:\n```java\n \npu``\nDescription:\n    实体名称: `AiFlowEvent`\nAiFlowEvent是AI流程事件接口，继承Serializable，提供getEventId()获取事件ID、getTaskId()获取任务ID、getPayload()获取载荷Map的方法，被多个构建器用于处理任务通知和规则匹配\n\n ",
            "href": "plugins/business-plugin-test/src/main/java/com/tencent/code/web/model/aiflow/event/CodeWikiTest.java#AiFlowEvent",
            "doc_file_path": "plugins/business-test/src/main/java/com/tencent/code/web/model/aiflow/event/CodeWikiTest.java#AiFlowEvent",
            "doc_id": "2368989774",
            "chunk_index": 1,
            "source": "code"
        }
    ]
}

若项目未开通 CodeWiki 或指定分支尚未完成代码分析，返回：

{
    "code": 404,
    "message": "未找到已完成的分析任务，请确认该分支/commit已完成代码分析",
    "trace_id": "f001acd3baddfb1d8cee97ca2d621568"
}

此时可调用「开通 / 手动更新项目 CodeWiki」接口触发分析，或前往项目的 CodeWiki 页面开通。

# 查询代码引用

基于 CodeWiki 的代码分析结果，查询代码实体之间的引用关系和调用链。

GET /api/codewiki/v3/projects/:id/code_references

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
branch	string（可选）	分支名，与 `commit` 至少传一个
commit	string（可选）	commit SHA，与 `branch` 至少传一个。优先使用 commit 精确匹配
file_path	string	代码实体所在文件路径（相对于仓库根目录）
line_number	integer（可选）	代码实体所在行号
name	string	代码实体名称，如 `createUser`（函数名）、`userCount`（全局变量）、`UserService`（类名）
doc_module_id	integer（可选）	模块 ID，限定在某个模块内查询。不传则默认使用仓库级模块（整仓）
depth_up	integer（可选）	向上展开层数（谁引用了我），范围 0~5，默认 1。为0时表示不查询
depth_down	integer（可选）	向下展开层数（我引用了谁），范围 0~5，默认 3。为0时表示不查询

返回值：

{
    "code": 0,
    "message": "success",
    "trace_id": "32d0858fd74e4966a45ba3927262d6eb.91.17872145939435781",
    "data": {
        "target": {  // 被查询的代码实体自身信息
            "type": "METHOD",
            "name": "createUser",
            "signature": "createUser(String name, String email)",
            "file": {
                "path": "src/main/java/com/example/service/UserService.java",
                "start_line": 22
            }
        },
        "up": {  // 向上引用链（谁引用了我），depth_up=0 时不返回该字段
            "depth": 2,  // 实际展开的最大深度
            "tree": [  // 树形结构，节点的 references 字段包含更深层引用，递归展开至指定层数
                {
                    "type": "METHOD",
                    "name": "handleCreateUser",
                    "signature": "handleCreateUser(String name, String email)",
                    "file": {
                        "path": "src/main/java/com/example/controller/UserController.java",
                        "start_line": 21
                    },
                    "depth": 1,
                    "references": [
                        {
                            "type": "METHOD",
                            "name": "registerUser",
                            "signature": "registerUser(String name, String email)",
                            "file": {
                                "path": "src/main/java/com/example/app/UserApplication.java",
                                "start_line": 20
                            },
                            "depth": 2,
                            "references": []
                        }
                    ]
                }
            ],
            "total_nodes": 2  // 该方向的节点总数
        },
        "down": {  // 向下引用链（我引用了谁），depth_down=0 时不返回该字段
            "depth": 2,
            "tree": [
                {
                    "type": "METHOD",
                    "name": "User",
                    "signature": "User(Long id, String name, String email)",
                    "file": {
                        "path": "src/main/java/com/example/model/User.java",
                        "start_line": 15
                    },
                    "depth": 1,
                    "references": []
                },
                {
                    "type": "CLASS",
                    "name": "User",
                    "file": {
                        "path": "src/main/java/com/example/model/User.java",
                        "start_line": 7
                    },
                    "depth": 1,
                    "references": []
                },
                {
                    "type": "METHOD",
                    "name": "save",
                    "signature": "save(User user)",
                    "file": {
                        "path": "src/main/java/com/example/repository/UserRepository.java",
                        "start_line": 18
                    },
                    "depth": 1,
                    "references": [
                        {
                            "type": "METHOD",
                            "name": "insert",
                            "signature": "insert(User user)",
                            "file": {
                                "path": "src/main/java/com/example/store/UserDataStore.java",
                                "start_line": 17
                            },
                            "depth": 2,
                            "references": []
                        },
                        {
                            "type": "CLASS",
                            "name": "User",
                            "file": {
                                "path": "src/main/java/com/example/model/User.java",
                                "start_line": 7
                            },
                            "depth": 2,
                            "references": []
                        }
                    ]
                }
            ],
            "total_nodes": 5
        }
    }
}

若项目未开通 CodeWiki 或指定分支/commit 尚未完成代码分析，返回：

{
    "code": 404,
    "message": "未找到已完成的分析任务，请确认该分支/commit已完成代码分析",
    "trace_id": "32d0858fd74e4966a45ba3927262d6eb.91.17872145939435781"
}

此时可调用「开通 / 手动更新项目 CodeWiki」接口触发分析，或前往项目的 CodeWiki 页面开通。

# 查询 CodeWiki 任务列表

搜索项目的 CodeWiki 生成任务列表，可按完成状态过滤。

GET /api/codewiki/v3/projects/:id/tasks

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
finished	boolean（可选）	是否只看已结束任务。`true`（默认）返回已完成/已取消/未找到；`false` 返回排队中/执行中/失败/超限
search	string（可选）	按关键词模糊搜索任务
page	integer（可选）	指定页码（默认 1）
per_page	integer（可选）	每页大小（默认 20）

返回值：

[
    {
        "tenantId": 1,
        "id": 145024,
        "docModuleId": 65811,
        "docAnalysisId": 166589,
        "projectId": 1228252,
        "forkRootId": 1228252,
        "requestId": "doc-code/code-business/code-business-test-test:65811-d41e390d",
        "username": "tgit",
        "type": "rerun",
        "data": "{\"fields\":\"[\\\"/plugins/business-plugin-test/\\\"]\"}",
        "branch": "feature/release-code-document-test",
        "sourceCommit": "INCR_SYNC_SOURCE",
        "targetCommit": "0f357420866665b88c3663d4832d98962aa43923",
        "status": "cancel",
        "error": "canceled by user",
        "host": null,
        "priority": 20,
        "pkgTotal": null,
        "fileTotal": null,
        "objTotal": null,
        "createdAt": 1785911942000,
        "updatedAt": 1785911957000,
        "lastOperator": "waynezwyu",
        "summaryRuleVersion": null,
        "closedTask": true,
        "fullSync": false,
        "completedTask": false,
        "normalTak": false,
        "highPriorityTask": false
    },
    {
        "tenantId": 1,
        "id": 143813,
        "docModuleId": 65811,
        "docAnalysisId": 166589,
        "projectId": 1228252,
        "forkRootId": 1228252,
        "requestId": "doc-code/code-business/code-business-test:65811-cc7438a6",
        "username": "tgittest",
        "type": "activate",
        "data": "{\"fields\":\"[\\\"/plugins/business-plugin-test/\\\"]\"}",
        "branch": "feature/release-code-document",
        "sourceCommit": "1ca4bc0709ba9f824c8e84cdf9def7f5ef93d86a",
        "targetCommit": "1ca4bc0709ba9f824c8e84cdf9def7f5ef93d86a",
        "status": "completed",
        "error": "",
        "host": "business-plugin-agent-task-557d77ff8b-xqzcf",
        "priority": 5,
        "pkgTotal": 213,
        "fileTotal": 894,
        "objTotal": 11519,
        "createdAt": 1785814542000,
        "updatedAt": 1785876306000,
        "lastOperator": "kylezhao",
        "summaryRuleVersion": -1,
        "closedTask": true,
        "fullSync": true,
        "completedTask": true,
        "normalTak": true,
        "highPriorityTask": false
    }
]

任务状态说明：

PENDING: 排队中
RUNNING: 执行中
COMPLETED: 已完成
CANCEL: 已取消
ERROR: 执行失败
TOO_BIG: 实体数量过大，默认会调度离线任务处理，无需重复提交，请稍后通过本接口查询最终状态
NOT_FOUND: 未找到可分析内容

# 查询 CodeWiki 模块列表

列出项目的 CodeWiki 模块。默认仓库级模块优先，其次按更新时间倒序。

GET /api/codewiki/v3/projects/:id/modules

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
enabled	boolean（可选）	按启用状态过滤，缺省不过滤
search	string（可选）	按模块名称模糊搜索
page	integer（可选）	指定页码（默认 1）
per_page	integer（可选）	每页大小（默认 20）

返回值：

[
    {
        "id": 65811,
        "project_id": 10730180,
        "name": "code-business-app",
        "type": "REPO",
        "enabled": true,
        "created_at": "2026-07-01T14:20:00+0800",
        "updated_at": "2026-08-05T10:38:01+0800"
    },
    {
        "id": 65812,
        "project_id": 10730180,
        "name": "business-plugin-agent",
        "type": "NORMAL",
        "enabled": true,
        "created_at": "2026-07-10T11:02:00+0800",
        "updated_at": "2026-08-02T18:30:00+0800"
    }
]

说明：type 为 REPO 表示仓库级模块（覆盖整个仓库），NORMAL 表示普通模块（覆盖仓库的部分目录）。

# 新建 CodeWiki 模块

在项目下新建一个普通 CodeWiki 模块，指定模块名与关联路径（fields，可多个），默认启用。创建成功后返回创建后的模块。

POST /api/codewiki/v3/projects/:id/modules

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
name	string	模块名称。必填
fields	array<string>	关联路径列表，必填。相对仓库根目录，需以 `/` 开头，可传多个，例如 `["/plugins/test", "/core/test"]`。缺省不关联路径。路径会被规范化（未以 `/` 开头时自动补前导 `/`）
enabled	boolean（可选）	是否启用，缺省为 `true`

返回值：

{
    "id": 65813,
    "project_id": 10730180,
    "type": "module",
    "name": "business-plugin-agent",
    "fields": ["/plugins/business-plugin-agent"],
    "enabled": true,
    "created_by": "git-user1",
    "updated_by": "git-user1",
    "created_at": "2026-08-05T11:00:00+0800",
    "updated_at": "2026-08-05T11:00:00+0800"
}

# 更新 CodeWiki 模块

更新指定 CodeWiki 模块，支持启用/停用、更新模块名、更新关联路径（fields）。由启用改为停用时，会同步取消该模块运行中的分析任务。更新成功后返回更新后的模块。

PUT /api/codewiki/v3/projects/:id/modules/:doc_module_id

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
doc_module_id	integer	待更新的 CodeWiki 模块 ID
name	string	模块名称
fields	array<string>	关联路径列表，相对仓库根目录，可传多个。不能为空
enabled	boolean	是否启用。必填；由 `true` 改为 `false` 时会取消该模块运行中的任务

返回值：

{
    "id": 65813,
    "project_id": 10730180,
    "type": "module",
    "name": "business-plugin-agent-renamed",
    "fields": ["/plugins/business-plugin-agent", "/plugins/business-plugin-web-agent"],
    "enabled": false,
    "created_by": "git-user1",
    "updated_by": "git-user1",
    "created_at": "2026-08-05T11:00:00+0800",
    "updated_at": "2026-08-05T12:30:00+0800"
}

说明：更新接口的 name、fields、enabled 均为必填，缺省会返回参数错误（例如缺少 enabled 返回 required parameter [Boolean enabled]）。仅支持新建与更新，暂不开放删除接口。

# 配置自动追踪

配置 CodeWiki 的自动追踪（定期随代码变更自动更新）。配置不存在时新建，已存在时更新。

同一项目下的同一个模块（id + doc_module_id）最多允许配置 3 条自动追踪，即一个模块最多追踪 3 个分支。已达上限时新增会返回参数错误，此时请先删除或复用已有分支的配置；对已有的 3 条配置修改 frequency / enabled 不受该限制影响。

POST /api/codewiki/v3/projects/:id/auto_tracks

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
frequency	string	更新频率，仅支持 `day` / `week` / `month`
enabled	boolean	是否启用自动追踪
branch	string（可选）	分支名，缺省取默认分支；SVN 项目忽略该参数
doc_module_id	integer	CodeWiki 模块 ID。SVN 项目必填；Git 项目可选，缺省取仓库级模块

返回值：

{
    "action": "created",
    "auto_track": {
        "id": 2048,
        "project_id": 10730180,
        "doc_module_id": 65811,
        "branch": "master",
        "frequency": "week",
        "enabled": true,
        "created_by": "git-user1",
        "updated_by": "git-user1",
        "created_at": "2026-08-05T11:00:00+0800",
        "updated_at": "2026-08-05T11:00:00+0800"
    }
}

action 表示本次操作的实际结果：

created: 新建了自动追踪配置
updated: 更新了已有配置
unchanged: 配置与传入参数一致，未做变更

# 查询自动追踪列表

列出项目的自动追踪配置。

GET /api/codewiki/v3/projects/:id/auto_tracks

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
doc_module_id	integer（可选）	限定查询指定模块的配置
enabled	boolean（可选）	按启用状态过滤，缺省不过滤
search	string（可选）	按关键词模糊搜索
page	integer（可选）	指定页码（默认 1）
per_page	integer（可选）	每页大小（默认 20）

返回值：

[
    {
        "id": 2048,
        "project_id": 10730180,
        "doc_module_id": 65811,
        "branch": "master",
        "frequency": "week",
        "enabled": true,
        "created_by": "git-user1",
        "updated_by": "git-user1",
        "created_at": "2026-08-05T11:00:00+0800",
        "updated_at": "2026-08-05T11:00:00+0800"
    },
    {
        "id": 2049,
        "project_id": 10730180,
        "doc_module_id": 65812,
        "branch": "master",
        "frequency": "day",
        "enabled": false,
        "created_by": "git-user2",
        "updated_by": "git-user2",
        "created_at": "2026-08-03T09:30:00+0800",
        "updated_at": "2026-08-04T20:15:00+0800"
    }
]

CodeWiki 开放接口

← 主机 CodeEntire 开放接口 →