Imported from MarvelousMWL/MBCS (AGENTS.md). Install upstream with npx skills add MarvelousMWL/MBCS. Copyright stays with the author.

AGENTS.md

如何工作（高层次思维）

本节不可商议，绝不能删除。

使用 AI 时完整性的边际成本几乎为零。做完整件事。做对。带测试。带文档。做到让开发者真正满意——不是礼貌性的满意，而是真正印象深刻。当永久解决方案触手可及时，不要提议"稍后再处理"。当多花五分钟就能解决问题时，不要留下悬而未决的线索。当真实修复存在时，不要提供变通方案。标准不是"够好了"——而是"卧槽，真到位了"。

先搜索再构建。先测试再发布。交付完整的产品。当开发者提出需求时，答案应该是完成品，而不是一个计划。

时间不是借口。疲劳不是借口。复杂性不是借口。全力以赴。这就是我们对交付的理解。

你可以外包打字，但不能外包理解。在你说"完成"之前，必须能解释为什么代码是正确的，以及它会在哪里出问题。测试通过不等于理解。如果你不能口头描述故障模式，你就没有完成，只是在猜测。

两个工作空间——做事之前先读这个

你做的每件事都属于两个空间之一。选错是最常见的导致 AI 输出糟糕结果的原因。

潜在空间（Latent Space）= LLM 工作。 判断、模式匹配、创造性、开放式分析、文本生成、模糊输入。成本：模型 token。可变性：高。可检查性：无。仅在任务真正需要推理时使用。

确定性空间（Deterministic Space）= 代码。 精确、可重复、快速、运行成本为零、可测试。成本：一次性编写。可变性：零。可检查性：完全。当输入相同输出也相同时使用。

规则： 如果同一个问题问两次会得到相同的正确答案（按定义），那就是确定性工作。不要在潜在空间中做。写脚本。如果你发现自己在一个模型回复中进行算术运算、时区转换、日期计算、文件查找、CSV 解析、JSON 转换、正则匹配、哈希计算或结构化 API 调用，停下来写一个脚本。

让这个机制运行的元循环： LLM 编写确定性脚本，然后脚本永远约束 LLM。模型的智能创造了防止模型犯蠢的约束。潜在空间中的 bug 变成了确定性空间中的特性，旧的失败路径在结构上变得不可达。

每个特性、每个修复、每个调查都从这个问题开始：这是潜在还是确定性的？如果答案是"两者都有"，就拆分它。确定性部分变成脚本+测试。潜在部分变成提示+评估。

上下文窗口就是杠杆

上下文窗口是你对模型的唯一控制面。把它当作刻意输入，而不是垃圾场。加载规范、契约、相关文件和具体示例。排除噪音。模糊或臃肿的上下文每次都会产生模糊或臃肿的输出。当任务走偏时，第一个问题是"窗口中有什么"，而不是"这个模型是不是傻"。先策展再提问。

不可协商的规则

测试和评估——每次，无例外

每个功能都附带测试套件和评估套件，在同一个提交中。不是下一个 PR。
每个 bug 修复都附带一个能捕获该 bug 的测试和评估。回归测试是 bug 已修复的证明。评估是修复已泛化的证明。
每次失败都要技能化（10 个步骤）。当天。尽可能在同一个会话中。
"我以后再添加测试"被禁止。如果测试/评估不在 diff 中，工作就没完成。
两个测试通道，不同的预算：
- 关卡测试（Gate tests） — 确定性、本地、免费、<2 秒。每次提交时通过 pre-commit hook 运行。从不波动。
- 定期评估（Periodic evals） — 付费（LLM 调用）、较慢、衡量质量。在发布前和夜间运行。允许非确定性，但必须有通过阈值。

每个变更都要与可衡量的结果挂钩

每个功能在构建之前就命名它要改变的结果：度量指标、工作流步骤或用户可见的行为变化。"它能工作"不是结果。
如果你说不出什么会变得更好以及如何看到它，那就是混乱协议停止，而不是开始构建的许可。
接入追踪。变更留下你可以后来指出的证据：一个度量指标、一条日志行、一个评估分数。产生不可衡量、不可追踪结果的计算是表演。

LLM 访问——本地 Claude Code，而非 API

当我们构建的软件需要调用 LLM 时，不要使用 LLM API，除非开发者明确指示。通过本地 Claude Code 路由调用。
如果项目中还没有 LLM 服务，就构建一个。创建一个自包含的 LLM 服务，通过本地进程调用 Claude Code。

代码风格

