{"id":"1061a94b-936d-4b7f-87d7-643f069ffb06","entityType":"agent","slug":"clawhub-myd2002-gitea-repo-ingest","name":"Gitea Repo Ingest","canonicalUrl":"https://www.xpersona.co/agent/clawhub-myd2002-gitea-repo-ingest","canonicalPath":"/agent/clawhub-myd2002-gitea-repo-ingest","generatedAt":"2026-10-11T17:45:15.577Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T13:59:58.368Z","emptyReason":null},"description":"Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source tr Skill: Gitea Repo Ingest Owner: myd2002 Summary: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source tr Tags: latest:1.0.6 Version history: v1.0.6 | 2026-07-09T14:37:58.657Z","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s175zrvz5m28epr76c6rt4dtex8474t6:gitea-repo-ingest","sourceUrl":"https://clawhub.ai/myd2002/gitea-repo-ingest","homepage":"https://clawhub.ai/myd2002/skills/gitea-repo-ingest","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/myd2002/gitea-repo-ingest","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/myd2002/skills/gitea-repo-ingest","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code under"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:58.368Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:58.368Z","emptyReason":null},"stars":null,"forks":null,"downloads":1053,"packageName":null,"latestVersion":"1.0.6","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T13:59:58.355Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T13:59:58.368Z","lastCrawledAt":"2026-10-11T13:59:58.355Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T13:59:58.355Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.6","createdAt":"2026-07-09T14:37:58.657Z","changelog":"gitea-repo-ingest 1.0.6 - Clarified usage of the validate-pages script: do not treat successful validation as the final result; always continue to the apply stage, as only apply updates the final result file. - Documented that apply writes a stable itemKey in the sourceItems array for repository sources, improving catalog consistency. - No code or implementation changes; documentation updated for workflow accuracy and clarity.","fileCount":14,"zipByteSize":25056},{"version":"1.0.5","createdAt":"2026-07-08T19:21:40.117Z","changelog":"**v1.0.5 changelog** - Added a strict `validate-pages` step to the ingestion workflow; JSON output must be validated before applying to the knowledge base. - Updated `pages.json` requirements: now must be pure JSON with correct character escaping and no Markdown explanations, comments, trailing commas, or unescaped backslashes. - The prescribed process now explicitly includes: prepare context → plan pages.json → validate pages.json → apply updates. - Documentation updated to clarify error correction, output constraints, and when to rerun validation before final ingestion.","fileCount":14,"zipByteSize":25038},{"version":"1.0.4","createdAt":"2026-07-08T17:35:44.876Z","changelog":"gitea-repo-ingest 1.0.4 - No changes were detected in this release. - Functionality, documentation, and logic remain unchanged.","fileCount":14,"zipByteSize":24098},{"version":"1.0.3","createdAt":"2026-07-08T16:58:06.599Z","changelog":"gitea-repo-ingest 1.0.3 - Clarified that knowledge graph planning should be performed before writing pages.json. - Provided guidance for when to create/update overview pages (overview/) based on team-level or project/architecture impact. - Added support for a relatedPages field in pages.json to express links from normal Wiki pages (e.g., overview/, projects/, meetings/). - Updated sample pages.json and relationship maintenance rules to include relatedPages. - Reorganized and emphasized entity identification and page-writing boundaries to avoid unnecessary or mechanical page creation.","fileCount":14,"zipByteSize":23520},{"version":"1.0.2","createdAt":"2026-07-08T11:01:51.625Z","changelog":"gitea-repo-ingest 1.0.2 - Added clarification and new guidance for handling large repositories: when `analysisLimits.largeRepository=true` or if the repo has many files, avoid summarizing every file—focus analysis on key samples and signal files, and keep `pages.json` output concise. - No code or implementation changes; SKILL.md documentation updated to guide behavior for large repositories.","fileCount":14,"zipByteSize":21684},{"version":"1.0.1","createdAt":"2026-07-07T17:45:08.490Z","changelog":"**Major update: Introduces a Python script-based, catalog-driven workflow for deterministic repo ingest and tight Gitea KB integration.** - Added all initial Python scripts for repo ingestion, evidence sampling, catalog maintenance, and task orchestration. - Switched to a strict two-stage process: `prepare` (context/evidence sampling) and `apply` (Wiki page commit & catalog update). - Greatly expanded and clarified documentation for skill boundaries, input conventions, repo handling, catalog rules, and page templates. - Enforced result writing via scripts and a single result JSON file, supporting robust error handling and tight integration. - Documented concrete `pages.json` structure, output envelope, and detailed expectations for incremental updates, source traceability, and page relationships.","fileCount":14,"zipByteSize":21121},{"version":"1.0.0","createdAt":"2026-07-06T16:34:35.553Z","changelog":"- Initial release of the gitea-repo-ingest skill. - Enables ingestion of Git/Gitea repositories into the Research KB using OpenClaw for code understanding. - Tracks commit changes and updates corresponding code pages in the Gitea-backed knowledge base. - Follows a detailed page template focused on knowledge reuse and codebase comprehension, not code listing. - Supports incremental updates, snapshot tracking, and explicit module-level change summaries. - Defines strict input, processing flow, output format, and error reporting conventions.","fileCount":6,"zipByteSize":6831}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175zrvz5m28epr76c6rt4dtex8474t6:gitea-repo-ingest","setupComplexity":"medium","setupSteps":["Python environment detected. Create a strict virtual environment (`python -m venv .venv`) before installing dependencies to prevent system-level package conflicts.","Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T17:45:15.575Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-myd2002-gitea-repo-ingest/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T13:59:58.368Z","emptyReason":null},"readme":"Skill: Gitea Repo Ingest\n\nOwner: myd2002\n\nSummary: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source tr\n\nTags: latest:1.0.6\n\nVersion history:\n\nv1.0.6 | 2026-07-09T14:37:58.657Z | user\n\ngitea-repo-ingest 1.0.6\n\n- Clarified usage of the validate-pages script: do not treat successful validation as the final result; always continue to the apply stage, as only apply updates the final result file.\n- Documented that apply writes a stable itemKey in the sourceItems array for repository sources, improving catalog consistency.\n- No code or implementation changes; documentation updated for workflow accuracy and clarity.\n\nv1.0.5 | 2026-07-08T19:21:40.117Z | user\n\n**v1.0.5 changelog**\n\n- Added a strict `validate-pages` step to the ingestion workflow; JSON output must be validated before applying to the knowledge base.\n- Updated `pages.json` requirements: now must be pure JSON with correct character escaping and no Markdown explanations, comments, trailing commas, or unescaped backslashes.\n- The prescribed process now explicitly includes: prepare context → plan pages.json → validate pages.json → apply updates.\n- Documentation updated to clarify error correction, output constraints, and when to rerun validation before final ingestion.\n\nv1.0.4 | 2026-07-08T17:35:44.876Z | user\n\ngitea-repo-ingest 1.0.4\n\n- No changes were detected in this release.\n- Functionality, documentation, and logic remain unchanged.\n\nv1.0.3 | 2026-07-08T16:58:06.599Z | user\n\ngitea-repo-ingest 1.0.3\n\n- Clarified that knowledge graph planning should be performed before writing pages.json.\n- Provided guidance for when to create/update overview pages (overview/) based on team-level or project/architecture impact.\n- Added support for a relatedPages field in pages.json to express links from normal Wiki pages (e.g., overview/, projects/, meetings/).\n- Updated sample pages.json and relationship maintenance rules to include relatedPages.\n- Reorganized and emphasized entity identification and page-writing boundaries to avoid unnecessary or mechanical page creation.\n\nv1.0.2 | 2026-07-08T11:01:51.625Z | user\n\ngitea-repo-ingest 1.0.2\n\n- Added clarification and new guidance for handling large repositories: when `analysisLimits.largeRepository=true` or if the repo has many files, avoid summarizing every file—focus analysis on key samples and signal files, and keep `pages.json` output concise.\n- No code or implementation changes; SKILL.md documentation updated to guide behavior for large repositories.\n\nv1.0.1 | 2026-07-07T17:45:08.490Z | user\n\n**Major update: Introduces a Python script-based, catalog-driven workflow for deterministic repo ingest and tight Gitea KB integration.**\n\n- Added all initial Python scripts for repo ingestion, evidence sampling, catalog maintenance, and task orchestration.\n- Switched to a strict two-stage process: `prepare` (context/evidence sampling) and `apply` (Wiki page commit & catalog update).\n- Greatly expanded and clarified documentation for skill boundaries, input conventions, repo handling, catalog rules, and page templates.\n- Enforced result writing via scripts and a single result JSON file, supporting robust error handling and tight integration.\n- Documented concrete `pages.json` structure, output envelope, and detailed expectations for incremental updates, source traceability, and page relationships.\n\nv1.0.0 | 2026-07-06T16:34:35.553Z | auto\n\n- Initial release of the gitea-repo-ingest skill.\n- Enables ingestion of Git/Gitea repositories into the Research KB using OpenClaw for code understanding.\n- Tracks commit changes and updates corresponding code pages in the Gitea-backed knowledge base.\n- Follows a detailed page template focused on knowledge reuse and codebase comprehension, not code listing.\n- Supports incremental updates, snapshot tracking, and explicit module-level change summaries.\n- Defines strict input, processing flow, output format, and error reporting conventions.\n\nArchive index:\n\nArchive v1.0.6: 14 files, 25056 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (293b), requirements.txt (77b), scripts/catalog.py (6673b), scripts/gitea_api.py (3242b), scripts/kb_writer.py (17457b), scripts/repo_reader.py (19241b), scripts/run_task.py (3817b), scripts/task_io.py (1010b), scripts/utils.py (2327b), setup.sh (204b), skill-card.md (1986b), SKILL.md (14438b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n写 `pages.json` 前先私下做一次知识图谱规划：代码库主页面是实体入口；`concepts/` 用来沉淀跨模块、跨资料可复用的抽象知识；`resources/` 用来登记具体可复用对象；`overview/` 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按准备、校验、写回流程执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成 ``。`pages.json` 必须是纯 JSON 对象，不允许包含 Markdown 解释、注释、尾随逗号或未转义反斜杠；正文里如果出现代码片段、Windows 路径、正则表达式、JSON 字符串或反引号，必须使用 JSON writer/serializer 写文件，或完整转义。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`、`relatedPages`。\n\n3. 校验 ``，不写入知识库：\n\n ```bash\n python3 scripts/run_task.py validate-pages --input --context --pages \n ```\n\n 如果校验失败，必须修正 `` 并重新运行 `validate-pages`。只有校验成功后才能执行 `apply`。不要把 `validate-pages` 的 `success=true` 当作最终结果；`validate-pages` 不写 `resultFile`，必须继续运行 `apply`。\n\n4. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，写回一个稳定 `itemKey` 的仓库级 `sourceItems[]` 资料项，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n5. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 团队知识库仓库名。\n- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。\n\n环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。\n\n## 上下文读取策略\n\n`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。\n\n`prepare` 会给出：\n\n- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。\n- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。\n- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。\n- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。\n- `existingKb`: 现有 catalog 相关页面和已有代码库页。\n\n初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 `analysisLimits.largeRepository=true` 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 `samples`、`importantFiles`、`topLevel`、`languageProfile`，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 `pages.json` 大小。\n\n增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。\n\n页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。\n\n## 页面与来源写入范围\n\n代码仓库入库通常至少维护：\n\n- `code/.md`: 代码仓库总览页，是本资料源的主页面。\n- `concepts/.md`: 概念页，记录稳定抽象知识节点。\n- `resources/.md`: 资源页，记录具体可复用对象。\n- `overview/.md`: 当仓库显著影响团队级导航、系统地图、项目集合、资料入口或研究主题综合时，创建或更新 overview 页；没有这种综合价值时不要硬建。\n\n如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。\n\n`source_files/` 的处理规则：\n\n- 代码仓库需要有来源登记文件，用于保留可追踪性。\n- `apply` 脚本会自动写入 `source_files/gitea_repo/-.md`。\n- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。\n- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。\n- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。\n\n不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。\n\n## 实体识别规则\n\n概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。\n\n资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。\n\n不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。\n\n## 代码库页面模板\n\n`code/.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。\n\n必须包含：\n\n1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。\n2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。\n3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。\n4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。\n5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。\n6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。\n7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。\n8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。\n9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。\n10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。\n11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。\n12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。\n13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。\n14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。\n15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。\n16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。\n17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/-.md` 来源登记文件。\n\n概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。\n\n资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。\n\n## 链接与 catalog 规则\n\n正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。\n\n关系维护规则：\n\n- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。\n- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。\n- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。\n- 其他普通 Wiki 页面如果与代码库有关，用 `relatedPages` 表达，例如 `overview/`、`projects/`、`papers/`、`surveys/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`、`qa/`。\n- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。\n\n`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。\n\n## pages.json 格式\n\n```json\n{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"relatedPages\": [\"overview/research-kb-v2.md\"],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}\n```\n\n## 输出格式\n\n`apply` 写出的 result 必须是单个 JSON 对象，包含：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n },\n \"sourceItems\": [\n {\n \"itemKey\": \"gitea_repo:1\",\n \"title\": \"example-repo\",\n \"sourceKind\": \"gitea_repo\",\n \"kind\": \"repository\",\n \"status\": \"ingested\",\n \"sha256\": \"\",\n \"originalPath\": \"https://example.com/repo.git\",\n \"archivedPath\": \"source_files/gitea_repo/1-example-repo.md\",\n \"url\": \"https://example.com/repo.git\",\n \"externalId\": \"\"\n }\n ]\n}\n```\n\n失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。\n\nFile v1.0.6:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.6\",\n \"publishedAt\": 1783607878657\n}\n\nFile v1.0.6:skill-card.md\n\n## Description:\n\nIngests public Git repositories or repositories on a configured Gitea server into a Research KB with code understanding, incremental comparison, source traceability, and catalog/index maintenance.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[myd2002](https://clawhub.ai/user/myd2002)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and knowledge-base maintainers use this skill to convert Git or configured Gitea repositories into Research KB wiki pages, source manifests, repository snapshots, and catalog/index updates.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill handles Gitea credentials while reading and writing repository content.\n\nMitigation: Use a tightly scoped Gitea bot token, keep repository URLs and platform configuration trusted, and avoid embedding tokens in git URLs.\n\nRisk: Repository files may be untrusted and could expose sensitive paths or misleading content during sampling.\n\nMitigation: Run only against trusted repositories, block symlink traversal during sampling, and clean or sanitize worktrees after use.\n\n## Reference(s):\n\n- [Gitea Repo Ingest on ClawHub](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, JSON]\n\n**Output Format:** [Markdown wiki pages plus JSON context, validation, and result envelopes]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes Research KB pages, source traceability manifests, catalog/index updates, repository snapshots, and repository-level sourceItems records.]\n\n## Skill Version(s):\n\n1.0.6 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.6:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared\n\nFile v1.0.6:requirements.txt\n\n# gitea_repo_ingest uses only the Python 3 standard library and the git CLI.\n\nArchive v1.0.5: 14 files, 25038 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (293b), requirements.txt (77b), scripts/catalog.py (6673b), scripts/gitea_api.py (3242b), scripts/kb_writer.py (17457b), scripts/repo_reader.py (19241b), scripts/run_task.py (3817b), scripts/task_io.py (1010b), scripts/utils.py (2327b), setup.sh (204b), skill-card.md (2552b), SKILL.md (13806b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n写 `pages.json` 前先私下做一次知识图谱规划：代码库主页面是实体入口；`concepts/` 用来沉淀跨模块、跨资料可复用的抽象知识；`resources/` 用来登记具体可复用对象；`overview/` 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按准备、校验、写回流程执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成 ``。`pages.json` 必须是纯 JSON 对象，不允许包含 Markdown 解释、注释、尾随逗号或未转义反斜杠；正文里如果出现代码片段、Windows 路径、正则表达式、JSON 字符串或反引号，必须使用 JSON writer/serializer 写文件，或完整转义。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`、`relatedPages`。\n\n3. 校验 ``，不写入知识库：\n\n ```bash\n python3 scripts/run_task.py validate-pages --input --context --pages \n ```\n\n 如果校验失败，必须修正 `` 并重新运行 `validate-pages`。只有校验成功后才能执行 `apply`。\n\n4. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n5. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 团队知识库仓库名。\n- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。\n\n环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。\n\n## 上下文读取策略\n\n`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。\n\n`prepare` 会给出：\n\n- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。\n- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。\n- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。\n- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。\n- `existingKb`: 现有 catalog 相关页面和已有代码库页。\n\n初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 `analysisLimits.largeRepository=true` 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 `samples`、`importantFiles`、`topLevel`、`languageProfile`，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 `pages.json` 大小。\n\n增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。\n\n页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。\n\n## 页面与来源写入范围\n\n代码仓库入库通常至少维护：\n\n- `code/.md`: 代码仓库总览页，是本资料源的主页面。\n- `concepts/.md`: 概念页，记录稳定抽象知识节点。\n- `resources/.md`: 资源页，记录具体可复用对象。\n- `overview/.md`: 当仓库显著影响团队级导航、系统地图、项目集合、资料入口或研究主题综合时，创建或更新 overview 页；没有这种综合价值时不要硬建。\n\n如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。\n\n`source_files/` 的处理规则：\n\n- 代码仓库需要有来源登记文件，用于保留可追踪性。\n- `apply` 脚本会自动写入 `source_files/gitea_repo/-.md`。\n- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。\n- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。\n- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。\n\n不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。\n\n## 实体识别规则\n\n概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。\n\n资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。\n\n不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。\n\n## 代码库页面模板\n\n`code/.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。\n\n必须包含：\n\n1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。\n2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。\n3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。\n4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。\n5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。\n6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。\n7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。\n8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。\n9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。\n10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。\n11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。\n12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。\n13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。\n14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。\n15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。\n16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。\n17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/-.md` 来源登记文件。\n\n概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。\n\n资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。\n\n## 链接与 catalog 规则\n\n正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。\n\n关系维护规则：\n\n- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。\n- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。\n- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。\n- 其他普通 Wiki 页面如果与代码库有关，用 `relatedPages` 表达，例如 `overview/`、`projects/`、`papers/`、`surveys/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`、`qa/`。\n- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。\n\n`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。\n\n## pages.json 格式\n\n```json\n{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"relatedPages\": [\"overview/research-kb-v2.md\"],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}\n```\n\n## 输出格式\n\n`apply` 写出的 result 必须是单个 JSON 对象，包含：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n }\n}\n```\n\n失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。\n\nFile v1.0.5:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.5\",\n \"publishedAt\": 1783538500117\n}\n\nFile v1.0.5:skill-card.md\n\n## Description:
\nIngest public Git repositories or repositories on the configured Gitea server into the Research KB for OpenClaw code understanding, incremental commit comparison, wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[myd2002](https://clawhub.ai/user/myd2002)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and Research KB maintainers use this skill to turn readable public or configured Gitea repositories into structured knowledge base pages, source manifests, and catalog/index updates. It supports initial and incremental scans by preparing repository context, validating generated pages JSON, and applying the resulting knowledge base writes.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Repository sampling may ingest committed secrets, including .env files, private keys, tokens, or credential exports.
\nMitigation: Use only repositories checked for committed secrets, remove .env from sampled extensions or add secret denylisting/redaction, and scope the Gitea bot token to the intended KB repository.
\nRisk: The apply workflow writes generated content back into team knowledge base pages, source manifests, catalog files, and index files.
\nMitigation: Run the validate-pages step before apply, review generated pages for correctness, and use least-privilege bot credentials for KB writes.
\n\n\n## Reference(s):
\n- [Gitea Repo Ingest on ClawHub](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)
\n- [Publisher profile: myd2002](https://clawhub.ai/user/myd2002)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]
\n**Output Format:** [Markdown guidance with shell commands and JSON files for context, pages, validation, apply results, and source traceability]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [The apply step can write Research KB pages, source manifests, catalog entries, and index updates; setup requires Python 3 and git.]
\n\n## Skill Version(s):
\n1.0.5 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.5:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared\n\nFile v1.0.5:requirements.txt\n\n# gitea_repo_ingest uses only the Python 3 standard library and the git CLI.\n\nArchive v1.0.4: 14 files, 24098 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (293b), requirements.txt (77b), scripts/catalog.py (6673b), scripts/gitea_api.py (3242b), scripts/kb_writer.py (14811b), scripts/repo_reader.py (18945b), scripts/run_task.py (2906b), scripts/task_io.py (1010b), scripts/utils.py (2327b), setup.sh (204b), skill-card.md (2371b), SKILL.md (13183b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n写 `pages.json` 前先私下做一次知识图谱规划：代码库主页面是实体入口；`concepts/` 用来沉淀跨模块、跨资料可复用的抽象知识；`resources/` 用来登记具体可复用对象；`overview/` 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按两段式执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成 ``。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`、`relatedPages`。\n\n3. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n4. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 团队知识库仓库名。\n- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。\n\n环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。\n\n## 上下文读取策略\n\n`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。\n\n`prepare` 会给出：\n\n- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。\n- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。\n- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。\n- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。\n- `existingKb`: 现有 catalog 相关页面和已有代码库页。\n\n初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 `analysisLimits.largeRepository=true` 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 `samples`、`importantFiles`、`topLevel`、`languageProfile`，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 `pages.json` 大小。\n\n增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。\n\n页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。\n\n## 页面与来源写入范围\n\n代码仓库入库通常至少维护：\n\n- `code/.md`: 代码仓库总览页，是本资料源的主页面。\n- `concepts/.md`: 概念页，记录稳定抽象知识节点。\n- `resources/.md`: 资源页，记录具体可复用对象。\n- `overview/.md`: 当仓库显著影响团队级导航、系统地图、项目集合、资料入口或研究主题综合时，创建或更新 overview 页；没有这种综合价值时不要硬建。\n\n如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。\n\n`source_files/` 的处理规则：\n\n- 代码仓库需要有来源登记文件，用于保留可追踪性。\n- `apply` 脚本会自动写入 `source_files/gitea_repo/-.md`。\n- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。\n- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。\n- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。\n\n不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。\n\n## 实体识别规则\n\n概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。\n\n资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。\n\n不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。\n\n## 代码库页面模板\n\n`code/.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。\n\n必须包含：\n\n1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。\n2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。\n3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。\n4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。\n5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。\n6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。\n7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。\n8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。\n9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。\n10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。\n11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。\n12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。\n13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。\n14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。\n15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。\n16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。\n17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/-.md` 来源登记文件。\n\n概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。\n\n资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。\n\n## 链接与 catalog 规则\n\n正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。\n\n关系维护规则：\n\n- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。\n- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。\n- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。\n- 其他普通 Wiki 页面如果与代码库有关，用 `relatedPages` 表达，例如 `overview/`、`projects/`、`papers/`、`surveys/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`、`qa/`。\n- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。\n\n`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。\n\n## pages.json 格式\n\n```json\n{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"relatedPages\": [\"overview/research-kb-v2.md\"],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}\n```\n\n## 输出格式\n\n`apply` 写出的 result 必须是单个 JSON 对象，包含：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n }\n}\n```\n\n失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。\n\nFile v1.0.4:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.4\",\n \"publishedAt\": 1783532144876\n}\n\nFile v1.0.4:skill-card.md\n\n## Description:
\nIngest public Git repositories or repositories on the configured Gitea server into the Research KB for code understanding, incremental commit comparison, wiki page updates, source traceability manifests, and Gitea-backed catalog/index maintenance.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[myd2002](https://clawhub.ai/user/myd2002)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and knowledge-base maintainers use this skill to convert readable Git or configured Gitea repositories into Research KB pages, source manifests, catalog updates, and incremental change context.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Repository contents, including accidental secrets or private configuration files, may be sampled and summarized into the knowledge base.
\nMitigation: Add explicit exclusions for .env files, private keys, kubeconfigs, and similar paths, and redact secrets before page generation.
\nRisk: Repository-derived context and cloned worktrees may remain available after ingestion.
\nMitigation: Use controlled shared directories and clean up cloned worktrees after ingestion.
\nRisk: The skill may ingest repositories outside the intended organizational scope when given broad repository URLs.
\nMitigation: Restrict accepted repository URLs with allowlist controls and review access permissions before running.
\n\n\n## Reference(s):
\n- [ClawHub skill release page](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)
\n\n\n## Skill Output:
\n**Output Type(s):** [markdown, json, shell commands, configuration, guidance]
\n**Output Format:** [Markdown knowledge-base pages, JSON task envelopes, and shell command guidance]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Produces repository-derived summaries, source manifests, catalog/index updates, and skip results for unchanged commits.]
\n\n## Skill Version(s):
\n1.0.4 (source: ClawHub release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.4:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared\n\nFile v1.0.4:requirements.txt\n\n# gitea_repo_ingest uses only the Python 3 standard library and the git CLI.\n\nArchive v1.0.3: 14 files, 23520 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (293b), requirements.txt (77b), scripts/catalog.py (6673b), scripts/gitea_api.py (3242b), scripts/kb_writer.py (13130b), scripts/repo_reader.py (17611b), scripts/run_task.py (2906b), scripts/task_io.py (1010b), scripts/utils.py (2327b), setup.sh (204b), skill-card.md (2314b), SKILL.md (13183b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n写 `pages.json` 前先私下做一次知识图谱规划：代码库主页面是实体入口；`concepts/` 用来沉淀跨模块、跨资料可复用的抽象知识；`resources/` 用来登记具体可复用对象；`overview/` 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按两段式执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成 ``。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`、`relatedPages`。\n\n3. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n4. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 团队知识库仓库名。\n- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。\n\n环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。\n\n## 上下文读取策略\n\n`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。\n\n`prepare` 会给出：\n\n- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。\n- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。\n- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。\n- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。\n- `existingKb`: 现有 catalog 相关页面和已有代码库页。\n\n初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 `analysisLimits.largeRepository=true` 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 `samples`、`importantFiles`、`topLevel`、`languageProfile`，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 `pages.json` 大小。\n\n增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。\n\n页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。\n\n## 页面与来源写入范围\n\n代码仓库入库通常至少维护：\n\n- `code/.md`: 代码仓库总览页，是本资料源的主页面。\n- `concepts/.md`: 概念页，记录稳定抽象知识节点。\n- `resources/.md`: 资源页，记录具体可复用对象。\n- `overview/.md`: 当仓库显著影响团队级导航、系统地图、项目集合、资料入口或研究主题综合时，创建或更新 overview 页；没有这种综合价值时不要硬建。\n\n如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。\n\n`source_files/` 的处理规则：\n\n- 代码仓库需要有来源登记文件，用于保留可追踪性。\n- `apply` 脚本会自动写入 `source_files/gitea_repo/-.md`。\n- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。\n- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。\n- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。\n\n不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。\n\n## 实体识别规则\n\n概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。\n\n资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。\n\n不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。\n\n## 代码库页面模板\n\n`code/.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。\n\n必须包含：\n\n1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。\n2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。\n3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。\n4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。\n5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。\n6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。\n7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。\n8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。\n9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。\n10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。\n11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。\n12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。\n13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。\n14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。\n15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。\n16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。\n17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/-.md` 来源登记文件。\n\n概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。\n\n资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。\n\n## 链接与 catalog 规则\n\n正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。\n\n关系维护规则：\n\n- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。\n- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。\n- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。\n- 其他普通 Wiki 页面如果与代码库有关，用 `relatedPages` 表达，例如 `overview/`、`projects/`、`papers/`、`surveys/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`、`qa/`。\n- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。\n\n`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。\n\n## pages.json 格式\n\n```json\n{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"relatedPages\": [\"overview/research-kb-v2.md\"],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}\n```\n\n## 输出格式\n\n`apply` 写出的 result 必须是单个 JSON 对象，包含：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n }\n}\n```\n\n失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。\n\nFile v1.0.3:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1783529886599\n}\n\nFile v1.0.3:skill-card.md\n\n## Description:
\nIngests public Git repositories or repositories on a configured Gitea server into a Research KB using OpenClaw code understanding, deterministic context preparation, source manifests, and catalog/index updates.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[myd2002](https://clawhub.ai/user/myd2002)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and knowledge-base maintainers use this skill to scan public Git or configured Gitea repositories, compare repository snapshots, plan code knowledge graph pages, and write Research KB pages, source traceability manifests, catalog entries, and result JSON envelopes.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Powerful Git and Gitea operations can inspect or update the wrong repository, organization, or knowledge-base target if task inputs are incorrect.
\nMitigation: Review repository URLs, target organizations, and generated page paths before applying writes; use dry-run or non-destructive checks first when available.
\nRisk: Provider tokens or repository credentials can be exposed if they are embedded in inputs, command history, or logs.
\nMitigation: Keep tokens in environment variables or credential helpers, avoid putting secrets in command arguments, and review errors for redacted output before sharing them.
\n\n\n## Reference(s):
\n- [ClawHub Skill Page](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, shell commands, configuration, JSON]
\n**Output Format:** [Markdown pages and JSON envelopes, with shell commands for the prepare/apply workflow.]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires Python 3 and git; uses Gitea credentials from environment variables when writing to a configured knowledge base.]
\n\n## Skill Version(s):
\n1.0.3 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.3:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared\n\nFile v1.0.3:requirements.txt\n\n# gitea_repo_ingest uses only the Python 3 standard library and the git CLI.\n\nArchive v1.0.2: 14 files, 21684 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (293b), requirements.txt (77b), scripts/catalog.py (5012b), scripts/gitea_api.py (3242b), scripts/kb_writer.py (10390b), scripts/repo_reader.py (15757b), scripts/run_task.py (2906b), scripts/task_io.py (1010b), scripts/utils.py (2327b), setup.sh (204b), skill-card.md (2487b), SKILL.md (12152b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按两段式执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，生成 ``。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`。\n\n3. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n4. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 团队知识库仓库名。\n- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。\n\n环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。\n\n## 上下文读取策略\n\n`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。\n\n`prepare` 会给出：\n\n- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。\n- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。\n- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。\n- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。\n- `existingKb`: 现有 catalog 相关页面和已有代码库页。\n\n初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。若 `analysisLimits.largeRepository=true` 或仓库文件较多，不要读取完整 worktree，不要按文件逐个总结；优先使用 `samples`、`importantFiles`、`topLevel`、`languageProfile`，只额外读取少量高信号入口、配置、核心模块、数据模型和测试文件，并控制 `pages.json` 大小。\n\n增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。\n\n页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。\n\n## 页面与来源写入范围\n\n代码仓库入库通常至少维护：\n\n- `code/.md`: 代码仓库总览页，是本资料源的主页面。\n- `concepts/.md`: 概念页，记录稳定抽象知识节点。\n- `resources/.md`: 资源页，记录具体可复用对象。\n\n如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。\n\n`source_files/` 的处理规则：\n\n- 代码仓库需要有来源登记文件，用于保留可追踪性。\n- `apply` 脚本会自动写入 `source_files/gitea_repo/-.md`。\n- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。\n- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。\n- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。\n\n不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。\n\n## 实体识别规则\n\n概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。\n\n资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。\n\n不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。\n\n## 代码库页面模板\n\n`code/.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。\n\n必须包含：\n\n1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。\n2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。\n3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。\n4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。\n5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。\n6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。\n7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。\n8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。\n9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。\n10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。\n11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。\n12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。\n13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。\n14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。\n15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。\n16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。\n17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/-.md` 来源登记文件。\n\n概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。\n\n资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。\n\n## 链接与 catalog 规则\n\n正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。\n\n关系维护规则：\n\n- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。\n- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。\n- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。\n- 其他页面如果与代码库有关，也应通过正文链接和 frontmatter 关系字段体现。\n- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。\n\n`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。\n\n## pages.json 格式\n\n```json\n{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}\n```\n\n## 输出格式\n\n`apply` 写出的 result 必须是单个 JSON 对象，包含：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n }\n}\n```\n\n失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1783508511625\n}\n\nFile v1.0.2:skill-card.md\n\n## Description:
\nIngest public Git repositories or repositories on the configured Gitea server into the Research KB with code understanding, incremental commit comparison, overview and concept pages, source traceability manifests, and Gitea-backed catalog updates.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[myd2002](https://clawhub.ai/user/myd2002)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and Research KB operators use this skill to turn readable public Git repositories or configured Gitea repositories into repository overview pages, concept pages, resource pages, source manifests, and catalog updates.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: A broad Gitea bot token could allow writes beyond the intended knowledge-base repository.
\nMitigation: Configure the Gitea bot token with access limited to the intended KB repository and avoid admin or broadly scoped tokens.
\nRisk: The apply step performs real commit operations against the configured Gitea KB.
\nMitigation: Review the payload, target repository, and generated pages before running apply where content quality or repository state matters.
\nRisk: Generated repository summaries may introduce incorrect or misleading knowledge-base content.
\nMitigation: Review generated pages before applying them and use source manifests to trace summaries back to repository evidence.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)
\n- [Skill instructions](artifact/SKILL.md)
\n- [Skill metadata](artifact/_meta.json)
\n\n\n## Skill Output:
\n**Output Type(s):** [Markdown, JSON, Shell commands, Configuration, Guidance]
\n**Output Format:** [Markdown knowledge-base pages and JSON result envelopes, with shell commands for prepare and apply steps]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [The apply workflow writes generated pages, a source manifest, catalog.json, index.md, and a resultFile JSON envelope.]
\n\n## Skill Version(s):
\n1.0.2 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.2:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared\n\nFile v1.0.2:requirements.txt\n\n# gitea_repo_ingest uses only the Python 3 standard library and the git CLI.\n\nArchive v1.0.1: 14 files, 21121 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (293b), requirements.txt (77b), scripts/catalog.py (5012b), scripts/gitea_api.py (3242b), scripts/kb_writer.py (10390b), scripts/repo_reader.py (14793b), scripts/run_task.py (2906b), scripts/task_io.py (1010b), scripts/utils.py (2327b), setup.sh (204b), skill-card.md (2307b), SKILL.md (11807b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按两段式执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，生成 ``。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`。\n\n3. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n4. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要退回到低质量 fallback 总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 团队知识库仓库名。\n- `platform.giteaUrl`、`platform.giteaOwner`、`sharedDir`: 平台上下文。\n\n环境变量包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。\n\n## 上下文读取策略\n\n`prepare` 会先用 `git ls-remote --symref` 判断远端 HEAD。若远端 commit 与上一轮 snapshot 相同，直接 skip，不 clone。若首次扫描或 commit 变化，才进行浅克隆和证据采样。\n\n`prepare` 会给出：\n\n- `repo.worktree`: 临时工作树路径，OpenClaw 可以继续读取其中源码。\n- `repo.latestCommit`、`repo.previousCommit`、`repo.changedFiles`、`repo.changedModules`。\n- `repo.importantFiles`: README、依赖、构建、配置、部署、CI 等关键文件。\n- `samples[]`: 脚本预采样的 README、配置、入口、测试、变更文件和结构性源码。\n- `existingKb`: 现有 catalog 相关页面和已有代码库页。\n\n初次扫描要重点读 README、目录树、依赖、构建、配置、部署、CI、入口、路由/API/CLI、任务调度、数据模型、核心服务和测试。\n\n增量扫描要重点读 `repo.previousCommit..repo.latestCommit` 的 `changedFiles`、`diffSummary`、受影响模块的现有页面章节，以及新增、删除、重命名、配置变更、接口变更、数据结构变更、权限变更。\n\n页面可以整体重写，但必须显式说明本次变化影响了哪些知识结论。未受影响章节应保持连续性，表现为增量更新，而不是像第一次见到仓库。\n\n## 页面与来源写入范围\n\n代码仓库入库通常至少维护：\n\n- `code/.md`: 代码仓库总览页，是本资料源的主页面。\n- `concepts/.md`: 概念页，记录稳定抽象知识节点。\n- `resources/.md`: 资源页，记录具体可复用对象。\n\n如果代码理解表明其他 Wiki 页面也需要同步更新，可以写入正常知识库页面，例如 `projects/`、`tech-notes/`、`experiments/`、`papers/`、`surveys/`、`notes/`、`qa/`、`meetings/`、`overview/`。\n\n`source_files/` 的处理规则：\n\n- 代码仓库需要有来源登记文件，用于保留可追踪性。\n- `apply` 脚本会自动写入 `source_files/gitea_repo/-.md`。\n- 该文件记录仓库 URL、访问模式、分支、commit、扫描时间、文件数量、顶层目录、语言分布、变更文件、变更模块、重要文件和生成页面。\n- 不要把代码仓库里的源码文件逐个上传到 `source_files/`。\n- 不要让 OpenClaw 在 `pages.json` 里直接写 `source_files/`；来源登记由脚本统一生成。\n\n不要通过 `pages.json` 写系统文件，例如 `.kb/`、`catalog.json`、`index.md`。`catalog.json` 和 `index.md` 由 `apply` 脚本统一维护。\n\n## 实体识别规则\n\n概念页适合架构范式、机制、算法、模型、评估概念、研究问题、业务流程模式、数据处理范式、任务调度机制、权限模型、状态流转，以及多个模块共享且有代码证据支撑的抽象知识。\n\n资源页适合数据集、模型、工具、库、框架、仓库、API、网站、论文、benchmark、平台服务、外部系统、协议、数据库、消息队列、云服务等具体可复用对象。\n\n不要为普通目录、普通文件、普通类名、普通函数名、临时变量、一次性实现细节、无证据的通用知识建页。\n\n## 代码库页面模板\n\n`code/.md` 是面向团队成员的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解这个仓库为什么存在、解决什么问题、由哪些模块组成、关键流程如何运转、沉淀了哪些知识、如何运行维护。\n\n必须包含：\n\n1. `## 仓库定位`: 仓库用途、业务/科研/工程目标、面向的用户/系统/流程、团队项目角色。\n2. `## 核心价值与使用场景`: 主要能力，每个场景说明输入、输出、价值。\n3. `## 功能模块总览`: 按功能/业务视角拆模块，不只按目录拆。\n4. `## 领域概念与关键对象`: 核心概念、状态、角色、数据对象、任务类型、文件类型、外部对象。\n5. `## 业务流程与工作流`: 端到端流程、触发条件、参与模块、关键步骤、结果、异常分支。\n6. `## 知识产出与页面关系`: 本仓库会维护哪些知识库内容，以及页面之间如何关联。\n7. `## 知识关联`: 相关概念、相关资源、相关项目/页面，使用 `[[path|标题]]`。\n8. `## 技术实现概览`: 技术栈、运行时、框架、关键依赖、构建、测试、部署。\n9. `## 架构与代码结构`: 系统边界、组件/模块、关键目录和关键文件。\n10. `## 接口、数据与协议`: API、CLI、事件、消息、数据库表、文件格式、配置 schema、外部协议和数据流。\n11. `## 配置、环境与权限`: 环境变量、配置文件、端口、存储路径、日志、权限模型、外部服务账号。不要写真实 token。\n12. `## 构建、运行、测试与部署`: 命令必须来自 README、构建文件、CI、配置或源码证据。\n13. `## 设计取舍与约束`: 设计选择、业务约束、架构约束、兼容要求、技术取舍。\n14. `## 风险、限制与待确认点`: 业务正确性、数据一致性、权限安全、任务可靠性、可维护性、性能、可观测性。\n15. `## 版本变化与知识演化`: commit 范围、变更文件、受影响模块、行为变化、知识结论变化。\n16. `## 源码阅读路线`: 从业务理解到源码阅读的推荐路径。\n17. `## 来源与证据索引`: README、配置、构建、CI、关键源码、测试、commit、diff、扫描时间，并引用 `source_files/gitea_repo/-.md` 来源登记文件。\n\n概念页必须包含：`定义与解释`、`在本仓库中的体现`、`证据片段`、`关联页面`、`边界与容易混淆点`、`来源与追踪`。\n\n资源页必须包含：`资源说明`、`使用位置`、`与仓库功能的关系`、`关联概念与页面`、`复用价值与注意事项`、`来源与追踪`。\n\n## 链接与 catalog 规则\n\n正文内部链接使用 `[[path-without-md|显示标题]]`，例如 `[[code/research-kb-v2|Research KB V2]]`、`[[concepts/task-snapshot|任务扫描水位]]`、`[[resources/sqlite|SQLite]]`。\n\n关系维护规则：\n\n- 代码库页通过 `relatedConcepts` 关联概念页，通过 `relatedResources` 关联资源页。\n- 概念页通过 `relatedCodePages` 反向关联支撑它的代码库页，通过 `relatedResources` 关联支撑它的资源。\n- 资源页通过 `relatedCodePages` 反向关联使用它的代码库页，通过 `relatedConcepts` 关联它支撑的概念。\n- 其他页面如果与代码库有关，也应通过正文链接和 frontmatter 关系字段体现。\n- 创建前先看 `existingKb.relatedPages` 和 catalog，发现同义页面时更新已有页，不重复建页。\n\n`apply` 脚本会合并 catalog 并补齐 catalog 层面的反向关系，但页面正文里的解释性链接仍需要 OpenClaw 写清楚。\n\n## pages.json 格式\n\n```json\n{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}\n```\n\n## 输出格式\n\n`apply` 写出的 result 必须是单个 JSON 对象，包含：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n }\n}\n```\n\n失败时 `success=false`，`errors[]` 写清原因。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要明确说明。\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1783446308490\n}\n\nFile v1.0.1:skill-card.md\n\n## Description:
\nIngest public Git repositories or repositories on the configured Gitea server into the Research KB.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[myd2002](https://clawhub.ai/user/myd2002)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and research teams use this skill to turn readable Git or configured Gitea repositories into Research KB wiki pages, source manifests, catalog entries, and index updates. It supports initial repository ingestion and incremental updates based on commit changes.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: A broadly scoped Gitea bot token could allow unintended knowledge-base writes.
\nMitigation: Use a least-privilege bot token limited to the intended Research KB repository.
\nRisk: Repositories containing live secrets or sensitive configuration may influence generated KB pages.
\nMitigation: Ingest only approved repositories that are safe to summarize and remove live secrets before scanning.
\nRisk: Generated wiki pages and catalog updates may misstate repository behavior if the input pages JSON is incomplete or inaccurate.
\nMitigation: Review generated pages before applying them and use the emitted source manifest to trace claims back to repository evidence.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)
\n- [Publisher profile](https://clawhub.ai/user/myd2002)
\n\n\n## Skill Output:
\n**Output Type(s):** [JSON, Markdown, Shell commands, Configuration]
\n**Output Format:** [JSON result envelopes and generated Markdown wiki pages]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Prepare mode emits repository context or a skip result; apply mode writes wiki pages, a source manifest, catalog/index updates, and a backend result JSON.]
\n\n## Skill Version(s):
\n1.0.1 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.1:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared\n\nFile v1.0.1:requirements.txt\n\n# gitea_repo_ingest uses only the Python 3 standard library and the git CLI.\n\nArchive v1.0.0: 6 files, 6831 bytes\n\nFiles: _meta.json (136b), env-example.txt (159b), main.js (220b), setup.sh (124b), skill-card.md (2275b), SKILL.md (9063b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: gitea_repo_ingest\ndescription: Ingest Git or Gitea repositories into the Research KB through OpenClaw code understanding, track commit changes, and update code pages in the Gitea-backed KB.\n---\n\n# gitea_repo_ingest\n\n## 职责边界\n\n`gitea_repo_ingest` 负责把一个可读取的 Git/Gitea 代码仓库整理成团队知识库中的代码库知识页。后端只负责校验仓库可访问、保存资料源、传入上一轮 `snapshot` 并调度任务；真正的代码理解、页面生成、catalog/index 更新由 OpenClaw 根据本 skill 完成。\n\n这个 skill 不负责创建 Gitea 账号、配置 token、选择扫描周期、管理后端数据库，也不把整个源码仓库复制进知识库。知识库里保存的是可复用的理解：项目目标、模块边界、运行方式、数据/API 流、配置入口、风险、变更摘要和后续追问线索。\n\n## 输入约定\n\n任务 JSON 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读取的仓库地址。\n- `source.config.defaultBranch`: 后端通过 `git ls-remote --symref` 尝试识别的默认分支，可为空。\n- `source.config.verifiedLatestCommit`: 新增资料源时后端探测到的 HEAD commit，可作为参考。\n- `source.lastSnapshot.latestCommit`: 上一次成功扫描的 commit。\n- `team.kbRepo`: 目标团队知识库仓库。\n- `platform.giteaUrl`、`platform.giteaOwner`、`platform.sharedDir`: 平台上下文。\n\n环境变量包括：`GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`。如果目标 repo 位于同一个 `GITEA_URL`，OpenClaw 可以使用 bot token 读取私有仓库；其他外部私有仓库不在本阶段支持范围内。\n\n## 处理流程\n\n1. 读取或浅克隆目标仓库，确定默认分支和最新 commit。\n2. 与 `source.lastSnapshot.latestCommit` 对比；commit 未变化时返回 `skippedSources[]` 和最新 `snapshot`，不重复写页面。\n3. 初次扫描时读取 README、目录树、依赖/构建/配置文件、入口文件、测试文件、部署文件、核心源码和重要接口。\n4. 增量扫描时读取 `previous..latest` 的 diff、变更文件和受影响模块；页面可整体重写，但必须显式呈现“上次 commit、本次 commit、变化模块、变化含义”。\n5. 写入或更新 `code/.md`，必要时更新相关 `projects/`、`resources/` 或 `concepts/` 页面，但不要为普通文件机械建页。\n6. 更新 `catalog.json` 和 `index.md`。\n7. 返回新的 `snapshot.latestCommit`、`changedModules` 和写入 commit 信息。\n\n## 代码库页面模板\n\n页面路径：`code/.md`。\n\n页面标题：`# 代码库：`。\n\n页面目标：这是一份面向团队知识库的代码仓库解读页，不是 README 复述、源码清单或纯技术审计。读者应能通过它理解：这个仓库为什么存在、服务什么业务/研究/工程目标、主要功能模块各自解决什么问题、关键流程如何运转、代码背后沉淀了哪些可复用知识，以及必要的技术实现、运行方式和风险。\n\n页面组织应遵循“知识理解优先，技术细节支撑”的原则：先解释仓库的用途、业务/科研语境、功能地图和核心概念，再进入架构、代码路径、接口数据、配置部署、质量风险和版本变化。缺失证据时写“仓库中未找到”，不要编造。\n\n页面必须包含以下章节：\n\n1. `## 仓库定位`\n 说明这个仓库是用来做什么的，它解决了什么业务/科研/工程问题，面向哪些用户、系统或流程。写清它在团队项目中的角色，而不仅是“一个后端/前端/工具库”。\n\n2. `## 核心价值与使用场景`\n 提炼仓库提供的主要能力，以及这些能力在真实场景中如何被使用。例如资料入库、任务调度、代码分析、会议整理、知识库问答、数据处理、模型评测、部署运维等。每个场景说明输入、输出和产生的价值。\n\n3. `## 功能模块总览`\n 用表格按业务/功能视角拆解模块，而不是只按目录拆解。字段建议包括：模块名称、解决的问题、主要职责、关键入口、相关代码路径、输入输出、依赖模块。模块说明应回答“这个模块为什么存在、负责哪块事情”。\n\n4. `## 领域概念与关键对象`\n 总结仓库中反复出现的核心概念、数据对象、状态、角色、任务类型、文件类型或外部资源。例如 user、data source、task、snapshot、catalog、codebase、meeting、conversation 等。说明每个概念的含义、生命周期、相关字段和代码位置。\n\n5. `## 业务流程与工作流`\n 用自然语言、表格或 Mermaid 图说明最重要的端到端流程。优先覆盖用户真正关心的流程：创建资料源、扫描仓库、生成 Wiki 页面、更新 catalog/index、问答引用、权限校验、失败重试等。每个流程写清触发条件、参与模块、关键步骤、结果和异常分支。\n\n6. `## 知识产出与页面关系`\n 说明这个仓库会产生或维护哪些知识库内容，页面写入哪些目录，catalog/index 如何变化，哪些页面之间有关联。对于代码仓库自身，也说明它适合沉淀成哪些概念页、资源页或项目页。\n\n7. `## 技术实现概览`\n 在知识层面之后再说明技术栈、工程类型、运行时、框架、关键依赖、包管理器、构建工具、测试工具和部署方式。技术说明要服务于理解功能模块，不要变成依赖列表。\n\n8. `## 架构与代码结构`\n 结合 C4/arc42 思路说明系统边界、容器/进程、组件/模块、关键类或函数。用表格列出重要目录和文件：路径、职责、关联功能模块、为什么重要。大型仓库优先总结边界和协作关系，不逐文件铺开。\n\n9. `## 接口、数据与协议`\n 汇总 API 路由、CLI 命令、事件/消息、数据库表、文件格式、配置 schema、外部协议和数据流。说明它们在业务流程中扮演的角色，以及关键字段的含义。\n\n10. `## 配置、环境与权限`\n 汇总环境变量、配置文件、端口、存储路径、日志位置、密钥归属、权限模型、外部服务账号。敏感值只写变量名和用途，不写实际 token。\n\n11. `## 构建、运行、测试与部署`\n 列出安装、启动、构建、测试、迁移、打包、部署、健康检查和常见排障命令。命令必须来自 README、package/pom/配置文件、CI 或源码证据。\n\n12. `## 设计取舍与约束`\n 提炼仓库中可观察到的重要设计选择、业务约束、架构约束、兼容性要求、技术取舍和隐含假设。没有显式说明时标注为“从代码结构推断”。\n\n13. `## 风险、限制与待确认点`\n 从业务正确性、数据一致性、权限安全、任务可靠性、可维护性、可测试性、性能、可观测性等角度总结风险。每个风险说明证据路径、可能影响和建议验证方式。\n\n14. `## 版本变化与知识演化`\n 记录本次扫描的 commit 范围、变更文件、受影响功能模块、行为变化、知识结论变化和需要关注的后续影响。初次扫描时写“初次扫描，无上一版本 diff”。\n\n15. `## 源码阅读路线`\n 给出从理解业务到阅读代码的推荐路线，例如“领域对象 -> 入口接口 -> 任务流程 -> 服务层 -> 数据存储 -> 外部集成 -> 测试”。这是代码导览，不写成问题清单。\n\n16. `## 来源与证据索引`\n 列出 README、配置文件、构建文件、CI 文件、关键源码路径、测试路径、commit hash、diff 文件列表和扫描时间。不要贴大段源码；必要代码片段保持短引用。\n## Frontmatter 与来源追踪\n\n页面 frontmatter 必须包含：\n\n- `type: \"code\"`\n- `sourceStatus: \"active|outdated|deleted|mixed\"`\n- `sources[].sourceType: \"gitea_repo\"`\n- `sources[].url`: 原仓库 URL\n- `sources[].commitHash`: 本次扫描 commit\n- `sources[].sourceId`: 后端资料源 ID\n\n## 输出格式\n\n输出必须是单个 JSON 对象：\n\n```json\n{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"sourceIds\": [1],\n \"keywords\": [\"backend\", \"api\"],\n \"contentHash\": \"sha256...\",\n \"sourceStatus\": \"active\"\n }\n ],\n \"archivedFiles\": [],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n }\n}\n```\n\n失败时 `success=false`，错误写入 `errors[]`。认证失败、仓库不存在、网络不可达、默认分支不存在、Gitea 写入失败都要给出明确原因。\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1783355675553\n}\n\nFile v1.0.0:skill-card.md\n\n## Description:
\nIngest Git or Gitea repositories into the Research KB through OpenClaw code understanding, track commit changes, and update code pages in the Gitea-backed KB.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[myd2002](https://clawhub.ai/user/myd2002)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and knowledge-base operators use this skill to ingest readable Git or Gitea repositories into a team Research KB, producing repository understanding pages and incremental change summaries. It supports codebase comprehension, catalog/index maintenance, and source-tracked knowledge reuse without copying full source repositories into the KB.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can operate with Gitea bot credentials and update team knowledge-base content.
\nMitigation: Install it only where operators are authorized to use those credentials, scope tokens to the required repositories, and review generated KB changes before relying on them.
\nRisk: Repository summaries and incremental change notes can be incomplete or misleading if source evidence is missing or a scan is stale.
\nMitigation: Require source URLs, commit hashes, changed modules, and explicit missing-evidence notes in generated pages, then rerun ingestion when repository commits change.
\n\n\n## Reference(s):
\n- [ClawHub Skill Page](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)
\n\n\n## Skill Output:
\n**Output Type(s):** [markdown, json, guidance, configuration]
\n**Output Format:** [JSON status object plus Markdown knowledge-base pages]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Returns success state, processed and skipped sources, created or updated page metadata, errors, commit information, and a repository snapshot.]
\n\n## Skill Version(s):
\n1.0.0 (source: release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.0:env-example.txt\n\nGITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared","readmeExcerpt":"Skill: Gitea Repo Ingest Owner: myd2002 Summary: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source tr Tags: latest:1.0.6 Version history: v1.0.6 | 2026-07-09T14:37:58.657Z ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python3 scripts/run_task.py prepare --input --context-output "},{"language":"bash","snippet":"python3 scripts/run_task.py validate-pages --input --context --pages "},{"language":"bash","snippet":"python3 scripts/run_task.py apply --input --context --pages "},{"language":"json","snippet":"{\"success\": true, \"resultFile\": \"\"}"},{"language":"json","snippet":"{\n \"pages\": [\n {\n \"path\": \"code/example-repo.md\",\n \"title\": \"代码库：example-repo\",\n \"type\": \"code\",\n \"content\": \"# 代码库：example-repo\\n\\n## 仓库定位\\n...\",\n \"sourceIds\": [1],\n \"relatedConcepts\": [\"concepts/task-snapshot.md\"],\n \"relatedResources\": [\"resources/sqlite.md\"],\n \"relatedCodePages\": [],\n \"relatedPages\": [\"overview/research-kb-v2.md\"],\n \"keywords\": [\"repository\", \"task\", \"snapshot\"],\n \"sourceStatus\": \"active\"\n }\n ]\n}"},{"language":"json","snippet":"{\n \"success\": true,\n \"processedSources\": [\"https://example.com/repo.git\"],\n \"createdPages\": [],\n \"updatedPages\": [],\n \"archivedFiles\": [\"source_files/gitea_repo/1-example-repo.md\"],\n \"skippedSources\": [],\n \"errors\": [],\n \"commitId\": \"\",\n \"snapshot\": {\n \"repoUrl\": \"https://example.com/repo.git\",\n \"latestCommit\": \"\",\n \"defaultBranch\": \"main\",\n \"changedModules\": []\n },\n \"sourceItems\": [\n {\n \"itemKey\": \"gitea_repo:1\",\n \"title\": \"example-repo\",\n \"sourceKind\": \"gitea_repo\",\n \"kind\": \"repository\",\n \"status\": \"ingested\",\n \"sha256\": \"\",\n \"originalPath\": \"https://example.com/repo.git\",\n \"archivedPath\": \"source_files/gitea_repo/1-example-repo.md\",\n \"url\": \"https://example.com/repo.git\",\n \"externalId\": \"\"\n }\n ]\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: gitea_repo_ingest\ndescription: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source traceability manifests, and Gitea-backed catalog/index updates.\n---\n\n# gitea_repo_ingest\n\n## 核心职责\n\n把一个可读取的代码仓库沉淀为团队知识库里的代码知识图谱。OpenClaw 负责深度代码理解和页面写作；本 skill 自带 Python 工具负责确定性动作：读取仓库、判断增量、采样证据、读取现有 catalog、写回 Markdown 页面、登记代码仓库来源、维护 `catalog.json`、维护 `index.md`、输出后端可读 JSON。\n\n支持范围：\n\n- 用户输入的公开 Git 仓库。\n- 用户输入的、部署在已配置 `GITEA_URL` 上且 bot token 可访问的 Gitea 仓库。\n- 同一 Gitea 的 HTTPS URL、`ssh://git@host/owner/repo.git`、`git@host:owner/repo.git` 会尽量转换成 bot token 可访问的 HTTPS URL。\n- Git 交互式凭据提示必须关闭；认证失败、仓库不存在、无权限或网络不可达时应快速失败并脱敏错误。\n- 其他外部私有仓库可以失败，不需要绕过权限。\n\n不要把完整源码仓库复制到知识库。知识库保存的是可复用理解：仓库用途、业务/科研目标、功能模块、工作流、领域概念、资源依赖、接口数据、运行部署、设计取舍、风险限制、版本变化和页面关系。\n\n写 `pages.json` 前先私下做一次知识图谱规划：代码库主页面是实体入口；`concepts/` 用来沉淀跨模块、跨资料可复用的抽象知识；`resources/` 用来登记具体可复用对象；`overview/` 用来维护团队级导航、系统地图、项目/主题综合和资料入口。不要为了满足格式机械建概念页、资源页或 overview 页；但当仓库理解显示某个已有主题、项目、架构概念、外部资源或团队导航需要更新时，应主动更新并建立跳转关系。\n\n## 必须使用的脚本流程\n\n不要直接手写 Gitea API。按准备、校验、写回流程执行：\n\n1. 准备上下文：\n\n ```bash\n python3 scripts/run_task.py prepare --input --context-output \n ```\n\n 如果输出 JSON 的 `mode` 是 `skip`，说明最新 commit 与上一轮 snapshot 一致。此时脚本已经可以写出 skip 结果；直接让最终回复指向 payload 中的 `resultFile`。\n\n2. 基于 `` 进行代码理解，先私下规划代码库页、概念页、资源页、overview/项目页和已有相关页之间的关系，再生成 ``。`pages.json` 必须是纯 JSON 对象，不允许包含 Markdown 解释、注释、尾随逗号或未转义反斜杠；正文里如果出现代码片段、Windows 路径、正则表达式、JSON 字符串或反引号，必须使用 JSON writer/serializer 写文件，或完整转义。`pages.json` 必须包含 `pages[]`，每个页面包含 `path`、`title`、`type`、`content`、`keywords`、`relatedConcepts`、`relatedResources`、`relatedCodePages`、`relatedPages`。\n\n3. 校验 ``，不写入知识库：\n\n ```bash\n python3 scripts/run_task.py validate-pages --input --context --pages \n ```\n\n 如果校验失败，必须修正 `` 并重新运行 `validate-pages`。只有校验成功后才能执行 `apply`。不要把 `validate-pages` 的 `success=true` 当作最终结果；`validate-pages` 不写 `resultFile`，必须继续运行 `apply`。\n\n4. 写回知识库：\n\n ```bash\n python3 scripts/run_task.py apply --input --context --pages \n ```\n\n `apply` 会写入 OpenClaw 生成的正常 Wiki 页面，重建 frontmatter，写入 `source_files/gitea_repo/-.md` 来源登记文件，更新 `catalog.json` 和 `index.md`，写回一个稳定 `itemKey` 的仓库级 `sourceItems[]` 资料项，并把后端需要的 JSON envelope 写到 payload 的 `resultFile`。\n\n5. 最终只回复 JSON，例如：\n\n ```json\n {\"success\": true, \"resultFile\": \"\"}\n ```\n\n如果脚本报错，修正输入或页面 JSON 后重试。不要在未完成代码理解时写低质量占位总览。\n\n## 输入约定\n\n任务 payload 通常包含：\n\n- `taskId`: 后端任务 ID。\n- `payloadFile`: 后端写出的 payload 路径。\n- `resultFile`: 需要写入的结果 JSON 路径。\n- `skill`: `gitea_repo_ingest`。\n- `source.id`、`source.name`、`source.type`: 资料源信息。\n- `source.config.repoUrl`: 用户填写且后端已校验可读的仓库地址。\n- `source.config.defaultBranch`: 后端尝试识别的默认分支，可为"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7cp7eb6ymqv898hke0ersmc1847fed\",\n \"slug\": \"gitea-repo-ingest\",\n \"version\": \"1.0.6\",\n \"publishedAt\": 1783607878657\n}"},{"path":"skill-card.md","content":"## Description:\n\nIngests public Git repositories or repositories on a configured Gitea server into a Research KB with code understanding, incremental comparison, source traceability, and catalog/index maintenance.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[myd2002](https://clawhub.ai/user/myd2002)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and knowledge-base maintainers use this skill to convert Git or configured Gitea repositories into Research KB wiki pages, source manifests, repository snapshots, and catalog/index updates.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill handles Gitea credentials while reading and writing repository content.\n\nMitigation: Use a tightly scoped Gitea bot token, keep repository URLs and platform configuration trusted, and avoid embedding tokens in git URLs.\n\nRisk: Repository files may be untrusted and could expose sensitive paths or misleading content during sampling.\n\nMitigation: Run only against trusted repositories, block symlink traversal during sampling, and clean or sanitize worktrees after use.\n\n## Reference(s):\n\n- [Gitea Repo Ingest on ClawHub](https://clawhub.ai/myd2002/skills/gitea-repo-ingest)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, JSON]\n\n**Output Format:** [Markdown wiki pages plus JSON context, validation, and result envelopes]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes Research KB pages, source traceability manifests, catalog/index updates, repository snapshots, and repository-level sourceItems records.]\n\n## Skill Version(s):\n\n1.0.6 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."},{"path":"env-example.txt","content":"GITEA_URL=http://127.0.0.1:3000\nGITEA_BOT_TOKEN=\nGITEA_BOT_USERNAME=research-kb-bot\nGITEA_ORG=\nTEAM_KB_REPO=team-kb\nOPENCLAW_SHARED_DIR=/srv/research-kb/shared"},{"path":"requirements.txt","content":"# gitea_repo_ingest uses only the Python 3 standard library and the git CLI."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source tr Skill: Gitea Repo Ingest Owner: myd2002 Summary: Ingest public Git repositories or repositories on the configured Gitea server into the Research KB. Use for Git/Gitea source scans that need OpenClaw code understanding, incremental commit comparison, code repository overview pages, concept pages, resource pages, related wiki page updates, source tr Tags: latest:1.0.6 Version history: v1.0.6 | 2026-07-09T14:37:58.657Z","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1397,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T13:59:58.368Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T13:59:58.368Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T17:45:15.577Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}