【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本指南围绕 learn-harness-engineering 开源仓库中的 Project 02「Agent-Readable Workspace」Agent 可读工作区展开讲解如何通过「仓库可读性」与「显式连续性工件」ARCHITECTURE.md、PRODUCT.md、session-handoff.md 等降低多会话开发中的上下文丢失问题。读者将掌握两阶段无辅助 vs 有辅助对比实验方法、基于 Electron React TypeScript 的文档导入/详情查看/持久化三大功能实现路径以及让第二个 Agent 会话仅凭仓库状态即可快速恢复工作的完整 harness 机制。项目背景与实验目标Project 02 是 learn-harness-engineering 教程系列中围绕「仓库必须成为系统事实源system of record」与「为什么单一巨型指令文件会失败」两讲见 Leçon 03 与 Leçon 04配套的实践项目。它的核心问题是当一个 Agent 会话中断后第二个会话只从仓库状态出发能否快速恢复上下文并继续工作本项目的任务载体是projects/project-02/目录包含两个可对比的工程目录内容对比关注点starter/基于 Project 01 代码文档导入、详情查看与持久化功能尚不完整文档较简略且没有session-handoff.md第二个会话需要重新发现多少上下文solution/同一产品切片已完整实现并附带恢复文档docs/ARCHITECTURE.md、docs/PRODUCT.md以及feature_list.json与session-handoff.md新会话能否仅凭仓库状态恢复工作实验设计为「两次运行」第一次不带任何辅助文档运行第二次预先放置上述文档再运行对比两次会话的恢复速度与质量。需要的工具与运行方式Agent 工具Claude Code 或 Codex用于执行两阶段会话实验Git版本管理观察变更Node.js Electron应用的运行环境运行命令需至少 2 个 Agent 会话完成# 进入 starter 目录 cd projects/project-02/starter npm install # 会话 A实现文档导入与详情查看 # 会话 B实现持久化观察 Agent 是否快速恢复上下文 # 进入 solution 目录 cd ../solution npm install # 携带完整 harness 重新运行对比会话恢复速度按照仓库 READMEprojects/project-02/README.md的建议这是一个两会话练习在三个产品功能全部完成前结束会话 A然后让会话 B 仅从仓库状态开始主要对比session-handoff.md与 docs 存在时会话 B 的恢复速度。Harness 机制Agent 可读工作区 持久化状态文件本项目的 harness 机制由两部分组成Agent 可读工作区Agent-readable workspace把架构、产品需求、启动规则等以结构化文档形式放入仓库让新会话可以快速理解项目边界与约定。持久化状态文件Persistent state filesfeature_list.json记录每个功能的状态与证据session-handoff.md记录上一会话的完成情况、遗留事项与决策二者共同构成会话之间的「记忆载体」。工作区文档层级docs/目录按 Agent 可读性组织见 solution/AGENTS.mddocs/ ARCHITECTURE.md -- Electron 分层、数据流、导入流水线 PRODUCT.md -- 功能需求与用户可见行为AGENTS.md 要求新增功能前先更新相关文档再写代码这能帮助 Agent 跨会话理解变更。启动规则Startup Rulessolution 的 AGENTS.md 定义了会话开始时的固定顺序完整阅读本文件理解项目边界与约定阅读docs/ARCHITECTURE.md理解 Electron 分层与导入流程阅读docs/PRODUCT.md理解功能需求运行npm install npm run check验证构建阅读feature_list.json查看所有功能当前状态。对比 starter 的 AGENTS.md仅 3 条 Quick Start 步骤加分层与约定摘要solution 的 AGENTS.md 增加了「会话交接Session Handoff」小节恢复工作时先读session-handoff.md结束会话时更新它记录完成内容、遗留事项、阻塞项/决策、修改过的文件。精确任务契约Exact Task Contract从 starter 开始。starter 已包含 Project 01 外壳与一个最小 harness任务是为 Project 02 产品切片加上让第二个会话快速恢复的工作区文档。各功能/工件在 starter 与 solution 中的状态对照如下功能 / 工件Starter 状态Solution 证据文档导入渲染层、preload、IPC、DocumentService的导入流程不完整src/renderer/components/ImportPanel.tsx、src/main/ipc-handlers.ts、src/services/document-service.ts文档详情详情面板未通过 IPC 加载并渲染完整文件内容src/renderer/components/DocumentDetail.tsx、IPC_CHANNELS.GET_DOCUMENT_CONTENT基础持久化导入的文档重启后不能完整恢复src/services/persistence-service.ts、documents-meta.json处理Agent 可读状态starter 中没有最终交接文件session-handoff.md、扩充的docs/ARCHITECTURE.md、扩充的docs/PRODUCT.md功能覆盖范围Project 02 覆盖三个核心产品功能详见 feature_list.json 的 7 项特性文档导入流程文件选择器 IPC 传输document-import文档详情视图元数据 内容展示document-detail基础持久化重启后导入文档仍然保留basic-persistence。其余 4 项窗口启动、文档列表面板、提问面板、数据目录从 Project 01 继承并验证通过。从源码理解三大功能的实现路径1. 文档导入全链路 IPC 数据通路架构文档ARCHITECTURE.md给出了完整的导入流程它演示了完整的 IPC 数据通路1. 用户在 App.tsx 中点击 Import 按钮 2. ImportPanel 渲染文件输入框 3. 用户选择 .txt 或 .md 文件 4. ImportPanel 调用 onImport(file.path) 5. App.tsx 调用 window.knowledgeBase.documents.import(filePath) 6. Preload 桥接层调用 ipcRenderer.invoke(documents:import, filePath) 7. ipc-handlers.ts 委托给 DocumentService.importDocument(filePath) 8. DocumentService a. 校验文件存在 b. 读取文件内容与 stat 信息 c. 创建 Document 元数据对象 d. 通过 PersistenceService 将文件复制到 documents 目录 e. 通过 PersistenceService 存储提取的文本内容 f. 追加到 documents-meta.json 9. 结果经 IPC 返回 10. App.tsx 调用 refreshDocuments() 更新列表 11. DocumentList 用新文档重新渲染底层实现可对照 document-service.ts 的importDocument()方法先fs.existsSync校验文件存在再用fs.readFileSync读取内容、fs.statSync获取大小生成包含iduuid v4、title去掉扩展名的文件名、filename、importedAt、size、status的Document对象随后copyFileToDocuments复制原件、writeText(content/id.txt)保存纯文本内容、writeJson(documents-meta.json)追加元数据。2. 文档详情专用 get-content IPC 通道内容查看增加了一条专用 IPC 通道对应IPC_CHANNELS.GET_DOCUMENT_CONTENT即documents:get-content流程如下1. 用户在 DocumentDetail 点击 View Content 2. DocumentDetail 调用 window.knowledgeBase.documents.getContent(id) 3. Preload 调用 documents:get-content IPC 4. ipc-handlers 委托给 DocumentService.getDocumentContent(id) 5. PersistenceService 读取 content/id.txt 6. 内容返回渲染层在 pre-wrap 容器中展示会话交接文件记录了该决策的动机session-handoff.md新增GET_DOCUMENT_CONTENT通道而非把内容打包进GET_DOCUMENT是为了让列表视图的 IPC 载荷保持轻量。删除按钮则同时移除存储的内容文件与 documents 目录中的原件副本。3. 基础持久化文件系统即存储持久化由 persistence-service.ts 实现它提供低层 JSON/文本文件 I/O原子写入语义先mkdirSync保证目录存在再writeFileSync。数据统一存放在app.getPath(userData)/knowledge-base-data/下knowledge-base-data/ documents-meta.json # 文档元数据数组 content/ doc-id.txt # 每篇文档提取的文本内容 chunks/ doc-id.json # 每篇文档的分块数组 index/ index-meta.json # 文档 ID 到分块 ID 的映射 qa-history.json # QA 交互日志持久化恢复的机制是App.tsx在挂载时通过useEffect调用refreshDocuments()DocumentService启动时读取documents-meta.jsonPersistenceService.readJson在文件不存在时返回 null从而在重启后完整恢复文档列表。会话交接文档剖析session-handoff.md 的结构session-handoff.md 是「仓库即系统事实源」的直接体现其结构包括Last Session最后会话时间戳如 2026-03-30What Was Accomplished已完成内容分点列出导入、详情、持久化三项各自的实现位置What Remains遗留事项Project 02 无遗留feature_list.json 中 7 项全部为passDecisions Made关键决策及其理由如新增GET_DOCUMENT_CONTENT通道、删除时同时移除内容文件与原件、导入面板以替换而非模态框方式出现Files Modified修改过的文件清单从src/shared/types.ts到docs/PRODUCT.md共 15 项Blockers阻塞项NoneNext Steps下一步进入 Project 03添加索引、元数据提取与 grounded QA。功能验收标准Definition of Donesolution 的 AGENTS.md 定义了「完成」的五条标准TypeScript 编译无错误npm run check应用能启动且窗口可见功能以pass状态和证据出现在feature_list.json代码遵守 Electron 分层边界主进程拥有窗口生命周期与 IPC 注册、preload 是主进程与渲染层之间唯一桥梁、渲染层仅通过window.knowledgeBaseAPI 通信且绝不导入 Node.js 模块、服务层是主进程中的纯 TypeScript 业务逻辑并构造注入PersistenceService变更反映到docs/ARCHITECTURE.md与/或docs/PRODUCT.md。feature_list.json中每条功能都带有status、evidence实现证据描述与testedAt时间戳例如document-import的证据写明「ImportPanel 触发window.knowledgeBase.documents.import(filePath)成功后 App.tsx 刷新文档列表Import 按钮切换导入视图」。关键工程约定TypeScript strict 模式不允许无注释的any仅具名导出named exportsIPC 通道在src/shared/types.ts中定义一次作为唯一事实源IPC_CHANNELS常量见 types.ts新增 IPC 通道遵循namespace:action模式如documents:get-content。相关课程导航Leçon 03. 为什么仓库必须成为系统事实源Leçon 04. 为什么单一巨型指令文件会失败这两讲为本项目提供了理论支撑Leçon 03 论证仓库文档化的必要性Leçon 04 论证将指令分散到多个文件而非堆在一个巨型文件中的合理性——Project 02 的AGENTS.md、ARCHITECTURE.md、PRODUCT.md、feature_list.json与session-handoff.md正是这一理念的可执行落地。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Project 02 实战用 Agent 可读工作区与交接文件让 Agent 跨会话无缝续作learn-harness-engineeringProject 02 实战用 Agent 可读工作区与交接文件让 Agent 跨会话无缝续作learn harness engineering 导读 本RemoveWindowsAI 一键清除 CopilotRemoveWindowsAI 一键清除 Copilot RemoveWindowsAI 能把 Windows 11 里的 Copilot 、 Recall 等Learn Harness Engineering 会话交接指南用 session-handoff.md 实现 Agent 多会话无缝续接Learn Harness Engineering 会话交接指南用 session handoff.md 实现 Agent 多会话无缝续接 本文围绕 lear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 构建 Agent 可读工作区：以 learn-harness-engineering Project 02 为例实现多会话无缝交接
【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本指南围绕 learn-harness-engineering 开源仓库中的 Project 02「Agent-Readable Workspace」Agent 可读工作区展开讲解如何通过「仓库可读性」与「显式连续性工件」ARCHITECTURE.md、PRODUCT.md、session-handoff.md 等降低多会话开发中的上下文丢失问题。读者将掌握两阶段无辅助 vs 有辅助对比实验方法、基于 Electron React TypeScript 的文档导入/详情查看/持久化三大功能实现路径以及让第二个 Agent 会话仅凭仓库状态即可快速恢复工作的完整 harness 机制。项目背景与实验目标Project 02 是 learn-harness-engineering 教程系列中围绕「仓库必须成为系统事实源system of record」与「为什么单一巨型指令文件会失败」两讲见 Leçon 03 与 Leçon 04配套的实践项目。它的核心问题是当一个 Agent 会话中断后第二个会话只从仓库状态出发能否快速恢复上下文并继续工作本项目的任务载体是projects/project-02/目录包含两个可对比的工程目录内容对比关注点starter/基于 Project 01 代码文档导入、详情查看与持久化功能尚不完整文档较简略且没有session-handoff.md第二个会话需要重新发现多少上下文solution/同一产品切片已完整实现并附带恢复文档docs/ARCHITECTURE.md、docs/PRODUCT.md以及feature_list.json与session-handoff.md新会话能否仅凭仓库状态恢复工作实验设计为「两次运行」第一次不带任何辅助文档运行第二次预先放置上述文档再运行对比两次会话的恢复速度与质量。需要的工具与运行方式Agent 工具Claude Code 或 Codex用于执行两阶段会话实验Git版本管理观察变更Node.js Electron应用的运行环境运行命令需至少 2 个 Agent 会话完成# 进入 starter 目录 cd projects/project-02/starter npm install # 会话 A实现文档导入与详情查看 # 会话 B实现持久化观察 Agent 是否快速恢复上下文 # 进入 solution 目录 cd ../solution npm install # 携带完整 harness 重新运行对比会话恢复速度按照仓库 READMEprojects/project-02/README.md的建议这是一个两会话练习在三个产品功能全部完成前结束会话 A然后让会话 B 仅从仓库状态开始主要对比session-handoff.md与 docs 存在时会话 B 的恢复速度。Harness 机制Agent 可读工作区 持久化状态文件本项目的 harness 机制由两部分组成Agent 可读工作区Agent-readable workspace把架构、产品需求、启动规则等以结构化文档形式放入仓库让新会话可以快速理解项目边界与约定。持久化状态文件Persistent state filesfeature_list.json记录每个功能的状态与证据session-handoff.md记录上一会话的完成情况、遗留事项与决策二者共同构成会话之间的「记忆载体」。工作区文档层级docs/目录按 Agent 可读性组织见 solution/AGENTS.mddocs/ ARCHITECTURE.md -- Electron 分层、数据流、导入流水线 PRODUCT.md -- 功能需求与用户可见行为AGENTS.md 要求新增功能前先更新相关文档再写代码这能帮助 Agent 跨会话理解变更。启动规则Startup Rulessolution 的 AGENTS.md 定义了会话开始时的固定顺序完整阅读本文件理解项目边界与约定阅读docs/ARCHITECTURE.md理解 Electron 分层与导入流程阅读docs/PRODUCT.md理解功能需求运行npm install npm run check验证构建阅读feature_list.json查看所有功能当前状态。对比 starter 的 AGENTS.md仅 3 条 Quick Start 步骤加分层与约定摘要solution 的 AGENTS.md 增加了「会话交接Session Handoff」小节恢复工作时先读session-handoff.md结束会话时更新它记录完成内容、遗留事项、阻塞项/决策、修改过的文件。精确任务契约Exact Task Contract从 starter 开始。starter 已包含 Project 01 外壳与一个最小 harness任务是为 Project 02 产品切片加上让第二个会话快速恢复的工作区文档。各功能/工件在 starter 与 solution 中的状态对照如下功能 / 工件Starter 状态Solution 证据文档导入渲染层、preload、IPC、DocumentService的导入流程不完整src/renderer/components/ImportPanel.tsx、src/main/ipc-handlers.ts、src/services/document-service.ts文档详情详情面板未通过 IPC 加载并渲染完整文件内容src/renderer/components/DocumentDetail.tsx、IPC_CHANNELS.GET_DOCUMENT_CONTENT基础持久化导入的文档重启后不能完整恢复src/services/persistence-service.ts、documents-meta.json处理Agent 可读状态starter 中没有最终交接文件session-handoff.md、扩充的docs/ARCHITECTURE.md、扩充的docs/PRODUCT.md功能覆盖范围Project 02 覆盖三个核心产品功能详见 feature_list.json 的 7 项特性文档导入流程文件选择器 IPC 传输document-import文档详情视图元数据 内容展示document-detail基础持久化重启后导入文档仍然保留basic-persistence。其余 4 项窗口启动、文档列表面板、提问面板、数据目录从 Project 01 继承并验证通过。从源码理解三大功能的实现路径1. 文档导入全链路 IPC 数据通路架构文档ARCHITECTURE.md给出了完整的导入流程它演示了完整的 IPC 数据通路1. 用户在 App.tsx 中点击 Import 按钮 2. ImportPanel 渲染文件输入框 3. 用户选择 .txt 或 .md 文件 4. ImportPanel 调用 onImport(file.path) 5. App.tsx 调用 window.knowledgeBase.documents.import(filePath) 6. Preload 桥接层调用 ipcRenderer.invoke(documents:import, filePath) 7. ipc-handlers.ts 委托给 DocumentService.importDocument(filePath) 8. DocumentService a. 校验文件存在 b. 读取文件内容与 stat 信息 c. 创建 Document 元数据对象 d. 通过 PersistenceService 将文件复制到 documents 目录 e. 通过 PersistenceService 存储提取的文本内容 f. 追加到 documents-meta.json 9. 结果经 IPC 返回 10. App.tsx 调用 refreshDocuments() 更新列表 11. DocumentList 用新文档重新渲染底层实现可对照 document-service.ts 的importDocument()方法先fs.existsSync校验文件存在再用fs.readFileSync读取内容、fs.statSync获取大小生成包含iduuid v4、title去掉扩展名的文件名、filename、importedAt、size、status的Document对象随后copyFileToDocuments复制原件、writeText(content/id.txt)保存纯文本内容、writeJson(documents-meta.json)追加元数据。2. 文档详情专用 get-content IPC 通道内容查看增加了一条专用 IPC 通道对应IPC_CHANNELS.GET_DOCUMENT_CONTENT即documents:get-content流程如下1. 用户在 DocumentDetail 点击 View Content 2. DocumentDetail 调用 window.knowledgeBase.documents.getContent(id) 3. Preload 调用 documents:get-content IPC 4. ipc-handlers 委托给 DocumentService.getDocumentContent(id) 5. PersistenceService 读取 content/id.txt 6. 内容返回渲染层在 pre-wrap 容器中展示会话交接文件记录了该决策的动机session-handoff.md新增GET_DOCUMENT_CONTENT通道而非把内容打包进GET_DOCUMENT是为了让列表视图的 IPC 载荷保持轻量。删除按钮则同时移除存储的内容文件与 documents 目录中的原件副本。3. 基础持久化文件系统即存储持久化由 persistence-service.ts 实现它提供低层 JSON/文本文件 I/O原子写入语义先mkdirSync保证目录存在再writeFileSync。数据统一存放在app.getPath(userData)/knowledge-base-data/下knowledge-base-data/ documents-meta.json # 文档元数据数组 content/ doc-id.txt # 每篇文档提取的文本内容 chunks/ doc-id.json # 每篇文档的分块数组 index/ index-meta.json # 文档 ID 到分块 ID 的映射 qa-history.json # QA 交互日志持久化恢复的机制是App.tsx在挂载时通过useEffect调用refreshDocuments()DocumentService启动时读取documents-meta.jsonPersistenceService.readJson在文件不存在时返回 null从而在重启后完整恢复文档列表。会话交接文档剖析session-handoff.md 的结构session-handoff.md 是「仓库即系统事实源」的直接体现其结构包括Last Session最后会话时间戳如 2026-03-30What Was Accomplished已完成内容分点列出导入、详情、持久化三项各自的实现位置What Remains遗留事项Project 02 无遗留feature_list.json 中 7 项全部为passDecisions Made关键决策及其理由如新增GET_DOCUMENT_CONTENT通道、删除时同时移除内容文件与原件、导入面板以替换而非模态框方式出现Files Modified修改过的文件清单从src/shared/types.ts到docs/PRODUCT.md共 15 项Blockers阻塞项NoneNext Steps下一步进入 Project 03添加索引、元数据提取与 grounded QA。功能验收标准Definition of Donesolution 的 AGENTS.md 定义了「完成」的五条标准TypeScript 编译无错误npm run check应用能启动且窗口可见功能以pass状态和证据出现在feature_list.json代码遵守 Electron 分层边界主进程拥有窗口生命周期与 IPC 注册、preload 是主进程与渲染层之间唯一桥梁、渲染层仅通过window.knowledgeBaseAPI 通信且绝不导入 Node.js 模块、服务层是主进程中的纯 TypeScript 业务逻辑并构造注入PersistenceService变更反映到docs/ARCHITECTURE.md与/或docs/PRODUCT.md。feature_list.json中每条功能都带有status、evidence实现证据描述与testedAt时间戳例如document-import的证据写明「ImportPanel 触发window.knowledgeBase.documents.import(filePath)成功后 App.tsx 刷新文档列表Import 按钮切换导入视图」。关键工程约定TypeScript strict 模式不允许无注释的any仅具名导出named exportsIPC 通道在src/shared/types.ts中定义一次作为唯一事实源IPC_CHANNELS常量见 types.ts新增 IPC 通道遵循namespace:action模式如documents:get-content。相关课程导航Leçon 03. 为什么仓库必须成为系统事实源Leçon 04. 为什么单一巨型指令文件会失败这两讲为本项目提供了理论支撑Leçon 03 论证仓库文档化的必要性Leçon 04 论证将指令分散到多个文件而非堆在一个巨型文件中的合理性——Project 02 的AGENTS.md、ARCHITECTURE.md、PRODUCT.md、feature_list.json与session-handoff.md正是这一理念的可执行落地。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Project 02 实战用 Agent 可读工作区与交接文件让 Agent 跨会话无缝续作learn-harness-engineeringProject 02 实战用 Agent 可读工作区与交接文件让 Agent 跨会话无缝续作learn harness engineering 导读 本RemoveWindowsAI 一键清除 CopilotRemoveWindowsAI 一键清除 Copilot RemoveWindowsAI 能把 Windows 11 里的 Copilot 、 Recall 等Learn Harness Engineering 会话交接指南用 session-handoff.md 实现 Agent 多会话无缝续接Learn Harness Engineering 会话交接指南用 session handoff.md 实现 Agent 多会话无缝续接 本文围绕 lear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考