跳转至

English

帮助与分诊

本页帮助开发者先选对入口,再按错误码、进程退出码与现象处理问题。Foundation 的错误码体系冻结在 Contracts(src/error-codes.json),不漂移;机制失败统一为 SFC2004 加稳定 details.kind。

先选入口

要解决的问题 入口 入口边界
不了解现有能力是否适用 foundation-adoption-review 唯一的自然语言采用诊断 Skill。它读取调用方提供的精确版本、能力目录查询结果和 adopt-plan 结果,给出完整匹配、部分匹配、候选匹配、无匹配或漏看已有能力
需要对目标做完整静态工程审阅或读取已有 Foundation 证明 foundation-engineering-check 同一 Plugin 内的静态工程审阅 Skill。它按所选范围审阅工程声明、公共能力采用和调用边界,再用 check proof-create 投影共同结论;读取旧证明用 check proof。版本与入口两个机械分支通过不等于全族通过
需要盘点存量项目与参考骨架的结构差异 planAdoption({ root, allowGitSpawn: false }) 或 adopt-plan --no-git-spawn 只读输出写集、冲突、风险和迁移完成条件;参考骨架不是所有项目必须复制的目录规范
需要核对现有工程声明和物理文件 runChecks、runCoreCheck、runEntryContractCheck 或 check 静态读取文件与配置,报告当前检查政策范围内的发现;不运行目标 Skill、业务脚本或 hooks
需要初始化空目录或写入受管投影 scaffold、projection 只有调用方已经授权对应写入时才使用;存量项目不存在通用 apply

采用诊断不安装或初始化项目,不执行 check、资格探测或宿主调用,也不替代 Audit(独立审计)的领域判断。它只解释调用方提供的事实,并把下一步指向具体公共入口。输入不完整时,结论保持候选或待确认。

治理检查与研发自测

治理检查面向被检查项目,核对声明、路径和实际文件是否一致。普通 check 只读;它不会启动目标程序,也不会证明整个宿主的所有文件操作、权限或内部工序已受 Foundation 约束。

研发自测面向 Foundation 自身。包测试、宿主驱动和资格测试只在项目明确授权的开发或验证流程中运行,用来验证 Foundation 的产品实现。研发自测通过不能替代目标项目的领域门禁、真实宿主资格或独立审计。

现有检查保留其既有政策假设,例如 Foundation 风格的版本源、入口形态和九类检查。只有目标项目确实采用这些政策时,结果才能据此解释;单包、独立发布单元、非 npm 版本源或其他入口形态不能被强行套入。稳定能力、候选能力和当前源码状态分别判断,精确边界以当前产品状态和所用版本的能力目录为准。

按稳定错误码分诊

错误码 名称 含义 处置
SFC1001 SCHEMA_VALIDATION_FAILED 文档未通过目标 Schema 验证 检查文档必填字段与类型约束
SFC1002 UNKNOWN_SCHEMA_ID $id 未在登记表注册 确认 $id 拼写与 Contracts 版本
SFC1003 DUPLICATE_SCHEMA_ID 重复 $id 注册被拒 不重复注册,复用已有登记
SFC1004 DUPLICATE_PROTOCOL_NAME 重复协议名/版本被拒 不重复登记协议
SFC1005 UNRESOLVED_REF $ref 目标无法解析 检查 $ref 指向
SFC1006 UNSUPPORTED_DIALECT 方言不在支持集 仅用 draft-07 / 2020-12
SFC1007 UNKNOWN_CHECK_TYPE 规则用九类外检查类型 不自定义检查类型
SFC1008 RULE_BUDGET_EXCEEDED 强制规则超预算/上限 不超 20(绝对 30)
SFC1009 UNKNOWN_ERROR_CODE 引用未登记错误码 只引用冻结登记表
SFC1010 FIXTURE_EXPECTATION_MISMATCH fixture 行为与期望不符 查 fixture 声明
SFC1011 UNKNOWN_PROTOCOL 引用未登记协议 确认协议名/版本
SFC1012 SCHEMA_COMPILE_FAILED Schema 本身无法编译 查 Schema 语法
SFC2002 UNKNOWN_OPERATION 操作名不在冻结词汇表 只用 validate
SFC2003 INVALID_PARAMS 参数不满足 params 合同 检查参数
SFC2004 EXECUTION_FAILED 机制执行失败 看 details.kind 细分
SFC3001 REPORT_DIGEST_MISMATCH 报告/结果摘要与绑定不一致 重算 model/result
SFC3002 REPORT_ELEMENT_MISSING 报告缺强制元素 补全报告字段
SFC3003 REPORT_FACT_DRIFT 报告字节偏离确定性重渲染 用机器结果重渲染

按进程退出码分诊(Engineering Kit)

退出码 含义 处置
0 成功 / 无发现 无需处置
1 check 有发现 处置发现项,Kit 不自动修复
2 拒绝 / 用法 / 机制错误 检查命令名、参数与 --fix 等被拒旗标

按现象分诊

  • 校验一直报 SFC1002:$id 未注册,先确认 Contracts 版本与 $id 命名空间。
  • 路径操作报 SFC2004 + path-traversal/symlink-escape/realpath-escape:路径越出受收容根,确认根目录边界,不要把业务选择规则塞进 Foundation。
  • 原子写报 SFC2004 + atomic-write-failed:目标越界或内容类型非法,检查路径收容与内容类型。
  • 状态存储报 store-locked:旧写者可能仍持有锁;在 Foundation 外确认旧写者已终止,再用精确 owner/fencing 调用 recoverStateStoreLock。
  • CLI host apply 直接失败:Engineering Kit 的 adopt-plan host-apply、通用或远端 apply 仍稳定拒绝。包 API applyHostPlan 只执行已登记宿主的摘要绑定本地 install/update;执行 uninstall 计划会返回 manual-recovery-required,不删除文件。Qoder 完整 driver 仍为 unsupported。
  • 同级 adapter 验证失败:verifyHostPeers 只接受由已登记 Profile 证明的宿主和路径类别;任一 peer 的路径、闭包、字节或 logicalMappings 不一致都会失败关闭,不会授予安装或发布状态。
  • 文档版本/命令对不上真源:以 scripts/docs/fact-check.mjs 复算结果为准,不凭记忆修订。

项目路由

  • 精确版本中的能力是否适用 / 现有方案是否重复 → foundation-adoption-review。
  • 完整静态工程审阅 / 读取已有 Foundation 证明 → foundation-engineering-check。
  • 发布远端状态 / npm 发布 → release-skill。
  • 任务 / 重试 / 返工 / 验收 → loop-agent。
  • 制品关系 / 版本锁 → artifact-graph。
  • 领域审计语义 → 独立审计消费者。
  • 通用结构 / 机制问题 → 本仓 docs/architecture.md 与 docs/agents/。

命令速查与权威事实

Engineering Kit 只有四个顶层命令:scaffold、adopt-plan、projection、check。其中 check 只诊断不修复,发现项交调用方处置。

  • 当前产品状态(版本、包集合、镜像坐标、门禁):当前产品状态(唯一状态页)。
  • 开发与提交规范:Git 生命周期指南。