Redtropig/harness-anchor

# harness-anchor ## 它是什么 `superpowers` 为你的 agent 提供**流程方法论**（头脑风暴 → 计划 → TDD → 审查）。 `harness-anchor` 为你的 agent 提供**环境与状态纪律**（我在哪里、当前激活的功能是什么、怎样才算“完成”、存在哪些文件、当遇到不熟悉的工具卡住时该怎么办）。 它们共同构成了一个完整的 harness，基于 Anthropic 的[面向长时间运行 Agent 的有效 Harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 以及 [learn-harness-engineering](https://walkinglabs.github.io/learn-harness-engineering/) 的 5 个子系统模型： | 子系统 | 提供者 | |---|---| | Instructions | superpowers + harness-anchor (`using-harness-anchor`) | | State | **harness-anchor** (`feature_list.json`, `progress.md`, `session-handoff.md`, `golden-rules.md`) | | Verification | **harness-anchor** (`anti-hallucination-gates`, `/verify`) + superpowers (TDD) | | Scope | **harness-anchor** (active-feature lock, scope-jump detection) | | Lifecycle | **harness-anchor** (`init.sh`, `/session-end`) | ## 安装说明（本地开发 marketplace） ``` # 1. 注册 marketplace（从已发布的 GitHub repo） claude /plugin marketplace add Redtropig/harness-anchor # 2. 安装 claude /plugin install harness-anchor@harness-anchor-local # 3. 启动 session；SessionStart hook 注入 harness-anchor banner claude ``` 在会话开始时，你应该能在 agent 的感知中看到一个 `...` 块。 ## 在新项目中快速开始 ``` # 在你的项目根目录下： /anchor # scaffolds AGENTS.md, feature_list.json, init.sh, progress.md, # session-handoff.md, PROJECT-TOC.md, context-budget.md, golden-rules.md /cpp-init # (C/C++ projects only) tunes init.sh, drops .clang-format, # .clang-tidy, scripts/sanitizer-build.sh /index-project # builds PROJECT-TOC.md from your git-tracked files bash init.sh # health-check the environment # 然后正常工作；在 session 结束时： /session-end # writes structured handoff, appends progress.md, suggests commit ``` ## 技能（共 14 个 — 根据会话上下文自动触发） | 技能 | 触发时机 | |---|---| | `using-harness-anchor` | 每次会话开始时自动加载（元技能） | | `project-indexing` | 定位文件；在使用 Glob 前查阅 `PROJECT-TOC.md` | | `feature-state-keeper` | 启动/推进/完成/阻塞某个功能 | | `init-verification` | 开始工作时；环境变更后；当某些功能停止运行时 | | `self-correction-loop` | 在工具/hook 返回警告、lint/类型/构建错误后 | | `anti-hallucination-gates` | 在声称“完成”、“已修复”、“通过”之前 | | `test-coverage-design` | 决定测试内容；在“完成”之前功能是否被覆盖（分派给 `coverage-analyst`） | | `capturing-golden-rules` | 当相同的错误再次发生 / 某条审查意见本质上是一条约定时 — 将其编码为持久的规则（反馈飞轮） | | `context-budget-discipline` | 长会话；subagents；获取大文件时 | | `docs-lookup` | 查找不熟悉的工具/API/错误（Context7 → WebSearch → 不确定性） | | `cpp-build-systems` | CMake/Meson/Make/Bazel 项目 | | `cpp-static-analysis` | clang-tidy / cppcheck / IWYU | | `cpp-formatting` | clang-format | | `cpp-sanitizers` | ASan / UBSan / TSan / valgrind | ## Subagents（5 个 — 通过 `Task` 工具或 slash 命令调用） | Agent | 角色 | |---|---| | `verification-runner` | 全新上下文评估器 — 运行构建/测试/lint，报告证据路径。只读。 | | `coverage-analyst` | 全新上下文覆盖率差距分析师 — 从代码和规范中推导测试义务，标记运行范围之外的路径，推荐优先进行 oracle-independent 测试。只读。 | | `drift-analyst` | 全新上下文漂移 / 熵扫描器 — 根据 `golden-rules.md` 和 slop 启发式方法（死代码、代码重复、文档漂移）检查更改的代码，并附带证据路径报告发现。只读。 | | `cpp-build-doctor` | 根据编译器输出诊断 C/C++ 构建失败。只读。 | | `index-curator` | `PROJECT-TOC.md` 的唯一写入者。由 `/index-project` 使用。 | ## Slash 命令 | 命令 | 作用 | |---|---| | `/anchor` | 将 harness 状态文件脚手架搭建到当前项目中（仅在明确批准后覆盖） | | `/cpp-init` | C/C++ 项目：调优 `init.sh`，放入 `.clang-format` / `.clang-tidy` / `sanitizer-build.sh` | | `/index-project` | 从 git 跟踪的源码（重新）构建 `PROJECT-TOC.md` | | `/verify` | 分派 `verification-runner` 进行全新上下文评估；通过 `--fix` 开启受控（≤ 2 个循环）的自动修复流程 | | `/test-plan` | 分派 `coverage-analyst` 进行实现后的覆盖率差距分析（义务、运行范围之外的路径、优先进行的最小 oracle-independent 测试）；只读 | | `/gc` | 分派 `drift-analyst` 根据 `golden-rules.md` 和 slop 启发式方法（死代码、代码重复、文档漂移）进行按需的代码漂移 / 熵扫描；只读，仅报告（并非 `git gc`） | | `/sanitize` | C/C++ 项目：在 ASan+UBSan 下构建（TSan 单独运行），运行测试，在固定的部分中报告发现，并附带 `.harness-anchor/sanitize-*.log` 证据路径 | | `/session-end` | 编写结构化的交接信息 + 追加 `progress.md` + 提供提交选项 | | `/status` | 只读项目概览：激活的功能、计数、git 树、TOC 新鲜度、交接头指针 | 📖 **完整的命令参考：**[docs/commands.md](docs/commands.md) — 何时使用每个命令、它的参数、先决条件、输出，以及 harness 对它的推荐。 ## Hooks（4 个 — 全部仅警告，永不阻塞） | Hook | 目的 | |---|---| | SessionStart | 注入状态横幅：激活的功能、项目类型、TOC 新鲜度、golden-rules 计数、交接头指针、元技能主体（≤ 2000 token 预算） | | PostToolUse | 在 Edit/Write 之后：对已通过功能的文件进行回归警告；当写入 `feature_list.json` 时警告重复的功能 `id`；当功能进行中编写了新模块时，发出 **new-code-module 范围蔓延警告**（作为提示侧 scope-jump 检查的操作侧补充）；当存在 `compile_commands.json` 时对 C/C++ 文件执行 clang-tidy；对 C/C++ 的编辑提示单行 `/sanitize`（从不在内联运行 sanitizers） | | Stop | 提醒更新 progress.md，刷新 session-handoff；从不阻塞 | | UserPromptSubmit | 检测 scope-jump 词汇（"顺便"、"also"、"by the way"）；呈现激活的功能以供确认 | ## 关键设计决策 - **仅警告的 Hooks。** PostToolUse / Stop / UserPromptSubmit hooks **永不阻塞** — 它们根据 Anthropic 的“反馈循环 > 门控”指导原则，注入 `additionalContext` 以进行自我纠正。 - **默认失败契约。** 完成标准初始状态为 `false`；agent 必须产生具体的证据路径（构建日志、测试输出、lint 报告）才能将其翻转为 `true`。参见 `skills/anti-hallucination-gates/`。 - **渐进式披露。** SessionStart 注入 ≤ 2000 tokens（横幅 + 自适应的 `PROJECT-TOC` 视图 — 目录映射，或小型仓库的完整文件列表 — + 元技能）。更深入的引用存在于 skill 子文件夹中，按需加载。 - **docs-lookup 是规范的。** 其他技能中不存在内联的 Context7 → WebSearch 瀑布流 — 它们全都引用 `docs-lookup` 来获取流程（包括失败模式检测和校准不确定性的兜底方案）。 - **全新上下文评估器。** `/verify` 在具有只读工具的 subagent 中分派 `verification-runner`；根据 Anthropic 2026 年 3 月的三 agent 架构，缓解“自我打分”的宽松性。 - **测试覆盖率在实现之后。** `/test-plan` + `coverage-analyst` 从代码 + 规范中推导出*必须*被测试的内容，并标记运行器范围之外的路径 — 这是具备代码感知能力的检查，能够处理 superpowers（刻意屏蔽代码的）TDD 无法做到的事情；实现前测试优先仍然是 TDD 的工作。应对相关的 LLM 盲点（代码和测试都是由 LLM 生成的）的可靠性依赖于 oracle-independent 测试（metamorphic / differential / property）+ 风险构建检查清单，而不是模型的判断。 - **熵治理是一个反馈飞轮 — 仅报告。** 反复出现的错误将成为 `golden-rules.md` 中可检查的规则（`capturing-golden-rules` 技能）；`/gc` 分派一个全新上下文的 `drift-analyst`，根据这些规则 + 通用的 slop 启发式方法（死代码、代码重复、文档漂移）扫描*已更改*的代码，并给出**建议** — 它从不自动重构。这种捕获习惯锚定在现有的 `/session-end` 检查点上，而不是一种新的仪式（Garg 的 Feedback Flywheel；根据 harness 工程实践指南，这是一种适合独立开发者的轻量级形式）。 - **繁重的操作是显式命令，而不是自动触发的 hooks。** Sanitizer 构建（`/sanitize`）和选择开启的自动修复循环（`/verify --fix`，限制为 ≤ 2 个全新评估的循环）远远超过了 ≤ 5s 的仅警告 hook 预算 — hook 可以*建议* `/sanitize`，但从不在内联中运行它。 - **C/C++ 一等公民支持。** 构建系统自动检测（CMake/Meson/Make/Bazel），感知 `compile_commands.json` 的 clang-tidy，sanitizer 构建模板。 ## 配套插件 | 插件 | 角色 | 是否必需？ | |---|---|---| | [`superpowers`](https://github.com/obra/superpowers) | 流程方法论 | 推荐 | | `context7` / 第一方文档 MCP（例如 Microsoft Learn） | 库和生态系统文档查找 | 可选（`docs-lookup` 在相关时优先使用第一方文档，否则使用 WebSearch） | `harness-anchor` 在 runtime 是**零依赖**的（bash + git；用于 `scripts/*.mjs` 索引/状态工具的 Node.js；python3 被 hooks 在内联中使用，并具有平滑的降级兜底）。 ## 验证安装 ``` bash scripts/validate-anchor.sh # self-consistency checks (count printed on run) bash scripts/validate-manifests.sh # manifest validation (name, version, sync) bash tests/hook-contracts/post-tool-use-warn.sh # PostToolUse hook contract bash scripts/cpp-detect.sh --target tests/cpp-detection/cmake-fixture # cpp-detect on a known fixture bash scripts/measure-context.sh # SessionStart context budget vs 8000-char cap ``` CI 会在 push/PR 时（ubuntu + macos）运行所有这些操作 — 参见 `.github/workflows/validate.yml`。 遇到问题？请参阅 [docs/troubleshooting.md](docs/troubleshooting.md)。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 ## 更新日志 发布历史请参阅 [CHANGELOG.md](CHANGELOG.md)。

标签：AI工具链, AI智能体, Bash脚本, C/C++开发, LLM测试框架, MITM代理, 工程化脚手架, 应用安全, 网络安全研究, 预握手