@bossmissing/agent-meta 0.2.0 → 0.4.0

package/README.md

@@ -24,7 +24,7 @@ pnpm test                 # Vitest
 
 | 命令 | 用途 |
 | --- | --- |
-| `meta init` | 初始化 Agent Meta 基础结构（`--yes` 非交互，`--type`，`--with-mcp <pack>`，`--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`） |
@@ -87,8 +87,9 @@ meta check --strict
 
 | Pack | 安装内容 | 附带 |
 | --- | --- | --- |
-| `ironbank` | MCP：`https://test-ib-mcp.hillinsight.tech/mcp` | skills：ironbank-mcp-reference / ironbank-citations / ironbank-docs-research |
+| `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)，浏览器自动化） | — |
+| `dev-env` | skills：dev-env（本地环境约定：项目进程本机启动，redis/mysql/mq 等中间件用 docker compose 启动，compose 只声明中间件） | AGENTS.md 规则：中间件依赖走 Docker，绝不本机全局安装 |
 | `superpowers` | Claude Code 插件（[obra/superpowers](https://github.com/obra/superpowers)，planning/TDD/debugging skills） | AGENTS.md 规则：默认不使用 brainstorming，除非人类明确要求 |
 
 ```bash
@@ -97,6 +98,21 @@ 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}}` 替换）：

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/dev-env/dev-env/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: dev-env
+description: |
+  本地开发 / 测试环境启动约定：项目进程直接本机启动，依赖的中间件
+  （Redis / MySQL / PostgreSQL / Kafka / RabbitMQ 等）通过 Docker 启动。
+  触发条件：用户要求"起本地环境"、"启动开发环境"、"跑集成测试"、
+  "起 redis / mysql / mq"，或应用报中间件连接失败（Connection refused /
+  ECONNREFUSED）需要排查本地依赖时。执行本地环境相关操作前必须先读取本 skill。
+---
+
+# Local Dev Environment（进程本机跑，中间件 Docker 跑）
+
+## 原则
+
+- 项目进程**永远直接在本机启动**（`pnpm dev` 等，见 AGENTS.md 项目命令）：
+  热重载、debugger、IDE 集成都保持可用。
+- 中间件依赖一律用 docker compose 启动，**不在本机全局安装**
+  （不 `brew install mysql`、不 `apt install redis`）。
+- compose 文件只声明中间件，**绝不包含应用本身**。
+
+## 文件约定
+
+- 项目根的 `docker-compose.dev.yml`：每个中间件一个 service，数据挂 named
+  volume，端口映射到 localhost。
+- 项目具体依赖哪些中间件、端口、应用启动命令：以 AGENTS.md 项目命令段和
+  `docs/engineering/testing.md` 为准，本 skill 只定义通用流程。
+- 文件不存在时：先从 AGENTS.md / README / `.env.example` / 配置文件识别项目
+  依赖哪些中间件，生成 compose 模板，并和用户确认版本与端口后再落盘。
+
+## 启动流程
+
+1. `docker info` 确认 Docker 正在运行。
+2. `docker compose -f docker-compose.dev.yml up -d`
+3. 等依赖就绪再起应用：`docker compose ps` 看 `healthy`；没有 healthcheck 的
+   service 用端口探测（`nc -z localhost <port>`）。MySQL/PostgreSQL 首次启动
+   有初始化耗时，连接被拒时先等再重试，不要急着改配置。
+4. 本机启动应用（AGENTS.md 项目命令）。
+5. 跑测试。
+
+## 日常操作
+
+- 状态：`docker compose -f docker-compose.dev.yml ps`
+- 单个中间件日志：`docker compose -f docker-compose.dev.yml logs -f redis`
+- 停止：`docker compose -f docker-compose.dev.yml down`（保留数据卷）
+- 重置数据：`down -v`（会删数据，执行前必须用户确认）
+- 端口冲突：`lsof -i :<port>` 找到占用方，和用户确认后再调整端口映射。
+
+## 硬性规则
+
+- 绝不在本机全局安装中间件；缺什么就加进 compose。
+- `down -v` 或删除数据卷前必须得到用户确认。
+- compose 里的账号密码只用于本地开发，绝不复用任何真实环境的凭据。

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

@@ -113,6 +113,8 @@ SOURCE_2: { id: "doc_id_yyy", title: "另一个文档", snippet: "相关内容..
 > **必须使用 Markdown 列表格式（每条前加 `- `）**，确保渲染时正确换行。
 > 每条摘要**控制在 20 字以内**。
 > 每次回答的引用来源**最多 8 条**，优先保留最相关的来源。
+> 来源是 IronBank **笔记**且 portal / task_id / note_id 已知时，标题写成深链形式（见 `ironbank-note-links` skill）：
+> `- ¹ [笔记标题](hillinsight://ib_note?portal=...&task=...&id=...&view=detail) — "摘要"`，让来源可点击打开。
 
 ### 标准回答格式
 

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

@@ -1,5 +1,5 @@
 ---
-name: ironbank-docs-search
+name: ironbank-docs-research
 description: 在 IronBank Docs（网盘 / 知识库文件）或 IronBank Notes（笔记 + 笔记附件）中做深度检索与证据收集时必须使用此 skill。触发场景包括：用户要求"去文档里找""搜一下 docs / notes""看看某份文档讲了什么""帮我搜笔记内容""确认文档 / 笔记里有没有某个细节""提取某个表格/段落/原文"。本 skill 覆盖两组并列工具——docs 四件套（全局搜索、文档摘要、单文档检索、chunk 精读）与 notes 三件套（全局搜索、单文档检索、chunk 精读，没有 summary），并给出它们之间的协作策略与选用规则。
 ---
 

package/assets/skills/ironbank/ironbank-mcp-reference/SKILL.md

@@ -9,6 +9,7 @@ description: IronBank MCP 强制参考指南。只要请求涉及 IronBank，或
 
 - 只要将要调用任意 `ironbank_*` 工具，必须先使用本 skill，不允许跳过。
 - 只要用户提到 IronBank / ironbank mcp，或提到看板（board）、任务（task）、最近任务（recent task）、任务关系（relation/mention）、频道（channel）、动态（activity）、笔记（note）、评论（comment）、附件（attachment）、`portal`、`fileId` 中任一关键词，默认触发本 skill。
+- 上下文中出现 `hillinsight://ib_note?...` 深链时，先加载 `ironbank-note-links` skill 解析出 `portal` / `task_id` / `note_id`，再按本 skill 的参数约定调用工具（链接已带齐三个 ID，可直接调 `ironbank_get_note_detail`，无需逐级定位）。
 - 下载附件时，必须先调用 `ironbank_get_file_download_info` 获取 `download_url`、`file_key`、`digest`、`size`，再调用 `decrypt-attachment` skill 解密。
 - 如果不确定是否属于 IronBank 场景，按“属于”处理，先触发本 skill。
 

package/assets/skills/ironbank/ironbank-note-links/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: ironbank-note-links
+description: |
+  解析与生成 IronBank 笔记深链（`hillinsight://ib_note?...`）。本项目的文档和 bug 都记录在 IronBank 中，仓库内文档（docs/、ADR、openspec、issue、commit message）以及与 LLM 的对话里，统一用这种链接引用 IronBank 笔记。触发条件（任一命中即必须使用本 skill）：
+    - 上下文中出现 `hillinsight://` 开头的链接（用户消息、文件内容、搜索结果中均算）
+    - 用户要求"打开/看看/读一下这个链接"且链接是 hillinsight 深链
+    - 需要在项目文档或回答中引用某条 IronBank 笔记（生成链接）
+    - 用户提到"把这个 bug/文档记到 IronBank 并留个链接"
+  解析链接需要 IronBank MCP（ironbank_* 工具），调用前先加载 ironbank-mcp-reference skill。
+---
+
+# IronBank 笔记深链（hillinsight://）解析与生成
+
+## 背景
+
+本项目的项目文档和 bug 记录都放在 IronBank。仓库内引用这些内容时，不复制正文，而是留一条深链：
+
+```
+hillinsight://ib_note?portal=<portal>&task=<task_id>&id=<note_id>&view=detail
+```
+
+示例：
+
+```
+hillinsight://ib_note?portal=v9owxx8o&task=83a5a825-d9a7-4114-ad63-08c26fb1a3b8&id=5a14a6da-210a-4d1c-8033-785d93412b47&view=detail
+```
+
+人类在 HLink / hillinsight 客户端里点击即可打开；Agent 遇到时必须通过 IronBank MCP 把正文读出来，**不允许**因为链接协议陌生而跳过、也不允许猜测其内容。
+
+## 链接结构 → MCP 参数映射
+
+| Query 参数 | 含义 | 对应 MCP 参数 |
+|---|---|---|
+| `portal` | 工作空间（多租户） | `portal` |
+| `task` | 笔记所属任务 ID | `task_id` |
+| `id` | 笔记 ID | `note_id` |
+| `view` | 客户端视图（通常 `detail`） | 无需传给 MCP，忽略 |
+
+三个 ID 一条链接全带齐了，**不需要**再走 board → task → channel 的逐级定位流程。
+
+## 流程一：解析（读）一条链接
+
+```
+Step 1  从链接中提取 portal / task / id 三个参数
+Step 2  ironbank_get_note_detail → note_id=id, task_id=task, portal=portal
+        （返回 Markdown 正文 + 附件 + 元数据）
+Step 3  如需讨论上下文：ironbank_get_note_comments → note_id, portal
+Step 4  如正文含 `fileId:` 附件链接且用户需要附件内容：
+        ironbank_get_file_download_info → 再交给 decrypt-attachment skill 解密
+```
+
+注意：
+
+- 一次出现多条链接时，可**并行**调用 `ironbank_get_note_detail`
+- 返回 `coverage: "partial"` 时要说明部分内容因权限被隐藏，不能当完整事实
+- 403 / 404 时如实告知链接不可访问或已删除，不要编造内容
+
+## 流程二：生成（写）一条链接
+
+当需要在项目文档、ADR、openspec change、bug 记录或回答中引用某条 IronBank 笔记时：
+
+```
+Step 1  确认该笔记的 portal、task_id、note_id
+        （来自 ironbank_get_notes / ironbank_list_recent_notes / ironbank_get_note_detail
+          / ironbank_create_note 的返回，或用户提供）
+Step 2  按固定格式拼接：
+        hillinsight://ib_note?portal=<portal>&task=<task_id>&id=<note_id>&view=detail
+Step 3  在 Markdown 中带上笔记标题作为可读文本：
+        [笔记标题](hillinsight://ib_note?portal=...&task=...&id=...&view=detail)
+```
+
+规则：
+
+- **只对真实存在的笔记生成链接**——三个 ID 必须来自工具返回或用户输入，禁止拼造
+- 参数顺序固定为 `portal` → `task` → `id` → `view`，`view` 固定填 `detail`
+- 在 docs/、ADR、openspec 里引用 IronBank 内容时，优先留链接而不是复制大段正文；需要摘录时附上链接作为出处
+- 用 `ironbank_create_note` 新建了 bug / 文档笔记后，把生成的链接回填到相关文档或回复里
+
+## 与其他 skill 的配合
+
+- 调用任何 `ironbank_*` 工具前，先加载 **ironbank-mcp-reference**（工具参数与层级模型）
+- 基于链接解析出的内容作答时，按 **ironbank-citations** 的角标格式标注来源；来源为笔记时，来源列表中的标题直接使用上面的深链 Markdown 链接
+- 需要在笔记正文里做语义定位时，转 **ironbank-docs-research** 的 notes 链路（`ironbank_notes_search_single` 等）
+
+## MCP 不可用时
+
+如果 `ironbank_*` 工具不存在或未连接，不要假装解析：明确告知用户 IronBank MCP 未安装 / 未连接（处理方式见 ironbank-mcp-reference 的「MCP 连接检查」），并原样保留链接。

package/dist/cli.js

@@ -51,6 +51,7 @@ program
     .option("-y, --yes", "non-interactive mode, accept all defaults")
     .option("--type <type>", "project type: node | monorepo | nextjs | cocos | backend | other")
     .option("--with-mcp <pack>", "install an MCP pack (.mcp.json + .claude/skills/), e.g. ironbank")
+    .option("--with-deploy <target>", "install a deploy skill: cloudflare | ansible | github-actions | none")
     .option("--dry-run", "show what would be created without writing files")
     .action(async (opts) => {
     try {
@@ -222,7 +223,7 @@ configCmd
 configCmd
     .command("set")
     .description("Set a configuration value, e.g. meta config set defaults.agents_max_lines 220")
-    .argument("<key>", "dot-separated key, e.g. defaults.review_interval_days")
+    .argument("<key>", "dot-separated key, e.g. validation.stale_review_days.active")
     .argument("<value>", "value")
     .action((key, value) => {
     try {

package/dist/commands/init.d.ts

@@ -3,6 +3,8 @@ export interface InitOptions {
     type?: string;
     /** Comma-separated MCP pack names to install, e.g. "ironbank,playwright". */
     withMcp?: string;
+    /** Deployment integration: cloudflare | ansible | github-actions | none. */
+    withDeploy?: string;
     dryRun?: boolean;
 }
 export declare function detectProjectType(root: string): string;

package/dist/commands/init.js

@@ -11,6 +11,7 @@ import { CONFIG_FILENAME, configExists } from "../core/config.js";
 import { padAdrNumber } from "../generators/adr-generator.js";
 import { installMcpPack } from "../generators/mcp-generator.js";
 import { getMcpPack, packServerSummary, MCP_PACKS } from "../core/mcp-packs.js";
+import { getDeployPack, DEPLOY_PACKS } from "../core/deploy-packs.js";
 import { EXIT_CODES, MetaError } from "../core/errors.js";
 const PROJECT_TYPES = ["node", "monorepo", "nextjs", "cocos", "backend", "other"];
 export function detectProjectType(root) {
@@ -89,7 +90,24 @@ export async function runInit(root, opts) {
         });
         mcpPacks = picks.map(getMcpPack);
     }
-    const packRules = mcpPacks.flatMap((p) => p.agentRules ?? []);
+    // Deployment integration: installs a deploy skill into .claude/skills/.
+    let deployTarget = opts.withDeploy?.trim();
+    if (deployTarget && deployTarget !== "none") {
+        getDeployPack(deployTarget); // fail fast on unknown targets, before any write
+    }
+    if (!deployTarget && !opts.yes) {
+        deployTarget = await select({
+            message: "部署方式（安装对应的部署 skill，可稍后再加）：",
+            choices: [
+                ...Object.entries(DEPLOY_PACKS).map(([value, p]) => ({ name: p.title, value })),
+                { name: "暂时不集成部署", value: "none" },
+            ],
+            default: "none",
+        });
+    }
+    const deployPack = deployTarget && deployTarget !== "none" ? getDeployPack(deployTarget) : null;
+    const allPacks = deployPack ? [...mcpPacks, deployPack] : mcpPacks;
+    const packRules = allPacks.flatMap((p) => p.agentRules ?? []);
     // Existing AGENTS.md handling.
     const agentsRel = DEFAULT_CONFIG.paths.root_agents;
     let agentsAction = writer.exists(agentsRel) ? "keep" : "create";
@@ -155,8 +173,8 @@ export async function runInit(root, opts) {
     // 4. First ADR
     const adrNumber = padAdrNumber(1, DEFAULT_CONFIG.defaults.adr_padding);
     writer.write(`docs/adr/${adrNumber}-repository-conventions.md`, renderNamedTemplate("adr-0001.md", root, templatesDir, { adr_number: adrNumber, owner, date }));
-    // 5. Optional MCP packs
-    for (const pack of mcpPacks)
+    // 5. Optional MCP packs and deploy skill
+    for (const pack of allPacks)
         installMcpPack(writer, root, pack);
     // Report
     if (dryRun) {
@@ -193,14 +211,14 @@ export async function runInit(root, opts) {
     if (fs.existsSync(path.join(root, DEFAULT_CONFIG.paths.openspec))) {
         logger.ok(`OpenSpec detected at ${DEFAULT_CONFIG.paths.openspec}/`);
     }
-    for (const pack of mcpPacks) {
+    for (const pack of allPacks) {
         logger.ok(`Pack '${pack.name}' installed: ${packServerSummary(pack)}`);
     }
-    if (mcpPacks.length > 0) {
+    if (allPacks.length > 0) {
         const artifacts = [
-            mcpPacks.some((p) => p.server) ? ".mcp.json" : "",
-            mcpPacks.some((p) => p.settings) ? ".claude/settings.json" : "",
-            mcpPacks.some((p) => p.hasSkills) ? ".claude/skills/" : "",
+            allPacks.some((p) => p.server) ? ".mcp.json" : "",
+            allPacks.some((p) => p.settings) ? ".claude/settings.json" : "",
+            allPacks.some((p) => p.hasSkills) ? ".claude/skills/" : "",
         ].filter(Boolean);
         logger.info(`  Commit ${artifacts.join(", ")} so the whole team gets the same tools.`);
     }

package/dist/commands/new-adr.js

@@ -46,7 +46,8 @@ export function runNewAdr(root, name, opts) {
         throw new MetaError(e.message, EXIT_CODES.CHECK_FAILED);
     }
     if (config.features.generate_indexes && !opts.dryRun) {
-        updateAdrIndex(writer, root, config);
+        // Keep the index next to the ADRs, including when --path overrides the directory.
+        updateAdrIndex(writer, root, config, relDir);
     }
     if (opts.dryRun) {
         logger.info("Would create:");

package/dist/commands/sync.js

@@ -5,6 +5,7 @@ import { FileWriter } from "../core/filesystem.js";
 import { logger } from "../core/logger.js";
 import { loadConfig } from "../core/config.js";
 import { updateAdrIndex, updateDomainIndex } from "../generators/index-generator.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
 export function runSync(root, opts) {
     const { config } = loadConfig(root);
     const all = !opts.indexes && !opts.openspec && !opts.templates;
@@ -35,8 +36,16 @@ export function runSync(root, opts) {
                 execSync("openspec update", { cwd: root, stdio: "inherit" });
                 logger.ok("OpenSpec updated");
             }
-            catch {
-                logger.warn("Could not run `openspec update` (is the OpenSpec CLI installed?). Skipped.");
+            catch (e) {
+                const err = e;
+                // ENOENT / exit 127: the binary is missing. Anything else is a real
+                // failure of an installed CLI and must fail the sync.
+                if (err.code === "ENOENT" || err.status === 127) {
+                    logger.warn("Could not run `openspec update` (is the OpenSpec CLI installed?). Skipped.");
+                }
+                else {
+                    throw new MetaError(`\`openspec update\` failed${typeof err.status === "number" ? ` with exit code ${err.status}` : ""}. Fix the OpenSpec errors above and re-run \`meta sync\`.`, EXIT_CODES.CHECK_FAILED);
+                }
             }
         }
     }

package/dist/core/deploy-packs.d.ts

@@ -0,0 +1,11 @@
+import type { McpPack } from "./mcp-packs.js";
+/**
+ * Deployment packs are skills-only packs (no MCP server, no plugin settings):
+ * installing one copies a deploy skill into `.claude/skills/` and appends its
+ * working rules to a freshly generated AGENTS.md. They reuse the McpPack
+ * shape so `installMcpPack` / `listPackSkillFiles` work unchanged.
+ */
+export declare const DEPLOY_PACKS: Record<string, McpPack>;
+/** Valid values for `--with-deploy`; 'none' means skip deployment integration. */
+export declare const DEPLOY_TARGETS: string[];
+export declare function getDeployPack(target: string): McpPack;

package/dist/core/deploy-packs.js

@@ -0,0 +1,42 @@
+import { EXIT_CODES, MetaError } from "./errors.js";
+/**
+ * Deployment packs are skills-only packs (no MCP server, no plugin settings):
+ * installing one copies a deploy skill into `.claude/skills/` and appends its
+ * working rules to a freshly generated AGENTS.md. They reuse the McpPack
+ * shape so `installMcpPack` / `listPackSkillFiles` work unchanged.
+ */
+export const DEPLOY_PACKS = {
+    cloudflare: {
+        name: "deploy-cloudflare",
+        title: "Cloudflare（本地 wrangler CLI）",
+        hasSkills: true,
+        agentRules: [
+            "Deploy via the deploy-cloudflare skill (local wrangler CLI). Run the project's build and tests before any deploy; manage secrets with `wrangler secret put`, never commit them.",
+        ],
+    },
+    ansible: {
+        name: "deploy-ansible",
+        title: "云主机（Ansible playbook；Windows 下用 Docker 运行 Ansible）",
+        hasSkills: true,
+        agentRules: [
+            "Deploy to cloud hosts via the deploy-ansible skill (ansible-playbook; on Windows run Ansible through Docker). Always dry-run with `--check` first; keep secrets in ansible-vault.",
+        ],
+    },
+    "github-actions": {
+        name: "deploy-github-actions",
+        title: "GitHub Workflow（GitHub Actions CI/CD）",
+        hasSkills: true,
+        agentRules: [
+            "Deploy via the deploy-github-actions skill (GitHub Actions). The deploy job must depend on passing build and tests; repository secrets belong in GitHub Actions secrets, never in workflow files.",
+        ],
+    },
+};
+/** Valid values for `--with-deploy`; 'none' means skip deployment integration. */
+export const DEPLOY_TARGETS = [...Object.keys(DEPLOY_PACKS), "none"];
+export function getDeployPack(target) {
+    const pack = DEPLOY_PACKS[target];
+    if (!pack) {
+        throw new MetaError(`Unknown deploy target '${target}'. Valid targets: ${DEPLOY_TARGETS.join(", ")}`, EXIT_CODES.BAD_ARGS);
+    }
+    return pack;
+}

package/dist/core/filesystem.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { EXIT_CODES, MetaError } from "./errors.js";
 /**
  * All file writes go through this class so that --dry-run can report the
  * exact set of files that would be created or updated without touching disk.
@@ -16,7 +17,14 @@ export class FileWriter {
         return path.isAbsolute(p) ? path.relative(this.root, p) : p;
     }
     abs(p) {
-        return path.isAbsolute(p) ? p : path.join(this.root, p);
+        const abs = path.resolve(this.root, p);
+        const root = path.resolve(this.root);
+        // Paths come from user config (paths.*) and CLI flags; never let a
+        // `../`-style value escape the project root.
+        if (abs !== root && !abs.startsWith(root + path.sep)) {
+            throw new MetaError(`Path '${p}' resolves outside the project root. Check paths.* in agent-meta.config.yaml.`, EXIT_CODES.BAD_ARGS);
+        }
+        return abs;
     }
     exists(p) {
         return fs.existsSync(this.abs(p));

package/dist/core/frontmatter.js

@@ -91,6 +91,7 @@ export function sectionHasContent(content, names) {
     let capturing = false;
     let sectionLevel = 0;
     let inFence = false;
+    const captured = [];
     for (const line of lines) {
         if (/^\s*(```|~~~)/.test(line))
             inFence = !inFence;
@@ -106,14 +107,14 @@ export function sectionHasContent(content, names) {
             }
             continue;
         }
-        if (!capturing)
-            continue;
-        const text = line
-            .replace(/<!--[\s\S]*?-->/g, "")
-            .replace(/^[-*+]\s*/, "")
-            .trim();
-        if (text.length > 0 && !/^<!--/.test(line.trim()))
-            return true;
+        if (capturing)
+            captured.push(line);
     }
-    return false;
+    // Strip comments across line boundaries (like extractSection does), so a
+    // comment spanning multiple lines never counts as content.
+    return captured
+        .join("\n")
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .split(/\r?\n/)
+        .some((line) => line.replace(/^[-*+]\s*/, "").trim().length > 0);
 }

package/dist/core/mcp-packs.js

@@ -8,6 +8,9 @@ export const MCP_PACKS = {
         title: "IronBank MCP (hillinsight)",
         server: { type: "http", url: "https://test-ib-mcp.hillinsight.tech/mcp" },
         hasSkills: true,
+        agentRules: [
+            "Project docs and bug reports live in IronBank and are referenced by `hillinsight://ib_note?...` deep links. When you encounter one, resolve it with the IronBank MCP (see the ironbank-note-links skill) instead of skipping it; when citing IronBank notes in docs or replies, emit links in the same format.",
+        ],
     },
     playwright: {
         name: "playwright",
@@ -15,6 +18,14 @@ export const MCP_PACKS = {
         server: { command: "npx", args: ["@playwright/mcp@latest"] },
         hasSkills: false,
     },
+    "dev-env": {
+        name: "dev-env",
+        title: "本地开发环境约定（进程本机跑，redis/mysql/mq 用 Docker）",
+        hasSkills: true,
+        agentRules: [
+            "Local dev/test environment: run the project process directly on the host; start middleware dependencies (redis/mysql/mq) with Docker via the dev-env skill. Never install middleware globally on the host.",
+        ],
+    },
     superpowers: {
         name: "superpowers",
         title: "Superpowers (obra/superpowers, Claude Code plugin: planning/TDD/debugging skills)",

package/dist/generators/adr-generator.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-export const ADR_FILE_RE = /^(\d{4,})-(.+)\.md$/;
+// Any digit count, so files generated under a custom defaults.adr_padding
+// (schema minimum: 1) are recognized by numbering, indexing and validation.
+export const ADR_FILE_RE = /^(\d+)-(.+)\.md$/;
 export function listAdrFiles(adrDirAbs) {
     if (!fs.existsSync(adrDirAbs))
         return [];

package/dist/generators/index-generator.d.ts

@@ -1,6 +1,6 @@
 import type { MetaConfig } from "../schemas/config.schema.js";
 import type { FileWriter } from "../core/filesystem.js";
 export declare function buildDomainIndexTable(root: string, config: MetaConfig): string;
-export declare function buildAdrIndexTable(root: string, config: MetaConfig): string;
+export declare function buildAdrIndexTable(root: string, config: MetaConfig, relDir?: string): string;
 export declare function updateDomainIndex(writer: FileWriter, root: string, config: MetaConfig): void;
-export declare function updateAdrIndex(writer: FileWriter, root: string, config: MetaConfig): void;
+export declare function updateAdrIndex(writer: FileWriter, root: string, config: MetaConfig, relDir?: string): void;

package/dist/generators/index-generator.js

@@ -5,15 +5,22 @@ import { dateValueToString } from "../core/paths.js";
 import { listAdrFiles } from "./adr-generator.js";
 import { renderNamedTemplate } from "../core/templates.js";
 import { todayISO } from "../core/paths.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
 const DOMAIN_MARKERS = ["<!-- meta:domain-index:start -->", "<!-- meta:domain-index:end -->"];
 const ADR_MARKERS = ["<!-- meta:adr-index:start -->", "<!-- meta:adr-index:end -->"];
-function replaceBetweenMarkers(content, [start, end], body) {
+function replaceBetweenMarkers(content, [start, end], body, relPath) {
     const startIdx = content.indexOf(start);
     const endIdx = content.indexOf(end);
-    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+    if (startIdx === -1 && endIdx === -1) {
         // No markers: append a managed section at the end.
         return `${content.trimEnd()}\n\n${start}\n${body}\n${end}\n`;
     }
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+        // Exactly one marker (or reversed order): regenerating here could swallow
+        // user content between the orphan marker and a freshly appended section.
+        throw new MetaError(`Index markers in ${relPath} are malformed: expected '${start}' followed by '${end}'. ` +
+            `Restore both markers (in order), or remove both to let the index be re-appended.`, EXIT_CODES.CHECK_FAILED);
+    }
     return (content.slice(0, startIdx + start.length) + "\n" + body + "\n" + content.slice(endIdx));
 }
 function frontmatterStr(data, key) {
@@ -52,8 +59,8 @@ export function buildDomainIndexTable(root, config) {
         ...rows,
     ].join("\n");
 }
-export function buildAdrIndexTable(root, config) {
-    const adrDir = path.join(root, config.paths.adr_docs);
+export function buildAdrIndexTable(root, config, relDir = config.paths.adr_docs) {
+    const adrDir = path.join(root, relDir);
     const rows = listAdrFiles(adrDir).map((info) => {
         const doc = parseDocFile(info.file);
         const title = frontmatterStr(doc.data, "title") || info.slug;
@@ -74,14 +81,14 @@ function updateIndexFile(writer, relPath, markers, table, templateName, root, co
             date: todayISO(),
         });
     }
-    const updated = replaceBetweenMarkers(content, markers, table);
+    const updated = replaceBetweenMarkers(content, markers, table, relPath);
     writer.write(relPath, updated, { overwrite: true });
 }
 export function updateDomainIndex(writer, root, config) {
     const rel = path.join(config.paths.domain_docs, "README.md");
     updateIndexFile(writer, rel, DOMAIN_MARKERS, buildDomainIndexTable(root, config), "domain-index-readme.md", root, config);
 }
-export function updateAdrIndex(writer, root, config) {
-    const rel = path.join(config.paths.adr_docs, "README.md");
-    updateIndexFile(writer, rel, ADR_MARKERS, buildAdrIndexTable(root, config), "adr-index-readme.md", root, config);
+export function updateAdrIndex(writer, root, config, relDir = config.paths.adr_docs) {
+    const rel = path.join(relDir, "README.md");
+    updateIndexFile(writer, rel, ADR_MARKERS, buildAdrIndexTable(root, config, relDir), "adr-index-readme.md", root, config);
 }

package/dist/schemas/config.schema.d.ts

@@ -38,20 +38,14 @@ export declare const configSchema: z.ZodObject<{
         templates?: string | undefined;
     }>>;
     defaults: z.ZodDefault<z.ZodObject<{
-        doc_status: z.ZodDefault<z.ZodString>;
-        review_interval_days: z.ZodDefault<z.ZodNumber>;
         adr_padding: z.ZodDefault<z.ZodNumber>;
         agents_max_lines: z.ZodDefault<z.ZodNumber>;
         local_agents_max_lines: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        doc_status: string;
-        review_interval_days: number;
         adr_padding: number;
         agents_max_lines: number;
         local_agents_max_lines: number;
     }, {
-        doc_status?: string | undefined;
-        review_interval_days?: number | undefined;
         adr_padding?: number | undefined;
         agents_max_lines?: number | undefined;
         local_agents_max_lines?: number | undefined;
@@ -141,8 +135,6 @@ export declare const configSchema: z.ZodObject<{
         templates: string;
     };
     defaults: {
-        doc_status: string;
-        review_interval_days: number;
         adr_padding: number;
         agents_max_lines: number;
         local_agents_max_lines: number;
@@ -184,8 +176,6 @@ export declare const configSchema: z.ZodObject<{
         templates?: string | undefined;
     } | undefined;
     defaults?: {
-        doc_status?: string | undefined;
-        review_interval_days?: number | undefined;
         adr_padding?: number | undefined;
         agents_max_lines?: number | undefined;
         local_agents_max_lines?: number | undefined;

package/dist/schemas/config.schema.js

@@ -33,8 +33,6 @@ export const configSchema = z.object({
         .default({}),
     defaults: z
         .object({
-        doc_status: z.string().default("active"),
-        review_interval_days: z.number().default(180),
         adr_padding: z.number().int().min(1).default(4),
         agents_max_lines: z.number().default(180),
         local_agents_max_lines: z.number().default(120),

package/dist/validators/adr-validator.js

@@ -27,8 +27,8 @@ export function validateAdrs(ctx) {
                 code: "ADR_FILENAME_INVALID",
                 severity: "error",
                 file: path.join(relDir, f),
-                message: `ADR filename must match NNNN-slug.md (padding: ${config.defaults.adr_padding})`,
-                suggestion: "Rename the file, e.g. 0002-my-decision.md.",
+                message: "ADR filename must match <number>-slug.md",
+                suggestion: `Rename the file, e.g. ${"2".padStart(config.defaults.adr_padding, "0")}-my-decision.md.`,
             });
         }
     }
@@ -87,8 +87,8 @@ export function validateAdrs(ctx) {
             });
         }
         else {
-            const numMatch = /(\d{4,})/.exec(title);
-            if (!numMatch || parseInt(numMatch[1], 10) !== info.number) {
+            const titleNumbers = title.match(/\d+/g) ?? [];
+            if (!titleNumbers.some((s) => parseInt(s, 10) === info.number)) {
                 issues.push({
                     code: "ADR_TITLE_NUMBER_MISMATCH",
                     severity: "error",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bossmissing/agent-meta",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Agent Meta CLI - manage AI agent collaboration metadata (AGENTS.md, domain docs, ADRs, frontmatter checks)",
   "keywords": [
     "cli",