Skip to content

Commit d6aa6fa

Browse files
HellowVirgilHellowVirgil
committed
docs: 为 Claude 添加项目文档和发布指南
添加 CLAUDE.md 项目概述文档，包含架构说明和开发命令 添加 release.md 正式版本发布指南 添加 release-snapshot.md 测试版本发布指南
1 parent d0fa079 commit d6aa6fa

File tree

3 files changed

+265
-0
lines changed

3 files changed

+265
-0
lines changed

‎.claude/commands/release-snapshot.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# 发布 Libro 测试版本
2+
3+
发布 libro 的测试版本（snapshot release）。
4+
5+
## 执行步骤
6+
7+
请按顺序执行以下命令：
8+
9+
1. **生成 changeset 文件**（需要用户在终端中交互操作）
10+
11+
```bash
12+
pnpm run changeset
13+
```
14+
15+
这会启动交互式界面，让用户选择:
16+
- 要发布的包（按空格选择，回车确认）
17+
- 版本变更类型（major/minor/patch）
18+
- 变更说明
19+
20+
**注意**：此步骤需要用户手动在终端中完成交互。
21+
22+
2. **构建项目**
23+
24+
```bash
25+
pnpm run build
26+
```
27+
28+
构建所有包，确保代码可以正常编译。
29+
30+
3. **发布 snapshot 版本**
31+
32+
```bash
33+
sh ./scripts/release-snapshot.sh
34+
```
35+
36+
此脚本会执行：
37+
- `changeset version --snapshot` - 更新版本号
38+
- `changeset publish --tag snapshot` - 发布到 npm 的 snapshot tag
39+
40+
4. **生成 resolutions 配置**
41+
42+
发布成功后，执行以下命令获取最新 snapshot 版本号：
43+
44+
```bash
45+
npm view @difizen/libro-core versions --json | jq -r '.[] | select(contains("snapshot"))' | tail -1
46+
```
47+
48+
使用获取到的版本号（如 `0.0.0-snapshot-20260203035545`），生成如下格式的 resolutions：
49+
50+
```json
51+
"resolutions": {
52+
"@difizen/libro-ai-native": "<snapshot-version>",
53+
"@difizen/libro-app": "<snapshot-version>",
54+
"@difizen/libro-code-cell": "<snapshot-version>",
55+
"@difizen/libro-code-editor": "<snapshot-version>",
56+
"@difizen/libro-codemirror": "<snapshot-version>",
57+
"@difizen/libro-cofine-editor": "<snapshot-version>",
58+
"@difizen/libro-cofine-editor-contribution": "<snapshot-version>",
59+
"@difizen/libro-cofine-editor-core": "<snapshot-version>",
60+
"@difizen/libro-cofine-textmate": "<snapshot-version>",
61+
"@difizen/libro-common": "<snapshot-version>",
62+
"@difizen/libro-core": "<snapshot-version>",
63+
"@difizen/libro-jupyter": "<snapshot-version>",
64+
"@difizen/libro-kernel": "<snapshot-version>",
65+
"@difizen/libro-l10n": "<snapshot-version>",
66+
"@difizen/libro-lab": "<snapshot-version>",
67+
"@difizen/libro-language-client": "<snapshot-version>",
68+
"@difizen/libro-lsp": "<snapshot-version>",
69+
"@difizen/libro-markdown": "<snapshot-version>",
70+
"@difizen/libro-markdown-cell": "<snapshot-version>",
71+
"@difizen/libro-output": "<snapshot-version>",
72+
"@difizen/libro-prompt-cell": "<snapshot-version>",
73+
"@difizen/libro-raw-cell": "<snapshot-version>",
74+
"@difizen/libro-rendermime": "<snapshot-version>",
75+
"@difizen/libro-search": "<snapshot-version>",
76+
"@difizen/libro-search-code-cell": "<snapshot-version>",
77+
"@difizen/libro-shared-model": "<snapshot-version>",
78+
"@difizen/libro-sql-cell": "<snapshot-version>",
79+
"@difizen/libro-terminal": "<snapshot-version>",
80+
"@difizen/libro-toc": "<snapshot-version>",
81+
"@difizen/libro-virtualized": "<snapshot-version>",
82+
"@difizen/libro-widget": "<snapshot-version>"
83+
}
84+
```
85+
86+
## 注意事项
87+
88+
- 确保在执行前工作目录是干净的（没有未提交的更改会影响发布）
89+
- `pnpm run changeset` 需要用户在终端中交互操作，无法自动完成
90+
- 如果构建失败，不要执行发布脚本
91+
- 发布成功后，告知用户发布的版本号并提供完整的 resolutions 配置

