架构一页纸

Agent 工作台背后的 harness 设计：数值建模主链为价值核心，工具调用、环境、权限、上下文、记忆五支柱作保障层，落在一个真实游戏数值项目中。

LLM 负责理解、编排、解释；确定性引擎负责数值正确性——数值建模主链（游戏框架 → 模块路线图 → plan_module 模块规划 → 跨模块校验收口）与老项目审计运维（查/改/模拟）跑在同一个 harness 上，工具调用、环境隔离、人在回路写权限、上下文、记忆五支柱保障 LLM 安全地围着确定性引擎工作。

数值建模主链（价值核心）

从游戏框架到全套模块数值，全程「LLM 产结构、引擎产数值」——agent 不只是查表工具，它承载完整的数值建模职责：

[游戏框架 confirmed 产物] workspaces/star-hero/framework.json
   moduleRoadmap（品类→模块优先级）+ systemBlueprint（养成线开闭）
   │
   ▼ 约束注入（buildPlanningDirective → system prompt，与 planning 路由 injectConstraints 同构）
   建模职责三纪律 + 模块路线图 + 蓝图线开闭 + 7 模块 intent 精简规范
   │
   ▼ agent 循环（LLM 语义路由 → plan_module；每轮文本流式 text_delta 直发前端）
   intent = moduleType / decisions / strategy / anchors 三段结构（LLM 只产结构，不产数值）
   │
   ▼ plan_module 工具内四步闭环（确定性，非 LLM 估算）
   ① 引擎外模块诚实拒绝——无确定性引擎支撑则不产出任何数值主张
   ② INTENT_VALIDATORS Zod 严格校验——失败回填 issue path + message，agent 循环多轮自纠
   ③ computeFromIntent 确定性计算——完整数值方案全部出自引擎
   ④ crossValidate 跨模块校验——framework.json 作 game-framework 上游条目，13 规则
   │
   ▼ 方案摘要回填轨迹（锚点采样 + 关键产出特征 + 校验结论，KB 级，<5KB 测试防线）——防轨迹 30k 截断吞方案
   │
   ▼ 总表收束——四大主线（battle/economy/progression/level）确认产物 → experience-expectation 确定性引擎汇总
   → 玩家体验预期总表（0 LLM），指导后续配置表关联（预留）

运行时

一次请求的微观循环：[用户输入] → /api/agent（限流 → 鉴权 → 余额守卫），先过一道复杂度路由，随后进入 lib/agent/loop.ts ——代码强约束的状态机（while + 权限门 + 轮次上限），六步一轮：

1. 1
   状态加载

   system prompt 装配：角色 + 工作区挂载状态 + 项目记忆注入（存在才注入，不撒谎；规划工作区另注入框架产物约束——见建模主链）

2. 2
   规划

   LLM 基于工具语义自主路由（tools JSON Schema 注入，经 mode 三档 × 工作区 kind 双维过滤——非本工作区工具不进 LLM 面；每轮流式 text_delta 直发前端打字机渲染，聚合结果与非流式逐字段等价）

3. 3
   行动

   tool_calls → 权限检查（read 直行 / write 分级：write_table 走人工确认回路，save_memory / restore_table 低风险由宿主直接放行）

4. 4
   执行

   ToolRegistry 分发 → 引擎纯函数 / 工作区文件（路径沙箱禁逃逸）

5. 5
   观察

   结果回填 tool 消息（30k 截断 + 60k history 累计预算护上下文）；同一工具连续失败 3 次注入换思路提示

6. 6
   状态写回

   会话 history（前端持有 + sessions 持久化）+ 项目记忆文件（save_memory）

↻ 循环至模型给出最终回答，或触及轮次上限（强制收尾：基于已获得的信息作答）

保障层：四要素映射与选型理由

harness 为什么存在——建模主链把「产数值」的权力全部收归确定性引擎后，剩余风险集中在 LLM 侧行为：乱调工具、路径逃逸、未确认写盘、上下文撒谎、跨会话失忆。五支柱（工具 / 沙箱 / 权限 / 上下文 / 记忆）逐一封掉这些口子，让 LLM 安全地围着引擎做建模与审计。每个要素都给出「本项目的实现」与「明确不做的工业方案及理由」——选型按信息密度与任务链长度取舍，不为炫技堆组件。

评测分层（引擎黄金集 + 编排层行为评测）

「LLM 管编排、引擎管正确性」的分界线同样切开了评测的两层——数值正确性与 LLM 行为正确性用不同手段验证，且判定器全确定性（不用 LLM 打分，与「不信任 LLM 数值产出」的哲学自洽）：

