# Aiweave Bridge

> |-

- **Type:** Skill
- **Install:** `agentstack add skill-xurb-nexus-nexus-harness-aiweave-bridge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xurb-nexus](https://agentstack.voostack.com/s/xurb-nexus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** https://github.com/xurb-nexus/nexus-harness/tree/main/skills/aiweave-bridge
- **Website:** https://xurb-nexus.github.io/nexus-harness/

## Install

```sh
agentstack add skill-xurb-nexus-nexus-harness-aiweave-bridge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 严格约束）
```

### rebuild_task_docs.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/`）
  5. 写盘后过 `lint_aiweave_invariants.py` + vendor `/doc-sync-check`，blocking 不通过返工
  6. 重跑 `record_docs_read.py record` 反向 grep 登记 evidence；token 不在新 docs 里立刻拒收
  7. vendor 字段在代码里找不到对应实现 → 登记 `vendor_template_mismatch` 到任务 notes，docs 顶部插 ``

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

## 调用约定

下游 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 输出契约

```json
{
  "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 字段（演进）

```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](https://github.com/xurb-nexus)
- **Source:** [xurb-nexus/nexus-harness](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xurb-nexus-nexus-harness-aiweave-bridge
- Seller: https://agentstack.voostack.com/s/xurb-nexus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.