zhaoshang_client_ui/harness

harness/ — agent 长时开发的工作环境

这套东西解决的问题：多轮会话开发时，状态不要存在于聊天记录或人的记忆里， 而是存在于仓库文件中。

参考：Learn Harness Engineering （核心公式 Agent = Model + Harness；设计原则：短入口，深链接）

结构

harness/
├── README.md            本文件：结构导航
├── progress.md          ★ 进度日志：当前已验证状态 + 每轮会话记录
├── feature_list.json    ★ 功能清单：状态 / 验证步骤 / 证据
├── init.sh              安装依赖 + 基础验证 + 打印启动命令
│
├── tools/               脚本都写这里（验证脚本、调试脚本、结构校验）
│   ├── README.md
│   └── validate-harness.mjs  ★ 校验 harness 结构本身（见下「机械约束」）
│
├── docs/                项目文档
│   ├── architecture.md    架构、目录、核心系统、关键约束
│   ├── quality.md         质量评分：各领域现状与缺口
│   ├── exec-plans/        ★ 执行计划与技术债
│   │   ├── README.md          计划管理方式（含「计划只能放这里」的硬规则）
│   │   ├── active/            进行中的计划
│   │   ├── completed/         已完成的计划（决策追溯）
│   │   └── tech-debt-tracker.md  技术债清单
│   └── reference/         接口契约与参考资料
│       ├── README.md        索引：先读哪份
│       ├── api-chat.md            现行接口契约
│       ├── api-chat-fields-zh.md  字段中英对照
│       ├── DMS_*.md               DMS 契约与栏目现状（含实测结论）
│       └── legacy/API.md          交接时的代码快照（非规格，勿照抄）
│
└── sops/                标准流程
    ├── session-start.md   开工流程
    ├── session-end.md     收尾清单
    ├── handoff.md         会话交接
    ├── verification.md    验证流程（含本项目踩过的坑）
    └── evaluator-rubric.md 六维度评审表

★ = 每轮都会读写；其余按需查。

机械约束（不是口头约定）

文档写「计划要放 exec-plans/」「同一时间只能一个 in_progress」， 光写着没用 —— 违反的时候得有东西报错：

node harness/tools/validate-harness.mjs    # 退出码非 0 = 有违规

它会检查：必备文件是否齐、有没有游离的计划文件、feature_list.json 是否有 假 passing / 重复 id / 多个 in_progress、progress.md 的会话编号是否重复。 收尾时跑一次（见 sops/session-end.md）。

怎么用

开工：按 sops/session-start.md 走 —— 读 progress.md 与 feature_list.json → 看提交 → 跑 init.sh → 只选一个功能做。

收尾：按 sops/session-end.md 过一遍清单， 当场更新 progress.md 与 feature_list.json，不要攒到会话结束。

验证：按 sops/verification.md —— 接口相关改动必须对真实后端端到端验证，脚本写到 tools/。

三条规则

1. 同一时间只做一个功能（feature_list.json 里只有一个 in_progress）
2. 没有可运行证据不得声称完成（构建通过只是底线，不是充分条件）
3. 每次改动完成就立刻更新记录，不要攒 —— 攒到最后必然漏记、且已写下的描述会过期

深链接在哪

根 CLAUDE.md 只保留很短的入口（开工步骤 + 规则 + 指向本目录）。 架构细节、接口契约、流程细节都在 harness/ 里 —— 这是刻意的： 入口短才有人读，细节深才不会污染入口。

与仓库其他部分的关系

位置	内容	入库
README.md	改动记录（按日期），给团队看	✅ 入库
CLAUDE.md / agents.md	简短入口 + 工作规则 / 开发原则	✅ 入库（2026-09-17 起）
harness/（本目录）	状态、流程、文档、脚本	✅ 入库（2026-09-17 起）
.env.*.local、.claude/settings.local.json	带凭据的本机配置	❌ 不入库
harness/tools/_*.mjs	esbuild 打包产物	❌ 不入库（会与源码漂移）

⚠️ 不要在三处重复记同一件事。 变更明细记在 README.md； harness/ 里只记 README 没有的东西 —— 哪些验证过、哪些还挂着、下一步做什么。