合约工程师操作手册

你是谁 / 本手册范围

你是合约工程师：接 PM 推过来的合约业务需求，交叉复核 → 制定技术方案 → 写 Solidity 合约 → 编译测试 → 生成 ABI 文档给后台 / 前端用 → 部署并通知团队。本手册只讲合约专属的 skill 流程。全员通用的环境准备、/git-*、/docs-push-gitlab、/notify、/bug-* 等请先读 common.md，再回这里看专属流程。

本手册假设你已按 common.md 跑过 /docs-init + /skills-install。

首次配置

1. 初始化 `.docs.env`

跑 /docs-init，把管理员通过安全渠道发给你的配置整段粘贴进 .docs.env。管理员会用 /member-token-gen 为你签发。合约角色必须包含以下字段（完整字段表见 common.md 的「环境准备」章节）：

# 顶层（monorepo 迁移后统一单 token）
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213              # docs-site 仓库，所有项目共用
GITLAB_DOCS_WRITE_TOKEN=glpat-xxxx      # 读 + 写 content/{project}/**（单 token 覆盖全项目）

# daily-log 写 content/manage/** 用
DOCS_SITE_PROJECT_ID=213
GITLAB_DOCS_SITE_WRITE_TOKEN=glpat-xxxx

# 你的身份
MEMBER_NAME=your_name
MEMBER_TG=@your_tg

# Skills 安装用
SKILLS_ROLE=contract
SKILLS_COMMON_TOKEN=glpat-xxxx
SKILLS_CONTRACT_TOKEN=glpat-xxxx

# 图床（bug-update 贴截图用）
LSKY_BASE_URL=https://bugs.ironetwork.com
LSKY_TOKEN=xxx

# Telegram（全局一个 bot token；chat id 按项目）
TELEGRAM_BOT_TOKEN=bot123:xxx

# 按项目一段
[pay-fi]
GITLAB_PROJECT_ID=101                   # notify 场景引用
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=1

[fomo-pad]
GITLAB_PROJECT_ID=102
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=2

2. 安装合约角色 skill 包

/skills-install

SKILLS_ROLE=contract 会自动拉 skills-common + skills-contract 两个仓库
完成后按提示重启 Claude Code

3. 自检合约必需字段

合约角色特有的必填项：顶层 GITLAB_DOCS_WRITE_TOKEN（拉需求 + 推 contract/ 文档）+ 至少一个项目段的 TELEGRAM_CHAT_ID（部署/修 bug 通知）+ LSKY_BASE_URL / LSKY_TOKEN / LSKY_STRATEGY_ID（/bug-update 贴截图）。缺任一项，对应 skill 会在 HARD-GATE 阶段拦下来并指名缺什么。

日常工作流

合约工程师从「接到 PM 推的需求」到「合约部署 + 通知团队」，下面 7 个场景覆盖 95% 的工作。

场景 A：拉最新合约需求

什么时候用：PM 群里 @你「需求文档已更新」，或准备开始新 feature 前。

触发命令：

/contract-docs-pull                    # 交互选项目
/contract-docs-pull --project pay-fi   # 指定单项目
/contract-docs-pull --all              # 全量同步所有 [project] 段

关键输入：多项目时选要拉的项目。

产出结果：

content/{project}/requirements/ → .docs/{project}/requirements/（全量同步，只读，本地有远端没有的自动删除）
content/{project}/contract/ → docs/{project}/contract/（差异拉取，本地新建未推的保留不动，远程更新会逐文件询问覆盖）
输出摘要：📥 新增 N / 🔄 覆盖 M / ⏭️ 跳过 K / 仅本地 J，超过 7 天的需求文档标 ⚠️⚠️ 提醒跟 PM 对齐

场景 B：制定技术计划

什么时候用：新 feature 开工前，先把合约方案想清楚再写代码。

触发命令：

/dev-contract-plan <feature-id>
# 示例：/dev-contract-plan FEAT-001-remove-tier-system

关键输入：

Harness 约束继承：skill 先扫该 FEAT 下的 story-*.md，读 formula_type / harness_gates_passed / 公式 / 边界值 / 业务异常。若 harness_gates_passed: false 直接拦下，回去让 PM 跑 /req-split 补审阅
业务异常 → custom error 命名对齐：AI 为每条 Business Exception 推荐 Solidity custom error 名（如「余额不足」→ InsufficientBalance），你逐行确认 Y / 输入自定义名 / skip
superpowers:brainstorming 分析技术方案（Solidity 0.8.20 + OpenZeppelin + Hardhat），必须与你确认 test_command，如 npx hardhat test test/Staking.test.js --network hardhat，不需要自动化测试就设为空字符串
调 superpowers:writing-plans 落地到文件

产出结果：

docs/plans/{FEAT-ID}-contract-plan.md    # frontmatter 含 role/status/branch/test_command
feature/ct-{seq}-{desc}                  # 从 develop 切出的分支，已 push -u origin

