docs/DESIGN.md

# 契约决策 AI 设计文档

## 版本规则

### v0.5.129 - Supabase KV 表权限收紧

修正 Supabase MVP 持久化 SQL 的权限策略，避免误用 publishable/anon key 暴露用户、会话、统计和项目记忆数据。

1. **只允许服务端密钥访问**：`app_kv` 表改为启用 Row Level Security，并撤销 `anon` 与 `authenticated` 对该表的直接权限。应用服务端继续通过 `SUPABASE_SERVICE_ROLE_KEY` 读写。

2. **明确禁止 publishable key**：文档中强调 `sb_publishable_...` / anon public key 只能用于前端公开场景，不能作为本项目的 `SUPABASE_SERVICE_ROLE_KEY`。

3. **不改业务逻辑**：本版本只收紧 Supabase 表权限说明，不修改注册、项目记忆、统计、开放参数抽取或公式计算。

涉及文件：`docs/database/supabase-kv.sql`、`docs/DESIGN.md`。

### v0.5.128 - Supabase MVP 持久化层

为解决 Hugging Face 免费 Space 本地 `data/` 不可靠的问题，新增 Supabase 作为服务端持久化层。目标是先保证内测用户、项目记忆和统计数据不随容器重启丢失。

1. **最小侵入 KV 方案**：新增 `SUPABASE_URL`、`SUPABASE_SERVICE_ROLE_KEY` 和 `SUPABASE_KV_TABLE`。配置后，服务端会把现有 `users.json`、`sessions.json`、`usage.json`、`analytics.json` 和 `projects/*.json` 同步到 Supabase `app_kv` 表。

2. **保持本地兜底与首次迁移**：未配置 Supabase 时继续使用本地 JSON 文件；配置 Supabase 时启动时从 Supabase 载入缓存，写入时同时写本地和 Supabase。如果 Supabase 表里没有对应 key，但本地已有历史 JSON，会在启动时把本地文件种到 Supabase，避免首次切换丢掉内测注册和项目数据。

3. **不改业务逻辑**：本版本只替换持久化底座，不改开放参数抽取、公式计算、候选排序、注册流程、项目记忆截断规则或前端布局。

4. **提供 SQL 文件**：新增 `docs/database/supabase-kv.sql`，用户在 Supabase SQL Editor 执行一次即可创建 MVP KV 表。

5. **健康检查可见**：`/api/health` 返回 `persistentStore.provider/configured/table/cachedRecords`，用于确认线上是否已经真正启用 Supabase，而不是仍在使用本地 JSON。

涉及文件：`server/index.ts`、`docs/database/supabase-kv.sql`、`docs/DEPLOY_HUGGINGFACE.md`、`docs/DESIGN.md`。

### v0.5.127 - 业务联系邮箱与持久记忆说明

在注册前法律同意门槛之后，补齐国际版法律文件中的业务联系邮箱，并明确项目记忆的持久化边界。

1. **业务联系邮箱统一**：国际版 Terms、Privacy、Refund/Subscription Policy 中的 support、privacy、legal、billing 联系邮箱统一为 `chendb8888@gmail.com`。

2. **上线检查同步**：`GLOBAL_MVP_LAUNCH_CHECKLIST.md` 标注当前 MVP 业务联系邮箱已确定，正式商用前仍需补齐法律主体名称和地址。

3. **持久记忆边界**：当前应用层已通过 `/api/projects` 将项目记忆写入 `data/projects/*.json`；本地环境和具备持久磁盘的部署环境可长期保存。Hugging Face 免费 Space 若未配置持久化存储或外部数据库，容器重启后仍可能丢失 `data/`，正式商用应迁移到持久存储。

涉及文件：`docs/legal/global-mvp/**`、`docs/DESIGN.md`。

### v0.5.126 - 注册前法律同意门槛

在 v0.5.125 法律文件上线后，注册入口增加显式同意机制，避免用户注册时看不到服务协议和免责声明。

1. **注册表单增加勾选项**：注册模式下展示“我已阅读并同意服务协议、隐私政策和 AI 免责声明”，中文界面链接到中文公开版法律文件，英文界面链接到 `global-mvp` 国际版法律文件。

2. **前端拦截**：未勾选时注册按钮不可用，并显示明确提示；登录模式不要求重新勾选。

3. **后端强校验**：`/api/auth/register` 必须收到 `legalAccepted: true` 才创建账号，防止绕过前端直接注册。

4. **记录同意版本**：用户记录保存 `legalAcceptedAt` 和 `legalAcceptedVersion`，方便后续内测统计和条款版本追溯。

涉及文件：`src/App.tsx`、`src/App.css`、`server/index.ts`、`docs/DESIGN.md`。

### v0.5.125 - 全球 MVP 法律文件升级

按“欧美、新加坡、日本等常见 SaaS 市场的最小可上线合规底线”整理法律文件，但仍定位为律师复核稿，不替代正式法律意见。

1. **国际版法律包升级**：更新 `docs/legal/global-mvp/` 下的 Terms、Privacy、AI Disclaimer、Document Upload Notice、Refund/Subscription Policy、Launch Checklist，并新增中文律师复核重点清单。

2. **中文公开版同步升级**：更新 `docs/legal/TERMS_OF_SERVICE.md`、`PRIVACY_POLICY.md`、`AI_DISCLAIMER.md`、`CONTRACT_UPLOAD_DATA_NOTICE.md`、`LAUNCH_COMPLIANCE_CHECKLIST.md` 和法律目录说明，方便应用页脚直接指向中文文件。

3. **覆盖重点**：明确 AI 辅助而非专业意见、合同上传和 OCR 风险、GDPR/UK GDPR、美国/加州隐私、新加坡 PDPA、日本 APPI 风格条款、跨境处理、支付订阅退款、用户上传责任、高影响事项人工复核和律师复核要求。

4. **不改业务逻辑**：本版本只整理法律和上线合规文件，不改开放参数抽取、公式计算、候选排序、前端布局或部署配置。

涉及文件：`docs/legal/**`、`docs/DESIGN.md`。

### v0.5.124 - 单候选恢复效用测算展示

修复单候选场景中，右侧方格决策卡只展示“当前可谈成 / 补强后 / 兑现”，没有展示我方效用、对方效用、共同剩余等核心契约效用指标的问题。

1. **单候选仍做完整效用计算**：只有一个候选时不进入横向候选排序，但仍使用当前安排的开放参数进入后台公式，计算匹配均衡、我方效用、对方效用、共同剩余、双赢概率、错配风险、当前可谈成率、补强后可谈成率和兑现概率。

2. **展示层补齐，不改公式**：本次只把已经存在的 `analysis.bilateralMatching` 与 `analysis.distribution` 显示到单候选决策卡，不新增固定权重、不新增工程评分、不改变开放参数抽取和公式计算。

3. **对话依据同步补充**：单候选的“对话输出依据”同步说明匹配均衡、我方效用、对方效用和共同剩余，避免用户误以为单候选没有做效用验算。

涉及文件：`src/App.tsx`、`docs/DESIGN.md`。

### v0.5.123 - 需求匹配缺项用候选公式值展示

修复多候选场景中，结构化摘要只返回 A 的逐项需求匹配，B/C 已经进入候选公式计算却在右侧卡片显示“需求匹配暂未形成 / 未单独计分”的问题。

1. **公式计算不变**：候选排序仍直接使用候选专属开放参数进入 `analyzeContract` 后得到的公式分，不新增固定权重、不启用固定因子。

2. **展示兜底改为公式值**：当大模型摘要漏掉某候选的 `candidateScores` 时，前端用该候选公式中的 `matchingEquilibrium` 作为需求匹配展示值，避免用户误以为该候选没有参与计算。

3. **明确解释来源**：如果没有逐项 pairs，需求匹配说明会提示“结构化摘要没有返回逐项需求匹配，当前用候选专属公式匹配值展示”，区分公式展示和逐项文字解释。

涉及文件：`src/App.tsx`、`docs/DESIGN.md`。

### v0.5.122 - 当前事实源候选边界隔离

修复多轮项目记忆或结构化摘要中残留旧候选时，当前只有 A/B 两个候选却在右侧决策卡和最终回复排序中出现 C 候选的问题。

1. **候选排序只读取当前事实源**：当前输入如果是完整候选集合，会从 `【当前完整情况｜替代此前候选事实】` 或 `【本次新增信息】` 中提取本轮事实，候选比较和 `candidateRanking` 不再直接扫描整个项目上下文。

2. **历史不产生本轮候选**：历史项目记忆仍可用于理解变化过程，但不能把旧 A/B/C 带入本轮候选列表。旧候选若没有在当前完整情况中重新出现，视为退出当前比较。

3. **决策卡与最终回复同源**：右侧方格决策卡、候选拆分、最终回复强约束排序均使用同一个当前事实源，避免“对话只有 A/B，卡片出现 C”或“卡片排序和最终答复候选数不同”的问题。

4. **不改变公式和权重原则**：本次只修候选边界数据源，不新增固定权重、不启用固定因子、不改变开放参数由大模型给出数字后再由后台公式计算的原则。

5. **事实性质保真**：开放参数抽取增加通用事实保真约束，保底费、授权费、报价、投资款、预付款、分成、股权、期权、工资、补偿、罚金等不得互相改写；授权、购买、合伙、雇佣、承包、代理等关系身份不得互相改写。

涉及文件：`src/App.tsx`、`docs/DESIGN.md`。

### v0.5.121 - 多候选开放参数分段抽取兜底

修复复杂多候选场景中，本地模型输出超长 JSON 时仍可能少逗号、数组断裂，导致“开放参数抽取失败，未继续执行固定因子计算”的问题。

1. **保留主抽取重试**：系统仍先尝试一次性抽取整体开放参数，并校验合法 JSON、数字字段完整、候选专属参数齐全。

2. **新增分候选抽取兜底**：如果整体 JSON 多次失败，且已经锁定 A/B/C/D 多个候选，则改为逐个候选短 JSON 抽取。每次只让模型抽取一个候选的专属开放参数，降低长 JSON 截断和漏逗号概率。

3. **仍不启用固定因子**：分候选兜底只改变结构化交付方式，不新增固定权重、不启用关键词打分、不使用固定基础因子补算。每个参数的 `value/confidence/weight/userWeight/otherWeight/riskWeight/refWeight` 仍必须由大模型给出。

4. **多候选计算保持分离**：A/B/C/D 的候选专属参数分别进入各自候选公式；共享约束和横向比较因素只作为共同背景，不替代候选专属验算。

涉及文件：`server/index.ts`、`docs/DESIGN.md`。

### v0.5.120 - 开放参数 JSON 重试与多候选比较参数保留

修复开放参数抽取因模型输出 JSON 截断、少逗号或数字字段缺失而直接中断的问题。用户要求失败后继续重试，且不能回退到固定因子补算。本版本保持“权重由大模型给出、后台公式计算”的原则，只增强结构化交付稳定性。

1. **开放参数抽取增加严格重试**：抽取结果必须是合法 JSON，并且每个开放参数都必须包含 `value/confidence/weight/userWeight/otherWeight/riskWeight/refWeight`。JSON 解析失败、数组为空或数字字段缺失时，会带着失败原因要求模型重发；不启用固定因子兜底。

2. **提高抽取 token 上限**：复杂多候选场景下，A/B/C/D 的候选专属变量容易被截断。本版本提高开放参数抽取输出长度，并要求模型在内容过多时保留最高影响变量，保证 JSON 完整优先。

3. **保留跨候选比较变量**：价格、期限、控制权、履约证据等横向对比变量可能同时提到 A/B/C/D。前端候选验算不再丢弃这类变量，而是把共享变量、跨候选比较变量和候选专属变量一起代入对应候选的公式计算。

4. **仍不设置工程权重**：本修复只处理“模型结构化输出是否合法、候选参数是否被正确带入”，不新增隐藏权重、不新增关键词加减分、不新增固定基础因子补算。

涉及文件：`server/index.ts`、`src/App.tsx`、`docs/DESIGN.md`。

### v0.5.119 - 开放参数权重直入公式与隐藏工程权重清理

本版本修正 v0.5.118 中残留的“场景化工程权重、非线性推荐指数、关键冲突惩罚、候选关键词加减分”等二次判断层。用户明确要求：权重只能由大模型在开放参数抽取时给出，后台公式直接代入计算，不能再由前端或服务端自行设置隐藏权重。

1. **候选排序改为公式直出**：候选 `decisionScore` 直接取该候选专属开放参数进入 `analyzeContract` 后得到的公式分，不再组合 `totalSurplus/userUtility/fulfillment/current` 的工程权重。

2. **删除候选关键词加减分**：移除 `candidateAdjustment`，不再因为“正规、案例、交付、AI、权限、售前”等关键词在前端给候选成功率加减分。相关信息必须由大模型抽取成开放参数，并通过公式影响结果。

3. **删除关键冲突工程惩罚**：移除 `keyConflictCost` 与 `decisionPenalty` 传递链。底线、风险、控制权冲突只能通过开放参数的 `value/confidence/weight/userWeight/otherWeight/riskWeight/refWeight` 进入公式，不能另设一条扣分线。

4. **推荐分不再非线性校准**：前台显示的“公式得分”= 后台公式分 × 100，不再做 65/78/88 分段映射，避免显示分和后台原始分不一致。

5. **开放参数权重不设默认值**：`value`、`confidence`、`weight`、`userWeight`、`otherWeight`、`riskWeight`、`refWeight` 必须由大模型给出有效数字；缺失时直接返回模型抽取失败，不启用固定基础因子补算。

6. **最终回复必须服从公式得分第一**：服务端排序表改为“公式得分”约束。大模型可以解释风险和谈判条件，但当前建议必须以公式得分第一的候选为基础；若输出不一致，触发重试和系统校正。

涉及文件：`src/contractEngine.ts`、`src/App.tsx`、`server/index.ts`、`docs/DESIGN.md`。

### v0.5.118 - 大模型结论与后台得分多层对齐保护

修复大模型最终结论与后台候选综合排序表仍可能不一致的问题。v0.5.117 只做"前 1400 字是否提及 leader + 单次重试",漏检率高且无兜底。本版本建立多层对齐保护:

1. **冲突检测升级为结论对齐检测**(`replyMayConflictWithRanking`):从"前 1400 字是否提及 leader"改为"结尾 800 字是否提到 leader + 是否出现明确推荐非 leader 的表述"。旧逻辑下模型可以在前 1400 字提到 leader,然后在结论部分推荐别的候选,检测不到。新逻辑只看结尾结论段,并检测"建议/推荐/倾向于/应该选 + 非leader"的组合模式。

2. **重试失败后服务端强制兜底**:旧逻辑重试一次后直接返回,即使仍不一致也照常输出。新逻辑在 2 次重试仍冲突时,在回复末尾追加"系统校正"段,明确告知用户后台测算的综合第一是谁、上方结论未通过一致性校验,请以校正为准。保证用户永远能看到正确结论。

3. **收紧逃生口,底线推翻需在 decisionPenaltyReason 范围内**(新增 `overrideWithoutValidRedLine`):旧逻辑允许模型用"不可让底线"推翻排序,但模型可以编造新底线。新逻辑:合法推翻的前提是 leader 自身的 `decisionPenalty > 0`(公式已识别到关键冲突);如果 leader 没有关键冲突成本,模型却仍在结论里推翻 leader 并推荐非 leader,判定为编造,触发重试。

4. **评分权重场景化**(`inferWeightsFromContext`):旧逻辑全场景固定权重(totalSurplus 0.40 / userUtility 0.25 / needMatch 0.18 / fulfillment 0.10 / current 0.07),导致公式第一与模型场景直觉第一系统性错位。新逻辑根据 `decisionContext` 动态调整权重:求职场景 fulfillment 权重 ↑,资产买卖 current 权重 ↑,合伙 totalSurplus 权重 ↑,外包采购 fulfillment 权重 ↑。权重仍由后台确定性公式决定,不引入大模型主观判断。

5. **排序表增加非线性映射说明**:`formatCandidateRankingHint` 在候选排序表后追加分数说明,告知模型推荐指数经过非线性校准(65→78 对应原始分 0.5→0.6,78→88 对应 0.6→0.72),判断候选差距时以"后台原始综合值"为准,避免模型基于显示分误判差距。

6. **解耦 needMatch 与 decisionScore**:旧逻辑 `needMatch`(大模型判断的需求匹配分)进入 `decisionScore` 计算,再用排序约束大模型,形成循环依赖。新逻辑 `decisionScore` 只用后台确定性变量(totalSurplus/userUtility/fulfillment/current),`needMatch` 单独作为展示栏,不参与排序计算,打破循环。

7. **候选名称锁定到候选边界锁定结果**(`candidateMentionPattern`):旧逻辑只用 id 和 title 生成正则,模型在决策输出里用"第一家/A公司/那个报价低的"等指代时匹配失败。新逻辑:前端把候选 `sourceText`(前 200 字符)传入,服务端从 sourceText 提取金额、比例、期限等关键实体词加入匹配源;同时增加 id→序号映射(A→1/B→2/C→3/D→4),匹配"第一个/第一家"等常见指代;并从 title 提取连续中文专有名词片段。

8. **强约束格式化**:排序表强约束新增"最后一段必须以'当前建议:候选X'开头"的硬格式要求,让结论可被正则锁定;同时明确列出合法推翻 leader 的 4 个必要条件(底线已列出、说明理由、说明重新接受条件、不编造新底线)。

涉及文件:`server/index.ts`(冲突检测、兜底、底线检测、排序表提示词、候选匹配)、`src/App.tsx`(评分公式解耦、场景化权重、sourceText 传递)。

### v0.5.117 - 候选评分与最终结论同源

- 修复多候选场景中“决策卡综合评分第一”和“对话最终建议”可能不一致的问题。
- 所有候选继续进入同一套后台验算，不因 `需求匹配待验证` 被一票否决；`待验证` 只表示该候选缺少逐项需求匹配分，仍需结合共同剩余、我方效用、对方效用、当前可谈成、补强后可谈成和签下后兑现综合判断。
- 前端在生成完整回复时，会把当前候选综合排序表同步传给服务端，作为大模型最终答复的强约束。
- 最终回复必须尊重后台候选排序：如果综合效用和共同剩余更高的候选排第一，默认应围绕该候选给出结论和谈判策略。
- 若最终回复不选择最高分候选，必须明确说明哪个不可让底线被触发、为什么该底线足以推翻分数，以及需要谈到什么条件后才可以重新排序；如果第一轮输出与排序表明显不一致，服务端会要求模型重新输出。
- 关键冲突继续作为“谈判成本/补强条件”进入解释，而不是自动变成工程上的一票否决。

### v0.5.116 - 笑面登录态恢复与接口认证一致

- 修复线上出现“左侧显示账号已登录，但调用 AI 接口返回请先登录后使用”的问题。
- 普通用户认证改为统一入口：先识别 Cookie Session；若 Session 文件或 Cookie 状态不同步，再使用当前浏览器的 `X-Client-Id` 恢复最近登录/注册过的账号。
- 登录和注册时会把当前浏览器 `clientId` 写入用户记录，并同时记录到 `analytics.json`，用于内测阶段的登录态兜底恢复。
- `/api/auth/me`、项目同步、后台验算、完整决策输出、文档提取、合同审查、支付入口和 token 使用记录统一使用同一套普通用户识别逻辑。
- 该兜底仅用于普通用户功能接口，不影响管理员后台；管理员后台仍只使用独立的 `APP_ADMIN_*` Cookie 签名机制。

### v0.5.115 - 内测注册与功能使用统计持久化

- 注册账号继续写入服务端 `data/users.json`，作为内测注册人数的主数据来源；登录成功会更新 `lastLoginAt` 和 `loginCount`。
- 新增 `data/analytics.json` 事件流水，记录注册、登录、后台验算、完整用例处理、文档提取、PDF 提取、OCR 提取、合同审查等产品行为。
- 管理后台 `/admin` 新增内测核心指标：注册人数、今日注册、实际使用人数、今日使用人数、处理用例数、今日用例数、后台验算数、PDF 使用人数、PDF 处理次数、OCR 次数和合同审查次数。
- 用户列表新增单用户行为统计：处理用例、后台验算、PDF、OCR、合同审查次数，方便判断哪些账号真正使用过产品。
- 事件统计只记录功能类型、用户、文件类型、字符数、模型等运营元数据，不记录用户原始决策文本或合同正文，降低隐私暴露风险。
- 该版本仍使用轻量 JSON 文件持久化，方便内测阶段快速验证；正式商用可按相同事件结构迁移到 PostgreSQL、Supabase、ClickHouse 或其他数据库。

### v0.5.114 - 共赢契约排序与关键冲突成本

- 修正多候选排序中“单点需求命中”过度抬高候选的问题：综合决策分改为以 `共同剩余` 为主轴，再结合 `我方效用`、`需求匹配`、`签下后兑现概率` 和 `当前可谈成率`。
- 需求匹配不再等同于“某一个高权重需求被满足”，而是回到契约理论中的双方共赢：双方都得到自己真正需要的东西，且共同剩余更高，才说明安排更匹配。
- 如果某候选只满足用户的单点核心诉求，例如“AI 核心岗位/AI 核心项目”，但现金流、安全、控制权、兑现概率或对方收益结构明显不足，则不能直接推荐接受；只能作为“可谈判改善”的候选。
- 若谈判无法提高双方共同剩余、降低关键冲突成本或补齐兑现机制，系统应建议继续寻找更合适的替代候选，而不是因为单点亮点强行选择当前候选。
- 对大模型已经识别出的关键冲突，不做一票否决；改为计入“关键冲突谈判成本”。这表示该候选仍可进入谈判补强，但当前条件下不能靠单一亮点压过整体效用更高的候选。
- 修复求职/岗位场景中“售前和交付”被误当作“交付周期或上线速度”的问题：在岗位语境下，该信息进入“职责泛化会稀释核心岗位价值”的风险解释。
- 决策卡中补充显示关键冲突谈判成本，避免用户只看到综合分变化但不知道扣分依据。
- 区分 `后台原始综合值` 与 `推荐指数`：后台继续使用 0-1 效用指数做排序和验算，前台主卡显示校准后的 0-100 推荐指数，避免用户把 0.58 误读成 58 分。
- `需求匹配` 仍显示大模型逐项需求匹配结果；如果用户需求本身冲突，例如“AI 核心机会”和“一年内不失业”同时存在，匹配分低不是公式坏了，而是当前候选没有同时满足这些需求。推荐排序再用共同剩余和兑现概率兜底。

### v0.5.113 - 行业维度知识库文件化

- 将原先写在 `server/domainKnowledge.ts` 内的行业关键维度拆分为独立 JSON 文件，统一放在 `knowledge/domain-dimensions/`。
- 每个行业一个文件，例如 `software-ai-outsourcing.json`、`job-offer.json`、`real-estate-asset.json`；通用契约维度放在 `shared-contract.json`。
- 服务端请求时动态读取知识库文件，代码只负责检索和格式化，不再把行业维度硬编码在源码中。
- 这样用户可以直接修改、增加或删除行业维度文件，不需要改 TypeScript 代码。
- Docker 部署已同步复制 `knowledge` 目录，保证笑面/HuggingFace Space 运行时也能读取同一套知识库。

### v0.5.110 - 结构化摘要限长与截断修复

- 修复复杂多候选案例中，`currentInfoSummary` 因 JSON 过长被模型截断，导致后续面板无法解析完整 A/B/C/D 候选的问题。
- 新增摘要输出体积限制：每个候选、需求匹配、候选打分和建议补充维度都只保留最高影响信息，避免把完整长文塞进单个 JSON。
- 新增 JSON 断裂重试：若结构化摘要无法解析，会按已锁定候选边界要求模型重发极简完整 JSON；再失败才降级为最小候选边界摘要，保证页面不串位、不空白。
- 该改动只保护结构化交付稳定性，不改变全要素识别、开放维度判断、权重判断和后台公式计算逻辑。

### v0.5.109 - 大模型候选边界锁定与分层提取

