Imported from sandersyao/dsh-credentials-mysql (
AGENTS.md). Install upstream withnpx skills add sandersyao/dsh-credentials-mysql. Copyright stays with the author.
AGENTS.md
本文件为开发本仓库的 Agent（或人工协作者）提供必须遵守的约定。读取后按此执行。
项目是什么
@sandersyao/dsh-credentials-mysql —— DeepSeek Harness（dsh）的 MySQL 凭据保险库提供方。它是 dsh-credentials 能力接缝的一个 Provider：以 Cordis 插件形式加载，注册为 ctx.credentials，把 refs 与 records 两空间的凭据持久化到 MySQL。
关键架构事实（先读文档，勿扫源码）
- 参考契约：
dsh-credentials的 README（Service API + 两键空间 + invariants）。 - 参考实现模式：
dsh-credentials-local—— 类继承CredentialProvider+static Config(schemastery) +[Service.init]初始化 + 实现全部抽象方法。 - 默认提供方在
dsh-basebundle 的cordis.patch.yml中以id: credentials挂载；本包 bundle 的 patch 停用默认credentials并插入本插件。 - 取值分层：继承进程环境(只读, 优先) → MySQL 受管存储(可写) → project/user
.env兜底。空存储值 = 不存在。 - 记录写路径：
modifyRecord用SELECT … FOR UPDATE+ 事务实现跨进程互斥（替代文件提供方的文件写锁）。
常用命令
pnpm install # 安装依赖（本地 store 在 .pnpm-store）
pnpm typecheck # 类型检查（strict）
pnpm lint / pnpm fmt # Biome 格式+lint
pnpm build # tsup 构建 → lib/
pnpm test # vitest run
pnpm test:coverage # 带覆盖率门禁（lines≥90）
pnpm smoke # 手动冒烟（先 build）
docker compose up -d # 启动本地 MySQL（env 取自 .env）代码风格约束（强制，违反即被打回）
- 类型声明（
interface/type/class）上方必须有多行 JSDoc/** ... */。 - 具名函数与方法上方必须有多行 JSDoc。
- 所有注释描述使用中文（标识符、代码、日志保持英文）。
- 数据表与字段必须有注释（DDL 内每列用
COMMENT '...'子句注明用途；表级COMMENT=只写表的一句话描述，不堆叠列注释）。 - 复杂/非显然逻辑：在实现上方补中文说明，解释「为什么」。
- 格式与 lint 由 Biome 统一（
biome check必须通过）。
安全基线（本项目红线）
- 连接凭据只来自环境变量/.env，绝不硬编码、绝不打印、绝不进日志。
- 全部 SQL 用参数化占位符
?；ref_name/rec_key绝不作 SQL 标识符拼接。 - 表前缀来自配置且校验
^[A-Za-z0-9_]+$；基名与 session-persistence 表不同，规避同库冲突。 - 配置
CREDENTIALS_ENCRYPTION_KEY时，ref 值与 record 敏感内容 AES-256-GCM 加密；未配置明文 + 启动告警。 - grant payload 双向
assertJsonValue（拒绝非有限数/循环/Date/bigint）。
测试要求
- 安全用例优先级最高；其次功能完整；再性能。
- 契约一致性套件必须覆盖
dsh-credentials的全部方法语义（空值=不存在、env 遮蔽、modifyRecord 互斥、grant JSON 往返、describe 不泄值）。 - 覆盖率门禁：
lines ≥ 90（为 v0.1.2-alpha.3 兼容打底）。
交接与文档
- 每个任务在
docs/tasks/T<id>/产出TASK_STATUS.md（markdown）+TASK.json（机器可读）。 - 技术债登记到
docs/TECH_DEBT.md+docs/TECH_DEBT.json。 - 任务队列总表：
docs/TASKS.json。