‎.claude/commands/release.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# 发布 Libro 正式版本
2+
3+
发布 libro 的正式版本（formal release）。
4+
5+
## 执行步骤
6+
7+
请按顺序执行以下步骤：
8+
9+
1. **生成 changeset 文件**（需要用户在终端中交互操作）
10+
11+
```bash
12+
pnpm run changeset
13+
```
14+
15+
这会启动交互式界面，让用户选择:
16+
- 要发布的包（按空格选择，回车确认）
17+
- 版本变更类型（major/minor/patch）
18+
- 变更说明
19+
20+
**注意**：此步骤需要用户手动在终端中完成交互。
21+
22+
2. **构建项目**
23+
24+
```bash
25+
pnpm run build
26+
```
27+
28+
构建所有包，确保代码可以正常编译。
29+
30+
3. **更新版本号**
31+
32+
```bash
33+
pnpm changeset version
34+
```
35+
36+
此命令会根据 changeset 文件更新所有包的版本号，并生成/更新 CHANGELOG.md 文件。
37+
38+
4. **发布到 npm**
39+
40+
```bash
41+
pnpm changeset publish
42+
```
43+
44+
发布所有包到 npm（默认使用 `latest` tag）。
45+
46+
5. **输出发布结果**
47+
48+
发布成功后，告知用户发布的版本号。
49+
50+
## 注意事项
51+
52+
- 确保在执行前工作目录是干净的（没有未提交的更改会影响发布）
53+
- 如果构建失败，不要继续执行后续步骤
54+
- 正式版本发布后，需要将 changeset 文件和版本更新提交到 git
55+
- 发布成功后，通常需要创建 git tag 并推送到远程仓库

‎CLAUDE.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Libro is a JavaScript + Python hybrid monorepo providing a Notebook product solution with AI capabilities. It supports kernel-level extensibility and defines workflows for large models.
8+
9+
## Development Commands
10+
11+
```bash
12+
# Initial setup (installs dependencies and builds packages)
13+
pnpm bootstrap
14+
15+
# Start development server (docs/demo site)
16+
pnpm run docs
17+
18+
# Build all packages
19+
pnpm run build
20+
21+
# Lint code
22+
pnpm run lint
23+
24+
# Run all tests
25+
pnpm run test
26+
27+
# Run tests for a specific package
28+
pnpm run test:jest --filter=@difizen/libro-core
29+
30+
# Type check
31+
pnpm run tsc
32+
33+
# Create changeset for version management
34+
pnpm run changeset
35+
36+
# Run CI checks (lint, typecheck, coverage)
37+
pnpm run ci:check
38+
```
39+
40+
## Architecture
41+
42+
### Dependency Injection Framework
43+
44+
Libro uses `@difizen/mana-app` for dependency injection. Core patterns:
45+
46+
- **ManaModule**: Modules are created using `ManaModule.create().register(...).dependOn(...)`
47+
- **@singleton / @transient**: Class decorators for DI scope
48+
- **@inject**: Property/constructor injection
49+
- **@prop()**: Reactive properties with MobX-like behavior
50+
- **Contributions**: Use `.contribution(Token)` to register providers, then inject `@inject(Token)` to get all contributions
51+
52+
### Core Package Structure (`@difizen/libro-core`)
53+
54+
- **LibroModule**: Main module that registers core services and depends on sub-modules
55+
- **LibroService**: Manages notebook views/models, tracks active/focus state, emits events
56+
- **LibroModel**: Notebook model containing cells and metadata
57+
- **LibroView**: Notebook view component
58+
- **LibroCellModule**: Cell system with `CellViewContribution` and `CellModelContribution` for registering cell types
59+
60+
### Cell System
61+
62+
Cells follow a contribution pattern. To add a new cell type:
63+
64+
1. Create `CellViewContribution` - provides the view component
65+
2. Create `CellModelContribution` - provides factory for the model
66+
3. Register both in your module
67+
68+
Existing cell types: `code-cell`, `markdown-cell`, `prompt-cell`, `sql-cell`, `raw-cell`
69+
70+
### Kernel Architecture (`@difizen/libro-kernel`)
71+
72+
- **IKernelConnection**: Interface for kernel communication
73+
- **ExecutableNotebookModel**: Extends NotebookModel with kernel connection support
74+
- Kernel connection is managed per notebook instance
75+
76+
### Key Packages
77+
78+
| Package | Purpose |
79+
| ----------------------- | ------------------------------------------------------ |
80+
| `libro-core` | Core notebook functionality, model/view, cell system |
81+
| `libro-kernel` | Kernel connection management |
82+
| `libro-jupyter` | Jupyter protocol implementation, integrates cell types |
83+
| `libro-lab` | Full lab application combining all features |
84+
| `libro-ai-native` | AI capabilities (completion, chat, error fixing) |
85+
| `libro-codemirror` | CodeMirror editor integration |
86+
| `libro-cofine-editor-*` | Advanced editor features (LSP, textmate) |
87+
| `libro-rendermime` | MIME type rendering for outputs |
88+
| `libro-output` | Output display components |
89+
90+
### Build System
91+
92+
- **pnpm** with workspaces for monorepo management
93+
- **nx** for task orchestration with caching
94+
- **father** for building individual packages (ESM output to `es/`)
95+
96+
### Version Management
97+
98+
- Uses **changesets** for version management
99+
- All `@difizen/*` packages are linked together (same version)
100+
- Run `pnpm run changeset` to create version changes
101+
102+
## Release Process
103+
104+
1. Create changeset: `pnpm run changeset` (or auto-generate for snapshots)
105+
2. Build: `pnpm run build`
106+
3. For snapshot release: `sh ./scripts/release-snapshot.sh`
107+
108+
## Commit Convention
109+
110+
Follow Angular commit guidelines:
111+
112+
- `feat(scope): description` - new feature
113+
- `fix(scope): description` - bug fix
114+
- `chore(scope): description` - maintenance
115+
116+
## Requirements
117+
118+
- Node.js 20.x
119+
- pnpm 8.15.6

0 commit comments

Comments
 (0)