dingtalk-workspace: Instructions file for Claude Code

CLAUDE.md — dingtalk-workspace-mcp 项目指令

本文件是项目级 agent 指令。优先级高于 ~/.claude/CLAUDE.md，但不覆盖用户显式请求。

---

这是什么项目

核心目标：交付一个 dws-driven 动态全覆盖的钉钉 MCP server。和现存 5+ 个 DingTalk MCP（手写固定 tool 子集）形成差异化——dws 升级新增能力时，本项目不改一行代码即自动暴露。

适用对象：任何 MCP host（Claude Desktop / Cursor / Codex / 其他）。host-agnostic 是不可妥协的红线。

仓库历史：早期试过"通用 MCP + 单一 host 专属扩展"双轨设计，扩展代码已归档至 legacy/（封档点 git tag milestone-v0.2）。npm 包名 @sputnicyoji/dingtalk-workspace-mcp 是项目本体。

不是：

• 不是 DingTalk 官方 SDK 再造
• 不是把 dws 用 Rust/Go/Python 重写一遍
• 不是通用 IM 接入框架（不考虑飞书/Slack/Teams）
• 不是任何 host 的专用集成方案（早期方向，已废弃，相关代码归档在 legacy/）

上游依赖：

• dws CLI（Go，用户本机自装）
• 钉钉官方走 "CLI + MCP 广场" 路径，不会自己出官方 MCP（这是本项目长期价值的护城河）

---

目录约定

dingtalk-workspace/
├── CLAUDE.md                 # 本文件
├── docs/
│   ├── ARCHITECTURE.md       # 架构 + 设计决策
│   ├── ROADMAP.md            # 版本节奏
│   ├── COMPARISON.md         # vs 其他 DingTalk MCP 对比
│   └── decisions/            # ADR
├── packages/
│   └── dingtalk-workspace-mcp/   # 唯一活跃 package
│       ├── src/
│       ├── dist/                 # tsc 输出，不进 git
│       ├── package.json
│       └── README.md
├── legacy/                   # 已归档代码与文档（不再迭代）
│   ├── hermes-extensions/    # 早期 host 专属扩展（v0.2 milestone 封档）
│   └── docs/                 # 配套调研文档
├── ref-git/                  # 参考仓库（dws 等），.gitignore 排除
└── LICENSE

禁止：

• 在 packages/dingtalk-workspace-mcp/ 中写任何业务逻辑（身份解析、报告模板、告警规则）
• 主包反向依赖 legacy/
• 给 legacy/ 加新代码或新模块（只接受 bug 修复）
• 任何形式的 host 假设（代码路径里出现 host 名字就是 red flag）

---

技术栈约束

模块	语言/运行时	理由
dingtalk-workspace-mcp	TypeScript + Node.js ≥20	对齐 npx -y 发行约定，MCP SDK 最成熟
legacy/	Python（冻结）	历史选型，保留原状不动

不用：

• Rust（性能优势用不上，发行方式和 npx 生态冲突）
• Go（除非 schema 解析硬瓶颈才考虑重写）

---

编码风格

TypeScript（主包）

• strict: true，不开 any 逃生舱
• 不写 class，纯函数 + 闭包状态
• 不引入 execa/cross-spawn，用 Node 原生 child_process
• 错误用 Result<T, E> 风格（{ ok: true, value } | { ok: false, error }），不滥用 throw
• 所有和 dws 的交互走 src/dispatch.ts 唯一入口