Learn Harness Engineering 实战第 02 讲：构建 Agent 可读工作区，让新会话无缝续跑

【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文对应仓库中《Project 02: Make the Project Readable and Pick Up Where You Left Off》的完整实战讲解原文位于 docs/ru/projects/project-02-agent-readable-workspace/index.md并有 中文版 与 英文版 可对照。本讲的核心问题是当一次任务被拆成两段会话Session执行时第二个会话如何不依赖口头交接、仅凭仓库内已提交的文件就能理解项目结构、知道当前进度并继续干活答案是把仓库本身改造成「Agent 可读的工作区」——通过ARCHITECTURE.md、PRODUCT.md、session-handoff.md、feature_list.json等持久化状态文件让仓库成为唯一的交接媒介。读完本文你将掌握 Agent 可读工作区的目录设计与文档分层约定、跨会话状态交接文件的写法以及文档导入、详情查看、本地持久化三块功能的 Electron 源码级实现路径。一、项目要做什么把「读得懂」变成一种产品特性1.1 两次运行、对照实验原文档的核心实验设计非常简洁同一份任务用仓库中已提交的两个目录各跑一遍并对比第二段会话的表现。第一次运行使用信息更薄的starter/工作区其中没有session-handoff.md文档也不完整第二次运行使用solution/形态的工作区其中包含更完整的ARCHITECTURE.md、PRODUCT.md和session-handoff.md。对比的观测指标只有一个第二段会话需要重新发现多少上下文How much rediscovery a second agent session does。如果第二个会话能仅凭仓库状态直接续跑、无需口头补充就说明工作区是「可读的」反之如果它要反复翻代码、猜进度、重新推断决策就说明交接机制失效。1.2 产品功能与 harness 机制原文档明确区分了两个层面层面内容产品功能Product features文档导入document import、文档详情与完整内容加载full document detail/content loading、重启后持久化persistence across restartharness 机制Harness feature可交接读取的工作区handoff-readable workspace 持久化状态文件persistent state files也就是说这个项目表面上是一个 Electron 知识库应用但它的真正教学目标是验证 harness 机制让仓库本身携带足够的结构信息与进度信息使任意一个全新 Agent 会话都能在启动阶段迅速「读懂」项目。二、实验环境与工具链原文档列出的工具非常克制全部来自仓库现有技术栈Claude Code 或 Codex承担两段会话的 Agent 执行体Git负责把工作区目录starter / solution作为独立切片提交并作为会话间状态传递的载体Node.js Electron承载应用本体仓库中的实际工程为 Vite React 18 TypeScript 的 Electron 桌面应用见 projects/project-02/solution/package.json。没有引入任何外部服务整个实验可以完全离线复现。三、仓库目录对照starter 与 solution 的差异即答案原文档给出一张对照表是理解本讲的关键。结合仓库实际内容展开如下目录里面有什么要对比什么starter/Project 01 的代码基础上文档导入、详情页、持久化尚未完成文档存在但刻意更薄且没有session-handoff.md第二段 Agent 会话要重新打开/重新发现多少上下文solution/同一产品切片已全部完成交接文档放在 solution 根目录并带有 feature_list.json 与 session-handoff.md全新会话能否只凭仓库状态继续工作、无需口头上下文对照仓库目录可以看到solution 的关键差异集中在几个「状态承载文件」上docs/ARCHITECTURE.md讲清楚 Electron 四层架构、导入流程、内容读取流程与数据存储布局docs/PRODUCT.md定义产品需求与用户可见行为AGENTS.md给 Agent 的启动规则、分层边界与完成定义feature_list.json7 个功能特性及其状态pass / failsession-handoff.md上一会话的进度、决策、修改文件与下一步计划。四、Agent 可读工作区的启动协议AGENTS.md要让「任何新会话都能读懂仓库」光有文件还不够必须有一个固定的读取顺序。solution 中的 AGENTS.md 定义了完整的 Startup Rules先完整读取本文件——它定义项目边界与约定读取docs/ARCHITECTURE.md——理解 Electron 层结构与导入流程读取docs/PRODUCT.md——理解功能需求运行npm install npm run check——验证工程能否干净构建读取feature_list.json——查看所有功能的当前状态。这套顺序本身就是「可读性」的落地形式Agent 不需要靠猜按序读五个文件就能在写任何代码之前建立完整心智模型。文档目录也被刻意组织成两级、职责单一的结构docs/ ARCHITECTURE.md -- Electron 分层、数据流、导入流水线 PRODUCT.md -- 功能需求与用户可见行为AGENTS.md 还约定新增功能前先更新对应文档再写代码When adding new features, update the relevant doc before writing code这是为了让后续会话能通过文档 diff 理解会话间发生了什么变化。五、跨会话交接的核心session-handoff.md 的写法projects/project-02/solution/session-handoff.md 是本讲最值得逐字研究的文件。它的结构可以提炼为通用模板区块内容解决什么问题## Last Session上一会话的时间戳让新会话知道交接的时效性### What Was Accomplished完成事项列表如 Document Import、Document Detail with Content、Basic Persistence避免重复劳动直接续跑### What Remains剩余事项本例为 No remaining features... All 7 features are at status pass明确边界防止 Agent 过度扩张范围### Decisions Made关键决策及理由如新增GET_DOCUMENT_CONTENTIPC 通道、删除时同时清理内容文件与原副本、导入面板采用替换式而非模态框保留隐性知识防止新会话推翻旧决策### Files Modified逐文件修改清单覆盖src/shared/types.ts、src/main/ipc-handlers.ts、src/preload/preload.ts、src/renderer/App.tsx、src/services/document-service.ts等让新会话能精确、定向地复查改动### Blockers阻塞项本例为 None暴露风险### Next Steps下一步进入 Project 03增加索引、元数据抽取与 grounded QA为下一个会话提供明确的起点AGENTS.md 中对应地规定了交接纪律恢复工作时先读session-handoff.md结束会话时更新它写入已完成事项、剩余事项、阻塞或决策、修改过的文件。这套「写入-读取」闭环就是持久化状态文件的本质——会话的记忆以文件形式沉淀在仓库里而不是停留在任何人的脑中或终端滚动条里。六、进度状态的机器可读形态feature_list.jsonprojects/project-02/solution/feature_list.json 把进度从散文形式升级为结构化数据。每个特性包含五个字段字段含义示例值id稳定标识document-importname特性名Document Importdescription验收描述通过 ImportPanel 文件选择器导入 .txt/.md文档出现在列表status状态pass另有 fail 等evidence实现证据具体到 IPC 调用链与组件行为testedAt验证时间2026-03-30T11:00:00Z该文件记录了 7 个特性全部为passwindow-launch、document-list、question-panel、data-directory来自 Project 01 沿用、document-import、document-detail、basic-persistence。值得注意每个特性的 evidence 都精确到代码路径例如document-detail的 evidence 写明了window.knowledgeBase.documents.getContent(id)、pre-wrap 容器展示、IPC_CHANNELS.GET_DOCUMENT_CONTENT已注册。这意味着feature_list.json既是进度表也是新会话的「待核验清单」。七、源码级印证文档导入、内容读取与持久化原文档明确这是 Project 01 基础上的延续产品特性是三件事导入、详情内容、持久化。以下从 solution 源码逐一印证。7.1 导入流程的完整 IPC 数据通路ARCHITECTURE.md 给出了 11 步导入流程从用户点击到列表刷新结合源码关键路径是ImportPanel触发onImport(file.path)App.tsx 调用window.knowledgeBase.documents.import(filePath)preload.ts 通过contextBridge.exposeInMainWorld(knowledgeBase, api)暴露类型化 API内部执行ipcRenderer.invoke(documents:import, filePath)ipc-handlers.ts 中ipcMain.handle(IPC_CHANNELS.IMPORT_DOCUMENT, ...)委托给DocumentService.importDocument(filePath)document-service.ts 依次完成校验文件存在 → 读取内容与 stat → 生成Document元数据uuidv4()生成 id、filename去掉扩展名作为 title、记录size与importedAt、状态置为imported→ 把原文件复制进数据目录 → 把抽取的文本写入content/doc-id.txt→ 追加到documents-meta.json结果沿 IPC 返回后App.tsx调用refreshDocuments()刷新列表。这条链路演示了 Electron 的标准边界纪律渲染进程不碰 Node API主进程独占文件系统。7.2 内容读取为什么要单独开一个 IPC 通道一个值得展开的设计决策来自 session-handoff 的 Decisions Made新增GET_DOCUMENT_CONTENTdocuments:get-content通道而不是把正文塞进GET_DOCUMENT一起返回。理由是保持列表视图的 payload 足够小——列表只需要元数据正文按需懒加载。对应源码通道在 types.ts 的IPC_CHANNELS中集中定义遵循namespace:action命名如documents:get-content由 ipc-handlers.ts 注册DocumentService.getDocumentContent(id)通过PersistenceService.readText(content/id.txt)读取最终在DocumentDetail的 pre-wrap 容器中展示。7.3 持久化数据目录结构与原子写入持久化由 persistence-service.ts 承担构造时即用fs.mkdirSync(..., { recursive: true })保证目录存在。ARCHITECTURE.md 给出完整存储布局knowledge-base-data/ documents-meta.json # 文档元数据数组 content/ doc-id.txt # 每个文档的抽取文本 chunks/ doc-id.json # 每个文档的分块数组 index/ index-meta.json # 文档 ID 到分块 ID 的映射 qa-history.json # QA 交互日志基础目录来自 Electron 的app.getPath(userData)。要点有两处JSON 统一走writeJson原子写先mkdirSync再writeFileSync避免半写状态文档删除是级联清理deleteDocument(id)同时删除 documents 目录中的原始副本和content/id.txt内容文件再重写documents-meta.json见 document-service.ts。重启恢复则靠App.tsx挂载时的useEffect调用refreshDocuments()配合DocumentService.listDocuments()读取documents-meta.json——这就是「文档在重启后依然存在」的实现原理。八、产品约束与验收标准PRODUCT.md 明确了可验证的产品边界约束单个文件最大 10 MB仅支持.txt与.md本版本 QA 为 mock 模式无 LLM 集成全部数据本地化、无网络请求。状态栏实时显示索引状态idle / indexing / ready / error、文档数与最近活动时间。完成定义Definition of Done出自 AGENTS.mdTypeScript 编译无错误npm run check→ 应用可启动且窗口可见 → 特性在feature_list.json中标记pass并附证据 → 遵守 Electron 分层边界 → 同步更新 ARCHITECTURE/PRODUCT 文档。九、如何复现与验证仓库只读所有操作均为查看、安装与运行阅读 projects/project-02/README.md 了解项目说明进入 projects/project-02/starter 运行npm install npm run check随后以两段会话跑通「导入文档 → 查看详情 → 重启后仍在」记录第二段会话需要重新发现多少上下文进入 projects/project-02/solution按 AGENTS.md 的启动协议读五个文件后仅凭仓库状态尝试直接续跑验证交接有效性用feature_list.json的 7 项特性逐一核对验收证据。十、关联学习路径本讲不是孤立的它在课程脉络中的位置是承接 Lecture 03「让仓库成为唯一事实来源」 与 Lecture 04「把指令拆分成多个文件」 的理念并为后续 Project 03多会话连续性、Project 04增量索引提供交接基座。session-handoff 与状态文件的完整模板体系可参考仓库 skills/harness-creator/templates/ 目录。一句话总结Project 02 用「可读工作区 持久化状态文件」把 Agent 会话的记忆外部化到仓库里让第二次运行乃至任意后续会话都能从文件而非对话中恢复上下文——这是所有多会话 Agent 工程的地基之一。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 项目 02构建 Agent 可读工作区让新会话从上次断点无缝续作learn harness engineering 项目 02构建 Agent 可读工作区让新会话从上次断点无缝续作 导读 本指南基于 learn harnProject 02 实战用 Agent 可读工作区与交接文件让 Agent 跨会话无缝续作learn-harness-engineeringProject 02 实战用 Agent 可读工作区与交接文件让 Agent 跨会话无缝续作learn harness engineering 导读 本构建 Agent 可读工作区以 learn-harness-engineering Project 02 为例实现多会话无缝交接构建 Agent 可读工作区以 learn harness engineering Project 02 为例实现多会话无缝交接 本指南围绕 learn ha上一篇终极指南如何使用Capybara-WebKit进行无头Web自动化测试下一篇推荐一款优雅的滚动特效库jQuery Smooth Scroll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考