注册工具清单（34 个）

工作区 2 / 计算 8 / 结构 4 / 记忆 2 / 改表 3 / 规划 1 / 问卷 4 / 任务 2 / 项目 3 / 交付 2 / 推演 2 / 澄清 1，包装确定性引擎纯函数、工作区文件操作与项目数据读取；JSON Schema 注入 function-calling，由模型语义路由（工作台轨迹流中每次调用均带权限色标注）。

read_memory 为只读；save_memory 为纯追加低风险写（宿主直接放行，写实例 overlay）；save_structure 为结构 IR sidecar 低风险写（只写 structure.json 不碰数值表）；write_table 走 dry-run → 人工确认 → apply-write 落盘两段式，restore_table 从 .bak 备份恢复；write_plan_rules 改规则层（planning-rules.json 单源：列生成规则 + confirmed 派生边），受影响配置表由确定性引擎沿派生边传播重算—— dry-run 多表 diff → 人工确认 → 逐表落盘（每表 .bak）；plan_tasks / update_task 为任务板低风险写（宿主直接放行，全模式可用）——需求拆解为带完成标准的任务并前向跟进 状态（done 必附 evidence），uiPayload 驱动工作台任务板实时更新；plan_module 为建模主链入口（intent → Zod 严格校验 → 引擎计算 → 跨模块校验，返回方案摘要——数值主张出自引擎计算，不写任何文件）；submit_answer 逐题记录为低风险写（宿主直接放行，仅 planning 工作区可写），finalize_framework 沿用 write_table 同款两段式（预演摘要 → 人工确认 → apply-write 落盘 framework.json，无 .bak——产物由答案确定性可重算）；list_projects / project_summary 按登录身份读取项目概览与单项目深览（项目数据经 ToolContext projectData 闭包注入，工具层零 DB 依赖，越权与不存在同文案拒绝）； experience_expectation 汇总四大主线 confirmed 产物直算玩家体验预期总表 （0 LLM），沿用两段式——预演快照 → 人工确认 → 前端直调既有 planning-state 端点落盘（LLM 不可触达落盘）；acceptance_report 服务端确定性重算体检结论 （读时重算只算不存，结论永远对齐当前 confirmed 数据）；export_deliverable 按域分发下载载荷（project 域走 /api/export 深链、workspace 域 inline 内容下发，容量护栏超限诚实拒绝，下载动作仅由用户点击触发）；simulate_progression / preview_difficulty 包装 growth-projection 与 difficulty-mirror 引擎做 what-if 推演（battle confirmed 产物为输入，档位口径与 UI 单源对齐）。

关键机制（操作与审计端的展开点）

操作类能力（查 / 改 / 模拟）构成审计运维端——建模主链的便利性与可信性辅证：已上线的项目可导入为工作区，用同一套引擎做反推、对账、安全变更。

1. 1.规则级改表

   外包项目实测全表等差驱动（攻击 100+5/级）→ 改表语义是改生成规则不是逐格改值：infer_column_rule 从列数据反推生成规则（等差 / 等比 / 幂律稳健拟合 + 手调断点定位），write_table 的 apply_curve 操作（等差 / 等比 / 表达式锚点公式）整列重算，audit_column 用锚点公式对账定位手调断点——推断 → 对账 → 重算共用同一表达式语言。

2. 2.两段式人在回路（表格覆盖类写操作）

   serverless 安全，跨请求零状态：LLM 调 write_table → 宿主 confirmWrite 闭包 dry-run 出 diff + 双曲线序列 → SSE confirm_request → 变更审查面板（规则摘要 / 双曲线 / 影响评估）→ 用户确认 → apply-write 端点落盘（.bak 备份 + 单步撤销）→ 自动续问让 agent 复核影响。LLM 无法触达落盘端点——落盘只源于用户的确认点击：confirm_request 随载荷签发 write token 凭证（绑定工作区/工具/模式/用户/参数摘要 + 30 分钟时效），apply-write 验签 + 模式单源重验，缺失/篡改/过期一律 403 fail-closed。写权限按风险分级：save_memory（纯追加记忆）、restore_table（从备份恢复）为低风险写，宿主直接放行，不用确认弹窗打断低风险操作。

3. 3.影响评估连动

   确认依据是影响不是 diff——面板呈现改前 / 改后 L1/Lmax 双锚的战力 / 击杀刀数 / 咬合评级对照（compute_power + simulateBattle 连动）。

