企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent记忆
• MCP服务

本篇技术指南讲解 Engram 仓库内置的深度技术审查技能（skills/pr-review-deep/SKILL.md）——一套面向任何外部或内部贡献合流前的标准化审查协议。它规定了审查触发的时机、五步审查流程（读完整 diff → 本地跑测试 → 验证 API/契约与迁移安全 → 核对文档与实现 → 检查提交卫生），以及决定 merge 还是 request changes 的 Merge Gate 判定标准。读完本文，你将掌握在 Engram 的多包仓库（store / server / cloud / dashboard / plugin）中执行一次可辩护、可追溯、能落地为"可操作修改意见"的 PR 审查的完整方法，并理解该协议如何与仓库的自动化门禁（CI、lint 棘轮、dead-code 棘轮、性能棘轮、Transient Artifact Policy）配合运转。

何时启用本技能：触发条件

按技能文档的 frontmatter，engram-pr-review-deep的 Trigger 是「Reviewing any external or internal contribution before merge」——任何外部或内部贡献在合并之前。具体到使用场景，技能文档明确了三类典型情况：

• Evaluating PRs from contributors：评估来自贡献者的 PR；
• Reviewing risky refactors：审查有风险的重构；
• Deciding merge vs request-changes：在"合并"与"请求修改"之间做决策。

该技能在仓库的技能索引（AGENTS.md）中被列为engram-pr-review-deep，与engram-branch-pr（PR 创建流程）、engram-commit-hygiene（提交卫生）、engram-docs-alignment（文档对齐）、engram-testing-coverage（测试与覆盖率）等技能共同构成贡献与审查闭环。审查者通常在 reviewer 角色下同时加载本技能与 审查相关的维护者视角文档，后者提供了面向审查与规划的主维护者清单。

五步审查流程：把"审"从印象变成证据

技能文档给出核心 Review Protocol，原文为五步，下面逐条展开并结合仓库证据说明每一步如何落地。

1. 读完整 diff，而不是只看 summary

第一条要求审查者阅读git diff的完整内容（包括被修改、新增、复制、重命名路径的目的地），而非依赖 PR 标题或摘要。

这条规则在仓库里有两层含义：

• scope 一致性：CONTRIBUTING.md明确要求 "Keep PR scope focused — one logical change per PR"。读完完整 diff 才能判断一个 PR 是否夹带了无关改动（如依赖升级混入功能提交）。
• Transient Artifact Policy 的全量检查：维护者 playbook 强调 "Inspect the complete changed-file set, including added, modified, copied, and renamed destinations"，并逐一对照 CONTRIBUTING.md 的违禁清单——例如仓库根的plan.md、agent-handoff.md、*.db文件、**/.idea/**、**/*.exe等。部分缩写的清单不足以完成审查，必须以策略原文为准。这条政策由 PR 验证 job 自动执行（Check PR Has No Transient Artifacts），但人工读 diff 仍是第一道关。

2. 本地运行相关测试：验证是候选方的证据

技能文档要求 "Run relevant tests locally"。这与仓库的「验证所有权」原则一脉相承——skills/testing-coverage/SKILL.md的表述非常精确：

Verification is evidence about the candidate; CI is the automated execution venue, not a substitute for local focused evidence.

翻译成审查动作就是：本地只跑"聚焦的、相关的"测试，不重复 CI 的广谱套件。具体命令模式（见skills/branch-pr/SKILL.md与CONTRIBUTING.md）：

# 行为变更：先跑聚焦回归测试，再跑受影响包的全量测试 go test ./internal/store -run '<回归测试名>' go test ./internal/store # 全量单元测试（CI 负责，本地按需） go test ./...

边界要点：

• 聚焦回归 + 受影响包是行为变更 PR 的必做项；docs-only 变更记录N/A — documentation-only; no Go behavior changed即可；
• 当改动横跨包边界（例如触及 store 与 server），应在两侧各找对应测试，因为 playbook 明确指出 "Expensive bugs appear between packages, not in isolated helpers"；
• 当 PR 尚未推送、或风险等级高时，审查者应额外运行适用的本地检查，并把"跑不了的检查"如实报告为缺失证据，而不是声称 CI 已覆盖。

3. 验证 API / 契约与迁移安全

这是技术审查中最容易放行 bug 的环节，技能文档要求 "Validate API/contracts and migration safety"。

API 契约验证：Engram 的 HTTP API 在 内部 server 包 实现，E2E 测试集中在internal/server/server_e2e_test.go（以//go:build e2e标记）。契约审查的典型关注点，以internal/server/prompt_capture_decision.go为例：

• 请求体字段非空校验（source必须是claude-code、cwd非空、content为字符串）；
• 用decoder.DisallowUnknownFields()拒绝未知字段，且解码尾部必须io.EOF才算合法 JSON；
• 响应中的错误码与 JSON 结构确定性（jsonError/jsonResponse的稳定形状）。

迁移安全：store 层 schema 变更必须被既有或新增测试覆盖，维护者 playbook 的 local store 变更清单明确要求 "Migration/schema is covered by existing or new tests"，同时若公开语义变化，需同步更新DOCS.md#database-schema。仓库中internal/store下存在大量迁移与 DDL 测试（如store_migration_test.go、store_legacy_ddl_test.go）可作为审查对照：每个 schema 版本改动都应有对应的迁移测试。

4. 文档与实现逐项核对

技能文档要求 "Check docs against implementation"，这一条对应skills/docs-alignment/SKILL.md的四个规则：

1. 文档描述当前行为，而非预期行为；
2. 代码变更与文档更新必须同一 PR；
3. 发布前验证示例；
4. 移除对废弃文件/端点/脚本的引用。

