Forgejo

Forgejo 是做什么的？

围绕 Forgejo REST API 的轻量级封装。每个资源对应独立脚本，智能体可以分别发现并调用它们。SkillHone 依赖此技能作为 VCS 后端，但它保持独立，以便 GitLab 或 Gitea 等其他后端提供相同的工作流接口。

脚本

脚本	资源	代表用法
scripts/issue.py	问题	python3 scripts/issue.py create --title "Bug"
scripts/pr.py	Pull request	python3 scripts/pr.py merge 1
scripts/wiki.py	Wiki 页面	python3 scripts/wiki.py get --title "Analysis"
scripts/repo.py	仓库元数据	python3 scripts/repo.py branches
scripts/summary.py	聚合面板	python3 scripts/summary.py

每个脚本支持 --help。在猜测标志前运行它。

配置

按以下顺序解析（优先匹配最先成功的）：

1. 环境变量：FORGEJO_URL、FORGEJO_TOKEN、FORGEJO_OWNER、FORGEJO_REPO
2. ~/.skillhone/settings.json + ~/.skillhone/identities.conf
3. 当前工作目录下的 _data/forgejo_config.txt

如果未设置任何值，脚本将退出并显示一条明确的消息，指出缺失的变量。

按资源用法

问题

python3 scripts/issue.py list
python3 scripts/issue.py view <N>
python3 scripts/issue.py create --title "Fix: timeout" --body "## Problem\n..."
python3 scripts/issue.py close <N>
python3 scripts/issue.py comment <N> --body "Done"

Pull Requests

python3 scripts/pr.py list
python3 scripts/pr.py view <M>
python3 scripts/pr.py create --title "Fix timeout" --head fix/timeout --base main --body "Closes #1"
python3 scripts/pr.py review <M> --approve
python3 scripts/pr.py merge <M> --method merge
python3 scripts/pr.py comment <M> --body "LGTM"

Wiki

python3 scripts/wiki.py list
python3 scripts/wiki.py get --title "Iteration-1-Observation"
python3 scripts/wiki.py create --title "Page" --body "content"
python3 scripts/wiki.py edit --title "Page" --body "updated content"

仓库元数据

python3 scripts/repo.py info
python3 scripts/repo.py branches

综合摘要

python3 scripts/summary.py
# 打开的问题 + 打开的 PR + 最新的观测 Wiki 页面

从其他技能调用

位于 ~/.skillhone/skills/ 下的其他技能通过绝对路径调用这些脚本：

python3 ~/.skillhone/skills/forgejo/scripts/issue.py list

这使得 VCS 后端可替换。GitLab 或 Gitea 技能可以公开等效的命令接口，而无需更改 SkillHone 的优化逻辑。

注意事项

• 包含 @ 字符的令牌会破坏 git clone 的 URL 注入。请使用不含 @ 的令牌或进行 URL 编码。
• 较旧版本的 Forgejo 不支持 merge --method squash。如果遇到 Unknown method，请回退到 merge。
• Wiki 页面以 .md 文件形式存储在单独的 git 仓库中（<repo>.wiki.git）。wiki.py 隐藏了此细节，但如果您需要自定义编辑，请直接克隆 wiki 仓库。

硬性规则

• 切勿将 Forgejo 令牌打印到 stdout/stderr 日志。脚本已进行脱敏处理；不要将其粘贴到 --body 字段中。
• 不要使用 curl 或手造 HTTP 从 SkillHone 工作流直接调用 Forgejo 的 REST API。请使用这些后端脚本，以便凭证加载、脱敏和后端替换保持集中管理。
• 不要通过 cat 读取 _data/forgejo_config.txt、~/.skillhone/settings.json 或 identities.conf 来发现凭证。脚本内部解析凭证。
• 不要通过任何这些脚本直接推送到 main。只通过 PR 进行。
• 当遇到 401/403 错误时，在修改脚本之前重新检查上面的配置解析顺序。