feat(architect-review): add architecture-level PR review action by Svtter · Pull Request #64 · sun-praise/opencode-actions

Svtter · 2026-05-13T01:38:37Z

Summary

Add architect-review/action.yml — a new action that reviews PR changes from an architecture perspective (coupling, module placement, layering, interface design, shotgun surgery)
Add .github/workflows/architect-review.yml — example workflow for running architect review on PRs
Update CI and smoke-test workflows to include the new action
Update README.md with architect-review documentation

Design decisions

Independent action alongside review, not merged — keeps concerns separated and allows teams to opt-in independently
Architecture context via AGENTS.md — opencode reads this file automatically; the prompt instructs the model to check it for project conventions
Same output format as review (阻塞项/建议项) — consistent UX across all review actions
Three-level verdict: 架构合理 / 架构有疑虑 / 架构有问题 — mirrors the review action's 可合并/有条件合并/不可合并 pattern
Cache key prefixed architect-review-opencode- — avoids cache collisions with other actions

Closes #63

🤖 Generated with Claude Code

github-actions · 2026-05-13T01:39:54Z

发现遗漏

摘要

架构审查 action 的核心功能已实现，但在对比 Issue #63 规范后发现一处遗漏。

MEDIUM

Issue 要求自动分析目录结构，但 prompt 缺少 AGENTS.md 不存在时的回退策略

Issue #63 的"待确认"条目中明确提到**"自动分析目录结构"**作为架构上下文注入的可选方案之一。PR 选择了 AGENTS.md 方案，这本身是合理的设计决策。但 prompt（architect-review/action.yml:83）仅说 "read AGENTS.md (or CLAUDE.md) if it exists"——如果 AGENTS.md 不存在，模型将完全没有项目的目录结构、分层约定等架构上下文，而 issue 期望的是至少能自动分析目录结构来推断约定。建议在 prompt 末尾增加一段回退指令：如果 AGENTS.md/CLAUDE.md 都不存在，则要求模型通过阅读项目目录树和关键配置文件来推断架构约定。应在 architect-review/action.yml 的 prompt 输入默认值中补充。

opencode session | github run

github-actions · 2026-05-13T01:39:59Z

有条件合并

简要总结

该 PR 新增 architect-review action，与现有 review action 架构一致：复用相同的 setup-opencode/github-run-opencode 基础设施、相同的输入参数列表、相同的 cache 模式。整体设计合理，代码质量良好，与现有模式高度一致。

阻塞项

README 描述未更新：README.md:202 行 smoke-tests all four actions 在 PR 添加 architect-review 到 CI 和 smoke-test 后仍为旧值。该描述原来就说"four"但实际列出 5 个 action，现在更应更新为正确数字（如"all actions"或明确列出全部）。

建议项

无其他建议。该 PR 代码质量良好，安全方面无问题（仅通过环境变量传递已有 API key），性能无影响（仅增加一次 opencode github run 调用），缓存 key 前缀 architect-review-opencode- 避免了与其他 action 的冲突。

opencode session | github run

github-actions · 2026-05-13T05:51:16Z

发现遗漏

摘要

对照 Issue #63 的规范，架构审查 action 的核心功能已基本实现：独立 action、复用 opencode 引擎、AGENTS.md 上下文注入、结构化输出。存在一处中等严重度的遗漏。

MEDIUM

AGENTS.md/CLAUDE.md 不存在时缺少架构上下文回退策略

Issue #63 的"待确认"中明确要求注入项目架构上下文（目录结构、分层约定、模块职责），并列出三种候选方案：AGENTS.md / 自定义配置 / 自动分析目录结构。PR 选择了 AGENTS.md 方案（合理的设计决策），但 prompt（architect-review/action.yml:83）仅说 "read AGENTS.md (or CLAUDE.md) if it exists"——如果这两个文件都不存在，模型完全没有项目的架构上下文（不知道目录布局、分层约定、模块职责），只能凭通用原则审查。Issue 期望的"自动分析目录结构"作为回退方案来实现。

