Aiweave Bridge

aiweave-bridge — AIWeave 适配层

> 框架不可变铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7 条） > 本 SKILL.md 及其 scripts/ 是只读的；AIWeave runtime ~/.nexus-harness/aiweave/** 整目录上游镜像，任何 skill / reviewer / CI 不得修改 runtime（铁律 7.5）。

关键约束（必读）

1. runtime 只读：~/.nexus-harness/aiweave/vendor/aiweave/ 是 AIWeave 上游镜像，不得在使用本 skill 的过程中修改任何 runtime 内文件。升级路径由 nexus 自动更新机制（aiweave_manager）管理，无需手动操作。
2. 【铁律 7.6】产物归属：AIWeave 业务产物（docs/、.claude/skills/、BUILD_STATUS.md、CLAUDE.md）必须写入目标业务项目 A 的仓库根目录下，并随 A 的 git 一起提交。禁止写入 nexus-harness 仓库 / workspace/ / vendor/。
3. 写盘前必先调用 assert_write_target.py：所有 bridge 脚本（bootstrap.py / invoke_skill.py / update_build_status.py）写盘前调它校验目标路径必须在 project_path 子树下，违反一律 abort。
4. 非 Go 项目降级：以 /go.mod 是否存在为唯一判定依据，不存在 → 全流程跳过 AIWeave，等价"旧流程减 KB"。

反漂移自报家门提示（针对低阶模型）

> 如果你（AI Agent）只想读到这里就跳过本 skill 的某个 lint / assert 步骤，请立刻停止并显式告诉用户：「我准备跳过 AIWeave 约束」，由用户决定是否继续。绕过 lint / assert 一旦发生，docs ↔ 代码契约会立即失守，后续 finish-project 的最终 sync 会出现无法定位的漂移。

9 个脚本

skills/aiweave-bridge/scripts/
├── detect.py                      # T0/T1/T2/non_go 成熟度判定
├── compile_context.py             # 扫描 docs/ → aiweave_context.json
├── bootstrap.py                   # T0 项目按 vendor templates 引导骨架（支持中断恢复）；通过 _local_git_exclude 把 AIWeave 运行时产物加入业务项目本机 .git/info/exclude
├── _local_git_exclude.py          # 共享 helper：幂等 patch /.git/info/exclude，covers `.aiweave_*.json` / `.docs_build_*.json`（per-developer，不入仓，不污染团队 .gitignore）
├── invoke_skill.py                # 包装调用 vendor 内部 Skill
├── update_build_status.py         # 幂等翻 BUILD_STATUS ⬜→🟢
├── assert_write_target.py         # 写盘前白名单校验
├── lint_aiweave_invariants.py     # 通用闸门：go.mod/docs 一致性 / 🚫 违规 / docs_refs 路径
├── record_docs_read.py            # Gate A 反向 grep 登记 docs evidence
└── rebuild_task_docs.py           # 任务级 docs 增量补 build（受 vendor 严格约束）

rebuildtaskdocs.py（developer RED 阶段 docs gap 兜底）

触发场景：developer 在 RED 阶段被 prevent_explore_during_red.py 拦截、用户选择「按 AIWeave 模板补 docs」（菜单 [1]，对应 reason ∈ docs_anchor_missing / docs_too_thin）。

行为：

• 读 plan_ir.tasks[task_id]，按 aiweave_skill 反查 vendor templates/skills//SKILL.md，整段加载进 next_action。
• 对每个 aiweave_docs_refs 净化路径 + anchor，按 abs_path 不存在 / anchor 缺失 / byte_size /docs/）

1. 写盘后过 lint_aiweave_invariants.py + vendor /doc-sync-check，blocking 不通过返工
2. 重跑 record_docs_read.py record 反向 grep 登记 evidence；token 不在新 docs 里立刻拒收
3. vendor 字段在代码里找不到对应实现 → 登记 vendor_template_mismatch 到任务 notes，docs 顶部插 ``

铁律：

• vendor SKILL.md 是唯一规范源；任何偏离视为反 AIWeave 作弊，reviewer 登记 blocking。
• 本脚本不调 LLM、不写 docs 内容；只准备指令包。docs 内容由主 AI 在原会话执行。
• 三道闸门 + token 反向 grep：assertwritetarget → lintaiweaveinvariants → /doc-sync-check → recorddocsread，五道防线锁死随意发挥。

调用约定

下游 skill 调用本桥接脚本时，遵循以下约定：

• 只读 vendor：bootstrap.py / invoke_skill.py 内部以 vendor/aiweave/templates/... 为模板，写盘目标恒为 project_path。
• 写盘 = 业务项目：所有写盘动作传 (target_path, project_path) 给 assert_write_target.py，校验 target_path 是 project_path 子树。
• lint 默认开：每个 stage 在调用 vendor Skill 前后跑 lint_aiweave_invariants.py，blocking 失败一律不前进。
• 降级：detect.py 返回 non_go 或 skipped 时，下游 skill 一律按"旧流程减 KB"走，不再调任何 bridge 脚本。

detect.py 输出契约

{
  "project_path": "/abs/path/to/A",
  "is_go": true,
  "maturity": "T0|T1|T2|non_go",
  "missing_specs": ["docs/INDEX.md", "docs/BUILD_STATUS.md", ...],
  "aiweave_root": "/abs/path/to/~/.nexus-harness/aiweave/vendor/aiweave",
  "project_docs_path": "/abs/path/to/A/docs",
  "go_mod_exists": true,
  "reason": "go.mod 存在，docs/ 完整，可直接进入选项式追问"
}

成熟度定义：

• T0：go.mod 存在，但 docs/ 完全缺失或缺 INDEX.md / BUILD_STATUS.md → 触发 bootstrap.py
• T1：go.mod + docs/INDEX.md + docs/BUILD_STATUS.md 都在，但 19 类篇章有缺失 → 列 missing_specs，让用户选「补齐」/「带缺口前进」
• T2：go.mod + 完整 19 类基础 docs/ + BUILD_STATUS 已有内容 → 直接 compile_context.py（v1.2 新增 5 类约束 docs 按工程复杂度可选启用，不计入 T2 必备）
• non_go：go.mod 不存在 → 全流程跳过 AIWeave

context.json 字段（演进）

{
  "project": "...",
  "project_path": "/abs/A",
  "aiweave_root": "/abs/~/.nexus-harness/aiweave/vendor/aiweave",
  "aiweave_status": "T0|T1|T2|non_go|skipped",
  "docs_index_path": "/abs/A/docs/INDEX.md",
  "aiweave_context_path": "/abs/workspace//aiweave_context.json"
}

旧字段 knowledge_base_dirs / kb_paths 保留但下游不再读取（向后兼容旧 archive）。

与下游 skill 的对接清单

| 下游 skill | 调本 bridge 时机 | 关键脚本 | |---|---|---| | prd-to-trd | 入口探测 + 选项题生成 | detect.py → compile_context.py → (T0 时) bootstrap.py | | plan-from-trd | preflight 对账 | compile_context.py 复用上次结果 | | developer | 任务入场 / 收尾 | update_build_status.py（任务收尾翻 ⬜→🟢） | | finish-project | 最终 sync | invoke_skill.py(sync-feature-to-docs) → invoke_skill.py(doc-sync-check) | | diagnose | L3 装载 | compile_context.py（只读 docs/INDEX.md） | | discover_workspace_stage | 阶段识别 | detect.py（轻量，仅判定 aiweave_status） |

自检 Checklist

• [ ] vendor 目录未被本会话修改
• [ ] 所有写盘目标都通过 assert_write_target.py 校验
• [ ] lint_aiweave_invariants.py 无 blocking 才进入下一 stage
• [ ] 非 Go 项目早降级，不调用任何 bridge 写盘脚本

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xurb-nexus
• Source: xurb-nexus/nexus-harness
• License: Apache-2.0
• Homepage: https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.