NJWL · 操作指南 / 维护者工作流

MCP 项目接入 · 2026-10-14

zfold8 等设备继续使用各自已有 SSH 身份。先查询项目；首次无权限时申请，经管理台批准后，自动登记和提交，无需手工上传 JSON。

项目审批与提交记录 · AI 接入说明与连接配置

DSH 机器人私聊通知审批人。批准不含发布权限；本页下方旧命令作为未接入 MCP 客户端的兼容方式。

统一授权、每次发布登记

2026-09-23确定：范围覆盖所有已登记项目的代码与部署配置，账号、密钥和权限由管理员维护。维护者一次接入，日常权限集中管理；每次发布必须绑定当次登记并通过检查。

完整规则、当前实际状态与实施验收清单

当前香港提交工具只记录修改，统一发布闸门尚未接通；不要把本说明当作已经开通发布权，也不要让维护者自行修改授权配置。

香港维护者与授权已上线

可在后台修改维护者名称、角色、状态和项目登记/提交能力；gpt@zfold8 为首个管理员。

进入后台 · 当前生效范围与操作说明
WORKFLOW / VERSION 1.0 / 2026-09-21

从维护者接入，到代码发布与审计

给管理员一份授权操作单，给维护者一条明确的提交路径，给下一位接手者完整的验收与交接材料。

项目接入确定范围与部署目标
身份核验账号、公钥与责任人
一次授权固定工具和项目权限
登记与提交绑定基线及候选版本
检查与发布记录结果与失败回滚
验收与同步业务结果、审计归档
先看清边界，再按角色操作。

大陆电芯发布入口已安装，已有两条生产发布成功回执；业务验收与多账号接入需分别核对。现有工具包含试点账号与项目限制；这里提供通用流程和交接模板，不能当作已完成多账号适配的一键安装包。

新增：模型与设备身份规范

显示名采用“模型@设备”，另设稳定的设备、归属用户和维护者编号；新SSH账号由命名规则生成。

查看命名规则、配置授权及管理员操作 →

配置授权升级代码已完成并通过34项隔离测试；大陆待管理员安装验证。现有账号及历史记录保持兼容，香港已接通独立配置授权，见香港后台操作说明。

把资料交给管理员和维护者

完整流程 ↓管理员操作单 ↓维护者申请表 ↓项目策略模板 ↓验收清单 ↓交接模板 ↓

JSON 是待审核模板，不会自动写入权限；不要填写私钥、令牌或生产数据。

维护者接入与代码发布工作流

版本 1.0 · 核对日期 2026-09-21 · 面向管理员、项目负责人、维护者及其 Agent。

本指南定义可复用的工作流和交接材料；不是已完成多租户适配的一键安装器。现有大陆工具限制为试点账号 gpt@zfold8，电芯发布器限制为固定项目和部署方式。新账号、新项目必须先适配工具并通过验收，不能只改 sudoers，也不能复用别人的私钥。

先选择你的情况

  • 已获授权的试点维护者修改电芯：按“日常提交”操作，登记发生在实际发布的服务器。
  • 同一项目新增维护者：管理员核验身份、建立独立账号和密钥映射，再配置工具内部授权；通过拒绝测试后交接。
  • 新服务器或新项目：先完成“项目接入”，确定源码、服务、健康检查、回滚和审计出口，再授权维护者。
  • 仅查看审计：走管理台账号授权，无须提供 SSH 写权限。

当前真实状态

  • 香港：电芯 src/public 已允许登记；香港登记工具记录源码前后差异，本身不发布代码。当前维护账号仍有完整 sudo，其他直写路径未被全局封锁。
  • 大陆：电芯登记、受控提交和发布工具已安装，sudo 命令权限及审计导出已核对。已读取两条电芯生产发布成功回执（20260921T032549Z-41061733、20260921T033436Z-e8471915）。业务验收与多账号接入仍需分别核对；先前12项隔离测试中的部署命令是模拟测试。
  • 两地审计：可通过本机同步工具导出并导入香港管理台。是显式同步，不是常驻实时同步；同步成功必须单独确认。
  • 其他人员：尚未提供可直接安装的通用多账号工具包。现有脚本中的 ACTOR、SUDO_USER 检查、项目路径、导出来源与本机 SSH 配置都需适配；本页模板不会自动授予权限。

角色与责任