建议在 architect-review/action.yml 的 prompt 默认值末尾增加回退指令：当 AGENTS.md/CLAUDE.md 均不存在时，要求模型通过 ls/tree 等命令浏览项目根目录的目录结构，并读取关键配置文件（如 package.json、cargo.toml、pyproject.toml）来推断项目的架构约定。

opencode session | github run

github-actions · 2026-05-13T05:53:43Z

审查结论

README "four actions" 与实际数量不符

README.md:202 的 "smoke-tests all four actions" 描述中，"four" 与实际列出的 action 数量不符：原已有 setup-opencode、run-opencode、github-run-opencode、review、feature-missing 共 5 个，该 PR 又新增了 architect-review。这是一个存在已久的文档缺陷，该 PR 修改了 README 但未修正此行。

`.github/workflows/architect-review.yml` 引用 feature 分支

第二笔提交 4efce15 将示例 workflow 中的 uses: Svtter/opencode-actions/architect-review@v2 改为了 @feat/architect-review。合入主分支后 feat/architect-review 分支将被删除，导致该 workflow 引用失效。

AGENTS.md 不存在时缺少回退策略

prompt (architect-review/action.yml:83) 仅要求读取 AGENTS.md/CLAUDE.md，未提供两者都不存在时的回退方案。这与 Issue #63 中"自动分析目录结构"的预期不完全一致。

有條件合並

架构审查 action 整体实现良好，与现有的 review action 结构一致，prompt 覆盖了耦合、模块放置、分层、接口设计、霰弹式修改等核心架构关注点，缓存 key 前缀 architect-review-opencode- 避免了与其他 action 的碰撞。

阻塞项：

.github/workflows/architect-review.yml:23 的 uses: Svtter/opencode-actions/architect-review@feat/architect-review 需改回 @v2（回退第二笔提交），与其他示例 workflow 保持一致。feat/architect-review 合入后即删除，将导致引用失效。

建议项：

README.md:202 "smoke-tests all four actions" 描述中的 four 数字不准确（原已列出 5 个 action，现新增为 6 个），建议改为动态表述如 "all actions" 或更新为正确数字。
architect-review/action.yml prompt 中没有考虑 AGENTS.md/CLAUDE.md 都不存在时的回退方案，建议补充一条回退指令：要求模型通过阅读项目目录树和关键配置文件（如 package.json、Cargo.toml 等）来推断架构约定。

opencode session | github run

Add a new architect-review action that focuses on structural concerns like coupling, module placement, layering, interface design, and shotgun surgery risks. Reads AGENTS.md/CLAUDE.md for project architecture context and outputs structured feedback consistent with the review action format. Closes #63 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

The architect-review action is new and not yet available in the v2 tag. Reference the feature branch so CI can find the action code. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

@v2

- Add git identity config step to architect-review workflow (fixes 'Author identity unknown' error when opencode agent tries to commit) - Change workflow ref from @feat/architect-review back to @v2 - Add fallback strategy in prompt when AGENTS.md/CLAUDE.md don't exist - Fix README 'four actions' to 'all actions' with correct action list

- Resolve README.md conflict: include both spec-coverage and architect-review - Add architect-review to review actions comparison table - Add architect-review to Publishing Checklist - Add comment explaining git identity in workflow - Optimize find command to exclude node_modules/.git/vendor in prompt

github-actions · 2026-05-14T14:57:42Z

无遗漏

对照 Issue #63 规范逐一核查：

