# Nomi Harness 需求真相源

> 这是 Nomi 自有 agent harness(治理内核)的**需求真相源**——后续所有 harness 设计以此为依据。
> 方法:**自下而上**——先从真实用户使用过程提炼需求点,再由需求反推 harness 机制(不是拿论文六组件去套)。
> 来源:4 个 persona(独立自媒体 / 漫剧作者 / 专业广告团队 / 非技术小白)模拟评审 + 用户拍板。
> 背景理论:论文《LLM 智能体测试框架综述》H=(E,T,C,S,L,V);构建思路参考 Claude Agent SDK,但实现 model-agnostic(P4,不绑 Claude)。

---

## 1. 产品灵魂:可控的透明

别人的 AI 是"会聊天的黑盒模型"。**Nomi 的 AI 是透明的创作伙伴**——它的五个维度全部「看得见、够得着、能纠正」,但默认不打扰。

| 用户能看见 AI… | 来自需求簇 |
|---|---|
| 在**做什么**(进度 / 错误) | B |
| **要做什么**、能改、不背着我乱来 | A |
| **记得什么**、基于什么在判断 | E |
| 花了**多少**额度 | C |
| 能不能**退回** | D |

**记忆是 AI 身上最后一块黑箱**,Nomi 要把它也照亮(用户拍板:记忆要悄悄记、悄悄用,但**可见可纠正**)。

> 贯穿原则 **渐进式披露**:默认极简(一句人话 + 进度条),想看 / 想改才下钻。**不叫"控制台"**(对小白是技术噪音),叫"创作进度 / AI 在做什么"。透明 ≠ 啰嗦——给"快速通览 + 下钻到细节"两档。

这就是"让用户看到这套 harness"的真正含义:把治理层产品化成**可控的透明**。

---

## 2. 需求地图(按创作流程的 8 个时刻)

**粗体 = 全员共振(最高优先信号)。**

### 🗣️ 时刻1:我说需求 → AI 理解
- N1 我说一句模糊的话,它得懂我的行业 / 风格("带货风"该啥样) — A·D
- N2 别让我做选择题、填技术参数,你自己定 — A·D

### ⏳ 时刻2:AI 干活 → 我等待
- N3 **我要知道它在动、没死、做到哪了**(轻量进度) — 全员
- N4 用人话告诉我在干嘛,别刷技术黑话 — A·C·D
- N5 慢可以,但慢完得对(别给我一堆驴唇不对马嘴) — A

### 📋 时刻3:AI 给计划 → 我审 / 确认 ⭐全员命门
- N6 **落地前让我看到完整计划**(建哪些、用什么模型、连了什么) — 全员
- N7 **计划我能逐项改,改了它记住**(是合同不是预览图) — 全员
- N8 但默认能一键全确认,别逼我逐个审 — A·C
- N9 **花钱前告诉我大概多少**(生成前预估;C 要镜头级,D 要一句话) — 全员

### ⚙️ 时刻4:AI 落地 → 执行 ⭐全员信任地基
- N10 **它只动我让它动的,绝不背着我改 / 删** — 全员
- N11 我定好的东西(角色卡)能锁住,AI 碰都不许碰 — B
- N12 我批的和它实际跑的要严丝合缝一致(可对账) — C

### ❌ 时刻5:出错了
- N13 **告诉我怎么办,不是甩我报错代码**(重点"咋办") — 全员
- N14 定位到哪个镜头 / 哪步、为什么失败 — C·B

### ↩️ 时刻6:我想反悔
- N15 **能一键撤销 / 退回上一步**("敢乱试全靠能退回") — A·D
- N16 能再来一版 / 换个风格重拆对比 — A

### 💾 时刻7:跨会话 / 长期
- N17 关了再打开能接着上次 — 全员(底线)
- N18 **它记得我这项目的设定**(风格 / 角色 / 品牌调性),不用每次交代 — 全员
- N19 记忆悄悄记 + 悄悄用,**但能看到记了什么、能删改记错的一条**,不强制管理 — D + 用户拍板

### 🎬 时刻8:专业进阶(少数但强,商业刚需)
- N20 可复现:调出当时完整配方,同参数重出同结果 — C
- N21 可审计导出:一份"这片怎么做的"清单 — C
- N22 改一处问我要不要同步全片 — B
- N23 生成前一致性自检(所有 A 镜头参考图是否一致) — B

### 🧭 贯穿元需求
- M1 **控制权在手边但不挡路**:默认自动,想干预随时够得着
- M2 **渐进式披露**:默认极简,想看才下钻(别摊一脸)
- M3 **快**:每条省 10 分钟 vs 费 10 分钟是两种人生

---

## 3. 需求簇 → harness 机制(由需求反推)

