Skip to content

AGENTS.md

Latest commit

 

History

History
158 lines (131 loc) · 7.2 KB

AGENTS.md

File metadata and controls

158 lines (131 loc) · 7.2 KB
Raw

AGENTS.md

Scope

  • 本仓是 AI协作交付系统（PathRelay）的装载器分发仓。
  • 仓标识：PathRelay。
  • 本仓负责维护装载器、当前装载包、历史包、schema、验证脚本、smoke 夹具和公开方法论文档。
  • 本仓不是任何业务项目、规格方案或外部协作文档的第二正本。
  • examples/ 当前为空；不要为了演示重建。
  • 目标项目装载后的正本在目标 repo 内，不回流覆盖本仓。
  • 方法论正文放在 docs/，入口文件只放长期规则。
  • 做事先读事实文件，再改代码或文档。

Source-of-Truth

  • 发布正本：docs/。
  • 仓根 README.md 是产品与命令入口说明。
  • schemas/package-manifest.schema.json 是 package manifest 结构约束。
  • schemas/installed-manifest.schema.json 是目标项目 .harness/manifest.json 结构约束。
  • 当前可安装包：loader-package/packages/current/。
  • 历史归档包：loader-package/packages/archive/v1/、loader-package/packages/archive/v2/。
  • 旧格式测试夹具：tests/fixtures/legacy-package/。
  • 负例夹具：tests/fixtures/negative/，保持故意坏状态。
  • 根入口不复制 docs 正文，只链接。
  • package 内 files/ 改动必须同步对应 package-manifest.json hash。

Required-Reading

  • 先读 README.md。
  • 再读 docs/README.md。
  • 改装载逻辑前读 loader-package/tools/harness_loader.py。
  • 改 manifest 前读 schemas/package-manifest.schema.json。
  • 改目标安装态前读 schemas/installed-manifest.schema.json。
  • 改验证前读 scripts/verify.sh 和 tests/run_smoke.sh。
  • 改 package 内入口前读 loader-package/packages/current/files/AI_AGENT_GUIDE.md。
  • 改包内容前对照 loader-package/packages/current/package-manifest.json。
  • 需要历史兼容时读 tests/fixtures/legacy-package/package-manifest.json。
  • 不确定 loader 是品牌还是技术词时，先按技术词保留，再在报告里列出。

Operating-Loop

  • install：对目标项目做 pre-install scan，写入 managed files，已有业务文件不覆盖。
  • sync：按 manifest 升级 managed files；用户改过的文件进入 conflict queue。
  • update：先跑 compat gate，再复用 sync。
  • resolve：按显式策略解决冲突，并更新目标 manifest hash。
  • uninstall：只删除 manifest 管理的文件，保留业务文件和需归档证据。
  • verify：检查 package 结构、hash、源码编译与 smoke lifecycle。
  • 每次改动先判断影响面：root docs、loader 工具、package files、schema、tests。
  • 改 root docs 不需要同步 package hash。
  • 改任一 package files/ 内容必须重算该 package manifest 对应 sha256。
  • 不修正 tests/fixtures/negative/。
  • tests/fixtures/legacy-package/ 保持旧格式，只同步自己的 hash。
  • archive/v1、archive/v2 保持各自 version 标识不变。
  • 交付前先自查实际文件内容，再跑最小验证。

L0-L3

  • L0：项目级结构、schema、manifest、安装态、回滚、安全边界；必须谨慎，必要时请人拍板。
  • L1：跨文件流程、装载生命周期、验证脚本、包兼容；需要完整验收。
  • L2：单文件或局部文档/脚本调整；需要相关 grep 或脚本验证。
  • L3：解释、索引、注释、小文案；仍要确认不破坏正本边界。
  • L0/L1 不凭记忆总结，必须读文件。
  • L2/L3 不扩大重构范围。
  • 无法判断等级时按更高等级处理。