规范要求	实现状态
新增架构审查 action（独立于 review）	✅ `architect-review/action.yml` 独立 composite action
审查维度：耦合、模块放置、分层、接口、霰弹式修改	✅ prompt 覆盖全部 5 个维度 + 额外增加了 consistency
复用 opencode agent 作为执行引擎	✅ 通过 `github-run-opencode` 的 Python 脚本执行
Prompt 包含项目架构上下文	✅ 读取 AGENTS.md/CLAUDE.md，且已包含两者都不存在时自动分析目录树和配置文件的回退策略
结构化输出（问题+建议+严重程度）	✅ 三档 verdict（合理/有疑虑/有问题）+ 阻塞项/建议项格式
CI/smoke-test 集成	✅ `.github/workflows/ci.yml` 和 `smoke-test.yml` 已添加
README 文档	✅ 已更新，含用法示例和对比表格
Cache key 隔离	✅ 前缀 `architect-review-opencode-`
待确认项（独立/合并、上下文注入方式、输出格式）	✅ 全部做出明确设计决策并一致实现

Issue #63 中三个"待确认"条目属于设计决策而非硬性需求，PR 均做出了合理选择并在 description 中说明了理由，代码实现与此一致。prompt 已包含 AGENTS.md/CLAUDE.md 不存在时的自动分析回退（ls -la/find 目录树 + 读取 package.json 等配置），覆盖了 issue 中提到的"自动分析目录结构"方案。

opencode session | github run

github-actions · 2026-05-14T14:57:53Z

可合并

该 PR 新增 architect-review 独立 action，代码结构与现有 review action 高度一致，所有之前 review 中提出的问题已在当前 HEAD 修复。

阻塞项：无

建议项：

architect-review 缺少 review action 内置的模型降级链（explicit model → MODEL_NAME → 默认模型），当前 model input 为空时不会自动 fallback。不过示例 workflow 已通过 ${{ vars.MODEL_NAME }} 兜底，不算功能缺陷，但考虑对齐 review 行为以降低用户心智负担。

opencode session | github run

@v2

The v2 tag does not include architect-review yet (new in this PR). Use ./architect-review local path reference so CI can find the action. TODO: switch back to @v2 after release.

github-actions · 2026-05-14T15:01:19Z

remote: Permission to sun-praise/opencode-actions.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/sun-praise/opencode-actions/': The requested URL returned error: 403

opencode session | github run

github-actions · 2026-05-14T15:01:23Z

无遗漏

对照 Issue #63 规范逐一核查，所有需求均已完整实现：

规范要求	实现状态
新增独立架构审查 action	✅ `architect-review/action.yml` — 独立 composite action
审查维度：耦合、模块放置、分层、接口设计、散弹枪修改	✅ Prompt 覆盖全部 5 个维度 + 额外增加 consistency
复用 opencode agent	✅ 通过 `github-run-opencode` Python 脚本执行
Prompt 包含项目架构上下文	✅ AGENTS.md/CLAUDE.md 作为主要来源，两者不存在时自动分析目录树和配置文件作为回退
结构化输出（问题+建议+严重程度）	✅ 三档 verdict（合理/有疑虑/有问题）+ 阻塞项/建议项格式
CI/smoke-test 集成	✅ `ci.yml` 和 `smoke-test.yml` 已添加
README 文档	✅ 含用法示例和对比表格
Cache key 隔离	✅ 前缀 `architect-review-opencode-`

先前 review 指出的 AGENTS.md 不存在时无回退策略的 gap 已在当前 HEAD 修复（action.yml:85-85 已加入自动分析目录结构和配置文件的回退指令）。workflow 中使用 ./architect-review 本地路径避免了 feature 分支引用问题。三个"待确认"设计决策均在 PR body 中明确说明且代码一致实现。

opencode session | github run

github-actions · 2026-05-14T15:01:30Z

可合并

分析总结

PR 实现了 architect-review 独立 action，代码结构与现有 review action 高度一致：复用相同的 setup-opencode/github-run-opencode 基础设施、相同的输入参数体系、相同的缓存模式。此前多轮 review 中提出的问题（README 描述、workflow 分支引用、AGENTS.md 回退策略）均已在当前 HEAD 修复。

阻塞项：无

建议项：