角色负责什么交付给下一步
项目负责人确认应用、代码范围、自动发布条件、业务验收人填好的项目策略
服务器管理员核验公钥、开账号、安装受控工具、配置精确 sudo 权限、测试撤销授权回执、主机指纹、工具版本
维护者 / Agent修改前登记、提交确切版本、运行业务检查、核对发布与同步结果登记号、候选摘要、检查证据
发布工具验证身份、范围、基线、候选版本；执行固定发布步骤系统生成的发布或失败回执
审计管理员控制谁可查看差异，检查同步及异常归档与问题处理记录

完整流程

项目接入 → 身份核验 → 管理员一次授权 → 验收交接 → 修改前登记 → 提交候选 → 校验 → 受控发布 → 业务验收 → 审计同步 → 归档。

登记失败不能进入提交；校验失败不能进入发布；发布成功但同步失败，保留“已发布 / 同步失败”两个独立状态，不能重新发布来解决同步问题。

项目接入：管理员先收齐这些资料

下载 project-policy.json，填写项目 ID、目标服务器、精确源码根目录、允许目录和后缀、排除目录、固定服务及发布命令、健康检查、备份与回滚方式、审计导出入口、责任人。模板中的 null 和 REPLACE_REQUIRED 必须填完。

接入检查：确认该目录确实是运行服务的构建来源；确定静态文件、容器镜像或系统服务的实际部署方式；记录服务身份和数据挂载。不得从目录同名、存在 Dockerfile 或另一台服务器的登记号推断发布目标。

现有电芯适配器只支持既有 Docker Compose 电芯服务，src/public 内的 JS/MJS/HTML/CSS/JSON/MD；最多20个文件、单文件2MiB、请求8MiB；已有父目录；不接受删除。数据库迁移、依赖更新、Dockerfile、Compose、系统配置、密钥、图片等不在此通道内，须另做适配和授权。

新项目的工具版本必须先在隔离环境验证；没有对应发布适配器时，只能标记“可登记 / 可提交 / 不可发布”，不能发放全量 sudo 作为临时替代。

身份与管理员授权

详细步骤见 admin-authorization.md。维护者提交 maintainer-request.json 和 SSH 公钥，通过独立渠道核对指纹。私钥留在维护者设备。

一名维护者的一台设备使用独立密钥；Agent 名称和设备标签是声明，实际系统身份来自 SSH 账号、公钥认证证据及 sudo 用户。多个 Agent 共用同一账号或密钥时，不能声称已区分各自身份。

管理员建立“维护者 → 账号/密钥 → 项目 → register/submit/publish/export 能力”的授权映射，记录授权人、理由、日期、撤销方法。模板中的到期时间只是管理记录，当前试点工具不会自动到期撤权。

账号能登录、项目能登记、工具内部允许该身份、sudo 允许固定入口，是四个分别要验收的条件。任何一个缺失都不能靠修改登记说明绕过。

日常提交：大陆电芯现有入口

先阅读项目 AGENTS.md 和本指南。命令在目标大陆服务器上以已获授权的 gpt@zfold8 执行；其他账号不得照抄账号名。把文件放在自己的工作目录，登记前不要直接修改生产文件。

登记 JSON 示例（将文件路径替换为本次真实范围）：

{"task":"CELL-任务编号","summary":"修改内容","reason":"修改原因","paths":["/home/ubuntu/apps/cell-qr-app/public/index.html"]}
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/register.py begin < spec.json

保存返回的 registration_id；将下面命令中的 REGISTRATION_ID 替换为该编号。香港审计号、网页 CHG 编号及已完成记录不能代用。

先在本地或隔离工作目录改代码并执行业务测试，再生成 files.json；content 必须为完整修改后文件内容，不是 diff。提交路径必须与登记集合相同。

{"files":[{"path":"/home/ubuntu/apps/cell-qr-app/public/index.html","content":"完整修改后源码"}]}
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py submit REGISTRATION_ID < files.json
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py publish REGISTRATION_ID
sudo /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py status REGISTRATION_ID

submit 校验身份、范围和基线，检查 JS/JSON 语法，保存不可变候选，不修改生产文件。publish 再次校验版本，备份源码与原镜像，只部署预先配置的服务；失败尝试回滚并保存结果。普通范围内的发布不需要管理员逐次批准，但首次授权与部署适配必须完成。

