二次开发

NIE-SLA 的生产源码分三处：私有 Agent/Worker 仓库、私有 Frontend 仓库与脱敏公开仓库。公开仓库只由脱敏脚本单向生成，不在其中直接修改生产逻辑。

Worker 与 Frontend

node --test tests/*.test.mjs
node --check app.js
node --check js/admin.js

发布前跑完整验证：

bash test.sh
pnpm run build
pnpm test
pnpm run test:update
pnpm exec wrangler deploy --dry-run --outdir .wrangler-dry-run

pnpm run build 准备 Worker Static Assets；不要手工把旧 Frontend 副本复制进构建目录。部署前确认 dry-run 列出的 D1、R2、Durable Object、Assets 与 Cron 绑定符合预期。

Rust Agent

需要稳定 Rust 工具链；跨架构 Linux Release 还需要项目支持的 Zig/target 配置。最低验证：

cargo fmt --check
cargo check --locked
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings

只在本机能运行不等于可发布。Agent Release 必须为每个受支持架构生成静态 Linux ELF，更新 VERSION 与 SHA256SUMS，并验证安装器的逐级哈希链。

配置与 Secret

公开配置与 Secret 分开处理：

• ADMIN_USERNAME、ADMIN_PASSWORD、ADMIN_PATH 是首次部署必填。
• 管理员登录后使用短期 x-admin-session，客户端不得长期保存或重复发送密码。
• Agent 与 Latency 使用每节点 scoped Token，不出现在公开 API。
• DEVELOPER_API_ORIGINS 只控制公开 /api/v1 的浏览器读取。
• NQ 图床地址与 Token 只能是 Worker Secret，不进入 D1 设置、普通备份或前端。
• 自定义 URL 必须使用无凭据 HTTPS，并通过服务端私网/重定向检查。

开发环境使用单独 Cloudflare 资源与测试凭据。本地预览不要指向生产 Admin API，也不要通过 URL ?api= 接受任意 API Base。

修改公开 API

/api/v1 是稳定兼容线：

1. 可以增加可选字段与新端点能力。
2. 不能在 v1 内静默删除、重命名或改变既有字段含义。
3. 新查询参数必须有默认值、范围限制与规范化缓存键。
4. 历史接口必须设置上限，0 或负数不能表示无限读取。
5. 公开输出必须经过 IP、端口、URL 凭据与内部错误脱敏。
6. 浏览器 CORS 只能回显精确 allowlist Origin。
7. 更新 Manifest、端点文档、契约测试与替代前端示例。

客户端先读 /api/v1 Manifest 做能力发现，不根据 worker_version 猜功能。

修改 Frontend

• 公共状态与 Agent 在线是不同来源，不能合并成单一布尔值。
• lite=1 用于首屏，图表数据在用户打开详情后再加载。
• 错误、空数据与 warnings[] 必须分别显示。
• 所有 API 文本用 textContent 或统一转义函数渲染。
• 320、375、390、768、1280、1440 像素检查无页面级横向溢出。
• 弹窗需要焦点陷阱、Escape 关闭、背景滚动锁定与 opener 焦点恢复。
• 静态资源修改后更新对应内容缓存键，并让测试固定当前入口键。

修改 Agent

• 根磁盘容量表示系统卷，不是挂载点求和；Linux IO 只选一个一致核算层级，避免分区、LVM 与物理设备重复累计。
• 离线队列写入必须使用受限权限、原子替换与落盘同步，失败时保持 dirty。
• 上传成功确认、退出与更新重启前必须 Flush。
• 输入指标需要类型、范围与时间窗口校验。
• 安装、更新与回滚保持二进制所有权、执行权限与 SHA-256 链。
• 固定 NQ/IP 动作只接受编译进二进制的动作枚举，不能扩展成任意命令、URL、参数或计划任务。

版本与发布

应用、Worker、文档与 Agent 使用同一个数字版本。稳定版按十进制语义递增：补丁版本为 1.1.93，下一个小版本为 1.2.0，不叠到 1.0.99 再进位。

应用/Worker/文档：1.1.93
Agent：v1.1.93
应用源码 Tag：app-v1.1.93
Agent Tag/Release：v1.1.93

不要覆盖已发布的同版本二进制或移动公开 Tag。代码发生发布级变化时先增加版本，再本地测试、构建、生成校验和与 Release 资产。纯文档纠错可以保持产品版本，但应标注不改变运行时。

公开仓库是开源使用者唯一的源码快照、更新清单与 Release 分发入口；私有 Agent/Worker 与 Frontend 仓库是生产源，只能通过脱敏脚本单向生成公开快照。公开一键构建按 update-manifest.json 固定 Tag 下载公开 Release；生产 Agent 从已部署站点的 /bin 安装与更新，不直接查询 GitHub API。

发布与部署流程

1. 本地门禁：bash test.sh 运行 Worker、前端与安装清单全套测试；agent/build-release.sh 构建 7 种架构二进制并生成 bin/VERSION 与 bin/SHA256SUMS。
2. 哈希链：新摘要先写入 setup.sh/update.sh 的 SHA256SUMS_SHA256，再写入 install.sh/quick-install.sh 的 DEFAULT_SETUP_SHA256，最后同步安装清单测试与后台安装命令模板。
3. 发布：Agent 私有仓库提交推送并创建 vX.Y.Z Tag 与 GitHub Release（附 7 架构资产）→ 前端仓库提交与 Tag → 公开仓库单向脱敏导出，并在公开仓库补 vX.Y.Z/app-vX.Y.Z Tag 与 Release 资产（一键部署与在线更新依赖它们）→ worker/deploy.sh 部署 Worker → scripts/smoke-prod.mjs 线上验证。
4. 自托管更新：一键部署默认启用 NIE-SLA Online Update workflow，每 6 小时检查一次官方稳定版；需要立即升级时在部署仓库的 Actions 页手动 Run workflow。长期未升级按 FAQ「后台显示有新版本但一直没有自动更新」 排查（Actions 未启用 / 缺少基线 / 文件与基线不一致）；不使用 Actions 时可同步仓库后执行 npm run deploy。

提交前清单

• 工作树只包含本次范围内的文件。
• 测试、格式化、lint、依赖审计与 production build 通过。
• Worker 改动完成 Wrangler dry-run。
• 前端完成桌面/移动端页面检查。
• 公开导出通过秘密扫描且只从私有源单向生成。
• 版本、Manifest、Tag 计划、Agent VERSION 与文档一致。
• 未把开发日志、缓存、构建临时目录或 Secret 加入提交。

仅开发替代前端时，无需 fork 完整 Worker，流程见API 集成实践。仅调整视觉样式时，使用主题系统。