nixevol/NixMsg
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feat/a1-admin-auth
NixMsg/docs/TASKS.md
T

33 KiB
Raw Permalink Blame History

NixMsg 开发任务拆分与多 Agent 协作

项 内容
版本 0.3
日期 2026-09-30
对应 PRD.md 0.5、DEVELOPMENT.md（对应 PRD 0.5）
仓库 https://git.asio.asia/nixevol/NixMsg.git，主分支 main
读者 总控 Agent、各开发线 Agent、负责人

1. 目标和交付标准

由多个 Agent 并行开发和测试，交付 NixMsg 服务端、管理后台、四种 SDK、Docker 镜像和文档。

下面全部满足才算交付：

  1. main 上 task check（构建、代码检查、单元测试）和全部集成测试通过。
  2. PRD 第 10 节 F01–F23 每条都有验收结果：通过；或未测，写明原因，列进交付说明供负责人事后审阅。
  3. 四种 SDK 都通过 DEVELOPMENT 第 9 节的接入清单。
  4. DEVELOPMENT 第 13 节的弱网、崩溃、压测、端到端测试做完并有报告。
  5. 二进制（linux/amd64、linux/arm64、windows/amd64）和 Docker 镜像（amd64、arm64）能按文档启动；镜像已推到 git.asio.asia/nixevol/nixmsg。
  6. 和文档不一致的实现、开发中自己拿的主意，都写进 docs/DEVIATIONS.md（写明原因和备选方案），并汇总进交付说明，供负责人事后审阅。
  7. 最终代码按第 7 节审核过，打上 v0.1.0 和 sdk/go/v0.1.0 标签并推送；npm、PyPI、Maven 三个 SDK 包已发布到 Gitea 包仓库。

2. 资料

  • docs/PRD.md：产品行为，以它为准。
  • docs/DEVELOPMENT.md：实现规范。第 5 节的库用法和第 15 节「不要这样做」必须看。
  • docs/TASKS.md：本文件。
  • MemRelay 项目记忆（项目 NixMsg，ID 25464650-ed5d-440e-b362-190f2852d451）：已确认的决定、技术栈选型、依赖库行为核对结论，以及各线的进度检查点。随时可以查。
  • 负责人已授权全程自动（第 9 节）。文档没写清或互相矛盾时不要停下来问，按和 PRD、DEVELOPMENT、PRD 第 9 节已确认决定最一致、最稳妥的做法自己定，写进 docs/DEVIATIONS.md（原因和备选方案）；不改 PRD 的产品行为。子 Agent 定不了的写进报告，由总控定。

3. 环境

  • 本机是 Windows，已有 Git、Go、Node.js LTS、pnpm、Python、JDK 21、Docker Desktop 和 scoop。缺的工具用 scoop 装，例如 scoop install task golangci-lint；包名不确定时先 scoop search。
  • 丢包模拟（netem）、多架构镜像等 Linux 相关的测试，在 Docker 的 Linux 容器里跑。toxiproxy 用它的官方 Docker 镜像。
  • 多个 Agent 在同一台机器上同时跑测试，必须互不干扰：
    • 测试里的服务一律监听随机端口（:0），数据放临时目录，不要写死 7443。
    • Docker 容器、网络、卷的名字带上自己的线名前缀，用完删除。
    • 不改全局配置：全局 git 配置、系统环境变量、全局 npm 配置都不要动。
  • 推送 git.asio.asia 用本机 Windows 凭据管理器里已存好的账号，不要把账号密码写进仓库、脚本或命令行。
  • 发布 SDK 包和推送镜像只在阶段 3 做，用 Gitea 个人访问令牌：总控用密码库条目 git.asio.asia 的账号在 Gitea 里创建一个只有 package 读写权限的令牌，立即存进 MemRelay 密码库，只写进本机用户级配置，不进仓库。

4. 协作规则

4.1 分支、工作树和提交

  • main 只由总控合并，任何时候都要能构建、测试全绿。

  • 每条线在自己的 git 工作树（worktree）里、自己的分支上工作，不共用目录。Multitask 模式下由总控给每个子 Agent 开独立环境（第 8 节）；需要手动建时：

    git fetch origin