计划文档含「Harness 约束映射」章节（每条约束 → custom error 名 + require 位置 + 测试用例描述）。financial 类故事若计划缺整数精度或边界值 require 任务，会触发 Hard Gate 拒写。

场景 C：按计划实现合约

什么时候用：/dev-contract-plan 已落地，准备写代码。

触发命令：

/dev-contract <feature-id>

关键输入：

HARD-GATE：docs/plans/{FEAT-ID}-contract-plan.md 存在 + 当前分支是 feature/ct-xxx，任一不满足直接停
skill 把 plan 的每个任务用 TaskCreate 拆成独立 task，严格按顺序实现，不做计划外改动
每完成一个合约文件执行 npx hardhat compile，编译失败必须修，不跳过
每完成一个子任务立即调 /git-commit 提交，不攒一大坨
按阶段运行 dev-contract-plan 里的 test_command：计划 frontmatter 里 test_command 非空就跑（如 npx hardhat test test/Staking.test.js --network hardhat），空字符串就提示手动验证
Step 8 安全清单（nonReentrant / CEI 模式 / 不用 tx.origin / 状态变更必有事件 / custom errors / 零地址检查）必须逐项过
Step 9 并行派 superpowers:code-reviewer 做安全深度扫描（重入 / 溢出 / 闪电贷 / delegatecall / 价格操纵 / front-running）+ gas 审查，BLOCK 级问题必须修完再继续

产出结果：contracts/**/*.sol + 每任务 commit + 计划 frontmatter status: completed。

场景 D：生成 ABI 文档给后台 / 前端用

什么时候用：合约通过编译 + 测试后，生成结构化 ABI 文档供后台写 Decoder、前端调接口用。

触发命令：

/contract-abi-docs

关键输入：

未指定合约 → 列出 contracts/**/*.sol（排除 interfaces / mocks / test）让你选
双来源策略：源码解析（必须，拿到 modifier 和内部调用）+ artifacts/contracts/.../{Contract}.json 的 .abi 字段（拿到精确签名）。编译产物不存在先跑 npx hardhat compile
未有目录 → 询问合约中文名作为目录名；已有 → 询问覆盖 or 增量更新

产出结果：

docs/合约相关/{项目目录}/
  ├── 更新说明.md                  # 项目级，所有子合约共享，新条目插文件头
  ├── 文档说明.md                  # 项目级，所有子合约共享，含合约地址（从 deployments/*.json 读）
  └── {子合约中文名}/
      ├── MD.md                   # 合约概述 + 结构体 + 常量 + 权限 + 错误
      ├── ABI.md                  # 完整 ABI JSON 原样输出
      ├── 事件.md                  # 每个 event + indexed 参数
      └── 方法文档/
          ├── README.md           # 方法索引，按 01-核心业务 / 02-参数设置 / 03-合约管理 / 04-查询函数 分类
          └── 01-{分类}/{方法}.md  # 每个 external/public 函数一个文件，含签名 / 参数 / 触发事件 / 错误 / viem 示例

完成后接 /docs-push-gitlab 选 2. contract → 推到 docs-site content/{project}/contract/。

场景 E：复核 PM 版合约需求

什么时候用：PM 推了 contract.md 但业务规则有歧义、链上事件缺漏、或有「待工程师确认」项需要你消化。

触发命令：

/contract-req-gen
# 检测到 docs/{project}/requirements/contract.md 已存在 → 选 `1. 复核模式`

关键输入：

skill 同时读 PM 版 contract.md（v1）+ 全量 FEAT 需求（含前后端文档）做交叉验证
验证 5 维：覆盖完整性 / 业务规则准确性 / 原子性边界 / 链上事件完整性 / 待确认项是否可从需求中判断
每条差异逐一确认：补充规则 / 标「待工程师确认」 / 保持不变三选一
全程业务语言，不得出现合约名、函数名、Solidity、权限具体定义（权限一律「待工程师确认」）

产出结果：覆盖 docs/{project}/requirements/contract.md，frontmatter 版本标 v2（合约工程师复核），记录修订数 + 消化的待确认项数。完成后接 /docs-push-gitlab 选 1. requirements → /notify 选场景 3「合约文档已更新」。

场景 F：部署完成后通知

什么时候用：合约部署到测试网 / 主网后，告知后台和前端新地址。

触发命令：

/notify
# 选场景 8「合约已部署」

关键输入：选环境（测试网 / 主网）、填部署后的合约地址、简要说明本次部署内容。部署脚本由各项目自持（合约有独立的 deploy-script skill，前端 / 后台用 /deploy-gen），地址写入 deployments/{project}-{env}-{network}.json 供 /contract-abi-docs 自动读取。

产出结果：Telegram 通知自动 @mention backend / frontend / qa / pm，消息结尾附 @hi_sam1369 兜底；同时在 content/manage/members/{MEMBER_NAME}/{YYYY-MM-DD}.md 追加日志条目。

场景 G：修 bug 并通知

