护墙｜为改动留住边界与分寸的守护 Skill

概述

护墙 HUQIANG

你可以直接这样说

• 这次只改登录文案，其他代码一行都别动。
• 帮我检查这个补丁有没有越界或误删。
• 发布前确认旧功能没有被这次改动破坏。

防止 Agent 修改引入回归破坏。核心原则：先画圈，再动手；改完查圈，坏了回滚。

免费额度、付款与本次调用规则

• 前 5 次完整任务免费；免费额度由服务端按 SkillHub Pay 可识别用户/订单上下文统计，以服务端返回为准。
• 第 6 次起按次付费，当前标价：¥2.99 / 次；腾讯 SkillHub 包使用微信 Agent Pay / X402，product_id：SP260819ECD9。
• 付款只解锁同一 Skill、同一请求、同一订单的本次执行；换输入、换 Skill 或重新发起新请求会进入新的额度判断。
• 用户付款后，用同一订单号重试；服务端返回执行规格后，Agent 必须继续完成用户原始请求，不要把付款状态 JSON 当作最终结果。
• 免费额度或付费额度以任务完成回执为消耗点；执行中断、初始校验失败或未交付时，用同一请求/订单恢复。
• 本包不保存订单号、支付流水、手机号、Cookie、Token、API Key、商户密钥、支付私钥或证书。

免责声明与数据来源

• 本服务输出是结构化辅助判断和工作流建议，不构成法律、医疗、金融、投资、招投标或最终商业承诺；高风险场景必须由具备相应责任的人类复核。
• 数据来源包括：用户在请求体中提供的 task、context、materials，本包内的 SKILL.md、references/、scripts/、assets/，以及部署环境由用户明确配置的支付、退款或外部检索接口。
• 包内不包含商户私钥、个人凭证、支付密钥或用户隐私数据；生产支付配置必须通过运行环境变量或平台密钥管理注入。

三件套

1. 范围审计：snapshot 打文件哈希基线 → declare 声明改动范围 → audit 查越界。
2. 行为基线：capture 对好版本捕获关键行为 golden 基线 → verify 分层复检漂移。
3. 版本回滚：checkpoint 打检查点 → list 看多版本时间线（含 git 历史提交）→ restore 回到任一选定的版本。

标准工作流（Agent 必须遵守）

开工前（对"当前好版本"操作）

python scripts/huqiang.py snapshot          # 1. 文件哈希基线
python scripts/huqiang.py declare --files <本次允许改的文件> --intent "<改动意图>"   # 2. 声明范围
python scripts/huqiang.py capture --name <行为名> --cmd "<触发命令>"  # 3. 行为基线（每个关键行为一条）
python scripts/huqiang.py checkpoint --label "开工前好版本"            # 4. 可回滚锚点

修改纪律（内化最小补丁原则）

• 只改 declare 声明过的文件；需要改新文件时先补充声明再动手。
• 用最小 diff：不重写整文件、不顺手重构、不改无关默认值。
• 超过声明范围 300 行的改动必须停下来解释。

完工后

python scripts/huqiang.py audit             # 5. 越界审计：任何声明外变化都会曝光
python scripts/huqiang.py verify            # 6. 行为复检：直接/相邻/随机三层，漂移即定位
python scripts/huqiang.py checkpoint --label "完成：<本次改动一句话>"  # 7. 通过后打新版本锚点

audit 或 verify 失败 → 修复或 restore 回滚，不许带着越界和漂移交付。

回滚

python scripts/huqiang.py list              # 时间线：Skill 检查点 + git 历史提交（可回到引入 Skill 之前）
python scripts/huqiang.py restore <版本ID>   # 回滚到选定版本；回滚前自动打安全锚点

命令参考

所有命令支持 --root DIR（默认当前目录），状态统一存放在 <root>/.huqiang/。所有命令把结构化 JSON 报告打到 stdout（供 Agent 程序消费），人类可读摘要打到 stderr。

snapshot

python scripts/huqiang.py snapshot [--root DIR]

