帮助与分诊¶
本页帮助开发者先选对入口,再按错误码、进程退出码与现象处理问题。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 仍稳定拒绝。包 APIapplyHostPlan只执行已登记宿主的摘要绑定本地 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 生命周期指南。