自动检查不代替项目测试。业务验收人还需确认登录、核心页面和相关 API；工具不会把人工自报的测试结果当作系统验证。代码/镜像回滚不会回滚数据库。

香港源码留痕的区别

香港使用 /usr/local/lib/njwl-agent-changes/agent-submit.py register spec.json，spec 需要 agent、environment、task、summary、reason、paths。修改后执行同工具 submit 登记号 --checks checks.json。

这个 submit 只记录实际修改，返回“已完成未发布”，不接收大陆候选包也不执行部署。大陆受控发布必须取得大陆登记号。跨站任务在 task 中记录相同业务任务号便于查找，但这不是跨站授权凭证。

跨服务器审计

现有试点：在维护者本机运行以下脚本，使用本机现有 SSH 身份从大陆导出脱敏记录、校验摘要后导入香港。

python3 /home/desktop/Desktop/gpt/njwl-workspace-android/maintenance/sync-mainland-records.py

该本机绝对路径仅适用于试点设备，其他部署不能照抄。新部署须由管理员配置导出端、接收端、独立采集身份、允许命令和受控导入位置，并测试失败重试与去重；不要复制试点私钥。没有常驻采集服务时，明确由谁在何时执行同步。

查看 https://njwl.ai/sso/#agent-changes：确认来源服务器、原始登记号、发布状态、时间、差异和同步时间。原始快照留在源服务器受限目录；页面只展示经过筛选的差异。SHA256 用于一致性检查，不代表数字签名或对 root 不可篡改。当前固定导出最近500条；新部署需另行制定归档与保留周期，避免把列表上限当作备份策略。

异常与恢复

情况应该怎么做
No such user先由管理员确认系统账号存在；设备标签不一定是登录用户名
登记路径不允许核对实际目标服务器与源码路径，管理员审查项目范围后配置，不事后补登记
sudo 要求密码 / 拒绝核对精确命令、解释器 -I 参数、脚本路径及工具内身份授权；不要放开通用 shell
线上基线已变化读取新版本、合并变化、重新登记与提交；不得强制覆盖
候选已存在 / 登记已结束保留旧记录，新版本使用新登记号
发布失败且已回滚核对回执与业务状态，修复后建立新任务
发布中断或只有开始回执停止重复发布，管理员核对运行镜像、源码摘要和原始回执
发布成功但同步失败只重试同步；原发布状态不变
主机密钥改变管理员通过独立渠道确认原因与指纹，不能关闭 StrictHostKeyChecking

验收与交接

下载 acceptance.md，逐项填写实际结果和证据，未执行标“未验证”。首次项目接入需做一次低风险的真实变更、业务验收和审计同步，随后才能称为完整工作流跑通。

给下一位维护者交付 handoff.md：目标主机和指纹、项目路径、工具版本、可用能力、登记/提交/状态命令、检查及回滚方式、审计入口、管理员联系方式。不得交付私钥、令牌、完整环境文件或生产数据。

人员退出时撤销该公钥及对应 sudo 和工具内部授权，检查已有会话、在途发布及未结束登记。仅删除公钥不终止已经建立的 SSH 会话；停用前先由管理员确认是否存在正在写入的发布任务。保留历史审计和撤销记录。

管理员授权：展开完整操作单

管理员授权操作单

本文件用于一次性接入；不要求管理员批准每次已授权范围内的普通发布。先看 workflow.md 的当前状态。新账号目前需要维护者适配工具后，管理员才能执行下述工具授权步骤。

1. 接收申请并核验

收齐 maintainer-request.json、项目负责人确认的 project-policy.json、公钥文件及其指纹。通过独立联系渠道确认负责人和公钥指纹；不接收私钥。公钥检查示例：

ssh-keygen -lf /root/reviewed-maintainer.pub
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

前者核对申请者公钥，后者给申请者核对服务器身份。只接受管理员已审核的公钥文件，不能把公网上未经核验的内容直接写进 authorized_keys。

2. 创建独立系统账号（新账号示例）

以下示例用 agent-demo-device，管理员应替换为批准的系统用户名；现有账号先人工核对，不覆盖原公钥。设备显示名可以不同，推荐系统用户名只用小写字母、数字及连字符。

