@bossmissing/agent-meta 0.1.0 → 0.3.0

package/README.md

@@ -24,13 +24,18 @@ pnpm test                 # Vitest
 
 | 命令 | 用途 |
 | --- | --- |
-| `meta init` | 初始化 Agent Meta 基础结构（`--yes` 非交互，`--type`，`--dry-run`） |
+| `meta init` | 初始化 Agent Meta 基础结构（`--yes` 非交互，`--type`，`--with-mcp <pack>`，`--with-deploy <target>`，`--dry-run`） |
 | `meta new-domain <name>` | 创建领域文档目录与局部 `AGENTS.md`（`--title` `--owner` `--with-state-machine` `--with-glossary` `--no-local-agents` `--force` `--dry-run`） |
 | `meta new-adr <slug>` | 自动编号创建 ADR（`--title` `--owner` `--status` `--path` `--dry-run`） |
 | `meta check` | 确定性元数据校验（`--strict` `--docs` `--adr` `--agents` `--openspec` `--json`） |
 | `meta audit` | 治理分析报告，不阻塞、不改文件（`--agents` `--docs` `--risk` `--json`） |
 | `meta sync` | 重建 `docs/domain` / `docs/adr` 索引，调用 `openspec update`（`--indexes` `--openspec` `--dry-run`） |
+| `meta new-change <name>` | 创建 OpenSpec 兼容变更目录（`--domain` `--schema` `--dry-run`），高风险领域自动附带 `risk-review.md` |
+| `meta doctor` | 检查运行环境：Node、包管理器、配置、路径、Git Hook、OpenSpec（`--json`） |
+| `meta review` | 定期仓库 review checklist：文档 / 代码 / 测试 / 安全，能机器判定的项实时给出 ✓/✗。文档按明确范围枚举（产品 / 架构 / 接口 / 领域 / ADR / 工程规范 / Runbooks / Agent 规则 / OpenSpec），附真实文件清单；`--pick-docs` 交互式让人类确认本轮整理哪些（`--json`） |
+| `meta preflight` | 上线前 checklist：自动跑 `meta check --strict`，人工项含"人类已 review 代码"；`--confirm` 逐项要求人类确认，未全部确认退出码 1（`--json`） |
 | `meta config list / set` | 查看与修改 `agent-meta.config.yaml` |
+| `meta config hooks lefthook` | 生成/合并 `lefthook.yml`，在 pre-commit 运行 `meta check`（`--dry-run`） |
 
 ## 退出码
 
