leanspec-development

LeanSpec 开发技能

LeanSpec 开发统一指南：涵盖编码、命令、发布、CI/CD 和运行器研究。

快速导航

目标	参考资料
强制规则与约定	RULES.md
变更日志格式与工作流	变更日志（下文）
i18n 文件位置与模式	I18N.md
Monorepo 结构与包	STRUCTURE.md
完整发布检查清单	PUBLISHING.md
npm 分发架构	NPM-DISTRIBUTION.md
开发版发布工作流	DEV-PUBLISHING.md
CI 工作流详情	CI-WORKFLOWS.md
gh CLI 命令参考	CI-COMMANDS.md
CI 故障排查	CI-TROUBLESHOOTING.md
运行器生态目录	runners-catalog.md

核心原则

1. 使用 pnpm — 切勿使用 npm 或 yarn
2. DRY — 提取共享逻辑，避免重复
3. 测试关键内容 — 测试业务逻辑和数据完整性，而非展示效果
4. 充分利用 Turborepo — 智能缓存（构建时间从 19s 降至 126ms）
5. i18n 是强制要求 — 所有面向用户的字符串都必须同时提供 en 和 zh-CN（参见 I18N.md）
6. 遵循 Rust 质量标准 — 所有代码都必须通过 cargo clippy -- -D warnings

---

命令

日常开发

pnpm install              # Install dependencies
pnpm dev                  # Start web UI + Rust HTTP server
pnpm dev:watch            # Same + auto-rebuild Rust on changes
pnpm dev:web              # Start web UI only
pnpm dev:desktop          # Start desktop app
pnpm build                # Build all TS packages
pnpm build:rust           # Build Rust (debug)
pnpm build:rust:release   # Build Rust (release)
pnpm typecheck            # ← NEVER SKIP before marking work complete
pnpm test                 # Run all tests
pnpm test:watch           # Watch mode
pnpm test:coverage        # With coverage
pnpm test:rust            # Rust tests only
pnpm format               # Format all code
pnpm cli                  # Run LeanSpec CLI

验证

pnpm pre-push             # Quick: typecheck + clippy
pnpm pre-release          # Full: build + typecheck + test + lint

⚠️ 标记工作完成前，务必运行 pnpm typecheck。

Rust

pnpm build:rust           # Debug build
pnpm build:rust:release   # Release build
pnpm check:rust           # Quick check without building
pnpm lint:rust            # Clippy with warnings as errors
pnpm format:rust          # Format Rust code
pnpm format:rust:check    # Check Rust formatting

# Low-level
cargo build --manifest-path rust/Cargo.toml
node scripts/copy-rust-binaries.mjs --debug

文档

pnpm docs:dev             # Start docs dev server
pnpm docs:build           # Build docs site

桌面端

pnpm dev:desktop          # Start desktop app in dev mode
cd packages/desktop
pnpm bundle:linux         # Debian package
pnpm bundle:macos         # DMG
pnpm bundle:windows       # NSIS installer

---

关键规则

由钩子或 CI 强制执行的规则：

1. 浅色/深色主题 — 所有 UI 都必须支持这两种主题
2. i18n — 同时更新 en 和 zh-CN → I18N.md ⚠️ 经常被遗忘
3. 回归测试 — 修复 Bug 必须包含先失败、后通过的测试
4. Rust 质量 — 必须通过 cargo clippy -- -D warnings
5. Rust 参数结构体 — 参数超过 7 个的函数必须使用参数结构体（由 clippy.toml 强制执行）
6. 使用 shadcn/ui — 禁止使用原生 HTML 表单元素
7. cursor-pointer — 所有可点击项都必须使用 cursor-pointer

完整要求请参见 RULES.md。

---

发布与版本

生产版本发布（推荐）

# 1. Update version (root only)
npm version patch  # or minor/major

# 2. Sync all packages
pnpm sync-versions

# 3. Validate everything
pnpm pre-release

# 4. Commit and push with tags
git add .
git commit -m "chore: release vX.X.X"
git push --follow-tags

# 5. Create GitHub Release (triggers publish workflow)
gh release create vX.X.X --title "vX.X.X" --notes "Release notes here"

开发版发布

# Publish dev version via GitHub Actions
gh workflow run publish.yml --field dev=true

# Dry run (validates without publishing)
gh workflow run publish.yml --field dev=true --field dry_run=true

# Install and test
npm install -g lean-spec@dev
lean-spec --version

版本管理

