NetPilot Harness

为已有项目安装 Codex 可按 scope 读取的项目规则、文档骨架、路由和窄职责项目 Agent。Harness 只写当前项目，不调用 Skills 安装器，不安装用户级 Skills、Agents 或宿主配置，也不生成业务代码。

快速开始

要求 Node.js 满足 package.json 的 engines，并让当前目录成为真实、非 symlink/junction 的项目根：

npx @netpilot/harness@latest

零参数命令会直接安装：

• 空项目（可仅含 Git 元数据）默认使用 fullstack-typescript；
• 已有 .agents/project/project.yml 时沿用已确认配置；
• 其他已有项目先按证据严格识别：唯一匹配时自动选择，无法匹配时回退到默认 fullstack-typescript，多个候选同时匹配时才要求显式指定。

只预览使用：

npx @netpilot/harness@latest --dry-run

需要确保选择 npm latest 时保留 @latest，以避免复用项目内同名旧依赖；不带版本的 npx 不保证远程最新。团队和 CI 应固定经过验证的完整 SemVer。

Recipe

| Recipe | 场景 | 选择方式 | | --- | --- | --- | | fullstack-typescript | pnpm monorepo；React、NestJS、Prisma/PostgreSQL、Redis、Docker、GitHub Actions | 空项目默认；符合证据时可自动识别；无匹配时零参数回退 | | fullstack-typescript-modular | 上述组合加 Web/API 架构画像、HTTP 前后端契约、身份、关联、韧性和 migration 证据要求 | 必须显式指定 | | fullstack-typescript-modular-shadcn | Boilerplate Golden Path；Vite/shadcn、Product Interface、contracts library、模块化 API 与数据库生命周期 | 必须显式指定 | | frontend-react-typescript | 单仓 React + TypeScript 前端与浏览器验收 | 必须显式指定 | | single-service-typescript | 单仓 NestJS 服务与数据、容器、CI 验证 | 符合证据时可自动识别 | | single-service-python | 单仓 Python API；Hatchling、uv、Ruff、mypy、pytest，并在 uv 锁定环境验证 | 必须显式指定 |

模块化全栈、单前端或 Python 服务项目安装：

npx @netpilot/harness@latest --recipe fullstack-typescript-modular
npx @netpilot/harness@latest --recipe fullstack-typescript-modular-shadcn
npx @netpilot/harness@latest --recipe frontend-react-typescript
npx @netpilot/harness@latest --recipe single-service-python

fullstack-typescript-modular 不生成应用源码。它为 apps/web 选择 web-feature-first、为 apps/api 选择 api-modular-monolith，并让 API 与 Web 共享 HTTP wire contract；REST 提供方和 Web Client 共同声明仓库级 check:contracts。身份、请求关联、服务韧性与 migration 检查同样只声明所需外部证据，Plan/Doctor 中的 missing 或 not-collected 不能解释为已通过。复杂示例见 examples/fullstack-typescript-modular。

fullstack-typescript-modular-shadcn 是独立 @netpilot/boilerplate 的治理画像，不改变空目录默认或既有 Ant Design Recipe。它只安装 Vite、shadcn、Product Interface、library、模块化 API、HTTP、关联、韧性、数据与项目 Agent 规则；React/NestJS 源码、基础组件、Playwright、Dockerfile 和 CI workflow 仍由 Boilerplate 生成。身份系统未实现前不选择 identity-security，避免把规则声明伪装成可用登录能力。示例见 examples/fullstack-typescript-modular-shadcn。

single-service-python 不预设 Web 框架、数据库、容器或 CI，也不会仅凭 pyproject.toml 推断 API 工作负载。它面向新项目或已经确认采用这套工具链的迁移；当前 Harness 不解析 Poetry/PDM、Black、Pyright、unittest 等替代 Python 工具配置，既有项目应先审查 --dry-run，不要把显式选择当成自动兼容证明。无法唯一识别但已经确认目标时，使用 --recipe <id>。

项目布局

安装结果集中在标准宿主目录中：

• .agents/project/project.yml：项目选择与覆盖；
• .agents/project/harness.lock：受管文件所有权、摘要与恢复提交点；
• .agents/project/rules/、.agents/project/generated/：按 scope 加载的规则和路由；
• .codex/agents/：依赖当前项目上下文的 Codex Agent。

.agents/project 是项目配置和受管状态，不是缓存；应与项目一起纳入版本控制。通用 Skills 由独立的 @netpilot/skills 安装到 .agents/skills，Harness 不重复安装。

从旧 .netpilot 布局升级时，先预览并原子迁移目录，再更新受管内容：

npx @netpilot/harness@latest migrate-layout
npx @netpilot/harness@latest migrate-layout --write
npx @netpilot/harness@latest upgrade
npx @netpilot/harness@latest upgrade --write

旧新布局并存、未知旧文件、人工修改过的受管内容或目标冲突都会阻断迁移，不会合并猜测。

项目级 Codex Agent

内置 Recipe 只选择 Codex。按 Recipe 可安装：

• browser-acceptance：真实浏览器、截图、console 与 network 证据；
• fullstack-qa：React、NestJS、PostgreSQL 与 Redis 跨层 QA；
• container-ci-verifier：Docker、Compose 与 CI 静态或获准本地验证。

这些 Agent 不修改受版本控制文件，也不执行发布或部署。项目必须被 Codex 信任；若返回 unknown agent_type，更新 Codex、确认 trust 后新开任务重新加载。真实宿主验证见项目 Agent 宿主 Smoke。

常用命令

| 命令 | 作用 | 默认写入 | | --- | --- | ---: | | 无参数 | 沿用配置、自动识别或回退默认 Recipe 后安装 | 是 | | --dry-run | 按相同选择规则预览 | 否 | | doctor | 诊断配置、lock、入口、检查和事务 | 否 | | migrate-layout [--write] | 预览或迁移旧项目布局 | 否 | | upgrade [--write] | 预览或更新干净的受管内容 | 否 | | setup --recipe <id> [--write] | 高级首装 | 否 | | init --recipe <id> [--write] | 创建最小项目配置 | 否 | | plan / apply [--write] | 计划或应用已有配置 | 否 | | recover [--write] | 预览或执行事务恢复 | 否 | | inspect / resolve / explain | 查看证据、解析结果或来源 | 否 | | validate | 校验内置 Pack、Recipe 和示例 | 否 |

setup、init、apply、upgrade、migrate-layout 与 recover 只有显式 --write 才修改目标。基础配置示例见 examples/fullstack-typescript/project.yml，显式架构与契约示例见 examples/fullstack-typescript-modular/project.yml，Boilerplate 治理画像见 examples/fullstack-typescript-modular-shadcn/project.yml。

安全边界

• 写入前全量预检；冲突时零写入，不提供 --force。
• managed/generated 文件受 lock digest 保护；seed-once 文件交给项目维护。
• 事务使用持久 journal、互斥所有权与 lock-last 提交；中断后显式运行 recover。
• upgrade 只支持版本单调的 update/add，不执行删除、重命名、owner/mode 迁移或三方合并。
• 不安装 Skills，不写用户 home，不修改 Codex trust，不执行任意 Pack 脚本、Git 回滚、发布或部署。
• Harness 只声明检查和证据要求，不会把“发现命令”报告为“验证通过”。

完整契约见安全应用设计。

开发与文档

npm ci
npm run verify

架构说明 · Pack 编写规范 · Python 技术栈研究 · 项目 Agent 设计 · 生态边界 · 版本变化 · 安全政策