Sponge Position Agent

@guobaigei/cheese-agent 是 HM2.0 岗位能力的独立 Package。岗位类型、字段规则、草稿合并、校验、Payload mapping 和写操作编排都以 Sponge 为唯一事实源；HM 与 Roll 只是不同宿主。

HM / Node / CLI -> SemanticPlan -> Command Compiler -> 8 Tools
Roll 原话/短引用 -> Sponge SemanticPlan -> Compiler ------> 8 内部工具
8 Tools           -> Application -> Position Domain -> PositionGateway -> HM API

HM/Node/CLI 每个自由文本业务轮次最多调用一次 planner；模型只输出带证据的 SemanticPlan，Compiler 再生成严格的内部 ToolDecision。结构化候选的合法序号或完整标签选择走确定性恢复。Roll 只调度，芝士使用现有模型处理语义并管理持久化会话。两条入口最终复用同一字段校验、补齐、领域和写入边界。

关键不变量和实现边界见架构说明书。字段路径、值 schema、职责、枚举、权限和联动以 src/position/positionFieldContract.ts 为唯一来源；字段契约使用说明不再维护另一份字段模板。

当前源码已完成统一字段契约 v2 的本轮修复，尚未发布，不能等同于下面安装示例中的 0.4.4。已清理旧语义别名测试并补充当前契约、补齐范围、成员定位、写入保护及 Roll 补查回归。2026-09-20 最近一次全量验收的 216 个原编号为：200 通过、9 失败、6 部分覆盖、1 前置阻塞；随后分阶段定向修复中，9 条失败原用例均有修复后的真实模型通过记录，C-011 定位测试的前置问题也已修正。最终 Sponge 类型检查、确定性测试和构建通过；其余 5 项部分覆盖与籍贯字典阻塞仍保留。这些结果不代表再次执行全量验收或完成真实 HM 写入联调，原始记录保留在本地 docs/testLog/。

Planner 仅在用户本轮明确改变补齐范围时输出 completionChange{mode,scope,evidence}；不输出即继承当前任务，内部 completionIntent 只存有效状态。批量逐项限制放在 itemFacts，不能扩散为整批约束。Provider 不拥有问题来源和关系运行状态；这些标记由投影及应用层维护。

HM 批量创建在当前 OS 用户 ~/.sponge/write-records/ 保存执行指纹和结果，按 HM 地址与凭据摘要隔离；不保存鉴权凭据。请求前持久记录未知状态，成功及未知项不随“重试失败项”重发，取消草稿也不清理记录。目录必须可写，容器部署应将该目录持久挂载；损坏、残留执行锁或未知结果须先人工核实，不自动删除、解锁或猜测成功。会话中的 unknownWrites 独立于可编辑草稿保留，既有 Roll 执行锁继续保护进程中断。此改动不新增环境变量或 HM 端点。

HM HTTP 会话保存在 ~/.sponge/http-sessions/，按运行环境、HM 地址和凭据摘要隔离。浏览器只保存会话 ID 与 revision，不再保存或回传完整业务状态；GET /api/sponge/positions 只读恢复既有公开结果。容器中的 ~/.sponge 必须使用生产、测试相互独立的持久卷，不能通过清空卷解除未知写入保护。

源码仓库目录结构

sponge/
├── docs/                         # 架构、字段目录、真实语料与回归规范
├── references/env.yaml           # Roll/standalone 环境变量声明
├── src/
│   ├── index.ts                  # 根稳定 API 白名单
│   ├── cli.ts                    # 本地 chat 调试入口
│   ├── core/                     # Session、ToolDecision、公共协议与通用工具
│   ├── model/                    # HM/Node/CLI SemanticPlan planner 与草稿建议生成器
│   ├── position/                 # 岗位 Domain 唯一实现
│   │   └── payload/              # draft/create/update Payload mapper
│   ├── application/              # PositionGateway 与岗位用例编排
│   ├── positions/                # Command Compiler、内部 ToolDecision、字段注册、八工具及编排
│   ├── adapters/                 # HM2、HM API、standalone 和 Roll 宿主适配
│   └── tests/                    # characterization / contract tests（不入发布包）
└── package.json                  # exports、rollAgent metadata 与发布白名单

