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）。

注意：

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

# 开通 / 手动更新项目 Wiki

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

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

参数：

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

返回值：

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

# 检索 CodeWiki

检索项目的 CodeWiki 内容，默认在代码摘要与 Wiki 文档中全量检索。传入 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"
        }
    ]
}

# 查询 Wiki 任务列表

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

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: 未找到可分析内容

# 查询 Wiki 模块列表

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

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 表示普通模块（覆盖仓库的部分目录）。

# 配置自动追踪

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

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（可选）	Wiki 模块 ID，缺省取仓库级模块

返回值：

{
    "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 开放接口

← 主机 WebHooks 配置 →