knowledge-base-update - SKILL.md Agent Skill

name: knowledge-base-update version: 2.0.0 description: >- 根据Jira单号自动在ssc-knowledge-base中更新需求维度的知识库。适用于需求测试完成后的知识库更新。 author: jiaxuan.han@shopee.com metadata: team: QA category: qa-skills tags: [knowledge-base-update, jira, knowledge-base, kb]

基于 Jira 单号的知识库自动更新 V2

此版本面向全局技能场景设计：

技能目录预期位于 ~/.codex/skills/kb-update-from-jira/
不假设当前工作目录是 ssc-knowledge-base
不依赖本地 git pull、git add、git push
更新知识库时，优先通过 GitLab MCP 直接读取和写入远程 ssc-knowledge-base 仓库

如果用户明确要求同时修改本地 checkout，可在远程方案完成后再额外同步；默认仅做远程更新。

When to Use

用户提供一个或多个 Jira 单号，要求更新知识库
需要根据 Jira + PRD + 代码变更补充业务知识
当前不在 ssc-knowledge-base 项目目录下，但仍需更新其知识库

Co-Located Resources

此技能应自带以下资源，并通过相对路径读取：

./jira_kb_mapping.yaml
可选：./references/kb_mapping.yaml

不要再引用仓库内路径，如 .cursor/skills/...。

Recommended Mapping Schema

jira_kb_mapping.yaml 建议至少支持以下字段：

jira_projects:
  SPWFM:
    domain: SPX
    product_line: workforce
    kb_repo_project_id: "shopee/bg-logistics/techplatform/ssc-knowledge-base"
    kb_base_branch: "release"
    kb_base_path: "knowledge_base/business/spx/workforce/business-lib"
    knowledge_update_log: "knowledge_base/business/spx/workforce/business-lib/knowledge_update_log.md"
    gitlab_repos:
      - "shopee/ssc/workforce-service"

兼容策略：

若缺少 kb_repo_project_id，优先使用用户输入；仍缺失时再询问用户
若缺少 kb_base_branch，通过 GitLab MCP get_project 获取默认分支
若缺少 knowledge_update_log，默认使用目标 KB 文件同目录下的 knowledge_update_log.md

Inputs

输入	必须	说明
`jira_keys`	是	一个或多个 Jira 单号，如 `SPWFM-1`
`code_repo`	否	需求代码仓库 `project_id`
`code_branch`	否	需求代码分支
`target_kb_file`	否	指定知识库文件路径
`kb_repo_project_id`	否	远程知识库仓库 GitLab `project_id`
`kb_base_branch`	否	知识库目标基线分支；不填则自动获取
`auto_create_mr`	否	是否自动创建 MR，默认 `true`
`remote_write`	否	是否直接写远程仓库，默认 `true`

MCP Tools

Atlassian

jira_get_issue
jira_get_issue_development_info
confluence_get_page

GitLab

discover_tools
get_project
get_repository_tree
get_file_contents
get_branch_diffs
list_merge_request_changed_files
list_merge_request_diffs
get_merge_request_file_diff
create_branch
push_files
create_or_update_file
create_merge_request

若当前 GitLab MCP 额外提供 MR 搜索/列表工具，可作为补充；但核心流程不得依赖它们存在。

Workflow

S0: 初始化

从用户消息中提取 Jira 单号，正则：[A-Z][A-Z0-9_]+-\d+。
读取与技能同目录的 jira_kb_mapping.yaml。
根据 Jira 项目键定位：
- kb_repo_project_id
- kb_base_path
- knowledge_update_log
- 候选业务代码仓库 gitlab_repos
调用 GitLab MCP：
- discover_tools 激活 repositories、branches、merge_requests、search
- get_project(project_id=<kb_repo_project_id>) 获取默认分支
默认以知识库仓库默认分支作为读取基线。
不执行本地 git pull，不假设当前目录存在知识库仓库。

S1: 收集 Jira 与 PRD 信息

对每个 Jira 单号执行：

读取 Jira 详情：

jira_get_issue
  issue_key: "<JIRA_KEY>"
  fields: "*all"
  comment_limit: 100

提取：

summary
description
labels
components
comments

读取开发信息：

jira_get_issue_development_info
  issue_key: "<JIRA_KEY>"
  application_type: "gitlab"

从 description、评论、开发信息中提取：

Confluence 页面链接
代码仓库 project_id
分支名 source_branch
MR IID

代码仓库判定优先级：

用户显式提供 code_repo / code_branch
Jira 开发面板
Jira 评论中的 GitLab 自动通知
jira_kb_mapping.yaml 中的 gitlab_repos
若仍无法确定，则允许跳过代码分析，仅基于 PRD 更新

Confluence 判定规则：

优先从 Jira description 提取 /pages/<page_id>
若无 page_id，但存在 Confluence URL，则从 URL 中继续解析
若没有 PRD 链接，则使用 Jira description 作为降级需求源

S2: 读取需求内容与代码变更

2a. 读取 PRD

若拿到 page_id：

confluence_get_page
  page_id: "<PAGE_ID>"
  convert_to_markdown: true
  include_metadata: true

否则使用 Jira description。

2b. 获取代码变更概览

优先策略：

有 merge_request_iid：用 MR 读取
无 MR 但有 source_branch：用分支对比读取
二者都没有：跳过代码分析

MR 方式：

list_merge_request_changed_files
  project_id: "<CODE_PROJECT_ID>"
  merge_request_iid: "<MR_IID>"
  excluded_file_patterns: ["^vendor/", "\\.pb\\.go$", "^test/"]

list_merge_request_diffs
  project_id: "<CODE_PROJECT_ID>"
  merge_request_iid: "<MR_IID>"
  unidiff: true