- 修复复杂多候选场景中 A/B/C 串位、丢候选、单候选为空的问题。根因不是公式，而是结构化摘要层让大模型一次性完成“识别候选、提事实、判断需求、补维度”，导致候选边界不稳定。
- 新增第一步“候选边界锁定”：大模型先只识别整体背景与 A-D 候选原文片段，不做判断、不总结、不重排优劣；如果只有一个当前对象，也锁定为 A。
- 后续结构化摘要和开放参数抽取都必须服从候选锁定结果：每个候选的事实、金额、期限、控制权、风险和承诺只能来自自己的原文片段，不能把 A 的事实写进 B，也不能把 B/C 合并。
- 服务端在摘要返回前做一致性修正：若候选锁定结果存在，但摘要 JSON 漏掉该候选，会把候选原文片段回填到对应 A/B/C/D 分区，避免决策卡和对话输出建立在错误候选上。
- 该版本仍然依赖大模型做全要素理解、开放维度判断和权重判断；程序只提供候选边界护栏，不把行业场景或参数写死。

### v0.5.108 - 补充维度的用户立场保真

- 修复行业知识库命中后，建议补充维度偶尔站错立场的问题：例如用户是房屋卖方时，不再让用户补“各房源信息”，而是围绕买方付款能力、贷款审批、签约/过户周期、同类成交、对方真实需求和让价空间来补充。
- `recommendedMissingDimensions` 增加角色保真约束：用户是甲方/发包方时，补供应商能力、交付物、验收、代码/数据/账号控制、换人接管；用户是求职者时，补岗位兑现、直属领导、考核、薪酬、试用期、发展路径和退出成本。
- 结构化提炼和最终回复都增加“关系名与单位保真”：候选对象必须沿用原文里的买家、卖家、供应商、工厂、服务商等关系名；报价、底价、预算、薪资、天/周/月/年等数字单位不得互相改写。
- 该规则仍是通用逻辑约束，不新增固定场景分类，也不把行业知识库内容当成已发生事实写入计算。

### v0.5.107 - 行业关键维度知识库辅助

- 新增“行业维度知识库”作为软参考层，覆盖 AI/软件外包、招聘 offer、房产/资产买卖、供应商采购、合伙股权、代理渠道、内容/IP、硬件 ODM 等主要泛契约场景。
- 知识库不直接参与公式计算，也不作为固定模板限制大模型；服务端只根据用户原文检索相关条目，把命中的关键维度、定义和建议收集方向提供给大模型参考。
- 开放参数抽取器会参考知识库，帮助识别本案可能遗漏的垂直行业变量；但变量是否采用、value/confidence/weight 如何给出，仍由大模型结合当前事实判断。
- `recommendedMissingDimensions` 会结合当前事实、候选差异、匹配缺口和知识库参考，输出更具体的下一步收集方向，例如 AI 外包场景中的 MVP 功能边界、代码与部署可接管性、数据权限与脱敏机制、模型运行成本、上线后维护响应等。
- 目标是在“不写死场景、不限制适用范围”的前提下，用知识库和后续网络搜索弥补模型对垂直领域关键维度的遗漏。

### v0.5.106 - 资料充足度阻断与当前判断分离

- 修复“开放参数已经足够形成候选排序，却仍被判定为必要信息不足”的问题。
- 后台现在区分两类状态：一是信息不足以验算，必须追问；二是信息足以形成当前初步判断，但仍有补充维度可提升排序、谈判条件或退出判断。
- 当开放参数中已经出现交换条件、风险/价值/控制权/履约信号，并且公式结果已能形成当前判断时，不再阻断结论；缺失信息继续作为建议补充项保留。
- 对话输出原则保持不变：当前结论必须明确，结尾提醒用户如有遗漏信息、对方新回复或条款变化，可以继续补充并重新验算。

本项目从 `v0.4.0` 开始维护设计版本。以后凡是涉及产品结构、后台算法、提示词约束、UI 信息架构、数据结构的改动，都必须同步更新本文档的“版本记录”。

回滚原则：

- 回滚 UI：优先按版本记录定位 `src/App.tsx` 与 `src/App.css` 的相关改动。
- 回滚算法：优先按版本记录定位 `src/contractEngine.ts` 中的公式版本号与返回结构。
- 回滚大模型策略：优先按版本记录定位 `vite.config.ts` 中的接口提示词和字段裁剪逻辑。

## 产品定位

契约决策 AI 不是普通聊天机器人，也不是泛化人生决策 AI，而是把交易、职场、合伙、人际、项目选择都还原为显性或隐性契约的个人契约决策智能体。

核心原则：

- 所有问题本质上都是契约。
- 多个 offer、多个买家、多个供应商、多个合作方不是新场景，而是当前市场情况的一部分。
- 公允价值不是单纯价格，而是市场情况中的一个维度；市场情况还包括候选对象数量、竞争强度、替代选择、对方急迫性、同类机会比较和筹码变化。
- 系统不能把“多方案”当成普通利弊分析，也不能把市场情况硬套成一对一谈判。
- 大厂 vs 小厂不是普通职业选择，而是两份雇佣契约的比较：各自承诺什么、要求用户付出什么、给不给成长/现金/稳定/控制权，未来风险由谁承担。
- 系统先挖用户真实需求，再判断哪份契约更匹配其内心需求和长期结果分布。
- 谈判是契约决策后的执行手段之一，不是产品入口。

核心价值：

1. 阻止用户在必要信息不足时仓促决策。
2. 用后台理论公式计算当前局势、未来风险和成功概率。
3. 先生成契约判断；只有当契约判断指向“继续推进且存在可协商对象”时，才生成谈判策略和让步策略。
4. 在项目跟踪中持续记忆新证据，形成后验判断。

## 业务流程图

```mermaid
flowchart TD
  A["用户输入一段情况"] --> B{"是否只是寒暄"}
  B -- "是" --> B1["返回自然开场白\n不写入项目记忆"]
  B -- "否" --> C{"是否为当前完整情况重述"}
  C -- "是" --> C1["重建当前候选事实\n历史进入贝叶斯先验"]
  C -- "否" --> C2["作为增量信息追加\n保留项目生命周期记忆"]
  C1 --> D["构建本轮有效项目上下文"]
  C2 --> D
  D --> D1["每次输入必重算\n生成本轮分析快照"]
  D1 --> D2["大模型候选边界锁定\n整体背景 + A-D 原文片段"]
  D2 --> E["分候选全要素提取\n不按固定场景归类"]
  E --> F["四理论后台验算\n匹配/控制权/分布/可信履约"]
  F --> F1["公式直出候选得分\n开放参数权重由大模型给出"]
  F1 --> G{"信息是否足以形成当前判断"}
  G -- "不足" --> G1["先说明已知事实和缺口\n给具体追问"]
  G -- "足够" --> H["生成明确契约决策\n签/谈/等/放弃"]
  H --> H1{"大模型结论是否与排序表一致"}
  H1 -- "不一致" --> H2["结论对齐检测\n触发重试(最多2次)"]
  H2 -- "仍不一致" --> H3["服务端强制兜底\n追加系统校正段"]
  H2 -- "重试后一致" --> I{"是否需要谈判执行"}
  H3 --> I
  H1 -- "一致" --> I
  I -- "是" --> I1["输出谈判策略\n开局条件/让步顺序/底线/退出触发"]
  I -- "否" --> I2["输出执行或观察建议"]
  G1 --> J["写入项目记忆"]
  I1 --> J
  I2 --> J
  J --> K["右侧方格决策卡\n展示本轮有效事实、候选对比和输出依据"]
  K --> L["变化面板\n展示相对上一轮的成功率/兑现/控制权/可信履约差异"]
```

关键说明：

- “项目生命周期”不是无条件把所有历史事实都当作当前事实。
- 用户补充“对方刚回复了”“新增一个条款”“融资进度更新”属于增量信息，进入后验更新。
- 用户重新给出“现在是什么情况”“当前完整情况”“以这次为准”或在已有项目中完整重述多个候选，属于当前状态重述，应替代此前候选事实。
- 旧记忆仍必须进入全上下文，用于贝叶斯先验、变化证据、可信履约、用户偏好变化和替代选择判断；但不能继续作为当前候选参与本轮候选对比，除非它在当前完整情况中再次出现。
- 每一次用户输入都必须触发一次新的后台验算。只要输入带来新信息，就形成新的分析快照；如果新快照相对上一轮发生变化，右侧测试面板必须显示变化方向和变化幅度。

## 项目状态转换图

```mermaid
stateDiagram-v2
  [*] --> EmptyProject: 新项目
  EmptyProject --> CurrentSnapshot: 首次有效输入
  CurrentSnapshot --> IncrementalUpdate: 用户补充新证据
  IncrementalUpdate --> Recalculation: 每次输入触发全量重算
  Recalculation --> CurrentSnapshot: 形成新判断快照
  CurrentSnapshot --> ReplacementSnapshot: 用户重述当前完整情况
  IncrementalUpdate --> ReplacementSnapshot: 用户声明以本次为准
  ReplacementSnapshot --> CurrentSnapshot: 全上下文重算当前事实
  CurrentSnapshot --> MissingInfo: 关键必要信息不足
  MissingInfo --> IncrementalUpdate: 用户补充缺失信息
  CurrentSnapshot --> DecisionReady: 信息足以形成当前结论
  DecisionReady --> NegotiationPlan: 需要继续谈或补强条件
  DecisionReady --> ExecuteOrExit: 建议接受/等待/放弃
  NegotiationPlan --> IncrementalUpdate: 对方新回复
  ExecuteOrExit --> PosteriorReview: 后续结果回填
  PosteriorReview --> CurrentSnapshot: 后验校准
```

状态规则：

- `CurrentSnapshot`：当前可用于计算的事实快照。
- `IncrementalUpdate`：新增事实，不删除旧候选，适合生命周期追踪。
- `ReplacementSnapshot`：当前完整情况重述，会重建当前候选事实；历史输入仍作为贝叶斯先验和变化证据进入计算，避免旧候选污染当前候选对比。
- `PosteriorReview`：真实结果回填，用于后验校准，而不是重新虚构当时信息。
- `Recalculation`：每次输入后的强制重算状态，必须生成新快照，并和上一轮比较变化。

## 四层理论内核

## 市场情况入口

原设计把“公允价值”理解得过窄，容易只想到价格、估值或标的市场价。现在统一改为“当前市场情况”：

1. 价格/薪酬/估值是否接近市场水平。
2. 同类标的、同类岗位、同类合作对象、同类机会的比较。
3. 候选对象数量：一个、多个、很多个。
4. 竞争强度：谁更稀缺，谁更着急，谁更有替代选择。
5. 时间窗口：市场是在变好、变坏，还是短期波动。
6. 对方急迫性与我方筹码。

市场情况不是产品模块，也不是输出模板，只是后台计算契约匹配、结果分布和谈判筹码的基础因子。

市场情况的作用：

- 形成用户或对手方的替代选择。
- 改变谈判筹码。
- 改变真实需求的紧迫性。
- 改变可接受契约条件。
- 改变成功率和履约风险。

因此，多个候选对象不是“二选一利弊分析”，而是当前市场情况的一部分。系统应先计算市场情况如何改变匹配度、控制权、结果分布和谈判筹码。

### 1. 双边匹配均衡

用途：即时判断当前双方是否有合作基础。

核心变量：

- 我方效用
- 对方效用
- 双方总剩余
- 替代选择压力
- 匹配均衡

### 2. 不完全契约与控制权

用途：判断未来风险控制。

核心变量：

- 参照点缺口
- hold-up 风险
- 再谈判风险
- 剩余控制权风险
- 状态触发控制权转移
- 专用投入激励匹配

### 3. 广义分布函数

用途：聚合当前匹配和未来风险，输出总体结果分布。

结果状态：

- 双赢匹配
- 中性波动
- 错配损耗

### 4. 贝叶斯后验更新

用途：计算对方可信履约指数。

核心输出：

- 先验可信度
- 后验可信度
- 正向证据
- 负向证据
- 可信等级

## 第三个用户价值：三段成功率

成功率必须由后台确定性公式计算，大模型不得自行估算。

三段成功率定义：

1. 当前方案成功率：按当前条件直接执行当前方案，成功达到目标的概率。
2. 优化条件后成功率：补齐信息、调整条件、重新排序需求或协商关键条件后，成功达到目标的概率。
3. 执行后兑现概率：选择落地、合作达成或签约后，实际兑现预期结果的概率。

说明：

- 谈判是决策的产物，不是所有问题的默认入口。
- 当问题存在多个候选对象时，系统把它作为当前市场情况处理，先识别替代选择、竞争强度和候选契约差异，再判断真实需求、约束和契约匹配度。
- 只有当后台判断“继续推进”且存在明确对手方、可交换条件、可让步空间时，三段成功率中的第二段才表现为谈判或让步策略。

### 当前方案成功率

模型：`bargaining-scorecard`

理论依据：

- Nash/Rubinstein bargaining
- 逻辑回归式评分卡
- 信息不对称下的筛选逻辑

核心因子：

- 双方总剩余
- 当前匹配质量
- 替代选择压力
- 对方可信履约
- 信息完整度
- 预期缺口
- hold-up 风险

### 优化条件后成功率

模型：`mechanism-counterfactual`

理论依据：

- 机制设计
- 反事实交换增益
- 帕累托改进
- 合约菜单设计

核心计算：

```text
优化条件后成功率 =
当前方案成功率
+ 条件优化产生的帕累托改进
- 条件优化成本
```

关键判断：

- 调整的是否是我方低成本条件
- 换回的是否是对方高价值承诺
- 是否损害控制权
- 是否增加下行风险

### 执行后兑现概率

模型：`bayesian-survival`

理论依据：

- 贝叶斯后验
- 生存分析 / Hazard model
- 委托代理
- 道德风险
- 不完全契约控制权

核心计算：

```text
履约概率 =
基础生存率 × exp(-阶段风险)
```

核心因子：

- 对方可信履约指数
- 控制权配置
- 状态触发机制
- 信息完整度
- 下行损失风险
- hold-up 风险
- 预期缺口

## 大模型边界

大模型只能做：

- 解释后台计算结果
- 组织专业表达
- 帮用户理解当前应该继续、暂停、换方案、补信息还是观察
- 在后台判断需要谈判时，生成谈判话术和让步顺序

大模型不能做：

- 自行估算胜率
- 重算概率分布
- 覆盖后台结论
- 暴露公式变量和 JSON
- 把所有决策默认改写成二元对抗或谈判问题
- 把契约决策泛化成普通利弊分析或人生建议
- 用排序表之外的理由推翻公式得分第一候选
- 在结论段推荐非公式得分第一候选

## 结论对齐保护(v0.5.119)

大模型最终结论与后台候选综合排序表之间建立多层对齐保护:

1. **结论对齐检测**:不再检查"前 1400 字是否提及 leader",改为检查结尾 800 字结论段是否提到 leader、是否出现"建议/推荐 + 非leader"的组合模式。
2. **2 次重试**:检测到最终结论与公式得分第一不一致时触发重试,prompt 明确要求以公式得分第一候选作为当前建议基础。
3. **服务端强制校正**:2 次重试仍冲突时,在回复末尾追加"系统校正"段,告知用户后台公式得分第一,保证用户永远能看到一致结论。
4. **强约束格式**:排序表要求模型最后一段以"当前建议:候选X"开头,让结论可被正则锁定。

排序计算规则(v0.5.119 调整):

- `decisionScore` 直接取候选专属开放参数进入后台公式后的 `analysis.score / 100`。
- `needMatch`(需求匹配)单独作为解释展示栏，不参与候选排序，不形成第二套权重。
- 前端不再根据场景、行业词、关键词或底线词给候选加减分。
- 显示的“公式得分”= `decisionScore × 100`，不做非线性校准。

## 版本记录

### v0.5.105 - 理论公式固定与动态权重验算

日期：2026-07-02

备份：

- 修改前已完整复制存档到：`F:\AI决策版本备份\contract-ai-before-theory-formula-20260702-020726`

问题背景：

- 泛契约场景不能靠固定行业参数或写死权重判断，否则买房、求职、外包、合作、A-to-A 谈判会互相串味。
- 用户要求“所有关系都先抽象成契约关系”，后台公式必须承接现代契约理论、双边匹配、概率分布与贝叶斯可信履约，而不是让大模型自由编造成功率。
- 同时，权重不能预先写死；应由大模型根据当前事实判断每个变量在本案中的重要性、置信度、风险方向和候选归属，再由后台公式确定性代入计算。

改动：

- 保留后台契约理论公式结构，不把公式、内部变量、JSON、权重明细暴露给普通用户。
- `extractOpenFactors` 提示词升级为“契约变量抽取器”：
  - 大模型只负责从当前事实中抽取可代入公式的变量。
  - 每个变量必须包含 `value`、`confidence`、`weight`，以及可选的 `userWeight`、`otherWeight`、`riskWeight`、`refWeight`。
  - 多候选场景必须在变量标签、分类或证据中保留 A/B/C/D 归属，避免候选串味。
  - 理论 2 强化控制权变量：最终拍板权、验收权、付款节点、尾款、暂停、解除、退出、资源配置、责任边界、账号/数据/代码/IP 归属。
  - 理论 4 强化可信履约证据：书面承诺、合同、案例、第三方证明、发票、授权、质保、SLA、现金流、融资确定性、口头承诺、画饼、不透明、无案例、拒绝写入等。
- `contractEngine` 新增动态权重承接：
  - 后台公式仍然固定，但宏观公式权重由当前抽取变量的 `weight/confidence/category/key/evidence` 汇总推导。
  - 双边匹配公式、参照契约/hold-up 风险、总分公式不再使用一组固定常数适配所有场景。
  - 控制权不再只认固定 `控制权/理论2` 分类，而是从全量变量中识别控制权相关事实。
  - 状态触发机制不再只依赖固定 `state_control_transfer` key，而是识别逾期、不达标、验收失败、资源不到位、融资失败、职责扩大、暂停、解除、退出等状态变量。
  - 贝叶斯可信履约指数不再只扫原文关键词，也会吸收结构化变量中的正向/负向履约证据。
- 控制权与状态触发计算改为“候选专属信号优先”：
  - 如果大模型已经抽取出候选 A/B/C/D 的专属控制权或状态变量，优先用这些变量计算。
  - 只有候选专属变量缺失时，才回退到基础先验，避免所有候选被同一组基础因子拉成相同分数。
- `npm run build` 改为同时构建前端 `dist` 和服务端 `server-dist`，避免部署时服务端仍使用旧算法。
- `/api/analyze-contract` 返回前裁剪 `formulas` 和 `successPanel.formulaVersion`，内部继续按公式计算，但前端与网络响应不暴露公式本体。

验证：

- 已运行 `npm run build:server` 通过。
- 使用同一组 A/B/C offer 变量做后台诊断：
  - A 与 C 因稳定性、平台/外企环境、组织支持和履约证据不同，可信履约、控制权和匹配结果发生区分。
- B 因现金流、融资、期权和职责泛化风险，可信履约与履约兑现概率被明显压低。
- 状态触发机制不再三个候选完全一致；如果用户补充“融资失败如何退出、职责扩大如何暂停、无法转 AI 如何处理”等事实，会重新进入全量计算。

涉及文件：

- `server/index.ts`
- `src/contractEngine.ts`
- `package.json`
- `docs/DESIGN.md`

### v0.4.0 - 三段胜率算法封装

日期：2026-05-31

改动：

- 将单一成功率升级为三段胜率：
  - 当前谈判胜率
  - 让步后胜率
  - 合作后履约概率
- 新增三个后台子模型：
  - `bargaining-scorecard`
  - `mechanism-counterfactual`
  - `bayesian-survival`
- `successPanel.formulaVersion` 升级为 `success-panel-deterministic-1.2`。
- 右侧测试面板展示三段胜率模型名、让步反事实、履约生存分析。
- 明确大模型不得自行估算成功率，只能引用后台 `successPanel`。

涉及文件：

- `src/contractEngine.ts`
- `src/App.tsx`
- `src/App.css`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.4.1 - 30轮回归后的模块识别修正

日期：2026-05-31

改动：

- 基于 30 个复杂用例回归，修复职场/伙伴/交易模块误判。
- 模块识别顺序调整为：
  - 伙伴/合伙强锚点优先
  - 职场强锚点第二
  - 交易强锚点第三
  - 其余再进入词典计分和开放参数提示
- 新增/增强英文和中文锚点：
  - 加薪、签字背锅、导师选择、内部转岗、远程办公
  - 合伙开店、婚前购房、广告合作、游戏发行、MCN、联合研发
- 针对游戏发行合作补充强锚点：
  - `indie game`
  - `game studio`
  - `publisher`
  - `sequel rights`
  - `creative control`
  - `recoup order`
  - `regional rights`
- 修复英文 `offers funding` 被职场 `offer` 误识别的问题：职场锚点改为 `\boffer\b` 词边界匹配。
- 移除英文 `performance` 作为职场强锚点，避免研发外包中的“产品性能”被误判为职场绩效。
- 输出清洗增加 `权重 -> 因素重要性`，避免用户侧泄露内部计算术语。

回归发现：

- 30轮测试中原始版本存在 6 个模块误判。
- 1 个输出泄露“权重”。
- 1 个三段胜率反常由模块误判触发。

涉及文件：

- `src/contractEngine.ts`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.4.2 - 复杂边界场景分类校准

日期：2026-05-31

改动：

- 基于 30 个复杂多因素用例继续校准模块识别边界。
- 将泛化的“股权/equity”从伙伴模块强锚点中移除，避免创业公司 CTO offer、期权补偿等职场契约被误判为合伙关系。
- 保留更精确的合伙语义锚点：
  - `股权分配`
  - `股权合作`
  - `equity split`
  - `equity distribution`
- 新增婚前购房关系契约英文锚点：
  - `before marriage`
  - `pre-marital`
  - `premarital`
  - `breakup exit`
  - `parent decision boundary`
- 未把泛化的 `couple` 设为强锚点，避免“情侣/夫妻普通消费交易”被误判为伙伴关系。

回归结果：

- 30 个复杂用例后台验算全部通过。
- 模块误判：0。
- 三段胜率反常标记：0。
- 自动检查到的内部术语泄露：0。
- 平均当前谈判胜率：0.539。
- 平均让步后胜率：0.571。
- 平均合作后履约概率：0.298。
- 平均贝叶斯可信履约指数：0.518。
- 平均控制权适配度：0.418。

仍需关注：

- 后台单轮完整分析平均耗时偏长，30 例纯后台回归约 5 分 31 秒。
- 履约概率整体偏保守，后续需要用真实成交/履约样本校准参数。
- 当前模块识别仍是规则 + 词典机制，复杂跨域场景未来应升级为可解释的冲突解析器。

涉及文件：

- `src/contractEngine.ts`
- `docs/DESIGN.md`
- `scripts/regression-30-v040.mjs`

### v0.4.3 - 大模型提示词最小化

日期：2026-05-31

改动：

- 将 `/api/decision-pack` 的大模型提示词从“策略灌输型”改为“结果解释型”。
- 大模型输入只保留：
  - 当前决策背景
  - 后台核心计算结果
  - 少量输出边界
- 后台传给大模型的结果包改为裁剪后的核心摘要：
  - 模块与初判
  - 必要信息缺口
  - 覆盖率
  - 结果分布
  - 三段胜率
  - 控制权
  - 贝叶斯可信履约指数
  - 双边匹配与参照合同核心结果
  - 已观察到的前 12 个关键因素
- 移除原先大量理论说明、策略规则、术语禁用清单和强制话术要求，降低模型被过度诱导导致幻觉的概率。
- 对少量容易泄露的专业术语改为输出清洗层处理，例如 `BATNA`、`Change Order`、`Price floor`，不再通过长提示词压制模型。
- 核心摘要字段从内部工程字段改为用户语义字段，避免 `score`、`mismatch`、`stageModels` 等字段名诱导模型输出工程化语言。

设计原则：

- 后台负责计算。
- 大模型负责理解背景、组织表达和生成可执行回复。
- 不再把完整产品方法论塞进单次提示词。
- 不让大模型接触公式、全量变量、完整 JSON 和合规审查结果。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.4.4 - 第二批30例复杂场景回归

日期：2026-05-31

改动：

- 新增第二批 30 个完全不同的复杂多因素用例，覆盖加盟转让、充电桩合作、应届生择业、代运营服务、共同养宠、调岗降薪、IP授权、ERP替换、异地同居、合资项目、婚礼场地等场景。
- 新增测试脚本 `scripts/regression-30-v043-newcases.mjs`，用于同时验证：
  - 模块识别
  - 三段成功率逻辑
  - 大模型输出术语泄露
  - 低可信/弱控制权下履约概率是否异常偏高