sudo adduser --disabled-password --gecos '' agent-demo-device
sudo install -d -m 700 -o agent-demo-device -g agent-demo-device /home/agent-demo-device/.ssh
sudo install -m 600 -o agent-demo-device -g agent-demo-device /root/reviewed-maintainer.pub /home/agent-demo-device/.ssh/authorized_keys
sudo install -d -m 700 -o agent-demo-device -g agent-demo-device /home/agent-demo-device/uploads

不要加入 sudo/docker 特权组，也不要把生产源码目录授予维护者直接写权限。上述操作只开通 SSH 公钥登录，不等于已经开放登记或发布。

已有账号添加新密钥应逐条追加并记录指纹，保留其他合法密钥；是否允许端口/代理转发按实际需要配置。公钥绑定身份仍须与项目授权对应。

3. 安装经过审查的工具版本

管理员在私有暂存目录审查安装包，核对从已确认渠道取得的 SHA256，先复制到 root 专用目录，再执行同一份已核验文件。禁止 curl URL | sudo bash。把工具源码和版本摘要纳入安装回执。

当前试点并非通用包：register.py、cell_submit.py 的 ACTOR，以及 export_records.py 的 SUDO_USER 检查固定为 gpt@zfold8；只改 sudoers 为新账号会被工具拒绝。不要简单去掉身份检查。

新账号适配必须覆盖：

  • 受 root 管理的维护者/项目/能力映射，默认拒绝未知身份。
  • 登记记录同时保存服务器、项目、真实账号/UID；提交与发布检查同一身份及项目。
  • 旧记录归属不可重写，账号更名或迁移另留回执。
  • 多项目分别配置目录、固定发布命令和审计来源，不能将一个项目编号用于另一个项目。
  • 导出是否跨维护者可见由管理员明确批准；未授权者不得读取全部差异。

上述通用映射目前是适配要求，并非现有 JSON 模板已被脚本读取。工具维护者应先交付实现和通过的验收结果，管理员再开放命令。

生产工具及其配置必须由 root 拥有，所在目录也不能由维护者写入。审计存储和候选目录只给工具写权限；维护者仅拥有自己的上传暂存目录。检查脚本不能以 root 直接执行提交者的任意测试脚本、npm 生命周期命令或自报发布命令。

4. 配置最小命令权限

下面是当前大陆试点已有规则的结构示例；不是新账号可直接套用的授权。新账号先完成上节工具适配，真实脚本路径也必须一致。

"gpt@zfold8" ALL=(root) NOPASSWD: /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/register.py *
"gpt@zfold8" ALL=(root) NOPASSWD: /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py submit *, /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py publish *, /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/cell_submit.py status *
"gpt@zfold8" ALL=(root) NOPASSWD: /usr/bin/python3 -I /usr/local/lib/njwl-maintenance/export_records.py

通配参数只允许交给严格校验参数的固定脚本；脚本还必须拒绝额外参数、非法登记号、越界路径和伪造身份。不要授权任意 python3、bash、docker、systemctl 或编辑 root 脚本。

先把拟用规则写入 root 暂存文件，使用 visudo -cf 校验，再 install -o root -g root -m 440 安装至 /etc/sudoers.d/ 下的专用文件，最后 visudo -c 验证全局。保留当前管理员会话；失败恢复备份，不退出后再修。

注意：export_records.py 后面没有参数。不要额外加尾部双引号空参数；这曾导致试点规则无法匹配正确命令。

5. 验收并签发交接单

以新维护者本人真实 SSH 会话运行测试；sudo -l 只是规则列表，不能替代实际调用。按 acceptance.md 验证正确操作可用、错误身份/范围/编号被拒绝、失败有回执、撤销有效。

授权回执填写：授权人、项目负责人、账号、UID、公钥指纹、目标主机指纹、项目、能力、工具/配置摘要、授权时间、复核时间、撤销入口、测试证据。不要记录私钥。当前工具不自动执行到期撤权，由管理员负责复核。

6. 撤销

先核对在途发布与活动会话，按指纹撤销指定 authorized_keys 条目，移除专用 sudoers 规则和工具内部项目授权，必要时终止已存在会话；再次测试新连接和发布入口均无法使用。保留历史记录，不删除同账号其他人员的密钥或整个共享账号。

接入验收：逐项核对实际证据

接入验收清单

填写：项目 / 服务器 / 工具版本与摘要 / 测试身份和UID / 公钥指纹 / 操作人 / 日期 / 证据位置。