position/ 是不依赖宿主的岗位领域层，positions/ 是 Agent 工具编排层；二者不得互相复制校验、详情或 Payload。HM 侧只保留仍被页面引用的薄 re-export facade 和 UI 展示/表单适配，迁移后的旧实现文件已删除。发布 tarball 不包含 src/、测试或内部改造计划。

Public API

• @guobaigei/cheese-agent：runSpongeTurn、executeToolDecision、Session、SemanticPlan、编译后 ToolDecision 和依赖协议。
• @guobaigei/cheese-agent/position：统一字段契约及其派生岗位类型、标准化、校验、详情转草稿、Payload mapper，以及岗位详情与预览共用的纯展示转换。
• @guobaigei/cheese-agent/core：核心协议、Session、芝士维护的能力说明，以及 sponge-public-v2 的严格输入/输出 schema 和浏览器安全投影。HTTP 与 Roll 共用 presentation + explanation；explanation.modelDescription 原样保留同次 Planner 的中文说明，无说明为 null，页面不展示分析。预览为有序 sections/groups/rows，叶子来源独立，问题按岗位关联；公开预览和岗位详情共用 position/positionDetailViewModel.ts 的纯展示转换及 PositionDetailContent；rows[].display 保存原详情组件的展示类型和值，fields 仅承载来源、变更及问题定位。图片 URL 在 Web 渲染边界解析。HTTP/Roll 记录版本为 4，旧响应记录保留并要求重新开始。公开 v1 缓存与会话不兼容，不迁移旧预览，Roll 另保留自身调度控制字段。HM Agent 列表不能从此处的业务能力目录生成，必须以 Roll 当前会话的能力数据为准。
• @guobaigei/cheese-agent/hm2：HM 受信宿主适配、HmPositionGateway 和 Application 依赖构造器。
• @guobaigei/cheese-agent/roll：Roll MCP stdio 启动入口。

Package 不提供 /runtime 子路径。Roll CLI 已经承担 Roll 场景的 runtime；Node/HM 直接使用根出口和 /hm2。

HM Web 通过部署变量 SPONGE_TRANSPORT=http|roll 选择入口，默认 HTTP；该开关属于 HM 宿主，不是 Package 工具参数，也不改变芝士业务内核或模型配置。HTTP 与 Roll 的会话分别维护，外部补查恢复仍由 Roll 入口承接；部署和切换约束见仓库根 README。

Roll Tools

Roll 暴露 preview（写操作预览）、resume_query（只读补查恢复）、execute（执行当前操作）、get_capabilities（统一 Markdown 操作说明书）、get_context（只读恢复）；独立岗位查询不走芝士，写流程内部仍保留目标定位与详情读取。调用约束见 SKILL.md。以下八个工具保留为内部实现：

• query_jobs：查询普通岗位候选或岗位草稿箱列表
• view_job_detail：查看普通岗位或保存草稿详情
• create_job：新建、基于岗位/草稿复制新建或载入草稿继续完善
• batch_create_jobs：同一项目、品牌下按岗位变体和门店批量生成独立岗位
• edit_job
• batch_edit_jobs
• preview_job
• operate_job

芝士的操作说明书唯一内容源为 src/core/capabilities.ts 中的 CHEESE_OPERATION_MANUAL，只包含「芝士介绍」和「两个最佳实践」。HTTP 首页、HTTP/CLI 的能力说明回复和 Roll get_capabilities 共用该 Markdown，不按入口维护不同版本；旧 SPONGE_CAPABILITY_MESSAGE、CHEESE_WRITE_CAPABILITY_MESSAGE 导出保留为同一内容的兼容别名。询问操作说明书只展示内容，不执行示例，也不清除当前岗位预览。

HM 在 Roll 模式下通过现有对话通道获取当前可用 Agent 列表，并请求所选 Agent 的只读操作说明工具；Web 按 Markdown 渲染，不维护固定 Agent 名单或另一份说明。目录/说明使用独立信息会话，不混入岗位编辑；结构化预览通过 Wire 1.2 getResult(operationId) 消费 cheese.public-result@1，不从 display 或文字回复重建。

