ECC GitHub Epic 确定性同步指南用 /epic-sync 对齐 Issue 正文、标签与本地协调快照【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC/epic-sync是 ECCThe agent harness performance optimization system中面向 GitHub Epic Issue 的确定性同步命令它将 Issue 正文视为唯一事实来源source of truth一键完成「正文 → 协调块 → 标签 → 本地 SQLite 缓存」的对齐闭环。阅读本文后你将掌握github-coordination.js同步子命令的完整用法、协调块Coordination Block的 JSON 结构、标签推导规则与本地快照落库原理并能在 Claude Code / Codex 等 harness 中直接复用这套以 GitHub Issue 为中心的 Epic 治理流程。/epic-sync 是什么一条命令完成四步确定性同步在 commands/epic-sync.md 中/epic-sync被定义为「对 Epic Issue 执行一次确定性同步」Run a deterministic sync for epic issues其核心命令为node scripts/github-coordination.js sync --repo owner/repo命令背后实际完成的四件事原文档定义源码逐一对应读取 Issue 正文作为权威的 Epic 状态以 GitHub Issue 的body为唯一事实来源从中提取协调块将协调块与标签进行对账reconcile根据协调块中的status、validation、review等字段推导出期望标签集合与 Issue 现有标签比对后计算增删为每个 Epic Issue 写出全新的本地快照把同步后的完整状态落库到本地 state store保持 SQLite 缓存与 GitHub 对齐快照记录以github-owner-repo-epic-number为稳定 ID 幂等 upsert。上述实现分别落在 actions.js 的applySync、parsing.js、state.js 与 store.js 中下文逐一展开。运行前提gh CLI、--repo 与默认行为同步依赖 GitHub 官方 CLIgh。在 gh-api.js 中所有 GitHub 操作issue view、issue list、issue edit、issue comment均通过spawnSync(gh, args)执行因此运行前必须已安装并登录gh环境变量GITHUB_TOKEN可用--repo为必填参数格式必须是owner/repo。normalizeRepo会严格校验owner/repo之外的形式如裸字符串justowner、多段路径都会抛出Invalid repo format不传子命令时github-coordination.js 会默认执行syncif (!parsed.command) parsed.command sync默认扫描上限为--limit 100个 Issue状态默认取allstate: options.state || all。完整命令行参考选项与输出格式同步子命令支持以下参数与 github-coordination.js 的usage()完全一致参数说明--repo owner/repo目标 GitHub 仓库必填--limit nsync/unblock 扫描的 Issue 数量上限默认 100--config path可选协调策略配置文件默认读取rootDir/config/github-native-coordination.json--db pathSQLite state store 路径--home dir覆盖 state store 使用的 home 目录默认取$HOME--dry-run只预览变更不修改 GitHub 与本地状态--json输出机器可读 JSON--help, -h显示帮助输出格式由formatOutput决定--json时输出完整 JSONsync/unblock默认走formatCollectionRepo:、Items:与逐条- #number status: title单个 Issue 的操作默认走formatSummaryStatus、Owner、Branch、Validation、Review、Tasks、Dependencies等字段。安全预演--dry-runapplySync中对dryRun的处理是仍完整计算每条 Issue 的期望标签与 body 差异但跳过editIssue与upsertCoordinationWorkItem并把snapshot置为null同时在结果中附带labelPlan{ addLabels, removeLabels }。因此生产环境建议先执行node scripts/github-coordination.js sync --repo owner/repo --dry-run核对标签增删计划与将要重写的正文后再去掉--dry-run正式执行。同步的底层实现applySync 的调用链applySyncactions.js对每条 Issue 依次执行拉取listIssues(repo, { state: all, limit })通过gh issue list --json number,title,body,url,state,labels,author,updatedAt,assignees批量获取读取状态getCoordinationState(issue, policy)—— 从 body 中正则提取协调块 JSON 并解析解析失败时仅输出 warning 并退回默认状态defaultCoordinationState构造下一状态buildIssueStateFromAction(issue, currentState, sync, {...})—— 保留现有status/validation/reviewproject.state缺省回退为backlog并刷新lastAction: sync、lastActionAt、lastSyncAt时间戳推导标签desiredLabelsForState(nextState, policy)生成期望标签集合对账标签syncIssueLabels(repo, issue, nextState, policy, options)计算addLabels与removeLabels移除规则coordination:*前缀或 epic 标签且不在期望集合中非 dry-run 且确有差异时调用gh issue edit --add-label/--remove-label重写正文mergeIssueBody(issue, nextState, policy)渲染新的协调块并替换旧块normalizeBodyForComparison会先把lastSyncAt归一化后再比较避免时间戳抖动造成无谓的editIssue调用落库upsertCoordinationWorkItem(store, repo, trackedIssue, nextState, sync, ...)写入本地 SQLite。最终返回{ repo, syncedAt, count, items }items中每条都包含summarizeStateForOutput的完整字段、labelPlan与snapshot。协调块Coordination BlockIssue 正文中的单一事实来源协调块是同步机制的核心数据载体。其标记名由策略中的sectionMarker决定默认ecc-coordination见 policy.js格式为 HTML 注释包裹的 JSON 代码块!-- ecc-coordination:start -- json { ... }renderCoordinationState[parsing.js](https://link.gitcode.com/i/c75b92e2173a5efb4d1e1c7adb5d0618)渲染出的完整字段包括 - schemaVersion默认 ecc.github.coordination.v1 - kind固定 epic - statusavailable / claimed / ready / blocked / published 等 - owner、branch认领人与分支 - validationpending / passed / failed - reviewnot-requested / requested / approved / changes-requested - project{ state: backlog | ..., fields: {} } - dependencies从正文 #123 引用中提取的依赖 Issue 号数组 - tasks从 ## Tasks / ## Task List 标题下的 - [ ] / - [x] 清单解析出的任务数组 - labels规范化后的标签列表 - lastAction、lastActionAt、lastSyncAt、notes。 mergeIssueBody 负责幂等合并若正文已存在相同 marker 的块则整体替换否则追加到正文末尾。extractCoordinationState 在 JSON 畸形时会抛出 SyntaxError提示 Malformed coordination JSON in bodygetCoordinationState 捕获后降级为默认状态并打印 warning保证同步流程不会因单条 Issue 损坏而中断。相关解析逻辑均有对应测试用例见 [tests/lib/github-coordination.test.js](https://link.gitcode.com/i/c1de2b0716ffd123835857780949c5f4)。 ## 标签与状态映射coord标签的推导规则 同步不直接复制标签而是根据协调状态「推导」期望标签。desiredLabelsForState 的规则默认值定义在 DEFAULT_LABELS[policy.js](https://link.gitcode.com/i/b895168714274744350ab9fdd0ea6427) | 状态 | 追加的标签 | | --- | --- | | 任何 Epic | epic、coordination:synced | | status: available | coordination:available | | status: claimed | coordination:claimed | | status: ready | coordination:ready | | status: blocked | coordination:blocked | | validation: passed | coordination:validated | | review: requested | coordination:review-requested | | review: approved | coordination:review-approved | | review: changes-requested | coordination:review-changes-requested | | status: published | coordination:published | syncIssueLabels 在加标签时只关心「期望集 vs 当前集」的差集删除时只清理 coordination:* 或 epic 标签绝不触碰用户自定义的业务标签避免同步误删。因此 /epic-sync 可以安全地反复运行——它是幂等的idempotent重复执行不会产生标签漂移或正文重复。 ## 本地快照与 SQLite 缓存 同步的最后一步是把每个 Epic 写入本地 state store[store.js](https://link.gitcode.com/i/ad6bbd680919f201a73ba2ce326a1a81) - 快照 IDepicWorkItemId(repo, issueNumber) 生成 github-owner-repo-epic-number保证同一 Epic 跨多次 sync 幂等 upsert - source: github-epic、sourceId 为 Issue 号status 通过 mapStateToWorkItemStatus 映射如 blocked → blocked、claimed/ready/validated → in-progress、published → done、available → open - priorityblocked 状态标记为 high其余为 normal - 完整协调状态、project 投影、标签与动作时间戳存入 metadatasyncedBy: ecc-github-coordination 标识来源。 存储后端由 createStateStore({ dbPath, homeDir }) 创建传 --db false 可禁用本地缓存openStore 直接返回 null此时 upsert 返回 null但 GitHub 侧同步照常执行。 ## 策略配置github-native-coordination.json 同步行为由协调策略控制配置文件默认为 [config/github-native-coordination.json](https://link.gitcode.com/i/d83c0b2b464a01f1f24df4aa6ffdd146)。loadPolicy 会递归合并 DEFAULT_POLICY 与用户配置各子对象按字段级浅合并关键可配置项 - schemaVersion、sectionMarker协调块版本与标记名 - labels覆盖上述全部标签名 - review.required是否强制 review 门禁默认 true - validation.required是否强制校验门禁默认 true - branchModelepicOnly默认 true、taskBranches默认 false即默认不创建任务分支 - projectGitHub Projects 投影开关默认 enabled: false与字段名映射。 可用 --config path 指向自定义策略文件文件缺失时静默回退到 DEFAULT_POLICY存在但无法解析或不是 JSON 对象时则直接抛错。 ## 兼容别名与 Epic 命令族 /epic-sync 提供两个兼容别名[commands/epic-sync.md](https://link.gitcode.com/i/4b06a65d5de41e53459e547c739df5ea) - /projects - /work-items sync-github 它与同族的 Epic 治理命令形成完整生命周期闭环 - [commands/epic-claim.md](https://link.gitcode.com/i/dd12859bcd4d3fad4c0678151eb3bfb5)claim issue-number认领 Epic写入 owner/branch 并追加认领审计评论 - [commands/epic-decompose.md](https://link.gitcode.com/i/95eec7965dca454db9983166cc8f8b26)decompose issue-number从正文任务清单与 #依赖 引用重建任务分解 - validate issue-number校验依赖是否全部关闭并更新 coordination:validated - review issue-number标记 approved/requested/changes-requested - publish issue-number通过校验与 review 门禁后发布status: published - unblock扫描所有 blocked Epic当其依赖全部关闭时自动置为 ready。 其中 publish 会先以 dry-run 方式执行 validate任一检查失败即抛错拒绝发布若策略要求 review 且当前不是 approved 也会拒绝。sync 本身是所有状态流转的公共底座——无论之前执行过哪条命令/epic-sync 都能把 GitHub 现状重新收敛为一致的协调块、标签与本地快照。 ## 安全边界与已知限制 - **写操作需谨慎**sync 会批量改写 Issue 正文与标签务必先用 --dry-run 与 --limit 小范围验证 - **gh shim 信任边界**环境变量 ECC_GH_SHIM 仅用于隔离测试环境让 gh 调用重定向到测试脚本生产环境设置它等同于允许任意脚本以调用者权限执行[gh-api.js](https://link.gitcode.com/i/d20e958a4627de891c5149459e17bdc6) 有明确注释警告 - **claim 非原子性**applyClaim 是「读→检查→写」序列并发调用可能双重认领源码注释建议通过外部串行化如任务队列规避——sync 本身不受此影响因为它是基于当前状态的幂等收敛。 ## 小结 /epic-sync 用一次幂等同步把「Issue 正文 协调块 标签 本地快照」四层状态收敛为同一事实。对多 Agent / 多 harness 协作场景而言它提供了可审计、可回放、可预演的 Epic 治理基线正文中的 JSON 协调块是机器可读的单一事实来源coordination:* 标签是 GitHub 原生的状态索引SQLite 快照则是本地可离线查询的投影。配合 claim / validate / review / publish / unblock 命令族即可在不引入第三方项目管理工具的前提下用纯 GitHub 原语跑通完整的 Epic 生命周期。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考