Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
fix: clarify session progress and project solution setup
sanbuphy391ed7c6b649
diff --git a/README.md b/README.mdindex cc6455c..bcbe2de 100644--- a/README.md+++ b/README.md@@ -252,12 +252,18 @@ The idea is simple: instead of just writing prompts, give your agent a set of st├── CLAUDE.md <-- (alternative, if using Claude Code)├── init.sh <-- runs install + verify + start├── feature_list.json <-- what features exist, which are done- ├── claude-progress.md <-- what happened each session+ ├── claude-progress.md <-- session progress (historical filename; agent-agnostic)└── src/ <-- your actual code```Grab the starter templates from the [Resource Library](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) and drop them into your project. That's it. Four files, and your agent sessions will already be significantly more stable than running on prompts alone.+`claude-progress.md` is a generic, repository-local session progress log; the+name is retained for compatibility with the course examples. It is not tied to+Claude Code and is not updated automatically by any agent. Codex, OpenHands,+Antigravity, and other coding agents can use the same file when their root+instructions tell them to read it at startup and update it before handoff.+---## Capstone Project: A Real Appdiff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex ca4548c..890bdb3 100644--- a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -42,7 +42,7 @@ With the scenarios above in mind, these concepts are no longer just jargon:There is really only one core principle: **When things fail, don't swap the model first — check the harness.** If the same model succeeds on similar, well-structured tasks, assume it's a harness problem.-What does this look like in practice? Attribute every failure to a specific layer. Don't just say "the model isn't good enough." Ask yourself: was the task unclear? Was context insufficient? Were there no verification methods? Map each failure to one of the five defense layers — task specification, context provision, execution environment, verification feedback, state management. Build this habit, and you'll find "the model isn't good enough" appearing less and less in your logs.+What does this look like in practice? Attribute every failure to a specific layer. Don't just say "the model isn't good enough." Ask yourself: was the task unclear? Was context insufficient? Were there no verification methods? Map each failure to one of the five defense layers — task specification, context provision, execution environment, verification feedback, or state management. These are failure-diagnosis layers, not additional core concepts. Build this habit, and you'll find "the model isn't good enough" appearing less and less in your logs.Then, write an explicit Definition of Done for every task. Don't say "add a search feature." Spell it out:```diff --git a/docs/en/resources/index.md b/docs/en/resources/index.mdindex c078e8b..7778862 100644--- a/docs/en/resources/index.md+++ b/docs/en/resources/index.md@@ -23,6 +23,10 @@ For a minimal setup, begin with:- root instructions: [`templates/AGENTS.md`](./templates/AGENTS.md) or [`templates/CLAUDE.md`](./templates/CLAUDE.md)- feature state: [`templates/feature_list.json`](./templates/feature_list.json)- progress log: [`templates/claude-progress.md`](./templates/claude-progress.md)++The filename is a historical course convention. This is a generic,+repository-local session progress log: any coding agent can use it, but agents+only read or update it when their instructions explicitly tell them to do so.- bootstrap script reference: `docs/en/resources/templates/init.sh`Then add:@@ -47,7 +51,7 @@ If you want the fuller OpenAI-style repository structure from the- `AGENTS.md` or `CLAUDE.md`- `feature_list.json`-- `claude-progress.md`+- `claude-progress.md` (generic session progress log; historical filename)- `init.sh`Those four files are enough to make most agent workflows noticeably more stable.diff --git a/docs/en/resources/templates/claude-progress.md b/docs/en/resources/templates/claude-progress.mdindex c6a0a7b..0cc2562 100644--- a/docs/en/resources/templates/claude-progress.md+++ b/docs/en/resources/templates/claude-progress.md@@ -1,5 +1,18 @@# Progress Log+<!--+This filename is kept for compatibility with the course examples. The file is+agent-agnostic: Codex, Claude Code, OpenHands, and other coding agents can use+it. Read it at session startup and update it before handoff through the+repository's agent instructions; no agent updates it automatically.+-->++This is a generic repository-local session progress log. The+`claude-progress.md` filename is a historical course convention, not a+Claude Code requirement. Any coding agent can use it when the repository's+instructions tell it to read the file at startup and update it before handoff;+agents do not update it automatically.+## Current Verified State- Repository root:diff --git a/docs/zh/resources/index.md b/docs/zh/resources/index.mdindex 865de48..1bc6802 100644--- a/docs/zh/resources/index.md+++ b/docs/zh/resources/index.md@@ -21,6 +21,11 @@- 根指令文件:[`templates/AGENTS.md`](./templates/AGENTS.md) 或 [`templates/CLAUDE.md`](./templates/CLAUDE.md)- 功能状态文件:[`templates/feature_list.json`](./templates/feature_list.json)- 进度日志:[`templates/claude-progress.md`](./templates/claude-progress.md)++这个文件名是课程早期留下的约定,实际是通用的、放在仓库里的会话进度日志,+并不绑定 Claude Code。Codex、OpenHands、Antigravity 等 agent 都可以使用,+但必须在 `AGENTS.md` 或其他等价指令里明确要求它在开工时读取、收尾时更新;+agent 不会自动维护这个文件。- 启动脚本参考:`docs/resources/templates/init.sh`然后按需要补上:@@ -43,7 +48,7 @@- `AGENTS.md` 或 `CLAUDE.md`- `feature_list.json`-- `claude-progress.md`+- `claude-progress.md`(通用会话进度日志,文件名沿用历史约定)- `init.sh`先把这四样放进项目里,再开始让 agent 持续工作,通常就已经能明显降低返工和瞎猜。diff --git a/docs/zh/resources/templates/claude-progress.md b/docs/zh/resources/templates/claude-progress.mdindex 8ee42ee..ed9f288 100644--- a/docs/zh/resources/templates/claude-progress.md+++ b/docs/zh/resources/templates/claude-progress.md@@ -1,5 +1,15 @@# 进度日志+<!--+文件名沿用课程历史约定,仅为兼容已有示例。这个文件与具体 agent 无关,Codex、+Claude Code、OpenHands 等都可以使用。请在仓库指令中要求 agent 开工时读取、+交接前更新;任何 agent 都不会自动维护它。+-->++这是一个通用的仓库内会话进度日志。`claude-progress.md` 只是课程沿用的历史+文件名,并不要求使用 Claude Code。只要仓库里的指令明确要求,Codex 或其他+coding agent 都可以在开工时读取、交接前更新;agent 不会自动维护这个文件。+## 当前已验证状态- 仓库根目录:diff --git a/projects/project-01/solution/package.json b/projects/project-01/solution/package.jsonindex c57e574..d0e4a1e 100644--- a/projects/project-01/solution/package.json+++ b/projects/project-01/solution/package.json@@ -18,6 +18,7 @@"devDependencies": {"@types/react": "^18.3.12","@types/react-dom": "^18.3.1",+ "@types/node": "^22.20.1","@types/uuid": "^9.0.7","@vitejs/plugin-react": "^4.3.4","electron": "^33.2.0",diff --git a/projects/project-01/solution/src/renderer/App.tsx b/projects/project-01/solution/src/renderer/App.tsxindex cede784..e9d3417 100644--- a/projects/project-01/solution/src/renderer/App.tsx+++ b/projects/project-01/solution/src/renderer/App.tsx@@ -1,9 +1,9 @@-import React, { useState, useCallback } from 'react';+import { useState, useCallback } from 'react';import { DocumentList } from './components/DocumentList';import { QuestionPanel } from './components/QuestionPanel';import { DocumentDetail } from './components/DocumentDetail';import { StatusBar } from './components/StatusBar';-import { Document, AppStatus, QAResponse } from '../../shared/types';+import { Document, AppStatus, QAResponse } from '../shared/types';declare global {interface Window {diff --git a/projects/project-01/solution/src/renderer/components/DocumentDetail.tsx b/projects/project-01/solution/src/renderer/components/DocumentDetail.tsxindex b2787ef..cb90602 100644--- a/projects/project-01/solution/src/renderer/components/DocumentDetail.tsx+++ b/projects/project-01/solution/src/renderer/components/DocumentDetail.tsx@@ -1,5 +1,5 @@-import React, { useEffect, useState } from 'react';-import { Document, Chunk } from '../../../shared/types';+import { useEffect, useState } from 'react';+import { Document, Chunk } from '../../shared/types';interface Props {document: Document;diff --git a/projects/project-01/solution/src/renderer/components/DocumentList.tsx b/projects/project-01/solution/src/renderer/components/DocumentList.tsxindex f3166ed..be4a73b 100644--- a/projects/project-01/solution/src/renderer/components/DocumentList.tsx+++ b/projects/project-01/solution/src/renderer/components/DocumentList.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { Document } from '../../../shared/types';+import { Document } from '../../shared/types';interface Props {documents: Document[];diff --git a/projects/project-01/solution/src/renderer/components/ImportPanel.tsx b/projects/project-01/solution/src/renderer/components/ImportPanel.tsxindex 29ca5cd..47c33d6 100644--- a/projects/project-01/solution/src/renderer/components/ImportPanel.tsx+++ b/projects/project-01/solution/src/renderer/components/ImportPanel.tsx@@ -1,7 +1,6 @@-import React from 'react';interface Props {- onImport: (filePath: string) => void;+ onImport: (file: File) => void;}export function ImportPanel({ onImport }: Props) {@@ -25,7 +24,7 @@ export function ImportPanel({ onImport }: Props) {accept=".txt,.md"onChange={e => {const file = e.target.files?.[0];- if (file) onImport(file.path);+ if (file) onImport(file);}}style={{ marginTop: '10px' }}/>diff --git a/projects/project-01/solution/src/renderer/components/QuestionPanel.tsx b/projects/project-01/solution/src/renderer/components/QuestionPanel.tsxindex 1b80cc5..ac605d1 100644--- a/projects/project-01/solution/src/renderer/components/QuestionPanel.tsx+++ b/projects/project-01/solution/src/renderer/components/QuestionPanel.tsx@@ -1,4 +1,4 @@-import React, { useState } from 'react';+import { useState } from 'react';interface Props {onAsk: (question: string) => void;diff --git a/projects/project-01/solution/src/renderer/components/StatusBar.tsx b/projects/project-01/solution/src/renderer/components/StatusBar.tsxindex 1bf587c..29756e1 100644--- a/projects/project-01/solution/src/renderer/components/StatusBar.tsx+++ b/projects/project-01/solution/src/renderer/components/StatusBar.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { AppStatus } from '../../../shared/types';+import { AppStatus } from '../../shared/types';interface Props {status: AppStatus;diff --git a/projects/project-01/solution/src/renderer/main.tsx b/projects/project-01/solution/src/renderer/main.tsxindex 4548baf..ad7fac2 100644--- a/projects/project-01/solution/src/renderer/main.tsx+++ b/projects/project-01/solution/src/renderer/main.tsx@@ -1,4 +1,4 @@-import React from 'react';+import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';import { App } from './App';@@ -6,7 +6,7 @@ const container = document.getElementById('root');if (!container) throw new Error('Root element not found');createRoot(container).render(- <React.StrictMode>+ <StrictMode><App />- </React.StrictMode>+ </StrictMode>);diff --git a/projects/project-02/solution/package.json b/projects/project-02/solution/package.jsonindex c57e574..d0e4a1e 100644--- a/projects/project-02/solution/package.json+++ b/projects/project-02/solution/package.json@@ -18,6 +18,7 @@"devDependencies": {"@types/react": "^18.3.12","@types/react-dom": "^18.3.1",+ "@types/node": "^22.20.1","@types/uuid": "^9.0.7","@vitejs/plugin-react": "^4.3.4","electron": "^33.2.0",diff --git a/projects/project-02/solution/src/renderer/App.tsx b/projects/project-02/solution/src/renderer/App.tsxindex f44c234..4a1a1b7 100644--- a/projects/project-02/solution/src/renderer/App.tsx+++ b/projects/project-02/solution/src/renderer/App.tsx@@ -1,10 +1,10 @@-import React, { useState, useCallback, useEffect } from 'react';+import { useState, useCallback, useEffect } from 'react';import { DocumentList } from './components/DocumentList';import { QuestionPanel } from './components/QuestionPanel';import { DocumentDetail } from './components/DocumentDetail';import { ImportPanel } from './components/ImportPanel';import { StatusBar } from './components/StatusBar';-import { Document, AppStatus, QAResponse } from '../../shared/types';+import { Document, AppStatus, QAResponse } from '../shared/types';declare global {interface Window {diff --git a/projects/project-02/solution/src/renderer/components/DocumentDetail.tsx b/projects/project-02/solution/src/renderer/components/DocumentDetail.tsxindex 0cb8380..e6df271 100644--- a/projects/project-02/solution/src/renderer/components/DocumentDetail.tsx+++ b/projects/project-02/solution/src/renderer/components/DocumentDetail.tsx@@ -1,5 +1,5 @@-import React, { useEffect, useState } from 'react';-import { Document, Chunk } from '../../../shared/types';+import { useEffect, useState } from 'react';+import { Document, Chunk } from '../../shared/types';interface Props {document: Document;diff --git a/projects/project-02/solution/src/renderer/components/DocumentList.tsx b/projects/project-02/solution/src/renderer/components/DocumentList.tsxindex f3166ed..be4a73b 100644--- a/projects/project-02/solution/src/renderer/components/DocumentList.tsx+++ b/projects/project-02/solution/src/renderer/components/DocumentList.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { Document } from '../../../shared/types';+import { Document } from '../../shared/types';interface Props {documents: Document[];diff --git a/projects/project-02/solution/src/renderer/components/ImportPanel.tsx b/projects/project-02/solution/src/renderer/components/ImportPanel.tsxindex 29ca5cd..47c33d6 100644--- a/projects/project-02/solution/src/renderer/components/ImportPanel.tsx+++ b/projects/project-02/solution/src/renderer/components/ImportPanel.tsx@@ -1,7 +1,6 @@-import React from 'react';interface Props {- onImport: (filePath: string) => void;+ onImport: (file: File) => void;}export function ImportPanel({ onImport }: Props) {@@ -25,7 +24,7 @@ export function ImportPanel({ onImport }: Props) {accept=".txt,.md"onChange={e => {const file = e.target.files?.[0];- if (file) onImport(file.path);+ if (file) onImport(file);}}style={{ marginTop: '10px' }}/>diff --git a/projects/project-02/solution/src/renderer/components/QuestionPanel.tsx b/projects/project-02/solution/src/renderer/components/QuestionPanel.tsxindex 1b80cc5..ac605d1 100644--- a/projects/project-02/solution/src/renderer/components/QuestionPanel.tsx+++ b/projects/project-02/solution/src/renderer/components/QuestionPanel.tsx@@ -1,4 +1,4 @@-import React, { useState } from 'react';+import { useState } from 'react';interface Props {onAsk: (question: string) => void;diff --git a/projects/project-02/solution/src/renderer/components/StatusBar.tsx b/projects/project-02/solution/src/renderer/components/StatusBar.tsxindex 1bf587c..29756e1 100644--- a/projects/project-02/solution/src/renderer/components/StatusBar.tsx+++ b/projects/project-02/solution/src/renderer/components/StatusBar.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { AppStatus } from '../../../shared/types';+import { AppStatus } from '../../shared/types';interface Props {status: AppStatus;diff --git a/projects/project-02/solution/src/renderer/main.tsx b/projects/project-02/solution/src/renderer/main.tsxindex 4548baf..ad7fac2 100644--- a/projects/project-02/solution/src/renderer/main.tsx+++ b/projects/project-02/solution/src/renderer/main.tsx@@ -1,4 +1,4 @@-import React from 'react';+import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';import { App } from './App';@@ -6,7 +6,7 @@ const container = document.getElementById('root');if (!container) throw new Error('Root element not found');createRoot(container).render(- <React.StrictMode>+ <StrictMode><App />- </React.StrictMode>+ </StrictMode>);diff --git a/projects/project-03/solution/package.json b/projects/project-03/solution/package.jsonindex 87653b1..993d2d3 100644--- a/projects/project-03/solution/package.json+++ b/projects/project-03/solution/package.json@@ -18,6 +18,7 @@"devDependencies": {"@types/react": "^18.3.12","@types/react-dom": "^18.3.1",+ "@types/node": "^22.20.1","@types/uuid": "^9.0.7","@vitejs/plugin-react": "^4.3.4","electron": "^33.2.0",diff --git a/projects/project-03/solution/src/renderer/App.tsx b/projects/project-03/solution/src/renderer/App.tsxindex b580114..573ec08 100644--- a/projects/project-03/solution/src/renderer/App.tsx+++ b/projects/project-03/solution/src/renderer/App.tsx@@ -1,10 +1,10 @@-import React, { useState, useCallback, useEffect } from 'react';+import { useState, useCallback, useEffect } from 'react';import { DocumentList } from './components/DocumentList';import { QuestionPanel } from './components/QuestionPanel';import { DocumentDetail } from './components/DocumentDetail';import { ImportPanel } from './components/ImportPanel';import { StatusBar } from './components/StatusBar';-import { Document, AppStatus, QAResponse } from '../../shared/types';+import { Document, AppStatus, QAResponse } from '../shared/types';declare global {interface Window {diff --git a/projects/project-03/solution/src/renderer/components/DocumentDetail.tsx b/projects/project-03/solution/src/renderer/components/DocumentDetail.tsxindex faf996b..758bf5d 100644--- a/projects/project-03/solution/src/renderer/components/DocumentDetail.tsx+++ b/projects/project-03/solution/src/renderer/components/DocumentDetail.tsx@@ -1,5 +1,5 @@-import React, { useEffect, useState } from 'react';-import { Document, Chunk, DocumentMetadata } from '../../../shared/types';+import { useEffect, useState } from 'react';+import { Document, Chunk, DocumentMetadata } from '../../shared/types';interface Props {document: Document;diff --git a/projects/project-03/solution/src/renderer/components/DocumentList.tsx b/projects/project-03/solution/src/renderer/components/DocumentList.tsxindex 5f57d9f..712d102 100644--- a/projects/project-03/solution/src/renderer/components/DocumentList.tsx+++ b/projects/project-03/solution/src/renderer/components/DocumentList.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { Document } from '../../../shared/types';+import { Document } from '../../shared/types';interface Props {documents: Document[];diff --git a/projects/project-03/solution/src/renderer/components/ImportPanel.tsx b/projects/project-03/solution/src/renderer/components/ImportPanel.tsxindex 29ca5cd..47c33d6 100644--- a/projects/project-03/solution/src/renderer/components/ImportPanel.tsx+++ b/projects/project-03/solution/src/renderer/components/ImportPanel.tsx@@ -1,7 +1,6 @@-import React from 'react';interface Props {- onImport: (filePath: string) => void;+ onImport: (file: File) => void;}export function ImportPanel({ onImport }: Props) {@@ -25,7 +24,7 @@ export function ImportPanel({ onImport }: Props) {accept=".txt,.md"onChange={e => {const file = e.target.files?.[0];- if (file) onImport(file.path);+ if (file) onImport(file);}}style={{ marginTop: '10px' }}/>diff --git a/projects/project-03/solution/src/renderer/components/QuestionPanel.tsx b/projects/project-03/solution/src/renderer/components/QuestionPanel.tsxindex 1b80cc5..ac605d1 100644--- a/projects/project-03/solution/src/renderer/components/QuestionPanel.tsx+++ b/projects/project-03/solution/src/renderer/components/QuestionPanel.tsx@@ -1,4 +1,4 @@-import React, { useState } from 'react';+import { useState } from 'react';interface Props {onAsk: (question: string) => void;diff --git a/projects/project-03/solution/src/renderer/components/StatusBar.tsx b/projects/project-03/solution/src/renderer/components/StatusBar.tsxindex f549971..573d788 100644--- a/projects/project-03/solution/src/renderer/components/StatusBar.tsx+++ b/projects/project-03/solution/src/renderer/components/StatusBar.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { AppStatus } from '../../../shared/types';+import { AppStatus } from '../../shared/types';interface Props {status: AppStatus;diff --git a/projects/project-03/solution/src/renderer/main.tsx b/projects/project-03/solution/src/renderer/main.tsxindex 4548baf..ad7fac2 100644--- a/projects/project-03/solution/src/renderer/main.tsx+++ b/projects/project-03/solution/src/renderer/main.tsx@@ -1,4 +1,4 @@-import React from 'react';+import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';import { App } from './App';@@ -6,7 +6,7 @@ const container = document.getElementById('root');if (!container) throw new Error('Root element not found');createRoot(container).render(- <React.StrictMode>+ <StrictMode><App />- </React.StrictMode>+ </StrictMode>);diff --git a/projects/project-04/solution/package.json b/projects/project-04/solution/package.jsonindex c57e574..d0e4a1e 100644--- a/projects/project-04/solution/package.json+++ b/projects/project-04/solution/package.json@@ -18,6 +18,7 @@"devDependencies": {"@types/react": "^18.3.12","@types/react-dom": "^18.3.1",+ "@types/node": "^22.20.1","@types/uuid": "^9.0.7","@vitejs/plugin-react": "^4.3.4","electron": "^33.2.0",diff --git a/projects/project-04/solution/src/renderer/App.tsx b/projects/project-04/solution/src/renderer/App.tsxindex cede784..e9d3417 100644--- a/projects/project-04/solution/src/renderer/App.tsx+++ b/projects/project-04/solution/src/renderer/App.tsx@@ -1,9 +1,9 @@-import React, { useState, useCallback } from 'react';+import { useState, useCallback } from 'react';import { DocumentList } from './components/DocumentList';import { QuestionPanel } from './components/QuestionPanel';import { DocumentDetail } from './components/DocumentDetail';import { StatusBar } from './components/StatusBar';-import { Document, AppStatus, QAResponse } from '../../shared/types';+import { Document, AppStatus, QAResponse } from '../shared/types';declare global {interface Window {diff --git a/projects/project-04/solution/src/renderer/components/DocumentDetail.tsx b/projects/project-04/solution/src/renderer/components/DocumentDetail.tsxindex b2787ef..cb90602 100644--- a/projects/project-04/solution/src/renderer/components/DocumentDetail.tsx+++ b/projects/project-04/solution/src/renderer/components/DocumentDetail.tsx@@ -1,5 +1,5 @@-import React, { useEffect, useState } from 'react';-import { Document, Chunk } from '../../../shared/types';+import { useEffect, useState } from 'react';+import { Document, Chunk } from '../../shared/types';interface Props {document: Document;diff --git a/projects/project-04/solution/src/renderer/components/DocumentList.tsx b/projects/project-04/solution/src/renderer/components/DocumentList.tsxindex f3166ed..be4a73b 100644--- a/projects/project-04/solution/src/renderer/components/DocumentList.tsx+++ b/projects/project-04/solution/src/renderer/components/DocumentList.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { Document } from '../../../shared/types';+import { Document } from '../../shared/types';interface Props {documents: Document[];diff --git a/projects/project-04/solution/src/renderer/components/ImportPanel.tsx b/projects/project-04/solution/src/renderer/components/ImportPanel.tsxindex 29ca5cd..47c33d6 100644--- a/projects/project-04/solution/src/renderer/components/ImportPanel.tsx+++ b/projects/project-04/solution/src/renderer/components/ImportPanel.tsx@@ -1,7 +1,6 @@-import React from 'react';interface Props {- onImport: (filePath: string) => void;+ onImport: (file: File) => void;}export function ImportPanel({ onImport }: Props) {@@ -25,7 +24,7 @@ export function ImportPanel({ onImport }: Props) {accept=".txt,.md"onChange={e => {const file = e.target.files?.[0];- if (file) onImport(file.path);+ if (file) onImport(file);}}style={{ marginTop: '10px' }}/>diff --git a/projects/project-04/solution/src/renderer/components/QuestionPanel.tsx b/projects/project-04/solution/src/renderer/components/QuestionPanel.tsxindex 1b80cc5..ac605d1 100644--- a/projects/project-04/solution/src/renderer/components/QuestionPanel.tsx+++ b/projects/project-04/solution/src/renderer/components/QuestionPanel.tsx@@ -1,4 +1,4 @@-import React, { useState } from 'react';+import { useState } from 'react';interface Props {onAsk: (question: string) => void;diff --git a/projects/project-04/solution/src/renderer/components/StatusBar.tsx b/projects/project-04/solution/src/renderer/components/StatusBar.tsxindex 1bf587c..29756e1 100644--- a/projects/project-04/solution/src/renderer/components/StatusBar.tsx+++ b/projects/project-04/solution/src/renderer/components/StatusBar.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { AppStatus } from '../../../shared/types';+import { AppStatus } from '../../shared/types';interface Props {status: AppStatus;diff --git a/projects/project-04/solution/src/renderer/main.tsx b/projects/project-04/solution/src/renderer/main.tsxindex 4548baf..ad7fac2 100644--- a/projects/project-04/solution/src/renderer/main.tsx+++ b/projects/project-04/solution/src/renderer/main.tsx@@ -1,4 +1,4 @@-import React from 'react';+import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';import { App } from './App';@@ -6,7 +6,7 @@ const container = document.getElementById('root');if (!container) throw new Error('Root element not found');createRoot(container).render(- <React.StrictMode>+ <StrictMode><App />- </React.StrictMode>+ </StrictMode>);diff --git a/projects/project-06/README-CN.md b/projects/project-06/README-CN.mdindex 26214bd..38360e6 100644--- a/projects/project-06/README-CN.md+++ b/projects/project-06/README-CN.md@@ -30,6 +30,12 @@ npm install./scripts/cleanup-scanner.sh```+`npm run dev` 必须在 `projects/project-06/solution` 目录中先执行+`npm install` 后运行。该命令会先编译主进程和渲染进程,再启动 Electron;+如果编译失败,应先根据终端中的 TypeScript/Vite 错误处理。没有编译错误但+窗口空白或无法打开时,通常是 Electron 运行环境没有桌面会话导致的。反馈+启动问题时,请同时提供终端完整输出、操作系统和 Node.js 版本。+## 具体任务对应关系Project 06 是完整产品 + 弱 harness 表面,与完整产品 + 强 harness 表面的对比。和前几个项目不同,starter 已经包含大部分产品功能,差距主要在代码周围的操作系统。diff --git a/projects/project-06/README.md b/projects/project-06/README.mdindex 95ad383..d5649c8 100644--- a/projects/project-06/README.md+++ b/projects/project-06/README.md@@ -30,6 +30,14 @@ npm install./scripts/cleanup-scanner.sh```+`npm run dev` must be run from `projects/project-06/solution` after+`npm install`. It builds the main process and renderer before opening Electron;+if the build fails, fix the printed TypeScript/Vite error first. A blank or+unavailable window without a build error is usually an Electron display+environment issue (for example, running without a desktop session), not a+product failure. Include the terminal output and OS/Node version when+reporting a reproducible startup problem.+## Exact Task ContractProject 06 is a capstone comparison between a complete product with weak harnessdiff --git a/projects/project-06/solution/scripts/dev.js b/projects/project-06/solution/scripts/dev.jsindex 2312bab..420305f 100644--- a/projects/project-06/solution/scripts/dev.js+++ b/projects/project-06/solution/scripts/dev.js@@ -3,6 +3,20 @@ const path = require('path');const root = path.resolve(__dirname, '..');+function requireDependency(name) {+ try {+ require.resolve(name, { paths: [root] });+ } catch {+ console.error(`[dev] Missing dependency: ${name}`);+ console.error('[dev] Run `npm install` from projects/project-06/solution, then retry `npm run dev`.');+ process.exit(1);+ }+}++requireDependency('typescript');+requireDependency('vite');+requireDependency('electron');+console.log('[dev] Building main + preload...');try {execSync('npx tsc -p tsconfig.node.json', { cwd: root, stdio: 'inherit' });diff --git a/projects/project-06/solution/src/renderer/App.tsx b/projects/project-06/solution/src/renderer/App.tsxindex 3b2e30d..55fe73f 100644--- a/projects/project-06/solution/src/renderer/App.tsx+++ b/projects/project-06/solution/src/renderer/App.tsx@@ -1,10 +1,10 @@-import React, { useState, useCallback, useEffect } from 'react';+import { useState, useCallback, useEffect } from 'react';import { DocumentList } from './components/DocumentList';import { QuestionPanel } from './components/QuestionPanel';import { DocumentDetail } from './components/DocumentDetail';import { ConversationHistory } from './components/ConversationHistory';import { StatusBar } from './components/StatusBar';-import { Document, AppStatus, QAResponse } from '../../shared/types';+import { Document, AppStatus, QAResponse } from '../shared/types';type ViewMode = 'documents' | 'history';diff --git a/projects/project-06/solution/src/renderer/components/ConversationHistory.tsx b/projects/project-06/solution/src/renderer/components/ConversationHistory.tsxindex 64047de..2b97be3 100644--- a/projects/project-06/solution/src/renderer/components/ConversationHistory.tsx+++ b/projects/project-06/solution/src/renderer/components/ConversationHistory.tsx@@ -1,5 +1,5 @@-import React, { useEffect, useState } from 'react';-import { QAHistory } from '../../../shared/types';+import { useEffect, useState } from 'react';+import { QAHistory } from '../../shared/types';/*** ConversationHistory -- solution version.diff --git a/projects/project-06/solution/src/renderer/components/DocumentDetail.tsx b/projects/project-06/solution/src/renderer/components/DocumentDetail.tsxindex 4f16aed..6f75d20 100644--- a/projects/project-06/solution/src/renderer/components/DocumentDetail.tsx+++ b/projects/project-06/solution/src/renderer/components/DocumentDetail.tsx@@ -1,5 +1,5 @@-import React, { useEffect, useState } from 'react';-import { Document, Chunk } from '../../../shared/types';+import { useEffect, useState } from 'react';+import { Document, Chunk } from '../../shared/types';interface Props {document: Document;diff --git a/projects/project-06/solution/src/renderer/components/DocumentList.tsx b/projects/project-06/solution/src/renderer/components/DocumentList.tsxindex 895ccec..79e791d 100644--- a/projects/project-06/solution/src/renderer/components/DocumentList.tsx+++ b/projects/project-06/solution/src/renderer/components/DocumentList.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { Document } from '../../../shared/types';+import { Document } from '../../shared/types';interface Props {documents: Document[];diff --git a/projects/project-06/solution/src/renderer/components/ImportPanel.tsx b/projects/project-06/solution/src/renderer/components/ImportPanel.tsxindex b8d6564..bc95d0d 100644--- a/projects/project-06/solution/src/renderer/components/ImportPanel.tsx+++ b/projects/project-06/solution/src/renderer/components/ImportPanel.tsx@@ -1,7 +1,5 @@-import React from 'react';-interface Props {- onImport: (filePath: string) => void;+ onImport: (file: File) => void;}export function ImportPanel({ onImport }: Props) {@@ -25,7 +23,7 @@ export function ImportPanel({ onImport }: Props) {accept=".txt,.md"onChange={e => {const file = e.target.files?.[0];- if (file) onImport(file.path);+ if (file) onImport(file);}}style={{ marginTop: '10px' }}/>diff --git a/projects/project-06/solution/src/renderer/components/QuestionPanel.tsx b/projects/project-06/solution/src/renderer/components/QuestionPanel.tsxindex 1b80cc5..ac605d1 100644--- a/projects/project-06/solution/src/renderer/components/QuestionPanel.tsx+++ b/projects/project-06/solution/src/renderer/components/QuestionPanel.tsx@@ -1,4 +1,4 @@-import React, { useState } from 'react';+import { useState } from 'react';interface Props {onAsk: (question: string) => void;diff --git a/projects/project-06/solution/src/renderer/components/StatusBar.tsx b/projects/project-06/solution/src/renderer/components/StatusBar.tsxindex c28d25d..ea2ebf1 100644--- a/projects/project-06/solution/src/renderer/components/StatusBar.tsx+++ b/projects/project-06/solution/src/renderer/components/StatusBar.tsx@@ -1,5 +1,4 @@-import React from 'react';-import { AppStatus } from '../../../shared/types';+import { AppStatus } from '../../shared/types';interface Props {status: AppStatus;diff --git a/projects/project-06/solution/src/renderer/main.tsx b/projects/project-06/solution/src/renderer/main.tsxindex 4548baf..ad7fac2 100644--- a/projects/project-06/solution/src/renderer/main.tsx+++ b/projects/project-06/solution/src/renderer/main.tsx@@ -1,4 +1,4 @@-import React from 'react';+import { StrictMode } from 'react';import { createRoot } from 'react-dom/client';import { App } from './App';@@ -6,7 +6,7 @@ const container = document.getElementById('root');if (!container) throw new Error('Root element not found');createRoot(container).render(- <React.StrictMode>+ <StrictMode><App />- </React.StrictMode>+ </StrictMode>);diff --git a/projects/project-06/solution/src/services/qa-service.ts b/projects/project-06/solution/src/services/qa-service.tsindex 8d52c30..1530017 100644--- a/projects/project-06/solution/src/services/qa-service.ts+++ b/projects/project-06/solution/src/services/qa-service.ts@@ -56,32 +56,6 @@ const MOCK_PATTERNS: Array<{},];-/** Generate follow-up suggestions based on the answer context. */-function generateFollowUps(question: string, citations: Citation[]): string[] {- const suggestions: string[] = [];-- if (citations.length > 0) {- suggestions.push(`Tell me more about ${citations[0].documentTitle}`);- }-- const questionLower = question.toLowerCase();- if (questionLower.includes('architecture') || questionLower.includes('design')) {- suggestions.push('How does the indexing pipeline work?');- suggestions.push('What logging is available?');- } else if (questionLower.includes('import') || questionLower.includes('document')) {- suggestions.push('How are documents indexed?');- suggestions.push('What file formats are supported?');- } else if (questionLower.includes('index') || questionLower.includes('chunk')) {- suggestions.push('How does keyword retrieval work?');- suggestions.push('What is the chunk size?');- } else {- suggestions.push('What is the system architecture?');- suggestions.push('How do I import documents?');- }-- return suggestions.slice(0, 3);-}-export class QaService {private persistence: PersistenceService;private indexingService: IndexingService;diff --git a/projects/project-06/solution/src/shared/types.ts b/projects/project-06/solution/src/shared/types.tsindex 31611cc..292069b 100644--- a/projects/project-06/solution/src/shared/types.ts+++ b/projects/project-06/solution/src/shared/types.ts@@ -58,6 +58,7 @@ export interface ConversationMessage {export interface AppStatus {documentsLoaded: number;+ currentIndexed?: number;indexStatus: 'idle' | 'indexing' | 'ready' | 'error';lastActivity: string;}