@@ -60,6 +65,53 @@ meta new-adr withdrawal-idempotency \
 meta check --strict
 ```
 
+## 硬限制（Hard Constraints）
+
+硬限制是不可违反的约束（安全、数据一致性、API 契约、性能预算、兼容性、合规）；没有显式声明的限制，AI 会当成可协商的。声明位置只有两处：
+
+- 领域级：`docs/domain/<domain>/rules.md` 的 `## 硬限制（不可违反）` 章节
+- 项目级：`docs/engineering/constraints.md`
+
+工具链全生命周期支持：`meta init` 生成容器与 AGENTS.md 规则；`meta new-change --domain <d>` 把该领域已声明的硬限制原文打印进上下文；`meta check` 对高风险领域校验硬限制非空（`HIGH_RISK_DOMAIN_MISSING_HARD_CONSTRAINTS`，warning 级，`--strict` 下阻塞）；`meta review` 实测声明完整性并提醒排查漂移；`meta preflight` 上线前列出全部硬限制声明文件供人工核对。
+
+## MCP 工具包
+
+`meta init` 可选安装工具包（交互式多选，或 `--with-mcp <pack>[,<pack>]` 非交互指定）。安装内容全部是项目级的，与"默认不使用全局工具"的 AGENTS.md 规则配套：
+
+- `.mcp.json` — 项目级 MCP server 配置（合并写入，绝不覆盖已有条目）
+- `.claude/settings.json` — Claude Code 插件配置（marketplace + enabledPlugins，已有值绝不覆盖）
+- `.claude/skills/` — 配套 skills（已存在的文件跳过）
+- `AGENTS.md` — pack 附带的使用规则（仅注入新生成的 AGENTS.md）
+
+当前可用的 pack：
+
+| Pack | 安装内容 | 附带 |
+| --- | --- | --- |
+| `ironbank` | MCP：`https://test-ib-mcp.hillinsight.tech/mcp` | skills：ironbank-mcp-reference / ironbank-citations / ironbank-docs-research / ironbank-note-links；AGENTS.md 规则：文档与 bug 记录在 IronBank，遇到 `hillinsight://ib_note?...` 深链用 MCP 解析，引用笔记时输出同格式链接 |
+| `playwright` | MCP：`npx @playwright/mcp@latest`（[microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp)，浏览器自动化） | — |
+| `superpowers` | Claude Code 插件（[obra/superpowers](https://github.com/obra/superpowers)，planning/TDD/debugging skills） | AGENTS.md 规则：默认不使用 brainstorming，除非人类明确要求 |
+
+```bash
+meta init --yes --with-mcp ironbank,playwright,superpowers
+```
+
+安装后请提交 `.mcp.json`、`.claude/settings.json` 和 `.claude/skills/`，团队成员即可获得相同的工具配置。
+
+## 部署 skill
+
+`meta init` 时可选择部署方式（交互式单选，或 `--with-deploy <target>` 非交互指定），安装对应的部署 skill 到 `.claude/skills/`，并在新生成的 AGENTS.md 里注入部署规则：
+
+| Target | 部署方式 | Skill 要点 |
+| --- | --- | --- |
+| `cloudflare` | 本地 wrangler CLI 部署 Workers / Pages | 部署前跑 build+test；secrets 用 `wrangler secret put`；部署后 curl 验证 + `wrangler tail` 排错 |
+| `ansible` | Ansible playbook 部署云主机（ECS/EC2/VPS） | `deploy/ansible/` 目录约定；Windows 或无 ansible 时用 Docker 运行 ansible-playbook；先 `--check` 干跑再实跑 |
+| `github-actions` | GitHub Actions workflow CI/CD | build+test 通过才部署；`gh secret set` 管理 secrets；`gh run watch` 监控 |
+| `none` | 暂时不集成部署（默认） | — |
+
+```bash
+meta init --yes --with-deploy cloudflare
+```
+
 ## 模板覆盖
 
 在项目内创建 `templates/agent-meta/<name>.tmpl` 可覆盖内置模板（仅支持 `{{variable}}` 替换）：
@@ -81,7 +133,7 @@ templates/agent-meta/agents.md.tmpl
 - run: pnpm exec meta check --strict
 ```
 
-Git Hook（lefthook）：
+Git Hook（lefthook）— 由 `meta config hooks lefthook` 自动生成或合并：
 
 ```yaml
 pre-commit:
@@ -89,3 +141,10 @@ pre-commit:
     meta-check:
       run: pnpm exec meta check
 ```
+
+环境自检：
+
+```bash
+meta doctor          # Node / 包管理器 / 配置 / 路径 / Git Hook / OpenSpec
+meta doctor --json
+```

package/assets/skills/deploy-ansible/deploy-ansible/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: deploy-ansible
+description: |
+  使用 Ansible playbook 将项目部署到云主机（ECS / EC2 / VPS 等 Linux 服务器）。
+  Windows 上没有原生 Ansible，必须用 Docker 容器运行 ansible-playbook。
+  触发条件：用户要求"部署到服务器 / 云主机 / ECS / VPS"、"ansible 部署"、"上线到主机"，
+  或要求编写、修改部署 playbook / inventory。执行任何主机部署操作前必须先读取本 skill。
+---
+
+# Deploy to Cloud Hosts（Ansible）
+
+## 目录约定
+
+```text
+deploy/ansible/
+  inventory.ini        # 主机清单：IP / 域名、ansible_user
+  playbook.yml         # 部署 playbook
+  group_vars/all.yml   # 变量；敏感值用 ansible-vault 加密
+```
+
+首次部署且该目录不存在时，按此结构生成模板，并和用户确认：目标主机地址、
+SSH 用户、服务的运行方式（systemd 还是 docker compose）、部署目录。
+
+## 运行方式（按平台选择）
+
+- **macOS / Linux 且本地已装 ansible**：
+  `ansible-playbook -i deploy/ansible/inventory.ini deploy/ansible/playbook.yml`
+- **Windows，或本地没有 ansible**：用 Docker 运行（Windows 下这是唯一方式，
+  先用 `docker info` 确认 Docker 正在运行）：
+
+  POSIX shell：
+
+  ```bash
+  docker run --rm -it \
+    -v "$PWD:/work" -v "$HOME/.ssh:/root/.ssh:ro" -w /work \
+    willhallonline/ansible:2.16-alpine \
+    ansible-playbook -i deploy/ansible/inventory.ini deploy/ansible/playbook.yml
+  ```
+
+  PowerShell（Windows）：
+
+  ```powershell
+  docker run --rm -it `
+    -v "${PWD}:/work" -v "$env:USERPROFILE\.ssh:/root/.ssh:ro" -w /work `
+    willhallonline/ansible:2.16-alpine `
+    ansible-playbook -i deploy/ansible/inventory.ini deploy/ansible/playbook.yml
+  ```
+
+平台判定：shell 里看 `uname`（无 uname 即 Windows），Node 环境看 `process.platform === "win32"`。
+
+## 部署流程
+
+1. **连通性**：`ansible all -i deploy/ansible/inventory.ini -m ping`。
+2. **干跑**：`ansible-playbook --check --diff ...`——playbook 有改动时必做，
+   把 diff 摘要给用户看。
+3. **实跑**：干跑无误后执行真实部署。
+4. **验证**：curl 健康检查 URL，或 `ansible all -i ... -m shell -a "systemctl status <svc>"`。
+
+## Playbook 编写规则
+
+- 幂等优先：用 `copy` / `template` / `git` / `systemd` / `docker_compose_v2`
+  等模块，不用裸 `shell`/`command`（确需 shell 时加 `creates`/`changed_when`）。
+- 敏感值（数据库密码、token）用 `ansible-vault encrypt` 加密进 group_vars，
+  vault 密码不进仓库（用 `--ask-vault-pass` 或本地密码文件）。
+- 多主机滚动发布用 `serial`，避免全量同时重启。
+
+## 硬性规则
+
+- `--check` 干跑未通过（或未执行）时绝不实跑。
+- 对 production inventory 执行 playbook 前必须得到用户明确确认。
+- 绝不把 SSH 私钥、vault 密码或明文 secret 写入仓库；私钥只读挂载进容器。

package/assets/skills/deploy-cloudflare/deploy-cloudflare/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: deploy-cloudflare
+description: |
+  使用本地 wrangler CLI 将项目部署到 Cloudflare（Workers / Pages）。
+  触发条件：用户要求"部署"、"deploy"、"上线"、"发布到 Cloudflare"、"部署到 CF"、
+  "wrangler deploy"，或要求配置 Cloudflare 部署环境、管理 Workers secrets、
+  创建 D1/KV/R2 资源、查看部署日志。执行任何 Cloudflare 部署相关操作前必须先读取本 skill。
+---
+
+# Deploy to Cloudflare（wrangler CLI）
+
+所有部署都通过项目本地的 wrangler CLI 完成，不依赖 CI。
+
+## 前置检查（每次部署前依次执行）
+
+1. **wrangler 可用**：`wrangler --version` 或 `pnpm exec wrangler --version`。
+   不存在时优先项目级安装：`pnpm add -D wrangler`（按项目包管理器换成 npm/yarn）。
+2. **已登录**：`wrangler whoami`。未登录时不要代替用户登录——提示用户自己运行
+   `wrangler login`（浏览器 OAuth），或配置 `CLOUDFLARE_API_TOKEN` 环境变量。
+3. **配置存在**：项目根应有 `wrangler.toml` / `wrangler.jsonc`。缺失时先和用户确认
+   项目形态（Worker 还是 Pages、入口文件、兼容日期），再生成最小配置。
+4. **构建与测试通过**：先运行项目的 build 和 test 命令（见 AGENTS.md 项目命令），
+   任何一步失败立即中止部署。
+
+## 部署
+
+- Workers：`wrangler deploy`；先验证产物可用 `wrangler deploy --dry-run`。
+- Pages：`wrangler pages deploy <构建输出目录> --project-name <name>`。
+- 多环境：在 wrangler.toml 里定义 `[env.staging]` / `[env.production]`，
+  部署用 `wrangler deploy --env staging`。默认先部署 staging 再部署 production。
+
+## Secrets 与资源
+
+- Secret：`wrangler secret put <NAME>`（值由用户交互输入；绝不写入仓库文件、
+  命令行参数或 shell 历史）。多环境时加 `--env`。
+- 普通变量：写在 wrangler.toml 的 `[vars]`。
+- 资源绑定：先创建（`wrangler d1 create` / `wrangler kv namespace create` /
+  `wrangler r2 bucket create`），再把返回的 binding/id 写入 wrangler.toml。
+
+## 部署后验证（必做）
+
+1. 记录部署输出中的 URL 和 version id，反馈给用户。
+2. `curl -sf <部署 URL>` 或项目健康检查端点，确认返回 200。
+3. 行为异常时用 `wrangler tail` 看实时日志定位，再决定是否回滚
+   （`wrangler rollback` 或重新部署上一个可用版本）。
+
+## 硬性规则
+
+- 绝不在 build 或 test 未通过时部署。
+- 绝不把 API token / secret 写入仓库中的任何文件。
+- 部署 production 环境前必须得到用户明确确认。

package/assets/skills/deploy-github-actions/deploy-github-actions/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: deploy-github-actions
+description: |
+  使用 GitHub Actions workflow 部署项目（CI/CD 自动部署）。
+  触发条件：用户要求"用 GitHub Actions 部署"、"CI 自动部署"、"push 后自动上线"、
+  "配置 deploy workflow"，或要求排查部署 workflow 失败。
+  执行任何 GitHub Actions 部署相关操作前必须先读取本 skill。
+---
+
+# Deploy via GitHub Actions
+
+部署由仓库内的 workflow 完成；本地只负责编写 workflow、配置 secrets、触发和监控，
+统一使用 `gh` CLI。
+
+## 前置检查
+
+1. `gh auth status` 已登录；`git remote -v` 的 origin 指向 GitHub 仓库。
+2. workflow 文件：`.github/workflows/deploy.yml`。
+
+## Workflow 约定
+
+`deploy.yml` 不存在时生成模板，结构固定为两个 job：
+
+- 触发：`push` 到 main + `workflow_dispatch`（保留手动触发入口）。
+- `build` job：checkout → 安装依赖 → build → test。
+- `deploy` job：`needs: build`，部署步骤由目标平台决定（wrangler action、
+  scp/ssh、云厂商 action 等），生成前先和用户确认目标平台。
+- production 部署加 `environment: production`，便于用户在 GitHub 配置
+  环境保护规则（人工审批、分支限制）。
+
+## Secrets
+
+- 写入：`gh secret set <NAME>`（值走交互输入或 stdin 管道，不出现在命令行参数里）。
+- 使用：workflow 中引用 `${{ secrets.NAME }}`。
+- 列出核对：`gh secret list`。
+
+## 触发与监控
+
+- 手动触发：`gh workflow run deploy.yml`（分支参数 `--ref <branch>`）。
+- push 触发后查看：`gh run list --workflow=deploy.yml -L 3`。
+- 实时跟踪：`gh run watch <run-id>`；结束后向用户报告结论。
+- 失败排查：`gh run view <run-id> --log-failed`，定位失败 step 后修复再触发。
+
+## 硬性规则
+
+- deploy job 必须 `needs` 通过 build+test 的 job；测试不过不部署。
+- secrets 只存放在 GitHub Actions secrets（或环境 secrets），绝不写入
+  workflow 文件或仓库。
+- 修改 workflow 后先用 `workflow_dispatch` 在非 production 环境验证，
+  再合入 main 启用自动部署。

package/assets/skills/ironbank/ironbank-citations/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: ironbank-citations
+description: |
+  为 IronBank 搜索 / 检索结果提供类似 Claude Web Search 风格的内联引用注解。当用户询问任何与 IronBank 相关的问题时（包括公司内部文档、知识库、任务、笔记等），必须强制启用此 skill。触发条件：用户提问涉及 IronBank 内容（文档检索、笔记检索、任务查找等）、用户明确要求"引用来源"或"标注出处"、用户使用以下任一工具获取信息后进行问答：
+        - ironbank_search_all           （跨内容全文 / 关键词检索）
+        - ironbank_docs_search          （docs 文件向量检索）
+        - ironbank_docs_search_single   （单文档向量检索）
+        - ironbank_docs_get_chunk       （docs chunk 原文）
+        - ironbank_docs_get_summary     （docs 文档摘要）
+        - ironbank_notes_search         （notes / note_file 向量检索）
+        - ironbank_notes_search_single  （单 note 文档向量检索）
+        - ironbank_notes_get_chunk      （notes chunk 原文）
+        - ironbank_get_board_list
+        - ironbank_get_channels
+        - ironbank_get_channel_info
+        - ironbank_get_channel_activities
+        - ironbank_get_note_comments
+        - ironbank_get_note_detail      （含 Markdown 正文 + 附件/元数据）
+        - ironbank_get_notes
+        - ironbank_list_recent_notes    （跨任务 board 级笔记列表，可按 update_time 时间窗筛选）
+        - ironbank_get_recent_tasks
+        - ironbank_get_task_info
+        - ironbank_get_task_relations
+        - ironbank_get_tasks_by_board
+    只要回答内容来源于以上任一工具的结果，就必须使用本 skill 的引用格式。即使用户没有明确要求引用，只要数据来自 IronBank，也要自动附加引用。
+---
+
+# IronBank Citations Skill — Web Search 风格内联引用
+
+## 目标
+
+模仿 Claude Web Search 的 `` 内联引用体验，让 IronBank 搜索结果的每个关键信息点都有可点击、可追溯的来源标注。
+
+> **强制规则**：只要回答中的信息来源于 IronBank 搜索 / 检索类工具（含 `ironbank_search_all`、`ironbank_docs_*`、`ironbank_notes_*`、`ironbank_get_note_*` 等），就必须使用本 skill 的引用格式，无需用户额外请求。
+
+---
+
+## 核心工作流
+
+### Step 1：搜索 / 检索 IronBank
+
+根据用户问题，调用合适的工具：
+
+- **跨内容关键词搜索**：`ironbank_search_all` — 词法 / 全文检索任务、笔记、文件
+- **docs 网盘语义检索**：`ironbank_docs_search` → `ironbank_docs_search_single` → `ironbank_docs_get_chunk`（向量相似 / RAG）
+- **notes 笔记语义检索**：`ironbank_notes_search` → `ironbank_notes_search_single` → `ironbank_notes_get_chunk`（向量相似 / RAG，覆盖 note 与 note_file）
+- **笔记正文回读**：`ironbank_get_note_detail`（含 Markdown 正文）/ `ironbank_get_note_comments`
+- **笔记发现**：`ironbank_get_notes`（按频道）/ `ironbank_list_recent_notes`（按看板和时间窗）
+- **任务和频道上下文**：`ironbank_get_task_info` / `ironbank_get_task_relations` / `ironbank_get_recent_tasks` / `ironbank_get_channel_info` / `ironbank_get_channel_activities`
+
+搜索时注意：
+1. 使用精准的关键词，必要时多次搜索以覆盖不同角度
+2. 关键词检索（search_all）擅长找具体 ID / 名字；语义检索（docs/notes_search）擅长找概念 / 释义
+3. 记录每条结果的 **id / document_id / chunk_id**、**title** 和 **snippet / content_preview**
+4. 为每条结果分配一个引用索引号（从 1 开始）
+
+### Step 2：构建引用索引
+
+将搜索结果组织为引用源列表，格式：
+
+```
+SOURCE_1: { id: "doc_id_xxx", title: "文档标题", snippet: "搜索结果摘要..." }
+SOURCE_2: { id: "doc_id_yyy", title: "另一个文档", snippet: "相关内容..." }
+```
+
+### Step 3：撰写带引用的回答
+
+**引用格式规则（最关键）：**
+
+使用上标数字角标 `[¹]` `[²]` 等标记引用，在回答末尾附上引用来源列表。
+
+**上标字符对照表（必须严格使用以下字符，禁止使用 ④⑤⑥ 等圆圈数字）：**
+
+| 序号 | 正文角标 | 来源列表 |
+|------|---------|---------|
+| 1 | `[¹]` | `¹` |
+| 2 | `[²]` | `²` |
+| 3 | `[³]` | `³` |
+| 4 | `[⁴]` | `⁴` |
+| 5 | `[⁵]` | `⁵` |
+| 6 | `[⁶]` | `⁶` |
+| 7 | `[⁷]` | `⁷` |
+| 8 | `[⁸]` | `⁸` |
+
+**格式示例：**
+
+```
+根据内部文档，该项目的截止日期为3月15日[¹]，负责人为张三[²]。技术方案采用了微服务架构[¹]，预计需要4个开发人员参与[³]。
+
+---
+**来源**
+- ¹ **项目计划书.pdf** — "截止日期3月15日，微服务架构"
+- ² **团队分工表.xlsx** — "负责人：张三"
+- ³ **资源评估报告.md** — "预计4名开发人员"
+```
+
+### 引用粒度规则
+
+| 情况 | 引用方式 |
+|------|---------|
+| 单一来源的事实 | 句末标 `[¹]` |
+| 多个来源支撑同一论点 | 句末标 `[¹][³]` |
+| 综合推断 | 标注所有依据，注明"综合自..." |
+| 非 IronBank 来源 | 标注 `[通用知识]` 或说明来源 |
+| 搜索无结果 | 明确告知用户未找到相关文档 |
+
+---
+
+## 输出格式规范
+
+### 来源列表格式（强制）
+
+> **必须使用 Markdown 列表格式（每条前加 `- `）**，确保渲染时正确换行。
+> 每条摘要**控制在 20 字以内**。
+> 每次回答的引用来源**最多 8 条**，优先保留最相关的来源。
+> 来源是 IronBank **笔记**且 portal / task_id / note_id 已知时，标题写成深链形式（见 `ironbank-note-links` skill）：
+> `- ¹ [笔记标题](hillinsight://ib_note?portal=...&task=...&id=...&view=detail) — "摘要"`，让来源可点击打开。
+
+### 标准回答格式
+
+```markdown
+[回答正文，每个关键事实后附上标角标引用]
+
+---
+**来源**
+- ¹ **文档标题** — "摘要（≤20字）"
+- ² **文档标题** — "摘要（≤20字）"
+```
+
+### 简短回答（1-2个信息点）
+
+> 该功能的上线日期为2月28日[¹]。
+>
+> ---
+> **来源**
+> - ¹ **发布计划.pdf** — "v2.0 计划2月28日上线"
+
+### 复杂回答（多个信息点）
+
+> **背景**
+> 该项目于2024年Q3启动[¹]，目标是重构现有支付系统[²]。
+>
+> **进展**
+> 目前已完成第一阶段开发[³]，测试覆盖率达到85%[³]。第二阶段预计Q1完成[¹]。
+>
+> **风险**
+> 主要风险包括第三方API兼容性问题[⁴]和人员变动[²]。
+>
+> ---
+> **来源**
+> - ¹ **项目立项书.pdf** — "Q3立项，二阶段Q1完成"
+> - ² **团队周报-W48.md** — "支付重构，人员调整风险"
+> - ³ **测试报告-v1.pdf** — "一阶段完成，覆盖率85%"
+> - ⁴ **技术评审记录.md** — "第三方API兼容性风险"
+
+---
+
+## 特殊场景
+
+### 搜索无结果
+
+```
+我在 IronBank 文档中没有找到关于"XXX"的相关信息。
+
+建议：
+- 尝试使用不同的关键词搜索
+- 确认文档是否已上传到 IronBank
+- 我可以基于通用知识回答，但无法提供内部文档来源
+```
+
+### 结果之间有冲突
+
+```
+⚠️ 注意：关于此问题，不同文档存在差异：
+- **文档A**[¹]: "...表述1..."
+- **文档B**[²]: "...表述2..."
+
+建议以更新日期较近的文档为准。
+```
+
+### 混合来源（IronBank + 通用知识）
+
+IronBank 来源的信息使用角标引用，通用知识部分标注 `[通用知识]` 或不加引用但明确说明。
+
+---
+
+## 注意事项
+
+1. **不要伪造引用**：只引用实际搜索到的内容，找不到就说找不到
+2. **引用要精确**：角标对应的来源摘要必须是搜索结果中的真实内容
+3. **保持可读性**：引用是辅助信息，不能喧宾夺主，正文要流畅自然
+4. **优先 IronBank**：如果 IronBank 有相关内容，优先引用内部文档
+5. **保持原文语言**：引用摘要保持搜索结果的原始语言
+6. **角标连续编号**：每次回答中的角标从 ¹ 开始连续编号，不跳号
+7. **来源列表用 Markdown 列表**：每条来源前必须加 `- `，确保换行渲染正确
+8. **引用数量上限 8 条**：超过时合并或保留最相关的来源
+9. **摘要精简**：每条摘要控制在 20 字以内，不要冗长

package/assets/skills/ironbank/ironbank-docs-research/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: ironbank-docs-research
+description: 在 IronBank Docs（网盘 / 知识库文件）或 IronBank Notes（笔记 + 笔记附件）中做深度检索与证据收集时必须使用此 skill。触发场景包括：用户要求"去文档里找""搜一下 docs / notes""看看某份文档讲了什么""帮我搜笔记内容""确认文档 / 笔记里有没有某个细节""提取某个表格/段落/原文"。本 skill 覆盖两组并列工具——docs 四件套（全局搜索、文档摘要、单文档检索、chunk 精读）与 notes 三件套（全局搜索、单文档检索、chunk 精读，没有 summary），并给出它们之间的协作策略与选用规则。
+---
+
+# IronBank 深度检索 Skill（Docs + Notes）
+
+## 目标
+
+在 IronBank 的两类 RAG 索引中（**Docs** = 网盘里的文件；**Notes** = 笔记本体 + 笔记附件 note_file），从"找资源"一路推进到"拿到可引用的原文证据"，并根据用户问题决定先看摘要、还是直接下钻到 chunk。
+
+## 何时用 Docs，何时用 Notes
+
+- **Docs**（`ironbank_docs_*`）→ 用户问的是上传到 IronBank 网盘 / 知识库的文件内容（PDF、Word、Excel 等），或不区分来源时
+- **Notes**（`ironbank_notes_*`）→ 用户明确说"笔记""note""note_file"，或想搜某条笔记里的内容、笔记下挂的附件内容
+- 不确定时，可以**并行**调两条线的 search，再汇总比较哪一边命中更相关
+
+## 工具分工（Docs 四件套）
+
+- `ironbank_docs_search`
+  作用：全局搜索网盘文件，找到候选 `document_id`
+- `ironbank_docs_get_summary`
+  作用：对 1-3 个候选文档做快速预读，帮助判断哪篇最值得继续深挖
+- `ironbank_docs_search_single`
+  作用：在单篇文档内搜索相关 chunk，定位具体证据
+- `ironbank_docs_get_chunk`
+  作用：读取指定 chunk 的完整内容，并通过 `prev_no` / `next_no` 继续扩展上下文
+
+## 工具分工（Notes 三件套）
+
+- `ironbank_notes_search`
+  作用：跨用户全部 note + note_file 做向量检索，可选 `board_id` 限定范围；返回的每条命中带 `source_type`（note / note_file）、`note_id`、`document_id`
+- `ironbank_notes_search_single`
+  作用：在单个 note / note_file 内搜索相关 chunk，定位具体证据
+- `ironbank_notes_get_chunk`
+  作用：读取指定 note / note_file chunk 的完整内容，并通过 `prev_no` / `next_no` 扩展上下文
+
+
+## 推荐主流程
+
+### Flow A：默认流程
+
+适用场景：用户只给主题，还不知道具体是哪篇文档。
+
+1. 先用 `ironbank_docs_search` 做全局搜索，拿到候选文档
+2. 对最相关的 1-3 篇文档调用 `ironbank_docs_get_summary`
+3. 选定最值得继续读的文档后，用 `ironbank_docs_search_single` 找相关 chunk
+4. 对命中的锚点调用 `ironbank_docs_get_chunk` 读取完整内容和前后上下文
+5. 整理答案并标注来源
+
+### Flow B：快速概览流程
+
+适用场景：用户要“这篇文档主要讲什么”“先给我一个概要”。
+
+1. 如果用户已提供 `document_id`，直接调用 `ironbank_docs_get_summary`
+2. 如果用户只给主题，先 `ironbank_docs_search`，再对候选文档调用 `ironbank_docs_get_summary`
+3. 只有当用户继续追问细节、原文、表格、精确数字时，再进入 `search_single -> get_chunk`
+
+### Flow C：精确取证流程
+
+适用场景：用户要具体表述、表格、数字、条款、前后文、可引用原文。
+
+1. 已知文档时，直接从 `ironbank_docs_search_single` 开始
+2. 未知文档时，先 `ironbank_docs_search`，必要时跳过 `summary`
+3. 一旦定位到相关 chunk，立刻调用 `ironbank_docs_get_chunk`
+4. 需要上下文时，基于 `prev_no` / `next_no` 继续读取邻近 chunk
+
+## 何时使用 `ironbank_docs_get_summary`
+
+优先使用 `summary` 的情况：
+
+- `ironbank_docs_search` 返回多个候选文档，单靠 snippet 很难判断哪篇更相关
+- 用户要的是“概览”“摘要”“这篇文档大概讲什么”
+- 需要先快速筛掉不相关文档，再决定是否投入 chunk 级检索
+
+跳过 `summary` 的情况：
+
+- 用户明确要求精确原文、表格、数字、条款或上下文
+- 已经知道目标文档，而且问题是文档内某个具体细节
+- 需要可验证证据，而不是高层概述
+
+工作规则：
+
+- `summary` 是“文档级预读工具”，通常放在 `docs_search` 和 `docs_search_single` 之间
+- `summary` 不能替代 chunk 原文；它只负责帮助筛选和建立理解
+- 最终回答若需要证据或引用，必须回到 `search_single` / `get_chunk`
+
+## 检索与下钻策略
+
+### Step 1：全局搜索
+
+使用 `ironbank_docs_search` 找候选文档。
+
+要点：
+
+- 关键词尽量短而准，优先 2-5 个词
+- 第一次无结果时，换同义词、缩短关键词、拆成两个问题重搜
+- 记录最相关的 `document_id`
+
+### Step 2：摘要筛选
+
+使用 `ironbank_docs_get_summary` 对 1-3 个候选文档做预读。
+
+要点：
+
+- 用 summary 判断“是不是这篇”“值不值得继续读”
+- 如果多个 summary 都相关，再分别进入单文档检索
+- 如果 summary 很泛或不足以支持结论，不要停在这里，继续下钻
+
+### Step 3：单文档内定位
+
+使用 `ironbank_docs_search_single` 在目标文档中找相关 chunk。
+
+要点：
+
+- 这里可以用更具体的二级关键词
+- 选最相关的 1-3 个命中作为锚点
+- 记录结果中的 `chunk_id`
+- snippet 只能用于定位，不能默认当作完整证据
+
+### Step 4：读取完整 chunk 与邻近上下文
+
+使用 `ironbank_docs_get_chunk` 读取锚点 chunk 的完整内容。
+
+正确方式：
+
+1. 先用 `chunk_id` 读取锚点 chunk
+2. 查看返回结果中的 `prev_no` 和 `next_no`
+3. 如需上下文，再用 `chunk_no = prev_no` 或 `chunk_no = next_no` 继续读取邻近 chunk
+
+重要规则：
+
+- 不要假设 `chunk_id` 是顺序编号
+- 不要对 `chunk_id` 做 `+1` / `-1`
+- 邻近扩展要依赖 `prev_no` / `next_no`
+
+停止扩展的条件：
+
+- 已经拿到完整答案
+- 前后文开始明显偏题
+- 已经覆盖完整表格、完整条款、完整定义或完整论述
+
+## 结构化数据与截断处理
+
+对表格、列表、财务数据、长段落要更谨慎：
+
+- 只看到表格前半段时，不要急着回答
+- 列表逻辑上应有更多项时，不要默认结果完整
+- 缺少合计行、结论行、尾部注释时，要继续读取相邻 chunk
+
+建议做法：
+
+1. 用 `ironbank_docs_search_single` 找到锚点
+2. 立刻用 `ironbank_docs_get_chunk` 读取完整 chunk
+3. 如果结果仍像是中途截断，继续用 `prev_no` / `next_no` 扩展
+
+## 回答策略
+
+回答时优先做到三件事：
+
+1. 先直接回答用户问题
+2. 再给出支撑该结论的文档证据
+3. 如果信息仍不完整，明确说明还缺什么
+
+建议的引用方式：
+
+- 来源：[文档标题]（document_id: xxx）
+- 来源：[文档标题] - chunk_id: xxx
+- 若上下文是通过 `chunk_no` 扩展得到，也可补充 `chunk_no`
+
+## 常见决策规则
+
+- 搜索结果很多且 snippet 脏乱：先用 `ironbank_docs_get_summary`
+- 搜索结果已经明显指向唯一文档，但用户要细节：跳过 summary，直接 `search_single`
+- 用户要摘要：优先 `get_summary`
+- 用户要原文、数字、表格、条款：优先 `search_single -> get_chunk`
+- 一个文档不够回答：对多个文档并行执行“summary 或 single search”流程，再汇总
+
+## 不要这样做
+
+- 不要把 `summary` 当成最终证据
+- 不要只看全局搜索 snippet 就下结论
+- 不要假设 `chunk_id` 是 `c12`、`c13` 这种连续编号
+- 不要通过手动增减 `chunk_id` 去读相邻内容
+- 不要在需要原文证据时停留在文档摘要层
+
+## Notes 链路的特别说明
+
+Notes 系（`ironbank_notes_*`）整体策略与 Docs 完全一致，但有几个差异要注意：
+
+1. **没有 summary 工具**：上面所有"先看 summary，再决定是否下钻"的步骤，对 notes 链路要直接跳过。判断要不要继续读，只能基于 `ironbank_notes_search` 返回的 `snippet` / `content_preview` / `similarity`
+2. **结果含两类来源**：每条命中通过 `source_type` 区分
+   - `source_type = "note"` → 命中的是某条笔记本身
+   - `source_type = "note_file"` → 命中的是笔记下挂的附件文件
+   - 两类都用同样的 `document_id` 进入 `ironbank_notes_search_single` / `ironbank_notes_get_chunk`，不需要分流处理
+3. **board_id 限定（可选）**：`ironbank_notes_search` 支持 `board_id` 入参，可把语义检索范围限定在某个看板下的笔记 — 适合"在 XX 项目的笔记里找"这种场景
+4. **chunk 扩展规则一样**：从 `ironbank_notes_get_chunk` 拿到 `prev_no` / `next_no` 后，照样用 `chunk_no` 继续读邻近内容；不要对 `chunk_id` 做 `+1` / `-1`
+5. **拿到 note 后想要正文**：如果用户后续问"这条笔记完整说了什么"，可以转去 `ironbank_get_note_detail`（来自 `ironbank-mcp-reference` skill）拿整篇 Markdown 正文（在 `content.content` 字段），不必继续在 chunk 层拼接
+
+何时优先 Notes vs Docs：
+
+- 用户明确说"笔记""note"：优先 Notes
+- 找用户自己写过的内容、讨论、会议记录、个人收藏：优先 Notes
+- 找上传到知识库的正式文档、PDF、Excel：优先 Docs
+- 都不确定：并行调两边的 search，看哪边 `similarity` 更高