Skip to content

Commit de9d1ff

Browse files
sanbuphysanbuphy
authored
Merge pull request #11 from cv47522/translate
docs(projects): add bilingual project readmes
2 parents 3b2d6fc + 37cee7c commit de9d1ff

12 files changed

Lines changed: 346 additions & 119 deletions

File tree

‎projects/project-01/README-CN.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Project 01: Baseline vs Minimal Harness
2+
3+
比较弱 harness（仅靠 prompt）和显式 harness（规则文件 + 验证机制）对 AI 编码代理任务完成率的影响。
4+
5+
## 目录说明
6+
7+
| 目录 | 含义 |
8+
|------|------|
9+
| `starter/` | **起点**——只有一个模糊的 `task-prompt.md`，没有 AGENTS.md、没有 feature_list.json。这是你给代理的"弱 harness"版本。 |
10+
| `solution/` | **参考实现**——相同的应用代码，但配备了完整的 harness 文件（AGENTS.md、feature_list.json、init.sh、claude-progress.md）。这是"显式 harness"版本。 |
11+
12+
## 使用方法
13+
14+
```sh
15+
# 1. 用 starter（弱 harness）跑一次代理任务
16+
cd starter
17+
npm install
18+
# 把 task-prompt.md 的内容作为 prompt 给 Claude Code / Codex
19+
# 让代理尝试完成：窗口启动、文档列表、问答面板、数据目录
20+
21+
# 2. 用 solution（显式 harness）跑一次
22+
cd ../solution
23+
npm install
24+
# 让代理读取 AGENTS.md，按规则执行同样的任务
25+
26+
# 3. 对比两次结果
27+
# - 任务是否完成？
28+
# - 需要重试几次？
29+
# - 代理是否提前声称"完成"？
30+
```
31+
32+
## 本项目涉及的功能
33+
34+
- Electron 窗口成功启动
35+
- UI 显示文档列表区域
36+
- UI 显示问答面板
37+
- 应用创建并使用本地数据目录
38+
39+
## 对应课件
40+
41+
- [Lecture 01: 为什么强大的模型仍然会失败](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
42+
- [Lecture 02: Harness 到底是什么](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md)

‎projects/project-01/README.md‎

Lines changed: 23 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,42 @@
11
# Project 01: Baseline vs Minimal Harness
22

3-
比较弱 harness（仅靠 prompt）和显式 harness（规则文件 + 验证机制）对 AI 编码代理任务完成率的影响。
3+
Compare how a weak harness (prompt only) and an explicit harness (rule files plus verification mechanisms) affect the completion rate of AI coding-agent tasks.
44

5-
## 目录说明
5+
## Directory Guide
66

7-
| 目录 | 含义 |
7+
| Directory | Meaning |
88
|------|------|
9-
| `starter/` | **起点**——只有一个模糊的 `task-prompt.md`，没有 AGENTS.md、没有 feature_list.json。这是你给代理的"弱 harness"版本。 |
10-
| `solution/` | **参考实现**——相同的应用代码，但配备了完整的 harness 文件（AGENTS.md、feature_list.json、init.sh、claude-progress.md）。这是"显式 harness"版本。 |
9+
| `starter/` | **Starting point**: only a vague `task-prompt.md`, with no AGENTS.md and no feature_list.json. This is the "weak harness" version you give to the agent. |
10+
| `solution/` | **Reference implementation**: the same application code, but with complete harness files (AGENTS.md, feature_list.json, init.sh, claude-progress.md). This is the "explicit harness" version. |
1111

12-
## 使用方法
12+
## How to Use
1313

1414
```sh
15-
# 1. 用 starter（弱 harness）跑一次代理任务
15+
# 1. Run the agent task once with starter (weak harness)
1616
cd starter
1717
npm install
18-
# 把 task-prompt.md 的内容作为 prompt 给 Claude Code / Codex
19-
# 让代理尝试完成：窗口启动、文档列表、问答面板、数据目录
18+
# Give the contents of task-prompt.md as the prompt to Claude Code / Codex
19+
# Ask the agent to complete: window startup, document list, QA panel, data directory
2020

21-
# 2. 用 solution（显式 harness）跑一次
21+
# 2. Run the same task with solution (explicit harness)
2222
cd ../solution
2323
npm install
24-
# 让代理读取 AGENTS.md，按规则执行同样的任务
24+
# Ask the agent to read AGENTS.md and follow the rules for the same task
2525

26-
# 3. 对比两次结果
27-
# - 任务是否完成？
28-
# - 需要重试几次？
29-
# - 代理是否提前声称"完成"？
26+
# 3. Compare the two results
27+
# - Was the task completed?
28+
# - How many retries were needed?
29+
# - Did the agent claim "done" too early?
3030
```
3131

32-
## 本项目涉及的功能
32+
## Features Covered
3333

34-
- Electron 窗口成功启动
35-
- UI 显示文档列表区域
36-
- UI 显示问答面板
37-
- 应用创建并使用本地数据目录
34+
- Electron window starts successfully
35+
- UI shows the document-list area
36+
- UI shows the QA panel
37+
- App creates and uses a local data directory
3838

39-
## 对应课件
39+
## Related Lectures
4040

41-
- [Lecture 01: 为什么强大的模型仍然会失败](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
42-
- [Lecture 02: Harness 到底是什么](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
41+
- [Lecture 01: Why Capable Agents Still Fail](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md)
42+
- [Lecture 02: What a Harness Actually Is](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md)

‎projects/project-02/README-CN.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Project 02: Agent-Readable Workspace
2+
3+
演示仓库可读性和显式连续性产物如何减少跨会话开发中的上下文丢失。
4+
5+
## 目录说明
6+
7+
| 目录 | 含义 |
8+
|------|------|
9+
| `starter/` | **起点**——基于 P1 solution 的代码，新增文档导入、详情视图、持久化功能待实现。harness 较弱：AGENTS.md 简陋，没有 session-handoff。 |
10+
| `solution/` | **参考实现**——所有新功能已实现，配备完整的 workspace 文档（ARCHITECTURE.md、PRODUCT.md、session-handoff.md）。 |
11+
12+
## 使用方法
13+
14+
```sh
15+
# 需要至少 2 个 agent 会话来完成
16+
cd starter
17+
npm install
18+
# Session A: 实现文档导入和详情视图
19+
# Session B: 实现持久化（观察 agent 能否快速恢复上下文）
20+
21+
cd ../solution
22+
npm install
23+
# 用完整 harness 重跑，对比会话恢复速度
24+
```
25+
26+
## 本项目涉及的功能
27+
28+
- 文档导入流程（文件选择器 + IPC 传输）
29+
- 文档详情视图（元数据 + 内容展示）
30+
- 基本持久化（导入的文档在重启后保留）
31+
32+
## 对应课件
33+
34+
- [Lecture 03: 让仓库成为唯一的真相来源](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
35+
- [Lecture 04: 拆分指令文件，而不是一个巨型文件](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)

‎projects/project-02/README.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,35 @@
11
# Project 02: Agent-Readable Workspace
22

3-
演示仓库可读性和显式连续性产物如何减少跨会话开发中的上下文丢失。
3+
Demonstrate how repository readability and explicit continuity artifacts reduce context loss during multi-session development.
44

5-
## 目录说明
5+
## Directory Guide
66

7-
| 目录 | 含义 |
7+
| Directory | Meaning |
88
|------|------|
9-
| `starter/` | **起点**——基于 P1 solution 的代码，新增文档导入、详情视图、持久化功能待实现。harness 较弱：AGENTS.md 简陋，没有 session-handoff。 |
10-
| `solution/` | **参考实现**——所有新功能已实现，配备完整的 workspace 文档（ARCHITECTURE.md、PRODUCT.md、session-handoff.md）。 |
9+
| `starter/` | **Starting point**: based on the P1 solution, with document import, detail view, and persistence still to implement. The harness is weak: AGENTS.md is minimal and there is no session handoff. |
10+
| `solution/` | **Reference implementation**: all new features are implemented, with complete workspace documentation (ARCHITECTURE.md, PRODUCT.md, session-handoff.md). |
1111

12-
## 使用方法
12+
## How to Use
1313

1414
```sh
15-
# 需要至少 2 个 agent 会话来完成
15+
# Requires at least 2 agent sessions to complete
1616
cd starter
1717
npm install
18-
# Session A: 实现文档导入和详情视图
19-
# Session B: 实现持久化（观察 agent 能否快速恢复上下文）
18+
# Session A: implement document import and the detail view
19+
# Session B: implement persistence (observe whether the agent quickly regains context)
2020

2121
cd ../solution
2222
npm install
23-
# 用完整 harness 重跑，对比会话恢复速度
23+
# Rerun with the complete harness and compare session recovery speed
2424
```
2525

26-
## 本项目涉及的功能
26+
## Features Covered
2727

28-
- 文档导入流程（文件选择器 + IPC 传输）
29-
- 文档详情视图（元数据 + 内容展示）
30-
- 基本持久化（导入的文档在重启后保留）
28+
- Document import flow (file picker plus IPC transfer)
29+
- Document detail view (metadata plus content display)
30+
- Basic persistence (imported documents remain after restart)
3131

32-
## 对应课件
32+
## Related Lectures
3333

34-
- [Lecture 03: 让仓库成为唯一的真相来源](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
35-
- [Lecture 04: 拆分指令文件，而不是一个巨型文件](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
34+
- [Lecture 03: Why the Repository Must Become the System of Record](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
35+
- [Lecture 04: Why One Giant Instruction File Fails](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)

‎projects/project-03/README-CN.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Project 03: Scope Control and Grounded Verification
2+
3+
评估显式范围控制和验证门控是否能提高交付准确性。
4+
5+
## 目录说明
6+
7+
| 目录 | 含义 |
8+
|------|------|
9+
| `starter/` | **起点**——基于 P2 solution，新增文档分块、元数据提取、索引状态、基础问答功能待实现。没有一次一个功能的策略约束。 |
10+
| `solution/` | **参考实现**——所有功能已实现，AGENTS.md 包含"一次一个功能"策略，feature_list.json 展示 fail→pass 的转换过程和验证证据。 |
11+
12+
## 使用方法
13+
14+
```sh
15+
cd starter
16+
npm install
17+
# 观察 agent 是否会同时实现多个功能（范围漂移）
18+
19+
cd ../solution
20+
npm install
21+
# 用 scope control 重跑，对比功能交付准确性
22+
```
23+
24+
## 本项目涉及的功能
25+
26+
- 文档分块（段落感知，~500 字符）
27+
- 元数据提取（词数、行数、段落数）
28+
- 索引状态在 UI 中显示
29+
- 基础问答流程，带来源引用
30+
31+
## 对应课件
32+
33+
- [Lecture 05: 保持跨会话上下文](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
34+
- [Lecture 06: 每次会话前先初始化](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)

‎projects/project-03/README.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,34 @@
11
# Project 03: Scope Control and Grounded Verification
22

3-
评估显式范围控制和验证门控是否能提高交付准确性。
3+
Evaluate whether explicit scope control and verification gates improve delivery accuracy.
44

5-
## 目录说明
5+
## Directory Guide
66

7-
| 目录 | 含义 |
7+
| Directory | Meaning |
88
|------|------|
9-
| `starter/` | **起点**——基于 P2 solution，新增文档分块、元数据提取、索引状态、基础问答功能待实现。没有一次一个功能的策略约束。 |
10-
| `solution/` | **参考实现**——所有功能已实现，AGENTS.md 包含"一次一个功能"策略，feature_list.json 展示 fail→pass 的转换过程和验证证据。 |
9+
| `starter/` | **Starting point**: based on the P2 solution, with document chunking, metadata extraction, index status, and basic QA still to implement. There is no "one feature at a time" strategy constraint. |
10+
| `solution/` | **Reference implementation**: all features are implemented. AGENTS.md includes a "one feature at a time" strategy, and feature_list.json shows the fail-to-pass transition and verification evidence. |
1111

12-
## 使用方法
12+
## How to Use
1313

1414
```sh
1515
cd starter
1616
npm install
17-
# 观察 agent 是否会同时实现多个功能（范围漂移）
17+
# Observe whether the agent implements multiple features at once (scope drift)
1818

1919
cd ../solution
2020
npm install
21-
# 用 scope control 重跑，对比功能交付准确性
21+
# Rerun with scope control and compare feature delivery accuracy
2222
```
2323

24-
## 本项目涉及的功能
24+
## Features Covered
2525

26-
- 文档分块（段落感知，~500 字符）
27-
- 元数据提取（词数、行数、段落数）
28-
- 索引状态在 UI 中显示
29-
- 基础问答流程，带来源引用
26+
- Document chunking (paragraph-aware, about 500 characters)
27+
- Metadata extraction (word count, line count, paragraph count)
28+
- Index status displayed in the UI
29+
- Basic QA flow with source citations
3030

31-
## 对应课件
31+
## Related Lectures
3232

33-
- [Lecture 05: 保持跨会话上下文](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
34-
- [Lecture 06: 每次会话前先初始化](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
33+
- [Lecture 05: Why Long-Running Tasks Lose Continuity](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
34+
- [Lecture 06: Why Initialization Needs Its Own Phase](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)

‎projects/project-04/README-CN.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Project 04: Runtime Observability and Structural Control
2+
3+
引入运行时可观测性和结构化边界检查，同时调试一个植入的运行时缺陷。
4+
5+
## 目录说明
6+
7+
| 目录 | 含义 |
8+
|------|------|
9+
| `starter/` | **起点**——基于 P3 solution，新增日志、结构化边界功能待实现。`IndexingService` 中植入了一个隐蔽 bug：超过 1000 字符的文件会产生空分块。没有架构检查脚本。 |
10+
| `solution/` | **参考实现**——结构化日志模块、架构边界检查脚本、植入 bug 已修复。 |
11+
12+
## 使用方法
13+
14+
```sh
15+
cd starter
16+
npm install
17+
# 1. 观察 agent 能否通过日志定位 bug
18+
# 2. 导入一个大文件，观察分块结果是否异常
19+
20+
cd ../solution
21+
npm install
22+
# 对比：结构化日志如何加速问题诊断
23+
```
24+
25+
## 本项目涉及的功能
26+
27+
- 启动日志
28+
- 导入和索引日志
29+
- 可见的问答失败路径
30+
- main / preload / renderer / services 层的显式边界
31+
- 调试一个植入的运行时缺陷
32+
33+
## 对应课件
34+
35+
- [Lecture 07: 给代理划定清晰的任务边界](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
36+
- [Lecture 08: 用功能列表约束代理行为](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)

‎projects/project-04/README.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,36 @@
11
# Project 04: Runtime Observability and Structural Control
22

3-
引入运行时可观测性和结构化边界检查，同时调试一个植入的运行时缺陷。
3+
Introduce runtime observability and structural boundary checks while debugging a seeded runtime defect.
44

5-
## 目录说明
5+
## Directory Guide
66

7-
| 目录 | 含义 |
7+
| Directory | Meaning |
88
|------|------|
9-
| `starter/` | **起点**——基于 P3 solution，新增日志、结构化边界功能待实现。`IndexingService` 中植入了一个隐蔽 bug：超过 1000 字符的文件会产生空分块。没有架构检查脚本。 |
10-
| `solution/` | **参考实现**——结构化日志模块、架构边界检查脚本、植入 bug 已修复。 |
9+
| `starter/` | **Starting point**: based on the P3 solution, with logging and structural boundary features still to implement. `IndexingService` contains a hidden seeded bug: files longer than 1000 characters produce empty chunks. There is no architecture-check script. |
10+
| `solution/` | **Reference implementation**: structured logging module, architecture boundary-check script, and the seeded bug fixed. |
1111

12-
## 使用方法
12+
## How to Use
1313

1414
```sh
1515
cd starter
1616
npm install
17-
# 1. 观察 agent 能否通过日志定位 bug
18-
# 2. 导入一个大文件，观察分块结果是否异常
17+
# 1. Observe whether the agent can locate the bug through logs
18+
# 2. Import a large file and check whether chunking behaves incorrectly
1919

2020
cd ../solution
2121
npm install
22-
# 对比：结构化日志如何加速问题诊断
22+
# Compare how structured logs speed up diagnosis
2323
```
2424

25-
## 本项目涉及的功能
25+
## Features Covered
2626

27-
- 启动日志
28-
- 导入和索引日志
29-
- 可见的问答失败路径
30-
- main / preload / renderer / services 层的显式边界
31-
- 调试一个植入的运行时缺陷
27+
- Startup logs
28+
- Import and indexing logs
29+
- Visible QA failure path
30+
- Explicit boundaries between main, preload, renderer, and services layers
31+
- Debugging a seeded runtime defect
3232

33-
## 对应课件
33+
## Related Lectures
3434

35-
- [Lecture 07: 给代理划定清晰的任务边界](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
36-
- [Lecture 08: 用功能列表约束代理行为](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
35+
- [Lecture 07: Why Agents Overreach and Under-Finish](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
36+
- [Lecture 08: Why Feature Lists Are Harness Primitives](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)

0 commit comments

Comments
 (0)