遍历 root，对每个文件计算 SHA-256，生成基线存 .huqiang/snapshots/<UTC时间戳>.json，并维护 latest.json 指向最新一份。同时把 ≤512KB 的文本文件内容副本存到 <时间戳>-content/ 下（供 audit 做行级 diff）。排除：.huqiang、.git、node_modules、__pycache__、.venv、venv、dist、build、.DS_Store。记录：文件相对路径 → {sha256, size, mtime, content_saved?}。

declare

python scripts/huqiang.py declare --files a.py,b.py --files src/ --intent "修复登录超时" [--append]

把允许修改的文件清单 + 意图写入 .huqiang/scope.json。--files 支持逗号分隔与重复传参混用；以 / 结尾的条目按目录前缀匹配。默认覆盖旧声明，--append 为追加。不带 --files → 退出码 2。

audit

python scripts/huqiang.py audit [--root DIR]

对比当前目录与 latest 快照，把每个 新增/修改/删除 的文件分类为 in-scope / out-of-scope；对有内容副本的文本文件给出 added_lines / removed_lines 行数统计。有任何 out-of-scope 变化、或声明范围内文件被删除 → 退出码 1；干净 → 0。无快照或无 scope 声明 → 退出码 2（提示先运行 snapshot / declare）。

capture

python scripts/huqiang.py capture --name login --cmd "pytest tests/test_login.py -q" 
    [--layer direct|adjacent|random] [--timeout 120]

在 root 下用参数列表运行命令（不调用 shell，默认超时 120s），把 stdout+stderr 合并后规范化再存：ISO 时间戳、日期、时间、UUID、40/64 位 hex、root 绝对路径统一替换为占位符（<TS> <DATE> <TIME> <UUID> <HEX40> <HEX64> <ROOT>），避免假漂移。存 .huqiang/behavior/<name>.json。layer 默认 direct。

verify

python scripts/huqiang.py verify [--sample 5]

重放所有已捕获行为，同样规范化后对比基线（输出 + exit code）。分层执行：先全部 direct（必过）→ 再全部 adjacent → 最后从 random 层抽 --sample 条。某一层出现漂移即停止：报告漂移行为名 + unified diff（前 50 行）+ 退出码 1；全部一致 → 0。无行为基线 → 退出码 2。

checkpoint

python scripts/huqiang.py checkpoint --label "开工前好版本"

把 root 工作树（排除规则同 snapshot）打成 tar.gz 存 .huqiang/checkpoints/<id>/archive.tar.gz，并写 meta.json（id、label、UTC 时间、git HEAD）。id 格式 cp-<时间戳>-<label slug>。同时维护 checkpoints/index.json 时间线索引。

list

python scripts/huqiang.py list [--root DIR]

输出多版本时间线：合并 (a) 检查点索引，(b) git 仓库的 git log -n 50 历史提交（包含引入本 Skill 之前的提交）。按时间倒序，每条标注 type: checkpoint|git-commit、id、时间、说明。非 git 目录只列检查点。

restore

python scripts/huqiang.py restore <id> [--yes]

回滚到选定版本。id 可为检查点 id（支持从头开始的前缀）或 git 提交 hash（支持短 hash）。安全流程：先自动打一个 label 为 "pre-restore safety" 的检查点（回滚本身也可回滚），再恢复。

• 检查点 id → 解压归档覆盖 root，并删除归档清单之外的现有文件（快照恢复语义；.huqiang/.git/node_modules 等排除目录绝不动）。tar 解压有路径穿越防护：拒绝绝对路径与 .. 成员，链接一律不解压。
• git 提交 → 用 git archive <hash> | tar -x 覆盖式恢复，并在报告中明确警告：该提交之后新增的文件仍残留，如需完全干净请自行 git reset --hard <hash>（本工具不主动执行 reset –hard）。

不带 --yes 时交互确认；stdin 非 tty（Agent/CI 场景）则拒绝并退出码 2。id 不存在 → 退出码 2。

status

python scripts/huqiang.py status [--root DIR]

一行汇总：最近快照时间、scope 声明内容、行为基线条数、检查点数量、是否 git 仓库、当前是否有未审计的改动。对没有任何 .huqiang 状态的目录也正常报告，退出码 0。

self-test

python scripts/huqiang.py self-test