分支方式：

get_branch_diffs
  project_id: "<CODE_PROJECT_ID>"
  from: "<default_branch>"
  to: "<SOURCE_BRANCH>"
  excluded_file_patterns: ["^vendor/", "\\.pb\\.go$", "^test/"]

2c. 深度文件探索

即使 diff 很小，也必须主动读取完整业务文件。仅读 diff 不足以产出高质量知识库更新。

步骤：

从 diff 路径和 PRD 主题识别业务目录
用 get_repository_tree 浏览 feature 分支相关目录
用 get_file_contents 读取关键文件完整内容

优先读取的文件类型：

P0：model.go、entity.go、schema
P0：constant、enum、status
P1：service.go、handler、usecase
P1：helper.go、util、calculator
P2：router、route、api
P2：config、yaml、json

进入写入前，至少完成以下自检：

是否已读取数据模型或字段定义
是否已读取核心业务逻辑或状态流转
是否已读取新增枚举或常量

若 feature 分支可访问但以上仍不满足，继续探索，不要过早进入知识写入。

S3: 定位远程知识库文件

使用 kb_repo_project_id 和 kb_base_branch 作为远程知识库仓库上下文。
在 kb_base_path 下调用 get_repository_tree 列出候选 .md 文件。
目标 KB 文件选择优先级：

用户显式提供 target_kb_file
精确映射文件命中
Jira summary 关键词匹配文件名
PRD 内容关键词匹配文件名
若仍不明确，再向用户询问

读取目标 KB 文件完整内容：

get_file_contents
  project_id: "<KB_REPO_PROJECT_ID>"
  ref: "<KB_BASE_BRANCH>"
  file_path: "<TARGET_KB_FILE>"

读取更新日志文件：

优先 knowledge_update_log
否则使用 <target_dir>/knowledge_update_log.md

若日志文件不存在，可在写入阶段一并创建。

S4: 知识提取与内容合成

从 PRD + 代码提取以下知识：

术语：新增术语、缩写、枚举值
功能：新增或变更的模块说明
流程：主流程、状态流转、上下游交互
规则：触发条件、判断条件、处理逻辑
模型：新增表、字段、状态定义
API：新增接口或关键入参出参

提取原则：

PRD 优先表达设计意图
代码用于补齐模型、状态、枚举、约束与实现细节
忽略 TBD/TBC
不写 UI 文案、菜单路径、页面布局

写入原则：

优先补充现有章节，不轻易新增大段结构
保持原文件标题层级、表格风格、列表风格
不删减已有内容
语义重复则跳过
同主题缺漏则补充
与现有内容冲突时标记 ⚠️ 待确认，不要自动覆盖
正文不写来源标注，不引用外部文档章节号

S5: 预览与确认

在真正写远程仓库前，先向用户展示：

目标知识库文件
拟新增/补充的核心知识点
涉及的日志文件
任何待确认冲突项

只有在用户确认后，才执行远程写入。

S6: 远程写入与建 MR

默认远程写入流程：

创建工作分支：

create_branch
  project_id: "<KB_REPO_PROJECT_ID>"
  branch: "kb-update/<JIRA_KEY>/<YYYYMMDD-HHMM>"
  ref: "<KB_BASE_BRANCH>"

将目标 KB 文件与 knowledge_update_log.md 一次性提交：

push_files
  project_id: "<KB_REPO_PROJECT_ID>"
  branch: "<WORK_BRANCH>"
  commit_message: "docs: update KB from <JIRA_KEY>"
  files:
    - file_path: "<TARGET_KB_FILE>"
      content: "<FULL_UPDATED_CONTENT>"
    - file_path: "<LOG_FILE>"
      content: "<FULL_UPDATED_LOG_CONTENT>"

若只有单文件修改，也可用 create_or_update_file；但多文件更新优先使用 push_files 以保持单次提交。
若 auto_create_mr = true，创建 MR：

create_merge_request
  project_id: "<KB_REPO_PROJECT_ID>"
  source_branch: "<WORK_BRANCH>"
  target_branch: "<KB_BASE_BRANCH>"
  title: "docs: update <module> KB from <JIRA_KEY>"
  description: |
    ## Summary
    - <变更摘要>

    ## Source
    - Jira: <JIRA_KEY>
    - PRD: <PAGE_TITLE>
    - Code: <CODE_PROJECT_ID> <SOURCE_BRANCH>

最终返回：

更新的远程文件列表
提交分支名
MR 链接

Key Rules

默认远程优先，不依赖本地 checkout。
不要再调用本地 git pull、git add、git push 作为主流程。
不要引用 .cursor/skills/... 作为资源路径；只读取技能目录内的同伴文件。
只有在用户明确要求时，才把变更同步到本地工作区。
若无法定位知识库文件，只在最后一步向用户询问，不要过早打断。
代码分析可降级，知识库定位不可臆测。
流程类知识优先保留主链路，再补边界与异常。
每条业务规则必须尽量覆盖触发条件、判断条件、处理逻辑。
多个 Jira 单号可合并到同一工作分支和同一 MR。
每次更新都要同步维护 knowledge_update_log.md。

Migration Notes

若要正式升级为全局技能，建议执行以下迁移：

将此目录复制到 ~/.codex/skills/kb-update-from-jira/
保留 jira_kb_mapping.yaml 作为同目录资源
将 SKILL_V2.md 重命名为 SKILL.md
为 jira_kb_mapping.yaml 增补 kb_repo_project_id、kb_base_branch、knowledge_update_log

Additional Resources

./jira_kb_mapping.yaml
可选：./references/kb_mapping.yaml