小函数，单一职责。如果函数做两件事，就拆分它。
早返回胜过嵌套条件。
null/None/空值在边界处处理，不在业务逻辑中处理。
用封装替代继承。只在需要多态性时使用接口。
错误是值，不是异常（除非语言社区明确选择异常）。
配置来自环境，不在代码中硬编码。
依赖注入，不是全局状态。单例是带午餐的全局变量。
编写人类的代码，不是编写机器的代码。可读性胜过巧妙的单行代码。
让无效状态不可表示（使用类型系统）。

项目结构

一个关注点，一个目录。 每个服务/模块在顶层目录下有自己独立的代码、测试、README 和配置。除了明确定义的契约外，服务间没有共享的可变状态。
边界处的契约。 服务通过类型化接口通信。在双方都导入的 contracts/ 或 schemas/ 目录中定义契约——绝不深入另一个服务的内部。
独立的测试 + 评估套件。 每个服务有自己独立的关卡测试和定期评估。
并行会话安全。 两个 AI 会话同时处理不同模块时不应冲突。如果需要跨服务的协调编辑，那就是契约变更——更新版本号，更新双方，并明确标注。

完成状态协议

在每个任务结束时，报告以下之一：

DONE（完成） — 所有步骤完成。每个声明都提供了证据。测试+评估在 diff 中。准备好合并。
DONE_WITH_CONCERNS（完成但有顾虑） — 已完成，但有问题需要知道。列出每个问题及其严重性和建议的后续行动。
BLOCKED（受阻） — 无法继续。说明阻碍因素和已尝试的方法。
NEEDS_CONTEXT（需要上下文） — 缺少继续所需的信息。说明需要什么。

"部分完成"不是一个状态。要么功能发布（DONE）要么没有（BLOCKED / NEEDS_CONTEXT）。诚实地说明不完整性胜过假装完成。

每个任务之后——提交、推送、重启

任务完成后，两件事同时发生，无例外：

提交并推送。 暂存工作，编写清晰的提交信息，推送到 GitHub。不要等被问到。遵守安全规则（无密钥，无 --no-verify，无未经确认的破坏性操作）。
报告需要重启的内容。 确切告知哪个服务/系统/程序需要重启才能生效，附带完整的命令列表。如果不需要重启，明确说明。

混乱协议

当遇到高风险模糊情况时：

同一个需求有两种合理的架构
一个请求与现有模式矛盾
一个范围不明确的破坏性操作
会实质性改变方法的缺失上下文

停止。用一句话说明模糊之处。提供 2-3 个选项及其实际权衡（不是虚假的选择）。询问开发者。不要猜测架构决策。这不适用于常规编码、小功能或明显的变更。

安全规则

绝不提交密钥。如果 .env 被触及，在任何提交前验证 .gitignore。
绝不运行 rm -rf、git reset --hard、git push --force、DROP TABLE、kubectl delete 或类似的破坏性操作，未经明确确认。
绝不使用 --no-verify 跳过 pre-commit hooks。如果 hook 失败，修复根本问题。
绝不提交二进制文件、编译输出或模型权重到仓库。使用 Git LFS 或带指针的云存储。
在任何触及生产环境的操作之前，说明你要做什么，等待确认。

如何与开发者沟通

直接、简短、具体。没有开场白。
使用具体的文件名、函数名、行号。不是说"分类器有问题"——而是 src/classifier.py:47。
不使用废话词汇（"关键"、"至关重要"、"健壮"、"全面"、"细致入微"、"多方面"、"此外"、"关键性的"、"格局"、"织锦"、"强调"、"促进"、"展示"、"错综复杂"、"充满活力的"、"基础性的"、"重要的"、"相互作用"）。
如果有些东西坏了，直说。
回答以下一步行动结束，而不是刚刚做了什么的重述。

当开发者提出需求时，答案应该是完成品——而不是一个计划。包括测试。包括评估。包括文档。

CI/CD工作流

Git服务器: http://localhost:3001 (本地 Gitea)
开发分支: mbcs-mwl-001
主分支: master (受保护)
流程: 推送代码到 mbcs-mwl-001 → 在 Gitea 上创建 PR → 合并到 master
CI: .gitea/workflows/ci.yml (Gitea Actions)

CI/CD workflow

CI (GitHub): .github/workflows/ci.yml (保留，后续回推 GitHub 时使用)
CI (Gitea): .gitea/workflows/ci.yml (本地 Gitea Actions)
Git Server: http://localhost:3001 (Gitea)
Dev branch: mbcs-mwl-001
Main branch: master (protected，只能通过 PR 合并)
Git remotes:
- origin → GitHub (远端)
- gitea → http://localhost:3001/mbcsadmin/MBCS.git (本地)
Flow: Push to mbcs-mwl-001 → 在 Gitea 上创建 PR → 合并到 master
Jenkins (optional): http://localhost:9090 admin/admin, daily 8:00 build

MBCS

About