在临时目录造一个小项目走完整流程：snapshot → declare → capture → checkpoint → 制造 in-scope + out-of-scope 改动 → audit 必须检出越界 → verify 必须检出漂移 → restore 回滚 → 确认文件恢复且越界文件被删除 → 回滚后 audit/verify 干净 → 负向路径（无快照 audit、未知 id restore、无 –files declare 均为退出码 2）。12 步全部断言通过退出码 0，任一失败退出码 1 并打印失败点。

退出码

常见场景

Agent 改代码前怎么接入

在每次"修改文件"任务开工前固定执行四连：snapshot → declare（把任务涉及文件全部列上）→ capture（每条关键行为一条）→ checkpoint。把这一步当作任务的一部分，改完必须 audit + verify 全绿才算交付；中途发现要改声明外的文件，先 declare --append 再动手。

CI 里当门禁

python scripts/huqiang.py snapshot && python scripts/huqiang.py declare --files "$CHANGED_FILES" --intent "CI gate"
# ... Agent 或脚本执行修改 ...
python scripts/huqiang.py audit || exit 1   # 越界即红灯
python scripts/huqiang.py verify || exit 1  # 行为漂移即红灯

JSON 报告在 stdout，可直接 jq 取 .out_of_scope_paths、.drifts[].name 做进一步处理。

改坏了怎么挑版本回滚

python scripts/huqiang.py list            # 看时间线：Skill 检查点 + git 历史提交
python scripts/huqiang.py restore <id> --yes   # 任选一条回滚，回滚前自动打安全锚点

git 仓库里即使是引入本 Skill 之前的提交也能回滚；回滚不满意，再 restore 安全锚点（pre-restore safety）即可反悔。

边界声明（本 Skill 不做什么）

• 不自动生成测试用例：行为基线只来自用户显式 capture 声明的命令，护墙不会自己发明用例。
• 不做性能回归：只比对输出与退出码，不测量耗时、内存或吞吐。
• 不处理外部状态：数据库、远端服务、已部署环境、已发送的消息不在快照和回滚范围内。
• 不强制阻断 Agent：护墙只审计、告警、提供回滚；是否停下来修复靠工作流约定，不在工具层硬阻断。
• 不替代版本控制：不做分支管理、合并、协作同步；大项目应直接使用 git，checkpoint 只面向快速本地锚点。
• 不判断基线行为本身是否正确：capture 是特征化记录（当前行为是什么），不是正确性验证（行为应该是什么）。

失败与异常场景的处理

• 前置条件缺失（无快照跑 audit、无 scope 跑 audit、无行为基线跑 verify）：退出码 2，报告里给出该先运行哪条命令，不会假装通过。
• 行为命令自身失败：capture 时命令非零退出会连同 exit code 一起记入基线；verify 时只有 exit code 和输出都与基线一致才算通过——基线里的失败不会被当成新漂移，新失败也藏不住。
• 非确定性输出导致假漂移：先确认是否属于已规范化的模式（时间戳/UUID/hex/路径）；若是业务随机性，把命令输出洗一遍再 capture（如 | sort），或在报告中人工确认后重新 capture 覆盖基线。
• restore 过程中断：回滚前已自动打 pre-restore safety 检查点，中断后用 list 找到它再 restore 一次即可回到回滚前状态。
• 归档安全校验失败（路径穿越、绝对路径成员）：restore 拒绝执行并退出码 2，目标目录不被修改。
• git 恢复后有残留文件：git archive 覆盖式恢复不删除该提交之后新增的文件；报告会明确警告，是否进一步 git reset --hard 由用户决定，工具不主动执行。
• 大目录快照慢：snapshot 只算哈希、只为 ≤512KB 文本文件存内容副本；超大 monorepo 建议用 --root 圈定子目录，而不是全仓快照。

局限性（必读）

• 文件级审计抓不到声明范围内的语义漂移：声明了可以改 app.py，Agent 在里面把别的逻辑改坏了，audit 看不出来——要靠 verify 的行为基线兜底。
• 非确定性输出会假漂移：时间戳、随机数、UUID 已做规范化缓解，但业务里的随机顺序、浮点抖动等仍可能误报；capture 时应选择输出稳定的命令，或先把输出洗一遍再捕获。
• 行为基线覆盖率取决于声明多少：没 capture 的行为，verify 管不到。
• 回滚不覆盖外部状态：数据库、远端服务、已发送的消息不在回滚范围内。
• 不强制阻断 Agent：护墙只审计、告警、提供回滚，纪律靠工作流约定。
• 不替代版本控制：大项目建议直接用 git；checkpoint 面向无 git 或需要快速本地锚点的场景。

