harness-step3-session-management

Harness Step 3: 建立跨 Session 状态管理

目标

创建三个文件，让 agent 在任何新 session 开始时能在 30 秒内恢复工作状态：

• init.sh：环境初始化脚本，验证项目可以正常启动
• tasks.json：当前任务清单，agent 的工作指令来源
• progress.md：人类可读的进度摘要，记录每次 session 的关键信息

核心原则：状态靠文件传递，不靠 agent 的记忆。git log 是主记录，这三个文件是辅助。

---

执行步骤

Step 1：扫描项目启动方式

在写 init.sh 之前，先确认项目如何启动和测试：

# 读 package.json 的 scripts（Node.js 项目）
cat package.json 2>/dev/null | grep -A 20 '"scripts"'

# 或读 Makefile（多语言项目）
cat Makefile 2>/dev/null | head -40

# 或读 pyproject.toml（Python 项目）
cat pyproject.toml 2>/dev/null | grep -A 20 '\[tool.poetry.scripts\]'

# 确认现有 AGENTS.md 里的启动命令
grep -A 5 '启动命令\|start\|dev\|run' AGENTS.md 2>/dev/null

收集：

• 开发服务器启动命令
• 测试命令
• 类型检查/lint 命令（如果有）
• 有没有需要先跑的初始化步骤（如数据库迁移）

---

Step 2：创建 init.sh

init.sh 的作用：每次 session 开始时运行，快速验证环境是否正常，不正常就立即修复再继续。

#!/bin/bash
# init.sh — 每次 session 开始时运行
# 验证开发环境处于可工作状态

set -e  # 任何步骤失败就停止

echo "=== 检查环境 ==="

# 1. 确认在正确目录
echo "工作目录: $(pwd)"

# 2. 安装依赖（如果 node_modules 不存在）
# [根据技术栈选择，以下是示例]
# Node.js:
if [ ! -d "node_modules" ]; then
  echo "安装依赖..."
  npm install
fi

# 3. 冒烟测试：验证项目能正常启动
# [根据项目实际情况写，目标是用最快的方式验证基本功能正常]
# 示例：跑一个最快的测试
# npm run test -- --testPathPattern=smoke 2>/dev/null || echo "警告：冒烟测试失败，请先修复"

echo "=== 环境检查完成，可以开始工作 ==="
echo "提示：运行 'git log --oneline -10' 查看最近工作历史"

写作要求：

• 根据扫描到的实际启动命令填写，不要留示例注释
• 冒烟测试要快（< 30秒），目的是快速发现环境问题，不是跑完整测试套件
• 如果项目有数据库，加一步检查数据库连接是否正常
• 写完后实际运行一遍，确认脚本无报错：bash init.sh

---

Step 3：创建 tasks.json

结构设计：

{
  "project": "[项目名]",
  "last_updated": "[今天日期，格式 YYYY-MM-DD]",
  "current_focus": "[当前最重要的一件事，一句话]",
  "tasks": [
    {
      "id": "[模块缩写]-[序号]",
      "title": "[任务标题]",
      "description": "[具体做什么，1-3句话]",
      "status": "pending | in_progress | done | blocked",
      "priority": "high | medium | low",
      "blocked_by": "[阻塞原因，仅 blocked 状态时填写]",
      "verify": "[如何验证这个任务完成了]",
      "requires_eval": false
    }
  ]
}

字段说明（每次新增任务时必须逐字段填写，不能省略）：

字段	是否必填	说明
id	必填	模块缩写 + 序号，如 auth-01、ui-03，简短可读
title	必填	任务标题，一句话
description	必填	具体做什么，1-3 句话
status	必填	初始值为 pending，由 agent 工作时更新
priority	必填	high / medium / low
blocked_by	仅 blocked 时填	阻塞原因
verify	必填	如何验证完成，必须是可执行的步骤（命令或操作）
requires_eval	必填	是否需要独立 Evaluator 评审，默认 false，见判断标准