Gitea Repo Ingest

gitea_repo_ingest

核心职责

把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 catalog.json、维护 index.md、输出后端可读 JSON。

支持范围：

• 用户输入的公开 Git 仓库。
• 用户输入的、部署在已配置 GITEA_URL 上且 bot token 可访问的 Gitea 仓库。
• 同一 Gitea 的 HTTPS URL、ssh://git@host/owner/repo.git、git@host:owner/repo.git 会尽量转换成 bot token 可访问的 HTTPS URL。
• Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。
• 其他外部私有仓库可以失败，不需要绕过权限。

不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。

写 pages.json 前先私下做一次知识图谱规划：代码库主页面是实体入口；concepts/ 用来沉淀跨模块、跨资料可复用的抽象知识；resources/ 用来登记具体可复用对象；overview/ 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。

必须使用的脚本流程

不要直接手写 Gitea API。按准备、校验、写回流程执行：

1. 准备上下文：

   python3 scripts/run_task.py prepare --input  --context-output 
   

   如果输出 JSON 的 mode 是 skip，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 resultFile。

2. 基于 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成。pages.json 必须是纯 JSON 对象，不允许包含 Markdown 解释、注释、尾随逗号或未转义反斜杠；正文里如果出现代码片段、Windows 路径、正则表达式、JSON 字符串或反引号，必须使用 JSON writer/serializer 写文件，或完整转义。pages.json 必须包含 pages[]，每个页面包含 path、title、type、content、keywords、relatedConcepts、relatedResources、relatedCodePages、relatedPages。

3. 校验 ``，不写入知识库：

   python3 scripts/run_task.py validate-pages --input  --context  --pages 
   

   如果校验失败，必须修正 `` 并重新运行 validate-pages。只有校验成功后才能执行 apply。不要把 validate-pages 的 success=true 当作最终结果；validate-pages 不写 resultFile，必须继续运行 apply。

4. 写回知识库：

   python3 scripts/run_task.py apply --input  --context  --pages 
   

   apply 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 source_files/gitea_repo/-.md 来源登记文件，更新 catalog.json 和 index.md，写回一个稳定 itemKey 的仓库级 sourceItems[] 资料项，并把后端需要的 JSON envelope 写到 payload 的 resultFile。

5. 最终只回复 JSON，例如：

   {"success": true, "resultFile": ""}
   

如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。

输入约定

任务 payload 通常包含：

• taskId: 后端任务 ID。
• payloadFile: 后端写出的 payload 路径。
• resultFile: 需要写入的结果 JSON 路径。
• skill: gitea_repo_ingest。
• source.id、source.name、source.type: 资料源信息。
• source.config.repoUrl: 用户填写且后端已校验可读的仓库地址。
• source.config.defaultBranch: 后端尝试识别的默认分支，可为空。
• source.config.verifiedLatestCommit: 新增资料源时后端探测到的 HEAD commit。
• source.lastSnapshot.latestCommit: 上一次成功扫描的 commit。
• team.kbRepo: 团队知识库仓库名。
• platform.giteaUrl、platform.giteaOwner、sharedDir: 平台上下文。

环境变量包括 GITEA_URL、GITEA_BOT_TOKEN、GITEA_BOT_USERNAME、GITEA_ORG、TEAM_KB_REPO、OPENCLAW_SHARED_DIR。

上下文读取策略

prepare 会先用 git ls-remote --symref 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。

prepare 会给出：

• repo.worktree: 临时工作树路径，OpenClaw 可以继续读取其中源码。
• repo.latestCommit、repo.previousCommit、repo.changedFiles、repo.changedModules。
• repo.importantFiles: README、依赖、构建、配置、部署、CI 等关键文件。
• samples[]: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。
• existingKb: 现有 catalog 相关页面和已有代码库页。

初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 analysisLimits.largeRepository=true 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 samples、importantFiles、topLevel、languageProfile，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 pages.json 大小。

增量扫描要重点读 repo.previousCommit..repo.latestCommit 的 changedFiles、diffSummary、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。

页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。

页面与来源写入范围

代码仓库入库通常至少维护：

• code/.md: 代码仓库总览页，是本资料源的主页面。
• concepts/.md: 概念页，记录稳定抽象知识节点。
• resources/.md: 资源页，记录具体可复用对象。
• overview/.md: 当仓库显著影响团队级导航、系统地图、项目集合、资料入口或研究主题综合时，创建或更新 overview 页；没有这种综合价值时不要硬建。

如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 projects/、tech-notes/、experiments/、papers/、surveys/、notes/、qa/、meetings/、overview/。

source_files/ 的处理规则：