git worktree add ../NixMsg-wt/<任务号> -b feat/<任务号>-<简述> origin/main

  • 分支名：feat/<任务号>-<简述>，例如 feat/n2-websocket-mochi；修别人发现的问题用 fix/<任务号>-<简述>。

  • 一功能一验证一提交：做完一个能验证的小功能，就补测试、跑 task check、提交，并推送到自己的远端分支。

  • 提交信息：type: 中文一句话描述，type 取 feat、fix、refactor、style、docs、test、chore、revert。

  • 不提交：构建产物、web/dist、数据库文件、证书和私钥、任何密码或令牌、aidocs/。

  • 只改自己线负责的目录（第 5 节）。必须动别人的目录时，改动尽量小，并在提交说明和报告里写明。

4.2 共享文件

文件 规则
go.mod、go.sum 各线可以加依赖；冲突时以 main 为准重新 go mod tidy
internal/protocol 总控在阶段 0 定好。之后要改先找总控，由总控改完合进 main，各线再 rebase
internal/store/migrations 0001 由总控在阶段 0 写好，包含全部表。之后要改表结构就加新文件，编号在 rebase 时取当时最大号加一
cmd/nixmsg/wire.go（组装各模块） 各线只加自己的注册代码；冲突时两边都保留
Taskfile.yml 总控维护；各线自己的任务写在 taskfiles/<线名>.yml，由主文件引入
docs/DEVIATIONS.md 按线分节，各线只写自己那节
docs/PRD.md、docs/DEVELOPMENT.md、docs/TASKS.md 开发期间不改 PRD 的产品行为；DEVELOPMENT、TASKS 只有总控能改（例如修正写错的地方），改了什么写进 docs/DEVIATIONS.md