每项状态只能填：通过、失败、未验证、不适用（附理由）。不要用“已安装”替代“通过”。拒绝测试先在隔离环境执行，不伪造其他人的生产任务。

管理员验收

  • [ ] 主机指纹和申请公钥通过独立渠道核对；新账号能以自己的密钥登录。
  • [ ] 未授予 sudo/docker 特权组；工具和配置所有权正确，维护者不能改工具或直接写生产源码。
  • [ ] sudoers 语法和实际命令调用通过；未知账号和未授权项目被拒绝。
  • [ ] 只允许预先配置的源码目录、后缀、服务和健康检查；数据、密钥、依赖及部署配置被排除。
  • [ ] 过期授权（若实现）或人工撤销后不能发起新发布；已建SSH会话及在途任务有处理方案。

登记和提交验收

  • [ ] 修改前真实登记，服务器、项目、账号、基线摘要正确。
  • [ ] 无编号、他人编号、其他服务器编号、结束编号均拒绝。
  • [ ] 路径越界、符号链接、重复文件、缺失/多余文件、请求超限均拒绝。
  • [ ] 未提交前不修改生产；提交后候选不可替换，发布绑定同一摘要。
  • [ ] 线上代码变化后拒绝旧基线，不自动覆盖并发修改。
  • [ ] JS/JSON语法检查确实执行；项目自己的功能测试有独立结果。

发布与回滚验收

  • [ ] 固定发布目标与真实服务一致；未执行提交者提供的任意shell命令。
  • [ ] 首次低风险真实变更成功；运行版本与候选一致，有系统回执。
  • [ ] 登录、关键页面及API由业务验收人检查；匿名保护没有被错误放开。
  • [ ] 隔离环境构建/启动失败测试保留失败回执，源码与镜像恢复正确。
  • [ ] 中断、仅开始回执、回滚失败均有明确人工恢复路径；同编号不能重复发布。
  • [ ] 明确数据库不随代码回滚，数据库变更另走流程。

审计与交接验收

  • [ ] 源服务器记录完整；不导出私钥、令牌、原始数据库或未脱敏快照。
  • [ ] 接收端验证来源、编号、摘要、重复及冲突；重试不覆盖已有完整记录。
  • [ ] 管理台显示真实来源服务器、原编号、操作者、状态、差异、同步时间。
  • [ ] 发布成功/同步失败分开表示；只重试同步可恢复展示。
  • [ ] 审计查看权限与发布权限分开；敏感差异仅授权人员可见。
  • [ ] 授权回执、AGENTS.md、联系渠道、备份及撤销步骤交给下一位维护者。

结论：可登记 / 可提交 / 可发布 / 已业务验收 / 已审计同步，分别填写。全部相关项通过后，才能签署“完整工作流已验收”。

项目交接：复制给下一位维护者

维护者交接单 / 项目 AGENTS.md 模板

状态：待填写，不代表已授权。

  • 项目ID、名称、负责人：
  • 生产目标服务器与SSH别名：
  • 管理员独立确认的主机密钥指纹：
  • 维护者真实系统账号、UID、公钥指纹、设备标签：
  • Agent名称（声明信息，不充当认证身份）：
  • 源码根目录、允许范围、排除项：
  • 本地工作区与生产路径区别：
  • 受控工具版本、SHA256、配置版本：
  • 已开通能力：register / submit / publish / status / export（逐项确认）
  • 真实登记命令及JSON格式：
  • 提交命令、候选格式和大小限制：
  • 检查项目与证据：
  • 发布命令、固定服务、健康检查：
  • 状态查询与失败恢复：
  • 审计导出、同步执行地点及负责人、管理台地址：
  • 管理员联系渠道、授权回执、复核/撤销方式：
  • 未验证项目与禁止操作：

协作要求：先登记再修改；不事后倒填。登记号不跨账号、跨服务器或跨项目代用。扩大范围先重新登记。提交确切版本，失败先查回执；不得用重复发布处理审计同步失败。发布状态以系统回执为依据，人工测试单独说明。不得修改工具、密钥、数据库、历史审计或未授权路径。

逐次任务回报：目标服务器 / 任务号 / 登记号 / 候选摘要 / 实际改动 / 检查结果 / 发布结果 / 业务验收 / 审计同步 / 限制与后续事项。