# Contributing to dsh-csp-runtime

感谢你对 **dsh-csp-runtime**（Cognitive State Protocol v0.1）的贡献兴趣。

## 开发环境

- Node.js `>=22.19`（CI 矩阵覆盖 22.19 与 24）
- 包管理器：npm

```bash
npm install
npm run typecheck   # tsc 零错误
npm run lint        # eslint 零警告（禁止 any）
npm run test        # vitest 全绿，核心模块覆盖率 >= 80%
npm run build       # 编译到 lib/
```

## 设计约束（务必遵守）

1. **协议不可扩张**：CSP v0.1 状态模型由 `docs/CSP-SCHEMA.v0.1.json` 与 `docs/DESIGN.md §8` 冻结。
   任何字段/枚举变更需先更新设计文档并经架构师与用户确认，**不要**在实现阶段自行扩张。
2. **职责隔离**：CSP 只描述"思考状态"。不写 CDP（工具元数据）、不写 IntentGraph 执行器。
   可引用 `capability_id` 与 `trace_id`，但不重复定义。
3. **仅注册 `cspStore` 服务**：禁用 `cdpRegistry` / `universalAdapter` / `intentNetwork`。
4. **config 白名单**：仅 `sources`/`capture`/`persistence`/`handoff`/`interop`。
5. **依赖纯净**：必选 `@deepseek-ai/cordis` + `@deepseek-ai/dsh-tools`；
   可选 `@deepseek-ai/cdp-metadata` / `@deepseek-ai/intent-network`；严禁任何 `@modelcontextprotocol/*`。
6. **代码质量**：禁止 `any`（用 `unknown` + 类型守卫）；外部输入用 zod/v4 校验；
   文件 IO 仅 `node:fs/promises` + 路径白名单；捕获默认 opt-in、零开销；
   不强制 LLM 调用、不执行不可信代码（只序列化/校验）。

## 提交约定

- 分支：`feat/xxx`、`fix/xxx`、`docs/xxx`
- 提交信息清晰说明"为何"而非仅"做了什么"
- 确保 `prepublishOnly` 四步（typecheck/lint/test/build）通过

## 测试

新增/修改功能请同步补充 `tests/`，并维持核心模块（schema/store/handoff/interop）覆盖率 ≥ 80%。