4.3 合并进 main

  1. 开发线：git fetch → git rebase origin/main → task check 和本任务的验证全过 → 推送分支 → 在 MemRelay 存一个检查点，标签 ready-to-merge，写清分支名、任务号、验证结果；Multitask 模式下，同样的内容也写进返回给总控的报告。
  2. 总控：按第 7 节清单审阅差异 → 在主工作区 git merge --ff-only <分支> → 跑 task check 和集成测试 → 推送 main → 通知各线 rebase。
  3. 不能快进（main 已经前进）时打回给开发线重新 rebase。冲突由开发线理解双方改动后解决。
  4. 功能分支 rebase 后，用 git push --force-with-lease 更新自己的远端分支（负责人已同意，见第 9 节）。只能用在自己的 feat/*、fix/* 分支上，不许用于别人的分支；任何人都不许强推 main。
  5. 如果仓库开了分支保护或合并请求审核，改成推分支、建合并请求，由总控合并。
  6. 本期不做 CI（负责人决定）。合并前的全量验证由总控在本机执行，开发线的自测不能代替。

4.4 进度记录

  • 各 Agent 按协作规则使用 MemRelay：开工前读项目上下文和最新检查点；完成一个任务、遇到阻塞、结束一次会话时存检查点，写明线名、任务号、分支、做了什么、验证结果、下一步。
  • 不在仓库里另建进度文件，免得多条线同时改同一个文件。

5. 分工

线 负责目录 主要内容
总控 L 根目录配置、cmd/nixmsg/wire.go、internal/protocol、迁移 0001、test/harness、docs/ 阶段 0（派子 Agent 做）、审阅合并、集成验证、最终验收和发布
平台 P cmd/nixmsg（wire.go 除外）、internal/config、internal/store（0001 除外）、internal/auth 配置和命令、写入合并、密码哈希池、令牌和锁定计数、指标注册
连接 N internal/listener、internal/broker 端口识别、TLS、WebSocket、mochi、登录与会话令牌、连接表、握手
消息 M internal/app/message 提交、分发、推送、确认、撤回、回执、清理、启动恢复
身份 I internal/app/identity、internal/app/group、internal/app/presence 注册、自己的资料、对话密码、在线与目录、群、停用和删除
后台接口 A internal/admin、internal/httpx 管理接口、API 令牌、操作日志、指标接口的访问规则
后台网页 W web/ Naive UI 后台和端到端测试
SDK 一 S1 sdk/go、sdk/js Go、JS/TS SDK
SDK 二 S2 sdk/python、sdk/java Python、Java/Android SDK
测试交付 Q test/（harness 除外）、deploy/、README.md 测试基础设施、验收用例、弱网和压测、Docker、发布、运维文档

6. 阶段和任务

flowchart LR
    T0[阶段0 总控 骨架与契约] --> P[平台 P]
    T0 --> N[连接 N]
    T0 --> M[消息 M]
    T0 --> I[身份 I]
    T0 --> A[后台接口 A]
    T0 --> W[后台网页 W]
    T0 --> Q[测试交付 Q]
    N --> S[SDK S1 S2 接入清单]
    M --> S
    I --> S
    A --> W2[网页联调 W4]
    P & N & M & I & A & S & W2 --> V[阶段2 验收 弱网 压测]
    V --> Z[阶段3 总控 审核与交付]
  • 阶段 0（总控负责，按第 8.2 节分三步派子 Agent 做）：T0.1–T0.5。全部合进 main 并推送后才开阶段 1。
  • 阶段 1、2（并行开发、联调和验收）：按第 8.2 节分四波，由总控派子 Agent 执行。前两波以各线开发为主，后两波以 SDK 接入清单、端到端测试、验收、弱网和压测为主。每波结束由总控审核、合并、验证；发现的问题开 fix/ 分支，交回原负责线修。
  • 阶段 3（只有总控）：全量回归、审核、偏差确认、打标签交付。

下面每个任务都要做到：代码、测试、文档依据里的规则都满足；验证项全部通过；task check 通过。任务说明里的「第 X 节」都指 DEVELOPMENT.md 的小节；指 PRD 或本文的会写明「PRD 第 X 节」「本文第 X 节」。

6.1 阶段 0：总控 L

T0.1 仓库骨架 · 依赖：无

  • 做：按 DEVELOPMENT 第 3 节建目录；go.mod（模块 git.asio.asia/nixevol/NixMsg）；Taskfile.yml，目标至少有 build、test、lint、check（构建加检查加单元测试）、web:dev、web:build、itest（集成测试）、docker，并引入 taskfiles/*.yml；golangci-lint 配置；web/ 用 Vite、Vue 3、TypeScript、Naive UI、Vue Router、Pinia 初始化，加 web/embed.go；cmd/nixmsg 先能 version，serve 先只打开库、跑迁移、在 listen 上提供 /healthz，端口为 0 时写 listen.addr；deploy/config.example.yaml；.cursor/worktrees.json，让新工作树自动执行 go mod download 和 pnpm install。
  • 验证：Windows 上 task check、task build 通过，产物是嵌入了前端的单个可执行文件；在 Docker 的 Linux 容器里 task check 也通过。

T0.2 协议包 internal/protocol · 依赖：T0.1

  • 做：DEVELOPMENT 第 6 节全部帧的 Go 类型，包括第 6.9 节注册的请求和响应、session_token、self.logout；第 6.10 节错误码常量；编码规则（不转义 HTML 和非 ASCII）；字段校验（编号规则、正文和自定义字段大小、send_at_ms 和 delay_ms 互斥）；第 7.3 节的请求指纹；整帧字节数计算。
  • 验证：每种帧的编码、解码、校验都有表驱动单元测试；指纹对 meta 的键顺序不敏感。

T0.3 数据库结构和存储接口 internal/store · 依赖：T0.1

  • 做：第 7.7 节的迁移执行器（有未应用版本时先 VACUUM INTO 备份）；0001_init.sql 包含第 7.7 节全部表和索引；按第 7.7 节的 DSN 打开写连接和读连接池；写入队列的接口（提交一个写操作、拿到结果）和一个先不合并的简单实现，P2 再换成合并提交。
  • 验证：空目录启动能建表；重复启动不会重复迁移；迁移前的备份文件存在；有单元测试。

T0.4 模块接口和管理接口契约 · 依赖：T0.2、T0.3

  • 做：internal/auth 和 internal/app/* 各服务的 Go 接口，以及测试用的假实现；broker 和 app 之间的接口（连接事件、上行帧分发、下行发布）；cmd/nixmsg/wire.go 组装骨架；docs/api/admin-api.md，写清第 8 节每个管理接口的请求、响应、分页和错误格式，W 线据此先用假数据开发。
  • 验证：task check 通过；契约文档覆盖第 8 节全部路由。

T0.5 集成测试启动器 test/harness · 依赖：T0.1

  • 做：编译一次服务端；每个测试用随机端口、临时目录启动一个进程（配置里 listen 的端口写 0，服务端启动后把实际地址写进 <data_dir>/listen.addr，见 DEVELOPMENT 第 4.1 节，启动器读它），自动执行 admin init 拿到管理员密码；提供管理接口客户端和 MQTT 测试客户端（WebSocket 和 TCP 都支持，能收发第 6 节的帧）；另外提供一个命令行启动器（例如 go run ./test/harness/cmd/testserver），在随机端口启动服务，把连接地址和管理员密码以 JSON 打到标准输出，收到 Ctrl+C 时退出并清理，给 JS、Python、Java 的集成测试用；测试结束时清理进程和目录。
  • 验证：示例集成测试能启动服务、访问 /healthz，结束后进程和目录都清干净；两个测试并行跑互不干扰；命令行启动器能打出连接信息，退出后清理干净。

6.2 平台 P

P1 配置和命令 · 依赖：T0.1、T0.3

  • 做：第 11.1 节配置的加载和校验（check-config 拒绝 max_body_bytes 大于 262144）；admin init、admin set-password、backup、healthcheck；log/slog JSON 日志；第 7.8 节的优雅停机。
  • 验证：各命令有测试；admin init 的密码只在终端打印一次、不进日志，已初始化的库拒绝再次执行。

P2 写入合并 · 依赖：T0.3

  • 做：第 7.2 节的合并事务（最多 256 个操作或凑满 2 毫秒）、每个操作一个 SAVEPOINT、读连接池；写库失败时请求返回 busy，/readyz 返回失败。
  • 验证：单个操作失败只回滚它自己；基准测试给出每秒能提交的写操作数，模拟每秒 200 条消息的写入量时队列不堆积。

P3 认证工具 internal/auth · 依赖：T0.1

  • 做：argon2id 哈希池（第 12 节参数、PHC 格式、并发上限）；会话令牌和 API 令牌的生成和哈希；锁定计数器（按键计数、时间窗口、到期解除、手动清除）。
  • 验证：单元测试；并发池能限制同时运行的哈希数；锁定窗口到期自动解除。

P4 指标注册 · 依赖：T0.1

  • 做：用 prometheus/client_golang 建注册表，定义第 4.3 节列出的指标，给各线打点用；/metrics 的处理函数（访问规则由 A 线在路由里加）。
  • 验证：单元测试能抓到指标文本。

6.3 连接 N

N1 端口与 TLS · 依赖：T0.1

  • 做：第 4.1–4.3 节和第 4.5 节：首字节识别、TLS 和证书每小时重载、admin_listen 分离、通道 Listener、路由骨架、受信任代理的真实 IP。
  • 验证：同一端口上明文 HTTP、TLS+HTTP、裸 TCP、TLS+TCP 都能识别；后台分离时的 404 规则；替换证书后新连接用上新证书；声明 ALPN mqtt 的客户端能完成握手。

N2 WebSocket 与 mochi · 依赖：N1、T0.2、T0.4

  • 做：第 4.4 节；第 5 节的装配约束、连接代号、心跳校正、ACL、OnPublish 投进每端的串行队列（长度 256，满了形成背压）；下行发布（整帧大小检查、QoS 选择、第 7.5 节的大帧并发名额）。
  • 验证：浏览器页面从别的域名连 /mqtt 成功；子协议不对的连接被关闭；超过客户端上限的下行不发布，并回调上层；QoS 0 的事件不占 inflight。

N3 登录、会话令牌和握手 · 依赖：N2、P3、T0.3

  • 做：第 5 节「登录与会话令牌」和锁定（用 P3 的工具）；内部故障时让 OnConnect 返回 error；顶号和连接表；第 6.1 节握手（返回 session_token、30 秒没握手就断开、没订阅 down 就断开）；self.logout；online_since 和 offline_since；把上下线事件交给 I 线。
  • 验证：F02 的全部验收（用测试启动器）；数据库不可读时客户端连接被直接关闭，而不是收到 0x86。

6.4 消息 M

M1 提交 · 依赖：T0.2、T0.3、T0.4

  • 做：第 6.2 节和第 7.3 节：先查防重，再校验、查配额、写授权和回复授权，发送时刻已到的立即分发；请求频率桶（第 6.10 节）。
  • 验证：表驱动测试覆盖防重命中、冲突、配额、授权、延迟和定时互斥。

M2 分发与推送 · 依赖：M1、N2

  • 做：第 7.4 节和第 7.5 节：调度器、queue_full、停用成员、推送窗口、确认计时和两种超时规则、OnPublishDropped 后重推、握手和断线时的投递调整、每秒清理循环。
  • 验证：F08–F12 的状态机测试和集成测试。

M3 确认、撤回、回执、状态 · 依赖：M2

  • 做：第 6.3 节、第 6.4 节、第 7.6 节：确认、撤回结果的判定、回执写入和推送窗口、revoked、status 分页、收尾删正文、每小时清理（防重行按条件删、分批删、wal_checkpoint）。
  • 验证：F13、F14、F18 的测试。

M4 启动恢复 · 依赖：M2

  • 做：第 7.8 节的启动恢复和写库失败处理。
  • 验证：推送中杀掉进程再重启，不保留的消息在宽限内重连仍能送到；停机期间到点的定时消息在启动后发出。

6.5 身份 I

I1 注册接口 · 依赖：T0.3、P3、N1

  • 做：第 6.9 节：开关、安全码、锁定、跨域、字段规则、source=self；settings 表读写。
  • 验证：F23 的全部验收。

I2 自己的资料和对话密码 · 依赖：N3、T0.2

  • 做：第 6.6 节的 self.*（改登录密码时返回新令牌）、unlock、授权表（版本、两种授权、回复授权）、按对方计总数的暂停。
  • 验证：F15 的全部验收。

I3 在线与目录 · 依赖：N3

  • 做：第 6.5 节：presence.get、presence.watch（QoS 0 事件）、directory.list（分页和 query）。
  • 验证：F03、F04 的验收。

I4 群 · 依赖：M1、I2

  • 做：第 6.7 节全部帧、群事件、成员上限、加人时的对话密码、退群、踢人、解散、转让，以及第 7.6 节表里的作废规则。
  • 验证：F06、F16 的验收。

I5 停用与删除 · 依赖：M3、I4

  • 做：第 7.6 节表里停用、删除端的全部处理（清会话令牌、作废消息、转让群主、清理数据），提供给 A 线调用。
  • 验证：F01 里停用和删除相关的验收；删除后用同一编号重新开通，不会串到旧数据。

6.6 后台接口 A

A1 鉴权 · 依赖：T0.3、T0.4、P3

  • 做：第 8 节的 Cookie 会话、X-Nixmsg-Request 头、管理员登录锁定、API 令牌鉴权和权限限制、令牌管理接口、操作日志。
  • 验证：F17 里令牌相关的验收；用令牌调用改管理员密码和令牌管理接口被拒绝。

A2 端管理 · 依赖：A1、I5、N3

  • 做：列表（按来源、在线状态筛选）、开通、CSV 批量开通（整批校验、结果只给一次）、批量停用、启用、删除、编辑、重置密码、踢下线、unlock、设置对话密码。
  • 验证：F01 的验收；导入 1000 行 CSV 成功。

A3 其余接口 · 依赖：A1、I1、I4、M3、P4

  • 做：注册设置、群管理、记录查询（筛选、分页、响应不含正文）、概览、只读设置、/metrics 的访问规则（第 4.3 节）。
  • 验证：F17 和 F22 里指标相关的验收；在所有管理接口的响应里搜不到测试正文。

6.7 后台网页 W

W1 框架 · 依赖：T0.1、T0.4

  • 做：第 2.4 节的界面要求和 Naive UI 用法；布局、登录页、路由守卫、请求封装（CSRF 头、错误提示）、中文。先按契约用假数据开发。
  • 验证：vue-tsc 类型检查、ESLint、Vitest 通过；页面在 1366×768 和 1920×1080 下没有重叠和遮挡。

W2 端管理页 · 依赖：W1

  • 做：列表、筛选、多选批量操作、开通和编辑弹窗、CSV 导入和结果下载、重置密码的结果只显示一次、解除锁定、设置对话密码。
  • 验证：组件测试；假数据下主流程可用。

W3 其余页面 · 依赖：W1

  • 做：概览、注册设置、群、投递记录、API 令牌（创建后只显示一次）、改管理员密码、只读参数。
  • 验证：组件测试；假数据下主流程可用。

W4 联调和端到端测试 · 依赖：A2、A3

  • 做：接真实接口；用 Playwright 走第 13 节的后台主路径（登录、开通、开启注册并设置安全码、建群、看到未完成记录），再加 API 令牌的创建和停用。
  • 验证：端到端测试在 task itest 里通过。

6.8 SDK S1、S2

S1 先做 Go，再做 JS/TS；S2 先做 Python，再做 Java/Android。每种语言都按下面五个任务做，任务号带语言，例如 S1-GO-1、S2-JAVA-3。

任务 内容 依赖
1 连接和会话 WebSocket（TCP 可选）、每次连接都带 Clean Start、握手、会话令牌（onSession、用令牌重连、session_invalid）、退避、停止重连的条件、连接超时 30 秒 T0.2
2 收发 发送队列（上限 1000、在途 100、rate_limited 自动重交、send_at_ms 不重算）、去重和再确认、串行回调、自动和手动确认、revoked、本地大小检查 任务 1
3 其余接口 撤回、状态、回执、在线、目录、订阅、群、self.*、logout、注册 任务 2
4 接入清单 第 9 节的 15 条集成测试，用 T0.5 的启动器起真实服务端 任务 3，以及 N3、M3、I2、I4 已合进 main
5 打包和文档 按 DEVELOPMENT 第 9 节设置包名、许可证信息和发布配置，用各工具的试运行方式确认能打包（真正发布在 Z3）；写这种语言的 README 和最小示例 任务 4

各语言的要点在 DEVELOPMENT 第 2.3 节和第 9 节：Go 用 ConnectPacketBuilder 每次设 Clean Start；JS 同时支持浏览器和 Node，发 ESM 和 CJS，要测跨域；Python 同步为主，另给 asyncio 包装；Java 编译成 Java 8 字节码，写清 Android API 24 的用法。

6.9 测试交付 Q

Q1 测试基础设施 · 依赖：T0.5

  • 做：toxiproxy 和 netem 的 Docker 编排（名字带前缀）；1000 连接的压测客户端；验收报告生成（F01–F23 对照表）。
  • 验证：能对一个运行中的服务端注入延迟、丢包、断开；压测客户端能保持 1000 个连接。

Q2 验收用例 · 依赖：各线的核心任务

  • 做：PRD 第 10 节每条至少有一个集成测试；各线写过的算数，Q 负责补齐和汇总成报告。
  • 验证：报告列出 F01–F23 每条的结果。

Q3 弱网、崩溃、压测 · 依赖：Q1、Q2

  • 做：DEVELOPMENT 第 13 节的全部相关测试，并出报告。
  • 验证：报告里的数字满足 PRD 第 8 节。

Q4 Docker 与发布 · 依赖：T0.1，最终在阶段 2 完成

  • 做：第 11.4 节的多阶段、多架构镜像；compose 示例；三个平台的二进制；镜像冒烟测试；推送镜像的 Taskfile 目标（推到 git.asio.asia/nixevol/nixmsg，真正推送在 Z3）；第 11.3 节 1Panel 证书说明。
  • 验证：两个架构的镜像都能初始化、启动、通过健康检查。

Q5 文档 · 依赖：各线完成

  • 做：README（功能、构建、运行）、运维手册（配置、备份、升级、证书、时钟、指标）、SDK 文档汇总。
  • 验证：按 README 在一台干净机器上能构建和启动。

6.10 阶段 3：总控 L

Z1 全量回归：在 main 上跑 task check、全部集成测试、端到端测试、四个 SDK 的接入清单、弱网和压测。

Z2 审核：按本文第 7 节清单逐项审核；做安全检查（日志和管理接口里没有正文、密码、令牌）；检查依赖的许可证。

Z3 交付：汇总 docs/DEVIATIONS.md 写进交付说明，供负责人回来审阅，不等确认；打 v0.1.0 和 sdk/go/v0.1.0 标签并推送；按本文第 3 节创建发布令牌，把 npm、PyPI、Maven 三个 SDK 包发布到 Gitea 包仓库，把两个架构的镜像推到 git.asio.asia/nixevol/nixmsg（版本号标签和 latest）；构建三个平台的二进制；写交付说明（功能清单、验收结果、已知问题）。

7. 审核清单

总控每次合并前和最终审核时都要过一遍：

  • 行为和 PRD 一致，实现和 DEVELOPMENT 一致；不一致的已写进 docs/DEVIATIONS.md。
  • 没有违反 DEVELOPMENT 第 15 节的任何一条。
  • MemRelay 里「依赖库行为核对结论」涉及的点都做对了：OnConnect 和 OnConnectAuthenticate 的分工、CodeSuccessIgnore、下行大小自查、WebSocket 的 Origin 校验、TLS 的 NextProtos、每次连接都带 Clean Start。
  • 所有写库都走写入队列；条件更新都检查了影响行数。
  • 日志、错误信息、管理接口响应里没有正文、密码、令牌和注册安全码。
  • 新代码有测试；测试用随机端口和临时目录。
  • 没有引入技术栈以外的框架和中间件。

8. 负责人操作说明（Cursor Multitask 模式）

负责人只给总控发一段提示词，之后全程自动，不再向负责人提问。总控分波派出子 Agent 并行开发（阶段 0 也由子 Agent 完成），每个子 Agent 在独立的工作树和分支里工作；每波结束由总控审核、合并、验证，最后执行阶段 3 并发布。用本地 Agent：仓库在自建的 Gitea 上，Cursor 的云端 Agent 只支持 GitHub、GitLab 等托管平台，而且用不了本机的 Docker。

8.1 负责人要做的

  1. 在 Cursor 里新建一个 Agent，模型选 Grok，切到 Multitask 模式，把下面的提示词原样发出，之后就可以离开。
  2. 总控不会停下来问你。每完成一波，它会在对话里留一段汇报；它自己拿的主意和与文档不一致的地方都记在 docs/DEVIATIONS.md，最后汇总进交付说明，回来后审阅即可。
  3. 回来时如果发现它停在半路（例如会话太长被截断、机器重启），新开一个 Multitask 会话再发一次同样的提示词。总控会看 MemRelay 检查点和 git 记录，从断点继续。
  4. 并行 N 个子 Agent，用量大约是 N 倍。Cursor 默认整台机器最多保留 25 个工作树，超出会删掉最旧的，所以总控合并后要及时删掉用完的工作树；需要时在设置里调大 cursor.worktreeMaxCount。

提示词：

你是 NixMsg 项目的总控 Agent，工作目录 e:\code\NixMsg（仓库 https://git.asio.asia/nixevol/NixMsg.git，主分支 main）。目标：用多个子 Agent 并行，把整个系统开发、测试、发布到交付状态。负责人不在，全程自动完成：中途不要向负责人提问，也不要等回复。

开工前：按协作规则读 MemRelay 项目记忆（项目 NixMsg）和最新检查点，看 git log，再完整阅读 docs/PRD.md、docs/DEVELOPMENT.md、docs/TASKS.md。如果前面的阶段或波次已经完成，从断点继续，不要重做。TASKS.md 第 8.2 节是编排计划，第 8.3 节是子 Agent 提示词模板，第 7 节是审核清单，严格照做。

执行顺序：
1. 按第 8.2 节从阶段 0 开始，一波一波推进。每一波在同一条消息里同时启动这一波的全部子 Agent；每个子 Agent 必须在各自独立的环境里运行（独立工作树和独立分支，each in its own environment），用和你相同的模型；用第 8.3 节模板把它的线、任务、负责目录、要读的文档小节和要返回的内容写清楚，因为子 Agent 看不到你的上下文。子 Agent 报告的工作路径如果是主工作区而不是独立工作树，这一波改为逐个串行执行。
2. 每一波的子 Agent 全部返回后：逐个按第 7 节审核；按第 8.2 节的合并顺序 rebase 后快进合并进 main，每合并一个跑一次 task check，全部合并后跑集成测试，再推送 main。审核或合并不通过的，让原来的子 Agent 接着修（resume），或者新开一个修复子 Agent（fix/ 分支），修好再合并。合并后删掉对应工作树，在 MemRelay 存检查点，在对话里写几句本波汇报（合并了什么、测试结果、遗留问题），然后不要结束，直接进入下一波。
3. 四波都完成后执行阶段 3（Z1–Z3）：全量回归、审核，把 DEVIATIONS 汇总进交付说明，打标签、发布 SDK 和镜像、写交付说明。这些全部完成后才结束。

规则：
- 需要拿主意时，按和 PRD、DEVELOPMENT、PRD 第 9 节已确认决定最一致、最稳妥的做法自己决定，写进 docs/DEVIATIONS.md（写明原因和备选方案），不改 PRD 的产品行为。
- 卡住的问题先换思路解决；实在解决不了就记进遗留问题，继续推进其余工作，最后在交付说明里写清楚。
- main 只由你合并，任何时候都要构建和测试全绿；子 Agent 不能再派生子 Agent，只做自己那条线。
- 不做破坏性操作：不删除业务数据和别人的文件，不强推、不改写 main 的历史，要撤销就用 git revert；清理自己建的分支、工作树、容器和测试数据可以直接做。
- 具体的开发、调试、修复都交给子 Agent，你只做编排、审核、合并和验证；少读大段输出，保持自己的上下文精简，避免中途被截断。

8.2 编排计划（总控照此执行）

波次 同时启动的子 Agent（线：任务） 合并顺序
阶段 0 分三步，每步合并后再开下一步：先 L：T0.1；再同时 L：T0.2、L：T0.3、L：T0.5；最后 L：T0.4 按步骤顺序；第二步里 T0.2 → T0.3 → T0.5
第 1 波 P：P1–P4；N：N1–N2；M：M1；I：I1；A：A1；W：W1–W3（用假数据）；Q：Q1 和 Q4 的镜像骨架；S1：Go、JS 的任务 1–3；S2：Python、Java 的任务 1–3 P → N → M → I → A → W → Q → S1 → S2
第 2 波 N：N3；M：M2–M4；I：I2–I4；A：A2；Q：已合并功能的验收用例（Q2 的第一部分） N → M → I → A → Q
第 3 波 I：I5；A：A3；S1：Go、JS 的任务 4–5；S2：Python、Java 的任务 4–5；Q：补齐 Q2，做 Q3 I → A → S1 → S2 → Q
第 4 波 W：W4；Q：Q4 定稿、Q5 W → Q
阶段 3 总控负责 Z1–Z3：回归中发现的问题派修复子 Agent（fix/ 分支），打标签、发布等收尾由总控执行 —
  • 每一波只依赖之前已经合进 main 的成果。同一波里依赖别的线还没合并的功能时（例如第 1 波的 A1、I1 用到 P3、N1，第 2 波的 I2、I3 用到 N3，A2 用到 I5），先用 T0.4 的接口和假实现写代码和单元测试，合并时由总控接上真实实现；需要真实实现的集成测试放到下一波补上。
  • 同一波的子 Agent 互相看不到对方的改动，只能看到这一波开始时的 main。
  • 每个子 Agent 做完先推送自己的分支、确认工作区干净，再返回报告。
  • 同一波子 Agent 太多、机器吃不消时，分两批启动，合并顺序不变。

8.3 子 Agent 提示词模板（总控把花括号换成具体内容再发）

你是 NixMsg 的开发线 {线名} 子 Agent，在自己独立的工作树和分支上工作，起点是 origin/main 的最新提交，分支按 feat/{任务号}-{简述} 命名。你看不到之前的对话，需要的信息都在仓库文档和 MemRelay 项目记忆（项目 NixMsg）里。

先读：docs/TASKS.md 第 3、4、5 节和第 6 节里 {任务号} 的说明；docs/DEVELOPMENT.md 的 {相关小节}；docs/PRD.md 的 {相关功能编号}；.cursor/rules/nixmsg-dev.mdc。

要做：按顺序完成 {任务号}，只改 {负责目录}。这一波里别的线还没合并的功能，用 T0.4 的接口和假实现。

规则：一功能一验证一提交（补测试 → task check 通过 → 提交 → 推送自己的分支）；提交信息用「type: 中文一句话」；测试用随机端口和临时目录；缺工具用 scoop 安装；实现和文档不一致的，写进 docs/DEVIATIONS.md 你那一节；不能再派生子 Agent；文档没写清或有疑问时，按和 PRD、DEVELOPMENT、PRD 第 9 节已确认决定最一致的做法实现，写进 DEVIATIONS 你那一节和报告，不要停下来等回复，也不要改 PRD；不做破坏性操作（不删别人的文件和数据，不碰 main）。

完成后返回：1）分支名和工作树路径；2）提交列表；3）每个任务的完成情况、验证命令和结果；4）写进 DEVIATIONS 的内容；5）没做完或拿不准的地方。返回前确认分支已推送、工作区干净。

9. 负责人已确认的协作事项

  • 2026-09-30：允许各开发 Agent 在 rebase 后用 git push --force-with-lease 更新自己的 feat/*、fix/* 远端分支；main 任何时候都不许强推。
  • 2026-09-30：SDK 发布到 Gitea 包仓库，镜像推到 git.asio.asia/nixevol/nixmsg；本期不做 CI；许可证为专有，源码仓库和发布物公开可读（DEVELOPMENT 第 2.1 节、第 9 节、第 11.4 节）。
  • PRD 第 9 节的默认规则 D1–D33 已全部确认，开发中不再等待确认；和文档不一致的实现按第 4.2 节写进 docs/DEVIATIONS.md。
  • 2026-09-30：负责人授权全程自动开发。开发、测试、发布过程中不向负责人提问、不等回复；需要拿主意时，按和 PRD、DEVELOPMENT、已确认决定最一致、最稳妥的做法自己定，写进 docs/DEVIATIONS.md（原因和备选方案），不改 PRD 的产品行为；不做破坏性操作；解决不了的问题记进遗留问题，继续推进其余工作。
Reference in New Issue View Git Blame Copy Permalink