Instruction file imported from zengys2007/ZHIJIAO-HARNESS (
.cursor/rules/30-harness.mdc). Copyright stays with the author.
Harness 专项规则
核心职责
Harness 是一张编译好的 LangGraph StateGraph，负责一轮对话的步数和停机。MVP 成功是保存一条非空助手回复。它不应成为一个包含所有工具细节的巨型节点，也不等同于单一提示词。
典型流程以 docs/superpowers/specs/2026-10-21-mvp-roadmap.md 为准：一轮教师消息调用一次 invoke。图上有模型节点和预留的工具节点。生产注册表为空，不要求工具调用。
新能力以后登记为工具，不增加节点或边。不使用 create_agent、create_react_agent 或 langgraph.prebuilt.ToolNode。不编译检查点，不使用 interrupt，不开启 LangSmith。不实现点名器、计时器、投票器或 use_preset。
教学意图与工具调用
- 模型通过工具参数表达要生成的内容，参数必须符合该工具的 schema。
- 不把模型返回的任意文本当作系统命令或工具权限。工具名单只来自注册表。
- 关键信息不足时，MVP 用文字回复追问。
ask_teacher留到有发布工具的阶段。 - 不得向模型提供 Shell、任意文件读取或外网工具。
状态机
- 对外状态只有
pending、running、succeeded、failed，不得在前后端复制另一套阶段状态。 - 每个状态转换要有明确的触发条件。
- 失败时保存可诊断的错误类别和安全的用户提示。
- 只允许合法转换；失败不得覆盖本会话已成功的回复。有版本之后，失败也不得覆盖上一成功版本。
- 一轮的步数有限，且应区分可重试与不可重试错误。
- 工具调用和结果记在会话事件里，便于排查失败原因。
工具注册
- 工具通过注册表接入，并声明名字、说明、参数 schema 和执行函数。
- 生产注册表当前为空。不登记点名器、计时器、投票器，也不提供
use_preset。 - 未知工具名必须作为工具错误返回，不得静默换成别的工具。
- 新增产物类型时登记新工具，不修改图的节点和边。
统一产物协议
产物至少应描述：
- 唯一标识
- 类型
- 标题
- 版本
- 文件清单
- 元数据
- 能力声明（例如预览、导出）
协议统一元数据和生命周期，不强制不同类型产物使用相同文件结构。网页、Office 文件和 Agent 配置可以拥有各自的文件和运行方式。
协议字段应在一个可信位置定义。改动协议时同步更新工具、存储、API、前端类型和测试。
迭代与版本
- 修改请求应关联原产物和当前版本。
- 尽可能进行局部修改并保留已有功能；必要时才重新生成。
- 每次成功修改创建新版本。
- 生成或校验失败不得覆盖最后一个成功版本。
- 记录版本来源、任务关联和必要的变更说明。
- 避免在版本记录中重复存储不必要的大量数据；根据当前存储方案选择文件快照或引用。
校验与预览
- 校验在发布之前执行。校验失败只成为工具结果，不发布版本。
- 至少检查文件清单、结构完整性、类型正确性和基础安全规则。
- 校验通过不代表交互逻辑绝对正确；预览和必要的自动化检查仍然重要。
- 预览运行时与后端业务进程隔离。
- 不得在后端直接执行任意生成代码。
- 对生成网页采用适当的 iframe sandbox、内容安全策略和网络限制。
模型适配
- 模型节点调用统一的
complete(messages, tools)，不直接依赖供应商 SDK。langchain-core只作为 LangGraph 的依赖存在。 - 生产注册表为空时，请求不带
tools。注册表非空时，才带上投影出的 schema。适配层归一工具调用格式，不在业务代码里选择工具。 - 节点不设置
RetryPolicy。重试只发生在complete内部的那一次。 - 记录必要的耗时、状态和错误类别，不记录密钥或敏感数据。
- MVP 使用一个可工作的 provider 即可，不要提前实现复杂模型路由。
未来扩展边界
后续可按路线登记讲义、课堂编排和检索工具，并在进入条件满足后使用异步任务队列。MVP 只保留工具注册表这一个扩展点，不提前实现完整多 Agent 或分布式系统。
