English summary: A Chinese-first, VS Code-native customization kit that turns GitHub Copilot into a project-level DRI (Directly Responsible Individual) with enforceable spec-driven workflows, 14-surface audits, and three-Gate decision governance. Read
README.en.mdfor the full English version.
一句话定位：把一整套「项目首席责任人开发协议」通过 VS Code 的全部官方扩展点接入 Copilot —— 不是提示词堆砌，而是可执行、可审计、可回滚的工程纪律资产。
- ✨ 这是什么
- 🎯 不是什么
- 🚀 快速开始
- 🧱 项目结构
- 🧭 核心方法论
- 🔀 工作流路由表
- 🛠️ 为什么是 VS Code 原生
- 🎁 鸣谢与设计谱系
- � 诚实声明 · 已知局限
- �🤝 欢迎共建
- 📄 License
agent-assets 是一套可被 clone 到任何项目的 Markdown + JSON 配置资产，为 VS Code + GitHub Copilot 量身定制。它把人类工程团队里"项目首席责任人（DRI）"该有的判断力、纪律和回滚边界，通过 VS Code 的官方 Agent Customization 接入点全部注入 Copilot。clone 到生产代码仓库后自动生效——无需安装、无需依赖、无需构建。
instructions/：按文件模式applyTo自动加载的领域规范（前端 / 后端 / 数据库 / 文档 / PowerShell / TDD / 代码审查 / 合规 / 总规则）。skills/：60+ 个按语义自动触发的工作流技能（写规格、执行规格、项目诊断、Bug 审计、根因定位 ……）。agents/：3 个持久角色（planner / implementer / code-reviewer），通过@name切换。prompts/：5 个斜杠命令模板（/specs-write、/specs-execute等）。hooks/：PreToolUse 安全拦截（拦rm -rf/DROP TABLE/git push --force等）+ PostToolUse 审计日志。.vscode/settings.json：把 Copilot 的 commit / PR / review 生成行为绑定到本仓库规范。
结果：Copilot 在本仓库里不是"问什么答什么"的助手，而是会主动维护项目全貌、按工作流分流、按门禁验证、按 Gate 决策、按 SSOT 不漂移的项目第一负责人。
为了节省你的判断成本，明确边界：
- 不是 Copilot 提示词合集或"魔法咒语"——所有协议都有可执行验证命令（ESLint / Ruff / pytest / 14 层 drift 防线 / TDD-Lock SHA-256）。
- 不是 MCP server、不是 VS Code 扩展、不是脚本工具——零安装，clone 即用。
- 不是 为其他 IDE 适配（Cursor / Cline / Claude Code 有自己的资产目录约定；本仓库仅提供
CLAUDE.md作为跨代理桥接参考）。 - 不是 强迫你照搬——所有协议以 DRI 自决 为底色，你拍板的范围被严格收窄到「战略 / 关键设计 / 不可回滚副作用」三类。
- 不是 仅适合大团队——单人独立开发者也能享受"自动维护 SSOT、自动审计、自动验证门禁"的红利。
前置：已安装 VS Code + GitHub Copilot 扩展 并登录 Copilot 订阅。
1. Clone 本仓库到你的项目根（或作为子目录）
git clone https://github.com/<owner>/agent-assets.git
cd agent-assets
2. 用 VS Code 打开本目录
code .
3. 替换 LICENSE 占位符
把 LICENSE 第 3 行的 [Your Name / Your Studio] 改成你的真实署名
4. 开始对话
在 Copilot Chat 里说："项目状态不清" → Copilot 会自动命中 /project-steward
或说："我要做 X 功能" → Copilot 会自动命中 /specs-write
打开后 VS Code 会自动检测 AGENTS.md、.github/copilot-instructions.md、.github/instructions/、.github/skills/，全部注入 Copilot 上下文。无需任何手动配置。
💡 若要把资产迁移到已有项目：把
.github/、AGENTS.md、CLAUDE.md、.vscode/settings.json、LICENSE、.markdownlint.json复制过去即可。docs/目录是 spec 工作流运行时自动创建的，仓库不预置。
agent-assets/
├── AGENTS.md # 跨代理中央注册表（VS Code 自动检测）
├── CLAUDE.md # Claude Code / Cursor / Windsurf 桥接入口
├── LICENSE # MIT
├── .markdownlint.json # Markdown 规则配置
├── .vscode/
│ ├── settings.json # Copilot 行为绑定（commit / PR / review / skillTool）
│ └── tasks.json # markdownlint 全量检查任务
└── .github/
├── copilot-instructions.md # VS Code 自动加载的核心协议（速查 + 路由表）
├── instructions/ # applyTo 文件模式自动加载的领域规范（9 个）
│ ├── rules.instructions.md # 完整开发协议（DRI / 三 Gate / 14 面审计 / DOM）
│ ├── frontend.instructions.md # TypeScript / React 风格
│ ├── backend.instructions.md # Python / FastAPI 风格
│ ├── database.instructions.md # SQL + 14 层 drift 防线
│ ├── documentation.instructions.md # 文档分层 + 命名纪律
│ ├── test-driven.instructions.md # TDD + DoD 门禁
│ ├── code-review.instructions.md # 审查三维度
│ ├── powershell.instructions.md # Windows PowerShell 风格
│ └── compliance.instructions.md # 版权 / AI 残留清理（手动附加）
├── skills/ # 语义自动触发的工作流（60+ 个）
│ ├── specs-write/SKILL.md # 模糊需求 → 可审查 Spec 合同
│ ├── specs-execute/SKILL.md # 按 Task TDD 执行
│ ├── project-steward/SKILL.md # 项目首席责任人诊断与分流
│ ├── project-inception/SKILL.md # 0 → 1 立项
│ ├── review/SKILL.md # 三轴变更审查
│ ├── diagnose/SKILL.md # 反馈回路驱动的根因定位
│ ├── bug-audit/SKILL.md # 缺陷影响面与严重性审计
│ ├── tdd/SKILL.md # 局部 TDD Red-Green-Refactor
│ └── ... # 完整列表见 AGENTS.md
├── prompts/ # 斜杠命令模板（5 个）
│ ├── specs-write.prompt.md
│ ├── specs-execute.prompt.md
│ ├── project-steward.prompt.md
│ ├── code-review.prompt.md
│ └── bug-diagnose.prompt.md
├── agents/ # 持久角色（3 个）
│ ├── planner.agent.md # 四阶规划
│ ├── implementer.agent.md # specs-execute 纪律执行
│ └── code-reviewer.agent.md # 只读三维度审查
├── hooks/ # 生命周期拦截
│ ├── safety-guard.json # PreToolUse 危险命令拦截
│ ├── pre-tool-guard.ps1 # 安全判定脚本
│ └── audit-log.json # PostToolUse 审计日志
└── verify-completeness.ps1 # 资产完整性自检
本仓库不是"提示词"，而是一套自洽的工程哲学。核心术语（均来自 rules.instructions.md）：
| 概念 | 一句话 |
|---|---|
| DRI（Directly Responsible Individual） | Copilot 是项目缺省 DRI，主动维护全貌、识别下一步、补齐上下文、执行验证、归档证据 |
| 三 Gate | Strategy（产品方向）/ Critical Design（架构契约）/ Real-World Side Effect（不可回滚副作用）—— 仅这三类由用户拍板 |
| 决策所有权矩阵 DOM | L-STRAT 战略级 / L-DESIGN 设计级 / L-IMPL 实现级 / L-ROUTINE 例行级 —— 越往下 Copilot 越自主 |
| Pause-and-Ask 白名单 | 只有 5 类情形允许阻塞式反问（战略 / 关键设计置信度<70% / 不可回滚 / Spec Breach / 低置信度） |
| 14 面全景审计 | 文档 SSOT / 历史 / 真实数据库 / 数据静态 / 架构 / 契约 / 依赖 / 运行部署 / 代码入口 / UI / 测试 / 安全隐私 / 可观测 / 合规版权 |
| SSOT 三层文档体系 | L1 战略 SSOT / L2 执行合同 / L3 交付归档 —— 一个事实只定义一次，其他用引用 |
| 开工四问 | 想清楚 → 最小够用 → 外科手术 → 可验证 |
| 三 TDD 闭环 | ATDD（AC→验收测试）/ BDD（US→场景）/ TDD（单测 PASS）—— /specs-execute Phase 7 必须全过 |
| 14 层 drift 防线 | 任何 Schema 变更必须 14 层 ALL GREEN：migration 完整性 / ORM 对齐 / 真库读回 / 列类型 / CHECK / 索引 / 触发器 / 视图 / mypy / OpenAPI 契约冻结 …… |
| 场景 | 命令 / Skill | 一句话 |
|---|---|---|
| 项目状态不清 / 下一步不明 | /project-steward |
全局诊断与分流 |
| 无母本 / L1 SSOT | /project-inception |
0 → 1 立项 |
| 新功能 / 跨模块重构 | /specs-write |
需求 → Spec 合同（七件套） |
| 执行已批准 Task | /specs-execute TASK-### |
强制复述 + TDD Red-Green-Refactor |
| 已实现 diff 审查 | review |
Standards / Spec / Verification 三轴 |
| 根因定位 / 性能回退 | diagnose |
反馈回路驱动的纪律化诊断 |
| Bug 影响面未知 | /bug-audit |
广度 + 深度缺陷审计 |
| 架构摩擦 / 浅模块 | /architecture-audit |
seam / interface 重塑 |
| 商业闭环 / MVP 生死 | /business-model-audit |
买方 / 替代方案 / ROI |
| 局部小功能 / 简单 bug | tdd 或 direct |
局部 Red-Green-Refactor |
完整工作流列表与触发条件见
AGENTS.md。
业界其他智能体方案把规则塞进 .cursorrules / .clinerules / CLAUDE.md 等单文件，本仓库完全使用 VS Code 官方 Agent Customization 接入点，对照 VS Code 官方文档：
| VS Code 接入点 | 本仓库用法 | 优势 |
|---|---|---|
AGENTS.md |
跨代理中央注册表 | VS Code 自动检测，零配置 |
.github/copilot-instructions.md |
核心协议速查 | 项目级 always-on |
.github/instructions/*.md + applyTo |
9 个领域规范按文件类型自动加载 | 按需注入，避免上下文污染 |
.github/skills/*/SKILL.md |
60+ 语义触发工作流 | Copilot 自动识别任务语义并加载 |
.github/agents/*.agent.md |
3 个持久角色 + 工具限制 + 模型偏好 | 角色边界清晰，工具权限隔离 |
.github/prompts/*.prompt.md |
5 个斜杠命令 | /specs-write 即可调用 |
.github/hooks/*.json |
PreToolUse / PostToolUse | 灾难命令硬拦截 + 审计日志 |
.vscode/settings.json |
Copilot commit/PR/review 生成行为绑定 | 让 Copilot 输出符合本仓规范 |
chat.useAgentsMdFile / chat.skillTool.enabled |
启用 AGENTS.md 与 Skill 工具 | 一处开关 |
对照参考：本仓库的 CLAUDE.md 是给 Claude Code / Cursor / Windsurf 的兼容入口；.github/instructions/ 的 applyTo 模式比单文件 .cursorrules 更精细（按语言隔离规范，避免上下文膨胀）。
本仓库坚持诚实标注外部来源。资产吸收分为四类，每一类都有清晰的来源、模式与凭证记录。
下列 skill 是从外部仓库完整拷贝 + 本地化适配而来（保留 MIT 协议），均经用户明确批准并记录在项目自带的来源审计凭证中：
- greensock/gsap-skills（GreenSock / Webflow）—— 8 个 GSAP 动画 skill 直接迁移：
gsap-core·gsap-timeline·gsap-scrolltrigger·gsap-plugins·gsap-utils·gsap-react·gsap-performance·gsap-frameworks- 批准记录：用户于 2026-05-29 明确批准（原话：「直接搬迁，做好windsurf及本地适配化即可」）
- 凭证文件：
.github/skills/asset-quality-gates/references/external-provenance-gsap-skills.md - 本地适配：每个 skill 添加中文译名、AGENTS.md 索引登记，移除外部平台专属配置（
.claude-plugin/.cursor-plugin）
下列工作流的设计机制吸收自外部 AI 工程资产仓库，经机制参考重写为中文协议（非源码复制）：
- garrytan/gstack —— 本仓库大量核心工作流的机制源自 gstack，包括：
- 生命周期闭环：思考-计划-构建-审查-测试-发布-复盘 →
/project-inception+/specs-write+/specs-execute+review+webapp-testing+/release-deploy+engineering-retro - 发布就绪度仪表盘 →
/release-deploy的 readiness-dashboard - 会话现场保存与恢复 →
session-contextskill - 运行教训账本 →
operational-learningsskill（Ephemeral / Project Local / Promoted 三层） - 浏览器 QA 与视觉证据 →
webapp-testingskill - 安全审计与威胁建模 →
/security-privacy-audit（STRIDE + OWASP） - 范围守卫与编辑锁 →
scope-guardskill - 代码健康度仪表盘 →
/code-health-dashboard - 设计系统与视觉 QA →
/design-system-audit+frontend-design - 工程周期复盘 →
engineering-retro - 浏览器操作流固化 →
browser-flow-codifierskill - 带所有权防线的提问控制 → DOM 决策所有权矩阵 + Pause-and-Ask 豁免名单
- 凭证文件：
.github/skills/asset-quality-gates/references/external-provenance-gstack-main.md（含完整功能覆盖矩阵）
- 生命周期闭环：思考-计划-构建-审查-测试-发布-复盘 →
gstack 的
/gstack-upgrade（静默自更新）、/setup-gbrain（向量库守护进程）、/setup-browser-cookies（Cookie 解密）等存在安全 / 合规风险的功能明确排除不导入，理由见凭证文件。
下列项目的设计哲学与目录约定被净室吸收，本仓库无源码复制：
- VS Code Agent Customization 官方文档 —— 本仓库全部接入点的权威依据。目标：完美贴合官方搭建指南，所有目录约定（
.github/instructions/、.github/skills/、.github/agents/、.github/prompts/、.github/hooks/、AGENTS.md）均严格对齐。 - Claude Code / Claude Design —— 净室吸收了 Anthropic 推动的「项目级 AI 协议文件」范式（
CLAUDE.md）。本仓库CLAUDE.md作为跨代理桥接入口致敬这一范式；同时本仓库的「项目首席责任人（DRI）协议」设计哲学受 Claude Code 的「agentic coding with guardrails」理念影响。 - GitHub Spec Kit / spec-kit by gistdotdev ——
/specs-write的「需求 → 可执行合同」分解思想受其启发，改造为中文 EARS / BDD / TDD 三轨配对。
下列经典著作与思想散见于各 instructions / skills，均为概念引用而非内容复制：
- EARS Notation（Alistair Mavin）—— 需求语句结构化语法，
/specs-write步进 5 引入。 - Behavior-Driven Development（Dan North）—— Gherkin
Given/When/Then场景。 - Test-Driven Development: By Example（Kent Beck）—— Red-Green-Refactor 与「测试应通过公共接口验证行为」哲学，是
tdd与/specs-executePhase 4-6 的基石。 - Growing Object-Oriented Software, Guided by Tests（Steve Freeman & Nat Pryce）——
tdd中「端到端 tracer bullet」「mock 准则」直接源自此书。 - Debugging: The 9 Indispensable Rules（David J. Agans）——
diagnose的「先建立反馈回路，再假设」纪律受其影响。 - The Pragmatic Programmer（David Thomas & Andrew Hunt）—— DRY、tracer bullet、broken windows 等概念。
- DRI 文化（Apple / Tesla 工程实践）—— 「Directly Responsible Individual」概念源自 Apple 工程文化，本仓库把它从人类组织延伸到 Copilot 自主决策模型。
- Contributor Covenant ——
CODE_OF_CONDUCT.md采用此国际通行社区行为准则。
本仓库通过 /asset-quality-gates skill 维护一套严格的外部资产 intake 协议（6 步流程 + R-CHK-10~15 检查项）：任何外部资产引入必须经 quarantine 隔离、license 兼容性判定、frontmatter 改造、eval seeding、AGENTS.md 索引登记、用户批准后才能进入启用路径。详见 .github/skills/asset-quality-gates/protocols/intake-protocol.md。这是本仓库「诚实标注外部来源」的制度保障。
本仓库不是以下项目的 fork 或包装：
- 不是 Cursor / Cline / Roo Code / Aider 的资产包 —— 那些项目各有自己的资产目录约定（
.cursorrules/.clinerules等），本仓库是 VS Code 原生方案。 - 不是 MCP server / VS Code 扩展 —— 零安装，纯配置资产。
- 不是 Continue / Cody 的替代 —— 本仓库只针对 GitHub Copilot。
感谢所有在公开讨论、issue、PR 中提出反馈的开发者。完整贡献者名单见 CONTRIBUTING.md 与 GitHub Insights 页面。
本仓库追求「高自决必须高审计」与「质量优先」，但坦白承认以下局限。这是诚实的工程表态，不是营销话术。
- 仍在演进：核心方法论（DRI / 三 Gate / DOM / 14 面审计 / 14 层 drift 防线）是单人独立开发实践中提炼的体系，未经大型团队 / 复杂分布式系统 / 合规严苛行业（金融 / 医疗）的长期验证。
- 可能过度工程化：14 面 / 14 层这类「对称美学」的数字，在某些场景下可能带来超出收益的流程开销。小团队 / 个人项目应自行裁剪。
- 术语学习曲线陡：DRI / DOM / SSOT / Pause-and-Ask / Gate A-B-C 等术语密集，新用户上手成本不低。
- 验证样本有限：
/specs-write→/specs-execute的完整七件套 spec 合同主要在中文个人项目中跑通；英文项目、跨国协作、多人并发 spec 场景验证不足。 - 跨代理兼容是单向桥：
CLAUDE.md只是给 Claude Code / Cursor / Windsurf 的入口指引，不保证这些代理能完整复现 VS Code Copilot 的 skill 触发、instruction applyTo、hook 拦截等行为。 - hook 拦截依赖宿主：
.github/hooks/safety-guard.json的 PreToolUse 拦截依赖 VS Code Copilot 的 hook 机制；若用户关闭了 Autopilot 高级评估器，灾难命令兜底完全依赖本仓库的 PowerShell 脚本，存在被绕过的理论风险。
- 中文主导：协议正文与大量 skill 是中文，海外非中文用户使用门槛较高。
README.en.md是翻译参考，多数 skill 仍待翻译。 - GSAP skills 是直接翻译：8 个 gsap-* skill 是从 GSAP 官方文档直接迁移，未做内容层面的本地化创新或中文场景适配，本质是官方文档的中文搬运 + AGENTS.md 索引登记。
- Windows / PowerShell 偏好：大量 DoD 命令默认假设 Windows + PowerShell 环境（如
.\venv\Scripts\python.exe），macOS / Linux 用户需自行调整。
- 单人维护为主：项目当前由维护者以 AI 协作方式推进，60+ skill 的覆盖深度不均，可能存在死链、过期引用、自相矛盾的角落案例。
- 跟随官方演进的压力：VS Code Copilot Agent Customization 仍在快速演进，接入点 API 可能变动；本仓库的同步速度取决于维护者精力。
- 未提供自动化测试：没有针对 skill 触发准确率、instruction 加载正确性的自动化测试套件（
/skill-evalskill 提供了人工 eval 框架，但未 CI 化）。
我们不回避、不粉饰。如果你在使用中遇到上述局限带来的具体问题，欢迎在 Issues 开诚布公地反馈——尤其是「这里过度工程化了」或「这里在大型团队失效」这类否定性反馈，对我们最有价值。
这是一个长期维护、社区驱动的开源项目。我们欢迎：
- 🐛 Bug 报告与建议：通过 GitHub Issues 提交，请先搜索是否已存在。
- 🔀 Pull Request：协议补充、新 Skill、英文翻译、跨代理兼容性改进。请先读
CONTRIBUTING.md了解规范与提交流。 - 🌐 国际化：欢迎把核心协议翻译成英文 / 日文 / 韩文等。本项目是中文主导，但欢迎双语并行。
- 💡 使用案例分享：在你的项目里用了本仓库？欢迎在 Discussions 分享场景与改进建议。
- ⭐ Star & Fork：如果本仓库帮到了你，欢迎点 Star 让更多人看到。
共建原则（详见 CONTRIBUTING.md）：
- 中文主导，国际开放：协议正文中文，但 issue / PR / commit message 接受双语。
- 净室吸收：吸收外部概念必须改写为中文协议并显式鸣谢，禁止直接复制他人源码。
- DRI 文化：每个 PR 必须有明确作者与可验证 DoD。
- Spec 优先：大型变更走
/specs-write，不接受"提示词堆砌"式 PR。
维护节奏：跟随 VS Code Copilot Agent Customization 官方演进同步迭代；语义版本号见 CHANGELOG.md。
MIT License © 2026 海口秀英区洞悉人工智能应用软件工作室
著作权人 / 登记主体：海口秀英区洞悉人工智能应用软件工作室 统一社会信用代码：92460000MAK66KH20N
详细署名规范（自然人作者 vs 著作权人 / 登记主体）见
.github/instructions/compliance.instructions.md与NOTICE。
让 Copilot 不只是助手，而是你的项目首席责任人。 🚀