From 7c4f5b4bb04f940bd6688729de0bd0781c30fd4d Mon Sep 17 00:00:00 2001
From: Research Assistant <research@example.com>
Date: Tue, 19 May 2026 15:47:53 +0800
Subject: [PATCH] docs: update AGENTS.md with skill graph structure, intent
 routing, bump/release, and skill deploy

---
 AGENTS.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b08be227..75511fd3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,26 @@
 | Vector DB | ChromaDB，由 `embed build` 管理 | 不与 memory DB 合并语义 |
 | Skill/workflow | 路由 → 执行 CLI → 解释结果 | 不绕过 CLI 直操作文件 |
 
+**Skill Graph 分层（`paperforge/skills/paperforge/`）：**
+
+| 层 | 位置 | 职责 |
+|----|------|------|
+| Compound | `SKILL.md` | bootstrap → capability check → intent routing → dispatch to molecule |
+| Molecules | `molecules/*.md` | 1 intent = 1 molecule，完整的用户意图执行流程 |
+| Atoms | `atoms/*.md` | 可复用的检索/持久化/澄清子步骤 |
+
+**Intent Routing 判定顺序（在 SKILL.md 中编码）：**
+```text
+0. 机械命令 → 直接执行
+1. 研究别名 → /pf-deep→deep_analyze, /pf-paper→read_known
+2. capture_project_knowledge — 用户要保存/归档
+3. read_known_paper — 用户给定了明确 paper
+4. discover_papers — 用户要论文列表
+5. find_supporting_evidence — 用户要具体证据/参数
+6. 无法判定 / 多 intent 冲突 → clarify-user-intent
+7. Post-action: 其他 molecule 输出后用户要保存 → capture
+```
+
 **运行时快照契约：**
 
 ```
@@ -44,13 +64,14 @@ JS 读（同步，不推断）:
 
 - 搜索用 `$PYTHON -m paperforge search`，不用 `grep`/`glob` 扫库。
 - 路径从 bootstrap 或 paper-context 获取，禁止自行拼接。
-- 未完成 paper-context 检查前不读原文（deep-reading、paper-qa）。
+- 未完成 paper-context 检查前不读原文（适用于 read-known-paper、deep-analyze-paper）。
 - Reading-log 不是事实源，只能用做复查定位。
 - 未知或拼错的 `/pf-*` 必须提示用户，禁止静默掉进 `project-engineering`。
+- **每个 molecule 开头有 Pre-flight Checklist，必须逐项打勾再执行，不跳步。**
 
 ---
 
-## 4. 机械 vs 思考路由
+## 4. 路由
 
 | Route | 类型 | 动作 |
 |-------|------|------|
@@ -62,7 +83,45 @@ JS 读（同步，不推断）:
 
 ---
 
-## 5. 测试
+## 5. 版本发布流程
+
+发布新版前确认测试通过，然后 bump 版本：
+
+```bash
+# Bump patch (1.5.x → 1.5.x+1)
+python scripts/bump.py patch
+
+# Bump minor (1.x.0 → 1.x+1.0)
+python scripts/bump.py minor
+
+# Bump to specific version
+python scripts/bump.py 1.6.0
+
+# 预览（不实际修改）
+python scripts/bump.py patch --dry-run
+```
+
+bump.py 会自动：更新 `__init__.py` / `manifest.json` → commit → tag。
+完成后需推送：
+
+```bash
+git push && git push --tags
+```
+
+GitHub Actions（release.yml / publish.yml）会自动在 tag push 后创建 Release 并构建插件。
+
+---
+
+## 6. Skill 部署
+
+Skill 文件在 `paperforge/skills/paperforge/` 中。部署到 vault 由 `paperforge/services/skill_deploy.py` 处理：
+- **setup wizard**：首次安装时部署
+- **`paperforge update`**：更新时覆盖部署（`overwrite=True`）
+- 手动部署到 vault 的 `.opencode/skills/paperforge/`：直接 copy 整个目录
+
+---
+
+## 7. 测试
 
 ```bash
 # Python
@@ -73,6 +132,9 @@ cd paperforge/plugin && npx vitest run
 
 # Lint
 ruff check --fix paperforge/ && ruff format paperforge/
+
+# Skill Graph contract tests
+python -m pytest tests/test_skill_graph_contracts.py tests/test_skill_graph_layout.py tests/test_pf_bootstrap_capabilities.py -v --tb=short
 ```
 
 ---
@@ -88,3 +150,4 @@ ruff check --fix paperforge/ && ruff format paperforge/
 | 架构 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
 | 维护者 | [docs/maintainer-guide.md](docs/maintainer-guide.md) |
 | 迁移历史 | [docs/MIGRATION-v1.2.md](docs/MIGRATION-v1.2.md) |
+| Skill Graph Spec (设计文档) | [docs/superpowers/specs/2026-05-19-paperforge-skill-graph-design.md](docs/superpowers/specs/2026-05-19-paperforge-skill-graph-design.md) |