项目决策看板

人决定目标、范围、重要取舍和验收；Agent 在授权内组织任务、实施、测试、维护记录。单 Agent 可以兼任角色，但自验不冒充独立审核。大小项目使用同一流程，按实际工作量增减明细，不按功能点数量分两套制度。

1. 三层入口

manager/SKILL.md 是本规则副本；manager/references/ 是本规则引用的按需协议。仅在规则未加载或版本改变时读规则，不每次重读全部资料。manager/board.html 是 index.json 的派生快照，绝不是第二份状态源。

2. 初始化和目录

使用技能包内 tools/pmboard.py init <项目根> --name <项目名>。只在用户授权建立管理时执行，不自动恢复旧任务。已有 manager/ 则停止，按 接入与隐私 渐进迁移，禁止覆盖。

<项目根>/
├── AGENTS.md                 # 未跟踪时才创建或维护入口块
├── README.md                 # 面向使用者的介绍、部署、启动、使用信息
└── manager/                  # 全部本地，不进 Git
    ├── SKILL.md              # 规则副本
    ├── references/           # 按需规则附件，不是项目手册
    ├── tools/pmboard.py      # 本地生成与校验工具，换 Agent 仍可用
    ├── templates/            # 离线 HTML 与按需明细模板，不默认读取
    ├── index.json            # Agent / HTML 共用的唯一项目索引
    ├── board.html            # 离线生成的用户概览
    ├── agents.md             # 唯一项目执行约定
    ├── privacy.json          # 占位符映射，禁止常规读取或导出
    ├── experience.json       # 结构化经验库，按场景检索
    ├── stages/               # 阶段目标与完成标记的补充依据
    ├── features/             # 按功能拆分需求、设计、代码入口、测试引用
    ├── tests/                # 测试明细与结果证据
    ├── issues/               # bug / change / risk 明细
    ├── decisions/            # 人类决定与依据
    ├── checkpoints/          # Agent 交接记录及可恢复变更引用
    └── history/              # 已结束索引与记录，按需建立

除核心文件外按需创建，禁止批量造空手册。README 不复制 agents.md。UI 风格、输出格式、Node/JDK 版本、仓库使用要求和提交授权属于 agents.md；仅使用者需要的信息才进入 README。私有地址和凭据不进入 README。

3. Git 与入口边界

• Git 项目使用 .git/info/exclude（通过 Git 查询真实位置，兼容 worktree）本地排除 /manager/；根 AGENTS.md 未跟踪时也排除。无 Git 时记录待配置，不宣称受到 Git 保护。
• 已跟踪 AGENTS.md 不追加、不取消跟踪、不使用 assume-unchanged/skip-worktree 隐藏差异；报告需宿主本地配置或用户显式读取 manager/SKILL.md。
• 若 manager/ 已有被跟踪文件，停止初始化并提示处理历史；忽略规则不会撤销跟踪或泄漏。
• manager/ 不随 Git 流转。换机器/换用户需授权的安全迁移包或共享存储；不共享原始 privacy.json。新接收者必须重新核对本机路径、代码和权限。
• 开发提交以功能单元组织，代码测试可按项目策略进 Git；管理、测试记录中的隐私不可夹带提交。dev/uat/prod 是环境标签，不强制建同名分支。

4. 统一索引契约

字段和示例见 数据协议。用工具 validate 检查，不给 JSON 加 Markdown 注释。

index.json 只放短简介、阶段管理标记、活跃功能状态摘要、阻塞/待决策摘要和明细路径。禁止存实现代码、测试步骤、长日志、完整设计、隐私映射或全部聊天。经验正文在 experience.json；索引只记录其路径。

不设硬性行数上限，但 JSON 不天然更省 token，也不是无限上下文。工具在索引超过 32 KiB 或活跃功能超过 50 项时提示整理，不截断、不丢风险；结束事项移入 history，保留导航。

两种状态，分别展示

