用途
Forgejo 是一个针对 Forgejo REST API 的轻量封装工具集,用于在 Forgejo 服务器上管理议题、拉取请求、Wiki 页面和仓库元数据。它作为 SkillHone 的版本控制(VCS)后端技能被依赖,但保持独立,使 GitLab 或 Gitea 等其他后端能够提供相同的工作流接口。
主要能力
工具集按资源划分为多个脚本,每个脚本负责一类操作:
- scripts/issue.py:议题管理,代表用法
python3 scripts/issue.py create --title "Bug" - scripts/pr.py:拉取请求管理,代表用法
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,在猜测参数前应先运行查看。
配置方式
配置按以下顺序解析(首个匹配项生效):
- 环境变量:FORGEJO_URL、FORGEJO_TOKEN、FORGEJO_OWNER、FORGEJO_REPO
- ~/.skillhone/settings.json 加 ~/.skillhone/identities.conf
- 当前工作目录下的 _data/forgejo_config.txt
若均未设置,脚本会以清晰的信息退出,指出缺失的变量。
使用方式
议题(Issues)
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
# open issues + open PRs + latest observation wiki page
从其他技能调用
位于 ~/.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 字段中。
- 不要从 SkillHone 工作流中用 curl 或手工构造的 HTTP 直接调用 Forgejo REST API。请使用这些后端脚本,以保持凭据加载、脱敏和后端替换的集中化。
- 不要通过 cat 查看 _data/forgejo_config.txt、~/.skillhone/settings.json 或 identities.conf 来获取凭据。脚本会在内部解析凭据。
- 不要通过这些脚本直接推送到 main。仅通过 PR 提交。
- 当遇到 401/403 时,先重新检查上述配置解析顺序,再更改脚本。
适用场景与限制
适用于需要通过智能体在 Forgejo 服务器上创建和管理议题、审查与合并拉取请求、读写 Wiki 页面以及查看仓库分支信息的场景,也可作为可替换的版本控制后端被其他技能按绝对路径调用。据现有资料,价格与平台支持等具体信息暂未提供。