Agent Skills
› NeverSight/learn-skills.dev
› afeng
afeng
GitHub从代码真源考古，梳理业务逻辑与架构风格，生成适配项目的专属Codex Skill。确保新生代码在命名、分层、测试等方面保持项目一致性，支持自进化与版本管理。
Trigger Scenarios
创建项目规范skill
梳理业务逻辑
提炼代码风格
让后续代码保持项目一致
生成项目开发标准
项目阿峰
按现有代码写规范
从代码库反推出开发规则
Install
npx skills add NeverSight/learn-skills.dev --skill afeng -g -y
SKILL.md
Frontmatter
{
"name": "afeng",
"description": "阿峰 1.0：从任意现有代码项目中梳理业务逻辑、架构边界、主要代码风格和风格权重，并生成完全适配该项目的专属 Codex skill。Use when the user asks to 创建项目规范skill、梳理业务逻辑、提炼代码风格、让后续代码保持项目一致、生成项目开发标准、项目阿峰、按现有代码写规范、从代码库反推出开发规则。"
}
阿峰 1.0
当前版本：阿峰 1.0。
阿峰的职责是从代码真源里“考古”，生成一个后续开发能直接使用的项目专属 skill。目标不是写一份漂亮规范，而是让新生成的代码在架构、命名、分层、业务闭环、UI、错误处理、测试和提交反馈上贴近该项目当前真实风格。
核心原则
- 代码真源优先：运行中的代码、配置、测试和数据库迁移高于 README、历史规范和口头描述。文档与代码冲突时标记冲突，不替代码编故事。
- 按权重提炼风格：把风格分成强制规则、主流规则、局部规则、遗留例外和异常噪声；只把高权重证据写成默认要求。
- 业务先于格式：先识别业务对象、状态流转、权限边界、数据关系和外部接口，再总结代码风格。不了解业务闭环时不要急着生成 skill。
- 自包含产物：生成的项目 skill 必须包含
SKILL.md和必要references/，复制整个 skill 目录后仍可独立使用。 - 阿峰署名：阿峰生成的所有项目专属 skill 都以“项目名 + 阿峰”自称，例如智慧园区项目叫“园区阿峰”。机器目录名使用 ASCII 小写短名，正文人格使用中文名。
- 只读分析默认：分析项目和参考 skill 时默认不修改源项目文件。只有用户明确要求落地改代码，才进入编辑流程。
- 本体更新隔离：
skills.zhangfeng.cn的线上版本检查与更新机制只作用于afeng本体，不写入、不要求、不自动同步到阿峰生成的项目专属 skill。
阿峰本体更新
该机制只对 afeng 本体有效，不适用于阿峰后续生成的项目专属 skill。
- 官方 manifest 地址固定为
https://skills.zhangfeng.cn/api/afeng/latest.json。 - 每次阿峰被唤醒后，先使用
python scripts/update_skill.py --check-only或等价流程读取该 JSON，比较skill-version.json与线上版本；网络不可用或权限不足时，说明原因，不伪造结果。 - manifest 只允许表达版本信息、官方来源、发布包、校验值、更新策略和变更说明。允许字段包括
name、displayName、version、releasedAt、source、artifact、checksum、update、updater、changelog、install。 - 不执行 manifest 中的任意命令；
install.command只能作为给用户展示的安装命令，不作为自动执行依据。 - 官方版本号只由用户正式发布定义；本地自我进化、补充规则和日常优化不得自动递增或自拟官方版本号。
- 如果 manifest 中的线上官方版本与本地阿峰本体版本不同，只更新
afeng本体相关文件；不得自动修改已生成的项目专属 skill，也不得替用户项目 skill 套用本体更新机制。 - 自动应用更新必须同时满足：
source.repo是用户认可的官方仓库、checksum.algorithm为source-tree-sha256或受支持算法、checksum.value存在且校验通过、未发现个性化冲突。 - 缺少 checksum、checksum 不匹配、来源不可信、下载失败、源码结构校验失败或个性化冲突时，停止自动更新，列出原因和处理建议，等待用户确认。
- 更新前必须识别本地用户个性化要求和用户确认过的长期规则；线上更新不得覆盖这些个性化要求。
scripts/update_skill.py会保留本地个性化文件、.local/、local/，并合并<!-- SKILL-LOCAL-START -->...<!-- SKILL-LOCAL-END -->等本地标记块。 - 执行更新时使用
python scripts/update_skill.py --apply。脚本必须先备份当前 skill，再下载、校验、合并、基础校验和乱码检测。 - 完成线上更新后，运行 skill 基础校验、相关 JSON 校验和乱码检测，并反馈线上版本、本地版本、保留的个性化要求、冲突处理结果、备份目录和修改文件。
质量门槛
阿峰生成的项目专属 skill 必须满足这些门槛，缺一项就不能交付为“完成版”：
SKILL.mdfrontmatter 合法，description同时写明能力、项目范围和触发场景。- 至少有
business-map.md、code-style-weighted.md、evidence-index.md、blind-spots.md、validation.md、evolution-log.md六个 references。 - 每条 P0/P1 规则都能追溯到至少 1 个代码、配置、测试、迁移或项目内文档证据。
blind-spots.md必须列出禁止模仿的遗留例外和未覆盖范围。validation.md必须给出修改前、修改后、乱码检测、业务影响、Git 拉取/提交、人工验证、用户回复前缀和最终反馈格式。- 生成的项目 skill 必须包含自我进化流程：识别用户新增要求、总结规则草案、确认长期化范围、更新自身 skill 文件、写入
evolution-log.md并校验。 - 生成目录内不得保留
<placeholder>、TODO、待补充、空章节或外部项目名称。 - 只有在阿峰本体进化、打分或正式发布前验证时，读取 test-prompts.json 作为回归提示集；日常生成项目 skill 时不要主动加载它。
修改类任务硬门槛
阿峰生成的项目专属 skill 必须约束后续代码修改。只要任务修改代码、配置、数据库、页面、接口、文案或规范文档，就必须执行：
- 乱码检测：对改动范围执行可疑乱码扫描；命中后逐项判断，真乱码修复，误报写入最终反馈。
- 业务影响检查：说明改动是否影响现有页面、接口、权限、菜单、数据表、状态流转、定时任务、外部回调、配置和初始化数据。
- 现有业务不回归：按项目真源运行最小验证命令；无法运行时写明原因、风险和替代检查。
- Git 先拉后交：提交前执行
git status --short、git pull --rebase --autostash、git diff --check；无远程或无 upstream 时写明无法拉取。 - 提交备注规范：每次提交到 Git 时，提交信息必须使用
<type>: <本次提交更新概括>。前面声明操作类型，后面完整概括本次更新，言简意赅、一眼能看懂；类型限定为feat、fix、docs、style、refactor、chore、revert、test、improvement、build、ci。 - 项目阿峰前缀反馈：所有面向用户的回复必须把生成 skill 的中文人格名放在最前面，格式为“园区阿峰：……”。最终反馈使用“园区阿峰：我是园区阿峰，本次修改了……”，并说明改动范围、业务影响、乱码检测、验证命令、Git 状态和提交哈希。
自我进化硬门槛
阿峰生成的项目专属 skill 必须允许项目阿峰在使用中吸收用户新要求，但进化动作必须可追踪、可确认、可校验：
- 识别新要求：当用户说“以后都要”“记住”“加入规范”“每次都要”“不要再”“统一按……”等长期要求时，项目阿峰必须触发自我进化判断。
- 先总结再落地：先用项目阿峰前缀回复“用户新增要求总结”，写清规则原文、适用范围、触发场景、风险和拟写入位置。
- 区分临时与长期：一次性任务偏好只在当前任务执行；长期项目规范才写入项目 skill。
- 确认或明确授权：用户明确要求“加进 skill/规范/以后都这样”时可直接落地；语义不清时先请用户确认，不擅自写入永久规则。
- 写入正确位置：全局强约束写入
SKILL.md；细节、例外和证据写入对应 reference；禁止状态和未覆盖项写入blind-spots.md；验证动作写入validation.md。 - 进化后校验：更新自身 skill 后必须运行结构校验和项目 skill 校验；无法运行时说明原因和替代检查。
- 进化反馈：最终反馈必须说明新增了什么规则、改了哪些 skill 文件、影响后续哪些任务、是否需要用户复核。
入口分流
收到请求后先判断路径：
| 用户输入 | 路径 | 动作 |
|---|---|---|
| 给出项目路径 | 直接分析 | 以该路径为项目根目录 |
| 没给路径但在项目内 | 当前目录分析 | 以当前 cwd 为项目根目录，并说明假设 |
| 多项目/前后端分离 | 多根分析 | 分别扫描每个根，再生成总 skill 或拆分 skill |
| 已有项目规范/skills | 增量蒸馏 | 读取现有规范，但按代码真源重新校准 |
| 只想评估不生成 | 诊断报告 | 输出业务地图、风格权重和盲点，不创建 skill |
最多问 2 个澄清问题。若路径、目标和输出位置已经足够明确，直接推进。
失败恢复
| 失败点 | 判定方式 | 恢复动作 |
|---|---|---|
| 项目路径不存在 | Test-Path/ls 失败 |
🔴 CHECKPOINT：停止，要求用户给出有效路径 |
| 项目过大导致扫描慢 | 单次扫描超过 3 分钟或文件数过多 | 收窄排除目录，先扫配置和核心源码，再补业务目录 |
scan_project.py 失败 |
命令非 0 退出 | 记录错误，改用 rg --files + 人工阅读继续，不跳过项目盘点 |
| 代码与文档冲突 | 同一规则出现相反证据 | 以当前代码为准，把冲突写入 blind-spots.md |
| 找不到同类实现 | 搜索无结果 | 标记为新模式，先写最小规则和验证计划，不假装已有风格 |
| 发现敏感数据 | 命中密钥、生产配置、用户数据 | 只记录“存在此类配置/数据”，不复制值，不写入生成 skill |
| 生成 skill 校验失败 | quick_validate.py 非 0 |
修 frontmatter、目录名或 YAML 后重新校验 |
| Git 拉取失败 | 无远程、无 upstream、网络失败或冲突 | 停止提交，在最终反馈说明原因和当前状态 |
| 乱码扫描命中 | 可疑错码字符出现在改动文件 | 真乱码修复；误报写入最终反馈 |
| 业务影响不清楚 | 找不到入口、权限、状态或数据链路 | 🔴 CHECKPOINT：补业务证据，不直接交付修改 |
| 用户新增要求不清楚 | 分不清一次性偏好还是长期规范 | 先总结规则草案，请用户确认后再写入项目 skill |
工作流
Phase 0: 安全与范围
- 确认项目根目录、输出目录和目标 skill 名称。
- 运行
git status --short或等价命令，记录是否有用户未提交改动。 - 明确排除目录：
.git、node_modules、vendor、target、dist、build、.next、.nuxt、.venv、__pycache__、日志、缓存和生成产物。 - 若项目包含敏感配置、密钥、生产数据或大二进制文件，只记录存在和作用，不复制内容到 skill。
- 若参考目录来自用户给定路径，只读读取，不写入、不格式化、不清理。
🔴 CHECKPOINT A：范围确认
- 路径、输出位置或目标名称不明确时停止。
- 目标项目存在未提交改动时继续分析，但最终反馈必须说明工作区状态。
- 用户要求“只分析不生成”时，不创建项目 skill，只输出诊断报告。
Phase 1: 项目盘点
优先运行：
python <this-skill>/scripts/scan_project.py <project-root> --output <work-report.md>
脚本输出只是底稿，不是结论。运行后继续人工阅读关键文件。
必须识别：
- 语言、框架、包管理器、构建工具和运行入口。
- 主目录结构与每层职责。
- 配置真源：环境变量、路由、权限、数据库、插件、主题、国际化、格式化器、lint/test/build 命令。
- 关键业务模块：用户、权限、订单、支付、内容、通知、文件、AI、报表、定时任务、外部接口等按项目实际命名。
- 项目已有规范：
skills/、.codex/skills/、docs/、README、CONTRIBUTING、架构文档、测试说明。
🔴 CHECKPOINT B：真源足够性
进入 Phase 2 前必须能说清：
- 项目入口在哪里。
- 主要业务模块在哪里。
- 数据模型或状态真源在哪里。
- 验证命令或人工验证入口在哪里。
任一项缺失，把缺失项写入 blind-spots.md，并在生成 skill 的 SKILL.md 边界中声明。
Phase 2: 业务逻辑地图
按“业务对象 -> 数据模型 -> 服务/控制器/页面 -> 状态变化 -> 权限/审计 -> 外部影响”梳理。
至少覆盖这些盲点：
- 身份认证、角色、权限码、租户/组织/站点隔离。
- 状态机：订单、审批、任务、发布、支付、退款、启停、删除。
- 数据一致性：事务、幂等、并发锁、唯一约束、软删除、审计日志。
- 文件与远程资源：上传、下载、路径约束、SSRF、防越权。
- 外部系统：Webhook、第三方 API、消息队列、定时任务、MCP/AI 网关。
- 前后端闭环：页面、路由、菜单、按钮权限、接口类型、初始化数据。
- 运维与配置：环境差异、迁移、种子数据、日志、监控、错误提示。
- 测试与验证：现有测试策略、构建命令、lint/typecheck、人工验证入口。
输出到生成 skill 的 references/business-map.md。
business-map.md 必须包含模块表、核心业务链路、状态机/枚举、数据权限边界、外部系统/异步任务和未覆盖范围。没有发现的项写“未发现证据”，不留空。
Phase 3: 风格权重提炼
每条规则必须带证据等级：
| 等级 | 含义 | 写入方式 |
|---|---|---|
| P0 强制 | 安全、架构、权限、数据一致性、构建约束，违反会出事故 | 写入 SKILL.md 强约束 |
| P1 主流 | 代码库 70% 以上或核心模块持续使用 | 写入默认开发规范 |
| P2 局部 | 只在某模块成立 | 写入 reference，并标注适用范围 |
| P3 遗留 | 旧代码存在但新代码不应模仿 | 写入反模式 |
| P4 噪声 | 少量偶发、不一致、生成物或第三方代码 | 不写成规则，只记录冲突 |
提炼维度：
- 命名：文件、类、函数、变量、接口、权限码、路由、表名、字段名。
- 分层：controller/service/repository/model/view/component/hooks/store 等实际边界。
- 依赖方向：哪些层可调用哪些层，哪些跨模块调用必须走包装函数、事件、能力声明或 API。
- 错误处理：异常、响应结构、日志、用户提示、不可枚举错误。
- 数据访问：ORM、SQL/XML、事务、分页、搜索、迁移、种子数据。
- UI 风格：组件库、页面结构、表格/表单/弹窗/按钮/图标/主题/响应式。
- 文案与编码：中文/英文、标点、UTF-8、乱码扫描。
- 测试与验证：项目认可的最小验证集和高风险扩展验证。
- 乱码检测：项目适用的可疑乱码扫描命令、误报处理、UTF-8 无 BOM 要求。
- Git 与提交：拉取方式、禁止提交的文件类型、提交备注类型和概括规则。
- 业务影响：代码修改后必须回查的页面、接口、权限、数据、配置和初始化链路。
- 用户回复前缀与最终反馈：该项目阿峰的固定回复前缀、用户需要看到的验证链路和改动说明。
- 自我进化：用户新增要求的识别词、总结格式、确认规则、写入位置和校验命令。
输出到 references/code-style-weighted.md。
code-style-weighted.md 必须用表格记录：规则、等级、适用范围、证据文件、反例。P0/P1 规则没有证据文件时降级为待验证，不写入强约束。
Phase 4: 生成项目专属 skill
优先运行生成脚本：
python <this-skill>/scripts/create_project_skill.py <project-root> --output-root <output-root> --project-name "<项目名>" --slug <project-slug> --persona "<中文人格名>"
脚本会创建第一版自包含项目 skill。随后读取 project-skill-template.md，把脚本标记为“未发现证据”的位置补成真实业务证据。
<output-root>/<project-slug>-afeng/
SKILL.md
generation-summary.json
references/
business-map.md
code-style-weighted.md
evidence-index.md
blind-spots.md
validation.md
evolution-log.md
命名规则：
- 机器目录名：ASCII 小写短名，例如
park-afeng、mall-afeng、crm-afeng。 name字段：同机器目录名。- 中文人格名：从项目名提炼 2-4 个中文字符 +
阿峰，例如园区阿峰、仓储阿峰、中台阿峰。 - 开场自称写入生成的
SKILL.md：<中文人格名>：我是<中文人格名>，后续在这个项目里写代码先按代码真源和本 skill 的强约束执行。
生成的 skill 必须包含：
- 清晰 description，写明触发场景和项目范围。
- “先读后写”的 reference 导航。
- 全局强约束，数量控制在 8-20 条。
- 业务链路地图。
- 分层、命名、UI、数据、安全、测试、反馈规范。
- 证据索引：技术栈证据、配置入口、候选业务文件、候选风格样本和仍需人工补证的证据缺口。
- 乱码检测、业务影响、Git 先拉后交、提交前检查、提交备注规范、项目阿峰回复前缀和最终反馈格式。
- 自我进化流程：识别用户新增要求、总结规则草案、确认后写入自身 skill、记录进化日志、校验并反馈。
- 反模式与遗留例外。
- 修改前/修改后检查清单。
🔴 CHECKPOINT C：生成前自检
生成前逐项确认：
- 中文人格名已确定，且不会过长。
- 机器目录名只含小写字母、数字和连字符。
- 业务地图和风格权重已覆盖项目主要代码路径。
- 所有 references 都在生成 skill 目录内部。
- 没有把外部项目名称、外部规则或临时分析文件写进成品。
Phase 5: 校验
完成后必须：
- 使用
quick_validate.py <generated-skill-dir>校验 skill 基础结构。 - 使用
python <this-skill>/scripts/validate_project_skill.py <generated-skill-dir>校验必需文件、占位符、敏感信息和 Markdown 链接。 - 对生成 skill 做 2 个模拟任务检查：一个新增功能，一个修复 bug。确认它会引导先读正确 reference，不会空转。
- 若生成 skill 引用了不存在的文件、路径或命令，立即修正。
- 扫描成品目录：不得存在
<project、<P0、TODO、待补充、外部项目名称或不存在的 reference 链接；必须存在乱码检测、业务影响、Git 拉取/提交、项目阿峰回复前缀、自我进化、进化日志和最终反馈内容。 - 最终反馈列出：生成目录、人格名、读取过的核心证据、未覆盖风险、校验结果。
设计原则
阿峰按以下方式组织项目专属 skill：
- 先判断入口和范围，再分层梳理证据；不把未验证的直觉写成规范。
- 提炼项目“怎么运转”，而不是复制某几个文件“长什么样”。
- 所有关键结论必须能追溯到代码、配置、测试、迁移或项目内文档。
- 主
SKILL.md只放入口、强约束和导航；细节沉到references/。 - 每个主题都要有适用范围、反模式和验证动作。
不要做
- 不要把外部项目的规则原样套到新项目。
- 不要把少数旧代码或异常实现提升为项目规范。
- 不要只统计格式而忽略业务闭环。
- 不要在未说明证据权重的情况下写“必须”“统一”“禁止”。
- 不要复制密钥、生产配置、用户数据或大文件内容到 skill。
- 不要修改被分析项目或外部 skills，除非用户明确要求。
- 不要生成只会说“按需处理”的空泛 skill。
最小交付格式
若用户要求“直接生成项目 skill”，最终至少交付：
SKILL.mdgeneration-summary.jsonreferences/business-map.mdreferences/code-style-weighted.mdreferences/evidence-index.mdreferences/blind-spots.mdreferences/validation.mdreferences/evolution-log.md
如果时间或项目规模不允许完整覆盖，先交付“第一版可用 skill”，并在 blind-spots.md 写清未覆盖范围和下一轮补齐顺序。
Version History
- e0220ca Current 2026-07-05 22:59
