feat(hosts): add Grok CLI host adapter - #52
Conversation
Register Grok as a first-class adapter for configured assets, session evidence, evidence bundles, and portable HTML report routing. Skills installed via symlink under ~/.grok/skills are now inventoried.
There was a problem hiding this comment.
Pull request overview
本 PR 在 Better Harness 中新增 Grok CLI 作为一等公民的宿主适配器：补齐会话证据读取（session-analysis）、已配置资产盘点（agent-customize / coding-agent-practices）、证据束（evidence-bundle）与 HTML 报告输出路由（.grok/better-harness），并同步更新文档矩阵与站点入口以将 Grok 标注为 Adapter support（非 Verified Quickstart）。实现与验收标准对齐到 docs/specs/2026-08-02-grok-host-adapter.md（Grok-A1/A2、Grok-S1–S4、Grok-R1/R2）。
Changes:
- 新增 Grok 会话平台：实现对
~/.grok/sessions/<url-encoded-cwd>/<session-id>/的发现、范围限定、事件归一化与可选signals.json用量读取 - 新增 Grok 资产盘点：读取
config.tomlMCP servers、skills、hooks、installed plugins 与 workspace.grok/.agents资产 - 更新 CLI/路由/文档与测试：将
grok纳入平台枚举、帮助文案、适配矩阵、主页卡片与相关单测
Reviewed changes
Copilot reviewed 38 out of 39 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| test/support-declarations.test.mjs | 扩展支持平台列表并更新 portable HTML 路由一致性断言以包含 Grok |
| test/session-analysis-providers.test.mjs | 为 Grok provider 添加 dispatcher 覆盖与会话事件/隔离/缺失 signals 的单测 |
| test/docs-site.test.mjs | 更新站点统计与矩阵边界断言（adapter 数从 2→3） |
| test/docs-entrypoints.test.mjs | 将 Grok 加入 adapter-support hosts、主页卡片计数与中英矩阵断言 |
| test/coding-agent-platform-notes.test.mjs | 将 Grok 纳入 Sessions Diagnostics 的平台说明与支持列表 |
| test/better-harness-evidence-bundle.test.mjs | evidence-bundle help 覆盖 Grok，并检查 --grok-home |
| test/agent-customize.test.mjs | 新增 Grok 资产盘点与 --grok-home 覆盖的端到端测试夹具 |
| templates/reporting/routing.md | 将 Grok 加入 portable HTML report 的宿主路由条件 |
| scripts/session-analysis/usage-summary.mjs | --platform help 列表加入 grok |
| scripts/session-analysis/selection-profile.mjs | --platform help 列表加入 grok |
| scripts/session-analysis/platforms/grok.mjs | 新增 Grok 会话证据适配器实现（sources/sessions/events/facts） |
| scripts/session-analysis/lifecycle-demand-signals.mjs | safeHost 白名单加入 grok |
| scripts/session-analysis/fs.mjs | walkFiles 改为可跟随目录 symlink（用于 Grok skills 软链场景） |
| scripts/session-analysis/analyzer.mjs | 注册 Grok 平台模块并更新帮助与 --grok-home |
| scripts/harness-analysis/task-loop-source.mjs | task-loop-source 平台枚举与 inventory 路由加入 grokHome/grok |
| scripts/harness-analysis/report-run.mjs | report 平台枚举与允许参数集合加入 grok/grok-home |
| scripts/harness-analysis/render-report.mjs | 为 grok 的 html 输出默认目录引入 .grok/better-harness 分支 |
| scripts/harness-analysis/evidence-bundle/contract.mjs | evidence-bundle providers 集合加入 grok |
| scripts/harness-analysis/evidence-bundle/cli.mjs | evidence-bundle CLI 帮助/参数白名单加入 --grok-home |
| scripts/harness-analysis/evidence-bundle/agent-customize.mjs | asset providers 集合加入 grok |
| scripts/coding-agent-practices/inventory.mjs | 平台提示与 userBase 推断加入 grokHome |
| scripts/coding-agent-practices/asset-integrity.mjs | provider 白名单与错误文案加入 grok |
| scripts/coding-agent-practices/asset-baseline.mjs | provider 白名单与错误文案加入 grok |
| scripts/agent-lint/cli.mjs | agent-assets-review provider 列表加入 grok |
| scripts/agent-customize/providers/index.mjs | 注册 Grok provider collector |
| scripts/agent-customize/providers/grok.mjs | 新增 Grok 配置资产盘点（skills/hooks/mcp/plugins/workspace primitives） |
| scripts/agent-customize/cli.mjs | CLI usage/参数透传加入 --grok-home |
| references/session-evidence/sessions-diagnostics.md | 文档增加 Grok 平台诊断与证据位置说明 |
| README.zh-CN.md | 文案更新：总适配器数与 adapter-support 列表加入 Grok |
| README.md | 文案更新：总适配器数与 adapter-support 列表加入 Grok |
| docs/src/pages/index.js | 主页新增 Grok host card，并更新架构说明/QuickStart 文案 |
| docs/specs/2026-08-02-grok-host-adapter.md | 新增 Grok 适配器 spec（验收、隐私边界、冒烟步骤） |
| docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/installation.mdx | 中文安装页：适配器总数更新为 9 |
| docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/adapter-matrix.md | 中文矩阵：加入 Grok 条目与边界说明 |
| docs/i18n/zh-Hans/code.json | 中文主页翻译新增 Grok host card 文案并更新计数文案 |
| docs/docs/installation.mdx | 英文安装页：适配器总数更新为 9 |
| docs/docs/hosts/adapter-matrix.md | 英文矩阵：加入 Grok 条目与边界说明 |
| docs/adapters/README.md | Canonical 矩阵：加入 Grok 行与相关说明段落 |
| assets/better-harness-architecture-en.svg | 架构图文字更新：capability adapters 数量与 adapter-support 列表加入 Grok |
Suppressed comments (1)
docs/src/pages/index.js:537
- This QuickStart intro still says "Eight host adapters" even though the rest of the PR bumps the declared total to nine. Update the English copy to match the docs and tests.
Eight host adapters are supported. Six have verified setup paths;
Pi, WorkBuddy, and Grok link to their current support boundaries.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // Dirent isDirectory/isFile are false for symlinks; follow them so hosts | ||
| // that install skills via ln -s (e.g. Grok ~/.grok/skills) are inventoried. | ||
| const linkedDirectory = entry.isSymbolicLink() ? await isDirectory(fullPath) : false; | ||
| if (entry.isDirectory() || linkedDirectory) { | ||
| await visit(fullPath, depth + 1); |
| Eight capability-level host adapters feed the same evidence | ||
| pipeline. Six have verified Quickstart paths; Pi and WorkBuddy keep | ||
| pipeline. Six have verified Quickstart paths; Pi, WorkBuddy, and Grok keep | ||
| their current adapter-support boundaries explicit. |
| options.out ??= options.mode === "cursor-canvas" | ||
| ? ".cursor/better-harness" | ||
| : options.mode === "html" && String(options.platform ?? options.provider ?? "").toLowerCase() === "grok" | ||
| ? ".grok/better-harness" | ||
| : ".qoder/better-harness"; |
Update frozen help fixtures, CLI registry summary, portable-HTML routing assertions, and Windows-portable Grok session path encoding checks.
OnMyAgent keeps SoT under .agents/skills and links .grok/skills to it. Inventory previously listed both paths, inflating owner routes past the 16-entry baseline and marking agentCustomize partial for normal depth.
Local validation updateI completed local validation against PR head The isolated skill-symlink path works: both native However, local validation found several issues that I believe should be addressed before merge:
Because the synthetic fixtures currently encode several assumptions that differ from Grok 0.2.118's native behavior, green tests alone do not validate the claimed “Verified assets + sessions + HTML render path” boundary. Please align the adapter and fixtures with the native CLI output, then repeat the real-host comparison. |
Summary
scripts/agent-customize/providers/grok.mjs) and session evidence (scripts/session-analysis/platforms/grok.mjs)..grok/better-harness).walkFilesfollow directory symlinks so Grok skills installed withln -sunder~/.grok/skillsare inventoried.Spec / acceptance
See
docs/specs/2026-08-02-grok-host-adapter.md(Grok-A1/A2, Grok-S1–S4, Grok-R1/R2).Install path for local use:
Test plan
node --test test/session-analysis-providers.test.mjs test/agent-customize.test.mjs test/support-declarations.test.mjs test/coding-agent-platform-notes.test.mjs test/docs-entrypoints.test.mjs test/better-harness-evidence-bundle.test.mjs test/docs-site.test.mjs(126 pass)session-analysis sources --platform grokdiscovers workspace sessionsagent-customize inventory --provider grokfinds symlink-installedbetter-harnessskillharness evidence-bundle --platform grok --depth quickreturnsstatus=completewith available lanes/better-harnessreport-loop smoke before Quickstart promotion