permission-resource-mcp

permission-resource-mcp 是一个独立的 TypeScript / Node 仓库，用于通过签名 OpenAPI 同步权限资源清单。仓库同时提供两层入口：

• MCP server：给 Codex、OpenCode 或其他 MCP 宿主使用
• CLI：给终端、CI 和全局 permission-resource-sync skill 封装使用

项目聚焦权限资源本身，也就是菜单、页面按钮和 API 权限点；不处理角色授权、用户角色绑定等相邻领域。

快速开始

npm install
npm run lint
npm run typecheck
npm test

本地开发：

npm run dev

构建发布产物：

npm run build

文档导航

常用入口

• 安装与接入速查
• CLI 使用说明
• 从 npm 发布到 Codex 接入指南
• permission_resource 接口契约说明
• permission_resource 最小可执行请求示例
• 新增权限标准操作流程

架构与背景

• 项目总览
• 项目结构与关键模块
• permission_resource 字段映射表
• permission_resource 自描述查询说明

设计与实现记录

• 执行者体验优化建议
• 回归验收清单
• CLI-first 最小实现计划
• upserts / deletions 模型优化记录
• 执行者体验优化计划记录

npm 包与双入口

当前发布包名：qm-permission-resource-mcp

包内提供两个可执行入口：

• MCP：permission-resource-mcp
• CLI：qm-permission-resource-cli

启动 MCP：

npx -y qm-permission-resource-mcp

调用 CLI：

npx -y -p qm-permission-resource-mcp qm-permission-resource-cli contract --topic manifest

CLI 默认输出人类可读的 pretty 摘要到 stdout。如果需要结构化结果，显式传 --json：

npx -y -p qm-permission-resource-mcp qm-permission-resource-cli contract --topic manifest --json

CLI 运行时会把阶段提示输出到 stderr。仓库内 permission-resource-sync wrapper 会自动补 --json，保证 skill 和脚本消费的是稳定 JSON。

CLI、MCP 与 skill 的关系

• MCP：给宿主工具调用，入口见 从 npm 发布到 Codex 接入指南
• CLI：给终端、CI、自动化脚本直接调用，入口见 CLI 使用说明
• skill：给 AI 使用的默认流程和守则，优先走 CLI，CLI 不可用时再回退 MCP

当前 wrapper 行为：

1. 先尝试 PATH 里的 qm-permission-resource-cli
2. 全局 CLI 不可用时，再检查当前工作目录下是否存在 dist/cli/main.js
3. 仍不可用时，回退 npx -y -p qm-permission-resource-mcp qm-permission-resource-cli ...

仅当明确处于“本地开发”场景时，才应在 CLI / wrapper 命令上附加 --dev。--dev 会允许读取当前工作区的 .env 和 dist/cli/main.js；默认模式下不要依赖这些工作区本地工件。

术语约定

建议优先使用这组术语：

• 名称：权限显示名，对应 name
• 前端权限编码：前端权限标识，对应 route
• API权限：接口权限点列表，对应 api_list
• 父级：层级归属，对应 parent_route / children / parentRoute
• 默认勾选：默认选中状态，对应 selected

自然语言中如果把术语说混，按下面规则归一化：

• 前端权限编码、权限编码、route、路由编码 都按 route 处理
• API权限、接口权限、后端权限、接口编码 都按 api_list 处理
• 如果用户只说 前端权限，不要直接假定一定是字段名；若同时给了明显像编码的值，可先按 前端权限编码 理解，但在 apply 前必须复述
• 如果语句无法判断是在说“权限名称”还是“前端权限编码”，先追问，再执行 plan / apply

Manifest 契约

manifest 使用 YAML，当前版本固定为 version: 1。manifest 输入字段使用 snake_case。

推荐写法

新推荐写法是：

• upserts：显式表达需要新增或收敛字段值的权限节点
• deletions：显式表达需要删除的权限节点

示例：

version: 1
upserts:
  - name: 系统设置
    route: system.settings
    parent_route: null
    selected: 1
    sort: 10

  - name: 用户管理
    route: system.settings.user
    parent_route: system.settings
    api_list:
      - /api/user/list
      - /api/user/update

deletions:
  - route: system.settings.legacy
    name: 旧权限

兼容写法

旧的树形写法仍然兼容：

• resources
• resources[].children
• resources[].api_list

它适合表达完整小树；深层级局部新增或编辑更推荐 upserts。

示例文件

• 兼容树形写法示例：manifests/examples/data-center.yaml
• 推荐 upserts 写法示例：manifests/examples/data-center-upserts.yaml
• 推荐 upserts + deletions 写法示例：manifests/examples/data-center-upserts-deletions.yaml

删除语义

• 推荐使用 deletions
• deletions[].route 必填
• deletions[].name 可选，作为保护条件
• 如果 route 存在但 name 不匹配，不会删除，会进入 skippedDeletes / skippedRoutes

旧删除语义

deleteMissing / --delete-missing 仍兼容，但已经降级为旧语义，不再推荐。传入时会返回 warning：

• deleteMissing=true 已属于旧删除语义；请改用 manifest.deletions 显式声明待删除权限

其他重要规则

• api_list 对应的是“API权限”，不是权限名称或前端权限编码
• parentRoute 不是 manifest 输入字段
• 在 upserts 中请使用 parent_route
• 在树形写法中请使用 children
• client_id 在 validate_manifest 传入 environment，或在 plan_sync / apply_sync 中执行时可以省略，此时会回退到运行时默认 CLIENT_ID
• AI 或 CLI 自己为了驱动流程生成的 manifest，默认应优先作为 manifestContent 或 --manifest-stdin 传入，而不是写临时文件

Skill

仓库附带一个操作型 skill：skills/permission-resource-sync。

当前默认策略：

• 优先接受自然语言变更描述
• 优先把自然语言归一化为 upserts / deletions
• 深层级新增 / 编辑优先生成 upserts + parent_route
• 删除优先生成 deletions
• 如果用户使用了模糊术语，例如只说“前端权限”，先做归一化复述；仍然不明确时先追问，再执行 plan / apply
• 优先生成内联 manifestContent
• 优先调用 qm-permission-resource-cli，CLI 不可用时再回退 MCP
• 仓库内 wrapper 会自动补 --json

发布

发布前检查：

npm run lint
npm test
npm run typecheck
npm run build
npm pack --dry-run

首次发布：

npm login
npm publish

后续发版：

npm version patch
npm publish

如果你之前已经发布过一个不完整的 CLI 包版本，需要重新发布一个新 patch 版本。原因是早期包的 files 白名单没有带上 dist/chunk-*.js，会导致全局安装后的 qm-permission-resource-cli 报 ERR_MODULE_NOT_FOUND。修复后的版本发布后，使用者需要重新安装：

npm install -g qm-permission-resource-mcp@latest

补充说明：

• prepublishOnly 会自动执行 lint + test + typecheck + build
• npm 包会包含双 bin、dist 构建产物、README 和 skills/permission-resource-sync
• 首发版本与 tag 建议见 release-0.1.0.md
• 从 npm 发布到 Codex / OpenCode 接入见 npm发布到Codex接入指南.md
• CLI 详细命令见 cli使用说明.md
• 契约说明见 permission_resource 接口契约说明.md