- 修复第二批回归发现的三个模块边界：
  - 代运营/外包/服务采购优先进入交易模块。
  - 异地恋同居、婚姻时间、分手成本、未来子女教育、父母赡养责任进入伙伴/关系契约模块。
  - 品牌联名快闪、成本共担、商标使用、菜单决策、客户数据进入伙伴/合作模块。
- 输出清洗补充：
  - `得分 -> 表现`
  - `参照点 -> 预期标准`
  - `medium -> 中等`
  - `因素重要性因素 -> 关键因素`
- 测试规则校准：让步成本高于收益但胜率上升的异常判断增加 0.01 容差，避免极小数值波动误报。

回归结果：

- 纯后台第二批 30 例：模块误判 0，三段胜率异常 0，泄露 0。
- 带大模型输出第二批 30 例：模块误判 0；发现 3 个输出术语泄露和 1 个测试阈值误报，已修复。

涉及文件：

- `src/contractEngine.ts`
- `vite.config.ts`
- `scripts/regression-30-v043-newcases.mjs`
- `docs/DESIGN.md`

### v0.4.5 - 取消前置模块归属

日期：2026-05-31

改动：

- 取消“先判断交易/职场/伙伴模块，再选择对应参数池”的前置路径。
- 后台改为全量因子池：
  - 基础因子来自原交易、职场、伙伴三类因子的全集。
  - 开放因子由大模型只抽取 `factors`，不再输出 `moduleHint`。
  - 账号归属、职业牺牲、控制权、时间压力、替代选择等只作为影响因子参与计算，不再决定场景归属。
- 大模型决策接口不再接收模块名，也不再看到场景类型字段。
- 右侧测试面板从“模块”改为“引擎”，显示 `全量因子决策引擎`。
- 第二批 30 例回归脚本移除模块归属检查，改为验证：
  - 三段胜率逻辑
  - 输出术语泄露
  - 低可信/弱控制权下履约概率是否异常偏高

设计原则：

- 不人为归类用户场景。
- 不让局部关键词决定语义归属。
- 减少“模块判断 -> 参数选择 -> 结果解释”的多层传导失真。
- 后台只做全量因子即时验算，大模型只解释核心计算结果。

涉及文件：

- `src/contractEngine.ts`
- `vite.config.ts`
- `src/App.tsx`
- `scripts/regression-30-v043-newcases.mjs`
- `docs/DESIGN.md`

### v0.4.6 - 输出质量产品化裁剪

日期：2026-05-31

改动：

- 对第二批 30 个真实大模型输出进行质量测试。
- 保留“三段成功率”的百分比展示：
  - 当前条件下谈成
  - 优化条件后谈成
  - 合作后顺利履约
- 其他内部计算结果改为强/中/弱或高/中/低，不再把控制权、承诺稳定性、收益结构等指标的原始小数直接交给大模型。
- 输出清洗补充：
  - `信息覆盖率 -> 信息完整度`
  - `覆盖率 -> 信息完整度`
  - `控制权适配度 -> 控制权清晰度`
  - `承诺缺口 -> 承诺不清`
  - `预期缺口 -> 预期不一致`
  - `高因素重要性关键因素 -> 关键因素`
  - `高因素重要性必要因素 -> 关键必要因素`
  - `替代选择（替代选择） -> 替代选择`
  - `后台数据显示/后台评估显示/后台计算显示 -> 测算结果显示`
  - `后台判定 -> 当前判断`
  - `Condition Precedent -> 先决条件`
  - `Total Compensation -> 总薪酬`

测试发现：

- v0.4.5 的计算方向正确，但真实输出仍偏后台报告化。
- 主要问题不是大模型乱想，而是传入的大模型摘要过于数值化。
- v0.4.6 将“可公开的用户价值数字”和“内部决策指标”分层，降低逆向工程和工程语言泄露风险。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.4.7 - 单系统提示词口语化输出

日期：2026-05-31

改动：

- `/api/decision-pack` 移除多条用户侧输出规则。
- 改为单条系统提示词控制表达风格：
  - 像决策顾问一样说人话。
  - 用接地气、容易懂的中文。
  - 说清楚该不该做、为什么、下一步怎么谈。
  - 少用数据和专业词。
  - 不暴露公式、JSON、字段名或内部计算过程。
- 用户消息只保留：
  - 当前背景
  - 后台核心计算结果

设计目的：

- 避免过度提示词导致表达僵硬。
- 保留后台计算优势，同时让前台输出更像真实顾问对话。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.4.8 - 测试面板去模块化 JSON

日期：2026-05-31

改动：

- `ContractAnalysis.moduleId` 从历史兼容的 `trade` 改为 `universal`。
- 分析结果统一显示为 `全量因子决策引擎`。
- 右侧测试面板底部从“模型输入 JSON”改为“大模型输入摘要 JSON”。
- 不再把完整后台对象原样展示给测试者，避免误以为系统仍按交易/职场/伙伴固定模块运行。
- 大模型输入摘要只展示：
  - 引擎标识
  - 初步判断与建议动作
  - 必要信息
  - 三段成功率
  - 结果倾向
  - 控制权摘要
  - 可信履约摘要
  - 已观察关键因子
  - 建议追问
- 追问问题去重，避免全量因子池中相似控制权问题重复出现。

涉及文件：