architect-review 缺少 review action 内置的模型降级链（inputs.model → MODEL_NAME → 默认模型）。当前 model input 为空时不会自动 fallback。示例 workflow 通过 ${{ vars.MODEL_NAME }} 兜底，但若用户在仓库中未设置该变量将导致模型为空。建议对齐 review 行为以降低用户心智负担。

opencode session | github run

github-actions · 2026-05-14T15:02:55Z

架构有疑虑

该 PR 新增的 architect-review action 整体设计合理：作为独立 composite action 置于 architect-review/ 目录，复用 setup-opencode/github-run-opencode 共享基础设施，输入参数体系与现有 review/feature-missing/spec-coverage 保持一致，cache key 前缀 architect-review-opencode- 避免了 cache 碰撞。prompt 覆盖了耦合、模块放置、分层、接口设计、霰弹式修改和一致性六个架构审查维度，并在 AGENTS.md/CLAUDE.md 不存在时提供了自动分析目录结构和配置文件的回退策略，已解决之前 review 中指出的 gap。CI、smoke-test、README 的集成均按已有模式完成。

阻塞项：无

建议项：

权限约束缺失：architect-review/action.yml 未设置 GITHUB_RUN_OPENCODE_PERMISSION 环境变量，而 review、feature-missing、spec-coverage 三个同类只读 action 均通过该变量对 opencode agent 施加了 git 写操作的限制（如 {"edit":"deny","bash":{"git commit *":"deny","git push *":"deny","git add *":"deny",...}}）。当前仅靠 prompt 中的 "DO NOT modify any code" 指令约束，缺少基础设施层的一致性防护。建议添加该权限约束，与其余只读 review 类 action 对齐。

opencode session | github run

… write ops Aligns with review/feature-missing/spec-coverage actions that already set this env var to enforce read-only mode at the infrastructure layer.

github-actions · 2026-05-14T15:06:18Z

经过对 Issue #63 规范与 PR 实现的对比检查，所有规范要求均已完整实现：

规范要求	实现位置
新增独立架构审查 action	`architect-review/action.yml` — 独立 composite action
审查维度：耦合、模块放置、分层、接口设计、散弹枪修改	Prompt 第 1-5 项全部覆盖（另增加第 6 项 Consistency）
复用 opencode agent 作为执行引擎	通过 `github-run-opencode` Python 脚本执行
Prompt 包含项目架构上下文（目录结构、分层约定、模块职责）	Prompt 读取 AGENTS.md/CLAUDE.md，且第 85 行已包含回退策略（自动分析目录树 + 配置文件推断约定）
结构化输出（问题 + 建议 + 严重程度）	三档 verdict（架构合理/有疑虑/有问题）+ 阻塞项/建议项格式
三个"待确认"设计决策	PR body 已做出明确决策，代码一致实现

README 描述（第 242 行）已更新为列出所有 7 个 action，无数字不一致问题。Workflow 引用使用 ./architect-review 本地路径并标注 TODO 注释，无分支引用风险。只读权限约束（GITHUB_RUN_OPENCODE_PERMISSION，第 264-265 行）已配置，限制了 git 写操作。

无遗漏

opencode session | github run

github-actions · 2026-05-14T15:06:24Z

现在让我对照 review/action.yml 看看模型降级链的处理方式：

根据对当前 PR HEAD（基于实际读取的文件内容）的完整分析：

已修复的过往问题：

AGENTS.md/CLAUDE.md 不存在的回退策略 → 已在 architect-review/action.yml:85 添加自动分析目录树+配置文件指令
README "four actions" 数字不准确 → 已在 README.md:242 显式列出全部 7 个 action
workflow 引用 feature 分支 → 已在 .github/workflows/architect-review.yml:30 改用 ./architect-review 本地路径，并加了 TODO 注释
缺少 GITHUB_RUN_OPENCODE_PERMISSION → 已在 architect-review/action.yml:264-265 添加，与 review/action.yml 一致
模型降级链不完整 → 两者都通过 GITHUB_RUN_OPENCODE_MODEL: ${{ inputs.model }} 传递给同一份 Python 脚本，行为无差异

