安装与代码验收

完整验收

完成 doctor 和必要的 CLI 准备/验收后，从目标根目录运行：

python3 tools/FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/project.py work resolve --project .
# Agent 根据 activeRules 修改代码
python3 tools/FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/project.py work check --project . --receipt RETURNED_UUID

RETURNED_UUID 是占位，使用成功 resolve 返回的 nextSteps.cwd/argv 中的准确 ID；不手填多份 context，也不选最近一次。新 work 入口不构建、不联网，要求已有 CLI 发行和匹配 build receipt；缺失时先显式准备，再运行 CLI 验收/resolve。内核输出位于 kernel.output，仍按原 schemaVersion 校验；旧 resolve/check 默认输出和退出码保留，也保留原构建行为，但不具有关联证明。

resolve|check 还可用 --work-mode normal|test|dev 透传逐任务工作模式，例如用户明确指定测试代码时 project.py resolve --project . --work-mode test，或用户明确指定 dev 代码时 project.py check --project . --diff /tmp/change.patch --work-mode dev。该参数不写入 .ftckb/project.yaml，不改变固定版本、team、season、profiles 或托管文件；省略时保持原命令与输出。--work-mode dev 缺少 --diff 时包装器拒绝执行。模式不能按文件名、路径或依赖推断，只有用户明确指定才使用；包装器会核对内核响应确实回报了请求的 workMode，避免旧内核静默忽略。

工作收据边界

固定源码已有 doctor 但尚无 work 入口时，用已审阅新 checkout 的绝对入口 python3 /path/to/reviewed-FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/project.py work resolve --project /path/to/FTC-project；保留目标 pin，后续沿返回的 nextSteps 使用同一外部入口，不自动升级。

work 的独立 envelope/file 为 workReceiptSchemaVersion:1；退出0为真实成功且关联验证通过，退出1为真实 check 硬违规，退出2为收据/上下文/接入/运行错误或冲突，退出64为新参数错误。kernel:{exitCode,output} 保留真实内核结果，不往 kernel JSON v2 加字段。

收据位于实际 Git directory 的 ftckb/receipts/<UUID>.json；若自定义 gitDir 在工作区内且不位于 .git 子树，明确拒绝，不修改 ignore 或迁移数据。允许普通 linked worktree 的外部 metadata；收据不进入项目工作区、不自动 commit、不改 audit，不自动选择 latest。它绑定 root/gitDir、配置原字节、team/season、原/规范 profiles、协议、pin、实际 knowledgePath、全部实际小写 .yaml/.yml 的路径/内容摘要和本次 mode，含 Git ignored 规则。任何这些输入变化都必须重新 resolve；v1 profiles 仍为 null，不变成 generic。normal 不静默继承 test/dev；dev check 必须提供本次 diff。普通机器人代码修改/提交和重复 check 允许，不设时间 TTL，不消费收据；用户可自行删除旧文件。

work 收到内核 stderr 时，在独立 envelope 返回安全分类的 diagnostics/auditStatus：审计存储失败为 incomplete，输入版本或其它诊断为 unknown，不暴露原始敏感内容；无诊断不添加这些字段，也不证明审计完整。用户摘要必须报告审计不完整/未知及诊断项。work 保留真实 kernel JSON/退出码和既有收据创建/关联语义；收据绑定实际执行不代表独立审计完整。CLI accept 对已报告的审计存储失败仍停止后续验收阶段。

调用前后重验上下文，传入diff时也核对其字节；中途变化即返回关联失败，并保留已执行的实际内核事实。收据是本地摘要，不是签名/身份/审批/不可抵赖审计；同用户可重算伪造，前后快照也不是抵御同权限 ABA 的事务。缺失、损坏、symlink 或不匹配时明确重新 resolve，不猜配分开的 audit 调用。compile/deploy/真机仍分别验证。

旧兼容入口仍可显式调用（不创建或使用工作收据）：

python3 tools/FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/project.py resolve --project .
python3 tools/FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/project.py check --project .

旧兼容完整验收（可能构建并立即运行内核；首次接入优先使用上面的分阶段入口）：

python3 tools/FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/verify.py --project .

输出/退出码	意义
`installationOk=true`、`projectCheck.ok=true`，0	接入有效且本次 diff 硬检查通过；仍有 soft 待评估
`installationOk=true`、`projectCheck.ok=false`，1	接入有效，但目标已有或新增硬违规，不能交付为通过
`installationOk=false`，2	配置/版本/构建/schema/知识加载或规则冲突等错误

project.py 的成功调用透传 kernel JSON 和退出码（check 0/1/2/64）；包装器自身失败是独立 integrationOk=false 输出，不冒充 kernel 成功。验收不推断违规是谁引入的；Agent 应记录开始时的工作区基线并如实区分。

错误恢复

其他队员克隆已经提交了接入配置的项目后：

git submodule update --init -- tools/FTC-Knowledge-Bank
python3 tools/FTC-Knowledge-Bank/.agents/skills/ftckb-integrate/scripts/verify.py --project .

旧 v1 项目保持原固定 SHA，不自动迁移。v1→v2 升级必须显式选择 profile；已有有效 v2 配置升级时可以保留原选择。升级时显式选择新版本，先 dry-run，再运行安装器的 --ref NEW_TAG_OR_SHA。它更新 gitlink、配置和未被人工修改的模板，重新构建并验收。没有 --ref 不升级；不要 git pull submodule 或 git submodule update --remote。

构建失败：托管文件和固定 submodule 保留，修正 JDK、缓存权限或网络后重跑安装或 verify。版本/路径冲突：先查看 git status、.gitmodules、配置与 submodule HEAD，不直接 reset/删除目录。安装中途被强制终止可能留下 Git 注册或部分托管文件；脚本宁可拒绝未知残留，也不猜测并删除。审阅具体残留后人工恢复；不要执行全仓库 git clean -fdx 或 git reset --hard。