• 阶段状态：index.json 中 stages[].status 是管理标记；阶段目标/验收依据在 detail_ref 指向的文件，明细不另维护一份竞争状态。
• 功能实现状态：基于当前代码核验，记录 implementation、verification、checked_at、code_fingerprint 和 evidence_ref。文档写完成不是实现证据；代码本身也不证明用户目标已满足。
• 工具计算当前代码指纹，仅帮助发现核验过期，不会自动判断实现正确。指纹不匹配时看板降为“待重新核验”，保留阶段标记，不假装实时知道代码变化。
• board.html 显示生成时间和索引摘要；打开旧 HTML 不会自动读取磁盘。代码/索引改变后需重新 render。未经核验不能显示绿色“已完成”。

5. 工作循环

1. 定位：读入口、索引和约定；核对项目根、Git/快照、文件差异、暂停状态和直接依赖。
2. 规划：明确目标、不做、功能 ID、负责人、范围、依赖和验收。结构/范围重大变化形成待决策；普通授权任务直接推进。
3. 实施：一次推进可验证的功能单元；共享文件先协调，有版本校验时使用。保留他人工作，不擅自 reset/clean/stash。
4. 验证：先复现再修复；编译、单元、集成、人工验收分开记录。保留证据、对应代码指纹和未覆盖项；不改断言掩盖失败。
5. 交接：明细保留变更、原因、测试、未知副作用和下一步；更新索引及必要经验，再运行 validate 和 render。
6. 提交/发布：agents.md 若明确授权测试后及时提交，可只提交本任务相关文件；没有授权不擅自提交。推送、发布、数据迁移权限分别核对。

蓝图（目的/受众/预期）、设计（模块/关联/功能）、开发、质量、交付、维护作为默认六个管理视角，不强制严格串行。bug 与新功能分别建 issue，可回到已有阶段，不每次聊天创建新阶段。图像/OCR 辅助只能生成待核对输入，不能替代需求确认或测试证据。

6. 人类看板与决策

看板只展示简介、管理进度、活跃功能的核验概况、待决策/阻塞，以及可复制/打开的路径。不要把任何 detail_ref 正文读进 HTML。

用户从现有问题的候选选项中选择并导出 JSON 决策单。该文件是待接收的提案，不直接修改项目，不自动形成授权。Agent：

1. 用 review-decision 核对项目 ID、索引 SHA-256、问题 ID 和选项。
2. 与当前用户确认这确为其选择，检查是否冲突或过期；有新状态时重新展示，不能静默套旧决定。
3. 将决定、确认依据、影响及来源 request_id 存到 decisions/，按责任范围更新索引；同一 request_id 只接收一次。
4. 再推进实施，不因下载了 JSON 就认为代码、部署或阶段已完成。

浏览器不能保证打开本机路径：路径按钮尝试 file://，失败时提示复制并在资源管理器打开。不使用 HTTP 服务、外链或执行命令来绕过浏览器限制。隐私映射永远不进入看板；根路径可能含个人目录名，所以看板本身也只限本地，不直接分享或提交。

看板所有路径统一显示为「BASE + 相对路径」且 BASE 自动识别：优先按 board.html 自身位置推导（所在 manager/ 的上一级，即本机真实项目根——每人/每台机器各自正确，数据无需改动）；可用 URL 参数 ?base= 显式覆盖（看板移到别处或要指向另一项目根时）；以上不可用时回退 index.json 的 project.root（生成时记录，仅作兜底）。相对路径在任何机器上保持有效。多项目/多人协作：一个项目根一套 manager/ 与看板，各自 BASE 自动识别，互不干扰。

7. 经验、隐私与多 Agent