可合并

架构审查 action 整体实现质量高，与现有 review action 结构完全对齐，prompt 覆盖了耦合、模块放置、分层、接口设计、霰弹式修改、一致性六个架构维度，并在 AGENTS.md/CLAUDE.md 不存在时有目录结构自动分析回退。cache key 前缀 architect-review-opencode- 避免了碰撞，权限约束 GITHUB_RUN_OPENCODE_PERMISSION 已添加。CI、smoke-test、README 均已按已有模式正确集成。

阻塞项：无

建议项：无

opencode session | github run

github-actions · 2026-05-14T15:06:39Z

remote: Permission to sun-praise/opencode-actions.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/sun-praise/opencode-actions/': The requested URL returned error: 403

opencode session | github run

github-actions · 2026-05-14T15:07:21Z

架构合理

该 PR 新增的 architect-review action 在架构上与现有 review、feature-missing、spec-coverage 等 convenience action 高度一致：同样是顶层独立目录的 composite action，复用 setup-opencode/ 做安装、github-run-opencode/ 做执行引擎，使用相同的输入参数体系和缓存模式。prompt 完整覆盖耦合、模块放置、分层、接口设计、霰弹式修改、一致性六个架构维度，且在 AGENTS.md/CLAUDE.md 不存在时提供了自动分析目录树和配置文件的回退策略。权限约束 (GITHUB_RUN_OPENCODE_PERMISSION) 已与其他只读 action 对齐。CI、smoke-test、README 集成均遵循已有模式。

阻塞项：无
建议项：

architect-review/action.yml 与 review/action.yml 存在大量结构化重复（retry 逻辑、缓存设置、版本解析、路径计算等）。如果未来想改变这些共享行为，需要对六个 convenience action 逐一修改。这属于项目已有的架构债务，非本 PR 引入，但建议考虑将共享步骤提取为独立 composite action 或使用 YAML anchor 重构。

opencode session | github run

…pt step - Add `architecture-context` input: comma-separated file paths for project architecture docs, appended to the prompt via shell step - Add `cleanup-error-comments` input: auto-delete error comments on failed runs - Add `build-prompt` shell step: assembles default prompt + architecture context, outputs via GITHUB_OUTPUT multiline heredoc - Change `prompt` input default to empty string (built-in prompt used when blank) - Zero engine changes — prompt assembly is purely in action.yml shell steps

github-actions · 2026-05-18T14:31:10Z

所有 spec 需求均已对照检查，结果是完全覆盖。

发现遗漏

摘要

对比 Issue #63 规范逐一核查：独立 action、5 个架构审查维度、opencode agent 复用、架构上下文注入（AGENTS.md + 回退自动分析）、结构化输出、CI/smoke-test 集成、README 文档、cache key 隔离——均已完整实现，且实现超出 spec 预期（额外增加了 Consistency 维度、architecture-context 自定义输入、fallback-models 降级链、GITHUB_RUN_OPENCODE_PERMISSION 只读权限约束）。

CRITICAL

无

MEDIUM

无

LOW

无

opencode session | github run

github-actions · 2026-05-18T14:31:19Z

可合并

该 PR 新增 architect-review 独立 action，与现有 review action 结构高度一致，prompt 覆盖耦合、模块放置、分层、接口设计、霰弹式修改、一致性六个架构维度，AGENTS.md/CLAUDE.md 不存在时已包含自动分析目录树和配置文件的回退策略，权限约束 GITHUB_RUN_OPENCODE_PERMISSION 已配置。CI、smoke-test、README 集成均按已有模式完成。

阻塞项：无

建议项：architect-review/action.yml 新增了 cleanup-error-comments 输入（第125-131行），但现有 review、feature-missing、spec-coverage 均未提供该输入。虽非功能缺陷，但与同类 action 存在不一致。建议保持对齐：要么全部添加，要么暂不引入该输入。

