Remogram

Remogram

通用 SCM/forge 边界 CLI 和 MCP 服务。输出归属提供方的 JSON 事实——本地 git 解析的引用（refs compare、sync plan）与 forge API 报告的 PR SHA（pr view、pr checks）。输出中不包含工作流或规划工具概念。

按编号对账 PR：pr view / pr checks 会将 forge 报告的 forge_source_sha 与本地 forge_source_branch_ref 对应的修订版本进行比较。如果不一致 → ok: false，error_code: stale_head——应执行 git fetch，而不是将其视为 forge 服务中断。

规划工具在 Remogram 之外解读意图和工作流权限。

安装

npm install -g @remogram/cli @remogram/mcp
remogram --version
remogram version --json

旧版预览（冻结在 @beta，可选）：npm install -g @remogram/cli@beta @remogram/mcp@beta

开发版检出：克隆此仓库，执行 npm ci、./scripts/npm-link.sh。默认分支：main。

快速开始

1. 将 .remogram.json.example 复制到 .remogram.json（设置 provider、owner、repo；对于可自托管的 Gitea/GitLab，添加 baseUrl）。
2. 导出令牌：GITEA_TOKEN、GITHUB_TOKEN / GH_TOKEN 或 GITLAB_TOKEN。
3. 初始化：

remogram doctor --json
remogram provider capabilities --json
remogram repo status --json
remogram pr view --number 1 --json
remogram merge plan --number 1 --json

命令目录：remogram contract --json。Agent 技能：npx skills add attebury/remogram --skill remogram-consumer -g -y。

提供方

Forge	"provider"	令牌环境变量
Gitea	gitea-api	GITEA_TOKEN
GitHub	github-api	GITHUB_TOKEN 或 GH_TOKEN
GitLab	gitlab-api	GITLAB_TOKEN

使用 *-api 提供方（forge HTTP）。保留的 github-gh / gitea-tea ID 会返回 provider_unsupported——v1 中尚未实现。不要求安装官方 CLI（gh、tea、glab）。

配置

**默认只读/规划。**在 .remogram.json 中通过 write_commands 启用写入（或使用绑定到仓库之外的运维人员覆盖配置）。缺少 ID → write_not_configured。

写入 ID	命令	说明
cr_open	cr open	与合并操作分开
cr_close	cr close	Gitea 生命周期
merge	merge execute	需要 --expected-base-sha / --expected-head-sha；cr_open 不会隐式启用此操作
publish_branch	publish execute	推送 git 到已配置的远程仓库
status_set	status set	提交状态 POST
issue / cr_edit ID	对应的命令	参见 contract --json

merge plan 是只读的——会报告 blockers[]；不会执行或授权合并。mergeability: clean 仅表示 git 无冲突。

可选的 merge_policy 豁免项（allow_missing_checks、allow_pending_checks）可放宽无 CI 仓库的检查阻塞项——环境变量：REMOGRAM_ALLOW_MISSING_CHECKS、REMOGRAM_ALLOW_PENDING_CHECKS。在严格检出环境中启用这些选项时，Doctor 会失败。

运维人员覆盖配置的查找顺序：--operator-config → REMOGRAM_OPERATOR_CONFIG → $XDG_CONFIG_HOME/remogram/operator/<provider>-<owner>-<repo>.json。bind 必须与 forge 身份匹配。

边界与信任

Remogram 只输出forge 事实——JSON 中不包含集成权限引用、泳道角色、任务 ID 或交接载荷。

概念	数据包字段	说明
PR 基准分支	forge_target_branch_ref	Forge 报告
PR 头部分支	forge_source_branch_ref	仅作为依据
默认分支	default_branch	不代表集成权限

每个forge 命令数据包都包含 type、schema_version、provider_id、remote_name、repo_id、observed_at、ok。生成方部分（例如 evidence forge-facts --json 输出的 remogram.forge_facts.v1）使用嵌套的生成方字段。信任封装和枚举值；将来自 forge 的字符串（标题、URL）视为不可信文本。

清单命令（refs inventory、cr inventory、whoami、branch protection、cr files、forge changes 等）扩展只读/规划功能——详情见 remogram contract --json 和使用者技能参考。

MCP

Stdio 服务 remogram-mcp 会委托 CLI 处理，与 remogram … --json 输出相同的 JSON。配置方法：examples/mcp/README.md。将 REMOGRAM_CWD 设为使用方仓库的根目录。

实时验证

跨代码托管平台的测试仓库：remogram-smoke（在 GitHub/Gitea 上也有镜像）。安装后使用 --json 数据包；monorepo 烟雾测试对比脚本仅供开发使用。

测试

npm test
npm run test:coverage
npm run security:secrets -- --full-history

覆盖率策略

npm run test:coverage 仅对 @remogram/core 进行插桩；@remogram/cli、@remogram/mcp 和 @remogram/provider-* 不在覆盖范围内。**阈值：**无，不会强制要求达到某个百分比。偏差检查：tests/core/coverage-config.test.mjs。

**CI（GitHub）：**推送到 main 或向其提交 PR 时运行 .github/workflows/ 中的工作流。

软件包

软件包	作用
@remogram/cli	CLI
@remogram/mcp	MCP 适配器
@remogram/core	信封、配置、功能上限
@remogram/provider-{gitea,github,gitlab}-api	支持的代码托管平台后端

Agent 技能

运行 npx skills add attebury/remogram --skill remogram-consumer -g -y（使用方），或运行 --skill remogram-core（贡献者）。技能从 GitHub 发布，而非 npm。

参与贡献

请参阅 CONTRIBUTING.md。