付费前置检查

调用本 Skill 前，先确认当前 Agent 已安装并可调用 weixinpay_pay：

• 已安装：继续请求相光域部署的 Pay Skill HTTPS 服务。
• 未安装：停止调用，并提示“当前 Agent 暂不支持微信支付付费能力，无法完成本次 Pay Skill 调用”。

本 Skill 是按次计费服务，平台价格为 2.99 元 / 次，product_id 为 SP260819ECD9。不得绕过支付直接交付付费结果。

工作流程

第一步：请求资源

向生产环境的 HTTPS 服务发起请求：

POST https://pay.tancoai.com/api/skillhub/pay/huqiang-payskill
Content-Type: application/json

请求体使用本 Skill 对应能力章节中定义的输入 JSON。上述是相光域正式 HTTPS 服务地址，不得替换为本地或临时隧道地址。

免费试用与扣次规则

前 5 次完整任务免费。免费次数按服务端完成回执扣减：只有服务端返回完整结果并生成完成回执时，才计入一次；输入校验失败、支付取消、网络中断或服务异常不扣免费次数。第 6 次起进入付费流程，按下方价格/次收费。

第二步：处理 402 支付响应

前 5 次命中免费额度时，服务端直接返回完整结果，不返回 402。第 6 次及以后触发付费时，首次付费请求不要携带 X-Out-Trade-No。服务端会创建微信支付订单，调用 SkillHub / 微信 Agent Pay X402 预下单，并返回：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>
Content-Type: application/json

响应体也会包含 WeixinPay 提示块。Agent 必须同时保存：

• WeixinPay-Required：作为 paymentCode 传给 weixinpay_pay。
• X-Out-Trade-No：支付成功后重试原请求时作为订单号凭证。

第三步：发起微信支付授权

调用 weixinpay_pay(paymentCode=<WeixinPay-Required>)，由用户在微信支付 AI 专属卡中确认并完成支付。支付未完成、取消或失败时，停止交付结果，只返回可读的失败说明。

第四步：支付成功后获取资源（必须执行）

支付成功后，Agent 必须用完全相同的请求体重试第一步，并携带订单号：

POST https://pay.tancoai.com/api/skillhub/pay/huqiang-payskill
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

服务端会按该订单号向微信支付查单；只有确认 trade_state=SUCCESS 后，才返回本 Skill 的付费结果。未确认支付时返回 PAYMENT_NOT_CONFIRMED，不得交付内容。

Pay Skill 服务接口

服务入口：https://pay.tancoai.com/api/skillhub/pay/huqiang-payskill Skill ID：huqiang-payskill Skill Version：1.0.9计费模式：前 5 次完整任务免费；第 6 次起按次调用，2.99 元 / 次平台 Product ID：SP260819ECD9 支付协议：微信 Agent Pay X402 支付触发 Header：WeixinPay-Required 订单重试 Header：X-Out-Trade-No

微信支付 API 证书、SkillHub 开发者私钥与商户配置只保存在相光域服务端，不进入 Skill ZIP、前端、日志或对话。

服务端验收

提交审核前至少跑通四个检查：

1. GET https://pay.tancoai.com/api/skillhub/pay/health 返回 status=ok。
2. 首次请求在无 X-Out-Trade-No 时返回 HTTP 402，且 Header 与 Body 都包含 WeixinPay-Required。
3. 用户支付后，携带同一个 X-Out-Trade-No 和原请求体重试，服务查单成功后返回 HTTP 200 与付费结果。
4. 私钥、微信支付证书、商户 Token 不进入 ZIP、前端、公开仓库或日志。
5. 异常处理：请求体不一致时服务返回 ORDER_REQUEST_MISMATCH；支付未确认时返回 PAYMENT_NOT_CONFIRMED。暂时失败时保留订单号并重试原请求，不得重复下单。