• privacy.json 默认空映射；个人数据可在授权下做占位符映射，凭据优先保存 env/keychain 引用，不要求把密钥复制到明文文件。占位符出现不代表必须解引用。
• AI 按需读取个人隐私仍可能将其送入模型服务；本地文件、Git 忽略和“禁止外泄”提示不构成技术隔离。处理凭据应交给授权运行环境，不能回显或打进包。
• experience.json 每条记录场景、观察、证据、有限结论、适用范围、状态及替代关系。重复合并，失效标记；一次严重事故也可记录，假设不写成根因。
• 多 Agent 各自维护功能/测试/检查点明细，指定一名索引维护者发布 index.json 和 board.html。索引 revision 与旧文件哈希用于冲突检查，不是排他锁。独立工作树也不隔离数据库和外部账户。
• 中断后先核对代码、检查点和外部副作用再恢复；状态未知时不要自动重放。管理文件因本地排除可能丢失，关键检查点应按授权进行本地备份。

8. 完成检查

• 当前索引是否只有概览和路径，所有被引用明细存在且不指向隐私文件？
• 阶段管理标记与功能代码核验是否分开，证据是否对应当前代码？
• 人的待决策是否清楚，是否保留了暂停、风险和未知？
• agents.md 是否仍为唯一执行约定，README 是否只含使用信息？
• manager/ 与本地入口是否未被 Git 跟踪，快照是否只留在本地？
• validate 是否通过、board.html 是否重新生成、路径失败是否有明确退路？

9. AI 付（按量付费）能力

tools/aipay/ 是可选模块：将本项目管理下可数字化的服务封装为按次收费 API，接入支付宝
AI 按量付费（A2M 402 协议）。接入遵循支付宝 AI 付 Skill（alipay-aipay）的既定流程，
本规则只维护模块在本包内的使用约束：

• 沙箱配置：项目根 .alipay-sandbox.json，不随 Skill 包分发（打包发布时手工排除该类本地敏感文件）；服务启动时读取，
  配置缺失或字段不完整必须显式失败，禁止占位值、示例密钥或回退生产网关。
• 沙箱联调：serviceId 固定 api_mock_service_id，沙箱网关 openapi-sandbox.dl.alipaydev.com；
  a2m-sandbox-test 通过标志沙箱联调通过，不等于生产就绪。
• 生产红线：正式上线前替换真实 serviceId，生产 appId/应用公钥/应用私钥/支付宝公钥必须属
  同一套生产应用；私钥格式与语言匹配（Python 等非 Java 用 PKCS#1 原始值，不做格式转换）。
• 用户授权：涉及支付宝沙箱资料、生产密钥、签约与开通时，按宿主授权边界收集和使用；不把
  私钥、密码、Payment-Proof 回显进看板、索引、README 或提交。

10. 付费改造特征（SkillHub 支付宝付费验收）

本 Skill 的付费能力遵循「支付宝付费改造最佳实践」，以下特征在本包中均有实现，可在
tools/aipay/ 中核实：

付费命令（probe / pay / complete / ack）

tools/aipay/pay_cli.py 暴露四个子命令，覆盖付费闭环（技能根目录执行）：

python tools/aipay/pay_cli.py probe    <资源URL> [--out 账单.json]      # 402 账单下发（Payment-Needed）
python tools/aipay/pay_cli.py pay      --bill 账单.json --buyer-id <2088> [--out 凭证.json]  # 完成支付换凭证
python tools/aipay/pay_cli.py complete <资源URL> --proof 凭证.json       # 携凭证重试：验付→履约→返回资源
python tools/aipay/pay_cli.py ack      --out-trade-no <订单号>          # 幂等确认履约状态

• probe：请求受保护资源，触发 402 与 Payment-Needed，本地脱敏保存账单。
• pay：对账单完成支付，取得 trade_no 与凭证素材。
• complete：携带 Payment-Proof 重试服务；服务端执行 payment.verify 验付、
  fulfillment.confirm 履约，返回 resource_id/content 与 Payment-Validation。
• ack：查询本地订单履约状态；PENDING_CONFIRM 视为可安全重试，FULFILLED 视为幂等完成。

支付环节依赖支付宝支付处理能力：先安装 npx -y @alipay/alipay-aipay@latest install
获取官方 AI 付 Skill，支付凭证生成与真实支付统一交由其封装脚本完成（沙箱收银端点
aicashier.dl.alipaydev.com/openclawpay/agent/v1/pay 已内置）。