Your Name
297 lines
12 KiB
Markdown
297 lines
12 KiB
Markdown
# Nexus 6.0 — 标准转接包（全量 · 与团队同等严谨）
|
||
|
||
> **更新**: 2026-05-23
|
||
> **地位**: 切换 AI 时**标准纪律的唯一索引**；与 `AI-HANDOFF`、`development-acceptance-standard` 并列必读。
|
||
> **要求**: 下一任 AI **不得降低**本包所列任何标准的执行力度；逐行审查与开发规范**同等强制**，不是可选项。
|
||
|
||
---
|
||
|
||
## 0. 严谨性契约（不可协商）
|
||
|
||
下一任 AI 必须接受并执行：
|
||
|
||
| 契约 | 含义 |
|
||
|------|------|
|
||
| **同等严谨** | 与用户团队相同的 DoD、Closure 表、行号、changelog、禁止降级 |
|
||
| **全文遵守** | 下列「必读全文」文档不得只读摘要；审计任务须按 v2 规范 §三 八步执行 |
|
||
| **禁止冒充** | 不得用 grep Top N、子代理汇总、无 Closure 表代替逐行走读 |
|
||
| **当场修复** | P0/P1 当场修；修复写 changelog + 更新 FINDING 矩阵 |
|
||
| **代码待办 = 0** | 合并/宣称完成前，审计产生的待办必须清零或经用户书面 📋 接受 |
|
||
|
||
---
|
||
|
||
## 1. 必读顺序（四档，按序加载）
|
||
|
||
### 档 A — 接续与验收（每次新会话）
|
||
|
||
| # | 文档 | 路径 |
|
||
|---|------|------|
|
||
| A1 | AI 接续 SSOT | `docs/project/AI-HANDOFF-2026-05-23.md` |
|
||
| A2 | 全站功能清单 | `docs/project/nexus-full-site-features.md` |
|
||
| A3 | 开发验收标准 L0～L5 | `docs/project/development-acceptance-standard.md` |
|
||
| A4 | **本文（标准转接包）** | `docs/project/standards-transfer-package.md` |
|
||
|
||
### 档 B — Cursor 强制规则（IDE 已注入，AI 须内化全文）
|
||
|
||
| 规则 | 路径 | 作用 |
|
||
|------|------|------|
|
||
| 完美实现 | `.cursor/rules/perfect-implementation.mdc` | 设计→技术文档→代码→changelog；禁止 TODO/降级 |
|
||
| 技术栈 | `.cursor/rules/nexus-tech-stack.mdc` | 四层架构、配置三写、Primary Worker |
|
||
| Python 后端 | `.cursor/rules/nexus-python-backend.mdc` | API/Service/Repo、会话中间件 |
|
||
| 前端 | `.cursor/rules/nexus-frontend.mdc` | api.js、Alpine、无 CDN |
|
||
| 安全 | `.cursor/rules/nexus-security.mdc` | JWT、凭据、注入、WebSSH |
|
||
| **逐行审计（触发器）** | `.cursor/rules/audit-line-review.mdc` | 用户说「全量审计/走读/Phase 2」时**强制**八步 |
|
||
|
||
### 档 C — 标准正文（开发/审计任务前**全文**阅读）
|
||
|
||
| 文档 | 权威路径 | 说明 |
|
||
|------|----------|------|
|
||
| 系统开发完整标准 v1.0 | **`standards/system-development-standard.md`** | 实现铁律、分层、后端/前端/DB/测试/迁移 |
|
||
| 逐行审计完整规范 v2.0 | **`standards/line-walk-audit-standard-v2.md`** | 8 步、PY/FE/SH 规则表、Closure、§十四提示词 |
|
||
| 审计核心原则（速查） | **`standards/audit-core-principles.md`** | DoD、严重度、KPI、10 大漏报 |
|
||
|
||
> `docs/project/` 下同名文件（如 `system-development-standard.md`、`line-walk-audit-standard-v2.md`、`audit-core-principles.md`）为**副本**；冲突时以 **`standards/`** 为准。
|
||
> Nexus 项目内 Cursor 走读 SSOT 另见：`docs/project/line-walk-audit-standard.md`（与 v2 对齐，批次报告引用此路径）。
|
||
|
||
### 档 D — 设计与专项（按任务选读，大改/上线必读）
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| Nexus 设计标准 | `docs/design/specs/design-standards.md` |
|
||
| 告警推送策略 | `docs/project/alert-push-policy.md` |
|
||
| 脚本执行 SSOT | `docs/project/script-execution.md` |
|
||
| 首次部署验收清单 | `docs/project/production-verification-checklist.md` |
|
||
| Phase 2 审计闭环 | `docs/project/phase-2-audit-remediation.md` |
|
||
| FINDING 矩阵 | `docs/reports/audit-phase-2-findings-matrix.md` |
|
||
| 全量审计报告 | `docs/reports/2026-05-23-full-audit-report.md` |
|
||
| WSL 代码验证 | `docs/project/wsl-integration-test.md` |
|
||
| 通用走读参考（非 Nexus 专用） | `docs/project/line-walk-audit-standard-general.md` |
|
||
|
||
### 档 E — 完成前自检（2026-06-01 起无 `.cursor/skills/`）
|
||
|
||
由当前 Agent 直接执行，不安装 superpowers 等工作流 Skill：
|
||
|
||
| 动作 | 依据 |
|
||
|------|------|
|
||
| 验证后再宣称完成 | `perfect-implementation.mdc`、L2 验收表 |
|
||
| 系统化调试 | 本包 §2 逐行审查 + 复现步骤 |
|
||
| TDD / 测试 | `tests/`、设计文档验收标准 |
|
||
| 代码审查反馈 | 用户评论 + Closure 矩阵 |
|
||
|
||
---
|
||
|
||
## 2. 逐行审查 — 与团队相同的执行标准（强制复述）
|
||
|
||
当用户要求 **全量审计 / 逐行审查 / 走读 / Phase 2 / 安全审计**，或改动 **安全路径**（见下）时，必须执行本节，**不得简化**。
|
||
|
||
### 2.1 触发条件
|
||
|
||
- 用户明确审计指令
|
||
- 或修改：`server/api/*`、`auth_*`、`webssh`、`agent`、`script_service`、`sync_engine*`、`servers.py` 凭据、`websocket`、前端 `innerHTML`/token 存储
|
||
|
||
### 2.2 单文件八步（每步必做）
|
||
|
||
```
|
||
Step 1 登记 path、语言、总行数 N（wc -l）
|
||
Step 2 全文 Read 至 EOF（每段 ≤200 行；末段 offset ≥ N-5）
|
||
Step 3 规则扫描 → 命中列表 H（standards/line-walk-audit-standard-v2.md §四）
|
||
Step 4 对 H 每条 Read ±15 行 → Closure 表（SAFE 须写依据）
|
||
Step 5 API/WS 文件：入口表（方法、路径、鉴权）
|
||
Step 6 外部输入 → sink（SQL/shell/文件/innerHTML/出站 HTTP）
|
||
Step 7 八类归类：BUG/VULN/STYLE/RISK/PERF/UX/EXT/OPT
|
||
Step 8 满足 DoD → 标「逐行完成 ✓」
|
||
```
|
||
|
||
**单会话上限**：最多 **5 个文件** 完成 8 步。
|
||
|
||
### 2.3 DoD（缺一不可）
|
||
|
||
```
|
||
[ ] 全文 Read 覆盖第 1～N 行
|
||
[ ] len(H) == Closure 表行数（H=0 须写「规则零命中，全文 CLEAN」）
|
||
[ ] 每条 FINDING：文件:行号 + 类型 + 严重度 + 修复建议
|
||
[ ] 每条 SAFE：写明依据（argv/白名单/常量/校验函数）
|
||
[ ] API/WS：有入口表
|
||
[ ] 标注输入→sink 或「无外部输入」
|
||
```
|
||
|
||
### 2.4 禁止（与 audit-line-review.mdc 一致）
|
||
|
||
- 无行号的 FINDING
|
||
- 「已审计 ✓」无 Closure 全表（含 SAFE）
|
||
- 单回复声称整目录 `server/` 或全部 `web/` 完成
|
||
- 子代理只出 Top 15 不落行号
|
||
- 同一任务混审计与改代码（除非用户明确要求）
|
||
- 攻击面抽查冒充逐行走读
|
||
|
||
### 2.5 严重度与 KPI
|
||
|
||
| 级别 | 处置 | KPI |
|
||
|------|------|-----|
|
||
| **P0** | 阻塞，当场修复 | 漏报 **-100** |
|
||
| **P1** | 当前批次修复 | 漏报 **-50** |
|
||
| P2/P3 | 本迭代或记录 | — |
|
||
| **📋** | 用户书面接受的设计取舍 | 文档化，不静默忽略 |
|
||
|
||
### 2.6 产出路径（必须落盘）
|
||
|
||
| 用途 | 路径 |
|
||
|------|------|
|
||
| 批次走读报告 | `docs/reports/audit-phase-2{a-j}-line-walk.md` |
|
||
| 闭环声明 | `docs/reports/audit-phase-2-walk-closure.md` 等 |
|
||
| FINDING 跟踪 | `docs/reports/audit-phase-2-findings-matrix.md` |
|
||
| 修复记录 | `docs/changelog/YYYY-MM-DD-*.md` |
|
||
|
||
### 2.7 给 AI 的粘贴提示词（完整版）
|
||
|
||
直接复制 **`standards/line-walk-audit-standard-v2.md` §十四.1** 全文；或见该文件 261～296 行。
|
||
|
||
### 2.8 审计 + 开发同时用时
|
||
|
||
```
|
||
系统提示词顺序：
|
||
1. standards/system-development-standard.md（全文）
|
||
2. standards/audit-core-principles.md（全文）
|
||
任务：
|
||
对 [路径] 逐行走读；FINDING 当场修复；changelog + 矩阵更新。
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 系统开发标准 — 要点索引（全文见 standards/）
|
||
|
||
| 章节 | 内容 |
|
||
|------|------|
|
||
| §零 | 实现铁律（与 perfect-implementation 一致） |
|
||
| §一 | 设计文档 → 技术文档 → 实现 → 测试 → changelog |
|
||
| §二 | 四层架构，禁止跨层 |
|
||
| §三 | FastAPI：Pydantic、JWT、HTTPException、禁止裸 dict |
|
||
| §四 | 前端：apiFetch、esc/escAttr、禁止 CDN |
|
||
| §五 | 安全：Fernet、compare_digest、shlex、危险命令 |
|
||
| §六～§十 | DB、Redis、SSH、后台任务、测试、部署 |
|
||
|
||
**代码生成任务**：粘贴 `standards/system-development-standard.md` 全文作为约束。
|
||
|
||
---
|
||
|
||
## 4. 设计标准（Nexus 产品约束）
|
||
|
||
全文：`docs/design/specs/design-standards.md`
|
||
|
||
- 信任管理员 + 防注入/XSS（非业务限制）
|
||
- 配置三写、不可改四项
|
||
- 性能基线、告警通道分工
|
||
- 明确「不做」：RBAC、文件编辑器、会话录像等
|
||
|
||
---
|
||
|
||
## 5. 验收与测试标准（与 development-acceptance-standard 对齐）
|
||
|
||
| 层级 | 标准来源 |
|
||
|------|----------|
|
||
| L0 | 档 B + 档 C 系统开发标准 |
|
||
| L1 | 设计/技术文档内验收标准 |
|
||
| L2 | `pytest tests/test_security_unit.py` + `scripts/wsl_integration_smoke.sh` |
|
||
| L3 | **本文 §2** 逐行 DoD |
|
||
| L4 | script-execution §11、alert-push-policy、T1～T5 |
|
||
| L5 | production-verification-checklist.md |
|
||
|
||
---
|
||
|
||
## 6. 历史审计资产（续审勿重复造轮子）
|
||
|
||
| 资产 | 路径 |
|
||
|------|------|
|
||
| Phase 2 各批次走读 | `docs/reports/audit-phase-2{a-j}-line-walk.md` |
|
||
| Phase 3 闭环 | `docs/reports/audit-phase-3-walk-closure.md` |
|
||
| 全量 vs Phase2 对账 | `docs/reports/audit-full-vs-phase2-reconciliation.md` |
|
||
| 审计计划参考 | `.cursor/plans/nexus_全面代码审计_a33e6fc2.plan.md` |
|
||
|
||
**续审规则**：已「逐行完成 ✓」的文件，仅在 **diff 触及该文件** 时重走 8 步；新文件必须完整走读。
|
||
|
||
---
|
||
|
||
## 7. 标准文件完整清单（转接核对用）
|
||
|
||
### 7.1 强制（档 A～C）
|
||
|
||
- [ ] `AI-HANDOFF-2026-05-23.md`
|
||
- [ ] `nexus-full-site-features.md`
|
||
- [ ] `development-acceptance-standard.md`
|
||
- [ ] `standards-transfer-package.md`（本文）
|
||
- [ ] `.cursor/rules/perfect-implementation.mdc`
|
||
- [ ] `.cursor/rules/nexus-tech-stack.mdc`
|
||
- [ ] `.cursor/rules/nexus-python-backend.mdc`
|
||
- [ ] `.cursor/rules/nexus-frontend.mdc`
|
||
- [ ] `.cursor/rules/nexus-security.mdc`
|
||
- [ ] `.cursor/rules/audit-line-review.mdc`
|
||
- [ ] `standards/system-development-standard.md`
|
||
- [ ] `standards/line-walk-audit-standard-v2.md`
|
||
- [ ] `standards/audit-core-principles.md`
|
||
|
||
### 7.2 按任务（档 D）
|
||
|
||
- [ ] `design-standards.md`
|
||
- [ ] `alert-push-policy.md`
|
||
- [ ] `script-execution.md`
|
||
- [ ] `production-verification-checklist.md`
|
||
- [ ] `phase-2-audit-remediation.md`
|
||
- [ ] `audit-phase-2-findings-matrix.md`
|
||
|
||
### 7.3 索引与副本
|
||
|
||
- [ ] `standards/README.md`
|
||
- [ ] `docs/project/line-walk-audit-standard.md`（Nexus SSOT / Cursor 引用）
|
||
- [ ] `docs/project/audit-line-review-cursor-rule.md`（规则说明副本，若有）
|
||
|
||
---
|
||
|
||
## 8. 给下一任 AI 的完整复制提示词（标准 + 接续）
|
||
|
||
```
|
||
【严谨性】你必须与 Nexus 团队同等严谨，不得降低任何标准。标准转接包：docs/project/standards-transfer-package.md
|
||
|
||
【必读 · 按序】
|
||
1. docs/project/AI-HANDOFF-2026-05-23.md
|
||
2. docs/project/nexus-full-site-features.md
|
||
3. docs/project/development-acceptance-standard.md
|
||
4. docs/project/standards-transfer-package.md
|
||
|
||
【规范 · 全文内化】
|
||
- .cursor/rules/perfect-implementation.mdc + nexus-*.mdc + audit-line-review.mdc
|
||
- standards/system-development-standard.md（开发）
|
||
- standards/line-walk-audit-standard-v2.md + standards/audit-core-principles.md（审计）
|
||
|
||
【逐行审查 · 触发即强制】
|
||
- 8 步/文件、全文 Read 至 EOF、Closure 全表含 SAFE、FINDING 必须 文件:行号
|
||
- 单回复 ≤5 文件；禁止 grep/Top15 冒充审计；P0/P1 当场修 + changelog + 矩阵
|
||
- 报告：docs/reports/audit-phase-2*-line-walk.md
|
||
|
||
【验收】
|
||
- 宣称完成：L2（pytest + wsl_integration_smoke.sh）+ changelog
|
||
- 宣称上线：L5 production-verification-checklist 全勾选
|
||
- 宣称完成前：跑 L2 验证命令（pytest / smoke），见 perfect-implementation.mdc
|
||
|
||
【项目态】未部署。端口：子机出站 443 心跳；中心→子机 SSH 22；8601 仅本机。
|
||
勿做已否决项（见 HANDOFF §7）。
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 与用户团队的等价检查表
|
||
|
||
交接完成时，下一任 AI 应能回答「是」：
|
||
|
||
| # | 问题 |
|
||
|---|------|
|
||
| 1 | 能否复述逐行 DoD 六项？ |
|
||
| 2 | 单会话最多走读几个文件？ |
|
||
| 3 | P0 漏报 KPI 扣多少分？ |
|
||
| 4 | FINDING 必须包含什么格式？ |
|
||
| 5 | 修复后必须更新哪两类文档？ |
|
||
| 6 | `standards/` 与 `docs/project/` 副本冲突时听谁的？ |
|
||
| 7 | 开发执行顺序七步是什么？ |
|
||
| 8 | 不可从 DB 覆盖的四项配置是什么？ |
|
||
|
||
全部「是」→ 标准转接合格。
|