让需求簇自己长出 harness 结构(不是拿组件套)。每个机制**必须连着一个用户能感知的功能**才有意义。

| 簇 | 需求点 | 逼出的 harness 机制 | 对应组件 | 用户看到什么 |
|---|---|---|---|---|
| **A** | N6·7·8·10·11·12 | **「计划—批准—执行」三态事务**:写操作先汇成可见、可逐项改、可锁的计划;批准后严格执行不偏离;结果可对账 | **L** + 计划中间层 | 计划清单卡(看全·逐项改·锁·确认) |
| **B** | N3·4·5·13·14 | **AI 行为的人话翻译层**:把执行事件 / 错误翻译成"正在拆第3个镜头""这张图没出来点这重试" | **V** + 翻译产品层 | 人话进度条 + 人话错误 |
| **C** | N9·20·21·12 | **每次行为的结构化记录**:记下每步用什么模型 / 参数 / 花多少 / seed / 结果。一份记录撑起成本预估 + 复现 + 审计 + 对账 | **V**(结构化轨迹,地基) | 成本预估 / 配方导出 / 批vs跑对账 |
| **D** | N15·16 | **AI 写操作是可回滚事务**:每次铺节点 = 一个快照点,撤销 = 回上一个干净态 | **E**(状态快照 / 回滚,§6.2.8) | 撤销 / 退回上一步 / 重来一版 |
| **E** | N1·18·19 | **项目级创作记忆**(Nomi 版 CLAUDE.md):自动提炼 + 悄悄注入 + 可见可纠正 | **C** + **S** | "AI 记得这些"可查可改的项目记忆卡 |
| **F** | N2 | ✅ 已做:模型档案 + agent 自己选模型配参数 | **T** | (bug① 已落) |

**重要**:V 轨迹(簇 C)是被需求逼出的**地基**,价值在它撑起的 4 个用户功能,不是轨迹本身——只做底层不做"对账 / 成本 / 复现"功能,用户感知不到。

---

## 4. 数据驱动优先级

需求强度(谁要 + 多痛)定的,不是我拍脑袋:

```
最痛  = 簇A(计划事务) + 簇D(撤销)        → L + E,全员命门 / 安全地基
其次  = 簇B(人话翻译) + 簇C(结构化记录)   → V,价值在产品层
再次  = 簇E(记忆)                        → C/S,要悄悄 + 可见
已做  = 簇F(选模型配参数)                 → T ✅
```

> 注:这修正了早期蓝图把 V 轨迹排第一的判断——真实用户没人要"轨迹",要的是 L(主权)和 V 产品化后的功能。

---

## 5. 裁剪:不做什么(及为什么)

Nomi 是**本地单用户创作工具 + 短任务 agent**,不照搬论文的多租户六组件做满:

| 不做 | 为什么 |
|---|---|
| L 的配额 / 多租户审计 | 单用户,无多租户;成本"预估 + 可见"够,不需配额强制 |
| C 的摘要压缩 / 来源标记 | 短任务(拆镜头很少超 24k);本地单用户无外部注入威胁面 |
| S 的远端 session store | 本地单机,文件落盘够,不需 S3/Redis |
| agent 会话 resume(N17 的对话部分) | 项目状态已持久化;persona B 明说"对话断了能忍",优先级低 |

---

## 6. 搭建路线

| 期 | 簇 | 做什么 | 衔接 |
|---|---|---|---|
| **一期·主权** | A + D | 计划—批准—执行事务(看全·逐项改·锁)+ 撤销 / 回滚 | 承接 bug① 的 `AgentPlanCard` + `applyCanvasToolCall`,衔接最顺 |
| **二期·信任** | B + C | 人话进度(治 bug②)+ 人话错误 + 成本预估 + 底层结构化轨迹 | 轨迹同时治"接入必漂" |
| **三期·记忆** | E | 项目记忆卡(悄悄记 + 可见可纠) | |
| 贯穿 | — | harness 内核统一(合并 chat + onboarding 两套,P1)+ repair 去重 + 渐进式披露形态 | |

**先从一期 · 簇 A(计划—批准—执行事务)开搭。**

---

## 附:现状锚点(开搭时的代码起点)
- 计划卡雏形:`src/workbench/generationCanvas/components/AgentPlanCard.tsx`(现在"确认即执行",缺逐项改 / 锁 / 对账)
- 写操作单一真相源:`src/workbench/generationCanvas/agent/applyCanvasToolCall.ts`
- 确认门:`electron/ai/agentChatV2.ts` 的 `awaitToolConfirmation` + `agentChatV2Ipc.ts`
- 散落的 harness 帮手:`electron/ai/agentChatHarness.ts`(待统一成内核)
- 已有结构化轨迹参考(可提炼成 V):`electron/ai/onboarding/reporter.ts`