G0-G3

  • G0：spec/source-of-truth 存在；没有正本就先补正本或报告缺口。
  • G1：验证入口跑过；能跑 scripts/verify.sh 就跑。
  • G2：契约不破坏；manifest/schema/compat/hash/负例夹具状态保持一致。
  • G3：风险已记录；不能验证的项必须写清原因和剩余风险。
  • 改 package files 后，G2 必须包含 hash mismatch=0。
  • 改 docs 后，G3 必须检查无 wikilink、无 frontmatter 残留、无敏感项目指代。
  • 改命名后，G2 必须检查产品名不再带旧后缀。
  • 改 smoke 或 verify 后，G1 必须跑相关脚本。
  • 若脚本因外部约束不能跑，不得包装成通过。

DoneWhen

  • 需求对应文件已实际落盘。
  • 读过关键 diff 或关键片段。
  • 产品名使用：中文「AI协作交付系统」，英文「PathRelay」，仓标识 PathRelay。
  • 技术 loader 词只在装载器、命令、变量、路径、兼容字段等语义中保留。
  • docs 发布内容可公开，无项目特定指代。
  • docs/methodology-src/ 不作为发布物保留。
  • package hash 已同步。
  • scripts/verify.sh 通过，或明确说明不能运行原因。
  • tests/run_smoke.sh 通过，或明确说明不能运行原因。
  • 报告包含改动、验证、grep、hash 和风险。

Commands

bash scripts/verify.sh
bash tests/run_smoke.sh

HARNESS_LOADER_BOUNDARY=/path/to/sandbox \
python3 loader-package/tools/harness_loader.py install \
  --target /path/to/sandbox/existing-project \
  --package loader-package/packages/current

HARNESS_LOADER_BOUNDARY=/path/to/sandbox \
python3 loader-package/tools/harness_loader.py sync \
  --target /path/to/sandbox/existing-project \
  --package loader-package/packages/current

HARNESS_LOADER_BOUNDARY=/path/to/sandbox \
python3 loader-package/tools/harness_loader.py update \
  --target /path/to/sandbox/existing-project \
  --package loader-package/packages/current

HARNESS_LOADER_BOUNDARY=/path/to/sandbox \
python3 loader-package/tools/harness_loader.py resolve \
  --target /path/to/sandbox/existing-project \
  --strategy incoming \
  --path PROJECT_STATE.md

HARNESS_LOADER_BOUNDARY=/path/to/sandbox \
python3 loader-package/tools/harness_loader.py uninstall \
  --target /path/to/sandbox/existing-project

Contracts

  • package-manifest.json 必须包含 version 和 files。
  • current manifest 必须有 manifest_version: 1、package: "PathRelay"。
  • current version 现在是 0.1.0。
  • current compat 必须包含 breaking、migration_required、min_loader。
  • current compat 当前值：breaking=false、migration_required=false、min_loader="0.1.0"。
  • files[].path 不允许绝对路径或 ..。
  • files[].sha256 必须匹配 files/ 下真实内容。
  • files[].preserve_on_uninstall 必须明确。
  • current files[].role 必须是 schema 允许值。
  • installed manifest schema 支持 installed-manifest-v1 和旧 real-loader-v1。

Records

  • 本仓验证摘要：records/verification/smoke-latest.json。
  • 目标项目装载后记录：records/latest.md。
  • 目标项目 MR 记录：records/mr/。
  • 目标项目回滚记录：records/rollback/rollback-plan.md。
  • 目标项目复盘：archive/retro.md。
  • 证据目录约定：evidence/runs/。
  • 卸载时需要保留的证据由装载器归档。

More-Docs

  • 方法论索引：docs/README.md
  • 正本边界：docs/source-of-truth.md
  • 入口上下文：docs/entry-context.md
  • 工作循环：docs/operating-loop.md
  • 执行掌控分级：docs/execution-control.md
  • 门禁分级：docs/gate-policy.md
  • 完成判定：docs/donewhen.md
  • 契约与兼容：docs/contracts.md
  • 留痕与证据：docs/records.md
  • 装载与发布：docs/loader-and-release.md
  • 验证与 smoke：docs/verification-and-smoke.md