Imported from xueyu888/shelf (
AGENTS.md). Install upstream withnpx skills add xueyu888/shelf. Copyright stays with the author.
AGENTS
仓库认知前提（强制）
- 框架不是某个项目的模板，而是 AI 编程时代的人和 AI 之间的共同结构语言。
- 仓库主分层应保持
Framework -> Config -> Code -> Evidence的单向收敛。 projects/<project_id>/project.toml是项目配置唯一入口；配置物理上统一，逻辑上必须明确区分framework / communication / exact。project.toml默认应使用中文注释，作为人与 AI 协作讨论的主入口。- 上述 TOML 文件在篇幅可控时，应优先提供详细注释而不是极简标签；至少在文件头和每个主 section 前说明职责边界、讨论重点与与相邻层的分界。
framework负责声明项目装配哪些 framework 模块；communication负责人与 AI 的结构化沟通要求；exact负责 Code 层精确消费字段。- 面向
framework/*.md的标准模板起手能力属于仓库基本作者入口，不得移除。当前保底入口为 Shelf AI 的@framework模板与显式插入命令；若未来重构，必须提供同等直接、默认可用、可测试的替代能力。
核心规则
framework/*.md是作者源。不要把 framework 真相源改成 schema、config 或生成物。- 每个 framework 文件必须解析成一个独立
FrameworkModuleclass。 - 每个
B*必须是一等Baseclass；每个R*必须是一等Ruleclass。 ConfigModule只消费对应FrameworkModuleexport；CodeModule只消费对应ConfigModule.exact_export；EvidenceModule只消费对应CodeModuleexport。- 架构关系只允许用组合，不允许用继承。
- 项目由三部分决定：framework markdown、统一 project config、真实 code 实现。不要把项目做成手写特化分支。
communication只能写结构化沟通要求；exact只能写 Code 层精确消费字段。- 自然语言说明只能做补充；机器判定必须依赖结构化字段。
generated/canonical.json是唯一机器真相源。其他 tree、report、evidence view 都只能是它的派生视图。- 不要恢复旧的核心架构。不要保留并行真相源，不要把旧系统换个名字继续跑。
- 写任何代码前，先评估是否存在更简洁的等效实现；若存在必须优先采用。只有在正确性、性能、兼容性或可测试性明确需要时，才允许增加实现复杂度。
- 禁止硬编码门禁/依赖/项目路径。涉及模块选择、跨层依赖、root 关系、项目定位时，必须基于 framework upstream、project 配置或运行时发现，不得写死
frontend/knowledge_base/backend固定分支或projects/project.toml固定回退。 - 防回退要求：提交前必须通过
tests/test_no_hardcode_guard.py，若出现命中项必须先改为配置化/结构化来源再继续。
默认工作顺序
- 读相关
framework/*.md - 找对应
FrameworkModule / ConfigModule / CodeModule / EvidenceModule - 校验
communication / exact - 修改 code composition 或 code internals
- 更新
generated/canonical.json - 更新所有 derived views 和 validation outputs
- 始终保持架构单一，不要创建 side channel
对话触发守卫（强制）
- AGENTS 只认最终生效的
shelf.*值作为门禁配置语义入口，不再维护独立目录常量；不再在 AGENTS 里区分配置最终写在哪个文件里。 - 默认受检目录为：
framework/ - 只要用户在 AI 对话中提出“改代码/改配置/改脚本/改模块”诉求（无论中文或英文），且目标修改路径命中上述受检范围，AI 在开始任何文件修改前，必须先执行：
uv run python scripts/validate_canonical.py --check-changes。 - bootstrap 例外：若
--check-changes失败原因为“当前仓库不存在任何projects/*/project.toml”，可进入 bootstrap 模式继续生成首个project.toml与对应代码/产物；生成后必须立刻恢复常规门禁并重新执行--check-changes。 - 若上述命令失败且输出包含
FRAMEWORK_VIOLATION，或“需求 -> framework 映射”无法成立，AI 必须拒绝继续修改命中门禁范围的文件，并明确提示“先由人修改 framework，再继续实现层变更”。 - 若上述命令失败但原因属于实现层漂移（示例：
static module boundary map mismatch、CORRESPONDENCE_VIOLATION、codegen_consistency），且该需求可在当前 framework 中完成显式映射，AI 应继续修改实现层文件（projects/**、src/project_runtime/**、scripts/**）以修复漂移；framework/**仍保持只读。 projects/<project_id>/project.toml是实现层配置入口；在映射成立前提下，AI 可以修改该文件以把 config/code 对齐到已存在的 framework 约束，无需额外等待人工先改 framework。- AI 完成命中门禁范围的修改后，提交前必须再次执行：
uv run python scripts/validate_canonical.py --check-changes，并确保未引入新的 framework 语义越权。 - 该守卫属于“对话级自动触发”，不得要求用户手工复制临时
project.toml才触发。
对话意图到框架映射门禁（强制）
- 用户提出“新增/调整功能”时，AI 必须先完成“需求 -> framework 显式映射”再动实现层文件。
- 映射结果至少应包含：
module_id、对应boundary_id（或明确的 Rule/Base 约束）、以及落点exact.*路径。 - 若 AI 不能给出上述映射，或映射结果无法在当前 framework 中找到对应约束，AI 必须拒绝修改命中门禁范围的实现文件，并提示“该需求尚未进入 framework，请先由人修改 framework”。
- 在“映射失败”场景中，AI 不得通过“直接改 config 或 code”规避框架前置；不得创建平行真相路径。
framework/**是人类作者源；AI 对 framework 绝对只读。不得因为“用户点名某个 framework 文件”“只是试写一版”“先改再恢复”或“先给人看效果”而直接落盘 framework 文件。- AI 需要给出候选稿时，必须按语义选择落点：正式 framework 作者稿候选写到
framework_drafts/** - AI 不得直接执行
framework_drafts/** -> framework/**的发布动作；正式 framework 作者源落盘必须由人类确认并单独触发。
工程执行规范（强制）
1. 环境与依赖
- 必须使用
uv管理 Python 环境与依赖。 - 新增依赖必须使用
uv add <package>。 - 必须提交
pyproject.toml与uv.lock。
2. 运行与验证命令
- 运行主程序：
uv run python src/main.py - 静态类型检查：
uv run mypy - 硬编码守卫：
uv run pytest -q tests/test_no_hardcode_guard.py - 项目生成产物物化：
uv run python scripts/materialize_project.py - canonical 验证：
uv run python scripts/validate_canonical.py - 变更传导验证：
uv run python scripts/validate_canonical.py --check-changes - 公开发布与版本说明标准：
specs/code/发布与版本说明标准.md
3. 变更执行要求
- 修改标准或代码后，必须执行对应验证命令。
- Python 代码变更后，必须通过静态类型检查（
uv run mypy）。 - 触及
src/project_runtime/**、src/frontend_kernel/**、tools/vscode/shelf-ai/**或scripts/**时，必须执行硬编码守卫测试（uv run pytest -q tests/test_no_hardcode_guard.py）。 - 项目行为变更必须先改
framework/*.md或projects/<project_id>/project.toml，再执行uv run python scripts/materialize_project.py生成产物；禁止直接手改projects/<project_id>/generated/*。 - 禁止在仓库规范文档中引入
pip install作为标准流程。 - 必须启用仓库
pre-pushhook：bash scripts/install_git_hooks.sh。 - 若 canonical 验证不通过，禁止推送。
- 公开发布时，必须提供符合规范的双语版本说明与正式安装产物。
- 公开发布版本说明必须按“上一版本 tag -> 当前版本 tag”的完整提交区间汇总；禁止只按单次会话/单次对话编写发布说明（示例：
shelf-ai-v0.1.20..shelf-ai-v0.1.21）。
4. 规范优先级
- 规范总纲：
specs/规范总纲与树形结构.md - 框架设计标准：
specs/框架设计核心标准.md - 领域标准：按项目选中的 framework 根模块（示例：
framework/backend/L1-M1-检索流程模块.md） - 代码规范目录：
specs/code/ - Python 实现质量（静态类型）：
specs/code/Python实现质量标准.md
4.1 按语言读取标准（强制）
- 修改
.py文件前，必须阅读specs/code/Python实现质量标准.md。 - 修改
.ts文件前，必须阅读specs/code/TypeScript实现质量标准.md。 - 修改
.tsx文件前，必须同时阅读specs/code/TypeScript实现质量标准.md与specs/code/HTML与模板实现质量标准.md。 - 修改
.js/.mjs/.cjs文件前，必须阅读specs/code/JavaScript实现质量标准.md。 - 修改
.jsx文件前，必须同时阅读specs/code/JavaScript实现质量标准.md与specs/code/HTML与模板实现质量标准.md。 - 修改
.html文件前，必须阅读specs/code/HTML与模板实现质量标准.md。 - 修改
.css/.scss/.less文件前，必须阅读specs/code/前端样式实现质量标准.md。 - 多语言或混合语法文件必须同时满足对应标准；冲突时按更严格者执行。
- 语言到标准的机器可读索引为
specs/code/代码语言标准索引.toml；新增语言或文件类型时，必须先更新该索引与本节，再允许 AI 或人工按新语言写代码。
4.2 Shelf AI 契约与技术方案同步（强制）
- 只要任务涉及
tools/vscode/shelf-ai/**，无论是代码、配置、README、release notes、tree 视图脚本，还是与插件直接耦合的导航 / evidence / validation 路径，都必须先阅读tools/vscode/shelf-ai/插件设计与实现契约.md。 - Shelf AI 插件的后续设计与实现，默认以
tools/vscode/shelf-ai/插件设计与实现契约.md作为一线约束；README、零散注释、临时讨论或历史实现都不得覆盖该文档。 - 凡是插件相关实现发生变化，必须同步审查该契约文档是否需要更新；若实现语义已变而契约文档未更新，则该实现视为未完成。
- 修改以下文件时，默认应同时检查该契约文档是否需要更新：
tools/vscode/shelf-ai/extension.jstools/vscode/shelf-ai/guarding.jstools/vscode/shelf-ai/framework_navigation.jstools/vscode/shelf-ai/framework_completion.jstools/vscode/shelf-ai/framework_grammar.jstools/vscode/shelf-ai/evidence_tree.jstools/vscode/shelf-ai/validation_runtime.jstools/vscode/shelf-ai/package.jsontools/vscode/shelf-ai/README.mdtools/vscode/shelf-ai/release-notes/*- 与插件直接耦合的 tree / validation / materialize 脚本
- Shelf AI 的 framework 作者语法必须采用“单 grammar 真相源”实现：
lint、snippet/completion、highlight三者只能共同消费同一套 grammar 定义，禁止各自维护分叉规则。 tools/vscode/shelf-ai/插件设计与实现契约.md第 13 章《仓库技术方案（当前讨论基线）》是本仓库技术方案讨论与落地的固定入口。- 以后凡是修改本仓库代码（不限语言、不限目录），提交前都必须审查第 13 章是否需要更新。
- 若实现语义、模块边界、交互行为、依赖策略、验证门槛任一发生变化，必须同步更新第 13 章；未更新视为任务未完成。
- 若本次代码变更不影响第 13 章，也必须在提交说明或评审说明中显式声明“技术方案章节无变更”。