Skip to content

Commit 6d68cb5

Browse files
phodalcodex
phodal
and
codex
committed
feat(inspector): publish interactive docs demo
Add a first-class Inspector tab with a green New badge, a deterministic English Workbench sample, evidence-bounded product guidance, and bilingual wrapper documentation. Implements docs/specs/2026-08-13-public-inspector-demo.md. Validated with 21 focused Inspector tests, the 1,309-test full suite, package verification, bilingual Docusaurus builds, and browser checks of Session View, Replay, console errors, and page overflow. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
1 parent afed21d commit 6d68cb5

15 files changed

Lines changed: 1614 additions & 8 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ on:
66
paths:
77
- "docs/**"
88
- "assets/**"
9+
- "scripts/commit-session-link/**"
10+
- "scripts/harness-inspector/**"
11+
- "scripts/session-analysis/**"
912
- ".github/workflows/pages.yml"
1013
workflow_dispatch:
1114

‎docs/docusaurus.config.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,13 @@ const config = {
109109
position: "left",
110110
label: "Docs",
111111
},
112+
{
113+
to: "/inspector/",
114+
label: "Inspector",
115+
position: "left",
116+
className: "navbar__link--inspector-new",
117+
"aria-label": "Inspector",
118+
},
112119
{
113120
to: "/blog",
114121
label: "Blog",

‎docs/i18n/zh-Hans/code.json‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,124 @@
11
{
2+
"inspector.meta.description": {
3+
"message": "探索 Better Harness 如何以明确的证据边界连接产品意图、Coding Agent 活动、会话、文件与提交。"
4+
},
5+
"inspector.hero.lead": {
6+
"message": "从产品意图追踪到 Agent 活动、会话、文件与提交，同时让证据强度及其限制始终可见。"
7+
},
8+
"inspector.boundaries.label": {
9+
"message": "Demo 边界"
10+
},
11+
"inspector.boundaries.interactive": {
12+
"message": "可交互样例"
13+
},
14+
"inspector.boundaries.readOnly": {
15+
"message": "只读"
16+
},
17+
"inspector.actions.fullscreen": {
18+
"message": "全屏打开"
19+
},
20+
"inspector.demo.title": {
21+
"message": "可交互 Harness Inspector 样例"
22+
},
23+
"inspector.demo.frameTitle": {
24+
"message": "可交互 Harness Inspector 样例"
25+
},
26+
"inspector.demo.loading": {
27+
"message": "正在加载可交互样例…"
28+
},
29+
"inspector.demo.note": {
30+
"message": "此确定性样例使用虚构的英文数据，不会读取你的工作区、Git 历史或 Coding Agent 会话。"
31+
},
32+
"inspector.features.eyebrow": {
33+
"message": "它展示什么"
34+
},
35+
"inspector.features.title": {
36+
"message": "沿着交付链路追踪，同时不越过证据边界"
37+
},
38+
"inspector.features.intro": {
39+
"message": "Inspector 把产品结构、Agent 活动与 Git 结果放进同一个只读工作区，并明确区分强关联与有用但有限的上下文。"
40+
},
41+
"inspector.features.intent.title": {
42+
"message": "从意图到交付"
43+
},
44+
"inspector.features.intent.body": {
45+
"message": "沿 Delivery Tree 从能力和 Story 意图，查看与之关联的会话、文件与提交。"
46+
},
47+
"inspector.features.session.title": {
48+
"message": "把会话放回上下文"
49+
},
50+
"inspector.features.session.body": {
51+
"message": "检查保留的提示词、归一化工具活动、文件路径、提交事件，以及只读会话回放。"
52+
},
53+
"inspector.features.evidence.title": {
54+
"message": "可解释的证据"
55+
},
56+
"inspector.features.evidence.body": {
57+
"message": "同步选择与 Evidence Drawer 会说明关联为何存在、可信度如何，以及它不能证明什么。"
58+
},
59+
"inspector.how.eyebrow": {
60+
"message": "如何使用"
61+
},
62+
"inspector.how.title": {
63+
"message": "先看全局，再沿着证据深入"
64+
},
65+
"inspector.how.scope.title": {
66+
"message": "选择范围"
67+
},
68+
"inspector.how.scope.body": {
69+
"message": "按产品意图查看时使用 Delivery Tree；按时间查看会话与提交时使用 Date。"
70+
},
71+
"inspector.how.lanes.title": {
72+
"message": "阅读三条信息轨"
73+
},
74+
"inspector.how.lanes.body": {
75+
"message": "在不离开当前 Story 或日期的情况下，对照用户提示、检查点活动以及提交或文件。"
76+
},
77+
"inspector.how.evidence.title": {
78+
"message": "检查关联关系"
79+
},
80+
"inspector.how.evidence.body": {
81+
"message": "选择提示、操作、提交或路径。相关项目会保持高亮，Evidence Drawer 则解释关联及其限制。"
82+
},
83+
"inspector.how.session.title": {
84+
"message": "打开 Session View 或 Replay"
85+
},
86+
"inspector.how.session.body": {
87+
"message": "深入查看保留的轮次和归一化工具调用，或回放已观察到的序列。Replay 不会重新运行工具，也不会恢复 Coding Agent 会话。"
88+
},
89+
"inspector.evidence.eyebrow": {
90+
"message": "理解证据标签"
91+
},
92+
"inspector.evidence.title": {
93+
"message": "关联会明确展示，但不会擅自推断作者身份"
94+
},
95+
"inspector.evidence.explicit": {
96+
"message": "保留的引用直接连接 Story、会话或提交。"
97+
},
98+
"inspector.evidence.observed": {
99+
"message": "会话与提交共享完全相同的仓库路径。这支持相关性判断，但不能证明作者身份。"
100+
},
101+
"inspector.evidence.candidate": {
102+
"message": "结构或时间信息提示了有用的关联，但仍需人工确认。"
103+
},
104+
"inspector.evidence.contextual": {
105+
"message": "附近的历史有助于解释交付过程，但不会声称存在直接关联。"
106+
},
107+
"inspector.local.eyebrow": {
108+
"message": "使用你自己的证据"
109+
},
110+
"inspector.local.title": {
111+
"message": "生成私有的自包含 Inspector"
112+
},
113+
"inspector.local.body": {
114+
"message": "安装 Better Harness 后，在仓库中运行高级 Inspector 命令。采集留在本地，生成的报告保持只读。"
115+
},
116+
"inspector.local.installation": {
117+
"message": "查看安装方式"
118+
},
119+
"inspector.local.output": {
120+
"message": "默认输出：.qoder/better-harness-runs/harness-inspector/inspector.html"
121+
},
2122
"homepage.dimensions.taskUnderstanding.title": {
3123
"message": "任务理解"
4124
},

‎docs/i18n/zh-Hans/docusaurus-theme-classic/navbar.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@
77
"message": "文档",
88
"description": "Navbar item with label Docs"
99
},
10+
"item.label.Inspector": {
11+
"message": "Inspector",
12+
"description": "Navbar item with label Inspector"
13+
},
1014
"item.label.Blog": {
1115
"message": "博客",
1216
"description": "Navbar item with label Blog"

‎docs/scripts/sync-assets.mjs‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
// Sync published assets from the repository root into docs/static/.
22
// assets/ stays the single source of truth; synced targets are gitignored.
3-
import { cpSync, mkdirSync, rmSync } from "node:fs";
3+
import { cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
44
import { dirname, join, resolve } from "node:path";
55
import { fileURLToPath } from "node:url";
66

7+
import { renderHarnessInspectorDemoHtml } from "../../scripts/harness-inspector/demo-report.mjs";
8+
79
export function syncAssets({ repoRoot, siteRoot }) {
810
const generatedDemoRoot = join(siteRoot, "static", "demo");
911

@@ -42,7 +44,11 @@ export function syncAssets({ repoRoot, siteRoot }) {
4244
mkdirSync(dirname(to), { recursive: true });
4345
cpSync(from, to, { recursive: true });
4446
}
45-
return copies.length;
47+
const inspectorDemo = join(generatedDemoRoot, "harness-inspector", "index.html");
48+
mkdirSync(dirname(inspectorDemo), { recursive: true });
49+
writeFileSync(inspectorDemo, renderHarnessInspectorDemoHtml(), "utf8");
50+
51+
return copies.length + 1;
4652
}
4753

4854
const currentFile = fileURLToPath(import.meta.url);

‎docs/specs/2026-08-13-public-inspector-demo.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Public Harness Inspector demo
2+
3+
## Traceability
4+
5+
- Spec ID: `public-inspector-demo`
6+
- Status: Implemented
7+
8+
## Intent
9+
10+
Add a first-class Harness Inspector entry to the Better Harness GitHub Pages
11+
site. Readers should understand the Inspector's evidence-bounded purpose and
12+
explore the current Workbench interactions without installing the project or
13+
exposing any maintainer's local sessions, prompts, paths, or repository state.
14+
15+
## Acceptance Scenarios
16+
17+
- AC-1: The website navbar contains an internal `Inspector` link immediately
18+
after Docs. A compact green `New` badge sits at the link's upper-right on
19+
desktop and beside the link on the mobile menu; `New` is not part of the
20+
product name, route, page title, or accessible link name.
21+
- AC-2: `/inspector/` is a full-width Docusaurus page with a concise product
22+
introduction, explicit `Interactive sample`, `Read-only`, and `English sample
23+
data` boundaries, an `Open full screen` action, and an embedded current
24+
Harness Inspector Workbench.
25+
- AC-3: The embedded Workbench is generated from a deterministic in-memory
26+
fixture. Every user-facing fixture value is English, no local session or Git
27+
discovery runs during the docs build, and the sample contains enough Stories,
28+
Sessions, Tool Calls, Files, Commits, dates, and evidence kinds to exercise
29+
Delivery Tree, Date, Evidence Drawer, Session View, and Replay interactions.
30+
- AC-4: The embedded page identifies itself as sample data rather than `real
31+
local evidence`, carries `noindex, follow`, and preserves the standalone
32+
Workbench's escaping and privacy guarantees. The indexable Docusaurus wrapper
33+
owns the public description.
34+
- AC-5: English and Simplified Chinese website builds expose the same English
35+
Workbench sample. Only the wrapper introduction and actions are localized.
36+
Desktop and narrow viewports retain usable navigation, iframe focus, a
37+
full-screen fallback, and no page-level horizontal overflow.
38+
- AC-6: Changes to the Inspector renderer, UI, fixture, docs page, or publishing
39+
workflow trigger or participate in the GitHub Pages build so the published
40+
demo cannot silently drift behind the current Workbench.
41+
- AC-7: The page continues below the interactive sample with concise,
42+
indexable documentation that explains the Inspector's core jobs, the
43+
difference between direct, observed, candidate, and contextual evidence, and
44+
the limits of what those relationships prove.
45+
- AC-8: A numbered usage guide walks readers through choosing a scope,
46+
inspecting the three Workbench lanes, opening evidence details, and using
47+
Session View or Replay. A separate local-project callout provides the exact
48+
advanced CLI command, default output location, and a link to installation
49+
documentation without implying that the hosted sample reads local data.
50+
51+
## Non-goals
52+
53+
- Publishing a maintainer's `.qoder/` report, native session identifiers, real
54+
prompts, commit authors, or current repository activity.
55+
- Reading a visitor's local workspace or offering a server-backed live report.
56+
- Rewriting the self-contained Workbench as Docusaurus React components.
57+
- Synchronizing the wrapper URL with every iframe selection in this slice; the
58+
standalone Workbench remains the owner of evidence deep links.
59+
- Adding Compare, editing mappings, recovery, or workspace mutation controls.
60+
61+
## Plan and Tasks
62+
63+
1. Add a pure Inspector demo builder under `scripts/harness-inspector/` with a
64+
fixed English fixture and generated timestamp.
65+
2. Add a bounded rendering presentation option for the sample context label,
66+
robots metadata, and optional public-demo marker without changing local
67+
report defaults.
68+
3. Generate `docs/static/demo/harness-inspector/index.html` during the existing
69+
docs asset-sync step instead of committing a second Workbench copy.
70+
4. Add a custom full-width `/inspector/` page, localized wrapper copy, full-screen
71+
action, iframe title, clipboard permission, and responsive frame layout.
72+
5. Add the `Inspector` navbar item and CSS-only green `New` badge while keeping
73+
the DOM link text and accessible name equal to `Inspector`.
74+
6. Extend Pages path triggers to include the Inspector owners and add focused
75+
behavior tests for fixture language, privacy, presentation metadata, and
76+
generated output.
77+
7. Add localized feature, usage, evidence-label, and local-project sections
78+
below the sample, with responsive cards and semantic headings/lists.
79+
80+
Decision rationale: the Inspector already emits a portable self-contained HTML
81+
Workbench. Embedding that artifact keeps one UI owner and makes the public sample
82+
track current interactions. A deterministic fixture prevents CI from depending
83+
on developer homes or native host state, while the Docusaurus wrapper provides
84+
the indexable explanation and locale-specific framing.
85+
86+
## Test and Review Evidence
87+
88+
- AC-3/AC-4: focused Vitest coverage builds the demo twice, compares the stable
89+
report projection, validates English fixture strings, asserts sample/noindex
90+
metadata, and rejects absolute-home or credential-shaped output.
91+
- AC-1/AC-2/AC-5: `cd docs && npm run build`, followed by Playwright checks of
92+
English and `zh-Hans` `/inspector/` routes, navbar/badge placement, iframe
93+
interaction, full-screen target, console/page errors, and desktop/narrow
94+
screenshots.
95+
- AC-6: inspect the Pages workflow path filter and run the docs prebuild from a
96+
clean generated-static target.
97+
- AC-7/AC-8: inspect the English and Simplified Chinese page structure in the
98+
production build, verify the installation link and literal CLI command, and
99+
review the lower-page layout at desktop and narrow breakpoints.
100+
- Documentation integrity: `node scripts/doc-link-graph/cli.mjs
101+
skills/better-harness` and `npx vitest run
102+
test/skills-docs/doc-link-graph.test.mjs` after adding this spec.
103+
- Regression and package boundary: focused Inspector tests, `npm test`,
104+
`npm run pack:verify`, and `git diff --check`.
105+
- Privacy risk: fixture generation must remain pure and fixed; the docs build
106+
must never call session discovery or Git history collection.
107+
- UI risk: nested browser scrolling can obscure the Workbench. Keep the wrapper
108+
as a viewport-height flex surface and provide a visible full-screen escape.
109+
110+
Observed on 2026-08-13:
111+
112+
- Focused Inspector coverage: 21 tests passed.
113+
- Documentation link graph: 6 tests passed after regeneration.
114+
- Full regression suite: 92 files and 1,309 tests passed.
115+
- Package verification: npm package and runtime zip contents passed.
116+
- Production documentation build: English and Simplified Chinese builds passed.
117+
- Browser verification: the English and Simplified Chinese wrappers loaded with
118+
no console errors or page-level horizontal overflow; the embedded sample used
119+
English-only fixture data and realistic short commit hashes. The standalone
120+
sample opened Session View and switched to Replay successfully.
121+
- Documentation extension: the English and Simplified Chinese production pages
122+
exposed all feature, usage, evidence-label, and local-project sections; the
123+
advanced CLI command and installation link were present, with no console
124+
errors or page-level horizontal overflow.

‎docs/src/css/custom.css‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,59 @@ html[data-theme="dark"] {
6969

7070
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
7171
}
72+
73+
/* `New` is presentation metadata, not part of the Inspector product name or
74+
accessible link label. The compact corner tag becomes inline on mobile. */
75+
.navbar__link--inspector-new {
76+
position: relative;
77+
margin-right: 10px;
78+
padding-right: 12px;
79+
}
80+
81+
.navbar__link--inspector-new::after {
82+
content: "New";
83+
position: absolute;
84+
top: 2px;
85+
right: 0;
86+
padding: 2px 5px;
87+
border-radius: 999px;
88+
color: #fff;
89+
background: #218739;
90+
box-shadow: 0 0 0 2px var(--ifm-navbar-background-color);
91+
font-size: 8px;
92+
font-weight: 800;
93+
line-height: 1.25;
94+
letter-spacing: 0.02em;
95+
transform: translate(20%, -20%);
96+
pointer-events: none;
97+
}
98+
99+
@media (max-width: 996px) {
100+
.navbar__link--inspector-new {
101+
display: flex;
102+
margin-right: 0;
103+
padding-right: var(--ifm-navbar-item-padding-horizontal);
104+
align-items: center;
105+
gap: 8px;
106+
}
107+
108+
.navbar__link--inspector-new::after {
109+
position: static;
110+
box-shadow: none;
111+
font-size: 9px;
112+
transform: none;
113+
}
114+
}
115+
116+
@media (min-width: 997px) and (max-width: 1250px) {
117+
.navbar__item {
118+
padding-right: 0.55rem;
119+
padding-left: 0.55rem;
120+
font-size: 0.88rem;
121+
white-space: nowrap;
122+
}
123+
124+
.navbar__search-input {
125+
width: 9.5rem;
126+
}
127+
}

0 commit comments

Comments
 (0)