• 根目录的 package.json 是版本号的唯一事实来源
• pnpm sync-versions 会将版本号同步到所有包（包括 Rust crate）
• CI 会自动验证版本号是否一致
• 切勿手动编辑包的版本号 — 使用 npm version + pnpm sync-versions

分发架构

LeanSpec 使用可选依赖来分发特定平台的 Rust 二进制文件：

类型	包
主包（已发布）	lean-spec、@leanspec/mcp、@leanspec/ui
平台包（已发布）	@leanspec/cli-{platform}、@leanspec/mcp-{platform}（各 5 个平台）
内部包（未发布）	@leanspec/desktop、@leanspec/ui-components

⚠️ 必须先发布平台包，再发布主包。 CI 工作流会自动处理这一流程。

详情请参见 PUBLISHING.md 和 NPM-DISTRIBUTION.md。

---

变更日志

按照 Keep a Changelog 格式和 语义化版本 更新 CHANGELOG.md。

查找变更

# Commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Files changed since last release
git diff $(git describe --tags --abbrev=0)..HEAD --stat

条目格式

仅包含已发布/已实现的变更 — 不包含计划中的规范、草稿或进行中的工作。

在 ## [Unreleased] 下，使用以下类别：新增、变更、修复、弃用、移除、安全、技术。

- **Feature Name** ([spec 123](https://web.lean-spec.dev/specs/123)) - Brief description
  - Sub-bullet with implementation details

写作风格

1. 加粗功能名称，后接描述
2. 适用时，链接相关规范
3. 使用现在时——“添加对……的支持”，而不是“已添加”
4. 明确具体——包含命令名称、标志名称和组件名称
5. 将相关变更归为一条，并使用子项
6. 使用 Breaking: 前缀标注破坏性变更

创建发布版本

1. 将 [Unreleased] 中的条目移至新版本：## [X.Y.Z] - YYYY-MM-DD
2. 在底部添加发布链接：[X.Y.Z]: https://github.com/codervisor/lean-spec/releases/tag/vX.Y.Z

---

CI/CD（GitHub Actions）

所有工作流交互都使用 gh CLI。触发新运行前先检查状态；轮询间隔至少为 30 秒。

可用工作流

工作流	文件	触发条件	用途
CI	ci.yml	推送、向 main 提交 PR	构建、测试、代码检查（Node.js + Rust）
发布	publish.yml	发布、手动触发	发布到 npm（所有平台）
桌面构建	desktop-build.yml	推送、PR、手动触发	构建 Tauri 桌面应用
Copilot 设置	copilot-setup-steps.yml	推送、PR、手动触发	为 Copilot Agent 设置环境

快速参考

# Check status
gh run list --limit 10
gh run list --workflow ci.yml --limit 5
gh run view <run-id>
gh run watch <run-id>

# Trigger
gh workflow run ci.yml
gh workflow run publish.yml --field dev=true

# Debug failures
gh run view <run-id> --log-failed
gh run rerun <run-id> --failed

# Artifacts
gh run download <run-id>
gh run download <run-id> --name ui-dist

详情请参阅 CI-WORKFLOWS.md、CI-COMMANDS.md 和 CI-TROUBLESHOOTING.md。

---

Runner 调研

调研 AI Agent Runner，随着生态系统的发展，及时更新 LeanSpec 的 Runner 注册表。

工作流

1. 读取当前状态：rust/leanspec-core/src/sessions/runner.rs（RunnerRegistry::builtins()）
2. 阅读目录：runners-catalog.md
3. 通过 web_search 调研：配置格式变更、CLI 变更、新环境变量、新功能、弃用项、新 Runner
4. 对比并找出差距：将调研结果与注册表交叉核对
5. 报告：细微更新 → 直接更新目录；重大变更 → 创建规范

Runner 级别

1. 第 1 级（高优先级）：Claude Code、Copilot、Cursor、Windsurf、Codex、Gemini
2. 第 2 级（中优先级）：Kiro、Amp、Aider、Goose、Continue、Roo Code
3. 第 3 级（持续关注）：Droid、Kimi、Qodo、Trae、Qwen Code、OpenHands、Crush、CodeBuddy、Kilo、Augment

关键源文件

文件	用途
rust/leanspec-core/src/sessions/runner.rs	Runner 注册表及检测配置
schemas/runners.json	自定义 Runner 配置的 JSON Schema
packages/cli/templates/_shared/agents-components/	AGENTS.md 模板组件