审查时的核对项（来自 docs-alignment 的 Verification checklist）：

• 端点名称与 server 路由一致；
• 脚本名称与仓库路径一致；
• 命令示例确实能按文档执行；
• 跨 Agent 的说明仍然准确。

维护者 playbook 进一步要求："If you change an endpoint, command, or setup, update docs in the same change"，且不重复DOCS.md之外的完整 API 引用。

5. 标记提交卫生违规

技能文档要求 "Flag commit hygiene violations"。Engram 的提交卫生由 GitHub ruleset 强制执行（推送即拒绝），审查者需要核对skills/commit-hygiene/SKILL.md中的规则：

• 提交信息必须匹配 Conventional Commits 正则：^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
• 分支名必须匹配^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$；
• 严禁Co-Authored-Bytrailer；
• 一个提交只做一件逻辑变更；描述用祈使语气（"add" 而非 "added"）；
• 变更路径不得触碰 Transient Artifact Policy 禁止项。

常见违规样例（推送即被拒）：Fix bug（无 type 前缀）、feat: Add login（描述应小写）、FEAT(cli): add flag（type 必须小写）、feat (cli): add flag（scope 前不能有空格）。

Merge Gate：什么条件下允许合并

技能文档给出明确的合流判定条件——Merge only when：

• checks are green：自动化检查全绿（详见下文"自动化门禁"一节）；
• risk is understood：风险已被理解并确认；
• blockers are resolved：阻塞项已解决；
• scope is coherent：变更范围自洽（一个 PR 一个逻辑变更）。

Otherwise request changes with actionable items——否则请求修改，且必须给出可操作的修改项（而非笼统的"请改进"）。

这与skills/branch-pr/SKILL.md中"PR 六项必需检查全过才能合并"的门禁互为表里；审查者给出的 request-changes 意见应能映射到具体文件、具体行、具体命令或具体规则。

与自动化门禁的配合：审查者眼里的 checks are green

"checks are green" 在 Engram 不是一句空话，它由一套分层自动化构成（详见CONTRIBUTING.md）：

合并前六个上下文必须全部通过。此外还有三类「棘轮」机制值得审查者留意，因为它们直接影响 "risk is understood" 的判断：

• Lint 棘轮：CI 使用 golangci-lint v2.13.2（errcheck、staticcheck、unused），只报告PR 新引入的发现；本地执行需精确版本，见Makefile的make lint。
• Dead-code 棘轮：make deadcode-check用golang.org/x/tools/cmd/deadcode@v0.30.0对比.deadcode-baseline.txt，新增不可达函数即失败；make deadcode-baseline仅在有意接受权衡时刷新基线，禁止为容纳新债而更新。
• 性能棘轮：make perf-check对比 store 搜索/扫描基准与已审查基线；CI 在 main 推送时以同一 runner 对比前一个 SHA 的基准，捕获统计显著的回退，但不把耗时当单测断言。基线记录产生它的 OS/架构/CPU，只在匹配主机上可比。

审查者应如实报告：PR CI 未运行前不得声称其已通过；lint、Windows 相关检查等非必需上下文也要按实际结果报告。

审查辅助工具与命令

Doctor 诊断

engram doctor是审查者确认"候选变更没有破坏本地存储健康"的辅助手段，支持--json、--project <name>、--check <name>参数，并有repair、discard-empty-prompt子命令（见cmd/engram/doctor.go）。完整说明见docs/DOCTOR.md。

Conflicts 冲突面

对涉及记忆冲突语义的变更，可运行cmd/engram/conflicts.go的list/show/stats/scan/deferred子命令确认关系判定行为未被破坏。

所有权速查

playbook 的 quick ownership decision 可帮助审查者判断"这个改动应该落在哪个包"，进而决定找哪里的测试与文档：

Does the change affect stored data? store/cloudstore Does it affect HTTP input/output? server/cloudserver Does it affect browser experience? dashboard Does it affect background replication? autosync Does it affect remote transport? remote/cloudserver Does it affect a specific agent or host? plugin/setup Does it affect human commands? cmd/engram + docs

警告信号（Warning Signs）

审查中如果看到下列模式，大概率需要 request changes（来源：docs/codebase/maintainer-playbook.md）：

同时，从源码结构看，仓库的边界导向（skills/architecture-guardrails/SKILL.md）与审查直接相关：本地 SQLite 是事实来源（source of truth），云是复制与共享访问；org 级策略必须 server 端强制而非仅存在于 UI；同步契约变更需同时覆盖 push 与 pull 路径。审查者应在这些边界上重点取样测试证据。

审查清单：把协议折叠成动作

把技能文档的协议折叠成一份可直接对照的审查清单：

1. 阅读完整 diff（含新增/修改/复制/重命名目的地），确认 scope 一致
2. 对照 Transient Artifact Policy 全量核对变更文件集
3. 行为变更：本地跑聚焦回归 + 受影响包测试，记录实际命令与结果
4. 验证 API 契约（字段校验、错误码、JSON 确定性）与迁移安全
5. 文档与实现逐项核对（端点名、脚本名、命令示例、跨 Agent 说明）
6. 检查提交卫生（Conventional Commits、分支命名、无Co-Authored-By、单逻辑提交）
7. 判断 Merge Gate 四项：checks green / risk understood / blockers resolved / scope coherent
8. 不满足则输出可操作的request-changes 项，逐条对应文件、行、命令或规则

这套协议的价值在于：它把"审 PR"从个人经验变成了可复现、可传递、有证据支撑的工程流程——每个放行或打回的决定，都能在 diff、测试输出、文档和门禁配置中找到落点。

• 人工智能
• AI Agent
• Agent记忆
• MCP服务