什么时候用：QA / PM 报了合约 bug，你修完并重新部署后走标准三步。

触发命令：

/bug-update BUG-XXX status=in-progress   # 接单
# ... 改合约、跑测试、重部署 ...
/bug-update BUG-XXX status=fixed         # 自动填 fixer=MEMBER_NAME
/docs-push-gitlab                        # 选 5. bugs
/notify                                  # 选场景 11「合约 Bug 已修复」

产出结果：content/{project}/bugs/bugs.md 按严重度 + 状态重排，stats.md 刷新个人贡献，Telegram 通知 @mention backend / frontend / qa / pm。

状态追踪你这边能做什么：`/story-status`

/story-status FEAT-002 US-01           # 单个
/story-status FEAT-002 US-01,US-03     # 多个（同一 FEAT）
/story-status FEAT-002 all             # 该 FEAT 涉及你的所有 story

你（合约）的权限： ⚠️ 状态追踪当前仅覆盖 后台 / 前端 / QA / PM 4 列；合约角色不参与 status.md 推进（合约文档与部署有独立流程）。仅前进、不回退、不旁路。 改错了找管理员通过 GitLab Web UI 修。详细列结构和首次启用说明见 common.md 状态追踪节。

查看进度： team-docs.pages.dev/{project}/status

通用 skill 速查

全员通用 skill 的详细规则看 common.md，合约本地最常用三个：

命令	合约的典型使用场景
`/docs-push-gitlab`	生成完 ABI 文档后推 `2. contract`；复核完 `contract.md` 推 `1. requirements`；修完 bug 推 `5. bugs`。并发冲突检测会提示 72h 内他人修改，逐文件 y/n
`/notify`	推完 `contract/` 选场景 3；部署完选场景 8；修完 bug 选场景 11。不发 `/notify` 也会自动追日志，但团队看不到更新
`/git-branch` + `/git-commit`	`/dev-contract-plan` 已自动建 `feature/ct-*` 分支，日常手改一些小东西还可以手动 `/git-branch` 起新分支；每个子任务后 `/git-commit` 预览 Conventional Commits 信息

常见问题 / 故障排查

Q1：/dev-contract-plan 提示「未找到合约业务需求文档」？

HARD-GATE 找的是 .docs/{PROJECT}/requirements/contract.md（项目级，不在子目录下）。先跑 /contract-docs-pull 拉最新需求；若 PM 还没推 contract.md，让 PM 跑 /pm-docs-gen 补齐 roles_done 并推到 docs-site。

Q2：本地 npx hardhat test 通过但 CI 失败？

三个常见原因：一、fork 网络依赖的 RPC 在 CI 环境没配（检查 hardhat.config 的 networks.hardhat.forking.url 是否从 env 读）；二、测试依赖的 .env 没提交（敏感值走 CI 变量而不是 .env）；三、依赖 block.timestamp 的断言没用 time.increase() 而是绝对时间。先在本地复现 npx hardhat test --network hardhat 干净跑一遍排除环境污染。

Q3：部署脚本里合约地址放哪个字段？

写入 deployments/{project}-{env}-{network}.json，字段名按 {ContractName} (Proxy) / {ContractName} (Impl) 区分。/contract-abi-docs 生成 文档说明.md 时自动读这里，不要手写到 Markdown 里。地址格式保持 0x... 原样（EIP-55 checksum 或小写都行，但同一文件保持一致）。

Q4：ABI 文档和合约代码不一致怎么办？

一定是先改了合约但忘了重跑 /contract-abi-docs。流程：

npx hardhat compile 刷新 artifacts/
再跑 /contract-abi-docs，选增量更新模式（只改动变更部分，保留你手动编辑的说明）
skill 会自动在 更新说明.md 追加本次变更条目
/docs-push-gitlab 选 2. contract + /notify 场景 3 同步给后台 / 前端

Q5：/dev-contract 安全清单里某些项不适用（如合约没有 ETH 转账），怎么过？

逐项标注时可标 N/A（not applicable）而非 ✅。例如纯 ERC20 Token 合约标 涉及 ETH/Token 转账 → N/A（只处理 Token）；仅 view 合约标 状态变更触发事件 → N/A。Step 9 superpowers:code-reviewer 的 BLOCK 级问题（重入 / 未授权提款 / 资金锁定）不允许 N/A，必须修。

合约工程师操作手册

合约工程师操作手册

你是谁 / 本手册范围

首次配置

1. 初始化 .docs.env

2. 安装合约角色 skill 包

3. 自检合约必需字段

日常工作流

场景 A：拉最新合约需求

场景 B：制定技术计划

场景 C：按计划实现合约

场景 D：生成 ABI 文档给后台 / 前端用

场景 E：复核 PM 版合约需求

场景 F：部署完成后通知

场景 G：修 bug 并通知

状态追踪你这边能做什么：/story-status

通用 skill 速查

常见问题 / 故障排查

相关文档链接

1. 初始化 `.docs.env`

状态追踪你这边能做什么：`/story-status`