- `src/contractEngine.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.31 - 双语界面历史默认文案迁移与布局修复

日期：2026-06-17

背景：

- 英文界面下，历史默认项目标题仍显示“新决策项目”。
- 历史默认欢迎语仍显示中文。
- 新增语言切换按钮后，顶部项目工具栏从 3 个控件变成 4 个控件，英文界面下项目选择框被挤到右侧。
- 模型连接失败时直接显示 `fetch failed`，对用户不友好。

改动：

- 新增默认项目标题识别：
  - `新决策项目`
  - `New Decision Project`
- 切换语言时仅迁移默认项目标题和默认欢迎语：
  - 真实用户输入、模型回复和历史对话不自动翻译。
- 读取本地项目和服务端项目后，会按当前语言迁移默认文案。
- 顶部项目工具栏改为 4 列：
  - 语言切换。
  - 项目选择。
  - 新建项目。
  - 删除项目。
- 移动端项目工具栏保持完整宽度。
- 前端将 `fetch failed` / network error 转成更清楚的模型连接提示。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.32 - 本地模型优先与 API 自动兜底

日期：2026-06-18

背景：

- 本地测试时希望保留本地大模型能力。
- 当本地模型服务未启动或连接失败时，希望自动使用云端 API，避免频繁手动切换 `.env.local`。

改动：

- 新增默认模型模式：
  - `LLM_PROVIDER=local-first`
- `local-first` 策略：
  - 第一步调用本地 OpenAI-compatible 服务。
  - 本地失败后，如果配置了 `DEEPSEEK_API_KEY`，自动调用 DeepSeek。
  - 未配置 DeepSeek Key 时，只尝试本地模型。
- 保留其他模式：
  - `LLM_PROVIDER=deepseek`：只使用 DeepSeek。
  - `LLM_PROVIDER=openai-compatible`：只使用本地/兼容接口；如设置 `LLM_FALLBACK_PROVIDER=deepseek` 可手动开启兜底。
  - `LLM_PROVIDER=api-first`：优先使用 API，再回退本地。
- 每次尝试都会写入 `data/usage.json`：
  - 本地失败会记录失败。
  - API 成功会记录成功和 token。
- `/api/health` 新增：
  - `llmMode`
  - `llmProviders`

配置示例：

```env
LLM_PROVIDER=local-first
LLM_BASE_URL=http://127.0.0.1:8080
LLM_MODEL=Qwen3.6-35B-A3B-UD-IQ4_XS.gguf
DEEPSEEK_API_KEY=sk-...
DEEPSEEK_MODEL=deepseek-v4-flash
```

涉及文件：

- `server/index.ts`
- `.env.local`
- `.env.example`
- `.env.beta.example`
- `README.md`
- `docs/DESIGN.md`

### v0.5.104 - 需求匹配改为 1+4+1 JSON

日期：2026-06-29

问题背景：

- 右侧“双方需求是否匹配”之前混用了候选价值/风险拼接，容易把 A/B/C/D 的价值和代价串味。
- 用户需要看到的是：我方需求是什么、每个候选能给什么/想要什么/我方代价是什么、逐项匹配后分数是多少。
- 9 组 JSON 过细，当前产品更适合 `1+4+1`：一组我方需求、最多四组候选、一组全参数匹配结论。

新增结构：

- `needMatch.userNeeds`：我方需求、开放维度、缺失信息。
- `needMatch.candidates.A-D`：每个候选独立记录：
  - 候选方可能需求。
  - 候选能给用户的价值。
  - 候选可能想从用户获得的东西。
  - 用户选择该候选的主要代价。
  - 候选专属开放维度。
- `needMatch.fullParameterMatch`：
  - `candidateScores.A-D`
  - 每个候选的逐项匹配、匹配分、我方满足度、对方满足度、关键缺口。
  - `recommendedMissingDimensions`：由大模型根据当前事实和匹配缺口推断“如果要更好判断什么更有利于匹配用户需求，建议用户提供什么具体信息”，不使用前端写死场景规则。

前端展示：

- `DecisionGridCard` 的第二栏优先读取 `needMatch`。
- 如果 `needMatch` 不存在，才回退到旧的候选价值/风险拼接逻辑。
- 展示顺序改为：我方需求 -> 匹配方法 -> 候选逐项需求匹配 -> 全参数匹配结论。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.33 - 内测模型通道手动选择

日期：2026-06-18

背景：

- 当前阶段是内测，不是公开公测。
- 测试时需要同时保留本地模型和云端 API 两种方式。
- 默认应继续保持“有本地用本地，没本地用 API”的自动策略。
- 为了对比本地模型、云端 API 和自动兜底效果，测试者需要在界面里手动选择本轮请求的模型通道。

改动：

- 前端新增内测模型选择按钮：
  - `自动`：本地优先，失败后尝试 API。
  - `本地`：只调用本地 OpenAI-compatible 模型。
  - `API`：只调用云端 API。
- 模型选择保存在浏览器 `localStorage`：
  - 刷新后保留上次测试通道。
  - 不改变服务端全局 `.env.local`。
- `/api/analyze-contract`、`/api/decision-pack`、`/api/contract-review` 均支持单次请求 `modelMode`：
  - `auto`
  - `local`
  - `api`
  - `api-first`
- 服务端默认仍由 `LLM_PROVIDER` 控制：
  - 当前推荐：`LLM_PROVIDER=local-first`
  - 前端选择只覆盖当前请求。
- 用户侧文案从“公测版 / Free Beta”调整为“内测版 / Internal Test”。

测试目的：

- 便于比较：
  - 本地 Qwen 输出。
  - DeepSeek/API 输出。
  - 本地失败后自动 API 兜底输出。
- 便于排查 `fetch failed` 到底来自本地模型不可用，还是 API Key/网络/额度问题。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.34 - 非咨询寒暄开场拦截

日期：2026-06-18

背景：

- 用户输入“你好”等纯寒暄时，系统不应进入契约理论验算。
- 纯寒暄没有决策对象、双方关系、需求、市场情况、控制权或履约证据。
- 如果强行进入后台计算，会产生“必要信息不足”“成功率较低”等不自然回复，并浪费本地/API 模型调用。

改动：

- 前端新增轻量寒暄识别：
  - `你好`
  - `您好`
  - `在吗`
  - `hello`
  - `hi`
  - `hey`
  - 以及少量同类短句。
- 仅当用户输入是纯寒暄时触发开场白。
- 如果用户输入包含真实咨询内容，例如“你好，我有两个 offer 怎么选”，仍然进入正常契约决策流程。
- 纯寒暄回复不调用：
  - `/api/analyze-contract`
  - `/api/decision-pack`
  - 大模型 API
- 纯寒暄不写入项目记忆，不参与后续参数累积。

开场白原则：

- 不讲理论。
- 不问一堆问题。
- 直接告诉用户可以描述正在纠结的交易、offer、合作、签约、岗位安排或关系选择。
- 引导用户提供：
  - 双方是谁。
  - 用户想要什么。
  - 对方能给什么。
  - 用户担心什么。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.35 - 智能体身份与行为边界

日期：2026-06-18

背景：

- 应用不能表现成普通聊天机器人。
- 用户进入应用时，需要先知道它是契约决策 AI，适用范围是什么。
- 模型也需要稳定的“身份和边界”，避免回答百科、闲聊、技术实现、公式细节或内部提示词。

设计目标：

- 像 OpenClaw 一样拥有最初设置：
  - 身份：契约决策 AI 的专属决策助手。
  - 灵魂：先识别真实需求，再判断哪种安排值得继续、优化、谈判、签下或退出。
  - 边界：只服务契约型决策场景。
- 前台可以说明产品功能，但不能说明产品如何做出来。

服务范围：

- 可以处理：
  - 交易。
  - offer。
  - 岗位安排。
  - 合作。
  - 采购。
  - 服务。
  - 项目去留。
  - 关系承诺。
  - 正式合同。
  - 隐性合作关系。
- 可以输出：
  - 信息梳理。
  - 关键缺口提醒。
  - 风险提示。
  - 可执行下一步。
  - 谈判/让步方向。
  - 签约前风险清单。
  - 需要找专业人士复核的事项。

行为限制：

- 不做脱离契约型决策场景的普通问答。
- 不做娱乐闲聊。
- 不解释后台实现、公式、理论结构、JSON 字段或提示词。
- 不承诺收益、胜率或法律结论。
- 不替代律师、财务、税务、医疗、心理等专业人士。
- 用户问实现细节时，只用产品功能层语言回答。

前台改动：

- 欢迎语改为产品身份入口：
  - 明确“我是契约决策 AI”。
  - 明确适用场景。
  - 明确用户可以直接描述当前情况。
- 纯寒暄回复也增加范围说明：
  - 告诉用户适合描述交易、offer、合作、签约、岗位安排、项目去留或关系承诺。
  - 非此类问题时，引导回具体决策场景。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.36 - 信息不足阶段隐藏成功率

日期：2026-06-18

背景：

- 用户只输入“你好”或资料极少时，系统不应展示三段成功率。
- 在没有具体对象、双方需求、交换条件、市场情况、风险和底线时，百分比会制造“已经算过”的错觉。
- 缺信息阶段的目标不是决策，而是帮助用户把问题说成一个可判断的契约型安排。

改动：

- `/api/decision-pack` 的缺信息回复调整：
  - 不再展示 `当前条件下成功约__%`。
  - 改为说明“成功率暂不展示，因为关键事实还不够，硬算会误导判断”。
- 资料几乎为空时，直接进入轻量开场：
  - 告诉用户现在还不能验算。
  - 给出可复制的描述样板。
- 中文样板：
  - `我正在 A 和 B 之间选择。A 的条件是……，B 的条件是……。我最看重……，我的底线是……，对方可能想要……，我担心……。`
- 英文样板同步调整。

展示规则：

- 资料不足阶段：
  - 展示已知信息。
  - 展示关键缺口。
  - 展示缺口会影响什么。
  - 展示样板和优先追问。
  - 不展示成功率百分比。
- 正式判断阶段：
  - 当必要信息足够，或用户明确要求“按现有资料分析”时，才允许展示三段成功率。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.37 - 项目完整性检查与冗余文件清理

日期：2026-06-18

背景：

- 当前项目经历过多轮原型、测试、输出对比和本地部署准备。
- 目录中残留了早期 Vite 模板资源、临时引擎测试副本和本地烟测项目数据。
- 需要确认 AI 决策项目完整性，同时清理非必要文件，避免与其他项目资料混杂。

检查结论：

- 核心应用文件保留：
  - `src/App.tsx`
  - `src/App.css`
  - `src/contractEngine.ts`
  - `server/index.ts`
  - `public/favicon.svg`
  - `docs/`
  - `scripts/`
  - 环境模板与 TypeScript/Vite 配置。
- 保留运行数据：
  - `data/users.json`
  - `data/sessions.json`
  - `data/usage.json`
  - 真实用户/匿名项目记忆。
- 保留测试脚本：
  - 这些脚本记录了历史回归测试、模型对比和输出质量测试，仍可用于上线前验证。

清理内容：

- 删除早期临时引擎测试目录：
  - `.tmp-engine-test/engine.mjs`
  - `.tmp-engine-test/favicon.svg`
  - `.tmp-engine-test/icons.svg`
- 删除未引用的模板/视觉资源：
  - `src/assets/hero.png`
  - `src/assets/react.svg`
  - `src/assets/vite.svg`
  - `public/icons.svg`
- 删除本地烟测/编码测试项目数据：
  - `data/projects/codex-smoke-test.json`
  - `data/projects/codex-utf8-test.json`
  - `data/projects/codex-utf8-escape-test.json`
- `.gitignore` 移除旧的 `优鱼/*` 项目残留规则。

验证：

- 删除后没有发现残留引用。
- `npm run build` 通过。
- `npm run build:server` 通过。
- `npm run lint` 通过。

涉及文件：

- `.gitignore`
- `docs/DESIGN.md`
- `.tmp-engine-test/`
- `src/assets/`
- `public/icons.svg`
- `data/projects/`

### v0.5.38 - Hugging Face Spaces 内测部署包

日期：2026-06-21

背景：

- 原计划优先部署内测版，而不是直接商业收费版。
- 内测版需要一个可公开访问的线上链接，便于测试真实使用意愿。
- 用户希望保留本地/API 双路线，但线上内测应优先使用云端 API，避免依赖本地模型服务。
- Hugging Face Spaces 的 Docker Space 适合作为第一阶段内测部署目标。

部署策略：

- 第一阶段：Hugging Face Spaces Docker 部署。
- 版本：`APP_RELEASE_CHANNEL=beta`。
- 模型：线上使用 `LLM_PROVIDER=deepseek`。
- 支付：内测阶段不启用 Stripe。
- 管理：保留 `/admin`，用于查看用户、项目、轮次和 token 用量。
- 数据：继续使用 JSON 文件存储，仅适合内测，不作为正式商业数据库。

新增文件：

- `Dockerfile`
  - 使用 Node 22 Alpine。
  - Builder 阶段执行 `npm run build` 和 `npm run build:server`。
  - Runner 阶段只安装生产依赖。
  - 默认监听 `PORT=7860`，适配 Hugging Face Spaces。
- `.dockerignore`
  - 排除 `.env.local`、`data/`、`node_modules/`、`dist/`、`server-dist/`、日志和 Git 元数据。
- `docs/DEPLOY_HUGGINGFACE.md`
  - 记录 Space 创建、Secrets 配置、访问地址和内测限制。

上线必要 Secrets：

- `DEEPSEEK_API_KEY`
- `APP_ADMIN_EMAIL`
- `APP_ADMIN_PASSWORD`
- `APP_ADMIN_SECRET`
- `PUBLIC_APP_URL`
- `APP_ALLOWED_ORIGINS`

当前限制：

- 免费/轻量 Space 的磁盘不适合作长期数据库。
- JSON 文件存储只适合早期内测。
- 正式商业上线前仍需迁移云数据库、完善日志脱敏、额度告警、备份和法律审阅。

涉及文件：

- `Dockerfile`
- `.dockerignore`
- `docs/DEPLOY_HUGGINGFACE.md`
- `docs/DESIGN.md`

### v0.5.39 - Hugging Face Space README 元数据修复

日期：2026-06-21

背景：

- 首次上传到 Hugging Face Space 后，运行状态显示 `CONFIG_ERROR`。
- 错误信息为 `Missing configuration in README`。
- Docker Space 需要在 `README.md` 顶部提供 Space 元数据。

改动：

- `README.md` 顶部新增 Hugging Face Space YAML front matter：
  - `title`
  - `emoji`
  - `colorFrom`
  - `colorTo`
  - `sdk: docker`
  - `app_port: 7860`
  - `pinned`
  - `license`

效果：

- Hugging Face 可以识别该仓库为 Docker Space。
- Space 会使用 `Dockerfile` 构建并监听 `7860` 端口。

涉及文件：

- `README.md`
- `docs/DESIGN.md`

### v0.5.40 - Hugging Face Docker 构建加速

日期：2026-06-21

背景：

- Hugging Face Space 识别 Docker 配置后长时间停留在 `BUILDING`。
- 原 Dockerfile 使用 builder/runner 两阶段构建，会执行两次 `npm ci`。
- 免费 CPU 构建环境下，两次依赖安装可能导致首次构建时间过长。

改动：

- Dockerfile 改为单阶段构建：
  - 只执行一次 `npm ci`。
  - 然后执行 `npm run build` 和 `npm run build:server`。
  - 直接用同一镜像启动 `npm run start`。

取舍：

- 镜像体积会比生产两阶段构建略大。
- 内测阶段优先保证构建速度和部署成功。
- 正式商业部署到专用云平台时，可再恢复多阶段生产镜像。

涉及文件：

- `Dockerfile`
- `docs/DESIGN.md`

### v0.5.41 - Hugging Face 预构建产物部署

日期：2026-06-21

背景：

- Space 长时间停留在 `BUILDING`。
- 即使 Dockerfile 简化为单阶段，Hugging Face 免费 CPU 仍需要现场执行 `npm ci` 和 TypeScript/Vite 构建。
- 当前内测目标是尽快拿到可访问链接，而不是在 Hugging Face 上重复完整构建。

改动：

- Dockerfile 改为预构建产物运行模式：
  - 不再执行 `npm ci`。
  - 不再执行 `npm run build`。
  - 镜像只复制 `dist/`、`server-dist/` 和 `docs/`。
  - 启动命令改为 `node server-dist/server/index.js`。
- 部署上传时额外包含本地生成的：
  - `dist/`
  - `server-dist/`

取舍：

- Space 仓库会包含构建产物。
- 构建速度显著提升，适合内测。
- 每次上线前必须先在本地执行：
  - `npm run build`
  - `npm run build:server`
  - `npm run lint`

涉及文件：

- `Dockerfile`
- `docs/DESIGN.md`
- Hugging Face Space 上传包中的 `dist/` 与 `server-dist/`

### v0.5.42 - 普通服务器预构建部署包

日期：2026-06-21

背景：

- Hugging Face Docker Space 长时间停留在 `BUILDING`。
- 用户希望直接使用本地构建完成的产物上传服务器运行。
- 普通 VPS/云服务器可以直接运行 Node.js 服务，不需要在服务器上重新执行构建。

部署策略：

- 本地执行：
  - `npm run build`
  - `npm run build:server`
  - `npm run lint`
- 打包运行产物：
  - `dist/`
  - `server-dist/`
  - `docs/`
  - `.env.production.example`
- 服务器只需要 Node.js 22+。
- 启动命令：
  - `node server-dist/server/index.js`

新增产物：

- `release/contract-decision-ai-server-prebuilt.zip`

新增文档：

- `docs/DEPLOY_PREBUILT_SERVER.md`

与 Hugging Face 的区别：

- Hugging Face Docker Space 即使上传构建产物，也仍需构建 Docker 镜像。
- 普通服务器可直接解压运行，部署速度更快。
- 普通服务器需要自行处理进程守护、HTTPS、域名、日志、备份和安全组。

涉及文件：

- `docs/DEPLOY_PREBUILT_SERVER.md`
- `docs/DESIGN.md`
- `release/contract-decision-ai-server-prebuilt.zip`

### v0.5.43 - Hugging Face 预构建产物 Docker 忽略规则修复

日期：2026-06-21

背景：

- 为了加速 Hugging Face Space 构建，Dockerfile 已改为直接复制本地预构建产物：
  - `dist/`
  - `server-dist/`
- 但 `.dockerignore` 仍排除了 `dist` 和 `server-dist`。
- 这会导致 Hugging Face Docker 构建上下文里缺少运行产物，Dockerfile 的 `COPY dist` / `COPY server-dist` 无法正常执行。

改动：

- `.dockerignore` 移除：
  - `dist`
  - `server-dist`
- `.gitignore` 继续忽略本地构建产物，不影响源码仓库清洁。
- Hugging Face 上传包仍手动包含 `dist/` 和 `server-dist/`。

涉及文件：

- `.dockerignore`
- `docs/DESIGN.md`

### v0.5.44 - Hugging Face 容器监听地址修复

日期：2026-06-21

背景：

- Hugging Face Space 已从 `BUILDING` 进入 `APP_STARTING`，说明 Docker 镜像可以构建，但平台仍未确认应用端口可访问。
- 容器平台通常要求服务监听 `0.0.0.0`，只监听本机回环地址会导致外部健康检查无法访问。

改动：

- 服务端新增 `HOST` 环境变量，默认值为 `0.0.0.0`。
- 启动日志从固定 `127.0.0.1` 改为输出实际监听地址。
- Hugging Face 部署环境应设置 `HOST=0.0.0.0`，继续使用 `PORT=7860`。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.45 - Hugging Face ESM 启动文件修复

日期：2026-06-21

背景：

- Hugging Face Space 仍停留在 `APP_STARTING`。
- 当前预构建 Dockerfile 只复制了 `dist/`、`server-dist/` 和 `docs/`，没有复制 `package.json`。
- 服务端编译产物使用 ES Module 语法，Node 需要读取 `package.json` 中的 `"type": "module"` 才能按 ESM 运行。
- 缺少 `package.json` 时，容器内可能以 CommonJS 方式加载 `server-dist/server/index.js`，导致启动阶段报错。

改动：

- Dockerfile 新增 `COPY package.json ./package.json`。
- 继续保持预构建部署，不在 Hugging Face 免费 CPU 环境里执行 `npm ci`。

涉及文件：

- `Dockerfile`
- `docs/DESIGN.md`

### v0.5.46 - Hugging Face App 嵌入显示修复

日期：2026-06-21

背景：

- 应用健康接口在带 Hugging Face 登录鉴权时已经返回 `200 OK`。
- 但 Space 的 App 页仍显示 `Starting...`。
- 原服务端安全头设置 `X-Frame-Options: DENY`，会阻止 Hugging Face 将 `hf.space` 应用嵌入 Space 页面展示。

改动：

- 移除 `X-Frame-Options: DENY`。
- 新增 `Content-Security-Policy: frame-ancestors 'self' https://huggingface.co https://*.huggingface.co`。
- 保留对嵌入来源的限制，同时允许 Hugging Face App 面板正常加载。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.47 - Hugging Face Docker 基础镜像降级缓存优化

日期：2026-06-21

背景：

- Hugging Face Space 在修复嵌入显示后长时间停留在 `BUILDING`。
- 当前运行产物总量很小，构建卡住更可能发生在 Docker 基础镜像拉取、平台队列或缓存命中阶段。
- 应用服务端不依赖 Node 22 特性，Node 20 已满足当前 ES2023 运行需求。

改动：

- Docker 基础镜像从 `node:22-alpine` 改为 `node:20-alpine`。
- 目标是提高 Hugging Face 免费 CPU Docker 构建的缓存命中率，减少长时间卡在构建阶段的概率。

涉及文件：

- `Dockerfile`
- `docs/DESIGN.md`

### v0.5.48 - 公测版强制登录后调用 AI

日期：2026-06-21

背景：

- Hugging Face Space 已改为 Public，未登录访问者也能打开应用页面。
- 如果未登录用户可以直接调用 AI，会消耗 DeepSeek API 额度，也无法做用户级用量统计、封禁和后续权限控制。

改动：

- 后端对会消耗模型或后台验算的接口增加登录校验：
  - `/api/analyze-contract`
  - `/api/decision-pack`
  - `/api/contract-review`
- 未登录请求返回 `401` 和“请先登录后使用”。
- 前端未登录时禁用发送按钮和合同上传按钮。
- 前端展示登录提示，避免用户误以为应用不可用。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.49 - 移动端注册登录入口修复

日期：2026-06-21

背景：

- 公测版已要求登录后才能调用 AI。
- 手机端原布局在 `max-width: 680px` 时直接隐藏左侧产品栏。
- 登录/注册表单位于左侧产品栏，因此手机用户无法看到注册入口，也无法继续使用产品。

改动：

- 手机端不再隐藏 `product-panel`。
- 移动端隐藏营销说明、功能卡片、项目状态、模型测试按钮和信任提示。
- 移动端保留品牌头部和账号登录/注册卡片。
- 聊天区移动端置于登录区下方，页面允许自然滚动。

涉及文件：

- `src/App.css`
- `docs/DESIGN.md`

### v0.5.50 - 移动端登录后收缩与合规说明固定

日期：2026-06-21

背景：

- 手机端需要按主流移动页面完整适配，不应在未登录时隐藏产品说明和注册入口。
- 用户注册/登录成功后，产品说明区可以自动收缩，把主要屏幕空间留给对话框。
- 合规说明必须始终在用户输入附近可见，避免用户误解 AI 输出为专业法律、财税或投资意见。

改动：

- `app-shell` 增加登录态 class：`authenticated`。
- 手机端未登录时完整展示产品说明、功能卡片、项目状态、模型模式、注册登录与合规边界，并支持整页纵向滑动。
- 手机端登录后自动收缩产品栏，只保留品牌与账号状态，把对话框高度提升到主视图。
- 对话框底部合规说明增加“合规说明”标签，并持续展示 Terms / Privacy 入口。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.51 - 免费商用字体与视觉资产治理

日期：2026-06-22

背景：

- 产品进入公开测试后，需要避免字体、图标、模板视觉和素材授权风险。
- 当前应用不应依赖付费字体、商业模板、图库素材或无法确认授权来源的默认图标。

改动：

- 全局字体栈改为免费商用优先：
  - `Noto Sans SC`
  - `Source Han Sans SC`
  - `Noto Sans`
  - `Liberation Sans`
  - 系统字体兜底
- 等宽字体栈改为免费商用优先：
  - `Noto Sans Mono`
  - `Source Code Pro`
  - `Liberation Mono`
  - 系统等宽字体兜底
- 替换 `public/favicon.svg` 为项目原创 SVG 图标，避免沿用模板或不明确来源图标。
- 新增 `docs/COMMERCIAL_ASSET_NOTICE.md`，记录字体、图标、视觉资产和依赖的商用授权边界。
- 新增 `LICENSE`，与 README / Hugging Face 元数据中的 MIT 许可声明保持一致。
- `package.json` 增加 `license: MIT`。
- README 增加商用资产说明入口。

涉及文件：

- `src/index.css`
- `src/App.css`
- `public/favicon.svg`
- `docs/COMMERCIAL_ASSET_NOTICE.md`
- `LICENSE`
- `package.json`
- `README.md`
- `docs/DESIGN.md`

### v0.5.103 - 怪词拦截进入后端资料 JSON

日期：2026-06-29

状态：

- 本地测试中。

背景：

- 用户指出 `重点错误内容` 是明显怪词，不应该出现在任何用户可见输出里。
- 上一版只在前端第 2 格主句层尝试清洗，但怪词仍可能先进入后端资料 JSON，再被决策回复或右侧卡片引用。

改动：

- `summarySystemPrompt` 明确禁止输出怪词、占位词和机器翻译腔。
- 禁止词包括：
  - `重点错误内容`
  - `兵员`
  - `偿付和融资`
  - `核心但度`
  - `自动化程度`
  - `安全投入`
  - `稳定启动`
  - `选项梦想`
- 后端 `summarizeCurrentInfo` 返回前统一调用 `sanitizeUserFacingReply`，阻止怪词进入后续决策提示词。
- 前端 `cleanSummaryPhrase` 同步补充清洗，作为最终展示保险。

设计目的：

- 怪词必须在“模型输出 -> 后端 JSON -> 决策提示 -> 前端展示”的链路前段就被拦截，而不是只靠最终页面替换。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.102 - 需求匹配主句去脏词与白名单化

日期：2026-06-29

状态：

- 本地测试中。

背景：

- 用户反馈第 2 格仍出现明显不自然或错误表达：
  - `重点错误内容`
  - `兵员或 AI 核心度`
  - `偿付和融资不确定`
  - `自动化程度和安全投入`
  - 候选价值中混入过度推断或脏开放维度。

改动：

- 第 2 格候选价值/代价改为白名单式生成：
  - 价值只从明确薪资、平台背书、福利、外企环境、低强度、直接 AI 产品、AI 接触但非核心、领导资源等可核查事实生成。
  - 代价只从岗位兑现不确定、现金流/融资、期权、职责泛化、工作强度、自主权/资源不足等可核查风险生成。
- `openDimensions` 仍保留在 JSON 中，但不再直接进入第 2 格主句，避免模型自行发挥污染用户可读解释。
- 增加短语清洗层：
  - 修正 `兵员`、`偿付和融资`、`核心但度` 等本地模型错误词。
  - 移除 `重点错误内容`。
- 第 2 格不再把整体 `错配或落空风险不低` 这种计算结论混进需求匹配主句。

设计目的：

- 第 2 格只回答“候选如何满足需求、候选自己的代价是什么”，不展示计算结论和模型脏词。
- 开放维度用于后台核查和后续计算，不直接污染用户侧主解释。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.101 - 需求匹配改用候选独立 JSON

日期：2026-06-29

状态：

- 本地测试中。

背景：

- 用户确认 `项目整体情况` 已修复，但 `双方需求是否匹配` 仍然把全局需求、A/B/C 对比事实混进每个候选自己的价值说明里。
- 典型错误：
  - Offer A 的价值中出现 `B: 直接负责企业知识库 AI Agent 产品`。
  - Offer B 的风险中混入整体真实需求。
  - Offer C 的价值/代价不是基于 C 自己的 JSON，而是套用整体因素池。

改动：

- 第 2 格 `双方需求是否匹配` 优先读取 `basic-facts-1.1` 的 5 分区 JSON：
  - 用户核心诉求、底线和共同背景只读取 `overall`。
  - Offer A 只读取 `A`。
  - Offer B 只读取 `B`。
  - Offer C 只读取 `C`。
  - Offer D 只读取 `D`。
- 新增候选专属解释函数：
  - `basicFactsCandidateNeedLine`
  - `basicFactsValueSummary`
  - `basicFactsRiskSummary`
- 收紧开放参数过滤：
  - 同时提到多个候选的开放参数不再作为单一候选的专属价值/风险。
  - 避免全局对比事实污染候选专属说明。

设计目的：

- 需求匹配必须回答“这个候选如何满足用户需求，以及它自己的代价是什么”，不能把整体背景或其他候选事实塞进当前候选。
- 结构化 JSON 不只是展示用，也必须成为后续需求匹配和解释的主数据源。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.100 - 基本情况五分区 JSON 交付

日期：2026-06-29

状态：

- 本地测试中。

背景：

- 用户指出“基本情况”不能继续用散文摘要或关键词提炼。
- 所有大模型交付都应尽量转成结构化 JSON，方便核查候选是否遗漏、事实是否串味、开放维度是否被保留。
- 多候选场景中，整体背景和 A/B/C/D 候选必须分属不同 JSON，不能放在同一段文字或一个混杂数组里。

改动：

- `summarySystemPrompt` 从文本摘要改为 JSON 结构化交付。
- 基本情况提炼输出固定为 5 个独立分区：
  - `overall`：用户身份、当前决策背景、共同事实、用户需求、现实约束、全局开放维度、全局缺失事实。
  - `A` / `B` / `C` / `D`：每个候选独立 JSON，包含专属事实、固定条款字段、候选专属开放维度和候选专属缺失事实。
- 未出现的候选必须填 `null`，禁止按“用户说有几个候选”硬补。
- 前端 `projectFactLines` 优先解析结构化 JSON；解析失败时才回退到旧文本/规则抽取。
- JSON 中保留 `openDimensions`，用于承接模型认为有价值但固定字段未覆盖的全量参考维度。

设计目的：

- 让“现在的基本情况”成为可核查事实底稿，而不是不可验证的摘要。
- 防止 A/B/C/D 候选信息串味。
- 为后续候选专属效用计算、候选专属控制权计算和多候选对比打基础。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.99 - 回退生命周期切片实验

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户反馈 `v0.5.97 / v0.5.98` 引入的“历史输入 / 当前完整情况 / 生命周期变化”切片后，右侧决策卡不仅 `现在是什么情况` 没有完整抓取第三个候选，后续需求匹配、候选对比和对话输出依据也只按少数候选识别。
- 根因是右侧卡片把展示和候选计算数据源缩窄为 `当前事实作用域`，导致用户原文中用自然语言连续表达的 A/B/C 候选被截断；同时后端强提示模型先判断时间结构，增加了本地模型漏抽事实的概率。

回退：

- 撤回右侧方格决策卡的 `生命周期变化与后验` 展示区。
- 撤回 `currentFactScope / historyFactScope` 对决策卡事实源和候选对比源的切片。
- 恢复右侧决策卡使用完整用户事实源 + 后台资料提炼做候选识别和效用解释。
- 撤回后端资料提炼、决策输出、开放参数抽取中的时间结构强提示，避免干扰基础事实抽取。
- 保留 `v0.5.94 / v0.5.95` 的多候选标记切片与“不按声明数量硬补”规则。
- 微调候选归一化边界，使 `。第三家...`、`，另一家...` 这类中文自然表达也能进入 A/B/C/D 识别。

设计结论：

- 生命周期和贝叶斯后验仍是产品目标，但不能在事实抽取层抢先切断当前候选文本。
- 下一版重新设计时，应先保证“完整事实抽取 -> 候选识别 -> 候选专属参数 -> 整体效用计算”的主链稳定，再添加变化面板。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.94 - 多候选标记切片优先

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户在三 offer 测试中输入了 A/B/C 三家：
  - 大厂平台型阵地。
  - 80 人 AI 应用创业公司。
  - 外企 SaaS 公司。
- 右侧方格决策卡仍只显示 1-2 个候选，导致后续需求匹配、效用计算、成功率解释和对话输出依据都无法覆盖全部候选。
- 根因是候选抽取器先按自然段返回，只要先抓到 A/B 两个候选，就不会进入句子级兜底；当第三个候选被用户写成 `第三家...`、`C是...` 或位于同一段后部时，容易被提前截断。

改动：

- `extractCandidateMap` 新增“候选标记切片优先”流程：
  - 先把 `一个 / 另一家 / 第三家 / 第四家` 归一化为 `A/B/C/D`。
  - 再按 `A/B/C/D` 标记在全文中切片，优先得到每个候选的专属事实文本。
  - 只有标记切片不足时，才继续使用自然段和句子级兜底。
- `splitFactCandidates` 的候选断句从 `A/B` 扩展到 `A/B/C/D`。
- 候选正文会在 `我的真实需求 / 我的底线 / 影响因素 / 请比较` 等共享信息前截断，避免把用户共同约束错误并入最后一个候选。

预期效果：

- 三个或四个候选并列输入时，右侧决策卡 `项目整体情况` 必须显示全部候选。
- 后续候选对比、成功率、效用和谈判依据都应以全部候选为基础，而不是只围绕单一候选计算。
- 最大候选数仍限制为 4，避免算力浪费。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.95 - 多候选禁止按声明数量硬补

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户测试输入写了“现在有三个 offer”，但正文只提供了两家候选的完整事实。
- 系统错误地把“声明有三个”当成候选数量目标，强行补出 Offer C，甚至把历史项目或共享上下文里的事实串入 C。
- 这导致：
  - `项目整体情况` 显示旧候选。
  - 需求匹配、成功率和对话依据出现 A/B/C 串味。
  - 明明只有两家事实，右侧卡却计算三家。

改动：

- `extractCandidateMap` 移除“如果声明数量大于已识别数量，就按段落补齐”的逻辑。
- `有三个 offer / 三家公司` 只作为项目事实，不再作为创建候选对象的依据。
- 只有原文真正出现候选事实段，才会生成对应 Offer A/B/C/D。

设计目的：

- 防止系统为了形式完整而虚构候选。
- 多候选计算必须基于真实出现的候选事实，而不是用户声明数量或旧项目残留。
- 如果用户说有 3 个候选但只写了 2 个，系统应显示 2 个已知候选，并把第三个作为信息缺口，而不是硬算。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.96 - 项目生命周期状态分流

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户指出“从单一当前情况改为全生命周期”后没有做好状态边界。
- 旧逻辑把所有新输入都视为项目记忆追加，导致：
  - 用户重新陈述当前完整情况时，旧候选仍参与当前计算。
  - 三 offer 测试中，历史 C 候选会污染后续只写 A/B 的当前状态。
  - 右侧决策卡额外拼接全部历史用户消息，绕过后台本轮上下文，继续把旧事实带回来。

改动：

- 新增 `isCurrentStateRestatement`：
  - 识别“现在是什么情况 / 当前完整情况 / 以这次为准 / 覆盖之前”等显式信号。
  - 在已有项目里，如果用户重新给出两个及以上候选、身份和当前局面，也视为当前完整情况重述。
- 新增 `ReplacementSnapshot` 语义：
  - 当前输入替代此前候选事实。
  - 历史记忆只用于理解变化过程，不再作为当前候选参与本轮测算。
- `buildProjectContext` 根据输入类型分流：
  - 增量信息：保留相关历史，做生命周期后验更新。
  - 当前完整情况：只用本轮当前事实作为候选计算基准。
- 右侧方格决策卡数据源改为最新一次实际送后台的 `analysisContext`，不再额外拼全部用户历史消息。
- 新增业务流程图和项目状态转换图：
  - 区分 `IncrementalUpdate` 与 `ReplacementSnapshot`。
  - 明确生命周期不是无条件累加全部旧事实。

设计目的：

- 保留长期项目记忆和后验能力。
- 避免旧候选、旧报价或旧条件污染当前状态。
- 让右侧决策卡、后台测算和对话输出使用同一份有效上下文。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.97 - 全上下文时间结构计算

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户指出 `v0.5.96` 只解决了旧候选污染，却可能错误丢掉历史上下文。
- 真正的生命周期计算必须让后台知道：
  - 第一次输入是什么。
  - 第二次输入改变了什么。
  - 当前实际情况是什么。
  - 哪些历史事实仍作为贝叶斯先验、变化证据和履约可信度依据。
- 如果完全丢掉历史，贝叶斯后验和长期项目跟踪就无法成立。

改动：

- `buildProjectContext` 在当前完整情况重述时，不再丢弃历史：
  - 历史输入进入 `【历史输入｜用于贝叶斯先验与变化证据】`。
  - 当前输入进入 `【当前完整情况｜用于判断当前实际候选】`。
  - 增加 `【时间结构规则】`，要求后台基于全部上下文计算。
- 历史候选的角色调整：
  - 不作为当前候选参与本轮候选对比。
  - 仍可作为替代选择、历史变化、偏好变化、承诺稳定性和贝叶斯可信履约证据。
- 右侧方格决策卡：
  - 当前候选展示读取当前事实作用域。
  - 后台分析仍使用完整时间结构上下文。
- 后端提示词同步：
  - `summarySystemPrompt` 明确多次输入的时间结构。
  - `decisionSystemPrompt` 明确历史输入与当前完整情况的优先级关系。
  - 开放参数抽取器明确四理论如何分别使用历史和当前事实。
- 业务流程图和状态转换图更新为：
  - 历史不是删除。
  - 历史进入贝叶斯。
  - 当前完整情况重建当前候选事实。

设计目的：

- 保留项目生命周期、后验更新和贝叶斯可信履约能力。
- 同时避免旧候选作为当前候选污染本轮选择。
- 让“大模型判断当前实际情况”建立在有时间顺序的全上下文之上，而不是无结构拼接。

涉及文件：

- `src/App.tsx`
- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.98 - 每轮输入强制重算与变化展示

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户进一步明确：只要用户有输入，就代表有新信息，必须重新计算一次。
- 生命周期不是只保存文本，而是每一轮都要形成新的计算快照。
- 如果本轮相对上一轮有变化，右侧测试卡必须展示变化，否则用户无法判断新信息如何影响结论。

改动：

- 右侧方格决策卡新增 `5. 生命周期变化与后验`：
  - 展示时间结构：历史输入、当前候选、退出当前比较的历史候选。
  - 展示历史如何进入贝叶斯先验和变化证据。
  - 展示当前排序锚点和签下后兑现参考。
- 新增“本轮计算变化”：
  - 当前成功率：上一轮 -> 本轮。
  - 补强后成功率：上一轮 -> 本轮。
  - 执行后兑现：上一轮 -> 本轮。
  - 对方可信履约：上一轮 -> 本轮。
  - 控制权清晰度：上一轮 -> 本轮。
  - 错配风险：上一轮 -> 本轮。
- `DecisionGridCard` 接收上一轮 `analysis`，用于计算变化幅度。
- 业务流程图和状态转换图新增 `Recalculation` 状态，明确每次输入必重算。

设计目的：

- 让用户看到“新信息改变了什么”，而不是只看到一个新的结论。
- 支撑长期决策和项目跟踪中的后验判断。
- 保持测试面板解释性，同时不暴露原始 JSON、公式和内部提示词。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.93 - 候选计算去除助手回复污染

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户指出不仅第一格漏掉第三家外企 SaaS，后续需求匹配、对比结论、输出依据也只按 1 家公司识别，整体比上一版更差。
- 复查发现候选比较输入仍包含 `latestAssistantMessage`。
- 当本地模型回复只重点提到某家公司时，助手回复会反向污染候选识别，导致原始用户输入里的 A/B/C 被压缩成单候选或少候选。

改动：

- 候选比较和候选拆分只读取用户事实上下文与后台摘要：
  - `latestAnalysisContext`
  - 当前项目全部用户消息
  - `currentInfoSummary`
- `latestAssistantMessage` 只用于提取“对话结论”，不再参与候选识别和候选效用计算。
- 如果文本明确出现 `三个 offer / 三家公司 / 3 个候选`，但实际只写出部分候选，系统只计算已出现的候选；缺失候选作为信息缺口处理，不再硬补。

设计目的：

- 右侧决策卡必须解释对话输出，但不能让对话输出反过来污染后台事实识别。
- 多候选计算必须以用户原始事实为准。
- 防止本地小模型回复遗漏某个候选后，前端后台跟着遗漏候选。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.92 - 候选序号词无“是”识别修复

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户反馈本轮测试比上一版更差，三 offer 仍只能识别两项。
- 查看输入后发现第二个候选写法是 `另一家80人人工智能应用创业公司...`，中间没有 `是/为`。
- 旧归一化只支持 `另一家是...`，导致该段没有被稳定打上 Offer B 前缀。

改动：

- 候选序号词后的 `是/为` 改为可选：
  - `一个是...`、`一个...` 都可识别为 A。
  - `另一家是...`、`另一家...` 都可识别为 B。
  - `第三家是...`、`第三家...` 都可识别为 C。
  - `第四家是...`、`第四家...` 都可识别为 D。

设计目的：

- 匹配用户自然表达，不要求用户用工程格式输入候选。
- 修复多候选自然段解析对中文省略“是”的脆弱性。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.91 - 多候选自然段顺序解析

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户再次反馈三 offer 场景仍只识别到两个候选。
- 旧候选段落解析仍会先把句号、分号切成句子，破坏“一个 offer 一段”的自然结构。
- 对于用户自然输入，候选通常是按自然段排列，而不是每句都有 A/B/C 标签。

改动：

- `extractCandidateMap` 改为自然段优先：
  - 先按空行/换行保留候选段落。
  - 判断段落是否像候选安排。
  - 有显式 A/B/C/D 前缀时按前缀归属。
  - 没有显式前缀时按出现顺序分配 A/B/C/D。
- 只有自然段解析无法形成两个及以上候选时，才回退到句子级识别。

设计目的：

- 用户写“一个是... / 另一家... / C 是...”或“第一家... / 第二家... / 第三家...”时，应稳定识别为多候选。
- 多候选识别应贴近用户自然书写方式，而不是要求用户按工程格式输入。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.90 - 候选段落解析与用户原文优先

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户截图显示三 offer 场景仍只识别到 2 个候选。
- 旧逻辑仍然过度依赖大正则和模型摘要：
  - 模型摘要可能漏掉 C。
  - `另一家` 没有进入 B 的归一化。
  - 候选比较有时拿到的是摘要/最后上下文，不是完整用户原文。

改动：

- 新增候选段落解析器：
  - 先按自然段提取候选事实。
  - 再识别 A/B/C/D 前缀。
  - 段落解析结果优先于旧的大正则抽取。
- `另一家` 补入 Offer B 归一化。
- 右侧决策卡和候选拆分输入源改为：
  - `latestAnalysisContext`
  - 当前项目所有用户消息合集
  - 后台摘要作为补充
- 候选检测、候选正文提取和候选比较优先使用同一份候选段落 Map。

设计目的：

- 多轮对话中，即使模型摘要漏掉某个候选，右侧后台仍能从用户原文中恢复 A/B/C/D。
- 保证项目事实、候选拆分、效用计算使用同一套候选段落事实。
- 降低中文自然表达对候选识别的影响。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.89 - 候选识别归一化进入计算入口

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户指出当前应用仍然无法稳定识别 A 和 C，只识别到 B。
- 根因是 `normalizeCandidateSource()` 只用于第一格项目事实清单，候选比较、候选拆分和测算范围判断仍使用原始文本。
- 结果是右侧事实卡可能看到多个候选，但真正候选计算仍可能只进入显式写成 `B 是...` 的候选。

改动：

- 候选归一化进入所有候选识别关键入口：
  - `optionScopeLabel`
  - `extractCandidateText`
  - `detectedCandidateIds`
  - `textMentionsCandidate`
  - `buildCandidateComparisons`
- 自然语言候选写法统一映射：
  - `一个 / 第一个 / 第一份 / 第一家 / 其一` -> Offer A
  - `第二个 / 第二份 / 另一个 / 其二` -> Offer B
  - `第三个 / 第三份 / 最后一个 / 其三` -> Offer C
  - `第四个 / 第四份 / 其四` -> Offer D

设计目的：

- 事实展示、候选拆分和候选效用计算必须使用同一套候选识别规则。
- 多 offer 场景中，不能因为用户没有显式写 `A 是` 就丢掉第一个候选。
- 保证 A/B/C/D 最多四候选比较在前端后台测试卡、候选拆分和对话输出依据中一致。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.88 - 本地测试静态资源禁用长缓存

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户截图仍显示旧标题 `现在是什么情况`，但构建产物中已经更新为 `项目整体情况`。
- 原因是服务端对 `dist/assets` 使用长期缓存策略，适合线上部署，但本地高频测试会导致浏览器继续使用旧 JS/CSS。

改动：

- 静态资源缓存策略调整：
  - 本地测试默认 `no-store`。
  - 仅当 `NODE_ENV=production` 且 `APP_RELEASE_CHANNEL` 不是 `local` 时，assets 才使用长期缓存。

设计目的：

- 本地测试时刷新页面即可拿到最新前端包。
- 保留线上正式部署时的长缓存能力。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.87 - 决策卡事实区滚动展示

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户截图显示右侧第一格在多候选长事实下仍然容易看不全。
- 方格卡使用 2x2 等高排版时，第一格与第二格共享行高，长事实可能被视觉截断或不易阅读。

改动：

- 方格决策卡第一格 `项目整体情况` 增加内部最大高度和纵向滚动。
- 第一格内每条事实增加轻分隔线，便于区分用户背景、Offer A、Offer B、Offer C、Offer D。

设计目的：

- 保留方格记事本结构，同时避免多候选事实被卡片版式压缩。
- 第一格只负责讲清项目事实，详细分析仍以自然语言对话和后续格子为准。

涉及文件：

- `src/App.css`
- `docs/DESIGN.md`

### v0.5.86 - 项目事实清单候选化提取

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户指出右侧方格决策卡第一格虽然改为项目整体情况，但事实仍然提取不清楚：
  - 三候选场景只显示 A/B，漏掉 C。
  - `一个是一家大厂...` 这类自然写法没有被稳定识别为 Offer A。
  - `城市是` 这类残缺字段被原样展示。
  - 第一格过度依赖本地模型资料摘要，导致事实丢失或不准确。

改动：

- 第一格 `项目整体情况` 改为优先从累计项目原文中抽取：
  - 用户/项目背景。
  - Offer A/B/C/D 候选事实。
- 支持将 `一个是 / 第一个 / 第一份 / 第一家` 归一为 Offer A，便于自然语言输入进入候选拆分。
- 过滤明显残缺字段，例如 `城市是`。
- 第一格不再只显示前三条，最多展示 6 条，以覆盖用户背景 + 4 个候选。
- 本地模型摘要仍作为兜底，但不再作为候选事实展示的唯一来源。

设计目的：

- 方格决策卡第一格必须先把“当前项目到底有哪些事实”讲清楚。
- 多候选场景中，候选事实不应因为模型摘要漏写而丢失。
- 右侧后台卡是解释计算依据的测试视图，事实不准确会直接破坏后续需求匹配、效用计算和谈判建议可信度。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.85 - 决策卡项目整体情况修复

日期：2026-06-28

状态：

- 本地测试中。

背景：

- 用户指出右侧方格决策卡第一格仍在展示“当前这一轮输入”，例如用户追问“就 B 的情况给我具体谈判策略”时，第一格会把这句追问当成“现在的情况”。
- 这会偏离项目记忆设计：每次新信息加入后，后台应基于整个项目累计资料重新验算，决策卡也应展示整个项目的整体情况，而不是最后一句话。

改动：

- 方格决策卡第一格标题从 `现在是什么情况` 改为 `项目整体情况`。
- 第一格事实来源改为优先读取后台返回的累计资料摘要 `debug.currentInfoSummary`。
- 只有当累计资料摘要为空时，才回退到最新用户输入做兜底提取。
- 英文标题同步从 `Situation` 改为 `Overall Project Context`。

设计目的：

- 决策卡是后台测试视图，应解释“整个项目累计状态下为什么这样判断”，而不是复述当前轮追问。
- 多轮对话中，用户每补充一项信息，都应该影响全量效用与候选对比，并在右侧卡片中反映为项目整体情况更新。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.84 - 多轮候选重算上下文修复

日期：2026-06-28

状态：

- 本地测试中，待用户确认后再决定是否部署线上。

背景：

- 用户指出三候选项目在第二轮补充新信息时，右侧后台会退化成单一候选。
- 根因是前端虽然把累计项目上下文送去后台验算，但项目记忆只保存了本轮新增文本；右侧决策卡和候选拆分又用“最后一句用户消息”重建候选比较。
- 当最新一轮只提到 B 或 C 时，右侧卡片只能看到单候选，无法展示 A/B/C 在新信息后的重新计算结果。

改动：

- `ProjectMemoryEntry` 新增 `analysisContext` 字段，保存本轮实际送入后台的累计项目上下文：
  - 历史轮次信息。
  - 本次新增信息。
- 右侧候选拆分和方格决策卡不再只用 `latestUserMessage`，改为优先使用 `latestMemory.analysisContext`。
- `/api/decision-pack` 返回 `debug.currentInfoSummary` 与 `debug.summary`，便于右侧后台展示本轮资料提炼和测算摘要。

设计目的：

- 多轮对话中，每次新信息都应触发“项目累计事实”的重新抽取、重新验算和重新展示。
- 三候选/四候选结构必须跨轮保留，不能因为用户最新一句只补充某个候选而丢掉其他候选。
- 右侧后台应展示“最新累计计算结果”，而不是“最后一句话的孤立计算结果”。

涉及文件：

- `src/App.tsx`
- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.83 - 报价追问与本地模型错词修正

日期：2026-06-28

状态：

- 本地测试中，待用户确认后再决定是否部署线上。

背景：

- 多轮 offer 测试中，用户追问“B 要加多少、我应该叫价多少”时，回复仍偏泛化，没有稳定输出明确的开价、成交区间和底线。
- 本地模型出现若干机器翻译腔或错词，例如“较高%期权”“爱情承诺”“伊丽莎白拒绝”等，影响可信度。
- 后处理规则曾把 `0.xxx` 一律替换为“较高”，导致 `0.5%期权` 这种关键事实被错误改写。

改动：

- 删除 `0.xxx -> 较高` 的通用替换规则，保留期权比例、概率、小数等关键数字。
- 增加用户追问具体报价/加价/叫价时的输出约束：
  - 建议开价。
  - 合理成交区间。
  - 最低可接受底线。
  - 低于底线时必须换到的非现金条件。
  - 一句话谈判话术。
- 增加本地模型常见错词清理：
  - “爱情承诺”修正为“口头承诺”。
  - “金字塔”修正为“立场”。
  - “万人接触AI产品”修正为“接触 AI 产品”。
  - “传承路径”修正为“晋升路径”。
  - “伊丽莎白拒绝”修正为“礼貌拒绝”。

设计目的：

- 让“继续追问价格/条件”的多轮对话更像真实谈判辅助，而不是重新泛泛分析。
- 保留原文数字事实，避免破坏用户对计算和建议的信任。
- 降低本地小模型的语言污染，让输出更接近商业可用表达。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.82 - 测试后台三栏布局恢复

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出开启右侧测试后台后，左侧产品介绍、注册/登录和合规说明全部消失。
- 测试后台的目的只是展示决策卡，不应破坏基础产品入口和账号入口。

改动：

- `showDebugPanel` 开启时不再移除左侧 `product-panel`。
- 桌面端恢复为三栏：
  - 左侧：产品介绍、项目状态、模型选择、账号/注册登录、合规边界。
  - 中间：对话机器人。
  - 右侧：方格记事本式决策卡测试后台。
- 窄屏/手机端改为垂直排列：
  - 产品/账号区在上。
  - 对话区在中。
  - 决策卡在下。
- 保留登录后手机端收缩部分产品说明的规则，但不再完全移除账号和合规入口。

设计目的：

- 让测试后台与正式产品入口并存。
- 避免用户测试时找不到注册、登录、产品说明或合规说明。
- 保持“聊天机器人 + 右侧后台卡”的测试形态，同时恢复商业产品基础布局。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.81 - 候选说明全要素化

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出多候选比较中 A / B / C 虽然分开列示，但“主要价值 / 主要代价”仍像同一套说辞。
- 这会让用户看不出每个候选为什么被这样排序，也无法理解候选的专属契约价值和风险。

改动：

- 多候选比较在每个候选独立验算时，同步生成候选专属的：
  - `valueSummary`：该候选能给用户的主要价值。
  - `riskSummary`：该候选带来的主要代价或风险。
- `valueSummary / riskSummary` 不再只按粗关键词模板生成，而是综合：
  - 候选自身文本。
  - 统一背景中的用户需求和约束。
  - 该候选专属开放参数。
  - 该候选独立契约验算结果。
- 决策卡第 2 格 `双方需求是否匹配` 和第 4 格 `对话输出依据` 统一读取候选专属摘要，避免 A/B/C 复用同一套说明。

设计目的：

- 让候选 A/B/C/D 的解释跟随各自事实和参数变化。
- 让“为什么优先 A、为什么 B 需要谈、为什么 C 排在某位置”在右侧后台卡片中能看懂。
- 保持全局需求画像与候选专属效用的边界：用户需求是统一背景，候选价值/风险是分别验算。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.80 - 多候选输出依据全量列示

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出第 4 格在多候选场景中只解释了领先候选和第二候选，导致中间候选（例如 B）消失。
- 一对多比较必须展示所有候选为什么排在当前位置，否则用户无法理解完整排序。

改动：

- 多候选场景下，第 4 格 `对话输出依据` 改为逐个候选列示，最多 4 个：
  - 当前成功率。
  - 我方效用。
  - 共同剩余。
  - 主要价值。
  - 主要代价。
  - 是否被优先考虑或需要补强短板。
- 保留顶部“当前领先候选”的说明，但不再只解释领先候选和第二候选。

设计目的：

- 确保 A/B/C/D 所有候选都被解释。
- 让用户理解完整排序，而不是只看到部分比较。
- 避免右侧卡片和真实候选数量不一致。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.79 - 对话输出依据案例化

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出方格决策卡第四格 `对话输出依据` 仍是知识解析和方法说明，没有结合当前实例解释为什么这样回复。
- 该格应解释“当前对话输出为什么是这个建议”，而不是复述系统如何一般性判断。

改动：

- 多候选场景下，第四格改为案例依据：
  - 当前领先候选是谁。
  - 领先候选的当前成功率、我方效用和共同剩余。
  - 领先候选能给用户的具体价值。
  - 领先候选的具体代价和为什么不能无条件接受。
  - 第二候选在什么风险补强后可能改变结论。
- 单候选场景下，第四格改为当前安排依据：
  - 当前成功率、优化后成功率和兑现概率。
  - 当前安排对应的用户真实需求。
  - 当前控制权风险和可信履约证据。
- 保留控制权和可信履约，但改为“本案控制权风险”“本案可信履约”，不再像通用理论说明。

设计目的：

- 让右侧方格卡解释左侧对话输出，而不是讲产品方法论。
- 让用户看到“为什么这次会这样建议”，提升产品可信度。
- 避免模板化和理论化。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.78 - 双方需求匹配格详解

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出方格决策卡第二格 `双方需求是否匹配` 太简单，只显示核心诉求、对方效用和共同剩余，无法说明为什么匹配或不匹配。
- 原始设计要求先挖用户真实需求，也要看对方真实需求和双方交换是否互补。

改动：

- 多候选场景下，第二格从字段摘要升级为候选逐项解释：
  - 用户核心取舍。
  - 每个候选能给用户的主要价值。
  - 每个候选需要用户承担的主要代价。
  - 候选方可能想从用户这里换到什么。
- 单候选场景下，第二格补充交换关系：
  - 用户要的是可持续收益和底线安全。
  - 对方要的是能力、资源、付款、执行或长期配合。
  - 只有双方都能拿到真实需要的东西，才有继续谈的基础。
- 修正 `不能接受会决定先保什么` 这类不自然表达，改为“已经出现不可接受项，后续判断要先保底线，再谈收益”。

设计目的：

- 让需求匹配格真正解释“为什么这个安排适合/不适合”。
- 避免决策卡退化成后台字段摘要。
- 保持契约理论中的双边需求匹配，而不是单边用户画像。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.77 - 统一背景因素池标识

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户在多候选测试中看到 `用户最核心需求 / base / 需求画像` 等字段，无法判断这是三家公司分别结果，还是统一用户背景。
- 该板块实际含义是同一个用户、同一市场和同一决策背景下的共同约束，应共同进入每个候选计算，但不是某个候选的专属结果。

改动：

- 右侧测试后台将 `全因素矩阵（整体，不按候选拆分）` 改名为：
  - `统一背景因素池（不是候选分别结果）`
- 多候选场景下增加说明：
  - 这里主要是同一个用户、同一市场和同一决策背景下的共同约束。
  - 它会共同进入每个候选的计算。
  - 候选专属依据应看上方 `候选者当前条件拆分`。
- 前台展示中将工程来源 `base` 显示为 `统一背景`，避免暴露内部字段并降低误解。

设计目的：

- 明确区分“统一背景因素”和“候选专属参数”。
- 避免用户把共同需求、底线、市场条件误读成某一个候选的单独评分。
- 继续保持候选对比结果可解释。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.76 - 多候选标记识别增强

日期：2026-06-26

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户测试发现实际存在多个候选时，应用仍按单候选处理。
- 原因是候选检测和候选正文抽取规则不一致：例如 `A 是... / B 是...`、`方案1：... / 方案2：...` 这类写法可能被检测到候选标记，但正文抽取失败，最终退回单候选。

改动：

- 统一候选检测与正文抽取规则。
- 最多支持 4 个候选，内部映射为：
  - `A / 1 / 一`
  - `B / 2 / 二`
  - `C / 3 / 三`
  - `D / 4 / 四`
- 支持常见候选写法：
  - `Offer A: ...`
  - `A 是 ...`
  - `方案1：...`
  - `候选一：...`
  - `买家2：...`
  - `供应商三：...`
- 仍然坚持只有两个及以上有效候选时才进入候选对比。

设计目的：

- 让一对多候选识别更贴近用户自然输入。
- 避免明明有多个候选却退回单候选。
- 保持最多 4 个候选的算力上限。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.75 - 最多四候选比较上限

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户提出真实场景可能存在 3 个、4 个候选，但不希望无限开放候选数量。
- 为保证计算精准、避免算力浪费和输出失控，多候选比较需要设置明确上限。

改动：

- 多候选比较支持 `A/B/C/D`，最多 4 个候选。
- 只有检测到两个及以上有效候选时，才进入候选对比。
- 1 个候选仍按当前安排整体验算。
- 右侧测试后台文案说明：
  - “最多支持 4 个候选，避免算力浪费。”
- 候选调试行从 A/B 专用改为 A/B/C/D 通用。

设计目的：

- 覆盖常见的二选一、三选一、四选一场景。
- 保证候选参数切分的准确性。
- 控制本地模型和 API 调用成本。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.74 - 单候选与多候选验算边界

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出现实中不一定总是 A/B 多候选，也可能只有一个 offer、一个买家、一个合作对象或一份待签安排。
- 如果只有一个候选，不能强行拆成 A/B 对比；否则会制造不存在的对象，导致测试后台和决策卡误导用户。
- 用户进一步明确：多候选时仍应使用全体效用模型，但为每个候选导入“共享背景 + 该候选专属参数”，而不是把候选完全割裂成孤立案例。

改动：

- 候选拆分触发条件收紧：
  - 只有识别到两个及以上有效候选时，才展示候选者当前条件对比。
  - 只有一个候选时，回到“当前这份安排”的整体验算和单组成功率。
- 候选验算上下文调整为：
  - 共享背景：用户约束、需求、家庭压力、时间、市场、城市、技能、加班、考核等共同信息。
  - 专属参数：只属于当前候选的薪酬、岗位、现金流、期权、控制权、履约信号等。
  - 排除项：其他候选的专属事实和开放参数。
- 决策卡测算范围说明同步调整：
  - 多候选显示整体比较。
  - 单候选显示当前安排整体验算。

设计目的：

- 保持契约决策模型的全体效用视角。
- 多候选时比较“同一用户/同一市场背景下，不同对象带来的效用差异”。
- 单候选时避免虚构对比对象，保持当前安排判断清晰。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.73 - 候选效用独立验算

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出上一版虽然把 A/B 展示分开了，但底层效用计算仍然沿用整体 `analysis`，没有真正分别计算 A 和 B。
- 一对多场景的商业价值在于比较每个候选契约本身，而不是把整体局势套到每个候选上。

改动：

- 候选拆分从“整体计算 + 候选修正”升级为“候选事实独立验算”：
  - Offer A 使用 `A 的事实 + 用户共享约束 + A 专属开放参数` 单独调用全量契约引擎。
  - Offer B 使用 `B 的事实 + 用户共享约束 + B 专属开放参数` 单独调用全量契约引擎。
- 每个候选现在拥有独立的：
  - 当前条件成功率。
  - 补强条件后成功率。
  - 签下后兑现概率。
  - 我方效用。
  - 对方效用。
  - 共同剩余。
  - 匹配均衡。
  - 双赢概率。
  - 错配风险。
- 右侧候选拆分面板展示上述独立验算结果。
- 方格决策卡候选卡也展示候选专属的我方效用、对方效用和共同剩余。

设计目的：

- 真正支持一对多候选契约比较。
- 避免把整体概率误当作 A 或 B 的单独概率。
- 让“当前条件候选对比”成为可解释、可测试、可迭代的后台计算结果。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.72 - 候选后台拆分与需求标签自然化

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出右侧决策卡出现“你这边要保护的是：短期/长期时间视角”这类后台字段，普通用户无法理解。
- 用户指出开放参数抽取、结果分布、成功概率、控制权、贝叶斯和全因素矩阵仍是整体输出，没有拆分 A/B，导致一对多场景下无法判断指标到底属于哪个候选。

改动：

- 决策卡“双方需求是否匹配”不再直接展示后台因子标签：
  - `短期/长期时间视角` 改为“你的时间取舍：既看长期结果，也在意眼前条件”等自然语言。
  - `现实约束/最低底线` 改为“你的硬底线：……不能被机会感冲掉”等用户可读句。
  - `需求优先级/取舍顺序`、`能力/兴趣/资源匹配` 同样转为自然表达。
- 右侧测试后台新增 `候选者当前条件拆分`：
  - A/B 分别展示当前条件、补强条件后、签下后兑现。
  - A/B 分别展示只属于该候选的开放参数和证据。
- 原有全局区块在多候选场景下显式标注为整体局势：
  - `开放参数抽取（整体局势）`
  - `结果概率分布（整体局势）`
  - `成功概率公式面板（整体局势）`
  - `控制权配置（整体局势）`
  - `贝叶斯可信履约指数（整体局势）`
  - `全因素矩阵（整体，不按候选拆分）`

设计目的：

- 面向用户的决策卡必须说人话，不能暴露工程标签。
- 一对多测试时，先看候选拆分，再看整体局势，避免把整体矩阵误读成某个候选的单独结论。
- 保留后台调试能力，但降低信息误读和逆向工程风险。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.71 - 当前条件候选对比优先

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户进一步指出，一对多场景不能只展示一个整体胜率，也不能把“当前、优化后、兑现”混成同等重要。
- 用户真正需要的是先看到“各个候选者在当前条件下谁更值得选”，再看通过谈判或补强条件后是否会改变判断。

改动：

- 决策卡在识别到 A/B、多 offer、多候选安排时，第三格优先展示“当前条件候选对比”。
- 候选卡按当前条件胜率降序排列，并直接标出“当前条件更占优”的候选方。
- “优化后”和“兑现”保留为辅助信息，用于解释谈判补强价值和签下后的落地风险，不再替代当前选择判断。
- 候选拆分测算只使用该候选自身事实与用户共享约束，避免 A/B 材料互相污染，导致 A 厂、B 厂的判断依据混在一起。

设计目的：

- 一对多不是一个抽象总分，而是多个候选契约的市场比较。
- 决策卡必须服务于用户当下选择：先回答“现在谁更优”，再回答“谈完以后是否可能变化”。
- 保持右侧后台卡片作为对话输出依据，而不是替代对话回复。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.70 - 一对多候选胜率拆分

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出一对多场景不能只给一个胜率。
- 多个 offer、买家、供应商或合作方虽然属于市场情况，但用户最终需要看到每个候选契约各自的当前成功率、优化后成功率和兑现概率，否则无法比较。

改动：

- 决策卡在识别到 A/B、多候选、多 offer 等场景时，第三格显示候选对比卡：
  - Offer A / A方：当前、优化后、兑现。
  - Offer B / B方：当前、优化后、兑现。
  - 每个候选附带影响该候选结果的主要原因。
- 单一交易、合作、签约、项目去留场景仍显示一组整体三段胜率。
- 多候选说明从“整体对比测算”进一步细化为：
  - 整体测算解释当前局势。
  - 候选拆分解释各候选契约的相对可行性和兑现风险。

设计目的：

- 保持“一对多也是契约市场情况”的原始原则。
- 同时满足用户做具体选择时必须看到候选方逐一对比的需求。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.69 - 决策卡测算范围自适应

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出右侧决策卡中的三段胜率和结果分布没有说明到底指 A 厂、B 厂还是整体对比。
- 同时不能把 A/B 写死，否则买卖、合伙、外包、单一 offer 等其他场景会失去适用性。

改动：

- 决策卡第三格从 `为什么这样判断` 改为 `对比结论依据 / Comparison Basis`。
- 新增测算范围说明：
  - 如果用户资料中出现 A/B、两个、多家、多个、二选一、候选等多方案线索，显示为“多个候选安排的整体对比测算，不是单独给某一个对象打分”。
  - 如果是单一交易、合作、签约或关系安排，显示为“当前这份安排的整体测算，用来解释对话回复为什么这样判断”。
- 决策卡会提取左侧对话中的结论句作为“对话结论”，再用后台结果分布、三段胜率、控制权和可信履约解释该结论的依据。

设计目的：

- 让右侧决策卡解释左侧对话的判断依据，而不是另生成一套结论。
- 保持多方案和单一契约场景都可用。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.68 - 右侧方格决策卡与敏感调试隐藏

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户明确“后台”指右侧决策卡，而不是工程调试面板。
- 用户希望右侧保留方格记事本式决策依据，但隐藏关键的公司 JSON 输入、系统提示词、公式和最终大模型输入，避免产品逻辑被轻易逆向。

改动：

- 左侧对话区移除结构化决策卡入口，避免对话区重复展示。
- 右侧测试面板顶部直接展示方格决策卡：
  - 当前事实。
  - 双方需求匹配。
  - 后台判断依据。
  - 对话输出依据。
- 右侧隐藏敏感工程内容：
  - 不再展示三大理论公式原文。
  - 不再展示系统提示词。
  - 不再展示最终用户消息/prompt。
  - 不再展示大模型输入摘要 JSON。
- 保留非敏感测试材料：
  - 项目记忆。
  - 核心判定。
  - 结果概率分布。
  - 三段成功率。
  - 控制权配置。
  - 可信履约指数。
  - 全因素矩阵。

设计目的：

- 让测试阶段仍能看到“为什么这样输出”的依据。
- 避免把内部公式、提示词和 JSON 结构暴露给普通用户或竞品。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.67 - 线下测试后台默认打开

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户当前处于线下测试阶段，需要像早期版本一样同时看到右侧后台计算和思考过程。
- 构建后的本地服务不属于 `import.meta.env.DEV`，导致测试后台默认隐藏。

改动：

- 测试后台显示规则改为：
  - 默认显示后台测试面板。
  - 只有显式设置 `VITE_SHOW_DEBUG_PANEL=false` 时才关闭。
- 便于本地测试时同时观察：
  - 对话自然语言输出。
  - 当前资料提炼。
  - 后台计算结果。
  - 模型输入与决策依据。

设计目的：

- 当前阶段优先服务产品调试和输出质量校准。
- 后续上线版本可通过构建环境变量关闭后台面板。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.66 - 决策卡收起式辅助面板

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出决策卡被放在对话区和输入框之间，体积过大，挡住对话且无法移动、下拉或收起。
- 用户指出决策卡与对话输出容易重复甚至产生不一致感，卡片不应抢占主输出位置。

改动：

- 决策卡移动回对话滚动区内部，作为对话内容后的辅助面板。
- 决策卡外层改为默认收起的抽屉：
  - 用户点击 `查看结构化决策卡` 才展开。
  - 收起状态只显示入口和后台分数。
  - 不再固定占用输入框上方空间。
- 决策卡标题从结论型文案改为 `结构化测算参考`：
  - 避免和自然语言对话中的最终建议冲突。
  - 完整结论、原因、话术仍以对话回复为准。
- 决策卡事实展示新增用户原文兜底：
  - 如果摘要模型未给出足够事实句，前端从最近一条用户消息中提取事实。

设计目的：

- 保持“对话为主、卡片为辅”的产品体验。
- 让卡片可查看、可收起，不打断用户继续对话。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.65 - 对话为主、决策卡为辅

日期：2026-06-25

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出决策卡内部下拉不适合作为主输出，信息仍然不够直观。
- 原始产品不是把对话回复替换成卡片，而是在原来的对话方式上增加结构化决策卡。
- 用户需要先读自然语言分析，再用决策卡快速扫一眼当前事实、需求匹配、判断和行动。

改动：

- 决策卡恢复为辅助总览卡：
  - 不再在卡片内部承载完整说明。
  - 不再使用卡内下拉作为主阅读方式。
  - 只展示当前资料、双方需求匹配、核心判断、三段成功率和行动摘要。
- 完整原因、逐条解释、谈判话术和让步逻辑继续由原来的对话回复承担。
- 卡片副标题明确提示：
  - `这是结构化总览，完整分析、原因和话术以对话回复为准。`

设计目的：

- 保持聊天机器人式自然解释，不让产品变成只有仪表盘。
- 让结构化卡片服务于扫读和复盘，而不是替代完整决策建议。

涉及文件：

- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.64 - 方格卡真实事实与测算结果下拉

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出 `月薪比现在低30%` 这类带数字和比例的内容是关键事实，不能因为没有句号或长度较短就被过滤掉。
- 用户指出方格卡本身没有下拉，用户看不到每格全貌；而卡片下方展开区混入了固定说明话术，不是模型输出或后台测算结果。

改动：

- 方格卡事实提取改为保留短事实句：
  - 保留数字、比例、金额、期限、期权、现金流、薪资变化等关键事实。
  - 继续过滤纯关键词和过短标签，但不再误删 `低30%`、`2%期权`、`12个月现金流` 等事实。
- 后端全要素提炼提示新增硬性要求：
  - 必须输出完整事实句。
  - 必须保留数字、比例、金额、期限、期权比例、现金流、降薪/涨薪幅度、付款时间、交付范围、控制权、退出条件。
  - 禁止把事实压缩成关键词列表。
- 方格卡四个格子改为可展开下拉卡片：
  - `现在是什么情况`
  - `双方需求是否匹配`
  - `为什么这样判断`
  - `怎么谈 / 怎么退`
- 移除前台固定教学话术，卡片内容只展示：
  - 大模型提炼的当前资料。
  - 后台测算出的双方收益、共同剩余、替代选择压力。
  - 后台测算出的结果分布、控制权、可信履约和三段成功率。
  - 后台生成的谈判/让步/退出策略。

设计目的：

- 避免前台看起来像模板话术或测试说明。
- 让用户在方格卡内直接看到真实事实、测算结果和执行策略的完整链路。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.63 - 方格卡事实句与下拉详解修正

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出方格卡中的“事实”展示成了 `收入`、`稳定`、`不能接受` 等关键词，用户无法理解这些词如何支撑判断。
- 用户指出详尽解释区被全部展开，页面信息过载；原来需要有下拉框，用户需要时再展开查看因果逻辑。

改动：

- 方格卡“现在是什么情况”只展示完整事实句：
  - 优先展示大模型整理出的当前资料摘要。
  - 不再把后台证据词、关键词或短标签直接当成事实展示。
  - 如果当前资料不足以形成事实句，前台明确说明“当前资料还没有形成可展示的完整事实句”。
- `决策原因说明` 改为可展开的下拉详解：
  - 卡片保留重要信息。
  - 下拉区承载逐条判断方法、因果关系和使用方式。
  - 避免一屏同时铺开所有解释，降低阅读压力。
- 保留原始设计要求的四段链路：
  - 现在的情况。
  - 双方需求是否匹配。
  - 为什么这样判断。
  - 怎么谈 / 怎么退。

设计目的：

- 让用户先看懂“已知事实”和“当前结论”，再按需展开查看为什么。
- 保持方格记事本式结构，同时避免卡片省略到用户看不懂。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.62 - 双方需求匹配纠偏

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出方格卡只写“你真正要什么”，忽略了“对方真正要什么”，偏离最初设计中的双边匹配均衡。
- 原始设计要求判断双方是否有合作基础，核心变量包括我方效用、对方效用、双方总剩余、替代选择压力和匹配均衡。

改动：

- 决策输出提示从“用户需求匹配”改为“双方需求匹配”：
  - 用户真正想要什么。
  - 对方真正想要什么。
  - 用户能给对方什么。
  - 对方能给用户什么。
  - 双方交换是否互补。
- 方格决策卡第二格改为 `双方需求是否匹配`。
- 卡片和解释区同时展示：
  - 我方需求。
  - 对方可能需求。
  - 双方共同剩余。
  - 替代选择压力。

设计目的：

- 回到契约理论底层，而不是单边用户画像。
- 防止应用退化成普通个人决策建议。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.61 - 方格卡与详尽解释分层

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出决策卡需要解释“为什么这样判断”，但如果所有因果说明都塞进方格里，会导致卡片过密、排版困难。
- 方格卡应负责结构化扫读，详细文字应负责解释因果逻辑。

改动：

- 方格决策卡只保留重要信息：
  - 当前情况摘要。
  - 真实需求摘要。
  - 当前结论与三段成功率。
  - 谈判作战卡核心项。
- 卡片下方新增 `决策原因说明`：
  - 逐条解释每一部分怎么判断。
  - 展示判断方法、因果关系和使用方式。
  - 保留谈判/让步/退出的完整解释。

设计目的：

- 同时满足“结构化呈现”和“详尽解释”。
- 避免卡片过小导致用户看不懂，也避免输出退回长篇散文。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.60 - 方格页自解释文案

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 方格页已有结构，但部分格子使用省略式字段名和“强/中/弱”短标签，普通用户不容易理解每格是什么意思。
- 方格记事本式页面必须像工作纸，而不是后台字段面板。

改动：

- 每个格子增加解释句，说明该格的用途：
  - 事实格说明“这里只摆已知材料，不是结论”。
  - 需求格说明“这里判断用户真正想要什么和取舍顺序”。
  - 匹配格说明“这里判断安排是否匹配用户需求”。
  - 风险格说明“这里判断控制权、下行风险和兑现能力”。
  - 成功率格说明三段成功率各自含义。
  - 退出格说明何时暂停或退出。
- 将 `标签：强/中/弱` 改成完整判断句，例如“某项比较充分，是加分项”“某项偏弱，容易影响最终判断”。

设计目的：

- 让结构化页面无需解释也能被用户读懂。
- 避免产品看起来像测试后台或工程字段展示。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.59 - 需求匹配与谈判执行并行交付

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 连续测试发现模型容易在“需求匹配”和“谈判策略”之间摆动：
  - 强调谈判时，真实需求和匹配判断变弱。
  - 强调需求匹配时，谈判、让步和退出执行又消失。
- 原始设计要求二者不是二选一，而是完整链路中的两个必交付部分。

改动：

- 决策输出提示改为两条主线并行：
  - 需求匹配线：用户真正想要什么、当前安排满足什么、牺牲什么、是否匹配短期/长期目标和现实底线。
  - 谈判执行线：开局条件、第一轮让步、第二轮让步交换条件、不能让的底线、暂停/退出触发点。
- 明确要求：
  - 需求匹配和谈判执行必须分别出现，不能只写其中一边。
  - 如果结论是继续推进，输出谈判和让步策略。
  - 如果结论是不推进或暂缓，也必须输出为什么暂不谈、先补什么条件或如何退出。
- 保留“谈判是决策的产物，不是默认入口”的原则，但执行方案不能缺席。

设计目的：

- 固化产品的完整交付链路，避免提示词权重变化导致顾此失彼。
- 让应用输出稳定区别于普通 GPT 作文：先判断需求匹配，再给可执行策略。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.58 - 方格页补回谈判作战卡

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- v0.5.57 将输出改为方格记事本式结构化页面，但右栏只保留行动结论、成功率和下一步，弱化了原始设计中的第二核心价值：如何谈、如何让、让到哪里停。
- 原始设计要求：先生成契约判断；只有判断指向继续推进且存在可协商对象时，才生成谈判策略和让步策略。

改动：

- 方格决策页右栏从单纯“行动”升级为：
  - 当前结论。
  - 三段成功率。
  - 谈判/让步作战卡。
  - 暂停/退出触发。
- 谈判作战卡结构：
  - 开局条件。
  - 第一轮让步。
  - 第二轮让步交换条件。
  - 不能让的底线。
  - 暂停/退出。
- 谈判内容由后台成功率、让步增益/成本、控制权和可信履约结果生成，不改变核心算法。

设计目的：

- 保持方格记事本结构，同时不丢掉契约决策 AI 的“实现最优解”的执行价值。
- 避免结构化页面退化成普通摘要页。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.57 - 方格记事本式结构化决策页

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户指出产品不应只和 GPT 拼一段回答，而应把契约决策的结构化优势展示出来。
- 参考“方格记事本”的记录逻辑，把复杂信息拆成可扫读的工作纸，而不是长篇作文。

改动：

- 前端新增 `方格决策页 / Grid Decision Page`：
  - 左栏：事实，展示已知材料和真实需求。
  - 中栏：解释，展示契约匹配、市场因素、风险与控制权。
  - 右栏：行动，展示当前结论、三段成功率和下一步。
- 决策页复用已有后台 `ContractAnalysis`，不改变算法和接口。
- 对话仍保留，但结构化决策页会在有分析结果后显示在对话区内。
- 移动端自动改成纵向三段，保证手机可读。

设计目的：

- 把产品从“聊天机器人”推进到“契约决策工作纸”。
- 让后台计算、需求匹配、控制权、成功率和行动建议成为可见产品价值。
- 降低用户直接拿 GPT 文笔对比的风险。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.56 - 需求匹配后的输出质量与术语稳定

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- v0.5.55 补回了“需求匹配 -> 契约判断 -> 谈判策略”的完整链路，但本地模型在复杂 offer 场景中出现了机器翻译腔和错词，例如“抄录费”“选项”“边境电商”等。
- 输出结构已经接近目标，但专业感、自然度和条款建议的现实性仍需收敛。

改动：

- 决策系统提示词新增中文质量约束：
  - 专业但接地气，避免机器翻译腔。
  - 期权统一说“期权”，现金补偿统一说“签约奖金、保底补偿、里程碑奖金或差额补贴”。
  - 不使用“抄录费”“选项”“边境电商”“归属责任”“现金不平等”等不自然说法。
  - 不给过度激进或明显不现实的条款建议。
  - 涉及期权、股权、劳动合同和法律效力时，只提醒书面确认并找专业人士复核，不输出法律结论。
- `sanitizeUserFacingReply` 增加本地模型常见错词清洗：
  - `边境电商 -> 跨境电商`
  - `选项 -> 期权`
  - `抄录费 -> 签约奖金`
  - `权利责 -> 权责`
  - 其他明显机器翻译错词替换。

设计目的：

- 保留需求匹配和谈判策略的完整链路，同时提升真实用户看到的专业感。
- 降低本地模型语言质量波动对产品价值的影响。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.55 - 需求匹配与谈判策略的步骤化合流

日期：2026-06-24

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- v0.5.54 恢复了谈判策略与让步阶梯，但测试发现输出重心容易过度转向谈判执行，削弱了 v0.5.0 的“需求画像优先决策”。
- 原始产品定位要求：先挖真实需求，再判断契约匹配，最后才决定是否需要谈判和让步。

改动：

- 服务端给大模型的后台摘要新增 `需求画像`：
  - 已识别的用户需求线索。
  - 仍不清楚的需求画像要素。
  - 明确提示先做需求匹配，不要直接跳到谈判。
- 决策输出提示改为完整步骤：
  - 先识别用户身份和立场。
  - 再判断用户真正想要什么、最怕失去什么、短期/长期哪个更重要。
  - 再判断当前安排或候选契约是否匹配这些需求。
  - 再解释收益、风险、控制权、可信履约和三段成功率。
  - 再给明确结论。
  - 只有当结论指向继续推进且存在对手方和可交换条件时，才输出谈判与让步策略。
- 保留结尾固定提醒：
  - 如果后续有遗漏信息、对方新回复或条款变化，可以继续告诉我，我会按最新情况重新判断。

设计目的：

- 防止系统在“需求匹配”和“谈判策略”之间顾此失彼。
- 保持契约决策 AI 的完整链路：需求画像 -> 契约匹配 -> 风险控制 -> 明确结论 -> 条件谈判/让步执行。
- 避免把所有问题默认处理成谈判问题，也避免退回普通利弊分析。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.54 - 谈判策略与让步阶梯回归

日期：2026-06-23

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- 用户测试发现新版输出重心偏向“判断是否值得”，弱化了原始产品的第二核心价值：为了达成最优解，如何谈判、如何让步、让到哪里停。
- 契约决策的结果不应只告诉用户“选哪个/签不签”，还应给出实现该结果的条件设计和让步路径。

改动：

- 决策系统提示词新增强制要求：
  - 当前结论必须明确给出，不允许用“看情况”替代判断。
  - 结尾不要追加追问清单，只追加固定提醒：如果后续有遗漏信息、对方新回复或条款变化，可以继续告诉我，我会按最新情况重新判断。
  - 作答前先识别用户身份和立场，所有策略必须站在用户一方。
  - “我准备卖/我准备买/我入职/我找外包/我出资”等原文证据优先级最高，避免把用户和对方角色说反。
  - 输出“谈判与让步策略”。
  - 包含开局条件、第一轮让步、第二轮让步交换条件、不能让的底线、暂停/退出触发点。
  - 让步必须是有条件交换，不允许无条件退让。
- 后台摘要新增 `让步空间判断`：
  - 把优化条件后成功率、让步改善空间、让步收益和让步损耗转成人话。
  - 不暴露公式、字段或内部计算细节。
- 最终决策提示中明确：
  - 非价格谈判场景也要转化为条件确认、控制权配置、资源支持或退出机制策略。
- GPT Builder 文档同步要求：
  - GPT 不能只保留判断结论。
  - 必须保留 Action 返回的可执行谈判、让步、控制权和退出策略。

涉及文件：

- `server/index.ts`
- `docs/GPT_BETA_ACTION_SETUP.md`
- `docs/DESIGN.md`

### v0.5.53 - 资料充足度分级与 GPT 搜索前置

日期：2026-06-23

状态：

- 隔离分支本地测试中，暂不部署线上。

背景：

- GPT Beta 测试中发现复杂场景仍频繁进入“必要信息不足”，导致用户感觉一直被追问。
- 原逻辑只要高权重必要条件未满足，就容易阻断，未区分“公开信息可搜索补足”和“只能由用户本人补充”的缺口。
- GPT 版本开启网页搜索后，应先搜索市场、行情、公开案例等信息，搜索不到或涉及用户私有取舍时再追问。

资料充足度标准：

- `insufficient`：
  - 没有具体安排、候选对象或交易关系。
  - 没有核心交换条件，且没有用户本人目标/担心/底线线索。
  - 只适合引导用户提供一个具体场景。
- `preliminary`：
  - 已有具体安排或候选对象。
  - 已有部分交换条件、用户目标、约束或风险线索。
  - 可以先做谨慎初判，缺口作为敏感因素提示，而不是直接阻断。
- `sufficient`：
  - 已有具体安排、核心条件、用户取舍/底线、市场/替代线索、控制权或履约证据中的多数要素。
  - 可以输出明确倾向、策略和成功率拆解。

缺口分类：

- `user-only`：
  - 用户真实需求、优先级、最低底线、风险承受力、能力兴趣匹配、私下承诺、内部控制权安排。
  - 不能靠 GPT 搜索替代，必要时才追问用户。
- `searchable`：
  - 市场价格、薪酬水平、同类成交、挂牌价、行业报价区间、公开融资信息、竞品和公开替代选择。
  - GPT 版本应先网页搜索补足。
- `hybrid`：
  - 双方替代选择/BATNA 等既有公开市场部分，也有用户私有部分。
  - GPT 先搜索公开替代，再只问用户本人可回答的真实备选和失败损失。

改动：

- `contractEngine` 新增 `informationSufficiency`：
  - `level`
  - `score`
  - `blocking`
  - `reasons`
  - `userOnlyMissing`
  - `searchableMissing`
  - `userQuestions`
  - `searchQuestions`
- `requiredFactors.blocking` 改为参考资料充足度，不再因为单个必要条件缺失直接阻断复杂场景。
- GPT Action 支持可选 `publicSearchContext`：
  - GPT 可把网页搜索得到的公开市场信息和可验证背景传给后端。
  - 后端把用户原文和公开搜索补充合并后进入计算。
- 阶段性回复区分：
  - “GPT 可以先搜索补足的公开信息”
  - “真正需要用户本人补充的信息”
- GPT Builder 设置文档增加搜索前置策略。

本地测试结果：

- 寒暄仍返回具体场景提示。
- Offer、买房、朋友合伙三个复杂场景已不再被资料不足门槛阻断。
- 本地 Qwen3.6 能按新版门槛进入分析，但部分场景仍需继续收敛过度拍板语气。

涉及文件：

- `src/contractEngine.ts`
- `server/index.ts`
- `docs/gpt-action-openapi.json`
- `docs/GPT_BETA_ACTION_SETUP.md`
- `docs/DESIGN.md`

### v0.5.52 - GPT 免费测试旁路接口

日期：2026-06-22

背景：

- 用户希望先用自定义 GPT 免费测试真实需求，不立即商业化。
- 主应用已经要求注册/登录后才能调用 AI，不应为 GPT 测试放开正式接口。
- 需要在不改变现有网站主流程的前提下，为 GPT Actions 提供一个受控测试入口。

改动：

- 新增 `/api/gpt/decision`：
  - 不要求普通用户登录。
  - 必须提供 `X-GPT-Beta-Key` 或 Bearer token。
  - 只走 API 模型，不依赖本地模型。
  - 复用后台契约计算、开放因子抽取、缺失信息判断和用户可读输出。
  - 只返回 `content`、`model` 和 beta 免责声明，不暴露公式、权重、JSON 或调试信息。
- 新增 `GPT_BETA_ACTION_KEY` 环境变量。
- 新增 GPT Actions OpenAPI schema：
  - `docs/gpt-action-openapi.json`
- 新增 GPT Builder 设置指南：
  - `docs/GPT_BETA_ACTION_SETUP.md`
- README 增加 GPT 免费测试入口说明。

涉及文件：

- `server/index.ts`
- `.env.example`
- `.env.beta.example`
- `.env.production.example`
- `docs/gpt-action-openapi.json`
- `docs/GPT_BETA_ACTION_SETUP.md`
- `README.md`
- `docs/DESIGN.md`

### v0.4.9 - 场景无关因子抽取

日期：2026-05-31

改动：

- 开放参数抽取提示移除“交易/职场/伙伴关系”字样。
- 抽取器明确禁止判断场景类型或归类到预设模块。
- 抽取目标改为“影响结果分布的变量”，包括：
  - 各方真实动机
  - 内在需求
  - 刚需强度
  - 对象与需求匹配
  - 替代选择
  - 时间压力
  - 信息优势
  - 预期标准
  - 外部环境
  - 长期收益
  - 失败成本
  - 隐藏风险
  - 可写清的约束工具
  - 控制权配置
- 前台文案从“交易、工作或合作场景”改为“你要决策的事情”，避免用户和模型都被场景分类牵引。

设计目的：

- 防止 JSON 输入带有场景先验。
- 防止大模型遇到未见过场景时按旧模板补全。
- 让系统只处理当前事实里的影响因子，而不是处理人为定义的场景类别。

涉及文件：

- `vite.config.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.0 - 需求画像优先决策

日期：2026-05-31

改动：

- 将“用户核心需求”提升为全量因子引擎的第一层必要条件。
- 新增需求画像必要因子：
  - 用户最核心需求
  - 需求优先级/取舍顺序
  - 短期/长期时间视角
  - 能力/兴趣/资源匹配
  - 现实约束/最低底线
- 全量因子池不再把价格、公允价值等交易型因子作为所有问题的默认阻断条件。
- 开放参数抽取器优先识别：
  - 用户到底更想成长、赚钱、稳定、自由、履历、关系还是安全感。
  - 用户是要短期收益还是长期选择权。
  - 当前对象是否匹配用户技能、兴趣、经验和资源。
  - 如果用户自己也不清楚需求，把“需求不清”作为高权重风险因子。
- 大模型输入摘要新增 `需求画像`，并优先展示给大模型。
- 右侧“大模型输入摘要 JSON”新增 `needProfile`。

设计原则：

- 决策不是先算风险，而是先弄清楚“这个人到底想要什么”。
- 所谓匹配，本质是用户需求、对方需求、对象条件、长期目标之间的匹配。
- 如果核心需求没挖出来，就不应该仓促给最终结论。

涉及文件：

- `src/contractEngine.ts`
- `vite.config.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.1 - 数字误读防护与需求缺口保留

日期：2026-05-31

改动：

- 真实测试发现模型把“60人公司”“12-15个月现金流”误读成薪资数字，产生 `12-15k/60k` 等原文不存在的信息。
- 系统提示词补充硬约束：
  - 不编造原文没有的数字。
  - 不把年龄、人数、月份、现金流周期误当成薪资。
- 后台 `features` 中保留需求画像类缺失因子，让右侧测试面板和大模型摘要都能看到“用户核心需求还没挖清楚”，而不是只看到风险和胜率。

设计目的：

- 防止数字语义误读导致幻觉。
- 当用户真实需求不清时，系统应优先追问需求，而不是替用户拍板。

涉及文件：

- `src/contractEngine.ts`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.2 - 数字含义表防误读

日期：2026-05-31

改动：

- 决策输出前新增数字含义表，随当前背景一起传给大模型。
- 自动标注：
  - `23岁 = 年龄`
  - `税前年薪28万 = 薪资/年收入`
  - `60人 = 人数/规模，不是薪资`
  - `12-15个月 = 时间周期，不是薪资`
- 目的不是增加理论提示词，而是把原文事实的数字语义标清楚，防止模型把人数、年龄、月份误读成薪资。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.3 - 输出数字事实校验

日期：2026-05-31

改动：

- 在大模型输出后增加数字事实校验。
- 对照用户原文检查：
  - 年龄表达：原文没有的 `xx岁` 不允许直接输出。
  - 万元金额：原文没有的 `xx万` 不允许直接输出。
  - `k` 薪资：原文没有的 `xxk` 不允许直接输出。
- 对不被原文支持的数字表达进行替换或泛化，避免本地模型把人数、月份、年薪误读成其他含义。

设计目的：

- 本地模型对数字上下文的遵循能力不稳定，不能完全依赖提示词。
- 涉及薪资、年龄、金额时，产品层必须做事实校验。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.4 - 背景数字语义标注

日期：2026-05-31

改动：

- 决策输出输入从“原文 + 数字含义表”改为“数字含义已标注的原文”。
- 例如：
  - `23岁` 改为 `23岁（年龄）`
  - `税前年薪28万` 改为 `税前年薪28万（年收入）`
  - `60人` 改为 `60人（人数/规模，不是薪资）`
  - `12-15个月` 改为 `12-15个月（时间周期，不是薪资）`
- 避免模型把数字含义表当成“数字本身不清楚”，从而反向制造疑问。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.5 - 人数表达自然化

日期：2026-05-31

改动：

- 将 `60人AI产品公司` 这类容易被本地模型误读为 `60% AI` 的相邻数字表达，改写为 `约60名员工规模的AI产品公司`。
- 目的：减少数字和业务名词粘连导致的语义误读。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.6 - 决策优先于谈判

日期：2026-06-02

改动：

- 产品定义从“默认生成谈判策略”校准为“先做决策，谈判只是决策产物之一”。
- 三段胜率统一改为三段成功率：
  - 当前方案成功率
  - 优化条件后成功率
  - 执行后兑现概率
- `/api/decision-pack` 的系统提示词增加硬约束：
  - 先判断问题类型。
  - 不默认把所有问题当成二元对抗或立刻谈判。
  - 多方案选择先挖真实需求、优先级、现实约束和长期目标。
  - 只有当结论是继续推进且存在明确对手方和可协商条件时，才输出谈判或让步建议。
- 前台欢迎语、输入占位文案和右侧测试面板的成功率标签改为通用决策语言。

设计目的：

- 修正“大厂 vs 小厂”这类个人路径选择被系统误导为合作谈判的问题。
- 保持本产品是决策 AI，而不是谈判机器人。
- 让后台公式先回答“该怎么决策”，再决定是否需要谈判。

涉及文件：

- `src/App.tsx`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.7 - 候选契约优先

日期：2026-06-02

改动：

- 修正 `v0.5.6` 可能把产品推向泛化决策 AI 的风险。
- 产品定位明确为“契约决策智能体”，不是普通人生决策工具。
- `/api/decision-pack` 输入字段从 `决策类型` 改为 `契约形态`。
- 多方案选择不再被理解为普通利弊题，而是被还原为多份候选契约比较。
- 大厂 vs 小厂这类职业选择被定义为两份雇佣契约：
  - 各自承诺什么。
  - 要求用户付出什么。
  - 是否满足用户成长、现金、稳定、履历、自由、控制权等真实需求。
  - 未来风险、控制权和履约不确定性由谁承担。
- 前台欢迎语和输入占位文案改为“契约选择”语言。

设计目的：

- 保留“谈判是决策产物”的修正，同时防止系统偏离契约理论底层。
- 让所有场景仍统一落在显性/隐性契约、结果分布、双赢匹配和控制权判断上。
- 先挖用户真实需求，再判断哪份契约更有利于用户内心需求和长期结果分布。

涉及文件：

- `src/App.tsx`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.8 - 市场情况入口

日期：2026-06-02

改动：

- 修正原设计把“公允价值”理解过窄的问题。
- 后台输入从 `契约形态` 改为 `当前市场情况`。
- 明确公允价值只是市场情况的一部分；市场情况还包括行情、候选对象数量、竞争强度、替代选择、对方急迫性、同类机会比较和筹码变化。
- 明确多个 offer、多个买家、多个供应商、多个合作方不是新场景，而是当前市场情况变量。
- 开放参数抽取新增 `市场情况` 类因子。
- 大模型输出约束新增：
  - 不把多个候选对象硬套成一对一谈判。
  - 不把候选契约比较降级成普通利弊分析。
  - 必须说明当前市场情况如何影响用户筹码、契约匹配和成功概率。

设计目的：

- 解释并修复此前回复固定、答非所问的根因：系统把市场情况误解成狭义公允价格，无法正确处理多个候选对象和市场竞争。
- 保持“万物皆契约”的底层逻辑，同时把市场情况作为精算参数纳入后台。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.9 - 两阶段查漏与推论

日期：2026-06-02

改动：

- 决策输出改为两阶段：
  - 第一阶段：默认阶段性分析。后台计算后先复述当前已知信息，说明基于现有资料可以推理到哪一步，再告诉用户哪些关键信息会显著改变结论，并建议用户补充。
  - 第二阶段：用户明确表示“目前只有这些信息”“无法补充”“先按当前资料分析”后，才按现有资料做谨慎推论。
- `/api/decision-pack` 新增 `allowInference` 开关。
- 前端自动识别用户表达：
  - `只有这些`
  - `目前只有`
  - `无法补充`
  - `先按当前分析`
  - `按现有`
  - `直接分析`
- 后台摘要新增 `缺失信息影响`，把每个缺失必要信息对应的判断影响一并纳入阶段性分析。
- 必要信息阻断时，前台回复不再交给大模型自由生成，而是由后台确定性生成，避免本地模型误读数字、选项数量或编造事实。
- 阶段性分析中的“当前已知事实”改为从用户原文确定性提取，不引用开放参数抽取里的证据，避免把金额、人数、时间周期误读成其他含义。
- 已知事实提炼不依赖具体场景词，而是提取用于契约决策的通用要点：数字、时间、成本、收益、风险、替代选择、市场情况、承诺、控制权、退出、底线和履约线索。

设计目的：

- 避免模型每次都机械输出“必要信息不足，不能下最终结论”。
- 让应用先完成“已知信息提炼 + 当前可推理范围 + 重大缺口影响”，再根据用户意愿进入不完全信息下的谨慎推论。
- 保留“阻止用户仓促决策”的初心，同时不让产品卡死在信息不足。

涉及文件：

- `src/App.tsx`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.10 - 全要素提取去预设化

日期：2026-06-02

改动：

- 开放参数抽取提示词不再列举固定因素清单。
- 不再要求模型按预设类别抽取，例如市场、替代、控制权、时间等。
- 只保留任务边界：让大模型做全要素提取，抽取所有会影响契约决策、结果分布、匹配程度、风险暴露、履约可能和用户真实需求的因素。
- 因素类别改为由大模型自行概括。
- 阶段性分析里的当前信息复述也改为“全要素提炼”，不按固定关键词或预设维度筛选。

设计目的：

- 避免开发者预设维度导致语义传导失真。
- 保持全量参数即时验算的产品初心。
- 后台只负责公式计算、查漏和阶段控制，不替大模型决定“应该提取什么”。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.11 - 四理论分路抽取

日期：2026-06-02

改动：

- 修正 `v0.5.10` 把“全要素提取”扩展到所有理论的问题，并修正理论1/理论3分工。
- 明确抽取分工：
  - 理论1：双边匹配均衡，负责专用信息抽取，用于判断当前契约匹配、双方效用、真实需求互补、市场情况和共同剩余。
  - 理论2：不完全契约/控制权，负责专用信息抽取，用于判断未来状态不完备、承诺不清、控制权归属、状态变化、专用投入、风险分配、退出/暂停/转移机制和 hold-up 风险。
  - 理论3：广义分布函数，负责全要素提取，用于聚合所有会影响契约决策、结果分布、匹配程度、风险暴露、收益/损失范围、上下行空间、波动、不确定性、尾部损失和成功/失败路径的因素。
  - 理论4：贝叶斯可信履约，负责专用信息抽取，用于判断历史行为、兑现记录、资金/资源能力、透明度、反复变更、违约信号和第三方可验证证据。
- `/api/analyze-contract` 的抽取结果从单一 `factors` 扩展为：
  - `matchingFactors`
  - `incompleteContractFactors`
  - `distributionFactors`
  - `bayesianFactors`
- 后台仍将四路因素合并进入统一验算，但保留类别前缀以便右侧测试面板识别理论来源。
- 如果模型没有在 `category` 中保留理论前缀，后台合并时会自动补上 `理论1/理论2/理论3/理论4` 前缀。
- 理论2动态因素只要类别包含 `理论2`，也会进入控制权计算。

设计目的：

- 保持广义分布函数作为全要素总模型。
- 防止理论2-4被通用因素稀释。
- 让每个核心理论都有自己的信息入口和计算依据。

涉及文件：

- `src/contractEngine.ts`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.12 - 计算结果模块化输入

日期：2026-06-02

改动：

- `/api/decision-pack` 不再把完整后台摘要 JSON 直接喂给大模型。
- 大模型输入改为按理论模块组织：
  - 当前资料提炼
  - 理论1：双边匹配均衡
  - 理论2：不完全契约与控制权
  - 理论2补充：承诺稳定性
  - 理论3：广义分布函数
  - 理论4：贝叶斯可信履约
  - 会显著改变结论的信息缺口
  - 建议优先追问
- 系统提示词只负责表达边界和安全约束；计算结果负责提供分模块事实。
- 必要信息阻断时仍走确定性阶段性分析，避免本地模型直接拍板或误读。

设计目的：

- 避免一坨 JSON 诱导模型输出测试报告。
- 让大模型知道每个结论来自哪个理论模块。
- 保留右侧测试面板的工程信息，同时让前台输出更像契约顾问对话。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.13 - 系统提示词与模块输入联调展示

日期：2026-06-02

改动：

- `/api/decision-pack` 返回调试信息：
  - 资料提炼系统提示词
  - 决策输出系统提示词
  - 回答模式
  - 当前资料提炼
  - 理论模块计算结果
  - 最终用户消息
- 右侧测试面板新增“最终大模型输入”区块。
- 必要信息阻断时也返回调试信息，并标明未调用最终大模型，使用后台确定性阶段性分析。

设计目的：

- 测试时能同时看到系统提示词和计算结果模块。
- 避免只看理论模块输入，却漏掉系统提示词约束。
- 方便后续排查输出是否被系统提示词、计算结果模块或本地模型能力影响。

涉及文件：

- `src/App.tsx`
- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.14 - 必要信息门槛与不完全契约边界

日期：2026-06-02

改动：

- 资料提炼系统提示词增加约束：不要为了精益求精而要求用户无限补充信息，只识别足以影响契约判断的必要信息。
- 决策输出系统提示词增加不完全契约原则：
  - 永远无法穷尽所有未来状态。
  - 必要信息够了就进入判断。
  - 剩余未知应通过控制权、退出机制、风险分配、分阶段验证和证据留存处理。
- 阶段性分析中的建议追问最多保留 3 个关键问题。
- 阶段性分析文案明确告诉用户：不用把所有信息都补完。

设计目的：

- 防止产品变成无限追问的信息收集器。
- 保留“阻止仓促决策”的底线，同时尊重不完全契约理论的现实边界。
- 让用户在必要信息足够后尽快进入契约判断和风险设计。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.15 - 场景化表达交给大模型

日期：2026-06-03

改动：

- 决策输出系统提示词新增场景表达约束：
  - 职场场景说岗位、职责、KPI、转正、汇报关系、授权、资源支持、去留。
  - 交易场景说价格、交付、付款、过户、验收、责任。
  - 合伙场景说分工、股权、账户、收益分配、退出。
  - 亲密关系说承诺、城市选择、生活成本、未来安排。
- 明确前台不要在所有场景里反复说“合同/契约/条款”，除非用户正在上传或审查正式合同。
- 不新增硬编码场景适配器。
- 后台阶段性分析只保留中性表达，例如“当前判断”“关键事项掌控”“后续边界、责任分配、退出安排、分阶段验证和证据留存”。

设计目的：

- 保留契约理论底层，但前台说用户所在场景的话；具体怎么表达交给大模型根据背景判断。
- 避免职场、关系、项目场景里反复出现生硬的“合同/契约”表达。
- 提升用户理解和代入感。

涉及文件：

- `vite.config.ts`
- `docs/DESIGN.md`

### v0.5.16 - 上线部署第一阶段护栏

日期：2026-06-09

改动：

- 生产构建默认隐藏右侧“后台思考与计算过程”测试面板。
- 开发环境仍默认显示测试面板；生产环境如需内部测试，可显式设置 `VITE_SHOW_DEBUG_PANEL=true`。
- 新增 Node 生产服务入口：
  - `npm run build` 构建前端。
  - `npm run build:server` 编译服务端。
  - `npm run start` 托管 `dist` 静态文件和 `/api/analyze-contract`、`/api/decision-pack`、`/api/contract-review`。
- 新增 `tsconfig.server.json`，把生产服务端编译到 `server-dist`。
- `server-dist` 加入 `.gitignore`。

设计目的：

- 避免正式用户看到公式、JSON、系统提示词和内部计算过程。
- 让应用脱离 Vite 开发服务器，具备部署到自有服务器或容器的基础形态。
- 保留测试能力，但把测试能力变成显式开关，而不是默认暴露。

上线状态：

- 当前版本适合“小范围内测/演示部署”。
- 正式商业上线前仍需补齐：用户登录、项目记忆云端存储、权限控制、合同上传隐私策略、访问限流、日志脱敏、模型服务稳定性监控。

涉及文件：

- `src/App.tsx`
- `server/index.ts`
- `package.json`
- `tsconfig.server.json`
- `.gitignore`
- `docs/DESIGN.md`

### v0.5.17 - 上线部署第二阶段护栏

日期：2026-06-09

改动：

- 生产服务新增 `/api/health` 健康检查接口。
- 生产 API 增加内存级限流：
  - 默认 60 秒 30 次。
  - 可通过 `API_RATE_LIMIT_WINDOW_MS` 和 `API_RATE_LIMIT_MAX` 调整。
- 生产服务增加基础安全响应头：
  - `X-Content-Type-Options`
  - `X-Frame-Options`
  - `Referrer-Policy`
  - `Permissions-Policy`
- 请求体大小限制改为环境变量控制，默认 `MAX_REQUEST_BODY_BYTES=512000`。
- 前端合同上传增加文件大小预检查，默认超过 200KB 时提示用户拆分或上传摘要。
- 新增 `.env.example`。
- `README.md` 从 Vite 模板改为项目部署说明。

设计目的：

- 让应用具备基础运维可观测性。
- 避免无保护的 API 被高频调用或超大请求拖垮。
- 降低合同上传阶段的失败率和用户困惑。
- 让部署不再依赖口头说明。

上线状态：

- 当前版本进一步接近“可公开内测”。
- 正式商业上线前仍需补齐账号体系、云端项目记忆、支付权限、日志脱敏、隐私协议和模型服务监控。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `README.md`
- `.env.example`
- `docs/DESIGN.md`

### v0.5.18 - 新项目 019e21d2 经验朋友圈立项

日期：2026-06-09

改动：

- 新增独立项目档案 `PROJECT-019e21d2-experience-circle.md`。
- 将“经验朋友圈”定义为契约决策 AI 的社区化和后验化延展。
- 明确两者关系：
  - 契约决策 AI 负责个案即时验算。
  - 经验朋友圈负责真实经历沉淀、同类案例参照和后验校准。
- 提出第一阶段先做个人私密经验卡，不直接做公开社区。
- 明确经验卡结构、合规边界和第一批落地任务。

设计目的：

- 避免把产品走偏成普通社区或泛朋友圈。
- 让用户真实决策经验反哺契约决策引擎。
- 为后续项目记忆、结果回填、后验概率校准和相似案例推荐建立产品边界。

涉及文件：

- `docs/PROJECT-019e21d2-experience-circle.md`
- `docs/DESIGN.md`

### v0.5.19 - 上线法律文件包

日期：2026-06-09

改动：

- 新增 `docs/legal/` 法律文件包：
  - 用户服务协议。
  - 隐私政策。
  - AI 风险免责声明。
  - 合同上传与数据处理说明。
  - 上线合规检查清单。
- README 新增法律文件包位置说明。
- 明确上述文件为律师审阅稿，不构成最终法律意见。

设计目的：

- 为契约决策 AI 正式上线准备基础法律文本。
- 明确产品不是 AI 律师，不提供最终法律、投资、税务、职业或财务意见。
- 强化合同上传、项目记忆、AI 概率输出和数据处理的边界。
- 让后续律师审阅有完整底稿。

涉及文件：

- `docs/legal/README.md`
- `docs/legal/TERMS_OF_SERVICE.md`
- `docs/legal/PRIVACY_POLICY.md`
- `docs/legal/AI_DISCLAIMER.md`
- `docs/legal/CONTRACT_UPLOAD_DATA_NOTICE.md`
- `docs/legal/LAUNCH_COMPLIANCE_CHECKLIST.md`
- `README.md`
- `docs/DESIGN.md`

### v0.5.30 - 中英双语版本

日期：2026-06-17

背景：

- 产品不能只保留中文界面，需要支持中国用户和海外/英文用户测试。
- 公测部署需要同一套代码支持中英两个版本，而不是维护两套前端。

改动：

- 前端新增语言状态：
  - `zh`
  - `en`
  - 使用 `localStorage` 记住用户选择。
- 主界面新增语言切换：
  - 中文界面显示 `EN` 按钮。
  - 英文界面显示 `中` 按钮。
- 主产品界面主要文案支持中英：
  - 首屏价值主张。
  - 核心能力卡片。
  - 项目状态。
  - 账号登录/注册。
  - 聊天输入和文件上传。
  - 法律/免责声明提示。
- 管理后台主要文案支持中英：
  - 登录页。
  - 指标卡。
  - 用户列表表头。
  - 用户状态和操作按钮。
- 前端请求新增语言参数：
  - `/api/decision-pack`
  - `/api/contract-review`
- 服务端输出支持语言切换：
  - 查漏模式确定性回复支持英文。
  - 最终大模型回复在英文模式下加入英文输出约束。
  - 合同审查在英文模式下输出英文。

当前限制：

- 右侧测试面板的深层调试字段仍以中文为主。
- 后台计算 JSON 字段和理论模块名称保持内部中文/英文混合，不作为普通用户前台展示。
- 用户已经保存的旧项目标题和历史消息不会自动翻译。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `docs/DESIGN.md`

### v0.5.29 - Token 用量与使用时间指标

日期：2026-06-17

背景：

- 公测需要观察真实使用强度和 AI 成本。
- 管理后台需要看到 token 用量、调用次数、接口耗时和失败调用。

改动：

- 新增 `data/usage.json` 用量日志。
- 每次大模型调用记录：
  - 时间 `createdAt`
  - 用户 ID / 匿名客户端 ID
  - provider
  - model
  - 调用目的：`extraction` / `summary` / `decision` / `review`
  - prompt token
  - completion token
  - total token
  - 接口耗时 `latencyMs`
  - 是否成功
  - 错误摘要
- 后台总览新增：
  - 总 token
  - 今日 token
  - 大模型调用次数
  - 平均耗时
  - 失败调用数
- 用户列表新增：
  - 用户总 token
  - 用户今日 token
  - 用户调用次数
  - 用户平均耗时

说明：

- 如果本地模型服务不返回 OpenAI 兼容 `usage` 字段，token 会记录为 0，但调用次数和耗时仍会记录。
- DeepSeek/OpenAI 兼容接口通常返回 `usage`，可正常统计 token。
- 当前用 JSON 文件保存最近 5000 条用量记录，正式商业版应迁移到数据库。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/App.css`
- `README.md`
- `docs/DESIGN.md`

### v0.5.28 - 公测用户管理后台

日期：2026-06-17

背景：

- 公测阶段需要知道是否有人真实使用产品。
- 需要查看注册用户、项目数量、项目轮次、最近活跃，并能处理异常账号。
- 现有系统已有用户数据和项目记忆，但没有管理员界面。

改动：

- 新增管理员配置：
  - `APP_ADMIN_EMAIL`
  - `APP_ADMIN_PASSWORD`
  - `APP_ADMIN_SECRET`
  - `APP_ADMIN_SESSION_COOKIE`
- 新增管理员 Cookie：
  - 独立于普通用户会话。
  - 使用 HMAC 签名。
  - 不使用普通用户账号作为管理员。
- 新增管理 API：
  - `POST /api/admin/login`
  - `POST /api/admin/logout`
  - `GET /api/admin/me`
  - `GET /api/admin/summary`
  - `GET /api/admin/users`
  - `POST /api/admin/users/update`
- 新增 `/admin` 前端页面：
  - 管理员登录。
  - 用户总数、活跃用户、暂停用户、项目数、项目记忆轮次、Pro 用户数。
  - 用户列表、邮箱搜索、创建时间、最近活跃、项目数、轮次。
  - 手动修改用户 plan：`free` / `beta` / `pro`。
  - 暂停或恢复用户。
- 普通用户登录增加禁用判断：
  - 被暂停用户不能登录。
  - 已有会话读取时也会被视为无效。

当前限制：

- 管理员密码来自环境变量，尚未做后台内改密码。
- 管理后台仍基于本地 JSON 文件统计。
- 未记录逐次 API 调用日志和 token 消耗。
- 未做角色体系，当前只有一个管理员入口。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/App.css`
- `.env.example`
- `.env.beta.example`
- `.env.production.example`
- `README.md`
- `docs/DESIGN.md`

### v0.5.20 - Global MVP 海外法律声明包

日期：2026-06-09

改动：

- 新增 `docs/legal/global-mvp/`：
  - Global Terms of Service。
  - Global Privacy Policy。
  - Global AI and Professional Advice Disclaimer。
  - Global Document Upload and Data Processing Notice。
  - Global Refund and Subscription Policy Draft。
  - Global MVP Launch Checklist。
- `docs/legal/README.md` 增加海外 MVP 入口。
- `README.md` 增加海外 MVP 法律文件路径。

设计目的：

- 将中国口径法律文件与海外独立站/全球 MVP 法律声明分开。
- 为中国以外用户服务准备更宽泛的 SaaS 条款、隐私权利、AI 使用边界和收款退款草案。
- 降低“AI 律师”“保证决策正确”“合同安全保证”等海外宣传风险。
- 为后续海外律师、支付服务商和云服务部署审查准备底稿。

参考口径：

- GDPR / UK GDPR 风格的数据主体权利。
- California CCPA/CPRA 风格隐私权利。
- EU AI Act 风险分级和人类监督口径。
- FTC 对 AI 营销声明的反欺骗口径。

涉及文件：

- `docs/legal/global-mvp/README.md`
- `docs/legal/global-mvp/GLOBAL_TERMS_OF_SERVICE.md`
- `docs/legal/global-mvp/GLOBAL_PRIVACY_POLICY.md`
- `docs/legal/global-mvp/GLOBAL_AI_DISCLAIMER.md`
- `docs/legal/global-mvp/GLOBAL_DOCUMENT_UPLOAD_NOTICE.md`
- `docs/legal/global-mvp/GLOBAL_REFUND_SUBSCRIPTION_POLICY.md`
- `docs/legal/global-mvp/GLOBAL_MVP_LAUNCH_CHECKLIST.md`
- `docs/legal/README.md`
- `README.md`
- `docs/DESIGN.md`

### v0.5.21 - 商业版首屏与法律入口优化

日期：2026-06-09

改动：

- 生产环境首屏从单一卡片改为商业 SaaS 布局：
  - 左侧产品概览。
  - 右侧契约决策对话主界面。
  - 移动端自动隐藏概览，保留对话主流程。
- 新增核心价值展示：
  - 全要素提取。
  - 四理论契约验算。
  - 三段成功率。
  - 合同风险提示。
- 生产界面新增服务边界提示：
  - AI 辅助分析。
  - 不替代律师、财务顾问、税务顾问或其他专业人士。
- 对话输入文案从测试口吻改为正式商业口吻。
- 生产界面底部新增 Terms / Privacy 入口。
- 生产服务支持访问 `/docs/legal/` 下的 Markdown 法律文件。

设计目的：

- 提升第一眼商业可信度。
- 避免用户把产品误解为普通聊天机器人。
- 在不暴露后台公式和提示词的前提下，表达产品差异化价值。
- 让法律声明可以从正式应用中直接访问。

仍未完成：

- 正式账号体系。
- 正式云数据库项目记忆。
- 正式支付与订阅。
- 法律页面正式 HTML 化。
- 输出质量持续回归测试。
- 商业化定价页和支付流程。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.22 - 10 用例全流程回归与生产输出清洗

日期：2026-06-09

测试范围：

- 10 个复杂场景：
  - 应届生 offer 选择。
  - 卖房谈判。
  - 朋友借钱。
  - 外包开发合同。
  - 联合投标合作。
  - 试用期职权被调整。
  - 合伙开咨询工作室。
  - 异地同居城市选择。
  - 跨境代运营服务采购。
  - 股权激励承诺。
- 每个场景执行：
  - `/api/analyze-contract`
  - `/api/decision-pack`
  - 默认查漏模式。
  - 用户确认“目前只有这些，先按现有信息分析”后的推论模式。

测试结论：

- 20 次核心 API 调用全部成功。
- 默认查漏模式均能返回阶段性分析和关键缺失信息。
- 推论模式均能返回完整建议。
- 未发现公式、JSON、内部字段名泄露。
- 发现少量生产输出仍带有“系统提示”“后台测算”等测试痕迹。

改动：

- 生产服务端 `sanitizeUserFacingReply` 增加商业化清洗：
  - 将“系统提示必要信息不足”改为“信息还不完整”。
  - 将“后台测算/后台计算/后台评估”改为“测算结果”。
  - 将部分场景中过硬的“隐性契约/契约逻辑/契约视角”改为更自然的“隐含约定/合作逻辑/合作视角”。

仍需观察：

- 默认查漏模式目前偏保守，10 个场景全部触发必要信息不足。
- 少数场景开放参数抽取为 0，需后续加强 JSON 解析重试和抽取兜底。
- 推论模式输出质量整体可用，但仍需 50-100 个固定商业用例做持续回归。

涉及文件：

- `server/index.ts`
- `docs/DESIGN.md`

### v0.5.23 - 上线差距补齐第一层：项目云端记忆与权限基础

日期：2026-06-09

背景：

- 上线前仍缺账号、云端项目记忆、付费权限控制。
- 当前阶段先补齐可运行的产品闭环，不引入复杂第三方账号或支付系统。
- 目标是让应用从“本地测试 Demo”进入“可部署试运行版本”。

改动：

- 新增匿名客户端 ID：
  - 前端为每个浏览器生成稳定 clientId。
  - 所有项目同步和分析请求携带 `X-Client-Id`。
  - 后续接邮箱、手机号或 OAuth 时，可直接替换为正式 userId。
- 新增服务端项目存储：
  - `GET /api/projects` 读取当前用户项目记忆。
  - `POST /api/projects` 保存当前用户项目记忆。
  - 服务端按用户 ID 写入 `data/projects/*.json`。
  - `data/` 加入 `.gitignore`，避免测试数据、合同摘要或用户隐私误提交。
- 新增权限配置基础：
  - `GET /api/entitlements` 返回当前计划和额度。
  - 环境变量支持免费/付费项目数和项目记忆轮次限制。
  - 前端展示当前权限、同步状态、项目额度和记忆轮次。
  - 免费版默认限制为 3 个项目、每项目 8 轮记忆；Pro 默认 100 个项目、每项目 200 轮记忆。
- 修复服务端配置读取顺序：
  - `.env.local` 必须在端口、权限和数据目录常量初始化前读取。
  - 避免部署后环境变量不生效。

产品意义：

- 项目跟踪能力不再只依赖浏览器 localStorage。
- 免费/付费差异有了后端口径，后续可以接支付、订阅或管理员配置。
- 账号体系有了最小可替换接口，避免现在为登录系统过度开发。

仍未完成：

- 正式账号注册、登录、找回密码和会话管理。
- 正式云数据库、备份和数据迁移。
- 付费订阅、发票、退款、权限变更。
- 项目数据导出和删除请求流程。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `.env.example`
- `.gitignore`
- `docs/DESIGN.md`

### v0.5.24 - 正式账号与支付系统基础

日期：2026-06-09

背景：

- 产品进入上线准备阶段，需要从匿名试用升级为正式账号体系。
- 付费权限不能由前端自行决定，必须由服务端订单和 Webhook 更新用户权益。
- 当前阶段先实现最小正式闭环：账号注册登录、会话、用户归属、支付订单、订阅 Webhook。

改动：

- 新增正式账号接口：
  - `POST /api/auth/register` 邮箱注册。
  - `POST /api/auth/login` 邮箱密码登录。
  - `POST /api/auth/logout` 退出登录。
  - `GET /api/auth/me` 获取当前用户与权益。
- 新增服务端密码安全：
  - 密码不明文存储。
  - 使用 PBKDF2-SHA256、随机盐、固定时间比较。
  - 用户数据写入 `data/users.json`。
- 新增 HttpOnly 会话：
  - 登录后写入 HttpOnly Cookie。
  - 会话写入 `data/sessions.json`。
  - 会话过期时间由 `APP_SESSION_DAYS` 控制。
- 项目记忆归属升级：
  - 已登录用户使用 `user-{userId}` 作为项目存储 ID。
  - 未登录用户仍保留匿名试用。
- 新增 Stripe 支付基础：
  - `POST /api/billing/checkout` 创建 Stripe Checkout 订阅订单。
  - `POST /api/billing/portal` 创建 Stripe Customer Portal 订阅管理入口。
  - `POST /api/billing/webhook` 接收并校验 Stripe Webhook 签名。
  - `checkout.session.completed` 将用户升级为 Pro。
  - `customer.subscription.updated` 根据订阅状态同步 Free/Pro。
  - `customer.subscription.deleted` 将用户降级为 Free。
- 新增前端账号区：
  - 未登录显示登录/注册表单。
  - 登录后显示邮箱、当前套餐、升级 Pro / 管理订阅和退出按钮。
  - 支付未配置时明确提示，不伪造付费成功。

环境变量：

- `APP_SESSION_COOKIE`
- `APP_SESSION_DAYS`
- `PUBLIC_APP_URL`
- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`
- `STRIPE_PRO_PRICE_ID`

仍未完成：

- 邮箱验证、忘记密码、账号删除和数据导出流程。
- 正式数据库替换本地 JSON 文件。
- 管理后台、订单列表、发票和退款流程。
- CSRF Token 和更细粒度风控。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/App.css`
- `.env.example`
- `docs/DESIGN.md`

### v0.5.25 - 公测版与商业版拆分

日期：2026-06-09

背景：

- 当前阶段需要先验证是否有人真实使用产品。
- 公测阶段不应要求用户支付，否则会干扰需求验证、使用频次和留存观察。
- 但商业版支付链路需要保留，避免后续重新改架构。

版本策略：

- 公测版：
  - `APP_RELEASE_CHANNEL=beta`
  - 保留账号注册、登录、项目记忆。
  - 默认返回 Beta 权益。
  - 不显示真实升级支付入口。
  - 支付接口返回“公测期无需支付”。
  - 默认额度：20 个项目、每项目 80 轮记忆。
- 商业版：
  - `APP_RELEASE_CHANNEL=production`
  - 使用 Free / Pro 权益。
  - Free 默认 3 个项目、每项目 8 轮记忆。
  - Pro 默认 100 个项目、每项目 200 轮记忆。
  - 启用 Stripe Checkout、Webhook 和 Customer Portal。

改动：

- 服务端新增 `APP_RELEASE_CHANNEL`。
- 权益接口新增：
  - `releaseChannel`
  - `billingEnabled`
- 公测版禁用：
  - `/api/billing/checkout`
  - `/api/billing/portal`
  - `/api/billing/webhook`
- 前端根据 `billingEnabled` 隐藏收费路径：
  - 公测版显示“公测免费”。
  - 商业版显示“升级 Pro / 管理订阅”。
- 新增环境模板：
  - `.env.beta.example`
  - `.env.production.example`

产品意义：

- 可以先上线公测收集真实用户行为。
- 不牺牲后续付费商业化路径。
- 同一套代码支持两个部署版本，降低维护成本。

仍需完成：

- 公测数据看板：注册数、活跃项目数、单项目轮次、留存、合同上传次数。
- 公测反馈入口。
- 公测到商业版的数据迁移和用户告知策略。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `.env.example`
- `.env.beta.example`
- `.env.production.example`
- `docs/DESIGN.md`

### v0.5.26 - DeepSeek API 入口配置

日期：2026-06-17

背景：

- 公测版需要可直接接入第三方大模型 API。
- DeepSeek 提供 OpenAI 兼容的 Chat Completions 接口，适合作为公测部署的云端模型入口。
- 原系统只有通用 `LLM_BASE_URL/LLM_MODEL`，虽然可以手动接 DeepSeek，但不够清晰。

改动：

- 新增模型入口配置：
  - `LLM_PROVIDER=openai-compatible | deepseek`
  - `DEEPSEEK_BASE_URL=https://api.deepseek.com`
  - `DEEPSEEK_API_KEY`
  - `DEEPSEEK_MODEL`
  - `DEEPSEEK_THINKING`
  - `DEEPSEEK_REASONING_EFFORT`
- 服务端新增 `llmProviderConfig()`：
  - `deepseek` 模式走 DeepSeek 专用环境变量。
  - DeepSeek endpoint 使用官方路径 `https://api.deepseek.com/chat/completions`。
  - 默认模式继续兼容本地 OpenAI 格式模型服务。
- 服务端新增 DeepSeek JSON mode 支持：
  - 开放参数抽取调用会传 `response_format: { type: "json_object" }`。
  - 继续保留 prompt 中的 JSON 输出要求，满足 DeepSeek JSON 输出约束。
- 服务端 `/api/health` 新增：
  - `llmProvider`
  - `llmModel`
  - `llmConfigured`
  - 不返回 API Key。
- 环境模板更新：
  - `.env.example`
  - `.env.beta.example`
  - `.env.production.example`

配置建议：

- 公测版推荐：
  - `APP_RELEASE_CHANNEL=beta`
  - `LLM_PROVIDER=deepseek`
  - `DEEPSEEK_MODEL=deepseek-v4-flash`
  - `DEEPSEEK_THINKING=disabled`
- 如果需要更强推理：
  - 可改为更高阶 DeepSeek 模型。
  - 可设置 `DEEPSEEK_THINKING=enabled` 和 `DEEPSEEK_REASONING_EFFORT=medium/high`。
  - 但需要关注成本、延迟和是否输出过度理论化。

涉及文件：

- `server/index.ts`
- `.env.example`
- `.env.beta.example`
- `.env.production.example`
- `docs/DESIGN.md`

### v0.5.27 - API Key 暴露风险治理

日期：2026-06-17

风险背景：

- DeepSeek / 大模型 API Key 如果进入前端包、公开仓库或浏览器日志，就会被直接盗刷。
- 即使 Key 不暴露，如果后端 API 没有限制来源，也可能被第三方网页跨站调用，间接消耗额度。

已有安全边界：

- 大模型 API Key 只从服务端环境变量读取。
- 前端不需要也不允许使用 `VITE_DEEPSEEK_API_KEY`。
- `.env.local` 已被 `.gitignore` 忽略。
- `/api/health` 只返回 `llmProvider`、`llmModel`、`llmConfigured`，不返回 Key。
- 生产服务已有限流、请求体大小限制和 no-store 响应头。

新增改动：

- 新增 `APP_ALLOWED_ORIGINS`：
  - 多个域名用英文逗号分隔。
  - 默认使用 `PUBLIC_APP_URL`。
- 普通 POST API 新增 Origin 校验：
  - 允许同源。
  - 允许 `APP_ALLOWED_ORIGINS` 中配置的域名。
  - 拒绝其他来源浏览器发起的写操作。
- Stripe Webhook 不走 Origin 校验：
  - 继续依赖 `Stripe-Signature` 签名校验。

部署要求：

- Hugging Face / 云平台部署时，DeepSeek Key 必须放在平台 Secrets。
- 禁止把 API Key 写入前端 `VITE_*` 环境变量。
- 禁止把真实 Key 写入 `.env.example`、README 或公开截图。
- 生产环境必须设置：
  - `PUBLIC_APP_URL`
  - `APP_ALLOWED_ORIGINS`
  - `API_RATE_LIMIT_*`
- 大模型平台应设置用量预算、余额告警和 Key 定期轮换。

仍需完成：

- 每用户每日额度。
- 每 IP + 每账号组合限流。
- 管理后台查看异常调用。
- Key 泄露后的自动禁用和轮换流程。
- CSRF Token，用于进一步保护 Cookie 登录态下的敏感写操作。

涉及文件：

- `server/index.ts`
- `.env.example`
- `.env.beta.example`
- `.env.production.example`
- `README.md`
- `docs/DESIGN.md`

### v0.5.28 - 决策卡可读性与补充维度兜底

日期：2026-06-30

改动背景：

- 测试面板中候选者指标原本以连续文本展示，数值容易挤在一起，用户无法快速看清每个候选的当前可谈成、补强后、兑现、效用和错配风险。
- “建议补充关键维度”在大模型未返回推荐项时会显示为空，和“全量信息”产品定位不一致。

新增改动：

- 候选者当前条件拆分改为表格化指标展示：
  - 当前可谈成
  - 补强后可谈成
  - 签下后兑现
  - 我方效用
  - 对方效用
  - 共同剩余
  - 匹配均衡
  - 可匹配概率
  - 错配风险
- 增加响应式表格布局：
  - 宽屏三列。
  - 中等屏两列。
  - 手机单列。
- “建议补充关键维度”增加兜底生成：
  - 优先展示大模型根据当前案例返回的推荐补充维度。
  - 如果大模型没有返回，前端基于当前公式计算结果、候选差异、控制权缺口、可信履约证据、替代选择压力、市场参照缺口和用户取舍顺序自动生成至少 3 个收集方向。
- 兜底补充方向按信息价值排序，避免出现“暂无新的高影响补充项”导致用户不知道下一步该收集什么信息。

涉及文件：

- `src/App.tsx`
- `src/App.css`
- `docs/DESIGN.md`

### v0.5.31 - 文件上传背景解析层

日期：2026-07-01

改动背景：

- 旧版“上传合同”只能读取 `.txt/.md/.text` 纯文本文件。
- 几十页或几百页项目资料、合同、报价书、合作方案通常以 PDF 或 Word 形式存在，要求用户复制粘贴不现实。
- 上传文件的主要用途是减少用户填写项目背景的成本，不应默认进入合同审查。
- 只有当用户在上下文中明确要求“审查合同/检查条款风险”时，才进入合同风险审查链路。

新增改动：

- 前端上传入口支持：
  - PDF
  - DOC
  - DOCX
  - TXT
  - Markdown
- 上传方式从浏览器本地 `FileReader.readAsText` 改为 `FormData` 文件上传，由后端解析文本。
- 后端新增 `/api/document-extract`：
  - 只负责解析文件文本。
  - 不调用大模型。
  - 不做合同审查。
  - 返回提取文本、文件名、字符数和截断提示。
- 前端上传后把提取文本放入输入框，用户补充“我要判断什么”后再发送，进入正常契约决策流程。
- 后端 `/api/contract-review` 保留兼容：
  - JSON 文本审查请求。
  - multipart 文件上传审查请求。
  - 但前端普通上传入口不再默认调用该接口。
- 后端新增文件解析能力：
  - PDF 使用 `pdf-parse` 提取文本。
  - DOC 使用 `word-extractor` 提取正文文本。
  - DOCX 使用 `mammoth` 提取正文文本。
  - TXT/Markdown 直接按 UTF-8 读取。
- 上传文件大小上限提升到 15MB，并保留解析后文本长度限制，避免一次审查超出模型上下文。
- 解析失败、加密文件、空文本、超长文本和不支持格式均返回明确错误提示。

涉及文件：

- `src/App.tsx`
- `server/index.ts`
- `package.json`
- `package-lock.json`
- `docs/DESIGN.md`

### v0.5.32 - A to A 泛契约场景升级

日期：2026-07-01

改动背景：

- 产品最终目标是 A to A 谈判砍价与契约决策工具，不能被早期“交易、offer、岗位、买卖”等示例词限制。
- 用户可能输入的是资源交换、代理渠道、承包交付、条件包、路径安排、关系承诺、平台合作等非标准场景。
- 旧版入口文案和候选识别正则仍偏向 offer/公司/买家/卖家，可能导致新场景候选漏识别或被误判为资料不足。

新增改动：

- 系统身份提示升级为 A to A 泛契约决策：
  - 双方或多方之间的价值交换。
  - 资源配置。
  - 承诺关系。
  - 条件包。
  - 路径安排。
  - 继续、谈判、签下、调整或退出。
- 前端中英文开场白、问候回复和输入框占位文案改为泛契约表达，交易/offer/岗位等只作为例子，不作为边界。
- 摘要 JSON 提取提示扩展候选对象表达：
  - 候选对象。
  - 交易对手。
  - 资源方。
  - 承诺方。
  - 条件包。
  - 路径安排。
  - 方案或选择。
- 候选识别正则扩展：
  - 服务商、承包商、代理、渠道、平台方、团队、项目、标的、安排等。
  - 支持 A方、A方案、A路径、A对象、A团队、A平台、A项目、A标的等泛化写法。
- 当前完整情况识别扩展：
  - 不再只依赖 offer/公司/买卖/合同。
  - 可识别资源方、需求方、承诺方、条件包、路径、代理、渠道、平台方等自包含候选集合。
- 信息充分度判断扩展：
  - 不再只把 offer、买卖、岗位、合同视为具体安排。
  - 将资源、授权、控制权、退出、区域、账号、数据、IP、客户归属等作为核心交换条件信号。

涉及文件：

- `server/index.ts`
- `src/App.tsx`
- `src/contractEngine.ts`
- `docs/DESIGN.md`

### v0.5.33 - 右侧决策卡去职场残留与泛契约候选解释

日期：2026-07-01

改动背景：

- A to A 泛契约测试中，外包开发、承包交付等场景仍会在右侧决策卡出现“平台背书、岗位兑现、家庭稳定”等早期求职用例残留。
- 这些残留会污染候选价值、候选风险、对方动机和对比结论依据，导致 A/B/C 候选解释看起来像同一套职场模板。

新增改动：

- 候选价值解释改为泛契约维度：
  - 价格、付款或成本条件。
  - 交付周期或上线目标。
  - 履约稳定性或流程保障。
  - 技术能力或产品相关性。
  - 资源支持、控制权或后续配合。
- 候选风险解释改为泛契约维度：
  - 履约证据或关键承诺不清。
  - 变更、验收或交付质量风险。
  - 控制权、归属或锁定风险。
  - 资金、付款或兑现风险。
  - 范围、资源或执行强度风险。
- 对方动机解释增加外包、承包、代理、渠道等场景优先判断，避免把“平台/流程”误判成大厂岗位逻辑。
- 项目事实摘要 fallback 的候选切分、事实筛选和统一背景说明改为泛契约词表。
- 底层因子“岗位匹配度”改名为“角色/能力匹配度”，避免全因素矩阵只适配职场场景。

涉及文件：

- `src/App.tsx`
- `src/contractEngine.ts`
- `docs/DESIGN.md`

### v0.5.34 - 统一背景因素池按场景加载

日期：2026-07-01

改动背景：

- 外包开发等 A to A 泛契约场景中，统一背景因素池会混入职场用例的“成长资产、组织认可、岗位类参照点”等因素。
- 原因是 universal 引擎将 `trade + career + partner` 三套基础因子全部加载，导致“项目、核心、长期、客户”等普通词误触发职场或关系因子。

新增改动：

- 基础因子池改为按当前文本加载：
  - 默认加载交易/项目契约因子。
  - 只有出现明确求职、岗位、薪酬、入职、招聘、晋升等词时，才加载职场因子。
  - 只有出现合伙、代理、渠道、账号、数据、代码、IP、外包、维护、退出等词时，才加载合作/关系因子。
- 这样保留泛契约适配能力，同时减少不相关基础因子进入统一背景池和计算过程。

涉及文件：

- `src/contractEngine.ts`
- `docs/DESIGN.md`

### v0.5.35 - 取消基础因子场景分类，回到全契约通用核心因子

日期：2026-07-01

改动背景：

- 用户指出“按关键词加载职场/合作/交易模块”仍然属于人为场景分类，会违背产品“全量信息、非固定场景”的初心。
- 正确结构应为：
  - 一组全部契约关系都适用的抽象核心因子。
  - 具体行业、具体对象、具体候选差异由大模型开放参数 JSON 提取。
  - 后台公式只吃结构化因子，不再按场景关键词切模块。

新增改动：

- `universal` 引擎不再根据关键词加载 `trade/career/partner` 因子库。
- 统一背景因素池只加载：
  - 用户核心需求。
  - 需求优先级/取舍。
  - 时间视角。
  - 能力/资源匹配。
  - 现实底线。
  - 价格/成本区间。
  - 时间/期限/急迫性。
  - 对方履约能力。
  - 标的/方案质量。
  - 权属/归属清晰度。
  - 交付/移交流程摩擦。
  - 风险分配工具。
  - 后续控制权/最终拍板权。
  - 状态触发控制权转移。
  - 当前市场情况。
  - 双方替代选择/BATNA。
  - 可信信号。
  - 签约/履约后隐性成本。
  - 后续协作需要。
- 行业和场景差异只通过开放参数进入，例如成本结构、交付风险、控制权偏好、知识产权归属、数据安全、候选信任先验等。

涉及文件：

- `src/contractEngine.ts`
- `docs/DESIGN.md`

### v0.5.36 - 旧场景因子展示过滤与交付维度改名

日期：2026-07-01

改动背景：

- 本地项目记忆中可能保存了旧版本计算结果，导致右侧仍展示“成长资产、组织认可”等职场专属基础因子。
- “交付/移交流程摩擦”表达不够直观，用户认为适用性和可读性不高。

新增改动：

- 右侧候选专属因素和统一背景因素池展示时过滤旧场景基础因子：
  - 成长资产。
  - 组织认可。
  - 薪酬/绩效回报。
  - 工作负荷/身心成本。
  - 晋升路径清晰度。
  - 外部机会。
  - 组织政治/背责风险。
  - 领导契约稳定性。
- “交付/移交流程摩擦”改名为“交付与验收安排”。
- 旧缓存中的“过户/交割摩擦”和“交付/移交流程摩擦”也会在展示层归一为“交付与验收安排”。

涉及文件：

- `src/App.tsx`
- `src/contractEngine.ts`
- `docs/DESIGN.md`

### v0.5.37 - 必要信息满足判断改为读取完整原文

日期：2026-07-01

改动背景：

- 引擎测试发现：用户原文已经包含报价、期限、候选方、控制权等信息时，若这些因子在展示层被过滤，必要信息判断仍可能误报缺失。
- 这会让“全量参数”看起来不完整，也会影响下一步补充维度建议。

新增改动：

- `requiredIsSatisfied` 不再只读取过滤后的特征列表。
- 必要信息判断同时读取：
  - 用户完整原文。
  - 开放参数提取结果。
  - 已观察到的结构化特征。
- 这样可避免“事实在原文里，但因为展示过滤导致后台认为不存在”的误判。

验证：

- 已用 5 个不同泛契约用例做引擎级测试：
  - 外包开发三选一。
  - 渠道代理合作。
  - 设备租赁与采购。
  - 联合营销换资源。
  - 合伙开店。
- 测试结果：未再出现旧职业场景因子；必要核心要素未误报缺失。

涉及文件：

- `src/contractEngine.ts`
- `docs/DESIGN.md`

### v0.5.111 - 阿里百炼 OCR 专用通道

日期：2026-07-05

改动：

- 普通决策、摘要、候选识别、谈判输出仍走本地/DeepSeek 文本推理链路。
- 新增阿里百炼 DashScope OCR 专用配置，只用于图片文件文字识别。
- 图片上传时先调用 OCR 提取文字，再进入原有契约决策/合同审查流程。
- 健康检查新增 OCR provider 状态，便于确认是否已配置。

配置：

`env
DASHSCOPE_OCR_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
DASHSCOPE_OCR_API_KEY=你的阿里百炼 Key
DASHSCOPE_OCR_MODEL=qwen3.6-flash
DASHSCOPE_OCR_THINKING=disabled
` 

注意：如果所选 Qwen 3.6 Flash 模型在百炼侧不接受图片输入，应只改 DASHSCOPE_OCR_MODEL 为百炼支持的视觉/OCR模型，不影响 DeepSeek 决策链路。

涉及文件：

- server/index.ts`n- .env.example`n- docs/DESIGN.md`n