opencode session | github run

github-actions · 2026-05-18T14:31:42Z

remote: Permission to sun-praise/opencode-actions.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/sun-praise/opencode-actions/': The requested URL returned error: 403

opencode session | github run

github-actions · 2026-05-18T14:33:25Z

架构有疑虑

架构分析

该 PR 新增的 architect-review action 整体设计合理：与 review、feature-missing、spec-coverage 一样作为顶层独立目录部署，复用 setup-opencode/（安装）和 github-run-opencode/（执行引擎）共享基础设施，使用相同的输入参数体系和缓存策略。CI、smoke-test、README 集成均按已有模式完成，cache key 前缀 architect-review-opencode- 避免了碰撞，GITHUB_RUN_OPENCODE_PERMISSION 只读权限约束已配置。prompt 覆盖了耦合、模块放置、分层、接口设计、霰弹式修改、一致性六个维度，且在 AGENTS.md/CLAUDE.md 不存在时提供了目录结构自动分析回退。

与同类 action 的详细对比：

维度	review	feature-missing	spec-coverage	architect-review
Prompt 传递	input default YAML	input default YAML	input default YAML	build-prompt step (heredoc)
`cleanup-error-comments`	❌	❌	❌	✅ 新增
`architecture-context`	❌	❌	❌	✅ 新增
`GITHUB_RUN_OPENCODE_PERMISSION`	✅	✅	✅	✅

阻塞项：无

建议项：

cleanup-error-comments 输入仅在 architect-review 引入，与同类 action 不一致 — review、feature-missing、spec-coverage 均未提供该输入，但它属于 PR comment 清理的基础设施功能，理论上应与同类 action 对齐。建议要么全部添加，要么暂不引入该输入。

opencode session | github run

sun-praise deleted a comment from github-actions Bot May 13, 2026

洋葱 and others added 4 commits May 14, 2026 22:52

fix(ci): reference current branch for architect-review action

21cb202

The architect-review action is new and not yet available in the v2 tag. Reference the feature branch so CI can find the action code. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Svtter force-pushed the feat/architect-review branch from 659a3dc to cf1ff37 Compare May 14, 2026 14:56

fix(ci): use local path for architect-review action

1abb455

The v2 tag does not include architect-review yet (new in this PR). Use ./architect-review local path reference so CI can find the action. TODO: switch back to @v2 after release.

fix(architect-review): add GITHUB_RUN_OPENCODE_PERMISSION to deny git…

b5049b2

… write ops Aligns with review/feature-missing/spec-coverage actions that already set this env var to enforce read-only mode at the infrastructure layer.

Svtter mentioned this pull request May 18, 2026

feat: add architect-review action #78

Closed

Svtter merged commit fccd066 into main May 18, 2026
4 checks passed

Svtter mentioned this pull request May 27, 2026

Bump version to 3.0.0 #125

Merged

Conversation

Svtter commented May 13, 2026

Summary

Design decisions

Uh oh!

github-actions Bot commented May 13, 2026

摘要

MEDIUM

Uh oh!

github-actions Bot commented May 13, 2026

简要总结

阻塞项

建议项

Uh oh!

github-actions Bot commented May 13, 2026

摘要

MEDIUM

Uh oh!

github-actions Bot commented May 13, 2026

审查结论

README "four actions" 与实际数量不符

.github/workflows/architect-review.yml 引用 feature 分支

AGENTS.md 不存在时缺少回退策略

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

分析总结

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 14, 2026

Uh oh!

github-actions Bot commented May 18, 2026

摘要

CRITICAL

MEDIUM

LOW

Uh oh!

github-actions Bot commented May 18, 2026

Uh oh!

github-actions Bot commented May 18, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 18, 2026

架构分析

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

`.github/workflows/architect-review.yml` 引用 feature 分支