芝士原生 MCP 工具以 structuredContent 返回共享公开正文 {conversation?,presentation,explanation}，声明 roll/appOutput；最小调度与补查信息通过模型可读的内嵌资源返回，不混入公开 fallbackText。SDK 0.6.0 的自动整对象封装不适合双出口，因此适配仅在本仓库 MCP 边界实现，不修改 Roll。当前源码的内部 SessionState 使用 position-fields-v2，Roll 记录版本仍为 4：公开动作和答案绑定由当前签名记录重建，不新增持久字段。完整状态在芝士本地签名持久化，按身份/环境隔离；重启可恢复，七天不活动过期，保留写入结果未知的记录。预览不写入，execute 校验当前版本并执行已保存参数。

Roll Web 按钮通过自然语言转交短会话、版本和公开 action-N / 问题候选引用，芝士从当前记录解析；不会直接调用工具，不保证 Roll 模型必然正确转交，失效引用必须停止而非自动替换。HTTP 保持原有结构化请求。接入需 Runtime 1.5、Wire 1.2、relay-client 0.2.0，以及本机精确 remoteAppOutputs 授权；本次不自动修改配置或发布包。详见 接入说明。

create_job 准备新建草稿；edit_job 在用户给出修改内容后生成或更新编辑预览；batch_create_jobs 按“公共字段 → 岗位变体 → 门店项覆盖”生成独立岗位预览，每个门店独立补齐并保留来源、校验和续轮草稿，所有门店必须解析到同一真实项目和品牌；batch_edit_jobs 为每个目标读取详情并维护独立的完整编辑草稿，内部复用普通编辑的补齐、联动和校验，首轮即收敛全部可建议必填缺口。批量编辑的共同值放 fields，逐岗差异首轮和自然语言续轮都按有序目标使用 targetIndex，Compiler/工具边界再映射为稳定 itemId；普通和结构化列表统一使用 set/clear/append/remove；结构化成员通过稳定 ID 或原结果序号定位，保留未提及成员。当前校验项的共享回答按逐岗字段成员合并，“帮我补充”处理全部未完成项。用户查看预览后发出保存、发布或应用修改指令，再由 operate_job 执行 save_draft、publish_draft、apply_edit、publish_batch_jobs 或 apply_batch_edit，不再二次确认；提供新的修改内容仍只更新预览。应用编辑保持原发布状态。上架和下架由 operate_job 在明确目标后直接执行。批量新增和批量编辑均限制为 2 到 20 条，分别逐项调用 /newhm/job/create 和 /newhm/job/update。部分成功时锁定成功项，用户要求重试时只处理失败项；返回总数、成功数、失败数、岗位 ID 和真实失败原因。单岗和批量完整更新前重新读取详情，与最初加载的版本对比；发生冲突则保留修改并提示重新加载。保存草稿回填真实草稿 ID；无法唯一找回 ID 时引导从草稿箱继续。cancel 清理尚未写入的草稿。HM HTTP UI 点击公开 action-N 时连同当前会话版本回传，服务端恢复原始结构化动作；Roll 继续使用其当前上下文中的 availableActions。两条线路都不把按钮标签交给 Planner 重新识别。

Roll 三种入口的分工：

0.4.4 的 lookupRequest → resume_query 按需补查契约见架构说明 Issue #12：结果按本次原序号或批量完整集合要求校验；恢复读取失败保留请求和检查点，读取恢复后可继续同一只读请求。本地使用模拟查询验证；真实 Roll/丸子协作仍待联调验收，发布版本不代表生产链路已通过。

当前未发布源码进一步明确 resume_query.result 必须为 JSON 对象，并统一 referenceSource 的身份字段与校验；旧中文列名只做确定性映射，未知或冲突字段拒绝。新增回归尚待执行；具体字段与恢复边界见上述架构说明及 SKILL.md。

• roll run --json：确定性调用和发布门禁，适合固定输入、固定工具与机器校验。
• roll ask --json：简单、单轮自然语言冒烟，验证 Roll 的工具选择。
• roll chat：多轮草稿、补充字段和直接写入流程的交互验证。

安装与运行

从 npmjs 安装已发布的公开 Package：

roll agent install '@guobaigei/[email protected]'
roll agent tools cheese-agent

以下本地源码调试和发布验证命令均从 monorepo 根目录执行。本地注册前先构建； build 会先执行完整 TypeScript 类型检查，再生成 dist：