• 代码仓库需要有来源登记文件，用于保留可追踪性。
• apply 脚本会自动写入 source_files/gitea_repo/-.md。
• 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。
• 不要把代码仓库里的源码文件逐个上传到 source_files/。
• 不要让 OpenClaw 在 pages.json 里直接写 source_files/；来源登记由脚本统一生成。

不要通过 pages.json 写系统文件，例如 .kb/、catalog.json、index.md。catalog.json 和 index.md 由 apply 脚本统一维护。

实体识别规则

概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。

资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。

不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。

代码库页面模板

code/.md 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。

必须包含：

1. ## 仓库定位: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。
2. ## 核心价值与使用场景: 主要能力，每个场景说明输入、输出、价值。
3. ## 功能模块总览: 按功能/业务视角拆模块，不只按目录拆。
4. ## 领域概念与关键对象: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。
5. ## 业务流程与工作流: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。
6. ## 知识产出与页面关系: 本仓库会维护哪些知识库内容，以及页面之间如何关联。
7. ## 知识关联: 相关概念、相关资源、相关项目/页面，使用 [[path|标题]]。
8. ## 技术实现概览: 技术栈、运行时、框架、关键依赖、构建、测试、部署。
9. ## 架构与代码结构: 系统边界、组件/模块、关键目录和关键文件。
10. ## 接口、数据与协议: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。
11. ## 配置、环境与权限: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。
12. ## 构建、运行、测试与部署: 命令必须来自 README、构建文件、CI、配置或源码证据。
13. ## 设计取舍与约束: 设计选择、业务约束、架构约束、兼容要求、技术取舍。
14. ## 风险、限制与待确认点: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。
15. ## 版本变化与知识演化: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。
16. ## 源码阅读路线: 从业务理解到源码阅读的推荐路径。
17. ## 来源与证据索引: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 source_files/gitea_repo/-.md 来源登记文件。

概念页必须包含：定义与解释、在本仓库中的体现、证据片段、关联页面、边界与容易混淆点、来源与追踪。

资源页必须包含：资源说明、使用位置、与仓库功能的关系、关联概念与页面、复用价值与注意事项、来源与追踪。

链接与 catalog 规则

正文内部链接使用 [[path-without-md|显示标题]]，例如 [[code/research-kb-v2|Research KB V2]]、[[concepts/task-snapshot|任务扫描水位]]、[[resources/sqlite|SQLite]]。

关系维护规则：

• 代码库页通过 relatedConcepts 关联概念页，通过 relatedResources 关联资源页。
• 概念页通过 relatedCodePages 反向关联支撑它的代码库页，通过 relatedResources 关联支撑它的资源。
• 资源页通过 relatedCodePages 反向关联使用它的代码库页，通过 relatedConcepts 关联它支撑的概念。
• 其他普通 Wiki 页面如果与代码库有关，用 relatedPages 表达，例如 overview/、projects/、papers/、surveys/、meetings/、experiments/、tech-notes/、notes/、qa/。
• 创建前先看 existingKb.relatedPages 和 catalog，发现同义页面时更新已有页，不重复建页。

apply 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。

pages.json 格式

{
  "pages": [
    {
      "path": "code/example-repo.md",
      "title": "代码库：example-repo",
      "type": "code",
      "content": "# 代码库：example-repo\n\n## 仓库定位\n...",
      "sourceIds": [1],
      "relatedConcepts": ["concepts/task-snapshot.md"],
      "relatedResources": ["resources/sqlite.md"],
      "relatedCodePages": [],
      "relatedPages": ["overview/research-kb-v2.md"],
      "keywords": ["repository", "task", "snapshot"],
      "sourceStatus": "active"
    }
  ]
}

输出格式

apply 写出的 result 必须是单个 JSON 对象，包含：

{
  "success": true,
  "processedSources": ["https://example.com/repo.git"],
  "createdPages": [],
  "updatedPages": [],
  "archivedFiles": ["source_files/gitea_repo/1-example-repo.md"],
  "skippedSources": [],
  "errors": [],
  "commitId": "",
  "snapshot": {
    "repoUrl": "https://example.com/repo.git",
    "latestCommit": "",
    "defaultBranch": "main",
    "changedModules": []
  },
  "sourceItems": [
    {
      "itemKey": "gitea_repo:1",
      "title": "example-repo",
      "sourceKind": "gitea_repo",
      "kind": "repository",
      "status": "ingested",
      "sha256": "",
      "originalPath": "https://example.com/repo.git",
      "archivedPath": "source_files/gitea_repo/1-example-repo.md",
      "url": "https://example.com/repo.git",
      "externalId": ""
    }
  ]
}

失败时 success=false，errors[] 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。