4. 4.上下文工程

   system prompt 动态装配（工作区真实挂载状态 + 记忆注入，不撒谎；规划工作区注入框架产物约束——建模主链同款机制）；工具结果 30k 硬截断 + history 累计预算 60k（超限从最旧 tool 消息循环压缩到 2k，最近 2 轮豁免——长会话 context 膨胀治理）；工具面按工作区 kind 裁剪（workspace-tool-policy 单源，与 mode 三档正交组合）；工具描述即路由依据（语义决策而非关键词）；GLM 上下文缓存为自动智能缓存机制（无需手动标记，命中低价计费）——BASE_SYSTEM_PROMPT 固定在最前 + tools schema 每轮恒定，prefix 已缓存友好。

5. 5.需求复杂度双路由

   纯函数零 LLM，两端各设一道闸：前置澄清启发式——写动词叠加复杂信号（≥2 改数子句 / 跨表意图 / 无目标参数 / 笼统范围词）命中即注入「先澄清」指令（只读工具可用、关键参数未定不得 write_table），把「参数没定就改」拦在 dry-run 之前；末端确定性验收——确认落盘后宿主检测续问标记注入验收指令（agent 用 read_table / audit_column 回读对照），叠加 verifyPersistedWrite「改前快照 × 参数纯重放 vs 落盘回读」全表逐格比对，首格不一致即定位报告。

逆向链（brownfield 接管）

老项目接管：从裸配置表逆推设计意图，与正向规划链构成同一张四层 IR 图谱的两个遍历入口——建模主链（正向从框架生成）与审计链（逆向从表反推）在图谱层汇合。

1. 1.L3 列规则（已上线）

   infer_column_rule 从列数据反推生成规则——Theil-Sen 稳健初值（防手调断点 masking）+ OLS 精化 + 断点定位；推断出的表达式零胶水喂给 audit_column 对账与 apply_curve 重算（共用同一表达式语言）；compareColumnRules 四态对比（consistent / rule-change / breakpoints-added / rule-broken）注入 confirm_request.ruleDeviation，变更审查面板分色预警规则偏离。

2. 2.L2 表关系与结构 IR

   infer_table_relation（已上线）推断表内列间派生结构（B≈A×k 系数关系；取整容限 0.5×(1+|k|) 防取整误报；中位比率初值 → Σb/Σa 精化；基准锚点列发现）；引擎黄金集（workspace-eval）十三步链式断言。表间结构已上线：infer_foreign_keys 外键值域包含检测（悬挂率 <5% 立边）；structure.json 结构 IR sidecar（判级 / 表角色 / 关系边 / 意图卡），状态机 inferred→confirmed/rejected，用户确认闭环（save_structure 固化，推断重跑不冲用户裁决）。

3. 3.四层图谱

   L1 游戏框架 / L2 模块规划 / L3 具体功能 / L4 配置表——图谱是工作区的结构化状态而非执行流水线，正向（规划链：planning 页与 agent 建模主链）与逆向（agent 审计）是同一张图的两个遍历入口，逆向产物复用正向链既有 schema（不另造格式）。

4. 4.三级分级输出 + round-trip

   逆向输出分三级——结论（确定性直推）/ 假设（附置信度 + 证据链）/ 缺口（转问卷补全），L1 逆向重建协议段已上线（proposed 意图卡注入 + 三级分级执行约束）；round-trip（重建规则正向重算 vs 真实表逐格对照）已固化为引擎黄金集步13 回归断言（L2 数值往返零漂移 + 战力成长性锚点）。

工作区双形态与双 Demo 场景

线上部署双工作区，workspace.json 的 kind 字段分流（describeWorkspace 按形态给不同挂载文案）：

债务与边界（诚实声明）

• 结构 IR 的 confirmed 裁决留用户会话完成；save_structure 线上只读部署走实例 overlay（同 write_table 边界）；确定性关系「自动 confirmed」以保守侧实现（全部候选 inferred 待用户确认）
• 影响评估当前窄版（hero / 成长表 + 敌人表锚点），schema 映射层留扩展位
• 战斗模拟为面板对拼模型（格挡 / 均衡量 / 弹反未建模，近似声明随结果返回不静默）
• plan_module 返回摘要不落盘（完整方案以摘要锚点为准，规划产物落盘确认回路为 Follow-up）；flash 模型产大 intent 的失败率由 Zod 回填多轮自纠兜底（smoke 输出每轮耗时供 60s 时限分析，不硬断言）
• 线上部署含双形态工作区：肉鸽格斗（审计，24 表规范化 JSON）+ 星之勇者（规划，framework.json 建模链）；写操作经实例 overlay 生效（同一温实例内读写自洽），冷启动回滚至 git 基线——演示环境已知边界，生产持久化接 Supabase / Blob