pnpm --filter @guobaigei/cheese-agent build
roll agent add "$PWD/sponge"
roll agent tools cheese-agent

CLI 同样运行构建后的 dist：

pnpm chat -- --help
pnpm chat -- --json --write-mode deny

--write-mode deny 会在 HM 网关写入边界拒绝自定义面试标签、岗位保存/发布和上下架请求，适合只读 bad case 验收；默认 allow 保持日常交互能力。报名表单使用 interviewExtLabels 的统一字段 patch，省略时保持原值；仅具体社会身份（非“不限”）和已配置健康证类型的健康证要求会自动追加对应缺失固定题，其他用人要求不自动勾选报名题目；已有配置继续保留，冲突操作保留局部问题。新自定义题使用契约中的字段类型与选项结构，缺少必要成员时保留校验项；新自定义面试标签和新选项只在用户确认岗位写操作后物化，预览不会产生历史标签。--json 额外输出 Compiler 生成的内部 ToolDecision、前置会话状态和 trace，便于分别定位语义计划、编译和工具执行；ToolDecision 不是模型的直接输出。

Standalone 环境配置

Roll/standalone 业务出口需要以下变量；Roll 语义入口另需现有模型配置（默认 DEEPSEEK_API_KEY，完整声明见 references/env.yaml）。缺少当前 provider 凭据时启动失败：

HM_BASE_URL=<测试或生产环境 newhm 地址>
HM_DULIDAY_TOKEN=<与该地址匹配的凭证>

HM_BASE_URL 是唯一目标环境来源，HM_DULIDAY_TOKEN 只负责鉴权。不使用 NEW_HM fallback，也不提供通过工具参数临时切换环境或凭证的能力。日志不得输出 Token，只能记录脱敏后的 API origin。改造和验收期间的真实写入只使用测试环境。

HM Web 的 Cookie、Next Route、日志和请求上下文仍由 HM 宿主负责，再通过薄适配层构造 Sponge 依赖。

开发与发布验证

验收准备与执行说明见 run-tests。旧 Excel 作为冻结场景来源，参数化步骤按当前契约拆分执行。验收复用现有 test 入口：--acceptance --mode offline|model --run-dir <新目录> --case-budget-ms <执行器单用例预算>；默认仍为 8 条代表用例。全表采用 --suite workbook|batch 配合 --mode model，以及 --suite system|faults 配合 --mode offline。两组模型场景可加 --cases 指定编号，确定性组执行全部子项。每组使用新结果目录，业务读写隔离在内存网关中；原始断言与链路复核分别保存，不能把局部通过等同于全字段或真实 HM 联调通过。

只有获得用户测试授权后才运行下列命令；准备测试代码不代表执行授权。

pnpm --filter @guobaigei/cheese-agent typecheck
pnpm --filter @guobaigei/cheese-agent test
pnpm --filter @guobaigei/cheese-agent build
pnpm --dir sponge pack

prepack 会在打包前强制执行 build。发布包只包含 dist、本 README、SKILL.md、references/env.yaml、架构文档、岗位字段文档和 package.json；源码、测试、改造计划、bad case 与日志不会进入 tarball。

正式发布使用 Package 内置的 package 命令。它会加载 env/.env.local 中的 NPM_TOKEN，依次执行 typecheck、test，并通过 prepack 强制 build，最后发布到 https://registry.npmjs.org/：

pnpm --dir sponge run package

该命令发布 sponge/package.json 中的当前版本，不自动修改版本号；如果该版本已存在，先显式升级版本。脚本只在发布子进程中加载 sponge/.npmrc.publish，其中只保存 ${NPM_TOKEN} 占位符，不保存真实凭证。命令使用 --no-git-checks 允许发布当前未提交工作区，但不会跳过 typecheck、test 或 prepack build。

文档

• 本 README：Package 边界、安装、运行和发布。
• 架构说明书：运行时不变量与实现契约。
• 字段契约使用说明：实际字段路径、patch、来源保护和联动的使用方式；完整目录由代码契约派生。
• Roll Agent 说明与环境变量声明：Roll 的机器可读调用约束。
• 源码仓库内的 docs/run-tests/SKILL.md：真实语料回归、冻结预期和结果归因；docs/测试用例.md 保存测试语料。两者不进入发布包。